@plebeiantech/lat.md 0.12.3-fork.2 → 0.12.3-fork.21

package/dist/src/view/references.js

@@ -1,111 +1,21 @@
 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 { buildFileIndex, buildSectionSlugIndex, flattenSections, resolveRef, } from '@plebeiantech/lat.md-core/lattice-model';
+import { analyzeMarkdownFile, } from '@plebeiantech/lat.md-core/markdown-analysis';
+import { toPosix } from '@plebeiantech/lat.md-core/path';
 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;
-}
+import { viewSourceTarget, rewriteLocalFileLink } from './source-target.js';
+import { documentUrl as routeDocumentUrl } from './document-route.js';
 /** 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),
-    };
+    return analyzeMarkdownFile(absolutePath, content, latDir, projectRoot);
 }
 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}`;
+    return rewriteLocalFileLink(url, requestedPath);
 }
 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}`;
+    const fragment = section.githubSlug ? section.githubSlug : '';
+    return routeDocumentUrl(path, fragment);
 }
 function breadcrumbs(latDir, projectRoot, section) {
     const path = toPosix(relative(latDir, resolve(projectRoot, section.filePath))).replace(/\.md$/i, '');
@@ -115,7 +25,7 @@ function sourceLineUrl(path, line) {
     const encoded = path.split('/').map(encodeURIComponent).join('/');
     return `/code/${encoded}?at=${line}`;
 }
-function linkedSection(url, sourcePath, sectionsByPath) {
+export function linkedSection(url, sourcePath, sectionsByPath) {
     if (url.startsWith('//') || /^[a-z][a-z\d+.-]*:/i.test(url))
         return null;
     const encodedSourcePath = sourcePath
@@ -124,20 +34,19 @@ function linkedSection(url, sourcePath, sectionsByPath) {
         .join('/');
     let destination;
     try {
-        destination = new URL(url, `http://lat.local/docs/${encodedSourcePath}`);
+        destination = new URL(url, `http://lat.local/${encodedSourcePath}`);
     }
     catch {
         return null;
     }
-    if (destination.origin !== 'http://lat.local' ||
-        !destination.pathname.startsWith('/docs/')) {
+    if (destination.origin !== 'http://lat.local') {
         return null;
     }
     let path;
     let fragment;
     try {
         path = destination.pathname
-            .slice('/docs/'.length)
+            .slice(1)
             .split('/')
             .map(decodeURIComponent)
             .join('/');
@@ -154,14 +63,15 @@ function linkedSection(url, sourcePath, sectionsByPath) {
     return (sections.find((section) => section.githubSlug?.toLowerCase() === fragment.toLowerCase()) ?? null);
 }
 function paragraphFor(file, section, line) {
-    return (file.paragraphs.get(line) ?? {
+    return (file.paragraphs.find((paragraph) => line >= paragraph.startLine && line <= paragraph.endLine) ?? {
         markdown: section.firstParagraph,
         startLine: line,
+        endLine: line,
         text: section.firstParagraph,
     });
 }
 /** Resolve cached outgoing occurrences into direct section and source indexes. */
-export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
+export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections, resolveExternalTarget) {
     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()));
@@ -174,6 +84,7 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
     }
     const incoming = new Map();
     const sourceByTarget = new Map();
+    const externalByTarget = new Map();
     const addIncoming = (targetId, key, reference) => {
         const target = targetId.toLowerCase();
         let references = incoming.get(target);
@@ -184,6 +95,24 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
         if (!references.has(key))
             references.set(key, reference);
     };
+    const addSourceReference = (target, key, reference) => {
+        let references = sourceByTarget.get(target);
+        if (!references) {
+            references = new Map();
+            sourceByTarget.set(target, references);
+        }
+        if (!references.has(key))
+            references.set(key, reference);
+    };
+    const addExternalReference = (target, key, reference) => {
+        let references = externalByTarget.get(target);
+        if (!references) {
+            references = new Map();
+            externalByTarget.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) {
@@ -198,16 +127,24 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
                 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 locationKey = `markdown:${section.filePath}:${reference.paragraph.startLine}`;
+            const externalTarget = resolveExternalTarget?.(ref.target);
+            if (externalTarget) {
+                addExternalReference(externalTarget, locationKey, reference);
+            }
+            const source = viewSourceTarget(ref.target);
+            if (source) {
+                addSourceReference(source.key, locationKey, reference);
+                if (source.symbol) {
+                    addSourceReference(source.fileKey, locationKey, reference);
+                }
+            }
             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);
+            addIncoming(resolved.resolved, locationKey, reference);
         }
         for (const link of file.markdownLinks) {
             if (link.kind !== 'link')
@@ -233,6 +170,16 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
     }
     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 externalTarget = resolveExternalTarget?.(ref.target);
+            if (externalTarget) {
+                addExternalReference(externalTarget, `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),
+                });
+            }
             const resolved = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
             if (resolved.ambiguous ||
                 !sectionById.has(resolved.resolved.toLowerCase())) {
@@ -252,22 +199,107 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
             target,
             [...references.values()],
         ])),
-        sourceByTarget,
+        sourceByTarget: new Map([...sourceByTarget].map(([target, references]) => [
+            target,
+            [...references.values()],
+        ])),
+        sourceReferenceCounts: new Map([...sourceByTarget].map(([target, references]) => [
+            target,
+            references.size,
+        ])),
+        externalByTarget: new Map([...externalByTarget].map(([target, references]) => [
+            target,
+            [...references.values()],
+        ])),
     };
 }
+async function renderExternalReference(reference, latDir, projectRoot, createWikiLinkResolver) {
+    if (reference.kind === 'code')
+        return reference;
+    const resolver = createWikiLinkResolver
+        ? await createWikiLinkResolver(reference.sourcePath)
+        : undefined;
+    return renderIndexedMarkdownReference(reference, latDir, projectRoot, resolver);
+}
+/** Render exact local Markdown and code backlinks for external targets. */
+export async function renderExternalSectionBackReferences(index, targets, latDir, projectRoot, createWikiLinkResolver) {
+    const sections = new Map();
+    for (const [target, headingId] of targets) {
+        let section = sections.get(headingId);
+        if (!section) {
+            section = { sectionId: target, references: new Map() };
+            sections.set(headingId, section);
+        }
+        const lowerTarget = target.toLowerCase();
+        const indexed = [...index.externalByTarget]
+            .filter(([candidate]) => candidate.toLowerCase() === lowerTarget)
+            .flatMap(([, references]) => references);
+        for (const reference of indexed) {
+            const key = reference.kind === 'markdown'
+                ? `markdown:${reference.sourcePath}:${reference.paragraph.startLine}`
+                : `code:${reference.path}:${reference.line}`;
+            if (!section.references.has(key))
+                section.references.set(key, reference);
+        }
+    }
+    const result = [];
+    for (const [headingId, section] of sections) {
+        const references = await Promise.all([...section.references.values()].map((reference) => renderExternalReference(reference, latDir, projectRoot, createWikiLinkResolver)));
+        result.push({ sectionId: section.sectionId, headingId, references });
+    }
+    return result;
+}
+/** Adapt exact external backlinks to the source context presentation. */
+export async function renderExternalSourceReferences(index, target, latDir, projectRoot, createWikiLinkResolver) {
+    const indexed = index.externalByTarget.get(target) ?? [];
+    const result = [];
+    for (const reference of indexed) {
+        const rendered = await renderExternalReference(reference, latDir, projectRoot, createWikiLinkResolver);
+        if (rendered.kind === 'markdown') {
+            result.push({
+                sectionId: rendered.sectionId,
+                breadcrumbs: rendered.breadcrumbs,
+                paragraph: rendered.paragraph,
+                paragraphTree: rendered.paragraphTree,
+                url: rendered.url,
+            });
+        }
+        else {
+            result.push({
+                sectionId: `code:${rendered.path}:${rendered.line}`,
+                breadcrumbs: [...rendered.path.split('/'), `line ${rendered.line}`],
+                paragraph: rendered.snippet,
+                paragraphTree: {
+                    version: 1,
+                    type: 'root',
+                    children: [
+                        {
+                            type: 'element',
+                            tagName: 'code',
+                            properties: {},
+                            children: [{ type: 'text', value: rendered.snippet }],
+                        },
+                    ],
+                },
+                url: rendered.url,
+            });
+        }
+    }
+    return result;
+}
 async function renderIndexedMarkdownReference(reference, latDir, projectRoot, resolveWikiLink) {
-    const paragraphHtml = (await renderMarkdown(reference.paragraph.markdown, reference.sourcePath, resolveWikiLink, {
+    const paragraphTree = (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;
+    })).tree;
     return {
         kind: 'markdown',
         sectionId: reference.section.id,
         breadcrumbs: breadcrumbs(latDir, projectRoot, reference.section),
         paragraph: reference.paragraph.text,
-        paragraphHtml,
+        paragraphTree,
         url: documentUrl(latDir, projectRoot, reference.section),
     };
 }
@@ -287,8 +319,6 @@ export async function renderSectionBackReferences(index, visibleSections, latDir
     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'
@@ -305,7 +335,8 @@ export async function renderSectionBackReferences(index, visibleSections, latDir
 }
 /** 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 source = viewSourceTarget(target);
+    const indexed = source ? (index.sourceByTarget.get(source.key) ?? []) : [];
     const resolverByPath = new Map();
     const located = [];
     for (const reference of indexed) {
@@ -323,7 +354,7 @@ export async function renderSourceReferenceContext(index, target, origin, latDir
                 sectionId: rendered.sectionId,
                 breadcrumbs: rendered.breadcrumbs,
                 paragraph: rendered.paragraph,
-                paragraphHtml: rendered.paragraphHtml,
+                paragraphTree: rendered.paragraphTree,
                 url: rendered.url,
             },
         });

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

@@ -1,12 +1,25 @@
-import { type Section } from '../lattice.js';
-import type { ViewSourceDocument } from './protocol.js';
+import { type Section } from '@plebeiantech/lat.md-core/lattice-model';
+import { type ExternalResolver } from '@plebeiantech/lat.md-core/external-sources';
+import type { ExternalTarget } from '@plebeiantech/lat.md-core/external-sources';
+import { renderExternalDocumentTree } from './external-document-tree.js';
+import type { ViewExternalDocument, 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: {
+export declare class ViewExternalNotFoundError extends Error {
+}
+export declare function externalUrl(target: string): string;
+/** Make repository-relative external-document links reflect pulled files. */
+export declare function resolveExternalDocumentLinks(tree: Awaited<ReturnType<typeof renderExternalDocumentTree>>, current: ExternalTarget, external: ExternalResolver, referenceIndex: ViewReferenceIndex): typeof tree;
+export declare function createMarkdownWikiLinkResolver(latDir: string, requestedPath: string, loadedSections: Section[], referenceIndex?: ViewReferenceIndex, externalResolver?: ExternalResolver, publishable?: (path: string) => Promise<boolean>): Promise<(target: string, context: {
     line: number;
-}) => Promise<string | null>>;
+}) => Promise<{
+    href: string;
+    referenceCount: number;
+} | null>>;
+/** Resolve and render one configured external file through the normal view models. */
+export declare function getViewExternal(latDir: string, projectRoot: string, targetValue: string, external: ExternalResolver, allSections: Section[], referenceIndex: ViewReferenceIndex, publishable?: (path: string) => Promise<boolean>): Promise<ViewExternalDocument>;
 /** 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>;
+export declare function getViewSource(latDir: string, projectRoot: string, requestedPath: string, requestedSymbol?: string, origin?: SourceReferenceOrigin, requestedLine?: number, allSections?: Section[], referenceIndex?: ViewReferenceIndex, publishable?: (path: string) => Promise<boolean>): Promise<ViewSourceDocument>;