comprehende 0.4.1 → 0.5.0

package/README.md

@@ -14,28 +14,35 @@ From this checkout:
 npx skills add ./ --skill comprehende
 ```
 
+## Why
+
+Usage of AI agents to write code has given us previously unseen ability to write code. A lot of code.
+
+Three concepts are important to understand:
+
+- Cognitive offloading: when we use tools by handing off the _how_ but keeping the _why_ and the _what_ - like a calculator adding numbers, we know why we need the sum, we tell it the two numbers to add together, it doesn't invent them
+- Cognitive surrender: when we stop constructing an answer and adopt the answer from the tool instead, without having our own view to compare against - like letting the calculator add two numbers together, letting it make up the numbers and accepting the answer.
+- Comprehension debt: the gap between the amount of code in the system and the amount of understanding the humans developing, maintaining or operating the system has.
+  - Comprehension debt compares to technical debt in a way, but there are very important differences
+  - Technical debt is a conscious tradeoff, meanwhile comprehension debt builds up without human decision
+  - Unlike tech debt, dragging us down (slow builds, dependencies etc.), comprehension debt is invisible, everything seems good until it doesn't - tests green, codebase looks clean, but nobody really understands what's going on
+  - Until something breaks, no-one knows where these debts are located.
+
+Cognitive surrender is the means to increase the comprehension debt in the project. In terms of AI coding agents, every time we are blindly accepting code generated by the agents, we increase this debt. This debt eventually bites back, and it does so where it hurts the most: during an incident, during a debug session, while struggling with trying to keep the AI bills down so that we don't run out of tokens after a day of work.
+
+This tool is for preventing this cognitive surrender while trying to maintain momentum created by the AI agents. By moving the balance from cognitive surrender to cognitive offloading, we want to keep ourselves in the loop while still allowing us to make advantage of the efficiency gains provided by AI coding agents.
+
 ## Develop
 
 [pnpm](https://pnpm.io/).
 
-```sh
-pnpm install
-pnpm test
-pnpm typecheck
-pnpm build
-pnpm pack:smoke
-pnpm sync:skill
-pnpm release:skill
-pnpm dev -- --help
-```
-
 `pnpm build` emits `dist/cli` and `dist/ui`. `prepack` runs that build, so `pnpm pack` / `pnpm publish` always ship the UI.
 
 `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 layer. Serve computes those payloads 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.
 
-`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.4.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.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
 
 ## Release
 

package/dist/api/live.js

@@ -1,22 +1,23 @@
 import { loadDocument } from "../cli/commands.js";
 import { blameFile } from "../git/blame.js";
 import { readImageBlob } from "../git/blob.js";
-import { fileLanguage, filePatchFromGit, readPathDiff, resolveSource, toHunkRef } from "../git/diff.js";
+import { fileLanguage, filePatchFromGit, readPathDiff, toHunkRef } from "../git/diff.js";
 import { GitError } from "../git/exec.js";
 import { listCommits } from "../git/log.js";
-import { mergeBase } from "../git/repo.js";
+import { pinRange } from "../git/repo.js";
 import { showFile } from "../git/show.js";
 import { coverReview } from "../review/coverage.js";
 import { isLockfilePath } from "../schema/lockfile.js";
 import { ApiError } from "./error.js";
-export async function openReview(cwd, dataPath) {
+export async function pinReviewSource(cwd, dataPath) {
     const document = await loadDocument(dataPath);
-    const resolvedRefs = await resolveSource(cwd, document.source.baseRef, document.source.headRef);
-    const { files, coverage } = await coverReview(cwd, document);
-    const [mergeBaseSha, commits] = await Promise.all([
-        mergeBase(cwd, document.source.baseRef, document.source.headRef),
-        listCommits(cwd, document.source.baseRef, document.source.headRef),
-    ]);
+    return pinRange(cwd, document.source.baseRef, document.source.headRef);
+}
+export async function openReview(cwd, dataPath, pin) {
+    const document = await loadDocument(dataPath);
+    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);
     return {
         cwd,
         document,
@@ -24,12 +25,12 @@ export async function openReview(cwd, dataPath) {
             baseRef: document.source.baseRef,
             headRef: document.source.headRef,
             range: document.source.range ?? `${document.source.baseRef}...${document.source.headRef}`,
-            baseSha: resolvedRefs.baseSha,
-            headSha: resolvedRefs.headSha,
+            baseSha: range.baseSha,
+            headSha: range.headSha,
         },
         files,
         coverage,
-        mergeBaseSha,
+        mergeBaseSha: range.mergeBaseSha,
         commits,
     };
 }
@@ -92,7 +93,7 @@ export function hunksPayload(ctx, groupId) {
         throw new ApiError(400, "missing group");
     }
     if (groupId === "unassigned") {
-        return serializeLayer(ctx.files, ctx.coverage.unassigned);
+        return serializeGroup(ctx.files, ctx.coverage.unassigned);
     }
     if (groupId === "lockfiles") {
         return serializeLockfiles(ctx.files);
@@ -101,13 +102,13 @@ export function hunksPayload(ctx, groupId) {
     if (group === undefined) {
         throw new ApiError(404, `unknown group "${groupId}"`);
     }
-    return serializeLayer(ctx.files, group.hunks);
+    return serializeGroup(ctx.files, group.hunks);
 }
 export async function filePayload(ctx, path, side) {
     const file = findFile(ctx.files, path);
     const lookup = side === "old" ? (file.oldPath ?? file.path) : file.path;
     assertSideExists(file, side);
-    const ref = side === "old" ? ctx.mergeBaseSha : ctx.document.source.headRef;
+    const ref = side === "old" ? ctx.mergeBaseSha : ctx.resolved.headSha;
     try {
         const content = await showFile(ctx.cwd, ref, lookup);
         return { path: lookup, ref, side, content, language: fileLanguage(lookup) };
@@ -120,7 +121,7 @@ export async function blamePayload(ctx, path, side) {
     const file = findFile(ctx.files, path);
     const lookup = side === "old" ? (file.oldPath ?? file.path) : file.path;
     assertSideExists(file, side);
-    const ref = side === "old" ? ctx.mergeBaseSha : ctx.document.source.headRef;
+    const ref = side === "old" ? ctx.mergeBaseSha : ctx.resolved.headSha;
     try {
         const lines = await blameFile(ctx.cwd, ref, lookup);
         return { path: lookup, ref, side, lines };
@@ -136,7 +137,7 @@ export async function imagePayload(ctx, path, side) {
     }
     const lookup = side === "old" ? (file.oldPath ?? file.path) : file.path;
     assertSideExists(file, side);
-    const ref = side === "old" ? ctx.mergeBaseSha : ctx.document.source.headRef;
+    const ref = side === "old" ? ctx.mergeBaseSha : ctx.resolved.headSha;
     try {
         const blob = await readImageBlob(ctx.cwd, ref, lookup);
         if (!blob.ok) {
@@ -202,10 +203,10 @@ function sidesFor(file) {
     }
     return ["old", "new"];
 }
-function serializeLayer(files, hunks) {
-    const groups = [];
+function serializeGroup(files, hunks) {
+    const filesByPath = [];
     for (const hunk of hunks) {
-        const existing = groups.find((group) => group.file.path === hunk.path);
+        const existing = filesByPath.find((entry) => entry.file.path === hunk.path);
         if (existing !== undefined) {
             existing.hunks.push(hunk);
             continue;
@@ -214,13 +215,13 @@ function serializeLayer(files, hunks) {
         if (file === undefined) {
             continue;
         }
-        groups.push({ file, hunks: [hunk] });
+        filesByPath.push({ file, hunks: [hunk] });
     }
-    const serializedFiles = groups.map(({ file, hunks: fileHunks }) => serializeLayerFile(file, fileHunks, true));
+    const serializedFiles = filesByPath.map(({ file, hunks: fileHunks }) => serializeGroupFile(file, fileHunks, true));
     return { hunks: hunks.map(serializeHunk), files: serializedFiles };
 }
 function serializeLockfiles(files) {
-    const serializedFiles = lockfileFiles(files).map((file) => serializeLayerFile(file, [], true));
+    const serializedFiles = lockfileFiles(files).map((file) => serializeGroupFile(file, [], true));
     return { hunks: [], files: serializedFiles };
 }
 function lockfileFiles(files) {
@@ -231,13 +232,13 @@ 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.document.source.baseRef, ctx.document.source.headRef, file.path);
+    const live = await readPathDiff(ctx.cwd, ctx.resolved.baseSha, ctx.resolved.headSha, file.path);
     if (live === undefined) {
         throw new ApiError(404, `no live diff for ${path}`);
     }
-    return serializeLayerFile(live, live.hunks, false);
+    return serializeGroupFile(live, live.hunks, false);
 }
-function serializeLayerFile(file, fileHunks, deferLockfile) {
+function serializeGroupFile(file, fileHunks, deferLockfile) {
     const lockfile = isLockfilePath(file.path) && !file.binary && !file.image;
     const deferred = deferLockfile && lockfile;
     const next = {
@@ -245,6 +246,7 @@ function serializeLayerFile(file, fileHunks, deferLockfile) {
         kind: file.image ? "image" : lockfile ? "lockfile" : "text",
         status: file.status,
         patch: deferred ? "" : file.image ? file.headerPatch : filePatchFromGit(file, fileHunks),
+        complete: file.hunks.length === fileHunks.length,
         hunks: fileHunks.map(serializeHunk),
     };
     if (file.oldPath !== undefined) {

package/dist/cli/args.js

@@ -11,7 +11,7 @@ Commands:
             Check schema, ref resolution, and hunk coverage
 
   serve     --data <review.json> [--port <n>] [--open]
-            Serve the local UI on 127.0.0.1 (re-reads git on each request)
+            Serve the local UI on 127.0.0.1 (pins commit SHAs at start)
 
   export    --data <review.json> --out <dir>
             Write a static site (same UI + frozen git payloads). No server after that.
@@ -26,8 +26,8 @@ Options:
   -h, --help       Show this help
   -v, --version    Show version
 
-Diffs always come from git in cwd. The review document is interpretation only.
-Export is a point-in-time copy. Rebase or new commits need a new export.
+Diffs come from git objects at the pinned SHAs. The review document is interpretation only.
+Serve resolves refs when it starts. A later checkout does not change that review.
 `;
 export function parseArgv(argv, cwd = process.cwd()) {
     const args = argv[0] === "--" ? argv.slice(1) : [...argv];

package/dist/cli/main.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { parseArgv, USAGE } from "./args.js";
 import { cmdIndex, cmdValidate, resolveDataPath, resolveOutPath } from "./commands.js";
 import { exportStaticSite } from "../api/snapshot.js";
-import { openReview } from "../api/live.js";
+import { openReview, pinReviewSource } from "../api/live.js";
 import { coverageErrors } from "../review/coverage.js";
 import { assertWorkTree } from "../git/repo.js";
 import { readPackageVersion } from "../package-root.js";
@@ -42,9 +42,10 @@ export async function run(argv) {
             }
             case "serve": {
                 const dataPath = resolveDataPath(request.data, request.cwd);
-                const ctx = await openReview(request.cwd, dataPath);
+                const pin = await pinReviewSource(request.cwd, dataPath);
+                const ctx = await openReview(request.cwd, dataPath, pin);
                 warnCoverage(ctx.coverage, "serve continues; git wins, unassigned/stale are visible");
-                const running = await startServer({ cwd: request.cwd, dataPath, port: request.port });
+                const running = await startServer({ cwd: request.cwd, dataPath, port: request.port, pin });
                 console.log(running.url);
                 console.error(`serving ${dataPath}  cwd=${request.cwd}  localhost only`);
                 if (request.open) {

package/dist/git/repo.js

@@ -14,6 +14,13 @@ export async function mergeBase(cwd, baseRef, headRef) {
     const sha = await git(cwd, ["merge-base", baseRef, headRef]);
     return sha.trim();
 }
+/** 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);
+    const headSha = await resolveCommit(cwd, headRef);
+    const mergeBaseSha = await mergeBase(cwd, baseSha, headSha);
+    return { baseRef, headRef, baseSha, headSha, mergeBaseSha };
+}
 export async function defaultBaseRef(cwd) {
     const remoteHead = await git(cwd, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], { allowFail: true });
     const trimmed = remoteHead.trim();

package/dist/git/show.js

@@ -1,9 +1,9 @@
+import { readBlob } from "./blob.js";
 import { assertSafePath, assertSafeRef } from "./repo.js";
 import { git } from "./exec.js";
 export async function showFile(cwd, ref, path) {
-    assertSafeRef(ref);
-    assertSafePath(path);
-    return git(cwd, ["show", "--end-of-options", `${ref}:${path}`]);
+    const bytes = await readBlob(cwd, ref, path);
+    return bytes.toString("utf8");
 }
 export async function fileExistsAt(cwd, ref, path) {
     assertSafeRef(ref);

package/dist/review/coverage.js

@@ -1,8 +1,10 @@
 import { flattenHunks, readDiff, toHunkRef } from "../git/diff.js";
+import { pinRange } from "../git/repo.js";
 import { hunkKey } from "../schema/identity.js";
 import { isLockfilePath } from "../schema/lockfile.js";
-export async function coverReview(cwd, document) {
-    const files = await readDiff(cwd, document.source.baseRef, document.source.headRef);
+export async function coverReview(cwd, document, pin) {
+    const range = pin ?? (await pinRange(cwd, document.source.baseRef, document.source.headRef));
+    const files = await readDiff(cwd, range.baseSha, range.headSha);
     const live = flattenHunks(files);
     return { files, coverage: joinCoverage(document, live) };
 }

package/dist/server/http.js

@@ -2,7 +2,7 @@ import { createServer } from "node:http";
 import { createReadStream, existsSync, statSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
 import { ApiError } from "../api/error.js";
-import { openReview, renderResource, snapshotJson } from "../api/live.js";
+import { openReview, pinReviewSource, renderResource, snapshotJson } from "../api/live.js";
 import { parseApiPath } from "../api/paths.js";
 import { GitError } from "../git/exec.js";
 import { findPackageRoot } from "../package-root.js";
@@ -25,8 +25,10 @@ const MIME = {
 };
 export async function startServer(opts) {
     const uiRoot = opts.uiRoot ?? join(findPackageRoot(), "dist/ui");
+    const pin = opts.pin ?? (await pinReviewSource(opts.cwd, opts.dataPath));
+    const bound = { ...opts, pin };
     const server = createServer((req, res) => {
-        void handle(req, res, opts, uiRoot);
+        void handle(req, res, bound, uiRoot);
     });
     await new Promise((resolveListen, reject) => {
         server.listen(opts.port, "127.0.0.1", () => resolveListen());
@@ -53,7 +55,7 @@ async function handle(req, res, opts, uiRoot) {
         }
         const resource = parseApiPath(url.pathname);
         if (resource !== undefined) {
-            const ctx = await openReview(opts.cwd, opts.dataPath);
+            const ctx = await openReview(opts.cwd, opts.dataPath, opts.pin);
             sendSnapshot(res, 200, await renderResource(ctx, resource));
             return;
         }