@cosmicdrift/kumiko-guards 0.281.0 → 0.283.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.281.0",
+  "version": "0.283.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>",
@@ -27,7 +27,7 @@
     "kumiko-guards": "./src/cli.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.281.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.283.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/generic-reason.ts

@@ -1,4 +1,4 @@
-import { type Node, SyntaxKind } from "ts-morph";
+import { type Node, SyntaxKind, VariableDeclarationKind } from "ts-morph";
 
 const GENERIC_REASONS = new Set([
   "",
@@ -29,6 +29,36 @@ export function literalReasonText(node: Node | undefined): string | undefined {
   return undefined;
 }
 
+// Resolves an Identifier to a module-local `const` initializer, so a
+// shared reason constant clears the same way as writing its text inline.
+// No import-boundary resolution, no `let` (reassignment stays unjudged).
+function resolveConstIdentifierText(node: Node): string | undefined {
+  if (!node.isKind(SyntaxKind.Identifier)) return undefined;
+  const declarations = node.getSymbol()?.getDeclarations() ?? [];
+  for (const decl of declarations) {
+    if (!decl.isKind(SyntaxKind.VariableDeclaration)) continue;
+    if (decl.getSourceFile() !== node.getSourceFile()) continue;
+    if (decl.getVariableStatement()?.getDeclarationKind() !== VariableDeclarationKind.Const) {
+      continue;
+    }
+    const text = literalReasonText(decl.getInitializer());
+    if (text !== undefined) return text;
+  }
+  return undefined;
+}
+
+// Same contract as literalReasonText, plus one hop: an Identifier that
+// resolves to a module-local `const` string/template initializer resolves
+// to that text. An import, a call, a template with substitutions, or a
+// `let`/reassigned binding stays undefined — same "not statically judgeable"
+// convention as literalReasonText.
+export function resolveReasonText(node: Node | undefined): string | undefined {
+  if (!node) return undefined;
+  const literal = literalReasonText(node);
+  if (literal !== undefined) return literal;
+  return resolveConstIdentifierText(node);
+}
+
 export function isGenericReason(text: string): boolean {
   const lowered = text.trim().toLowerCase();
   if (GENERIC_PREFIXES.some((prefix) => lowered.startsWith(prefix))) {

package/src/_lib/guard-kit.ts

@@ -479,6 +479,23 @@ export function guardKitPreflightError(guardCount: number, rootCount: number): s
   return undefined;
 }
 
+/**
+ * Validates CLI args for one subcommand against the flags it actually
+ * understands — every arg must match `known` exactly (not just a `--`-prefix
+ * check, which let a single-dash typo or a stray positional through
+ * unnoticed). An unknown arg must fail loud, never pass through silently.
+ */
+export function cliFlagsError(
+  subcommand: string,
+  argv: readonly string[],
+  known: readonly string[],
+): string | undefined {
+  const unknown = argv.filter((arg) => !known.includes(arg));
+  if (unknown.length === 0) return undefined;
+  const knownList = known.length > 0 ? known.join(", ") : "(none)";
+  return `Unknown argument${unknown.length > 1 ? "s" : ""} for "${subcommand}": ${unknown.join(", ")}. Known flags: ${knownList}`;
+}
+
 export type GuardKitBannerDeps = {
   readonly resolution?: RootResolution;
 };
@@ -505,6 +522,47 @@ export function printGuardKitBanner(
   if (project) console.log(`Project: ${project.getSourceFiles().length} files`);
 }
 
+export type SuiteInventory = {
+  readonly count: number;
+  readonly names: readonly string[];
+};
+
+export type GuardKitInventory = {
+  readonly version: string;
+  readonly total: number;
+  readonly suites: {
+    readonly guards: SuiteInventory;
+    readonly ui: SuiteInventory;
+    readonly checks: SuiteInventory;
+  };
+};
+
+function suiteInventory(items: readonly { readonly name: string }[]): SuiteInventory {
+  const names = items.map((item) => item.name);
+  return { count: names.length, names };
+}
+
+/**
+ * Static registration inventory for the three suites — reads each array's
+ * `.name` only, no scan/project/guard.run(). What a consumer's CI checks
+ * against instead of running the guards, e.g. so a guard dropped from a
+ * suite's array is missing here too, not just silently absent from a run.
+ */
+export function buildGuardKitInventory(args: {
+  readonly guards: readonly { readonly name: string }[];
+  readonly uiGuards: readonly { readonly name: string }[];
+  readonly checks: readonly { readonly name: string }[];
+}): GuardKitInventory {
+  const guards = suiteInventory(args.guards);
+  const ui = suiteInventory(args.uiGuards);
+  const checks = suiteInventory(args.checks);
+  return {
+    version: guardKitVersion(),
+    total: guards.count + ui.count + checks.count,
+    suites: { guards, ui, checks },
+  };
+}
+
 /**
  * Vacuity floor for guards with their own `main()`.
  *

package/src/changes.json

@@ -1,4 +1,27 @@
 [
+  {
+    "version": "0.283.0",
+    "type": "fix",
+    "title": "Escape-Hatch-Declared Guard resolves a module-local const reason instead of forcing duplicate literals",
+    "detail": "`_lib/generic-reason.ts`'s `literalReasonText` only accepted a string/template literal in place — an Identifier (even a module-local `const SOME_REASON = \"...\"`) fell through as \"not statically judgeable\" and was rejected exactly like a real placeholder. Every consumer declaring several hooks with the same justification (e.g. publicstatus's five GDPR delete hooks) had to repeat the same reason text literally in each `declareEscapeHatch({ reason })` / `escapeHatch: { reason }` / `unsafeAllTenants: { reason }` / `acknowledgeCrossTenant(reason)` call, because a shared constant made the guard fail.\nThe guard now resolves an Identifier to a module-local `const` initializer (string or non-templated template literal only — no imports, no `let`, no reassignment) via a new `resolveReasonText`, used at all four call sites; `isGenericReason` is unchanged and still applies to the resolved text, so a const resolving to `\"todo\"` is rejected exactly as before. An import, a function call, or a template literal with substitutions still doesn't resolve, and the `unsafe-raw-outside-system-scope` / `system-identity-outside-declared-scope` findings now say why when a nearby `declareEscapeHatch` call's reason is one of those three shapes. Both R2 and R3's base messages now also name `declareEscapeHatch({ reason: \"...\" })` as a direct body statement of a named hook among the allowed ways to clear the finding."
+  },
+  {
+    "version": "0.282.0",
+    "type": "fix",
+    "title": "kumiko-guards bin now passes flags through to the guards, ui, and checks subcommands",
+    "detail": "The bin's `guards` subcommand called run-guards.ts's suite runner directly, skipping the `--explain`/`--write-security-baseline`/`--strict-security-baseline` handling that only existed in run-guards.ts's own `if (import.meta.main)` block — a consumer running `bunx @cosmicdrift/kumiko-guards guards --write-security-baseline` got a normal guard run with the flag silently dropped. Each suite (guards, ui, checks) now exports a `run*Cli(argv)` function that validates argv against that suite's known flags and applies them; both the bin and the suite's own direct-invocation entry point call the same function, so they cannot drift apart again. Validation matches each arg exactly against the known list (not just a `--`-prefix check), so a single-dash typo or a stray positional also exits 1 with the flags that subcommand accepts, rather than passing through unnoticed."
+  },
+  {
+    "version": "0.282.0",
+    "type": "improvement",
+    "title": "kumiko-guards list prints the registration inventory as JSON"
+  },
+  {
+    "version": "0.282.0",
+    "type": "improvement",
+    "title": "Port the upgrade-state and runtime-isolation guards",
+    "detail": "guard-upgrade-state and check-runtime-isolation ported from the private infra/guards package into the public @cosmicdrift/kumiko-guards package, rebuilt onto the public RepoCheck pattern with single-repo root resolution. guard-app-dockerfile, guard-doc-status, check-licenses, and check-security stay in infra/guards as CDGS-specific house rules (private registry scope, CDGS doc taxonomy, and CDGS license/security exception files with no equivalent consumer-facing mechanism in the public package) — they were deliberately not ported, not forgotten."
+  },
   {
     "version": "0.3.0",
     "type": "improvement",

package/src/check-runtime-isolation.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+// Runtime-Isolation Guard.
+//
+// Prevents production code (runtime) from transitively loading test or
+// tooling modules — the original trigger was a top-level Vitest import in a
+// testing helper that crashed drizzle-kit under Node. Every file gets a
+// runtime context assigned; every import edge is checked against a compat
+// matrix.
+//
+// Per-file classification (highest priority first):
+//   1. File directive       →  // @runtime <kind>  in the first 5 lines
+//   2. Path pattern         →  *.test.ts, *.integration.ts, *.e2e.ts,
+//                               **/__tests__/**, **/testing/**  → test;
+//                               plus a handful of verified-isomorphic
+//                               single-file/directory carve-outs (see
+//                               runtime-isolation-classify.ts)
+//   3. Workspace             →  package.json `"kumiko": { "runtime": "..." }`
+//   4. Client reachability   →  transitively reachable, via value imports,
+//                                from a browser-bundle entry
+//                                (`src/client-*.tsx`) or from any file that
+//                                already classifies as "client" on its own
+//                                (directive/path/workspace)
+//   5. Default                →  runtime
+//
+// Compat matrix: which runtime context may import which.
+//   runtime → runtime, client
+//   client  → client
+//   dev     → runtime, client, dev, tooling
+//   tooling → runtime, client, dev, tooling, test
+//   test    → everything
+//
+// Single-repo only (unlike infra/guards' check-runtime-isolation.ts, which
+// scans every sibling checkout in one shared ts-morph project): this public
+// package only ever resolves the repo `cwd` sits in, so there is exactly one
+// repo root to classify files against.
+//
+// Pure classification + violation detection live in
+// `runtime-isolation-classify.ts` (unit-testable with an in-memory ts-morph
+// project) — this file only does the repo/glob resolution, ts-morph project
+// setup, and RepoCheck wiring.
+//
+// A file/import edge classified "client" importing "runtime" can be a real
+// finding this guard needs to see, but can also be a known, reviewed
+// exception (e.g. samples/recipes are worked examples, not the framework's
+// own production surface — see kumiko-framework#2337 for the one currently
+// frozen here). Exceptions are tracked via a per-repo baseline file
+// (`.kumiko-runtime-isolation-baseline.json`, same `baselineRatchet`
+// mechanism as check-complexity/guard-pii-annotations/etc.), not a
+// hardcoded list in this source file: a consumer repo can freeze or clear
+// its own findings the same way, with `--write-baseline`.
+//
+// Usage:
+//   bun packages/guards/src/check-runtime-isolation.ts
+//   bun packages/guards/src/check-runtime-isolation.ts --write-baseline
+
+import * as path from "node:path";
+import { Project } from "ts-morph";
+import {
+  baselineRatchet,
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import { frameworkTsConfigPath, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
+import {
+  classify,
+  computeClientReachablePaths,
+  findRuntimeIsolationViolations,
+  isClientEntryPath,
+  type Runtime,
+} from "./runtime-isolation-classify";
+
+const SCAN: ScanSpec = { scope: "source", extensions: ["ts", "tsx"] };
+const BASELINE_FILE = ".kumiko-runtime-isolation-baseline.json";
+
+type RawViolation = {
+  readonly file: string;
+  readonly line: number;
+  readonly fileRuntime: Runtime;
+  readonly importedSpec: string;
+  readonly importedRuntime: Runtime;
+};
+
+function printViolation(v: RawViolation, root: string): void {
+  const fileRel = path.relative(root, v.file);
+  console.log(`  ${fileRel}:${v.line}`);
+  console.log(`    [${v.fileRuntime}] imports [${v.importedRuntime}] "${v.importedSpec}"`);
+}
+
+function violationKey(rootAbsPath: string, v: RawViolation): string {
+  return `${path.relative(rootAbsPath, v.file)}::${v.importedSpec}`;
+}
+
+function countByKey(
+  rootAbsPath: string,
+  violations: readonly RawViolation[],
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const v of violations) {
+    const key = violationKey(rootAbsPath, v);
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function ratchetFor(rootAbsPath: string) {
+  return baselineRatchet({
+    file: path.join(rootAbsPath, BASELINE_FILE),
+    formatVersion: 1,
+    unit: "runtime-isolation violation(s)",
+  });
+}
+
+function scanRoot(root: RepoRoot): {
+  allViolations: readonly RawViolation[];
+  outsideRoot: readonly string[];
+  scannedFiles: number;
+} {
+  const tsConfigFilePath = frameworkTsConfigPath();
+  const project =
+    tsConfigFilePath !== undefined
+      ? new Project({
+          tsConfigFilePath,
+          skipAddingFilesFromTsConfig: true,
+          skipFileDependencyResolution: true,
+        })
+      : new Project({ skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: true });
+
+  const paths = scanFiles(SCAN, [root]);
+  // Exact-path lookup, never a re-glob: `project.getSourceFiles(paths)`
+  // treats each array entry as a glob pattern — pathologically slow (and,
+  // for a bracketed filename like `[id].tsx`, a broken character class)
+  // over thousands of paths. `getSourceFile(path)` is an exact lookup.
+  const scannedFiles = paths
+    .map((p) => project.getSourceFile(p) ?? project.addSourceFileAtPath(p))
+    .filter((f) => {
+      const fp = f.getFilePath();
+      return !fp.includes("/node_modules/") && !fp.includes("/dist/");
+    });
+
+  const workspaceCache = new Map<string, Runtime | null>();
+  const clientReachable = computeClientReachablePaths(scannedFiles, (sf) => {
+    const rel = path.relative(root.absPath, sf.getFilePath());
+    if (isClientEntryPath(rel)) return true;
+    return classify(sf.getFilePath(), root.absPath, workspaceCache) === "client";
+  });
+
+  const { violations: allViolations, outsideRoot } = findRuntimeIsolationViolations(
+    scannedFiles,
+    root.absPath,
+    workspaceCache,
+    clientReachable,
+  );
+
+  return { allViolations, outsideRoot, scannedFiles: scannedFiles.length };
+}
+
+export const check: RepoCheck = {
+  name: "Runtime-Isolation Check",
+  hint:
+    "runtime may import runtime/client only; client may import client only; " +
+    "dev/tooling/test are more permissive. See runtime-isolation-classify.ts for the compat matrix. " +
+    "New, deliberate exception? `bun packages/guards/src/check-runtime-isolation.ts --write-baseline`",
+  run(roots) {
+    const root = roots[0];
+    if (!root) return { violations: [], matchedFiles: 0, notApplicable: true };
+    const rootAbsPath = root.absPath;
+
+    const { allViolations, outsideRoot, scannedFiles } = scanRoot(root);
+    for (const v of allViolations) printViolation(v, rootAbsPath);
+
+    const counts = countByKey(rootAbsPath, allViolations);
+    const resolveLine = (key: string): number => {
+      const relFile = key.split("::")[0];
+      return allViolations.find((v) => path.relative(rootAbsPath, v.file) === relFile)?.line ?? 1;
+    };
+    const violations: GuardViolation[] = ratchetFor(rootAbsPath).check(
+      counts,
+      "runtime may import runtime/client only; client may import client only — see runtime-isolation-classify.ts for the compat matrix.",
+      {
+        formatDriftRemediation:
+          "Run `bun packages/guards/src/check-runtime-isolation.ts --write-baseline` once.",
+        resolveLine,
+      },
+    );
+
+    if (outsideRoot.length > 0) {
+      console.log(
+        `  Runtime-Isolation Check: ${outsideRoot.length} import target(s) outside the repo root (skipped).`,
+      );
+    }
+
+    return { violations, matchedFiles: scannedFiles, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  if (args.includes("--write-baseline")) {
+    const root = resolveRepoRoots()[0];
+    if (!root) {
+      console.error("No repo root resolved — nothing to baseline.");
+      process.exit(1);
+    }
+    const { allViolations } = scanRoot(root);
+    for (const v of allViolations) printViolation(v, root.absPath);
+    ratchetFor(root.absPath).write(countByKey(root.absPath, allViolations));
+    process.exit(0);
+  }
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/cli.ts

@@ -1,55 +1,79 @@
 #!/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;
+// runners already use in their own `if (import.meta.main)` blocks — including
+// flags, which each runner's own *Cli function validates and applies so this
+// bin and the direct `bun run-*.ts` invocation can never drift apart.
+import { buildGuardKitInventory, cliFlagsError } from "./_lib/guard-kit";
+import { GUARD_FLAGS, GUARDS, runGuardsCli } from "./run-guards";
+import { REPO_CHECK_FLAGS, REPO_CHECKS, runRepoChecksCli } from "./run-repo-checks";
+import { runUiGuardsCli, UI_GUARD_FLAGS, UI_GUARDS } from "./run-ui-guards";
+
+const SUBCOMMANDS = ["guards", "ui", "checks", "list"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
 
+const SUBCOMMAND_FLAGS: Record<Subcommand, readonly string[]> = {
+  guards: GUARD_FLAGS,
+  ui: UI_GUARD_FLAGS,
+  checks: REPO_CHECK_FLAGS,
+  list: [],
+};
+
 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));
+function printHelp(): void {
+  console.log("Usage: kumiko-guards [guards|ui|checks|list] [flags]");
+  console.log();
+  for (const sub of SUBCOMMANDS) {
+    const flags = SUBCOMMAND_FLAGS[sub];
+    console.log(`  ${sub}${flags.length > 0 ? ` [${flags.join("|")}]` : ""}`);
+  }
 }
 
 async function main(): Promise<void> {
   const subcommand = process.argv[2];
+  if (subcommand === "--help" || subcommand === "-h") {
+    printHelp();
+    process.exit(0);
+  }
   if (subcommand !== undefined && !isSubcommand(subcommand)) {
     console.error(
       `Unknown subcommand "${subcommand}". Valid subcommands: ${SUBCOMMANDS.join(", ")}`,
     );
     process.exit(1);
   }
+  const flags = process.argv.slice(3);
+
+  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));
+    return;
+  }
 
   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();
+  if (subcommand === undefined || subcommand === "guards") {
+    failed += runGuardsCli(subcommand === "guards" ? flags : []);
+  }
+  if (subcommand === undefined || subcommand === "ui") {
+    failed += runUiGuardsCli(subcommand === "ui" ? flags : []);
+  }
+  if (subcommand === undefined || subcommand === "checks") {
+    failed += await runRepoChecksCli(subcommand === "checks" ? flags : []);
+  }
 
   process.exit(failed > 0 ? 1 : 0);
 }