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

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

@@ -1,5 +1,6 @@
-import { type Section } from '../lattice.js';
+import { type Section } from '../lattice-model.js';
+import type { ExternalResolver } from '../external-sources.js';
 import type { ViewDocumentError } from './protocol.js';
 import type { ViewCodeReferenceFile, ViewParsedMarkdownFile } from './references.js';
 /** Build per-document validation errors entirely from the current view snapshot. */
-export declare function buildViewDiagnostics(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[], projectRoot: string): Promise<ReadonlyMap<string, readonly ViewDocumentError[]>>;
+export declare function buildViewDiagnostics(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[], projectRoot: string, external?: ExternalResolver, latDir?: string): Promise<ReadonlyMap<string, readonly ViewDocumentError[]>>;

package/dist/src/view/diagnostics.js

@@ -1,41 +1,10 @@
 import { existsSync } from 'node:fs';
 import { extname, relative, resolve, dirname } from 'node:path';
-import { ambiguousRefMessage, sourceRefError } from '../cli/check.js';
-import { buildFileIndex, buildSectionSlugIndex, flattenSections, parseFrontmatter, resolveRef, } from '../lattice.js';
-import { clearSymbolCache } from '../source-parser.js';
-import { toPosix } from '../walk.js';
-const MAX_BODY_LENGTH = 250;
-function decodeLinkPart(value) {
-    try {
-        return decodeURIComponent(value);
-    }
-    catch {
-        return value;
-    }
-}
-function localLinkTarget(url) {
-    const value = url.trim();
-    if (value.startsWith('/'))
-        return null;
-    const windowsDrivePath = /^[a-zA-Z]:\\/.test(value);
-    if (!windowsDrivePath && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) {
-        return null;
-    }
-    const queryAt = value.indexOf('?');
-    const fragmentAt = value.indexOf('#');
-    const pathEnd = Math.min(queryAt === -1 ? value.length : queryAt, fragmentAt === -1 ? value.length : fragmentAt);
-    const rawPath = value.slice(0, pathEnd);
-    const path = rawPath === '' ? null : decodeLinkPart(rawPath);
-    const fragment = fragmentAt === -1 ? null : decodeLinkPart(value.slice(fragmentAt + 1));
-    if (rawPath === '' && fragment === null)
-        return null;
-    if (path?.includes('\\'))
-        return { kind: 'invalid-backslash' };
-    return { kind: 'target', path, fragment };
-}
-function bodyTextLength(body) {
-    return body.replace(/\[\[[^\]]*\]\]/g, '').length;
-}
+import { ambiguousRefMessage, repositoryRefError } from '../cli/check.js';
+import { buildFileIndex, buildSectionSlugIndex, flattenSections, resolveRef, } from '../lattice-model.js';
+import { SourceParserRuntime } from '../source-parser.js';
+import { toPosix } from '../path.js';
+import { parseLocalMarkdownTarget } from '../markdown-validation.js';
 function error(line, target, message, options = {}) {
     return {
         anchor: options.anchor || `user-content-markdown-error-${line}`,
@@ -64,12 +33,11 @@ function addError(errors, path, diagnostic) {
     errors.set(path, fileErrors);
 }
 async function markdownLinkError(file, filesByAbsolutePath, link, projectRoot) {
-    const target = localLinkTarget(link.url);
+    const target = parseLocalMarkdownTarget(link.url);
     if (target === null)
         return null;
-    if (target.kind === 'invalid-backslash') {
-        return error(link.line, link.url, `invalid ${link.kind} (${link.url}) — backslashes are not path separators in Markdown; use "/" instead`);
-    }
+    if (target.kind === 'invalid-backslash')
+        return null;
     const absolutePath = target.path
         ? resolve(dirname(file.absolutePath), target.path)
         : file.absolutePath;
@@ -90,8 +58,8 @@ async function markdownLinkError(file, filesByAbsolutePath, link, projectRoot) {
     return error(link.line, link.url, `broken link (${link.url}) — heading "#${target.fragment}" not found in "${destination.path}"`);
 }
 /** Build per-document validation errors entirely from the current view snapshot. */
-export async function buildViewDiagnostics(markdownFiles, codeFiles, allSections, projectRoot) {
-    clearSymbolCache();
+export async function buildViewDiagnostics(markdownFiles, codeFiles, allSections, projectRoot, external, latDir = resolve(projectRoot, 'lat.md')) {
+    const sourceParserRuntime = new SourceParserRuntime();
     const files = [...markdownFiles];
     const errors = new Map();
     const sections = flattenSections(allSections);
@@ -99,25 +67,58 @@ export async function buildViewDiagnostics(markdownFiles, codeFiles, allSections
     const fileIndex = buildFileIndex(allSections);
     const slugIndex = buildSectionSlugIndex(allSections);
     const filesByAbsolutePath = new Map(files.map((file) => [resolve(file.absolutePath), file]));
+    if (external) {
+        const root = files.find((file) => file.path === 'lat.md') ?? files[0];
+        if (root) {
+            for (const configError of external.snapshot.errors) {
+                addError(errors, root.path, error(1, 'external-sources', configError.message, {
+                    marker: 'line',
+                }));
+            }
+        }
+    }
     for (const file of files) {
+        for (const diagnostic of file.diagnostics) {
+            addError(errors, file.path, error(diagnostic.line, diagnostic.target, diagnostic.message, {
+                anchor: diagnostic.anchor,
+                marker: diagnostic.marker,
+            }));
+        }
         for (const ref of file.wikiRefs) {
+            if (external) {
+                try {
+                    if (external.parse(ref.target)) {
+                        await external.resolve(ref.target);
+                        continue;
+                    }
+                }
+                catch (externalError) {
+                    addError(errors, file.path, error(ref.line, ref.target, externalError.message));
+                    continue;
+                }
+                const unknownExternal = external.unknownTargetMessage(ref.target);
+                if (unknownExternal) {
+                    addError(errors, file.path, error(ref.line, ref.target, unknownExternal));
+                    continue;
+                }
+            }
             const resolved = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
             let message = null;
             if (resolved.ambiguous) {
                 message = ambiguousRefMessage(ref.target, resolved.ambiguous, resolved.suggested);
             }
             else if (!sectionIds.has(resolved.resolved.toLowerCase())) {
-                message = await sourceRefError(ref.target, projectRoot);
+                message = await repositoryRefError(ref.target, projectRoot, {
+                    latDir,
+                    runtime: sourceParserRuntime,
+                });
             }
             if (message)
                 addError(errors, file.path, error(ref.line, ref.target, message));
         }
         const links = new Map();
         for (const link of file.validationLinks) {
-            if ('identifier' in link) {
-                addError(errors, file.path, error(link.line, link.identifier, `undefined ${link.kind === 'imageReference' ? 'image' : 'link'} reference (${link.source}) — definition "[${link.identifier}]" not found`, { marker: 'line' }));
-            }
-            else if (link.kind !== 'definition') {
+            if (!('identifier' in link) && link.kind !== 'definition') {
                 links.set(`${link.kind}:${link.line}:${link.url}`, {
                     kind: link.kind,
                     line: link.line,
@@ -133,16 +134,6 @@ export async function buildViewDiagnostics(markdownFiles, codeFiles, allSections
             if (diagnostic)
                 addError(errors, file.path, diagnostic);
         }
-        for (const section of flattenSections(file.sections)) {
-            if (!section.firstParagraph) {
-                addError(errors, file.path, error(section.startLine, section.id, `section "${section.id}" has no leading paragraph. Every section must start with a brief overview (≤${MAX_BODY_LENGTH} chars).`, { anchor: section.githubSlug, marker: 'heading' }));
-                continue;
-            }
-            const length = bodyTextLength(section.firstParagraph);
-            if (length > MAX_BODY_LENGTH) {
-                addError(errors, file.path, error(section.startLine, section.id, `section "${section.id}" leading paragraph is ${length} characters (max ${MAX_BODY_LENGTH}, excluding [[wiki links]]).`, { anchor: section.githubSlug, marker: 'heading' }));
-            }
-        }
     }
     const mentionedSections = new Set();
     for (const file of codeFiles) {
@@ -155,7 +146,7 @@ export async function buildViewDiagnostics(markdownFiles, codeFiles, allSections
         }
     }
     for (const file of files) {
-        if (!parseFrontmatter(file.content).requireCodeMention)
+        if (!file.frontmatter.requireCodeMention)
             continue;
         for (const section of flattenSections(file.sections)) {
             if (section.children.length === 0 &&

package/dist/src/view/document-edit.d.ts

@@ -0,0 +1,8 @@
+export declare class ViewDocumentConflictError extends Error {
+}
+export type AppliedDocumentEdit = {
+    content: string;
+    merged: boolean;
+};
+/** Apply the user's base-to-edited patch to the latest content on disk. */
+export declare function applyDocumentEdit(baseContent: string, editedContent: string, currentContent: string): AppliedDocumentEdit;

package/dist/src/view/document-edit.js

@@ -0,0 +1,25 @@
+import { applyPatch, createPatch } from 'diff';
+const PATCH_CONTEXT_LINES = 3;
+const PATCH_FUZZ_LINES = 2;
+export class ViewDocumentConflictError extends Error {
+}
+/** Apply the user's base-to-edited patch to the latest content on disk. */
+export function applyDocumentEdit(baseContent, editedContent, currentContent) {
+    if (baseContent === editedContent) {
+        return { content: currentContent, merged: currentContent !== baseContent };
+    }
+    if (currentContent === editedContent) {
+        return { content: currentContent, merged: currentContent !== baseContent };
+    }
+    if (currentContent === baseContent) {
+        return { content: editedContent, merged: false };
+    }
+    const patch = createPatch('document.md', baseContent, editedContent, undefined, undefined, { context: PATCH_CONTEXT_LINES });
+    const content = applyPatch(currentContent, patch, {
+        fuzzFactor: PATCH_FUZZ_LINES,
+    });
+    if (content === false) {
+        throw new ViewDocumentConflictError('Could not save because this file changed in the same area. Your edits are still in the editor.');
+    }
+    return { content, merged: true };
+}

package/dist/src/view/document-route.d.ts

@@ -0,0 +1,12 @@
+/** Build the canonical, extensionless browser route for a Markdown file. */
+export declare function documentUrl(path: string, fragment?: string): string;
+/** Resolve an extensionless browser route back to its Markdown file path. */
+export declare function documentPath(pathname: string): string | null;
+/** Resolve an explicit `.md` route to the raw Markdown file it requests. */
+export declare function rawDocumentPath(pathname: string): string | null;
+/** Build the browser route for a non-Markdown file stored in the vault. */
+export declare function documentResourceUrl(path: string): string;
+/** Resolve a browser resource route to a safe vault-relative file path. */
+export declare function documentResourcePath(pathname: string): string | null;
+/** Keep relative Markdown-to-Markdown links inside the rendered document UI. */
+export declare function rewriteDocumentLink(value: string, sourcePath: string): string;

package/dist/src/view/document-route.js

@@ -0,0 +1,93 @@
+const DOCUMENT_PREFIX = '/docs/';
+const RESOURCE_PREFIX = '/resources/';
+const MARKDOWN_EXTENSION = '.md';
+function encodePath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+function decodeDocumentPath(pathname) {
+    if (!pathname.startsWith(DOCUMENT_PREFIX))
+        return null;
+    try {
+        const path = pathname
+            .slice(DOCUMENT_PREFIX.length)
+            .split('/')
+            .map(decodeURIComponent)
+            .join('/');
+        return path && !path.endsWith('/') ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the canonical, extensionless browser route for a Markdown file. */
+export function documentUrl(path, fragment = '') {
+    const routePath = path.endsWith(MARKDOWN_EXTENSION)
+        ? path.slice(0, -MARKDOWN_EXTENSION.length)
+        : path;
+    return `${DOCUMENT_PREFIX}${encodePath(routePath)}${fragment ? `#${encodeURIComponent(fragment)}` : ''}`;
+}
+/** Resolve an extensionless browser route back to its Markdown file path. */
+export function documentPath(pathname) {
+    const path = decodeDocumentPath(pathname);
+    if (!path || path.toLowerCase().endsWith(MARKDOWN_EXTENSION))
+        return null;
+    return `${path}${MARKDOWN_EXTENSION}`;
+}
+/** Resolve an explicit `.md` route to the raw Markdown file it requests. */
+export function rawDocumentPath(pathname) {
+    const path = decodeDocumentPath(pathname);
+    return path?.toLowerCase().endsWith(MARKDOWN_EXTENSION) ? path : null;
+}
+/** Build the browser route for a non-Markdown file stored in the vault. */
+export function documentResourceUrl(path) {
+    return `${RESOURCE_PREFIX}${encodePath(path)}`;
+}
+/** Resolve a browser resource route to a safe vault-relative file path. */
+export function documentResourcePath(pathname) {
+    if (!pathname.startsWith(RESOURCE_PREFIX))
+        return null;
+    try {
+        const segments = pathname
+            .slice(RESOURCE_PREFIX.length)
+            .split('/')
+            .map(decodeURIComponent);
+        if (segments.length === 0 ||
+            segments.some((segment) => !segment ||
+                segment === '.' ||
+                segment === '..' ||
+                segment.includes('\\'))) {
+            return null;
+        }
+        return segments.join('/');
+    }
+    catch {
+        return null;
+    }
+}
+/** Keep relative Markdown-to-Markdown links inside the rendered document UI. */
+export function rewriteDocumentLink(value, sourcePath) {
+    if (!value ||
+        value.startsWith('#') ||
+        value.startsWith('/') ||
+        value.startsWith('//') ||
+        /^[a-z][a-z\d+.-]*:/i.test(value)) {
+        return value;
+    }
+    let resolved;
+    try {
+        resolved = new URL(value, `http://lat.local${DOCUMENT_PREFIX}${encodePath(sourcePath)}`);
+    }
+    catch {
+        return value;
+    }
+    if (resolved.origin !== 'http://lat.local')
+        return value;
+    const path = rawDocumentPath(resolved.pathname);
+    if (path) {
+        return `${documentUrl(path)}${resolved.search}${resolved.hash}`;
+    }
+    const resourcePath = decodeDocumentPath(resolved.pathname);
+    if (!resourcePath)
+        return value;
+    return `${documentResourceUrl(resourcePath)}${resolved.search}${resolved.hash}`;
+}

package/dist/src/view/document-tree.d.ts

@@ -0,0 +1,18 @@
+import type { ViewDocumentElement, ViewDocumentTree } from './protocol.js';
+type HastLikeNode = {
+    type?: unknown;
+    value?: unknown;
+    tagName?: unknown;
+    properties?: unknown;
+    children?: unknown;
+};
+/** Strip a sanitized HAST tree to the stable JSON wire representation. */
+export declare function toViewDocumentTree(tree: HastLikeNode): ViewDocumentTree;
+export declare function documentTreeUrls(tree: ViewDocumentTree): string[];
+export declare function visitDocumentElements(tree: ViewDocumentTree, visitor: (element: ViewDocumentElement) => void): void;
+/** Apply parser-neutral presentation to links that leave the current site. */
+export declare function decorateExternalSiteLinks(tree: ViewDocumentTree): ViewDocumentTree;
+/** Clone a document tree while structurally rewriting navigable URLs. */
+export declare function rewriteDocumentTreeUrls(tree: ViewDocumentTree, rewrite: (value: string) => string): ViewDocumentTree;
+export declare function textDocumentTree(value: string): ViewDocumentTree;
+export {};

package/dist/src/view/document-tree.js

@@ -0,0 +1,139 @@
+function propertyValue(value) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string' || typeof item === 'number');
+    }
+    return undefined;
+}
+function documentNode(node) {
+    if (node.type === 'text' && typeof node.value === 'string') {
+        return { type: 'text', value: node.value };
+    }
+    if (node.type !== 'element' || typeof node.tagName !== 'string')
+        return null;
+    const properties = {};
+    if (node.properties && typeof node.properties === 'object') {
+        for (const [name, value] of Object.entries(node.properties)) {
+            const normalized = propertyValue(value);
+            if (normalized !== undefined)
+                properties[name] = normalized;
+        }
+    }
+    const children = Array.isArray(node.children)
+        ? node.children
+            .map((child) => documentNode(child))
+            .filter((child) => child !== null)
+        : [];
+    return {
+        type: 'element',
+        tagName: node.tagName,
+        properties,
+        children,
+    };
+}
+/** Strip a sanitized HAST tree to the stable JSON wire representation. */
+export function toViewDocumentTree(tree) {
+    if (tree.type !== 'root' || !Array.isArray(tree.children)) {
+        throw new Error('Document adapter did not produce a root node');
+    }
+    return {
+        version: 1,
+        type: 'root',
+        children: tree.children
+            .map((child) => documentNode(child))
+            .filter((child) => child !== null),
+    };
+}
+export function documentTreeUrls(tree) {
+    const urls = [];
+    visitDocumentElements(tree, (element) => {
+        for (const name of ['href', 'src']) {
+            const value = element.properties[name];
+            if (typeof value === 'string')
+                urls.push(value);
+        }
+    });
+    return urls;
+}
+export function visitDocumentElements(tree, visitor) {
+    const visit = (node) => {
+        if (node.type !== 'element')
+            return;
+        visitor(node);
+        for (const child of node.children)
+            visit(child);
+    };
+    for (const child of tree.children)
+        visit(child);
+}
+function classNames(value) {
+    if (Array.isArray(value))
+        return value.map(String);
+    return typeof value === 'string' ? value.split(/\s+/).filter(Boolean) : [];
+}
+function isExternalSiteUrl(value) {
+    return /^(?:https?:)?\/\//i.test(value);
+}
+function containsElementTag(element, tagName) {
+    return element.children.some((child) => child.type === 'element' &&
+        (child.tagName === tagName || containsElementTag(child, tagName)));
+}
+/** Apply parser-neutral presentation to links that leave the current site. */
+export function decorateExternalSiteLinks(tree) {
+    visitDocumentElements(tree, (element) => {
+        const href = element.properties.href;
+        if (element.tagName !== 'a' ||
+            typeof href !== 'string' ||
+            !isExternalSiteUrl(href)) {
+            return;
+        }
+        const classes = classNames(element.properties.className);
+        if (!classes.includes('external-link'))
+            classes.push('external-link');
+        element.properties.className = classes;
+        if (containsElementTag(element, 'img'))
+            return;
+        const alreadyDecorated = element.children.some((child) => child.type === 'element' &&
+            child.tagName === 'span' &&
+            classNames(child.properties.className).includes('external-link-icon'));
+        if (!alreadyDecorated) {
+            element.children.push({
+                type: 'element',
+                tagName: 'span',
+                properties: {
+                    ariaHidden: 'true',
+                    className: ['external-link-icon'],
+                },
+                children: [],
+            });
+        }
+    });
+    return tree;
+}
+/** Clone a document tree while structurally rewriting navigable URLs. */
+export function rewriteDocumentTreeUrls(tree, rewrite) {
+    const cloneNode = (node) => {
+        if (node.type === 'text')
+            return { ...node };
+        const properties = { ...node.properties };
+        for (const name of ['href', 'src']) {
+            const value = properties[name];
+            if (typeof value === 'string')
+                properties[name] = rewrite(value);
+        }
+        return {
+            ...node,
+            properties,
+            children: node.children.map(cloneNode),
+        };
+    };
+    return { ...tree, children: tree.children.map(cloneNode) };
+}
+export function textDocumentTree(value) {
+    return { version: 1, type: 'root', children: [{ type: 'text', value }] };
+}

package/dist/src/view/external-document-tree.d.ts

@@ -0,0 +1,3 @@
+import type { ViewDocumentTree } from './protocol.js';
+/** Reflect a native non-Markdown parser AST into the browser document tree. */
+export declare function renderExternalDocumentTree(format: 'asciidoc' | 'restructuredtext', content: string): Promise<ViewDocumentTree>;