@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.
- package/package.json +2 -2
- package/protocol/qa-result.v1.json +9 -0
- package/src/agent/anthropic-agent.mjs +35 -2
- package/src/api/github-graphql.mjs +60 -2
- package/src/api/github-rest.mjs +23 -0
- package/src/cli.mjs +23 -0
- package/src/commands/code-review.mjs +71 -60
- package/src/commands/decompose.mjs +75 -4
- package/src/commands/doctor.mjs +105 -4
- package/src/commands/implement.mjs +82 -10
- package/src/commands/init.mjs +147 -29
- package/src/commands/merge.mjs +56 -4
- package/src/commands/move.mjs +4 -7
- package/src/commands/order.mjs +2 -2
- package/src/commands/qa-run.mjs +140 -19
- package/src/commands/qa.mjs +22 -21
- package/src/commands/repair-stage.mjs +2 -5
- package/src/commands/story.mjs +2 -2
- package/src/commands/task.mjs +2 -2
- package/src/commands/triage.mjs +2 -5
- package/src/commands/update.mjs +31 -8
- package/src/commands/validate.mjs +2 -5
- package/src/commands/workspace.mjs +112 -0
- package/src/config.mjs +19 -0
- package/src/lib/artifact-pr.mjs +1 -1
- package/src/lib/bug-doc.mjs +6 -1
- package/src/lib/claude.mjs +4 -0
- package/src/lib/decomposition-doc.mjs +56 -3
- package/src/lib/dependency-map.mjs +3 -0
- package/src/lib/doc-paths.mjs +6 -1
- package/src/lib/flow-run.mjs +14 -3
- package/src/lib/pr-link.mjs +109 -0
- package/src/lib/pr-ready.mjs +146 -0
- package/src/lib/project-root.mjs +51 -0
- package/src/lib/qa-exec.mjs +73 -0
- package/src/lib/qa-report.mjs +172 -8
- package/src/lib/repo-role.mjs +102 -0
- package/src/lib/workspace.mjs +151 -0
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/decompose/SKILL.md +1 -0
- package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
- package/src/plugin/skills/implement/SKILL.md +2 -2
- package/src/plugin/skills/merge/SKILL.md +3 -2
- package/src/plugin/skills/qa/SKILL.md +6 -1
- package/src/plugin/skills/qa-executor/SKILL.md +43 -1
- package/src/plugin/skills/setup/SKILL.md +12 -0
- package/src/setup/files.mjs +35 -13
- package/src/templates/skill/SKILL.md +27 -5
- package/src/templates/skill/core.md +5 -1
- package/src/templates/workflows/code/code-review.yml +60 -0
- package/src/templates/workflows/code/qa.yml +59 -0
- 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
|
+
}
|
package/src/lib/project-root.mjs
CHANGED
|
@@ -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
|
+
}
|
package/src/lib/qa-exec.mjs
CHANGED
|
@@ -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)');
|
package/src/lib/qa-report.mjs
CHANGED
|
@@ -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,
|
|
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
|
|
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
|
|
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
|
-
|
|
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,
|
|
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
|
'',
|