Parse workflow/dev.yml as YAML in the gate guard; add node:test coverage

Author: dmerand

.github/workflows/tests-pr.yml

@@ -320,11 +320,14 @@ jobs:
   ci-gate-sync:
     name: 'CI gate manifest'
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v4
+      - name: Setup deps
+        uses: ./.github/actions/setup-cli-deps
         with:
           node-version: ${{ env.DEFAULT_NODE_VERSION }}
+      - name: Test the gate checker
+        run: node --test bin/check-ci-gates.test.js
       - name: Check the CI gate manifest matches this workflow
         run: node bin/check-ci-gates.js

bin/check-ci-gates.js

@@ -1,65 +1,82 @@
 // Drift guard: fails if the local CI-gate manifest (bin/ci-gates.js) falls out of
 // sync with .github/workflows/tests-pr.yml, or if the pinned tool versions in
-// dev.yml and tests-pr.yml disagree. Runs in CI (ci-gate-sync job) and locally
-// (pnpm check-ci-gates, also invoked by pre-ci).
+// dev.yml and tests-pr.yml disagree. Parses the YAML structurally (not by regex)
+// so the guard does not break when the workflow's formatting changes.
 import {readFileSync} from 'node:fs'
-import {fileURLToPath} from 'node:url'
+import {fileURLToPath, pathToFileURL} from 'node:url'
 import {dirname, join} from 'node:path'
 
+import {parse as parseYaml} from 'yaml'
+
 import {MANIFEST_JOB_IDS} from './ci-gates.js'
 
-const root = join(dirname(fileURLToPath(import.meta.url)), '..')
-const read = (rel) => readFileSync(join(root, rel), 'utf8')
+// Pure and testable: given the two YAML texts and the manifest job ids, return
+// the list of human-readable problems (empty when everything is in sync).
+export function findProblems({workflow, devYml, manifestJobIds}) {
+  const problems = []
 
-const problems = []
+  const wf = parseYaml(workflow) ?? {}
+  const dev = parseYaml(devYml) ?? {}
 
-// 1. Workflow job ids must exactly match the manifest job ids.
-const workflow = read('.github/workflows/tests-pr.yml')
-const jobsSection = workflow.slice(workflow.search(/^jobs:/m))
-const workflowJobIds = [...jobsSection.matchAll(/^ {2}([A-Za-z0-9_-]+):\s*$/gm)].map((match) => match[1])
+  // 1. Workflow job ids must exactly match the manifest job ids.
+  const workflowJobIds = Object.keys(wf.jobs ?? {})
+  const manifestSet = new Set(manifestJobIds)
+  const workflowSet = new Set(workflowJobIds)
+  const missingFromManifest = workflowJobIds.filter((id) => !manifestSet.has(id))
+  const staleInManifest = manifestJobIds.filter((id) => !workflowSet.has(id))
 
-const manifestSet = new Set(MANIFEST_JOB_IDS)
-const workflowSet = new Set(workflowJobIds)
-const missingFromManifest = workflowJobIds.filter((id) => !manifestSet.has(id))
-const staleInManifest = MANIFEST_JOB_IDS.filter((id) => !workflowSet.has(id))
+  if (missingFromManifest.length > 0) {
+    problems.push(
+      `Workflow jobs not classified in bin/ci-gates.js: ${missingFromManifest.join(', ')}.\n` +
+        `  Add each to CI_GATES as a 'pre-ci' gate (with a local command) or 'ci-only' (with a reason).`,
+    )
+  }
+  if (staleInManifest.length > 0) {
+    problems.push(`bin/ci-gates.js lists jobs absent from tests-pr.yml: ${staleInManifest.join(', ')}.`)
+  }
 
-if (missingFromManifest.length > 0) {
-  problems.push(
-    `Workflow jobs not classified in bin/ci-gates.js: ${missingFromManifest.join(', ')}.\n` +
-      `  Add each to CI_GATES as a 'pre-ci' gate (with a local command) or 'ci-only' (with a reason).`,
-  )
-}
-if (staleInManifest.length > 0) {
-  problems.push(
-    `bin/ci-gates.js lists jobs absent from tests-pr.yml: ${staleInManifest.join(', ')}.\n` +
-      `  Remove them or fix the job id.`,
-  )
-}
+  // 2. Pinned tool versions must agree between dev.yml and tests-pr.yml.
+  const ciNode = wf.env?.DEFAULT_NODE_VERSION
+  const ciPnpm = wf.env?.PNPM_VERSION
+  const nodeStep = (dev.up ?? []).find((step) => step && typeof step === 'object' && step.node)?.node
+  const devNode = nodeStep?.version == null ? undefined : String(nodeStep.version)
+  const devPnpm = nodeStep?.package_manager ? String(nodeStep.package_manager).split('@').pop() : undefined
 
-// 2. Pinned tool versions must agree between dev.yml and tests-pr.yml.
-const devYml = read('dev.yml')
-const pick = (source, regex, label) => {
-  const match = source.match(regex)
-  if (!match) problems.push(`Could not parse ${label}.`)
-  return match ? match[1] : null
-}
+  const require = (value, label) => {
+    if (value == null || value === '') problems.push(`Could not read ${label}.`)
+  }
+  require(ciNode, 'DEFAULT_NODE_VERSION from tests-pr.yml')
+  require(ciPnpm, 'PNPM_VERSION from tests-pr.yml')
+  require(devNode, 'the node version from dev.yml')
+  require(devPnpm, 'the pnpm version from dev.yml')
 
-const ciNode = pick(workflow, /DEFAULT_NODE_VERSION:\s*'([^']+)'/, 'DEFAULT_NODE_VERSION in tests-pr.yml')
-const devNode = pick(devYml, /node:\s*\n\s+version:\s*([0-9][\w.-]*)/, 'node version in dev.yml')
-const ciPnpm = pick(workflow, /PNPM_VERSION:\s*'([^']+)'/, 'PNPM_VERSION in tests-pr.yml')
-const devPnpm = pick(devYml, /package_manager:\s*pnpm@([0-9][\w.-]*)/, 'pnpm version in dev.yml')
+  if (ciNode && devNode && String(ciNode) !== devNode) {
+    problems.push(`Node version mismatch: dev.yml ${devNode} vs tests-pr.yml DEFAULT_NODE_VERSION ${ciNode}.`)
+  }
+  if (ciPnpm && devPnpm && String(ciPnpm) !== devPnpm) {
+    problems.push(`pnpm version mismatch: dev.yml ${devPnpm} vs tests-pr.yml PNPM_VERSION ${ciPnpm}.`)
+  }
 
-if (ciNode && devNode && ciNode !== devNode) {
-  problems.push(`Node version mismatch: dev.yml ${devNode} vs tests-pr.yml DEFAULT_NODE_VERSION ${ciNode}.`)
-}
-if (ciPnpm && devPnpm && ciPnpm !== devPnpm) {
-  problems.push(`pnpm version mismatch: dev.yml ${devPnpm} vs tests-pr.yml PNPM_VERSION ${ciPnpm}.`)
+  return {problems, workflowJobIds, ciNode, ciPnpm}
 }
 
-if (problems.length > 0) {
-  console.error('CI gate manifest is out of sync with the workflow:\n')
-  for (const problem of problems) console.error(`- ${problem}`)
-  process.exit(1)
-}
+// Run as a CLI when invoked directly (not when imported by a test).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+  const read = (rel) => readFileSync(join(root, rel), 'utf8')
+
+  const {problems, workflowJobIds, ciNode, ciPnpm} = findProblems({
+    workflow: read('.github/workflows/tests-pr.yml'),
+    devYml: read('dev.yml'),
+    manifestJobIds: MANIFEST_JOB_IDS,
+  })
 
-console.log(`CI gate manifest in sync: ${workflowJobIds.length} workflow jobs classified; tool versions match (node ${ciNode}, pnpm ${ciPnpm}).`)
+  if (problems.length > 0) {
+    console.error('CI gate manifest is out of sync with the workflow:\n')
+    for (const problem of problems) console.error(`- ${problem}`)
+    process.exit(1)
+  }
+  console.log(
+    `CI gate manifest in sync: ${workflowJobIds.length} workflow jobs classified; tool versions match (node ${ciNode}, pnpm ${ciPnpm}).`,
+  )
+}

bin/check-ci-gates.test.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {findProblems} from './check-ci-gates.js'
+
+const workflow = (jobIds, {node = '26.1.0', pnpm = '10.11.1'} = {}) =>
+  `name: tests\non: pull_request\nenv:\n  DEFAULT_NODE_VERSION: '${node}'\n  PNPM_VERSION: '${pnpm}'\njobs:\n` +
+  jobIds.map((id) => `  ${id}:\n    runs-on: ubuntu-latest\n    steps: []`).join('\n') +
+  '\n'
+
+const devYml = ({node = '26.1.0', pnpm = '10.11.1'} = {}) =>
+  `name: cli\nup:\n  - node:\n      version: ${node}\n      package_manager: pnpm@${pnpm}\n  - packages:\n      - jq\n`
+
+test('in sync: no problems', () => {
+  const {problems} = findProblems({workflow: workflow(['a', 'b']), devYml: devYml(), manifestJobIds: ['a', 'b']})
+  assert.deepEqual(problems, [])
+})
+
+test('workflow job missing from the manifest', () => {
+  const {problems} = findProblems({workflow: workflow(['a', 'b', 'c']), devYml: devYml(), manifestJobIds: ['a', 'b']})
+  assert.match(problems.join('\n'), /not classified.*\bc\b/)
+})
+
+test('manifest lists a job absent from the workflow', () => {
+  const {problems} = findProblems({workflow: workflow(['a']), devYml: devYml(), manifestJobIds: ['a', 'b']})
+  assert.match(problems.join('\n'), /absent from tests-pr\.yml.*\bb\b/)
+})
+
+test('node version mismatch is detected', () => {
+  const {problems} = findProblems({workflow: workflow(['a'], {node: '25.0.0'}), devYml: devYml({node: '26.1.0'}), manifestJobIds: ['a']})
+  assert.match(problems.join('\n'), /Node version mismatch/)
+})
+
+test('pnpm version mismatch is detected', () => {
+  const {problems} = findProblems({workflow: workflow(['a']), devYml: devYml({pnpm: '9.0.0'}), manifestJobIds: ['a']})
+  assert.match(problems.join('\n'), /pnpm version mismatch/)
+})
+
+test('a missing version pin is reported, not silently passed', () => {
+  const noEnv = `name: t\non: pull_request\njobs:\n  a:\n    runs-on: ubuntu-latest\n    steps: []\n`
+  const {problems} = findProblems({workflow: noEnv, devYml: devYml(), manifestJobIds: ['a']})
+  assert.match(problems.join('\n'), /Could not read DEFAULT_NODE_VERSION/)
+})
+
+test('structural parse survives formatting a regex would miss', () => {
+  // Inline comment after the job key and a non-2-space step indent — both break
+  // a line-anchored regex but are irrelevant to a YAML parse.
+  const wf = `env:\n  DEFAULT_NODE_VERSION: '26.1.0'\n  PNPM_VERSION: '10.11.1'\njobs:\n  build: # freshness gate\n    runs-on: ubuntu-latest\n    steps: []\n`
+  const {problems, workflowJobIds} = findProblems({workflow: wf, devYml: devYml(), manifestJobIds: ['build']})
+  assert.deepEqual(workflowJobIds, ['build'])
+  assert.deepEqual(problems, [])
+})

package.json

@@ -85,6 +85,7 @@
     "ts-node": "^10.9.1",
     "typescript": "5.9.3",
     "vitest": "^3.1.4",
+    "yaml": "2.8.3",
     "zod": "3.24.4"
   },
   "workspaces": {