@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/analyze/chains.ts

@@ -0,0 +1,411 @@
+/**
+ * chains — boundary-aware import-chain stitching (the "why" answer).
+ *
+ * The human-meaningful import chain for a client-reachable module is a
+ * JOIN of two graphs: RSC-graph importers ABOVE the `'use client'`
+ * boundary and SSR-graph importers BELOW it. Walking `importers` naively
+ * in one graph produces virtual-entry noise (`virtual:vite-rsc/css`)
+ * instead of semantic importers — the design/47 §7 findings this module
+ * bakes in:
+ *
+ * - RSC-side walks terminate at `virtual:timber-route-manifest` or the
+ *   first route-convention file (page/layout/…), never the literal RSC
+ *   entry — route files' importer is the manifest, whose importers are
+ *   framework internals; the manifest is the semantic root.
+ * - `\0virtual:vite-rsc/*` importers are filtered so they can never
+ *   surface in a chain.
+ * - When multiple boundaries import the target, one chain is reported
+ *   PER BOUNDARY — a single BFS shortest path would pick arbitrarily.
+ *
+ * The chain/hop shapes and text formatting are shared with doc 43's
+ * `timber why` so both commands emit the same contract: hops carry
+ * `{ id, directive, boundary }`, and one shortest chain is emitted per
+ * (boundary, reaching route entry) pair — doc 43's "one shortest path
+ * per reaching entry", crossed with §7's per-boundary rule.
+ *
+ * Design docs: 47-module-environment-tooling.md §7, 43-analyze-cli.md
+ * §Output Formats.
+ */
+
+import { relative, isAbsolute } from 'node:path';
+import { normalizePath } from 'vite';
+import { isConventionSourceFile, type Directive } from './classify.ts';
+
+/**
+ * Duck-typed view of a Vite environment module node — a supertype of
+ * `EnvironmentModuleNode` for the members the walk reads, so live
+ * dev-server graphs and crawl graphs both satisfy it structurally.
+ */
+export interface ChainModuleNode {
+  id: string | null;
+  url: string;
+  file: string | null;
+  importers: Set<ChainModuleNode>;
+}
+
+/** Duck-typed view of a Vite environment module graph. */
+export interface ChainGraph {
+  getModulesByFile(file: string): Set<ChainModuleNode> | undefined;
+}
+
+/** Per-hop directive in doc 43's JSON vocabulary. */
+export type HopDirective = 'client' | 'server' | null;
+
+export interface ChainHop {
+  /** Absolute file path, or a virtual module id printed verbatim. */
+  id: string;
+  directive: HopDirective;
+  /** True only on the hop that crosses the server→client boundary. */
+  boundary: boolean;
+}
+
+export interface ImportChain {
+  /**
+   * Semantic root: a route-convention file, or the route-manifest
+   * virtual id when the walk reached it without passing one. Null when
+   * the RSC-side walk dead-ended (no root found) — the chain then
+   * starts at its deepest known importer and consumers must present it
+   * as partial.
+   */
+  entry: string | null;
+  /**
+   * The `'use client'` file this chain crosses; null for a pure
+   * server-side chain.
+   */
+  boundary: string | null;
+  /** Hops in forward import order, entry → … → target. */
+  hops: ChainHop[];
+}
+
+export interface ChainContext {
+  rsc: ChainGraph;
+  ssr: ChainGraph;
+  /** Absolute app directory — scopes route-convention root detection. */
+  appDir: string;
+  /**
+   * Configured pageExtensions, when the caller has resolved the app
+   * config — a `page.mdx` app's route files are only roots with it.
+   * Omitted → scanner defaults.
+   */
+  pageExtensions?: readonly string[];
+  /**
+   * First directive of a file's ORIGINAL source (design/43: never the
+   * transformed output, where directives are stripped/proxied).
+   */
+  getDirective(file: string): Directive;
+}
+
+/**
+ * The route manifest appears under several ids depending on environment
+ * and build phase: `virtual:timber-route-manifest`,
+ * `\0virtual:timber-route-manifest`, and a root-prefixed form
+ * (plugins/routing.ts) — match by substring.
+ */
+function isRouteManifest(key: string): boolean {
+  return key.includes('virtual:timber-route-manifest');
+}
+
+/** plugin-rsc internal virtuals (observed: virtual:vite-rsc/css). */
+function isViteRscInternal(key: string): boolean {
+  return key.includes('virtual:vite-rsc/');
+}
+
+/**
+ * File-level vertex key for a node: the file path when Vite resolved
+ * one, else the virtual id. Multiple nodes can exist per file (query
+ * variants); collapsing to the file keeps chains at source granularity.
+ */
+function vertexKey(node: ChainModuleNode): string | null {
+  return node.file ?? node.id ?? node.url ?? null;
+}
+
+/**
+ * Separator for path signatures. Sorts below every printable character
+ * so comparing joined signatures equals comparing key sequences.
+ */
+const SIG_SEP = '\u0000';
+
+/**
+ * Backwards level-order BFS over `importers` from `start`, collapsing
+ * nodes to file-level vertices and filtering plugin-rsc internals.
+ *
+ * Shortest-path ties are broken GLOBALLY: each vertex's predecessor is
+ * the candidate whose full path signature (the id sequence from the
+ * target outward) is lexicographically smallest — per-frontier
+ * candidate selection, not merely per-parent importer sorting, so
+ * reconverging equal-length branches still yield the advertised
+ * representative path (doc 43 §Tie-Breaking).
+ *
+ * `stopAt` marks terminal vertices. By default their importers are not
+ * expanded (RSC walks must not proceed past a route root into
+ * framework internals); with `continuePastTerminals` the traversal
+ * records the terminal and keeps walking — the SSR walk needs this so
+ * an outer boundary that imports an inner boundary is still
+ * discovered (one chain per boundary).
+ */
+function walkImporters(
+  graph: ChainGraph,
+  start: string,
+  stopAt: (key: string) => boolean,
+  continuePastTerminals = false
+): { predecessors: Map<string, string | null>; terminals: string[] } {
+  const startNodes = graph.getModulesByFile(start);
+  const predecessors = new Map<string, string | null>();
+  const terminals: string[] = [];
+  if (!startNodes || startNodes.size === 0) return { predecessors, terminals };
+
+  predecessors.set(start, null);
+  const signatures = new Map<string, string>([[start, start]]);
+  const nodesOf = new Map<string, ChainModuleNode[]>([[start, [...startNodes]]]);
+  let frontier = [start];
+
+  while (frontier.length > 0) {
+    interface Candidate {
+      sig: string;
+      parent: string;
+      observed: ChainModuleNode[];
+    }
+    const candidates = new Map<string, Candidate>();
+    for (const key of frontier) {
+      if (stopAt(key)) {
+        terminals.push(key);
+        if (!continuePastTerminals) continue;
+      }
+      for (const node of nodesOf.get(key) ?? []) {
+        for (const importer of node.importers) {
+          const importerKey = vertexKey(importer);
+          if (!importerKey || isViteRscInternal(importerKey)) continue;
+          if (predecessors.has(importerKey)) continue;
+          // Every frontier vertex has a signature (set when its level
+          // was fixed); the fallback only satisfies the type.
+          const sig = (signatures.get(key) ?? key) + SIG_SEP + importerKey;
+          const existing = candidates.get(importerKey);
+          if (!existing) {
+            candidates.set(importerKey, { sig, parent: key, observed: [importer] });
+          } else {
+            // Keep every observed node object (virtual ids have no file
+            // index to re-fetch from), but the smallest signature wins
+            // the predecessor slot.
+            existing.observed.push(importer);
+            if (sig < existing.sig) {
+              existing.sig = sig;
+              existing.parent = key;
+            }
+          }
+        }
+      }
+    }
+    // Fix the next level, ordered by signature so terminal discovery
+    // order — and therefore chain order — is deterministic.
+    const next = [...candidates.entries()].sort(([, a], [, b]) =>
+      a.sig < b.sig ? -1 : a.sig > b.sig ? 1 : 0
+    );
+    frontier = [];
+    for (const [importerKey, candidate] of next) {
+      predecessors.set(importerKey, candidate.parent);
+      signatures.set(importerKey, candidate.sig);
+      // Re-fetch the file's FULL node set from the graph: the importer
+      // edges seen so far may cover only one of several nodes per file
+      // (query variants — ?direct, ?v=…), and expanding a partial set
+      // would silently drop the sibling nodes' importers and dead-end
+      // the chain. Virtual ids have no file index; use observed nodes.
+      const fullNodes = graph.getModulesByFile(importerKey);
+      nodesOf.set(
+        importerKey,
+        fullNodes && fullNodes.size > 0 ? [...fullNodes] : candidate.observed
+      );
+      frontier.push(importerKey);
+    }
+  }
+  return { predecessors, terminals };
+}
+
+/** Follow predecessors from `from` back to the walk's start vertex. */
+function pathToStart(predecessors: Map<string, string | null>, from: string): string[] {
+  const path: string[] = [];
+  for (let key: string | null = from; key !== null; key = predecessors.get(key) ?? null) {
+    path.push(key);
+  }
+  return path;
+}
+
+function isRouteRoot(key: string, ctx: ChainContext): boolean {
+  // Manifest matching applies to virtual ids only — a real file whose
+  // path happens to contain the substring must not become a root.
+  if (!isAbsolute(key) && isRouteManifest(key)) return true;
+  if (!isAbsolute(key)) return false;
+  if (key !== ctx.appDir && !key.startsWith(ctx.appDir + '/')) return false;
+  return isConventionSourceFile(key, ctx.pageExtensions);
+}
+
+/**
+ * RSC-side walk: importers of `file` in the RSC graph up to the
+ * semantic roots. Returns one chain PER reaching route entry (doc 43:
+ * "one shortest path per reaching entry"), each with hops in forward
+ * order (root → … → file), in discovery order (shallowest first,
+ * signature tie-break). When no root was reached, a single partial
+ * result (entry: null) carrying the deepest known path.
+ */
+function rscSideChains(
+  file: string,
+  ctx: ChainContext
+): Array<{ entry: string | null; files: string[] }> {
+  const { predecessors, terminals } = walkImporters(ctx.rsc, file, (key) => isRouteRoot(key, ctx));
+  if (terminals.length > 0) {
+    return terminals.map((root) => ({ entry: root, files: pathToStart(predecessors, root) }));
+  }
+  if (predecessors.size <= 1) {
+    // Nothing above the file at all (or file absent from the graph).
+    return [{ entry: null, files: [file] }];
+  }
+  // Dead end — no root found. Report from the deepest vertex on the
+  // last-discovered shortest path so the partial chain is still useful.
+  const keys = [...predecessors.keys()];
+  const deepest = keys[keys.length - 1];
+  return [{ entry: null, files: pathToStart(predecessors, deepest) }];
+}
+
+/** Map a source directive onto the doc-43 hop vocabulary. */
+function hopDirective(key: string, ctx: ChainContext): HopDirective {
+  if (!isAbsolute(key)) return null;
+  const directive = ctx.getDirective(key);
+  if (directive === 'use client') return 'client';
+  if (directive === 'use server') return 'server';
+  return null;
+}
+
+function toChain(
+  entry: string | null,
+  boundary: string | null,
+  files: string[],
+  ctx: ChainContext
+): ImportChain {
+  return {
+    entry,
+    boundary,
+    hops: files.map((key) => ({
+      id: key,
+      directive: hopDirective(key, ctx),
+      boundary: boundary !== null && key === boundary,
+    })),
+  };
+}
+
+/**
+ * Stitch the import chain(s) for a target file.
+ *
+ * - Target in the SSR graph (client-side): walk SSR importers up to
+ *   each `'use client'` boundary that the RSC graph knows (nested
+ *   boundaries only reachable from other client components are walked
+ *   THROUGH — they exist in no RSC graph, so the chain must continue
+ *   to a boundary a server component actually references), then walk
+ *   RSC importers from that boundary to the semantic root. One chain
+ *   per boundary.
+ * - Target in the RSC graph without `'use client'`: a pure server
+ *   chain (boundary: null). Shared modules get both kinds.
+ * - Target IS an RSC-known boundary: an RSC-side chain from the target
+ *   itself, PLUS any outer-boundary chains the SSR walk finds — a
+ *   boundary imported by another boundary is pulled in by both. A
+ *   nested `'use client'` target the RSC graph does NOT know is
+ *   handled like any client-internal file — the SSR walk continues to
+ *   the boundary a server component references.
+ */
+export function stitchImportChains(rawTargetFile: string, rawCtx: ChainContext): ImportChain[] {
+  // Vite module-node `file` values are slash-normalized even on
+  // Windows, while node:path targets/appDir arrive backslashed there —
+  // normalize both once so graph lookups and containment checks agree
+  // (normalizePath only rewrites separators on Windows, so posix paths
+  // pass through untouched).
+  const targetFile = normalizePath(rawTargetFile);
+  const ctx: ChainContext = { ...rawCtx, appDir: normalizePath(rawCtx.appDir) };
+
+  const chains: ImportChain[] = [];
+  const targetDirective = ctx.getDirective(targetFile);
+  const targetInRsc = (ctx.rsc.getModulesByFile(targetFile)?.size ?? 0) > 0;
+
+  if (targetDirective === 'use client' && targetInRsc) {
+    for (const above of rscSideChains(targetFile, ctx)) {
+      chains.push(toChain(above.entry, targetFile, above.files, ctx));
+    }
+  }
+
+  // Client-side chains: one per RSC-known boundary above the target.
+  const isRscKnownBoundary = (key: string): boolean =>
+    isAbsolute(key) &&
+    ctx.getDirective(key) === 'use client' &&
+    (ctx.rsc.getModulesByFile(key)?.size ?? 0) > 0;
+
+  // continuePastTerminals: an outer boundary that imports an inner
+  // boundary must still be discovered — one chain per boundary.
+  const ssrWalk = walkImporters(ctx.ssr, targetFile, isRscKnownBoundary, true);
+  for (const boundary of [...ssrWalk.terminals].sort()) {
+    // A boundary target records itself as a terminal; its own chain is
+    // the RSC-side one already pushed above.
+    if (boundary === targetFile) continue;
+    const below = pathToStart(ssrWalk.predecessors, boundary);
+    for (const above of rscSideChains(boundary, ctx)) {
+      // Stitch, dropping the duplicated boundary vertex from the RSC side.
+      chains.push(toChain(above.entry, boundary, [...above.files.slice(0, -1), ...below], ctx));
+    }
+  }
+
+  // Pure server chains when the RSC graph reaches the target directly.
+  if (targetInRsc && targetDirective !== 'use client') {
+    for (const above of rscSideChains(targetFile, ctx)) {
+      chains.push(toChain(above.entry, null, above.files, ctx));
+    }
+  }
+
+  // SSR-side dead end with nothing else to show: mirror the RSC side's
+  // honesty and emit a partial chain from the deepest importer instead
+  // of returning [] as if the file were in no graph. A singleton walk
+  // (target in the SSR graph with no importers at all) still emits its
+  // one-hop partial — graph membership is information.
+  if (chains.length === 0 && ssrWalk.predecessors.size > 0) {
+    const keys = [...ssrWalk.predecessors.keys()];
+    const deepest = keys[keys.length - 1];
+    chains.push(toChain(null, null, pathToStart(ssrWalk.predecessors, deepest), ctx));
+  }
+
+  return chains;
+}
+
+/**
+ * Render chains in doc 43's text shape — shared by `timber graph` and
+ * `timber why` so both commands print identically:
+ *
+ * ```
+ *   app/page.tsx
+ *     → app/nav.tsx  ← 'use client' [boundary]
+ *       → src/lib/icons/chevron.ts
+ * ```
+ *
+ * Paths under `projectRoot` print relative; virtual ids print verbatim
+ * (doc 43 §Relative-vs-Absolute Paths). A partial chain (entry: null)
+ * is prefixed with an honest marker instead of silently posing as
+ * complete.
+ */
+export function formatChains(chains: ImportChain[], projectRoot: string): string {
+  const root = normalizePath(projectRoot);
+  const lines: string[] = [];
+  for (const chain of chains) {
+    if (lines.length > 0) lines.push('');
+    if (chain.entry === null) {
+      lines.push('  (partial chain — no route root found)');
+    }
+    chain.hops.forEach((hop, index) => {
+      const display =
+        isAbsolute(hop.id) && hop.id.startsWith(root + '/') ? relative(root, hop.id) : hop.id;
+      const indent = '  '.repeat(index + 1);
+      const arrow = index === 0 ? '' : '→ ';
+      let annotation = '';
+      if (hop.directive === 'client') {
+        annotation = `  ← 'use client'${hop.boundary ? ' [boundary]' : ''}`;
+      } else if (hop.directive === 'server') {
+        annotation = `  ← 'use server'`;
+      }
+      lines.push(`${indent}${arrow}${display}${annotation}`);
+    });
+  }
+  return lines.join('\n');
+}

package/src/analyze/classify.ts

@@ -0,0 +1,259 @@
+/**
+ * classify — environment-graph classification for project modules.
+ *
+ * The one classification module every frontend shares (design/47): the
+ * `timber graph` CLI, the dev-server endpoint, the VS Code extension,
+ * and the cold crawl must never disagree about a file's environment.
+ * Classification intersects RSC/SSR module-graph membership with
+ * first-directive detection to produce the decided taxonomy:
+ *
+ * - `server`          — RSC graph only
+ * - `client-boundary` — has `'use client'`
+ * - `client-internal` — reachable only behind a boundary, no directive
+ * - `shared`          — instantiated in both environments; INFO, never a
+ *                       warning — shared-by-design is a legitimate pattern
+ * - `server-action`   — has `'use server'`
+ * - `unreferenced`    — in no graph and no provisional signal; files with
+ *                       a directive or filename convention get that
+ *                       provisional kind instead, marked `pending`
+ *
+ * The browser (`client`) Vite graph stays empty until a real browser
+ * requests modules, so membership is RSC × SSR — the SSR graph is a
+ * faithful proxy for the client tree (design/47 §8, with the frontier
+ * caveat below).
+ *
+ * Design docs: 47-module-environment-tooling.md (taxonomy, §8),
+ * 43-analyze-cli.md (directive detection rules).
+ */
+
+import { basename, extname } from 'node:path';
+import { parseAst, normalizePath } from 'vite';
+import { hasDirective } from '../rsc-runtime/transforms.ts';
+import { isRouteConventionFile } from '../routing/scanner.ts';
+import {
+  isDynamicMetadataExtension,
+  isStaticMetadataExtension,
+} from '../server/metadata-routes.ts';
+
+/** The statement-list shape hasDirective consumes (estree Program body). */
+type DirectiveBody = Parameters<typeof hasDirective>[0];
+
+export type ModuleKind =
+  | 'server'
+  | 'client-boundary'
+  | 'client-internal'
+  | 'shared'
+  | 'server-action'
+  | 'unreferenced';
+
+export type Directive = 'use client' | 'use server' | null;
+
+/**
+ * What a frontend observed about one project module. Graph membership
+ * comes from the live dev-server graphs or the cold crawl; the directive
+ * comes from the module's original source (never the transformed output,
+ * where the RSC plugin has already stripped or proxied it).
+ */
+export interface ModuleObservation {
+  /** Absolute path of the source file. */
+  file: string;
+  /** Present in the RSC environment's module graph. */
+  inRsc: boolean;
+  /** Present in the SSR environment's module graph. */
+  inSsr: boolean;
+  /**
+   * Present in the browser (`client`) environment's module graph. Only a
+   * live dev server with a real connected browser can confirm this — the
+   * client graph stays empty otherwise (design/47 §8) — so the cold
+   * crawl always observes false. Defaults to false.
+   */
+  inClient?: boolean;
+  /**
+   * False when the SSR graph has a node for this file but Vite never
+   * transformed it — the §8 signature of a module behind an unexecuted
+   * dynamic import (`transformResult == null`). Its own membership is
+   * trustworthy; its subtree is not. Defaults to true.
+   */
+  ssrTransformed?: boolean;
+  /** First directive of the original source, or null. */
+  directive: Directive;
+}
+
+export interface ModuleClassification {
+  file: string;
+  kind: ModuleKind;
+  /**
+   * Raw per-environment graph membership, in doc 43's classification
+   * vocabulary (`{ client, ssr, rsc }`). `kind` is the interpreted
+   * answer; this is the evidence. `client` is confirmable only by a
+   * live browser graph — static scans always report false.
+   */
+  envs: { rsc: boolean; ssr: boolean; client: boolean };
+  /**
+   * True when no graph has confirmed this module — the kind is
+   * provisional, derived from directive + filename convention, and
+   * frontends must visibly mark it "pending" (design/47 §2).
+   */
+  pending: boolean;
+  /**
+   * §8 frontier: the module is reachable (it ships to the browser) but
+   * was never transformed, so modules behind it may be missing from the
+   * graphs entirely. Consumers should transform-on-demand or surface
+   * "reachable, subtree unknown".
+   */
+  subtreeUnknown: boolean;
+}
+
+/** File extensions eligible for directive detection. */
+const PARSEABLE_EXTENSIONS = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
+
+/**
+ * Parse language for a source file, from its extension. Never force
+ * `tsx` onto plain `.ts`: JSX-ambiguous TypeScript such as
+ * `const identity = <T>(value: T) => value` is valid TS but rejected
+ * by a TSX parse, and the resulting parse failure would silently drop
+ * the file's directive and poison signals. Plain JS parses as `jsx`
+ * (JSX-in-.js is common in Vite projects and JS has no generic-arrow
+ * ambiguity for the x-syntax to break).
+ */
+export function langForFile(file: string): 'ts' | 'tsx' | 'jsx' {
+  if (/\.tsx$/.test(file)) return 'tsx';
+  if (/\.[mc]?ts$/.test(file)) return 'ts';
+  return 'jsx';
+}
+
+/**
+ * Detect the first directive of a module's original source.
+ *
+ * Never string-match or regex directives (design/43): `hasDirective`
+ * from @vitejs/plugin-rsc checks for the `directive` property on
+ * ExpressionStatements — the same check the RSC plugin runs to decide
+ * boundaries, so classification agrees with what the framework actually
+ * does with the file. The directive must be in prologue position (before
+ * any import or statement) per the ECMAScript spec. Non-JS sources
+ * (CSS, MDX, assets) and sources that fail to parse return null — no
+ * directive is a safe default; classification then falls back to graph
+ * membership.
+ */
+export function detectDirective(code: string, file: string): Directive {
+  if (!PARSEABLE_EXTENSIONS.test(file)) return null;
+  let body: DirectiveBody;
+  try {
+    // Vite's parseAst returns oxc-typed nodes; hasDirective expects the
+    // estree shapes. They are structurally identical for the top-level
+    // statement scan — the same bridge the rest of the codebase uses
+    // (plugin-context.ts parse memo, routing/export-detect.ts).
+    body = parseAst(code, { lang: langForFile(file) }).body as unknown as DirectiveBody;
+  } catch {
+    return null;
+  }
+  if (hasDirective(body, 'use client')) return 'use client';
+  if (hasDirective(body, 'use server')) return 'use server';
+  return null;
+}
+
+/** Optional context for classification. */
+export interface ClassifyContext {
+  /**
+   * Absolute path of the app directory. When provided, convention-based
+   * provisional classification only applies to files inside it — a
+   * `lib/page.tsx` is not a route file, and the scanner would never
+   * recognize it there.
+   */
+  appDir?: string;
+  /**
+   * Configured pageExtensions, when the caller has resolved the app
+   * config. Omitted → scanner defaults.
+   */
+  pageExtensions?: readonly string[];
+}
+
+/**
+ * Whether a file is a route-convention source the framework itself
+ * imports (page/layout/route/… plus metadata routes). Conventions are
+ * derived from the routing scanner and the metadata route table — never
+ * a local duplicate list (drift lesson). Each family carries the
+ * scanner's own extension rules.
+ *
+ * Shared by the provisional classifier below and by chains.ts, whose
+ * RSC-side walks terminate at the first route-convention file
+ * (design/47 §7) — the two must never disagree about what counts.
+ *
+ * `pageExtensions` mirrors the scanner's parameter: callers that have
+ * resolved the app config pass the configured set (a `page.mdx` app);
+ * callers without config access fall back to the defaults and tolerate
+ * the mismatch.
+ */
+export function isConventionSourceFile(file: string, pageExtensions?: readonly string[]): boolean {
+  const ext = extname(file).slice(1);
+  const base = basename(file, `.${ext}`);
+  return (
+    isRouteConventionFile(base, ext, pageExtensions) ||
+    isStaticMetadataExtension(base, ext) ||
+    isDynamicMetadataExtension(base, ext)
+  );
+}
+
+/**
+ * Provisional kind for a file no graph has confirmed (design/47 §2):
+ * directive first, then filename convention, else `unreferenced`.
+ */
+function provisionalKind(file: string, directive: Directive, ctx?: ClassifyContext): ModuleKind {
+  if (directive === 'use client') return 'client-boundary';
+  if (directive === 'use server') return 'server-action';
+  // Normalize both sides before the containment check: on Windows,
+  // `file` may arrive slash-normalized (Vite module-node paths are)
+  // while appDir comes from node:path with backslashes — comparing raw
+  // would misreport every provisional route file as unreferenced.
+  if (ctx?.appDir && !normalizePath(file).startsWith(normalizePath(ctx.appDir) + '/')) {
+    return 'unreferenced';
+  }
+  if (isConventionSourceFile(file, ctx?.pageExtensions)) return 'server';
+  return 'unreferenced';
+}
+
+/**
+ * Classify one module from its observation. Pure — all frontends call
+ * this with membership data from their own graph source.
+ */
+export function classifyModule(
+  obs: ModuleObservation,
+  ctx?: ClassifyContext
+): ModuleClassification {
+  const referenced = obs.inRsc || obs.inSsr || obs.inClient === true;
+  const subtreeUnknown = obs.inSsr && obs.ssrTransformed === false;
+  const envs = { rsc: obs.inRsc, ssr: obs.inSsr, client: obs.inClient === true };
+
+  if (!referenced) {
+    return {
+      file: obs.file,
+      kind: provisionalKind(obs.file, obs.directive, ctx),
+      envs,
+      pending: true,
+      subtreeUnknown: false,
+    };
+  }
+
+  // Directive wins over membership: a 'use client' file also has an RSC
+  // graph node (the client-reference proxy), and a 'use server' module
+  // appears in the SSR graph when referenced from client forms — the
+  // directive is what those memberships mean.
+  let kind: ModuleKind;
+  if (obs.directive === 'use client') kind = 'client-boundary';
+  else if (obs.directive === 'use server') kind = 'server-action';
+  else if (obs.inRsc && obs.inSsr) kind = 'shared';
+  else if (obs.inRsc) kind = 'server';
+  else kind = 'client-internal';
+
+  return { file: obs.file, kind, envs, pending: false, subtreeUnknown };
+}
+
+/** Classify a batch of observations, sorted by file for stable output. */
+export function classifyModules(
+  observations: Iterable<ModuleObservation>,
+  ctx?: ClassifyContext
+): ModuleClassification[] {
+  return [...observations]
+    .map((obs) => classifyModule(obs, ctx))
+    .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+}