comprehende 0.2.0 → 0.4.0

package/README.md

@@ -25,16 +25,25 @@ 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 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.2.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
+`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.
+
+`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.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
 
 ## Release
 
-Bump `version` in `package.json` when the CLI or UI changes, then run `pnpm sync:skill` so the skill pin matches. Pre-commit and `pnpm test` fail if the staged package version and skill pin differ. Do not bump for skill-only edits.
+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.
+
+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.
 
 Push to `main`. CI packs and tests the tarball on every change. If the version is not on npm yet, CI publishes it. Skill-only commits keep the same version, so they do not publish.
 
@@ -48,4 +57,16 @@ cd fixtures/repo
 node ../../dist/cli/main.js serve --data ../example/review.json
 ```
 
-`pnpm fixture` writes a tiny git repo to `fixtures/repo` (gitignored) and a refs-only `fixtures/example/review.json`. Serve with cwd set to `fixtures/repo`.
+Export a static copy (cwd still `fixtures/repo`):
+
+```sh
+node ../../dist/cli/main.js export --data ../example/review.json --out ../../fixtures/site
+```
+
+The folder has the UI plus frozen `api/*.json` payloads and image bytes. There is no git in that folder. Host it with any static file server:
+
+```sh
+python3 -m http.server --directory ../../fixtures/site 8080
+```
+
+`pnpm fixture` writes a tiny git repo to `fixtures/repo` (gitignored) and a refs-only `fixtures/example/review.json`. Serve or export with cwd set to `fixtures/repo`.

package/dist/api/error.js

@@ -0,0 +1,8 @@
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+    }
+}

package/dist/api/live.js

@@ -0,0 +1,295 @@
+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 { GitError } from "../git/exec.js";
+import { listCommits } from "../git/log.js";
+import { mergeBase } 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) {
+    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 {
+        cwd,
+        document,
+        resolved: {
+            baseRef: document.source.baseRef,
+            headRef: document.source.headRef,
+            range: document.source.range ?? `${document.source.baseRef}...${document.source.headRef}`,
+            baseSha: resolvedRefs.baseSha,
+            headSha: resolvedRefs.headSha,
+        },
+        files,
+        coverage,
+        mergeBaseSha,
+        commits,
+    };
+}
+export function reviewPayload(ctx) {
+    const { document, resolved, files, coverage, commits } = ctx;
+    const lockfiles = lockfileFiles(files);
+    return {
+        document,
+        resolved,
+        coverage: {
+            totalHunks: coverage.totalHunks,
+            assignedHunks: coverage.assignedHunks,
+            unassignedCount: coverage.unassigned.length,
+            staleCount: coverage.stale.length,
+        },
+        groups: coverage.groups
+            .slice()
+            .sort((a, b) => a.group.suggestedOrder - b.group.suggestedOrder || a.group.id.localeCompare(b.group.id))
+            .map((group) => ({
+            id: group.group.id,
+            title: group.group.title,
+            why: group.group.why,
+            summary: group.group.summary,
+            lookFor: group.group.lookFor ?? [],
+            dependsOn: group.group.dependsOn ?? [],
+            part: group.group.part,
+            suggestedOrder: group.group.suggestedOrder,
+            hunkCount: group.hunks.length,
+            staleCount: group.stale.length,
+            files: uniquePaths(group.hunks),
+        })),
+        unassigned: {
+            hunkCount: coverage.unassigned.length,
+            files: uniquePaths(coverage.unassigned),
+        },
+        lockfiles: {
+            fileCount: lockfiles.length,
+            files: lockfiles.map((file) => file.path),
+        },
+        stale: coverage.stale,
+        files: files.map((file) => {
+            const entry = {
+                path: file.path,
+                status: file.status,
+                binary: file.binary,
+                image: file.image,
+                hunkCount: file.hunks.length,
+            };
+            if (file.oldPath !== undefined) {
+                entry.oldPath = file.oldPath;
+            }
+            return entry;
+        }),
+        skipped: files.filter((file) => file.binary && !file.image).map((file) => ({ path: file.path, reason: "binary" })),
+        commits,
+    };
+}
+export function hunksPayload(ctx, groupId) {
+    if (groupId === "") {
+        throw new ApiError(400, "missing group");
+    }
+    if (groupId === "unassigned") {
+        return serializeLayer(ctx.files, ctx.coverage.unassigned);
+    }
+    if (groupId === "lockfiles") {
+        return serializeLockfiles(ctx.files);
+    }
+    const group = ctx.coverage.groups.find((item) => item.group.id === groupId);
+    if (group === undefined) {
+        throw new ApiError(404, `unknown group "${groupId}"`);
+    }
+    return serializeLayer(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;
+    try {
+        const content = await showFile(ctx.cwd, ref, lookup);
+        return { path: lookup, ref, side, content, language: fileLanguage(lookup) };
+    }
+    catch (error) {
+        throw new ApiError(404, error instanceof Error ? error.message : "file not found");
+    }
+}
+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;
+    try {
+        const lines = await blameFile(ctx.cwd, ref, lookup);
+        return { path: lookup, ref, side, lines };
+    }
+    catch (error) {
+        throw new ApiError(404, error instanceof Error ? error.message : "blame not available");
+    }
+}
+export async function imagePayload(ctx, path, side) {
+    const file = findFile(ctx.files, path);
+    if (!file.image) {
+        throw new ApiError(404, "path is not an image in the live diff");
+    }
+    const lookup = side === "old" ? (file.oldPath ?? file.path) : file.path;
+    assertSideExists(file, side);
+    const ref = side === "old" ? ctx.mergeBaseSha : ctx.document.source.headRef;
+    try {
+        const blob = await readImageBlob(ctx.cwd, ref, lookup);
+        if (!blob.ok) {
+            throw new ApiError(404, `Git LFS object sha256:${blob.oid} is not in this clone`);
+        }
+        return { encoding: "bytes", mediaType: blob.mediaType, body: blob.bytes };
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            throw error;
+        }
+        throw new ApiError(404, error instanceof Error ? error.message : "image not found");
+    }
+}
+export async function renderResource(ctx, resource) {
+    switch (resource.kind) {
+        case "review":
+            return { encoding: "json", body: reviewPayload(ctx) };
+        case "hunks":
+            return { encoding: "json", body: hunksPayload(ctx, resource.group) };
+        case "file":
+            return { encoding: "json", body: await filePayload(ctx, resource.path, resource.side) };
+        case "blame":
+            return { encoding: "json", body: await blamePayload(ctx, resource.path, resource.side) };
+        case "image":
+            return imagePayload(ctx, resource.path, resource.side);
+        case "patch":
+            return { encoding: "json", body: await patchPayload(ctx, resource.path) };
+    }
+}
+export function listResources(ctx) {
+    const resources = [
+        { kind: "review" },
+        { kind: "hunks", group: "unassigned" },
+        { kind: "hunks", group: "lockfiles" },
+    ];
+    for (const group of ctx.document.groups) {
+        resources.push({ kind: "hunks", group: group.id });
+    }
+    for (const file of ctx.files) {
+        if (file.image) {
+            for (const side of sidesFor(file)) {
+                resources.push({ kind: "image", path: file.path, side });
+            }
+            continue;
+        }
+        if (isLockfilePath(file.path) && !file.binary) {
+            resources.push({ kind: "patch", path: file.path });
+        }
+        for (const side of sidesFor(file)) {
+            resources.push({ kind: "file", path: file.path, side });
+            resources.push({ kind: "blame", path: file.path, side });
+        }
+    }
+    return resources;
+}
+function sidesFor(file) {
+    if (file.status === "added") {
+        return ["new"];
+    }
+    if (file.status === "deleted") {
+        return ["old"];
+    }
+    return ["old", "new"];
+}
+function serializeLayer(files, hunks) {
+    const groups = [];
+    for (const hunk of hunks) {
+        const existing = groups.find((group) => group.file.path === hunk.path);
+        if (existing !== undefined) {
+            existing.hunks.push(hunk);
+            continue;
+        }
+        const file = files.find((item) => item.path === hunk.path);
+        if (file === undefined) {
+            continue;
+        }
+        groups.push({ file, hunks: [hunk] });
+    }
+    const serializedFiles = groups.map(({ file, hunks: fileHunks }) => serializeLayerFile(file, fileHunks, true));
+    return { hunks: hunks.map(serializeHunk), files: serializedFiles };
+}
+function serializeLockfiles(files) {
+    const serializedFiles = lockfileFiles(files).map((file) => serializeLayerFile(file, [], true));
+    return { hunks: [], files: serializedFiles };
+}
+function lockfileFiles(files) {
+    return files.filter((file) => isLockfilePath(file.path) && !file.binary && !file.image);
+}
+async function patchPayload(ctx, path) {
+    const file = findFile(ctx.files, 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);
+    if (live === undefined) {
+        throw new ApiError(404, `no live diff for ${path}`);
+    }
+    return serializeLayerFile(live, live.hunks, false);
+}
+function serializeLayerFile(file, fileHunks, deferLockfile) {
+    const lockfile = isLockfilePath(file.path) && !file.binary && !file.image;
+    const deferred = deferLockfile && lockfile;
+    const next = {
+        path: file.path,
+        kind: file.image ? "image" : lockfile ? "lockfile" : "text",
+        status: file.status,
+        patch: deferred ? "" : file.image ? file.headerPatch : filePatchFromGit(file, fileHunks),
+        hunks: fileHunks.map(serializeHunk),
+    };
+    if (file.oldPath !== undefined) {
+        next.oldPath = file.oldPath;
+    }
+    if (file.added !== undefined) {
+        next.added = file.added;
+    }
+    if (file.removed !== undefined) {
+        next.removed = file.removed;
+    }
+    return next;
+}
+function serializeHunk(hunk) {
+    return {
+        ...toHunkRef(hunk),
+        header: hunk.header,
+        language: fileLanguage(hunk.path),
+        lines: hunk.lines,
+    };
+}
+function findFile(files, path) {
+    const file = files.find((item) => item.path === path || item.oldPath === path);
+    if (file === undefined) {
+        throw new ApiError(404, `path is not in the live diff: ${path}`);
+    }
+    return file;
+}
+function assertSideExists(file, side) {
+    if (side === "old" && file.status === "added") {
+        throw new ApiError(404, "file did not exist on the base side");
+    }
+    if (side === "new" && file.status === "deleted") {
+        throw new ApiError(404, "file does not exist on the head side");
+    }
+}
+function uniquePaths(hunks) {
+    return [...new Set(hunks.map((hunk) => hunk.path))];
+}
+export function snapshotJson(body) {
+    return `${JSON.stringify(body)}\n`;
+}
+export function isUnavailableSnapshot(error) {
+    if (error instanceof ApiError) {
+        return error.status === 404 || error.status === 400;
+    }
+    return error instanceof GitError;
+}

package/dist/api/paths.js

@@ -0,0 +1,114 @@
+export function apiHref(resource) {
+    switch (resource.kind) {
+        case "review":
+            return "api/review.json";
+        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`;
+    }
+}
+/** Decoded relative path under the site root. Static hosts map encoded request URLs onto this. */
+export function apiFsRel(resource) {
+    switch (resource.kind) {
+        case "review":
+            return "api/review.json";
+        case "hunks":
+            return `api/hunks/${encodeURIComponent(resource.group)}.json`;
+        case "file":
+            return `api/files/${resource.side}/${resource.path}.json`;
+        case "blame":
+            return `api/blame/${resource.side}/${resource.path}.json`;
+        case "image":
+            return `api/images/${resource.side}/${resource.path}`;
+        case "patch":
+            return `api/patches/${resource.path}.json`;
+    }
+}
+export function parseApiPath(pathname) {
+    const parts = pathname.split("/").filter((part) => part !== "").map(decodeSegment);
+    if (parts[0] !== "api" || parts[1] === undefined) {
+        return undefined;
+    }
+    if (parts[1] === "review.json" && parts.length === 2) {
+        return { kind: "review" };
+    }
+    if (parts[1] === "hunks" && parts.length === 3 && parts[2] !== undefined) {
+        const group = jsonStem(parts[2]);
+        if (group === undefined) {
+            return undefined;
+        }
+        return { kind: "hunks", group };
+    }
+    if (parts[1] === "images" && parts.length >= 4 && parts[2] !== undefined) {
+        const side = parts[2];
+        if (side !== "old" && side !== "new") {
+            return undefined;
+        }
+        const path = parts.slice(3).join("/");
+        if (!isRepoPath(path)) {
+            return undefined;
+        }
+        return { kind: "image", path, side };
+    }
+    if (parts[1] === "patches" && parts.length >= 3) {
+        const rest = parts.slice(2);
+        const last = rest.at(-1);
+        const stem = last === undefined ? undefined : jsonStem(last);
+        if (stem === undefined) {
+            return undefined;
+        }
+        rest[rest.length - 1] = stem;
+        const path = rest.join("/");
+        if (!isRepoPath(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") {
+            return undefined;
+        }
+        const rest = parts.slice(3);
+        const last = rest.at(-1);
+        const stem = last === undefined ? undefined : jsonStem(last);
+        if (stem === undefined) {
+            return undefined;
+        }
+        rest[rest.length - 1] = stem;
+        const path = rest.join("/");
+        if (!isRepoPath(path)) {
+            return undefined;
+        }
+        return { kind: parts[1] === "files" ? "file" : "blame", path, side };
+    }
+    return undefined;
+}
+function encodeFilePath(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+function jsonStem(file) {
+    if (!file.endsWith(".json")) {
+        return undefined;
+    }
+    const stem = file.slice(0, -".json".length);
+    return stem === "" ? undefined : stem;
+}
+function isRepoPath(path) {
+    return path !== "" && !path.startsWith("/") && !path.includes("\0") && !path.split("/").includes("..");
+}

package/dist/api/snapshot.js

@@ -0,0 +1,45 @@
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { findPackageRoot } from "../package-root.js";
+import { isUnavailableSnapshot, listResources, openReview, renderResource, snapshotJson, } from "./live.js";
+import { apiFsRel } from "./paths.js";
+export async function exportStaticSite(opts) {
+    const outDir = resolve(opts.outDir);
+    const uiRoot = opts.uiRoot ?? join(findPackageRoot(), "dist/ui");
+    if (!existsSync(uiRoot)) {
+        throw new Error("UI is missing from this install. Reinstall comprehende from npm, or from a git checkout run `pnpm build`.");
+    }
+    if (existsSync(join(outDir, ".git"))) {
+        throw new Error(`refusing to write export into a git repository: ${outDir}`);
+    }
+    const ctx = opts.ctx ?? (await openReview(opts.cwd, opts.dataPath));
+    await mkdir(outDir, { recursive: true });
+    await rm(join(outDir, "assets"), { recursive: true, force: true });
+    await rm(join(outDir, "api"), { recursive: true, force: true });
+    await cp(uiRoot, outDir, { recursive: true });
+    const apiFiles = [];
+    for (const resource of listResources(ctx)) {
+        let body;
+        try {
+            body = await renderResource(ctx, resource);
+        }
+        catch (error) {
+            if (isUnavailableSnapshot(error)) {
+                continue;
+            }
+            throw error;
+        }
+        const rel = apiFsRel(resource);
+        const abs = join(outDir, ...rel.split("/"));
+        await mkdir(dirname(abs), { recursive: true });
+        if (body.encoding === "json") {
+            await writeFile(abs, snapshotJson(body.body));
+        }
+        else {
+            await writeFile(abs, Buffer.from(body.body));
+        }
+        apiFiles.push(rel);
+    }
+    return { outDir, apiFiles };
+}

package/dist/api/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/args.js

@@ -1,4 +1,4 @@
-const COMMANDS = new Set(["index", "validate", "serve"]);
+const COMMANDS = new Set(["index", "validate", "serve", "export"]);
 export const USAGE = `Usage: comprehende <command> [options]
 
 Run inside the git repository under review. Cwd is the repo.
@@ -13,16 +13,21 @@ Commands:
   serve     --data <review.json> [--port <n>] [--open]
             Serve the local UI on 127.0.0.1 (re-reads git on each request)
 
+  export    --data <review.json> --out <dir>
+            Write a static site (same UI + frozen git payloads). No server after that.
+
 Options:
   --base <ref>     Base ref (default: origin/HEAD or main/master)
   --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)
   --open           Open the UI in a browser
   -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.
 `;
 export function parseArgv(argv, cwd = process.cwd()) {
     const args = argv[0] === "--" ? argv.slice(1) : [...argv];
@@ -52,6 +57,7 @@ export function parseArgv(argv, cwd = process.cwd()) {
             base: flag(rest, "--base"),
             head: flag(rest, "--head"),
             data: flag(rest, "--data"),
+            out: flag(rest, "--out"),
             port,
             open: rest.includes("--open"),
         };

package/dist/cli/commands.js

@@ -28,6 +28,12 @@ export function resolveDataPath(data, cwd) {
     }
     return isAbsolute(data) ? data : resolve(cwd, data);
 }
+export function resolveOutPath(out, cwd) {
+    if (out === undefined) {
+        throw new Error("missing --out <dir>");
+    }
+    return isAbsolute(out) ? out : resolve(cwd, out);
+}
 export async function cmdValidate(cwd, dataPath) {
     const document = await loadDocument(dataPath);
     await resolveSource(cwd, document.source.baseRef, document.source.headRef);

package/dist/cli/main.js

@@ -4,9 +4,10 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgv, USAGE } from "./args.js";
-import { cmdIndex, cmdValidate, loadDocument, resolveDataPath } from "./commands.js";
-import { resolveSource } from "../git/diff.js";
-import { coverReview, coverageErrors } from "../review/coverage.js";
+import { cmdIndex, cmdValidate, resolveDataPath, resolveOutPath } from "./commands.js";
+import { exportStaticSite } from "../api/snapshot.js";
+import { openReview } from "../api/live.js";
+import { coverageErrors } from "../review/coverage.js";
 import { assertWorkTree } from "../git/repo.js";
 import { readPackageVersion } from "../package-root.js";
 import { startServer } from "../server/http.js";
@@ -41,13 +42,8 @@ export async function run(argv) {
             }
             case "serve": {
                 const dataPath = resolveDataPath(request.data, request.cwd);
-                const document = await loadDocument(dataPath);
-                await resolveSource(request.cwd, document.source.baseRef, document.source.headRef);
-                const { coverage } = await coverReview(request.cwd, document);
-                const problems = coverageErrors(coverage);
-                if (problems.length > 0) {
-                    console.error(`coverage issues (serve continues; git wins, unassigned/stale are visible):\n${problems.join("\n\n")}`);
-                }
+                const ctx = await openReview(request.cwd, dataPath);
+                warnCoverage(ctx.coverage, "serve continues; git wins, unassigned/stale are visible");
                 const running = await startServer({ cwd: request.cwd, dataPath, port: request.port });
                 console.log(running.url);
                 console.error(`serving ${dataPath}  cwd=${request.cwd}  localhost only`);
@@ -57,6 +53,16 @@ export async function run(argv) {
                 await waitForClose(running.server);
                 return 0;
             }
+            case "export": {
+                const dataPath = resolveDataPath(request.data, request.cwd);
+                const outDir = resolveOutPath(request.out, request.cwd);
+                const ctx = await openReview(request.cwd, dataPath);
+                warnCoverage(ctx.coverage, "export continues; git wins, unassigned/stale are visible");
+                const result = await exportStaticSite({ cwd: request.cwd, dataPath, outDir, ctx });
+                console.log(result.outDir);
+                console.error(`exported ${dataPath}  ${result.apiFiles.length} api files  no git in the folder`);
+                return 0;
+            }
         }
     }
     catch (error) {
@@ -64,6 +70,12 @@ export async function run(argv) {
         return 1;
     }
 }
+function warnCoverage(coverage, note) {
+    const problems = coverageErrors(coverage);
+    if (problems.length > 0) {
+        console.error(`coverage issues (${note}):\n${problems.join("\n\n")}`);
+    }
+}
 function waitForClose(server) {
     return new Promise((resolve) => {
         const shutdown = () => {

package/dist/git/blob.js

@@ -0,0 +1,21 @@
+import { imageMediaType } from "../schema/image.js";
+import { gitBuffer } from "./exec.js";
+import { parseLfsPointer, readLfsObject } from "./lfs.js";
+import { assertSafePath, assertSafeRef } from "./repo.js";
+export async function readBlob(cwd, ref, path) {
+    assertSafeRef(ref);
+    assertSafePath(path);
+    return gitBuffer(cwd, ["cat-file", "blob", `${ref}:${path}`]);
+}
+export async function readImageBlob(cwd, ref, path) {
+    const blob = await readBlob(cwd, ref, path);
+    const pointer = parseLfsPointer(blob);
+    if (pointer === undefined) {
+        return { ok: true, bytes: blob, mediaType: imageMediaType(path), lfs: false };
+    }
+    const object = await readLfsObject(cwd, pointer);
+    if (object === undefined) {
+        return { ok: false, oid: pointer.oid };
+    }
+    return { ok: true, bytes: object, mediaType: imageMediaType(path), lfs: true };
+}