@cosmicdrift/kumiko-guards 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -23,6 +23,9 @@
       "default": "./src/index.ts"
     }
   },
+  "bin": {
+    "kumiko-guards": "./src/cli.ts"
+  },
   "dependencies": {
     "@cosmicdrift/kumiko-repo-manifest": "0.1.0",
     "ts-morph": "^28.0.0"

package/src/_lib/guard-kit.ts

@@ -13,7 +13,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { relative as pathRelative } from "node:path";
+import { relative as pathRelative, resolve } from "node:path";
 import { Project, type SourceFile } from "ts-morph";
 import { compareToBaseline, findRepoRootFor } from "./baseline-compare";
 import {
@@ -126,6 +126,13 @@ export function isAllowlisted(relPath: string, allowlist: readonly RegExp[]): bo
   return allowlist.some((re) => re.test(relPath));
 }
 
+// allRepos guards render sibling hits as "../<repo>/..." relative to ROOT —
+// freezing those into a repo-local baseline would fail a sibling's own
+// refactor locally while CI (no sibling checked out there) never sees it.
+export function isLocalFinding<T extends { readonly file: string }>(item: T): boolean {
+  return !item.file.startsWith("../");
+}
+
 type BaselinePayload = {
   readonly format: number;
   readonly generated: string;
@@ -161,7 +168,7 @@ export function baselineRatchet(args: {
       perFile,
     };
     writeFileSync(args.file, `${JSON.stringify(payload, null, 2)}\n`);
-    console.log(`  Baseline geschrieben: ${args.file} (total ${total})`);
+    console.log(`  Baseline written: ${args.file} (total ${total})`);
   };
   const check = (
     current: Readonly<Record<string, number>>,
@@ -173,7 +180,7 @@ export function baselineRatchet(args: {
   ): GuardViolation[] => {
     if (!existsSync(args.file)) {
       console.log(
-        `  Keine Baseline gefunden (${args.file}). Erst mit \`--write-baseline\` einfrieren — bis dahin Warnung, kein Fail.`,
+        `  No baseline found (${args.file}). Freeze it first with \`--write-baseline\` — warning until then, no fail.`,
       );
       return [];
     }
@@ -185,7 +192,7 @@ export function baselineRatchet(args: {
         {
           file: args.file,
           line: 1,
-          message: `Baseline-Datei nicht lesbar (kaputtes JSON, Merge-Marker, abgebrochener Write): ${e instanceof Error ? e.message : String(e)}. ${opts?.formatDriftRemediation ?? remediation}`,
+          message: `Baseline file unreadable (broken JSON, merge marker, aborted write): ${e instanceof Error ? e.message : String(e)}. ${opts?.formatDriftRemediation ?? remediation}`,
         },
       ];
     }
@@ -200,8 +207,8 @@ export function baselineRatchet(args: {
           line: 1,
           message:
             raw.format !== args.formatVersion
-              ? `Baseline-Format-Drift: erwartet format=${args.formatVersion}, gelesen format=${raw.format ?? "<missing>"}. ${opts?.formatDriftRemediation ?? remediation}`
-              : `Baseline-Datei hat kein gültiges "perFile"-Objekt. ${opts?.formatDriftRemediation ?? remediation}`,
+              ? `Baseline format drift: expected format=${args.formatVersion}, read format=${raw.format ?? "<missing>"}. ${opts?.formatDriftRemediation ?? remediation}`
+              : `Baseline file has no valid "perFile" object. ${opts?.formatDriftRemediation ?? remediation}`,
         },
       ];
     }
@@ -209,14 +216,14 @@ export function baselineRatchet(args: {
     const { regressions, reduced } = compareToBaseline(current, baseline.perFile);
     if (regressions.length === 0) {
       const total = Object.values(current).reduce((sum, count) => sum + count, 0);
-      console.log(`  ✓ Baseline (${baseline.total}) — aktuell ${total}`);
-      if (reduced > 0) console.log(`  ✓ ${reduced} ${args.unit} reduziert seit Baseline.`);
+      console.log(`  ✓ Baseline (${baseline.total}) — current ${total}`);
+      if (reduced > 0) console.log(`  ✓ ${reduced} ${args.unit} reduced since baseline.`);
       return [];
     }
     return regressions.map((regression) => ({
       file: regression.file,
       line: opts?.resolveLine?.(regression.file) ?? 1,
-      message: `${args.unit} über Baseline: baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline}). ${remediation}`,
+      message: `${args.unit} over baseline: baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline}). ${remediation}`,
     }));
   };
   const handleCli = (current: Readonly<Record<string, number>>): boolean => {
@@ -226,7 +233,7 @@ export function baselineRatchet(args: {
       return true;
     }
     if (cliArgs.includes("--no-baseline")) {
-      console.log("  Baseline-Vergleich uebersprungen (--no-baseline).");
+      console.log("  Baseline comparison skipped (--no-baseline).");
       return true;
     }
     return false;
@@ -362,7 +369,7 @@ export type RepoCheck = {
 };
 
 const VACUOUS_MESSAGE =
-  "0 Dateien gescannt, obwohl die Ziel-Repos im Checkout liegen — die Globs greifen nicht.";
+  "0 files scanned even though the target repos are in the checkout — the globs are not matching.";
 
 /** Standalone-`main()` guards (their own scan/walk, no shared ts-morph project) run in-process through this. */
 export async function runRepoChecks(
@@ -435,7 +442,7 @@ export function explainGuards(
     for (const { root, source } of roots) {
       const rootScan = scanByAbsPath.get(root.absPath);
       if (!rootScan) {
-        lines.push(`  ${root.name} [${source}] — außerhalb kinds`);
+        lines.push(`  ${root.name} [${source}] — outside kinds`);
         continue;
       }
       // Exact-path lookup, never a re-glob: `project.getSourceFiles(globs)`
@@ -443,13 +450,61 @@ export function explainGuards(
       // `[id].tsx` is then a broken (or pathologically slow) character class.
       const fileCount = rootScan.files.filter((f) => project.getSourceFile(f) !== undefined).length;
       lines.push(
-        `  ${root.name} [${source}] ${fileCount} Dateien (Source-Surface ${rootScan.sourceSurface})`,
+        `  ${root.name} [${source}] ${fileCount} files (source surface ${rootScan.sourceSurface})`,
       );
     }
   }
   return lines;
 }
 
+function guardKitVersion(): string {
+  const pkgPath = resolve(import.meta.dir, "../../package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { readonly version?: string };
+  return pkg.version ?? "0.0.0";
+}
+
+/**
+ * Pure preflight verdict, injectable for tests: which of the two globally
+ * silent-green cases (infra#2863) applies, if any. Not to be confused with a
+ * single guard finding no target repos — that stays a per-guard `skipped`
+ * line in `reportResults`.
+ */
+export function guardKitPreflightError(guardCount: number, rootCount: number): string | undefined {
+  if (rootCount === 0) {
+    return "No repo root resolved — checkout has no package.json with a kumiko.json/src layout above cwd.";
+  }
+  if (guardCount === 0) {
+    return "No guards registered — the runner's guard array is empty.";
+  }
+  return undefined;
+}
+
+export type GuardKitBannerDeps = {
+  readonly resolution?: RootResolution;
+};
+
+/**
+ * Shared entrypoint banner for the three bin/run-*.ts runners: fails closed
+ * on the two globally-empty cases above, otherwise prints the header every
+ * run starts with, before the first guard result. Not used by `--explain`,
+ * which already prints its own "Repo: ..." header.
+ */
+export function printGuardKitBanner(
+  guardCount: number,
+  project?: Project,
+  deps: GuardKitBannerDeps = {},
+): void {
+  const { roots } = deps.resolution ?? explainRepoRoots();
+  const error = guardKitPreflightError(guardCount, roots.length);
+  if (error !== undefined) {
+    console.error(error);
+    process.exit(1);
+  }
+  console.log(`kumiko-guards ${guardKitVersion()} - ${guardCount} guards registered`);
+  console.log(`Roots: ${roots.map((r) => r.root.name).join(", ")} (${roots.length})`);
+  if (project) console.log(`Project: ${project.getSourceFiles().length} files`);
+}
+
 /**
  * Vacuity floor for guards with their own `main()`.
  *
@@ -483,11 +538,11 @@ export function reportResults(results: readonly RunResult[]): number {
       // Not applicable does not mean checked — that must stay visible,
       // otherwise a standalone run reads like a complete one.
       const scope = r.notApplicable
-        ? " — übersprungen, Ziel-Repos nicht im Checkout"
-        : ` (${r.matchedFiles ?? 0} Dateien)`;
+        ? " — skipped, target repos not in checkout"
+        : ` (${r.matchedFiles ?? 0} files)`;
       const frozen =
         r.frozenFindings && r.frozenFindings > 0
-          ? ` — ${r.frozenFindings} eingefrorene Security-Findings (Baseline)`
+          ? ` — ${r.frozenFindings} frozen security findings (baseline)`
           : "";
       console.log(`  ✓ ${r.name} (${r.ms}ms)${scope}${frozen}`);
       for (const w of r.warnings ?? []) {
@@ -507,14 +562,14 @@ export function reportResults(results: readonly RunResult[]): number {
     }
     if (r.violatingRoots && r.violatingRoots.length > 0) {
       console.error(
-        `    0 Quelldateien in: ${r.violatingRoots.join(", ")} — kumiko.json deklariert sourceRoots, der Scope "source" liefert dort nichts.`,
+        `    0 source files in: ${r.violatingRoots.join(", ")} — kumiko.json declares sourceRoots, scope "source" yields nothing there.`,
       );
       console.error(
-        "    Manifest (kumiko.json) oder Checkout prüfen; ohne Manifest gilt der abgeleitete Fallback packages/*/src bzw. src/.",
+        "    Check the manifest (kumiko.json) or the checkout; without a manifest the derived fallback packages/*/src or src/ applies.",
       );
     }
     if (r.security) {
-      console.error(`    [security] Funde ohne Baseline-Deckung sind immer FAIL.`);
+      console.error(`    [security] Findings without baseline coverage always FAIL.`);
     }
     for (const v of r.outcome?.violations ?? []) {
       console.error(`    ${v.file}:${v.line}  ${v.message}`);

package/src/_lib/qn.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared helpers für Qualified-Names (QN, z.B. "tickets:write:close").
+ * Extrahiert aus guard-action-wiring.ts + guard-write-handler-qns.ts, die
+ * beide eine byte-identische toKebab-Implementierung inline hatten.
+ */
+
+export function toKebab(s: string): string {
+  return s
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+// Regex für ein gültiges Write-Handler-QN.
+// Erlaubt 3 Segmente (feature:write:handler) oder 4+ (feature:write:entity:verb, feature:write:domain:entity:verb).
+// Akzeptiert camelCase + kebab-case — Normalisierung auf kebab erfolgt vor Manifest-Match.
+// Jedes Segment einzeln validiert (kein ":" im Segment-Zeichensatz) — sonst
+// akzeptiert die letzte Segment-Gruppe trailing/doppelte Colons wie
+// "tickets:write:close:" als valide.
+export const VALID_QN_RE =
+  /^[a-zA-Z][a-zA-Z0-9-]*:write:[a-zA-Z][a-zA-Z0-9-]*(:[a-zA-Z][a-zA-Z0-9-]*)*$/;

package/src/_lib/security-baseline-cli.ts

@@ -28,7 +28,7 @@ export function writeSecurityBaselines(guards: readonly AstGuard[], project: Pro
   for (const root of roots) {
     const load = loadSecurityBaseline(root.name, root.absPath);
     if (load.kind === "invalid") {
-      console.error(`  ✗ Security-Baseline ${load.file}: ${load.reason}`);
+      console.error(`  ✗ Security baseline ${load.file}: ${load.reason}`);
       process.exit(1);
     }
     hardFailByRepo.set(root.name, load.hardFail);
@@ -38,7 +38,7 @@ export function writeSecurityBaselines(guards: readonly AstGuard[], project: Pro
     const hardFail = hardFailByRepo.get(root.name) ?? [];
     const baseline = buildSecurityBaseline(root.name, guardViolations, roots, cwd, hardFail);
     const path = writeSecurityBaseline(baseline, root.absPath);
-    console.log(`  Security-Baseline geschrieben: ${path} (total ${baseline.total})`);
+    console.log(`  Security baseline written: ${path} (total ${baseline.total})`);
     for (const guardName of hardFail) {
       const count = guardViolations
         .filter((gv) => gv.guardName === guardName)
@@ -46,7 +46,7 @@ export function writeSecurityBaselines(guards: readonly AstGuard[], project: Pro
         .filter((v) => locateFinding(v.file, roots, cwd)?.repo === root.name).length;
       if (count > 0) {
         console.warn(
-          `  ! ${root.name}: ${count} Funde von ${guardName} nicht eingefroren (hardFail) — der Guard-Lauf blockiert sie`,
+          `  ! ${root.name}: ${count} findings from ${guardName} not frozen (hardFail) — the guard run blocks them`,
         );
       }
     }

package/src/_lib/security-baseline.ts

@@ -98,18 +98,18 @@ export function loadSecurityBaseline(repo: string, repoDir: string): SecurityBas
     return {
       kind: "invalid",
       file,
-      reason: `kaputtes JSON: ${e instanceof Error ? e.message : String(e)}`,
+      reason: `broken JSON: ${e instanceof Error ? e.message : String(e)}`,
     };
   }
   const parsed = parseSecurityBaseline(raw);
   if (!parsed) {
-    return { kind: "invalid", file, reason: "unerwartetes Baseline-Format (format/repo/findings)" };
+    return { kind: "invalid", file, reason: "unexpected baseline format (format/repo/findings)" };
   }
   if (parsed.repo !== repo) {
     return {
       kind: "invalid",
       file,
-      reason: `repo-Feld "${parsed.repo}" passt nicht zum Dateinamen "${repo}"`,
+      reason: `repo field "${parsed.repo}" does not match the file name "${repo}"`,
     };
   }
   return { kind: "ok", findings: parsed.findings, hardFail: parsed.hardFail ?? [] };
@@ -192,7 +192,7 @@ export function applySecurityBaseline(args: {
         {
           file: baseline.file,
           line: 1,
-          message: `Security-Baseline unlesbar oder ungültig: ${baseline.reason}. Datei reparieren; ein kaputter Baseline-Stand darf keine Funde freigeben.`,
+          message: `Security baseline unreadable or invalid: ${baseline.reason}. Fix the file; a broken baseline must not release any findings.`,
         },
       ]);
       for (const e of allEntries) blockingEntries.push([e.index, e.violation]);
@@ -204,7 +204,7 @@ export function applySecurityBaseline(args: {
           e.index,
           {
             ...e.violation,
-            message: `${e.violation.message} (Security-Baseline ${repo}: ${guardName} ist fertig migriert — keine Baseline-Toleranz)`,
+            message: `${e.violation.message} (security baseline ${repo}: ${guardName} finished migrating — no baseline tolerance)`,
           },
         ]);
       }
@@ -224,7 +224,7 @@ export function applySecurityBaseline(args: {
             e.index,
             {
               ...e.violation,
-              message: `${e.violation.message} (Security-Baseline ${repo}: erlaubt=${regression.baseline}, aktuell=${regression.current})`,
+              message: `${e.violation.message} (security baseline ${repo}: allowed=${regression.baseline}, current=${regression.current})`,
             },
           ]);
         }
@@ -247,7 +247,7 @@ export function applySecurityBaseline(args: {
           {
             file: baseline.file,
             line: 1,
-            message: `Security-Baseline unlesbar oder ungültig: ${baseline.reason}. Datei reparieren; ein kaputter Baseline-Stand darf keine Funde freigeben.`,
+            message: `Security baseline unreadable or invalid: ${baseline.reason}. Fix the file; a broken baseline must not release any findings.`,
           },
         ]);
         continue;
@@ -267,7 +267,7 @@ export function applySecurityBaseline(args: {
           {
             file: join(root.absPath, r.file),
             line: 1,
-            message: `Security-Baseline veraltet: ${root.name}/${r.file} erlaubt ${r.baseline}, gefunden ${r.current} — \`--write-security-baseline\` ausführen und committen, sonst deckt der Headroom neue Funde.`,
+            message: `Security baseline stale: ${root.name}/${r.file} allows ${r.baseline}, found ${r.current} — run \`--write-security-baseline\` and commit, otherwise the headroom covers new findings.`,
           },
         ]);
       }

package/src/changes.json

@@ -1,4 +1,36 @@
 [
+  {
+    "version": "0.3.0",
+    "type": "improvement",
+    "title": "Add a consumer CLI entry so bunx @cosmicdrift/kumiko-guards runs all three suites"
+  },
+  {
+    "version": "0.3.0",
+    "type": "fix",
+    "title": "Fix two false-positive findings in the Secret-Literal and Thin-Wrappers guards",
+    "detail": "The Secret-Literal Guard flagged secret-fallback patterns documented inside comments: only line-start `//` comments were skipped, so a block-comment line (JSDoc-style `*`, `/*`, `*/`) explaining the rule tripped the guard on its own documentation. Block-comment lines are now recognized as comments too. The Thin-Wrappers Guard misread `/regex/.test(x)` as a call to a function literally named `test`, reporting the enclosing function as a thin wrapper around it. That misclassification no longer fires."
+  },
+  {
+    "version": "0.3.0",
+    "type": "improvement",
+    "title": "Port the last five infra/guards guards",
+    "detail": "app-feature-structure, lib-test-coverage, i18n-locale-terminology, feature-integration-tests, and test-stack-drift ported from the private infra/guards package into the public @cosmicdrift/kumiko-guards package. The latter two were rebuilt from ad-hoc infra scripts onto the public RepoCheck pattern; the other three are literal AstGuard ports."
+  },
+  {
+    "version": "0.3.0",
+    "type": "improvement",
+    "title": "Add startup banner, fail-closed on zero roots/guards, and finish English output"
+  },
+  {
+    "version": "0.2.0",
+    "type": "improvement",
+    "title": "Migrate remaining framework-semantic guards out of infra/guards"
+  },
+  {
+    "version": "0.2.0",
+    "type": "improvement",
+    "title": "Add runner parity with the private infra/guards package"
+  },
   {
     "version": "0.1.1",
     "type": "fix",