@decocms/start 2.10.0 → 2.12.0

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

@@ -0,0 +1,460 @@
+import { describe, expect, it } from "vitest";
+import { _internals, ALL_RULES } from "./rules";
+import { runAudit } from "./runner";
+import type { FsAdapter, FsWriter } 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";
+
+/**
+ * Mutable in-memory FS — read AND write share one backing store. Used
+ * for fix-mode tests. The `store` is exposed so tests can assert what
+ * the writer left behind (deletions and content rewrites).
+ */
+function makeMutableFs(initial: Record<string, string>): {
+  fs: FsAdapter;
+  writer: FsWriter;
+  store: Record<string, string>;
+  log: { kind: "delete" | "write"; absPath: string }[];
+} {
+  const store = Object.fromEntries(
+    Object.entries(initial).map(([k, v]) => [k.replace(/\\/g, "/"), v]),
+  );
+  const log: { kind: "delete" | "write"; absPath: string }[] = [];
+  const fs: FsAdapter = {
+    exists(absPath) {
+      return absPath.replace(/\\/g, "/") in store;
+    },
+    readText(absPath) {
+      const k = absPath.replace(/\\/g, "/");
+      if (!(k in store)) throw new Error(`ENOENT: ${absPath}`);
+      return store[k];
+    },
+    glob(siteDir, pattern, excludeDirs = []) {
+      const root = siteDir.replace(/\\/g, "/");
+      const all = Object.keys(store).filter((p) => p.startsWith(`${root}/`));
+      const filtered = all.filter((p) => {
+        const rel = p.slice(root.length + 1);
+        return !excludeDirs.some((dir) => rel.startsWith(`${dir}/`));
+      });
+      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 writer: FsWriter = {
+    deleteFile(absPath) {
+      const k = absPath.replace(/\\/g, "/");
+      delete store[k];
+      log.push({ kind: "delete", absPath: k });
+    },
+    writeText(absPath, content) {
+      const k = absPath.replace(/\\/g, "/");
+      store[k] = content;
+      log.push({ kind: "write", absPath: k });
+    },
+  };
+  return { fs, writer, store, log };
+}
+
+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);
+    expect(report.totalFixActions).toBe(0);
+  });
+
+  it("supportsAutoFix flag reflects rule capability", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const supported = report.rules
+      .filter((r) => r.supportsAutoFix)
+      .map((r) => r.rule)
+      .sort();
+    expect(supported).toEqual(
+      ["dead-lib-shims", "dead-runtime-shim", "local-widgets-types"].sort(),
+    );
+  });
+});
+
+describe("runAudit — fix mode", () => {
+  it("does not mutate when no writer is provided (default audit-only)", () => {
+    const { fs, store } = makeMutableFs({
+      "/site/src/lib/dead.ts": "export const foo = 1;\n",
+    });
+    const before = { ...store };
+    runAudit(SITE, fs);
+    expect(store).toEqual(before);
+  });
+
+  it("fix mode deletes a dead-lib shim and reports the action", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/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, { writer });
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].kind).toBe("delete");
+    expect(r.fixes![0].file).toBe("src/lib/dead.ts");
+    expect("/site/src/lib/dead.ts" in store).toBe(false);
+    expect("/site/src/sections/Other.tsx" in store).toBe(true);
+    expect(report.totalFixActions).toBe(1);
+  });
+
+  it("fix mode rewrites runtime imports + deletes runtime.ts", () => {
+    const { fs, writer, store, log } = makeMutableFs({
+      "/site/src/runtime.ts":
+        "export const invoke = createNestedInvokeProxy();\nexport function createNestedInvokeProxy() { return {}; }\n",
+      "/site/src/sections/A.tsx": 'import { invoke } from "~/runtime";\nconsole.log(invoke);\n',
+      "/site/src/sections/B.tsx": "import { invoke } from '~/runtime';\nconsole.log(invoke);\n",
+      "/site/src/sections/C.tsx":
+        'import { other } from "~/something-else";\nconsole.log(other);\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].detail).toMatch(/rewrote 2 import/);
+    expect("/site/src/runtime.ts" in store).toBe(false);
+    expect(store["/site/src/sections/A.tsx"]).toContain('"@decocms/start/sdk"');
+    expect(store["/site/src/sections/B.tsx"]).toContain("'@decocms/start/sdk'");
+    expect(store["/site/src/sections/C.tsx"]).toContain('"~/something-else"');
+    expect(log.filter((e) => e.kind === "delete")).toHaveLength(1);
+    expect(log.filter((e) => e.kind === "write")).toHaveLength(2);
+  });
+
+  it("fix mode rewrites widgets imports + deletes widgets.ts", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/types/widgets.ts": "export type ImageWidget = string;\n",
+      "/site/src/sections/A.tsx":
+        'import type { ImageWidget } from "~/types/widgets";\nexport const x: ImageWidget = "y";\n',
+      "/site/src/sections/B.tsx":
+        "import type { ImageWidget } from '~/types/widgets';\nexport const y: ImageWidget = 'z';\n",
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "local-widgets-types")!;
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].detail).toMatch(/rewrote 2 import/);
+    expect("/site/src/types/widgets.ts" in store).toBe(false);
+    expect(store["/site/src/sections/A.tsx"]).toContain('"@decocms/start/types/widgets"');
+    expect(store["/site/src/sections/B.tsx"]).toContain("'@decocms/start/types/widgets'");
+  });
+
+  it("fix mode is a no-op for rules without applyFix (e.g. framework-todos)", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/sections/Foo.tsx": "// TODO: move into decoVitePlugin\nexport const x = 1;\n",
+    });
+    const beforeStore = { ...store };
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "framework-todos")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toBeUndefined();
+    expect(r.supportsAutoFix).toBe(false);
+    expect(store).toEqual(beforeStore);
+  });
+
+  it("fix mode rewrites only exact matches, not prefix collisions", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/types/widgets.ts": "export type ImageWidget = string;\n",
+      "/site/src/sections/A.tsx":
+        'import type { ImageWidget } from "~/types/widgets";\nimport thing from "~/types/widgets-extra";\n',
+    });
+    runAudit(SITE, fs, { writer });
+    expect(store["/site/src/sections/A.tsx"]).toContain('"@decocms/start/types/widgets"');
+    expect(store["/site/src/sections/A.tsx"]).toContain('"~/types/widgets-extra"');
+  });
+});

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

@@ -0,0 +1,137 @@
+/**
+ * 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, FsWriter, Rule, RuleSummary } from "./types";
+
+export interface RunAuditOptions {
+  /**
+   * When set, rules with an `applyFix` implementation will run their
+   * fix and the report will include the resulting `FixAction[]`.
+   * Without this, the runner is purely read-only.
+   */
+  writer?: FsWriter;
+  /** Restrict to a subset of rules (defaults to all). */
+  rules?: Rule[];
+}
+
+export function runAudit(
+  siteDir: string,
+  adapter: FsAdapter,
+  options: RunAuditOptions = {},
+): AuditReport {
+  const rules = options.rules ?? ALL_RULES;
+  const summaries: RuleSummary[] = rules.map((rule) => {
+    const findings = rule.run({ siteDir, fs: adapter });
+    const supportsAutoFix = typeof rule.applyFix === "function";
+    let fixes: RuleSummary["fixes"];
+    if (options.writer && rule.applyFix && findings.length > 0) {
+      fixes = rule.applyFix({ siteDir, fs: adapter }, findings, options.writer);
+    }
+    return {
+      rule: rule.id,
+      title: rule.title,
+      findings,
+      supportsAutoFix,
+      fixes,
+    };
+  });
+  return {
+    site: siteDir,
+    rules: summaries,
+    totalFindings: summaries.reduce((acc, s) => acc + s.findings.length, 0),
+    totalFixActions: summaries.reduce((acc, s) => acc + (s.fixes?.length ?? 0), 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();
+  },
+};
+
+/**
+ * Real disk writer used by the CLI when `--fix` is on. Tests should
+ * use a recording adapter and never instantiate this.
+ *
+ * `deleteFile` is intentionally tolerant: if the file is already gone
+ * (race with a previous fix or manual cleanup), we treat that as a
+ * no-op rather than crashing the audit.
+ */
+export const realFsWriter: FsWriter = {
+  deleteFile(absPath: string) {
+    if (fs.existsSync(absPath)) fs.unlinkSync(absPath);
+  },
+  writeText(absPath: string, content: string) {
+    fs.writeFileSync(absPath, content, "utf-8");
+  },
+};