@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/fonts/ast.ts

@@ -1,15 +1,22 @@
 /**
- * Acorn-based AST utilities for extracting static font configs from source code.
+ * AST utilities for extracting static font configs from source code.
+ * Uses OXC via Vite's `parseAst` — handles JS/JSX/TS/TSX natively.
  *
- * Replaces the fragile regex-based extraction in fonts.ts and local.ts.
- * Uses acorn (already a Vite dependency) for robust parsing that handles
- * comments, trailing commas, multi-line configs, and other edge cases
- * the regex approach missed.
+ * Provides two tiers of API:
+ *
+ * 1. **Source-text helpers** (`extractFontConfigAst`, `extractLocalFontConfigAst`,
+ *    `detectDynamicFontCallAst`) — parse a snippet and return extracted config.
+ *    Still used by tests and callers that have only a string.
+ *
+ * 2. **AST-node helpers** (`extractGoogleFontConfigFromNode`,
+ *    `extractLocalFontConfigFromNode`, `findFontCallSites`) — operate on
+ *    nodes from an already-parsed Program so the transform hook can share
+ *    one parse with all analysis steps.
  *
  * Design doc: 24-fonts.md §"Step 1: Static Analysis"
  */
 
-import { parse } from 'acorn';
+import { parseAst as viteParseAst } from 'vite';
 import type { GoogleFontConfig } from './types.js';
 import type { LocalFontConfig, LocalFontSrc } from './types.js';
 
@@ -46,20 +53,34 @@ interface IdentifierNode extends AstNode {
   name: string;
 }
 
+// ── Offset → line/column helper ──────────────────────────────────────────────
+
+/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
+function offsetToLineColumn(source: string, offset: number): { line: number; column: number } {
+  let line = 1;
+  let lastNewline = -1;
+  for (let i = 0; i < offset; i++) {
+    if (source[i] === '\n') {
+      line++;
+      lastNewline = i;
+    }
+  }
+  return { line, column: offset - lastNewline - 1 };
+}
+
 // ── Core AST extraction helpers ──────────────────────────────────────────────
 
 /**
  * Parse a JavaScript expression string into an AST node.
  *
- * Wraps the expression in parens so acorn treats it as an expression statement.
+ * Wraps the expression in parens so OXC (via vite.parseAst) treats it as an expression statement.
  * Returns null if parsing fails.
  */
 function parseExpression(source: string): AstNode | null {
   try {
-    const ast = parse(`(${source})`, {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-    }) as unknown as { body: Array<{ expression: AstNode }> };
+    const ast = viteParseAst(`(${source})`, { lang: 'tsx' }) as unknown as {
+      body: Array<{ expression: AstNode }>;
+    };
     return ast.body[0]?.expression ?? null;
   } catch {
     return null;
@@ -293,7 +314,7 @@ export function extractLocalFontConfigAst(callSource: string): LocalFontConfig |
  * Detect if source code contains dynamic/computed font function calls
  * that cannot be statically analyzed.
  *
- * Uses acorn to parse the full source and inspect CallExpression nodes.
+ * Uses OXC (via vite.parseAst) to parse the full source and inspect CallExpression nodes.
  * Returns the offending expression string if found, null if all calls are static.
  */
 export function detectDynamicFontCallAst(source: string, importedNames: string[]): string | null {
@@ -301,10 +322,7 @@ export function detectDynamicFontCallAst(source: string, importedNames: string[]
 
   let ast;
   try {
-    ast = parse(source, {
-      ecmaVersion: 'latest',
-      sourceType: 'module',
-    }) as unknown as { body: AstNode[] };
+    ast = viteParseAst(source, { lang: 'tsx' }) as unknown as { body: AstNode[] };
   } catch {
     // If we can't parse the source at all, fall back to no detection
     return null;
@@ -357,3 +375,494 @@ function walkForDynamicCalls(node: AstNode, names: Set<string>, source: string):
 
   return null;
 }
+
+// ── AST-node-level config extraction ─────────────────────────────────────────
+//
+// These work on an already-parsed ObjectExpression node so the transform
+// hook can share one OXC (via vite.parseAst) parse of the full source file with all analysis
+// steps (TIM-827).
+
+/**
+ * Extract a GoogleFontConfig from an ObjectExpression AST node.
+ *
+ * This is the node-level equivalent of `extractFontConfigAst` — it skips
+ * the parse step because the caller already has a parsed Program.
+ */
+export function extractGoogleFontConfigFromNode(node: AstNode): GoogleFontConfig | null {
+  if (node.type !== 'ObjectExpression') return null;
+  return extractGoogleConfig(node as ObjectExpressionNode);
+}
+
+/**
+ * Extract a LocalFontConfig from an ObjectExpression AST node.
+ */
+export function extractLocalFontConfigFromNode(node: AstNode): LocalFontConfig | null {
+  if (node.type !== 'ObjectExpression') return null;
+  return extractLocalConfig(node as ObjectExpressionNode);
+}
+
+/** Shared implementation for GoogleFontConfig extraction from an object node. */
+function extractGoogleConfig(objNode: ObjectExpressionNode): GoogleFontConfig {
+  const props = objectProperties(objNode);
+  const config: GoogleFontConfig = {};
+
+  const subsetsNode = props.get('subsets');
+  if (subsetsNode) {
+    const arr = extractStringArray(subsetsNode);
+    if (arr) config.subsets = arr;
+  }
+
+  const weightNode = props.get('weight');
+  if (weightNode) {
+    const arr = extractStringArray(weightNode);
+    if (arr) {
+      config.weight = arr;
+    } else {
+      const s = extractString(weightNode);
+      if (s !== undefined) config.weight = s;
+    }
+  }
+
+  const displayNode = props.get('display');
+  if (displayNode) {
+    const s = extractString(displayNode);
+    if (s !== undefined) config.display = s as GoogleFontConfig['display'];
+  }
+
+  const variableNode = props.get('variable');
+  if (variableNode) {
+    const s = extractString(variableNode);
+    if (s !== undefined) config.variable = s;
+  }
+
+  const styleNode = props.get('style');
+  if (styleNode) {
+    const arr = extractStringArray(styleNode);
+    if (arr) {
+      config.style = arr;
+    } else {
+      const s = extractString(styleNode);
+      if (s !== undefined) config.style = s;
+    }
+  }
+
+  const preloadNode = props.get('preload');
+  if (preloadNode) {
+    const b = extractBoolean(preloadNode);
+    if (b !== undefined) config.preload = b;
+  }
+
+  return config;
+}
+
+/** Shared implementation for LocalFontConfig extraction from an object node. */
+function extractLocalConfig(objNode: ObjectExpressionNode): LocalFontConfig | null {
+  const props = objectProperties(objNode);
+
+  const displayNode = props.get('display');
+  const display = displayNode
+    ? (extractString(displayNode) as LocalFontConfig['display'])
+    : undefined;
+
+  const variableNode = props.get('variable');
+  const variable = variableNode ? extractString(variableNode) : undefined;
+
+  const familyNode = props.get('family');
+  const family = familyNode ? extractString(familyNode) : undefined;
+
+  const srcNode = props.get('src');
+  if (!srcNode) return null;
+
+  const srcString = extractString(srcNode);
+  if (srcString !== undefined) {
+    return { src: srcString, display, variable, family };
+  }
+
+  if (srcNode.type === 'ArrayExpression') {
+    const arr = srcNode as ArrayExpressionNode;
+    const entries: LocalFontSrc[] = [];
+    for (const elem of arr.elements) {
+      const entry = extractLocalFontSrcEntry(elem);
+      if (!entry) return null;
+      entries.push(entry);
+    }
+    if (entries.length === 0) return null;
+    return { src: entries, display, variable, family };
+  }
+
+  return null;
+}
+
+// ── Font module specifiers ───────────────────────────────────────────────────
+
+const GOOGLE_FONT_SOURCES = new Set([
+  '@timber/fonts/google',
+  '@timber-js/app/fonts/google',
+  'next/font/google',
+]);
+
+const LOCAL_FONT_SOURCES = new Set([
+  '@timber/fonts/local',
+  '@timber-js/app/fonts/local',
+  'next/font/local',
+]);
+
+// ── Parsed source types ──────────────────────────────────────────────────────
+
+/** A font import binding discovered from an ImportDeclaration. */
+export interface FontBinding {
+  /** The local name used in the module (after `as`, if present). */
+  localName: string;
+  /**
+   * The original exported name (before `as`). For Google fonts this is
+   * the PascalCase_With_Underscores name that maps to the family. For
+   * local fonts (`default` import), this is `'default'`.
+   */
+  importedName: string;
+  /** `'google'` or `'local'`. */
+  provider: 'google' | 'local';
+  /** The AST node of the ImportDeclaration (for removal via magic-string). */
+  importNode: AstNode & { start: number; end: number };
+}
+
+/** A font function call site discovered from a CallExpression. */
+export interface FontCallSite {
+  /** The binding that this call references. */
+  binding: FontBinding;
+  /**
+   * The variable name this call is assigned to, if the call appears in a
+   * VariableDeclarator. `null` for bare expression statements.
+   */
+  assignedName: string | null;
+  /** The first argument AST node (expected to be an ObjectExpression). */
+  configNode: AstNode;
+  /**
+   * The outermost AST node to replace. For a VariableDeclaration with a
+   * single declarator this is the full declaration; for a bare expression
+   * statement it is the ExpressionStatement. The transform replaces
+   * `source[replaceStart..replaceEnd]`.
+   */
+  replaceStart: number;
+  replaceEnd: number;
+  /** Line number (1-based) of the call for error messages. */
+  line: number;
+  /** Column (0-based) of the call for error messages. */
+  column: number;
+}
+
+/** Result of `findFontCallSites` — everything the transform needs. */
+export interface FontAnalysis {
+  bindings: FontBinding[];
+  callSites: FontCallSite[];
+  /** Import nodes that should be removed (deduplicated). */
+  importNodesToRemove: Array<{ start: number; end: number }>;
+  /** First dynamic call expression text, or `null`. */
+  dynamicCall: string | null;
+  /**
+   * Font calls found in nested scopes (functions, if-blocks, etc.).
+   * These are errors — font calls must be module-level.
+   */
+  nestedCalls: Array<{ name: string; line: number; column: number }>;
+}
+
+interface PositionedNode extends AstNode {
+  start: number;
+  end: number;
+}
+
+interface ImportDeclarationNode extends PositionedNode {
+  type: 'ImportDeclaration';
+  source: LiteralNode & { value: string };
+  specifiers: Array<
+    PositionedNode & {
+      type: string;
+      local: IdentifierNode;
+      imported?: IdentifierNode;
+    }
+  >;
+}
+
+interface CallExpressionNode extends PositionedNode {
+  type: 'CallExpression';
+  callee: AstNode;
+  arguments: PositionedNode[];
+}
+
+interface VariableDeclaratorNode extends PositionedNode {
+  type: 'VariableDeclarator';
+  id: PositionedNode;
+  init: PositionedNode | null;
+}
+
+interface VariableDeclarationNode extends PositionedNode {
+  type: 'VariableDeclaration';
+  declarations: VariableDeclaratorNode[];
+}
+
+interface ExpressionStatementNode extends PositionedNode {
+  type: 'ExpressionStatement';
+  expression: PositionedNode;
+}
+
+interface ExportNamedDeclarationNode extends PositionedNode {
+  type: 'ExportNamedDeclaration';
+  declaration: VariableDeclarationNode | ExpressionStatementNode | null;
+}
+
+// ── Type guards for AST narrowing ────────────────────────────────────────────
+//
+// OXC's parsed nodes all share the base `PositionedNode` shape with
+// `type: string`. TypeScript can't narrow a union that includes a
+// `string`-typed catch-all, so we use explicit type guards instead of
+// bare `.type ===` checks.
+
+function isImportDeclaration(node: PositionedNode): node is ImportDeclarationNode {
+  return node.type === 'ImportDeclaration';
+}
+
+function isVariableDeclaration(node: PositionedNode): node is VariableDeclarationNode {
+  return node.type === 'VariableDeclaration';
+}
+
+function isExpressionStatement(node: PositionedNode): node is ExpressionStatementNode {
+  return node.type === 'ExpressionStatement';
+}
+
+function isExportNamedDeclaration(node: PositionedNode): node is ExportNamedDeclarationNode {
+  return node.type === 'ExportNamedDeclaration';
+}
+
+function isCallExpression(node: PositionedNode): node is CallExpressionNode {
+  return node.type === 'CallExpression';
+}
+
+function isIdentifier(node: AstNode): node is IdentifierNode {
+  return node.type === 'Identifier';
+}
+
+interface ProgramNode extends PositionedNode {
+  type: 'Program';
+  body: PositionedNode[];
+}
+
+/**
+ * Parse a full source file and find all font imports and call sites.
+ *
+ * Returns `null` if the source has no font-related imports.
+ */
+export function findFontCallSites(source: string): FontAnalysis | null {
+  let program: ProgramNode;
+  try {
+    program = viteParseAst(source, { lang: 'tsx' }) as unknown as ProgramNode;
+  } catch {
+    return null;
+  }
+
+  // Step 1: Find all font import declarations and build the bindings list.
+  const bindings: FontBinding[] = [];
+  const importNodesToRemove: Array<{ start: number; end: number }> = [];
+
+  for (const stmt of program.body) {
+    if (!isImportDeclaration(stmt)) continue;
+    const importDecl = stmt;
+    const specSource = importDecl.source.value;
+
+    let provider: 'google' | 'local' | null = null;
+    if (GOOGLE_FONT_SOURCES.has(specSource)) provider = 'google';
+    else if (LOCAL_FONT_SOURCES.has(specSource)) provider = 'local';
+    if (!provider) continue;
+
+    for (const spec of importDecl.specifiers) {
+      if (spec.type === 'ImportSpecifier' && provider === 'google') {
+        bindings.push({
+          localName: spec.local.name,
+          importedName: spec.imported?.name ?? spec.local.name,
+          provider,
+          importNode: importDecl,
+        });
+      } else if (spec.type === 'ImportDefaultSpecifier' && provider === 'local') {
+        bindings.push({
+          localName: spec.local.name,
+          importedName: 'default',
+          provider,
+          importNode: importDecl,
+        });
+      }
+      // ImportNamespaceSpecifier (`import * as fonts from ...`) is not
+      // currently supported — the old regex didn't handle it either.
+      // If we add it later, we'd need to also handle `fonts.Inter(...)`
+      // member expressions in the call-site walk.
+    }
+
+    importNodesToRemove.push({ start: stmt.start, end: stmt.end });
+  }
+
+  if (bindings.length === 0) return null;
+
+  // Step 2: Walk the AST for CallExpression nodes whose callee is a font binding.
+  const bindingsByName = new Map(bindings.map((b) => [b.localName, b]));
+  const callSites: FontCallSite[] = [];
+  let dynamicCall: string | null = null;
+
+  for (const stmt of program.body) {
+    // Unwrap `export const roboto = Roboto(...)` — the AST wraps the
+    // VariableDeclaration inside an ExportNamedDeclaration node.
+    const effectiveStmt =
+      isExportNamedDeclaration(stmt) && stmt.declaration ? stmt.declaration : stmt;
+
+    // VariableDeclaration: `const inter = Inter({ ... })`
+    if (isVariableDeclaration(effectiveStmt)) {
+      for (const declarator of effectiveStmt.declarations) {
+        if (!declarator.init) continue;
+        if (!isCallExpression(declarator.init)) continue;
+        const call = declarator.init;
+        const site = matchCallExpression(call, bindingsByName, source);
+        if (!site) continue;
+
+        if (site === 'dynamic') {
+          if (!dynamicCall && isIdentifier(call.callee)) {
+            const argStart = call.arguments[0].start;
+            const argEnd = call.arguments[0].end;
+            dynamicCall = `${call.callee.name}(${source.slice(argStart, argEnd)})`;
+          }
+          continue;
+        }
+
+        const assignedName = isIdentifier(declarator.id) ? declarator.id.name : null;
+
+        const { line, column } = offsetToLineColumn(source, call.start);
+        callSites.push({
+          binding: site.binding,
+          assignedName,
+          configNode: site.configNode,
+          replaceStart: call.start,
+          replaceEnd: call.end,
+          line,
+          column,
+        });
+      }
+    }
+
+    // ExpressionStatement: `Inter({ ... })` as a bare call
+    if (isExpressionStatement(effectiveStmt)) {
+      if (isCallExpression(effectiveStmt.expression)) {
+        const call = effectiveStmt.expression;
+        const site = matchCallExpression(call, bindingsByName, source);
+        if (site && site !== 'dynamic') {
+          const { line, column } = offsetToLineColumn(source, call.start);
+          callSites.push({
+            binding: site.binding,
+            assignedName: null,
+            configNode: site.configNode,
+            replaceStart: effectiveStmt.start,
+            replaceEnd: effectiveStmt.end,
+            line,
+            column,
+          });
+        } else if (site === 'dynamic' && !dynamicCall && isIdentifier(call.callee)) {
+          const argStart = call.arguments[0].start;
+          const argEnd = call.arguments[0].end;
+          dynamicCall = `${call.callee.name}(${source.slice(argStart, argEnd)})`;
+        }
+      }
+    }
+  }
+
+  // Step 3: Walk nested scopes to find font calls that aren't module-level.
+  // Font calls must be at module scope (same constraint as Next.js).
+  // If the import is removed but a nested call remains, it's a ReferenceError.
+  const nestedCalls: Array<{ name: string; line: number; column: number }> = [];
+  for (const stmt of program.body) {
+    if (stmt.type === 'ImportDeclaration') continue;
+    walkForNestedFontCalls(stmt as AstNode, bindingsByName, source, nestedCalls, false);
+  }
+
+  return { bindings, callSites, importNodesToRemove, dynamicCall, nestedCalls };
+}
+
+/**
+ * Recursively walk an AST node looking for font CallExpressions in nested
+ * scopes (function bodies, if-blocks, loops, etc.). Font calls must be
+ * module-level; nested calls are collected as errors.
+ *
+ * `isNested` tracks whether we've descended past the top-level statement.
+ * Top-level VariableDeclarations and ExpressionStatements are already
+ * handled by the main loop in `findFontCallSites`, so we only flag calls
+ * found deeper.
+ */
+function walkForNestedFontCalls(
+  node: AstNode,
+  bindings: Map<string, FontBinding>,
+  source: string,
+  out: Array<{ name: string; line: number; column: number }>,
+  isNested: boolean
+): void {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.type === 'CallExpression') {
+    const callee = node.callee as AstNode;
+    if (isNested && callee.type === 'Identifier' && bindings.has((callee as IdentifierNode).name)) {
+      const pos = offsetToLineColumn(source, (node as PositionedNode).start);
+      out.push({ name: (callee as IdentifierNode).name, line: pos.line, column: pos.column });
+      return; // Don't recurse into this call's children
+    }
+  }
+
+  // These node types introduce a nested scope — any font call inside is an error.
+  const scopeTypes = new Set([
+    'FunctionDeclaration',
+    'FunctionExpression',
+    'ArrowFunctionExpression',
+    'IfStatement',
+    'ForStatement',
+    'ForInStatement',
+    'ForOfStatement',
+    'WhileStatement',
+    'DoWhileStatement',
+    'SwitchStatement',
+    'TryStatement',
+    'BlockStatement',
+    'ClassDeclaration',
+    'ClassExpression',
+  ]);
+  const enterNested = isNested || scopeTypes.has(node.type);
+
+  for (const key of Object.keys(node)) {
+    if (key === 'type') continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === 'object' && (item as AstNode).type) {
+          walkForNestedFontCalls(item as AstNode, bindings, source, out, enterNested);
+        }
+      }
+    } else if (child && typeof child === 'object' && (child as AstNode).type) {
+      walkForNestedFontCalls(child as AstNode, bindings, source, out, enterNested);
+    }
+  }
+}
+
+/**
+ * Match a CallExpression against the font bindings map.
+ *
+ * Returns the binding + config node if the call is a static font call,
+ * `'dynamic'` if it's a font call with a non-object argument, or `null`
+ * if the callee doesn't match any font binding.
+ */
+function matchCallExpression(
+  call: CallExpressionNode,
+  bindings: Map<string, FontBinding>,
+  _source: string
+): { binding: FontBinding; configNode: AstNode } | 'dynamic' | null {
+  if (!isIdentifier(call.callee)) return null;
+  const calleeName = call.callee.name;
+  const binding = bindings.get(calleeName);
+  if (!binding) return null;
+
+  const args = call.arguments;
+  if (args.length === 0 || args[0].type !== 'ObjectExpression') {
+    return 'dynamic';
+  }
+
+  return { binding, configNode: args[0] };
+}