@pareto4/pp-core 1.5.0

package/scripts/workflow-policy.cjs

@@ -0,0 +1,483 @@
+'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 helpers
+// ---------------------------------------------------------------------------
+
+// Build the GitHub Actions Cartesian product of the given base-list matrix
+// keys. Returns one context object per realized job, each mapping every key
+// to a stringified value. A single key yields one context per value (identical
+// to the legacy base-list expansion); N keys yield the full cross-product.
+// Values are stringified to match runner-label comparison and matrix-expression
+// resolution, which operate on strings.
+function cartesianProduct(keys, matrix) {
+  return keys.reduce(
+    (contexts, key) =>
+      contexts.flatMap((context) =>
+        matrix[key].map((value) => ({ ...context, [key]: String(value) })),
+      ),
+    [{}],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 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 });
+      }
+    }
+  }
+
+  // GitHub Actions realizes one job per element of the Cartesian product of all
+  // base-list matrix keys (every matrix.<k> that is an array, excluding the
+  // include/exclude control keys), and each realized job's context carries a
+  // value for EVERY matrix key — so ${{ matrix.<key> }} references (e.g. in a
+  // shell: field) resolve against any realization, not only the runs-on key.
+  // Single-axis matrices yield exactly one realization per value, identical to
+  // the prior behavior; only multi-axis matrices change shape.
+  // Each realization is pushed unconditionally — deduplicating by runner label
+  // would collapse distinct Cartesian rows (e.g. matrix.os: [macos-latest,
+  // macos-latest] paired with different shells) and hide policy violations.
+  if (Array.isArray(matrix[key])) {
+    const baseListKeys = Object.keys(matrix).filter(
+      (k) => k !== 'include' && k !== 'exclude' && Array.isArray(matrix[k]),
+    );
+    for (const context of cartesianProduct(baseListKeys, matrix)) {
+      realizations.push({ runner: context[key], resolvable: true, context });
+    }
+  }
+
+  // matrix.exclude: remove matches by runner label (first match only).
+  // KNOWN LIMITATION (out of scope for #435, tracked as a follow-up): this
+  // matches on the runs-on key's runner label rather than the full exclude
+  // tuple, so a multi-axis exclude like { os: macos-latest, shell: bash } can
+  // remove the wrong cross-product cell. Full GitHub Actions tuple-match
+  // (including the include-rows-are-not-excluded rule) is deferred; #435 scopes
+  // only the base-list cross-product expansion above.
+  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,
+};

package/scripts/workflow-size.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * @file workflow-size.cjs
+ *
+ * Single source of truth for measuring workflow `.md` file sizes in bytes.
+ *
+ * Shared by `tests/workflow-size-budget.test.cjs` (the CI guard) and
+ * `scripts/update-size-baseline.cjs` (the baseline generator) so the two can
+ * never disagree on HOW a file is measured.  A divergence between the generator
+ * and the guard would silently mis-record the baseline (issue #1074).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const WORKFLOWS_DIR = path.join(__dirname, '..', 'pp-core', 'workflows');
+
+/**
+ * Byte size of a file, counted as on an LF (Unix) checkout.
+ *
+ * The size budget is calibrated against `wc -c` on a Unix (LF) checkout, but
+ * these `.md` files have no `eol=lf` in `.gitattributes`, so Windows checks
+ * them out as CRLF.  Counting raw on-disk bytes there adds one byte per line,
+ * a Windows-only false positive that diverges from the LF calibration basis
+ * (issue #683).  Stripping CR yields the same LF byte count on every platform.
+ * This is still a raw byte count (not a trailing-newline-stripping line count).
+ *
+ * @param {string} filePath - Absolute or relative path to the file.
+ * @returns {number} LF-normalized byte length.
+ */
+function lfByteCount(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return Buffer.byteLength(content.replace(/\r\n/g, '\n'), 'utf-8');
+}
+
+/**
+ * List top-level workflow stems (filenames without the `.md` extension), sorted.
+ * Non-recursive by design: per-mode bodies under `workflows/<name>/modes/` and
+ * templates are NOT measured — only the always-loaded top-level workflows.
+ *
+ * @param {string} [dir] - Workflows directory (defaults to the canonical one).
+ * @returns {string[]} Sorted stems, e.g. `['autonomous', 'plan-phase', ...]`.
+ */
+function listWorkflowStems(dir = WORKFLOWS_DIR) {
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+/**
+ * Measure every top-level `.md` file in `dir`, keyed by filename, byte sizes.
+ * Generic over directory and an optional filename predicate — used for both
+ * workflows (`pp-core/workflows/*.md`) and agents (`agents/gsd-*.md`) so the
+ * size guards and the baseline generator share one measurement path (#1074).
+ * Non-recursive by design.
+ *
+ * @param {string} dir - Directory to scan.
+ * @param {function(string): boolean} [predicate] - Filename filter (default: all `.md`).
+ * @returns {Object<string, number>} Map of filename → LF byte size, keys sorted.
+ */
+function measureMdFiles(dir, predicate = () => true) {
+  const out = {};
+  const names = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && predicate(f))
+    .sort();
+  for (const name of names) out[name] = lfByteCount(path.join(dir, name));
+  return out;
+}
+
+/**
+ * Measure every top-level workflow file, keyed by filename (`<stem>.md`).
+ *
+ * @param {string} [dir] - Workflows directory (defaults to the canonical one).
+ * @returns {Object<string, number>} Map of `<stem>.md` → LF byte size, sorted.
+ */
+function measureWorkflows(dir = WORKFLOWS_DIR) {
+  return measureMdFiles(dir);
+}
+
+module.exports = {
+  WORKFLOWS_DIR,
+  lfByteCount,
+  listWorkflowStems,
+  measureMdFiles,
+  measureWorkflows,
+};