@1aboveio/skills 0.10.0

package/skills/cicd-pipeline/mergify/scripts/audit-core.mjs

@@ -0,0 +1,131 @@
+// Import-only core for auditing a repo's .mergify.yml against this skill's best-practice default.
+//
+//   node audit.mjs [--file .mergify.yml] [--allow-warn] [--json]
+//
+// Like ensure-coverage's ci-audit.mjs, this is a BENCHMARK THAT ABSTAINS, not a YAML
+// parser (the repo ships no YAML dependency). Every check works on the raw text and
+// returns `abstain` when it cannot decide, rather than risk a false verdict. A check
+// that can't find the structure it needs is reported `abstain`, never `pass`.
+//
+// Exit: 2 if any FAIL, 1 if any WARN (unless --allow-warn), else 0.
+import fs from 'node:fs'
+
+// The lines indented UNDER a `key:` (by the first child's indent), or null if the key
+// is absent. Enough structure-awareness to scope a check to one block without a parser.
+export function blockUnder(text, key) {
+  const lines = text.split('\n')
+  const i = lines.findIndex((l) => new RegExp(`^(\\s*)${key}\\s*:`).test(l))
+  if (i < 0) return null
+  const keyIndent = lines[i].match(/^(\s*)/)[1].length
+  const out = []
+  for (let j = i + 1; j < lines.length; j++) {
+    const l = lines[j]
+    if (l.trim() === '' || l.trim().startsWith('#')) { out.push(l); continue }
+    const ind = l.match(/^(\s*)/)[1].length
+    if (ind <= keyIndent) break
+    out.push(l)
+  }
+  return out.join('\n')
+}
+
+// Strip `#` comments so a check never trips on prose that merely NAMES a bad pattern.
+const uncommented = (text) => text.split('\n').map((l) => l.replace(/(^|\s)#.*$/, '')).join('\n')
+
+export function auditText(raw) {
+  const text = uncommented(raw)
+  const f = []
+  const add = (check, status, detail) => f.push({ check, status, detail })
+
+  // 1. Deprecated auto-queue forms — decidable, always wrong.
+  if (/\bauto_merge\s*:\s*true/.test(text)) add('deprecated-forms', 'fail', '`auto_merge: true` is deprecated — use auto_merge_conditions (SKILL.md §1).')
+  else if (/\bautoqueue\s*:/.test(text)) add('deprecated-forms', 'fail', '`queue_rules[].autoqueue` is deprecated — use auto_merge_conditions (SKILL.md §1).')
+  else add('deprecated-forms', 'pass', 'no deprecated auto_merge/autoqueue.')
+
+  // 2. Enqueue policy: hybrid (auto scoped to a passed review) is the default.
+  const amc = blockUnder(text, 'auto_merge_conditions')
+  if (amc == null) {
+    if (/auto_merge_conditions\s*:/.test(text)) add('enqueue-policy', 'abstain', 'auto_merge_conditions present but its block could not be read — check by hand.')
+    else add('enqueue-policy', 'note', 'no auto_merge_conditions → fully MANUAL enqueue. OK if deliberate (say so in a comment); the default is hybrid (SKILL.md §1).')
+  } else if (!/approved-reviews-by/.test(amc)) {
+    add('enqueue-policy', 'warn', 'auto_merge_conditions has no review arm (`approved-reviews-by`) — this is the retired indiscriminate form; scope auto-enqueue to a passed review (SKILL.md §1).')
+  } else if (!/changes-requested-reviews-by/.test(amc)) {
+    add('enqueue-policy', 'warn', 'auto_merge_conditions approves without also requiring `#changes-requested-reviews-by = 0` — an open change request could be out-voted; add it (SKILL.md §1).')
+  } else {
+    add('enqueue-policy', 'pass', 'hybrid: auto-enqueue scoped to a passed review.')
+  }
+
+  // 3. branch_protection_injection_mode: merge (only meaningful with a queue).
+  if (!/queue_rules\s*:/.test(text)) add('injection-mode', 'abstain', 'no queue_rules found — not a queue config?')
+  else if (/branch_protection_injection_mode\s*:\s*merge/.test(text)) add('injection-mode', 'pass', 'branch_protection_injection_mode: merge.')
+  else add('injection-mode', 'warn', 'branch_protection_injection_mode is not `merge` — a required Mergify check can then block queue ENTRY (SKILL.md).')
+
+  // 4. Gate defined once (anchor) and asserted in multiple places.
+  if (!/&gate\b/.test(text)) add('gate-anchor', 'abstain', 'no `&gate` anchor — cannot check the define-once/assert-thrice shape.')
+  else {
+    const refs = (text.match(/\*gate\b/g) || []).length
+    if (refs >= 2) add('gate-anchor', 'pass', `gate anchor referenced ${refs}× (define once, assert many).`)
+    else add('gate-anchor', 'warn', `gate anchor referenced only ${refs}× — assert it in queue_conditions AND merge_conditions (and the merge protection), not hand-copied.`)
+  }
+
+  // 5. `-draft` must NOT sit in queue_conditions/merge_conditions (epic-986 incident).
+  //    It belongs in auto_merge_conditions only.
+  for (const key of ['queue_conditions', 'merge_conditions']) {
+    const block = blockUnder(text, key)
+    if (block == null) continue
+    if (/(^|\s)-\s*-draft\b|(^|\s)-draft\b/.test(block)) {
+      add('draft-placement', 'warn', `\`-draft\` appears in ${key} — GitHub can't merge a draft anyway, and a queued draft strands the whole batch (epic-986). Keep -draft in auto_merge_conditions only (SKILL.md, \`-draft\` note).`)
+    }
+  }
+  if (!f.some((x) => x.check === 'draft-placement')) add('draft-placement', 'pass', '-draft not misplaced in queue/merge conditions.')
+
+  // 6. Batch mode is on per this skill's default. The standard is `batch_size: 3`,
+  //    written explicitly: unset, `batch_size` silently runs at Mergify's built-in
+  //    default of 1 (no batching), so the absence reads as a silent no-batch, not a
+  //    batched default. Dynamic {min, max} is batching too (SKILL.md Rule 3 / configuration.md §2-3).
+  const qr = blockUnder(text, 'queue_rules')
+  if (qr == null) {
+    add('batch-mode', 'abstain', 'no queue_rules found — nothing to batch.')
+  } else {
+    const inline = qr.match(/^\s*batch_size\s*:\s*(\S.*)$/m)?.[1]
+    const under = blockUnder(qr, 'batch_size')
+    const bs = inline ?? (under != null && under.trim() !== '' ? under : null)
+    if (bs == null) add('batch-mode', 'warn', 'no `batch_size` on the queue rule — it silently runs at Mergify\'s built-in 1, so batches NEVER form; set batch_size: 3 (this skill\'s default), or say deliberately why not (SKILL.md Rule 3).')
+    else if (/^\s*min\s*:/.test(bs)) add('batch-mode', 'pass', 'dynamic batch_size {min, max} — batching on.')
+    else if (/^\s*[2-9]\d*\s*$/.test(bs.trim())) add('batch-mode', 'pass', `batch_size ${bs.trim()} — batching on.`)
+    else add('batch-mode', 'warn', `batch_size: ${bs.trim()} — batches never form (must be > 1); raise it to 3 (this skill's default), or say deliberately why not (SKILL.md Rule 3).`)
+  }
+
+  return f
+}
+
+function verdict(findings) {
+  if (findings.some((x) => x.status === 'fail')) return 'FAIL'
+  if (findings.some((x) => x.status === 'warn')) return 'WARN'
+  return 'PASS'
+}
+
+export function runCli(argv) {
+  const flags = { file: '.mergify.yml', json: false, allowWarn: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--file') flags.file = argv[++i]
+    else if (a === '--json') flags.json = true
+    else if (a === '--allow-warn') flags.allowWarn = true
+  }
+  if (!fs.existsSync(flags.file)) {
+    console.error(`mergify-audit: no config at ${flags.file} (pass --file <path>).`)
+    return 2
+  }
+  const findings = auditText(fs.readFileSync(flags.file, 'utf8'))
+  const v = verdict(findings)
+  if (flags.json) {
+    console.log(JSON.stringify({ file: flags.file, verdict: v, findings }, null, 2))
+  } else {
+    const glyph = { pass: '✓', note: '·', abstain: '?', warn: '⚠', fail: '✗' }
+    for (const x of findings) console.log(`${glyph[x.status] || '?'} [${x.status}] ${x.check}: ${x.detail}`)
+    console.log(`\n${v} — ${flags.file}`)
+  }
+  if (v === 'FAIL') return 2
+  if (v === 'WARN') return flags.allowWarn ? 0 : 1
+  return 0
+}

package/skills/cicd-pipeline/mergify/scripts/audit.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from './audit-core.mjs'
+
+process.exitCode = runCli(process.argv.slice(2))