Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): say why the bug lane refused, not just that it did (PRD-7862) (#3337)

Andrew Mikofalvyb996bd8eefe7
diff --git a/.github/scripts/bug-lane-refusal-payload.mjs b/.github/scripts/bug-lane-refusal-payload.mjs
new file mode 100644
index 000000000..4a061d714
--- /dev/null
+++ b/.github/scripts/bug-lane-refusal-payload.mjs
@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+/**
+ * The Slack page for a bug-lane refusal.
+ *
+ * WHY this is not a format string in the workflow. A refusal that names a SHA
+ * and a verdict tells a reader nothing they can act on, and `apply-conflict` in
+ * particular reads as "this fix is incompatible with the stable" when the far
+ * likelier cause is that an unrelated commit rewrote the same line of CI
+ * config since the stable was cut. That is the same distinction the point
+ * release runbook already draws for `pnpm-workspace.yaml` — config drift is
+ * not a dependency — and it was never surfaced for this lane, so every
+ * refusal read as the severe case. The reader has one question, "does this
+ * need a manual point release?", and answering it requires knowing WHICH
+ * paths collided and whether any of them carries behavior.
+ *
+ * This explains; it does not resolve. The lane keeps the unconditional hard
+ * fail — automated dispatches never set `resolve_paths`, and nothing here
+ * changes that. The classification decides what the message SAYS, never what
+ * the lane DOES.
+ *
+ * Classification is fail-closed. A path is inert only when it is positively
+ * proven to be both non-shipping and non-gating; anything unreadable,
+ * unparseable, or merely unrecognized is reported as behavior-carrying. A
+ * false "inert" would invite an operator to force through a fix that really
+ * does depend on something the stable lacks, so the failure direction is
+ * chosen deliberately: over-reporting severity costs a human a minute of
+ * reading, under-reporting it costs a bad release.
+ *
+ * Usage:
+ * node bug-lane-refusal-payload.mjs --input <json> [--repo owner/name]
+ *
+ * Emits the payload as JSON on stdout. Everything is assembled through
+ * JSON.stringify, so a commit subject containing quotes cannot corrupt the
+ * body.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+
+const DEFAULT_REPO = 'inkeep/open-knowledge';
+
+/**
+ * Leaf keys whose divergence cannot change what a release does.
+ *
+ * `scripts.test:e2e` is the Playwright CI subset: a single ~10 KB line listing
+ * every spec file the tier runs. Every commit that adds an e2e test appends to
+ * it, which is exactly what a well-formed bug fix does, so it is the highest
+ * churn line in the repo and collides with any sibling append that landed
+ * since the stable. It is `test:e2e` specifically and not `test:*`: turbo runs
+ * `test` as the lane's own verification tier, so a drifted `scripts.test`
+ * WOULD change the verdict, while `test:e2e` is a separate task that the lane
+ * never invokes.
+ *
+ * Entries are added only with both halves proven: the file does not reach a
+ * user (enforced separately, below, by requiring the package be private) and
+ * the key does not gate the verification the lane runs.
+ */
+export const INERT_JSON_KEYS = Object.freeze(new Set(['scripts.test:e2e']));
+
+/** Dotted leaf paths, so `scripts.test:e2e` is one key rather than a subtree. */
+function flattenJson(value, prefix = '', out = {}) {
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+ out[prefix] = JSON.stringify(value);
+ return out;
+ }
+ for (const [k, v] of Object.entries(value)) {
+ flattenJson(v, prefix ? `${prefix}.${k}` : k, out);
+ }
+ return out;
+}
+
+/** Leaf keys that differ between two parsed JSON documents, in sorted order. */
+export function changedJsonKeys(before, after) {
+ const a = flattenJson(before);
+ const b = flattenJson(after);
+ const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+ return [...keys].filter((k) => a[k] !== b[k]).sort();
+}
+
+/**
+ * Is this conflicted path provably inert, and why?
+ *
+ * The question asked is deliberately about the FIX's own edit, not about the
+ * conflict hunk: a textual conflict says two sides touched one line, while
+ * what an operator needs to know is whether the change the fix is trying to
+ * make carries behavior. So this reads what the fix changed relative to its
+ * own parent and judges that.
+ */
+export function classifyConflictPath({ path, before, after }) {
+ const unknown = (why) => ({ path, inert: false, detail: why });
+
+ if (!path.endsWith('package.json')) {
+ return unknown('carries behavior (or cannot be proven not to)');
+ }
+ let parsedBefore;
+ let parsedAfter;
+ try {
+ parsedBefore = JSON.parse(before);
+ parsedAfter = JSON.parse(after);
+ } catch {
+ return unknown('unreadable at one of the two revisions');
+ }
+ // The non-shipping half. A published package's manifest reaches users
+ // whatever key moved, so it is never eligible regardless of the key.
+ if (parsedAfter.private !== true) {
+ return unknown('a published package manifest');
+ }
+ const keys = changedJsonKeys(parsedBefore, parsedAfter);
+ // No line-level change means the conflict did not come from the fix, so
+ // there is nothing here to judge as harmless.
+ if (keys.length === 0) {
+ return unknown('conflicted without the fix changing it');
+ }
+ const offenders = keys.filter((k) => !INERT_JSON_KEYS.has(k));
+ if (offenders.length > 0) {
+ return unknown(`changes ${offenders.join(', ')}`);
+ }
+ return {
+ path,
+ inert: true,
+ detail: `${keys.join(', ')} only — private package, not in turbo \`test\`. Does not ship, does not gate.`,
+ };
+}
+
+/** The real git boundary; injected as a fake in tests. */
+export function makeGitShow(cwd = process.cwd()) {
+ return (rev, path) => {
+ try {
+ return execFileSync('git', ['show', `${rev}:${path}`], {
+ cwd,
+ encoding: 'utf8',
+ env: gitCleanEnv(),
+ maxBuffer: 64 * 1024 * 1024,
+ });
+ } catch {
+ return null;
+ }
+ };
+}
+
+/**
+ * Classify every conflicted path of every dropped ref.
+ *
+ * A ref is only as resolvable as its worst path, so `inert` on the ref is the
+ * conjunction: one behavior-carrying collision means the whole pick is the
+ * severe case no matter how many harmless ones sit beside it.
+ */
+export function classifyRefs(refs, gitShow) {
+ return refs.map((entry) => {
+ const files = (entry.conflicts ?? []).map((path) => {
+ const before = gitShow(`${entry.ref}^`, path);
+ const after = gitShow(entry.ref, path);
+ if (before === null || after === null) {
+ return { path, inert: false, detail: 'unreadable at one of the two revisions' };
+ }
+ return classifyConflictPath({ path, before, after });
+ });
+ return {
+ ...entry,
+ files,
+ inert: files.length > 0 && files.every((f) => f.inert),
+ };
+ });
+}
+
+/**
+ * The headline has one job: let a reader scanning the channel tell a fix that
+ * genuinely cannot ship from one that is only blocked by churn, without
+ * opening the run.
+ */
+export function describeRefusal({ verdict, refs }) {
+ if (verdict === 'fail') {
+ return {
+ headline: 'Bug lane: verification failed on the synthetic tree',
+ meaning:
+ 'The fast tiers went red on BOTH attempts, or the install failed. Past flake-class: treat it as a real conflict with the stable.',
+ };
+ }
+ if (refs.length > 0 && refs.every((r) => r.inert)) {
+ return {
+ headline: 'Bug lane: point release blocked by config drift, not by the fix',
+ meaning:
+ 'Every collision is in a path that neither ships nor gates verification. The fix itself applies cleanly to the stable.',
+ };
+ }
+ return {
+ headline: 'Bug lane: the fix does not apply to the current stable',
+ meaning:
+ 'At least one collision is in a path that carries behavior, so the fix depends on something that landed after the stable was cut.',
+ };
+}
+
+/**
+ * What an operator can actually do. Deliberately does not offer
+ * `resolve_paths` for the inert case: its allowlist is code and covers only
+ * `pnpm-workspace.yaml`, so naming a package manifest refuses with
+ * `resolve-path-not-allowlisted` before the tree is touched. Sending someone
+ * to a door that is locked is worse than saying it is locked.
+ */
+export function optionsFor({ verdict, refs }) {
+ if (verdict === 'fail') {
+ return [
+ 'Read the failing tier in the run log before anything else — a red synthetic tree is a real incompatibility, not a retry candidate.',
+ 'The fixes ride their cycle’s stable. Forcing them past a red verification is not an option this lane offers.',
+ ];
+ }
+ const allInert = refs.length > 0 && refs.every((r) => r.inert);
+ if (allInert) {
+ return [
+ 'Do nothing — the fix ships with its cycle’s stable on the ordinary soak. Since the collision carries no behavior, waiting costs only time.',
+ 'If the fix is urgent enough to hand-cut: it IS self-contained over the stable, so the usual "pick a smaller commit" advice does not apply. `resolve_paths` does not cover this path (allowlist is code, `pnpm-workspace.yaml` only), so it needs a human decision — see RELEASES.md, "When the conflict is config drift, not a dependency".',
+ ];
+ }
+ return [
+ 'Let it ride its cycle’s stable. A behavior-carrying collision means the fix genuinely depends on later work.',
+ 'If it must ship sooner, the answer is a smaller self-contained commit, not a forced pick — see RELEASES.md, "When a guard refuses".',
+ ];
+}
+
+const MAX_REFS_SHOWN = 5;
+const MAX_FILES_SHOWN = 8;
+
+function refLines(refs) {
+ const lines = [];
+ for (const entry of refs.slice(0, MAX_REFS_SHOWN)) {
+ const tickets = (entry.tickets ?? []).join(', ');
+ const label = [`\`${entry.ref.slice(0, 9)}\``, tickets && `(${tickets})`].filter(Boolean).join(' ');
+ const shown = entry.files.slice(0, MAX_FILES_SHOWN);
+ lines.push(
+ `${label} — conflicted in ${entry.files.length} file${entry.files.length === 1 ? '' : 's'}:`,
+ );
+ for (const f of shown) {
+ lines.push(` • \`${f.path}\` — ${f.inert ? 'INERT' : 'CARRIES BEHAVIOR'} (${f.detail})`);
+ }
+ if (entry.files.length > shown.length) {
+ lines.push(` • …and ${entry.files.length - shown.length} more`);
+ }
+ // The reassurance that makes an inert verdict legible: naming what DID
+ // apply is what separates "one line drifted" from "this fix is broken".
+ const clean = Number(entry.totalFiles) - entry.files.length;
+ if (Number.isFinite(clean) && clean > 0) {
+ lines.push(` ${clean} other file${clean === 1 ? '' : 's'} in the commit applied cleanly.`);
+ }
+ }
+ if (refs.length > MAX_REFS_SHOWN) {
+ lines.push(`…and ${refs.length - MAX_REFS_SHOWN} more ref(s); see the run.`);
+ }
+ return lines;
+}
+
+export function buildSlackPayload({ verdict, stable, refs, runUrl, repo = DEFAULT_REPO }) {
+ const { headline, meaning } = describeRefusal({ verdict, refs });
+ const summary = `⛔ ${headline}`;
+ const body = [
+ `*Over \`${stable}\` on \`${repo}\`.* ${meaning}`,
+ '',
+ '*Why it refused*',
+ ...refLines(refs),
+ '',
+ '*What you can do*',
+ ...optionsFor({ verdict, refs }).map((o, i) => `${i + 1}. ${o}`),
+ '',
+ // Only the run link is conditional; the blank separators above are
+ // deliberate and must survive.
+ ...(runUrl ? [`<${runUrl}|Run log>`] : []),
+ '_Further identical refusals stay silent; the lane pages again only if the refusal changes._',
+ ].join('\n');
+
+ return {
+ // `text` is the notification / a11y fallback Slack recommends alongside blocks.
+ text: summary,
+ blocks: [
+ { type: 'header', text: { type: 'plain_text', text: summary, emoji: true } },
+ { type: 'section', text: { type: 'mrkdwn', text: body } },
+ ],
+ };
+}
+
+export function parseArgs(argv) {
+ const args = {};
+ const rest = argv.slice(2);
+ for (let i = 0; i < rest.length; i += 1) {
+ const key = rest[i];
+ if (!key.startsWith('--')) continue;
+ args[key.slice(2)] = rest[i + 1] ?? '';
+ i += 1;
+ }
+ if (!args.input) throw new Error('--input is required');
+ const parsed = JSON.parse(args.input);
+ return {
+ verdict: parsed.verdict || 'conflict',
+ stable: parsed.stable || '(unknown stable)',
+ refs: Array.isArray(parsed.refs) ? parsed.refs : [],
+ runUrl: parsed.runUrl || '',
+ repo: args.repo || parsed.repo || DEFAULT_REPO,
+ };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ try {
+ const parsed = parseArgs(process.argv);
+ const refs = classifyRefs(parsed.refs, makeGitShow());
+ process.stdout.write(JSON.stringify(buildSlackPayload({ ...parsed, refs })));
+ } catch (err) {
+ process.stderr.write(`${err.message}\n`);
+ process.exit(1);
+ }
+}
diff --git a/.github/scripts/bug-lane-refusal-payload.test.mjs b/.github/scripts/bug-lane-refusal-payload.test.mjs
new file mode 100644
index 000000000..967c93d55
--- /dev/null
+++ b/.github/scripts/bug-lane-refusal-payload.test.mjs
@@ -0,0 +1,330 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+import {
+ buildSlackPayload,
+ changedJsonKeys,
+ classifyConflictPath,
+ classifyRefs,
+ describeRefusal,
+ INERT_JSON_KEYS,
+ optionsFor,
+ parseArgs,
+} from './bug-lane-refusal-payload.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const bugLane = readFileSync(join(REPO_ROOT, '.github', 'workflows', 'bug-lane.yml'), 'utf8');
+
+/** A private manifest whose only fix-side change is the Playwright subset. */
+const appManifest = (e2e) =>
+ JSON.stringify({
+ name: '@inkeep/open-knowledge-app',
+ private: true,
+ scripts: { test: 'vitest run', 'test:e2e': `playwright test ${e2e}` },
+ });
+
+describe('changedJsonKeys', () => {
+ test('reports dotted leaf paths, not subtrees', () => {
+ expect(changedJsonKeys({ scripts: { a: '1', b: '2' } }, { scripts: { a: '1', b: '3' } })).toEqual(
+ ['scripts.b'],
+ );
+ });
+
+ test('catches added and removed leaves, not just modified ones', () => {
+ expect(changedJsonKeys({ a: 1 }, { a: 1, b: 2 })).toEqual(['b']);
+ expect(changedJsonKeys({ a: 1, b: 2 }, { a: 1 })).toEqual(['b']);
+ });
+
+ test('does not confuse a stringified value with a structural change', () => {
+ expect(changedJsonKeys({ a: '1' }, { a: 1 })).toEqual(['a']);
+ });
+});
+
+describe('classifyConflictPath', () => {
+ // The incident this exists for: a bug fix appended one Playwright spec to
+ // the CI subset, an unrelated feature had appended six since the stable, and
+ // the whole point release was refused over a line that does not ship.
+ test('the e2e-subset append is inert', () => {
+ const got = classifyConflictPath({
+ path: 'packages/app/package.json',
+ before: appManifest('a.e2e.ts b.e2e.ts'),
+ after: appManifest('a.e2e.ts b.e2e.ts preview-tab-promotion.e2e.ts'),
+ });
+ expect(got.inert).toBe(true);
+ expect(got.detail).toContain('scripts.test:e2e');
+ expect(got.detail).toMatch(/does not ship/i);
+ });
+
+ test('a published manifest is never inert, whatever key moved', () => {
+ const pub = (e2e) =>
+ JSON.stringify({ name: '@inkeep/open-knowledge', scripts: { 'test:e2e': e2e } });
+ const got = classifyConflictPath({ path: 'packages/cli/package.json', before: pub('a'), after: pub('b') });
+ expect(got.inert).toBe(false);
+ expect(got.detail).toMatch(/published/);
+ });
+
+ test('a sibling key riding along disqualifies the whole path', () => {
+ const before = appManifest('a.e2e.ts');
+ const after = JSON.stringify({
+ name: '@inkeep/open-knowledge-app',
+ private: true,
+ scripts: { test: 'vitest run', 'test:e2e': 'playwright test a.e2e.ts b.e2e.ts' },
+ dependencies: { react: '19.2.0' },
+ });
+ const got = classifyConflictPath({ path: 'packages/app/package.json', before, after });
+ expect(got.inert).toBe(false);
+ expect(got.detail).toContain('dependencies.react');
+ });
+
+ // `scripts.test` IS the tier the lane runs to verify the synthetic tree, so
+ // treating it like its `test:e2e` sibling would let a drifted verification
+ // command be reported as harmless.
+ test('scripts.test is not inert even though test:e2e is', () => {
+ expect(INERT_JSON_KEYS.has('scripts.test')).toBe(false);
+ const after = JSON.stringify({
+ name: '@inkeep/open-knowledge-app',
+ private: true,
+ scripts: { test: 'vitest run --changed', 'test:e2e': 'playwright test a.e2e.ts' },
+ });
+ const got = classifyConflictPath({
+ path: 'packages/app/package.json',
+ before: appManifest('a.e2e.ts'),
+ after,
+ });
+ expect(got.inert).toBe(false);
+ expect(got.detail).toContain('scripts.test');
+ });
+
+ test.each([
+ ['a source file', 'packages/app/src/components/FileTree.tsx', 'x', 'y'],
+ ['a lockfile', 'pnpm-lock.yaml', 'a', 'b'],
+ ['a workflow', '.github/workflows/release.yml', 'a', 'b'],
+ ])('fails closed on %s', (_label, path, before, after) => {
+ expect(classifyConflictPath({ path, before, after }).inert).toBe(false);
+ });
+
+ test('fails closed on unparseable JSON rather than assuming', () => {
+ const got = classifyConflictPath({
+ path: 'packages/app/package.json',
+ before: '{not json',
+ after: appManifest('a.e2e.ts'),
+ });
+ expect(got.inert).toBe(false);
+ expect(got.detail).toMatch(/unreadable/);
+ });
+
+ test('a path the fix never changed is not called harmless', () => {
+ const same = appManifest('a.e2e.ts');
+ const got = classifyConflictPath({ path: 'packages/app/package.json', before: same, after: same });
+ expect(got.inert).toBe(false);
+ expect(got.detail).toMatch(/without the fix changing it/);
+ });
+});
+
+describe('classifyRefs', () => {
+ const gitShow = (blobs) => (rev, path) => blobs[`${rev}:${path}`] ?? null;
+
+ test('a ref is inert only when every one of its paths is', () => {
+ const blobs = {
+ 'abc^:packages/app/package.json': appManifest('a.e2e.ts'),
+ 'abc:packages/app/package.json': appManifest('a.e2e.ts b.e2e.ts'),
+ 'abc^:packages/app/src/x.ts': 'a',
+ 'abc:packages/app/src/x.ts': 'b',
+ };
+ const [onlyConfig] = classifyRefs(
+ [{ ref: 'abc', conflicts: ['packages/app/package.json'] }],
+ gitShow(blobs),
+ );
+ expect(onlyConfig.inert).toBe(true);
+
+ const [withSource] = classifyRefs(
+ [{ ref: 'abc', conflicts: ['packages/app/package.json', 'packages/app/src/x.ts'] }],
+ gitShow(blobs),
+ );
+ expect(withSource.inert).toBe(false);
+ });
+
+ test('an unreadable blob fails closed instead of throwing', () => {
+ const [entry] = classifyRefs([{ ref: 'abc', conflicts: ['gone.json'] }], gitShow({}));
+ expect(entry.inert).toBe(false);
+ expect(entry.files[0].detail).toMatch(/unreadable/);
+ });
+
+ test('a ref with no recorded conflicts is not vacuously inert', () => {
+ expect(classifyRefs([{ ref: 'abc', conflicts: [] }], gitShow({}))[0].inert).toBe(false);
+ });
+});
+
+describe('describeRefusal', () => {
+ const inert = [{ ref: 'a', inert: true, files: [] }];
+ const behavioral = [{ ref: 'a', inert: false, files: [] }];
+
+ test('the three refusal classes read differently at a glance', () => {
+ const h = (args) => describeRefusal(args).headline;
+ const drift = h({ verdict: 'conflict', refs: inert });
+ const real = h({ verdict: 'conflict', refs: behavioral });
+ const red = h({ verdict: 'fail', refs: [] });
+ expect(new Set([drift, real, red]).size).toBe(3);
+ expect(drift).toMatch(/config drift, not by the fix/);
+ expect(real).toMatch(/does not apply/);
+ });
+
+ test('one behavior-carrying ref in a mixed batch picks the severe headline', () => {
+ expect(describeRefusal({ verdict: 'conflict', refs: [...inert, ...behavioral] }).headline).toMatch(
+ /does not apply/,
+ );
+ });
+});
+
+describe('optionsFor', () => {
+ test('the inert case never points at resolve_paths, which would refuse', () => {
+ const opts = optionsFor({ verdict: 'conflict', refs: [{ ref: 'a', inert: true, files: [] }] });
+ expect(opts.join('\n')).not.toMatch(/-f resolve_paths=/);
+ expect(opts.join('\n')).toMatch(/allowlist is code/);
+ });
+
+ test('inert and behavioral give different advice', () => {
+ const a = optionsFor({ verdict: 'conflict', refs: [{ ref: 'x', inert: true, files: [] }] });
+ const b = optionsFor({ verdict: 'conflict', refs: [{ ref: 'x', inert: false, files: [] }] });
+ expect(a).not.toEqual(b);
+ expect(b.join('\n')).toMatch(/smaller self-contained commit/);
+ });
+});
+
+describe('buildSlackPayload', () => {
+ const refs = [
+ {
+ ref: '103e961036fc053824b98f1e44a4616d6d4d9d87',
+ tickets: ['PRD-7835'],
+ totalFiles: 28,
+ inert: true,
+ files: [{ path: 'packages/app/package.json', inert: true, detail: 'scripts.test:e2e only' }],
+ },
+ ];
+
+ test('names the ticket, the path, the verdict and what applied cleanly', () => {
+ const body = buildSlackPayload({
+ verdict: 'conflict',
+ stable: 'v0.48.9',
+ refs,
+ runUrl: 'https://example.test/run/1',
+ }).blocks[1].text.text;
+ expect(body).toContain('PRD-7835');
+ expect(body).toContain('packages/app/package.json');
+ expect(body).toContain('v0.48.9');
+ expect(body).toContain('27 other files in the commit applied cleanly');
+ });
+
+ test('keeps the silence-is-deliberate note', () => {
+ const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs, runUrl: '' }).blocks[1]
+ .text.text;
+ expect(body).toMatch(/Further identical refusals stay silent/);
+ });
+
+ test('a commit subject containing quotes cannot corrupt the payload', () => {
+ const hostile = [
+ { ...refs[0], tickets: ['"}, {"type":"section","text":"pwned'], files: refs[0].files },
+ ];
+ const payload = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs: hostile, runUrl: '' });
+ expect(JSON.parse(JSON.stringify(payload)).blocks).toHaveLength(2);
+ });
+
+ test('caps a large batch instead of blowing Slack’s block limit', () => {
+ const many = Array.from({ length: 12 }, (_, i) => ({
+ ref: `${i}`.repeat(12),
+ tickets: [],
+ totalFiles: 2,
+ inert: false,
+ files: Array.from({ length: 20 }, (_, j) => ({
+ path: `p${j}.ts`,
+ inert: false,
+ detail: 'carries behavior',
+ })),
+ }));
+ const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs: many, runUrl: '' })
+ .blocks[1].text.text;
+ expect(body).toMatch(/and 7 more ref\(s\)/);
+ expect(body).toMatch(/and 12 more/);
+ expect(body.length).toBeLessThan(3000);
+ });
+});
+
+describe('parseArgs', () => {
+ test('requires --input', () => {
+ expect(() => parseArgs(['node', 'x'])).toThrow(/--input is required/);
+ });
+
+ test('defaults a missing refs array rather than throwing', () => {
+ expect(parseArgs(['node', 'x', '--input', '{"verdict":"fail"}']).refs).toEqual([]);
+ });
+});
+
+describe('workflow wiring', () => {
+ /** Exact bounds of a step: its `- name:` up to the next sibling step. */
+ const step = (name) => {
+ const rest = bugLane.slice(bugLane.indexOf(`- name: ${name}`));
+ const end = rest.indexOf('\n - name: ');
+ return end === -1 ? rest : rest.slice(0, end);
+ };
+
+ /**
+ * The step's executable shell, with whole-line comments removed. Assertions
+ * about what the shell DOES must not be satisfiable — or broken — by prose
+ * that quotes the very form it warns against.
+ */
+ const shellOf = (name) =>
+ step(name)
+ .split('\n')
+ .filter((l) => !/^\s*#/.test(l))
+ .join('\n');
+
+ test('the verify step records conflicted paths before aborting the pick', () => {
+ const verify = step('Verify the synthetic tree');
+ const conflictCapture = verify.indexOf('--diff-filter=U');
+ const abort = verify.indexOf('cherry-pick --abort');
+ expect(conflictCapture).toBeGreaterThan(-1);
+ // An abort clears the index, so capturing after it yields an empty list and
+ // the page silently loses the only datum that makes it actionable.
+ expect(conflictCapture).toBeLessThan(abort);
+ });
+
+ test('the refusal page builds its body through this script', () => {
+ expect(step('Page on a refusal')).toContain('bug-lane-refusal-payload.mjs');
+ });
+
+ // `${V:-{\}}` expands to a LITERAL `{\}` — a brace in a parameter-expansion
+ // default is not escapable there. jq --argjson then refuses, and the enriched
+ // page degrades to the plain fallback on every single run, with nothing in
+ // the log saying the enrichment never happened.
+ test('the page does not default a JSON var with a brace expansion', () => {
+ expect(shellOf('Page on a refusal')).not.toMatch(/\$\{[A-Za-z_]+:-\{/);
+ });
+
+ // Steps share one workspace, and verify leaves it detached at the stable tag
+ // — which predates this script, so it is simply not on disk by the time the
+ // page runs. Without a restore the page degrades to the fallback forever,
+ // and nothing in the log says the enrichment never happened.
+ test('the page restores the lane scripts the detached tree dropped', () => {
+ const shell = shellOf('Page on a refusal');
+ const restore = shell.indexOf('git checkout "$GITHUB_SHA"');
+ const invoke = shell.indexOf('bug-lane-refusal-payload.mjs');
+ expect(restore).toBeGreaterThan(-1);
+ expect(restore).toBeLessThan(invoke);
+ });
+
+ // `git checkout <ref> -- a b` is atomic: one path missing at that ref aborts
+ // the whole restore, so combining them would let an unrelated rename leave
+ // the page silently degraded. Asserted as the shape it must have — one
+ // single-token pathspec, driven by a loop — rather than by trying to exclude
+ // every way two could be written.
+ test('the restore names one path at a time', () => {
+ expect(shellOf('Page on a refusal')).toMatch(
+ /for p in [^\n]*\n\s*git checkout "\$GITHUB_SHA" -- "\$p"/,
+ );
+ });
+
+ test('the lane still never authorizes conflict resolution when dispatching', () => {
+ expect(bugLane).not.toContain('resolve_paths');
+ });
+});
diff --git a/.github/scripts/bug-lane.mjs b/.github/scripts/bug-lane.mjs
index 169c92351..945f07001 100644
--- a/.github/scripts/bug-lane.mjs
+++ b/.github/scripts/bug-lane.mjs
@@ -179,6 +179,19 @@ export async function evaluateBugLane({
};
}
+/**
+ * Qualifying sha -> the Bug tickets that qualified it. Only qualifying commits
+ * are included: a rejected commit's links describe why it was NOT picked, and
+ * surfacing them downstream would invite a reader to think it shipped.
+ */
+export function ticketsByRef(result) {
+ const out = {};
+ for (const c of result.perCommit) {
+ if (c.qualifies && c.linkedIssues.length > 0) out[c.sha] = [...c.linkedIssues];
+ }
+ return out;
+}
+
// --- workflow-runtime wiring (real git boundary) ---
function runGit(args) {
@@ -271,7 +284,15 @@ async function main() {
if (process.env.GITHUB_OUTPUT) {
appendFileSync(
process.env.GITHUB_OUTPUT,
- [`fix_refs=${result.fixRefs.join(',')}`, `stable=${stable}`, ''].join('\n'),
+ [
+ `fix_refs=${result.fixRefs.join(',')}`,
+ `stable=${stable}`,
+ // sha -> the Bug tickets that qualified it, so a refusal page can name
+ // the bug a reader recognises instead of only a SHA. One line: the map
+ // is bounded by the qualifying set, which is single digits.
+ `fix_tickets=${JSON.stringify(ticketsByRef(result))}`,
+ '',
+ ].join('\n'),
);
}
}
diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjs
index a2f31b065..321ee0b9a 100644
--- a/.github/scripts/release-cascade-shape.test.mjs
+++ b/.github/scripts/release-cascade-shape.test.mjs
@@ -554,7 +554,14 @@ describe('the bug lane verifies the synthetic tree at the same bar as main', ()
bugLane.indexOf('- name: Page on a refusal'),
bugLane.indexOf('- name: Record that this refusal was paged'),
);
- expect(page).toContain('Further identical refusals stay silent');
+ // The sentence lives in the payload builder the step shells out to, so the
+ // contract is "the step composes a body that carries it" rather than "the
+ // YAML contains the literal". Assert both halves: the step reaches the
+ // builder, and the builder still emits the sentence.
+ expect(page).toContain('bug-lane-refusal-payload.mjs');
+ expect(
+ readFileSync(join(WORKFLOWS, '..', 'scripts', 'bug-lane-refusal-payload.mjs'), 'utf8'),
+ ).toContain('Further identical refusals stay silent');
});
test('a suppressed refusal still leaves a trace in the run', () => {
diff --git a/.github/workflows/bug-lane.yml b/.github/workflows/bug-lane.yml
index 079981456..39bea9b49 100644
--- a/.github/workflows/bug-lane.yml
+++ b/.github/workflows/bug-lane.yml
@@ -141,15 +141,42 @@ jobs:
IFS=',' read -ra REFS <<< "$FIX_REFS"
SURVIVORS=()
DROPPED=()
+ # Which paths collided, per dropped ref, as JSON for the refusal page.
+ # "conflict" alone cannot distinguish a fix that genuinely depends on
+ # later work from one blocked by an unrelated rewrite of a line of CI
+ # config, and that is the whole question a reader has.
+ CONFLICT_JSON='[]'
for ref in "${REFS[@]}"; do
if git cherry-pick "$ref"; then
SURVIVORS+=("$ref")
else
+ # BEFORE the abort: --abort clears the index, and with it the
+ # unmerged-path list this reads. Capturing after yields nothing.
+ # A plain read loop rather than `mapfile` so the shell does not
+ # depend on a bash 4 builtin.
+ CONFLICTED=()
+ while IFS= read -r f; do
+ [[ -n "$f" ]] && CONFLICTED+=("$f")
+ done < <(git diff --name-only --diff-filter=U || true)
+ TOTAL_FILES=$(git show --pretty=format: --name-only "$ref" | grep -c . || true)
+ # `${a[@]+"${a[@]}"}` so an empty array is not an unbound-variable
+ # error under `set -u`: a pick can fail without conflicting (an
+ # empty commit), and that must still mint a report.
+ CONFLICT_JSON=$(jq -c \
+ --arg ref "$ref" \
+ --argjson total "${TOTAL_FILES:-0}" \
+ --args '. + [{ref: $ref, totalFiles: $total, conflicts: $ARGS.positional}]' \
+ <<< "$CONFLICT_JSON" ${CONFLICTED[@]+"${CONFLICTED[@]}"})
git cherry-pick --abort || true
DROPPED+=("$ref")
- echo "::notice::bug-lane: ${ref} does not apply cleanly onto ${STABLE}; dropped from this batch — it will ship with its cycle's stable instead."
+ echo "::notice::bug-lane: ${ref} does not apply cleanly onto ${STABLE} (conflicted in: ${CONFLICTED[*]:-none}); dropped from this batch — it will ship with its cycle's stable instead."
fi
done
+ {
+ echo "conflicts<<CONFLICTS_EOF"
+ echo "$CONFLICT_JSON"
+ echo "CONFLICTS_EOF"
+ } >> "$GITHUB_OUTPUT"
if [[ ${#DROPPED[@]} -gt 0 ]]; then
echo "dropped_refs=$(IFS=','; echo "${DROPPED[*]}")" >> "$GITHUB_OUTPUT"
fi
@@ -337,8 +364,11 @@ jobs:
SLACK_RELEASES_WEBHOOK_URL: ${{ secrets.SLACK_RELEASES_WEBHOOK_URL }}
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
FIX_REFS: ${{ steps.evaluate.outputs.fix_refs }}
+ FIX_TICKETS: ${{ steps.evaluate.outputs.fix_tickets }}
SURVIVING_REFS: ${{ steps.verify.outputs.surviving_refs }}
DROPPED_REFS: ${{ steps.verify.outputs.dropped_refs }}
+ CONFLICTS: ${{ steps.verify.outputs.conflicts }}
+ STABLE: ${{ steps.evaluate.outputs.stable }}
VERDICT: ${{ steps.verify.outputs.verdict }}
run: |
set -uo pipefail
@@ -353,23 +383,45 @@ jobs:
echo "::notice::No Slack webhook secret set — refusal page skipped."
else
RUN_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
- # Name only the refs each verdict is actually about: on conflict the
- # whole qualifying set conflicted; on fail only the survivors reached
- # the verification stage.
- if [[ "$VERDICT" == "conflict" ]]; then
- TEXT="⛔ Bug lane: no qualifying fix is self-contained over the stable — all of ${FIX_REFS} conflict. They ride their cycle's 24h path; investigate whether any needs a manual point release. ${RUN_URL}"
- else
- TEXT="⛔ Bug lane: verification failed on the synthetic tree for ${SURVIVING_REFS} — the fast tiers went red on BOTH attempts, or the install failed. Either way this is past flake-class: treat it as a real conflict with the stable, not a retryable blip."
- if [[ -n "${DROPPED_REFS}" ]]; then
- TEXT="${TEXT} Also dropped for conflict: ${DROPPED_REFS}."
- fi
- TEXT="${TEXT} The fixes ride their cycle's 24h path. ${RUN_URL}"
+ # The verify step left the workspace detached at the stable tag,
+ # which predates this tooling — every step shares one workspace, so
+ # the builder below is simply absent from disk. Restore the lane's
+ # own scripts from the ref the workflow is running from. Restored
+ # per path, never as one pathspec: `git checkout <ref> -- a b` is
+ # atomic, so a path missing at that ref would silently take the
+ # other one down with it and leave the page permanently degraded.
+ # The synthetic tree has already served its purpose here — verify
+ # is done, and dispatch (which reads no repo file) is mutually
+ # exclusive with this step.
+ for p in .github/scripts scripts; do
+ git checkout "$GITHUB_SHA" -- "$p" 2>/dev/null \
+ || echo "::warning::bug-lane: could not restore ${p}; the page may fall back."
+ done
+ # Defaults go through intermediate variables, NOT `${V:-{\}}`: a
+ # brace in a parameter-expansion default is taken literally
+ # (backslash and all), so jq --argjson would reject it and every
+ # page would silently degrade to the fallback below.
+ TICKETS_JSON="${FIX_TICKETS:-}"
+ [[ -z "$TICKETS_JSON" ]] && TICKETS_JSON='{}'
+ CONFLICTS_JSON="${CONFLICTS:-}"
+ [[ -z "$CONFLICTS_JSON" ]] && CONFLICTS_JSON='[]'
+ # Join each dropped ref to the tickets that qualified it, so the
+ # page names the bug rather than only a SHA.
+ INPUT="$(jq -nc \
+ --arg verdict "$VERDICT" \
+ --arg stable "$STABLE" \
+ --arg runUrl "$RUN_URL" \
+ --argjson conflicts "$CONFLICTS_JSON" \
+ --argjson tickets "$TICKETS_JSON" \
+ '{verdict: $verdict, stable: $stable, runUrl: $runUrl,
+ refs: [$conflicts[] | . + {tickets: ($tickets[.ref] // [])}]}')"
+ # A page that cannot be composed must not become silence: fall back
+ # to the bare facts rather than skipping the POST, and leave the
+ # marker unwritten so the next tick tries again.
+ if ! payload="$(node .github/scripts/bug-lane-refusal-payload.mjs --input "$INPUT")"; then
+ echo "::warning::bug-lane: could not compose the refusal page; falling back to a plain message."
+ payload="$(jq -nc --arg t "⛔ Bug lane refused ${FIX_REFS} (${VERDICT}) over ${STABLE}. ${RUN_URL}" '{text: $t}')"
fi
- # Say that the silence which follows is deliberate. Without this a
- # reader cannot tell "paged once, still refusing every tick" from
- # "resolved", and would read the quiet channel as good news.
- TEXT="${TEXT} Further identical refusals stay silent; the lane pages again only if the refusal changes."
- payload="$(jq -nc --arg t "$TEXT" '{text: $t}')"
if curl -sS --fail -X POST -H 'Content-type: application/json' --data "$payload" "$WEBHOOK_URL"; then
delivered=true
else