@plebeiantech/lat.md 0.12.3-fork.9 → 0.13.4-fork.2

package/dist/src/view/publication.js

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dirname, join, relative, sep } from 'node:path';
+import { normalizeRepositoryPath, inspectRepositoryPath, } from '@plebeiantech/lat.md-core/repository-path';
+import { walkEntries } from '@plebeiantech/lat.md-core/walk';
+const exec = promisify(execFile);
+const portable = (path) => path.split(sep).join('/');
+function publicPath(path) {
+    return path
+        .split('/')
+        .every((part) => part.toLowerCase() !== 'config.local.yaml' &&
+        part.toLowerCase() !== 'node_modules' &&
+        !part.startsWith('.'));
+}
+/** Publication scope is deliberately narrower than interactive source browsing. */
+export async function createPublicationPolicy(projectRoot) {
+    let files;
+    const git = (args) => exec('git', ['-c', 'core.fsmonitor=false', ...args], {
+        cwd: projectRoot,
+        maxBuffer: 50 * 1024 * 1024,
+    });
+    let tracked;
+    try {
+        tracked = (await git(['ls-files', '--stage', '-z', '--', '.'])).stdout;
+    }
+    catch (error) {
+        // A directory without Git still has a useful publication policy: honor
+        // .gitignore and the ordinary walker exclusions rather than publish all files.
+        if (error.code !== 'ENOENT' &&
+            !String(error.stderr).includes('not a git repository'))
+            throw error;
+        if (error.code === 'ENOENT') {
+            for (let directory = projectRoot;; directory = dirname(directory)) {
+                if (existsSync(join(directory, '.git')))
+                    throw new Error('Git is required to determine publication scope for this checkout');
+                if (dirname(directory) === directory)
+                    break;
+            }
+        }
+        files = await walkEntries(projectRoot);
+        return policy(new Set(files.filter(publicPath)), projectRoot);
+    }
+    const ignored = new Set((await git([
+        'ls-files',
+        '--cached',
+        '--ignored',
+        '--exclude-standard',
+        '-z',
+        '--',
+        '.',
+    ])).stdout.split('\0'));
+    files = tracked.split('\0').flatMap((entry) => {
+        const tab = entry.indexOf('\t');
+        const mode = entry.slice(0, entry.indexOf(' '));
+        if (tab < 0 || !['100644', '100755'].includes(mode))
+            return [];
+        const path = entry.slice(tab + 1);
+        return publicPath(path) && !ignored.has(path) ? [path] : [];
+    });
+    return policy(new Set(files), projectRoot);
+}
+function policy(files, root) {
+    const realRoot = realpath(root);
+    return async (authoredPath) => {
+        const path = normalizeRepositoryPath(authoredPath);
+        if (!path || path !== authoredPath || !publicPath(path) || !files.has(path))
+            return false;
+        const inspected = await inspectRepositoryPath(root, path);
+        if (inspected.kind !== 'file')
+            return false;
+        const real = inspected.realPath;
+        // Resolving the root through a platform alias must not change membership.
+        const realRelative = portable(relative(await realRoot, real));
+        return publicPath(realRelative) && files.has(realRelative);
+    };
+}

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

@@ -1,34 +1,14 @@
-import type { Root } from 'mdast';
-import type { CodeRef } from '../code-refs.js';
-import { type Ref, type MdLink, type Section } from '../lattice.js';
+import type { CodeRef } from '@plebeiantech/lat.md-core/code-refs';
+import { type Section } from '@plebeiantech/lat.md-core/lattice-model';
+import { type MarkdownFileAnalysis, type MarkdownParagraph } from '@plebeiantech/lat.md-core/markdown-analysis';
 import { type WikiLinkResolver } from './markdown.js';
 import type { ViewCodeBackReference, ViewSectionBackReferences, ViewSourceReference } from './protocol.js';
 export type SourceReferenceOrigin = {
     sectionId: string;
     line: number;
 };
-type ParagraphContent = {
-    markdown: string;
-    startLine: number;
-    text: string;
-};
-type MarkdownLink = {
-    kind: 'image' | 'link';
-    line: number;
-    url: string;
-};
-export type ViewParsedMarkdownFile = {
-    absolutePath: string;
-    content: string;
-    path: string;
-    projectPath: string;
-    tree: Root;
-    sections: Section[];
-    wikiRefs: Ref[];
-    paragraphs: Map<number, ParagraphContent>;
-    markdownLinks: MarkdownLink[];
-    validationLinks: MdLink[];
-};
+type ParagraphContent = MarkdownParagraph;
+export type ViewParsedMarkdownFile = MarkdownFileAnalysis;
 export type ViewCodeReferenceFile = {
     path: string;
     lines: string[];
@@ -48,12 +28,17 @@ export type ViewReferenceIndex = {
     incomingBySection: ReadonlyMap<string, readonly IndexedBackReference[]>;
     sourceByTarget: ReadonlyMap<string, readonly IndexedMarkdownReference[]>;
     sourceReferenceCounts: ReadonlyMap<string, number>;
+    externalByTarget: ReadonlyMap<string, readonly IndexedBackReference[]>;
 };
 /** Parse one Markdown file once into every structure needed by the view store. */
 export declare function parseViewMarkdownFile(absolutePath: string, content: string, latDir: string, projectRoot: string): ViewParsedMarkdownFile;
 export declare function linkedSection(url: string, sourcePath: string, sectionsByPath: ReadonlyMap<string, Section[]>): Section | null;
 /** Resolve cached outgoing occurrences into direct section and source indexes. */
-export declare function buildViewReferenceIndex(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[]): ViewReferenceIndex;
+export declare function buildViewReferenceIndex(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[], resolveExternalTarget?: (target: string) => string | null): ViewReferenceIndex;
+/** Render exact local Markdown and code backlinks for external targets. */
+export declare function renderExternalSectionBackReferences(index: ViewReferenceIndex, targets: ReadonlyMap<string, string>, latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<ViewSectionBackReferences[]>;
+/** Adapt exact external backlinks to the source context presentation. */
+export declare function renderExternalSourceReferences(index: ViewReferenceIndex, target: string, latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<ViewSourceReference[]>;
 /** Render direct reverse-index entries for the sections visible in one file. */
 export declare function renderSectionBackReferences(index: ViewReferenceIndex, visibleSections: Section[], latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<ViewSectionBackReferences[]>;
 /** Render cached Markdown occurrences that point to one source target. */

package/dist/src/view/references.js

@@ -1,112 +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';
-import { viewSourceTarget } from './source-target.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, '');
@@ -125,20 +34,19 @@ export 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('/');
@@ -155,14 +63,15 @@ export 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()));
@@ -175,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);
@@ -194,6 +104,15 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
         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) {
@@ -209,6 +128,10 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
                 activeWikiLink: ref.target,
             };
             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);
@@ -247,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())) {
@@ -274,21 +207,99 @@ export function buildViewReferenceIndex(markdownFiles, codeFiles, allSections) {
             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),
     };
 }
@@ -308,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'
@@ -345,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,15 +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[], referenceIndex?: ViewReferenceIndex): 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<{
     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>;