toiljs 0.0.115 → 0.0.117

package/src/compiler/prerender.ts

@@ -1,263 +0,0 @@
-import { createRequire } from 'node:module';
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-import type * as TS from 'typescript';
-import type { Plugin } from 'vite';
-
-import { type ResolvedToilConfig } from './config.js';
-import { patternToBracketFile, scanRoutes, staticSectionPattern } from './routes.js';
-import { injectSeoHtml, routeSeo } from './seo.js';
-
-type Ts = typeof TS;
-
-/**
- * True when `mod` exposes the classic TypeScript compiler API the static extractor drives.
- *
- * Resolving `typescript` is not enough to know it can parse: TypeScript 7 (the native port) moved
- * the compiler API off the package's main entry, which now exports only `version`. That module is a
- * perfectly good object, so a truthy check passes and the first `ts.ScriptTarget.Latest` then dies
- * with `Cannot read properties of undefined (reading 'Latest')`. Probe the members we actually use.
- */
-function isCompilerApi(mod: unknown): mod is Ts {
-    const ts = mod as Partial<Ts> | null | undefined;
-    return (
-        typeof ts?.createSourceFile === 'function' &&
-        typeof ts.isVariableStatement === 'function' &&
-        typeof ts.ScriptTarget === 'object' &&
-        typeof ts.ScriptKind === 'object' &&
-        typeof ts.SyntaxKind === 'object'
-    );
-}
-
-/** Warn once per process: an unusable TypeScript silently costs baked metadata, so say so. */
-let warnedUnusable = false;
-function warnUnusableTypeScript(mod: unknown): void {
-    if (warnedUnusable) return;
-    warnedUnusable = true;
-    const version = (mod as { version?: string } | null)?.version;
-    process.stderr.write(
-        `  toil: typescript${version ? `@${version}` : ''} does not expose the compiler API ` +
-            `(TypeScript 7 moved it to 'typescript/unstable/*').\n` +
-            `  toil: route metadata will NOT be baked into the built HTML. Install typescript ^6 to restore it.\n`,
-    );
-}
-
-/**
- * Resolves the project's TypeScript, used to read each route's static `metadata`. Returns `null`
- * when it isn't installed (callers then index pages by path only) *or* when the resolved version
- * doesn't expose the compiler API, which is warned about rather than crashing the build.
- */
-export async function loadTypeScript(root: string): Promise<Ts | null> {
-    let mod: unknown;
-    try {
-        const resolved = createRequire(path.join(root, 'package.json')).resolve('typescript');
-        const ns = (await import(pathToFileURL(resolved).href)) as { default?: Ts } & Ts;
-        mod = ns.default ?? ns;
-    } catch {
-        return null;
-    }
-    if (isCompilerApi(mod)) return mod;
-    warnUnusableTypeScript(mod);
-    return null;
-}
-
-/** The sync twin of {@link loadTypeScript}, for callers that can't await (e.g. `buildPageIndex`). */
-export function loadTypeScriptSync(root: string): Ts | null {
-    let mod: unknown;
-    try {
-        mod = createRequire(path.join(root, 'package.json'))('typescript');
-    } catch {
-        return null;
-    }
-    const ts = (mod as { default?: Ts })?.default ?? mod;
-    if (isCompilerApi(ts)) return ts;
-    warnUnusableTypeScript(ts);
-    return null;
-}
-
-/** Marks an AST node that isn't a static literal (so its value can't be baked at build). */
-const UNRESOLVED = Symbol('unresolved');
-
-/** Statically evaluates a literal expression node to a JS value, or `UNRESOLVED` if it isn't one. */
-function evalNode(ts: Ts, node: TS.Expression): unknown {
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
-    if (ts.isNumericLiteral(node)) return Number(node.text);
-    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
-    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
-    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
-    if (ts.isArrayLiteralExpression(node)) {
-        const out: unknown[] = [];
-        for (const el of node.elements) {
-            const value = evalNode(ts, el);
-            if (value === UNRESOLVED) return UNRESOLVED;
-            out.push(value);
-        }
-        return out;
-    }
-    if (ts.isObjectLiteralExpression(node)) return evalObject(ts, node);
-    return UNRESOLVED;
-}
-
-/** Evaluates an object literal to a plain object, skipping any property that isn't a static literal. */
-function evalObject(ts: Ts, node: TS.ObjectLiteralExpression): Record<string, unknown> {
-    const obj: Record<string, unknown> = {};
-    for (const prop of node.properties) {
-        if (!ts.isPropertyAssignment(prop)) continue;
-        const key = ts.isIdentifier(prop.name)
-            ? prop.name.text
-            : ts.isStringLiteral(prop.name)
-              ? prop.name.text
-              : null;
-        if (key === null) continue;
-        const value = evalNode(ts, prop.initializer);
-        if (value !== UNRESOLVED) obj[key] = value;
-    }
-    return obj;
-}
-
-/**
- * Extracts the named `export const <name> = { … }` object-literal exports from a route file in a
- * single parse, returning the statically-evaluable subset of each (dynamic and computed values are
- * skipped). Names that are absent or not object literals are omitted from the result.
- */
-export function extractStaticExports(
-    ts: Ts,
-    filePath: string,
-    names: readonly string[],
-): Record<string, Record<string, unknown>> {
-    let source: string;
-    try {
-        source = fs.readFileSync(filePath, 'utf8');
-    } catch {
-        return {};
-    }
-    const wanted = new Set(names);
-    const out: Record<string, Record<string, unknown>> = {};
-    const sf = ts.createSourceFile(
-        filePath,
-        source,
-        ts.ScriptTarget.Latest,
-        true,
-        ts.ScriptKind.TSX,
-    );
-    for (const stmt of sf.statements) {
-        if (!ts.isVariableStatement(stmt)) continue;
-        if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
-        for (const decl of stmt.declarationList.declarations) {
-            if (
-                ts.isIdentifier(decl.name) &&
-                wanted.has(decl.name.text) &&
-                !(decl.name.text in out) &&
-                decl.initializer &&
-                ts.isObjectLiteralExpression(decl.initializer)
-            ) {
-                out[decl.name.text] = evalObject(ts, decl.initializer);
-            }
-        }
-    }
-    return out;
-}
-
-/**
- * Extracts a route's `export const metadata = { … }` if it's a static object literal, returning the
- * statically-evaluable subset (dynamic `generateMetadata` and computed values are skipped). `null`
- * when the file has no static metadata.
- */
-export function extractStaticMetadata(ts: Ts, filePath: string): Record<string, unknown> | null {
-    return extractStaticExports(ts, filePath, ['metadata']).metadata ?? null;
-}
-
-/**
- * True when the route file has a literal `export const <name> = true`. Used to detect the edge-SSR
- * opt-in (`export const ssr = true`) without spinning up a Vite SSR server, so the static prerender
- * can leave SSR routes to the SSR path.
- */
-export function exportsTrue(ts: Ts, filePath: string, name: string): boolean {
-    let source: string;
-    try {
-        source = fs.readFileSync(filePath, 'utf8');
-    } catch {
-        return false;
-    }
-    const sf = ts.createSourceFile(
-        filePath,
-        source,
-        ts.ScriptTarget.Latest,
-        true,
-        ts.ScriptKind.TSX,
-    );
-    for (const stmt of sf.statements) {
-        if (!ts.isVariableStatement(stmt)) continue;
-        if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
-        for (const decl of stmt.declarationList.declarations) {
-            if (
-                ts.isIdentifier(decl.name) &&
-                decl.name.text === name &&
-                decl.initializer?.kind === ts.SyntaxKind.TrueKeyword
-            ) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-
-/**
- * Build-only plugin that statically pre-renders per-route HTML for SEO. After the bundle is written,
- * it takes the built shell (`index.html`), and for each route bakes that route's `metadata` (merged
- * over the site-wide `seo` defaults) into a browsable HTML file so a JS-less crawler gets correct
- * per-page tags:
- *   - a STATIC route (`/about`) -> `<route>/index.html`;
- *   - a DYNAMIC route (`/blog/:id`) -> a literal bracket template `blog/[id].html` that the static
- *     server serves for any concrete `/blog/<x>` and the client router hydrates. Its canonical points
- *     at the route's static section (`/blog`); the client sets the exact per-value URL on hydration.
- * A dynamic template is a file, never a `<seg>/index.html` folder, so it never shadows a sibling.
- */
-export function prerenderPlugin(cfg: ResolvedToilConfig): Plugin {
-    return {
-        name: 'toil:prerender-seo',
-        apply: 'build',
-        async closeBundle() {
-            if (!cfg.seo) return;
-            const outDir = path.resolve(cfg.root, cfg.outDir);
-            const shellPath = path.join(outDir, 'index.html');
-            if (!fs.existsSync(shellPath)) return;
-            const shell = fs.readFileSync(shellPath, 'utf8');
-            // Stash the clean built shell (asset tags, no per-route SEO yet) so the post-build SSG
-            // pass bakes dynamic routes from it rather than from this file once it's been overwritten
-            // with the `/` route's head (which would duplicate canonical/og tags).
-            fs.writeFileSync(path.join(cfg.toilDir, 'shell.html'), shell);
-            const ts = await loadTypeScript(cfg.root);
-
-            const routes = scanRoutes(cfg.routesAbsDir).filter(
-                (r) => r.slot === undefined && !r.intercept,
-            );
-            for (const route of routes) {
-                const isDynamic = /[:*]/.test(route.pattern);
-                // A dynamic route that opts into edge SSR (`export const ssr = true`) is rendered by
-                // the SSR template path. Baking a static bracket template would let the edge's
-                // static-first serving shadow it, so leave SSR routes to SSR. (When `ts` is null the
-                // check is skipped and we bake anyway: fail-OPEN deliberately favors the common
-                // non-SSR dynamic route, which would 404 without a template; typescript is always
-                // present in a real toiljs project, so this branch is effectively unreachable.)
-                if (isDynamic && ts && exportsTrue(ts, route.file, 'ssr')) continue;
-                const metadata = ts ? extractStaticMetadata(ts, route.file) : null;
-                // A dynamic route's concrete URL is unknown at build, so its canonical/OG URL points
-                // at the static section (`/blog/:id` -> `/blog`); the client refines it on hydration.
-                const seoPattern = isDynamic ? staticSectionPattern(route.pattern) : route.pattern;
-                const html = injectSeoHtml(shell, routeSeo(cfg.seo, metadata, seoPattern));
-                // Dynamic -> a literal bracket template (`blog/[id].html`); static -> `<route>/index.html`
-                // (the `/` route is the shell itself). The bracket file is never a folder+index.html.
-                const target = isDynamic
-                    ? path.join(outDir, patternToBracketFile(route.pattern))
-                    : route.pattern === '/'
-                      ? shellPath
-                      : path.join(outDir, route.pattern.replace(/^\//, ''), 'index.html');
-                fs.mkdirSync(path.dirname(target), { recursive: true });
-                fs.writeFileSync(target, html);
-            }
-        },
-    };
-}

package/src/compiler/routes.ts

@@ -1,170 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** A discovered route: the source file and the URL pattern it serves. */
-export interface ScannedRoute {
-    readonly file: string;
-    readonly pattern: string;
-    /** Named parallel slot this route belongs to (from an `@slot` dir), or `undefined` for the main tree. */
-    readonly slot?: string;
-    /** True for an intercepting route (`(.)`/`(..)`/`(...)`), matched only on soft navigation. */
-    readonly intercept?: boolean;
-}
-
-const ROUTE_EXT = /\.(tsx|jsx)$/;
-/** Special files that live alongside routes but are not themselves pages. */
-const SPECIAL_FILE = /^(layout|template|loading|error|global-error|404|not-found)\.(tsx|jsx)$/;
-
-/**
- * Derives a route pattern from a route file path (relative to the routes dir).
- *   index.tsx          -> /
- *   about.tsx          -> /about
- *   blog/index.tsx     -> /blog
- *   blog/[id].tsx        -> /blog/:id
- *   docs/[...slug].tsx   -> /docs/*slug    (catch-all)
- *   docs/[[...slug]].tsx -> /docs/**slug   (optional catch-all)
- *   (marketing)/about.tsx -> /about        (route group: parens add no URL segment)
- *   @modal/photo/[id].tsx -> /photo/:id     (parallel slot: `@slot` adds no URL segment)
- */
-/** Converts a path segment's dynamic brackets to URL params (`[id]`→`:id`, `[...x]`→`*x`, `[[...x]]`→`**x`). */
-function toUrlSegment(segment: string): string {
-    return segment
-        .replace(/^\[\[\.\.\.(.+)\]\]$/, '**$1')
-        .replace(/^\[\.\.\.(.+)\]$/, '*$1')
-        .replace(/^\[(.+)\]$/, ':$1');
-}
-
-/** Inverse of {@link toUrlSegment}: turns a URL pattern segment back into its on-disk bracket
- *  form (`:id`→`[id]`, `*x`→`[...x]`, `**x`→`[[...x]]`). Static segments pass through unchanged. */
-function bracketSegment(segment: string): string {
-    if (segment.startsWith('**')) return `[[...${segment.slice(2)}]]`;
-    if (segment.startsWith('*')) return `[...${segment.slice(1)}]`;
-    if (segment.startsWith(':')) return `[${segment.slice(1)}]`;
-    return segment;
-}
-
-/**
- * The on-disk HTML filename (relative to the build output dir) a DYNAMIC route pattern bakes to:
- * the inverse of the scan mapping, with the last segment as the file and the rest as directories.
- * This is the literal bracket template the static server serves for any matching URL and the client
- * router hydrates, so it must not become a `<seg>/index.html` folder (which would shadow siblings).
- *   /blog/:id      -> blog/[id].html
- *   /docs/*slug    -> docs/[...slug].html
- *   /docs/**slug   -> docs/[[...slug]].html
- *   /:category/:id -> [category]/[id].html
- */
-export function patternToBracketFile(pattern: string): string {
-    return pattern.split('/').filter(Boolean).map(bracketSegment).join('/') + '.html';
-}
-
-/**
- * The static "section" of a pattern: the same pattern with every dynamic (`:`/`*`) segment dropped.
- * Used as the canonical/OG base URL when baking a dynamic route's build-time SEO (the concrete
- * per-value URL is unknown at build; the client sets it on hydration).
- *   /blog/:id      -> /blog
- *   /:category/:id -> /
- */
-export function staticSectionPattern(pattern: string): string {
-    const kept = pattern
-        .split('/')
-        .filter(Boolean)
-        .filter((s) => !s.startsWith(':') && !s.startsWith('*'));
-    return '/' + kept.join('/');
-}
-
-/** Interception markers: `(.)` same level, `(..)` up one, `(...)` from the routes root. */
-const INTERCEPT_RE = /^\((\.{1,3})\)(.+)$/;
-
-export function filePathToRoute(relPath: string): string {
-    const withoutExt = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '');
-    const segments = withoutExt.split('/').filter(Boolean);
-    const out: string[] = [];
-    for (let i = 0; i < segments.length; i++) {
-        const segment = segments[i];
-        if (/^\(.+\)$/.test(segment)) continue;
-        if (/^@/.test(segment)) continue; // parallel-slot marker, contributes no URL segment
-        if (segment === 'index' && i === segments.length - 1) continue;
-        out.push(toUrlSegment(segment));
-    }
-    return '/' + out.join('/');
-}
-
-/**
- * The URL an intercepting route targets, or `null` if the path has no `(.)`/`(..)`/`(...)` marker.
- * The marker resolves the target relative to the route's position (ignoring `@slot`/`(group)`
- * segments): `(.)` keeps the current level, `(..)` drops one, `(...)` resets to the root.
- *   @modal/(.)photo/[id].tsx     -> /photo/:id
- *   feed/@modal/(..)photo/[id].tsx -> /photo/:id
- */
-export function interceptTarget(relPath: string): string | null {
-    const segments = relPath.replace(/\\/g, '/').replace(ROUTE_EXT, '').split('/').filter(Boolean);
-    const out: string[] = [];
-    let marked = false;
-    for (let i = 0; i < segments.length; i++) {
-        const segment = segments[i];
-        if (/^@/.test(segment)) continue;
-        const marker = INTERCEPT_RE.exec(segment);
-        if (marker) {
-            marked = true;
-            const dots = marker[1].length;
-            if (dots === 2)
-                out.pop(); // (..) up one level
-            else if (dots === 3) out.length = 0; // (...) from the routes root
-            out.push(toUrlSegment(marker[2]));
-            continue;
-        }
-        if (/^\(.+\)$/.test(segment)) continue;
-        if (segment === 'index' && i === segments.length - 1) continue;
-        out.push(toUrlSegment(segment));
-    }
-    return marked ? '/' + out.join('/') : null;
-}
-
-/**
- * Ranks a pattern so more specific routes match first: static segments beat dynamic (`:x`),
- * which beat catch-all (`*x`); deeper routes beat shallower ones.
- */
-function specificity(pattern: string): number {
-    const segments = pattern.split('/').filter(Boolean);
-    let score = segments.length * 10;
-    for (const segment of segments) {
-        if (segment.startsWith('*')) score -= 5;
-        else if (!segment.startsWith(':')) score += 5;
-    }
-    return score;
-}
-
-/** The parallel-slot name for a route path (the first `@slot` segment), or `undefined`. */
-function slotOf(relPath: string): string | undefined {
-    for (const segment of relPath.replace(/\\/g, '/').split('/')) {
-        const match = /^@(.+)$/.exec(segment);
-        if (match) return match[1];
-    }
-    return undefined;
-}
-
-/** Recursively scans `routesDir` for `.tsx`/`.jsx` files, returning routes sorted by specificity. */
-export function scanRoutes(routesDir: string): ScannedRoute[] {
-    if (!fs.existsSync(routesDir)) return [];
-    const found: ScannedRoute[] = [];
-    const walk = (dir: string): void => {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(full);
-            } else if (ROUTE_EXT.test(entry.name) && !SPECIAL_FILE.test(entry.name)) {
-                const rel = path.relative(routesDir, full);
-                const target = interceptTarget(rel);
-                found.push({
-                    file: full,
-                    pattern: target ?? filePathToRoute(rel),
-                    slot: slotOf(rel),
-                    intercept: target !== null,
-                });
-            }
-        }
-    };
-    walk(routesDir);
-    found.sort((a, b) => specificity(b.pattern) - specificity(a.pattern));
-    return found;
-}