lat.md 0.5.0 → 0.7.0

package/dist/src/cli/check.d.ts

@@ -1,4 +1,4 @@
-import type { CliContext } from './context.js';
+import type { CmdContext, CmdResult } from '../context.js';
 export type CheckError = {
     file: string;
     line: number;
@@ -19,7 +19,9 @@ export type IndexError = {
     snippet?: string;
 };
 export declare function checkIndex(latticeDir: string): Promise<IndexError[]>;
-export declare function checkMdCmd(ctx: CliContext): Promise<void>;
-export declare function checkCodeRefsCmd(ctx: CliContext): Promise<void>;
-export declare function checkIndexCmd(ctx: CliContext): Promise<void>;
-export declare function checkAllCmd(ctx: CliContext): Promise<void>;
+export declare function checkSections(latticeDir: string): Promise<CheckError[]>;
+export declare function checkAllCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkMdCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkCodeRefsCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkIndexCommand(ctx: CmdContext): Promise<CmdResult>;
+export declare function checkSectionsCommand(ctx: CmdContext): Promise<CmdResult>;

package/dist/src/cli/check.js

@@ -1,8 +1,10 @@
 import { readFile } from 'node:fs/promises';
-import { basename, extname, join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, dirname, extname, join, relative } from 'node:path';
 import { listLatticeFiles, loadAllSections, extractRefs, flattenSections, parseFrontmatter, parseSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { scanCodeRefs } from '../code-refs.js';
 import { 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);
@@ -30,7 +32,68 @@ function countByExt(paths) {
     }
     return stats;
 }
+/** Source file extensions recognized for code wiki links. */
+const SOURCE_EXTS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.py',
+    '.rs',
+    '.go',
+    '.c',
+    '.h',
+]);
+function isSourcePath(target) {
+    const hashIdx = target.indexOf('#');
+    const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
+    const ext = extname(filePart);
+    return SOURCE_EXTS.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.
+ */
+async function tryResolveSourceRef(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_EXTS].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) {
+    const projectRoot = dirname(latticeDir);
     const files = await listLatticeFiles(latticeDir);
     const allSections = await loadAllSections(latticeDir);
     const flat = flattenSections(allSections);
@@ -39,7 +102,7 @@ export async function checkMd(latticeDir) {
     const errors = [];
     for (const file of files) {
         const content = await readFile(file, 'utf-8');
-        const refs = extractRefs(file, content, latticeDir);
+        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);
@@ -52,19 +115,23 @@ export async function checkMd(latticeDir) {
                 });
             }
             else if (!sectionIds.has(resolved.toLowerCase())) {
-                errors.push({
-                    file: relPath,
-                    line: ref.line,
-                    target: ref.target,
-                    message: `broken link [[${ref.target}]] — no matching section found`,
-                });
+                // Try resolving as a source code reference (e.g. [[src/foo.ts#bar]])
+                const sourceErr = await tryResolveSourceRef(ref.target, projectRoot);
+                if (sourceErr !== null) {
+                    errors.push({
+                        file: relPath,
+                        line: ref.line,
+                        target: ref.target,
+                        message: sourceErr,
+                    });
+                }
             }
         }
     }
     return { errors, files: countByExt(files) };
 }
 export async function checkCodeRefs(latticeDir) {
-    const projectRoot = join(latticeDir, '..');
+    const projectRoot = dirname(latticeDir);
     const allSections = await loadAllSections(latticeDir);
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
@@ -98,7 +165,7 @@ export async function checkCodeRefs(latticeDir) {
         const fm = parseFrontmatter(content);
         if (!fm.requireCodeMention)
             continue;
-        const sections = parseSections(file, content, latticeDir);
+        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);
@@ -151,9 +218,22 @@ function indexSnippet(entries) {
 export async function checkIndex(latticeDir) {
     const errors = [];
     const allPaths = await walkEntries(latticeDir);
+    // Flag non-.md files — only markdown belongs in lat.md/
+    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 lat.md/`,
+            });
+        }
+    }
+    // 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 allPaths) {
+    for (const p of mdPaths) {
         const parts = p.split('/');
         // Add every directory prefix
         for (let i = 1; i < parts.length; i++) {
@@ -169,7 +249,7 @@ export async function checkIndex(latticeDir) {
         const indexRelPath = dir === '' ? indexFileName : dir + '/' + indexFileName;
         // Get the immediate children of this directory
         const prefix = dir === '' ? '' : dir + '/';
-        const childPaths = allPaths
+        const childPaths = mdPaths
             .filter((p) => p.startsWith(prefix) && p !== indexRelPath)
             .map((p) => p.slice(prefix.length));
         const children = immediateEntries(childPaths);
@@ -222,84 +302,124 @@ export async function checkIndex(latticeDir) {
     }
     return errors;
 }
-function formatErrors(ctx, errors, startIdx = 0) {
-    for (let i = 0; i < errors.length; i++) {
-        const err = errors[i];
-        if (i > 0 || startIdx > 0)
-            console.error('');
-        const loc = ctx.chalk.cyan(err.file + ':' + err.line);
-        const [first, ...rest] = err.message.split('\n');
-        console.error(`- ${loc}: ${ctx.chalk.red(first)}`);
-        for (const line of rest) {
-            console.error(`  ${ctx.chalk.red(line)}`);
+// --- 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) {
+    const 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 formatIndexErrors(ctx, errors, startIdx = 0) {
-    for (let i = 0; i < errors.length; i++) {
-        if (i > 0 || startIdx > 0)
-            console.error('');
-        const loc = ctx.chalk.cyan(errors[i].dir);
-        const [first, ...rest] = errors[i].message.split('\n');
-        console.error(`- ${loc}: ${ctx.chalk.red(first)}`);
+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) {
-            console.error(`  ${ctx.chalk.red(line)}`);
+            lines.push(`  ${s.red(line)}`);
         }
     }
+    return lines;
 }
-function formatErrorCount(ctx, count) {
-    if (count > 0) {
-        console.error(ctx.chalk.red(`\n${count} error${count === 1 ? '' : 's'} found`));
+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 formatStats(ctx, stats) {
-    const entries = Object.entries(stats).sort(([a], [b]) => a.localeCompare(b));
-    const parts = entries.map(([ext, n]) => `${n} ${ext}`);
-    console.log(ctx.chalk.dim(`Scanned ${parts.join(', ')}`));
+function formatErrorCount(count, s) {
+    return s.red(`\n${count} error${count === 1 ? '' : 's'} found`);
 }
-export async function checkMdCmd(ctx) {
-    const { errors, files } = await checkMd(ctx.latDir);
-    formatStats(ctx, files);
-    formatErrors(ctx, errors);
-    formatErrorCount(ctx, errors.length);
-    if (errors.length > 0)
-        process.exit(1);
-    console.log(ctx.chalk.green('md: All links OK'));
-}
-export async function checkCodeRefsCmd(ctx) {
-    const { errors, files } = await checkCodeRefs(ctx.latDir);
-    formatStats(ctx, files);
-    formatErrors(ctx, errors);
-    formatErrorCount(ctx, errors.length);
-    if (errors.length > 0)
-        process.exit(1);
-    console.log(ctx.chalk.green('code-refs: All references OK'));
-}
-export async function checkIndexCmd(ctx) {
-    const errors = await checkIndex(ctx.latDir);
-    formatIndexErrors(ctx, errors);
-    formatErrorCount(ctx, errors.length);
-    if (errors.length > 0)
-        process.exit(1);
-    console.log(ctx.chalk.green('index: All directory index files OK'));
-}
-export async function checkAllCmd(ctx) {
+// --- Unified command functions ---
+export async function checkAllCommand(ctx) {
     const md = await checkMd(ctx.latDir);
     const code = await checkCodeRefs(ctx.latDir);
     const indexErrors = await checkIndex(ctx.latDir);
+    const sectionErrors = await checkSections(ctx.latDir);
     const allErrors = [...md.errors, ...code.errors];
     const allFiles = { ...md.files };
     for (const [ext, n] of Object.entries(code.files)) {
         allFiles[ext] = (allFiles[ext] || 0) + n;
     }
-    formatStats(ctx, allFiles);
-    formatErrors(ctx, allErrors);
-    formatIndexErrors(ctx, indexErrors, allErrors.length);
-    const totalErrors = allErrors.length + indexErrors.length;
-    formatErrorCount(ctx, totalErrors);
-    if (totalErrors > 0)
-        process.exit(1);
-    console.log(ctx.chalk.green('All checks passed'));
+    const s = ctx.styler;
+    const lines = [formatFileStats(allFiles, s)];
+    // Init version warning first — user should fix setup before addressing errors
+    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));
+    const totalErrors = allErrors.length + indexErrors.length + sectionErrors.length;
+    if (totalErrors > 0) {
+        lines.push(formatErrorCount(totalErrors, s));
+        return { output: lines.join('\n'), isError: true };
+    }
+    lines.push(s.green('All checks passed'));
     const { getLlmKey } = await import('../config.js');
     let hasKey = false;
     try {
@@ -309,10 +429,59 @@ export async function checkAllCmd(ctx) {
         // key resolution failed (e.g. empty file) — treat as missing
     }
     if (!hasKey) {
-        console.log(ctx.chalk.yellow('Warning:') +
+        lines.push(s.yellow('Warning:') +
             ' No LLM key found — semantic search (lat search) will not work.' +
             ' Provide a key via LAT_LLM_KEY, LAT_LLM_KEY_FILE, LAT_LLM_KEY_HELPER, or run ' +
-            ctx.chalk.cyan('lat init') +
+            s.cyan('lat init') +
             ' to configure.');
     }
+    return { output: lines.join('\n') };
+}
+export async function checkMdCommand(ctx) {
+    const { errors, files } = await checkMd(ctx.latDir);
+    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 checkCodeRefsCommand(ctx) {
+    const { errors, files } = await checkCodeRefs(ctx.latDir);
+    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) {
+    const errors = await checkIndex(ctx.latDir);
+    const s = ctx.styler;
+    const lines = [];
+    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);
+    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') };
 }

package/dist/src/cli/context.d.ts

@@ -1,10 +1,6 @@
-import { type ChalkInstance } from 'chalk';
-export type CliContext = {
-    latDir: string;
-    color: boolean;
-    chalk: ChalkInstance;
-};
+import type { CmdContext } from '../context.js';
+export type { CmdContext };
 export declare function resolveContext(opts: {
     dir?: string;
     color?: boolean;
-}): CliContext;
+}): CmdContext;

package/dist/src/cli/context.js

@@ -1,5 +1,18 @@
+import { dirname } from 'node:path';
 import chalk from 'chalk';
 import { findLatticeDir } from '../lattice.js';
+function makeChalkStyler() {
+    return {
+        bold: (s) => chalk.bold(s),
+        dim: (s) => chalk.dim(s),
+        red: (s) => chalk.red(s),
+        cyan: (s) => chalk.cyan(s),
+        white: (s) => chalk.white(s),
+        green: (s) => chalk.green(s),
+        yellow: (s) => chalk.yellow(s),
+        boldWhite: (s) => chalk.bold.white(s),
+    };
+}
 export function resolveContext(opts) {
     const color = opts.color !== false;
     if (!color) {
@@ -11,5 +24,6 @@ export function resolveContext(opts) {
         console.error(chalk.dim('Run `lat init` to create one.'));
         process.exit(1);
     }
-    return { latDir, color, chalk };
+    const projectRoot = dirname(latDir);
+    return { latDir, projectRoot, styler: makeChalkStyler(), mode: 'cli' };
 }

package/dist/src/cli/expand.d.ts

@@ -0,0 +1,7 @@
+import type { CmdContext, CmdResult } from '../context.js';
+/**
+ * Resolve [[refs]] in text and return the expanded output.
+ * Returns null if there are no wiki links, or if resolution fails.
+ */
+export declare function expandPrompt(ctx: CmdContext, text: string): Promise<string | null>;
+export declare function expandCommand(ctx: CmdContext, text: string): Promise<CmdResult>;

package/dist/src/cli/expand.js

@@ -0,0 +1,92 @@
+import { join, relative } from 'node:path';
+import { loadAllSections, findSections, } from '../lattice.js';
+const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
+function formatLocation(section, projectRoot) {
+    const relPath = relative(process.cwd(), join(projectRoot, section.filePath));
+    return `${relPath}:${section.startLine}-${section.endLine}`;
+}
+/**
+ * Resolve [[refs]] in text and return the expanded output.
+ * Returns null if there are no wiki links, or if resolution fails.
+ */
+export async function expandPrompt(ctx, text) {
+    const refs = [...text.matchAll(WIKI_LINK_RE)];
+    if (refs.length === 0)
+        return null;
+    const allSections = await loadAllSections(ctx.latDir);
+    const resolved = new Map();
+    const errors = [];
+    for (const match of refs) {
+        const target = match[1];
+        if (resolved.has(target))
+            continue;
+        const matches = findSections(allSections, target);
+        if (matches.length >= 1) {
+            resolved.set(target, {
+                target,
+                best: matches[0],
+                alternatives: matches.slice(1),
+            });
+        }
+        else {
+            errors.push(`No section found for [[${target}]]`);
+        }
+    }
+    if (errors.length > 0)
+        return null;
+    // Replace [[refs]] inline
+    let output = text.replace(WIKI_LINK_RE, (_match, target) => {
+        const ref = resolved.get(target);
+        return `[[${ref.best.section.id}]]`;
+    });
+    // Append context block as nested outliner
+    output += '\n\n<lat-context>\n';
+    for (const ref of resolved.values()) {
+        const isExact = ref.best.reason === 'exact match' ||
+            ref.best.reason.startsWith('file stem expanded');
+        const all = isExact ? [ref.best] : [ref.best, ...ref.alternatives];
+        if (isExact) {
+            output += `* \`[[${ref.target}]]\` is referring to:\n`;
+        }
+        else {
+            output += `* \`[[${ref.target}]]\` might be referring to either of the following:\n`;
+        }
+        for (const m of all) {
+            const reason = isExact ? '' : ` (${m.reason})`;
+            output += `  * [[${m.section.id}]]${reason}\n`;
+            output += `    * ${formatLocation(m.section, ctx.projectRoot)}\n`;
+            if (m.section.firstParagraph) {
+                output += `    * ${m.section.firstParagraph}\n`;
+            }
+        }
+    }
+    output += '</lat-context>\n';
+    return output;
+}
+export async function expandCommand(ctx, text) {
+    const result = await expandPrompt(ctx, text);
+    if (result === null) {
+        const refs = [...text.matchAll(WIKI_LINK_RE)];
+        if (refs.length === 0) {
+            return { output: text };
+        }
+        // Resolution failed — find which ref is broken
+        const allSections = await loadAllSections(ctx.latDir);
+        for (const match of refs) {
+            const target = match[1];
+            const matches = findSections(allSections, target);
+            if (matches.length === 0) {
+                const s = ctx.styler;
+                return {
+                    output: s.red(`No section found for [[${target}]]`) +
+                        ' (no exact, substring, or fuzzy matches).\n' +
+                        s.dim('Ask the user to correct the reference.'),
+                    isError: true,
+                };
+            }
+        }
+        // All refs matched individually but expansion still failed — shouldn't happen
+        return { output: text };
+    }
+    return { output: result };
+}

package/dist/src/cli/gen.js

@@ -9,9 +9,16 @@ export function readCursorRulesTemplate() {
 }
 export async function genCmd(target) {
     const normalized = target.toLowerCase();
-    if (normalized !== 'agents.md' && normalized !== 'claude.md') {
-        console.error(`Unknown target: ${target}. Supported: agents.md, claude.md`);
-        process.exit(1);
+    switch (normalized) {
+        case 'agents.md':
+        case 'claude.md':
+            process.stdout.write(readAgentsTemplate());
+            break;
+        case 'cursor-rules.md':
+            process.stdout.write(readCursorRulesTemplate());
+            break;
+        default:
+            console.error(`Unknown target: ${target}. Supported: agents.md, claude.md, cursor-rules.md`);
+            process.exit(1);
     }
-    process.stdout.write(readAgentsTemplate());
 }

package/dist/src/cli/hook.d.ts

@@ -0,0 +1 @@
+export declare function hookCmd(agent: string, event: string): Promise<void>;