lat.md 0.7.0 → 0.7.1

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/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.
@@ -84,13 +84,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 +103,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 +111,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lat.md",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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",