@spec-wave/cli 0.34.1 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -12,7 +12,9 @@
12
12
  // perigoso.
13
13
 
14
14
  import { execSync } from 'node:child_process';
15
- import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
15
+ import {
16
+ existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync, rmSync, copyFileSync, statSync,
17
+ } from 'node:fs';
16
18
  import path from 'node:path';
17
19
  import chalk from 'chalk';
18
20
 
@@ -34,11 +36,13 @@ import { parseQaPlanDoc, resolveTargetScenarios } from '../lib/qa-plan-doc.mjs';
34
36
  import {
35
37
  qaExecutionGate, greenTargetStage, storyCanAdvance, featureCanAdvanceQa,
36
38
  extractRegressionSection, renderQaCommand, buildQaContext, qaProcessEnv,
39
+ resolveQaEvidenceConfig,
37
40
  } from '../lib/qa-exec.mjs';
38
41
  import { pushWithRebase } from '../lib/git-retry.mjs';
39
42
  import {
40
43
  aggregateVerdict, validateQaResults, combineWithPrevious, parseLastQaReport,
41
44
  renderQaReport, renderQaBugDoc, qaOriginMarker, matchesQaOrigin, shortSha,
45
+ evidenceScenarioDir, evidenceMediaUrl, QA_EVIDENCE_MAX_BYTES,
42
46
  } from '../lib/qa-report.mjs';
43
47
  import {
44
48
  CONFIG_FILE, STAGE_QA, STAGE_UAT, STAGE_READY, PROGRESS_TODO, PROGRESS_IN_PROGRESS,
@@ -103,24 +107,105 @@ function headShaOf(root) {
103
107
  }
104
108
  }
105
109
 
106
- // Commit LOCAL escopado ao arquivo — o `qa` roda no checkout do usuário, e o
107
- // bug.md de reprovação é conteúdo determinístico produzido aqui mesmo. Nunca
108
- // varre o index: `git commit -- <path>` só leva o que este comando escreveu.
109
- function commitLocalFile(root, fileRel, message) {
110
+ // Commit LOCAL escopado ao caminho (arquivo OU diretório) — o `qa` roda no
111
+ // checkout do usuário, e tanto o bug.md de reprovação quanto a evidência visual
112
+ // são conteúdo produzido aqui mesmo. Nunca varre o index: `git commit -- <path>`
113
+ // só leva o que este comando escreveu. `git add -- <dir>` também registra as
114
+ // remoções dentro dele, que é como a re-execução substitui a evidência antiga.
115
+ //
116
+ // Devolve o SHA curto do commit (ou do HEAD, quando não havia nada a commitar
117
+ // — conteúdo idêntico é no-op, não falha), ou null quando o commit falhou.
118
+ function commitLocalPath(root, rel, message) {
110
119
  const cwd = root || process.cwd();
111
120
  try {
112
- execSync(`git add -- ${JSON.stringify(fileRel)}`, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
113
- execSync(`git commit -m ${JSON.stringify(message)} -- ${JSON.stringify(fileRel)}`, {
114
- cwd, stdio: ['ignore', 'pipe', 'pipe'],
115
- });
116
- return true;
121
+ execSync(`git add -A -- ${JSON.stringify(rel)}`, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
122
+ const staged = execSync(`git diff --cached --name-only -- ${JSON.stringify(rel)}`, {
123
+ cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'],
124
+ }).trim();
125
+ if (staged) {
126
+ execSync(`git commit -m ${JSON.stringify(message)} -- ${JSON.stringify(rel)}`, {
127
+ cwd, stdio: ['ignore', 'pipe', 'pipe'],
128
+ });
129
+ }
130
+ return headShaOf(root) || 'HEAD';
117
131
  } catch (err) {
118
132
  console.warn(chalk.yellow(
119
- `⚠️ ${fileRel} escrito, mas o commit local falhou (${String(err.message).split('\n')[0]}) — ` +
133
+ `⚠️ ${rel} escrito, mas o commit local falhou (${String(err.message).split('\n')[0]}) — ` +
120
134
  'commite-o você mesmo.'
121
135
  ));
122
- return false;
136
+ return null;
137
+ }
138
+ }
139
+
140
+ // Publica a evidência visual (vídeo/foto) que o executor deixou no staging:
141
+ // copia cada arquivo declarado em `evidenceFiles` para o diretório versionado
142
+ // (`docs/features/<slug>/qa/cenario-<n>/` ou `docs/bugs/<slug>/qa/...`), num
143
+ // commit ÚNICO, e empurra. Roda ANTES do roteamento por veredito, para que o
144
+ // bug.md de uma reprova já possa linkar o caminho publicado.
145
+ //
146
+ // Evidência é ENRIQUECIMENTO, nunca o canal do veredito: arquivo declarado mas
147
+ // ausente, acima do teto, commit ou push rejeitado → aviso e segue. Um `fail`
148
+ // real NUNCA vira `blocked` por causa de um vídeo que não subiu.
149
+ //
150
+ // Cada `cenario-<n>` EXECUTADO é limpo antes da cópia: a pasta reflete a última
151
+ // corrida, mesmo quando ela não gravou nada (evidência velha ao lado de veredito
152
+ // novo seria pior que pasta vazia). Cenários fora do alvo (`--only`) não são
153
+ // tocados — herdam links do relatório anterior.
154
+ //
155
+ // Muta `results[i].evidenceFiles` para os caminhos PUBLICADOS (relativos à raiz
156
+ // do repo); devolve o sha que os serve, ou null quando nada foi publicado.
157
+ //
158
+ // Exportada para o teste de integração em repositório temporário; `push` é
159
+ // injetável pelo mesmo motivo (o teste não tem remoto).
160
+ export async function publishEvidence({
161
+ root, results, stagingAbs, targetRel, targetAbs, push = pushWithRebase,
162
+ }) {
163
+ const cwd = root || process.cwd();
164
+ let copied = 0;
165
+ let removed = 0;
166
+ for (const r of results) {
167
+ const scenarioRel = `${targetRel}/${evidenceScenarioDir(r.numero)}`;
168
+ const scenarioAbs = path.join(targetAbs, evidenceScenarioDir(r.numero));
169
+ if (existsSync(scenarioAbs)) {
170
+ rmSync(scenarioAbs, { recursive: true, force: true });
171
+ removed += 1;
172
+ }
173
+ const published = [];
174
+ for (const name of r.evidenceFiles || []) {
175
+ const src = path.join(stagingAbs, evidenceScenarioDir(r.numero), name);
176
+ if (!existsSync(src)) {
177
+ console.warn(chalk.yellow(`⚠️ Cenário ${r.numero}: evidência "${name}" declarada mas ausente em ${path.relative(cwd, src)} — ignorada.`));
178
+ continue;
179
+ }
180
+ const size = statSync(src).size;
181
+ if (size > QA_EVIDENCE_MAX_BYTES) {
182
+ console.warn(chalk.yellow(
183
+ `⚠️ Cenário ${r.numero}: "${name}" tem ${(size / 1024 / 1024).toFixed(1)} MB, acima do teto de ` +
184
+ `${QA_EVIDENCE_MAX_BYTES / 1024 / 1024} MB que a UI serve — não publicada. Grave clipes mais curtos/leves.`
185
+ ));
186
+ continue;
187
+ }
188
+ mkdirSync(scenarioAbs, { recursive: true });
189
+ copyFileSync(src, path.join(scenarioAbs, name));
190
+ published.push(`${scenarioRel}/${name}`);
191
+ copied += 1;
192
+ }
193
+ r.evidenceFiles = published;
194
+ }
195
+ if (copied === 0 && removed === 0) return null;
196
+
197
+ const sha = commitLocalPath(root, targetRel,
198
+ `docs: evidência visual do QA em ${targetRel} (${copied} arquivo(s)) [spec-wave]`);
199
+ if (!sha) return null;
200
+ if (copied > 0) console.log(`Evidência visual publicada em ${chalk.cyan(targetRel)}/ (${copied} arquivo(s), commit ${sha}).`);
201
+ const pushed = await push({ cwd });
202
+ if (!pushed.ok) {
203
+ console.warn(chalk.yellow(
204
+ `⚠️ Evidência commitada, mas o push foi rejeitado após ${pushed.attempts} tentativa(s): ` +
205
+ `${String(pushed.error).split('\n')[0]} — os links do relatório só vão resolver depois do seu push.`
206
+ ));
123
207
  }
208
+ return headShaOf(root) || sha;
124
209
  }
125
210
 
126
211
  function parseOnly(only) {
@@ -230,10 +315,12 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
230
315
  let qaPlanRel = null;
231
316
  let specRel = null;
232
317
  let featureStories = []; // Stories da Feature (modo Feature — o verde as aprova uma a uma)
318
+ let evidenceTarget = null; // { rel, abs } — onde a evidência visual é publicada
233
319
 
234
320
  if (type === 'Bug') {
235
- const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
321
+ const { fileRel, fileAbs, qaEvidenceDirRel, qaEvidenceDirAbs } = bugDocPaths(issue.title, root);
236
322
  qaPlanRel = fileRel;
323
+ evidenceTarget = { rel: qaEvidenceDirRel, abs: qaEvidenceDirAbs };
237
324
  if (!existsSync(fileAbs)) {
238
325
  const achado = await loadArtifact({
239
326
  token, owner, repo, root, pathRel: fileRel, doc: 'bug', issueNumber: number,
@@ -273,6 +360,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
273
360
  const paths = featureDocPaths(root, { title: feature.title }, 'Feature');
274
361
  qaPlanRel = paths['qa-plan'].rel;
275
362
  specRel = paths.spec.rel;
363
+ evidenceTarget = paths.qaEvidenceDir;
276
364
  const plano = await loadArtifact({
277
365
  token, owner, repo, root, pathRel: qaPlanRel, doc: 'qa-plan', issueNumber: feature.number,
278
366
  }).catch(() => null);
@@ -369,6 +457,11 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
369
457
  const resultFile = path.join(WORK_DIR, `qa-result-${number}.json`);
370
458
  const contextAbs = path.join(root || process.cwd(), contextFile);
371
459
  const resultAbs = path.join(root || process.cwd(), resultFile);
460
+ // Staging da evidência visual — mesmo padrão do resultado: gitignored, limpo
461
+ // antes de cada corrida (vídeo velho não pode virar evidência nova).
462
+ const evidenceDir = path.join(WORK_DIR, `qa-evidence-${number}`);
463
+ const evidenceAbs = path.join(root || process.cwd(), evidenceDir);
464
+ const evidence = resolveQaEvidenceConfig(config?.qa);
372
465
 
373
466
  const context = buildQaContext({
374
467
  type, issue: { number, title: issue.title }, stage,
@@ -376,9 +469,11 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
376
469
  comments: commentGroups, pullRequests,
377
470
  setup: config?.qa?.setup || null,
378
471
  resultFile,
472
+ evidenceDir, evidence, env: config?.qa?.env || null,
379
473
  });
380
474
  writeFileSync(contextAbs, context);
381
475
  if (existsSync(resultAbs)) unlinkSync(resultAbs); // resultado velho não pode virar veredito novo
476
+ if (!dryRun) rmSync(evidenceAbs, { recursive: true, force: true });
382
477
 
383
478
  const template = process.env.SPEC_WAVE_QA_CMD || config?.qa?.command;
384
479
  const vars = {
@@ -479,6 +574,25 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
479
574
  }
480
575
  }
481
576
 
577
+ // headSha = o commit TESTADO (vai no marcador do relatório). O commit da
578
+ // evidência vem depois e só serve os links.
579
+ const headSha = headShaOf(root);
580
+
581
+ // ── Evidência visual → repositório (antes do veredito, nunca o altera) ─────
582
+ let evidenceBase = null;
583
+ try {
584
+ const evidenceSha = evidenceTarget
585
+ ? await publishEvidence({
586
+ root, results, stagingAbs: evidenceAbs, targetRel: evidenceTarget.rel, targetAbs: evidenceTarget.abs,
587
+ })
588
+ : null;
589
+ if (evidenceSha) evidenceBase = { owner, repo, sha: evidenceSha };
590
+ } catch (err) {
591
+ console.warn(chalk.yellow(`⚠️ Falha ao publicar a evidência visual: ${err.message} — seguindo sem ela.`));
592
+ for (const r of results) r.evidenceFiles = [];
593
+ }
594
+ rmSync(evidenceAbs, { recursive: true, force: true });
595
+
482
596
  // ── Estado acumulado e veredito ────────────────────────────────────────────
483
597
  const { combined, pendingNumbers } = combineWithPrevious({
484
598
  executed: results,
@@ -487,14 +601,13 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
487
601
  });
488
602
  let verdict = aggregateVerdict(combined);
489
603
  const planSha = shortSha(planContent);
490
- const headSha = headShaOf(root);
491
604
  const byNumero = new Map(scenarios.map(s => [s.numero, s]));
492
605
 
493
606
  console.log(`\nVeredito agregado: ${chalk.bold(verdict)} (${combined.length} cenário(s) no escopo, ${results.length} executado(s) agora).`);
494
607
 
495
608
  const outcome = {
496
609
  token, projectToken, owner, repo, root, config, board, issue, number, type, feature,
497
- featureStories,
610
+ featureStories, evidenceBase,
498
611
  };
499
612
 
500
613
  let bugs = [];
@@ -579,14 +692,18 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
579
692
  // ── Desfechos ────────────────────────────────────────────────────────────────
580
693
 
581
694
  async function postReport({
582
- token, owner, repo, number, type, run, verdict, planSha, headSha,
695
+ token, owner, repo, number, type, run, verdict, planSha, headSha, evidenceBase,
583
696
  combined, pendingNumbers, bugs, trailer,
584
697
  }) {
698
+ // Cenário herdado (`--only`) traz links de uma corrida anterior, servidos
699
+ // pelo commit daquela corrida — sem a base desta, cai na branch default.
700
+ const base = evidenceBase || { owner, repo, sha: 'HEAD' };
585
701
  const markdown = renderQaReport({
586
702
  issue: number,
587
703
  scope: `${type} #${number}`,
588
704
  run, verdict, planSha, headSha,
589
705
  results: combined,
706
+ evidenceBase: base,
590
707
  bugs,
591
708
  pendingNumbers,
592
709
  trailer,
@@ -613,7 +730,7 @@ async function stayInQa({ projectToken, board, issue }) {
613
730
  // estado que a spec proíbe.
614
731
  async function openBugsForFailures({
615
732
  token, projectToken, owner, repo, root, board,
616
- failed, byNumero, severity, headSha, qaPlanRel, feature, type, number,
733
+ failed, byNumero, severity, headSha, qaPlanRel, feature, evidenceBase,
617
734
  }) {
618
735
  const bugs = [];
619
736
  const pushFailures = [];
@@ -640,10 +757,13 @@ async function openBugsForFailures({
640
757
  matchesQaOrigin(c.body, { issue: storyNumber, cenario: scenario.numero }));
641
758
  if (existing) {
642
759
  console.log(`Cenário ${scenario.numero} já tem Bug aberto (#${existing.number}) — comentando nele.`);
760
+ const midia = (r.evidenceFiles || []).length > 0 && evidenceBase
761
+ ? `\n\n**Evidência visual:** ${r.evidenceFiles.map(f => `[${f.split('/').pop()}](${evidenceMediaUrl(evidenceBase.owner, evidenceBase.repo, evidenceBase.sha, f)})`).join(' · ')}`
762
+ : '';
643
763
  await commentOnIssue(token, owner, repo, existing.number,
644
764
  `🧪 **O cenário ${scenario.numero} da Story #${storyNumber} reprovou de novo** ` +
645
765
  `(${headSha ? `commit \`${headSha}\`` : 'nova execução'}).\n\n` +
646
- `**Evidência:** ${r.evidencia || '(sem evidência registrada)'}`
766
+ `**Evidência:** ${r.evidencia || '(sem evidência registrada)'}${midia}`
647
767
  ).catch(() => {});
648
768
  bugs.push({ number: existing.number, cenario: scenario.numero, existing: true });
649
769
  continue;
@@ -675,6 +795,7 @@ async function openBugsForFailures({
675
795
  mkdirSync(dirAbs, { recursive: true });
676
796
  writeFileSync(fileAbs, renderQaBugDoc({
677
797
  title: resumo, scenario, evidence: r.evidencia, severity, headSha,
798
+ evidenceFiles: r.evidenceFiles || [], evidenceBase,
678
799
  featureNumber: feature?.number ?? null,
679
800
  }));
680
801
  } catch (err) {
@@ -682,7 +803,7 @@ async function openBugsForFailures({
682
803
  pushFailures.push({ numero: r.numero, error: `escrita do ${fileRel} falhou: ${err.message}` });
683
804
  continue;
684
805
  }
685
- const committed = commitLocalFile(root, fileRel,
806
+ const committed = commitLocalPath(root, fileRel,
686
807
  `docs: gera ${fileRel} (reprovação de QA, cenário ${scenario.numero} da Story #${storyNumber}) [spec-wave]`);
687
808
  if (!committed) {
688
809
  pushFailures.push({ numero: r.numero, error: `commit do ${fileRel} falhou` });
@@ -18,12 +18,15 @@ import { slugify } from './slugify.mjs';
18
18
  *
19
19
  * @param {string} title título da issue (com ou sem o prefixo [BUG])
20
20
  * @param {string} [root] raiz do repositório; ausente = process.cwd()
21
- * @returns {{ slug: string, dirRel: string, fileRel: string, dirAbs: string, fileAbs: string }}
21
+ * @returns {{ slug: string, dirRel: string, fileRel: string, dirAbs: string, fileAbs: string, qaEvidenceDirRel: string, qaEvidenceDirAbs: string }}
22
22
  */
23
23
  export function bugDocPaths(title, root = null) {
24
24
  const slug = slugify(title);
25
25
  const dirRel = `docs/bugs/${slug}`;
26
26
  const fileRel = `${dirRel}/bug.md`;
27
+ // Evidência visual do `qa <bug>` (Teste de Regressão = cenário 1), no mesmo
28
+ // desenho de docs/features/<slug>/qa/ — ver featureDocPaths().
29
+ const qaEvidenceDirRel = `${dirRel}/qa`;
27
30
  const base = root || process.cwd();
28
31
  return {
29
32
  slug,
@@ -31,6 +34,8 @@ export function bugDocPaths(title, root = null) {
31
34
  fileRel,
32
35
  dirAbs: path.resolve(base, dirRel),
33
36
  fileAbs: path.resolve(base, fileRel),
37
+ qaEvidenceDirRel,
38
+ qaEvidenceDirAbs: path.resolve(base, qaEvidenceDirRel),
34
39
  };
35
40
  }
36
41
 
@@ -35,7 +35,7 @@ export function resolveDocDir(root, issue, type) {
35
35
  * @param {string|null} root
36
36
  * @param {{title?: string}} issue
37
37
  * @param {string|null} [type]
38
- * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition, 'qa-plan'}} cada documento com {rel, abs}
38
+ * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition, 'qa-plan', 'dependency-map', qaEvidenceDir}} cada documento com {rel, abs}
39
39
  */
40
40
  export function featureDocPaths(root, issue, type) {
41
41
  const { slug, rel, dir } = resolveDocDir(root, issue, type);
@@ -54,5 +54,10 @@ export function featureDocPaths(root, issue, type) {
54
54
  // pelo decompose --apply, atualizado pelo `order --sync`, lido por
55
55
  // order/implement/merge/qa-lead no lugar de N chamadas de API.
56
56
  'dependency-map': doc('dependency-map.json'),
57
+ // Evidência visual da execução do QA (vídeo/foto por cenário), publicada
58
+ // pelo `qa <issue>` em `qa/cenario-<n>/` — <n> é o número POSICIONAL do
59
+ // cenário no qa-plan.md (o mesmo do `--only`). CONTRATO com a UI: arquivos
60
+ // planos dentro de cada `cenario-<n>/`, sem subpasta.
61
+ qaEvidenceDir: doc('qa'),
57
62
  };
58
63
  }
@@ -0,0 +1,54 @@
1
+ // Vínculo PR → issue: quais issues um PR declara implementar.
2
+ //
3
+ // Mora no lib porque três consumidores dependem da MESMA régua e não podem
4
+ // divergir: o `code-review` (o que mover no board), o `merge` (achar o PR de
5
+ // cada Story numa pilha) e o desrascunho (quais PRs são desta Feature). Estava
6
+ // em commands/code-review.mjs; quando lib/pr-ready.mjs passou a precisar dele,
7
+ // o import formava ciclo (code-review → pr-ready → code-review).
8
+
9
+ // Vínculo EXPLÍCITO: o verbo é obrigatório. `Relacionado: #10` e `#10` solto
10
+ // deixaram de contar — referência cruzada em PR é prática comum (uma PR de
11
+ // documentação citando três Features moveu as três para 👀 Code Review, e uma
12
+ // delas nem plano tinha). Aceita `#N`, `owner/repo#N` e a URL completa da issue.
13
+ const EXPLICIT_LINK_RE =
14
+ /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implement(?:s|ed)?)\b\s*:?\s+(?:https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/(\d+)|[\w.-]+\/[\w.-]+#(\d+)|#(\d+))/gi;
15
+
16
+ // Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`.
17
+ const ANY_MENTION_RE = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
18
+
19
+ // Blocos de código não são vínculo: um `Closes #12` dentro de um exemplo de
20
+ // commit message é documentação, não promessa.
21
+ function stripCodeBlocks(body) {
22
+ return String(body)
23
+ .replace(/^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[ \t]*$/gm, '\n')
24
+ .replace(/`[^`\n]*`/g, ' ');
25
+ }
26
+
27
+ /**
28
+ * Números de issues que o PR declara implementar (função PURA — testável).
29
+ *
30
+ * @param {string} body corpo do PR
31
+ * @param {object} [opts]
32
+ * @param {'explicit'|'any-mention'} [opts.linkMode='explicit']
33
+ * @returns {number[]} na ordem em que aparecem, sem repetição
34
+ */
35
+ export function extractIssueNumbers(body, { linkMode = 'explicit' } = {}) {
36
+ if (!body) return [];
37
+ const nums = new Set();
38
+ const text = stripCodeBlocks(body);
39
+ const re = linkMode === 'any-mention' ? ANY_MENTION_RE : EXPLICIT_LINK_RE;
40
+ re.lastIndex = 0;
41
+ for (const m of text.matchAll(re)) {
42
+ const n = parseInt(m.slice(1).find(Boolean) || '', 10);
43
+ if (n) nums.add(n);
44
+ }
45
+ return [...nums];
46
+ }
47
+
48
+ /**
49
+ * O `linkMode` configurado em `.spec-wave.json`, normalizado.
50
+ * Qualquer valor que não seja `any-mention` cai no padrão `explicit`.
51
+ */
52
+ export function resolveLinkMode(config) {
53
+ return config?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
54
+ }
@@ -0,0 +1,142 @@
1
+ // Rascunho → pronto para revisão: o sinal de que a Feature acabou.
2
+ //
3
+ // O `implement` manda abrir cada PR de Story em rascunho de propósito. Numa
4
+ // pilha (cada PR baseado no anterior), rascunho evita que o CI rode em cascata
5
+ // a cada rebase e — o que importa aqui — é a marca visível de que o dev-agent
6
+ // AINDA ESTÁ TRABALHANDO: ninguém revisa nem mergeia uma feature pela metade,
7
+ // porque o GitHub bloqueia o merge de rascunho.
8
+ //
9
+ // O que faltava era o outro lado do sinal. Tirar do rascunho era 100% manual,
10
+ // então um PR pronto ficava indistinguível de um PR abandonado no meio. Agora,
11
+ // quando a ÚLTIMA Story da Feature entra em Code Review — o mesmo instante em
12
+ // que a Feature avança de Etapa —, todos os PRs da Feature saem do rascunho de
13
+ // uma vez: a feature inteira fica pronta para review no mesmo momento.
14
+ //
15
+ // Decisão pura (planPrsToReady) + executor best-effort (markFeaturePrsReady),
16
+ // mesmo contrato de implement-board.mjs: falhar aqui NUNCA derruba a
17
+ // implementação, que a essa altura já está commitada.
18
+
19
+ import * as p from '@clack/prompts';
20
+ import { listIssuePullRequests, listOpenPullRequests, markPullRequestReadyForReview } from '../api/github-graphql.mjs';
21
+ import { extractIssueNumbers } from './pr-link.mjs';
22
+
23
+ /**
24
+ * Dos PRs coletados, quais devem sair do rascunho (função PURA — testável).
25
+ *
26
+ * Filtra por `isDraft` porque a mutation do GitHub ERRA num PR que já está
27
+ * pronto: sem o filtro, a segunda execução do implement (ou o destravamento de
28
+ * uma Feature que já avançou) encheria a saída de falhas que não são falhas.
29
+ *
30
+ * PR fechado ou já mergeado fica de fora: não há rascunho a desfazer, e mexer
31
+ * num PR fechado só produziria erro. Sem `id` (node ID) também sai — é o que a
32
+ * mutation exige, e um PR sem ele veio de uma fonte que não sabemos operar.
33
+ *
34
+ * @param {Array<{id?:string, number:number, state?:string, merged?:boolean, isDraft?:boolean}>} prs
35
+ * @returns {Array<object>} sem repetição, em ordem crescente de número
36
+ */
37
+ export function planPrsToReady(prs = []) {
38
+ const out = new Map();
39
+ for (const pr of prs) {
40
+ if (!pr?.id || !pr.isDraft || pr.merged) continue;
41
+ if (pr.state && pr.state !== 'open') continue;
42
+ if (!out.has(pr.number)) out.set(pr.number, pr);
43
+ }
44
+ return [...out.values()].sort((a, b) => a.number - b.number);
45
+ }
46
+
47
+ /**
48
+ * Todos os PRs da Feature, pelas duas fontes de vínculo que o `merge` usa.
49
+ *
50
+ * O vínculo nativo do GitHub (closedByPullRequestsReferences) só é registrado
51
+ * quando a base do PR é a branch default — numa pilha, só o PR de baixo tem.
52
+ * Os de cima são invisíveis por ali, e é justamente a pilha inteira que precisa
53
+ * sair do rascunho. Por isso o corpo (`Closes #N`, mesmo parser do code-review)
54
+ * é a fonte primária aqui, e o vínculo nativo entra como complemento — ele pega
55
+ * o PR ligado pela UI, sem `Closes` no corpo.
56
+ *
57
+ * @param {object} params
58
+ * @param {number[]} params.issueNumbers Feature + Stories: um PR que fecha
59
+ * qualquer uma delas é PR desta Feature.
60
+ * @param {Array<{nodeId:string}>} [params.issueNodes] para o vínculo nativo
61
+ * @returns {Promise<Array<object>>} PRs sem repetição
62
+ */
63
+ export async function collectFeaturePullRequests({
64
+ token, owner, repo, issueNumbers = [], issueNodes = [], linkMode = 'explicit',
65
+ }) {
66
+ const alvo = new Set(issueNumbers);
67
+ const byNumber = new Map();
68
+
69
+ const abertos = await listOpenPullRequests(token, owner, repo).catch(() => []);
70
+ for (const pr of abertos) {
71
+ const fecha = extractIssueNumbers(pr.body || '', { linkMode });
72
+ if (fecha.some(n => alvo.has(n))) byNumber.set(pr.number, pr);
73
+ }
74
+
75
+ for (const node of issueNodes) {
76
+ if (!node?.nodeId) continue;
77
+ for (const pr of await listIssuePullRequests(token, node.nodeId).catch(() => [])) {
78
+ if (!byNumber.has(pr.number)) byNumber.set(pr.number, pr);
79
+ }
80
+ }
81
+ return [...byNumber.values()];
82
+ }
83
+
84
+ /**
85
+ * Tira do rascunho todos os PRs da Feature. Best-effort: qualquer falha vira
86
+ * warn e a implementação segue — o trabalho já está commitado, e um PR que não
87
+ * saiu do rascunho é recuperável à mão (o warn diz quais).
88
+ *
89
+ * Com `dryRun`, apenas ANUNCIA: nada é escrito no GitHub.
90
+ *
91
+ * @param {object} params
92
+ * @param {{number:number, nodeId?:string}} params.feature
93
+ * @param {Array<{number:number, nodeId?:string}>} params.stories todas as
94
+ * Stories da Feature — as recém-concluídas E as que já estavam em Code Review
95
+ * @returns {Promise<number[]>} números dos PRs marcados como prontos
96
+ */
97
+ export async function markFeaturePrsReady({
98
+ token, owner, repo, feature, stories = [], dryRun = false, log = p.log, linkMode = 'explicit',
99
+ }) {
100
+ if (!token || !owner || !repo || !feature?.number) return [];
101
+ try {
102
+ const prs = await collectFeaturePullRequests({
103
+ token, owner, repo, linkMode,
104
+ issueNumbers: [feature.number, ...stories.map(s => s.number)].filter(Boolean),
105
+ issueNodes: [feature, ...stories],
106
+ });
107
+ const alvos = planPrsToReady(prs);
108
+ if (alvos.length === 0) return [];
109
+
110
+ if (dryRun) {
111
+ log.info(
112
+ `PRs (dry-run): ${alvos.map(pr => `#${pr.number}`).join(', ')} sairiam do rascunho ` +
113
+ `(Feature #${feature.number} pronta para review) — não aplicado`
114
+ );
115
+ return [];
116
+ }
117
+
118
+ const marcados = [];
119
+ const falhas = [];
120
+ for (const pr of alvos) {
121
+ try {
122
+ await markPullRequestReadyForReview(token, pr.id);
123
+ marcados.push(pr.number);
124
+ } catch (err) {
125
+ falhas.push(`#${pr.number} (${err.message})`);
126
+ }
127
+ }
128
+ if (marcados.length > 0) {
129
+ log.success(
130
+ `${marcados.length} PR(s) da Feature #${feature.number} prontos para revisão: ` +
131
+ marcados.map(n => `#${n}`).join(', ')
132
+ );
133
+ }
134
+ if (falhas.length > 0) {
135
+ log.warn(`PRs que continuam em rascunho — marque como prontos à mão: ${falhas.join(', ')}`);
136
+ }
137
+ return marcados;
138
+ } catch (err) {
139
+ log.warn(`PRs da Feature #${feature.number} seguem em rascunho (${err.message}) — marque como prontos à mão.`);
140
+ return [];
141
+ }
142
+ }
@@ -10,6 +10,43 @@ import {
10
10
  LABEL_QA, LABEL_QA_READY, LABEL_QA_APPROVED, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN,
11
11
  labelNames,
12
12
  } from '../config.mjs';
13
+ import { QA_EVIDENCE_EXTENSIONS, QA_EVIDENCE_MAX_BYTES, evidenceScenarioDir } from './qa-report.mjs';
14
+
15
+ /** Plataformas do bloco `qa` — decide qual ferramenta grava a evidência visual. */
16
+ export const QA_PLATFORMS = ['web', 'mobile'];
17
+
18
+ /**
19
+ * Configuração de evidência visual, resolvida do bloco `qa` (função PURA).
20
+ *
21
+ * `qa.platform` ausente → `web` (repositórios existentes não mudam de
22
+ * comportamento). A ferramenta vem de `qa.web.evidence` (`playwright` | `none`)
23
+ * ou `qa.mobile.evidence` (`maestro` | `none`); ausente = a ferramenta padrão
24
+ * da plataforma. Não há camada de validação: valor desconhecido é tratado
25
+ * como `none` e o `doctor` é quem aponta.
26
+ *
27
+ * `explicit` diz se o usuário PEDIU a evidência (declarou `platform` ou
28
+ * `<platform>.evidence`) ou se ela só existe por default — o `doctor` avisa da
29
+ * ferramenta ausente no primeiro caso e apenas informa no segundo, para um
30
+ * repositório que nunca ouviu falar de evidência visual não ganhar um aviso.
31
+ *
32
+ * @param {object|null} [qa] bloco `qa` do .spec-wave.json
33
+ * @returns {{ platform: 'web'|'mobile', tool: 'playwright'|'maestro'|null, appId: string|null, device: string|null, explicit: boolean }}
34
+ */
35
+ export function resolveQaEvidenceConfig(qa = null) {
36
+ const platform = QA_PLATFORMS.includes(qa?.platform) ? qa.platform : 'web';
37
+ const block = platform === 'mobile' ? (qa?.mobile || {}) : (qa?.web || {});
38
+ const wanted = block.evidence ?? (platform === 'mobile' ? 'maestro' : 'playwright');
39
+ const tool = (platform === 'mobile' && wanted === 'maestro') || (platform === 'web' && wanted === 'playwright')
40
+ ? wanted
41
+ : null;
42
+ return {
43
+ platform,
44
+ tool,
45
+ appId: platform === 'mobile' ? (block.appId || null) : null,
46
+ device: platform === 'mobile' ? (block.device || null) : null,
47
+ explicit: qa?.platform != null || block.evidence != null,
48
+ };
49
+ }
13
50
 
14
51
  /** Tipos que passam pela execução de QA (spec §3). */
15
52
  export const QA_RUNNABLE_TYPES = ['Feature', 'Story', 'Bug'];
@@ -235,11 +272,18 @@ export function qaProcessEnv(configEnv = {}, processEnv = {}) {
235
272
  * @param {Array<{number:number, state:string, merged:boolean}>} [params.pullRequests]
236
273
  * @param {string|null} [params.setup] `qa.setup` do .spec-wave.json
237
274
  * @param {string} params.resultFile caminho do JSON de resultados
275
+ * @param {string|null} [params.evidenceDir] diretório de STAGING da evidência
276
+ * visual (`.spec-wave/qa-evidence-<n>`); null = sem seção de evidência
277
+ * @param {{platform:string, tool:string|null, appId?:string|null, device?:string|null}} [params.evidence]
278
+ * saída de resolveQaEvidenceConfig()
279
+ * @param {Record<string,string>} [params.env] `qa.env` (BASE_URL etc.), para o
280
+ * executor não reler o .spec-wave.json
238
281
  * @returns {string} markdown
239
282
  */
240
283
  export function buildQaContext({
241
284
  type, issue, stage = null, scenarios = [], specRel = null, qaPlanRel = null,
242
285
  comments = [], pullRequests = [], setup = null, resultFile,
286
+ evidenceDir = null, evidence = null, env = null,
243
287
  } = {}) {
244
288
  const lines = [];
245
289
  lines.push(`# Contexto de QA — ${type} #${issue.number}`);
@@ -266,6 +310,7 @@ export function buildQaContext({
266
310
  lines.push(JSON.stringify({
267
311
  scenarios: scenarios.slice(0, 1).map(s => ({
268
312
  cenario: s.numero, verdict: 'pass | fail | blocked', evidencia: 'comando + saída + status',
313
+ ...(evidenceDir && evidence?.tool ? { evidenceFiles: ['gravacao.webm', 'final.png'] } : {}),
269
314
  })),
270
315
  }, null, 2));
271
316
  lines.push('```');
@@ -275,6 +320,34 @@ export function buildQaContext({
275
320
  lines.push('- `fail` exige `evidencia` não vazia (ela vira o bug.md do Bug aberto);');
276
321
  lines.push('- `blocked` exige `blockedReason`, um de: `ambiente` · `setup-falhou` · `massa-de-dados` · `dependencia-nao-entregue` · `bloqueado-por-bug` · `credencial` · `outro` (este exige `evidencia` com o motivo).');
277
322
 
323
+ if (evidenceDir) {
324
+ const tool = evidence?.tool || null;
325
+ lines.push('');
326
+ lines.push('## Evidência visual (vídeo/foto) — OPCIONAL, nunca substitui `evidencia`');
327
+ lines.push('');
328
+ lines.push(`**Plataforma:** ${evidence?.platform || 'web'} · **Ferramenta:** ${tool || 'nenhuma (evidência visual desligada)'}` +
329
+ (evidence?.appId ? ` · **appId:** \`${evidence.appId}\`` : '') +
330
+ (evidence?.device ? ` · **device:** \`${evidence.device}\`` : ''));
331
+ const envEntries = Object.entries(env || {}).filter(([, v]) => v != null && v !== '');
332
+ if (envEntries.length > 0) {
333
+ lines.push(`**Ambiente (\`qa.env\`):** ${envEntries.map(([k, v]) => `${k}=\`${v}\``).join(' · ')}`);
334
+ }
335
+ if (tool) {
336
+ lines.push('');
337
+ lines.push(tool === 'maestro'
338
+ ? '- Para cada cenário, sintetize um flow **Maestro** mínimo a partir dos Passos/Critério e rode-o com gravação de vídeo; tire ao menos uma captura do estado final. Confira as flags da versão instalada (`maestro --help`, `maestro record --help`) — elas mudam entre versões.'
339
+ : '- Para cada cenário, sintetize um script **Playwright** descartável (fora do repositório ou em arquivo temporário, NUNCA commitado) com vídeo e screenshot habilitados e rode-o contra a `BASE_URL`. Confira a API da versão instalada (`npx playwright --version`) — a gravação muda entre versões.');
340
+ lines.push(`- Grave em \`${evidenceDir}/${evidenceScenarioDir('<n>')}/\` (<n> = número POSICIONAL do cenário), arquivos PLANOS, sem subpasta.`);
341
+ lines.push(`- Nome: letras, dígitos, ponto, hífen, sublinhado (sem espaço, sem começar com ponto). Extensões aceitas: ${QA_EVIDENCE_EXTENSIONS.join(', ')}.`);
342
+ lines.push(`- **Teto: ${Math.round(QA_EVIDENCE_MAX_BYTES / 1024 / 1024)} MB por arquivo** — clipe curto e em baixa resolução (webm/mp4 comprimido; screenshot png/webp). Acima disso a CLI não publica.`);
343
+ lines.push('- Referencie cada arquivo em `evidenceFiles` do cenário (só o NOME, ex.: `"evidenceFiles": ["gravacao.webm", "final.png"]`). A CLI copia para o repositório e comita.');
344
+ lines.push('- Ferramenta ausente ou gravação que falhou **não é `blocked`**: execute o cenário do mesmo jeito e omita `evidenceFiles`. O texto em `evidencia` continua obrigatório nas mesmas regras.');
345
+ } else {
346
+ lines.push('');
347
+ lines.push('Evidência visual desligada para este repositório — não grave vídeo/foto; `evidenceFiles` deve ficar ausente.');
348
+ }
349
+ }
350
+
278
351
  if (setup) {
279
352
  lines.push('');
280
353
  lines.push('## Setup do ambiente (rode antes do primeiro cenário)');