feat(diff): add HTML formatter, side-by-side mode, analyzers, and security scoring

[unclesp1d3r]

Summary

• Formatter interface: Unified all formatters behind a shared Formatter interface with New() and NewWithMode() factory functions, replacing the switch statement in outputDiffResult()
• HTML formatter: Self-contained HTML report output (--format html) using markdown-to-HTML conversion via goldmark, with embedded CSS, dark/light theme, collapsible sections, security badges, and print-friendly styles — fully offline, no CDN
• Side-by-side display mode: Two-column terminal layout (--mode side-by-side) using golang.org/x/term for width detection, with automatic fallback to unified format on narrow terminals (<80 cols)
• Semantic analyzers: New internal/diff/analyzers/ package with IP normalization (handles leading-zero octets), whitespace/port/protocol/path normalization (--normalize), and rule reorder detection (--detect-order)
• Security impact scoring engine: New internal/diff/security/ package with pattern-based scoring (10 built-in patterns covering firewall, system, NAT, users, interfaces), aggregate risk summaries, and automatic augmentation of changes without existing security impact
• Golden snapshot tests: Comprehensive goldie-based snapshot tests for HTML, Markdown, and JSON formatters with 3 scenarios each (no changes, single section, multi-section with security)
• CLI wiring: New flags --format html, --mode unified|side-by-side, --normalize, --detect-order with validation, shell completions, and updated help text

New packages

• internal/diff/formatters/ — Formatter interface, factory, HTML/side-by-side formatters
• internal/diff/analyzers/ — Normalizer, OrderDetector
• internal/diff/security/ — Scorer, Patterns, RiskSummary

Stats

• 35 files changed, +2863 / -157 lines
• 9 golden snapshot files for formatter regression testing
• 0 lint issues, all tests pass

Test Plan

• just ci-check passes (lint + all tests)
• Golden snapshot tests for HTML, Markdown, and JSON formatters
• Manual: opndossier diff old.xml new.xml -f html -o report.html produces valid self-contained HTML
• Manual: opndossier diff old.xml new.xml -m side-by-side renders two-column layout
• Manual: opndossier diff old.xml new.xml --normalize --detect-order reduces noise
• Manual: Security badges appear in all output formats (terminal, markdown, json, html)
• Verify narrow terminal (<80 cols) falls back to unified mode

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• New Features

  • Added HTML output format for configuration diff reports
  • Added side-by-side display mode for terminal diffs
  • Added configuration value normalization (IP addresses, ports, protocols, paths) to reduce cosmetic differences
  • Added firewall rule reorder detection with new display option
  • Enhanced security impact analysis with pattern-based scoring across firewall rules, system settings, and network configurations

• Documentation

  • Updated help text and examples to showcase new output formats and normalization options

Walkthrough

Adds HTML output and a side‑by‑side terminal formatter, a formatter factory, normalization and reorder-detection analyzers, pattern-based security scoring with RiskSummary, engine wiring to apply normalization/reorder detection/scoring, and extensive formatter/analyzer/golden tests and CLI flags.

Changes

Cohort / File(s)	Summary
CLI / Command cmd/diff.go	Adds html format, -m/--mode (unified
Formatter Factory & Types internal/diff/formatters/formatter.go, internal/diff/formatters/formatter_test.go	Introduces Formatter interface, format constants (terminal,markdown,json,html), mode constants, and factory New/NewWithMode.
HTML Formatter & Tests internal/diff/formatters/html.go, internal/diff/formatters/html_test.go	New HTMLFormatter that renders Markdown→HTML and emits a self-contained HTML document; tests validate structure, badges, and self-contained output.
Terminal Side‑by‑Side & Tests internal/diff/formatters/terminal_sidebyside.go, .../terminal_sidebyside_test.go	Adds SideBySideFormatter with width detection, unified fallback, truncation/padding, two-column rendering and security badge support; tests cover layout, truncation, and badge rendering.
Markdown/Terminal Formatters internal/diff/formatters/markdown.go	Emits Reordered summary count and symbol mapping for reordered changes; uses scorer-friendly security labels.
Formatter Golden Tests & Fixtures internal/diff/formatters/golden_test.go, internal/diff/formatters/testdata/golden/*	Golden-file tests added for HTML/Markdown/JSON outputs with deterministic builders and fixtures.
Normalizer Analyzer & Tests internal/diff/analyzers/normalizer.go, .../normalizer_test.go	New Normalizer with methods for IP, whitespace, port, protocol, and path normalization; comprehensive unit tests.
Order Detector & Tests internal/diff/analyzers/order_detector.go, .../order_detector_test.go	New OrderDetector detecting reorders between ID lists; tests for various reorder scenarios.
Security Patterns & Scoring internal/diff/security/patterns.go, internal/diff/security/scorer.go, internal/diff/security/risk.go, ..._test.go	Adds Pattern model and DefaultPatterns, Scorer with Score/ScoreAll, RiskSummary/RiskItem model and aggregation logic; tests validate matching and scoring.
Engine Integration & Tests internal/diff/engine.go, internal/diff/engine_test.go	Wires scorer, normalizer, orderDetector into Engine; applies normalization, augments SecurityImpact via patterns, detects firewall reorders, computes RiskSummary; tests for normalization, reorder detection, and risk summary.
Core Diff Types & Tests internal/diff/types.go, internal/diff/types_test.go	Adds ChangeReordered, Summary.Reordered, Result.RiskSummary, NewResult, Options.Mode/Normalize/DetectOrder, ChangesBySection, HasChanges, and case-insensitive section matching.
Analyzer Performance internal/diff/analyzer.go	Replaced O(n) slice lookups with O(1) set lookups and capacity tuning for interface and DHCP comparisons.
Processor Markdown Builder internal/processor/report.go	Refactored Markdown emission to a fluent/chained builder style and consolidated section rendering.
Markdown Rendering internal/markdown/formatters.go	Enables Goldmark table extension and permits raw HTML in renderer (html.WithUnsafe).
Misc / Manifest / Docs go.mod, internal/audit/plugin.go, LICENSE, AGENTS.md	Promotes golang.org/x/term to direct dependency; minor comment/license/agent docs updates.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as Diff CLI
    participant Engine as Diff Engine
    participant Normal as Normalizer
    participant OrderDet as OrderDetector
    participant Scorer as Security Scorer
    participant Factory as Formatter Factory
    participant Formatter as Concrete Formatter
    participant Writer as Output Writer

    CLI->>Engine: Compare(options, oldCfg, newCfg)
    alt DetectOrder enabled
        Engine->>OrderDet: DetectReorders(oldRuleIDs, newRuleIDs)
        OrderDet-->>Engine: []OrderChange
    end
    loop per change
        alt Normalize enabled
            Engine->>Normal: NormalizeValue(old/new)
            Normal-->>Engine: normalized value
        end
        Engine->>Scorer: Score(change) // preserves explicit SecurityImpact or matches patterns
        Scorer-->>Engine: SecurityImpact
    end
    Engine->>Scorer: ScoreAll(changes)
    Scorer-->>Engine: RiskSummary
    Engine->>Factory: NewWithMode(format, mode, Writer)
    Factory-->>Formatter: ConcreteFormatter
    Engine->>Formatter: Format(result)
    Formatter->>Writer: Write(output)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(diff): add configuration diff tool for OPNsense XML comparison #227 — Directly related work that also modifies the diff subsystem (formatters, engine, normalization/order detection, scoring).
• feat: parse and report IDS/Suricata configuration #237 — Related changes to report/markdown generation and formatting that touch internal/processor/report.go.
• feat(reports): implement gateway groups in reports for GitHub Issue 65 #83 — Overlaps on processor/report.go and markdown/golden-test flow modernizations.

Poem

✨ Columns split the old and new in tidy light,
Normalizers hush the noise so diffs read right.
Orders found, patterns score the riskiest thing,
HTML blooms, side‑by‑side makes changes sing.
Secure, auditable—small tools doing big things.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 48.75% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows conventional commit format with 'feat(diff):' prefix and clearly describes the main additions: HTML formatter, side-by-side mode, analyzers, and security scoring.
Description check	✅ Passed	Description provides a clear summary, lists new packages, documents test plan outcomes, and includes statistics. Most template sections are present or reasonably addressed through the structured summary format.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch alert-fix-1

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 markdownlint-cli2 (0.20.0)

AGENTS.md

markdownlint-cli2 v0.20.0 (markdownlint v0.40.0)
Finding: AGENTS.md /*.md !CHANGELOG.md !.venv/ !/node_modules/ !/pycache/ !**/*.tpl.md
Linting: 72 file(s)
TypeError: Cannot read properties of undefined (reading 'slice')
at applyFix (file:///usr/local/lib/node_modules/markdownlint-cli2/node_modules/markdownlint/lib/markdownlint.mjs:1295:10)
at applyFixes (file:///usr/local/lib/node_modules/markdownlint-cli2/node_modules/markdownlint/lib/markdownlint.mjs:1369:26)
at file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:817:31
at async Promise.all (index 0)
at async Promise.all (index 0)
at async main (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:1063:23)
at async file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs:14:22

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 75.98784% with 158 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/diff/formatters/terminal_sidebyside.go	57.14%	35 Missing and 19 partials ⚠️
cmd/diff.go	16.27%	35 Missing and 1 partial ⚠️
internal/processor/report.go	72.00%	20 Missing and 1 partial ⚠️
internal/diff/analyzer.go	73.80%	7 Missing and 4 partials ⚠️
internal/diff/analyzers/normalizer.go	86.66%	5 Missing and 5 partials ⚠️
internal/diff/security/scorer.go	87.67%	8 Missing and 1 partial ⚠️
internal/diff/formatters/html.go	57.14%	3 Missing and 3 partials ⚠️
internal/diff/engine.go	93.90%	2 Missing and 3 partials ⚠️
internal/diff/formatters/markdown.go	37.50%	4 Missing and 1 partial ⚠️
internal/diff/types.go	87.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds new diff output capabilities (HTML + side-by-side terminal) and introduces a security scoring subsystem intended to enrich diff results with risk summaries, fitting into the cmd/diff → internal/diff pipeline.

Changes:

• Introduces a formatter factory + new HTML and side-by-side terminal formatters (with embedded static assets).
• Adds new analyzer utilities (normalization + reorder detection) and a pattern-based security scoring engine with aggregated RiskSummary.
• Extends diff CLI/options/types to support new flags, output mode, and risk summary metadata.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
internal/processor/report.go	Refactors markdown generation to use chained builder calls; adjusts Summary() rendering.
internal/diff/types.go	Adds ChangeReordered, risk summary types, and new diff options/behavior knobs.
internal/diff/types_test.go	Extends section filtering tests for case-insensitive matches.
internal/diff/security/scorer.go	Adds pattern-based scoring and aggregate risk computation.
internal/diff/security/scorer_test.go	Adds unit tests for scorer behavior and aggregation.
internal/diff/security/risk.go	Defines risk summary model and scoring weights for the security package.
internal/diff/security/patterns.go	Defines built-in risk scoring patterns.
internal/diff/security/patterns_test.go	Tests for default pattern integrity/uniqueness.
internal/diff/formatters/formatter.go	Adds Formatter interface and factory (New, NewWithMode).
internal/diff/formatters/formatter_test.go	Tests factory behavior and interface compliance.
internal/diff/formatters/html.go	Adds self-contained HTML report formatter (template + embedded assets).
internal/diff/formatters/html_test.go	Tests HTML output structure, embedding, and risk/security badge rendering.
internal/diff/formatters/terminal_sidebyside.go	Adds side-by-side terminal formatter with width detection + unified fallback.
internal/diff/formatters/terminal_sidebyside_test.go	Tests side-by-side formatting behavior and fallback paths.
internal/diff/formatters/static/styles.css	Adds embedded CSS for HTML report (dark/light + print).
internal/diff/formatters/static/scripts.js	Adds embedded JS for HTML interactivity (toggle/filter).
internal/diff/formatters/static/report.html.tmpl	Adds embedded HTML template for diff reports and risk summary section.
internal/diff/formatters/markdown.go	Updates security badge mapping to use diff.SecurityImpact* constants.
internal/diff/engine.go	Wires in security scoring + aggregate risk summary population.
internal/diff/analyzers/normalizer.go	Adds normalization helpers (IP/whitespace/port/protocol/path).
internal/diff/analyzers/normalizer_test.go	Unit tests for normalizer behaviors.
internal/diff/analyzers/order_detector.go	Adds reorder detection helper for ordered ID lists.
internal/diff/analyzers/order_detector_test.go	Unit tests for reorder detection behavior.
cmd/diff.go	Adds new CLI flags/completions/help text and uses formatter factory.
internal/audit/plugin.go	Collapses package comment formatting.
go.mod	Adds golang.org/x/term dependency for terminal sizing.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 37 out of 37 changed files in this pull request and generated 2 comments.

[unclesp1d3r]

Addressed all unresolved Copilot review findings in commit 1787694:

Code fixes:

• order_detector.go:47 - Sorted DetectReorders output by ID for deterministic results (also partial fix for Implement deterministic ordering for map-based configuration elements #243)
• scorer.go:101/100 - TopRisks already uses tier-based prioritization: medium items are only appended when summary.High == 0. This prevents medium items from crowding out high items.
• engine.go (normalize) - Fixed misleading --normalize description to "Normalize displayed values". Also added skip logic for changes where normalized values are equal.
• engine.go:214 (detect-order) - Reorder detection now runs AFTER section comparison and filters out UUIDs that already have content changes.
• terminal_sidebyside.go:66 - By design: queries os.Stdout since side-by-side is only for interactive terminals. Falls back to unified when width < 80.
• engine.go:161 - NormalizePort now validates input is numeric before processing, preventing damage to non-port strings.
• scorer.go:24 - Updated ChangeInput.Type comment to include "reordered".
• terminal_sidebyside.go:130 - Replaced %-*s with padRight() using lipgloss.Width() for ANSI-safe alignment.
• html.go:82 - Added html.WithUnsafe() to goldmark renderer to preserve <details> sections.
• engine_test.go - Added 5 engine integration tests for DetectOrder, Normalize, and RiskSummary.
• cmd/diff.go:76 - Fixed flag help text.

Low priority/deferred:

• golden_test.go:141 - RiskSummary in golden tests: Scoring is tested separately in security/scorer_test.go. Adding scorer integration to golden tests would tightly couple formatter and scorer tests.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated no new comments.