mandrel-platform 0.25.0 → 0.26.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/check-workflow-gh-flags.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * check-workflow-gh-flags.mjs — static lint for known-invalid `gh` CLI flag
+ * combinations inside GitHub Actions workflows.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A `gh api` invocation is valid shell and passes `actionlint` /
+ * `shellcheck`, yet can still be rejected by the `gh` CLI at RUNTIME because a
+ * flag combination is unsupported. That failure surfaces only when the step
+ * runs — for the release pipeline, that means "at release time", the worst
+ * possible moment. Release 0.25.0 wedged its `await-smoke` gate for exactly
+ * this reason:
+ *
+ *     gh api --paginate --slurp "…/status" --jq '…'
+ *     → the `--slurp` option is not supported with `--jq` or `--template`
+ *
+ * Every poll attempt failed instantly, `|| echo none` swallowed it, and the
+ * gate timed out on EVERY release even though smoke was green. No unit test,
+ * acceptance critic, epic-audit, or code-review caught it because none
+ * exercised the real `gh` CLI. This lint shifts that class of failure LEFT
+ * into `ci-required` so an invalid `gh` invocation fails a PR, not a release.
+ *
+ * RULES (extensible — add more as new `gh` incompatibilities are discovered):
+ *   1. slurp-with-jq — `gh` rejects `--slurp` together with `--jq` or
+ *      `--template`. The supported pattern is `gh api --slurp … | jq …`
+ *      (pipe to a STANDALONE jq), so this lint splits on shell pipes and only
+ *      flags a single `gh` command segment that carries BOTH flags.
+ *
+ * SCOPE: `.github/workflows/*.yml` + `templates/workflows/*.yml`.
+ * Exit 0 when clean, 1 when any violation is found (prints file:line).
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const WORKFLOW_DIRS = ['.github/workflows', 'templates/workflows'];
+
+/**
+ * Blank out full-line comments (YAML `#` lines and shell `#` comment lines
+ * inside `run:` blocks) while preserving line count, so the lint never
+ * analyzes PROSE — a workflow comment that merely *documents* an invalid flag
+ * combo (like this file's own header, or a step comment describing the rule)
+ * is not a `gh` command and must not be flagged. Only whole-line comments are
+ * stripped; an inline `#` inside real shell is left alone (it is rarely a
+ * comment there and never carries the flag pattern this lint targets).
+ */
+export function stripComments(source) {
+  return source
+    .split('\n')
+    .map((line) => (/^\s*#/.test(line) ? '' : line))
+    .join('\n');
+}
+
+/**
+ * Collapse shell line-continuations (`\` + newline) so a multi-line `gh`
+ * invocation becomes one logical line, WITHOUT losing the original line number
+ * of where the command started. Returns an array of
+ * `{ line, text }` logical commands (1-indexed `line`).
+ */
+export function collapseContinuations(source) {
+  const rawLines = source.split('\n');
+  const logical = [];
+  let buf = null;
+  let startLine = 0;
+  for (let i = 0; i < rawLines.length; i++) {
+    const line = rawLines[i];
+    const continues = /\\\s*$/.test(line);
+    const stripped = line.replace(/\\\s*$/, '');
+    if (buf === null) {
+      startLine = i + 1;
+      buf = stripped;
+    } else {
+      buf += ' ' + stripped.trim();
+    }
+    if (!continues) {
+      logical.push({ line: startLine, text: buf });
+      buf = null;
+    }
+  }
+  if (buf !== null) logical.push({ line: startLine, text: buf });
+  return logical;
+}
+
+/**
+ * Split a logical shell line into command segments on the separators that
+ * terminate one simple command and start another: pipe, `;`, `&&`, `||`,
+ * and command-substitution boundaries. A `gh api --slurp … | jq …` therefore
+ * becomes two segments — the `gh` part (no `--jq`) and the `jq` part — so the
+ * SUPPORTED pattern is never flagged.
+ */
+export function splitSegments(text) {
+  // Split on |, ||, ;, &&, and the `$(` / `)` / backtick substitution edges.
+  return text.split(/\|\||&&|[|;`]|\$\(|\)/);
+}
+
+/** Return an array of rule-violation strings for one segment (may be empty). */
+export function lintSegment(segment) {
+  const violations = [];
+  const isGh = /(^|\s)gh(\s|$)/.test(segment);
+  if (!isGh) return violations;
+
+  // Rule 1 — slurp-with-jq/template.
+  const hasSlurp = /(^|\s)--slurp(\s|=|$)/.test(segment);
+  const hasJq = /(^|\s)--jq(\s|=|$)/.test(segment);
+  const hasTemplate = /(^|\s)(--template|-t)(\s|=|$)/.test(segment);
+  if (hasSlurp && (hasJq || hasTemplate)) {
+    violations.push(
+      `slurp-with-jq: \`gh\` rejects --slurp together with ${
+        hasJq ? '--jq' : '--template'
+      }. Pipe --slurp's output to a STANDALONE jq instead: \`gh api --slurp … | jq …\`.`,
+    );
+  }
+  return violations;
+}
+
+/** Lint a single workflow file. Returns an array of finding objects. */
+export function lintFile(path, source) {
+  const findings = [];
+  for (const { line, text } of collapseContinuations(stripComments(source))) {
+    for (const segment of splitSegments(text)) {
+      for (const rule of lintSegment(segment)) {
+        findings.push({ path, line, rule });
+      }
+    }
+  }
+  return findings;
+}
+
+function collectWorkflowFiles() {
+  const files = [];
+  for (const dir of WORKFLOW_DIRS) {
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      if (name.endsWith('.yml') || name.endsWith('.yaml')) {
+        files.push(join(dir, name));
+      }
+    }
+  }
+  return files.sort();
+}
+
+function main() {
+  const files = collectWorkflowFiles();
+  const findings = [];
+  for (const f of files) {
+    findings.push(...lintFile(f, readFileSync(f, 'utf8')));
+  }
+
+  if (findings.length === 0) {
+    console.log(
+      `[check-workflow-gh-flags] ✓ ${files.length} workflow file(s) — no invalid gh flag combinations.`,
+    );
+    return 0;
+  }
+
+  console.error(
+    `[check-workflow-gh-flags] ✗ ${findings.length} invalid gh flag combination(s):\n`,
+  );
+  for (const { path, line, rule } of findings) {
+    console.error(`  ${path}:${line} — ${rule}`);
+  }
+  console.error(
+    '\nThese pass actionlint/shellcheck but fail the `gh` CLI at RUNTIME. Fix before merge.',
+  );
+  return 1;
+}
+
+// Run only as a CLI, not when imported by the test suite.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main());
+}

package/scripts/check-workflow-gh-flags.test.mjs

@@ -0,0 +1,86 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  collapseContinuations,
+  splitSegments,
+  lintSegment,
+  lintFile,
+} from './check-workflow-gh-flags.mjs';
+
+test('collapseContinuations joins backslash-continued lines and keeps start line', () => {
+  const src = ['a=1', 'state="$(gh api --slurp x \\', '  --jq y \\', '  || echo none)"', 'b=2'].join(
+    '\n',
+  );
+  const logical = collapseContinuations(src);
+  const joined = logical.find((l) => l.text.includes('gh api'));
+  assert.equal(joined.line, 2, 'start line is the first line of the command');
+  assert.match(joined.text, /gh api --slurp x\s+--jq y\s+\|\| echo none/);
+});
+
+test('lintSegment flags gh --slurp with --jq (the 0.25.0 regression)', () => {
+  const v = lintSegment('gh api --paginate --slurp "repos/x/commits/y/status" --jq \'.a\'');
+  assert.equal(v.length, 1);
+  assert.match(v[0], /slurp-with-jq/);
+});
+
+test('lintSegment flags gh --slurp with --template / -t', () => {
+  assert.equal(lintSegment('gh api --slurp x --template "{{.a}}"').length, 1);
+  assert.equal(lintSegment('gh api --slurp x -t "{{.a}}"').length, 1);
+});
+
+test('lintSegment does NOT flag the SUPPORTED pattern (slurp piped to standalone jq)', () => {
+  // The pipe splits this into two segments upstream; each segment alone is clean.
+  assert.equal(lintSegment('gh api --paginate --slurp "…/status"').length, 0);
+  assert.equal(lintSegment(" jq -r '[.[].statuses[]] | first.state'").length, 0);
+});
+
+test('lintSegment ignores non-gh commands and plain gh usage', () => {
+  assert.equal(lintSegment('jq --slurp --jq nonsense').length, 0, 'not a gh command');
+  assert.equal(lintSegment('gh api "repos/x" --jq .a').length, 0, 'jq without slurp is fine');
+  assert.equal(lintSegment('gh api --slurp x').length, 0, 'slurp without jq is fine');
+});
+
+test('splitSegments separates a gh|jq pipe so the supported pattern is not flagged end-to-end', () => {
+  const cmd =
+    'state="$(gh api --paginate --slurp "repos/x/commits/y/status" | jq -r \'.a\' || echo none)"';
+  const segs = splitSegments(cmd);
+  const flagged = segs.flatMap((s) => lintSegment(s));
+  assert.equal(flagged.length, 0, 'gh segment has slurp-no-jq; jq segment is not gh');
+});
+
+test('lintFile flags the invalid combo across continuation lines', () => {
+  const src = [
+    'jobs:',
+    '  x:',
+    '    steps:',
+    '      - run: |',
+    '          state="$(gh api --slurp "u" \\',
+    "            --jq '.a' \\",
+    '            || echo none)"',
+  ].join('\n');
+  const findings = lintFile('.github/workflows/fake.yml', src);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].line, 5, 'points at the line the gh command starts on');
+  assert.match(findings[0].rule, /slurp-with-jq/);
+});
+
+test('lintFile ignores COMMENTS that merely document the invalid combo (false-positive guard)', () => {
+  // A step comment describing the rule — must NOT be flagged (regression: this
+  // exact false positive failed CI on the guard's own PR).
+  const src = [
+    '      # Catches gh flag combos like --slurp with --jq that fail at runtime.',
+    '      - name: Lint gh CLI flag combinations',
+    '        run: node scripts/check-workflow-gh-flags.mjs',
+  ].join('\n');
+  assert.deepEqual(lintFile('.github/workflows/ci.yml', src), []);
+});
+
+test('lintFile is clean for the corrected release-please pattern', () => {
+  const src = [
+    '      - run: |',
+    '          state="$(gh api --paginate --slurp "u" 2>/dev/null \\',
+    "            | jq -r '[.[].statuses[]] | first.state' \\",
+    '            || echo none)"',
+  ].join('\n');
+  assert.deepEqual(lintFile('.github/workflows/ok.yml', src), []);
+});