@cloverleaf/reference-impl 0.3.1 → 0.4.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "cloverleaf",
+  "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge).",
+  "version": "0.4.1",
+  "author": {
+    "name": "Renato D'Arrigo",
+    "email": "renato.darrigo@gmail.com"
+  },
+  "homepage": "https://github.com/cloverleaf-org/cloverleaf",
+  "repository": "https://github.com/cloverleaf-org/cloverleaf",
+  "license": "MIT",
+  "keywords": [
+    "cloverleaf",
+    "methodology",
+    "ai-first",
+    "reference-implementation"
+  ]
+}

package/VERSION

@@ -1 +1 @@
-0.3.1
+0.4.1

package/config/affected-routes.json

@@ -1,13 +1,11 @@
 {
-  "pageRoots": ["site/src/pages/"],
+  "pageRoots": ["src/pages/"],
   "globalPatterns": [
-    "site/src/layouts/**",
-    "site/src/components/**",
-    "site/src/styles/**",
-    "site/public/**",
-    "site/astro.config.*",
-    "site/src/content/**"
+    "src/layouts/**",
+    "src/components/**",
+    "src/styles/**",
+    "public/**"
   ],
-  "routeScope": ["site/src/**", "site/public/**"],
+  "routeScope": ["src/**", "public/**"],
   "contentRoutes": {}
 }

package/config/qa-rules.json

@@ -1,19 +1,9 @@
 {
   "rules": [
     {
-      "cwd": "standard",
-      "match": ["standard/**"],
-      "command": "npm ci && npm test"
-    },
-    {
-      "cwd": "reference-impl",
-      "match": ["reference-impl/**"],
-      "command": "npm ci && npm test"
-    },
-    {
-      "cwd": "site",
-      "match": ["site/**"],
-      "command": "npm ci && npm run build"
+      "cwd": ".",
+      "match": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.json"],
+      "command": "npm test"
     }
   ]
 }

package/config/ui-paths.json

@@ -1,3 +1,8 @@
 {
-  "patterns": ["site/**"]
+  "patterns": [
+    "src/pages/**",
+    "src/components/**",
+    "src/layouts/**",
+    "src/styles/**"
+  ]
 }

package/config/ui-review.json

@@ -0,0 +1,18 @@
+{
+  "viewports": {
+    "mobile":  { "width": 375,  "height": 667 },
+    "tablet":  { "width": 768,  "height": 1024 },
+    "desktop": { "width": 1280, "height": 800 }
+  },
+  "visualDiff": {
+    "enabled": true,
+    "threshold": 0.1,
+    "maxDiffRatio": 0.01,
+    "mask": []
+  },
+  "axe": {
+    "viewports": ["desktop"],
+    "dedupeBy": ["ruleId", "target"],
+    "ignored": []
+  }
+}

package/dist/affected-routes.mjs

@@ -25,7 +25,7 @@ function routeForPage(file, pageRoot) {
         return '/';
     return `/${withoutExt}/`;
 }
-export function loadDefaultConfig() {
+function loadDefaultConfig() {
     if (!existsSync(DEFAULT_CONFIG)) {
         throw new Error(`affected-routes config not found at ${DEFAULT_CONFIG}`);
     }

package/dist/axe-dedupe.mjs

@@ -0,0 +1,42 @@
+const SEVERITY_MAP = {
+    critical: 'blocker',
+    serious: 'error',
+    moderate: 'warning',
+    minor: 'info',
+};
+function dedupeKeyOf(raw, keys) {
+    return keys.map((k) => raw[k]).join('||');
+}
+export function dedupeAxeFindings(raws, keys, ignored = []) {
+    // Filter out ignored (ruleId, target) tuples BEFORE grouping.
+    const filtered = raws.filter((raw) => {
+        return !ignored.some((i) => i.ruleId === raw.ruleId && i.target === raw.target);
+    });
+    const groups = new Map();
+    for (const raw of filtered) {
+        const key = dedupeKeyOf(raw, keys);
+        const existing = groups.get(key);
+        if (existing) {
+            if (!existing.viewports.includes(raw.viewport))
+                existing.viewports.push(raw.viewport);
+        }
+        else {
+            groups.set(key, { first: raw, viewports: [raw.viewport] });
+        }
+    }
+    const out = [];
+    for (const { first, viewports } of groups.values()) {
+        out.push({
+            severity: SEVERITY_MAP[first.impact],
+            message: first.message,
+            rule: first.ruleId,
+            metadata: {
+                target: first.target,
+                impact: first.impact,
+                viewports,
+                ...(first.helpUrl ? { helpUrl: first.helpUrl } : {}),
+            },
+        });
+    }
+    return out;
+}

package/dist/cli.mjs

@@ -12,6 +12,8 @@
  *   write-feedback <repoRoot> <taskId> <envelopeJsonPath>
  *   latest-feedback <repoRoot> <taskId>
  *   emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]
+ *   ui-review-config --repo-root <repoRoot>
+ *   plugin-root
  */
 import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
@@ -24,6 +26,8 @@ import { matchesUiPaths } from './ui-paths.mjs';
 import { loadUiPathsConfig } from './ui-paths.mjs';
 import { computeAffectedRoutes } from './affected-routes.mjs';
 import { loadAffectedRoutesConfig } from './affected-routes.mjs';
+import { loadUiReviewConfig } from './ui-review-config.mjs';
+import { getPluginRoot } from './plugin-path.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -39,7 +43,9 @@ function usage(msg) {
         '  advance-status <repoRoot> <taskId> <toStatus> <actor> [gate] [path]\n' +
         '  write-feedback <repoRoot> <taskId> <envelopeJsonPath>\n' +
         '  latest-feedback <repoRoot> <taskId>\n' +
-        '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n');
+        '  emit-gate-decision <repoRoot> <workItemId> <gate> <decision> <actor> [--comment=<str>]\n' +
+        '  ui-review-config --repo-root <repoRoot>\n' +
+        '  plugin-root\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -211,6 +217,31 @@ try {
             process.stdout.write(`${JSON.stringify(result)}\n`);
             process.exit(0);
         }
+        case 'ui-review-config': {
+            const flags = rest.filter((a) => a.startsWith('--'));
+            const repoRootFlag = flags.find((f) => f.startsWith('--repo-root=') || f === '--repo-root');
+            let repoRoot;
+            if (repoRootFlag === '--repo-root') {
+                repoRoot = rest[rest.indexOf('--repo-root') + 1];
+            }
+            else if (repoRootFlag) {
+                repoRoot = repoRootFlag.replace('--repo-root=', '');
+            }
+            else {
+                repoRoot = rest.filter((a) => !a.startsWith('--'))[0];
+            }
+            if (!repoRoot) {
+                console.error('usage: ui-review-config --repo-root <repoRoot>');
+                process.exit(1);
+            }
+            const config = loadUiReviewConfig(repoRoot);
+            process.stdout.write(JSON.stringify(config, null, 2));
+            process.exit(0);
+        }
+        case 'plugin-root': {
+            process.stdout.write(getPluginRoot());
+            process.exit(0);
+        }
         default:
             usage(`Unknown command: ${command}`);
     }

package/dist/feedback.mjs

@@ -29,7 +29,7 @@ export function allFeedback(repoRoot, taskId) {
     const dir = feedbackDir(repoRoot);
     if (!existsSync(dir))
         return [];
-    const re = new RegExp(`^${escapeRegex(taskId)}-r(\\d+)\\.json$`);
+    const re = new RegExp(`^${escapeRegex(taskId)}-[ruq](\\d+)\\.json$`);
     const entries = readdirSync(dir)
         .map((f) => ({ f, m: f.match(re) }))
         .filter((x) => !!x.m)

package/dist/plugin-path.mjs

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+/**
+ * Absolute path to the plugin root.
+ *
+ * At runtime, this module lives at <plugin-root>/lib/plugin-path.js (or .ts in dev),
+ * so the plugin root is the parent directory.
+ *
+ * Works under:
+ * - dev mode (repo source: <repo>/reference-impl/)
+ * - npm install (node_modules/@cloverleaf/reference-impl/)
+ * - claude plugin install cache (~/.claude/plugins/cache/cloverleaf-local/cloverleaf/0.4.1/)
+ * - legacy symlink into ~/.claude/plugins/cloverleaf/
+ * - claude --plugin-dir <path>
+ */
+export function getPluginRoot() {
+    return resolve(here, '..');
+}

package/dist/qa-report.mjs

@@ -0,0 +1,65 @@
+function escape(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function renderRow(r) {
+    const status = r.passed ? 'PASS' : 'FAIL';
+    const statusClass = r.passed ? 'pass' : 'fail';
+    return `
+    <tr class="${statusClass}">
+      <td>${escape(r.ruleId)}</td>
+      <td><code>${escape(r.command)}</code></td>
+      <td>${escape(r.cwd)}</td>
+      <td>${r.durationMs}ms</td>
+      <td class="status">${status}</td>
+    </tr>
+    <tr class="detail ${statusClass}">
+      <td colspan="5">
+        ${r.stdoutTail ? `<details><summary>stdout (tail)</summary><pre>${escape(r.stdoutTail)}</pre></details>` : ''}
+        ${r.stderrTail ? `<details open><summary>stderr (tail)</summary><pre>${escape(r.stderrTail)}</pre></details>` : ''}
+      </td>
+    </tr>
+  `;
+}
+export function renderQaReport(runs) {
+    const empty = runs.length === 0
+        ? `<p class="empty">No runs / results.</p>`
+        : '';
+    const rows = runs.map(renderRow).join('');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Cloverleaf QA Report</title>
+  <style>
+    body { font: 14px/1.4 system-ui, sans-serif; margin: 2rem; color: #111; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 0.5rem; border-bottom: 1px solid #ddd; text-align: left; vertical-align: top; }
+    .status { font-weight: 600; }
+    .pass .status { color: #0a7; }
+    .fail .status { color: #c33; }
+    tr.detail td { background: #fafafa; padding-top: 0; }
+    pre { overflow: auto; background: #f4f4f4; padding: 0.5rem; }
+    .empty { color: #888; }
+  </style>
+</head>
+<body>
+  <h1>Cloverleaf QA Report</h1>
+  ${empty}
+  ${runs.length > 0 ? `
+  <table>
+    <thead>
+      <tr><th>Rule</th><th>Command</th><th>CWD</th><th>Duration</th><th>Status</th></tr>
+    </thead>
+    <tbody>
+      ${rows}
+    </tbody>
+  </table>
+  ` : ''}
+</body>
+</html>`;
+}

package/dist/qa-rules.mjs

@@ -4,7 +4,7 @@ import { dirname, join } from 'node:path';
 import { matchesUiPaths } from './ui-paths.mjs';
 const here = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_CONFIG = join(here, '..', 'config', 'qa-rules.json');
-export function loadDefaultRules() {
+function loadDefaultRules() {
     if (!existsSync(DEFAULT_CONFIG))
         return [];
     const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));

package/dist/route-slug.mjs

@@ -0,0 +1,23 @@
+/**
+ * Turn a URL path into a filesystem-safe slug used in baseline/diff filenames.
+ * - "/" → "index"
+ * - "/faq/" → "faq"
+ * - "/guide/chapter-3/" → "guide-chapter-3"
+ * - "/docs/v1.2/getting started/" → "docs-v1-2-getting-started"
+ * Query/hash are stripped.
+ */
+export function slugifyRoute(route) {
+    const pathOnly = route.split(/[?#]/)[0];
+    if (pathOnly === '/' || pathOnly === '')
+        return 'index';
+    const trimmed = pathOnly.replace(/^\/+|\/+$/g, '');
+    if (trimmed === '')
+        return 'index';
+    const slugged = trimmed
+        .toLowerCase()
+        .replace(/[^a-z0-9/-]+/g, '-')
+        .replace(/\/+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return slugged || 'index';
+}

package/dist/ui-paths.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 const here = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_CONFIG = join(here, '..', 'config', 'ui-paths.json');
-export function loadDefaultPatterns() {
+function loadDefaultPatterns() {
     if (!existsSync(DEFAULT_CONFIG))
         return ['site/**'];
     const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8'));

package/dist/ui-review-config.mjs

@@ -0,0 +1,41 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DEFAULT = join(here, '..', 'config', 'ui-review.json');
+const HARDCODED_FALLBACK = {
+    viewports: {
+        mobile: { width: 375, height: 667 },
+        tablet: { width: 768, height: 1024 },
+        desktop: { width: 1280, height: 800 },
+    },
+    visualDiff: { enabled: true, threshold: 0.1, maxDiffRatio: 0.01, mask: [] },
+    axe: { viewports: ['desktop'], dedupeBy: ['ruleId', 'target'], ignored: [] },
+};
+function readAsConfig(path) {
+    try {
+        const doc = JSON.parse(readFileSync(path, 'utf-8'));
+        // Back-compat: if ignored is missing from an older override, default it.
+        if (doc.axe && !('ignored' in doc.axe)) {
+            doc.axe.ignored = [];
+        }
+        return doc;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadUiReviewConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-review.json');
+    if (existsSync(consumerPath)) {
+        const parsed = readAsConfig(consumerPath);
+        if (parsed)
+            return parsed;
+    }
+    if (existsSync(PACKAGE_DEFAULT)) {
+        const parsed = readAsConfig(PACKAGE_DEFAULT);
+        if (parsed)
+            return parsed;
+    }
+    return HARDCODED_FALLBACK;
+}

package/dist/visual-diff.mjs

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+function ensureDir(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+function writeBaseline(baselinePath, buf) {
+    ensureDir(baselinePath);
+    writeFileSync(baselinePath, buf);
+}
+export function compareVisual(args) {
+    const candidatePng = PNG.sync.read(args.candidateBuf);
+    if (!existsSync(args.baselinePath)) {
+        writeBaseline(args.baselinePath, args.candidateBuf);
+        return {
+            status: 'new-baseline',
+            diffPixels: 0,
+            diffRatio: 0,
+            width: candidatePng.width,
+            height: candidatePng.height,
+        };
+    }
+    const baselineBuf = readFileSync(args.baselinePath);
+    const baselinePng = PNG.sync.read(baselineBuf);
+    if (baselinePng.width !== candidatePng.width || baselinePng.height !== candidatePng.height) {
+        writeBaseline(args.baselinePath, args.candidateBuf);
+        return {
+            status: 'dimension-mismatch',
+            diffPixels: 0,
+            diffRatio: 0,
+            width: candidatePng.width,
+            height: candidatePng.height,
+        };
+    }
+    const diffPng = new PNG({ width: candidatePng.width, height: candidatePng.height });
+    const diffPixels = pixelmatch(baselinePng.data, candidatePng.data, diffPng.data, candidatePng.width, candidatePng.height, { threshold: args.threshold });
+    const totalPixels = candidatePng.width * candidatePng.height;
+    const diffRatio = diffPixels / totalPixels;
+    if (diffRatio > args.maxDiffRatio) {
+        ensureDir(args.diffPath);
+        writeFileSync(args.diffPath, PNG.sync.write(diffPng));
+        ensureDir(args.candidateOutPath);
+        writeFileSync(args.candidateOutPath, args.candidateBuf);
+        writeBaseline(args.baselinePath, args.candidateBuf);
+        return {
+            status: 'diff',
+            diffPixels,
+            diffRatio,
+            width: candidatePng.width,
+            height: candidatePng.height,
+        };
+    }
+    writeBaseline(args.baselinePath, args.candidateBuf);
+    return {
+        status: 'match',
+        diffPixels,
+        diffRatio,
+        width: candidatePng.width,
+        height: candidatePng.height,
+    };
+}

package/install.sh

@@ -2,59 +2,45 @@
 set -euo pipefail
 
 # Cloverleaf Reference Impl installer.
-# Default: installs skills + CLI shim into ~/.claude/plugins/cloverleaf/.
-# --project: installs locally into ./.claude/plugins/cloverleaf/.
+#
+# As of v0.4.0, cloverleaf installs as a proper Claude Code plugin via the
+# `claude plugin` CLI. Point Claude Code at the cloverleaf repo root (where
+# .claude-plugin/marketplace.json lives), then install the plugin from the
+# resulting marketplace.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-MODE="user"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --project) MODE="project"; shift ;;
-    --help|-h)
-      echo "Usage: ./install.sh [--project]"
-      echo "  --project: install locally in .claude/plugins/cloverleaf/"
-      echo "  (default): install at ~/.claude/plugins/cloverleaf/"
-      exit 0 ;;
-    *) echo "Unknown arg: $1"; exit 2 ;;
-  esac
-done
-
-if [[ "$MODE" == "user" ]]; then
-  INSTALL_ROOT="${HOME}/.claude/plugins/cloverleaf"
-else
-  INSTALL_ROOT="$(pwd)/.claude/plugins/cloverleaf"
+if ! command -v claude >/dev/null 2>&1; then
+  echo "error: 'claude' CLI not found on PATH."
+  echo "Install Claude Code first: https://docs.claude.com/claude-code"
+  exit 1
 fi
 
-mkdir -p "${INSTALL_ROOT}/skills" "${INSTALL_ROOT}/prompts" "${INSTALL_ROOT}/bin"
-
-# Symlink config directory
-ln -sf "${SCRIPT_DIR}/config" "${INSTALL_ROOT}/config"
-
-# Symlink skills
-for f in "${SCRIPT_DIR}/skills/"*.md; do
-  name="$(basename "$f")"
-  ln -sf "$f" "${INSTALL_ROOT}/skills/${name}"
-done
+if [ ! -f "${REPO_ROOT}/.claude-plugin/marketplace.json" ]; then
+  echo "error: ${REPO_ROOT}/.claude-plugin/marketplace.json not found."
+  echo "This script expects to be run from inside a cloverleaf checkout."
+  exit 1
+fi
 
-# Symlink prompts
-for f in "${SCRIPT_DIR}/prompts/"*.md; do
-  name="$(basename "$f")"
-  ln -sf "$f" "${INSTALL_ROOT}/prompts/${name}"
-done
+echo "Registering cloverleaf marketplace from ${REPO_ROOT}..."
+claude plugin marketplace add "${REPO_ROOT}"
 
-# Write the CLI shim
-cat > "${INSTALL_ROOT}/bin/cloverleaf-cli" <<EOF
-#!/usr/bin/env bash
-exec npx --yes tsx "${SCRIPT_DIR}/lib/cli.ts" "\$@"
-EOF
-chmod +x "${INSTALL_ROOT}/bin/cloverleaf-cli"
+echo "Installing cloverleaf plugin..."
+claude plugin install cloverleaf@cloverleaf-local
 
-echo "Cloverleaf reference impl installed at: ${INSTALL_ROOT}"
-echo "Skills available: $(ls "${INSTALL_ROOT}/skills" | wc -l | tr -d ' ')"
 echo ""
-echo "Add ${INSTALL_ROOT}/bin to your PATH if you want to invoke cloverleaf-cli directly,"
-echo "or reference it by absolute path from your skill calls."
+echo "Cloverleaf installed. Slash commands:"
+echo "  /cloverleaf-new-task   — scaffold a Task from a brief"
+echo "  /cloverleaf-run        — full pipeline orchestrator"
+echo "  /cloverleaf-implement  — run Implementer"
+echo "  /cloverleaf-document   — run Documenter"
+echo "  /cloverleaf-review     — run Reviewer"
+echo "  /cloverleaf-ui-review  — run UI Reviewer (visual diff + multi-viewport + axe)"
+echo "  /cloverleaf-qa         — run QA"
+echo "  /cloverleaf-merge      — merge gate"
+echo ""
+echo "Restart any open Claude Code sessions to pick up the new skills."
 
 # Post-install: warn about Playwright chromium if not cached
 if [ ! -d "${HOME}/.cache/ms-playwright" ] || [ -z "$(ls -A "${HOME}/.cache/ms-playwright" 2>/dev/null)" ]; then

package/lib/affected-routes.ts

@@ -34,7 +34,7 @@ function routeForPage(file: string, pageRoot: string): string | null {
   return `/${withoutExt}/`;
 }
 
-export function loadDefaultConfig(): AffectedRoutesConfig {
+function loadDefaultConfig(): AffectedRoutesConfig {
   if (!existsSync(DEFAULT_CONFIG)) {
     throw new Error(`affected-routes config not found at ${DEFAULT_CONFIG}`);
   }

package/lib/axe-dedupe.ts

@@ -0,0 +1,64 @@
+import type { Finding, FindingSeverity } from './feedback.js';
+
+export type AxeImpact = 'critical' | 'serious' | 'moderate' | 'minor';
+
+export interface RawAxeFinding {
+  viewport: string;
+  ruleId: string;
+  target: string;
+  impact: AxeImpact;
+  message: string;
+  helpUrl?: string;
+}
+
+export type DedupeKey = 'ruleId' | 'target';
+
+const SEVERITY_MAP: Record<AxeImpact, FindingSeverity> = {
+  critical: 'blocker',
+  serious:  'error',
+  moderate: 'warning',
+  minor:    'info',
+};
+
+function dedupeKeyOf(raw: RawAxeFinding, keys: DedupeKey[]): string {
+  return keys.map((k) => raw[k]).join('||');
+}
+
+export function dedupeAxeFindings(
+  raws: RawAxeFinding[],
+  keys: DedupeKey[],
+  ignored: Array<{ ruleId: string; target: string }> = []
+): Finding[] {
+  // Filter out ignored (ruleId, target) tuples BEFORE grouping.
+  const filtered = raws.filter((raw) => {
+    return !ignored.some(
+      (i) => i.ruleId === raw.ruleId && i.target === raw.target
+    );
+  });
+
+  const groups = new Map<string, { first: RawAxeFinding; viewports: string[] }>();
+  for (const raw of filtered) {
+    const key = dedupeKeyOf(raw, keys);
+    const existing = groups.get(key);
+    if (existing) {
+      if (!existing.viewports.includes(raw.viewport)) existing.viewports.push(raw.viewport);
+    } else {
+      groups.set(key, { first: raw, viewports: [raw.viewport] });
+    }
+  }
+  const out: Finding[] = [];
+  for (const { first, viewports } of groups.values()) {
+    out.push({
+      severity: SEVERITY_MAP[first.impact],
+      message: first.message,
+      rule: first.ruleId,
+      metadata: {
+        target: first.target,
+        impact: first.impact,
+        viewports,
+        ...(first.helpUrl ? { helpUrl: first.helpUrl } : {}),
+      },
+    });
+  }
+  return out;
+}