fimo 0.7.0-experimental.2 → 0.7.0-experimental.4

package/dist/scripts/render-parity/capture.d.ts

@@ -0,0 +1,56 @@
+import { type ParityBaseline } from './types.js';
+export interface CaptureOptions {
+    cwd: string;
+    packageManager: string;
+    routes: Array<{
+        path: string;
+    }>;
+    framework: string | null;
+    bootTimeoutMs?: number;
+    routeTimeoutMs?: number;
+    /** Reuse an already-running dev server instead of booting one: the warm
+     *  server recompiles incrementally, so repeated checks cost seconds. The
+     *  server is probed once and never stopped. */
+    serverOrigin?: string;
+    /** Concrete values for dynamic route params so `[locale]`-style routes are
+     *  actually captured instead of skipped. A route resolves (and is captured)
+     *  only when EVERY `:param` in it has a value here; both baseline and check
+     *  read the same values, so the comparison stays symmetric. */
+    paramValues?: Record<string, string>;
+    onProgress?: (message: string) => void;
+}
+/** Substitute known params into a `:param` route path; returns the concrete
+ *  path, or null when a param has no value (still unresolvable → skip). */
+export declare function resolveRoutePath(routePath: string, paramValues: Record<string, string>): string | null;
+export declare class CaptureError extends Error {
+    readonly stderrTail: string;
+    constructor(message: string, stderrTail?: string);
+}
+export declare function findFreePort(): Promise<number>;
+/**
+ * Build workspace packages the app needs BEFORE booting its dev server. Fimo
+ * runs the app's bare `next dev`, but in a Turborepo/pnpm monorepo the
+ * internal deps (`@repo/*`) aren't built by that — `turbo dev` would build
+ * them first. This detects unbuilt internal deps and runs the monorepo's
+ * build once (the root `build` script, else `turbo run build`); turbo's cache
+ * makes an already-built repo near-instant. A build failure is surfaced with
+ * an actionable message instead of a cryptic `Cannot find module` at boot.
+ */
+export declare function ensureWorkspaceDepsBuilt(cwd: string, packageManager: string, onProgress?: (message: string) => void): void;
+interface DevServer {
+    origin: string;
+    stderrTail: () => string;
+    stop: () => Promise<void>;
+}
+export declare function startDevServer(opts: {
+    cwd: string;
+    packageManager: string;
+    bootTimeoutMs: number;
+}): Promise<DevServer>;
+/**
+ * Boot the project's own dev server, capture every static route's normalized
+ * signature, and tear the server down. Baseline and check both run through
+ * this identical pipeline — that symmetry is the gate's correctness property.
+ */
+export declare function captureParityBaseline(opts: CaptureOptions): Promise<ParityBaseline>;
+export {};

package/dist/scripts/render-parity/capture.js

@@ -0,0 +1,366 @@
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { extractRouteSignature } from './normalize-html.js';
+import { PARITY_BASELINE_VERSION } from './types.js';
+/** Substitute known params into a `:param` route path; returns the concrete
+ *  path, or null when a param has no value (still unresolvable → skip). */
+export function resolveRoutePath(routePath, paramValues) {
+    const resolved = routePath.replace(/:([A-Za-z0-9_]+)/g, (_, name) => paramValues[name] ? encodeURIComponent(paramValues[name]) : `:${name}`);
+    return resolved.includes(':') ? null : resolved;
+}
+const DEFAULT_BOOT_TIMEOUT_MS = 90_000;
+const DEFAULT_ROUTE_TIMEOUT_MS = 60_000;
+const READINESS_POLL_MS = 500;
+const KILL_GRACE_MS = 5_000;
+export class CaptureError extends Error {
+    stderrTail;
+    constructor(message, stderrTail = '') {
+        super(message);
+        this.name = 'CaptureError';
+        this.stderrTail = stderrTail;
+    }
+}
+export function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+function preflight(cwd) {
+    if (!fs.existsSync(path.join(cwd, 'node_modules'))) {
+        throw new CaptureError('node_modules is missing — run your package manager install first.');
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        if (!pkg.scripts?.dev) {
+            throw new CaptureError('No `dev` script in package.json — the parity capture boots your dev server.');
+        }
+    }
+    catch (error) {
+        if (error instanceof CaptureError) {
+            throw error;
+        }
+        throw new CaptureError('Could not read package.json.');
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The monorepo root above `cwd` (pnpm-workspace / turbo / npm workspaces),
+ *  or null when `cwd` is standalone. */
+function workspaceRoot(cwd) {
+    let dir = cwd;
+    for (let depth = 0; depth < 6; depth += 1) {
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) || fs.existsSync(path.join(dir, 'turbo.json'))) {
+            return dir;
+        }
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+            if (pkg.workspaces) {
+                return dir;
+            }
+        }
+        catch {
+            // keep walking up
+        }
+    }
+    return null;
+}
+/** Internal workspace packages this app depends on (`workspace:` / `catalog:`
+ *  protocol) whose build output is missing — a bare `next dev` fails on
+ *  `Cannot find module '@repo/…/dist/…'` until they are built. */
+function unbuiltWorkspaceDeps(cwd) {
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const deps = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })
+        .filter(([, version]) => typeof version === 'string' && (version.startsWith('workspace:') || version.startsWith('catalog:')))
+        .map(([name]) => name);
+    return deps.filter((name) => {
+        const depDir = path.join(cwd, 'node_modules', name);
+        try {
+            const depPkg = JSON.parse(fs.readFileSync(path.join(depDir, 'package.json'), 'utf8'));
+            const entry = depPkg.module ?? depPkg.main;
+            if (typeof entry === 'string') {
+                return !fs.existsSync(path.join(depDir, entry));
+            }
+            // exports-only package: treat a missing dist/ as unbuilt.
+            return Boolean(depPkg.exports) && !fs.existsSync(path.join(depDir, 'dist'));
+        }
+        catch {
+            return false; // can't resolve the link → don't force a build
+        }
+    });
+}
+/**
+ * Build workspace packages the app needs BEFORE booting its dev server. Fimo
+ * runs the app's bare `next dev`, but in a Turborepo/pnpm monorepo the
+ * internal deps (`@repo/*`) aren't built by that — `turbo dev` would build
+ * them first. This detects unbuilt internal deps and runs the monorepo's
+ * build once (the root `build` script, else `turbo run build`); turbo's cache
+ * makes an already-built repo near-instant. A build failure is surfaced with
+ * an actionable message instead of a cryptic `Cannot find module` at boot.
+ */
+export function ensureWorkspaceDepsBuilt(cwd, packageManager, onProgress) {
+    const root = workspaceRoot(cwd);
+    if (!root) {
+        return;
+    }
+    const unbuilt = unbuiltWorkspaceDeps(cwd);
+    if (unbuilt.length === 0) {
+        return;
+    }
+    onProgress?.(`building workspace packages (${unbuilt.slice(0, 3).join(', ')}${unbuilt.length > 3 ? '…' : ''})`);
+    let rootBuild = null;
+    try {
+        const rootPkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (rootPkg.scripts?.build) {
+            rootBuild = { command: packageManager, args: ['run', 'build'] };
+        }
+    }
+    catch {
+        // fall through to turbo
+    }
+    if (!rootBuild && fs.existsSync(path.join(root, 'turbo.json'))) {
+        rootBuild = { command: 'npx', args: ['turbo', 'run', 'build'] };
+    }
+    if (!rootBuild) {
+        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) must be built before the dev server can boot, and the monorepo has no root \`build\` script or turbo config to run. Build them yourself, then re-run \`npx fimo migrate\`.`);
+    }
+    const result = spawnSync(rootBuild.command, rootBuild.args, {
+        cwd: root,
+        timeout: 300_000,
+        encoding: 'utf8',
+        env: { ...process.env, NEXT_TELEMETRY_DISABLED: '1' },
+    });
+    if (result.status !== 0) {
+        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) need building for the dev server, but \`${rootBuild.command} ${rootBuild.args.join(' ')}\` failed at ${path.relative(cwd, root) || 'the repo root'}. Build them yourself, then re-run \`npx fimo migrate\`.\n${(result.stderr || result.stdout || '').slice(-800)}`);
+    }
+}
+export async function startDevServer(opts) {
+    preflight(opts.cwd);
+    const port = await findFreePort();
+    const child = spawn(opts.packageManager, ['run', 'dev'], {
+        cwd: opts.cwd,
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, PORT: String(port), NEXT_TELEMETRY_DISABLED: '1', BROWSER: 'none' },
+    });
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+    child.stdout?.on('data', (chunk) => {
+        stdoutBuffer = `${stdoutBuffer}${chunk.toString()}`.slice(-8_000);
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderrBuffer = `${stderrBuffer}${chunk.toString()}`.slice(-8_000);
+    });
+    let exited = false;
+    child.on('exit', () => {
+        exited = true;
+    });
+    const stop = async () => {
+        if (exited || child.pid === undefined) {
+            return;
+        }
+        try {
+            if (process.platform === 'win32') {
+                spawn('taskkill', ['/pid', String(child.pid), '/T', '/F']);
+            }
+            else {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+        }
+        catch {
+            child.kill('SIGTERM');
+        }
+        const deadline = Date.now() + KILL_GRACE_MS;
+        while (!exited && Date.now() < deadline) {
+            await sleep(100);
+        }
+        if (!exited && child.pid !== undefined && process.platform !== 'win32') {
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+    };
+    // Readiness: an HTTP response BELOW 500 counts as listening (a 404 means
+    // the router is up). Nuxt's dev server answers 503 immediately while Vite
+    // still builds — treating that as ready captured a baseline of 503s.
+    // Dev scripts that hardcode their own port are handled by sniffing stdout.
+    const probe = async (origin) => {
+        try {
+            const response = await fetch(origin, { signal: AbortSignal.timeout(2_000) });
+            return response.status < 500;
+        }
+        catch {
+            return false;
+        }
+    };
+    // Probe via the `localhost` hostname, never a numeric loopback: Vite-family
+    // servers (Astro, Nuxt, SvelteKit) may bind ::1 only, and Node's fetch
+    // tries both address families for a hostname (Happy Eyeballs).
+    const deadline = Date.now() + opts.bootTimeoutMs;
+    let origin = `http://localhost:${port}`;
+    while (Date.now() < deadline) {
+        if (exited) {
+            await stop();
+            throw new CaptureError('The dev server exited before becoming ready.', stderrBuffer || stdoutBuffer);
+        }
+        if (await probe(origin)) {
+            return { origin, stderrTail: () => stderrBuffer, stop };
+        }
+        const sniffed = stdoutBuffer.match(/(?:localhost|127\.0\.0\.1):(\d{2,5})/);
+        if (sniffed && Number(sniffed[1]) !== port) {
+            const candidate = `http://localhost:${sniffed[1]}`;
+            if (await probe(candidate)) {
+                origin = candidate;
+                return { origin, stderrTail: () => stderrBuffer, stop };
+            }
+        }
+        await sleep(READINESS_POLL_MS);
+    }
+    await stop();
+    throw new CaptureError(`The dev server did not answer within ${Math.round(opts.bootTimeoutMs / 1000)}s.`, stderrBuffer || stdoutBuffer);
+}
+async function fetchRoute(origin, routePath, timeoutMs) {
+    const response = await fetch(new URL(routePath, origin), {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { accept: 'text/html' },
+    });
+    return { status: response.status, html: await response.text() };
+}
+/**
+ * Boot the project's own dev server, capture every static route's normalized
+ * signature, and tear the server down. Baseline and check both run through
+ * this identical pipeline — that symmetry is the gate's correctness property.
+ */
+export async function captureParityBaseline(opts) {
+    const bootTimeoutMs = opts.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
+    const routeTimeoutMs = opts.routeTimeoutMs ?? DEFAULT_ROUTE_TIMEOUT_MS;
+    const routes = {};
+    const paramValues = opts.paramValues ?? {};
+    // Capturable = a concrete URL exists (no params, or all params resolved via
+    // paramValues). The capture is keyed by the ORIGINAL route.path so baseline
+    // and check line up; only the fetched URL is the resolved one.
+    const staticRoutes = [];
+    for (const route of opts.routes) {
+        const resolved = route.path.includes(':') ? resolveRoutePath(route.path, paramValues) : route.path;
+        if (resolved === null) {
+            routes[route.path] = { skipped: 'dynamic-params' };
+        }
+        else {
+            staticRoutes.push({ path: route.path, url: resolved });
+        }
+    }
+    let server;
+    if (opts.serverOrigin) {
+        const origin = opts.serverOrigin.replace(/\/+$/, '');
+        opts.onProgress?.(`using the running dev server at ${origin}`);
+        try {
+            await fetch(origin, { signal: AbortSignal.timeout(5_000) });
+        }
+        catch {
+            throw new CaptureError(`No dev server answered at ${origin} — start it (e.g. \`${opts.packageManager} run dev\`) or drop --server to boot one.`);
+        }
+        server = { origin, stderrTail: () => '', stop: async () => { } };
+    }
+    else {
+        // Monorepo: build the app's workspace deps before the bare dev boot, or
+        // `next dev` dies on `Cannot find module '@repo/…'`.
+        ensureWorkspaceDepsBuilt(opts.cwd, opts.packageManager, opts.onProgress);
+        const bootStartedAt = Date.now();
+        opts.onProgress?.('starting your dev server');
+        const bootTicker = setInterval(() => {
+            opts.onProgress?.(`starting your dev server (${Math.round((Date.now() - bootStartedAt) / 1000)}s)`);
+        }, 5_000);
+        bootTicker.unref();
+        try {
+            server = await startDevServer({ cwd: opts.cwd, packageManager: opts.packageManager, bootTimeoutMs });
+        }
+        finally {
+            clearInterval(bootTicker);
+        }
+    }
+    try {
+        // Sequential on purpose: dev compilers choke on parallel cold compiles.
+        let index = 0;
+        for (const route of staticRoutes) {
+            index += 1;
+            const routeStartedAt = Date.now();
+            const progress = () => {
+                const elapsed = Math.round((Date.now() - routeStartedAt) / 1000);
+                opts.onProgress?.(`capturing ${route.path} (${index}/${staticRoutes.length}${elapsed >= 5 ? `, ${elapsed}s` : ''})`);
+            };
+            progress();
+            const routeTicker = setInterval(progress, 5_000);
+            routeTicker.unref();
+            try {
+                let result = await fetchRoute(server.origin, route.url, routeTimeoutMs).catch(async () => {
+                    // One retry: first-compile latency and transient dev-server flake.
+                    await sleep(1_000);
+                    return fetchRoute(server.origin, route.url, routeTimeoutMs);
+                });
+                if (result.status >= 500) {
+                    await sleep(1_000);
+                    const retried = await fetchRoute(server.origin, route.url, routeTimeoutMs).catch(() => null);
+                    if (retried) {
+                        result = retried;
+                    }
+                }
+                routes[route.path] = {
+                    signature: extractRouteSignature(result.html, { origin: server.origin, status: result.status }),
+                };
+            }
+            catch (error) {
+                routes[route.path] = { skipped: 'fetch-failed', error: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                clearInterval(routeTicker);
+            }
+        }
+        // Second pass for error pages: by now the dev server is fully warm, so a
+        // 500 recorded above was very likely a cold-compile flake. An error
+        // snapshot poisons the baseline (the parity gate would compare against
+        // the error page forever), so retry once more before accepting it.
+        for (const route of staticRoutes) {
+            const capture = routes[route.path];
+            if (capture && 'signature' in capture && capture.signature.status >= 500) {
+                opts.onProgress?.(`retrying ${route.path} (captured ${capture.signature.status})`);
+                const retried = await fetchRoute(server.origin, route.url, routeTimeoutMs).catch(() => null);
+                if (retried && retried.status < 500) {
+                    routes[route.path] = {
+                        signature: extractRouteSignature(retried.html, { origin: server.origin, status: retried.status }),
+                    };
+                }
+            }
+        }
+    }
+    finally {
+        await server.stop();
+    }
+    return {
+        version: PARITY_BASELINE_VERSION,
+        capturedAt: new Date().toISOString(),
+        engine: 'dev-server',
+        framework: opts.framework,
+        command: `${opts.packageManager} run dev`,
+        routes,
+    };
+}

package/dist/scripts/render-parity/capture.test.d.ts

@@ -0,0 +1 @@
+export {};