mandrel 2.59.0 → 2.61.0

package/.agents/scripts/check-action-pinning.js

@@ -1,260 +0,0 @@
-/**
- * CLI: third-party GitHub Action pinning gate.
- *
- * Story #4079 (audit::devops). Closes a supply-chain regression window the
- * `ci.yml` / `release-please.yml` comments *claimed* was guarded by a
- * nonexistent `npm run audit-security` gate. There is no such npm script;
- * `audit-security` is only a manual `/audit-security` slash-command lens.
- * Nothing actually enforced that third-party `uses:` refs stay SHA-pinned,
- * so a future edit reverting `trufflehog@<sha>` to `@main` would pass CI
- * silently.
- *
- * This script scans `.github/workflows/*.yml` (and `*.yaml`), extracts every
- * `uses:` ref, and fails the build when a **third-party** action (anything
- * not under the first-party `actions/*` org) is pinned to a floating ref
- * instead of a full 40-char commit SHA. First-party `actions/*` refs are
- * allowed on major-version tags (`@v4`) — Dependabot's `github-actions`
- * ecosystem bumps those in-place, matching the rationale in the workflow
- * file headers.
- *
- * A "floating ref" is any of:
- *   - a branch head: `@main`, `@master`
- *   - a tag / partial-SHA that is not a full 40-hex-char commit SHA
- *     (`@v5`, `@v3.95.3`, `@release`, a 7-char short SHA, …)
- *
- * Contract:
- *   - Scans the workflows directory (default `.github/workflows`, override
- *     with `--dir <path>`).
- *   - Prints `<file>:<lineNo> <ref> — <reason>` for each violation, then a
- *     one-line summary even on a clean scan so operators see the "ok" signal.
- *   - With `--json`: writes a structured envelope to stdout and skips the
- *     human summary.
- *   - Exit codes: 0 = no violations; 1 = at least one floating third-party
- *     ref. A missing / empty workflows directory exits 0 (nothing to gate).
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { runAsCli } from './lib/cli-utils.js';
-
-/**
- * Parse argv for `--dir <path>` and `--json`. Exported so unit tests can pin
- * the parser.
- *
- * @param {string[]} argv
- * @returns {{ dir: string | null, json: boolean }}
- */
-export function parseArgv(argv = []) {
-  let dir = null;
-  let json = false;
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a === '--dir') {
-      const next = argv[i + 1];
-      if (next && !next.startsWith('--')) {
-        dir = next;
-        i += 1;
-      }
-    } else if (a === '--json') {
-      json = true;
-    }
-  }
-  return { dir, json };
-}
-
-/**
- * Is the given ref suffix a full 40-char hex commit SHA?
- *
- * @param {string} ref The portion after the `@` in a `uses:` value.
- * @returns {boolean}
- */
-export function isFullSha(ref) {
-  return /^[0-9a-f]{40}$/i.test(ref);
-}
-
-/**
- * Is the action a first-party `actions/*` action (e.g. `actions/checkout`)?
- * First-party refs are allowed to float on major-version tags because
- * Dependabot's `github-actions` ecosystem bumps them in-place.
- *
- * Local (`./…`) and reusable-workflow (`owner/repo/.github/workflows/x.yml`)
- * refs and Docker refs (`docker://…`) are out of scope for the SHA-pin gate;
- * `isFirstParty` only matters for `owner/repo[@ref]` registry actions.
- *
- * @param {string} action The portion before the `@` in a `uses:` value.
- * @returns {boolean}
- */
-export function isFirstParty(action) {
-  return /^actions\//.test(action);
-}
-
-/**
- * Pure helper: scan a single workflow file's text for `uses:` refs and return
- * the violations. A violation is a third-party `owner/repo@ref` where `ref`
- * is not a full 40-char SHA.
- *
- * Skips:
- *   - local actions (`uses: ./path`)
- *   - Docker refs (`uses: docker://…`)
- *   - first-party `actions/*` refs (allowed on major-version tags)
- *   - refs with no `@` (pinned by default branch implicitly — flagged as a
- *     violation: an unpinned third-party ref floats on the default branch)
- *
- * @param {string} file Relative file label used in violation rows.
- * @param {string} text The file contents.
- * @returns {Array<{ file: string, line: number, action: string, ref: string | null, reason: string }>}
- */
-export function scanWorkflowText(file, text) {
-  const violations = [];
-  const lines = text.split(/\r?\n/);
-  // Match `uses:` values, optionally quoted. The value runs until whitespace
-  // or a `#` comment. Capture the raw value for downstream parsing.
-  const usesRe = /^\s*(?:-\s*)?uses:\s*['"]?([^'"#\s]+)['"]?/;
-  for (let i = 0; i < lines.length; i += 1) {
-    const m = usesRe.exec(lines[i]);
-    if (!m) continue;
-    const value = m[1];
-    const lineNo = i + 1;
-    // Local actions and Docker refs are out of scope for the SHA-pin gate.
-    if (value.startsWith('./') || value.startsWith('docker://')) continue;
-    const atIndex = value.indexOf('@');
-    const action = atIndex === -1 ? value : value.slice(0, atIndex);
-    const ref = atIndex === -1 ? null : value.slice(atIndex + 1);
-    // First-party actions/* may float on major-version tags.
-    if (isFirstParty(action)) continue;
-    if (ref === null) {
-      violations.push({
-        file,
-        line: lineNo,
-        action,
-        ref: null,
-        reason: 'third-party action with no ref floats on the default branch',
-      });
-      continue;
-    }
-    if (!isFullSha(ref)) {
-      const floating = ref === 'main' || ref === 'master';
-      violations.push({
-        file,
-        line: lineNo,
-        action,
-        ref,
-        reason: floating
-          ? `third-party action pinned to branch head @${ref} (CWE-1357)`
-          : `third-party action @${ref} is not a full 40-char commit SHA`,
-      });
-    }
-  }
-  return violations;
-}
-
-/**
- * Enumerate workflow files (`*.yml` / `*.yaml`) directly under `dir`.
- * Returns absolute paths sorted for deterministic output. A missing directory
- * yields an empty list.
- *
- * @param {string} dir Absolute workflows directory.
- * @returns {string[]}
- */
-export function listWorkflowFiles(dir) {
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((e) => e.isFile() && /\.ya?ml$/i.test(e.name))
-    .map((e) => path.join(dir, e.name))
-    .sort();
-}
-
-/**
- * Pure helper: render the human-readable report. One line per violation
- * followed by a one-line summary. The summary carries a `(gate fail)` /
- * `(ok)` marker so the result is visible in CI output.
- *
- * @param {Array<{ file: string, line: number, action: string, ref: string | null, reason: string }>} violations
- * @returns {string}
- */
-export function renderReport(violations) {
-  const lines = [];
-  for (const v of violations) {
-    const refLabel = v.ref === null ? '(no ref)' : `@${v.ref}`;
-    lines.push(`${v.file}:${v.line} ${v.action}${refLabel} — ${v.reason}`);
-  }
-  const tag = violations.length > 0 ? '(gate fail)' : '(ok)';
-  lines.push(`[action-pinning] violations=${violations.length} ${tag}`);
-  return lines.join('\n');
-}
-
-/**
- * Top-level CLI entry. Exported so tests can drive the full pipeline against a
- * fixture workflows directory without touching the repo's real workflows.
- *
- * @param {{
- *   argv?: string[],
- *   cwd?: string,
- *   stdout?: { write: (s: string) => void },
- *   stderr?: { write: (s: string) => void },
- * }} [opts]
- * @returns {Promise<number>} exit code: 0 = clean; 1 = floating third-party ref
- */
-export async function runCli({
-  argv = process.argv.slice(2),
-  cwd = process.cwd(),
-  stdout = process.stdout,
-  stderr = process.stderr,
-} = {}) {
-  const { dir, json } = parseArgv(argv);
-  const resolvedDir = path.resolve(
-    cwd,
-    dir ?? path.join('.github', 'workflows'),
-  );
-
-  const files = listWorkflowFiles(resolvedDir);
-  const violations = [];
-  for (const file of files) {
-    let text;
-    try {
-      text = fs.readFileSync(file, 'utf-8');
-    } catch {
-      continue;
-    }
-    violations.push(...scanWorkflowText(path.relative(cwd, file), text));
-  }
-
-  const exitCode = violations.length > 0 ? 1 : 0;
-
-  if (json) {
-    const envelope = {
-      kind: 'action-pinning-report',
-      dir: resolvedDir,
-      filesScanned: files.length,
-      violations,
-      exitCode,
-    };
-    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
-  } else {
-    if (files.length === 0) {
-      stderr.write(
-        `[action-pinning] ⚠ no workflow files found under ${resolvedDir}\n`,
-      );
-    }
-    stdout.write(`\n--- action-pinning scan ---\n`);
-    stdout.write(`${renderReport(violations)}\n`);
-  }
-
-  return exitCode;
-}
-
-async function main() {
-  return runCli();
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'action-pinning',
-  propagateExitCode: true,
-  errorPrefix: '[action-pinning] ❌ Fatal error',
-});

package/.agents/scripts/check-audit-attribution.js

@@ -1,302 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI: attribute a red `npm audit` result to the diff or to the merge base.
- *
- * Runs from `ci.yml` immediately after the required "Dependency Vulnerability
- * Audit (SCA)" step fails, and only on a pull request. It re-audits the merge
- * base's committed lockfile and says, as the first line a reader sees,
- * whether this branch caused the failure.
- *
- * The verdict never changes whether the branch may land — see
- * `attributionExitCode` in `lib/audit-attribution.js`. It changes how long it
- * takes to understand why it may not.
- *
- * Exit codes:
- *   0 — the probe could not reach a verdict (`unknown`); the SCA step's own
- *       failure stands unmodified.
- *   1 — a verdict was reached: `pre-existing` or `introduced-by-this-diff`.
- *       Both fail, because the advisory is real either way.
- */
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-import process from 'node:process';
-
-import {
-  attributionExitCode,
-  auditAdvisories,
-  deriveVerdict,
-  diffAdvisories,
-  renderAdvisoryDetail,
-  renderAttribution,
-  UNKNOWN,
-} from './lib/audit-attribution.js';
-import { execFileCapture } from './lib/child-exec.js';
-import { runAsCli } from './lib/cli-utils.js';
-import { Logger } from './lib/Logger.js';
-
-/** The label the nightly sweep keys its reusable tracking issue on. */
-const TRACKING_LABEL = 'meta::dependency-advisory';
-
-const HELP = {
-  invocation:
-    'node .agents/scripts/check-audit-attribution.js --base <ref> [--cwd <dir>]',
-  summary:
-    'Say whether a red high-severity npm advisory came from this pull request or was already on its merge base.',
-  flags: [
-    ['--base <ref>', 'Base commit or ref to attribute against. Required.'],
-    ['--cwd <dir>', 'Repository root. Default: process.cwd().'],
-    [
-      '--no-tracking-issue',
-      "Skip the `gh issue list` lookup for the nightly sweep's tracking issue.",
-    ],
-  ],
-  notes: [
-    'Run it only after the required SCA step has already failed — it re-audits\nthe base to attribute that failure, and reports `unknown` when the head\naudits clean.',
-    "Exit codes:\n  0  unknown — the probe degraded; the SCA step's own failure stands\n  1  a verdict was reached (pre-existing or introduced-by-this-diff)",
-    'Both real verdicts exit 1. A check that passed on `pre-existing` would let\nadvisories accumulate on `main` unnoticed, which is what the nightly sweep\n(.github/workflows/dependency-audit-cron.yml) exists to prevent.',
-  ],
-};
-
-export function parseArgs(argv) {
-  const out = { base: null, cwd: process.cwd(), trackingIssue: true };
-  for (let i = 2; i < argv.length; i += 1) {
-    // Read the option KEY, not the dashed spelling: the key is what the
-    // negation guard and every reader below name.
-    const key = argv[i].replace(/^--/, '');
-    if (key === 'base') out.base = argv[++i] ?? null;
-    else if (key === 'cwd') out.cwd = argv[++i] ?? out.cwd;
-    // A runner with no `gh` credentials would spend a subprocess to fail; the
-    // verdict never depended on the lookup, so let the caller skip it.
-    else if (key === 'no-tracking-issue') out.trackingIssue = false;
-  }
-  return out;
-}
-
-/**
- * Materialize the base commit's manifest pair into a scratch directory.
- *
- * Read out of git rather than from a checkout — the job's working tree is the
- * head, and swapping files in it to run a probe is exactly the kind of side
- * effect this must not have.
- *
- * @returns {string} the scratch directory (caller removes it)
- */
-function materializeBase({ cwd, base, git }) {
-  const dir = mkdtempSync(path.join(tmpdir(), 'audit-attribution-'));
-  for (const file of ['package.json', 'package-lock.json']) {
-    writeFileSync(path.join(dir, file), git(cwd, 'show', `${base}:${file}`));
-  }
-  return dir;
-}
-
-// `execFileCapture` owns the stdout ceiling, `shell: false` and error
-// normalisation for the whole tree — a lockfile is large enough that a
-// re-forked local ceiling would be a real defect, not a style point.
-const defaultGit = (cwd, ...args) => execFileCapture('git', args, { cwd });
-
-/**
- * The decision core, with every I/O collaborator injectable
- * (`.agents/rules/test-seams.md` rules 1-2, 4) so the whole verdict table is
- * reachable without a git history, a network, or an npm spawn.
- *
- * @returns {{ verdict: string, exitCode: number, lines: string[] }}
- */
-export function runAttribution(argv = process.argv, deps = {}) {
-  const {
-    git = defaultGit,
-    auditHead = auditAdvisories,
-    auditBase = auditAdvisories,
-    materialize = materializeBase,
-    lookupTrackingIssue = defaultLookupTrackingIssue,
-    cleanup = (dir) => rmSync(dir, { recursive: true, force: true }),
-    logger = Logger,
-  } = deps;
-  const args = parseArgs(argv);
-
-  if (!args.base) {
-    const lines = renderAttribution({
-      verdict: UNKNOWN,
-      reason: 'no --base ref was supplied',
-    });
-    for (const line of lines) logger.info(line);
-    return { verdict: UNKNOWN, exitCode: 0, lines };
-  }
-
-  const head = auditTheHead({ args, auditHead });
-  if (head.reason) {
-    return report({ verdict: UNKNOWN, args, logger, reason: head.reason });
-  }
-
-  const { baseAudit, reason } = auditTheBase({
-    args,
-    git,
-    auditBase,
-    materialize,
-    cleanup,
-  });
-  const { introduced, preExisting } = diffAdvisories({
-    head: head.advisories,
-    base: baseAudit?.advisories ?? null,
-  });
-
-  // Per advisory: the merge base is "already failing for this" exactly when it
-  // carries every advisory the head does. A base red for its own advisory must
-  // not absolve a diff that added a different one.
-  const verdict = deriveVerdict({
-    headFailed: true,
-    baseAudit: baseAudit && { failed: introduced.length === 0 },
-  });
-  return report({
-    verdict,
-    args,
-    logger,
-    reason,
-    trackingIssue: resolveTrackingIssue({
-      verdict,
-      args,
-      lookupTrackingIssue,
-    }),
-    introduced,
-    preExisting,
-  });
-}
-
-/**
- * Audit the head tree, converting both no-verdict cases — the audit itself
- * broke, or the head is clean — into a `reason` the caller reports as
- * `unknown`. Neither is an accusation, and neither is worth auditing a base for.
- *
- * @param {{ args: object, auditHead: Function }} ctx
- * @returns {{ advisories?: Array<object>, reason: string|null }}
- */
-function auditTheHead({ args, auditHead }) {
-  try {
-    const head = auditHead(args.cwd);
-    return head.failed
-      ? { advisories: head.advisories, reason: null }
-      : {
-          reason:
-            'the head tree audits clean, so there is nothing to attribute',
-        };
-  } catch (err) {
-    return { reason: msg(err) };
-  }
-}
-
-/**
- * Look the nightly sweep's tracking issue up, unless there is no verdict to
- * attach it to or `--no-tracking-issue` said not to spend the round-trip.
- *
- * @param {{ verdict: string, args: object, lookupTrackingIssue: Function }} ctx
- * @returns {number|null}
- */
-function resolveTrackingIssue({ verdict, args, lookupTrackingIssue }) {
-  if (verdict === UNKNOWN || !args.trackingIssue) return null;
-  return safeLookup(lookupTrackingIssue, args.cwd);
-}
-
-/**
- * Materialize the merge base and audit it, converting every way that can fail
- * into a `reason` rather than a throw. The scratch directory is always removed.
- *
- * @param {object} ctx
- * @returns {{ baseAudit: object|null, reason: string|null }}
- */
-function auditTheBase({ args, git, auditBase, materialize, cleanup }) {
-  let dir = null;
-  try {
-    dir = materialize({ cwd: args.cwd, base: args.base, git });
-    return { baseAudit: auditBase(dir), reason: null };
-  } catch (err) {
-    return { baseAudit: null, reason: msg(err) };
-  } finally {
-    if (dir) {
-      try {
-        cleanup(dir);
-      } catch {
-        // A leaked scratch dir under the OS temp root is not worth failing a
-        // report over.
-      }
-    }
-  }
-}
-
-function msg(err) {
-  return String(err?.message ?? err).slice(0, 200);
-}
-
-function report({
-  verdict,
-  args,
-  logger,
-  reason = null,
-  trackingIssue = null,
-  introduced = [],
-  preExisting = [],
-}) {
-  const lines = [
-    ...renderAttribution({
-      verdict,
-      baseRef: args.base,
-      trackingIssue,
-      reason,
-    }),
-    // The two lists are reported separately even when the verdict is
-    // `introduced-by-this-diff`: an author fixing B still needs to know A is
-    // not theirs.
-    ...renderAdvisoryDetail({ introduced, preExisting }),
-  ];
-  for (const line of lines) logger.info(line);
-  return {
-    verdict,
-    exitCode: attributionExitCode(verdict),
-    lines,
-    introduced,
-    preExisting,
-  };
-}
-
-/**
- * Look up the open tracking issue by LABEL, not a title search: GitHub's
- * issue search index lags, and the nightly sweep keys the same issue the same
- * way for the same reason.
- */
-function defaultLookupTrackingIssue(cwd) {
-  const out = execFileCapture(
-    'gh',
-    [
-      'issue',
-      'list',
-      '--label',
-      TRACKING_LABEL,
-      '--state',
-      'open',
-      '--limit',
-      '1',
-      '--json',
-      'number',
-      '--jq',
-      '.[0].number // empty',
-    ],
-    { cwd },
-  ).trim();
-  return out ? Number(out) : null;
-}
-
-function safeLookup(lookup, cwd) {
-  try {
-    const n = lookup(cwd);
-    return Number.isInteger(n) ? n : null;
-  } catch {
-    // No token, no network, no `gh` — the verdict is still worth printing.
-    return null;
-  }
-}
-
-runAsCli(import.meta.url, async () => runAttribution().exitCode, {
-  source: 'audit-attribution',
-  propagateExitCode: true,
-  errorPrefix: '[audit-attribution] ❌ Fatal error',
-  usage: HELP,
-});