@shortlink-org/portolan 0.2.4 → 0.3.0

package/scripts/provenance.mjs

@@ -0,0 +1,72 @@
+// Where each catalog source last changed, for the site's stamp.
+//
+// A fragment carries no provenance of its own (portolan.0010); the history of
+// the checkout does. The browser cannot ask git, so this Vite plugin asks at
+// build time - and again under the dev server whenever a source changes -
+// and answers with one virtual module, keyed by the path `src/data.ts` gives
+// a source. Nothing watches `.git`: a commit made while the dev server runs
+// shows after a restart, or after the next change to a source.
+
+import { existsSync, globSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { forgetHistory, stampsFor } from "./history.mjs";
+import { readManifest } from "./manifest.mjs";
+
+export const PROVENANCE_MODULE = "virtual:portolan-provenance";
+const RESOLVED = `\0${PROVENANCE_MODULE}`;
+
+/**
+ * The stamp of every source the manifest's patterns find under `workspace`,
+ * keyed by its path as the manifest spells it.
+ *
+ * A staged site (`portolan dev`, `portolan build`) imports its sources under
+ * flattened names, `portolan/source-0007.json`, and keeps the way back in
+ * `.portolan/source-paths.json`. Such a stamp is keyed by the staged name the
+ * browser imports and carries `source`, the path the file has in the
+ * workspace - the one a project's root is a prefix of, and the one a link to
+ * the file has to name. Without it the site would know its sources only by
+ * names nobody typed.
+ *
+ * @param {string} workspace
+ * @param {string} siteRoot  Vite's root, which may contain flattened sources
+ * @returns {Record<string, {commit: string, generatedAt: string, source?: string}>}
+ */
+export function provenance(workspace, siteRoot = workspace) {
+  const sourceMap = join(siteRoot, ".portolan/source-paths.json");
+  if (existsSync(sourceMap)) {
+    const paths = JSON.parse(readFileSync(sourceMap, "utf8"));
+    const stamps = stampsFor(workspace, Object.values(paths));
+    return Object.fromEntries(Object.entries(paths).map(([staged, source]) => [staged, { ...stamps.get(source), source }]));
+  }
+  const manifest = readManifest(join(workspace, "portolan.json"));
+  const paths = [];
+  for (const pattern of manifest.sources ?? []) {
+    for (const path of globSync(pattern, { cwd: workspace })) paths.push(path.split("\\").join("/"));
+  }
+  return Object.fromEntries(stampsFor(workspace, paths.sort()));
+}
+
+/** @param {string} workspace */
+export function provenancePlugin(workspace) {
+  let siteRoot = workspace;
+  return {
+    name: "portolan-provenance",
+    configResolved(config) {
+      siteRoot = config.root;
+    },
+    resolveId(id) {
+      return id === PROVENANCE_MODULE ? RESOLVED : undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED) return undefined;
+      return `export default ${JSON.stringify(provenance(workspace, siteRoot))};\n`;
+    },
+    handleHotUpdate({ file, server }) {
+      if (!file.endsWith(".json") || file.includes("/node_modules/")) return;
+      forgetHistory();
+      const mod = server.moduleGraph.getModuleById(RESOLVED);
+      if (mod) server.moduleGraph.invalidateModule(mod);
+    },
+  };
+}

package/scripts/provenance.test.mjs

@@ -0,0 +1,149 @@
+// The provenance of a source is the history's (portolan.0010): the commit
+// that last changed the file, read off the checkout and never written in.
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { changedSince, forgetHistory, lastCommitTouching, stampsFor } from "./history.mjs";
+import { provenance } from "./provenance.mjs";
+
+const created = [];
+afterEach(() => {
+  forgetHistory();
+  for (const path of created.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+const ADA = { GIT_AUTHOR_NAME: "Ada Lovelace", GIT_AUTHOR_EMAIL: "ada@example.com", GIT_COMMITTER_NAME: "Ada Lovelace", GIT_COMMITTER_EMAIL: "ada@example.com" };
+
+function repository() {
+  const root = mkdtempSync(join(tmpdir(), "portolan-provenance-"));
+  created.push(root);
+  const git = (args, date = "2026-01-01T09:00:00Z") =>
+    execFileSync("git", ["-C", root, ...args], {
+      encoding: "utf8",
+      env: { ...process.env, ...ADA, GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date },
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  const write = (name, contents) => {
+    mkdirSync(join(root, name, ".."), { recursive: true });
+    writeFileSync(join(root, name), contents);
+  };
+  git(["init", "-q"]);
+  return { root, git, write };
+}
+
+function elsewhere() {
+  const dir = mkdtempSync(join(tmpdir(), "portolan-no-repo-"));
+  created.push(dir);
+  return dir;
+}
+
+describe("stampsFor", () => {
+  // The stamp is the commit the change landed in, which is what a stamp
+  // written into the file could never say.
+  it("dates a source by the commit that last changed it", () => {
+    const { root, git, write } = repository();
+    write("portolan/domain.json", "{}\n");
+    write("portolan/api.json", "{}\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "both"], "2026-01-01T09:00:00Z");
+    write("portolan/domain.json", '{"changed":true}\n');
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "domain again"], "2026-02-02T10:00:00Z");
+    const second = git(["rev-parse", "--short=7", "HEAD"]);
+    const first = git(["rev-parse", "--short=7", "HEAD~1"]);
+
+    const stamps = stampsFor(root, ["portolan/domain.json", "portolan/api.json"]);
+    expect(stamps.get("portolan/domain.json")).toEqual({ commit: second, generatedAt: "2026-02-02T10:00:00Z" });
+    expect(stamps.get("portolan/api.json")).toEqual({ commit: first, generatedAt: "2026-01-01T09:00:00Z" });
+  });
+
+  it("calls a modified, an untracked and an unversioned file uncommitted, dated by the working tree", () => {
+    const { root, git, write } = repository();
+    write("portolan/domain.json", "{}\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "one"]);
+    write("portolan/domain.json", '{"dirty":true}\n');
+    write("portolan/new.json", "{}\n");
+    const outside = elsewhere();
+    writeFileSync(join(outside, "authored.json"), "{}\n");
+
+    const stamps = stampsFor(root, ["portolan/domain.json", "portolan/new.json", join(outside, "authored.json")]);
+    expect(stamps.size).toBe(3);
+    for (const stamp of stamps.values()) {
+      expect(stamp.commit).toBe("uncommitted");
+      expect(Number.isNaN(Date.parse(stamp.generatedAt))).toBe(false);
+    }
+  });
+});
+
+describe("what changed since the output was last committed", () => {
+  it("lists the inputs that moved, working tree included, and leaves the output directory out", () => {
+    const { root, git, write } = repository();
+    write("svc/main.go", "package main\n");
+    write("svc/go.mod", "module svc\n");
+    write("svc/portolan/domain.json", "{}\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "generated"], "2026-01-01T09:00:00Z");
+    const generated = git(["rev-parse", "--short=7", "HEAD"]);
+    write("svc/main.go", "package main // changed\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "source moved"], "2026-02-02T10:00:00Z");
+    write("svc/go.mod", "module svc // dirty\n");
+    write("svc/new.go", "package main\n");
+    write("svc/portolan/domain.json", '{"regenerated":true}\n');
+
+    expect(lastCommitTouching(root, ["svc/portolan/domain.json"])).toEqual({ commit: generated, date: "2026-01-01T09:00:00Z" });
+    expect(changedSince(root, generated, ["svc"], ["svc/portolan"])).toEqual(["svc/go.mod", "svc/main.go", "svc/new.go"]);
+    expect(changedSince(root, generated, ["svc"])).toContain("svc/portolan/domain.json");
+  });
+
+  it("answers null for an output nobody has committed, and nothing outside a repository", () => {
+    const { root, write } = repository();
+    write("svc/portolan/domain.json", "{}\n");
+    expect(lastCommitTouching(root, ["svc/portolan/domain.json"])).toBeNull();
+    const outside = elsewhere();
+    expect(lastCommitTouching(outside, ["x.json"])).toBeNull();
+    expect(changedSince(outside, "HEAD", ["."])).toEqual([]);
+  });
+});
+
+describe("the site's provenance module", () => {
+  it("stamps every source the manifest's patterns find, keyed as the manifest spells them", () => {
+    const { root, git, write } = repository();
+    write("portolan.json", JSON.stringify({ sources: ["portolan/*.json", "services/*/portolan/*.json"] }));
+    write("portolan/host.json", "{}\n");
+    write("services/oms/portolan/domain.json", "{}\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "one"], "2026-03-03T03:00:00Z");
+    const head = git(["rev-parse", "--short=7", "HEAD"]);
+
+    expect(provenance(root)).toEqual({
+      "portolan/host.json": { commit: head, generatedAt: "2026-03-03T03:00:00Z" },
+      "services/oms/portolan/domain.json": { commit: head, generatedAt: "2026-03-03T03:00:00Z" },
+    });
+  });
+
+  // A staged site imports flattened copies. The stamp is the workspace file's,
+  // keyed by the name the browser imports, and it says which file that was -
+  // the path a project's root is a prefix of.
+  it("keys a staged site's sources by their flattened names and says where each came from", () => {
+    const { root, git, write } = repository();
+    write("portolan.json", JSON.stringify({ sources: ["services/*/portolan/*.json"] }));
+    write("services/oms/portolan/domain.json", "{}\n");
+    git(["add", "."]);
+    git(["commit", "-q", "-m", "one"], "2026-03-03T03:00:00Z");
+    const head = git(["rev-parse", "--short=7", "HEAD"]);
+    const stage = join(root, ".portolan", "site");
+    write(".portolan/site/.portolan/source-paths.json", JSON.stringify({
+      "portolan/source-0001.json": "services/oms/portolan/domain.json",
+    }));
+
+    expect(provenance(root, stage)).toEqual({
+      "portolan/source-0001.json": { commit: head, generatedAt: "2026-03-03T03:00:00Z", source: "services/oms/portolan/domain.json" },
+    });
+  });
+});

package/scripts/run-builtin.mjs

@@ -2,12 +2,12 @@
 
 // Process adapter for plugins bundled in the npm package. It keeps the
 // plugin's cwd in the user's workspace while resolving source and toolchain
-// files from the installation. The Go plugins no longer come through here:
-// they are one wasm module (portolan.0006), and the fetchers run inside the
-// host (portolan.0008).
+// files from the installation. Most Go plugins are one wasm module
+// (portolan.0006). A Go plugin that needs the project toolchain is compiled to
+// a workspace-local sidecar here, then run with the user's workspace as cwd.
 
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -29,6 +29,8 @@ const args = [...(plugin.process.args ?? [])];
 
 if (command === "cargo" && existsSync(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"))) {
   run(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"), []);
+} else if (command === "go") {
+  buildAndRunGo(args);
 } else {
   if (command === "cargo") {
     process.env.CARGO_TARGET_DIR = resolve(workspace, ".portolan", "bin", "cargo");
@@ -40,6 +42,38 @@ if (command === "cargo" && existsSync(resolve(installRoot, "plugins/extract-rust
   run(command, resolved);
 }
 
+// `go run` changes module resolution with the current directory, but the
+// analyzer must keep the scanned workspace as its cwd. Build from Portolan's
+// shipped module first, outside the workspace, and execute the resulting
+// native sidecar from the workspace. The Go build cache makes subsequent
+// describe/extract calls cheap; rebuilding also prevents a stale sidecar after
+// an npm upgrade with the same workspace cache.
+function buildAndRunGo(argv) {
+  if (argv[0] !== "run" || typeof argv[1] !== "string" || !argv[1] || argv[1].startsWith("-")) {
+    console.error(`portolan: built-in ${name} has an unsupported Go command`);
+    process.exitCode = 2;
+    return;
+  }
+  const binDir = resolve(workspace, ".portolan", "bin", "go");
+  const executable = resolve(binDir, process.platform === "win32" ? `${name}.exe` : name);
+  mkdirSync(binDir, { recursive: true });
+  const built = spawnSync("go", ["build", "-mod=readonly", "-o", executable, argv[1]], {
+    cwd: installRoot,
+    env: { ...process.env, GOWORK: "off" },
+    stdio: "inherit",
+  });
+  if (built.error) {
+    console.error(`portolan: built-in ${name} could not build: ${built.error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (built.status !== 0) {
+    process.exitCode = built.status ?? 1;
+    return;
+  }
+  run(executable, argv.slice(2));
+}
+
 function resolveArgument(executable, index) {
   if (["node", "python", "python3"].includes(executable)) return index === 0;
   if (executable === "java") return index === 1;

package/scripts/schema.mjs

@@ -116,6 +116,13 @@ function compose() {
         description:
           "The source projects that make up the estate. A project gives repeated pipeline inputs one name for the generated site's Settings page; estate-wide inputs such as flows need no project.",
       },
+      warningPolicies: {
+        type: "array",
+        maxItems: 100,
+        items: { $ref: "#/$defs/warningPolicy" },
+        description:
+          "CEL policies for reviewed extraction limitations. Expressions are type-checked when the manifest is read and suppression always requires a reason.",
+      },
       plugins: {
         type: "array",
         items: { $ref: "#/$defs/plugin" },
@@ -139,6 +146,28 @@ function compose() {
       },
     },
     $defs: {
+      warningPolicy: {
+        type: "object",
+        additionalProperties: false,
+        required: ["when", "action", "reason"],
+        properties: {
+          when: {
+            type: "string",
+            minLength: 1,
+            maxLength: 1000,
+            description: "Boolean CEL expression over plugin, rule, severity, project, phase, ref, message and count.",
+          },
+          action: {
+            const: "suppress",
+            description: "Suppress matching diagnostics from the active view while retaining them in the report.",
+          },
+          reason: {
+            type: "string",
+            minLength: 1,
+            description: "Why this limitation is consciously accepted.",
+          },
+        },
+      },
       catalogProfile: {
         type: "object",
         additionalProperties: false,

package/scripts/warning-policy.mjs

@@ -0,0 +1,161 @@
+import { Environment } from "@marcbachmann/cel-js";
+
+const ENVIRONMENT = new Environment({
+  unlistedVariablesAreDyn: false,
+  limits: {
+    maxAstNodes: 256,
+    maxDepth: 32,
+    maxListElements: 32,
+    maxMapEntries: 32,
+    maxCallArguments: 8,
+  },
+})
+  .registerVariable("plugin", "string")
+  .registerVariable("rule", "string")
+  .registerVariable("severity", "string")
+  .registerVariable("project", "string")
+  .registerVariable("phase", "string")
+  .registerVariable("ref", "string")
+  .registerVariable("message", "string")
+  .registerVariable("count", "int");
+const COMPILED = new Map();
+
+const RULES = [
+  rule("openapi.missing-operation-id", /\bhas no operationId\b/i, "warning", "Add stable operationId values to the OpenAPI operations."),
+  rule("schema.duplicate-declaration", /\bduplicate declaration\b/i, "warning", "Remove or reconcile duplicate schema declarations; Portolan currently uses the first."),
+  rule("analysis.typed-fallback", /\btyped call graph unavailable\b/i, "warning", "Run an extractor build with typed analysis support or inspect calls found by the syntax fallback."),
+  rule("catalog.unresolved-call", /\bcalls .+ which nothing in this catalog resolves\b/i, "warning", "Add or correct the provider contract, then regenerate to resolve the call."),
+  rule("catalog.unmapped-proto-peer", /\bmanifest names no peer for that package\b/i, "warning", "Map the protobuf package under peers, or declare it under externals."),
+  rule("flow.unresolved-step", /\bstep .+ is unresolved\b/i, "warning", "Declare the referenced endpoint, message, or store so this flow step can be joined."),
+  rule("flow.unknown-port", /\bis neither a domain port nor a use case\b/i, "warning", "Model this dependency as a domain port or use case, or accept that its calls stay outside the flow."),
+  rule("flow.unreached-event", /\bno flow reaches this event\b/i, "warning", "Connect the event to its publisher flow or remove the stale event declaration."),
+  rule("flow.unknown-event", /\breacts to the message named .+ which no event .+ declares is called\b/i, "warning", "Declare the event name used by the handler or correct the handler mapping."),
+  rule("django.invalid-aggregate-root", /\baggregates names .+ and no model there is called that\b/i, "warning", "Choose an existing concrete model for the application's aggregates option."),
+  rule("django.ambiguous-aggregate-root", /\bmodels to choose from: name the root in the aggregates option\b/i, "warning", "Choose the aggregate root explicitly in the django-domain aggregates option."),
+  rule("django.unknown-http-verb", /\bmounted as an HTTP view, but no HTTP verb is declared\b/i, "warning", "Declare the accepted HTTP methods on the view or route."),
+  rule("river.missing-worker", /\bno registered Worker\b/i, "warning", "Register the River worker in this component or remove the unmatched insert."),
+  rule("watermill.unresolved-topic", /\bWatermill .+ topic could not be resolved\b/i, "warning", "Use a literal, constant, or configuration default for the Watermill topic."),
+  rule("messaging.unresolved-subject", /\bsubject of .+ could not be resolved\b/i, "warning", "Use a literal, constant, configuration default, or visible caller argument for the subject."),
+  rule("store.external-migrations", /\bmigrations are applied from .+ whose schema is not in this tree\b/i, "warning", "Vendor or expose the external migrations so their tables can be included in the store."),
+  rule("store.missing-foreign-table", /\bcolumn .+ references .+ which no migration here creates\b/i, "warning", "Include the referenced table migration or correct the foreign-key target."),
+  rule("schema.unresolved-type", /\bis not declared in the protos read here\b/i, "warning", "Include the imported protobuf declaration or map the type to an external schema."),
+  rule("source.offline-cache", /\bnot fetched \(offline\)\b/i, "info", "Regenerate with network access when the vendored copy must be refreshed."),
+  rule("source.unpinned", /\bnot pinned\b/i, "warning", "Pin the source to an immutable commit or schema version."),
+  rule("source.parse-failed", /\bcould not (?:be read|parse|be parsed|be encoded)\b/i, "error", "Open the referenced source and fix the parse or read error."),
+  rule("extraction.no-match", /\b(?:no .+ (?:was|were) found|no .+ matched|declares no |no models in this application)\b/i, "info", "Confirm this capability is absent, or point the extractor at the source that declares it."),
+];
+
+const FALLBACK_ACTION = "Inspect the referenced source and either fix the extraction gap or add a reviewed CEL policy with a reason.";
+
+/**
+ * Classify, count and apply CEL policies to one step's raw warnings.
+ * Policy evaluation happens here, while the build still has its manifest;
+ * deployed sites receive decisions, not an expression runtime.
+ */
+export function diagnoseWarnings({ plugin, warnings, policies = [], project = "", phase = "" }) {
+  const diagnostics = warnings.map((message) => classifyWarning(plugin, message));
+  const counts = new Map();
+  for (const diagnostic of diagnostics) {
+    const key = `${diagnostic.plugin}\0${diagnostic.rule}\0${diagnostic.severity}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const compiled = policies.map((policy) => ({ ...policy, expression: compilePolicy(policy.when) }));
+
+  return diagnostics.map((diagnostic) => {
+    const count = counts.get(`${diagnostic.plugin}\0${diagnostic.rule}\0${diagnostic.severity}`) ?? 1;
+    const context = {
+      plugin: diagnostic.plugin,
+      rule: diagnostic.rule,
+      severity: diagnostic.severity,
+      project,
+      phase,
+      ref: diagnostic.ref ?? "",
+      message: diagnostic.message,
+      count: BigInt(count),
+    };
+    const matched = compiled.find((policy) => policy.action === "suppress" && policy.expression(context) === true);
+    return {
+      ...diagnostic,
+      count,
+      project,
+      phase,
+      suppressed: Boolean(matched),
+      ...(matched ? { suppressionReason: matched.reason } : {}),
+    };
+  });
+}
+
+/** Validate CEL syntax, names and the boolean result type while reading the manifest. */
+export function warningPolicyProblems(policies, path = "portolan.json") {
+  const problems = [];
+  for (const [index, policy] of (Array.isArray(policies) ? policies : []).entries()) {
+    if (!policy || typeof policy !== "object" || typeof policy.when !== "string") continue;
+    try {
+      compilePolicy(policy.when);
+    } catch (cause) {
+      problems.push(`${path} warningPolicies/${index}/when: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+  }
+  return problems;
+}
+
+export function classifyWarning(plugin, message) {
+  const definition = RULES.find((candidate) => candidate.matches.test(message));
+  const ref = warningRef(message);
+  return {
+    plugin,
+    message,
+    rule: definition?.id ?? `plugin.${slug(plugin)}.other-${fingerprint(message)}`,
+    severity: definition?.severity ?? "warning",
+    action: definition?.action ?? FALLBACK_ACTION,
+    ...(ref ? { ref } : {}),
+  };
+}
+
+function compilePolicy(source) {
+  if (COMPILED.has(source)) return COMPILED.get(source);
+  let expression;
+  try {
+    expression = ENVIRONMENT.parse(source);
+  } catch (cause) {
+    throw new Error(`invalid CEL: ${cause instanceof Error ? firstLine(cause.message) : String(cause)}`);
+  }
+  const checked = expression.check();
+  if (!checked.valid) throw new Error(`invalid CEL: ${firstLine(checked.error?.message ?? "type check failed")}`);
+  if (checked.type !== "bool") throw new Error(`CEL expression must return bool, got ${checked.type}`);
+  COMPILED.set(source, expression);
+  return expression;
+}
+
+function rule(id, matches, severity, action) {
+  return { id, matches, severity, action };
+}
+
+function warningRef(message) {
+  const match = message.match(/^(.+?):\s+(?=[A-Za-z/])/);
+  return match?.[1]?.trim() || undefined;
+}
+
+function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "unknown";
+}
+
+function fingerprint(message) {
+  const ref = warningRef(message);
+  const body = (ref ? message.slice(message.indexOf(":", ref.length) + 1) : message)
+    .toLowerCase()
+    .replace(/`[^`]*`|"[^"]*"|'[^']*'/g, "<value>")
+    .replace(/\b\d+\b/g, "#")
+    .replace(/\s+/g, " ")
+    .trim();
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < body.length; index += 1) {
+    hash ^= body.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+function firstLine(message) {
+  return String(message).split("\n", 1)[0];
+}

package/scripts/warning-policy.test.mjs

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { diagnoseWarnings, warningPolicyProblems } from "./warning-policy.mjs";
+
+describe("warning CEL policies", () => {
+  const warnings = [
+    "api: /book POST has no operationId; listed by verb and path",
+    "api: /cancel POST has no operationId; listed by verb and path",
+  ];
+
+  it("evaluates typed CEL over the diagnostic and its repetition count", () => {
+    const diagnostics = diagnoseWarnings({
+      plugin: "openapi",
+      warnings,
+      project: "aviacore",
+      phase: "extract",
+      policies: [{
+        when: "plugin == 'openapi' && rule == 'openapi.missing-operation-id' && project == 'aviacore' && count >= 2",
+        action: "suppress",
+        reason: "Owned upstream.",
+      }],
+    });
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0]).toMatchObject({
+      rule: "openapi.missing-operation-id",
+      count: 2,
+      project: "aviacore",
+      phase: "extract",
+      suppressed: true,
+      suppressionReason: "Owned upstream.",
+    });
+  });
+
+  it("leaves non-matching diagnostics active", () => {
+    const [diagnostic] = diagnoseWarnings({
+      plugin: "openapi",
+      warnings: warnings.slice(0, 1),
+      project: "aviasupp",
+      phase: "extract",
+      policies: [{ when: "project == 'aviacore'", action: "suppress", reason: "Only core." }],
+    });
+    expect(diagnostic?.suppressed).toBe(false);
+  });
+
+  it("reports unknown variables, syntax errors and non-boolean expressions", () => {
+    expect(warningPolicyProblems([{ when: "unknown == 1" }])).toEqual([
+      expect.stringContaining("Unknown variable: unknown"),
+    ]);
+    expect(warningPolicyProblems([{ when: "plugin ==" }])).toEqual([
+      expect.stringContaining("invalid CEL"),
+    ]);
+    expect(warningPolicyProblems([{ when: "plugin" }])).toEqual([
+      expect.stringContaining("must return bool"),
+    ]);
+  });
+});

package/src/app/Sidebar.tsx

@@ -878,15 +878,15 @@ function AggregateNode({
         depth={2}
         open={aopen}
         onToggle={() => toggle(akey, false)}
-        label={`aggregate ${aggregate.name}`}
+        label={`${aggregate.kind === "model-group" ? "model group" : "aggregate"} ${aggregate.name}`}
         selId={aggregate.id}
         under={
           <div
             className="mono truncate pr-2 text-muted"
             style={{ paddingLeft: indent(3), fontSize: 11 }}
-            title={`aggregate root: ${aggregate.root}`}
+            title={aggregate.kind === "model-group" ? "Model group; aggregate boundary not specified" : `aggregate root: ${aggregate.root}`}
           >
-            root: {aggregate.root}
+            {aggregate.kind === "model-group" ? "model group" : `root: ${aggregate.root}`}
           </div>
         }
         right={

package/src/catalog-docs.test.ts

@@ -0,0 +1,64 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { catalogDocs } from "./catalog-docs";
+// @ts-expect-error The build's documentation mount is a plain JavaScript module.
+import { siteDocs } from "../scripts/site-docs.mjs";
+
+const roots: string[] = [];
+afterEach(() => roots.splice(0).forEach((root) => rmSync(root, { recursive: true, force: true })));
+
+describe("catalog documentation URLs", () => {
+  it.each(["default", "avia", "portolan"])("opens the files actually published for root catalog %s", (id) => {
+    const root = mkdtempSync(join(tmpdir(), "catalog-docs-"));
+    roots.push(root);
+    const out = join(root, "generated", "markdown");
+    const dist = join(root, "dist");
+    mkdirSync(out, { recursive: true });
+    mkdirSync(dist);
+    writeFileSync(join(out, "llms.txt"), "# Catalog\n[Home](README.md)\n");
+    writeFileSync(join(out, "llms-full.txt"), "# Full catalog\n");
+    writeFileSync(join(out, "README.md"), "# Home\n");
+    const manifest = { generate: [{ plugin: "markdown", ...(id === "default" ? {} : { catalog: id }), out }] };
+    siteDocs({ manifest, dist });
+
+    const urls = catalogDocs(manifest, id, "/portolan/")!;
+    expect(urls.index).toBe("/portolan/llms.txt");
+    const published = (url: string) => readFileSync(join(dist, url.slice("/portolan/".length)), "utf8");
+    expect(published(urls.index)).toContain("[Home](docs/README.md)");
+    expect(published(urls.full)).toBe("# Full catalog\n");
+    expect(published(`${urls.pages}README.md`)).toBe("# Home\n");
+  });
+
+  it("uses a nested output directory even when it differs from the catalog id", () => {
+    const manifest = { generate: [
+      { plugin: "markdown", catalog: "avia", out: "./generated/docs/" },
+      { plugin: "markdown", catalog: "example", out: "generated/docs/samples" },
+    ] };
+    expect(catalogDocs(manifest, "example", "/portolan")).toEqual({
+      pages: "/portolan/docs/samples/",
+      index: "/portolan/docs/samples/llms.txt",
+      full: "/portolan/docs/samples/llms-full.txt",
+    });
+  });
+
+  it("preserves the demo's example paths and supports a site served at /", () => {
+    const manifest = { generate: [
+      { plugin: "markdown", catalog: "portolan", out: "docs" },
+      { plugin: "markdown", catalog: "example", out: "docs/example" },
+    ] };
+    expect(catalogDocs(manifest, "example", "/")?.index).toBe("/docs/example/llms.txt");
+    expect(catalogDocs(manifest, "portolan", "/")?.index).toBe("/llms.txt");
+  });
+
+  it("does not invent URLs for missing or unmounted documentation", () => {
+    expect(catalogDocs({}, "default", "/")).toBeNull();
+    const manifest = { generate: [
+      { plugin: "markdown", catalog: "avia", out: "docs" },
+      { plugin: "markdown", catalog: "example", out: "docs-other" },
+    ] };
+    expect(catalogDocs(manifest, "unknown", "/")).toBeNull();
+    expect(catalogDocs(manifest, "example", "/")).toBeNull();
+  });
+});