@cosmicdrift/kumiko-guards 0.334.0 → 0.335.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.334.0",
+  "version": "0.335.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.334.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.335.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/framework-import.ts

@@ -0,0 +1,29 @@
+import * as path from "node:path";
+import { type Node, SyntaxKind } from "ts-morph";
+
+const FRAMEWORK_PACKAGE = "@cosmicdrift/kumiko-framework";
+// Inside the framework monorepo itself the helpers are imported relatively,
+// so a relative specifier counts when it resolves into the framework package.
+const FRAMEWORK_SOURCE_DIR_MARKER = "/packages/framework/src/";
+
+function isFrameworkModuleSpecifier(specifier: string, importingFile: string): boolean {
+  if (specifier === FRAMEWORK_PACKAGE || specifier.startsWith(`${FRAMEWORK_PACKAGE}/`)) {
+    return true;
+  }
+  if (!specifier.startsWith(".")) return false;
+  const resolved = path.resolve(path.dirname(importingFile), specifier);
+  return `${resolved}/`.includes(FRAMEWORK_SOURCE_DIR_MARKER);
+}
+
+// A text match on a function name lets a same-named local no-op clear an
+// escape-hatch finding, so the identifier must resolve to an import of
+// `exportedName` from the framework package. Aliased imports resolve too.
+export function isFrameworkImportOf(node: Node, exportedName: string): boolean {
+  if (!node.isKind(SyntaxKind.Identifier)) return false;
+  const decls = node.getSymbol()?.getDeclarations() ?? [];
+  return decls.some((decl) => {
+    if (!decl.isKind(SyntaxKind.ImportSpecifier) || decl.getName() !== exportedName) return false;
+    const specifier = decl.getImportDeclaration().getModuleSpecifierValue();
+    return isFrameworkModuleSpecifier(specifier, decl.getSourceFile().getFilePath());
+  });
+}

package/src/_lib/git-env.ts

@@ -1,13 +1,5 @@
-/**
- * Spawned git calls get an allowlisted environment, never `...process.env`.
- * A caller running as a pre-push hook would otherwise inherit `GIT_DIR`/
- * `GIT_WORK_TREE` from git, which git prefers over `cwd` — so an inherited
- * environment would answer for the hook's repo instead of the path being
- * asked about. `HOME` stays in, so the global config is still read.
- *
- * An allowlist (not a blocklist) so a future git env var neither of us has
- * thought of yet is excluded by construction, not by omission.
- */
+// Allowlist, not `...process.env`: git prefers an inherited GIT_DIR/GIT_WORK_TREE over cwd,
+// so a pre-push hook's env would answer for the hook's repo. HOME stays so global config loads.
 export const GIT_ENV_KEYS = ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "USER", "LOGNAME"] as const;
 
 /**

package/src/_lib/guard-kit.ts

@@ -474,8 +474,13 @@ export function explainGuards(
 
 function guardKitVersion(): string {
   const pkgPath = resolve(import.meta.dir, "../../package.json");
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
-  return pkg.version ?? "0.0.0";
+  // The version only decorates the banner; it must never abort a guard run.
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
 }
 
 /**
@@ -494,12 +499,7 @@ export function guardKitPreflightError(guardCount: number, rootCount: number): s
   return undefined;
 }
 
-/**
- * Validates CLI args for one subcommand against the flags it actually
- * understands — every arg must match `known` exactly (not just a `--`-prefix
- * check, which let a single-dash typo or a stray positional through
- * unnoticed). An unknown arg must fail loud, never pass through silently.
- */
+// Exact match, not a `--` prefix check: single-dash typos and positionals must not slip through.
 export function cliFlagsError(
   subcommand: string,
   argv: readonly string[],

package/src/_lib/sql-inventory.ts

@@ -108,8 +108,12 @@ export const BLOCKING_SQL_KINDS: ReadonlyArray<SqlInventoryKind> = ["unsafe", "a
 const TS_GLOB = new Bun.Glob("**/*.{ts,tsx}");
 
 // kumiko-platform deliberately returns no scan dirs (0 files) — its docs-samples tree needs its own allowlist review before this guard scans it (follow-up issue).
+export function isSqlScanExcluded(root: RepoRoot): boolean {
+  return root.name === "kumiko-platform";
+}
+
 export function sqlScanDirsFor(root: RepoRoot): readonly string[] {
-  if (root.name === "kumiko-platform") return [];
+  if (isSqlScanExcluded(root)) return [];
   return sourceRootDirs(root).map((dir) => dir.slice(root.absPath.length).replace(/^\/+/, ""));
 }
 

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.335.0",
+    "type": "improvement",
+    "title": "Stricter guard detection for raw-sql, test-template-drift, framed extension sections, runtime-isolation and test-stack-drift",
+    "detail": "Stricter guard detection; app repos that carried an undetected pattern can now turn red.\n- `guard-raw-sql`: only kumiko-platform is skipped. An app repo whose declared `sourceRoots` all do not exist now fails as vacuous (0 files scanned) instead of passing.\n- `test-template-drift`: `...defineAppE2eConfig(...)` spread next to `fullyParallel`, `retries`, `timeout`, `workers` or `expect`, and shorthand `{ viewport }` / `{ deviceScaleFactor }`, are flagged.\n- `no-framed-extension-sections`: an `extensionSectionComponents` registry held in a variable, shorthand or spread is resolved.\n- `runtime-isolation`: entries declared in package.json `kumiko.clientEntry` / `kumiko.clientEntries[].sourceFile` count as browser code.\n- `test-stack-drift`: `@no-server-stack:` only opts out when it sits in a comment, not in a string literal.\n- Direct `run-guards.ts` / `run-ui-guards.ts` / `run-repo-checks.ts` invocations exit with 1 instead of the failure count.",
+    "migration": "App repos that carried a previously undetected pattern can now fail their guards. Fix the reported sites; a vacuous raw-sql scan (all declared sourceRoots missing) must declare existing source roots."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Escape-hatch guards accept only real framework imports, a corrupt cast baseline is an error, hints name kumiko-guards guards",
+    "detail": "The escape-hatch guards now only accept `declareEscapeHatch` and `withUnsafeRawGrant` imported from the framework itself; a local function or an import from another module with the same name no longer satisfies them. A corrupt `.kumiko-cast-baseline.json` is now an error instead of being treated as an empty baseline. Guard hints point at `kumiko-guards guards`."
+  },
   {
     "version": "0.332.0",
     "type": "fix",

package/src/check-as-casts.ts

@@ -48,6 +48,7 @@ import {
   buildSharedProject,
   filesForGuard,
   type GuardOutcome,
+  type GuardViolation,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
@@ -546,26 +547,89 @@ function writeBaseline(all: readonly Site[]): void {
 // Per File:target: aktueller Count gegen baseline. Mehr → Regression.
 // Cast-Tausch (Cast A weg, Cast B mit anderem target hinzu) wird so erkannt
 // obwohl Total stabil bleibt. Nur Report — Warnung, kein Fail.
-function reportBaseline(all: readonly Site[]): void {
+// Merge-conflict markers, truncated writes and hand edits all land here; the
+// file is read once at the boundary so the comparison below can trust its shape.
+function isCountsByFile(value: unknown): value is Record<string, Record<string, number>> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every(
+    (targets) =>
+      typeof targets === "object" &&
+      targets !== null &&
+      !Array.isArray(targets) &&
+      Object.values(targets).every((count) => typeof count === "number"),
+  );
+}
+
+type BaselineLoad =
+  | { kind: "missing" }
+  | { kind: "format-drift"; format: unknown }
+  | { kind: "invalid"; reason: string }
+  | { kind: "ok"; baseline: Baseline };
+
+export function loadBaseline(file: string): BaselineLoad {
+  if (!existsSync(file)) return { kind: "missing" };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (error) {
+    return { kind: "invalid", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { kind: "invalid", reason: "expected a JSON object" };
+  }
+  const record: Record<string, unknown> = { ...parsed };
+  if (record["format"] !== BASELINE_FORMAT_VERSION) {
+    return { kind: "format-drift", format: record["format"] };
+  }
+  const { generated, totalSuspect, perFile } = record;
+  if (
+    typeof generated !== "string" ||
+    typeof totalSuspect !== "number" ||
+    !isCountsByFile(perFile)
+  ) {
+    return {
+      kind: "invalid",
+      reason: "expected { format, generated: string, totalSuspect: number, perFile: object }",
+    };
+  }
+  return {
+    kind: "ok",
+    baseline: { format: BASELINE_FORMAT_VERSION, generated, totalSuspect, perFile },
+  };
+}
+
+export function reportBaseline(
+  all: readonly Site[],
+  baselineFile: string = baselinePath,
+): GuardViolation[] {
   const repoLocalSuspects = repoLocal(suspectByFileAndTarget(all));
   const repoLocalTotal = totalOf(repoLocalSuspects);
 
-  if (!existsSync(baselinePath)) {
+  const loaded = loadBaseline(baselineFile);
+  if (loaded.kind === "missing") {
     console.log(
       "\n  No baseline found. Freeze one with `--write-baseline` first — warning, no fail until then.",
     );
-    return;
+    return [];
   }
-
-  const rawBaseline = JSON.parse(readFileSync(baselinePath, "utf-8")) as Partial<Baseline>;
-  if (rawBaseline.format !== BASELINE_FORMAT_VERSION) {
+  if (loaded.kind === "invalid") {
+    // A corrupt baseline must not read as "no regressions".
+    return [
+      {
+        file: baselineFile,
+        line: 1,
+        message: `Cannot read cast baseline ${baselineFile}: ${loaded.reason}. Fix the file (e.g. resolve merge-conflict markers) or regenerate it with \`bun packages/guards/src/check-as-casts.ts --write-baseline\`.`,
+      },
+    ];
+  }
+  if (loaded.kind === "format-drift") {
     console.log(
-      `\n  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, read format=${rawBaseline.format ?? "<missing>"}.`,
+      `\n  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, read format=${String(loaded.format ?? "<missing>")}.`,
     );
     console.log("  Run `bun packages/guards/src/check-as-casts.ts --write-baseline` once.");
-    return;
+    return [];
   }
-  const baseline = rawBaseline as Baseline;
+  const { baseline } = loaded;
 
   type Regression = { file: string; target: string; baseline: number; current: number };
   const regressions: Regression[] = [];
@@ -602,7 +666,7 @@ function reportBaseline(all: readonly Site[]): void {
         "    3. If a cleanup reduction in one file offsets an increase in another: " +
         "run `bun packages/guards/src/check-as-casts.ts --write-baseline` after committing",
     );
-    return;
+    return [];
   }
 
   console.log(`\n  ✓ Baseline (${baseline.totalSuspect}) — current ${repoLocalTotal}`);
@@ -611,17 +675,21 @@ function reportBaseline(all: readonly Site[]): void {
       `  ✓ ${reduced} suspect cast(s) reduced since baseline. Run \`--write-baseline\` if appropriate.`,
     );
   }
+  return [];
 }
 
 function analyseCasts(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
   const { all, scanned } = scanCasts(files);
   reportCasts(all, scanned);
   reportUnknownReasons(all);
-  if (compareBaseline) reportBaseline(all);
-  else console.log("\n  Baseline comparison skipped (--no-baseline).");
+  if (!compareBaseline) {
+    console.log("\n  Baseline comparison skipped (--no-baseline).");
+    return { violations: [] };
+  }
   // WARNUNG, kein Fail (coding-standards.md → "Type Assertions"): weder
-  // unbekannte @cast-boundary-Reasons noch Baseline-Regression blocken.
-  return { violations: [] };
+  // unbekannte @cast-boundary-Reasons noch Baseline-Regression blocken. Nur
+  // eine unlesbare Baseline schlägt fehl.
+  return { violations: reportBaseline(all) };
 }
 
 export const guard: AstGuard = {

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

@@ -133,6 +133,14 @@ function scanPackageJsonScripts(root: RepoRoot, findings: TextLineFinding[]): nu
   return scanned;
 }
 
+// A bare substring match would accept the entry inside a TOML comment or under
+// another key such as coveragePathIgnorePatterns, which leaves `bun test` unguarded.
+function ignoresRealTests(bunfigToml: string): boolean {
+  const withoutComments = bunfigToml.replace(/^\s*#.*$/gm, "");
+  const match = /^\s*pathIgnorePatterns\s*=\s*\[([^\]]*)\]/m.exec(withoutComments);
+  return match?.[1]?.includes(`"${REAL_TEST_IGNORE_ENTRY}"`) ?? false;
+}
+
 // The generated bunfig template (packages/testing/src/bunfig.ts) is what app
 // and library repos consume via `kumiko-testing bunfig` — the framework repo
 // hand-maintains its own root bunfig*.toml files and doesn't run this
@@ -150,7 +158,7 @@ function bunfigMissingRealExclusion(root: RepoRoot, findings: TextLineFinding[])
       continue;
     }
     scanned++;
-    if (!content.includes(REAL_TEST_IGNORE_ENTRY)) {
+    if (!ignoresRealTests(content)) {
       findings.push({
         file: rel,
         line: 1,

package/src/check-runtime-isolation.ts

@@ -68,9 +68,11 @@ import { type ScanSpec, scanFiles, scanRoots } from "./_lib/scan-scope";
 import {
   classify,
   computeClientReachablePaths,
+  createDirectiveClassifier,
   findRuntimeIsolationViolations,
   isClientEntryPath,
   type Runtime,
+  readDeclaredClientEntries,
 } from "./runtime-isolation-classify";
 
 const SCAN: ScanSpec = { scope: "source", extensions: ["ts", "tsx"] };
@@ -141,11 +143,15 @@ function scanRoot(root: RepoRoot): {
       return !fp.includes("/node_modules/") && !fp.includes("/dist/");
     });
 
+  const declaredClientEntries = readDeclaredClientEntries(root.absPath);
   const workspaceCache = new Map<string, Runtime | null>();
+  const directiveOf = createDirectiveClassifier();
   const clientReachable = computeClientReachablePaths(scannedFiles, (sf) => {
     const rel = path.relative(root.absPath, sf.getFilePath());
-    if (isClientEntryPath(rel)) return true;
-    return classify(sf.getFilePath(), root.absPath, workspaceCache) === "client";
+    if (isClientEntryPath(rel, declaredClientEntries)) return true;
+    return (
+      classify(sf.getFilePath(), root.absPath, workspaceCache, undefined, directiveOf) === "client"
+    );
   });
 
   const { violations: allViolations, outsideRoot } = findRuntimeIsolationViolations(
@@ -153,6 +159,7 @@ function scanRoot(root: RepoRoot): {
     root.absPath,
     workspaceCache,
     clientReachable,
+    directiveOf,
   );
 
   return { allViolations, outsideRoot, scannedFiles: scannedFiles.length };

package/src/cli.ts

@@ -45,6 +45,10 @@ async function main(): Promise<void> {
     process.exit(1);
   }
   const flags = process.argv.slice(3);
+  if (subcommand !== undefined && (flags.includes("--help") || flags.includes("-h"))) {
+    printHelp();
+    process.exit(0);
+  }
 
   if (subcommand === "list") {
     const flagsError = cliFlagsError("list", flags, SUBCOMMAND_FLAGS.list);

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

@@ -13,7 +13,7 @@
  *
  * Usage:
  *   bun guards/guard-access-denied-test.ts
- *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ *   Baseline: kumiko-guards guards --write-security-baseline
  */
 
 import * as path from "node:path";
@@ -117,7 +117,7 @@ export const guard: AstGuard = {
   name: "Access-Denied-Test Guard",
   scan: SCAN,
   security: true,
-  hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `bun guards/run-guards.ts --write-security-baseline`.",
+  hint: "Role-restricted write handlers need a test that references the handler and asserts a caller without the role is rejected (AccessDeniedError / access_denied / 403). Existing gaps are frozen in the security baseline; after closing one: `kumiko-guards guards --write-security-baseline`.",
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     // consumer CI scans only its own repo, so a sibling repo's test must not count as coverage
     const violations: GuardViolation[] = findHandlersWithoutAccessDeniedTest(files, roots).map(

package/src/guard-admin-api.ts

@@ -34,12 +34,11 @@ const SCAN: ScanSpec = { scope: "source", extensions: ["ts"] };
 const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 
 // Allowed callers: migration runners (sample-local, src/ and bin/) +
-// admin scripts + the definition itself + this guard script.
+// admin scripts + the definition itself.
 const ALLOWLIST: readonly RegExp[] = [
   /^samples\/[^/]+\/src\/migration\//,
   /^scripts\/migrations\//,
   /^packages\/framework\/src\/event-store\/admin-api\.ts$/,
-  /^scripts\/guard-admin-api\.ts$/,
 ];
 
 const GUARDED_CALLS = new Set(["appendRaw", "appendRawBatch"]);

package/src/guard-app-feature-structure.ts

@@ -40,8 +40,8 @@ export const guard: AstGuard = {
   name: "App-Feature-Structure Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Konvention: feature.ts nur Registrierung, Screens unter web/ (eine Datei pro Screen), Handler unter handlers/, " +
-    `Domain-Logik unter lib/. Custom-Screens brauchen // ${IGNORE_TAG} <Grund> (deklarative Screen-Typen sind der Default).`,
+    "Convention: feature.ts is registration only, screens live under web/ (one file per screen), handlers under handlers/, " +
+    `domain logic under lib/. Custom screens need // ${IGNORE_TAG} <reason> (declarative screen types are the default).`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     for (const sf of files) {
@@ -56,7 +56,7 @@ export const guard: AstGuard = {
             file: filePath,
             line: 1,
             message:
-              "web-Monolith am Feature-Root — Screens/Client-Def gehören unter web/ (index.ts + eine Datei pro Screen)",
+              "web monolith at feature root — screens/client def belong under web/ (index.ts + one file per screen)",
           });
         }
       }
@@ -74,7 +74,7 @@ export const guard: AstGuard = {
         violations.push({
           file: filePath,
           line: 1,
-          message: "JSX-Komponente am Feature-Root — unter web/ verschieben",
+          message: "JSX component at feature root — move it under web/",
         });
       }
 
@@ -85,7 +85,7 @@ export const guard: AstGuard = {
           violations.push({
             file: filePath,
             line: 1,
-            message: `feature.ts hat ${lines} Zeilen (max ${MAX_FEATURE_TS_LINES}) — Handler nach handlers/, Schemas nach schema/, Logik nach lib/`,
+            message: `feature.ts has ${lines} lines (max ${MAX_FEATURE_TS_LINES}) — move handlers to handlers/, schemas to schema/, logic to lib/`,
           });
         }
       }
@@ -99,11 +99,13 @@ export const guard: AstGuard = {
         // Nur r.screen-Kontext: das umgebende Call-Target muss auf .screen enden.
         const call = prop.getFirstAncestorByKind(SyntaxKind.CallExpression);
         if (call === undefined || !call.getExpression().getText().endsWith(".screen")) continue;
+        // Only the screen's own config declares its type; nested `{ type: "custom" }` objects are widget config.
+        if (prop.getParent() !== call.getArguments()[0]) continue;
         if (hasIgnoreTag(call, IGNORE_TAG) || hasIgnoreTag(prop, IGNORE_TAG)) continue;
         violations.push({
           file: filePath,
           line: prop.getStartLineNumber(),
-          message: `r.screen type:"custom" ohne Allowlist-Tag — deklarativen Screen-Typ nutzen oder // ${IGNORE_TAG} <Grund>`,
+          message: `r.screen type:"custom" without allowlist tag — use a declarative screen type or // ${IGNORE_TAG} <reason>`,
         });
       }
     }

package/src/guard-direct-fetch.ts

@@ -118,7 +118,7 @@ export const guard: AstGuard = {
   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` on the line above. ' +
-    "Local bindings named fetch are flagged (false positive — unblock via that marker or ALLOWLIST in infra/guards/guard-direct-fetch.ts). " +
+    "Local bindings named fetch are flagged (false positive — unblock via that marker). " +
     'Known gap: bracket access (globalThis["fetch"](...)).',
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];

package/src/guard-error-reasons.ts

@@ -60,6 +60,10 @@ const UNPROC_CALL_NAMES = new Set(["UnprocessableError", "failUnprocessable"]);
 // justification, not an error-reason code.
 const ACCESS_DECLARATION_NAMES = new Set(["openToAll", "escapeHatch"]);
 
+// Calls whose object-literal argument carries a prose `reason` for an
+// access grant / escape hatch.
+const ACCESS_DECLARATION_CALLS = new Set(["declareEscapeHatch", "withUnsafeRawGrant"]);
+
 interface Violation {
   readonly file: string;
   readonly line: number;
@@ -135,8 +139,8 @@ function scanFile(sf: SourceFile): Violation[] {
 }
 
 // A `reason` PropertyAssignment whose object literal is the initializer of
-// an `openToAll` / `escapeHatch` PropertyAssignment, or the sole argument
-// object of a bare `declareEscapeHatch(...)` call, is an access-declaration
+// an `openToAll` / `escapeHatch` PropertyAssignment, or an argument
+// object of a bare `declareEscapeHatch(...)` / `withUnsafeRawGrant(...)` call, is an access-declaration
 // justification, not an error-reason code.
 export function isAccessDeclarationReason(prop: Node): boolean {
   const objectLiteral = prop.getParent();
@@ -147,7 +151,7 @@ export function isAccessDeclarationReason(prop: Node): boolean {
   }
   if (owner?.isKind(SyntaxKind.CallExpression)) {
     const callee = owner.getExpression();
-    return callee.isKind(SyntaxKind.Identifier) && callee.getText() === "declareEscapeHatch";
+    return callee.isKind(SyntaxKind.Identifier) && ACCESS_DECLARATION_CALLS.has(callee.getText());
   }
   return false;
 }

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

@@ -46,10 +46,11 @@
  * unresolved and the R2/R3 finding names that explicitly. The declaration
  * does not propagate upward: it covers escalations inside that function's
  * own body, not the function it is nested inside. This detection is purely
- * lexical — the guard matches on the name `declareEscapeHatch`, not on where
- * it was imported from, so a same-named local function clears just as well;
- * consistent with `escapeHatch:` itself, which is likewise never checked for
- * origin. Referenced-by-variable functions, spread options, computed/string
+ * lexical except for origin: `declareEscapeHatch` (and `withUnsafeRawGrant`
+ * for R2) must resolve to an import from `@cosmicdrift/kumiko-framework`
+ * (or, inside the framework package, a relative import into its `src`), so a
+ * same-named local function does not clear. `escapeHatch:` itself is a plain
+ * property and is never checked for origin. Referenced-by-variable functions, spread options, computed/string
  * keys, and a non-literal, non-module-local-const `escapeHatch`/`reason`
  * value are conservatively not recognized (miss, don't falsely clear).
  *
@@ -68,7 +69,7 @@
  *
  * Usage:
  *   bun guards/guard-escape-hatch-declared.ts
- *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ *   Baseline: kumiko-guards guards --write-security-baseline
  */
 import * as path from "node:path";
 import {
@@ -78,6 +79,7 @@ import {
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
+import { isFrameworkImportOf } from "./_lib/framework-import";
 import { isGenericReason, resolveReasonText } from "./_lib/generic-reason";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
@@ -230,7 +232,7 @@ function isExplicitUnsafeRawGrant(call: Node): boolean {
   const receiver = expr.getExpression();
   return (
     receiver.isKind(SyntaxKind.CallExpression) &&
-    receiver.getExpression().getText() === "withUnsafeRawGrant"
+    isFrameworkImportOf(receiver.getExpression(), "withUnsafeRawGrant")
   );
 }
 
@@ -387,9 +389,7 @@ function declareEscapeHatchReasonNode(stmt: Node): Node | undefined {
   const expr = stmt.getExpression();
   if (!expr.isKind(SyntaxKind.CallExpression)) return undefined;
   const callee = expr.getExpression();
-  if (!callee.isKind(SyntaxKind.Identifier) || callee.getText() !== "declareEscapeHatch") {
-    return undefined;
-  }
+  if (!isFrameworkImportOf(callee, "declareEscapeHatch")) return undefined;
   const args = expr.getArguments();
   const arg = args[0];
   if (args.length !== 1 || !arg?.isKind(SyntaxKind.ObjectLiteralExpression)) return undefined;
@@ -471,7 +471,8 @@ function hasDeclaredEscapeHatchStatement(fn: Node): boolean {
     body = fn.getBody();
   }
   if (!body?.isKind(SyntaxKind.Block)) return false;
-  return body.getStatements().some((stmt) => isValidDeclareEscapeHatchCall(stmt));
+  const firstStatement = body.getStatements()[0];
+  return firstStatement !== undefined && isValidDeclareEscapeHatchCall(firstStatement);
 }
 
 function isInsideEscapeHatchDeclaredFunction(node: Node): boolean {
@@ -680,7 +681,7 @@ export function createEscapeHatchGuard(opts: { root: string }): AstGuard {
     name: "Escape-Hatch-Declared Guard",
     scan: SCAN,
     security: true,
-    hint: 'Declare an escape hatch (r.systemScope() on the feature definition, .job.ts/r.job(...) for jobs, or { escapeHatch: { reason: "..." } } on the handler or hook), or remove the ctx.db.raw/unsafeRaw/queryAs|writeAs(system)/unsafeAllTenants access. Baseline after a deliberate reduction: `bun guards/run-guards.ts --write-security-baseline`',
+    hint: 'Declare an escape hatch (r.systemScope() on the feature definition, .job.ts/r.job(...) for jobs, or { escapeHatch: { reason: "..." } } on the handler or hook), or remove the ctx.db.raw/unsafeRaw/queryAs|writeAs(system)/unsafeAllTenants access. Baseline after a deliberate reduction: `kumiko-guards guards --write-security-baseline`',
     run(files) {
       const violations: GuardViolation[] = [
         ...findGenericReasonCalls(files, opts.root).map((f) => ({

package/src/guard-i18n-keys.ts

@@ -63,7 +63,6 @@ function collectUsedKeys(sf: SourceFile): UsedKey[] {
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const exprText = call.getExpression().getText();
     if (exprText !== "t" && !/(^|\.)t$/.test(exprText)) continue;
-    if (exprText === "test" || exprText === "expect") continue;
     const args = call.getArguments();
     if (args.length === 0) continue;
     const first = args[0];

package/src/guard-i18n-locale-terminology.ts

@@ -92,7 +92,7 @@ export function findViolations(files: readonly SourceFile[]): GuardViolation[] {
         violations.push({
           file: sf.getFilePath(),
           line: prop.getStartLineNumber(),
-          message: `[${locale}] verbotener Begriff "${hit}" in Übersetzungswert — nutze "${rule.preferred}" (fw#2200).`,
+          message: `[${locale}] forbidden term "${hit}" in translation value — use "${rule.preferred}" (fw#2200).`,
         });
       }
     }
@@ -104,7 +104,7 @@ export function findViolations(files: readonly SourceFile[]): GuardViolation[] {
 export const guard: AstGuard = {
   name: "i18n-Locale-Terminology Guard",
   scan: SCAN,
-  hint: "DE: Mandant statt Tenant/Organisation; ES: Organización statt tenant-Loanword. Rollen wie TenantAdmin sind OK.",
+  hint: "DE: Mandant instead of Tenant/Organisation; ES: Organización instead of the tenant loanword. Roles like TenantAdmin are fine.",
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations = findViolations(files)
       .map((v) => ({ ...v, file: relFromRepoRoot(v.file, roots) }))

package/src/guard-lib-test-coverage.ts

@@ -29,6 +29,7 @@
 import { dirname, resolve } from "node:path";
 import { Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import { escapeRegExp } from "./_lib/handler-name-forms";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
 
 // isTestFile() classifies by regex on the file's own path, not by which within-glob matched it, so lib/ vs. test classification stays correct regardless of scan-scope resolution.
@@ -116,16 +117,20 @@ function bodyTextWithoutImports(testSf: SourceFile): string {
 }
 
 function referencesName(testSf: SourceFile, name: string): boolean {
-  return new RegExp(`\\b${name}\\b`).test(bodyTextWithoutImports(testSf));
+  // `\b` does not treat `$` as a word character, so identifiers like `format$`
+  // need explicit identifier-char lookarounds.
+  return new RegExp(`(?<![\\w$])${escapeRegExp(name)}(?![\\w$])`).test(
+    bodyTextWithoutImports(testSf),
+  );
 }
 
 export const guard: AstGuard = {
   name: "Lib-Test-Coverage Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Jede lib-Datei mit exportierter Funktion braucht einen Test, der aus dem " +
-    "Modul importiert und jede Funktion namentlich referenziert. IO-Loader, die " +
-    `ein Integrationstest deckt: // ${IGNORE_TAG} <Grund, z.B. integration-covered via …>`,
+    "Every lib file with an exported function needs a test that imports from the " +
+    "module and references each function by name. IO loaders that an " +
+    `integration test covers: // ${IGNORE_TAG} <reason, e.g. integration-covered via …>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
     const testFiles: SourceFile[] = [];
@@ -145,7 +150,7 @@ export const guard: AstGuard = {
         violations.push({
           file: sf.getFilePath(),
           line: 1,
-          message: `Kein Test importiert dieses lib-Modul (${relevant.length} exportierte Funktion(en) ungetestet)`,
+          message: `No test imports this lib module (${relevant.length} exported function(s) untested)`,
         });
         continue;
       }
@@ -155,7 +160,7 @@ export const guard: AstGuard = {
         violations.push({
           file: sf.getFilePath(),
           line: e.node.getStartLineNumber(),
-          message: `Exportierte Funktion "${e.name}" wird in keinem verknüpften Test namentlich referenziert`,
+          message: `Exported function "${e.name}" is not referenced by name in any linked test`,
         });
       }
     }