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

package/src/plugins/prerender-sugar.ts

@@ -0,0 +1,320 @@
+/**
+ * timber-prerender-sugar — Vite plugin that desugars `export const prerender`
+ * on page and layout files into `cache.component(...)` wrappers.
+ *
+ * Design doc: design/45-cache-lifetimes.md §"Route-Level Static" and
+ * §"Layout Propagation".
+ *
+ * `export const prerender = true` on a page is pure sugar: it desugars to
+ * wrapping the page's default export in `timber.cache.component(Component,
+ * { prerender: true })`. Layout propagation cascades a layout's
+ * `export const prerender` to descendant pages via most-specific-wins:
+ * walk the segment tree from leaf to root, first explicit value wins.
+ *
+ * Layout declarations are propagation policy only. Layouts receive the real
+ * descendant React element as `children` to preserve the server-layout
+ * containment boundary, so their props are not cache-keyable and the layout
+ * itself must not be registered for capture.
+ *
+ * This transform runs BEFORE timber-prebuilt so the generated
+ * `cache.component(...)` call is picked up by the callsite rewrite.
+ */
+
+import MagicString from 'magic-string';
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode, RouteFile } from '../routing/types.ts';
+import { getPrerenderExport, type PrerenderExportValue } from '../routing/export-detect.ts';
+
+interface AstNode {
+  type: string;
+  start: number;
+  end: number;
+  name?: string;
+  declaration?: AstNode;
+  id?: AstNode & { name?: string };
+  expression?: AstNode;
+}
+
+/**
+ * Walk the segment tree and resolve the effective prerender value for
+ * every page. Returns a map from page file path to resolved value.
+ *
+ * **Pages:** walk from leaf toward root; first explicit `export const prerender`
+ * wins (page > nearest layout > ... > root layout). If none, dynamic.
+ *
+ * **Layouts:** declarations propagate to descendant pages but layouts are not
+ * included in the result. Their real React-element `children` preserve secure
+ * containment and deliberately make child-independent layout caching invalid.
+ */
+export function resolvePagePrerender(root: SegmentNode): Map<string, PrerenderExportValue> {
+  const result = new Map<string, PrerenderExportValue>();
+
+  function walk(node: SegmentNode, ancestorStack: PrerenderExportValue[]) {
+    if (node.segmentType === 'intercepting' || node.segmentType === 'private') return;
+
+    // Check this segment's layout for a prerender export
+    const layoutValue = node.layout ? getPrerenderExport(node.layout.filePath) : undefined;
+    const stack = layoutValue !== undefined ? [layoutValue, ...ancestorStack] : ancestorStack;
+
+    if (node.page) {
+      const pageValue = getPrerenderExport(node.page.filePath);
+      // Page's own value takes priority; otherwise use nearest ancestor
+      const resolved = pageValue !== undefined ? pageValue : stack[0];
+      // Only record if the resolved value is truthy (prerender: true or options object)
+      // prerender: false explicitly opts out
+      if (resolved !== undefined && resolved !== false) {
+        result.set(node.page.filePath, resolved);
+      }
+    }
+
+    for (const child of node.children) walk(child, stack);
+    for (const slot of Object.values(node.slots)) walk(slot, stack);
+  }
+
+  walk(root, []);
+  return result;
+}
+
+/**
+ * Build the `cache.component` options source text from a resolved value.
+ */
+function buildOptionsSource(value: PrerenderExportValue): string {
+  if (value === true) return '{ prerender: true }';
+  if (typeof value === 'object') {
+    const parts = ['prerender: true'];
+    if (value.ttl !== undefined) parts.push(`ttl: ${value.ttl}`);
+    if (value.tags !== undefined) parts.push(`tags: ${JSON.stringify(value.tags)}`);
+    return `{ ${parts.join(', ')} }`;
+  }
+  return '{ prerender: true }';
+}
+
+/**
+ * Find the default export in the AST and return info needed for the rewrite.
+ */
+interface DefaultExportInfo {
+  kind: 'declaration' | 'expression' | 'identifier';
+  node: AstNode;
+  name?: string;
+  /** For `export { X as default, Y }` — position of the default specifier. */
+  specifierIndex?: number;
+  specifierCount?: number;
+  specifierStart?: number;
+  specifierEnd?: number;
+}
+
+function findDefaultExport(program: { body: AstNode[] }, source: string): DefaultExportInfo | null {
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ExportDefaultDeclaration' || !stmt.declaration) continue;
+    const decl = stmt.declaration;
+
+    // export default function Name(...) { ... }
+    // export default class Name { ... }
+    if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+      const name = decl.id?.name;
+      if (name) return { kind: 'declaration', node: stmt, name };
+      // Anonymous function/class — treat as expression
+      return { kind: 'expression', node: stmt };
+    }
+
+    // export default SomeIdentifier
+    if (decl.type === 'Identifier') {
+      return { kind: 'identifier', node: stmt, name: decl.name };
+    }
+
+    // export default <expression>
+    return { kind: 'expression', node: stmt };
+  }
+
+  // Check for `export { X as default }` (not re-exports from other modules)
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ExportNamedDeclaration') continue;
+    // Skip re-exports: `export { X as default } from './other'`
+    if ((stmt as any).source) continue;
+    const specifiers = (stmt as any).specifiers as
+      | Array<{
+          type: string;
+          start: number;
+          end: number;
+          local?: { name: string };
+          exported?: { name: string };
+        }>
+      | undefined;
+    if (!specifiers) continue;
+    for (let i = 0; i < specifiers.length; i++) {
+      const spec = specifiers[i];
+      if (spec.exported?.name === 'default' && spec.local?.name && spec.local.name !== 'default') {
+        return {
+          kind: 'identifier' as const,
+          node: stmt,
+          name: spec.local.name,
+          specifierIndex: i,
+          specifierCount: specifiers.length,
+          specifierStart: spec.start,
+          specifierEnd: spec.end,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function timberPrerenderSugar(ctx: PluginContext): Plugin {
+  let resolvedPages: Map<string, PrerenderExportValue> | null = null;
+
+  function ensureResolved() {
+    if (resolvedPages) return;
+    if (!ctx.routeTree) {
+      resolvedPages = new Map();
+      return;
+    }
+    resolvedPages = resolvePagePrerender(ctx.routeTree.root);
+  }
+
+  return {
+    name: 'timber-prerender-sugar',
+
+    buildStart() {
+      // Reset on each build (watch mode rebuilds)
+      resolvedPages = null;
+    },
+
+    transform(code, id) {
+      // Only process in RSC environment (same gate as prebuilt.ts)
+      if (this?.environment?.name === 'client') return;
+      // Skip node_modules
+      if (id.includes('node_modules')) return;
+
+      ensureResolved();
+      if (!resolvedPages || resolvedPages.size === 0) return;
+
+      const value = resolvedPages.get(id);
+      if (!value) return;
+
+      // This page has a resolved prerender value — wrap its default export
+      let program: { body: AstNode[] };
+      try {
+        program = ctx.parseCached!.parse(code) as unknown as { body: AstNode[] };
+      } catch {
+        return;
+      }
+
+      const defaultExport = findDefaultExport(program, code);
+      if (!defaultExport) {
+        // Warn if the file has a prerender export but no wrappable default export
+        // (e.g. `export { default } from './impl'` — a re-export we can't rewrite).
+        if (value) {
+          const relPath = id.replace(ctx.root + '/', '');
+          console.warn(
+            `[timber] ${relPath}: export const prerender is declared but the default ` +
+              `export cannot be wrapped (re-export or missing). The prerender declaration ` +
+              `will be ignored for this file.`
+          );
+        }
+        return;
+      }
+
+      // Skip if the default export is already a cache.component(...) call —
+      // avoid double-wrapping. Only check the default export itself, not the
+      // whole file (a page may use cache.component for child components).
+      if (defaultExport.kind === 'expression' && defaultExport.node.declaration) {
+        const declText = code.slice(
+          defaultExport.node.declaration.start,
+          defaultExport.node.declaration.end
+        );
+        if (declText.includes('.component(')) return;
+      }
+
+      // Record this page as desugared for downstream attribution
+      ctx.prerenderSugarPages ??= new Set();
+      ctx.prerenderSugarPages.add(id);
+
+      const s = new MagicString(code);
+      const optionsSource = buildOptionsSource(value);
+
+      // Add the cache import at the top (after directives)
+      const importAlias = '__timber_prerender_cache__';
+      let insertOffset = 0;
+      for (const stmt of program.body) {
+        const isDirective =
+          stmt.type === 'ExpressionStatement' && typeof (stmt as any).directive === 'string';
+        if (!isDirective) {
+          insertOffset = stmt.start;
+          break;
+        }
+      }
+      s.appendLeft(
+        insertOffset,
+        `import { cache as ${importAlias} } from '@timber-js/app/cache';\n`
+      );
+
+      switch (defaultExport.kind) {
+        case 'declaration': {
+          // `export default function Name() { ... }`
+          // → `function Name() { ... }` + `export default cache.component(Name, opts)`
+          const declStart = defaultExport.node.declaration!.start;
+          // Remove `export default ` prefix
+          s.overwrite(defaultExport.node.start, declStart, '');
+          // Append the wrapped export at the end
+          s.append(
+            `\nexport default ${importAlias}.component(${defaultExport.name}, ${optionsSource});\n`
+          );
+          break;
+        }
+        case 'identifier': {
+          if (defaultExport.specifierCount !== undefined && defaultExport.specifierCount > 1) {
+            // Multi-specifier: `export { Page as default, generateStaticSegmentParams }`
+            // Remove only the default specifier + surrounding comma, keep others.
+            const specStart = defaultExport.specifierStart!;
+            const specEnd = defaultExport.specifierEnd!;
+            const idx = defaultExport.specifierIndex!;
+            // Remove the specifier and a comma (trailing if first, leading otherwise)
+            if (idx === 0) {
+              // First specifier: remove text up to (but not including) the next specifier start
+              const nextSpec = (defaultExport.node as any).specifiers?.[1];
+              if (nextSpec) s.remove(specStart, nextSpec.start);
+            } else {
+              // Not first: remove from end of previous specifier to this specifier's end
+              const prevSpec = (defaultExport.node as any).specifiers?.[idx - 1];
+              if (prevSpec) s.remove(prevSpec.end, specEnd);
+            }
+            // Append the wrapped default export separately
+            s.appendLeft(
+              defaultExport.node.end,
+              `\nexport default ${importAlias}.component(${defaultExport.name}, ${optionsSource});`
+            );
+          } else {
+            // `export default MyPage` or `export { MyPage as default }` (sole specifier)
+            // → `export default cache.component(MyPage, opts)`
+            s.overwrite(
+              defaultExport.node.start,
+              defaultExport.node.end,
+              `export default ${importAlias}.component(${defaultExport.name}, ${optionsSource});`
+            );
+          }
+          break;
+        }
+        case 'expression': {
+          // `export default () => <div/>` or `export default async function() { ... }`
+          // → `const __default = ...; export default cache.component(__default, opts)`
+          const decl = defaultExport.node.declaration!;
+          s.overwrite(defaultExport.node.start, decl.start, 'const __timber_default_page__ = ');
+          // Ensure trailing semicolon
+          const afterExpr = code.charAt(defaultExport.node.end - 1) === ';' ? '' : ';';
+          s.appendLeft(
+            defaultExport.node.end,
+            `${afterExpr}\nexport default ${importAlias}.component(__timber_default_page__, ${optionsSource});`
+          );
+          break;
+        }
+      }
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: 'boundary' }),
+      };
+    },
+  };
+}