fimo 0.8.0 → 0.9.0-experimental.10

package/dist/scripts/routes/module-resolve.js

@@ -0,0 +1,78 @@
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', '.fimo']);
+export const DEFAULT_COMPONENT_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js'];
+export function walkFiles(dir, matches, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry)) {
+            continue;
+        }
+        const full = join(dir, entry);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir) {
+            walkFiles(full, matches, out);
+        }
+        else if (matches(entry)) {
+            out.push(full);
+        }
+    }
+}
+/** Import map of a routes file: local component name → module specifier. */
+export function componentImports(code) {
+    const imports = new Map();
+    for (const match of code.matchAll(/import\s+(\w+)\s*(?:,\s*\{[^}]*\})?\s+from\s+['"]([^'"]+)['"]/g)) {
+        imports.set(match[1], match[2]);
+    }
+    for (const match of code.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
+        for (const token of match[1].split(',')) {
+            const name = token.replace(/\s+as\s+(\w+)\s*$/, '$1').trim();
+            if (/^\w+$/.test(name)) {
+                imports.set(name, match[2]);
+            }
+        }
+    }
+    for (const match of code.matchAll(/(?:const|let)\s+(\w+)\s*=\s*(?:React\.)?lazy\(\s*(?:async\s*)?\(\)\s*=>\s*import\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+        imports.set(match[1], match[2]);
+    }
+    return imports;
+}
+export function resolveModuleFile(cwd, fromFile, spec, extensions = DEFAULT_COMPONENT_EXTENSIONS) {
+    let base;
+    if (spec.startsWith('.')) {
+        base = join(dirname(fromFile), spec);
+    }
+    else if (spec.startsWith('~/') || spec.startsWith('@/')) {
+        base = join(cwd, 'src', spec.slice(2));
+    }
+    else {
+        return null;
+    }
+    for (const candidate of [
+        ...extensions.map((ext) => `${base}${ext}`),
+        ...extensions.map((ext) => join(base, `index${ext}`)),
+        base,
+    ]) {
+        try {
+            if (statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}

package/dist/scripts/routes/page-structure.d.ts

@@ -0,0 +1,72 @@
+import type { CollectionCandidate } from '../scan-wrappable.js';
+/**
+ * Page-structure drafts — the machine's proposed NESTED model of a page.
+ * The scanner already sees everything the model needs: the page file's
+ * section components (capitalized JSX children, in document order), each
+ * section's label keys (its file-derived prefix) and its in-code collection
+ * candidates (typed rows). Joined, that IS the page's Single: one nested
+ * block field per section, recursing into the section's own components so
+ * deep structure (a Features grid whose groups live in their own files)
+ * surfaces too. The agent refines names and shapes — it no longer decides
+ * WHETHER to model, and real marketing copy stops dying as "page furniture"
+ * exemptions.
+ */
+export interface PageSectionDraft {
+    /** Proposed field key on the page Single (camelCase of the component). */
+    key: string;
+    component: string;
+    file: string;
+    /** The section's label-key prefix (file-derived). */
+    prefix: string;
+    /** Staged label keys the section owns — its scalar copy fields. */
+    labelKeys: string[];
+    /** In-code collection candidates found in the section's file — its
+     *  repeated block items (cards, quotes, logos), with their source rows so
+     *  the Single's document can be assembled without reopening the code. */
+    collections: Array<{
+        name: string;
+        fields: string[];
+        count: number;
+        rows?: Array<Record<string, unknown>>;
+    }>;
+    /** Content-bearing components the section renders — nested blocks. */
+    children?: PageSectionDraft[];
+    /** The same file drafts on several pages — chrome. Model it ONCE as a
+     *  Single Type, never as a per-page block. */
+    shared?: boolean;
+}
+export interface PageStructureDraft {
+    pageId: string;
+    /** Proposed Single uid (PascalCase of the page id). */
+    single: string;
+    sections: PageSectionDraft[];
+}
+export declare function draftPageStructures(args: {
+    cwd: string;
+    framework: string | null;
+    routes: Record<string, {
+        path?: string;
+        labelPrefixes?: unknown;
+        [key: string]: unknown;
+    }>;
+    stagedKeys: Iterable<string>;
+    collections: CollectionCandidate[];
+}): PageStructureDraft[];
+/** Flat section count across the nesting — the summary's visibility number. */
+export declare function countDraftSections(draft: PageStructureDraft): number;
+/**
+ * The machine-BUILT page Single: a ready-to-push singleton schema plus its
+ * filled document, assembled from the draft's non-shared sections (shared
+ * sections are chrome — modeled once elsewhere). One `max: 1` block per
+ * section; the section's labels become scalar fields carrying the staged
+ * values, its repeated arrays become nested blocks carrying the source
+ * rows, its child components nest the same way. The agent renames fields
+ * to editorial names and rewires reads — it no longer composes anything.
+ */
+export interface PageSingleDraft {
+    uid: string;
+    pageId: string;
+    schema: Record<string, unknown>;
+    document: Record<string, unknown>;
+}
+export declare function buildPageSingleDraft(draft: PageStructureDraft, labelValues: Record<string, string>): PageSingleDraft | null;

package/dist/scripts/routes/page-structure.js

@@ -0,0 +1,234 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { frameworkSectionStyle } from '../frameworks/discover.js';
+import { componentImports, resolveModuleFile, resolveRouteFiles } from './label-prefixes.js';
+const MAX_SECTION_DEPTH = 3;
+const MAX_DRAFT_ROWS = 50;
+const pascal = (value) => value
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .split(/[-_.\s]/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+const camel = (value) => {
+    const p = pascal(value);
+    return p.charAt(0).toLowerCase() + p.slice(1);
+};
+/** Capitalized JSX tags in DOCUMENT order (deduped, first appearance). */
+function sectionTags(code) {
+    const seen = new Set();
+    const tags = [];
+    for (const match of code.matchAll(/<([A-Z]\w*)[\s/>]/g)) {
+        if (!seen.has(match[1])) {
+            seen.add(match[1]);
+            tags.push(match[1]);
+        }
+    }
+    return tags;
+}
+function draftSection(context, tag, file, depth) {
+    const rel = relative(context.cwd, file);
+    const prefix = context.style.fileScope(rel);
+    const labelKeys = context.keysByPrefix.get(prefix) ?? [];
+    const collections = (context.collectionsByFile.get(rel) ?? []).map((candidate) => ({
+        name: candidate.name,
+        fields: candidate.fields,
+        count: candidate.count,
+        ...(candidate.typedRows ? { rows: candidate.typedRows.slice(0, MAX_DRAFT_ROWS) } : {}),
+    }));
+    const children = depth < MAX_SECTION_DEPTH ? draftChildSections(context, file, depth + 1) : [];
+    if (labelKeys.length === 0 && collections.length === 0 && children.length === 0) {
+        return null; // pure layout — nothing to model
+    }
+    const draft = { key: camel(tag), component: tag, file: rel, prefix, labelKeys, collections };
+    if (children.length > 0) {
+        draft.children = children;
+    }
+    return draft;
+}
+/** Auto-imported components (Nuxt's components/ convention): a tag with no
+ *  import statement may still be a local file at a conventional path. */
+function resolveAutoImportedComponent(context, tag) {
+    for (const dir of context.style.fallbackComponentDirs) {
+        for (const ext of context.style.extensions) {
+            const candidate = join(context.cwd, dir, `${tag}${ext}`);
+            try {
+                if (statSync(candidate).isFile()) {
+                    return candidate;
+                }
+            }
+            catch {
+                /* try next */
+            }
+        }
+    }
+    return null;
+}
+function draftChildSections(context, file, depth) {
+    let code;
+    try {
+        code = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const imports = componentImports(code);
+    const sections = [];
+    for (const tag of sectionTags(code)) {
+        const spec = imports.get(tag);
+        const sectionFile = spec
+            ? resolveModuleFile(context.cwd, file, spec, context.style.extensions)
+            : resolveAutoImportedComponent(context, tag);
+        if (!sectionFile || context.visited.has(sectionFile)) {
+            continue; // library components (Button, Link) have no local file
+        }
+        context.visited.add(sectionFile);
+        const section = draftSection(context, tag, sectionFile, depth);
+        if (section) {
+            sections.push(section);
+        }
+    }
+    return sections;
+}
+export function draftPageStructures(args) {
+    const { cwd, framework, routes, collections } = args;
+    const keysByPrefix = new Map();
+    for (const key of args.stagedKeys) {
+        const dot = key.indexOf('.');
+        if (dot > 0) {
+            const prefix = key.slice(0, dot);
+            keysByPrefix.set(prefix, [...(keysByPrefix.get(prefix) ?? []), key]);
+        }
+    }
+    const collectionsByFile = new Map();
+    for (const candidate of collections) {
+        collectionsByFile.set(candidate.file, [...(collectionsByFile.get(candidate.file) ?? []), candidate]);
+    }
+    const style = frameworkSectionStyle(framework);
+    const drafts = [];
+    for (const { routeId, file } of resolveRouteFiles(cwd, framework, routes)) {
+        const context = { cwd, style, keysByPrefix, collectionsByFile, visited: new Set([file]) };
+        const sections = draftChildSections(context, file, 1);
+        if (sections.length > 1) {
+            drafts.push({ pageId: routeId, single: pascal(routeId), sections });
+        }
+    }
+    markSharedSections(drafts);
+    return drafts;
+}
+/** A section file drafted on several pages is chrome — flag it so the agent
+ *  models it once (Single Type) instead of nesting it under every page. */
+function markSharedSections(drafts) {
+    const pagesByFile = new Map();
+    const index = (pageId, sections) => {
+        for (const section of sections) {
+            pagesByFile.set(section.file, (pagesByFile.get(section.file) ?? new Set()).add(pageId));
+            index(pageId, section.children ?? []);
+        }
+    };
+    for (const draft of drafts) {
+        index(draft.pageId, draft.sections);
+    }
+    const flag = (sections) => {
+        for (const section of sections) {
+            if ((pagesByFile.get(section.file)?.size ?? 0) > 1) {
+                section.shared = true;
+            }
+            flag(section.children ?? []);
+        }
+    };
+    for (const draft of drafts) {
+        flag(draft.sections);
+    }
+}
+/** Flat section count across the nesting — the summary's visibility number. */
+export function countDraftSections(draft) {
+    const walk = (sections) => sections.reduce((total, section) => total + 1 + walk(section.children ?? []), 0);
+    return walk(draft.sections);
+}
+const labelFieldName = (key) => camel(key.split('.').pop() ?? key);
+const scalarType = (value) => value.length > 80 || value.includes('\n') ? 'text' : 'string';
+function sectionBlock(section, labelValues) {
+    const fields = {};
+    const value = {};
+    let fieldCount = 0;
+    for (const key of section.labelKeys) {
+        const name = labelFieldName(key);
+        if (fields[name]) {
+            continue;
+        }
+        const labelValue = labelValues[key] ?? '';
+        fields[name] = { type: scalarType(labelValue) };
+        value[name] = labelValue;
+        fieldCount += 1;
+    }
+    for (const collection of section.collections) {
+        const name = camel(collection.name);
+        if (fields[name]) {
+            continue;
+        }
+        const itemFields = {};
+        for (const field of collection.fields) {
+            itemFields[field] = { type: 'string' };
+        }
+        if (Object.keys(itemFields).length === 0) {
+            continue;
+        }
+        fields[name] = { type: 'blocks', schema: { fields: itemFields } };
+        value[name] = (collection.rows ?? []).map((row) => {
+            const item = {};
+            for (const field of collection.fields) {
+                const cell = row[field];
+                if (cell != null && typeof cell !== 'object') {
+                    item[field] = typeof cell === 'string' ? cell : String(cell);
+                }
+            }
+            return item;
+        });
+        fieldCount += 1;
+    }
+    for (const child of section.children ?? []) {
+        if (child.shared) {
+            continue;
+        }
+        const block = sectionBlock(child, labelValues);
+        if (!block || fields[child.key]) {
+            continue;
+        }
+        fields[child.key] = { type: 'blocks', max: 1, schema: { fields: block.fields } };
+        value[child.key] = [block.value];
+        fieldCount += block.fieldCount;
+    }
+    if (Object.keys(fields).length === 0) {
+        return null;
+    }
+    return { fields, value, fieldCount };
+}
+export function buildPageSingleDraft(draft, labelValues) {
+    const fields = {};
+    const document = {};
+    let totalFields = 0;
+    for (const section of draft.sections) {
+        if (section.shared || fields[section.key]) {
+            continue;
+        }
+        const block = sectionBlock(section, labelValues);
+        if (!block) {
+            continue;
+        }
+        fields[section.key] = { type: 'blocks', max: 1, schema: { fields: block.fields } };
+        document[section.key] = [block.value];
+        totalFields += block.fieldCount;
+    }
+    // A one-field page is a label, not a Single — only real structure drafts.
+    if (Object.keys(fields).length === 0 || totalFields < 3) {
+        return null;
+    }
+    return {
+        uid: draft.single,
+        pageId: draft.pageId,
+        schema: { uid: draft.single, name: draft.single, isSingleton: true, fields },
+        document,
+    };
+}

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

@@ -0,0 +1,200 @@
+/**
+ * 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' | 'formatted-text' | 'image' | 'video' | 'file-link' | 'attribute';
+export interface WrappableItem {
+    kind: WrappableKind;
+    file: string;
+    line: number;
+    preview: string;
+    /** AST span info for the --apply codemod (offsets into the file). */
+    span?: {
+        start: number;
+        end: number;
+        parentTag?: string;
+        openNameStart?: number;
+        openNameEnd?: number;
+        closeNameStart?: number;
+        closeNameEnd?: number;
+    };
+}
+/**
+ * In-code collection candidate: an array literal of same-shaped objects with
+ * user-visible string fields (services cards, FAQ items, testimonials, …).
+ * Flat labels are the wrong shape for these — they belong in a Fimo
+ * collection (schema + entries), migrated by the agent.
+ */
+export interface CollectionCandidate {
+    name: string;
+    file: string;
+    line: number;
+    count: number;
+    fields: string[];
+    sample: string;
+    /**
+     * Cross-collection references detected by value matching: this candidate's
+     * field values point at another candidate's identity values. Migrated as
+     * Fimo `reference` fields (`target`/`targets` + `many`), never as strings.
+     */
+    references?: CandidateReference[];
+    /** Per-field string values (capped) — internal input to reference
+     *  detection; stripped before the plan is written. */
+    fieldValues?: Record<string, string[]>;
+    /** First row with NATIVE value types — internal input to schema-draft
+     *  type inference; stripped before the plan is written. */
+    typedSample?: Record<string, unknown>;
+    /** All rows (capped) with NATIVE value types — internal input to the
+     *  rows-staging generator; stripped before the plan is written. */
+    typedRows?: Record<string, unknown>[];
+    manyFields?: string[];
+}
+export interface CandidateReference {
+    field: string;
+    /** Candidate name(s) the values point at: one = fixed target, several = polymorphic. */
+    targets: string[];
+    many: boolean;
+}
+interface ReferenceMatchable {
+    name: string;
+    references?: CandidateReference[];
+    fieldValues?: Record<string, string[]>;
+    manyFields?: string[];
+}
+/**
+ * Annotate candidates whose field values point at another candidate's
+ * identity values: one full-coverage target = fixed reference, several
+ * partial targets covering together = polymorphic. Mutates in place.
+ *
+ * Coverage is OCCURRENCE-weighted and dangling-adjusted: values matching no
+ * candidate's identity set are dangling references by definition (deleted
+ * targets, sentinels) and drop out of the denominator, weighted by how
+ * often they occur — 1,700 case studies pointing at 12 clients with 190
+ * distinct ghost values is still a reference field, because 89% of the ROWS
+ * resolve. Guards against coincidence: at least 2 distinct matched values
+ * and at least half the occurrences must resolve somewhere.
+ */
+export declare function annotateCandidateReferences(candidates: ReferenceMatchable[]): void;
+/**
+ * External live data source: content fetched at render time from a
+ * third-party API (GitHub stats, dev.to posts, a headless CMS). Invisible to
+ * the wrap scan by nature — the migration must ASK the user what to do with
+ * it (keep live vs ingest) instead of guessing.
+ */
+export interface ExternalSource {
+    host: string;
+    files: string[];
+    count: number;
+    /** 'cms' when detected via a headless-CMS SDK dependency: the site's
+     *  CONTENT lives there — migrating it is the point, not an option. */
+    kind?: 'api' | 'cms';
+}
+/** Identities of already-wrapped content, for the seeding gate. */
+export interface WrappedIds {
+    labels: string[];
+    media: string[];
+    richText: string[];
+    files: string[];
+    /** Every wrapped key, ALL kinds, in ENCOUNTER order (per-file walk, files
+     *  in walk order) — the on-page reading order the Studio Pages view sorts
+     *  by. Deduplicated keeping the first occurrence; never sorted. */
+    ordered: string[];
+}
+export interface WrapScanResult {
+    items: WrappableItem[];
+    wrappedCount: number;
+    filesScanned: number;
+    wrappedIds: WrappedIds;
+    collections: CollectionCandidate[];
+    externalSources: ExternalSource[];
+    dataFiles: DataCopyFile[];
+    /** `t()` calls bound to a FOREIGN i18n library (next-intl, i18next, …), not
+     *  Fimo — surfaced so the migration never claims them as editable coverage. */
+    foreignI18nCount: number;
+}
+/**
+ * A .json data file whose values are site copy (config-driven sites keep ALL
+ * their text there and templates render only expressions, so template/JSX
+ * scanning finds nothing). Each detected file must be triaged in the manifest
+ * (`wrap.dataFiles`) — otherwise a copy-in-config site would pass the
+ * coverage gate with zero editable content.
+ */
+export interface DataCopyFile {
+    file: string;
+    strings: number;
+    samples: string[];
+    collections: DataFileCollection[];
+    /** 'markdown' groups: prose documents (md/mdx) aggregated per directory —
+     *  content the wrap cannot label-ify (Tier 1b ingestion territory), but the
+     *  triage decision must still be explicit. */
+    kind?: 'markdown';
+    /** Number of documents behind a markdown group entry. */
+    count?: number;
+}
+export interface DataFileCollection {
+    path: string;
+    length: number;
+    copyFields: string[];
+    references?: CandidateReference[];
+    /** Internal input to reference detection; stripped before the plan is written. */
+    fieldValues?: Record<string, string[]>;
+    /** First row with NATIVE value types — internal input to schema-draft
+     *  type inference; stripped before the plan is written. */
+    typedSample?: Record<string, unknown>;
+    /** All rows (capped) with NATIVE value types — internal to rows staging. */
+    typedRows?: Record<string, unknown>[];
+    manyFields?: string[];
+    /** Fields forced to `string` regardless of inferred type — markdown/MDX
+     *  bodies stay verbatim so the user's existing renderer keeps working
+     *  (wrap mode never reshapes what the page already renders). */
+    verbatimFields?: string[];
+}
+export declare function scanWrappableFile(filePath: string, code: string, relPath: string, opts?: {
+    i18nFimoWired?: boolean;
+}): {
+    items: WrappableItem[];
+    wrapped: number;
+    wrappedIds: WrappedIds;
+    collections: CollectionCandidate[];
+    foreignI18n?: number;
+};
+/**
+ * Parse ONE markdown/MDX document into a typed row: YAML frontmatter fields
+ * (natively typed — dates, booleans, numbers, arrays) plus a `slug` (from
+ * frontmatter or the filename stem) and a `body` holding the raw markdown
+ * after the frontmatter, verbatim. The body stays a string so the user's
+ * existing markdown renderer keeps rendering it unchanged (wrap mode).
+ */
+export declare function parseMarkdownDoc(fileName: string, raw: string): Record<string, unknown> | null;
+/**
+ * Read every markdown/MDX document in a directory (non-recursively — one
+ * group per directory) into typed rows. Shared by the scanner (sampling for
+ * schema drafts + reference detection) and the rows stager (full dataset).
+ */
+export declare function readMarkdownGroupRows(dir: string): Array<Record<string, unknown>>;
+export declare function scanDataJson(relPath: string, raw: string): DataCopyFile | null;
+/**
+ * The label keys a `decision: "labels"` data file is expected to seed —
+ * one per prose string, keyed by JSON path under the recorded prefix. The
+ * seeding gate verifies each exists in the database.
+ */
+export declare function dataFileLabelKeys(raw: string, prefix: string, filePath?: string): string[];
+/** Find render-time fetches of third-party APIs (fetch with an http(s) literal or template prefix). */
+export declare function scanExternalSources(rootDir: string, dirs: string[]): ExternalSource[];
+/**
+ * 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[];
+    excludePrefixes?: string[];
+    dataDirs?: string[];
+    keepInternal?: boolean;
+    /** The app's i18n message loader is wired to Fimo (imports
+     *  `loadFimoMessages`), so its foreign `t()` calls ARE Fimo-backed and
+     *  editable — count them as covered instead of excluding them. */
+    i18nFimoWired?: boolean;
+}): WrapScanResult;
+export {};