lat.md 0.2.3 → 0.3.0

package/dist/src/cli/init.js

@@ -1,4 +1,4 @@
-import { existsSync, cpSync, mkdirSync, writeFileSync, symlinkSync, } from 'node:fs';
+import { existsSync, cpSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, chmodSync, symlinkSync, } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
@@ -13,6 +13,49 @@ async function confirm(rl, message) {
         return true;
     }
 }
+const HOOK_COMMAND = '.claude/hooks/lat-prompt-hook.sh';
+/**
+ * Check if .claude/settings.json already has the lat-prompt hook configured.
+ */
+function hasLatHook(settingsPath) {
+    if (!existsSync(settingsPath))
+        return false;
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        const entries = settings?.hooks?.UserPromptSubmit;
+        if (!Array.isArray(entries))
+            return false;
+        return entries.some((entry) => entry.hooks?.some((h) => h.command === HOOK_COMMAND));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Add the lat-prompt hook to .claude/settings.json, preserving existing config.
+ */
+function addLatHook(settingsPath) {
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Corrupted file — start fresh
+        }
+    }
+    if (!settings.hooks || typeof settings.hooks !== 'object') {
+        settings.hooks = {};
+    }
+    const hooks = settings.hooks;
+    if (!Array.isArray(hooks.UserPromptSubmit)) {
+        hooks.UserPromptSubmit = [];
+    }
+    hooks.UserPromptSubmit.push({
+        hooks: [{ type: 'command', command: HOOK_COMMAND }],
+    });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
 export async function initCmd(targetDir) {
     const root = resolve(targetDir ?? process.cwd());
     const latDir = join(root, 'lat.md');
@@ -60,6 +103,31 @@ export async function initCmd(targetDir) {
             console.log(`\n${existing} already exists. Run ${chalk.cyan('lat gen agents.md')} to preview the template,` +
                 ` then incorporate its content or overwrite as needed.`);
         }
+        // Step 3: Claude Code prompt hook
+        const claudeDir = join(root, '.claude');
+        const hooksDir = join(claudeDir, 'hooks');
+        const hookPath = join(hooksDir, 'lat-prompt-hook.sh');
+        const settingsPath = join(claudeDir, 'settings.json');
+        if (hasLatHook(settingsPath)) {
+            console.log(chalk.green('Claude Code hook') + ' already configured');
+        }
+        else {
+            console.log('');
+            console.log(chalk.bold('Claude Code hook') +
+                ' — adds a per-prompt reminder for the agent to consult lat.md');
+            console.log(chalk.dim('  Creates .claude/hooks/lat-prompt-hook.sh and registers it in .claude/settings.json'));
+            console.log(chalk.dim('  On every prompt, the agent is instructed to run `lat search` and `lat prompt` before working.'));
+            if (await ask('Set up Claude Code prompt hook?')) {
+                mkdirSync(hooksDir, { recursive: true });
+                const templateHook = join(findTemplatesDir(), 'lat-prompt-hook.sh');
+                copyFileSync(templateHook, hookPath);
+                chmodSync(hookPath, 0o755);
+                addLatHook(settingsPath);
+                console.log(chalk.green('Created .claude/hooks/lat-prompt-hook.sh'));
+                console.log(chalk.green('Updated .claude/settings.json') +
+                    ' with UserPromptSubmit hook');
+            }
+        }
     }
     finally {
         rl?.close();

package/dist/src/cli/locate.js

@@ -1,13 +1,12 @@
 import { loadAllSections, findSections } from '../lattice.js';
 import { formatResultList } from '../format.js';
 export async function locateCmd(ctx, query) {
+    const stripped = query.replace(/^\[\[|\]\]$/g, '');
     const sections = await loadAllSections(ctx.latDir);
-    const matches = findSections(sections, query);
+    const matches = findSections(sections, stripped);
     if (matches.length === 0) {
-        console.error(ctx.chalk.red(`No sections matching "${query}" (no exact, substring, or fuzzy matches)`));
+        console.error(ctx.chalk.red(`No sections matching "${stripped}" (no exact, substring, or fuzzy matches)`));
         process.exit(1);
     }
-    console.log(formatResultList(`Sections matching "${query}":`, matches, ctx.latDir, {
-        numbered: true,
-    }));
+    console.log(formatResultList(`Sections matching "${stripped}":`, matches, ctx.latDir));
 }

package/dist/src/cli/prompt.js

@@ -1,20 +1,12 @@
 import { relative } from 'node:path';
-import { loadAllSections, findSections, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
+import { loadAllSections, findSections, } from '../lattice.js';
 const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
-function formatContext(section, latDir) {
+function formatLocation(section, latDir) {
     const relPath = relative(process.cwd(), latDir + '/' + section.file + '.md');
-    const loc = `${relPath}:${section.startLine}-${section.endLine}`;
-    let text = `[${section.id}](${loc})`;
-    if (section.body) {
-        text += `: ${section.body}`;
-    }
-    return text;
+    return `${relPath}:${section.startLine}-${section.endLine}`;
 }
 export async function promptCmd(ctx, text) {
     const allSections = await loadAllSections(ctx.latDir);
-    const flat = flattenSections(allSections);
-    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-    const fileIndex = buildFileIndex(allSections);
     const refs = [...text.matchAll(WIKI_LINK_RE)];
     if (refs.length === 0) {
         process.stdout.write(text);
@@ -25,41 +17,43 @@ export async function promptCmd(ctx, text) {
         const target = match[1];
         if (resolved.has(target))
             continue;
-        // Resolve short refs (e.g. search#X → tests/search#X)
-        const { resolved: resolvedTarget } = resolveRef(target, sectionIds, fileIndex);
-        const q = resolvedTarget.toLowerCase();
-        const exact = flat.find((s) => s.id.toLowerCase() === q);
-        if (exact) {
-            resolved.set(target, exact);
-            continue;
-        }
-        const fuzzy = findSections(allSections, target);
-        if (fuzzy.length === 1) {
-            resolved.set(target, fuzzy[0]);
+        const matches = findSections(allSections, target);
+        if (matches.length >= 1) {
+            resolved.set(target, {
+                target,
+                best: matches[0],
+                alternatives: matches.slice(1),
+            });
             continue;
         }
-        if (fuzzy.length > 1) {
-            console.error(ctx.chalk.red(`Ambiguous reference [[${target}]].`));
-            console.error(ctx.chalk.dim('\nCould match:\n'));
-            for (const m of fuzzy) {
-                console.error('  ' + m.id);
-            }
-            console.error(ctx.chalk.dim('\nAsk the user which section they meant.'));
-            process.exit(1);
-        }
         console.error(ctx.chalk.red(`No section found for [[${target}]] (no exact, substring, or fuzzy matches).`));
         console.error(ctx.chalk.dim('Ask the user to correct the reference.'));
         process.exit(1);
     }
     // Replace [[refs]] inline
     let output = text.replace(WIKI_LINK_RE, (_match, target) => {
-        const section = resolved.get(target);
-        return `[[${section.id}]]`;
+        const ref = resolved.get(target);
+        return `[[${ref.best.section.id}]]`;
     });
-    // Append context block
+    // Append context block as nested outliner
     output += '\n\n<lat-context>\n';
-    for (const section of resolved.values()) {
-        output += formatContext(section, ctx.latDir) + '\n';
+    for (const ref of resolved.values()) {
+        const isExact = ref.best.reason === 'exact match';
+        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.latDir)}\n`;
+            if (m.section.body) {
+                output += `    * ${m.section.body}\n`;
+            }
+        }
     }
     output += '</lat-context>\n';
     process.stdout.write(output);

package/dist/src/cli/refs.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
-import { formatSectionPreview } from '../format.js';
+import { formatResultList } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
 export async function refsCmd(ctx, query, scope) {
     const allSections = await loadAllSections(ctx.latDir);
@@ -22,13 +22,18 @@ export async function refsCmd(ctx, query, scope) {
         if (matches.length > 0) {
             console.error(ctx.chalk.dim('\nDid you mean:\n'));
             for (const m of matches) {
-                console.error('  ' + ctx.chalk.white(m.id));
+                console.error(ctx.chalk.dim('*') +
+                    ' ' +
+                    ctx.chalk.white(m.section.id) +
+                    ' ' +
+                    ctx.chalk.dim(`(${m.reason})`));
             }
         }
         process.exit(1);
     }
     const targetId = exactMatch.id.toLowerCase();
-    let hasOutput = false;
+    const mdMatches = [];
+    const codeLines = [];
     if (scope === 'md' || scope === 'md+code') {
         const files = await listLatticeFiles(ctx.latDir);
         const matchingFromSections = new Set();
@@ -44,11 +49,8 @@ export async function refsCmd(ctx, query, scope) {
         }
         if (matchingFromSections.size > 0) {
             const referrers = flat.filter((s) => matchingFromSections.has(s.id.toLowerCase()));
-            for (let i = 0; i < referrers.length; i++) {
-                if (hasOutput)
-                    console.log('');
-                console.log(formatSectionPreview(referrers[i], ctx.latDir));
-                hasOutput = true;
+            for (const s of referrers) {
+                mdMatches.push({ section: s, reason: 'wiki link' });
             }
         }
     }
@@ -58,15 +60,24 @@ export async function refsCmd(ctx, query, scope) {
         for (const ref of codeRefs) {
             const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
             if (codeResolved.toLowerCase() === targetId) {
-                if (hasOutput)
-                    console.log('');
-                console.log(`  ${ref.file}:${ref.line}`);
-                hasOutput = true;
+                codeLines.push(`${ref.file}:${ref.line}`);
             }
         }
     }
-    if (!hasOutput) {
+    if (mdMatches.length === 0 && codeLines.length === 0) {
         console.error(ctx.chalk.red(`No references to "${exactMatch.id}" found`));
         process.exit(1);
     }
+    if (mdMatches.length > 0) {
+        console.log(formatResultList(`References to "${exactMatch.id}":`, mdMatches, ctx.latDir));
+    }
+    if (codeLines.length > 0) {
+        if (mdMatches.length > 0)
+            console.log('');
+        console.log(ctx.chalk.bold('Code references:'));
+        console.log('');
+        for (const line of codeLines) {
+            console.log(`${ctx.chalk.dim('*')} ${line}`);
+        }
+    }
 }

package/dist/src/cli/search.js

@@ -44,10 +44,9 @@ export async function searchCmd(ctx, query, opts) {
         const byId = new Map(flat.map((s) => [s.id, s]));
         const matched = results
             .map((r) => byId.get(r.id))
-            .filter((s) => !!s);
-        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.latDir, {
-            numbered: true,
-        }));
+            .filter((s) => !!s)
+            .map((s) => ({ section: s, reason: 'semantic match' }));
+        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.latDir));
     }
     finally {
         await closeDb(db);

package/dist/src/format.d.ts

@@ -1,8 +1,6 @@
-import type { Section } from './lattice.js';
+import type { Section, SectionMatch } from './lattice.js';
 export declare function formatSectionId(id: string): string;
 export declare function formatSectionPreview(section: Section, latticeDir: string, opts?: {
-    index?: number;
-}): string;
-export declare function formatResultList(header: string, sections: Section[], latticeDir: string, opts?: {
-    numbered?: boolean;
+    reason?: string;
 }): string;
+export declare function formatResultList(header: string, matches: SectionMatch[], latticeDir: string): string;

package/dist/src/format.js

@@ -9,28 +9,28 @@ export function formatSectionId(id) {
 }
 export function formatSectionPreview(section, latticeDir, opts) {
     const relPath = relative(process.cwd(), latticeDir + '/' + section.file + '.md');
-    const prefix = opts?.index != null ? `${chalk.dim(`${opts.index}.`)} ` : '  ';
-    const indent = opts?.index != null ? '   ' : '  ';
+    const kind = section.id.includes('#') ? 'Section' : 'File';
+    const reasonSuffix = opts?.reason ? ' ' + chalk.dim(`(${opts.reason})`) : '';
     const lines = [
-        `${prefix}${formatSectionId(section.id)}`,
-        `${indent}${chalk.dim('Defined in')} ${chalk.cyan(relPath)}${chalk.dim(`:${section.startLine}-${section.endLine}`)}`,
+        `${chalk.dim('*')} ${chalk.dim(kind + ':')} [[${formatSectionId(section.id)}]]${reasonSuffix}`,
+        `  ${chalk.dim('Defined in')} ${chalk.cyan(relPath)}${chalk.dim(`:${section.startLine}-${section.endLine}`)}`,
     ];
     if (section.body) {
         const truncated = section.body.length > 200
             ? section.body.slice(0, 200) + '...'
             : section.body;
         lines.push('');
-        lines.push(`${indent}${chalk.dim('>')} ${truncated}`);
+        lines.push(`  ${chalk.dim('>')} ${truncated}`);
     }
     return lines.join('\n');
 }
-export function formatResultList(header, sections, latticeDir, opts) {
+export function formatResultList(header, matches, latticeDir) {
     const lines = ['', chalk.bold(header), ''];
-    for (let i = 0; i < sections.length; i++) {
+    for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
-        lines.push(formatSectionPreview(sections[i], latticeDir, {
-            index: opts?.numbered ? i + 1 : undefined,
+        lines.push(formatSectionPreview(matches[i].section, latticeDir, {
+            reason: matches[i].reason,
         }));
     }
     lines.push('');

package/dist/src/lattice.d.ts

@@ -45,5 +45,9 @@ export type ResolveResult = {
  * `suggested` is set to that candidate so the caller can propose a fix.
  */
 export declare function resolveRef(target: string, sectionIds: Set<string>, fileIndex: Map<string, string[]>): ResolveResult;
-export declare function findSections(sections: Section[], query: string): Section[];
+export type SectionMatch = {
+    section: Section;
+    reason: string;
+};
+export declare function findSections(sections: Section[], query: string): SectionMatch[];
 export declare function extractRefs(filePath: string, content: string, latticeDir?: string): Ref[];

package/dist/src/lattice.js

@@ -254,44 +254,164 @@ export function resolveRef(target, sectionIds, fileIndex) {
 const MAX_DISTANCE_RATIO = 0.4;
 export function findSections(sections, query) {
     const flat = flattenSections(sections);
-    const isFullPath = query.includes('#');
-    // Tier 0: resolve short refs (e.g. search#X → tests/search#X)
-    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
-    const fileIndex = buildFileIndex(sections);
-    const { resolved } = resolveRef(query, sectionIds, fileIndex);
-    const q = resolved.toLowerCase();
+    // Leading # means "search for a heading", strip it
+    const normalized = query.startsWith('#') ? query.slice(1) : query;
+    const q = normalized.toLowerCase();
+    const isFullPath = normalized.includes('#');
     // Tier 1: exact full-id match
     const exact = flat.filter((s) => s.id.toLowerCase() === q);
-    if (exact.length > 0 && isFullPath)
-        return exact;
+    const exactMatches = exact.map((s) => ({
+        section: s,
+        reason: 'exact match',
+    }));
+    if (exactMatches.length > 0 && isFullPath)
+        return exactMatches;
+    // Tier 1b: file stem expansion
+    // For bare names: "locate" → matches root section of "tests/locate.md"
+    // For paths with #: "setup#Install" → expands to "guides/setup#Install"
+    const fileIndex = buildFileIndex(sections);
+    const stemMatches = [];
+    if (isFullPath) {
+        // Expand file stem in the file part of the query
+        const hashIdx = normalized.indexOf('#');
+        const filePart = normalized.slice(0, hashIdx);
+        const rest = normalized.slice(hashIdx);
+        const paths = fileIndex.get(filePart) ?? [];
+        for (const p of paths) {
+            const expanded = (p + rest).toLowerCase();
+            const s = flat.find((s) => s.id.toLowerCase() === expanded && !exact.includes(s));
+            if (s)
+                stemMatches.push({
+                    section: s,
+                    reason: `file stem expanded: ${filePart} → ${p}`,
+                });
+        }
+        if (stemMatches.length > 0)
+            return [...exactMatches, ...stemMatches];
+    }
+    else {
+        // Bare name: match file root sections via stem index
+        const paths = fileIndex.get(normalized) ?? [];
+        for (const p of paths) {
+            const s = flat.find((s) => s.id.toLowerCase() === p.toLowerCase() && !exact.includes(s));
+            if (s)
+                stemMatches.push({ section: s, reason: 'file stem match' });
+        }
+    }
     // Tier 2: exact match on trailing segments (subsection name match)
+    const seen = new Set([
+        ...exact.map((s) => s.id),
+        ...stemMatches.map((m) => m.section.id),
+    ]);
     const subsection = isFullPath
         ? []
-        : flat.filter((s) => tailSegments(s.id).some((tail) => tail.toLowerCase() === q));
+        : flat
+            .filter((s) => {
+            if (seen.has(s.id))
+                return false;
+            return tailSegments(s.id).some((tail) => tail.toLowerCase() === q);
+        })
+            .map((s) => ({ section: s, reason: 'section name match' }));
+    // Tier 2b: subsequence match — query segments are a subsequence of section id segments
+    // e.g. "Markdown#Resolution Rules" matches "markdown#Wiki Links#Resolution Rules"
+    const seenSub = new Set([...seen, ...subsection.map((m) => m.section.id)]);
+    const qParts = q.split('#');
+    const subsequence = qParts.length >= 2
+        ? flat
+            .filter((s) => {
+            if (seenSub.has(s.id))
+                return false;
+            const sParts = s.id.toLowerCase().split('#');
+            if (sParts.length <= qParts.length)
+                return false;
+            let qi = 0;
+            for (const sp of sParts) {
+                if (sp === qParts[qi])
+                    qi++;
+                if (qi === qParts.length)
+                    return true;
+            }
+            return false;
+        })
+            .map((s) => {
+            const skipped = s.id.split('#').length - qParts.length;
+            return {
+                section: s,
+                reason: `path match, ${skipped} intermediate ${skipped === 1 ? 'section' : 'sections'} skipped`,
+            };
+        })
+        : [];
     // Tier 3: fuzzy match by edit distance on each segment tail and full id
-    const seen = new Set([
-        ...exact.map((s) => s.id),
-        ...subsection.map((s) => s.id),
+    const seenAll = new Set([
+        ...seenSub,
+        ...subsequence.map((m) => m.section.id),
     ]);
     const fuzzy = [];
+    // For full-path queries, extract the file and heading parts so we can
+    // fuzzy-match only the heading portion when the file part matches exactly.
+    // This prevents the shared file prefix from inflating similarity scores
+    // (e.g. "cli#locat" would otherwise fuzzy-match "cli#prompt").
+    const qHashIdx = normalized.indexOf('#');
+    const qFile = qHashIdx === -1 ? null : normalized.slice(0, qHashIdx).toLowerCase();
+    const qHeading = qHashIdx === -1 ? null : normalized.slice(qHashIdx + 1).toLowerCase();
     for (const s of flat) {
-        if (seen.has(s.id))
+        if (seenAll.has(s.id))
             continue;
         const candidates = [s.id, ...tailSegments(s.id)];
         let best = Infinity;
+        let bestCandidate = '';
         for (const c of candidates) {
-            const d = levenshtein(c.toLowerCase(), q);
-            const maxLen = Math.max(c.length, q.length);
-            if (d / maxLen <= MAX_DISTANCE_RATIO && d < best) {
+            let d;
+            let maxLen;
+            const cl = c.toLowerCase();
+            const cHashIdx = cl.indexOf('#');
+            // When both query and candidate have # and their file parts match,
+            // compare only the heading portions to avoid file-prefix inflation
+            if (qFile && qHeading && cHashIdx !== -1) {
+                const cFile = cl.slice(0, cHashIdx);
+                const cHeading = cl.slice(cHashIdx + 1);
+                if (cFile === qFile) {
+                    d = levenshtein(cHeading, qHeading);
+                    maxLen = Math.max(cHeading.length, qHeading.length);
+                }
+                else {
+                    d = levenshtein(cl, q);
+                    maxLen = Math.max(c.length, q.length);
+                }
+            }
+            else {
+                d = levenshtein(cl, q);
+                maxLen = Math.max(c.length, q.length);
+            }
+            if (maxLen > 0 && d / maxLen <= MAX_DISTANCE_RATIO && d < best) {
                 best = d;
+                bestCandidate = c;
             }
         }
         if (best < Infinity) {
-            fuzzy.push({ section: s, distance: best });
+            fuzzy.push({ section: s, distance: best, matched: bestCandidate });
         }
     }
     fuzzy.sort((a, b) => a.distance - b.distance);
-    return [...exact, ...subsection, ...fuzzy.map((f) => f.section)];
+    const fuzzyMatches = fuzzy.map((f) => ({
+        section: f.section,
+        reason: f.matched.toLowerCase() === f.section.id.toLowerCase()
+            ? `fuzzy match, distance ${f.distance}`
+            : `fuzzy match on "${f.matched}", distance ${f.distance}`,
+    }));
+    // Sort results: shallower depth first, then fewer path segments
+    const sortKey = (s) => {
+        const pathDepth = (s.file.match(/\//g) || []).length;
+        return s.depth * 100 + pathDepth;
+    };
+    const sortedStems = [...stemMatches].sort((a, b) => sortKey(a.section) - sortKey(b.section));
+    return [
+        ...exactMatches,
+        ...sortedStems,
+        ...subsection,
+        ...subsequence,
+        ...fuzzyMatches,
+    ];
 }
 export function extractRefs(filePath, content, latticeDir) {
     const tree = parse(stripFrontmatter(content));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",

package/templates/lat-prompt-hook.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# lat.md prompt hook for Claude Code
+# Injected by `lat init` — reminds the agent to consult lat.md before working.
+#
+# This hook fires on every user prompt submission. It adds a short instruction
+# telling the agent to run `lat search` and `lat prompt` so that lat.md context
+# is consulted before any code changes.
+
+cat <<'HOOK_JSON'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Before starting work on this task:\n1. Run `lat search` with a query relevant to the task and read the results to understand the design intent.\n2. If the prompt contains [[refs]], run `lat prompt` on the full prompt text to resolve them.\n3. After completing work, run `lat check` to validate all links and code refs.\nDo not skip these steps."
+  }
+}
+HOOK_JSON