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

package/dist/src/view/store.js

@@ -1,17 +1,30 @@
+import { repositoryFilePath } from '@plebeiantech/lat.md-core/repository-path';
+import { randomUUID } from 'node:crypto';
 import { watch as watchFiles } from 'node:fs';
-import { readFile, realpath } from 'node:fs/promises';
+import { readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 import { basename, extname, isAbsolute, relative, resolve, sep, } from 'node:path';
-import { LAT_REF_RE, scanCodeRefs } from '../code-refs.js';
-import { listLatticeFiles, parseFrontmatter, } from '../lattice.js';
-import { SOURCE_EXTENSIONS } from '../source-parser.js';
-import { toPosix } from '../walk.js';
+import { createCodeReferenceDiscovery, LAT_REF_RE, } from '@plebeiantech/lat.md-core/code-refs';
+import { createExternalResolver, } from '@plebeiantech/lat.md-core/external-sources';
+import { listLatticeFiles } from '@plebeiantech/lat.md-core/project-discovery';
+import { analyzeMarkdownPath } from '@plebeiantech/lat.md-core/markdown-analysis-cache';
+import { isSourceFileExtension } from '@plebeiantech/lat.md-core/source-formats';
+import { toPosix } from '@plebeiantech/lat.md-core/path';
 import { renderMarkdown } from './markdown.js';
 import { buildViewDiagnostics } from './diagnostics.js';
+import { applyDocumentEdit, ViewDocumentConflictError, } from './document-edit.js';
 import { buildGitDiffTree } from './git-diff.js';
+import { buildViewGraph } from './graph.js';
+import { buildViewTableOfContents } from './table-of-contents.js';
 import { emptyViewGitSnapshot, findViewGitRepository, readViewGitSnapshot, sameViewGitSnapshot, } from './git.js';
-import { createMarkdownWikiLinkResolver, getViewSource, ViewDocumentNotFoundError, } from './repository.js';
-import { buildViewReferenceIndex, parseViewMarkdownFile, renderSectionBackReferences, } from './references.js';
+import { DEFAULT_VIEW_LOGO_TEXT } from './protocol.js';
+import { createMarkdownWikiLinkResolver, getViewExternal, getViewSource, ViewDocumentNotFoundError, ViewSourceNotFoundError, } from './repository.js';
+import { buildViewReferenceIndex, renderSectionBackReferences, } from './references.js';
+import { rewriteLocalFileLink } from './source-target.js';
 const DEFAULT_DEBOUNCE_MS = 75;
+const DEFAULT_GIT_POLL_MS = 2_000;
+const EXTERNAL_REFRESH_PATH = '@lat-external-refresh';
+const DOCUMENT_EDIT_WRITE_ATTEMPTS = 3;
+const DOCUMENT_EDIT_TEMP_PREFIX = '.lat-edit-';
 function isInside(root, candidate) {
     const rel = relative(root, candidate);
     return (rel === '' ||
@@ -21,8 +34,16 @@ function projectPath(projectRoot, path) {
     const normalized = isAbsolute(path) ? relative(projectRoot, path) : path;
     return toPosix(normalized).replace(/^\.\//, '');
 }
+function isInternalLatCachePath(path, latPath) {
+    const cachePath = latPath ? `${latPath}/.cache` : '.cache';
+    return path === cachePath || path.startsWith(`${cachePath}/`);
+}
+function excludedCodePath(projectRoot, path, excludedPaths) {
+    const absolutePath = resolve(projectRoot, path);
+    return excludedPaths.some((root) => isInside(resolve(root), absolutePath));
+}
 function sourcePath(path) {
-    return SOURCE_EXTENSIONS.has(extname(path).toLowerCase());
+    return isSourceFileExtension(extname(path).toLowerCase());
 }
 function obviouslyIgnoredCodePath(path, latPath) {
     const parts = path.split('/');
@@ -55,7 +76,10 @@ async function loadCodeReferenceFiles(projectRoot, refs) {
     const files = new Map();
     await Promise.all([...refsByFile].map(async ([path, fileRefs]) => {
         try {
-            const content = await readFile(resolve(projectRoot, path), 'utf8');
+            const safePath = await repositoryFilePath(projectRoot, path);
+            if (!safePath)
+                return;
+            const content = await readFile(safePath, 'utf8');
             files.set(path, { path, lines: content.split('\n'), refs: fileRefs });
         }
         catch {
@@ -64,22 +88,61 @@ async function loadCodeReferenceFiles(projectRoot, refs) {
     }));
     return files;
 }
-async function scanCodeState(projectRoot) {
-    const scan = await scanCodeRefs(projectRoot);
-    const scope = new Set(scan.files.map((path) => projectPath(projectRoot, path)));
+async function scanCodeState(projectRoot, excludedPaths = [], publishable) {
+    const discovery = createCodeReferenceDiscovery(projectRoot);
+    const [scan, sourceFiles] = await Promise.all([
+        discovery.scan(),
+        discovery.listSourceFiles(),
+    ]);
+    const allowed = (path) => !excludedCodePath(projectRoot, path, excludedPaths);
+    const candidates = sourceFiles.filter(allowed);
+    const decisions = await Promise.all(candidates.map((path) => publishable?.(projectPath(projectRoot, path)) ?? true));
+    const files = candidates.filter((_, index) => decisions[index]);
+    const scope = new Set(files.map((path) => projectPath(projectRoot, path)));
+    const refs = scan.refs.filter((ref) => allowed(ref.file) && scope.has(ref.file));
     return {
-        files: await loadCodeReferenceFiles(projectRoot, scan.refs),
+        files: await loadCodeReferenceFiles(projectRoot, refs),
         scope,
     };
 }
-function viewIndex(latDir, paths, diagnostics, git) {
-    const files = [...paths].sort();
+function viewIndex(latDir, markdownFiles, diagnostics, git, references, external) {
+    const files = [...markdownFiles.keys()].sort();
+    const externalFiles = new Map();
+    for (const target of references.externalByTarget.keys()) {
+        try {
+            const parsed = external.parse(target);
+            if (!parsed)
+                continue;
+            const hash = parsed.identity.indexOf('#');
+            const baseTarget = hash === -1 ? parsed.identity : parsed.identity.slice(0, hash);
+            externalFiles.set(baseTarget, {
+                handle: parsed.handle,
+                path: parsed.resolvedPath,
+                target: baseTarget,
+            });
+        }
+        catch {
+            // Invalid external targets remain diagnostics, not sidebar entries.
+        }
+    }
     const directoryName = basename(latDir);
     const indexName = directoryName.endsWith('.md')
         ? directoryName
         : `${directoryName}.md`;
+    const directoryOrder = Object.fromEntries([...markdownFiles].flatMap(([path, file]) => {
+        const separator = path.lastIndexOf('/');
+        const directory = separator === -1 ? '' : path.slice(0, separator);
+        const name = directory ? basename(directory) : directoryName;
+        const filename = name.endsWith('.md') ? name : `${name}.md`;
+        if (path.slice(separator + 1) !== filename)
+            return [];
+        return [[directory, file.indexEntries]];
+    }));
     return {
         files,
+        directoryOrder,
+        externalFiles: [...externalFiles.values()].sort((left, right) => left.handle.localeCompare(right.handle) ||
+            left.path.localeCompare(right.path)),
         entry: files.includes(indexName) ? indexName : (files[0] ?? ''),
         errorCounts: Object.fromEntries([...diagnostics]
             .filter(([, errors]) => errors.length > 0)
@@ -89,21 +152,37 @@ function viewIndex(latDir, paths, diagnostics, git) {
                 files: Object.fromEntries([...git.files].map(([path, file]) => [path, file.status])),
             }
             : null,
+        logoText: DEFAULT_VIEW_LOGO_TEXT,
     };
 }
-async function buildSnapshot(latDir, projectRoot, markdownFiles, codeFiles, git, generation, markdownGeneration) {
+async function buildSnapshot(latDir, projectRoot, markdownFiles, codeFiles, git, generation, markdownGeneration, options) {
     const files = new Map([...markdownFiles].sort(([left], [right]) => left.localeCompare(right)));
     const allSections = [...files.values()].flatMap((file) => file.sections);
-    const diagnostics = await buildViewDiagnostics(files.values(), codeFiles.values(), allSections, projectRoot);
+    const external = await createExternalResolver(latDir, projectRoot, {
+        ignoreLocal: options.externalIgnoreLocal,
+        ca: options.externalCa,
+    });
+    await external.reconcile();
+    const diagnostics = await buildViewDiagnostics(files.values(), codeFiles.values(), allSections, projectRoot, external, latDir);
+    const references = buildViewReferenceIndex(files.values(), codeFiles.values(), allSections, (target) => {
+        try {
+            return external.parse(target)?.identity ?? null;
+        }
+        catch {
+            return target;
+        }
+    });
     return {
         generation,
         markdownGeneration,
         files,
         allSections,
-        references: buildViewReferenceIndex(files.values(), codeFiles.values(), allSections),
+        references,
+        graph: buildViewGraph(files.values(), codeFiles.values(), allSections, diagnostics, git, generation, references, external),
         diagnostics,
         git,
-        index: viewIndex(latDir, [...files.keys()], diagnostics, git),
+        index: viewIndex(latDir, files, diagnostics, git, references, external),
+        external,
     };
 }
 /** Own the immutable, incrementally refreshed project snapshot for `lat ui`. */
@@ -119,9 +198,13 @@ export class ViewStore {
     ignoredCodePaths = new Set();
     listeners = new Set();
     watcher = null;
+    externalWatchers = [];
     pendingPaths = new Set();
     debounceTimer = null;
+    gitPollTimer = null;
+    gitPollQueued = false;
     refreshTail = Promise.resolve();
+    editTail = Promise.resolve();
     closed = false;
     constructor(latDir, projectRoot, realLatDir, snapshot, codeFiles, codeScope, gitRepository, options) {
         this.latDir = latDir;
@@ -140,6 +223,7 @@ export class ViewStore {
         return this.snapshotValue.markdownGeneration;
     }
     startWatching() {
+        this.startGitPolling();
         if (this.options.watch === false || this.watcher)
             return;
         try {
@@ -151,6 +235,29 @@ export class ViewStore {
         catch (error) {
             process.stderr.write(`lat ui watcher: ${error.message}\n`);
         }
+        this.refreshExternalWatchers();
+    }
+    refreshExternalWatchers() {
+        for (const watcher of this.externalWatchers)
+            watcher.close();
+        this.externalWatchers = [];
+        if (this.options.watch === false)
+            return;
+        const paths = new Set([...this.snapshotValue.external.snapshot.sources.values()]
+            .map((source) => source.localPath)
+            .filter((path) => Boolean(path)));
+        for (const path of paths) {
+            try {
+                const watcher = watchFiles(path, { recursive: true }, () => this.scheduleRefresh(EXTERNAL_REFRESH_PATH));
+                watcher.on('error', (error) => {
+                    process.stderr.write(`lat ui external watcher: ${error.message}\n`);
+                });
+                this.externalWatchers.push(watcher);
+            }
+            catch (error) {
+                process.stderr.write(`lat ui external watcher: ${error.message}\n`);
+            }
+        }
     }
     subscribe(listener) {
         this.listeners.add(listener);
@@ -159,6 +266,18 @@ export class ViewStore {
     getIndex() {
         return this.snapshotValue.index;
     }
+    getGraph() {
+        return this.snapshotValue.graph;
+    }
+    async renderSectionOutput(markdown, sectionId) {
+        const snapshot = this.snapshotValue;
+        const section = snapshot.allSections.find((candidate) => candidate.id.toLowerCase() === sectionId.toLowerCase());
+        const requestedPath = section
+            ? toPosix(relative(this.latDir, resolve(this.projectRoot, section.filePath)))
+            : 'section-output.md';
+        const resolver = await createMarkdownWikiLinkResolver(this.latDir, requestedPath, snapshot.allSections, snapshot.references, snapshot.external, this.options.publishable);
+        return (await renderMarkdown(markdown, requestedPath, resolver)).tree;
+    }
     async getDocument(requestedPath) {
         if (!requestedPath ||
             requestedPath.includes('\\') ||
@@ -171,33 +290,152 @@ export class ViewStore {
         if (!file) {
             throw new ViewDocumentNotFoundError('Markdown document not found');
         }
-        const resolver = await createMarkdownWikiLinkResolver(this.latDir, requestedPath, snapshot.allSections);
-        const rendered = await renderMarkdown(file.content, requestedPath, resolver, { errors: [...(snapshot.diagnostics.get(requestedPath) ?? [])] }, file.tree);
+        const resolver = await createMarkdownWikiLinkResolver(this.latDir, requestedPath, snapshot.allSections, snapshot.references, snapshot.external, this.options.publishable);
+        const rendered = await renderMarkdown(file.content, requestedPath, resolver, {
+            errors: [...(snapshot.diagnostics.get(requestedPath) ?? [])],
+            rewriteMarkdownLink: (url) => rewriteLocalFileLink(url, requestedPath),
+        });
+        const errors = [...(snapshot.diagnostics.get(requestedPath) ?? [])];
         const gitFile = snapshot.git.files.get(requestedPath);
-        const gitRendered = gitFile
-            ? await renderMarkdown(file.content, requestedPath, resolver, { errors: [...(snapshot.diagnostics.get(requestedPath) ?? [])] }, buildGitDiffTree(gitFile.baseContent, file.content, file.tree))
+        const gitTree = gitFile
+            ? buildGitDiffTree(gitFile.baseContent, file.content)
+            : null;
+        const gitRendered = gitTree
+            ? await renderMarkdown(file.content, requestedPath, resolver, {
+                errors,
+                rewriteMarkdownLink: (url) => rewriteLocalFileLink(url, requestedPath),
+            }, gitTree)
             : null;
-        const errors = [...(snapshot.diagnostics.get(requestedPath) ?? [])];
         return {
             path: requestedPath,
             ...rendered,
-            gitHtml: gitRendered?.html ?? null,
+            gitTree: gitRendered?.tree ?? null,
+            tableOfContents: buildViewTableOfContents(file.sections, file.headingTitles, { errors, gitTree }),
+            graphNodeIds: Object.fromEntries(snapshot.graph.nodes
+                .filter((node) => node.documentPath === requestedPath && node.kind === 'document')
+                .map((node) => {
+                const hash = new URL(node.url, 'http://lat.local').hash.slice(1);
+                let headingId = hash;
+                try {
+                    headingId = decodeURIComponent(hash);
+                }
+                catch {
+                    // Keep malformed fragments as-is; they cannot collide with valid ids.
+                }
+                return [headingId, node.id];
+            })),
             errors,
-            backReferences: await renderSectionBackReferences(snapshot.references, file.sections, this.latDir, this.projectRoot, (path) => createMarkdownWikiLinkResolver(this.latDir, path, snapshot.allSections)),
+            backReferences: await renderSectionBackReferences(snapshot.references, file.sections, this.latDir, this.projectRoot, (path) => createMarkdownWikiLinkResolver(this.latDir, path, snapshot.allSections, snapshot.references, snapshot.external, this.options.publishable)),
             frontmatter: {
-                requireCodeMention: parseFrontmatter(file.content).requireCodeMention === true,
+                requireCodeMention: file.frontmatter.requireCodeMention === true,
             },
         };
     }
-    getSource(requestedPath, requestedSymbol = '', origin, requestedLine = 0) {
+    async editableDocumentPath(requestedPath) {
+        if (!requestedPath ||
+            requestedPath.includes('\\') ||
+            isAbsolute(requestedPath) ||
+            !requestedPath.toLowerCase().endsWith('.md') ||
+            !this.snapshotValue.files.has(requestedPath)) {
+            throw new ViewDocumentNotFoundError('Markdown document not found');
+        }
+        let realFile;
+        try {
+            realFile = await realpath(resolve(this.latDir, requestedPath));
+        }
+        catch {
+            throw new ViewDocumentNotFoundError('Markdown document not found');
+        }
+        if (!isInside(this.realLatDir, realFile)) {
+            throw new ViewDocumentNotFoundError('Markdown document not found');
+        }
+        return realFile;
+    }
+    async getDocumentSource(requestedPath) {
+        const path = await this.editableDocumentPath(requestedPath);
+        return { path: requestedPath, content: await readFile(path, 'utf8') };
+    }
+    async getDocumentResource(requestedPath) {
+        if (this.options.publishable &&
+            !(await this.options.publishable(projectPath(this.projectRoot, resolve(this.latDir, requestedPath)))))
+            throw new ViewDocumentNotFoundError(`Resource is excluded from publication: ${requestedPath}`);
+        if (!requestedPath ||
+            requestedPath.includes('\\') ||
+            isAbsolute(requestedPath) ||
+            requestedPath.toLowerCase().endsWith('.md')) {
+            throw new ViewDocumentNotFoundError('Document resource not found');
+        }
+        let path;
+        try {
+            path = await realpath(resolve(this.latDir, requestedPath));
+            if (!isInside(this.realLatDir, path) || !(await stat(path)).isFile()) {
+                throw new ViewDocumentNotFoundError('Document resource not found');
+            }
+            return await readFile(path);
+        }
+        catch (error) {
+            if (error instanceof ViewDocumentNotFoundError)
+                throw error;
+            throw new ViewDocumentNotFoundError('Document resource not found');
+        }
+    }
+    editDocument(requestedPath, baseContent, editedContent) {
+        const operation = this.editTail.then(async () => {
+            const path = await this.editableDocumentPath(requestedPath);
+            for (let attempt = 0; attempt < DOCUMENT_EDIT_WRITE_ATTEMPTS; attempt++) {
+                const currentContent = await readFile(path, 'utf8');
+                const edit = applyDocumentEdit(baseContent, editedContent, currentContent);
+                if (edit.content === currentContent) {
+                    return { path: requestedPath, ...edit };
+                }
+                const currentStat = await stat(path);
+                const temporaryPath = resolve(this.latDir, `${DOCUMENT_EDIT_TEMP_PREFIX}${process.pid}-${randomUUID()}.tmp`);
+                try {
+                    await writeFile(temporaryPath, edit.content, {
+                        encoding: 'utf8',
+                        flag: 'wx',
+                        mode: currentStat.mode,
+                    });
+                    if ((await readFile(path, 'utf8')) !== currentContent)
+                        continue;
+                    await rename(temporaryPath, path);
+                }
+                finally {
+                    await rm(temporaryPath, { force: true });
+                }
+                await this.refresh([resolve(this.latDir, requestedPath)]);
+                return { path: requestedPath, ...edit };
+            }
+            throw new ViewDocumentConflictError('Could not save because this file kept changing. Your edits are still in the editor.');
+        });
+        this.editTail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async getSource(requestedPath, requestedSymbol = '', origin, requestedLine = 0) {
+        if (this.options.publishable &&
+            !(await this.options.publishable(requestedPath)))
+            throw new ViewSourceNotFoundError(`Source is excluded from publication: ${requestedPath}`);
         const snapshot = this.snapshotValue;
-        return getViewSource(this.latDir, this.projectRoot, requestedPath, requestedSymbol, origin, requestedLine, snapshot.allSections, snapshot.references);
+        return getViewSource(this.latDir, this.projectRoot, requestedPath, requestedSymbol, origin, requestedLine, snapshot.allSections, snapshot.references, this.options.publishable);
+    }
+    getExternal(target) {
+        const snapshot = this.snapshotValue;
+        return getViewExternal(this.latDir, this.projectRoot, target, snapshot.external, snapshot.allSections, snapshot.references, this.options.publishable);
     }
     refresh(paths) {
         if (this.closed)
             return Promise.resolve();
-        const normalized = paths.map((path) => path ? projectPath(this.projectRoot, path) : '');
-        const refresh = this.refreshTail.then(() => this.applyRefresh(normalized));
+        const latPath = projectPath(this.projectRoot, this.latDir);
+        const normalized = paths
+            .map((path) => (path ? projectPath(this.projectRoot, path) : ''))
+            .filter((path) => !isInternalLatCachePath(path, latPath));
+        if (paths.length > 0 && normalized.length === 0) {
+            return Promise.resolve();
+        }
+        return this.queueRefresh(normalized, false);
+    }
+    queueRefresh(paths, pollGit) {
+        const refresh = this.refreshTail.then(() => this.applyRefresh(paths, pollGit));
         this.refreshTail = refresh.catch(() => { });
         return refresh;
     }
@@ -206,15 +444,35 @@ export class ViewStore {
         if (this.debounceTimer)
             clearTimeout(this.debounceTimer);
         this.debounceTimer = null;
+        if (this.gitPollTimer)
+            clearInterval(this.gitPollTimer);
+        this.gitPollTimer = null;
         this.watcher?.close();
         this.watcher = null;
+        for (const watcher of this.externalWatchers)
+            watcher.close();
+        this.externalWatchers = [];
+        await this.editTail;
         await this.refreshTail;
         this.listeners.clear();
     }
     scheduleRefresh(path) {
         if (this.closed)
             return;
-        this.pendingPaths.add(path ? projectPath(this.projectRoot, path) : '');
+        if (path !== EXTERNAL_REFRESH_PATH &&
+            basename(path).startsWith(DOCUMENT_EDIT_TEMP_PREFIX) &&
+            path.endsWith('.tmp')) {
+            return;
+        }
+        const normalizedPath = path === EXTERNAL_REFRESH_PATH
+            ? path
+            : path
+                ? projectPath(this.projectRoot, path)
+                : '';
+        const latPath = projectPath(this.projectRoot, this.latDir);
+        if (isInternalLatCachePath(normalizedPath, latPath))
+            return;
+        this.pendingPaths.add(normalizedPath);
         if (this.debounceTimer)
             clearTimeout(this.debounceTimer);
         this.debounceTimer = setTimeout(() => {
@@ -226,6 +484,24 @@ export class ViewStore {
             });
         }, this.options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
     }
+    startGitPolling() {
+        const interval = this.options.gitPollMs ?? DEFAULT_GIT_POLL_MS;
+        if (!this.gitRepository || interval <= 0 || this.gitPollTimer)
+            return;
+        this.gitPollTimer = setInterval(() => {
+            if (this.closed || this.gitPollQueued)
+                return;
+            this.gitPollQueued = true;
+            void this.queueRefresh([], true)
+                .catch((error) => {
+                process.stderr.write(`lat ui git: ${error.message}\n`);
+            })
+                .finally(() => {
+                this.gitPollQueued = false;
+            });
+        }, interval);
+        this.gitPollTimer.unref();
+    }
     async readMarkdownFile(absolutePath) {
         let realFile;
         try {
@@ -236,12 +512,13 @@ export class ViewStore {
         }
         if (!isInside(this.realLatDir, realFile))
             return null;
-        const content = await readFile(realFile, 'utf8');
-        return parseViewMarkdownFile(absolutePath, content, this.latDir, this.projectRoot);
+        return analyzeMarkdownPath(absolutePath, this.latDir, this.projectRoot);
     }
-    async applyRefresh(paths) {
+    async applyRefresh(paths, pollGit) {
         const fullRefresh = paths.includes('');
         const latPath = projectPath(this.projectRoot, this.latDir);
+        const externalChanged = paths.includes(EXTERNAL_REFRESH_PATH) ||
+            paths.includes(`${latPath}/config.local.yaml`);
         const touchesMarkdown = fullRefresh ||
             paths.some((path) => path === latPath || path.startsWith(`${latPath}/`));
         let markdownFiles = new Map(this.snapshotValue.files);
@@ -298,7 +575,7 @@ export class ViewStore {
             }
             linkedResourceChanged = paths.some((path) => path.startsWith(`${latPath}/`) && !path.toLowerCase().endsWith('.md'));
         }
-        if (touchesMarkdown && this.gitRepository) {
+        if ((touchesMarkdown || pollGit) && this.gitRepository) {
             try {
                 const nextGit = await readViewGitSnapshot(this.gitRepository, markdownFiles);
                 gitChanged = !sameViewGitSnapshot(git, nextGit);
@@ -308,12 +585,15 @@ export class ViewStore {
                 process.stderr.write(`lat ui git: ${error.message}\n`);
             }
         }
-        const codePaths = paths.filter((path) => path && sourcePath(path) && !obviouslyIgnoredCodePath(path, latPath));
+        const codePaths = paths.filter((path) => path &&
+            sourcePath(path) &&
+            !obviouslyIgnoredCodePath(path, latPath) &&
+            !excludedCodePath(this.projectRoot, path, this.options.codeExcludePaths ?? []));
         const refreshCodeScope = fullRefresh ||
             paths.some((path) => path === '.gitignore' || path.endsWith('/.gitignore')) ||
             codePaths.some((path) => !this.codeScope.has(path) && !this.ignoredCodePaths.has(path));
         if (refreshCodeScope) {
-            const nextCode = await scanCodeState(this.projectRoot);
+            const nextCode = await scanCodeState(this.projectRoot, this.options.codeExcludePaths, this.options.publishable);
             codeFiles = nextCode.files;
             this.codeScope = nextCode.scope;
             this.ignoredCodePaths.clear();
@@ -352,10 +632,12 @@ export class ViewStore {
         if (!markdownChanged &&
             !codeChanged &&
             !gitChanged &&
-            !linkedResourceChanged)
+            !linkedResourceChanged &&
+            !externalChanged)
             return;
         this.codeFiles = codeFiles;
-        this.snapshotValue = await buildSnapshot(this.latDir, this.projectRoot, markdownFiles, codeFiles, git, this.snapshotValue.generation + 1, this.snapshotValue.markdownGeneration + (markdownChanged ? 1 : 0));
+        this.snapshotValue = await buildSnapshot(this.latDir, this.projectRoot, markdownFiles, codeFiles, git, this.snapshotValue.generation + 1, this.snapshotValue.markdownGeneration + (markdownChanged ? 1 : 0), this.options);
+        this.refreshExternalWatchers();
         const change = {
             generation: this.snapshotValue.generation,
             markdownGeneration: this.snapshotValue.markdownGeneration,
@@ -369,7 +651,7 @@ export async function createViewStore(latDir, projectRoot, options = {}) {
     const [realLatDir, markdownPaths, codeState, gitRepository] = await Promise.all([
         realpath(latDir),
         listLatticeFiles(latDir),
-        scanCodeState(projectRoot),
+        scanCodeState(projectRoot, options.codeExcludePaths, options.publishable),
         options.git === false
             ? Promise.resolve(null)
             : findViewGitRepository(projectRoot, latDir),
@@ -382,8 +664,7 @@ export async function createViewStore(latDir, projectRoot, options = {}) {
         const realFile = await realpath(absolutePath);
         if (!isInside(realLatDir, realFile))
             return;
-        const content = await readFile(realFile, 'utf8');
-        const parsed = parseViewMarkdownFile(absolutePath, content, latDir, projectRoot);
+        const parsed = await analyzeMarkdownPath(absolutePath, latDir, projectRoot);
         markdownFiles.set(parsed.path, parsed);
     }));
     if (markdownFiles.size === 0) {
@@ -398,7 +679,7 @@ export async function createViewStore(latDir, projectRoot, options = {}) {
             process.stderr.write(`lat ui git: ${error.message}\n`);
         }
     }
-    const store = new ViewStore(latDir, projectRoot, realLatDir, await buildSnapshot(latDir, projectRoot, markdownFiles, codeState.files, git, 0, 0), codeState.files, codeState.scope, gitRepository, options);
+    const store = new ViewStore(latDir, projectRoot, realLatDir, await buildSnapshot(latDir, projectRoot, markdownFiles, codeState.files, git, 0, 0, options), codeState.files, codeState.scope, gitRepository, options);
     store.startWatching();
     return store;
 }

package/dist/src/view/table-of-contents.d.ts

@@ -0,0 +1,9 @@
+import type { Root } from 'mdast';
+import { type Section } from '@plebeiantech/lat.md-core/lattice-model';
+import type { ViewDocumentError, ViewDocumentTocItem } from './protocol.js';
+export type ViewTableOfContentsOptions = {
+    errors?: readonly ViewDocumentError[];
+    gitTree?: Root | null;
+};
+/** Project rendered headings into the document's local navigation. */
+export declare function buildViewTableOfContents(sections: Section[], titles: readonly string[], options?: ViewTableOfContentsOptions): ViewDocumentTocItem[];

package/dist/src/view/table-of-contents.js

@@ -0,0 +1,83 @@
+import { flattenSections, } from '@plebeiantech/lat.md-core/lattice-model';
+function sectionAtLine(sections, line) {
+    let owner = null;
+    for (const section of sections) {
+        if (line < section.startLine || line > section.endLine)
+            continue;
+        if (!owner || section.depth >= owner.depth)
+            owner = section;
+    }
+    return owner;
+}
+function classNames(node) {
+    const value = node.data?.hProperties?.className;
+    if (Array.isArray(value))
+        return value.map(String);
+    return value ? [String(value)] : [];
+}
+function hasGitChanges(node) {
+    if (classNames(node).some((name) => name.startsWith('git-'))) {
+        return true;
+    }
+    if (!('children' in node) || !Array.isArray(node.children))
+        return false;
+    return node.children.some((child) => hasGitChanges(child));
+}
+function gitChangedSections(sections, tree) {
+    const changed = new Set();
+    if (!tree)
+        return changed;
+    const headingStack = [];
+    const rootSection = sections[0] ?? null;
+    for (const node of tree.children) {
+        if (node.type === 'heading') {
+            while (headingStack.length > 0 &&
+                headingStack[headingStack.length - 1].depth >= node.depth) {
+                headingStack.pop();
+            }
+            const line = node.position?.start.line;
+            const section = line
+                ? (sections.find((candidate) => candidate.startLine === line && candidate.depth === node.depth) ?? null)
+                : null;
+            if (section)
+                headingStack.push(section);
+            if (hasGitChanges(node)) {
+                const owner = section ?? headingStack[headingStack.length - 1] ?? rootSection;
+                if (owner)
+                    changed.add(owner.id);
+            }
+            continue;
+        }
+        if (!hasGitChanges(node))
+            continue;
+        const line = node.position?.start.line;
+        const owner = (line ? sectionAtLine(sections, line) : null) ??
+            headingStack[headingStack.length - 1] ??
+            rootSection;
+        if (owner)
+            changed.add(owner.id);
+    }
+    return changed;
+}
+/** Project rendered headings into the document's local navigation. */
+export function buildViewTableOfContents(sections, titles, options = {}) {
+    const flatSections = flattenSections(sections);
+    const errorCounts = new Map();
+    for (const error of options.errors ?? []) {
+        const owner = sectionAtLine(flatSections, error.line);
+        if (owner)
+            errorCounts.set(owner.id, (errorCounts.get(owner.id) ?? 0) + 1);
+    }
+    const gitChanges = gitChangedSections(flatSections, options.gitTree);
+    return flatSections.flatMap((section, index) => section.githubSlug
+        ? [
+            {
+                id: section.githubSlug,
+                title: titles[index] || section.heading,
+                depth: section.depth,
+                errorCount: errorCounts.get(section.id) ?? 0,
+                hasGitChanges: gitChanges.has(section.id),
+            },
+        ]
+        : []);
+}

package/dist/src/view/vercel-build.d.ts

@@ -0,0 +1,24 @@
+type FileTraceResult = {
+    fileList: Set<string>;
+    warnings: Set<Error>;
+};
+export type VercelBuildDependencies = {
+    traceFiles: (files: string[], options: {
+        base: string;
+        conditions: string[];
+        exportsOnly: boolean;
+        processCwd: string;
+    }) => Promise<FileTraceResult>;
+};
+export type VercelBuildOptions = {
+    force?: boolean;
+    warn?: (message: string) => void;
+};
+export type VercelBuildResult = {
+    files: number;
+    functionPath: string;
+    outputDir: string;
+};
+/** Convert an installed portable Lat UI server into Vercel Build Output API v3. */
+export declare function buildVercelOutput(requestedArtifact: string, requestedOutput?: string, options?: VercelBuildOptions, dependencies?: VercelBuildDependencies): Promise<VercelBuildResult>;
+export {};