mandrel-platform 0.17.2 → 0.19.0

package/scripts/check-workflow-portability.mjs

@@ -68,41 +68,49 @@
  *   It is dependency-free (no YAML parser) so it copies cleanly into any repo.
  */
 
-import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { readFileSync, statSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { resolve, join, relative, basename } from "node:path";
 
+import { parseFlags } from "./lib/args.mjs";
+import { parseUsesLine, classifyUses, isSha40 } from "./lib/uses-pins.mjs";
+import { listWorkflowFiles, listActionFiles } from "./lib/walk.mjs";
+
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
 
-const args = process.argv.slice(2);
-let workflowsDir = null;
-let actionsDir = null;
-let pinCheck = true;
-
-for (let i = 0; i < args.length; i++) {
-  if ((args[i] === "--workflows-dir" || args[i] === "-w") && args[i + 1]) {
-    workflowsDir = args[++i];
-  } else if ((args[i] === "--actions-dir" || args[i] === "-a") && args[i + 1]) {
-    actionsDir = args[++i];
-  } else if (args[i] === "--no-pin-check") {
-    pinCheck = false;
-  } else if (args[i] === "--help" || args[i] === "-h") {
-    process.stdout.write(
-      "Usage: node scripts/check-workflow-portability.mjs [--workflows-dir <dir>] [--actions-dir <dir>] [--no-pin-check]\n"
-    );
-    process.exit(0);
-  }
+/**
+ * Parse the CLI argv slice into an options object. Pure — no I/O, no exit — so
+ * the sibling node:test suite can exercise it. `--help` is surfaced as a flag
+ * for the CLI wrapper to act on rather than exiting here. Unknown flags are
+ * ignored (lenient CLI), preserving this script's historical behavior.
+ */
+export function parseArgs(argv) {
+  return parseFlags(argv, {
+    flags: {
+      "--workflows-dir": { type: "string", dest: "workflowsDir", default: null },
+      "--actions-dir": { type: "string", dest: "actionsDir", default: null },
+      "--no-pin-check": { type: "boolean", dest: "pinCheck", value: false, default: true },
+      "--help": { type: "boolean", dest: "help", value: true, default: false },
+    },
+    aliases: {
+      "-w": "--workflows-dir",
+      "-a": "--actions-dir",
+      "-h": "--help",
+    },
+    onUnknown: "ignore",
+  });
 }
 
+// Runtime bindings shared by the discovery/lint helpers below. Initialized at
+// module load with safe defaults (cwd-relative dirs, pin-check on) and
+// re-derived per invocation inside runCli() so importing this module never
+// triggers a scan.
 const repoRoot = process.cwd();
-const resolvedWorkflowsDir = workflowsDir
-  ? resolve(workflowsDir)
-  : resolve(repoRoot, ".github/workflows");
-const resolvedActionsDir = actionsDir
-  ? resolve(actionsDir)
-  : resolve(repoRoot, ".github/actions");
+let resolvedWorkflowsDir = resolve(repoRoot, ".github/workflows");
+let resolvedActionsDir = resolve(repoRoot, ".github/actions");
+let pinCheck = true;
 
 // ---------------------------------------------------------------------------
 // Minimal indentation-aware YAML walk (dependency-free)
@@ -117,7 +125,7 @@ const resolvedActionsDir = actionsDir
 // for a parent mapping. Quotes are stripped from keys so `"on":` === `on`.
 // ---------------------------------------------------------------------------
 
-function walkYaml(content) {
+export function walkYaml(content) {
   const lines = content.split("\n");
   const stack = []; // [{ indent, key }]
   const records = [];
@@ -193,19 +201,42 @@ const EXPR = /\$\{\{/;
 // Content checks (reused for both working-tree files and pinned blobs)
 // ---------------------------------------------------------------------------
 
+/**
+ * Detect whether a workflow declares `workflow_call` — i.e. is reusable and
+ * therefore subject to Rules 1 & 2. Two shapes count:
+ *
+ *   1. Mapping form — `on:` is a mapping with a `workflow_call:` child, so the
+ *      walk yields a record whose path is `on.workflow_call` (or a descendant).
+ *   2. Inline form — `workflow_call` sits directly on the `on:` value, as a
+ *      bare scalar (`on: workflow_call`) or inside a flow sequence
+ *      (`on: [workflow_call]`, `on: [push, workflow_call]`). The walk yields a
+ *      single record with path `on` whose value carries the trigger token(s).
+ *
+ * The former mapping-only check silently skipped inline-declared reusable
+ * workflows, so Rules 1 & 2 never ran on them.
+ */
+export function isReusableWorkflow(records) {
+  return records.some((r) => {
+    const p = r.path.join(".");
+    if (p === "on.workflow_call" || p.startsWith("on.workflow_call.")) return true;
+    // Inline scalar / flow-sequence on the top-level `on:` key.
+    if (p === "on" && /\bworkflow_call\b/.test(r.value)) return true;
+    return false;
+  });
+}
+
 /** Reusable-workflow checks (Rules 1 & 2). Returns [{line, message}]. */
-function checkWorkflowContent(content) {
+export function checkWorkflowContent(content) {
   const violations = [];
   const records = walkYaml(content);
 
-  const isReusable = records.some(
-    (r) => r.path.join(".") === "on.workflow_call" || r.path.join(".").startsWith("on.workflow_call.")
-  );
-  if (!isReusable) return violations;
+  if (!isReusableWorkflow(records)) return violations;
 
-  // Rule 1: no relative `uses:` anywhere in a reusable workflow.
+  // Rule 1: no relative `uses:` anywhere in a reusable workflow. Allow an
+  // optional leading `- ` so the sequence/list form (`- uses: ./…`) is caught
+  // as well as the mapping form — mirrors check-action-pins.mjs's `usesRe`.
   content.split("\n").forEach((raw, idx) => {
-    if (/^\s*uses:\s*['"]?\.\//.test(raw)) {
+    if (/^\s*(?:-\s+)?uses:\s*['"]?\.\//.test(raw)) {
       violations.push({
         line: idx + 1,
         message:
@@ -239,7 +270,7 @@ function checkWorkflowContent(content) {
 }
 
 /** Composite-action checks (Rules 3/4 of the original; manifest cleanliness). */
-function checkActionContent(content) {
+export function checkActionContent(content) {
   const violations = [];
   const records = walkYaml(content);
 
@@ -307,15 +338,23 @@ function gitShow(sha, path) {
 function collectInternalPins(content) {
   const pins = [];
   content.split("\n").forEach((raw, idx) => {
-    const m = raw.match(
-      /uses:\s*['"]?[\w.-]+\/[\w.-]+\/([^@\s'"]+)@([0-9a-fA-F]{40})/
-    );
-    if (!m) return;
-    const subpath = m[1];
-    const sha = m[2];
+    const bareRef = parseUsesLine(raw);
+    if (bareRef === null) return;
+    // `owner/repo/<subpath>@<sha>` — classify against *any* owner (this repo's
+    // own slug or a fork's), then keep only same-repo refs whose subpath
+    // resolves to a real path in the working tree. Passing the parsed owner as
+    // the "first-party" owner makes classifyUses treat every owner/repo the
+    // same; the existsSync gate below is what actually decides "internal".
+    const atIdx = bareRef.lastIndexOf("@");
+    if (atIdx === -1) return;
+    const owner = bareRef.slice(0, atIdx).split("/").slice(0, 2).join("/");
+    const cls = classifyUses(bareRef, owner);
+    if (cls.kind !== "first-party" || !cls.subpath) return;
+    if (!isSha40(cls.ref)) return; // only full-SHA pins are validated by Rule 3
+    const subpath = cls.subpath;
     const local = join(repoRoot, subpath);
     if (!existsSync(local)) return; // external ref → skip
-    pins.push({ subpath, sha, line: idx + 1 });
+    pins.push({ subpath, sha: cls.ref, line: idx + 1 });
   });
   return pins;
 }
@@ -343,46 +382,10 @@ function resolvePinnedManifest(subpath) {
 }
 
 // ---------------------------------------------------------------------------
-// File discovery
+// File discovery — `listWorkflowFiles` / `listActionFiles` are imported from
+// `./lib/walk.mjs` (Story #203).
 // ---------------------------------------------------------------------------
 
-function listWorkflowFiles(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
-    .map((f) => join(dir, f));
-}
-
-function listActionFiles(dir) {
-  const found = [];
-  let entries;
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return found;
-  }
-  for (const entry of entries) {
-    const full = join(dir, entry);
-    let st;
-    try {
-      st = statSync(full);
-    } catch {
-      continue;
-    }
-    if (st.isDirectory()) {
-      found.push(...listActionFiles(full));
-    } else if (entry === "action.yml" || entry === "action.yaml") {
-      found.push(full);
-    }
-  }
-  return found;
-}
-
 // ---------------------------------------------------------------------------
 // Per-file lint
 // ---------------------------------------------------------------------------
@@ -442,52 +445,94 @@ function lintFile(filePath) {
 // Run
 // ---------------------------------------------------------------------------
 
-const workflowFiles = listWorkflowFiles(resolvedWorkflowsDir);
-const actionFiles = listActionFiles(resolvedActionsDir);
-const allFiles = [...workflowFiles, ...actionFiles];
-
-process.stdout.write(
-  `[check-workflow-portability] Workflows: ${relative(repoRoot, resolvedWorkflowsDir)}/ (${workflowFiles.length})\n` +
-  `[check-workflow-portability] Actions  : ${relative(repoRoot, resolvedActionsDir)}/ (${actionFiles.length})\n` +
-  `[check-workflow-portability] Pin check: ${pinCheck ? (isGitRepo() ? "on" : "on (git unavailable — skipped)") : "off"}\n`
-);
+/**
+ * Run the full lint end-to-end and return a POSIX exit code (0 = clean,
+ * 1 = violations). Applies the parsed options to the shared runtime bindings,
+ * discovers the workflow/action files, lints each, and reports. `log` / `err`
+ * are injectable so the sibling node:test suite can capture output without
+ * touching the real streams; the direct-invocation guard below wires them to
+ * process.stdout / process.stderr.
+ */
+export function runCli(argv, { log = writeStdout, err = writeStderr } = {}) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    log(
+      "Usage: node scripts/check-workflow-portability.mjs [--workflows-dir <dir>] [--actions-dir <dir>] [--no-pin-check]\n"
+    );
+    return 0;
+  }
 
-if (allFiles.length === 0) {
-  process.stdout.write(
-    `[check-workflow-portability] No workflow or action files found — nothing to lint.\n`
+  resolvedWorkflowsDir = opts.workflowsDir
+    ? resolve(opts.workflowsDir)
+    : resolve(repoRoot, ".github/workflows");
+  resolvedActionsDir = opts.actionsDir
+    ? resolve(opts.actionsDir)
+    : resolve(repoRoot, ".github/actions");
+  pinCheck = opts.pinCheck;
+  pinSkips.length = 0; // idempotent across repeated runCli() calls
+
+  const workflowFiles = listWorkflowFiles(resolvedWorkflowsDir);
+  const actionFiles = listActionFiles(resolvedActionsDir);
+  const allFiles = [...workflowFiles, ...actionFiles];
+
+  log(
+    `[check-workflow-portability] Workflows: ${relative(repoRoot, resolvedWorkflowsDir)}/ (${workflowFiles.length})\n` +
+    `[check-workflow-portability] Actions  : ${relative(repoRoot, resolvedActionsDir)}/ (${actionFiles.length})\n` +
+    `[check-workflow-portability] Pin check: ${pinCheck ? (isGitRepo() ? "on" : "on (git unavailable — skipped)") : "off"}\n`
   );
-  process.exit(0);
-}
 
-let total = 0;
-for (const file of allFiles) {
-  const violations = lintFile(file);
-  if (violations.length === 0) continue;
-  total += violations.length;
-  const rel = relative(repoRoot, file);
-  process.stderr.write(`\n[check-workflow-portability] ❌ ${rel}\n`);
-  for (const v of violations) {
-    process.stderr.write(`     ${rel}:${v.line} — ${v.message}\n`);
+  if (allFiles.length === 0) {
+    log(
+      `[check-workflow-portability] No workflow or action files found — nothing to lint.\n`
+    );
+    return 0;
+  }
+
+  let total = 0;
+  for (const file of allFiles) {
+    const violations = lintFile(file);
+    if (violations.length === 0) continue;
+    total += violations.length;
+    const rel = relative(repoRoot, file);
+    err(`\n[check-workflow-portability] ❌ ${rel}\n`);
+    for (const v of violations) {
+      err(`     ${rel}:${v.line} — ${v.message}\n`);
+    }
+  }
+
+  if (pinSkips.length > 0) {
+    log(
+      `\n[check-workflow-portability] ⚠️  ${pinSkips.length} internal pin(s) could not be verified (Rule 3 skipped):\n`
+    );
+    for (const s of pinSkips) log(`     ${s}\n`);
   }
-}
 
-if (pinSkips.length > 0) {
-  process.stdout.write(
-    `\n[check-workflow-portability] ⚠️  ${pinSkips.length} internal pin(s) could not be verified (Rule 3 skipped):\n`
+  if (total > 0) {
+    err(
+      `\n[check-workflow-portability] ${total} portability violation${total === 1 ? "" : "s"} detected.\n` +
+      `   These fail only when a CONSUMER repo calls the workflow/action, which is\n` +
+      `   exactly why in-repo CI never caught them before. Fix each above.\n\n`
+    );
+    return 1;
+  }
+
+  log(
+    `[check-workflow-portability] ✅ All reusable workflows and composite actions are cross-repo portable.\n`
   );
-  for (const s of pinSkips) process.stdout.write(`     ${s}\n`);
+  return 0;
 }
 
-if (total > 0) {
-  process.stderr.write(
-    `\n[check-workflow-portability] ${total} portability violation${total === 1 ? "" : "s"} detected.\n` +
-    `   These fail only when a CONSUMER repo calls the workflow/action, which is\n` +
-    `   exactly why in-repo CI never caught them before. Fix each above.\n\n`
-  );
-  process.exit(1);
+function writeStdout(s) {
+  process.stdout.write(s);
+}
+function writeStderr(s) {
+  process.stderr.write(s);
 }
 
-process.stdout.write(
-  `[check-workflow-portability] ✅ All reusable workflows and composite actions are cross-repo portable.\n`
-);
-process.exit(0);
+// Only run when executed directly, not when imported by the test suite.
+const invokedDirectly =
+  process.argv[1] &&
+  resolve(process.argv[1]).endsWith("check-workflow-portability.mjs");
+if (invokedDirectly) {
+  process.exit(runCli(process.argv.slice(2)));
+}

package/scripts/check-workflow-portability.test.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * check-workflow-portability.test.mjs — node:test suite for the cross-repo
+ * portability lint (Story #199).
+ *
+ * This is the "equivalent self-test" the Story's acceptance criteria call for.
+ * It exercises the two blind spots the Story closes, plus the surrounding
+ * behavior so the fixes are pinned against regression:
+ *
+ *   1. Rule 1 now catches the sequence/list form `- uses: ./…` (previously the
+ *      leading `- ` slipped past the mapping-only regex), so a local action
+ *      referenced inside a workflow_call workflow IS flagged.
+ *   2. `on: workflow_call` declared INLINE (bare scalar or flow sequence) is
+ *      detected as reusable, so Rules 1 & 2 actually run on it — the former
+ *      mapping-only `on.workflow_call` check silently skipped these.
+ *
+ * Pure exported helpers keep the whole suite offline — no temp dirs, no git.
+ *
+ * Run: node --test scripts/check-workflow-portability.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  walkYaml,
+  isReusableWorkflow,
+  checkWorkflowContent,
+  checkActionContent,
+  parseArgs,
+} from "./check-workflow-portability.mjs";
+
+// ---------------------------------------------------------------------------
+// isReusableWorkflow — inline vs mapping workflow_call detection
+// ---------------------------------------------------------------------------
+
+test("isReusableWorkflow: mapping form (on: > workflow_call:) is reusable", () => {
+  const yaml = ["on:", "  workflow_call:", "    inputs:", "      foo:", "        type: string", ""].join("\n");
+  assert.equal(isReusableWorkflow(walkYaml(yaml)), true);
+});
+
+test("isReusableWorkflow: inline scalar form (on: workflow_call) is reusable", () => {
+  const yaml = ["name: reusable", "on: workflow_call", "jobs: {}", ""].join("\n");
+  assert.equal(isReusableWorkflow(walkYaml(yaml)), true);
+});
+
+test("isReusableWorkflow: inline flow-sequence form (on: [workflow_call]) is reusable", () => {
+  const yaml = ["on: [workflow_call]", "jobs: {}", ""].join("\n");
+  assert.equal(isReusableWorkflow(walkYaml(yaml)), true);
+});
+
+test("isReusableWorkflow: mixed inline flow-sequence (on: [push, workflow_call]) is reusable", () => {
+  const yaml = ["on: [push, workflow_call]", "jobs: {}", ""].join("\n");
+  assert.equal(isReusableWorkflow(walkYaml(yaml)), true);
+});
+
+test("isReusableWorkflow: a plain push-triggered workflow is NOT reusable", () => {
+  const yaml = ["on:", "  push:", "    branches: [main]", "jobs: {}", ""].join("\n");
+  assert.equal(isReusableWorkflow(walkYaml(yaml)), false);
+});
+
+test("isReusableWorkflow: inline scalar `on: push` is NOT reusable (no false positive)", () => {
+  const yaml = ["on: push", "jobs: {}", ""].join("\n");
+  assert.equal(isReusableWorkflow(walkYaml(yaml)), false);
+});
+
+// ---------------------------------------------------------------------------
+// Rule 1 — relative `uses: ./…`, both mapping and sequence forms
+// ---------------------------------------------------------------------------
+
+test("Rule 1: sequence form `- uses: ./…` inside a workflow_call workflow IS flagged", () => {
+  const yaml = [
+    "on:",
+    "  workflow_call:",
+    "jobs:",
+    "  build:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: ./.github/actions/foo",
+    "",
+  ].join("\n");
+  const violations = checkWorkflowContent(yaml);
+  assert.equal(violations.length, 1, "expected exactly one Rule 1 violation");
+  assert.match(violations[0].message, /relative `uses: \.\/` path/);
+});
+
+test("Rule 1: mapping form `uses: ./…` is still flagged (no regression)", () => {
+  const yaml = [
+    "on:",
+    "  workflow_call:",
+    "jobs:",
+    "  build:",
+    "    uses: ./.github/workflows/reused.yml",
+    "",
+  ].join("\n");
+  const violations = checkWorkflowContent(yaml);
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /relative `uses: \.\/` path/);
+});
+
+test("Rule 1: sequence-form relative `uses` combined with INLINE workflow_call IS flagged", () => {
+  // Combines both fixes: inline reusable detection + sequence-form catch.
+  const yaml = [
+    "name: reusable-inline",
+    "on: workflow_call",
+    "jobs:",
+    "  build:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: ./.github/actions/foo",
+    "",
+  ].join("\n");
+  const violations = checkWorkflowContent(yaml);
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /relative `uses: \.\/` path/);
+});
+
+test("Rule 1: absolute owner/repo `uses` in a reusable workflow is NOT flagged", () => {
+  const yaml = [
+    "on: workflow_call",
+    "jobs:",
+    "  build:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "",
+  ].join("\n");
+  assert.deepEqual(checkWorkflowContent(yaml), []);
+});
+
+test("Rule 1: relative `uses` in a NON-reusable workflow is NOT flagged", () => {
+  // `./` is portable when the workflow only runs in its own repo.
+  const yaml = [
+    "on:",
+    "  push:",
+    "jobs:",
+    "  build:",
+    "    steps:",
+    "      - uses: ./.github/actions/foo",
+    "",
+  ].join("\n");
+  assert.deepEqual(checkWorkflowContent(yaml), []);
+});
+
+// ---------------------------------------------------------------------------
+// Rule 2 — ${{ }} in workflow_call input/secret meta runs on inline form too
+// ---------------------------------------------------------------------------
+
+test("Rule 2: still fires on the mapping workflow_call form", () => {
+  const yaml = [
+    "on:",
+    "  workflow_call:",
+    "    inputs:",
+    "      name:",
+    "        description: ${{ runner.os }}",
+    "",
+  ].join("\n");
+  const violations = checkWorkflowContent(yaml);
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /expression in workflow_call/);
+});
+
+// ---------------------------------------------------------------------------
+// checkActionContent — untouched by this Story, guarded against regression
+// ---------------------------------------------------------------------------
+
+test("checkActionContent: flags ${{ }} in a composite input default", () => {
+  const yaml = [
+    "inputs:",
+    "  dest:",
+    "    default: ${{ runner.temp }}",
+    "",
+  ].join("\n");
+  const violations = checkActionContent(yaml);
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /expression in action input/);
+});
+
+// ---------------------------------------------------------------------------
+// parseArgs — pure option parsing
+// ---------------------------------------------------------------------------
+
+test("parseArgs: defaults are pin-check on, no dir overrides, no help", () => {
+  assert.deepEqual(parseArgs([]), {
+    workflowsDir: null,
+    actionsDir: null,
+    pinCheck: true,
+    help: false,
+  });
+});
+
+test("parseArgs: --no-pin-check, dir overrides, and --help are parsed", () => {
+  assert.deepEqual(parseArgs(["-w", "wf", "--actions-dir", "act", "--no-pin-check", "--help"]), {
+    workflowsDir: "wf",
+    actionsDir: "act",
+    pinCheck: false,
+    help: true,
+  });
+});