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

package/src/plugins/dynamic-transform.ts

@@ -1,161 +0,0 @@
-/**
- * timber-dynamic-transform — Vite sub-plugin for 'use dynamic' directive.
- *
- * Detects `'use dynamic'` directives in server component function bodies
- * and transforms them into `markDynamic()` runtime calls. The directive
- * declares a dynamic boundary — the component and its subtree opt out of
- * the pre-rendered shell and render per-request.
- *
- * - In `output: 'static'` mode, `'use dynamic'` is a build error.
- * - In standard SSR routes (no prerender.ts), the directive is a no-op
- *   (everything is already per-request), but the transform still runs
- *   so the runtime can skip unnecessary work.
- *
- * Design doc: design/15-future-prerendering.md §"'use dynamic'"
- */
-
-import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-/**
- * Quick check: does this source file contain 'use dynamic' anywhere?
- * Used as a fast bail-out before doing expensive AST parsing.
- */
-export function containsUseDynamic(code: string): boolean {
-  return containsDirective(code, 'use dynamic');
-}
-
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
-
-interface TransformResult {
-  code: string;
-  map?: null;
-}
-
-/**
- * Find function declarations/expressions containing 'use dynamic' and
- * transform them into markDynamic() calls.
- *
- * Input:
- * ```tsx
- * export default async function AddToCartButton({ productId }) {
- *   'use dynamic'
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * Output:
- * ```tsx
- * import { markDynamic as __markDynamic } from '@timber-js/app/runtime';
- * export default async function AddToCartButton({ productId }) {
- *   __markDynamic();
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * The markDynamic() call registers the component boundary as dynamic
- * at render time. The pre-render pass uses this to know which subtrees
- * to skip and leave as holes for per-request rendering.
- */
-export function transformUseDynamic(code: string): TransformResult | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  // Replace directive strings with __markDynamic() calls, processing
-  // from end to start to preserve source offsets
-  let result = code;
-  for (const fn of functions) {
-    // Replace the directive in the body content
-    const cleanBody = fn.bodyContent.replace(/['"]use dynamic['"];?/, '__markDynamic();');
-    // Reconstruct: replace the body content between braces
-    result = result.slice(0, fn.bodyStart) + cleanBody + result.slice(fn.bodyEnd);
-  }
-
-  // Add the import at the top
-  result = `import { markDynamic as __markDynamic } from '@timber-js/app/runtime';\n` + result;
-
-  return { code: result, map: null };
-}
-
-// ---------------------------------------------------------------------------
-// Static mode validation
-// ---------------------------------------------------------------------------
-
-/**
- * In `output: 'static'` mode, `'use dynamic'` is a build error.
- * Static mode renders everything at build time — there is no per-request
- * rendering to opt into.
- */
-export function validateNoDynamicInStaticMode(
-  code: string
-): { message: string; line?: number } | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  return {
-    message:
-      `'use dynamic' cannot be used in static mode (output: 'static'). ` +
-      `Static mode renders all content at build time — there is no per-request rendering. ` +
-      `Remove the directive or switch to output: 'server'.`,
-    line: functions[functions.length - 1].directiveLine, // First occurrence (sorted descending)
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Vite Plugin
-// ---------------------------------------------------------------------------
-
-/**
- * Create the timber-dynamic-transform Vite plugin.
- *
- * In server mode: transforms 'use dynamic' into markDynamic() calls.
- * In static mode: rejects 'use dynamic' as a build error.
- */
-export function timberDynamicTransform(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-
-  return {
-    name: 'timber-dynamic-transform',
-
-    transform(code: string, id: string) {
-      // Skip node_modules
-      if (id.includes('node_modules')) return null;
-
-      // Only check files in the app directory
-      if (!id.includes('/app/') && !id.startsWith('app/')) return null;
-
-      // Only check JS/TS files
-      if (!/\.[jt]sx?$/.test(id)) return null;
-
-      // Quick bail-out
-      if (!containsUseDynamic(code)) return null;
-
-      // In static mode, 'use dynamic' is a build error
-      if (isStatic) {
-        const error = validateNoDynamicInStaticMode(code);
-        if (error) {
-          this.error(
-            `[timber] Static mode error in ${id}${error.line ? `:${error.line}` : ''}: ${error.message}`
-          );
-        }
-        return null;
-      }
-
-      // In server mode, transform the directive
-      return transformUseDynamic(code);
-    },
-  };
-}

package/src/plugins/server-action-exports.ts

@@ -1,220 +0,0 @@
-import type { Plugin } from 'vite';
-import { Parser } from 'acorn';
-import acornJsx from 'acorn-jsx';
-import { detectFileDirective } from '#/utils/directive-parser.js';
-
-const jsxParser = Parser.extend(acornJsx());
-
-/**
- * Rewrite 'use server' module exports to bypass RSC plugin AST validation.
- *
- * The RSC plugin's client/SSR proxy transform (transformProxyExport) requires
- * all `export const` initializers to be `async ArrowFunctionExpression`. But
- * `createActionClient().action()` and `validated()` return async functions via
- * CallExpressions — valid at runtime but rejected by the static AST check.
- *
- * This plugin rewrites non-function-expression exports from:
- *
- *   export const foo = someCall();
- *
- * to:
- *
- *   const foo = someCall();
- *   export { foo };
- *
- * The `export { name }` form bypasses the RSC plugin's validation without
- * changing runtime semantics. Function expression exports (async arrows,
- * async function expressions) are left untouched.
- *
- * See design/08-forms-and-actions.md §"Middleware for Server Actions"
- */
-export function timberServerActionExports(): Plugin {
-  return {
-    name: 'timber-server-action-exports',
-    transform(code, id) {
-      // Skip non-JS/TS files
-      if (!/\.[jt]sx?$/.test(id)) return;
-      // Quick bail-out
-      if (!code.includes('use server')) return;
-      // Check for file-level directive
-      const directive = detectFileDirective(code, ['use server']);
-      if (!directive) return;
-
-      return rewriteServerActionExports(code);
-    },
-  };
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AcornNode = any;
-
-/**
- * Check if an AST node is an async function expression (arrow or regular).
- * These are handled correctly by the RSC plugin and don't need rewriting.
- */
-function isAsyncFunctionExpr(node: AcornNode): boolean {
-  if (!node) return false;
-  return (
-    (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression') && node.async
-  );
-}
-
-/**
- * Extract identifier names from a declarator's id pattern.
- * Handles simple identifiers and destructuring patterns.
- */
-function extractDeclNames(id: AcornNode): string[] {
-  if (id.type === 'Identifier') return [id.name];
-
-  // ObjectPattern: const { a, b } = ...
-  if (id.type === 'ObjectPattern') {
-    return id.properties.flatMap((p: AcornNode) => extractDeclNames(p.value ?? p.argument));
-  }
-
-  // ArrayPattern: const [a, b] = ...
-  if (id.type === 'ArrayPattern') {
-    return id.elements.filter(Boolean).flatMap((e: AcornNode) => extractDeclNames(e));
-  }
-
-  // RestElement: const [...rest] = ...
-  if (id.type === 'RestElement') {
-    return extractDeclNames(id.argument);
-  }
-
-  // AssignmentPattern: const { a = 1 } = ...
-  if (id.type === 'AssignmentPattern') {
-    return extractDeclNames(id.left);
-  }
-
-  return [];
-}
-
-interface RewriteTarget {
-  /** Start offset of the `export` keyword */
-  exportStart: number;
-  /** Start offset of the `const/let/var` keyword (right after `export `) */
-  declStart: number;
-  /** Names to re-export */
-  names: string[];
-}
-
-function rewriteServerActionExports(code: string): { code: string; map: null } | undefined {
-  let ast: AcornNode;
-  try {
-    ast = jsxParser.parse(code, {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-    });
-  } catch {
-    // TypeScript that esbuild hasn't stripped yet — use regex fallback
-    return rewriteServerActionExportsFallback(code);
-  }
-
-  const targets: RewriteTarget[] = [];
-
-  for (const node of ast.body) {
-    // Case 1: export const/let/var name = <non-function-expression>
-    if (
-      node.type === 'ExportNamedDeclaration' &&
-      node.declaration?.type === 'VariableDeclaration'
-    ) {
-      const hasNonFunctionInit = node.declaration.declarations.some(
-        (d: AcornNode) => d.init && !isAsyncFunctionExpr(d.init)
-      );
-      if (!hasNonFunctionInit) continue;
-
-      const names = node.declaration.declarations.flatMap((d: AcornNode) => extractDeclNames(d.id));
-      if (names.length === 0) continue;
-
-      targets.push({
-        exportStart: node.start,
-        declStart: node.declaration.start,
-        names,
-      });
-    }
-
-    // Case 2: export default <non-function-expression>
-    if (node.type === 'ExportDefaultDeclaration') {
-      const decl = node.declaration;
-      if (
-        decl.type !== 'FunctionDeclaration' &&
-        decl.type !== 'Identifier' &&
-        !isAsyncFunctionExpr(decl)
-      ) {
-        // export default someCall() → const $$default = someCall(); export default $$default;
-        targets.push({
-          exportStart: node.start,
-          declStart: -1, // sentinel for default export
-          names: ['default'],
-        });
-      }
-    }
-  }
-
-  if (targets.length === 0) return undefined;
-
-  // Process from end to start to preserve character positions
-  let result = code;
-  const reExports: string[] = [];
-
-  for (let i = targets.length - 1; i >= 0; i--) {
-    const target = targets[i];
-
-    if (target.declStart === -1) {
-      // export default <expr> → const $$default = <expr>;\nexport default $$default;
-      const node = ast.body.find(
-        (n: AcornNode) => n.type === 'ExportDefaultDeclaration' && n.start === target.exportStart
-      );
-      if (node) {
-        const exprCode = code.slice(node.declaration.start, node.declaration.end);
-        const replacement = `const $$default = ${exprCode};\nexport default $$default;`;
-        result = result.slice(0, node.start) + replacement + result.slice(node.end);
-      }
-      continue;
-    }
-
-    // Remove 'export ' from the declaration
-    result = result.slice(0, target.exportStart) + result.slice(target.declStart);
-    reExports.push(...target.names);
-  }
-
-  if (reExports.length > 0) {
-    result += '\nexport { ' + reExports.join(', ') + ' };\n';
-  }
-
-  return { code: result, map: null };
-}
-
-/**
- * Regex fallback for TypeScript files that acorn cannot parse.
- *
- * Matches `export const/let/var name = <expr>` where the initializer does
- * NOT start with `async function` or `async (` (i.e., not an async
- * function expression or async arrow function).
- */
-function rewriteServerActionExportsFallback(code: string): { code: string; map: null } | undefined {
-  // Match: export const/let/var <name> = <non-async-function-expr>
-  const pattern =
-    /^(export\s+)((?:const|let|var)\s+(\w+)\s*=\s*)(?!async\s+(?:function[\s(]|\())/gm;
-
-  const names: string[] = [];
-  let result = code;
-  let offset = 0;
-  let match;
-
-  while ((match = pattern.exec(code)) !== null) {
-    const exportKeyword = match[1]; // 'export ' (with trailing space)
-    const name = match[3];
-
-    // Remove 'export ' at this position (adjusted for prior removals)
-    const pos = match.index + offset;
-    result = result.slice(0, pos) + result.slice(pos + exportKeyword.length);
-    offset -= exportKeyword.length;
-    names.push(name);
-  }
-
-  if (names.length === 0) return undefined;
-
-  result += '\nexport { ' + names.join(', ') + ' };\n';
-  return { code: result, map: null };
-}

package/src/routing/status-file-lint.ts

@@ -1,112 +0,0 @@
-/**
- * Lint status files and error.tsx for missing 'use client' directive.
- *
- * Status files (error.tsx, 404.tsx, 4xx.tsx, 5xx.tsx, NNN.tsx) and legacy
- * compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx) are passed
- * as fallbackComponent to TimberErrorBoundary — a 'use client' component.
- * RSC forbids passing server component functions as props to client
- * components, causing a hard-to-debug runtime error.
- *
- * This module provides a build/dev-time check that warns when these files
- * are missing the 'use client' directive.
- *
- * See design/10-error-handling.md §"Status-Code Files".
- */
-
-import { readFileSync } from 'node:fs';
-import type { RouteTree, SegmentNode } from './types.js';
-import { detectFileDirective } from '#/utils/directive-parser.js';
-
-/** Extensions that require 'use client' (component files, not MDX/JSON). */
-const CLIENT_REQUIRED_EXTENSIONS = new Set(['tsx', 'jsx', 'ts', 'js']);
-
-export interface StatusFileLintWarning {
-  filePath: string;
-  fileType: string;
-}
-
-/**
- * Walk the route tree and check all status files and error files for
- * the 'use client' directive. Returns an array of warnings for files
- * that are missing it.
- *
- * MDX and JSON status files are excluded — MDX files are server components
- * by design, and JSON files are data, not components.
- */
-export function lintStatusFileDirectives(tree: RouteTree): StatusFileLintWarning[] {
-  const warnings: StatusFileLintWarning[] = [];
-  walkNode(tree.root, warnings);
-  return warnings;
-}
-
-function walkNode(node: SegmentNode, warnings: StatusFileLintWarning[]): void {
-  // Check error.tsx
-  if (node.error) {
-    checkFile(node.error.filePath, node.error.extension, 'error', warnings);
-  }
-
-  // Check status-code files (404.tsx, 4xx.tsx, 5xx.tsx, etc.)
-  if (node.statusFiles) {
-    for (const [code, file] of node.statusFiles) {
-      checkFile(file.filePath, file.extension, code, warnings);
-    }
-  }
-
-  // Check legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
-  if (node.legacyStatusFiles) {
-    for (const [name, file] of node.legacyStatusFiles) {
-      checkFile(file.filePath, file.extension, name, warnings);
-    }
-  }
-
-  // Recurse into children and slots
-  for (const child of node.children) {
-    walkNode(child, warnings);
-  }
-  for (const [, slotNode] of node.slots) {
-    walkNode(slotNode, warnings);
-  }
-}
-
-function checkFile(
-  filePath: string,
-  extension: string,
-  fileType: string,
-  warnings: StatusFileLintWarning[]
-): void {
-  if (!CLIENT_REQUIRED_EXTENSIONS.has(extension)) return;
-
-  let code: string;
-  try {
-    code = readFileSync(filePath, 'utf-8');
-  } catch {
-    return; // File unreadable — skip silently
-  }
-
-  const directive = detectFileDirective(code, ['use client']);
-  if (!directive) {
-    warnings.push({ filePath, fileType });
-  }
-}
-
-/**
- * Format warnings into human-readable console output.
- */
-export function formatStatusFileLintWarnings(warnings: StatusFileLintWarning[]): string {
-  const lines = [
-    `[timber] ${warnings.length} status/error file${warnings.length > 1 ? 's' : ''} missing 'use client' directive:`,
-    '',
-  ];
-
-  for (const w of warnings) {
-    lines.push(`  ${w.filePath}`);
-  }
-
-  lines.push('');
-  lines.push(
-    "  Status files and error.tsx are rendered inside TimberErrorBoundary (a 'use client' component)."
-  );
-  lines.push("  Add 'use client' as the first line of each file to avoid a runtime error.");
-
-  return lines.join('\n');
-}

package/src/search-params/analyze.ts

@@ -1,192 +0,0 @@
-/**
- * Static analyzability checker for search-params.ts files.
- *
- * Validates that a search-params.ts file's default export is statically
- * analyzable — a createSearchParams() call or a chain of .extend()/.pick()
- * calls on a SearchParamsDefinition.
- *
- * Non-analyzable files produce a hard build error with a diagnostic.
- *
- * Design doc: design/09-typescript.md §"Static Analyzability"
- */
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Result of analyzing a search-params.ts file. */
-export interface AnalyzeResult {
-  /** Whether the file is statically analyzable. */
-  valid: boolean;
-  /** Error details when valid is false. */
-  error?: AnalyzeError;
-}
-
-/** Diagnostic error for non-analyzable search-params.ts. */
-export interface AnalyzeError {
-  /** Absolute file path. */
-  filePath: string;
-  /** Description of the non-analyzable expression. */
-  expression: string;
-  /** Suggested fix. */
-  suggestion: string;
-}
-
-// ---------------------------------------------------------------------------
-// AST-free source analysis
-//
-// We use a lightweight regex-based approach to validate the structure of the
-// default export. This avoids requiring a TypeScript compiler instance at
-// build time for the initial validation pass. The full type extraction
-// (reading T from SearchParamsDefinition<T>) still happens via the TypeScript
-// compiler in the codegen step — this module just validates the *shape*.
-// ---------------------------------------------------------------------------
-
-/**
- * Patterns that indicate a valid default export:
- *
- * 1. `export default createSearchParams(...)`
- * 2. `export default someVar.extend(...)`
- * 3. `export default someVar.pick(...)`
- * 4. `export default someVar.extend(...).extend(...)`  (chained)
- * 5. `export default someVar.extend(...).pick(...)`    (chained)
- * 6. `export default createSearchParams(...).extend(...)`
- *
- * Invalid patterns:
- * - `export default someFunction(...)` (arbitrary factory)
- * - `export default condition ? a : b` (runtime conditional)
- * - `export default variable` (opaque reference without call)
- */
-
-/**
- * Analyze a search-params.ts file source for static analyzability.
- *
- * @param source - The file content as a string
- * @param filePath - Absolute path to the file (for diagnostics)
- */
-export function analyzeSearchParams(source: string, filePath: string): AnalyzeResult {
-  // Strip comments to avoid false matches
-  const stripped = stripComments(source);
-
-  // Find the default export
-  const defaultExport = extractDefaultExport(stripped);
-
-  if (!defaultExport) {
-    return {
-      valid: false,
-      error: {
-        filePath,
-        expression: '(no default export found)',
-        suggestion:
-          'search-params.ts must have a default export. Use: export default createSearchParams({ ... })',
-      },
-    };
-  }
-
-  // Validate the expression
-  if (isValidExpression(defaultExport.trim())) {
-    return { valid: true };
-  }
-
-  return {
-    valid: false,
-    error: {
-      filePath,
-      expression: defaultExport.trim(),
-      suggestion:
-        'The default export must be a createSearchParams() call, or a chain of ' +
-        '.extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory ' +
-        'functions and runtime conditionals are not supported.',
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/** Strip single-line and multi-line comments from source. */
-function stripComments(source: string): string {
-  // Remove multi-line comments
-  let result = source.replace(/\/\*[\s\S]*?\*\//g, '');
-  // Remove single-line comments
-  result = result.replace(/\/\/.*$/gm, '');
-  return result;
-}
-
-/**
- * Extract the expression from `export default <expr>`.
- *
- * Handles both:
- *   export default createSearchParams(...)
- *   export default expr\n (terminated by newline or semicolon before next statement)
- */
-function extractDefaultExport(source: string): string | undefined {
-  // Match `export default` followed by the expression
-  const match = source.match(
-    /export\s+default\s+([\s\S]+?)(?:;|\n(?=export|import|const|let|var|function|class|type|interface|declare))/
-  );
-  if (match) {
-    return match[1];
-  }
-
-  // Fallback: match everything after `export default` to end of file
-  const fallback = source.match(/export\s+default\s+([\s\S]+)$/);
-  if (fallback) {
-    return fallback[1].replace(/;\s*$/, '');
-  }
-
-  return undefined;
-}
-
-/**
- * Check if an expression is a valid statically-analyzable pattern.
- *
- * Valid patterns:
- * - Starts with `createSearchParams(`
- * - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)
- * - A variable identifier followed by chaining
- */
-function isValidExpression(expr: string): boolean {
-  // Normalize whitespace
-  const normalized = expr.replace(/\s+/g, ' ').trim();
-
-  // Pattern 1: starts with createSearchParams(
-  if (normalized.startsWith('createSearchParams(')) {
-    return true;
-  }
-
-  // Pattern 2: chain ending with .extend(...) or .pick(...)
-  // This covers: someVar.extend(...), createSearchParams(...).extend(...).pick(...), etc.
-  if (/\.(extend|pick)\s*\(/.test(normalized)) {
-    // Reject ternaries and other conditional patterns
-    if (/\?/.test(normalized) && /:/.test(normalized)) {
-      return false;
-    }
-    // Reject function declarations/expressions
-    if (/^\s*(function|=>|\()/.test(normalized)) {
-      return false;
-    }
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Format an AnalyzeError into a human-readable build error message.
- */
-export function formatAnalyzeError(error: AnalyzeError): string {
-  return [
-    `[timber] Non-analyzable search-params.ts`,
-    ``,
-    `  File: ${error.filePath}`,
-    `  Expression: ${error.expression}`,
-    ``,
-    `  ${error.suggestion}`,
-    ``,
-    `  The framework must be able to statically extract the type from your`,
-    `  search-params.ts at build time. Dynamic values, conditionals, and`,
-    `  arbitrary factory functions prevent this analysis.`,
-  ].join('\n');
-}