@spec-wave/cli 0.34.2 → 1.0.1

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.
Files changed (52) hide show
  1. package/package.json +2 -2
  2. package/protocol/qa-result.v1.json +9 -0
  3. package/src/agent/anthropic-agent.mjs +35 -2
  4. package/src/api/github-graphql.mjs +60 -2
  5. package/src/api/github-rest.mjs +23 -0
  6. package/src/cli.mjs +23 -0
  7. package/src/commands/code-review.mjs +71 -60
  8. package/src/commands/decompose.mjs +75 -4
  9. package/src/commands/doctor.mjs +105 -4
  10. package/src/commands/implement.mjs +82 -10
  11. package/src/commands/init.mjs +147 -29
  12. package/src/commands/merge.mjs +56 -4
  13. package/src/commands/move.mjs +4 -7
  14. package/src/commands/order.mjs +2 -2
  15. package/src/commands/qa-run.mjs +140 -19
  16. package/src/commands/qa.mjs +22 -21
  17. package/src/commands/repair-stage.mjs +2 -5
  18. package/src/commands/story.mjs +2 -2
  19. package/src/commands/task.mjs +2 -2
  20. package/src/commands/triage.mjs +2 -5
  21. package/src/commands/update.mjs +31 -8
  22. package/src/commands/validate.mjs +2 -5
  23. package/src/commands/workspace.mjs +112 -0
  24. package/src/config.mjs +19 -0
  25. package/src/lib/artifact-pr.mjs +1 -1
  26. package/src/lib/bug-doc.mjs +6 -1
  27. package/src/lib/claude.mjs +4 -0
  28. package/src/lib/decomposition-doc.mjs +56 -3
  29. package/src/lib/dependency-map.mjs +3 -0
  30. package/src/lib/doc-paths.mjs +6 -1
  31. package/src/lib/flow-run.mjs +14 -3
  32. package/src/lib/pr-link.mjs +109 -0
  33. package/src/lib/pr-ready.mjs +146 -0
  34. package/src/lib/project-root.mjs +51 -0
  35. package/src/lib/qa-exec.mjs +73 -0
  36. package/src/lib/qa-report.mjs +172 -8
  37. package/src/lib/repo-role.mjs +102 -0
  38. package/src/lib/workspace.mjs +151 -0
  39. package/src/plugin/.claude-plugin/plugin.json +1 -1
  40. package/src/plugin/skills/decompose/SKILL.md +1 -0
  41. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  42. package/src/plugin/skills/implement/SKILL.md +2 -2
  43. package/src/plugin/skills/merge/SKILL.md +3 -2
  44. package/src/plugin/skills/qa/SKILL.md +6 -1
  45. package/src/plugin/skills/qa-executor/SKILL.md +43 -1
  46. package/src/plugin/skills/setup/SKILL.md +12 -0
  47. package/src/setup/files.mjs +35 -13
  48. package/src/templates/skill/SKILL.md +27 -5
  49. package/src/templates/skill/core.md +5 -1
  50. package/src/templates/workflows/code/code-review.yml +60 -0
  51. package/src/templates/workflows/code/qa.yml +59 -0
  52. package/src/templates/workflows/pr-events.yml +116 -0
@@ -0,0 +1,146 @@
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 { extractIssueRefs, hubIssueNumbers } 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
+ // `owner/repo` é o hub: as issues são dele e, por ora, os PRs listados também.
70
+ // Um `#N` solto num PR do hub é issue do hub; um `outro/repo#N` não é desta
71
+ // Feature — sem isso `acme/api#412` num PR do hub casaria a Story #412.
72
+ const hub = { owner, repo };
73
+ const abertos = await listOpenPullRequests(token, owner, repo).catch(() => []);
74
+ for (const pr of abertos) {
75
+ const fecha = hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo: hub, linkMode }), hub);
76
+ if (fecha.some(n => alvo.has(n))) byNumber.set(pr.number, pr);
77
+ }
78
+
79
+ for (const node of issueNodes) {
80
+ if (!node?.nodeId) continue;
81
+ for (const pr of await listIssuePullRequests(token, node.nodeId).catch(() => [])) {
82
+ if (!byNumber.has(pr.number)) byNumber.set(pr.number, pr);
83
+ }
84
+ }
85
+ return [...byNumber.values()];
86
+ }
87
+
88
+ /**
89
+ * Tira do rascunho todos os PRs da Feature. Best-effort: qualquer falha vira
90
+ * warn e a implementação segue — o trabalho já está commitado, e um PR que não
91
+ * saiu do rascunho é recuperável à mão (o warn diz quais).
92
+ *
93
+ * Com `dryRun`, apenas ANUNCIA: nada é escrito no GitHub.
94
+ *
95
+ * @param {object} params
96
+ * @param {{number:number, nodeId?:string}} params.feature
97
+ * @param {Array<{number:number, nodeId?:string}>} params.stories todas as
98
+ * Stories da Feature — as recém-concluídas E as que já estavam em Code Review
99
+ * @returns {Promise<number[]>} números dos PRs marcados como prontos
100
+ */
101
+ export async function markFeaturePrsReady({
102
+ token, owner, repo, feature, stories = [], dryRun = false, log = p.log, linkMode = 'explicit',
103
+ }) {
104
+ if (!token || !owner || !repo || !feature?.number) return [];
105
+ try {
106
+ const prs = await collectFeaturePullRequests({
107
+ token, owner, repo, linkMode,
108
+ issueNumbers: [feature.number, ...stories.map(s => s.number)].filter(Boolean),
109
+ issueNodes: [feature, ...stories],
110
+ });
111
+ const alvos = planPrsToReady(prs);
112
+ if (alvos.length === 0) return [];
113
+
114
+ if (dryRun) {
115
+ log.info(
116
+ `PRs (dry-run): ${alvos.map(pr => `#${pr.number}`).join(', ')} sairiam do rascunho ` +
117
+ `(Feature #${feature.number} pronta para review) — não aplicado`
118
+ );
119
+ return [];
120
+ }
121
+
122
+ const marcados = [];
123
+ const falhas = [];
124
+ for (const pr of alvos) {
125
+ try {
126
+ await markPullRequestReadyForReview(token, pr.id);
127
+ marcados.push(pr.number);
128
+ } catch (err) {
129
+ falhas.push(`#${pr.number} (${err.message})`);
130
+ }
131
+ }
132
+ if (marcados.length > 0) {
133
+ log.success(
134
+ `${marcados.length} PR(s) da Feature #${feature.number} prontos para revisão: ` +
135
+ marcados.map(n => `#${n}`).join(', ')
136
+ );
137
+ }
138
+ if (falhas.length > 0) {
139
+ log.warn(`PRs que continuam em rascunho — marque como prontos à mão: ${falhas.join(', ')}`);
140
+ }
141
+ return marcados;
142
+ } catch (err) {
143
+ log.warn(`PRs da Feature #${feature.number} seguem em rascunho (${err.message}) — marque como prontos à mão.`);
144
+ return [];
145
+ }
146
+ }
@@ -14,6 +14,7 @@
14
14
  import { existsSync, readFileSync } from 'node:fs';
15
15
  import path from 'node:path';
16
16
  import { CONFIG_FILE } from '../config.mjs';
17
+ import { configuredRole, declaredHub, parseRepoRef } from './repo-role.mjs';
17
18
 
18
19
  /**
19
20
  * Procura o .spec-wave.json em `cwd` e nos diretórios acima (função quase pura:
@@ -98,3 +99,53 @@ export function resolveRepoContext(cwd = process.cwd(), env = process.env) {
98
99
  error,
99
100
  };
100
101
  }
102
+
103
+ /**
104
+ * O contexto que TODO comando de fluxo quer: o repositório dono das issues e
105
+ * do board — o hub (RFC-005). Num hub (ou num config antigo, sem `role`) é o
106
+ * próprio repositório; num repo de código é o `hub` declarado no config.
107
+ *
108
+ * `self` continua sendo o repositório em que o comando roda — é o que um
109
+ * `#N` solto no corpo de um PR significa. Rodando no hub os dois coincidem.
110
+ *
111
+ * @param {string} [cwd=process.cwd()]
112
+ * @param {object} [env=process.env]
113
+ * @returns {{ owner: string|undefined, repo: string|undefined,
114
+ * self: { owner: string|undefined, repo: string|undefined },
115
+ * role: 'hub'|'code', root: string|null, config: object|null,
116
+ * error: string|null }}
117
+ */
118
+ export function resolveHubContext(cwd = process.cwd(), env = process.env) {
119
+ const ctx = resolveRepoContext(cwd, env);
120
+ const self = { owner: ctx.owner, repo: ctx.repo };
121
+ const role = configuredRole(ctx.config);
122
+ if (role !== 'code') return { ...ctx, self, role };
123
+ const hub = declaredHub(ctx.config);
124
+ if (!hub) {
125
+ return {
126
+ ...ctx, self, role, owner: undefined, repo: undefined,
127
+ error: `${CONFIG_FILE} declara role "code" mas não diz qual é o hub — esperado hub: { owner, repo }.`,
128
+ };
129
+ }
130
+ return { ...ctx, self, role, owner: hub.owner, repo: hub.repo };
131
+ }
132
+
133
+ /**
134
+ * Onde está o PR que um comando de board (`code-review`, `qa`) vai ler:
135
+ * `--pr-repo` (o despachante do repo de código informa), senão o repositório
136
+ * em que o comando roda. Sem `--pr-repo` num hub multi-repo o PR é procurado
137
+ * no hub — e um 404 aí é o sinal certo, não a issue errada.
138
+ *
139
+ * @param {string|undefined} prRepoOpt valor de `--pr-repo`
140
+ * @param {ReturnType<typeof resolveHubContext>} ctx
141
+ * @returns {{ owner: string, repo: string }}
142
+ */
143
+ export function resolvePrRepo(prRepoOpt, ctx) {
144
+ if (prRepoOpt) {
145
+ const parsed = parseRepoRef(prRepoOpt);
146
+ if (!parsed) throw new Error(`--pr-repo inválido: "${prRepoOpt}". Use owner/repo.`);
147
+ return parsed;
148
+ }
149
+ if (ctx.self?.owner && ctx.self?.repo) return { owner: ctx.self.owner, repo: ctx.self.repo };
150
+ return { owner: ctx.owner, repo: ctx.repo };
151
+ }
@@ -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)');
@@ -14,6 +14,116 @@ export const QA_REPORT_VERSION = 1;
14
14
  /** Vereditos aceitos por cenário. */
15
15
  export const QA_VERDICTS = ['pass', 'fail', 'blocked'];
16
16
 
17
+ // ── Evidência visual (vídeo/foto) — CONTRATO com a UI do SpecWave ──────────
18
+ //
19
+ // A UI lê `docs/features/<slug>/qa/cenario-<n>/` (ou `docs/bugs/<slug>/qa/`)
20
+ // direto da branch default e serve cada arquivo por uma Lambda síncrona: o
21
+ // nome precisa casar o padrão abaixo (o server responde 400 fora dele), só as
22
+ // extensões listadas aparecem na tela, e acima do teto ela mostra "sem prévia".
23
+ // Por isso a validação é ESTRITA aqui: publicar um arquivo que a UI recusa é
24
+ // gastar espaço no repositório sem ganhar nada.
25
+
26
+ /** Extensões de mídia que a UI serve. */
27
+ export const QA_EVIDENCE_IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp'];
28
+ export const QA_EVIDENCE_VIDEO_EXTENSIONS = ['mp4', 'webm', 'mov'];
29
+ export const QA_EVIDENCE_EXTENSIONS = [...QA_EVIDENCE_VIDEO_EXTENSIONS, ...QA_EVIDENCE_IMAGE_EXTENSIONS];
30
+
31
+ /** Teto DURO por arquivo (Lambda síncrona de 6 MB, corpo em base64 +33%). */
32
+ export const QA_EVIDENCE_MAX_BYTES = 4 * 1024 * 1024;
33
+
34
+ /** Nome de arquivo aceito pela UI: sem espaço, sem barra, sem dotfile. */
35
+ export const QA_EVIDENCE_NAME_RE = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
36
+
37
+ /** Subpasta de um cenário dentro do diretório de evidência. */
38
+ export function evidenceScenarioDir(numero) {
39
+ return `cenario-${numero}`;
40
+ }
41
+
42
+ /**
43
+ * Tipo de mídia pela extensão (função PURA).
44
+ *
45
+ * @param {string} file nome ou caminho do arquivo
46
+ * @returns {'image'|'video'|null} null = extensão fora do contrato
47
+ */
48
+ export function evidenceMediaKind(file) {
49
+ const ext = String(file || '').toLowerCase().split('.').pop();
50
+ if (QA_EVIDENCE_IMAGE_EXTENSIONS.includes(ext)) return 'image';
51
+ if (QA_EVIDENCE_VIDEO_EXTENSIONS.includes(ext)) return 'video';
52
+ return null;
53
+ }
54
+
55
+ /**
56
+ * URL pública de um arquivo de evidência publicado (função PURA).
57
+ *
58
+ * Imagem → raw.githubusercontent.com (o GitHub a EMBUTE no comentário);
59
+ * vídeo → página blob do GitHub (o raw de um .webm só baixa; a página blob
60
+ * toca inline). O `sha` é o commit que PUBLICOU a evidência, não o HEAD
61
+ * testado — a re-execução sobrescreve o mesmo caminho, e um link por branch
62
+ * passaria a apontar para a corrida seguinte.
63
+ *
64
+ * @param {string} owner
65
+ * @param {string} repo
66
+ * @param {string} sha commit (curto ou longo) ou branch
67
+ * @param {string} pathRel caminho relativo à raiz do repositório
68
+ * @returns {string}
69
+ */
70
+ export function evidenceMediaUrl(owner, repo, sha, pathRel) {
71
+ const encoded = String(pathRel || '').split('/').map(encodeURIComponent).join('/');
72
+ const base = evidenceMediaKind(pathRel) === 'image'
73
+ ? `https://raw.githubusercontent.com/${owner}/${repo}/${sha}/`
74
+ : `https://github.com/${owner}/${repo}/blob/${sha}/`;
75
+ return base + encoded;
76
+ }
77
+
78
+ /**
79
+ * Normaliza e valida os nomes de evidência declarados por um cenário (PURA).
80
+ *
81
+ * Aceita o nome puro (`video.webm`) ou prefixado pela própria subpasta
82
+ * (`cenario-2/video.webm`) — é o erro mais provável de um executor que copiou
83
+ * o caminho inteiro — e rejeita todo o resto: qualquer barra remanescente,
84
+ * `..`, nome fora do padrão da UI ou extensão que a UI não serve.
85
+ *
86
+ * @param {*} value `evidenceFiles` do resultado
87
+ * @param {number} numero número posicional do cenário
88
+ * @param {string} at prefixo das mensagens de erro (ex.: "scenarios[0]")
89
+ * @returns {string[]} nomes de arquivo (sem diretório), sem duplicatas
90
+ */
91
+ export function normalizeEvidenceFiles(value, numero, at = 'evidenceFiles') {
92
+ if (value == null) return [];
93
+ if (!Array.isArray(value)) {
94
+ throw new Error(`${at}.evidenceFiles deveria ser uma lista de nomes de arquivo, veio ${JSON.stringify(value)}.`);
95
+ }
96
+ const prefix = `${evidenceScenarioDir(numero)}/`;
97
+ const out = [];
98
+ value.forEach((item, i) => {
99
+ if (typeof item !== 'string') {
100
+ throw new Error(`${at}.evidenceFiles[${i}] deveria ser string, veio ${JSON.stringify(item)}.`);
101
+ }
102
+ let name = item.trim().replace(/^\.\//, '');
103
+ if (name.startsWith(prefix)) name = name.slice(prefix.length);
104
+ if (name.includes('/') || name.includes('\\') || name.includes('..')) {
105
+ throw new Error(
106
+ `${at}.evidenceFiles[${i}] = ${JSON.stringify(item)}: informe só o NOME do arquivo dentro de ` +
107
+ `${prefix} (sem subpasta, sem \`..\`).`
108
+ );
109
+ }
110
+ if (!QA_EVIDENCE_NAME_RE.test(name)) {
111
+ throw new Error(
112
+ `${at}.evidenceFiles[${i}] = ${JSON.stringify(item)}: nome fora do padrão ` +
113
+ '(letras, dígitos, ponto, hífen e sublinhado; sem espaço, sem começar com ponto).'
114
+ );
115
+ }
116
+ if (!evidenceMediaKind(name)) {
117
+ throw new Error(
118
+ `${at}.evidenceFiles[${i}] = ${JSON.stringify(item)}: extensão fora do contrato ` +
119
+ `(aceitas: ${QA_EVIDENCE_EXTENSIONS.join(', ')}).`
120
+ );
121
+ }
122
+ if (!out.includes(name)) out.push(name);
123
+ });
124
+ return out;
125
+ }
126
+
17
127
  export const QA_REPORT_MARKER_RE =
18
128
  /<!--\s*spec-wave:qa-report\s+v(?<version>\d+)\s+issue=(?<issue>\d+)\s+run=(?<run>\d+)\s+verdict=(?<verdict>pass|fail|blocked)\s+planSha=(?<planSha>[0-9a-f]+)\s+headSha=(?<headSha>[0-9a-f?]+)\s*-->/g;
19
129
 
@@ -84,11 +194,15 @@ export function aggregateVerdict(results = []) {
84
194
  * motivo do relatório de trilha depende dele;
85
195
  * • `fail` exige `evidencia` não vazia — sem evidência não há bug.md
86
196
  * determinístico;
87
- * • `blockedReason: outro` exige `evidencia` não vazia (é o texto livre).
197
+ * • `blockedReason: outro` exige `evidencia` não vazia (é o texto livre);
198
+ * • `evidenceFiles` (opcional) só é validado na FORMA — nomes de arquivo que
199
+ * a UI aceita (normalizeEvidenceFiles). Se existem em disco é o comando que
200
+ * confere, ao publicar: evidência visual é ENRIQUECIMENTO, nunca o canal do
201
+ * veredito, então arquivo ausente vira aviso, não erro.
88
202
  *
89
203
  * @param {*} payload objeto lido do arquivo de resultados
90
204
  * @param {number[]} expected números dos cenários que DEVIAM ter sido executados
91
- * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string, blockedReason:string|null}>}
205
+ * @returns {Array<{numero:number, verdict:'pass'|'fail'|'blocked', evidencia:string, blockedReason:string|null, evidenceFiles:string[]}>}
92
206
  */
93
207
  export function validateQaResults(payload, expected = []) {
94
208
  if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.scenarios)) {
@@ -132,6 +246,7 @@ export function validateQaResults(payload, expected = []) {
132
246
  verdict,
133
247
  evidencia,
134
248
  blockedReason: verdict === 'blocked' ? blockedReason : null,
249
+ evidenceFiles: normalizeEvidenceFiles(item?.evidenceFiles, numero, at),
135
250
  });
136
251
  });
137
252
  const missing = expected.filter(n => !out.has(n));
@@ -178,7 +293,9 @@ export function combineWithPrevious({ executed = [], previous = new Map(), allNu
178
293
  if (prev) {
179
294
  combined.push({
180
295
  numero: n, verdict: prev.verdict, evidencia: prev.evidencia || '(corrida anterior)',
181
- blockedReason: prev.blockedReason || null, carried: true,
296
+ blockedReason: prev.blockedReason || null,
297
+ evidenceFiles: Array.isArray(prev.evidenceFiles) ? prev.evidenceFiles : [],
298
+ carried: true,
182
299
  });
183
300
  } else {
184
301
  pendingNumbers.push(n);
@@ -221,6 +338,11 @@ export function parseLastQaReport(comments = []) {
221
338
  verdict: s.verdict,
222
339
  evidencia: s.evidencia || '',
223
340
  blockedReason: s.blockedReason || null,
341
+ // Caminhos JÁ PUBLICADOS (relativos à raiz do repo) — o cenário
342
+ // herdado num `--only` mantém os links da corrida que o gravou.
343
+ evidenceFiles: Array.isArray(s.evidenceFiles)
344
+ ? s.evidenceFiles.filter(f => typeof f === 'string' && f)
345
+ : [],
224
346
  }]));
225
347
  }
226
348
  // Bugs abertos pela corrida — o `qa-lead` compõe o `bugsOpened` do
@@ -246,12 +368,33 @@ function sanitizeCell(text, max = 200) {
246
368
  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
247
369
  }
248
370
 
371
+ // Links da evidência visual de UM cenário, para o markdown (função PURA).
372
+ // Imagem embutida (miniatura clicável); vídeo só como link — o GitHub não toca
373
+ // vídeo por URL em comentário/markdown, a página blob toca.
374
+ function renderEvidenceLinks(files = [], base = null, { inline = true } = {}) {
375
+ return (files || []).map((rel) => {
376
+ const name = String(rel).split('/').pop();
377
+ if (!base?.owner || !base?.repo || !base?.sha) return `\`${rel}\``;
378
+ const url = evidenceMediaUrl(base.owner, base.repo, base.sha, rel);
379
+ if (evidenceMediaKind(rel) === 'image') {
380
+ return inline
381
+ ? `<a href="${url}"><img src="${url}" alt="${name}" width="160"></a>`
382
+ : `[📷 ${name}](${url})`;
383
+ }
384
+ return `[🎬 ${name}](${url})`;
385
+ });
386
+ }
387
+
249
388
  /**
250
389
  * Monta o comentário de relatório de QA (função PURA).
251
390
  *
252
391
  * Primeira linha = marcador (contrato com a UI). O bloco JSON no fim é o que a
253
392
  * próxima execução com `--only` lê para compor o estado acumulado.
254
393
  *
394
+ * A coluna **Mídia** só existe quando algum cenário tem evidência visual —
395
+ * sem ela a tabela é byte a byte a de antes (a UI parseia o bloco JSON, não a
396
+ * tabela, mas leitores humanos e testes antigos não ganham uma coluna vazia).
397
+ *
255
398
  * @param {object} params
256
399
  * @param {number} params.issue issue onde o relatório será postado
257
400
  * @param {string} params.scope ex.: "Story #412" ou "Feature #360"
@@ -259,14 +402,17 @@ function sanitizeCell(text, max = 200) {
259
402
  * @param {'pass'|'fail'|'blocked'} params.verdict veredito agregado
260
403
  * @param {string} params.planSha sha curto do qa-plan.md executado
261
404
  * @param {string} [params.headSha] sha curto do HEAD do checkout
262
- * @param {Array<{numero, verdict, evidencia, carried?}>} params.results
405
+ * @param {Array<{numero, verdict, evidencia, carried?, evidenceFiles?:string[]}>} params.results
406
+ * `evidenceFiles` = caminhos JÁ PUBLICADOS, relativos à raiz do repositório
407
+ * @param {{owner:string, repo:string, sha:string}|null} [params.evidenceBase]
408
+ * de onde servir a mídia — sem ele os caminhos saem como texto
263
409
  * @param {Array<{number:number, cenario:number, existing?:boolean}>} [params.bugs]
264
410
  * @param {number[]} [params.pendingNumbers] cenários sem veredito em corrida parcial
265
411
  * @param {string} [params.trailer] linha final livre (o que acontece a seguir)
266
412
  * @returns {string} markdown
267
413
  */
268
414
  export function renderQaReport({
269
- issue, scope, run, verdict, planSha, headSha, results = [], bugs = [],
415
+ issue, scope, run, verdict, planSha, headSha, results = [], evidenceBase = null, bugs = [],
270
416
  pendingNumbers = [], trailer = '',
271
417
  } = {}) {
272
418
  const parts = [
@@ -275,11 +421,17 @@ export function renderQaReport({
275
421
  `**Escopo:** ${scope} · **Cenários:** ${results.length} · **Execução:** ${run}ª`,
276
422
  ];
277
423
 
278
- const linhas = ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
424
+ const comMidia = results.some(r => Array.isArray(r.evidenceFiles) && r.evidenceFiles.length > 0);
425
+ const linhas = comMidia
426
+ ? ['| Cenário | Veredito | Evidência | Mídia |', '|---|---|---|---|']
427
+ : ['| Cenário | Veredito | Evidência |', '|---|---|---|'];
279
428
  for (const r of results) {
280
429
  const carried = r.carried ? ' _(corrida anterior)_' : '';
281
430
  const reason = r.verdict === 'blocked' && r.blockedReason ? ` (${r.blockedReason})` : '';
282
- linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict}${reason} | ${sanitizeCell(r.evidencia)}${carried} |`);
431
+ const midia = comMidia
432
+ ? ` ${renderEvidenceLinks(r.evidenceFiles, evidenceBase).join(' ') || '—'} |`
433
+ : '';
434
+ linhas.push(`| ${r.numero} | ${VERDICT_ICON[r.verdict] || r.verdict}${reason} | ${sanitizeCell(r.evidencia)}${carried} |${midia}`);
283
435
  }
284
436
  parts.push(linhas.join('\n'));
285
437
 
@@ -308,6 +460,10 @@ export function renderQaReport({
308
460
  verdict: r.verdict,
309
461
  evidencia: sanitizeCell(r.evidencia, 400),
310
462
  ...(r.verdict === 'blocked' && r.blockedReason ? { blockedReason: r.blockedReason } : {}),
463
+ // Aditivo ao v1: caminhos publicados da evidência visual (só quando há).
464
+ ...(Array.isArray(r.evidenceFiles) && r.evidenceFiles.length > 0
465
+ ? { evidenceFiles: r.evidenceFiles }
466
+ : {}),
311
467
  })),
312
468
  // Aditivo ao v1: o `qa-lead` lê daqui os Bugs da corrida.
313
469
  bugs: bugs.map(b => ({ number: b.number, cenario: b.cenario, existing: !!b.existing })),
@@ -334,13 +490,18 @@ export function renderQaReport({
334
490
  * @param {string} params.title título do Bug (sem o prefixo [BUG])
335
491
  * @param {{anchor, numero, story, criterio, precondicoes, passos, esperado}} params.scenario
336
492
  * @param {string} params.evidence evidência bruta da reprovação
493
+ * @param {string[]} [params.evidenceFiles] evidência visual JÁ PUBLICADA (caminhos
494
+ * relativos à raiz do repositório)
495
+ * @param {{owner:string, repo:string, sha:string}|null} [params.evidenceBase]
496
+ * de onde servir a mídia — sem ele os caminhos saem como texto
337
497
  * @param {string} params.severity P0–P3
338
498
  * @param {string} [params.headSha] commit do checkout onde a reprova aconteceu
339
499
  * @param {number|null} [params.featureNumber]
340
500
  * @returns {string} markdown
341
501
  */
342
502
  export function renderQaBugDoc({
343
- title, scenario, evidence, severity, headSha = null, featureNumber = null,
503
+ title, scenario, evidence, evidenceFiles = [], evidenceBase = null, severity,
504
+ headSha = null, featureNumber = null,
344
505
  } = {}) {
345
506
  const [
346
507
  reproducao, esperadoObtido, impacto, causaRaiz, escopo, regressao,
@@ -367,6 +528,9 @@ export function renderQaBugDoc({
367
528
  `**Esperado:** ${scenario.esperado || '—'}`,
368
529
  '',
369
530
  `**Obtido:** ${evidence || '(sem evidência registrada)'}`,
531
+ ...(evidenceFiles.length > 0
532
+ ? ['', '**Evidência visual:** ' + renderEvidenceLinks(evidenceFiles, evidenceBase, { inline: false }).join(' · ')]
533
+ : []),
370
534
  '',
371
535
  `## ${impacto}`,
372
536
  '',