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

package/src/analyze/graph-command.ts

@@ -0,0 +1,762 @@
+/**
+ * graph-command — `timber graph <file> [--json] [--all --json]`.
+ *
+ * Answers "what environment(s) does this file run in?" by delegating
+ * to a running dev server when one is discovered (milliseconds), and
+ * falling back to the cold crawl + mtime-keyed cache otherwise
+ * (design/47 §5b). Dev-server responses are NOT cached in the mtime
+ * cache: live answers may include real browser-graph data.
+ *
+ * Config anchoring deliberately diverges from `check`/`build`: those
+ * discover the Vite config from the cwd ("the app here"), which is
+ * wrong for a file-addressed command invoked from a monorepo root —
+ * cwd anchoring would select the wrong app. `graph` walks UP from the
+ * target file's directory to the nearest Vite config and resolves from
+ * there, so the file's own app answers. `--config` overrides, same as
+ * everywhere else.
+ *
+ * Cold-path policy: a cold single-file query runs the full-project
+ * crawl (`--all` internally) and caches the entire report — one crawl
+ * per project state, every subsequent question a cache hit. The
+ * cache-hit path never imports Vite.
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, realpath, rm } from 'node:fs/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { DEV_DISCOVERY_DIR, isPidAlive, type DevRecord } from '../plugins/dev-discovery.ts';
+import {
+  collectBaseFingerprintEntries,
+  computeProjectFingerprint,
+  fingerprintEntriesForFiles,
+  hashFingerprintEntries,
+  readGraphCache,
+  writeGraphCache,
+  GRAPH_CACHE_VERSION,
+  GRAPH_JSON_VERSION,
+} from './graph-cache.ts';
+import type { CrawlReport, GraphModuleReport } from './crawl.ts';
+import type { ImportChain } from './chains.ts';
+import { normalizeSlashes } from './scan.ts';
+
+const execFileAsync = promisify(execFile);
+
+export type GraphSource = 'dev-server' | 'static-scan';
+
+/** Crawl deadline passed to the child, plus slack for its boot/exit. */
+const CRAWL_TIMEOUT_MS = 120_000;
+const SPAWN_SLACK_MS = 30_000;
+
+/**
+ * Short timeout for the dev-server probe: the fast path must not hold
+ * the fallback hostage if the server is wedged or the connection hangs.
+ */
+const DEV_PROBE_TIMEOUT_MS = 2_000;
+
+/**
+ * Vite's own default config file names, in Vite's precedence order.
+ * Matching the list (rather than globbing) keeps the walk-up aligned
+ * with what `createServer` would discover in each directory.
+ */
+const VITE_CONFIG_FILES = [
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.ts',
+  'vite.config.cjs',
+  'vite.config.mts',
+  'vite.config.cts',
+];
+
+export interface GraphOptions {
+  /** Target file; required unless `all`. */
+  file?: string;
+  /** Explicit Vite config path (overrides the walk-up discovery). */
+  config?: string;
+  json: boolean;
+  all: boolean;
+}
+
+/**
+ * Walk up from `startDir` to the nearest directory containing a Vite
+ * config file. Returns the config's absolute path, or null at the
+ * filesystem root.
+ */
+export function findViteConfigUpward(startDir: string): string | null {
+  let dir = startDir;
+  for (;;) {
+    for (const name of VITE_CONFIG_FILES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Max response body size (16 MB — matches the crawl child). */
+const PROBE_MAX_BODY_BYTES = 16 * 1024 * 1024;
+
+/**
+ * HTTP(S) GET with a wall-clock deadline and response-size limit,
+ * returning the parsed JSON body or null on any failure. Uses
+ * node:http/https directly — `fetch` silently strips the Host header,
+ * which the endpoint's DNS-rebinding defense needs to see as `localhost`.
+ *
+ * The wall-clock timer covers both connection and body streaming —
+ * node's `timeout` option is an INACTIVITY timeout that resets on every
+ * chunk, so a slow-drip response would never fire it.
+ */
+function probeEndpoint(record: DevRecord, path: string, timeoutMs: number): Promise<unknown> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value: unknown) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(wallClock);
+      resolve(value);
+    };
+
+    const probeHost =
+      record.host === '0.0.0.0' || record.host === '::' || record.host === ''
+        ? '127.0.0.1'
+        : record.host;
+    const doRequest = record.protocol === 'https' ? httpsRequest : httpRequest;
+    const req = doRequest(
+      {
+        hostname: probeHost,
+        port: record.port,
+        path,
+        method: 'GET',
+        // Self-signed certs are normal for dev servers.
+        rejectUnauthorized: false,
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          req.destroy();
+          done(null);
+          return;
+        }
+        const chunks: Buffer[] = [];
+        let totalBytes = 0;
+        res.on('data', (chunk: Buffer) => {
+          totalBytes += chunk.length;
+          if (totalBytes > PROBE_MAX_BODY_BYTES) {
+            req.destroy();
+            done(null);
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Record<
+              string,
+              unknown
+            >;
+            done(
+              parsed?.version === GRAPH_JSON_VERSION && parsed?.source === 'dev-server'
+                ? parsed
+                : null
+            );
+          } catch {
+            done(null);
+          }
+        });
+        res.on('error', () => done(null));
+      }
+    );
+    req.on('error', () => done(null));
+
+    const wallClock = setTimeout(() => {
+      req.destroy();
+      done(null);
+    }, timeoutMs);
+    req.end();
+  });
+}
+
+/**
+ * Try to delegate a graph query to a running dev server discovered via
+ * `.timber/dev/` records. Returns the parsed JSON response on success,
+ * null on any failure (missing dir, no live records, probe failure).
+ * Every failure mode is silent — the caller falls back to the cold crawl.
+ */
+async function tryDevServer(
+  configDir: string,
+  configFile: string,
+  queryString: string
+): Promise<unknown> {
+  const dir = join(configDir, DEV_DISCOVERY_DIR);
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    let record: DevRecord;
+    try {
+      record = JSON.parse(readFileSync(join(dir, entry), 'utf8')) as DevRecord;
+    } catch {
+      continue;
+    }
+    if (
+      typeof record.port !== 'number' ||
+      !Number.isInteger(record.port) ||
+      record.port < 1 ||
+      record.port > 65535 ||
+      typeof record.pid !== 'number' ||
+      !Number.isInteger(record.pid) ||
+      record.pid < 1 ||
+      typeof record.host !== 'string' ||
+      (record.protocol !== 'http' && record.protocol !== 'https')
+    ) {
+      continue;
+    }
+    // Skip records from a different Vite config (TIM-1393). Records
+    // without configFile (old servers) are accepted — rejecting them
+    // would break the fast path until every server restarts.
+    if (record.configFile && normalizeSlashes(record.configFile) !== normalizeSlashes(configFile))
+      continue;
+    if (!isPidAlive(record.pid)) continue;
+    let result: unknown;
+    try {
+      result = await probeEndpoint(record, `/__timber/graph${queryString}`, DEV_PROBE_TIMEOUT_MS);
+    } catch {
+      // http.request can throw synchronously on malformed hostnames
+      // (ERR_INVALID_CHAR) or other invalid options — treat as absent.
+      continue;
+    }
+    if (result) return result;
+  }
+  return null;
+}
+
+/**
+ * Resolve the app root from the config file's own directory, reading
+ * it off the timber root-sync plugin api (the single supported way —
+ * cf. cli-check.ts). Only runs on the cold path.
+ *
+ * Resolution uses SERVE/development semantics, not build's: the crawl
+ * child evaluates this same config through `createServer` (dev), and
+ * the dev-server fast path answers from dev graphs — the dev graphs
+ * are the tool's ground truth (design/47 §Motivation). Resolving the
+ * root under build mode while crawling under serve would let a
+ * command/mode-branching config select one app and crawl another.
+ */
+async function resolveAppRoot(
+  configFile: string
+): Promise<{ root: string; configFileDependencies: string[]; pageExtensions?: string[] }> {
+  const { resolveConfig } = await import('vite');
+  // Lazy for the same reason as Vite itself: plugin-context.ts has a
+  // module-level `parseAst` import from vite, so a static import here
+  // would make even warm cache hits pay Vite's startup cost — the
+  // cache-hit path must stay vite-free (design/47 §Cold-path policy).
+  const { isTimberPluginApi } = await import('../plugin-context.ts');
+  // Anchor Vite's cwd-relative defaults at the config's directory, not
+  // the caller's cwd — the whole point of the walk-up. The config's own
+  // explicit `root` option still wins over this cwd, as it should.
+  const previousCwd = process.cwd();
+  process.chdir(dirname(configFile));
+  // Route config-evaluation stdout to stderr for the duration: the
+  // app's config and plugin hooks run in THIS process, and any
+  // console.log from them would land in front of the --json contract,
+  // breaking JSON.parse(stdout) consumers. (The crawl child has the
+  // same problem solved by --out; this parent-side evaluation needs
+  // the equivalent.) Bind write() so its overloads keep their exact
+  // callback semantics.
+  const stdoutWrite = process.stdout.write;
+  process.stdout.write = process.stderr.write.bind(process.stderr) as typeof process.stdout.write;
+  try {
+    // TIMBER_ANALYZE and middlewareMode mirror the crawl child's boot:
+    // serve-mode config hooks otherwise start dev-only side effects in
+    // THIS process — the startup holding server binds the app's port
+    // and keeps the CLI alive forever (index.ts gates it on
+    // !middlewareMode), and platform dev plugins may open remote
+    // connections classification never needs.
+    process.env.TIMBER_ANALYZE = '1';
+    const {
+      plugins,
+      configFileDependencies,
+      resolve: resolveOptions,
+    } = await resolveConfig(
+      { configFile, logLevel: 'error', server: { middlewareMode: true } },
+      'serve',
+      'development',
+      'development'
+    );
+    const rootSync = plugins.find((plugin) => plugin.name === 'timber-root-sync');
+    if (!rootSync || !isTimberPluginApi(rootSync.api)) {
+      throw new Error(
+        `[timber] ${configFile} does not produce the timber plugin.\n` +
+          `  \`timber graph\` resolves the app through Vite so it classifies the same\n` +
+          `  modules the build builds. Check that the config lists timber():\n\n` +
+          `    import { timber } from '@timber-js/app';\n` +
+          `    export default { plugins: [timber()] };\n`
+      );
+    }
+    // Same path space as the crawl's report.root — the hit path
+    // fingerprints cache.report.root, so a divergent space here
+    // (backslashes, or symlink-vs-physical) would make miss- and
+    // hit-path entry strings differ and the cache never match. Vite
+    // does NOT realpath its resolved root; the crawl realpaths unless
+    // resolve.preserveSymlinks keeps graphs on symlink paths — mirror
+    // that decision from the same resolved config.
+    const { normalizePath } = await import('vite');
+    const pluginCtx = rootSync.api.getContext();
+    const rawRoot = pluginCtx.root;
+    return {
+      root: normalizePath(resolveOptions.preserveSymlinks ? rawRoot : await realpath(rawRoot)),
+      // A config helper imported from OUTSIDE the app root (a shared
+      // vite.shared.ts beside a monorepo config) can reshape aliases,
+      // plugins, or timber options without touching anything the disk
+      // scan sees — the fingerprint must track these too. Vite's list
+      // covers the vite.config bundle; timber.config.ts is require()d
+      // by root-sync during resolveConfig, so its transitive imports
+      // live in require.cache and are collected from there.
+      configFileDependencies: [...configFileDependencies, ...collectTimberConfigDeps()],
+      pageExtensions: pluginCtx.config.pageExtensions,
+    };
+  } finally {
+    process.stdout.write = stdoutWrite;
+    process.chdir(previousCwd);
+  }
+}
+
+/**
+ * Transitive dependencies of the loaded timber.config, from
+ * require.cache: `loadTimberConfigFile` loads the config with native
+ * require() (design/11 §Config Loading Semantics), so after
+ * resolveConfig has run the config module and everything it imported —
+ * including helpers OUTSIDE the app root that Vite's
+ * configFileDependencies cannot see — sit in the cache with their
+ * children recorded. node_modules entries are skipped (the lockfile
+ * fingerprint covers them).
+ */
+function collectTimberConfigDeps(): string[] {
+  const require = createRequire(import.meta.url);
+  const cache = require.cache ?? {};
+  const roots = Object.values(cache).filter(
+    (mod): mod is NonNullable<typeof mod> =>
+      mod != null && /timber\.config\.(?:ts|js|mjs)$/.test(mod.filename)
+  );
+  const deps: string[] = [];
+  const seen = new Set<string>();
+  const queue = [...roots];
+  while (queue.length > 0) {
+    const mod = queue.shift()!;
+    if (seen.has(mod.filename)) continue;
+    seen.add(mod.filename);
+    if (mod.filename.includes(`${sep}node_modules${sep}`)) continue;
+    deps.push(mod.filename);
+    queue.push(...mod.children);
+  }
+  return deps;
+}
+
+/**
+ * Locate the crawl child entry beside this module: the built `.js` in
+ * a published install, the `.ts` source under tsx (tests, this repo).
+ */
+function resolveCrawlEntry(): { entry: string; nodeArgs: string[] } {
+  const jsEntry = fileURLToPath(new URL('./crawl-entry.js', import.meta.url));
+  if (existsSync(jsEntry)) return { entry: jsEntry, nodeArgs: [] };
+  const tsEntry = fileURLToPath(new URL('./crawl-entry.ts', import.meta.url));
+  return { entry: tsEntry, nodeArgs: ['--import', 'tsx/esm'] };
+}
+
+/** Spawn the crawl child and read its report from the --out file. */
+async function runColdCrawl(root: string, configFile: string): Promise<CrawlReport> {
+  const { entry, nodeArgs } = resolveCrawlEntry();
+  const outFile = join(root, '.timber', `graph-crawl-${process.pid}.json`);
+  await mkdir(dirname(outFile), { recursive: true });
+  try {
+    await execFileAsync(
+      process.execPath,
+      [
+        ...nodeArgs,
+        entry,
+        '--root',
+        root,
+        '--config',
+        configFile,
+        '--out',
+        outFile,
+        '--timeout',
+        String(CRAWL_TIMEOUT_MS),
+      ],
+      {
+        // Same cwd anchor as resolveAppRoot: a config that derives
+        // options from process.cwd() must evaluate identically in the
+        // resolution that selected the app and in the crawl that
+        // classifies it, or the two describe different apps. The app
+        // root still reaches the child explicitly via --root.
+        cwd: dirname(configFile),
+        // The child's BFS deadline handles hung transforms; this spawn
+        // timeout is the outer guard for a hang in createServer itself,
+        // which the deadline cannot cover (see crawl-entry.ts).
+        timeout: CRAWL_TIMEOUT_MS + SPAWN_SLACK_MS,
+        maxBuffer: 16 * 1024 * 1024,
+      }
+    );
+    return JSON.parse(await readFile(outFile, 'utf8')) as CrawlReport;
+  } finally {
+    await rm(outFile, { force: true }).catch(() => {});
+  }
+}
+
+interface GraphAnswer {
+  report: CrawlReport;
+  configFile: string;
+  cached: boolean;
+}
+
+/**
+ * Produce the full-project report: cache hit when the fingerprint
+ * matches, cold crawl otherwise.
+ *
+ * The scan-derived base entries are computed BEFORE the crawl — files
+ * changing mid-crawl make the next query miss, never the reverse. The
+ * `trackedExtras` (config dependencies + every file the report
+ * classifies) are only knowable after resolution and crawl, so their
+ * entries are stat'd afterwards; for those alone, a mid-crawl edit is
+ * stale-until-the-next-edit rather than an immediate miss.
+ */
+async function loadReport(configFile: string): Promise<GraphAnswer> {
+  // The cache is anchored at the config file's directory, NOT the
+  // resolved Vite root: knowing the root requires resolveConfig (which
+  // imports Vite), and the entire point of the hit path is answering
+  // without it. Reading and writing must use the same anchor — a split
+  // (read here, write under the resolved root) would never hit for a
+  // config whose `root` points elsewhere, silently re-crawling forever.
+  const cacheDir = dirname(configFile);
+  const cache = await readGraphCache(cacheDir);
+  if (cache && cache.configFile === configFile) {
+    const fingerprint = await computeProjectFingerprint(
+      cache.report.root,
+      configFile,
+      cache.trackedExtras,
+      cache.pageExtensions
+    );
+    if (fingerprint === cache.fingerprint) {
+      return { report: cache.report, configFile, cached: true };
+    }
+  }
+
+  const { root, configFileDependencies, pageExtensions } = await resolveAppRoot(configFile);
+  const baseEntries = await collectBaseFingerprintEntries(root, configFile, pageExtensions);
+  process.stderr.write('[timber] graph cache miss — cold project crawl (~2.5–10 s)\n');
+  // Config-dependency entries are snapshotted BEFORE the crawl, like
+  // the base entries: a config helper edited during the multi-second
+  // crawl must make the next query miss, not be stamped post-crawl
+  // with its new mtime beside a report built from its old contents.
+  const configDepEntries = await fingerprintEntriesForFiles(configFileDependencies);
+  const report = await runColdCrawl(root, configFile);
+  if (report.incomplete) {
+    // Deadline-truncated report: transient (slow machine, cold dep
+    // optimizer). Serve it — a truncated answer now beats none — but
+    // never cache it: with unchanged files it would be served forever,
+    // with no retry after the transient cause cleared.
+    process.stderr.write('[timber] crawl hit its deadline — serving truncated, uncached report\n');
+    return { report, configFile, cached: false };
+  }
+  const trackedExtras = [
+    ...new Set([...configFileDependencies, ...report.modules.map((m) => m.file)]),
+  ].sort();
+  // Report-file entries can only be stat'd post-crawl (the set is
+  // unknowable before); for those alone a mid-crawl edit is stale-
+  // until-next-edit. Files already covered pre-crawl (scan overlap,
+  // config deps) keep their pre-crawl entries — hashFingerprintEntries
+  // dedupes identical strings, and a mid-crawl edit produces a
+  // DIFFERENT post-crawl entry for the same path, which changes the
+  // hash and correctly misses on the next query.
+  const reportFileEntries = await fingerprintEntriesForFiles(report.modules.map((m) => m.file));
+  const fingerprint = hashFingerprintEntries([
+    ...baseEntries,
+    ...configDepEntries,
+    ...reportFileEntries,
+  ]);
+  await writeGraphCache(cacheDir, {
+    version: GRAPH_CACHE_VERSION,
+    fingerprint,
+    configFile,
+    pageExtensions,
+    trackedExtras,
+    report,
+  });
+  return { report, configFile, cached: false };
+}
+
+/** Project-relative display path (JSON always stays absolute). */
+function displayPath(file: string, root: string): string {
+  const rel = relative(root, file);
+  return rel.startsWith('..') ? file : rel;
+}
+
+/**
+ * Crawl errors that bear on one file's answer: failures on the file
+ * itself (recorded by path or by root-relative URL) plus scan-level
+ * failures, which undermine completeness for every file. Without this,
+ * a target whose own transform failed would print a confident `server`
+ * classification while only `--all` exposed the error (codex review,
+ * PR #1056).
+ */
+function errorsForTarget(report: CrawlReport, target: string): CrawlReport['errors'] {
+  const asUrl = '/' + relative(report.root, target).split('\\').join('/');
+  return report.errors.filter(
+    (error) => error.environment === 'scan' || error.id === target || error.id === asUrl
+  );
+}
+
+async function printSingleFile(
+  input: string,
+  target: string,
+  module: GraphModuleReport,
+  answer: GraphAnswer,
+  json: boolean
+): Promise<void> {
+  const errors = errorsForTarget(answer.report, target);
+  if (json) {
+    console.log(
+      JSON.stringify({
+        version: GRAPH_JSON_VERSION,
+        source: 'static-scan' satisfies GraphSource,
+        cached: answer.cached,
+        target: { input, resolved: target },
+        kind: module.kind,
+        pending: module.pending,
+        subtreeUnknown: module.subtreeUnknown,
+        envs: module.envs,
+        boundary: module.boundary,
+        chains: module.chains,
+        poisonings: module.poisonings,
+        errors,
+      })
+    );
+    return;
+  }
+
+  const root = answer.report.root;
+  const envs = Object.entries(module.envs)
+    .filter(([, present]) => present)
+    .map(([env]) => env);
+  console.log(
+    `${displayPath(target, root)} — ${module.kind}` +
+      `${module.pending ? ' (pending: no graph has confirmed this file yet)' : ''}`
+  );
+  console.log(`  source: static-scan${answer.cached ? ' (cached)' : ''}`);
+  console.log(`  environments: ${envs.length > 0 ? envs.join(', ') : 'none'}`);
+  if (module.subtreeUnknown) {
+    console.log('  note: reachable, but its subtree is unknown (never transformed)');
+  }
+  if (module.chains.length > 0) {
+    // Lazy import: the text formatter pulls Vite (normalizePath); the
+    // JSON path above must stay import-free for fast cache hits.
+    const { formatChains } = await import('./chains.ts');
+    console.log('  import chains:');
+    console.log(formatChains(module.chains, root));
+  }
+  for (const poisoning of module.poisonings) {
+    console.log(
+      `  poisoning: ${poisoning.description} (${poisoning.specifier}) — ` +
+        `implies ${poisoning.implies}`
+    );
+  }
+  for (const error of errors) {
+    console.log(`  error [${error.environment}]: ${error.message} (${error.id})`);
+  }
+}
+
+/**
+ * The single-file JSON contract shape for dev-server responses. Shared
+ * between the HTTP endpoint (graph-endpoint.ts) and this consumer so
+ * the boundary crossing is typed, not cast. The endpoint produces this
+ * shape; `probeEndpoint` parses it; `printDevServerText` formats it.
+ */
+interface DevServerFileResponse {
+  version: number;
+  source: string;
+  cached: boolean;
+  target: { input: string; resolved: string };
+  kind: string;
+  pending: boolean;
+  subtreeUnknown: boolean;
+  envs: Record<string, boolean>;
+  boundary: boolean;
+  chains: ImportChain[];
+  poisonings: Array<{ description: string; specifier: string; implies: string }>;
+  errors: Array<{ environment: string; message: string; id: string }>;
+}
+
+/**
+ * Text-mode output for a dev-server response. The response carries the
+ * same fields as the static-scan JSON, so the formatting mirrors
+ * `printSingleFile` with `source: "dev-server"`.
+ */
+async function printDevServerText(data: DevServerFileResponse, configDir: string): Promise<void> {
+  console.log(
+    `${displayPath(data.target.resolved, configDir)} — ${data.kind}` +
+      `${data.pending ? ' (pending: no graph has confirmed this file yet)' : ''}`
+  );
+  console.log('  source: dev-server');
+  const envList = Object.entries(data.envs)
+    .filter(([, present]) => present)
+    .map(([env]) => env);
+  console.log(`  environments: ${envList.length > 0 ? envList.join(', ') : 'none'}`);
+  if (data.subtreeUnknown) {
+    console.log('  note: reachable, but its subtree is unknown (never transformed)');
+  }
+  if (data.chains.length > 0) {
+    const { formatChains } = await import('./chains.ts');
+    console.log('  import chains:');
+    console.log(formatChains(data.chains, configDir));
+  }
+  for (const poisoning of data.poisonings) {
+    console.log(
+      `  poisoning: ${poisoning.description} (${poisoning.specifier}) — ` +
+        `implies ${poisoning.implies}`
+    );
+  }
+  for (const error of data.errors) {
+    console.log(`  error [${error.environment}]: ${error.message} (${error.id})`);
+  }
+}
+
+/**
+ * Run `timber graph`. Throws with actionable messages; the CLI's main()
+ * prints and exits nonzero.
+ */
+export async function runGraph(options: GraphOptions): Promise<void> {
+  if (options.all && !options.json) {
+    throw new Error(
+      'timber graph --all requires --json (no text format is defined for the full project).'
+    );
+  }
+  let target: { input: string; candidates: string[] } | null = null;
+  if (options.file) {
+    const resolved = resolve(process.cwd(), options.file);
+    if (!existsSync(resolved)) {
+      throw new Error(`[timber] file not found: ${resolved}`);
+    }
+    // Report paths are slash-normalized (normalizeSlashes) and usually
+    // realpaths — but under resolve.preserveSymlinks the graphs keep
+    // symlink paths. Look up BOTH forms rather than guessing the
+    // config's setting (the hit path is vite-free and cannot ask):
+    // as-typed first, realpath second.
+    const asTyped = normalizeSlashes(resolved);
+    const physical = normalizeSlashes(await realpath(resolved));
+    target = {
+      input: options.file,
+      candidates: asTyped === physical ? [asTyped] : [asTyped, physical],
+    };
+  }
+  if (!options.all && !target) {
+    throw new Error('Usage: timber graph <file> [--json], or timber graph --all --json');
+  }
+
+  // Anchor config discovery at the AS-TYPED path (candidates[0]): under
+  // preserveSymlinks a symlinked target's realpath may live in a
+  // sibling workspace package, and walking up from there would select
+  // that package's config — or none — instead of the app the user
+  // addressed. The realpath candidate exists only for module lookup.
+  const anchor = target ? dirname(target.candidates[0]) : process.cwd();
+  const configFile = options.config
+    ? resolve(process.cwd(), options.config)
+    : findViteConfigUpward(anchor);
+  if (!configFile || !existsSync(configFile)) {
+    throw new Error(
+      `[timber] no Vite config found walking up from ${anchor}.\n` +
+        `  \`timber graph\` anchors config discovery at the target file (not the cwd)\n` +
+        `  so the file's own app answers in a monorepo. Pass --config <path> to override.`
+    );
+  }
+
+  // Fast path: delegate to a running dev server if one is discovered.
+  // The query string mirrors the endpoint's contract — `?file=` for
+  // single-file, `?all=1` for the full project. The endpoint returns
+  // the same JSON contract the CLI prints, so on success the response
+  // is printed verbatim (JSON mode) or decoded and formatted (text).
+  // TIMBER_ANALYZE=1 suppresses delegation: the crawl child sets it
+  // to skip dev-server side effects, and it also prevents the child
+  // from discovering and probing the parent dev server's own endpoint.
+  const configDir = dirname(configFile);
+  const delegate = process.env.TIMBER_ANALYZE !== '1';
+  if (delegate && options.all) {
+    const live = await tryDevServer(configDir, configFile, '?all=1');
+    if (live) {
+      // --json is already guaranteed by the guard at the top.
+      console.log(JSON.stringify(live));
+      return;
+    }
+  } else if (delegate && target) {
+    // The endpoint accepts absolute paths — pass the as-typed candidate
+    // (matching the CLI's own config anchoring, not the realpath).
+    const live = await tryDevServer(
+      configDir,
+      configFile,
+      `?file=${encodeURIComponent(target.candidates[0])}`
+    );
+    if (live) {
+      if (options.json) {
+        // Preserve the user's original input (e.g. "app/page.tsx") —
+        // the endpoint echoes the absolute path we sent as target.input,
+        // which would differ from the cold path's relative input.
+        const liveObj = live as Record<string, unknown>;
+        if (typeof liveObj.target === 'object' && liveObj.target !== null) {
+          (liveObj.target as Record<string, unknown>).input = target.input;
+        }
+        console.log(JSON.stringify(liveObj));
+        return;
+      }
+      // The endpoint produces DevServerFileResponse by construction —
+      // both frontends use the same classification pipeline. This is
+      // the HTTP JSON boundary: probeEndpoint returns `unknown` from
+      // JSON.parse; we narrow here because the endpoint's shape is our
+      // own contract, not third-party data.
+      await printDevServerText(live as DevServerFileResponse, configDir);
+      return;
+    }
+  }
+
+  // Cold path: mtime-keyed cache, then crawl.
+  const answer = await loadReport(configFile);
+
+  if (options.all) {
+    console.log(
+      JSON.stringify({
+        version: GRAPH_JSON_VERSION,
+        source: 'static-scan' satisfies GraphSource,
+        cached: answer.cached,
+        root: answer.report.root,
+        configFile: answer.configFile,
+        modules: answer.report.modules,
+        errors: answer.report.errors,
+        stats: answer.report.stats,
+      })
+    );
+    return;
+  }
+
+  if (!target) {
+    // Unreachable — validated at the top; kept for type narrowing.
+    throw new Error('Usage: timber graph <file> [--json]');
+  }
+  const candidates = target.candidates;
+  const module = answer.report.modules.find((m) => candidates.includes(m.file));
+  if (!module) {
+    throw new Error(
+      `[timber] ${candidates[0]} is not part of the app at ${answer.report.root}\n` +
+        `  (resolved from ${configFile}). Only project source files inside the app\n` +
+        `  root are classified — node_modules and non-source files are not.`
+    );
+  }
+  await printSingleFile(target.input, module.file, module, answer, options.json);
+}