comprehende 0.5.4 → 0.6.0

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.4` (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.6.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
 
 ## Release
 

package/dist/api/agent-md.js

@@ -23,8 +23,9 @@ function overviewAgentMd(review) {
         "Answer questions about this git change.",
         overviewSteps(review),
         pinBlock(review, { commits: true }),
-        ticketsBlock(review),
+        sourcesBlock(review),
         coverageBlock(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]),
         reviewConcernsBlock(review),
@@ -78,17 +79,17 @@ function pinBlock(review, options) {
         commits,
     ]);
 }
-function ticketsBlock(review) {
-    const tickets = review.document.tickets ?? [];
-    if (tickets.length === 0) {
+function sourcesBlock(review) {
+    const sources = review.document.sources ?? [];
+    if (sources.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}`;
+    const lines = sources.map((source) => {
+        const gist = source.gist !== undefined ? ` ${source.gist}` : "";
+        const url = source.url !== undefined ? `\n  ${source.url}` : "";
+        return `- ${source.kind} ${source.label}${gist}${url}`;
     });
-    return ["Tickets:", ...lines].join("\n");
+    return ["Sources:", ...lines].join("\n");
 }
 function coverageBlock(review) {
     const lines = [];

package/dist/api/live.js

@@ -6,8 +6,10 @@ import { GitError } from "../git/exec.js";
 import { listCommits } from "../git/log.js";
 import { pinRange, readRepoIdentity } from "../git/repo.js";
 import { showFile } from "../git/show.js";
-import { coverReview } from "../review/coverage.js";
+import { coverReview, coverageErrors } from "../review/coverage.js";
+import { commentPinErrors, staleCommentPins } from "../review/pins.js";
 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) {
@@ -18,6 +20,7 @@ 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 pins = await staleCommentPins(cwd, document, range);
     const commits = await listCommits(cwd, range.baseSha, range.headSha);
     const repo = await readRepoIdentity(cwd);
     return {
@@ -33,12 +36,13 @@ export async function openReview(cwd, dataPath, pin) {
         },
         files,
         coverage,
+        staleCommentPins: pins,
         mergeBaseSha: range.mergeBaseSha,
         commits,
     };
 }
 export function reviewPayload(ctx) {
-    const { document, repo, resolved, files, coverage, commits } = ctx;
+    const { document, repo, resolved, files, coverage, staleCommentPins, commits } = ctx;
     const lockfiles = lockfileFiles(files);
     return {
         document,
@@ -49,6 +53,7 @@ export function reviewPayload(ctx) {
             assignedHunks: coverage.assignedHunks,
             unassignedCount: coverage.unassigned.length,
             staleCount: coverage.stale.length,
+            staleSourceCount: staleCommentPins.length,
         },
         groups: coverage.groups
             .slice()
@@ -61,6 +66,7 @@ export function reviewPayload(ctx) {
             lookFor: group.group.lookFor ?? [],
             dependsOn: group.group.dependsOn ?? [],
             part: group.group.part,
+            sources: group.group.sources ?? [],
             suggestedOrder: group.group.suggestedOrder,
             hunkCount: group.hunks.length,
             staleCount: group.stale.length,
@@ -75,6 +81,7 @@ export function reviewPayload(ctx) {
             files: lockfiles.map((file) => file.path),
         },
         stale: coverage.stale,
+        staleSources: staleCommentPins,
         files: files.map((file) => {
             const entry = {
                 path: file.path,
@@ -92,6 +99,13 @@ export function reviewPayload(ctx) {
         commits,
     };
 }
+export function reviewProblems(ctx) {
+    return [
+        ...coverageErrors(ctx.coverage),
+        ...sourceCitationErrors(ctx.document),
+        ...commentPinErrors(ctx.staleCommentPins),
+    ];
+}
 export function hunksPayload(ctx, groupId) {
     if (groupId === "") {
         throw new ApiError(400, "missing group");

package/dist/cli/args.js

@@ -8,7 +8,7 @@ Commands:
             List hunk refs from live git (no patch text)
 
   validate  --data <review.json>
-            Check schema, ref resolution, and hunk coverage
+            Check schema, ref resolution, hunk coverage, and source citations
 
   serve     --data <review.json> [--port <n>] [--open]
             Serve the local UI on 127.0.0.1 (pins commit SHAs at start)

package/dist/cli/commands.js

@@ -3,7 +3,9 @@ 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 { 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) {
     const baseRef = base ?? (await defaultBaseRef(cwd));
     const headRef = head ?? "HEAD";
@@ -36,9 +38,10 @@ export function resolveOutPath(out, cwd) {
 }
 export async function cmdValidate(cwd, dataPath) {
     const document = await loadDocument(dataPath);
-    await resolveSource(cwd, document.source.baseRef, document.source.headRef);
+    const resolved = await resolveSource(cwd, document.source.baseRef, document.source.headRef);
     const { coverage } = await coverReview(cwd, document);
-    const errors = coverageErrors(coverage);
+    const pins = await staleCommentPins(cwd, document, resolved);
+    const errors = [...coverageErrors(coverage), ...sourceCitationErrors(document), ...commentPinErrors(pins)];
     if (errors.length > 0) {
         throw new Error(errors.join("\n\n"));
     }

package/dist/cli/main.js

@@ -6,8 +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, pinReviewSource } from "../api/live.js";
-import { coverageErrors } from "../review/coverage.js";
+import { openReview, pinReviewSource, reviewProblems } from "../api/live.js";
 import { assertWorkTree } from "../git/repo.js";
 import { readPackageVersion } from "../package-root.js";
 import { startServer } from "../server/http.js";
@@ -44,7 +43,7 @@ export async function run(argv) {
                 const dataPath = resolveDataPath(request.data, request.cwd);
                 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");
+                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);
                 console.error(`serving ${dataPath}  cwd=${request.cwd}  localhost only`);
@@ -58,7 +57,7 @@ export async function run(argv) {
                 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");
+                warnReview(ctx, "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`);
@@ -71,8 +70,8 @@ export async function run(argv) {
         return 1;
     }
 }
-function warnCoverage(coverage, note) {
-    const problems = coverageErrors(coverage);
+function warnReview(ctx, note) {
+    const problems = reviewProblems(ctx);
     if (problems.length > 0) {
         console.error(`coverage issues (${note}):\n${problems.join("\n\n")}`);
     }

package/dist/git/exec.js

@@ -1,6 +1,26 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+const GIT_DIR_VARS = new Set([
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_COMMON_DIR",
+    "GIT_PREFIX",
+]);
+/** Drop inherited git dir vars so `cwd` is the repository, including linked worktrees. */
+export function gitEnv(base = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || GIT_DIR_VARS.has(key.toUpperCase())) {
+            continue;
+        }
+        env[key] = value;
+    }
+    return env;
+}
 export class GitError extends Error {
     args;
     stderr;
@@ -17,6 +37,7 @@ export async function git(cwd, args, opts) {
     try {
         const { stdout } = await execFileAsync("git", ["-c", "core.quotepath=false", ...args], {
             cwd,
+            env: gitEnv(),
             encoding: "utf8",
             maxBuffer: 64 * 1024 * 1024,
         });
@@ -34,6 +55,7 @@ export async function gitBuffer(cwd, args, opts) {
     try {
         const { stdout } = await execFileAsync("git", ["-c", "core.quotepath=false", ...args], {
             cwd,
+            env: gitEnv(),
             encoding: "buffer",
             maxBuffer: 64 * 1024 * 1024,
             ...(opts?.input !== undefined ? { input: Buffer.from(opts.input) } : {}),

package/dist/git/lfs.js

@@ -1,8 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { join } from "node:path";
 import { LFS_POINTER_VERSION } from "../schema/image.js";
-import { git } from "./exec.js";
+import { gitCommonDir } from "./repo.js";
 const POINTER_MAX = 1024;
 export function parseLfsPointer(bytes) {
     if (bytes.length === 0 || bytes.length > POINTER_MAX) {
@@ -25,10 +25,6 @@ export function parseLfsPointer(bytes) {
 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);

package/dist/git/repo.js

@@ -1,4 +1,4 @@
-import { basename } from "node:path";
+import { basename, dirname, isAbsolute, resolve } 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 });
@@ -30,12 +30,18 @@ export function nameFromRemoteUrl(url) {
     const last = pathPart.split("/").filter(Boolean).at(-1);
     return last === undefined || last === "" ? null : last;
 }
+export async function gitCommonDir(cwd) {
+    const raw = (await git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).trim();
+    return isAbsolute(raw) ? raw : resolve(cwd, raw);
+}
 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 };
+    if (fromOrigin !== null) {
+        return { name: fromOrigin, origin };
+    }
+    return { name: basename(dirname(await gitCommonDir(cwd))), origin };
 }
 /** Drop userinfo from an http(s) remote so a copied prompt never carries a token. */
 export function stripRemoteCredentials(url) {

package/dist/review/pins.js

@@ -0,0 +1,30 @@
+import { fileExistsAt, showFile } from "../git/show.js";
+import { isLinePinned, textLineCount } from "../schema/source.js";
+export async function staleCommentPins(cwd, document, range) {
+    const stale = [];
+    for (const source of document.sources ?? []) {
+        if (!isLinePinned(source)) {
+            continue;
+        }
+        if (!(await commentPinMatches(cwd, source, range))) {
+            stale.push({ id: source.id, path: source.path, side: source.side, line: source.line });
+        }
+    }
+    return stale;
+}
+export function commentPinErrors(pins) {
+    if (pins.length === 0) {
+        return [];
+    }
+    const lines = pins.map((pin) => `  ${pin.id} ${pin.path} ${pin.side}:${pin.line}`);
+    return [`stale: ${pins.length} comment pin(s) do not match live git:\n${lines.join("\n")}`];
+}
+async function commentPinMatches(cwd, source, range) {
+    const sha = source.side === "old" ? range.baseSha : range.headSha;
+    if (!(await fileExistsAt(cwd, sha, source.path))) {
+        return false;
+    }
+    const content = await showFile(cwd, sha, source.path);
+    const count = textLineCount(content);
+    return source.line >= 1 && source.line <= count;
+}

package/dist/schema/parse.js

@@ -1,8 +1,34 @@
-import { isReviewSize, REVIEW_SIZES } from "./types.js";
-const DOCUMENT_KEYS = new Set(["version", "source", "size", "summary", "why", "tickets", "groups"]);
+import { isReviewSize, isSourceKind, isSourceSide, REVIEW_SIZES, SOURCE_KINDS, } from "./types.js";
+const DOCUMENT_KEYS = new Set(["version", "source", "size", "title", "summary", "why", "tickets", "sources", "groups"]);
 const SOURCE_KEYS = new Set(["baseRef", "headRef", "range"]);
 const TICKET_KEYS = new Set(["id", "url", "title", "part"]);
-const GROUP_KEYS = new Set(["id", "title", "why", "summary", "lookFor", "dependsOn", "part", "suggestedOrder", "hunkRefs"]);
+const REVIEW_SOURCE_KEYS = new Set([
+    "id",
+    "kind",
+    "label",
+    "url",
+    "title",
+    "gist",
+    "part",
+    "author",
+    "body",
+    "path",
+    "side",
+    "line",
+]);
+const COMMENT_ONLY_KEYS = ["author", "body", "path", "side", "line"];
+const GROUP_KEYS = new Set([
+    "id",
+    "title",
+    "why",
+    "summary",
+    "lookFor",
+    "dependsOn",
+    "part",
+    "sources",
+    "suggestedOrder",
+    "hunkRefs",
+]);
 const HUNK_KEYS = new Set(["path", "oldPath", "oldStart", "oldLines", "newStart", "newLines"]);
 export function parseReviewDocument(input) {
     const errors = [];
@@ -15,25 +41,27 @@ export function parseReviewDocument(input) {
     }
     const source = parseSource(input.source, errors);
     const size = parseSize(input.size, errors);
+    const title = requiredString(input.title, "title", errors);
     const summary = requiredString(input.summary, "summary", errors);
-    const tickets = parseTickets(input.tickets, errors);
-    const groups = parseGroups(input.groups, errors);
+    const sources = parseDocumentSources(input.sources, input.tickets, errors);
+    const groups = parseGroups(input.groups, sources, errors);
     const why = input.why === undefined ? undefined : requiredString(input.why, "why", errors);
-    if (errors.length > 0 || source === undefined || size === undefined || summary === undefined) {
+    if (errors.length > 0 || source === undefined || size === undefined || title === undefined || summary === undefined) {
         return { ok: false, errors };
     }
     const document = {
         version: 1,
         source,
         size,
+        title,
         summary,
         groups,
     };
     if (why !== undefined) {
         document.why = why;
     }
-    if (tickets !== undefined) {
-        document.tickets = tickets;
+    if (sources !== undefined) {
+        document.sources = sources;
     }
     return { ok: true, document };
 }
@@ -75,15 +103,154 @@ function parseSource(value, errors) {
     }
     return source;
 }
-function parseTickets(value, errors) {
-    if (value === undefined) {
+function parseDocumentSources(sourcesValue, ticketsValue, errors) {
+    if (sourcesValue !== undefined && ticketsValue !== undefined) {
+        errors.push("document has both sources and tickets; use sources");
+    }
+    if (sourcesValue !== undefined) {
+        return parseSources(sourcesValue, errors);
+    }
+    if (ticketsValue !== undefined) {
+        return parseLegacyTickets(ticketsValue, errors);
+    }
+    return undefined;
+}
+function parseSources(value, errors) {
+    if (!Array.isArray(value)) {
+        errors.push("sources must be an array");
+        return undefined;
+    }
+    const sources = [];
+    const ids = new Set();
+    value.forEach((item, i) => {
+        const source = parseSourceItem(item, `sources[${i}]`, errors);
+        if (source === undefined) {
+            return;
+        }
+        if (ids.has(source.id)) {
+            errors.push(`duplicate source id "${source.id}"`);
+        }
+        ids.add(source.id);
+        sources.push(source);
+    });
+    return sources;
+}
+function parseSourceItem(value, label, errors) {
+    if (!isRecord(value)) {
+        errors.push(`${label} must be an object`);
+        return undefined;
+    }
+    extraKeys(value, REVIEW_SOURCE_KEYS, label, errors);
+    const id = requiredString(value.id, `${label}.id`, errors);
+    const kind = parseKind(value.kind, `${label}.kind`, errors);
+    const sourceLabel = requiredString(value.label, `${label}.label`, errors);
+    if (id === undefined || kind === undefined || sourceLabel === undefined) {
         return undefined;
     }
+    const source = { id, kind, label: sourceLabel };
+    if (value.url !== undefined) {
+        const url = requiredString(value.url, `${label}.url`, errors);
+        if (url !== undefined) {
+            source.url = url;
+        }
+    }
+    if (value.title !== undefined) {
+        const title = requiredString(value.title, `${label}.title`, errors);
+        if (title !== undefined) {
+            source.title = title;
+        }
+    }
+    if (value.gist !== undefined) {
+        const gist = requiredString(value.gist, `${label}.gist`, errors);
+        if (gist !== undefined) {
+            source.gist = gist;
+        }
+    }
+    if (value.part !== undefined) {
+        const part = requiredString(value.part, `${label}.part`, errors);
+        if (part !== undefined) {
+            source.part = part;
+        }
+    }
+    if (kind === "transcript" && source.url !== undefined) {
+        errors.push(`${label}.url must be omitted for transcripts`);
+    }
+    assignCommentFields(value, source, kind, label, errors);
+    return source;
+}
+function assignCommentFields(value, source, kind, label, errors) {
+    const present = COMMENT_ONLY_KEYS.filter((key) => value[key] !== undefined);
+    if (kind !== "pr-comment") {
+        for (const key of present) {
+            errors.push(`${label}.${key} is only valid on pr-comment sources`);
+        }
+        return;
+    }
+    if (value.author !== undefined) {
+        const author = requiredString(value.author, `${label}.author`, errors);
+        if (author !== undefined) {
+            source.author = author;
+        }
+    }
+    if (value.body !== undefined) {
+        const body = requiredString(value.body, `${label}.body`, errors, { allowEmpty: true });
+        if (body !== undefined) {
+            source.body = body;
+        }
+    }
+    if (source.author === undefined) {
+        errors.push(`${label}.author is required on pr-comment sources`);
+    }
+    if (source.body === undefined) {
+        errors.push(`${label}.body is required on pr-comment sources`);
+    }
+    const pinCount = [value.path, value.side, value.line].filter((item) => item !== undefined).length;
+    if (pinCount === 0) {
+        return;
+    }
+    if (pinCount !== 3) {
+        errors.push(`${label} line pin needs path, side, and line together`);
+    }
+    if (value.path !== undefined) {
+        const path = requiredString(value.path, `${label}.path`, errors);
+        if (path !== undefined) {
+            source.path = path;
+        }
+    }
+    if (value.side !== undefined) {
+        if (!isSourceSide(value.side)) {
+            errors.push(`${label}.side must be old or new`);
+        }
+        else {
+            source.side = value.side;
+        }
+    }
+    if (value.line !== undefined) {
+        const line = requiredInt(value.line, `${label}.line`, errors);
+        if (line !== undefined) {
+            if (line < 1) {
+                errors.push(`${label}.line must be a positive integer`);
+            }
+            else {
+                source.line = line;
+            }
+        }
+    }
+}
+function parseKind(value, label, errors) {
+    if (isSourceKind(value)) {
+        return value;
+    }
+    errors.push(`${label} must be one of ${SOURCE_KINDS.join(", ")}`);
+    return undefined;
+}
+function parseLegacyTickets(value, errors) {
     if (!Array.isArray(value)) {
         errors.push("tickets must be an array");
         return undefined;
     }
-    const tickets = [];
+    const sources = [];
+    const ids = new Set();
     value.forEach((item, i) => {
         if (!isRecord(item)) {
             errors.push(`tickets[${i}] must be an object`);
@@ -94,30 +261,34 @@ function parseTickets(value, errors) {
         if (id === undefined) {
             return;
         }
-        const ticket = { id };
+        if (ids.has(id)) {
+            errors.push(`duplicate source id "${id}"`);
+        }
+        ids.add(id);
+        const source = { id, kind: "ticket", label: id };
         if (item.url !== undefined) {
             const url = requiredString(item.url, `tickets[${i}].url`, errors);
             if (url !== undefined) {
-                ticket.url = url;
+                source.url = url;
             }
         }
         if (item.title !== undefined) {
             const title = requiredString(item.title, `tickets[${i}].title`, errors);
             if (title !== undefined) {
-                ticket.title = title;
+                source.title = title;
             }
         }
         if (item.part !== undefined) {
             const part = requiredString(item.part, `tickets[${i}].part`, errors);
             if (part !== undefined) {
-                ticket.part = part;
+                source.part = part;
             }
         }
-        tickets.push(ticket);
+        sources.push(source);
     });
-    return tickets;
+    return sources;
 }
-function parseGroups(value, errors) {
+function parseGroups(value, sources, errors) {
     if (!Array.isArray(value)) {
         errors.push("groups must be an array");
         return [];
@@ -138,6 +309,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 groupSources = parseStringList(item.sources, `groups[${i}].sources`, errors);
         const part = item.part === undefined ? undefined : requiredString(item.part, `groups[${i}].part`, errors);
         if (id === undefined || title === undefined || why === undefined || summary === undefined || suggestedOrder === undefined) {
             return;
@@ -156,18 +328,32 @@ function parseGroups(value, errors) {
         if (part !== undefined) {
             group.part = part;
         }
+        if (groupSources !== undefined) {
+            group.sources = groupSources;
+        }
         groups.push(group);
     });
-    const known = new Set(groups.map((group) => group.id));
+    const knownGroups = new Set(groups.map((group) => group.id));
+    const knownSources = new Set((sources ?? []).map((source) => source.id));
     for (const group of groups) {
         for (const dep of group.dependsOn ?? []) {
             if (dep === group.id) {
                 errors.push(`groups id "${group.id}" depends on itself`);
             }
-            else if (!known.has(dep)) {
+            else if (!knownGroups.has(dep)) {
                 errors.push(`groups id "${group.id}" dependsOn unknown group "${dep}"`);
             }
         }
+        const seen = new Set();
+        for (const sourceId of group.sources ?? []) {
+            if (seen.has(sourceId)) {
+                errors.push(`groups id "${group.id}" lists source "${sourceId}" twice`);
+            }
+            seen.add(sourceId);
+            if (!knownSources.has(sourceId)) {
+                errors.push(`groups id "${group.id}" sources unknown id "${sourceId}"`);
+            }
+        }
     }
     return groups;
 }

package/dist/schema/skill-sync.js

@@ -4,6 +4,7 @@ import { dirname, join, relative } from "node:path";
 import { applyCliPin, cliPinErrors, listedCliPins } from "./cli-pin.js";
 import { skillPaths } from "./skill-paths.js";
 import { findPackageRoot } from "../package-root.js";
+import { gitEnv } from "../git/exec.js";
 export function skillSyncErrors(input) {
     const errors = [];
     if (input.nextSchema !== input.canonicalSchema) {
@@ -110,6 +111,7 @@ function gitStagedTree(root, prefix) {
     const listing = execFileSync("git", ["ls-files", "-z", "--", prefix], {
         cwd: root,
         encoding: "utf8",
+        env: gitEnv(),
     });
     const out = new Map();
     for (const full of listing.split("\0").filter(Boolean)) {
@@ -119,7 +121,7 @@ function gitStagedTree(root, prefix) {
 }
 function gitShowStaged(root, path) {
     try {
-        return execFileSync("git", ["show", `:${path}`], { cwd: root, encoding: "utf8" });
+        return execFileSync("git", ["show", `:${path}`], { cwd: root, encoding: "utf8", env: gitEnv() });
     }
     catch {
         throw new Error(`staged file missing: ${path}`);