lat.md 0.4.2 → 0.5.0

package/dist/src/cli/check.js

@@ -127,19 +127,26 @@ function immediateEntries(walkedPaths) {
     }
     return [...entries].sort();
 }
-/** Parse bullet items from an index file. Matches `- **name** — description` */
+/** Parse bullet items from an index file. Matches `- [[name]] — description` */
 function parseIndexEntries(content) {
     const names = new Set();
-    const re = /^- \*\*(.+?)\*\*/gm;
+    const re = /^- \[\[([^\]]+?)(?:\|[^\]]+)?\]\]/gm;
     let match;
     while ((match = re.exec(content)) !== null) {
         names.add(match[1]);
     }
     return names;
 }
+/**
+ * Convert a filesystem entry name to its wiki link stem.
+ * Strips `.md` extension from files; directories stay as-is.
+ */
+function entryToStem(name) {
+    return name.endsWith('.md') ? name.slice(0, -3) : name;
+}
 /** Generate a bullet-list snippet for the given entry names. */
 function indexSnippet(entries) {
-    return entries.map((e) => `- **${e}** — <describe>`).join('\n');
+    return entries.map((e) => `- [[${entryToStem(e)}]] — <describe>`).join('\n');
 }
 export async function checkIndex(latticeDir) {
     const errors = [];
@@ -183,12 +190,16 @@ export async function checkIndex(latticeDir) {
             });
             continue;
         }
-        // Parse existing entries and validate
+        // Parse existing entries and validate.
+        // Listed entries are wiki link stems (no .md extension).
+        // Children are filesystem names (with .md for files, bare for dirs).
         const listed = parseIndexEntries(content);
+        const childStems = new Set(children.map(entryToStem));
+        const stemToChild = new Map(children.map((c) => [entryToStem(c), c]));
         const relDir = dir === '' ? basename(latticeDir) + '/' : dir + '/';
         const missing = [];
         for (const child of children) {
-            if (!listed.has(child)) {
+            if (!listed.has(entryToStem(child))) {
                 missing.push(child);
             }
         }
@@ -199,11 +210,12 @@ export async function checkIndex(latticeDir) {
                 snippet: indexSnippet(missing),
             });
         }
+        const indexStem = entryToStem(indexFileName);
         for (const name of listed) {
-            if (!children.includes(name) && name !== indexFileName) {
+            if (!childStems.has(name) && name !== indexStem) {
                 errors.push({
                     dir: relDir,
-                    message: `"${indexRelPath}" lists "${name}" but it does not exist`,
+                    message: `"${indexRelPath}" lists "[[${name}]]" but it does not exist`,
                 });
             }
         }

package/dist/src/cli/context.js

@@ -8,6 +8,7 @@ export function resolveContext(opts) {
     const latDir = findLatticeDir(opts.dir) ?? '';
     if (!latDir) {
         console.error(chalk.red('No lat.md directory found'));
+        console.error(chalk.dim('Run `lat init` to create one.'));
         process.exit(1);
     }
     return { latDir, color, chalk };

package/dist/src/lattice.js

@@ -81,7 +81,7 @@ export function parseSections(filePath, content, latticeDir) {
             stack.pop();
         }
         const parent = stack.length > 0 ? stack[stack.length - 1] : null;
-        const id = parent ? `${parent.id}#${heading}` : file;
+        const id = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
         const section = {
             id,
             heading,
@@ -131,28 +131,14 @@ export function parseSections(filePath, content, latticeDir) {
     }
     return roots;
 }
-const sectionsCache = new Map();
-export function loadAllSections(latticeDir) {
-    const noCache = !!process.env._LAT_TEST_DISABLE_FS_CACHE;
-    const key = resolve(latticeDir);
-    if (!noCache) {
-        const cached = sectionsCache.get(key);
-        if (cached)
-            return cached;
+export async function loadAllSections(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));
     }
-    const result = (async () => {
-        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));
-        }
-        return all;
-    })();
-    if (!noCache) {
-        sectionsCache.set(key, result);
-    }
-    return result;
+    return all;
 }
 export function flattenSections(sections) {
     const result = [];
@@ -232,17 +218,39 @@ export function resolveRef(target, sectionIds, fileIndex) {
     const hashIdx = target.indexOf('#');
     const filePart = hashIdx === -1 ? target : target.slice(0, hashIdx);
     const rest = hashIdx === -1 ? '' : target.slice(hashIdx);
-    const candidates = fileIndex.get(filePart) ?? [];
-    if (candidates.length === 1) {
-        const expanded = candidates[0] + rest;
+    // Try resolving the file part: either it's a full path or a bare stem
+    const filePaths = fileIndex.has(filePart)
+        ? fileIndex.get(filePart)
+        : [filePart];
+    if (filePaths.length === 1) {
+        const fp = filePaths[0];
+        const expanded = fp + rest;
         if (sectionIds.has(expanded.toLowerCase())) {
             return { resolved: expanded, ambiguous: null, suggested: null };
         }
+        // Try inserting root headings between file and rest.
+        // Handles Obsidian-style file#heading refs where the h1 is implicit.
+        const rootHeadings = findRootHeadings(fp, sectionIds);
+        for (const h1 of rootHeadings) {
+            const withRoot = rest ? `${fp}#${h1}${rest}` : `${fp}#${h1}`;
+            if (sectionIds.has(withRoot.toLowerCase())) {
+                return { resolved: withRoot, ambiguous: null, suggested: null };
+            }
+        }
     }
-    else if (candidates.length > 1) {
+    else if (filePaths.length > 1) {
         // Multiple files share this stem — ambiguous at the filename level
-        const all = candidates.map((c) => c + rest);
-        const valid = candidates.filter((c) => sectionIds.has((c + rest).toLowerCase()));
+        const all = filePaths.map((c) => c + rest);
+        const valid = filePaths.filter((c) => {
+            if (sectionIds.has((c + rest).toLowerCase()))
+                return true;
+            // Also try with root heading insertion
+            const rootHeadings = findRootHeadings(c, sectionIds);
+            return rootHeadings.some((h1) => {
+                const withRoot = rest ? `${c}#${h1}${rest}` : `${c}#${h1}`;
+                return sectionIds.has(withRoot.toLowerCase());
+            });
+        });
         return {
             resolved: target,
             ambiguous: all,
@@ -251,6 +259,20 @@ export function resolveRef(target, sectionIds, fileIndex) {
     }
     return { resolved: target, ambiguous: null, suggested: null };
 }
+/**
+ * Find root (h1) headings for a file by scanning sectionIds for entries
+ * that have exactly the pattern `file#heading` (no further # segments).
+ */
+function findRootHeadings(file, sectionIds) {
+    const prefix = file.toLowerCase() + '#';
+    const headings = [];
+    for (const id of sectionIds) {
+        if (id.startsWith(prefix) && !id.includes('#', prefix.length)) {
+            headings.push(id.slice(prefix.length));
+        }
+    }
+    return headings;
+}
 const MAX_DISTANCE_RATIO = 0.4;
 export function findSections(sections, query) {
     const flat = flattenSections(sections);
@@ -266,6 +288,16 @@ export function findSections(sections, query) {
     }));
     if (exactMatches.length > 0 && isFullPath)
         return exactMatches;
+    // Tier 1a: bare name matches file — return root sections of that file
+    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',
+            }));
+        }
+    }
     // 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"
@@ -276,26 +308,53 @@ export function findSections(sections, 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 stemPaths = fileIndex.get(filePart) ?? [];
+        // 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) {
             const expanded = (p + rest).toLowerCase();
             const s = flat.find((s) => s.id.toLowerCase() === expanded && !exact.includes(s));
-            if (s)
+            if (s) {
                 stemMatches.push({
                     section: s,
-                    reason: `file stem expanded: ${filePart} → ${p}`,
+                    reason: stemPaths.length > 0
+                        ? `file stem expanded: ${filePart} → ${p}`
+                        : 'exact match',
                 });
+                continue;
+            }
+            // Try inserting root headings: file#rest → file#h1#rest
+            const rootsOfFile = flat.filter((s) => s.file.toLowerCase() === p.toLowerCase() &&
+                !s.id.includes('#', s.file.length + 1));
+            for (const root of rootsOfFile) {
+                const withRoot = (root.id + rest).toLowerCase();
+                const match = flat.find((s) => s.id.toLowerCase() === withRoot && !exact.includes(s));
+                if (match) {
+                    stemMatches.push({
+                        section: match,
+                        reason: stemPaths.length > 0
+                            ? `file stem expanded: ${filePart} → ${p}`
+                            : 'exact match',
+                    });
+                }
+            }
         }
         if (stemMatches.length > 0)
             return [...exactMatches, ...stemMatches];
     }
     else {
-        // Bare name: match file root sections via stem index
+        // Bare name: match root sections of files 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' });
+            for (const s of flat) {
+                if (exact.includes(s))
+                    continue;
+                // Root sections have id = "file#heading" (exactly 2 segments)
+                if (s.file.toLowerCase() === p.toLowerCase() &&
+                    !s.id.includes('#', s.file.length + 1)) {
+                    stemMatches.push({ section: s, reason: 'file stem match' });
+                }
+            }
         }
     }
     // Tier 2: exact match on trailing segments (subsection name match)
@@ -437,7 +496,7 @@ export function extractRefs(filePath, content, latticeDir) {
             stack.pop();
         }
         const parent = stack.length > 0 ? stack[stack.length - 1] : null;
-        const id = parent ? `${parent.id}#${heading}` : file;
+        const id = parent ? `${parent.id}#${heading}` : `${file}#${heading}`;
         flat[idx].id = id;
         stack.push({ id, depth });
         idx++;

package/dist/src/walk.d.ts

@@ -2,10 +2,6 @@
  * Walk a directory tree respecting .gitignore rules. Returns relative paths
  * of all non-ignored files, excluding .git/ and dotfiles (e.g. .gitignore).
  *
- * Results are memoized by resolved directory path — safe because CLI commands
- * don't modify the filesystem during a run. Set _LAT_TEST_DISABLE_FS_CACHE=1
- * to bypass caching in tests that mutate the filesystem mid-run.
- *
  * This is the single entry point for all directory walking in lat.md — both
  * code-ref scanning and lat.md/ index validation use it so .gitignore rules
  * are consistently honored.

package/dist/src/walk.js

@@ -1,32 +1,16 @@
-import { resolve } from 'node:path';
 // @ts-expect-error -- no type declarations
 import walk from 'ignore-walk';
-const cache = new Map();
 /**
  * Walk a directory tree respecting .gitignore rules. Returns relative paths
  * of all non-ignored files, excluding .git/ and dotfiles (e.g. .gitignore).
  *
- * Results are memoized by resolved directory path — safe because CLI commands
- * don't modify the filesystem during a run. Set _LAT_TEST_DISABLE_FS_CACHE=1
- * to bypass caching in tests that mutate the filesystem mid-run.
- *
  * This is the single entry point for all directory walking in lat.md — both
  * code-ref scanning and lat.md/ index validation use it so .gitignore rules
  * are consistently honored.
  */
 export function walkEntries(dir) {
-    const noCache = !!process.env._LAT_TEST_DISABLE_FS_CACHE;
-    if (!noCache) {
-        const cached = cache.get(resolve(dir));
-        if (cached)
-            return cached;
-    }
-    const result = walk({
+    return walk({
         path: dir,
         ignoreFiles: ['.gitignore'],
     }).then((entries) => entries.filter((e) => !e.startsWith('.git/') && !e.startsWith('.')));
-    if (!noCache) {
-        cache.set(resolve(dir), result);
-    }
-    return result;
 }

package/package.json

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