@cosmicdrift/kumiko-guards 0.362.0 → 0.364.0

package/src/guard-agent-docs-drift.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+/**
+ * Guard: the generated agent docs under `packages/framework/agents/` must
+ * match what `bun run gen:agent-docs` renders from the current sources
+ * (feature manifest, renderer-web exports, sample recipes), and every
+ * `agents/<file>.md` path the hand-written `packages/framework/AGENTS.md`
+ * points at must exist in that generated set.
+ *
+ * Only the framework repo itself has these files; consumer repos are
+ * `notApplicable`.
+ *
+ * Usage:
+ *   bun guard-agent-docs-drift.ts
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_DOCS_DIR, readAgentDocsOnDisk, renderAgentDocs } from "./_lib/agent-docs";
+import {
+  type GuardViolation,
+  type RepoCheck,
+  type RepoCheckOutcome,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import type { RepoRoot } from "./_lib/roots";
+
+const FRAMEWORK_PACKAGE_JSON_REL = "packages/framework/package.json";
+const FRAMEWORK_PACKAGE_NAME = "@cosmicdrift/kumiko-framework";
+const AGENTS_MD_REL = "packages/framework/AGENTS.md";
+const AGENTS_REF_RE = /`agents\/([A-Za-z0-9._/-]+\.md)`/g;
+const REGENERATE_HINT = "run `bun run gen:agent-docs` and commit the result";
+
+function isFrameworkRepo(root: RepoRoot): boolean {
+  const packageJsonPath = join(root.absPath, FRAMEWORK_PACKAGE_JSON_REL);
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "name" in parsed &&
+      parsed.name === FRAMEWORK_PACKAGE_NAME
+    );
+  } catch {
+    return false;
+  }
+}
+
+function firstDifferingLine(expected: string, actual: string): number {
+  const expectedLines = expected.split("\n");
+  const actualLines = actual.split("\n");
+  const length = Math.max(expectedLines.length, actualLines.length);
+  for (let index = 0; index < length; index++) {
+    if (expectedLines[index] !== actualLines[index]) return index + 1;
+  }
+  return 1;
+}
+
+function agentsMdReferenceViolations(
+  absPath: string,
+  generated: ReadonlyMap<string, string>,
+): GuardViolation[] {
+  const agentsMdPath = join(absPath, AGENTS_MD_REL);
+  if (!existsSync(agentsMdPath)) return [];
+  const violations: GuardViolation[] = [];
+  const lines = readFileSync(agentsMdPath, "utf-8").split("\n");
+  lines.forEach((text, index) => {
+    for (const match of text.matchAll(AGENTS_REF_RE)) {
+      const key = match[1];
+      if (key === undefined || generated.has(key)) continue;
+      violations.push({
+        file: AGENTS_MD_REL,
+        line: index + 1,
+        message: `references agents/${key}, which is not generated. Fix the reference or add the source (an example needs samples/recipes/<slug>/package.json).`,
+      });
+    }
+  });
+  return violations;
+}
+
+function rootViolations(absPath: string): { violations: GuardViolation[]; fileCount: number } {
+  const generated = renderAgentDocs(absPath);
+  const onDisk = readAgentDocsOnDisk(absPath);
+  const violations: GuardViolation[] = [];
+  for (const [rel, expected] of generated) {
+    const file = `${AGENT_DOCS_DIR}/${rel}`;
+    const actual = onDisk.get(rel);
+    if (actual === undefined) {
+      violations.push({
+        file,
+        line: 1,
+        message: `generated file is missing; ${REGENERATE_HINT}`,
+      });
+    } else if (actual !== expected) {
+      violations.push({
+        file,
+        line: firstDifferingLine(expected, actual),
+        message: `content differs from the generated output; ${REGENERATE_HINT}`,
+      });
+    }
+  }
+  for (const rel of onDisk.keys()) {
+    if (generated.has(rel)) continue;
+    violations.push({
+      file: `${AGENT_DOCS_DIR}/${rel}`,
+      line: 1,
+      message: `stale file no longer produced by the generator; ${REGENERATE_HINT}`,
+    });
+  }
+  violations.push(...agentsMdReferenceViolations(absPath, generated));
+  return { violations, fileCount: generated.size };
+}
+
+export const check: RepoCheck = {
+  name: "agent-docs-drift",
+  hint: "Run `bun run gen:agent-docs` and commit packages/framework/agents/.",
+  run(roots): RepoCheckOutcome {
+    const frameworkRoots = roots.filter(isFrameworkRepo);
+    if (frameworkRoots.length === 0) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+    const violations: GuardViolation[] = [];
+    let matchedFiles = 0;
+    for (const root of frameworkRoots) {
+      const result = rootViolations(root.absPath);
+      violations.push(...result.violations);
+      matchedFiles += result.fileCount;
+    }
+    return { violations, matchedFiles, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-comment-lang.ts

@@ -36,12 +36,16 @@ const SCAN: ScanSpec = {
 
 const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
 
+// Case-sensitive lower case: an upper-case licence name or a capitalised name
+// must not count, and a single short marker that is also an English word is
+// not enough.
 const DE_MARKER_RE =
-  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/i;
+  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/g;
+const MIN_DE_MARKER_HITS = 2;
 const UMLAUT_RE = /[äöüÄÖÜß]/;
 
 export function isGermanComment(text: string): boolean {
-  return DE_MARKER_RE.test(text) || UMLAUT_RE.test(text);
+  return UMLAUT_RE.test(text) || (text.match(DE_MARKER_RE)?.length ?? 0) >= MIN_DE_MARKER_HITS;
 }
 
 export type Site = {
@@ -68,13 +72,8 @@ function germanCommentSite(
   };
 }
 
-// After these tokens a `/` is division, not the start of a regex literal.
-const DIVISION_PRECEDING_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
-  ts.SyntaxKind.Identifier,
-  ts.SyntaxKind.ThisKeyword,
-  ts.SyntaxKind.TrueKeyword,
-  ts.SyntaxKind.FalseKeyword,
-  ts.SyntaxKind.NullKeyword,
+// Tokens that end an operand without being identifiers or keywords.
+const OPERAND_END_PUNCTUATION_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.NumericLiteral,
   ts.SyntaxKind.BigIntLiteral,
   ts.SyntaxKind.StringLiteral,
@@ -88,6 +87,42 @@ const DIVISION_PRECEDING_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.MinusMinusToken,
 ]);
 
+// Reserved words after which an expression (so possibly a regex) starts.
+const EXPRESSION_INTRODUCING_KEYWORDS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.ReturnKeyword,
+  ts.SyntaxKind.TypeOfKeyword,
+  ts.SyntaxKind.InstanceOfKeyword,
+  ts.SyntaxKind.InKeyword,
+  ts.SyntaxKind.CaseKeyword,
+  ts.SyntaxKind.VoidKeyword,
+  ts.SyntaxKind.DeleteKeyword,
+  ts.SyntaxKind.ThrowKeyword,
+  ts.SyntaxKind.NewKeyword,
+  ts.SyntaxKind.YieldKeyword,
+  ts.SyntaxKind.AwaitKeyword,
+  ts.SyntaxKind.ElseKeyword,
+  ts.SyntaxKind.DoKeyword,
+  ts.SyntaxKind.ExtendsKeyword,
+  ts.SyntaxKind.DefaultKeyword,
+]);
+
+function isIdentifierOrKeyword(kind: ts.SyntaxKind): boolean {
+  return (
+    kind === ts.SyntaxKind.Identifier ||
+    (kind >= ts.SyntaxKind.FirstKeyword && kind <= ts.SyntaxKind.LastKeyword)
+  );
+}
+
+// After an operand end a `/` is division, not the start of a regex literal.
+// Contextual keywords (`from`, `type`, `of`, ...) scan as keyword kinds but are
+// valid member and variable names, so every non-introducing keyword counts. A `!`
+// is the non-null postfix only when the token before it ended an operand.
+function isOperandEnd(kind: ts.SyntaxKind, previousEndedOperand: boolean): boolean {
+  if (kind === ts.SyntaxKind.ExclamationToken) return previousEndedOperand;
+  if (OPERAND_END_PUNCTUATION_KINDS.has(kind)) return true;
+  return isIdentifierOrKeyword(kind) && !EXPRESSION_INTRODUCING_KEYWORDS.has(kind);
+}
+
 const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
   ts.SyntaxKind.SingleLineCommentTrivia,
   ts.SyntaxKind.MultiLineCommentTrivia,
@@ -101,11 +136,9 @@ const TRIVIA_KINDS: ReadonlySet<ts.SyntaxKind> = new Set([
 function rescanSlashAsRegex(
   scanner: ts.Scanner,
   kind: ts.SyntaxKind,
-  previousSignificant: ts.SyntaxKind | undefined,
+  previousEndedOperand: boolean,
 ): ts.SyntaxKind {
-  if (previousSignificant !== undefined && DIVISION_PRECEDING_KINDS.has(previousSignificant)) {
-    return kind;
-  }
+  if (previousEndedOperand) return kind;
   const reScanned = scanner.reScanSlashToken();
   return reScanned === ts.SyntaxKind.RegularExpressionLiteral ? reScanned : kind;
 }
@@ -135,7 +168,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
 
   const templateBraceDepths: number[] = [];
   let braceDepth = 0;
-  let previousSignificant: ts.SyntaxKind | undefined;
+  let previousEndedOperand = false;
 
   let kind = scanner.scan();
   while (kind !== ts.SyntaxKind.EndOfFileToken) {
@@ -153,7 +186,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
       }
       case ts.SyntaxKind.SlashToken:
       case ts.SyntaxKind.SlashEqualsToken:
-        kind = rescanSlashAsRegex(scanner, kind, previousSignificant);
+        kind = rescanSlashAsRegex(scanner, kind, previousEndedOperand);
         break;
       case ts.SyntaxKind.TemplateHead:
       case ts.SyntaxKind.TemplateMiddle:
@@ -173,7 +206,7 @@ export function scanGermanComments(fullText: string, file: string): Site[] {
       default:
         break;
     }
-    if (!TRIVIA_KINDS.has(kind)) previousSignificant = kind;
+    if (!TRIVIA_KINDS.has(kind)) previousEndedOperand = isOperandEnd(kind, previousEndedOperand);
     kind = scanner.scan();
   }
   return sites;
@@ -234,21 +267,20 @@ function gitOrFail(args: readonly string[], cwd: string, message: string): strin
 const REWRITE_HINT = `Translate new German comments to English (why, not what), or if deliberate:\n    // ${IGNORE_TAG} <reason>`;
 
 function runTouchedMode(
-  all: readonly Site[],
   argv: readonly string[],
   root: string,
-  repoLocalScannedFiles: number,
+  repoLocalScannedFiles: ReadonlySet<string>,
 ): number {
   const baseArg = argv.find((arg) => arg.startsWith(BASE_FLAG_PREFIX));
   const baseRef = baseArg ? baseArg.slice(BASE_FLAG_PREFIX.length) : "origin/main";
   if (baseRef.startsWith("-")) {
     throw new CommentLangFailure(
-      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref.`,
+      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref. Pass a ref name such as origin/main.`,
     );
   }
 
   // No repo-local file scanned at all must not read as clean (vacuous pass).
-  if (repoLocalScannedFiles === 0) {
+  if (repoLocalScannedFiles.size === 0) {
     console.log("  Touched mode: 0 repo-local files scanned — not applicable, no failure.");
     return 0;
   }
@@ -256,7 +288,7 @@ function runTouchedMode(
   const gitToplevel = gitOrFail(
     ["rev-parse", "--show-toplevel"],
     root,
-    "Touched mode: no git repository found.",
+    "Touched mode: no git repository found. Run it inside a git checkout.",
   ).trim();
   const mergeBase = gitOrFail(
     ["merge-base", baseRef, "HEAD"],
@@ -265,35 +297,37 @@ function runTouchedMode(
   ).trim();
   // -z: NUL-terminated and unquoted, so non-ASCII paths still match the lookup below.
   const touchedFiles = gitOrFail(
-    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase],
+    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase, "HEAD"],
     gitToplevel,
-    "Touched mode: git diff --name-only failed.",
+    "Touched mode: git diff --name-only failed. Check the git error below and that the base ref is reachable.",
   )
     .split("\0")
     .filter(Boolean);
 
-  // Sites are keyed relative to root, git output relative to the toplevel;
-  // a silent mismatch would read as "no violations".
-  const sitesByGitFile = new Map<string, Site[]>();
-  for (const site of all.filter(isLocalFinding)) {
-    const gitRelPath = path.relative(gitToplevel, path.resolve(root, site.file));
-    sitesByGitFile.set(gitRelPath, [...(sitesByGitFile.get(gitRelPath) ?? []), site]);
-  }
-
+  // The commits being pushed are checked, not the working tree: contents come from
+  // HEAD so line numbers match the `mergeBase..HEAD` diff. Scan scope is keyed
+  // relative to root, git output relative to the toplevel.
   const violations: Array<{ file: string; sites: Site[] }> = [];
   for (const file of touchedFiles) {
-    const candidates = sitesByGitFile.get(file);
-    if (!candidates || candidates.length === 0) continue;
+    const rootRelFile = path.relative(root, path.resolve(gitToplevel, file));
+    if (!repoLocalScannedFiles.has(rootRelFile)) continue;
     // --literal-pathspecs: filenames with glob magic must match themselves.
+    const headContent = gitOrFail(
+      ["--literal-pathspecs", "show", `HEAD:${file}`],
+      gitToplevel,
+      `Touched mode: git show HEAD:${file} failed. Check the git error below.`,
+    );
+    const candidates = scanGermanComments(headContent, rootRelFile);
+    if (candidates.length === 0) continue;
     const addedLines = parseAddedLineRanges(
       gitOrFail(
-        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "--", file],
+        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "HEAD", "--", file],
         gitToplevel,
-        `Touched mode: git diff --unified=0 failed for ${file}.`,
+        `Touched mode: git diff --unified=0 failed for ${file}. Check the git error below.`,
       ),
     );
     const touchedSites = sitesTouchedByAddedLines(candidates, addedLines);
-    if (touchedSites.length > 0) violations.push({ file, sites: touchedSites });
+    if (touchedSites.length > 0) violations.push({ file: rootRelFile, sites: touchedSites });
   }
 
   if (violations.length === 0) {
@@ -470,25 +504,27 @@ export function runCommentLangCli(
   try {
     const all: Site[] = [];
     let scanned = 0;
-    let repoLocalScanned = 0;
+    const repoLocalScanned = new Set<string>();
     for (const absPath of scanFiles(SCAN, resolveRepoRoots(root))) {
       if (EXCLUDE.test(absPath)) continue;
       scanned++;
       const file = path.relative(root, absPath);
-      if (isLocalFinding({ file })) repoLocalScanned++;
+      if (isLocalFinding({ file })) repoLocalScanned.add(file);
       all.push(...scanGermanComments(readFileSync(absPath, "utf-8"), file));
     }
 
     // Zero scanned files must not read as a clean pass (misresolved root, empty scope).
     if (scanned === 0) {
-      throw new CommentLangFailure("Scanned 0 files — repo root or scan scope did not resolve.");
+      throw new CommentLangFailure(
+        "Scanned 0 files — repo root or scan scope did not resolve. Run it from inside a repo checkout whose kumiko.json declares the source roots.",
+      );
     }
 
     console.log(
       `Comment-Language Audit: ${scanned} files checked, ${all.length} German comment(s) found.`,
     );
 
-    if (argv.includes("--touched")) return runTouchedMode(all, argv, root, repoLocalScanned);
+    if (argv.includes("--touched")) return runTouchedMode(argv, root, repoLocalScanned);
     if (argv.includes("--list")) {
       for (const site of all.slice(0, LIST_LIMIT)) {
         console.log(`  ${site.file}:${site.line}  ${site.snippet}`);

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

@@ -461,6 +461,9 @@ export const guard: AstGuard = {
   name: "Direct-Entity-Writes Guard",
   scan: SCAN,
   security: true,
+  hint:
+    "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

package/src/guard-html-escape.ts

@@ -83,7 +83,7 @@ function templateStaticText(tpl: Node): string {
   if (tpl.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)) {
     return tpl.getLiteralText();
   }
-  const t = tpl as TemplateExpression;
+  const t = tpl.asKindOrThrow(SyntaxKind.TemplateExpression);
   return [
     t.getHead().getLiteralText(),
     ...t.getTemplateSpans().map((s) => s.getLiteral().getLiteralText()),
@@ -172,7 +172,7 @@ type LocalFunction = FunctionDeclaration | ArrowFunction | FunctionExpression;
 
 function localFunctionsOf(callee: Node, sf: SourceFile): LocalFunction[] | undefined {
   if (!callee.isKind(SyntaxKind.Identifier)) return undefined;
-  const decls = localDeclarations(callee as Identifier, sf);
+  const decls = localDeclarations(callee, sf);
   if (decls.length === 0) return undefined;
   const fns: LocalFunction[] = [];
   for (const d of decls) {

package/src/guard-pre-es-patterns.ts

@@ -163,6 +163,9 @@ const PATTERNS: readonly Pattern[] = [
 export const guard: AstGuard = {
   name: "Pre-ES-Patterns Guard",
   scan: SCAN,
+  hint:
+    "These APIs were removed with the event-sourcing migration. Use the events table with ctx.loadAggregate / queryProjection, ctx.appendEvent on aggregate streams, " +
+    'r.multiStreamProjection for cross-aggregate consumers, and configValue.created/updated/deleted events (aggregateType: "configValue") for config changes.',
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-public-exports-changelog.ts

@@ -270,7 +270,7 @@ function scanPackage(cwd: string, project: Project, pkg: PackageName): PackageSc
     pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
   } catch (e) {
     console.error(
-      `  ${pkg}: package.json unreadable (${e instanceof Error ? e.message : String(e)}).`,
+      `  ${pkg}: package.json unreadable (${e instanceof Error ? e.message : String(e)}). Fix the file so it is valid JSON.`,
     );
     return null;
   }
@@ -320,7 +320,9 @@ export type EvaluateResult = {
 
 function buildFinding(missing: MissingExport, version: string): UncoveredFinding {
   if (!isPackageName(missing.pkg)) {
-    throw new Error(`baseline package key not in scope: ${missing.pkg}`);
+    throw new Error(
+      `baseline package key not in scope: ${missing.pkg}. Remove the key from the baseline or re-freeze it with --write-baseline.`,
+    );
   }
   const pkg = missing.pkg;
   const changelogPath = owningChangelogPath(pkg, missing.key);
@@ -370,7 +372,7 @@ function findingsAgainstBaseline(
   for (const [pkg, keys] of Object.entries(baseline.packages)) {
     if (!isPackageName(pkg)) {
       console.error(
-        `  Baseline contains unknown package key "${pkg}", ignored (only framework|bundled-features).`,
+        `  Baseline contains unknown package key "${pkg}", ignored (only framework|bundled-features). Remove the key from the baseline or re-freeze it with --write-baseline.`,
       );
       continue;
     }
@@ -397,7 +399,9 @@ export function evaluatePublicExportsChangelog(args: {
   logOutOfScopeNotice();
   const scans = scanAllPackages(args.cwd, args.project);
   if (scans.length === 0 && args.mode === "check") {
-    console.error("  No package scanned: the guard would pass vacuously.");
+    console.error(
+      "  No package scanned: the guard would pass vacuously. Run it from a kumiko-framework checkout that contains the framework package.",
+    );
     return { scans, baselineStatus: "ok", findings: [vacuousFinding()] };
   }
 
@@ -441,11 +445,16 @@ export async function loadChangesetParser(frameworkRootAbsPath: string): Promise
     frameworkRootAbsPath,
     "packages/framework/src/engine/changeset-changes.ts",
   );
-  if (!existsSync(parserPath)) throw new Error(`changeset parser not found: ${parserPath}`);
+  if (!existsSync(parserPath))
+    throw new Error(
+      `changeset parser not found: ${parserPath}. Run the guard from a complete kumiko-framework checkout.`,
+    );
   const loaded: unknown = await import(pathToFileURL(parserPath).href);
   const parse = isRecord(loaded) ? loaded["parseChangesetChanges"] : undefined;
   if (!isChangesetParser(parse)) {
-    throw new Error(`${parserPath} does not export parseChangesetChanges as a function`);
+    throw new Error(
+      `${parserPath} does not export parseChangesetChanges as a function. Export it from that file.`,
+    );
   }
   return parse;
 }
@@ -560,7 +569,7 @@ export function writeBaseline(
   const frameworkScan = scans.find((s) => s.pkg === "framework");
   if (!frameworkScan) {
     console.error(
-      "  framework package.json missing: asOfVersion undetermined, baseline not written.",
+      "  framework package.json missing: asOfVersion undetermined, baseline not written. Run it from a kumiko-framework checkout.",
     );
     return 1;
   }
@@ -665,7 +674,9 @@ export async function runPublicExportsChangelogCli(
   }
   const tsConfigFilePath = frameworkTsConfigPath(cwd);
   if (tsConfigFilePath === undefined) {
-    console.error("  public-exports-changelog: framework tsconfig.json not found.");
+    console.error(
+      "  public-exports-changelog: framework tsconfig.json not found. Run it from a complete kumiko-framework checkout.",
+    );
     return 1;
   }
   const project = new Project({ tsConfigFilePath, skipAddingFilesFromTsConfig: true });
@@ -676,7 +687,9 @@ export async function runPublicExportsChangelogCli(
     try {
       pending = await loadPendingBreakingChanges(scanCwd);
     } catch (e) {
-      console.error(`  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}`);
+      console.error(
+        `  Cannot read open changesets: ${e instanceof Error ? e.message : String(e)}. Fix the changeset file named above.`,
+      );
       return 1;
     }
     return writeBaseline(scanCwd, project, join(scanCwd, BASELINE_FILE), pending);

package/src/guard-raw-sql.ts

@@ -78,7 +78,7 @@ async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
     for (const hit of report.hits) {
       if (hit.allowed) continue;
       if (hit.file.includes("/__tests__/")) continue;
-      if (!(BLOCKING_SQL_KINDS as readonly string[]).includes(hit.kind)) continue;
+      if (!BLOCKING_SQL_KINDS.some((kind) => kind === hit.kind)) continue;
       if (hit.markerSuppressed) {
         // One line like `asRawClient(db).unsafe(` yields two hits for one marker.
         if (hit.markerReason !== undefined && hit.markerLine !== undefined) {

package/src/guard-thin-wrappers.ts

@@ -36,7 +36,6 @@ import {
   Project,
   type SourceFile,
   SyntaxKind,
-  type VariableDeclaration,
 } from "ts-morph";
 import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 import { frameworkTsConfigPath } from "./_lib/roots";
@@ -62,7 +61,7 @@ export const KNOWN_WRAPPER_REASONS = [
 export type WrapperReason = (typeof KNOWN_WRAPPER_REASONS)[number];
 
 function isKnownReason(r: string): r is WrapperReason {
-  return (KNOWN_WRAPPER_REASONS as readonly string[]).includes(r);
+  return KNOWN_WRAPPER_REASONS.some((known) => known === r);
 }
 
 // ── Built-in filter ─────────────────────────────────────────────────────
@@ -222,7 +221,7 @@ function getFnName(node: FnNode): string | undefined {
   if (node.isKind(SyntaxKind.FunctionDeclaration)) return node.getName() ?? undefined;
   const parent = node.getParent();
   if (parent?.isKind(SyntaxKind.VariableDeclaration)) {
-    return (parent as VariableDeclaration).getName();
+    return parent.getName();
   }
   if (parent?.isKind(SyntaxKind.PropertyAssignment)) {
     return parent.getFirstChild()?.getText();
@@ -378,6 +377,9 @@ const SCAN: ScanSpec = {
   frameworkWithin: ["packages/*/src/**"],
 };
 
+const WRAPPER_FIX =
+  "call the delegate directly, or mark a deliberate wrapper with // @wrapper-known <reason>";
+
 export const check: RepoCheck = {
   name: "Thin-Wrappers Guard",
   run(roots) {
@@ -404,12 +406,16 @@ export const check: RepoCheck = {
       scanned++;
       for (const f of collectFindings(sf)) {
         if (f.markerReason === null) {
-          warnings.push({ file: f.file, line: f.line, message: `${f.fnName} → ${f.callee}` });
+          warnings.push({
+            file: f.file,
+            line: f.line,
+            message: `${f.fnName} → ${f.callee}  (${WRAPPER_FIX})`,
+          });
         } else if (!isKnownReason(f.markerReason)) {
           warnings.push({
             file: f.file,
             line: f.line,
-            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}")`,
+            message: `${f.fnName} → ${f.callee}  (reason="${f.markerReason}"; use a known reason from the list in this guard)`,
           });
         }
       }