@bookedsolid/rea 0.40.0 → 0.42.0

package/dist/cli/install/unified-diff.js

@@ -0,0 +1,270 @@
+/**
+ * Minimal LCS-based unified-diff renderer (0.41.0).
+ *
+ * Used by `rea upgrade --check` to emit a per-file preview of what the
+ * upgrade flow WOULD change. We deliberately ship our own implementation
+ * rather than pulling in the `diff` npm package — REA's dependency
+ * footprint is small and load-bearing, and the upgrade-check preview is
+ * the only consumer.
+ *
+ * Output shape mirrors `diff -u`:
+ *
+ *     --- a/path/to/file
+ *     +++ b/path/to/file
+ *     @@ -1,3 +1,4 @@
+ *      context line
+ *     -removed line
+ *     +added line
+ *      context line
+ *
+ * Hunks are constructed greedily — adjacent changed regions within
+ * `contextLines` of each other are merged into a single hunk so a
+ * reviewer reading the output doesn't have to mentally stitch tiny
+ * back-to-back hunks together.
+ *
+ * Performance: classic O(n*m) LCS with two parallel `Uint32Array`s for
+ * the DP table. Files in the upgrade-check path are bounded at
+ * `DIFF_SIZE_CAP_BYTES` (256 KiB) by callers, so even the worst-case
+ * shape (256 KiB of single-character lines) stays inside the addressable
+ * range of `Uint32Array` indices (~4 GiB worth of cells). The caller is
+ * responsible for refusing to diff files larger than the cap; this
+ * module trusts its inputs.
+ *
+ * Newline handling: we split on `\n` only. A file with `\r\n` line
+ * endings will surface as one big changed block if compared against a
+ * `\n`-ending canonical, which is the right behavior — line endings
+ * differing IS a real difference. We do not normalize.
+ */
+const DEFAULT_CONTEXT_LINES = 3;
+/**
+ * Hard cap on the DP-table cell count. The O(m*n) LCS table is the
+ * dominant memory cost; with a 4-byte `Uint32Array` cell, this works
+ * out to ~16 MiB of allocation at the cap. We deliberately key off
+ * cell COUNT, not file bytes — codex round-1 P1 flagged that the
+ * 256 KiB byte cap callers enforce can still produce pathological
+ * matrices when files are mostly single-character lines (200 KiB of
+ * one-char lines = 200K lines = 40 GiB of cells).
+ *
+ * Exported so callers can detect the "too large to diff" verdict
+ * structurally instead of grepping the returned string.
+ */
+export const MAX_LCS_CELLS = 4_000_000;
+/**
+ * Sentinel returned in place of a real diff when the line counts
+ * would blow past `MAX_LCS_CELLS`. Wrapped in a recognizable comment
+ * shape so consumers grepping the diff body see a clear notice.
+ */
+export const DIFF_TOO_LARGE_NOTICE = '# rea: diff suppressed — file pair too large for the LCS matrix budget\n';
+/**
+ * Compute the LCS table for two line arrays. Cell (i, j) is the length
+ * of the longest common subsequence of `a[0..i)` and `b[0..j)`.
+ *
+ * Returns a row-major `Uint32Array` of size `(a.length + 1) * (b.length + 1)`.
+ */
+function lcsTable(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const rowStride = n + 1;
+    const table = new Uint32Array((m + 1) * rowStride);
+    for (let i = 1; i <= m; i += 1) {
+        const rowBase = i * rowStride;
+        const prevRowBase = (i - 1) * rowStride;
+        for (let j = 1; j <= n; j += 1) {
+            if (a[i - 1] === b[j - 1]) {
+                table[rowBase + j] = table[prevRowBase + (j - 1)] + 1;
+            }
+            else {
+                const up = table[prevRowBase + j];
+                const left = table[rowBase + (j - 1)];
+                table[rowBase + j] = up >= left ? up : left;
+            }
+        }
+    }
+    return table;
+}
+/**
+ * Walk the LCS table backwards to produce the ordered diff op sequence.
+ */
+function backtrackOps(a, b, table) {
+    const ops = [];
+    const rowStride = b.length + 1;
+    let i = a.length;
+    let j = b.length;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && a[i - 1] === b[j - 1]) {
+            ops.push({ kind: 'context', text: a[i - 1] });
+            i -= 1;
+            j -= 1;
+            continue;
+        }
+        const up = i > 0 ? table[(i - 1) * rowStride + j] : -1;
+        const left = j > 0 ? table[i * rowStride + (j - 1)] : -1;
+        if (j > 0 && (i === 0 || left >= up)) {
+            ops.push({ kind: 'add', text: b[j - 1] });
+            j -= 1;
+        }
+        else {
+            ops.push({ kind: 'remove', text: a[i - 1] });
+            i -= 1;
+        }
+    }
+    ops.reverse();
+    return ops;
+}
+/**
+ * Group ops into hunks. A hunk covers a contiguous changed region plus
+ * `contextLines` of context on each side. Two adjacent changed regions
+ * separated by fewer than `2 * contextLines` context lines are merged
+ * into a single hunk (the shared context belongs to both).
+ */
+function buildHunks(ops, contextLines) {
+    // First pass: collect indices of every change op.
+    const changedIndices = [];
+    for (let i = 0; i < ops.length; i += 1) {
+        if (ops[i].kind !== 'context')
+            changedIndices.push(i);
+    }
+    if (changedIndices.length === 0)
+        return [];
+    const windows = [];
+    for (const idx of changedIndices) {
+        const winStart = Math.max(0, idx - contextLines);
+        const winEnd = Math.min(ops.length, idx + 1 + contextLines);
+        const last = windows.length > 0 ? windows[windows.length - 1] : null;
+        if (last !== null && winStart <= last.end) {
+            last.end = Math.max(last.end, winEnd);
+        }
+        else {
+            windows.push({ start: winStart, end: winEnd });
+        }
+    }
+    // Convert windows to hunks with correct old/new line numbers.
+    // Track 1-based line cursors as we walk the full ops array.
+    const hunks = [];
+    let oldLine = 1;
+    let newLine = 1;
+    let opIdx = 0;
+    for (const win of windows) {
+        while (opIdx < win.start) {
+            const op = ops[opIdx];
+            if (op.kind === 'context') {
+                oldLine += 1;
+                newLine += 1;
+            }
+            else if (op.kind === 'remove') {
+                oldLine += 1;
+            }
+            else {
+                newLine += 1;
+            }
+            opIdx += 1;
+        }
+        const hunkOldStart = oldLine;
+        const hunkNewStart = newLine;
+        let hunkOldLines = 0;
+        let hunkNewLines = 0;
+        const hunkOps = [];
+        while (opIdx < win.end) {
+            const op = ops[opIdx];
+            hunkOps.push(op);
+            if (op.kind === 'context') {
+                hunkOldLines += 1;
+                hunkNewLines += 1;
+                oldLine += 1;
+                newLine += 1;
+            }
+            else if (op.kind === 'remove') {
+                hunkOldLines += 1;
+                oldLine += 1;
+            }
+            else {
+                hunkNewLines += 1;
+                newLine += 1;
+            }
+            opIdx += 1;
+        }
+        hunks.push({
+            oldStart: hunkOldStart,
+            oldLines: hunkOldLines,
+            newStart: hunkNewStart,
+            newLines: hunkNewLines,
+            ops: hunkOps,
+        });
+    }
+    return hunks;
+}
+/**
+ * Render hunks in unified-diff format. Header lines name the old and new
+ * paths via `--- a/<oldPath>` / `+++ b/<newPath>`, the same convention
+ * `diff -u` uses.
+ *
+ * When both files are identical, returns an empty string — the caller
+ * decides whether to emit a "no changes" notice.
+ */
+function renderHunks(oldPath, newPath, hunks) {
+    if (hunks.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`--- a/${oldPath}`);
+    lines.push(`+++ b/${newPath}`);
+    for (const hunk of hunks) {
+        // Unified-diff convention: a hunk that contains zero lines on one
+        // side renders `0,0` for that side's count. Empty single-line hunks
+        // render `N` without a comma (`@@ -5 +5,2 @@`). We always emit the
+        // comma form for simplicity — `diff -u` accepts it.
+        lines.push(`@@ -${String(hunk.oldStart)},${String(hunk.oldLines)} +${String(hunk.newStart)},${String(hunk.newLines)} @@`);
+        for (const op of hunk.ops) {
+            if (op.kind === 'context')
+                lines.push(` ${op.text}`);
+            else if (op.kind === 'add')
+                lines.push(`+${op.text}`);
+            else
+                lines.push(`-${op.text}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Compute a unified diff between two text blobs.
+ *
+ * Returns the empty string when the two inputs are byte-identical. The
+ * caller decides whether to wrap that in a "no changes" notice.
+ *
+ * Splits on `\n` and drops a single trailing `\n` if present so the
+ * final line is not phantom-blank. A file that genuinely ends without
+ * a newline will appear identical to one that ends with a single
+ * newline — REA's canonical files all end with `\n`, so this is fine
+ * for our use case. Callers that need strict-EOL fidelity should
+ * normalize upstream.
+ */
+export function diffUnified(oldText, newText, options = {}) {
+    if (oldText === newText)
+        return '';
+    const oldPath = options.oldPath ?? 'file';
+    const newPath = options.newPath ?? oldPath;
+    const contextLines = options.contextLines ?? DEFAULT_CONTEXT_LINES;
+    // Drop one trailing newline so split() doesn't produce a phantom empty
+    // line at the end. We compare the trailing-stripped forms; the diff
+    // header doesn't track EOL state because callers don't.
+    const oldNorm = oldText.endsWith('\n') ? oldText.slice(0, -1) : oldText;
+    const newNorm = newText.endsWith('\n') ? newText.slice(0, -1) : newText;
+    // Empty file → empty array of lines.
+    const oldLines = oldNorm.length === 0 ? [] : oldNorm.split('\n');
+    const newLines = newNorm.length === 0 ? [] : newNorm.split('\n');
+    // Codex round-1 P1: guard against pathological line-count blowups
+    // BEFORE allocating the DP table. Cell count grows as
+    // (m+1)*(n+1) — a 200 KiB file of one-character lines is well
+    // inside any reasonable byte cap but would allocate gigabytes of
+    // Uint32 cells. Return a sentinel comment the caller can detect
+    // and surface as "too large to render" instead of OOMing.
+    const cellCount = (oldLines.length + 1) * (newLines.length + 1);
+    if (cellCount > MAX_LCS_CELLS) {
+        return (`--- a/${oldPath}\n` +
+            `+++ b/${newPath}\n` +
+            DIFF_TOO_LARGE_NOTICE);
+    }
+    const table = lcsTable(oldLines, newLines);
+    const ops = backtrackOps(oldLines, newLines, table);
+    const hunks = buildHunks(ops, contextLines);
+    return renderHunks(oldPath, newPath, hunks);
+}

package/dist/cli/upgrade-check.d.ts

@@ -0,0 +1,187 @@
+/**
+ * `rea upgrade --check` — 0.41.0 consumer-UX dry-run preview.
+ *
+ * Today `rea upgrade` rewrites consumer files immediately (gated by
+ * interactive prompts and `--dry-run` for a coarse preview). There has
+ * been no way to PREVIEW what would change, file-by-file, with the
+ * actual textual delta, before running the real upgrade. `--check`
+ * fills that gap.
+ *
+ * # Contract
+ *
+ * - Reads the same canonical file set as `rea upgrade`, classifies it
+ *   against the installed manifest, and emits a summary table of
+ *   counts (created / modified / unchanged / removed-upstream) plus a
+ *   unified diff per modified file.
+ * - Never writes to disk. The classification phase is pure; nothing
+ *   downstream of `computeUpgradePlan` mutates the filesystem.
+ * - Exits 0 regardless of what would change — `--check` is a preview,
+ *   not an enforcement gate. Consumers wiring `rea upgrade --check`
+ *   into CI gate on diff-present via the JSON output (`--json`).
+ * - Distinct from `--dry-run`: `--dry-run` runs the FULL interactive
+ *   upgrade flow with writes suppressed (prompts still fire, output
+ *   still streams in classification order). `--check` is purely
+ *   structured, non-interactive, and emits the unified diffs that
+ *   `--dry-run` does not.
+ *
+ * # JSON output
+ *
+ * `--json` emits a single document with shape:
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "rea_version": "0.41.0",
+ *       "target_root": "/abs/path/to/repo",
+ *       "bootstrap": false,
+ *       "counts": { "created": 1, "modified": 3, "unchanged": 47,
+ *                   "removed_upstream": 0 },
+ *       "files": [
+ *         { "path": "hooks/foo.sh", "action": "modified",
+ *           "old_sha": "…", "new_sha": "…", "diff": "--- …\n+++ …\n…" },
+ *         …
+ *       ]
+ *     }
+ *
+ * `diff` is included for `created` (showing full content as additions),
+ * `modified` (true unified diff), and `removed_upstream` (showing the
+ * full content as removals). It is omitted for `unchanged`.
+ *
+ * # Why not extend `--dry-run`?
+ *
+ * `--dry-run` already serves a different purpose: rehearse the full
+ * upgrade flow in interactive mode. Bolting structured output onto it
+ * would either change its existing output shape (breaking pipelines)
+ * or fork it into two output paths anyway. A new flag is cleaner.
+ */
+import { type CanonicalFile } from './install/canonical.js';
+/** Hard cap on the diff input size. Mirrors `DIFF_SIZE_CAP_BYTES` in
+ *  upgrade.ts so the two preview surfaces agree on the "too big to
+ *  render" threshold. */
+export declare const CHECK_DIFF_SIZE_CAP_BYTES: number;
+/**
+ * Stable schema marker for the JSON document. Bumped when the shape
+ * changes in a non-additive way.
+ */
+export declare const UPGRADE_CHECK_SCHEMA_VERSION = 1;
+/**
+ * Tokens for hook commands that older rea versions registered into
+ * `.claude/settings.json` and that the upgrade flow PRUNES on every
+ * run. Mirrors `STALE_HOOK_COMMAND_TOKENS` in `upgrade.ts` — kept in
+ * sync because both modules want to anticipate the same prune set.
+ *
+ * Re-exported by upgrade.ts so the actual write path uses the same
+ * list.
+ */
+export declare const UPGRADE_CHECK_STALE_HOOK_TOKENS: readonly string[];
+export type UpgradeCheckAction = 'created' | 'modified' | 'unchanged' | 'removed_upstream';
+export interface UpgradeCheckFile {
+    /** Repo-relative path of the file (POSIX-normalized). */
+    path: string;
+    action: UpgradeCheckAction;
+    /** Synthetic entries (settings.json subset hash, CLAUDE.md fragment,
+     *  .gitignore managed block) are flagged so the renderer can label
+     *  them in the table. */
+    synthetic?: 'settings' | 'claude-md' | 'gitignore';
+    /** SHA-256 of the on-disk content at preview time, when present. */
+    old_sha?: string;
+    /** SHA-256 of the would-be-installed content. */
+    new_sha?: string;
+    /** Unified diff body. Empty string for `unchanged`. May be omitted
+     *  when the file exceeds `CHECK_DIFF_SIZE_CAP_BYTES` — `diff_truncated`
+     *  is then `true`. */
+    diff?: string;
+    /** Set when the diff was suppressed for size. Operators inspect the
+     *  files manually in this case. */
+    diff_truncated?: boolean;
+    /** Free-form notice the renderer should display alongside the file
+     *  row (e.g. "removed-upstream — kept by default unless --force"). */
+    note?: string;
+}
+/**
+ * 0.42.0 charter item 2 — surface the same settings-schema validation
+ * the real upgrade flow runs. `runUpgrade` calls `validateSettings`
+ * on the merged result and refuses the write (throws) when it fails;
+ * pre-0.42.0 `rea upgrade --check` never invoked that check, so a
+ * preview could promise a write that the real upgrade would refuse.
+ *
+ *   - `parsed: true` — schema validation succeeded; `errors` is empty.
+ *     The real upgrade WOULD write the merged settings on demand.
+ *   - `parsed: false` — schema validation failed. `errors` carries the
+ *     same zod-issue strings `runUpgrade` would surface in its throw
+ *     message. The real upgrade would refuse and leave settings.json
+ *     untouched.
+ */
+export interface UpgradeCheckSettingsValidation {
+    parsed: boolean;
+    errors: string[];
+}
+export interface UpgradeCheckPlan {
+    schema_version: typeof UPGRADE_CHECK_SCHEMA_VERSION;
+    rea_version: string;
+    target_root: string;
+    /** `true` when no install-manifest exists; the consumer is on a
+     *  pre-G12 install and the first real upgrade will record SHAs
+     *  for whatever is on disk. */
+    bootstrap: boolean;
+    counts: {
+        created: number;
+        modified: number;
+        unchanged: number;
+        removed_upstream: number;
+    };
+    files: UpgradeCheckFile[];
+    /** 0.42.0 — schema-validation outcome on the merged settings.json
+     *  the real `rea upgrade` would write. `null` when the synthetic
+     *  settings classification did not produce a merged result (should
+     *  not happen in practice; defensive). */
+    settings_validation: UpgradeCheckSettingsValidation | null;
+    /**
+     * 0.42.0 codex round 3 P2 (2026-05-16) — top-level "preview = real"
+     * verdict. `true` when `rea upgrade` would actually start mutating
+     * the install; `false` when the new pre-flight (settings-validation)
+     * gate would refuse the upgrade before any file is written.
+     *
+     * Why this matters: `counts` + `files` still describe what WOULD be
+     * written if validation passed (operators want the diff so they can
+     * fix the underlying invalid setting and see the upgrade preview in
+     * one shot). But CI and automation consuming the JSON need a single
+     * unambiguous signal that the real upgrade will write nothing in
+     * the current state. Use `would_apply` as that signal; treat
+     * `files[]` + `counts` as conditional on `would_apply === true`.
+     */
+    would_apply: boolean;
+}
+export interface ComputeUpgradeCheckOptions {
+    /** Defaults to `process.cwd()`. */
+    baseDir?: string;
+    /** Tests can stub the canonical file enumeration; production reads
+     *  from `PKG_ROOT`. */
+    canonicalFiles?: CanonicalFile[];
+    /** When `false`, skips the unified-diff computation (counts + paths
+     *  only). Default `true`. Useful for very large repos previewed in
+     *  CI where the diffs are not consumed. */
+    includeDiffs?: boolean;
+}
+/**
+ * Compute the full upgrade-check plan. Pure (filesystem reads only —
+ * no writes). All synthetic entries (CLAUDE.md fragment, settings
+ * subset hash, .gitignore managed block) are included alongside the
+ * canonical-file classifications.
+ */
+export declare function computeUpgradeCheck(options?: ComputeUpgradeCheckOptions): Promise<UpgradeCheckPlan>;
+/**
+ * Render the plan as a human-readable summary block. Designed for
+ * terminal consumption — counts table on top, then a per-file section
+ * with the diff body indented.
+ */
+export declare function renderUpgradeCheck(plan: UpgradeCheckPlan): string;
+export interface RunUpgradeCheckOptions {
+    json?: boolean;
+    /** Strip `diff` bodies from output (counts + paths only). */
+    noDiff?: boolean;
+}
+/**
+ * Commander entrypoint for `rea upgrade --check`. Always exits 0 —
+ * `--check` is a preview, not a gate.
+ */
+export declare function runUpgradeCheck(options?: RunUpgradeCheckOptions): Promise<void>;