@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/review-render.js

@@ -0,0 +1,224 @@
+/**
+ * Builds the rendered before/after comparison shown inside the review center.
+ *
+ * Both versions of a page are rendered with the same engine the published site
+ * uses, then lined up block by block so a writer can read the proposal as a
+ * finished page instead of as a patch.
+ */
+import { renderMarkdown } from './doxbrix-markdown.js';
+import { alignBlocks, escapeHtml, markHtmlWordDiff, splitHtmlBlocks, } from './review-diff.js';
+/** Number of unchanged blocks kept visible on each side of a change. */
+const CONTEXT_BLOCKS = 1;
+export function renderedDiff(options) {
+    const before = safeRender(options.before);
+    const after = safeRender(options.after);
+    const rows = [];
+    const headerBefore = pageHeader(options.before);
+    const headerAfter = pageHeader(options.after);
+    if (headerBefore !== '' || headerAfter !== '') {
+        rows.push({
+            status: !options.before.exists
+                ? 'added'
+                : !options.after.exists
+                    ? 'removed'
+                    : headerBefore === headerAfter
+                        ? 'equal'
+                        : 'changed',
+            ...(options.before.exists ? { before: headerBefore } : {}),
+            ...(options.after.exists ? { after: headerAfter } : {}),
+        });
+    }
+    rows.push(...alignBlocks(splitHtmlBlocks(before), splitHtmlBlocks(after)));
+    const added = rows.filter((row) => row.status === 'added').length;
+    const removed = rows.filter((row) => row.status === 'removed').length;
+    const changed = rows.filter((row) => row.status === 'changed').length;
+    const hasChanges = added + removed + changed > 0;
+    return {
+        html: rowGroups(rows, hasChanges).map(groupHtml).join(''),
+        added,
+        removed,
+        changed,
+    };
+}
+function safeRender(side) {
+    if (!side.exists)
+        return '';
+    try {
+        return renderMarkdown(side.body).html;
+    }
+    catch (error) {
+        return `<div class="dp-p rd-render-error">This version could not be rendered: ${escapeHtml(error instanceof Error ? error.message : String(error))}</div>`;
+    }
+}
+function pageHeader(side) {
+    if (!side.exists)
+        return '';
+    const description = side.description
+        ? `<p class="dp-page-description">${escapeHtml(side.description)}</p>`
+        : '';
+    return `<h1 class="dp-page-title">${escapeHtml(side.title)}</h1>${description}`;
+}
+/**
+ * Group the aligned rows so long stretches of untouched content collapse into a
+ * single expandable strip, keeping the changes close together on screen.
+ */
+function rowGroups(rows, hasChanges) {
+    if (!hasChanges)
+        return [{ folded: false, rows: [...rows] }];
+    const visible = rows.map((row, index) => {
+        // The page title always stays on screen so the reader keeps their bearings.
+        if (row.status !== 'equal' || index === 0)
+            return true;
+        return rows.some((other, otherIndex) => other.status !== 'equal' && Math.abs(otherIndex - index) <= CONTEXT_BLOCKS);
+    });
+    const groups = [];
+    for (const [index, row] of rows.entries()) {
+        const folded = !visible[index];
+        const last = groups.at(-1);
+        if (last && last.folded === folded)
+            last.rows.push(row);
+        else
+            groups.push({ folded, rows: [row] });
+    }
+    // A one-block fold costs more attention than it saves.
+    return groups.map((group) => (group.folded && group.rows.length < 2 ? { ...group, folded: false } : group));
+}
+function groupHtml(group) {
+    const rows = group.rows.map(rowHtml).join('');
+    if (!group.folded)
+        return rows;
+    const count = group.rows.length;
+    return `<details class="rd-fold"><summary class="rd-fold-summary"><span class="rd-fold-line"></span><span class="rd-fold-label">${count} unchanged block${count === 1 ? '' : 's'}</span><span class="rd-fold-line"></span></summary><div class="rd-fold-body">${rows}</div></details>`;
+}
+function rowHtml(row) {
+    let before = row.before ?? '';
+    let after = row.after ?? '';
+    if (row.status === 'changed' && before !== '' && after !== '') {
+        const marked = markHtmlWordDiff(before, after);
+        before = marked.before;
+        after = marked.after;
+    }
+    return `<div class="rd-row" data-status="${row.status}">${cell('before', before, row.status)}${cell('after', after, row.status)}</div>`;
+}
+function cell(side, html, status) {
+    const empty = html === ''
+        ? `<div class="rd-empty">${side === 'before' ? 'Not in the current page' : 'Removed from the page'}</div>`
+        : '';
+    // The tag names the side whenever the two columns are stacked and the sticky
+    // column headers no longer apply.
+    const tag = `<span class="rd-cell-tag">${side === 'before' ? 'Current' : 'Proposed'}</span>`;
+    return `<div class="rd-cell rd-cell--${side}" data-status="${status}"><div class="rd-gutter" aria-hidden="true"></div><div class="dp-blocks rd-content">${tag}${html}${empty}</div></div>`;
+}
+/**
+ * Document for the comparison frame. It carries no controls of its own — the
+ * review screen owns every choice — so the whole frame is documentation.
+ */
+export function renderedDiffDocument(input) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Rendered comparison</title>
+  <link rel="stylesheet" href="/reader.css">
+  <style>${renderedDiffCss()}</style>
+</head>
+<body class="rd-body${input.onlyChanges ? ' rd-only-changes' : ''}" data-mode="${input.layout}" data-theme="${input.theme}">
+  ${input.notice ? `<div class="rd-notice">${escapeHtml(input.notice)}</div>` : ''}
+  <div class="rd-scroll">
+    <div class="rd-heads">
+      <div class="rd-head rd-head--before"><span class="rd-dot rd-dot--before"></span>Current documentation</div>
+      <div class="rd-head rd-head--after"><span class="rd-dot rd-dot--after"></span>Proposed update</div>
+    </div>
+    <div class="dp-root rd-root" data-color-theme="${input.theme}" data-code-theme="auto">${input.diff.html}</div>
+    ${input.diff.added + input.diff.removed + input.diff.changed === 0
+        ? '<div class="rd-none">Nothing in the rendered page changed. The difference is in the file itself — open the source diff to see it.</div>'
+        : ''}
+  </div>
+</body>
+</html>`;
+}
+function renderedDiffCss() {
+    return `
+:root{--rv-accent:#0B7F7B;--rv-border:#E1E5ED;--rv-text:#193B73;--rv-heading:#032F7B;--rv-muted:#647392;--rv-added:#16794B;--rv-added-soft:#F0FAF4;--rv-added-line:#C7EAD5;--rv-removed:#B4233F;--rv-removed-soft:#FFF5F6;--rv-removed-line:#F3CDD4;--rv-changed:#865A00;--rv-changed-line:#EEDCA9;--rv-page:#F7F8FB;color-scheme:light}
+*{box-sizing:border-box}
+html{scroll-behavior:smooth}
+body.rd-body{margin:0;background:var(--rv-page);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;color:var(--rv-text);-webkit-font-smoothing:antialiased}
+body.rd-body[data-theme='dark']{--rv-border:#334155;--rv-text:#cbd5e1;--rv-heading:#f8fafc;--rv-muted:#94a3b8;--rv-added:#6ee7a8;--rv-added-soft:#102a20;--rv-added-line:#245c43;--rv-removed:#fda4b4;--rv-removed-soft:#32151c;--rv-removed-line:#713141;--rv-changed:#f5cf75;--rv-changed-line:#705a25;--rv-page:#0f172a;color-scheme:dark}
+body.rd-body[data-theme='dark'] .rd-none,body.rd-body[data-theme='dark'] .rd-head,body.rd-body[data-theme='dark'] .rd-cell{background:#172033}
+.rd-notice{margin:16px 18px 0;padding:10px 14px;border-radius:7px;background:#FFFAEB;border:1px solid var(--rv-changed-line);color:var(--rv-changed);font-size:12.5px;font-weight:600}
+.rd-none{margin:18px auto;max-width:560px;padding:22px;text-align:center;border:1px solid var(--rv-border);border-radius:8px;color:var(--rv-muted);font-size:13px;background:#fff}
+
+.rd-scroll{padding:14px 16px 64px}
+.rd-heads{position:sticky;top:0;z-index:15;display:grid;grid-template-columns:1fr 1fr;gap:10px;padding:6px 0 10px;background:linear-gradient(180deg,var(--rv-page) 70%,rgba(247,248,246,0))}
+body.rd-body[data-mode='unified'] .rd-heads{display:none}
+.rd-head{display:flex;align-items:center;gap:7px;font-size:12px;font-weight:600;color:var(--rv-muted)}
+.rd-dot{width:8px;height:8px;border-radius:50%}
+.rd-dot--before{background:#B3BAC5}
+.rd-dot--after{background:var(--rv-accent)}
+
+/* The reader stylesheet paints its own page background; the comparison supplies
+   the surface instead, so it is cleared for both themes. */
+.rd-root,.rd-root[data-color-theme='light'],.rd-root[data-color-theme='dark']{min-height:0;background:transparent;background-image:none;display:flex;flex-direction:column;gap:2px}
+.rd-row{display:grid;grid-template-columns:1fr 1fr;gap:10px;align-items:stretch}
+body.rd-body[data-mode='unified'] .rd-row{grid-template-columns:1fr;gap:0}
+body.rd-body[data-mode='unified'] .rd-row[data-status='equal'] .rd-cell--before{display:none}
+body.rd-body[data-mode='unified'] .rd-row[data-status='changed'] .rd-cell--before{margin-bottom:2px}
+body.rd-body.rd-only-changes .rd-row[data-status='equal']{display:none}
+body.rd-body.rd-only-changes .rd-fold{display:none}
+
+.rd-cell{position:relative;display:flex;gap:10px;padding:6px 14px 6px 0;border-radius:7px;background:#fff;border:1px solid transparent;min-width:0}
+.rd-gutter{width:4px;flex:none;border-radius:4px;background:transparent;margin:6px 0 6px 6px}
+.rd-content{margin-top:0;padding:8px 0;min-width:0;flex:1;overflow-x:auto}
+.rd-content>*:first-child{margin-top:0}
+.rd-content>*:last-child{margin-bottom:0}
+/* Wide blocks scroll inside their own cell instead of being clipped by the
+   column, and identifiers stay whole rather than breaking mid-token. */
+.rd-content{overflow-wrap:normal}
+.rd-content table{min-width:min-content}
+.rd-content code,.rd-content kbd,.rd-content samp{overflow-wrap:normal;word-break:keep-all}
+.rd-content pre{max-width:100%;overflow-x:auto}
+
+.rd-cell[data-status='equal']{background:#fff;border-color:#ECEFEB}
+.rd-cell--before[data-status='changed']{background:var(--rv-removed-soft);border-color:var(--rv-removed-line)}
+.rd-cell--before[data-status='changed'] .rd-gutter{background:var(--rv-removed)}
+.rd-cell--after[data-status='changed']{background:var(--rv-added-soft);border-color:var(--rv-added-line)}
+.rd-cell--after[data-status='changed'] .rd-gutter{background:var(--rv-added)}
+.rd-cell--after[data-status='added']{background:var(--rv-added-soft);border-color:var(--rv-added-line)}
+.rd-cell--after[data-status='added'] .rd-gutter{background:var(--rv-added)}
+.rd-cell--before[data-status='removed']{background:var(--rv-removed-soft);border-color:var(--rv-removed-line)}
+.rd-cell--before[data-status='removed'] .rd-gutter{background:var(--rv-removed)}
+.rd-cell--before[data-status='added'],.rd-cell--after[data-status='removed']{background:repeating-linear-gradient(45deg,#FBFCFD,#FBFCFD 8px,#F2F5F8 8px,#F2F5F8 16px);border-color:#EEF1F5}
+.rd-empty{padding:14px 2px;font-size:12px;font-style:italic;color:#8B94A5}
+
+.rd-word{border-radius:3px;padding:0 2px;background:transparent;color:inherit;font-weight:inherit}
+.rd-cell--after .rv-word--ins,.rv-word--ins{background:#CBF4C9;color:var(--rv-added);border-radius:3px;padding:0 2px;box-decoration-break:clone;-webkit-box-decoration-break:clone}
+.rd-cell--before .rv-word--del,.rv-word--del{background:#FDE2DD;color:var(--rv-removed);border-radius:3px;padding:0 2px;box-decoration-break:clone;-webkit-box-decoration-break:clone}
+
+.rd-fold{margin:2px 0}
+.rd-fold-summary{list-style:none;display:flex;align-items:center;gap:12px;cursor:pointer;padding:6px 4px;user-select:none}
+.rd-fold-summary::-webkit-details-marker{display:none}
+.rd-fold-line{flex:1;height:1px;background:linear-gradient(90deg,transparent,var(--rv-border) 20%,var(--rv-border) 80%,transparent)}
+.rd-fold-label{font-size:11.5px;font-weight:600;color:#8B94A5;white-space:nowrap;padding:3px 10px;border:1px solid var(--rv-border);border-radius:100px;background:#fff}
+.rd-fold[open] .rd-fold-label{color:var(--rv-muted)}
+.rd-fold-body{display:flex;flex-direction:column;gap:2px;margin-top:2px}
+.rd-render-error{color:#B91C1C}
+
+.rd-cell-tag{display:none;margin-bottom:8px;padding:2px 8px;border-radius:5px;font-size:11px;font-weight:600;border:1px solid var(--rv-border);color:var(--rv-muted);background:#fff}
+.rd-cell--before .rd-cell-tag{border-color:var(--rv-removed-line);color:var(--rv-removed)}
+.rd-cell--after .rd-cell-tag{border-color:var(--rv-added-line);color:var(--rv-added)}
+body.rd-body[data-mode='unified'] .rd-cell-tag{display:inline-block}
+body.rd-body[data-mode='unified'] .rd-row[data-status='equal'] .rd-cell-tag{display:none}
+
+/* Below this width the two columns cannot sit side by side, so the comparison
+   stacks and every cell names the side it belongs to. */
+@media(max-width:640px){
+  .rd-row{grid-template-columns:1fr;gap:2px}
+  .rd-heads{display:none}
+  .rd-cell-tag{display:inline-block}
+  .rd-row[data-status='equal'] .rd-cell--before{display:none}
+  .rd-row[data-status='equal'] .rd-cell-tag{display:none}
+}
+  `;
+}
+//# sourceMappingURL=review-render.js.map

package/dist/review-report.d.ts

@@ -0,0 +1,9 @@
+import type { AgentName, DocumentationReviewReport } from './types.js';
+export declare function persistReviewReport(root: string, output: string, execution: {
+    agent: AgentName;
+    model?: string;
+    reasoning?: string;
+}): Promise<DocumentationReviewReport>;
+export declare function listReviewReports(root: string): Promise<DocumentationReviewReport[]>;
+export declare function parseReviewReport(output: string): Pick<DocumentationReviewReport, 'score' | 'hardGates' | 'summary' | 'findings'>;
+//# sourceMappingURL=review-report.d.ts.map

package/dist/review-report.js

@@ -0,0 +1,89 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const REVIEW_DIRECTORY = join('.doxloop', 'reviews');
+export async function persistReviewReport(root, output, execution) {
+    const parsed = parseReviewReport(output);
+    const report = {
+        schemaVersion: 1,
+        id: `review-${Date.now()}-${randomBytes(3).toString('hex')}`,
+        createdAt: new Date().toISOString(),
+        agent: execution.agent,
+        ...(execution.model ? { model: execution.model } : {}),
+        ...(execution.reasoning ? { reasoning: execution.reasoning } : {}),
+        ...parsed,
+    };
+    const directory = join(root, REVIEW_DIRECTORY);
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, `${report.id}.json`), `${JSON.stringify(report, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    return report;
+}
+export async function listReviewReports(root) {
+    let entries;
+    try {
+        entries = await readdir(join(root, REVIEW_DIRECTORY), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const reports = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !/^review-[a-z0-9-]+\.json$/.test(entry.name))
+            continue;
+        try {
+            const raw = JSON.parse(await readFile(join(root, REVIEW_DIRECTORY, entry.name), 'utf8'));
+            if (isReviewReport(raw))
+                reports.push(raw);
+        }
+        catch { /* A damaged operational report does not hide other reviews. */ }
+    }
+    return reports.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+export function parseReviewReport(output) {
+    const structured = /<doxloop-review>\s*([\s\S]*?)\s*<\/doxloop-review>/i.exec(output)?.[1];
+    if (structured) {
+        try {
+            const raw = JSON.parse(structured);
+            const findings = Array.isArray(raw.findings) ? raw.findings.flatMap(normalizeFinding).slice(0, 50) : [];
+            return { score: boundedScore(raw.score), hardGates: gate(raw.hardGates), summary: text(raw.summary) || summaryFromOutput(output), findings };
+        }
+        catch { /* Fall through to the safe Markdown parser. */ }
+    }
+    const scoreMatch = /(?:quality|rubric|overall)?\s*score[^\d]{0,20}(\d{1,3})(?:\s*\/\s*100|%)/i.exec(output);
+    const gateMatch = /hard[- ]?gates?[^\n]*(pass|fail)/i.exec(output)?.[1]?.toLowerCase();
+    const findings = output.split(/\r?\n/).flatMap((line, index) => {
+        const match = /^\s*(?:[-*]|\d+\.)\s*(?:(blocker|major|minor)\s*[:—-]\s*)?(.{12,})$/i.exec(line);
+        if (!match?.[2])
+            return [];
+        const severity = (match[1]?.toLowerCase() ?? inferSeverity(match[2]));
+        return [{ id: `finding-${index + 1}`, severity, title: match[2].slice(0, 120), description: match[2], pages: pageReferences(match[2]), evidence: [], recommendation: match[2] }];
+    }).slice(0, 50);
+    return { score: scoreMatch ? boundedScore(Number(scoreMatch[1])) : 0, hardGates: gateMatch === 'pass' ? 'pass' : gateMatch === 'fail' ? 'fail' : 'unknown', summary: summaryFromOutput(output), findings };
+}
+function normalizeFinding(value, index) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    const raw = value;
+    const title = text(raw.title);
+    if (!title)
+        return [];
+    return [{ id: text(raw.id) || `finding-${index + 1}`, severity: severity(raw.severity), title, description: text(raw.description) || title, pages: textList(raw.pages), evidence: textList(raw.evidence), recommendation: text(raw.recommendation) || title }];
+}
+function summaryFromOutput(output) {
+    const line = output.split(/\r?\n/).map((item) => item.replace(/^#+\s*/, '').trim()).find((item) => item.length >= 20 && !item.startsWith('{') && !item.startsWith('<'));
+    return line?.slice(0, 500) ?? 'The review completed without a structured summary.';
+}
+function pageReferences(value) { return [...new Set(value.match(/[\w./-]+\.(?:md|mdx|rst|html)/gi) ?? [])]; }
+function inferSeverity(value) { return /block|critical|security|broken/i.test(value) ? 'blocker' : /missing|incorrect|major|stale/i.test(value) ? 'major' : 'minor'; }
+function severity(value) { return value === 'blocker' || value === 'major' ? value : 'minor'; }
+function boundedScore(value) { const number = typeof value === 'number' ? value : Number(value); return Number.isFinite(number) ? Math.max(0, Math.min(100, Math.round(number))) : 0; }
+function gate(value) { return value === 'pass' || value === 'fail' ? value : 'unknown'; }
+function text(value) { return typeof value === 'string' ? value.trim() : ''; }
+function textList(value) { return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim() !== '').map((item) => item.trim()) : []; }
+function isReviewReport(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const report = value;
+    return report.schemaVersion === 1 && typeof report.id === 'string' && typeof report.createdAt === 'string' && typeof report.agent === 'string' && typeof report.score === 'number' && ['pass', 'fail', 'unknown'].includes(report.hardGates ?? '') && typeof report.summary === 'string' && Array.isArray(report.findings);
+}
+//# sourceMappingURL=review-report.js.map

package/dist/review-ui.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The review center: four screens joined by real URLs.
+ *
+ *   /                       the proposals waiting for a decision
+ *   /runs/:id               what one proposal changes, and why
+ *   /runs/:id/pages/:n      one page at a time, current beside proposed
+ *   /runs/:id/done          what was applied
+ *
+ * The reading screen carries one bar above the comparison and one below it;
+ * everything else lives on the screen where it belongs.
+ */
+export declare function icon(name: string, size?: number): string;
+export declare function reviewDocument(token: string): string;
+//# sourceMappingURL=review-ui.d.ts.map