@cosmicdrift/kumiko-guards 0.1.0 → 0.3.0

package/src/check-complexity.ts

@@ -0,0 +1,292 @@
+#!/usr/bin/env bun
+/**
+ * Complexity-Check fuer Handler-Hotspots mit Baseline-Regression-Guard.
+ *
+ * Berechnet zyklomatische Komplexitaet pro Funktion/Methode (Basis 1, +1 je
+ * Entscheidungspunkt: if, for, while, case, catch, &&, ||, ??, Ternary).
+ * Ueber dem Schwellwert -> 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).
+ *
+ * Bewusste Luecke: gezaehlt werden Hotspots pro File, nicht deren Hoehe — eine
+ * bereits gelistete Funktion darf komplexer werden, ohne dass der Guard faellt.
+ *
+ * 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.
+ *
+ * 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
+ *
+ * Regel: Issue kumiko-framework#1282
+ */
+
+import * as path from "node:path";
+import { Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  type GuardOutcome,
+  type GuardViolation,
+  isLocalFinding,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { hasIgnoreTag } from "./_lib/ignore-tag";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+const COMPLEXITY_THRESHOLD = 15;
+const MAX_REPORTED = 30;
+const BUDGET_TAG = "kumiko-lint-ignore complexity-budget";
+
+const FUNCTION_KINDS = [
+  SyntaxKind.FunctionDeclaration,
+  SyntaxKind.FunctionExpression,
+  SyntaxKind.ArrowFunction,
+  SyntaxKind.MethodDeclaration,
+  SyntaxKind.Constructor,
+  SyntaxKind.GetAccessor,
+  SyntaxKind.SetAccessor,
+] as const;
+
+export interface Hotspot {
+  file: string;
+  line: number;
+  name: string;
+  complexity: number;
+}
+
+function functionName(node: Node): string {
+  if (
+    Node.isFunctionDeclaration(node) ||
+    Node.isMethodDeclaration(node) ||
+    Node.isGetAccessorDeclaration(node) ||
+    Node.isSetAccessorDeclaration(node)
+  ) {
+    return node.getName() ?? "<anonymous>";
+  }
+  if (Node.isConstructorDeclaration(node)) return "constructor";
+  // Arrow/function-expression assigned to a variable, object property, or
+  // class property (`foo = () => {...}`): use that name.
+  const parent = node.getParent();
+  if (
+    Node.isVariableDeclaration(parent) ||
+    Node.isPropertyAssignment(parent) ||
+    Node.isPropertyDeclaration(parent)
+  ) {
+    return parent.getName();
+  }
+  return "<anonymous>";
+}
+
+// hasIgnoreTag() only checks the node's own start line and the line above —
+// for a JSDoc-documented function, "the line above" is the JSDoc's closing
+// `*/`, not a line where a developer would naturally place a bare `//` tag.
+// Extend the check to the line above the JSDoc block too.
+function hasBudgetTag(fn: Node): boolean {
+  if (hasIgnoreTag(fn, BUDGET_TAG)) return true;
+  const jsDocStartLine = fn.getStartLineNumber(true);
+  if (jsDocStartLine === fn.getStartLineNumber()) return false;
+  const lines = fn.getSourceFile().getFullText().split("\n");
+  return (lines[jsDocStartLine - 2] ?? "").includes(BUDGET_TAG);
+}
+
+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.
+    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;
+    }
+  });
+  return complexity;
+}
+
+export function collectHotspots(sf: SourceFile): Hotspot[] {
+  const file = path.relative(ROOT, sf.getFilePath());
+  const hotspots: Hotspot[] = [];
+  for (const kind of FUNCTION_KINDS) {
+    for (const fn of sf.getDescendantsOfKind(kind)) {
+      const complexity = computeComplexity(fn);
+      if (complexity < COMPLEXITY_THRESHOLD) continue;
+      if (hasBudgetTag(fn)) continue;
+      hotspots.push({
+        file,
+        line: fn.getStartLineNumber(),
+        name: functionName(fn),
+        complexity,
+      });
+    }
+  }
+  return hotspots;
+}
+
+const BASELINE_FILE = ".kumiko-complexity-baseline.json";
+
+const BASELINE_FORMAT_VERSION = 1;
+
+// The baseline lives inside one repo and may only gate that repo's own files.
+// The guard scans every root, so sibling hits appear as "../<repo>/..." relative
+// to ROOT: freezing those would fail a money-horse refactor locally in the
+// framework (invisible in CI, where no sibling is checked out), and would leak
+// private repo paths into the public framework history. The report still lists
+// every hotspot — only the baseline view is repo-local.
+export function localHotspots(hotspots: readonly Hotspot[]): readonly Hotspot[] {
+  return hotspots.filter(isLocalFinding);
+}
+
+export function countHotspotsByFile(hotspots: readonly Hotspot[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const h of hotspots) counts[h.file] = (counts[h.file] ?? 0) + 1;
+  return counts;
+}
+
+function scan(files: readonly SourceFile[]): {
+  hotspots: Hotspot[];
+  scanned: number;
+} {
+  const hotspots: Hotspot[] = [];
+  let scanned = 0;
+  for (const sf of files) {
+    if (EXCLUDE.test(sf.getFilePath())) continue;
+    scanned++;
+    hotspots.push(...collectHotspots(sf));
+  }
+  hotspots.sort((a, b) => b.complexity - a.complexity);
+  return { hotspots, scanned };
+}
+
+function report(hotspots: readonly Hotspot[], scanned: number): void {
+  console.log(`Complexity Check: ${scanned} files checked.`);
+  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`);
+  }
+  console.log(
+    `\n  Rule: split the function, or deliberately allow it with "// ${BUDGET_TAG} <reason>".`,
+  );
+}
+
+const complexityBaseline = baselineRatchet({
+  file: path.join(ROOT, BASELINE_FILE),
+  formatVersion: BASELINE_FORMAT_VERSION,
+  unit: "Complexity-Hotspot(s)",
+});
+
+// `scan` sorts by complexity descending, so the first hit for a file is its
+// worst function — the one the violation should point at, not whichever
+// hotspot happens to come first in the file.
+export function resolveHotspotLine(hotspots: readonly Hotspot[], file: string): number {
+  return hotspots.find((h) => h.file === file)?.line ?? 1;
+}
+
+function checkBaseline(scanned: readonly Hotspot[]): GuardViolation[] {
+  const hotspots = localHotspots(scanned);
+  return complexityBaseline.check(
+    countHotspotsByFile(hotspots),
+    `Split the function, or allow it with "// ${BUDGET_TAG} <reason>".`,
+    {
+      formatDriftRemediation: `Run \`bun guards/check-complexity.ts --write-baseline\` once.`,
+      resolveLine: (file) => resolveHotspotLine(hotspots, file),
+    },
+  );
+}
+
+function analyse(files: readonly SourceFile[], compareBaseline: boolean): GuardOutcome {
+  const { hotspots, scanned } = scan(files);
+  report(hotspots, scanned);
+  if (!compareBaseline) {
+    console.log("  Baseline comparison skipped (--no-baseline).");
+    return { violations: [] };
+  }
+  return { violations: checkBaseline(hotspots) };
+}
+
+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.
+  hint: "after a deliberate change: `bun guards/check-complexity.ts --write-baseline`",
+  run: (files) => analyse(files, true),
+};
+
+// 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.
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  if (args.includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    const { hotspots, scanned } = scan(filesForGuard(project, guard));
+    report(hotspots, scanned);
+    complexityBaseline.write(countHotspotsByFile(localHotspots(hotspots)));
+    process.exit(0);
+  }
+  if (args.includes("--no-baseline")) {
+    const project = buildSharedProject([guard]);
+    analyse(filesForGuard(project, guard), false);
+    process.exit(0);
+  }
+  runStandalone(guard);
+}

package/src/check-predicates.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+/**
+ * Predicate-Extraction Check (WARNUNG, kein 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).
+ *
+ * Output: Warnung mit Datei:Zeile + Hinweis auf Regel. Exit-Code immer 0.
+ *
+ * Usage:
+ *   bun guards/check-predicates.ts
+ *
+ * Regel: ~/.claude/rules/coding-standards.md → "Predicate Extraction"
+ */
+
+import * as path from "node:path";
+import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+
+const ROOT = process.cwd();
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+
+const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+
+const OPERATOR_THRESHOLD = 3;
+const LENGTH_THRESHOLD = 80;
+const DUP_MIN_OPERATORS = 2;
+
+interface Site {
+  file: string;
+  line: number;
+  text: string;
+  operators: number;
+  ands: number;
+  ors: number;
+}
+
+function normalize(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+// Keywords/primitives we keep literal when building the structural shape.
+// Everything else that looks like an identifier or property access collapses to `_`,
+// so `toKebab(x) !== x` and `toKebab(y) !== y` share the same shape.
+const SHAPE_KEEP = new Set([
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "void",
+  "delete",
+  "await",
+  "true",
+  "false",
+  "null",
+  "undefined",
+  "string",
+  "number",
+  "object",
+  "boolean",
+  "symbol",
+  "bigint",
+  "function",
+]);
+
+function structuralShape(text: string): string {
+  return text.replace(/\b[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)*\b/g, (match) => {
+    const dot = match.indexOf(".");
+    const head = dot === -1 ? match : match.slice(0, dot);
+    return SHAPE_KEEP.has(head) ? match : "_";
+  });
+}
+
+function countOperators(text: string): { ands: number; ors: number } {
+  const ands = (text.match(/&&/g) ?? []).length;
+  const ors = (text.match(/\|\|/g) ?? []).length;
+  return { ands, ors };
+}
+
+function collectConditions(sf: SourceFile): Site[] {
+  const sites: Site[] = [];
+  const file = path.relative(ROOT, sf.getFilePath());
+
+  const push = (node: Node, conditionNode: Node | undefined): void => {
+    if (!conditionNode) return;
+    const raw = conditionNode.getText();
+    const text = normalize(raw);
+    const { ands, ors } = countOperators(text);
+    const operators = ands + ors;
+    if (operators === 0 && text.length < LENGTH_THRESHOLD) return;
+    sites.push({
+      file,
+      line: node.getStartLineNumber(),
+      text,
+      operators,
+      ands,
+      ors,
+    });
+  };
+
+  for (const ifNode of sf.getDescendantsOfKind(SyntaxKind.IfStatement)) {
+    push(ifNode, ifNode.getExpression());
+  }
+  for (const whileNode of sf.getDescendantsOfKind(SyntaxKind.WhileStatement)) {
+    push(whileNode, whileNode.getExpression());
+  }
+  for (const tern of sf.getDescendantsOfKind(SyntaxKind.ConditionalExpression)) {
+    push(tern, tern.getCondition());
+  }
+  return sites;
+}
+
+// Warning-only Check: blockt nie (returnt immer 0 violations). Die Findings
+// werden via console ausgegeben; der Runner zeigt `✓` solange nichts wirft.
+export const guard: AstGuard = {
+  name: "Predicate Extraction Check",
+  scan: SCAN,
+  run(files) {
+    const allSites: Site[] = [];
+    let scanned = 0;
+    for (const sf of files) {
+      if (EXCLUDE.test(sf.getFilePath())) continue;
+      scanned++;
+      allSites.push(...collectConditions(sf));
+    }
+
+    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 });
+    }
+
+    console.log(`Predicate-Extraction Check: ${scanned} files checked.`);
+    console.log(
+      `  Fat predicates (>=${OPERATOR_THRESHOLD} ops or >${LENGTH_THRESHOLD} chars): ${fatSites.length}`,
+    );
+    console.log(`  Exact duplicates: ${textDups.length}`);
+    console.log(`  Structural duplicates (same pattern, different names): ${shapeDups.length}`);
+
+    if (fatSites.length === 0 && textDups.length === 0 && shapeDups.length === 0) {
+      console.log("  Nothing to report.");
+      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)}`);
+      }
+    }
+
+    console.log(
+      "\n  Rule: extract as a named function (isX/hasY/canZ) when the condition has a stable name.",
+    );
+    console.log("  Warning, no fail.");
+    return { violations: [] };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/check-secret-literals.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+/**
+ * Secret-Literal-Guard (stack-agnostisch).
+ *
+ * Flaggt hartkodierte 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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+import { join } from "node:path";
+import { Glob } from "bun";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { scanLinesForPredicate } from "./_lib/scan-lines";
+
+// Server-side only: apps/server (not apps/mobile — client code, no server secrets).
+const SCAN_PATTERNS: ReadonlyArray<string> = [
+  "bin/**/*.ts",
+  "src/**/*.ts",
+  "apps/server/src/**/*.ts",
+  "packages/*/src/**/*.ts",
+];
+
+const EXCLUDE_DIR = /(?:^|\/)(?:node_modules|dist|__tests__)\//;
+const IS_TEST = /\.(?:test|integration)\.tsx?$/;
+// The one accepted home for dev-secret fallbacks (see header).
+const DEV_ENTRYPOINT = /(?:^|\/)bin\/server\.ts$/;
+
+// A `?? "literal"` / `|| "literal"` nullish/or fallback to a string literal.
+const STRING_FALLBACK = /(?:\?\?|\|\|)\s*(['"`])([^'"`\n]+)\1/;
+// ...on a line that is about a secret (assignee name or the literal itself).
+const SECRET_CONTEXT = /secret|password|passphrase|hmac|private[_-]?key|signing[_-]?key/i;
+// Short / numeric literals are versions or flags (e.g. `_CURRENT_VERSION ?? "1"`),
+// never a usable secret.
+const TRIVIAL_LITERAL = /^[\d.]+$/;
+
+export type SecretLiteralFinding = {
+  readonly file: string;
+  readonly line: number;
+  readonly text: string;
+};
+
+/** Returns the offending literal, or null when the line is clean. */
+export function secretLiteralOnLine(line: string): string | null {
+  // Only the line start counts as a comment (`//`, or a block-comment line
+  // starting with `*`/`/*`/`*/`): stripping from the first `//` anywhere in
+  // the line would cut connection-string fallbacks (postgres://, redis://,
+  // https://token@host/…) off before their closing quote, losing findings.
+  const code = /^\s*(?:\/\/|\/\*|\*\/|\*)/.test(line) ? "" : line;
+  if (!SECRET_CONTEXT.test(code)) return null;
+  const match = STRING_FALLBACK.exec(code);
+  if (!match) return null;
+  const literal = match[2];
+  if (!literal || literal.length < 8 || TRIVIAL_LITERAL.test(literal)) return null;
+  return literal;
+}
+
+async function scanRoot(
+  root: RepoRoot,
+): Promise<{ readonly findings: SecretLiteralFinding[]; readonly scannedFiles: number }> {
+  const findings: SecretLiteralFinding[] = [];
+  let scannedFiles = 0;
+  for (const pattern of SCAN_PATTERNS) {
+    for (const rel of new Glob(pattern).scanSync({ cwd: root.absPath })) {
+      if (EXCLUDE_DIR.test(`/${rel}`) || IS_TEST.test(rel) || DEV_ENTRYPOINT.test(rel)) {
+        continue;
+      }
+      const abs = join(root.absPath, rel);
+      scannedFiles++;
+      scanLinesForPredicate(abs, rel, (line) => secretLiteralOnLine(line) !== null, findings);
+    }
+  }
+  return { findings, scannedFiles };
+}
+
+export async function scanSecretLiterals(roots: readonly RepoRoot[]): Promise<{
+  readonly findings: SecretLiteralFinding[];
+  readonly scannedFiles: number;
+}> {
+  const findings: SecretLiteralFinding[] = [];
+  let scannedFiles = 0;
+  for (const root of roots) {
+    const result = await scanRoot(root);
+    findings.push(...result.findings);
+    scannedFiles += result.scannedFiles;
+  }
+  return { findings, scannedFiles };
+}
+
+export const check: RepoCheck = {
+  name: "Secret-Literal Guard",
+  hint:
+    "A missing secret must fail hard, never fall back to a literal. " +
+    "Read from the validated env (throw if missing). Dev-only fallbacks belong in bin/server.ts.",
+  async run(roots) {
+    if (roots.length === 0) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+    const { findings, scannedFiles } = await scanSecretLiterals(roots);
+    return {
+      violations: findings.map((f) => ({ file: f.file, line: f.line, message: f.text })),
+      matchedFiles: scannedFiles,
+      notApplicable: false,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check], resolveRepoRoots()));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/cli.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env bun
+// Consumer entry point for `bunx @cosmicdrift/kumiko-guards`. Runs all three
+// suites (or one, via subcommand) using the exact call forms the three
+// runners already use in their own `if (import.meta.main)` blocks.
+import {
+  buildSharedProject,
+  printGuardKitBanner,
+  reportResults,
+  runGuards,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import { GUARDS } from "./run-guards";
+import { REPO_CHECKS } from "./run-repo-checks";
+import { UI_GUARDS } from "./run-ui-guards";
+
+const SUBCOMMANDS = ["guards", "ui", "checks"] as const;
+type Subcommand = (typeof SUBCOMMANDS)[number];
+
+function isSubcommand(value: string): value is Subcommand {
+  return (SUBCOMMANDS as readonly string[]).includes(value);
+}
+
+function runGuardsSuite(): number {
+  const project = buildSharedProject(GUARDS);
+  printGuardKitBanner(GUARDS.length, project);
+  return reportResults(runGuards(GUARDS, project));
+}
+
+function runUiGuardsSuite(): number {
+  const project = buildSharedProject(UI_GUARDS);
+  printGuardKitBanner(UI_GUARDS.length, project);
+  return reportResults(runGuards(UI_GUARDS, project));
+}
+
+async function runRepoChecksSuite(): Promise<number> {
+  printGuardKitBanner(REPO_CHECKS.length);
+  return reportResults(await runRepoChecks(REPO_CHECKS));
+}
+
+async function main(): Promise<void> {
+  const subcommand = process.argv[2];
+  if (subcommand !== undefined && !isSubcommand(subcommand)) {
+    console.error(
+      `Unknown subcommand "${subcommand}". Valid subcommands: ${SUBCOMMANDS.join(", ")}`,
+    );
+    process.exit(1);
+  }
+
+  let failed = 0;
+  if (subcommand === undefined || subcommand === "guards") failed += runGuardsSuite();
+  if (subcommand === undefined || subcommand === "ui") failed += runUiGuardsSuite();
+  if (subcommand === undefined || subcommand === "checks") failed += await runRepoChecksSuite();
+
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+if (import.meta.main) {
+  await main();
+}