@plebeiantech/lat.md 0.12.3-fork.1

package/dist/src/view/server.js

@@ -0,0 +1,233 @@
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ViewDocumentNotFoundError, ViewSourceNotFoundError, } from './repository.js';
+import { createViewSearch } from './search.js';
+import { createViewStore } from './store.js';
+const DEFAULT_HOST = '127.0.0.1';
+const defaultClientDir = fileURLToPath(new URL('./client/', import.meta.url));
+function documentUrl(path) {
+    return `/docs/${path.split('/').map(encodeURIComponent).join('/')}`;
+}
+function setSecurityHeaders(res) {
+    res.setHeader('Content-Security-Policy', "default-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'");
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+}
+function send(res, status, contentType, body, headOnly = false) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', contentType);
+    res.setHeader('Content-Length', Buffer.byteLength(body));
+    res.end(headOnly ? undefined : body);
+}
+function sendJson(res, status, value, headOnly) {
+    res.setHeader('Cache-Control', 'no-store');
+    send(res, status, 'application/json; charset=utf-8', JSON.stringify(value), headOnly);
+}
+function contentType(path) {
+    switch (extname(path)) {
+        case '.css':
+            return 'text/css; charset=utf-8';
+        case '.html':
+            return 'text/html; charset=utf-8';
+        case '.js':
+            return 'text/javascript; charset=utf-8';
+        case '.json':
+            return 'application/json; charset=utf-8';
+        case '.svg':
+            return 'image/svg+xml';
+        case '.woff2':
+            return 'font/woff2';
+        default:
+            return 'application/octet-stream';
+    }
+}
+function clientPath(clientDir, requestPath) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(requestPath);
+    }
+    catch {
+        return null;
+    }
+    const candidate = resolve(clientDir, `.${decoded}`);
+    const rel = relative(clientDir, candidate);
+    if (rel === '..' || rel.startsWith(`..${sep}`))
+        return null;
+    return candidate;
+}
+async function sendClientFile(res, path, headOnly, immutable = false) {
+    try {
+        const body = await readFile(path);
+        res.setHeader('Cache-Control', immutable ? 'public, max-age=31536000, immutable' : 'no-cache');
+        send(res, 200, contentType(path), body, headOnly);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
+    }
+}
+/** Start the read-only loopback server used by `lat ui`. */
+export async function startViewServer(ctx, options = {}) {
+    const host = options.host ?? DEFAULT_HOST;
+    const clientDir = options.clientDir ?? defaultClientDir;
+    const store = await createViewStore(ctx.latDir, ctx.projectRoot, {
+        git: options.git,
+        watch: options.watch,
+    });
+    const search = options.search ??
+        createViewSearch(ctx.latDir, undefined, () => store.markdownGeneration);
+    const eventClients = new Set();
+    const broadcastChange = (change) => {
+        const message = `event: change\ndata: ${JSON.stringify(change)}\n\n`;
+        for (const client of eventClients)
+            client.write(message);
+    };
+    const unsubscribeStore = store.subscribe(broadcastChange);
+    const server = createServer((req, res) => {
+        void (async () => {
+            setSecurityHeaders(res);
+            const method = req.method ?? 'GET';
+            const headOnly = method === 'HEAD';
+            if (method !== 'GET' && !headOnly) {
+                res.setHeader('Allow', 'GET, HEAD');
+                send(res, 405, 'text/plain; charset=utf-8', 'Method not allowed');
+                return;
+            }
+            const url = new URL(req.url ?? '/', `http://${host}`);
+            if (url.pathname === '/') {
+                const entry = store.getIndex().entry;
+                if (!entry) {
+                    send(res, 404, 'text/plain; charset=utf-8', 'No Markdown files found');
+                    return;
+                }
+                res.statusCode = 302;
+                res.setHeader('Location', documentUrl(entry));
+                res.end();
+                return;
+            }
+            if (url.pathname === '/api/index') {
+                sendJson(res, 200, store.getIndex(), headOnly);
+                return;
+            }
+            if (url.pathname === '/api/events') {
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+                res.setHeader('Cache-Control', 'no-cache');
+                res.setHeader('Connection', 'keep-alive');
+                res.flushHeaders();
+                if (headOnly) {
+                    res.end();
+                    return;
+                }
+                eventClients.add(res);
+                res.write(`event: ready\ndata: ${JSON.stringify({ generation: store.snapshot.generation, markdownGeneration: store.markdownGeneration })}\n\n`);
+                req.once('close', () => eventClients.delete(res));
+                return;
+            }
+            if (url.pathname === '/api/document') {
+                const path = url.searchParams.get('path') ?? '';
+                try {
+                    sendJson(res, 200, await store.getDocument(path), headOnly);
+                }
+                catch (error) {
+                    if (!(error instanceof ViewDocumentNotFoundError))
+                        throw error;
+                    sendJson(res, 404, { error: error.message }, headOnly);
+                }
+                return;
+            }
+            if (url.pathname === '/api/search') {
+                const query = (url.searchParams.get('query') ?? '').trim();
+                if (query.length > 500) {
+                    sendJson(res, 400, { error: 'Search query is too long' }, headOnly);
+                    return;
+                }
+                sendJson(res, 200, await search(query), headOnly);
+                return;
+            }
+            if (url.pathname === '/api/source') {
+                const path = url.searchParams.get('path') ?? '';
+                const symbol = url.searchParams.get('symbol') ?? '';
+                const from = url.searchParams.get('from') ?? '';
+                const parsedLine = Number(url.searchParams.get('line'));
+                const parsedFocusLine = Number(url.searchParams.get('at'));
+                const focusLine = Number.isInteger(parsedFocusLine) && parsedFocusLine > 0
+                    ? parsedFocusLine
+                    : 0;
+                const origin = from && Number.isInteger(parsedLine) && parsedLine > 0
+                    ? { sectionId: from, line: parsedLine }
+                    : undefined;
+                try {
+                    sendJson(res, 200, await store.getSource(path, symbol, origin, focusLine), headOnly);
+                }
+                catch (error) {
+                    if (!(error instanceof ViewSourceNotFoundError))
+                        throw error;
+                    sendJson(res, 404, { error: error.message }, headOnly);
+                }
+                return;
+            }
+            if (url.pathname.startsWith('/assets/')) {
+                const path = clientPath(clientDir, url.pathname);
+                if (!path) {
+                    send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
+                    return;
+                }
+                await sendClientFile(res, path, headOnly, true);
+                return;
+            }
+            if (url.pathname === '/search' ||
+                url.pathname.startsWith('/docs/') ||
+                url.pathname.startsWith('/code/')) {
+                await sendClientFile(res, join(clientDir, 'index.html'), headOnly);
+                return;
+            }
+            send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
+        })().catch((error) => {
+            if (res.headersSent) {
+                res.destroy(error);
+                return;
+            }
+            sendJson(res, 500, { error: error.message }, false);
+        });
+    });
+    try {
+        await new Promise((resolveListen, reject) => {
+            server.once('error', reject);
+            server.listen(options.port ?? 0, host, () => {
+                server.off('error', reject);
+                resolveListen();
+            });
+        });
+    }
+    catch (error) {
+        unsubscribeStore();
+        await store.close();
+        throw error;
+    }
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        await new Promise((resolveClose) => server.close(() => resolveClose()));
+        unsubscribeStore();
+        await store.close();
+        throw new Error('Could not determine lat ui server address');
+    }
+    return {
+        server,
+        store,
+        url: `http://${host}:${address.port}/`,
+        close: async () => {
+            unsubscribeStore();
+            for (const client of eventClients)
+                client.end();
+            eventClients.clear();
+            await store.close();
+            await new Promise((resolveClose, reject) => {
+                server.close((error) => (error ? reject(error) : resolveClose()));
+            });
+        },
+    };
+}

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

@@ -0,0 +1,57 @@
+import { type Section } from '../lattice.js';
+import { type ViewGitRepository, type ViewGitSnapshot } from './git.js';
+import type { ViewDocument, ViewDocumentError, ViewIndex, ViewProjectChange, ViewSourceDocument } from './protocol.js';
+import { type ViewCodeReferenceFile, type ViewParsedMarkdownFile, type ViewReferenceIndex } from './references.js';
+export type ViewProjectSnapshot = {
+    generation: number;
+    markdownGeneration: number;
+    files: ReadonlyMap<string, ViewParsedMarkdownFile>;
+    allSections: Section[];
+    references: ViewReferenceIndex;
+    diagnostics: ReadonlyMap<string, readonly ViewDocumentError[]>;
+    git: ViewGitSnapshot;
+    index: ViewIndex;
+};
+export type ViewStoreOptions = {
+    debounceMs?: number;
+    git?: boolean;
+    watch?: boolean;
+};
+type ViewStoreListener = (change: ViewProjectChange) => void;
+/** Own the immutable, incrementally refreshed project snapshot for `lat ui`. */
+export declare class ViewStore {
+    readonly latDir: string;
+    readonly projectRoot: string;
+    private readonly realLatDir;
+    private readonly gitRepository;
+    private readonly options;
+    private snapshotValue;
+    private codeFiles;
+    private codeScope;
+    private ignoredCodePaths;
+    private listeners;
+    private watcher;
+    private pendingPaths;
+    private debounceTimer;
+    private refreshTail;
+    private closed;
+    constructor(latDir: string, projectRoot: string, realLatDir: string, snapshot: ViewProjectSnapshot, codeFiles: Map<string, ViewCodeReferenceFile>, codeScope: Set<string>, gitRepository: ViewGitRepository | null, options: ViewStoreOptions);
+    get snapshot(): ViewProjectSnapshot;
+    get markdownGeneration(): number;
+    startWatching(): void;
+    subscribe(listener: ViewStoreListener): () => void;
+    getIndex(): ViewIndex;
+    getDocument(requestedPath: string): Promise<ViewDocument>;
+    getSource(requestedPath: string, requestedSymbol?: string, origin?: {
+        sectionId: string;
+        line: number;
+    }, requestedLine?: number): Promise<ViewSourceDocument>;
+    refresh(paths: string[]): Promise<void>;
+    close(): Promise<void>;
+    private scheduleRefresh;
+    private readMarkdownFile;
+    private applyRefresh;
+}
+/** Build the initial project snapshot and optionally begin incremental updates. */
+export declare function createViewStore(latDir: string, projectRoot: string, options?: ViewStoreOptions): Promise<ViewStore>;
+export {};

package/dist/src/view/store.js

@@ -0,0 +1,404 @@
+import { watch as watchFiles } from 'node:fs';
+import { readFile, realpath } 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 { renderMarkdown } from './markdown.js';
+import { buildViewDiagnostics } from './diagnostics.js';
+import { buildGitDiffTree } from './git-diff.js';
+import { emptyViewGitSnapshot, findViewGitRepository, readViewGitSnapshot, sameViewGitSnapshot, } from './git.js';
+import { createMarkdownWikiLinkResolver, getViewSource, ViewDocumentNotFoundError, } from './repository.js';
+import { buildViewReferenceIndex, parseViewMarkdownFile, renderSectionBackReferences, } from './references.js';
+const DEFAULT_DEBOUNCE_MS = 75;
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return (rel === '' ||
+        (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`)));
+}
+function projectPath(projectRoot, path) {
+    const normalized = isAbsolute(path) ? relative(projectRoot, path) : path;
+    return toPosix(normalized).replace(/^\.\//, '');
+}
+function sourcePath(path) {
+    return SOURCE_EXTENSIONS.has(extname(path).toLowerCase());
+}
+function obviouslyIgnoredCodePath(path, latPath) {
+    const parts = path.split('/');
+    return (path === latPath ||
+        path.startsWith(`${latPath}/`) ||
+        parts.includes('.git') ||
+        parts.includes('.claude') ||
+        parts.includes('node_modules'));
+}
+function codeRefsFromContent(path, content) {
+    const refs = [];
+    const lines = content.split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        LAT_REF_RE.lastIndex = 0;
+        let match;
+        while ((match = LAT_REF_RE.exec(lines[index])) !== null) {
+            refs.push({ target: match[1], file: path, line: index + 1 });
+        }
+    }
+    return refs;
+}
+async function loadCodeReferenceFiles(projectRoot, refs) {
+    const refsByFile = new Map();
+    for (const ref of refs) {
+        const path = toPosix(ref.file);
+        const fileRefs = refsByFile.get(path) ?? [];
+        fileRefs.push({ ...ref, file: path });
+        refsByFile.set(path, fileRefs);
+    }
+    const files = new Map();
+    await Promise.all([...refsByFile].map(async ([path, fileRefs]) => {
+        try {
+            const content = await readFile(resolve(projectRoot, path), 'utf8');
+            files.set(path, { path, lines: content.split('\n'), refs: fileRefs });
+        }
+        catch {
+            // A file may disappear between the project scan and this read.
+        }
+    }));
+    return files;
+}
+async function scanCodeState(projectRoot) {
+    const scan = await scanCodeRefs(projectRoot);
+    const scope = new Set(scan.files.map((path) => projectPath(projectRoot, path)));
+    return {
+        files: await loadCodeReferenceFiles(projectRoot, scan.refs),
+        scope,
+    };
+}
+function viewIndex(latDir, paths, diagnostics, git) {
+    const files = [...paths].sort();
+    const directoryName = basename(latDir);
+    const indexName = directoryName.endsWith('.md')
+        ? directoryName
+        : `${directoryName}.md`;
+    return {
+        files,
+        entry: files.includes(indexName) ? indexName : (files[0] ?? ''),
+        errorCounts: Object.fromEntries([...diagnostics]
+            .filter(([, errors]) => errors.length > 0)
+            .map(([path, errors]) => [path, errors.length])),
+        git: git.available
+            ? {
+                files: Object.fromEntries([...git.files].map(([path, file]) => [path, file.status])),
+            }
+            : null,
+    };
+}
+async function buildSnapshot(latDir, projectRoot, markdownFiles, codeFiles, git, generation, markdownGeneration) {
+    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);
+    return {
+        generation,
+        markdownGeneration,
+        files,
+        allSections,
+        references: buildViewReferenceIndex(files.values(), codeFiles.values(), allSections),
+        diagnostics,
+        git,
+        index: viewIndex(latDir, [...files.keys()], diagnostics, git),
+    };
+}
+/** Own the immutable, incrementally refreshed project snapshot for `lat ui`. */
+export class ViewStore {
+    latDir;
+    projectRoot;
+    realLatDir;
+    gitRepository;
+    options;
+    snapshotValue;
+    codeFiles;
+    codeScope;
+    ignoredCodePaths = new Set();
+    listeners = new Set();
+    watcher = null;
+    pendingPaths = new Set();
+    debounceTimer = null;
+    refreshTail = Promise.resolve();
+    closed = false;
+    constructor(latDir, projectRoot, realLatDir, snapshot, codeFiles, codeScope, gitRepository, options) {
+        this.latDir = latDir;
+        this.projectRoot = projectRoot;
+        this.realLatDir = realLatDir;
+        this.gitRepository = gitRepository;
+        this.options = options;
+        this.snapshotValue = snapshot;
+        this.codeFiles = codeFiles;
+        this.codeScope = codeScope;
+    }
+    get snapshot() {
+        return this.snapshotValue;
+    }
+    get markdownGeneration() {
+        return this.snapshotValue.markdownGeneration;
+    }
+    startWatching() {
+        if (this.options.watch === false || this.watcher)
+            return;
+        try {
+            this.watcher = watchFiles(this.projectRoot, { recursive: true }, (_event, filename) => this.scheduleRefresh(filename?.toString() ?? ''));
+            this.watcher.on('error', (error) => {
+                process.stderr.write(`lat ui watcher: ${error.message}\n`);
+            });
+        }
+        catch (error) {
+            process.stderr.write(`lat ui watcher: ${error.message}\n`);
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getIndex() {
+        return this.snapshotValue.index;
+    }
+    async getDocument(requestedPath) {
+        if (!requestedPath ||
+            requestedPath.includes('\\') ||
+            isAbsolute(requestedPath) ||
+            !requestedPath.toLowerCase().endsWith('.md')) {
+            throw new ViewDocumentNotFoundError('Markdown document not found');
+        }
+        const snapshot = this.snapshotValue;
+        const file = snapshot.files.get(requestedPath);
+        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 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))
+            : null;
+        const errors = [...(snapshot.diagnostics.get(requestedPath) ?? [])];
+        return {
+            path: requestedPath,
+            ...rendered,
+            gitHtml: gitRendered?.html ?? null,
+            errors,
+            backReferences: await renderSectionBackReferences(snapshot.references, file.sections, this.latDir, this.projectRoot, (path) => createMarkdownWikiLinkResolver(this.latDir, path, snapshot.allSections)),
+            frontmatter: {
+                requireCodeMention: parseFrontmatter(file.content).requireCodeMention === true,
+            },
+        };
+    }
+    getSource(requestedPath, requestedSymbol = '', origin, requestedLine = 0) {
+        const snapshot = this.snapshotValue;
+        return getViewSource(this.latDir, this.projectRoot, requestedPath, requestedSymbol, origin, requestedLine, snapshot.allSections, snapshot.references);
+    }
+    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));
+        this.refreshTail = refresh.catch(() => { });
+        return refresh;
+    }
+    async close() {
+        this.closed = true;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = null;
+        this.watcher?.close();
+        this.watcher = null;
+        await this.refreshTail;
+        this.listeners.clear();
+    }
+    scheduleRefresh(path) {
+        if (this.closed)
+            return;
+        this.pendingPaths.add(path ? projectPath(this.projectRoot, path) : '');
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            const paths = [...this.pendingPaths];
+            this.pendingPaths.clear();
+            void this.refresh(paths).catch((error) => {
+                process.stderr.write(`lat ui refresh: ${error.message}\n`);
+            });
+        }, this.options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+    }
+    async readMarkdownFile(absolutePath) {
+        let realFile;
+        try {
+            realFile = await realpath(absolutePath);
+        }
+        catch {
+            return null;
+        }
+        if (!isInside(this.realLatDir, realFile))
+            return null;
+        const content = await readFile(realFile, 'utf8');
+        return parseViewMarkdownFile(absolutePath, content, this.latDir, this.projectRoot);
+    }
+    async applyRefresh(paths) {
+        const fullRefresh = paths.includes('');
+        const latPath = projectPath(this.projectRoot, this.latDir);
+        const touchesMarkdown = fullRefresh ||
+            paths.some((path) => path === latPath || path.startsWith(`${latPath}/`));
+        let markdownFiles = new Map(this.snapshotValue.files);
+        let codeFiles = new Map(this.codeFiles);
+        let markdownChanged = false;
+        let codeChanged = false;
+        let git = this.snapshotValue.git;
+        let gitChanged = false;
+        let linkedResourceChanged = false;
+        if (touchesMarkdown) {
+            const discovered = new Map((await listLatticeFiles(this.latDir)).map((absolutePath) => [
+                toPosix(relative(this.latDir, absolutePath)),
+                absolutePath,
+            ]));
+            const changed = new Set();
+            for (const path of markdownFiles.keys()) {
+                if (!discovered.has(path))
+                    changed.add(path);
+            }
+            for (const path of discovered.keys()) {
+                if (!markdownFiles.has(path))
+                    changed.add(path);
+            }
+            for (const path of paths) {
+                if (path === '') {
+                    for (const markdownPath of discovered.keys())
+                        changed.add(markdownPath);
+                    continue;
+                }
+                if (path === latPath)
+                    continue;
+                if (!path.startsWith(`${latPath}/`))
+                    continue;
+                const markdownPath = path.slice(latPath.length + 1);
+                if (markdownPath.toLowerCase().endsWith('.md')) {
+                    changed.add(markdownPath);
+                }
+            }
+            for (const path of [...changed].sort()) {
+                const absolutePath = discovered.get(path);
+                if (!absolutePath) {
+                    markdownChanged = markdownFiles.delete(path) || markdownChanged;
+                    continue;
+                }
+                const next = await this.readMarkdownFile(absolutePath);
+                if (!next) {
+                    markdownChanged = markdownFiles.delete(path) || markdownChanged;
+                    continue;
+                }
+                if (markdownFiles.get(path)?.content === next.content)
+                    continue;
+                markdownFiles.set(path, next);
+                markdownChanged = true;
+            }
+            linkedResourceChanged = paths.some((path) => path.startsWith(`${latPath}/`) && !path.toLowerCase().endsWith('.md'));
+        }
+        if (touchesMarkdown && this.gitRepository) {
+            try {
+                const nextGit = await readViewGitSnapshot(this.gitRepository, markdownFiles);
+                gitChanged = !sameViewGitSnapshot(git, nextGit);
+                git = nextGit;
+            }
+            catch (error) {
+                process.stderr.write(`lat ui git: ${error.message}\n`);
+            }
+        }
+        const codePaths = paths.filter((path) => path && sourcePath(path) && !obviouslyIgnoredCodePath(path, latPath));
+        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);
+            codeFiles = nextCode.files;
+            this.codeScope = nextCode.scope;
+            this.ignoredCodePaths.clear();
+            for (const path of codePaths) {
+                if (!this.codeScope.has(path))
+                    this.ignoredCodePaths.add(path);
+            }
+            codeChanged = true;
+        }
+        else {
+            for (const path of codePaths) {
+                if (this.ignoredCodePaths.has(path) || !this.codeScope.has(path)) {
+                    continue;
+                }
+                try {
+                    const content = await readFile(resolve(this.projectRoot, path), 'utf8');
+                    const refs = codeRefsFromContent(path, content);
+                    if (refs.length > 0) {
+                        codeFiles.set(path, {
+                            path,
+                            lines: content.split('\n'),
+                            refs,
+                        });
+                    }
+                    else {
+                        codeFiles.delete(path);
+                    }
+                }
+                catch {
+                    this.codeScope.delete(path);
+                    codeFiles.delete(path);
+                }
+                codeChanged = true;
+            }
+        }
+        if (!markdownChanged &&
+            !codeChanged &&
+            !gitChanged &&
+            !linkedResourceChanged)
+            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));
+        const change = {
+            generation: this.snapshotValue.generation,
+            markdownGeneration: this.snapshotValue.markdownGeneration,
+        };
+        for (const listener of this.listeners)
+            listener(change);
+    }
+}
+/** Build the initial project snapshot and optionally begin incremental updates. */
+export async function createViewStore(latDir, projectRoot, options = {}) {
+    const [realLatDir, markdownPaths, codeState, gitRepository] = await Promise.all([
+        realpath(latDir),
+        listLatticeFiles(latDir),
+        scanCodeState(projectRoot),
+        options.git === false
+            ? Promise.resolve(null)
+            : findViewGitRepository(projectRoot, latDir),
+    ]);
+    if (markdownPaths.length === 0) {
+        throw new Error(`No Markdown files found in ${latDir}`);
+    }
+    const markdownFiles = new Map();
+    await Promise.all(markdownPaths.map(async (absolutePath) => {
+        const realFile = await realpath(absolutePath);
+        if (!isInside(realLatDir, realFile))
+            return;
+        const content = await readFile(realFile, 'utf8');
+        const parsed = parseViewMarkdownFile(absolutePath, content, latDir, projectRoot);
+        markdownFiles.set(parsed.path, parsed);
+    }));
+    if (markdownFiles.size === 0) {
+        throw new Error(`No readable Markdown files found in ${latDir}`);
+    }
+    let git = emptyViewGitSnapshot();
+    if (gitRepository) {
+        try {
+            git = await readViewGitSnapshot(gitRepository, markdownFiles);
+        }
+        catch (error) {
+            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);
+    store.startWatching();
+    return store;
+}