fimo 0.7.0-experimental.1 → 0.7.0-experimental.10

package/dist/runtime/wrapped/server.test.js

@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { wrapCollection } from './server.js';
+const SOURCE = [
+    {
+        slug: 'post-1',
+        title: 'Charting the bay',
+        body: 'Prose one.\n\nProse two.',
+        cover: '/images/a.png',
+        featured: true,
+        tags: ['tides'],
+    },
+    {
+        slug: 'post-2',
+        title: 'Berth songs',
+        body: 'More prose.',
+        cover: '/images/b.png',
+        featured: false,
+        tags: ['harbor'],
+    },
+];
+function mockEntries(rows) {
+    return vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ data: rows.map((data, index) => ({ id: `row-${index}`, data })) }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+    }));
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('wrapCollection', () => {
+    it('overlays type-matched Fimo values and falls back per field on shape mismatches', async () => {
+        const spy = mockEntries([
+            {
+                slug: 'post-1',
+                title: 'Charting the bay TOGETHER', // string → replaces
+                body: { type: 'doc', content: [] }, // richtext doc → fallback
+                cover: { source: 'local', url: '/images/a.png', alt: '' }, // media envelope → fallback
+                featured: false, // boolean → replaces
+                tags: [{ documentId: 'x' }], // reference handles → fallback
+            },
+        ]);
+        const rows = await wrapCollection('Post', SOURCE, { apiUrl: 'http://tenant.test' });
+        expect(rows).toHaveLength(2);
+        expect(rows[0].title).toBe('Charting the bay TOGETHER');
+        expect(rows[0].body).toBe('Prose one.\n\nProse two.');
+        expect(rows[0].cover).toBe('/images/a.png');
+        expect(rows[0].featured).toBe(false);
+        expect(rows[0].tags).toEqual(['tides']);
+        // Row without a matching entry stays pure source.
+        expect(rows[1]).toEqual(SOURCE[1]);
+        const url = new URL(String(spy.mock.calls[0][0]));
+        expect(JSON.parse(url.searchParams.get('where') ?? '{}')).toEqual({ slug: { $in: ['post-1', 'post-2'] } });
+    });
+    it('returns the source rows untouched when the API has nothing', async () => {
+        mockEntries([]);
+        const rows = await wrapCollection('Post', SOURCE, { apiUrl: 'http://tenant.test' });
+        expect(rows).toEqual(SOURCE);
+    });
+    it('returns the source rows when no key field is detectable', async () => {
+        const spy = mockEntries([]);
+        const keyless = [{ n: 1 }, { n: 2 }];
+        const rows = await wrapCollection('Stat', keyless, { apiUrl: 'http://tenant.test' });
+        expect(rows).toEqual(keyless);
+        expect(spy).not.toHaveBeenCalled();
+    });
+});
+describe('loadFimoMessages', () => {
+    afterEach(() => vi.restoreAllMocks());
+    const mockLabels = (labels) => vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ data: { labels } }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+    }));
+    it('un-flattens the Fimo dictionary and deep-merges over the static fallback', async () => {
+        const { loadFimoMessages } = await import('./server.js');
+        mockLabels({ 'home.title': 'Bienvenue', 'cart.items': '{count, plural, one {# article} other {# articles}}' });
+        const fallback = { home: { title: 'FR fallback', cta: 'Commencer' }, nav: { about: 'À propos' } };
+        const messages = await loadFimoMessages('fr', { apiUrl: 'http://tenant.test', fallback });
+        // Edited key from Fimo wins; fallback-only keys survive; ICU stays opaque.
+        expect(messages).toEqual({
+            home: { title: 'Bienvenue', cta: 'Commencer' },
+            nav: { about: 'À propos' },
+            cart: { items: '{count, plural, one {# article} other {# articles}}' },
+        });
+    });
+    it('returns the fallback untouched when Fimo has no labels for the locale', async () => {
+        const { loadFimoMessages } = await import('./server.js');
+        mockLabels({});
+        const fallback = { home: { title: 'Static only' } };
+        expect(await loadFimoMessages('de', { apiUrl: 'http://tenant.test', fallback })).toEqual(fallback);
+    });
+});

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

@@ -0,0 +1,61 @@
+import { KeyAllocator, type ApplyWrapResult } from './apply-wrap.js';
+import { type WrappableItem } from './scan-wrappable.js';
+/**
+ * The template half of the --apply codemod: wraps plain TEMPLATE text nodes
+ * with the framework's t() form and injects the per-file wiring head once.
+ * Framework-neutral by contract — everything framework-specific arrives via
+ * a TemplateWrapStyle from the framework registry (frameworks/discover.ts).
+ *
+ * Grown out of the batch-dogfood plan-driven wrapper (392/392 items on a
+ * 201-route site); the lessons it encodes:
+ * - heads go in the INSTANCE script, never a `<script module>` block;
+ * - files that already bind a `t` identifier (i18n libraries, custom
+ *   helpers) are left whole for the agent — renaming foreign t() calls
+ *   broke a real site;
+ * - label VALUES decode HTML entities while the inline fallback keeps the
+ *   source form, so rendering never changes;
+ * - keys are collision-safe via the shared KeyAllocator.
+ *
+ * Anything that is not a plain text node (attributes, media, markup the
+ * preview matcher cannot anchor) stays in the plan for the agent — same
+ * philosophy as the JSX codemod: provably safe or hands off.
+ */
+export interface TemplateWrapStyle {
+    /** File extension this style owns, e.g. '.astro'. */
+    ext: string;
+    /** Wiring lines injected once per file (the t() head). */
+    head: string;
+    /** Marker proving our wiring (or an equivalent manual one) is present. */
+    headMarker: RegExp;
+    /** t() delimiters around `"key", "fallback"`. */
+    open: string;
+    close: string;
+    /**
+     * Insert the head into a file. Return null when the file has no safe
+     * injection point (e.g. an options-API script) — its items stay agent work.
+     */
+    injectHead: (code: string, head: string) => string | null;
+    /** Override the key scope for route-convention filenames (+page.svelte). */
+    fileScope?: (file: string) => string | null;
+    /** One-time project wiring once any file was wrapped. Returns files written. */
+    ensureWiring?: (rootDir: string) => string[];
+}
+/**
+ * Shared injection helper for SFC-style templates: first instance script,
+ * never a `<script module>` block (module scope cannot read page data), or a
+ * fresh script when the file has none.
+ */
+export declare function injectIntoInstanceScript(code: string, head: string, scriptTag: string): string;
+export declare function applyTemplateWrapToFile(code: string, style: TemplateWrapStyle, items: WrappableItem[], allocator: KeyAllocator): {
+    code: string;
+} & Omit<ApplyWrapResult, 'filesChanged'>;
+/**
+ * Apply the template wraps across a project — same contract as applyWrap:
+ * scans, mutates source files, returns the generated labels for staging and
+ * seeding. The style's ensureWiring hook then writes any one-time project
+ * wiring (e.g. a root layout labels loader) when files were wrapped.
+ */
+export declare function applyTemplateWrap(rootDir: string, opts: {
+    style: TemplateWrapStyle;
+    excludePrefixes?: string[];
+}): ApplyWrapResult;

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

@@ -0,0 +1,132 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { decodeJsxEntities, KeyAllocator, slugify } from './apply-wrap.js';
+import { scanWrappable } from './scan-wrappable.js';
+/**
+ * Shared injection helper for SFC-style templates: first instance script,
+ * never a `<script module>` block (module scope cannot read page data), or a
+ * fresh script when the file has none.
+ */
+export function injectIntoInstanceScript(code, head, scriptTag) {
+    const instance = code.match(/<script(?![^>]*\bmodule\b)[^>]*>\r?\n?/);
+    if (instance && instance.index !== undefined) {
+        const at = instance.index + instance[0].length;
+        return `${code.slice(0, at)}\t${head}\n${code.slice(at)}`;
+    }
+    return `${scriptTag}\n\t${head}\n</script>\n\n${code}`;
+}
+/**
+ * A file that already binds `t` (an i18n library, a custom helper) is agent
+ * work: the dogfood proved rewiring foreign t() calls breaks rendering.
+ */
+function bindsForeignT(code) {
+    return (/\buseI18n\s*\(/.test(code) ||
+        /(?:const|let|var)\s+t\s*=/.test(code) ||
+        /import\s*\{[^}]*\bt\b[^}]*\}\s*from/.test(code));
+}
+function previewPattern(preview) {
+    const core = preview
+        .replace(/…$/, '')
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\\? /g, '\\s+');
+    return new RegExp(`>(\\s*)(${core}[^<{]*?)(\\s*)<`);
+}
+export function applyTemplateWrapToFile(code, style, items, allocator) {
+    const applied = [];
+    const skipped = [];
+    const labels = {};
+    const hasHead = style.headMarker.test(code);
+    if (!hasHead && bindsForeignT(code)) {
+        return {
+            code,
+            applied,
+            skipped: items.map((item) => ({ item, reason: 'file binds its own t() — agent work' })),
+            labels,
+        };
+    }
+    if (!hasHead && style.injectHead(code, style.head) === null) {
+        return {
+            code,
+            applied,
+            skipped: items.map((item) => ({ item, reason: 'no safe wiring point in this file — agent work' })),
+            labels,
+        };
+    }
+    const file = items[0]?.file ?? '';
+    const scope = style.fileScope?.(file) ?? slugify(basename(file).replace(/\.[a-z0-9]+$/i, '')) ?? 'shared';
+    let next = code;
+    for (const item of items) {
+        if (item.kind !== 'text') {
+            skipped.push({ item, reason: `${item.kind} stays agent work` });
+            continue;
+        }
+        const match = next.match(previewPattern(item.preview));
+        if (!match || match.index === undefined) {
+            skipped.push({ item, reason: 'text node not matched in source — agent work' });
+            continue;
+        }
+        const collapsed = match[2].replace(/\s+/g, ' ').trim();
+        const id = allocator.allocate(scope || 'shared', slugify(collapsed));
+        const escaped = collapsed.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        const replacement = `>${match[1]}${style.open}"${id}", "${escaped}"${style.close}${match[3]}<`;
+        next = next.slice(0, match.index) + replacement + next.slice(match.index + match[0].length);
+        labels[id] = decodeJsxEntities(collapsed);
+        applied.push({ kind: 'text', file: item.file, line: item.line, id, preview: item.preview });
+    }
+    if (applied.length > 0 && !style.headMarker.test(next)) {
+        next = style.injectHead(next, style.head) ?? next;
+    }
+    return { code: next, applied, skipped, labels };
+}
+/**
+ * Apply the template wraps across a project — same contract as applyWrap:
+ * scans, mutates source files, returns the generated labels for staging and
+ * seeding. The style's ensureWiring hook then writes any one-time project
+ * wiring (e.g. a root layout labels loader) when files were wrapped.
+ */
+export function applyTemplateWrap(rootDir, opts) {
+    const { style } = opts;
+    const scan = scanWrappable(rootDir, { excludePrefixes: opts.excludePrefixes });
+    const existingLabels = (() => {
+        try {
+            return JSON.parse(readFileSync(join(rootDir, '.fimo', 'migration', 'labels.json'), 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    })();
+    const allocator = new KeyAllocator([...Object.keys(existingLabels), ...scan.wrappedIds.labels]);
+    const result = { applied: [], skipped: [], labels: {}, filesChanged: [] };
+    const byFile = new Map();
+    for (const item of scan.items) {
+        if (!item.file.endsWith(style.ext)) {
+            continue;
+        }
+        const list = byFile.get(item.file) ?? [];
+        list.push(item);
+        byFile.set(item.file, list);
+    }
+    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 = applyTemplateWrapToFile(code, style, items, allocator);
+        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);
+        }
+    }
+    if (result.filesChanged.length > 0 && style.ensureWiring) {
+        result.filesChanged.push(...style.ensureWiring(rootDir));
+    }
+    return result;
+}

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

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

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;