@contentbit/core 0.1.0 → 0.3.0

package/dist/analyze.d.ts

@@ -0,0 +1,87 @@
+export interface OutlineEntry {
+    /** ATX heading level, 1-6. */
+    level: number;
+    text: string;
+    /** 1-based source line. */
+    line: number;
+    /** Prose words from this heading (inclusive) until the next heading of any level. */
+    words: number;
+}
+export interface BlockInstance {
+    name: string;
+    /** 1-based line of the opening fence. */
+    line: number;
+    /** 1 for top-level blocks, +1 per nesting level. */
+    depth: number;
+}
+export interface LinkItem {
+    url: string;
+    text: string;
+    line: number;
+    external: boolean;
+}
+export interface DocumentStats {
+    file: {
+        path: string | null;
+        bytes: number;
+        lines: number;
+    };
+    frontmatter: {
+        present: boolean;
+        keys: string[];
+        data: Record<string, unknown>;
+        lines: {
+            start: number;
+            end: number;
+        } | null;
+    };
+    length: {
+        /** Prose words only: frontmatter, code, and markup syntax are excluded. */
+        words: number;
+        /** Characters of the full source, frontmatter included. */
+        characters: number;
+        /** ceil(words / 200). */
+        readingMinutes: number;
+        /** Rough heuristic: ceil(characters / 4). */
+        approxTokens: number;
+    };
+    outline: OutlineEntry[];
+    blocks: {
+        total: number;
+        byName: Record<string, number>;
+        maxDepth: number;
+        instances: BlockInstance[];
+    };
+    links: {
+        total: number;
+        external: number;
+        internal: number;
+        domains: string[];
+        items: LinkItem[];
+    };
+    images: {
+        total: number;
+        missingAlt: number;
+    };
+    code: {
+        fences: number;
+        languages: string[];
+        inlineSpans: number;
+    };
+    structure: {
+        listItems: number;
+        tables: number;
+        blockquotes: number;
+    };
+}
+export interface AnalyzeOptions {
+    /** Reported back in `file.path`; analyze never touches the filesystem. */
+    path?: string;
+}
+/**
+ * Scan a document and return structured stats: prose length, heading outline,
+ * block census, links, images, code, and structure counts. Purely syntactic
+ * and deterministic — no registry, no validation, no filesystem access.
+ */
+export declare function analyzeDocument(source: string, options?: AnalyzeOptions): DocumentStats;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3D,WAAW,EAAE;QACX,OAAO,EAAE,OAAO,CAAA;QAChB,IAAI,EAAE,MAAM,EAAE,CAAA;QACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC7B,KAAK,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAC7C,CAAA;IACD,MAAM,EAAE;QACN,2EAA2E;QAC3E,KAAK,EAAE,MAAM,CAAA;QACb,2DAA2D;QAC3D,UAAU,EAAE,MAAM,CAAA;QAClB,yBAAyB;QACzB,cAAc,EAAE,MAAM,CAAA;QACtB,6CAA6C;QAC7C,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,aAAa,EAAE,CAAA;KAC3B,CAAA;IACD,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,EAAE,CAAA;QACjB,KAAK,EAAE,QAAQ,EAAE,CAAA;KAClB,CAAA;IACD,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7C,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IAClE,SAAS,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CACtE;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAsBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CA4L3F"}

package/dist/analyze.js

@@ -0,0 +1,204 @@
+import { extractFrontmatter, stripFrontmatter } from './frontmatter.js';
+import { parseDocument } from './parser.js';
+/** UTF-8 byte length without Node Buffer or TextEncoder (core is environment-agnostic). */
+function utf8Length(source) {
+    let bytes = 0;
+    for (const ch of source) {
+        const cp = ch.codePointAt(0);
+        bytes += cp <= 0x7f ? 1 : cp <= 0x7ff ? 2 : cp <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+const CODE_FENCE_RE = /^(`{3,}|~{3,})(.*)$/;
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+const LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s+/;
+const TABLE_SEPARATOR_RE = /^\|?[\s:|-]+$/;
+const CODE_SPAN_RE = /`[^`]+`/g;
+const IMAGE_RE = /!\[([^\]]*)\]\(([^)]*)\)/g;
+const LINK_RE = /\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const AUTOLINK_RE = /<(https?:\/\/[^>\s]+)>/g;
+const EXTERNAL_URL_RE = /^(?:https?:)?\/\//i;
+/**
+ * Scan a document and return structured stats: prose length, heading outline,
+ * block census, links, images, code, and structure counts. Purely syntactic
+ * and deterministic — no registry, no validation, no filesystem access.
+ */
+export function analyzeDocument(source, options = {}) {
+    const frontmatter = extractFrontmatter(source);
+    const { document } = parseDocument(stripFrontmatter(source));
+    const outline = [];
+    const blocks = { total: 0, byName: {}, maxDepth: 0, instances: [] };
+    const links = {
+        total: 0,
+        external: 0,
+        internal: 0,
+        domains: [],
+        items: [],
+    };
+    const images = { total: 0, missingAlt: 0 };
+    const code = { fences: 0, languages: [], inlineSpans: 0 };
+    const structure = { listItems: 0, tables: 0, blockquotes: 0 };
+    const languages = new Set();
+    const domains = new Set();
+    let words = 0;
+    function addWords(count) {
+        words += count;
+        const section = outline[outline.length - 1];
+        if (section)
+            section.words += count;
+    }
+    function recordLink(url, text, line) {
+        const external = EXTERNAL_URL_RE.test(url);
+        links.total++;
+        if (external) {
+            links.external++;
+            const host = url.match(/^(?:https?:)?\/\/(?:[^/?#@]*@)?([^/?#:]+)/i);
+            if (host)
+                domains.add(host[1].toLowerCase());
+        }
+        else {
+            links.internal++;
+        }
+        links.items.push({ url, text, line, external });
+    }
+    /** Replace inline markup with its prose equivalent, recording links/images/spans. */
+    function inlineToProse(text, line) {
+        return text
+            .replace(CODE_SPAN_RE, () => {
+            code.inlineSpans++;
+            return ' ';
+        })
+            .replace(IMAGE_RE, (_, alt) => {
+            images.total++;
+            if (alt.trim() === '')
+                images.missingAlt++;
+            return ' ';
+        })
+            .replace(LINK_RE, (_, label, url) => {
+            recordLink(url, label, line);
+            return label;
+        })
+            .replace(AUTOLINK_RE, (_, url) => {
+            recordLink(url, url, line);
+            return ' ';
+        });
+    }
+    function countWords(text) {
+        return text.split(/\s+/).filter((token) => /[\p{L}\p{N}]/u.test(token)).length;
+    }
+    function scanMarkdown(value, startLine) {
+        let fence = null;
+        let inBlockquote = false;
+        let prevLineHasPipe = false;
+        const lines = value.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineNo = startLine + i;
+            const trimmed = line.trim();
+            const fenceMatch = trimmed.match(CODE_FENCE_RE);
+            if (fence !== null) {
+                if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length) {
+                    fence = null;
+                }
+                continue;
+            }
+            if (fenceMatch) {
+                fence = fenceMatch[1];
+                code.fences++;
+                const lang = fenceMatch[2].trim().split(/\s+/)[0];
+                if (lang)
+                    languages.add(lang);
+                inBlockquote = false;
+                prevLineHasPipe = false;
+                continue;
+            }
+            if (trimmed === '') {
+                inBlockquote = false;
+                prevLineHasPipe = false;
+                continue;
+            }
+            const heading = trimmed.match(HEADING_RE);
+            if (heading) {
+                const raw = heading[2].replace(/\s+#+\s*$/, '');
+                const text = inlineToProse(raw, lineNo).replace(/\s+/g, ' ').trim();
+                outline.push({ level: heading[1].length, text, line: lineNo, words: 0 });
+                addWords(countWords(text));
+                inBlockquote = false;
+                prevLineHasPipe = false;
+                continue;
+            }
+            let content = trimmed;
+            if (content.startsWith('>')) {
+                if (!inBlockquote) {
+                    structure.blockquotes++;
+                    inBlockquote = true;
+                }
+                content = content.replace(/^(>\s*)+/, '');
+            }
+            else {
+                inBlockquote = false;
+            }
+            if (LIST_ITEM_RE.test(content)) {
+                structure.listItems++;
+                content = content.replace(LIST_ITEM_RE, '');
+            }
+            if (content.includes('|')) {
+                if (TABLE_SEPARATOR_RE.test(content) && content.includes('-') && prevLineHasPipe) {
+                    structure.tables++;
+                }
+                prevLineHasPipe = true;
+                content = inlineToProse(content, lineNo).replaceAll('|', ' ');
+            }
+            else {
+                prevLineHasPipe = false;
+                content = inlineToProse(content, lineNo);
+            }
+            addWords(countWords(content));
+        }
+    }
+    function walk(nodes, depth) {
+        for (const node of nodes) {
+            if (node.type === 'block') {
+                blocks.total++;
+                blocks.byName[node.name] = (blocks.byName[node.name] ?? 0) + 1;
+                blocks.maxDepth = Math.max(blocks.maxDepth, depth);
+                blocks.instances.push({ name: node.name, line: node.openPosition.start.line, depth });
+                walk(node.children, depth + 1);
+            }
+            else {
+                scanMarkdown(node.value, node.position.start.line);
+            }
+        }
+    }
+    walk(document.children, 1);
+    code.languages = [...languages];
+    links.domains = [...domains].sort();
+    const sourceLines = source === '' ? 0 : source.split('\n').length - (source.endsWith('\n') ? 1 : 0);
+    return {
+        file: {
+            path: options.path ?? null,
+            bytes: utf8Length(source),
+            lines: sourceLines,
+        },
+        frontmatter: frontmatter
+            ? {
+                present: true,
+                keys: frontmatter.keys,
+                data: frontmatter.data,
+                lines: frontmatter.lines,
+            }
+            : { present: false, keys: [], data: {}, lines: null },
+        length: {
+            words,
+            characters: source.length,
+            readingMinutes: Math.ceil(words / 200),
+            approxTokens: Math.ceil(source.length / 4),
+        },
+        outline,
+        blocks,
+        links,
+        images,
+        code,
+        structure,
+    };
+}

package/dist/authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAWD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,EAChC,IAAI,GAAE,qBAA0B,GAC/B,MAAM,CA0BR"}
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAkEpD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAWD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,EAChC,IAAI,GAAE,qBAA0B,GAC/B,MAAM,CA8BR"}

package/dist/authoring.js

@@ -1,3 +1,50 @@
+function typeLabel(def) {
+    switch (def.type) {
+        case 'enum':
+            return `one of ${Object.values(def.entries ?? {}).join('|')}`;
+        case 'literal':
+            return `one of ${(def.values ?? []).map(String).join('|')}`;
+        case 'union':
+            return `one of ${(def.options ?? [])
+                .map((o) => typeLabel(o.def).replace(/^one of /, ''))
+                .join('|')}`;
+        default:
+            return def.type;
+    }
+}
+/** One `- name: type (required|optional[, default: x]) [— description]` line per prop. */
+function describeProps(schema) {
+    const root = schema.def;
+    if (root.type !== 'object' || !root.shape)
+        return [];
+    const lines = [];
+    for (const [name, field] of Object.entries(root.shape)) {
+        // Unwrap optional/default/nullable wrappers; .describe() may sit on any layer.
+        let current = field;
+        let optional = false;
+        let defaultValue;
+        let description = current.description;
+        while (['optional', 'default', 'nullable'].includes(current.def.type)) {
+            optional = true;
+            if (current.def.type === 'default') {
+                const dv = current.def.defaultValue;
+                defaultValue = typeof dv === 'function' ? dv() : dv;
+            }
+            if (!current.def.innerType)
+                break;
+            current = current.def.innerType;
+            description ??= current.description;
+        }
+        const presence = defaultValue !== undefined
+            ? `(optional, default: ${String(defaultValue)})`
+            : optional
+                ? '(optional)'
+                : '(required)';
+        const suffix = description ? ` — ${description}` : '';
+        lines.push(`- ${name}: ${typeLabel(current.def)} ${presence}${suffix}`);
+    }
+    return lines;
+}
 const LLM_PREAMBLE = `# Content block authoring rules
 
 - write regular Markdown by default; use blocks only when they improve scanning or structure
@@ -17,6 +64,11 @@ export function generateAuthoringGuide(defs, opts = {}) {
         lines.push(def.childOnly
             ? `${def.description} (child block — only inside a parent that allows it)`
             : def.description);
+        if (def.props) {
+            const props = describeProps(def.props);
+            if (props.length > 0)
+                lines.push('', 'Props:', ...props);
+        }
         lines.push('', `Content: ${def.content.describe()}`);
         if (def.authoring.useWhen.length > 0) {
             lines.push('', 'Use when:', ...def.authoring.useWhen.map((u) => `- ${u}`));

package/dist/frontmatter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Blank out a leading YAML frontmatter block so block syntax inside it is
+ * never parsed as content. Every line is replaced by an empty line (the
+ * newlines stay), so diagnostic positions in the remaining document are
+ * unchanged. Sources without frontmatter are returned as-is.
+ */
+export declare function stripFrontmatter(source: string): string;
+export interface Frontmatter {
+    /** Raw YAML between the fences (fences excluded). */
+    raw: string;
+    /** Best-effort parsed data; values the subset parser can't handle stay raw strings. */
+    data: Record<string, unknown>;
+    /** Top-level keys in document order. */
+    keys: string[];
+    /** 1-based fence lines, inclusive. */
+    lines: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * Extract and parse a leading YAML frontmatter block. Parsing covers the flat
+ * subset real content frontmatter uses: `key: value` scalars (quoted/plain
+ * strings, numbers, booleans, null), inline arrays, dash lists, and block
+ * scalars. Nested mappings and anything else fall back to the raw text of the
+ * value, so no input ever throws. Returns null when there is no frontmatter.
+ */
+export declare function extractFrontmatter(source: string): Frontmatter | null;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IACX,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,wCAAwC;IACxC,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,sCAAsC;IACtC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAOrE"}

package/dist/frontmatter.js

@@ -0,0 +1,202 @@
+// A YAML frontmatter block at the very start of the file: an opening ---
+// fence, an optional body (empty frontmatter is legal), and a closing ---
+// fence. Both fences tolerate trailing spaces/tabs, which editors and CMS
+// exports routinely leave behind.
+const FM_RE = /^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/;
+/**
+ * Blank out a leading YAML frontmatter block so block syntax inside it is
+ * never parsed as content. Every line is replaced by an empty line (the
+ * newlines stay), so diagnostic positions in the remaining document are
+ * unchanged. Sources without frontmatter are returned as-is.
+ */
+export function stripFrontmatter(source) {
+    const match = FM_RE.exec(source);
+    if (!match)
+        return source;
+    return match[0].replace(/[^\n]+/g, '') + source.slice(match[0].length);
+}
+/**
+ * Extract and parse a leading YAML frontmatter block. Parsing covers the flat
+ * subset real content frontmatter uses: `key: value` scalars (quoted/plain
+ * strings, numbers, booleans, null), inline arrays, dash lists, and block
+ * scalars. Nested mappings and anything else fall back to the raw text of the
+ * value, so no input ever throws. Returns null when there is no frontmatter.
+ */
+export function extractFrontmatter(source) {
+    const match = source.match(FM_RE);
+    if (!match)
+        return null;
+    const blockLines = match[0].replace(/\r?\n$/, '').split(/\r?\n/);
+    const inner = blockLines.slice(1, -1);
+    const { data, keys } = parseYamlSubset(inner);
+    return { raw: inner.join('\n'), data, keys, lines: { start: 1, end: blockLines.length } };
+}
+const KEY_RE = /^([A-Za-z0-9_.-]+):(.*)$/;
+function parseYamlSubset(lines) {
+    const data = {};
+    const keys = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#') || /^[ \t]/.test(line)) {
+            i++;
+            continue;
+        }
+        const m = line.match(KEY_RE);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const [, key, rawValue] = m;
+        const value = rawValue.trim();
+        i++;
+        const indented = [];
+        while (i < lines.length && /^[ \t]/.test(lines[i]) && lines[i].trim() !== '') {
+            indented.push(lines[i]);
+            i++;
+        }
+        keys.push(key);
+        data[key] = parseValue(value, indented);
+    }
+    return { data, keys };
+}
+function parseValue(value, indented) {
+    if (/^[|>][+-]?$/.test(value))
+        return dedent(indented).join('\n');
+    if (value === '') {
+        if (indented.length === 0)
+            return null;
+        const items = dedent(indented);
+        const list = parseDashList(items);
+        if (list)
+            return list;
+        const mapping = parseNestedMapping(items);
+        if (mapping)
+            return mapping;
+        return items.join('\n');
+    }
+    return parseScalar(value);
+}
+// A one-level mapping: every dedented line is `key: scalar` (or `key:` with an
+// inline array value). Returns null if any line isn't a flat mapping entry —
+// e.g. a deeper-indented line or a `key:` with no inline value, which would
+// need its own nested block — so the caller keeps the raw-text fallback.
+function parseNestedMapping(items) {
+    const out = {};
+    for (const line of items) {
+        if (/^[ \t]/.test(line))
+            return null;
+        const m = line.match(KEY_RE);
+        if (!m)
+            return null;
+        const [, key, rawValue] = m;
+        const v = rawValue.trim();
+        if (v === '')
+            return null;
+        out[key] = parseScalar(v);
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
+function parseDashList(items) {
+    const groups = [];
+    let current = null;
+    for (const line of items) {
+        if (line.startsWith('- ')) {
+            if (current)
+                groups.push(current);
+            current = [line.slice(2)];
+        }
+        else if (current && /^[ \t]/.test(line)) {
+            current.push(line);
+        }
+        else {
+            return null;
+        }
+    }
+    if (current)
+        groups.push(current);
+    return groups.map((group) => parseDashItem(group));
+}
+function parseDashItem(lines) {
+    const first = lines[0].trim();
+    if (lines.length === 1)
+        return parseNestedMapping([first]) ?? parseScalar(first);
+    const rest = dedent(lines.slice(1));
+    const mapping = parseNestedMapping([first, ...rest]);
+    return mapping ?? lines.join('\n');
+}
+function dedent(lines) {
+    const indent = Math.min(...lines.map((l) => l.match(/^[ \t]*/)[0].length));
+    return lines.map((l) => l.slice(indent));
+}
+function parseScalar(value) {
+    if (value === '' || value === 'null' || value === '~')
+        return null;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (/^[+-]?\d+$/.test(value))
+        return Number.parseInt(value, 10);
+    if (/^[+-]?\d*\.\d+$/.test(value))
+        return Number.parseFloat(value);
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+        return value.slice(1, -1).replace(/''/g, "'");
+    }
+    if (value.startsWith('[') && value.endsWith(']')) {
+        const inner = value.slice(1, -1).trim();
+        if (inner === '')
+            return [];
+        return splitInlineItems(inner).map((item) => parseScalar(item.trim()));
+    }
+    if (value.startsWith('{') && value.endsWith('}')) {
+        const inner = value.slice(1, -1).trim();
+        if (inner === '')
+            return {};
+        const out = {};
+        for (const item of splitInlineItems(inner)) {
+            const m = item.trim().match(KEY_RE);
+            if (!m)
+                return value;
+            const [, key, rawValue] = m;
+            out[key] = parseScalar(rawValue.trim());
+        }
+        return out;
+    }
+    return value;
+}
+/** Split inline array items on top-level commas, respecting quotes. */
+function splitInlineItems(inner) {
+    const items = [];
+    let current = '';
+    let quote = null;
+    for (const ch of inner) {
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            current += ch;
+            quote = ch;
+        }
+        else if (ch === ',') {
+            items.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    items.push(current);
+    return items;
+}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export type { SourcePoint, SourceRange, Severity, Diagnostic } from './diagnosti
 export { formatDiagnostic } from './diagnostics.js';
 export type { DocumentNode, ContentNode, MarkdownNode, BlockNode } from './ast.js';
 export { parseDocument, type ParseResult } from './parser.js';
+export { stripFrontmatter, extractFrontmatter, type Frontmatter } from './frontmatter.js';
+export { analyzeDocument, type AnalyzeOptions, type DocumentStats, type OutlineEntry, type BlockInstance, type LinkItem, } from './analyze.js';
 export { parseProps } from './props.js';
 export { bodyLineRange } from './position.js';
 export { createBlockRegistry, defineBlock, BlockRegistry, type BlockDefinition, type ContentModel, type AuthoringMeta, type Report, } from './registry.js';
@@ -10,4 +12,5 @@ export { markdownBody, pipeRows, listItems, childBlocks, type MarkdownBodyData,
 export { validateDocument, isValidatedBlock, type ValidateOptions, type ValidationResult, type ValidatedBlockNode, } from './validate.js';
 export { generateAuthoringGuide, type AuthoringGuideOptions } from './authoring.js';
 export { renderToMarkdown, type MarkdownBlockRenderer, type MarkdownRenderContext, type RenderToMarkdownOptions, } from './render-markdown.js';
+export { parseLinkFrontmatter, buildLinkIndex, validateLinks, serializeLinkIndex, aliasReplacementsForPage, type LinkResolveMode, type LinkResolverOptions, type LinkTarget, type LinkFrontmatter, type ParseLinkResult, type LinkReference, type IndexedPage, type LinkAliasEntry, type LinkIndex, type LinkInput, type LinkDiagnostic, type SerializedLinkIndex, } from './links.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAClF,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,GACZ,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACnF,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAClF,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACzF,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,GACZ,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACnF,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,6 +1,8 @@
 export { VERSION } from './version.js';
 export { formatDiagnostic } from './diagnostics.js';
 export { parseDocument } from './parser.js';
+export { stripFrontmatter, extractFrontmatter } from './frontmatter.js';
+export { analyzeDocument, } from './analyze.js';
 export { parseProps } from './props.js';
 export { bodyLineRange } from './position.js';
 export { createBlockRegistry, defineBlock, BlockRegistry, } from './registry.js';
@@ -8,3 +10,4 @@ export { markdownBody, pipeRows, listItems, childBlocks, } from './content-model
 export { validateDocument, isValidatedBlock, } from './validate.js';
 export { generateAuthoringGuide } from './authoring.js';
 export { renderToMarkdown, } from './render-markdown.js';
+export { parseLinkFrontmatter, buildLinkIndex, validateLinks, serializeLinkIndex, aliasReplacementsForPage, } from './links.js';

package/dist/links.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import type { Diagnostic } from './diagnostics.js';
+declare const LinkTarget: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+declare const LinkFrontmatter: z.ZodObject<{
+    slug: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    linksTo: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    keywords: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodOptional<z.ZodString>;
+        secondary: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LinkTarget = z.infer<typeof LinkTarget>;
+export type LinkFrontmatter = z.infer<typeof LinkFrontmatter>;
+export type LinkResolveMode = 'global-slug' | 'same-locale-slug' | 'same-locale-key' | 'prefer-same-locale-key-fallback-slug';
+export interface LinkResolverOptions {
+    resolve?: LinkResolveMode;
+    localeField?: string;
+    slugField?: string;
+    keyField?: string;
+    defaultLocale?: string;
+}
+export type ParseLinkResult = {
+    ok: true;
+    value: LinkFrontmatter | null;
+} | {
+    ok: false;
+    errors: string[];
+};
+export interface LinkReference {
+    target?: string;
+    locale?: string;
+    slug: string;
+    key?: string;
+}
+export interface IndexedPage {
+    slug: string;
+    key?: string;
+    locale?: string;
+    path: string;
+    title?: string;
+    keywords?: {
+        primary?: string;
+        secondary?: string[];
+    };
+    linksTo: string[];
+    linkedFrom: string[];
+    aliases: string[];
+    linkRefs: LinkReference[];
+    linkedFromRefs: LinkReference[];
+}
+export interface LinkAliasEntry {
+    alias: string;
+    locale?: string;
+    replacement: string;
+    page: IndexedPage;
+}
+export interface LinkIndex {
+    pages: Map<string, IndexedPage>;
+    aliases: Map<string, string>;
+    aliasEntries: LinkAliasEntry[];
+    options: Required<Pick<LinkResolverOptions, 'resolve'>> & Omit<LinkResolverOptions, 'resolve'>;
+}
+export interface LinkInput {
+    path: string;
+    data: Record<string, unknown>;
+}
+export interface SerializedLinkIndex {
+    pages: Array<Omit<IndexedPage, 'linkRefs' | 'linkedFromRefs' | 'linksTo' | 'linkedFrom'> & {
+        linksTo: string[] | LinkReference[];
+        linkedFrom: string[] | LinkReference[];
+    }>;
+    aliases: Record<string, string | LinkReference>;
+}
+export interface LinkDiagnostic {
+    file: string;
+    diagnostic: Diagnostic;
+}
+export declare function parseLinkFrontmatter(data: Record<string, unknown>, options?: LinkResolverOptions): ParseLinkResult;
+export declare function buildLinkIndex(inputs: LinkInput[], options?: LinkResolverOptions): LinkIndex;
+export declare function serializeLinkIndex(index: LinkIndex): SerializedLinkIndex;
+export declare function aliasReplacementsForPage(index: LinkIndex, data: Record<string, unknown>): Map<string, string>;
+export declare function validateLinks(inputs: LinkInput[], options?: LinkResolverOptions): LinkDiagnostic[];
+export {};
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,kBAAkB,CAAA;AAO/D,QAAA,MAAM,UAAU;;;;mBAWd,CAAA;AAEF,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;iBAQnB,CAAA;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AACnD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,kBAAkB,GAClB,iBAAiB,GACjB,sCAAsC,CAAA;AAE1C,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,GAC3C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEnC,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IACrD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,QAAQ,EAAE,aAAa,EAAE,CAAA;IACzB,cAAc,EAAE,aAAa,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,WAAW,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,YAAY,EAAE,cAAc,EAAE,CAAA;IAC9B,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAA;CAC/F;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CACV,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,gBAAgB,GAAG,SAAS,GAAG,YAAY,CAAC,GAAG;QAC5E,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAAA;QACnC,UAAU,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAAA;KACvC,CACF,CAAA;IACD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,CAAA;CAChD;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;CACvB;AAsBD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,GAAE,mBAAwB,GAChC,eAAe,CAMjB;AAKD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,SAAS,CA4DhG;AAKD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,mBAAmB,CA6BxE;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAWrB;AAMD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,GAAE,mBAAwB,GAChC,cAAc,EAAE,CA0HlB"}

package/dist/links.js

@@ -0,0 +1,435 @@
+import { z } from 'zod';
+const Keywords = z.object({
+    primary: z.string().optional(),
+    secondary: z.array(z.string()).optional(),
+});
+const LinkTarget = z.union([
+    z.string(),
+    z
+        .object({
+        slug: z.string().min(1).optional(),
+        key: z.string().min(1).optional(),
+        locale: z.string().min(1).optional(),
+    })
+        .refine((target) => target.slug || target.key, {
+        message: 'object linksTo targets must include slug or key',
+    }),
+]);
+const LinkFrontmatter = z.object({
+    slug: z.string().min(1),
+    key: z.string().min(1).optional(),
+    locale: z.string().min(1).optional(),
+    title: z.string().optional(),
+    linksTo: z.array(LinkTarget).optional(),
+    aliases: z.array(z.string()).optional(),
+    keywords: Keywords.optional(),
+});
+const DEFAULT_OPTIONS = {
+    resolve: 'global-slug',
+};
+const FM_POSITION = {
+    start: { line: 1, column: 1, offset: 0 },
+    end: { line: 1, column: 1, offset: 0 },
+};
+// Returns { value: null } when there is no `slug` (a non-participating page),
+// parsed data when the link shape is valid, or shape errors otherwise. Never
+// throws — callers turn errors into diagnostics.
+export function parseLinkFrontmatter(data, options = {}) {
+    const normalized = normalizeFrontmatter(data, options);
+    if (!('slug' in normalized))
+        return { ok: true, value: null };
+    const parsed = LinkFrontmatter.safeParse(normalized);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    return { ok: false, errors: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`) };
+}
+// Pure: builds the resolved link graph from per-file frontmatter data. Pass 1
+// collects pages and registers aliases; pass 2 resolves each linksTo through
+// the configured identity maps and inverts edges to derive linkedFrom.
+export function buildLinkIndex(inputs, options = {}) {
+    const resolvedOptions = { ...DEFAULT_OPTIONS, ...options };
+    const pages = new Map();
+    const aliases = new Map();
+    const aliasEntries = [];
+    for (const { path, data } of inputs) {
+        const parsed = parseLinkFrontmatter(data, resolvedOptions);
+        if (!parsed.ok || parsed.value === null)
+            continue;
+        const fm = parsed.value;
+        const page = {
+            slug: fm.slug,
+            key: fm.key,
+            locale: effectiveLocale(fm, resolvedOptions),
+            path,
+            title: fm.title,
+            keywords: fm.keywords,
+            linksTo: [],
+            linkedFrom: [],
+            aliases: fm.aliases ?? [],
+            linkRefs: [],
+            linkedFromRefs: [],
+        };
+        pages.set(pageMapKey(page, resolvedOptions), page);
+    }
+    for (const page of pages.values()) {
+        for (const alias of page.aliases) {
+            const replacement = replacementFor(page, resolvedOptions);
+            const key = aliasMapKey(alias, page.locale, resolvedOptions);
+            aliases.set(key, replacement);
+            aliasEntries.push({ alias, locale: page.locale, replacement, page });
+        }
+    }
+    const lookup = buildLookup(pages, resolvedOptions);
+    for (const page of pages.values()) {
+        const source = parseLinkFrontmatter(inputForPage(page, inputs, resolvedOptions), resolvedOptions);
+        if (!source.ok || source.value === null)
+            continue;
+        for (const rawTarget of source.value.linksTo ?? []) {
+            const resolved = resolveTarget(rawTarget, page, lookup, resolvedOptions);
+            if (!resolved.page) {
+                page.linksTo.push(resolved.target);
+                continue;
+            }
+            page.linksTo.push(replacementFor(resolved.page, resolvedOptions));
+            page.linkRefs.push(referenceFor(resolved.page, resolved.target));
+            if (resolved.page === page)
+                continue;
+            const from = replacementFor(page, resolvedOptions);
+            if (!resolved.page.linkedFrom.includes(from))
+                resolved.page.linkedFrom.push(from);
+            if (!resolved.page.linkedFromRefs.some((r) => sameReference(r, page))) {
+                resolved.page.linkedFromRefs.push(referenceFor(page));
+            }
+        }
+    }
+    return { pages, aliases, aliasEntries, options: resolvedOptions };
+}
+// Stable, sorted JSON form for .contentbit/link-index.json. Global-slug projects
+// keep the original compact string arrays; locale/key projects receive richer
+// references so agents can see which local target was resolved.
+export function serializeLinkIndex(index) {
+    const scoped = [...index.pages.values()].some((page) => page.locale || page.key);
+    const pages = [...index.pages.values()]
+        .map((p) => {
+        const base = {
+            slug: p.slug,
+            ...(p.key ? { key: p.key } : {}),
+            ...(p.locale ? { locale: p.locale } : {}),
+            path: p.path,
+            ...(p.title ? { title: p.title } : {}),
+            ...(p.keywords ? { keywords: p.keywords } : {}),
+            linksTo: scoped ? p.linkRefs : [...p.linksTo],
+            linkedFrom: scoped ? sortedRefs(p.linkedFromRefs) : [...p.linkedFrom].sort(),
+            aliases: [...p.aliases],
+        };
+        return base;
+    })
+        .sort((a, b) => sortIdentity(a.locale, a.slug).localeCompare(sortIdentity(b.locale, b.slug)));
+    const aliases = {};
+    if (scoped) {
+        for (const entry of [...index.aliasEntries].sort((a, b) => sortIdentity(a.locale, a.alias).localeCompare(sortIdentity(b.locale, b.alias)))) {
+            aliases[aliasMapKey(entry.alias, entry.locale, index.options)] = referenceFor(entry.page);
+        }
+    }
+    else {
+        for (const key of [...index.aliases.keys()].sort())
+            aliases[key] = index.aliases.get(key);
+    }
+    return { pages, aliases };
+}
+export function aliasReplacementsForPage(index, data) {
+    const parsed = parseLinkFrontmatter(data, index.options);
+    const out = new Map();
+    if (!parsed.ok || parsed.value === null)
+        return out;
+    const locale = effectiveLocale(parsed.value, index.options);
+    for (const entry of index.aliasEntries) {
+        if (index.options.resolve === 'global-slug' || entry.locale === locale) {
+            out.set(entry.alias, entry.replacement);
+        }
+    }
+    return out;
+}
+// Cross-file link validation. Emits shape errors, duplicate-slug and
+// alias-conflict errors, dangling-link errors (with did-you-mean), and
+// self-link / orphan warnings. Returns file-tagged diagnostics so the CLI can
+// format each with its own filename.
+export function validateLinks(inputs, options = {}) {
+    const resolvedOptions = { ...DEFAULT_OPTIONS, ...options };
+    const out = [];
+    const validInputs = [];
+    const seenSlug = new Map(); // identity -> first file
+    const seenKey = new Map(); // identity -> first file
+    const seenAlias = new Map(); // identity -> file
+    // Shape + duplicate/alias-conflict pass (operates on raw inputs).
+    for (const { path, data } of inputs) {
+        const parsed = parseLinkFrontmatter(data, resolvedOptions);
+        if (!parsed.ok) {
+            for (const e of parsed.errors)
+                out.push(diag(path, 'CB_LINK_SHAPE', 'error', `invalid link frontmatter: ${e}`));
+            continue;
+        }
+        if (parsed.value === null)
+            continue;
+        const fm = parsed.value;
+        const locale = effectiveLocale(fm, resolvedOptions);
+        validInputs.push({ path, fm });
+        const slugKey = scopedKey(fm.slug, locale, resolvedOptions);
+        const prior = seenSlug.get(slugKey);
+        if (prior)
+            out.push(diag(path, 'CB_SLUG_DUPLICATE', 'error', `slug "${fm.slug}" also used by ${prior}`));
+        else
+            seenSlug.set(slugKey, path);
+        if (usesKeyResolution(resolvedOptions) && !fm.key) {
+            out.push(diag(path, 'CB_KEY_MISSING', 'error', `page "${fm.slug}" is missing key`));
+        }
+        if (fm.key) {
+            const keyKey = scopedKey(fm.key, locale, resolvedOptions);
+            const priorKey = seenKey.get(keyKey);
+            if (priorKey)
+                out.push(diag(path, 'CB_KEY_DUPLICATE', 'error', `key "${fm.key}" also used by ${priorKey}`));
+            else
+                seenKey.set(keyKey, path);
+        }
+        for (const alias of fm.aliases ?? []) {
+            const aliasKey = scopedKey(alias, locale, resolvedOptions);
+            if (seenAlias.has(aliasKey))
+                out.push(diag(path, 'CB_ALIAS_CONFLICT', 'error', `alias "${alias}" already declared by ${seenAlias.get(aliasKey)}`));
+            else
+                seenAlias.set(aliasKey, path);
+        }
+    }
+    const index = buildLinkIndex(inputs, resolvedOptions);
+    const lookup = buildLookup(index.pages, resolvedOptions);
+    for (const { path, fm } of validInputs) {
+        const page = index.pages.get(pageMapKey(frontmatterIdentity(fm, resolvedOptions), resolvedOptions));
+        if (!page)
+            continue;
+        // alias colliding with a real slug/key in the same scope
+        for (const alias of page.aliases) {
+            if (collidesWithPageIdentity(alias, page.locale, lookup, resolvedOptions))
+                out.push(diag(page.path, 'CB_ALIAS_CONFLICT', 'error', `alias "${alias}" collides with an existing page identity`));
+        }
+        for (const target of fm.linksTo ?? []) {
+            const resolved = resolveTarget(target, page, lookup, resolvedOptions);
+            if (resolved.page === page) {
+                out.push(diag(page.path, 'CB_LINK_SELF', 'warning', `page "${page.slug}" links to itself`));
+                continue;
+            }
+            if (resolved.page && resolved.crossLocale) {
+                out.push(diag(page.path, 'CB_LINK_CROSS_LOCALE', 'warning', `linksTo "${resolved.target}" resolves to locale "${resolved.page.locale}"`));
+                continue;
+            }
+            if (!resolved.page) {
+                if (targetExistsOutsideLocale(resolved.target, page.locale, lookup, resolvedOptions)) {
+                    out.push(diag(page.path, 'CB_LINK_LOCALE_MISSING', 'error', `linksTo "${resolved.target}" exists in another locale but not "${page.locale ?? 'default'}"`));
+                    continue;
+                }
+                const hint = closest(resolved.target, candidatesFor(page.locale, lookup, resolvedOptions));
+                out.push(diag(page.path, 'CB_LINK_UNRESOLVED', 'error', `linksTo "${resolved.target}" does not resolve to any page`, hint ? `Did you mean "${hint}"?` : undefined));
+            }
+        }
+        if (page.linkedFrom.length === 0)
+            out.push(diag(page.path, 'CB_LINK_ORPHAN', 'warning', `page "${page.slug}" has no inbound links`));
+    }
+    return out;
+}
+function normalizeFrontmatter(data, options) {
+    const out = { ...data };
+    copyConfiguredField(out, data, options.slugField, 'slug');
+    copyConfiguredField(out, data, options.keyField, 'key');
+    copyConfiguredField(out, data, options.localeField, 'locale');
+    return out;
+}
+function copyConfiguredField(out, data, from, to) {
+    if (!from || from === to || !(from in data) || to in out)
+        return;
+    out[to] = data[from];
+}
+function effectiveLocale(fm, options) {
+    return fm.locale ?? options.defaultLocale;
+}
+function frontmatterIdentity(fm, options) {
+    return { slug: fm.slug, key: fm.key, locale: effectiveLocale(fm, options) };
+}
+function pageMapKey(page, options) {
+    if (options.resolve === 'global-slug')
+        return page.slug;
+    return scopedKey(page.slug, page.locale, options);
+}
+function scopedKey(value, locale, options) {
+    if (options.resolve === 'global-slug')
+        return value;
+    return `${locale ?? ''}\0${value}`;
+}
+function aliasMapKey(alias, locale, options) {
+    return options.resolve === 'global-slug' ? alias : `${locale ?? ''}:${alias}`;
+}
+function replacementFor(page, options) {
+    if (options.resolve === 'same-locale-key')
+        return page.key ?? page.slug;
+    if (options.resolve === 'prefer-same-locale-key-fallback-slug')
+        return page.key ?? page.slug;
+    return page.slug;
+}
+function referenceFor(page, target) {
+    return {
+        ...(target ? { target } : {}),
+        ...(page.locale ? { locale: page.locale } : {}),
+        slug: page.slug,
+        ...(page.key ? { key: page.key } : {}),
+    };
+}
+function sameReference(ref, page) {
+    return ref.slug === page.slug && ref.locale === page.locale && ref.key === page.key;
+}
+function sortedRefs(refs) {
+    return [...refs].sort((a, b) => sortIdentity(a.locale, a.key ?? a.slug).localeCompare(sortIdentity(b.locale, b.key ?? b.slug)));
+}
+function sortIdentity(locale, value) {
+    return `${locale ?? ''}\0${value}`;
+}
+function buildLookup(pages, options) {
+    const lookup = {
+        bySlug: new Map(),
+        byScopedSlug: new Map(),
+        byKey: new Map(),
+        byScopedKey: new Map(),
+        aliasBySlug: new Map(),
+        aliasByScopedSlug: new Map(),
+        aliasByKey: new Map(),
+        aliasByScopedKey: new Map(),
+    };
+    for (const page of pages.values()) {
+        pushMulti(lookup.bySlug, page.slug, page);
+        lookup.byScopedSlug.set(scopedKey(page.slug, page.locale, options), page);
+        if (page.key) {
+            pushMulti(lookup.byKey, page.key, page);
+            lookup.byScopedKey.set(scopedKey(page.key, page.locale, options), page);
+        }
+        for (const alias of page.aliases) {
+            lookup.aliasBySlug.set(alias, page);
+            lookup.aliasByScopedSlug.set(scopedKey(alias, page.locale, options), page);
+            if (page.key) {
+                lookup.aliasByKey.set(alias, page);
+                lookup.aliasByScopedKey.set(scopedKey(alias, page.locale, options), page);
+            }
+        }
+    }
+    return lookup;
+}
+function pushMulti(map, key, page) {
+    const existing = map.get(key);
+    if (existing)
+        existing.push(page);
+    else
+        map.set(key, [page]);
+}
+function resolveTarget(rawTarget, source, lookup, options) {
+    if (typeof rawTarget !== 'string') {
+        const locale = rawTarget.locale ?? source.locale;
+        const page = rawTarget.key
+            ? lookup.byScopedKey.get(scopedKey(rawTarget.key, locale, options))
+            : rawTarget.slug
+                ? lookup.byScopedSlug.get(scopedKey(rawTarget.slug, locale, options))
+                : undefined;
+        const target = rawTarget.key ?? rawTarget.slug ?? '';
+        return {
+            page,
+            target,
+            explicitLocale: rawTarget.locale,
+            crossLocale: Boolean(page && rawTarget.locale && rawTarget.locale !== source.locale),
+            matchedBy: rawTarget.key ? 'key' : 'slug',
+        };
+    }
+    const locale = source.locale;
+    if (options.resolve === 'global-slug') {
+        const page = lookup.aliasBySlug.get(rawTarget) ?? single(lookup.bySlug.get(rawTarget));
+        return { page, target: rawTarget, crossLocale: false, matchedBy: page ? 'slug' : undefined };
+    }
+    if (options.resolve === 'same-locale-key') {
+        const scoped = scopedKey(rawTarget, locale, options);
+        const page = lookup.byScopedKey.get(scoped) ?? lookup.aliasByScopedKey.get(scoped);
+        return { page, target: rawTarget, crossLocale: false, matchedBy: page ? 'key' : undefined };
+    }
+    if (options.resolve === 'prefer-same-locale-key-fallback-slug') {
+        const scoped = scopedKey(rawTarget, locale, options);
+        const page = lookup.byScopedKey.get(scoped) ??
+            lookup.aliasByScopedKey.get(scoped) ??
+            lookup.byScopedSlug.get(scoped) ??
+            lookup.aliasByScopedSlug.get(scoped);
+        return { page, target: rawTarget, crossLocale: false, matchedBy: page ? 'key' : undefined };
+    }
+    const scoped = scopedKey(rawTarget, locale, options);
+    const page = lookup.byScopedSlug.get(scoped) ?? lookup.aliasByScopedSlug.get(scoped);
+    return { page, target: rawTarget, crossLocale: false, matchedBy: page ? 'slug' : undefined };
+}
+function single(values) {
+    return values?.length === 1 ? values[0] : undefined;
+}
+function usesKeyResolution(options) {
+    return options.resolve === 'same-locale-key';
+}
+function collidesWithPageIdentity(alias, locale, lookup, options) {
+    if (options.resolve === 'global-slug')
+        return lookup.bySlug.has(alias);
+    const scoped = scopedKey(alias, locale, options);
+    return (lookup.byScopedSlug.has(scoped) ||
+        (usesKeyResolution(options) && lookup.byScopedKey.has(scoped)));
+}
+function targetExistsOutsideLocale(target, locale, lookup, options) {
+    if (options.resolve === 'global-slug')
+        return false;
+    const byIdentity = usesKeyResolution(options) ? lookup.byKey : lookup.bySlug;
+    return (byIdentity.get(target) ?? []).some((page) => page.locale !== locale);
+}
+function candidatesFor(locale, lookup, options) {
+    if (options.resolve === 'global-slug')
+        return [...lookup.bySlug.keys()];
+    const out = [];
+    for (const page of lookup.byScopedSlug.values()) {
+        if (page.locale === locale)
+            out.push(usesKeyResolution(options) && page.key ? page.key : page.slug);
+    }
+    return out;
+}
+function inputForPage(page, inputs, options) {
+    for (const input of inputs) {
+        const parsed = parseLinkFrontmatter(input.data, options);
+        if (!parsed.ok || parsed.value === null)
+            continue;
+        const identity = frontmatterIdentity(parsed.value, options);
+        if (pageMapKey(identity, options) === pageMapKey(page, options))
+            return input.data;
+    }
+    return {};
+}
+function diag(file, code, severity, message, hint) {
+    return { file, diagnostic: { code, severity, message, hint, position: FM_POSITION } };
+}
+// Levenshtein distance for did-you-mean hints. Small inputs (slugs), so the
+// simple O(n*m) matrix is fine.
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[a.length][b.length];
+}
+function closest(target, candidates) {
+    let best;
+    let bestD = Infinity;
+    for (const c of candidates) {
+        const d = editDistance(target, c);
+        if (d < bestD) {
+            bestD = d;
+            best = c;
+        }
+    }
+    return best && bestD <= Math.max(2, Math.floor(target.length / 3)) ? best : undefined;
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentbit/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Parser, validator, and registry for Content Blocks: structured Markdown components without framework lock-in.",
   "keywords": [
     "ast",