comprehende 0.5.5 → 0.6.1

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

package/dist/api/agent-md.js

@@ -23,7 +23,7 @@ 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,
@@ -79,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/api/shiki-langs.js

@@ -0,0 +1,138 @@
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+export const SHIKI_LANGS_FILE = "shiki-langs.json";
+const LANG_MODULE = /[/\\]@shikijs[/\\]langs[/\\]dist[/\\]([^/\\]+)\.m?js(?:\?|$)/;
+const SKIP_LANGS = new Set(["text", "ansi"]);
+export function shikiLangId(id) {
+    return id.match(LANG_MODULE)?.[1];
+}
+export function parseShikiLangsManifest(input) {
+    if (!isRecord(input) || input.version !== 1) {
+        return undefined;
+    }
+    const chunks = stringList(input.chunks);
+    const files = stringListMap(input.files);
+    const lookup = stringMap(input.lookup);
+    if (chunks === undefined || files === undefined || lookup === undefined) {
+        return undefined;
+    }
+    return { version: 1, chunks, files, lookup };
+}
+export function highlightLangFromPath(path, lookup) {
+    const fileName = path.split(/[/\\]/).pop() ?? path;
+    if (lookup[fileName] !== undefined) {
+        return lookup[fileName];
+    }
+    const compound = fileName.match(/\.([^/\\]+\.[^/\\]+)$/)?.[1];
+    if (compound !== undefined && lookup[compound] !== undefined) {
+        return lookup[compound];
+    }
+    const simple = fileName.match(/\.([^.]+)$/)?.[1] ?? "";
+    return lookup[simple];
+}
+export function highlightLangsForPaths(paths, lookup) {
+    const langs = new Set();
+    for (const path of paths) {
+        const lang = highlightLangFromPath(path, lookup);
+        if (lang !== undefined && !SKIP_LANGS.has(lang)) {
+            langs.add(lang);
+        }
+    }
+    return [...langs];
+}
+export function highlightPathsFromFiles(files) {
+    const paths = [];
+    for (const file of files) {
+        paths.push(file.path);
+        if (file.oldPath !== undefined) {
+            paths.push(file.oldPath);
+        }
+    }
+    return paths;
+}
+export function chunksToKeep(manifest, langs) {
+    const keep = new Set();
+    for (const lang of langs) {
+        const files = manifest.files[lang];
+        if (files === undefined) {
+            return undefined;
+        }
+        for (const file of files) {
+            keep.add(file);
+        }
+    }
+    return [...keep];
+}
+export async function pruneUnusedHighlighterChunks(outDir, paths) {
+    const manifest = await loadManifest(join(outDir, SHIKI_LANGS_FILE));
+    if (manifest === undefined) {
+        return [];
+    }
+    const langs = highlightLangsForPaths(paths, manifest.lookup);
+    const keep = chunksToKeep(manifest, langs);
+    if (keep === undefined) {
+        return [];
+    }
+    const keepSet = new Set(keep);
+    const removed = [];
+    for (const file of manifest.chunks) {
+        if (keepSet.has(file)) {
+            continue;
+        }
+        await rm(join(outDir, file), { force: true });
+        await rm(join(outDir, `${file}.map`), { force: true });
+        removed.push(file);
+    }
+    return removed;
+}
+async function loadManifest(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return parseShikiLangsManifest(JSON.parse(text));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringList(value) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        return undefined;
+    }
+    return value;
+}
+function stringMap(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== "string") {
+            return undefined;
+        }
+        out[key] = item;
+    }
+    return out;
+}
+function stringListMap(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        const list = stringList(item);
+        if (list === undefined) {
+            return undefined;
+        }
+        out[key] = list;
+    }
+    return out;
+}

package/dist/api/snapshot.js

@@ -4,6 +4,7 @@ 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";
+import { highlightPathsFromFiles, pruneUnusedHighlighterChunks } from "./shiki-langs.js";
 export async function exportStaticSite(opts) {
     const outDir = resolve(opts.outDir);
     const uiRoot = opts.uiRoot ?? join(findPackageRoot(), "dist/ui");
@@ -41,5 +42,6 @@ export async function exportStaticSite(opts) {
         }
         apiFiles.push(rel);
     }
+    await pruneUnusedHighlighterChunks(outDir, highlightPathsFromFiles(ctx.files));
     return { outDir, apiFiles };
 }

package/dist/cli/args.js

@@ -8,13 +8,14 @@ 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)
 
   export    --data <review.json> --out <dir>
-            Write a static site (same UI + frozen git payloads). No server after that.
+            Write a static site (same UI + frozen git payloads). Highlighters only
+            for languages in the review. No server after that.
 
 Options:
   --base <ref>     Base ref (default: origin/HEAD or main/master)

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/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", "title", "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 = [];
@@ -17,8 +43,8 @@ export function parseReviewDocument(input) {
     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 || title === undefined || summary === undefined) {
         return { ok: false, errors };
@@ -34,8 +60,8 @@ export function parseReviewDocument(input) {
     if (why !== undefined) {
         document.why = why;
     }
-    if (tickets !== undefined) {
-        document.tickets = tickets;
+    if (sources !== undefined) {
+        document.sources = sources;
     }
     return { ok: true, document };
 }
@@ -77,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`);
@@ -96,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 [];
@@ -140,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;
@@ -158,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;
 }