@plebeiantech/lat.md 0.12.3-fork.1

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

@@ -0,0 +1,22 @@
+import type { Root } from 'mdast';
+export type WikiLinkContext = {
+    line: number;
+};
+export type WikiLinkResolver = (target: string, context: WikiLinkContext) => string | null | Promise<string | null>;
+export type MarkdownRenderOptions = {
+    activeMarkdownLink?: string;
+    activeWikiLink?: string;
+    errors?: {
+        anchor: string;
+        line: number;
+        marker: 'heading' | 'line' | 'target';
+        target: string;
+    }[];
+    lineOffset?: number;
+    rewriteMarkdownLink?: (url: string) => string;
+};
+/** Render a lat.md file as safe HTML with resolved wiki links. */
+export declare function renderMarkdown(markdown: string, filePath: string, resolveWikiLink?: WikiLinkResolver, options?: MarkdownRenderOptions, parsedTree?: Root): Promise<{
+    html: string;
+    title: string;
+}>;

package/dist/src/view/markdown.js

@@ -0,0 +1,322 @@
+import { basename, extname } from 'node:path';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
+import rehypeSlug from 'rehype-slug';
+import rehypeStringify from 'rehype-stringify';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+import { parse } from '../parser.js';
+const CODE_LINK_CLASSES = [
+    'wiki-link-code',
+    'wiki-link-active',
+    'code-link-language',
+    'code-language-ts',
+    'code-language-js',
+    'code-language-py',
+    'code-language-rs',
+    'code-language-go',
+    'code-language-c',
+];
+const ERROR_CLASS = 'markdown-error';
+const GIT_CLASSES = ['git-added', 'git-removed'];
+function classAttributes(tag) {
+    return [
+        ...(defaultSchema.attributes?.[tag] ?? []),
+        ['className', ERROR_CLASS, ...GIT_CLASSES],
+    ];
+}
+const sanitizeSchema = {
+    ...defaultSchema,
+    tagNames: [...(defaultSchema.tagNames ?? []), 'ins'],
+    attributes: {
+        ...defaultSchema.attributes,
+        a: [
+            ...(defaultSchema.attributes?.a ?? []).filter((attribute) => !(Array.isArray(attribute) && attribute[0] === 'className')),
+            [
+                'className',
+                'data-footnote-backref',
+                'wiki-link-segmented',
+                'wiki-link-code',
+                'wiki-link-active',
+                ERROR_CLASS,
+                ...GIT_CLASSES,
+            ],
+        ],
+        blockquote: classAttributes('blockquote'),
+        code: classAttributes('code'),
+        del: classAttributes('del'),
+        div: classAttributes('div'),
+        h1: classAttributes('h1'),
+        h2: classAttributes('h2'),
+        h3: classAttributes('h3'),
+        h4: classAttributes('h4'),
+        h5: classAttributes('h5'),
+        h6: classAttributes('h6'),
+        img: classAttributes('img'),
+        ins: classAttributes('ins'),
+        li: classAttributes('li'),
+        p: classAttributes('p'),
+        pre: classAttributes('pre'),
+        span: [
+            ...(defaultSchema.attributes?.span ?? []),
+            'ariaHidden',
+            [
+                'className',
+                'wiki-link-context',
+                'wiki-link-leaf',
+                ...CODE_LINK_CLASSES.slice(2),
+                ERROR_CLASS,
+                ...GIT_CLASSES,
+            ],
+        ],
+    },
+};
+const htmlProcessor = unified()
+    .use(remarkRehype)
+    .use(rehypeSanitize, sanitizeSchema)
+    .use(rehypeSlug)
+    .use(rehypeStringify);
+function nodeText(node) {
+    if (typeof node.value === 'string')
+        return node.value;
+    if (!Array.isArray(node.children))
+        return '';
+    return node.children
+        .map((child) => nodeText(child))
+        .join('');
+}
+function wikiLinkContent(node) {
+    if (node.data.alias) {
+        return {
+            children: [{ type: 'text', value: node.data.alias }],
+            segmented: false,
+        };
+    }
+    const hash = node.value.lastIndexOf('#');
+    if (hash <= 0 || hash === node.value.length - 1) {
+        return {
+            children: [{ type: 'text', value: node.value }],
+            segmented: false,
+        };
+    }
+    return {
+        children: [
+            {
+                type: 'emphasis',
+                data: {
+                    hName: 'span',
+                    hProperties: { className: ['wiki-link-context'] },
+                },
+                children: [{ type: 'text', value: node.value.slice(0, hash + 1) }],
+            },
+            {
+                type: 'emphasis',
+                data: {
+                    hName: 'span',
+                    hProperties: { className: ['wiki-link-leaf'] },
+                },
+                children: [{ type: 'text', value: node.value.slice(hash + 1) }],
+            },
+        ],
+        segmented: true,
+    };
+}
+function codeLanguage(target) {
+    switch (extname(target.split('#', 1)[0]).toLowerCase()) {
+        case '.ts':
+        case '.tsx':
+            return { className: 'code-language-ts', label: 'TS' };
+        case '.js':
+        case '.jsx':
+            return { className: 'code-language-js', label: 'JS' };
+        case '.py':
+            return { className: 'code-language-py', label: 'PY' };
+        case '.rs':
+            return { className: 'code-language-rs', label: 'RS' };
+        case '.go':
+            return { className: 'code-language-go', label: 'GO' };
+        case '.c':
+        case '.h':
+            return { className: 'code-language-c', label: 'C' };
+        default:
+            return null;
+    }
+}
+function languageIcon(language) {
+    return {
+        type: 'emphasis',
+        data: {
+            hName: 'span',
+            hProperties: {
+                ariaHidden: 'true',
+                className: ['code-link-language', language.className],
+            },
+        },
+        children: [{ type: 'text', value: language.label }],
+    };
+}
+function targetMatches(node, target) {
+    if (node.type === 'wikiLink') {
+        return node.value.toLowerCase() === target.toLowerCase();
+    }
+    if (node.type === 'link' || node.type === 'image') {
+        return node.url === target;
+    }
+    if (node.type === 'linkReference' || node.type === 'imageReference') {
+        return node.identifier.toLowerCase() === target.toLowerCase();
+    }
+    return false;
+}
+function errorNodeScore(node, error) {
+    const { line, marker, target } = error;
+    const start = node.position?.start.line;
+    const end = node.position?.end.line;
+    if (!start || !end || line < start || line > end)
+        return null;
+    if (marker === 'heading') {
+        return start === line && node.type === 'heading' ? 0 : null;
+    }
+    if (marker === 'target' && targetMatches(node, target))
+        return 0;
+    if (node.type === 'paragraph')
+        return marker === 'line' ? 1 : 3;
+    if (start === line)
+        return 4;
+    return 5 + (end - start);
+}
+function markMarkdownErrors(tree, errors) {
+    for (const error of errors) {
+        let selected = null;
+        let selectedScore = Number.POSITIVE_INFINITY;
+        visit(tree, (candidate) => {
+            if (candidate.type === 'root' || candidate.type === 'text')
+                return;
+            const node = candidate;
+            const score = errorNodeScore(node, error);
+            if (score === null || score >= selectedScore)
+                return;
+            selected = node;
+            selectedScore = score;
+        });
+        if (!selected)
+            continue;
+        const node = selected;
+        const properties = node.data?.hProperties ?? {};
+        const currentClasses = properties.className;
+        const classes = Array.isArray(currentClasses)
+            ? currentClasses.map(String)
+            : currentClasses
+                ? [String(currentClasses)]
+                : [];
+        if (!classes.includes(ERROR_CLASS))
+            classes.push(ERROR_CLASS);
+        const generatedAnchor = error.anchor.startsWith('user-content-');
+        node.data = {
+            ...node.data,
+            hProperties: {
+                ...properties,
+                className: classes,
+                ...(node.type === 'heading' && !generatedAnchor
+                    ? {}
+                    : { id: error.anchor.replace(/^user-content-/, '') }),
+            },
+        };
+    }
+}
+/** Render a lat.md file as safe HTML with resolved wiki links. */
+export async function renderMarkdown(markdown, filePath, resolveWikiLink, options = {}, parsedTree) {
+    const tree = parsedTree ? structuredClone(parsedTree) : parse(markdown);
+    tree.children = tree.children.filter((node) => node.type !== 'yaml');
+    if (options.errors)
+        markMarkdownErrors(tree, options.errors);
+    if (options.rewriteMarkdownLink || options.activeMarkdownLink) {
+        visit(tree, 'link', (node) => {
+            const authoredUrl = node.url;
+            if (options.activeMarkdownLink &&
+                authoredUrl === options.activeMarkdownLink) {
+                node.data = {
+                    ...node.data,
+                    hProperties: {
+                        ...(node.data?.hProperties ?? {}),
+                        className: ['wiki-link-active'],
+                    },
+                };
+            }
+            if (options.rewriteMarkdownLink) {
+                node.url = options.rewriteMarkdownLink(authoredUrl);
+            }
+        });
+    }
+    const firstHeading = tree.children.find((node) => node.type === 'heading');
+    const title = firstHeading
+        ? nodeText(firstHeading)
+        : basename(filePath, '.md');
+    const resolvedLinks = new Map();
+    if (resolveWikiLink) {
+        const wikiLinks = [];
+        visit(tree, 'wikiLink', (node) => {
+            wikiLinks.push(node);
+        });
+        for (const node of wikiLinks) {
+            resolvedLinks.set(node, await resolveWikiLink(node.value, {
+                line: (node.position?.start.line ?? 0) + (options.lineOffset ?? 0),
+            }));
+        }
+    }
+    visit(tree, 'wikiLink', (node, index, parent) => {
+        if (index === undefined || !parent || !('children' in parent))
+            return;
+        const href = resolvedLinks.get(node);
+        const markedProperties = node.data?.hProperties;
+        if (href) {
+            const content = wikiLinkContent(node);
+            const language = href.startsWith('/code/')
+                ? codeLanguage(node.value)
+                : null;
+            const classes = content.segmented ? ['wiki-link-segmented'] : [];
+            if (language)
+                classes.push('wiki-link-code');
+            if (options.activeWikiLink &&
+                node.value.toLowerCase() === options.activeWikiLink.toLowerCase()) {
+                classes.push('wiki-link-active');
+            }
+            parent.children[index] = {
+                type: 'link',
+                url: href,
+                data: classes.length > 0 || markedProperties
+                    ? {
+                        hProperties: {
+                            ...markedProperties,
+                            className: [
+                                ...classes,
+                                ...(Array.isArray(markedProperties?.className)
+                                    ? markedProperties.className.map(String)
+                                    : []),
+                            ],
+                        },
+                    }
+                    : undefined,
+                children: language
+                    ? [languageIcon(language), ...content.children]
+                    : content.children,
+            };
+            return;
+        }
+        const alias = node.data.alias ? `|${node.data.alias}` : '';
+        parent.children[index] = markedProperties
+            ? {
+                type: 'emphasis',
+                data: {
+                    hName: 'span',
+                    hProperties: markedProperties,
+                },
+                children: [{ type: 'text', value: `[[${node.value}${alias}]]` }],
+            }
+            : {
+                type: 'text',
+                value: `[[${node.value}${alias}]]`,
+            };
+    });
+    const hast = await htmlProcessor.run(tree);
+    return { html: htmlProcessor.stringify(hast), title };
+}

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

@@ -0,0 +1,89 @@
+export type ViewGitFileStatus = 'modified' | 'new';
+export type ViewGitState = {
+    files: Record<string, ViewGitFileStatus>;
+};
+export type ViewIndex = {
+    files: string[];
+    entry: string;
+    errorCounts: Record<string, number>;
+    git: ViewGitState | null;
+};
+export type ViewDocumentError = {
+    anchor: string;
+    line: number;
+    marker: 'heading' | 'line' | 'target';
+    message: string;
+    target: string;
+};
+export type ViewSearchResult = {
+    sectionId: string;
+    title: string;
+    path: string;
+    breadcrumbs: string[];
+    description: string;
+    url: string;
+};
+export type ViewSearchResponse = {
+    query: string;
+    results: ViewSearchResult[];
+};
+export type ViewProjectChange = {
+    generation: number;
+    markdownGeneration: number;
+};
+export type ViewDocument = {
+    path: string;
+    title: string;
+    html: string;
+    gitHtml: string | null;
+    errors: ViewDocumentError[];
+    backReferences: ViewSectionBackReferences[];
+    frontmatter: {
+        requireCodeMention: boolean;
+    };
+};
+export type ViewMarkdownBackReference = {
+    kind: 'markdown';
+    sectionId: string;
+    breadcrumbs: string[];
+    paragraph: string;
+    paragraphHtml: string;
+    url: string;
+};
+export type ViewCodeBackReference = {
+    kind: 'code';
+    path: string;
+    line: number;
+    snippet: string;
+    url: string;
+};
+export type ViewSectionBackReference = ViewMarkdownBackReference | ViewCodeBackReference;
+export type ViewSectionBackReferences = {
+    sectionId: string;
+    headingId: string;
+    references: ViewSectionBackReference[];
+};
+export type ViewSourceReference = {
+    sectionId: string;
+    breadcrumbs: string[];
+    paragraph: string;
+    paragraphHtml: string;
+    url: string;
+};
+export type ViewSourceDocument = {
+    path: string;
+    content: string;
+    highlightedHtmlLines: string[];
+    focus: {
+        symbol: string;
+        kind: string;
+        signature: string;
+        startLine: number;
+        endLine: number;
+    } | null;
+    context: ViewSourceReference | null;
+    otherReferences: ViewSourceReference[];
+};
+export type ViewError = {
+    error: string;
+};

package/dist/src/view/protocol.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,62 @@
+import type { Root } from 'mdast';
+import type { CodeRef } from '../code-refs.js';
+import { type Ref, type MdLink, type Section } from '../lattice.js';
+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[];
+};
+export type ViewCodeReferenceFile = {
+    path: string;
+    lines: string[];
+    refs: CodeRef[];
+};
+type IndexedMarkdownReference = {
+    kind: 'markdown';
+    section: Section;
+    sourcePath: string;
+    line: number;
+    paragraph: ParagraphContent;
+    activeWikiLink?: string;
+    activeMarkdownLink?: string;
+};
+type IndexedBackReference = IndexedMarkdownReference | ViewCodeBackReference;
+export type ViewReferenceIndex = {
+    incomingBySection: ReadonlyMap<string, readonly IndexedBackReference[]>;
+    sourceByTarget: ReadonlyMap<string, readonly IndexedMarkdownReference[]>;
+};
+/** 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;
+/** Resolve cached outgoing occurrences into direct section and source indexes. */
+export declare function buildViewReferenceIndex(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[]): ViewReferenceIndex;
+/** 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. */
+export declare function renderSourceReferenceContext(index: ViewReferenceIndex, target: string, origin: SourceReferenceOrigin | undefined, latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<{
+    context: ViewSourceReference | null;
+    otherReferences: ViewSourceReference[];
+}>;
+export {};