@cosmicdrift/kumiko-guards 0.377.0 → 0.379.0

package/src/guard-direct-entity-writes.ts

@@ -18,6 +18,11 @@
  *         (dash vs. underscore) but share the `ent` symbol. Plus an explicit
  *         `backingTable` override. Tables that are NOT statically resolvable
  *         are skipped (a miss is preferable to a false block).
+ *      c) Tables of external packages (node_modules, workspace links), read from the
+ *         `kumiko-es-tables.json` catalog each published package ships; a package whose
+ *         sources live in the checked repo must keep that catalog current (checked here,
+ *         rewritten with `--write-baseline --guard=<name>`).
+ *      d) `r.projection({ table })` tables: event-fed read models, only the apply may write.
  *
  *   2. **Find direct writes.** Two forms:
  *      - Method form `<receiver>.insert(<tableIdent>)` / `.update` / `.delete`.
@@ -46,13 +51,21 @@
 import * as path from "node:path";
 import {
   type CallExpression,
+  type FileSystemHost,
   type Identifier,
   Node,
   type ObjectLiteralExpression,
+  type Project,
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
-import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  isExternalSourcePath,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
 
 const ROOT = process.cwd();
 
@@ -95,46 +108,6 @@ const FN_WRITE_HELPERS = new Map<string, "insert" | "update" | "delete">([
   ["deleteManyBatched", "delete"],
 ]);
 
-// Writes that are deliberately outside the event-store executor. Match on file + enclosing function + table so the exception cannot widen silently.
-type DirectWriteException = {
-  readonly file: RegExp;
-  readonly functionName: string;
-  readonly table: string;
-  readonly justification: string;
-};
-
-const DIRECT_WRITE_EXCEPTIONS: readonly DirectWriteException[] = [
-  {
-    file: /(^|\/)packages\/bundled-features\/src\/template-resolver\/seeding\.ts$/,
-    functionName: "resolveExistingForEventStoreSeed",
-    table: "templateResourcesTable",
-    justification: "Orphan projection row without events, no event-store verb possible",
-  },
-];
-
-// First named container: `function f`, `const f = () =>`, or `run: () =>` in an object literal.
-function enclosingFunctionName(node: Node): string | undefined {
-  for (const ancestor of node.getAncestors()) {
-    if (Node.isFunctionDeclaration(ancestor)) return ancestor.getName();
-    if (Node.isVariableDeclaration(ancestor) || Node.isPropertyAssignment(ancestor)) {
-      return ancestor.getName();
-    }
-  }
-  return undefined;
-}
-
-function isDirectWriteException(call: CallExpression, table: string): boolean {
-  const functionName = enclosingFunctionName(call);
-  if (functionName === undefined) return false;
-  const file = call.getSourceFile().getFilePath();
-  return DIRECT_WRITE_EXCEPTIONS.some(
-    (exception) =>
-      exception.file.test(file) &&
-      exception.functionName === functionName &&
-      exception.table === table,
-  );
-}
-
 // `table as EntityTableMeta`, `(table)`, `table!`, `<T>table`, `table satisfies T` all name the same table.
 export function unwrapTableExpression(node: Node): Node {
   let current = node;
@@ -156,21 +129,26 @@ export function unwrapTableExpression(node: Node): Node {
 // declaration disambiguates them.
 type TableId = string; // "${filePath}::${name}"
 
-function declIdOf(id: import("ts-morph").Identifier): TableId | undefined {
+function declIdOf(id: Identifier): TableId | undefined {
   const symbol = id.getSymbol();
   if (!symbol) return undefined;
-  const decls = symbol.getDeclarations();
+  // An imported identifier's own declaration is the ImportSpecifier; follow the alias
+  // chain (barrels, renames) so the ID matches the one built at the definition.
+  const resolved = symbol.isAlias() ? (symbol.getAliasedSymbol() ?? symbol) : symbol;
+  const decls = resolved.getDeclarations();
   if (decls.length === 0) return undefined;
   // Param-only symbols are factory pass-throughs — skip.
   if (decls.every((d) => d.getKind() === SyntaxKind.Parameter)) return undefined;
   const first = decls[0];
   if (!first) return undefined;
-  return `${first.getSourceFile().getFilePath()}::${id.getText()}`;
+  const name = Node.hasName(first) ? first.getName() : id.getText();
+  return `${first.getSourceFile().getFilePath()}::${name}`;
 }
 
 export function collectEsTables(files: readonly SourceFile[]): Set<TableId> {
   const tables = new Set<TableId>();
   for (const sf of files) {
+    if (!sf.getFullText().includes("createEventStoreExecutor")) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const expr = call.getExpression();
       if (expr.getText() !== "createEventStoreExecutor") continue;
@@ -251,6 +229,8 @@ function rebuildableEntityTableDeclId(
   return declIdOf(nameNode.asKindOrThrow(SyntaxKind.Identifier));
 }
 
+const ENTITY_METHOD_ACCESS = /\.\s*entity\b/;
+
 // Tables registered via `r.entity({ name, ...entityDef })` as a rebuildable implicit
 // projection, linked entity→table via the shared entity-def symbol (see header), not by name string.
 export function collectEntityProjectionTables(files: readonly SourceFile[]): Set<TableId> {
@@ -259,6 +239,7 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
 
   // Pass 1: entity-def decls that r.entity makes rebuildable (+ {table} override).
   for (const sf of files) {
+    if (!ENTITY_METHOD_ACCESS.test(sf.getFullText())) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const registration = entityRegistrationOf(call);
       if (!registration) continue;
@@ -270,6 +251,7 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
   // Pass 2: `const xTable = buildEntityTable(<name>, <entityDef>)` where entityDef
   // is in the rebuildable set → xTable is a rebuildable entity table.
   for (const sf of files) {
+    if (!sf.getFullText().includes("buildEntityTable")) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const did = rebuildableEntityTableDeclId(call, rebuildableEntities);
       if (did) tables.add(did);
@@ -279,6 +261,39 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
   return tables;
 }
 
+const PROJECTION_METHOD_ACCESS = /\.\s*projection\b/;
+
+// The `table` of `r.projection({ table, apply })`: an event-fed read model, so only its apply
+// (tx receiver) may write it. Shorthand `{ table }` is a name-only reference to the same symbol.
+export function collectProjectionTables(files: readonly SourceFile[]): Set<TableId> {
+  const tables = new Set<TableId>();
+  for (const sf of files) {
+    if (!PROJECTION_METHOD_ACCESS.test(sf.getFullText())) continue;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const callee = call.getExpression().asKind(SyntaxKind.PropertyAccessExpression);
+      if (callee?.getName() !== "projection") continue;
+      const definition = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+      const property = definition?.getProperty("table");
+      const identifier =
+        property?.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getNameNode() ??
+        unwrapTableExpression(
+          property?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer() ?? call,
+        ).asKind(SyntaxKind.Identifier);
+      const did = identifier && declIdOf(identifier);
+      if (did) tables.add(did);
+    }
+  }
+  return tables;
+}
+
+function collectScopeEsTables(files: readonly SourceFile[]): Set<TableId> {
+  return new Set<TableId>([
+    ...collectEsTables(files),
+    ...collectEntityProjectionTables(files),
+    ...collectProjectionTables(files),
+  ]);
+}
+
 type Violation = {
   file: string;
   line: number;
@@ -427,14 +442,246 @@ function hasAnyTableWriteOrDeclaration(files: readonly SourceFile[]): boolean {
   return false;
 }
 
+// A TableId ends in `::<identifier text>`, so a table argument whose text is no ES table name
+// can never match; filtering on the name avoids a symbol lookup (TS program build) per call.
+function tableNamesOf(tableIds: ReadonlySet<TableId>): Set<string> {
+  return new Set([...tableIds].map((tableId) => tableId.slice(tableId.lastIndexOf("::") + 2)));
+}
+
+// Local names an import can give a table in this file (`import { a as b }` -> b). Syntactic,
+// so a rename or barrel re-export never hides an ES table from the name prefilter.
+function importedBindingNames(sf: SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const declaration of sf.getImportDeclarations()) {
+    const defaultName = declaration.getDefaultImport()?.getText();
+    if (defaultName) names.add(defaultName);
+    for (const specifier of declaration.getNamedImports()) {
+      names.add(specifier.getAliasNode()?.getText() ?? specifier.getName());
+    }
+  }
+  return names;
+}
+
+const ES_TABLE_CATALOG_FILE = "kumiko-es-tables.json";
+
+type CatalogEntry = { readonly module: string; readonly export: string };
+
+function tableIdFilePath(tableId: TableId): string {
+  return tableId.slice(0, tableId.lastIndexOf("::"));
+}
+
+function tableIdName(tableId: TableId): string {
+  return tableId.slice(tableId.lastIndexOf("::") + 2);
+}
+
+function packageRootOf(host: FileSystemHost, filePath: string): string | undefined {
+  let dir = path.dirname(filePath);
+  while (dir !== path.dirname(dir)) {
+    if (host.fileExistsSync(path.join(dir, "package.json"))) return dir;
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+// Source (`src/x.ts`, workspace link) and published (`dist/x.d.ts`) layouts must yield one key.
+function moduleOf(packageRoot: string, filePath: string): string {
+  return path
+    .relative(packageRoot, filePath)
+    .split(path.sep)
+    .join("/")
+    .replace(/^(src|dist)\//, "")
+    .replace(/\.d\.ts$|\.(ts|tsx|js)$/, "");
+}
+
+function catalogKey(module: string, exportName: string): string {
+  return `${module}::${exportName}`;
+}
+
+function isCatalogEntry(value: unknown): value is CatalogEntry {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "module" in value &&
+    "export" in value &&
+    typeof value.module === "string" &&
+    typeof value.export === "string"
+  );
+}
+
+function parseCatalog(text: string): CatalogEntry[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return Array.isArray(parsed) && parsed.every(isCatalogEntry) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readCatalogKeys(host: FileSystemHost, packageRoot: string): Set<string> {
+  const catalogPath = path.join(packageRoot, ES_TABLE_CATALOG_FILE);
+  if (!host.fileExistsSync(catalogPath)) return new Set();
+  const entries = parseCatalog(host.readFileSync(catalogPath)) ?? [];
+  return new Set(entries.map((entry) => catalogKey(entry.module, entry.export)));
+}
+
+export type ExternalEsTables = { has(tableId: TableId): boolean };
+
+// A published package ships `kumiko-es-tables.json` (module + export of its ES tables), because
+// its sources are not on disk in a consumer (only dist/*.d.ts). Missing catalog: no ES tables.
+export function createExternalEsTables(project: Project): ExternalEsTables {
+  const host = project.getFileSystem();
+  const keysByPackageRoot = new Map<string, ReadonlySet<string>>();
+  return {
+    has(tableId) {
+      const filePath = tableIdFilePath(tableId);
+      const root = packageRootOf(host, filePath);
+      if (root === undefined) return false;
+      let keys = keysByPackageRoot.get(root);
+      if (!keys) {
+        keys = readCatalogKeys(host, root);
+        keysByPackageRoot.set(root, keys);
+      }
+      return keys.has(catalogKey(moduleOf(root, filePath), tableIdName(tableId)));
+    },
+  };
+}
+
+function isPublishedPackage(host: FileSystemHost, packageRoot: string): boolean {
+  try {
+    const manifest: unknown = JSON.parse(host.readFileSync(path.join(packageRoot, "package.json")));
+    return !(
+      typeof manifest === "object" &&
+      manifest !== null &&
+      "private" in manifest &&
+      manifest.private === true
+    );
+  } catch {
+    return false;
+  }
+}
+
+// Owner side: the exported scope ES tables of every published package, grouped by package root.
+function deriveCatalogs(
+  files: readonly SourceFile[],
+  esTables: ReadonlySet<TableId>,
+): Map<string, CatalogEntry[]> {
+  const catalogs = new Map<string, CatalogEntry[]>();
+  const firstFile = files[0];
+  if (!firstFile) return catalogs;
+  const project = firstFile.getProject();
+  const host = project.getFileSystem();
+  const scopePaths = new Set<string>(files.map((file) => file.getFilePath()));
+  const publishedByRoot = new Map<string, boolean>();
+  for (const tableId of esTables) {
+    const filePath = tableIdFilePath(tableId);
+    if (!scopePaths.has(filePath) || EXCLUDE.test(filePath)) continue;
+    const name = tableIdName(tableId);
+    if (!project.getSourceFile(filePath)?.getVariableDeclaration(name)?.isExported()) continue;
+    const root = packageRootOf(host, filePath);
+    if (root === undefined) continue;
+    let published = publishedByRoot.get(root);
+    if (published === undefined) {
+      published = isPublishedPackage(host, root);
+      publishedByRoot.set(root, published);
+    }
+    if (!published) continue;
+    const entries = catalogs.get(root) ?? [];
+    entries.push({ module: moduleOf(root, filePath), export: name });
+    catalogs.set(root, entries);
+  }
+  for (const [root, entries] of catalogs) {
+    entries.sort(
+      (a, b) => a.module.localeCompare(b.module, "en") || a.export.localeCompare(b.export, "en"),
+    );
+    catalogs.set(root, [
+      ...new Map(entries.map((e) => [catalogKey(e.module, e.export), e])).values(),
+    ]);
+  }
+  return catalogs;
+}
+
+const REWRITE_CATALOGS_COMMAND =
+  'bun packages/guards/src/run-guards.ts --write-baseline --guard="Direct-Entity-Writes Guard"';
+
+// Published packages whose catalog exists on disk although they define no ES table any more.
+function publishedRootsWithCatalog(files: readonly SourceFile[]): Set<string> {
+  const roots = new Set<string>();
+  const firstFile = files[0];
+  if (!firstFile) return roots;
+  const host = firstFile.getProject().getFileSystem();
+  const rootByDir = new Map<string, string | undefined>();
+  for (const sf of files) {
+    const dir = path.dirname(sf.getFilePath());
+    if (!rootByDir.has(dir)) rootByDir.set(dir, packageRootOf(host, dir));
+    const root = rootByDir.get(dir);
+    if (root !== undefined && host.fileExistsSync(path.join(root, ES_TABLE_CATALOG_FILE))) {
+      roots.add(root);
+    }
+  }
+  return roots;
+}
+
+function catalogViolations(
+  files: readonly SourceFile[],
+  esTables: ReadonlySet<TableId>,
+): { file: string; line: number; message: string; neverFrozen: boolean }[] {
+  const firstFile = files[0];
+  if (!firstFile) return [];
+  const host = firstFile.getProject().getFileSystem();
+  const expected = deriveCatalogs(files, esTables);
+  const roots = new Set([...expected.keys(), ...publishedRootsWithCatalog(files)]);
+  const violations: { file: string; line: number; message: string; neverFrozen: boolean }[] = [];
+  for (const root of roots) {
+    const wanted = new Set((expected.get(root) ?? []).map((e) => catalogKey(e.module, e.export)));
+    const actual = readCatalogKeys(host, root);
+    const missing = [...wanted].filter((key) => !actual.has(key));
+    const surplus = [...actual].filter((key) => !wanted.has(key));
+    if (missing.length === 0 && surplus.length === 0) continue;
+    const catalogPath = path.join(root, ES_TABLE_CATALOG_FILE);
+    const detail = [
+      missing.length > 0 ? `missing: ${missing.join(", ")}` : "",
+      surplus.length > 0 ? `surplus: ${surplus.join(", ")}` : "",
+    ]
+      .filter(Boolean)
+      .join("; ");
+    violations.push({
+      file: path.relative(ROOT, catalogPath),
+      line: 0,
+      message: `ES table catalog out of date (${detail}). Rewrite it: ${REWRITE_CATALOGS_COMMAND}`,
+      neverFrozen: true,
+    });
+  }
+  return violations;
+}
+
+function writeCatalogs(files: readonly SourceFile[], esTables: ReadonlySet<TableId>): void {
+  const firstFile = files[0];
+  if (!firstFile) throw new Error("No scanned files: refusing to rewrite ES table catalogs");
+  const host = firstFile.getProject().getFileSystem();
+  const expected = deriveCatalogs(files, esTables);
+  for (const root of publishedRootsWithCatalog(files)) {
+    if (!expected.has(root)) host.deleteSync(path.join(root, ES_TABLE_CATALOG_FILE));
+  }
+  for (const [root, entries] of expected) {
+    host.writeFileSync(
+      path.join(root, ES_TABLE_CATALOG_FILE),
+      `${JSON.stringify(entries, null, 2)}\n`,
+    );
+  }
+}
+
 export function scanDirectWrites(
   sf: SourceFile,
   esTables: ReadonlySet<TableId>,
+  externalEsTables: ExternalEsTables = createExternalEsTables(sf.getProject()),
 ): Omit<Violation, "file">[] {
   const out: Omit<Violation, "file">[] = [];
+  // Superset of every name a write may use for an ES table: definition names plus import bindings.
+  const candidateNames = new Set([...tableNamesOf(esTables), ...importedBindingNames(sf)]);
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const w = resolveWrite(call);
     if (!w) continue;
+    if (!candidateNames.has(w.tableArg.getText())) continue;
 
     // Walk the receiver chain down to its leftmost identifier. For `db.insert`
     // that's `db`; for `ctx.db.raw` (function-form arg0) that's `ctx`; for
@@ -446,8 +693,10 @@ export function scanDirectWrites(
     const receiverName = receiver.getText();
 
     const did = declIdOf(w.tableArg);
-    if (!did || !esTables.has(did)) continue;
-    if (isDirectWriteException(call, w.tableArg.getText())) continue;
+    if (!did) continue;
+    if (!esTables.has(did)) {
+      if (!isExternalSourcePath(tableIdFilePath(did)) || !externalEsTables.has(did)) continue;
+    }
 
     if (TX_RECEIVER_NAMES.has(receiverName)) {
       // A tx receiver is only legitimate when the write actually sits
@@ -457,7 +706,7 @@ export function scanDirectWrites(
       if (isInsideProjectionApply(call)) continue;
       out.push({
         line: call.getStartLineNumber(),
-        receiver: receiverName,
+        receiver: w.receiver.getText(),
         op: w.op,
         table: w.tableArg.getText(),
         snippet: call.getText().slice(0, 120),
@@ -468,7 +717,7 @@ export function scanDirectWrites(
 
     out.push({
       line: call.getStartLineNumber(),
-      receiver: receiverName,
+      receiver: w.receiver.getText(),
       op: w.op,
       table: w.tableArg.getText(),
       snippet: call.getText().slice(0, 120),
@@ -486,14 +735,9 @@ export const guard: AstGuard = {
     "Write ES-entity tables through the entity write handlers / event-store executor or inside an r.projection apply (tx receiver); a direct insert/update/delete lets the projection row drift from the event stream. " +
     "For a BLOCKED scan, check that the scan still covers the files declaring r.entity / createEventStoreExecutor.",
   run(files) {
-    // Merge both collections BEFORE the empty-set check — otherwise a repo
-    // that only uses r.entity (no createEventStoreExecutor anymore) would
-    // skip every scan: the canary violation fires falsely, and writes on
-    // entity tables go undetected.
-    const esTables = new Set<TableId>([
-      ...collectEsTables(files),
-      ...collectEntityProjectionTables(files),
-    ]);
+    // Merge all collections BEFORE the empty-set check — otherwise a repo that only uses r.entity
+    // would skip every scan: the canary fires falsely and writes on entity tables go undetected.
+    const esTables = collectScopeEsTables(files);
     if (esTables.size === 0) {
       // An empty set means either the repo has no event store at all, or the
       // scan lost the ES definitions while table writes are still present.
@@ -510,13 +754,23 @@ export const guard: AstGuard = {
       };
     }
 
-    const violations: Array<{ file: string; line: number; message: string }> = [];
+    const violations: Array<{
+      file: string;
+      line: number;
+      message: string;
+      neverFrozen?: boolean;
+    }> = catalogViolations(files, esTables);
+
+    const firstFile = files[0];
+    const externalEsTables = firstFile
+      ? createExternalEsTables(firstFile.getProject())
+      : { has: () => false };
 
     for (const sf of files) {
       const file = sf.getFilePath();
       if (EXCLUDE.test(file)) continue;
 
-      for (const hit of scanDirectWrites(sf, esTables)) {
+      for (const hit of scanDirectWrites(sf, esTables, externalEsTables)) {
         violations.push({
           file: path.relative(ROOT, file),
           line: hit.line,
@@ -527,6 +781,9 @@ export const guard: AstGuard = {
 
     return { violations };
   },
+  writeBaseline(files) {
+    writeCatalogs(files, collectScopeEsTables(files));
+  },
 };
 
 // Run only when invoked as a script — tests import the helpers without

package/src/guard-direct-fetch.ts

@@ -31,6 +31,7 @@ import {
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { lineHasIgnoreTag } from "./_lib/ignore-tag";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const SCAN: ScanSpec = {
@@ -48,7 +49,9 @@ const EXCLUDE =
 
 // packages/framework/src/http/egress.ts IS the egress() implementation.
 const ALLOWLIST = [/^kumiko-framework\/packages\/framework\/src\/http\/egress\.ts$/];
-const ALLOW_MARKER = "guard-allow: same-origin fetch";
+const IGNORE_TAG = "kumiko-lint-ignore direct-fetch";
+const IGNORE_TAG_WITH_REASON_RE =
+  /kumiko-lint-ignore\s+(?:[\w-]+,)*direct-fetch(?:,[\w-]+)*(?=\s|$)(.*)$/;
 
 interface Violation {
   line: number;
@@ -61,14 +64,12 @@ const GLOBAL_FETCH_RECEIVERS = new Set(["globalThis", "window"]);
 
 // The marker is a per-line skip for a security guard, so it only counts with a
 // non-generic reason after it — a bare marker still reports the finding.
-function hasAllowMarkerWithReason(sf: SourceFile, line: number): boolean {
+function hasIgnoreTagWithReason(sf: SourceFile, line: number): boolean {
   const lines = sf.getFullText().split("\n");
   const idx = line - 1;
   return [lines[idx] ?? "", lines[idx - 1] ?? ""].some((text) => {
-    const markerAt = text.indexOf(ALLOW_MARKER);
-    if (markerAt < 0) return false;
-    const reason = text
-      .slice(markerAt + ALLOW_MARKER.length)
+    if (!lineHasIgnoreTag(text, IGNORE_TAG)) return false;
+    const reason = (IGNORE_TAG_WITH_REASON_RE.exec(text)?.[1] ?? "")
       .replace(/^\s*(?:—|–|-|:)\s*/, "")
       .trim();
     return !isGenericReason(reason);
@@ -127,7 +128,7 @@ export const guard: AstGuard = {
   security: true,
   hint:
     "Replace raw fetch(...) with egress(policy)(...) from @cosmicdrift/kumiko-framework/http (framework#2147). " +
-    'Same-origin path literal (`"/api/..."`) is allowed; otherwise put `// guard-allow: same-origin fetch — <specific reason>` on the line above (a bare marker does not count). ' +
+    'Same-origin path literal (`"/api/..."`) is allowed; otherwise put `// kumiko-lint-ignore direct-fetch <specific reason>` on the line above (a bare marker does not count). ' +
     "Local bindings named fetch are flagged (false positive — unblock via that marker). " +
     'Known gap: bracket access (globalThis["fetch"](...)).',
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
@@ -142,7 +143,7 @@ export const guard: AstGuard = {
         root === undefined ? undefined : `${root.name}/${pathRelative(root.absPath, file)}`;
       if (key !== undefined && isAllowlisted(key, ALLOWLIST)) continue;
       for (const v of findRawFetchCalls(sf)) {
-        if (hasAllowMarkerWithReason(sf, v.line)) continue;
+        if (hasIgnoreTagWithReason(sf, v.line)) continue;
         violations.push({
           // cwd-relative, not repo-relative `rel` — the security baseline
           // needs an unambiguous path to resolve back to (repo, relPath).

package/src/guard-escape-hatch-declared.ts

@@ -128,6 +128,7 @@ function scannableFiles(files: readonly SourceFile[]): SourceFile[] {
 export function systemScopeDirs(files: readonly SourceFile[]): string[] {
   const dirs: string[] = [];
   for (const sf of scannableFiles(files)) {
+    if (!sf.getFullText().includes("systemScope")) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const expr = call.getExpression();
       if (
@@ -189,6 +190,10 @@ function isTenantDbExpression(node: Node): boolean {
   return (node.getSymbol()?.getDeclarations() ?? []).some(isTenantDbDeclaration);
 }
 
+// Text prefilters: a node walk per rule per file is the guard's dominant cost, and
+// a rule's anchor name must appear verbatim in any file it can fire on.
+const RAW_ACCESS = /\.\s*raw\b/;
+
 function findRawFindings(
   sf: SourceFile,
   root: string,
@@ -196,6 +201,7 @@ function findRawFindings(
 ): EscapeHatchFinding[] {
   if (isInSystemScope(sf.getFilePath(), systemDirs)) return [];
   const out: EscapeHatchFinding[] = [];
+  if (!RAW_ACCESS.test(sf.getFullText())) return out;
   for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
     if (pa.getName() !== "raw") continue;
     if (!isTenantDbExpression(pa.getExpression())) continue;
@@ -217,6 +223,7 @@ function findUnsafeRawFindings(
 ): EscapeHatchFinding[] {
   if (isInSystemScope(sf.getFilePath(), systemDirs)) return [];
   const out: EscapeHatchFinding[] = [];
+  if (!sf.getFullText().includes("unsafeRaw")) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
@@ -531,6 +538,8 @@ function findSystemIdentityFindings(
   systemDirs: readonly string[],
 ): EscapeHatchFinding[] {
   const out: EscapeHatchFinding[] = [];
+  const text = sf.getFullText();
+  if (!text.includes("queryAs") && !text.includes("writeAs")) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
@@ -562,6 +571,7 @@ function findUnsafeAllTenantsFindings(
   systemDirs: readonly string[],
 ): EscapeHatchFinding[] {
   const out: EscapeHatchFinding[] = [];
+  if (!sf.getFullText().includes("unsafeAllTenants")) return out;
   for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
     const nameNode = prop.getNameNode();
     if (!nameNode.isKind(SyntaxKind.Identifier) || nameNode.getText() !== "unsafeAllTenants") {
@@ -609,6 +619,8 @@ const GENERIC_REASON_METHODS = new Set(["acknowledgeCrossTenant", "unsafeRaw"]);
 
 function findGenericReasonMethodCalls(sf: SourceFile, root: string): GenericReasonFinding[] {
   const out: GenericReasonFinding[] = [];
+  const text = sf.getFullText();
+  if (![...GENERIC_REASON_METHODS].some((method) => text.includes(method))) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) continue;
@@ -634,6 +646,7 @@ function findGenericReasonDeclareEscapeHatchCalls(
   root: string,
 ): GenericReasonFinding[] {
   const out: GenericReasonFinding[] = [];
+  if (!sf.getFullText().includes("declareEscapeHatch")) return out;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression();
     if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
@@ -662,6 +675,7 @@ function findGenericReasonObjectProperty(
   propertyName: string,
 ): GenericReasonFinding[] {
   const out: GenericReasonFinding[] = [];
+  if (!sf.getFullText().includes(propertyName)) return out;
   for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
     if (pa.getName() !== propertyName) continue;
     const init = pa.getInitializer();

package/src/guard-guards-doc-drift.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+/**
+ * Fails when docs/reference/guards.md differs from what the generator renders from the guard sources.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import {
+  GUARDS_DOC_REL,
+  GUARDS_SRC_REL,
+  hasGuardsSource,
+  renderGuardsDoc,
+} from "./_lib/guards-doc";
+
+const REGENERATE_HINT = "run `bun run gen:guards-doc` and commit the result";
+
+export const check: RepoCheck = {
+  name: "guards-doc-drift",
+  hint: "Run `bun run gen:guards-doc` and commit docs/reference/guards.md.",
+  run(roots) {
+    const frameworkRoots = roots.filter((root) => hasGuardsSource(root.absPath));
+    const violations: { file: string; line: number; message: string }[] = [];
+    for (const root of frameworkRoots) {
+      const docPath = join(root.absPath, GUARDS_DOC_REL);
+      const expected = renderGuardsDoc(root.absPath);
+      if (!existsSync(docPath)) {
+        violations.push({ file: GUARDS_DOC_REL, line: 1, message: `missing; ${REGENERATE_HINT}` });
+      } else if (readFileSync(docPath, "utf-8") !== expected) {
+        violations.push({
+          file: GUARDS_DOC_REL,
+          line: 1,
+          message: `differs from the generated output (sources in ${GUARDS_SRC_REL}); ${REGENERATE_HINT}`,
+        });
+      }
+    }
+    return {
+      violations,
+      matchedFiles: frameworkRoots.length,
+      notApplicable: frameworkRoots.length === 0,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}