comprehende 0.6.1 → 0.8.0

package/README.md

@@ -1,5 +1,7 @@
 # Comprehende
 
+[![npm](https://img.shields.io/npm/v/comprehende)](https://www.npmjs.com/package/comprehende)
+
 Local review assistant for git diffs. Groups changes by review concern and shows them in a fixed UI. Diffs always come from git in the repo you run the CLI in — never from the model, never stored in the review document.
 
 ## Install the skill
@@ -40,15 +42,17 @@ This tool is for preventing this cognitive surrender while trying to maintain mo
 
 `pnpm sync:skill` copies the JSON Schema into `skills-next/comprehende/`, pins `npx comprehende@<version>` there, and mirrors that tree into `.agents/skills/comprehende` so agents in this checkout use the next skill. It does not touch `skills/comprehende/`.
 
-`comprehende serve` and `comprehende export` share one UI and one git payload. Serve resolves refs to commit SHAs when it starts, then computes those payloads from the objects on each request. Export writes the same JSON (and image bytes) next to the UI so any static file server can host the review.
+`comprehende serve` and `comprehende export` share one UI and one git payload. Serve resolves refs to commit SHAs when it starts, then computes those payloads from the objects on each request. Export writes the same JSON (and image bytes) next to the UI so any static file server can host the review. The URL hash is the UI location (`#overview`, `#group/<id>`, `#unassigned`, `#lockfiles`), so a refresh or a shared link opens the same view in either mode.
+
+This repository publishes those exports to GitHub Pages. A pull request review lives at `https://matemolnar8.github.io/comprehende/pr/<number>/`. A named site lives at `https://matemolnar8.github.io/comprehende/site/<name>/`. Enable Pages once. In the GitHub repo, open Settings, Pages, Deploy from a branch, branch `gh-pages`, folder `/`. A workflow removes the pull request folder when that pull request closes, and drops sites older than 30 days.
 
-`pnpm dev` and `pnpm exec` run with this package as cwd, so they only make sense when _this_ repo is the one under review. To review a different project from a checkout, `cd` into it and run `npx comprehende@0.6.1` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
+`pnpm dev` and `pnpm exec` run with this package as cwd, so they only make sense when _this_ repo is the one under review. To review a different project from a checkout, `cd` into it and run `npx comprehende@0.8.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
 
 ## Release
 
 Edit the skill in `skills-next/comprehende/`. `npx skills add` reads `skills/comprehende/` only.
 
-Bump `version` in `package.json` when the CLI or UI changes, then run `pnpm sync:skill` so the next skill pin matches. Pre-commit and `pnpm test` fail if the staged package version and next skill pin differ. Do not bump for skill-only edits.
+Bump `version` in `package.json` when the CLI or UI changes, then run `pnpm sync:skill` so the next skill pin matches. Pre-commit and `pnpm test` fail if the staged package version and next skill pin differ. Do not bump for skill-only edits. Use the number the user names. If they name none, use the next semver: patch for fixes, minor for new use, major for breaking.
 
 When that next skill should ship with `npx skills add`, run `pnpm release:skill`. That copies `skills-next/comprehende/` onto `skills/comprehende/`. Run it in the same change that publishes a new CLI. Then `npx skills add` installs instructions that match the package they pin.
 

package/dist/api/agent-md.js

@@ -1,17 +1,14 @@
+import { formatHunkRef } from "../schema/identity.js";
+import { padIndex, sizeLabel } from "../schema/types.js";
+import { agentMdGroupHref } from "./paths.js";
 export const AGENT_MD_MEDIA_TYPE = "text/markdown; charset=utf-8";
-export function formatHunkRef(ref) {
-    const rename = ref.oldPath !== undefined ? `${ref.oldPath} -> ` : "";
-    return `${rename}${ref.path} @@ -${ref.oldStart},${ref.oldLines} +${ref.newStart},${ref.newLines} @@`;
-}
+export { formatHunkRef };
 export function isImageSlot(ref) {
     return ref.oldStart === 0 && ref.oldLines === 0 && ref.newStart === 0 && ref.newLines === 0;
 }
 export function agentClipboardPrompt(url) {
     return `Answer the following questions by using ${url}`;
 }
-function groupAgentMdHref(id) {
-    return `groups/${encodeURIComponent(id)}.md`;
-}
 export function agentMd(review, resource) {
     if (resource.target === "overview") {
         return overviewAgentMd(review);
@@ -28,6 +25,7 @@ function overviewAgentMd(review) {
         joinBlocks(["The title:", review.document.title]),
         review.document.why !== undefined ? joinBlocks(["The why:", review.document.why]) : null,
         joinBlocks([`The what (${sizeLabel(review.document.size)}):`, review.document.summary]),
+        lookForBlock(review.document.lookFor ?? []),
         reviewConcernsBlock(review),
     ]);
 }
@@ -103,7 +101,7 @@ function coverageBlock(review) {
 }
 function reviewConcernsBlock(review) {
     const sections = review.groups.map((group, i) => {
-        const href = groupAgentMdHref(group.id);
+        const href = agentMdGroupHref(group.id);
         return joinBlocks([
             `### ${padIndex(i + 1)} ${group.title} (\`${group.id}\`)`,
             group.summary,
@@ -159,7 +157,7 @@ function overviewSteps(review) {
         "",
         "3. Answer from live git.",
         "   Follow those files. Use the why and the what as interpretation. Live git wins when they disagree.",
-        `   ${showCodeRule()}`,
+        `   ${SHOW_CODE_RULE}`,
         "   Done when the answer quotes the live code.",
     ].join("\n");
 }
@@ -179,7 +177,7 @@ function groupSteps(review) {
         "",
         "3. Answer from live git.",
         "   Read those hunks. Use the why and the what as interpretation. Live git wins when they disagree.",
-        `   ${showCodeRule()}`,
+        `   ${SHOW_CODE_RULE}`,
         "   Done when the answer quotes the live code.",
     ].join("\n");
 }
@@ -191,15 +189,7 @@ function resolveShaSteps(review) {
         "   Done when both objects exist.",
     ];
 }
-function showCodeRule() {
-    return "When you show code, quote the live git lines.";
-}
-function padIndex(index) {
-    return String(index).padStart(2, "0");
-}
-function sizeLabel(size) {
-    return size.replace("-", " ");
-}
+const SHOW_CODE_RULE = "When you show code, quote the live git lines.";
 function joinBlocks(parts) {
     return parts.filter((part) => part !== null && part !== undefined && part.length > 0).join("\n\n");
 }

package/dist/api/live.js

@@ -1,4 +1,4 @@
-import { loadDocument } from "../cli/commands.js";
+import { loadDocument } from "../review/load.js";
 import { blameFile } from "../git/blame.js";
 import { readImageBlob } from "../git/blob.js";
 import { fileLanguage, filePatchFromGit, readPathDiff, toHunkRef } from "../git/diff.js";
@@ -12,12 +12,13 @@ import { isLockfilePath } from "../schema/lockfile.js";
 import { sourceCitationErrors } from "../schema/source.js";
 import { AGENT_MD_MEDIA_TYPE, agentMd } from "./agent-md.js";
 import { ApiError } from "./error.js";
-export async function pinReviewSource(cwd, dataPath) {
-    const document = await loadDocument(dataPath);
+import { REVIEW_BUCKETS } from "./types.js";
+export async function pinReviewSource(cwd, data) {
+    const document = typeof data === "string" ? await loadDocument(data) : data;
     return pinRange(cwd, document.source.baseRef, document.source.headRef);
 }
-export async function openReview(cwd, dataPath, pin) {
-    const document = await loadDocument(dataPath);
+export async function openReview(cwd, data, pin) {
+    const document = typeof data === "string" ? await loadDocument(data) : data;
     const range = pin ?? (await pinRange(cwd, document.source.baseRef, document.source.headRef));
     const { files, coverage } = await coverReview(cwd, document, range);
     const pins = await staleCommentPins(cwd, document, range);
@@ -110,10 +111,10 @@ export function hunksPayload(ctx, groupId) {
     if (groupId === "") {
         throw new ApiError(400, "missing group");
     }
-    if (groupId === "unassigned") {
+    if (groupId === REVIEW_BUCKETS.unassigned) {
         return serializeGroup(ctx.files, ctx.coverage.unassigned);
     }
-    if (groupId === "lockfiles") {
+    if (groupId === REVIEW_BUCKETS.lockfiles) {
         return serializeLockfiles(ctx.files);
     }
     const group = ctx.coverage.groups.find((item) => item.group.id === groupId);
@@ -198,8 +199,8 @@ export function listResources(ctx) {
     const resources = [
         { kind: "review" },
         { kind: "agent-md", target: "overview" },
-        { kind: "hunks", group: "unassigned" },
-        { kind: "hunks", group: "lockfiles" },
+        { kind: "hunks", group: REVIEW_BUCKETS.unassigned },
+        { kind: "hunks", group: REVIEW_BUCKETS.lockfiles },
     ];
     for (const group of ctx.document.groups) {
         resources.push({ kind: "hunks", group: group.id });
@@ -260,12 +261,20 @@ async function patchPayload(ctx, path) {
     if (!isLockfilePath(file.path) || file.binary || file.image) {
         throw new ApiError(404, "path is not a deferred lockfile");
     }
-    const live = await readPathDiff(ctx.cwd, ctx.resolved.baseSha, ctx.resolved.headSha, file.path);
+    const live = await readPathDiffSafe(ctx, file.path);
     if (live === undefined) {
         throw new ApiError(404, `no live diff for ${path}`);
     }
     return serializeGroupFile(live, live.hunks, false);
 }
+async function readPathDiffSafe(ctx, path) {
+    try {
+        return await readPathDiff(ctx.cwd, ctx.resolved.baseSha, ctx.resolved.headSha, path);
+    }
+    catch (error) {
+        throw new ApiError(404, error instanceof Error ? error.message : "diff not available");
+    }
+}
 function serializeGroupFile(file, fileHunks, deferLockfile) {
     const lockfile = isLockfilePath(file.path) && !file.binary && !file.image;
     const deferred = deferLockfile && lockfile;
@@ -317,9 +326,10 @@ function uniquePaths(hunks) {
 export function snapshotJson(body) {
     return `${JSON.stringify(body)}\n`;
 }
+/** 404 (and transient git failures) mean the live object moved. Skip it in export. 400 is a bad request, not a skip. */
 export function isUnavailableSnapshot(error) {
     if (error instanceof ApiError) {
-        return error.status === 404 || error.status === 400;
+        return error.status === 404;
     }
     return error instanceof GitError;
 }

package/dist/api/paths.js

@@ -1,23 +1,17 @@
+import { isSourceSide } from "../schema/types.js";
 export function apiHref(resource) {
-    switch (resource.kind) {
-        case "review":
-            return "api/review.json";
-        case "agent-md":
-            return agentMdRel(resource);
-        case "hunks":
-            return `api/hunks/${encodeURIComponent(resource.group)}.json`;
-        case "file":
-            return `api/files/${resource.side}/${encodeFilePath(resource.path)}.json`;
-        case "blame":
-            return `api/blame/${resource.side}/${encodeFilePath(resource.path)}.json`;
-        case "image":
-            return `api/images/${resource.side}/${encodeFilePath(resource.path)}`;
-        case "patch":
-            return `api/patches/${encodeFilePath(resource.path)}.json`;
-    }
+    return apiRel(resource, true);
 }
 /** Decoded relative path under the site root. Static hosts map encoded request URLs onto this. */
 export function apiFsRel(resource) {
+    return apiRel(resource, false);
+}
+/** Relative link from overview.md to a group file. Overview lives in api/agent, groups live in api/agent/groups. */
+export function agentMdGroupHref(group) {
+    return `groups/${encodeURIComponent(group)}.md`;
+}
+function apiRel(resource, encodeFiles) {
+    const filePath = (path) => (encodeFiles ? encodeFilePath(path) : path);
     switch (resource.kind) {
         case "review":
             return "api/review.json";
@@ -26,13 +20,13 @@ export function apiFsRel(resource) {
         case "hunks":
             return `api/hunks/${encodeURIComponent(resource.group)}.json`;
         case "file":
-            return `api/files/${resource.side}/${resource.path}.json`;
+            return `api/files/${resource.side}/${filePath(resource.path)}.json`;
         case "blame":
-            return `api/blame/${resource.side}/${resource.path}.json`;
+            return `api/blame/${resource.side}/${filePath(resource.path)}.json`;
         case "image":
-            return `api/images/${resource.side}/${resource.path}`;
+            return `api/images/${resource.side}/${filePath(resource.path)}`;
         case "patch":
-            return `api/patches/${resource.path}.json`;
+            return `api/patches/${filePath(resource.path)}.json`;
     }
 }
 export function parseApiPath(pathname) {
@@ -65,11 +59,11 @@ export function parseApiPath(pathname) {
     }
     if (parts[1] === "images" && parts.length >= 4 && parts[2] !== undefined) {
         const side = parts[2];
-        if (side !== "old" && side !== "new") {
+        if (!isSourceSide(side)) {
             return undefined;
         }
         const path = parts.slice(3).join("/");
-        if (!isRepoPath(path)) {
+        if (!isSafePath(path)) {
             return undefined;
         }
         return { kind: "image", path, side };
@@ -83,14 +77,14 @@ export function parseApiPath(pathname) {
         }
         rest[rest.length - 1] = stem;
         const path = rest.join("/");
-        if (!isRepoPath(path)) {
+        if (!isSafePath(path)) {
             return undefined;
         }
         return { kind: "patch", path };
     }
     if ((parts[1] === "files" || parts[1] === "blame") && parts.length >= 4 && parts[2] !== undefined) {
         const side = parts[2];
-        if (side !== "old" && side !== "new") {
+        if (!isSourceSide(side)) {
             return undefined;
         }
         const rest = parts.slice(3);
@@ -101,7 +95,7 @@ export function parseApiPath(pathname) {
         }
         rest[rest.length - 1] = stem;
         const path = rest.join("/");
-        if (!isRepoPath(path)) {
+        if (!isSafePath(path)) {
             return undefined;
         }
         return { kind: parts[1] === "files" ? "file" : "blame", path, side };
@@ -123,22 +117,26 @@ function agentMdRel(resource) {
     if (resource.target === "overview") {
         return "api/agent/overview.md";
     }
-    return `api/agent/groups/${encodeURIComponent(resource.group)}.md`;
+    return `api/agent/${agentMdGroupHref(resource.group)}`;
 }
 function jsonStem(file) {
-    if (!file.endsWith(".json")) {
-        return undefined;
-    }
-    const stem = file.slice(0, -".json".length);
-    return stem === "" ? undefined : stem;
+    return stem(file, ".json");
 }
 function mdStem(file) {
-    if (!file.endsWith(".md")) {
+    return stem(file, ".md");
+}
+function stem(file, ext) {
+    if (!file.endsWith(ext)) {
         return undefined;
     }
-    const stem = file.slice(0, -".md".length);
-    return stem === "" ? undefined : stem;
+    const bare = file.slice(0, -ext.length);
+    return bare === "" ? undefined : bare;
 }
-function isRepoPath(path) {
-    return path !== "" && !path.startsWith("/") && !path.includes("\0") && !path.split("/").includes("..");
+export function isSafePath(path) {
+    return (path.trim() !== "" && !path.startsWith("/") && !path.includes("\0") && !path.split("/").includes(".."));
+}
+export function assertSafePath(path) {
+    if (!isSafePath(path)) {
+        throw new Error(`invalid path: ${path}`);
+    }
 }

package/dist/api/types.js

@@ -1 +1,5 @@
-export {};
+/** Hunk group ids outside the review document. The UI fetches them with the same hunks endpoint. */
+export const REVIEW_BUCKETS = {
+    unassigned: "unassigned",
+    lockfiles: "lockfiles",
+};

package/dist/cli/args.js

@@ -1,4 +1,11 @@
 const COMMANDS = new Set(["index", "validate", "serve", "export"]);
+export const DEFAULT_PORT = 4567;
+export class ArgError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArgError";
+    }
+}
 export const USAGE = `Usage: comprehende <command> [options]
 
 Run inside the git repository under review. Cwd is the repo.
@@ -22,7 +29,7 @@ Options:
   --head <ref>     Head ref (default: HEAD)
   --data <path>    Review document path
   --out <dir>      Output directory for export
-  --port <n>       Listen port (default: 4567, 0 for ephemeral)
+  --port <n>       Listen port (default: ${DEFAULT_PORT}, 0 for ephemeral)
   --open           Open the UI in a browser
   -h, --help       Show this help
   -v, --version    Show version
@@ -47,9 +54,9 @@ export function parseArgv(argv, cwd = process.cwd()) {
     }
     const rest = args.slice(1);
     try {
-        const port = Number(flag(rest, "--port") ?? "4567");
+        const port = Number(flag(rest, "--port") ?? String(DEFAULT_PORT));
         if (!Number.isInteger(port) || port < 0) {
-            throw new Error("--port must be a non-negative integer");
+            throw new ArgError("--port must be a non-negative integer");
         }
         return {
             kind: "command",
@@ -80,14 +87,14 @@ function flag(args, name) {
         if (arg === name) {
             const value = args[i + 1];
             if (value === undefined || value.startsWith("-")) {
-                throw new Error(`${name} requires a value`);
+                throw new ArgError(`${name} requires a value`);
             }
             return value;
         }
         if (arg.startsWith(prefix)) {
             const value = arg.slice(prefix.length);
             if (value === "") {
-                throw new Error(`${name} requires a value`);
+                throw new ArgError(`${name} requires a value`);
             }
             return value;
         }

package/dist/cli/commands.js

@@ -1,40 +1,17 @@
-import { readFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
 import { readHunkIndex, resolveSource } from "../git/diff.js";
 import { defaultBaseRef } from "../git/repo.js";
 import { coverReview, coverageErrors } from "../review/coverage.js";
+import { loadDocument, resolveCliPath } from "../review/load.js";
 import { commentPinErrors, staleCommentPins } from "../review/pins.js";
-import { parseReviewJson } from "../schema/parse.js";
 import { sourceCitationErrors } from "../schema/source.js";
-export async function resolveRange(cwd, base, head) {
+export async function cmdIndex(cwd, base, head) {
     const baseRef = base ?? (await defaultBaseRef(cwd));
     const headRef = head ?? "HEAD";
     await resolveSource(cwd, baseRef, headRef);
-    return { baseRef, headRef };
-}
-export async function cmdIndex(cwd, base, head) {
-    const range = await resolveRange(cwd, base, head);
-    return readHunkIndex(cwd, range.baseRef, range.headRef);
-}
-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) {
-    if (data === undefined) {
-        throw new Error("missing --data <review.json>");
-    }
-    return isAbsolute(data) ? data : resolve(cwd, data);
+    return readHunkIndex(cwd, baseRef, headRef);
 }
 export function resolveOutPath(out, cwd) {
-    if (out === undefined) {
-        throw new Error("missing --out <dir>");
-    }
-    return isAbsolute(out) ? out : resolve(cwd, out);
+    return resolveCliPath(out, cwd, "--out <dir>");
 }
 export async function cmdValidate(cwd, dataPath) {
     const document = await loadDocument(dataPath);

package/dist/cli/main.js

@@ -4,7 +4,8 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgv, USAGE } from "./args.js";
-import { cmdIndex, cmdValidate, resolveDataPath, resolveOutPath } from "./commands.js";
+import { cmdIndex, cmdValidate, resolveOutPath } from "./commands.js";
+import { loadDocument, resolveDataPath } from "../review/load.js";
 import { exportStaticSite } from "../api/snapshot.js";
 import { openReview, pinReviewSource, reviewProblems } from "../api/live.js";
 import { assertWorkTree } from "../git/repo.js";
@@ -41,8 +42,9 @@ export async function run(argv) {
             }
             case "serve": {
                 const dataPath = resolveDataPath(request.data, request.cwd);
-                const pin = await pinReviewSource(request.cwd, dataPath);
-                const ctx = await openReview(request.cwd, dataPath, pin);
+                const document = await loadDocument(dataPath);
+                const pin = await pinReviewSource(request.cwd, document);
+                const ctx = await openReview(request.cwd, document, pin);
                 warnReview(ctx, "serve continues; git wins, unassigned/stale are visible");
                 const running = await startServer({ cwd: request.cwd, dataPath, port: request.port, pin });
                 console.log(running.url);
@@ -56,7 +58,8 @@ export async function run(argv) {
             case "export": {
                 const dataPath = resolveDataPath(request.data, request.cwd);
                 const outDir = resolveOutPath(request.out, request.cwd);
-                const ctx = await openReview(request.cwd, dataPath);
+                const document = await loadDocument(dataPath);
+                const ctx = await openReview(request.cwd, document);
                 warnReview(ctx, "export continues; git wins, unassigned/stale are visible");
                 const result = await exportStaticSite({ cwd: request.cwd, dataPath, outDir, ctx });
                 console.log(result.outDir);

package/dist/git/exec.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/** Mirrored in scripts/install-git-hooks.js, which runs as plain node without tsx. Update both. */
 const GIT_DIR_VARS = new Set([
     "GIT_DIR",
     "GIT_WORK_TREE",
@@ -76,13 +77,12 @@ export async function gitOk(cwd, args) {
     }
 }
 function asExecFailure(error) {
-    if (typeof error === "object" && error !== null) {
-        const record = error;
+    if (isRecord(error)) {
         return {
-            message: typeof record.message === "string" ? record.message : "git failed",
-            stdout: bufferText(record.stdout),
-            stderr: bufferText(record.stderr),
-            code: typeof record.code === "number" ? record.code : null,
+            message: typeof error.message === "string" ? error.message : "git failed",
+            stdout: bufferText(error.stdout),
+            stderr: bufferText(error.stderr),
+            code: typeof error.code === "number" ? error.code : null,
         };
     }
     return { message: "git failed", stdout: "", stderr: "", code: null };
@@ -96,6 +96,9 @@ function bufferText(value) {
     }
     return "";
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function gitFailure(args, failure) {
     return new GitError(`git ${args.join(" ")} failed: ${failure.stderr.trim() || failure.message}`, args, failure.stderr, failure.code);
 }

package/dist/git/repo.js

@@ -1,5 +1,8 @@
-import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { basename as nodeBasename, dirname, isAbsolute, resolve } from "node:path";
+import { assertSafePath, isSafePath } from "../api/paths.js";
+import { basename as posixBasename } from "../schema/types.js";
 import { git, gitOk } from "./exec.js";
+export { assertSafePath, isSafePath };
 export async function assertWorkTree(cwd) {
     const inside = await git(cwd, ["rev-parse", "--is-inside-work-tree"], { allowFail: true });
     if (inside.trim() !== "true") {
@@ -27,8 +30,8 @@ export function nameFromRemoteUrl(url) {
         : value.includes(":")
             ? value.slice(value.lastIndexOf(":") + 1)
             : value;
-    const last = pathPart.split("/").filter(Boolean).at(-1);
-    return last === undefined || last === "" ? null : last;
+    const last = posixBasename(pathPart);
+    return last === "" ? null : last;
 }
 export async function gitCommonDir(cwd) {
     const raw = (await git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).trim();
@@ -41,7 +44,7 @@ export async function readRepoIdentity(cwd) {
     if (fromOrigin !== null) {
         return { name: fromOrigin, origin };
     }
-    return { name: basename(dirname(await gitCommonDir(cwd))), origin };
+    return { name: nodeBasename(dirname(await gitCommonDir(cwd))), origin };
 }
 /** Drop userinfo from an http(s) remote so a copied prompt never carries a token. */
 export function stripRemoteCredentials(url) {
@@ -93,8 +96,12 @@ export function assertSafeRef(ref) {
         throw new Error(`invalid git ref: ${ref}`);
     }
 }
-export function assertSafePath(path) {
-    if (path.trim() === "" || path.startsWith("/") || path.includes("\0") || path.split("/").includes("..")) {
-        throw new Error(`invalid path: ${path}`);
+export function resolveInsideRoot(root, relative) {
+    assertSafePath(relative);
+    const rootAbs = resolve(root);
+    const abs = resolve(root, relative);
+    if (abs !== rootAbs && !abs.startsWith(`${rootAbs}/`)) {
+        throw new Error(`invalid path: ${relative}`);
     }
+    return abs;
 }

package/dist/git/show.js

@@ -1,6 +1,6 @@
 import { readBlob } from "./blob.js";
 import { assertSafePath, assertSafeRef } from "./repo.js";
-import { git } from "./exec.js";
+import { gitOk } from "./exec.js";
 export async function showFile(cwd, ref, path) {
     const bytes = await readBlob(cwd, ref, path);
     return bytes.toString("utf8");
@@ -8,11 +8,5 @@ export async function showFile(cwd, ref, path) {
 export async function fileExistsAt(cwd, ref, path) {
     assertSafeRef(ref);
     assertSafePath(path);
-    try {
-        await git(cwd, ["cat-file", "-e", `${ref}:${path}`]);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return gitOk(cwd, ["cat-file", "-e", `${ref}:${path}`]);
 }

package/dist/package-root.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 export function findPackageRoot(from = import.meta.url) {
@@ -7,7 +8,7 @@ export function findPackageRoot(from = import.meta.url) {
         const pkgPath = join(dir, "package.json");
         if (existsSync(pkgPath)) {
             const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-            if (pkg.name === "comprehende") {
+            if (isRecord(pkg) && pkg.name === "comprehende") {
                 return dir;
             }
         }
@@ -20,6 +21,22 @@ export function findPackageRoot(from = import.meta.url) {
 }
 export function readPackageVersion() {
     const pkgPath = join(findPackageRoot(), "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-    return pkg.version;
+    return parsePackageVersion(readFileSync(pkgPath, "utf8"));
+}
+export function parsePackageVersion(text) {
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed)) {
+        throw new Error("package.json version must be a non-empty string");
+    }
+    const version = parsed.version;
+    if (typeof version !== "string" || version === "") {
+        throw new Error("package.json version must be a non-empty string");
+    }
+    return version;
+}
+export async function readPackageVersionFromDir(root) {
+    return parsePackageVersion(await readFile(join(root, "package.json"), "utf8"));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/review/coverage.js

@@ -1,6 +1,6 @@
 import { flattenHunks, readDiff, toHunkRef } from "../git/diff.js";
 import { pinRange } from "../git/repo.js";
-import { hunkKey } from "../schema/identity.js";
+import { formatHunkRef, hunkKey } from "../schema/identity.js";
 import { isLockfilePath } from "../schema/lockfile.js";
 export async function coverReview(cwd, document, pin) {
     const range = pin ?? (await pinRange(cwd, document.source.baseRef, document.source.headRef));
@@ -11,7 +11,8 @@ export async function coverReview(cwd, document, pin) {
 export function joinCoverage(document, live) {
     const liveByKey = new Map();
     for (const hunk of live) {
-        liveByKey.set(hunkKey(hunk), hunk);
+        const key = hunkKey(hunk);
+        liveByKey.set(key, hunk);
     }
     const assignedKeys = new Set();
     const allStale = [];
@@ -22,18 +23,22 @@ export function joinCoverage(document, live) {
             if (isLockfilePath(ref.path)) {
                 continue;
             }
-            const match = liveByKey.get(hunkKey(ref));
+            const key = hunkKey(ref);
+            const match = liveByKey.get(key);
             if (match === undefined) {
                 stale.push(ref);
                 allStale.push(ref);
                 continue;
             }
             hunks.push(match);
-            assignedKeys.add(hunkKey(match));
+            assignedKeys.add(key);
         }
         return { group, hunks, stale };
     });
-    const unassigned = live.filter((hunk) => !assignedKeys.has(hunkKey(hunk)));
+    const unassigned = live.filter((hunk) => {
+        const key = hunkKey(hunk);
+        return !assignedKeys.has(key);
+    });
     return {
         groups,
         unassigned,
@@ -53,10 +58,5 @@ export function coverageErrors(coverage) {
     return errors;
 }
 function formatRefs(refs) {
-    return refs
-        .map((ref) => {
-        const rename = ref.oldPath !== undefined ? `${ref.oldPath} -> ` : "";
-        return `  ${rename}${ref.path} @@ -${ref.oldStart},${ref.oldLines} +${ref.newStart},${ref.newLines} @@`;
-    })
-        .join("\n");
+    return refs.map((ref) => `  ${formatHunkRef(ref)}`).join("\n");
 }