lat.md 0.6.0 → 0.7.1

package/dist/src/source-parser.js

@@ -28,6 +28,10 @@ async function getLanguage(ext) {
         '.js': 'tree-sitter-javascript.wasm',
         '.jsx': 'tree-sitter-javascript.wasm',
         '.py': 'tree-sitter-python.wasm',
+        '.rs': 'tree-sitter-rust.wasm',
+        '.go': 'tree-sitter-go.wasm',
+        '.c': 'tree-sitter-c.wasm',
+        '.h': 'tree-sitter-c.wasm',
     };
     const wasmFile = grammarMap[ext];
     if (!wasmFile)
@@ -228,6 +232,380 @@ function extractPySymbols(tree) {
     }
     return symbols;
 }
+function extractRustSymbols(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_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'function',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'struct_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'class',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'enum_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'class',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'trait_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'interface',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'impl_item') {
+            // impl Type { ... } or impl Trait for Type { ... }
+            const typeName = node.childForFieldName('type')?.text;
+            if (!typeName)
+                continue;
+            const body = node.childForFieldName('body');
+            if (!body)
+                continue;
+            for (let j = 0; j < body.namedChildCount; j++) {
+                const member = body.namedChild(j);
+                if (member.type === 'function_item') {
+                    const name = extractName(member);
+                    if (name) {
+                        symbols.push({
+                            name,
+                            kind: 'method',
+                            parent: typeName,
+                            startLine: member.startPosition.row + 1,
+                            endLine: member.endPosition.row + 1,
+                            signature: firstLine(member.text),
+                        });
+                    }
+                }
+            }
+        }
+        else if (node.type === 'const_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'const',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'static_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'variable',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'type_item') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'type',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+    }
+    return symbols;
+}
+/**
+ * Extract the receiver type name from a Go method declaration's receiver node.
+ * Handles both value receivers (Greeter) and pointer receivers (*Greeter).
+ */
+function goReceiverType(receiverNode) {
+    const param = receiverNode.namedChild(0);
+    if (!param)
+        return null;
+    const typeNode = param.childForFieldName('type');
+    if (!typeNode)
+        return null;
+    // pointer_type -> child is the actual type name
+    if (typeNode.type === 'pointer_type') {
+        return typeNode.namedChild(0)?.text ?? null;
+    }
+    return typeNode.text;
+}
+function extractGoSymbols(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_declaration') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'function',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'method_declaration') {
+            const name = extractName(node);
+            const receiver = node.childForFieldName('receiver');
+            const typeName = receiver ? goReceiverType(receiver) : null;
+            if (name && typeName) {
+                symbols.push({
+                    name,
+                    kind: 'method',
+                    parent: typeName,
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'type_declaration') {
+            for (let j = 0; j < node.namedChildCount; j++) {
+                const spec = node.namedChild(j);
+                if (spec.type !== 'type_spec')
+                    continue;
+                const name = spec.childForFieldName('name')?.text;
+                if (!name)
+                    continue;
+                const typeNode = spec.childForFieldName('type');
+                const kind = typeNode?.type === 'interface_type' ? 'interface' : 'class';
+                symbols.push({
+                    name,
+                    kind,
+                    startLine: spec.startPosition.row + 1,
+                    endLine: spec.endPosition.row + 1,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'const_declaration') {
+            for (let j = 0; j < node.namedChildCount; j++) {
+                const spec = node.namedChild(j);
+                if (spec.type !== 'const_spec')
+                    continue;
+                const name = spec.childForFieldName('name')?.text;
+                if (name) {
+                    symbols.push({
+                        name,
+                        kind: 'const',
+                        startLine: spec.startPosition.row + 1,
+                        endLine: spec.endPosition.row + 1,
+                        signature: firstLine(node.text),
+                    });
+                }
+            }
+        }
+        else if (node.type === 'var_declaration') {
+            for (let j = 0; j < node.namedChildCount; j++) {
+                const spec = node.namedChild(j);
+                if (spec.type !== 'var_spec')
+                    continue;
+                const name = spec.childForFieldName('name')?.text;
+                if (name) {
+                    symbols.push({
+                        name,
+                        kind: 'variable',
+                        startLine: spec.startPosition.row + 1,
+                        endLine: spec.endPosition.row + 1,
+                        signature: firstLine(node.text),
+                    });
+                }
+            }
+        }
+    }
+    return symbols;
+}
+/**
+ * Extract the declarator name from a C function_declarator node.
+ * Handles plain identifiers and pointer declarators (*name).
+ */
+function cFuncName(declarator) {
+    if (declarator.type === 'function_declarator') {
+        const inner = declarator.childForFieldName('declarator');
+        if (!inner)
+            return null;
+        if (inner.type === 'identifier')
+            return inner.text;
+        if (inner.type === 'pointer_declarator') {
+            // *name — dig through pointer layers
+            let cur = inner;
+            while (cur.type === 'pointer_declarator') {
+                const child = cur.childForFieldName('declarator');
+                if (!child)
+                    return null;
+                cur = child;
+            }
+            return cur.type === 'identifier' ? cur.text : null;
+        }
+    }
+    return null;
+}
+/**
+ * Extract the variable name from a C init_declarator or plain declarator.
+ * Handles pointers like `*DEFAULT_NAME = "World"`.
+ */
+function cVarName(declarator) {
+    let node = declarator;
+    // Unwrap init_declarator to get the declarator part
+    if (node.type === 'init_declarator') {
+        const inner = node.childForFieldName('declarator');
+        if (!inner)
+            return null;
+        node = inner;
+    }
+    if (node.type === 'identifier')
+        return node.text;
+    if (node.type === 'pointer_declarator') {
+        let cur = node;
+        while (cur.type === 'pointer_declarator') {
+            const child = cur.childForFieldName('declarator');
+            if (!child)
+                return null;
+            cur = child;
+        }
+        return cur.type === 'identifier' ? cur.text : null;
+    }
+    return null;
+}
+function extractCSymbols(tree) {
+    const symbols = [];
+    collectCNodes(tree.rootNode, symbols);
+    return symbols;
+}
+/**
+ * Walk C AST nodes, collecting symbols. Recurses into preproc_ifdef /
+ * preproc_ifndef blocks so header include guards don't hide declarations.
+ */
+function collectCNodes(parent, symbols) {
+    for (let i = 0; i < parent.childCount; i++) {
+        const node = parent.child(i);
+        const startLine = node.startPosition.row + 1;
+        const endLine = node.endPosition.row + 1;
+        if (node.type === 'function_definition') {
+            const declarator = node.childForFieldName('declarator');
+            const name = declarator ? cFuncName(declarator) : null;
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'function',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'struct_specifier') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'class',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'enum_specifier') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'class',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'type_definition') {
+            const declarator = node.childForFieldName('declarator');
+            const name = declarator?.type === 'type_identifier' ? declarator.text : null;
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'type',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'declaration') {
+            const declarator = node.childForFieldName('declarator');
+            const name = declarator ? cVarName(declarator) : null;
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'variable',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'preproc_def') {
+            const name = extractName(node);
+            if (name) {
+                symbols.push({
+                    name,
+                    kind: 'const',
+                    startLine,
+                    endLine,
+                    signature: firstLine(node.text),
+                });
+            }
+        }
+        else if (node.type === 'preproc_ifdef' ||
+            node.type === 'preproc_ifndef') {
+            // Recurse into include guard / conditional blocks
+            collectCNodes(node, symbols);
+        }
+    }
+}
 function firstLine(text) {
     const nl = text.indexOf('\n');
     return nl === -1 ? text : text.slice(0, nl);
@@ -245,6 +623,15 @@ export async function parseSourceSymbols(filePath, content) {
     if (ext === '.py') {
         return extractPySymbols(tree);
     }
+    if (ext === '.rs') {
+        return extractRustSymbols(tree);
+    }
+    if (ext === '.go') {
+        return extractGoSymbols(tree);
+    }
+    if (ext === '.c' || ext === '.h') {
+        return extractCSymbols(tree);
+    }
     return extractTsSymbols(tree);
 }
 /**
@@ -302,7 +689,7 @@ export function sourceSymbolsToSections(symbols, filePath) {
             children: [],
             startLine: sym.startLine,
             endLine: sym.endLine,
-            body: sym.signature,
+            firstParagraph: sym.signature,
         };
         sections.push(section);
         if (sym.kind === 'class') {
@@ -325,7 +712,7 @@ export function sourceSymbolsToSections(symbols, filePath) {
             children: [],
             startLine: sym.startLine,
             endLine: sym.endLine,
-            body: sym.signature,
+            firstParagraph: sym.signature,
         };
         parentSection.children.push(section);
     }

package/package.json

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

package/templates/AGENTS.md

@@ -1,7 +1,7 @@
 # Before starting work
 
 - Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
-- Run `lat prompt` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
+- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
 
 # Post-task checklist (REQUIRED — do not skip)
 
@@ -23,7 +23,7 @@ This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a s
 lat locate "Section Name"      # find a section by name (exact, fuzzy)
 lat refs "file#Section"        # find what references a section
 lat search "natural language"  # semantic search across all sections
-lat prompt "user prompt text"  # expand [[refs]] to resolved locations
+lat expand "user prompt text"  # expand [[refs]] to resolved locations
 lat check                      # validate all links and code refs
 ```
 
@@ -35,8 +35,8 @@ If `lat search` fails because no API key is configured, explain to the user that
 
 - **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
+- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
+- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
 
 # Test specs
 
@@ -49,7 +49,12 @@ lat:
 ---
 # Tests
 
+Authentication and authorization test specifications.
+
 ## User login
+
+Verify credential validation and error handling for the login endpoint.
+
 ### Rejects expired tokens
 Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
 
@@ -57,7 +62,7 @@ Tokens past their expiry timestamp are rejected with 401, even if otherwise vali
 Login request without a password field returns 400 with a descriptive error.
 ```
 
-Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable.
+Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
 
 Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
 
@@ -72,3 +77,29 @@ def test_handles_missing_password():
 ```
 
 Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
+
+# Section structure
+
+Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
+
+```markdown
+# Good Section
+
+Brief overview of what this section documents and why it matters.
+
+More detail can go in subsequent paragraphs, code blocks, or lists.
+
+## Child heading
+
+Details about this child topic.
+```
+
+```markdown
+# Bad Section
+
+## Child heading
+
+Details about this child topic.
+```
+
+The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.

package/templates/cursor-rules.md

@@ -1,7 +1,7 @@
 # Before starting work
 
 - Use the `lat_search` tool to find sections relevant to your task. Read them to understand the design intent before writing code.
-- Use the `lat_prompt` tool on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
+- Use the `lat_expand` tool on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
 
 # Post-task checklist (REQUIRED — do not skip)
 
@@ -23,7 +23,7 @@ You have access to the following MCP tools from the `lat` server:
 
 - **lat_locate** — find a section by name (exact, fuzzy)
 - **lat_search** — semantic search across all sections
-- **lat_prompt** — expand `[[refs]]` in text to resolved locations
+- **lat_expand** — expand `[[refs]]` in text to resolved locations
 - **lat_check** — validate all wiki links and code refs
 - **lat_refs** — find what references a section
 
@@ -33,8 +33,8 @@ If `lat_search` fails because `LAT_LLM_KEY` is not set, explain to the user that
 
 - **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
+- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
+- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
 
 # Test specs
 
@@ -47,7 +47,12 @@ lat:
 ---
 # Tests
 
+Authentication and authorization test specifications.
+
 ## User login
+
+Verify credential validation and error handling for the login endpoint.
+
 ### Rejects expired tokens
 Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
 

package/templates/lat-prompt-hook.sh

@@ -3,14 +3,14 @@
 # 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
+# telling the agent to run `lat search` and `lat expand` 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."
+    "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 expand` 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

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

@@ -1,2 +0,0 @@
-import type { CliContext } from './context.js';
-export declare function promptCmd(ctx: CliContext, text: string): Promise<void>;