lat.md 0.5.0 → 0.7.0

package/package.json

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

@@ -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
 ```
 
@@ -33,9 +33,10 @@ 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
-- **Code refs**: `// @lat: [[section-id]]` (JS/TS) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
+- **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/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
 
@@ -48,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.
 
@@ -56,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:
 
@@ -71,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
 
@@ -31,9 +31,10 @@ 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
-- **Code refs**: `// @lat: [[section-id]]` (JS/TS) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
+- **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/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
 
@@ -46,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>;

package/dist/src/cli/prompt.js

@@ -1,60 +0,0 @@
-import { 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');
-    return `${relPath}:${section.startLine}-${section.endLine}`;
-}
-export async function promptCmd(ctx, text) {
-    const allSections = await loadAllSections(ctx.latDir);
-    const refs = [...text.matchAll(WIKI_LINK_RE)];
-    if (refs.length === 0) {
-        process.stdout.write(text);
-        return;
-    }
-    const resolved = new Map();
-    for (const match of refs) {
-        const target = match[1];
-        if (resolved.has(target))
-            continue;
-        const matches = findSections(allSections, target);
-        if (matches.length >= 1) {
-            resolved.set(target, {
-                target,
-                best: matches[0],
-                alternatives: matches.slice(1),
-            });
-            continue;
-        }
-        console.error(ctx.chalk.red(`No section found for [[${target}]] (no exact, substring, or fuzzy matches).`));
-        console.error(ctx.chalk.dim('Ask the user to correct the reference.'));
-        process.exit(1);
-    }
-    // Replace [[refs]] inline
-    let output = text.replace(WIKI_LINK_RE, (_match, target) => {
-        const ref = resolved.get(target);
-        return `[[${ref.best.section.id}]]`;
-    });
-    // 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 all = isExact ? [ref.best] : [ref.best, ...ref.alternatives];
-        if (isExact) {
-            output += `* \`[[${ref.target}]]\` is referring to:\n`;
-        }
-        else {
-            output += `* \`[[${ref.target}]]\` might be referring to either of the following:\n`;
-        }
-        for (const m of all) {
-            const reason = isExact ? '' : ` (${m.reason})`;
-            output += `  * [[${m.section.id}]]${reason}\n`;
-            output += `    * ${formatLocation(m.section, ctx.latDir)}\n`;
-            if (m.section.body) {
-                output += `    * ${m.section.body}\n`;
-            }
-        }
-    }
-    output += '</lat-context>\n';
-    process.stdout.write(output);
-}