@cosmicdrift/kumiko-guards 0.326.0 → 0.327.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.326.0",
+  "version": "0.327.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.326.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.327.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

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

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type LockPackage = {
+  /** Key inside the lockfile's `packages` object; nested copies carry their parent path. */
+  readonly lockKey: string;
+  readonly name: string;
+  readonly version: string;
+  /** 1-based line of the key in bun.lock, 1 when it cannot be located. */
+  readonly line: number;
+};
+
+export type LockfileRead =
+  | { readonly ok: true; readonly packages: readonly LockPackage[] }
+  | { readonly ok: false; readonly reason: string };
+
+type ParsedBunLock = { readonly packages?: Record<string, unknown> };
+
+function isParsedBunLock(value: unknown): value is ParsedBunLock {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const packages = (value as Record<string, unknown>)["packages"];
+  return (
+    packages === undefined ||
+    (packages !== null && typeof packages === "object" && !Array.isArray(packages))
+  );
+}
+
+// bun.lock allows trailing commas (JSONC-lite) but no comments in practice —
+// stripping them is enough to make it JSON.parse-able.
+function stripTrailingCommas(jsonc: string): string {
+  return jsonc.replace(/,(\s*[}\]])/g, "$1");
+}
+
+function parseNameAndVersion(
+  resolvedNameAtVersion: string,
+): { readonly name: string; readonly version: string } | null {
+  const match = resolvedNameAtVersion.match(/^(@[^/]+\/[^@]+|[^@]+)@(.+)$/);
+  const [, name, version] = match ?? [];
+  return name !== undefined && version !== undefined ? { name, version } : null;
+}
+
+// packages are visited in file order, so each lookup resumes where the last one ended
+// (a per-entry slice+split of the whole file would be quadratic on real lockfiles).
+function createLineLocator(raw: string): (lockKey: string) => number {
+  let offset = Math.max(raw.indexOf('"packages"'), 0);
+  let line = 1;
+  for (let i = 0; i < offset; i++) if (raw.charCodeAt(i) === 10) line++;
+  return (lockKey) => {
+    const at = raw.indexOf(`${JSON.stringify(lockKey)}:`, offset);
+    if (at < 0) return 1;
+    for (let i = offset; i < at; i++) if (raw.charCodeAt(i) === 10) line++;
+    offset = at;
+    return line;
+  };
+}
+
+/**
+ * Every entry of `root`'s bun.lock `packages` graph as `{ lockKey, name, version }`.
+ * Name and version come from the entry's own resolved `name@version` value, not
+ * the key (keys are hoisting-conflict paths).
+ *
+ * `undefined` when there is no bun.lock. A lockfile that cannot be parsed, or
+ * holds an entry not readable as `name@version`, fails closed (`ok: false`)
+ * instead of silently shrinking the package list. A lockfile without a
+ * `packages` key yields an empty list.
+ */
+export function readLockfilePackages(root: string): LockfileRead | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(join(root, "bun.lock"), "utf-8");
+  } catch {
+    return undefined;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripTrailingCommas(raw));
+  } catch {
+    return { ok: false, reason: "not valid JSON" };
+  }
+  if (!isParsedBunLock(parsed)) return { ok: false, reason: "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` };
+    }
+    const nameAndVersion = parseNameAndVersion(entry[0]);
+    if (!nameAndVersion) {
+      return { ok: false, reason: `entry "${lockKey}" is not readable as name@version` };
+    }
+    packages.push({ lockKey, ...nameAndVersion, line: lineOf(lockKey) });
+  }
+  return { ok: true, packages };
+}

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.327.0",
+    "type": "improvement",
+    "title": "New repo check flags nested Kumiko package copies that drift from the top-level install",
+    "detail": "The new Single-Runtime-Instance check reads bun.lock and reports every Kumiko-scoped package resolved at more than one version unless it is marked dev/tooling/test; copies nested under a dev/tooling/test-marked package are ignored. The runtime-isolation guard also recognizes the \"prod\" kumiko.runtime marker.",
+    "migration": "A repo whose bun.lock resolves a runtime/client/prod-marked Kumiko package at more than one version now fails `kumiko-guards checks`; align the dependency ranges or pin one version via root overrides. dev/tooling/test-marked packages (kumiko-cli, kumiko-guards, kumiko-repo-manifest) are exempt, as are copies nested under such a package (e.g. the kumiko-guards > kumiko-cli subtree)."
+  },
   {
     "version": "0.324.0",
     "type": "fix",

package/src/check-runtime-isolation.ts

@@ -23,10 +23,11 @@
 //   5. Default                →  runtime
 //
 // Compat matrix: which runtime context may import which.
-//   runtime → runtime, client
+//   runtime → runtime, client, prod
 //   client  → client
-//   dev     → runtime, client, dev, tooling
-//   tooling → runtime, client, dev, tooling, test
+//   prod    → runtime, client, prod
+//   dev     → runtime, client, prod, dev, tooling
+//   tooling → runtime, client, prod, dev, tooling, test
 //   test    → everything
 //
 // Single-repo only (unlike infra/guards' check-runtime-isolation.ts, which

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

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+/**
+ * Single-Runtime-Instance Guard (kumiko-studio#229).
+ *
+ * A Kumiko runtime library resolved at two versions in one bun.lock (a nested
+ * copy under a feature package next to the top-level install) loads twice in
+ * one process: two registries, two module singletons. This flags every
+ * Kumiko-scoped package with more than one distinct resolved version unless
+ * its `kumiko.runtime` marker says dev/tooling/test (those never share a
+ * process with the app runtime). A package with no marker, or one not
+ * installed, is treated as runtime — fail closed.
+ *
+ * Copies nested under a dev/tooling/test-marked ancestor (e.g. kumiko-guards >
+ * kumiko-cli > kumiko-framework) belong to the dev-tool subtree, not the app
+ * process: they are ignored, and drift is judged on the remaining entries. An
+ * ancestor without marker does not protect its subtree.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type LockPackage, readLockfilePackages } from "./_lib/bun-lock-packages";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { ALL_RUNTIMES } from "./runtime-isolation-classify";
+
+const KUMIKO_PACKAGE_SCOPES: readonly string[] = ["@cosmicdrift/", "@cosmicdriftgamestudio/"];
+const WORKSPACE_VERSION_PREFIX = "workspace:";
+const EXEMPT_MARKERS: ReadonlySet<string> = new Set(["dev", "tooling", "test"]);
+
+function isKumikoPackage(name: string): boolean {
+  return KUMIKO_PACKAGE_SCOPES.some((scope) => name.startsWith(scope));
+}
+
+// Node-style lookup: the parent workspace hoists installs above the repo root.
+function readRuntimeMarker(rootAbsPath: string, packageName: string): string | undefined {
+  let dir = rootAbsPath;
+  for (;;) {
+    const pkgPath = join(dir, "node_modules", packageName, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const marker = (
+          JSON.parse(readFileSync(pkgPath, "utf8")) as { kumiko?: { runtime?: unknown } }
+        ).kumiko?.runtime; // @cast-boundary package-json
+        return typeof marker === "string" && ALL_RUNTIMES.has(marker) ? marker : undefined;
+      } catch {
+        return undefined;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+// A copy lives in the dev-tool subtree when any ancestor segment of its lockKey is dev/tooling/test-marked.
+function lockKeyAncestors(lockKey: string): string[] {
+  const names: string[] = [];
+  const segments = lockKey.split("/");
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i] ?? "";
+    if (segment.startsWith("@") && i + 1 < segments.length) {
+      names.push(`${segment}/${segments[i + 1]}`);
+      i++;
+    } else {
+      names.push(segment);
+    }
+  }
+  return names.slice(0, -1);
+}
+
+function groupByName(packages: readonly LockPackage[]): Map<string, LockPackage[]> {
+  const byName = new Map<string, LockPackage[]>();
+  for (const pkg of packages) {
+    if (pkg.version.startsWith(WORKSPACE_VERSION_PREFIX) || !isKumikoPackage(pkg.name)) continue;
+    const group = byName.get(pkg.name) ?? [];
+    group.push(pkg);
+    byName.set(pkg.name, group);
+  }
+  return byName;
+}
+
+export const check: RepoCheck = {
+  name: "Single-Runtime-Instance Guard",
+  hint:
+    "A runtime/client/prod Kumiko package resolves at more than one version in bun.lock, so two " +
+    "instances load in one process. Align the dependency ranges so one version satisfies all " +
+    'dependents, or pin it via root `overrides`. Packages marked kumiko.runtime "dev", "tooling" ' +
+    'or "test", and copies nested under such a package, are exempt.',
+  run(roots: readonly RepoRoot[]) {
+    const violations: { file: string; line: number; message: string }[] = [];
+    let matchedFiles = 0;
+    for (const root of roots) {
+      const markerCache = new Map<string, string | undefined>();
+      const markerOf = (name: string): string | undefined => {
+        if (!markerCache.has(name)) markerCache.set(name, readRuntimeMarker(root.absPath, name));
+        return markerCache.get(name);
+      };
+      const isUnderExemptAncestor = (lockKey: string): boolean =>
+        lockKeyAncestors(lockKey).some((ancestor) => EXEMPT_MARKERS.has(markerOf(ancestor) ?? ""));
+      const lock = readLockfilePackages(root.absPath);
+      if (lock === undefined) continue;
+      matchedFiles++;
+      if (!lock.ok) {
+        violations.push({
+          file: "bun.lock",
+          line: 1,
+          message: `bun.lock could not be parsed (${root.name}): ${lock.reason}`,
+        });
+        continue;
+      }
+      for (const [name, allEntries] of groupByName(lock.packages)) {
+        const marker = markerOf(name);
+        if (marker !== undefined && EXEMPT_MARKERS.has(marker)) continue;
+        const entries = allEntries.filter((e) => !isUnderExemptAncestor(e.lockKey));
+        if (new Set(entries.map((e) => e.version)).size < 2) continue;
+        const nested = entries.filter((e) => e.lockKey !== name);
+        const firstNestedLine = Math.min(
+          ...(nested.length > 0 ? nested : entries).map((e) => e.line),
+        );
+        const versions = entries.map((e) => `${e.version} (${e.lockKey})`).join(", ");
+        violations.push({
+          file: "bun.lock",
+          line: firstNestedLine,
+          message: `${name} [${marker ?? "no kumiko.runtime marker"}] resolves at ${new Set(entries.map((e) => e.version)).size} versions in ${root.name}: ${versions}`,
+        });
+      }
+    }
+    return { violations, matchedFiles, notApplicable: matchedFiles === 0 };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check], resolveRepoRoots()));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-feature-integration-tests.ts

@@ -120,7 +120,7 @@ function collectImportedFeatureIds(project: Project, roots: readonly RepoRoot[])
  * introduced by this change. Backfilling is its own scope per feature, not
  * a sweep.
  */
-const ALLOWLIST: ReadonlySet<string> = new Set(["step-dispatcher"]);
+const ALLOWLIST: ReadonlySet<string> = new Set<string>();
 
 export function computeOrphans(
   features: ReadonlyMap<string, string>,

package/src/run-repo-checks.ts

@@ -5,6 +5,7 @@ import { check as realProviderIsolation } from "./check-real-provider-isolation"
 // per-guard subprocess/project.
 import { check as runtimeIsolation } from "./check-runtime-isolation";
 import { check as secretLiterals } from "./check-secret-literals";
+import { check as singleRuntimeInstance } from "./check-single-runtime-instance";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
 import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
 import { check as primitivesDiscipline } from "./guard-primitives-discipline";
@@ -26,6 +27,7 @@ export const REPO_CHECKS = [
   runtimeIsolation,
   upgradeState,
   realProviderIsolation,
+  singleRuntimeInstance,
 ];
 
 // No flags today — the array stays so an unknown flag still fails loud

package/src/runtime-isolation-classify.ts

@@ -15,22 +15,24 @@ import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
 import type { ImportDeclaration, SourceFile } from "ts-morph";
 
-export type Runtime = "runtime" | "client" | "dev" | "tooling" | "test";
+export type Runtime = "runtime" | "client" | "prod" | "dev" | "tooling" | "test";
 
 export const ALL_RUNTIMES: ReadonlySet<string> = new Set([
   "runtime",
   "client",
+  "prod",
   "dev",
   "tooling",
   "test",
 ]);
 
 export const COMPAT: Record<Runtime, ReadonlySet<Runtime>> = {
-  runtime: new Set(["runtime", "client"]),
+  runtime: new Set(["runtime", "client", "prod"]),
   client: new Set(["client"]),
-  dev: new Set(["runtime", "client", "dev", "tooling"]),
-  tooling: new Set(["runtime", "client", "dev", "tooling", "test"]),
-  test: new Set(["runtime", "client", "dev", "tooling", "test"]),
+  prod: new Set(["runtime", "client", "prod"]),
+  dev: new Set(["runtime", "client", "prod", "dev", "tooling"]),
+  tooling: new Set(["runtime", "client", "prod", "dev", "tooling", "test"]),
+  test: new Set(["runtime", "client", "prod", "dev", "tooling", "test"]),
 };
 
 /**
@@ -296,7 +298,14 @@ export function findRuntimeIsolationViolations(
     seenOutside.add(fp);
     outsideRoot.push(fp);
   };
-  const stats: Record<Runtime, number> = { runtime: 0, client: 0, dev: 0, tooling: 0, test: 0 };
+  const stats: Record<Runtime, number> = {
+    runtime: 0,
+    client: 0,
+    prod: 0,
+    dev: 0,
+    tooling: 0,
+    test: 0,
+  };
   const withinRoot = (fp: string) => fp === repoRoot || fp.startsWith(`${repoRoot}/`);
 
   for (const sf of sourceFiles) {