@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/doxbrix-build.d.ts

@@ -0,0 +1,19 @@
+export interface DoxbrixBuildOptions {
+    root: string;
+    outDir?: string;
+    /** Origin-relative mount point, for example `/repository`. */
+    basePath?: string;
+    /** Public origin used for canonical URLs and sitemap entries. */
+    siteUrl?: string;
+    clean?: boolean;
+}
+export interface StaticBuildResult {
+    outputDir: string;
+    pages: number;
+    assets: number;
+    basePath: string;
+    siteUrl?: string;
+}
+/** Build the built-in Doxbrix reader into portable static files. */
+export declare function buildDoxbrixStaticSite(options: DoxbrixBuildOptions): Promise<StaticBuildResult>;
+//# sourceMappingURL=doxbrix-build.d.ts.map

package/dist/doxbrix-build.js

@@ -0,0 +1,167 @@
+import { readRedirects } from './page-operations.js';
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
+import { renderMarkdown } from './doxbrix-markdown.js';
+import { DoxloopError } from './errors.js';
+import { listFiles, resolveContainedDirectory } from './fs.js';
+import { loadQualityConfig } from './quality-config.js';
+import { reverifyClaims } from './quality-claims.js';
+import { loadPages, loadProject, loadSiteConfig, pageId, ROOT_CONTENT_IGNORED_DIRECTORIES, } from './project.js';
+import { doxbrixDocument, firstSitePage, redirectTarget } from './preview.js';
+const PACKAGE_ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const DOXBRIX_CSS = resolve(PACKAGE_ROOT, 'assets', 'doxbrix-preview.css');
+const ASSET_EXTENSIONS = new Set([
+    '.avif', '.bmp', '.eot', '.gif', '.ico', '.jpeg', '.jpg', '.mov', '.mp3',
+    '.mp4', '.ogg', '.otf', '.pdf', '.png', '.svg', '.ttf', '.wav', '.webm',
+    '.webp', '.woff', '.woff2',
+]);
+/** Build the built-in Doxbrix reader into portable static files. */
+export async function buildDoxbrixStaticSite(options) {
+    const root = resolve(options.root);
+    const project = await loadProject(root);
+    if (project.generator !== 'doxbrix') {
+        throw new DoxloopError('The built-in static builder only supports Doxbrix projects.');
+    }
+    const outputDir = resolve(options.outDir ?? join(root, 'build'));
+    if (outputDir === root) {
+        throw new DoxloopError('Doxbrix build output cannot replace the project directory.');
+    }
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Build content directory', { allowRoot: true });
+    if (options.clean !== false)
+        await rm(outputDir, { recursive: true, force: true });
+    await mkdir(join(outputDir, '__doxloop'), { recursive: true });
+    const [paths, site, css, qualityConfig, verification] = await Promise.all([
+        loadPages(root, project),
+        loadSiteConfig(root, project),
+        readFile(DOXBRIX_CSS, 'utf8'),
+        loadQualityConfig(root),
+        loadQualityConfig(root).then((config) => config.readerVerification?.enabled ? reverifyClaims(root, project, false).then((result) => result.metadata) : undefined),
+    ]);
+    if (paths.length === 0)
+        throw new DoxloopError('Doxbrix static build found no pages.');
+    const basePath = normalizeBasePath(options.basePath);
+    const siteUrl = publicSiteUrl(options.siteUrl, site.site);
+    const search = [];
+    const sitemap = [];
+    const ids = new Set(paths.map((path) => pageId(contentRoot, path)));
+    const navigationHome = firstSitePage(site);
+    const firstId = navigationHome && ids.has(navigationHome) ? navigationHome : pageId(contentRoot, paths[0]);
+    for (const path of paths) {
+        const id = pageId(contentRoot, path);
+        const parsed = matter(await readFile(path, 'utf8'));
+        const title = text(parsed.data.title) || labelFromId(id);
+        const description = text(parsed.data.description);
+        const href = `${basePath}/${id}`;
+        const canonical = text(parsed.data.canonical) || (siteUrl ? new URL(`${id}/`, trailingSlash(siteUrl)).toString() : undefined);
+        const socialImage = resolvePublicReference(text(parsed.data.socialImage), siteUrl);
+        const verificationEntry = qualityConfig.readerVerification?.enabled
+            ? verification?.pages[relative(root, path).replace(/\\/g, '/')]
+            : undefined;
+        const html = doxbrixDocument({
+            site,
+            title,
+            ...(description ? { description } : {}),
+            ...(canonical ? { canonical } : {}),
+            ...(socialImage ? { socialImage } : {}),
+            current: id,
+            rendered: renderMarkdown(parsed.content),
+            ...(verificationEntry ? { verification: verificationEntry } : {}),
+            basePath,
+            liveReload: false,
+        });
+        const pageOutput = join(outputDir, ...id.split('/'), 'index.html');
+        await mkdir(dirname(pageOutput), { recursive: true });
+        await writeFile(pageOutput, html, 'utf8');
+        if (id.endsWith('/index'))
+            await writeFile(join(outputDir, ...id.split('/').slice(0, -1), 'index.html'), html, 'utf8');
+        search.push({ title, description: description ?? '', href, text: markdownSearchText(parsed.content) });
+        if (siteUrl)
+            sitemap.push(new URL(`${id}/`, trailingSlash(siteUrl)).toString());
+    }
+    // Write last so an unlisted index page cannot replace the navigation homepage.
+    await cp(join(outputDir, ...firstId.split('/'), 'index.html'), join(outputDir, 'index.html'));
+    const builtPages = new Map([...ids].map((id) => [id, id]));
+    for (const [from, to] of Object.entries(await readRedirects(root))) {
+        // A redirect stub is only worth writing when the page it points at exists in this build.
+        if (to !== '/' && !redirectTarget(to, site, builtPages))
+            continue;
+        const target = `${basePath}${to}`;
+        const output = join(outputDir, from.replace(/^\//, ''), 'index.html');
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, `<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=${target}"><link rel="canonical" href="${target}"><a href="${target}">This page has moved</a>`, 'utf8');
+    }
+    await writeFile(join(outputDir, '__doxloop', 'doxbrix.css'), css, 'utf8');
+    await writeFile(join(outputDir, '__doxloop', 'search-index'), JSON.stringify(search), 'utf8');
+    await writeFile(join(outputDir, '__doxloop', 'search-index.json'), `${JSON.stringify(search, null, 2)}\n`, 'utf8');
+    await writeFile(join(outputDir, 'sitemap.xml'), sitemapXml(sitemap), 'utf8');
+    await writeFile(join(outputDir, 'robots.txt'), robotsTxt(siteUrl), 'utf8');
+    let assets = 0;
+    const ignoredDirectories = new Set(ROOT_CONTENT_IGNORED_DIRECTORIES);
+    ignoredDirectories.add(relative(contentRoot, outputDir).split(/[\\/]/)[0] || 'build');
+    for (const asset of await listFiles(contentRoot, ASSET_EXTENSIONS, { ignoredDirectories })) {
+        const destination = join(outputDir, relative(contentRoot, asset));
+        await mkdir(dirname(destination), { recursive: true });
+        await cp(asset, destination);
+        assets++;
+    }
+    return {
+        outputDir,
+        pages: paths.length,
+        assets,
+        basePath,
+        ...(siteUrl ? { siteUrl } : {}),
+    };
+}
+function publicSiteUrl(explicit, site) {
+    const configured = explicit ?? process.env.DOXLOOP_SITE_URL ?? text(site?.url);
+    if (!configured)
+        return undefined;
+    let url;
+    try {
+        url = new URL(configured);
+    }
+    catch {
+        throw new DoxloopError(`Invalid static site URL: ${configured}`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new DoxloopError('Static site URL must be an HTTP(S) URL without credentials, query, or fragment.');
+    }
+    return url.toString();
+}
+function resolvePublicReference(value, siteUrl) {
+    if (!value)
+        return undefined;
+    if (/^https?:\/\//i.test(value) || !siteUrl)
+        return value;
+    return new URL(value.replace(/^\//, ''), trailingSlash(siteUrl)).toString();
+}
+function normalizeBasePath(value = '') {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === '/')
+        return '';
+    if (/^[a-z][a-z\d+.-]*:/i.test(trimmed) || trimmed.startsWith('//')) {
+        throw new DoxloopError('Static build base path must be an origin-relative URL path.');
+    }
+    const normalized = `/${trimmed.replace(/^\/+|\/+$/g, '')}`;
+    if (normalized.split('/').some((part) => part === '..')) {
+        throw new DoxloopError('Static build base path cannot leave its URL root.');
+    }
+    return normalized;
+}
+function sitemapXml(urls) {
+    const body = urls.map((url) => `  <url><loc>${xml(url)}</loc></url>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}${body ? '\n' : ''}</urlset>\n`;
+}
+function robotsTxt(siteUrl) {
+    return `User-agent: *\nAllow: /\n${siteUrl ? `Sitemap: ${new URL('sitemap.xml', trailingSlash(siteUrl)).toString()}\n` : ''}`;
+}
+function trailingSlash(value) { return value.endsWith('/') ? value : `${value}/`; }
+function text(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+function xml(value) { return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;'); }
+function labelFromId(id) { return id.split('/').at(-1).replace(/[-_]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase()); }
+function markdownSearchText(markdown) {
+    return markdown.replace(/```[\s\S]*?```/g, ' ').replace(/`([^`]+)`/g, '$1').replace(/!\[[^\]]*\]\([^)]+\)/g, ' ').replace(/\[([^\]]+)\]\([^)]+\)/g, '$1').replace(/<[^>]+>/g, ' ').replace(/[#>*_~|=-]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 12_000);
+}
+//# sourceMappingURL=doxbrix-build.js.map

package/dist/doxbrix-markdown.d.ts

@@ -16,5 +16,14 @@ export interface RenderResult {
     html: string;
     toc: TocEntry[];
 }
+export interface EditableBlock {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Map editable rendered regions to exact source spans, including repeated blocks and CRLF. */
+export declare function renderEditableMarkdown(md: string): RenderResult & {
+    blocks: EditableBlock[];
+};
 export declare function renderMarkdown(md: string): RenderResult;
 //# sourceMappingURL=doxbrix-markdown.d.ts.map

package/dist/doxbrix-markdown.js

@@ -18,6 +18,53 @@ const uid = () => `t${(uidCounter++).toString(36)}`;
 let tocEntries = [];
 const slugCounts = new Map();
 let renderDepth = 0;
+let editableSource;
+let editableBlocks = [];
+let originalEditableSource = '';
+let editableOffsets = [];
+let editableCursor = 0;
+let editScope;
+/** Map editable rendered regions to exact source spans, including repeated blocks and CRLF. */
+export function renderEditableMarkdown(md) {
+    originalEditableSource = md;
+    editableSource = md.replace(/\r\n/g, '\n');
+    editableOffsets = [];
+    for (let i = 0; i < md.length; i++) {
+        editableOffsets.push(i);
+        if (md[i] === '\r' && md[i + 1] === '\n')
+            i++;
+    }
+    editableOffsets.push(md.length);
+    editableCursor = 0;
+    editScope = undefined;
+    editableBlocks = [];
+    try {
+        return { ...renderMarkdown(md), blocks: [...editableBlocks] };
+    }
+    finally {
+        editableSource = undefined;
+        editableBlocks = [];
+        editableOffsets = [];
+        editScope = undefined;
+    }
+}
+function editAttributes(text, code = false) {
+    if (!editableSource || !text.trim())
+        return '';
+    const from = editScope?.cursor ?? 0;
+    const start = editableSource.indexOf(text, from);
+    if (start < 0 || (editScope ? start + text.length > editScope.end : editableSource.indexOf(text, start + 1) !== -1))
+        return '';
+    if (editScope)
+        editScope.cursor = start + text.length;
+    const sourceStart = editableOffsets[start];
+    const sourceEnd = editableOffsets[start + text.length];
+    if (editableBlocks.some((block) => sourceStart < block.end && sourceEnd > block.start))
+        return '';
+    const original = originalEditableSource.slice(sourceStart, sourceEnd);
+    editableBlocks.push({ start: sourceStart, end: sourceEnd, text: original });
+    return ` data-edit-start="${sourceStart}" data-edit-end="${sourceEnd}" data-edit-format="${code ? 'plain' : 'markdown'}" data-edit-source="${escAttr(original)}"`;
+}
 export function renderMarkdown(md) {
     uidCounter = 0;
     tocEntries = [];
@@ -417,7 +464,7 @@ function codeBlock(code, lang) {
     catch {
         highlighted = esc(code);
     }
-    return `<div class="dp-code-block dp-code-theme-auto dp-code-theme-light"><div class="dp-code-header"><span class="dp-code-lang">${esc(lang || 'plaintext')}</span><button class="dp-code-copy-btn" type="button" aria-label="Copy code">${copyIcon()}<span>Copy</span></button></div><pre class="dp-code-pre dp-hl-auto dp-hl-light"><code>${highlighted}</code></pre></div>`;
+    return `<div class="dp-code-block dp-code-theme-auto dp-code-theme-light"><div class="dp-code-header"><span class="dp-code-lang">${esc(lang || 'plaintext')}</span><button class="dp-code-copy-btn" type="button" aria-label="Copy code">${copyIcon()}<span>Copy</span></button></div><pre class="dp-code-pre dp-hl-auto dp-hl-light"><code${editAttributes(code, true)}>${highlighted}</code></pre></div>`;
 }
 function copyIcon() {
     return '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
@@ -675,7 +722,26 @@ function responseExample(_props, inner) {
 // Markdown chunk renderer.
 // ---------------------------------------------------------------------------
 function renderMarkdownChunk(md, top) {
+    const previous = editScope;
+    const start = editableSource?.indexOf(md, editableCursor) ?? -1;
+    editScope = start >= 0 ? { start, end: start + md.length, cursor: start } : undefined;
+    if (start >= 0)
+        editableCursor = start + md.length;
+    try {
+        return renderMarkdownLines(md, top);
+    }
+    finally {
+        editScope = previous;
+    }
+}
+function renderMarkdownLines(md, top) {
     const lines = md.split('\n');
+    const lineOffsets = [];
+    let offset = 0;
+    for (const line of lines) {
+        lineOffsets.push(offset);
+        offset += line.length + 1;
+    }
     const out = [];
     let i = 0;
     let guard = 0;
@@ -685,10 +751,14 @@ function renderMarkdownChunk(md, top) {
             break;
         }
         const line = lines[i];
-        const fence = /^\s*(```|~~~)(\w*)\s*$/.exec(line);
+        if (editScope)
+            editScope.cursor = editScope.start + lineOffsets[i];
+        const fence = /^\s*(```+|~~~+)\s*([^\s`~]*)(?:\s+.*)?$/.exec(line);
         if (fence) {
             const lang = fence[2] ?? '';
             const body = [];
+            if (editScope)
+                editScope.cursor = editScope.start + lineOffsets[i] + line.length + 1;
             i++;
             while (i < lines.length && !/^\s*(```|~~~)\s*$/.test(lines[i]))
                 body.push(lines[i++]);
@@ -712,8 +782,10 @@ function renderMarkdownChunk(md, top) {
             i++;
             continue;
         }
-        const h = /^(#{1,6})\s+(.*)$/.exec(line);
+        const h = /^\s*(#{1,6})\s+(.*)$/.exec(line);
         if (h) {
+            if (editScope)
+                editScope.cursor += line.indexOf(h[2], h[1].length);
             out.push(heading(h[1].length, h[2], top));
             i++;
             continue;
@@ -742,10 +814,14 @@ function renderMarkdownChunk(md, top) {
         if (/^\s*([-*+]|\d+\.)\s+/.test(line)) {
             const ordered = /^\s*\d+\.\s+/.test(line);
             const items = [];
+            const itemStarts = [];
             while (i < lines.length && /^\s*([-*+]|\d+\.)\s+/.test(lines[i])) {
-                items.push(lines[i++].replace(/^\s*([-*+]|\d+\.)\s+/, ''));
+                const item = lines[i].replace(/^\s*([-*+]|\d+\.)\s+/, '');
+                itemStarts.push((editScope?.start ?? 0) + lineOffsets[i] + lines[i].length - item.length);
+                items.push(item);
+                i++;
             }
-            out.push(renderList(items, ordered));
+            out.push(renderList(items, ordered, itemStarts));
             continue;
         }
         // Lone-image paragraph -> block image (matches the reader's image block).
@@ -761,8 +837,11 @@ function renderMarkdownChunk(md, top) {
             !/^\s*(#{1,6}\s|>\s?|```|~~~|<!--|<\/[A-Za-z]|([-*+]|\d+\.)\s+)/.test(lines[i])) {
             para.push(lines[i++]);
         }
+        // A malformed block opener must still advance, preserving text below it.
+        if (!para.length)
+            para.push(lines[i++]);
         if (para.length)
-            out.push(`<p class="dp-p">${inline(para.join(' '))}</p>`);
+            out.push(`<p class="dp-p"${editAttributes(para.join('\n'))}>${inline(para.join(' '))}</p>`);
     }
     return out.join('\n');
 }
@@ -772,31 +851,39 @@ function heading(level, text, top) {
     if (top && (lvl === 2 || lvl === 3 || lvl === 4)) {
         tocEntries.push({ id, level: lvl, title: stripInline(text) });
     }
-    return `<h${lvl} id="${escAttr(id)}" class="dp-h${lvl}">${inline(text)}</h${lvl}>`;
+    return `<h${lvl} id="${escAttr(id)}" class="dp-h${lvl}"${editAttributes(text)}>${inline(text)}</h${lvl}>`;
 }
-function renderList(items, ordered) {
+function renderList(items, ordered, starts) {
     const isTask = items.some((it) => /^\[[ xX]\]\s+/.test(it));
     if (isTask) {
         const lis = items
-            .map((it) => {
+            .map((it, index) => {
+            if (editScope)
+                editScope.cursor = starts[index];
             const m = /^\[([ xX])\]\s+(.*)$/.exec(it);
             const checked = m && m[1] !== ' ';
             const icon = `<span class="dp-task-check-icon${checked ? ' checked' : ''}"></span>`;
             const txt = m ? m[2] : it;
+            if (editScope)
+                editScope.cursor += it.length - txt.length;
             const style = checked ? ' style="text-decoration:line-through;color:#9ca3af"' : '';
-            return `<li class="dp-task-item">${icon}<span${style}>${inline(txt)}</span></li>`;
+            return `<li class="dp-task-item">${icon}<span${style}${editAttributes(txt)}>${inline(txt)}</span></li>`;
         })
             .join('');
         return `<ul class="dp-task-list">${lis}</ul>`;
     }
     const tag = ordered ? 'ol' : 'ul';
     const cls = ordered ? 'dp-ol' : 'dp-ul';
-    const lis = items.map((it) => `<li>${inline(it)}</li>`).join('');
+    const lis = items.map((it, index) => {
+        if (editScope)
+            editScope.cursor = starts[index];
+        return `<li${editAttributes(it)}>${inline(it)}</li>`;
+    }).join('');
     return `<${tag} class="${cls}">${lis}</${tag}>`;
 }
 function renderTable(header, rows) {
-    const head = `<tr>${header.map((c) => `<th>${inline(c)}</th>`).join('')}</tr>`;
-    const body = rows.map((r) => `<tr>${r.map((c) => `<td>${inline(c)}</td>`).join('')}</tr>`).join('');
+    const head = `<tr>${header.map((c) => `<th${editAttributes(c)}>${inline(c)}</th>`).join('')}</tr>`;
+    const body = rows.map((r) => `<tr>${r.map((c) => `<td${editAttributes(c)}>${inline(c)}</td>`).join('')}</tr>`).join('');
     return `<div class="dp-table-wrap"><table class="dp-table"><thead>${head}</thead><tbody>${body}</tbody></table></div>`;
 }
 // ---------------------------------------------------------------------------
@@ -809,7 +896,7 @@ function inline(text) {
         const html = tag === 'Badge'
             ? `<span class="dp-inline-badge">${esc(str(props.text) || (body ?? '').trim())}</span>`
             : `<span class="dp-inline-badge">${esc(iconGlyph(str(props.name)))}</span>`;
-        tokens.push(html);
+        tokens.push(editableSource !== undefined ? `<span contenteditable="false" data-md-atom="${escAttr(_m)}">${html}</span>` : html);
         return `${TOK_OPEN}${tokens.length - 1}${TOK_CLOSE}`;
     });
     s = esc(s);
@@ -821,6 +908,20 @@ function inline(text) {
     s = s.replace(/~~([^~]+)~~/g, '<s>$1</s>');
     s = s.replace(/(^|[^*])\*([^*]+)\*/g, '$1<em>$2</em>');
     s = s.replace(/(^|[^_\w])_([^_]+)_/g, '$1<em>$2</em>');
+    if (editableSource !== undefined) {
+        const links = [...text.matchAll(/(?<!!)\[([^\]]+)\](\([^)\s]+[^)]*\))/g)];
+        let linkIndex = 0;
+        s = s.replace(/<a class="df-inline-link"[^>]*>/g, (tag) => {
+            const link = links[linkIndex++];
+            return link ? tag.replace(/>$/, ` data-md-suffix="${escAttr(']' + link[2])}">`) : tag;
+        });
+        const images = [...text.matchAll(/!\[([^\]]*)\]\([^)\s]+[^)]*\)/g)];
+        let imageIndex = 0;
+        s = s.replace(/<img [^>]*\/>/g, (tag) => {
+            const source = images[imageIndex++]?.[0];
+            return source ? `<span contenteditable="false" data-md-atom="${escAttr(source)}">${tag}</span>` : tag;
+        });
+    }
     if (tokens.length) {
         s = s.replace(new RegExp(`${TOK_OPEN}(\\d+)${TOK_CLOSE}`, 'g'), (_m, k) => tokens[Number(k)] ?? '');
     }

package/dist/drift.d.ts

@@ -0,0 +1,10 @@
+import type { DoxloopProject, DriftResult, SourceChange } from './types.js';
+/**
+ * Answer "which documentation pages no longer match the product?" without
+ * starting an agent. Detection is deterministic and safe to run on a schedule
+ * or in continuous integration.
+ */
+export declare function computeDrift(root: string, project: DoxloopProject): Promise<DriftResult>;
+export declare function computeDriftFromChanges(root: string, project: DoxloopProject, changes: SourceChange[]): Promise<DriftResult>;
+export declare function formatDrift(result: DriftResult): string;
+//# sourceMappingURL=drift.d.ts.map

package/dist/drift.js

@@ -0,0 +1,164 @@
+import { pagesForChange, readEvidenceMap } from './evidence.js';
+import { isWatchedPath } from './globs.js';
+import { changedSourcePaths, collectSourceChanges, readSyncState } from './sync.js';
+/**
+ * Answer "which documentation pages no longer match the product?" without
+ * starting an agent. Detection is deterministic and safe to run on a schedule
+ * or in continuous integration.
+ */
+export async function computeDrift(root, project) {
+    const changes = await collectSourceChanges(root, project.sources);
+    return computeDriftFromChanges(root, project, changes);
+}
+export async function computeDriftFromChanges(root, project, changes) {
+    const map = await readEvidenceMap(root);
+    const notes = [];
+    const sources = [];
+    const reasonsByPage = new Map();
+    let unresolved = false;
+    for (const change of changes) {
+        const rawPaths = changedSourcePaths(change);
+        const changedPaths = rawPaths.filter((path) => isWatchedPath(path, project.sync.watch, project.sync.ignore));
+        sources.push({
+            name: change.name,
+            path: change.path,
+            kind: change.kind,
+            changedPaths,
+            filteredPaths: rawPaths.length - changedPaths.length,
+            ...('baseline' in change ? { baseline: change.baseline } : {}),
+            ...('head' in change ? { head: change.head } : {}),
+            ...(change.scope ? { scope: change.scope } : {}),
+        });
+        const note = unresolvedNote(change);
+        if (note) {
+            notes.push(note);
+            unresolved = true;
+            continue;
+        }
+        if (changedPaths.length === 0)
+            continue;
+        if (!map) {
+            notes.push(`Source "${change.name}" changed, but no evidence map exists yet, so affected pages cannot be named. Run \`doxloop update\` to build one.`);
+            unresolved = true;
+            continue;
+        }
+        const matched = pagesForChange(map, change.name, changedPaths);
+        for (const [page, paths] of matched) {
+            const reasons = reasonsByPage.get(page) ?? [];
+            reasons.push({
+                source: change.name,
+                paths,
+                ...('baseline' in change ? { baseline: change.baseline } : {}),
+                ...('head' in change ? { head: change.head } : {}),
+            });
+            reasonsByPage.set(page, reasons);
+        }
+        const attributed = new Set([...matched.values()].flat());
+        const unattributed = changedPaths.filter((path) => !attributed.has(path));
+        if (unattributed.length > 0) {
+            notes.push(`${unattributed.length} changed file${unattributed.length === 1 ? '' : 's'} in "${change.name}" ${unattributed.length === 1 ? 'is' : 'are'} not referenced by any page.`);
+        }
+    }
+    if (map && project.sync.maxVerificationAgeDays) {
+        const state = await readSyncState(root);
+        const threshold = project.sync.maxVerificationAgeDays;
+        const severity = project.sync.maxVerificationAgeSeverity ?? 'warn';
+        for (const [page, evidence] of Object.entries(map.pages)) {
+            for (const entry of evidence.sources) {
+                const record = state.sources[entry.source];
+                const explicit = evidence.verifiedOn?.[entry.source];
+                const revisionMatches = record && evidence.verifiedAt?.[entry.source] && [record.commit, record.contentFingerprint].includes(evidence.verifiedAt[entry.source]);
+                const verifiedOn = explicit ?? (revisionMatches ? record.recordedAt : undefined);
+                const ageDays = verifiedOn ? Math.floor((Date.now() - Date.parse(verifiedOn)) / 86_400_000) : Number.POSITIVE_INFINITY;
+                if (ageDays <= threshold)
+                    continue;
+                const ageLabel = Number.isFinite(ageDays) ? `${ageDays} days` : 'an unknown amount of time';
+                if (severity === 'warn') {
+                    notes.push(`Page "${page}" was last verified against "${entry.source}" ${ageLabel} ago; policy is ${threshold} days.`);
+                    continue;
+                }
+                const reasons = reasonsByPage.get(page) ?? [];
+                reasons.push({ source: entry.source, paths: [], kind: 'max-age', ...(Number.isFinite(ageDays) ? { ageDays } : {}) });
+                reasonsByPage.set(page, reasons);
+            }
+        }
+    }
+    const pages = [...reasonsByPage.entries()]
+        .map(([page, reasons]) => stalePage(page, reasons, map))
+        .sort((left, right) => left.page.localeCompare(right.page));
+    return {
+        status: pages.length > 0 ? 'stale' : unresolved ? 'unknown' : 'current',
+        pages,
+        trackedPages: map ? Object.keys(map.pages).length : 0,
+        sources,
+        evidenceMap: map ? 'present' : 'missing',
+        notes,
+    };
+}
+function stalePage(page, reasons, map) {
+    const recorded = map?.pages[page]?.verifiedAt;
+    const verifiedAt = recorded
+        ? recorded[reasons[0]?.source ?? '']
+        : undefined;
+    return { page, reasons, ...(verifiedAt ? { verifiedAt } : {}) };
+}
+/**
+ * Conditions where drift cannot be decided from local state. These are
+ * reported rather than silently treated as "documentation is current".
+ */
+function unresolvedNote(change) {
+    switch (change.kind) {
+        case 'missing-path':
+            return `Source "${change.name}" is configured as ${change.path}, which does not exist.`;
+        case 'not-git':
+            return `Source "${change.name}" is not a Git repository, so changes cannot be compared.`;
+        case 'no-baseline':
+            return `Source "${change.name}" has no sync baseline yet. Accepting the next update records one.`;
+        case 'baseline-lost':
+            return `The recorded baseline for source "${change.name}" no longer exists, so changes cannot be compared.`;
+        case 'spec-remote':
+            return `The API specification "${change.name}" is remote and is not compared locally. The next update checks it.`;
+        default:
+            return undefined;
+    }
+}
+export function formatDrift(result) {
+    const lines = [];
+    if (result.status === 'stale') {
+        lines.push(`Documentation drift: ${result.pages.length} page${result.pages.length === 1 ? '' : 's'} stale`, '');
+        for (const page of result.pages) {
+            lines.push(`  ${page.page}`);
+            for (const reason of page.reasons) {
+                if (reason.kind === 'max-age') {
+                    lines.push(`    stale because  verification is ${reason.ageDays === undefined ? 'undated' : `${reason.ageDays} days old`} for source "${reason.source}"`);
+                    continue;
+                }
+                const because = reason.paths.length === 0
+                    ? `source "${reason.source}" changed`
+                    : `${reason.paths.slice(0, 5).join(', ')}${reason.paths.length > 5 ? `, and ${reason.paths.length - 5} more` : ''} changed`;
+                lines.push(`    stale because  ${because}${reason.head ? ` (${reason.head.slice(0, 12)})` : ''}`);
+            }
+            if (page.verifiedAt) {
+                lines.push(`    last verified  ${page.verifiedAt.slice(0, 12)}`);
+            }
+            lines.push('');
+        }
+        const current = Math.max(result.trackedPages - result.pages.length, 0);
+        if (current > 0)
+            lines.push(`  ${current} other tracked page${current === 1 ? '' : 's'} current`, '');
+    }
+    else if (result.status === 'current') {
+        lines.push('Documentation is current with the recorded source baseline.', '');
+    }
+    else {
+        lines.push('Documentation drift could not be determined.', '');
+    }
+    for (const note of result.notes)
+        lines.push(`  Note: ${note}`);
+    if (result.notes.length > 0)
+        lines.push('');
+    if (result.status === 'stale')
+        lines.push('Fix with: doxloop update');
+    return lines.join('\n').trimEnd();
+}
+//# sourceMappingURL=drift.js.map

package/dist/evaluation.d.ts

@@ -0,0 +1,46 @@
+export declare const EVALUATION_CONTRACT_VERSION: "1.0.0";
+export declare const EVALUATION_BASELINE_FILE: string;
+export interface EvaluationMetric {
+    id: string;
+    score: number;
+    weight: number;
+    detail: string;
+}
+export interface EvaluationReport {
+    schemaVersion: 1;
+    contractVersion: '1.0.0';
+    generatedAt: string;
+    mode: 'generation' | 'update';
+    project: string;
+    score: number;
+    metrics: EvaluationMetric[];
+    durationMs?: number;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        costUsd?: number;
+    };
+    reviewer: {
+        accepted: number;
+        revised: number;
+        rejected: number;
+    };
+    regression?: {
+        baselineScore: number;
+        delta: number;
+        threshold: number;
+        blocked: boolean;
+    };
+}
+export declare function evaluateWorkspace(root: string, options: {
+    mode: 'generation' | 'update';
+    before?: string;
+    expectedChangedPages?: string[];
+    maximumPages?: number;
+    durationMs?: number;
+    usage?: EvaluationReport['usage'];
+    regressionThreshold?: number;
+}): Promise<EvaluationReport>;
+export declare function approveEvaluationBaseline(root: string, report: EvaluationReport): Promise<void>;
+export declare function formatEvaluation(report: EvaluationReport): string;
+//# sourceMappingURL=evaluation.d.ts.map