@shortlink-org/portolan 0.3.0 → 0.4.0

package/scripts/local-api.mjs

@@ -20,8 +20,11 @@ import { basename, dirname, join, posix, relative, resolve, sep } from "node:pat
 
 import { loadManifest, readManifest, readManifestText } from "./manifest.mjs";
 import { builtinPluginNames } from "./builtin-plugins.mjs";
+import { pluginsFresh } from "./plugins-fresh.mjs";
 import { djangoAggregateCandidates } from "../src/lib/django-aggregates.mjs";
 import { installDeliveryPreset, planDeliveryPreset, publicDeliveryPreset } from "./delivery-presets.mjs";
+import { formatLike } from "./json-format.mjs";
+import { UPLOAD_LIMIT, checkRecording, manifestWithTraceStep, recordingPath, stepWithMappings, summarizeTraceTrial, traceStepFor } from "./trace-trials.mjs";
 import {
   discoverProject,
   matches,
@@ -311,7 +314,16 @@ function pluginOptions(plugin, project, detectedOptions = {}) {
       out: "project.json",
     };
   }
-  if (["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin)) {
+  if (plugin === "php-ddd" || plugin === "csharp-ddd") {
+    // The tree names its own contexts and services; the manifest only says
+    // where the code lives and how core it is.
+    return {
+      ...(project.repository ? { repo: repositoryParts(project.repository).web } : {}),
+      ...(detectedOptions?.classification ? { classification: detectedOptions.classification } : {}),
+      out: "domain.json",
+    };
+  }
+  if (["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain"].includes(plugin)) {
     return { ...common, ...(project.repository ? { repo: repositoryParts(project.repository).web } : {}), ...detectedOptions, serviceName: project.name, out: "domain.json" };
   }
   if (plugin === "sql") return { ...common, store: "pg", ...detectedOptions, out: "stores.json" };
@@ -431,7 +443,7 @@ export function planProject(workspace, manifest, request) {
   };
   const out = posix.join(finalRoot, "portolan");
   const detectionByPlugin = new Map(discovery.detections.map((item) => [item.plugin, item]));
-  const hasDomainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin));
+  const hasDomainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain", "php-ddd", "csharp-ddd"].includes(plugin));
   const projectDetectionOptions = {
     groupKind: splitDeployables ? "system" : hasDomainModel ? "bounded-context" : "system",
     ...(hasDomainModel ? { componentKind: "service" } : {}),
@@ -456,7 +468,7 @@ export function planProject(workspace, manifest, request) {
     if (!splitDeployables) {
       const options = plugin === "project"
         ? projectDetectionOptions
-        : ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin)
+        : ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain", "php-ddd", "csharp-ddd"].includes(plugin)
           ? domainDetectionOptions(plugin)
           : detectionByPlugin.get(plugin)?.options;
       return [{ plugin, in: finalRoot, out, options: pluginOptions(plugin, project, options) }];
@@ -605,11 +617,19 @@ function projectRequestPlan(workspace, manifest, request) {
   return { base, plan, starter };
 }
 
+/**
+ * Writes the manifest in the style the file already has: an unchanged
+ * subtree is copied byte for byte, a changed array keeps the shape its old
+ * self had, so that what the page changed is what the diff shows.
+ */
 export function writeManifest(path, manifest) {
+  let before = "";
+  try { before = readFileSync(path, "utf8"); } catch {}
+  const text = before.trim() ? formatLike(before.replace(/\n$/, ""), manifest) : JSON.stringify(manifest, null, 2);
   const staging = mkdtempSync(join(dirname(path), ".portolan-manifest-"));
   const temp = join(staging, "portolan.json");
   try {
-    writeFileSync(temp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+    writeFileSync(temp, `${text}\n`, { flag: "wx" });
     const validation = loadManifest(temp);
     if (validation.problems.length) throw new Error(validation.problems.join("\n"));
     renameSync(temp, path);
@@ -664,6 +684,40 @@ export function saveDjangoAggregates(workspace, request) {
   return { saved: request.selections.length };
 }
 
+/**
+ * The manifest's `problemRules` as written, with a revision of the whole file:
+ * a save quotes it, so two pages editing the rules cannot overwrite each
+ * other, and neither can a hand edit made while the page was open.
+ */
+export function problemRulesState(workspace) {
+  const path = join(workspace, "portolan.json");
+  const text = readFileSync(path, "utf8");
+  const manifest = readManifestText(text, path);
+  return {
+    revision: createHash("sha256").update(text).digest("hex"),
+    rules: Array.isArray(manifest.problemRules) ? manifest.problemRules : [],
+  };
+}
+
+/**
+ * Replaces `problemRules`. The expressions are type-checked and the shape is
+ * checked against the schema by writeManifest, through the same loader gen
+ * uses, so a rule the page accepts is a rule gen accepts.
+ */
+export function saveProblemRules(workspace, request) {
+  const current = problemRulesState(workspace);
+  if (request?.revision !== current.revision) {
+    throw new Error("portolan.json has changed since the rules were read. Reload the page and try again.");
+  }
+  if (!Array.isArray(request.rules)) throw new Error("rules must be an array.");
+  const path = join(workspace, "portolan.json");
+  const manifest = readManifest(path);
+  if (request.rules.length) manifest.problemRules = request.rules;
+  else delete manifest.problemRules;
+  writeManifest(path, manifest);
+  return problemRulesState(workspace);
+}
+
 export function writeProject(workspace, request) {
   const manifestPath = join(workspace, "portolan.json");
   const before = readFileSync(manifestPath, "utf8");
@@ -762,6 +816,18 @@ async function body(req) {
   return text ? JSON.parse(text) : {};
 }
 
+/** The bytes of an upload, as they came, up to a limit that is said out loud. */
+async function rawBody(req, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) throw new Error(`The upload is larger than ${Math.round(limit / 1024 / 1024)} MB.`);
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
 function localRequest(req) {
   const address = req.socket.remoteAddress ?? "";
   const localAddress = address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
@@ -993,6 +1059,65 @@ function prepareProjectTrial(workspace, request) {
   return { ...snapshot, fingerprint, plan };
 }
 
+/**
+ * A recording uploaded from the page, staged where the verifier will read it
+ * - the project's recordings directory, in a snapshot of the workspace - with
+ * the verify step that reads it, added to the snapshot's manifest when the
+ * project has none. The workspace itself is not touched until the trial is
+ * applied.
+ */
+function prepareTraceTrial(workspace, { projectId, name, content }) {
+  const manifest = readManifest(join(workspace, "portolan.json"));
+  const project = (manifest.projects ?? []).find((candidate) => candidate.id === projectId);
+  if (!project) throw new Error(`Project "${projectId}" does not exist. Add the project before recording it.`);
+  const known = builtinPluginNames().has("otel") || (manifest.plugins ?? []).some((plugin) => plugin.name === "otel");
+  if (!known) throw new Error("The otel verifier is not available in this installation.");
+  const { batches, spans } = checkRecording(content);
+  const recording = recordingPath(name, { taken: (candidate) => lstatExists(join(workspace, project.root, candidate)) });
+  const fingerprint = workspaceFingerprint(workspace);
+  const snapshot = snapshotWorkspace(workspace);
+  if (workspaceFingerprint(workspace) !== fingerprint) {
+    rmSync(snapshot.holder, { recursive: true, force: true });
+    throw new Error("Files changed while the trial workspace was being created. Try again.");
+  }
+  const target = join(snapshot.snapshot, project.root, recording);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  const next = manifestWithTraceStep(manifest, project);
+  if (next.changed) writeManifest(join(snapshot.snapshot, "portolan.json"), next.manifest);
+  const trace = { projectId, root: project.root, recording, step: next.step, stepAdded: next.changed, stepChange: next.change, batches, spans, content };
+  return { ...snapshot, fingerprint, trace };
+}
+
+/**
+ * The recording written beside the project, and the manifest with the step
+ * that reads it and the names the page mapped. Undoable the way a project
+ * is: the manifest before is remembered for a while.
+ */
+function applyTraceTrial(workspace, trial, { services, events, routes } = {}) {
+  const manifestPath = join(workspace, "portolan.json");
+  const before = readFileSync(manifestPath, "utf8");
+  const manifest = readManifestText(before, manifestPath);
+  const project = (manifest.projects ?? []).find((candidate) => candidate.id === trial.trace.projectId);
+  if (!project) throw new Error(`Project "${trial.trace.projectId}" no longer exists.`);
+  const target = join(workspace, project.root, trial.trace.recording);
+  if (lstatExists(target)) throw new Error(`${posix.join(project.root, trial.trace.recording)} appeared while the trial ran. Run it again.`);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, trial.trace.content, { flag: "wx" });
+  const next = manifestWithTraceStep(manifest, project);
+  const found = traceStepFor(next.manifest, project);
+  const mapped = stepWithMappings(found.step, { services, events, routes });
+  const changed = next.changed || JSON.stringify(mapped) !== JSON.stringify(found.step);
+  let undoToken = null;
+  if (changed) {
+    const verify = [...next.manifest.verify];
+    verify[found.index] = mapped;
+    writeManifest(manifestPath, { ...next.manifest, verify });
+    undoToken = rememberManifestUndo(workspace, before, readFileSync(manifestPath, "utf8"));
+  }
+  return { recording: posix.join(project.root, trial.trace.recording), project: project.id, stepAdded: next.changed, manifestChanged: changed, undoToken };
+}
+
 function freeLocalPort() {
   return new Promise((resolvePort, reject) => {
     const server = createNetServer();
@@ -1053,9 +1178,31 @@ async function startProjectPreview(job) {
   return job.previewUrl;
 }
 
+/**
+ * Rebuilds src/likec4/generated.jsx from likec4/ in the workspace, the way
+ * `npm run likec4:gen` does before `dev`. Said in the run's log either way;
+ * a bundle that fails to build leaves the last one in place.
+ */
+function refreshLikeC4Bundle(job) {
+  return new Promise((done) => {
+    const bin = join(job.runRoot, "node_modules/likec4/bin/likec4.mjs");
+    if (!lstatExists(bin)) return done();
+    emit(job, { type: "log", stream: "stdout", message: "likec4 → src/likec4/generated.jsx" });
+    const child = spawn(process.execPath, [bin, "gen", "react", "likec4", "-o", "src/likec4/generated.jsx", "--no-use-dot"], { cwd: job.runRoot, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    child.stdout.on("data", (chunk) => { output += chunk; });
+    child.stderr.on("data", (chunk) => { output += chunk; });
+    child.on("error", (error) => { emit(job, { type: "log", stream: "stderr", message: `likec4: ${error.message}` }); done(); });
+    child.on("close", (code) => {
+      if (code !== 0) emit(job, { type: "log", stream: "stderr", message: `likec4 gen react exited with ${code}:\n${output.trim()}` });
+      done();
+    });
+  });
+}
+
 function startJob(workspace, mode, approvedPreview, preparedTrial) {
   const id = randomUUID();
-  const preview = mode === "preview" || mode === "project-preview";
+  const preview = mode === "preview" || mode === "project-preview" || mode === "trace-preview";
   const fingerprint = preparedTrial?.fingerprint ?? (preview ? workspaceFingerprint(workspace) : approvedPreview?.fingerprint);
   const snapshot = preparedTrial ?? (preview ? snapshotWorkspace(workspace) : null);
   if (preview && !preparedTrial && workspaceFingerprint(workspace) !== fingerprint) {
@@ -1064,13 +1211,21 @@ function startJob(workspace, mode, approvedPreview, preparedTrial) {
   }
   const generatedAt = preview ? new Date().toISOString() : approvedPreview?.generatedAt;
   const gitAuth = gitAuthEnvironment();
-  const job = { id, mode, status: "running", events: [], subscribers: new Set(), buffers: { stdout: "", stderr: "" }, child: null, gitAuth, runRoot: snapshot?.snapshot ?? workspace, snapshotHolder: snapshot?.holder ?? null, fingerprint, generatedAt, projectPlan: preparedTrial?.plan ?? null, projectRequest: preparedTrial ? structuredClone(preparedTrial.request) : null };
+  const job = { id, mode, status: "running", events: [], subscribers: new Set(), buffers: { stdout: "", stderr: "" }, child: null, gitAuth, runRoot: snapshot?.snapshot ?? workspace, snapshotHolder: snapshot?.holder ?? null, fingerprint, generatedAt, projectPlan: preparedTrial?.plan ?? null, projectRequest: preparedTrial?.request ? structuredClone(preparedTrial.request) : null, trace: preparedTrial?.trace ?? null };
   jobs.set(id, job);
   const cli = process.env.PORTOLAN_CLI;
-  const command = cli ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
+  // `npm run gen` builds the plugins first, which a checkout whose plugin
+  // sources have not moved since the last build does not need: the fourth
+  // trial of a recording in a row learns nothing from a minute of javac.
+  // When every artefact is at least as new as its sources the generator
+  // runs on its own; anything doubtful takes the road that builds.
+  const fresh = !cli && pluginsFresh(job.runRoot);
+  const command = cli || fresh ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
   const args = cli
     ? [cli, mode === "check" ? "check" : "generate", "--cwd", job.runRoot]
-    : ["run", mode === "check" ? "gen:check" : "gen"];
+    : fresh
+      ? [join(job.runRoot, "scripts/gen.mjs"), ...(mode === "check" ? ["--check"] : [])]
+      : ["run", mode === "check" ? "gen:check" : "gen"];
   let child;
   try {
     child = spawn(command, args, {
@@ -1107,6 +1262,18 @@ function startJob(workspace, mode, approvedPreview, preparedTrial) {
       }
       catch (cause) { job.status = "failed"; emit(job, { type: "log", stream: "stderr", message: `Could not summarise project trial: ${cause instanceof Error ? cause.message : String(cause)}` }); }
     }
+    if (mode === "trace-preview" && job.status === "ok") {
+      try {
+        job.traceTrial = summarizeTraceTrial(job.runRoot, job.trace, job.events);
+        emit(job, { type: "trace-trial-ready", ...job.traceTrial });
+      }
+      catch (cause) { job.status = "failed"; emit(job, { type: "log", stream: "stderr", message: `Could not summarise the recording: ${cause instanceof Error ? cause.message : String(cause)}` }); }
+    }
+    // The catalog is written, and the pictures' sources with it; the bundle
+    // the dev server draws them from is built once before it starts, so a
+    // write from the page rebuilds it here, or the new flow has no picture
+    // until the next start.
+    if (mode === "write" && job.status === "ok" && !process.env.PORTOLAN_CLI) await refreshLikeC4Bundle(job);
     emit(job, { type: "process-finished", status: job.status, code, signal });
     for (const response of job.subscribers) response.end();
     job.subscribers.clear();
@@ -1140,6 +1307,9 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
           if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/django-aggregates`) {
             return send(res, 200, djangoAggregateProposals(workspace));
           }
+          if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/rules`) {
+            return send(res, 200, problemRulesState(workspace));
+          }
           if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/delivery-presets`) {
             const features = url.searchParams.has("features")
               ? url.searchParams.get("features").split(",").filter(Boolean)
@@ -1159,6 +1329,19 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             req.on("close", () => job.subscribers.delete(res));
             return;
           }
+          if (req.method === "POST" && url.pathname === `${LOCAL_API_PREFIX}/traces/trials` && req.headers["x-portolan-local"] === "1") {
+            // The one upload the local API takes: a recording, as bytes,
+            // named by headers rather than wrapped in JSON.
+            if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
+            const content = await rawBody(req, UPLOAD_LIMIT);
+            const projectId = String(req.headers["x-portolan-project"] ?? "");
+            const name = decodeURIComponent(String(req.headers["x-portolan-filename"] ?? "recording.jsonl"));
+            const prepared = prepareTraceTrial(workspace, { projectId, name, content });
+            let job;
+            try { job = startJob(workspace, "trace-preview", null, prepared); }
+            catch (cause) { rmSync(prepared.holder, { recursive: true, force: true }); throw cause; }
+            return send(res, 202, { runId: job.id, mode: job.mode, recording: posix.join(prepared.trace.root, prepared.trace.recording), project: projectId, stepAdded: prepared.trace.stepAdded, stepChange: prepared.trace.stepChange, spans: prepared.trace.spans });
+          }
           if (req.method !== "POST" || req.headers["content-type"]?.split(";")[0] !== "application/json" || req.headers["x-portolan-local"] !== "1") {
             return send(res, 405, { error: "Use a local JSON request." });
           }
@@ -1167,6 +1350,10 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             if ([...jobs.values()].some((job) => job.status === "running")) throw new Error("Wait for the current generation to finish before saving aggregate roots.");
             return send(res, 200, saveDjangoAggregates(workspace, input));
           }
+          if (url.pathname === `${LOCAL_API_PREFIX}/rules`) {
+            if ([...jobs.values()].some((job) => job.status === "running")) throw new Error("Wait for the current generation to finish before saving rules.");
+            return send(res, 200, saveProblemRules(workspace, input));
+          }
           if (url.pathname === `${LOCAL_API_PREFIX}/delivery-presets/install`) {
             return send(res, 201, installDeliveryPreset(workspace, input));
           }
@@ -1201,6 +1388,27 @@ export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
             disposeProjectTrial(trial);
             return send(res, 200, { runId: trial.id, status: "disposed" });
           }
+          const applyTraceMatch = url.pathname.match(/^\/__portolan\/traces\/trials\/([^/]+)\/apply$/);
+          if (applyTraceMatch) {
+            if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
+            const trial = jobs.get(applyTraceMatch[1]);
+            if (!trial?.trace || trial.status !== "ok" || !trial.traceTrial) return send(res, 409, { error: "Run a successful recording trial before keeping it." });
+            if (trial.applied) return send(res, 409, { error: "This recording was already kept." });
+            if (workspaceFingerprint(workspace) !== trial.fingerprint) return send(res, 409, { error: "Files changed after this trial. Upload the recording again." });
+            const result = applyTraceTrial(workspace, trial, { services: input.services, events: input.events, routes: input.routes });
+            trial.applied = true;
+            const generation = input.generate ? startJob(workspace, "write", trial) : null;
+            return send(res, 201, { ...result, setup: setup(workspace, publicSetupFrom), run: generation ? { runId: generation.id, mode: generation.mode } : null });
+          }
+          const disposeTraceMatch = url.pathname.match(/^\/__portolan\/traces\/trials\/([^/]+)\/dispose$/);
+          if (disposeTraceMatch) {
+            const trial = jobs.get(disposeTraceMatch[1]);
+            if (!trial?.trace) return send(res, 404, { error: "Recording trial not found." });
+            if (trial.status === "running") return send(res, 409, { error: "Cancel the running trial first." });
+            trial.trace.content = null;
+            disposeProjectTrial(trial);
+            return send(res, 200, { runId: trial.id, status: "disposed" });
+          }
           if (url.pathname === `${LOCAL_API_PREFIX}/projects/preview`) {
             const manifest = readManifest(join(workspace, "portolan.json"));
             return send(res, 200, projectRequestPlan(workspace, manifest, input).plan);

package/scripts/local-api.test.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { rmSync } from "node:fs";
 
-import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, readLocalSource, removeProject, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, workspaceFingerprint, writeProject } from "./local-api.mjs";
+import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, problemRulesState, readLocalSource, removeProject, saveProblemRules, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, workspaceFingerprint, writeManifest, writeProject } from "./local-api.mjs";
 import { installDeliveryPreset, planDeliveryPreset, providerFromRemote, publicDeliveryPreset } from "./delivery-presets.mjs";
 
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -48,7 +48,10 @@ describe("local API base path", () => {
   });
 });
 
-describe("local project setup", () => {
+// Each delivery-preset test spawns a dozen git processes; while the whole
+// suite is starting, one spawn takes hundreds of milliseconds, so the
+// default five seconds is a coin flip rather than a limit.
+describe("local project setup", { timeout: 30_000 }, () => {
   it("detects GitHub and GitLab remotes without treating arbitrary hosts as a forge", () => {
     expect(providerFromRemote("git@github.com:acme/shop.git")).toBe("github");
     expect(providerFromRemote("https://gitlab.example.com/acme/shop.git")).toBe("gitlab");
@@ -771,3 +774,86 @@ describe("workspaceFingerprint", () => {
     expect(workspaceFingerprint(root)).toBe(unborn);
   });
 });
+
+describe("writing the manifest", () => {
+  it("keeps the file's own formatting and changes only what changed", () => {
+    const root = workspace();
+    const path = join(root, "portolan.json");
+    const before = [
+      "{",
+      '  "sources": ["data/*.json", "services/*/portolan/*.json"],',
+      '  "projects": [],',
+      '  "plugins": [{ "name": "otel", "process": { "command": "true" } }],',
+      '  "extract": [],',
+      '  "verify": [',
+      "    {",
+      '      "plugin": "otel",',
+      '      "in": "services/billing",',
+      '      "out": "services/billing/portolan",',
+      '      "options": {',
+      '        "traces": [',
+      '          "telemetry/traces.jsonl"',
+      "        ]",
+      "      }",
+      "    }",
+      "  ]",
+      "}",
+      "",
+    ].join("\n");
+    writeFileSync(path, before);
+
+    const manifest = JSON.parse(before);
+    manifest.verify[0].options.traces.push("telemetry/recordings/*.jsonl");
+    writeManifest(path, manifest);
+
+    const after = readFileSync(path, "utf8");
+    expect(JSON.parse(after)).toEqual(manifest);
+    expect(after).toContain('  "sources": ["data/*.json", "services/*/portolan/*.json"],');
+    expect(after).toContain('  "plugins": [{ "name": "otel", "process": { "command": "true" } }],');
+    expect(after).toContain('          "telemetry/traces.jsonl",\n          "telemetry/recordings/*.jsonl"\n        ]');
+    expect(after.endsWith("}\n")).toBe(true);
+  });
+
+  it("still refuses a manifest the schema rejects, and leaves the file as it was", () => {
+    const root = workspace();
+    const path = join(root, "portolan.json");
+    const before = readFileSync(path, "utf8");
+    expect(() => writeManifest(path, { ...JSON.parse(before), verify: [{ plugin: "nope", in: "x", out: "y" }] })).toThrow();
+    expect(readFileSync(path, "utf8")).toBe(before);
+  });
+});
+
+describe("problem rules", () => {
+  it("reads the manifest's rules with a revision, and writes them back through the schema", () => {
+    const root = workspace();
+    const before = problemRulesState(root);
+    expect(before.rules).toEqual([]);
+    expect(before.revision).toMatch(/^[0-9a-f]{64}$/);
+
+    const rules = [
+      { id: "shared-store", enabled: false, reason: "one database by design" },
+      { id: "team.quiet-event", over: "event", severity: "warning", title: "Quiet event", when: "size(event.consumers) == 0", message: "'nothing consumes ' + event.id" },
+    ];
+    const after = saveProblemRules(root, { revision: before.revision, rules });
+    expect(after.rules).toEqual(rules);
+    expect(after.revision).not.toBe(before.revision);
+    expect(JSON.parse(readFileSync(join(root, "portolan.json"), "utf8")).problemRules).toEqual(rules);
+
+    // Emptying the list removes the key, so a manifest that never had one
+    // does not gain an empty array.
+    const emptied = saveProblemRules(root, { revision: after.revision, rules: [] });
+    expect(emptied.rules).toEqual([]);
+    expect(JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"))).not.toHaveProperty("problemRules");
+  });
+
+  it("refuses a stale revision and a rule the type check rejects, and leaves the file alone", () => {
+    const root = workspace();
+    const { revision } = problemRulesState(root);
+    const text = readFileSync(join(root, "portolan.json"), "utf8");
+    expect(() => saveProblemRules(root, { revision: "0".repeat(64), rules: [] })).toThrow(/changed since/);
+    expect(() => saveProblemRules(root, { revision, rules: [{ id: "team.a", over: "event", title: "A", when: "event.nme == 'x'", message: "'m'" }] })).toThrow(/nme/);
+    expect(() => saveProblemRules(root, { revision, rules: [{ id: "rpc", when: "true" }] })).toThrow(/built-in/);
+    expect(() => saveProblemRules(root, { revision, rules: [{ id: "team.b", over: "event", title: "B", when: "true", message: "'m'", extra: 1 }] })).toThrow();
+    expect(readFileSync(join(root, "portolan.json"), "utf8")).toBe(text);
+  });
+});

package/scripts/local-discovery.mjs

@@ -387,6 +387,15 @@ function detectionsFor(root, files) {
   const tsDomain = files.has("package.json") ? laidOutDomainEvidence(root, files, "typescript") : "";
   const rustDomain = files.has("Cargo.toml") ? laidOutDomainEvidence(root, files, "rust") : "";
   const javaDomain = ["pom.xml", "build.gradle", "build.gradle.kts"].some((name) => files.has(name)) ? laidOutDomainEvidence(root, files, "java") : "";
+  // A Laravel application keeps its Eloquent models under app/Models, or
+  // under each package's src/Models when it is built from packages.
+  const laravelDomain = files.has("composer.json") ? matches(files, /^(?:app|packages\/[^/]+\/[^/]+\/src)\/Models\/[^/]+\.php$/)[0] ?? "" : "";
+  // A PHP tree laid out by bounded context keeps each module's model under
+  // src/<Context>/<Module>/Domain, with Shared beside the contexts.
+  const phpDdd = files.has("composer.json") ? matches(files, /^src\/(?!Shared\/)[^/]+\/(?!Shared\/)[^/]+\/Domain\/[^/]+\.php$/)[0] ?? "" : "";
+  // A .NET tree laid out by module keeps each module's model under
+  // src/Modules/<Module>/Domain, with the HTTP host under src/API.
+  const csharpDdd = matches(files, /^src\/Modules\/[^/]+\/Domain\/.+\.cs$/)[0] ?? "";
   return [
     detected("project", projectEvidence, {}, projectEvidence.join(", ")),
     detected("go-domain", goDomain ? [goDomain] : [], {}, goDomain),
@@ -394,6 +403,9 @@ function detectionsFor(root, files) {
     detected("rust-domain", rustDomain ? [rustDomain] : [], {}, rustDomain),
     detected("java-domain", javaDomain ? [javaDomain] : [], {}, javaDomain),
     detected("django-domain", files.has("manage.py") && matches(files, /(^|\/)models(?:\/[^/]+)?\.py$/i).length ? ["manage.py"] : []),
+    detected("laravel-domain", laravelDomain ? [laravelDomain] : [], {}, laravelDomain),
+    detected("php-ddd", phpDdd ? [phpDdd] : [], {}, phpDdd),
+    detected("csharp-ddd", csharpDdd ? [csharpDdd] : [], {}, csharpDdd),
     detected("celery", celery, {}, celery[0]),
     detected("openapi", openapi, openapi[0] ? { spec: openapi[0] } : {}, openapi[0], true),
     detected(

package/scripts/manifest.mjs

@@ -13,6 +13,12 @@ import { normalize } from "node:path";
 
 import Ajv from "ajv/dist/2020.js";
 import { warningPolicyProblems } from "./warning-policy.mjs";
+import { problemRuleProblems } from "../src/lib/problem-rules-cel.mjs";
+
+// The rules that have a reader, by id, so that an entry naming one is read as
+// a switch and any other as a rule of its own. Read once, like the schema:
+// the file is part of the package, and a manifest cannot add to it.
+const builtinRuleIds = () => JSON.parse(readFileSync(new URL("../rules/builtin.json", import.meta.url), "utf8")).map((rule) => rule.id);
 
 // Read when asked, not when loaded: the CLI sets PORTOLAN_SCHEMA after its imports.
 const schemaFile = () => process.env.PORTOLAN_SCHEMA || "schema/portolan.schema.json";
@@ -39,7 +45,10 @@ export function loadManifest(path = "portolan.json") {
  */
 export function parseManifest(text, path = "portolan.json") {
   const manifest = JSON.parse(text);
-  const policyProblems = warningPolicyProblems(manifest.warningPolicies, path);
+  const policyProblems = [
+    ...warningPolicyProblems(manifest.warningPolicies, path),
+    ...problemRuleProblems(manifest.problemRules, builtinRuleIds(), path),
+  ];
 
   let schema;
   try {

package/scripts/plugin-host.mjs

@@ -90,7 +90,7 @@ export async function runPlugin(plugin, request, requestedLimits = {}, access =
 // can be named, so a manifest cannot point the host at arbitrary code.
 // ---------------------------------------------------------------------------
 
-const HOST_PLUGINS = new Set(["fetch-git", "fetch-bsr", "fetch-csr"]);
+const HOST_PLUGINS = new Set(["fetch-git", "fetch-bsr", "fetch-csr", "fetch-k8s", "fetch-argocd"]);
 
 async function runHost(plugin, request) {
   const name = String(plugin.host);
@@ -215,6 +215,25 @@ function safeFileName(name) {
   return parts.every((part) => part !== "" && part !== "." && part !== "..");
 }
 
+/**
+ * What a plugin reads, or what it makes - the groups of the plugin index. A
+ * phase says where in a run a plugin goes; the category says what kind of
+ * fact it is after, which is the question a reader choosing extractors asks.
+ * Mirrors the Category constants in plugin/describe.go.
+ */
+export const PLUGIN_CATEGORIES = [
+  "code",
+  "contracts",
+  "messaging",
+  "data",
+  "infrastructure",
+  "repository",
+  "documents",
+  "evidence",
+  "sources",
+  "exports",
+];
+
 function validateDescriptor(pluginName, descriptor) {
   if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
     throw new Error(`plugin ${pluginName}: describe is not an object`);
@@ -225,6 +244,9 @@ function validateDescriptor(pluginName, descriptor) {
   if (typeof descriptor.summary !== "string") {
     throw new Error(`plugin ${pluginName}: describe.summary is missing`);
   }
+  if (!PLUGIN_CATEGORIES.includes(descriptor.category)) {
+    throw new Error(`plugin ${pluginName}: describe.category must be one of ${PLUGIN_CATEGORIES.join(", ")}`);
+  }
   if (!Array.isArray(descriptor.phases) || descriptor.phases.some((phase) => !["extract", "verify", "generate"].includes(phase))) {
     throw new Error(`plugin ${pluginName}: describe.phases is invalid`);
   }

package/scripts/plugins-fresh.mjs

@@ -0,0 +1,97 @@
+// Says whether the built plugins are newer than their sources, so that a run
+// started from the page can skip building them.
+//
+// `npm run gen` builds the wasm and the Java extractor first, every time,
+// which is right for a checkout somebody just changed and wrong for the
+// fourth trial of a recording in a row: a minute of javac and the Go
+// toolchain to learn nothing changed. The page asks here first and runs the
+// generator alone when the answer is yes. Anything doubtful - a missing
+// artefact, a source newer than it, a tree that cannot be read - is "no",
+// and the build runs as it always did.
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Where the Go sources the wasm is built from live, relative to the workspace. */
+const GO_ROOTS = ["plugins", "catalog", "plugin", "internal", "go.mod", "go.sum"];
+const GO_WASM = "plugins/portolan-go.wasm";
+const JAVA_SOURCES = "plugins/extract-java/src";
+const JAVA_BUILD = "plugins/extract-java/build";
+
+/** Directories under a source root that hold no sources of ours. */
+const SKIP = new Set(["node_modules", "target", "build", "testdata", ".git", "vendor"]);
+
+/**
+ * The newest modification time under a path, counting only files whose
+ * name passes `keep`, or -1 when nothing does. A path that cannot be read is
+ * treated as newer than anything, which sends the caller down the safe road.
+ */
+export function newestMtime(root, keep) {
+  let newest = -1;
+  const pending = [root];
+  while (pending.length) {
+    const path = pending.pop();
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      let entries;
+      try {
+        entries = readdirSync(path, { withFileTypes: true });
+      } catch {
+        return Number.POSITIVE_INFINITY;
+      }
+      for (const entry of entries) {
+        if (entry.isDirectory() && SKIP.has(entry.name)) continue;
+        pending.push(join(path, entry.name));
+      }
+    } else if (keep(path)) {
+      newest = Math.max(newest, stat.mtimeMs);
+    }
+  }
+  return newest;
+}
+
+function oldestArtefact(root, keep) {
+  let oldest = Number.POSITIVE_INFINITY;
+  let any = false;
+  const pending = [root];
+  while (pending.length) {
+    const path = pending.pop();
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      for (const entry of readdirSync(path, { withFileTypes: true })) pending.push(join(path, entry.name));
+    } else if (keep(path)) {
+      any = true;
+      oldest = Math.min(oldest, stat.mtimeMs);
+    }
+  }
+  return any ? oldest : -1;
+}
+
+/**
+ * Whether every built plugin is at least as new as every source it is built
+ * from. `true` means `node scripts/gen.mjs` can run on its own; anything
+ * else means `npm run gen`, which builds first.
+ */
+export function pluginsFresh(workspace) {
+  const wasm = oldestArtefact(join(workspace, GO_WASM), () => true);
+  if (wasm < 0) return false;
+  const goSources = Math.max(
+    ...GO_ROOTS.map((root) => newestMtime(join(workspace, root), (path) => /\.(go|mod|sum)$/.test(path))),
+  );
+  if (!(goSources <= wasm)) return false;
+
+  const classes = oldestArtefact(join(workspace, JAVA_BUILD), (path) => path.endsWith(".class"));
+  if (classes < 0) return false;
+  const javaSources = newestMtime(join(workspace, JAVA_SOURCES), (path) => path.endsWith(".java"));
+  return javaSources <= classes;
+}