fimo 0.8.0 → 0.9.0-experimental.10

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

@@ -0,0 +1,64 @@
+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);
+}
+/**
+ * pnpm's minimumReleaseAge setting refuses freshly published packages —
+ * exactly what a just-published fimo experimental is. The refusal surfaces
+ * deep in install/boot output; detect it and hand back the one-line fix
+ * instead of leaving an opaque boot failure.
+ */
+export declare function pnpmReleaseAgeHint(output: string): string | null;
+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. Builds are SCOPED to the flagged packages (turbo/pnpm/npm
+ * filters) — the root build script builds the whole app too and fails for
+ * reasons unrelated to the deps; it is only the last resort when no filter
+ * mechanism exists. 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,436 @@
+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;
+    }
+}
+/**
+ * pnpm's minimumReleaseAge setting refuses freshly published packages —
+ * exactly what a just-published fimo experimental is. The refusal surfaces
+ * deep in install/boot output; detect it and hand back the one-line fix
+ * instead of leaving an opaque boot failure.
+ */
+export function pnpmReleaseAgeHint(output) {
+    if (!/minimumReleaseAge|ERR_PNPM_.*RELEASE/i.test(output)) {
+        return null;
+    }
+    return ('pnpm is refusing a freshly published package (minimumReleaseAge). ' +
+        'Add `minimumReleaseAgeExclude: ["fimo"]` to pnpm-workspace.yaml (or set `minimumReleaseAge: 0`), ' +
+        're-run your install, then re-run `npx fimo migrate`.');
+}
+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;
+}
+/** Every relative path target in an exports map (conditions and subpaths
+ *  flattened; `require`/`import`/`types`/`default` values alike). */
+function exportsTargets(exportsMap) {
+    if (typeof exportsMap === 'string') {
+        return exportsMap.startsWith('./') ? [exportsMap] : [];
+    }
+    if (Array.isArray(exportsMap)) {
+        return exportsMap.flatMap(exportsTargets);
+    }
+    if (exportsMap && typeof exportsMap === 'object') {
+        return Object.values(exportsMap).flatMap(exportsTargets);
+    }
+    return [];
+}
+/** A target file (or, for a `*` pattern, its base directory) exists. */
+function exportsTargetExists(depDir, target) {
+    const star = target.indexOf('*');
+    if (star === -1) {
+        return fs.existsSync(path.join(depDir, target));
+    }
+    const base = target.slice(0, star).replace(/\/[^/]*$/, '');
+    return fs.existsSync(path.join(depDir, base || '.'));
+}
+/** 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: unbuilt when a RESOLVED target is missing — an
+            // exports map pointing at checked-in sources (eslint configs, type-only
+            // packages) never produces dist/ and must not be flagged forever.
+            const targets = exportsTargets(depPkg.exports);
+            return targets.length > 0 && targets.some((target) => !exportsTargetExists(depDir, target));
+        }
+        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. Builds are SCOPED to the flagged packages (turbo/pnpm/npm
+ * filters) — the root build script builds the whole app too and fails for
+ * reasons unrelated to the deps; it is only the last resort when no filter
+ * mechanism exists. 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 build = null;
+    if (fs.existsSync(path.join(root, 'turbo.json'))) {
+        build = { command: 'npx', args: ['turbo', 'run', 'build', ...unbuilt.map((name) => `--filter=${name}`)] };
+    }
+    else if (packageManager === 'pnpm') {
+        build = {
+            command: 'pnpm',
+            args: [...unbuilt.flatMap((name) => ['--filter', name]), 'run', '--if-present', 'build'],
+        };
+    }
+    else if (packageManager === 'npm') {
+        build = {
+            command: 'npm',
+            args: ['run', 'build', '--if-present', ...unbuilt.flatMap((name) => ['--workspace', name])],
+        };
+    }
+    else {
+        // No filter mechanism (yarn classic, bun) — the root build is the last resort.
+        try {
+            const rootPkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+            if (rootPkg.scripts?.build) {
+                build = { command: packageManager, args: ['run', 'build'] };
+            }
+        }
+        catch {
+            // handled below
+        }
+    }
+    if (!build) {
+        throw new CaptureError(`Workspace packages (${unbuilt.join(', ')}) must be built before the dev server can boot, and the monorepo has no build mechanism the migration can drive. Build them yourself, then re-run \`npx fimo migrate\`.`);
+    }
+    const result = spawnSync(build.command, build.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 \`${build.command} ${build.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 {
+            // A generous per-attempt cap: connection-refused fails instantly, so
+            // this only holds when a server is LISTENING but slow (first SSR
+            // compile) — the exact case a short timeout misclassified as down.
+            const response = await fetch(origin, { signal: AbortSignal.timeout(15_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}`);
+        // Retry across a mid-recompile stall (Turbopack holds requests for
+        // seconds) — one short-timeout attempt misread a busy server as down.
+        let answered = false;
+        for (let attempt = 0; attempt < 3 && !answered; attempt++) {
+            try {
+                await fetch(origin, { signal: AbortSignal.timeout(10_000) });
+                answered = true;
+            }
+            catch {
+                if (attempt < 2) {
+                    await sleep(2_000);
+                }
+            }
+        }
+        if (!answered) {
+            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/compare.d.ts

@@ -0,0 +1,59 @@
+import type { InlineMark, ParityBaseline } from './types.js';
+export interface BlockFinding {
+    kind: 'text-changed' | 'block-missing' | 'block-added' | 'marks-changed';
+    index: number;
+    tag?: string;
+    before?: string;
+    after?: string;
+    marksBefore?: InlineMark[];
+    marksAfter?: InlineMark[];
+}
+export interface MediaFinding {
+    kind: 'changed' | 'missing' | 'added' | 'rehosted';
+    index: number;
+    before?: string;
+    after?: string;
+}
+export interface LinkFinding {
+    kind: 'changed' | 'missing' | 'added';
+    index: number;
+    before?: string;
+    after?: string;
+}
+export interface RouteDiff {
+    route: string;
+    clean: boolean;
+    unverified?: boolean;
+    statusChange?: {
+        before: number;
+        after: number;
+    };
+    blocks: BlockFinding[];
+    images: MediaFinding[];
+    videos: MediaFinding[];
+    links: LinkFinding[];
+    notes: string[];
+}
+export interface ParityComparison {
+    diffs: RouteDiff[];
+    clean: number;
+    drifted: number;
+    unverified: number;
+}
+export interface CompareOptions {
+    /**
+     * Full-match regexes for text that is dynamic BY THE SITE'S OWN DESIGN
+     * (live clocks, visitor counters). A block whose text fully matches the
+     * same pattern in baseline and current compares as equal. Recorded in
+     * `.fimo/migration/manifest.json` → `wrap.parityIgnores` with a reason.
+     */
+    ignoreTextPatterns?: string[];
+    /**
+     * Routes whose content drifts by DECISION — they render a keep-live
+     * external data source (`wrap.dataSources` → live). Counted as
+     * unverified, never silently clean.
+     */
+    ignoreRoutes?: string[];
+}
+export declare function compareBaselines(baseline: ParityBaseline, current: ParityBaseline, options?: CompareOptions): ParityComparison;
+export declare function formatRouteDiff(diff: RouteDiff): string[];

package/dist/scripts/render-parity/normalize-html.d.ts

@@ -0,0 +1,13 @@
+import type { RouteSignature } from './types.js';
+/** Strip the capture origin so differing ports between runs compare equal. */
+export declare function normalizeHref(href: string, origin: string): string;
+/**
+ * Media src normalization: origin strip + Next image-optimizer decode, so a
+ * pre-wrap `next/image` (`/_next/image?url=…&w=…`) and a post-wrap plain
+ * `<img src>` of the same asset compare equal.
+ */
+export declare function normalizeMediaSrc(src: string, origin: string): string;
+export declare function extractRouteSignature(html: string, opts: {
+    origin: string;
+    status: number;
+}): RouteSignature;