forgedock 1.18.0 → 1.20.0

package/scripts/ci-local/adapters/github-actions.mjs

@@ -0,0 +1,349 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// github-actions.mjs - GitHub Actions workflows -> normalised jobs.
+// Reads workflows from the base ref (trusted) plus the PR's own edits, applies on.pull_request/push path filters,
+// dorny/paths-filter outputs and job `if:` conditions, and defers anything that cannot be proven locally.
+
+import path from 'node:path';
+import {
+  Unsupported, Degraded, parseYaml, branchMatches, matchesFilter, evalExpr, interpolate, condTrue, hostClass, jobId, deferred, notApplicable,
+  SECRET_REF, DEPLOY_NAME, commandExists, run, majorOf, str,
+} from '../lib.mjs';
+import { stepsFromScript, shellArgv } from './common.mjs';
+
+export const id = 'github-actions';
+export const DEF_RE = /^\.github\/workflows\/[^/]+\.ya?ml$/;
+
+const NOOP_ACTIONS = /^(actions\/checkout|actions\/cache(\/(restore|save))?|actions\/upload-artifact|step-security\/harden-runner|Swatinem\/rust-cache)(@|$)/;
+const SETUP = {
+  'actions/setup-node': { tool: 'node', key: 'node-version', local: () => process.version },
+  'actions/setup-python': { tool: 'python3', key: 'python-version', local: () => run('python3', ['--version']).out.trim() },
+  'actions/setup-go': { tool: 'go', key: 'go-version', local: () => run('go', ['version']).out.trim() },
+  'actions/setup-java': { tool: 'java', key: 'java-version', local: () => { const r = run('java', ['-version']); return (r.err + r.out).split('\n')[0]; } },
+  'actions/setup-dotnet': { tool: 'dotnet', key: 'dotnet-version', local: () => run('dotnet', ['--version']).out.trim() },
+  'ruby/setup-ruby': { tool: 'ruby', key: 'ruby-version', local: () => run('ruby', ['--version']).out.trim() },
+  'oven-sh/setup-bun': { tool: 'bun', key: 'bun-version', local: () => run('bun', ['--version']).out.trim() },
+  'astral-sh/setup-uv': { tool: 'uv', key: 'version', local: () => run('uv', ['--version']).out.trim() },
+  'pnpm/action-setup': { tool: 'pnpm', key: 'version', local: () => run('pnpm', ['--version']).out.trim() },
+  'dtolnay/rust-toolchain': { tool: 'cargo', key: 'toolchain', local: () => run('cargo', ['--version']).out.trim() },
+  'shivammathur/setup-php': { tool: 'php', key: 'php-version', local: () => run('php', ['--version']).out.split('\n')[0] },
+  'denoland/setup-deno': { tool: 'deno', key: 'deno-version', local: () => run('deno', ['--version']).out.split('\n')[0] },
+};
+const SHELLCHECK_ACTIONS = /^(ludeeus\/action-shellcheck|reviewdog\/action-shellcheck)(@|$)/;
+
+function events(on) {
+  if (on === undefined || on === null) return {};
+  if (typeof on === 'string') return { [on]: {} };
+  if (Array.isArray(on)) return Object.fromEntries(on.map((e) => [e, {}]));
+  return Object.fromEntries(Object.entries(on).map(([k, v]) => [k, v && typeof v === 'object' ? v : {}]));
+}
+
+function pathsOk(cfg, changed) {
+  if (!changed.length) return true;
+  if (Array.isArray(cfg.paths)) return changed.some((f) => matchesFilter(f, cfg.paths));
+  if (Array.isArray(cfg['paths-ignore'])) return changed.some((f) => !matchesFilter(f, cfg['paths-ignore']));
+  return true;
+}
+
+function branchOk(cfg, branch) {
+  if (Array.isArray(cfg.branches)) return branchMatches(branch, cfg.branches);
+  if (Array.isArray(cfg['branches-ignore'])) return !branchMatches(branch, cfg['branches-ignore']);
+  return true;
+}
+
+// Does this workflow gate a pull request into the base branch? Returns '' when yes, else the reason it does not.
+function gateReason(ev, a) {
+  const names = Object.keys(ev);
+  if (ev.pull_request) {
+    const c = ev.pull_request;
+    if (!branchOk(c, a.baseBranch)) return `pull_request branches filter excludes base ${a.baseBranch}`;
+    if (!pathsOk(c, a.changed)) return 'pull_request path filter selects none of the changed files';
+    return '';
+  }
+  if (ev.push) {
+    const c = ev.push;
+    if (Array.isArray(c.tags) && !Array.isArray(c.branches) && !Array.isArray(c['branches-ignore'])) return 'push is tag-only';
+    if (!branchOk(c, a.headBranch || '')) return `push branches filter excludes ${a.headBranch}`;
+    if (!pathsOk(c, a.changed)) return 'push path filter selects none of the changed files';
+    return '';
+  }
+  return `not a pull-request gate (events: ${names.join(', ') || 'none'})`;
+}
+
+function mergeDocs(baseText, headText) {
+  const b = baseText != null ? safe(baseText) : null; const h = headText != null ? safe(headText) : null;
+  if (b === undefined || h === undefined) return undefined;
+  if (!b) return h; if (!h) return b;
+  return { ...h, jobs: { ...(b.jobs || {}), ...(h.jobs || {}) } };
+}
+function safe(t) { try { return parseYaml(t); } catch (e) { if (e instanceof Degraded) throw e; return undefined; } }
+
+function topo(jobs) {
+  const ids = Object.keys(jobs); const done = new Set(); const out = [];
+  const needsOf = (j) => [].concat(jobs[j].needs || []).filter((n) => typeof n === 'string');
+  let guard = ids.length + 2;
+  while (out.length < ids.length && guard-- > 0) for (const j of ids) if (!done.has(j) && needsOf(j).every((n) => done.has(n) || !(n in jobs))) { done.add(j); out.push(j); }
+  for (const j of ids) if (!done.has(j)) out.push(j); // cycles: processed last, deferred by missing needs
+  return out;
+}
+
+export function expandMatrix(m, ctx) {
+  if (m === undefined || m === null) return [{}];
+  if (typeof m === 'string') throw new Unsupported('dynamic matrix');
+  const base = {}; for (const [k, v] of Object.entries(m)) if (!['include', 'exclude'].includes(k)) { let val = v; if (typeof val === 'string') val = interpolate(val, ctx); if (!Array.isArray(val)) throw new Unsupported('dynamic matrix axis ' + k); base[k] = val; }
+  let combos = [{}];
+  for (const [k, vals] of Object.entries(base)) combos = combos.flatMap((c) => vals.map((v) => ({ ...c, [k]: v })));
+  if (!Object.keys(base).length) combos = [];
+  const ex = Array.isArray(m.exclude) ? m.exclude : [];
+  combos = combos.filter((c) => !ex.some((e) => Object.entries(e).every(([k, v]) => c[k] === v)));
+  // GitHub include semantics (forge#4040): an entry extends every combo whose ORIGINAL axis values all match it (an entry
+  // naming no original axis matches every combo); an entry that matches no combo is added as a new combo. Original axis
+  // values are never overwritten; extra keys are.
+  for (const inc of Array.isArray(m.include) ? m.include : []) {
+    const keys = Object.keys(inc).filter((k) => k in base);
+    const targets = Object.keys(base).length ? combos.filter((c) => keys.every((k) => c[k] === inc[k])) : [];
+    if (targets.length) { for (const t of targets) for (const [k, v] of Object.entries(inc)) if (!(k in base)) t[k] = v; }
+    else combos.push({ ...inc });
+  }
+  return combos.length ? combos : [{}];
+}
+
+function osClass(runsOn) {
+  const labels = [].concat(runsOn && runsOn.labels ? runsOn.labels : runsOn).filter((x) => typeof x === 'string').map((x) => x.toLowerCase());
+  if (!labels.length) return { reason: 'runs-on missing' };
+  if (labels.includes('self-hosted') || (runsOn && runsOn.group)) return { reason: 'self-hosted runner' };
+  for (const l of labels) { if (/windows/.test(l)) return { os: 'win32', label: l }; if (/macos|mac-?os/.test(l)) return { os: 'darwin', label: l }; if (/ubuntu|linux|debian|arm64|x64/.test(l)) return { os: 'linux', label: l }; }
+  return { reason: `unknown runner label ${labels.join(',')}` };
+}
+function hostRuns(os) { const h = hostClass(); return os === 'linux' ? h === 'linux' || h === 'darwin' : os === h; }
+
+// forge#4040 (SEC-5, FIX-2): no expression whose value could carry attacker-influenced text is ever substituted into script
+// text. A `github.*` or `env.*` expression (env values are themselves expanded from github.* at plan time, so
+// `${{ env.X }}` is the indirect form of the same injection) is evaluated into an environment VALUE and the script gets a
+// quoted shell variable reference. Any other expression is substituted literally only when its value is inert
+// ([A-Za-z0-9_./:@+,=-]); otherwise it goes through the environment too.
+const INERT = /^[A-Za-z0-9_.\/:@+,=-]*$/;
+function quoteState(before) {
+  let q = '';
+  for (let i = 0; i < before.length; i++) {
+    const c = before[i];
+    if (q === "'") { if (c === "'") q = ''; continue; }
+    if (c === '\\') { i++; continue; }
+    if (q === '"') { if (c === '"') q = ''; continue; }
+    if (c === '"' || c === "'") q = c;
+  }
+  return q;
+}
+export function interpolateRunScript(text, ctx, env, shell) {
+  if (typeof text !== 'string' || !text.includes('${{')) return text;
+  const posix = !shell || /^\s*(bash|sh)(\s|$)/.test(String(shell));
+  let n = 0;
+  return text.replace(/\$\{\{([\s\S]*?)\}\}/g, (m, e, off, whole) => {
+    const v = str(evalExpr(e, ctx));
+    const tainted = /(^|[^A-Za-z0-9_.])(github|env)\s*(\.|\[)/.test(e);
+    if (!tainted && INERT.test(v)) return v;
+    if (!posix) throw new Unsupported('expression with a non-inert value in a non-POSIX shell script');
+    const name = `FORGE_CI_EXPR_${++n}`; env[name] = v;
+    const q = quoteState(whole.slice(0, off));
+    return q === '"' ? `\${${name}}` : q === "'" ? `'"\${${name}}"'` : `"\${${name}}"`;
+  });
+}
+
+function versionNote(action, step, ctx) {
+  const spec = SETUP[action]; if (!spec) return '';
+  const want = interpolate(String((step.with || {})[spec.key] ?? ''), ctx);
+  if (!want || /lts|latest|stable|nightly|[<>~^*]|file/i.test(want) || /^\W*$/.test(want)) return '';
+  const w = majorOf(want); if (w === null) return '';
+  const l = majorOf(spec.local() || '');
+  return l !== null && l !== w ? `${action} wants ${spec.key} ${want}; local is ${String(spec.local()).slice(0, 40)} (major differs)` : '';
+}
+
+function shellcheckStep(action, step, ctx, a) {
+  const w = step.with || {};
+  const isLudeeus = action.startsWith('ludeeus');
+  const dir = String(interpolate(String(isLudeeus ? (w.scandir || '.') : (w.path || '.')), ctx)).replace(/^\.\//, '') || '.';
+  const ign = String(w.ignore_paths || w.exclude || '').split(/\s+/).filter(Boolean).map((p) => p.replace(/^\.\//, '').replace(/\/$/, ''));
+  const ignNames = String(w.ignore_names || '').split(/\s+/).filter(Boolean);
+  const extra = String(w.additional_files || '').split(/\s+/).filter(Boolean);
+  const sev = isLudeeus ? w.severity : null;
+  const files = a.tracked.filter((f) => /\.(sh|bash|ksh)$/.test(f) && (dir === '.' || f === dir || f.startsWith(dir.replace(/\/$/, '') + '/')) && !ign.some((p) => f === p || f.startsWith(p + '/')) && !ignNames.includes(path.posix.basename(f)));
+  for (const f of extra) if (a.tracked.includes(f) && !files.includes(f)) files.push(f);
+  const flags = [];
+  if (sev) flags.push('-S', String(sev));
+  if (!isLudeeus && w.shellcheck_flags !== '') flags.push(...String(w.shellcheck_flags ?? '--external-sources').split(/\s+/).filter(Boolean));
+  if (isLudeeus && w.shellcheck_opts) flags.push(...String(w.shellcheck_opts).split(/\s+/).filter(Boolean));
+  if (!commandExists('shellcheck')) return { missing: 'shellcheck' };
+  if (!files.length) return { noop: true, note: `no shell files under ${dir}` };
+  return { command: ['shellcheck', ...flags, ...files.sort()].map((t) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(t) ? t : `'${t.replace(/'/g, "'\\''")}'`)).join(' ') };
+}
+
+// dorny/paths-filter: evaluate each filter against the changed files; returns { name: 'true'|'false', changes: json }.
+function pathsFilterOutputs(step, ctx, a) {
+  const w = step.with || {};
+  let text = w.filters;
+  if (typeof text !== 'string') throw new Unsupported('paths-filter without inline filters');
+  text = interpolate(text, ctx);
+  if (!/\n/.test(text) && /\.ya?ml$/.test(text.trim())) {
+    const f = text.trim().replace(/^\.\//, '');
+    const body = a.readDefs(f); const t = body.head != null ? body.head : body.base;
+    if (t == null) throw new Unsupported('paths-filter file ' + f);
+    text = t;
+  }
+  const doc = parseYaml(text);
+  if (!doc || typeof doc !== 'object') throw new Unsupported('paths-filter filters unreadable');
+  const out = {}; const hit = [];
+  const flat = (v) => (typeof v === 'string' ? [v] : Array.isArray(v) ? v.flatMap(flat) : v && typeof v === 'object' ? Object.values(v).flatMap(flat) : []);
+  for (const [name, spec] of Object.entries(doc)) {
+    const pats = flat(spec);
+    const ok = a.changed.some((f) => matchesFilter(f, pats));
+    out[name] = ok ? 'true' : 'false'; if (ok) hit.push(name);
+  }
+  out.changes = JSON.stringify(hit);
+  return out;
+}
+
+function parseServices(svcs, ctx) {
+  const out = [];
+  for (const [name, s] of Object.entries(svcs || {})) {
+    if (!s || typeof s.image !== 'string') throw new Unsupported('service without image');
+    if (s.credentials) throw new Unsupported('service credentials');
+    const env = {}; for (const [k, v] of Object.entries(s.env || {})) env[k] = String(interpolate(String(v), ctx));
+    out.push({ name, image: String(interpolate(s.image, ctx)), env, ports: (s.ports || []).map(String), options: s.options ? String(interpolate(String(s.options), ctx)) : '' });
+  }
+  return out;
+}
+
+export function plan(a) {
+  const jobsOut = []; const warnings = []; const used = [];
+  const files = a.defFiles(DEF_RE);
+  for (const file of files) {
+    const { base, head } = a.readDefs(file);
+    const doc = mergeDocs(base, head);
+    const wfName = path.posix.basename(file).replace(/\.ya?ml$/, '');
+    if (doc === undefined) { warnings.push(`${file}: unreadable YAML; its jobs are deferred-to-ci`); jobsOut.push(deferred(jobId('gha', wfName), 'github-actions', file, 'workflow YAML unreadable')); continue; }
+    if (!doc || typeof doc !== 'object' || !doc.jobs) continue;
+    used.push(file);
+    const ev = events(doc.on !== undefined ? doc.on : doc.true);
+    if (ev.pull_request_target) { jobsOut.push(deferred(jobId('gha', wfName), 'github-actions', doc.name || file, 'pull_request_target workflow runs with base-branch secrets')); continue; }
+    const why = gateReason(ev, a);
+    if (why) { jobsOut.push(notApplicable(jobId('gha', wfName), 'github-actions', doc.name || file, why)); continue; }
+    planWorkflow(file, wfName, doc, a, jobsOut, warnings);
+  }
+  return { jobs: jobsOut, warnings, used };
+}
+
+function planWorkflow(file, wfName, doc, a, out, warnings) {
+  const wfEnv = doc.env || {};
+  const base = { github: { event_name: 'pull_request', base_ref: a.baseBranch, head_ref: a.headBranch || '', ref: `refs/heads/${a.headBranch || ''}`, ref_name: a.headBranch || '', ref_type: 'branch', sha: a.headSha, repository: a.repository || '', workspace: a.repo, event: { pull_request: { base: { sha: a.baseSha, ref: a.baseBranch, repo: { full_name: a.repository || '' } }, head: { sha: a.headSha, ref: a.headBranch || '', repo: { fork: false, full_name: a.repository || '' } }, draft: false, labels: [] } } }, runner: { os: { linux: 'Linux', darwin: 'macOS', win32: 'Windows' }[hostClass()], arch: process.arch === 'arm64' ? 'ARM64' : 'X64', temp: process.env.TMPDIR || '/tmp' } };
+  const jobs = doc.jobs; const results = {}; // jobKey -> { status, outputs }
+  const planOne = (key) => {
+    const job = jobs[key] || {};
+    const jid = jobId('gha', wfName, key);
+    let name = key;
+    const needs = [].concat(job.needs || []).filter((n) => typeof n === 'string');
+    const baseCtx = { ...base, env: {}, needs: {}, steps: undefined };
+    for (const n of needs) if (results[n] && results[n].outputs) baseCtx.needs[n] = { outputs: results[n].outputs, result: results[n].status === 'applicable' ? 'success' : 'skipped' };
+    try { if (typeof job.name === 'string') name = String(interpolate(job.name, { ...baseCtx, matrix: undefined })) || key; } catch { name = job.name; }
+    const def = (reason, extra) => { out.push(deferred(jid, 'github-actions', name, reason, { needs: needs.map((n) => jobId('gha', wfName, n)), ...extra })); results[key] = { status: 'deferred', outputs: null }; };
+    const na = (reason) => { out.push(notApplicable(jid, 'github-actions', name, reason)); results[key] = { status: 'skipped', outputs: {} }; };
+
+    try {
+      // needs: a deferred or missing dependency means the job cannot be proven here
+      const badNeed = needs.find((n) => !results[n] || results[n].status === 'deferred');
+      const skipNeed = needs.find((n) => results[n] && results[n].status === 'skipped');
+      if (badNeed && !(typeof job.if === 'string' && /always\(\)/.test(job.if))) return def(`needs ${badNeed}, which is not run locally`);
+      if (skipNeed && !(typeof job.if === 'string' && /always\(\)/.test(job.if))) return na(`needs ${skipNeed}, which was skipped`);
+      if (job.uses) return def('reusable workflow job');
+      if (job.container) return def('job runs in a container');
+      if (job.environment) return def('environment-protected job (deploy)');
+      if (job.if !== undefined && !condTrue(job.if, { ...baseCtx, env: wfEnv })) return na(`job if: ${String(job.if).trim().slice(0, 80)} is false`);
+      if (DEPLOY_NAME.test(key) || DEPLOY_NAME.test(String(job.name || ''))) return def('deploy/publish job');
+      const scanJob = JSON.stringify({ ...job, steps: (job.steps || []).map((s) => (s && s.uses && (NOOP_ACTIONS.test(s.uses) || SETUP[String(s.uses).split('@')[0]]) ? { ...s, with: undefined } : s)) });
+      if (SECRET_REF.test(scanJob) || SECRET_REF.test(JSON.stringify(wfEnv))) return def('references secrets');
+      if (job.permissions && job.permissions['id-token'] === 'write') return def('requests an OIDC token');
+
+      const matrixCtx = { ...baseCtx, env: wfEnv };
+      const combos = expandMatrix(job.strategy && job.strategy.matrix, matrixCtx);
+      const variants = []; let chosen = null;
+      for (const combo of combos) {
+        const cctx = { ...baseCtx, matrix: combo, env: wfEnv };
+        let ro = job['runs-on']; if (typeof ro === 'string') ro = interpolate(ro, cctx); else if (Array.isArray(ro)) ro = ro.map((x) => interpolate(x, cctx));
+        const c = osClass(ro);
+        const tag = Object.keys(combo).length ? Object.entries(combo).map(([k, v]) => `${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`).join(',') : '';
+        if (c.reason) { variants.push(`${tag || 'default'}: ${c.reason}`); continue; }
+        if (!hostRuns(c.os)) { variants.push(`${tag || c.label}: ${c.label} (host is ${hostClass()})`); continue; }
+        if (chosen) { variants.push(`${tag || c.label}: matrix variant not run locally`); continue; }
+        chosen = { combo, ctx: cctx, tag };
+      }
+      if (!chosen && combos.length === 1) return def(variants[0].replace(/^[^:]*: /, ''));
+      if (variants.length) out.push(deferred(jobId(jid, 'variants'), 'github-actions', name, `${variants.length} variant(s) not run on this host: ${variants.slice(0, 3).join('; ')}${variants.length > 3 ? '; ...' : ''}`, { variants: variants.length }));
+      if (!chosen) { results[key] = { status: 'deferred', outputs: null }; return; }
+      const built = buildJob(file, wfName, key, jid, name, job, doc, chosen, needs, wfEnv, a, warnings);
+      if (built.defer) return def(built.defer);
+      results[key] = { status: 'applicable', outputs: built.outputs };
+      out.push(built.job);
+    } catch (e) {
+      if (e instanceof Unsupported) return def(`unsupported construct: ${e.message}`);
+      throw e;
+    }
+  };
+  for (const key of topo(jobs)) planOne(key);
+}
+
+function buildJob(file, wfName, key, jid, name, job, doc, chosen, needs, wfEnv, a, warnings) {
+  const ctx = chosen.ctx;
+  const jobEnvRaw = { ...wfEnv, ...(job.env || {}) };
+  const env = {};
+  for (const [k, v] of Object.entries(jobEnvRaw)) env[k] = String(interpolate(String(v), ctx));
+  ctx.env = env;
+  const defaults = { ...(doc.defaults && doc.defaults.run), ...(job.defaults && job.defaults.run) };
+  const steps = []; const notes = []; const stepsCtx = {}; ctx.steps = stepsCtx;
+  const toolWarn = [];
+  let outputs = {};
+  for (const [i, st] of (job.steps || []).entries()) {
+    if (!st) continue;
+    if (st.if !== undefined && !condTrue(st.if, ctx)) continue;
+    const label = st.name ? String(interpolate(String(st.name), ctx)) : (st.uses ? String(st.uses) : `step ${i + 1}`);
+    const senv = {}; for (const [k, v] of Object.entries(st.env || {})) senv[k] = String(interpolate(String(v), ctx));
+    if (st.uses) {
+      const action = String(st.uses).split('@')[0];
+      if (NOOP_ACTIONS.test(String(st.uses))) continue;
+      if (SETUP[action]) {
+        if (!commandExists(SETUP[action].tool)) return { defer: `toolchain not installed locally: ${SETUP[action].tool} (${action})` };
+        const n = versionNote(action, st, ctx); if (n) toolWarn.push(n);
+        continue;
+      }
+      if (/^dorny\/paths-filter$/.test(action)) { stepsCtx[st.id || `step${i}`] = { outputs: pathsFilterOutputs(st, ctx, a) }; continue; }
+      if (SHELLCHECK_ACTIONS.test(String(st.uses))) {
+        const sc = shellcheckStep(action, st, ctx, a);
+        if (sc.missing) return { defer: `tool not installed: ${sc.missing}` };
+        if (sc.noop) continue;
+        steps.push({ name: label, command: sc.command, cwd: '.', env: { ...senv }, shell: 'bash', kind: 'check' });
+        continue;
+      }
+      return { defer: `unknown action ${st.uses}` };
+    }
+    if (typeof st.run === 'string') {
+      const script = interpolateRunScript(st.run, { ...ctx, env: { ...ctx.env, ...senv } }, senv, st.shell || defaults.shell);
+      const cwd = st['working-directory'] || defaults['working-directory'] || '.';
+      const shell = st.shell || defaults.shell;
+      if (!shellArgv(shell)) return { defer: `shell ${shell} is not available locally` };
+      const r = stepsFromScript(script, { name: label, cwd: String(interpolate(String(cwd), ctx)), env: senv, shell, repo: a.repo, continue_on_error: st['continue-on-error'] === true, timeout_s: st['timeout-minutes'] ? Number(st['timeout-minutes']) * 60 : undefined });
+      if (r.defer) return { defer: r.defer };
+      steps.push(...r.steps);
+      continue;
+    }
+    return { defer: `unsupported step shape at index ${i}` };
+  }
+  // job outputs resolved from dorny steps (the `changes` job pattern)
+  for (const [k, v] of Object.entries(job.outputs || {})) { try { outputs[k] = String(interpolate(String(v), ctx)); } catch { /* left unresolved: needs.X.outputs.k is Unsupported downstream */ } }
+  if (!steps.length && !Object.keys(outputs).length && !(job.steps || []).length) return { defer: 'job has no steps' };
+  let services = [];
+  if (job.services) services = parseServices(job.services, ctx);
+  warnings.push(...toolWarn.map((w) => `${jid}: ${w}`));
+  const timeout_s = job['timeout-minutes'] ? Number(job['timeout-minutes']) * 60 : undefined;
+  const j = { id: jid, source: 'github-actions', name, workflow: file, cwd: '.', env, services, steps, needs: needs.map((n) => jobId('gha', wfName, n)), timeout_s, matrix: chosen.tag || undefined, deferred_reason: null, warnings: toolWarn, version_drift: toolWarn.length ? toolWarn : undefined, resolves_outputs: Object.keys(outputs).length > 0 && !steps.length };
+  if (!steps.length) { j.not_applicable = Object.keys(outputs).length ? 'resolved locally (path-filter outputs only)' : 'no runnable steps'; }
+  return { job: j, outputs };
+}

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;
+}