@shortlink-org/portolan 0.2.4 → 0.4.0

package/scripts/trace-trials.mjs

@@ -0,0 +1,176 @@
+// A recording uploaded from the page becomes a file beside the project and a
+// verify step that reads it - nothing else. The pure half of that lives here,
+// where a test can hold it: which step reads a project's recordings, where an
+// upload lands, and what a trial run said about it once the verifier ran.
+//
+// The recording is kept in the repository on purpose (portolan.0014). The
+// catalog is regenerated from files, by anyone, on any machine; a recording
+// held anywhere else would verify a flow once and never again.
+
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+
+export const TRACE_PLUGIN = "otel";
+export const RECORDINGS_DIR = "telemetry/recordings";
+export const RECORDINGS_GLOB = `${RECORDINGS_DIR}/*.jsonl`;
+export const UPLOAD_LIMIT = 32 * 1024 * 1024;
+
+/** The verify step that reads a project's recordings, or null. */
+export function traceStepFor(manifest, project) {
+  const steps = (manifest.verify ?? []).map((step, index) => ({ step, index }));
+  const mine = steps.filter(({ step }) => step.plugin === TRACE_PLUGIN && step.in === project.root);
+  return mine[0] ?? null;
+}
+
+/**
+ * The manifest with a step that reads the project's recordings: the one it
+ * has, widened to the recordings directory when it does not look there yet,
+ * or a new one after the last verify step. Says whether anything changed.
+ */
+export function manifestWithTraceStep(manifest, project) {
+  const found = traceStepFor(manifest, project);
+  const verify = [...(manifest.verify ?? [])];
+  if (found) {
+    const traces = found.step.options?.traces ?? [];
+    if (traces.includes(RECORDINGS_GLOB)) return { manifest, changed: false, change: "none", step: found.step };
+    const step = { ...found.step, options: { ...found.step.options, traces: [...traces, RECORDINGS_GLOB] } };
+    verify[found.index] = step;
+    return { manifest: { ...manifest, verify }, changed: true, change: "widened", step };
+  }
+  const step = {
+    plugin: TRACE_PLUGIN,
+    in: project.root,
+    out: posix.join(project.root, "portolan"),
+    options: { traces: [RECORDINGS_GLOB], out: "observed.json" },
+  };
+  verify.push(step);
+  return { manifest: { ...manifest, verify }, changed: true, change: "added", step };
+}
+
+/** The step with the names the page was told to map, merged over what it had. */
+export function stepWithMappings(step, { services, events, routes } = {}) {
+  const options = { ...step.options };
+  if (services && Object.keys(services).length) options.services = { ...options.services, ...services };
+  if (events && Object.keys(events).length) options.events = { ...options.events, ...events };
+  if (routes && Object.keys(routes).length) options.routes = { ...options.routes, ...routes };
+  return { ...step, options };
+}
+
+/**
+ * Where an upload lands, relative to the project root: dated, named after
+ * the file it came as, and not on top of a recording already there.
+ */
+export function recordingPath(name, { today = new Date(), taken = () => false } = {}) {
+  const base = String(name ?? "").split(/[\\/]/).pop() ?? "";
+  const stem = base.replace(/\.(jsonl?|ndjson)$/i, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "recording";
+  const date = today.toISOString().slice(0, 10);
+  let candidate = `${RECORDINGS_DIR}/${date}-${stem}.jsonl`;
+  for (let n = 2; taken(candidate); n += 1) candidate = `${RECORDINGS_DIR}/${date}-${stem}-${n}.jsonl`;
+  return candidate;
+}
+
+/**
+ * Says whether the bytes are a recording the verifier can read: OTLP JSON,
+ * one batch per file or one per line, with resourceSpans in it.
+ */
+export function checkRecording(content) {
+  const text = content.toString("utf8");
+  if (!text.trim()) throw new Error("The recording is empty.");
+  let batches = 0;
+  let spans = 0;
+  const read = (value) => {
+    if (!value || typeof value !== "object" || !Array.isArray(value.resourceSpans)) throw new Error("The recording is JSON, but not OTLP: no resourceSpans in it.");
+    batches += 1;
+    for (const rs of value.resourceSpans) for (const ss of rs?.scopeSpans ?? []) spans += (ss?.spans ?? []).length;
+  };
+  try {
+    read(JSON.parse(text));
+  } catch (cause) {
+    if (cause instanceof SyntaxError) {
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        let value;
+        try { value = JSON.parse(line); } catch { throw new Error("The recording is not OTLP JSON: a collector's file exporter writes one batch per line."); }
+        read(value);
+      }
+    } else {
+      throw cause;
+    }
+  }
+  if (!spans) throw new Error("The recording has no spans in it.");
+  return { batches, spans };
+}
+
+/** What a verifier's warning is about, so the page can offer the mapping it asks for. */
+export function readVerifyWarning(message) {
+  let m = message.match(/spans from service\.name "([^"]+)" match no service/);
+  if (m) return { kind: "service", name: m[1], message };
+  m = message.match(/(?:publishes|consumes) "([^"]+)", which matches no event/);
+  if (m) return { kind: "event", name: m[1], message };
+  m = message.match(/answers on ([A-Z]* ?\S+), which no interface it provides declares/);
+  if (m) return { kind: "route", name: m[1].trim(), message };
+  m = message.match(/calls ([A-Z]+ \S+) on (\S+), which no service/);
+  if (m) return { kind: "call", name: m[1], message };
+  if (/but the catalog says it goes on/.test(message)) return { kind: "channel", message };
+  return { kind: "other", message };
+}
+
+/**
+ * What the trial run said about the recording: the flows the verifier wrote
+ * with it, and the warnings that name something the page could map.
+ */
+export function summarizeTraceTrial(snapshot, trial, events) {
+  const step = trial.step;
+  const finished = events.find((event) => event.type === "step-finished" && event.phase === "verify" && event.plugin === step.plugin && event.output === step.out && (event.input ?? step.in) === step.in)
+    ?? events.find((event) => event.type === "step-finished" && event.phase === "verify" && event.plugin === step.plugin && event.output === step.out);
+  const warnings = (finished?.warnings ?? []).map(readVerifyWarning);
+  const fragmentName = step.options?.out ?? "observed.json";
+  let fragment = { flows: [] };
+  try { fragment = JSON.parse(readFileSync(join(snapshot, step.out, fragmentName), "utf8")); } catch {}
+  // An example names its recording relative to the repository, the way every
+  // `source` in the catalog does; the upload was laid under the step's input.
+  const recording = posix.join(step.in, trial.recording);
+  const flows = [];
+  for (const flow of fragment.flows ?? []) {
+    const examples = (flow.examples ?? []).filter((example) => example.recording === recording);
+    const steps = [];
+    const walk = (nodes) => {
+      for (const node of nodes ?? []) {
+        if (node.type === "step") steps.push(node);
+        else if (node.type === "alt") for (const branch of node.branches ?? []) walk(branch.steps);
+        else if (node.type === "parallel") for (const branch of node.branches ?? []) walk(branch);
+        else walk(node.steps);
+      }
+    };
+    walk(flow.steps);
+    const shown = new Set(examples.flatMap((example) => example.steps.map((s) => s.step)));
+    const observed = String(flow.slug ?? "").startsWith("observed-");
+    flows.push({
+      id: flow.id,
+      slug: flow.slug,
+      name: flow.name,
+      owner: flow.owner,
+      kind: observed ? "observed" : "declared",
+      inRecording: examples.length > 0,
+      traces: examples.length,
+      verified: steps.filter((s) => s.status === "verified").length,
+      unresolved: steps.filter((s) => s.status === "unresolved").length,
+      added: steps.filter((s) => s.seen && !observed && /^seen\d+$/.test(String(s.id))).length,
+      shown: shown.size,
+      steps: steps.length,
+      examples: (flow.examples ?? []).length,
+    });
+  }
+  flows.sort((a, b) => Number(b.inRecording) - Number(a.inRecording) || a.slug.localeCompare(b.slug));
+  return {
+    project: trial.projectId,
+    recording: trial.recording,
+    stepAdded: trial.stepAdded,
+    stepChange: trial.stepChange ?? (trial.stepAdded ? "added" : "none"),
+    status: finished?.status ?? "failed",
+    spans: trial.spans,
+    flows,
+    warnings,
+    mappings: { services: step.options?.services ?? {}, events: step.options?.events ?? {}, routes: step.options?.routes ?? {} },
+  };
+}

package/scripts/trace-trials.test.mjs

@@ -0,0 +1,142 @@
+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 { checkRecording, manifestWithTraceStep, readVerifyWarning, recordingPath, stepWithMappings, summarizeTraceTrial, traceStepFor } from "./trace-trials.mjs";
+
+const project = { id: "auth", name: "Auth", root: "examples/auth", context: "auth", service: "auth" };
+
+describe("the step that reads a project's recordings", () => {
+  it("is added after the last verify step when the project has none", () => {
+    const manifest = { sources: ["x/*.json"], projects: [project], verify: [{ plugin: "codeowners", in: ".github", out: "data" }] };
+    const next = manifestWithTraceStep(manifest, project);
+
+    expect(next.changed).toBe(true);
+    expect(next.change).toBe("added");
+    expect(next.manifest.verify).toHaveLength(2);
+    expect(next.step).toEqual({ plugin: "otel", in: "examples/auth", out: "examples/auth/portolan", options: { traces: ["telemetry/recordings/*.jsonl"], out: "observed.json" } });
+    expect(manifest.verify).toHaveLength(1);
+  });
+
+  it("is widened to the recordings directory when it reads elsewhere, and left alone when it already does", () => {
+    const step = { plugin: "otel", in: "examples/auth", out: "examples/auth/portolan", options: { traces: ["telemetry/traces.jsonl"], out: "observed.json", services: { "auth-api": "auth.auth" } } };
+    const manifest = { sources: [], projects: [project], verify: [step] };
+
+    const widened = manifestWithTraceStep(manifest, project);
+    expect(widened.changed).toBe(true);
+    expect(widened.change).toBe("widened");
+    expect(widened.step.options.traces).toEqual(["telemetry/traces.jsonl", "telemetry/recordings/*.jsonl"]);
+    expect(widened.step.options.services).toEqual({ "auth-api": "auth.auth" });
+
+    const again = manifestWithTraceStep(widened.manifest, project);
+    expect(again.changed).toBe(false);
+    expect(again.change).toBe("none");
+    expect(traceStepFor(again.manifest, project)?.index).toBe(0);
+  });
+
+  it("is the project's own, not another project's", () => {
+    const other = { plugin: "otel", in: "examples/shop/cart", out: "examples/shop/cart/portolan", options: { traces: ["telemetry/traces.jsonl"] } };
+    expect(traceStepFor({ verify: [other] }, project)).toBeNull();
+  });
+
+  it("takes the names the page mapped over what it had", () => {
+    const step = { plugin: "otel", in: "x", out: "y", options: { traces: ["a"], events: { "a.B": "x.y.B" } } };
+    const mapped = stepWithMappings(step, { services: { "auth-api": "auth.auth" }, events: { "a.C": "x.y.C" }, routes: { "POST /api/v1/sessions": "login" } });
+    expect(mapped.options).toEqual({ traces: ["a"], events: { "a.B": "x.y.B", "a.C": "x.y.C" }, services: { "auth-api": "auth.auth" }, routes: { "POST /api/v1/sessions": "login" } });
+    expect(stepWithMappings(step, {})).toEqual(step);
+  });
+});
+
+describe("where an upload lands", () => {
+  const today = new Date("2026-09-12T10:00:00Z");
+
+  it("is dated, named after the file, and never on top of another", () => {
+    expect(recordingPath("Login Traces.JSONL", { today })).toBe("telemetry/recordings/2026-09-12-login-traces.jsonl");
+    expect(recordingPath("/tmp/export/traces.json", { today })).toBe("telemetry/recordings/2026-09-12-traces.jsonl");
+    expect(recordingPath("", { today })).toBe("telemetry/recordings/2026-09-12-recording.jsonl");
+    const taken = new Set(["telemetry/recordings/2026-09-12-traces.jsonl", "telemetry/recordings/2026-09-12-traces-2.jsonl"]);
+    expect(recordingPath("traces.jsonl", { today, taken: (candidate) => taken.has(candidate) })).toBe("telemetry/recordings/2026-09-12-traces-3.jsonl");
+  });
+});
+
+describe("what an upload has to be", () => {
+  const batch = (spans) => JSON.stringify({ resourceSpans: [{ resource: { attributes: [] }, scopeSpans: [{ spans }] }] });
+  const span = { traceId: "t", spanId: "s", name: "GET /", kind: 2 };
+
+  it("reads one value or one per line", () => {
+    expect(checkRecording(Buffer.from(batch([span])))).toEqual({ batches: 1, spans: 1 });
+    expect(checkRecording(Buffer.from(`${batch([span])}\n${batch([span, span])}\n`))).toEqual({ batches: 2, spans: 3 });
+  });
+
+  it("refuses what the verifier could not read, and says why", () => {
+    expect(() => checkRecording(Buffer.from(""))).toThrow(/empty/);
+    expect(() => checkRecording(Buffer.from("not json"))).toThrow(/not OTLP JSON/);
+    expect(() => checkRecording(Buffer.from('{"traces":[]}'))).toThrow(/no resourceSpans/);
+    expect(() => checkRecording(Buffer.from(batch([])))).toThrow(/no spans/);
+  });
+});
+
+describe("what a verifier's warning is about", () => {
+  it("names the service, event or route the page could map", () => {
+    expect(readVerifyWarning('spans from service.name "auth-api" match no service in the catalog; name it under `services` to say which one it is')).toMatchObject({ kind: "service", name: "auth-api" });
+    expect(readVerifyWarning('publishes "auth.Ended", which matches no event of its own in the catalog; name it under `events`')).toMatchObject({ kind: "event", name: "auth.Ended" });
+    expect(readVerifyWarning('consumes "auth.Ended", which matches no event in the catalog; name it under `events`')).toMatchObject({ kind: "event", name: "auth.Ended" });
+    expect(readVerifyWarning("answers on GET /v1/health, which no interface it provides declares; the flow opens on the route rather than an operation")).toMatchObject({ kind: "route", name: "GET /v1/health" });
+    expect(readVerifyWarning("calls GET /v1/profiles/42 on profile, which no service in the catalog answers on; the hop is unresolved")).toMatchObject({ kind: "call", name: "GET /v1/profiles/42" });
+    expect(readVerifyWarning('publishes "a" on "x", but the catalog says it goes on "y"')).toMatchObject({ kind: "channel" });
+    expect(readVerifyWarning("something else")).toEqual({ kind: "other", message: "something else" });
+  });
+});
+
+describe("what a trial run said about the recording", () => {
+  const roots = [];
+  afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+  it("lists the flows the recording showed first, with what it raised and added", () => {
+    const snapshot = mkdtempSync(join(tmpdir(), "portolan-trace-trial-"));
+    roots.push(snapshot);
+    mkdirSync(join(snapshot, "examples/auth/portolan"), { recursive: true });
+    const recording = "telemetry/recordings/2026-09-12-login.jsonl";
+    const named = `examples/auth/${recording}`;
+    writeFileSync(join(snapshot, "examples/auth/portolan/observed.json"), JSON.stringify({
+      flows: [
+        {
+          id: "flow.auth-login", slug: "auth-login", name: "Login", owner: "auth", participants: [],
+          steps: [
+            { type: "step", id: "s1", status: "verified", seen: { traces: 1 } },
+            { type: "step", id: "s2", status: "declared" },
+            { type: "alt", id: "alt3", branches: [{ title: "blocked", steps: [{ type: "step", id: "seen1", status: "unresolved", seen: { traces: 1 } }] }] },
+          ],
+          examples: [{ id: `${recording}#t1`, recording: named, traceId: "t1", durationMs: 1, steps: [{ step: "s1", durationMs: 1 }, { step: "seen1", durationMs: 1 }] }],
+        },
+        {
+          id: "flow.observed-auth-get-v1-health", slug: "observed-auth-get-v1-health", name: "Observed: GET /v1/health", owner: "auth", participants: [],
+          steps: [{ type: "step", id: "s1", status: "verified", seen: { traces: 3 } }],
+          examples: [{ id: "telemetry/traces.jsonl#t9", recording: "examples/auth/telemetry/traces.jsonl", traceId: "t9", durationMs: 1, steps: [] }],
+        },
+      ],
+    }));
+    const step = { plugin: "otel", in: "examples/auth", out: "examples/auth/portolan", options: { traces: ["telemetry/recordings/*.jsonl"], out: "observed.json", services: { "auth-api": "auth.auth" } } };
+    const events = [
+      { type: "step-finished", phase: "extract", plugin: "go-domain", output: "examples/auth/portolan", status: "ok", warnings: ["ignored"] },
+      { type: "step-finished", phase: "verify", plugin: "otel", input: "examples/auth", output: "examples/auth/portolan", status: "warning", warnings: ['spans from service.name "risk" match no service in the catalog; name it under `services` to say which one it is'] },
+    ];
+
+    const summary = summarizeTraceTrial(snapshot, { projectId: "auth", root: "examples/auth", recording, step, stepAdded: true, stepChange: "widened", spans: 7 }, events);
+
+    expect(summary).toMatchObject({ project: "auth", recording, stepAdded: true, stepChange: "widened", status: "warning", spans: 7, mappings: { services: { "auth-api": "auth.auth" }, events: {}, routes: {} } });
+    expect(summary.warnings).toEqual([{ kind: "service", name: "risk", message: events[1].warnings[0] }]);
+    expect(summary.flows.map((flow) => flow.slug)).toEqual(["auth-login", "observed-auth-get-v1-health"]);
+    expect(summary.flows[0]).toMatchObject({ kind: "declared", inRecording: true, traces: 1, verified: 1, unresolved: 1, added: 1, shown: 2, steps: 3, examples: 1 });
+    expect(summary.flows[1]).toMatchObject({ kind: "observed", inRecording: false, traces: 0, verified: 1, added: 0 });
+  });
+
+  it("is a failed, empty summary when the verifier wrote nothing", () => {
+    const snapshot = mkdtempSync(join(tmpdir(), "portolan-trace-trial-"));
+    roots.push(snapshot);
+    const step = { plugin: "otel", in: "x", out: "x/portolan", options: { traces: [] } };
+    const summary = summarizeTraceTrial(snapshot, { projectId: "p", root: "x", recording: "telemetry/recordings/a.jsonl", step, stepAdded: false, spans: 1 }, []);
+    expect(summary).toMatchObject({ status: "failed", flows: [], warnings: [] });
+  });
+});

package/scripts/warning-policy.mjs

@@ -0,0 +1,167 @@
+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", /\bno 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|it)\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.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 .+\btopic (?:generator could not be resolved|unresolved)\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("messaging.unresolved-queue", /\bqueue of .+ could not be resolved\b/i, "warning", "Use a literal, constant, configuration default, constructor argument, or visible caller argument for the queue."),
+  rule("terraform.unresolved-name", /\b(?:could not be resolved to a literal, a variable default, a local or a module argument|is named with \w+_prefix, so its name is decided at apply time|sets no \w+, so its name is decided at apply time)\b/i, "warning", "Name the resource with a literal, a variable default, a local or a module argument so the catalog can address it."),
+  rule("terraform.name-at-apply-time", /\bis `[^`]*`, with .+ decided at apply time\b/i, "info", "The literal part of the name is listed; the rest is filled when Terraform applies."),
+  rule("terraform.unresolved-reference", /\bcould not be followed to (?:a queue, a table or a stream|an? \w+(?: \w+)*) declared here\b/i, "warning", "Reference the resource by its Terraform address, or declare it in this module."),
+  rule("terraform.module-skipped", /\bmodule ".+" (?:comes from|calls) .+ and is not read\b/i, "info", "Vendor the module under the input root to have its resources read."),
+  rule("terraform.not-read", /\bis not read: .+ is not part of this reader yet\b/i, "info", "This AWS product is not modelled yet; the resource is listed so the gap is visible."),
+  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|read) \(offline\)/i, "info", "Regenerate with network access when the vendored copy must be refreshed."),
+  rule("source.unreachable", /\bnot (?:fetched|read) \((?!offline\))/i, "warning", "The far end could not be reached and the committed copy was used; check the server and the credential, then regenerate."),
+  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,93 @@
+import { describe, expect, it } from "vitest";
+import { classifyWarning, diagnoseWarnings, warningPolicyProblems } from "./warning-policy.mjs";
+
+describe("warning CEL policies", () => {
+  const warnings = [
+    "aviacore-api: no operationId on 53 of 53 operations; listed by verb and path: GET /a, POST /b and 51 more",
+    "aviasupp-api: no operationId on 2 of 9 operations; listed by verb and path: POST /book, POST /cancel",
+  ];
+
+  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"),
+    ]);
+  });
+});
+
+describe("warning classification", () => {
+  // Each message is worded the way the plugin that emits it words it today
+  // (grep the plugin for the phrase before editing a rule), so a policy that
+  // names the rule keeps matching during generation.
+  const emitted = [
+    ["openapi", "aviacore-api: no operationId on 53 of 53 operations; listed by verb and path: GET /a, POST /b and 51 more", "openapi.missing-operation-id"],
+    ["go-domain", "calls ledger.v1 and the manifest names no peer for that package; add it under `peers` to say which service answers, or under `externals` when the far end is outside the estate, until then the calls are unresolved", "catalog.unmapped-proto-peer"],
+    ["java-domain", "calls ledger.v1 and the manifest names no peer for it; add it under `peers` to say which service answers, or under `externals` when the far end is outside the estate, until then the calls are unresolved", "catalog.unmapped-proto-peer"],
+    ["go-domain", "internal/app: port `clock Clock` is neither a domain port nor a use case; its calls are left out of the flow", "flow.unknown-port"],
+    ["rust-domain", "src/app.rs: port `clock: Clock` is neither a domain port, a use case nor a client; its calls are left out of the flow", "flow.unknown-port"],
+    ["watermill", "internal/bus/router.go:12:3: Watermill handler orders is registered on topic `cfg.Topic`, which this reader cannot resolve to a literal, a constant, a config default or a caller's argument; the handler is kept with its topic unresolved", "watermill.unresolved-topic"],
+    ["watermill", "internal/bus/cqrs.go:40:5: Watermill CQRS handler topic generator could not be resolved", "watermill.unresolved-topic"],
+    ["go-nats", "internal/pub.go:8:2: subject of Publish could not be resolved to a literal, a constant, a config default or a caller's argument", "messaging.unresolved-subject"],
+    ["go-sqs", "internal/relay.go:15:2: queue of SendMessage could not be resolved to a literal, a constant, a config default, a constructor's argument or a caller's argument", "messaging.unresolved-queue"],
+    ["terraform", "deploy/queues.tf:12: name of aws_sqs_queue.opaque could not be resolved to a literal, a variable default, a local or a module argument", "terraform.unresolved-name"],
+    ["terraform", "deploy/queues.tf:40: aws_sqs_queue.generated is named with name_prefix, so its name is decided at apply time and is not read", "terraform.unresolved-name"],
+    ["terraform", "deploy/lambda.tf:52: aws_lambda_function.unnamed sets no function_name, so its name is decided at apply time and is not read", "terraform.unresolved-name"],
+    ["terraform", "deploy/data.tf:80: name of aws_sqs_queue.per_account is `fulfillment-events-{account_id}`, with {account_id} decided at apply time", "terraform.name-at-apply-time"],
+    ["terraform", "deploy/lambda.tf:30: event_source_arn of aws_lambda_event_source_mapping.in could not be followed to a queue, a table or a stream declared here", "terraform.unresolved-reference"],
+    ["terraform", "deploy/lambda.tf:30: function_name of aws_lambda_event_source_mapping.in could not be followed to an aws_lambda_function declared here", "terraform.unresolved-reference"],
+    ["terraform", "deploy/main.tf:36: module \"vpc\" comes from terraform-aws-modules/vpc/aws, which is not in this tree, and is not read", "terraform.module-skipped"],
+    ["terraform", "deploy/data.tf:69: aws_kinesis_stream.clicks is not read: Kinesis is not part of this reader yet", "terraform.not-read"],
+    ["git", "github.com/acme/ledger: not fetched (offline); the copy committed in this repository is used unchanged", "source.offline-cache"],
+    ["markdown", "flow.checkout step \"pay\" is unresolved: POST /pay", "flow.unresolved-step"],
+    ["rust-domain", "Confirm: src/policy.rs: Confirm.handle reacts to the message named \"payment.authorized\", which no event this repository declares is called; the step is unresolved", "flow.unknown-event"],
+  ];
+
+  it.each(emitted)("classifies what %s emits to a stable rule", (plugin, message, rule) => {
+    expect(classifyWarning(plugin, message).rule).toBe(rule);
+  });
+
+  it("no longer carries a rule for a warning no plugin emits", () => {
+    const message = "billing/records: no model called Records, and 2 models to choose from: name the root in the aggregates option";
+    expect(classifyWarning("django-domain", message).rule).toMatch(/^plugin\.django-domain\.other-/);
+  });
+});

package/src/app/Breadcrumbs.test.ts

@@ -10,6 +10,9 @@ describe("crumbsFor", () => {
     expect(crumbsFor("/language")).toEqual([
       { label: "language", to: "/language" },
     ]);
+    expect(crumbsFor("/plugins")).toEqual([
+      { label: "plugins", to: "/plugins" },
+    ]);
     expect(crumbsFor("/problems")).toEqual([
       { label: "problems", to: "/problems" },
     ]);

package/src/app/Breadcrumbs.tsx

@@ -85,6 +85,9 @@ export function crumbsFor(pathname: string): Crumb[] {
   if (parts[0] === "problems")
     return [{ label: "problems", to: paths.problems() }];
 
+  if (parts[0] === "plugins")
+    return [{ label: "plugins", to: paths.plugins() }];
+
   if (parts[0] === "registry") {
     const crumbs: Crumb[] = [{ label: "registry", to: paths.registry() }];
     const slug = parts[1];

package/src/app/CatalogApp.tsx

@@ -18,6 +18,7 @@ import { FlowDetail } from "../pages/FlowDetail";
 import { FlowIndex } from "../pages/FlowIndex";
 import { AdrIndex } from "../pages/AdrIndex";
 import { Language } from "../pages/Language";
+import { PluginIndex } from "../pages/PluginIndex";
 import { AdrDetail } from "../pages/AdrDetail";
 import { Overview } from "../pages/Overview";
 import { ContextMap } from "../pages/ContextMap";
@@ -119,6 +120,7 @@ function AppRoutes({
       />
       <Route path="/adrs" element={<AdrIndex />} />
       <Route path="/language" element={<Language />} />
+      <Route path="/plugins" element={<PluginIndex />} />
       <Route path="/adrs/:adr" element={<AdrDetail />} />
       <Route path="/problems" element={<Problems />} />
       <Route path="/settings/*" element={<Settings />} />

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={