RubyGems - ui_guardrails - Versions diffs - 1.2.0 → 1.3.0 - Mend

ui_guardrails 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

checksums.yaml +4 -4
data/README.md +20 -2
data/lib/guardrails/a11y_audit.rb +26 -3
data/lib/guardrails/a11y_deep.rb +27 -2
data/lib/guardrails/audit.rb +31 -3
data/lib/guardrails/class_itis.rb +30 -3
data/lib/guardrails/cross_codebase_patterns.rb +30 -3
data/lib/guardrails/partial_similarity.rb +30 -3
data/lib/guardrails/report/finding.rb +63 -0
data/lib/guardrails/report/html/template.html.erb +237 -0
data/lib/guardrails/report/html.rb +104 -0
data/lib/guardrails/report/run.rb +224 -0
data/lib/guardrails/stimulus_audit.rb +88 -12
data/lib/guardrails/tui/editor.rb +71 -0
data/lib/guardrails/tui/keys.rb +101 -0
data/lib/guardrails/tui/screen.rb +361 -0
data/lib/guardrails/tui/state.rb +356 -0
data/lib/guardrails/tui.rb +154 -0
data/lib/guardrails/version.rb +1 -1
data/lib/guardrails/view_component_audit.rb +57 -7
data/lib/guardrails/visual_diff.rb +36 -6
data/lib/tasks/guardrails.rake +41 -192
metadata +10 -1

data/lib/guardrails/report/html/template.html.erb ADDED Viewed

@@ -0,0 +1,237 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="ui_guardrails <%= h Guardrails::VERSION %>">
+<title>Guardrails audit — <%= h project_name %></title>
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #fbfaf8; --surface: #ffffff; --ink: #1d1c1a; --muted: #6b6760; --line: #e4e0d8;
+    --code-bg: #f4f1ec; --accent: #2b5fd9;
+    --error: #c0322b; --error-bg: #fbeceb;
+    --warning: #9a6300; --warning-bg: #fbf3e0;
+    --suggestion: #1f6f78; --suggestion-bg: #e6f3f4;
+    --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #161514; --surface: #1f1e1c; --ink: #ece9e3; --muted: #9a958c; --line: #33312d;
+      --code-bg: #262422; --accent: #8fb0ff;
+      --error: #ff8a80; --error-bg: #3a1f1d;
+      --warning: #f0c060; --warning-bg: #36290f;
+      --suggestion: #7fd0d8; --suggestion-bg: #14302f;
+    }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.55 var(--sans); }
+  a { color: var(--accent); }
+  code, pre, .loc, .mono { font-family: var(--mono); font-size: 13px; }
+  .wrap { max-width: 1040px; margin: 0 auto; padding: 0 20px; }
+  header.top { position: sticky; top: 0; z-index: 2; background: var(--bg); border-bottom: 1px solid var(--line); }
+  header.top .wrap { display: flex; flex-wrap: wrap; align-items: center; gap: 10px 16px; padding-top: 12px; padding-bottom: 12px; }
+  h1 { font-size: 17px; margin: 0; font-weight: 650; letter-spacing: -0.01em; }
+  h1 span { color: var(--muted); font-weight: 400; }
+  .controls { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-left: auto; }
+  input[type=search], select {
+    font: inherit; font-size: 14px; color: var(--ink); background: var(--surface);
+    border: 1px solid var(--line); border-radius: 6px; padding: 5px 9px;
+  }
+  input[type=search] { width: 220px; }
+  .toggle {
+    font: inherit; font-size: 13px; font-weight: 600; cursor: pointer; border-radius: 999px; padding: 3px 11px;
+    border: 1px solid transparent; color: var(--sev); background: var(--sev-bg);
+  }
+  .toggle[aria-pressed=false] { background: transparent; border-color: var(--line); color: var(--muted); text-decoration: line-through; }
+  .error { --sev: var(--error); --sev-bg: var(--error-bg); }
+  .warning { --sev: var(--warning); --sev-bg: var(--warning-bg); }
+  .suggestion { --sev: var(--suggestion); --sev-bg: var(--suggestion-bg); }
+  main { padding: 24px 0 56px; }
+  .meta { color: var(--muted); font-size: 13px; margin: 0 0 20px; }
+  table.rollup { width: 100%; border-collapse: collapse; background: var(--surface); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; }
+  .rollup th { text-align: left; font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--sev); background: var(--sev-bg); padding: 7px 14px; }
+  .rollup td { padding: 7px 14px; border-top: 1px solid var(--line); }
+  .rollup td.count { text-align: right; font-variant-numeric: tabular-nums; width: 1%; white-space: nowrap; }
+  .rollup td.flag { color: var(--muted); font-size: 13px; width: 1%; white-space: nowrap; }
+  .rollup a { color: inherit; text-decoration: none; font-weight: 550; }
+  .rollup a:hover { text-decoration: underline; }
+  section.category { margin-top: 40px; scroll-margin-top: 70px; }
+  section.category h2 { font-size: 16px; margin: 0 0 4px; display: flex; align-items: baseline; gap: 10px; }
+  .badge { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; color: var(--sev); background: var(--sev-bg); border-radius: 4px; padding: 2px 7px; }
+  .tally { color: var(--muted); font-weight: 400; font-size: 14px; }
+  .framing { color: var(--muted); margin: 0 0 14px; max-width: 70ch; }
+  .finding { background: var(--surface); border: 1px solid var(--line); border-left: 3px solid var(--sev); border-radius: 6px; padding: 11px 14px; margin-top: 8px; }
+  .finding h3 { font: 600 13.5px/1.45 var(--mono); margin: 0; overflow-wrap: anywhere; }
+  .suggest { margin: 5px 0 0; }
+  .suggest::before { content: "→ "; color: var(--suggestion); font-weight: 700; }
+  .locs { list-style: none; margin: 7px 0 0; padding: 0; }
+  .loc { color: var(--muted); overflow-wrap: anywhere; }
+  a.loc[href] { color: var(--accent); }
+  details.more summary { cursor: pointer; color: var(--muted); font-size: 13px; margin-top: 3px; }
+  pre { background: var(--code-bg); border-radius: 5px; padding: 8px 11px; margin: 9px 0 0; overflow-x: auto; white-space: pre-wrap; overflow-wrap: anywhere; }
+  dl.details { display: grid; grid-template-columns: max-content 1fr; gap: 2px 12px; margin: 8px 0 0; font-size: 13px; }
+  dl.details dt { color: var(--muted); }
+  dl.details dd { margin: 0; overflow-wrap: anywhere; }
+  footer.credit { border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; text-align: center; padding: 22px 0 36px; }
+  footer.credit a { color: inherit; font-weight: 600; }
+  footer.credit a:hover { color: var(--accent); }
+  .clean, .nomatch { text-align: center; color: var(--muted); padding: 60px 0; }
+  [hidden] { display: none !important; }
+</style>
+</head>
+<body>
+<header class="top">
+  <div class="wrap">
+    <h1>Guardrails audit <span>— <%= h project_name %></span></h1>
+    <div class="controls">
+      <%- Summary::SEVERITY_ORDER.each do |severity| -%>
+      <%- next if severity_count(severity).zero? -%>
+      <button type="button" class="toggle <%= severity %>" data-severity="<%= severity %>" aria-pressed="true"><%= h SEVERITY_LABEL[severity] %>s · <%= severity_count(severity) %></button>
+      <%- end -%>
+      <input type="search" id="filter" placeholder="Filter findings…" aria-label="Filter findings">
+      <select id="editor" aria-label="Open file locations in">
+        <option value="">Links: off</option>
+        <%- EDITOR_URLS.each_key do |name| -%>
+        <option><%= h name %></option>
+        <%- end -%>
+      </select>
+    </div>
+  </div>
+</header>
+<main class="wrap">
+  <p class="meta"><%= pluralize(findings.length, "finding") %> across <%= pluralize(@categories.length, "category", "categories") %> · <span class="mono"><%= h @root %></span> · generated <%= h @generated_at.strftime("%Y-%m-%d %H:%M") %> by ui_guardrails <%= h Guardrails::VERSION %></p>
+  <%- if @categories.empty? -%>
+  <p class="clean">✓ No findings — the audit is clean.</p>
+  <%- else -%>
+  <table class="rollup">
+    <%- severity_groups.each do |severity, group| -%>
+    <tbody class="<%= severity %>" data-severity="<%= severity %>">
+      <tr><th colspan="3"><%= h SEVERITY_LABEL[severity] %>s — <%= pluralize(group.sum(&:count), "finding") %></th></tr>
+      <%- group.each do |category| -%>
+      <tr>
+        <td><a href="#<%= anchor(category) %>"><%= h category.name %></a></td>
+        <td class="flag"><%= "auto-fix available" if category.auto_fix %></td>
+        <td class="count"><%= category.count %></td>
+      </tr>
+      <%- end -%>
+    </tbody>
+    <%- end -%>
+  </table>
+  <%- @categories.each do |category| -%>
+  <section class="category <%= category.severity %>" id="<%= anchor(category) %>" data-severity="<%= category.severity %>">
+    <h2><span class="badge"><%= h SEVERITY_LABEL[category.severity] %></span> <%= h category.name %> <span class="tally"><span class="shown"><%= category.count %></span> of <%= category.count %></span></h2>
+    <%- if category.framing -%>
+    <p class="framing"><%= h category.framing %></p>
+    <%- end -%>
+    <%- category.findings.each do |finding| -%>
+    <article class="finding <%= finding.severity %>" data-severity="<%= finding.severity %>" data-search="<%= h search_text(finding) %>">
+      <h3><%= h finding.title %></h3>
+      <%- if finding.suggestion -%>
+      <p class="suggest"><%= h finding.suggestion %></p>
+      <%- end -%>
+      <%- unless finding.locations.empty? -%>
+      <%- shown, rest = finding.locations.first(8), finding.locations.drop(8) -%>
+      <ul class="locs">
+        <%- shown.each do |location| -%>
+        <li><a class="loc" data-path="<%= h absolute(location) %>" data-line="<%= h location.line %>" data-column="<%= h location.column %>"><%= h location %></a></li>
+        <%- end -%>
+      </ul>
+      <%- unless rest.empty? -%>
+      <details class="more">
+        <summary>… and <%= rest.length %> more</summary>
+        <ul class="locs">
+          <%- rest.each do |location| -%>
+          <li><a class="loc" data-path="<%= h absolute(location) %>" data-line="<%= h location.line %>" data-column="<%= h location.column %>"><%= h location %></a></li>
+          <%- end -%>
+        </ul>
+      </details>
+      <%- end -%>
+      <%- end -%>
+      <%- if finding.snippet -%>
+      <pre><code><%= h finding.snippet %></code></pre>
+      <%- end -%>
+      <%- unless finding.details.empty? -%>
+      <dl class="details">
+        <%- finding.details.each do |label, value| -%>
+        <dt><%= h label %></dt><dd class="mono"><%= h value %></dd>
+        <%- end -%>
+      </dl>
+      <%- end -%>
+    </article>
+    <%- end -%>
+  </section>
+  <%- end -%>
+  <p class="nomatch" hidden>No findings match the current filter.</p>
+  <%- end -%>
+</main>
+<footer class="credit">
+  <div class="wrap">ui-guardrails — built by <a href="https://meticulous.com" rel="noopener">Meticulous</a> with love</div>
+</footer>
+<script>
+(function () {
+  var EDITORS = <%= editor_urls_json %>;
+  var filter = document.getElementById("filter");
+  var editor = document.getElementById("editor");
+  var toggles = [].slice.call(document.querySelectorAll(".toggle"));
+  var off = {};
+  function apply() {
+    var needle = filter.value.trim().toLowerCase();
+    var any = false;
+    [].forEach.call(document.querySelectorAll("section.category"), function (section) {
+      var shown = 0;
+      [].forEach.call(section.querySelectorAll(".finding"), function (el) {
+        var visible = !off[el.dataset.severity] && (!needle || el.dataset.search.indexOf(needle) !== -1);
+        el.hidden = !visible;
+        if (visible) shown++;
+      });
+      section.hidden = shown === 0;
+      section.querySelector(".shown").textContent = shown;
+      if (shown) any = true;
+    });
+    var nomatch = document.querySelector(".nomatch");
+    if (nomatch) nomatch.hidden = any;
+  }
+  function link() {
+    var template = EDITORS[editor.value];
+    [].forEach.call(document.querySelectorAll("a.loc"), function (a) {
+      if (!template) { a.removeAttribute("href"); return; }
+      a.href = template
+        .replace("{path}", encodeURI(a.dataset.path))
+        .replace("{line}", a.dataset.line || "1")
+        .replace("{column}", a.dataset.column || "1");
+    });
+  }
+  toggles.forEach(function (button) {
+    button.addEventListener("click", function () {
+      var severity = button.dataset.severity;
+      off[severity] = !off[severity];
+      button.setAttribute("aria-pressed", String(!off[severity]));
+      apply();
+    });
+  });
+  filter.addEventListener("input", apply);
+  editor.addEventListener("change", function () {
+    try { localStorage.setItem("guardrails-editor", editor.value); } catch (e) {}
+    link();
+  });
+  try { editor.value = localStorage.getItem("guardrails-editor") || ""; } catch (e) {}
+  link();
+})();
+</script>
+</body>
+</html>

data/lib/guardrails/report/html.rb ADDED Viewed

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+require "erb"
+require "fileutils"
+require "json"
+require "pathname"
+require_relative "finding"
+require_relative "summary"
+require_relative "../version"
+module Guardrails
+  module Report
+    # The audit as one self-contained HTML file: no server, no asset
+    # pipeline, no network. Everything (CSS, the small filter script)
+    # is inline, so the file works opened from disk, attached to a PR,
+    # or published as a CI artifact.
+    #
+    # Renders from Report::Category / Report::Finding, the same data
+    # the TUI browses — the two are views of one audit run.
+    class Html
+      DEFAULT_PATH = "tmp/guardrails/audit.html"
+      TEMPLATE = File.expand_path("html/template.html.erb", __dir__)
+      # "Open in editor" link schemes, chosen client-side and kept in
+      # localStorage — the report can't know which editor its reader
+      # uses, and a CI artifact is read by more than one person.
+      EDITOR_URLS = {
+        "VS Code" => "vscode://file/{path}:{line}:{column}",
+        "Cursor" => "cursor://file/{path}:{line}:{column}",
+        "Zed" => "zed://file/{path}:{line}:{column}",
+        "TextMate" => "txmt://open?url=file://{path}&line={line}&column={column}",
+        "RubyMine" => "x-mine://open?file={path}&line={line}&column={column}"
+      }.freeze
+      SEVERITY_LABEL = { error: "Error", warning: "Warning", suggestion: "Suggestion" }.freeze
+      def initialize(categories:, root:, generated_at: Time.now)
+        @categories = categories
+        @root = Pathname(root).expand_path
+        @generated_at = generated_at
+      end
+      def render
+        ERB.new(File.read(TEMPLATE, encoding: Encoding::UTF_8), trim_mode: "-").result(binding)
+      end
+      # Writes the report and returns the absolute path written.
+      def write(path = DEFAULT_PATH)
+        target = Pathname(path)
+        target = @root.join(target) unless target.absolute?
+        FileUtils.mkdir_p(target.dirname)
+        File.write(target, render)
+        target
+      end
+      private
+      def h(text)
+        ERB::Util.html_escape(text.to_s)
+      end
+      def findings
+        @categories.flat_map(&:findings)
+      end
+      def project_name
+        @root.basename.to_s
+      end
+      def severity_groups
+        Summary::SEVERITY_ORDER.filter_map do |severity|
+          group = @categories.select { |c| c.severity == severity }
+          [severity, group] unless group.empty?
+        end
+      end
+      def severity_count(severity)
+        findings.count { |f| f.severity == severity }
+      end
+      def anchor(category)
+        "cat-#{category.name.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')}"
+      end
+      def absolute(location)
+        @root.join(location.file).to_s
+      end
+      # Lowercased text the client-side filter matches against.
+      def search_text(finding)
+        [finding.category, finding.title, finding.suggestion, *finding.files].compact.join(" ").downcase
+      end
+      # JSON embedded in a <script> must not be able to close it.
+      def editor_urls_json
+        JSON.generate(EDITOR_URLS).gsub("</", '<\/')
+      end
+      def pluralize(count, singular, plural = "#{singular}s")
+        "#{count} #{count == 1 ? singular : plural}"
+      end
+    end
+  end
+end

data/lib/guardrails/report/run.rb ADDED Viewed

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+require "stringio"
+require "pathname"
+require_relative "../audit"
+require_relative "../stimulus_audit"
+require_relative "../partial_similarity"
+require_relative "../view_component_audit"
+require_relative "../a11y_audit"
+require_relative "../cross_codebase_patterns"
+require_relative "../class_itis"
+require_relative "../a11y_deep"
+require_relative "../visual_diff"
+require_relative "summary"
+require_relative "finding"
+require_relative "../configuration"
+module Guardrails
+  module Report
+    # One full audit pass: runs every detector once and holds the
+    # results so any number of front-ends (text report, JSON, and
+    # anything interactive) can render from the same data without
+    # re-running detectors or re-deriving the summary.
+    #
+    # Detectors still print their own per-section text; Run captures
+    # that into `body` rather than letting it hit the terminal, because
+    # the summary has to print first and needs every detector's count.
+    #
+    # `new` takes plain arguments so it's callable from specs and
+    # non-rake entry points; `from_env` is the one place the audit's
+    # env-var surface is parsed, shared by every task that runs one.
+    class Run
+      TRUTHY = %w[1 true yes].freeze
+      attr_reader :violations, :stimulus, :similarity, :view_components,
+                  :a11y, :patterns, :classitis, :a11y_deep, :visual_diff
+      # Builds a Run from the documented env vars (SUGGEST, APPLY,
+      # AXE_JSON, VISUAL_DIFF*, SIMILARITY_THRESHOLD, PATTERN_*,
+      # CLASSITIS_*).
+      def self.from_env(root:, style: nil, env: ENV)
+        # Visual-diff is opt-in (baselines need deliberate setup). Enabled
+        # when either VISUAL_DIFF=1 is set in the env (sidecar mode) or
+        # Guardrails.configuration.visual_diff.enabled was flipped on by a
+        # Rails initializer (embedded mode). Env overrides Configuration.
+        visual_diff_on = truthy?(env["VISUAL_DIFF"]) || Guardrails.configuration.visual_diff.enabled
+        # Strip + reject blank env values — an empty VISUAL_DIFF_DIR would
+        # otherwise be applied as snap_diff_dir = "" and glob from the repo
+        # root (potentially scanning the whole tree).
+        if (dir = env["VISUAL_DIFF_DIR"]) && !dir.strip.empty?
+          Guardrails.configure { |c| c.visual_diff.snap_diff_dir = dir.strip }
+        end
+        if (thr = env["VISUAL_DIFF_THRESHOLD"]) && !thr.strip.empty?
+          Guardrails.configure { |c| c.visual_diff.threshold = thr.strip }
+        end
+        similarity = {}
+        similarity[:threshold] = env["SIMILARITY_THRESHOLD"].to_f if env["SIMILARITY_THRESHOLD"]
+        patterns = {}
+        patterns[:min_size] = env["PATTERN_MIN_SIZE"].to_i if env["PATTERN_MIN_SIZE"]
+        patterns[:min_occurrences] = env["PATTERN_MIN_OCCURRENCES"].to_i if env["PATTERN_MIN_OCCURRENCES"]
+        classitis = {}
+        classitis[:min_classes] = env["CLASSITIS_MIN_CLASSES"].to_i if env["CLASSITIS_MIN_CLASSES"]
+        classitis[:min_occurrences] = env["CLASSITIS_MIN_OCCURRENCES"].to_i if env["CLASSITIS_MIN_OCCURRENCES"]
+        new(root: root, style: style,
+            suggest: truthy?(env["SUGGEST"]), apply: truthy?(env["APPLY"]),
+            axe_json: env["AXE_JSON"], visual_diff: visual_diff_on,
+            similarity: similarity, patterns: patterns, classitis: classitis)
+      end
+      def self.truthy?(value)
+        TRUTHY.include?(value&.downcase)
+      end
+      # `style` should be bound to the *real* output stream, not the
+      # capture sink: detectors write into a StringIO but must make
+      # ANSI decisions against the terminal, or the report body prints
+      # plain while the summary around it is colored. Pass nil to get
+      # uncolored output (what JSON mode wants — the body is discarded).
+      def initialize(root:, style: nil, suggest: false, apply: false,
+                     axe_json: nil, visual_diff: false,
+                     similarity: {}, patterns: {}, classitis: {})
+        @root = Pathname(root)
+        @style = style
+        @suggest = suggest
+        @apply = apply
+        @axe_json = axe_json
+        @visual_diff_on = visual_diff
+        @similarity_opts = similarity
+        @pattern_opts = patterns
+        @classitis_opts = classitis
+        @sink = StringIO.new
+      end
+      def call
+        @violations = detect(Audit.new(**common, suggest: @suggest, apply: @apply, format: :text))
+        @stimulus = detect(StimulusAudit.new(**common))
+        @similarity = detect(PartialSimilarity.new(**common, **@similarity_opts))
+        @view_components = detect(ViewComponentAudit.new(**common))
+        @a11y = detect(A11yAudit.new(**common))
+        @patterns = detect(CrossCodebasePatterns.new(**common, **@pattern_opts))
+        @classitis = detect(ClassItis.new(**common, **@classitis_opts))
+        @a11y_deep_runner = @axe_json ? A11yDeep.new(input: @axe_json, output: @sink, style: @style) : nil
+        @a11y_deep = @a11y_deep_runner ? detect(@a11y_deep_runner) : []
+        @visual_diff_runner = @visual_diff_on ? VisualDiff.new(**common) : nil
+        @visual_diff = @visual_diff_runner ? detect(@visual_diff_runner) : []
+        self
+      end
+      # Every finding as detector-agnostic data (see Report::Finding),
+      # grouped by category and ordered errors → warnings →
+      # suggestions, biggest category first — the same order the
+      # summary rollup uses. Category names match `summary_entries`.
+      def categories
+        @categories ||= @detected
+                        .flat_map { |detector, result| detector.categories(result) }
+                        .sort_by
+                        .with_index { |c, i| [Summary::SEVERITY_ORDER.index(c.severity), -c.count, i] }
+      end
+      def findings
+        categories.flat_map(&:findings)
+      end
+      # The per-detector sections, exactly as the detectors printed them.
+      def body
+        @sink.string
+      end
+      def summary_entries
+        [
+          entry("raw_color", count_type(:raw_color), :error, auto_fix: true),
+          entry("tailwind_arbitrary", count_type(:tailwind_arbitrary), :error, auto_fix: true),
+          entry("inline_style", count_type(:inline_style), :warning),
+          entry("helper_recommended", count_type(:helper_recommended), :warning),
+          entry("a11y (static)", a11y.length, :error),
+          entry("a11y (deep)", a11y_deep.length, :error),
+          entry("stimulus orphaned", stimulus.orphaned.length, :warning),
+          entry("stimulus dead", stimulus.dead.length, :warning),
+          entry("missing previews", view_components.missing_previews.length, :warning),
+          entry("orphan slots", view_components.orphan_slots.length, :warning),
+          entry("visual diff", visual_diff.length, :error),
+          entry("similar partials", similarity.length, :suggestion,
+                unit: "pairs", action: "consider deduplicating"),
+          entry("cross-codebase patterns", patterns.length, :suggestion,
+                unit: "candidates", action: "consider extracting partials"),
+          entry("class-itis", classitis.length, :suggestion,
+                unit: "clusters", action: "consider extracting component / @apply")
+        ]
+      end
+      # FORMAT=json payload. Shape is a public contract — unchanged
+      # since 1.0.0.
+      def to_h
+        {
+          summary: {
+            violations: violations.length,
+            stimulus_orphaned: stimulus.orphaned.length,
+            stimulus_dead: stimulus.dead.length,
+            similar_partials: similarity.length,
+            missing_previews: view_components.missing_previews.length,
+            orphan_slots: view_components.orphan_slots.length,
+            a11y: a11y.length,
+            a11y_deep: a11y_deep.length,
+            patterns: patterns.length,
+            classitis: classitis.length,
+            visual_diff: visual_diff.length
+          },
+          violations: violations.map(&:to_h),
+          stimulus: { orphaned: stimulus.orphaned, dead: stimulus.dead },
+          similar_partials: similarity.map(&:to_h),
+          view_components: {
+            missing_previews: view_components.missing_previews,
+            orphan_slots: view_components.orphan_slots.map(&:to_h)
+          },
+          a11y: a11y.map(&:to_h),
+          a11y_deep: a11y_deep.map(&:to_h),
+          patterns: patterns.map { |p|
+            { fingerprint: p.fingerprint, shape: p.shape, size: p.size, count: p.count, occurrences: p.occurrences.map(&:to_h) }
+          },
+          classitis: classitis.map { |c|
+            { tag: c.tag, classes: c.classes, count: c.count, occurrences: c.occurrences.map(&:to_h) }
+          },
+          visual_diff: visual_diff.map(&:to_h)
+        }
+      end
+      # Exit-code contract: any error or warning fails; the suggestion-
+      # tier pattern / class-itis detectors don't. Deep a11y and visual
+      # diff only fail when a finding crosses their configured
+      # threshold, and are no-ops when not opted into.
+      def failing?
+        violations.any? || stimulus.violations? || similarity.any? ||
+          view_components.violations? || a11y.any? ||
+          (@a11y_deep_runner&.any_failing?(a11y_deep) || false) ||
+          (@visual_diff_runner&.any_failing?(visual_diff) || false)
+      end
+      private
+      # Runs a detector and remembers the pair, so `categories` can ask
+      # each detector to normalize its own result later — only
+      # front-ends that want findings-as-data pay for building them.
+      def detect(detector)
+        result = detector.run
+        (@detected ||= []) << [detector, result]
+        result
+      end
+      def common
+        { root: @root, output: @sink, style: @style }
+      end
+      def count_type(type)
+        violations.count { |v| v.type == type }
+      end
+      def entry(category, count, severity, **rest)
+        Summary::Entry.new(category: category, count: count, severity: severity, **rest)
+      end
+    end
+  end
+end