forgedock 1.18.0 → 1.19.0

package/scripts/ci-local/adapters/gitlab-ci.mjs

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// gitlab-ci.mjs - .gitlab-ci.yml (+ local includes) -> normalised jobs. Merge-request pipeline semantics:
+// rules/only/except with changes: path filters, stages and needs ordering, extends, variables. Services, triggers,
+// environments, manual jobs and credential-like variables are deferred-to-ci.
+
+import path from 'node:path';
+import { Unsupported, matchesFilter, branchMatches, jobId, deferred, notApplicable, parseDuration, secretLikeVar, DEPLOY_NAME } from '../lib.mjs';
+import { stepsFromScript, loadDoc, parseSafe, deepMerge, baseJob, globList } from './common.mjs';
+
+export const id = 'gitlab-ci';
+export const DEF_RE = /^\.gitlab-ci\.ya?ml$/;
+const RESERVED = new Set(['stages', 'variables', 'default', 'include', 'workflow', 'image', 'services', 'before_script', 'after_script', 'cache', 'artifacts', 'pages', 'spec', 'inputs']);
+
+// --- minimal GitLab rules:if evaluator ($VAR, strings, ==, !=, =~, !~, &&, ||, !, parens, null) ---
+function evalRule(src, vars) {
+  const toks = []; let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (/\s/.test(c)) { i++; continue; }
+    if (c === '$') { const m = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/.exec(src.slice(i)); if (!m) throw new Unsupported('rule syntax'); toks.push({ t: 'var', v: m[1] }); i += m[0].length; continue; }
+    if (c === '"' || c === "'") { const j = src.indexOf(c, i + 1); if (j < 0) throw new Unsupported('rule string'); toks.push({ t: 'str', v: src.slice(i + 1, j) }); i = j + 1; continue; }
+    if (c === '/') { const m = /^\/((?:\\.|[^/\\])*)\/([a-z]*)/.exec(src.slice(i)); if (!m) throw new Unsupported('rule regex'); toks.push({ t: 're', v: new RegExp(m[1], m[2].replace(/[^imsu]/g, '')) }); i += m[0].length; continue; }
+    const two = src.slice(i, i + 2);
+    if (['==', '!=', '=~', '!~', '&&', '||'].includes(two)) { toks.push({ t: 'op', v: two }); i += 2; continue; }
+    if ('()!'.includes(c)) { toks.push({ t: 'op', v: c }); i++; continue; }
+    if (/^null\b/.test(src.slice(i))) { toks.push({ t: 'null' }); i += 4; continue; }
+    throw new Unsupported('rule token ' + c);
+  }
+  let p = 0;
+  const val = (t) => (t.t === 'var' ? (t.v in vars ? vars[t.v] : (() => { throw new Unsupported('variable $' + t.v); })()) : t.t === 'null' ? null : t.t === 'str' ? t.v : t.t === 're' ? t.v : (() => { throw new Unsupported('rule operand'); })());
+  function prim() {
+    const t = toks[p++]; if (!t) throw new Unsupported('rule end');
+    if (t.t === 'op' && t.v === '(') { const v = or(); if (!(toks[p] && toks[p].v === ')')) throw new Unsupported('rule )'); p++; return v; }
+    if (t.t === 'op' && t.v === '!') return !prim();
+    const l = val(t); const n = toks[p];
+    if (n && n.t === 'op' && ['==', '!=', '=~', '!~'].includes(n.v)) {
+      p++; const r = val(toks[p++]);
+      if (n.v === '==') return (l === null ? null : l) === (r === null ? null : r);
+      if (n.v === '!=') return l !== r;
+      const hit = l !== null && r instanceof RegExp && r.test(String(l)); return n.v === '=~' ? hit : !hit;
+    }
+    return l !== null && l !== '';
+  }
+  function and() { let l = prim(); while (toks[p] && toks[p].v === '&&') { p++; const r = prim(); l = l && r; } return l; }
+  function or() { let l = and(); while (toks[p] && toks[p].v === '||') { p++; const r = and(); l = l || r; } return l; }
+  const v = or(); if (p < toks.length) throw new Unsupported('rule trailing'); return !!v;
+}
+
+function refMatches(ref, a) {
+  if (typeof ref !== 'string') return false;
+  if (ref === 'merge_requests' || ref === 'branches' || ref === 'pushes' || ref === 'external_pull_requests') return true;
+  if (['tags', 'schedules', 'api', 'triggers', 'web', 'pipelines', 'chat'].includes(ref)) return false;
+  const m = /^\/(.*)\/([a-z]*)$/.exec(ref);
+  return m ? new RegExp(m[1], m[2]).test(a.headBranch || '') : branchMatches(a.headBranch || '', [ref]);
+}
+
+function resolveExtends(name, jobs, depth = 0) {
+  const j = jobs[name]; if (!j || typeof j !== 'object') throw new Unsupported(`extends target ${name}`);
+  if (depth > 6) throw new Unsupported('extends depth');
+  let merged = {};
+  for (const e of [].concat(j.extends || [])) merged = deepMerge(merged, resolveExtends(e, jobs, depth + 1));
+  const own = { ...j }; delete own.extends;
+  return deepMerge(merged, own);
+}
+
+function loadWithIncludes(a, file, seen = new Set(), depth = 0) {
+  const doc = loadDoc(a, file, parseSafe);
+  if (doc === undefined) return undefined;
+  if (!doc || typeof doc !== 'object') return doc;
+  let merged = {};
+  const warn = [];
+  for (const inc of [].concat(doc.include || [])) {
+    const loc = typeof inc === 'string' ? inc : inc && inc.local;
+    if (!loc || /^https?:/.test(loc)) { warn.push(`include not resolved: ${typeof inc === 'string' ? inc : JSON.stringify(inc).slice(0, 60)}`); continue; }
+    const f = loc.replace(/^\//, '');
+    if (seen.has(f) || depth > 3) continue; seen.add(f);
+    const sub = loadWithIncludes(a, f, seen, depth + 1);
+    if (sub && typeof sub === 'object') { warn.push(...(sub.__warnings || [])); delete sub.__warnings; merged = deepMerge(merged, sub); }
+  }
+  const out = deepMerge(merged, doc); delete out.include; out.__warnings = warn; return out;
+}
+
+export function plan(a) {
+  const out = []; const warnings = []; const used = [];
+  for (const file of a.defFiles(DEF_RE)) {
+    const doc = loadWithIncludes(a, file);
+    if (doc === undefined) { out.push(deferred(jobId('gitlab', 'pipeline'), 'gitlab-ci', file, 'pipeline YAML unreadable')); continue; }
+    if (!doc || typeof doc !== 'object') continue;
+    used.push(file);
+    for (const w of doc.__warnings || []) warnings.push(`${file}: ${w} (jobs from it are not in the plan)`);
+    const stages = Array.isArray(doc.stages) ? doc.stages : ['.pre', 'build', 'test', 'deploy', '.post'];
+    const gvars = vars(doc.variables); const defaults = doc.default || {};
+    const defined = new Set([...Object.keys(gvars)]);
+    const names = Object.keys(doc).filter((k) => !RESERVED.has(k) && !k.startsWith('.') && !k.startsWith('__') && doc[k] && typeof doc[k] === 'object' && !Array.isArray(doc[k]));
+    const results = {}; const byStage = {};
+    for (const name of names) {
+      const jid = jobId('gitlab', name);
+      let job;
+      try { job = doc[name].extends ? resolveExtends(name, doc) : doc[name]; } catch (e) { if (e instanceof Unsupported) { out.push(deferred(jid, 'gitlab-ci', name, e.message)); results[name] = 'deferred'; continue; } throw e; }
+      if (!job.script && !job.trigger && !job.run) continue;
+      const stage = job.stage || 'test';
+      const env = { ...gvars, ...vars(job.variables) };
+      const ctxVars = { CI_PIPELINE_SOURCE: 'merge_request_event', CI_MERGE_REQUEST_TARGET_BRANCH_NAME: a.baseBranch, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME: a.headBranch || '', CI_COMMIT_BRANCH: null, CI_COMMIT_TAG: null, CI_COMMIT_REF_NAME: a.headBranch || '', CI_COMMIT_SHA: a.headSha, ...env };
+      const def = (r) => { out.push(deferred(jid, 'gitlab-ci', name, r)); results[name] = 'deferred'; };
+      const na = (r) => { out.push(notApplicable(jid, 'gitlab-ci', name, r)); results[name] = 'skipped'; };
+      try {
+        const gate = gating(job, ctxVars, a);
+        if (gate.na) { na(gate.na); continue; }
+        if (gate.defer) { def(gate.defer); continue; }
+        if (job.trigger) { def('trigger (child/multi-project pipeline)'); continue; }
+        if (job.environment) { def('deploy environment'); continue; }
+        if (job.secrets || job.id_tokens) { def('uses CI secrets / OIDC tokens'); continue; }
+        if (DEPLOY_NAME.test(name) || stage === 'deploy') { def('deploy/publish job'); continue; }
+        const services = job.services || defaults.services;
+        if (services && services.length) { def('service containers need docker network aliases (not reproduced on the host)'); continue; }
+        const lines = [].concat(defaults.before_script || [], job.before_script || [], job.script || []);
+        if (lines.some((l) => typeof l !== 'string')) { def('script uses !reference or nested lists'); continue; }
+        const sv = secretLikeVar(lines.join('\n'), defined) || secretLikeVar(JSON.stringify(env), defined);
+        if (/CI_JOB_TOKEN|CI_REGISTRY_PASSWORD/.test(lines.join('\n'))) { def('uses CI_JOB_TOKEN / registry credentials'); continue; }
+        if (sv) { def(`references credential-like variable $${sv}`); continue; }
+        const warn = []; const image = job.image || defaults.image;
+        if (image) warn.push(`image ${typeof image === 'string' ? image : image.name} ignored; running with the host toolchain`);
+        let matrix; let variants = 0;
+        if (job.parallel && typeof job.parallel === 'object' && job.parallel.matrix) {
+          const combos = job.parallel.matrix.flatMap((m) => Object.entries(m).reduce((acc, [k, v]) => acc.flatMap((c) => [].concat(v).map((x) => ({ ...c, [k]: String(x) }))), [{}]));
+          Object.assign(env, combos[0] || {}); matrix = Object.entries(combos[0] || {}).map(([k, v]) => `${k}=${v}`).join(','); variants = combos.length - 1;
+        }
+        Object.assign(env, { CI_PROJECT_DIR: a.repo, CI_COMMIT_SHA: a.headSha, CI_COMMIT_REF_NAME: a.headBranch || '', CI_MERGE_REQUEST_TARGET_BRANCH_NAME: a.baseBranch, CI_PIPELINE_SOURCE: 'merge_request_event', CI_JOB_NAME: name });
+        const r = stepsFromScript(lines.join('\n'), { name, cwd: '.', env: {}, repo: a.repo, continue_on_error: job.allow_failure === true, timeout_s: parseDuration(job.timeout) });
+        if (r.defer) { def(r.defer); continue; }
+        const needs = job.needs !== undefined ? [].concat(job.needs).map((n) => (typeof n === 'string' ? n : n && n.job)).filter(Boolean).map((n) => jobId('gitlab', n)) : null;
+        const j = baseJob({ id: jid, source: 'gitlab-ci', name, env: Object.fromEntries(Object.entries(env).map(([k, v]) => [k, String(v)])), steps: r.steps, warnings: warn, matrix, needs: needs || [], timeout_s: parseDuration(job.timeout) });
+        j._stage = stage; j._explicitNeeds = needs !== null;
+        (byStage[stage] = byStage[stage] || []).push(j);
+        results[name] = 'applicable'; out.push(j);
+        if (variants) out.push(deferred(jobId(jid, 'variants'), 'gitlab-ci', name, `${variants} parallel:matrix variant(s) not run locally`));
+      } catch (e) { if (e instanceof Unsupported) { def(`unsupported construct: ${e.message}`); continue; } throw e; }
+    }
+    // stage ordering: a job without explicit needs waits for every runnable job of earlier stages
+    for (const jobs of Object.values(byStage)) for (const j of jobs) {
+      if (j._explicitNeeds) { delete j._stage; delete j._explicitNeeds; continue; }
+      const idx = stages.indexOf(j._stage);
+      j.needs = Object.entries(byStage).filter(([s]) => stages.indexOf(s) < idx && stages.indexOf(s) >= 0).flatMap(([, js]) => js.map((x) => x.id));
+      delete j._stage; delete j._explicitNeeds;
+    }
+  }
+  return { jobs: out, warnings, used };
+}
+
+function vars(v) { const o = {}; for (const [k, x] of Object.entries(v || {})) o[k] = x && typeof x === 'object' ? String(x.value ?? '') : String(x ?? ''); return o; }
+
+function changesOk(list, a) { const pats = globList(list && list.paths ? list.paths : list); return !a.changed.length || a.changed.some((f) => matchesFilter(f, pats)); }
+
+// -> { na } | { defer } | {} (job is selected)
+function gating(job, v, a) {
+  if (job.when === 'manual' || job.when === 'delayed') return { defer: `when: ${job.when}` };
+  if (job.when === 'never') return { na: 'when: never' };
+  if (Array.isArray(job.rules)) {
+    for (const r of job.rules) {
+      if (r.if !== undefined && !evalRule(String(r.if), v)) continue;
+      if (r.changes !== undefined && !changesOk(r.changes, a)) continue;
+      if (r.exists !== undefined) throw new Unsupported('rules:exists');
+      if (r.when === 'never') return { na: 'matched a when: never rule' };
+      if (r.when === 'manual' || r.when === 'delayed') return { defer: `rule when: ${r.when}` };
+      return {};
+    }
+    return { na: 'no rule selects this merge-request pipeline' };
+  }
+  if (job.only !== undefined) {
+    const o = Array.isArray(job.only) ? { refs: job.only } : job.only;
+    const refs = globList(o.refs || (Array.isArray(job.only) ? job.only : []));
+    if (refs.length && !refs.some((x) => refMatches(x, a))) return { na: 'only: refs do not select this pipeline' };
+    if (o.changes && !changesOk(o.changes, a)) return { na: 'only: changes selects none of the changed files' };
+  }
+  if (job.except !== undefined) {
+    const o = Array.isArray(job.except) ? { refs: job.except } : job.except;
+    const refs = globList(o.refs || (Array.isArray(job.except) ? job.except : []));
+    if (refs.some((x) => refMatches(x, a))) return { na: 'except: refs exclude this pipeline' };
+    if (o.changes && changesOk(o.changes, a)) return { na: 'except: changes excludes this pipeline' };
+  }
+  return {};
+}

package/scripts/ci-local/adapters/portability.mjs

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// portability.mjs - deterministic cross-platform checks that always run, because macOS/Windows CI jobs are deferred:
+// Windows-invalid filename characters and reserved names, case-insensitive path collisions, CRLF in shell scripts,
+// bash 3.2 constructs and GNU-only tool flags (added lines only), plus the repo's own check-shell-portability.sh
+// when present. Findings are `PORTABILITY | <rule> | <file>[:line] | <detail>` lines.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, jobId } from '../lib.mjs';
+import { baseJob } from './common.mjs';
+
+export const id = 'portability';
+const WIN_BAD = /[<>:"|?*\u0000-\u001f]/;
+const WIN_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i;
+const SH_EXT = /\.(sh|bash)$/;
+
+const BASH32 = [
+  [/\b(mapfile|readarray)\b/, 'bash-4 builtin mapfile/readarray'],
+  [/\b(declare|local|typeset)\s+-[A-Za-z]*A\b/, 'bash-4 associative array'],
+  [/\$\{[A-Za-z_][A-Za-z0-9_]*(,,|\^\^)\}|\$\{[A-Za-z_][A-Za-z0-9_]*[,^]\}/, 'bash-4 case modification expansion'],
+  [/(^|[^|])\|&/, 'bash-4 |& redirection'],
+  [/&>>/, 'bash-4 &>> redirection'],
+  [/\bcoproc\b/, 'bash-4 coproc'],
+  [/\bwait\s+-n\b/, 'bash-4.3 wait -n'],
+  [/\[\[\s+-v\s/, 'bash-4.2 [[ -v ]]'],
+  [/\b(local|declare)\s+-n\b/, 'bash-4.3 namerefs'],
+  [/\$\{[A-Za-z_][A-Za-z0-9_]*@[AEPQUuLa]\}/, 'bash-4.4/5 parameter transformation'],
+  [/\bread\s+(-[A-Za-z]*i\b)/, 'bash-4 read -i'],
+  [/\$(EPOCHSECONDS|EPOCHREALTIME|SRANDOM|BASHPID)\b/, 'bash-4/5 special variable'],
+  [/;;&|;&(\s|$)/, 'bash-4 case fallthrough'],
+  [/\bshopt\s+-s\s+(globstar|lastpipe|inherit_errexit)\b/, 'bash-4 shopt option'],
+];
+const GNU = [
+  [/\bgrep\s+(-[A-Za-z]*P\b|--perl-regexp)/, 'grep -P (PCRE) is GNU-only'],
+  [/\bsed\s+-i\s+(?!['"])/, 'sed -i without a backup suffix argument is GNU-only'],
+  [/\bsed\s+(-[A-Za-z]*r\b|--regexp-extended)/, 'sed -r is GNU-only (use -E)'],
+  [/\bdate\s+(-d\b|--date)/, 'date -d is GNU-only'],
+  [/\breadlink\s+-f\b/, 'readlink -f is GNU-only'],
+  [/\bstat\s+-c\b/, 'stat -c is GNU-only'],
+  [/\bxargs\s+(-r\b|--no-run-if-empty)/, 'xargs -r is GNU-only'],
+  [/\bfind\b.*\s-printf\b/, 'find -printf is GNU-only'],
+  [/\bsort\s+(-[A-Za-z]*V\b|--version-sort)/, 'sort -V is not on older BSD sort'],
+  [/\bhead\s+-n\s*-[0-9]/, 'head -n -N is GNU-only'],
+  [/\bls\s+--color\b/, 'ls --color is GNU-only'],
+  [/\bcp\s+--parents\b/, 'cp --parents is GNU-only'],
+];
+
+export function plan(a) {
+  if (!a.changed.length) return { jobs: [], warnings: [], used: [] };
+  const steps = [{ name: 'portability checks (filenames, case collisions, CRLF, bash 3.2, GNU-only flags)', command: '(built-in portability checks)', cwd: '.', env: {}, kind: 'check', builtin: 'portability' }];
+  if (a.changed.some((f) => /^scripts\/.*\.sh$/.test(f)) && fs.existsSync(path.join(a.repo, 'scripts/check-shell-portability.sh')) && fs.existsSync(path.join(a.repo, 'scripts'))) {
+    steps.push({ name: 'repo check-shell-portability.sh', command: 'bash scripts/check-shell-portability.sh scripts', cwd: '.', env: {}, kind: 'check', prescoped: true });
+  }
+  return { jobs: [baseJob({ id: jobId('portability', 'builtin'), source: 'portability', name: 'portability checks', steps })], warnings: [], used: [] };
+}
+
+function addedLines(repo, from, f) {
+  const tracked = git(repo, ['ls-files', '--error-unmatch', '--', f]).code === 0;
+  if (!tracked) { try { return fs.readFileSync(path.join(repo, f), 'utf8').split('\n').map((t, i) => ({ n: i + 1, t })); } catch { return []; } }
+  const d = git(repo, ['diff', '-U0', '--no-color', '--no-ext-diff', from, '--', f]).out;
+  const out = []; let n = 0;
+  for (const l of d.split('\n')) {
+    const h = /^@@ -\d+(?:,\d+)? \+(\d+)/.exec(l);
+    if (h) { n = Number(h[1]); continue; }
+    if (l.startsWith('+') && !l.startsWith('+++')) { out.push({ n, t: l.slice(1) }); n++; }
+  }
+  return out;
+}
+
+// Run the built-in checks; returns an array of finding strings.
+export function checkPortability({ repo, from, changed, tracked }) {
+  const findings = [];
+  const lower = new Map();
+  for (const f of tracked) { const k = f.toLowerCase(); lower.set(k, (lower.get(k) || []).concat(f)); }
+  for (const f of changed) {
+    for (const seg of f.split('/')) {
+      if (WIN_BAD.test(seg)) { findings.push(`PORTABILITY | windows-filename | ${f} | invalid character in "${seg}"`); break; }
+      if (/[. ]$/.test(seg)) { findings.push(`PORTABILITY | windows-filename | ${f} | segment "${seg}" ends with a dot or space`); break; }
+      if (WIN_RESERVED.test(seg)) { findings.push(`PORTABILITY | windows-filename | ${f} | reserved device name "${seg}"`); break; }
+    }
+    if (f.length > 240) findings.push(`PORTABILITY | windows-path-length | ${f} | path longer than 240 characters`);
+    const same = lower.get(f.toLowerCase()) || [];
+    if (same.length > 1) findings.push(`PORTABILITY | case-collision | ${f} | collides with ${same.filter((x) => x !== f).join(', ')} on case-insensitive filesystems`);
+    const abs = path.join(repo, f);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+    let head = ''; try { head = fs.readFileSync(abs, 'utf8').slice(0, 200); } catch { continue; }
+    const isShell = SH_EXT.test(f) || /^#!.*\b(ba)?sh\b/.test(head);
+    if (!isShell && !/\.bats$/.test(f)) continue;
+    const lines = addedLines(repo, from, f);
+    for (const { n, t } of lines) {
+      if (/\r$/.test(t)) { findings.push(`PORTABILITY | crlf | ${f}:${n} | CRLF line ending in a shell script`); break; }
+    }
+    if (/\.bats$/.test(f)) continue;
+    for (const { n, t } of lines) {
+      const s = t.replace(/\r$/, '');
+      if (/^\s*#/.test(s) || /allowlist:/.test(s)) continue;
+      for (const [re, why] of BASH32) if (re.test(s)) findings.push(`PORTABILITY | bash-3.2 | ${f}:${n} | ${why}`);
+      for (const [re, why] of GNU) if (re.test(s)) findings.push(`PORTABILITY | gnu-only | ${f}:${n} | ${why}`);
+    }
+  }
+  return findings;
+}

package/scripts/ci-local/adapters/task-runners.mjs

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// task-runners.mjs - repos with no CI definition that gates the change: derive the check set from the repo's own
+// task runners and tool configuration (package.json scripts, Makefile, justfile, Taskfile, tox/nox, pre-commit,
+// pyproject tools, Cargo, Go, Maven, Gradle). Only lint/test/check style tasks; never build/deploy/publish.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { jobId } from '../lib.mjs';
+import { parseSafe, baseJob } from './common.mjs';
+import { stepsFromScript } from './common.mjs';
+
+export const id = 'task-runners';
+const NODE_SCRIPTS = ['lint', 'test', 'typecheck', 'type-check', 'check', 'tsc', 'format:check', 'test:unit'];
+const TASK_NAMES = ['test', 'lint', 'check', 'ci', 'verify'];
+
+const read = (a, f) => { try { return fs.readFileSync(path.join(a.repo, f), 'utf8'); } catch { return null; } };
+const has = (a, f) => fs.existsSync(path.join(a.repo, f));
+
+function mk(a, kind, name, command, extra = {}) {
+  const r = stepsFromScript(command, { name, cwd: '.', env: {}, repo: a.repo });
+  const steps = [...(extra.pre || []), ...r.steps];
+  return baseJob({ id: jobId('task', kind, name), source: 'task-runners', name: `${kind}: ${name}`, steps, warnings: [] });
+}
+
+export function plan(a) {
+  const jobs = []; const used = [];
+  const add = (j) => jobs.push(j);
+
+  const pjText = read(a, 'package.json');
+  if (pjText) {
+    let pj = null; try { pj = JSON.parse(pjText); } catch { /* malformed */ }
+    const pm = has(a, 'pnpm-lock.yaml') ? 'pnpm' : has(a, 'yarn.lock') ? 'yarn' : (has(a, 'bun.lock') || has(a, 'bun.lockb')) ? 'bun' : 'npm';
+    if (pj && pj.scripts) {
+      used.push('package.json');
+      const install = !has(a, 'node_modules') ? [{ name: 'install dependencies', command: pm === 'npm' ? (has(a, 'package-lock.json') ? 'npm ci' : 'npm install') : `${pm} install`, cwd: '.', env: {}, kind: 'install' }] : [];
+      for (const s of NODE_SCRIPTS) if (typeof pj.scripts[s] === 'string' && !/^\s*echo\b.*(no test|not specified)/i.test(pj.scripts[s]) && !/Error: no test specified/.test(pj.scripts[s])) add(mk(a, pm, s, s === 'test' && pm === 'npm' ? 'npm test' : `${pm} run ${s}`, { pre: install }));
+    }
+  }
+  const mf = read(a, 'Makefile') || read(a, 'makefile') || read(a, 'GNUmakefile');
+  if (mf) { used.push('Makefile'); for (const t of TASK_NAMES) if (new RegExp(`^${t}\\s*:`, 'm').test(mf)) add(mk(a, 'make', t, `make ${t}`)); }
+  const jf = read(a, 'justfile') || read(a, 'Justfile');
+  if (jf) { used.push('justfile'); for (const t of TASK_NAMES) if (new RegExp(`^${t}\\b[^\\n:]*:`, 'm').test(jf)) add(mk(a, 'just', t, `just ${t}`)); }
+  const tf = read(a, 'Taskfile.yml') || read(a, 'Taskfile.yaml');
+  if (tf) { const d = parseSafe(tf); used.push('Taskfile'); if (d && d.tasks) for (const t of TASK_NAMES) if (d.tasks[t]) add(mk(a, 'task', t, `task ${t}`)); }
+  if (has(a, 'tox.ini')) { used.push('tox.ini'); add(mk(a, 'python', 'tox', 'tox -q')); }
+  if (has(a, 'noxfile.py')) { used.push('noxfile.py'); add(mk(a, 'python', 'nox', 'nox')); }
+  const py = read(a, 'pyproject.toml');
+  if (py) {
+    used.push('pyproject.toml');
+    if (/^\[tool\.ruff/m.test(py)) add(mk(a, 'python', 'ruff', 'ruff check .'));
+    if (/^\[tool\.black/m.test(py)) add(mk(a, 'python', 'black', 'black --check .'));
+    if (/^\[tool\.pytest/m.test(py) || has(a, 'pytest.ini')) add(mk(a, 'python', 'pytest', 'pytest'));
+    if (/^\[tool\.mypy/m.test(py)) add(mk(a, 'python', 'mypy', 'mypy .'));
+  } else if (has(a, 'pytest.ini')) add(mk(a, 'python', 'pytest', 'pytest'));
+  if (has(a, '.pre-commit-config.yaml')) {
+    used.push('.pre-commit-config.yaml');
+    const files = a.changed.filter((f) => has(a, f));
+    if (files.length) { const j = mk(a, 'pre-commit', 'run', 'pre-commit run --files ' + files.map((f) => `'${f.replace(/'/g, "'\\''")}'`).join(' ')); j.steps.forEach((s) => { s.prescoped = true; }); add(j); }
+  }
+  if (has(a, 'Cargo.toml')) { used.push('Cargo.toml'); add(mk(a, 'cargo', 'test', 'cargo test')); }
+  if (has(a, 'go.mod')) { used.push('go.mod'); add(mk(a, 'go', 'vet', 'go vet ./...')); add(mk(a, 'go', 'test', 'go test ./...')); }
+  if (has(a, 'pom.xml')) { used.push('pom.xml'); add(mk(a, 'maven', 'test', 'mvn -q -B test')); }
+  if (has(a, 'build.gradle') || has(a, 'build.gradle.kts')) { used.push('gradle'); add(mk(a, 'gradle', 'test', has(a, 'gradlew') ? './gradlew test' : 'gradle test')); }
+  return { jobs, warnings: [], used };
+}

package/scripts/ci-local/cli.mjs

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// cli.mjs - node entry behind scripts/ci-local.sh. Subcommands: plan, run.
+// Exit codes: 0 pass, 1 a runnable job failed, 2 degraded or usage error (the gate could not run; never a pass).
+
+import fs from 'node:fs';
+import { Degraded } from './lib.mjs';
+import { buildPlan, summarizePlan } from './plan.mjs';
+
+function parseArgs(argv) {
+  const o = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    const take = () => { if (i + 1 >= argv.length) throw new Error(`${t} needs a value`); return argv[++i]; };
+    if (t === '--repo') o.repo = take(); else if (t === '--base') o.base = take(); else if (t === '--base-branch') o.baseBranch = take();
+    else if (t === '--head-branch') o.headBranch = take(); else if (t === '--files') o.files = take().split(/[\n ]+/).filter(Boolean);
+    else if (t === '--files-from') o.files = fs.readFileSync(take(), 'utf8').split('\n').filter(Boolean);
+    else if (t === '--out') o.out = take(); else if (t === '--plan') o.planFile = take(); else if (t === '--no-cache') o.noCache = true;
+    else if (t === '--budget-minutes') o.budgetMinutes = Number(take()); else if (t === '--max-parallel') o.maxParallel = Number(take());
+    else if (t === '--json') o.json = true; else if (t === '--result-file') o.resultFile = take(); else if (t === '--iteration') o.iteration = Number(take());
+    else if (t === '--cache-dir') o.cacheDir = take(); else if (t === '--result-cache-dir') o.resultCacheDir = take();
+    else if (t.startsWith('-')) throw new Error(`unknown option ${t}`); else o._.push(t);
+  }
+  return o;
+}
+
+async function main() {
+  const [sub, ...rest] = process.argv.slice(2);
+  const o = parseArgs(rest);
+  if (!['plan', 'run'].includes(sub)) { console.error('usage: ci-local.sh plan|run --repo PATH --base REF [--files "a b"] [--out FILE]'); return 2; }
+  if (!o.repo) { console.error('ci-local: --repo is required'); return 2; }
+  let plan;
+  if (sub === 'run' && o.planFile) plan = JSON.parse(fs.readFileSync(o.planFile, 'utf8'));
+  else plan = buildPlan(o);
+  if (sub === 'plan') {
+    if (o.out) fs.writeFileSync(o.out, JSON.stringify(plan, null, 2));
+    if (o.json) console.log(JSON.stringify(plan, null, 2)); else for (const l of summarizePlan(plan)) console.log(l);
+    return 0;
+  }
+  const { runPlan } = await import('./run.mjs');
+  return runPlan(plan, o);
+}
+
+// process.exitCode (not process.exit) so a large stdout pipe is flushed before the process ends.
+main().then((c) => { process.exitCode = c; }, (e) => {
+  const msg = String((e && e.message) || e).split('\n')[0];
+  if (!(e instanceof Degraded)) console.error(`ci-local: ${msg}`);
+  console.log(`CI_LOCAL_RESULT: DEGRADED reason=${msg}`); process.exitCode = 2;
+});