@opengsd/gsd-core 1.2.0-rc.1

package/scripts/workflow-policy.cjs

@@ -0,0 +1,450 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// ---------------------------------------------------------------------------
+// Policy: native shell per OS
+// ---------------------------------------------------------------------------
+const POLICY = Object.freeze({
+  'ubuntu-latest':  'bash',
+  'ubuntu-22.04':   'bash',
+  'ubuntu-24.04':   'bash',
+  'macos-latest':   'zsh',
+  'macos-13':       'zsh',
+  'macos-14':       'zsh',
+  'macos-15':       'zsh',
+  'windows-latest': 'pwsh',
+  'windows-2022':   'pwsh',
+  'windows-2025':   'pwsh',
+});
+
+const VIOLATION = Object.freeze({
+  WRONG_SHELL_FOR_OS:         'wrong_shell_for_os',
+  MACOS_MISSING_EXPLICIT_ZSH: 'macos_missing_explicit_zsh',
+  UNKNOWN_RUNNER:             'unknown_runner',
+  UNRESOLVABLE_MATRIX:        'unresolvable_matrix',
+});
+
+// ---------------------------------------------------------------------------
+// Runner default (GitHub Actions documented defaults, not policy)
+// ---------------------------------------------------------------------------
+function runnerDefault(runner) {
+  if (!runner) return null;
+  if (runner.startsWith('windows-')) return 'pwsh';
+  return 'bash'; // ubuntu-* and macos-* both default to bash on GHA
+}
+
+// ---------------------------------------------------------------------------
+// Matrix expansion
+// ---------------------------------------------------------------------------
+
+/**
+ * Expand a runs-on expression against a job's strategy.matrix.
+ * Returns an array of { runner: string, resolvable: boolean, context: object }
+ * objects where `context` holds ALL key→value pairs for the realization row
+ * (so shell expressions like ${{ matrix.shell }} can be resolved against it).
+ * 'resolvable: false' means the expression was an unresolved matrix ref.
+ */
+function expandRunsOn(runsOnRaw, matrix) {
+  if (!runsOnRaw) return [];
+
+  const raw = String(runsOnRaw).trim();
+
+  // Detect matrix expression: ${{ matrix.X }} or ${{ matrix['X'] }}
+  const matrixExprRe = /\$\{\{\s*matrix\.(\w+)\s*\}\}/;
+  const match = raw.match(matrixExprRe);
+
+  if (!match) {
+    // Literal runner label
+    return [{ runner: raw, resolvable: true, context: {} }];
+  }
+
+  const key = match[1];
+
+  if (!matrix) {
+    return [{ runner: raw, resolvable: false, context: {} }];
+  }
+
+  const realizations = [];
+
+  // matrix.include entries carry complete row context — prefer them as they
+  // contain all keys (os, node-version, shell, full_only, etc.).
+  // Each include row is a distinct CI realization and must be validated
+  // independently — even if two rows share the same runner label, their
+  // contexts (and therefore effective shells) may differ.
+  if (Array.isArray(matrix.include)) {
+    for (const entry of matrix.include) {
+      if (entry && entry[key] != null) {
+        const runner = String(entry[key]);
+        // Clone all keys from include row as the realization context
+        const context = {};
+        for (const [k, v] of Object.entries(entry)) {
+          context[k] = v != null ? String(v) : '';
+        }
+        realizations.push({ runner, resolvable: true, context });
+      }
+    }
+  }
+
+  // Collect values from matrix.<key> list (e.g. matrix.os: [ubuntu, macos])
+  // These base-list entries have no extra context beyond the key itself.
+  // Each entry is pushed unconditionally — deduplicating by runner alone
+  // would collapse distinct Cartesian rows (e.g. duplicate os values paired
+  // with different shell values) and hide policy violations on later rows.
+  if (Array.isArray(matrix[key])) {
+    for (const val of matrix[key]) {
+      const runner = String(val);
+      realizations.push({ runner, resolvable: true, context: { [key]: runner } });
+    }
+  }
+
+  // matrix.exclude: remove matches
+  if (Array.isArray(matrix.exclude)) {
+    for (const excl of matrix.exclude) {
+      if (excl && excl[key] != null) {
+        const exclRunner = String(excl[key]);
+        const idx = realizations.findIndex(r => r.runner === exclRunner);
+        if (idx !== -1) realizations.splice(idx, 1);
+      }
+    }
+  }
+
+  if (realizations.length === 0) {
+    // Could not resolve — no concrete values found
+    return [{ runner: raw, resolvable: false, context: {} }];
+  }
+
+  return realizations;
+}
+
+// ---------------------------------------------------------------------------
+// Matrix expression resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * If `expr` is a `${{ matrix.<key> }}` expression, look up the value in
+ * `realizationContext` (a plain-object snapshot of one matrix.include row).
+ * Returns:
+ *   { resolved: true, value: string }   — expression resolved to a concrete value
+ *   { resolved: false, key: string }    — matrix key absent in this realization
+ *   null                                — `expr` is not a matrix expression
+ */
+function resolveMatrixExpr(expr, realizationContext) {
+  if (!expr || typeof expr !== 'string') return null;
+  const m = expr.match(/^\s*\$\{\{\s*matrix\.(\w+)\s*\}\}\s*$/);
+  if (!m) return null;
+  const key = m[1];
+  if (!realizationContext || !(key in realizationContext)) {
+    return { resolved: false, key };
+  }
+  return { resolved: true, value: String(realizationContext[key]) };
+}
+
+// ---------------------------------------------------------------------------
+// Effective-shell resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a step's shell, job defaults, workflow defaults, runner, and the
+ * current matrix realization context, return the effective shell that will
+ * actually execute.
+ *
+ * Matrix expressions (`${{ matrix.shell }}`) in any shell field are resolved
+ * against `realizationContext` (a plain object of key→value for the current
+ * matrix.include row).
+ *
+ * Returns:
+ *   { shell: string, unresolvable: false }  — concrete shell value
+ *   { shell: null,  unresolvable: true, key: string } — matrix expr present but key missing
+ */
+function effectiveShell(stepShell, jobDefaultsShell, workflowDefaultsShell, runner, realizationContext) {
+  for (const raw of [stepShell, jobDefaultsShell, workflowDefaultsShell]) {
+    if (!raw) continue;
+    const mx = resolveMatrixExpr(raw, realizationContext);
+    if (mx !== null) {
+      // It's a matrix expression
+      if (!mx.resolved) {
+        return { shell: null, unresolvable: true, key: mx.key };
+      }
+      return { shell: mx.value, unresolvable: false };
+    }
+    // Literal value
+    return { shell: raw, unresolvable: false };
+  }
+  // Nothing set at any level — use runner default
+  return { shell: runnerDefault(runner), unresolvable: false };
+}
+
+// ---------------------------------------------------------------------------
+// Violation detection
+// ---------------------------------------------------------------------------
+/**
+ * Determines whether a step/runner combination violates shell policy.
+ *
+ * `rawStepShell`, `rawJobDefaultsShell`, `rawWorkflowDefaultsShell` are the
+ * raw (possibly matrix-expression) values before resolution. They're used
+ * only for the MACOS_MISSING_EXPLICIT_ZSH sub-classification: that violation
+ * fires only when nothing is set at any level (all three are null/empty AND
+ * the runner default is wrong).
+ */
+function detectViolation(runner, resolvedShell, rawStepShell, rawJobDefaultsShell, rawWorkflowDefaultsShell) {
+  if (!(runner in POLICY)) {
+    return VIOLATION.UNKNOWN_RUNNER;
+  }
+  const expected = POLICY[runner];
+  // GHA accepts custom shells as a format string containing '{0}' (e.g. 'zsh {0}').
+  // Per https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+  // the shell name before the space is the executable; strip the format suffix before
+  // comparing against the policy so 'zsh {0}' satisfies the 'zsh' requirement.
+  const normalizedShell = resolvedShell ? resolvedShell.replace(/\s+\{0\}$/, '') : resolvedShell;
+  if (normalizedShell !== expected) {
+    // Specific subtype for macOS missing explicit zsh:
+    // fires only when no shell is set at any level (inherited runner default).
+    if (runner.startsWith('macos-') && !rawStepShell && !rawJobDefaultsShell && !rawWorkflowDefaultsShell) {
+      return VIOLATION.MACOS_MISSING_EXPLICIT_ZSH;
+    }
+    return VIOLATION.WRONG_SHELL_FOR_OS;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Source map: find line numbers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the line number of a string in YAML text.
+ * Returns 1-based line number of the first occurrence at or after startLine.
+ */
+function findLineNumber(yamlText, searchStr, startLine) {
+  const lines = yamlText.split('\n');
+  const start = Math.max(0, (startLine || 1) - 1);
+  for (let i = start; i < lines.length; i++) {
+    if (lines[i].includes(searchStr)) {
+      return i + 1;
+    }
+  }
+  // Fall back to scanning from beginning
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(searchStr)) {
+      return i + 1;
+    }
+  }
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+// Core inspector
+// ---------------------------------------------------------------------------
+
+/**
+ * inspectWorkflow(yamlText, { filePath }) → structured inspection result
+ */
+function inspectWorkflow(yamlText, { filePath = '<unknown>' } = {}) {
+  let doc;
+  try {
+    doc = yaml.load(yamlText, { schema: yaml.DEFAULT_SCHEMA });
+  } catch (e) {
+    return {
+      filePath,
+      jobs: [],
+      workflowDefaultsShell: null,
+      parseError: e.message,
+    };
+  }
+
+  if (!doc || typeof doc !== 'object') {
+    return { filePath, jobs: [], workflowDefaultsShell: null };
+  }
+
+  const workflowDefaultsShell =
+    doc.defaults?.run?.shell ?? null;
+
+  const jobs = [];
+
+  for (const [jobId, jobDef] of Object.entries(doc.jobs || {})) {
+    if (!jobDef || typeof jobDef !== 'object') continue;
+
+    const runsOnRaw = jobDef['runs-on'];
+    const matrix = jobDef.strategy?.matrix ?? null;
+    const jobDefaultsShell = jobDef.defaults?.run?.shell ?? null;
+
+    const runsOnStr = runsOnRaw != null ? String(runsOnRaw) : '';
+    const runsOnExpressions = [runsOnStr];
+    const runnerRealizations = expandRunsOn(runsOnStr, matrix);
+
+    const steps = [];
+
+    for (const [stepIndex, step] of (jobDef.steps || []).entries()) {
+      if (!step || typeof step !== 'object') continue;
+
+      // Only check steps that actually run shell scripts (have `run:`)
+      if (!step.run) continue;
+
+      const stepShell = step.shell ?? null;
+      const stepName = step.name ?? `step-${stepIndex}`;
+
+      for (const { runner, resolvable, context: realizationContext } of runnerRealizations) {
+        if (!resolvable) {
+          // Can't resolve runner — emit UNRESOLVABLE_MATRIX
+          const lineNum = findLineNumber(yamlText, stepName !== `step-${stepIndex}` ? stepName : String(step.run).slice(0, 20));
+          steps.push({
+            index: stepIndex,
+            name: stepName,
+            stepShell,
+            effectiveShell: null,
+            runner,
+            violation: VIOLATION.UNRESOLVABLE_MATRIX,
+            evidence: {
+              line: lineNum,
+              snippet: `runs-on: ${runsOnStr} (unresolvable matrix expression)`,
+            },
+          });
+          continue;
+        }
+
+        const effResult = effectiveShell(stepShell, jobDefaultsShell, workflowDefaultsShell, runner, realizationContext);
+
+        // If a matrix expression referenced a key not present in this realization row
+        if (effResult.unresolvable) {
+          const lineNum = findLineNumber(yamlText, stepName !== `step-${stepIndex}` ? stepName : String(step.run).slice(0, 20));
+          steps.push({
+            index: stepIndex,
+            name: stepName,
+            stepShell,
+            effectiveShell: null,
+            runner,
+            violation: VIOLATION.UNRESOLVABLE_MATRIX,
+            evidence: {
+              line: lineNum,
+              snippet: `matrix.${effResult.key} not present in realization for runner=${runner}`,
+            },
+          });
+          continue;
+        }
+
+        const eff = effResult.shell;
+        const violation = detectViolation(runner, eff, stepShell, jobDefaultsShell, workflowDefaultsShell);
+
+        // Find evidence line: prefer step name, then shell:, then run: content
+        let evidenceLine = 1;
+        let evidenceSnippet = '';
+
+        if (stepName !== `step-${stepIndex}`) {
+          evidenceLine = findLineNumber(yamlText, stepName);
+          evidenceSnippet = `name: ${stepName}`;
+        } else if (stepShell) {
+          evidenceLine = findLineNumber(yamlText, `shell: ${stepShell}`);
+          evidenceSnippet = `shell: ${stepShell}`;
+        } else {
+          const runSnippet = String(step.run).split('\n')[0].slice(0, 40);
+          evidenceLine = findLineNumber(yamlText, runSnippet);
+          evidenceSnippet = runSnippet;
+        }
+
+        steps.push({
+          index: stepIndex,
+          name: stepName,
+          stepShell,
+          effectiveShell: eff,
+          runner,
+          violation: violation ?? null,
+          evidence: {
+            line: evidenceLine,
+            snippet: evidenceSnippet,
+          },
+        });
+      }
+    }
+
+    const resolvedRunners = runnerRealizations
+      .filter(r => r.resolvable)
+      .map(r => r.runner);
+
+    jobs.push({
+      jobId,
+      runsOnExpressions,
+      resolvedRunners,
+      defaultsShell: jobDefaultsShell,
+      steps,
+    });
+  }
+
+  return {
+    filePath,
+    jobs,
+    workflowDefaultsShell,
+  };
+}
+
+/**
+ * inspectWorkflowFile(absPath) — reads file from disk and calls inspectWorkflow.
+ */
+function inspectWorkflowFile(absPath) {
+  const text = fs.readFileSync(absPath, 'utf8');
+  return inspectWorkflow(text, { filePath: absPath });
+}
+
+// ---------------------------------------------------------------------------
+// runPolicyLint
+// ---------------------------------------------------------------------------
+
+/**
+ * runPolicyLint({ workflowsDir }) → { violations, summary }
+ */
+function runPolicyLint({ workflowsDir }) {
+  const absDir = path.resolve(workflowsDir);
+  const files = fs.readdirSync(absDir)
+    .filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+    .map(f => path.join(absDir, f))
+    .sort();
+
+  const violations = [];
+
+  for (const filePath of files) {
+    const result = inspectWorkflowFile(filePath);
+    for (const job of result.jobs) {
+      for (const step of job.steps) {
+        if (step.violation) {
+          violations.push({
+            filePath: result.filePath,
+            jobId: job.jobId,
+            stepIndex: step.index,
+            stepName: step.name,
+            runner: step.runner,
+            effectiveShell: step.effectiveShell,
+            stepShell: step.stepShell,
+            violation: step.violation,
+            evidence: step.evidence,
+          });
+        }
+      }
+    }
+  }
+
+  const perViolationType = {};
+  for (const v of violations) {
+    perViolationType[v.violation] = (perViolationType[v.violation] || 0) + 1;
+  }
+
+  return {
+    violations,
+    summary: {
+      total: violations.length,
+      perViolationType,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+module.exports = {
+  POLICY,
+  VIOLATION,
+  inspectWorkflow,
+  inspectWorkflowFile,
+  runPolicyLint,
+};