comprehende 0.5.1 → 0.5.3

package/README.md

@@ -42,7 +42,7 @@ This tool is for preventing this cognitive surrender while trying to maintain mo
 
 `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.
 
-`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.5.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.5.3` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
 
 ## Release
 

package/dist/api/agent-md.js

@@ -0,0 +1,204 @@
+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 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);
+    }
+    return groupAgentMd(review, resource.group);
+}
+function overviewAgentMd(review) {
+    return joinBlocks([
+        "Answer questions about this git change.",
+        overviewSteps(review),
+        pinBlock(review, { commits: true }),
+        ticketsBlock(review),
+        coverageBlock(review),
+        review.document.why !== undefined ? joinBlocks(["The why:", review.document.why]) : null,
+        joinBlocks([`The what (${sizeLabel(review.document.size)}):`, review.document.summary]),
+        reviewConcernsBlock(review),
+    ]);
+}
+function groupAgentMd(review, id) {
+    const listed = review.groups.find((group) => group.id === id);
+    const documentGroup = review.document.groups.find((group) => group.id === id);
+    if (listed === undefined || documentGroup === undefined) {
+        return null;
+    }
+    const index = review.groups.findIndex((group) => group.id === id) + 1;
+    const total = review.groups.length;
+    const hunks = documentGroup.hunkRefs;
+    const heading = `Review concern ${padIndex(index)} of ${padIndex(total)}: ${listed.title} (\`${listed.id}\`)`;
+    return joinBlocks([
+        "Answer questions about this review concern.",
+        groupSteps(review),
+        pinBlock(review, { commits: false }),
+        heading,
+        listed.part !== undefined ? `Part: ${listed.part}` : null,
+        "The why:",
+        listed.why,
+        "The what:",
+        listed.summary,
+        lookForBlock(listed.lookFor),
+        dependsOnBlock(review, listed.dependsOn),
+        hunkList("Hunk refs for this concern:", hunks),
+        imageNote(hunks),
+        listed.staleCount > 0
+            ? `Stale hunk refs in this concern: ${listed.staleCount}. Live git wins. The pointer is flagged, not replaced.`
+            : null,
+    ]);
+}
+function pinBlock(review, options) {
+    const { baseSha, headSha, baseRef, headRef } = review.resolved;
+    const repo = review.repo.origin !== null
+        ? `Repository: ${review.repo.name}\nOrigin: ${review.repo.origin}`
+        : `Repository: ${review.repo.name}`;
+    const commits = options.commits && review.commits.length > 0
+        ? ["Commits:", ...review.commits.map((commit) => `- ${commit.shortSha} ${commit.subject}`)].join("\n")
+        : null;
+    return joinBlocks([
+        "## Pin",
+        repo,
+        `base (merge-base)  ${baseSha}`,
+        `head               ${headSha}`,
+        `Named refs at pin: ${baseRef} ... ${headRef}`,
+        "Read the diff:",
+        `git diff --find-renames ${baseSha} ${headSha}`,
+        commits,
+    ]);
+}
+function ticketsBlock(review) {
+    const tickets = review.document.tickets ?? [];
+    if (tickets.length === 0) {
+        return null;
+    }
+    const lines = tickets.map((ticket) => {
+        const title = ticket.title !== undefined ? ` ${ticket.title}` : "";
+        const url = ticket.url !== undefined ? `\n  ${ticket.url}` : "";
+        return `- ${ticket.id}${title}${url}`;
+    });
+    return ["Tickets:", ...lines].join("\n");
+}
+function coverageBlock(review) {
+    const lines = [];
+    if (review.coverage.unassignedCount > 0) {
+        lines.push(`Unassigned live hunks: ${review.coverage.unassignedCount}. They are in git and in no group.`);
+    }
+    if (review.coverage.staleCount > 0) {
+        lines.push(`Stale hunk refs: ${review.coverage.staleCount}. Live git wins. The pointer is flagged, not replaced.`);
+    }
+    return lines.length === 0 ? null : lines.join("\n");
+}
+function reviewConcernsBlock(review) {
+    const sections = review.groups.map((group, i) => {
+        const href = groupAgentMdHref(group.id);
+        return joinBlocks([
+            `### ${padIndex(i + 1)} ${group.title} (\`${group.id}\`)`,
+            group.summary,
+            dependsOnBlock(review, group.dependsOn),
+            `[${href}](${href})`,
+        ]);
+    });
+    return ["## Review concerns", ...sections].join("\n\n");
+}
+function lookForBlock(lookFor) {
+    if (lookFor.length === 0) {
+        return null;
+    }
+    return ["Look for:", ...lookFor.map((item) => `- ${item}`)].join("\n");
+}
+function dependsOnBlock(review, dependsOn) {
+    if (dependsOn.length === 0) {
+        return null;
+    }
+    const lines = dependsOn.map((id) => {
+        const dep = review.groups.find((group) => group.id === id);
+        if (dep === undefined) {
+            return `- ${id}`;
+        }
+        const index = review.groups.findIndex((group) => group.id === id) + 1;
+        return `- ${padIndex(index)} ${dep.title} (\`${dep.id}\`)`;
+    });
+    return ["Depends on:", ...lines].join("\n");
+}
+function hunkList(heading, hunks) {
+    if (hunks.length === 0) {
+        return `${heading}\n(none)`;
+    }
+    return [heading, ...hunks.map((hunk) => `- ${formatHunkRef(hunk)}`)].join("\n");
+}
+function imageNote(hunks) {
+    if (!hunks.some(isImageSlot)) {
+        return null;
+    }
+    return "Hunk refs with @@ -0,0 +0,0 @@ are image or binary slots. Identify those by path.";
+}
+function overviewSteps(review) {
+    return [
+        "## Steps",
+        "",
+        "When no question follows this paste, explain this change.",
+        "",
+        ...resolveShaSteps(review),
+        "",
+        "2. Choose the relevant review concerns.",
+        "   Read Review concerns. Fetch a concern file only when that concern is relevant to the question.",
+        "   Done when every concern the question touches has its markdown loaded.",
+        "",
+        "3. Answer from live git.",
+        "   Follow those files. Use the why and the what as interpretation. Live git wins when they disagree.",
+        `   ${showCodeRule()}`,
+        "   Done when the answer quotes the live code.",
+    ].join("\n");
+}
+function groupSteps(review) {
+    const { baseSha, headSha } = review.resolved;
+    return [
+        "## Steps",
+        "",
+        "When no question follows this paste, explain this review concern.",
+        "",
+        ...resolveShaSteps(review),
+        "",
+        "2. Load the hunks.",
+        "   A hunk ref is a pointer into the live git diff at the pinned SHAs.",
+        `   For each hunk ref, run \`git diff --find-renames ${baseSha} ${headSha} -- <path>\` and keep the hunk whose header matches the @@ range.`,
+        "   Done when every hunk ref has a matching live hunk.",
+        "",
+        "3. Answer from live git.",
+        "   Read those hunks. Use the why and the what as interpretation. Live git wins when they disagree.",
+        `   ${showCodeRule()}`,
+        "   Done when the answer quotes the live code.",
+    ].join("\n");
+}
+function resolveShaSteps(review) {
+    const { baseSha, headSha } = review.resolved;
+    return [
+        "1. Resolve the pinned SHAs.",
+        `   Run \`git rev-parse --verify ${baseSha}\` and \`git rev-parse --verify ${headSha}\` in this repository.`,
+        "   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("-", " ");
+}
+function joinBlocks(parts) {
+    return parts.filter((part) => part !== null && part !== undefined && part.length > 0).join("\n\n");
+}

package/dist/api/live.js

@@ -4,10 +4,11 @@ import { readImageBlob } from "../git/blob.js";
 import { fileLanguage, filePatchFromGit, readPathDiff, toHunkRef } from "../git/diff.js";
 import { GitError } from "../git/exec.js";
 import { listCommits } from "../git/log.js";
-import { pinRange } from "../git/repo.js";
+import { pinRange, readRepoIdentity } from "../git/repo.js";
 import { showFile } from "../git/show.js";
 import { coverReview } from "../review/coverage.js";
 import { isLockfilePath } from "../schema/lockfile.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);
@@ -18,9 +19,11 @@ export async function openReview(cwd, dataPath, pin) {
     const range = pin ?? (await pinRange(cwd, document.source.baseRef, document.source.headRef));
     const { files, coverage } = await coverReview(cwd, document, range);
     const commits = await listCommits(cwd, range.baseSha, range.headSha);
+    const repo = await readRepoIdentity(cwd);
     return {
         cwd,
         document,
+        repo,
         resolved: {
             baseRef: document.source.baseRef,
             headRef: document.source.headRef,
@@ -35,10 +38,11 @@ export async function openReview(cwd, dataPath, pin) {
     };
 }
 export function reviewPayload(ctx) {
-    const { document, resolved, files, coverage, commits } = ctx;
+    const { document, repo, resolved, files, coverage, commits } = ctx;
     const lockfiles = lockfileFiles(files);
     return {
         document,
+        repo,
         resolved,
         coverage: {
             totalHunks: coverage.totalHunks,
@@ -156,6 +160,14 @@ export async function renderResource(ctx, resource) {
     switch (resource.kind) {
         case "review":
             return { encoding: "json", body: reviewPayload(ctx) };
+        case "agent-md": {
+            const body = agentMd(reviewPayload(ctx), resource);
+            if (body === null) {
+                const id = resource.target === "group" ? resource.group : "overview";
+                throw new ApiError(404, `unknown group "${id}"`);
+            }
+            return { encoding: "bytes", mediaType: AGENT_MD_MEDIA_TYPE, body: Buffer.from(body, "utf8") };
+        }
         case "hunks":
             return { encoding: "json", body: hunksPayload(ctx, resource.group) };
         case "file":
@@ -171,11 +183,13 @@ export async function renderResource(ctx, resource) {
 export function listResources(ctx) {
     const resources = [
         { kind: "review" },
+        { kind: "agent-md", target: "overview" },
         { kind: "hunks", group: "unassigned" },
         { kind: "hunks", group: "lockfiles" },
     ];
     for (const group of ctx.document.groups) {
         resources.push({ kind: "hunks", group: group.id });
+        resources.push({ kind: "agent-md", target: "group", group: group.id });
     }
     for (const file of ctx.files) {
         if (file.image) {

package/dist/api/paths.js

@@ -2,6 +2,8 @@ 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":
@@ -19,6 +21,8 @@ export function apiFsRel(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":
@@ -39,6 +43,19 @@ export function parseApiPath(pathname) {
     if (parts[1] === "review.json" && parts.length === 2) {
         return { kind: "review" };
     }
+    if (parts[1] === "agent") {
+        if (parts.length === 3 && parts[2] === "overview.md") {
+            return { kind: "agent-md", target: "overview" };
+        }
+        if (parts.length === 4 && parts[2] === "groups" && parts[3] !== undefined) {
+            const group = mdStem(parts[3]);
+            if (group === undefined) {
+                return undefined;
+            }
+            return { kind: "agent-md", target: "group", group };
+        }
+        return undefined;
+    }
     if (parts[1] === "hunks" && parts.length === 3 && parts[2] !== undefined) {
         const group = jsonStem(parts[2]);
         if (group === undefined) {
@@ -102,6 +119,12 @@ function decodeSegment(segment) {
         return segment;
     }
 }
+function agentMdRel(resource) {
+    if (resource.target === "overview") {
+        return "api/agent/overview.md";
+    }
+    return `api/agent/groups/${encodeURIComponent(resource.group)}.md`;
+}
 function jsonStem(file) {
     if (!file.endsWith(".json")) {
         return undefined;
@@ -109,6 +132,13 @@ function jsonStem(file) {
     const stem = file.slice(0, -".json".length);
     return stem === "" ? undefined : stem;
 }
+function mdStem(file) {
+    if (!file.endsWith(".md")) {
+        return undefined;
+    }
+    const stem = file.slice(0, -".md".length);
+    return stem === "" ? undefined : stem;
+}
 function isRepoPath(path) {
     return path !== "" && !path.startsWith("/") && !path.includes("\0") && !path.split("/").includes("..");
 }

package/dist/git/repo.js

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import { git, gitOk } from "./exec.js";
 export async function assertWorkTree(cwd) {
     const inside = await git(cwd, ["rev-parse", "--is-inside-work-tree"], { allowFail: true });
@@ -14,6 +15,47 @@ export async function mergeBase(cwd, baseRef, headRef) {
     const sha = await git(cwd, ["merge-base", baseRef, headRef]);
     return sha.trim();
 }
+/** Last path segment of a git remote URL, without .git. */
+export function nameFromRemoteUrl(url) {
+    let value = url.trim();
+    if (value === "") {
+        return null;
+    }
+    value = value.replace(/\.git$/i, "").replace(/\/+$/, "");
+    const pathPart = value.includes("://")
+        ? value.replace(/^[^:]+:\/\/[^/]+\//, "")
+        : value.includes(":")
+            ? value.slice(value.lastIndexOf(":") + 1)
+            : value;
+    const last = pathPart.split("/").filter(Boolean).at(-1);
+    return last === undefined || last === "" ? null : last;
+}
+export async function readRepoIdentity(cwd) {
+    const originText = (await git(cwd, ["config", "--get", "remote.origin.url"], { allowFail: true })).trim();
+    const origin = originText === "" ? null : stripRemoteCredentials(originText);
+    const top = (await git(cwd, ["rev-parse", "--show-toplevel"])).trim();
+    const fromOrigin = origin !== null ? nameFromRemoteUrl(origin) : null;
+    return { name: fromOrigin ?? basename(top), origin };
+}
+/** Drop userinfo from an http(s) remote so a copied prompt never carries a token. */
+export function stripRemoteCredentials(url) {
+    const trimmed = url.trim();
+    if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(trimmed)) {
+        return trimmed;
+    }
+    try {
+        const parsed = new URL(trimmed);
+        if (parsed.username === "" && parsed.password === "") {
+            return trimmed;
+        }
+        parsed.username = "";
+        parsed.password = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        return trimmed;
+    }
+}
 /** Resolve refs to commits once. Later checkout or branch motion does not move these SHAs. */
 export async function pinRange(cwd, baseRef, headRef) {
     const baseSha = await resolveCommit(cwd, baseRef);

package/dist/server/http.js

@@ -11,6 +11,7 @@ const MIME = {
     ".js": "text/javascript; charset=utf-8",
     ".css": "text/css; charset=utf-8",
     ".json": "application/json; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
     ".svg": "image/svg+xml",
     ".map": "application/json; charset=utf-8",
     ".woff2": "font/woff2",