mandrel-platform 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^2.7.0"
+    "mandrel": "^2.31.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/check-first-party-pin-freshness.mjs

@@ -38,6 +38,22 @@
  * <subpath>` names, plus every tracked working-tree file under it, so an added
  * or removed sibling is drift too.
  *
+ * ## Why a subpath can have COMPANIONS (Story #389)
+ *
+ * The subpaths this checker knows are exactly the ones named on `uses:` lines,
+ * which reopens the same blind spot one level up the moment an action's
+ * behaviour moves into a SIBLING DIRECTORY. Story #389 reduced
+ * `.github/actions/osv-track-issue` to a thin preset that executes
+ * `.github/actions/track-issue/track-issue.mjs` — nothing `uses:` the generic
+ * action, so a rewrite of that shared core would leave every `osv-track-issue`
+ * pin reading fresh while the pinned SHA runs the old state machine.
+ *
+ * `COMPANION_SUBPATHS` closes it: a subpath's companions are folded into the
+ * tree comparison and into the drift cache key, so an edit confined to the
+ * shared core marks every call site of every dependent preset stale. The map
+ * is deliberately explicit rather than inferred — a heuristic over `run:`
+ * bodies would both miss indirection and invent false drift.
+ *
  * This checker closes it by classifying every first-party SHA pin into one of
  * two failure classes — deliberately kept distinct, because their remedies
  * differ:
@@ -325,6 +341,33 @@ export function createGit(repoRoot) {
 // Subpath tree comparison
 // ---------------------------------------------------------------------------
 
+/**
+ * Subpaths whose runtime behaviour lives partly in ANOTHER directory that no
+ * `uses:` line names. Each key's companions are compared alongside it, so an
+ * edit confined to a shared core still marks the dependent pins stale.
+ *
+ * Keep this map in step with any preset/core split under `.github/actions/`:
+ * an entry omitted here is a pin that reads fresh while running old code.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const COMPANION_SUBPATHS = {
+  // Story #389 — the preset executes ../track-issue/track-issue.mjs.
+  ".github/actions/osv-track-issue": [".github/actions/track-issue"],
+};
+
+/**
+ * Companion subpaths for a `uses:` subpath (empty when it stands alone).
+ * Trailing slashes are tolerated so `foo/` and `foo` resolve identically.
+ *
+ * @param {string} subpath
+ * @param {Record<string, string[]>} [map]
+ * @returns {string[]}
+ */
+export function companionsFor(subpath, map = COMPANION_SUBPATHS) {
+  return map[String(subpath).replace(/\/+$/, "")] || [];
+}
+
 /** How each drift kind reads in the report. */
 const DRIFT_PHRASE = {
   differs: "differs from the working-tree copy",
@@ -341,15 +384,21 @@ const DRIFT_PHRASE = {
  * since the pinned revision is drift just as much as one whose bytes changed —
  * all three change what the pinned revision actually executes.
  *
+ * `companions` extends the comparison to directories the subpath EXECUTES but
+ * no `uses:` line names (Story #389). They are compared identically: a shared
+ * core that differs at the pinned SHA is exactly as inert as a sibling script.
+ *
  * @param {{lsTree: Function, lsFiles: Function, show: Function}} git
  * @param {string} repoRoot
  * @param {string} sha
  * @param {string} subpath
+ * @param {string[]} [companions]
  * @returns {Array<{path: string, kind: "differs" | "added" | "removed" | "unreadable"}>}
  */
-export function diffSubpathAtSha(git, repoRoot, sha, subpath) {
-  const pinned = new Set(git.lsTree(sha, subpath));
-  const working = new Set(git.lsFiles(subpath));
+export function diffSubpathAtSha(git, repoRoot, sha, subpath, companions = []) {
+  const roots = [subpath, ...companions];
+  const pinned = new Set(roots.flatMap((root) => git.lsTree(sha, root)));
+  const working = new Set(roots.flatMap((root) => git.lsFiles(root)));
   const drift = [];
 
   for (const path of [...new Set([...pinned, ...working])].sort()) {
@@ -384,12 +433,17 @@ export function diffSubpathAtSha(git, repoRoot, sha, subpath) {
  *
  * @param {string} subpath
  * @param {ReturnType<typeof diffSubpathAtSha>} drift
+ * @param {string[]} [companions]
  * @returns {string}
  */
-export function describeDrift(subpath, drift) {
+export function describeDrift(subpath, drift, companions = []) {
   const detail = drift.map((d) => `${d.path} ${DRIFT_PHRASE[d.kind]}`).join("; ");
+  const scope =
+    companions.length > 0
+      ? `${subpath} (and the shared code it executes: ${companions.join(", ")})`
+      : subpath;
   return (
-    `${drift.length} file(s) under ${subpath} lag the pinned SHA — the pinned ` +
+    `${drift.length} file(s) under ${scope} lag the pinned SHA — the pinned ` +
     `revision is what actually runs: ${detail}`
   );
 }
@@ -406,7 +460,11 @@ export function describeDrift(subpath, drift) {
  * `git` is injectable so a caller can drive the classification against a
  * substitute history; it defaults to the real git bound to `opts.cwd`.
  *
- * @param {{cwd?: string, workflowsDir?: string, actionsDir?: string, firstPartyOwner?: string, ref?: string}} opts
+ * `opts.companions` overrides {@link COMPANION_SUBPATHS} — injectable so a
+ * fixture can exercise the shared-core relationship without depending on this
+ * repo's own action layout.
+ *
+ * @param {{cwd?: string, workflowsDir?: string, actionsDir?: string, firstPartyOwner?: string, ref?: string, companions?: Record<string, string[]>}} opts
  * @param {ReturnType<typeof createGit>} [git]
  * @returns {{ok: boolean, fatal: string|null, stale: object[], unreachable: object[], unpinnedRefs: object[], scanned: number, files: string[], headSha: string|null}}
  */
@@ -457,12 +515,15 @@ export function runCheck(opts = {}, git = createGit(resolve(opts.cwd || process.
 
   // Every call site for a subpath must move together, so the same
   // (sha, subpath) pair is compared repeatedly — `setup-toolchain` alone has
-  // five. Resolve each tree once.
+  // five. Resolve each tree once. The companions are part of the key: two
+  // subpaths sharing a core must not collide, and a companion map override
+  // must not read a cache entry computed without it.
+  const companionMap = opts.companions || COMPANION_SUBPATHS;
   const driftCache = new Map();
-  const driftFor = (sha, subpath) => {
-    const key = `${sha}:${subpath}`;
+  const driftFor = (sha, subpath, companions) => {
+    const key = `${sha}:${[subpath, ...companions].join(",")}`;
     if (!driftCache.has(key)) {
-      driftCache.set(key, diffSubpathAtSha(git, repoRoot, sha, subpath));
+      driftCache.set(key, diffSubpathAtSha(git, repoRoot, sha, subpath, companions));
     }
     return driftCache.get(key);
   };
@@ -511,12 +572,13 @@ export function runCheck(opts = {}, git = createGit(resolve(opts.cwd || process.
         continue;
       }
 
-      const drift = driftFor(pin.sha, pin.subpath);
+      const companions = companionsFor(pin.subpath, companionMap);
+      const drift = driftFor(pin.sha, pin.subpath, companions);
       if (drift.length > 0) {
         stale.push({
           ...pin,
           manifest: manifest.path,
-          reason: describeDrift(pin.subpath, drift),
+          reason: describeDrift(pin.subpath, drift, companions),
         });
       }
     }

package/scripts/check-first-party-pin-freshness.test.mjs

@@ -37,8 +37,10 @@ import {
   resolveManifest,
   manifestsMatch,
   diffSubpathAtSha,
+  companionsFor,
   runCheck,
   runCli,
+  COMPANION_SUBPATHS,
 } from "./check-first-party-pin-freshness.mjs";
 
 const OWNER = "test-owner/test-repo";
@@ -390,6 +392,165 @@ test("diffSubpathAtSha: a blob git cannot resolve at the pinned SHA is drift, no
   assert.deepEqual(drift, [{ path, kind: "differs" }]);
 });
 
+// ---------------------------------------------------------------------------
+// Story #389 — a subpath's COMPANIONS are compared alongside it
+//
+// The subpaths this checker knows are exactly the ones named on `uses:` lines,
+// so the moment an action's behaviour moves into a sibling DIRECTORY the
+// Story #379 blind spot reopens one level up. `osv-track-issue` is now a thin
+// preset that executes `../track-issue/track-issue.mjs`, and nothing `uses:`
+// the generic action — so without a companion map, a rewrite of that shared
+// core leaves every preset call site reading fresh while the pinned SHA runs
+// the old state machine.
+// ---------------------------------------------------------------------------
+
+const PRESET_SUBPATH = ".github/actions/osv-track-issue";
+const CORE_SUBPATH = ".github/actions/track-issue";
+const PRESET_COMPANIONS = { [PRESET_SUBPATH]: [CORE_SUBPATH] };
+
+/** A workflow pinning `subpath@sha`, one step per call site. */
+function workflowFor(subpath, sha) {
+  return [
+    "name: fixture",
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "jobs:",
+    "  demo:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    `      - uses: ${OWNER}/${subpath}@${sha}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * A repo shaped like the post-#389 split: a preset directory whose manifest
+ * runs a script in a sibling core directory that no `uses:` line names. Both
+ * are committed; the caller then edits the CORE in the working tree only.
+ */
+function makePresetRepo(label) {
+  const root = mkdtempSync(join(tmpdir(), `pinfresh-${label}-`));
+  git(root, "init", "-b", "main");
+  git(root, "config", "user.email", "fixture@example.invalid");
+  git(root, "config", "user.name", "Pin Freshness Fixture");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "config", "core.hooksPath", join(root, ".no-hooks"));
+
+  put(root, `${CORE_SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${CORE_SUBPATH}/track-issue.mjs`, "export const verdict = () => 'noop';\n");
+  put(root, `${PRESET_SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${PRESET_SUBPATH}/osv-track-issue.mjs`, "import '../track-issue/track-issue.mjs';\n");
+  git(root, "add", "-A");
+  git(root, "commit", "-m", "split the tracker into a core and a preset");
+  const after = git(root, "rev-parse", "HEAD");
+
+  return { root, after };
+}
+
+test("stale: an edit confined to the shared core marks every preset call site stale", () => {
+  const { root, after } = makePresetRepo("companion-stale");
+  track(root);
+  // Two call sites, both pinning the preset — neither names the core.
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+  put(root, ".github/workflows/two.yml", workflowFor(PRESET_SUBPATH, after));
+
+  // The edit is confined to the core, and nothing under the preset changes.
+  put(root, `${CORE_SUBPATH}/track-issue.mjs`, "export const verdict = () => 'create';\n");
+
+  // The premise, asserted rather than assumed: without the companion map this
+  // fixture reads perfectly fresh — which is the blind spot, not a pass.
+  const blind = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: {} });
+  assert.equal(blind.ok, true, "premise: a preset-only comparison sees no drift");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.scanned, 2);
+  assert.equal(result.stale.length, 2, "every call site of the preset is stale, not just one");
+  assert.equal(result.unreachable.length, 0);
+  for (const f of result.stale) {
+    assert.equal(f.subpath, PRESET_SUBPATH);
+    assert.match(f.reason, /track-issue\.mjs/, "the report names the drifting shared file");
+    assert.match(f.reason, /shared code it executes/, "and explains why a sibling tree is in scope");
+  }
+});
+
+test("stale: a file added to the shared core since the pinned SHA is drift", () => {
+  const { root, after } = makePresetRepo("companion-added");
+  track(root);
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+  put(root, `${CORE_SUBPATH}/helper.mjs`, "export const help = () => 1;\n");
+  git(root, "add", "-A");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+
+  assert.equal(result.ok, false);
+  assert.match(result.stale[0].reason, /helper\.mjs/);
+});
+
+test("clean: a pin carrying the current core AND preset exits 0", () => {
+  const { root, after } = makePresetRepo("companion-clean");
+  track(root);
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+  assert.equal(result.ok, true);
+});
+
+test("a subpath with no companions is compared exactly as before", () => {
+  const { root, after } = makePresetRepo("companion-unmapped");
+  track(root);
+  // Pin the CORE directly — it has no companions of its own, so a preset edit
+  // must not leak into its comparison.
+  put(root, ".github/workflows/one.yml", workflowFor(CORE_SUBPATH, after));
+  put(root, `${PRESET_SUBPATH}/osv-track-issue.mjs`, "// rewritten preset\n");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+  assert.equal(result.ok, true, "companions are directional, not symmetric");
+});
+
+test("diffSubpathAtSha: companions are unioned into both sides of the comparison", () => {
+  const presetPath = `${PRESET_SUBPATH}/action.yml`;
+  const corePath = `${CORE_SUBPATH}/action.yml`;
+  const presetBody = readFileSync(join(REPO_ROOT, presetPath), "utf8");
+  // The pinned side knows only the preset; the working side also has the core.
+  const fake = {
+    lsTree: (_sha, root) => (root === PRESET_SUBPATH ? [presetPath] : []),
+    lsFiles: (root) => (root === PRESET_SUBPATH ? [presetPath] : [corePath]),
+    show: () => presetBody,
+  };
+
+  const without = diffSubpathAtSha(fake, REPO_ROOT, "0".repeat(40), PRESET_SUBPATH);
+  assert.deepEqual(without, [], "the preset tree alone is identical at both ends");
+
+  const withCore = diffSubpathAtSha(fake, REPO_ROOT, "0".repeat(40), PRESET_SUBPATH, [CORE_SUBPATH]);
+  assert.deepEqual(withCore, [{ path: corePath, kind: "added" }]);
+});
+
+test("companionsFor: unmapped subpaths stand alone, and trailing slashes resolve", () => {
+  assert.deepEqual(companionsFor(".github/actions/setup-toolchain"), []);
+  assert.deepEqual(companionsFor(PRESET_SUBPATH, PRESET_COMPANIONS), [CORE_SUBPATH]);
+  assert.deepEqual(companionsFor(`${PRESET_SUBPATH}/`, PRESET_COMPANIONS), [CORE_SUBPATH]);
+});
+
+test("COMPANION_SUBPATHS: every mapped subpath and companion exists in this repo", () => {
+  // A map entry pointing at a path that no longer exists is a silently-dead
+  // guard — the pin would read fresh again with nothing flagging it.
+  for (const [subpath, companions] of Object.entries(COMPANION_SUBPATHS)) {
+    assert.ok(
+      resolveManifest(REPO_ROOT, subpath),
+      `${subpath} is mapped but resolves to no manifest`
+    );
+    for (const companion of companions) {
+      assert.ok(
+        resolveManifest(REPO_ROOT, companion),
+        `${subpath} names companion ${companion}, which resolves to no manifest`
+      );
+    }
+  }
+});
+
 // ---------------------------------------------------------------------------
 // AC-7 — third-party / local / docker references are never classified
 // ---------------------------------------------------------------------------

package/scripts/osv-track-issue.test.mjs

@@ -6,6 +6,14 @@
 // clears. That contract is the pure `decideVerdict` function — these tests
 // pin every branch of it, plus the marker round-trip and the gh-driven
 // lookup, without any network access.
+//
+// Story #389 moved that state machine into the generic
+// `.github/actions/track-issue` core and reduced this module to a preset over
+// it. Every test below predates that move and is retained verbatim: passing
+// unmodified is the evidence that the extraction preserved the OSV verdict
+// contract rather than rewriting it. The sections appended at the end cover
+// what the move newly put at risk — marker continuity against a LIVE advisory
+// issue, and the findings-envelope adapter.
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -15,8 +23,11 @@ import {
   extractDigest,
   digestMarker,
   buildIssueBody,
+  buildEnvUpdates,
   findTrackingIssue,
+  DIGEST_PREFIX,
   TRACKER_MARKER,
+  TRACKER_MARKER_KEY,
 } from "../.github/actions/osv-track-issue/osv-track-issue.mjs";
 
 const issueWithDigest = (number, digest) => ({
@@ -89,3 +100,147 @@ test("findTrackingIssue returns null when nothing carries the marker", () => {
   const runner = () => JSON.stringify([{ number: 1, body: "no marker" }]);
   assert.equal(findTrackingIssue({ repo: "acme/app", labels: [] }, runner), null);
 });
+
+// ---------------------------------------------------------------------------
+// Story #389 — marker continuity across the extraction
+//
+// These two strings are what a LIVE advisory issue in a consumer repo is keyed
+// on. A changed byte in either would leave that issue undiscoverable, so the
+// next scheduled run would open a SECOND one — the exact duplicate-spam
+// failure this action exists to prevent. They are therefore asserted as
+// literals, not derived from the module under test.
+// ---------------------------------------------------------------------------
+
+test("the tracker marker is byte-identical to the live one", () => {
+  assert.equal(TRACKER_MARKER, "<!-- mandrel:osv-advisory-tracker -->");
+  assert.equal(TRACKER_MARKER_KEY, "mandrel:osv-advisory-tracker");
+  assert.equal(DIGEST_PREFIX, "mandrel:osv-advisory-digest:");
+});
+
+test("a rendered OSV body round-trips its digest through the live digest prefix", () => {
+  const body = buildIssueBody({
+    digest: "cafe1234-3",
+    summary: "| advisory | package |",
+    repo: "acme/app",
+    branch: "main",
+  });
+
+  assert.ok(body.includes("<!-- mandrel:osv-advisory-tracker -->"));
+  assert.ok(body.includes("<!-- mandrel:osv-advisory-digest: cafe1234-3 -->"));
+  assert.equal(extractDigest(body), "cafe1234-3");
+});
+
+test("the OSV body is unchanged by the extraction — markers, prose, then summary", () => {
+  // Pinned against the shape the pre-#389 module produced. A silent body
+  // rewrite would churn every consumer's tracking issue on the next run.
+  const body = buildIssueBody({
+    digest: "d-1",
+    summary: "SUMMARY-BLOCK",
+    repo: "acme/app",
+    branch: "trunk",
+  });
+
+  assert.equal(
+    body,
+    [
+      "<!-- mandrel:osv-advisory-tracker -->",
+      "<!-- mandrel:osv-advisory-digest: d-1 -->",
+      "",
+      "Scheduled OSV advisory scan of `acme/app` (default branch `trunk`) found advisories at or",
+      "above the configured gate. This issue is maintained automatically by the",
+      "`advisory-scan.yml` reusable workflow — it is updated when the finding set changes",
+      "and closed automatically when the set clears. Do not edit the markers above.",
+      "",
+      "SUMMARY-BLOCK",
+    ].join("\n"),
+  );
+});
+
+test("an empty summary still renders the historical placeholder", () => {
+  const body = buildIssueBody({ digest: "d-1", summary: "", repo: "a/b", branch: "main" });
+  assert.match(body, /_\(no summary provided\)_/);
+});
+
+// ---------------------------------------------------------------------------
+// Story #389 — the findings-envelope adapter
+//
+// This module no longer performs the upsert; it translates the osv-scan
+// envelope into the generic TRACK_* contract and hands it to the shared core.
+// ---------------------------------------------------------------------------
+
+/** Collapse the adapter's entry list into a lookup for assertion. */
+const asMap = (entries) => Object.fromEntries(entries);
+
+test("the adapter forwards the live marker and digest prefix verbatim", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "abc123", counts: { blocking: 2 }, failOn: "high", summary: "s" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+
+  assert.equal(env.TRACK_MARKER, "mandrel:osv-advisory-tracker");
+  assert.equal(env.TRACK_DIGEST_PREFIX, "mandrel:osv-advisory-digest:");
+});
+
+test("the adapter passes the scanner's own digest rather than deriving one", () => {
+  // The scanner digest depends on finding identity (id + package + version +
+  // source); a derived one over a count-shaped label would churn on nothing.
+  const env = asMap(
+    buildEnvUpdates({ digest: "scanner-digest", counts: { blocking: 3 }, failOn: "high" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+  assert.equal(env.TRACK_DIGEST, "scanner-digest");
+});
+
+test("a blocking count of zero yields an empty failing set", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "empty-0", counts: { blocking: 0 }, failOn: "high" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+  assert.deepEqual(JSON.parse(env.TRACK_FAILED_ITEMS), []);
+});
+
+test("a non-zero blocking count yields a non-empty failing set", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "d", counts: { blocking: 4 }, failOn: "critical" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+  const items = JSON.parse(env.TRACK_FAILED_ITEMS);
+  assert.equal(items.length, 1);
+  assert.match(items[0], /4 advisory finding\(s\) at or above the 'critical' gate/);
+});
+
+test("the adapter neither refreshes on an unchanged set nor comments on change", () => {
+  // Both knobs default to today's OSV posture, so the preset must set neither.
+  const env = asMap(buildEnvUpdates({ digest: "d", counts: { blocking: 1 } }, { OSV_TRACK_REPO: "a/b" }));
+  assert.equal(env.TRACK_UNCHANGED_BEHAVIOR, undefined);
+  assert.equal(env.TRACK_COMMENT_ON_CHANGE, undefined);
+  assert.equal(env.TRACK_RUN_URL, undefined, "no run link — the body stays byte-stable across runs");
+});
+
+test("the adapter carries the caller's title, labels and branch through", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "d", counts: { blocking: 1 } }, {
+      OSV_TRACK_REPO: "acme/app",
+      OSV_TRACK_BRANCH: "trunk",
+      OSV_TRACK_TITLE: "Custom title",
+      OSV_TRACK_LABELS: "security,ops",
+    }),
+  );
+
+  assert.equal(env.TRACK_REPO, "acme/app");
+  assert.equal(env.TRACK_BRANCH, "trunk");
+  assert.equal(env.TRACK_TITLE, "Custom title");
+  assert.equal(env.TRACK_LABELS, "security,ops");
+  assert.match(env.TRACK_BODY_INTRO, /Scheduled OSV advisory scan of `acme\/app` \(default branch `trunk`\)/);
+  assert.match(env.TRACK_CLOSE_COMMENT, /no longer reports any finding at or above the gate/);
+});
+
+test("the adapter defaults the title to the documented one when the caller omits it", () => {
+  const env = asMap(buildEnvUpdates({ digest: "d", counts: { blocking: 1 } }, { OSV_TRACK_REPO: "a/b" }));
+  assert.equal(env.TRACK_TITLE, "OSV advisory scan — default branch findings");
+  assert.equal(env.TRACK_BRANCH, "main");
+});

package/scripts/track-issue.test.mjs

@@ -0,0 +1,375 @@
+// Unit coverage for the generic single-issue failure tracker (Story #389).
+//
+// The whole point of this action is a SINGLE tracked issue that does not spam:
+// it must open once, stay quiet while the failing set is unchanged, update only
+// on a real change, and close when the set clears. That contract is the pure
+// `decideVerdict` function — these tests pin every branch of it, plus the
+// failing-set derivation, the digest, the marker round-trip and the gh-driven
+// lookup, without any network access.
+//
+// Run: node --test scripts/track-issue.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  DEFAULT_CLOSE_COMMENT,
+  DEFAULT_INTRO,
+  buildIssueBody,
+  computeDigest,
+  decideVerdict,
+  defaultDigestPrefix,
+  digestMarker,
+  extractDigest,
+  failingJobs,
+  findTrackingIssue,
+  markerKey,
+  markerLine,
+  renderEnvEntry,
+  resolveConfig,
+} from "../.github/actions/track-issue/track-issue.mjs";
+
+const MARKER = "acme:nightly-tracker";
+const PREFIX = defaultDigestPrefix(MARKER);
+const OPTS = { digestPrefix: PREFIX };
+
+/** An open tracked issue whose body carries `digest`. */
+const issueWithDigest = (number, digest) => ({
+  number,
+  body: buildIssueBody({ marker: MARKER, digestPrefix: PREFIX, digest, detail: "…" }),
+});
+
+// ---------------------------------------------------------------------------
+// AC-3 — the four-way state machine survives the extraction unchanged
+// ---------------------------------------------------------------------------
+
+test("CREATE when items are failing and no tracking issue is open", () => {
+  const v = decideVerdict(null, { failedCount: 2, digest: "abcd1234" }, OPTS);
+  assert.equal(v.action, "create");
+});
+
+test("UPDATE when the failing-set digest changed since the issue was written", () => {
+  const existing = issueWithDigest(42, "abcd1234");
+  const v = decideVerdict(existing, { failedCount: 3, digest: "zzzz9999" }, OPTS);
+  assert.equal(v.action, "update");
+});
+
+test("CLOSE when the failing set is now empty but an issue is still open", () => {
+  const existing = issueWithDigest(42, "abcd1234");
+  const v = decideVerdict(existing, { failedCount: 0, digest: "green-0" }, OPTS);
+  assert.equal(v.action, "close");
+});
+
+test("NOOP when nothing is failing and there is no issue to close", () => {
+  const v = decideVerdict(null, { failedCount: 0, digest: "green-0" }, OPTS);
+  assert.equal(v.action, "noop");
+});
+
+// ---------------------------------------------------------------------------
+// AC-4 — the never-a-second-issue invariant, asserted on the core
+// ---------------------------------------------------------------------------
+
+test("two consecutive failing runs against an open marked issue never yield CREATE", () => {
+  // Run 1 opens the issue; the tracker then finds it on every subsequent run.
+  assert.equal(decideVerdict(null, { failedCount: 1, digest: "d1" }, OPTS).action, "create");
+  const open = issueWithDigest(7, "d1");
+
+  // Run 2 — same failing set. Run 3 — a DIFFERENT failing set. Neither may
+  // create: a second issue is the duplicate-spam failure this action prevents.
+  const second = decideVerdict(open, { failedCount: 1, digest: "d1" }, OPTS);
+  const third = decideVerdict(open, { failedCount: 4, digest: "d2" }, OPTS);
+
+  assert.equal(second.action, "noop");
+  assert.equal(third.action, "update");
+  for (const v of [second, third]) assert.notEqual(v.action, "create");
+});
+
+test("an unparseable body never yields CREATE while an issue is open", () => {
+  // A human editing the body away is not a licence to open a second issue: the
+  // marker still found the issue, so the worst case is a redundant UPDATE.
+  const mangled = { number: 9, body: "someone deleted the digest marker" };
+  assert.equal(decideVerdict(mangled, { failedCount: 2, digest: "d9" }, OPTS).action, "update");
+});
+
+// ---------------------------------------------------------------------------
+// AC-5 — only `failure` counts; cancelled/skipped are not failures
+// ---------------------------------------------------------------------------
+
+test("failingJobs counts only entries whose result is exactly `failure`", () => {
+  const needs = {
+    build: { result: "success" },
+    test: { result: "failure" },
+    deploy: { result: "cancelled" },
+    docs: { result: "skipped" },
+    lint: { result: "failure" },
+  };
+  assert.deepEqual(failingJobs(needs), ["lint", "test"]);
+});
+
+test("a job-results payload of only cancelled/skipped never yields CREATE", () => {
+  // A self-hosted fleet going down produces a wall of `cancelled` — raising an
+  // issue for that is precisely the noise this tracker exists to avoid.
+  const noise = { a: { result: "cancelled" }, b: { result: "skipped" }, c: { result: "success" } };
+  const failed = failingJobs(noise);
+  assert.deepEqual(failed, []);
+
+  const digest = computeDigest(failed);
+  assert.equal(
+    decideVerdict(null, { failedCount: failed.length, digest }, OPTS).action,
+    "noop",
+    "no open issue → nothing to do",
+  );
+  assert.equal(
+    decideVerdict(issueWithDigest(3, "d1"), { failedCount: failed.length, digest }, OPTS).action,
+    "close",
+    "an open issue is closed, because nothing is actually failing",
+  );
+});
+
+test("resolveConfig derives an empty failing set from an all-cancelled job payload", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_JOB_RESULTS: JSON.stringify({ a: { result: "cancelled" }, b: { result: "skipped" } }),
+  });
+  assert.deepEqual(cfg.failedItems, []);
+  assert.equal(cfg.digest, "green-0");
+});
+
+// ---------------------------------------------------------------------------
+// AC-6 — unchanged-set behaviour is selectable, defaulting to today's posture
+// ---------------------------------------------------------------------------
+
+test("an unchanged digest is NOOP by default", () => {
+  const existing = issueWithDigest(42, "same-digest");
+  const v = decideVerdict(existing, { failedCount: 2, digest: "same-digest" }, OPTS);
+  assert.equal(v.action, "noop");
+  assert.equal(v.changed, false);
+});
+
+test("the same unchanged digest is UPDATE under `unchanged-behavior: refresh`", () => {
+  const existing = issueWithDigest(42, "same-digest");
+  const v = decideVerdict(
+    existing,
+    { failedCount: 2, digest: "same-digest" },
+    { ...OPTS, unchangedBehavior: "refresh" },
+  );
+  assert.equal(v.action, "update");
+  assert.equal(v.changed, false, "a refresh is not a change — it must not fire a change comment");
+});
+
+test("resolveConfig defaults unchanged-behavior to noop and rejects an unknown value", () => {
+  const base = { TRACK_MARKER: MARKER, TRACK_REPO: "acme/app" };
+  assert.equal(resolveConfig(base).unchangedBehavior, "noop");
+  assert.equal(resolveConfig({ ...base, TRACK_UNCHANGED_BEHAVIOR: "refresh" }).unchangedBehavior, "refresh");
+  assert.equal(
+    resolveConfig({ ...base, TRACK_UNCHANGED_BEHAVIOR: "shout" }).unchangedBehavior,
+    "noop",
+    "an unrecognised value falls back to the quiet posture rather than spamming",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Marker + digest contract
+// ---------------------------------------------------------------------------
+
+test("the action owns both marker lines and they round-trip through a body", () => {
+  const body = buildIssueBody({
+    marker: MARKER,
+    digestPrefix: PREFIX,
+    digest: "deadbeef",
+    intro: "watching the nightly",
+    detail: "one job is red",
+  });
+
+  assert.ok(body.includes(markerLine(MARKER)));
+  assert.equal(extractDigest(body, PREFIX), "deadbeef");
+  assert.equal(extractDigest("no markers here", PREFIX), null);
+  assert.match(body, /watching the nightly/);
+  assert.match(body, /one job is red/);
+});
+
+test("a marker supplied as a rendered comment is not double-wrapped", () => {
+  // A caller that hands over `<!-- k -->` must still produce `<!-- k -->` —
+  // a double-wrapped marker would never match the live issue again.
+  assert.equal(markerKey("<!-- acme:x -->"), "acme:x");
+  assert.equal(markerLine("<!-- acme:x -->"), "<!-- acme:x -->");
+});
+
+test("the legacy `--!>` comment terminator is stripped, not left in the key", () => {
+  // `--!>` closes an HTML comment just as `-->` does. A stripper blind to it
+  // leaves a stray `!` in the key, so the rendered marker stops matching the
+  // live issue and the next run opens a second one.
+  assert.equal(markerKey("<!-- acme:x --!>"), "acme:x");
+  assert.equal(markerLine("<!-- acme:x --!>"), "<!-- acme:x -->");
+});
+
+test("a digest marker closed with `--!>` is still recovered", () => {
+  assert.equal(extractDigest("<!-- acme:d: abc123 --!>", "acme:d:"), "abc123");
+});
+
+test("extractDigest skips non-matching comments and needs a single token", () => {
+  const body = [
+    "<!-- acme:nightly-tracker -->",
+    "<!-- unrelated: note -->",
+    "<!-- acme:d: two tokens -->",
+    "<!-- acme:d: realdigest -->",
+  ].join("\n");
+  assert.equal(extractDigest(body, "acme:d:"), "realdigest");
+  assert.equal(extractDigest("<!-- acme:d: -->", "acme:d:"), null);
+  assert.equal(extractDigest("<!-- acme:d: unterminated", "acme:d:"), null);
+});
+
+test("the digest prefix defaults from the marker but is overridable", () => {
+  assert.equal(defaultDigestPrefix(MARKER), "acme:nightly-tracker-digest:");
+  assert.match(digestMarker("abc", "custom:pfx:"), /<!-- custom:pfx: abc -->/);
+  assert.equal(extractDigest(digestMarker("abc", "custom:pfx:"), "custom:pfx:"), "abc");
+});
+
+test("a regex-special digest prefix is matched literally, not as a pattern", () => {
+  const prefix = "acme(v1).digest:";
+  assert.equal(extractDigest(digestMarker("xyz", prefix), prefix), "xyz");
+  assert.equal(extractDigest("<!-- acmeXv1Yxdigest: xyz -->", prefix), null);
+});
+
+test("body defaults fill in when the caller supplies no prose", () => {
+  const body = buildIssueBody({ marker: MARKER, digestPrefix: PREFIX, digest: "d" });
+  assert.ok(body.includes(DEFAULT_INTRO));
+  assert.match(body, /_\(no detail provided\)_/);
+  assert.ok(!body.includes("Latest run:"), "an absent run-url omits the line entirely");
+});
+
+test("a run-url is rendered only when supplied", () => {
+  const body = buildIssueBody({
+    marker: MARKER,
+    digestPrefix: PREFIX,
+    digest: "d",
+    runUrl: "https://example.invalid/run/1",
+  });
+  assert.match(body, /Latest run: https:\/\/example\.invalid\/run\/1/);
+});
+
+// ---------------------------------------------------------------------------
+// Digest derivation
+// ---------------------------------------------------------------------------
+
+test("computeDigest is order-independent and de-duplicating", () => {
+  assert.equal(computeDigest(["b", "a"]), computeDigest(["a", "b"]));
+  assert.equal(computeDigest(["a", "a", "b"]), computeDigest(["a", "b"]));
+  assert.notEqual(computeDigest(["a"]), computeDigest(["a", "b"]));
+  assert.match(computeDigest(["a"]), /^[0-9a-f]{12}$/);
+});
+
+test("computeDigest marks an empty set legibly rather than hashing nothing", () => {
+  assert.equal(computeDigest([]), "green-0");
+  assert.equal(computeDigest(undefined), "green-0");
+});
+
+// ---------------------------------------------------------------------------
+// Environment contract
+// ---------------------------------------------------------------------------
+
+test("failed-items takes precedence over job-results when both are supplied", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: JSON.stringify(["explicit"]),
+    TRACK_JOB_RESULTS: JSON.stringify({ ignored: { result: "failure" } }),
+  });
+  assert.deepEqual(cfg.failedItems, ["explicit"]);
+});
+
+test("an explicit digest wins over the derived one", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: JSON.stringify(["a"]),
+    TRACK_DIGEST: "caller-supplied",
+  });
+  assert.equal(cfg.digest, "caller-supplied");
+});
+
+test("malformed failed-items is an error, not a silently-empty failing set", () => {
+  // Swallowing a parse error here would CLOSE a live tracked issue while the
+  // failures it names are still happening.
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: "{not json",
+  });
+  assert.match(cfg.error, /TRACK_FAILED_ITEMS/);
+
+  const notAnArray = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: '{"a":1}',
+  });
+  assert.match(notAnArray.error, /JSON string array/);
+});
+
+test("malformed job-results is an error rather than an empty failing set", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_JOB_RESULTS: "{not json",
+  });
+  assert.match(cfg.error, /TRACK_JOB_RESULTS/);
+});
+
+test("resolveConfig splits labels and defaults the quiet knobs", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_LABELS: " ci , ,tracking ",
+  });
+  assert.deepEqual(cfg.labels, ["ci", "tracking"]);
+  assert.equal(cfg.commentOnChange, false);
+  assert.equal(cfg.dryRun, false);
+  assert.equal(cfg.branch, "main");
+  assert.equal(cfg.closeComment, DEFAULT_CLOSE_COMMENT);
+});
+
+test("renderEnvEntry escalates a multi-line value to the heredoc form", () => {
+  assert.equal(renderEnvEntry("K", "one"), "K=one\n");
+  const multi = renderEnvEntry("K", "one\ntwo");
+  assert.match(multi, /^K<<K_EOF_7f3a\none\ntwo\nK_EOF_7f3a\n$/);
+  assert.throws(() => renderEnvEntry("K", "a\nK_EOF_7f3a"), /delimiter/);
+});
+
+// ---------------------------------------------------------------------------
+// gh lookup
+// ---------------------------------------------------------------------------
+
+test("findTrackingIssue confirms the marker rather than trusting the search hint", () => {
+  const calls = [];
+  const runner = (args, opts) => {
+    calls.push({ args, opts });
+    // gh's `in:body` search is fuzzy — return one true match and one false positive.
+    return JSON.stringify([
+      { number: 99, body: "unrelated issue mentioning nightly-tracker in prose" },
+      { number: 100, body: `${markerLine(MARKER)}\n${digestMarker("x-1", PREFIX)}\nbody` },
+    ]);
+  };
+
+  const found = findTrackingIssue({ repo: "acme/app", labels: ["ci"], marker: MARKER }, runner);
+
+  assert.equal(found.number, 100);
+  assert.ok(calls[0].args.includes("--label"));
+  assert.ok(calls[0].args.includes("ci"));
+});
+
+test("findTrackingIssue returns null when nothing carries the marker", () => {
+  const runner = () => JSON.stringify([{ number: 1, body: "no marker" }]);
+  assert.equal(findTrackingIssue({ repo: "acme/app", labels: [], marker: MARKER }, runner), null);
+});
+
+test("findTrackingIssue surfaces a gh failure rather than reporting no issue", () => {
+  // Reporting "no issue" on a failed lookup would open a duplicate.
+  const runner = () => {
+    throw new Error("gh: not authenticated");
+  };
+  assert.throws(
+    () => findTrackingIssue({ repo: "acme/app", labels: [], marker: MARKER }, runner),
+    /gh issue list failed/,
+  );
+});