@cosmicdrift/kumiko-guards 0.334.0 → 0.335.0

package/src/runtime-isolation-classify.ts

@@ -11,7 +11,7 @@
 // classification rules down so future edits trip a test, not a
 // production drift.
 
-import { existsSync, readFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, readSync } from "node:fs";
 import * as path from "node:path";
 import type { ImportDeclaration, SourceFile } from "ts-morph";
 
@@ -96,11 +96,54 @@ export function classifyByPath(repoRelativePath: string): Runtime | null {
  * their sources live under `packages/*\/src/`, not a repo-root `src/`. Kept
  * independent of the framework's own regex (cross-package import would be a
  * build-vs-lint layering violation) — if apps stop following this naming
- * convention, this drifts and needs a matching update.
+ * convention, this drifts and needs a matching update. Entries the app
+ * declares itself (`readDeclaredClientEntries`) count in addition, so a
+ * `./src/admin/index.tsx` entry is classified as browser code too.
  */
-export function isClientEntryPath(repoRelativePath: string): boolean {
+export function isClientEntryPath(
+  repoRelativePath: string,
+  declaredEntries: ReadonlySet<string> = new Set(),
+): boolean {
   const rel = repoRelativePath.replace(/\\/g, "/");
-  return /^src\/client(-[a-z][a-z0-9-]*)?\.tsx?$/.test(rel);
+  return declaredEntries.has(rel) || /^src\/client(-[a-z][a-z0-9-]*)?\.tsx?$/.test(rel);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parses `kumiko.clientEntry` / `kumiko.clientEntries[].sourceFile` out of a
+ * package.json value into repo-relative paths. Parsed locally instead of
+ * importing the build's resolver (layering: lint must not depend on
+ * server-runtime); anything malformed is ignored — `kumiko build` owns
+ * rejecting it.
+ */
+export function parseDeclaredClientEntries(packageJson: unknown): ReadonlySet<string> {
+  const entries = new Set<string>();
+  const kumiko = isRecord(packageJson) ? packageJson["kumiko"] : undefined;
+  if (!isRecord(kumiko)) return entries;
+  const sources: unknown[] = [kumiko["clientEntry"]];
+  const multi = kumiko["clientEntries"];
+  if (Array.isArray(multi)) {
+    for (const entry of multi) sources.push(isRecord(entry) ? entry["sourceFile"] : undefined);
+  }
+  for (const source of sources) {
+    if (typeof source === "string") {
+      entries.add(path.posix.normalize(source.replace(/\\/g, "/")));
+    }
+  }
+  return entries;
+}
+
+export function readDeclaredClientEntries(repoAbsPath: string): ReadonlySet<string> {
+  const file = path.join(repoAbsPath, "package.json");
+  if (!existsSync(file)) return new Set();
+  try {
+    return parseDeclaredClientEntries(JSON.parse(readFileSync(file, "utf8")));
+  } catch {
+    return new Set();
+  }
 }
 
 /**
@@ -122,6 +165,42 @@ export function isValueImport(decl: ImportDeclaration): boolean {
   return true;
 }
 
+export type ValueModuleEdge = {
+  readonly spec: string;
+  readonly target: SourceFile;
+  readonly line: number;
+};
+
+/**
+ * Every runtime-weighted edge out of a file: value imports plus value
+ * re-exports (`export { x } from`, `export * from`) — barrels are how most
+ * client entries reach runtime code. Shared by the direct-edge check and the
+ * reachability walk so both see the same edge set.
+ */
+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;
+    edges.push({
+      spec: decl.getModuleSpecifierValue(),
+      target,
+      line: decl.getStartLineNumber(),
+    });
+  }
+  for (const decl of sf.getExportDeclarations()) {
+    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() });
+  }
+  return edges;
+}
+
 /**
  * Map dist declaration files back to src. Project References make ts-morph
  * resolve imports to `.d.ts` under `dist/`; classification and the reachable
@@ -159,10 +238,7 @@ export function computeClientReachablePaths(
     if (fp.includes("/node_modules/") || fp.includes("/dist/")) continue;
     if (reached.has(fp)) continue;
     reached.add(fp);
-    for (const decl of sf.getImportDeclarations()) {
-      if (!isValueImport(decl)) continue;
-      const target = decl.getModuleSpecifierSourceFile();
-      if (!target) continue;
+    for (const { target } of valueModuleEdges(sf)) {
       const targetPath = toEffectivePath(target.getFilePath());
       if (targetPath.includes("/node_modules/") || targetPath.includes("/dist/")) continue;
       if (!reached.has(targetPath)) queue.push(target);
@@ -171,24 +247,69 @@ export function computeClientReachablePaths(
   return reached;
 }
 
-/**
- * Classify a file by its top-of-file `// @runtime <kind>` directive.
- * Reads the first 600 bytes only (cap blast radius on huge files).
- */
-export function classifyByDirective(filePath: string): Runtime | null {
-  let head: string;
+const DIRECTIVE_HEAD_BYTES = 600;
+const DIRECTIVE_HEAD_LINES = 8;
+
+export type HeadReader = (filePath: string) => string | null;
+
+// Reads only the file head, so classifying a large source file does not pull
+// it fully into memory.
+export function readFileHead(filePath: string): string | null {
+  let fd: number;
+  try {
+    fd = openSync(filePath, "r");
+  } catch {
+    return null;
+  }
   try {
-    head = readFileSync(filePath, "utf8").slice(0, 600);
+    const buffer = Buffer.alloc(DIRECTIVE_HEAD_BYTES);
+    const bytesRead = readSync(fd, buffer, 0, DIRECTIVE_HEAD_BYTES, 0);
+    return buffer.toString("utf8", 0, bytesRead);
   } catch {
     return null;
+  } finally {
+    closeSync(fd);
   }
-  for (const line of head.split("\n").slice(0, 8)) {
+}
+
+/**
+ * Classify a file by its top-of-file `// @runtime <kind>` directive.
+ * Reads the first 600 bytes only (cap blast radius on huge files).
+ */
+export function classifyByDirective(
+  filePath: string,
+  readHead: HeadReader = readFileHead,
+): Runtime | null {
+  const head = readHead(filePath);
+  if (head === null) return null;
+  for (const line of head.split("\n").slice(0, DIRECTIVE_HEAD_LINES)) {
     const m = line.match(/\/\/\s*@runtime\s+(\w+)/);
     if (m && ALL_RUNTIMES.has(m[1] ?? "")) return m[1] as Runtime;
   }
   return null;
 }
 
+export type DirectiveClassifier = (filePath: string) => Runtime | null;
+
+/**
+ * Per-run memo of `classifyByDirective`: the guard classifies each file in
+ * several passes (client reachability, then violations), and each pass would
+ * otherwise re-read the same head. Created per run, not module-global, so
+ * tests stay isolated.
+ */
+export function createDirectiveClassifier(
+  readHead: HeadReader = readFileHead,
+): DirectiveClassifier {
+  const cache = new Map<string, Runtime | null>();
+  return (filePath) => {
+    const cached = cache.get(filePath);
+    if (cached !== undefined) return cached;
+    const result = classifyByDirective(filePath, readHead);
+    cache.set(filePath, result);
+    return result;
+  };
+}
+
 /**
  * Walk upward from `filePath` looking for the nearest package.json that
  * carries a `kumiko.runtime` marker. Stops at `repoRoot`. Caches per
@@ -201,7 +322,8 @@ export function findWorkspaceRuntime(
   cache: Map<string, Runtime | null>,
 ): Runtime | null {
   let dir = path.dirname(filePath);
-  while (dir.startsWith(repoRoot) && dir !== repoRoot) {
+  // Includes repoRoot itself: a single-package consumer repo keeps its marker there.
+  while (dir.startsWith(repoRoot)) {
     const r = readWorkspaceRuntime(dir, cache);
     if (r) return r;
     // Stop at the first package.json — don't fall through to a parent
@@ -212,6 +334,7 @@ export function findWorkspaceRuntime(
     } catch {
       // No package.json here — keep climbing.
     }
+    if (dir === repoRoot) break;
     dir = path.dirname(dir);
   }
   return null;
@@ -250,12 +373,13 @@ export function classify(
   repoRoot: string,
   workspaceCache: Map<string, Runtime | null>,
   clientReachable?: ReadonlySet<string>,
+  directiveOf: DirectiveClassifier = (file) => classifyByDirective(file),
 ): Runtime {
   const effectivePath = toEffectivePath(filePath);
 
   const rel = path.relative(repoRoot, effectivePath);
   return (
-    classifyByDirective(effectivePath) ??
+    directiveOf(effectivePath) ??
     classifyByPath(rel) ??
     findWorkspaceRuntime(effectivePath, repoRoot, workspaceCache) ??
     (clientReachable?.has(effectivePath) ? "client" : undefined) ??
@@ -284,6 +408,7 @@ export function findRuntimeIsolationViolations(
   repoRoot: string,
   workspaceCache: Map<string, Runtime | null>,
   clientReachable: ReadonlySet<string> = new Set(),
+  directiveOf: DirectiveClassifier = createDirectiveClassifier(),
 ): {
   readonly violations: readonly Violation[];
   readonly stats: Record<Runtime, number>;
@@ -315,13 +440,10 @@ export function findRuntimeIsolationViolations(
       noteOutside(fp);
       continue;
     }
-    const fileRt = classify(fp, repoRoot, workspaceCache, clientReachable);
+    const fileRt = classify(fp, repoRoot, workspaceCache, clientReachable, directiveOf);
     stats[fileRt]++;
 
-    for (const decl of sf.getImportDeclarations()) {
-      if (!isValueImport(decl)) continue;
-      const target = decl.getModuleSpecifierSourceFile();
-      if (!target) continue;
+    for (const { spec, target, line } of valueModuleEdges(sf)) {
       const targetPath = target.getFilePath();
       if (targetPath.includes("/node_modules/")) continue;
       if (!withinRoot(targetPath)) {
@@ -333,9 +455,9 @@ export function findRuntimeIsolationViolations(
       if (!COMPAT[fileRt].has(targetRt)) {
         violations.push({
           file: fp,
-          line: decl.getStartLineNumber(),
+          line,
           fileRuntime: fileRt,
-          importedSpec: decl.getModuleSpecifierValue(),
+          importedSpec: spec,
           importedFile: targetPath,
           importedRuntime: targetRt,
         });