@plebeiantech/lat.md 0.12.3-fork.13 → 0.12.3-fork.14

package/dist/src/markdown-analysis-cache.js

@@ -0,0 +1,139 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { PARSER_CACHE_VERSION, hashParserContent, parsedCachePath, parserCacheIdentity, readParsedCache, writeParsedCache, } from './parser-cache.js';
+import { toPosix } from './path.js';
+import { loadMarkdownAnalyzer } from './markdown-analyzer-loader.js';
+export { PARSER_CACHE_VERSION } from './parser-cache.js';
+/** Return the collision-safe, sharded cache path for one Markdown file. */
+export function markdownAnalysisCachePath(latDir, projectRoot, absolutePath) {
+    return parsedCachePath(latDir, parserCacheIdentity(absolutePath, projectRoot));
+}
+function emptyTimings(values) {
+    return {
+        ...values,
+        cacheWriteMs: 0,
+        parseMs: 0,
+        sectionsMs: 0,
+        refsMs: 0,
+        linksMs: 0,
+        paragraphsMs: 0,
+        frontmatterMs: 0,
+        indexEntriesMs: 0,
+        diagnosticsMs: 0,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function cachedAnalysis(entry, contentHash, content, absolutePath, latDir, projectRoot) {
+    if (!entry ||
+        entry.version !== PARSER_CACHE_VERSION ||
+        entry.contentHash !== contentHash) {
+        return null;
+    }
+    try {
+        const analysis = entry.value;
+        const expectedPath = toPosix(relative(latDir, absolutePath));
+        const expectedProjectPath = toPosix(relative(projectRoot, absolutePath));
+        if (!isRecord(analysis) ||
+            analysis.content !== content ||
+            analysis.path !== expectedPath ||
+            analysis.projectPath !== expectedProjectPath ||
+            !isRecord(analysis.frontmatter) ||
+            !Array.isArray(analysis.sections) ||
+            !Array.isArray(analysis.headingTitles) ||
+            !Array.isArray(analysis.wikiRefs) ||
+            !Array.isArray(analysis.paragraphs) ||
+            !Array.isArray(analysis.markdownLinks) ||
+            !Array.isArray(analysis.validationLinks) ||
+            !Array.isArray(analysis.indexEntries) ||
+            !Array.isArray(analysis.diagnostics)) {
+            return null;
+        }
+        return { ...analysis, absolutePath };
+    }
+    catch {
+        return null;
+    }
+}
+/** Read, hash, and attempt to hydrate one Markdown file from persistent cache. */
+export async function prepareMarkdownAnalysis(absolutePath, latDir, projectRoot, cache = true) {
+    const cachePath = markdownAnalysisCachePath(latDir, projectRoot, absolutePath);
+    const readStarted = performance.now();
+    const contentPromise = readFile(absolutePath, 'utf8').then((content) => ({
+        content,
+        readMs: performance.now() - readStarted,
+    }));
+    const cacheStarted = performance.now();
+    const cachePromise = cache
+        ? readParsedCache(cachePath).then((entry) => ({
+            entry,
+            cacheReadMs: performance.now() - cacheStarted,
+        }))
+        : Promise.resolve({ entry: null, cacheReadMs: 0 });
+    const [{ content, readMs }, { entry, cacheReadMs }] = await Promise.all([
+        contentPromise,
+        cachePromise,
+    ]);
+    const hashStarted = performance.now();
+    const contentHash = hashParserContent(content);
+    const hashMs = performance.now() - hashStarted;
+    const analysis = cache
+        ? cachedAnalysis(entry, contentHash, content, absolutePath, latDir, projectRoot)
+        : null;
+    const timings = {
+        readMs,
+        hashMs,
+        cacheReadMs,
+        cacheStatus: cache ? (analysis ? 'hit' : 'miss') : 'disabled',
+    };
+    return {
+        absolutePath,
+        cachePath,
+        content,
+        contentHash,
+        analysis: analysis
+            ? { ...analysis, timings: emptyTimings(timings) }
+            : undefined,
+        timings,
+    };
+}
+/** Attach I/O timings and best-effort publish one newly parsed analysis. */
+export async function publishMarkdownAnalysis(prepared, analysis) {
+    const base = {
+        ...analysis,
+        timings: {
+            ...analysis.timings,
+            ...prepared.timings,
+            cacheWriteMs: 0,
+        },
+    };
+    if (prepared.timings.cacheStatus === 'disabled')
+        return base;
+    const started = performance.now();
+    try {
+        await writeParsedCache(prepared.cachePath, prepared.contentHash, base);
+    }
+    catch {
+        // The cache is a disposable optimization; analysis must work read-only.
+    }
+    base.timings.cacheWriteMs = performance.now() - started;
+    return base;
+}
+/** Analyze one path through the same persistent cache used by project runs. */
+export async function analyzeMarkdownPath(absolutePath, latDir, projectRoot, cache = true, onParserImport) {
+    const prepared = await prepareMarkdownAnalysis(absolutePath, latDir, projectRoot, cache);
+    const detail = toPosix(relative(latDir, absolutePath));
+    if (prepared.analysis) {
+        onParserImport?.({
+            parser: 'Markdown analyzer',
+            imported: false,
+            durationMs: 0,
+            detail: `${detail} cached`,
+        });
+        return prepared.analysis;
+    }
+    const analyzeMarkdownFile = await loadMarkdownAnalyzer(onParserImport, detail);
+    return publishMarkdownAnalysis(prepared, analyzeMarkdownFile(absolutePath, prepared.content, latDir, projectRoot));
+}

package/dist/src/markdown-analysis-worker.d.ts

@@ -0,0 +1,16 @@
+import type { MarkdownFileAnalysis } from './markdown-analysis.js';
+export type MarkdownWorkerTask = {
+    id: number;
+    absolutePath: string;
+    content: string;
+    latDir: string;
+    projectRoot: string;
+};
+export type MarkdownWorkerResponse = {
+    id: number;
+    analysis: MarkdownFileAnalysis;
+    importMs?: number;
+} | {
+    id: number;
+    error: string;
+};

package/dist/src/markdown-analysis-worker.js

@@ -0,0 +1,33 @@
+import { parentPort } from 'node:worker_threads';
+import { performance } from 'node:perf_hooks';
+if (!parentPort)
+    throw new Error('Markdown analysis worker needs a parent port');
+async function loadAnalyzer() {
+    const started = performance.now();
+    const sourceRuntime = import.meta.url.endsWith('.ts');
+    const moduleUrl = new URL(sourceRuntime ? './markdown-analysis.ts' : './markdown-analysis.js', import.meta.url).href;
+    const module = sourceRuntime
+        ? await import('tsx/esm/api').then(({ tsImport }) => tsImport(moduleUrl, import.meta.url))
+        : await import(moduleUrl);
+    return {
+        analyzeMarkdownFile: module.analyzeMarkdownFile,
+        importMs: performance.now() - started,
+    };
+}
+const analyzerPromise = loadAnalyzer();
+let importReported = false;
+parentPort.on('message', async (task) => {
+    try {
+        const loaded = await analyzerPromise;
+        const importMs = importReported ? undefined : loaded.importMs;
+        importReported = true;
+        const analysis = loaded.analyzeMarkdownFile(task.absolutePath, task.content, task.latDir, task.projectRoot);
+        parentPort.postMessage({ id: task.id, analysis, importMs });
+    }
+    catch (error) {
+        parentPort.postMessage({
+            id: task.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+});

package/dist/src/markdown-analysis.d.ts

@@ -0,0 +1,50 @@
+import type { LatFrontmatter, MdLink, Ref, Section } from './lattice-model.js';
+import { type LocalMarkdownDiagnostic } from './markdown-validation.js';
+export type MarkdownParagraph = {
+    markdown: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+};
+export type MarkdownDestinationLink = {
+    kind: 'image' | 'link';
+    line: number;
+    url: string;
+};
+export type MarkdownAnalysisTimings = {
+    readMs: number;
+    hashMs: number;
+    cacheReadMs: number;
+    cacheWriteMs: number;
+    cacheStatus: 'disabled' | 'hit' | 'miss';
+    parseMs: number;
+    sectionsMs: number;
+    refsMs: number;
+    linksMs: number;
+    paragraphsMs: number;
+    frontmatterMs: number;
+    indexEntriesMs: number;
+    diagnosticsMs: number;
+};
+/** Serializable semantic facts extracted from one Markdown file. */
+export type MarkdownFileAnalysis = {
+    absolutePath: string;
+    content: string;
+    path: string;
+    projectPath: string;
+    frontmatter: LatFrontmatter;
+    sections: Section[];
+    headingTitles: string[];
+    wikiRefs: Ref[];
+    paragraphs: MarkdownParagraph[];
+    markdownLinks: MarkdownDestinationLink[];
+    validationLinks: MdLink[];
+    indexEntries: string[];
+    diagnostics: LocalMarkdownDiagnostic[];
+    timings: MarkdownAnalysisTimings;
+};
+/**
+ * Parse and analyze one Markdown document. The syntax tree is deliberately
+ * confined to this call so callers and workers only exchange serializable facts.
+ */
+export declare function analyzeMarkdownFile(absolutePath: string, content: string, latDir: string, projectRoot: string): MarkdownFileAnalysis;

package/dist/src/markdown-analysis.js

@@ -0,0 +1,139 @@
+import { performance } from 'node:perf_hooks';
+import { relative } from 'node:path';
+import { visit } from 'unist-util-visit';
+import { extractLinks, extractRefs, parseFrontmatter, parseSections, } from './lattice.js';
+import { parse } from './parser.js';
+import { toPosix } from './path.js';
+import { analyzeLocalMarkdownDiagnostics, } from './markdown-validation.js';
+function elapsed(work) {
+    const start = performance.now();
+    return [work(), performance.now() - start];
+}
+function inlineText(node) {
+    if (node.type === 'wikiLink')
+        return node.data.alias ?? node.value;
+    if ('value' in node && typeof node.value === 'string')
+        return node.value;
+    if (node.type === 'image')
+        return node.alt ?? '';
+    if (!('children' in node) || !Array.isArray(node.children))
+        return '';
+    return node.children
+        .map((child) => inlineText(child))
+        .join('');
+}
+function extractParagraphs(content, tree) {
+    const result = [];
+    visit(tree, 'paragraph', (node) => {
+        const startLine = node.position?.start.line;
+        const endLine = node.position?.end.line;
+        if (!startLine || !endLine)
+            return;
+        const text = inlineText(node).replace(/\s+/g, ' ').trim();
+        const startOffset = node.position?.start.offset;
+        const endOffset = node.position?.end.offset;
+        result.push({
+            markdown: startOffset === undefined || endOffset === undefined
+                ? text
+                : content.slice(startOffset, endOffset),
+            startLine,
+            endLine,
+            text,
+        });
+    });
+    return result;
+}
+function extractHeadingTitles(tree) {
+    const titles = [];
+    visit(tree, 'heading', (node) => {
+        titles.push(inlineText(node));
+    });
+    return titles;
+}
+function extractDestinationLinks(tree) {
+    const definitions = new Map();
+    visit(tree, 'definition', (node) => {
+        definitions.set(node.identifier.toLowerCase(), node.url);
+    });
+    const links = [];
+    visit(tree, (node) => {
+        if (node.type !== 'link' &&
+            node.type !== 'image' &&
+            node.type !== 'linkReference' &&
+            node.type !== 'imageReference') {
+            return;
+        }
+        const line = node.position?.start.line;
+        if (!line)
+            return;
+        const url = node.type === 'link' || node.type === 'image'
+            ? node.url
+            : definitions.get(node.identifier.toLowerCase());
+        if (!url)
+            return;
+        links.push({
+            kind: node.type === 'image' || node.type === 'imageReference'
+                ? 'image'
+                : 'link',
+            line,
+            url,
+        });
+    });
+    return links;
+}
+function extractIndexEntries(content) {
+    const names = new Set();
+    const pattern = /^- \[\[([^\]]+?)(?:\|[^\]]+)?\]\]/gm;
+    let match;
+    while ((match = pattern.exec(content)) !== null)
+        names.add(match[1]);
+    return [...names];
+}
+/**
+ * Parse and analyze one Markdown document. The syntax tree is deliberately
+ * confined to this call so callers and workers only exchange serializable facts.
+ */
+export function analyzeMarkdownFile(absolutePath, content, latDir, projectRoot) {
+    const [tree, parseMs] = elapsed(() => parse(content));
+    const [sections, sectionsMs] = elapsed(() => parseSections(absolutePath, content, projectRoot, tree));
+    const [wikiRefs, refsMs] = elapsed(() => extractRefs(absolutePath, content, projectRoot, tree));
+    const [validationLinks, linksMs] = elapsed(() => extractLinks(content, tree));
+    const [[paragraphs, markdownLinks, headingTitles], paragraphsMs] = elapsed(() => [
+        extractParagraphs(content, tree),
+        extractDestinationLinks(tree),
+        extractHeadingTitles(tree),
+    ]);
+    const [frontmatter, frontmatterMs] = elapsed(() => parseFrontmatter(content));
+    const [indexEntries, indexEntriesMs] = elapsed(() => extractIndexEntries(content));
+    const [diagnostics, diagnosticsMs] = elapsed(() => analyzeLocalMarkdownDiagnostics(validationLinks, sections));
+    return {
+        absolutePath,
+        content,
+        path: toPosix(relative(latDir, absolutePath)),
+        projectPath: toPosix(relative(projectRoot, absolutePath)),
+        frontmatter,
+        sections,
+        headingTitles,
+        wikiRefs,
+        paragraphs,
+        markdownLinks,
+        validationLinks,
+        indexEntries,
+        diagnostics,
+        timings: {
+            readMs: 0,
+            hashMs: 0,
+            cacheReadMs: 0,
+            cacheWriteMs: 0,
+            cacheStatus: 'disabled',
+            parseMs,
+            sectionsMs,
+            refsMs,
+            linksMs,
+            paragraphsMs,
+            frontmatterMs,
+            indexEntriesMs,
+            diagnosticsMs,
+        },
+    };
+}

package/dist/src/markdown-analyzer-loader.d.ts

@@ -0,0 +1,4 @@
+import type { analyzeMarkdownFile } from './markdown-analysis.js';
+import type { ParserImportObserver } from './parser-import.js';
+/** Load the Markdown analyzer at the cache-miss boundary and report its cost. */
+export declare function loadMarkdownAnalyzer(onParserImport?: ParserImportObserver, detail?: string): Promise<typeof analyzeMarkdownFile>;

package/dist/src/markdown-analyzer-loader.js

@@ -0,0 +1,13 @@
+import { performance } from 'node:perf_hooks';
+/** Load the Markdown analyzer at the cache-miss boundary and report its cost. */
+export async function loadMarkdownAnalyzer(onParserImport, detail) {
+    const started = performance.now();
+    const module = await import('./markdown-analysis.js');
+    onParserImport?.({
+        parser: 'Markdown analyzer',
+        imported: true,
+        durationMs: performance.now() - started,
+        detail,
+    });
+    return module.analyzeMarkdownFile;
+}

package/dist/src/markdown-validation.d.ts

@@ -0,0 +1,25 @@
+import { type MdLink, type Section } from './lattice-model.js';
+export declare const MAX_SECTION_SUMMARY_LENGTH = 250;
+export type LocalMarkdownDiagnostic = {
+    rule: 'markdown-reference-definition' | 'markdown-path-separator' | 'section-leading-paragraph';
+    line: number;
+    target: string;
+    message: string;
+    anchor?: string;
+    marker?: 'target' | 'line' | 'heading';
+};
+export type LocalMarkdownTarget = {
+    kind: 'target';
+    /** Decoded on-disk path, or null for a fragment in the current file. */
+    path: string | null;
+    /** Decoded fragment without `#`, or null when none was authored. */
+    fragment: string | null;
+} | {
+    kind: 'invalid-backslash';
+};
+/** Parse a local Markdown destination without confusing escaped #/? in paths. */
+export declare function parseLocalMarkdownTarget(url: string): LocalMarkdownTarget | null;
+/** Count summary text while excluding `[[...]]` markers and link content. */
+export declare function sectionSummaryLength(body: string): number;
+/** Validate rules that need no facts outside one parsed Markdown file. */
+export declare function analyzeLocalMarkdownDiagnostics(links: readonly MdLink[], sections: readonly Section[]): LocalMarkdownDiagnostic[];

package/dist/src/markdown-validation.js

@@ -0,0 +1,104 @@
+import { flattenSections } from './lattice-model.js';
+export const MAX_SECTION_SUMMARY_LENGTH = 250;
+function decodeLinkPart(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** Parse a local Markdown destination without confusing escaped #/? in paths. */
+export function parseLocalMarkdownTarget(url) {
+    const value = url.trim();
+    if (value.startsWith('/'))
+        return null;
+    const windowsDrivePath = /^[a-zA-Z]:\\/.test(value);
+    if (!windowsDrivePath && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) {
+        return null;
+    }
+    // Split before decoding: `%23` and `%3F` decode to `#` and `?`, which would
+    // then truncate a filename that legitimately contains them.
+    const queryAt = value.indexOf('?');
+    const fragmentAt = value.indexOf('#');
+    const pathEnd = Math.min(queryAt === -1 ? value.length : queryAt, fragmentAt === -1 ? value.length : fragmentAt);
+    const rawPath = value.slice(0, pathEnd);
+    const path = rawPath === '' ? null : decodeLinkPart(rawPath);
+    const fragment = fragmentAt === -1 ? null : decodeLinkPart(value.slice(fragmentAt + 1));
+    if (rawPath === '' && fragment === null)
+        return null;
+    if (path?.includes('\\'))
+        return { kind: 'invalid-backslash' };
+    return { kind: 'target', path, fragment };
+}
+/** Count summary text while excluding `[[...]]` markers and link content. */
+export function sectionSummaryLength(body) {
+    return body.replace(/\[\[[^\]]*\]\]/g, '').length;
+}
+/** Validate rules that need no facts outside one parsed Markdown file. */
+export function analyzeLocalMarkdownDiagnostics(links, sections) {
+    const diagnostics = [];
+    for (const link of links) {
+        if ('identifier' in link) {
+            const kind = link.kind === 'imageReference' ? 'image' : 'link';
+            const renderedKind = kind === 'image' ? 'an image' : 'a link';
+            const escapedSource = link.source.replace('[', '\\[');
+            diagnostics.push({
+                rule: 'markdown-reference-definition',
+                line: link.line,
+                target: link.identifier,
+                message: link.style === 'definition'
+                    ? `malformed reference definition (${link.source}) — ` +
+                        `write it as "[${link.identifier}]: <destination>" on its own line, ` +
+                        `or escape the opening bracket as "${escapedSource}" to keep it as literal text`
+                    : link.style === 'shortcut'
+                        ? `undefined shortcut ${kind} reference (${link.source}) — ` +
+                            `add a definition "[${link.identifier}]: <destination>" to make it ${renderedKind}, ` +
+                            `or escape the opening bracket as "${escapedSource}" to keep it as literal text`
+                        : `undefined ${kind} reference (${link.source}) — definition "[${link.identifier}]" not found`,
+                marker: 'line',
+            });
+            continue;
+        }
+        if (parseLocalMarkdownTarget(link.url)?.kind === 'invalid-backslash') {
+            const kind = link.kind === 'image' ? 'image' : 'link';
+            diagnostics.push({
+                rule: 'markdown-path-separator',
+                line: link.line,
+                target: link.url,
+                message: `invalid ${kind} (${link.url}) — backslashes are not path ` +
+                    'separators in Markdown; use "/" instead',
+            });
+        }
+    }
+    for (const section of flattenSections([...sections])) {
+        if (!section.firstParagraph) {
+            diagnostics.push({
+                rule: 'section-leading-paragraph',
+                line: section.startLine,
+                target: section.id,
+                message: `section "${section.id}" has no leading paragraph. ` +
+                    `Every section must start with a brief overview (≤${MAX_SECTION_SUMMARY_LENGTH} chars) ` +
+                    `summarizing what it documents — this powers search snippets and command output.`,
+                anchor: section.githubSlug,
+                marker: 'heading',
+            });
+            continue;
+        }
+        const length = sectionSummaryLength(section.firstParagraph);
+        if (length > MAX_SECTION_SUMMARY_LENGTH) {
+            diagnostics.push({
+                rule: 'section-leading-paragraph',
+                line: section.startLine,
+                target: section.id,
+                message: `section "${section.id}" leading paragraph is ${length} characters ` +
+                    `(max ${MAX_SECTION_SUMMARY_LENGTH}, excluding [[wiki links]]). ` +
+                    `Keep the first paragraph brief — it serves as the section's summary ` +
+                    `in search results and command output. Use subsequent paragraphs for details.`,
+                anchor: section.githubSlug,
+                marker: 'heading',
+            });
+        }
+    }
+    return diagnostics;
+}

package/dist/src/mcp/server.js

@@ -2,14 +2,16 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { dirname } from 'node:path';
-import { findLatticeDir } from '../lattice.js';
+import { findLatticeDir } from '../project-discovery.js';
 import { plainStyler } from '../context.js';
 import { locateCommand } from '../cli/locate.js';
 import { sectionCommand } from '../cli/section.js';
 import { searchCommand } from '../cli/search.js';
+import { DEFAULT_SEARCH_LIMIT, DEFAULT_SEARCH_THRESHOLD, } from '../search/search.js';
 import { expandCommand } from '../cli/expand.js';
 import { checkAllCommand } from '../cli/check.js';
 import { refsCommand } from '../cli/refs.js';
+import { externalListCommand, externalShowCommand } from '../cli/external.js';
 function toMcp(result) {
     const content = [{ type: 'text', text: result.output }];
     return result.isError ? { content, isError: true } : { content };
@@ -27,24 +29,34 @@ export async function startMcpServer() {
         styler: plainStyler,
         mode: 'mcp',
     };
+    const requestContext = () => ({ ...ctx, analysis: undefined });
     const server = new McpServer({
         name: 'lat',
         version: '1.0.0',
     });
-    server.tool('lat_locate', 'Find sections by name (exact, fuzzy, subsequence matching)', { query: z.string().describe('Section name or id to search for') }, async ({ query }) => toMcp(await locateCommand(ctx, query)));
-    server.tool('lat_section', 'Show a section with its content, outgoing wiki link targets, and incoming references', {
-        query: z.string().describe('Section id to look up (short or full form)'),
-    }, async ({ query }) => toMcp(await sectionCommand(ctx, query)));
+    server.tool('lat_locate', 'Find sections by name (exact, fuzzy, subsequence matching)', { query: z.string().describe('Section name or id to search for') }, async ({ query }) => toMcp(await locateCommand(requestContext(), query)));
+    server.tool('lat_section', 'Show a local section or exact external target with content and references', {
+        query: z
+            .string()
+            .describe('Local section id or exact handle:path#fragment target'),
+    }, async ({ query }) => toMcp(await sectionCommand(requestContext(), query)));
     server.tool('lat_search', 'Semantic search across lat.md sections using embeddings', {
         query: z.string().describe('Search query in natural language'),
         limit: z
             .number()
             .optional()
-            .default(5)
-            .describe('Max results (default 5)'),
-    }, async ({ query, limit }) => toMcp(await searchCommand(ctx, query, { limit })));
-    server.tool('lat_expand', 'Expand [[refs]] in text to resolved lat.md section paths with context', { text: z.string().describe('Text containing [[refs]] to expand') }, async ({ text: input }) => toMcp(await expandCommand(ctx, input)));
-    server.tool('lat_check', 'Run full lat.md validation: links, code references, indexes, and section structure', {}, async () => toMcp(await checkAllCommand(ctx)));
+            .default(DEFAULT_SEARCH_LIMIT)
+            .describe(`Max results (default ${DEFAULT_SEARCH_LIMIT})`),
+        threshold: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .default(DEFAULT_SEARCH_THRESHOLD)
+            .describe('Minimum cosine similarity score (default 0.35)'),
+    }, async ({ query, limit, threshold }) => toMcp(await searchCommand(requestContext(), query, { limit, threshold })));
+    server.tool('lat_expand', 'Expand [[refs]] in text to resolved lat.md section paths with context', { text: z.string().describe('Text containing [[refs]] to expand') }, async ({ text: input }) => toMcp(await expandCommand(requestContext(), input)));
+    server.tool('lat_check', 'Run full lat.md validation: links, code references, indexes, and section structure', {}, async () => toMcp(await checkAllCommand(requestContext())));
     server.tool('lat_refs', 'Find sections that reference a given section via wiki links or @lat code comments', {
         query: z.string().describe('Section id to find references for'),
         scope: z
@@ -52,7 +64,11 @@ export async function startMcpServer() {
             .optional()
             .default('md+code')
             .describe('Where to search: md, code, or md+code'),
-    }, async ({ query, scope }) => toMcp(await refsCommand(ctx, query, scope)));
+    }, async ({ query, scope }) => toMcp(await refsCommand(requestContext(), query, scope)));
+    server.tool('lat_external_list', 'List configured external sources without fetching or changing caches', {}, async () => toMcp(await externalListCommand(ctx, true)));
+    server.tool('lat_external_show', 'Show one configured external source or exact external target without fetching it', {
+        source: z.string().describe('External source handle or exact target'),
+    }, async ({ source }) => toMcp(await externalShowCommand(ctx, source, true)));
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/src/parser-cache.d.ts

@@ -0,0 +1,17 @@
+/** Version of persistent parser outputs and their shared on-disk contract. */
+export declare const PARSER_CACHE_VERSION = 1;
+export type ParsedCacheEntry = {
+    version: number;
+    contentHash: string;
+    value: unknown;
+};
+/** Hash complete parser input bytes for cache invalidation. */
+export declare function hashParserContent(content: string): string;
+/** Normalize an on-disk file into its project-relative parser identity. */
+export declare function parserCacheIdentity(absolutePath: string, projectRoot: string): string;
+/** Return the collision-safe, short-name-sharded cache path for an identity. */
+export declare function parsedCachePath(latDir: string, identity: string): string;
+/** Read and decode a cache entry, treating every malformed state as a miss. */
+export declare function readParsedCache(path: string): Promise<ParsedCacheEntry | null>;
+/** Atomically publish one disposable parser cache entry. */
+export declare function writeParsedCache(path: string, contentHash: string, value: unknown): Promise<void>;