@cloverleaf/reference-impl 0.3.0 → 0.4.0

package/lib/affected-routes.ts

@@ -9,6 +9,7 @@ export interface AffectedRoutesConfig {
   pageRoots: string[];
   globalPatterns: string[];
   routeScope: string[];
+  contentRoutes: Record<string, string>;
 }
 
 function globToRegex(pattern: string): RegExp {
@@ -33,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}`);
   }
@@ -42,9 +43,32 @@ export function loadDefaultConfig(): AffectedRoutesConfig {
     pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
     globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
     routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+    contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+      ? doc.contentRoutes
+      : {},
   };
 }
 
+export function loadAffectedRoutesConfig(repoRoot: string): AffectedRoutesConfig {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'affected-routes.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as Partial<AffectedRoutesConfig>;
+      return {
+        pageRoots: Array.isArray(doc.pageRoots) ? doc.pageRoots : [],
+        globalPatterns: Array.isArray(doc.globalPatterns) ? doc.globalPatterns : [],
+        routeScope: Array.isArray(doc.routeScope) ? doc.routeScope : [],
+        contentRoutes: (doc.contentRoutes && typeof doc.contentRoutes === 'object' && !Array.isArray(doc.contentRoutes))
+          ? doc.contentRoutes
+          : {},
+      };
+    } catch {
+      // fall through
+    }
+  }
+  return loadDefaultConfig();
+}
+
 export function computeAffectedRoutes(
   changedFiles: string[],
   config: AffectedRoutesConfig
@@ -68,6 +92,15 @@ export function computeAffectedRoutes(
       routes.add(mapped);
       continue;
     }
+    // contentRoutes: map content-collection files to specific routes
+    for (const [pattern, route] of Object.entries(config.contentRoutes)) {
+      if (globToRegex(pattern).test(file)) {
+        routes.add(route);
+        mapped = route;
+        break;
+      }
+    }
+    if (mapped) continue;
     if (matchesAny(file, config.routeScope)) {
       inScopeButUnmatched = true;
     }

package/lib/axe-dedupe.ts

@@ -0,0 +1,53 @@
+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[]): Finding[] {
+  const groups = new Map<string, { first: RawAxeFinding; viewports: string[] }>();
+  for (const raw of raws) {
+    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;
+}

package/lib/cli.ts

@@ -12,6 +12,7 @@
  *   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>
  */
 
 import { readFileSync } from 'node:fs';
@@ -21,8 +22,11 @@ import { advanceStatus } from './state.js';
 import { emitGateDecision } from './events.js';
 import { writeFeedback, latestFeedback } from './feedback.js';
 import { nextTaskId, inferProject } from './ids.js';
-import { matchesUiPaths, loadDefaultPatterns } from './ui-paths.js';
-import { computeAffectedRoutes, loadDefaultConfig } from './affected-routes.js';
+import { matchesUiPaths } from './ui-paths.js';
+import { loadUiPathsConfig } from './ui-paths.js';
+import { computeAffectedRoutes } from './affected-routes.js';
+import { loadAffectedRoutesConfig } from './affected-routes.js';
+import { loadUiReviewConfig } from './ui-review-config.js';
 import type { FeedbackEnvelope } from './feedback.js';
 
 function die(msg: string, code = 1): never {
@@ -41,7 +45,8 @@ function usage(msg?: string): never {
       '  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'
   );
   process.exit(2);
 }
@@ -186,7 +191,7 @@ try {
         console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
         process.exit(2);
       }
-      const patterns = loadDefaultPatterns();
+      const { patterns } = loadUiPathsConfig(repoRoot);
       const result = matchesUiPaths(changed, patterns);
       process.stdout.write(`${result}\n`);
       process.exit(0);
@@ -213,12 +218,32 @@ try {
         console.error(`branch ${branch} not found: ${stderrStr || err.message || 'unknown'}`);
         process.exit(2);
       }
-      const config = loadDefaultConfig();
+      const config = loadAffectedRoutesConfig(repoRoot);
       const result = computeAffectedRoutes(changed, config);
       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: string | undefined;
+      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);
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }

package/lib/feedback.ts

@@ -13,12 +13,19 @@ export interface FindingLocation {
   work_item_id?: { project: string; id: string };
 }
 
+export interface Attachment {
+  label: string;
+  path: string;
+}
+
 export interface Finding {
   severity: FindingSeverity;
   message: string;
   location?: FindingLocation;
   suggestion?: string;
   rule?: string;
+  attachments?: Attachment[];
+  metadata?: Record<string, unknown>;
 }
 
 export interface FeedbackEnvelope {

package/lib/qa-report.ts

@@ -0,0 +1,77 @@
+export interface QaRunResult {
+  ruleId: string;
+  command: string;
+  cwd: string;
+  durationMs: number;
+  passed: boolean;
+  stdoutTail: string;
+  stderrTail: string;
+}
+
+function escape(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function renderRow(r: QaRunResult): string {
+  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: QaRunResult[]): string {
+  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/lib/qa-rules.ts

@@ -12,12 +12,27 @@ export interface QaRule {
   command: string;
 }
 
-export function loadDefaultRules(): QaRule[] {
+function loadDefaultRules(): QaRule[] {
   if (!existsSync(DEFAULT_CONFIG)) return [];
   const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8')) as { rules?: QaRule[] };
   return Array.isArray(doc.rules) ? doc.rules : [];
 }
 
+export function loadQaRulesConfig(repoRoot: string): QaRule[] {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'qa-rules.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { rules?: QaRule[] };
+      if (Array.isArray(doc.rules)) {
+        return doc.rules;
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return loadDefaultRules();
+}
+
 export function selectTestCommands(changedFiles: string[], rules: QaRule[]): QaRule[] {
   return rules.filter((rule) => matchesUiPaths(changedFiles, rule.match));
 }

package/lib/route-slug.ts

@@ -0,0 +1,21 @@
+/**
+ * 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: string): string {
+  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/lib/ui-paths.ts

@@ -5,7 +5,7 @@ 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(): string[] {
+function loadDefaultPatterns(): string[] {
   if (!existsSync(DEFAULT_CONFIG)) return ['site/**'];
   const doc = JSON.parse(readFileSync(DEFAULT_CONFIG, 'utf-8')) as { patterns?: string[] };
   return Array.isArray(doc.patterns) ? doc.patterns : ['site/**'];
@@ -20,6 +20,21 @@ function globToRegex(pattern: string): RegExp {
   return new RegExp(`^${regex}$`);
 }
 
+export function loadUiPathsConfig(repoRoot: string): { patterns: string[] } {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'ui-paths.json');
+  if (existsSync(consumerPath)) {
+    try {
+      const doc = JSON.parse(readFileSync(consumerPath, 'utf-8')) as { patterns?: string[] };
+      if (Array.isArray(doc.patterns)) {
+        return { patterns: doc.patterns };
+      }
+    } catch {
+      // fall through to package default
+    }
+  }
+  return { patterns: loadDefaultPatterns() };
+}
+
 export function matchesUiPaths(changedFiles: string[], patterns: string[]): boolean {
   if (changedFiles.length === 0) return false;
   const regexes = patterns.map(globToRegex);

package/lib/ui-review-config.ts

@@ -0,0 +1,57 @@
+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');
+
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+export interface UiReviewConfig {
+  viewports: Record<string, Viewport>;
+  visualDiff: {
+    enabled: boolean;
+    threshold: number;
+    maxDiffRatio: number;
+    mask: string[];
+  };
+  axe: {
+    viewports: string[];
+    dedupeBy: ('ruleId' | 'target')[];
+  };
+}
+
+const HARDCODED_FALLBACK: UiReviewConfig = {
+  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'] },
+};
+
+function readAsConfig(path: string): UiReviewConfig | null {
+  try {
+    const doc = JSON.parse(readFileSync(path, 'utf-8')) as UiReviewConfig;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+export function loadUiReviewConfig(repoRoot: string): UiReviewConfig {
+  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/lib/visual-diff.ts

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+
+export type VisualDiffStatus = 'new-baseline' | 'match' | 'diff' | 'dimension-mismatch';
+
+export interface VisualDiffResult {
+  status: VisualDiffStatus;
+  diffPixels: number;
+  diffRatio: number;
+  width: number;
+  height: number;
+}
+
+export interface CompareVisualArgs {
+  baselinePath: string;
+  candidateBuf: Buffer;
+  diffPath: string;
+  candidateOutPath: string;
+  threshold: number;
+  maxDiffRatio: number;
+}
+
+function ensureDir(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function writeBaseline(baselinePath: string, buf: Buffer): void {
+  ensureDir(baselinePath);
+  writeFileSync(baselinePath, buf);
+}
+
+export function compareVisual(args: CompareVisualArgs): VisualDiffResult {
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "reference-implementation"
   ],
   "files": [
+    ".claude-plugin",
     "skills",
     "lib",
     "prompts",
@@ -46,14 +47,18 @@
     "prepublishOnly": "npm test && npm run build"
   },
   "dependencies": {
-    "@cloverleaf/standard": "^0.3.0",
+    "@cloverleaf/standard": "^0.4.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "axe-core": "^4.10.0",
+    "pixelmatch": "^5.3.0",
     "playwright": "^1.47.0",
-    "axe-core": "^4.10.0"
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"

package/prompts/qa.md

@@ -57,6 +57,27 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 - Use `git worktree`: do NOT `git checkout` in the main working directory.
 - Always teardown the worktree, even on error.
 
+## QA Report (v0.4)
+
+After executing all matched QA rules, write an HTML report summarizing each run to `<repoRoot>/.cloverleaf/runs/{taskId}/qa/report.html` (substitute `{taskId}` with the `id` field from the task input, e.g., `{{task.id}}`).
+
+Use `renderQaReport(runs)` from `lib/qa-report.ts` to produce the HTML. Ensure the directory exists first (`mkdir -p`).
+
+In the feedback you emit, include the report as an attachment on a single info-level finding (or on whichever summary finding you already emit):
+
+```json
+{
+  "severity": "info",
+  "rule": "qa-report",
+  "message": "QA report written",
+  "attachments": [
+    { "label": "report", "path": ".cloverleaf/runs/{taskId}/qa/report.html" }
+  ]
+}
+```
+
+This lets humans at final-gate inspect the full QA detail without grovelling through logs.
+
 ## Output
 
 Respond with exactly one JSON object and nothing else: