comprehende 0.6.1 → 0.8.0

package/dist/review/load.js

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { parseReviewJson } from "../schema/parse.js";
+export async function loadDocument(dataPath) {
+    const text = await readFile(dataPath, "utf8");
+    const parsed = parseReviewJson(text);
+    if (!parsed.ok) {
+        throw new Error(`invalid review document:\n${parsed.errors.map((error) => `  - ${error}`).join("\n")}`);
+    }
+    return parsed.document;
+}
+export function resolveDataPath(data, cwd) {
+    return resolveCliPath(data, cwd, "--data <review.json>");
+}
+export function resolveCliPath(value, cwd, flag) {
+    if (value === undefined) {
+        throw new Error(`missing ${flag}`);
+    }
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}

package/dist/review/pins.js

@@ -1,4 +1,4 @@
-import { fileExistsAt, showFile } from "../git/show.js";
+import { showFile } from "../git/show.js";
 import { isLinePinned, textLineCount } from "../schema/source.js";
 export async function staleCommentPins(cwd, document, range) {
     const stale = [];
@@ -21,10 +21,13 @@ export function commentPinErrors(pins) {
 }
 async function commentPinMatches(cwd, source, range) {
     const sha = source.side === "old" ? range.baseSha : range.headSha;
-    if (!(await fileExistsAt(cwd, sha, source.path))) {
+    let content;
+    try {
+        content = await showFile(cwd, sha, source.path);
+    }
+    catch {
         return false;
     }
-    const content = await showFile(cwd, sha, source.path);
     const count = textLineCount(content);
     return source.line >= 1 && source.line <= count;
 }

package/dist/schema/cli-pin.js

@@ -8,6 +8,10 @@ export function listedCliPins(markdown) {
 export function applyCliPin(markdown, version) {
     return markdown.replace(PIN, cliPin(version));
 }
+/** Rewrite every `npx comprehende@…` invocation to `command`. */
+export function replaceCliPin(markdown, command) {
+    return markdown.replace(PIN, command);
+}
 export function cliPinErrors(markdown, version) {
     const expected = cliPin(version);
     const pins = listedCliPins(markdown);

package/dist/schema/hunk-meta.js

@@ -2,28 +2,6 @@ export function hunkRangeLabel(header) {
     const match = /^(@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@)/.exec(header);
     return match?.[1] ?? header;
 }
-export function hunkContext(header) {
-    const match = /^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@\s*(.*)$/.exec(header);
-    const ctx = match?.[1]?.trim();
-    if (ctx === undefined || ctx === "") {
-        return undefined;
-    }
-    return looksLikeCodeAnchor(ctx) ? ctx : undefined;
-}
-function looksLikeCodeAnchor(line) {
-    if (line.startsWith("#")) {
-        return false;
-    }
-    const hasCodeToken = /[(){};=<>]|=>/.test(line) || /[a-zA-Z_][\w]*\(/.test(line);
-    const hasKeyword = /\b(function|class|const|let|var|type|interface|enum|export|import|def|fn|async|return|struct|impl|pub)\b/.test(line);
-    if (/^[A-Z]/.test(line) && line.includes(": ") && !hasCodeToken && !hasKeyword) {
-        return false;
-    }
-    if (/[.!?]$/.test(line) && !hasCodeToken) {
-        return false;
-    }
-    return hasCodeToken || hasKeyword || /^[A-Za-z_][\w.]*$/.test(line);
-}
 export function addedSymbols(addedLines) {
     const names = [];
     const pattern = /^(?:export\s+)?(?:async\s+)?(?:function|class|type|interface|enum)\s+([A-Za-z_][\w]*)/;
@@ -49,59 +27,3 @@ export function lineDelta(lines) {
     }
     return { added, removed };
 }
-export function splitDiffRows(lines) {
-    const rows = [];
-    let index = 0;
-    while (index < lines.length) {
-        const line = lines[index];
-        if (line === undefined) {
-            break;
-        }
-        if (line.kind === "ctx") {
-            rows.push({
-                left: { kind: "ctx", number: line.oldNumber, text: line.text },
-                right: { kind: "ctx", number: line.newNumber, text: line.text },
-            });
-            index += 1;
-            continue;
-        }
-        if (line.kind === "del") {
-            const removed = [];
-            while (index < lines.length && lines[index]?.kind === "del") {
-                const next = lines[index];
-                if (next !== undefined) {
-                    removed.push(next);
-                }
-                index += 1;
-            }
-            const added = [];
-            while (index < lines.length && lines[index]?.kind === "add") {
-                const next = lines[index];
-                if (next !== undefined) {
-                    added.push(next);
-                }
-                index += 1;
-            }
-            const count = Math.max(removed.length, added.length);
-            for (let offset = 0; offset < count; offset += 1) {
-                const leftLine = removed[offset];
-                const rightLine = added[offset];
-                rows.push({
-                    left: leftLine === undefined
-                        ? null
-                        : { kind: leftLine.kind, number: leftLine.oldNumber, text: leftLine.text },
-                    right: rightLine === undefined
-                        ? null
-                        : { kind: rightLine.kind, number: rightLine.newNumber, text: rightLine.text },
-                });
-            }
-            continue;
-        }
-        rows.push({
-            left: null,
-            right: { kind: "add", number: line.newNumber, text: line.text },
-        });
-        index += 1;
-    }
-    return rows;
-}

package/dist/schema/identity.js

@@ -2,6 +2,7 @@ export function hunkKey(ref) {
     const oldPath = ref.oldPath ?? "";
     return `${oldPath}\0${ref.path}\0${ref.oldStart}\0${ref.newStart}`;
 }
-export function sameHunk(a, b) {
-    return hunkKey(a) === hunkKey(b);
+export function formatHunkRef(ref) {
+    const rename = ref.oldPath !== undefined ? `${ref.oldPath} -> ` : "";
+    return `${rename}${ref.path} @@ -${ref.oldStart},${ref.oldLines} +${ref.newStart},${ref.newLines} @@`;
 }

package/dist/schema/image.js

@@ -1,3 +1,4 @@
+import { basename } from "./types.js";
 export const IMAGE_EXTENSIONS = ["png", "jpg", "jpeg", "gif", "webp", "bmp", "avif", "ico"];
 const IMAGE_EXT = new Set(IMAGE_EXTENSIONS);
 export const LFS_POINTER_VERSION = "version https://git-lfs.github.com/spec/v1";
@@ -12,7 +13,7 @@ const MEDIA = {
     ico: "image/x-icon",
 };
 export function imageExtension(path) {
-    const base = path.split("/").pop() ?? path;
+    const base = basename(path);
     const dot = base.lastIndexOf(".");
     if (dot <= 0) {
         return undefined;
@@ -27,9 +28,3 @@ export function imageMediaType(path) {
     const ext = imageExtension(path);
     return ext === undefined ? "application/octet-stream" : MEDIA[ext];
 }
-export function isLfsPointerText(text) {
-    return text.includes(LFS_POINTER_VERSION) && /oid sha256:[a-f0-9]{64}/.test(text);
-}
-export function isImageHunkRef(ref) {
-    return ref.oldStart === 0 && ref.oldLines === 0 && ref.newStart === 0 && ref.newLines === 0;
-}

package/dist/schema/lockfile.js

@@ -1,3 +1,4 @@
+import { basename } from "./types.js";
 const LOCKFILE_NAMES = new Set([
     ".terraform.lock.hcl",
     "bun.lock",
@@ -33,6 +34,6 @@ const LOCKFILE_NAMES = new Set([
     "yarn.lock",
 ]);
 export function isLockfilePath(path) {
-    const base = path.split("/").pop() ?? path;
+    const base = basename(path);
     return LOCKFILE_NAMES.has(base) || base.endsWith(".gradle.lockfile");
 }

package/dist/schema/parse.js

@@ -1,69 +1,15 @@
-import { isReviewSize, isSourceKind, isSourceSide, REVIEW_SIZES, SOURCE_KINDS, } from "./types.js";
-const DOCUMENT_KEYS = new Set(["version", "source", "size", "title", "summary", "why", "tickets", "sources", "groups"]);
-const SOURCE_KEYS = new Set(["baseRef", "headRef", "range"]);
-const TICKET_KEYS = new Set(["id", "url", "title", "part"]);
-const REVIEW_SOURCE_KEYS = new Set([
-    "id",
-    "kind",
-    "label",
-    "url",
-    "title",
-    "gist",
-    "part",
-    "author",
-    "body",
-    "path",
-    "side",
-    "line",
-]);
-const COMMENT_ONLY_KEYS = ["author", "body", "path", "side", "line"];
-const GROUP_KEYS = new Set([
-    "id",
-    "title",
-    "why",
-    "summary",
-    "lookFor",
-    "dependsOn",
-    "part",
-    "sources",
-    "suggestedOrder",
-    "hunkRefs",
-]);
-const HUNK_KEYS = new Set(["path", "oldPath", "oldStart", "oldLines", "newStart", "newLines"]);
+import * as z from "zod";
+import { reviewDocumentSchema } from "./review.js";
+const UNKNOWN_FIELD_NOTE = "review documents may not store patch text or file contents";
 export function parseReviewDocument(input) {
-    const errors = [];
     if (!isRecord(input)) {
         return { ok: false, errors: ["review document must be a JSON object"] };
     }
-    extraKeys(input, DOCUMENT_KEYS, "document", errors);
-    if (input.version !== 1) {
-        errors.push("version must be 1");
-    }
-    const source = parseSource(input.source, errors);
-    const size = parseSize(input.size, errors);
-    const title = requiredString(input.title, "title", errors);
-    const summary = requiredString(input.summary, "summary", errors);
-    const sources = parseDocumentSources(input.sources, input.tickets, errors);
-    const groups = parseGroups(input.groups, sources, errors);
-    const why = input.why === undefined ? undefined : requiredString(input.why, "why", errors);
-    if (errors.length > 0 || source === undefined || size === undefined || title === undefined || summary === undefined) {
-        return { ok: false, errors };
-    }
-    const document = {
-        version: 1,
-        source,
-        size,
-        title,
-        summary,
-        groups,
-    };
-    if (why !== undefined) {
-        document.why = why;
-    }
-    if (sources !== undefined) {
-        document.sources = sources;
+    const result = reviewDocumentSchema.safeParse(input);
+    if (result.success) {
+        return { ok: true, document: result.data };
     }
-    return { ok: true, document };
+    return { ok: false, errors: formatZodIssues(result.error) };
 }
 export function parseReviewJson(text) {
     let value;
@@ -75,382 +21,35 @@ export function parseReviewJson(text) {
     }
     return parseReviewDocument(value);
 }
-function parseSize(value, errors) {
-    if (isReviewSize(value)) {
-        return value;
-    }
-    errors.push(`size must be one of ${REVIEW_SIZES.join(", ")}`);
-    return undefined;
-}
-function parseSource(value, errors) {
-    if (!isRecord(value)) {
-        errors.push("source must be an object");
-        return undefined;
-    }
-    extraKeys(value, SOURCE_KEYS, "source", errors);
-    const baseRef = requiredString(value.baseRef, "source.baseRef", errors);
-    const headRef = requiredString(value.headRef, "source.headRef", errors);
-    let range;
-    if (value.range !== undefined) {
-        range = requiredString(value.range, "source.range", errors);
-    }
-    if (baseRef === undefined || headRef === undefined) {
-        return undefined;
-    }
-    const source = { baseRef, headRef };
-    if (range !== undefined) {
-        source.range = range;
-    }
-    return source;
-}
-function parseDocumentSources(sourcesValue, ticketsValue, errors) {
-    if (sourcesValue !== undefined && ticketsValue !== undefined) {
-        errors.push("document has both sources and tickets; use sources");
-    }
-    if (sourcesValue !== undefined) {
-        return parseSources(sourcesValue, errors);
-    }
-    if (ticketsValue !== undefined) {
-        return parseLegacyTickets(ticketsValue, errors);
-    }
-    return undefined;
-}
-function parseSources(value, errors) {
-    if (!Array.isArray(value)) {
-        errors.push("sources must be an array");
-        return undefined;
-    }
-    const sources = [];
-    const ids = new Set();
-    value.forEach((item, i) => {
-        const source = parseSourceItem(item, `sources[${i}]`, errors);
-        if (source === undefined) {
-            return;
-        }
-        if (ids.has(source.id)) {
-            errors.push(`duplicate source id "${source.id}"`);
-        }
-        ids.add(source.id);
-        sources.push(source);
-    });
-    return sources;
-}
-function parseSourceItem(value, label, errors) {
-    if (!isRecord(value)) {
-        errors.push(`${label} must be an object`);
-        return undefined;
-    }
-    extraKeys(value, REVIEW_SOURCE_KEYS, label, errors);
-    const id = requiredString(value.id, `${label}.id`, errors);
-    const kind = parseKind(value.kind, `${label}.kind`, errors);
-    const sourceLabel = requiredString(value.label, `${label}.label`, errors);
-    if (id === undefined || kind === undefined || sourceLabel === undefined) {
-        return undefined;
-    }
-    const source = { id, kind, label: sourceLabel };
-    if (value.url !== undefined) {
-        const url = requiredString(value.url, `${label}.url`, errors);
-        if (url !== undefined) {
-            source.url = url;
-        }
-    }
-    if (value.title !== undefined) {
-        const title = requiredString(value.title, `${label}.title`, errors);
-        if (title !== undefined) {
-            source.title = title;
-        }
-    }
-    if (value.gist !== undefined) {
-        const gist = requiredString(value.gist, `${label}.gist`, errors);
-        if (gist !== undefined) {
-            source.gist = gist;
-        }
-    }
-    if (value.part !== undefined) {
-        const part = requiredString(value.part, `${label}.part`, errors);
-        if (part !== undefined) {
-            source.part = part;
-        }
-    }
-    if (kind === "transcript" && source.url !== undefined) {
-        errors.push(`${label}.url must be omitted for transcripts`);
-    }
-    assignCommentFields(value, source, kind, label, errors);
-    return source;
-}
-function assignCommentFields(value, source, kind, label, errors) {
-    const present = COMMENT_ONLY_KEYS.filter((key) => value[key] !== undefined);
-    if (kind !== "pr-comment") {
-        for (const key of present) {
-            errors.push(`${label}.${key} is only valid on pr-comment sources`);
-        }
-        return;
-    }
-    if (value.author !== undefined) {
-        const author = requiredString(value.author, `${label}.author`, errors);
-        if (author !== undefined) {
-            source.author = author;
-        }
-    }
-    if (value.body !== undefined) {
-        const body = requiredString(value.body, `${label}.body`, errors, { allowEmpty: true });
-        if (body !== undefined) {
-            source.body = body;
-        }
-    }
-    if (source.author === undefined) {
-        errors.push(`${label}.author is required on pr-comment sources`);
-    }
-    if (source.body === undefined) {
-        errors.push(`${label}.body is required on pr-comment sources`);
-    }
-    const pinCount = [value.path, value.side, value.line].filter((item) => item !== undefined).length;
-    if (pinCount === 0) {
-        return;
-    }
-    if (pinCount !== 3) {
-        errors.push(`${label} line pin needs path, side, and line together`);
-    }
-    if (value.path !== undefined) {
-        const path = requiredString(value.path, `${label}.path`, errors);
-        if (path !== undefined) {
-            source.path = path;
-        }
-    }
-    if (value.side !== undefined) {
-        if (!isSourceSide(value.side)) {
-            errors.push(`${label}.side must be old or new`);
-        }
-        else {
-            source.side = value.side;
-        }
-    }
-    if (value.line !== undefined) {
-        const line = requiredInt(value.line, `${label}.line`, errors);
-        if (line !== undefined) {
-            if (line < 1) {
-                errors.push(`${label}.line must be a positive integer`);
-            }
-            else {
-                source.line = line;
-            }
-        }
-    }
-}
-function parseKind(value, label, errors) {
-    if (isSourceKind(value)) {
-        return value;
-    }
-    errors.push(`${label} must be one of ${SOURCE_KINDS.join(", ")}`);
-    return undefined;
-}
-function parseLegacyTickets(value, errors) {
-    if (!Array.isArray(value)) {
-        errors.push("tickets must be an array");
-        return undefined;
-    }
-    const sources = [];
-    const ids = new Set();
-    value.forEach((item, i) => {
-        if (!isRecord(item)) {
-            errors.push(`tickets[${i}] must be an object`);
-            return;
-        }
-        extraKeys(item, TICKET_KEYS, `tickets[${i}]`, errors);
-        const id = requiredString(item.id, `tickets[${i}].id`, errors);
-        if (id === undefined) {
-            return;
-        }
-        if (ids.has(id)) {
-            errors.push(`duplicate source id "${id}"`);
-        }
-        ids.add(id);
-        const source = { id, kind: "ticket", label: id };
-        if (item.url !== undefined) {
-            const url = requiredString(item.url, `tickets[${i}].url`, errors);
-            if (url !== undefined) {
-                source.url = url;
-            }
-        }
-        if (item.title !== undefined) {
-            const title = requiredString(item.title, `tickets[${i}].title`, errors);
-            if (title !== undefined) {
-                source.title = title;
-            }
-        }
-        if (item.part !== undefined) {
-            const part = requiredString(item.part, `tickets[${i}].part`, errors);
-            if (part !== undefined) {
-                source.part = part;
-            }
-        }
-        sources.push(source);
-    });
-    return sources;
-}
-function parseGroups(value, sources, errors) {
-    if (!Array.isArray(value)) {
-        errors.push("groups must be an array");
-        return [];
-    }
-    const ids = new Set();
-    const groups = [];
-    value.forEach((item, i) => {
-        if (!isRecord(item)) {
-            errors.push(`groups[${i}] must be an object`);
-            return;
-        }
-        extraKeys(item, GROUP_KEYS, `groups[${i}]`, errors);
-        const id = requiredString(item.id, `groups[${i}].id`, errors);
-        const title = requiredString(item.title, `groups[${i}].title`, errors);
-        const why = requiredString(item.why, `groups[${i}].why`, errors);
-        const summary = requiredString(item.summary, `groups[${i}].summary`, errors, { allowEmpty: true });
-        const suggestedOrder = requiredNumber(item.suggestedOrder, `groups[${i}].suggestedOrder`, errors);
-        const hunkRefs = parseHunkRefs(item.hunkRefs, `groups[${i}].hunkRefs`, errors);
-        const lookFor = parseStringList(item.lookFor, `groups[${i}].lookFor`, errors);
-        const dependsOn = parseStringList(item.dependsOn, `groups[${i}].dependsOn`, errors);
-        const groupSources = parseStringList(item.sources, `groups[${i}].sources`, errors);
-        const part = item.part === undefined ? undefined : requiredString(item.part, `groups[${i}].part`, errors);
-        if (id === undefined || title === undefined || why === undefined || summary === undefined || suggestedOrder === undefined) {
-            return;
-        }
-        if (ids.has(id)) {
-            errors.push(`duplicate group id "${id}"`);
-        }
-        ids.add(id);
-        const group = { id, title, why, summary, suggestedOrder, hunkRefs };
-        if (lookFor !== undefined) {
-            group.lookFor = lookFor;
-        }
-        if (dependsOn !== undefined) {
-            group.dependsOn = dependsOn;
-        }
-        if (part !== undefined) {
-            group.part = part;
-        }
-        if (groupSources !== undefined) {
-            group.sources = groupSources;
-        }
-        groups.push(group);
-    });
-    const knownGroups = new Set(groups.map((group) => group.id));
-    const knownSources = new Set((sources ?? []).map((source) => source.id));
-    for (const group of groups) {
-        for (const dep of group.dependsOn ?? []) {
-            if (dep === group.id) {
-                errors.push(`groups id "${group.id}" depends on itself`);
-            }
-            else if (!knownGroups.has(dep)) {
-                errors.push(`groups id "${group.id}" dependsOn unknown group "${dep}"`);
-            }
-        }
-        const seen = new Set();
-        for (const sourceId of group.sources ?? []) {
-            if (seen.has(sourceId)) {
-                errors.push(`groups id "${group.id}" lists source "${sourceId}" twice`);
-            }
-            seen.add(sourceId);
-            if (!knownSources.has(sourceId)) {
-                errors.push(`groups id "${group.id}" sources unknown id "${sourceId}"`);
+function formatZodIssues(error) {
+    const errors = [];
+    for (const issue of error.issues) {
+        if (issue.code === "unrecognized_keys") {
+            const where = formatPath(issue.path) || "document";
+            for (const key of issue.keys) {
+                errors.push(`${where} has unknown field "${key}" (${UNKNOWN_FIELD_NOTE})`);
             }
+            continue;
         }
+        const path = formatPath(issue.path);
+        errors.push(path === "" ? issue.message : `${path} ${issue.message}`);
     }
-    return groups;
+    return errors;
 }
-function parseHunkRefs(value, label, errors) {
-    if (!Array.isArray(value)) {
-        errors.push(`${label} must be an array`);
-        return [];
-    }
-    const refs = [];
-    value.forEach((item, i) => {
-        const ref = parseHunkRef(item, `${label}[${i}]`, errors);
-        if (ref !== undefined) {
-            refs.push(ref);
+function formatPath(path) {
+    let out = "";
+    for (const part of path) {
+        if (typeof part === "number") {
+            out += `[${part}]`;
         }
-    });
-    return refs;
-}
-export function parseHunkRef(value, label, errors) {
-    if (!isRecord(value)) {
-        errors.push(`${label} must be an object`);
-        return undefined;
-    }
-    extraKeys(value, HUNK_KEYS, label, errors);
-    const path = requiredString(value.path, `${label}.path`, errors);
-    const oldStart = requiredInt(value.oldStart, `${label}.oldStart`, errors);
-    const oldLines = requiredInt(value.oldLines, `${label}.oldLines`, errors);
-    const newStart = requiredInt(value.newStart, `${label}.newStart`, errors);
-    const newLines = requiredInt(value.newLines, `${label}.newLines`, errors);
-    let oldPath;
-    if (value.oldPath !== undefined) {
-        oldPath = requiredString(value.oldPath, `${label}.oldPath`, errors);
-    }
-    if (path === undefined ||
-        oldStart === undefined ||
-        oldLines === undefined ||
-        newStart === undefined ||
-        newLines === undefined) {
-        return undefined;
-    }
-    const ref = { path, oldStart, oldLines, newStart, newLines };
-    if (oldPath !== undefined) {
-        ref.oldPath = oldPath;
-    }
-    return ref;
-}
-function parseStringList(value, label, errors) {
-    if (value === undefined) {
-        return undefined;
-    }
-    if (!Array.isArray(value)) {
-        errors.push(`${label} must be an array of strings`);
-        return undefined;
-    }
-    const items = [];
-    value.forEach((item, i) => {
-        const text = requiredString(item, `${label}[${i}]`, errors);
-        if (text !== undefined) {
-            items.push(text);
+        else if (out === "") {
+            out = String(part);
         }
-    });
-    return items;
-}
-function extraKeys(value, allowed, label, errors) {
-    for (const key of Object.keys(value)) {
-        if (!allowed.has(key)) {
-            errors.push(`${label} has unknown field "${key}" (review documents may not store patch text or file contents)`);
+        else {
+            out += `.${String(part)}`;
         }
     }
-}
-function requiredString(value, label, errors, opts) {
-    if (typeof value !== "string") {
-        errors.push(`${label} must be a string`);
-        return undefined;
-    }
-    if (!opts?.allowEmpty && value.trim() === "") {
-        errors.push(`${label} must be a non-empty string`);
-        return undefined;
-    }
-    return value;
-}
-function requiredNumber(value, label, errors) {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        errors.push(`${label} must be a finite number`);
-        return undefined;
-    }
-    return value;
-}
-function requiredInt(value, label, errors) {
-    const n = requiredNumber(value, label, errors);
-    if (n === undefined) {
-        return undefined;
-    }
-    if (!Number.isInteger(n) || n < 0) {
-        errors.push(`${label} must be a non-negative integer`);
-        return undefined;
-    }
-    return n;
+    return out;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);