@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/plugins/request-dep.ts

@@ -1,499 +0,0 @@
-/**
- * timber-request-dep — Static module-graph analysis for request-dependency.
- *
- * Replaces runtime ALS-based taint tracking with a build/dev-time computed
- * map: segment entry file → statically request-dependent?
- *
- * A segment/slot is request-dependent iff any module reachable from its
- * layout/page/default in the RSC module graph (stopping at client-reference
- * boundaries) imports and calls a request accessor (getHeaders, cookies,
- * getSearchParams, etc.) or calls .get() on a search-params/cookie
- * definition object.
- *
- * This is deterministic, covers children/barrels/node_modules/Suspense-
- * deferred code, and is computed before any byte is flushed.
- *
- * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
- */
-
-import type { Plugin } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
-import {
-  findImportBindings,
-  type ProgramNode,
-  type CallExpressionNode,
-  type MemberExpressionNode,
-  type IdentifierNode,
-} from './callsite-ast.js';
-
-// ─── Module specifiers whose bindings are request accessors ──────────────
-
-const ACCESSOR_SOURCES = new Set(['@timber-js/app/server', 'next/headers', 'next/headers.js']);
-
-const ACCESSOR_NAMES = new Set([
-  'getHeaders',
-  'getHeader',
-  'getSearchParams',
-  'getCookieJar',
-  'getCookie',
-  // next/headers shim names
-  'headers',
-  'cookies',
-]);
-
-const DEFINITION_FACTORY_SOURCES = new Set([
-  '@timber-js/app/search-params',
-  '@timber-js/app/cookies',
-]);
-
-const DEFINITION_FACTORY_NAMES = new Set(['defineSearchParams', 'defineCookie']);
-
-// ─── Framework module detection ─────────────────────────────────────────
-
-export function isFrameworkModule(id: string): boolean {
-  return (
-    /[\\/]node_modules[\\/]@timber-js[\\/]app[\\/]/.test(id) ||
-    /[\\/]packages[\\/]timber-app[\\/]src[\\/]/.test(id)
-  );
-}
-
-// ─── Fast token pre-filter ───────────────────────────────────────────────
-
-const ACCESSOR_TOKENS = [
-  'getHeaders',
-  'getHeader',
-  'getSearchParams',
-  'getCookieJar',
-  'getCookie',
-  'headers',
-  'cookies',
-  'defineSearchParams',
-  'defineCookie',
-  // .get() on imported/local definition bindings (searchParams.get())
-  '.get(',
-];
-
-function hasRelevantToken(code: string): boolean {
-  for (const token of ACCESSOR_TOKENS) {
-    if (code.includes(token)) return true;
-  }
-  return false;
-}
-
-// ─── Per-module facts ────────────────────────────────────────────────────
-
-export interface ModuleFacts {
-  /** Module directly calls a request accessor. */
-  callsAccessor: boolean;
-  /** Module imports a definition factory (defineSearchParams/defineCookie). */
-  importsDefinitionFactory: boolean;
-  /** Import specifiers where `.get()` was called on the binding. */
-  getterCallSources: string[];
-}
-
-// ─── AST analysis ────────────────────────────────────────────────────────
-
-export function analyzeModule(code: string, program: ProgramNode): ModuleFacts {
-  const facts: ModuleFacts = {
-    callsAccessor: false,
-    importsDefinitionFactory: false,
-    getterCallSources: [],
-  };
-
-  // Check for accessor imports
-  for (const name of ACCESSOR_NAMES) {
-    const bindings = findImportBindings(program, ACCESSOR_SOURCES, name);
-    if (bindings.named.size > 0 || bindings.namespaces.size > 0) {
-      // Check if any binding is actually called (not just imported)
-      if (hasCallSite(program, bindings.named, bindings.namespaces, name)) {
-        facts.callsAccessor = true;
-      }
-    }
-  }
-
-  // Check for definition factory imports
-  for (const name of DEFINITION_FACTORY_NAMES) {
-    const bindings = findImportBindings(program, DEFINITION_FACTORY_SOURCES, name);
-    if (bindings.named.size > 0 || bindings.namespaces.size > 0) {
-      facts.importsDefinitionFactory = true;
-    }
-  }
-
-  // Check for .get() calls on imported bindings (searchParams.get(), etc.)
-  // Collect which import sources have .get() called on their bindings.
-  for (const stmt of program.body) {
-    if (stmt.type !== 'ImportDeclaration') continue;
-    const decl = stmt as unknown as {
-      source: { value: string };
-      specifiers: Array<{ type: string; local: IdentifierNode; imported?: IdentifierNode }>;
-    };
-    for (const spec of decl.specifiers) {
-      if (spec.type === 'ImportDefaultSpecifier' || spec.type === 'ImportSpecifier') {
-        const localName = spec.local.name;
-        if (hasGetterCall(program, localName)) {
-          facts.getterCallSources.push(decl.source.value);
-        }
-      }
-    }
-  }
-
-  // Check for co-located definitions: const sp = defineSearchParams(...); sp.get()
-  // If a module both mints a definition AND calls .get() on any local binding
-  // whose init is a defineSearchParams/defineCookie call, it's a taint source.
-  if (facts.importsDefinitionFactory) {
-    for (const stmt of program.body) {
-      if (stmt.type !== 'VariableDeclaration') continue;
-      for (const decl of ((stmt as Record<string, unknown>).declarations as Array<
-        Record<string, unknown>
-      >) ?? []) {
-        if (!decl.init || !decl.id) continue;
-        const init = decl.init as Record<string, unknown>;
-        // Check if init is a call to a definition factory
-        if (init.type === 'CallExpression') {
-          const callee = init.callee as Record<string, unknown>;
-          if (callee.type === 'Identifier') {
-            const calleeName = (callee as unknown as IdentifierNode).name;
-            // Check if this name is a definition factory binding
-            for (const factoryName of DEFINITION_FACTORY_NAMES) {
-              const bindings = findImportBindings(program, DEFINITION_FACTORY_SOURCES, factoryName);
-              if (bindings.named.has(calleeName)) {
-                // This local variable is a definition instance
-                const localName =
-                  (decl.id as Record<string, unknown>).type === 'Identifier'
-                    ? (decl.id as unknown as IdentifierNode).name
-                    : null;
-                if (localName && hasGetterCall(program, localName)) {
-                  facts.callsAccessor = true;
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-
-  return facts;
-}
-
-/** Check if any named/namespace binding is called as a function. */
-function hasCallSite(
-  program: ProgramNode,
-  named: Set<string>,
-  namespaces: Set<string>,
-  importedName: string
-): boolean {
-  return walkForCall(program, named, namespaces, importedName);
-}
-
-function walkForCall(
-  node: Record<string, unknown>,
-  named: Set<string>,
-  namespaces: Set<string>,
-  importedName: string
-): boolean {
-  if (node.type === 'CallExpression') {
-    const call = node as unknown as CallExpressionNode;
-    const callee = call.callee;
-    // Direct call: getHeaders()
-    if (callee.type === 'Identifier' && named.has((callee as IdentifierNode).name)) {
-      return true;
-    }
-    // Namespace call: ns.getHeaders()
-    if (callee.type === 'MemberExpression') {
-      const member = callee as MemberExpressionNode;
-      if (
-        !member.computed &&
-        member.object.type === 'Identifier' &&
-        namespaces.has((member.object as IdentifierNode).name) &&
-        member.property.type === 'Identifier' &&
-        (member.property as IdentifierNode).name === importedName
-      ) {
-        return true;
-      }
-    }
-  }
-  for (const key of Object.keys(node)) {
-    if (key === 'type' || key === 'start' || key === 'end') continue;
-    const val = node[key];
-    if (val && typeof val === 'object') {
-      if (Array.isArray(val)) {
-        for (const item of val) {
-          if (item && typeof item === 'object' && typeof item.type === 'string') {
-            if (walkForCall(item as Record<string, unknown>, named, namespaces, importedName))
-              return true;
-          }
-        }
-      } else if (typeof (val as Record<string, unknown>).type === 'string') {
-        if (walkForCall(val as Record<string, unknown>, named, namespaces, importedName))
-          return true;
-      }
-    }
-  }
-  return false;
-}
-
-/**
- * Check if the object chain of a `.get()` call contains `localName`.
- * Walks through MemberExpression objects and CallExpression callees
- * to handle chained patterns like `getFilterCookie(key).get()` or
- * `cookies.theme.get()`.
- */
-function objectChainContains(node: Record<string, unknown>, name: string): boolean {
-  if (node.type === 'Identifier' && (node as unknown as IdentifierNode).name === name) return true;
-  if (node.type === 'MemberExpression') {
-    return objectChainContains(
-      (node as unknown as MemberExpressionNode).object as Record<string, unknown>,
-      name
-    );
-  }
-  if (node.type === 'CallExpression') {
-    return objectChainContains(
-      (node as unknown as CallExpressionNode).callee as Record<string, unknown>,
-      name
-    );
-  }
-  return false;
-}
-
-/**
- * Check if `.get(...)` is called on `localName` anywhere in the module.
- * Handles direct (`localName.get()`), chained call (`localName(args).get()`),
- * and nested member (`localName.prop.get()`) patterns.
- */
-function hasGetterCall(node: Record<string, unknown>, localName: string): boolean {
-  if (node.type === 'CallExpression') {
-    const call = node as unknown as CallExpressionNode;
-    if (call.callee.type === 'MemberExpression') {
-      const member = call.callee as MemberExpressionNode;
-      if (
-        !member.computed &&
-        member.property.type === 'Identifier' &&
-        (member.property as IdentifierNode).name === 'get' &&
-        objectChainContains(member.object as Record<string, unknown>, localName)
-      ) {
-        return true;
-      }
-    }
-  }
-  for (const key of Object.keys(node)) {
-    if (key === 'type' || key === 'start' || key === 'end') continue;
-    const val = node[key];
-    if (val && typeof val === 'object') {
-      if (Array.isArray(val)) {
-        for (const item of val) {
-          if (item && typeof item === 'object' && typeof item.type === 'string') {
-            if (hasGetterCall(item as Record<string, unknown>, localName)) return true;
-          }
-        }
-      } else if (typeof (val as Record<string, unknown>).type === 'string') {
-        if (hasGetterCall(val as Record<string, unknown>, localName)) return true;
-      }
-    }
-  }
-  return false;
-}
-
-// ─── Module graph reachability ───────────────────────────────────────────
-
-/** Walk the module graph from an entry, returning true if any taint source is reachable. */
-function isReachableTaintSource(
-  entryId: string,
-  factsMap: Map<string, ModuleFacts>,
-  definitionModules: Set<string>,
-  getImports: (id: string) => string[]
-): boolean {
-  const visited = new Set<string>();
-  const stack = [entryId];
-
-  while (stack.length > 0) {
-    const id = stack.pop()!;
-    if (visited.has(id)) continue;
-    visited.add(id);
-
-    const facts = factsMap.get(id);
-    if (facts) {
-      if (facts.callsAccessor) return true;
-      // Check if any .get() call is on a definition module
-      for (const source of facts.getterCallSources) {
-        // Resolve relative to the module — for now just check if the
-        // resolved ID is a definition module.
-        // In dev, the getter source is unresolved; we check if any
-        // imported module is a definition module by looking at actual imports.
-      }
-    }
-
-    // Check if this module IS a definition module and has .get() callers
-    // (handled by the importer's facts)
-
-    const imports = getImports(id);
-    for (const imp of imports) {
-      // Stop at client boundaries — 'use client' modules in the RSC graph
-      // resolve to generated proxy stubs with no further imports.
-      // Also stop at virtual modules (they're framework internals).
-      if (!imp.startsWith('\0') && !visited.has(imp)) {
-        stack.push(imp);
-      }
-    }
-  }
-
-  // Second pass: check getter calls against definition modules
-  for (const id of visited) {
-    const facts = factsMap.get(id);
-    if (!facts) continue;
-    if (facts.getterCallSources.length === 0) continue;
-    // Check if any import of this module is a definition module
-    const imports = getImports(id);
-    for (const imp of imports) {
-      if (definitionModules.has(imp)) {
-        // This module imports a definition module and calls .get() on some binding.
-        // Conservative: treat it as a taint source.
-        return true;
-      }
-    }
-  }
-
-  return false;
-}
-
-// ─── Plugin ──────────────────────────────────────────────────────────────
-
-const BRIDGE_KEY = Symbol.for('timber:request-dep');
-
-export function timberRequestDep(ctx: PluginContext): Plugin {
-  const factsMap = new Map<string, ModuleFacts>();
-  const definitionModules = new Set<string>();
-  const cache = new Map<string, boolean>();
-
-  return {
-    name: 'timber-request-dep',
-    // Only run in RSC environment — that's where server components render.
-    applyToEnvironment(env) {
-      return env.name === 'rsc';
-    },
-
-    async transform(code, id) {
-      // Skip non-JS (include .mdx/.md — compiled to JS by timber-mdx before this runs)
-      if (!/\.[mc]?[jt]sx?$/.test(id) && !/\.mdx?$/.test(id)) return;
-      // Skip virtual modules
-      if (id.startsWith('\0') || id.startsWith('virtual:')) return;
-      // Skip framework modules — their internal accessor calls (e.g.,
-      // getCookieJar in define-cookie.ts) are implementation details.
-      // In dev they're externalized and never reach transform; in prod
-      // they would cause false positives (any module importing defineCookie
-      // would be tainted). Analysis relies on user-code .get() patterns.
-      if (isFrameworkModule(id)) return;
-      // Fast token check
-      if (!hasRelevantToken(code)) return;
-
-      const program = (this as unknown as { parse(code: string): ProgramNode }).parse(code);
-      const facts = analyzeModule(code, program);
-
-      if (
-        facts.callsAccessor ||
-        facts.importsDefinitionFactory ||
-        facts.getterCallSources.length > 0
-      ) {
-        factsMap.set(id, facts);
-        if (facts.importsDefinitionFactory) {
-          definitionModules.add(id);
-        }
-      }
-
-      // No code transform needed — this is analysis only.
-      return undefined;
-    },
-
-    configureServer(server) {
-      // Register the bridge so runtime can query request-dep status.
-      const resolver = (filePath: string): boolean => {
-        if (cache.has(filePath)) return cache.get(filePath)!;
-
-        const rscEnv = server.environments?.rsc;
-        if (!rscEnv?.moduleGraph) {
-          return true; // Unknown → conservative
-        }
-
-        const getImports = (moduleId: string): string[] => {
-          const mod = rscEnv.moduleGraph.getModuleById(moduleId);
-          if (!mod) return [];
-          const result: string[] = [];
-          for (const imp of mod.importedModules) {
-            if (imp.id) result.push(imp.id);
-          }
-          return result;
-        };
-
-        const result = isReachableTaintSource(filePath, factsMap, definitionModules, getImports);
-        cache.set(filePath, result);
-        return result;
-      };
-
-      (globalThis as Record<symbol, unknown>)[BRIDGE_KEY] = resolver;
-
-      // Clear cache on file changes
-      const clearCache = () => cache.clear();
-      server.watcher.on('change', clearCache);
-      server.watcher.on('add', clearCache);
-      server.watcher.on('unlink', clearCache);
-    },
-
-    buildEnd() {
-      // Prod: compute the full map and register on globalThis for the
-      // build manifest plugin to pick up.
-      if (ctx.dev) return;
-
-      const getModuleInfo = (
-        this as unknown as {
-          getModuleInfo: (
-            id: string
-          ) => { importedIds?: string[]; dynamicallyImportedIds?: string[] } | null;
-        }
-      ).getModuleInfo;
-
-      const getImports = (moduleId: string): string[] => {
-        const info = getModuleInfo(moduleId);
-        if (!info) return [];
-        return [...(info.importedIds ?? []), ...(info.dynamicallyImportedIds ?? [])];
-      };
-
-      const requestDepMap: Record<string, boolean> = {};
-
-      // Walk the route tree to find all segment entry files
-      if (ctx.routeTree) {
-        walkSegmentTree(ctx.routeTree.root as unknown as WalkableNode, (filePath: string) => {
-          const result = isReachableTaintSource(filePath, factsMap, definitionModules, getImports);
-          requestDepMap[filePath] = result;
-        });
-      }
-
-      // Store on ctx for build-manifest plugin to serialize into the manifest.
-      // Prod runtime reads from __TIMBER_BUILD_MANIFEST__.requestDep.
-      (ctx as unknown as Record<string, unknown>).requestDepMap = requestDepMap;
-    },
-  };
-}
-
-interface WalkableNode {
-  layout?: { filePath: string };
-  page?: { filePath: string };
-  default?: { filePath: string };
-  children?: unknown[];
-  slots?: Record<string, unknown>;
-}
-
-function walkSegmentTree(node: WalkableNode, fn: (filePath: string) => void): void {
-  if (node.layout) fn(node.layout.filePath);
-  if (node.page) fn(node.page.filePath);
-  if (node.default) fn((node.default as { filePath: string }).filePath);
-  if (node.children) {
-    for (const child of node.children) {
-      walkSegmentTree(child as typeof node, fn);
-    }
-  }
-  if (node.slots) {
-    for (const slot of Object.values(node.slots)) {
-      walkSegmentTree(slot as typeof node, fn);
-    }
-  }
-}

package/src/search-params/registry.ts

@@ -1,31 +0,0 @@
-/**
- * Runtime registry for route-scoped search params definitions.
- *
- * When a route's modules load, the framework registers its search-params
- * definition here. useQueryStates('/route') resolves codecs from this map.
- *
- * Design doc: design/23-search-params.md §"Runtime: Registration at Route Load"
- */
-
-import type { SearchParamsDefinition } from './define.js';
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const registry = new Map<string, SearchParamsDefinition<any>>();
-
-/**
- * Register a route's search params definition.
- * Called by the generated route manifest loader when a route's modules load.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {
-  registry.set(route, definition);
-}
-
-/**
- * Look up a route's search params definition.
- * Returns undefined if the route hasn't been loaded yet.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function getSearchParamsDefinition(route: string): SearchParamsDefinition<any> | undefined {
-  return registry.get(route);
-}