fimo 0.8.0 → 0.9.0-experimental.1

package/dist/scripts/i18n-namespace.js

@@ -0,0 +1,155 @@
+/**
+ * Shared next-intl namespace resolution for the two independent label-key
+ * scanners (`extract-translations` for `fimo validate`, `scan-wrappable` for
+ * `migrate wrap --check`). Both must record the SAME key form the i18n
+ * ingestion stores, or the seeding gate can never go green.
+ *
+ * `const t = useTranslations("plans.checkout")` scopes every `t("buyNow")` in
+ * that component to `plans.checkout.buyNow`. Root-scoped `useTranslations()`
+ * (namespace `""`) and server `getTranslations` are handled; a bare `t(...)`
+ * with no binding (Fimo's own label call) keeps its key unchanged.
+ */
+export const isFunctionLike = (node) => node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression';
+/** Collect `useTranslations`/`getTranslations` bindings declared in a function's
+ *  direct body: variable name → namespace (`""` for root scope). */
+const unwrapAwait = (node) => (node?.type === 'AwaitExpression' ? node.argument : node);
+/**
+ * The namespace of a `useTranslations`/`getTranslations` call, or null if the
+ * node is not such a call. Handles the string arg (`getTranslations("seo")`),
+ * the object arg (`getTranslations({ locale, namespace: "seo" })`), and no arg
+ * (root scope → `""`). A dynamic namespace resolves to `""` (best effort).
+ */
+function translationCallNamespace(node) {
+    if (node?.type !== 'CallExpression' || node.callee?.type !== 'Identifier') {
+        return null;
+    }
+    if (node.callee.name !== 'useTranslations' && node.callee.name !== 'getTranslations') {
+        return null;
+    }
+    const arg = node.arguments?.[0];
+    if (!arg) {
+        return '';
+    }
+    if (arg.type === 'Literal' && typeof arg.value === 'string') {
+        return arg.value;
+    }
+    if (arg.type === 'ObjectExpression') {
+        for (const prop of arg.properties ?? []) {
+            const keyName = prop?.key?.name ?? prop?.key?.value;
+            if (keyName === 'namespace' && prop.value?.type === 'Literal' && typeof prop.value.value === 'string') {
+                return prop.value.value;
+            }
+        }
+    }
+    return '';
+}
+/** Mark every identifier bound by a parameter pattern (plain, defaulted, or
+ *  destructured — `t`, `t = x`, `{ t }`, `[t]`) as unresolvable (null). */
+function markParamBindings(node, bindings) {
+    if (!node) {
+        return;
+    }
+    switch (node.type) {
+        case 'Identifier':
+            if (!bindings.has(node.name)) {
+                bindings.set(node.name, null);
+            }
+            break;
+        case 'AssignmentPattern':
+            markParamBindings(node.left, bindings);
+            break;
+        case 'RestElement':
+            markParamBindings(node.argument, bindings);
+            break;
+        case 'ArrayPattern':
+            for (const element of node.elements ?? []) {
+                markParamBindings(element, bindings);
+            }
+            break;
+        case 'ObjectPattern':
+            for (const prop of node.properties ?? []) {
+                markParamBindings(prop.type === 'RestElement' ? prop.argument : prop.value, bindings);
+            }
+            break;
+        default:
+            break;
+    }
+}
+export function collectScopedBindings(fnNode) {
+    const bindings = new Map();
+    const body = fnNode.body;
+    const statements = body && Array.isArray(body.body) ? body.body : [];
+    for (const stmt of statements) {
+        if (stmt?.type !== 'VariableDeclaration') {
+            continue;
+        }
+        for (const decl of stmt.declarations ?? []) {
+            const init = unwrapAwait(decl?.init);
+            // `const t = [await] useTranslations/getTranslations(...)`
+            if (decl?.id?.type === 'Identifier') {
+                const namespace = translationCallNamespace(init);
+                if (namespace !== null) {
+                    bindings.set(decl.id.name, namespace);
+                }
+                continue;
+            }
+            // `const [a, t] = await Promise.all([...])` or `= use(Promise.all([...]))`
+            if (decl?.id?.type === 'ArrayPattern') {
+                // Unwrap React's `use()` wrapper around the promise.
+                const source = init?.type === 'CallExpression' && init.callee?.type === 'Identifier' && init.callee.name === 'use'
+                    ? unwrapAwait(init.arguments?.[0])
+                    : init;
+                const promiseAll = source?.type === 'CallExpression' &&
+                    source.callee?.type === 'MemberExpression' &&
+                    source.callee.object?.name === 'Promise' &&
+                    source.callee.property?.name === 'all';
+                const elements = promiseAll
+                    ? source.arguments?.[0]?.type === 'ArrayExpression'
+                        ? source.arguments[0].elements
+                        : null
+                    : source?.type === 'ArrayExpression'
+                        ? source.elements
+                        : null;
+                if (elements) {
+                    decl.id.elements?.forEach((el, index) => {
+                        if (el?.type !== 'Identifier') {
+                            return;
+                        }
+                        const namespace = translationCallNamespace(unwrapAwait(elements[index]));
+                        if (namespace !== null) {
+                            bindings.set(el.name, namespace);
+                        }
+                    });
+                }
+            }
+        }
+    }
+    // Function parameters are bound by the CALLER: a `t` passed in carries the
+    // caller's namespace, unknowable here. Mark them null so their t() calls are
+    // counted as covered but never demanded by the seeding gate as a bare leaf.
+    for (const param of fnNode.params ?? []) {
+        markParamBindings(param, bindings);
+    }
+    return bindings;
+}
+/**
+ * Resolve a `<name>("leaf")` call to its full key given the scope stack
+ * (innermost first).
+ * - `scoped`: the callee is a resolved `useTranslations` binding — namespace
+ *   prepended (unless root `""`).
+ * - `unresolvable`: the callee is a passed-in parameter — its namespace lives in
+ *   the caller and cannot be known here, so the caller should count the call as
+ *   covered but NOT demand the (bare) key.
+ */
+export function resolveScopedKey(calleeName, leafKey, scopes) {
+    for (let i = scopes.length - 1; i >= 0; i -= 1) {
+        if (scopes[i].has(calleeName)) {
+            const namespace = scopes[i].get(calleeName);
+            if (namespace === null || namespace === undefined) {
+                return { key: leafKey, scoped: false, unresolvable: true };
+            }
+            return { key: namespace ? `${namespace}.${leafKey}` : leafKey, scoped: true, unresolvable: false };
+        }
+    }
+    return { key: leafKey, scoped: false, unresolvable: false };
+}

package/dist/scripts/lib/validation-report.d.ts

@@ -23,6 +23,7 @@ export interface PhaseResult {
     skipped?: {
         reason: string;
     };
+    warnings?: string[];
 }
 export interface ValidationReport {
     ok: boolean;

package/dist/scripts/lib/validation-report.js

@@ -76,6 +76,9 @@ function formatPhaseHuman(phase) {
             out.push(`    ${parts.join(', ')}`);
         }
     }
+    for (const warning of phase.warnings ?? []) {
+        out.push(`    ⚠ ${warning}`);
+    }
     for (const err of phase.errors) {
         const loc = err.file ? ` (${err.file}${err.line ? `:${err.line}` : ''}${err.column ? `:${err.column}` : ''})` : '';
         out.push(`    [${err.kind}] ${err.rule}: ${err.message}${loc}`);

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/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;