fix(report): three Copilot review fixes — TTY detection + CHANGELOG accuracy

PR #20 review surfaced two distinct issues, both real:

1. Color decisions were made against the StringIO sink, not the
   real terminal. Each detector's print_report instantiated
   Report::Style.new(io: @output), and the rake task passes
   `output: sink` (a StringIO) so the sink can be flushed around
   the top/bottom Summary renders. StringIO is never a TTY, so
   the body of the report came out plain even on a real terminal,
   while the Summary (rendered directly to $stdout) was colored.
   Inconsistent and silently dead — exactly the failure mode TTY
   detection is supposed to prevent.

   Fix: build one Report::Style instance in the rake task bound
   to $stdout (the real terminal), thread it through every
   detector via the existing `style:` constructor parameter, and
   pass the same instance to Summary. Detectors keep writing to
   sink but make their color decisions consistently against the
   real output target.

   Audit was the one detector that didn't accept `style:` yet
   (every other migrated detector did) — added the parameter.

2. CHANGELOG severity table claimed inline_style and
   helper_recommended were errors, but SEVERITY_FOR_TYPE in
   audit.rb classifies them as warnings (and the rake task's
   summary entries match the warning classification). Updated
   the CHANGELOG table to match the code. Also added a note
   about a11y_deep: section heading is a fixed banner, but
   per-finding severity varies based on axe impact —
   critical/serious become error, moderate becomes warning,
   minor becomes suggestion.

Full suite 498/498.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jathayde

CHANGELOG.md

@@ -34,9 +34,11 @@ Each detector type carries an implicit severity that drives both summary groupin
 
 | Severity | Detectors |
 |---|---|
-| `error` | `raw_color`, `tailwind_arbitrary`, `inline_style`, `helper_recommended`, all 4 static `a11y` rules, `a11y_deep` (critical/serious impacts), `visual_diff` (any mismatch above threshold) |
-| `warning` | `stimulus orphaned`, `stimulus dead`, `missing previews`, `orphan slots`, `a11y_deep` (moderate impact) |
-| `suggestion` | `similar partials`, `cross-codebase patterns`, `class-itis`, `a11y_deep` (minor impact) |
+| `error` | `raw_color`, `tailwind_arbitrary`, all 4 static `a11y` rules (`image_alt`, `button_name`, `link_name`, `input_label`), `visual_diff` (any mismatch above threshold) |
+| `warning` | `inline_style`, `helper_recommended`, `stimulus orphaned`, `stimulus dead`, `missing previews`, `orphan slots` |
+| `suggestion` | `similar partials`, `cross-codebase patterns`, `class-itis` |
+
+**`a11y_deep` is a special case:** its section heading is fixed (rendered as a single banner), but each finding is tagged at a severity derived from axe-core's `impact` field — `critical` and `serious` become `error`, `moderate` becomes `warning`, `minor` becomes `suggestion`. So a single `a11y_deep` section can contain a mix of severity tags. The summary entry for the section uses the strictest impact present (default: `:error` if any are present) so the rollup over-counts toward urgency rather than under-counts.
 
 This isn't yet exposed as a configurable filter (e.g. `SEVERITY=error` to mute suggestions) — see follow-ups below.
 

lib/guardrails/audit.rb

@@ -70,13 +70,14 @@ class Audit
       flood-color lighting-color stop-color
     ].freeze
 
-    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false)
+    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil)
       @root = Pathname(root)
       @output = output
       @suggest = suggest
       @format = format
       @apply = apply
       @config = load_audit_config
+      @style = style
     end
 
     def run

lib/tasks/guardrails.rake

@@ -111,23 +111,39 @@ namespace :guardrails do
       # render the top-of-report summary before the per-category
       # details (the summary needs every detector's count). Then
       # write the sink + per-category sections out together.
+      #
+      # Important: detectors write into `sink` (StringIO) but make
+      # ANSI-color decisions against `$stdout`. If we let each
+      # detector instantiate its own Style bound to the sink, every
+      # color() call would be false (StringIO isn't a TTY) and the
+      # body of the report would print plain even on a real terminal,
+      # while the top/bottom summary printed straight to $stdout
+      # would still be colored. Pre-build one Style here and thread
+      # it through every detector so the whole report tracks the
+      # real terminal's TTY/NO_COLOR signal consistently.
       require "guardrails/report/summary"
+      require "guardrails/report/style"
       sink = StringIO.new
+      report_style = Guardrails::Report::Style.new(io: $stdout)
       violations = Guardrails::Audit.new(
-        root: root, output: sink, suggest: suggest, apply: apply, format: :text
+        root: root, output: sink, suggest: suggest, apply: apply, format: :text,
+        style: report_style
       ).run
-      stimulus = Guardrails::StimulusAudit.new(root: root, output: sink).run
+      stimulus = Guardrails::StimulusAudit.new(root: root, output: sink, style: report_style).run
       similarity_opts[:output] = sink
+      similarity_opts[:style] = report_style
       similarity = Guardrails::PartialSimilarity.new(**similarity_opts).run
-      vc = Guardrails::ViewComponentAudit.new(root: root, output: sink).run
-      a11y = Guardrails::A11yAudit.new(root: root, output: sink).run
+      vc = Guardrails::ViewComponentAudit.new(root: root, output: sink, style: report_style).run
+      a11y = Guardrails::A11yAudit.new(root: root, output: sink, style: report_style).run
       pattern_opts[:output] = sink
+      pattern_opts[:style] = report_style
       patterns = Guardrails::CrossCodebasePatterns.new(**pattern_opts).run
       classitis_opts[:output] = sink
+      classitis_opts[:style] = report_style
       classitis = Guardrails::ClassItis.new(**classitis_opts).run
-      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path, output: sink) : nil
+      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path, output: sink, style: report_style) : nil
       a11y_deep = a11y_deep_runner&.run || []
-      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root, output: sink) : nil
+      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root, output: sink, style: report_style) : nil
       visual_diff = visual_diff_runner&.run || []
 
       summary_entries = [
@@ -187,7 +203,7 @@ namespace :guardrails do
       # don't have to scroll back up after the per-detector dump.
       # On a long output (Patchvault has 981 findings) the bottom
       # recap is the load-bearing one.
-      summary = Guardrails::Report::Summary.new(entries: summary_entries, output: $stdout)
+      summary = Guardrails::Report::Summary.new(entries: summary_entries, output: $stdout, style: report_style)
       summary.render
       $stdout.write sink.string
       summary.render(recap: true)