@plebeiantech/lat.md 0.12.3-fork.17 → 0.12.3-fork.20

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

@@ -1,59 +0,0 @@
-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

@@ -1,233 +0,0 @@
-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

@@ -1,6 +0,0 @@
-/** 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

@@ -1,30 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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' };
-    }
-}

package/dist/src/source-formats.d.ts

@@ -1,7 +0,0 @@
-/** Source file extensions supported by Lat's parser and code-reference scan. */
-export declare const SOURCE_FILE_EXTENSIONS: readonly [".c", ".dart", ".erb", ".go", ".h", ".java", ".js", ".jsx", ".php", ".py", ".rake", ".rb", ".rs", ".ts", ".tsx"];
-/** A source extension supported everywhere Lat accepts source files. */
-export type SourceFileExtension = (typeof SOURCE_FILE_EXTENSIONS)[number];
-export declare function isSourceFileExtension(extension: string): extension is SourceFileExtension;
-export declare function sourceFileExtension(path: string): SourceFileExtension | null;
-export declare function isSourceFilePath(path: string): boolean;

package/dist/src/source-formats.js

@@ -1,30 +0,0 @@
-import { extname } from 'node:path';
-/** Source file extensions supported by Lat's parser and code-reference scan. */
-export const SOURCE_FILE_EXTENSIONS = [
-    '.c',
-    '.dart',
-    '.erb',
-    '.go',
-    '.h',
-    '.java',
-    '.js',
-    '.jsx',
-    '.php',
-    '.py',
-    '.rake',
-    '.rb',
-    '.rs',
-    '.ts',
-    '.tsx',
-];
-const sourceFileExtensionSet = new Set(SOURCE_FILE_EXTENSIONS);
-export function isSourceFileExtension(extension) {
-    return sourceFileExtensionSet.has(extension);
-}
-export function sourceFileExtension(path) {
-    const extension = extname(path);
-    return isSourceFileExtension(extension) ? extension : null;
-}
-export function isSourceFilePath(path) {
-    return sourceFileExtension(path) !== null;
-}

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

@@ -1,67 +0,0 @@
-import type { Section } from './lattice-model.js';
-export type SourceSymbol = {
-    name: string;
-    kind: 'function' | 'class' | 'const' | 'type' | 'interface' | 'method' | 'variable';
-    parent?: string;
-    startLine: number;
-    endLine: number;
-    signature: string;
-};
-export type SourceAnalysisCacheStatus = 'disabled' | 'hit' | 'miss';
-export type SourceAnalysisTimings = {
-    readMs: number;
-    hashMs: number;
-    cacheReadMs: number;
-    cacheWriteMs: number;
-    parseMs: number;
-    cacheStatus: SourceAnalysisCacheStatus;
-};
-export type SourceFileAnalysis = {
-    path: string;
-    symbols: SourceSymbol[];
-    timings: SourceAnalysisTimings;
-};
-export type AnalyzeSourceSymbolsOptions = {
-    identity?: string;
-    cache?: boolean;
-    readMs?: number;
-    runtime?: SourceParserRuntime;
-};
-export type ResolveSourceSymbolOptions = {
-    latDir?: string;
-    cache?: boolean;
-    onFileAnalyzed?: (analysis: SourceFileAnalysis) => void;
-    runtime?: SourceParserRuntime;
-};
-export declare function parseSourceSymbols(filePath: string, content: string): Promise<SourceSymbol[]>;
-type ResolvedSourceCacheEntry = {
-    symbols: SourceSymbol[];
-    analysis?: SourceFileAnalysis;
-    error?: string;
-};
-/** Request-scoped owner for in-flight and completed source parser work. */
-export declare class SourceParserRuntime {
-    readonly analyses: Map<string, Promise<SourceFileAnalysis>>;
-    readonly symbols: Map<string, Promise<ResolvedSourceCacheEntry>>;
-    clear(): void;
-}
-/** Return the parser cache path for one project source file. */
-export declare function sourceAnalysisCachePath(latDir: string, projectRoot: string, absolutePath: string): string;
-/** Analyze source content through the shared versioned persistent cache. */
-export declare function analyzeSourceSymbols(filePath: string, content: string, latDir: string, options?: AnalyzeSourceSymbolsOptions): Promise<SourceFileAnalysis>;
-/** Clear the symbol cache. Call between top-level operations. */
-export declare function clearSymbolCache(): void;
-/**
- * Check whether a source file path (relative to projectRoot) has a given symbol.
- * Used by lat check to validate source code wiki links lazily.
- */
-export declare function resolveSourceSymbol(filePath: string, symbolPath: string, projectRoot: string, options?: ResolveSourceSymbolOptions): Promise<{
-    found: boolean;
-    symbols: SourceSymbol[];
-    error?: string;
-}>;
-/**
- * Convert source symbols to Section objects for uniform handling.
- */
-export declare function sourceSymbolsToSections(symbols: SourceSymbol[], filePath: string): Section[];
-export {};