lat.md 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yury Selivanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,66 @@
-# Lattice
+# lat.md
 
-Anchor source code to high-level concepts defined in markdown. 
-See [lattice.md](lattice.md) for the full spec.
+[![CI](https://github.com/1st1/lat.md/actions/workflows/ci.yml/badge.svg)](https://github.com/1st1/lat.md/actions/workflows/ci.yml)
+
+A knowledge graph for your codebase, written in markdown.
+
+## The problem
+
+`AGENTS.md` doesn't scale. A single flat file can describe a small project, but as a codebase grows, maintaining one monolithic document becomes impractical. Key design decisions get buried, business logic goes undocumented, and agents hallucinate context they should be able to look up.
+
+## The idea
+
+Compress the knowledge about your program domain into a **graph** — a set of interconnected markdown files that live in a `lat.md/` directory at the root of your project. Sections link to each other with `[[wiki links]]`, source files link back with `// @lat:` comments, and `lat check` ensures nothing drifts out of sync.
+
+The result is a structured knowledge base that:
+
+- 📈 **Scales** — split knowledge across as many files and sections as you need
+- 🔗 **Cross-references** — wiki links (`[[cli#search#Indexing]]`) connect concepts into a navigable graph
+- ✅ **Stays in sync** — `lat check` validates that all links resolve and that required code references exist
+- 🔍 **Is searchable** — exact, fuzzy, and semantic (vector) search across all sections
+- 🤝 **Works for humans and machines** — readable in any editor (or Obsidian), queryable by agents via the `lat` CLI
+
+## Install
+
+```bash
+npm install -g lat.md
+```
+
+Or use directly with `npx lat.md <command>`.
+
+## 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.
+
+```
+my-project/
+├── lat.md/
+│   ├── architecture.md    # system design, key decisions
+│   ├── auth.md            # authentication & authorization logic
+│   └── tests.md           # test specs (require-code-mention: true)
+├── src/
+│   ├── auth.ts            # // @lat: [[auth#OAuth Flow]]
+│   └── server.ts          # // @lat: [[architecture#Request Pipeline]]
+└── ...
+```
+
+## CLI
+
+```bash
+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 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
+```
 
 ## Development
 
-Requires Node.js 22+.
+Requires Node.js 22+ and pnpm.
 
 ```bash
 pnpm install
-pnpm test            # run tests once
-pnpm test:watch      # run tests in watch mode
-pnpm typecheck       # tsc --noEmit
-pnpm format          # prettier
+pnpm build
+pnpm test
 ```

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

@@ -0,0 +1,18 @@
+import type { CliContext } from './context.js';
+export type CheckError = {
+    file: string;
+    line: number;
+    target: string;
+    message: string;
+};
+/** File counts grouped by extension (e.g. { ".ts": 5, ".py": 2 }). */
+export type FileStats = Record<string, number>;
+export type CheckResult = {
+    errors: CheckError[];
+    files: FileStats;
+};
+export declare function checkMd(latticeDir: string): Promise<CheckResult>;
+export declare function checkCodeRefs(latticeDir: string): Promise<CheckResult>;
+export declare function checkMdCmd(ctx: CliContext): Promise<void>;
+export declare function checkCodeRefsCmd(ctx: CliContext): Promise<void>;
+export declare function checkAllCmd(ctx: CliContext): Promise<void>;

package/dist/src/cli/check.js

@@ -0,0 +1,122 @@
+import { readFile } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import { listLatticeFiles, loadAllSections, extractRefs, flattenSections, parseFrontmatter, parseSections, } from '../lattice.js';
+import { scanCodeRefs } from '../code-refs.js';
+function countByExt(paths) {
+    const stats = {};
+    for (const p of paths) {
+        const ext = extname(p) || '(no ext)';
+        stats[ext] = (stats[ext] || 0) + 1;
+    }
+    return stats;
+}
+export async function checkMd(latticeDir) {
+    const files = await listLatticeFiles(latticeDir);
+    const allSections = await loadAllSections(latticeDir);
+    const flat = flattenSections(allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const errors = [];
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        const refs = extractRefs(file, content);
+        const relPath = relative(process.cwd(), file);
+        for (const ref of refs) {
+            const target = ref.target.toLowerCase();
+            if (!sectionIds.has(target)) {
+                errors.push({
+                    file: relPath,
+                    line: ref.line,
+                    target: ref.target,
+                    message: `broken link [[${ref.target}]] — no matching section found`,
+                });
+            }
+        }
+    }
+    return { errors, files: countByExt(files) };
+}
+export async function checkCodeRefs(latticeDir) {
+    const projectRoot = join(latticeDir, '..');
+    const allSections = await loadAllSections(latticeDir);
+    const flat = flattenSections(allSections);
+    const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const scan = await scanCodeRefs(projectRoot);
+    const errors = [];
+    const mentionedSections = new Set();
+    for (const ref of scan.refs) {
+        const target = ref.target.toLowerCase();
+        mentionedSections.add(target);
+        if (!sectionIds.has(target)) {
+            errors.push({
+                file: ref.file,
+                line: ref.line,
+                target: ref.target,
+                message: `@lat: [[${ref.target}]] — no matching section found`,
+            });
+        }
+    }
+    const files = await listLatticeFiles(latticeDir);
+    for (const file of files) {
+        const content = await readFile(file, 'utf-8');
+        const fm = parseFrontmatter(content);
+        if (!fm.requireCodeMention)
+            continue;
+        const sections = parseSections(file, content);
+        const fileSections = flattenSections(sections);
+        const leafSections = fileSections.filter((s) => s.children.length === 0);
+        const relPath = relative(process.cwd(), file);
+        for (const leaf of leafSections) {
+            if (!mentionedSections.has(leaf.id.toLowerCase())) {
+                errors.push({
+                    file: relPath,
+                    line: leaf.startLine,
+                    target: leaf.id,
+                    message: `section "${leaf.id}" requires a code mention but none found`,
+                });
+            }
+        }
+    }
+    return { errors, files: countByExt(scan.files) };
+}
+function formatErrors(ctx, errors) {
+    for (const err of errors) {
+        console.error(`${ctx.chalk.cyan(err.file + ':' + err.line)}: ${ctx.chalk.red(err.message)}`);
+    }
+    if (errors.length > 0) {
+        console.error(ctx.chalk.red(`\n${errors.length} error${errors.length === 1 ? '' : 's'} found`));
+    }
+}
+function formatStats(ctx, stats) {
+    const entries = Object.entries(stats).sort(([a], [b]) => a.localeCompare(b));
+    const parts = entries.map(([ext, n]) => `${n} ${ext}`);
+    console.log(ctx.chalk.dim(`Scanned ${parts.join(', ')}`));
+}
+export async function checkMdCmd(ctx) {
+    const { errors, files } = await checkMd(ctx.latDir);
+    formatStats(ctx, files);
+    formatErrors(ctx, errors);
+    if (errors.length > 0)
+        process.exit(1);
+    console.log(ctx.chalk.green('md: All links OK'));
+}
+export async function checkCodeRefsCmd(ctx) {
+    const { errors, files } = await checkCodeRefs(ctx.latDir);
+    formatStats(ctx, files);
+    formatErrors(ctx, errors);
+    if (errors.length > 0)
+        process.exit(1);
+    console.log(ctx.chalk.green('code-refs: All references OK'));
+}
+export async function checkAllCmd(ctx) {
+    const md = await checkMd(ctx.latDir);
+    const code = await checkCodeRefs(ctx.latDir);
+    const allErrors = [...md.errors, ...code.errors];
+    const allFiles = { ...md.files };
+    for (const [ext, n] of Object.entries(code.files)) {
+        allFiles[ext] = (allFiles[ext] || 0) + n;
+    }
+    formatStats(ctx, allFiles);
+    formatErrors(ctx, allErrors);
+    if (allErrors.length > 0)
+        process.exit(1);
+    console.log(ctx.chalk.green('All checks passed'));
+}

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

@@ -0,0 +1,10 @@
+import { type ChalkInstance } from 'chalk';
+export type CliContext = {
+    latDir: string;
+    color: boolean;
+    chalk: ChalkInstance;
+};
+export declare function resolveContext(opts: {
+    dir?: string;
+    color?: boolean;
+}): CliContext;

package/dist/src/cli/context.js

@@ -0,0 +1,14 @@
+import chalk from 'chalk';
+import { findLatticeDir } from '../lattice.js';
+export function resolveContext(opts) {
+    const color = opts.color !== false;
+    if (!color) {
+        chalk.level = 0;
+    }
+    const latDir = findLatticeDir(opts.dir) ?? '';
+    if (!latDir) {
+        console.error(chalk.red('No lat.md directory found'));
+        process.exit(1);
+    }
+    return { latDir, color, chalk };
+}

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

@@ -0,0 +1,2 @@
+export declare function readAgentsTemplate(): string;
+export declare function genCmd(target: string): Promise<void>;

package/dist/src/cli/gen.js

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findTemplatesDir } from './templates.js';
+export function readAgentsTemplate() {
+    return readFileSync(join(findTemplatesDir(), 'AGENTS.md'), 'utf-8');
+}
+export async function genCmd(target) {
+    const normalized = target.toLowerCase();
+    if (normalized !== 'agents.md' && normalized !== 'claude.md') {
+        console.error(`Unknown target: ${target}. Supported: agents.md, claude.md`);
+        process.exit(1);
+    }
+    process.stdout.write(readAgentsTemplate());
+}

package/dist/src/cli/index.js

@@ -1,19 +1,128 @@
 #!/usr/bin/env node
-import { locate } from './locate.js';
-import { refs } from './refs.js';
-const args = process.argv.slice(2);
-const command = args[0];
-const commands = {
-    locate,
-    refs,
-};
-const handler = commands[command];
-if (!handler) {
-    console.error(`Usage: lat <command>
-
-Commands:
-  locate <query>                          Find sections by id
-  refs <query> [--scope=md|code|md+code]  Find references to a section`);
-    process.exit(1);
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { resolveContext } from './context.js';
+import { locateCmd } from './locate.js';
+import { refsCmd } from './refs.js';
+function findPackageJson() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = join(dir, 'package.json');
+        try {
+            return JSON.parse(readFileSync(candidate, 'utf-8')).version;
+        }
+        catch { }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return '0.0.0';
+        dir = parent;
+    }
 }
-await handler(args.slice(1));
+const version = findPackageJson();
+const program = new Command();
+program
+    .name('lat')
+    .description('Anchor source code to high-level concepts defined in markdown')
+    .version(version)
+    .option('--dir <path>', 'project root to look for lat.md in (default: cwd)')
+    .option('--no-color', 'disable color output');
+program
+    .command('locate')
+    .description('Find sections by id')
+    .argument('<query>', 'section id to search for')
+    .action(async (query) => {
+    const ctx = resolveContext(program.opts());
+    await locateCmd(ctx, query);
+});
+program
+    .command('refs')
+    .description('Find references to a section')
+    .argument('<query>', 'section id to find references for')
+    .option('--scope <scope>', 'where to search: md, code, or md+code', 'md')
+    .action(async (query, opts) => {
+    const scope = opts.scope;
+    if (scope !== 'md' && scope !== 'code' && scope !== 'md+code') {
+        console.error(`Unknown scope: ${scope}. Use md, code, or md+code.`);
+        process.exit(1);
+    }
+    const ctx = resolveContext(program.opts());
+    await refsCmd(ctx, query, scope);
+});
+const check = program
+    .command('check')
+    .description('Validate links and code references')
+    .action(async () => {
+    const ctx = resolveContext(program.opts());
+    const { checkAllCmd } = await import('./check.js');
+    await checkAllCmd(ctx);
+});
+check
+    .command('md')
+    .description('Validate wiki links in lat.md markdown files')
+    .action(async () => {
+    const ctx = resolveContext(program.opts());
+    const { checkMdCmd } = await import('./check.js');
+    await checkMdCmd(ctx);
+});
+check
+    .command('code-refs')
+    .description('Validate @lat code references and coverage')
+    .action(async () => {
+    const ctx = resolveContext(program.opts());
+    const { checkCodeRefsCmd } = await import('./check.js');
+    await checkCodeRefsCmd(ctx);
+});
+program
+    .command('prompt')
+    .description('Expand [[refs]] in a prompt to lat.md section locations')
+    .argument('[text]', 'prompt text')
+    .option('--stdin', 'read prompt from stdin')
+    .action(async (text, opts) => {
+    if (opts.stdin) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        text = Buffer.concat(chunks).toString('utf-8');
+    }
+    if (!text) {
+        console.error('Provide prompt text as an argument or use --stdin');
+        process.exit(1);
+    }
+    const ctx = resolveContext(program.opts());
+    const { promptCmd } = await import('./prompt.js');
+    await promptCmd(ctx, text);
+});
+program
+    .command('search')
+    .description('Semantic search across lat.md sections')
+    .argument('[query]', 'search query in plain English')
+    .option('--limit <n>', 'max results', '5')
+    .option('--reindex', 'force full re-indexing')
+    .action(async (query, opts) => {
+    const ctx = resolveContext(program.opts());
+    const { searchCmd } = await import('./search.js');
+    await searchCmd(ctx, query, {
+        limit: parseInt(opts.limit),
+        reindex: opts.reindex,
+    });
+});
+program
+    .command('gen')
+    .description('Generate a file to stdout (agents.md, claude.md)')
+    .argument('<target>', 'file to generate: agents.md or claude.md')
+    .action(async (target) => {
+    const { genCmd } = await import('./gen.js');
+    await genCmd(target);
+});
+program
+    .command('init')
+    .description('Initialize a lat.md directory')
+    .argument('[dir]', 'target directory (default: cwd)')
+    .action(async (dir) => {
+    const { initCmd } = await import('./init.js');
+    await initCmd(dir);
+});
+await program.parseAsync();

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

@@ -0,0 +1 @@
+export declare function initCmd(targetDir?: string): Promise<void>;

package/dist/src/cli/init.js

@@ -0,0 +1,67 @@
+import { existsSync, cpSync, mkdirSync, writeFileSync, symlinkSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import chalk from 'chalk';
+import { findTemplatesDir } from './templates.js';
+import { readAgentsTemplate } from './gen.js';
+async function confirm(rl, message) {
+    try {
+        const answer = await rl.question(`${message} ${chalk.dim('[Y/n]')} `);
+        return answer.trim().toLowerCase() !== 'n';
+    }
+    catch {
+        return true;
+    }
+}
+export async function initCmd(targetDir) {
+    const root = resolve(targetDir ?? process.cwd());
+    const latDir = join(root, 'lat.md');
+    const interactive = process.stdin.isTTY ?? false;
+    const rl = interactive
+        ? createInterface({ input: process.stdin, output: process.stdout })
+        : null;
+    const ask = async (message) => {
+        if (!rl)
+            return true;
+        return confirm(rl, message);
+    };
+    try {
+        // Step 1: lat.md/ directory
+        if (existsSync(latDir)) {
+            console.log(chalk.green('lat.md/') + ' already exists');
+        }
+        else {
+            if (!(await ask('Create lat.md/ directory?'))) {
+                console.log('Aborted.');
+                return;
+            }
+            const templateDir = join(findTemplatesDir(), 'init');
+            mkdirSync(latDir, { recursive: true });
+            cpSync(templateDir, latDir, { recursive: true });
+            console.log(chalk.green('Created lat.md/'));
+        }
+        // Step 2: AGENTS.md / CLAUDE.md
+        const agentsPath = join(root, 'AGENTS.md');
+        const claudePath = join(root, 'CLAUDE.md');
+        const hasAgents = existsSync(agentsPath);
+        const hasClaude = existsSync(claudePath);
+        if (!hasAgents && !hasClaude) {
+            if (await ask('Generate AGENTS.md and CLAUDE.md with lat.md instructions for coding agents?')) {
+                const template = readAgentsTemplate();
+                writeFileSync(agentsPath, template);
+                symlinkSync('AGENTS.md', claudePath);
+                console.log(chalk.green('Created AGENTS.md and CLAUDE.md → AGENTS.md'));
+            }
+        }
+        else {
+            const existing = [hasAgents && 'AGENTS.md', hasClaude && 'CLAUDE.md']
+                .filter(Boolean)
+                .join(' and ');
+            console.log(`\n${existing} already exists. Run ${chalk.cyan('lat gen agents.md')} to preview the template,` +
+                ` then incorporate its content or overwrite as needed.`);
+        }
+    }
+    finally {
+        rl?.close();
+    }
+}

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

@@ -1 +1,2 @@
-export declare function locate(args: string[]): Promise<void>;
+import type { CliContext } from './context.js';
+export declare function locateCmd(ctx: CliContext, query: string): Promise<void>;

package/dist/src/cli/locate.js

@@ -1,25 +1,13 @@
-import { findLatticeDir, loadAllSections, findSections } from '../lattice.js';
-import { formatSectionPreview } from '../format.js';
-export async function locate(args) {
-    if (args.length < 1) {
-        console.error('Usage: lat locate <query>');
-        process.exit(1);
-    }
-    const query = args[0];
-    const latticeDir = findLatticeDir();
-    if (!latticeDir) {
-        console.error('No .lattice directory found');
-        process.exit(1);
-    }
-    const sections = await loadAllSections(latticeDir);
+import { loadAllSections, findSections } from '../lattice.js';
+import { formatResultList } from '../format.js';
+export async function locateCmd(ctx, query) {
+    const sections = await loadAllSections(ctx.latDir);
     const matches = findSections(sections, query);
     if (matches.length === 0) {
-        console.error(`No sections matching "${query}"`);
+        console.error(ctx.chalk.red(`No sections matching "${query}" (no exact, substring, or fuzzy matches)`));
         process.exit(1);
     }
-    for (let i = 0; i < matches.length; i++) {
-        if (i > 0)
-            console.log('');
-        console.log(formatSectionPreview(matches[i], latticeDir));
-    }
+    console.log(formatResultList(`Sections matching "${query}":`, matches, ctx.latDir, {
+        numbered: true,
+    }));
 }

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

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

package/dist/src/cli/prompt.js

@@ -0,0 +1,62 @@
+import { relative } from 'node:path';
+import { loadAllSections, findSections, flattenSections, } from '../lattice.js';
+const WIKI_LINK_RE = /\[\[([^\]]+)\]\]/g;
+function formatContext(section, latDir) {
+    const relPath = relative(process.cwd(), latDir + '/' + section.file + '.md');
+    const loc = `${relPath}:${section.startLine}-${section.endLine}`;
+    let text = `[${section.id}](${loc})`;
+    if (section.body) {
+        text += `: ${section.body}`;
+    }
+    return text;
+}
+export async function promptCmd(ctx, text) {
+    const allSections = await loadAllSections(ctx.latDir);
+    const flat = flattenSections(allSections);
+    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 q = target.toLowerCase();
+        const exact = flat.find((s) => s.id.toLowerCase() === q);
+        if (exact) {
+            resolved.set(target, exact);
+            continue;
+        }
+        const fuzzy = findSections(allSections, target);
+        if (fuzzy.length === 1) {
+            resolved.set(target, fuzzy[0]);
+            continue;
+        }
+        if (fuzzy.length > 1) {
+            console.error(ctx.chalk.red(`Ambiguous reference [[${target}]].`));
+            console.error(ctx.chalk.dim('\nCould match:\n'));
+            for (const m of fuzzy) {
+                console.error('  ' + m.id);
+            }
+            console.error(ctx.chalk.dim('\nAsk the user which section they meant.'));
+            process.exit(1);
+        }
+        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 section = resolved.get(target);
+        return `[[${section.id}]]`;
+    });
+    // Append context block
+    output += '\n\n<lat-context>\n';
+    for (const section of resolved.values()) {
+        output += formatContext(section, ctx.latDir) + '\n';
+    }
+    output += '</lat-context>\n';
+    process.stdout.write(output);
+}

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

@@ -1 +1,4 @@
-export declare function refs(args: string[]): Promise<void>;
+import type { CliContext } from './context.js';
+type Scope = 'md' | 'code' | 'md+code';
+export declare function refsCmd(ctx: CliContext, query: string, scope: Scope): Promise<void>;
+export {};