@plebeiantech/lat.md 0.12.3-fork.8 → 0.13.4-fork.1

package/dist/src/cli/check.js

@@ -1,781 +0,0 @@
-import { readFile, writeFile, lstat, rename, unlink } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { basename, dirname, extname, join, relative, resolve } from 'node:path';
-import { listLatticeFiles, loadAllSections, extractLinks, extractRefs, flattenSections, parseFrontmatter, parseSections, buildFileIndex, buildSectionSlugIndex, resolveRef, } from '../lattice.js';
-import { scanCodeRefs } from '../code-refs.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 { SOURCE_EXTENSIONS, clearSymbolCache } from '../source-parser.js';
-import { toPosix, walkEntries } from '../walk.js';
-import { INIT_VERSION, readInitVersion } from '../init-version.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');
-}
-function countByExt(paths) {
-    const stats = {};
-    for (const p of paths) {
-        const ext = extname(p) || '(no ext)';
-        stats[ext] = (stats[ext] || 0) + 1;
-    }
-    return stats;
-}
-function isSourcePath(target) {
-    const hashIdx = target.indexOf('#');
-    const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
-    const ext = extname(filePart);
-    return SOURCE_EXTENSIONS.has(ext);
-}
-/**
- * Try resolving a wiki link target as a source code reference.
- * Returns null if the reference is valid, or an error message string.
- */
-export async function sourceRefError(target, projectRoot) {
-    if (!isSourcePath(target)) {
-        // Check if it looks like a file path with an unsupported extension
-        const hashIdx = target.indexOf('#');
-        const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
-        const ext = extname(filePart);
-        if (ext && hashIdx !== -1) {
-            const supported = [...SOURCE_EXTENSIONS].sort().join(', ');
-            return `broken link [[${target}]] — unsupported file extension "${ext}". Supported: ${supported}`;
-        }
-        return `broken link [[${target}]] — no matching section found`;
-    }
-    const hashIdx = target.indexOf('#');
-    const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
-    const symbolPart = hashIdx === -1 ? '' : target.slice(hashIdx + 1);
-    const absPath = join(projectRoot, filePart);
-    if (!existsSync(absPath)) {
-        return `broken link [[${target}]] — file "${filePart}" not found`;
-    }
-    if (!symbolPart) {
-        // File-only link with no symbol — valid as long as file exists
-        return null;
-    }
-    try {
-        const { resolveSourceSymbol } = await import('../source-parser.js');
-        const { found, error } = await resolveSourceSymbol(filePart, symbolPart, projectRoot);
-        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)) {
-    clearSymbolCache();
-    const files = await listLatticeFiles(latticeDir);
-    const allSections = await loadAllSections(latticeDir, projectRoot);
-    const flat = flattenSections(allSections);
-    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-    const fileIndex = buildFileIndex(allSections);
-    const slugIndex = buildSectionSlugIndex(allSections);
-    const errors = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const refs = extractRefs(file, content, projectRoot);
-        const relPath = relative(process.cwd(), file);
-        for (const ref of refs) {
-            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 source code reference (e.g. [[src/foo.ts#bar]])
-                const sourceErr = await sourceRefError(ref.target, projectRoot);
-                if (sourceErr !== null) {
-                    errors.push({
-                        file: relPath,
-                        line: ref.line,
-                        target: ref.target,
-                        message: sourceErr,
-                    });
-                }
-            }
-        }
-    }
-    return { errors, files: countByExt(files) };
-}
-function decodeLinkPart(value) {
-    try {
-        return decodeURIComponent(value);
-    }
-    catch {
-        return value;
-    }
-}
-/** Parse a local markdown destination without confusing escaped #/? in paths. */
-function localLinkTarget(url) {
-    const u = url.trim();
-    if (u.startsWith('/'))
-        return null;
-    const windowsDrivePath = /^[a-zA-Z]:\\/.test(u);
-    if (!windowsDrivePath && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(u)) {
-        return null;
-    }
-    // Split before decoding: `%23` and `%3F` decode to `#` and `?`, which would
-    // then truncate a filename that legitimately contains them.
-    const queryAt = u.indexOf('?');
-    const fragmentAt = u.indexOf('#');
-    const pathEnd = Math.min(queryAt === -1 ? u.length : queryAt, fragmentAt === -1 ? u.length : fragmentAt);
-    const rawPath = u.slice(0, pathEnd);
-    const path = rawPath === '' ? null : decodeLinkPart(rawPath);
-    const fragment = fragmentAt === -1 ? null : decodeLinkPart(u.slice(fragmentAt + 1));
-    if (rawPath === '' && fragment === null)
-        return null;
-    if (path?.includes('\\'))
-        return { kind: 'invalid-backslash' };
-    return {
-        kind: 'target',
-        path,
-        fragment,
-    };
-}
-export async function checkLinks(latticeDir) {
-    const files = await listLatticeFiles(latticeDir);
-    const errors = [];
-    const headingCache = new Map();
-    const headingsFor = async (file) => {
-        const cached = headingCache.get(file);
-        if (cached)
-            return cached;
-        const content = await readFile(file, 'utf-8');
-        const headings = new Set(flattenSections(parseSections(file, content)).map((section) => section.githubSlug));
-        headingCache.set(file, headings);
-        return headings;
-    };
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const relPath = toPosix(relative(process.cwd(), file));
-        for (const link of extractLinks(content)) {
-            if ('identifier' in link) {
-                const kind = link.kind === 'imageReference' ? 'image' : 'link';
-                errors.push({
-                    file: relPath,
-                    line: link.line,
-                    target: link.identifier,
-                    message: `undefined ${kind} reference (${link.source}) — definition "[${link.identifier}]" not found`,
-                });
-                continue;
-            }
-            const target = localLinkTarget(link.url);
-            if (target === null)
-                continue;
-            if (target.kind === 'invalid-backslash') {
-                const kind = link.kind === 'image' ? 'image' : 'link';
-                errors.push({
-                    file: relPath,
-                    line: link.line,
-                    target: link.url,
-                    message: `invalid ${kind} (${link.url}) — backslashes are not path ` +
-                        'separators in Markdown; use "/" instead',
-                });
-                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 headingsFor(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)) {
-    const allSections = await loadAllSections(latticeDir, projectRoot);
-    const flat = flattenSections(allSections);
-    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-    const fileIndex = buildFileIndex(allSections);
-    const slugIndex = buildSectionSlugIndex(allSections);
-    const scan = await scanCodeRefs(projectRoot);
-    const errors = [];
-    const mentionedSections = new Set();
-    for (const ref of scan.refs) {
-        const { resolved, ambiguous, suggested } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
-        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 listLatticeFiles(latticeDir);
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const fm = parseFrontmatter(content);
-        if (!fm.requireCodeMention)
-            continue;
-        const sections = parseSections(file, content, projectRoot);
-        const fileSections = flattenSections(sections);
-        const leafSections = fileSections.filter((s) => s.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, files: countByExt(scan.files) };
-}
-/**
- * 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, opts = {}) {
-    const errors = [];
-    const allPaths = await walkEntries(latticeDir);
-    // Flag non-.md files — only markdown belongs in the checked directory.
-    for (const p of allPaths) {
-        const name = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
-        if (!name.endsWith('.md')) {
-            const relDir = basename(latticeDir) + '/';
-            errors.push({
-                dir: relDir,
-                message: `"${p}" is not a .md file — only markdown files belong in the checked directory`,
-            });
-        }
-    }
-    // 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 readFile(indexFullPath, 'utf-8');
-        }
-        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 ---
-/** Max characters for the first paragraph of a section (excluding [[wiki links]]). */
-const MAX_BODY_LENGTH = 250;
-/** Count body text length excluding `[[...]]` wiki link markers and content. */
-function bodyTextLength(body) {
-    return body.replace(/\[\[[^\]]*\]\]/g, '').length;
-}
-export async function checkSections(latticeDir, projectRoot = dirname(latticeDir)) {
-    const files = await listLatticeFiles(latticeDir);
-    const errors = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const sections = parseSections(file, content, projectRoot);
-        const flat = flattenSections(sections);
-        const relPath = relative(process.cwd(), file);
-        for (const section of flat) {
-            if (!section.firstParagraph) {
-                errors.push({
-                    file: relPath,
-                    line: section.startLine,
-                    target: section.id,
-                    message: `section "${section.id}" has no leading paragraph. ` +
-                        `Every section must start with a brief overview (≤${MAX_BODY_LENGTH} chars) ` +
-                        `summarizing what it documents — this powers search snippets and command output.`,
-                });
-                continue;
-            }
-            const len = bodyTextLength(section.firstParagraph);
-            if (len > MAX_BODY_LENGTH) {
-                errors.push({
-                    file: relPath,
-                    line: section.startLine,
-                    target: section.id,
-                    message: `section "${section.id}" leading paragraph is ${len} characters ` +
-                        `(max ${MAX_BODY_LENGTH}, excluding [[wiki links]]). ` +
-                        `Keep the first paragraph brief — it serves as the section's summary ` +
-                        `in search results and command output. Use subsequent paragraphs for details.`,
-                });
-            }
-        }
-    }
-    return errors;
-}
-// --- Formatting helpers (shared by all check commands) ---
-function formatFileStats(files, s) {
-    const entries = Object.entries(files).sort(([a], [b]) => a.localeCompare(b));
-    return s.dim(`Scanned ${entries.map(([ext, n]) => `${n} ${ext}`).join(', ')}`);
-}
-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`);
-}
-// --- Unified command functions ---
-export async function checkAllCommand(ctx, opts = {}) {
-    const startTime = Date.now();
-    const md = await checkMd(ctx.latDir, ctx.projectRoot);
-    const linkErrors = await checkLinks(ctx.latDir);
-    const code = await checkCodeRefs(ctx.latDir, ctx.projectRoot);
-    // `--fix` is index-only: an index is derived from frontmatter, so it can be
-    // regenerated. Nothing else `lat check` reports has a mechanical fix.
-    const indexErrors = await checkIndex(ctx.latDir, opts);
-    const sectionErrors = await checkSections(ctx.latDir, ctx.projectRoot);
-    const modeErrors = await checkMode(ctx.latDir, ctx.projectRoot);
-    const statusErrors = await checkStatus(ctx.latDir, ctx.projectRoot);
-    const fmErrors = await checkFrontmatter(ctx.latDir, ctx.projectRoot);
-    const coverageErrors = await checkCoverage(ctx.latDir, ctx.projectRoot);
-    const elapsed = Date.now() - startTime;
-    const allErrors = [...md.errors, ...linkErrors, ...code.errors];
-    const allFiles = { ...md.files };
-    for (const [ext, n] of Object.entries(code.files)) {
-        allFiles[ext] = (allFiles[ext] || 0) + n;
-    }
-    const s = ctx.styler;
-    const elapsedStr = elapsed < 1000 ? `${elapsed}ms` : `${(elapsed / 1000).toFixed(1)}s`;
-    const lines = [
-        formatFileStats(allFiles, s) + s.dim(` in ${elapsedStr}`),
-    ];
-    // Init version warning first — user should fix setup before addressing errors
-    if (!ctx.headless) {
-        const storedVersion = readInitVersion(ctx.latDir);
-        if (storedVersion === null) {
-            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) {
-            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'));
-    // 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, files } = await checkMd(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [formatFileStats(files, s)];
-    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, files } = await checkCodeRefs(ctx.latDir, ctx.projectRoot);
-    const s = ctx.styler;
-    const lines = [formatFileStats(files, s)];
-    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, 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') };
-}