@plebeiantech/lat.md 0.12.3-fork.17 → 0.12.3-fork.20

package/dist/src/cli/check.js

@@ -1,834 +0,0 @@
-import { lstat, rename, unlink, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { basename, dirname, extname, join, relative, resolve } from 'node:path';
-import { performance } from 'node:perf_hooks';
-import { flattenSections, resolveRef } from '../lattice-model.js';
-import { isSourceFileExtension, SOURCE_FILE_EXTENSIONS, } from '../source-formats.js';
-import { inspectRepositoryPath, normalizeRepositoryPath, } from '../repository-path.js';
-import { toPosix } from '../path.js';
-import { TimingProfiler } from '../profiler.js';
-import { checkMode } from './check-mode.js';
-import { checkStatus } from './check-status.js';
-import { checkFrontmatter } from './check-frontmatter.js';
-import { checkCoverage } from './check-coverage.js';
-import { indexEntryNameFromDest } from './link-scheme.js';
-import { fencedLineMask } from './gen-index.js';
-import { INIT_VERSION, readInitVersion } from '../init-version.js';
-import { CheckRunContext } from './check-context.js';
-import { parseLocalMarkdownTarget } from '../markdown-validation.js';
-function filePart(id) {
-    const h = id.indexOf('#');
-    return h === -1 ? id : id.slice(0, h);
-}
-/** Format an ambiguous-ref error as structured markdown-like text. */
-export function ambiguousRefMessage(target, candidates, suggested) {
-    const shortName = filePart(target);
-    const fileList = candidates.map((c) => `  - "${filePart(c)}.md"`).join('\n');
-    const lines = [];
-    if (suggested) {
-        lines.push(`ambiguous link '[[${target}]]' — did you mean '[[${suggested}]]'?`);
-    }
-    else {
-        const options = candidates.map((a) => `'[[${a}]]'`).join(', ');
-        lines.push(`ambiguous link '[[${target}]]' — multiple paths match, use either of: ${options}`);
-    }
-    lines.push(`  The short path "${shortName}" is ambiguous — ${candidates.length} files match:`, fileList, `  Please fix the link to use a fully qualified path.`);
-    return lines.join('\n');
-}
-async function profileTime(profile, label, work, detail) {
-    return profile ? profile.time(label, work, detail) : work();
-}
-function profileTimeSync(profile, label, work, detail) {
-    return profile ? profile.timeSync(label, work, detail) : work();
-}
-/**
- * Validate an unresolved wiki link as a repository path or source symbol.
- * Returns null when valid, otherwise a user-facing error message.
- */
-export async function repositoryRefError(target, projectRoot, sourceOptions = {}) {
-    const hashIdx = target.indexOf('#');
-    const authoredPath = hashIdx === -1 ? target : target.slice(0, hashIdx);
-    if (!authoredPath) {
-        return `broken link [[${target}]] — no matching section found`;
-    }
-    const filePart = normalizeRepositoryPath(authoredPath);
-    if (!filePart) {
-        return `broken link [[${target}]] — repository path "${authoredPath}" must stay within the project root`;
-    }
-    const symbolPart = hashIdx === -1 ? '' : target.slice(hashIdx + 1);
-    const ext = extname(filePart);
-    const sourcePath = isSourceFileExtension(ext);
-    const inspected = await inspectRepositoryPath(projectRoot, filePart);
-    if (inspected.kind === 'outside') {
-        return `broken link [[${target}]] — repository path "${filePart}" resolves outside the project root`;
-    }
-    if (hashIdx === -1) {
-        if (inspected.kind === 'missing') {
-            return `broken link [[${target}]] — repository file or directory "${filePart}" not found`;
-        }
-        if (inspected.kind === 'other') {
-            return `broken link [[${target}]] — repository path "${filePart}" is not a regular file or directory`;
-        }
-        return null;
-    }
-    if (inspected.kind === 'directory') {
-        return `broken link [[${target}]] — directory "${filePart}" cannot have a fragment`;
-    }
-    if (inspected.kind === 'other') {
-        return `broken link [[${target}]] — repository path "${filePart}" is not a regular file or directory`;
-    }
-    if (!sourcePath) {
-        if (ext || inspected.kind === 'file') {
-            const shownExtension = ext || '(none)';
-            const supported = SOURCE_FILE_EXTENSIONS.join(', ');
-            return `broken link [[${target}]] — unsupported file extension "${shownExtension}" for fragment reference. Supported: ${supported}`;
-        }
-        return `broken link [[${target}]] — no matching section found`;
-    }
-    if (inspected.kind === 'missing') {
-        return `broken link [[${target}]] — file "${filePart}" not found`;
-    }
-    if (!symbolPart) {
-        // Preserve the existing file-level behavior for an empty fragment.
-        return null;
-    }
-    try {
-        const { resolveSourceSymbol } = await import('../source-parser.js');
-        const { found, error } = await resolveSourceSymbol(filePart, symbolPart, projectRoot, sourceOptions);
-        if (error) {
-            return `broken link [[${target}]] — ${error}`;
-        }
-        if (!found) {
-            return `broken link [[${target}]] — symbol "${symbolPart}" not found in "${filePart}"`;
-        }
-        return null;
-    }
-    catch (err) {
-        return `broken link [[${target}]] — failed to parse "${filePart}": ${err instanceof Error ? err.message : String(err)}`;
-    }
-}
-export async function checkMd(latticeDir, projectRoot = dirname(latticeDir), context) {
-    const run = context ?? new CheckRunContext(latticeDir, projectRoot);
-    run.clearSourceSymbolCache();
-    const files = await run.markdownFiles();
-    const { sectionIds, fileIndex, slugIndex } = await run.sectionIndex();
-    const errors = [];
-    const external = await run.externalResolver();
-    for (const error of external.snapshot.errors) {
-        errors.push({
-            file: relative(process.cwd(), error.file),
-            line: 1,
-            target: '',
-            message: error.message,
-        });
-    }
-    for (const file of files) {
-        const refs = await run.refs(file);
-        const relPath = relative(process.cwd(), file);
-        for (const ref of refs) {
-            try {
-                if (external.parse(ref.target)) {
-                    await run.resolveExternal(ref.target);
-                    continue;
-                }
-            }
-            catch (error) {
-                errors.push({
-                    file: relPath,
-                    line: ref.line,
-                    target: ref.target,
-                    message: `broken external link [[${ref.target}]] — ${error.message}`,
-                });
-                continue;
-            }
-            const unknownExternal = external.unknownTargetMessage(ref.target);
-            if (unknownExternal) {
-                errors.push({
-                    file: relPath,
-                    line: ref.line,
-                    target: ref.target,
-                    message: unknownExternal,
-                });
-                continue;
-            }
-            const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
-            if (ambiguous) {
-                errors.push({
-                    file: relPath,
-                    line: ref.line,
-                    target: ref.target,
-                    message: ambiguousRefMessage(ref.target, ambiguous, suggested),
-                });
-            }
-            else if (!sectionIds.has(resolved.toLowerCase())) {
-                // Try resolving as a repository path or source symbol.
-                const sourceErr = await run.resolveRepositoryLink(ref.target, () => repositoryRefError(ref.target, projectRoot, run.sourceSymbolOptions()));
-                if (sourceErr !== null) {
-                    errors.push({
-                        file: relPath,
-                        line: ref.line,
-                        target: ref.target,
-                        message: sourceErr,
-                    });
-                }
-            }
-        }
-    }
-    return { errors };
-}
-// --- Relative link validation ---
-export async function checkLinks(latticeDir, context) {
-    const run = context ?? new CheckRunContext(latticeDir, dirname(latticeDir));
-    const files = await run.markdownFiles();
-    const errors = [];
-    for (const file of files) {
-        const links = await run.links(file);
-        const relPath = toPosix(relative(process.cwd(), file));
-        for (const diagnostic of await run.diagnostics(file)) {
-            if (diagnostic.rule !== 'markdown-reference-definition' &&
-                diagnostic.rule !== 'markdown-path-separator') {
-                continue;
-            }
-            errors.push({
-                file: relPath,
-                line: diagnostic.line,
-                target: diagnostic.target,
-                message: diagnostic.message,
-            });
-        }
-        for (const link of links) {
-            if ('identifier' in link)
-                continue;
-            const target = parseLocalMarkdownTarget(link.url);
-            if (target === null)
-                continue;
-            if (target.kind === 'invalid-backslash')
-                continue;
-            const abs = target.path ? resolve(dirname(file), target.path) : file;
-            if (!existsSync(abs)) {
-                const kind = link.kind === 'image' ? 'image' : 'link';
-                const shown = toPosix(relative(process.cwd(), abs));
-                errors.push({
-                    file: relPath,
-                    line: link.line,
-                    target: link.url,
-                    message: `broken ${kind} (${link.url}) — file "${shown}" not found`,
-                });
-                continue;
-            }
-            if (target.fragment &&
-                extname(abs).toLowerCase() === '.md' &&
-                link.kind !== 'image') {
-                const headings = await run.headings(abs);
-                if (!headings.has(target.fragment)) {
-                    const shown = toPosix(relative(process.cwd(), abs));
-                    errors.push({
-                        file: relPath,
-                        line: link.line,
-                        target: link.url,
-                        message: `broken link (${link.url}) — heading "#${target.fragment}" not found in "${shown}"`,
-                    });
-                }
-            }
-        }
-    }
-    return errors;
-}
-export async function checkCodeRefs(latticeDir, projectRoot = dirname(latticeDir), context) {
-    const run = context ?? new CheckRunContext(latticeDir, projectRoot);
-    const [{ sectionIds, fileIndex, slugIndex }, scan, external] = await Promise.all([
-        run.sectionIndex(),
-        run.codeRefs(),
-        run.externalResolver(),
-    ]);
-    const errors = [];
-    for (const error of external.snapshot.errors) {
-        errors.push({
-            file: relative(process.cwd(), error.file),
-            line: 1,
-            target: '',
-            message: error.message,
-        });
-    }
-    const mentionedSections = new Set();
-    for (const ref of scan.refs) {
-        try {
-            const externalTarget = profileTimeSync(run.profile, 'classify code-reference target', () => external.parse(ref.target), ref.target);
-            if (externalTarget) {
-                await run.resolveExternal(ref.target);
-                continue;
-            }
-        }
-        catch (error) {
-            errors.push({
-                file: relative(process.cwd(), join(projectRoot, ref.file)),
-                line: ref.line,
-                target: ref.target,
-                message: `@lat: [[${ref.target}]] — ${error.message}`,
-            });
-            continue;
-        }
-        const unknownExternal = profileTimeSync(run.profile, 'check unknown external handle', () => external.unknownTargetMessage(ref.target), ref.target);
-        if (unknownExternal) {
-            errors.push({
-                file: relative(process.cwd(), join(projectRoot, ref.file)),
-                line: ref.line,
-                target: ref.target,
-                message: `@lat: [[${ref.target}]] — ${unknownExternal}`,
-            });
-            continue;
-        }
-        const { resolved, ambiguous, suggested } = profileTimeSync(run.profile, 'resolve internal code reference', () => resolveRef(ref.target, sectionIds, fileIndex, slugIndex), ref.target);
-        mentionedSections.add(resolved.toLowerCase());
-        const displayPath = relative(process.cwd(), join(projectRoot, ref.file));
-        if (ambiguous) {
-            errors.push({
-                file: displayPath,
-                line: ref.line,
-                target: ref.target,
-                message: ambiguousRefMessage(ref.target, ambiguous, suggested),
-            });
-        }
-        else if (!sectionIds.has(resolved.toLowerCase())) {
-            errors.push({
-                file: displayPath,
-                line: ref.line,
-                target: ref.target,
-                message: `@lat: [[${ref.target}]] — no matching section found`,
-            });
-        }
-    }
-    const files = await run.markdownFiles();
-    for (const file of files) {
-        const fm = await run.frontmatter(file);
-        if (!fm.requireCodeMention)
-            continue;
-        const fileSections = flattenSections(await run.sections(file));
-        const leafSections = fileSections.filter((section) => section.children.length === 0);
-        const relPath = relative(process.cwd(), file);
-        for (const leaf of leafSections) {
-            if (!mentionedSections.has(leaf.id.toLowerCase())) {
-                errors.push({
-                    file: relPath,
-                    line: leaf.startLine,
-                    target: leaf.id,
-                    message: `section "${leaf.id}" requires a code mention but none found`,
-                });
-            }
-        }
-    }
-    return { errors };
-}
-/**
- * Extract the immediate (first-level) entries from walkEntries results.
- * Returns unique file and directory names visible in a given directory.
- */
-function immediateEntries(walkedPaths) {
-    const entries = new Set();
-    for (const p of walkedPaths) {
-        const slash = p.indexOf('/');
-        entries.add(slash === -1 ? p : p.slice(0, slash));
-    }
-    return [...entries].sort();
-}
-/**
- * Parse bullet items from an index file. Recognizes both the legacy
- * hand-written form (`- [[name]] — description`) and the generated form
- * written by `lat check --fix` / `lat check index --fix`
- * (`- [Title](name) — summary`) — the two do not collide because the second
- * only matches when a `(` immediately follows the closing `]`, which never
- * happens in a `[[...]]` wiki link.
- */
-function parseIndexEntries(content) {
-    const names = new Set();
-    const lines = content.split('\n');
-    const fenced = fencedLineMask(lines);
-    const unfencedContent = lines.map((l, i) => (fenced[i] ? '' : l)).join('\n');
-    const wikiRe = /^- \[\[([^\]]+?)(?:\|[^\]]+)?\]\]/gm;
-    let match;
-    while ((match = wikiRe.exec(unfencedContent)) !== null) {
-        names.add(match[1]);
-    }
-    // Label allows escaped brackets (`\]`, `\[`) without ending the match early.
-    const mdRe = /^- \[((?:\\.|[^\]])*)\]\(([^)]*)\)/gm;
-    while ((match = mdRe.exec(unfencedContent)) !== null) {
-        const name = indexEntryNameFromDest(match[2]);
-        if (name !== null)
-            names.add(entryToStem(name));
-    }
-    return names;
-}
-/**
- * Convert a filesystem entry name to its wiki link stem.
- * Strips `.md` extension from files; directories stay as-is.
- */
-function entryToStem(name) {
-    return name.endsWith('.md') ? name.slice(0, -3) : name;
-}
-/** Generate a bullet-list snippet for the given entry names. */
-function indexSnippet(entries) {
-    return entries.map((e) => `- [[${entryToStem(e)}]] — <describe>`).join('\n');
-}
-export async function checkIndex(latticeDir, context, opts = {}) {
-    const run = context ?? new CheckRunContext(latticeDir, dirname(latticeDir));
-    const errors = [];
-    const allPaths = await run.entries();
-    const referencedResources = new Set();
-    for (const file of await run.markdownFiles()) {
-        for (const link of await run.links(file)) {
-            if ('identifier' in link)
-                continue;
-            const target = parseLocalMarkdownTarget(link.url);
-            if (!target || target.kind === 'invalid-backslash' || !target.path) {
-                continue;
-            }
-            const absolutePath = resolve(dirname(file), target.path);
-            const resourcePath = toPosix(relative(latticeDir, absolutePath));
-            if (resourcePath &&
-                resourcePath !== '..' &&
-                !resourcePath.startsWith('../') &&
-                !resourcePath.toLowerCase().endsWith('.md')) {
-                referencedResources.add(resourcePath);
-            }
-        }
-    }
-    // Flag non-.md files unless Markdown reaches them as local resources. The
-    // machine-local external override is the other intentional non-Markdown
-    // configuration file in the vault.
-    for (const p of allPaths) {
-        const name = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
-        if (!name.endsWith('.md') &&
-            p !== 'config.local.yaml' &&
-            !referencedResources.has(p)) {
-            const relDir = basename(latticeDir) + '/';
-            errors.push({
-                dir: relDir,
-                message: `"${p}" is not a .md file or a referenced local resource — remove it or link to it from Markdown`,
-            });
-        }
-    }
-    // Only .md files participate in index validation
-    const mdPaths = allPaths.filter((p) => p.endsWith('.md'));
-    // Collect all directories to check (including root, represented as '')
-    const dirs = new Set(['']);
-    for (const p of mdPaths) {
-        const parts = p.split('/');
-        // Add every directory prefix
-        for (let i = 1; i < parts.length; i++) {
-            dirs.add(parts.slice(0, i).join('/'));
-        }
-    }
-    // Deepest directories first: a subdirectory's index must already be
-    // regenerated before its parent index reads a title/summary from it.
-    const orderedDirs = [...dirs].sort((a, b) => b.split('/').length - a.split('/').length);
-    for (const dir of orderedDirs) {
-        // Determine the index file name and its expected path.
-        // The index file shares the directory's name — for `lat.md/` it's `lat.md`,
-        // for a subdir `api/` it's `api.md`.
-        const dirName = dir === '' ? basename(latticeDir) : dir.split('/').pop();
-        const indexFileName = dirName.endsWith('.md') ? dirName : dirName + '.md';
-        const indexRelPath = dir === '' ? indexFileName : dir + '/' + indexFileName;
-        // Get the immediate children of this directory
-        const prefix = dir === '' ? '' : dir + '/';
-        const childPaths = mdPaths
-            .filter((p) => p.startsWith(prefix) && p !== indexRelPath)
-            .map((p) => p.slice(prefix.length));
-        const children = immediateEntries(childPaths);
-        if (children.length === 0)
-            continue;
-        // Check if the index file exists
-        const indexFullPath = join(latticeDir, indexRelPath);
-        let content;
-        try {
-            content = await run.content(indexFullPath);
-        }
-        catch {
-            content = null;
-        }
-        if (content === null) {
-            if (opts.fix) {
-                const refusal = await writeGeneratedIndex(latticeDir, dir, indexFullPath, dirName, null, children);
-                if (refusal)
-                    errors.push(refusal);
-                continue;
-            }
-            const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
-            errors.push({
-                dir: relDir,
-                message: `missing index file "${indexRelPath}" — create it with a directory listing:\n\n${indexSnippet(children)}`,
-                snippet: indexSnippet(children),
-            });
-            continue;
-        }
-        // Parse existing entries and validate.
-        // Listed entries are wiki link stems (no .md extension).
-        // Children are filesystem names (with .md for files, bare for dirs).
-        const listed = parseIndexEntries(content);
-        const childStems = new Set(children.map(entryToStem));
-        const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
-        const missing = [];
-        for (const child of children) {
-            if (!listed.has(entryToStem(child))) {
-                missing.push(child);
-            }
-        }
-        const indexStem = entryToStem(indexFileName);
-        const stale = [];
-        for (const name of listed) {
-            if (!childStems.has(name) && name !== indexStem) {
-                stale.push(name);
-            }
-        }
-        if (missing.length === 0 && stale.length === 0)
-            continue;
-        if (opts.fix) {
-            const refusal = await writeGeneratedIndex(latticeDir, dir, indexFullPath, dirName, content, children);
-            if (refusal)
-                errors.push(refusal);
-            continue;
-        }
-        if (missing.length > 0) {
-            errors.push({
-                dir: relDir,
-                message: `"${indexRelPath}" is missing entries — add:\n\n${indexSnippet(missing)}`,
-                snippet: indexSnippet(missing),
-            });
-        }
-        for (const name of stale) {
-            errors.push({
-                dir: relDir,
-                message: `"${indexRelPath}" lists "[[${name}]]" but it does not exist`,
-            });
-        }
-    }
-    return errors;
-}
-/**
- * Build entry sources for a directory's children and write the generated
- * index. Returns an IndexError describing a refusal if the index path (or
- * the temporary path used to write it) is a symlink; returns null on
- * success.
- *
- * The write never follows a symlink: it writes to a temp file in the same
- * directory (created with O_EXCL, so a pre-planted symlink there is refused
- * rather than written through) and renames it over the target, since rename
- * replaces a symlink rather than following it.
- */
-async function writeGeneratedIndex(latticeDir, dir, indexFullPath, dirName, existingContent, children) {
-    const relIndexPath = relative(latticeDir, indexFullPath);
-    const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
-    try {
-        const stat = await lstat(indexFullPath);
-        if (stat.isSymbolicLink()) {
-            return {
-                dir: relDir,
-                message: `refusing to write generated index "${relIndexPath}" — it is a symlink`,
-            };
-        }
-    }
-    catch {
-        // Does not exist yet — fine, we're creating it.
-    }
-    const { renderIndexEntries, spliceIndexContent } = await import('./gen-index.js');
-    const entries = children.map((child) => {
-        const isDir = !child.endsWith('.md');
-        const dest = isDir ? `${child}/${child}.md` : child;
-        const readFrom = isDir
-            ? join(latticeDir, dir, child, `${child}.md`)
-            : join(latticeDir, dir, child);
-        return { name: child, dest, readFrom };
-    });
-    const rendered = await renderIndexEntries(entries);
-    const dirLabel = dirName.endsWith('.md') ? dirName.slice(0, -3) : dirName;
-    const spliced = spliceIndexContent(existingContent, dirLabel, rendered);
-    if (!spliced.ok) {
-        return {
-            dir: relDir,
-            message: `refusing to write generated index "${relIndexPath}" — ${spliced.message}`,
-        };
-    }
-    const newContent = spliced.content;
-    const tempPath = `${indexFullPath}.tmp`;
-    try {
-        const tempStat = await lstat(tempPath);
-        if (tempStat.isSymbolicLink() || tempStat.isFile()) {
-            // Something is already at the temp path (possibly a pre-planted
-            // symlink). Refuse rather than write through or over it.
-            //
-            // This also catches a leftover temp file from a run killed between the
-            // write and the rename, which would otherwise block --fix for this
-            // directory forever. That case is harmless to clear, but the reader
-            // cannot tell the two apart from here, so say what to do rather than
-            // deleting a file this command was never asked to remove.
-            return {
-                dir: relDir,
-                message: `refusing to write generated index "${relIndexPath}" — its temporary write path "${relative(latticeDir, tempPath)}" already exists. Inspect it, then delete it to allow --fix to proceed.`,
-            };
-        }
-    }
-    catch {
-        // Nothing at the temp path — fine.
-    }
-    try {
-        // 'wx' is the load-bearing flag, not a detail: it fails rather than
-        // follows if anything appeared at the temp path since the lstat above,
-        // which closes the window between the two checks.
-        await writeFile(tempPath, newContent, { encoding: 'utf-8', flag: 'wx' });
-    }
-    catch (err) {
-        return {
-            dir: relDir,
-            message: `refusing to write generated index "${relIndexPath}" — could not create temporary write path "${relative(latticeDir, tempPath)}" (${err.message})`,
-        };
-    }
-    try {
-        await rename(tempPath, indexFullPath);
-    }
-    catch (err) {
-        await unlink(tempPath).catch(() => { });
-        throw err;
-    }
-    return null;
-}
-// --- Section structure validation ---
-export async function checkSections(latticeDir, projectRoot = dirname(latticeDir), context) {
-    const run = context ?? new CheckRunContext(latticeDir, projectRoot);
-    const files = await run.markdownFiles();
-    const errors = [];
-    for (const file of files) {
-        const relPath = relative(process.cwd(), file);
-        for (const diagnostic of await run.diagnostics(file)) {
-            if (diagnostic.rule !== 'section-leading-paragraph')
-                continue;
-            errors.push({
-                file: relPath,
-                line: diagnostic.line,
-                target: diagnostic.target,
-                message: diagnostic.message,
-            });
-        }
-    }
-    return errors;
-}
-// --- Formatting helpers (shared by all check commands) ---
-function formatCheckErrors(errors, s) {
-    const lines = [];
-    for (const err of errors) {
-        lines.push('');
-        const loc = s.cyan(err.file + ':' + err.line);
-        const [first, ...rest] = err.message.split('\n');
-        lines.push(`- ${loc}: ${s.red(first)}`);
-        for (const line of rest) {
-            lines.push(`  ${s.red(line)}`);
-        }
-    }
-    return lines;
-}
-function formatCheckIndexErrors(errors, s) {
-    const lines = [];
-    for (const err of errors) {
-        lines.push('');
-        const loc = s.cyan(err.dir);
-        const [first, ...rest] = err.message.split('\n');
-        lines.push(`- ${loc}: ${s.red(first)}`);
-        for (const line of rest) {
-            lines.push(`  ${s.red(line)}`);
-        }
-    }
-    return lines;
-}
-function formatErrorCount(count, s) {
-    return s.red(`\n${count} error${count === 1 ? '' : 's'} found`);
-}
-export async function checkAllCommand(ctx, options = {}) {
-    const startTime = performance.now();
-    const profile = options.profile ? new TimingProfiler() : undefined;
-    // `--fix` is index-only: an index is derived from frontmatter, so it can be
-    // regenerated. Nothing else `lat check` reports has a mechanical fix.
-    //
-    // A fixing run also has to finish before any other check starts. The checks
-    // below run concurrently over one shared parse cache, and --fix rewrites the
-    // very files they read; interleaving that write with those reads would make
-    // the run's verdict depend on scheduling. So it gets its own context, and
-    // the readers get a fresh one built after the writing is done.
-    const fixIndexErrors = options.fix
-        ? await profileTime(profile, 'generate directory indexes', () => checkIndex(ctx.latDir, new CheckRunContext(ctx.latDir, ctx.projectRoot, profile), { fix: true }))
-        : null;
-    const run = new CheckRunContext(ctx.latDir, ctx.projectRoot, profile);
-    const [md, linkErrors, code, checkedIndexErrors, sectionErrors, modeErrors, statusErrors, fmErrors, coverageErrors,] = await Promise.all([
-        profileTime(profile, 'check Markdown wiki links', () => checkMd(ctx.latDir, ctx.projectRoot, run)),
-        profileTime(profile, 'check relative Markdown links', () => checkLinks(ctx.latDir, run)),
-        profileTime(profile, 'check @lat code references', () => checkCodeRefs(ctx.latDir, ctx.projectRoot, run)),
-        // Already generated above when --fix is set; re-reporting it would only
-        // describe the state the fix just left behind.
-        fixIndexErrors
-            ? Promise.resolve([])
-            : profileTime(profile, 'check directory indexes', () => checkIndex(ctx.latDir, run)),
-        profileTime(profile, 'check section structure', () => checkSections(ctx.latDir, ctx.projectRoot, run)),
-        profileTime(profile, 'check Diátaxis modes', () => checkMode(ctx.latDir, ctx.projectRoot)),
-        profileTime(profile, 'check review status', () => checkStatus(ctx.latDir, ctx.projectRoot)),
-        profileTime(profile, 'check frontmatter placement', () => checkFrontmatter(ctx.latDir, ctx.projectRoot)),
-        profileTime(profile, 'check documentation coverage', () => checkCoverage(ctx.latDir, ctx.projectRoot)),
-    ]);
-    const indexErrors = fixIndexErrors ?? checkedIndexErrors;
-    const elapsed = performance.now() - startTime;
-    const allErrors = [
-        ...new Map([...md.errors, ...linkErrors, ...code.errors].map((error) => [
-            `${error.file}\0${error.line}\0${error.target}\0${error.message}`,
-            error,
-        ])).values(),
-    ];
-    const s = ctx.styler;
-    const elapsedStr = elapsed < 1000
-        ? `${Math.round(elapsed)}ms`
-        : `${(elapsed / 1000).toFixed(1)}s`;
-    const lines = profile ? profile.format(elapsed) : [];
-    // Init version warning first — user should fix setup before addressing errors
-    if (!ctx.headless) {
-        const storedVersion = readInitVersion(ctx.latDir);
-        if (storedVersion === null) {
-            if (lines.length > 0)
-                lines.push('');
-            lines.push(s.yellow('Warning:') +
-                ' No init version recorded — run ' +
-                s.cyan('lat init') +
-                ' to set up agent hooks and configuration.');
-        }
-        else if (storedVersion < INIT_VERSION) {
-            if (lines.length > 0)
-                lines.push('');
-            lines.push(s.yellow('Warning:') +
-                ' Your setup is outdated (v' +
-                storedVersion +
-                ' → v' +
-                INIT_VERSION +
-                '). Re-run ' +
-                s.cyan('lat init') +
-                ' to update agent hooks and configuration.');
-        }
-    }
-    lines.push(...formatCheckErrors(allErrors, s));
-    lines.push(...formatCheckIndexErrors(indexErrors, s));
-    lines.push(...formatCheckErrors(sectionErrors, s));
-    lines.push(...formatCheckErrors(modeErrors, s));
-    lines.push(...formatCheckErrors(statusErrors, s));
-    lines.push(...formatCheckErrors(fmErrors, s));
-    lines.push(...formatCheckErrors(coverageErrors, s));
-    const totalErrors = allErrors.length +
-        indexErrors.length +
-        sectionErrors.length +
-        modeErrors.length +
-        statusErrors.length +
-        fmErrors.length +
-        coverageErrors.length;
-    if (totalErrors > 0) {
-        lines.push(formatErrorCount(totalErrors, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green(`All checks passed in ${elapsedStr}`));
-    // Suggest ripgrep if check was slow (>1s) and rg is not available
-    if (elapsed > 1000) {
-        const { hasRipgrep } = await import('../code-refs.js');
-        if (!(await hasRipgrep())) {
-            lines.push(s.yellow('Tip:') +
-                ' Install ' +
-                s.cyan('ripgrep') +
-                ' (rg) for faster code scanning.' +
-                ' See https://github.com/BurntSushi/ripgrep#installation');
-        }
-    }
-    return { output: lines.join('\n') };
-}
-export async function checkMdCommand(ctx) {
-    const { errors } = await checkMd(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [];
-    lines.push(...formatCheckErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('md: All links OK'));
-    return { output: lines.join('\n') };
-}
-export async function checkLinksCommand(ctx) {
-    const errors = await checkLinks(ctx.latDir);
-    const s = ctx.styler;
-    const lines = [];
-    lines.push(...formatCheckErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('links: All relative links resolve'));
-    return { output: lines.join('\n') };
-}
-export async function checkCodeRefsCommand(ctx) {
-    const { errors } = await checkCodeRefs(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [];
-    lines.push(...formatCheckErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('code-refs: All references OK'));
-    return { output: lines.join('\n') };
-}
-export async function checkIndexCommand(ctx, opts = {}) {
-    const errors = await checkIndex(ctx.latDir, undefined, opts);
-    const s = ctx.styler;
-    const lines = [];
-    if (opts.fix) {
-        lines.push(s.green('index: directory index files regenerated'));
-        if (errors.length > 0) {
-            lines.push(...formatCheckIndexErrors(errors, s));
-            lines.push(formatErrorCount(errors.length, s));
-            return { output: lines.join('\n'), isError: true };
-        }
-        return { output: lines.join('\n') };
-    }
-    lines.push(...formatCheckIndexErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('index: All directory index files OK'));
-    return { output: lines.join('\n') };
-}
-export async function checkSectionsCommand(ctx) {
-    const errors = await checkSections(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [];
-    lines.push(...formatCheckErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('sections: All sections have valid leading paragraphs'));
-    return { output: lines.join('\n') };
-}
-export async function checkModeCommand(ctx) {
-    const errors = await checkMode(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [];
-    lines.push(...formatCheckErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('mode: All documents match their Diátaxis mode'));
-    return { output: lines.join('\n') };
-}
-export async function checkStatusCommand(ctx) {
-    const errors = await checkStatus(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [];
-    lines.push(...formatCheckErrors(errors, s));
-    if (errors.length > 0) {
-        lines.push(formatErrorCount(errors.length, s));
-        return { output: lines.join('\n'), isError: true };
-    }
-    lines.push(s.green('status: Every recorded review matches its document'));
-    return { output: lines.join('\n') };
-}