@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/lattice.js

@@ -0,0 +1,816 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, basename, relative, resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import GithubSlugger from 'github-slugger';
+import { parse as parseYaml } from 'yaml';
+import { parse } from './parser.js';
+import { toPosix, walkEntries } from './walk.js';
+import { visit } from 'unist-util-visit';
+/**
+ * Every field this build reads out of the `lat:` mapping. Kept in one place so
+ * a field added later is covered by the misplacement check without a second
+ * edit — the trap this list guards against is silent, so it must not depend on
+ * whoever adds the next field remembering to register it twice.
+ */
+export const LAT_FIELDS = [
+    'require-code-mention',
+    'mode',
+    'status',
+    'reviewed-hash',
+    'tags',
+];
+export function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return { raw: {} };
+    let raw = {};
+    const problems = [];
+    try {
+        const parsed = parseYaml(match[1]);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed)) {
+            const root = parsed;
+            const lat = root['lat'];
+            const hasLatMapping = lat !== null && typeof lat === 'object' && !Array.isArray(lat);
+            if (hasLatMapping) {
+                raw = lat;
+            }
+            // A field written at the document root was accepted by the regex reader
+            // this parser replaced. Staying quiet about it is what makes the change
+            // dangerous: the field simply stops being read.
+            for (const field of LAT_FIELDS) {
+                if (Object.hasOwn(root, field) && !Object.hasOwn(raw, field)) {
+                    problems.push({ kind: 'root-level-field', field });
+                }
+            }
+        }
+    }
+    catch (err) {
+        // One malformed line anywhere in the block used to be harmless, because
+        // the old reader pattern-matched the raw text. A strict parse throws away
+        // every field instead, so the failure has to be reported rather than
+        // swallowed.
+        raw = {};
+        problems.push({
+            kind: 'parse-error',
+            message: err.message.split('\n')[0],
+        });
+    }
+    const result = { raw };
+    if (raw['require-code-mention'] === true) {
+        result.requireCodeMention = true;
+    }
+    if (problems.length > 0)
+        result.problems = problems;
+    return result;
+}
+export function findLatticeDir(from) {
+    let dir = resolve(from ?? process.cwd());
+    while (true) {
+        const candidate = join(dir, 'lat.md');
+        if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function findProjectRoot(from) {
+    const latDir = findLatticeDir(from);
+    return latDir ? dirname(latDir) : null;
+}
+export async function listLatticeFiles(latticeDir) {
+    const entries = await walkEntries(latticeDir);
+    return entries
+        .filter((e) => e.endsWith('.md'))
+        .sort()
+        .map((e) => join(latticeDir, e));
+}
+function headingText(node) {
+    return node.children
+        .filter((c) => c.type === 'text')
+        .map((c) => c.value)
+        .join('');
+}
+/** Extract the rendered text GitHub uses as input to its heading slugger. */
+function githubHeadingText(node) {
+    if (!node || typeof node !== 'object')
+        return '';
+    const value = node;
+    if (value.type === 'text' || value.type === 'inlineCode') {
+        return value.value ?? '';
+    }
+    if (value.type === 'image' || value.type === 'imageReference') {
+        return value.alt ?? '';
+    }
+    if (value.type === 'wikiLink') {
+        return value.data?.alias ?? value.value ?? '';
+    }
+    if (value.children) {
+        return value.children.map(githubHeadingText).join('');
+    }
+    return '';
+}
+function inlineText(node) {
+    return node.children
+        .map((c) => {
+        if (c.type === 'text')
+            return c.value;
+        if (c.type === 'inlineCode')
+            return '`' + c.value + '`';
+        if (c.type === 'wikiLink')
+            return '[[' + c.value + ']]';
+        if ('children' in c)
+            return inlineText(c);
+        return '';
+    })
+        .join('');
+}
+function lastLine(content) {
+    const lines = content.split('\n');
+    // If trailing newline, count doesn't include empty last line
+    return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
+}
+export function parseSections(filePath, content, projectRoot, tree = parse(content)) {
+    const file = projectRoot
+        ? toPosix(relative(projectRoot, filePath)).replace(/\.md$/, '')
+        : basename(filePath, '.md');
+    const sectionFilePath = projectRoot
+        ? toPosix(relative(projectRoot, filePath))
+        : basename(filePath);
+    const roots = [];
+    const stack = [];
+    const flat = [];
+    const slugger = new GithubSlugger();
+    visit(tree, 'heading', (node) => {
+        const heading = headingText(node);
+        const depth = node.depth;
+        const startLine = node.position.start.line;
+        // Pop stack until we find a parent with smaller depth
+        while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+            stack.pop();
+        }
+        const parent = stack.length > 0 ? stack[stack.length - 1] : null;
+        const id = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
+        const section = {
+            id,
+            heading,
+            depth,
+            file,
+            filePath: sectionFilePath,
+            children: [],
+            startLine,
+            endLine: 0,
+            firstParagraph: '',
+            githubSlug: slugger.slug(githubHeadingText(node)),
+        };
+        if (parent) {
+            parent.children.push(section);
+        }
+        else {
+            roots.push(section);
+        }
+        stack.push(section);
+        flat.push(section);
+    });
+    // Compute endLine: line before next heading or last line of file
+    const fileLastLine = lastLine(content);
+    for (let i = 0; i < flat.length; i++) {
+        if (i + 1 < flat.length) {
+            flat[i].endLine = flat[i + 1].startLine - 1;
+        }
+        else {
+            flat[i].endLine = fileLastLine;
+        }
+    }
+    // Extract firstParagraph: first paragraph after each heading
+    const children = tree.children;
+    let headingIdx = 0;
+    for (let i = 0; i < children.length; i++) {
+        const node = children[i];
+        if (node.type === 'heading') {
+            // Find the first paragraph after this heading, before the next heading
+            for (let j = i + 1; j < children.length; j++) {
+                if (children[j].type === 'heading')
+                    break;
+                if (children[j].type === 'paragraph') {
+                    flat[headingIdx].firstParagraph = inlineText(children[j]);
+                    break;
+                }
+            }
+            headingIdx++;
+        }
+    }
+    return roots;
+}
+export async function loadAllSections(latticeDir, projectRoot = dirname(latticeDir)) {
+    const files = await listLatticeFiles(latticeDir);
+    const all = [];
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        all.push(...parseSections(file, content, projectRoot));
+    }
+    return all;
+}
+export function flattenSections(sections) {
+    const result = [];
+    for (const s of sections) {
+        result.push(s);
+        result.push(...flattenSections(s.children));
+    }
+    return result;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] =
+                a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Returns the trailing segment(s) of a section id.
+ * e.g. "markdown#Frontmatter#require-code-mention" → ["Frontmatter#require-code-mention", "require-code-mention"]
+ * The full id itself is not included (handled by exact match).
+ */
+function tailSegments(id) {
+    const parts = id.split('#');
+    const tails = [];
+    for (let i = 1; i < parts.length; i++) {
+        tails.push(parts.slice(i).join('#'));
+    }
+    return tails;
+}
+/**
+ * Build an index mapping path suffixes to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a suffix is unambiguous.
+ *
+ * For a file like `lat.md/guides/setup`, indexes both `guides/setup` and `setup`.
+ * This ensures backward-compatible short refs after the vault root moved to the
+ * project root (so section IDs now include the `lat.md/` prefix).
+ */
+export function buildFileIndex(sections) {
+    const flat = flattenSections(sections);
+    const index = new Map();
+    for (const s of flat) {
+        const parts = s.file.split('/');
+        // Index all trailing path suffixes (excluding the full path itself,
+        // which is handled by exact match). Keys are lowercase for
+        // case-insensitive lookup.
+        for (let i = 1; i < parts.length; i++) {
+            const suffix = parts.slice(i).join('/').toLowerCase();
+            if (!index.has(suffix))
+                index.set(suffix, new Set());
+            index.get(suffix).add(s.file);
+        }
+    }
+    const result = new Map();
+    for (const [stem, paths] of index) {
+        result.set(stem, [...paths]);
+    }
+    return result;
+}
+/**
+ * Map GitHub-slugged heading paths back to canonical, literal-heading ids.
+ * Every path segment accepts either representation so an implicit literal h1
+ * can still prefix slugged child headings during short-ref resolution.
+ */
+export function buildSectionSlugIndex(sections) {
+    const aliases = new Map();
+    const stacks = new Map();
+    const sluggers = new Map();
+    for (const section of flattenSections(sections)) {
+        let slugger = sluggers.get(section.file);
+        if (!slugger) {
+            slugger = new GithubSlugger();
+            sluggers.set(section.file, slugger);
+        }
+        // Always advance the fallback slugger so manually constructed Section
+        // objects without githubSlug still get correct duplicate suffixes.
+        const fallbackSlug = slugger.slug(section.heading);
+        const headingSlug = section.githubSlug ?? fallbackSlug;
+        const stack = stacks.get(section.file) ?? [];
+        while (stack.length > 0 && stack[stack.length - 1].depth >= section.depth) {
+            stack.pop();
+        }
+        const levels = [
+            ...stack,
+            {
+                depth: section.depth,
+                literal: section.heading.toLowerCase(),
+                slug: headingSlug.toLowerCase(),
+            },
+        ];
+        let paths = [''];
+        for (const level of levels) {
+            const options = [...new Set([level.literal, level.slug])];
+            paths = paths.flatMap((path) => options.map((part) => (path ? `${path}#${part}` : part)));
+        }
+        for (const path of paths) {
+            const alias = `${section.file.toLowerCase()}#${path}`;
+            if (!aliases.has(alias))
+                aliases.set(alias, section.id);
+        }
+        stack.push(levels[levels.length - 1]);
+        stacks.set(section.file, stack);
+    }
+    return aliases;
+}
+/**
+ * Normalize separators only in the file portion of a section reference.
+ * Headings are authored text and may legitimately contain backslashes.
+ */
+function normalizeRefFilePath(target) {
+    const hashIdx = target.indexOf('#');
+    if (hashIdx === -1)
+        return toPosix(target);
+    return toPosix(target.slice(0, hashIdx)) + target.slice(hashIdx);
+}
+/**
+ * Resolve a potentially short reference to its canonical full-path form.
+ * If the file segment of the ref is a bare stem that uniquely maps to one
+ * full path, expands it. Otherwise returns the ref unchanged.
+ *
+ * When ambiguous (multiple files share the stem), returns all candidates.
+ * If exactly one candidate actually contains the referenced section,
+ * `suggested` is set to that candidate so the caller can propose a fix.
+ */
+export function resolveRef(target, sectionIds, fileIndex, slugIndex) {
+    target = normalizeRefFilePath(target);
+    const resolveKnown = (candidate) => {
+        // Preserve existing wiki-link meaning when a literal heading happens to
+        // collide with a different heading's GitHub slug.
+        if (sectionIds.has(candidate.toLowerCase()))
+            return candidate;
+        return slugIndex?.get(candidate.toLowerCase()) ?? null;
+    };
+    const resolveInFile = (file, rest) => {
+        const direct = resolveKnown(file + rest);
+        if (direct)
+            return direct;
+        // Try inserting root headings between file and rest. This also works for
+        // slugged child segments because the slug index contains mixed paths.
+        const rootHeadings = findRootHeadings(file, sectionIds);
+        for (const h1 of rootHeadings) {
+            const withRoot = rest ? `${file}#${h1}${rest}` : `${file}#${h1}`;
+            const resolved = resolveKnown(withRoot);
+            if (resolved)
+                return resolved;
+        }
+        return null;
+    };
+    // Already matches a known section — no resolution needed
+    const direct = resolveKnown(target);
+    if (direct) {
+        return { resolved: direct, ambiguous: null, suggested: null };
+    }
+    // Extract the file segment (before first #) and try resolving it
+    const hashIdx = target.indexOf('#');
+    const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
+    const rest = hashIdx === -1 ? '' : target.slice(hashIdx);
+    // Try resolving the file part: either it's a full path or a bare stem
+    // File index keys are lowercase for case-insensitive lookup.
+    const lcFilePart = filePart.toLowerCase();
+    const filePaths = fileIndex.has(lcFilePart)
+        ? fileIndex.get(lcFilePart)
+        : [filePart];
+    if (filePaths.length === 1) {
+        const fp = filePaths[0];
+        const resolved = resolveInFile(fp, rest);
+        if (resolved) {
+            return { resolved, ambiguous: null, suggested: null };
+        }
+    }
+    else if (filePaths.length > 1) {
+        // Multiple files share this stem — ambiguous at the filename level
+        const all = filePaths.map((c) => c + rest);
+        const valid = filePaths.filter((c) => resolveInFile(c, rest) !== null);
+        return {
+            resolved: target,
+            ambiguous: all,
+            suggested: valid.length === 1 ? valid[0] + rest : null,
+        };
+    }
+    return { resolved: target, ambiguous: null, suggested: null };
+}
+/**
+ * Find root (h1) headings for a file by scanning sectionIds for entries
+ * that have exactly the pattern `file#heading` (no further # segments).
+ */
+function findRootHeadings(file, sectionIds) {
+    const prefix = file.toLowerCase() + '#';
+    const headings = [];
+    for (const id of sectionIds) {
+        if (id.startsWith(prefix) && !id.includes('#', prefix.length)) {
+            headings.push(id.slice(prefix.length));
+        }
+    }
+    return headings;
+}
+const MAX_DISTANCE_RATIO = 0.4;
+export function findSections(sections, query) {
+    const flat = flattenSections(sections);
+    // Leading # means "search for a heading", strip it
+    const normalized = normalizeRefFilePath(query.startsWith('#') ? query.slice(1) : query);
+    const q = normalized.toLowerCase();
+    const isFullPath = normalized.includes('#');
+    const byId = new Map(flat.map((s) => [s.id.toLowerCase(), s]));
+    const slugIndex = buildSectionSlugIndex(sections);
+    const sectionFor = (candidate) => {
+        const key = candidate.toLowerCase();
+        return byId.get(key) ?? byId.get(slugIndex.get(key)?.toLowerCase() ?? '');
+    };
+    // Tier 1: exact full-id match
+    const literalExact = flat.filter((s) => s.id.toLowerCase() === q);
+    const slugExact = literalExact.length === 0 && isFullPath
+        ? sectionFor(normalized)
+        : undefined;
+    const exact = slugExact ? [slugExact] : literalExact;
+    const exactMatches = exact.map((s) => ({
+        section: s,
+        reason: 'exact match',
+    }));
+    if (exactMatches.length > 0 && isFullPath)
+        return exactMatches;
+    // Build file index early — used by both tier 1a and 1b
+    const fileIndex = buildFileIndex(sections);
+    // Tier 1a: bare name matches file — return root sections of that file
+    // Also checks via file index (e.g. "dev-process" → "lat.md/dev-process")
+    if (!isFullPath && exactMatches.length === 0) {
+        const matchFiles = new Set();
+        // Direct match
+        for (const s of flat) {
+            if (s.file.toLowerCase() === q &&
+                !s.id.includes('#', s.file.length + 1)) {
+                matchFiles.add(s.file);
+            }
+        }
+        // File index expansion (keys are lowercase)
+        const indexPaths = fileIndex.get(q) ?? [];
+        for (const p of indexPaths) {
+            matchFiles.add(p);
+        }
+        if (matchFiles.size > 0) {
+            const fileRoots = flat.filter((s) => matchFiles.has(s.file) && !s.id.includes('#', s.file.length + 1));
+            if (fileRoots.length > 0) {
+                return fileRoots.map((s) => ({
+                    section: s,
+                    reason: 'exact match',
+                }));
+            }
+        }
+    }
+    // Tier 1b: file stem expansion
+    // For bare names: "locate" → matches root section of "tests/locate.md"
+    // For paths with #: "setup#Install" → expands to "guides/setup#Install"
+    const stemMatches = [];
+    if (isFullPath) {
+        // Expand file stem in the file part of the query
+        const hashIdx = normalized.indexOf('#');
+        const filePart = normalized.slice(0, hashIdx);
+        const rest = normalized.slice(hashIdx);
+        const stemPaths = fileIndex.get(filePart.toLowerCase()) ?? [];
+        // Also try filePart as a direct file path (for root-level files not in index)
+        const allPaths = stemPaths.length > 0 ? stemPaths : filePart ? [filePart] : [];
+        for (const p of allPaths) {
+            const s = sectionFor(p + rest);
+            if (s) {
+                if (exact.includes(s))
+                    continue;
+                stemMatches.push({
+                    section: s,
+                    reason: stemPaths.length > 0
+                        ? `file stem expanded: ${filePart} → ${p}`
+                        : 'exact match',
+                });
+                continue;
+            }
+            // Try inserting root headings: file#rest → file#h1#rest
+            const rootsOfFile = flat.filter((s) => s.file.toLowerCase() === p.toLowerCase() &&
+                !s.id.includes('#', s.file.length + 1));
+            for (const root of rootsOfFile) {
+                const match = sectionFor(root.id + rest);
+                if (match) {
+                    if (exact.includes(match))
+                        continue;
+                    stemMatches.push({
+                        section: match,
+                        reason: stemPaths.length > 0
+                            ? `file stem expanded: ${filePart} → ${p}`
+                            : 'exact match',
+                    });
+                }
+            }
+        }
+        if (stemMatches.length > 0)
+            return [...exactMatches, ...stemMatches];
+    }
+    else {
+        // Bare name: match root sections of files via stem index (keys lowercase)
+        const paths = fileIndex.get(q) ?? [];
+        for (const p of paths) {
+            for (const s of flat) {
+                if (exact.includes(s))
+                    continue;
+                // Root sections have id = "file#heading" (exactly 2 segments)
+                if (s.file.toLowerCase() === p.toLowerCase() &&
+                    !s.id.includes('#', s.file.length + 1)) {
+                    stemMatches.push({ section: s, reason: 'file stem match' });
+                }
+            }
+        }
+    }
+    // Tier 2: exact match on trailing segments (subsection name match)
+    const seen = new Set([
+        ...exact.map((s) => s.id),
+        ...stemMatches.map((m) => m.section.id),
+    ]);
+    const slugTailMatches = new Set();
+    if (!isFullPath) {
+        for (const [alias, canonical] of slugIndex) {
+            if (alias.slice(alias.lastIndexOf('#') + 1) === q) {
+                slugTailMatches.add(canonical.toLowerCase());
+            }
+        }
+    }
+    const literalTailMatches = new Set(isFullPath
+        ? []
+        : flat
+            .filter((s) => tailSegments(s.id).some((tail) => tail.toLowerCase() === q))
+            .map((s) => s.id.toLowerCase()));
+    const subsection = isFullPath
+        ? []
+        : flat
+            .filter((s) => {
+            if (seen.has(s.id))
+                return false;
+            const id = s.id.toLowerCase();
+            return literalTailMatches.size > 0
+                ? literalTailMatches.has(id)
+                : slugTailMatches.has(id);
+        })
+            .map((s) => ({ section: s, reason: 'section name match' }));
+    // Tier 2b: subsequence match — query segments are a subsequence of section id segments
+    // e.g. "Markdown#Resolution Rules" matches "markdown#Wiki Links#Resolution Rules"
+    // Also tries expanding the file part via the file index for short refs.
+    const seenSub = new Set([...seen, ...subsection.map((m) => m.section.id)]);
+    const qParts = q.split('#');
+    // Build query variants: original + file-index-expanded forms
+    const qVariants = [qParts];
+    if (qParts.length >= 2) {
+        const expanded = fileIndex.get(qParts[0]);
+        if (expanded) {
+            for (const exp of expanded) {
+                qVariants.push([exp.toLowerCase(), ...qParts.slice(1)]);
+            }
+        }
+    }
+    const subsequence = qParts.length >= 2
+        ? flat
+            .filter((s) => {
+            if (seenSub.has(s.id))
+                return false;
+            const sParts = s.id.toLowerCase().split('#');
+            return qVariants.some((variant) => {
+                if (sParts.length <= variant.length)
+                    return false;
+                let qi = 0;
+                for (const sp of sParts) {
+                    if (sp === variant[qi])
+                        qi++;
+                    if (qi === variant.length)
+                        return true;
+                }
+                return false;
+            });
+        })
+            .map((s) => {
+            const skipped = s.id.split('#').length - qParts.length;
+            return {
+                section: s,
+                reason: `path match, ${skipped} intermediate ${skipped === 1 ? 'section' : 'sections'} skipped`,
+            };
+        })
+        : [];
+    // Tier 3: fuzzy match by edit distance on each segment tail and full id
+    const seenAll = new Set([
+        ...seenSub,
+        ...subsequence.map((m) => m.section.id),
+    ]);
+    const fuzzy = [];
+    // For full-path queries, extract the file and heading parts so we can
+    // fuzzy-match only the heading portion when the file part matches exactly.
+    // This prevents the shared file prefix from inflating similarity scores
+    // (e.g. "cli#locat" would otherwise fuzzy-match "cli#prompt").
+    const qHashIdx = normalized.indexOf('#');
+    const qFile = qHashIdx === -1 ? null : normalized.slice(0, qHashIdx).toLowerCase();
+    const qHeading = qHashIdx === -1 ? null : normalized.slice(qHashIdx + 1).toLowerCase();
+    for (const s of flat) {
+        if (seenAll.has(s.id))
+            continue;
+        const candidates = [s.id, ...tailSegments(s.id)];
+        let best = Infinity;
+        let bestCandidate = '';
+        for (const c of candidates) {
+            let d;
+            let maxLen;
+            const cl = c.toLowerCase();
+            const cHashIdx = cl.indexOf('#');
+            // When both query and candidate have # and their file parts match,
+            // compare only the heading portions to avoid file-prefix inflation
+            if (qFile && qHeading && cHashIdx !== -1) {
+                const cFile = cl.slice(0, cHashIdx);
+                const cHeading = cl.slice(cHashIdx + 1);
+                if (cFile === qFile) {
+                    d = levenshtein(cHeading, qHeading);
+                    maxLen = Math.max(cHeading.length, qHeading.length);
+                }
+                else {
+                    d = levenshtein(cl, q);
+                    maxLen = Math.max(c.length, q.length);
+                }
+            }
+            else {
+                d = levenshtein(cl, q);
+                maxLen = Math.max(c.length, q.length);
+            }
+            if (maxLen > 0 && d / maxLen <= MAX_DISTANCE_RATIO && d < best) {
+                best = d;
+                bestCandidate = c;
+            }
+        }
+        if (best < Infinity) {
+            fuzzy.push({ section: s, distance: best, matched: bestCandidate });
+        }
+    }
+    fuzzy.sort((a, b) => a.distance - b.distance);
+    const fuzzyMatches = fuzzy.map((f) => ({
+        section: f.section,
+        reason: f.matched.toLowerCase() === f.section.id.toLowerCase()
+            ? `fuzzy match, distance ${f.distance}`
+            : `fuzzy match on "${f.matched}", distance ${f.distance}`,
+    }));
+    // Sort results: shallower depth first, then fewer path segments
+    const sortKey = (s) => {
+        const pathDepth = (s.file.match(/\//g) || []).length;
+        return s.depth * 100 + pathDepth;
+    };
+    const sortedStems = [...stemMatches].sort((a, b) => sortKey(a.section) - sortKey(b.section));
+    return [
+        ...exactMatches,
+        ...sortedStems,
+        ...subsection,
+        ...subsequence,
+        ...fuzzyMatches,
+    ];
+}
+export function extractRefs(filePath, content, projectRoot, tree = parse(content)) {
+    const file = projectRoot
+        ? toPosix(relative(projectRoot, filePath)).replace(/\.md$/, '')
+        : basename(filePath, '.md');
+    const refs = [];
+    // Build a flat list of sections to determine enclosing section for each wiki link
+    const flat = [];
+    visit(tree, 'heading', (node) => {
+        flat.push({
+            id: '', // filled below
+            startLine: node.position.start.line,
+        });
+    });
+    // Re-derive ids using the same logic as parseSections
+    const stack = [];
+    let idx = 0;
+    visit(tree, 'heading', (node) => {
+        const heading = headingText(node);
+        const depth = node.depth;
+        while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+            stack.pop();
+        }
+        const parent = stack.length > 0 ? stack[stack.length - 1] : null;
+        const id = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
+        flat[idx].id = id;
+        stack.push({ id, depth });
+        idx++;
+    });
+    visit(tree, 'wikiLink', (node) => {
+        const line = node.position.start.line;
+        // Find enclosing section: last heading with startLine <= link line
+        let fromSection = '';
+        for (const s of flat) {
+            if (s.startLine <= line) {
+                fromSection = s.id;
+            }
+            else {
+                break;
+            }
+        }
+        refs.push({
+            target: node.value,
+            fromSection,
+            file,
+            line,
+        });
+    });
+    return refs;
+}
+function isEscapedAt(value, index) {
+    let slashes = 0;
+    for (let i = index - 1; i >= 0 && value[i] === '\\'; i--)
+        slashes++;
+    return slashes % 2 === 1;
+}
+function closingBracket(value, open) {
+    let depth = 0;
+    for (let i = open; i < value.length; i++) {
+        if (isEscapedAt(value, i))
+            continue;
+        if (value[i] === '[') {
+            depth++;
+        }
+        else if (value[i] === ']') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Extract link destinations and undefined full/collapsed references. */
+export function extractLinks(content, tree = parse(content)) {
+    const links = [];
+    visit(tree, ['link', 'image', 'definition'], (node) => {
+        const { url, type, position } = node;
+        links.push({ url, kind: type, line: position.start.line });
+    });
+    // CommonMark parses a reference with no matching definition as plain text,
+    // so it has no linkReference node to visit. Scan the authored syntax while
+    // excluding AST ranges where bracket text is data rather than prose.
+    const excluded = [];
+    visit(tree, [
+        'code',
+        'inlineCode',
+        'html',
+        'yaml',
+        'link',
+        'image',
+        'definition',
+        'linkReference',
+        'imageReference',
+        'wikiLink',
+    ], (node) => {
+        const start = node.position?.start.offset;
+        const end = node.position?.end.offset;
+        if (start !== undefined && end !== undefined) {
+            excluded.push({ start, end });
+        }
+    });
+    const overlapsExcluded = (start, end) => excluded.some((range) => start < range.end && end > range.start);
+    for (let open = 0; open < content.length; open++) {
+        if (content[open] !== '[' || isEscapedAt(content, open))
+            continue;
+        const labelEnd = closingBracket(content, open);
+        const identifierStart = labelEnd + 1;
+        if (labelEnd === -1 ||
+            content[identifierStart] !== '[' ||
+            isEscapedAt(content, identifierStart)) {
+            continue;
+        }
+        const identifierEnd = closingBracket(content, identifierStart);
+        if (identifierEnd === -1)
+            continue;
+        const isImage = open > 0 && content[open - 1] === '!' && !isEscapedAt(content, open - 1);
+        const start = isImage ? open - 1 : open;
+        const end = identifierEnd + 1;
+        if (overlapsExcluded(start, end)) {
+            open = identifierEnd;
+            continue;
+        }
+        const explicitIdentifier = content.slice(identifierStart + 1, identifierEnd);
+        const identifier = explicitIdentifier || content.slice(open + 1, labelEnd);
+        if (identifier.trim() === '') {
+            open = identifierEnd;
+            continue;
+        }
+        links.push({
+            identifier: identifier.trim(),
+            source: content.slice(start, end),
+            kind: isImage ? 'imageReference' : 'linkReference',
+            line: content.slice(0, start).split('\n').length,
+        });
+        open = identifierEnd;
+    }
+    return links.sort((a, b) => a.line - b.line);
+}