mandrel-platform 0.18.0 → 0.19.0

package/scripts/lib/args.mjs

@@ -0,0 +1,93 @@
+/**
+ * scripts/lib/args.mjs
+ *
+ * The single argv-parsing seam shared by the pin-tooling CLIs
+ * (`check-action-pins.mjs`, `check-workflow-portability.mjs`, …). Each of
+ * those scripts had grown its own hand-rolled `parseArgs` — one throwing on
+ * an unknown flag, one silently ignoring it, and both re-implementing the
+ * same "take the next argv slot as this flag's value" dance. They had already
+ * drifted (different alias support, different unknown-flag policy), which is
+ * exactly the duplication Story #203 consolidates.
+ *
+ * `parseFlags(argv, spec)` is a tiny, dependency-free flag reader driven by a
+ * declarative spec. It intentionally does NOT try to be a full getopt: it
+ * supports the two shapes the pin tooling actually uses —
+ *
+ *   • `string` flags   — `--workflows-dir <value>` (optionally with aliases,
+ *                        e.g. `-w`), consuming the next argv slot as the value.
+ *   • `boolean` flags  — `--no-pin-check`, `--help` (present ⇒ the configured
+ *                        boolean value, default the inverse).
+ *
+ * The unknown-flag policy is a per-call knob (`onUnknown`) so a strict lint
+ * (fail loudly on a typo'd flag) and a lenient CLI (ignore stray args) can
+ * share one parser without either losing its behavior.
+ *
+ * This module reads no environment and performs no I/O, so the sibling
+ * `args.test.mjs` suite exercises it entirely offline.
+ */
+
+/**
+ * @typedef {Object} FlagSpec
+ * @property {"string" | "boolean"} type  How to consume the flag.
+ * @property {string} dest               The result key to write.
+ * @property {*} [default]               Default value when the flag is absent.
+ * @property {boolean} [value]           For a boolean flag, the value to set
+ *                                       when the flag IS present (default true).
+ */
+
+/**
+ * Parse an argv slice (the array AFTER `node script.mjs`) into an options
+ * object driven by `spec`.
+ *
+ * @param {string[]} argv
+ * @param {Object} spec
+ * @param {Record<string, FlagSpec>} spec.flags  Map of canonical flag token
+ *   (e.g. `"--workflows-dir"`) to its {@link FlagSpec}.
+ * @param {Record<string, string>} [spec.aliases]  Map of alias token
+ *   (e.g. `"-w"`) to a canonical flag token present in `spec.flags`.
+ * @param {"throw" | "ignore"} [spec.onUnknown]  What to do with an argument
+ *   that is not a known flag or alias. `"throw"` (default) fails loudly;
+ *   `"ignore"` skips it.
+ * @returns {Record<string, *>} The resolved options, seeded from each flag's
+ *   `default`.
+ */
+export function parseFlags(argv, spec) {
+  const flags = spec?.flags ?? {};
+  const aliases = spec?.aliases ?? {};
+  const onUnknown = spec?.onUnknown ?? "throw";
+
+  // Seed the result with every flag's declared default.
+  const opts = {};
+  for (const def of Object.values(flags)) {
+    opts[def.dest] = "default" in def ? def.default : undefined;
+  }
+
+  const canonical = (arg) => {
+    if (Object.prototype.hasOwnProperty.call(flags, arg)) return arg;
+    if (Object.prototype.hasOwnProperty.call(aliases, arg)) return aliases[arg];
+    return null;
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const key = canonical(arg);
+    if (key === null) {
+      if (onUnknown === "ignore") continue;
+      throw new Error(`unknown argument "${arg}"`);
+    }
+    const def = flags[key];
+    if (def.type === "boolean") {
+      opts[def.dest] = "value" in def ? def.value : true;
+      continue;
+    }
+    // string flag: consume the next argv slot as the value.
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      throw new Error(`missing value for "${arg}"`);
+    }
+    opts[def.dest] = next;
+    i++;
+  }
+
+  return opts;
+}

package/scripts/lib/args.test.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * args.test.mjs — node:test suite for the shared argv parser
+ * (`scripts/lib/args.mjs`, Story #203).
+ *
+ * Covers the two flag shapes the pin tooling uses (string-with-value and
+ * boolean-present), alias resolution, default seeding, and both unknown-flag
+ * policies (throw for the strict ratchet, ignore for the lenient portability
+ * CLI). Pure — no I/O, fully offline.
+ *
+ * Run: node --test scripts/lib/args.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseFlags } from "./args.mjs";
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+test("parseFlags seeds each flag's declared default when absent", () => {
+  const opts = parseFlags([], {
+    flags: {
+      "--dir": { type: "string", dest: "dir", default: ".github/workflows" },
+      "--flag": { type: "boolean", dest: "flag", default: false },
+    },
+  });
+  assert.deepEqual(opts, { dir: ".github/workflows", flag: false });
+});
+
+test("parseFlags leaves dest undefined when a flag has no default", () => {
+  const opts = parseFlags([], {
+    flags: { "--dir": { type: "string", dest: "dir" } },
+  });
+  assert.equal("dir" in opts, true);
+  assert.equal(opts.dir, undefined);
+});
+
+// ---------------------------------------------------------------------------
+// String flags
+// ---------------------------------------------------------------------------
+
+test("parseFlags reads a string flag's value from the next slot", () => {
+  const opts = parseFlags(["--dir", "wf"], {
+    flags: { "--dir": { type: "string", dest: "dir", default: null } },
+  });
+  assert.equal(opts.dir, "wf");
+});
+
+test("parseFlags throws when a string flag is missing its value", () => {
+  assert.throws(
+    () =>
+      parseFlags(["--dir"], {
+        flags: { "--dir": { type: "string", dest: "dir" } },
+      }),
+    /missing value for "--dir"/
+  );
+});
+
+test("parseFlags treats a following --flag as a missing value, not the value", () => {
+  assert.throws(
+    () =>
+      parseFlags(["--dir", "--other"], {
+        flags: {
+          "--dir": { type: "string", dest: "dir" },
+          "--other": { type: "boolean", dest: "other" },
+        },
+      }),
+    /missing value for "--dir"/
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Boolean flags
+// ---------------------------------------------------------------------------
+
+test("parseFlags sets a boolean flag to its configured value when present", () => {
+  const opts = parseFlags(["--no-pin-check"], {
+    flags: {
+      "--no-pin-check": { type: "boolean", dest: "pinCheck", value: false, default: true },
+    },
+  });
+  assert.equal(opts.pinCheck, false);
+});
+
+test("parseFlags defaults a boolean present-value to true", () => {
+  const opts = parseFlags(["--help"], {
+    flags: { "--help": { type: "boolean", dest: "help", default: false } },
+  });
+  assert.equal(opts.help, true);
+});
+
+// ---------------------------------------------------------------------------
+// Aliases
+// ---------------------------------------------------------------------------
+
+test("parseFlags resolves an alias to its canonical flag", () => {
+  const opts = parseFlags(["-w", "wf", "-h"], {
+    flags: {
+      "--workflows-dir": { type: "string", dest: "workflowsDir", default: null },
+      "--help": { type: "boolean", dest: "help", default: false },
+    },
+    aliases: { "-w": "--workflows-dir", "-h": "--help" },
+  });
+  assert.equal(opts.workflowsDir, "wf");
+  assert.equal(opts.help, true);
+});
+
+// ---------------------------------------------------------------------------
+// Unknown-flag policy
+// ---------------------------------------------------------------------------
+
+test("parseFlags throws on an unknown flag by default", () => {
+  assert.throws(
+    () => parseFlags(["--nope"], { flags: {} }),
+    /unknown argument "--nope"/
+  );
+});
+
+test("parseFlags ignores unknown args when onUnknown is 'ignore'", () => {
+  const opts = parseFlags(["--nope", "--dir", "wf", "stray"], {
+    flags: { "--dir": { type: "string", dest: "dir", default: null } },
+    onUnknown: "ignore",
+  });
+  assert.equal(opts.dir, "wf");
+});
+
+// ---------------------------------------------------------------------------
+// Realistic combined spec (mirrors check-action-pins.mjs)
+// ---------------------------------------------------------------------------
+
+test("parseFlags handles a full mixed spec end-to-end", () => {
+  const spec = {
+    flags: {
+      "--workflows-dir": { type: "string", dest: "workflowsDir", default: ".github/workflows" },
+      "--actions-dir": { type: "string", dest: "actionsDir", default: ".github/actions" },
+      "--first-party-owner": { type: "string", dest: "firstPartyOwner", default: "dsj1984/mandrel-platform" },
+      "--no-single-pin": { type: "boolean", dest: "singlePin", value: false, default: true },
+    },
+    onUnknown: "throw",
+  };
+  const opts = parseFlags(
+    ["--first-party-owner", "x/y", "--workflows-dir", "wf", "--no-single-pin"],
+    spec
+  );
+  assert.equal(opts.firstPartyOwner, "x/y");
+  assert.equal(opts.workflowsDir, "wf");
+  assert.equal(opts.actionsDir, ".github/actions");
+  assert.equal(opts.singlePin, false);
+});

package/scripts/lib/gh-json.mjs

@@ -0,0 +1,119 @@
+/**
+ * scripts/lib/gh-json.mjs
+ *
+ * The single GitHub-access seam shared by the pin-drift dashboard
+ * (`check-pin-drift.mjs`) and the pin-repair loop (`platform-repair.mjs`).
+ * Extracted from `check-pin-drift.mjs` (Story #198) so both consumers run
+ * `gh api` through one thin, injectable runner and one JSON parser.
+ *
+ * GitHub access is via the `gh` CLI (`gh api`), so callers inherit the
+ * environment's auth (a `GH_TOKEN`/`GITHUB_TOKEN` in CI, or `gh auth`
+ * locally). No secrets are read or printed here.
+ *
+ * ## Fail-closed HTTP-status surfacing (Story #198)
+ *
+ * `gh api` exits non-zero on any HTTP error and writes a line like
+ * `gh: Not Found (HTTP 404)` to stderr. `execFileSync` turns that into a
+ * thrown Error whose `.stderr` / `.message` carries the `(HTTP <code>)`
+ * marker. Historically the per-consumer fetchers in the dashboard caught
+ * *every* such error and returned an "absent" sentinel — so a transient 500,
+ * a network blip, or an auth failure all read as "no drift" and the
+ * `--strict` gate silently exited 0 (a fail-OPEN). That is the bug this
+ * module exists to close.
+ *
+ * `httpStatusOf(err)` parses the HTTP status back out of a thrown `gh` error,
+ * and `isNotFound(err)` is the ONLY predicate a fetcher may use to justify
+ * swallowing an error into an "absent" result. Every other error must
+ * propagate so the caller's per-consumer catch records an `error` row (which
+ * `hasDrift` counts and `--strict` fails on) — the gate fails CLOSED.
+ */
+
+import { execFileSync } from "node:child_process";
+
+/**
+ * Default gh runner — shells out to the `gh` CLI.
+ *
+ * @param {string[]} args
+ * @returns {string}
+ */
+export function defaultGhRunner(args) {
+  return execFileSync("gh", args, {
+    encoding: "utf-8",
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+/**
+ * Extract the HTTP status code from an error thrown by a `gh api` invocation.
+ * `gh` reports failures as `gh: <message> (HTTP <code>)` on stderr, which
+ * `execFileSync` surfaces on the thrown error's `.stderr` (a Buffer/string)
+ * and, for some shells, folded into `.message`. Also handles a structured
+ * error that already carries a numeric `.httpStatus` / `.status` HTTP field.
+ *
+ * @param {unknown} err
+ * @returns {number | null}  The HTTP status, or null when none can be parsed.
+ */
+export function httpStatusOf(err) {
+  if (!err || typeof err !== "object") return null;
+  // A pre-tagged HTTP status wins (set by ghApiJson on rethrow, or by a caller
+  // that already classified the error). Guard against `execFileSync`'s own
+  // numeric `.status` (that is a PROCESS exit code, not an HTTP status), so we
+  // only trust an explicit `.httpStatus`.
+  const tagged = /** @type {{ httpStatus?: unknown }} */ (err).httpStatus;
+  if (typeof tagged === "number" && Number.isInteger(tagged)) return tagged;
+
+  const parts = [];
+  const e = /** @type {{ stderr?: unknown, stdout?: unknown, message?: unknown }} */ (err);
+  if (e.stderr != null) parts.push(String(e.stderr));
+  if (e.stdout != null) parts.push(String(e.stdout));
+  if (typeof e.message === "string") parts.push(e.message);
+  const haystack = parts.join("\n");
+  // `gh` form: "(HTTP 404)". REST body form: "\"status\":\"404\"".
+  const m = /\(HTTP\s+(\d{3})\)/.exec(haystack) || /"status"\s*:\s*"(\d{3})"/.exec(haystack);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
+
+/**
+ * Is `err` a GitHub 404 (Not Found)? This is the ONLY error class a fetcher
+ * may legitimately swallow into an "absent" sentinel — a 404 genuinely means
+ * "this resource does not exist" (a consumer with no `package.json`, no
+ * `.github/workflows/` dir, no release). Every other status (403, 429, 5xx,
+ * or an unparseable transport failure) must fail CLOSED.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isNotFound(err) {
+  return httpStatusOf(err) === 404;
+}
+
+/**
+ * Run `gh api <path>` and parse the JSON response. On failure, the thrown
+ * error is re-thrown with its HTTP status tagged on `.httpStatus` (parsed via
+ * `httpStatusOf`) so downstream `catch` blocks can distinguish a 404 (safe to
+ * treat as "absent") from every other error (must fail closed). The status is
+ * surfaced, never swallowed here — the swallow/rethrow policy lives in the
+ * per-consumer fetchers.
+ *
+ * @param {string} apiPath  e.g. "repos/owner/repo/releases/latest".
+ * @param {(args: string[]) => string} runGh  Injectable runner.
+ * @returns {unknown}
+ */
+export function ghApiJson(apiPath, runGh) {
+  let raw;
+  try {
+    raw = runGh(["api", apiPath, "-H", "Accept: application/vnd.github+json"]);
+  } catch (err) {
+    const status = httpStatusOf(err);
+    if (status !== null && err && typeof err === "object" && !("httpStatus" in err)) {
+      try {
+        /** @type {{ httpStatus?: number }} */ (err).httpStatus = status;
+      } catch {
+        // Non-extensible error object — the parseable status still lives in
+        // `.stderr`/`.message`, so httpStatusOf(err) recovers it downstream.
+      }
+    }
+    throw err;
+  }
+  return JSON.parse(raw);
+}

package/scripts/lib/semver-duration.mjs

@@ -0,0 +1,84 @@
+/**
+ * scripts/lib/semver-duration.mjs
+ *
+ * The semver + Renovate-duration parsers shared by the pin-drift dashboard
+ * (`check-pin-drift.mjs`) and the pin-repair loop (`platform-repair.mjs`).
+ * Extracted from `check-pin-drift.mjs` (Story #198) so both consumers parse
+ * release tags, dependency specs, and `minimumReleaseAge` windows through one
+ * SSOT rather than a monolith import.
+ *
+ * These are pure functions — no I/O, no GitHub access.
+ */
+
+/**
+ * Extract a comparable `x.y.z` semver core from a release tag or version spec.
+ * The platform tags releases as `mandrel-platform-v<semver>`; consumer specs
+ * may carry a range prefix (`^0.11.3`, `~0.11.3`). Returns the dotted triple
+ * or null when no numeric semver core is present (`workspace:*`, `latest`, a
+ * git URL).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function parseSemver(value) {
+  if (typeof value !== "string") return null;
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+  return m ? `${m[1]}.${m[2]}.${m[3]}` : null;
+}
+
+/**
+ * Compare two `x.y.z` semver cores. Returns -1 when a < b, 0 when equal, 1
+ * when a > b. Inputs MUST already be normalized dotted triples (see
+ * `parseSemver`).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Parse a Renovate-style `minimumReleaseAge` duration into milliseconds. The
+ * preset uses human strings like `"3 days"`, `"36 hours"`, `"1 week"`; this
+ * accepts an integer (or float) count followed by a unit (the same units
+ * Renovate's `ms`-backed parser accepts). Returns null for an unparseable or
+ * non-positive value so the caller can fall back to "no hold window".
+ *
+ * @param {unknown} value
+ * @returns {number | null}  Window length in ms, or null.
+ */
+export function parseDurationMs(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    // Bare number is interpreted as days (the preset's unit of record).
+    return value * 24 * 60 * 60 * 1000;
+  }
+  if (typeof value !== "string") return null;
+  const m = /^\s*(\d+(?:\.\d+)?)\s*([a-z]+)\s*$/i.exec(value.trim());
+  if (!m) return null;
+  const count = Number.parseFloat(m[1]);
+  if (!Number.isFinite(count) || count <= 0) return null;
+  const unit = m[2].toLowerCase();
+  const units = {
+    minute: 60 * 1000,
+    minutes: 60 * 1000,
+    min: 60 * 1000,
+    mins: 60 * 1000,
+    hour: 60 * 60 * 1000,
+    hours: 60 * 60 * 1000,
+    hr: 60 * 60 * 1000,
+    hrs: 60 * 60 * 1000,
+    day: 24 * 60 * 60 * 1000,
+    days: 24 * 60 * 60 * 1000,
+    week: 7 * 24 * 60 * 60 * 1000,
+    weeks: 7 * 24 * 60 * 60 * 1000,
+  };
+  const factor = units[unit];
+  return factor ? count * factor : null;
+}

package/scripts/lib/uses-pins.mjs

@@ -0,0 +1,220 @@
+/**
+ * scripts/lib/uses-pins.mjs
+ *
+ * The single home for `uses:`-line parsing, reference classification, and
+ * 40-hex-SHA validation shared by the pin-tooling scripts. These primitives
+ * had been copy-pasted into `check-action-pins.mjs` (the SHA-pin ratchet) and
+ * partially re-implemented as ad-hoc regexes in `check-workflow-portability.mjs`
+ * (the internal-pin collector) — the exact drift Story #203 consolidates.
+ *
+ * Nothing here reads the filesystem or the environment: every function is a
+ * pure text transform, so the sibling `uses-pins.test.mjs` runs fully offline.
+ *
+ * ## Vocabulary
+ *
+ *   • A raw `uses:` VALUE is whatever follows `uses:` on a workflow/action
+ *     line, possibly quoted and possibly carrying a trailing `# vX.Y.Z` tag
+ *     note. {@link stripUsesValue} reduces it to the bare reference.
+ *   • A bare REFERENCE is `owner/repo[/subpath]@gitref`, `./local/path`, or
+ *     `docker://image`. {@link classifyUses} sorts it into first-party /
+ *     third-party / local / docker / unparseable.
+ *   • A git REF is a full 40-char commit SHA, a tag, a branch, or a short SHA.
+ *     {@link isSha40} is the SHA-pin predicate the ratchet enforces.
+ *
+ * ## Single-pin invariant (Story #203)
+ *
+ * {@link findSinglePinViolations} adds an INTRA-repo check absent from the
+ * cross-repo pin-drift dashboard: within one repo's `.github/workflows/`, two
+ * first-party `uses:` refs to the SAME subpath MUST carry the SAME SHA. Two
+ * workflows pinning `owner/repo/.github/actions/foo` at different commits is a
+ * silent split-brain — one workflow runs the fixed action, the other the
+ * stale one. This check makes that state fail CI.
+ */
+
+const DEFAULT_FIRST_PARTY_OWNER = "dsj1984/mandrel-platform";
+
+/** A full git commit SHA is exactly 40 lowercase/uppercase hex characters. */
+const SHA40_RE = /^[0-9a-fA-F]{40}$/;
+
+/**
+ * Matches a YAML `uses:` mapping key: optional leading whitespace, an optional
+ * leading `- ` (sequence item), then `uses:` and the value. A `uses:` inside a
+ * `#` comment or a `run:` heredoc is indented past a leading `#`, so anchoring
+ * on the leading token avoids false hits on documentation examples.
+ */
+const USES_LINE_RE = /^\s*(?:-\s+)?uses:\s*(\S.*)$/;
+
+export { DEFAULT_FIRST_PARTY_OWNER, SHA40_RE, USES_LINE_RE };
+
+/**
+ * Strip a trailing `# comment` (the conventional `# v4.2.2` tag note) and
+ * surrounding whitespace/quotes from a raw `uses:` value, returning the bare
+ * action reference. A `#` inside the ref itself is not valid GitHub syntax,
+ * so splitting on the first ` #` is safe.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function stripUsesValue(raw) {
+  let v = String(raw).trim();
+  // Drop a trailing comment: the first '#' that is preceded by whitespace (or
+  // at the start) begins a comment. GitHub action refs never contain '#'.
+  const hashIdx = v.search(/\s#/);
+  if (hashIdx !== -1) v = v.slice(0, hashIdx);
+  v = v.trim();
+  // Unwrap matched surrounding quotes.
+  if (
+    (v.startsWith('"') && v.endsWith('"')) ||
+    (v.startsWith("'") && v.endsWith("'"))
+  ) {
+    v = v.slice(1, -1).trim();
+  }
+  return v;
+}
+
+/**
+ * If a line is a YAML `uses:` mapping key, return its bare reference (comment
+ * and quotes stripped); otherwise return null. Whole-line `#` comments never
+ * match.
+ *
+ * @param {string} line
+ * @returns {string | null}
+ */
+export function parseUsesLine(line) {
+  const raw = String(line);
+  if (/^\s*#/.test(raw)) return null;
+  const m = raw.match(USES_LINE_RE);
+  if (!m) return null;
+  return stripUsesValue(m[1]);
+}
+
+/**
+ * Classify a bare `uses:` reference. Returns one of:
+ *   { kind: 'local' }                     — `./path` or `../path` (exempt)
+ *   { kind: 'docker' }                    — `docker://image` (exempt)
+ *   { kind: 'first-party', owner, subpath, ref } — the configured first-party
+ *                                           owner (exempt from the SHA ratchet)
+ *   { kind: 'third-party', owner, subpath, ref } — external action (MUST be
+ *                                           SHA-pinned)
+ *   { kind: 'unparseable' }               — not a recognizable `uses:` reference
+ *
+ * `subpath` is the path segment after `owner/repo/` (empty string when the ref
+ * is the bare `owner/repo`), so single-pin comparison can key on it.
+ *
+ * @param {string} bareRef
+ * @param {string} [firstPartyOwner]
+ * @returns {{kind: string, owner?: string, subpath?: string, ref?: string, ownerRepoPath?: string}}
+ */
+export function classifyUses(bareRef, firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER) {
+  const ref = String(bareRef).trim();
+  if (ref === "") return { kind: "unparseable" };
+  if (ref.startsWith("./") || ref.startsWith("../")) return { kind: "local" };
+  if (ref.startsWith("docker://")) return { kind: "docker" };
+
+  // owner/repo[/subpath]@gitref. The git ref is everything after the LAST '@'
+  // (an action subpath never contains '@'; the ref does not either).
+  const atIdx = ref.lastIndexOf("@");
+  if (atIdx === -1) {
+    // No `@ref` at all — not a pinnable external reference (e.g. a malformed
+    // entry). Treat as unparseable so the caller can flag it explicitly.
+    return { kind: "unparseable", ownerRepoPath: ref };
+  }
+  const ownerRepoPath = ref.slice(0, atIdx);
+  const gitRef = ref.slice(atIdx + 1);
+  const segments = ownerRepoPath.split("/");
+  if (segments.length < 2) return { kind: "unparseable", ownerRepoPath, ref: gitRef };
+
+  const ownerRepo = `${segments[0]}/${segments[1]}`;
+  const subpath = segments.slice(2).join("/");
+  if (ownerRepo.toLowerCase() === String(firstPartyOwner).toLowerCase()) {
+    return { kind: "first-party", owner: ownerRepo, subpath, ref: gitRef };
+  }
+  return { kind: "third-party", owner: ownerRepo, subpath, ref: gitRef };
+}
+
+/**
+ * True when a git ref is a full 40-character commit SHA.
+ *
+ * @param {string} gitRef
+ * @returns {boolean}
+ */
+export function isSha40(gitRef) {
+  return SHA40_RE.test(String(gitRef).trim());
+}
+
+/**
+ * Scan a file's TEXT for first-party `uses:` refs and index each by its
+ * `owner/repo/subpath` reference target, capturing the SHA (or non-SHA ref)
+ * each site pins. Returns a Map keyed by `owner/repo` + `/subpath` (the full
+ * reference minus `@ref`), each value an array of
+ * `{ file, line, ref, target }` occurrences. Only `first-party` refs with a
+ * non-empty subpath are collected — a bare `owner/repo@ref` self-reference has
+ * no subpath to disambiguate, and third-party refs are governed by the
+ * cross-repo pin-drift dashboard, not the intra-repo single-pin invariant.
+ *
+ * @param {string} content
+ * @param {string} displayFile
+ * @param {string} [firstPartyOwner]
+ * @returns {Map<string, Array<{file: string, line: number, ref: string, target: string}>>}
+ */
+export function collectFirstPartyPins(
+  content,
+  displayFile,
+  firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER
+) {
+  const byTarget = new Map();
+  const lines = String(content).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const bareRef = parseUsesLine(lines[i]);
+    if (bareRef === null) continue;
+    const cls = classifyUses(bareRef, firstPartyOwner);
+    if (cls.kind !== "first-party") continue;
+    if (!cls.subpath) continue; // bare owner/repo self-ref has no subpath to key on
+    const target = `${cls.owner}/${cls.subpath}`;
+    const occ = { file: displayFile, line: i + 1, ref: cls.ref, target };
+    const existing = byTarget.get(target);
+    if (existing) existing.push(occ);
+    else byTarget.set(target, [occ]);
+  }
+  return byTarget;
+}
+
+/**
+ * The single-pin invariant (Story #203). Given a list of `{ file, content }`
+ * records (the repo's workflow files), find every first-party `uses:` target
+ * that is pinned to MORE THAN ONE distinct SHA across the set. Returns an
+ * array of violations, one per drifting target:
+ *
+ *   { target, shas: [...distinct refs], occurrences: [{ file, line, ref }] }
+ *
+ * A target pinned consistently (or referenced only once) yields no violation.
+ *
+ * @param {Array<{file: string, content: string}>} files
+ * @param {string} [firstPartyOwner]
+ * @returns {Array<{target: string, shas: string[], occurrences: Array<{file: string, line: number, ref: string}>}>}
+ */
+export function findSinglePinViolations(files, firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER) {
+  // Merge every file's per-target occurrences into one index.
+  const merged = new Map();
+  for (const { file, content } of files) {
+    const perFile = collectFirstPartyPins(content, file, firstPartyOwner);
+    for (const [target, occs] of perFile) {
+      const existing = merged.get(target);
+      if (existing) existing.push(...occs);
+      else merged.set(target, [...occs]);
+    }
+  }
+
+  const violations = [];
+  for (const [target, occs] of merged) {
+    const distinct = [...new Set(occs.map((o) => o.ref))];
+    if (distinct.length > 1) {
+      violations.push({
+        target,
+        shas: distinct,
+        occurrences: occs.map((o) => ({ file: o.file, line: o.line, ref: o.ref })),
+      });
+    }
+  }
+  return violations;
+}