@shortlink-org/portolan 0.2.4 → 0.4.0

package/scripts/local-discovery.mjs

@@ -169,7 +169,7 @@ function goDeployables(root, files) {
   return out;
 }
 
-function detected(plugin, candidates, options = {}, label = candidates[0], ambiguous = false, selected = true) {
+function detected(plugin, candidates, options = {}, label = candidates[0], ambiguous = false, selected = true, preview = []) {
   if (!candidates.length) return null;
   return {
     plugin,
@@ -178,15 +178,74 @@ function detected(plugin, candidates, options = {}, label = candidates[0], ambig
     candidates,
     options,
     selected,
+    ...(preview.length ? { preview } : {}),
+  };
+}
+
+const ADR_STATUSES = new Map([
+  ["proposed", "proposed"], ["draft", "proposed"], ["pending", "proposed"], ["на рассмотрении", "proposed"],
+  ["accepted", "accepted"], ["approved", "accepted"], ["adopted", "accepted"], ["принято", "accepted"], ["принят", "accepted"],
+  ["superseded", "superseded"], ["заменено", "superseded"], ["заменён", "superseded"],
+  ["deprecated", "deprecated"], ["obsolete", "deprecated"], ["устарело", "deprecated"],
+  ["rejected", "rejected"], ["declined", "rejected"], ["отклонено", "rejected"],
+]);
+
+function normalizedAdrStatus(value) {
+  return ADR_STATUSES.get(value.trim().replace(/[.:]+$/, "").toLowerCase()) ?? "";
+}
+
+// Discovery mirrors the tolerant shapes accepted by extract-adr closely
+// enough to enable the capability with confidence and to show what it found.
+// Git-backed dates are resolved by the extractor, so a format without an
+// explicit Date can still be previewed here without inventing one.
+function adrPreview(root, name) {
+  let source = "";
+  try { source = readFileSync(join(root, name), "utf8").replaceAll("\r\n", "\n"); } catch { return null; }
+  const lines = source.split("\n");
+  const heading = lines.find((line) => line.trim()) ?? "";
+  const base = posix.basename(name, ".md");
+  const numberedFile = /^(\d+)-([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(base);
+
+  let number = "";
+  let title = "";
+  let match = /^#\s+[a-z][a-z0-9.-]*\.(\d{4})\s+—\s+(.+?)\s*$/i.exec(heading);
+  if (match) [number, title] = match.slice(1);
+  else if ((match = /^#\s+(\d+)\.\s+(.+?)\s*$/.exec(heading))) [number, title] = match.slice(1);
+  else if ((match = /^#\s+ADR[-\s]?0*(\d+)\s*[.:—-]\s*(.+?)\s*$/i.exec(heading))) [number, title] = match.slice(1);
+  else if (numberedFile && (match = /^#\s+(.+?)\s*$/.exec(heading))) {
+    number = numberedFile[1];
+    title = match[1];
+  }
+  if (!number || !title || !numberedFile || Number(numberedFile[1]) !== Number(number)) return null;
+  if (!lines.some((line) => /^#{2,6}\s/.test(line))) return null;
+
+  let status = "";
+  const bullet = /^-\s+\*\*Status:\*\*\s*(.*?)\s*$/mi.exec(source);
+  if (bullet) status = normalizedAdrStatus(bullet[1]);
+  if (!status) {
+    const at = lines.findIndex((line) => /^#{2,6}\s+(?:Status|Статус)\s*:?/i.test(line));
+    if (at >= 0) {
+      const inline = /^#{2,6}\s+(?:Status|Статус)\s*:?\s*(.*?)\s*$/i.exec(lines[at])?.[1] ?? "";
+      const following = lines.slice(at + 1).find((line) => line.trim() && !/^#{1,6}\s/.test(line)) ?? "";
+      status = normalizedAdrStatus(inline || following);
+    }
+  }
+  if (!status) return null;
+
+  const writtenDate = /^(?:-\s+\*\*Date:\*\*|Date:)\s*(\S.*?)\s*$/mi.exec(source)?.[1];
+  if (writtenDate) {
+    const stamp = new Date(`${writtenDate}T00:00:00Z`);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(writtenDate) || Number.isNaN(stamp.getTime()) || stamp.toISOString().slice(0, 10) !== writtenDate) return null;
+  }
+  const date = writtenDate ?? "from git history";
+  return {
+    file: name,
+    fields: { number: String(Number(number)), title: title.trim(), status, date },
   };
 }
 
 function compatibleAdrs(root, candidates) {
-  return candidates.filter((name) => {
-    let source = "";
-    try { source = readFileSync(join(root, name), "utf8"); } catch { return false; }
-    return /^#\s+[^\n]+\.\d{4}\s+[—-]/m.test(source) && /^-\s+\*\*Status:\*\*/mi.test(source) && /^-\s+\*\*Date:\*\*/mi.test(source);
-  });
+  return candidates.map((name) => adrPreview(root, name)).filter(Boolean);
 }
 
 function goDomainEvidence(root, files) {
@@ -211,6 +270,18 @@ function goDomainEvidence(root, files) {
   return "";
 }
 
+// This is a discovery hint; the Go AST extractor proves the handler binding.
+function goHTTPServerEvidence(root, files) {
+  for (const name of matches(files, /\.go$/).filter((name) => !/(?:_test|\.gen|_generated)\.go$/.test(name) && !/(?:^|\/)(?:testdata|vendor)\//.test(name))) {
+    let source;
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    if (/Code generated .*DO NOT EDIT/.test(source)) continue;
+    if (/"net\/http"/.test(source) && /\.Handle(?:Func)?\s*\(/.test(source)) return name;
+    if (/"github\.com\/(?:go-chi\/chi|gin-gonic\/gin|labstack\/echo)(?:\/v\d+)?"/.test(source) && /\.(?:Get|Post|Put|Patch|Delete|GET|POST|PUT|PATCH|DELETE)\s*\(/.test(source)) return name;
+  }
+  return "";
+}
+
 function laidOutDomainEvidence(root, files, language) {
   const extension = language === "typescript" ? "ts" : language === "rust" ? "rs" : "java";
   const prefix = language === "java" ? /(?:^|\/)domain\/([^/]+)\/[^/]+\.java$/i : /^src\/domain\/([^/]+)\/[^/]+\.(?:ts|rs)$/i;
@@ -291,8 +362,9 @@ function detectionsFor(root, files) {
   const graphql = matches(files, /\.graphqls?$/i);
   const protos = matches(files, /\.proto$/i);
   const sql = matches(files, /(^|\/)(migrations?|repository)(\/|.*\/).*\.sql$/i);
-  const adrs = matches(files, /(^|\/)(docs\/adr|adr)\/.*\.md$/i);
-  const supportedAdrs = compatibleAdrs(root, adrs);
+  const adrs = matches(files, /(^|\/)(docs\/adr|adr)\/.*\.md$/i).filter((name) => posix.basename(name).toLowerCase() !== "readme.md");
+  const adrPreviews = compatibleAdrs(root, adrs);
+  const supportedAdrs = adrPreviews.map((item) => item.file);
   const glossaries = matches(files, /(^|\/)glossary\.md$/i);
   // The app module is the one file a Celery project always has; the tasks
   // and the calls that enqueue them are found from there.
@@ -308,13 +380,22 @@ function detectionsFor(root, files) {
   const protoDirs = compactDirectories(protos);
   const projectMarkers = ["go.mod", "package.json", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts", "manage.py", "Dockerfile", "README.md"].filter((name) => files.has(name));
   const projectEvidence = projectMarkers.length ? projectMarkers : [[...files].sort()[0]].filter(Boolean);
-  const goDomain = files.has("go.mod") ? goDomainEvidence(root, files) : "";
+  const goDomain = files.has("go.mod") ? goDomainEvidence(root, files) || goHTTPServerEvidence(root, files) : "";
   const goHTTPClient = files.has("go.mod") ? goHTTPClientEvidence(root, files) : "";
   const goSOAPClient = files.has("go.mod") ? goSOAPClientEvidence(root, files) : "";
   const goRedis = files.has("go.mod") ? goRedisEvidence(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),
@@ -322,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(
@@ -349,6 +433,7 @@ function detectionsFor(root, files) {
       supportedAdrs[0] ? `${posix.dirname(supportedAdrs[0])}/*.md` : `${posix.dirname(adrs[0] ?? "docs/adr/x.md")}/*.md (format not recognized)`,
       !supportedAdrs.length,
       supportedAdrs.length > 0,
+      adrPreviews,
     ),
     detected("glossary", glossaries, glossaries.length ? { files: glossaries } : {}, glossaries.join(", ")),
   ].filter(Boolean);

package/scripts/manifest.mjs

@@ -12,6 +12,13 @@ import { readFileSync } from "node:fs";
 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";
@@ -38,20 +45,24 @@ export function loadManifest(path = "portolan.json") {
  */
 export function parseManifest(text, path = "portolan.json") {
   const manifest = JSON.parse(text);
+  const policyProblems = [
+    ...warningPolicyProblems(manifest.warningPolicies, path),
+    ...problemRuleProblems(manifest.problemRules, builtinRuleIds(), path),
+  ];
 
   let schema;
   try {
     schema = JSON.parse(readFileSync(schemaFile(), "utf8"));
   } catch {
-    return { manifest, problems: [] };
+    return { manifest, problems: policyProblems };
   }
 
   const ajv = new Ajv({ allErrors: true, strictSchema: false });
   const validate = ajv.compile(schema);
 
-  if (validate(manifest)) return { manifest, problems: [] };
+  if (validate(manifest)) return { manifest, problems: policyProblems };
 
-  return { manifest, problems: explain(validate.errors ?? [], manifest, schema, path) };
+  return { manifest, problems: [...explain(validate.errors ?? [], manifest, schema, path), ...policyProblems] };
 }
 
 /**

package/scripts/manifest.test.mjs

@@ -58,6 +58,30 @@ describe("the manifest schema", () => {
     expect(check(good)).toEqual([]);
   });
 
+  it("accepts a typed CEL warning policy only with an action and reason", () => {
+    expect(check({
+      ...good,
+      warningPolicies: [{
+        when: "plugin == 'openapi' && rule == 'openapi.missing-operation-id' && count > 10",
+        action: "suppress",
+        reason: "The contract is owned upstream.",
+      }],
+    })).toEqual([]);
+
+    const problems = check({
+      ...good,
+      warningPolicies: [{ when: "plugin == 'openapi'", action: "suppress" }],
+    });
+    expect(problems.join("\n")).toContain('warningPolicies/0: "reason" is missing');
+  });
+
+  it("refuses a CEL warning policy with unknown variables or a non-boolean result", () => {
+    expect(check({ ...good, warningPolicies: [{ when: "owner == 'team'", action: "suppress", reason: "test" }] }).join("\n"))
+      .toContain("Unknown variable: owner");
+    expect(check({ ...good, warningPolicies: [{ when: "plugin", action: "suppress", reason: "test" }] }).join("\n"))
+      .toContain("CEL expression must return bool");
+  });
+
   it("refuses an unstable project id", () => {
     const problems = check({
       ...good,

package/scripts/output-diff.mjs

@@ -0,0 +1,94 @@
+// Why a generated file is not what the generator produces now, in one line.
+//
+// `gen --check` used to say "changed docs/x.md" and nothing else, which sent
+// the reader to a diff of the whole file to learn that one number moved.
+// The first difference is usually the whole story: a JSON fragment names the
+// path that differs and both values, a page names the line.
+
+/**
+ * @param {string | Buffer | null} current  what is on disk, null when absent
+ * @param {string | Buffer} wanted          what the generator produced
+ * @param {string} name                     the file's name, for its format
+ * @returns {string}
+ */
+export function explainChange(current, wanted, name) {
+  if (current === null) return "not on disk yet";
+  if (Buffer.isBuffer(current) || Buffer.isBuffer(wanted)) return "binary contents differ";
+  if (name.endsWith(".json")) {
+    const found = jsonDifference(current, wanted);
+    if (found) return found;
+  }
+  return lineDifference(current, wanted);
+}
+
+/** The first path where two JSON documents disagree, or "" when either does not parse. */
+export function jsonDifference(current, wanted) {
+  let a;
+  let b;
+  try {
+    a = JSON.parse(current);
+    b = JSON.parse(wanted);
+  } catch {
+    return "";
+  }
+  return firstDifference(a, b, "") ?? "same value, different formatting";
+}
+
+function firstDifference(a, b, path) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const shared = Math.min(a.length, b.length);
+    for (let i = 0; i < shared; i++) {
+      const found = firstDifference(a[i], b[i], `${path}[${i}]`);
+      if (found) return found;
+    }
+    if (a.length !== b.length) {
+      return `${path || "the document"}: ${a.length} item${a.length === 1 ? "" : "s"} → ${b.length}`;
+    }
+    return null;
+  }
+  if (isObject(a) && isObject(b)) {
+    for (const key of Object.keys(b)) {
+      const at = path ? `${path}.${key}` : key;
+      if (!(key in a)) return `${at}: added ${short(b[key])}`;
+      const found = firstDifference(a[key], b[key], at);
+      if (found) return found;
+    }
+    for (const key of Object.keys(a)) {
+      if (!(key in b)) return `${path ? `${path}.${key}` : key}: removed`;
+    }
+    return null;
+  }
+  if (Object.is(a, b)) return null;
+  return `${path || "the document"}: ${short(a)} → ${short(b)}`;
+}
+
+/** The first line that differs, with both sides, or the extra lines when one is a prefix of the other. */
+export function lineDifference(current, wanted) {
+  const a = current.split("\n");
+  const b = wanted.split("\n");
+  const shared = Math.min(a.length, b.length);
+  for (let i = 0; i < shared; i++) {
+    if (a[i] !== b[i]) return `line ${i + 1}: ${short(a[i])} → ${short(b[i])}`;
+  }
+  if (a.length === b.length) return "identical";
+  const extra = Math.abs(a.length - b.length);
+  return a.length < b.length
+    ? `line ${shared + 1}: ${extra} line${extra === 1 ? "" : "s"} added`
+    : `line ${shared + 1}: ${extra} line${extra === 1 ? "" : "s"} removed`;
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A value as one short token: strings quoted, structures summarised. */
+function short(value) {
+  const text = typeof value === "string" ? JSON.stringify(value) : isObject(value) || Array.isArray(value) ? summarise(value) : String(value);
+  return text.length > 60 ? `${text.slice(0, 57)}…` : text;
+}
+
+function summarise(value) {
+  if (Array.isArray(value)) return `[${value.length} item${value.length === 1 ? "" : "s"}]`;
+  const keys = Object.keys(value);
+  return `{${keys.slice(0, 3).join(", ")}${keys.length > 3 ? ", …" : ""}}`;
+}

package/scripts/output-diff.test.mjs

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+
+import { explainChange, jsonDifference, lineDifference } from "./output-diff.mjs";
+
+describe("explainChange", () => {
+  it("names the JSON path and both values", () => {
+    const current = JSON.stringify({ contexts: [{ services: [{ commands: [{ source: "package.json:58" }] }] }] });
+    const wanted = JSON.stringify({ contexts: [{ services: [{ commands: [{ source: "package.json:59" }] }] }] });
+    expect(explainChange(current, wanted, "commands.json")).toBe(
+      'contexts[0].services[0].commands[0].source: "package.json:58" → "package.json:59"',
+    );
+  });
+
+  it("says what was added, what was removed, and when a list grew", () => {
+    expect(jsonDifference('{"a":1}', '{"a":1,"b":{"x":1,"y":2}}')).toBe("b: added {x, y}");
+    expect(jsonDifference('{"a":1,"b":2}', '{"a":1}')).toBe("b: removed");
+    expect(jsonDifference('{"flows":[1]}', '{"flows":[1,2,3]}')).toBe("flows: 1 item → 3");
+  });
+
+  it("falls back to lines for text, and for JSON that does not parse", () => {
+    expect(lineDifference("a\nb\nc", "a\nB\nc")).toBe('line 2: "b" → "B"');
+    expect(lineDifference("a\nb", "a\nb\nc\nd")).toBe("line 3: 2 lines added");
+    expect(lineDifference("a\nb\nc", "a")).toBe("line 2: 2 lines removed");
+    expect(explainChange("{not json", "{still not", "x.json")).toBe('line 1: "{not json" → "{still not"');
+  });
+
+  it("knows a file that is not there yet, and a binary one", () => {
+    expect(explainChange(null, "x", "x.md")).toBe("not on disk yet");
+    expect(explainChange(Buffer.from([1]), Buffer.from([2]), "x.png")).toBe("binary contents differ");
+  });
+
+  it("keeps a long value readable", () => {
+    const long = "x".repeat(200);
+    expect(jsonDifference('{"a":"short"}', `{"a":"${long}"}`)).toMatch(/^a: "short" → "x{56}…$/);
+  });
+});

package/scripts/package-smoke.mjs

@@ -2,9 +2,9 @@
 // This catches accidental cwd coupling before the same package reaches npm.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -31,9 +31,58 @@ try {
   writeFileSync(resolve(fixture, "package.json"), '{"name":"package-smoke","version":"1.0.0"}\n');
   writeFileSync(resolve(fixture, "README.md"), "# Package smoke\n");
   // A Go domain layout: init should notice it and wire the extractor without being asked.
-  writeFileSync(resolve(fixture, "go.mod"), "module example.com/smoke\n\ngo 1.24\n");
+  writeFileSync(resolve(fixture, "go.mod"), "module example.com/smoke\n\ngo 1.27.0\n");
   mkdirSync(resolve(fixture, "internal/domain/order"), { recursive: true });
   writeFileSync(resolve(fixture, "internal/domain/order/order.go"), "package order\n\ntype Order struct{ ID string }\n");
+  writeGoFixture("app/main.go", `package app
+import (
+  "example.com/smoke/actions/rules"
+  "example.com/smoke/connector"
+)
+type Router struct{}
+func (*Router) POST(string, func()) {}
+type Requester interface { ConnExec(connector.API) }
+func Start(r *Router) { r.POST("/rules", RulesAction) }
+func RulesAction() {
+  request := &rules.Request{}
+  Dispatch(request)
+}
+func Dispatch(request Requester) { Invoke(request) }
+func Invoke(request Requester) {
+  conn := connector.Build("runtime")
+  request.ConnExec(conn)
+}
+`);
+  writeGoFixture("actions/rules/request.go", `package rules
+import "example.com/smoke/connector"
+type Request struct{}
+func (*Request) ConnExec(conn connector.API) { conn.Rules() }
+`);
+  writeGoFixture("connector/factory.go", `package connector
+import "example.com/smoke/provider/alpha"
+type API interface { Rules() }
+func Build(name string) API {
+  switch name { case "alpha": return alpha.New(); default: return nil }
+}
+`);
+  writeGoFixture("provider/alpha/connector.go", `package alpha
+import "example.com/smoke/provider/alpha/client"
+type rulesClient interface { FetchRules() }
+type Connector struct { client rulesClient }
+func New() *Connector { return &Connector{client: &client.Client{}} }
+func (c *Connector) Rules() { c.client.FetchRules() }
+`);
+  writeGoFixture("provider/alpha/client/client.go", `package client
+import "net/http"
+type Client struct{}
+func (c *Client) FetchRules() { c.fetchRules() }
+func (c *Client) fetchRules() { c.finishRules() }
+func (c *Client) finishRules() {
+  _, _ = http.Get("https://alpha.example/v1/rules")
+  if false { c.fetchRules() }
+}
+func (*Client) CheckRules() { _, _ = http.Get("https://alpha.example/v1/check-rules") }
+`);
   run("git", ["init", "--quiet"]);
   run("git", ["config", "user.email", "portolan@example.invalid"]);
   run("git", ["config", "user.name", "Portolan smoke test"]);
@@ -44,9 +93,13 @@ try {
   run(process.execPath, [cli, "check", "--cwd", fixture]);
   run(process.execPath, [cli, "build", "--cwd", fixture, "--output", "dist", "--base", "/architecture/"]);
 
-  for (const path of ["portolan/project.json", "portolan/domain.json", "docs/README.md", "dist/index.html", "dist/404.html"]) {
+  for (const path of ["portolan/project.json", "portolan/domain.json", "portolan/http-clients.json", "docs/README.md", "dist/index.html", "dist/404.html"]) {
     if (!existsSync(resolve(fixture, path))) throw new Error(`smoke test did not write ${path}`);
   }
+  const calls = JSON.parse(readFileSync(resolve(fixture, "portolan/http-clients.json"), "utf8"));
+  if (!calls.flows.some((flow) => flow.name === "POST /rules → provider APIs")) {
+    throw new Error(`package smoke did not preserve the typed HTTP provider flow; got ${calls.flows.map((flow) => flow.name).join(", ")}`);
+  }
   console.log("package smoke: init, generate, check, and build passed outside the repository");
 } finally {
   rmSync(fixture, { recursive: true, force: true });
@@ -56,3 +109,8 @@ try {
 function run(command, args) {
   execFileSync(command, args, { cwd: fixture, stdio: "inherit" });
 }
+
+function writeGoFixture(path, contents) {
+  mkdirSync(dirname(resolve(fixture, path)), { recursive: true });
+  writeFileSync(resolve(fixture, path), contents);
+}

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);
@@ -185,8 +185,28 @@ export function validateResponse(name, response) {
 }
 
 function validBase64(value) {
-  return value.length % 4 === 0
-    && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+  if (value.length % 4 !== 0) return false;
+
+  let payloadLength = value.length;
+  if (value.endsWith("==")) payloadLength -= 2;
+  else if (value.endsWith("=")) payloadLength -= 1;
+
+  // A repeated-group regexp over a multi-megabyte binary can exhaust V8's
+  // regexp stack. Validate the same alphabet iteratively so vendoring a large
+  // file remains bounded by its bytes rather than the JavaScript call stack.
+  for (let index = 0; index < payloadLength; index += 1) {
+    const code = value.charCodeAt(index);
+    const alphabet = code >= 65 && code <= 90
+      || code >= 97 && code <= 122
+      || code >= 48 && code <= 57
+      || code === 43
+      || code === 47;
+    if (!alphabet) return false;
+  }
+  for (let index = payloadLength; index < value.length; index += 1) {
+    if (value.charCodeAt(index) !== 61) return false;
+  }
+  return true;
 }
 
 function safeFileName(name) {
@@ -195,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`);
@@ -205,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/plugin-host.test.mjs

@@ -21,6 +21,15 @@ describe("plugin response validation", () => {
     expect(() => validateResponse("fixture", { files: [{ name: "image.png", contents: "x", encoding: "binary" }] })).toThrow("encoding is not supported");
   });
 
+  it("validates multi-megabyte base64 without overflowing the regexp stack", () => {
+    const contents = "A".repeat(13 * 1024 * 1024);
+    expect(validateResponse("fixture", { files: [{ name: "large.bin", contents, encoding: "base64" }] }).files[0]).toEqual({
+      name: "large.bin",
+      contents,
+      encoding: "base64",
+    });
+  });
+
   it.each(["../secret", "/tmp/result", "C:\\tmp\\result", "a/../../secret", "./result"])(
     "rejects unsafe output name %s",
     (name) => {

package/scripts/plugin-wasm-worker.mjs

@@ -10,7 +10,10 @@ async function run() {
     const wasi = new WASI({
       version: "preview1",
       args: [workerData.name],
-      env: {},
+      env: {
+        GOOS: process.env.GOOS || ({ win32: "windows" }[process.platform] ?? process.platform),
+        GOARCH: process.env.GOARCH || ({ x64: "amd64", ia32: "386" }[process.arch] ?? process.arch),
+      },
       // Empty for a generator or a describe request. An extract or verify
       // step gets the workspace as `/`, and nothing else (portolan.0006).
       preopens: workerData.workspace ? { "/": workerData.workspace } : {},

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;
+}