@opengsd/gsd-core 1.11.0 → 1.13.0

package/scripts/ci-pr-mergeability.cjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+'use strict';
+
+// ci-pr-mergeability.cjs — #3833 PR mergeability preflight.
+//
+// Risk asymmetry drives this design: a false positive (a clean PR wrongly
+// classified CONFLICTED) skips every gated compute lane in all eight gated
+// workflows on EVERY PR — a repo-wide outage. A false negative (a real
+// conflict missed) is today's behavior; the per-job scripts/ci-rebase-check.cjs
+// backstop still catches it there. So the weight is entirely on the
+// false-positive surface: the single predicate `mergeable === false`, and
+// every falsy-but-not-false value around it.
+//
+// GitHub's `mergeable` field on GET /repos/:owner/:repo/pulls/:number is a
+// documented tri-state: `true`, `false`, or `null` while a background
+// computation is still running. `null` is falsy — `if (!mergeable)` would
+// misclassify "still computing" as "conflicted" and would have red every PR
+// in the repo the moment this job started running. Only strict `=== false`
+// counts as a conflict.
+//
+// `mergeable_state` is read only for the human-facing annotation, never for
+// the verdict: its `blocked` value means "required checks have not passed",
+// which is true for every PR while THIS preflight job itself is one of the
+// required checks still running — classifying on it would self-deadlock the
+// pipeline (the gate can never go green because it is itself ungreen).
+//
+// Because `mergeable` starts null and GitHub computes it asynchronously, this
+// polls with linear backoff up to a small budget, then fails OPEN
+// (INDETERMINATE => exit 0) rather than blocking the world on an API that
+// hasn't finished thinking.
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const VERDICT = Object.freeze({
+  MERGEABLE: 'MERGEABLE',
+  CONFLICTED: 'CONFLICTED',
+  INDETERMINATE: 'INDETERMINATE',
+  SKIPPED_NOT_A_PR: 'SKIPPED_NOT_A_PR',
+});
+
+const MAX_ATTEMPTS = 5;
+const BASE_DELAY_MS = 2000;
+
+/**
+ * Pure, total classifier: payload -> VERDICT atom. Never throws.
+ * Deliberately reads ONLY `mergeable`, and only with strict equality — see
+ * the header comment for why `mergeable_state` and truthiness are excluded.
+ */
+function classifyMergeability(payload) {
+  if (payload === null || typeof payload !== 'object') return VERDICT.INDETERMINATE;
+  if (payload.mergeable === true) return VERDICT.MERGEABLE;
+  if (payload.mergeable === false) return VERDICT.CONFLICTED;
+  return VERDICT.INDETERMINATE;
+}
+
+/**
+ * Linear backoff: attempt 1..N-1 gives 1x..(N-1)x baseMs. Non-positive/NaN
+ * attempts clamp to one base interval rather than producing 0 or NaN delays.
+ */
+function nextDelayMs(attempt, { baseMs = BASE_DELAY_MS } = {}) {
+  const n = Number.isFinite(attempt) && attempt > 0 ? Math.floor(attempt) : 1;
+  return baseMs * n;
+}
+
+/**
+ * Dependency-injected poll loop. Resolves as soon as GitHub reports a
+ * definite mergeable/conflicted state, or gives up after maxAttempts and
+ * reports INDETERMINATE (fail-open).
+ *
+ * @returns {Promise<{verdict:string, attempts:number, payload:*, reason:string}>}
+ */
+async function resolveMergeability({
+  fetchPr,
+  sleep,
+  eventName,
+  prNumber,
+  maxAttempts = MAX_ATTEMPTS,
+  baseDelayMs = BASE_DELAY_MS,
+} = {}) {
+  if (eventName !== 'pull_request') {
+    return { verdict: VERDICT.SKIPPED_NOT_A_PR, attempts: 0, payload: null, reason: 'not-a-pull-request' };
+  }
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    return { verdict: VERDICT.INDETERMINATE, attempts: 0, payload: null, reason: 'no-pr-number' };
+  }
+
+  let attempts = 0;
+  let lastPayload = null;
+  let lastError = null;
+
+  for (let i = 1; i <= maxAttempts; i++) {
+    attempts = i;
+    let payload;
+    try {
+      payload = await fetchPr(prNumber);
+      lastPayload = payload;
+      lastError = null;
+    } catch (err) {
+      lastError = err;
+      payload = null;
+    }
+
+    const verdict = classifyMergeability(payload);
+    if (verdict === VERDICT.MERGEABLE || verdict === VERDICT.CONFLICTED) {
+      return { verdict, attempts, payload, reason: 'resolved' };
+    }
+
+    if (i < maxAttempts) {
+      await sleep(nextDelayMs(i, { baseMs: baseDelayMs }));
+    }
+  }
+
+  return {
+    verdict: VERDICT.INDETERMINATE,
+    attempts,
+    payload: lastPayload,
+    reason: lastError ? 'fetch-failed' : 'mergeability-not-computed',
+  };
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  node scripts/ci-pr-mergeability.cjs',
+    '',
+    'CI-only preflight: polls the GitHub API for a PR\'s mergeable state and',
+    'fails the job (exit 1) only on a definite conflict. Everything else',
+    '(unknown, unreadable, not a PR) fails open (exit 0).',
+    '',
+    'Environment variables read:',
+    '  GITHUB_EVENT_NAME    workflow trigger event; only "pull_request" is polled',
+    '  GITHUB_REPOSITORY    owner/repo',
+    '  GITHUB_TOKEN         optional bearer token for the API read',
+    '  GITHUB_BASE_REF      PR base branch name (default: next)',
+    '  GITHUB_API_URL       GitHub API base URL (default: https://api.github.com)',
+    '  PR_NUMBER            the pull request number',
+    '  GITHUB_OUTPUT        path to append verdict=/mergeable= step outputs to',
+    '  GITHUB_STEP_SUMMARY  path to append a human-readable summary to',
+    '  GSD_PR_MERGEABILITY_BASE_DELAY_MS  optional numeric override of the base backoff, for tests',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(`${usage()}\n`);
+      throw new ExitError(0);
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+}
+
+function writeOutput(lines) {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (typeof outputPath !== 'string' || outputPath === '') return;
+  try {
+    const fs = require('node:fs');
+    fs.appendFileSync(outputPath, `${lines.join('\n')}\n`);
+  } catch (err) {
+    // A failure while REPORTING the verdict must never invert the gate.
+    process.stderr.write(`::warning::failed to write GITHUB_OUTPUT: ${err.message}\n`);
+  }
+}
+
+function writeSummary(text) {
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (typeof summaryPath !== 'string' || summaryPath === '') return;
+  try {
+    const fs = require('node:fs');
+    fs.appendFileSync(summaryPath, `${text}\n`);
+  } catch (err) {
+    process.stderr.write(`::warning::failed to write GITHUB_STEP_SUMMARY: ${err.message}\n`);
+  }
+}
+
+// `argv` defaults to real CLI argv but is a parameter so tests can call
+// main() in-process (e.g. main([])) without inheriting the test runner's own
+// argv, which would otherwise trip parseArgs's "unknown argument" branch.
+async function main(argv = process.argv.slice(2)) {
+  parseArgs(argv);
+
+  const eventName = process.env.GITHUB_EVENT_NAME;
+  const repo = process.env.GITHUB_REPOSITORY || '';
+  const token = process.env.GITHUB_TOKEN || '';
+  const baseBranch = process.env.GITHUB_BASE_REF || 'next';
+  const apiBase = process.env.GITHUB_API_URL || 'https://api.github.com';
+  const prNumberRaw = process.env.PR_NUMBER;
+  const prNumber = Number.parseInt(prNumberRaw, 10);
+
+  const overrideDelay = Number(process.env.GSD_PR_MERGEABILITY_BASE_DELAY_MS);
+  const baseDelayMs = Number.isFinite(overrideDelay) && overrideDelay >= 0 ? overrideDelay : BASE_DELAY_MS;
+
+  const fetchPr = async (number) => {
+    const url = `${apiBase}/repos/${repo}/pulls/${number}`;
+    const headers = {
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      'user-agent': 'gsd-core-ci-pr-mergeability',
+    };
+    if (token) headers.authorization = `Bearer ${token}`;
+    const response = await fetch(url, { headers, signal: AbortSignal.timeout(10000) });
+    if (!response.ok) {
+      throw new Error(`GitHub API responded ${response.status}`);
+    }
+    const text = await response.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  };
+
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  const result = await resolveMergeability({
+    fetchPr,
+    sleep,
+    eventName,
+    prNumber: Number.isNaN(prNumber) ? NaN : prNumber,
+    maxAttempts: MAX_ATTEMPTS,
+    baseDelayMs,
+  });
+
+  const mergeable = result.verdict === VERDICT.CONFLICTED ? 'false' : 'true';
+  writeOutput([`verdict=${result.verdict}`, `mergeable=${mergeable}`]);
+  writeSummary(`PR mergeability preflight: ${result.verdict}`);
+
+  if (result.verdict === VERDICT.CONFLICTED) {
+    process.stderr.write(
+      `::error::This pull request cannot cleanly merge ${baseBranch}. Rebase onto current ${baseBranch} and push again; no CI will run until the conflict is resolved.\n`,
+    );
+    const state = result.payload && typeof result.payload === 'object' ? result.payload.mergeable_state : undefined;
+    if (state) {
+      process.stderr.write(`::error::mergeable_state: ${state}\n`);
+    }
+    return 1;
+  }
+
+  if (result.verdict === VERDICT.INDETERMINATE) {
+    process.stderr.write(
+      '::warning::GitHub did not report mergeability within the polling budget; proceeding (fail-open). scripts/ci-rebase-check.cjs remains the in-job backstop.\n',
+    );
+    return 0;
+  }
+
+  process.stdout.write(`PR mergeability preflight: ${result.verdict}\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = {
+  VERDICT,
+  MAX_ATTEMPTS,
+  BASE_DELAY_MS,
+  classifyMergeability,
+  nextDelayMs,
+  resolveMergeability,
+  main,
+};

package/scripts/ci-test-scope.cjs

@@ -39,6 +39,10 @@ const PROTECTED_WORKFLOWS = new Set([
   'mutation.yml',
   'security-scan.yml',
   'release.yml',
+  // #3833: the reusable gate every `pull_request` compute lane depends on —
+  // marking it inert would let a change to the gate itself ship without ever
+  // running the full matrix it is responsible for enforcing.
+  'pr-mergeable-preflight.yml',
 ]);
 for (const wf of PROTECTED_WORKFLOWS) {
   if (INERT_WORKFLOWS.has(wf)) {
@@ -93,6 +97,10 @@ const RULES = [
     tests: [
       'tests/run-tests-harness.test.cjs',
       'tests/workflow-shell-pinning.test.cjs',
+      // #4220: the run-scoped temp root + computeSweepProtectSet ancestor-walk
+      // termination coverage — was previously not re-selected by an edit to
+      // scripts/run-tests.cjs, the exact file that shipped the #4020 hang.
+      'tests/run-tests-temp-root.test.cjs',
     ],
   },
   {
@@ -298,6 +306,9 @@ const RULES = [
       'tests/require-userprofile-with-home.rule.test.cjs',
       'tests/normalize-path-in-content.rule.test.cjs',
       'tests/require-fs-op-fallback.rule.test.cjs',
+      // #4244 (origin #4020/#4220 Windows CI hang) — see ADR-1703 amendment.
+      'tests/require-full-tmpdir-triad.rule.test.cjs',
+      'tests/no-unbounded-dirname-walk.rule.test.cjs',
     ],
   },
   {
@@ -341,19 +352,48 @@ function missingRuleTestFiles(rules) {
   return [...referenced].filter(f => !existsSync(path.join(__dirname, '..', f))).sort();
 }
 
-// Fail loudly at module load, mirroring the PROTECTED_WORKFLOWS check above —
-// this fires on EVERY invocation of the CLI (including the real `changes` job
-// in .github/workflows/test.yml), not only when a test suite happens to run.
-{
-  const missing = missingRuleTestFiles(RULES);
-  if (missing.length > 0) {
-    throw new Error(
-      `ci-test-scope: RULES reference test file(s) that do not exist on disk ` +
-      `(silent coverage hole — see #2758):\n  ${missing.join('\n  ')}`,
-    );
-  }
+/**
+ * Every PROTECTED_WORKFLOWS member that does not exist on disk.
+ * The name list and the real filenames are two surfaces over one fact
+ * (#3833): without this, renaming or deleting a gating workflow silently
+ * un-protects it and CI stays green while the protection is gone. Same
+ * shape and rationale as missingRuleTestFiles() above.
+ */
+function missingProtectedWorkflows(names = PROTECTED_WORKFLOWS) {
+  return [...names]
+    .filter(name => !existsSync(path.join(__dirname, '..', '.github', 'workflows', name)))
+    .sort();
+}
+
+/**
+ * Shared module-load assertion for the two "this list names something that
+ * does not exist on disk" guards above. Both are silent-coverage-hole guards:
+ * a name that no longer resolves stops selecting/protecting anything while CI
+ * stays green, so both must fail loudly at load rather than at test time.
+ */
+function assertNoneMissing(missing, summary, issueRef) {
+  if (missing.length === 0) return;
+  throw new Error(`ci-test-scope: ${summary} (${issueRef}):\n  ${missing.join('\n  ')}`);
 }
 
+// Fail loudly at module load — this fires on EVERY invocation of the CLI
+// (including the real `changes` job in .github/workflows/test.yml), not only
+// when a test suite happens to run.
+assertNoneMissing(
+  missingRuleTestFiles(RULES),
+  'RULES reference test file(s) that do not exist on disk (silent coverage hole)',
+  'see #2758',
+);
+
+// A PROTECTED_WORKFLOWS entry naming a file that does not exist means the
+// workflow was renamed or deleted without updating this list, silently
+// un-protecting it while CI stays green.
+assertNoneMissing(
+  missingProtectedWorkflows(PROTECTED_WORKFLOWS),
+  'PROTECTED_WORKFLOWS reference workflow file(s) that do not exist on disk (silent protection hole)',
+  'see #3833',
+);
+
 function usage() {
   return [
     'Usage:',
@@ -590,4 +630,4 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { RULES, missingRuleTestFiles };
+module.exports = { RULES, missingRuleTestFiles, PROTECTED_WORKFLOWS, INERT_WORKFLOWS, missingProtectedWorkflows };

package/scripts/ci-timeout-report.cjs

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * scripts/ci-timeout-report.cjs
+ *
+ * Scheduled CI-timeout trending report (#4036). Polls GitHub's Actions REST
+ * API for recently completed jobs across test.yml, mutation.yml, and
+ * install-smoke.yml, resolves each job's declared `timeout-minutes` budget,
+ * computes elapsed-vs-cap via scripts/lib/ci-job-timing.cjs, and appends
+ * new (never-before-seen) records to a JSONL history file. Every record also
+ * carries the triggering `runEvent` (e.g. `push`/`pull_request`) so entries
+ * for jobs whose matrix genuinely differs by trigger (e.g. `smoke`'s
+ * push-only macOS row) can be told apart in the persisted trend — records
+ * are never filtered by event, only labeled.
+ *
+ * Invoked from a GitHub Actions workflow via actions/github-script, e.g.:
+ *   const report = require(`${process.env.GITHUB_WORKSPACE}/scripts/ci-timeout-report.cjs`);
+ *   const result = await report.main({ github, context, core });
+ */
+
+const yaml = require('js-yaml');
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  computeElapsedPct, isNearCap, formatNearCapNotice,
+} = require('./lib/ci-job-timing.cjs');
+
+const HISTORY_PATH = path.join(__dirname, '..', 'tests', 'ci-timeout-budget-history.jsonl');
+const WORKFLOWS_DIR = path.join(__dirname, '..', '.github', 'workflows');
+
+// Static job name → job-id rules, first match wins, checked in array order
+// (test-inert before test, since both job names start with "test ").
+const JOB_RULES = [
+  { workflowFile: 'test.yml', jobKey: 'test-inert', test: (name) => name === 'test (inert CI)' },
+  { workflowFile: 'test.yml', jobKey: 'test', test: (name) => name.startsWith('test (') && name !== 'test (inert CI)' },
+  { workflowFile: 'test.yml', jobKey: 'test-full', test: (name) => name.startsWith('full test (') },
+  { workflowFile: 'test.yml', jobKey: 'coverage-gate', test: (name) => name === 'Coverage gate (merged shards)' },
+  { workflowFile: 'install-smoke.yml', jobKey: 'smoke', test: (name) => name.startsWith('smoke (') },
+];
+
+function resolveJobTimeoutMinutes({ jobName, workflowFile, workflowYamlText, covered }) {
+  if (workflowFile === 'mutation.yml') {
+    const m = jobName.match(/^Stryker \(([^)]+)\)$/);
+    if (!m) return null;
+    const moduleName = m[1];
+    if (!covered || !Object.prototype.hasOwnProperty.call(covered, moduleName)) return null;
+    return covered[moduleName].timeoutMinutes || 15;
+  }
+
+  const rule = JOB_RULES.find((r) => r.workflowFile === workflowFile && r.test(jobName));
+  if (!rule) return null;
+
+  const doc = yaml.load(workflowYamlText);
+  const budget = doc && doc.jobs && doc.jobs[rule.jobKey] ? doc.jobs[rule.jobKey]['timeout-minutes'] : undefined;
+  return typeof budget === 'number' ? budget : null;
+}
+
+/**
+ * @param {{job: object, workflowFile: string, workflowYamlText: ?string, covered: ?object}} args
+ *   `job.runEvent` is the triggering event (e.g. `push`/`pull_request`) — carried through to
+ *   the returned record so entries whose matrix genuinely differs by trigger (e.g. `smoke`'s
+ *   push-only macOS row) can be distinguished in the persisted history.
+ */
+function parseJobRecord({ job, workflowFile, workflowYamlText, covered }) {
+  if (!job.completed_at) return null;
+
+  const timeoutMinutes = resolveJobTimeoutMinutes({ jobName: job.name, workflowFile, workflowYamlText, covered });
+  if (timeoutMinutes == null) return null;
+
+  const { elapsedMs, pct } = computeElapsedPct({
+    startedAt: job.started_at, completedAt: job.completed_at, timeoutMinutes,
+  });
+
+  return {
+    runId: job.run_id,
+    jobName: job.name,
+    workflowFile,
+    sha: job.head_sha,
+    runEvent: job.runEvent,
+    completedAt: job.completed_at,
+    elapsedMs,
+    timeoutMinutes,
+    pct,
+  };
+}
+
+function buildReportLines(runs, { workflowFile, workflowYamlText, covered }) {
+  const records = [];
+  for (const { run, jobs } of runs) {
+    for (const job of jobs) {
+      const rec = parseJobRecord({
+        job: {
+          ...job, run_id: run.id, head_sha: run.head_sha, runEvent: run.event,
+        },
+        workflowFile,
+        workflowYamlText,
+        covered,
+      });
+      if (rec) records.push(rec);
+    }
+  }
+  return records;
+}
+
+function dedupeAgainstHistory(newRecords, historyText) {
+  const seen = new Set();
+  for (const line of String(historyText || '').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      seen.add(`${rec.runId}::${rec.jobName}`);
+    } catch {
+      // Malformed history line — skip it rather than crash the whole report.
+    }
+  }
+  return newRecords.filter((r) => !seen.has(`${r.runId}::${r.jobName}`));
+}
+
+function formatHistoryLine(record) {
+  return `${JSON.stringify(record)}\n`;
+}
+
+const WORKFLOW_FILES = ['test.yml', 'mutation.yml', 'install-smoke.yml'];
+const MAX_RUNS_PER_WORKFLOW = 15;
+
+/**
+ * Orchestration entry point — impure, invoked from actions/github-script.
+ *
+ * @param {{github: object, context: object, core: object, historyPath?: string, fs?: object}} args
+ * @returns {Promise<{added: number, nearCap: number}>}
+ */
+async function main({
+  github, context, core, historyPath = HISTORY_PATH, fs: fsImpl = fs,
+}) {
+  const { owner, repo } = context.repo;
+  const mutationMatrix = require('./mutation-matrix.cjs');
+
+  const allNewRecords = [];
+
+  for (const workflowFile of WORKFLOW_FILES) {
+    const covered = workflowFile === 'mutation.yml' ? mutationMatrix.COVERED : null;
+    const workflowYamlText = workflowFile === 'mutation.yml'
+      ? null
+      : fsImpl.readFileSync(path.join(WORKFLOWS_DIR, workflowFile), 'utf8');
+
+    let runsList;
+    try {
+      runsList = await github.paginate(github.rest.actions.listWorkflowRuns, {
+        owner,
+        repo,
+        workflow_id: workflowFile,
+        status: 'completed',
+        per_page: 30,
+      });
+    } catch (err) {
+      core.warning(`ci-timeout-report: failed to list runs for ${workflowFile}: ${err.message}`);
+      continue;
+    }
+
+    const runs = runsList.slice(0, MAX_RUNS_PER_WORKFLOW);
+    const runsWithJobs = [];
+
+    for (const run of runs) {
+      try {
+        const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRun, {
+          owner,
+          repo,
+          run_id: run.id,
+          per_page: 50,
+        });
+        runsWithJobs.push({ run, jobs });
+      } catch (err) {
+        core.warning(`ci-timeout-report: failed to list jobs for ${workflowFile} run ${run.id}: ${err.message}`);
+      }
+    }
+
+    const records = buildReportLines(runsWithJobs, { workflowFile, workflowYamlText, covered });
+    allNewRecords.push(...records);
+  }
+
+  let historyText = '';
+  try {
+    historyText = fsImpl.readFileSync(historyPath, 'utf8');
+  } catch {
+    // First run — history file does not exist yet, treat as empty.
+    historyText = '';
+  }
+
+  const deduped = dedupeAgainstHistory(allNewRecords, historyText);
+
+  if (deduped.length > 0) {
+    const newLines = deduped.map(formatHistoryLine).join('');
+    fsImpl.appendFileSync(historyPath, newLines);
+  }
+  // First-run bootstrap when there is nothing new to append is handled by
+  // `git add` picking up whatever the history file already contains.
+
+  let nearCapCount = 0;
+  for (const record of deduped) {
+    if (!isNearCap(record.pct)) continue;
+    nearCapCount += 1;
+
+    const notice = formatNearCapNotice({
+      label: `${record.jobName} (run ${record.runId})`,
+      pct: record.pct,
+      elapsedMs: record.elapsedMs,
+      capMs: record.timeoutMinutes * 60000,
+    });
+
+    core.warning(notice.warningLine.replace(/^::warning title=CI budget::/, ''));
+
+    if (core.summary) {
+      core.summary.addRaw(`${notice.summaryMarkdown}\n`);
+    }
+  }
+
+  return { added: deduped.length, nearCap: nearCapCount };
+}
+
+module.exports = {
+  HISTORY_PATH,
+  WORKFLOWS_DIR,
+  JOB_RULES,
+  resolveJobTimeoutMinutes,
+  parseJobRecord,
+  buildReportLines,
+  dedupeAgainstHistory,
+  formatHistoryLine,
+  main,
+};