@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/release_publication.ts

@@ -16,12 +16,20 @@
  * import path changes.
  */
 import { spawnSync } from 'node:child_process';
-import { DERIVED_MARKER, publication_blockers } from './_lib/release_highlights.js';
+import {
+    DERIVED_MARKER,
+    type MixObligation,
+    previous_release_tag,
+    publication_blockers,
+    section_publication_blockers,
+} from './_lib/release_highlights.js';
+import { loadTaxonomy, measureRange } from './measure_release_mix.js';
 import * as fs from 'node:fs';
 import process from 'node:process';
 
 import { gh_argv_label, gh_retry } from './_lib/gh_transient.js';
 import {
+    NEXT_SECTION_RE,
     extract_changelog_section,
     tag_message_from_section,
     pr_body_from_section,
@@ -37,6 +45,7 @@ import {
     SystemExitError,
     _cap_body,
     read_changelog_text,
+    reEscape,
 } from './release_env.js';
 
 function die(msg: string, code = 2): never {
@@ -422,6 +431,71 @@ export function _is_non_fast_forward(stderr: string, stdout: string): boolean {
     return /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text);
 }
 
+/**
+ * The pre-push local gate run, as an argv the caller hands to `run()`.
+ *
+ * Every release-PR assertion that can run locally, run BEFORE the branch leaves
+ * the machine. `guard_release_branch_push` below covers the changelog-section
+ * obligations; this covers the rest of `release-validation.yml` — PR shape,
+ * template pin — from `src/config/release-gate-locality.yml`, the registry
+ * `tests/scripts/release_gate_locality.test.ts` keeps in step with the
+ * workflow. `--cheap` drops the one row that leaves the machine, so a registry
+ * outage cannot read as a release defect.
+ *
+ * An argv rather than a call, so the pipeline issues it through `run()` and
+ * `release_drill` intercepts it exactly as it intercepts `task
+ * release-prepare`. A real subprocess inside the simulated world would run
+ * gates against the live tree.
+ *
+ * Lives here rather than in `release.ts` for the reason
+ * `_refuse_unpublishable` already states: that file is 2000+ lines and every
+ * line above 1500 is charged by the source-size growth ratchet.
+ */
+export function local_release_gate_argv(): string[] {
+    return ['task', 'release:verify', '--', '--cheap'];
+}
+
+/**
+ * Measure the governance-versus-product level for the span under release.
+ *
+ * The push guard's fourth site reads the SAME obligation the release PR reads,
+ * which until 2026-09-05 it did not: `publication_blockers` knew two sentinels
+ * and not this one, so the earliest refusal was the pull request. That gap was
+ * documented in `docs/contracts/CHANGELOG-conventions.md` and it is what turned
+ * 14.17.0 red after a branch, a PR and a CI run had already been spent.
+ *
+ * Returns `null` on any measurement failure — a shallow clone or a missing tag
+ * is an environment fact, and the contract is explicit that it degrades to a
+ * warning rather than to a refusal. `null` produces no blocker downstream.
+ */
+export function measure_mix_obligation(
+    version: string,
+    fromRef?: string | null,
+): MixObligation | null {
+    try {
+        const from = fromRef ?? previous_release_tag('HEAD', REPO_ROOT);
+        if (!from) return null;
+        const reading = measureRange(from, 'HEAD', loadTaxonomy(), version, REPO_ROOT);
+        const o = reading.response_obligation;
+        return {
+            triggered: o.triggered,
+            level:
+                `governance-only ${String(o.governance_only)} vs consumer-only ` +
+                `${String(o.consumer_only)} (taxonomy ${reading.taxonomy_version})`,
+        };
+    } catch (err) {
+        // The CI side prints `⚠️  governance mix not measured`; swallowing it
+        // here made a broken taxonomy file disable BOTH local guards in
+        // silence while CI kept refusing — the exact asymmetry this change
+        // exists to remove, restored one layer down.
+        process.stderr.write(
+            `⚠️   governance mix not measured for ${version}: ${(err as Error).message}\n` +
+                '    Both local guards are inert for this obligation; the release PR still refuses.\n',
+        );
+        return null;
+    }
+}
+
 /**
  * Refuse the FIRST remote state of a release whose section is not publishable.
  *
@@ -465,7 +539,12 @@ export function guard_release_branch_push(branch: string): void {
     if (!section) {
         return;
     }
-    const blockers = publication_blockers(section.body, version, `\`${branch}\``);
+    const blockers = section_publication_blockers(
+        section.body,
+        version,
+        `\`${branch}\``,
+        measure_mix_obligation(version),
+    );
     if (blockers.length === 0) {
         return;
     }
@@ -614,7 +693,28 @@ export function guard_release_curation(version: string, prMerged = false): void
     if (!section) {
         return;
     }
-    const blockers = publication_blockers(section.body, version, `\`release/${version}\``);
+    // The head-level blockers plus the mix obligation — deliberately NOT the
+    // tests footer.
+    //
+    // This site runs BEFORE `prepend_changelog`'s output is committed, and
+    // `--resume` skips the whole bump block once `package.json` already carries
+    // the target version. So a refusal here for a missing footer is a trap: the
+    // writer never gets a second chance to render it, the message forbids
+    // hand-writing it, and the operator is left rolling `package.json` back by
+    // hand. The footer is a MEASUREMENT the writer produces, not prose the
+    // operator can supply, which is exactly why it does not belong at the site
+    // that fires before the artefact exists in git.
+    //
+    // `guard_release_branch_push` carries it instead: by then the section is
+    // committed and editable on the branch, and nothing has left the machine.
+    const blockers = [
+        ...publication_blockers(
+            section.body,
+            version,
+            `\`release/${version}\``,
+            measure_mix_obligation(version),
+        ),
+    ];
     if (blockers.length === 0) {
         return;
     }
@@ -1017,3 +1117,143 @@ export function create_and_push_annotated_tag(version: string): void {
     run(['git', 'tag', '-a', version, '-m', tag_message_from_section(merged.body, version)]);
     _push_tag(version);
 }
+
+// Relocated from `release.ts` on 2026-09-05, for the reason
+// `_refuse_unpublishable` above already states: that file is 2000+ lines and
+// every line above 1500 is charged by the source-size growth ratchet. The move
+// is not incidental to this change — the `Tests: N` footer became a
+// section-level publication obligation in the same diff
+// (`section_publication_blockers`), so the writer that emits it and the guard
+// that refuses its absence now sit in one module. `release.ts` re-exports all
+// four names, so every existing importer is unaffected.
+
+const _TEST_COUNT_LINE_RE = /^Tests:\s+(\d+)/m;
+
+/**
+ * Buffer ceiling for the `vitest list` probe, in bytes.
+ *
+ * `spawnSync` buffers the child's whole stdout in memory and fails with
+ * ENOBUFS past `maxBuffer`, whose default is 1 MiB. The probe emits one line
+ * per test case, so its output grows with the suite: at 9470 cases the listing
+ * is ~1.25 MB, i.e. already past the default. That is what silently dropped
+ * the footer from the 9.10.0 notes and turned the `changelog-entry` gate red.
+ * 64 MiB is ~50× the current listing — headroom for a suite many times this
+ * size, at no cost when the output is small.
+ */
+export const _TEST_LIST_MAX_BUFFER = 64 * 1024 * 1024;
+
+/**
+ * Count test cases from a finished `vitest list` spawn result, or return null
+ * when the probe did not produce a usable listing.
+ *
+ * Split out from `_count_tests_current` so the failure modes are testable
+ * without spawning the real (~14s, >1 MB) collection. `warn` is injected for
+ * the same reason; it defaults to stderr.
+ */
+export function _count_from_list_result(
+    res: {
+        error?: (Error & { code?: string }) | undefined;
+        status: number | null;
+        stdout: string | null;
+    },
+    warn: (msg: string) => void = (msg) => void process.stderr.write(msg),
+): number | null {
+    // The trend line is informational and never blocks a release — but a
+    // SILENT drop is what shipped 9.8.0 and 9.10.0 without a footer, so every
+    // degradation says why. The `changelog-entry` CI gate treats a missing
+    // footer as fatal, so this warning is the difference between fixing the
+    // probe now and finding out from a red release PR.
+    if (res.error) {
+        // ENOENT (no npx) · ETIMEDOUT · ENOBUFS (listing past maxBuffer).
+        const code = res.error.code ?? res.error.message;
+        warn(
+            `⚠️  test-count probe failed (${code}) — the \`Tests:\` footer will ` +
+                `be omitted from the release notes, which fails the ` +
+                `\`CHANGELOG entry exists for head version\` gate.\n`,
+        );
+        return null;
+    }
+    if ((res.status ?? 1) !== 0) {
+        warn(
+            `⚠️  test-count probe exited ${res.status ?? '(null)'} — the ` +
+                `\`Tests:\` footer will be omitted from the release notes.\n`,
+        );
+        return null;
+    }
+    const lines = (res.stdout ?? '').split('\n').filter((l) => l.trim().length > 0);
+    if (lines.length === 0) {
+        warn('⚠️  test-count probe listed 0 cases — the `Tests:` footer will be omitted.\n');
+        return null;
+    }
+    return lines.length;
+}
+
+/**
+ * Return the collected vitest test-case count on the current tree
+ * (`npx vitest list`, one line per case; ~14s wall). Returns null when
+ * collection fails — the trend line is informational, never a release
+ * blocker, but every failure warns (see `_count_from_list_result`).
+ * (Replaced the dead `pytest --collect-only` probe on 2026-07-08,
+ * road-to-truth-and-reference-hygiene Phase 3: the Python suite was retired
+ * with ADR-200, so the old probe always degraded to null and the `Tests:`
+ * footer silently vanished from release notes.)
+ */
+export function _count_tests_current(): number | null {
+    // Recursion/cost guard: `npx vitest list` inside a vitest-driven release
+    // test would collect the whole suite from within the suite (the child
+    // inherits VITEST=… from the runner) — the exact recursion the caller
+    // comment warns about. Degrade to null there, same as any other
+    // collection failure.
+    if (process.env['VITEST'] !== undefined) {
+        return null;
+    }
+    const res = spawnSync('npx', ['vitest', 'list'], {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 180_000,
+        maxBuffer: _TEST_LIST_MAX_BUFFER,
+    });
+    return _count_from_list_result(res);
+}
+
+/**
+ * Read CHANGELOG.md and return the most recent `Tests: N` footer under the
+ * `prev_tag` heading, or null when not found.
+ */
+export function _previous_test_count_from_changelog(prev_tag: string | null): number | null {
+    if (!prev_tag || !fs.existsSync(CHANGELOG)) {
+        return null;
+    }
+    const text = fs.readFileSync(CHANGELOG, 'utf-8');
+    const heading_re = new RegExp(`^##\\s+\\[?${reEscape(prev_tag)}\\b`, 'm');
+    const m = heading_re.exec(text);
+    if (!m) {
+        return null;
+    }
+    const headEnd = m.index + m[0].length;
+    const rest = text.slice(headEnd);
+    const next_heading = NEXT_SECTION_RE.exec(rest);
+    const sectionEnd = headEnd + (next_heading ? next_heading.index : rest.length);
+    const section = text.slice(headEnd, sectionEnd);
+    const count_match = _TEST_COUNT_LINE_RE.exec(section);
+    return count_match ? Number.parseInt(count_match[1] as string, 10) : null;
+}
+
+/**
+ * Return the `Tests: N (+M since X.Y.Z)` footer line, or null when the current
+ * count cannot be determined. Silent on collection errors.
+ */
+export function _render_test_trend_line(prev_tag: string | null): string | null {
+    const current = _count_tests_current();
+    if (current === null) {
+        return null;
+    }
+    const previous = _previous_test_count_from_changelog(prev_tag);
+    if (previous === null || !prev_tag) {
+        return `Tests: ${current}`;
+    }
+    const delta = current - previous;
+    const sign = delta >= 0 ? '+' : '';
+    return `Tests: ${current} (${sign}${delta} since ${prev_tag})`;
+}

package/src/scripts/release_verify.ts

@@ -0,0 +1,220 @@
+#!/usr/bin/env tsx
+/**
+ * Run every release-PR assertion that CAN run locally, before anything is
+ * pushed.
+ *
+ * `release-validation.yml` is the last gate a release passes and the most
+ * expensive one to fail: it runs after `gh pr create`, so a branch, a pull
+ * request and a CI run are already spent by the time it speaks. Twice in three
+ * releases it refused something reproducible locally in under two seconds —
+ * 14.14.0 (PR #1812) on the curated head, 14.17.0 (PR #1856) on the
+ * governance-mix response. In both cases the check existed, was runnable, and
+ * nothing ran it.
+ *
+ * This is the command that runs it. It is DERIVED from
+ * `src/config/release-gate-locality.yml` rather than from a hand-kept list, so
+ * a new release-validation job cannot be added without either giving this
+ * runner a command or declaring, with a classified reason, that it has none —
+ * `tests/scripts/release_gate_locality.test.ts` enforces that half.
+ *
+ * Deliberately NOT a gate script: it runs commands rather than inspecting a
+ * corpus, so it has no `scanned:` count to report and no place in
+ * `gate-coverage.yml`. Same shape as `release_drill`, which is also a runner
+ * with a task and a test and no coverage row.
+ *
+ * Usage:
+ *     task release:verify                 # version from the branch, else package.json
+ *     task release:verify -- --version 14.17.0
+ *     task release:verify -- --list       # print the plan, run nothing
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const REGISTRY = path.join(REPO_ROOT, 'src', 'config', 'release-gate-locality.yml');
+
+interface Row {
+    local: string | null;
+    reason?: string;
+    verify: boolean;
+    network?: boolean;
+    partial?: string;
+    release_branch_only?: boolean;
+    script: string | null;
+    guard?: string | null;
+}
+
+/**
+ * Collapse rows that reproduce to the SAME command.
+ *
+ * Two jobs legitimately share one local reproduction — `changelog-entry` and
+ * `highlight-plausibility` are both answered by `check_release_highlights` —
+ * and running it twice would double the cost while reporting a coverage the
+ * second run did not add. The ids stay joined so the output still names every
+ * job the command answers for.
+ */
+function plan(rows: ReadonlyArray<readonly [string, Row]>, version: string): Array<[string, string]> {
+    const byCommand = new Map<string, string[]>();
+    for (const [id, r] of rows) {
+        const cmd = r.local!.replace('${VERSION}', version);
+        const label = r.partial ? `${id} (partial: ${r.partial})` : id;
+        byCommand.set(cmd, [...(byCommand.get(cmd) ?? []), label]);
+    }
+    return [...byCommand.entries()].map(([cmd, ids]) => [ids.join(' + '), cmd]);
+}
+
+/**
+ * The version under release.
+ *
+ * The branch name first, because that is what `release-validation.yml` itself
+ * reads (`head_ref`) — running the gates against a different version than CI
+ * will read would be a green run that proves nothing. `package.json` is the
+ * fallback for a maintainer probing before the branch exists.
+ */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+
+export function resolve_version(argv: readonly string[], cwd = REPO_ROOT): string | null {
+    const v = resolve_version_raw(argv, cwd);
+    // Every row's command is interpolated into `bash -c`, and two of the three
+    // sources here are strings git and npm hand back rather than values this
+    // file chose. `on_release_branch` already applies exactly this shape check;
+    // not applying it on the path that reaches a shell was the asymmetry.
+    return v !== null && SEMVER_RE.test(v) ? v : null;
+}
+
+function resolve_version_raw(argv: readonly string[], cwd = REPO_ROOT): string | null {
+    const i = argv.indexOf('--version');
+    if (i !== -1 && argv[i + 1]) return argv[i + 1]!;
+    const branch = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        cwd,
+        encoding: 'utf-8',
+    });
+    const name = (branch.stdout ?? '').trim();
+    if (name.startsWith('release/')) return name.slice('release/'.length);
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8')) as {
+            version?: string;
+        };
+        return pkg.version ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/** Whether HEAD is a `release/X.Y.Z` branch — decides the `release_branch_only` rows. */
+export function on_release_branch(cwd = REPO_ROOT): boolean {
+    const r = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, encoding: 'utf-8' });
+    return /^release\/\d+\.\d+\.\d+$/u.test((r.stdout ?? '').trim());
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const version = resolve_version(argv);
+    if (!version) {
+        process.stderr.write('release_verify: could not resolve a version to check.\n');
+        return 2;
+    }
+    const reg = parseYaml(fs.readFileSync(REGISTRY, 'utf-8')) as { jobs: Record<string, Row> };
+    const cheap = argv.includes('--cheap');
+    const releaseHead = on_release_branch();
+    // Every job lands in exactly one bucket, and the buckets are built from one
+    // pass so they cannot fail to partition. The first version filtered `rows`
+    // and then derived `uncovered` from a DIFFERENT predicate, so `audit-gate`
+    // under `--cheap` satisfied neither and vanished from the report: the run
+    // printed "3 pass" and "4 not covered" over eight jobs and read as a
+    // clearance for a job nobody ran. `--cheap` is the variant `task release`
+    // fires unattended, so that was the report nobody would be reading.
+    const runnable: Array<[string, Row]> = [];
+    const skipped: Array<[string, string]> = [];
+    for (const [id, r] of Object.entries(reg.jobs)) {
+        if (!r.verify || !r.local) {
+            skipped.push([id, r.reason ?? 'not part of the verify set']);
+        } else if (cheap && r.network) {
+            skipped.push([id, 'skipped by --cheap — leaves the machine']);
+        } else if (r.release_branch_only && !releaseHead) {
+            skipped.push([id, 'asserts a release-PR diff, and HEAD is not a release/X.Y.Z branch']);
+        } else {
+            runnable.push([id, r]);
+        }
+    }
+    if (runnable.length + skipped.length !== Object.keys(reg.jobs).length) {
+        process.stderr.write('release_verify: internal accounting error — jobs lost.\n');
+        return 2;
+    }
+    const rows = runnable;
+    const steps = plan(rows, version);
+
+    // Where the version came from, because off a release branch it falls back
+    // to `package.json` — which is the version already RELEASED, not the one
+    // being cut. A green run against it says nothing about the next release,
+    // and `task release:verify` with no arguments is exactly the pre-probe the
+    // task description invites.
+    const provenance = argv.includes('--version')
+        ? 'from --version'
+        : releaseHead
+          ? 'from the release branch'
+          : 'from package.json — NOT a release branch, so this is the version already released';
+    process.stdout.write(
+        `release_verify: ${version} (${provenance}) — ${String(steps.length)} local gate command(s)` +
+            `${cheap ? ' (cheap set — network rows skipped)' : ''}\n\n`,
+    );
+
+    if (argv.includes('--list')) {
+        for (const [id, cmd] of steps) {
+            process.stdout.write(`  ${id}\n    ${cmd}\n`);
+        }
+        for (const [id, why] of skipped) {
+            process.stdout.write(`  ${id} — not run\n    ${why}\n`);
+        }
+        return 0;
+    }
+
+    const failed: string[] = [];
+    for (const [id, cmd] of steps) {
+        process.stdout.write(`─── ${id}\n    ${cmd}\n`);
+        const res = spawnSync('bash', ['-c', cmd], { cwd: REPO_ROOT, stdio: 'inherit' });
+        if (res.status !== 0) {
+            failed.push(id);
+            process.stdout.write(`    ❌  ${id} (exit ${String(res.status ?? -1)})\n\n`);
+        } else {
+            process.stdout.write(`    ✅  ${id}\n\n`);
+        }
+    }
+
+    if (failed.length > 0) {
+        process.stderr.write(
+            `❌  ${String(failed.length)} release gate(s) would fail the release PR: ${failed.join(', ')}.\n` +
+                '    Nothing has left this machine yet. Fix them, then re-run.\n',
+        );
+        return 1;
+    }
+    // The runner names what it did NOT cover — a green run that silently
+    // omitted a job would read as a clearance it is not.
+    process.stdout.write(
+        `✅  ${String(rows.length)} of ${String(Object.keys(reg.jobs).length)} ` +
+            `release-validation job(s) pass for ${version} (${String(steps.length)} command(s)).\n` +
+            `    Not covered by this run (${String(skipped.length)}):\n` +
+            skipped.map(([id, why]) => `      ${id} — ${why}\n`).join('') +
+            '    See src/config/release-gate-locality.yml.\n',
+    );
+    return 0;
+}
+
+const _isMain = (() => {
+    const entry = process.argv[1];
+    if (!entry) return false;
+    try {
+        return fs.realpathSync(entry) === fs.realpathSync(_HERE);
+    } catch {
+        return false;
+    }
+})();
+
+if (_isMain) {
+    process.exit(main());
+}