@elalfner/relevo 0.7.0 → 0.8.0

package/scripts/lib/messages.mjs

@@ -29,10 +29,18 @@ const REQUIRED = {
   no_assignee: ['actor', 'issue'],
   ready_denied: ['issue'],
   ready_denied_maintainer: ['issue'],
+  urgent_denied: ['issue'],
+  urgent_denied_maintainer: ['issue'],
   blocked_notice: ['issue', 'title', 'blockers'],
   queued_capacity: ['issue', 'title', 'assignee', 'built', 'limit'],
   queued_agents: ['issue', 'title'],
   fix_done: ['issue', 'title', 'summary', 'qa', 'commit', 'iteration'],
+  ship_stopped: ['actor', 'issue', 'reasons'],
+  ship_not_approver: ['actor', 'issue'],
+  ship_no_ci: ['actor', 'issue'],
+  ship_needs_app: ['actor', 'issue', 'base'],
+  ship_done: ['issue', 'pr', 'base'],
+  ship_failed: ['issue', 'run'],
 };
 
 // The lifecycle state whose next step each message shows (see next-step.mjs, the only place that knows the commands).
@@ -52,6 +60,7 @@ const CATALOG = {
       '',
       'What happened: {{tasks_done}} of {{tasks_total}} tasks done, QA passed.',
       'Branch: {{branch}}',
+      'Started ahead of the queue (urgent): you now have {{built_waiting}} built issues waiting for your review.',
       'Built from the issue text: {{issue_hash_short}}',
       'What to test: {{scenarios}} scenarios (checklist below)',
       'Riskiest area, check it first: {{risk}}',
@@ -93,6 +102,7 @@ const CATALOG = {
       '',
       'Pull request: {{pr}}',
       'Your next step: {{command}}',
+      'Or apply the label {{ship_label}} to this issue: it ships on GitHub, with no local copy.',
     ],
     needs_reviewer: [
       '@{{spec_writer}} #{{issue}} "{{title}}" has no available reviewer',
@@ -134,10 +144,19 @@ const CATALOG = {
       '#{{issue}} was not started: this repository is public, so only maintainers can mark an issue ready, and the label was removed',
       'Applied by: @{{actor}}',
     ],
+    urgent_denied: [
+      '#{{issue}}: the urgent label was removed because only people with write access can ask for an early start. The issue keeps its place in the queue.',
+      'Applied by: @{{actor}}',
+    ],
+    urgent_denied_maintainer: [
+      '#{{issue}}: the urgent label was removed because this repository is public, so only maintainers can ask for an early start. The issue keeps its place in the queue.',
+      'Applied by: @{{actor}}',
+    ],
     blocked_notice: [
       '#{{issue}} "{{title}}" is blocked',
       '',
       'Waiting for {{blockers}} to be merged. It starts automatically when they are.',
+      '{{urgent_note}}',
     ],
     queued_capacity: [
       '#{{issue}} "{{title}}" is queued',
@@ -157,6 +176,41 @@ const CATALOG = {
       'Commit: {{commit}}',
       '@{{recipient}} {{ask}}',
     ],
+    ship_stopped: [
+      '@{{actor}} #{{issue}} was not shipped',
+      '',
+      'Why: {{reasons}}',
+      'Nothing was merged and the issue keeps its state; the relevo:ship label was removed. Apply it again once this is solved, or run `/relevo:ship {{issue}}`.',
+    ],
+    ship_not_approver: [
+      '@{{actor}} #{{issue}} was not shipped: you did not approve this pull request',
+      '',
+      'An eligible person who did not approve has to say so in writing, and a label cannot. Run `/relevo:ship {{issue}}`, which asks you to confirm it, or ask {{approvers}} to apply the label. The label was removed.',
+    ],
+    ship_no_ci: [
+      '@{{actor}} #{{issue}} was not shipped: no check ran on this pull request',
+      '',
+      'Nothing but the review vouches for this code, and the label cannot confirm that. Run `/relevo:ship {{issue}}`, which asks you, or set `review.ship_without_ci: true` in relevo.yml to let the label merge without checks. The label was removed.',
+    ],
+    ship_needs_app: [
+      '@{{actor}} #{{issue}} was not shipped: {{base}} requires status checks',
+      '',
+      'The archive commit needs its own checks, and a push with the workflow token starts none. Create a GitHub App for this repository and store its id and private key as the secrets RELEVO_SHIP_APP_ID and RELEVO_SHIP_APP_KEY (see docs/execution.md), or run `/relevo:ship {{issue}}`. Nothing was archived; the label was removed.',
+    ],
+    ship_done: [
+      '#{{issue}} shipped ✅',
+      '',
+      'Pull request {{pr}} was squash-merged into {{base}} as {{commit}}.',
+      'Applied by: @{{actor}}',
+      '{{checks_note}}',
+      'The issue is closed and its labels removed. Promoting {{base}} to the release branch is a separate pull request.',
+    ],
+    ship_failed: [
+      '#{{issue}} was not shipped: the run ended without an outcome',
+      '',
+      '{{log_line}}',
+      'When the cause is fixed, apply relevo:ship again: a specification already archived is not archived twice.',
+    ],
   },
   es: {
     built: [
@@ -164,6 +218,7 @@ const CATALOG = {
       '',
       'Qué pasó: {{tasks_done}} de {{tasks_total}} tareas hechas, QA aprobado.',
       'Rama: {{branch}}',
+      'Empezó antes que la cola (urgente): ahora tienes {{built_waiting}} issues construidos esperando tu revisión.',
       'Construida con el texto del issue: {{issue_hash_short}}',
       'Qué probar: {{scenarios}} escenarios (checklist abajo)',
       'Zona más riesgosa, revísala primero: {{risk}}',
@@ -205,6 +260,7 @@ const CATALOG = {
       '',
       'Pull request: {{pr}}',
       'Tu siguiente paso: {{command}}',
+      'O pon la etiqueta {{ship_label}} a este issue: se fusiona en GitHub, sin copia local.',
     ],
     needs_reviewer: [
       '@{{spec_writer}} #{{issue}} "{{title}}" no tiene revisor disponible',
@@ -246,10 +302,19 @@ const CATALOG = {
       '#{{issue}} no se inició: este repositorio es público, así que solo quienes mantienen el proyecto pueden marcar un issue como ready, y se quitó la etiqueta',
       'Aplicada por: @{{actor}}',
     ],
+    urgent_denied: [
+      '#{{issue}}: se quitó la etiqueta de urgente porque solo quienes tienen acceso de escritura pueden pedir un inicio anticipado. El issue conserva su lugar en la cola.',
+      'Aplicada por: @{{actor}}',
+    ],
+    urgent_denied_maintainer: [
+      '#{{issue}}: se quitó la etiqueta de urgente porque este repositorio es público, así que solo quienes mantienen el proyecto pueden pedir un inicio anticipado. El issue conserva su lugar en la cola.',
+      'Aplicada por: @{{actor}}',
+    ],
     blocked_notice: [
       '#{{issue}} "{{title}}" está bloqueado',
       '',
       'Espera a que se fusionen {{blockers}}. Empieza solo cuando lo estén.',
+      '{{urgent_note}}',
     ],
     queued_capacity: [
       '#{{issue}} "{{title}}" está en cola',
@@ -269,6 +334,41 @@ const CATALOG = {
       'Commit: {{commit}}',
       '@{{recipient}} {{ask}}',
     ],
+    ship_stopped: [
+      '@{{actor}} #{{issue}} no se fusionó',
+      '',
+      'Por qué: {{reasons}}',
+      'No se fusionó nada y el issue conserva su estado; se quitó la etiqueta relevo:ship. Vuelve a ponerla cuando esté resuelto, o ejecuta `/relevo:ship {{issue}}`.',
+    ],
+    ship_not_approver: [
+      '@{{actor}} #{{issue}} no se fusionó: tú no aprobaste este pull request',
+      '',
+      'Quien es elegible pero no aprobó tiene que decirlo por escrito, y una etiqueta no puede. Ejecuta `/relevo:ship {{issue}}`, que te pide confirmarlo, o pide a {{approvers}} que ponga la etiqueta. Se quitó la etiqueta.',
+    ],
+    ship_no_ci: [
+      '@{{actor}} #{{issue}} no se fusionó: no corrió ningún check en este pull request',
+      '',
+      'Solo la revisión respalda este código, y la etiqueta no puede confirmarlo. Ejecuta `/relevo:ship {{issue}}`, que te lo pregunta, o pon `review.ship_without_ci: true` en relevo.yml para que la etiqueta fusione sin checks. Se quitó la etiqueta.',
+    ],
+    ship_needs_app: [
+      '@{{actor}} #{{issue}} no se fusionó: {{base}} exige status checks',
+      '',
+      'El commit del archivo necesita sus propios checks, y un push con el token del workflow no lanza ninguno. Crea una GitHub App para este repositorio y guarda su id y su clave privada como los secrets RELEVO_SHIP_APP_ID y RELEVO_SHIP_APP_KEY (ver docs/execution.es.md), o ejecuta `/relevo:ship {{issue}}`. No se archivó nada; se quitó la etiqueta.',
+    ],
+    ship_done: [
+      '#{{issue}} fusionada ✅',
+      '',
+      'El pull request {{pr}} se fusionó con squash en {{base}} como {{commit}}.',
+      'La pidió: @{{actor}}',
+      '{{checks_note}}',
+      'El issue está cerrado y sin etiquetas. Promover {{base}} a la rama de release es un pull request aparte.',
+    ],
+    ship_failed: [
+      '#{{issue}} no se fusionó: la ejecución terminó sin resultado',
+      '',
+      '{{log_line}}',
+      'Cuando la causa esté resuelta, vuelve a poner relevo:ship: una especificación ya archivada no se archiva dos veces.',
+    ],
   },
 };
 
@@ -297,7 +397,16 @@ export function renderMessage(kind, data = {}, language = 'en') {
   });
   const language_ = pickLanguage(language);
   const es = language_ === 'es';
+  // The person who applied the label is mentioned when the run knows who it was.
+  if (kind === 'ship_failed') {
+    const who = present(values.actor) ? `@${values.actor} ` : '';
+    values.log_line = es ? `${who}${who ? 'lee' : 'Lee'} el log para ver por qué: ${values.run}` : `${who}${who ? 'read' : 'Read'} the log to see why: ${values.run}`;
+  }
   if (kind === 'built' && present(values.issue_hash)) values.issue_hash_short = shortHash(values.issue_hash);
+  // Urgent does not skip dependencies: an urgent issue that is blocked says so.
+  if (kind === 'blocked_notice' && values.urgent === true) {
+    values.urgent_note = es ? 'La etiqueta de urgente no salta las dependencias: empieza primero en la cola cuando se fusionen.' : 'The urgent label does not skip dependencies: it goes first in the queue once they are merged.';
+  }
 
   // The next step comes from one table. needs-spec depends on why the issue came back, qa-failed on what the branch holds.
   if (STATE_OF[kind]) {

package/scripts/lib/next-step.mjs

@@ -104,6 +104,18 @@ const TABLE = {
     who: 'spec_writer',
     hint: { en: 'assign a reviewer or ask someone to take it', es: 'asigna a alguien que revise o pide que alguien lo tome' },
   },
+  // The ship workflow is merging it; when it stops, its comment says why and the issue is back on pr-open.
+  ship: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'the ship workflow is merging it', es: 'el workflow de ship lo está fusionando' },
+  },
+  // A request next to the state, not a state: the state it travels with decides the next step.
+  urgent: {
+    command: null,
+    who: 'nobody',
+    hint: { en: 'it starts before the others; the state it is in decides the next step', es: 'empieza antes que las demás; el estado en que está decide el siguiente paso' },
+  },
 };
 
 const WHO = {

package/scripts/lib/plan.mjs

@@ -6,7 +6,8 @@
 //   issues     [{ number, title, body, state, labels: [names], assignees: [logins],
 //                 milestone: { number, due_on } | null,
 //                 ready_at: ISO | null,   // when the ready label was last applied
-//                 ready_by: login | null  // who applied it }]
+//                 ready_by: login | null, // who applied it
+//                 urgent_by: login | null // who applied the urgent label, when the issue carries it }]
 //   completed  issue numbers closed as completed (their pull request merged)
 //   running    issue numbers with an agent run in progress
 //   permissions  { login: 'admin' | 'maintain' | 'write' | 'triage' | 'read' | 'none' }
@@ -61,6 +62,12 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
   const linked = (config.links ?? []);
   const own = repo ? repo.toLowerCase() : null;
 
+  // The urgent label is a request that only the people who may start work can make. A label from anyone else is not
+  // valid: it is removed (with a notice) and the issue is evaluated as a normal one.
+  const mayTrigger = config.trust === 'public' ? MAY_TRIGGER_PUBLIC : MAY_TRIGGER;
+  const hasUrgentLabel = (issue) => has(issue, 'urgent');
+  const isUrgent = (issue) => hasUrgentLabel(issue) && Boolean(issue.urgent_by) && mayTrigger.has(permissions[issue.urgent_by]);
+
   const runningSet = new Set(running);
   open.filter((i) => has(i, 'building')).forEach((i) => runningSet.add(i.number));
   let freeSlots = Math.max(0, config.limits.concurrent_agents - runningSet.size);
@@ -71,14 +78,16 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
     if (owner) builtBy.set(owner, (builtBy.get(owner) ?? 0) + 1);
   });
 
+  // Valid urgent issues are considered first, so they take the free agent slots before the others; inside each group
+  // the order is the time `ready` was applied.
   const candidates = open
     .filter((i) => has(i, 'ready') || has(i, 'queued') || has(i, 'blocked'))
-    .sort(byReadyAt);
+    .sort((a, b) => Number(isUrgent(b)) - Number(isUrgent(a)) || byReadyAt(a, b));
 
   const decisions = [];
 
   function decision(issue, action, reason, extra = {}) {
-    const labels = extra.labels ?? { add: [], remove: [] };
+    let labels = extra.labels ?? { add: [], remove: [] };
     const out = {
       issue: issue.number,
       action,
@@ -87,6 +96,16 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
       comment: extra.comment ?? null,
       assign: extra.assign ?? null,
     };
+    // An urgent label that is not valid is removed in the decision of the issue, with its own notice. An issue whose
+    // run is in progress is left alone.
+    if (action !== 'skip' && hasUrgentLabel(issue) && !isUrgent(issue)) {
+      labels = { add: labels.add, remove: [...labels.remove, names.urgent] };
+      out.labels = labels;
+      out.notice = {
+        kind: config.trust === 'public' ? 'urgent_denied_maintainer' : 'urgent_denied',
+        data: { issue: issue.number, ...(issue.urgent_by ? { actor: issue.urgent_by } : {}) },
+      };
+    }
     if (action === 'start') Object.assign(out, extra.start);
     decisions.push(out);
   }
@@ -189,15 +208,17 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
       decision(issue, 'block', `waiting for ${blockers.join(', ')}`, {
         labels: moveTo(issue, 'blocked'),
         comment: entering
-          ? { kind: 'blocked_notice', data: { issue: issue.number, title: issue.title, blockers: blockers.join(', ') } }
+          ? { kind: 'blocked_notice', data: { issue: issue.number, title: issue.title, blockers: blockers.join(', '), ...(isUrgent(issue) ? { urgent: true } : {}) } }
           : null,
       });
       return;
     }
 
-    // Gate 3: capacity of the assignee.
+    // Gate 3: capacity of the assignee. A valid urgent label skips this gate and no other.
     const built = assignee ? builtBy.get(assignee) ?? 0 : 0;
-    if (assignee && built >= config.limits.built_unreviewed_per_person) {
+    const overCapacity = Boolean(assignee) && built >= config.limits.built_unreviewed_per_person;
+    const urgent = isUrgent(issue);
+    if (overCapacity && !urgent) {
       decision(issue, 'queue', `${assignee} already has ${built} built issues waiting for review`, {
         labels: moveTo(issue, 'queued'),
         comment: has(issue, 'queued')
@@ -244,6 +265,8 @@ export function planGo({ config, issues, completed = [], completedExternal = [],
         stack: platform.entry.stack,
         path: platform.entry.path,
         targets: platform.entry.targets,
+        // Only when the urgent label let the issue start over the assignee's capacity: the hand-off message says so.
+        ...(overCapacity && urgent ? { urgent: true, built_waiting: built + 1 } : {}),
       },
     });
   });

package/scripts/lib/preflight.mjs

@@ -27,7 +27,7 @@ function checkConfig({ readConfig }) {
 
 function checkOpenspec({ run }) {
   const r = run('openspec', ['--version']);
-  return r.status === 0 ? pass('openspec') : fail('openspec', 'the OpenSpec command line does not run', 'run /relevo:doctor');
+  return r.status === 0 ? pass('openspec') : fail('openspec', 'the OpenSpec command line does not run. Stop here: do not go on from memory and do not write anything under openspec/changes/ by hand', 'install it with `npm install --global @fission-ai/openspec` (Node.js 20.19 or newer), or run /relevo:doctor');
 }
 
 function checkOpenspecRoot({ run }) {

package/scripts/lib/review-events.mjs

@@ -16,8 +16,11 @@ function summarise(body, es) {
   return text.length > SUMMARY_LENGTH ? `${text.slice(0, SUMMARY_LENGTH)}…` : text;
 }
 
-/** Returns { action, labels: { add, remove }, comment } or null when the event changes nothing. */
-export function planReviewEvent({ config, event, pr, issue }) {
+/**
+ * Returns { action, labels: { add, remove }, comment } or null when the event changes nothing.
+ * shipWorkflow: the ship workflow is installed on the default branch, so the approval also names its label.
+ */
+export function planReviewEvent({ config, event, pr, issue, shipWorkflow = false }) {
   if (config.review.mode === 'none') return null;
   const names = resolveLabelNames(config.labels);
   const has = (key) => issue.labels.includes(names[key]);
@@ -49,7 +52,7 @@ export function planReviewEvent({ config, event, pr, issue }) {
     return {
       action: 'approved',
       labels: { add: [], remove: [] },
-      comment: { kind: 'approved', data: { recipient, issue: issue.number, reviewer: event.reviewer, pr: pr.url } },
+      comment: { kind: 'approved', data: { recipient, issue: issue.number, reviewer: event.reviewer, pr: pr.url, ...(shipWorkflow ? { ship_label: names.ship } : {}) } },
     };
   }
   return null;

package/scripts/lib/ship-github.mjs

@@ -0,0 +1,87 @@
+// What ship reads from GitHub besides the pull request: the commits since the approved head, the checks of that
+// head, and whether the base branch requires checks. The client is injected (`gh(args) -> stdout`) for the tests.
+// Implements "Checks of the approved head count for the archive commit" and "Repositories that require checks ship
+// with an App" of openspec/specs/ship/spec.md.
+
+const SPECS_DIR = 'openspec/';
+// The compare API lists at most 300 files; a longer list cannot be proven to stay inside the specifications.
+const COMPARE_FILE_LIMIT = 300;
+
+const ROLLUP_QUERY = `query($owner: String!, $name: String!, $oid: GitObjectID!) {
+  repository(owner: $owner, name: $name) {
+    object(oid: $oid) {
+      ... on Commit {
+        statusCheckRollup {
+          contexts(first: 100) {
+            nodes {
+              __typename
+              ... on CheckRun { name status conclusion }
+              ... on StatusContext { context state }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+
+// The fields shipDecision reads.
+export const PR_FIELDS = 'number,state,isDraft,mergeable,title,author,reviews,statusCheckRollup,headRefName,headRefOid,baseRefName';
+
+/** The open pull request of `branch` (or its latest one), as `gh pr view --json` gives it, or null when none exists. */
+export function loadPr(gh, repo, branch) {
+  const found = JSON.parse(gh(['pr', 'list', '--repo', repo, '--head', branch, '--state', 'all', '--json', 'number,state', '--limit', '5']));
+  const open = found.find((p) => p.state === 'OPEN') ?? found[0];
+  return open ? JSON.parse(gh(['pr', 'view', String(open.number), '--repo', repo, '--json', PR_FIELDS])) : null;
+}
+
+const notFound = (err) => /404|Not Found/i.test(String(err?.stderr ?? err?.message ?? err));
+
+/** True when every file that changed from `baseline` to `head` is under `openspec/`, and something changed. */
+export function changedOnlySpecs(gh, repo, baseline, head) {
+  if (!baseline || !head || baseline === head) return false;
+  const data = JSON.parse(gh(['api', `repos/${repo}/compare/${baseline}...${head}`]));
+  const files = data.files ?? [];
+  if (files.length === 0 || files.length >= COMPARE_FILE_LIMIT) return false;
+  return files.every((f) => f.filename.startsWith(SPECS_DIR) && (!f.previous_filename || f.previous_filename.startsWith(SPECS_DIR)));
+}
+
+/** The status check rollup of one commit, in the shape `gh pr view --json statusCheckRollup` gives. */
+export function commitRollup(gh, repo, oid) {
+  const [owner, name] = repo.split('/');
+  const data = JSON.parse(gh(['api', 'graphql', '-f', `query=${ROLLUP_QUERY}`, '-f', `owner=${owner}`, '-f', `name=${name}`, '-f', `oid=${oid}`]));
+  return data.data?.repository?.object?.statusCheckRollup?.contexts?.nodes ?? [];
+}
+
+/** The input of shipDecision's `baselineChecks`, or undefined when there is no baseline to compare. */
+export function baselineChecks(gh, repo, baseline, head) {
+  if (!baseline || !head || baseline === head) return undefined;
+  const archiveOnly = changedOnlySpecs(gh, repo, baseline, head);
+  return { archiveOnly, rollup: archiveOnly ? commitRollup(gh, repo, baseline) : [] };
+}
+
+/**
+ * Whether merging into `branch` requires status checks, by a ruleset or by classic branch protection.
+ * Returns { required: boolean, contexts: [names] }. A branch without protection requires none.
+ */
+export function requiredChecks(gh, repo, branch) {
+  const contexts = new Set();
+  let required = false;
+  const rules = JSON.parse(gh(['api', `repos/${repo}/rules/branches/${encodeURIComponent(branch)}`]));
+  (Array.isArray(rules) ? rules : []).filter((r) => r.type === 'required_status_checks').forEach((r) => {
+    required = true;
+    (r.parameters?.required_status_checks ?? []).forEach((c) => contexts.add(c.context));
+  });
+  try {
+    const protection = JSON.parse(gh(['api', `repos/${repo}/branches/${encodeURIComponent(branch)}/protection`]));
+    const classic = protection.required_status_checks;
+    if (classic) {
+      required = true;
+      (classic.contexts ?? []).forEach((c) => contexts.add(c));
+      (classic.checks ?? []).forEach((c) => contexts.add(c.context));
+    }
+  } catch (err) {
+    if (!notFound(err)) throw err;
+  }
+  return { required, contexts: [...contexts] };
+}