lat.md 0.7.0 → 0.7.2

package/README.md

@@ -33,7 +33,7 @@ After installing, run `lat init` in the repo you want to use lat in.
 
 ## How it works
 
-Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.
+Run `lat init` to scaffold a `lat.md/` directory, then write markdown files describing your architecture, business logic, test specs — whatever matters. Link between sections using `[[file#Section#Subsection]]` syntax. Link to source code symbols with `[[src/auth.ts#validateToken]]`. Annotate source code with `// @lat: [[section-id]]` (or `# @lat: [[section-id]]` in Python) comments to tie implementation back to concepts.
 
 ```
 my-project/
@@ -53,9 +53,10 @@ my-project/
 npx lat.md init                        # scaffold a lat.md/ directory
 npx lat.md check                       # validate all wiki links and code refs
 npx lat.md locate "OAuth Flow"         # find sections by name (exact, fuzzy)
+npx lat.md section "auth#OAuth Flow"   # show a section with its links and refs
 npx lat.md refs "auth#OAuth Flow"      # find what references a section
 npx lat.md search "how do we auth?"    # semantic search via embeddings
-npx lat.md prompt "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
+npx lat.md expand "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
 ```
 
 ## Configuration

package/dist/src/cli/check.js

@@ -3,6 +3,7 @@ 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 { SOURCE_EXTENSIONS } from '../source-parser.js';
 import { walkEntries } from '../walk.js';
 import { INIT_VERSION, readInitVersion } from '../init-version.js';
 function filePart(id) {
@@ -32,23 +33,11 @@ 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);
+    return SOURCE_EXTENSIONS.has(ext);
 }
 /**
  * Try resolving a wiki link target as a source code reference.
@@ -61,7 +50,7 @@ async function tryResolveSourceRef(target, projectRoot) {
         const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
         const ext = extname(filePart);
         if (ext && hashIdx !== -1) {
-            const supported = [...SOURCE_EXTS].sort().join(', ');
+            const supported = [...SOURCE_EXTENSIONS].sort().join(', ');
             return `broken link [[${target}]] — unsupported file extension "${ext}". Supported: ${supported}`;
         }
         return `broken link [[${target}]] — no matching section found`;

package/dist/src/cli/hook.js

@@ -1,10 +1,13 @@
-import { dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { dirname, extname } from 'node:path';
 import { findLatticeDir } from '../lattice.js';
 import { plainStyler } from '../context.js';
 import { expandPrompt } from './expand.js';
 import { runSearch } from './search.js';
 import { getSection, formatSectionOutput } from './section.js';
 import { getLlmKey } from '../config.js';
+import { checkMd, checkCodeRefs, checkIndex, checkSections } from './check.js';
+import { SOURCE_EXTENSIONS } from '../source-parser.js';
 function outputPromptSubmit(context) {
     process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
@@ -74,7 +77,7 @@ async function handleUserPromptSubmit() {
         // If we can't parse stdin, still emit the reminder
     }
     const parts = [];
-    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.');
+    parts.push("Before starting work, run `lat search` with one or more queries describing the user's intent.", 'ALWAYS do this, even when the task seems straightforward — search results may reveal critical design details, protocols, or constraints.', 'Use `lat section` to read the full content of relevant matches.', 'Do not read files, write code, or run commands until you have searched.', '', 'Remember: `lat.md/` must stay in sync with the codebase. If you change code, update the relevant sections in `lat.md/` and run `lat check` before finishing.');
     const latDir = findLatticeDir();
     if (latDir && userPrompt) {
         const ctx = makeHookCtx(latDir);
@@ -106,8 +109,44 @@ async function handleUserPromptSubmit() {
     }
     outputPromptSubmit(parts.join('\n'));
 }
+/** Minimum diff size (in lines) to consider "significant" code change. */
+/** Minimum code change size (lines) before we consider flagging lat.md/ sync. */
+const DIFF_THRESHOLD = 5;
+/** lat.md/ changes below this ratio of code changes trigger a sync reminder. */
+const LATMD_RATIO = 0.05;
+/** Run `git diff --numstat` and return { codeLines, latMdLines }. */
+function analyzeDiff(projectRoot) {
+    let output;
+    try {
+        output = execSync('git diff HEAD --numstat', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+        });
+    }
+    catch {
+        return { codeLines: 0, latMdLines: 0 };
+    }
+    let codeLines = 0;
+    let latMdLines = 0;
+    // Each line: "added\tremoved\tfile" (e.g. "42\t11\tsrc/cli/hook.ts")
+    for (const line of output.split('\n')) {
+        const parts = line.split('\t');
+        if (parts.length < 3)
+            continue;
+        const added = parseInt(parts[0], 10) || 0;
+        const removed = parseInt(parts[1], 10) || 0;
+        const file = parts[2];
+        const changed = added + removed;
+        if (file.startsWith('lat.md/')) {
+            latMdLines += changed;
+        }
+        else if (SOURCE_EXTENSIONS.has(extname(file))) {
+            codeLines += changed;
+        }
+    }
+    return { codeLines, latMdLines };
+}
 async function handleStop() {
-    // Only emit the reminder if we're in a project with lat.md
     const latDir = findLatticeDir();
     if (!latDir)
         return;
@@ -121,11 +160,52 @@ async function handleStop() {
     catch {
         // If we can't parse stdin, treat as first attempt
     }
-    // Don't block twice — avoids infinite loop
-    if (stopHookActive)
+    // Always run lat check — even on second pass
+    const md = await checkMd(latDir);
+    const code = await checkCodeRefs(latDir);
+    const indexErrors = await checkIndex(latDir);
+    const sectionErrors = await checkSections(latDir);
+    const totalErrors = md.errors.length +
+        code.errors.length +
+        indexErrors.length +
+        sectionErrors.length;
+    const checkFailed = totalErrors > 0;
+    // Second pass — warn the user but don't block again
+    if (stopHookActive) {
+        if (checkFailed) {
+            console.error(`lat check is still failing (${totalErrors} error(s)). Run \`lat check\` to see details.`);
+        }
+        return;
+    }
+    const projectRoot = dirname(latDir);
+    // Analyze git diff — flag when lat.md/ changes are < 5% of code changes
+    const { codeLines, latMdLines } = analyzeDiff(projectRoot);
+    let needsSync = false;
+    if (codeLines >= DIFF_THRESHOLD) {
+        // Round up lat.md lines to 1 if there are more than 5 code lines changed
+        // (a tiny lat.md touch still counts as effort)
+        const effectiveLatMd = latMdLines === 0 ? 0 : Math.max(latMdLines, 1);
+        needsSync = effectiveLatMd < codeLines * LATMD_RATIO;
+    }
+    // Nothing to do — let the agent stop cleanly
+    if (!checkFailed && !needsSync)
         return;
     const parts = [];
-    parts.push('Before finishing, verify:', '- Did you update `lat.md/`? Run `lat search` with a query describing what you changed to find relevant sections that may need updating.', '- Did you run `lat check` and confirm all links and code refs pass?', 'If you made code changes but did not update lat.md/, do that now.');
+    if (checkFailed && needsSync) {
+        parts.push('`lat check` found errors AND the codebase has changes (' +
+            codeLines +
+            ' lines) with no updates to `lat.md/`. Before finishing:', '', '1. Update `lat.md/` to reflect your code changes — run `lat search` to find relevant sections.', '2. Run `lat check` until it passes.');
+    }
+    else if (checkFailed) {
+        parts.push('`lat check` found ' +
+            totalErrors +
+            ' error(s). Run `lat check`, fix the errors, and repeat until it passes.');
+    }
+    else {
+        parts.push('The codebase has changes (' +
+            codeLines +
+            ' lines) but `lat.md/` was not updated. Update `lat.md/` to be in sync with the changes — run `lat search` to find relevant sections. Run `lat check` at the end.');
+    }
     outputStop(parts.join('\n'));
 }
 export async function hookCmd(agent, event) {

package/dist/src/cli/refs.js

@@ -97,7 +97,7 @@ export async function refsCommand(ctx, query, scope) {
         parts.push(formatResultList(ctx, `References to "${target.id}":`, mdRefs));
     }
     if (codeRefs.length > 0) {
-        parts.push(s.bold('Code references:') +
+        parts.push('## Code references:' +
             '\n\n' +
             codeRefs.map((l) => `${s.dim('*')} ${l}`).join('\n'));
     }

package/dist/src/cli/search.js

@@ -3,7 +3,7 @@ import { detectProvider } from '../search/provider.js';
 import { indexSections } from '../search/index.js';
 import { searchSections } from '../search/search.js';
 import { loadAllSections, flattenSections, } from '../lattice.js';
-import { formatResultList } from '../format.js';
+import { formatResultList, formatNavHints } from '../format.js';
 async function withDb(latDir, key, progress, fn) {
     const provider = detectProvider(key);
     const db = openDb(latDir);
@@ -94,14 +94,8 @@ export async function searchCommand(ctx, query, opts, progress) {
     if (result.matches.length === 0) {
         return { output: 'No results found.' };
     }
-    const navHints = ctx.mode === 'cli'
-        ? '- `lat section "section#id"` \u2014 show full content with outgoing/incoming refs\n' +
-            '- `lat search "new query"` \u2014 search for something else'
-        : '- `lat_section` \u2014 show full content with outgoing/incoming refs\n' +
-            '- `lat_search` \u2014 search for something else';
     return {
         output: formatResultList(ctx, `Search results for "${query}":`, result.matches) +
-            '\nTo navigate further:\n' +
-            navHints,
+            formatNavHints(ctx),
     };
 }

package/dist/src/cli/section.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { loadAllSections, findSections, flattenSections, extractRefs, buildFileIndex, resolveRef, listLatticeFiles, } from '../lattice.js';
-import { formatSectionId } from '../format.js';
+import { formatSectionId, formatNavHints } from '../format.js';
 /**
  * Look up a section by id, return its content, outgoing wiki link targets,
  * and incoming references from other sections.
@@ -22,13 +22,12 @@ export async function getSection(ctx, query) {
         return { kind: 'no-match', suggestions: matches };
     }
     const section = top.section;
-    // Read raw content between startLine and endLine
+    // Read raw content between startLine and the end of the last descendant
     const absPath = join(ctx.projectRoot, section.filePath);
     const fileContent = await readFile(absPath, 'utf-8');
     const lines = fileContent.split('\n');
-    const content = lines
-        .slice(section.startLine - 1, section.endLine)
-        .join('\n');
+    const end = fullEndLine(section);
+    const content = lines.slice(section.startLine - 1, end).join('\n');
     // Find outgoing wiki link targets within this section's content
     const flat = flattenSections(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
@@ -73,6 +72,11 @@ export async function getSection(ctx, query) {
     }
     return { kind: 'found', section, content, outgoingRefs, incomingRefs };
 }
+function fullEndLine(section) {
+    if (section.children.length === 0)
+        return section.endLine;
+    return fullEndLine(section.children[section.children.length - 1]);
+}
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max) + '...' : s;
 }
@@ -84,13 +88,17 @@ export function formatSectionOutput(ctx, result) {
     const { section, content, outgoingRefs, incomingRefs } = result;
     const relPath = relative(process.cwd(), join(ctx.projectRoot, section.filePath));
     const loc = `${s.cyan(relPath)}${s.dim(`:${section.startLine}-${section.endLine}`)}`;
+    const quoted = content
+        .split('\n')
+        .map((line) => (line ? `> ${line}` : '>'))
+        .join('\n');
     const parts = [
         `${s.bold('[[' + formatSectionId(section.id, s) + ']]')} (${loc})`,
         '',
-        content,
+        quoted,
     ];
     if (outgoingRefs.length > 0) {
-        parts.push('', s.bold('This section references:'), '');
+        parts.push('', '## This section references:', '');
         for (const ref of outgoingRefs) {
             const body = ref.resolved.firstParagraph
                 ? ` ${s.dim('—')} ${truncate(ref.resolved.firstParagraph, 120)}`
@@ -99,7 +107,7 @@ export function formatSectionOutput(ctx, result) {
         }
     }
     if (incomingRefs.length > 0) {
-        parts.push('', s.bold('Referenced by:'), '');
+        parts.push('', '## Referenced by:', '');
         for (const ref of incomingRefs) {
             const body = ref.section.firstParagraph
                 ? ` ${s.dim('—')} ${truncate(ref.section.firstParagraph, 120)}`
@@ -107,6 +115,7 @@ export function formatSectionOutput(ctx, result) {
             parts.push(`${s.dim('*')} [[${formatSectionId(ref.section.id, s)}]]${body}`);
         }
     }
+    parts.push(formatNavHints(ctx));
     return parts.join('\n');
 }
 export async function sectionCommand(ctx, query) {

package/dist/src/format.d.ts

@@ -5,3 +5,4 @@ export declare function formatSectionPreview(ctx: CmdContext, section: Section,
     reason?: string;
 }): string;
 export declare function formatResultList(ctx: CmdContext, header: string, matches: SectionMatch[]): string;
+export declare function formatNavHints(ctx: CmdContext): string;

package/dist/src/format.js

@@ -21,7 +21,7 @@ export function formatSectionPreview(ctx, section, opts) {
     return lines.join('\n');
 }
 export function formatResultList(ctx, header, matches) {
-    const lines = ['', ctx.styler.bold(header), ''];
+    const lines = ['', `## ${header}`, ''];
     for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
@@ -32,3 +32,12 @@ export function formatResultList(ctx, header, matches) {
     lines.push('');
     return lines.join('\n');
 }
+export function formatNavHints(ctx) {
+    const s = ctx.styler;
+    const hints = ctx.mode === 'cli'
+        ? `${s.dim('*')} \`lat section "section#id"\` \u2014 show full content with outgoing/incoming refs\n` +
+            `${s.dim('*')} \`lat search "new query"\` \u2014 search for something else`
+        : `${s.dim('*')} \`lat_section\` \u2014 show full content with outgoing/incoming refs\n` +
+            `${s.dim('*')} \`lat_search\` \u2014 search for something else`;
+    return `\n## To navigate further:\n\n${hints}`;
+}

package/dist/src/lattice.d.ts

@@ -19,7 +19,6 @@ export type LatFrontmatter = {
     requireCodeMention?: boolean;
 };
 export declare function parseFrontmatter(content: string): LatFrontmatter;
-export declare function stripFrontmatter(content: string): string;
 export declare function findLatticeDir(from?: string): string | null;
 export declare function findProjectRoot(from?: string): string | null;
 export declare function listLatticeFiles(latticeDir: string): Promise<string[]>;

package/dist/src/lattice.js

@@ -15,9 +15,6 @@ export function parseFrontmatter(content) {
     }
     return result;
 }
-export function stripFrontmatter(content) {
-    return content.replace(/^---\n[\s\S]*?\n---\n*/, '');
-}
 export function findLatticeDir(from) {
     let dir = resolve(from ?? process.cwd());
     while (true) {
@@ -69,7 +66,7 @@ function lastLine(content) {
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
 export function parseSections(filePath, content, projectRoot) {
-    const tree = parse(stripFrontmatter(content));
+    const tree = parse(content);
     const file = projectRoot
         ? relative(projectRoot, filePath).replace(/\.md$/, '')
         : basename(filePath, '.md');
@@ -522,7 +519,7 @@ export function findSections(sections, query) {
     ];
 }
 export function extractRefs(filePath, content, projectRoot) {
-    const tree = parse(stripFrontmatter(content));
+    const tree = parse(content);
     const file = projectRoot
         ? relative(projectRoot, filePath).replace(/\.md$/, '')
         : basename(filePath, '.md');

package/dist/src/parser.js

@@ -1,9 +1,11 @@
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
+import remarkFrontmatter from 'remark-frontmatter';
 import { wikiLinkSyntax, wikiLinkFromMarkdown, wikiLinkToMarkdown, } from './extensions/wiki-link/index.js';
 const processor = unified()
     .use(remarkParse)
+    .use(remarkFrontmatter)
     .use(remarkStringify)
     .data('micromarkExtensions', [wikiLinkSyntax()])
     .data('fromMarkdownExtensions', [wikiLinkFromMarkdown()])

package/dist/src/source-parser.d.ts

@@ -7,6 +7,8 @@ export type SourceSymbol = {
     endLine: number;
     signature: string;
 };
+/** All source file extensions that lat can parse (derived from grammarMap). */
+export declare const SOURCE_EXTENSIONS: ReadonlySet<string>;
 export declare function parseSourceSymbols(filePath: string, content: string): Promise<SourceSymbol[]>;
 /**
  * Check whether a source file path (relative to projectRoot) has a given symbol.

package/dist/src/source-parser.js

@@ -21,18 +21,22 @@ async function ensureParser() {
     }
     return parserInstance;
 }
+/** Extension → tree-sitter WASM grammar mapping. This is the single source of
+ *  truth for which source file extensions lat supports. */
+const grammarMap = {
+    '.ts': 'tree-sitter-typescript.wasm',
+    '.tsx': 'tree-sitter-tsx.wasm',
+    '.js': 'tree-sitter-javascript.wasm',
+    '.jsx': 'tree-sitter-javascript.wasm',
+    '.py': 'tree-sitter-python.wasm',
+    '.rs': 'tree-sitter-rust.wasm',
+    '.go': 'tree-sitter-go.wasm',
+    '.c': 'tree-sitter-c.wasm',
+    '.h': 'tree-sitter-c.wasm',
+};
+/** All source file extensions that lat can parse (derived from grammarMap). */
+export const SOURCE_EXTENSIONS = new Set(Object.keys(grammarMap));
 async function getLanguage(ext) {
-    const grammarMap = {
-        '.ts': 'tree-sitter-typescript.wasm',
-        '.tsx': 'tree-sitter-tsx.wasm',
-        '.js': 'tree-sitter-javascript.wasm',
-        '.jsx': 'tree-sitter-javascript.wasm',
-        '.py': 'tree-sitter-python.wasm',
-        '.rs': 'tree-sitter-rust.wasm',
-        '.go': 'tree-sitter-go.wasm',
-        '.c': 'tree-sitter-c.wasm',
-        '.h': 'tree-sitter-c.wasm',
-    };
     const wasmFile = grammarMap[ext];
     if (!wasmFile)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",
@@ -55,6 +55,7 @@
     "commander": "^14.0.3",
     "ignore-walk": "^8.0.0",
     "mdast-util-to-markdown": "^2.1.0",
+    "remark-frontmatter": "^5.0.0",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.0",