mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/orchestration/merge-queue.js

@@ -0,0 +1,158 @@
+/**
+ * merge-queue.js — the one GraphQL seam for a merge-queue-protected base:
+ * whether the PR's base requires a queue, whether the PR sits in it, and the
+ * dequeue. Keyed on the PR node, so no owner/repo is needed.
+ */
+
+import { gh as defaultGh, describeGhFailure } from '../gh-exec.js';
+
+/** Bound on each merge-queue GraphQL call, so a wedged `gh` cannot stall close. */
+const MERGE_QUEUE_GH_TIMEOUT_MS = 30_000;
+
+const MERGE_QUEUE_STATE_QUERY =
+  'query($id: ID!) { node(id: $id) { ... on PullRequest { isMergeQueueEnabled isInMergeQueue } } }';
+
+const DEQUEUE_MUTATION =
+  'mutation($id: ID!) { dequeuePullRequest(input: { id: $id }) { mergeQueueEntry { id } } }';
+
+/** `gh` stderr when the base requires a merge queue and the arm spelling is wrong. */
+export const MERGE_QUEUE_REFUSAL = /when merge queue enabled/i;
+
+/**
+ * @param {{ stdout?: string }|string|undefined} result
+ * @returns {object|null}
+ */
+function parseGraphqlData(result) {
+  const text = typeof result === 'string' ? result : result?.stdout;
+  const parsed = JSON.parse(String(text ?? ''));
+  if (Array.isArray(parsed?.errors) && parsed.errors.length > 0) {
+    throw new Error(
+      `graphql: ${parsed.errors.map((e) => e?.message).join('; ')}`,
+    );
+  }
+  return parsed?.data ?? null;
+}
+
+/**
+ * Whether the PR's base requires a merge queue, and whether the PR sits in
+ * it now. Keyed on the PR node, so it needs no owner/repo. Never throws: any
+ * failure returns `queueRequired: null` and the caller keeps the non-queue
+ * behaviour.
+ *
+ * @param {{ prNumber?: number|string, prRef?: string, prNodeId?: string,
+ *   gh?: object, timeoutMs?: number }} args `prNodeId` skips the id lookup.
+ * @returns {Promise<{ queueRequired: boolean|null, inQueue: boolean|null,
+ *   prNodeId: string|null, error?: string }>}
+ */
+export async function readMergeQueueState({
+  prNumber,
+  prRef,
+  prNodeId,
+  gh,
+  timeoutMs = MERGE_QUEUE_GH_TIMEOUT_MS,
+}) {
+  const facade = gh ?? defaultGh;
+  let id = prNodeId ?? null;
+  try {
+    if (!id) {
+      const view = await facade.pr.view(String(prRef ?? prNumber), ['id']);
+      id = typeof view?.id === 'string' && view.id ? view.id : null;
+    }
+    if (!id) throw new Error('PR node id unavailable');
+    const data = parseGraphqlData(
+      await facade.api({
+        method: 'POST',
+        endpoint: 'graphql',
+        body: { query: MERGE_QUEUE_STATE_QUERY, variables: { id } },
+        execOpts: { timeoutMs },
+      }),
+    );
+    const node = data?.node;
+    if (typeof node?.isMergeQueueEnabled !== 'boolean') {
+      throw new Error('merge-queue fields absent from the GraphQL response');
+    }
+    return {
+      queueRequired: node.isMergeQueueEnabled,
+      inQueue: node.isInMergeQueue === true,
+      prNodeId: id,
+    };
+  } catch (err) {
+    return {
+      queueRequired: null,
+      inQueue: null,
+      prNodeId: id,
+      error: describeGhFailure(err),
+    };
+  }
+}
+
+/**
+ * Take an enqueued PR out of the merge queue. `--disable-auto` cannot: GitHub
+ * clears the auto-merge request on enqueue, so it reads as never armed.
+ *
+ * @returns {Promise<{ ok: boolean, detail: string }>}
+ */
+async function dequeuePullRequest({ prNodeId, gh }) {
+  try {
+    parseGraphqlData(
+      await (gh ?? defaultGh).api({
+        method: 'POST',
+        endpoint: 'graphql',
+        body: { query: DEQUEUE_MUTATION, variables: { id: prNodeId } },
+        execOpts: { timeoutMs: MERGE_QUEUE_GH_TIMEOUT_MS },
+      }),
+    );
+    return { ok: true, detail: 'dequeued' };
+  } catch (err) {
+    return { ok: false, detail: describeGhFailure(err) };
+  }
+}
+
+/**
+ * Arm on a merge-queue base: a bare `--auto`, and never the direct-merge
+ * fallback — a merge that bypassed the queue would defeat the protection it
+ * exists for.
+ *
+ * @returns {Promise<{ enabled: boolean, mergeQueue: true, reason?: string }>}
+ */
+export async function armForMergeQueue({ exec, prNumber, armCwd }) {
+  try {
+    const result = await exec(['pr', 'merge', String(prNumber), '--auto'], {
+      cwd: armCwd,
+    });
+    if (result.status === 0) return { enabled: true, mergeQueue: true };
+    return {
+      enabled: false,
+      mergeQueue: true,
+      reason: `merge-queue arm failed; gh-exit-${result.status}: ${(result.stderr ?? '').trim().slice(0, 200)}`,
+    };
+  } catch (err) {
+    return {
+      enabled: false,
+      mergeQueue: true,
+      reason: `gh-spawn-error: ${err?.message ?? err}`,
+    };
+  }
+}
+
+/**
+ * Disarm an enqueued PR by dequeueing it. The caller owns the still-armed
+ * warning, so both disarm paths share it.
+ *
+ * @returns {Promise<{ disarmed: boolean, alreadyUnarmed: false, detail: string }>}
+ */
+export async function disarmByDequeue({ prNodeId, ref, gh, progress }) {
+  const dequeued = await dequeuePullRequest({ prNodeId, gh });
+  if (!dequeued.ok) {
+    return {
+      disarmed: false,
+      alreadyUnarmed: false,
+      detail: `merge-queue dequeue failed: ${dequeued.detail}`.slice(0, 200),
+    };
+  }
+  progress?.(
+    'CONFIRM',
+    `🔓 PR #${ref} removed from the merge queue — the PR stays open and hand-mergeable.`,
+  );
+  return { disarmed: true, alreadyUnarmed: false, detail: 'dequeued' };
+}

package/.agents/scripts/lib/orchestration/pinned-identifier-lint.js

@@ -1,38 +1,16 @@
 /**
- * pinned-identifier-lint.js — the `pinned-identifier` advisory lint over a
- * draft Story's `acceptance[]` (Story #5323).
- *
- * `acceptance[]` is the Story's **binding** contract and `changes[]` only an
- * advisory sketch the deliverer may revise, so an acceptance item naming an
- * internal symbol pins something the executor is free to rename out from
- * under it. The story-author prompt has always said so; nothing surfaced a
- * violation, which left the rule enforced only by the authoring model
- * remembering it.
- *
- * The classifier lives in its own module because its vocabulary is its own:
- * four token grammars and a call-suffix strip that the sibling prose lint in
- * `plan-text-hygiene.js` shares nothing with.
- *
- * Advisory by contract: findings are deterministic text for the persist
- * dry-run's warning list. They never gate persist and spawn nothing.
- *
- * Pure, synchronous, no I/O.
+ * pinned-identifier-lint.js — advisory lint flagging `acceptance[]` items that
+ * name an internal symbol. Acceptance is binding while `changes[]` is only a
+ * sketch the deliverer may rename, so a pinned symbol breaks under a legal
+ * refactor. Findings are warnings only. Pure, synchronous, no I/O.
  *
  * @module lib/orchestration/pinned-identifier-lint
  */
 
 /**
- * An inline code span carrying one of these is naming something other than a
- * source identifier, and is never a pinned identifier:
- *
- *   - `/` — a file path or a glob (`src/app.js`, `tests/x/*.spec.ts`);
- *   - `.` — a dotted path, a filename, or a config key
- *     (`delivery.routing.closeAndLand`, `story-body.js`);
- *   - `:` — a label (`agent::ready`, `type::story`);
- *   - `-` — a kebab token: a `data-testid` value, a slug, a package name, or
- *     a CLI flag (`--dry-run`);
- *   - whitespace — an argv shape, so a command (`npm run lint`);
- *   - `[` / `]` — a field reference (`acceptance[]`).
+ * A code span containing any of these names a path/glob, dotted key or
+ * filename, label, kebab token or flag, command, or field reference — never a
+ * source identifier.
  */
 const NON_IDENTIFIER_MARKERS = /[/.:\-\s[\]]/;
 
@@ -40,29 +18,20 @@ const NON_IDENTIFIER_MARKERS = /[/.:\-\s[\]]/;
 const BARE_IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 
 /**
- * An UPPER_SNAKE token. Exempt by contract: an environment variable and an
- * internal constant are the same shape, and warning on every `DATABASE_URL`
- * to catch the occasional pinned constant trades a real class of false
- * positives for a marginal gain.
+ * UPPER_SNAKE is exempt: env vars and constants share the shape, and warning
+ * on every `DATABASE_URL` costs more than it catches.
  */
 const UPPER_SNAKE_RE = /^[A-Z0-9_$]+$/;
 
-/**
- * A case transition (`staffCan`, `MyCalendarBoard`, `TimeGrid`) — the
- * signature that separates a source identifier from a prose word a criterion
- * legitimately quotes (`landed`, `pending`, `main`).
- */
+/** A case transition separates an identifier from a quoted prose word. */
 const CASE_TRANSITION_RE = /[a-z][A-Z]/;
 
-/** The remedy, either side of the identifiers a finding names. */
 const MESSAGE_HEAD = 'Acceptance item pins the internal identifier(s) ';
 const MESSAGE_TAIL =
   '; `changes[]` is an advisory sketch the deliverer may reshape, so assert ' +
   'the observable behaviour instead of the symbol that implements it.';
 
 /**
- * Collect the inline code spans of one acceptance item.
- *
  * @param {string} item
  * @returns {string[]}
  */
@@ -71,13 +40,8 @@ function codeSpans(item) {
 }
 
 /**
- * Decide whether one code span pins a source identifier: a bare token
- * carrying a case transition, with no separator that would make it a path, a
- * label, a kebab token, a flag or a command, and not an UPPER_SNAKE name.
- *
- * Deliberately conservative in one direction only: a false positive costs a
- * warning line the author dismisses, while a false negative on a path, a
- * testid or a command would train the author to ignore the lint.
+ * Conservative: a false positive costs a dismissable warning, while flagging
+ * paths or commands would train authors to ignore the lint.
  *
  * @param {string} span
  * @returns {boolean}
@@ -93,11 +57,8 @@ function isPinnedIdentifier(span) {
 }
 
 /**
- * The authored `acceptance[]` of one draft Story.
- *
- * It is authored at the ticket's top level — the machine contract the
- * validators read — and synced into the body only at assembly, so the top
- * level wins; the parsed body covers a draft that carries it inline.
+ * Top-level `acceptance[]` wins (it is synced into the body only at
+ * assembly); the parsed body covers an inline draft.
  *
  * @param {object} story The raw draft ticket.
  * @param {object} body Its parsed body.
@@ -109,14 +70,13 @@ function resolveAcceptance(story, body) {
 }
 
 /**
- * Evaluate the lint over one draft Story — one finding per offending
- * acceptance item, naming every identifier it pinned.
+ * One finding per offending acceptance item.
  *
  * @param {object} story The raw draft ticket.
  * @param {object} body Its parsed body.
  * @param {string} slug
- * @param {(text: string) => string} excerpt Evidence truncator, shared with
- *   the sibling lints so every finding excerpts alike.
+ * @param {(text: string) => string} excerpt Evidence truncator shared with
+ *   the sibling lints.
  * @returns {Array<{ kind: 'pinned-identifier', slug: string, evidence: string, message: string }>}
  */
 export function findPinnedIdentifiers(story, body, slug, excerpt) {