@decocms/start 2.9.0 → 2.11.0

package/scripts/migrate/post-cleanup/rules.ts

@@ -0,0 +1,293 @@
+/**
+ * Post-migration cleanup audit — rule implementations.
+ *
+ * Each rule mirrors a section in
+ * `.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md`.
+ * The intent is to take the human checklist and make it programmatically
+ * detectable so future migrations get the same scrubbing automatically.
+ *
+ * Rules are intentionally read-only here — `--fix` is a follow-up.
+ */
+
+import type { Finding, Rule, RuleContext } from "./types";
+
+const SRC_GLOB_EXCLUDES = ["node_modules", "dist", ".wrangler", ".vite", ".tanstack", "build"];
+
+/* ------------------------------------------------------------------ */
+/* Rule 1 — dead `src/lib/*` shims                                     */
+/* ------------------------------------------------------------------ */
+
+const EXPORT_RE = /^export\s+(?:function|const|interface|type|class)\s+([A-Za-z_][A-Za-z0-9_]*)/gm;
+
+function extractExports(content: string): string[] {
+  const out: string[] = [];
+  for (const m of content.matchAll(EXPORT_RE)) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+function symbolUsedOutsideLib(siteDir: string, fs: RuleContext["fs"], symbol: string): boolean {
+  const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+  const re = new RegExp(`\\b${symbol}\\b`);
+  for (const file of tsFiles) {
+    if (file.includes("/src/lib/")) continue;
+    const content = fs.readText(file);
+    if (re.test(content)) return true;
+  }
+  return false;
+}
+
+const ruleDeadLibShims: Rule = {
+  id: "dead-lib-shims",
+  title: "Dead src/lib/* shims",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const libFiles = fs.glob(siteDir, "src/lib/*.ts", SRC_GLOB_EXCLUDES);
+    if (libFiles.length === 0) return [];
+
+    const findings: Finding[] = [];
+    for (const abs of libFiles) {
+      const rel = abs.slice(siteDir.length + 1);
+      const content = fs.readText(abs);
+      const exports = extractExports(content);
+      if (exports.length === 0) continue;
+      const allDead = exports.every((s) => !symbolUsedOutsideLib(siteDir, fs, s));
+      if (!allDead) continue;
+      findings.push({
+        rule: "dead-lib-shims",
+        severity: "info",
+        file: rel,
+        message: `${exports.length} export(s), 0 external imports`,
+        fix: `rm ${rel}`,
+        meta: { exports },
+      });
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 2 — obsolete inline vite plugins                               */
+/* ------------------------------------------------------------------ */
+
+const OBSOLETE_VITE_PLUGINS: { name: string; reason: string }[] = [
+  {
+    name: "site-manual-chunks",
+    reason: "framework's decoVitePlugin() now owns chunking",
+  },
+  {
+    name: "deco-stub-meta-gen",
+    reason: "framework now stubs meta.gen.{json,ts} on the client by default",
+  },
+];
+
+const ruleObsoleteVitePlugins: Rule = {
+  id: "obsolete-vite-plugins",
+  title: "Obsolete inline Vite plugins",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    const candidates = ["vite.config.ts", "vite.config.js", "vite.config.mjs"];
+    for (const rel of candidates) {
+      const abs = `${siteDir}/${rel}`;
+      if (!fs.exists(abs)) continue;
+      const content = fs.readText(abs);
+      for (const plugin of OBSOLETE_VITE_PLUGINS) {
+        const re = new RegExp(`name:\\s*["']${plugin.name}["']`);
+        if (!re.test(content)) continue;
+        findings.push({
+          rule: "obsolete-vite-plugins",
+          severity: "warning",
+          file: rel,
+          message: `'${plugin.name}' plugin is obsolete — ${plugin.reason}`,
+          fix: `delete the inline '${plugin.name}' plugin from ${rel}`,
+          meta: { plugin: plugin.name },
+        });
+      }
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 3 — dead `src/runtime.ts` invoke shim                          */
+/* ------------------------------------------------------------------ */
+
+const ruleDeadRuntimeShim: Rule = {
+  id: "dead-runtime-shim",
+  title: "Dead src/runtime.ts invoke shim",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const abs = `${siteDir}/src/runtime.ts`;
+    if (!fs.exists(abs)) return [];
+    const content = fs.readText(abs);
+    // Heuristic: if the file's only meaningful exports are `invoke` /
+    // `createNestedInvokeProxy`, it's purely a shim.
+    const exports = extractExports(content);
+    const onlyInvokeShim =
+      exports.length > 0 && exports.every((e) => ["invoke", "createNestedInvokeProxy"].includes(e));
+    if (!onlyInvokeShim) return [];
+    return [
+      {
+        rule: "dead-runtime-shim",
+        severity: "info",
+        file: "src/runtime.ts",
+        message: `Only re-exports invoke (${exports.join(", ")}) — replace with @decocms/start/sdk`,
+        fix: 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts',
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 4 — site-local `withSiteGlobals` workaround                    */
+/* ------------------------------------------------------------------ */
+
+const ruleSiteLocalGlobals: Rule = {
+  id: "site-local-with-globals",
+  title: "Site-local withSiteGlobals wrapper",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    const candidates = fs.glob(siteDir, "src/**/withSiteGlobals.ts", SRC_GLOB_EXCLUDES);
+    for (const abs of candidates) {
+      const content = fs.readText(abs);
+      // Heuristic: any local definition (function/const) of withSiteGlobals or
+      // cmsRouteWithGlobals indicates a local wrapper, not a re-export from
+      // the framework. The framework version would just re-export.
+      const definesWrapper =
+        /(?:export\s+)?(?:function|const)\s+(?:withSiteGlobals|cmsRouteWithGlobals)\b/.test(
+          content,
+        );
+      const reExportsFromFramework = /from\s+['"]@decocms\/start\/routes['"]/.test(content);
+      if (!definesWrapper || reExportsFromFramework) continue;
+      const rel = abs.slice(siteDir.length + 1);
+      const lineCount = content.split("\n").length;
+      findings.push({
+        rule: "site-local-with-globals",
+        severity: "warning",
+        file: rel,
+        message: `Local wrapper (~${lineCount} LOC) — framework now exports withSiteGlobals from @decocms/start/routes`,
+        fix: "delete the local wrapper and import { withSiteGlobals } from '@decocms/start/routes'",
+        meta: { lineCount },
+      });
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 5 — `~/lib/vtex-*` shim regression                             */
+/* ------------------------------------------------------------------ */
+
+const ruleVtexShimRegression: Rule = {
+  id: "vtex-shim-regression",
+  title: "Imports from ~/lib/vtex-* (silent stub regression)",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    const findings: Finding[] = [];
+    const re = /from\s+['"]~\/lib\/vtex-([A-Za-z0-9-]+)['"]/g;
+    for (const abs of tsFiles) {
+      if (abs.includes("/src/lib/")) continue;
+      const content = fs.readText(abs);
+      const matches = [...content.matchAll(re)];
+      if (matches.length === 0) continue;
+      const rel = abs.slice(siteDir.length + 1);
+      const shims = [...new Set(matches.map((m) => `vtex-${m[1]}`))];
+      findings.push({
+        rule: "vtex-shim-regression",
+        severity: "warning",
+        file: rel,
+        message: `Imports from dead shim(s): ${shims.join(", ")} — runtime is silently stubbed`,
+        fix: "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'",
+        meta: { shims },
+      });
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 6 — local `src/types/widgets.ts` shadowing framework           */
+/* ------------------------------------------------------------------ */
+
+const ruleLocalWidgetsTypes: Rule = {
+  id: "local-widgets-types",
+  title: "Local src/types/widgets.ts shadowing framework",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const abs = `${siteDir}/src/types/widgets.ts`;
+    if (!fs.exists(abs)) return [];
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    const re = /from\s+['"]~\/types\/widgets['"]/;
+    let importCount = 0;
+    for (const f of tsFiles) {
+      if (f === abs) continue;
+      if (re.test(fs.readText(f))) importCount++;
+    }
+    return [
+      {
+        rule: "local-widgets-types",
+        severity: "info",
+        file: "src/types/widgets.ts",
+        message: `Local file shadows @decocms/start/types/widgets (used in ${importCount} place(s))`,
+        fix: 'rewrite imports to "@decocms/start/types/widgets" and rm src/types/widgets.ts',
+        meta: { importCount },
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 7 — orphan "TODO: framework" comments                          */
+/* ------------------------------------------------------------------ */
+
+const ruleFrameworkTodos: Rule = {
+  id: "framework-todos",
+  title: "Orphan TODOs deferring to the framework",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const tsFiles = [
+      ...fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES),
+      ...fs.glob(siteDir, "vite.config.ts", SRC_GLOB_EXCLUDES),
+    ];
+    const findings: Finding[] = [];
+    const re = /TODO[^\n]*?(?:deco|framework|move into)/i;
+    for (const abs of tsFiles) {
+      const content = fs.readText(abs);
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (!re.test(lines[i])) continue;
+        const rel = abs.slice(siteDir.length + 1);
+        findings.push({
+          rule: "framework-todos",
+          severity: "info",
+          file: `${rel}:${i + 1}`,
+          message: lines[i].trim().slice(0, 120),
+          fix: "Triage: shipped → adopt; deferred → file issue; obsolete → delete",
+        });
+      }
+    }
+    return findings;
+  },
+};
+
+export const ALL_RULES: Rule[] = [
+  ruleDeadLibShims,
+  ruleObsoleteVitePlugins,
+  ruleDeadRuntimeShim,
+  ruleSiteLocalGlobals,
+  ruleVtexShimRegression,
+  ruleLocalWidgetsTypes,
+  ruleFrameworkTodos,
+];
+
+/** Exported for direct unit tests. */
+export const _internals = {
+  extractExports,
+  symbolUsedOutsideLib,
+  rules: {
+    ruleDeadLibShims,
+    ruleObsoleteVitePlugins,
+    ruleDeadRuntimeShim,
+    ruleSiteLocalGlobals,
+    ruleVtexShimRegression,
+    ruleLocalWidgetsTypes,
+    ruleFrameworkTodos,
+  },
+};

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -0,0 +1,288 @@
+import { describe, expect, it } from "vitest";
+import { _internals, ALL_RULES } from "./rules";
+import { runAudit } from "./runner";
+import type { FsAdapter } from "./types";
+
+/**
+ * In-memory FsAdapter for tests. Maps absolute path → file content.
+ * `glob` does a literal substring-pattern match — good enough for our
+ * tests which never use complex globs.
+ */
+function makeFs(files: Record<string, string>): FsAdapter {
+  const norm = Object.fromEntries(
+    Object.entries(files).map(([k, v]) => [k.replace(/\\/g, "/"), v]),
+  );
+  return {
+    exists(absPath) {
+      return absPath.replace(/\\/g, "/") in norm;
+    },
+    readText(absPath) {
+      const key = absPath.replace(/\\/g, "/");
+      if (!(key in norm)) throw new Error(`ENOENT: ${absPath}`);
+      return norm[key];
+    },
+    glob(siteDir, pattern, excludeDirs = []) {
+      const root = siteDir.replace(/\\/g, "/");
+      const all = Object.keys(norm).filter((p) => p.startsWith(`${root}/`));
+      const filtered = all.filter((p) => {
+        const rel = p.slice(root.length + 1);
+        return !excludeDirs.some((dir) => rel.startsWith(`${dir}/`));
+      });
+      // Build a regex that handles ** and {a,b} the same way the real
+      // adapter does — but lighter, just enough for the test patterns.
+      const branches = pattern.includes("{")
+        ? pattern
+            .match(/\{([^{}]+)\}/)![1]
+            .split(",")
+            .map((b) => pattern.replace(/\{[^{}]+\}/, b.trim()))
+        : [pattern];
+      const regexes = branches.map((p) => {
+        const re = p
+          .replace(/[.+^$()|]/g, "\\$&")
+          .replace(/\*\*\//g, "<<DBL>>")
+          .replace(/\*\*/g, "<<DBL>>")
+          .replace(/\*/g, "[^/]*")
+          .replace(/<<DBL>>/g, "(?:.*/)?");
+        return new RegExp(`^${re}$`);
+      });
+      return filtered
+        .filter((p) => {
+          const rel = p.slice(root.length + 1);
+          return regexes.some((re) => re.test(rel));
+        })
+        .sort();
+    },
+  };
+}
+
+const SITE = "/site";
+
+describe("runAudit — empty site", () => {
+  it("returns zero findings on an empty tree", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    expect(report.site).toBe(SITE);
+    expect(report.totalFindings).toBe(0);
+    expect(report.rules).toHaveLength(ALL_RULES.length);
+    for (const r of report.rules) expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: dead-lib-shims", () => {
+  it("flags a shim whose only export is unreferenced", () => {
+    const fs = makeFs({
+      "/site/src/lib/dead.ts": "export const foo = 1;\n",
+      "/site/src/sections/Other.tsx": 'export const x = "y";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/lib/dead.ts");
+    expect(r.findings[0].fix).toContain("rm src/lib/dead.ts");
+  });
+
+  it("does not flag a shim referenced from outside src/lib", () => {
+    const fs = makeFs({
+      "/site/src/lib/used.ts": "export function helper() { return 1; }\n",
+      "/site/src/sections/Caller.tsx": 'import { helper } from "~/lib/used";\nhelper();\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does not flag a shim with no exports at all (likely intentional empty file)", () => {
+    const fs = makeFs({
+      "/site/src/lib/empty.ts": "// nothing here\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags only when ALL exports are dead — partial use spares the file", () => {
+    const fs = makeFs({
+      "/site/src/lib/mixed.ts": "export const used = 1;\nexport const unused = 2;\n",
+      "/site/src/sections/Caller.tsx": 'import { used } from "~/lib/mixed";\nconsole.log(used);\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: obsolete-vite-plugins", () => {
+  it("detects site-manual-chunks", () => {
+    const fs = makeFs({
+      "/site/vite.config.ts": `
+        export default defineConfig({
+          plugins: [
+            { name: "site-manual-chunks", config() { return {}; } },
+          ],
+        });
+      `,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.plugin).toBe("site-manual-chunks");
+  });
+
+  it("detects deco-stub-meta-gen", () => {
+    const fs = makeFs({
+      "/site/vite.config.ts": 'plugins: [{ name: "deco-stub-meta-gen", enforce: "pre" }]',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.plugin).toBe("deco-stub-meta-gen");
+  });
+
+  it("returns zero findings when both are absent", () => {
+    const fs = makeFs({
+      "/site/vite.config.ts": 'plugins: [{ name: "react", enforce: "pre" }]',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: dead-runtime-shim", () => {
+  it("flags an invoke-only runtime.ts", () => {
+    const fs = makeFs({
+      "/site/src/runtime.ts":
+        "export const invoke = createNestedInvokeProxy();\nexport function createNestedInvokeProxy() { return {}; }\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/runtime.ts");
+  });
+
+  it("does not flag a runtime.ts that exports site-specific helpers", () => {
+    const fs = makeFs({
+      "/site/src/runtime.ts": "export const invoke = {};\nexport const customHelper = () => 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: site-local-with-globals", () => {
+  it("flags a local cmsRouteWithGlobals wrapper", () => {
+    const lines = Array(120).fill("// boilerplate").join("\n");
+    const fs = makeFs({
+      "/site/src/server/routes/withSiteGlobals.ts": `${lines}\nexport function cmsRouteWithGlobals() { return {}; }\n`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "site-local-with-globals")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.lineCount).toBeGreaterThan(100);
+  });
+
+  it("does not flag a re-export from the framework", () => {
+    const fs = makeFs({
+      "/site/src/server/routes/withSiteGlobals.ts":
+        'export { withSiteGlobals } from "@decocms/start/routes";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "site-local-with-globals")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: vtex-shim-regression", () => {
+  it("flags imports from ~/lib/vtex-segment", () => {
+    const fs = makeFs({
+      "/site/src/sections/Foo.tsx": 'import { getSegment } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.shims).toContain("vtex-segment");
+  });
+
+  it("does not flag imports from src/lib itself", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts": 'import other from "~/lib/vtex-fetch";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: local-widgets-types", () => {
+  it("flags presence of src/types/widgets.ts and counts imports", () => {
+    const fs = makeFs({
+      "/site/src/types/widgets.ts": "export type ImageWidget = string;\n",
+      "/site/src/sections/A.tsx": 'import type { ImageWidget } from "~/types/widgets";\n',
+      "/site/src/sections/B.tsx": 'import type { ImageWidget } from "~/types/widgets";\n',
+      "/site/src/sections/C.tsx": "export const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-widgets-types")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.importCount).toBe(2);
+  });
+
+  it("returns zero findings when the file does not exist", () => {
+    const fs = makeFs({
+      "/site/src/sections/A.tsx": "export const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-widgets-types")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: framework-todos", () => {
+  it("flags TODOs that mention deco/framework/move into", () => {
+    const fs = makeFs({
+      "/site/src/sections/Foo.tsx":
+        "// TODO: move into decoVitePlugin in next release\nexport const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "framework-todos")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toContain(":1");
+  });
+
+  it("does not flag unrelated TODOs", () => {
+    const fs = makeFs({
+      "/site/src/sections/Foo.tsx": "// TODO: i18n strings\nexport const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "framework-todos")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("internals", () => {
+  it("extractExports parses common forms (top-level, unindented)", () => {
+    const code = [
+      "export const a = 1;",
+      "export function b() {}",
+      "export interface C {}",
+      "export type D = string;",
+      "export class E {}",
+      "const private_ = 1;",
+    ].join("\n");
+    expect(_internals.extractExports(code).sort()).toEqual(["C", "D", "E", "a", "b"]);
+  });
+});
+
+describe("runAudit — totals", () => {
+  it("totalFindings sums across all rules", () => {
+    const fs = makeFs({
+      "/site/src/lib/dead.ts": "export const x = 1;\n",
+      "/site/vite.config.ts": 'plugins: [{ name: "site-manual-chunks", config() {} }]',
+      "/site/src/sections/Foo.tsx":
+        "// TODO: deco framework should own this\nexport const y = 2;\n",
+    });
+    const report = runAudit(SITE, fs);
+    expect(report.totalFindings).toBe(3);
+  });
+});

package/scripts/migrate/post-cleanup/runner.ts

@@ -0,0 +1,97 @@
+/**
+ * Post-migration cleanup audit — orchestrator.
+ *
+ * `runAudit` is the testable, FS-injected entry. The CLI in
+ * `../../migrate-post-cleanup.ts` wires up the real disk adapter.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ALL_RULES } from "./rules";
+import type { AuditReport, FsAdapter, Rule, RuleSummary } from "./types";
+
+export function runAudit(
+  siteDir: string,
+  adapter: FsAdapter,
+  rules: Rule[] = ALL_RULES,
+): AuditReport {
+  const summaries: RuleSummary[] = rules.map((r) => ({
+    rule: r.id,
+    title: r.title,
+    findings: r.run({ siteDir, fs: adapter }),
+  }));
+  return {
+    site: siteDir,
+    rules: summaries,
+    totalFindings: summaries.reduce((acc, s) => acc + s.findings.length, 0),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Real disk adapter                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Minimal recursive-walk glob — intentionally tiny, no external deps.
+ * Supports `**`, `*`, and `{a,b,c}` brace expansion.  Does NOT support
+ * extglob, negation, or `?`. That's fine: every pattern in this audit
+ * fits the supported subset.
+ */
+function expandBraces(pattern: string): string[] {
+  const m = pattern.match(/\{([^{}]+)\}/);
+  if (!m) return [pattern];
+  const [whole, inner] = m;
+  const start = pattern.indexOf(whole);
+  const before = pattern.slice(0, start);
+  const after = pattern.slice(start + whole.length);
+  const branches = inner.split(",");
+  return branches.flatMap((b) => expandBraces(`${before}${b}${after}`));
+}
+
+function patternToRegex(pattern: string): RegExp {
+  const re = pattern
+    .replace(/[.+^$()|]/g, "\\$&")
+    .replace(/\*\*\//g, "<<DBL>>")
+    .replace(/\*\*/g, "<<DBL>>")
+    .replace(/\*/g, "[^/]*")
+    .replace(/<<DBL>>/g, "(?:.*/)?");
+  return new RegExp(`^${re}$`);
+}
+
+function walk(dir: string, rootDir: string, excludeDirs: Set<string>, out: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (excludeDirs.has(entry.name)) continue;
+      walk(abs, rootDir, excludeDirs, out);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+}
+
+export const realFsAdapter: FsAdapter = {
+  exists(absPath: string) {
+    return fs.existsSync(absPath);
+  },
+  readText(absPath: string) {
+    return fs.readFileSync(absPath, "utf-8");
+  },
+  glob(siteDir: string, pattern: string, excludeDirs: string[] = []) {
+    const allFiles: string[] = [];
+    walk(siteDir, siteDir, new Set(excludeDirs), allFiles);
+    const patterns = expandBraces(pattern).map(patternToRegex);
+    const matches = allFiles.filter((abs) => {
+      const rel = abs.slice(siteDir.length + 1).replace(/\\/g, "/");
+      return patterns.some((re) => re.test(rel));
+    });
+    return matches.sort();
+  },
+};