fimo 0.6.0 → 0.7.0-experimental.10

package/dist/scripts/apply-wrap-templates.test.js

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { applyTemplateWrap } from './apply-wrap-templates.js';
+import { astroTemplateWrapStyle } from './frameworks/astro/template-style.js';
+import { nuxtTemplateWrapStyle } from './frameworks/nuxt/template-style.js';
+import { svelteTemplateWrapStyle } from './frameworks/sveltekit/template-style.js';
+import { scanWrappable } from './scan-wrappable.js';
+let dir;
+const project = (files) => {
+    dir = mkdtempSync(join(tmpdir(), 'apply-wrap-templates-'));
+    for (const [rel, content] of Object.entries(files)) {
+        const full = join(dir, rel);
+        mkdirSync(join(full, '..'), { recursive: true });
+        writeFileSync(full, content);
+    }
+    return dir;
+};
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('applyTemplateWrap — astro', () => {
+    it('wraps plain text nodes and injects the head into an existing fence', () => {
+        const root = project({
+            'src/pages/index.astro': `---
+const year = 2026;
+---
+<html><body>
+<main>
+  <h1>Welcome to the harbor</h1>
+  <p>
+    Ship your docs
+    without the busywork.
+  </p>
+  <footer>&copy; 2026 Harbor</footer>
+</main>
+</body></html>
+`,
+        });
+        const result = applyTemplateWrap(root, { style: astroTemplateWrapStyle });
+        const code = readFileSync(join(root, 'src/pages/index.astro'), 'utf8');
+        expect(result.applied.length).toBe(3);
+        expect(code).toContain('import { loadFimoT } from "fimo/astro/server";');
+        expect(code.indexOf('loadFimoT')).toBeGreaterThan(code.indexOf('---'));
+        expect(code).toContain('<h1>{t("index.welcome-to-the-harbor", "Welcome to the harbor")}</h1>');
+        // Multiline text collapses into the fallback, whitespace outside the wrap survives.
+        expect(code).toContain('{t("index.ship-your-docs-without", "Ship your docs without the busywork.")}');
+        // Label VALUE decodes entities; the inline fallback keeps the source form.
+        expect(code).toContain('"&copy; 2026 Harbor")}');
+        expect(result.labels['index.copy-2026-harbor']).toBe('© 2026 Harbor');
+        // The injected form counts as wrapped on re-scan: nothing left, keys visible.
+        const rescan = scanWrappable(root);
+        expect(rescan.items.filter((item) => item.kind === 'text')).toEqual([]);
+        expect(rescan.wrappedIds.labels).toContain('index.welcome-to-the-harbor');
+    });
+    it('creates a frontmatter fence when the file has none', () => {
+        const root = project({
+            'src/pages/plain.astro': `<main><p>Just some copy here</p></main>
+`,
+        });
+        applyTemplateWrap(root, { style: astroTemplateWrapStyle });
+        const code = readFileSync(join(root, 'src/pages/plain.astro'), 'utf8');
+        expect(code.startsWith('---\nimport { loadFimoT }')).toBe(true);
+        expect(code).toContain('{t("plain.just-some-copy-here", "Just some copy here")}');
+    });
+    it('leaves files that bind their own t() to the agent', () => {
+        const source = `---
+import { useTranslations } from "../i18n";
+const t = useTranslations("en");
+---
+<main><p>Localized copy already</p></main>
+`;
+        const root = project({ 'src/pages/i18n.astro': source });
+        const result = applyTemplateWrap(root, { style: astroTemplateWrapStyle });
+        expect(result.applied).toEqual([]);
+        expect(result.skipped.some((skip) => skip.reason.includes('binds its own t()'))).toBe(true);
+        expect(readFileSync(join(root, 'src/pages/i18n.astro'), 'utf8')).toBe(source);
+    });
+    it('allocates collision-safe keys for repeated copy', () => {
+        const root = project({
+            'src/pages/dup.astro': `---
+---
+<ul><li>Learn more</li><li>Learn more</li></ul>
+`,
+        });
+        const result = applyTemplateWrap(root, { style: astroTemplateWrapStyle });
+        expect(Object.keys(result.labels).sort()).toEqual(['dup.learn-more', 'dup.learn-more-2']);
+    });
+});
+describe('applyTemplateWrap — nuxt', () => {
+    it('wraps with mustache t() and injects into script setup', () => {
+        const root = project({
+            'pages/about.vue': `<script setup>
+const links = [];
+</script>
+
+<template>
+  <main>
+    <h1>About the crew</h1>
+    <p v-if="links.length > 0">We keep the harbor running</p>
+  </main>
+</template>
+`,
+        });
+        const result = applyTemplateWrap(root, { style: nuxtTemplateWrapStyle });
+        const code = readFileSync(join(root, 'pages/about.vue'), 'utf8');
+        expect(result.applied.length).toBe(2);
+        expect(code).toContain("import { useFimoT } from 'fimo/nuxt'");
+        expect(code.indexOf('useFimoT')).toBeLessThan(code.indexOf('const links'));
+        expect(code).toContain('<h1>{{ t("about.about-the-crew", "About the crew") }}</h1>');
+        // The quoted `>` inside v-if must not truncate the tag match.
+        expect(code).toContain('{{ t("about.we-keep-the-harbor", "We keep the harbor running") }}');
+        const rescan = scanWrappable(root);
+        expect(rescan.items.filter((item) => item.kind === 'text')).toEqual([]);
+    });
+    it('skips options-API files (no safe wiring point)', () => {
+        const source = `<script>
+export default { name: 'Legacy' };
+</script>
+
+<template>
+  <p>Legacy component copy</p>
+</template>
+`;
+        const root = project({ 'pages/legacy.vue': source });
+        const result = applyTemplateWrap(root, { style: nuxtTemplateWrapStyle });
+        expect(result.applied).toEqual([]);
+        expect(result.skipped.some((skip) => skip.reason.includes('no safe wiring point'))).toBe(true);
+        expect(readFileSync(join(root, 'pages/legacy.vue'), 'utf8')).toBe(source);
+    });
+    it('creates a script setup block when the file is template-only', () => {
+        const root = project({
+            'pages/bare.vue': `<template>
+  <p>Bare template copy</p>
+</template>
+`,
+        });
+        applyTemplateWrap(root, { style: nuxtTemplateWrapStyle });
+        const code = readFileSync(join(root, 'pages/bare.vue'), 'utf8');
+        expect(code.startsWith('<script setup>')).toBe(true);
+        expect(code).toContain('{{ t("bare.bare-template-copy", "Bare template copy") }}');
+    });
+});
+describe('applyTemplateWrap — sveltekit', () => {
+    it('wraps text, injects into the INSTANCE script, scopes by route dir, wires the layout', () => {
+        const root = project({
+            'src/routes/pricing/+page.svelte': `<script lang="ts" module>
+export const prerender = true;
+</script>
+
+<script lang="ts">
+let count = 0;
+</script>
+
+<main>
+  <h1>Simple pricing</h1>
+</main>
+`,
+        });
+        const result = applyTemplateWrap(root, { style: svelteTemplateWrapStyle });
+        const code = readFileSync(join(root, 'src/routes/pricing/+page.svelte'), 'utf8');
+        expect(code).toContain('{t("pricing.simple-pricing", "Simple pricing")}');
+        // Head goes in the instance script, never the module script.
+        const moduleBlock = code.slice(code.indexOf('<script lang="ts" module>'), code.indexOf('</script>'));
+        expect(moduleBlock).not.toContain('makeFimoT');
+        expect(code.indexOf('makeFimoT')).toBeGreaterThan(code.indexOf('<script lang="ts">'));
+        expect(code).toContain('const t = makeFimoT($page.data.fimoLabels);');
+        // One-time wiring: the root layout labels loader is written once.
+        expect(result.filesChanged).toContain('src/routes/+layout.server.js');
+        const layout = readFileSync(join(root, 'src/routes/+layout.server.js'), 'utf8');
+        expect(layout).toContain("loadFimoLabels } from 'fimo/svelte/server'");
+        expect(layout).toContain('fimoLabels: labels.dictionaries[labels.defaultLocale]');
+    });
+    it('never overwrites an existing +layout.server file', () => {
+        const existing = `export const load = () => ({ session: null });\n`;
+        const root = project({
+            'src/routes/+layout.server.ts': existing,
+            'src/routes/+page.svelte': `<h1>Front page headline</h1>\n`,
+        });
+        const result = applyTemplateWrap(root, { style: svelteTemplateWrapStyle });
+        expect(result.applied.length).toBe(1);
+        expect(result.labels['home.front-page-headline']).toBe('Front page headline');
+        expect(result.filesChanged).not.toContain('src/routes/+layout.server.js');
+        expect(existsSync(join(root, 'src/routes/+layout.server.js'))).toBe(false);
+        expect(readFileSync(join(root, 'src/routes/+layout.server.ts'), 'utf8')).toBe(existing);
+    });
+    it('scopes component files by their own name', () => {
+        const root = project({
+            'src/lib/Footer.svelte': `<footer><p>Made with care at the docks</p></footer>\n`,
+            'src/routes/+page.svelte': `<h1>Hello sailor</h1>\n`,
+        });
+        const result = applyTemplateWrap(root, { style: svelteTemplateWrapStyle });
+        expect(result.labels['footer.made-with-care-at']).toBe('Made with care at the docks');
+        expect(result.labels['home.hello-sailor']).toBe('Hello sailor');
+    });
+});

package/dist/scripts/apply-wrap.d.ts

@@ -0,0 +1,46 @@
+import { type WrappableItem } from './scan-wrappable.js';
+export interface AppliedTransform {
+    kind: 'text' | 'image' | 'file-link';
+    file: string;
+    line: number;
+    id: string;
+    preview: string;
+}
+export interface ApplyWrapResult {
+    applied: AppliedTransform[];
+    skipped: Array<{
+        item: WrappableItem;
+        reason: string;
+    }>;
+    labels: Record<string, string>;
+    filesChanged: string[];
+}
+export declare function decodeJsxEntities(text: string): string;
+/** Deterministic scope from the file path: app/about/page.tsx -> about. */
+export declare function keyScope(file: string): string;
+export declare function slugify(text: string): string;
+export declare class KeyAllocator {
+    private readonly used;
+    constructor(existing: Iterable<string>);
+    allocate(scope: string, slug: string): string;
+}
+/**
+ * Merge the fimo/next import with an existing one, or insert a new one AFTER
+ * the last import statement — positioned via the AST, never line matching
+ * (a multiline `import {\n …` opening line is not the end of the imports,
+ * as a real portfolio migration proved).
+ */
+export declare function ensureFimoImport(code: string, specifiers: string[], importModule?: string): string;
+export declare function applyWrapToFile(code: string, items: WrappableItem[], allocator: KeyAllocator, importModule?: string): {
+    code: string;
+    applied: AppliedTransform[];
+    skipped: Array<{
+        item: WrappableItem;
+        reason: string;
+    }>;
+    labels: Record<string, string>;
+};
+export declare function applyWrap(rootDir: string, opts?: {
+    excludePrefixes?: string[];
+    importModule?: string;
+}): ApplyWrapResult;

package/dist/scripts/apply-wrap.js

@@ -0,0 +1,278 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseSync } from 'oxc-parser';
+import { scanWrappable } from './scan-wrappable.js';
+/**
+ * The --apply codemod: performs the PROVABLY-SAFE wrap transforms
+ * deterministically, leaving every judgment call to the agent.
+ *
+ * In scope:  plain JSX text -> FimoText, <img src="literal"> -> FimoMediaImage,
+ *            <a href="/file.pdf"> -> FimoFileLink.
+ * Out of scope (agent work): attributes (useLabels crosses the RSC boundary),
+ *            formatted text (marks -> FimoRichTextBlock), next/image <Image>
+ *            (framework-specific props), collections, layout wiring.
+ *
+ * Correctness is enforced by the gates, not assumed: the render-parity
+ * baseline is captured BEFORE applying, and `fimo migrate wrap --check`
+ * verifies the result like any other actor's work.
+ */
+/** Elements whose children cannot contain a <span> wrapper. */
+const NO_ELEMENT_CHILDREN = new Set(['option', 'title', 'textarea', 'script', 'style', 'select']);
+function collapse(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+// JSX text carries HTML entities (&apos;, &amp;, …). The FALLBACK keeps the
+// original source form, but the label VALUE is rendered literally by
+// FimoText — seeding the raw entity re-escapes it on screen (the remix
+// dogfood shipped "What&apos;s next?"). Decode when generating values.
+const JSX_ENTITIES = {
+    '&amp;': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+    '&nbsp;': ' ',
+    '&copy;': '©',
+};
+export function decodeJsxEntities(text) {
+    return text
+        .replace(/&(amp|lt|gt|quot|apos|nbsp|copy);/g, (entity) => JSX_ENTITIES[entity] ?? entity)
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)));
+}
+/** Deterministic scope from the file path: app/about/page.tsx -> about. */
+export function keyScope(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const appMatch = normalized.match(/(?:^|\/)app\/(.*)\/?page\.[jt]sx?$/);
+    if (appMatch) {
+        const dir = appMatch[1].replace(/\/$/, '');
+        if (!dir) {
+            return 'home';
+        }
+        const segments = dir
+            .split('/')
+            .filter((segment) => !segment.startsWith('(') && !segment.startsWith('@'))
+            .map((segment) => segment.replace(/^\[+|\]+$/g, '').replace(/^\.\.\./, ''));
+        return segments.join('.') || 'home';
+    }
+    if (/(?:^|\/)app\/layout\.[jt]sx?$/.test(normalized)) {
+        return 'layout';
+    }
+    const stem = basename(normalized).replace(/\.[jt]sx?$/, '');
+    return slugify(stem) || 'shared';
+}
+export function slugify(text) {
+    return collapse(text)
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .split('-')
+        .slice(0, 4)
+        .join('-');
+}
+export class KeyAllocator {
+    used = new Set();
+    constructor(existing) {
+        for (const key of existing) {
+            this.used.add(key);
+        }
+    }
+    allocate(scope, slug) {
+        const base = `${scope}.${slug || 'item'}`;
+        let candidate = base;
+        let counter = 2;
+        while (this.used.has(candidate)) {
+            candidate = `${base}-${counter++}`;
+        }
+        this.used.add(candidate);
+        return candidate;
+    }
+}
+/**
+ * Merge the fimo/next import with an existing one, or insert a new one AFTER
+ * the last import statement — positioned via the AST, never line matching
+ * (a multiline `import {\n …` opening line is not the end of the imports,
+ * as a real portfolio migration proved).
+ */
+export function ensureFimoImport(code, specifiers, importModule = 'fimo/next') {
+    if (specifiers.length === 0) {
+        return code;
+    }
+    const moduleRe = importModule.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+    const importMatch = code.match(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*(['\"])${moduleRe}\\2\\s*;?`));
+    if (importMatch) {
+        const existing = importMatch[1]
+            .split(',')
+            .map((token) => token.trim())
+            .filter(Boolean);
+        const merged = [...new Set([...existing, ...specifiers])].sort();
+        return code.replace(importMatch[0], `import { ${merged.join(', ')} } from "${importModule}";`);
+    }
+    const statement = `import { ${[...new Set(specifiers)].sort().join(', ')} } from "${importModule}";`;
+    let insertAt = 0;
+    try {
+        const program = parseSync('module.tsx', code).program;
+        for (const node of program.body ?? []) {
+            if (node.type === 'ImportDeclaration') {
+                insertAt = node.end;
+            }
+        }
+    }
+    catch {
+        insertAt = 0;
+    }
+    if (insertAt === 0) {
+        return `${statement}\n${code}`;
+    }
+    return `${code.slice(0, insertAt)}\n${statement}${code.slice(insertAt)}`;
+}
+export function applyWrapToFile(code, items, allocator, importModule = 'fimo/next') {
+    const applied = [];
+    const skipped = [];
+    const labels = {};
+    const edits = [];
+    const specifiers = new Set();
+    for (const item of items) {
+        const span = item.span;
+        if (!span) {
+            skipped.push({ item, reason: 'no span info' });
+            continue;
+        }
+        const scope = keyScope(item.file);
+        if (item.kind === 'text') {
+            if (span.parentTag && NO_ELEMENT_CHILDREN.has(span.parentTag.toLowerCase())) {
+                skipped.push({ item, reason: `<${span.parentTag}> cannot contain a wrapper element` });
+                continue;
+            }
+            const raw = code.slice(span.start, span.end);
+            const core = raw.trim();
+            if (!core) {
+                skipped.push({ item, reason: 'whitespace only' });
+                continue;
+            }
+            const lead = raw.slice(0, raw.indexOf(core));
+            const trail = raw.slice(raw.indexOf(core) + core.length);
+            const id = allocator.allocate(scope, slugify(core));
+            edits.push({
+                start: span.start,
+                end: span.end,
+                replacement: `${lead}<FimoText id="${id}">${core}</FimoText>${trail}`,
+            });
+            specifiers.add('FimoText');
+            labels[id] = decodeJsxEntities(collapse(core));
+            applied.push({ kind: 'text', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        if (item.kind === 'image') {
+            if (span.openNameStart === undefined ||
+                span.openNameEnd === undefined ||
+                code.slice(span.openNameStart, span.openNameEnd) !== 'img') {
+                skipped.push({ item, reason: 'next/image and custom components stay agent work' });
+                continue;
+            }
+            const id = allocator.allocate(scope, slugify(basename(item.preview).replace(/\.[a-z0-9]+$/i, '')));
+            edits.push({
+                start: span.openNameStart,
+                end: span.openNameEnd,
+                replacement: `FimoMediaImage id="${id}"`,
+            });
+            specifiers.add('FimoMediaImage');
+            applied.push({ kind: 'image', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        if (item.kind === 'file-link') {
+            if (span.openNameStart === undefined ||
+                span.openNameEnd === undefined ||
+                span.closeNameStart === undefined ||
+                span.closeNameEnd === undefined) {
+                skipped.push({ item, reason: 'self-closing or unparsable anchor' });
+                continue;
+            }
+            const id = allocator.allocate(scope, slugify(basename(item.preview).replace(/\.[a-z0-9]+$/i, '')));
+            edits.push({ start: span.openNameStart, end: span.openNameEnd, replacement: `FimoFileLink id="${id}"` });
+            edits.push({ start: span.closeNameStart, end: span.closeNameEnd, replacement: 'FimoFileLink' });
+            specifiers.add('FimoFileLink');
+            applied.push({ kind: 'file-link', file: item.file, line: item.line, id, preview: item.preview });
+            continue;
+        }
+        skipped.push({ item, reason: `${item.kind} stays agent work` });
+    }
+    let next = code;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) {
+        next = next.slice(0, edit.start) + edit.replacement + next.slice(edit.end);
+    }
+    next = ensureFimoImport(next, [...specifiers], importModule);
+    return { code: next, applied, skipped, labels };
+}
+/**
+ * Apply the safe transforms across the project. Mutates source files and
+ * merges generated labels into `.fimo/migration/labels.json` (never
+ * overwriting existing keys).
+ */
+/** Recorded coverage exemptions the codemod must NOT wrap — items the user
+ *  deliberately kept out (dev-only UI, OG-image markup, …). Matched by the
+ *  same (file, kind, preview) triple the coverage gate uses, so "record the
+ *  exemption first, then --apply auto-wraps the rest" holds. */
+function readApplyExemptions(rootDir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'manifest.json'), 'utf8'));
+        const raw = manifest?.wrap?.exemptions;
+        return Array.isArray(raw)
+            ? raw.filter((entry) => typeof entry?.file === 'string' &&
+                typeof entry?.kind === 'string' &&
+                typeof entry?.preview === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function applyWrap(rootDir, opts = {}) {
+    const scan = scanWrappable(rootDir, { excludePrefixes: opts.excludePrefixes });
+    const existingLabels = (() => {
+        try {
+            return JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'labels.json'), 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    })();
+    // Honor recorded exemptions: the codemod skips them so the coverage gate's
+    // exemption and the codemod stay consistent — otherwise --apply would wrap
+    // an item the user just exempted and the gate would flag the drift.
+    const exemptions = readApplyExemptions(rootDir);
+    const isExempt = (item) => exemptions.some((exemption) => exemption.file === item.file && exemption.kind === item.kind && exemption.preview === item.preview);
+    const allocator = new KeyAllocator([...Object.keys(existingLabels), ...scan.wrappedIds.labels]);
+    const byFile = new Map();
+    for (const item of scan.items) {
+        if (isExempt(item)) {
+            continue;
+        }
+        const list = byFile.get(item.file) ?? [];
+        list.push(item);
+        byFile.set(item.file, list);
+    }
+    const result = { applied: [], skipped: [], labels: {}, filesChanged: [] };
+    for (const [file, items] of byFile) {
+        const filePath = join(rootDir, file);
+        let code;
+        try {
+            code = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            result.skipped.push(...items.map((item) => ({ item, reason: 'unreadable file' })));
+            continue;
+        }
+        const fileResult = applyWrapToFile(code, items, allocator, opts.importModule ?? 'fimo/next');
+        result.applied.push(...fileResult.applied);
+        result.skipped.push(...fileResult.skipped);
+        Object.assign(result.labels, fileResult.labels);
+        if (fileResult.applied.length > 0) {
+            writeFileSync(filePath, fileResult.code);
+            result.filesChanged.push(file);
+        }
+    }
+    return result;
+}

package/dist/scripts/apply-wrap.test.d.ts

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