feat(pm): add --reconcile to ensure-pm-labels, aligning drifted label objects (#10193)

Claude-Session: https://claude.ai/code/session_019T1sSZbQTnLhrK9HhNdNiB

Co-authored-by: Claude <noreply@anthropic.com>

Author: Jack Q

scripts/pm/check-label-desc-cap.mjs

@@ -62,11 +62,22 @@
  * dry-run mode of its own, which is the other half of why nothing measured this
  * before.
  *
+ * ## Both ways a description reaches GitHub
+ *
+ * The vocabulary script has two modes: create-if-missing (default) and
+ * `--reconcile`, which additionally sends colour and description to
+ * `gh label edit`. `gh label edit` 422s over the cap exactly as `gh label create`
+ * does, so the gate's charter — no description this script sends can 422 —
+ * spans both. The self-test drives the script in BOTH modes and asserts that
+ * every edit carries the same string as its create, which is what keeps the
+ * single measured `-d` literal per label sufficient. Without those cases the
+ * gate would still pass while covering only half of what the script sends.
+ *
  * Missing file or empty read is RED, never a pass — a gate that cannot find its
  * input must fail, not skip.
  */
 
-import { execFileSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -210,38 +221,72 @@ function readTarget() {
 }
 
 /**
- * Run the real script with a fake `gh` on PATH and return every description it
- * was actually invoked with. The fake records one argument per line and closes
- * each invocation with a sentinel line; no argument in this file contains a
- * newline, and no control bytes are written.
+ * Run the real script with a fake `gh` on PATH and return every label call it
+ * actually made, plus the script's exit status. The fake records one argument
+ * per line and closes each invocation with a sentinel line; no argument in this
+ * file contains a newline, and no control bytes are written.
+ *
+ * `args` are passed through to the script — which is how the `--reconcile` mode
+ * is measured. `failEdit` makes the fake `gh` reject `label edit`, so the
+ * self-test can assert that a failed reconciliation is LOUD: unlike creation,
+ * whose `|| true` is mandatory for rerunnability, a swallowed edit failure would
+ * report success while leaving the drift live.
+ *
+ * The script is run via `spawnSync`, not `execFileSync`, because two of the
+ * behaviours under test are non-zero exits (an unknown flag, a failed edit) and
+ * a throwing runner cannot observe an exit status it converts into an exception.
  */
-export function dryRunDescriptions(scriptPath) {
+export function dryRunCalls(scriptPath, args = [], { failEdit = false } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'pm-label-cap-'));
   try {
     const log = join(dir, 'calls.log');
     const fake = join(dir, 'gh');
     writeFileSync(
       fake,
-      ['#!/usr/bin/env bash', 'for a in "$@"; do printf "%s\\n" "$a" >> "$FAKE_GH_LOG"; done', 'printf "<<<END>>>\\n" >> "$FAKE_GH_LOG"', 'exit 0', ''].join('\n'),
+      [
+        '#!/usr/bin/env bash',
+        'for a in "$@"; do printf "%s\\n" "$a" >> "$FAKE_GH_LOG"; done',
+        'printf "<<<END>>>\\n" >> "$FAKE_GH_LOG"',
+        'if [ -n "${FAKE_GH_FAIL_EDIT:-}" ] && [ "${2:-}" = "edit" ]; then echo "fake gh: refusing" >&2; exit 1; fi',
+        'exit 0',
+        '',
+      ].join('\n'),
     );
     chmodSync(fake, 0o755);
     writeFileSync(log, '');
-    execFileSync('bash', [scriptPath], {
-      env: { ...process.env, PATH: `${dir}:${process.env.PATH ?? ''}`, FAKE_GH_LOG: log },
-      stdio: 'ignore',
-    });
-    const out = [];
+    const env = { ...process.env, PATH: `${dir}:${process.env.PATH ?? ''}`, FAKE_GH_LOG: log };
+    if (failEdit) env.FAKE_GH_FAIL_EDIT = '1';
+    const proc = spawnSync('bash', [scriptPath, ...args], { env, stdio: 'ignore' });
+    const calls = [];
     for (const call of readFileSync(log, 'utf8').split('<<<END>>>\n')) {
-      const args = call.split('\n').filter((a) => a !== '');
-      const i = args.indexOf('-d');
-      if (args[0] === 'label' && args[1] === 'create' && i !== -1) out.push(args[i + 1]);
+      const argv = call.split('\n').filter((a) => a !== '');
+      if (argv[0] !== 'label') continue;
+      const flag = (...names) => {
+        const i = argv.findIndex((a) => names.includes(a));
+        return i === -1 ? null : argv[i + 1];
+      };
+      calls.push({
+        verb: argv[1],
+        name: argv[2],
+        repo: flag('-R', '--repo'),
+        color: flag('-c', '--color'),
+        description: flag('-d', '--description'),
+        argv,
+      });
     }
-    return out;
+    return { calls, status: proc.status };
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
 }
 
+/** Every description the script passes to `gh label create`. See dryRunCalls. */
+export function dryRunDescriptions(scriptPath) {
+  return dryRunCalls(scriptPath)
+    .calls.filter((c) => c.verb === 'create' && c.description !== null)
+    .map((c) => c.description);
+}
+
 function run() {
   const source = readTarget();
   const descriptions = parseDescriptions(source);
@@ -357,6 +402,74 @@ function selfTest() {
   // The floor: a parser that matches nothing must not read as clean.
   t('an empty parse is below the floor', parseDescriptions('echo hi').length < MIN_DESCRIPTIONS, true);
 
+  // ── The --reconcile mode ──────────────────────────────────────────────────
+  //
+  // This gate's charter is "no description the script sends to GitHub can 422".
+  // Reconcile adds a SECOND way to send one (`gh label edit`), so without the
+  // cases below the gate's coverage would silently shrink to the create path
+  // while still reading as a full pass — the parser-matches-nothing failure in
+  // a new place. The cases assert the two properties that keep the cap honest:
+  // every edit carries the same string as its create, and nothing else is sent.
+  const script = join(REPO_ROOT, TARGET);
+  // The verb is deliberately NOT part of the signature: these cases compare a
+  // create against its edit, and equality is the whole assertion.
+  const sig = (c) => JSON.stringify([c.name, c.repo, c.color, c.description]);
+  const verbs = (calls, v) => calls.filter((c) => c.verb === v);
+
+  const plain = dryRunCalls(script);
+  const reconciled = dryRunCalls(script, ['--reconcile']);
+
+  t('the default run issues no label edit at all', verbs(plain.calls, 'edit').length, 0);
+  t('…and exits 0', plain.status, 0);
+  t('reconcile exits 0 when every edit succeeds', reconciled.status, 0);
+  t(
+    'reconcile creates exactly what the default run creates',
+    verbs(reconciled.calls, 'create').map(sig),
+    verbs(plain.calls, 'create').map(sig),
+  );
+  t(
+    'reconcile edits exactly the labels it creates — same name, repo, colour and description',
+    verbs(reconciled.calls, 'edit').map(sig),
+    verbs(reconciled.calls, 'create').map(sig),
+  );
+  t(
+    'so every description reconcile SENDS is one this gate already measured',
+    verbs(reconciled.calls, 'edit').filter((c) => !real.some((r) => templateMatches(r.raw, c.description))),
+    [],
+  );
+  t(
+    '…and none of them would 422',
+    verbs(reconciled.calls, 'edit').filter((c) => charLength(c.description) > MAX_DESCRIPTION_CHARS),
+    [],
+  );
+  t(
+    'reconcile issues no verb other than create and edit — it never deletes',
+    [...new Set(reconciled.calls.map((c) => c.verb))].filter((v) => v !== 'create' && v !== 'edit'),
+    [],
+  );
+  t(
+    'reconcile never renames: no --name/-n reaches gh',
+    reconciled.calls.filter((c) => c.argv.includes('--name') || c.argv.includes('-n')).map((c) => c.name),
+    [],
+  );
+  t(
+    'reconcile is idempotent — a second run issues the identical call sequence',
+    dryRunCalls(script, ['--reconcile']).calls.map(sig),
+    reconciled.calls.map(sig),
+  );
+
+  // A mistyped flag must not fall through to a create-only run that prints the
+  // ordinary success line — the operator would read a reconciliation that never
+  // happened as done.
+  const mistyped = dryRunCalls(script, ['--reconsile']);
+  t('an unknown flag exits non-zero', mistyped.status, 2);
+  t('…and issues no gh calls at all', mistyped.calls.length, 0);
+
+  // The asymmetry with creation: a failed edit means the drift is still live.
+  const brokenEdit = dryRunCalls(script, ['--reconcile'], { failEdit: true });
+  t('a failing gh label edit makes the script exit non-zero', brokenEdit.status !== 0, true);
+  t('…while the same failure in the default mode cannot arise (no edits)', verbs(dryRunCalls(script, [], { failEdit: true }).calls, 'edit').length, 0);
+
   if (failed) {
     console.error(`\n❌ check-label-desc-cap --self-test: ${failed} case(s) failed`);
     process.exit(1);