comprehende 0.1.0 → 0.3.0

package/dist/git/diff.js

@@ -1,3 +1,4 @@
+import { isImagePath, isLfsPointerText } from "../schema/image.js";
 import { git } from "./exec.js";
 import { rangeLabel, resolveCommit } from "./repo.js";
 const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
@@ -23,7 +24,7 @@ export async function readDiff(cwd, baseRef, headRef) {
         "--end-of-options",
         `${baseRef}...${headRef}`,
     ]);
-    return parseUnifiedDiff(stdout);
+    return classifyDiffFiles(parseUnifiedDiff(stdout));
 }
 export async function readHunkIndex(cwd, baseRef, headRef) {
     const { source } = await resolveSource(cwd, baseRef, headRef);
@@ -31,6 +32,12 @@ export async function readHunkIndex(cwd, baseRef, headRef) {
     const hunks = [];
     const skipped = [];
     for (const file of files) {
+        if (file.image) {
+            for (const hunk of file.hunks) {
+                hunks.push(toHunkRef(hunk));
+            }
+            continue;
+        }
         if (file.binary) {
             skipped.push({ path: file.path, reason: "binary" });
             continue;
@@ -196,6 +203,7 @@ class FileBuilder {
             path,
             status,
             binary: this.binary,
+            image: false,
             headerPatch: this.headerPatch,
             patch: this.patch,
             hunks,
@@ -282,14 +290,48 @@ function stripDiffPath(raw) {
 export function flattenHunks(files) {
     const hunks = [];
     for (const file of files) {
-        if (file.binary) {
+        if (file.binary && !file.image) {
             continue;
         }
         hunks.push(...file.hunks);
     }
     return hunks;
 }
+export function classifyDiffFiles(files) {
+    return files.map(classifyDiffFile);
+}
+function classifyDiffFile(file) {
+    if (!isImagePath(file.path) && (file.oldPath === undefined || !isImagePath(file.oldPath))) {
+        return file;
+    }
+    if (file.binary || isLfsPointerText(file.patch)) {
+        return asImageFile(file);
+    }
+    return file;
+}
+function asImageFile(file) {
+    return { ...file, image: true, hunks: [imageLiveHunk(file.path, file.oldPath)] };
+}
+export function imageLiveHunk(path, oldPath) {
+    const hunk = {
+        path,
+        oldStart: 0,
+        oldLines: 0,
+        newStart: 0,
+        newLines: 0,
+        header: "image",
+        lines: [],
+        patch: "",
+    };
+    if (oldPath !== undefined) {
+        hunk.oldPath = oldPath;
+    }
+    return hunk;
+}
 export function fileLanguage(path) {
+    if (isImagePath(path)) {
+        return "image";
+    }
     const ext = path.split(".").pop()?.toLowerCase();
     switch (ext) {
         case "ts":

package/dist/git/exec.js

@@ -27,7 +27,21 @@ export async function git(cwd, args, opts) {
         if (opts?.allowFail) {
             return failure.stdout;
         }
-        throw new GitError(`git ${args.join(" ")} failed: ${failure.stderr.trim() || failure.message}`, args, failure.stderr, failure.code);
+        throw gitFailure(args, failure);
+    }
+}
+export async function gitBuffer(cwd, args, opts) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-c", "core.quotepath=false", ...args], {
+            cwd,
+            encoding: "buffer",
+            maxBuffer: 64 * 1024 * 1024,
+            ...(opts?.input !== undefined ? { input: Buffer.from(opts.input) } : {}),
+        });
+        return stdout;
+    }
+    catch (error) {
+        throw gitFailure(args, asExecFailure(error));
     }
 }
 export async function gitOk(cwd, args) {
@@ -44,10 +58,22 @@ function asExecFailure(error) {
         const record = error;
         return {
             message: typeof record.message === "string" ? record.message : "git failed",
-            stdout: typeof record.stdout === "string" ? record.stdout : "",
-            stderr: typeof record.stderr === "string" ? record.stderr : "",
+            stdout: bufferText(record.stdout),
+            stderr: bufferText(record.stderr),
             code: typeof record.code === "number" ? record.code : null,
         };
     }
     return { message: "git failed", stdout: "", stderr: "", code: null };
 }
+function bufferText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Buffer) {
+        return value.toString("utf8");
+    }
+    return "";
+}
+function gitFailure(args, failure) {
+    return new GitError(`git ${args.join(" ")} failed: ${failure.stderr.trim() || failure.message}`, args, failure.stderr, failure.code);
+}

package/dist/git/lfs.js

@@ -0,0 +1,39 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { LFS_POINTER_VERSION } from "../schema/image.js";
+import { git } from "./exec.js";
+const POINTER_MAX = 1024;
+export function parseLfsPointer(bytes) {
+    if (bytes.length === 0 || bytes.length > POINTER_MAX) {
+        return undefined;
+    }
+    if (bytes.includes(0)) {
+        return undefined;
+    }
+    const text = new TextDecoder("utf8").decode(bytes);
+    if (!text.startsWith(`${LFS_POINTER_VERSION}\n`)) {
+        return undefined;
+    }
+    const oid = /^oid sha256:([a-f0-9]{64})$/m.exec(text)?.[1];
+    const sizeRaw = /^size (\d+)$/m.exec(text)?.[1];
+    if (oid === undefined || sizeRaw === undefined) {
+        return undefined;
+    }
+    return { oid, size: Number(sizeRaw) };
+}
+export function lfsObjectPath(gitCommonDir, oid) {
+    return join(gitCommonDir, "lfs", "objects", oid.slice(0, 2), oid.slice(2, 4), oid);
+}
+export async function gitCommonDir(cwd) {
+    const raw = (await git(cwd, ["rev-parse", "--git-common-dir"])).trim();
+    return isAbsolute(raw) ? raw : resolve(cwd, raw);
+}
+export async function readLfsObject(cwd, pointer) {
+    const common = await gitCommonDir(cwd);
+    const stored = lfsObjectPath(common, pointer.oid);
+    if (!existsSync(stored)) {
+        return undefined;
+    }
+    return readFile(stored);
+}

package/dist/schema/cli-pin.js

@@ -0,0 +1,18 @@
+export function cliPin(version) {
+    return `npx comprehende@${version}`;
+}
+const PIN = /npx comprehende@([^\s`]+)/g;
+export function listedCliPins(markdown) {
+    return [...markdown.matchAll(PIN)].map((match) => match[1] ?? "");
+}
+export function applyCliPin(markdown, version) {
+    return markdown.replace(PIN, cliPin(version));
+}
+export function cliPinErrors(markdown, version) {
+    const expected = cliPin(version);
+    const pins = listedCliPins(markdown);
+    if (pins.length === 0) {
+        return [`SKILL.md must pin ${expected}`];
+    }
+    return [...new Set(pins.filter((pin) => pin !== version))].map((pin) => `SKILL.md pins npx comprehende@${pin}, package.json version is ${version}`);
+}

package/dist/schema/image-diff.js

@@ -0,0 +1,51 @@
+const UNCHANGED_KEEP = 0.35;
+const THRESHOLD = 8;
+/** Paint a same-size RGBA pair. Unchanged pixels go gray; changed pixels go magenta. */
+export function diffRgba(oldPixels, newPixels, width, height, threshold = THRESHOLD) {
+    const total = width * height;
+    const pixels = new Uint8ClampedArray(total * 4);
+    let changed = 0;
+    for (let i = 0; i < total; i += 1) {
+        const o = i * 4;
+        const oldA = oldPixels[o + 3] ?? 0;
+        const newA = newPixels[o + 3] ?? 0;
+        const empty = oldA === 0 && newA === 0;
+        const dr = Math.abs((oldPixels[o] ?? 0) - (newPixels[o] ?? 0));
+        const dg = Math.abs((oldPixels[o + 1] ?? 0) - (newPixels[o + 1] ?? 0));
+        const db = Math.abs((oldPixels[o + 2] ?? 0) - (newPixels[o + 2] ?? 0));
+        const da = Math.abs(oldA - newA);
+        const delta = Math.max(dr, dg, db, da);
+        if (empty || delta <= threshold) {
+            const gray = grayOf(newPixels[o] ?? 0, newPixels[o + 1] ?? 0, newPixels[o + 2] ?? 0);
+            const faded = Math.round(gray * UNCHANGED_KEEP);
+            pixels[o] = faded;
+            pixels[o + 1] = faded;
+            pixels[o + 2] = faded;
+            pixels[o + 3] = 255;
+            continue;
+        }
+        changed += 1;
+        if (oldA === 0 && newA > 0) {
+            pixels[o] = 26;
+            pixels[o + 1] = 127;
+            pixels[o + 2] = 55;
+            pixels[o + 3] = 255;
+            continue;
+        }
+        if (newA === 0 && oldA > 0) {
+            pixels[o] = 207;
+            pixels[o + 1] = 34;
+            pixels[o + 2] = 46;
+            pixels[o + 3] = 255;
+            continue;
+        }
+        pixels[o] = 200;
+        pixels[o + 1] = 40;
+        pixels[o + 2] = 160;
+        pixels[o + 3] = 255;
+    }
+    return { pixels, changed, total };
+}
+function grayOf(r, g, b) {
+    return Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b);
+}

package/dist/schema/image.js

@@ -0,0 +1,35 @@
+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";
+const MEDIA = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    avif: "image/avif",
+    ico: "image/x-icon",
+};
+export function imageExtension(path) {
+    const base = path.split("/").pop() ?? path;
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0) {
+        return undefined;
+    }
+    const ext = base.slice(dot + 1).toLowerCase();
+    return IMAGE_EXT.has(ext) ? ext : undefined;
+}
+export function isImagePath(path) {
+    return imageExtension(path) !== undefined;
+}
+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/parse.js

@@ -2,7 +2,7 @@ import { isReviewSize, REVIEW_SIZES } from "./types.js";
 const DOCUMENT_KEYS = new Set(["version", "source", "size", "walkthrough", "tickets", "groups"]);
 const SOURCE_KEYS = new Set(["baseRef", "headRef", "range"]);
 const TICKET_KEYS = new Set(["id", "url", "title"]);
-const GROUP_KEYS = new Set(["id", "title", "summary", "lookFor", "dependsOn", "suggestedOrder", "hunkRefs"]);
+const GROUP_KEYS = new Set(["id", "title", "summary", "lookFor", "dependsOn", "part", "suggestedOrder", "hunkRefs"]);
 const HUNK_KEYS = new Set(["path", "oldPath", "oldStart", "oldLines", "newStart", "newLines"]);
 export function parseReviewDocument(input) {
     const errors = [];
@@ -129,6 +129,7 @@ function parseGroups(value, 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 part = item.part === undefined ? undefined : requiredString(item.part, `groups[${i}].part`, errors);
         if (id === undefined || title === undefined || summary === undefined || suggestedOrder === undefined) {
             return;
         }
@@ -143,6 +144,9 @@ function parseGroups(value, errors) {
         if (dependsOn !== undefined) {
             group.dependsOn = dependsOn;
         }
+        if (part !== undefined) {
+            group.part = part;
+        }
         groups.push(group);
     });
     const known = new Set(groups.map((group) => group.id));

package/dist/schema/skill-sync.js

@@ -0,0 +1,90 @@
+import { execFileSync } from "node:child_process";
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { cliPinErrors } from "./cli-pin.js";
+import { skillPaths } from "./skill-paths.js";
+import { findPackageRoot, readPackageVersion } from "../package-root.js";
+export function skillSyncErrors(input) {
+    const errors = [];
+    if (input.publishedSchema !== input.canonicalSchema) {
+        errors.push("skills/comprehende/references/review.schema.json drifted. Run: pnpm sync:skill");
+    }
+    if (input.installedSchema !== input.canonicalSchema) {
+        errors.push(".agents/skills/comprehende/references/review.schema.json drifted. Run: pnpm sync:skill");
+    }
+    errors.push(...cliPinErrors(input.publishedSkillMd, input.version));
+    const publishedKeys = [...input.publishedFiles.keys()].sort();
+    const installedKeys = [...input.installedFiles.keys()].sort();
+    if (publishedKeys.join("\n") !== installedKeys.join("\n")) {
+        errors.push(".agents/skills/comprehende is not a copy of skills/comprehende. Run: pnpm sync:skill");
+        return errors;
+    }
+    for (const rel of publishedKeys) {
+        if (input.publishedFiles.get(rel) !== input.installedFiles.get(rel)) {
+            errors.push(`${rel} differs between skills/ and .agents/. Run: pnpm sync:skill`);
+        }
+    }
+    return errors;
+}
+export async function loadWorkingTreeSkillSync(root = findPackageRoot()) {
+    const paths = skillPaths(root);
+    const publishedFiles = await readTree(paths.publishedSkill);
+    const installedFiles = await readTree(paths.installedSkill);
+    return {
+        version: readPackageVersion(),
+        canonicalSchema: await readFile(paths.canonicalSchema, "utf8"),
+        publishedSchema: await readFile(paths.publishedSchema, "utf8"),
+        installedSchema: await readFile(paths.installedSchema, "utf8"),
+        publishedSkillMd: publishedFiles.get("SKILL.md") ?? "",
+        publishedFiles,
+        installedFiles,
+    };
+}
+export function loadStagedSkillSync(root = findPackageRoot()) {
+    const publishedFiles = gitStagedTree(root, "skills/comprehende");
+    const installedFiles = gitStagedTree(root, ".agents/skills/comprehende");
+    const pkg = JSON.parse(gitShowStaged(root, "package.json"));
+    return {
+        version: pkg.version,
+        canonicalSchema: gitShowStaged(root, "src/schema/review.schema.json"),
+        publishedSchema: gitShowStaged(root, "skills/comprehende/references/review.schema.json"),
+        installedSchema: gitShowStaged(root, ".agents/skills/comprehende/references/review.schema.json"),
+        publishedSkillMd: publishedFiles.get("SKILL.md") ?? "",
+        publishedFiles,
+        installedFiles,
+    };
+}
+async function readTree(dir) {
+    const out = new Map();
+    const walk = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            out.set(relative(dir, full), await readFile(full, "utf8"));
+        }
+    };
+    await walk(dir);
+    return out;
+}
+function gitStagedTree(root, prefix) {
+    const listing = execFileSync("git", ["ls-files", "-z", "--", prefix], {
+        cwd: root,
+        encoding: "utf8",
+    });
+    const out = new Map();
+    for (const full of listing.split("\0").filter(Boolean)) {
+        out.set(relative(prefix, full), gitShowStaged(root, full));
+    }
+    return out;
+}
+function gitShowStaged(root, path) {
+    try {
+        return execFileSync("git", ["show", `:${path}`], { cwd: root, encoding: "utf8" });
+    }
+    catch {
+        throw new Error(`staged file missing: ${path}`);
+    }
+}