@spec-wave/cli 0.27.0 → 0.29.0

package/src/commands/merge.mjs

@@ -0,0 +1,292 @@
+// Mergeia os PRs empilhados das Stories de uma Feature, na ordem topológica —
+// o passo final do fluxo, que até aqui era inteiramente manual e frágil.
+//
+// O implement empilha de propósito (cada Story revisável sozinha, diff limpo),
+// mas a pilha torna o merge ordem-dependente: `--delete-branch` no primeiro PR
+// já fechou o segundo sem volta. A sequência segura, que este comando encapsula:
+//
+//   para cada PR, na ordem das dependências:
+//     1. reaponta a base para a default (o anterior já mergeou; com merge
+//        commit o retarget é limpo — por isso o método é `merge`, não squash)
+//     2. mergeia
+//     3. atualiza o board (code-review + qa — merge move até 🧪 QA)
+//   e SÓ NO FIM apaga as branches, quando nenhum PR aberto depende delas.
+//
+// PR em rascunho BLOQUEIA o plano inteiro: marcar pronto é o ato de revisão
+// humana (e o que dispara o CI) — mergear rascunho por cima seria pular a única
+// aprovação que o fluxo tem. Falha no meio para a fila e explica: os merges já
+// feitos ficam, rodar de novo retoma de onde parou (PR mergeado sai do plano).
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, getPR, getRepoDefaultBranch, updatePRBase, mergePR, deleteBranch, listBlockedBy,
+} from '../api/github-rest.mjs';
+import { listSubIssues, listIssuePullRequests } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
+import { resolveRepoContext } from '../lib/project-root.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { acquireLock, releaseLock } from './run.mjs';
+import { codeReview } from './code-review.mjs';
+import { qa } from './qa.mjs';
+
+/**
+ * O plano de merge (função PURA — é onde mora toda a decisão).
+ *
+ * Separa cada Story em um destino: `fila` (PR aberto, pronto, entra na ordem),
+ * `concluidas` (PR já mergeado — é o que torna rodar de novo uma RETOMADA),
+ * `bloqueios` (rascunho, mais de um PR aberto — parar antes de mergear
+ * qualquer coisa, porque merge parcial de uma pilha é o pior estado) e
+ * `avisos` (Story sem PR nenhum — fica de fora, mas quem depende dela pode
+ * carregar commits que não existem na base).
+ *
+ * @param {object} params
+ * @param {number[]} params.sorted ordem topológica (números de Story)
+ * @param {Map<number, {title: string}>} params.byNumber
+ * @param {Map<number, Array<{number, state, merged, isDraft, baseRefName, headRefName}>>} params.prsByStory
+ * @param {string} params.defaultBranch
+ * @returns {{ fila: Array<{story:number, pr:object}>, concluidas: Array<{story:number, pr:object}>,
+ *             semPr: number[], bloqueios: string[], avisos: string[] }}
+ */
+export function planMerge({ sorted = [], byNumber = new Map(), prsByStory = new Map(), defaultBranch } = {}) {
+  const fila = [];
+  const concluidas = [];
+  const semPr = [];
+  const bloqueios = [];
+  const avisos = [];
+  const headsNoPlano = new Set();
+
+  for (const story of sorted) {
+    const prs = prsByStory.get(story) || [];
+    const mergeados = prs.filter(pr => pr.merged);
+    const abertos = prs.filter(pr => pr.state === 'open');
+
+    if (mergeados.length > 0 && abertos.length === 0) {
+      concluidas.push({ story, pr: mergeados[0] });
+      continue;
+    }
+    if (abertos.length === 0) {
+      semPr.push(story);
+      continue;
+    }
+    if (abertos.length > 1) {
+      bloqueios.push(
+        `Story #${story} tem ${abertos.length} PRs abertos (${abertos.map(x => `#${x.number}`).join(', ')}) — ` +
+        'ambíguo; feche o que não vale antes de mergear.'
+      );
+      continue;
+    }
+    const pr = abertos[0];
+    if (pr.isDraft) {
+      bloqueios.push(
+        `PR #${pr.number} (Story #${story}) está em RASCUNHO. Marcar pronto é a revisão humana ` +
+        'e o que dispara o CI — revise e marque pronto antes de mergear.'
+      );
+      continue;
+    }
+    // Base que não é a default nem a head de alguém que mergeia antes: ou a
+    // pilha está fora de ordem, ou aponta para algo que este plano não conhece.
+    if (pr.baseRefName !== defaultBranch && !headsNoPlano.has(pr.baseRefName)) {
+      avisos.push(
+        `PR #${pr.number} (Story #${story}) tem base "${pr.baseRefName}", que não é a default ` +
+        'nem a branch de um PR anterior da fila — confira a pilha antes de confirmar.'
+      );
+    }
+    headsNoPlano.add(pr.headRefName);
+    fila.push({ story, pr });
+  }
+
+  if (semPr.length > 0) {
+    avisos.push(
+      `Story(ies) sem PR: ${semPr.map(n => `#${n}`).join(', ')} — ficam de fora; ` +
+      'se um PR da fila depender do código delas, o merge vai levar esse código junto.'
+    );
+  }
+
+  return { fila, concluidas, semPr, bloqueios, avisos };
+}
+
+export async function merge({ feature: featureArg, yes = false, dryRun = false, keepBranches = false } = {}) {
+  if (process.env.GITHUB_ACTIONS === 'true') {
+    p.log.error('`spec-wave merge` é um comando local — dentro do Actions o merge é decisão humana.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const featureNumber = parseInt(String(featureArg).replace('#', ''), 10);
+  if (!Number.isInteger(featureNumber) || featureNumber <= 0) {
+    p.log.error(`Feature inválida: "${featureArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { owner, repo, root } = resolveRepoContext();
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} (\`spec-wave init\`) ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave merge #${featureNumber}`));
+  const s = p.spinner();
+  s.start('Montando o plano de merge...');
+
+  let featureIssue;
+  let defaultBranch;
+  try {
+    featureIssue = await getIssue(token, owner, repo, featureNumber);
+    defaultBranch = await getRepoDefaultBranch(token, owner, repo);
+  } catch (err) {
+    s.stop('');
+    p.log.error(`Não foi possível ler ${owner}/${repo}#${featureNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (detectIssueType(featureIssue) !== 'Feature') {
+    s.stop('');
+    p.log.error(`\`spec-wave merge\` só aceita Features. Issue #${featureNumber} é ${detectIssueType(featureIssue) || 'de tipo desconhecido'}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // As Stories e a ordem — as mesmas fontes do `order`.
+  let subs;
+  try {
+    subs = await listSubIssues(token, featureIssue.node_id);
+  } catch (err) {
+    s.stop('');
+    p.log.error(`Não foi possível listar as sub-issues: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const stories = subs.filter(x => detectIssueType({ title: x.title, labels: x.labels }) === 'Story');
+  if (stories.length === 0) {
+    s.stop('');
+    p.log.info(`Feature #${featureNumber} não tem Stories — nada a mergear.`);
+    p.outro('Nada a fazer.');
+    return;
+  }
+
+  const enriched = await Promise.all(stories.map(async (st) => {
+    const fromBody = parseDependencies(st.body);
+    const fromBlockedBy = (await listBlockedBy(token, owner, repo, st.number).catch(() => []))
+      .map(b => b.number);
+    return { number: st.number, title: st.title, nodeId: st.nodeId, dependsOn: [...new Set([...fromBody, ...fromBlockedBy])] };
+  }));
+  const byNumber = new Map(enriched.map(x => [x.number, x]));
+  const { order: sorted, cycle } = orderStories(
+    enriched.map(({ number, dependsOn }) => ({ number, dependsOn })));
+  if (cycle.length > 0) {
+    s.stop('');
+    p.log.error(
+      `Ciclo de dependências entre Stories (${cycle.map(n => `#${n}`).join(', ')}) — ` +
+      'não existe ordem de merge. Corrija as linhas "Depende de" e rode de novo.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const prsByStory = new Map();
+  for (const story of sorted) {
+    prsByStory.set(story, await listIssuePullRequests(token, byNumber.get(story).nodeId).catch(() => []));
+  }
+
+  const plano = planMerge({ sorted, byNumber, prsByStory, defaultBranch });
+  s.stop(`${plano.fila.length} PR(s) a mergear · ${plano.concluidas.length} já mergeado(s).`);
+
+  const linha = ({ story, pr }) => {
+    const retarget = pr.baseRefName !== defaultBranch ? `  ${chalk.dim(`base ${pr.baseRefName} → ${defaultBranch}`)}` : '';
+    return `  PR #${pr.number} · Story #${story} ${byNumber.get(story)?.title || ''}${retarget}`;
+  };
+  if (plano.fila.length > 0) {
+    p.note(plano.fila.map(linha).join('\n'), `Ordem de merge (base: ${defaultBranch}, método: merge commit)`);
+  }
+  for (const a of plano.avisos) p.log.warn(a);
+  for (const b of plano.bloqueios) p.log.error(b);
+
+  if (plano.bloqueios.length > 0) {
+    p.outro('Bloqueado — merge parcial de pilha é o pior estado; resolva e rode de novo.');
+    process.exitCode = 1;
+    return;
+  }
+  if (plano.fila.length === 0) {
+    p.outro(plano.concluidas.length > 0 ? 'Tudo já mergeado.' : 'Nenhum PR aberto para mergear.');
+    return;
+  }
+  if (dryRun || !yes) {
+    p.outro(dryRun ? 'Dry-run: nada foi mergeado.' : 'Confirme com `--yes` para mergear nesta ordem.');
+    return;
+  }
+
+  // ---------- Execução ----------
+  const lock = acquireLock(root, `merge-${featureNumber}`);
+  const mergedHeads = [];
+  try {
+    for (const { story, pr } of plano.fila) {
+      // Estado fresco: a fila pode ter envelhecido entre o plano e este ponto.
+      const atual = await getPR(token, owner, repo, pr.number);
+      if (atual.merged_at) {
+        p.log.info(`PR #${pr.number} já estava mergeado — seguindo.`);
+        continue;
+      }
+      if (atual.base?.ref !== defaultBranch) {
+        p.log.step(`PR #${pr.number}: base ${atual.base?.ref} → ${defaultBranch}`);
+        await updatePRBase(token, owner, repo, pr.number, defaultBranch);
+      }
+      try {
+        await mergePR(token, owner, repo, pr.number, { method: 'merge' });
+      } catch (err) {
+        // 405 = draft/check pendente/conflito. Parar AQUI preserva a ordem: os
+        // dependentes continuam com branch e PR intactos, e rodar de novo retoma.
+        p.log.error(
+          `Merge do PR #${pr.number} (Story #${story}) recusado: ${err.message}\n` +
+          'Nada depois dele foi mergeado. Resolva (checks, conflito) e rode o comando de novo — ' +
+          'os já mergeados saem do plano sozinhos.'
+        );
+        process.exitCode = 1;
+        return;
+      }
+      p.log.success(`PR #${pr.number} mergeado (Story #${story}).`);
+      mergedHeads.push(pr.headRefName);
+
+      // Board: merge move até 🧪 QA. Falha aqui não desfaz merge — avisa e segue.
+      try {
+        await codeReview({ prNumber: String(pr.number) });
+        await qa({ prNumber: String(pr.number) });
+      } catch (err) {
+        p.log.warn(`Board não atualizado para o PR #${pr.number}: ${err.message} — rode \`spec-wave run --pr ${pr.number}\` depois.`);
+      }
+    }
+
+    // Branches só no FIM, quando nenhum PR aberto depende delas — apagar antes
+    // do retarget do dependente foi o que fechou um PR empilhado sem volta.
+    if (!keepBranches) {
+      for (const head of mergedHeads) {
+        if (!head) continue;
+        await deleteBranch(token, owner, repo, head).catch(err =>
+          p.log.warn(`Branch ${head} não apagada: ${err.message}`));
+      }
+    }
+  } finally {
+    releaseLock(lock);
+  }
+
+  p.outro(
+    `${chalk.green('✓')} ${mergedHeads.length} PR(s) mergeado(s) na ordem` +
+    (keepBranches ? ' (branches mantidas).' : ', branches apagadas.')
+  );
+}

package/src/commands/move.mjs

@@ -191,6 +191,14 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
   // mesmo quando a Etapa não avança — ver ensureWorkItemType.
   const typeField = await resolveField(token, project, 'Work Item Type').catch(() => null);
 
+  // A Etapa de PARTIDA, lida antes de escrever: a mensagem de sucesso imprime a
+  // transição real ("✅ Ready → 🧪 QA"), não a intenção do comando.
+  const lerEtapa = async () => {
+    const itemId = await addProjectItem(token, project.id, issue.node_id);
+    return etapaField?.id ? await getItemSingleSelectValue(token, itemId, etapaField.id) : null;
+  };
+  const antes = await lerEtapa().catch(() => null);
+
   let moved;
   try {
     moved = await advanceToStage(
@@ -203,24 +211,31 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
   }
 
   if (moved) {
+    // Confirmação por leitura — era o usuário quem tinha que "confirmar lendo o
+    // board de volta"; agora o comando lê, e uma escrita que não pegou vira
+    // erro visível em vez de ✅ mentiroso.
+    const depois = await lerEtapa().catch(() => null);
+    if (depois !== null && depois !== stage) {
+      p.log.error(
+        `A escrita não confirmou: o board ainda mostra ${chalk.bold(depois)} ` +
+        `(esperado ${chalk.bold(stage)}). Verifique permissões do token no Project.`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const confirmada = depois !== null;
     p.log.success(
-      `${type || 'Issue'} #${issueNumber} → Etapa ${chalk.bold(stage)} / Status ${chalk.bold(status)}.`
+      `${type || 'Issue'} #${issueNumber}: ${chalk.bold(antes || '—')} → ${chalk.bold(stage)}` +
+      ` / Status ${chalk.bold(status)}` +
+      (confirmada ? ' (confirmado por leitura do board)' : ' (leitura de confirmação falhou — confira o board)')
     );
     p.outro(`${chalk.green('✓')} ${issue.title}`);
     return;
   }
 
   // false = já está nessa Etapa ou adiante (ou numa coluna fora da ordem
-  // canônica). A Etapa NUNCA retrocede — lê a atual só para informar.
-  let current = null;
-  if (etapaField?.id) {
-    try {
-      const itemId = await addProjectItem(token, project.id, issue.node_id);
-      current = await getItemSingleSelectValue(token, itemId, etapaField.id);
-    } catch {
-      // sem leitura da Etapa — segue com o aviso genérico
-    }
-  }
+  // canônica). A Etapa NUNCA retrocede — informa a atual, já lida antes.
+  const current = antes ?? await lerEtapa().catch(() => null);
   p.log.info(
     `#${issueNumber} não foi movida: a Etapa nunca retrocede, e ela já está em ` +
     `${chalk.bold(current || `"${stage}" ou etapa posterior`)}.`

package/src/commands/order.mjs

@@ -39,6 +39,37 @@ export function featureLabel(feature) {
   return `#${feature?.number} ${curto}`.trim();
 }
 
+/**
+ * Divergências de milestone entre a Feature e suas Stories (função PURA).
+ *
+ * O `order` é o detector do pós-apply, e até aqui ele só checava a Etapa
+ * (`Etapa: —`). Milestone tem o mesmo modo de falha: o apply herda a do pai
+ * (resolveInheritedMilestone), mas issues criadas antes dessa herança — ou com
+ * ela falhando — nascem sem milestone, invisíveis em qualquer visão de release,
+ * e ninguém percebe porque o passo sai verde. Foi assim que ~230 issues
+ * nasceram órfãs.
+ *
+ * Feature sem milestone não gera aviso: não há referência de comparação, e o
+ * repositório pode simplesmente não usar milestones.
+ *
+ * @param {{number?: number, title?: string}|null} featureMilestone
+ * @param {Array<{number: number, milestone?: {number: number, title: string}|null}>} stories
+ * @returns {string[]} uma linha de aviso por Story divergente
+ */
+export function milestoneMismatches(featureMilestone, stories = []) {
+  if (!Number.isInteger(featureMilestone?.number)) return [];
+  const ref = featureMilestone.title || `#${featureMilestone.number}`;
+  const out = [];
+  for (const s of stories) {
+    if (!Number.isInteger(s?.milestone?.number)) {
+      out.push(`#${s.number} está SEM milestone — a Feature está em "${ref}".`);
+    } else if (s.milestone.number !== featureMilestone.number) {
+      out.push(`#${s.number} está em "${s.milestone.title || `#${s.milestone.number}`}", mas a Feature está em "${ref}".`);
+    }
+  }
+  return out;
+}
+
 /**
  * O mapa de execução de várias Features (função PURA).
  *
@@ -350,5 +381,16 @@ export async function order({ feature: featureArg } = {}) {
     p.log.warn('Dependências fora de ordem:\n' + outOfOrder.map(w => `  • ${w}`).join('\n'));
   }
 
+  // 7. Milestone das Stories contra a da Feature — a outra órfã do pós-apply.
+  const milestoneWarns = milestoneMismatches(featureIssue.milestone, stories);
+  if (milestoneWarns.length > 0) {
+    p.log.warn(
+      chalk.yellow.bold('⚠ Milestone divergente da Feature:') + '\n' +
+      milestoneWarns.map(w => `  • ${w}`).join('\n') + '\n' +
+      'Story fora do milestone da Feature some de toda visão de release. ' +
+      'Corrija na issue (gh issue edit <n> --milestone "<título>").'
+    );
+  }
+
   p.outro(`${chalk.green('✓')} ${sorted.length} de ${enriched.length} story(ies) ordenada(s).`);
 }