lat.md 0.5.0 → 0.6.0

package/dist/src/cli/check.js

@@ -1,5 +1,6 @@
 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';
@@ -30,7 +31,50 @@ function countByExt(paths) {
     }
     return stats;
 }
+/** Source file extensions recognized for code wiki links. */
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py']);
+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)) {
+        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 +83,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 +96,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 +146,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);

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

@@ -1,6 +1,7 @@
 import { type ChalkInstance } from 'chalk';
 export type CliContext = {
     latDir: string;
+    projectRoot: string;
     color: boolean;
     chalk: ChalkInstance;
 };

package/dist/src/cli/context.js

@@ -1,3 +1,4 @@
+import { dirname } from 'node:path';
 import chalk from 'chalk';
 import { findLatticeDir } from '../lattice.js';
 export function resolveContext(opts) {
@@ -11,5 +12,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, color, chalk };
 }

package/dist/src/cli/locate.js

@@ -8,5 +8,5 @@ export async function locateCmd(ctx, query) {
         console.error(ctx.chalk.red(`No sections matching "${stripped}" (no exact, substring, or fuzzy matches)`));
         process.exit(1);
     }
-    console.log(formatResultList(`Sections matching "${stripped}":`, matches, ctx.latDir));
+    console.log(formatResultList(`Sections matching "${stripped}":`, matches, ctx.projectRoot));
 }

package/dist/src/cli/prompt.js

@@ -1,8 +1,8 @@
-import { relative } from 'node:path';
+import { join, relative } from 'node:path';
 import { loadAllSections, findSections, } from '../lattice.js';
 const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
-function formatLocation(section, latDir) {
-    const relPath = relative(process.cwd(), latDir + '/' + section.file + '.md');
+function formatLocation(section, projectRoot) {
+    const relPath = relative(process.cwd(), join(projectRoot, section.filePath));
     return `${relPath}:${section.startLine}-${section.endLine}`;
 }
 export async function promptCmd(ctx, text) {
@@ -38,7 +38,8 @@ export async function promptCmd(ctx, text) {
     // 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';
+        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`;
@@ -49,7 +50,7 @@ export async function promptCmd(ctx, text) {
         for (const m of all) {
             const reason = isExact ? '' : ` (${m.reason})`;
             output += `  * [[${m.section.id}]]${reason}\n`;
-            output += `    * ${formatLocation(m.section, ctx.latDir)}\n`;
+            output += `    * ${formatLocation(m.section, ctx.projectRoot)}\n`;
             if (m.section.body) {
                 output += `    * ${m.section.body}\n`;
             }

package/dist/src/cli/refs.js

@@ -1,5 +1,4 @@
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { listLatticeFiles, loadAllSections, findSections, extractRefs, flattenSections, buildFileIndex, resolveRef, } from '../lattice.js';
 import { formatResultList } from '../format.js';
 import { scanCodeRefs } from '../code-refs.js';
@@ -39,7 +38,7 @@ export async function refsCmd(ctx, query, scope) {
         const matchingFromSections = new Set();
         for (const file of files) {
             const content = await readFile(file, 'utf-8');
-            const fileRefs = extractRefs(file, content, ctx.latDir);
+            const fileRefs = extractRefs(file, content, ctx.projectRoot);
             for (const ref of fileRefs) {
                 const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
                 if (refResolved.toLowerCase() === targetId) {
@@ -55,8 +54,7 @@ export async function refsCmd(ctx, query, scope) {
         }
     }
     if (scope === 'code' || scope === 'md+code') {
-        const projectRoot = join(ctx.latDir, '..');
-        const { refs: codeRefs } = await scanCodeRefs(projectRoot);
+        const { refs: codeRefs } = await scanCodeRefs(ctx.projectRoot);
         for (const ref of codeRefs) {
             const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
             if (codeResolved.toLowerCase() === targetId) {
@@ -69,7 +67,7 @@ export async function refsCmd(ctx, query, scope) {
         process.exit(1);
     }
     if (mdMatches.length > 0) {
-        console.log(formatResultList(`References to "${exactMatch.id}":`, mdMatches, ctx.latDir));
+        console.log(formatResultList(`References to "${exactMatch.id}":`, mdMatches, ctx.projectRoot));
     }
     if (codeLines.length > 0) {
         if (mdMatches.length > 0)

package/dist/src/cli/search.js

@@ -59,7 +59,7 @@ export async function searchCmd(ctx, query, opts) {
             .map((r) => byId.get(r.id))
             .filter((s) => !!s)
             .map((s) => ({ section: s, reason: 'semantic match' }));
-        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.latDir));
+        console.log(formatResultList(`Search results for "${query}":`, matched, ctx.projectRoot));
     }
     finally {
         await closeDb(db);

package/dist/src/format.d.ts

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

package/dist/src/format.js

@@ -1,4 +1,4 @@
-import { relative } from 'node:path';
+import { join, relative } from 'node:path';
 import chalk from 'chalk';
 export function formatSectionId(id) {
     const parts = id.split('#');
@@ -7,8 +7,8 @@ export function formatSectionId(id) {
         : chalk.dim(parts.slice(0, -1).join('#') + '#') +
             chalk.bold.white(parts[parts.length - 1]);
 }
-export function formatSectionPreview(section, latticeDir, opts) {
-    const relPath = relative(process.cwd(), latticeDir + '/' + section.file + '.md');
+export function formatSectionPreview(section, projectRoot, opts) {
+    const relPath = relative(process.cwd(), join(projectRoot, section.filePath));
     const kind = section.id.includes('#') ? 'Section' : 'File';
     const reasonSuffix = opts?.reason ? ' ' + chalk.dim(`(${opts.reason})`) : '';
     const lines = [
@@ -24,12 +24,12 @@ export function formatSectionPreview(section, latticeDir, opts) {
     }
     return lines.join('\n');
 }
-export function formatResultList(header, matches, latticeDir) {
+export function formatResultList(header, matches, projectRoot) {
     const lines = ['', chalk.bold(header), ''];
     for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
-        lines.push(formatSectionPreview(matches[i].section, latticeDir, {
+        lines.push(formatSectionPreview(matches[i].section, projectRoot, {
             reason: matches[i].reason,
         }));
     }

package/dist/src/lattice.d.ts

@@ -3,6 +3,7 @@ export type Section = {
     heading: string;
     depth: number;
     file: string;
+    filePath: string;
     children: Section[];
     startLine: number;
     endLine: number;
@@ -20,13 +21,18 @@ export type LatFrontmatter = {
 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[]>;
-export declare function parseSections(filePath: string, content: string, latticeDir?: string): Section[];
+export declare function parseSections(filePath: string, content: string, projectRoot?: string): Section[];
 export declare function loadAllSections(latticeDir: string): Promise<Section[]>;
 export declare function flattenSections(sections: Section[]): Section[];
 /**
- * Build an index mapping bare file stems to their full vault-relative paths.
- * Used by resolveRef to allow short references when a stem is unambiguous.
+ * Build an index mapping path suffixes to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a suffix is unambiguous.
+ *
+ * For a file like `lat.md/guides/setup`, indexes both `guides/setup` and `setup`.
+ * This ensures backward-compatible short refs after the vault root moved to the
+ * project root (so section IDs now include the `lat.md/` prefix).
  */
 export declare function buildFileIndex(sections: Section[]): Map<string, string[]>;
 export type ResolveResult = {
@@ -50,4 +56,4 @@ export type SectionMatch = {
     reason: string;
 };
 export declare function findSections(sections: Section[], query: string): SectionMatch[];
-export declare function extractRefs(filePath: string, content: string, latticeDir?: string): Ref[];
+export declare function extractRefs(filePath: string, content: string, projectRoot?: string): Ref[];

package/dist/src/lattice.js

@@ -31,6 +31,10 @@ export function findLatticeDir(from) {
         dir = parent;
     }
 }
+export function findProjectRoot(from) {
+    const latDir = findLatticeDir(from);
+    return latDir ? dirname(latDir) : null;
+}
 export async function listLatticeFiles(latticeDir) {
     const entries = await walkEntries(latticeDir);
     return entries
@@ -64,11 +68,14 @@ function lastLine(content) {
     // If trailing newline, count doesn't include empty last line
     return lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
 }
-export function parseSections(filePath, content, latticeDir) {
+export function parseSections(filePath, content, projectRoot) {
     const tree = parse(stripFrontmatter(content));
-    const file = latticeDir
-        ? relative(latticeDir, filePath).replace(/\.md$/, '')
+    const file = projectRoot
+        ? relative(projectRoot, filePath).replace(/\.md$/, '')
         : basename(filePath, '.md');
+    const sectionFilePath = projectRoot
+        ? relative(projectRoot, filePath)
+        : basename(filePath);
     const roots = [];
     const stack = [];
     const flat = [];
@@ -87,6 +94,7 @@ export function parseSections(filePath, content, latticeDir) {
             heading,
             depth,
             file,
+            filePath: sectionFilePath,
             children: [],
             startLine,
             endLine: 0,
@@ -132,11 +140,12 @@ export function parseSections(filePath, content, latticeDir) {
     return roots;
 }
 export async function loadAllSections(latticeDir) {
+    const projectRoot = dirname(latticeDir);
     const files = await listLatticeFiles(latticeDir);
     const all = [];
     for (const file of files) {
         const content = await readFile(file, 'utf-8');
-        all.push(...parseSections(file, content, latticeDir));
+        all.push(...parseSections(file, content, projectRoot));
     }
     return all;
 }
@@ -180,18 +189,26 @@ function tailSegments(id) {
     return tails;
 }
 /**
- * Build an index mapping bare file stems to their full vault-relative paths.
- * Used by resolveRef to allow short references when a stem is unambiguous.
+ * Build an index mapping path suffixes to their full vault-relative paths.
+ * Used by resolveRef to allow short references when a suffix is unambiguous.
+ *
+ * For a file like `lat.md/guides/setup`, indexes both `guides/setup` and `setup`.
+ * This ensures backward-compatible short refs after the vault root moved to the
+ * project root (so section IDs now include the `lat.md/` prefix).
  */
 export function buildFileIndex(sections) {
     const flat = flattenSections(sections);
     const index = new Map();
     for (const s of flat) {
-        const stem = s.file.includes('/') ? s.file.split('/').pop() : null;
-        if (stem) {
-            if (!index.has(stem))
-                index.set(stem, new Set());
-            index.get(stem).add(s.file);
+        const parts = s.file.split('/');
+        // Index all trailing path suffixes (excluding the full path itself,
+        // which is handled by exact match). Keys are lowercase for
+        // case-insensitive lookup.
+        for (let i = 1; i < parts.length; i++) {
+            const suffix = parts.slice(i).join('/').toLowerCase();
+            if (!index.has(suffix))
+                index.set(suffix, new Set());
+            index.get(suffix).add(s.file);
         }
     }
     const result = new Map();
@@ -219,8 +236,10 @@ export function resolveRef(target, sectionIds, fileIndex) {
     const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
     const rest = hashIdx === -1 ? '' : target.slice(hashIdx);
     // Try resolving the file part: either it's a full path or a bare stem
-    const filePaths = fileIndex.has(filePart)
-        ? fileIndex.get(filePart)
+    // File index keys are lowercase for case-insensitive lookup.
+    const lcFilePart = filePart.toLowerCase();
+    const filePaths = fileIndex.has(lcFilePart)
+        ? fileIndex.get(lcFilePart)
         : [filePart];
     if (filePaths.length === 1) {
         const fp = filePaths[0];
@@ -288,27 +307,44 @@ export function findSections(sections, query) {
     }));
     if (exactMatches.length > 0 && isFullPath)
         return exactMatches;
+    // Build file index early — used by both tier 1a and 1b
+    const fileIndex = buildFileIndex(sections);
     // Tier 1a: bare name matches file — return root sections of that file
+    // Also checks via file index (e.g. "dev-process" → "lat.md/dev-process")
     if (!isFullPath && exactMatches.length === 0) {
-        const fileRoots = flat.filter((s) => s.file.toLowerCase() === q && !s.id.includes('#', s.file.length + 1));
-        if (fileRoots.length > 0) {
-            return fileRoots.map((s) => ({
-                section: s,
-                reason: 'exact match',
-            }));
+        const matchFiles = new Set();
+        // Direct match
+        for (const s of flat) {
+            if (s.file.toLowerCase() === q &&
+                !s.id.includes('#', s.file.length + 1)) {
+                matchFiles.add(s.file);
+            }
+        }
+        // File index expansion (keys are lowercase)
+        const indexPaths = fileIndex.get(q) ?? [];
+        for (const p of indexPaths) {
+            matchFiles.add(p);
+        }
+        if (matchFiles.size > 0) {
+            const fileRoots = flat.filter((s) => matchFiles.has(s.file) && !s.id.includes('#', s.file.length + 1));
+            if (fileRoots.length > 0) {
+                return fileRoots.map((s) => ({
+                    section: s,
+                    reason: 'exact match',
+                }));
+            }
         }
     }
     // 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 stemPaths = fileIndex.get(filePart) ?? [];
+        const stemPaths = fileIndex.get(filePart.toLowerCase()) ?? [];
         // Also try filePart as a direct file path (for root-level files not in index)
         const allPaths = stemPaths.length > 0 ? stemPaths : filePart ? [filePart] : [];
         for (const p of allPaths) {
@@ -343,8 +379,8 @@ export function findSections(sections, query) {
             return [...exactMatches, ...stemMatches];
     }
     else {
-        // Bare name: match root sections of files via stem index
-        const paths = fileIndex.get(normalized) ?? [];
+        // Bare name: match root sections of files via stem index (keys lowercase)
+        const paths = fileIndex.get(q) ?? [];
         for (const p of paths) {
             for (const s of flat) {
                 if (exact.includes(s))
@@ -373,24 +409,37 @@ export function findSections(sections, query) {
             .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"
+    // Also tries expanding the file part via the file index for short refs.
     const seenSub = new Set([...seen, ...subsection.map((m) => m.section.id)]);
     const qParts = q.split('#');
+    // Build query variants: original + file-index-expanded forms
+    const qVariants = [qParts];
+    if (qParts.length >= 2) {
+        const expanded = fileIndex.get(qParts[0]);
+        if (expanded) {
+            for (const exp of expanded) {
+                qVariants.push([exp.toLowerCase(), ...qParts.slice(1)]);
+            }
+        }
+    }
     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 qVariants.some((variant) => {
+                if (sParts.length <= variant.length)
+                    return false;
+                let qi = 0;
+                for (const sp of sParts) {
+                    if (sp === variant[qi])
+                        qi++;
+                    if (qi === variant.length)
+                        return true;
+                }
                 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;
@@ -472,10 +521,10 @@ export function findSections(sections, query) {
         ...fuzzyMatches,
     ];
 }
-export function extractRefs(filePath, content, latticeDir) {
+export function extractRefs(filePath, content, projectRoot) {
     const tree = parse(stripFrontmatter(content));
-    const file = latticeDir
-        ? relative(latticeDir, filePath).replace(/\.md$/, '')
+    const file = projectRoot
+        ? relative(projectRoot, filePath).replace(/\.md$/, '')
         : basename(filePath, '.md');
     const refs = [];
     // Build a flat list of sections to determine enclosing section for each wiki link

package/dist/src/mcp/server.js

@@ -1,14 +1,13 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { relative } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { findLatticeDir, loadAllSections, findSections, flattenSections, buildFileIndex, resolveRef, extractRefs, listLatticeFiles, } from '../lattice.js';
 import { scanCodeRefs } from '../code-refs.js';
 import { checkMd, checkCodeRefs, checkIndex } from '../cli/check.js';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-function formatSection(s, latDir) {
-    const relPath = relative(process.cwd(), latDir + '/' + s.file + '.md');
+function formatSection(s, projectRoot) {
+    const relPath = relative(process.cwd(), join(projectRoot, s.filePath));
     const kind = s.id.includes('#') ? 'Section' : 'File';
     const lines = [
         `* ${kind}: [[${s.id}]]`,
@@ -20,12 +19,13 @@ function formatSection(s, latDir) {
     }
     return lines.join('\n');
 }
-function formatMatches(header, matches, latDir) {
+function formatMatches(header, matches, projectRoot) {
     const lines = [header, ''];
     for (let i = 0; i < matches.length; i++) {
         if (i > 0)
             lines.push('');
-        lines.push(formatSection(matches[i].section, latDir) + ` (${matches[i].reason})`);
+        lines.push(formatSection(matches[i].section, projectRoot) +
+            ` (${matches[i].reason})`);
     }
     return lines.join('\n');
 }
@@ -35,6 +35,7 @@ export async function startMcpServer() {
         process.stderr.write('No lat.md directory found\n');
         process.exit(1);
     }
+    const projectRoot = dirname(latDir);
     const server = new McpServer({
         name: 'lat',
         version: '1.0.0',
@@ -56,7 +57,7 @@ export async function startMcpServer() {
             content: [
                 {
                     type: 'text',
-                    text: formatMatches(`Sections matching "${query}":`, matches, latDir),
+                    text: formatMatches(`Sections matching "${query}":`, matches, projectRoot),
                 },
             ],
         };
@@ -117,7 +118,7 @@ export async function startMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: formatMatches(`Search results for "${query}":`, matched, latDir),
+                        text: formatMatches(`Search results for "${query}":`, matched, projectRoot),
                     },
                 ],
             };
@@ -165,7 +166,8 @@ export async function startMcpServer() {
         });
         output += '\n\n<lat-context>\n';
         for (const ref of resolved.values()) {
-            const isExact = ref.best.reason === 'exact match';
+            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`;
@@ -175,7 +177,7 @@ export async function startMcpServer() {
             }
             for (const m of all) {
                 const reason = isExact ? '' : ` (${m.reason})`;
-                const relPath = relative(process.cwd(), latDir + '/' + m.section.file + '.md');
+                const relPath = relative(process.cwd(), join(projectRoot, m.section.filePath));
                 output += `  * [[${m.section.id}]]${reason}\n`;
                 output += `    * ${relPath}:${m.section.startLine}-${m.section.endLine}\n`;
                 if (m.section.body) {
@@ -259,7 +261,7 @@ export async function startMcpServer() {
             const matchingFromSections = new Set();
             for (const file of files) {
                 const content = await readFile(file, 'utf-8');
-                const fileRefs = extractRefs(file, content, latDir);
+                const fileRefs = extractRefs(file, content, projectRoot);
                 for (const ref of fileRefs) {
                     const { resolved: refResolved } = resolveRef(ref.target, sectionIds, fileIndex);
                     if (refResolved.toLowerCase() === targetId) {
@@ -275,7 +277,6 @@ export async function startMcpServer() {
             }
         }
         if (scope === 'code' || scope === 'md+code') {
-            const projectRoot = join(latDir, '..');
             const { refs: codeRefs } = await scanCodeRefs(projectRoot);
             for (const ref of codeRefs) {
                 const { resolved: codeResolved } = resolveRef(ref.target, sectionIds, fileIndex);
@@ -296,7 +297,7 @@ export async function startMcpServer() {
         }
         const parts = [];
         if (mdMatches.length > 0) {
-            parts.push(formatMatches(`References to "${exactMatch.id}":`, mdMatches, latDir));
+            parts.push(formatMatches(`References to "${exactMatch.id}":`, mdMatches, projectRoot));
         }
         if (codeLines.length > 0) {
             parts.push('Code references:\n' + codeLines.map((l) => `* ${l}`).join('\n'));

package/dist/src/search/index.js

@@ -1,24 +1,25 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { loadAllSections, flattenSections } from '../lattice.js';
 import { embed } from './embeddings.js';
 function hashContent(text) {
     return createHash('sha256').update(text).digest('hex');
 }
-async function sectionContent(section, latDir) {
-    const filePath = join(latDir, section.file + '.md');
+async function sectionContent(section, projectRoot) {
+    const filePath = join(projectRoot, section.filePath);
     const content = await readFile(filePath, 'utf-8');
     const lines = content.split('\n');
     return lines.slice(section.startLine - 1, section.endLine).join('\n');
 }
 export async function indexSections(latDir, db, provider, key) {
+    const projectRoot = dirname(latDir);
     const allSections = await loadAllSections(latDir);
     const flat = flattenSections(allSections);
     // Build current state: id -> { section, content, hash }
     const current = new Map();
     for (const s of flat) {
-        const text = await sectionContent(s, latDir);
+        const text = await sectionContent(s, projectRoot);
         current.set(s.id, { section: s, content: text, hash: hashContent(text) });
     }
     // Get existing hashes from DB

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

@@ -0,0 +1,23 @@
+import type { Section } from './lattice.js';
+export type SourceSymbol = {
+    name: string;
+    kind: 'function' | 'class' | 'const' | 'type' | 'interface' | 'method' | 'variable';
+    parent?: string;
+    startLine: number;
+    endLine: number;
+    signature: string;
+};
+export declare function parseSourceSymbols(filePath: string, content: string): Promise<SourceSymbol[]>;
+/**
+ * Check whether a source file path (relative to projectRoot) has a given symbol.
+ * Used by lat check to validate source code wiki links lazily.
+ */
+export declare function resolveSourceSymbol(filePath: string, symbolPath: string, projectRoot: string): Promise<{
+    found: boolean;
+    symbols: SourceSymbol[];
+    error?: string;
+}>;
+/**
+ * Convert source symbols to Section objects for uniform handling.
+ */
+export declare function sourceSymbolsToSections(symbols: SourceSymbol[], filePath: string): Section[];

package/dist/src/source-parser.js

@@ -0,0 +1,333 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { Parser, Language, } from 'web-tree-sitter';
+// Lazy singleton for the parser
+let parserReady = null;
+let parserInstance = null;
+const languages = new Map();
+function wasmDir() {
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve('@repomix/tree-sitter-wasms/package.json');
+    return join(dirname(pkgPath), 'out');
+}
+async function ensureParser() {
+    if (!parserReady) {
+        parserReady = Parser.init();
+    }
+    await parserReady;
+    if (!parserInstance) {
+        parserInstance = new Parser();
+    }
+    return parserInstance;
+}
+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',
+    };
+    const wasmFile = grammarMap[ext];
+    if (!wasmFile)
+        return null;
+    // Ensure WASM runtime is initialized before loading languages
+    await ensureParser();
+    if (!languages.has(wasmFile)) {
+        const wasmPath = join(wasmDir(), wasmFile);
+        const lang = await Language.load(wasmPath);
+        languages.set(wasmFile, lang);
+    }
+    return languages.get(wasmFile);
+}
+function extractName(node) {
+    const nameNode = node.childForFieldName('name');
+    return nameNode ? nameNode.text : null;
+}
+function extractTsSymbols(tree) {
+    const symbols = [];
+    const root = tree.rootNode;
+    for (let i = 0; i < root.childCount; i++) {
+        let node = root.child(i);
+        // Unwrap export_statement to get the inner declaration
+        const isExport = node.type === 'export_statement';
+        if (isExport) {
+            const inner = node.namedChildren.find((c) => c.type === 'function_declaration' ||
+                c.type === 'class_declaration' ||
+                c.type === 'lexical_declaration' ||
+                c.type === 'type_alias_declaration' ||
+                c.type === 'interface_declaration' ||
+                c.type === 'abstract_class_declaration');
+            if (inner)
+                node = inner;
+        }
+        const startLine = node.startPosition.row + 1;
+        const endLine = node.endPosition.row + 1;
+        if (node.type === 'function_declaration' ||
+            node.type === 'generator_function_declaration') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'function',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'class_declaration' ||
+            node.type === 'abstract_class_declaration') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'class',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+                // Extract methods
+                const body = node.childForFieldName('body');
+                if (body) {
+                    extractClassMethods(body, name, symbols);
+                }
+            }
+        }
+        else if (node.type === 'lexical_declaration') {
+            // const/let declarations
+            for (const decl of node.namedChildren) {
+                if (decl.type === 'variable_declarator') {
+                    const name = extractName(decl);
+                    if (name) {
+                        symbols.push({
+                            name,
+                            kind: 'const',
+                            startLine,
+                            endLine,
+                            signature: firstLine(node.text),
+                        });
+                    }
+                }
+            }
+        }
+        else if (node.type === 'type_alias_declaration') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'type',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'interface_declaration') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'interface',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+    }
+    return symbols;
+}
+function extractClassMethods(body, className, symbols) {
+    for (let i = 0; i < body.namedChildCount; i++) {
+        const member = body.namedChild(i);
+        if (member.type === 'method_definition' ||
+            member.type === 'public_field_definition') {
+            const name = extractName(member);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'method',
+                    parent: className,
+                    startLine: member.startPosition.row + 1,
+                    endLine: member.endPosition.row + 1,
+                    signature: firstLine(member.text),
+                });
+            }
+        }
+    }
+}
+function extractPySymbols(tree) {
+    const symbols = [];
+    const root = tree.rootNode;
+    for (let i = 0; i < root.childCount; i++) {
+        const node = root.child(i);
+        const startLine = node.startPosition.row + 1;
+        const endLine = node.endPosition.row + 1;
+        if (node.type === 'function_definition') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'function',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'class_definition') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'class',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+                // Extract methods
+                const body = node.childForFieldName('body');
+                if (body) {
+                    for (let j = 0; j < body.namedChildCount; j++) {
+                        const member = body.namedChild(j);
+                        if (member.type === 'function_definition') {
+                            const methodName = extractName(member);
+                            if (methodName) {
+                                symbols.push({
+                                    name: methodName,
+                                    kind: 'method',
+                                    parent: name,
+                                    startLine: member.startPosition.row + 1,
+                                    endLine: member.endPosition.row + 1,
+                                    signature: firstLine(member.text),
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else if (node.type === 'expression_statement' &&
+            node.namedChildCount === 1 &&
+            node.namedChild(0).type === 'assignment') {
+            // Top-level assignment: FOO = ...
+            const assign = node.namedChild(0);
+            const left = assign.childForFieldName('left');
+            if (left && left.type === 'identifier') {
+                symbols.push({
+                    name: left.text,
+                    kind: 'variable',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+    }
+    return symbols;
+}
+function firstLine(text) {
+    const nl = text.indexOf('\n');
+    return nl === -1 ? text : text.slice(0, nl);
+}
+export async function parseSourceSymbols(filePath, content) {
+    const ext = filePath.match(/\.[^.]+$/)?.[0] ?? '';
+    const lang = await getLanguage(ext);
+    if (!lang)
+        return [];
+    const p = await ensureParser();
+    p.setLanguage(lang);
+    const tree = p.parse(content);
+    if (!tree)
+        return [];
+    if (ext === '.py') {
+        return extractPySymbols(tree);
+    }
+    return extractTsSymbols(tree);
+}
+/**
+ * Check whether a source file path (relative to projectRoot) has a given symbol.
+ * Used by lat check to validate source code wiki links lazily.
+ */
+export async function resolveSourceSymbol(filePath, symbolPath, projectRoot) {
+    const absPath = join(projectRoot, filePath);
+    let content;
+    try {
+        content = readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        return { found: false, symbols: [] };
+    }
+    let symbols;
+    try {
+        symbols = await parseSourceSymbols(filePath, content);
+    }
+    catch (err) {
+        return {
+            found: false,
+            symbols: [],
+            error: `failed to parse "${filePath}": ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const parts = symbolPath.split('#');
+    if (parts.length === 1) {
+        // Simple symbol: getConfigDir
+        const found = symbols.some((s) => s.name === parts[0] && !s.parent);
+        return { found, symbols };
+    }
+    if (parts.length === 2) {
+        // Nested symbol: MyClass#myMethod
+        const found = symbols.some((s) => s.name === parts[1] && s.parent === parts[0]);
+        return { found, symbols };
+    }
+    return { found: false, symbols };
+}
+/**
+ * Convert source symbols to Section objects for uniform handling.
+ */
+export function sourceSymbolsToSections(symbols, filePath) {
+    const sections = [];
+    const classMap = new Map();
+    for (const sym of symbols) {
+        if (sym.parent)
+            continue; // Handle methods after their class
+        const section = {
+            id: `${filePath}#${sym.name}`,
+            heading: sym.name,
+            depth: 1,
+            file: filePath,
+            filePath,
+            children: [],
+            startLine: sym.startLine,
+            endLine: sym.endLine,
+            body: sym.signature,
+        };
+        sections.push(section);
+        if (sym.kind === 'class') {
+            classMap.set(sym.name, section);
+        }
+    }
+    // Add methods as children
+    for (const sym of symbols) {
+        if (!sym.parent)
+            continue;
+        const parentSection = classMap.get(sym.parent);
+        if (!parentSection)
+            continue;
+        const section = {
+            id: `${filePath}#${sym.parent}#${sym.name}`,
+            heading: sym.name,
+            depth: 2,
+            file: filePath,
+            filePath,
+            children: [],
+            startLine: sym.startLine,
+            endLine: sym.endLine,
+            body: sym.signature,
+        };
+        parentSection.children.push(section);
+    }
+    return sections;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "packageManager": "pnpm@10.30.2",
@@ -50,6 +50,7 @@
     "@folder/xdg": "^4.0.1",
     "@libsql/client": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@repomix/tree-sitter-wasms": "^0.1.16",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "ignore-walk": "^8.0.0",
@@ -58,6 +59,7 @@
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.0",
     "unist-util-visit": "^5.0.0",
+    "web-tree-sitter": "^0.26.6",
     "zod": "^4.3.6"
   }
 }

package/templates/AGENTS.md

@@ -33,8 +33,9 @@ If `lat search` fails because no API key is configured, explain to the user that
 
 # Syntax primer
 
-- **Section ids**: `path/to/file#Heading#SubHeading` — full form uses vault-relative path (e.g. `tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
-- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections
+- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
+- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
+- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`. `lat check` validates these exist.
 - **Code refs**: `// @lat: [[section-id]]` (JS/TS) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
 
 # Test specs

package/templates/cursor-rules.md

@@ -31,8 +31,9 @@ If `lat_search` fails because `LAT_LLM_KEY` is not set, explain to the user that
 
 # Syntax primer
 
-- **Section ids**: `path/to/file#Heading#SubHeading` — full form uses vault-relative path (e.g. `tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
-- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections
+- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
+- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
+- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`. `lat check` validates these exist.
 - **Code refs**: `// @lat: [[section-id]]` (JS/TS) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
 
 # Test specs