@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.148

package/src/fonts/ast-walk.ts

@@ -0,0 +1,235 @@
+/**
+ * Generic AST node types and recursive walkers for font static analysis.
+ *
+ * `ast.ts` owns parsing, config extraction, and call-site discovery; this
+ * module owns the recursive walks that police where font bindings may be
+ * used (dynamic configs, nested scopes, unconsumed references). Split out
+ * to keep `ast.ts` under the 500-code-line limit (design/18-build-system.md).
+ *
+ * Design doc: 24-fonts.md §"Step 1: Static Analysis"
+ */
+
+// ── AST node types (minimal subset of estree) ────────────────────────────────
+
+export interface AstNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface IdentifierNode extends AstNode {
+  type: 'Identifier';
+  name: string;
+}
+
+export interface PositionedNode extends AstNode {
+  start: number;
+  end: number;
+}
+
+/** A flagged reference/usage for build-error reporting. */
+export interface FlaggedUsage {
+  name: string;
+  line: number;
+  column: number;
+}
+
+// ── Offset → line/column helper ──────────────────────────────────────────────
+
+/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
+export 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 };
+}
+
+// ── Shared recursion plumbing ────────────────────────────────────────────────
+
+/**
+ * Invoke `visit` on every direct child AST node of `node` (array elements
+ * and object-valued properties with a `type` field).
+ */
+export function walkChildNodes(node: AstNode, visit: (child: AstNode) => void): void {
+  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) {
+          visit(item as AstNode);
+        }
+      }
+    } else if (child && typeof child === 'object' && (child as AstNode).type) {
+      visit(child as AstNode);
+    }
+  }
+}
+
+// ── Walkers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively walk the AST looking for CallExpression nodes where
+ * the callee is one of the imported font names and the first argument
+ * is not an ObjectExpression (i.e. it's dynamic).
+ */
+export function walkForDynamicCalls(
+  node: AstNode,
+  names: ReadonlySet<string>,
+  source: string
+): string | null {
+  if (!node || typeof node !== 'object') return null;
+
+  if (node.type === 'CallExpression') {
+    const callee = node.callee as AstNode;
+    if (callee.type === 'Identifier' && names.has((callee as IdentifierNode).name)) {
+      const args = node.arguments as AstNode[];
+      if (args.length > 0 && args[0].type !== 'ObjectExpression') {
+        // Extract the argument source text
+        const argStart = (args[0] as PositionedNode).start;
+        const argEnd = (args[0] as PositionedNode).end;
+        const argText = source.slice(argStart, argEnd);
+        const calleeName = (callee as IdentifierNode).name;
+        return `${calleeName}(${argText})`;
+      }
+    }
+  }
+
+  let result: string | null = null;
+  walkChildNodes(node, (child) => {
+    if (!result) result = walkForDynamicCalls(child, names, source);
+  });
+  return result;
+}
+
+/**
+ * Node types that introduce a nested scope — any font call inside is an
+ * error (font calls must be module-level, same constraint as Next.js).
+ * Module scope so it isn't rebuilt on every recursive walk call.
+ */
+const NESTED_SCOPE_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'IfStatement',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+  'WhileStatement',
+  'DoWhileStatement',
+  'SwitchStatement',
+  'TryStatement',
+  'BlockStatement',
+  'ClassDeclaration',
+  'ClassExpression',
+]);
+
+/**
+ * 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.
+ */
+export function walkForNestedFontCalls(
+  node: AstNode,
+  bindingNames: ReadonlyMap<string, unknown>,
+  source: string,
+  out: FlaggedUsage[],
+  isNested: boolean
+): void {
+  if (!node || typeof node !== 'object') return;
+
+  if (node.type === 'CallExpression') {
+    const callee = node.callee as AstNode;
+    if (
+      isNested &&
+      callee.type === 'Identifier' &&
+      bindingNames.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
+    }
+  }
+
+  const enterNested = isNested || NESTED_SCOPE_TYPES.has(node.type);
+  walkChildNodes(node, (child) =>
+    walkForNestedFontCalls(child, bindingNames, source, out, enterNested)
+  );
+}
+
+/**
+ * Recursively walk an AST node looking for references to font bindings
+ * that were not consumed by a recognized call site.
+ *
+ * Skips:
+ * - recognized CallExpressions (the transform rewrites them wholesale)
+ * - TS type-position nodes (erased at runtime)
+ * - non-computed member properties (`obj.Inter` doesn't reference the binding)
+ * - non-computed object keys (`{ Inter: 1 }` doesn't reference the binding)
+ * - export aliases (`export { inter as Inter }` — only `local` is a reference)
+ */
+export function walkForUnconsumedReferences(
+  node: AstNode,
+  bindingNames: ReadonlyMap<string, unknown>,
+  consumedCallStarts: ReadonlySet<number>,
+  source: string,
+  out: FlaggedUsage[]
+): void {
+  if (!node || typeof node !== 'object') return;
+  if (node.type === 'ImportDeclaration' || node.type.startsWith('TS')) return;
+
+  if (node.type === 'Identifier') {
+    const name = (node as IdentifierNode).name;
+    if (bindingNames.has(name)) {
+      const pos = offsetToLineColumn(source, (node as PositionedNode).start);
+      out.push({ name, line: pos.line, column: pos.column });
+    }
+    return;
+  }
+
+  if (node.type === 'CallExpression' && consumedCallStarts.has((node as PositionedNode).start)) {
+    return; // The whole call (callee + config object) is rewritten.
+  }
+
+  if (node.type === 'MemberExpression' && !(node as { computed?: boolean }).computed) {
+    const object = (node as { object?: AstNode }).object;
+    if (object) {
+      walkForUnconsumedReferences(object, bindingNames, consumedCallStarts, source, out);
+    }
+    return;
+  }
+
+  if (node.type === 'Property' && !(node as { computed?: boolean }).computed) {
+    const value = (node as { value?: AstNode }).value;
+    if (value) {
+      walkForUnconsumedReferences(value, bindingNames, consumedCallStarts, source, out);
+    }
+    return;
+  }
+
+  if (node.type === 'ExportSpecifier') {
+    // Only `local` references a module binding. `exported` is just the
+    // public name — `export { inter as Inter }` must not flag `Inter`.
+    const local = (node as { local?: AstNode }).local;
+    if (local) {
+      walkForUnconsumedReferences(local, bindingNames, consumedCallStarts, source, out);
+    }
+    return;
+  }
+
+  walkChildNodes(node, (child) =>
+    walkForUnconsumedReferences(child, bindingNames, consumedCallStarts, source, out)
+  );
+}