fimo 0.6.0 → 0.7.0-experimental.10

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

@@ -0,0 +1,306 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { captureParityBaseline, CaptureError, ensureWorkspaceDepsBuilt, findFreePort, resolveRoutePath, } from './capture.js';
+let dir;
+/**
+ * Hermetic fixture: a project whose `dev` script is a tiny node server
+ * honoring PORT — exercises the whole engine without Next.
+ */
+const SERVER_JS = `
+const http = require('http');
+http
+  .createServer((req, res) => {
+    if (req.url === '/about') {
+      res.writeHead(200, { 'content-type': 'text/html' });
+      res.end('<html><body><h1>About us</h1><p>We are <strong>honest</strong>.</p></body></html>');
+      return;
+    }
+    if (req.url === '/broken') {
+      res.writeHead(500, { 'content-type': 'text/html' });
+      res.end('<html><body><p>error page placeholder</p></body></html>');
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'text/html' });
+    res.end('<html><body><h1>Home</h1><img src="/hero.png"/><a href="/whitepaper.pdf">PDF</a></body></html>');
+  })
+  .listen(process.env.PORT, '127.0.0.1');
+`;
+/**
+ * Vite-family behavior (Astro, Nuxt, SvelteKit): ignores PORT, picks its own
+ * port, binds the IPv6 loopback only, and announces itself with a
+ * `localhost:<port>` banner. The engine must sniff the banner and probe via
+ * the hostname (a numeric 127.0.0.1 probe never reaches a ::1-only server).
+ */
+const IPV6_SNIFF_SERVER_JS = `
+const http = require('http');
+const server = http.createServer((req, res) => {
+  res.writeHead(200, { 'content-type': 'text/html' });
+  res.end('<html><body><h1>Home</h1></body></html>');
+});
+const announce = () => console.log('  | Local    http://localhost:' + server.address().port + '/');
+server.listen(0, '::1', announce).on('error', () => server.listen(0, '127.0.0.1', announce));
+`;
+/**
+ * Nuxt-dev behavior: the HTTP socket answers immediately but serves 503
+ * until the app finishes building. Readiness must wait for a sub-500.
+ */
+const BOOT_503_SERVER_JS = `
+const http = require('http');
+const startedAt = Date.now();
+http
+  .createServer((req, res) => {
+    if (Date.now() - startedAt < 2000) {
+      res.writeHead(503, { 'content-type': 'text/html' });
+      res.end('<html><body>Server is starting</body></html>');
+      return;
+    }
+    res.writeHead(200, { 'content-type': 'text/html' });
+    res.end('<html><body><h1>Home</h1></body></html>');
+  })
+  .listen(process.env.PORT, '127.0.0.1');
+`;
+const project = (opts = {}) => {
+    dir = mkdtempSync(join(tmpdir(), 'parity-capture-'));
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 't', scripts: { dev: opts.devScript ?? 'node server.js' } }));
+    writeFileSync(join(dir, 'server.js'), SERVER_JS);
+    writeFileSync(join(dir, 'server-ipv6.js'), IPV6_SNIFF_SERVER_JS);
+    writeFileSync(join(dir, 'server-503-then-200.js'), BOOT_503_SERVER_JS);
+    if (opts.withNodeModules !== false) {
+        mkdirSync(join(dir, 'node_modules'), { recursive: true });
+    }
+    return dir;
+};
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('findFreePort', () => {
+    it('returns a usable port', async () => {
+        const port = await findFreePort();
+        expect(port).toBeGreaterThan(0);
+    });
+});
+describe('ensureWorkspaceDepsBuilt (monorepo pre-build)', () => {
+    const monorepo = (opts) => {
+        dir = mkdtempSync(join(tmpdir(), 'ws-build-'));
+        writeFileSync(join(dir, 'pnpm-workspace.yaml'), "packages:\n  - 'apps/*'\n  - 'packages/*'\n");
+        writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'root', private: true, scripts: opts.rootBuild ? { build: opts.rootBuild } : {} }));
+        // The app depends on an internal workspace package.
+        mkdirSync(join(dir, 'apps/ui'), { recursive: true });
+        writeFileSync(join(dir, 'apps/ui/package.json'), JSON.stringify({ name: '@repo/ui', dependencies: { '@repo/shared': 'workspace:*' } }));
+        // The internal package, symlink-style resolved under the app's node_modules.
+        const depDir = join(dir, 'apps/ui/node_modules/@repo/shared');
+        mkdirSync(depDir, { recursive: true });
+        writeFileSync(join(depDir, 'package.json'), JSON.stringify({ name: '@repo/shared', main: 'dist/index.js' }));
+        if (opts.depBuilt) {
+            mkdirSync(join(depDir, 'dist'), { recursive: true });
+            writeFileSync(join(depDir, 'dist/index.js'), 'module.exports = {};');
+        }
+        return { root: dir, app: join(dir, 'apps/ui'), depDir };
+    };
+    it('builds the app`s unbuilt workspace deps via the root build script', () => {
+        // The root build script materializes the missing dist so a later boot works.
+        const build = "node -e \"require('fs').mkdirSync('apps/ui/node_modules/@repo/shared/dist',{recursive:true});require('fs').writeFileSync('apps/ui/node_modules/@repo/shared/dist/index.js','')\"";
+        const { app, depDir } = monorepo({ rootBuild: build, depBuilt: false });
+        ensureWorkspaceDepsBuilt(app, 'npm');
+        expect(existsSync(join(depDir, 'dist/index.js'))).toBe(true);
+    });
+    it('is a no-op when the workspace deps are already built', () => {
+        const { app } = monorepo({ rootBuild: 'exit 1', depBuilt: true });
+        // depBuilt → nothing to build → the failing build script is never run.
+        expect(() => ensureWorkspaceDepsBuilt(app, 'npm')).not.toThrow();
+    });
+    it('does nothing for a standalone (non-monorepo) app', () => {
+        dir = mkdtempSync(join(tmpdir(), 'standalone-'));
+        writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'solo', dependencies: { next: '^15.0.0' } }));
+        expect(() => ensureWorkspaceDepsBuilt(dir, 'npm')).not.toThrow();
+    });
+    it('throws an actionable error when the build fails', () => {
+        const { app } = monorepo({ rootBuild: 'exit 1', depBuilt: false });
+        expect(() => ensureWorkspaceDepsBuilt(app, 'npm')).toThrow(/need building|failed/i);
+    });
+});
+describe('resolveRoutePath (dynamic param substitution)', () => {
+    it('substitutes known params and reports unresolved ones', () => {
+        expect(resolveRoutePath('/:locale/blog', { locale: 'en' })).toBe('/en/blog');
+        expect(resolveRoutePath('/:locale', { locale: 'fr' })).toBe('/fr');
+        // A content param with no value stays unresolved → the route is skipped.
+        expect(resolveRoutePath('/:locale/blog/:slug', { locale: 'en' })).toBeNull();
+        expect(resolveRoutePath('/blog/:slug', { locale: 'en' })).toBeNull();
+        expect(resolveRoutePath('/static', {})).toBe('/static');
+    });
+});
+describe('captureParityBaseline', () => {
+    it('boots the dev server, captures routes, and tears down', async () => {
+        const cwd = project();
+        const baseline = await captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: 'next',
+            routes: [{ path: '/' }, { path: '/about' }, { path: '/blog/:slug' }],
+            bootTimeoutMs: 30_000,
+            routeTimeoutMs: 10_000,
+        });
+        expect(baseline.version).toBe(1);
+        const home = baseline.routes['/'];
+        expect('signature' in home && home.signature.blocks[0]).toEqual({ tag: 'h1', text: 'Home', marks: [] });
+        expect('signature' in home && home.signature.images).toEqual(['/hero.png']);
+        const about = baseline.routes['/about'];
+        expect('signature' in about && about.signature.blocks[1].marks[0]).toEqual({ kind: 'strong', text: 'honest' });
+        expect(baseline.routes['/blog/:slug']).toEqual({ skipped: 'dynamic-params' });
+    }, 60_000);
+    it('captures [locale] routes by substituting the param (i18n sites are no longer all-skipped)', async () => {
+        const cwd = project();
+        const baseline = await captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: 'next',
+            routes: [{ path: '/:locale' }, { path: '/:locale/blog/:slug' }],
+            paramValues: { locale: 'en' },
+            bootTimeoutMs: 30_000,
+            routeTimeoutMs: 10_000,
+        });
+        // Keyed by the ORIGINAL path, captured from the resolved /en URL.
+        const localeRoot = baseline.routes['/:locale'];
+        expect('signature' in localeRoot && localeRoot.signature.blocks[0].text).toBe('Home');
+        // A content param (:slug) still can't be resolved → skipped.
+        expect(baseline.routes['/:locale/blog/:slug']).toEqual({ skipped: 'dynamic-params' });
+    }, 60_000);
+    it('records 5xx status as part of the signature', async () => {
+        const cwd = project();
+        const baseline = await captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: 'next',
+            routes: [{ path: '/broken' }],
+            bootTimeoutMs: 30_000,
+            routeTimeoutMs: 10_000,
+        });
+        const broken = baseline.routes['/broken'];
+        expect('signature' in broken && broken.signature.status).toBe(500);
+    }, 60_000);
+    it('waits through boot-time 503s (nuxi answers before the app is built)', async () => {
+        const cwd = project({ devScript: 'node server-503-then-200.js' });
+        const baseline = await captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: 'nuxt',
+            routes: [{ path: '/' }],
+            bootTimeoutMs: 30_000,
+            routeTimeoutMs: 10_000,
+        });
+        const home = baseline.routes['/'];
+        expect('signature' in home && home.signature.status).toBe(200);
+    }, 60_000);
+    it('finds a PORT-ignoring, ::1-bound server through its localhost banner', async () => {
+        const cwd = project({ devScript: 'node server-ipv6.js' });
+        const baseline = await captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: 'astro',
+            routes: [{ path: '/' }],
+            bootTimeoutMs: 30_000,
+            routeTimeoutMs: 10_000,
+        });
+        const home = baseline.routes['/'];
+        expect('signature' in home && home.signature.status).toBe(200);
+    }, 60_000);
+    it('fails fast without node_modules', async () => {
+        const cwd = project({ withNodeModules: false });
+        await expect(captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: null,
+            routes: [{ path: '/' }],
+            bootTimeoutMs: 5_000,
+        })).rejects.toThrow(CaptureError);
+    });
+    it('surfaces stderr when the dev server dies at boot', async () => {
+        const cwd = project({ devScript: 'node -e "console.error(\'FATAL: nope\'); process.exit(1)"' });
+        await expect(captureParityBaseline({
+            cwd,
+            packageManager: 'npm',
+            framework: null,
+            routes: [{ path: '/' }],
+            bootTimeoutMs: 15_000,
+        })).rejects.toMatchObject({ stderrTail: expect.stringContaining('FATAL: nope') });
+    }, 30_000);
+});
+it('retries error routes once the server is warm instead of poisoning the baseline', async () => {
+    const { mkdtempSync, writeFileSync, rmSync, mkdirSync } = await import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const dir = mkdtempSync(join(tmpdir(), 'warm-retry-'));
+    try {
+        mkdirSync(join(dir, 'node_modules'), { recursive: true });
+        // First hit on /flaky answers 500 (cold compile), later hits answer 200.
+        writeFileSync(join(dir, 'server.js'), `const http = require('http');
+let flakyHits = 0;
+http.createServer((req, res) => {
+  if (req.url.startsWith('/flaky')) {
+    flakyHits += 1;
+    if (flakyHits <= 2) { res.writeHead(500); res.end(''); return; }
+    res.writeHead(200, {'content-type': 'text/html'});
+    res.end('<html><body><h1>Recovered</h1></body></html>');
+    return;
+  }
+  res.writeHead(200, {'content-type': 'text/html'});
+  res.end('<html><body><h1>Home</h1></body></html>');
+}).listen(process.env.PORT || 0, '127.0.0.1');`);
+        writeFileSync(join(dir, 'package.json'), JSON.stringify({ scripts: { dev: 'node server.js' } }));
+        const baseline = await captureParityBaseline({
+            cwd: dir,
+            packageManager: 'npm',
+            routes: [{ path: '/' }, { path: '/flaky' }],
+            framework: 'next',
+            bootTimeoutMs: 20_000,
+            routeTimeoutMs: 5_000,
+        });
+        const flaky = baseline.routes['/flaky'];
+        expect(flaky && 'signature' in flaky ? flaky.signature.status : null).toBe(200);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}, 30_000);
+it('reuses a running server via serverOrigin without booting or stopping it', async () => {
+    const http = await import('node:http');
+    const server = http.createServer((_req, res) => {
+        res.writeHead(200, { 'content-type': 'text/html' });
+        res.end('<html><body><h1>Warm</h1></body></html>');
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    const origin = `http://127.0.0.1:${typeof address === 'object' && address ? address.port : 0}`;
+    try {
+        // cwd with no dev script and no node_modules: booting would fail loudly.
+        const { mkdtempSync, rmSync } = await import('node:fs');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const dir = mkdtempSync(join(tmpdir(), 'warm-origin-'));
+        try {
+            const baseline = await captureParityBaseline({
+                cwd: dir,
+                packageManager: 'npm',
+                routes: [{ path: '/' }],
+                framework: 'next',
+                serverOrigin: origin,
+                routeTimeoutMs: 5_000,
+            });
+            const route = baseline.routes['/'];
+            expect(route && 'signature' in route ? route.signature.status : null).toBe(200);
+            // the server is still ours and still alive
+            const probe = await fetch(origin);
+            expect(probe.status).toBe(200);
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    finally {
+        server.close();
+    }
+}, 20_000);

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/compare.test.d.ts

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

package/dist/scripts/render-parity/compare.test.js

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import { compareBaselines, formatRouteDiff } from './compare.js';
+const signature = (over = {}) => ({
+    status: 200,
+    blocks: [
+        { tag: 'h1', text: 'Ship faster', marks: [] },
+        { tag: 'p', text: 'Read honest numbers today', marks: [{ kind: 'strong', text: 'honest numbers' }] },
+        { tag: 'p', text: 'Get early access', marks: [] },
+    ],
+    images: ['/images/hero.png'],
+    videos: [],
+    links: [{ href: '/whitepaper.pdf', text: 'PDF' }],
+    ...over,
+});
+const baseline = (routes) => ({
+    version: 1,
+    capturedAt: '2026-07-06T00:00:00Z',
+    engine: 'dev-server',
+    framework: 'next',
+    command: 'npm run dev',
+    routes: Object.fromEntries(Object.entries(routes).map(([route, sig]) => [route, { signature: sig }])),
+});
+describe('compareBaselines', () => {
+    it('reports clean when identical', () => {
+        const result = compareBaselines(baseline({ '/': signature() }), baseline({ '/': signature() }));
+        expect(result).toMatchObject({ clean: 1, drifted: 0, unverified: 0 });
+    });
+    it('reports a single text change with index and before/after', () => {
+        const after = signature();
+        after.blocks = after.blocks.map((block, i) => (i === 2 ? { ...block, text: 'Get access' } : block));
+        const { diffs, drifted } = compareBaselines(baseline({ '/': signature() }), baseline({ '/': after }));
+        expect(drifted).toBe(1);
+        expect(diffs[0].blocks).toEqual([
+            { kind: 'text-changed', index: 2, tag: 'p', before: 'Get early access', after: 'Get access' },
+        ]);
+    });
+    it('reports one block-added without cascading through LCS', () => {
+        const after = signature();
+        after.blocks = [after.blocks[0], { tag: 'p', text: 'Injected', marks: [] }, ...after.blocks.slice(1)];
+        const { diffs } = compareBaselines(baseline({ '/': signature() }), baseline({ '/': after }));
+        expect(diffs[0].blocks).toEqual([{ kind: 'block-added', index: 1, tag: 'p', after: 'Injected' }]);
+    });
+    it('reports lost marks even when text is unchanged', () => {
+        const after = signature();
+        after.blocks = after.blocks.map((block, i) => (i === 1 ? { ...block, marks: [] } : block));
+        const { diffs } = compareBaselines(baseline({ '/': signature() }), baseline({ '/': after }));
+        expect(diffs[0].blocks[0]).toMatchObject({ kind: 'marks-changed', index: 1 });
+        expect(formatRouteDiff(diffs[0])[0]).toContain('marks changed at block 1');
+    });
+    it('reports status change and media change', () => {
+        const after = signature({ status: 500, images: ['/images/other.png'] });
+        const { diffs } = compareBaselines(baseline({ '/': signature() }), baseline({ '/': after }));
+        expect(diffs[0].statusChange).toEqual({ before: 200, after: 500 });
+        expect(diffs[0].images[0]).toMatchObject({ kind: 'changed', before: '/images/hero.png' });
+    });
+    it('treats rehosted media as an informational note, not drift', () => {
+        const after = signature({ images: ['https://assets.fimo.ai/uploads/hero-abc123.png'] });
+        const { diffs, drifted } = compareBaselines(baseline({ '/': signature() }), baseline({ '/': after }));
+        expect(drifted).toBe(0);
+        expect(diffs[0].notes[0]).toContain('media rehosted');
+    });
+    it('counts skipped routes as unverified', () => {
+        const base = baseline({ '/': signature() });
+        base.routes['/blog/:slug'] = { skipped: 'dynamic-params' };
+        const current = baseline({ '/': signature() });
+        current.routes['/blog/:slug'] = { skipped: 'dynamic-params' };
+        const result = compareBaselines(base, current);
+        expect(result).toMatchObject({ clean: 1, unverified: 1 });
+    });
+    it('reports link href changes', () => {
+        const after = signature({ links: [{ href: '/wp.pdf', text: 'PDF' }] });
+        const { diffs } = compareBaselines(baseline({ '/': signature() }), baseline({ '/': after }));
+        expect(diffs[0].links[0]).toMatchObject({ kind: 'changed', before: '/whitepaper.pdf', after: '/wp.pdf' });
+    });
+    it('treats by-design dynamic text as equal when both sides match a parityIgnore pattern', () => {
+        const clockBefore = signature({ blocks: [{ tag: 'div', text: '4:50:25 PM CET', marks: [] }] });
+        const clockAfter = signature({ blocks: [{ tag: 'div', text: '5:04:30 PM CET', marks: [] }] });
+        const pattern = String.raw `\d{1,2}:\d{2}:\d{2} [AP]M [A-Z]+`;
+        const without = compareBaselines(baseline({ '/': clockBefore }), baseline({ '/': clockAfter }));
+        expect(without.drifted).toBe(1);
+        const withIgnore = compareBaselines(baseline({ '/': clockBefore }), baseline({ '/': clockAfter }), {
+            ignoreTextPatterns: [pattern],
+        });
+        expect(withIgnore).toMatchObject({ drifted: 0, clean: 1 });
+        // A REAL edit does not hide behind the pattern: only one side matches.
+        const edited = signature({ blocks: [{ tag: 'div', text: 'Totally different copy', marks: [] }] });
+        const realDrift = compareBaselines(baseline({ '/': clockBefore }), baseline({ '/': edited }), {
+            ignoreTextPatterns: [pattern],
+        });
+        expect(realDrift.drifted).toBe(1);
+    });
+    it('ignores invalid parityIgnore regexes instead of crashing', () => {
+        const result = compareBaselines(baseline({ '/': signature() }), baseline({ '/': signature() }), {
+            ignoreTextPatterns: ['[unclosed'],
+        });
+        expect(result.clean).toBe(1);
+    });
+});

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;