@cosmicdrift/kumiko-guards 0.334.0 → 0.336.0

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 {
@@ -77,7 +78,9 @@ import {
   type PropertyAssignment,
   type SourceFile,
   SyntaxKind,
+  VariableDeclarationKind,
 } 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 +233,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 +390,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;
@@ -421,12 +422,22 @@ function isExplicitlyUnresolvableReason(node: Node): boolean {
     (decl) =>
       decl.isKind(SyntaxKind.ImportSpecifier) ||
       decl.isKind(SyntaxKind.ImportClause) ||
-      decl.isKind(SyntaxKind.NamespaceImport),
+      decl.isKind(SyntaxKind.NamespaceImport) ||
+      isNonConstVariableDeclaration(decl),
+  );
+}
+
+function isNonConstVariableDeclaration(decl: Node): boolean {
+  if (!decl.isKind(SyntaxKind.VariableDeclaration)) return false;
+  const list = decl.getParent();
+  return (
+    list.isKind(SyntaxKind.VariableDeclarationList) &&
+    list.getDeclarationKind() !== VariableDeclarationKind.Const
   );
 }
 
 const UNRESOLVABLE_REASON_HINT =
-  " A declareEscapeHatch({ reason }) call was found here, but its reason is an import, a function call, or a template with substitutions — none of those can be statically judged, so declareEscapeHatch needs a string literal or a module-local const instead.";
+  " A declareEscapeHatch({ reason }) call was found here, but its reason is an import, a function call, or a template with substitutions (or a `let`/non-`const` binding) — none of those can be statically judged, so declareEscapeHatch needs a string literal or a module-local const instead.";
 
 // Walks the same ancestor chain as isInsideEscapeHatchDeclaredFunction, but
 // looks for a declareEscapeHatch statement whose reason is one of the three
@@ -471,7 +482,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 +692,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-fake-tests.ts

@@ -77,40 +77,47 @@ function isDirectAssertionCall(call: CallExpression): boolean {
   return ASSERTION_API_METHODS.has(name);
 }
 
-// A bare identifier `foo(...)` counts as an assertion when `foo` is declared
-// in the SAME file (function declaration, or a variable initialized with an
-// arrow/function expression, at any nesting level) and its own body asserts —
+// A bare identifier `foo(...)` counts as an assertion when `foo` resolves
+// (by symbol, so a same-named helper in another scope is not confused with it)
+// to a declaration in the SAME file (function declaration, or a variable
+// initialized with an arrow/function expression) whose own body asserts —
 // recursively, so a chain of thin wrappers around expect() still counts.
-function resolveSameFileHelper(sf: SourceFile, name: string): Node | undefined {
-  const fn = sf
-    .getDescendantsOfKind(SyntaxKind.FunctionDeclaration)
-    .find((f) => f.getName() === name);
-  if (fn) return fn;
-  const varDecl = sf
-    .getDescendantsOfKind(SyntaxKind.VariableDeclaration)
-    .find((v) => v.getName() === name);
-  const init = varDecl?.getInitializer();
-  if (
-    init &&
-    (init.isKind(SyntaxKind.ArrowFunction) || init.isKind(SyntaxKind.FunctionExpression))
-  ) {
-    return init;
+function resolveSameFileHelper(sf: SourceFile, identifier: Node): Node | undefined {
+  for (const decl of identifier.getSymbol()?.getDeclarations() ?? []) {
+    if (decl.getSourceFile() !== sf) continue;
+    if (decl.isKind(SyntaxKind.FunctionDeclaration)) return decl;
+    if (!decl.isKind(SyntaxKind.VariableDeclaration)) continue;
+    const init = decl.getInitializer();
+    if (
+      init &&
+      (init.isKind(SyntaxKind.ArrowFunction) || init.isKind(SyntaxKind.FunctionExpression))
+    ) {
+      return init;
+    }
   }
   return undefined;
 }
 
-// depth limit + visited set: a helper chain deeper than the limit is treated
-// as unproven (violation), and a recursive helper never infinite-loops.
-function bodyHasAssertion(node: Node, sf: SourceFile, depth: number, visited: Set<Node>): boolean {
-  if (visited.has(node)) return false;
-  visited.add(node);
+// depth limit + shallowest-visit memo: a helper chain deeper than the limit is
+// treated as unproven (violation), a recursive helper never infinite-loops, and
+// a helper first reached at the depth limit is still explored when reached
+// again via a shorter path.
+function bodyHasAssertion(
+  node: Node,
+  sf: SourceFile,
+  depth: number,
+  shallowestVisit: Map<Node, number>,
+): boolean {
+  const seenAt = shallowestVisit.get(node);
+  if (seenAt !== undefined && seenAt <= depth) return false;
+  shallowestVisit.set(node, depth);
   for (const call of node.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     if (isDirectAssertionCall(call)) return true;
     if (depth >= MAX_HELPER_DEPTH) continue;
     const expr = call.getExpression();
     if (!expr.isKind(SyntaxKind.Identifier)) continue;
-    const helper = resolveSameFileHelper(sf, expr.getText());
-    if (helper && bodyHasAssertion(helper, sf, depth + 1, visited)) return true;
+    const helper = resolveSameFileHelper(sf, expr);
+    if (helper && bodyHasAssertion(helper, sf, depth + 1, shallowestVisit)) return true;
   }
   return false;
 }
@@ -141,7 +148,7 @@ function scanFile(sf: SourceFile): Violation[] {
     const isArrowOrFn =
       body.isKind(SyntaxKind.ArrowFunction) || body.isKind(SyntaxKind.FunctionExpression);
     if (!isArrowOrFn) continue;
-    const hasAssertion = bodyHasAssertion(body, sf, 0, new Set());
+    const hasAssertion = bodyHasAssertion(body, sf, 0, new Map());
     if (!hasAssertion) {
       const nameArg = args[0]?.getText().slice(0, 50) ?? "<anonymous>";
       violations.push({

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

@@ -44,7 +44,7 @@ const RULES: Record<"de" | "es", LocaleRule> = {
     // Tenants? covers plural; Organisation(en|s)? without trailing \b so
     // compounds like Organisations-ID / Organisationsstruktur still match
     // (infra#603). TenantAdmin stays safe: \b after Tenant fails on 'A'.
-    forbidden: [/\bTenants?\b/i, /\bOrganisation(en|s)?/],
+    forbidden: [/\bTenants?\b/i, /\bOrganisation(en|s)?/i],
   },
   es: {
     preferred: "Organización",
@@ -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`,
         });
       }
     }

package/src/guard-no-custom-primitives.ts

@@ -28,6 +28,7 @@ import {
   compareToBaseline,
   filesForGuard,
   type GuardViolation,
+  relativeToCwd,
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
@@ -66,7 +67,7 @@ function collectRawFormHtml(sf: SourceFile): RawFormFinding[] {
     if (!RAW_FORM_TAGS.has(tag)) continue;
     if (hasIgnoreTag(el, IGNORE_TAG)) continue;
     findings.push({
-      file: path.relative(ROOT, sf.getFilePath()),
+      file: relativeToCwd(sf.getFilePath()),
       line: el.getStartLineNumber(),
       tag,
     });
@@ -146,7 +147,7 @@ function analyse(
       if (!PRIMITIVE_NAME.test(c.name)) continue;
       if (hasIgnoreTag(c.node, IGNORE_TAG)) continue;
       violations.push({
-        file: sf.getFilePath(),
+        file: relativeToCwd(sf.getFilePath()),
         line: c.line,
         message: `App-local UI primitive "${c.name}" — use a framework widget/primitive`,
       });

package/src/guard-no-framed-extension-sections.ts

@@ -34,7 +34,13 @@
 // two; no usage site found at all, or any other mount kind, stays flagged.
 
 import * as path from "node:path";
-import { Node, type ObjectLiteralExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  Node,
+  type ObjectLiteralExpression,
+  type SourceFile,
+  SyntaxKind,
+  VariableDeclarationKind,
+} from "ts-morph";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
 
@@ -59,32 +65,93 @@ function isExternalSourceFile(sf: SourceFile): boolean {
   return sf.getFilePath().includes("/node_modules/");
 }
 
+function stringConstantValue(node: Node): string | undefined {
+  if (Node.isStringLiteral(node) || Node.isNoSubstitutionTemplateLiteral(node)) {
+    return node.getLiteralText();
+  }
+  if (Node.isAsExpression(node)) return stringConstantValue(node.getExpression());
+  if (!Node.isIdentifier(node)) return undefined;
+  const symbol = node.getSymbol();
+  const resolved = symbol?.isAlias() ? symbol.getAliasedSymbol() : symbol;
+  for (const decl of resolved?.getDeclarations() ?? []) {
+    if (!Node.isVariableDeclaration(decl)) continue;
+    if (decl.getVariableStatement()?.getDeclarationKind() !== VariableDeclarationKind.Const) {
+      continue;
+    }
+    const init = decl.getInitializer();
+    const value = init === undefined ? undefined : stringConstantValue(init);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+// Registry keys and `__component` usages meet on the resolved string value, so
+// two features' same-named local consts don't collide and a literal never
+// matches a computed key. An unresolvable identifier keeps a name-based key
+// that no literal can equal, which leaves the component conservatively flagged.
+function registryKeyFor(node: Node): string {
+  return stringConstantValue(node) ?? `unresolved:${node.getText()}`;
+}
+
+function addRegistryMembers(
+  sf: SourceFile,
+  literal: ObjectLiteralExpression,
+  entries: Map<string, string>,
+  visited: Set<Node>,
+): void {
+  if (visited.has(literal)) return;
+  visited.add(literal);
+  for (const member of literal.getProperties()) {
+    // { NOTES_SECTION_EXTENSION_NAME: NotesSection } (PropertyAssignment,
+    // possibly computed-key) or { NotesSection } (ShorthandPropertyAssignment).
+    if (Node.isPropertyAssignment(member)) {
+      const valueInit = member.getInitializer();
+      if (valueInit === undefined || valueInit.getKind() !== SyntaxKind.Identifier) continue;
+      const nameNode = member.getNameNode();
+      const key = Node.isComputedPropertyName(nameNode)
+        ? registryKeyFor(nameNode.getExpression())
+        : Node.isStringLiteral(nameNode)
+          ? nameNode.getLiteralValue()
+          : member.getName();
+      entries.set(valueInit.getText(), key);
+    } else if (Node.isShorthandPropertyAssignment(member)) {
+      const name = member.getName();
+      entries.set(name, name);
+    } else if (Node.isSpreadAssignment(member)) {
+      addRegistryFromExpression(sf, member.getExpression(), entries, visited);
+    }
+  }
+}
+
+// The registry may be inline, a same-file variable (`extensionSectionComponents:
+// shared`, `{ extensionSectionComponents }`) or spread in (`{ ...shared }`).
+function addRegistryFromExpression(
+  sf: SourceFile,
+  expression: Node,
+  entries: Map<string, string>,
+  visited: Set<Node>,
+): void {
+  if (Node.isObjectLiteralExpression(expression)) {
+    addRegistryMembers(sf, expression, entries, visited);
+    return;
+  }
+  if (!Node.isIdentifier(expression)) return;
+  const init = sf.getVariableDeclaration(expression.getText())?.getInitializer();
+  if (init !== undefined) addRegistryFromExpression(sf, init, entries, visited);
+}
+
 /** Maps each registered component's identifier to the registry key usage sites reference via `__component: SOME_CONST`. */
 function findExtensionComponentEntries(sf: SourceFile): Map<string, string> {
   const entries = new Map<string, string>();
+  const visited = new Set<Node>();
   for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
     if (prop.getName() !== "extensionSectionComponents") continue;
     const init = prop.getInitializer();
-    if (init === undefined || init.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
-    for (const member of init.asKindOrThrow(SyntaxKind.ObjectLiteralExpression).getProperties()) {
-      // { NOTES_SECTION_EXTENSION_NAME: NotesSection } (PropertyAssignment,
-      // possibly computed-key) or { NotesSection } (ShorthandPropertyAssignment).
-      if (member.getKind() === SyntaxKind.PropertyAssignment) {
-        const pa = member.asKindOrThrow(SyntaxKind.PropertyAssignment);
-        const valueInit = pa.getInitializer();
-        if (valueInit === undefined || valueInit.getKind() !== SyntaxKind.Identifier) continue;
-        const nameNode = pa.getNameNode();
-        const key = Node.isComputedPropertyName(nameNode)
-          ? nameNode.getExpression().getText()
-          : Node.isStringLiteral(nameNode)
-            ? nameNode.getLiteralValue()
-            : pa.getName();
-        entries.set(valueInit.getText(), key);
-      } else if (member.getKind() === SyntaxKind.ShorthandPropertyAssignment) {
-        const name = member.asKindOrThrow(SyntaxKind.ShorthandPropertyAssignment).getName();
-        entries.set(name, name);
-      }
-    }
+    if (init !== undefined) addRegistryFromExpression(sf, init, entries, visited);
+  }
+  for (const prop of sf.getDescendantsOfKind(SyntaxKind.ShorthandPropertyAssignment)) {
+    if (prop.getName() !== "extensionSectionComponents") continue;
+    addRegistryFromExpression(sf, prop.getNameNode(), entries, visited);
   }
   return entries;
 }
@@ -259,11 +326,8 @@ function findComponentNameUsages(sf: SourceFile): { name: string; kind: MountKin
     if (prop.getName() !== "__component") continue;
     const init = prop.getInitializer();
     if (init === undefined) continue;
-    const name = Node.isStringLiteral(init)
-      ? init.getLiteralValue()
-      : Node.isIdentifier(init)
-        ? init.getText()
-        : undefined;
+    const name =
+      Node.isStringLiteral(init) || Node.isIdentifier(init) ? registryKeyFor(init) : undefined;
     if (name === undefined) continue;
     usages.push({ name, kind: mountKindFor(prop) });
   }

package/src/guard-no-inline-styles.ts

@@ -5,7 +5,13 @@
 // Part of App-Mounting 2.0 (infra#208).
 
 import { type SourceFile, SyntaxKind } from "ts-morph";
-import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relativeToCwd,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
 
 const SCAN: ScanSpec = {
@@ -30,7 +36,7 @@ export const guard: AstGuard = {
         if (attr.getNameNode().getText() !== "style") continue;
         if (hasIgnoreTag(attr, IGNORE_TAG)) continue;
         violations.push({
-          file: sf.getFilePath(),
+          file: relativeToCwd(sf.getFilePath()),
           line: attr.getStartLineNumber(),
           message: "style= prop in app code (use theme tokens/widgets)",
         });
@@ -45,7 +51,7 @@ export const guard: AstGuard = {
         if (name !== "CSSProperties" && name !== "React.CSSProperties") continue;
         if (hasIgnoreTag(ref, IGNORE_TAG)) continue;
         violations.push({
-          file: sf.getFilePath(),
+          file: relativeToCwd(sf.getFilePath()),
           line: ref.getStartLineNumber(),
           message: "CSSProperties style object in app code (use theme tokens/widgets)",
         });

package/src/guard-no-logic-in-views.ts

@@ -19,7 +19,13 @@ import {
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
-import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relativeToCwd,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
 
 const SCAN: ScanSpec = {
@@ -134,7 +140,7 @@ export const guard: AstGuard = {
         if (name === "" || !isViewLogic(name, fn)) continue;
         if (hasIgnoreTag(fn, IGNORE_TAG)) continue;
         violations.push({
-          file: sf.getFilePath(),
+          file: relativeToCwd(sf.getFilePath()),
           line: fn.getStartLineNumber(),
           message: `View logic "${name}" belongs in lib/ (with a test) — web/ only components/hooks`,
         });

package/src/guard-no-raw-hooks.ts

@@ -11,7 +11,13 @@
 // Part of App-Mounting 2.0 (infra#208).
 
 import { Node, type SourceFile, SyntaxKind } from "ts-morph";
-import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relativeToCwd,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
 
 // Match property/identifier names instead of call text — otherwise
@@ -40,7 +46,8 @@ export const guard: AstGuard = {
   name: "No-Raw-Hooks Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Use the framework hook set: useQuery (live: true for SSE), useMutation, useDisclosure. " +
+    "Use the framework hook set: useQuery (live: true for SSE), useMutation, useDisclosure, " +
+    "useReportStepComplete (wizard extension steps). " +
     `Real special case (DOM integration or similar): // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];
@@ -52,7 +59,7 @@ export const guard: AstGuard = {
         if (BANNED_HOOKS.has(name)) {
           if (hasIgnoreTag(call, IGNORE_TAG)) continue;
           violations.push({
-            file: sf.getFilePath(),
+            file: relativeToCwd(sf.getFilePath()),
             line: call.getStartLineNumber(),
             message: `${name} in App-Screen — use framework hooks (useQuery/useMutation/useDisclosure)`,
           });
@@ -61,7 +68,7 @@ export const guard: AstGuard = {
         if (name === "fetch") {
           if (hasIgnoreTag(call, IGNORE_TAG)) continue;
           violations.push({
-            file: sf.getFilePath(),
+            file: relativeToCwd(sf.getFilePath()),
             line: call.getStartLineNumber(),
             message: "fetch() in App-Screen — use useQuery/useMutation or an API client (*.ts)",
           });

package/src/guard-open-to-all-reason.ts

@@ -12,7 +12,7 @@
  *
  * Usage:
  *   bun guards/guard-open-to-all-reason.ts
- *   Baseline: bun guards/run-guards.ts --write-security-baseline
+ *   Baseline: kumiko-guards guards --write-security-baseline
  */
 import * as path from "node:path";
 import { type SourceFile, SyntaxKind } from "ts-morph";
@@ -85,7 +85,7 @@ export function createOpenToAllReasonGuard(opts: { root: string }): AstGuard {
     name: "Open-To-All-Reason Guard",
     scan: SCAN,
     security: true,
-    hint: 'Provide openToAll: { reason: "<why any authenticated user may call this>" } (+ personalData: "tenant-members" for write handlers with unbound personal data). Baseline after a deliberate reduction: `bun guards/run-guards.ts --write-security-baseline`',
+    hint: 'Provide openToAll: { reason: "<why any authenticated user may call this>" } (+ personalData: "tenant-members" for write handlers with unbound personal data). Baseline after a deliberate reduction: `kumiko-guards guards --write-security-baseline`',
     run(files) {
       const violations: GuardViolation[] = [
         ...findGenericOpenToAllReasons(files, opts.root).map((f) => ({

package/src/guard-primitives-discipline.ts

@@ -167,10 +167,11 @@ function walk(dir: string, out: string[]): void {
 }
 
 function buildTagPattern(tag: string): RegExp {
-  // Match `<tag` at the JSX opening: after whitespace, a paren, or >.
+  // Match `<tag` at the JSX opening: at line start or after a char that can't
+  // end an identifier/member access (`cond?<input/>:<div/>` hits, `Array<input` doesn't).
   // Negative lookahead `[a-zA-Z0-9-]` so `<input` doesn't match `<inputfoo`.
   // Doesn't match the closing tag (`</tag>`) — that would be redundant.
-  return new RegExp(`(^|[\\s(>{,;])<${tag}(?![a-zA-Z0-9-])`, "u");
+  return new RegExp(`(^|[^\\w$.])<${tag}(?![a-zA-Z0-9-])`, "u");
 }
 
 const TAG_PATTERNS = FORBIDDEN_TAGS.map((t) => ({ ...t, pattern: buildTagPattern(t.tag) }));

package/src/guard-raw-classname.ts

@@ -9,7 +9,13 @@
 // respective migration PR (ui-guards input in _app-test.yml).
 
 import { type JsxAttribute, type SourceFile, SyntaxKind } from "ts-morph";
-import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relativeToCwd,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
 
 const SCAN: ScanSpec = {
@@ -97,7 +103,7 @@ export const guard: AstGuard = {
           const bad = offendingTokens(part.text);
           if (bad.length === 0) continue;
           violations.push({
-            file: sf.getFilePath(),
+            file: relativeToCwd(sf.getFilePath()),
             line: part.line,
             message: `design-bearing Tailwind classes in app code: ${bad.join(", ")}`,
           });

package/src/guard-raw-sql.ts

@@ -14,7 +14,12 @@
 
 import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
-import { BLOCKING_SQL_KINDS, scanRepo, sqlScanDirsFor } from "./_lib/sql-inventory";
+import {
+  BLOCKING_SQL_KINDS,
+  isSqlScanExcluded,
+  scanRepo,
+  sqlScanDirsFor,
+} from "./_lib/sql-inventory";
 
 export type RawSqlFinding = {
   readonly repo: string;
@@ -65,8 +70,9 @@ export const check: RepoCheck = {
     "Rule: runtime SQL only in db/queries/*, bun-db/query.ts, testing/*, or with " +
     "// kumiko-lint-ignore raw-sql <reason> on the line or the line above.",
   async run(roots) {
-    // kumiko-platform's deliberate empty scan-dir list must not read as vacuous (infra#610).
-    const applicableRoots = roots.filter((r) => sqlScanDirsFor(r).length > 0);
+    // Only the deliberate exclusion is skipped; a repo whose declared source roots
+    // are all missing stays in the scan so 0 files surfaces as vacuous.
+    const applicableRoots = roots.filter((r) => !isSqlScanExcluded(r));
     if (applicableRoots.length === 0) {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }