mandrel-platform 0.17.2 → 0.19.0

package/scripts/lib/uses-pins.test.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * uses-pins.test.mjs — node:test suite for the shared `uses:`-line / SHA-pin
+ * primitives (`scripts/lib/uses-pins.mjs`, Story #203).
+ *
+ * Covers value stripping, line parsing, reference classification (incl. the
+ * new `subpath` field), the 40-char-SHA predicate, and the intra-repo
+ * single-pin invariant that `check-action-pins.mjs` now enforces. Pure — no
+ * temp dirs, no git, fully offline.
+ *
+ * Run: node --test scripts/lib/uses-pins.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  DEFAULT_FIRST_PARTY_OWNER,
+  stripUsesValue,
+  parseUsesLine,
+  classifyUses,
+  isSha40,
+  collectFirstPartyPins,
+  findSinglePinViolations,
+} from "./uses-pins.mjs";
+
+const SHA = "11bd71901bbe5b1630ceea73d27597364c9af683"; // 40 hex
+const SHA2 = "0000000000000000000000000000000000000000"; // 40 hex, distinct
+const SHORT = "11bd719"; // 7 hex
+
+// ---------------------------------------------------------------------------
+// isSha40
+// ---------------------------------------------------------------------------
+
+test("isSha40 accepts exactly 40 hex chars (any case)", () => {
+  assert.equal(isSha40(SHA), true);
+  assert.equal(isSha40(SHA.toUpperCase()), true);
+});
+
+test("isSha40 rejects tags, short SHAs, branches, and off-by-one", () => {
+  assert.equal(isSha40("v4"), false);
+  assert.equal(isSha40(SHORT), false);
+  assert.equal(isSha40("main"), false);
+  assert.equal(isSha40(SHA + "0"), false); // 41 chars
+  assert.equal(isSha40("g".repeat(40)), false); // non-hex
+});
+
+// ---------------------------------------------------------------------------
+// stripUsesValue
+// ---------------------------------------------------------------------------
+
+test("stripUsesValue drops the trailing # tag comment", () => {
+  assert.equal(
+    stripUsesValue(`actions/checkout@${SHA} # v4.2.2`),
+    `actions/checkout@${SHA}`
+  );
+});
+
+test("stripUsesValue unwraps surrounding quotes and no-comment inputs", () => {
+  assert.equal(stripUsesValue(`actions/checkout@${SHA}`), `actions/checkout@${SHA}`);
+  assert.equal(stripUsesValue(`"actions/checkout@${SHA}"`), `actions/checkout@${SHA}`);
+  assert.equal(stripUsesValue(`'actions/checkout@${SHA}'`), `actions/checkout@${SHA}`);
+});
+
+// ---------------------------------------------------------------------------
+// parseUsesLine
+// ---------------------------------------------------------------------------
+
+test("parseUsesLine returns the bare ref for a mapping-key uses line", () => {
+  assert.equal(parseUsesLine(`      - uses: actions/checkout@${SHA} # v4`), `actions/checkout@${SHA}`);
+  assert.equal(parseUsesLine(`  uses: actions/checkout@${SHA}`), `actions/checkout@${SHA}`);
+});
+
+test("parseUsesLine returns null for comments and non-uses lines", () => {
+  assert.equal(parseUsesLine("# uses: actions/checkout@v4"), null);
+  assert.equal(parseUsesLine("    steps:"), null);
+  assert.equal(parseUsesLine("      run: echo uses: not-a-key"), null);
+});
+
+// ---------------------------------------------------------------------------
+// classifyUses (incl. subpath)
+// ---------------------------------------------------------------------------
+
+test("classifyUses flags external owner/repo as third-party with subpath", () => {
+  const c = classifyUses(`github/codeql-action/analyze@${SHA}`);
+  assert.equal(c.kind, "third-party");
+  assert.equal(c.owner, "github/codeql-action");
+  assert.equal(c.subpath, "analyze");
+  assert.equal(c.ref, SHA);
+});
+
+test("classifyUses treats the default first-party owner as exempt and exposes subpath", () => {
+  const c = classifyUses(
+    `dsj1984/mandrel-platform/.github/actions/setup-toolchain@${SHA}`
+  );
+  assert.equal(c.kind, "first-party");
+  assert.equal(c.owner, DEFAULT_FIRST_PARTY_OWNER);
+  assert.equal(c.subpath, ".github/actions/setup-toolchain");
+  assert.equal(c.ref, SHA);
+});
+
+test("classifyUses honours a custom first-party owner", () => {
+  const c = classifyUses(`my-org/my-repo/.github/workflows/x.yml@v1`, "my-org/my-repo");
+  assert.equal(c.kind, "first-party");
+  assert.equal(c.subpath, ".github/workflows/x.yml");
+});
+
+test("classifyUses exempts local and docker refs", () => {
+  assert.equal(classifyUses("./.github/actions/foo").kind, "local");
+  assert.equal(classifyUses("../shared/action").kind, "local");
+  assert.equal(classifyUses("docker://alpine:3.19").kind, "docker");
+});
+
+test("classifyUses reports empty subpath for a bare owner/repo self-ref", () => {
+  const c = classifyUses(`dsj1984/mandrel-platform@${SHA}`);
+  assert.equal(c.kind, "first-party");
+  assert.equal(c.subpath, "");
+});
+
+test("classifyUses returns unparseable for a ref with no @ or too few segments", () => {
+  assert.equal(classifyUses("").kind, "unparseable");
+  assert.equal(classifyUses("actions/checkout").kind, "unparseable");
+  assert.equal(classifyUses(`justowner@${SHA}`).kind, "unparseable");
+});
+
+// ---------------------------------------------------------------------------
+// collectFirstPartyPins
+// ---------------------------------------------------------------------------
+
+test("collectFirstPartyPins keys first-party subpath refs by target", () => {
+  const content = [
+    "    steps:",
+    `      - uses: dsj1984/mandrel-platform/.github/actions/setup-toolchain@${SHA}`,
+    `      - uses: actions/checkout@${SHA}`, // third-party → ignored
+    `      - uses: dsj1984/mandrel-platform@${SHA}`, // bare self-ref, no subpath → ignored
+  ].join("\n");
+  const byTarget = collectFirstPartyPins(content, "wf.yml");
+  assert.equal(byTarget.size, 1);
+  const occs = byTarget.get("dsj1984/mandrel-platform/.github/actions/setup-toolchain");
+  assert.equal(occs.length, 1);
+  assert.equal(occs[0].ref, SHA);
+  assert.equal(occs[0].line, 2);
+  assert.equal(occs[0].file, "wf.yml");
+});
+
+// ---------------------------------------------------------------------------
+// findSinglePinViolations (the single-pin invariant)
+// ---------------------------------------------------------------------------
+
+test("findSinglePinViolations is clean when a target is pinned consistently", () => {
+  const files = [
+    {
+      file: "a.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+    },
+    {
+      file: "b.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+    },
+  ];
+  assert.deepEqual(findSinglePinViolations(files), []);
+});
+
+test("findSinglePinViolations flags a target pinned to two different SHAs", () => {
+  const files = [
+    {
+      file: "a.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+    },
+    {
+      file: "b.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA2}`,
+    },
+  ];
+  const v = findSinglePinViolations(files);
+  assert.equal(v.length, 1);
+  assert.equal(v[0].target, "dsj1984/mandrel-platform/.github/actions/foo");
+  assert.equal(v[0].shas.length, 2);
+  assert.ok(v[0].shas.includes(SHA));
+  assert.ok(v[0].shas.includes(SHA2));
+  assert.equal(v[0].occurrences.length, 2);
+  assert.deepEqual(
+    v[0].occurrences.map((o) => o.file).sort(),
+    ["a.yml", "b.yml"]
+  );
+});
+
+test("findSinglePinViolations catches drift within a single file too", () => {
+  const files = [
+    {
+      file: "a.yml",
+      content: [
+        `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+        `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA2}`,
+      ].join("\n"),
+    },
+  ];
+  const v = findSinglePinViolations(files);
+  assert.equal(v.length, 1);
+  assert.equal(v[0].shas.length, 2);
+});
+
+test("findSinglePinViolations ignores third-party targets (cross-repo dashboard owns those)", () => {
+  const files = [
+    { file: "a.yml", content: `      - uses: github/codeql-action/analyze@${SHA}` },
+    { file: "b.yml", content: `      - uses: github/codeql-action/analyze@${SHA2}` },
+  ];
+  assert.deepEqual(findSinglePinViolations(files), []);
+});
+
+test("findSinglePinViolations honours a custom first-party owner", () => {
+  const files = [
+    { file: "a.yml", content: `      - uses: my-org/my-repo/actions/x@${SHA}` },
+    { file: "b.yml", content: `      - uses: my-org/my-repo/actions/x@${SHA2}` },
+  ];
+  const v = findSinglePinViolations(files, "my-org/my-repo");
+  assert.equal(v.length, 1);
+  assert.equal(v[0].target, "my-org/my-repo/actions/x");
+});

package/scripts/lib/walk.mjs

@@ -0,0 +1,74 @@
+/**
+ * scripts/lib/walk.mjs
+ *
+ * The single directory-discovery seam for the pin-tooling scripts. Both
+ * `check-action-pins.mjs` and `check-workflow-portability.mjs` had grown their
+ * own `listWorkflowFiles` / `listActionFiles` pair — same intent, subtly
+ * different code (one sorted, one didn't; one guarded `statSync`, one didn't).
+ * Story #203 consolidates them here.
+ *
+ * All discovery is best-effort: a missing directory or an unreadable entry
+ * yields `[]` / is skipped rather than throwing, so a repo without a
+ * `.github/actions/` tree lints cleanly. Results are sorted for deterministic
+ * output.
+ */
+
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * List `*.yml` / `*.yaml` files directly under a workflows dir
+ * (non-recursive — GitHub only runs top-level workflow files).
+ *
+ * @param {string} dir
+ * @returns {string[]} Sorted absolute/relative paths (as joined from `dir`).
+ */
+export function listWorkflowFiles(dir) {
+  if (!existsSync(dir)) return [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((f) => /\.ya?ml$/.test(f))
+    .map((f) => join(dir, f))
+    .filter((p) => {
+      try {
+        return statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+}
+
+/**
+ * Recursively list composite `action.yml` / `action.yaml` files under a dir.
+ *
+ * @param {string} dir
+ * @returns {string[]} Sorted paths.
+ */
+export function listActionFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) {
+        walk(full);
+      } else if (/^action\.ya?ml$/.test(e.name)) {
+        out.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return out.sort();
+}

package/scripts/platform-repair.mjs

@@ -68,7 +68,9 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { buildReport, defaultGhRunner, isFullSha } from "./check-pin-drift.mjs";
+import { buildReport, isFullSha } from "./check-pin-drift.mjs";
+import { defaultGhRunner } from "./lib/gh-json.mjs";
+import { parseSemver } from "./lib/semver-duration.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -188,12 +190,16 @@ export function describeDrift(result) {
     const short = v.pinnedSha ? v.pinnedSha.slice(0, 7) : "?";
     out.push(`**Release lag** — workflow \`uses:\` pins \`${short}\`, behind the latest release.`);
   }
+  // Normalize the npm version through the shared parser (Story #198): the
+  // detector already emits a dotted triple, but re-parsing keeps the repair
+  // PR body robust to a raw spec ever reaching here (`^0.11.7` → `0.11.7`).
+  const npmVersion = parseSemver(result.npm?.version ?? null) ?? result.npm?.version ?? "?";
   if (result.surfaceSkew === true) {
     out.push(
-      `**Surface skew** — the npm \`mandrel-platform\` dependency (\`${result.npm?.version ?? "?"}\`) and the workflow \`uses:\` pins are on different releases.`,
+      `**Surface skew** — the npm \`mandrel-platform\` dependency (\`${npmVersion}\`) and the workflow \`uses:\` pins are on different releases.`,
     );
   } else if (result.npm?.npmState === "lagging") {
-    out.push(`**npm lag** — \`mandrel-platform@${result.npm.version}\` is behind the latest release.`);
+    out.push(`**npm lag** — \`mandrel-platform@${npmVersion}\` is behind the latest release.`);
   }
   return out;
 }