@shortlink-org/portolan 0.2.4 → 0.4.0

package/scripts/plugins-fresh.test.mjs

@@ -0,0 +1,64 @@
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { newestMtime, pluginsFresh } from "./plugins-fresh.mjs";
+
+const roots = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+function at(path, seconds) {
+  utimesSync(path, seconds, seconds);
+}
+
+/** A workspace with a built wasm and Java classes, all stamped at `built`, over sources stamped at `source`. */
+function workspace({ source, built }) {
+  const root = mkdtempSync(join(tmpdir(), "portolan-fresh-"));
+  roots.push(root);
+  for (const dir of ["plugins/verify-otel", "plugins/extract-java/src/org", "plugins/extract-java/build/org", "catalog", "plugin"]) mkdirSync(join(root, dir), { recursive: true });
+  const files = {
+    "go.mod": source, "plugins/verify-otel/verify.go": source, "catalog/model.go": source, "plugin/protocol.go": source,
+    "plugins/extract-java/src/org/Main.java": source,
+    "plugins/portolan-go.wasm": built, "plugins/extract-java/build/org/Main.class": built,
+  };
+  for (const [name, stamp] of Object.entries(files)) {
+    writeFileSync(join(root, name), "x");
+    at(join(root, name), stamp);
+  }
+  return root;
+}
+
+describe("whether the built plugins are newer than their sources", () => {
+  it("is yes when every artefact is at least as new as every source", () => {
+    expect(pluginsFresh(workspace({ source: 1000, built: 2000 }))).toBe(true);
+    expect(pluginsFresh(workspace({ source: 2000, built: 2000 }))).toBe(true);
+  });
+
+  it("is no when a Go source, a Java source, or go.mod is newer, or an artefact is missing", () => {
+    const go = workspace({ source: 1000, built: 2000 });
+    at(join(go, "catalog/model.go"), 3000);
+    expect(pluginsFresh(go)).toBe(false);
+
+    const java = workspace({ source: 1000, built: 2000 });
+    at(join(java, "plugins/extract-java/src/org/Main.java"), 3000);
+    expect(pluginsFresh(java)).toBe(false);
+
+    const mod = workspace({ source: 1000, built: 2000 });
+    at(join(mod, "go.mod"), 3000);
+    expect(pluginsFresh(mod)).toBe(false);
+
+    const missing = workspace({ source: 1000, built: 2000 });
+    rmSync(join(missing, "plugins/portolan-go.wasm"));
+    expect(pluginsFresh(missing)).toBe(false);
+  });
+
+  it("leaves a plugin's own build output and test data out of the sources", () => {
+    const root = workspace({ source: 1000, built: 2000 });
+    mkdirSync(join(root, "plugins/extract-rust/target"), { recursive: true });
+    writeFileSync(join(root, "plugins/extract-rust/target/out.go"), "x");
+    at(join(root, "plugins/extract-rust/target/out.go"), 5000);
+    expect(pluginsFresh(root)).toBe(true);
+    expect(newestMtime(join(root, "plugins"), (path) => path.endsWith(".go"))).toBe(1000 * 1000);
+  });
+});

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";
 
@@ -27,8 +27,11 @@ if (!plugin?.process) {
 const command = plugin.process.command;
 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"), []);
+const prebuilt = command === "cargo" ? prebuiltCargoBinary(args) : "";
+if (prebuilt) {
+  run(prebuilt, []);
+} else if (command === "go") {
+  buildAndRunGo(args);
 } else {
   if (command === "cargo") {
     process.env.CARGO_TARGET_DIR = resolve(workspace, ".portolan", "bin", "cargo");
@@ -40,9 +43,61 @@ 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) {
+  // `go run [build flags] <package> [args]`: the build flags (-mod=mod, -tags)
+  // belong to the build, the package is what is built, the rest is the
+  // sidecar's own command line.
+  const flags = [];
+  let at = 1;
+  while (argv[0] === "run" && typeof argv[at] === "string" && argv[at].startsWith("-")) flags.push(argv[at++]);
+  const pkg = argv[at];
+  if (argv[0] !== "run" || typeof pkg !== "string" || !pkg) {
+    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=mod", ...flags.filter((flag) => flag !== "-mod=mod"), "-o", executable, pkg], {
+    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(at + 1));
+}
+
+// A Rust plugin already built in release mode under its own crate directory,
+// `plugins/extract-rust/target/release/portolan-extract-rust`, is run as it
+// is; the crate is named after its directory, which is what the manifest
+// path names.
+function prebuiltCargoBinary(argv) {
+  const manifest = argv[argv.indexOf("--manifest-path") + 1];
+  if (!manifest || argv.indexOf("--manifest-path") < 0) return "";
+  const crate = dirname(manifest).split("/").pop();
+  const binary = resolve(installRoot, dirname(manifest), "target", "release", `portolan-${crate}`);
+  return existsSync(binary) ? binary : "";
+}
+
 function resolveArgument(executable, index) {
   if (["node", "python", "python3"].includes(executable)) return index === 0;
   if (executable === "java") return index === 1;
+  if (executable === "dotnet") return index === 0;
   if (executable === "cargo") return index === 3;
   return false;
 }

package/scripts/schema.mjs

@@ -1,8 +1,9 @@
 // Composes the JSON Schema for portolan.json out of what the plugins say about
 // themselves.
 //
-//   node scripts/schema.mjs            write schema/portolan.schema.json
-//   node scripts/schema.mjs --check    fail if the schema on disk is not what
+//   node scripts/schema.mjs            write schema/portolan.schema.json and
+//                                      src/lib/plugin-index.json
+//   node scripts/schema.mjs --check    fail if either file on disk is not what
 //                                      the plugins describe now
 //
 // The manifest tells each plugin the things its source cannot carry - which
@@ -19,8 +20,14 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 
 import { describePlugin } from "./plugin-host.mjs";
+import { RULE_ID, SEVERITIES, SUBJECT_NAMES, SUBJECTS } from "../src/lib/problem-rules-cel.mjs";
+
+// The built-in problem rules, so the schema can say which ids are switches
+// and which must carry a whole rule.
+const BUILTIN_RULES = JSON.parse(readFileSync("rules/builtin.json", "utf8"));
 
 const OUT = "schema/portolan.schema.json";
+const INDEX = "src/lib/plugin-index.json";
 
 const check = process.argv.includes("--check");
 // Bootstrap exception: this command produces the schema that loadManifest
@@ -51,25 +58,65 @@ for (const plugin of manifest.plugins ?? []) {
 }
 
 const composed = `${JSON.stringify(compose(), null, 2)}\n`;
+const index = `${JSON.stringify(pluginIndex(), null, 2)}\n`;
+
+let stale = false;
+for (const [path, contents, directory] of [
+  [OUT, composed, "schema"],
+  [INDEX, index, "src/lib"],
+]) {
+  let current = null;
+  try {
+    current = readFileSync(path, "utf8");
+  } catch {
+    // Absent, which is the same as out of date.
+  }
 
-let current = null;
-try {
-  current = readFileSync(OUT, "utf8");
-} catch {
-  // Absent, which is the same as out of date.
+  if (current === contents) {
+    console.log(`${path}: up to date`);
+  } else if (check) {
+    console.error(
+      `${path} is ${current === null ? "missing" : "out of date"}. Run \`npm run schema\`.`,
+    );
+    stale = true;
+  } else {
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(path, contents);
+    console.log(`${path}: written from ${described.size} plugin${described.size === 1 ? "" : "s"}`);
+  }
 }
+if (stale) process.exit(1);
 
-if (current === composed) {
-  console.log(`${OUT}: up to date`);
-} else if (check) {
-  console.error(
-    `${OUT} is ${current === null ? "missing" : "out of date"}. Run \`npm run schema\`.`,
-  );
-  process.exit(1);
-} else {
-  mkdirSync("schema", { recursive: true });
-  writeFileSync(OUT, composed);
-  console.log(`${OUT}: written from ${described.size} plugin${described.size === 1 ? "" : "s"}`);
+/**
+ * The plugin index: every plugin the package ships, as it describes itself,
+ * with how the manifest runs it. The site's /plugins page and the landing's
+ * list of inputs are rendered from this, so a plugin added to portolan.json
+ * appears there without anyone writing it down twice. Kept under src/ rather
+ * than beside the schema because the staged site copies src/ and nothing else.
+ */
+function pluginIndex() {
+  const out = [];
+  for (const plugin of manifest.plugins ?? []) {
+    const descriptor = described.get(plugin.name);
+    if (!descriptor) continue;
+    out.push({
+      name: plugin.name,
+      plugin: descriptor.name,
+      summary: descriptor.summary,
+      category: descriptor.category,
+      phases: descriptor.phases,
+      ...(descriptor.needs?.length ? { needs: descriptor.needs } : {}),
+      runtime: plugin.wasm ? "wasm" : plugin.host ? "host" : "process",
+      // The toolchain a process plugin asks the build for; the sandboxed
+      // module and the host's own code ask for nothing.
+      ...(plugin.process ? { toolchain: plugin.process.command } : {}),
+      source: plugin.host
+        ? `scripts/host-plugins/${plugin.host}.mjs`
+        : `plugins/${descriptor.name}`,
+      options: descriptor.options ?? {},
+    });
+  }
+  return out;
 }
 
 function compose() {
@@ -116,6 +163,20 @@ 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.",
+      },
+      problemRules: {
+        type: "array",
+        maxItems: 200,
+        items: { $ref: "#/$defs/problemRule" },
+        description:
+          "The rules the Problems page applies. An entry naming a built-in rule (rules/builtin.json) switches it off or re-grades it, with a reason; any other id is a rule of its own, written in CEL over one subject. Expressions are type-checked when the manifest is read and run in the page over the merged catalog.",
+      },
       plugins: {
         type: "array",
         items: { $ref: "#/$defs/plugin" },
@@ -139,6 +200,29 @@ function compose() {
       },
     },
     $defs: {
+      problemRule: problemRuleSchema(),
+      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,
@@ -244,7 +328,7 @@ function compose() {
             description: "What the steps below call this plugin. It need not be the plugin's own name.",
           },
           host: {
-            enum: ["fetch-git", "fetch-bsr", "fetch-csr"],
+            enum: ["fetch-git", "fetch-bsr", "fetch-csr", "fetch-k8s", "fetch-argocd"],
             description:
               "A plugin the host runs inside its own process, because it needs a socket or a git binary (portolan.0008). Only the ones shipped with Portolan can be named.",
           },
@@ -371,3 +455,67 @@ function fail(message) {
   console.error(`portolan schema: ${message}`);
   process.exit(1);
 }
+
+/**
+ * One entry of `problemRules`. Two shapes under one id field: a built-in id
+ * may only be switched, re-graded and explained; any other id is a whole
+ * rule, over one subject, with the expressions the page runs.
+ */
+function problemRuleSchema() {
+  const builtinIds = BUILTIN_RULES.map((rule) => rule.id);
+  const subjectFields = SUBJECT_NAMES.map(
+    (name) => `${name}: ${Object.keys(SUBJECTS[name].schema).join(", ")}`,
+  ).join("; ");
+  const expression = (returns, what) => ({
+    type: "string",
+    minLength: 1,
+    maxLength: 2000,
+    description: `${what} CEL returning ${returns}, over the subject named by \`over\` and \`estate\` (services, contexts, stores, channels, externals). Fields by subject: ${subjectFields}.`,
+  });
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["id"],
+    properties: {
+      id: {
+        type: "string",
+        pattern: RULE_ID.source,
+        description: `The rule. One of the built-in ids - ${builtinIds.join(", ")} - to switch or re-grade that rule; any other id declares a rule of its own.`,
+      },
+      enabled: {
+        type: "boolean",
+        default: true,
+        description: "Whether the rule produces rows. A disabled rule needs a reason and stays listed on the Settings page.",
+      },
+      severity: {
+        enum: SEVERITIES,
+        description: "How wrong a row of this rule is. For a built-in rule this replaces the severity its passport was written with.",
+      },
+      reason: {
+        type: "string",
+        minLength: 1,
+        description: "Why the rule is off or re-graded, or, for a rule of your own, why the estate holds it.",
+      },
+      over: {
+        enum: SUBJECT_NAMES,
+        description: "What one row of the rule is about, and what `when` and `message` read.",
+      },
+      when: expression("bool", "The condition: a row exists for every subject where it holds."),
+      message: expression("string", "The note on the row."),
+      peer: expression("string", "The row's far end, when it has one; a service, event or table id links to its page."),
+      title: { type: "string", minLength: 1, description: "The rule's name on the Settings page." },
+      note: { type: "string", minLength: 1, description: "The short words on every row of the rule; the title when absent." },
+      description: { type: "string", description: "What the rule checks and why it matters." },
+      action: { type: "string", description: "What a reader does about a row." },
+    },
+    if: { properties: { id: { enum: builtinIds } } },
+    then: {
+      not: {
+        anyOf: ["over", "when", "message", "peer", "title", "note", "description", "action"].map((key) => ({
+          required: [key],
+        })),
+      },
+    },
+    else: { required: ["over", "when", "message", "title"] },
+  };
+}