@revola-ai/video-craft 0.2.1

package/src/sourceCitations.test.ts

@@ -0,0 +1,747 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { isUpstreamIssue } from "./provenance";
+import { commentsOnly, extractDocCitations, extractIssueCitations } from "./sourceCitations";
+import { toolchainRepoRoot as repoRoot } from "./testSupport";
+
+/**
+ * The extractors, unit-tested against the shapes citations actually take in
+ * this codebase's comments. The trailing-punctuation cases are not
+ * hypothetical: a prune script written during the 2026-08-26 review used a
+ * greedy character class that swallowed the sentence-ending period, so
+ * `docs/.../foo.md.` failed an existsSync and two live design docs landed in
+ * a delete set. Nothing caught it but a manual read of the output.
+ */
+describe("extractDocCitations", () => {
+  test("finds a bare path", () => {
+    expect(extractDocCitations("see docs/superpowers/specs/a.md for why"))
+      .toEqual(["docs/superpowers/specs/a.md"]);
+  });
+
+  test("strips the sentence-ending period, not the extension", () => {
+    expect(extractDocCitations("Design: docs/superpowers/specs/a.md."))
+      .toEqual(["docs/superpowers/specs/a.md"]);
+  });
+
+  test("strips the punctuation a citation is wrapped in", () => {
+    const cases: [string, string][] = [
+      ["(docs/plans/b.md)", "docs/plans/b.md"],
+      ["`docs/plans/b.md`", "docs/plans/b.md"],
+      ['"docs/plans/b.md",', "docs/plans/b.md"],
+      ["docs/plans/b.md;", "docs/plans/b.md"],
+      ["docs/plans/b.md:", "docs/plans/b.md"],
+    ];
+    for (const [input, want] of cases) {
+      expect(extractDocCitations(input), `input ${input}`).toEqual([want]);
+    }
+  });
+
+  test("finds a single-segment path at the repo root", () => {
+    // An earlier DOC_PATTERN required a subdirectory, so every root-level
+    // citation - `docs/accounting.md` among them - went unchecked.
+    expect(extractDocCitations("Accounting correlation (docs/accounting.md): present only when"))
+      .toEqual(["docs/accounting.md"]);
+  });
+
+  test("does NOT extract a docs/ path out of a longer path or a URL", () => {
+    // The URL shape is the one that occurs in this repo's comments
+    // (remotion.dev/docs/..., gemini-api/docs/...): without the left anchor its
+    // tail is read as a local file and fails. The project-relative shape occurs
+    // INSIDE the scanned trees too, in rule `recordedIn:` fields and their test
+    // assertions - string literals today, but one quoted line away from a
+    // comment, and it resolves nowhere at this repo's root.
+    expect(extractDocCitations("recorded: qse-qguard-video/docs/motion-brand-spec.md")).toEqual([]);
+    expect(extractDocCitations("see https://remotion.dev/docs/lambda/bucket-security")).toEqual([]);
+    expect(extractDocCitations("https://github.com/acme/repo/blob/main/docs/setup/install.md")).toEqual([]);
+  });
+
+  test("does NOT invent a citation from a directory glob or a wrapped line", () => {
+    // Real shapes in this repo: a `phase-*.md` glob built at runtime, and a
+    // path broken across two comment lines. Neither is a resolvable file, and
+    // flagging them would train readers to ignore the check.
+    expect(extractDocCitations("reads docs/headless/phase-*.md")).toEqual([]);
+    expect(extractDocCitations("docs/superpowers/specs/2026-08-08-build2-\n// round2-report.md")).toEqual([]);
+  });
+
+  test("accepts a trailing-slash directory citation", () => {
+    // The prose convention says "the design doc under docs/superpowers/", so
+    // the directory form is a real citation and is resolved like any other.
+    expect(extractDocCitations("the design doc under docs/superpowers/"))
+      .toEqual(["docs/superpowers/"]);
+  });
+
+  test("deduplicates and returns stable order", () => {
+    expect(extractDocCitations("docs/plans/x.md and again docs/plans/x.md"))
+      .toEqual(["docs/plans/x.md"]);
+  });
+});
+
+describe("extractIssueCitations", () => {
+  test("finds both id families", () => {
+    expect(extractIssueCitations("bd remotion-videos-8r8 and video-toolchain-n0n"))
+      .toEqual(["remotion-videos-8r8", "video-toolchain-n0n"]);
+  });
+
+  test("finds an id in prose punctuation", () => {
+    expect(extractIssueCitations("(remotion-videos-corc, remotion-videos-b4pq)."))
+      .toEqual(["remotion-videos-b4pq", "remotion-videos-corc"]);
+  });
+
+  test("does not match a longer word that merely starts with an id", () => {
+    // This is the case the trailing \b earns its keep on: without it the regex
+    // would happily take the first four suffix characters and invent an id.
+    expect(extractIssueCitations("remotion-videos-abcdefg")).toEqual([]);
+  });
+
+  test("does not match the bare repo name", () => {
+    // Note this one passes on the {3,4} suffix requirement, NOT on \b - there
+    // is no suffix at all to bound. Kept because the bare name is everywhere in
+    // this repo's prose and a future loosening of the suffix rule must not
+    // start matching it.
+    expect(extractIssueCitations("extracted from remotion-videos on 2026-08-24")).toEqual([]);
+  });
+
+  test("resolves a child id to the parent that has the record", () => {
+    expect(extractIssueCitations("see remotion-videos-5ky3.1")).toEqual(["remotion-videos-5ky3"]);
+  });
+});
+
+describe("commentsOnly", () => {
+  test("keeps line and block comments, drops code", () => {
+    const src = [
+      'const a = "docs/not-a-citation.md";',
+      "// see docs/real/one.md",
+      "/* and docs/real/two.md */",
+    ].join("\n");
+    const got = commentsOnly(src, "a.ts");
+    expect(got).toContain("docs/real/one.md");
+    expect(got).toContain("docs/real/two.md");
+    expect(got).not.toContain("not-a-citation");
+  });
+
+  // Each literal-shape test below carries a REAL citation in a real comment and
+  // asserts it survives, alongside the literal that must not. Without that
+  // positive half a bare `not.toContain` passes just as happily on the empty
+  // string, so a commentsOnly that extracted NOTHING would have looked green.
+  // Four of these had exactly that gap when the 2026-08-26 mutation pass ran.
+
+  test("a /* inside a TEMPLATE literal does NOT open a block comment", () => {
+    // costShell.ts:115 interpolates a `/*.json` glob into an error message. The
+    // "opener must follow a delimiter" heuristic allowed it, because the slash
+    // there follows a closing brace - which reopened the whole false-open class
+    // one patch after it was supposedly closed.
+    const src = [
+      "// docs/real/keep-me.md",
+      "const msg = `${projectDir} has BOTH ${legacy} and ${dir}/*.json; counted twice.`;",
+      'const p = "docs/not-a-citation.md";',
+    ].join("\n");
+    const got = commentsOnly(src, "a.ts");
+    expect(got).toContain("docs/real/keep-me.md");
+    expect(got).not.toContain("docs/not-a-citation.md");
+  });
+
+  test("a // inside a string does NOT open a line comment", () => {
+    // joinShell.test.ts:146 writes a source file whose CONTENT carries a `//`.
+    const src = [
+      "// docs/real/keep-me.md",
+      'writeFileSync(p, "export default () => null; // gap v0\\n");',
+    ].join("\n");
+    const got = commentsOnly(src, "a.ts");
+    expect(got).toContain("docs/real/keep-me.md");
+    expect(got).not.toContain("gap v0");
+  });
+
+  test("a /* inside a string does NOT open a block comment", () => {
+    // The real shape, from joinShell.test.ts:1838: a gitignore glob written as
+    // a string literal. The naive scanner treated everything after it as
+    // comment text - 600 lines of one file, which put every string literal
+    // below back in scope and produced a false dangling-citation failure.
+    const src = [
+      "// docs/real/keep-me.md",
+      'writeFileSync(p, "**/.video/*\\n.worktrees/\\n");',
+      'expect(stray("docs/vendor-notes.txt")).toBeNull();',
+    ].join("\n");
+    const got = commentsOnly(src, "a.ts");
+    expect(got).toContain("docs/real/keep-me.md");
+    expect(got).not.toContain("docs/vendor-notes.txt");
+  });
+
+  test("a // inside a URL string does NOT open a line comment", () => {
+    const src = '// docs/real/keep-me.md\nconst u = "https://host/docs/x.md";';
+    const got = commentsOnly(src, "a.ts");
+    expect(got).toContain("docs/real/keep-me.md");
+    expect(got).not.toContain("docs/x.md");
+  });
+
+  test("a real block comment still closes on the same line", () => {
+    const src = "/* docs/a/b.md */ const x = \"docs/c/d.md\";";
+    const got = commentsOnly(src, "a.ts");
+    expect(got).toContain("docs/a/b.md");
+    expect(got).not.toContain("docs/c/d.md");
+  });
+
+  test("a generic arrow in a .ts file does not swallow the comments after it", () => {
+    // `<T>(x) => x` is ordinary TypeScript and a JSX error in TSX. The parser
+    // does not throw on it - it error-recovers, reads the `<T>` as an
+    // unterminated JSX element, and stops yielding comment ranges from there to
+    // EOF. Parsing every file as TSX cost worktreeShell.ts half its comment
+    // text and hid a live remotion-videos-b4pq citation from the guard, which
+    // is the same swallow-everything-after failure the hand-rolled scanner had.
+    const src = "const id = <T>(x: T): T => x;\n// docs/after-generic.md\n";
+    expect(commentsOnly(src, "a.ts")).toContain("docs/after-generic.md");
+  });
+
+  test("a .tsx file is still parsed as TSX", () => {
+    const src = 'const El = () => <div className="x" />;\n// docs/after-jsx.md\n';
+    expect(commentsOnly(src, "a.tsx")).toContain("docs/after-jsx.md");
+  });
+
+  test("refuses a file the parser cannot read, rather than silently seeing less", () => {
+    // The failure this whole module exists to prevent is a guard reporting
+    // clean while reading less than it claims. A parse error means exactly
+    // that, so it is raised - naming the file, because the throw happens at
+    // module scope in the caller where the path is the only clue available.
+    expect(() => commentsOnly("const a = (;", "broken.ts")).toThrow(/broken\.ts/);
+  });
+
+  test("sees a comment that is the last thing inside a block", () => {
+    // forEachChild never visits closing tokens, so a comment in the leading
+    // trivia of a `}` / `]` / `)` was invisible - 229 of them across the tree.
+    const src = "function f() {\n  go();\n  // docs/tail-of-block.md\n}\n";
+    expect(commentsOnly(src, "a.ts")).toContain("docs/tail-of-block.md");
+  });
+
+  test("sees a JSX expression-container comment", () => {
+    // {/* ... */} is the ONLY comment form available inside JSX children, and
+    // the kit and fixture trees are .tsx - so this was a blind spot over real
+    // source, not a hypothetical one.
+    const src = "const E = () => <div>{/* docs/jsx-child.md */}</div>;\n";
+    expect(commentsOnly(src, "a.tsx")).toContain("docs/jsx-child.md");
+  });
+
+  test("JSX TEXT is data: a bare // or /* in rendered text is not a comment", () => {
+    // The same bug a third time. `<div>/* x */</div>` RENDERS those characters
+    // - they are text, like a string literal - but the JSX children SyntaxList
+    // starts at the first character of the run, so the comment-range lookup
+    // read an opener there and called it a comment.
+    const line = commentsOnly("const E = () => <div>// docs/jsx-text.md</div>;\n", "a.tsx");
+    expect(line).not.toContain("docs/jsx-text.md");
+    const block = commentsOnly("const E = () => <div>/* docs/jsx-text.md */</div>;\n", "b.tsx");
+    expect(block).not.toContain("docs/jsx-text.md");
+  });
+
+  test("an unterminated /* in JSX text does not swallow the rest of the file", () => {
+    // The unbounded form, and the reason this is not merely cosmetic: the
+    // stray opener ran to EOF and dragged a string literal back into citation
+    // scope, which is precisely what the gitignore glob did to joinShell before
+    // any of this was parsed rather than scanned.
+    const src = [
+      "export const Card = () => (",
+      "  <pre>",
+      "    /* build with: npm run build",
+      "  </pre>",
+      ");",
+      "",
+      "// docs/real/keep-me.md",
+      'const cfg = { doc: "docs/this-is-a-string-literal.md" };',
+    ].join("\n");
+    const got = commentsOnly(src, "c.tsx");
+    expect(got).toContain("docs/real/keep-me.md");
+    expect(got).not.toContain("docs/this-is-a-string-literal.md");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The repo-wide guard. Everything above tests the extractors; this walks the
+// real source and holds its citations to account.
+// ---------------------------------------------------------------------------
+
+// Everything this repo authors. `scripts/` and `infra/` were left out of the
+// first version and that is where the only real dangling citation in the tree
+// turned out to live - a citation checker blind to the file it would have
+// caught is a poor advertisement for itself. Fixture trees inside these roots
+// are scanned too: a typo'd bd id in a fixture comment is the same defect as
+// one in source.
+//
+// The repo-root video projects are NOT here, and the reason is the opposite of
+// what an earlier version of this comment claimed. They cite the BARE form
+// `docs/motion-brand-spec.md`, which DOC_PATTERN matches and which does not
+// exist at this repo's root, so adding them would produce a dozen dangling
+// failures for citations that are correct relative to their own project. Doing
+// it properly means resolving a project's citations against that project's
+// root, which is a different guard from this one.
+const SOURCE_DIRS = ["packages", "scripts", "infra"];
+const SKIP = new Set(["node_modules", "dist", ".cache", ".turbo"]);
+/** Authored source, whatever the extension - `commentsOnly` picks the parser
+ *  from the file name, so .js/.mjs/.cjs/.jsx are read as themselves. */
+const SOURCE_EXT = /\.(?:m|c)?[jt]sx?$/;
+
+// Root-level config source is scanned too. vitest.config.ts carries a real bd
+// citation in a comment and sat outside every tree above, which the coverage
+// test below now makes impossible to reintroduce silently.
+
+// NOT recorded as an exception anywhere: `scripts/session-preflight.sh`
+// hard-fails unless `docs/security/act854-auth-json-remediation.md` exists, and
+// that file has never existed in this repo or upstream - so that gate has never
+// been passable. SOURCE_EXT never opens a .sh file, so this guard cannot see it
+// at all, and writing an exception for it would claim coverage the code does
+// not have. Tracked as video-toolchain-o3r, which needs a human answer about
+// token rotation before it can be closed.
+
+/** The citation module's own two files, and NOTHING ELSE - which is why this is
+ *  derived from one base name rather than written as a list.
+ *
+ *  Both hold SYNTHETIC citations (`docs/plans/b.md`, `docs/.../foo.md`) whose
+ *  whole job is to exercise the parser, and the module's doc comments name
+ *  example paths the same way - illustrations, not claims. They are fixtures
+ *  that happen to live outside a `fixtures/` directory, and scanning them would
+ *  make the guard fail on its own test data. Every OTHER file IS scanned: a
+ *  typo'd bd id in a test comment is the same defect as one in source.
+ *
+ *  A LIST HERE WAS A HOLE. SKIP_FILES is spliced into both sides of the
+ *  coverage equality below, so any entry naming a real tracked file was
+ *  invisible to it by construction: exempting 653 of 667 files kept the suite
+ *  green, and a planted dangling citation was silenced just by adding its
+ *  file's path here. That is the same unchecked-exemption defect this module
+ *  exists to catch, so the exemption is no longer a list that can be appended
+ *  to - adding a third file now means changing the shape of this code, and the
+ *  coverage test pins the count regardless. */
+const SELF = "packages/video-craft/src/sourceCitations";
+const SKIP_FILES = new Set([`${SELF}.ts`, `${SELF}.test.ts`]);
+
+/** Authored source under SOURCE_DIRS plus the repo-root config files, minus
+ *  build output and the two files above. A symlink to a DIRECTORY is refused:
+ *  `entry.isDirectory()` is false for one, so a symlinked subtree would
+ *  silently leave the walk - the same invisible under-coverage this whole file
+ *  exists to stop. A symlinked FILE is followed like any other file. */
+const sourceFiles = (): string[] => {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(join(repoRoot, dir), { withFileTypes: true })) {
+      if (SKIP.has(entry.name)) continue;
+      const rel = `${dir}/${entry.name}`;
+      if (entry.isSymbolicLink() && statSync(join(repoRoot, rel)).isDirectory()) {
+        throw new Error(
+          `${rel} is a symlinked directory; this walk does not descend into one, so its ` +
+          "source would leave the scan silently. Teach the walk to follow it (watching for " +
+          "cycles) before landing one in a scanned tree.");
+      }
+      if (entry.isDirectory()) walk(rel);
+      else if (SOURCE_EXT.test(entry.name) && !SKIP_FILES.has(rel)) out.push(rel);
+    }
+  };
+  for (const d of SOURCE_DIRS) walk(d);
+  for (const entry of readdirSync(repoRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() && SOURCE_EXT.test(entry.name) && !SKIP_FILES.has(entry.name)) {
+      out.push(entry.name);
+    }
+  }
+  return out;
+};
+
+// Comment text only: a path in a string literal is data, not a claim. The files
+// are read and parsed once here, at module scope, and the citation tests below
+// work from this array rather than re-reading them. The file name is passed
+// through so `commentsOnly` can pick the right parser for it.
+const scanned = sourceFiles().map((rel) => ({
+  rel, text: commentsOnly(readFileSync(join(repoRoot, rel), "utf8"), rel),
+}));
+
+type Scanned = { rel: string; text: string };
+
+/** Ids in a committed bd export. A missing export is a broken checkout, not a
+ *  reason to pass silently - the convention depends on it. A malformed line
+ *  names the file and the line, because a bare JSON.parse throw at module scope
+ *  points at this function and gives the reader nothing to act on. Nothing is
+ *  skipped but blank lines: a `#` line in a JSONL export is corruption, and an
+ *  entry with no `id` would otherwise put `undefined` in the set. */
+const idsFrom = (rel: string): Set<string> => {
+  const out = new Set<string>();
+  const lines = readFileSync(join(repoRoot, rel), "utf8").split("\n");
+  lines.forEach((line, i) => {
+    if (!line.trim()) return;
+    let id: unknown;
+    try {
+      ({ id } = JSON.parse(line) as { id: unknown });
+    } catch (err) {
+      throw new Error(`${rel}:${i + 1} is not valid JSON: ${(err as Error).message}`);
+    }
+    if (typeof id !== "string" || !id) throw new Error(`${rel}:${i + 1} has no string id`);
+    out.add(id);
+  });
+  return out;
+};
+
+/** Read once, not per test - several of the tests below need them. */
+const KNOWN_ISSUE_IDS = idsFrom(".beads/issues.jsonl");
+
+/**
+ * Every issue id in the upstream remotion-videos backlog, open and closed,
+ * snapshotted into this repo. See the header of the file itself for why.
+ *
+ * The short version: the migration took only the OPEN issues, so a comment
+ * citing one that was closed upstream has no local record and is still a
+ * perfectly good citation. Before this snapshot those were covered by a
+ * hand-maintained allowlist that lived in this file, alongside the citations it
+ * described - so the two tests over it only proved the two halves agreed with
+ * each other. A typo in a comment plus the same typo in the list passed green,
+ * and the failure message steered the reader straight into doing that, because
+ * "add it to the list" is the same keystroke for a real citation and a typo.
+ *
+ * What CI can and cannot see is stated on the tests themselves, below.
+ */
+const UPSTREAM_SNAPSHOT = ".beads/upstream-issue-ids.txt";
+const upstreamSnapshotIds = (): Set<string> => {
+  const out = new Set<string>();
+  readFileSync(join(repoRoot, UPSTREAM_SNAPSHOT), "utf8").split("\n").forEach((line, i) => {
+    const id = line.trim();
+    if (!id || id.startsWith("#")) return;
+    if (/\s/.test(id)) throw new Error(`${UPSTREAM_SNAPSHOT}:${i + 1} is not a bare id: ${id}`);
+    out.add(id);
+  });
+  return out;
+};
+const UPSTREAM_ISSUE_IDS = upstreamSnapshotIds();
+
+/**
+ * Case-EXACT existence, resolved one path segment at a time.
+ *
+ * `existsSync` answers on the filesystem's terms: APFS is case-insensitive, so
+ * a comment citing `docs/Accounting.md` resolves on the author's Mac and fails
+ * on a Linux CI runner. readdirSync returns the true on-disk casing, so
+ * comparing against it checks what Linux will check. Unit-tested below against
+ * real repo paths - a mutation pass found that reverting this to existsSync was
+ * otherwise undetectable, since the repo-wide test only ever exercises it in
+ * the direction that passes.
+ */
+const existsCaseExact = (cited: string): boolean => {
+  let dir = repoRoot;
+  for (const segment of cited.split("/").filter(Boolean)) {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return false;
+    }
+    if (!entries.includes(segment)) return false;
+    dir = join(dir, segment);
+  }
+  return true;
+};
+
+/** Files in one scanned tree or package, by path prefix. */
+const under = (prefix: string): Scanned[] => scanned.filter((f) => f.rel.startsWith(prefix));
+
+const countDocs = (files: Scanned[]): number =>
+  files.flatMap((f) => extractDocCitations(f.text)).length;
+const countIds = (files: Scanned[]): number =>
+  files.flatMap((f) => extractIssueCitations(f.text)).length;
+
+// The three checks, as functions over an arbitrary file list rather than
+// straight-line code over `scanned`. Each is run twice below: once against the
+// real tree expecting nothing, and once against a synthetic file KNOWN to be
+// bad. Without that second call, deleting the body of a check leaves an empty
+// `missing` array and the test passes - a mutation pass proved both id checks
+// could be removed outright with the suite still green.
+const danglingDocs = (files: Scanned[]): string[] => {
+  const out: string[] = [];
+  for (const { rel, text } of files) {
+    for (const cited of extractDocCitations(text)) {
+      if (!existsCaseExact(cited)) out.push(`${rel} -> ${cited}`);
+    }
+  }
+  return out;
+};
+
+const unresolvedLocalIds = (files: Scanned[]): string[] => {
+  const out: string[] = [];
+  for (const { rel, text } of files) {
+    for (const id of extractIssueCitations(text)) {
+      if (!isUpstreamIssue(id) && !KNOWN_ISSUE_IDS.has(id)) out.push(`${rel} -> ${id}`);
+    }
+  }
+  return out;
+};
+
+const unresolvedUpstreamIds = (files: Scanned[]): string[] => {
+  const out: string[] = [];
+  for (const { rel, text } of files) {
+    for (const id of extractIssueCitations(text)) {
+      if (!isUpstreamIssue(id)) continue;
+      if (!KNOWN_ISSUE_IDS.has(id) && !UPSTREAM_ISSUE_IDS.has(id)) {
+        out.push(
+          `${rel} -> ${id} (not in .beads/issues.jsonl, not in ${UPSTREAM_SNAPSHOT}; ` +
+          "if this id is real, refresh the snapshot from a remotion-videos checkout - " +
+          "see that file's header - rather than adding the id by hand)");
+      }
+    }
+  }
+  return out;
+};
+
+/** A file that is definitely not in the tree, for the positive controls. */
+const SYNTHETIC_BAD: Scanned[] = [{
+  rel: "synthetic-control.ts",
+  text: "// docs/definitely-not-a-real-doc.md and remotion-videos-zzz9 and video-toolchain-zzz9",
+}];
+
+/**
+ * The source files git knows about, which is where the coverage floor comes
+ * from. Deliberately NOT filtered by SKIP: build output and node_modules are
+ * gitignored, so git never lists them, and taking the expected set from a
+ * source the walk does not control is the whole point.
+ *
+ * A floor derived from the same exclusion list as the walk is not a floor. Two
+ * rounds of this file learned that the hard way - first the package list came
+ * from SKIP, then its replacement was itself unasserted, so returning a single
+ * package dropped 615 of 668 files with every test still green.
+ */
+const trackedSourceFiles = (): string[] =>
+  execFileSync("git", ["ls-files", "-z"], { cwd: repoRoot, encoding: "utf8", maxBuffer: 64 << 20 })
+    .split("\0")
+    .filter((p) => p && SOURCE_EXT.test(p))
+    .filter((p) => SOURCE_DIRS.some((d) => p.startsWith(`${d}/`)) || !p.includes("/"))
+    .sort();
+
+/** Workspace packages, from the workspace definition. */
+const workspacePackages = (): string[] => {
+  const globs = (JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")) as
+    { workspaces?: string[] }).workspaces ?? [];
+  const out: string[] = [];
+  for (const glob of globs) {
+    const [root, star] = glob.split("/");
+    if (!root || star !== "*") throw new Error(`unsupported workspace glob: ${glob}`);
+    for (const entry of readdirSync(join(repoRoot, root), { withFileTypes: true })) {
+      if (entry.isDirectory() && existsSync(join(repoRoot, root, entry.name, "package.json"))) {
+        out.push(`${root}/${entry.name}`);
+      }
+    }
+  }
+  return out;
+};
+
+/** Packages that legitimately carry neither kind of citation. NAMED, because an
+ *  exemption should be a claim someone made on purpose - and checked, below, so
+ *  it cannot quietly grow to cover everything. */
+const NO_CITATIONS = new Set(["packages/design-systems"]);
+
+describe("the scan covers what it claims to", () => {
+  test("the git file list has not collapsed", () => {
+    // trackedSourceFiles() is the expected side of the equality below, so a
+    // collapsed or truncated list would quietly shrink the floor. Hard
+    // thresholds, deliberately far below any real value, not a census.
+    //
+    // WHAT THIS CANNOT PROVE: that the list came from git. A mutation returning
+    // the walked set instead passes every assertion here, because the invented
+    // list is the same files. The obvious cross-check - `git ls-tree -r HEAD`
+    // against `git ls-files` - was rejected on purpose: ls-tree reads the
+    // commit and ls-files reads the index, so it would fail for anyone holding
+    // an uncommitted source file, and a floor that fires during ordinary work
+    // gets deleted. Rewriting this helper to launder the walk is self-sabotage
+    // of the same order as deleting the assertion, which no test defends
+    // against; it is recorded here rather than papered over.
+    const tracked = trackedSourceFiles();
+    expect(tracked.length).toBeGreaterThan(600);
+    expect(tracked).toContain("vitest.config.ts");
+    expect(tracked).toContain("packages/video-cli/src/cli.ts");
+    expect(tracked).toContain(`${SELF}.ts`);
+  });
+
+  test("every tracked source file is scanned, and nothing else is", () => {
+    // The floor that makes the rest meaningful, and the one that cannot be
+    // widened by editing what it checks: git's file list does not care what
+    // SKIP, SOURCE_DIRS or workspacePackages() say. Adding a directory name to
+    // SKIP, dropping a tree, or returning fewer packages all show up here as a
+    // concrete list of files that stopped being scanned.
+    //
+    // SKIP_FILES is the exception, because it appears on both sides - so it is
+    // pinned to exactly the citation module's own two files, which is the only
+    // exemption this guard is entitled to.
+    expect([...SKIP_FILES].sort()).toEqual([`${SELF}.test.ts`, `${SELF}.ts`].sort());
+    for (const skipped of SKIP_FILES) {
+      expect(trackedSourceFiles(), `${skipped} is exempted but not a tracked file`)
+        .toContain(skipped);
+    }
+    const walked = [...scanned.map((f) => f.rel), ...SKIP_FILES].sort();
+    expect(walked).toEqual(trackedSourceFiles());
+  });
+
+  test("the corpus the citation checks run over has not collapsed", () => {
+    // The checks below take a file list, so a truncated corpus would make them
+    // pass over nothing. Hard floors with headroom, deliberately not a census.
+    //
+    // What this does NOT defend: a call site edited to pass a slice. Nothing
+    // can - that is indistinguishable from deleting the assertion, and no test
+    // defends against its own removal.
+    expect(scanned.length).toBeGreaterThan(600);
+    expect(countDocs(scanned)).toBeGreaterThan(40);
+    expect(countIds(scanned)).toBeGreaterThan(150);
+  });
+
+  test("the workspace package list is the one git sees on disk", () => {
+    // workspacePackages() no longer shares an input with the walk, but nothing
+    // asserted it was COMPLETE: `return out.slice(0, 1)` was green, and it kept
+    // design-systems - the one package the citation floor exempts - so every
+    // per-package check collapsed to "one package has at least one file".
+    const fromGit = [...new Set(
+      trackedSourceFiles()
+        .filter((p) => p.startsWith("packages/"))
+        .map((p) => p.split("/").slice(0, 2).join("/")))].sort();
+    expect(workspacePackages().sort()).toEqual(fromGit);
+  });
+
+  test("every scanned tree and every workspace package is actually reached", () => {
+    for (const dir of SOURCE_DIRS) {
+      expect(under(`${dir}/`).length, `no files scanned under ${dir}/`).toBeGreaterThan(0);
+    }
+    for (const pkg of workspacePackages()) {
+      expect(under(`${pkg}/`).length, `no files scanned in ${pkg}`).toBeGreaterThan(0);
+    }
+  });
+
+  test("each kind of citation is floored separately, per package", () => {
+    // Summing doc and id citations reproduced inside each package the very
+    // residual the per-package split was meant to remove: id citations alone
+    // clear a combined floor everywhere, so extractDocCitations could return
+    // [] for the entire repo and this test would still pass. Floor them apart.
+    for (const pkg of workspacePackages()) {
+      if (NO_CITATIONS.has(pkg)) continue;
+      const files = under(`${pkg}/`);
+      expect(countDocs(files), `${pkg} yielded no docs/ citations`).toBeGreaterThan(0);
+      expect(countIds(files), `${pkg} yielded no bd id citations`).toBeGreaterThan(0);
+    }
+  });
+
+  test("the citation exemption covers only packages that really cite nothing", () => {
+    // Otherwise the exemption is the escape hatch: adding every package to it
+    // turns the floor above into a no-op, silently.
+    for (const pkg of NO_CITATIONS) {
+      const files = under(`${pkg}/`);
+      expect(countDocs(files) + countIds(files),
+        `${pkg} is exempted but does cite things - drop it from NO_CITATIONS`).toBe(0);
+    }
+  });
+
+  test("the trees outside packages/ carry citations of their own", () => {
+    // NAMED HERE, deliberately not derived from SOURCE_DIRS. The first version
+    // of this test iterated SOURCE_DIRS.filter(d => d !== "packages"), so
+    // deleting a tree from SOURCE_DIRS also deleted its own floor: the mutation
+    // "scripts/ dropped from the walk" passed green. That is the circularity
+    // the workspacePackages() comment above describes, written into the fix
+    // for it, and only a mutation pass over this file surfaced it.
+    // Floored APART, like the packages above. A summed floor here was blind to
+    // narrowing SOURCE_EXT to drop .mjs: that deletes 100% of infra/'s docs
+    // coverage (both docs/accounting.md citations are in .mjs) and scripts/'s
+    // only docs citation, while each tree keeps one .ts id citation and clears
+    // a combined count. Same residual as the packages floor had, one tree over.
+    for (const dir of ["scripts", "infra"]) {
+      expect(SOURCE_DIRS, `${dir}/ is no longer walked at all`).toContain(dir);
+      const files = under(`${dir}/`);
+      expect(countDocs(files), `${dir}/ yielded no docs/ citations`).toBeGreaterThan(0);
+      expect(countIds(files), `${dir}/ yielded no bd id citations`).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("existsCaseExact", () => {
+  test("resolves a real path, and rejects the same path in the wrong case", () => {
+    // The whole point: existsSync says true to both of these on APFS, and the
+    // second one is a red CI run on Linux.
+    expect(existsCaseExact("docs/accounting.md")).toBe(true);
+    expect(existsCaseExact("docs/Accounting.md")).toBe(false);
+    expect(existsCaseExact("DOCS/accounting.md")).toBe(false);
+  });
+
+  test("checks INTERMEDIATE segments, not just the file name", () => {
+    expect(existsCaseExact("docs/superpowers/")).toBe(true);
+    expect(existsCaseExact("docs/Superpowers/")).toBe(false);
+  });
+
+  test("rejects a path that is not there at all", () => {
+    expect(existsCaseExact("docs/definitely-not-a-real-doc.md")).toBe(false);
+    expect(existsCaseExact("docs/accounting.md/nested")).toBe(false);
+  });
+});
+
+describe("source comments cite things that exist", () => {
+  test("every docs/ path cited in a source comment resolves on disk", () => {
+    // The 2026-08-25 extraction left ten of these dangling. They were fixed by
+    // hand and nothing was left behind to stop it recurring; this is it.
+    expect(danglingDocs(scanned)).toEqual([]);
+    expect(danglingDocs(SYNTHETIC_BAD), "the check itself stopped working").toHaveLength(1);
+  });
+
+  test("every video-toolchain- issue cited in source exists in this repo's DB", () => {
+    // This repo's own ids have no upstream excuse.
+    //
+    // NO LONGER VACUOUS, and the transition is worth recording. This check
+    // spent its whole life with nothing real to check - every id in the corpus
+    // was a remotion-videos- one, and the synthetic control below was the only
+    // thing exercising it. video-toolchain-h6e was the first change to cite a
+    // local id from scanned comments, and this test caught it immediately:
+    // `bd create` writes the live DB, `.beads/issues.jsonl` is a committed
+    // EXPORT of it, and the id resolves only once someone runs `bd export`. So
+    // the failure mode it now guards, in the words it shows up in, is
+    // "<file> -> video-toolchain-<id> (not in .beads/issues.jsonl ...)" on a
+    // freshly filed issue, and the fix is the export, not the comment.
+    expect(unresolvedLocalIds(scanned)).toEqual([]);
+    expect(unresolvedLocalIds(SYNTHETIC_BAD), "the check itself stopped working").toHaveLength(1);
+  });
+
+  test("every remotion-videos- issue cited in source exists, here or in the snapshot", () => {
+    // Runs in CI with no upstream checkout, because the upstream ids are
+    // snapshotted in the repo. This replaced a tautology: the old version
+    // asserted the id matched /^remotion-videos-[a-z0-9]{3,4}$/, which
+    // extractIssueCitations guarantees by construction, so it could not fail -
+    // over exactly the ids that no other tier verified.
+    //
+    // What this does NOT prove: that the snapshot itself is honest. In CI the
+    // evidence for those ids is a text file in this same repo, so a typo added
+    // to a comment AND to the snapshot passes here. The drift test below is
+    // what catches that, and it needs the sibling checkout.
+    expect(unresolvedUpstreamIds(scanned)).toEqual([]);
+    expect(unresolvedUpstreamIds(SYNTHETIC_BAD), "the check itself stopped working")
+      .toHaveLength(1);
+  });
+
+  test("the snapshot is a well-formed export of bare ids", () => {
+    // Shape only - it catches a truncated or corrupted file, which would
+    // otherwise surface as a pile of "citation does not exist" failures
+    // pointing at comments that are perfectly fine. It does NOT detect a
+    // plausible hand-added id; only the drift test does, so this test is named
+    // for what it checks rather than for what one might hope it checks.
+    expect(UPSTREAM_ISSUE_IDS.size).toBeGreaterThan(300);
+    const malformed = [...UPSTREAM_ISSUE_IDS]
+      // `.1` suffixes are real: bd child issues appear in the export under
+      // their parent's id, and extractIssueCitations resolves a cited child to
+      // that parent, so both forms have to survive.
+      .filter((id) => !/^remotion-videos-[a-z0-9]+(?:\.\d+)?$/.test(id));
+    expect(malformed).toEqual([]);
+  });
+
+  // Drift tier. The snapshot is what CI checks against; this is what proves the
+  // snapshot still matches reality, and it needs the other repo on disk. It
+  // SKIPS rather than passes when absent, so the weaker coverage is visible in
+  // the run instead of silent. Nothing in .github/workflows sets
+  // REMOTION_VIDEOS_ROOT, so in CI this never runs - which is exactly why the
+  // test above says out loud what it cannot prove. Gated the same way as the
+  // upstream tier in packages/video-cli/src/radar/corpus.test.ts.
+  const upstreamDb = process.env.REMOTION_VIDEOS_ROOT
+    ? join(process.env.REMOTION_VIDEOS_ROOT, ".beads/issues.jsonl") : "";
+  const haveUpstream = Boolean(upstreamDb && existsSync(upstreamDb));
+
+  test.skipIf(!haveUpstream)("the upstream id snapshot has not drifted", () => {
+    const live = new Set(
+      readFileSync(upstreamDb, "utf8").split("\n").filter((l) => l.trim())
+        .map((l) => (JSON.parse(l) as { id: string }).id));
+    // An id in the snapshot but NOT upstream means the snapshot was hand-edited
+    // or the id was deleted, and either way the CI check above is trusting a
+    // fiction. The other direction - upstream gaining issues - is normal and
+    // does not invalidate anything already snapshotted, so it is not checked
+    // here and the snapshot may legitimately be stale in that sense.
+    const fabricated = [...UPSTREAM_ISSUE_IDS].filter((id) => !live.has(id));
+    expect(fabricated).toEqual([]);
+  });
+});