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

package/dist/src/parser-cache.js

@@ -0,0 +1,65 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative } from 'node:path';
+import { toPosix } from './path.js';
+/** Version of persistent parser outputs and their shared on-disk contract. */
+export const PARSER_CACHE_VERSION = 1;
+/** Hash complete parser input bytes for cache invalidation. */
+export function hashParserContent(content) {
+    return createHash('sha1').update(content).digest('hex');
+}
+/** Normalize an on-disk file into its project-relative parser identity. */
+export function parserCacheIdentity(absolutePath, projectRoot) {
+    return toPosix(relative(projectRoot, absolutePath)).normalize('NFC');
+}
+function readablePath(identity) {
+    const normalized = identity
+        .replace(/[^a-zA-Z0-9_-]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+    return (normalized || 'parsed').slice(-120);
+}
+function cacheShard(identity) {
+    const shortName = basename(identity);
+    const stem = shortName.slice(0, shortName.length - extname(shortName).length);
+    const firstTwo = [...stem.toLowerCase()].slice(0, 2).join('');
+    return firstTwo.replace(/[^a-z0-9]/g, '_') || '_';
+}
+/** Return the collision-safe, short-name-sharded cache path for an identity. */
+export function parsedCachePath(latDir, identity) {
+    const normalizedIdentity = toPosix(identity).normalize('NFC');
+    const digest = hashParserContent(normalizedIdentity);
+    return join(latDir, '.cache', 'parsed', cacheShard(normalizedIdentity), `${digest}_${readablePath(normalizedIdentity)}`);
+}
+/** Read and decode a cache entry, treating every malformed state as a miss. */
+export async function readParsedCache(path) {
+    try {
+        const serialized = await readFile(path, 'utf8');
+        const newline = serialized.indexOf('\n');
+        if (newline < 0)
+            return null;
+        const match = /^v(\d+):([a-f0-9]{40})$/.exec(serialized.slice(0, newline).trim());
+        if (!match)
+            return null;
+        return {
+            version: Number(match[1]),
+            contentHash: match[2],
+            value: JSON.parse(serialized.slice(newline + 1)),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically publish one disposable parser cache entry. */
+export async function writeParsedCache(path, contentHash, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, `v${PARSER_CACHE_VERSION}:${contentHash}\n${JSON.stringify(value)}\n`);
+        await rename(temp, path);
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => { });
+    }
+}

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

@@ -0,0 +1,8 @@
+/** One observable decision to load or skip a lazily imported parser module. */
+export type ParserImportEvent = {
+    parser: 'AsciiDoc parser' | 'Markdown analyzer' | 'reStructuredText parser';
+    imported: boolean;
+    durationMs: number;
+    detail?: string;
+};
+export type ParserImportObserver = (event: ParserImportEvent) => void;

package/dist/src/parser-import.js

@@ -0,0 +1 @@
+export {};

package/dist/src/parser.js

@@ -2,17 +2,92 @@ import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
 import remarkFrontmatter from 'remark-frontmatter';
+import remarkMath from 'remark-math';
+import { gfmAutolinkLiteralFromMarkdown } from 'mdast-util-gfm-autolink-literal';
+import { gfmFootnoteFromMarkdown, gfmFootnoteToMarkdown, } from 'mdast-util-gfm-footnote';
+import { gfmStrikethroughFromMarkdown, gfmStrikethroughToMarkdown, } from 'mdast-util-gfm-strikethrough';
+import { gfmTableFromMarkdown, gfmTableToMarkdown } from 'mdast-util-gfm-table';
+import { gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown, } from 'mdast-util-gfm-task-list-item';
+import { gfmAutolinkLiteral } from 'micromark-extension-gfm-autolink-literal';
+import { gfmFootnote } from 'micromark-extension-gfm-footnote';
+import { gfmStrikethrough } from 'micromark-extension-gfm-strikethrough';
+import { gfmTable } from 'micromark-extension-gfm-table';
+import { gfmTaskListItem } from 'micromark-extension-gfm-task-list-item';
+import { visit } from 'unist-util-visit';
+import { alertMarkerToMarkdown, markAlertMarkers, } from './extensions/alert-marker.js';
 import { wikiLinkSyntax, wikiLinkFromMarkdown, wikiLinkToMarkdown, } from './extensions/wiki-link/index.js';
 const processor = unified()
     .use(remarkParse)
     .use(remarkFrontmatter)
+    .use(remarkMath)
     .use(remarkStringify)
-    .data('micromarkExtensions', [wikiLinkSyntax()])
-    .data('fromMarkdownExtensions', [wikiLinkFromMarkdown()])
-    .data('toMarkdownExtensions', [wikiLinkToMarkdown()]);
+    .data('micromarkExtensions', [
+    gfmAutolinkLiteral(),
+    gfmFootnote(),
+    gfmStrikethrough(),
+    gfmTable(),
+    gfmTaskListItem(),
+    wikiLinkSyntax(),
+])
+    .data('fromMarkdownExtensions', [
+    gfmAutolinkLiteralFromMarkdown(),
+    gfmFootnoteFromMarkdown(),
+    gfmStrikethroughFromMarkdown(),
+    gfmTableFromMarkdown(),
+    gfmTaskListItemFromMarkdown(),
+    wikiLinkFromMarkdown(),
+])
+    .data('toMarkdownExtensions', [
+    alertMarkerToMarkdown(),
+    gfmFootnoteToMarkdown(),
+    gfmStrikethroughToMarkdown(),
+    gfmTableToMarkdown(),
+    gfmTaskListItemToMarkdown(),
+    wikiLinkToMarkdown(),
+]);
+const BARE_AUTOLINK_DATA_KEY = 'latBareAutolink';
+function bareAutolinkText(node) {
+    if (node.children.length !== 1 || node.children[0].type !== 'text') {
+        return null;
+    }
+    const text = node.children[0].value;
+    if (node.url !== text &&
+        node.url !== `http://${text}` &&
+        node.url !== `mailto:${text}`) {
+        return null;
+    }
+    return text;
+}
 export function parse(markdown) {
-    return processor.parse(markdown);
+    const tree = processor.parse(markdown);
+    markAlertMarkers(tree);
+    visit(tree, 'link', (node) => {
+        const text = bareAutolinkText(node);
+        const sourceLength = node.position?.end.offset !== undefined &&
+            node.position.start.offset !== undefined
+            ? node.position.end.offset - node.position.start.offset
+            : null;
+        if (text === null || sourceLength !== text.length)
+            return;
+        node.data = {
+            ...node.data,
+            [BARE_AUTOLINK_DATA_KEY]: true,
+        };
+    });
+    return tree;
 }
 export function toMarkdown(tree) {
-    return processor.stringify(tree);
+    const serializable = structuredClone(tree);
+    visit(serializable, 'link', (node, index, parent) => {
+        if (index === undefined ||
+            !parent ||
+            node.data?.[BARE_AUTOLINK_DATA_KEY] !== true) {
+            return;
+        }
+        const text = bareAutolinkText(node);
+        if (text === null)
+            return;
+        parent.children[index] = { type: 'text', value: text };
+    });
+    return processor.stringify(serializable);
 }

package/dist/src/path.d.ts

@@ -0,0 +1,2 @@
+/** Normalize path separators for stable project-relative identities. */
+export declare function toPosix(path: string): string;

package/dist/src/path.js

@@ -0,0 +1,4 @@
+/** Normalize path separators for stable project-relative identities. */
+export function toPosix(path) {
+    return path.replace(/\\/g, '/');
+}

package/dist/src/profiler.d.ts

@@ -0,0 +1,16 @@
+export type Profiler = {
+    time<T>(label: string, work: () => Promise<T>, detail?: string): Promise<T>;
+    timeSync<T>(label: string, work: () => T, detail?: string): T;
+    record(label: string, durationMs: number, detail?: string): void;
+};
+export declare class TimingProfiler implements Profiler {
+    private readonly root;
+    private readonly activeNode;
+    private node;
+    time<T>(label: string, work: () => Promise<T>, detail?: string): Promise<T>;
+    timeSync<T>(label: string, work: () => T, detail?: string): T;
+    record(label: string, durationMs: number, detail?: string): void;
+    private recordNode;
+    format(totalMs: number): string[];
+    private formatNode;
+}

package/dist/src/profiler.js

@@ -0,0 +1,81 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { performance } from 'node:perf_hooks';
+export class TimingProfiler {
+    root = {
+        label: '',
+        calls: 0,
+        totalMs: 0,
+        maxMs: 0,
+        children: new Map(),
+    };
+    activeNode = new AsyncLocalStorage();
+    node(label) {
+        const parent = this.activeNode.getStore() ?? this.root;
+        let node = parent.children.get(label);
+        if (!node) {
+            node = {
+                label,
+                calls: 0,
+                totalMs: 0,
+                maxMs: 0,
+                children: new Map(),
+            };
+            parent.children.set(label, node);
+        }
+        return node;
+    }
+    async time(label, work, detail) {
+        const node = this.node(label);
+        const start = performance.now();
+        try {
+            return await this.activeNode.run(node, work);
+        }
+        finally {
+            this.recordNode(node, performance.now() - start, detail);
+        }
+    }
+    timeSync(label, work, detail) {
+        const node = this.node(label);
+        const start = performance.now();
+        try {
+            return this.activeNode.run(node, work);
+        }
+        finally {
+            this.recordNode(node, performance.now() - start, detail);
+        }
+    }
+    record(label, durationMs, detail) {
+        this.recordNode(this.node(label), durationMs, detail);
+    }
+    recordNode(node, durationMs, detail) {
+        node.calls++;
+        node.totalMs += durationMs;
+        if (durationMs > node.maxMs) {
+            node.maxMs = durationMs;
+            node.maxDetail = detail;
+        }
+    }
+    format(totalMs) {
+        const lines = [`Profile (${totalMs.toFixed(1)}ms total):`];
+        for (const node of this.root.children.values()) {
+            this.formatNode(node, 1, lines);
+        }
+        return lines;
+    }
+    formatNode(node, depth, lines) {
+        const indent = '  '.repeat(depth);
+        let summary = `${indent}${node.label}: ${node.totalMs.toFixed(1)}ms`;
+        if (node.calls > 1) {
+            summary +=
+                ` total across ${node.calls} calls` +
+                    ` (${(node.totalMs / node.calls).toFixed(1)}ms avg,` +
+                    ` ${node.maxMs.toFixed(1)}ms max` +
+                    (node.maxDetail ? `: ${node.maxDetail}` : '') +
+                    ')';
+        }
+        lines.push(summary);
+        for (const child of node.children.values()) {
+            this.formatNode(child, depth + 1, lines);
+        }
+    }
+}

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

@@ -0,0 +1,59 @@
+import { type Ref, type Section, type SectionSlugIndex } from './lattice-model.js';
+import type { MarkdownFileAnalysis } from './markdown-analysis.js';
+import { type ScanResult } from './code-refs.js';
+import { type ResolveSourceSymbolOptions } from './source-parser.js';
+import { type ExternalResolver } from './external-sources.js';
+import type { ParserImportObserver } from './parser-import.js';
+export type MarkdownAnalysisExecutor = 'inline' | 'workers' | 'auto';
+export type MarkdownProjectAnalysis = {
+    latDir: string;
+    projectRoot: string;
+    entries: string[];
+    markdownFiles: string[];
+    files: ReadonlyMap<string, MarkdownFileAnalysis>;
+    filesByAbsolutePath: ReadonlyMap<string, MarkdownFileAnalysis>;
+    allSections: Section[];
+    sections: Section[];
+    sectionById: ReadonlyMap<string, Section>;
+    sectionIds: ReadonlySet<string>;
+    fileIndex: Map<string, string[]>;
+    slugIndex: SectionSlugIndex;
+    wikiRefs: readonly Ref[];
+    outgoingRefsBySection: ReadonlyMap<string, readonly Ref[]>;
+    refsByTarget: ReadonlyMap<string, readonly Ref[]>;
+    incomingRefsBySection: ReadonlyMap<string, readonly Ref[]>;
+};
+export type AnalyzeMarkdownProjectOptions = {
+    executor?: MarkdownAnalysisExecutor;
+    maxWorkers?: number;
+    cache?: boolean;
+    onFileAnalyzed?: (analysis: MarkdownFileAnalysis) => void;
+    onParserImport?: ParserImportObserver;
+};
+/** Read and analyze every Markdown file into one immutable command snapshot. */
+export declare function analyzeMarkdownProject(latDir: string, projectRoot: string, options?: AnalyzeMarkdownProjectOptions): Promise<MarkdownProjectAnalysis>;
+/** Lazy request-scoped owner for one immutable project analysis. */
+export declare class MarkdownProjectSession {
+    readonly latDir: string;
+    readonly projectRoot: string;
+    readonly options: AnalyzeMarkdownProjectOptions;
+    private analysisPromise?;
+    private codeRefsPromise?;
+    private externalPromise?;
+    private readonly sourceParserRuntime;
+    constructor(latDir: string, projectRoot: string, options?: AnalyzeMarkdownProjectOptions);
+    analysis(): Promise<MarkdownProjectAnalysis>;
+    codeRefs(): Promise<ScanResult>;
+    external(): Promise<ExternalResolver>;
+    sourceSymbolOptions(): ResolveSourceSymbolOptions;
+}
+type AnalysisContext = {
+    latDir: string;
+    projectRoot: string;
+    analysis?: MarkdownProjectSession;
+};
+/** Reuse one lazy project snapshot throughout a CLI or MCP request. */
+export declare function commandProjectAnalysis(context: AnalysisContext): Promise<MarkdownProjectAnalysis>;
+/** Obtain the complete lazy request session for nested semantic operations. */
+export declare function commandProjectSession(context: AnalysisContext): MarkdownProjectSession;
+export {};

package/dist/src/project-analysis.js

@@ -0,0 +1,233 @@
+import { availableParallelism } from 'node:os';
+import { join } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { buildFileIndex, buildSectionSlugIndex, flattenSections, resolveRef, } from './lattice-model.js';
+import { prepareMarkdownAnalysis, publishMarkdownAnalysis, } from './markdown-analysis-cache.js';
+import { walkEntries } from './walk.js';
+import { scanCodeRefs } from './code-refs.js';
+import { SourceParserRuntime, } from './source-parser.js';
+import { createExternalResolver, } from './external-sources.js';
+import { loadMarkdownAnalyzer } from './markdown-analyzer-loader.js';
+async function analyzeInline(files, latDir, projectRoot, onParserImport) {
+    if (files.length === 0)
+        return [];
+    const analyzeMarkdownFile = await loadMarkdownAnalyzer(onParserImport, 'main thread');
+    return Promise.all(files.map((file) => publishMarkdownAnalysis(file, analyzeMarkdownFile(file.absolutePath, file.content, latDir, projectRoot))));
+}
+function runWorkerTask(worker, task) {
+    return new Promise((resolve, reject) => {
+        const onMessage = (response) => {
+            cleanup();
+            if ('error' in response) {
+                reject(new Error(`Failed to analyze ${task.absolutePath}: ${response.error}`));
+            }
+            else {
+                resolve(response);
+            }
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onExit = (code) => {
+            cleanup();
+            reject(new Error(`Markdown analysis worker exited with code ${code} while reading ${task.absolutePath}`));
+        };
+        const cleanup = () => {
+            worker.off('message', onMessage);
+            worker.off('error', onError);
+            worker.off('exit', onExit);
+        };
+        worker.once('message', onMessage);
+        worker.once('error', onError);
+        worker.once('exit', onExit);
+        worker.postMessage(task);
+    });
+}
+async function analyzeWithWorkers(files, latDir, projectRoot, maxWorkers, onParserImport) {
+    const workerCount = Math.max(1, Math.min(files.length, maxWorkers ?? 10, Math.max(1, availableParallelism() - 1)));
+    const workers = Array.from({ length: workerCount }, () => {
+        const sourceRuntime = import.meta.url.endsWith('.ts');
+        return new Worker(new URL(sourceRuntime
+            ? './markdown-analysis-worker.ts'
+            : './markdown-analysis-worker.js', import.meta.url), {
+            execArgv: sourceRuntime
+                ? ['--import', 'tsx']
+                : process.execArgv.filter((argument) => !argument.startsWith('--input-type')),
+        });
+    });
+    const analyses = new Array(files.length);
+    let next = 0;
+    try {
+        await Promise.all(workers.map(async (worker, workerIndex) => {
+            while (true) {
+                const id = next++;
+                if (id >= files.length)
+                    return;
+                const file = files[id];
+                const response = await runWorkerTask(worker, {
+                    id,
+                    absolutePath: file.absolutePath,
+                    content: file.content,
+                    latDir,
+                    projectRoot,
+                });
+                analyses[id] = response.analysis;
+                if (response.importMs !== undefined) {
+                    onParserImport?.({
+                        parser: 'Markdown analyzer',
+                        imported: true,
+                        durationMs: response.importMs,
+                        detail: `worker ${workerIndex + 1}`,
+                    });
+                }
+            }
+        }));
+        return Promise.all(analyses.map((analysis, index) => publishMarkdownAnalysis(files[index], analysis)));
+    }
+    finally {
+        await Promise.all(workers.map((worker) => worker.terminate()));
+    }
+}
+/** Read and analyze every Markdown file into one immutable command snapshot. */
+export async function analyzeMarkdownProject(latDir, projectRoot, options = {}) {
+    const entries = await walkEntries(latDir);
+    const markdownFiles = entries
+        .filter((entry) => entry.endsWith('.md'))
+        .sort()
+        .map((entry) => join(latDir, entry));
+    const prepared = await Promise.all(markdownFiles.map((absolutePath) => prepareMarkdownAnalysis(absolutePath, latDir, projectRoot, options.cache !== false)));
+    const analyses = new Array(markdownFiles.length);
+    const misses = [];
+    const missIndexes = [];
+    for (const [index, file] of prepared.entries()) {
+        if (file.analysis)
+            analyses[index] = file.analysis;
+        else {
+            misses.push(file);
+            missIndexes.push(index);
+        }
+    }
+    if (misses.length === 0) {
+        options.onParserImport?.({
+            parser: 'Markdown analyzer',
+            imported: false,
+            durationMs: 0,
+            detail: prepared.length === 0
+                ? 'no Markdown files'
+                : `all ${prepared.length} Markdown files cached`,
+        });
+    }
+    const executor = options.executor === 'auto' || options.executor === undefined
+        ? misses.length >= 8
+            ? 'workers'
+            : 'inline'
+        : options.executor;
+    const parsed = executor === 'workers' && misses.length > 1
+        ? await analyzeWithWorkers(misses, latDir, projectRoot, options.maxWorkers, options.onParserImport)
+        : await analyzeInline(misses, latDir, projectRoot, options.onParserImport);
+    for (const [index, analysis] of parsed.entries()) {
+        analyses[missIndexes[index]] = analysis;
+    }
+    const files = new Map();
+    const filesByAbsolutePath = new Map();
+    for (const analysis of analyses) {
+        files.set(analysis.path, analysis);
+        filesByAbsolutePath.set(analysis.absolutePath, analysis);
+        options.onFileAnalyzed?.(analysis);
+    }
+    const allSections = analyses.flatMap((analysis) => analysis.sections);
+    const sections = flattenSections(allSections);
+    const sectionById = new Map(sections.map((section) => [section.id.toLowerCase(), section]));
+    const sectionIds = new Set(sectionById.keys());
+    const fileIndex = buildFileIndex(allSections);
+    const slugIndex = buildSectionSlugIndex(allSections);
+    const wikiRefs = analyses.flatMap((analysis) => analysis.wikiRefs);
+    const outgoingRefsBySection = new Map();
+    const refsByTarget = new Map();
+    const incomingRefsBySection = new Map();
+    const append = (index, key, ref) => {
+        const refs = index.get(key);
+        if (refs)
+            refs.push(ref);
+        else
+            index.set(key, [ref]);
+    };
+    for (const ref of wikiRefs) {
+        const from = ref.fromSection.toLowerCase();
+        const target = ref.target.toLowerCase();
+        append(outgoingRefsBySection, from, ref);
+        append(refsByTarget, target, ref);
+        const resolved = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+        if (!resolved.ambiguous) {
+            const resolvedId = resolved.resolved.toLowerCase();
+            if (sectionIds.has(resolvedId)) {
+                append(incomingRefsBySection, resolvedId, ref);
+            }
+        }
+    }
+    return {
+        latDir,
+        projectRoot,
+        entries,
+        markdownFiles,
+        files,
+        filesByAbsolutePath,
+        allSections,
+        sections,
+        sectionById,
+        sectionIds,
+        fileIndex,
+        slugIndex,
+        wikiRefs,
+        outgoingRefsBySection,
+        refsByTarget,
+        incomingRefsBySection,
+    };
+}
+/** Lazy request-scoped owner for one immutable project analysis. */
+export class MarkdownProjectSession {
+    latDir;
+    projectRoot;
+    options;
+    analysisPromise;
+    codeRefsPromise;
+    externalPromise;
+    sourceParserRuntime = new SourceParserRuntime();
+    constructor(latDir, projectRoot, options = {}) {
+        this.latDir = latDir;
+        this.projectRoot = projectRoot;
+        this.options = options;
+    }
+    analysis() {
+        this.analysisPromise ??= analyzeMarkdownProject(this.latDir, this.projectRoot, this.options);
+        return this.analysisPromise;
+    }
+    codeRefs() {
+        this.codeRefsPromise ??= scanCodeRefs(this.projectRoot);
+        return this.codeRefsPromise;
+    }
+    external() {
+        this.externalPromise ??= (async () => {
+            const resolver = await createExternalResolver(this.latDir, this.projectRoot);
+            await resolver.reconcile();
+            return resolver;
+        })();
+        return this.externalPromise;
+    }
+    sourceSymbolOptions() {
+        return {
+            latDir: this.latDir,
+            runtime: this.sourceParserRuntime,
+        };
+    }
+}
+/** Reuse one lazy project snapshot throughout a CLI or MCP request. */
+export function commandProjectAnalysis(context) {
+    return commandProjectSession(context).analysis();
+}
+/** Obtain the complete lazy request session for nested semantic operations. */
+export function commandProjectSession(context) {
+    context.analysis ??= new MarkdownProjectSession(context.latDir, context.projectRoot);
+    return context.analysis;
+}

package/dist/src/project-discovery.d.ts

@@ -0,0 +1,6 @@
+/** Find the nearest ancestor containing the project's lat.md directory. */
+export declare function findLatticeDir(from?: string): string | null;
+/** Find the root of the nearest project containing a lat.md directory. */
+export declare function findProjectRoot(from?: string): string | null;
+/** List project Markdown files without loading the Markdown parser. */
+export declare function listLatticeFiles(latticeDir: string): Promise<string[]>;

package/dist/src/project-discovery.js

@@ -0,0 +1,30 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Find the nearest ancestor containing the project's lat.md directory. */
+export function findLatticeDir(from) {
+    let dir = resolve(from ?? process.cwd());
+    while (true) {
+        const candidate = join(dir, 'lat.md');
+        if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Find the root of the nearest project containing a lat.md directory. */
+export function findProjectRoot(from) {
+    const latDir = findLatticeDir(from);
+    return latDir ? dirname(latDir) : null;
+}
+/** List project Markdown files without loading the Markdown parser. */
+export async function listLatticeFiles(latticeDir) {
+    const { walkEntries } = await import('./walk.js');
+    const entries = await walkEntries(latticeDir);
+    return entries
+        .filter((entry) => entry.endsWith('.md'))
+        .sort()
+        .map((entry) => join(latticeDir, entry));
+}

package/dist/src/repository-path.d.ts

@@ -0,0 +1,11 @@
+export type RepositoryPathKind = 'directory' | 'file' | 'other';
+export type RepositoryPathInspection = {
+    kind: RepositoryPathKind;
+    realPath: string;
+} | {
+    kind: 'missing' | 'outside';
+};
+/** Normalize a portable project-root-relative path without allowing escapes. */
+export declare function normalizeRepositoryPath(authoredPath: string): string | null;
+/** Inspect an existing path after resolving symlinks beneath the project root. */
+export declare function inspectRepositoryPath(projectRoot: string, path: string): Promise<RepositoryPathInspection>;

package/dist/src/repository-path.js

@@ -0,0 +1,52 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, posix, relative, resolve, sep } from 'node:path';
+import { toPosix } from './path.js';
+/** Normalize a portable project-root-relative path without allowing escapes. */
+export function normalizeRepositoryPath(authoredPath) {
+    if (!authoredPath || authoredPath.includes('\0'))
+        return null;
+    const portable = toPosix(authoredPath);
+    if (posix.isAbsolute(portable) || /^[a-z]:\//i.test(portable))
+        return null;
+    const normalized = posix.normalize(portable).replace(/^\.\//, '');
+    if (normalized === '..' ||
+        normalized.startsWith('../') ||
+        normalized.includes('\0')) {
+        return null;
+    }
+    return normalized;
+}
+function isInside(root, candidate) {
+    const path = relative(root, candidate);
+    return (path === '' ||
+        (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`)));
+}
+/** Inspect an existing path after resolving symlinks beneath the project root. */
+export async function inspectRepositoryPath(projectRoot, path) {
+    const candidate = resolve(projectRoot, ...path.split('/'));
+    let realRoot;
+    let realPath;
+    try {
+        [realRoot, realPath] = await Promise.all([
+            realpath(projectRoot),
+            realpath(candidate),
+        ]);
+    }
+    catch {
+        return { kind: 'missing' };
+    }
+    if (!isInside(realRoot, realPath))
+        return { kind: 'outside' };
+    try {
+        const info = await stat(realPath);
+        const kind = info.isFile()
+            ? 'file'
+            : info.isDirectory()
+                ? 'directory'
+                : 'other';
+        return { kind, realPath };
+    }
+    catch {
+        return { kind: 'missing' };
+    }
+}