@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/review-diff.js

@@ -0,0 +1,400 @@
+/**
+ * Diff primitives for the local review center.
+ *
+ * Two kinds of diff are produced here. `unifiedRows` turns the stored proposal
+ * hunks back into a reviewable unified diff with surrounding context and
+ * word-level emphasis, and `alignBlocks`/`markHtmlWordDiff` line up the two
+ * rendered versions of a page so a reader can compare them side by side without
+ * reading Markdown at all.
+ */
+/** Guard so a pathological file cannot allocate a huge LCS table. */
+const MAX_TABLE_CELLS = 4_000_000;
+/** Longest-common-subsequence diff over pre-computed comparison keys. */
+export function diffKeys(before, after) {
+    const spans = [];
+    const push = (type, bs, be, as, ae) => {
+        if (bs === be && as === ae)
+            return;
+        const last = spans.at(-1);
+        if (last?.type === type) {
+            last.beforeEnd = be;
+            last.afterEnd = ae;
+            return;
+        }
+        spans.push({ type, beforeStart: bs, beforeEnd: be, afterStart: as, afterEnd: ae });
+    };
+    // Trimming the shared head and tail keeps the table small for the common case
+    // of a one-line edit inside a long file.
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head += 1;
+    let tail = 0;
+    while (tail < before.length - head &&
+        tail < after.length - head &&
+        before[before.length - 1 - tail] === after[after.length - 1 - tail]) {
+        tail += 1;
+    }
+    const oldMid = before.slice(head, before.length - tail);
+    const newMid = after.slice(head, after.length - tail);
+    push('equal', 0, head, 0, head);
+    if (oldMid.length === 0 || newMid.length === 0 ||
+        (oldMid.length + 1) * (newMid.length + 1) > MAX_TABLE_CELLS) {
+        push('delete', head, head + oldMid.length, head, head);
+        push('insert', head + oldMid.length, head + oldMid.length, head, head + newMid.length);
+    }
+    else {
+        const table = Array.from({ length: oldMid.length + 1 }, () => new Uint32Array(newMid.length + 1));
+        for (let old = oldMid.length - 1; old >= 0; old -= 1) {
+            for (let next = newMid.length - 1; next >= 0; next -= 1) {
+                table[old][next] = oldMid[old] === newMid[next]
+                    ? table[old + 1][next + 1] + 1
+                    : Math.max(table[old + 1][next], table[old][next + 1]);
+            }
+        }
+        let old = 0;
+        let next = 0;
+        while (old < oldMid.length || next < newMid.length) {
+            if (old < oldMid.length && next < newMid.length && oldMid[old] === newMid[next]) {
+                push('equal', head + old, head + old + 1, head + next, head + next + 1);
+                old += 1;
+                next += 1;
+            }
+            else if (old < oldMid.length &&
+                (next >= newMid.length || table[old + 1][next] >= table[old][next + 1])) {
+                // Removals are emitted before the additions that replace them so a
+                // consumer can pair the two into a single before/after comparison.
+                push('delete', head + old, head + old + 1, head + next, head + next);
+                old += 1;
+            }
+            else {
+                push('insert', head + old, head + old, head + next, head + next + 1);
+                next += 1;
+            }
+        }
+    }
+    const beforeTailStart = before.length - tail;
+    const afterTailStart = after.length - tail;
+    push('equal', beforeTailStart, before.length, afterTailStart, after.length);
+    return spans;
+}
+/**
+ * Rebuild a reviewable unified diff from the proposal's stored hunks. The hunks
+ * only carry the changed lines, so the surrounding context comes from the
+ * snapshot of the file taken when the proposal was generated.
+ */
+export function unifiedRows(beforeText, hunks, options = {}) {
+    const context = options.context ?? 3;
+    const lines = textLines(beforeText);
+    const rows = [];
+    let added = 0;
+    let removed = 0;
+    let oldCursor = 0;
+    let newCursor = 0;
+    /**
+     * `leading` marks a run that follows a change (keep its first lines) and
+     * `trailing` a run that precedes one (keep its last lines). A run with
+     * neither — a file without changes — is shown in full.
+     */
+    const emitContext = (from, to, leading, trailing) => {
+        const count = to - from;
+        if (count <= 0)
+            return;
+        const head = leading ? Math.min(context, count) : trailing ? 0 : count;
+        const tail = trailing ? Math.min(context, count) : 0;
+        if (head + tail >= count) {
+            for (let index = from; index < to; index += 1) {
+                rows.push({
+                    type: 'context',
+                    oldNumber: index + 1,
+                    newNumber: newCursor + (index - from) + 1,
+                    html: escapeHtml(lines[index] ?? ''),
+                });
+            }
+            newCursor += count;
+            return;
+        }
+        for (let index = from; index < from + head; index += 1) {
+            rows.push({
+                type: 'context',
+                oldNumber: index + 1,
+                newNumber: newCursor + (index - from) + 1,
+                html: escapeHtml(lines[index] ?? ''),
+            });
+        }
+        rows.push({ type: 'gap', html: '', hidden: count - head - tail });
+        for (let index = to - tail; index < to; index += 1) {
+            rows.push({
+                type: 'context',
+                oldNumber: index + 1,
+                newNumber: newCursor + (index - from) + 1,
+                html: escapeHtml(lines[index] ?? ''),
+            });
+        }
+        newCursor += count;
+    };
+    for (const [position, hunk] of hunks.entries()) {
+        emitContext(oldCursor, hunk.oldStart, position > 0, true);
+        oldCursor = hunk.oldStart;
+        newCursor = hunk.newStart;
+        const state = hunk.acceptedAt ? 'accepted' : hunk.rejectedAt ? 'rejected' : 'pending';
+        const pairs = pairChangedLines(hunk.oldLines, hunk.newLines);
+        for (const [index, line] of hunk.oldLines.entries()) {
+            const partner = pairs.get(index);
+            rows.push({
+                type: 'delete',
+                oldNumber: oldCursor + index + 1,
+                html: partner === undefined ? escapeHtml(line) : wordDiffText(line, partner).before,
+                hunkId: hunk.id,
+                hunkState: state,
+            });
+            removed += 1;
+        }
+        for (const [index, line] of hunk.newLines.entries()) {
+            const partner = pairs.has(index) ? hunk.oldLines[index] : undefined;
+            rows.push({
+                type: 'insert',
+                newNumber: newCursor + index + 1,
+                html: partner === undefined ? escapeHtml(line) : wordDiffText(partner, line).after,
+                hunkId: hunk.id,
+                hunkState: state,
+            });
+            added += 1;
+        }
+        oldCursor = hunk.oldStart + hunk.oldLines.length;
+        newCursor = hunk.newStart + hunk.newLines.length;
+    }
+    emitContext(oldCursor, lines.length, hunks.length > 0, false);
+    return { rows, added, removed };
+}
+/**
+ * Pair a removed line with the added line that replaced it, so the two can be
+ * shown with only the differing words highlighted. Only confident matches are
+ * paired; unrelated lines stay whole-line additions and removals.
+ */
+function pairChangedLines(oldLines, newLines) {
+    const pairs = new Map();
+    const count = Math.min(oldLines.length, newLines.length);
+    for (let index = 0; index < count; index += 1) {
+        const before = oldLines[index];
+        const after = newLines[index];
+        if (before !== after && similarity(before, after) >= 0.45)
+            pairs.set(index, after);
+    }
+    return pairs;
+}
+function similarity(before, after) {
+    const left = words(before);
+    const right = words(after);
+    if (left.length === 0 || right.length === 0)
+        return 0;
+    const shared = new Map();
+    for (const word of left)
+        shared.set(word, (shared.get(word) ?? 0) + 1);
+    let common = 0;
+    for (const word of right) {
+        const available = shared.get(word) ?? 0;
+        if (available > 0) {
+            shared.set(word, available - 1);
+            common += 1;
+        }
+    }
+    return (2 * common) / (left.length + right.length);
+}
+/** Word-level diff of two plain-text lines, returned as escaped HTML. */
+export function wordDiffText(before, after) {
+    const left = tokenizeWords(before);
+    const right = tokenizeWords(after);
+    const spans = diffKeys(left, right);
+    let beforeHtml = '';
+    let afterHtml = '';
+    for (const span of spans) {
+        const removedText = left.slice(span.beforeStart, span.beforeEnd).join('');
+        const addedText = right.slice(span.afterStart, span.afterEnd).join('');
+        if (span.type === 'equal') {
+            beforeHtml += escapeHtml(removedText);
+            afterHtml += escapeHtml(addedText);
+            continue;
+        }
+        if (span.type === 'delete' && removedText.trim() !== '') {
+            beforeHtml += `<mark class="rv-word rv-word--del">${escapeHtml(removedText)}</mark>`;
+        }
+        else if (span.type === 'delete') {
+            beforeHtml += escapeHtml(removedText);
+        }
+        if (span.type === 'insert' && addedText.trim() !== '') {
+            afterHtml += `<mark class="rv-word rv-word--ins">${escapeHtml(addedText)}</mark>`;
+        }
+        else if (span.type === 'insert') {
+            afterHtml += escapeHtml(addedText);
+        }
+    }
+    return { before: beforeHtml, after: afterHtml };
+}
+function tokenizeWords(value) {
+    return value.match(/\s+|[A-Za-z0-9_]+|[^\sA-Za-z0-9_]/g) ?? [];
+}
+function words(value) {
+    return value.match(/[A-Za-z0-9_]+/g) ?? [];
+}
+/* ── Rendered HTML diff ───────────────────────────────────────────────── */
+const VOID_ELEMENTS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+/**
+ * Split rendered documentation HTML into its top-level blocks (one paragraph,
+ * heading, code block, callout, table … per entry) so two renderings can be
+ * lined up against each other.
+ */
+export function splitHtmlBlocks(html) {
+    const blocks = [];
+    const pattern = /<!--[\s\S]*?-->|<\/?([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+    let depth = 0;
+    let start = 0;
+    let match;
+    while ((match = pattern.exec(html)) !== null) {
+        if (match[0].startsWith('<!--'))
+            continue;
+        const name = match[1].toLowerCase();
+        const closing = match[0].startsWith('</');
+        const selfClosing = match[2]?.trimEnd().endsWith('/') ?? false;
+        if (VOID_ELEMENTS.has(name) || selfClosing) {
+            if (depth === 0) {
+                blocks.push(html.slice(start, match.index + match[0].length).trim());
+                start = match.index + match[0].length;
+            }
+            continue;
+        }
+        if (closing) {
+            depth -= 1;
+            if (depth <= 0) {
+                depth = 0;
+                blocks.push(html.slice(start, match.index + match[0].length).trim());
+                start = match.index + match[0].length;
+            }
+            continue;
+        }
+        depth += 1;
+    }
+    const rest = html.slice(start).trim();
+    if (rest !== '')
+        blocks.push(rest);
+    return blocks.filter((block) => block !== '');
+}
+/** Visible text of an HTML fragment, used as the block comparison key. */
+export function htmlText(html) {
+    return decodeEntities(html.replace(/<[^>]*>/g, ' '))
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Align the blocks of two rendered pages. Adjacent removals and additions are
+ * paired into a single "changed" row so the reader sees one before/after
+ * comparison instead of two disconnected entries.
+ */
+export function alignBlocks(before, after) {
+    const spans = diffKeys(before.map(blockKey), after.map(blockKey));
+    const rows = [];
+    for (let index = 0; index < spans.length; index += 1) {
+        const span = spans[index];
+        if (span.type === 'equal') {
+            for (let offset = 0; offset < span.beforeEnd - span.beforeStart; offset += 1) {
+                rows.push({
+                    status: 'equal',
+                    before: before[span.beforeStart + offset],
+                    after: after[span.afterStart + offset],
+                });
+            }
+            continue;
+        }
+        if (span.type === 'delete') {
+            const next = spans[index + 1];
+            const removed = before.slice(span.beforeStart, span.beforeEnd);
+            if (next?.type === 'insert') {
+                const inserted = after.slice(next.afterStart, next.afterEnd);
+                const paired = Math.min(removed.length, inserted.length);
+                for (let offset = 0; offset < paired; offset += 1) {
+                    rows.push({ status: 'changed', before: removed[offset], after: inserted[offset] });
+                }
+                for (const block of removed.slice(paired))
+                    rows.push({ status: 'removed', before: block });
+                for (const block of inserted.slice(paired))
+                    rows.push({ status: 'added', after: block });
+                index += 1;
+                continue;
+            }
+            for (const block of removed)
+                rows.push({ status: 'removed', before: block });
+            continue;
+        }
+        for (const block of after.slice(span.afterStart, span.afterEnd)) {
+            rows.push({ status: 'added', after: block });
+        }
+    }
+    return rows;
+}
+function blockKey(html) {
+    const tag = /<\s*([a-zA-Z][\w-]*)/.exec(html)?.[1]?.toLowerCase() ?? 'text';
+    return `${tag}${htmlText(html)}`;
+}
+/**
+ * Highlight the words that differ between two rendered blocks while leaving the
+ * surrounding markup — links, code spans, table cells — intact.
+ */
+export function markHtmlWordDiff(before, after) {
+    const left = tokenizeHtml(before);
+    const right = tokenizeHtml(after);
+    const leftKeys = left.map((token) => (token.tag ? `
${token.value}` : token.value));
+    const rightKeys = right.map((token) => (token.tag ? `
${token.value}` : token.value));
+    const spans = diffKeys(leftKeys, rightKeys);
+    let beforeHtml = '';
+    let afterHtml = '';
+    for (const span of spans) {
+        for (let index = span.beforeStart; index < span.beforeEnd; index += 1) {
+            beforeHtml += wrapToken(left[index], span.type === 'delete' ? 'del' : undefined);
+        }
+        for (let index = span.afterStart; index < span.afterEnd; index += 1) {
+            afterHtml += wrapToken(right[index], span.type === 'insert' ? 'ins' : undefined);
+        }
+    }
+    return { before: beforeHtml, after: afterHtml };
+}
+function tokenizeHtml(html) {
+    const tokens = [];
+    const pattern = /<[^>]*>|\s+|[^\s<]+/g;
+    let match;
+    while ((match = pattern.exec(html)) !== null) {
+        tokens.push({ value: match[0], tag: match[0].startsWith('<') });
+    }
+    return tokens;
+}
+function wrapToken(token, mark) {
+    if (!mark || token.tag || token.value.trim() === '')
+        return token.value;
+    return `<mark class="rv-word rv-word--${mark}">${token.value}</mark>`;
+}
+/* ── Shared helpers ───────────────────────────────────────────────────── */
+export function textLines(text) {
+    if (text === '')
+        return [];
+    const normalized = text.replace(/\r\n/g, '\n');
+    return normalized.endsWith('\n') ? normalized.slice(0, -1).split('\n') : normalized.split('\n');
+}
+export function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#039;');
+}
+function decodeEntities(value) {
+    return value
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"')
+        .replaceAll('&#039;', "'")
+        .replaceAll('&nbsp;', ' ')
+        .replaceAll('&amp;', '&');
+}
+//# sourceMappingURL=review-diff.js.map

package/dist/review-learning.d.ts

@@ -0,0 +1,11 @@
+export declare const REVIEW_PREFERENCES_FILE: string;
+export interface ReviewPreference {
+    id: string;
+    at: string;
+    kind: 'revision' | 'rejection' | 'inline-edit' | 'edit';
+    paths: string[];
+    instruction: string;
+}
+export declare function recordReviewPreference(root: string, preference: Omit<ReviewPreference, 'id' | 'at'>): Promise<void>;
+export declare function reviewPreferenceGuidance(root: string): Promise<string>;
+//# sourceMappingURL=review-learning.d.ts.map

package/dist/review-learning.js

@@ -0,0 +1,60 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureGitignoreEntries, pathExists } from './fs.js';
+export const REVIEW_PREFERENCES_FILE = join('.doxloop', 'review-preferences.json');
+const preferenceQueues = new Map();
+export async function recordReviewPreference(root, preference) {
+    const previous = preferenceQueues.get(root) ?? Promise.resolve();
+    const queued = previous.catch(() => undefined).then(() => persistReviewPreference(root, preference));
+    preferenceQueues.set(root, queued);
+    try {
+        await queued;
+    }
+    finally {
+        if (preferenceQueues.get(root) === queued)
+            preferenceQueues.delete(root);
+    }
+}
+async function persistReviewPreference(root, preference) {
+    const current = await readPreferences(root);
+    const entry = {
+        ...preference,
+        paths: [...new Set(preference.paths.filter((path) => typeof path === 'string').map((path) => path.slice(0, 500)))].slice(0, 100),
+        instruction: redactPreference(preference.instruction).trim().slice(0, 2_000),
+        id: `feedback-${Date.now().toString(36)}`,
+        at: new Date().toISOString(),
+    };
+    if (!entry.instruction)
+        return;
+    const entries = [...current, entry].slice(-100);
+    await ensureGitignoreEntries(root, [REVIEW_PREFERENCES_FILE]);
+    await mkdir(join(root, '.doxloop'), { recursive: true, mode: 0o700 });
+    await writeFile(join(root, REVIEW_PREFERENCES_FILE), `${JSON.stringify({ schemaVersion: 1, entries }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+export async function reviewPreferenceGuidance(root) {
+    const entries = (await readPreferences(root)).slice(-20);
+    if (entries.length === 0)
+        return 'No prior reviewer preferences have been recorded.';
+    return entries.map((entry) => `- ${entry.kind} on ${entry.paths.join(', ') || 'the proposal'}: ${entry.instruction}`).join('\n');
+}
+async function readPreferences(root) {
+    const path = join(root, REVIEW_PREFERENCES_FILE);
+    if (!(await pathExists(path)))
+        return [];
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return value.schemaVersion === 1 && Array.isArray(value.entries) ? value.entries.filter(validPreference) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function validPreference(value) {
+    return !!value && ['revision', 'rejection', 'inline-edit', 'edit'].includes(value.kind) && Array.isArray(value.paths) && value.paths.every((item) => typeof item === 'string') && typeof value.instruction === 'string' && value.instruction.trim() !== '';
+}
+function redactPreference(value) {
+    return value
+        .replace(/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')
+        .replace(/\b(?:gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16})\b/g, '[REDACTED CREDENTIAL]');
+}
+//# sourceMappingURL=review-learning.js.map

package/dist/review-render.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+export interface RenderedSide {
+    title: string;
+    description: string;
+    body: string;
+    exists: boolean;
+}
+export interface RenderedDiffOptions {
+    before: RenderedSide;
+    after: RenderedSide;
+}
+export interface RenderedDiff {
+    html: string;
+    added: number;
+    removed: number;
+    changed: number;
+}
+export declare function renderedDiff(options: RenderedDiffOptions): RenderedDiff;
+export interface ComparisonDocument {
+    diff: RenderedDiff;
+    /** Layout and density are owned by the surrounding screen, not by this frame. */
+    layout: 'split' | 'unified';
+    onlyChanges: boolean;
+    theme: 'light' | 'dark';
+    notice?: string;
+}
+/**
+ * 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 declare function renderedDiffDocument(input: ComparisonDocument): string;
+//# sourceMappingURL=review-render.d.ts.map