@cosmicdrift/kumiko-guards 0.351.0 → 0.352.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.351.0",
+  "version": "0.352.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.351.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.352.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "New No-Temporal-Polyfill-Import guard reports direct temporal-polyfill value imports outside kumiko-types",
+    "detail": "Scans source and test files (ts, tsx). Flags named, default, namespace and side-effect imports, re-exports, import() and require of \"temporal-polyfill\" or its subpaths, and prints the replacement import from @cosmicdrift/kumiko-types/temporal. Type-only imports and triple-slash type references pass."
+  },
+  {
+    "version": "0.352.0",
+    "type": "breaking",
+    "title": "upgrade-state guard fails on open manual upgrade steps",
+    "detail": "Every entry in the marker's pendingManual list now produces a guard violation until it is resolved.",
+    "migration": "Run `kumiko-upgrade --resolve <id> --reason \"<what you did>\"` for each open step once you applied it, or add `--not-applicable` when it does not concern your repo. The guard passes when no manual step is left open."
+  },
   {
     "version": "0.351.0",
     "type": "fix",

package/src/guard-no-temporal-polyfill-import.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+/**
+ * Guard: finds value imports from `temporal-polyfill` outside kumiko-types.
+ *
+ * Since 0.351.0 `@cosmicdrift/kumiko-types/temporal` is the single source of
+ * the Temporal API: native `globalThis.Temporal` wins, the polyfill is only a
+ * fallback. A module that imports `Temporal` straight from `temporal-polyfill`
+ * gets the polyfill classes while framework-made values are native ones, so
+ * `instanceof Temporal.Instant` and `z.instanceof(Temporal.Instant)` reject
+ * them ("expected Instant, received Instant"). Side-effect imports such as
+ * `temporal-polyfill/global` are flagged too: they can put a second
+ * implementation on the global.
+ *
+ * Not flagged: `import type` (erased at runtime) and the
+ * `/// <reference types="temporal-polyfill/global" />` directive.
+ *
+ * Usage:
+ *   bun guards/guard-no-temporal-polyfill-import.ts
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import { type ImportDeclaration, Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  findRepoRootFor,
+  type GuardViolation,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+
+const SCAN: ScanSpec = {
+  scope: "source+tests",
+  extensions: ["ts", "tsx"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+
+const REPLACEMENT_IMPORT = 'import { Temporal } from "@cosmicdrift/kumiko-types/temporal";';
+
+// The one module that resolves native-vs-polyfill; repo-scoped so an app file
+// at the same relative path does not inherit the exception.
+const TEMPORAL_SOURCE = { repo: "kumiko-framework", relPath: "packages/types/src/temporal.ts" };
+
+export function isTemporalSingleSource(repoName: string | undefined, relPath: string): boolean {
+  return repoName === TEMPORAL_SOURCE.repo && relPath === TEMPORAL_SOURCE.relPath;
+}
+
+function isPolyfillSpecifier(specifier: string): boolean {
+  return specifier === "temporal-polyfill" || specifier.startsWith("temporal-polyfill/");
+}
+
+function isTypeOnlyImport(decl: ImportDeclaration): boolean {
+  if (decl.isTypeOnly()) return true;
+  const named = decl.getNamedImports();
+  const hasValueBinding =
+    decl.getDefaultImport() !== undefined || decl.getNamespaceImport() !== undefined;
+  return !hasValueBinding && named.length > 0 && named.every((n) => n.isTypeOnly());
+}
+
+type PolyfillImport = { readonly line: number; readonly specifier: string };
+
+function findPolyfillValueImports(sf: SourceFile): PolyfillImport[] {
+  const found: PolyfillImport[] = [];
+  for (const decl of sf.getImportDeclarations()) {
+    const specifier = decl.getModuleSpecifierValue();
+    if (isPolyfillSpecifier(specifier) && !isTypeOnlyImport(decl)) {
+      found.push({ line: decl.getStartLineNumber(), specifier });
+    }
+  }
+  for (const decl of sf.getExportDeclarations()) {
+    const specifier = decl.getModuleSpecifierValue();
+    if (specifier !== undefined && isPolyfillSpecifier(specifier) && !decl.isTypeOnly()) {
+      found.push({ line: decl.getStartLineNumber(), specifier });
+    }
+  }
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    const isRequireCall = Node.isIdentifier(callee) && callee.getText() === "require";
+    const isDynamicImport = callee.getKind() === SyntaxKind.ImportKeyword;
+    if (!isRequireCall && !isDynamicImport) continue;
+    const arg = call.getArguments()[0];
+    if (arg && Node.isStringLiteral(arg) && isPolyfillSpecifier(arg.getLiteralValue())) {
+      found.push({ line: call.getStartLineNumber(), specifier: arg.getLiteralValue() });
+    }
+  }
+  return found;
+}
+
+export const guard: AstGuard = {
+  name: "No-Temporal-Polyfill-Import Guard",
+  scan: SCAN,
+  hint: `Import Temporal from the kumiko single source instead: ${REPLACEMENT_IMPORT} A direct "temporal-polyfill" import creates a second Temporal implementation, so instanceof and z.instanceof(Temporal.Instant) reject framework-made values.`,
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
+    const violations: GuardViolation[] = [];
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      const rel = relFromRepoRoot(file, roots);
+      if (isTemporalSingleSource(findRepoRootFor(file, roots)?.name, rel)) continue;
+      for (const hit of findPolyfillValueImports(sf)) {
+        violations.push({
+          file: rel,
+          line: hit.line,
+          message: `[${hit.specifier}] direct temporal-polyfill import — use ${REPLACEMENT_IMPORT}`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-restricted-symbols.ts

@@ -36,11 +36,18 @@ const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 const RESTRICTED_SYMBOLS = new Set([
   "getUnscopedAggregateStreamMaxVersion",
   "getUnscopedAggregateStreamTenant",
+  // Appends any event type without the feature-ownership check of ctx.appendEvent and without
+  // an audited unsafeRaw escape hatch, so new callers need an explicit allowlist entry.
+  "appendEventInTenantDb",
+  "getStreamVersionInTenantDb",
 ]);
 
 const ALLOWLIST = [
   /^packages\/framework\/src\/event-store\/event-store\.ts$/,
   /^packages\/framework\/src\/event-store\/index\.ts$/,
+  /^packages\/framework\/src\/event-store\/tenant-db-append\.ts$/,
+  /^packages\/bundled-features\/src\/cap-counter\/cap-reservation\.ts$/,
+  /^packages\/bundled-features\/src\/user-data-rights-defaults\/hooks\/delivery-attempt\.userdata-hook\.ts$/,
   /^packages\/bundled-features\/src\/tenant\/seeding\.ts$/,
   /^packages\/bundled-features\/src\/tier-engine\/feature\.ts$/,
 ];
@@ -112,7 +119,7 @@ function findRestrictedSymbolReferences(sf: SourceFile): Violation[] {
 export const guard: AstGuard = {
   name: "Restricted-Symbols Guard",
   scan: SCAN,
-  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
+  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.appendEvent — only framework-internal coordination code may use them. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
   run(files, roots = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 
@@ -125,7 +132,7 @@ export const guard: AstGuard = {
         violations.push({
           file: rel,
           line: v.line,
-          message: `[${v.symbol}] unscoped stream-primitive referenced outside allowlist`,
+          message: `[${v.symbol}] restricted event-store primitive referenced outside allowlist`,
         });
       }
     }

package/src/guard-upgrade-state.ts

@@ -7,7 +7,9 @@
  * `@cosmicdrift/kumiko-cli` or `@cosmicdrift/kumiko-dev-server`) and records
  * the version it was applied at. This guard re-runs `kumiko-upgrade --from <marker version> --json` and
  * fails if any changelog entries are still pending — meaning the marker is
- * stale and the repo hasn't run the upgrade since.
+ * stale and the repo hasn't run the upgrade since. It also fails once per open
+ * `pendingManual` step the marker still carries (breaking changes without a
+ * codemod that nobody resolved yet).
  *
  * Single-repo only, like `guard-upgrade-state.ts` in infra/guards but
  * without that package's multi-repo `resolveRepoRoots()` scan loop — this
@@ -31,7 +33,16 @@ import {
 const MARKER_REL = ".kumiko/upgrade-state.json";
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 
-type UpgradeMarker = { readonly version: string };
+type PendingManualStep = {
+  readonly id: string;
+  readonly version: string;
+  readonly title: string;
+};
+
+type UpgradeMarker = {
+  readonly version: string;
+  readonly pendingManual: readonly PendingManualStep[];
+};
 
 type PendingEntry = {
   readonly version: string;
@@ -71,6 +82,25 @@ export function isUpgradeJson(value: unknown): value is UpgradeJson {
   );
 }
 
+export function isPendingManualStep(value: unknown): value is PendingManualStep {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v["id"] === "string" &&
+    v["id"].length > 0 &&
+    typeof v["version"] === "string" &&
+    typeof v["title"] === "string"
+  );
+}
+
+function readPendingManual(parsed: unknown): readonly PendingManualStep[] {
+  const raw =
+    parsed && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>)["pendingManual"]
+      : undefined;
+  return Array.isArray(raw) ? raw.filter(isPendingManualStep) : [];
+}
+
 export function readMarker(root: string): UpgradeMarker | { error: string } {
   const markerPath = join(root, MARKER_REL);
   if (!existsSync(markerPath)) {
@@ -93,7 +123,7 @@ export function readMarker(root: string): UpgradeMarker | { error: string } {
       error: `${MARKER_REL} is missing a valid "version" field (expected semver x.y.z[-pre][+build]) — broken marker file`,
     };
   }
-  return { version };
+  return { version, pendingManual: readPendingManual(parsed) };
 }
 
 /** Pending changelog entries turned into guard violations — pure, testable without a subprocess. */
@@ -109,6 +139,20 @@ export function pendingViolations(json: UpgradeJson, markerVersion: string): Gua
   }));
 }
 
+/** Open manual upgrade steps from the marker, one violation each. */
+export function pendingManualViolations(
+  pendingManual: readonly PendingManualStep[],
+): GuardViolation[] {
+  return pendingManual.map((step) => ({
+    file: MARKER_REL,
+    line: 1,
+    message:
+      `Open manual upgrade step ${step.id} (${step.version}): ${step.title}. ` +
+      `Resolve it with \`kumiko-upgrade --resolve ${step.id} --reason "<what you did>"\` ` +
+      `or mark it with \`--not-applicable\`.`,
+  }));
+}
+
 export function resolveKumikoUpgradeBin(
   cwd: string,
   pathEnv: string | undefined = process.env["PATH"],
@@ -204,16 +248,17 @@ export const check: RepoCheck = {
         notApplicable: false,
       };
     }
+    const manualViolations = pendingManualViolations(marker.pendingManual);
     const result = await runKumikoUpgrade(marker.version, rootAbsPath);
     if (!result.ok) {
       return {
-        violations: [{ file: MARKER_REL, line: 1, message: result.error }],
+        violations: [{ file: MARKER_REL, line: 1, message: result.error }, ...manualViolations],
         matchedFiles: 1,
         notApplicable: false,
       };
     }
     return {
-      violations: pendingViolations(result.json, marker.version),
+      violations: [...pendingViolations(result.json, marker.version), ...manualViolations],
       matchedFiles: 1,
       notApplicable: false,
     };

package/src/run-guards.ts

@@ -42,6 +42,7 @@ import { guard as loadallEvents } from "./guard-loadall-events";
 import { guard as noDateApi } from "./guard-no-date-api";
 import { guard as noDirectFs } from "./guard-no-direct-fs";
 import { guard as noLogicInViews } from "./guard-no-logic-in-views";
+import { guard as noTemporalPolyfillImport } from "./guard-no-temporal-polyfill-import";
 import { guard as openToAllReason } from "./guard-open-to-all-reason";
 import { guard as piiAnnotations } from "./guard-pii-annotations";
 import { guard as preEsPatterns } from "./guard-pre-es-patterns";
@@ -72,6 +73,7 @@ export const GUARDS = [
   htmlEscape,
   crossFeatureImports,
   noDateApi,
+  noTemporalPolyfillImport,
   restrictedSymbols,
   fakeTests,
   noLogicInViews,