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

package/src/analyze/live-graph.ts

@@ -0,0 +1,232 @@
+/**
+ * live-graph — classification from a running dev server's environment
+ * module graphs (the fast path).
+ *
+ * When a dev server runs, the env module graphs are already resident —
+ * classification is a lookup, not a crawl. This module adapts those
+ * graphs to the SAME classification pipeline the cold crawl uses
+ * (classify.ts + chains.ts + poison-scan.ts — design/47's "one
+ * classification module, thin frontends" requirement), so the
+ * dev-server endpoint and the CLI can never disagree about a file.
+ *
+ * Differences from the crawl, both inherent to the live source:
+ *
+ * - The browser (`client`) graph can be non-empty here (a real browser
+ *   has requested modules), so `envs.client` is confirmable.
+ * - Rendering populates graphs lazily — only visited routes' code is
+ *   present, and modules behind unexecuted dynamic imports carry
+ *   `transformResult == null` (the §8 frontier). Those are reported as
+ *   `subtreeUnknown` rather than transformed on demand: a hint must
+ *   never mutate the dev server's graphs as a side effect of asking.
+ *
+ * Design docs: 47-module-environment-tooling.md §8, §"Dev-server
+ * endpoint".
+ */
+
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { normalizePath } from 'vite';
+import {
+  classifyModule,
+  detectDirective,
+  type ClassifyContext,
+  type Directive,
+} from './classify.ts';
+import type { GraphModuleReport } from './crawl.ts';
+import { stitchImportChains, type ChainGraph, type ImportChain } from './chains.ts';
+import {
+  collectImportSpecifiers,
+  importSignals,
+  poisoningsFor,
+  type Poisoning,
+} from './poison-scan.ts';
+import { buildSourceExtensions, scanProjectSourceFiles, type ScanFailure } from './scan.ts';
+
+/**
+ * Duck-typed node view for liveness checks — the `transformResult`
+ * member ChainModuleNode deliberately omits (§8 detection is a
+ * classification concern, not a chain concern).
+ */
+interface LiveModuleNode {
+  transformResult: unknown;
+}
+
+import type { ChainModuleNode } from './chains.ts';
+
+/** Duck-typed module graph — structural supertype of Vite's. */
+export interface LiveGraph extends ChainGraph {
+  getModulesByFile(file: string): Set<ChainModuleNode & LiveModuleNode> | undefined;
+}
+
+export interface LiveGraphContext {
+  rsc: LiveGraph;
+  ssr: LiveGraph;
+  client: LiveGraph;
+  /** Realpath'd project root. */
+  root: string;
+  appDir: string;
+  pageExtensions?: readonly string[];
+}
+
+/**
+ * Per-module answer — the crawl's shape, aliased rather than restated
+ * so a field added to one frontend cannot silently miss the other.
+ */
+export type LiveModuleReport = GraphModuleReport;
+
+/** Non-empty node set for a file in one graph. */
+function memberOf(graph: LiveGraph, file: string): boolean {
+  return (graph.getModulesByFile(file)?.size ?? 0) > 0;
+}
+
+/**
+ * §8: an SSR-graph member whose every node was never transformed is a
+ * module behind an unexecuted dynamic import — reachable (it ships to
+ * the browser) but its subtree may be missing from the graphs.
+ *
+ * Live-source caveat: Vite also clears `transformResult` when a watched
+ * edit invalidates a node, so on the live graphs `subtreeUnknown`
+ * means "not currently transformed" — a freshly-edited module reads
+ * the same as a dormant dynamic-import payload until the next render
+ * re-transforms it. The two states are indistinguishable from the
+ * graph alone, and both honestly mean the subtree is not currently
+ * known; consumers refreshing on `timber:graph-update` events see the
+ * flag clear once the module is re-transformed.
+ */
+function ssrTransformed(graph: LiveGraph, file: string): boolean | undefined {
+  const nodes = graph.getModulesByFile(file);
+  if (!nodes || nodes.size === 0) return undefined;
+  for (const node of nodes) {
+    if (node.transformResult != null) return true;
+  }
+  return false;
+}
+
+/**
+ * Classify one file from the live graphs. `file` must be an absolute
+ * realpath (graph nodes carry realpaths); it is slash-normalized here
+ * to match Vite's node keying.
+ */
+export async function classifyLiveFile(
+  rawFile: string,
+  ctx: LiveGraphContext,
+  // Shared across a ?all=1 sweep (classifyLiveProject) — a per-call
+  // cache would re-read every chain hop's source per target file,
+  // quadratic sync IO on well-connected graphs.
+  getDirective: (file: string) => Directive = makeDirectiveReader(),
+  // Failures are recorded, not swallowed (crawl parity): a lost source
+  // read means the directive/poisoning half of the answer is missing,
+  // and consumers deserve to see that beside the classification.
+  errors?: LiveGraphError[]
+): Promise<LiveModuleReport> {
+  const file = normalizePath(rawFile);
+  let code: string | null = null;
+  try {
+    code = await readFile(file, 'utf8');
+  } catch (error) {
+    // Unreadable (deleted mid-query): classification proceeds on graph
+    // membership alone; directive/poisonings default to none.
+    errors?.push({
+      environment: 'scan',
+      id: file,
+      message: `source read failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+  const directive: Directive = code === null ? null : detectDirective(code, file);
+  const signals = code === null ? [] : importSignals(collectImportSpecifiers(code, file));
+
+  const classifyCtx: ClassifyContext = {
+    appDir: ctx.appDir,
+    pageExtensions: ctx.pageExtensions,
+  };
+  const classification = classifyModule(
+    {
+      file,
+      inRsc: memberOf(ctx.rsc, file),
+      inSsr: memberOf(ctx.ssr, file),
+      inClient: memberOf(ctx.client, file),
+      ssrTransformed: ssrTransformed(ctx.ssr, file),
+      directive,
+    },
+    classifyCtx
+  );
+
+  const chains = classification.pending
+    ? []
+    : stitchImportChains(file, {
+        rsc: ctx.rsc,
+        ssr: ctx.ssr,
+        appDir: ctx.appDir,
+        pageExtensions: ctx.pageExtensions,
+        getDirective,
+      });
+
+  return {
+    ...classification,
+    boundary: directive === 'use client',
+    chains,
+    poisonings: poisoningsFor(classification.kind, classification.pending, signals),
+  };
+}
+
+/**
+ * Synchronous directive reader with a per-call cache. chains.ts wants a
+ * sync callback; node:fs readFileSync per unique hop file is acceptable
+ * for a walk bounded by chain length.
+ */
+function makeDirectiveReader(): (file: string) => Directive {
+  const cache = new Map<string, Directive>();
+  return (file) => {
+    const hit = cache.get(file);
+    if (hit !== undefined) return hit;
+    let directive: Directive = null;
+    try {
+      directive = detectDirective(readFileSync(file, 'utf8'), file);
+    } catch {
+      directive = null;
+    }
+    cache.set(file, directive);
+    return directive;
+  };
+}
+
+/** Live-source error entry — the crawl's error vocabulary. */
+export interface LiveGraphError {
+  environment: 'scan';
+  id: string;
+  message: string;
+}
+
+export interface LiveProjectReport {
+  root: string;
+  modules: LiveModuleReport[];
+  errors: LiveGraphError[];
+}
+
+/**
+ * Classify every project source file from the live graphs. Files on
+ * disk that no graph reached get the §2 provisional/pending
+ * classification — on a lazily-warmed dev server that includes routes
+ * nobody has visited yet, which is honest: the graphs genuinely have
+ * not confirmed them.
+ */
+export async function classifyLiveProject(ctx: LiveGraphContext): Promise<LiveProjectReport> {
+  const files: string[] = [];
+  const errors: LiveProjectReport['errors'] = [];
+  const extensions = buildSourceExtensions(ctx.pageExtensions);
+  await scanProjectSourceFiles(
+    ctx.root,
+    files,
+    (failure: ScanFailure) =>
+      errors.push({ environment: 'scan', id: failure.dir, message: failure.message }),
+    0,
+    extensions
+  );
+  const modules: LiveModuleReport[] = [];
+  const getDirective = makeDirectiveReader();
+  for (const file of files) {
+    modules.push(await classifyLiveFile(file, ctx, getDirective, errors));
+  }
+  modules.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return { root: ctx.root, modules, errors };
+}

package/src/analyze/poison-rules.ts

@@ -0,0 +1,165 @@
+/**
+ * poison-rules — single source of truth for server-only / client-only
+ * module rules.
+ *
+ * Two tiers with different enforcement policies (design/47 §3):
+ *
+ * 1. **Explicit markers** (`server-only`, `client-only`) — evaluation-time
+ *    poison pills. `plugins/shims.ts` resolves them to virtual modules
+ *    whose body is a top-level `throw` in the wrong environment and a
+ *    silent no-op in the right one. The error fires when the module is
+ *    evaluated, not at resolve time.
+ *
+ * 2. **Inferred rules** (`node:*` imports, timber's ALS modules, browser
+ *    globals) — report-only. They have legitimate false positives
+ *    (`import.meta.env.SSR`-guarded `node:*` use, conditionally-imported
+ *    packages), so erroring the build on them would refuse working apps.
+ *    The `timber graph` reporter surfaces them as hints.
+ *
+ * Both shims.ts and the reporter consume this module so the two surfaces
+ * can never disagree. Promoting inferred rules to build errors is a
+ * policy flip on this list, never a new rule set.
+ *
+ * Design doc: 47-module-environment-tooling.md §3.
+ */
+
+import { isBuiltin } from 'node:module';
+
+/** Vite environment names the dev server / build run. */
+export type EnvironmentName = 'rsc' | 'ssr' | 'client';
+
+// ─── Tier 1: explicit markers (evaluation-time poison pills) ──────────────
+
+export interface ExplicitMarker {
+  /** The bare specifier user code imports (`server-only` / `client-only`). */
+  readonly specifier: string;
+  /** Virtual module ID the specifier resolves to in shims.ts. */
+  readonly virtualId: string;
+  /**
+   * True when evaluating the marker in `env` is a violation (the virtual
+   * module body must throw). `undefined` means "no environment context"
+   * (e.g. a non-environment-aware build) and is treated as a server
+   * environment — matching the historical shims.ts behavior.
+   */
+  readonly violatesIn: (env: EnvironmentName | string | undefined) => boolean;
+  /** Exact runtime error message thrown in the wrong environment. */
+  readonly errorMessage: string;
+  readonly enforcement: 'poison-pill';
+}
+
+export const EXPLICIT_MARKERS: readonly ExplicitMarker[] = [
+  {
+    specifier: 'server-only',
+    virtualId: '\0timber:server-only',
+    violatesIn: (env) => env === 'client',
+    errorMessage:
+      'This module cannot be imported from a Client Component module. ' +
+      'It should only be used from a Server Component.',
+    enforcement: 'poison-pill',
+  },
+  {
+    specifier: 'client-only',
+    virtualId: '\0timber:client-only',
+    violatesIn: (env) => env !== 'client',
+    errorMessage:
+      'This module cannot be imported from a Server Component module. ' +
+      'It should only be used from a Client Component.',
+    enforcement: 'poison-pill',
+  },
+];
+
+/**
+ * Look up an explicit marker by its import specifier. Throws on an
+ * unknown specifier — callers reference rules that must exist, and a
+ * silent undefined would just defer the failure.
+ */
+export function markerFor(specifier: string): ExplicitMarker {
+  const marker = EXPLICIT_MARKERS.find((m) => m.specifier === specifier);
+  if (!marker) throw new Error(`[timber] unknown poison marker: ${specifier}`);
+  return marker;
+}
+
+/**
+ * Generate the virtual module body for an explicit marker in `env`:
+ * a top-level throw in the wrong environment, a no-op otherwise.
+ */
+export function poisonPillSource(
+  marker: ExplicitMarker,
+  env: EnvironmentName | string | undefined
+): string {
+  if (marker.violatesIn(env)) {
+    return `throw new Error(${JSON.stringify(marker.errorMessage)});`;
+  }
+  return 'export {};';
+}
+
+// ─── Tier 2: inferred rules (report-only) ─────────────────────────────────
+
+export interface InferredRule {
+  readonly id: string;
+  /** Which exclusivity the signal implies for the containing module. */
+  readonly implies: 'server-only' | 'client-only';
+  readonly enforcement: 'report-only';
+  /** Human-readable description for reporter output. */
+  readonly description: string;
+  /** Import-specifier signal — matches static import sources. */
+  readonly matchesImport?: (specifier: string) => boolean;
+  /**
+   * Identifier signal — global names whose use implies the exclusivity.
+   * Consumers must apply shadow-safe matching (an allowlisted-position
+   * AST check, not a text search).
+   */
+  readonly identifiers?: readonly string[];
+}
+
+/**
+ * Timber modules that hold per-request AsyncLocalStorage state. Importing
+ * one from client-reachable code is a strong server-only signal — cf. the
+ * no-server-imports-in-isomorphic-define-modules rule.
+ */
+const ALS_MODULE_SPECIFIERS = new Set([
+  '@timber-js/app/server',
+  '@timber-js/app/server/internal',
+  '#server-internal',
+]);
+
+/**
+ * The ALS registry module itself, as it appears in import sources.
+ * Framework code imports it ESM-style with a `.js` specifier — both
+ * `../server/als-registry.js` and sibling `./als-registry.js` forms
+ * exist throughout src/server — while resolved module ids carry `.ts`.
+ * Matching any path ending in the basename is deliberate: the rule is
+ * report-only, and a user file coincidentally named als-registry is a
+ * far rarer event than a missed hint on the real one.
+ */
+const ALS_REGISTRY_SUFFIX = /(?:^|\/)als-registry\.(?:ts|js)$/;
+
+export const INFERRED_RULES: readonly InferredRule[] = [
+  {
+    id: 'node-builtin-import',
+    implies: 'server-only',
+    enforcement: 'report-only',
+    description: 'imports a node:* built-in module',
+    // Deliberately node:-prefixed only, matching design/47 §3's scope.
+    // Bare builtin names (`buffer`, `events`, `process`, `util`, …) are
+    // also real npm packages that browser code legitimately imports (the
+    // classic polyfill set) — matching them would report working client
+    // code, so they are intentionally NOT a signal.
+    matchesImport: (specifier) => specifier.startsWith('node:') && isBuiltin(specifier),
+  },
+  {
+    id: 'timber-als-module',
+    implies: 'server-only',
+    enforcement: 'report-only',
+    description: "imports timber's per-request AsyncLocalStorage modules",
+    matchesImport: (specifier) =>
+      ALS_MODULE_SPECIFIERS.has(specifier) || ALS_REGISTRY_SUFFIX.test(specifier),
+  },
+  {
+    id: 'browser-global',
+    implies: 'client-only',
+    enforcement: 'report-only',
+    description: 'references a browser-only global',
+    identifiers: ['window', 'document', 'navigator', 'localStorage', 'sessionStorage'],
+  },
+];

package/src/analyze/poison-scan.ts

@@ -0,0 +1,159 @@
+/**
+ * poison-scan — report-only poisoning detection for `timber graph`.
+ *
+ * Matches a module's static import specifiers against the shared rule
+ * lists in poison-rules.ts (the single source of truth — design/47 §3)
+ * and reports a poisoning only when the implied exclusivity CONFLICTS
+ * with where the module actually runs: a server-only signal in a
+ * client-reachable module, or a client-only signal in a server-reachable
+ * one. A `node:fs` import in a file only the RSC environment loads is
+ * working code, not a finding.
+ *
+ * Scope: import-specifier signals only (explicit markers + the inferred
+ * rules' `matchesImport`). The inferred browser-global identifier rules
+ * need shadow-safe allowlisted-position AST matching and are a separate
+ * ticket — reporting them from a text scan would flag legitimate code.
+ *
+ * Design docs: 47-module-environment-tooling.md §3.
+ */
+
+import { parseAst } from 'vite';
+import { EXPLICIT_MARKERS, INFERRED_RULES } from './poison-rules.ts';
+import { langForFile, PARSEABLE_EXTENSIONS, type ModuleKind } from './classify.ts';
+
+/** One poisoning finding on a module, in the JSON-contract shape. */
+export interface Poisoning {
+  /** Rule id — an inferred rule's id, or the explicit marker specifier. */
+  rule: string;
+  /** The import specifier that matched. */
+  specifier: string;
+  /** Which exclusivity the signal implies for the containing module. */
+  implies: 'server-only' | 'client-only';
+  /** Human-readable description for reporter output. */
+  description: string;
+}
+
+/**
+ * A NON-EMPTY specifier list where every entry is type-only. Empty or
+ * absent lists return false — a bare `import 'pkg'` is a side-effect
+ * import and very much runs.
+ */
+function isAllSpecifiersTypeOnly(
+  specifiers: Array<{ importKind?: string; exportKind?: string }> | undefined
+): boolean {
+  if (!specifiers || specifiers.length === 0) return false;
+  return specifiers.every((s) => s.importKind === 'type' || s.exportKind === 'type');
+}
+
+/**
+ * Collect every static import/export source and string-literal dynamic
+ * import from a module's original source. Sources that fail to parse
+ * (or are not JS/TS at all) return [] — no specifiers is a safe
+ * default for a report-only scan.
+ */
+export function collectImportSpecifiers(code: string, file: string): string[] {
+  if (!PARSEABLE_EXTENSIONS.test(file)) return [];
+  let program;
+  try {
+    // Language from the extension, never forced tsx — see langForFile.
+    program = parseAst(code, { lang: langForFile(file) });
+  } catch {
+    return [];
+  }
+  const specifiers: string[] = [];
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    if (typeof node !== 'object' || node === null) return;
+    const record = node as Record<string, unknown> & {
+      type?: string;
+      importKind?: string;
+      exportKind?: string;
+      specifiers?: Array<{ importKind?: string; exportKind?: string }>;
+    };
+    if (
+      (record.type === 'ImportDeclaration' ||
+        record.type === 'ExportNamedDeclaration' ||
+        record.type === 'ExportAllDeclaration') &&
+      // Type-only imports/exports are erased at runtime — `import type
+      // { Stats } from 'node:fs'` in client code is working code, and
+      // flagging it would be a false positive in a report-only scan.
+      // Covers both the declaration-level form (`import type {…}`,
+      // importKind on the declaration) and the inline form
+      // (`import { type Stats }`, where the declaration stays 'value'
+      // and each SPECIFIER carries the kind) — a declaration whose
+      // specifiers are all type-only is erased just the same.
+      record.importKind !== 'type' &&
+      record.exportKind !== 'type' &&
+      !isAllSpecifiersTypeOnly(record.specifiers) &&
+      typeof (record.source as { value?: unknown } | null)?.value === 'string'
+    ) {
+      specifiers.push((record.source as { value: string }).value);
+    } else if (
+      record.type === 'ImportExpression' &&
+      (record.source as { type?: string; value?: unknown })?.type === 'Literal' &&
+      typeof (record.source as { value?: unknown }).value === 'string'
+    ) {
+      specifiers.push((record.source as { value: string }).value);
+    }
+    for (const key of Object.keys(record)) {
+      if (key === 'type') continue;
+      visit(record[key]);
+    }
+  };
+  visit(program.body);
+  return specifiers;
+}
+
+/** Exclusivity signals a module's import specifiers carry. */
+export function importSignals(specifiers: string[]): Poisoning[] {
+  const signals: Poisoning[] = [];
+  for (const specifier of specifiers) {
+    for (const marker of EXPLICIT_MARKERS) {
+      if (specifier === marker.specifier) {
+        signals.push({
+          rule: marker.specifier,
+          specifier,
+          implies: marker.specifier === 'server-only' ? 'server-only' : 'client-only',
+          description: `imports the ${marker.specifier} poison-pill marker`,
+        });
+      }
+    }
+    for (const rule of INFERRED_RULES) {
+      if (rule.matchesImport?.(specifier)) {
+        signals.push({
+          rule: rule.id,
+          specifier,
+          implies: rule.implies,
+          description: rule.description,
+        });
+      }
+    }
+  }
+  return signals;
+}
+
+/**
+ * Filter a module's signals down to actual conflicts with its
+ * classification. Environment reach follows the taxonomy: boundary /
+ * client-internal / shared modules run client-side; server / shared /
+ * server-action modules run server-side. Pending (provisional) modules
+ * run nowhere confirmed, so nothing conflicts yet.
+ */
+export function poisoningsFor(
+  kind: ModuleKind,
+  pending: boolean,
+  signals: Poisoning[]
+): Poisoning[] {
+  if (pending || signals.length === 0) return [];
+  const clientReachable =
+    kind === 'client-boundary' || kind === 'client-internal' || kind === 'shared';
+  const serverReachable = kind === 'server' || kind === 'shared' || kind === 'server-action';
+  return signals.filter(
+    (signal) =>
+      (signal.implies === 'server-only' && clientReachable) ||
+      (signal.implies === 'client-only' && serverReachable)
+  );
+}