fimo 0.3.1 → 0.3.2-experimental.1783354419249

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

@@ -0,0 +1,102 @@
+import { 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, findFreePort } 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>boom</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');
+`;
+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);
+    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('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('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('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);
+});

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

@@ -0,0 +1,44 @@
+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 declare function compareBaselines(baseline: ParityBaseline, current: ParityBaseline): 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,75 @@
+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' });
+    });
+});

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;

package/dist/scripts/render-parity/normalize-html.js

@@ -0,0 +1,208 @@
+import * as cheerio from 'cheerio';
+const REMOVED_TAGS = new Set(['script', 'style', 'noscript', 'template', 'link', 'meta', 'svg', 'iframe', 'head']);
+const BLOCK_TAGS = new Set([
+    'p',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'li',
+    'td',
+    'th',
+    'dt',
+    'dd',
+    'blockquote',
+    'figcaption',
+    'pre',
+    'button',
+    'label',
+    'summary',
+    'caption',
+    'option',
+]);
+const FALLBACK_BLOCK_TAGS = new Set(['div', 'section', 'article', 'main', 'aside', 'header', 'footer', 'nav', 'body']);
+const MARK_KIND = {
+    strong: 'strong',
+    b: 'strong',
+    em: 'em',
+    i: 'em',
+    u: 'u',
+    s: 's',
+    del: 's',
+    strike: 's',
+    code: 'code',
+    a: 'a',
+};
+function collapse(text) {
+    return text.replace(/ /g, ' ').replace(/\s+/g, ' ').trim();
+}
+/** Strip the capture origin so differing ports between runs compare equal. */
+export function normalizeHref(href, origin) {
+    if (href.startsWith(origin)) {
+        const stripped = href.slice(origin.length);
+        return stripped.startsWith('/') ? stripped : `/${stripped}`;
+    }
+    return href;
+}
+/**
+ * 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 function normalizeMediaSrc(src, origin) {
+    let value = normalizeHref(src, origin);
+    const optimizerMatch = value.match(/^\/_next\/image\?(.+)$/);
+    if (optimizerMatch) {
+        const params = new URLSearchParams(optimizerMatch[1]);
+        const url = params.get('url');
+        if (url) {
+            value = url;
+        }
+    }
+    return value;
+}
+function isExcluded(node) {
+    const tag = node.name?.toLowerCase() ?? '';
+    if (REMOVED_TAGS.has(tag)) {
+        return true;
+    }
+    // Hidden elements are not visible content — except Next streaming
+    // containers (div[hidden][id^="S:"]), whose content replaces Suspense
+    // holes; kept in document order so streamed content is captured
+    // symmetrically between baseline and check.
+    if (node.attribs && 'hidden' in node.attribs) {
+        const isStreamingContainer = tag === 'div' && (node.attribs.id ?? '').startsWith('S:');
+        if (!isStreamingContainer) {
+            return true;
+        }
+    }
+    return false;
+}
+function nearestBlock(node) {
+    let current = node.parent;
+    let fallback = null;
+    while (current) {
+        const tag = current.name?.toLowerCase();
+        if (tag && BLOCK_TAGS.has(tag)) {
+            return current;
+        }
+        if (!fallback && tag && FALLBACK_BLOCK_TAGS.has(tag)) {
+            fallback = current;
+        }
+        current = current.parent;
+    }
+    return fallback;
+}
+function collectText(node) {
+    if (node.type === 'text') {
+        return String(node.data ?? '');
+    }
+    if (node.type !== 'tag' || isExcluded(node)) {
+        return '';
+    }
+    return (node.children ?? []).map(collectText).join('');
+}
+export function extractRouteSignature(html, opts) {
+    const $ = cheerio.load(html);
+    const bodyNode = $('body').get(0);
+    const blocks = [];
+    const blockIndex = new Map();
+    const images = [];
+    const videos = [];
+    const links = [];
+    const visit = (node) => {
+        if (node.type === 'text') {
+            const text = collapse(String(node.data ?? ''));
+            if (!text) {
+                return;
+            }
+            const block = nearestBlock(node);
+            if (!block) {
+                return;
+            }
+            const existing = blockIndex.get(block);
+            if (existing === undefined) {
+                blockIndex.set(block, blocks.length);
+                blocks.push({ tag: block.name?.toLowerCase() ?? 'div', text, marks: [] });
+            }
+            else {
+                blocks[existing].text = collapse(`${blocks[existing].text} ${text}`);
+            }
+            return;
+        }
+        if (node.type !== 'tag' && node.type !== 'root') {
+            return;
+        }
+        if (node.type === 'tag' && isExcluded(node)) {
+            return;
+        }
+        const tag = node.name?.toLowerCase() ?? '';
+        const attribs = node.attribs ?? {};
+        // Inline-marks signature: the formatting that must survive wrapping and
+        // the TipTap seed round-trip. Attached to the nearest block.
+        const markKind = MARK_KIND[tag];
+        if (markKind) {
+            const text = collapse(collectText(node));
+            if (text) {
+                const block = nearestBlock(node);
+                if (block) {
+                    if (!blockIndex.has(block)) {
+                        blockIndex.set(block, blocks.length);
+                        blocks.push({ tag: block.name?.toLowerCase() ?? 'div', text: '', marks: [] });
+                    }
+                    const mark = { kind: markKind, text };
+                    if (markKind === 'a') {
+                        if (attribs.href) {
+                            mark.href = normalizeHref(attribs.href, opts.origin);
+                            blocks[blockIndex.get(block)].marks.push(mark);
+                        }
+                    }
+                    else {
+                        blocks[blockIndex.get(block)].marks.push(mark);
+                    }
+                }
+            }
+        }
+        if (tag === 'img' && attribs.src) {
+            images.push(normalizeMediaSrc(attribs.src, opts.origin));
+        }
+        if (tag === 'source' && attribs.src) {
+            const parentTag = node.parent?.name?.toLowerCase();
+            if (parentTag === 'picture') {
+                images.push(normalizeMediaSrc(attribs.src, opts.origin));
+            }
+            else if (parentTag === 'video') {
+                videos.push(normalizeMediaSrc(attribs.src, opts.origin));
+            }
+        }
+        if (tag === 'video') {
+            if (attribs.src) {
+                videos.push(normalizeMediaSrc(attribs.src, opts.origin));
+            }
+            if (attribs.poster) {
+                videos.push(normalizeMediaSrc(attribs.poster, opts.origin));
+            }
+        }
+        if (tag === 'a' && attribs.href) {
+            links.push({ href: normalizeHref(attribs.href, opts.origin), text: collapse(collectText(node)) });
+        }
+        for (const child of node.children ?? []) {
+            visit(child);
+        }
+    };
+    if (bodyNode) {
+        for (const child of bodyNode.children ?? []) {
+            visit(child);
+        }
+    }
+    // Blocks created empty by a mark preceding any direct text (e.g. a <p>
+    // starting with <strong>) get their text from the block's full content.
+    for (const [block, index] of blockIndex) {
+        if (!blocks[index].text) {
+            blocks[index].text = collapse(collectText(block));
+        }
+    }
+    return { status: opts.status, blocks: blocks.filter((block) => block.text.length > 0), images, videos, links };
+}

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

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

package/dist/scripts/render-parity/normalize-html.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { extractRouteSignature, normalizeMediaSrc } from './normalize-html.js';
+const ORIGIN = 'http://localhost:3999';
+const extract = (body, status = 200) => extractRouteSignature(`<!doctype html><html><head><title>x</title></head><body>${body}</body></html>`, {
+    origin: ORIGIN,
+    status,
+});
+describe('extractRouteSignature', () => {
+    it('is invariant to Fimo wrapper spans and attribute churn', () => {
+        const before = extract('<main><h1>Ship faster</h1><p>Analytics for humans</p></main>');
+        const after = extract('<main class="x"><h1 data-y="1"><span data-fimo-source="__labels.en.home.hero.title.value">Ship faster</span></h1><p><span data-fimo-source="z">Analytics for humans</span></p></main>');
+        expect(after.blocks).toEqual(before.blocks);
+    });
+    it('captures inline marks with hrefs and fails on their loss', () => {
+        const withMarks = extract('<p>Read <strong>honest numbers</strong> and <a href="/docs">the docs</a>.</p>');
+        expect(withMarks.blocks[0].marks).toEqual([
+            { kind: 'strong', text: 'honest numbers' },
+            { kind: 'a', text: 'the docs', href: '/docs' },
+        ]);
+        const lostBold = extract('<p>Read honest numbers and <a href="/docs">the docs</a>.</p>');
+        expect(lostBold.blocks[0].marks).toHaveLength(1);
+        expect(withMarks.blocks[0].text).toBe(lostBold.blocks[0].text);
+    });
+    it('drops scripts (RSC flight payload), styles, and hidden elements but keeps streaming containers', () => {
+        const sig = extract('<p>Visible</p><script>self.__next_f.push([1,"Hidden payload text"])</script><style>.x{}</style><div hidden>gone</div><div hidden id="S:0"><p>Streamed</p></div>');
+        expect(sig.blocks.map((b) => b.text)).toEqual(['Visible', 'Streamed']);
+    });
+    it('collapses whitespace, decodes entities, merges runs per block', () => {
+        const sig = extract('<p>  Hello&nbsp;&amp;\n  <span>world</span>  </p>');
+        expect(sig.blocks).toEqual([{ tag: 'p', text: 'Hello & world', marks: [] }]);
+    });
+    it('extracts media with origin stripping and optimizer decoding', () => {
+        const sig = extract(`<img src="${ORIGIN}/_next/image?url=%2Fimages%2Fhero.png&w=640&q=75" /><video src="/demo.mp4" poster="/poster.jpg"></video>`);
+        expect(sig.images).toEqual(['/images/hero.png']);
+        expect(sig.videos).toEqual(['/demo.mp4', '/poster.jpg']);
+    });
+    it('extracts links with normalized hrefs', () => {
+        const sig = extract(`<p><a href="${ORIGIN}/pricing">Pricing</a> <a href="/whitepaper.pdf">PDF</a></p>`);
+        expect(sig.links).toEqual([
+            { href: '/pricing', text: 'Pricing' },
+            { href: '/whitepaper.pdf', text: 'PDF' },
+        ]);
+    });
+    it('attaches text to the nearest block through wrapper divs', () => {
+        const wrapped = extract('<div><p>Original</p></div>');
+        const withWrapper = extract('<div><div data-wrapper><p>Original</p></div></div>');
+        expect(withWrapper.blocks).toEqual(wrapped.blocks);
+    });
+    it('records status', () => {
+        expect(extract('<p>x</p>', 500).status).toBe(500);
+    });
+});
+describe('normalizeMediaSrc', () => {
+    it('keeps plain srcs and decodes optimizer urls', () => {
+        expect(normalizeMediaSrc('/a.png', ORIGIN)).toBe('/a.png');
+        expect(normalizeMediaSrc('/_next/image?url=%2Fb.png&w=64', ORIGIN)).toBe('/b.png');
+    });
+});

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

@@ -0,0 +1,41 @@
+export declare const PARITY_BASELINE_VERSION = 1;
+export interface InlineMark {
+    kind: 'strong' | 'em' | 'u' | 's' | 'code' | 'a';
+    text: string;
+    href?: string;
+}
+export interface TextBlock {
+    tag: string;
+    text: string;
+    marks: InlineMark[];
+}
+export interface RouteSignature {
+    status: number;
+    blocks: TextBlock[];
+    images: string[];
+    videos: string[];
+    links: Array<{
+        href: string;
+        text: string;
+    }>;
+}
+export type RouteCapture = {
+    signature: RouteSignature;
+} | {
+    skipped: 'dynamic-params' | 'fetch-failed';
+    error?: string;
+};
+/**
+ * Normalized pre-wrap snapshot of every route's rendered content. Written to
+ * `.fimo/migration/parity-baseline.json`; `fimo migrate wrap --check`
+ * recaptures with the identical pipeline and compares.
+ */
+export interface ParityBaseline {
+    version: typeof PARITY_BASELINE_VERSION;
+    capturedAt: string;
+    engine: 'dev-server';
+    framework: string | null;
+    command: string;
+    unwrappedAtCapture?: number;
+    routes: Record<string, RouteCapture>;
+}

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

@@ -0,0 +1 @@
+export const PARITY_BASELINE_VERSION = 1;

package/dist/scripts/scan-wrappable.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Inverse of extract-translations: finds content that is NOT yet wrapped with
+ * Fimo primitives — hardcoded JSX text, image/video sources, file links, and
+ * user-visible attribute strings. Drives the wrap migration's coverage gate:
+ * every item must end wrapped, ignored-with-a-reason, or unresolved.
+ */
+export type WrappableKind = 'text' | 'image' | 'video' | 'file-link' | 'attribute';
+export interface WrappableItem {
+    kind: WrappableKind;
+    file: string;
+    line: number;
+    preview: string;
+}
+/** Identities of already-wrapped content, for the seeding gate. */
+export interface WrappedIds {
+    labels: string[];
+    media: string[];
+    richText: string[];
+    files: string[];
+}
+export interface WrapScanResult {
+    items: WrappableItem[];
+    wrappedCount: number;
+    filesScanned: number;
+    wrappedIds: WrappedIds;
+}
+export declare function scanWrappableFile(filePath: string, code: string, relPath: string): {
+    items: WrappableItem[];
+    wrapped: number;
+    wrappedIds: WrappedIds;
+};
+/**
+ * Scan a project's source directories for unwrapped content. `dirs` defaults
+ * to the common Next/React layouts that exist under `rootDir`.
+ */
+export declare function scanWrappable(rootDir: string, opts?: {
+    dirs?: string[];
+}): WrapScanResult;