docs: the portability report fails only with --strict

developing.md said findings never fail the portability report. Since the
report gained --strict, that's true only by default: --strict exits 1 when
it finds any. The workflow still runs it without --strict.

docs/reference/developing.md

@@ -33,7 +33,7 @@ suite. Both sets are readable in the root `package.json` scripts.
 
 | Lane | Command | Meaning |
 |---|---|---|
-| Portability report | `node scripts/portability-report.mjs` | lists added lines with machine-specific values; findings never fail it (`.github/workflows/portability-report.yml`) |
+| Portability report | `node scripts/portability-report.mjs` | lists added lines with machine-specific values; findings don't fail it by default, and `--strict` exits 1 when it finds any. The workflow (`.github/workflows/portability-report.yml`) runs it without `--strict`. |
 
 ## The norm (web-UI freeze at 0.5.0)
 

scripts/portability-report.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // Lists lines added by a change that contain values tied to one machine, network or account, so
-// the author can replace them with portable ones or keep them on purpose. Findings never fail it: a finding is a question, not a verdict. It exits 0
-// with or without findings and 2 on an operational error (bad argument, git failure).
+// the author can replace them with portable ones or keep them on purpose. A finding is a question, not a verdict: the default
+// exits 0 with or without findings, --strict exits 1 when findings exist, and 2 is an operational error (bad argument, git failure).
 //
 // What it looks for:
 //   1. Credentials: keys, tokens, passwords, key blocks.
@@ -17,6 +17,7 @@
 //   node scripts/portability-report.mjs --staged             # what is staged for the next commit
 //   add --out report.md to also write the report to a file
 //   add --locations-only to list file and line without quoting the matched text (for public CI output)
+//   add --strict to exit 1 when findings exist (the default stays advisory: exit 0 either way)
 
 import { execFileSync } from "node:child_process";
 import { writeFileSync, realpathSync } from "node:fs";
@@ -133,11 +134,12 @@ export function renderReport(findings, label, { locationsOnly = false } = {}) {
 }
 
 function parseArguments(argv) {
-  const options = { staged: false, locationsOnly: false };
+  const options = { staged: false, locationsOnly: false, strict: false };
   for (let index = 0; index < argv.length; index += 1) {
     const key = argv[index];
     if (key === "--staged") options.staged = true;
     else if (key === "--locations-only") options.locationsOnly = true;
+    else if (key === "--strict") options.strict = true;
     else if (["--from", "--to", "--out", "--repo"].includes(key)) options[key.slice(2)] = argv[++index];
     else throw new Error(`Unknown argument: ${key}`);
   }
@@ -163,12 +165,13 @@ export function main(argv = process.argv.slice(2)) {
     label = `${from.slice(0, 8)}..${to.length > 12 ? to.slice(0, 8) : to}`;
   }
   const diff = git(repo, ["-c", "core.quotePath=false", "diff", "-U0", "--no-color", "--src-prefix=a/", "--dst-prefix=b/", "--diff-filter=ACMR", ...range]);
-  const report = renderReport(findPortabilityIssues(addedLines(diff)), label, {
+  const findings = findPortabilityIssues(addedLines(diff));
+  const report = renderReport(findings, label, {
     locationsOnly: options.locationsOnly,
   });
   process.stdout.write(report);
   if (options.out) writeFileSync(options.out, report);
-  return 0;
+  return options.strict && findings.length > 0 ? 1 : 0;
 }
 
 function invokedDirectly() {

scripts/portability-report.test.mjs

@@ -173,3 +173,32 @@ test("strips Git's separator tab and leaves C-quoted filenames quoted", () => {
   }
   assert.deepEqual(addedLines("+++ b/ordinary name.md\t\n@@ -0,0 +1 @@\n+see /Users/alice/project\n"), [{ file: "ordinary name.md", line: 1, text: "see /Users/alice/project" }]);
 });
+
+test("--strict exits 1 on findings, keeps the advisory default at 0, and exits 0 on a clean stage", async () => {
+  const { mkdtempSync, writeFileSync, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+  const { execFileSync, spawnSync } = await import("node:child_process");
+  const repo = mkdtempSync(join(tmpdir(), "openrig-portability-strict-"));
+  const script = fileURLToPath(new URL("./portability-report.mjs", import.meta.url));
+  try {
+    execFileSync("git", ["init", "--quiet", repo]);
+    execFileSync("git", ["-C", repo, "config", "user.email", "[email protected]"]);
+    execFileSync("git", ["-C", repo, "config", "user.name", "t"]);
+    writeFileSync(join(repo, "a.md"), "see /Users/alice/work\n");
+    execFileSync("git", ["-C", repo, "add", "--", "a.md"]);
+
+    const strictWithFindings = spawnSync(process.execPath, [script, "--repo", repo, "--staged", "--strict"], { encoding: "utf8" });
+    assert.equal(strictWithFindings.status, 1, strictWithFindings.stdout + strictWithFindings.stderr);
+
+    const advisoryWithFindings = spawnSync(process.execPath, [script, "--repo", repo, "--staged"], { encoding: "utf8" });
+    assert.equal(advisoryWithFindings.status, 0, advisoryWithFindings.stdout + advisoryWithFindings.stderr);
+
+    execFileSync("git", ["-C", repo, "commit", "--quiet", "-m", "seed"]);
+    writeFileSync(join(repo, "b.md"), "Nothing machine-specific here.\n");
+    execFileSync("git", ["-C", repo, "add", "--", "b.md"]);
+    const strictClean = spawnSync(process.execPath, [script, "--repo", repo, "--staged", "--strict"], { encoding: "utf8" });
+    assert.equal(strictClean.status, 0, strictClean.stdout + strictClean.stderr);
+  } finally { rmSync(repo, { recursive: true, force: true }); }
+});