@cosmicdrift/kumiko-guards 0.369.0 → 0.370.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.369.0",
+  "version": "0.370.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.369.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.370.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "import-extensions guard reports relative .js and .jsx specifiers",
+    "detail": "The import-extensions guard fails on a relative specifier that ends in .js or .jsx in a .ts or .tsx file (import, export from, import type and import()). Declaration files and fixtures are skipped. The message points to the import-extensions codemod. There is no baseline."
+  },
+  {
+    "version": "0.370.0",
+    "type": "improvement",
+    "title": "Runtime-isolation guard resolves imports through the TypeScript resolver",
+    "detail": "The runtime-isolation guard resolves import and re-export targets with ts.resolveModuleName, so path aliases and package exports are followed, and classifies e2e directories as test code. resolveImportTargetPath is exported for other guards."
+  },
   {
     "version": "0.366.0",
     "type": "improvement",

package/src/guard-import-extensions.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+/**
+ * Guard: relative imports in TypeScript sources name the source file (`./foo.ts`),
+ * not the emitted one (`./foo.js`).
+ *
+ * The tsconfig sets `allowImportingTsExtensions` and `rewriteRelativeImportExtensions`, so tsc
+ * writes `.js` into the published dist. A `.js` specifier in a source file works under bundler
+ * resolution, but it makes the source tree read two ways and hides missing files from editors
+ * that jump to the importee.
+ *
+ * Usage:
+ *   bun guards/guard-import-extensions.ts
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+
+const SCAN: ScanSpec = {
+  scope: "source+tests",
+  extensions: ["ts", "tsx"],
+};
+
+const EXCLUDE = /(\.d\.ts$|\/fixtures\/)/;
+const RELATIVE_JS_SPECIFIER = /^\.{1,2}\/.*\.jsx?$/;
+
+interface Finding {
+  readonly line: number;
+  readonly specifier: string;
+}
+
+function relativeJsSpecifier(node: Node | undefined): string | undefined {
+  const literal = node?.asKind(SyntaxKind.StringLiteral);
+  const value = literal?.getLiteralValue();
+  return value !== undefined && RELATIVE_JS_SPECIFIER.test(value) ? value : undefined;
+}
+
+function findJsSpecifiers(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  const add = (node: Node | undefined): void => {
+    const specifier = relativeJsSpecifier(node);
+    if (node !== undefined && specifier !== undefined) {
+      findings.push({ line: node.getStartLineNumber(), specifier });
+    }
+  };
+  for (const declaration of [...sf.getImportDeclarations(), ...sf.getExportDeclarations()]) {
+    add(declaration.getModuleSpecifier());
+  }
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (call.getExpression().getKind() === SyntaxKind.ImportKeyword) add(call.getArguments()[0]);
+  }
+  return findings;
+}
+
+export const guard: AstGuard = {
+  name: "Import-Extensions Guard",
+  scan: SCAN,
+  hint:
+    "Relative imports name the source file: `./foo.js` -> `./foo.ts`, `./Comp.jsx` -> `./Comp.tsx`. " +
+    "Run the import-extensions codemod: `bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/import-extensions.ts . --write`. " +
+    "The tsconfig needs `allowImportingTsExtensions` (and `rewriteRelativeImportExtensions` when tsc emits).",
+  run(files) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      if (EXCLUDE.test(file)) continue;
+      for (const { line, specifier } of findJsSpecifiers(sf)) {
+        violations.push({
+          file,
+          line,
+          message: `relative import "${specifier}" ends in .js/.jsx; use the .ts/.tsx source (codemod: import-extensions)`,
+        });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-public-exports-changelog.ts

@@ -606,6 +606,21 @@ export function isCoveredByPendingChangeset(
   return texts.length > 0 && everyNameMentioned(texts, droppedNames);
 }
 
+// A removed feature folder has no changes.json the release fold could write to,
+// so its dropped exports are named by the breaking block of whichever feature
+// took them over; every name must still be mentioned by one block.
+export function pendingFeaturesFor(
+  cwd: string,
+  pkg: PackageName,
+  key: string,
+  pending: PendingBreakingChanges,
+): readonly string[] {
+  const feature = changesetFeatureFor(pkg, key);
+  if (pkg === "framework") return [feature];
+  if (existsSync(join(cwd, "packages/bundled-features/src", feature))) return [feature];
+  return [...pending.keys()];
+}
+
 // ── Write baseline ────────────────────────────────────────────────────────
 
 // An absent, unreadable or format-drifted old baseline means "nothing frozen
@@ -635,11 +650,10 @@ function uncoveredDrops(
   const uncovered: UncoveredFinding[] = [];
   for (const m of missing) {
     if (!isPackageName(m.pkg)) continue;
+    const coveringFeatures = pendingFeaturesFor(cwd, m.pkg, m.key, pendingBreakingChanges);
     if (
-      isCoveredByPendingChangeset(
-        pendingBreakingChanges,
-        changesetFeatureFor(m.pkg, m.key),
-        m.names,
+      coveringFeatures.some((feature) =>
+        isCoveredByPendingChangeset(pendingBreakingChanges, feature, m.names),
       )
     ) {
       continue;

package/src/index.ts

@@ -34,3 +34,4 @@ export { writeSecurityBaselines } from "./_lib/security-baseline-cli";
 export { GUARD_FLAGS, GUARDS, runGuardsCli } from "./run-guards";
 export { REPO_CHECK_FLAGS, REPO_CHECKS, runRepoChecksCli } from "./run-repo-checks";
 export { runUiGuardsCli, UI_GUARD_FLAGS, UI_GUARDS } from "./run-ui-guards";
+export { resolveImportTargetPath } from "./runtime-isolation-classify";

package/src/run-guards.ts

@@ -38,6 +38,7 @@ import { guard as htmlEscape } from "./guard-html-escape";
 import { guard as i18nKeys } from "./guard-i18n-keys";
 import { guard as i18nLocaleMount } from "./guard-i18n-locale-mount";
 import { guard as i18nLocaleTerminology } from "./guard-i18n-locale-terminology";
+import { guard as importExtensions } from "./guard-import-extensions";
 import { guard as libTestCoverage } from "./guard-lib-test-coverage";
 import { guard as loadallEvents } from "./guard-loadall-events";
 import { guard as noDateApi } from "./guard-no-date-api";
@@ -73,6 +74,7 @@ export const GUARDS = [
   unsafeJsonParse,
   silentSkip,
   htmlEscape,
+  importExtensions,
   crossFeatureImports,
   noDateApi,
   noTemporalPolyfillImport,

package/src/runtime-isolation-classify.ts

@@ -13,7 +13,13 @@
 
 import { closeSync, existsSync, openSync, readFileSync, readSync } from "node:fs";
 import * as path from "node:path";
-import type { ImportDeclaration, SourceFile } from "ts-morph";
+import {
+  type ExportDeclaration,
+  type ImportDeclaration,
+  type Project,
+  type SourceFile,
+  ts,
+} from "ts-morph";
 
 const RUNTIME_KINDS = ["runtime", "client", "prod", "dev", "tooling", "test"] as const;
 
@@ -34,26 +40,24 @@ export const COMPAT: Record<Runtime, ReadonlySet<Runtime>> = {
   test: new Set(["runtime", "client", "prod", "dev", "tooling", "test"]),
 };
 
-/**
- * Classify a file by its path relative to the repo root. Returns null
- * if no path-pattern matched (caller falls back to workspace / default).
- *
- * Pure function — accepts a repo-relative path string, no I/O.
- */
-export function classifyByPath(repoRelativePath: string): Runtime | null {
-  const rel = repoRelativePath.replace(/\\/g, "/");
-  if (/\/(__tests__|testing)\//.test(rel)) return "test";
-  if (/\/testing\.tsx?$/.test(rel)) return "test";
-  if (/\.(test|integration|e2e|spec)\.[tj]sx?$/.test(rel)) return "test";
-  if (/(?:^|\/)scripts\//.test(rel)) return "tooling";
-  if (/(?:^|\/)bin\//.test(rel)) return "tooling";
-  if (/\/drizzle\/[^/]+\.ts$/.test(rel)) return "tooling";
-  if (/\/drizzle\.config\.[tj]s$/.test(rel)) return "tooling";
+// First match wins, so the test rules stay ahead of the tooling and client carve-outs.
+const PATH_RULES: readonly (readonly [RegExp, Runtime])[] = [
+  [/\/(__tests__|testing)\//, "test"],
+  [/\/testing\.tsx?$/, "test"],
+  [/\.(test|integration|e2e|spec)\.[tj]sx?$/, "test"],
+  // Playwright suites live in e2e/ at the repo root, next to a package or a
+  // sample and import kumiko-testing/e2e; without this rule they read as
+  // runtime code importing the test tier. Deliberately not any nested e2e/.
+  [/^(?:e2e|packages\/[^/]+\/e2e|samples\/(?:.+\/)?e2e)\//, "test"],
+  [/(?:^|\/)scripts\//, "tooling"],
+  [/(?:^|\/)bin\//, "tooling"],
+  [/\/drizzle\/[^/]+\.ts$/, "tooling"],
+  [/\/drizzle\.config\.[tj]s$/, "tooling"],
 
   // Shared UI types are used by both client and runtime. In the kumiko isolation
   // model, "client" is the most permissive production category that "runtime"
   // can also import.
-  if (/(?:^|\/)ui-types\//.test(rel)) return "client";
+  [/(?:^|\/)ui-types\//, "client"],
 
   // Same reasoning, two more shapes: a `web.ts`/`web/` subpath is the
   // established convention (locale-de, locale-es, bundled-features) for the
@@ -68,8 +72,9 @@ export function classifyByPath(repoRelativePath: string): Runtime | null {
   // `utils`/`errors` are common enough directory names elsewhere that a
   // repo-wide match risks misclassifying an unrelated server-only folder in
   // some other package.
-  if (/(?:^|\/)web\//.test(rel) || /\/web\.tsx?$/.test(rel)) return "client";
-  if (/^packages\/framework\/src\/(?:time|utils|engine\/types|errors)\//.test(rel)) return "client";
+  [/(?:^|\/)web\//, "client"],
+  [/\/web\.tsx?$/, "client"],
+  [/^packages\/framework\/src\/(?:time|utils|engine\/types|errors)\//, "client"],
 
   // More single-file carve-outs, same "package marker is coarser than the
   // file" shape, verified case by case rather than by a directory
@@ -77,11 +82,23 @@ export function classifyByPath(repoRelativePath: string): Runtime | null {
   //  - locale-{de,es}/src/strings.ts: pure string-constant data (zero
   //    imports), re-exported by the already-client `web.ts` sibling in the
   //    same package but shadowed by the package's own `"runtime"` marker.
-  if (/^packages\/locale-(?:de|es)\/src\/strings\.ts$/.test(rel)) return "client";
+  [/^packages\/locale-(?:de|es)\/src\/strings\.ts$/, "client"],
   //  - dev-server/src/env-schema.ts: a zod-only schema, no dev-server-
   //    internal imports — safe to carve out on its own.
-  if (/^packages\/dev-server\/src\/env-schema\.ts$/.test(rel)) return "client";
+  [/^packages\/dev-server\/src\/env-schema\.ts$/, "client"],
+];
 
+/**
+ * Classify a file by its path relative to the repo root. Returns null
+ * if no path-pattern matched (caller falls back to workspace / default).
+ *
+ * Pure function — accepts a repo-relative path string, no I/O.
+ */
+export function classifyByPath(repoRelativePath: string): Runtime | null {
+  const rel = repoRelativePath.replace(/\\/g, "/");
+  for (const [pattern, runtime] of PATH_RULES) {
+    if (pattern.test(rel)) return runtime;
+  }
   return null;
 }
 
@@ -166,7 +183,7 @@ export function isValueImport(decl: ImportDeclaration): boolean {
 
 export type ValueModuleEdge = {
   readonly spec: string;
-  readonly target: SourceFile;
+  readonly targetPath: string;
   readonly line: number;
 };
 
@@ -180,11 +197,11 @@ export function valueModuleEdges(sf: SourceFile): ValueModuleEdge[] {
   const edges: ValueModuleEdge[] = [];
   for (const decl of sf.getImportDeclarations()) {
     if (!isValueImport(decl)) continue;
-    const target = decl.getModuleSpecifierSourceFile();
-    if (!target) continue;
+    const targetPath = resolveImportTargetPath(decl);
+    if (!targetPath) continue;
     edges.push({
       spec: decl.getModuleSpecifierValue(),
-      target,
+      targetPath,
       line: decl.getStartLineNumber(),
     });
   }
@@ -192,14 +209,62 @@ export function valueModuleEdges(sf: SourceFile): ValueModuleEdge[] {
     if (decl.isTypeOnly()) continue;
     const named = decl.getNamedExports();
     if (named.length > 0 && named.every((n) => n.isTypeOnly())) continue;
-    const target = decl.getModuleSpecifierSourceFile();
     const spec = decl.getModuleSpecifierValue();
-    if (!target || spec === undefined) continue;
-    edges.push({ spec, target, line: decl.getStartLineNumber() });
+    const targetPath = resolveImportTargetPath(decl);
+    if (!targetPath || spec === undefined) continue;
+    edges.push({ spec, targetPath, line: decl.getStartLineNumber() });
   }
   return edges;
 }
 
+const moduleResolutionCaches = new WeakMap<Project, ts.ModuleResolutionCache>();
+const javaScriptExtensions: ReadonlySet<string> = new Set([
+  ts.Extension.Js,
+  ts.Extension.Jsx,
+  ts.Extension.Mjs,
+  ts.Extension.Cjs,
+]);
+
+/**
+ * Resolve an import or re-export to its target file path without touching the
+ * type checker. ts-morph's `getModuleSpecifierSourceFile()` goes through
+ * `getSymbol()`, which creates the full program and binds every file: on a
+ * multi-repo scan that doubled the RSS past the CI runner's memory. Plain
+ * `ts.resolveModuleName` yields the same real paths for workspace files. JS
+ * targets are dropped unless `allowJs` is on, because the program never
+ * contained them either.
+ */
+export function resolveImportTargetPath(
+  decl: ImportDeclaration | ExportDeclaration,
+): string | undefined {
+  const spec = decl.getModuleSpecifierValue();
+  if (spec === undefined) return undefined;
+  const project = decl.getProject();
+  const options = project.getCompilerOptions();
+  const host = project.getModuleResolutionHost();
+  let cache = moduleResolutionCaches.get(project);
+  if (!cache) {
+    cache = ts.createModuleResolutionCache(
+      host.getCurrentDirectory?.() ?? process.cwd(),
+      ts.sys.useCaseSensitiveFileNames
+        ? (fileName) => fileName
+        : (fileName) => fileName.toLowerCase(),
+      options,
+    );
+    moduleResolutionCaches.set(project, cache);
+  }
+  const resolved = ts.resolveModuleName(
+    spec,
+    decl.getSourceFile().getFilePath(),
+    options,
+    host,
+    cache,
+  ).resolvedModule;
+  if (!resolved) return undefined;
+  if (!options.allowJs && javaScriptExtensions.has(resolved.extension)) return undefined;
+  return resolved.resolvedFileName;
+}
+
 /**
  * Map dist declaration files back to src. Project References make ts-morph
  * resolve imports to `.d.ts` under `dist/`; classification and the reachable
@@ -237,10 +302,12 @@ export function computeClientReachablePaths(
     if (fp.includes("/node_modules/") || fp.includes("/dist/")) continue;
     if (reached.has(fp)) continue;
     reached.add(fp);
-    for (const { target } of valueModuleEdges(sf)) {
-      const targetPath = toEffectivePath(target.getFilePath());
+    const project = sf.getProject();
+    for (const edge of valueModuleEdges(sf)) {
+      const targetPath = toEffectivePath(edge.targetPath);
       if (targetPath.includes("/node_modules/") || targetPath.includes("/dist/")) continue;
-      if (!reached.has(targetPath)) queue.push(target);
+      if (reached.has(targetPath)) continue;
+      queue.push(project.getSourceFile(targetPath) ?? project.addSourceFileAtPath(targetPath));
     }
   }
   return reached;
@@ -446,8 +513,7 @@ export function findRuntimeIsolationViolations(
     const fileRt = classify(fp, repoRoot, workspaceCache, clientReachable, directiveOf);
     stats[fileRt]++;
 
-    for (const { spec, target, line } of valueModuleEdges(sf)) {
-      const targetPath = target.getFilePath();
+    for (const { spec, targetPath, line } of valueModuleEdges(sf)) {
       if (targetPath.includes("/node_modules/")) continue;
       if (!withinRoot(targetPath)) {
         noteOutside(targetPath);