@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/plugin-context.ts

@@ -0,0 +1,503 @@
+/**
+ * Plugin context — internal types and helpers for timber sub-plugins.
+ *
+ * These are NOT part of the user-facing API. They are consumed by
+ * sub-plugins (routing, entries, shims, etc.) via relative imports.
+ * The root entry point (index.ts) does not re-export them.
+ *
+ * Design doc: 18-build-system.md §"Shared Plugin Context"
+ */
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { parseAst } from 'vite';
+import type { RouteTree } from './routing/types.ts';
+import type { BuildManifest } from './server/build-manifest.ts';
+import type { CaptureSummary } from './server/prebuilt-builder.ts';
+import type { StartupTimer } from './utils/startup-timer.ts';
+import { createStartupTimer } from './utils/startup-timer.ts';
+import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.ts';
+import type { RscManifest } from './plugins/static-build.ts';
+import type { HoldingServer } from './dev-tools/holding-server.ts';
+import type { ProgramNode } from './plugins/callsite-ast.ts';
+
+// Re-export for sub-plugin convenience — they import from plugin-context.ts
+export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.ts';
+
+// ── Client JavaScript config ─────────────────────────────────────────────
+
+/** Fully resolved client JavaScript configuration (no optionals). */
+export interface ResolvedClientJavascript {
+  disabled: boolean;
+  enableHMRInDev: boolean;
+}
+
+/**
+ * Resolve `clientJavascript` into a fully resolved config.
+ */
+export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
+  if (config.clientJavascript !== undefined) {
+    if (typeof config.clientJavascript === 'boolean') {
+      return {
+        disabled: !config.clientJavascript,
+        enableHMRInDev: !config.clientJavascript,
+      };
+    }
+    return {
+      disabled: config.clientJavascript.disabled,
+      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
+    };
+  }
+  return { disabled: false, enableHMRInDev: false };
+}
+
+// ── Plugin Context ────────────────────────────────────────────────────────
+
+/**
+ * Shared context object passed to all sub-plugins via closure.
+ *
+ * Sub-plugins communicate through this context — not through Vite's
+ * plugin API or global state.
+ * See design/18-build-system.md §"Shared Plugin Context".
+ */
+export interface PluginContext {
+  config: TimberUserConfig;
+  /** Resolved client JavaScript configuration */
+  clientJavascript: ResolvedClientJavascript;
+  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
+  routeTree: RouteTree | null;
+  /** Absolute path to the app/ directory */
+  appDir: string;
+  /** Absolute path to the project root */
+  root: string;
+  /** Whether the dev server is running (set by timber-root-sync in configResolved) */
+  dev: boolean;
+  /**
+   * Vite's resolved `base` (set by timber-root-sync in configResolved).
+   * Always has a trailing slash; `'/'` unless the app is deployed under a
+   * sub-path. Every URL the framework emits — assets, fonts, RSC payloads —
+   * carries this prefix. This is the single copy: sub-plugins read it here
+   * rather than capturing `config.base` in their own configResolved.
+   *
+   * **Availability:** written by timber-root-sync, which has no `enforce`, so
+   * it is populated from `buildStart`/`load`/`generateBundle`/`configureServer`
+   * onward — but NOT during the `configResolved` of an `enforce: 'pre'`
+   * plugin, which Vite runs first. A pre plugin that needs the base inside
+   * its own `configResolved` must read `config.base` there (timber-fonts
+   * does). See TIM-1261.
+   */
+  base: string;
+  /** CSS build manifest (populated by adapter after client build, null in dev) */
+  buildManifest: BuildManifest | null;
+  /** Per-build deployment ID for version skew detection (null in dev) */
+  deploymentId: string | null;
+  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
+  timer: StartupTimer;
+  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */
+  holdingServer?: HoldingServer | null;
+  /**
+   * Resolved absolute path to the build output directory.
+   *
+   * Defaults to `<root>/.timber/dist`. Can be overridden via
+   * `timber.config.ts` `buildDir` or Vite's `build.outDir`.
+   * Timber config takes precedence when both are set.
+   *
+   * Used by adapter-build and cli preview.
+   */
+  buildDir: string;
+  /**
+   * Per-route client reference keys captured during the RSC build.
+   * Maps absolute route file paths to the set of client reference
+   * hash keys they transitively import. Used by adapter-build to
+   * populate per-route modulepreload entries from clientReferenceDeps.
+   */
+  routeClientRefKeys?: Map<string, Set<string>>;
+  /**
+   * Static request-dependency verdict per segment entry file, keyed by the
+   * absolute `filePath` the route scanner produced. Computed once by
+   * `timber-request-dep`'s RSC `buildEnd` and serialized into
+   * `buildManifest.requestDep` by `timber-build-manifest` (build only — dev
+   * answers the same question through the `Symbol.for('timber:request-dep')`
+   * bridge instead).
+   *
+   * `undefined` and `{}` are different states and the difference is the whole
+   * of TIM-1300: an empty object means the analysis ran and found no segments,
+   * `undefined` means it never ran, and the runtime cannot tell them apart —
+   * every key is absent either way, so every segment falls to the conservative
+   * `true` and nothing is ever skipped. The build fails loudly on `undefined`
+   * rather than shipping that silently.
+   */
+  requestDepMap?: Record<string, boolean>;
+  /**
+   * Maps absolute module IDs of client references in non-facade RSC
+   * chunks to the absolute paths of their consuming facade modules.
+   * Built during the RSC `generateBundle` phase by timber-chunks,
+   * consumed by `clientChunkGroup` to reclassify `shared:` modules
+   * that are only used by a single route boundary.
+   * See design/27-chunking-strategy.md, TIM-1107.
+   */
+  sharedModuleFacades?: Map<string, string[]>;
+  /**
+   * Module ID → prebuilt component IDs declared in it. Recorded by the
+   * timber-prebuilt transform (RSC environment, production builds only),
+   * consumed by the RSC `generateBundle` module-graph walk that computes
+   * `routePrebuiltComponents`. See design/44-render-at-build-time.md.
+   */
+  prebuiltModuleComponents?: Map<string, string[]>;
+  /**
+   * Module ID → mapping of variable name to component ID for the prebuilt
+   * components declared in that module. Used at `generateBundle` time to
+   * trace imports from other modules back to specific component IDs.
+   */
+  prebuiltBindingNames?: Map<string, Map<string, string>>;
+  /**
+   * Component ID → distinct static call-site prop objects captured from
+   * JSX usage sites during the transform and generateBundle phases.
+   * Consumed by the post-build capture pass to render with actual props
+   * instead of empty `{}`. See design/44 §Props Derivation.
+   */
+  prebuiltCallSiteProps?: Map<string, Record<string, unknown>[]>;
+  /**
+   * Route file path (page or layout, absolute) → prebuilt component IDs
+   * transitively reachable from it. Computed during RSC `generateBundle`,
+   * consumed by the post-build capture pass (TIM-1119) to decide which
+   * components to render under which route's param combos.
+   */
+  routePrebuiltComponents?: Map<string, string[]>;
+  /**
+   * Page file paths that were desugared from `export const prerender` by
+   * timber-prerender-sugar. The prebuilt transform uses this to verify
+   * the generated `cache.component(...)` call was picked up.
+   */
+  prerenderSugarPages?: Set<string>;
+  /**
+   * Component ID → built chunk file name for prebuilt-declaring modules
+   * that are only reachable via dynamic imports (import.meta.glob, lazy
+   * routes). The capture pass imports these chunks to trigger
+   * cache.component() registration before rendering. Populated during
+   * RSC generateBundle alongside routePrebuiltComponents.
+   */
+  prebuiltLazyChunks?: Map<string, string>;
+  /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */
+  captureSummary?: CaptureSummary;
+  /**
+   * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
+   * transforms. Collapses both cross-plugin and cross-environment duplicate
+   * parses: identical code hits, rewritten code misses (correct because Vite
+   * transforms chain — a rewrite produces different code). Bounded LRU (32
+   * entries) so it doesn't hold programs for the whole build.
+   *
+   * Consumers MUST treat the returned ProgramNode as read-only — they collect
+   * ranges and rewrite CODE via MagicString; the AST itself is never mutated.
+   */
+  parseCached?: ParseMemo;
+  /**
+   * Content-Type mappings for extensionless static API route outputs.
+   * Populated during static generation, consumed by adapter-build to
+   * write per-path Content-Type rules in _headers. See TIM-1241.
+   */
+  staticContentTypes?: Record<string, string>;
+  /**
+   * RSC flight payload manifest mapping unhashed → hashed URLs.
+   * Populated during static generation, consumed by adapters to set
+   * immutable cache headers for `_rsc/` files. See TIM-1254.
+   */
+  rscManifest?: RscManifest;
+}
+
+// ── AST parse memo ───────────────────────────────────────────────────────
+
+const PARSE_MEMO_CAPACITY = 32;
+
+/**
+ * Content-keyed LRU memo for `parseAst`. Transforms for the same module run
+ * back-to-back across plugins and environments, so a tiny window captures the
+ * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.
+ */
+export class ParseMemo {
+  private cache = new Map<string, ProgramNode>();
+
+  /**
+   * Parse code, returning a cached ProgramNode if the same code was parsed
+   * before. The returned AST MUST NOT be mutated — it may be shared across
+   * multiple consumers.
+   */
+  parse(code: string): ProgramNode {
+    const existing = this.cache.get(code);
+    if (existing) {
+      // LRU refresh: move to end
+      this.cache.delete(code);
+      this.cache.set(code, existing);
+      return existing;
+    }
+    const program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+    if (this.cache.size >= PARSE_MEMO_CAPACITY) {
+      // Evict oldest (first inserted)
+      const firstKey = this.cache.keys().next().value!;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(code, program);
+    return program;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+// ── App directory resolution ──────────────────────────────────────────────
+
+// ── Plugin API (Vite `plugin.api`) ────────────────────────────────────────
+
+/**
+ * What `timber-root-sync` publishes on its Vite `plugin.api`.
+ *
+ * The single supported way to read timber's *resolved* configuration from
+ * outside the plugin pipeline. Re-reading `timber.config.ts` is not equivalent:
+ * config passed inline as `timber({ ... })` in `vite.config.ts` exists only in
+ * the plugin's closure, and `root`/`appDir` are resolved against Vite's root
+ * rather than the caller's cwd.
+ */
+export interface TimberPluginApi {
+  /** The live plugin context. Fully populated from `configResolved` onward. */
+  getContext(): PluginContext;
+}
+
+/** Narrow an unknown Vite `plugin.api` to timber's. */
+export function isTimberPluginApi(api: unknown): api is TimberPluginApi {
+  return (
+    typeof api === 'object' &&
+    api !== null &&
+    'getContext' in api &&
+    typeof api.getContext === 'function'
+  );
+}
+
+/**
+ * Resolve the app directory. Checks (in order):
+ * 1. Explicit `configAppDir` from timber.config.ts
+ * 2. `<root>/app`
+ * 3. `<root>/src/app`
+ *
+ * Throws if none exist.
+ */
+export function resolveAppDir(root: string, configAppDir?: string): string {
+  if (configAppDir) {
+    const explicit = join(root, configAppDir);
+    if (!existsSync(explicit)) {
+      throw new Error(`[timber] Configured appDir "${configAppDir}" does not exist at ${explicit}`);
+    }
+    return explicit;
+  }
+
+  const rootApp = join(root, 'app');
+  if (existsSync(rootApp)) return rootApp;
+
+  const srcApp = join(root, 'src', 'app');
+  if (existsSync(srcApp)) return srcApp;
+
+  throw new Error(
+    `[timber] Could not find app directory. Expected "app/" or "src/app/" in ${root}. ` +
+      `You can set appDir in timber.config.ts to specify a custom location.`
+  );
+}
+
+// ── Plugin context factory ────────────────────────────────────────────────
+
+export function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
+  const projectRoot = root ?? process.cwd();
+  const resolvedConfig: TimberUserConfig = { ...config };
+  return {
+    config: resolvedConfig,
+    clientJavascript: resolveClientJavascript(resolvedConfig),
+    routeTree: null,
+    appDir: join(projectRoot, 'app'),
+    root: projectRoot,
+    dev: false,
+    base: '/',
+    buildManifest: null,
+    deploymentId: null,
+    timer: createStartupTimer(),
+    holdingServer: null,
+    buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+    parseCached: new ParseMemo(),
+  };
+}
+
+// ── Build directory resolution ────────────────────────────────────────────
+
+/** Default build output directory (relative to root). */
+export const DEFAULT_BUILD_DIR = join('.timber', 'dist');
+
+/**
+ * Resolve the build output directory.
+ *
+ * Priority:
+ * 1. Explicit `timberBuildDir` from timber.config.ts
+ * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')
+ * 3. Default: `.timber/dist`
+ *
+ * Returns an absolute path.
+ */
+export function resolveBuildDir(
+  root: string,
+  timberBuildDir?: string,
+  viteBuildOutDir?: string
+): string {
+  if (timberBuildDir) {
+    return resolve(root, timberBuildDir);
+  }
+  if (viteBuildOutDir && viteBuildOutDir !== 'dist') {
+    return resolve(root, viteBuildOutDir);
+  }
+  return join(root, DEFAULT_BUILD_DIR);
+}
+
+// ── Config file loading ───────────────────────────────────────────────────
+
+/**
+ * Map known timber.config load failures to actionable hints (TIM-1040).
+ * Returns null when the error has no known remedy beyond its own message.
+ *
+ * Known failure modes of loading timber.config.ts via native require():
+ * - Node < 22.18 has no default type stripping → ERR_UNKNOWN_FILE_EXTENSION
+ * - Non-erasable TS syntax (enums, namespaces, parameter properties)
+ *   → ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX / ERR_INVALID_TYPESCRIPT_SYNTAX
+ * - ESM syntax in a `"type": "commonjs"` package → the stripped .ts is
+ *   parsed as CJS and throws SyntaxError: "Unexpected token 'export'"
+ *   (export statements) or "Cannot use import statement outside a
+ *   module" (import statements)
+ */
+export function configLoadHint(configName: string, err: unknown): string | null {
+  const code = (err as NodeJS.ErrnoException | null)?.code;
+  const isTs = configName.endsWith('.ts');
+
+  if (isTs && code === 'ERR_UNKNOWN_FILE_EXTENSION') {
+    return (
+      'Loading a TypeScript config requires Node.js 22.18+ (built-in type stripping). ' +
+      'Upgrade Node.js or rewrite the config as timber.config.js.'
+    );
+  }
+  if (code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX' || code === 'ERR_INVALID_TYPESCRIPT_SYNTAX') {
+    return (
+      'Node.js loads the config with type stripping, which only supports erasable TypeScript syntax — ' +
+      'replace enums, namespaces, and constructor parameter properties with plain objects and types.'
+    );
+  }
+  if (
+    isTs &&
+    err instanceof SyntaxError &&
+    /Unexpected token '(export|import)'|Cannot use import statement outside a module/.test(
+      err.message
+    )
+  ) {
+    return (
+      'The config uses ESM syntax but Node.js parsed it as CommonJS — ' +
+      'set "type": "module" in package.json, or use module.exports instead of export default.'
+    );
+  }
+  return null;
+}
+
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ * Throws a descriptive error naming the file when a config file exists
+ * but fails to load — a broken config must fail loudly, never silently
+ * degrade (see TIM-1066). Known failure modes get an actionable hint
+ * appended (see configLoadHint, TIM-1040).
+ *
+ * Uses require() — Node 22.12+ can require() ESM modules, and Node
+ * 22.18+ strips types from .ts files by default (hence the engines
+ * field requiring >=22.18.0). This keeps timber() synchronous — no
+ * async config loading needed.
+ * This is the single config loader — dev, build, and preview all use it.
+ */
+export function loadTimberConfigFile(root: string): TimberUserConfig | null {
+  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  const req = createRequire(join(root, 'package.json'));
+
+  for (const name of configNames) {
+    const configPath = join(root, name);
+    if (existsSync(configPath)) {
+      try {
+        const mod = req(configPath);
+        return (mod.default ?? mod) as TimberUserConfig;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const hint = configLoadHint(name, err);
+        throw new Error(
+          `[timber] Failed to load ${configPath}: ${message}${hint ? `\n${hint}` : ''}`,
+          { cause: err }
+        );
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
+ * and warn the user. The `output` key is excluded because it defaults to 'server'
+ * in createPluginContext and would always appear as an inline key.
+ *
+ * Returns the list of conflicting key names (for testing).
+ */
+export function warnConfigConflicts(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): string[] {
+  const conflicts: string[] = [];
+  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {
+    if (key in inline && inline[key] !== undefined) {
+      conflicts.push(key);
+    }
+  }
+  if (conflicts.length > 0) {
+    console.warn(
+      `[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(', ')} set in both ` +
+        `vite.config.ts (inline) and timber.config.ts. ` +
+        `Move all config to timber.config.ts to avoid confusion. ` +
+        `The inline value from vite.config.ts will be used.`
+    );
+  }
+  return conflicts;
+}
+
+/**
+ * Drop own keys whose value is `undefined` so they don't clobber file
+ * config during spread merging. `timber({ buildDir: process.env.BUILD_DIR })`
+ * with the var unset must not erase the timber.config.ts value.
+ */
+function stripUndefined<T extends object>(obj: T): T {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as T;
+}
+
+/**
+ * Merge file-based config (timber.config.ts) with inline config (vite.config.ts).
+ * Inline config takes precedence — file config only fills in missing fields.
+ * Inline keys explicitly set to `undefined` are treated as absent, matching
+ * the `!== undefined` check in warnConfigConflicts.
+ */
+export function mergeFileConfig(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): TimberUserConfig {
+  warnConfigConflicts(inline, fileConfig);
+  const definedInline = stripUndefined(inline);
+
+  return {
+    ...fileConfig,
+    ...definedInline,
+    ...(fileConfig.limits && definedInline.limits
+      ? { limits: { ...fileConfig.limits, ...stripUndefined(definedInline.limits) } }
+      : {}),
+    ...(fileConfig.dev && definedInline.dev
+      ? { dev: { ...fileConfig.dev, ...stripUndefined(definedInline.dev) } }
+      : {}),
+    ...(fileConfig.mdx && definedInline.mdx
+      ? { mdx: { ...fileConfig.mdx, ...stripUndefined(definedInline.mdx) } }
+      : {}),
+  };
+}