@timber-js/app 0.1.0 → 0.1.2

package/src/utils/directive-parser.ts

@@ -0,0 +1,529 @@
+/**
+ * AST-based directive detection for 'use cache', 'use dynamic',
+ * 'use client', and 'use server'.
+ *
+ * Uses acorn to parse source code and detect directives properly,
+ * avoiding false positives from regex matching inside string literals,
+ * comments, or template expressions.
+ *
+ * @module
+ */
+
+import { Parser } from 'acorn';
+import acornJsx from 'acorn-jsx';
+
+// acorn parser with JSX support
+const jsxParser = Parser.extend(acornJsx());
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FileDirective {
+  /** The directive value, e.g. 'use client', 'use server' */
+  directive: string;
+  /** 1-based line number where the directive appears */
+  line: number;
+}
+
+export interface FunctionWithDirective {
+  /** Function name (or 'default' for anonymous default exports) */
+  name: string;
+  /** The directive found in the function body */
+  directive: string;
+  /** 1-based line number of the directive */
+  directiveLine: number;
+  /** Start offset of the function in the source */
+  start: number;
+  /** End offset of the function in the source */
+  end: number;
+  /** Start offset of the function body block (after the '{') */
+  bodyStart: number;
+  /** End offset of the function body block (the '}') */
+  bodyEnd: number;
+  /** Content between { and } of the function body */
+  bodyContent: string;
+  /** 'export ', 'export default ', or '' */
+  prefix: string;
+  /** Whether this is an arrow function */
+  isArrow: boolean;
+  /** The function signature (everything before the body '{') */
+  declaration: string;
+}
+
+// ---------------------------------------------------------------------------
+// File-level directive detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect a file-level directive ('use client', 'use server', etc.).
+ *
+ * Per the ECMAScript spec, directives are string literal expression
+ * statements at the start of a program body (before any non-directive
+ * statements). This function checks the AST `Program.body` for
+ * `ExpressionStatement` nodes whose expression is a `Literal` string
+ * matching a known directive.
+ *
+ * Returns the first matching directive, or null if none found.
+ */
+export function detectFileDirective(
+  code: string,
+  directives: string[] = ['use client', 'use server']
+): FileDirective | null {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let ast: any;
+  try {
+    ast = jsxParser.parse(code, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      locations: true,
+    });
+  } catch {
+    // If the file fails to parse (e.g. TypeScript syntax), fall back to
+    // a safe line-by-line check that only considers lines before any
+    // non-comment, non-whitespace, non-directive content.
+    return detectFileDirectiveFallback(code, directives);
+  }
+
+  for (const node of ast.body) {
+    if (
+      node.type === 'ExpressionStatement' &&
+      node.expression.type === 'Literal' &&
+      typeof node.expression.value === 'string'
+    ) {
+      if (directives.includes(node.expression.value)) {
+        return {
+          directive: node.expression.value,
+          line: node.loc.start.line,
+        };
+      }
+    } else {
+      // Directives must appear before any non-directive statements
+      break;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Fallback for TypeScript files that acorn cannot parse.
+ *
+ * Scans lines from the top of the file. Skips blank lines and comments.
+ * Checks if the first real statement is a directive string literal.
+ */
+function detectFileDirectiveFallback(code: string, directives: string[]): FileDirective | null {
+  const lines = code.split('\n');
+  let inBlockComment = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i].trim();
+
+    // Handle block comments
+    if (inBlockComment) {
+      const endIdx = line.indexOf('*/');
+      if (endIdx === -1) continue;
+      line = line.slice(endIdx + 2).trim();
+      inBlockComment = false;
+      if (!line) continue;
+    }
+
+    // Skip blank lines
+    if (!line) continue;
+
+    // Skip line comments
+    if (line.startsWith('//')) continue;
+
+    // Skip block comment start
+    if (line.startsWith('/*')) {
+      const endIdx = line.indexOf('*/', 2);
+      if (endIdx === -1) {
+        inBlockComment = true;
+        continue;
+      }
+      line = line.slice(endIdx + 2).trim();
+      if (!line) continue;
+    }
+
+    // Check for directive
+    for (const dir of directives) {
+      // Match 'directive' or "directive" optionally followed by ;
+      if (
+        line === `'${dir}'` ||
+        line === `'${dir}';` ||
+        line === `"${dir}"` ||
+        line === `"${dir}";`
+      ) {
+        return { directive: dir, line: i + 1 };
+      }
+    }
+
+    // First non-comment, non-blank line is not a directive — stop
+    break;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Function-body directive detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all functions in the source code that contain a directive
+ * (e.g. 'use cache', 'use dynamic') as their first body statement.
+ *
+ * Parses the source with acorn and walks the AST looking for function
+ * declarations and arrow function expressions whose body is a
+ * BlockStatement with a directive prologue.
+ *
+ * Returns an array of function info objects, sorted by position
+ * (descending) for safe end-to-start replacement.
+ */
+export function findFunctionsWithDirective(
+  code: string,
+  directive: string
+): FunctionWithDirective[] {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let ast: any;
+  try {
+    ast = jsxParser.parse(code, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      locations: true,
+    });
+  } catch {
+    // TypeScript fallback: return empty — callers should use the quick
+    // regex check first and skip non-matching files anyway
+    return findFunctionsWithDirectiveFallback(code, directive);
+  }
+
+  const results: FunctionWithDirective[] = [];
+  walkAst(ast, code, directive, results, []);
+
+  // Sort descending by start position for safe end-to-start replacement
+  results.sort((a, b) => b.start - a.start);
+  return results;
+}
+
+/**
+ * Recursive AST walker that finds functions with a directive in their body.
+ */
+function walkAst(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  code: string,
+  directive: string,
+  results: FunctionWithDirective[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ancestors: any[]
+): void {
+  if (!node || typeof node !== 'object') return;
+
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      walkAst(child, code, directive, results, ancestors);
+    }
+    return;
+  }
+
+  if (!node.type) return;
+
+  // Check function declarations and expressions
+  if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression') {
+    checkFunctionBody(node, code, directive, results, ancestors);
+  }
+
+  // Check arrow functions with block bodies
+  if (node.type === 'ArrowFunctionExpression' && node.body && node.body.type === 'BlockStatement') {
+    checkFunctionBody(node, code, directive, results, ancestors);
+  }
+
+  // Walk children
+  const newAncestors = [...ancestors, node];
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'loc' || key === 'start' || key === 'end') continue;
+    const child = node[key];
+    if (child && typeof child === 'object') {
+      walkAst(child, code, directive, results, newAncestors);
+    }
+  }
+}
+
+/**
+ * Check if a function's body starts with the target directive.
+ */
+function checkFunctionBody(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  code: string,
+  directive: string,
+  results: FunctionWithDirective[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ancestors: any[]
+): void {
+  const body = node.type === 'ArrowFunctionExpression' ? node.body : node.body;
+  if (!body || body.type !== 'BlockStatement' || body.body.length === 0) return;
+
+  // Check the first statement for a directive
+  const firstStmt = body.body[0];
+  if (
+    firstStmt.type !== 'ExpressionStatement' ||
+    firstStmt.expression.type !== 'Literal' ||
+    firstStmt.expression.value !== directive
+  ) {
+    return;
+  }
+
+  // Determine function metadata from AST context
+  const parent = ancestors[ancestors.length - 1];
+  const grandparent = ancestors.length >= 2 ? ancestors[ancestors.length - 2] : null;
+
+  let name = '';
+  let prefix = '';
+  const isArrow = node.type === 'ArrowFunctionExpression';
+  let funcStart = node.start;
+  let funcEnd = node.end;
+
+  if (node.type === 'FunctionDeclaration') {
+    name = node.id?.name || 'default';
+
+    // Check for export
+    if (parent?.type === 'ExportNamedDeclaration') {
+      prefix = 'export ';
+      funcStart = parent.start;
+      funcEnd = parent.end;
+    } else if (parent?.type === 'ExportDefaultDeclaration') {
+      prefix = 'export default ';
+      funcStart = parent.start;
+      funcEnd = parent.end;
+    }
+  } else if (node.type === 'ArrowFunctionExpression') {
+    // Arrow in variable declaration: const name = async () => {}
+    if (parent?.type === 'VariableDeclarator' && parent.id?.name) {
+      name = parent.id.name;
+      // Include the full variable declaration
+      if (grandparent?.type === 'VariableDeclaration') {
+        funcStart = grandparent.start;
+        funcEnd = grandparent.end;
+      }
+    }
+  } else if (node.type === 'FunctionExpression') {
+    // Function expression in variable: const name = async function() {}
+    name = node.id?.name || '';
+    if (parent?.type === 'VariableDeclarator' && parent.id?.name) {
+      name = parent.id.name;
+      if (grandparent?.type === 'VariableDeclaration') {
+        funcStart = grandparent.start;
+        funcEnd = grandparent.end;
+      }
+    }
+  }
+
+  if (!name) return; // Skip anonymous functions we can't name
+
+  // Extract the body content (between the braces)
+  const bodyStart = body.start + 1; // after '{'
+  const bodyEnd = body.end - 1; // before '}'
+  const bodyContent = code.slice(bodyStart, bodyEnd);
+
+  // Extract declaration (everything before the body '{')
+  const declaration = code.slice(funcStart, body.start).trim();
+
+  results.push({
+    name,
+    directive,
+    directiveLine: firstStmt.loc.start.line,
+    start: funcStart,
+    end: funcEnd,
+    bodyStart,
+    bodyEnd,
+    bodyContent,
+    prefix,
+    isArrow,
+    declaration,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// TypeScript fallback for function-body directives
+// ---------------------------------------------------------------------------
+
+/**
+ * Fallback that uses regex to find functions with directives when acorn
+ * cannot parse the file (TypeScript with type annotations).
+ *
+ * This is less precise but handles common patterns. The regex approach
+ * is only used as a fallback — pure JS/JSX files always use the AST path.
+ */
+function findFunctionsWithDirectiveFallback(
+  code: string,
+  directive: string
+): FunctionWithDirective[] {
+  const results: FunctionWithDirective[] = [];
+  const directivePattern = new RegExp(`['"]${escapeRegex(directive)}['"]`);
+
+  // Quick bail-out
+  if (!directivePattern.test(code)) return results;
+
+  // Pattern 1: function declarations
+  const fnDeclPattern =
+    /(?:(export\s+default\s+|export\s+))?async\s+function\s+(\w+)\s*\([^)]*\)\s*\{/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = fnDeclPattern.exec(code)) !== null) {
+    const prefix = match[1]?.trim() || '';
+    const name = match[2];
+    const bodyStart = match.index + match[0].length;
+    const bodyEnd = findMatchingBraceFallback(code, bodyStart - 1);
+    if (bodyEnd === -1) continue;
+
+    const bodyContent = code.slice(bodyStart, bodyEnd);
+    // Check that the directive is the first meaningful statement
+    const trimmedBody = bodyContent.trimStart();
+    if (!trimmedBody.startsWith(`'${directive}'`) && !trimmedBody.startsWith(`"${directive}"`))
+      continue;
+
+    const directiveLine =
+      code.slice(0, bodyStart).split('\n').length +
+      bodyContent.slice(0, bodyContent.indexOf(directive)).split('\n').length -
+      1;
+
+    results.push({
+      name,
+      directive,
+      directiveLine,
+      start: match.index,
+      end: bodyEnd + 1,
+      bodyStart,
+      bodyEnd,
+      bodyContent,
+      prefix: prefix ? prefix + ' ' : '',
+      isArrow: false,
+      declaration: code.slice(match.index, bodyStart - 1).trimEnd(),
+    });
+  }
+
+  // Pattern 2: arrow functions
+  const arrowPattern = /(?:const|let|var)\s+(\w+)\s*=\s*async\s*(\([^)]*\)|[^=]*?)\s*=>\s*\{/g;
+  while ((match = arrowPattern.exec(code)) !== null) {
+    const name = match[1];
+    const bodyStart = match.index + match[0].length;
+    const bodyEnd = findMatchingBraceFallback(code, bodyStart - 1);
+    if (bodyEnd === -1) continue;
+
+    const bodyContent = code.slice(bodyStart, bodyEnd);
+    const trimmedBody = bodyContent.trimStart();
+    if (!trimmedBody.startsWith(`'${directive}'`) && !trimmedBody.startsWith(`"${directive}"`))
+      continue;
+
+    const directiveLine =
+      code.slice(0, bodyStart).split('\n').length +
+      bodyContent.slice(0, bodyContent.indexOf(directive)).split('\n').length -
+      1;
+
+    results.push({
+      name,
+      directive,
+      directiveLine,
+      start: match.index,
+      end: bodyEnd + 1,
+      bodyStart,
+      bodyEnd,
+      bodyContent,
+      prefix: '',
+      isArrow: true,
+      declaration: code.slice(match.index, bodyStart - 1).trimEnd(),
+    });
+  }
+
+  results.sort((a, b) => b.start - a.start);
+  return results;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find matching closing brace — same algorithm as cache-transform.ts
+ * but kept here for the fallback path only.
+ */
+function findMatchingBraceFallback(code: string, openPos: number): number {
+  let depth = 1;
+  let i = openPos + 1;
+
+  while (i < code.length && depth > 0) {
+    const ch = code[i];
+
+    if (ch === "'" || ch === '"') {
+      i = skipStringFallback(code, i);
+      continue;
+    }
+    if (ch === '`') {
+      i = skipTemplateFallback(code, i);
+      continue;
+    }
+    if (ch === '/' && code[i + 1] === '/') {
+      i = code.indexOf('\n', i);
+      if (i === -1) return -1;
+      i++;
+      continue;
+    }
+    if (ch === '/' && code[i + 1] === '*') {
+      i = code.indexOf('*/', i + 2);
+      if (i === -1) return -1;
+      i += 2;
+      continue;
+    }
+
+    if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    i++;
+  }
+
+  return depth === 0 ? i - 1 : -1;
+}
+
+function skipStringFallback(code: string, start: number): number {
+  const quote = code[start];
+  let i = start + 1;
+  while (i < code.length) {
+    if (code[i] === '\\') {
+      i += 2;
+      continue;
+    }
+    if (code[i] === quote) return i + 1;
+    i++;
+  }
+  return i;
+}
+
+function skipTemplateFallback(code: string, start: number): number {
+  let i = start + 1;
+  while (i < code.length) {
+    if (code[i] === '\\') {
+      i += 2;
+      continue;
+    }
+    if (code[i] === '`') return i + 1;
+    if (code[i] === '$' && code[i + 1] === '{') {
+      i = findMatchingBraceFallback(code, i + 1) + 1;
+      continue;
+    }
+    i++;
+  }
+  return i;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: quick regex check (for fast bail-out before AST parsing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Quick regex check for whether code contains a directive string.
+ * Use as a fast bail-out before calling the AST-based functions.
+ */
+export function containsDirective(code: string, directive: string): boolean {
+  return code.includes(directive);
+}

package/src/utils/format.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared formatting utilities.
+ */
+
+/** Format a byte count as a human-readable string (e.g. "1.50 kB"). */
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}

package/src/utils/startup-timer.ts

@@ -0,0 +1,102 @@
+/**
+ * Startup timer — records named phases with their durations.
+ *
+ * Used by the plugin system to instrument cold start and report a
+ * timing breakdown in dev mode. Zero overhead in production (disabled).
+ *
+ * See design/18-build-system.md, TIM-155.
+ */
+
+import { performance } from 'node:perf_hooks';
+
+export interface PhaseRecord {
+  name: string;
+  startMs: number;
+  durationMs: number;
+}
+
+export interface StartupTimer {
+  /** Mark the beginning of a named phase. */
+  start(phase: string): void;
+  /** Mark the end of a named phase. Returns duration in ms. */
+  end(phase: string): number;
+  /** Get all completed phase records, ordered by start time. */
+  getPhases(): PhaseRecord[];
+  /** Total elapsed time from first start() to last end(). */
+  totalMs(): number;
+  /** Format a human-readable summary string. */
+  formatSummary(): string;
+}
+
+/**
+ * Create a startup timer that records phase durations.
+ */
+export function createStartupTimer(): StartupTimer {
+  const pending = new Map<string, number>();
+  const phases: PhaseRecord[] = [];
+
+  return {
+    start(phase: string): void {
+      pending.set(phase, performance.now());
+    },
+
+    end(phase: string): number {
+      const startMs = pending.get(phase);
+      if (startMs === undefined) {
+        return 0;
+      }
+      pending.delete(phase);
+      const durationMs = performance.now() - startMs;
+      phases.push({ name: phase, startMs, durationMs });
+      return durationMs;
+    },
+
+    getPhases(): PhaseRecord[] {
+      return [...phases].sort((a, b) => a.startMs - b.startMs);
+    },
+
+    totalMs(): number {
+      if (phases.length === 0) return 0;
+      const sorted = this.getPhases();
+      const first = sorted[0];
+      const last = sorted[sorted.length - 1];
+      return last.startMs + last.durationMs - first.startMs;
+    },
+
+    formatSummary(): string {
+      const sorted = this.getPhases();
+      if (sorted.length === 0) return 'No phases recorded.';
+
+      const lines = sorted.map((p) => {
+        const ms = p.durationMs.toFixed(1);
+        return `  ${p.name.padEnd(30)} ${ms.padStart(8)}ms`;
+      });
+
+      const total = this.totalMs().toFixed(1);
+      lines.push(`  ${'total'.padEnd(30)} ${total.padStart(8)}ms`);
+
+      return ['[timber] startup timing:', ...lines].join('\n');
+    },
+  };
+}
+
+/**
+ * No-op timer for production builds — all methods are empty.
+ */
+export function createNoopTimer(): StartupTimer {
+  return {
+    start() {},
+    end() {
+      return 0;
+    },
+    getPhases() {
+      return [];
+    },
+    totalMs() {
+      return 0;
+    },
+    formatSummary() {
+      return '';
+    },
+  };
+}