@timber-js/app 0.1.1 → 0.1.3

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

@@ -0,0 +1,114 @@
+/**
+ * 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/routing/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Route tree types for timber.js file-system routing.
+ *
+ * The route tree is built by scanning the app/ directory and recognizing
+ * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).
+ */
+
+/** Segment type classification */
+export type SegmentType =
+  | 'static' // e.g. "dashboard"
+  | 'dynamic' // e.g. "[id]"
+  | 'catch-all' // e.g. "[...slug]"
+  | 'optional-catch-all' // e.g. "[[...slug]]"
+  | 'group' // e.g. "(marketing)"
+  | 'slot' // e.g. "@sidebar"
+  | 'intercepting' // e.g. "(.)photo", "(..)photo", "(...)photo"
+  | 'private'; // e.g. "_components", "_lib" — excluded from routing
+
+/**
+ * Intercepting route marker — indicates how many levels up to resolve the
+ * intercepted route from the intercepting route's location.
+ *
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+export type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';
+
+/** All recognized interception markers, ordered longest-first for parsing. */
+export const INTERCEPTION_MARKERS: InterceptionMarker[] = ['(..)(..)', '(.)', '(..)', '(...)'];
+
+/** A single file discovered in a route segment */
+export interface RouteFile {
+  /** Absolute path to the file */
+  filePath: string;
+  /** File extension without leading dot (e.g. "tsx", "ts", "mdx") */
+  extension: string;
+}
+
+/** A node in the segment tree */
+export interface SegmentNode {
+  /** The raw directory name (e.g. "dashboard", "[id]", "(auth)", "@sidebar") */
+  segmentName: string;
+  /** Classified segment type */
+  segmentType: SegmentType;
+  /** The dynamic param name, if dynamic (e.g. "id" for "[id]", "slug" for "[...slug]") */
+  paramName?: string;
+  /** The URL path prefix at this segment level (e.g. "/dashboard") */
+  urlPath: string;
+  /** For intercepting segments: the marker used, e.g. "(.)". */
+  interceptionMarker?: InterceptionMarker;
+  /**
+   * For intercepting segments: the segment name after stripping the marker.
+   * E.g., for "(.)photo" this is "photo".
+   */
+  interceptedSegmentName?: string;
+
+  // --- File conventions ---
+  page?: RouteFile;
+  layout?: RouteFile;
+  middleware?: RouteFile;
+  access?: RouteFile;
+  route?: RouteFile;
+  error?: RouteFile;
+  default?: RouteFile;
+  /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */
+  statusFiles?: Map<string, RouteFile>;
+  /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */
+  jsonStatusFiles?: Map<string, RouteFile>;
+  /** denied.tsx — slot-only denial rendering */
+  denied?: RouteFile;
+  /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
+  legacyStatusFiles?: Map<string, RouteFile>;
+  /** prerender.ts — signals build-time pre-rendering for this segment's shell */
+  prerender?: RouteFile;
+  /** search-params.ts — typed search params definition for this route */
+  searchParams?: RouteFile;
+  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
+  metadataRoutes?: Map<string, RouteFile>;
+
+  // --- Children ---
+  children: SegmentNode[];
+  /** Parallel route slots (keyed by slot name without @) */
+  slots: Map<string, SegmentNode>;
+}
+
+/** The full route tree output from the scanner */
+export interface RouteTree {
+  /** The root segment node (representing app/) */
+  root: SegmentNode;
+  /** All discovered proxy.ts files (should be at most one, in app/) */
+  proxy?: RouteFile;
+}
+
+/** Configuration passed to the scanner */
+export interface ScannerConfig {
+  /** Recognized page/layout extensions (without dots). Default: ['tsx', 'ts', 'jsx', 'js'] */
+  pageExtensions?: string[];
+}
+
+/** Default page extensions */
+export const DEFAULT_PAGE_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js'];

package/src/search-params/analyze.ts

@@ -0,0 +1,192 @@
+/**
+ * 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');
+}

package/src/search-params/codecs.ts

@@ -0,0 +1,153 @@
+/**
+ * Built-in codecs and the fromSchema bridge for Standard Schema-compatible
+ * validation libraries (Zod, Valibot, ArkType).
+ *
+ * Design doc: design/09-typescript.md §"The SearchParamCodec Protocol"
+ */
+
+import type { SearchParamCodec } from './create.js';
+
+// ---------------------------------------------------------------------------
+// Standard Schema interface (subset)
+//
+// Standard Schema (https://github.com/standard-schema/standard-schema) defines
+// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.
+// We depend only on `~standard.validate` to avoid coupling to any specific lib.
+// ---------------------------------------------------------------------------
+
+interface StandardSchemaV1<Output = unknown> {
+  '~standard': {
+    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+  };
+}
+
+type StandardSchemaResult<Output> =
+  | { value: Output; issues?: undefined }
+  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };
+
+// ---------------------------------------------------------------------------
+// Sync validate helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod v4's ~standard.validate() signature includes Promise in the return union
+ * to satisfy the Standard Schema spec, but in practice Zod always validates
+ * synchronously for the schema types we use. We assert the result is sync and
+ * throw if it isn't — search params parsing must be synchronous.
+ */
+function validateSync<Output>(
+  schema: StandardSchemaV1<Output>,
+  value: unknown
+): StandardSchemaResult<Output> {
+  const result = schema['~standard'].validate(value);
+  if (result instanceof Promise) {
+    throw new Error(
+      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'
+    );
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// fromSchema — bridge from Standard Schema to SearchParamCodec
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
+ * SearchParamCodec.
+ *
+ * Parse: coerces the raw URL string through the schema. On validation failure,
+ * parses `undefined` to get the schema's default value (the schema should have
+ * a `.default()` call). If that also fails, returns `undefined`.
+ *
+ * Serialize: uses `String()` for primitives, `null` for null/undefined.
+ *
+ * ```ts
+ * import { fromSchema } from '@timber/app/search-params'
+ * import { z } from 'zod/v4'
+ *
+ * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
+ * ```
+ */
+export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      // For array inputs, take the last value (consistent with URLSearchParams.get())
+      const input = Array.isArray(value) ? value[value.length - 1] : value;
+
+      // Try parsing the raw value
+      const result = validateSync(schema, input);
+      if (!result.issues) {
+        return result.value;
+      }
+
+      // On failure, try parsing undefined to get the default
+      const defaultResult = validateSync(schema, undefined);
+      if (!defaultResult.issues) {
+        return defaultResult.value;
+      }
+
+      // No default available — return undefined (codec design choice)
+      return undefined as T;
+    },
+
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      return String(value);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// fromArraySchema — bridge for array-valued search params
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a Standard Schema for array values. Handles both single strings
+ * and repeated query keys (`?tag=a&tag=b`).
+ *
+ * ```ts
+ * import { fromArraySchema } from '@timber/app/search-params'
+ * import { z } from 'zod/v4'
+ *
+ * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
+ * ```
+ */
+export function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      // Coerce single string to array for array schemas
+      let input: unknown = value;
+      if (typeof value === 'string') {
+        input = [value];
+      } else if (value === undefined) {
+        input = undefined;
+      }
+
+      const result = validateSync(schema, input);
+      if (!result.issues) {
+        return result.value;
+      }
+
+      // On failure, try undefined for default
+      const defaultResult = validateSync(schema, undefined);
+      if (!defaultResult.issues) {
+        return defaultResult.value;
+      }
+
+      return undefined as T;
+    },
+
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      if (Array.isArray(value)) {
+        return value.length === 0 ? null : value.join(',');
+      }
+      return String(value);
+    },
+  };
+}