@cosmicdrift/kumiko-guards 0.334.0 → 0.336.0

package/src/guard-section-fields-raw.ts

@@ -11,7 +11,9 @@
  * generator in #3042). `sectionFieldSpecs` (engine/screen-helpers.ts) is the
  * one reader that unions both sources.
  *
- * Flagged: for-of, spread and array reads over `<…section…>.fields`.
+ * Flagged: for-of, spread, array reads, indexing, call arguments and
+ * destructuring over the `fields` of a section (by name or by a `groups`
+ * property on its type), also behind `!`, parentheses, `as` and `??`.
  * Known gap: `section.fields.length` is not flagged — the fields-XOR-groups
  * validator itself needs it, and an emptiness check is not the silent-
  * iteration bug.
@@ -35,7 +37,13 @@
  *   bun guards/guard-section-fields-raw.ts --no-baseline    # skip comparison
  */
 import * as path from "node:path";
-import { type Node, type PropertyAccessExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type Node,
+  type PropertyAccessExpression,
+  type SourceFile,
+  SyntaxKind,
+  type VariableDeclaration,
+} from "ts-morph";
 import {
   type AstGuard,
   baselineRatchet,
@@ -68,9 +76,10 @@ const SCAN: ScanSpec = {
 const EXCLUDE = /(__tests__|\.test\.tsx?$|\.integration\.tsx?$|\.d\.ts$)/;
 
 const IGNORE_TAG = "kumiko-lint-ignore section-fields-raw";
-// hasIgnoreTag() from _lib accepts a bare tag; the issue's premise 2 wants a
-// visible reason, so the trailing `\S` is the whole point of not reusing it.
-const REASONED_TAG = new RegExp(`${IGNORE_TAG}\\s+\\S`);
+// hasIgnoreTag() from _lib accepts a bare tag; a visible reason is required, so
+// the reason must start with a real character: the `*` of a closing `*/` (block
+// and JSX comments) must not count as one.
+const REASONED_TAG = new RegExp(`${IGNORE_TAG}\\s+(?!\\*/)[^\\s*]`);
 
 const SECTION_RECEIVER = /section/i;
 
@@ -83,6 +92,7 @@ const ARRAY_READS = new Set([
   "find",
   "findIndex",
   "findLast",
+  "findLastIndex",
   "flat",
   "flatMap",
   "forEach",
@@ -90,6 +100,7 @@ const ARRAY_READS = new Set([
   "indexOf",
   "join",
   "keys",
+  "lastIndexOf",
   "map",
   "reduce",
   "reduceRight",
@@ -99,7 +110,9 @@ const ARRAY_READS = new Set([
   "sort",
   "toReversed",
   "toSorted",
+  "toSpliced",
   "values",
+  "with",
 ]);
 
 function relFile(sf: SourceFile, roots: readonly RepoRoot[]): string {
@@ -112,19 +125,68 @@ function hasReasonedIgnoreTag(node: Node): boolean {
   return REASONED_TAG.test(lines[line - 1] ?? "") || REASONED_TAG.test(lines[line - 2] ?? "");
 }
 
+// A section is recognised by its name or, when types resolve, by carrying a
+// `groups` property — so `sec.fields` and `layout.sections.map((s) => s.fields)`
+// are caught too. The name regex stays as the fallback for untyped receivers.
+function isSectionReceiver(receiver: Node): boolean {
+  if (SECTION_RECEIVER.test(receiver.getText())) return true;
+  return receiver.getType().getProperty("groups") !== undefined;
+}
+
+// Climbs `x!`, `(x)`, `x as T` and `x ?? y` so a wrapped read is judged by the
+// context it ends up in.
+function unwrapReadContext(access: Node): Node {
+  let current = access;
+  for (;;) {
+    const parent = current.getParent();
+    if (
+      parent !== undefined &&
+      (parent.isKind(SyntaxKind.NonNullExpression) ||
+        parent.isKind(SyntaxKind.ParenthesizedExpression) ||
+        parent.isKind(SyntaxKind.AsExpression) ||
+        (parent.isKind(SyntaxKind.BinaryExpression) &&
+          parent.getOperatorToken().getKind() === SyntaxKind.QuestionQuestionToken &&
+          parent.getLeft() === current))
+    ) {
+      current = parent;
+      continue;
+    }
+    return current;
+  }
+}
+
 function isSequenceRead(access: PropertyAccessExpression): boolean {
-  const parent = access.getParent();
+  const read = unwrapReadContext(access);
+  const parent = read.getParent();
   if (parent === undefined) return false;
-  if (parent.isKind(SyntaxKind.ForOfStatement)) return parent.getExpression() === access;
+  if (parent.isKind(SyntaxKind.ForOfStatement)) return parent.getExpression() === read;
   if (parent.isKind(SyntaxKind.SpreadElement) || parent.isKind(SyntaxKind.SpreadAssignment)) {
     return true;
   }
-  if (parent.isKind(SyntaxKind.PropertyAccessExpression) && ARRAY_READS.has(parent.getName())) {
+  if (parent.isKind(SyntaxKind.ElementAccessExpression)) return parent.getExpression() === read;
+  if (parent.isKind(SyntaxKind.CallExpression)) return parent.getArguments().includes(read);
+  if (
+    parent.isKind(SyntaxKind.PropertyAccessExpression) &&
+    parent.getExpression() === read &&
+    ARRAY_READS.has(parent.getName())
+  ) {
     return parent.getParent()?.isKind(SyntaxKind.CallExpression) === true;
   }
   return false;
 }
 
+function isDestructuredFieldsRead(declaration: VariableDeclaration): boolean {
+  const pattern = declaration.getNameNode();
+  const initializer = declaration.getInitializer();
+  if (!pattern.isKind(SyntaxKind.ObjectBindingPattern) || initializer === undefined) return false;
+  if (!isSectionReceiver(initializer)) return false;
+  return pattern
+    .getElements()
+    .some(
+      (element) => (element.getPropertyNameNode() ?? element.getNameNode()).getText() === "fields",
+    );
+}
+
 export interface Finding {
   file: string;
   line: number;
@@ -138,7 +200,7 @@ export function scanRawSectionFieldReads(
   const findings: Finding[] = [];
   for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
     if (access.getName() !== "fields") continue;
-    if (!SECTION_RECEIVER.test(access.getExpression().getText())) continue;
+    if (!isSectionReceiver(access.getExpression())) continue;
     if (!isSequenceRead(access)) continue;
     if (hasReasonedIgnoreTag(access)) continue;
     const line = access.getStartLineNumber();
@@ -148,6 +210,16 @@ export function scanRawSectionFieldReads(
       `  [section-fields-raw WARN] ${file}:${line}  raw read of ${access.getText().slice(0, 80)} — use sectionFieldSpecs(section)`,
     );
   }
+  for (const declaration of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+    if (!isDestructuredFieldsRead(declaration)) continue;
+    if (hasReasonedIgnoreTag(declaration)) continue;
+    const line = declaration.getStartLineNumber();
+    const file = relFile(sf, roots);
+    findings.push({ file, line, snippet: declaration.getText().slice(0, 80) });
+    console.warn(
+      `  [section-fields-raw WARN] ${file}:${line}  destructured fields of ${declaration.getText().slice(0, 80)} — use sectionFieldSpecs(section)`,
+    );
+  }
   return findings;
 }
 

package/src/guard-test-stack-drift.ts

@@ -94,8 +94,18 @@ function collectCallNames(sf: SourceFile): Map<string, number[]> {
   return calls;
 }
 
+// Only a marker inside a real comment counts: the same text
+// inside a string/template literal is fixture data, not an opt-out.
 function hasOptOutMarker(sf: SourceFile): boolean {
-  return OPT_OUT_MARKER.test(sf.getFullText());
+  const text = sf.getFullText();
+  const marker = new RegExp(OPT_OUT_MARKER.source, "gi");
+  for (const match of text.matchAll(marker)) {
+    const kind = sf.getDescendantAtPos(match.index)?.getKind();
+    if (kind === SyntaxKind.SingleLineCommentTrivia || kind === SyntaxKind.MultiLineCommentTrivia) {
+      return true;
+    }
+  }
+  return false;
 }
 
 export function scanFile(sf: SourceFile): Violation | null {

package/src/guard-test-template-drift.ts

@@ -74,6 +74,16 @@ const RAW_DEFINE_CONFIG_MODULE = "@playwright/test";
 
 const TEMPLATE_OWNED_KEYS: ReadonlySet<string> = new Set(["viewport", "deviceScaleFactor"]);
 
+// Top-level config keys the template owns; spreading defineAppE2eConfig(...)
+// and then setting one of them re-opens the drift the template closes.
+const TEMPLATE_OWNED_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  "fullyParallel",
+  "retries",
+  "timeout",
+  "workers",
+  "expect",
+]);
+
 export interface Finding {
   file: string;
   line: number;
@@ -148,7 +158,11 @@ function isPlaywrightUseObject(node: Node): boolean {
 function templateOwnedKeyFindings(sf: SourceFile): Finding[] {
   const findings: Finding[] = [];
   const isConfigFile = CONFIG_FILENAME.test(sf.getFilePath());
-  for (const prop of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+  const props = [
+    ...sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment),
+    ...sf.getDescendantsOfKind(SyntaxKind.ShorthandPropertyAssignment),
+  ];
+  for (const prop of props) {
     const name = prop.getName();
     if (!TEMPLATE_OWNED_KEYS.has(name)) continue;
     // viewport is only drift in the config's own use/project use — a spec's
@@ -170,6 +184,34 @@ function templateOwnedKeyFindings(sf: SourceFile): Finding[] {
   return findings;
 }
 
+function isDefineAppE2eConfigSpread(node: Node): boolean {
+  if (!Node.isSpreadAssignment(node)) return false;
+  const spread = node.getExpression();
+  return (
+    Node.isCallExpression(spread) && spread.getExpression().getText() === DEFINE_APP_E2E_CONFIG
+  );
+}
+
+function configOverrideFindings(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  for (const literal of sf.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+    const properties = literal.getProperties();
+    if (!properties.some(isDefineAppE2eConfigSpread)) continue;
+    for (const prop of properties) {
+      if (!Node.isPropertyAssignment(prop) && !Node.isShorthandPropertyAssignment(prop)) continue;
+      const name = prop.getName();
+      if (!TEMPLATE_OWNED_CONFIG_KEYS.has(name)) continue;
+      const message = withExceptionNote(
+        prop,
+        `Config key "${name}" next to a ...defineAppE2eConfig(...) spread — timeouts, retries, workers and expect belong to the template; pass the supported options to defineAppE2eConfig instead.`,
+      );
+      if (message !== undefined)
+        findings.push({ file: "", line: prop.getStartLineNumber(), message });
+    }
+  }
+  return findings;
+}
+
 function isPageScreenshotCall(call: Node): boolean {
   if (!Node.isCallExpression(call)) return false;
   const callee = call.getExpression();
@@ -202,7 +244,11 @@ export function scanTemplateDrift(
   const findings: Finding[] = [];
   const own = ownConfigFinding(sf);
   if (own !== undefined) findings.push({ ...own, file });
-  for (const f of [...templateOwnedKeyFindings(sf), ...pageScreenshotFindings(sf)]) {
+  for (const f of [
+    ...templateOwnedKeyFindings(sf),
+    ...configOverrideFindings(sf),
+    ...pageScreenshotFindings(sf),
+  ]) {
     findings.push({ ...f, file });
   }
   return findings.sort((a, b) => a.line - b.line);

package/src/guard-test-timeouts.ts

@@ -2,7 +2,8 @@
 /**
  * Guard: tests wait for a condition, not for time. Flags, in test files and
  * Playwright specs/helpers:
- *   (a) `test.setTimeout(...)`, `test.slow(...)` — raising a timeout hides the
+ *   (a) `test.setTimeout(...)`, `test.slow(...)`, `setDefaultTimeout(...)`,
+ *       `*.describe.configure({ timeout })` — raising a timeout hides the
  *       cause of a slow or flaky test
  *   (b) `<page>.waitForTimeout(...)` — a fixed sleep instead of a condition
  *   (c) sleep loops — a `while`/`do`/`for`/`for…of`/`for…in` whose body calls
@@ -67,6 +68,8 @@ const LOOP_LABELS: ReadonlyMap<SyntaxKind, string> = new Map([
 const SLEEP_CALLEES: ReadonlySet<string> = new Set(["sleep", "Bun.sleep"]);
 const TIMEOUT_RAISING_CALLEES: ReadonlySet<string> = new Set(["test.setTimeout", "test.slow"]);
 const SET_TIMEOUT_CALLEE = /(^|\.)setTimeout$/;
+const SET_DEFAULT_TIMEOUT_CALLEE = /(^|\.)setDefaultTimeout$/;
+const DESCRIBE_CONFIGURE_CALLEE = /(^|\.)describe\.configure$/;
 
 export interface Finding {
   file: string;
@@ -127,10 +130,26 @@ function exceptionNote(node: Node): "allowed" | "incomplete" | "none" {
   return nearby.some((text) => text.includes(EXCEPTION_TAG)) ? "incomplete" : "none";
 }
 
+function hasTimeoutProperty(node: Node | undefined): boolean {
+  return (
+    node !== undefined &&
+    Node.isObjectLiteralExpression(node) &&
+    node.getProperties().some((prop) => {
+      if (Node.isShorthandPropertyAssignment(prop) || Node.isPropertyAssignment(prop)) {
+        return prop.getName() === "timeout";
+      }
+      return false;
+    })
+  );
+}
+
 function raisedTimeoutReason(call: CallExpression): string | undefined {
   const callee = call.getExpression();
   const calleeText = callee.getText();
-  if (TIMEOUT_RAISING_CALLEES.has(calleeText)) {
+  if (TIMEOUT_RAISING_CALLEES.has(calleeText) || SET_DEFAULT_TIMEOUT_CALLEE.test(calleeText)) {
+    return `${calleeText}(…) raises the timeout instead of fixing the cause`;
+  }
+  if (DESCRIBE_CONFIGURE_CALLEE.test(calleeText) && call.getArguments().some(hasTimeoutProperty)) {
     return `${calleeText}(…) raises the timeout instead of fixing the cause`;
   }
   if (Node.isPropertyAccessExpression(callee) && callee.getName() === "waitForTimeout") {

package/src/guard-thin-wrappers.ts

@@ -39,7 +39,7 @@ import {
 } from "ts-morph";
 import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 import { frameworkTsConfigPath } from "./_lib/roots";
-import { type ScanSpec, scanFiles, scanRoots } from "./_lib/scan-scope";
+import { keepsRootKind, type ScanSpec, scanFiles } from "./_lib/scan-scope";
 
 const ROOT = process.cwd();
 
@@ -387,7 +387,7 @@ export const check: RepoCheck = {
     // The kind filter (scan-scope.ts keepsRootKind) excludes "tooling" roots by
     // default — that's a deliberate scope choice, not a vacuous scan, so it must
     // report notApplicable instead of matchedFiles: 0.
-    if (scanRoots(SCAN, roots).length === 0) {
+    if (!roots.some((root) => keepsRootKind(SCAN, root))) {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }
 

package/src/guard-upgrade-state.ts

@@ -109,9 +109,12 @@ export function pendingViolations(json: UpgradeJson, markerVersion: string): Gua
   }));
 }
 
-function resolveKumikoUpgradeBin(cwd: string): string | undefined {
-  const which = Bun.which("kumiko-upgrade");
-  if (which) return which;
+export function resolveKumikoUpgradeBin(
+  cwd: string,
+  pathEnv: string | undefined = process.env["PATH"],
+): string | undefined {
+  // Repo-pinned binary wins over PATH so the marker is measured against the
+  // version this checkout actually installs.
   let dir = cwd;
   for (;;) {
     const candidate = join(dir, "node_modules", ".bin", "kumiko-upgrade");
@@ -120,7 +123,7 @@ function resolveKumikoUpgradeBin(cwd: string): string | undefined {
     if (parent === dir) break;
     dir = parent;
   }
-  return undefined;
+  return Bun.which("kumiko-upgrade", { PATH: pathEnv }) ?? undefined;
 }
 
 async function runKumikoUpgrade(

package/src/pre-push.sh

@@ -123,7 +123,7 @@ fi
 # canonical sibling path instead of this worktree — checking the wrong
 # code. Run the worktree-local check only when scripts/check-wt.sh is
 # tracked and executable (untracked/symlink stubs must not hijack push).
-if [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] \
+if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
    && git -C "$REPO_ROOT" ls-files --error-unmatch scripts/check-wt.sh >/dev/null 2>&1 \
    && [ -x "$REPO_ROOT/scripts/check-wt.sh" ]; then
   echo "[pre-push] worktree detected — worktree check (see scripts/check-wt.sh)…"
@@ -153,7 +153,7 @@ run_guard_bin() {
 # worktree's own package.json scripts directly instead (only when nested
 # under the parent workspace; a standalone worktree's own `bun run test`
 # already checks the right code).
-if [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] \
+if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
    && [ -n "$PARENT_DIR" ]; then
   cd "$REPO_ROOT"
   echo "[pre-push] worktree without scripts/check-wt.sh — running this worktree's package.json scripts (typecheck, lint, test, test:dom) and guards (guards, checks, comment-lang)…"

package/src/run-guards.ts

@@ -121,6 +121,10 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
     console.error(flagsError);
     return 1;
   }
+  if (guardNameArg !== undefined && !flags.includes("--write-baseline")) {
+    console.error("--guard=<name> is only valid with --write-baseline");
+    return 1;
+  }
   if (flags.includes("--explain")) {
     for (const line of explainGuards(GUARDS, buildSharedProject(GUARDS))) {
       console.log(line);
@@ -169,5 +173,6 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
 // Only run on direct invocation — otherwise `import { GUARDS }` would kick
 // off the whole suite and the list wouldn't be testable.
 if (import.meta.main) {
-  process.exit(runGuardsCli(process.argv.slice(2)));
+  // Exit codes wrap at 256, so a raw failure count could read as success.
+  process.exit(runGuardsCli(process.argv.slice(2)) > 0 ? 1 : 0);
 }

package/src/run-repo-checks.ts

@@ -49,5 +49,5 @@ export async function runRepoChecksCli(argv: readonly string[]): Promise<number>
 }
 
 if (import.meta.main) {
-  process.exit(await runRepoChecksCli(process.argv.slice(2)));
+  process.exit((await runRepoChecksCli(process.argv.slice(2))) > 0 ? 1 : 0);
 }

package/src/run-ui-guards.ts

@@ -47,5 +47,5 @@ export function runUiGuardsCli(argv: readonly string[]): number {
 
 // Same as run-guards.ts: only run on direct invocation.
 if (import.meta.main) {
-  process.exit(runUiGuardsCli(process.argv.slice(2)));
+  process.exit(runUiGuardsCli(process.argv.slice(2)) > 0 ? 1 : 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,
         });