fimo 0.8.0 → 0.9.0-experimental.10

package/dist/scripts/scan-wrappable.js

@@ -0,0 +1,1355 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseSync } from 'oxc-parser';
+import YAML from 'yaml';
+import { collectScopedBindings, isFunctionLike, resolveScopedKey } from './i18n-namespace.js';
+// Fields whose values act as an entry's identity when another candidate's
+// field points at it. Matching is by VALUE OVERLAP, so a rename-heavy schema
+// still resolves; thresholds keep accidental overlaps out.
+/**
+ * Fields whose values identify a row STABLY (kebab slugs, ids, keys).
+ * Display fields (name, title) are deliberately excluded: matching them
+ * promotes person-name coincidences into references, and staged reference
+ * resolution is `by: slug` — a display-name "reference" could never resolve.
+ */
+const IDENTITY_FIELDS = ['slug', 'id', 'key'];
+/**
+ * Occurrence-capped value collection for reference detection. Identity sets
+ * must SPAN the whole collection — a 100-value window over 1,727 authors
+ * hides 94% of the identity space and every large relation with it — and
+ * coverage is occurrence-weighted, so duplicates are kept. The generous cap
+ * only bounds memory on very large sources.
+ */
+const FIELD_VALUES_CAP = 20_000;
+function capOccurrences(values) {
+    const kept = [];
+    for (const value of values) {
+        if (value) {
+            kept.push(value);
+            if (kept.length >= FIELD_VALUES_CAP) {
+                break;
+            }
+        }
+    }
+    return kept;
+}
+/**
+ * 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 function annotateCandidateReferences(candidates) {
+    const identitySets = candidates.map((candidate) => {
+        const sets = [];
+        for (const field of IDENTITY_FIELDS) {
+            const values = candidate.fieldValues?.[field];
+            if (values && new Set(values).size >= 2) {
+                sets.push(new Set(values));
+            }
+        }
+        return sets;
+    });
+    candidates.forEach((candidate, index) => {
+        const references = [];
+        for (const [field, rawValues] of Object.entries(candidate.fieldValues ?? {})) {
+            const values = rawValues.filter(Boolean);
+            if (new Set(values).size < 2) {
+                continue;
+            }
+            const matchesAnywhere = (value) => candidates.some((_, otherIndex) => otherIndex !== index && identitySets[otherIndex].some((set) => set.has(value)));
+            const explained = values.filter(matchesAnywhere).length;
+            if (explained / values.length < 0.5) {
+                continue;
+            }
+            const coverage = [];
+            candidates.forEach((other, otherIndex) => {
+                if (otherIndex === index) {
+                    return;
+                }
+                let matched = 0;
+                let distinctMatched = 0;
+                for (const set of identitySets[otherIndex]) {
+                    const hits = values.filter((value) => set.has(value));
+                    if (hits.length > matched) {
+                        matched = hits.length;
+                        distinctMatched = new Set(hits).size;
+                    }
+                }
+                if (matched / values.length >= 0.3) {
+                    coverage.push({ name: other.name, cover: matched / explained, distinctMatched });
+                }
+            });
+            const full = coverage.filter((target) => target.cover >= 0.8 && target.distinctMatched >= 2);
+            const combined = coverage.reduce((sum, target) => sum + target.cover, 0);
+            const many = candidate.manyFields?.includes(field) ?? false;
+            if (full.length === 1) {
+                references.push({ field, targets: [full[0].name], many });
+            }
+            else if (full.length === 0 && coverage.length >= 2 && combined >= 0.8) {
+                references.push({ field, targets: coverage.map((target) => target.name).sort(), many });
+            }
+        }
+        if (references.length > 0) {
+            candidate.references = references;
+        }
+    });
+}
+// Elements whose subtree counts as already wrapped.
+const WRAPPING_COMPONENTS = new Set([
+    'FimoText',
+    'FimoRichTextBlock',
+    'FimoMediaImage',
+    'FimoMediaVideo',
+    'FimoFileLink',
+    'Text',
+    'RichText',
+]);
+const IMAGE_ELEMENTS = new Set(['img', 'Image']);
+const VIDEO_ELEMENTS = new Set(['video', 'source', 'Video']);
+const WRAPPABLE_ATTRIBUTES = new Set(['placeholder', 'title', 'aria-label']);
+const FILE_LINK_PATTERN = /\.(pdf|zip|docx?|xlsx?|pptx?|csv|mp4|mov|webm)$/i;
+const SKIP_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'build', '.fimo']);
+const MIN_TEXT_LENGTH = 3;
+/**
+ * Prose containers whose children mix raw text with inline elements or
+ * expressions. Wrapping such text node-by-node produces FRAGMENT labels
+ * (", and agencies building…") that nobody can find or edit as a sentence —
+ * the whole block merges into ONE `formatted-text` item instead (agent work:
+ * the fimo`` tagged template or RichText, never the auto-wrap codemod).
+ */
+const PROSE_TAGS = new Set([
+    'p',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'li',
+    'blockquote',
+    'figcaption',
+    'dt',
+    'dd',
+    'label',
+    'legend',
+    'td',
+    'th',
+    'caption',
+    'summary',
+]);
+function meaningfulLength(text) {
+    return text.replace(/[^\p{L}\p{N}]/gu, '').length;
+}
+const PREVIEW_LENGTH = 60;
+function toPreview(value) {
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    return collapsed.length > PREVIEW_LENGTH ? `${collapsed.slice(0, PREVIEW_LENGTH)}…` : collapsed;
+}
+function lineOf(code, offset) {
+    return code.slice(0, offset).split('\n').length;
+}
+function jsxElementName(node) {
+    const name = node?.openingElement?.name ?? node?.name;
+    if (!name) {
+        return null;
+    }
+    if (name.type === 'JSXIdentifier') {
+        return name.name;
+    }
+    if (name.type === 'JSXMemberExpression') {
+        return name.property?.name ?? null;
+    }
+    return null;
+}
+function attributeValue(node, attribute) {
+    const attrs = node?.openingElement?.attributes ?? [];
+    for (const attr of attrs) {
+        if (attr.type !== 'JSXAttribute' || attr.name?.name !== attribute) {
+            continue;
+        }
+        const value = attr.value;
+        if (value?.type === 'Literal' && typeof value.value === 'string' && value.value.length > 0) {
+            return { value: value.value, start: attr.start ?? node.start ?? 0 };
+        }
+    }
+    return null;
+}
+const WRAPPED_ID_KIND = {
+    FimoText: 'labels',
+    Text: 'labels',
+    FimoRichTextBlock: 'richText',
+    RichText: 'richText',
+    FimoMediaImage: 'media',
+    FimoMediaVideo: 'media',
+    FimoFileLink: 'files',
+};
+// ── Non-JSX template scanning (.astro / .vue / .svelte) ─────────────────────
+// Coverage-only: text nodes are counted as wrappable items (no AST span, so
+// the codemod skips them — the agent wraps via the per-framework t() recipe),
+// and t('key', ...) usages count as wrapped so the gate converges.
+const TEMPLATE_EXPR_ONLY = /^[\s{}]*$|^\{[\s\S]*\}$|^\{\{[\s\S]*\}\}$/;
+/**
+ * Blank out <script>/<style>/<title> blocks in a markup body, preserving
+ * offsets. Script content is returned so t('key') usages inside it still
+ * count as wrapped; style content is dropped (CSS is never copy); <title>
+ * is head metadata the DOM edit contract cannot target (SEO surface, not
+ * body copy).
+ */
+function stripScriptAndStyle(markup) {
+    let scripts = '';
+    let out = markup.replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, (block, inner) => {
+        scripts += `${inner}\n`;
+        return ' '.repeat(block.length);
+    });
+    // Comments are stripped explicitly: the quote-aware tag splitter must never
+    // be asked to eat `<!-- ... -->` (an apostrophe inside opens a fake quote).
+    for (const dropRe of [/<!--[\s\S]*?-->/g, /<style\b[^>]*>[\s\S]*?<\/style>/gi, /<title\b[^>]*>[\s\S]*?<\/title>/gi]) {
+        out = out.replace(dropRe, (block) => ' '.repeat(block.length));
+    }
+    return { markup: out, scripts };
+}
+function extractTemplate(ext, code) {
+    if (ext === 'astro') {
+        // \r?\n: CRLF checkouts exist in the wild (a2-fresh dogfood).
+        const match = code.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+        const offset = match ? match[0].length : 0;
+        const body = stripScriptAndStyle(code.slice(offset));
+        return { template: body.markup, offset, frontmatter: `${match ? match[1] : ''}\n${body.scripts}` };
+    }
+    if (ext === 'vue') {
+        const match = code.match(/<template[^>]*>([\s\S]*)<\/template>/);
+        const script = code.match(/<script[^>]*>([\s\S]*?)<\/script>/);
+        // The template region can itself contain <title> (inline SVG) — strip it
+        // like the astro/svelte branches do.
+        const body = stripScriptAndStyle(match ? match[1] : '');
+        return {
+            template: body.markup,
+            offset: match ? code.indexOf(match[1]) : 0,
+            frontmatter: `${script ? script[1] : ''}\n${body.scripts}`,
+        };
+    }
+    // svelte: strip script/style/title blocks, keep the markup
+    const body = stripScriptAndStyle(code);
+    return { template: body.markup, offset: 0, frontmatter: body.scripts };
+}
+function scanTemplateFile(ext, code, relPath) {
+    const items = [];
+    const wrappedIds = { labels: [], media: [], richText: [], files: [], ordered: [] };
+    let wrapped = 0;
+    const { template, offset, frontmatter } = extractTemplate(ext, code);
+    // t('key', ...) in frontmatter/script and in template expressions = wrapped.
+    for (const source of [frontmatter, template]) {
+        for (const match of source.matchAll(/\bt\(\s*['"]([^'"]+)['"]/g)) {
+            wrapped += 1;
+            wrappedIds.labels.push(match[1]);
+            wrappedIds.ordered.push(match[1]);
+        }
+    }
+    // data-fimo-source attributes = wrapped media/labels rendered via attrs.
+    wrapped += (template.match(/data-fimo-source/g) ?? []).length;
+    // Raw text nodes: strip tags and expressions, then measure leftover copy.
+    // Expression removal loops to a fixpoint so nested braces vanish entirely —
+    // `{title && <h2>{title}</h2>}` is prop-driven rendering, not copy.
+    let withoutExpr = template;
+    let before = '';
+    while (before !== withoutExpr) {
+        before = withoutExpr;
+        withoutExpr = withoutExpr.replace(/\{\{[\s\S]*?\}\}|\{[^{}]*\}/g, (m) => ' '.repeat(m.length));
+    }
+    // Tag-matching tolerates quoted attribute sections: vue templates write
+    // `v-if="page > 1"` and a naive <[^>]*> ends the tag at that inner '>'.
+    const textChunks = withoutExpr.split(/<(?:"[^"]*"|'[^']*'|[^"'>])*>/);
+    let cursor = 0;
+    for (const chunk of textChunks) {
+        const at = withoutExpr.indexOf(chunk, cursor);
+        cursor = at + chunk.length;
+        const meaningful = chunk.replace(/[^\p{L}\p{N}]/gu, '');
+        if (meaningful.length >= MIN_TEXT_LENGTH && !TEMPLATE_EXPR_ONLY.test(chunk)) {
+            items.push({
+                kind: 'text',
+                file: relPath,
+                line: lineOf(code, offset + Math.max(at, 0)),
+                preview: toPreview(chunk),
+            });
+        }
+    }
+    return { items, wrapped, wrappedIds };
+}
+function unwrapTsExpression(node) {
+    let current = node;
+    while (current && (current.type === 'TSAsExpression' || current.type === 'TSSatisfiesExpression')) {
+        current = current.expression;
+    }
+    return current;
+}
+/** First array object as NATIVE values (literals + literal arrays only) —
+ *  the typed input the schema-draft generator infers field types from.
+ *  Internal like fieldValues: stripped before the plan is written. */
+function literalObjectSample(obj) {
+    const out = {};
+    for (const prop of obj?.properties ?? []) {
+        if (prop.type !== 'Property' && prop.type !== 'ObjectProperty') {
+            continue;
+        }
+        const key = prop.key?.name ?? (typeof prop.key?.value === 'string' ? prop.key.value : null);
+        if (!key) {
+            continue;
+        }
+        const value = unwrapTsExpression(prop.value);
+        if (value?.type === 'Literal') {
+            out[key] = value.value;
+        }
+        else if (value?.type === 'ArrayExpression') {
+            const elements = (value.elements ?? []).map(unwrapTsExpression);
+            if (elements.every((el) => el?.type === 'Literal')) {
+                out[key] = elements.map((el) => el.value);
+            }
+        }
+    }
+    return out;
+}
+function detectCollectionFromDeclarator(declarator, codeForLines, scriptOffset, relPath, out) {
+    const init = unwrapTsExpression(declarator?.init);
+    if (!init || init.type !== 'ArrayExpression' || !Array.isArray(init.elements) || init.elements.length < 2) {
+        return;
+    }
+    const objects = init.elements.map(unwrapTsExpression);
+    if (!objects.every((el) => el?.type === 'ObjectExpression')) {
+        return;
+    }
+    // One level of nesting flattens into dotted keys ("button.text"): pricing
+    // tiers keep their copy inside nested objects and would otherwise slip by.
+    const stringFields = (obj, prefix = '', depth = 0) => {
+        const map = new Map();
+        for (const prop of obj.properties ?? []) {
+            if (prop.type !== 'Property' && prop.type !== 'ObjectProperty') {
+                continue;
+            }
+            const key = prop.key?.name ?? (typeof prop.key?.value === 'string' ? prop.key.value : null);
+            const value = unwrapTsExpression(prop.value);
+            if (!key) {
+                continue;
+            }
+            if (value?.type === 'Literal' && typeof value.value === 'string') {
+                map.set(`${prefix}${key}`, value.value);
+            }
+            else if (value?.type === 'ObjectExpression' && depth < 1) {
+                for (const [nestedKey, nestedValue] of stringFields(value, `${prefix}${key}.`, depth + 1)) {
+                    map.set(nestedKey, nestedValue);
+                }
+            }
+        }
+        return map;
+    };
+    // String-array fields (tags: ['a', 'b']) are candidate MANY-references.
+    const arrayStringFields = (obj) => {
+        const map = new Map();
+        for (const prop of obj.properties ?? []) {
+            if (prop.type !== 'Property' && prop.type !== 'ObjectProperty') {
+                continue;
+            }
+            const key = prop.key?.name ?? (typeof prop.key?.value === 'string' ? prop.key.value : null);
+            const value = unwrapTsExpression(prop.value);
+            if (!key || value?.type !== 'ArrayExpression') {
+                continue;
+            }
+            const elements = (value.elements ?? []).map(unwrapTsExpression);
+            if (elements.length > 0 && elements.every((el) => el?.type === 'Literal' && typeof el.value === 'string')) {
+                map.set(key, elements.map((el) => el.value));
+            }
+        }
+        return map;
+    };
+    const first = stringFields(objects[0]);
+    const common = [...first.keys()].filter((key) => objects.every((obj) => stringFields(obj).has(key)));
+    // User-visible heuristic: at least one shared field reads like copy.
+    const copyField = common.find((key) => objects.some((obj) => /\s/.test(stringFields(obj).get(key) ?? '')));
+    if (common.length === 0 || !copyField) {
+        return;
+    }
+    const fieldValues = {};
+    for (const key of common) {
+        fieldValues[key] = capOccurrences(objects.map((obj) => stringFields(obj).get(key) ?? ''));
+    }
+    const manyFields = [];
+    const firstArrays = arrayStringFields(objects[0]);
+    for (const key of firstArrays.keys()) {
+        if (objects.every((obj) => arrayStringFields(obj).has(key))) {
+            fieldValues[key] = capOccurrences(objects.flatMap((obj) => arrayStringFields(obj).get(key) ?? []));
+            manyFields.push(key);
+        }
+    }
+    out.push({
+        name: declarator.id?.name ?? 'items',
+        file: relPath,
+        line: lineOf(codeForLines, scriptOffset + (declarator.start ?? 0)),
+        count: objects.length,
+        fields: common.sort(),
+        sample: toPreview(stringFields(objects[0]).get(copyField) ?? ''),
+        fieldValues,
+        typedSample: literalObjectSample(objects[0]),
+        typedRows: objects.slice(0, 500).map(literalObjectSample),
+        ...(manyFields.length > 0 ? { manyFields } : {}),
+    });
+}
+/**
+ * Collection candidates inside an SFC script block (.vue `<script setup>`,
+ * .astro frontmatter, .svelte scripts) — the pricing/features arrays of
+ * config-in-component templates live there, invisible to template text
+ * scanning (the nuxtship dogfood's pricing tiers proved it).
+ */
+function scanScriptCollections(scriptCode, originalCode, relPath) {
+    const collections = [];
+    if (!scriptCode.trim()) {
+        return collections;
+    }
+    let program;
+    try {
+        program = parseSync('inline-script.ts', scriptCode).program;
+    }
+    catch {
+        return collections;
+    }
+    const base = originalCode.indexOf(scriptCode);
+    const codeForLines = base >= 0 ? originalCode : scriptCode;
+    const scriptOffset = base >= 0 ? base : 0;
+    const walk = (node) => {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        if (node.type === 'VariableDeclarator') {
+            detectCollectionFromDeclarator(node, codeForLines, scriptOffset, relPath, collections);
+        }
+        for (const value of Object.values(node)) {
+            if (Array.isArray(value)) {
+                value.forEach(walk);
+            }
+            else if (value && typeof value === 'object' && value.type) {
+                walk(value);
+            }
+        }
+    };
+    walk(program);
+    return collections;
+}
+/** i18n libraries whose `t`/`useTranslations` is NOT Fimo: their `t('key')`
+ *  calls read from the library's own message store (locales/*.json), so
+ *  counting them as Fimo coverage is a lie — editing them in Fimo Studio does
+ *  nothing to the live site. */
+const FOREIGN_I18N_SOURCES = [
+    /^next-intl(\/|$)/,
+    /^use-intl(\/|$)/,
+    /^react-i18next$/,
+    /^i18next$/,
+    /^react-intl$/,
+    /^@lingui\//,
+];
+/** Does this file bind `t` from a foreign i18n library (and NOT from Fimo)?
+ *  Only then are its `t()` calls excluded from the wrapped count. */
+function foreignI18nBinding(ast) {
+    let foreign = false;
+    let fimo = false;
+    for (const node of ast.body ?? []) {
+        if (node.type !== 'ImportDeclaration' || typeof node.source?.value !== 'string') {
+            continue;
+        }
+        const src = node.source.value;
+        if (/^fimo(\/|$)/.test(src)) {
+            fimo = true;
+        }
+        if (FOREIGN_I18N_SOURCES.some((re) => re.test(src))) {
+            foreign = true;
+        }
+    }
+    return foreign && !fimo;
+}
+export function scanWrappableFile(filePath, code, relPath, opts = {}) {
+    const items = [];
+    let wrapped = 0;
+    let foreignI18n = 0;
+    const wrappedIds = { labels: [], media: [], richText: [], files: [], ordered: [] };
+    const collections = [];
+    const templateExt = filePath.match(/\.(astro|vue|svelte)$/)?.[1];
+    if (templateExt) {
+        const result = scanTemplateFile(templateExt, code, relPath);
+        const { frontmatter } = extractTemplate(templateExt, code);
+        return { ...result, collections: scanScriptCollections(frontmatter, code, relPath) };
+    }
+    let ast;
+    try {
+        ast = parseSync(filePath, code).program;
+    }
+    catch {
+        return { items, wrapped, wrappedIds, collections };
+    }
+    // A foreign `t()` is Fimo-backed once the message loader is wired to Fimo
+    // (the ingested labels flow through it), so it counts as covered.
+    const foreignT = !opts.i18nFimoWired && foreignI18nBinding(ast);
+    function detectCollection(declarator) {
+        detectCollectionFromDeclarator(declarator, code, 0, relPath, collections);
+    }
+    // Text nodes absorbed into a merged formatted-text item (keyed by offset) —
+    // the JSXText visitor skips them so fragments never become labels.
+    const mergedText = new Set();
+    function containsWrappedContent(node) {
+        if (!node || typeof node !== 'object') {
+            return false;
+        }
+        if (node.type === 'CallExpression' && node.callee?.type === 'Identifier' && node.callee.name === 't') {
+            return true;
+        }
+        if (node.type === 'TaggedTemplateExpression' && node.tag?.type === 'Identifier' && node.tag.name === 'fimo') {
+            return true;
+        }
+        if (node.type === 'JSXElement') {
+            const name = jsxElementName(node);
+            if (name && WRAPPING_COMPONENTS.has(name)) {
+                return true;
+            }
+        }
+        for (const key of Object.keys(node)) {
+            const child = node[key];
+            if (Array.isArray(child)) {
+                if (child.some((item) => containsWrappedContent(item))) {
+                    return true;
+                }
+            }
+            else if (typeof child === 'object' && child !== null && containsWrappedContent(child)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Every JSXText inside a prose element, recursing through inline children
+     *  (inside a `<p>`, nested elements are inline by HTML rules). */
+    function collectProseTextNodes(node, out) {
+        for (const child of node.children ?? []) {
+            if (child.type === 'JSXText') {
+                out.push(child);
+            }
+            else if (child.type === 'JSXElement') {
+                collectProseTextNodes(child, out);
+            }
+        }
+    }
+    function visit(node, insideWrapped, parentTag, scopes) {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        let childInsideWrapped = insideWrapped;
+        let childParentTag = parentTag;
+        // A function introduces a new scope layer with its useTranslations bindings,
+        // so a namespaced `t("leaf")` records the full key (matching the ingested DB).
+        const childScopes = isFunctionLike(node) ? [...scopes, collectScopedBindings(node)] : scopes;
+        if (node.type === 'JSXElement') {
+            const name = jsxElementName(node);
+            if (name) {
+                childParentTag = name;
+            }
+            if (name && WRAPPING_COMPONENTS.has(name)) {
+                wrapped += 1;
+                childInsideWrapped = true;
+                const kind = WRAPPED_ID_KIND[name];
+                const id = attributeValue(node, 'id');
+                if (kind && id) {
+                    wrappedIds[kind].push(id.value);
+                    wrappedIds.ordered.push(id.value);
+                }
+            }
+            if (!insideWrapped && name) {
+                if (IMAGE_ELEMENTS.has(name)) {
+                    const src = attributeValue(node, 'src');
+                    if (src) {
+                        items.push({
+                            kind: 'image',
+                            file: relPath,
+                            line: lineOf(code, src.start),
+                            preview: toPreview(src.value),
+                            span: {
+                                start: node.start,
+                                end: node.end,
+                                openNameStart: node.openingElement?.name?.start,
+                                openNameEnd: node.openingElement?.name?.end,
+                            },
+                        });
+                    }
+                }
+                else if (VIDEO_ELEMENTS.has(name)) {
+                    const src = attributeValue(node, 'src');
+                    if (src) {
+                        items.push({ kind: 'video', file: relPath, line: lineOf(code, src.start), preview: toPreview(src.value) });
+                    }
+                }
+                else if (name === 'a') {
+                    const href = attributeValue(node, 'href');
+                    if (href && FILE_LINK_PATTERN.test(href.value)) {
+                        items.push({
+                            kind: 'file-link',
+                            file: relPath,
+                            line: lineOf(code, href.start),
+                            preview: toPreview(href.value),
+                            span: {
+                                start: node.start,
+                                end: node.end,
+                                openNameStart: node.openingElement?.name?.start,
+                                openNameEnd: node.openingElement?.name?.end,
+                                closeNameStart: node.closingElement?.name?.start,
+                                closeNameEnd: node.closingElement?.name?.end,
+                            },
+                        });
+                    }
+                }
+                for (const attribute of WRAPPABLE_ATTRIBUTES) {
+                    const value = attributeValue(node, attribute);
+                    // Technical enums are not copy: next/image placeholder="blur|empty".
+                    if (value && attribute === 'placeholder' && /^(blur|empty)$/.test(value.value)) {
+                        continue;
+                    }
+                    if (value) {
+                        items.push({
+                            kind: 'attribute',
+                            file: relPath,
+                            line: lineOf(code, value.start),
+                            preview: `${attribute}: ${toPreview(value.value)}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Mixed prose detection runs on the ELEMENT (before its children are
+        // visited): a prose tag whose direct children interleave raw text with
+        // inline elements/expressions becomes ONE formatted-text item, and its
+        // text nodes are recorded so the JSXText visitor below skips them.
+        if (node.type === 'JSXElement' && !insideWrapped) {
+            const proseName = jsxElementName(node);
+            if (proseName && PROSE_TAGS.has(proseName)) {
+                const children = node.children ?? [];
+                const directText = children.filter((child) => child.type === 'JSXText' && meaningfulLength(String(child.value ?? '')) > 0);
+                const inline = children.filter((child) => child.type === 'JSXElement' ||
+                    (child.type === 'JSXExpressionContainer' && child.expression?.type !== 'JSXEmptyExpression'));
+                if (directText.length > 0 &&
+                    inline.length > 0 &&
+                    !directText.some((child) => mergedText.has(child.start)) &&
+                    !children.some((child) => containsWrappedContent(child))) {
+                    const textNodes = [];
+                    collectProseTextNodes(node, textNodes);
+                    const combined = textNodes.map((textNode) => String(textNode.value ?? '')).join(' ');
+                    if (meaningfulLength(combined) >= MIN_TEXT_LENGTH) {
+                        for (const textNode of textNodes) {
+                            if (typeof textNode.start === 'number') {
+                                mergedText.add(textNode.start);
+                            }
+                        }
+                        const inner = code.slice(node.openingElement?.end ?? node.start ?? 0, node.closingElement?.start ?? node.end ?? 0);
+                        items.push({
+                            kind: 'formatted-text',
+                            file: relPath,
+                            line: lineOf(code, node.start ?? 0),
+                            preview: toPreview(inner),
+                            span: { start: node.start, end: node.end, parentTag: proseName },
+                        });
+                    }
+                }
+            }
+        }
+        if (node.type === 'JSXText' && !insideWrapped && !mergedText.has(node.start)) {
+            const text = String(node.value ?? '');
+            const meaningful = text.replace(/[^\p{L}\p{N}]/gu, '');
+            if (meaningful.length >= MIN_TEXT_LENGTH) {
+                items.push({
+                    kind: 'text',
+                    file: relPath,
+                    line: lineOf(code, node.start ?? 0),
+                    preview: toPreview(text),
+                    span: { start: node.start, end: node.end, parentTag },
+                });
+            }
+        }
+        if (node.type === 'VariableDeclarator') {
+            detectCollection(node);
+        }
+        // t('key') calls count as wrapped content — but ONLY when `t` is Fimo's.
+        // A file that binds `t` from next-intl/i18next reads its own message store
+        // at runtime, so counting those calls as Fimo coverage is a false positive
+        // (the honest-agent finding: ~88 pre-existing next-intl keys "covered" but
+        // never actually editable in Fimo).
+        if (node.type === 'CallExpression' && node.callee?.type === 'Identifier' && node.callee.name === 't') {
+            if (foreignT) {
+                foreignI18n += 1;
+            }
+            else {
+                wrapped += 1;
+                const firstArg = node.arguments?.[0];
+                if (firstArg?.type === 'Literal' && typeof firstArg.value === 'string') {
+                    // Resolve the next-intl namespace so the recorded key matches the
+                    // ingested (namespaced) label in the DB. A passed-in param `t` is
+                    // unresolvable (the caller owns the namespace) — the call still counts
+                    // as wrapped, but we do not demand its bare key from the seeding gate.
+                    const resolved = resolveScopedKey(node.callee.name, firstArg.value, childScopes);
+                    if (!resolved.unresolvable) {
+                        wrappedIds.labels.push(resolved.key);
+                        wrappedIds.ordered.push(resolved.key);
+                    }
+                }
+            }
+        }
+        for (const key of Object.keys(node)) {
+            const child = node[key];
+            if (Array.isArray(child)) {
+                for (const item of child) {
+                    visit(item, childInsideWrapped, childParentTag, childScopes);
+                }
+            }
+            else if (typeof child === 'object' && child !== null) {
+                visit(child, childInsideWrapped, childParentTag, childScopes);
+            }
+        }
+    }
+    visit(ast, false, undefined, []);
+    return { items, wrapped, wrappedIds, collections, ...(foreignI18n > 0 ? { foreignI18n } : {}) };
+}
+function collectSourceFiles(dir, out = []) {
+    if (!existsSync(dir)) {
+        return out;
+    }
+    for (const entry of readdirSync(dir)) {
+        if (SKIP_DIRS.has(entry)) {
+            continue;
+        }
+        const full = join(dir, entry);
+        let stats;
+        try {
+            stats = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stats.isDirectory()) {
+            collectSourceFiles(full, out);
+        }
+        else if (/\.(ts|tsx|jsx|astro|vue|svelte)$/.test(entry) &&
+            !/\.d\.ts$/.test(entry) &&
+            !/\.(test|spec)\./.test(entry)) {
+            // Plain .ts included: collection arrays live in lib/constants-style
+            // modules, not only in JSX files.
+            out.push(full);
+        }
+    }
+    return out;
+}
+// ── Data-file copy detection (config-driven sites) ──────────────────────────
+const DATA_KEY_SKIP = new Set([
+    'icon',
+    'href',
+    'url',
+    'src',
+    'slug',
+    'id',
+    'lang',
+    'charset',
+    'type',
+    'logo',
+    'image',
+    'video',
+    'class',
+    'variant',
+    'theme',
+    'color',
+]);
+function isProseValue(key, value) {
+    if (DATA_KEY_SKIP.has(key.toLowerCase()) || key.startsWith('@')) {
+        return false;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < 3 || /^(https?:|mailto:|tel:|[./#@])/.test(trimmed)) {
+        return false;
+    }
+    // Prose has spaces; a short single token is an identifier, not copy.
+    return trimmed.includes(' ') || trimmed.length >= 12;
+}
+/**
+ * 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 function parseMarkdownDoc(fileName, raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    let frontmatter = {};
+    if (match) {
+        try {
+            const parsed = YAML.parse(match[1]);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                frontmatter = parsed;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    const body = raw.slice(match ? match[0].length : 0).trim();
+    const stem = fileName.replace(/\.[^.]+$/, '');
+    const slug = typeof frontmatter.slug === 'string' && frontmatter.slug.length > 0 ? frontmatter.slug : stem;
+    return { ...frontmatter, slug, body };
+}
+/**
+ * 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 function readMarkdownGroupRows(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const rows = [];
+    for (const entry of readdirSync(dir).sort()) {
+        if (!/\.(md|mdx)$/.test(entry) || /^(readme|changelog|license|contributing|agents|claude)\.md$/i.test(entry)) {
+            continue;
+        }
+        try {
+            const row = parseMarkdownDoc(entry, readFileSync(join(dir, entry), 'utf8'));
+            if (row) {
+                rows.push(row);
+            }
+        }
+        catch {
+            // unreadable document: skip it
+        }
+    }
+    return rows;
+}
+/**
+ * Build a DataFileCollection from markdown rows, mirroring scanDataJson's
+ * array branch (fieldValues for reference detection, typedSample for type
+ * inference) but keeping ALL rows in typedRows and marking `body` verbatim.
+ */
+function markdownGroupCollection(name, rows) {
+    if (rows.length < 2) {
+        return null;
+    }
+    const shape = Object.keys(rows[0]).sort().join(',');
+    if (!rows.every((row) => Object.keys(row).sort().join(',') === shape)) {
+        return null;
+    }
+    const fieldValues = {};
+    const manyFields = [];
+    for (const field of Object.keys(rows[0])) {
+        if (field === 'body') {
+            continue; // prose body is not a reference identity
+        }
+        if (rows.every((row) => typeof row[field] === 'string')) {
+            fieldValues[field] = capOccurrences(rows.map((row) => row[field]));
+        }
+        else if (rows.every((row) => Array.isArray(row[field]) && row[field].every((el) => typeof el === 'string'))) {
+            fieldValues[field] = capOccurrences(rows.flatMap((row) => row[field]));
+            manyFields.push(field);
+        }
+    }
+    return {
+        path: name,
+        length: rows.length,
+        copyFields: ['body'],
+        fieldValues,
+        typedSample: rows[0],
+        typedRows: rows,
+        verbatimFields: ['body'],
+        ...(manyFields.length > 0 ? { manyFields } : {}),
+    };
+}
+export function scanDataJson(relPath, raw) {
+    let parsed;
+    try {
+        parsed = /\.ya?ml$/.test(relPath) ? YAML.parse(raw) : JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    // Machine-format payloads whose strings are data, not copy: GeoJSON /
+    // TopoJSON name properties (map/globe sites) read as prose but are not
+    // site text.
+    const rootType = parsed?.type;
+    if (typeof rootType === 'string' &&
+        ['FeatureCollection', 'Feature', 'Topology', 'GeometryCollection'].includes(rootType)) {
+        return null;
+    }
+    const found = { file: relPath, strings: 0, samples: [], collections: [] };
+    const walk = (node, jsonPath, key) => {
+        if (typeof node === 'string') {
+            if (isProseValue(key, node)) {
+                found.strings += 1;
+                if (found.samples.length < 3) {
+                    found.samples.push(node.length > 60 ? `${node.slice(0, 57)}…` : node);
+                }
+            }
+            return;
+        }
+        if (Array.isArray(node)) {
+            const objects = node.filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry));
+            if (objects.length >= 2 && objects.length === node.length) {
+                const shape = Object.keys(objects[0]).sort().join(',');
+                const sameShape = objects.every((entry) => Object.keys(entry).sort().join(',') === shape);
+                const copyFields = Object.keys(objects[0]).filter((field) => objects.every((entry) => typeof entry[field] === 'string' && isProseValue(field, entry[field])));
+                if (sameShape && copyFields.length > 0) {
+                    // All common string fields (identity slugs included, prose or not)
+                    // plus string-array fields feed reference detection.
+                    const fieldValues = {};
+                    const manyFields = [];
+                    const typedSample = objects[0];
+                    for (const field of Object.keys(objects[0])) {
+                        if (objects.every((entry) => typeof entry[field] === 'string')) {
+                            fieldValues[field] = capOccurrences(objects.map((entry) => entry[field]));
+                        }
+                        else if (objects.every((entry) => Array.isArray(entry[field]) && entry[field].every((el) => typeof el === 'string'))) {
+                            fieldValues[field] = capOccurrences(objects.flatMap((entry) => entry[field]));
+                            manyFields.push(field);
+                        }
+                    }
+                    found.collections.push({
+                        path: jsonPath || '.',
+                        length: node.length,
+                        copyFields,
+                        fieldValues,
+                        typedSample,
+                        ...(manyFields.length > 0 ? { manyFields } : {}),
+                    });
+                }
+            }
+            node.forEach((entry, index) => walk(entry, `${jsonPath}[${index}]`, key));
+            return;
+        }
+        if (node && typeof node === 'object') {
+            for (const [childKey, child] of Object.entries(node)) {
+                walk(child, jsonPath ? `${jsonPath}.${childKey}` : childKey, childKey);
+            }
+        }
+    };
+    walk(parsed, '', '');
+    return found.strings >= 3 || found.collections.length > 0 ? found : 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 function dataFileLabelKeys(raw, prefix, filePath = '') {
+    let parsed;
+    try {
+        parsed = /\.ya?ml$/.test(filePath) ? YAML.parse(raw) : JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const keys = [];
+    const walk = (node, jsonPath, key) => {
+        if (typeof node === 'string') {
+            if (isProseValue(key, node)) {
+                keys.push(`${prefix}${jsonPath}`);
+            }
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach((entry, index) => walk(entry, `${jsonPath}.${index}`, key));
+            return;
+        }
+        if (node && typeof node === 'object') {
+            for (const [childKey, child] of Object.entries(node)) {
+                walk(child, jsonPath ? `${jsonPath}.${childKey}` : childKey, childKey);
+            }
+        }
+    };
+    walk(parsed, '', '');
+    return keys;
+}
+function collectDataFiles(dir, out = []) {
+    if (!existsSync(dir)) {
+        return out;
+    }
+    for (const entry of readdirSync(dir)) {
+        if (SKIP_DIRS.has(entry)) {
+            continue;
+        }
+        const full = join(dir, entry);
+        let stats;
+        try {
+            stats = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stats.isDirectory()) {
+            collectDataFiles(full, out);
+        }
+        else if (/\.(json|ya?ml)$/.test(entry) &&
+            !/^(package(-lock)?|tsconfig.*|.*\.config)\.json$/.test(entry) &&
+            !/^(pnpm-workspace|pnpm-lock|\.?prettierrc.*|renovate)\.(ya?ml)$/.test(entry)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+const INTERNAL_HOSTS = /^(localhost|127\.0\.0\.1|.*\.fimo\.ai)$/;
+function collectAllScriptFiles(dir, out = []) {
+    if (!existsSync(dir)) {
+        return out;
+    }
+    for (const entry of readdirSync(dir)) {
+        if (SKIP_DIRS.has(entry)) {
+            continue;
+        }
+        const full = join(dir, entry);
+        let stats;
+        try {
+            stats = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stats.isDirectory()) {
+            collectAllScriptFiles(full, out);
+        }
+        else if (/\.(ts|tsx|js|jsx|mjs)$/.test(entry) && !/\.(test|spec)\./.test(entry)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/** Find render-time fetches of third-party APIs (fetch with an http(s) literal or template prefix). */
+export function scanExternalSources(rootDir, dirs) {
+    const byHost = new Map();
+    const record = (rawUrl, relPath) => {
+        let host;
+        try {
+            host = new URL(rawUrl).hostname;
+        }
+        catch {
+            return;
+        }
+        if (!host || INTERNAL_HOSTS.test(host)) {
+            return;
+        }
+        const bucket = byHost.get(host) ?? { files: new Set(), count: 0 };
+        bucket.files.add(relPath);
+        bucket.count += 1;
+        byHost.set(host, bucket);
+    };
+    for (const dir of dirs) {
+        for (const file of collectAllScriptFiles(join(rootDir, dir))) {
+            let code;
+            try {
+                code = readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const plainScript = /\.(ts|js|mjs)$/.test(file);
+            if (!code.includes('fetch(') && !(plainScript && /https?:\/\//.test(code))) {
+                continue;
+            }
+            const relPath = relative(rootDir, file);
+            let ast;
+            try {
+                ast = parseSync(file, code).program;
+            }
+            catch {
+                continue;
+            }
+            const walk = (node) => {
+                if (!node || typeof node !== 'object') {
+                    return;
+                }
+                if (node.type === 'CallExpression') {
+                    const callee = node.callee;
+                    const isFetch = (callee?.type === 'Identifier' && callee.name === 'fetch') ||
+                        (callee?.type === 'MemberExpression' && callee.property?.name === 'fetch');
+                    if (isFetch) {
+                        const arg = node.arguments?.[0];
+                        if (arg?.type === 'Literal' && typeof arg.value === 'string' && /^https?:\/\//.test(arg.value)) {
+                            record(arg.value, relPath);
+                        }
+                        else if (arg?.type === 'TemplateLiteral') {
+                            const head = arg.quasis?.[0]?.value?.cooked ?? '';
+                            if (/^https?:\/\//.test(head)) {
+                                record(head, relPath);
+                            }
+                        }
+                        else if (arg?.type === 'NewExpression' && arg.callee?.name === 'URL') {
+                            const urlArg = arg.arguments?.[0];
+                            if (urlArg?.type === 'Literal' && typeof urlArg.value === 'string' && /^https?:\/\//.test(urlArg.value)) {
+                                record(urlArg.value, relPath);
+                            }
+                        }
+                    }
+                }
+                // API base URLs typically live as constants in plain .ts/.js helper
+                // files, separate from the fetch call itself (hackernews dogfood).
+                // Template/component files are excluded: their URL literals are links.
+                if (plainScript &&
+                    node.type === 'VariableDeclarator' &&
+                    node.init?.type === 'Literal' &&
+                    typeof node.init.value === 'string' &&
+                    /^https?:\/\//.test(node.init.value)) {
+                    record(node.init.value, relPath);
+                }
+                for (const key of Object.keys(node)) {
+                    const child = node[key];
+                    if (Array.isArray(child)) {
+                        for (const item of child) {
+                            walk(item);
+                        }
+                    }
+                    else if (typeof child === 'object' && child !== null) {
+                        walk(child);
+                    }
+                }
+            };
+            walk(ast);
+        }
+    }
+    const sources = [...byHost.entries()].map(([host, bucket]) => ({
+        host,
+        files: [...bucket.files].sort(),
+        count: bucket.count,
+        kind: 'api',
+    }));
+    // Headless-CMS SDK clients never show up as fetch(url) literals — detect
+    // them from package.json. For these, the site's content LIVES in the CMS.
+    const CMS_SDKS = [
+        ['basehub', 'BaseHub'],
+        ['contentful', 'Contentful'],
+        ['@sanity/client', 'Sanity'],
+        ['next-sanity', 'Sanity'],
+        ['@prismicio/client', 'Prismic'],
+        ['@datocms/cma-client', 'DatoCMS'],
+        ['react-datocms', 'DatoCMS'],
+        ['@storyblok/react', 'Storyblok'],
+        ['storyblok-js-client', 'Storyblok'],
+        ['payload', 'Payload'],
+        ['@hygraph/management-sdk', 'Hygraph'],
+    ];
+    try {
+        const pkg = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        const seen = new Set();
+        for (const [dep, name] of CMS_SDKS) {
+            if (!name || !deps[dep] || seen.has(name)) {
+                continue;
+            }
+            seen.add(name);
+            sources.push({ host: name, files: ['package.json'], count: 1, kind: 'cms' });
+        }
+    }
+    catch {
+        // no package.json — nothing to add
+    }
+    return sources.sort((a, b) => a.host.localeCompare(b.host));
+}
+/**
+ * Scan a project's source directories for unwrapped content. `dirs` defaults
+ * to the common Next/React layouts that exist under `rootDir`.
+ */
+export function scanWrappable(rootDir, opts = {}) {
+    const dirs = (opts.dirs ?? ['app', 'src', 'pages', 'components']).filter((dir) => existsSync(join(rootDir, dir)));
+    const excluded = (opts.excludePrefixes ?? []).map((prefix) => prefix.replace(/\/+$/, ''));
+    const files = new Set();
+    for (const dir of dirs) {
+        for (const file of collectSourceFiles(join(rootDir, dir))) {
+            const rel = relative(rootDir, file);
+            if (excluded.some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`))) {
+                continue;
+            }
+            files.add(file);
+        }
+    }
+    const items = [];
+    const collections = [];
+    let wrappedCount = 0;
+    let foreignI18nCount = 0;
+    const idSets = {
+        labels: new Set(),
+        media: new Set(),
+        richText: new Set(),
+        files: new Set(),
+    };
+    const orderedIds = [];
+    const orderedSeen = new Set();
+    for (const file of files) {
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const result = scanWrappableFile(file, code, relative(rootDir, file), {
+            i18nFimoWired: opts.i18nFimoWired,
+        });
+        items.push(...result.items);
+        collections.push(...result.collections);
+        wrappedCount += result.wrapped;
+        foreignI18nCount += result.foreignI18n ?? 0;
+        for (const kind of ['labels', 'media', 'richText', 'files']) {
+            for (const id of result.wrappedIds[kind]) {
+                idSets[kind].add(id);
+            }
+        }
+        for (const id of result.wrappedIds.ordered) {
+            if (!orderedSeen.has(id)) {
+                orderedSeen.add(id);
+                orderedIds.push(id);
+            }
+        }
+    }
+    const dataFiles = [];
+    // Markdown/MDX documents: group per directory so a 40-post blog is ONE
+    // triage decision, not forty. A directory holding ≥2 content docs is a
+    // group; the per-doc rows are parsed once by markdownGroupCollection.
+    const markdownDirs = new Set();
+    const collectMarkdown = (dir) => {
+        if (!existsSync(dir)) {
+            return;
+        }
+        let hasContentDoc = false;
+        for (const entry of readdirSync(dir)) {
+            if (SKIP_DIRS.has(entry)) {
+                continue;
+            }
+            const full = join(dir, entry);
+            let stats;
+            try {
+                stats = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stats.isDirectory()) {
+                collectMarkdown(full);
+            }
+            else if (/\.(md|mdx)$/.test(entry) &&
+                !/^(readme|changelog|license|contributing|agents|claude)\.md$/i.test(entry)) {
+                hasContentDoc = true;
+            }
+        }
+        if (hasContentDoc) {
+            markdownDirs.add(relative(rootDir, dir) || '.');
+        }
+    };
+    // Frameworks may keep page copy outside the source roots — those extra
+    // directories come from the framework registry (frameworks/discover.ts),
+    // never from names hardcoded here.
+    const dataDirs = [...dirs, ...(opts.dataDirs ?? []).filter((dir) => existsSync(join(rootDir, dir)))];
+    for (const dir of dataDirs) {
+        for (const file of collectDataFiles(join(rootDir, dir))) {
+            const rel = relative(rootDir, file);
+            if (excluded.some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`))) {
+                continue;
+            }
+            try {
+                const detected = scanDataJson(rel, readFileSync(file, 'utf8'));
+                if (detected) {
+                    dataFiles.push(detected);
+                }
+            }
+            catch {
+                // unreadable data file: not copy we can act on
+            }
+        }
+    }
+    for (const dir of dataDirs) {
+        collectMarkdown(join(rootDir, dir));
+    }
+    for (const groupKey of [...markdownDirs].sort()) {
+        const rows = readMarkdownGroupRows(join(rootDir, groupKey));
+        if (rows.length === 0) {
+            continue;
+        }
+        // A same-shaped group of ≥2 docs becomes a stageable collection (schema
+        // draft + rows), exactly like a JSON data file; a ragged or single-doc
+        // group stays a bare markdown triage item for the agent to decide.
+        const name = groupKey.split('/').filter(Boolean).pop() ?? 'content';
+        const collection = markdownGroupCollection(name, rows);
+        const samples = rows
+            .map((row) => (typeof row.body === 'string' ? toPreview(row.body) : ''))
+            .filter(Boolean)
+            .slice(0, 2);
+        dataFiles.push({
+            file: `${groupKey}/*.md`,
+            strings: rows.length,
+            samples,
+            collections: collection ? [collection] : [],
+            kind: 'markdown',
+            count: rows.length,
+        });
+    }
+    dataFiles.sort((a, b) => a.file.localeCompare(b.file));
+    items.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    collections.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    // Cross-candidate reference detection in ONE unified pass: in-code
+    // candidates AND data-file collections all match against each other —
+    // posts.json pointing at authors.json (the most common real-world shape)
+    // is a reference like any other. Data-file matchables are named like the
+    // schema drafts name them (json path, else the file stem) so annotations,
+    // drafts, and staged rows stay in one namespace. The raw value sets are
+    // internal — strip them once annotated.
+    const dataFileMatchables = dataFiles.flatMap((dataFile) => dataFile.collections.map((collection) => {
+        const stem = dataFile.file.replace(/^.*\//, '').replace(/\.[a-z]+$/i, '');
+        const pathName = (collection.path ?? '').replace(/^\$\.?/, '').replace(/^\.+$/, '');
+        return {
+            collection,
+            matchable: {
+                name: pathName || stem,
+                fieldValues: collection.fieldValues,
+                manyFields: collection.manyFields,
+            },
+        };
+    }));
+    annotateCandidateReferences([...collections, ...dataFileMatchables.map((entry) => entry.matchable)]);
+    for (const entry of dataFileMatchables) {
+        if (entry.matchable.references) {
+            entry.collection.references = entry.matchable.references;
+        }
+    }
+    if (!opts.keepInternal) {
+        for (const candidate of collections) {
+            delete candidate.fieldValues;
+            delete candidate.typedSample;
+            delete candidate.manyFields;
+        }
+        for (const dataFile of dataFiles) {
+            for (const collection of dataFile.collections) {
+                delete collection.fieldValues;
+                delete collection.typedSample;
+                delete collection.typedRows;
+                delete collection.manyFields;
+                delete collection.verbatimFields;
+            }
+        }
+    }
+    return {
+        items,
+        collections,
+        dataFiles,
+        // Live data sources often sit in backend/helper roots (server routes,
+        // shared utils) rather than page roots — sweep those too.
+        externalSources: scanExternalSources(rootDir, [...new Set([...dirs, 'server', 'utils', 'lib'])].filter((dir) => existsSync(join(rootDir, dir)))),
+        wrappedCount,
+        foreignI18nCount,
+        filesScanned: files.size,
+        wrappedIds: {
+            labels: [...idSets.labels].sort(),
+            media: [...idSets.media].sort(),
+            richText: [...idSets.richText].sort(),
+            files: [...idSets.files].sort(),
+            // Encounter order, never sorted — the on-page reading order.
+            ordered: orderedIds,
+        },
+    };
+}