@cosmicdrift/kumiko-guards 0.356.0 → 0.357.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.356.0",
+  "version": "0.357.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>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.356.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.357.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/bun-lock-packages.ts

@@ -12,7 +12,7 @@ export type LockPackage = {
 
 export type LockfileRead =
   | { readonly ok: true; readonly packages: readonly LockPackage[] }
-  | { readonly ok: false; readonly reason: string };
+  | { readonly ok: false; readonly detail: string };
 
 type ParsedBunLock = { readonly packages?: Record<string, unknown> };
 
@@ -76,19 +76,19 @@ export function readLockfilePackages(root: string): LockfileRead | undefined {
   try {
     parsed = JSON.parse(stripTrailingCommas(raw));
   } catch {
-    return { ok: false, reason: "not valid JSON" };
+    return { ok: false, detail: "not valid JSON" };
   }
-  if (!isParsedBunLock(parsed)) return { ok: false, reason: "unexpected top-level shape" };
+  if (!isParsedBunLock(parsed)) return { ok: false, detail: "unexpected top-level shape" };
 
   const lineOf = createLineLocator(raw);
   const packages: LockPackage[] = [];
   for (const [lockKey, entry] of Object.entries(parsed.packages ?? {})) {
     if (!Array.isArray(entry) || typeof entry[0] !== "string") {
-      return { ok: false, reason: `entry "${lockKey}" is not a resolved-package tuple` };
+      return { ok: false, detail: `entry "${lockKey}" is not a resolved-package tuple` };
     }
     const nameAndVersion = parseNameAndVersion(entry[0]);
     if (!nameAndVersion) {
-      return { ok: false, reason: `entry "${lockKey}" is not readable as name@version` };
+      return { ok: false, detail: `entry "${lockKey}" is not readable as name@version` };
     }
     packages.push({ lockKey, ...nameAndVersion, line: lineOf(lockKey) });
   }

package/src/_lib/guard-kit.ts

@@ -15,7 +15,7 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { relative as pathRelative, resolve, sep } from "node:path";
 import { Project, type SourceFile } from "ts-morph";
-import { compareToBaseline, findRepoRootFor } from "./baseline-compare";
+import { type BaselineRegression, compareToBaseline, findRepoRootFor } from "./baseline-compare";
 import {
   explainRepoRoots,
   findLocalRepo,
@@ -220,13 +220,55 @@ export function baselineRatchet(args: {
     const total = Object.values(perFile).reduce((sum, count) => sum + count, 0);
     const payload: BaselinePayload = {
       format: args.formatVersion,
-      generated: new Date().toISOString().slice(0, 10),
+      generated: Temporal.Now.instant().toString().slice(0, 10),
       total,
       perFile,
     };
     writeFileSync(args.file, `${JSON.stringify(payload, null, 2)}\n`);
     console.log(`  Baseline written: ${args.file} (total ${total})`);
   };
+  const regressionViolations = (
+    regressions: readonly BaselineRegression[],
+    message: (regression: BaselineRegression) => string,
+    resolveLine: ((file: string) => number) | undefined,
+  ): GuardViolation[] =>
+    regressions.map((regression) => ({
+      file: regression.file,
+      line: resolveLine?.(regression.file) ?? 1,
+      message: message(regression),
+    }));
+  const baselineProblem = (message: string): GuardViolation[] => [
+    { file: args.file, line: 1, message },
+  ];
+  const driftMessage = (raw: Partial<BaselinePayload>, driftHint: string): string | undefined => {
+    if (raw.format !== args.formatVersion) {
+      return `Baseline format drift: expected format=${args.formatVersion}, read format=${raw.format ?? "<missing>"}. ${driftHint}`;
+    }
+    if (typeof raw.perFile !== "object" || raw.perFile === null) {
+      return `Baseline file has no valid "perFile" object. ${driftHint}`;
+    }
+    return undefined;
+  };
+  const checkMissingBaseline = (
+    current: Readonly<Record<string, number>>,
+    remediation: string,
+    resolveLine: ((file: string) => number) | undefined,
+  ): GuardViolation[] => {
+    if (args.failClosed === true) {
+      return regressionViolations(
+        compareToBaseline(current, {}).regressions,
+        (regression) =>
+          `${args.unit} without a baseline file (${args.file}): ${regression.current} not frozen. ${remediation}`,
+        resolveLine,
+      );
+    }
+    // Nothing to freeze: a missing baseline is equivalent to an empty one.
+    if (Object.values(current).every((count) => count === 0)) return [];
+    console.log(
+      `  No baseline found (${args.file}). Freeze it first with \`--write-baseline\` — warning until then, no fail.`,
+    );
+    return [];
+  };
   const check = (
     current: Readonly<Record<string, number>>,
     remediation: string,
@@ -235,49 +277,20 @@ export function baselineRatchet(args: {
       readonly resolveLine?: (file: string) => number;
     },
   ): GuardViolation[] => {
-    if (!existsSync(args.file) && args.failClosed === true) {
-      return compareToBaseline(current, {}).regressions.map((regression) => ({
-        file: regression.file,
-        line: opts?.resolveLine?.(regression.file) ?? 1,
-        message: `${args.unit} without a baseline file (${args.file}): ${regression.current} not frozen. ${remediation}`,
-      }));
-    }
     if (!existsSync(args.file)) {
-      // Nothing to freeze: a missing baseline is equivalent to an empty one.
-      if (Object.values(current).every((count) => count === 0)) return [];
-      console.log(
-        `  No baseline found (${args.file}). Freeze it first with \`--write-baseline\` — warning until then, no fail.`,
-      );
-      return [];
+      return checkMissingBaseline(current, remediation, opts?.resolveLine);
     }
+    const driftHint = opts?.formatDriftRemediation ?? remediation;
     let raw: Partial<BaselinePayload>;
     try {
       raw = JSON.parse(readFileSync(args.file, "utf-8"));
     } catch (e) {
-      return [
-        {
-          file: args.file,
-          line: 1,
-          message: `Baseline file unreadable (broken JSON, merge marker, aborted write): ${e instanceof Error ? e.message : String(e)}. ${opts?.formatDriftRemediation ?? remediation}`,
-        },
-      ];
-    }
-    if (
-      raw.format !== args.formatVersion ||
-      typeof raw.perFile !== "object" ||
-      raw.perFile === null
-    ) {
-      return [
-        {
-          file: args.file,
-          line: 1,
-          message:
-            raw.format !== args.formatVersion
-              ? `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}`,
-        },
-      ];
+      return baselineProblem(
+        `Baseline file unreadable (broken JSON, merge marker, aborted write): ${e instanceof Error ? e.message : String(e)}. ${driftHint}`,
+      );
     }
+    const drift = driftMessage(raw, driftHint);
+    if (drift !== undefined) return baselineProblem(drift);
     const baseline = raw as BaselinePayload;
     const { regressions, reduced } = compareToBaseline(current, baseline.perFile);
     if (regressions.length === 0) {
@@ -286,12 +299,14 @@ export function baselineRatchet(args: {
       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} over baseline: baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline}). ${remediation}`,
-    }));
+    return regressionViolations(
+      regressions,
+      (regression) =>
+        `${args.unit} over baseline: baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline}). ${remediation}`,
+      opts?.resolveLine,
+    );
   };
+
   const handleCli = (current: Readonly<Record<string, number>>): boolean => {
     const cliArgs = process.argv.slice(2);
     if (cliArgs.includes("--write-baseline")) {
@@ -360,6 +375,71 @@ export type RunGuardsDeps = {
   readonly strictSecurityBaseline?: boolean;
 };
 
+function errorText(e: unknown): string {
+  return e instanceof Error ? (e.stack ?? e.message) : String(e);
+}
+
+function applySecurityBaselineFor(
+  guard: AstGuard,
+  outcome: GuardOutcome,
+  roots: readonly RepoRoot[],
+  deps: RunGuardsDeps,
+): ReturnType<typeof applySecurityBaseline> | undefined {
+  // Security guards get no skip flag: every finding must clear the baseline.
+  if (!isSecurityGuard(guard)) return undefined;
+  return applySecurityBaseline({
+    guardName: guard.name,
+    violations: outcome.violations,
+    roots,
+    cwd: process.cwd(),
+    load:
+      deps.securityBaseline ??
+      ((repo) => {
+        const root = roots.find((r) => r.name === repo);
+        return loadSecurityBaseline(repo, root?.absPath ?? process.cwd());
+      }),
+    strict: deps.strictSecurityBaseline === true,
+  });
+}
+
+function runOneGuard(
+  guard: AstGuard,
+  project: Project,
+  roots: readonly RepoRoot[],
+  scan: (guard: AstGuard, roots: readonly RepoRoot[]) => readonly RootScan[],
+  deps: RunGuardsDeps,
+  start: number,
+): RunResult {
+  const scans = scan(guard, roots);
+  const paths = [...new Set(scans.flatMap((s) => s.files))].sort();
+  const files = paths.map((p) => project.getSourceFile(p) ?? project.addSourceFileAtPath(p));
+  const outcome = guard.run(files, roots);
+  const securityResult = applySecurityBaselineFor(guard, outcome, roots, deps);
+  const effectiveOutcome: GuardOutcome = securityResult
+    ? { violations: securityResult.blocking }
+    : outcome;
+  const { violatingRoots } = checkRootFloor(guard, scans);
+  const notApplicable = scans.length === 0;
+  return {
+    name: guard.name,
+    ok: effectiveOutcome.violations.length === 0 && violatingRoots.length === 0,
+    ms: Math.round(performance.now() - start),
+    outcome: effectiveOutcome,
+    hint: guard.hint,
+    notApplicable,
+    skipReason: notApplicable
+      ? roots.length === 0
+        ? "repos-missing"
+        : "outside-kinds"
+      : undefined,
+    scanKinds: notApplicable ? guard.scan.kinds : undefined,
+    matchedFiles: files.length,
+    violatingRoots: violatingRoots.length > 0 ? violatingRoots : undefined,
+    frozenFindings: securityResult?.frozen,
+    security: securityResult !== undefined ? true : undefined,
+  };
+}
+
 // `project` is injectable so the run/catch wiring can be unit-tested with an
 // in-memory project — buildSharedProject() needs the framework tsconfig, absent
 // in a standalone repo checkout.
@@ -378,55 +458,13 @@ export function runGuards(
   for (const guard of guards) {
     const start = performance.now();
     try {
-      const scans = scan(guard, roots);
-      const paths = [...new Set(scans.flatMap((s) => s.files))].sort();
-      const files = paths.map((p) => project.getSourceFile(p) ?? project.addSourceFileAtPath(p));
-      const outcome = guard.run(files, roots);
-      // Security guards get no skip flag: every finding must clear the baseline.
-      const securityResult = isSecurityGuard(guard)
-        ? applySecurityBaseline({
-            guardName: guard.name,
-            violations: outcome.violations,
-            roots,
-            cwd: process.cwd(),
-            load:
-              deps.securityBaseline ??
-              ((repo) => {
-                const root = roots.find((r) => r.name === repo);
-                return loadSecurityBaseline(repo, root?.absPath ?? process.cwd());
-              }),
-            strict: deps.strictSecurityBaseline === true,
-          })
-        : undefined;
-      const effectiveOutcome: GuardOutcome = securityResult
-        ? { violations: securityResult.blocking }
-        : outcome;
-      const { violatingRoots } = checkRootFloor(guard, scans);
-      const notApplicable = scans.length === 0;
-      results.push({
-        name: guard.name,
-        ok: effectiveOutcome.violations.length === 0 && violatingRoots.length === 0,
-        ms: Math.round(performance.now() - start),
-        outcome: effectiveOutcome,
-        hint: guard.hint,
-        notApplicable,
-        skipReason: notApplicable
-          ? roots.length === 0
-            ? "repos-missing"
-            : "outside-kinds"
-          : undefined,
-        scanKinds: notApplicable ? guard.scan.kinds : undefined,
-        matchedFiles: files.length,
-        violatingRoots: violatingRoots.length > 0 ? violatingRoots : undefined,
-        frozenFindings: securityResult?.frozen,
-        security: securityResult !== undefined ? true : undefined,
-      });
+      results.push(runOneGuard(guard, project, roots, scan, deps, start));
     } catch (e) {
       results.push({
         name: guard.name,
         ok: false,
         ms: Math.round(performance.now() - start),
-        error: e instanceof Error ? (e.stack ?? e.message) : String(e),
+        error: errorText(e),
       });
     }
   }
@@ -600,6 +638,7 @@ export function printGuardKitBanner(
   if (error !== undefined) {
     console.error(error);
     process.exit(1);
+    // skip: process.exit is stubbed in tests, so control can fall through
     return;
   }
   console.log(`kumiko-guards ${guardKitVersion()} - ${guardCount} guards registered`);
@@ -674,55 +713,65 @@ export function classifyRun(args: {
   return { notApplicable, vacuous };
 }
 
+function printPassedResult(r: RunResult): void {
+  // Not applicable does not mean checked — that must stay visible,
+  // otherwise a standalone run reads like a complete one.
+  const scope = r.notApplicable
+    ? r.skipReason === "outside-kinds"
+      ? ` — skipped, repo kind outside guard kinds (${(r.scanKinds ?? []).join(", ")})`
+      : " — skipped, target repos not in checkout"
+    : ` (${r.matchedFiles ?? 0} files)`;
+  const frozen =
+    r.frozenFindings && r.frozenFindings > 0
+      ? ` — ${r.frozenFindings} frozen security findings (baseline)`
+      : "";
+  console.log(`  ✓ ${r.name} (${r.ms}ms)${scope}${frozen}`);
+  for (const w of r.warnings ?? []) {
+    console.log(`    ! ${w.file}:${w.line}  ${w.message}`);
+  }
+}
+
+function printViolationDetails(r: RunResult): void {
+  if (r.violatingRoots && r.violatingRoots.length > 0) {
+    console.error(
+      `    0 source files in: ${r.violatingRoots.join(", ")} — kumiko.json declares sourceRoots, scope "source" yields nothing there.`,
+    );
+    console.error(
+      "    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] Findings without baseline coverage always FAIL.`);
+  }
+  for (const v of r.outcome?.violations ?? []) {
+    console.error(`    ${v.file}:${v.line}  ${v.message}`);
+  }
+  for (const w of r.warnings ?? []) {
+    console.error(`    ! ${w.file}:${w.line}  ${w.message}`);
+  }
+  if (r.hint) console.error(`    → ${r.hint}`);
+}
+
+function printFailedResult(r: RunResult): void {
+  console.log(`  ✗ ${r.name} (${r.ms}ms)`);
+  if (r.error) {
+    console.error(`    THREW: ${r.error}`);
+  } else if (r.message) {
+    console.error(`    ${r.message}`);
+  } else {
+    printViolationDetails(r);
+  }
+}
+
 export function reportResults(results: readonly RunResult[]): number {
   let failed = 0;
   for (const r of results) {
     if (r.ok) {
-      // Not applicable does not mean checked — that must stay visible,
-      // otherwise a standalone run reads like a complete one.
-      const scope = r.notApplicable
-        ? r.skipReason === "outside-kinds"
-          ? ` — skipped, repo kind outside guard kinds (${(r.scanKinds ?? []).join(", ")})`
-          : " — skipped, target repos not in checkout"
-        : ` (${r.matchedFiles ?? 0} files)`;
-      const frozen =
-        r.frozenFindings && r.frozenFindings > 0
-          ? ` — ${r.frozenFindings} frozen security findings (baseline)`
-          : "";
-      console.log(`  ✓ ${r.name} (${r.ms}ms)${scope}${frozen}`);
-      for (const w of r.warnings ?? []) {
-        console.log(`    ! ${w.file}:${w.line}  ${w.message}`);
-      }
-      continue;
-    }
-    failed++;
-    console.log(`  ✗ ${r.name} (${r.ms}ms)`);
-    if (r.error) {
-      console.error(`    THREW: ${r.error}`);
-      continue;
-    }
-    if (r.message) {
-      console.error(`    ${r.message}`);
-      continue;
-    }
-    if (r.violatingRoots && r.violatingRoots.length > 0) {
-      console.error(
-        `    0 source files in: ${r.violatingRoots.join(", ")} — kumiko.json declares sourceRoots, scope "source" yields nothing there.`,
-      );
-      console.error(
-        "    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] Findings without baseline coverage always FAIL.`);
-    }
-    for (const v of r.outcome?.violations ?? []) {
-      console.error(`    ${v.file}:${v.line}  ${v.message}`);
-    }
-    for (const w of r.warnings ?? []) {
-      console.error(`    ! ${w.file}:${w.line}  ${w.message}`);
+      printPassedResult(r);
+    } else {
+      failed++;
+      printFailedResult(r);
     }
-    if (r.hint) console.error(`    → ${r.hint}`);
   }
   return failed;
 }

package/src/_lib/qn.ts

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * Shared helpers for qualified names (QN, e.g. "tickets:write:close").
+ * Extracted from guard-action-wiring.ts + guard-write-handler-qns.ts, which
+ * both had a byte-identical toKebab implementation inline.
  */
 
 export function toKebab(s: string): string {
@@ -11,11 +11,11 @@ export function toKebab(s: string): string {
     .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.
+// Regex for a valid write-handler QN.
+// Allows 3 segments (feature:write:handler) or 4+ (feature:write:entity:verb, feature:write:domain:entity:verb).
+// Accepts camelCase + kebab-case — normalization to kebab happens before the manifest match.
+// Every segment is validated on its own (no ":" in the segment character set) — otherwise
+// the last segment group would accept trailing/double colons like
+// "tickets:write:close:" as valid.
 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/roots.ts

@@ -41,9 +41,10 @@ export type RepoRoot = {
 const warnedDerivedFallbacks = new Set<string>();
 
 function warnDerivedFallbackOnce(message: string): void {
-  if (warnedDerivedFallbacks.has(message)) return;
-  warnedDerivedFallbacks.add(message);
-  console.error(message);
+  if (!warnedDerivedFallbacks.has(message)) {
+    warnedDerivedFallbacks.add(message);
+    console.error(message);
+  }
 }
 
 const manifestCache = new Map<string, LoadedRepoManifest | undefined>();