@cosmicdrift/kumiko-guards 0.331.0 → 0.332.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.331.0",
+  "version": "0.332.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.331.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.332.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/git-env.ts

@@ -10,11 +10,37 @@
  */
 export const GIT_ENV_KEYS = ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "USER", "LOGNAME"] as const;
 
+/**
+ * Extra keys for git calls that talk to a remote (`git fetch`): without the
+ * SSH agent / proxy settings the transport cannot authenticate or connect.
+ * Opt-in via `gitEnv(env, { transport: true })`; local-only calls stay narrow.
+ * `GIT_DIR`/`GIT_WORK_TREE` are deliberately never part of this list.
+ */
+export const GIT_TRANSPORT_ENV_KEYS = [
+  "SSH_AUTH_SOCK",
+  "SSH_AGENT_PID",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND",
+  "GIT_ASKPASS",
+  "SSH_ASKPASS",
+  "GIT_TERMINAL_PROMPT",
+  "GIT_SSL_CAINFO",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "NO_PROXY",
+  "no_proxy",
+  "ALL_PROXY",
+] as const;
+
 export function gitEnv(
   env: Readonly<Record<string, string | undefined>> = process.env,
+  options: { readonly transport?: boolean } = {},
 ): Record<string, string> {
+  const keys = options.transport ? [...GIT_ENV_KEYS, ...GIT_TRANSPORT_ENV_KEYS] : GIT_ENV_KEYS;
   const out: Record<string, string> = {};
-  for (const key of GIT_ENV_KEYS) {
+  for (const key of keys) {
     const value = env[key];
     if (value !== undefined) out[key] = value;
   }

package/src/_lib/guard-kit.ts

@@ -271,12 +271,12 @@ export type RunResult = {
   readonly warnings?: readonly GuardViolation[];
 };
 
-// Per-root floor: a root whose declared sourceRoots hold zero .ts/.tsx files is a violation; only applies to scope "source".
+// Per-root floor: a root whose declared sourceRoots hold zero .ts/.tsx files is a violation; applies to every scope that includes source ("source", "source+tests").
 export function checkRootFloor(
   guard: Pick<AstGuard, "scan">,
   scans: readonly RootScan[],
 ): { readonly violatingRoots: readonly string[] } {
-  if (guard.scan.scope !== "source") return { violatingRoots: [] };
+  if (guard.scan.scope === "tests") return { violatingRoots: [] };
   return {
     violatingRoots: scans.filter((scan) => scan.sourceSurface === 0).map((scan) => scan.root.name),
   };
@@ -531,6 +531,7 @@ export function printGuardKitBanner(
   if (error !== undefined) {
     console.error(error);
     process.exit(1);
+    return;
   }
   console.log(`kumiko-guards ${guardKitVersion()} - ${guardCount} guards registered`);
   console.log(`Roots: ${roots.map((r) => r.root.name).join(", ")} (${roots.length})`);

package/src/_lib/scan-scope.ts

@@ -24,7 +24,9 @@ export type ScanSpec =
       /** Globs relative to the matched source root dir; narrows only. */
       readonly within?: readonly string[];
     })
-  | (ScanSpecBase & { readonly scope: "tests" });
+  | (ScanSpecBase & { readonly scope: "tests" })
+  // Union of the source and test surface — for guards that correlate source declarations with test coverage.
+  | (ScanSpecBase & { readonly scope: "source+tests" });
 
 export type RootScan = {
   readonly root: RepoRoot;
@@ -141,13 +143,21 @@ function keepForSpec(hit: Hit, root: RepoRoot, spec: ScanSpec): boolean {
 
 function scanRoot(spec: ScanSpec, root: RepoRoot): RootScan {
   const sourceSurfaceHits = afterExcludes(sourceHits(root), root.manifest.excludes);
+  const testSurfaceHits = () => afterExcludes(testHits(root), root.manifest.excludes);
   const scopeHits =
     spec.scope === "source"
       ? sourceSurfaceHits
-      : afterExcludes(testHits(root), root.manifest.excludes);
-  const seen = new Set(scopeHits.map((hit) => hit.repoRel));
+      : spec.scope === "tests"
+        ? testSurfaceHits()
+        : [...sourceSurfaceHits, ...testSurfaceHits()];
+  const seen = new Set<string>();
+  const uniqueScopeHits = scopeHits.filter((hit) => {
+    if (seen.has(hit.repoRel)) return false;
+    seen.add(hit.repoRel);
+    return true;
+  });
   const additionalHits = afterExcludes(extraHits(root, spec.extraGlobs), root.manifest.excludes);
-  const files = [...scopeHits, ...additionalHits.filter((hit) => !seen.has(hit.repoRel))]
+  const files = [...uniqueScopeHits, ...additionalHits.filter((hit) => !seen.has(hit.repoRel))]
     .filter((hit) => keepForSpec(hit, root, spec))
     .map((hit) => join(root.absPath, hit.repoRel))
     .sort();

package/src/_lib/security-baseline.ts

@@ -86,10 +86,14 @@ export function parseSecurityBaseline(raw: unknown): SecurityBaseline | undefine
 }
 
 export function loadSecurityBaseline(repo: string, repoDir: string): SecurityBaselineLoad {
+  const file = securityBaselinePath(repoDir);
   if (!REPO_NAME_RE.test(repo)) {
-    throw new Error(`loadSecurityBaseline: invalid repo name "${repo}"`);
+    return {
+      kind: "invalid",
+      file,
+      reason: `repo name "${repo}" from package.json is not a valid lowercase package name`,
+    };
   }
-  const file = securityBaselinePath(repoDir);
   if (!existsSync(file)) return { kind: "ok", findings: {}, hardFail: [] };
   let raw: unknown;
   try {

package/src/_lib/test-file.ts

@@ -0,0 +1,2 @@
+/** `*.test.ts(x)`, `*.integration.ts(x)` and `*.integration.test.ts(x)`. */
+export const TEST_FILE_RE = /\.(?:test|integration)(?:\.test)?\.tsx?$/;

package/src/changes.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "0.332.0",
+    "type": "fix",
+    "title": "direct-entity-writes canary counts only real table writes"
+  },
+  {
+    "version": "0.332.0",
+    "type": "improvement",
+    "title": "gitEnv is exported from the package root"
+  },
+  {
+    "version": "0.332.0",
+    "type": "fix",
+    "title": "git transport env is kept for the changes-json fetch"
+  },
+  {
+    "version": "0.332.0",
+    "type": "improvement",
+    "title": "guards resolve aliased imports, literal values, tsx lib files and entityEdit slots precisely",
+    "migration": "Neue Violations moeglich: lib-test-coverage erfasst jetzt .tsx und tiefere lib-Ebenen und zaehlt Fixtures unter __tests__ ohne .test-Suffix nicht als Test; test-stack-drift loest Import-Aliase auf; direct-fetch wertet den Laufzeitwert des Literals aus; no-framed-extension-sections behandelt nur slots.header von entityEdit-Screens als Header. Betroffene Stellen mit Test, echtem Import oder Anpassung beheben."
+  },
+  {
+    "version": "0.332.0",
+    "type": "improvement",
+    "title": "Coverage guards scan test files; admin-api, primitives-discipline and real-provider-isolation resolve roots and workspaces properly",
+    "migration": "Neue Violations moeglich: access-denied-test und tenant-escalation zaehlen jetzt auch *.integration.ts und Tests ausserhalb der sourceRoots als Coverage (Scope source+tests); primitives-discipline scannt alle flat-src-App-Roots; check-real-provider-isolation flaggt Scripts, die test:real/e2e:real aufrufen, und prueft alle Workspace-package.json. Betroffene Stellen fixen oder per Security-Baseline neu einfrieren."
+  },
+  {
+    "version": "0.332.0",
+    "type": "improvement",
+    "title": "secret-literal guard flags more fallbacks and no longer leaks literals",
+    "migration": "Neue Violations bei `*/ code`-Zeilen, Code-Zeilen mit fuehrendem `*` und Literalen mit hmac/private-key/signing-key; die Violation-Message nennt Name und Laenge statt der Zeile. Fallbacks entfernen und das Secret hart aus dem validierten Env lesen."
+  },
+  {
+    "version": "0.332.0",
+    "type": "improvement",
+    "title": "html-escape guard flags unescaped intermediate templates and raw-returning local helpers",
+    "migration": "Neue Violations bei ungeescapten Zwischen-Templates und lokalen Helfern, die Input roh zurueckgeben; diese per escapeHtml absichern."
+  },
+  {
+    "version": "0.332.0",
+    "type": "improvement",
+    "title": "worktree pre-push runs the consumer-CI guards"
+  },
   {
     "version": "0.331.0",
     "type": "improvement",

package/src/check-real-provider-isolation.ts

@@ -68,32 +68,66 @@ function scanCiWorkflows(root: RepoRoot, findings: TextLineFinding[]): number {
 // package.json scripts: a real-provider signal in any script OTHER than the
 // two designated ones is a leak (e.g. a "test" or "ci" script that pulls in
 // the real env or filters for a .real. spec by hand).
+const REAL_SCRIPT_CALL = /\b(?:test|e2e):real\b/;
+
 function scriptLeaksRealProvider(name: string, command: string): string | undefined {
   if (REAL_SCRIPT_NAMES.has(name)) return undefined;
   if (command.includes(REAL_PROVIDERS_ENV)) {
     return `script "${name}" sets ${REAL_PROVIDERS_ENV} outside test:real/e2e:real: ${command}`;
   }
+  if (REAL_SCRIPT_CALL.test(command)) {
+    return `script "${name}" invokes test:real/e2e:real, which would run real-provider specs from a default script: ${command}`;
+  }
   if (/\.real\.(test|spec)\.ts/.test(command)) {
     return `script "${name}" references a *.real. spec/test outside test:real/e2e:real: ${command}`;
   }
   return undefined;
 }
 
-function scanPackageJsonScripts(root: RepoRoot, findings: TextLineFinding[]): number {
-  const path = join(root.absPath, "package.json");
-  let parsed: { scripts?: Record<string, string> };
+type WorkspaceManifest = {
+  scripts?: Record<string, string>;
+  workspaces?: string[] | { packages?: string[] };
+};
+
+function readManifest(abs: string): WorkspaceManifest | undefined {
   try {
-    parsed = JSON.parse(readFileSync(path, "utf8")) as { scripts?: Record<string, string> };
+    return JSON.parse(readFileSync(abs, "utf8")) as WorkspaceManifest;
   } catch {
-    return 0;
+    return undefined;
   }
-  const scripts = parsed.scripts ?? {};
+}
+
+function workspacePatterns(manifest: WorkspaceManifest): string[] {
+  const declared = Array.isArray(manifest.workspaces)
+    ? manifest.workspaces
+    : (manifest.workspaces?.packages ?? []);
+  return declared.filter((pattern) => !pattern.startsWith("!"));
+}
+
+// Root package.json plus every workspace package.json the root's `workspaces` globs resolve to.
+function packageJsonRels(root: RepoRoot, rootManifest: WorkspaceManifest): string[] {
+  const rels = new Set<string>(["package.json"]);
+  for (const pattern of workspacePatterns(rootManifest)) {
+    const glob = new Glob(`${pattern.replace(/\/$/, "")}/package.json`);
+    for (const rel of glob.scanSync({ cwd: root.absPath })) {
+      if (rel.split("/").includes("node_modules")) continue;
+      rels.add(rel);
+    }
+  }
+  return [...rels].sort();
+}
+
+function scanPackageJsonScripts(root: RepoRoot, findings: TextLineFinding[]): number {
+  const rootManifest = readManifest(join(root.absPath, "package.json"));
+  if (rootManifest === undefined) return 0;
   let scanned = 0;
-  for (const [name, command] of Object.entries(scripts)) {
-    scanned++;
-    const message = scriptLeaksRealProvider(name, command);
-    if (message !== undefined) {
-      findings.push({ file: "package.json", line: 1, text: message });
+  for (const rel of packageJsonRels(root, rootManifest)) {
+    const manifest = rel === "package.json" ? rootManifest : readManifest(join(root.absPath, rel));
+    if (manifest === undefined) continue;
+    for (const [name, command] of Object.entries(manifest.scripts ?? {})) {
+      scanned++;
+      const message = scriptLeaksRealProvider(name, command);
+      if (message !== undefined) findings.push({ file: rel, line: 1, text: message });
     }
   }
   return scanned;

package/src/check-secret-literals.ts

@@ -22,11 +22,12 @@
  * jedes Repo läuft diesen Check in seiner eigenen CI gegen sich selbst,
  * statt dass ein zentraler Scan in fremde Sibling-Checkouts greift.
  */
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { Glob } from "bun";
+import { ts } from "ts-morph";
 import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
-import { scanLinesForPredicate } from "./_lib/scan-lines";
 
 // Server-side only: a declared sourceRoot under a mobile/client app has no server secrets to leak.
 const CLIENT_SOURCE_ROOT = /(?:^|\/)mobile(?:\/|$)/;
@@ -42,31 +43,94 @@ const DEV_ENTRYPOINT = /(?:^|\/)bin\/server\.ts$/;
 
 // A `?? "literal"` / `|| "literal"` nullish/or fallback to a string literal.
 const STRING_FALLBACK = /(?:\?\?|\|\|)\s*(['"`])([^'"`\n]+)\1/;
-// ...on a line that is about a secret (assignee name or the literal itself).
-const SECRET_CONTEXT = /secret|password|passphrase|hmac|private[_-]?key|signing[_-]?key/i;
+// A secret-like identifier. Matched only against the text LEFT of the fallback
+// (assignee / property name): `cfg.title ?? "Secret Santa"` is a label, not a secret.
+const SECRET_NAME =
+  /[\w$]*(?:secret|password|passphrase|hmac|private[_-]?key|signing[_-]?key)[\w$]*/i;
 // Short / numeric literals are versions or flags (e.g. `_CURRENT_VERSION ?? "1"`),
 // never a usable secret.
 const TRIVIAL_LITERAL = /^[\d.]+$/;
+const MIN_SECRET_LENGTH = 8;
+const IGNORE_TAG = "kumiko-lint-ignore secret-literal";
 
 export type SecretLiteralFinding = {
   readonly file: string;
   readonly line: number;
-  readonly text: string;
+  /** Assignee / property name left of the fallback. Never the literal. */
+  readonly name: string;
+  readonly literalLength: number;
 };
 
-/** Returns the offending literal, or null when the line is clean. */
-export function secretLiteralOnLine(line: string): string | null {
-  // Only the line start counts as a comment (`//`, or a block-comment line
-  // starting with `*`/`/*`/`*/`): stripping from the first `//` anywhere in
-  // the line would cut connection-string fallbacks (postgres://, redis://,
-  // https://token@host/…) off before their closing quote, losing findings.
-  const code = /^\s*(?:\/\/|\/\*|\*\/|\*)/.test(line) ? "" : line;
-  if (!SECRET_CONTEXT.test(code)) return null;
-  const match = STRING_FALLBACK.exec(code);
-  if (!match) return null;
-  const literal = match[2];
-  if (!literal || literal.length < 8 || TRIVIAL_LITERAL.test(literal)) return null;
-  return literal;
+const isJsDocKind = (kind: ts.SyntaxKind): boolean =>
+  kind >= ts.SyntaxKind.FirstJSDocNode && kind <= ts.SyntaxKind.LastJSDocNode;
+
+// Blanks every comment with spaces (newlines kept, so line numbers survive).
+// The real TypeScript parser decides what is a comment: a hand-rolled
+// per-line tokenizer misreads regex literals (`/^https?:\/*/`) and template
+// continuation lines as comment starts and then skips code, which would make
+// this security guard fail open. Trivia between two tokens contains only
+// whitespace and comments, so it is masked directly from the token gaps.
+function maskComments(source: string): string {
+  const sourceFile = ts.createSourceFile("scan.ts", source, ts.ScriptTarget.Latest, false);
+  const chars = [...source];
+  const blank = (from: number, to: number): void => {
+    for (let i = from; i < to; i++) if (chars[i] !== "\n") chars[i] = " ";
+  };
+  const visit = (node: ts.Node): void => {
+    const children = node.getChildren(sourceFile).filter((child) => !isJsDocKind(child.kind));
+    if (children.length > 0) {
+      for (const child of children) visit(child);
+      return;
+    }
+    const trivia = source.slice(node.pos, node.getStart(sourceFile));
+    for (const m of trivia.matchAll(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g)) {
+      blank(node.pos + m.index, node.pos + m.index + m[0].length);
+    }
+  };
+  visit(sourceFile);
+  return chars.join("");
+}
+
+export type SecretLiteralHit = {
+  readonly lineNumber: number;
+  readonly name: string;
+  readonly literalLength: number;
+};
+
+// Literal content alone is enough when it names key material; bare
+// secret/password stays name-only so "Secret Santa" labels are not flagged.
+const SECRET_LITERAL_TOKEN = /hmac|private[_-]?key|signing[_-]?key/i;
+// Assignee / property name directly left of the fallback (`k = …`, `key: …`).
+const LHS_NAME = /([\w$]+)\s*[:=][^:=]*$/;
+const UNNAMED_PLACEHOLDER = "<unnamed>";
+
+/**
+ * Per-file scan on comment-masked source (see maskComments), so only comment
+ * text is skipped and a wrapped code line that starts with `*` is still
+ * checked. Opt-out: `// kumiko-lint-ignore secret-literal <reason>` on the
+ * line itself or the line above (checked on the raw lines).
+ */
+export function scanLinesForSecretLiterals(lines: readonly string[]): SecretLiteralHit[] {
+  const hits: SecretLiteralHit[] = [];
+  const maskedLines = maskComments(lines.join("\n")).split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i] ?? "";
+    const code = maskedLines[i] ?? "";
+    const match = STRING_FALLBACK.exec(code);
+    if (!match) continue;
+    const literal = match[2];
+    if (!literal || literal.length < MIN_SECRET_LENGTH || TRIVIAL_LITERAL.test(literal)) continue;
+    const left = code.slice(0, match.index);
+    const name =
+      SECRET_NAME.exec(left)?.[0] ??
+      (SECRET_LITERAL_TOKEN.test(literal)
+        ? (LHS_NAME.exec(left)?.[1] ?? UNNAMED_PLACEHOLDER)
+        : undefined);
+    if (name === undefined) continue;
+    if (raw.includes(IGNORE_TAG) || (lines[i - 1] ?? "").includes(IGNORE_TAG)) continue;
+    hits.push({ lineNumber: i + 1, name, literalLength: literal.length });
+  }
+  return hits;
 }
 
 async function scanRoot(
@@ -79,9 +143,16 @@ async function scanRoot(
       if (EXCLUDE_DIR.test(`/${rel}`) || IS_TEST.test(rel) || DEV_ENTRYPOINT.test(rel)) {
         continue;
       }
-      const abs = join(root.absPath, rel);
       scannedFiles++;
-      scanLinesForPredicate(abs, rel, (line) => secretLiteralOnLine(line) !== null, findings);
+      const lines = readFileSync(join(root.absPath, rel), "utf8").split("\n");
+      for (const hit of scanLinesForSecretLiterals(lines)) {
+        findings.push({
+          file: rel,
+          line: hit.lineNumber,
+          name: hit.name,
+          literalLength: hit.literalLength,
+        });
+      }
     }
   }
   return { findings, scannedFiles };
@@ -112,7 +183,11 @@ export const check: RepoCheck = {
     }
     const { findings, scannedFiles } = await scanSecretLiterals(roots);
     return {
-      violations: findings.map((f) => ({ file: f.file, line: f.line, message: f.text })),
+      violations: findings.map((f) => ({
+        file: f.file,
+        line: f.line,
+        message: `hardcoded secret fallback for "${f.name}" (${f.literalLength} chars)`,
+      })),
       matchedFiles: scannedFiles,
       notApplicable: false,
     };

package/src/guard-access-denied-test.ts

@@ -27,14 +27,14 @@ import {
   nameForms,
 } from "./_lib/handler-name-forms";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { TEST_FILE_RE } from "./_lib/test-file";
 
 const ROOT = process.cwd();
 const SCAN: ScanSpec = {
-  scope: "source",
+  scope: "source+tests",
   extensions: ["ts"],
   frameworkWithin: ["packages/*/src/**", "samples/**"],
 };
-const TEST_FILE = /\.test\.ts$/;
 
 // Any role that lets an unauthenticated/unrestricted caller through means
 // nobody is actually excluded by this handler's roles.
@@ -47,7 +47,7 @@ export function findRoleRestrictedWriteHandlers(
 ): RoleRestrictedHandler[] {
   const out: RoleRestrictedHandler[] = [];
   for (const sf of files) {
-    if (TEST_FILE.test(sf.getFilePath())) continue;
+    if (TEST_FILE_RE.test(sf.getFilePath())) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const callee = call.getExpression().getText();
       if (callee !== "defineWriteHandler" && !/\.writeHandler$/.test(callee)) continue;
@@ -99,7 +99,7 @@ export function findHandlersWithoutAccessDeniedTest(
   const repoKeyOf = (filePath: string): string => findRepoRootFor(filePath, roots)?.absPath ?? "";
   const testTextsByRepo = new Map<string, string[]>();
   for (const sf of files) {
-    if (!TEST_FILE.test(sf.getFilePath())) continue;
+    if (!TEST_FILE_RE.test(sf.getFilePath())) continue;
     const text = sf.getFullText();
     if (!ACCESS_DENIED_ASSERTION.test(text)) continue;
     const repoKey = repoKeyOf(sf.getFilePath());

package/src/guard-admin-api.ts

@@ -21,7 +21,9 @@
 
 import * as path from "node:path";
 import { type CallExpression, type Identifier, type SourceFile, SyntaxKind } from "ts-morph";
+import { findRepoRootFor } from "./_lib/baseline-compare";
 import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const ROOT = process.cwd();
 
@@ -49,10 +51,14 @@ export interface Violation {
   enclosingFunction: string;
 }
 
-function collectViolations(sourceFile: SourceFile): Violation[] {
+function collectViolations(sourceFile: SourceFile, roots: readonly RepoRoot[]): Violation[] {
   const violations: Violation[] = [];
-  const relativePath = path.relative(ROOT, sourceFile.getFilePath());
-  if (isAllowed(relativePath)) return violations;
+  const filePath = sourceFile.getFilePath();
+  // Allowlist is repo-root-relative; the reported path stays cwd-relative for the security baseline.
+  const repoRoot = findRepoRootFor(filePath, roots);
+  const allowlistPath = path.relative(repoRoot?.absPath ?? ROOT, filePath);
+  const relativePath = path.relative(ROOT, filePath);
+  if (isAllowed(allowlistPath)) return violations;
 
   const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
   for (const call of calls) {
@@ -112,13 +118,13 @@ export const guard: AstGuard = {
   // App repos are not exempt — appendRaw/appendRawBatch bypasses the pipeline there too (infra#502).
   security: true,
   hint: "Admin API (appendRaw/appendRawBatch) bypasses the pipeline — only allowed in samples/*/migration/ or scripts/migrations/. For domain events: ctx.appendEvent / write handler.",
-  run(files) {
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 
     for (const sf of files) {
       const file = sf.getFilePath();
       if (EXCLUDE.test(file)) continue;
-      for (const v of collectViolations(sf)) {
+      for (const v of collectViolations(sf, roots)) {
         violations.push({
           file: v.file,
           line: v.line,

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

@@ -287,11 +287,47 @@ function resolveWrite(
   return undefined;
 }
 
+// Callee names whose result is a table definition: `const xTable = <builder>(...)`.
+const TABLE_BUILDER_NAMES: ReadonlySet<string> = new Set([
+  "pgTable",
+  "table",
+  "buildEntityTable",
+  "defineUnmanagedTable",
+  "deriveEntityTableMeta",
+]);
+
+function isTableDeclaration(identifier: Identifier): boolean {
+  const symbol = identifier.getSymbol();
+  const resolved = symbol?.getAliasedSymbol() ?? symbol;
+  return (resolved?.getDeclarations() ?? []).some((decl) => {
+    if (decl.getKind() !== SyntaxKind.VariableDeclaration) return false;
+    const init = decl.asKindOrThrow(SyntaxKind.VariableDeclaration).getInitializer();
+    if (init?.getKind() !== SyntaxKind.CallExpression) return false;
+    const callee = init.asKindOrThrow(SyntaxKind.CallExpression).getExpression();
+    const calleeName =
+      callee.getKind() === SyntaxKind.PropertyAccessExpression
+        ? callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName()
+        : callee.getText();
+    return TABLE_BUILDER_NAMES.has(calleeName);
+  });
+}
+
+// A write whose table argument resolves to a real table declaration — keeps
+// `map.delete(key)` / `set.delete(id)` from counting as table writes.
+function isTableWriteCall(call: CallExpression): boolean {
+  const write = resolveWrite(call);
+  return (
+    write !== undefined &&
+    declIdOf(write.tableArg) !== undefined &&
+    isTableDeclaration(write.tableArg)
+  );
+}
+
 function hasAnyTableWrite(files: readonly SourceFile[]): boolean {
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      if (resolveWrite(call)) return true;
+      if (isTableWriteCall(call)) return true;
     }
   }
   return false;

package/src/guard-direct-fetch.ts

@@ -21,6 +21,7 @@
 
 import { relative as pathRelative } from "node:path";
 import { type CallExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { literalReasonText } from "./_lib/generic-reason";
 import {
   type AstGuard,
   findRepoRootFor,
@@ -79,13 +80,9 @@ function isSameOriginLiteralArg(expr: CallExpression): boolean {
     return head.startsWith("/") && !head.startsWith("//") && head.length >= 2;
   }
 
-  if (
-    arg.getKind() !== SyntaxKind.StringLiteral &&
-    arg.getKind() !== SyntaxKind.NoSubstitutionTemplateLiteral
-  ) {
-    return false;
-  }
-  const path = arg.getText().slice(1, -1);
+  // Runtime value, not source text: "/\/attacker.example" is "//attacker.example".
+  const path = literalReasonText(arg);
+  if (path === undefined) return false;
   // Reject protocol-relative URLs ("//evil.example") — not same-origin.
   return path.startsWith("/") && !path.startsWith("//");
 }

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

@@ -561,7 +561,8 @@ function findUnsafeAllTenantsFindings(
       line: prop.getStartLineNumber(),
       rule: "unsafe-all-tenants-outside-declared-scope",
       message:
-        'unsafeAllTenants used outside a declared scope — restrict to a systemScope feature, a .job.ts / r.job(...) job, or declare { escapeHatch: { reason: "..." } } alongside it.',
+        'unsafeAllTenants used outside a declared scope — restrict to a systemScope feature, a .job.ts / r.job(...) job, declare { escapeHatch: { reason: "..." } } alongside it, or call declareEscapeHatch({ reason: "..." }) as a direct body statement of a named hook.' +
+        unresolvableDeclareEscapeHatchHint(call),
     });
   }
   return out;

package/src/guard-feature-integration-tests.ts

@@ -6,15 +6,16 @@
  * from CLAUDE.md.
  *
  * Coverage rule: a feature counts as covered when an integration test
- * imports anything — relative or via the `@cosmicdrift/kumiko-bundled-features`
- * package — that resolves into its `packages/bundled-features/src/<name>/`
- * directory. That's deliberately broader than "imports feature.ts itself":
- * a test that imports a sibling module of the feature (e.g. its resolver,
- * its defaults helper) still proves the directory ran, and a barrel import
- * of the whole package still proves the feature was composed. Since the
- * `<name>-feature.ts` -> `feature.ts` rename (df3f6b5b) the file basename is
- * identical for all 56 features — the directory name is the only usable
- * identifier.
+ * imports anything that resolves into its
+ * `packages/bundled-features/src/<name>/` directory — either relatively, or
+ * via the subpath `@cosmicdrift/kumiko-bundled-features/<feature>`. That's
+ * deliberately broader than "imports feature.ts itself": a test that imports
+ * a sibling module of the feature (e.g. its resolver, its defaults helper)
+ * still proves the directory ran. Only subpath imports count: a barrel
+ * import without subpath (`@cosmicdrift/kumiko-bundled-features`) covers no
+ * feature. Since the `<name>-feature.ts` -> `feature.ts` rename (df3f6b5b)
+ * the file basename is identical for all 56 features — the directory name
+ * is the only usable identifier.
  *
  * Usage:
  *   bun guards/guard-feature-integration-tests.ts