@shortlink-org/portolan 0.2.2 → 0.2.3

package/README.md

@@ -201,8 +201,13 @@ for against what is on `PATH`. The Docker image contains all of them.
 
 While `portolan dev` is running, open **Settings → Delivery presets**. Portolan
 detects GitHub or GitLab from the repository's `origin`, previews the exact CI
-changes, and installs architecture checks and static catalog publishing in one
-step. Existing unmanaged workflow files are never overwritten.
+changes, and generates only the jobs selected there. Architecture checks and
+static catalog publishing are selected by default; pull-request architecture
+diffs and GitHub SARIF annotations are opt-in. Check, review, and publication
+live in separate GitHub workflows, while SARIF augments the review workflow, so
+comment and code-scanning permissions are granted only when those capabilities
+are enabled. Existing unmanaged workflow files are never overwritten, and
+disabling a capability removes only files managed by Portolan.
 
 ### Run without installing Node or language toolchains
 

package/cli/portolan.mjs

@@ -19,6 +19,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { fileURLToPath } from "node:url";
 
 import { InitError, commandWorks, init as runInit, isInteractive, promptAnswers, toolchainFor } from "./init.mjs";
+import { loadManifest, readManifest } from "../scripts/manifest.mjs";
 
 const installRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(readFileSync(resolve(installRoot, "package.json"), "utf8"));
@@ -54,7 +55,10 @@ export async function main(argv = process.argv.slice(2)) {
       return dev(workspace, parsed);
     case "diff":
       if (!parsed.positionals[0]) fail("diff requires a base branch, tag, or commit");
-      return runScript("scripts/diff.mjs", parsed.positionals, workspace);
+      return runScript("scripts/diff.mjs", diffArgs(parsed), workspace);
+    case "comment":
+      if (!parsed.positionals[0]) fail("comment requires a markdown file");
+      return runScript("scripts/forge-comment.mjs", [parsed.positionals[0]], workspace);
     case "doctor":
       return doctor(workspace);
     default:
@@ -68,7 +72,7 @@ function parse(argv) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") value.help = true;
     else if (arg === "--version" || arg === "-v") value.version = true;
-    else if (["--cwd", "--output", "--base", "--host", "--port"].includes(arg)) {
+    else if (["--cwd", "--output", "--base", "--host", "--port", "--format", "--site", "--head"].includes(arg)) {
       const next = argv[++index];
       if (!next) fail(`${arg} requires a value`);
       value[arg.slice(2)] = next;
@@ -80,6 +84,14 @@ function parse(argv) {
   return value;
 }
 
+function diffArgs(parsed) {
+  const args = [parsed.positionals[0]];
+  for (const name of ["format", "output", "site", "head"]) {
+    if (parsed[name]) args.push(`--${name}`, parsed[name]);
+  }
+  return args;
+}
+
 function help() {
   console.log(`Portolan ${VERSION}
 
@@ -92,6 +104,7 @@ Commands:
   check      fail when committed generated files are out of date
   build      build the static site
   diff BASE  describe architecture changes against BASE
+  comment FILE  post or update a pull-request comment from Markdown
   doctor     check the local runtime and project configuration
   version    print the CLI version
 
@@ -99,6 +112,9 @@ Options:
   --cwd DIR       project directory (default: current directory)
   --output DIR    build output (default: dist)
   --base PATH     deployed URL base (default: /)
+  --format TYPE   diff format: markdown, json, or sarif
+  --site URL      catalog URL linked from an architecture diff
+  --head BRANCH   head branch linked from an architecture diff
   --host HOST     dev server host (default: 127.0.0.1)
   --port PORT     dev server port
   --yes, -y       init without questions: take every detected default`);
@@ -118,10 +134,24 @@ async function init(workspace, options) {
 
 function doctor(workspace) {
   const manifestPath = resolve(workspace, "portolan.json");
-  const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null;
+  let manifest = null;
+  let manifestProblems = [];
+  if (existsSync(manifestPath)) {
+    try {
+      const loaded = loadManifest(manifestPath);
+      manifest = loaded.manifest;
+      manifestProblems = loaded.problems;
+    } catch (cause) {
+      manifestProblems = [cause instanceof Error ? cause.message : String(cause)];
+    }
+  }
   const checks = [
     ["Node.js >= 24", Number(process.versions.node.split(".")[0]) >= 24, process.version],
-    ["portolan.json", Boolean(manifest), "required"],
+    [
+      "portolan.json",
+      Boolean(manifest) && manifestProblems.length === 0,
+      manifestProblems.length > 0 ? manifestProblems.join("; ") : "required",
+    ],
     ["Git", commandWorks("git", ["--version"]), "used for deterministic source stamps"],
   ];
 
@@ -157,7 +187,7 @@ async function build(workspace, options) {
   runNode(packageBin("vite", "bin/vite.js"), ["build", stage, "--config", resolve(stage, "vite.config.ts"), "--outDir", output, "--emptyOutDir"], workspace, env);
 
   const { siteDocs } = await import(resolve(installRoot, "scripts/site-docs.mjs"));
-  const manifest = JSON.parse(readFileSync(resolve(workspace, "portolan.json"), "utf8"));
+  const manifest = readManifest(resolve(workspace, "portolan.json"));
   const written = siteDocs({ manifest, dist: output });
   copyFileSync(resolve(output, "index.html"), resolve(output, "404.html"));
   console.log(`site: ${relative(workspace, output) || "."}${written.length ? `; mounted ${written.join(", ")}` : ""}`);
@@ -178,7 +208,7 @@ async function dev(workspace, options) {
 export async function prepareSite(workspace) {
   const manifestPath = resolve(workspace, "portolan.json");
   if (!existsSync(manifestPath)) fail("portolan.json is missing; run portolan init first");
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const manifest = readManifest(manifestPath);
   const stage = resolve(workspace, ".portolan", "site");
   rmSync(stage, { recursive: true, force: true });
   mkdirSync(stage, { recursive: true });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shortlink-org/portolan",
   "description": "Generate a navigable architecture catalog from code and specifications.",
   "private": false,
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",
@@ -68,10 +68,10 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "3.0.45",
-    "@ai-sdk/react": "4.0.97",
+    "@ai-sdk/react": "4.0.98",
     "@asyncapi/react-component": "^3.1.8",
     "@clack/prompts": "^1.8.0",
-    "@floating-ui/react": "^0.27.0",
+    "@floating-ui/react": "^0.27.20",
     "@headlessui/react": "^2.2.10",
     "@scalar/api-reference-react": "^0.9.66",
     "@tailwindcss/vite": "^4.0.0",
@@ -80,7 +80,7 @@
     "@tanstack/react-virtual": "^3.14.10",
     "@vitejs/plugin-react": "^6.1.1",
     "@xyflow/react": "^12.11.5",
-    "ai": "7.0.94",
+    "ai": "7.0.95",
     "ajv": "^8.20.0",
     "elkjs": "^0.12.0",
     "html-to-image": "^1.11.13",

package/scripts/builtin-plugins.mjs

@@ -4,10 +4,11 @@
 // package happens to run them. Custom plugins may still be declared in the
 // manifest with `process` or `wasm`; those declarations always win.
 
-import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { readManifest } from "./manifest.mjs";
+
 export const INSTALL_ROOT = process.env.PORTOLAN_INSTALL_ROOT
   ? resolve(process.env.PORTOLAN_INSTALL_ROOT)
   : resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -16,7 +17,7 @@ let definitions;
 
 function shippedDefinitions() {
   if (definitions) return definitions;
-  const manifest = JSON.parse(readFileSync(resolve(INSTALL_ROOT, "portolan.json"), "utf8"));
+  const manifest = readManifest(resolve(INSTALL_ROOT, "portolan.json"));
   definitions = new Map((manifest.plugins ?? []).map((plugin) => [plugin.name, plugin]));
   return definitions;
 }

package/scripts/catalog-sources.mjs

@@ -14,6 +14,7 @@ import { validateCatalog } from "../src/catalog.ts";
 import { filterCatalogForProfile } from "../src/catalog-profile.ts";
 import { enrichCatalog } from "../src/enrich.ts";
 import { mergeCatalogs } from "../src/merge.ts";
+import { readManifest } from "./manifest.mjs";
 
 /**
  * `exclude` names source files to leave out, as the manifest would spell
@@ -22,7 +23,7 @@ import { mergeCatalogs } from "../src/merge.ts";
  * what it wrote last time would count as what it saw this time.
  */
 export async function loadCatalog(manifestPath = "portolan.json", { exclude = [], profile } = {}) {
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const manifest = readManifest(manifestPath);
   const excluded = new Set(exclude.map((path) => normalize(path)));
   const selected = profile
     ? (manifest.catalogs ?? []).find((candidate) => candidate.id === profile)

package/scripts/catalog-sources.test.mjs

@@ -29,7 +29,17 @@ describe("catalog sources", () => {
 
   it("still reports missing sources for a configured project", async () => {
     const { path, missing } = manifest({ sources: [], projects: [] });
-    writeFileSync(path, `${JSON.stringify({ sources: [missing], projects: [{ id: "billing" }], extract: [] }, null, 2)}\n`);
+    writeFileSync(path, `${JSON.stringify({
+      sources: [missing],
+      projects: [{
+        id: "billing",
+        name: "Billing",
+        root: "services/billing",
+        context: "shop",
+        service: "billing",
+      }],
+      extract: [],
+    }, null, 2)}\n`);
     await expect(loadCatalog(path)).rejects.toThrow(/no catalog matched/);
   });
 });

package/scripts/delivery-presets.mjs

@@ -22,6 +22,26 @@ const GENERATED = "# Generated by Portolan. Preview changes in Settings before u
 const GITLAB_START = "# >>> Portolan delivery preset >>>";
 const GITLAB_END = "# <<< Portolan delivery preset <<<";
 const PROVIDERS = new Set(["github", "gitlab"]);
+const FEATURE_IDS = ["check", "diff", "sarif", "pages"];
+const DEFAULT_FEATURES = ["check", "pages"];
+const FEATURE_DETAILS = {
+  check: {
+    label: "Architecture check",
+    description: "Fail when committed architecture files are stale.",
+  },
+  diff: {
+    label: "Pull-request architecture diff",
+    description: "Post a sticky architecture summary where review happens.",
+  },
+  sarif: {
+    label: "SARIF annotations",
+    description: "Annotate changed architecture in GitHub's checks and code-scanning views.",
+  },
+  pages: {
+    label: "Static catalog publishing",
+    description: "Build and publish the catalog after changes reach the default branch.",
+  },
+};
 
 function exists(path) {
   try { lstatSync(path); return true; } catch { return false; }
@@ -153,9 +173,58 @@ jobs:
 `;
 }
 
-function gitlabBlock() {
-  return `${GITLAB_START}
-"portolan:check":
+function githubDiff({ pages, sarif }) {
+  const site = pages
+    ? "\n          site: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
+    : "";
+  const sarifInput = sarif ? "\n          sarif-output: .portolan/diff.sarif" : "";
+  const sarifPermission = sarif ? "\n  security-events: write # annotations in the checks tab" : "";
+  const upload = sarif
+    ? `
+      - name: Annotate the checks tab
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: .portolan/diff.sarif
+          category: architecture-diff
+        # Fork pull requests have a read-only token; the Markdown summary still works.
+        continue-on-error: true
+`
+    : "";
+  return `${GENERATED}
+name: Portolan architecture diff
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write${sarifPermission}
+
+concurrency:
+  group: portolan-diff-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  describe:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: shortlink-org/portolan@${VERSION}
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        with:
+          command: diff
+          version: ${VERSION}
+          base-ref: origin/\${{ github.base_ref }}
+          head-ref: \${{ github.head_ref }}
+          comment: true${site}${sarifInput}
+${upload}`;
+}
+
+function gitlabCheck() {
+  return `"portolan:check":
   stage: .pre
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
@@ -167,8 +236,30 @@ function gitlabBlock() {
   rules:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+`;
+}
 
-"portolan:pages":
+function gitlabDiff({ pages }) {
+  const site = pages ? ' --site "$CI_PAGES_URL"' : "";
+  return `"portolan:review":
+  stage: .pre
+  image:
+    name: ghcr.io/shortlink-org/portolan:${VERSION}
+    entrypoint: [""]
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    - portolan diff "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"${site} --output .portolan/diff.md
+    - cat .portolan/diff.md
+    - portolan comment .portolan/diff.md
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+`;
+}
+
+function gitlabPages() {
+  return `"portolan:pages":
   stage: .post
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
@@ -182,11 +273,19 @@ function gitlabBlock() {
     publish: dist
   rules:
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-${GITLAB_END}
 `;
 }
 
-function mergeGitlab(existing) {
+function gitlabBlock(features) {
+  const jobs = [];
+  if (features.has("check")) jobs.push(gitlabCheck());
+  if (features.has("diff")) jobs.push(gitlabDiff({ pages: features.has("pages") }));
+  if (features.has("pages")) jobs.push(gitlabPages());
+  if (jobs.length === 0) return "";
+  return `${GITLAB_START}\n${jobs.join("\n")}${GITLAB_END}\n`;
+}
+
+function mergeGitlab(existing, features) {
   const start = existing.indexOf(GITLAB_START);
   const end = existing.indexOf(GITLAB_END);
   if ((start === -1) !== (end === -1) || (start !== -1 && end < start)) {
@@ -194,12 +293,17 @@ function mergeGitlab(existing) {
   }
   if (start !== -1) {
     const after = end + GITLAB_END.length;
-    return { content: `${existing.slice(0, start)}${gitlabBlock().trimEnd()}${existing.slice(after)}`.replace(/\n*$/, "\n") };
+    const replacement = gitlabBlock(features).trimEnd();
+    const content = `${existing.slice(0, start)}${replacement}${existing.slice(after)}`
+      .replace(/\n{3,}/g, "\n\n")
+      .replace(/^\n+|\n+$/g, "");
+    return { content: content ? `${content}\n` : "" };
   }
-  if (/^[ \t]*["']?portolan:(?:check|pages)["']?\s*:/m.test(existing)) {
+  if (/^[ \t]*["']?portolan:(?:check|review|pages)["']?\s*:/m.test(existing)) {
     return { conflict: "This pipeline already declares a Portolan job outside the managed region." };
   }
-  return { content: `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${gitlabBlock()}` };
+  const block = gitlabBlock(features);
+  return { content: block ? `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}` : existing };
 }
 
 function textDiff(path, before, after) {
@@ -251,6 +355,16 @@ function readTarget(workspace, path) {
 function githubFile(workspace, path, content) {
   const current = readTarget(workspace, path);
   const managed = current.safe && current.content.startsWith(GENERATED);
+  if (content === null) {
+    if (!current.exists || !managed) return null;
+    return {
+      path,
+      status: "removed",
+      diff: textDiff(path, current.content, ""),
+      current: current.content,
+      next: "",
+    };
+  }
   const status = !current.exists ? "added" : !current.safe || !managed ? "conflict" : current.content === content ? "unchanged" : "changed";
   return {
     path,
@@ -262,39 +376,102 @@ function githubFile(workspace, path, content) {
   };
 }
 
-function gitlabFile(workspace) {
+function gitlabFile(workspace, features) {
   const path = ".gitlab-ci.yml";
   const current = readTarget(workspace, path);
   if (!current.safe) return { path, status: "conflict", message: "The existing pipeline is not a safe UTF-8 file.", diff: "", current: "", next: "" };
-  const merged = mergeGitlab(current.content);
+  const merged = mergeGitlab(current.content, features);
   if (merged.conflict) return { path, status: "conflict", message: merged.conflict, diff: "", current: current.content, next: "" };
-  const status = !current.exists ? "added" : current.content === merged.content ? "unchanged" : "changed";
+  const status = current.content === merged.content ? "unchanged" : !current.exists ? "added" : "changed";
   return { path, status, diff: textDiff(path, current.content, merged.content), current: current.content, next: merged.content };
 }
 
-function revisionFor(provider, files) {
+function revisionFor(provider, features, files) {
   const hash = createHash("sha256").update(provider);
+  hash.update("\0"); hash.update([...features].sort().join(","));
   for (const file of files) {
     hash.update("\0"); hash.update(file.path); hash.update("\0"); hash.update(file.current); hash.update("\0"); hash.update(file.next);
   }
   return hash.digest("hex");
 }
 
-export function planDeliveryPreset(workspace, requestedProvider) {
+function deliveryRequest(request) {
+  return typeof request === "string" || request == null ? { provider: request ?? undefined } : request;
+}
+
+function installedFeatures(workspace, provider) {
+  const selected = new Set();
+  if (provider === "github") {
+    const check = readTarget(workspace, ".github/workflows/portolan-check.yml");
+    const review = readTarget(workspace, ".github/workflows/portolan-review.yml");
+    const pages = readTarget(workspace, ".github/workflows/portolan-pages.yml");
+    if (check.safe && check.content.startsWith(GENERATED)) selected.add("check");
+    if (review.safe && review.content.startsWith(GENERATED)) {
+      selected.add("diff");
+      if (review.content.includes("sarif-output:")) selected.add("sarif");
+    }
+    if (pages.safe && pages.content.startsWith(GENERATED)) selected.add("pages");
+    return selected;
+  }
+  const pipeline = readTarget(workspace, ".gitlab-ci.yml");
+  if (!pipeline.safe || !pipeline.content.includes(GITLAB_START)) return selected;
+  const managed = pipeline.content.slice(
+    pipeline.content.indexOf(GITLAB_START),
+    pipeline.content.indexOf(GITLAB_END) + GITLAB_END.length,
+  );
+  if (/^[ \t]*["']?portolan:check["']?\s*:/m.test(managed)) selected.add("check");
+  if (/^[ \t]*["']?portolan:review["']?\s*:/m.test(managed)) selected.add("diff");
+  if (/^[ \t]*["']?portolan:pages["']?\s*:/m.test(managed)) selected.add("pages");
+  return selected;
+}
+
+function selectedFeatures(workspace, request, provider) {
+  const installed = request.features == null ? installedFeatures(workspace, provider) : null;
+  const raw = request.features == null
+    ? installed.size > 0 ? [...installed] : DEFAULT_FEATURES
+    : Array.isArray(request.features)
+      ? request.features
+      : String(request.features).split(",").filter(Boolean);
+  const selected = new Set(raw);
+  for (const feature of selected) {
+    if (!FEATURE_IDS.includes(feature)) throw new Error(`Unknown delivery feature ${feature}.`);
+  }
+  if (selected.has("sarif")) selected.add("diff");
+  if (provider !== "github" && selected.has("sarif")) {
+    throw new Error("SARIF annotations are currently available only for GitHub.");
+  }
+  return selected;
+}
+
+function featureOptions(provider, selected) {
+  return FEATURE_IDS.map((id) => ({
+    id,
+    ...FEATURE_DETAILS[id],
+    selected: selected.has(id),
+    available: id !== "sarif" || provider === "github",
+    requires: id === "sarif" ? ["diff"] : [],
+  }));
+}
+
+export function planDeliveryPreset(workspace, requested = {}) {
+  const request = deliveryRequest(requested);
   const detected = detectDeliveryForge(workspace);
-  const provider = requestedProvider || detected.provider || "github";
+  const provider = request.provider || detected.provider || "github";
   if (!PROVIDERS.has(provider)) throw new Error("Delivery preset must be github or gitlab.");
+  const features = selectedFeatures(workspace, request, provider);
   const files = provider === "github"
     ? [
-        githubFile(workspace, ".github/workflows/portolan-check.yml", githubCheck(detected.defaultBranch)),
-        githubFile(workspace, ".github/workflows/portolan-pages.yml", githubPages(detected.defaultBranch)),
-      ]
-    : [gitlabFile(workspace)];
+        githubFile(workspace, ".github/workflows/portolan-check.yml", features.has("check") ? githubCheck(detected.defaultBranch) : null),
+        githubFile(workspace, ".github/workflows/portolan-review.yml", features.has("diff") ? githubDiff({ pages: features.has("pages"), sarif: features.has("sarif") }) : null),
+        githubFile(workspace, ".github/workflows/portolan-pages.yml", features.has("pages") ? githubPages(detected.defaultBranch) : null),
+      ].filter(Boolean)
+    : [gitlabFile(workspace, features)];
   const status = files.some((file) => file.status === "conflict")
     ? "conflict"
     : files.every((file) => file.status === "unchanged")
       ? "installed"
-      : files.some((file) => file.status === "changed") && (provider !== "gitlab" || files[0].current.includes(GITLAB_START))
+      : files.some((file) => ["removed", "unchanged"].includes(file.status))
+          || files.some((file) => file.status === "changed" && (provider !== "gitlab" || file.current.includes(GITLAB_START)))
         ? "update"
         : "available";
   return {
@@ -304,8 +481,8 @@ export function planDeliveryPreset(workspace, requestedProvider) {
     repository: detected.repository,
     defaultBranch: detected.defaultBranch,
     status,
-    revision: revisionFor(provider, files),
-    features: ["Validate generated architecture in reviews", "Publish the static catalog"],
+    revision: revisionFor(provider, features, files),
+    features: featureOptions(provider, features),
     files,
   };
 }
@@ -315,7 +492,8 @@ export function publicDeliveryPreset(plan) {
 }
 
 export function installDeliveryPreset(workspace, request) {
-  const plan = planDeliveryPreset(workspace, request.provider);
+  const selection = { provider: request.provider, features: request.features };
+  const plan = planDeliveryPreset(workspace, selection);
   if (!request.revision || request.revision !== plan.revision) {
     const error = new Error("Files changed after this preset preview. Preview it again.");
     error.status = 409;
@@ -339,6 +517,11 @@ export function installDeliveryPreset(workspace, request) {
   for (const file of plan.files) {
     if (file.status === "unchanged") continue;
     const target = resolve(workspace, file.path);
+    if (file.status === "removed") {
+      rmSync(target);
+      written.push(file.path);
+      continue;
+    }
     mkdirSync(dirname(target), { recursive: true });
     const temporary = join(dirname(target), `.portolan-${randomUUID()}.tmp`);
     try {
@@ -349,5 +532,5 @@ export function installDeliveryPreset(workspace, request) {
     }
     written.push(file.path);
   }
-  return { ...publicDeliveryPreset(planDeliveryPreset(workspace, request.provider)), written };
+  return { ...publicDeliveryPreset(planDeliveryPreset(workspace, selection)), written };
 }

package/scripts/diff.mjs

@@ -29,6 +29,7 @@ import { enrichCatalog } from "../src/enrich.ts";
 import { mergeCatalogs } from "../src/merge.ts";
 import { diffCatalogs, SEVERITIES } from "../src/lib/catalog-diff.ts";
 import { loadCatalog } from "./catalog-sources.mjs";
+import { readManifestText } from "./manifest.mjs";
 
 const HEADINGS = {
   breaking: "Breaking",
@@ -142,7 +143,10 @@ function defaultBase() {
 
 /** The merged, enriched, validated catalog as it stood at `ref`. */
 function catalogAt(ref) {
-  const manifest = JSON.parse(git(["show", ref + ":portolan.json"]));
+  const manifest = readManifestText(
+    git(["show", ref + ":portolan.json"]),
+    `${ref}:portolan.json`,
+  );
   const patterns = (manifest.sources ?? []).map(globToRegExp);
 
   const paths = git(["ls-tree", "-r", "--name-only", ref])