@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/routing/export-detect.ts

@@ -0,0 +1,448 @@
+/**
+ * AST-based export detection for route files.
+ *
+ * Uses Vite's `parseAst` (backed by oxc) to precisely detect named and
+ * default exports, replacing the regex-based approach that was fragile
+ * with TypeScript syntax (type exports, `as` aliases, comments, etc.).
+ */
+
+import { existsSync } from 'node:fs';
+import { parseAst } from 'vite';
+import { readFileCached } from './file-cache.ts';
+
+interface AstNode {
+  type: string;
+  exportKind?: string;
+  declaration?: AstNode;
+  specifiers?: Array<{
+    exported?: { name: string };
+    local?: { name: string };
+    exportKind?: string;
+  }>;
+  id?: { name: string };
+  declarations?: Array<{ id?: { name: string }; init?: AstNode }>;
+  /** Set on re-exports: `export { X } from './y'`. Absent on local exports. */
+  source?: { value?: string } | null;
+  /** Set on runtime-transparent wrappers: `X as T`, `X satisfies T`, `(X)`, `X!`. */
+  expression?: AstNode;
+  /** Set on `Identifier` nodes. */
+  name?: string;
+}
+
+interface ProgramNode {
+  body: AstNode[];
+}
+
+function tryParse(source: string): ProgramNode | null {
+  try {
+    return parseAst(source, { lang: 'tsx' }) as unknown as ProgramNode;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect all named export identifiers from a parsed program.
+ * Handles: `export function X`, `export const X`, `export { X }`,
+ * `export { X } from '...'`, `export { Y as X }`.
+ */
+function collectNamedExports(program: ProgramNode): Set<string> {
+  const names = new Set<string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ExportNamedDeclaration') continue;
+    // Skip `export type ...` declarations — they're erased at runtime
+    if (stmt.exportKind === 'type') continue;
+
+    if (stmt.declaration) {
+      if (stmt.declaration.id?.name) {
+        names.add(stmt.declaration.id.name);
+      }
+      if (stmt.declaration.declarations) {
+        for (const decl of stmt.declaration.declarations) {
+          if (decl.id?.name) names.add(decl.id.name);
+        }
+      }
+    }
+
+    if (stmt.specifiers) {
+      for (const spec of stmt.specifiers) {
+        // Skip `export { type X }` — per-specifier type exports
+        if (spec.exportKind === 'type') continue;
+        if (spec.exported?.name && spec.exported.name !== 'default') {
+          names.add(spec.exported.name);
+        }
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * The specifier exporting a *runtime* default from this statement, if any.
+ *
+ * Type-only exports erase, so they are not default exports at runtime — and
+ * TypeScript spells that two ways, on two different nodes: `export type { X as
+ * default }` marks the **statement**, `export { type X as default }` marks the
+ * **specifier**. Both have to be checked, or a type alias reads as a component:
+ * a status file whose only default is a type has nothing for the error boundary
+ * to receive (the renderer's `mod?.default` skips it), so treating it as one
+ * would fail a build over a file that cannot break anything.
+ *
+ * One implementation because two callers must agree on what "has a default
+ * export" means: `hasDefaultExport` decides whether to warn that a page has
+ * none, and `fileDefaultExportIsLocalValue` decides whether to fail the build.
+ */
+function defaultSpecifier(stmt: AstNode): NonNullable<AstNode['specifiers']>[number] | null {
+  if (stmt.type !== 'ExportNamedDeclaration' || !stmt.specifiers) return null;
+  if (stmt.exportKind === 'type') return null;
+  for (const spec of stmt.specifiers) {
+    if (spec.exportKind === 'type') continue;
+    if (spec.exported?.name === 'default') return spec;
+  }
+  return null;
+}
+
+/**
+ * Check whether a program has a default export.
+ * Handles: `export default ...`, `export { X as default }`,
+ * `export { default } from '...'`. Type-only defaults do not count —
+ * see `defaultSpecifier`.
+ */
+function hasDefaultExport(program: ProgramNode): boolean {
+  for (const stmt of program.body) {
+    if (stmt.type === 'ExportDefaultDeclaration') return true;
+    if (defaultSpecifier(stmt)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check whether a program has any bare `export * from '...'` declarations.
+ * Excludes `export * as X from '...'` (namespace re-exports) since those
+ * create a namespace object, not individual top-level exports.
+ */
+function hasStarExport(program: ProgramNode): boolean {
+  return program.body.some(
+    (stmt) =>
+      stmt.type === 'ExportAllDeclaration' && !(stmt as any).exported && stmt.exportKind !== 'type'
+  );
+}
+
+/**
+ * Check if a file exports a specific named export.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export function fileHasExport(filePath: string, exportName: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    return collectNamedExports(program).has(exportName);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file has any of the given named exports.
+ * Returns the set of matching export names.
+ */
+export function fileHasAnyExport(filePath: string, exportNames: readonly string[]): Set<string> {
+  const matches = new Set<string>();
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return matches;
+    const exports = collectNamedExports(program);
+    for (const name of exportNames) {
+      if (exports.has(name)) matches.add(name);
+    }
+  } catch {
+    // Graceful fallback: return empty set
+  }
+  return matches;
+}
+
+/**
+ * Check if a file has a default export.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export function fileHasDefaultExport(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    return hasDefaultExport(program);
+  } catch {
+    return false;
+  }
+}
+
+/** Node types whose value is unambiguously constructed by this module. */
+const FUNCTION_LIKE = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'ClassDeclaration',
+  'ClassExpression',
+]);
+
+/**
+ * Expression wrappers that erase at runtime and so cannot change where a value
+ * was constructed: `X as T`, `X satisfies T`, `<T>X`, `X!`, `X<T>`, `(X)`.
+ */
+const TRANSPARENT_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSNonNullExpression',
+  'TSInstantiationExpression',
+  'ParenthesizedExpression',
+]);
+
+/**
+ * Strip runtime-transparent wrappers so the node underneath can be classified.
+ *
+ * Without this, `(() => <h1 />) satisfies React.FC` reads as a
+ * `TSSatisfiesExpression` rather than the arrow function it compiles to, and a
+ * provably-local component is misread as one whose origin cannot be
+ * determined — turning a build error into a warning.
+ */
+function unwrapTransparent(node: AstNode): AstNode {
+  let current = node;
+  while (TRANSPARENT_WRAPPERS.has(current.type) && current.expression) {
+    current = current.expression;
+  }
+  return current;
+}
+
+/**
+ * Whether `name` is bound at module top level to a function or class written
+ * in this file. An imported binding can never match: imports are
+ * `ImportDeclaration` specifiers, not function/class/variable declarations,
+ * and a module-level name cannot be both.
+ */
+function bindsLocalFunction(program: ProgramNode, name: string): boolean {
+  for (const stmt of program.body) {
+    // `export function X() {}` binds X locally too — unwrap the export.
+    const decl = stmt.type === 'ExportNamedDeclaration' ? stmt.declaration : stmt;
+    if (!decl) continue;
+    if (
+      (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') &&
+      decl.id?.name === name
+    ) {
+      return true;
+    }
+    if (decl.type === 'VariableDeclaration') {
+      for (const d of decl.declarations ?? []) {
+        if (d.id?.name === name && d.init && FUNCTION_LIKE.has(unwrapTransparent(d.init).type)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether the default export is *provably* a value constructed by this module:
+ * `export default function/class/() => {}`, or a name bound to a function or
+ * class declared here — whether it leaves via `export default Name` or
+ * `export { Name as default }`. Both spellings are the same fact about where
+ * the value was built, so both must answer the same way.
+ *
+ * This is the sound half of "is this a server component?". A file with no
+ * `'use client'` directive whose default export is built here is a server
+ * component, full stop. Everything else — `export { default } from
+ * './client-thing'`, `export default Imported`, `export default memo(X)`,
+ * an unparseable file — returns false, because the exported value may have
+ * been minted in a module that *does* carry the directive. Callers must not
+ * infer "server component" from a missing directive alone.
+ */
+export function fileDefaultExportIsLocalValue(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    for (const stmt of program.body) {
+      if (stmt.type === 'ExportDefaultDeclaration') {
+        const decl = stmt.declaration && unwrapTransparent(stmt.declaration);
+        if (!decl) return false;
+        if (FUNCTION_LIKE.has(decl.type)) return true;
+        if (decl.type === 'Identifier' && decl.name) {
+          return bindsLocalFunction(program, decl.name);
+        }
+        return false;
+      }
+
+      // `export { Name as default }` — the same default export by another
+      // spelling. `hasDefaultExport` already counts it, so an analysis that
+      // skipped it here would let the exact defect this powers slip through
+      // as a warning.
+      const spec = defaultSpecifier(stmt);
+      if (spec) {
+        // `export { X as default } from './client-thing'` re-exports another
+        // module's value — the directive governing it lives over there.
+        if (stmt.source) return false;
+        return spec.local?.name ? bindsLocalFunction(program, spec.local.name) : false;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file has any `export * from '...'` declarations.
+ * Returns false if the file doesn't exist or can't be parsed.
+ */
+export function fileHasStarExport(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    return hasStarExport(program);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parsed value of `export const prerender` from a route file.
+ *
+ * - `true` / `false` — literal boolean
+ * - `{ ttl?, tags? }` — ISR options object (prerender: true is implied)
+ * - `undefined` — no `export const prerender` found
+ *
+ * See design/45-cache-lifetimes.md §"Route-Level Static".
+ */
+export type PrerenderExportValue = boolean | { ttl?: number; tags?: string[] };
+
+function extractLiteralValue(node: AstNode): unknown {
+  if (!node) return undefined;
+  const n = node as any;
+  if (n.type === 'Literal') return n.value;
+  if (n.type === 'UnaryExpression' && n.operator === '-' && n.argument?.type === 'Literal') {
+    return -(n.argument.value as number);
+  }
+  if (n.type === 'ArrayExpression') {
+    const elements = n.elements as AstNode[] | undefined;
+    if (!elements) return undefined;
+    const result: unknown[] = [];
+    for (const el of elements) {
+      const v = extractLiteralValue(el);
+      if (v === undefined) return undefined;
+      result.push(v);
+    }
+    return result;
+  }
+  return undefined;
+}
+
+function extractObjectLiteral(node: AstNode): Record<string, unknown> | undefined {
+  if ((node as any).type !== 'ObjectExpression') return undefined;
+  const props = (node as any).properties as AstNode[] | undefined;
+  if (!props) return undefined;
+  const result: Record<string, unknown> = {};
+  for (const prop of props) {
+    const p = prop as any;
+    if (p.type === 'SpreadElement') return undefined;
+    if (p.type !== 'Property' || p.computed) return undefined;
+    const key =
+      p.key?.type === 'Identifier'
+        ? p.key.name
+        : p.key?.type === 'Literal'
+          ? String(p.key.value)
+          : undefined;
+    if (!key) return undefined;
+    const value = extractLiteralValue(p.value);
+    if (value === undefined) return undefined;
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Extract the value of `export const prerender` from a file.
+ * Returns undefined if the file doesn't export `prerender` or can't be parsed.
+ *
+ * Supports:
+ *   export const prerender = true;
+ *   export const prerender = false;
+ *   export const prerender = { ttl: 3600, tags: ['docs'] };
+ */
+export function getPrerenderExport(filePath: string): PrerenderExportValue | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return undefined;
+
+    for (const stmt of program.body) {
+      if (stmt.type !== 'ExportNamedDeclaration') continue;
+      if (stmt.exportKind === 'type') continue;
+      if (!stmt.declaration) continue;
+      const decl = stmt.declaration;
+      if (decl.type !== 'VariableDeclaration') continue;
+      const declarations = decl.declarations as
+        | Array<{
+            id?: { name?: string };
+            init?: AstNode;
+          }>
+        | undefined;
+      if (!declarations) continue;
+      for (const d of declarations) {
+        if (d.id?.name !== 'prerender' || !d.init) continue;
+        const init = d.init as any;
+        if (init.type === 'Literal' && typeof init.value === 'boolean') {
+          return init.value;
+        }
+        if (init.type === 'ObjectExpression') {
+          const obj = extractObjectLiteral(init);
+          if (!obj) return undefined;
+          const result: { ttl?: number; tags?: string[] } = {};
+          if ('ttl' in obj && typeof obj.ttl === 'number') result.ttl = obj.ttl;
+          if (
+            'tags' in obj &&
+            Array.isArray(obj.tags) &&
+            obj.tags.every((t: unknown) => typeof t === 'string')
+          ) {
+            result.tags = obj.tags as string[];
+          }
+          return result;
+        }
+        return undefined;
+      }
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check if a file starts with a specific directive (e.g. "use client").
+ * Directives are string literal expression statements at the top of the file.
+ */
+export function fileHasDirective(filePath: string, directive: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    for (const stmt of program.body) {
+      if (stmt.type !== 'ExpressionStatement') break;
+      const expr = (stmt as any).expression;
+      if (expr?.type !== 'Literal' || typeof expr.value !== 'string') break;
+      if (expr.value === directive) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/src/routing/file-cache.ts

@@ -0,0 +1,23 @@
+import { readFileSync, statSync } from 'node:fs';
+
+const cache = new Map<string, { mtimeMs: number; size: number; content: string }>();
+
+/**
+ * Read a file's text content, returning a cached copy when the file
+ * hasn't been modified since the last read (checked via mtime + size).
+ *
+ * Falls back to a fresh read on any stat/read error.
+ */
+export function readFileCached(filePath: string): string {
+  try {
+    const stat = statSync(filePath);
+    const entry = cache.get(filePath);
+    if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) return entry.content;
+    const content = readFileSync(filePath, 'utf-8');
+    cache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, content });
+    return content;
+  } catch {
+    cache.delete(filePath);
+    return readFileSync(filePath, 'utf-8');
+  }
+}

package/src/routing/index.ts

@@ -1,6 +1,6 @@
-export { scanRoutes, classifySegment } from './scanner.js';
-export { generateRouteMap } from './codegen.js';
-export type { CodegenOptions } from './codegen.js';
+export { scanRoutes } from './scanner.ts';
+export { generateRouteMap } from './codegen.ts';
+export type { CodegenOptions } from './codegen.ts';
 export type {
   RouteTree,
   SegmentNode,
@@ -8,7 +8,16 @@ export type {
   RouteFile,
   ScannerConfig,
   InterceptionMarker,
-} from './types.js';
-export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-export { collectInterceptionRewrites } from './interception.js';
-export type { InterceptionRewrite } from './interception.js';
+} from './types.ts';
+export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.ts';
+export { collectInterceptionRewrites } from './interception.ts';
+export type { InterceptionRewrite } from './interception.ts';
+export { classifyUrlSegment, classifySegment } from './segment-classify.ts';
+export type { UrlSegment, SegmentClassification } from './segment-classify.ts';
+export { collectLeafRoutes } from './walkers.ts';
+export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.ts';
+export {
+  validateSchemaAgainstRoutes,
+  collectDynamicSegmentsFromTree,
+} from './schema-validation.ts';
+export type { SchemaWarning } from './schema-validation.ts';

package/src/routing/interception-overlap.ts

@@ -0,0 +1,141 @@
+/**
+ * Pattern intersection for intercepted URL patterns.
+ *
+ * Checks whether two intercepted URL patterns can both match the same concrete
+ * URL. Used by the cross-mode claim check (TIM-1319) to detect when a
+ * children-path interceptor and a slot interceptor from the same owner overlap.
+ *
+ * This is not the order-dependence oracle (`findOrderDependentCollision`) the
+ * within-mode collision checks use. `findInterceptionMatch` picks the mode by
+ * first-match on `pathnameMatchesPattern`, which has no priority tiers, so a
+ * static `/feed/foo` and a dynamic `/feed/[id]` both match `/feed/foo` even
+ * though `matchUrlParts` would resolve the static deterministically. The
+ * intersection test catches that: it walks both patterns segment by segment and
+ * asks whether any value satisfies both.
+ *
+ * This is not a model of `matchNode` precedence — that decides *which*
+ * candidate wins when several match one URL. This decides the prior question:
+ * *do* they both match one URL at all? The two questions are independent, and
+ * conflating them is what caused TIM-1308's five-round drift.
+ */
+
+import { classifyUrlSegment } from './segment-classify.ts';
+
+/**
+ * Check whether two intercepted URL patterns can both match the same concrete
+ * URL. Returns a display string for the overlapping URL, or null.
+ *
+ * Walks both patterns segment by segment:
+ * - Two statics: must be identical.
+ * - Static + dynamic: static must satisfy the dynamic's affix constraints.
+ * - Two dynamics: affix constraints must be compatible.
+ * - A catch-all at either side: compatible with everything remaining.
+ *
+ * If the patterns differ in length, they can only overlap if the longer one's
+ * extra part is an optional catch-all (which also matches zero segments).
+ */
+export function interceptedPatternsOverlap(p1: string, p2: string): string | null {
+  if (p1 === p2) return p1;
+
+  const parts1 = p1 === '/' ? [] : p1.slice(1).split('/');
+  const parts2 = p2 === '/' ? [] : p2.slice(1).split('/');
+  const display: string[] = [];
+  let i = 0;
+
+  while (i < parts1.length && i < parts2.length) {
+    const seg1 = classifyUrlSegment(parts1[i]);
+    const seg2 = classifyUrlSegment(parts2[i]);
+
+    if (
+      seg1.kind === 'catch-all' ||
+      seg1.kind === 'optional-catch-all' ||
+      seg2.kind === 'catch-all' ||
+      seg2.kind === 'optional-catch-all'
+    ) {
+      display.push('<any>');
+      return '/' + display.join('/');
+    }
+
+    const part = segmentsOverlap(seg1, seg2);
+    if (part === null) return null;
+    display.push(part);
+    i++;
+  }
+
+  const remaining = i < parts1.length ? parts1 : i < parts2.length ? parts2 : null;
+  if (remaining) {
+    const next = classifyUrlSegment(remaining[i]);
+    if (next.kind !== 'optional-catch-all') return null;
+  }
+
+  return display.length === 0 ? '/' : '/' + display.join('/');
+}
+
+/**
+ * Can some concrete value satisfy both classified URL segments?
+ *
+ * An affixed dynamic (`a-[id].png`) constrains both the prefix and suffix of
+ * the value, so a static segment must satisfy those constraints and two
+ * dynamics must have compatible affixes — prefixes where one extends the other,
+ * and likewise for suffixes. Without this check, `/feed/photo.jpg` beside
+ * `/feed/asset-[id].png` would be falsely rejected.
+ */
+function segmentsOverlap(
+  seg1: ReturnType<typeof classifyUrlSegment>,
+  seg2: ReturnType<typeof classifyUrlSegment>
+): string | null {
+  if (seg1.kind === 'static' && seg2.kind === 'static') {
+    return seg1.value === seg2.value ? seg1.value : null;
+  }
+
+  if (seg1.kind === 'static' && seg2.kind === 'dynamic') {
+    return staticMatchesAffix(seg1.value, seg2) ? seg1.value : null;
+  }
+  if (seg2.kind === 'static' && seg1.kind === 'dynamic') {
+    return staticMatchesAffix(seg2.value, seg1) ? seg2.value : null;
+  }
+
+  if (seg1.kind === 'dynamic' && seg2.kind === 'dynamic') {
+    return dynamicAffixesCompatible(seg1, seg2) ? '<any>' : null;
+  }
+
+  return '<any>';
+}
+
+/**
+ * Does a static value satisfy an affixed dynamic's prefix, suffix, and
+ * non-empty capture constraints?
+ *
+ * Mirrors the check `pathnameMatchesPattern` applies: the value must start with
+ * the prefix, end with the suffix, and be strictly longer than their combined
+ * length (a capture of zero characters is not a match).
+ */
+function staticMatchesAffix(value: string, dynamic: { prefix?: string; suffix?: string }): boolean {
+  const prefix = dynamic.prefix ?? '';
+  const suffix = dynamic.suffix ?? '';
+  if (!prefix && !suffix) return true;
+  if (prefix && !value.startsWith(prefix)) return false;
+  if (suffix && !value.endsWith(suffix)) return false;
+  return value.length > prefix.length + suffix.length;
+}
+
+/**
+ * Can some value simultaneously satisfy two affixed dynamics?
+ *
+ * Two prefix constraints are compatible when one extends the other (a value
+ * starting with the longer one also starts with the shorter). Suffixes are
+ * analogous. Without affixes on either side, every value works.
+ */
+function dynamicAffixesCompatible(
+  d1: { prefix?: string; suffix?: string },
+  d2: { prefix?: string; suffix?: string }
+): boolean {
+  const p1 = d1.prefix ?? '',
+    s1 = d1.suffix ?? '';
+  const p2 = d2.prefix ?? '',
+    s2 = d2.suffix ?? '';
+
+  if (p1 && p2 && !p1.startsWith(p2) && !p2.startsWith(p1)) return false;
+  if (s1 && s2 && !s1.endsWith(s2) && !s2.endsWith(s1)) return false;
+  return true;
+}