@cosmicdrift/kumiko-guards 0.355.0 → 0.357.0

package/src/check-complexity.ts

@@ -1,34 +1,34 @@
 #!/usr/bin/env bun
 /**
- * Complexity-Check fuer Handler-Hotspots mit Baseline-Regression-Guard.
+ * Complexity check for handler hotspots with a baseline regression guard.
  *
- * Berechnet zyklomatische Komplexitaet pro Funktion/Methode (Basis 1, +1 je
- * Entscheidungspunkt: if, for, while, case, catch, &&, ||, ??, Ternary).
- * Ueber dem Schwellwert -> Hotspot.
+ * Computes cyclomatic complexity per function/method (base 1, +1 per decision
+ * point: if, for, while, case, catch, &&, ||, ??, ternary). Above the
+ * threshold -> hotspot.
  *
- * Baseline-Regression-Guard wie guard-comment-lang.ts: `.kumiko-complexity-
- * baseline.json` im Repo-Root pinnt pro File die eingefrorene Hotspot-Anzahl.
- *   - aktuell <= baseline pro File: PASS
- *   - aktuell >  baseline pro File: FAIL
- * Reduktionen updaten die Baseline NICHT automatisch — nach Refactor-Commits
- * `--write-baseline` aufrufen. Ohne Baseline-Datei bleibt der Check
- * warning-only (Bootstrap: einmalig `--write-baseline`).
- * Die Baseline umfasst nur Files des eigenen Repos; Sibling-Hotspots gehoeren
- * in deren eigene Baseline (siehe localHotspots).
+ * Baseline regression guard like guard-comment-lang.ts: `.kumiko-complexity-
+ * baseline.json` in the repo root pins the frozen hotspot count per file.
+ *   - current <= baseline per file: PASS
+ *   - current >  baseline per file: FAIL
+ * Reductions do NOT update the baseline automatically — run `--write-baseline`
+ * after refactor commits. Without a baseline file the check stays
+ * warning-only (bootstrap: run `--write-baseline` once).
+ * The baseline covers only files of the repo itself; sibling hotspots belong
+ * in their own baseline (see localHotspots).
  *
- * Bewusste Luecke: gezaehlt werden Hotspots pro File, nicht deren Hoehe — eine
- * bereits gelistete Funktion darf komplexer werden, ohne dass der Guard faellt.
+ * Deliberate gap: hotspots are counted per file, not their height — an
+ * already listed function may get more complex without the guard failing.
  *
- * Opt-out: `// kumiko-lint-ignore complexity-budget <Grund>` auf der
- * Funktionszeile, der Zeile darueber, oder (bei JSDoc-dokumentierten
- * Funktionen) der Zeile ueber dem JSDoc-Block.
+ * Opt-out: `// kumiko-lint-ignore complexity-budget <reason>` on the function
+ * line, the line above, or (for JSDoc-documented functions) the line above
+ * the JSDoc block.
  *
  * Usage:
- *   bun guards/check-complexity.ts                  # Vergleich gegen Baseline
- *   bun guards/check-complexity.ts --write-baseline # Baseline neu schreiben
- *   bun guards/check-complexity.ts --no-baseline    # Vergleich ueberspringen
+ *   bun guards/check-complexity.ts                  # compare against baseline
+ *   bun guards/check-complexity.ts --write-baseline # rewrite baseline
+ *   bun guards/check-complexity.ts --no-baseline    # skip comparison
  *
- * Regel: Issue kumiko-framework#1282
+ * Rule: issue kumiko-framework#1282
  */
 
 import * as path from "node:path";
@@ -114,43 +114,42 @@ function hasBudgetTag(fn: Node): boolean {
   return lineHasIgnoreTag(lines[jsDocStartLine - 2] ?? "", BUDGET_TAG);
 }
 
+const BRANCH_KINDS: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.IfStatement,
+  SyntaxKind.ForStatement,
+  SyntaxKind.ForInStatement,
+  SyntaxKind.ForOfStatement,
+  SyntaxKind.WhileStatement,
+  SyntaxKind.DoStatement,
+  SyntaxKind.CatchClause,
+  SyntaxKind.ConditionalExpression,
+  SyntaxKind.CaseClause,
+]);
+
+const SHORT_CIRCUIT_OPERATORS: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.AmpersandAmpersandToken,
+  SyntaxKind.BarBarToken,
+  SyntaxKind.QuestionQuestionToken,
+]);
+
+function isDecisionPoint(node: Node): boolean {
+  const kind = node.getKind();
+  if (BRANCH_KINDS.has(kind)) return true;
+  if (kind !== SyntaxKind.BinaryExpression) return false;
+  const operator = node.asKindOrThrow(SyntaxKind.BinaryExpression).getOperatorToken().getKind();
+  return SHORT_CIRCUIT_OPERATORS.has(operator);
+}
+
 export function computeComplexity(fn: Node): number {
   let complexity = 1;
   fn.forEachDescendant((node, traversal) => {
-    // Don't count decision points inside a nested function-like node —
-    // those get their own Hotspot entry.
+    // skip: decision points inside a nested function-like node belong to its
+    // own Hotspot entry
     if (node !== fn && (FUNCTION_KINDS as readonly SyntaxKind[]).includes(node.getKind())) {
       traversal.skip();
       return;
     }
-    switch (node.getKind()) {
-      case SyntaxKind.IfStatement:
-      case SyntaxKind.ForStatement:
-      case SyntaxKind.ForInStatement:
-      case SyntaxKind.ForOfStatement:
-      case SyntaxKind.WhileStatement:
-      case SyntaxKind.DoStatement:
-      case SyntaxKind.CatchClause:
-      case SyntaxKind.ConditionalExpression:
-        complexity++;
-        break;
-      case SyntaxKind.CaseClause:
-        complexity++;
-        break;
-      case SyntaxKind.BinaryExpression: {
-        const op = node.asKindOrThrow(SyntaxKind.BinaryExpression).getOperatorToken().getKind();
-        if (
-          op === SyntaxKind.AmpersandAmpersandToken ||
-          op === SyntaxKind.BarBarToken ||
-          op === SyntaxKind.QuestionQuestionToken
-        ) {
-          complexity++;
-        }
-        break;
-      }
-      default:
-        break;
-    }
+    if (isDecisionPoint(node)) complexity++;
   });
   return complexity;
 }
@@ -220,18 +219,18 @@ function report(hotspots: readonly Hotspot[], scanned: number): void {
   console.log(`  Hotspots (complexity >= ${COMPLEXITY_THRESHOLD}): ${hotspots.length}`);
   if (hotspots.length === 0) {
     console.log("  Nothing to report.");
-    return;
-  }
-  const shown = hotspots.slice(0, MAX_REPORTED);
-  for (const h of shown) {
-    console.log(`    ${h.file}:${h.line}  ${h.name}()  complexity=${h.complexity}`);
-  }
-  if (hotspots.length > shown.length) {
-    console.log(`    ... ${hotspots.length - shown.length} more`);
+  } else {
+    const shown = hotspots.slice(0, MAX_REPORTED);
+    for (const h of shown) {
+      console.log(`    ${h.file}:${h.line}  ${h.name}()  complexity=${h.complexity}`);
+    }
+    if (hotspots.length > shown.length) {
+      console.log(`    ... ${hotspots.length - shown.length} more`);
+    }
+    console.log(
+      `\n  Rule: split the function, or deliberately allow it with "// ${BUDGET_TAG} <reason>".`,
+    );
   }
-  console.log(
-    `\n  Rule: split the function, or deliberately allow it with "// ${BUDGET_TAG} <reason>".`,
-  );
 }
 
 const complexityBaseline = baselineRatchet({
@@ -276,9 +275,9 @@ function analyse(
 export const guard: AstGuard = {
   name: "Complexity Check",
   scan: SCAN,
-  // Kein Remediation-Text hier: reportResults haengt hint an JEDEN Fail, auch
-  // an Format-Drift, wo "Funktion aufteilen" in die Irre fuehrt. Der konkrete
-  // Rat steht deshalb in der jeweiligen Violation-Message.
+  // No remediation text here: reportResults appends the hint to EVERY failure,
+  // including format drift, where "split the function" would mislead. The
+  // concrete advice lives in the respective violation message.
   hint: 'after a deliberate change: `kumiko-guards guards --write-baseline --guard="Complexity Check"`',
   run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
   writeBaseline: (files) => {
@@ -288,9 +287,9 @@ export const guard: AstGuard = {
   },
 };
 
-// Flags werden NUR hier gelesen, nicht in run() — der Shared-Runner
-// (run-guards.ts) faehrt 18 Guards mit derselben argv, ein --write-baseline
-// dort duerfte die Baseline nicht stillschweigend neu schreiben.
+// Flags are read ONLY here, not in run() — the shared runner (run-guards.ts)
+// drives 18 guards with the same argv, and a --write-baseline there must not
+// silently rewrite the baseline.
 if (import.meta.main) {
   const args = process.argv.slice(2);
   if (args.includes("--write-baseline")) {

package/src/check-predicates.ts

@@ -1,19 +1,19 @@
 #!/usr/bin/env bun
 /**
- * Predicate-Extraction Check (WARNUNG, kein Fail).
+ * Predicate-extraction check (WARNING, no fail).
  *
- * Findet zwei Arten von Kandidaten fuer Predicate-Extraction:
- *  1. Fat Predicates — `if`/`while`/ternary Conditions mit >=3 logischen
- *     Operatoren (&&/||) ODER Condition-Text >80 Zeichen.
- *  2. Duplikate — dieselbe Condition (normalisiert) >=2x im Scan-Scope,
- *     mit >=2 Operatoren (um triviale `!x`-Checks auszuschliessen).
+ * Finds two kinds of candidates for predicate extraction:
+ *  1. Fat predicates — `if`/`while`/ternary conditions with >=3 logical
+ *     operators (&&/||) OR condition text >80 characters.
+ *  2. Duplicates — the same (normalized) condition >=2x in the scan scope,
+ *     with >=2 operators (to exclude trivial `!x` checks).
  *
- * Output: Warnung mit Datei:Zeile + Hinweis auf Regel. Exit-Code immer 0.
+ * Output: warning with file:line + a pointer to the rule. Exit code is always 0.
  *
  * Usage:
  *   bun guards/check-predicates.ts
  *
- * Regel: ~/.claude/rules/coding-standards.md → "Predicate Extraction"
+ * Rule: ~/.claude/rules/coding-standards.md → "Predicate Extraction"
  */
 
 import * as path from "node:path";
@@ -91,11 +91,13 @@ function collectConditions(sf: SourceFile): Site[] {
   const file = path.relative(ROOT, sf.getFilePath());
 
   const push = (node: Node, conditionNode: Node | undefined): void => {
+    // skip: a missing condition (e.g. `for (;;)`) has nothing to extract
     if (!conditionNode) return;
     const raw = conditionNode.getText();
     const text = normalize(raw);
     const { ands, ors } = countOperators(text);
     const operators = ands + ors;
+    // skip: a short condition without logical operators needs no named predicate
     if (operators === 0 && text.length < LENGTH_THRESHOLD) return;
     sites.push({
       file,
@@ -119,8 +121,83 @@ function collectConditions(sf: SourceFile): Site[] {
   return sites;
 }
 
-// Warning-only Check: blockt nie (returnt immer 0 violations). Die Findings
-// werden via console ausgegeben; der Runner zeigt `✓` solange nichts wirft.
+type TextDuplicateGroup = [Site, Site, ...Site[]];
+type ShapeDuplicateGroup = { shape: string; sites: Site[] };
+
+function bucketDuplicateCandidates(allSites: readonly Site[]): {
+  byText: Map<string, Site[]>;
+  byShape: Map<string, Site[]>;
+} {
+  const byText = new Map<string, Site[]>();
+  const byShape = new Map<string, Site[]>();
+  for (const s of allSites) {
+    // Count as duplicate candidate if either >=2 operators OR text long enough
+    // that repetition is still worth extracting (covers 1-operator but lengthy
+    // domain checks like kebab-case validation).
+    if (s.operators < DUP_MIN_OPERATORS && s.text.length < LENGTH_THRESHOLD) continue;
+    const textBucket = byText.get(s.text) ?? [];
+    textBucket.push(s);
+    byText.set(s.text, textBucket);
+    const shape = structuralShape(s.text);
+    const shapeBucket = byShape.get(shape) ?? [];
+    shapeBucket.push(s);
+    byShape.set(shape, shapeBucket);
+  }
+  return { byText, byShape };
+}
+
+function findTextDuplicates(byText: ReadonlyMap<string, Site[]>): TextDuplicateGroup[] {
+  const textDups: TextDuplicateGroup[] = [];
+  for (const bucket of byText.values()) {
+    if (bucket.length < 2) continue;
+    const [first, second, ...rest] = bucket;
+    if (first !== undefined && second !== undefined) textDups.push([first, second, ...rest]);
+  }
+  return textDups;
+}
+
+function findShapeDuplicates(byShape: ReadonlyMap<string, Site[]>): ShapeDuplicateGroup[] {
+  const shapeDups: ShapeDuplicateGroup[] = [];
+  for (const [shape, bucket] of byShape.entries()) {
+    if (bucket.length < 2) continue;
+    // Skip when sites are already covered by exact-text duplicate group.
+    const firstText = bucket[0]?.text;
+    const allSame = bucket.every((s) => s.text === firstText);
+    if (allSame) continue;
+    shapeDups.push({ shape, sites: bucket });
+  }
+  return shapeDups;
+}
+
+const snip = (text: string): string => (text.length > 90 ? `${text.slice(0, 87)}...` : text);
+
+function printFatPredicates(fatSites: readonly Site[]): void {
+  console.log(`\n  Fat-predicate candidates:`);
+  for (const s of fatSites) {
+    const hint = s.ands === 0 && s.ors >= 3 ? "  (Array.includes/Set?)" : "";
+    console.log(`    ${s.file}:${s.line}  [${s.ands}&& ${s.ors}||]  ${snip(s.text)}${hint}`);
+  }
+}
+
+function printTextDuplicates(textDups: readonly TextDuplicateGroup[]): void {
+  console.log(`\n  Exact duplicates:`);
+  for (const group of textDups) {
+    const [first] = group;
+    console.log(`    ${group.length}x  ${snip(first.text)}`);
+    for (const s of group) console.log(`      - ${s.file}:${s.line}`);
+  }
+}
+
+function printShapeDuplicates(shapeDups: readonly ShapeDuplicateGroup[]): void {
+  console.log(`\n  Structural duplicates:`);
+  for (const { shape, sites } of shapeDups) {
+    console.log(`    ${sites.length}x  shape: ${snip(shape)}`);
+    for (const s of sites) console.log(`      - ${s.file}:${s.line}  ${snip(s.text)}`);
+  }
+}
+
+// Warning-only check: never blocks (always returns 0 violations). The
+// findings are printed via console; the runner shows `✓` as long as nothing throws.
 export const guard: AstGuard = {
   name: "Predicate Extraction Check",
   scan: SCAN,
@@ -136,37 +213,9 @@ export const guard: AstGuard = {
     const fatSites = allSites.filter(
       (s) => s.operators >= OPERATOR_THRESHOLD || s.text.length >= LENGTH_THRESHOLD,
     );
-
-    const byText = new Map<string, Site[]>();
-    const byShape = new Map<string, Site[]>();
-    for (const s of allSites) {
-      // Count as duplicate candidate if either >=2 operators OR text long enough
-      // that repetition is still worth extracting (covers 1-operator but lengthy
-      // domain checks like kebab-case validation).
-      if (s.operators < DUP_MIN_OPERATORS && s.text.length < LENGTH_THRESHOLD) continue;
-      const textBucket = byText.get(s.text) ?? [];
-      textBucket.push(s);
-      byText.set(s.text, textBucket);
-      const shape = structuralShape(s.text);
-      const shapeBucket = byShape.get(shape) ?? [];
-      shapeBucket.push(s);
-      byShape.set(shape, shapeBucket);
-    }
-    const textDups: Array<[Site, Site, ...Site[]]> = [];
-    for (const bucket of byText.values()) {
-      if (bucket.length < 2) continue;
-      const [first, second, ...rest] = bucket;
-      if (first !== undefined && second !== undefined) textDups.push([first, second, ...rest]);
-    }
-    const shapeDups: Array<{ shape: string; sites: Site[] }> = [];
-    for (const [shape, bucket] of byShape.entries()) {
-      if (bucket.length < 2) continue;
-      // Skip when sites are already covered by exact-text duplicate group.
-      const firstText = bucket[0]?.text;
-      const allSame = bucket.every((s) => s.text === firstText);
-      if (allSame) continue;
-      shapeDups.push({ shape, sites: bucket });
-    }
+    const { byText, byShape } = bucketDuplicateCandidates(allSites);
+    const textDups = findTextDuplicates(byText);
+    const shapeDups = findShapeDuplicates(byShape);
 
     console.log(`Predicate-Extraction Check: ${scanned} files checked.`);
     console.log(
@@ -180,32 +229,9 @@ export const guard: AstGuard = {
       return { violations: [] };
     }
 
-    const snip = (text: string): string => (text.length > 90 ? `${text.slice(0, 87)}...` : text);
-
-    if (fatSites.length > 0) {
-      console.log(`\n  Fat-predicate candidates:`);
-      for (const s of fatSites) {
-        const hint = s.ands === 0 && s.ors >= 3 ? "  (Array.includes/Set?)" : "";
-        console.log(`    ${s.file}:${s.line}  [${s.ands}&& ${s.ors}||]  ${snip(s.text)}${hint}`);
-      }
-    }
-
-    if (textDups.length > 0) {
-      console.log(`\n  Exact duplicates:`);
-      for (const group of textDups) {
-        const [first] = group;
-        console.log(`    ${group.length}x  ${snip(first.text)}`);
-        for (const s of group) console.log(`      - ${s.file}:${s.line}`);
-      }
-    }
-
-    if (shapeDups.length > 0) {
-      console.log(`\n  Structural duplicates:`);
-      for (const { shape, sites } of shapeDups) {
-        console.log(`    ${sites.length}x  shape: ${snip(shape)}`);
-        for (const s of sites) console.log(`      - ${s.file}:${s.line}  ${snip(s.text)}`);
-      }
-    }
+    if (fatSites.length > 0) printFatPredicates(fatSites);
+    if (textDups.length > 0) printTextDuplicates(textDups);
+    if (shapeDups.length > 0) printShapeDuplicates(shapeDups);
 
     console.log(
       "\n  Rule: extract as a named function (isX/hasY/canZ) when the condition has a stable name.",

package/src/check-secret-literals.ts

@@ -1,26 +1,26 @@
 #!/usr/bin/env bun
 /**
- * Secret-Literal-Guard (stack-agnostisch).
+ * Secret-literal guard (stack-agnostic).
  *
- * Flaggt hartkodierte Secret-Fallbacks in Server-Code:
+ * Flags hardcoded secret fallbacks in server code:
  *   const s = env.JWT_SECRET ?? "hardcoded-prod-secret";   // ✗
  *   hmacSecret: config.X ?? "cashcolt-mailer-hmac-secret", // ✗
  *
- * Ein `?? "<literal>"`-Fallback auf etwas Secret-artiges heißt: fehlt die
- * Env-Variable, läuft der Server mit einem im Repo sichtbaren Secret weiter —
- * genau die Klasse, die bei einem Deploy-Fehler zum geleakten Prod-Secret wird.
- * Secure-by-default: fehlendes Secret → hart fehlschlagen, nie auf ein Literal
- * zurückfallen.
+ * A `?? "<literal>"` fallback on something secret-like means: if the env
+ * variable is missing, the server keeps running with a secret visible in the
+ * repo — exactly the class that becomes a leaked prod secret after a deploy
+ * mistake. Secure by default: a missing secret → fail hard, never fall back to
+ * a literal.
  *
- * AKZEPTIERTE AUSNAHME: `bin/server.ts` ist der designierte DEV-Entrypoint
- * (runDevApp). Dort sind Dev-Secret-Fallbacks gewollt — der PROD-Entrypoint
- * `bin/main.ts` (runProdApp) liest dieselben Secrets aus dem validierten Env
- * und failt hart. Der Guard akzeptiert Literale daher nur in `bin/server.ts`
- * und flaggt sie überall sonst (Prod-Entrypoint, Config-Module, Handler, Lib).
+ * ACCEPTED EXCEPTION: `bin/server.ts` is the designated DEV entrypoint
+ * (runDevApp). Dev secret fallbacks are intended there — the PROD entrypoint
+ * `bin/main.ts` (runProdApp) reads the same secrets from the validated env
+ * and fails hard. The guard therefore accepts literals only in `bin/server.ts`
+ * and flags them everywhere else (prod entrypoint, config modules, handlers, lib).
  *
- * Scannt den eigenen Checkout (die `roots`, die der Runner auflöst) —
- * jedes Repo läuft diesen Check in seiner eigenen CI gegen sich selbst,
- * statt dass ein zentraler Scan in fremde Sibling-Checkouts greift.
+ * Scans its own checkout (the `roots` the runner resolves) —
+ * every repo runs this check against itself in its own CI, instead of a
+ * central scan reaching into foreign sibling checkouts.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -81,11 +81,11 @@ function maskComments(source: string): string {
     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);
+    } else {
+      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);
@@ -105,6 +105,33 @@ const SECRET_LITERAL_TOKEN = /hmac|private[_-]?key|signing[_-]?key/i;
 const LHS_NAME = /([\w$]+)\s*[:=][^:=]*$/;
 const UNNAMED_PLACEHOLDER = "<unnamed>";
 
+type SecretFallback = { readonly name: string; readonly literalLength: number };
+
+function secretNameFor(left: string, literal: string): string | undefined {
+  return (
+    SECRET_NAME.exec(left)?.[0] ??
+    (SECRET_LITERAL_TOKEN.test(literal)
+      ? (LHS_NAME.exec(left)?.[1] ?? UNNAMED_PLACEHOLDER)
+      : undefined)
+  );
+}
+
+// Every fallback on the line is inspected; the name is read only from the text since the
+// previous fallback, so an earlier assignee cannot lend its name to a later literal.
+function firstSecretFallback(code: string): SecretFallback | undefined {
+  let previousEnd = 0;
+  for (const match of code.matchAll(STRING_FALLBACK)) {
+    const left = code.slice(previousEnd, match.index);
+    previousEnd = match.index + match[0].length;
+    const literal = match[2];
+    if (!literal || literal.length < MIN_SECRET_LENGTH || TRIVIAL_LITERAL.test(literal)) continue;
+    const name = secretNameFor(left, literal);
+    if (name === undefined) continue;
+    return { name, literalLength: literal.length };
+  }
+  return undefined;
+}
+
 /**
  * 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
@@ -116,26 +143,10 @@ export function scanLinesForSecretLiterals(lines: readonly string[]): SecretLite
   const maskedLines = maskComments(lines.join("\n")).split("\n");
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i] ?? "";
-    const code = maskedLines[i] ?? "";
     if (lineHasIgnoreTag(raw, IGNORE_TAG) || lineHasIgnoreTag(lines[i - 1] ?? "", IGNORE_TAG))
       continue;
-    // Every fallback on the line is inspected; the name is read only from the text since the
-    // previous fallback, so an earlier assignee cannot lend its name to a later literal.
-    let previousEnd = 0;
-    for (const match of code.matchAll(STRING_FALLBACK)) {
-      const left = code.slice(previousEnd, match.index);
-      previousEnd = match.index + match[0].length;
-      const literal = match[2];
-      if (!literal || literal.length < MIN_SECRET_LENGTH || TRIVIAL_LITERAL.test(literal)) continue;
-      const name =
-        SECRET_NAME.exec(left)?.[0] ??
-        (SECRET_LITERAL_TOKEN.test(literal)
-          ? (LHS_NAME.exec(left)?.[1] ?? UNNAMED_PLACEHOLDER)
-          : undefined);
-      if (name === undefined) continue;
-      hits.push({ lineNumber: i + 1, name, literalLength: literal.length });
-      break;
-    }
+    const fallback = firstSecretFallback(maskedLines[i] ?? "");
+    if (fallback) hits.push({ lineNumber: i + 1, ...fallback });
   }
   return hits;
 }

package/src/check-single-runtime-instance.ts

@@ -103,7 +103,7 @@ export const check: RepoCheck = {
         violations.push({
           file: "bun.lock",
           line: 1,
-          message: `bun.lock could not be parsed (${root.name}): ${lock.reason}`,
+          message: `bun.lock could not be parsed (${root.name}): ${lock.detail}`,
         });
         continue;
       }

package/src/cli.ts

@@ -37,8 +37,11 @@ function printHelp(): void {
   }
 }
 
-async function main(): Promise<void> {
-  const subcommand = process.argv[2];
+function parseInvocation(argv: readonly string[]): {
+  subcommand: Subcommand | undefined;
+  flags: string[];
+} {
+  const subcommand = argv[2];
   if (subcommand === "--help" || subcommand === "-h") {
     printHelp();
     process.exit(0);
@@ -49,27 +52,37 @@ async function main(): Promise<void> {
     );
     process.exit(1);
   }
-  const flags = process.argv.slice(3);
+  const flags = argv.slice(3);
   if (subcommand !== undefined && (flags.includes("--help") || flags.includes("-h"))) {
     printHelp();
     process.exit(0);
   }
+  return { subcommand, flags };
+}
+
+function printInventory(flags: readonly string[]): void {
+  const flagsError = cliFlagsError("list", flags, SUBCOMMAND_FLAGS.list);
+  if (flagsError !== undefined) {
+    console.error(flagsError);
+    process.exit(1);
+  }
+  // Registration inventory only — no scan, no project, no guard.run(). What
+  // CI checks against instead of running the guards: a guard dropped from a
+  // suite's array goes missing here too, not just silently from a run.
+  const inventory = buildGuardKitInventory({
+    guards: GUARDS,
+    uiGuards: UI_GUARDS,
+    checks: REPO_CHECKS,
+  });
+  console.log(JSON.stringify(inventory));
+}
+
+async function main(): Promise<void> {
+  const { subcommand, flags } = parseInvocation(process.argv);
 
   if (subcommand === "list") {
-    const flagsError = cliFlagsError("list", flags, SUBCOMMAND_FLAGS.list);
-    if (flagsError !== undefined) {
-      console.error(flagsError);
-      process.exit(1);
-    }
-    // Registration inventory only — no scan, no project, no guard.run(). What
-    // CI checks against instead of running the guards: a guard dropped from a
-    // suite's array goes missing here too, not just silently from a run.
-    const inventory = buildGuardKitInventory({
-      guards: GUARDS,
-      uiGuards: UI_GUARDS,
-      checks: REPO_CHECKS,
-    });
-    console.log(JSON.stringify(inventory));
+    printInventory(flags);
+    // skip: the inventory subcommand only prints and must not run any guard
     return;
   }