@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/view/references.js

@@ -0,0 +1,345 @@
+import { relative, resolve } from 'node:path';
+import { visit } from 'unist-util-visit';
+import { buildFileIndex, buildSectionSlugIndex, extractRefs, extractLinks, flattenSections, parseSections, resolveRef, } from '../lattice.js';
+import { parse } from '../parser.js';
+import { toPosix } from '../walk.js';
+import { renderMarkdown } from './markdown.js';
+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 paragraphs(content, tree) {
+    const byLine = new Map();
+    visit(tree, 'paragraph', (node) => {
+        const start = node.position?.start.line;
+        const end = node.position?.end.line;
+        if (!start || !end)
+            return;
+        const text = inlineText(node).replace(/\s+/g, ' ').trim();
+        const startOffset = node.position?.start.offset;
+        const endOffset = node.position?.end.offset;
+        const paragraph = {
+            markdown: startOffset === undefined || endOffset === undefined
+                ? text
+                : content.slice(startOffset, endOffset),
+            startLine: start,
+            text,
+        };
+        for (let line = start; line <= end; line++)
+            byLine.set(line, paragraph);
+    });
+    return byLine;
+}
+function markdownLinks(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) {
+            links.push({
+                kind: node.type === 'image' || node.type === 'imageReference'
+                    ? 'image'
+                    : 'link',
+                line,
+                url,
+            });
+        }
+    });
+    return links;
+}
+/** Parse one Markdown file once into every structure needed by the view store. */
+export function parseViewMarkdownFile(absolutePath, content, latDir, projectRoot) {
+    const tree = parse(content);
+    return {
+        absolutePath,
+        content,
+        path: toPosix(relative(latDir, absolutePath)),
+        projectPath: toPosix(relative(projectRoot, absolutePath)),
+        tree,
+        sections: parseSections(absolutePath, content, projectRoot, tree),
+        wikiRefs: extractRefs(absolutePath, content, projectRoot, tree),
+        paragraphs: paragraphs(content, tree),
+        markdownLinks: markdownLinks(tree),
+        validationLinks: extractLinks(content, tree),
+    };
+}
+function contextMarkdownLink(requestedPath, url) {
+    if (url.startsWith('/') ||
+        url.startsWith('//') ||
+        /^[a-z][a-z\d+.-]*:/i.test(url)) {
+        return url;
+    }
+    const encodedPath = requestedPath
+        .split('/')
+        .map(encodeURIComponent)
+        .join('/');
+    const resolved = new URL(url, `http://lat.local/docs/${encodedPath}`);
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+function documentUrl(latDir, projectRoot, section) {
+    const path = toPosix(relative(latDir, resolve(projectRoot, section.filePath)));
+    const encoded = path.split('/').map(encodeURIComponent).join('/');
+    const fragment = section.githubSlug
+        ? `#${encodeURIComponent(section.githubSlug)}`
+        : '';
+    return `/docs/${encoded}${fragment}`;
+}
+function breadcrumbs(latDir, projectRoot, section) {
+    const path = toPosix(relative(latDir, resolve(projectRoot, section.filePath))).replace(/\.md$/i, '');
+    return [...path.split('/'), ...section.id.split('#').slice(1)];
+}
+function sourceLineUrl(path, line) {
+    const encoded = path.split('/').map(encodeURIComponent).join('/');
+    return `/code/${encoded}?at=${line}`;
+}
+function linkedSection(url, sourcePath, sectionsByPath) {
+    if (url.startsWith('//') || /^[a-z][a-z\d+.-]*:/i.test(url))
+        return null;
+    const encodedSourcePath = sourcePath
+        .split('/')
+        .map(encodeURIComponent)
+        .join('/');
+    let destination;
+    try {
+        destination = new URL(url, `http://lat.local/docs/${encodedSourcePath}`);
+    }
+    catch {
+        return null;
+    }
+    if (destination.origin !== 'http://lat.local' ||
+        !destination.pathname.startsWith('/docs/')) {
+        return null;
+    }
+    let path;
+    let fragment;
+    try {
+        path = destination.pathname
+            .slice('/docs/'.length)
+            .split('/')
+            .map(decodeURIComponent)
+            .join('/');
+        fragment = decodeURIComponent(destination.hash.slice(1));
+    }
+    catch {
+        return null;
+    }
+    const sections = sectionsByPath.get(path.toLowerCase());
+    if (!sections)
+        return null;
+    if (!fragment)
+        return sections[0] ?? null;
+    return (sections.find((section) => section.githubSlug?.toLowerCase() === fragment.toLowerCase()) ?? null);
+}
+function paragraphFor(file, section, line) {
+    return (file.paragraphs.get(line) ?? {
+        markdown: section.firstParagraph,
+        startLine: line,
+        text: section.firstParagraph,
+    });
+}
+/** Resolve cached outgoing occurrences into direct section and source indexes. */
+export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
+    const files = [...markdownFiles].sort((a, b) => a.path.localeCompare(b.path));
+    const sections = flattenSections(allSections);
+    const sectionIds = new Set(sections.map((section) => section.id.toLowerCase()));
+    const fileIndex = buildFileIndex(allSections);
+    const slugIndex = buildSectionSlugIndex(allSections);
+    const sectionById = new Map(sections.map((section) => [section.id.toLowerCase(), section]));
+    const sectionsByPath = new Map();
+    for (const file of files) {
+        sectionsByPath.set(file.path.toLowerCase(), flattenSections(file.sections));
+    }
+    const incoming = new Map();
+    const sourceByTarget = new Map();
+    const addIncoming = (targetId, key, reference) => {
+        const target = targetId.toLowerCase();
+        let references = incoming.get(target);
+        if (!references) {
+            references = new Map();
+            incoming.set(target, references);
+        }
+        if (!references.has(key))
+            references.set(key, reference);
+    };
+    for (const file of files) {
+        const fileSections = flattenSections(file.sections).sort((a, b) => a.startLine - b.startLine);
+        for (const ref of file.wikiRefs) {
+            const section = sectionById.get(ref.fromSection.toLowerCase());
+            if (!section)
+                continue;
+            const reference = {
+                kind: 'markdown',
+                section,
+                sourcePath: file.path,
+                line: ref.line,
+                paragraph: paragraphFor(file, section, ref.line),
+                activeWikiLink: ref.target,
+            };
+            const sourceKey = ref.target.toLowerCase();
+            const sourceReferences = sourceByTarget.get(sourceKey) ?? [];
+            sourceReferences.push(reference);
+            sourceByTarget.set(sourceKey, sourceReferences);
+            const resolved = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+            if (resolved.ambiguous ||
+                !sectionById.has(resolved.resolved.toLowerCase())) {
+                continue;
+            }
+            addIncoming(resolved.resolved, `markdown:${section.filePath}:${reference.paragraph.startLine}`, reference);
+        }
+        for (const link of file.markdownLinks) {
+            if (link.kind !== 'link')
+                continue;
+            const targetSection = linkedSection(link.url, file.path, sectionsByPath);
+            if (!targetSection)
+                continue;
+            const section = fileSections
+                .filter((candidate) => candidate.startLine <= link.line)
+                .at(-1);
+            if (!section)
+                continue;
+            const reference = {
+                kind: 'markdown',
+                section,
+                sourcePath: file.path,
+                line: link.line,
+                paragraph: paragraphFor(file, section, link.line),
+                activeMarkdownLink: link.url,
+            };
+            addIncoming(targetSection.id, `markdown:${section.filePath}:${reference.paragraph.startLine}`, reference);
+        }
+    }
+    for (const file of [...codeFiles].sort((a, b) => a.path.localeCompare(b.path))) {
+        for (const ref of [...file.refs].sort((a, b) => a.line - b.line)) {
+            const resolved = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
+            if (resolved.ambiguous ||
+                !sectionById.has(resolved.resolved.toLowerCase())) {
+                continue;
+            }
+            addIncoming(resolved.resolved, `code:${ref.file}:${ref.line}`, {
+                kind: 'code',
+                path: ref.file,
+                line: ref.line,
+                snippet: file.lines[ref.line - 1]?.trim() ?? '',
+                url: sourceLineUrl(ref.file, ref.line),
+            });
+        }
+    }
+    return {
+        incomingBySection: new Map([...incoming].map(([target, references]) => [
+            target,
+            [...references.values()],
+        ])),
+        sourceByTarget,
+    };
+}
+async function renderIndexedMarkdownReference(reference, latDir, projectRoot, resolveWikiLink) {
+    const paragraphHtml = (await renderMarkdown(reference.paragraph.markdown, reference.sourcePath, resolveWikiLink, {
+        activeWikiLink: reference.activeWikiLink,
+        activeMarkdownLink: reference.activeMarkdownLink,
+        lineOffset: reference.paragraph.startLine - 1,
+        rewriteMarkdownLink: (url) => contextMarkdownLink(reference.sourcePath, url),
+    })).html;
+    return {
+        kind: 'markdown',
+        sectionId: reference.section.id,
+        breadcrumbs: breadcrumbs(latDir, projectRoot, reference.section),
+        paragraph: reference.paragraph.text,
+        paragraphHtml,
+        url: documentUrl(latDir, projectRoot, reference.section),
+    };
+}
+/** Render direct reverse-index entries for the sections visible in one file. */
+export async function renderSectionBackReferences(index, visibleSections, latDir, projectRoot, createWikiLinkResolver) {
+    const resolverByPath = new Map();
+    const resolverFor = (path) => {
+        let resolver = resolverByPath.get(path);
+        if (!resolver) {
+            resolver = createWikiLinkResolver
+                ? createWikiLinkResolver(path)
+                : Promise.resolve(async () => null);
+            resolverByPath.set(path, resolver);
+        }
+        return resolver;
+    };
+    const result = [];
+    for (const section of flattenSections(visibleSections)) {
+        const indexed = index.incomingBySection.get(section.id.toLowerCase()) ?? [];
+        if (indexed.length === 0)
+            continue;
+        const references = [];
+        for (const reference of indexed) {
+            references.push(reference.kind === 'code'
+                ? reference
+                : await renderIndexedMarkdownReference(reference, latDir, projectRoot, await resolverFor(reference.sourcePath)));
+        }
+        result.push({
+            sectionId: section.id,
+            headingId: section.githubSlug ?? '',
+            references,
+        });
+    }
+    return result;
+}
+/** Render cached Markdown occurrences that point to one source target. */
+export async function renderSourceReferenceContext(index, target, origin, latDir, projectRoot, createWikiLinkResolver) {
+    const indexed = index.sourceByTarget.get(target.toLowerCase()) ?? [];
+    const resolverByPath = new Map();
+    const located = [];
+    for (const reference of indexed) {
+        let resolver = resolverByPath.get(reference.sourcePath);
+        if (!resolver) {
+            resolver = createWikiLinkResolver
+                ? createWikiLinkResolver(reference.sourcePath)
+                : Promise.resolve(async () => null);
+            resolverByPath.set(reference.sourcePath, resolver);
+        }
+        const rendered = await renderIndexedMarkdownReference(reference, latDir, projectRoot, await resolver);
+        located.push({
+            line: reference.line,
+            reference: {
+                sectionId: rendered.sectionId,
+                breadcrumbs: rendered.breadcrumbs,
+                paragraph: rendered.paragraph,
+                paragraphHtml: rendered.paragraphHtml,
+                url: rendered.url,
+            },
+        });
+    }
+    const context = origin
+        ? (located.find((candidate) => candidate.line === origin.line &&
+            candidate.reference.sectionId.toLowerCase() ===
+                origin.sectionId.toLowerCase())?.reference ?? null)
+        : null;
+    const otherSections = new Map();
+    for (const candidate of located) {
+        const key = candidate.reference.sectionId.toLowerCase();
+        if (context && key === context.sectionId.toLowerCase())
+            continue;
+        if (!otherSections.has(key))
+            otherSections.set(key, candidate.reference);
+    }
+    return { context, otherReferences: [...otherSections.values()] };
+}

package/dist/src/view/repository.d.ts

@@ -0,0 +1,12 @@
+import { type Section } from '../lattice.js';
+import type { ViewSourceDocument } from './protocol.js';
+import { type SourceReferenceOrigin, type ViewReferenceIndex } from './references.js';
+export declare class ViewDocumentNotFoundError extends Error {
+}
+export declare class ViewSourceNotFoundError extends Error {
+}
+export declare function createMarkdownWikiLinkResolver(latDir: string, requestedPath: string, loadedSections: Section[]): Promise<(target: string, context: {
+    line: number;
+}) => Promise<string | null>>;
+/** Read and highlight a source file after constraining it to the project root. */
+export declare function getViewSource(latDir: string, projectRoot: string, requestedPath: string, requestedSymbol?: string, origin?: SourceReferenceOrigin, requestedLine?: number, allSections?: Section[], referenceIndex?: ViewReferenceIndex): Promise<ViewSourceDocument>;

package/dist/src/view/repository.js

@@ -0,0 +1,167 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, relative, resolve, sep, } from 'node:path';
+import { buildFileIndex, buildSectionSlugIndex, flattenSections, resolveRef, } from '../lattice.js';
+import { resolveSourceSymbol, SOURCE_EXTENSIONS, } from '../source-parser.js';
+import { toPosix } from '../walk.js';
+import { highlightSource } from './highlight.js';
+import { renderSourceReferenceContext, } from './references.js';
+export class ViewDocumentNotFoundError extends Error {
+}
+export class ViewSourceNotFoundError extends Error {
+}
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return (rel === '' ||
+        (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`)));
+}
+function documentUrl(path) {
+    return `/docs/${path.split('/').map(encodeURIComponent).join('/')}`;
+}
+function sourceUrl(path, symbol, origin) {
+    const encodedPath = path.split('/').map(encodeURIComponent).join('/');
+    const query = new URLSearchParams();
+    if (origin) {
+        query.set('from', origin.sectionId);
+        query.set('line', String(origin.line));
+    }
+    const search = query.size > 0 ? `?${query}` : '';
+    const fragment = symbol ? `#${encodeURIComponent(symbol)}` : '';
+    return `/code/${encodedPath}${search}${fragment}`;
+}
+function sourceTarget(target) {
+    const hash = target.indexOf('#');
+    const path = hash === -1 ? target : target.slice(0, hash);
+    if (!SOURCE_EXTENSIONS.has(extname(path)))
+        return null;
+    return { path, symbol: hash === -1 ? '' : target.slice(hash + 1) };
+}
+function matchingSymbol(symbols, symbolPath) {
+    const parts = symbolPath.split('#');
+    if (parts.length === 1) {
+        return symbols.find((symbol) => symbol.name === parts[0] && !symbol.parent);
+    }
+    if (parts.length === 2) {
+        return symbols.find((symbol) => symbol.parent === parts[0] && symbol.name === parts[1]);
+    }
+    return undefined;
+}
+export async function createMarkdownWikiLinkResolver(latDir, requestedPath, loadedSections) {
+    const projectRoot = dirname(latDir);
+    const flat = flattenSections(loadedSections);
+    const sectionIds = new Set(flat.map((section) => section.id.toLowerCase()));
+    const fileIndex = buildFileIndex(loadedSections);
+    const slugIndex = buildSectionSlugIndex(loadedSections);
+    const byId = new Map(flat.map((section) => [section.id.toLowerCase(), section]));
+    const currentFile = toPosix(relative(projectRoot, resolve(latDir, requestedPath)));
+    const currentSections = flat
+        .filter((section) => section.filePath === currentFile)
+        .sort((a, b) => a.startLine - b.startLine);
+    return async (target, context) => {
+        const result = resolveRef(target, sectionIds, fileIndex, slugIndex);
+        if (result.ambiguous)
+            return null;
+        const section = byId.get(result.resolved.toLowerCase());
+        if (section) {
+            const absoluteFile = resolve(projectRoot, section.filePath);
+            const file = toPosix(relative(latDir, absoluteFile));
+            const fragment = target.includes('#') && section.githubSlug
+                ? `#${encodeURIComponent(section.githubSlug)}`
+                : '';
+            return `${documentUrl(file)}${fragment}`;
+        }
+        const source = sourceTarget(target);
+        if (!source)
+            return null;
+        try {
+            await readViewSource(projectRoot, source.path, source.symbol);
+            let section;
+            for (const candidate of currentSections) {
+                if (candidate.startLine > context.line)
+                    break;
+                section = candidate;
+            }
+            const origin = section
+                ? { sectionId: section.id, line: context.line }
+                : undefined;
+            return sourceUrl(source.path, source.symbol, origin);
+        }
+        catch (error) {
+            if (error instanceof ViewSourceNotFoundError)
+                return null;
+            throw error;
+        }
+    };
+}
+async function readViewSource(projectRoot, requestedPath, requestedSymbol = '', requestedLine = 0) {
+    if (!requestedPath ||
+        requestedPath.includes('\\') ||
+        isAbsolute(requestedPath) ||
+        !SOURCE_EXTENSIONS.has(extname(requestedPath))) {
+        throw new ViewSourceNotFoundError('Source document not found');
+    }
+    const candidate = resolve(projectRoot, requestedPath);
+    let realRoot;
+    let realFile;
+    try {
+        [realRoot, realFile] = await Promise.all([
+            realpath(projectRoot),
+            realpath(candidate),
+        ]);
+    }
+    catch {
+        throw new ViewSourceNotFoundError('Source document not found');
+    }
+    if (!isInside(realRoot, realFile)) {
+        throw new ViewSourceNotFoundError('Source document not found');
+    }
+    const content = await readFile(realFile, 'utf-8');
+    if (!requestedSymbol) {
+        if (!requestedLine)
+            return { path: requestedPath, content, focus: null };
+        const line = content.split('\n')[requestedLine - 1];
+        if (line === undefined) {
+            throw new ViewSourceNotFoundError('Source line not found');
+        }
+        return {
+            path: requestedPath,
+            content,
+            focus: {
+                symbol: `line ${requestedLine}`,
+                kind: 'reference',
+                signature: line.trim() || `Line ${requestedLine}`,
+                startLine: requestedLine,
+                endLine: requestedLine,
+            },
+        };
+    }
+    const resolved = await resolveSourceSymbol(requestedPath, requestedSymbol, projectRoot);
+    const symbol = resolved.found
+        ? matchingSymbol(resolved.symbols, requestedSymbol)
+        : undefined;
+    if (!symbol) {
+        throw new ViewSourceNotFoundError('Source symbol not found');
+    }
+    return {
+        path: requestedPath,
+        content,
+        focus: {
+            symbol: requestedSymbol,
+            kind: symbol.kind,
+            signature: symbol.signature,
+            startLine: symbol.startLine,
+            endLine: symbol.endLine,
+        },
+    };
+}
+/** Read and highlight a source file after constraining it to the project root. */
+export async function getViewSource(latDir, projectRoot, requestedPath, requestedSymbol = '', origin, requestedLine = 0, allSections = [], referenceIndex) {
+    const source = await readViewSource(projectRoot, requestedPath, requestedSymbol, requestedLine);
+    const references = referenceIndex
+        ? await renderSourceReferenceContext(referenceIndex, `${source.path}${requestedSymbol ? `#${requestedSymbol}` : ''}`, origin, latDir, projectRoot, (path) => createMarkdownWikiLinkResolver(latDir, path, allSections))
+        : { context: null, otherReferences: [] };
+    return {
+        ...source,
+        highlightedHtmlLines: highlightSource(source.path, source.content),
+        ...references,
+    };
+}

package/dist/src/view/search.d.ts

@@ -0,0 +1,14 @@
+import type { SectionMatch } from '../lattice.js';
+import type { ViewSearchResponse } from './protocol.js';
+export type ViewSearch = (query: string) => Promise<ViewSearchResponse>;
+export type ViewSearchDependencies = {
+    runIndex: (latDir: string) => Promise<void>;
+    runSearch: (latDir: string, query: string, limit: number, options: {
+        buildIndex: false;
+    }) => Promise<{
+        query: string;
+        matches: SectionMatch[];
+    }>;
+};
+/** Create the lazily indexed semantic search service used by `lat ui`. */
+export declare function createViewSearch(latDir: string, dependencies?: ViewSearchDependencies, getGeneration?: () => number): ViewSearch;

package/dist/src/view/search.js

@@ -0,0 +1,64 @@
+import { dirname, relative, resolve } from 'node:path';
+import { toPosix } from '../walk.js';
+const VIEW_SEARCH_LIMIT = 10;
+const defaultDependencies = {
+    async runIndex(latDir) {
+        const { runIndex } = await import('../cli/search.js');
+        await runIndex(latDir);
+    },
+    async runSearch(latDir, query, limit, options) {
+        const { runSearch } = await import('../cli/search.js');
+        return runSearch(latDir, query, limit, undefined, options);
+    },
+};
+function documentUrl(path, headingId) {
+    const encodedPath = path.split('/').map(encodeURIComponent).join('/');
+    const fragment = headingId ? `#${encodeURIComponent(headingId)}` : '';
+    return `/docs/${encodedPath}${fragment}`;
+}
+function viewSearchResult(latDir, match) {
+    const section = match.section;
+    const projectRoot = dirname(latDir);
+    const path = toPosix(relative(latDir, resolve(projectRoot, section.filePath)));
+    const fileBreadcrumbs = path.replace(/\.md$/i, '').split('/');
+    return {
+        sectionId: section.id,
+        title: section.heading,
+        path,
+        breadcrumbs: [...fileBreadcrumbs, ...section.id.split('#').slice(1)],
+        description: section.firstParagraph,
+        url: documentUrl(path, section.githubSlug),
+    };
+}
+/** Create the lazily indexed semantic search service used by `lat ui`. */
+export function createViewSearch(latDir, dependencies = defaultDependencies, getGeneration = () => 0) {
+    let indexReady = null;
+    let indexedGeneration = -1;
+    const prepareIndex = async () => {
+        while (indexedGeneration < getGeneration() || indexedGeneration < 0) {
+            if (!indexReady) {
+                const generation = getGeneration();
+                indexReady = dependencies
+                    .runIndex(latDir)
+                    .then(() => {
+                    indexedGeneration = Math.max(indexedGeneration, generation);
+                })
+                    .finally(() => {
+                    indexReady = null;
+                });
+            }
+            await indexReady;
+        }
+    };
+    return async (rawQuery) => {
+        const query = rawQuery.trim();
+        if (!query)
+            return { query: '', results: [] };
+        await prepareIndex();
+        const search = await dependencies.runSearch(latDir, query, VIEW_SEARCH_LIMIT, { buildIndex: false });
+        return {
+            query: search.query,
+            results: search.matches.map((match) => viewSearchResult(latDir, match)),
+        };
+    };
+}

package/dist/src/view/server.d.ts

@@ -0,0 +1,20 @@
+import { type Server } from 'node:http';
+import type { CmdContext } from '../context.js';
+import { type ViewSearch } from './search.js';
+import { type ViewStore } from './store.js';
+export type ViewServer = {
+    server: Server;
+    store: ViewStore;
+    url: string;
+    close: () => Promise<void>;
+};
+export type ViewServerOptions = {
+    clientDir?: string;
+    git?: boolean;
+    host?: string;
+    port?: number;
+    search?: ViewSearch;
+    watch?: boolean;
+};
+/** Start the read-only loopback server used by `lat ui`. */
+export declare function startViewServer(ctx: CmdContext, options?: ViewServerOptions): Promise<ViewServer>;