@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
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spec-wave/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
|
-
"spec-wave": "
|
|
7
|
+
"spec-wave": "bin/spec-wave.mjs"
|
|
8
8
|
},
|
|
9
9
|
"publishConfig": {
|
|
10
10
|
"access": "public"
|
|
@@ -29,6 +29,15 @@
|
|
|
29
29
|
"type": "string",
|
|
30
30
|
"description": "Evidência bruta (comando, saída, código de status). OBRIGATÓRIA e não vazia em `fail` (vira o bug.md determinístico) e em `blocked` com `blockedReason: outro`."
|
|
31
31
|
},
|
|
32
|
+
"evidenceFiles": {
|
|
33
|
+
"type": "array",
|
|
34
|
+
"description": "OPCIONAL (aditivo ao v1). Evidência VISUAL do cenário — vídeo/foto gravados por Maestro (mobile) ou Playwright (web). Nomes de arquivo (sem diretório) que o executor gravou em `<evidenceDir>/cenario-<n>/`; a CLI os publica em `docs/features/<slug>/qa/cenario-<n>/` (ou `docs/bugs/<slug>/qa/`). Só extensões mp4, webm, mov, png, jpg, jpeg, gif, webp; teto de 4 MB por arquivo (acima disso a CLI avisa e não publica). Nunca substitui `evidencia` (texto), que continua obrigatória nas mesmas regras.",
|
|
35
|
+
"items": {
|
|
36
|
+
"type": "string",
|
|
37
|
+
"pattern": "^[A-Za-z0-9_-][A-Za-z0-9._-]*\\.(mp4|webm|mov|png|jpg|jpeg|gif|webp)$"
|
|
38
|
+
},
|
|
39
|
+
"uniqueItems": true
|
|
40
|
+
},
|
|
32
41
|
"blockedReason": {
|
|
33
42
|
"enum": [
|
|
34
43
|
"ambiente",
|
|
@@ -43,6 +43,38 @@ export function withoutBlankCredentials(env) {
|
|
|
43
43
|
return copy;
|
|
44
44
|
}
|
|
45
45
|
|
|
46
|
+
/**
|
|
47
|
+
* Ambiente do subprocesso com UMA credencial: a que o provider escolheu
|
|
48
|
+
* (função PURA).
|
|
49
|
+
*
|
|
50
|
+
* Os providers `anthropic` e `claude-oauth` rodam neste mesmo backend e diferem
|
|
51
|
+
* SÓ na credencial — mas o Claude Code não lê o `.spec-wave.json`: ele resolve
|
|
52
|
+
* credencial por conta própria, e nessa ordem `ANTHROPIC_API_KEY` vem ANTES do
|
|
53
|
+
* token da assinatura. Com as duas no ambiente, quem escolheu `claude-oauth`
|
|
54
|
+
* era silenciosamente atendido pela chave de API, e a falha aparecia como um
|
|
55
|
+
* erro da conta errada (foi "Credit balance is too low" de uma conta de API
|
|
56
|
+
* zerada, num repo que tinha assinatura válida).
|
|
57
|
+
*
|
|
58
|
+
* Por isso a decisão não pode ficar com o Claude Code: quem sabe qual credencial
|
|
59
|
+
* vale é o config, e `credentialVar` é como essa decisão chega até aqui. O
|
|
60
|
+
* backend continua sem saber o que é `claude-oauth` — ele recebe o NOME da
|
|
61
|
+
* variável, não o provider.
|
|
62
|
+
*
|
|
63
|
+
* Sem `credentialVar` o comportamento é o de antes (só o saneamento de vazias):
|
|
64
|
+
* é o caso de quem chama o motor direto, sem config resolvido.
|
|
65
|
+
*
|
|
66
|
+
* @param {object} env
|
|
67
|
+
* @param {string|null} [credentialVar] nome da variável a preservar
|
|
68
|
+
*/
|
|
69
|
+
export function credentialEnvFor(env, credentialVar = null) {
|
|
70
|
+
const copy = withoutBlankCredentials(env);
|
|
71
|
+
if (!credentialVar) return copy;
|
|
72
|
+
for (const key of CREDENTIAL_VARS) {
|
|
73
|
+
if (key !== credentialVar) delete copy[key];
|
|
74
|
+
}
|
|
75
|
+
return copy;
|
|
76
|
+
}
|
|
77
|
+
|
|
46
78
|
/** Base de comparação da allowlist: absoluto resolvido, minúsculo no win32. */
|
|
47
79
|
function normalizeWritePath(p) {
|
|
48
80
|
const resolved = path.resolve(p);
|
|
@@ -142,8 +174,9 @@ export async function runAnthropicAgent(prompt, options) {
|
|
|
142
174
|
// (PATH, HOME). O saneamento existe porque `${{ secrets.X }}` de um
|
|
143
175
|
// secret inexistente injeta string VAZIA: um CLAUDE_CODE_OAUTH_TOKEN=""
|
|
144
176
|
// chegando ao CLI é ambiguidade gratuita entre "não configurado" e
|
|
145
|
-
// "configurado errado".
|
|
146
|
-
|
|
177
|
+
// "configurado errado". E `credentialVar` deixa passar SÓ a credencial
|
|
178
|
+
// do provider escolhido — ver credentialEnvFor.
|
|
179
|
+
env: credentialEnvFor(process.env, options.credentialVar ?? null),
|
|
147
180
|
// Desliga o carregamento de settings do filesystem (~/.claude,
|
|
148
181
|
// .claude/settings.json) para o subprocesso não herdar hooks ou
|
|
149
182
|
// permissões de fora deste `queryOptions`.
|
|
@@ -383,7 +383,7 @@ export async function listSubIssues(token, issueNodeId) {
|
|
|
383
383
|
* branch. `includeClosedPrs` de propósito: PR já mergeado é o que diz que a
|
|
384
384
|
* Story está entregue.
|
|
385
385
|
*
|
|
386
|
-
* @returns {Promise<Array<{number, state, merged, isDraft, baseRefName, headRefName}>>}
|
|
386
|
+
* @returns {Promise<Array<{id, number, state, merged, isDraft, baseRefName, headRefName}>>}
|
|
387
387
|
*/
|
|
388
388
|
export async function listIssuePullRequests(token, issueNodeId) {
|
|
389
389
|
const client = makeClient(token);
|
|
@@ -392,7 +392,7 @@ export async function listIssuePullRequests(token, issueNodeId) {
|
|
|
392
392
|
node(id: $id) {
|
|
393
393
|
... on Issue {
|
|
394
394
|
closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
|
|
395
|
-
nodes { number state merged isDraft baseRefName headRefName }
|
|
395
|
+
nodes { id number state merged isDraft baseRefName headRefName }
|
|
396
396
|
}
|
|
397
397
|
}
|
|
398
398
|
}
|
|
@@ -400,6 +400,7 @@ export async function listIssuePullRequests(token, issueNodeId) {
|
|
|
400
400
|
`, { id: issueNodeId });
|
|
401
401
|
const nodes = result.node?.closedByPullRequestsReferences?.nodes || [];
|
|
402
402
|
return nodes.map(n => ({
|
|
403
|
+
id: n.id,
|
|
403
404
|
number: n.number,
|
|
404
405
|
state: (n.state || '').toLowerCase(), // open | closed | merged
|
|
405
406
|
merged: Boolean(n.merged),
|
|
@@ -409,6 +410,63 @@ export async function listIssuePullRequests(token, issueNodeId) {
|
|
|
409
410
|
}));
|
|
410
411
|
}
|
|
411
412
|
|
|
413
|
+
/**
|
|
414
|
+
* Todos os PRs ABERTOS do repositório, com corpo — o plano B do `merge` quando
|
|
415
|
+
* o vínculo nativo falha. O GitHub só registra closedByPullRequestsReferences
|
|
416
|
+
* quando a base do PR é a branch default; numa pilha, só o PR de baixo tem, e
|
|
417
|
+
* os demais ficam invisíveis para listIssuePullRequests até o retarget. O corpo
|
|
418
|
+
* (`Closes #N`) é o que o autor declarou, então o merge parseia daqui.
|
|
419
|
+
*
|
|
420
|
+
* @returns {Promise<Array<{id, number, state, merged, isDraft, baseRefName, headRefName, body}>>}
|
|
421
|
+
*/
|
|
422
|
+
export async function listOpenPullRequests(token, owner, repo) {
|
|
423
|
+
const client = makeClient(token);
|
|
424
|
+
const result = await client(`
|
|
425
|
+
query OpenPRs($owner: String!, $repo: String!) {
|
|
426
|
+
repository(owner: $owner, name: $repo) {
|
|
427
|
+
pullRequests(states: OPEN, first: 100, orderBy: { field: CREATED_AT, direction: DESC }) {
|
|
428
|
+
nodes { id number state merged isDraft baseRefName headRefName body }
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
`, { owner, repo });
|
|
433
|
+
const nodes = result.repository?.pullRequests?.nodes || [];
|
|
434
|
+
return nodes.map(n => ({
|
|
435
|
+
id: n.id,
|
|
436
|
+
number: n.number,
|
|
437
|
+
state: (n.state || '').toLowerCase(),
|
|
438
|
+
merged: Boolean(n.merged),
|
|
439
|
+
isDraft: Boolean(n.isDraft),
|
|
440
|
+
baseRefName: n.baseRefName || null,
|
|
441
|
+
headRefName: n.headRefName || null,
|
|
442
|
+
body: n.body || '',
|
|
443
|
+
}));
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/**
|
|
447
|
+
* Tira um PR do rascunho. Só existe em GraphQL — a REST não expõe a transição
|
|
448
|
+
* draft → ready (o PATCH de `draft` é ignorado em silêncio, que é pior).
|
|
449
|
+
*
|
|
450
|
+
* Marcar como pronto é o SINAL de que o trabalho acabou: enquanto o dev-agent
|
|
451
|
+
* implementa as Stories de uma Feature, os PRs ficam em rascunho para que
|
|
452
|
+
* ninguém revise nem mergeie uma feature pela metade; quando a última Story
|
|
453
|
+
* entra em Code Review, o `implement` marca todos como prontos de uma vez.
|
|
454
|
+
*
|
|
455
|
+
* Idempotente do lado de cá: um PR já pronto devolve erro do GitHub, então o
|
|
456
|
+
* chamador filtra por `isDraft` antes (ver planPrsToReady).
|
|
457
|
+
*/
|
|
458
|
+
export async function markPullRequestReadyForReview(token, pullRequestId) {
|
|
459
|
+
const client = makeClient(token);
|
|
460
|
+
const result = await client(`
|
|
461
|
+
mutation ReadyForReview($id: ID!) {
|
|
462
|
+
markPullRequestReadyForReview(input: { pullRequestId: $id }) {
|
|
463
|
+
pullRequest { number isDraft }
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
`, { id: pullRequestId });
|
|
467
|
+
return result.markPullRequestReadyForReview?.pullRequest || null;
|
|
468
|
+
}
|
|
469
|
+
|
|
412
470
|
/**
|
|
413
471
|
* Issues que o GitHub reconhece como fechadas por este PR
|
|
414
472
|
* (`Closes #N` e o vínculo feito pela UI). É a MESMA lista que fecha as issues
|
package/src/api/github-rest.mjs
CHANGED
|
@@ -24,6 +24,29 @@ export async function getOwnerNodeId(token, owner) {
|
|
|
24
24
|
}
|
|
25
25
|
}
|
|
26
26
|
|
|
27
|
+
// GitHub Projects v2 só é acessível pelo GitHub App do spec-wave quando o
|
|
28
|
+
// owner é uma organização — Projects v2 de conta pessoal não são suportados
|
|
29
|
+
// pela instalação do App. Usado por `init` (bloqueia antes de criar repo/project)
|
|
30
|
+
// e por `doctor` (diagnóstico de instalações já configuradas).
|
|
31
|
+
export async function getOwnerType(token, owner) {
|
|
32
|
+
const octokit = makeOctokit(token);
|
|
33
|
+
try {
|
|
34
|
+
await octokit.rest.orgs.get({ org: owner });
|
|
35
|
+
return 'Organization';
|
|
36
|
+
} catch (err) {
|
|
37
|
+
if (err.status !== 404) throw err;
|
|
38
|
+
}
|
|
39
|
+
try {
|
|
40
|
+
await octokit.rest.users.getByUsername({ username: owner });
|
|
41
|
+
return 'User';
|
|
42
|
+
} catch (err) {
|
|
43
|
+
if (err.status === 404) {
|
|
44
|
+
throw new Error(`Owner "${owner}" não encontrado no GitHub.`);
|
|
45
|
+
}
|
|
46
|
+
throw err;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
27
50
|
export async function getRepoNodeId(token, owner, repo) {
|
|
28
51
|
const octokit = makeOctokit(token);
|
|
29
52
|
const res = await octokit.rest.repos.get({ owner, repo });
|
package/src/cli.mjs
CHANGED
|
@@ -45,6 +45,8 @@ export function buildProgram() {
|
|
|
45
45
|
.description('Configura spec-wave em um repositório GitHub')
|
|
46
46
|
.option('--dry-run', 'Simula a configuração sem fazer alterações')
|
|
47
47
|
.option('--repo <owner/repo>', 'Repositório GitHub (ignora o wizard interativo)')
|
|
48
|
+
.option('--role <role>', 'Papel do repositório no Project (RFC-005): hub (issues, docs e workflows — padrão) ou code (só branch e PR)')
|
|
49
|
+
.option('--hub <owner/repo>', 'Com --role code: o repositório hub do Project a que este repo de código pertence')
|
|
48
50
|
.option('--project-title <title>', 'Nome do GitHub Project (padrão: "<repo> — Spec Wave")')
|
|
49
51
|
.option('--skip-project', 'Pula a criação do GitHub Project (use se já foi criado)')
|
|
50
52
|
.option('--skip-labels', 'Pula a criação das labels')
|
|
@@ -313,6 +315,7 @@ export function buildProgram() {
|
|
|
313
315
|
.command('code-review')
|
|
314
316
|
.description('Move Feature para Code Review ao abrir um PR (usado pelo GitHub Action)')
|
|
315
317
|
.requiredOption('--pr-number <n>', 'Número do Pull Request')
|
|
318
|
+
.option('--pr-repo <owner/repo>', 'Repositório onde o PR foi aberto, quando não é o hub (multi-repo, RFC-005)')
|
|
316
319
|
.option('--resolve-only', 'Só descobre a Feature-alvo e imprime feature=<n>, sem tocar no board')
|
|
317
320
|
.action(async (options) => {
|
|
318
321
|
const { codeReview } = await import('./commands/code-review.mjs');
|
|
@@ -324,6 +327,7 @@ export function buildProgram() {
|
|
|
324
327
|
.description('Executa o plano de QA de uma issue (Feature/Story/Bug) localmente; com --pr-number, move a Feature para QA (usado pelo GitHub Action)')
|
|
325
328
|
.argument('[issue]', 'Número da issue (Feature, Story ou Bug), ex.: 12 ou #12')
|
|
326
329
|
.option('--pr-number <n>', 'Modo Action: move a Feature/Bug do PR aprovado ou mergeado para 🧪 QA')
|
|
330
|
+
.option('--pr-repo <owner/repo>', 'Com --pr-number: repositório onde o PR foi aberto, quando não é o hub (multi-repo, RFC-005)')
|
|
327
331
|
.option('--only <n[,m]>', 'Executa só o(s) cenário(s) indicado(s) — número POSICIONAL no plano')
|
|
328
332
|
.option('--severity <p>', 'Severidade dos Bugs abertos na reprova: P0, P1, P2 ou P3 (default: qa.defaultBugPriority ou P2)')
|
|
329
333
|
.option('--dry-run', 'Monta o contexto e imprime cenários e comando — ZERO escrita no GitHub')
|
|
@@ -368,6 +372,25 @@ Re-teste após o fix: qa <story> --only <cenário> (não duplica Bug — comenta
|
|
|
368
372
|
|
|
369
373
|
Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
|
|
370
374
|
|
|
375
|
+
program
|
|
376
|
+
.command('workspace')
|
|
377
|
+
.description('Monta o workspace multi-repo de uma issue (RFC-005): mapeia ou clona, ao lado do hub, os repositórios que ela declara com repo:<slug>')
|
|
378
|
+
.argument('<acao>', 'prepare')
|
|
379
|
+
.requiredOption('--issue <n>', 'Feature (agrega os repos das Stories), Story ou Task')
|
|
380
|
+
.option('--json', 'Imprime o layout em JSON (workspaceDir, repos[], repoDirs) — para o Action e para scripts')
|
|
381
|
+
.option('--dry-run', 'Resolve o layout e imprime; não clona nada')
|
|
382
|
+
.option('--refresh', 'Ignora o cache de sub-issues ao agregar os repos de uma Feature')
|
|
383
|
+
.action(async (acao, options) => {
|
|
384
|
+
const { workspace } = await import('./commands/workspace.mjs');
|
|
385
|
+
await workspace({ action: acao, ...options })
|
|
386
|
+
.catch(err => { console.error(err.message); process.exit(1); });
|
|
387
|
+
})
|
|
388
|
+
.addHelpText('after', `
|
|
389
|
+
Ordem de resolução por slug: override em .spec-wave/workspace.json ({ "dirs": { "<slug>": "<caminho>" } })
|
|
390
|
+
→ irmão do hub (<pai do hub>/<slug>) → clone gerenciado em <hub>/.spec-wave/repos/<slug>.
|
|
391
|
+
Irmãos e overrides são seus: nunca são clonados nem tocados. O implement lê o mesmo layout
|
|
392
|
+
para preencher {workspaceDir} e {repoDirs} no comando do spec-kit.`);
|
|
393
|
+
|
|
371
394
|
program
|
|
372
395
|
.command('qa-lead')
|
|
373
396
|
.description('Orquestra o QA de uma trilha (milestone): prepara os planos (plan), executa o ciclo em containers paralelos (run) e reimprime relatórios (report)')
|
|
@@ -6,7 +6,9 @@ import {
|
|
|
6
6
|
} from '../api/github-graphql.mjs';
|
|
7
7
|
import { detectIssueType } from '../lib/issue-type.mjs';
|
|
8
8
|
import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
|
|
9
|
-
import {
|
|
9
|
+
import { resolveHubContext, resolvePrRepo } from '../lib/project-root.mjs';
|
|
10
|
+
import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
|
|
11
|
+
import { extractIssueRefs, hubIssueNumbers, resolveLinkMode, sameRepo } from '../lib/pr-link.mjs';
|
|
10
12
|
import {
|
|
11
13
|
STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
|
|
12
14
|
LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, labelNames,
|
|
@@ -19,45 +21,6 @@ const DONE_STAGE = STAGE_DONE;
|
|
|
19
21
|
const TODO_STATUS = PROGRESS_TODO;
|
|
20
22
|
const DONE_STATUS = PROGRESS_DONE;
|
|
21
23
|
|
|
22
|
-
// Vínculo EXPLÍCITO: o verbo é obrigatório. `Relacionado: #10` e `#10` solto
|
|
23
|
-
// deixaram de contar — referência cruzada em PR é prática comum (uma PR de
|
|
24
|
-
// documentação citando três Features moveu as três para 👀 Code Review, e uma
|
|
25
|
-
// delas nem plano tinha). Aceita `#N`, `owner/repo#N` e a URL completa da issue.
|
|
26
|
-
const EXPLICIT_LINK_RE =
|
|
27
|
-
/\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;
|
|
28
|
-
|
|
29
|
-
// Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`.
|
|
30
|
-
const ANY_MENTION_RE = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
|
|
31
|
-
|
|
32
|
-
// Blocos de código não são vínculo: um `Closes #12` dentro de um exemplo de
|
|
33
|
-
// commit message é documentação, não promessa.
|
|
34
|
-
function stripCodeBlocks(body) {
|
|
35
|
-
return String(body)
|
|
36
|
-
.replace(/^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[ \t]*$/gm, '\n')
|
|
37
|
-
.replace(/`[^`\n]*`/g, ' ');
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
/**
|
|
41
|
-
* Números de issues que o PR declara implementar (função PURA — testável).
|
|
42
|
-
*
|
|
43
|
-
* @param {string} body corpo do PR
|
|
44
|
-
* @param {object} [opts]
|
|
45
|
-
* @param {'explicit'|'any-mention'} [opts.linkMode='explicit']
|
|
46
|
-
* @returns {number[]} na ordem em que aparecem, sem repetição
|
|
47
|
-
*/
|
|
48
|
-
export function extractIssueNumbers(body, { linkMode = 'explicit' } = {}) {
|
|
49
|
-
if (!body) return [];
|
|
50
|
-
const nums = new Set();
|
|
51
|
-
const text = stripCodeBlocks(body);
|
|
52
|
-
const re = linkMode === 'any-mention' ? ANY_MENTION_RE : EXPLICIT_LINK_RE;
|
|
53
|
-
re.lastIndex = 0;
|
|
54
|
-
for (const m of text.matchAll(re)) {
|
|
55
|
-
const n = parseInt(m.slice(1).find(Boolean) || '', 10);
|
|
56
|
-
if (n) nums.add(n);
|
|
57
|
-
}
|
|
58
|
-
return [...nums];
|
|
59
|
-
}
|
|
60
|
-
|
|
61
24
|
/**
|
|
62
25
|
* Recorte temporal da subárvore (função PURA — testável).
|
|
63
26
|
*
|
|
@@ -207,28 +170,35 @@ async function collectReviewUnit(token, owner, repo, issueNumber, { notAfter = n
|
|
|
207
170
|
|
|
208
171
|
// A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
|
|
209
172
|
// (ou etapa posterior). readToken lê as issues; projToken opera no Project.
|
|
173
|
+
//
|
|
174
|
+
// Devolve também as Stories: quem chama usa a mesma lista para tirar os PRs da
|
|
175
|
+
// Feature do rascunho, sem repetir o listSubIssues.
|
|
210
176
|
async function allStoriesReadyForReview(readToken, projToken, project, etapaField, featureNodeId) {
|
|
211
|
-
if (!etapaField?.id) return true; // sem campo Etapa não há como checar — assume ok
|
|
212
177
|
const subs = await listSubIssues(readToken, featureNodeId).catch(() => []);
|
|
213
|
-
const stories = subs
|
|
214
|
-
|
|
178
|
+
const stories = subs
|
|
179
|
+
.filter(s => detectIssueType({ title: s.title }) === 'Story')
|
|
180
|
+
.map(s => ({ number: s.number, nodeId: s.nodeId }));
|
|
181
|
+
if (!etapaField?.id) return { ready: true, stories }; // sem campo Etapa não há como checar — assume ok
|
|
182
|
+
if (stories.length === 0) return { ready: true, stories };
|
|
215
183
|
const tgtIdx = STAGE_ORDER.indexOf(CODE_REVIEW_STAGE);
|
|
216
184
|
for (const st of stories) {
|
|
217
185
|
const itemId = await addProjectItem(projToken, project.id, st.nodeId);
|
|
218
186
|
const current = await getItemSingleSelectValue(projToken, itemId, etapaField.id).catch(() => null);
|
|
219
187
|
const idx = current ? STAGE_ORDER.indexOf(current) : -1;
|
|
220
|
-
if (idx === -1 || idx < tgtIdx) return false; // há Story pendente
|
|
188
|
+
if (idx === -1 || idx < tgtIdx) return { ready: false, stories }; // há Story pendente
|
|
221
189
|
}
|
|
222
|
-
return true;
|
|
190
|
+
return { ready: true, stories };
|
|
223
191
|
}
|
|
224
192
|
|
|
225
|
-
export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
193
|
+
export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = false }) {
|
|
226
194
|
const token = await resolveToken();
|
|
227
195
|
const projectToken = process.env.PROJECT_TOKEN || token;
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
196
|
+
// Dois repositórios, que só coincidem no mono-repo: o hub (dono das issues e
|
|
197
|
+
// do board) e o repositório onde o PR foi aberto. O comando roda SEMPRE no
|
|
198
|
+
// hub (RFC-005 §7.1) — o repo de código não executa a CLI — então
|
|
199
|
+
// GITHUB_REPOSITORY/config dão o hub, e `--pr-repo` diz onde está o PR.
|
|
200
|
+
const ctx = resolveHubContext();
|
|
201
|
+
const { owner, repo, config: cfg } = ctx;
|
|
232
202
|
|
|
233
203
|
if (!owner || !repo) {
|
|
234
204
|
throw new Error(
|
|
@@ -236,18 +206,33 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
236
206
|
'Defina GITHUB_REPOSITORY=owner/repo ou rode dentro de um repositório com .spec-wave.json.'
|
|
237
207
|
);
|
|
238
208
|
}
|
|
209
|
+
const hub = { owner, repo };
|
|
210
|
+
const prRepo = resolvePrRepo(prRepoOpt, ctx);
|
|
211
|
+
const prNum = parseInt(prNumber, 10);
|
|
239
212
|
|
|
240
|
-
const pr = await getPR(token, owner, repo,
|
|
241
|
-
const linkMode = cfg
|
|
213
|
+
const pr = await getPR(token, prRepo.owner, prRepo.repo, prNum);
|
|
214
|
+
const linkMode = resolveLinkMode(cfg);
|
|
242
215
|
|
|
243
216
|
// Duas fontes de vínculo, nesta ordem: o que o GitHub reconhece nativamente
|
|
244
217
|
// (o mesmo que fecha a issue no merge, e que cobre o vínculo feito pela UI) e
|
|
245
218
|
// o que está escrito no corpo. `Implements #N` só existe na segunda.
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
219
|
+
// O vínculo nativo é sempre do repositório do PR — cross-repo o GitHub não
|
|
220
|
+
// popula (RFC-005 §4) — então só conta quando o PR está no próprio hub.
|
|
221
|
+
const linked = sameRepo(prRepo, hub)
|
|
222
|
+
? await getPRClosingIssues(token, prRepo.owner, prRepo.repo, prNum).catch(err => {
|
|
223
|
+
console.warn(`Não foi possível ler os vínculos nativos do PR: ${err.message}`);
|
|
224
|
+
return [];
|
|
225
|
+
})
|
|
226
|
+
: [];
|
|
227
|
+
const refs = extractIssueRefs(pr.body || '', { prRepo, linkMode });
|
|
228
|
+
const issueNums = [...new Set([...linked, ...hubIssueNumbers(refs, hub)])];
|
|
229
|
+
const foraDoHub = refs.filter(r => !sameRepo(r, hub));
|
|
230
|
+
if (foraDoHub.length > 0) {
|
|
231
|
+
console.log(
|
|
232
|
+
`Ignorando vínculo com issue de outro repositório: ${foraDoHub.map(r => `${r.owner}/${r.repo}#${r.number}`).join(', ')} ` +
|
|
233
|
+
`(o board é de ${owner}/${repo}).`
|
|
234
|
+
);
|
|
235
|
+
}
|
|
251
236
|
|
|
252
237
|
if (issueNums.length === 0) {
|
|
253
238
|
console.log(
|
|
@@ -291,6 +276,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
291
276
|
const featuresChecked = new Set();
|
|
292
277
|
const deferred = new Set();
|
|
293
278
|
const ignored = [];
|
|
279
|
+
const prontos = []; // PRs que saíram do rascunho porque a Feature terminou
|
|
294
280
|
|
|
295
281
|
// Regras ao abrir o PR: Tasks → 🎉 Done (implementação concluída);
|
|
296
282
|
// Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
|
|
@@ -371,7 +357,8 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
371
357
|
if (feature && !featuresChecked.has(feature.number)) {
|
|
372
358
|
featuresChecked.add(feature.number);
|
|
373
359
|
try {
|
|
374
|
-
const ready = await allStoriesReadyForReview(
|
|
360
|
+
const { ready, stories: featureStories } = await allStoriesReadyForReview(
|
|
361
|
+
token, projectToken, project, etapaField, feature.nodeId);
|
|
375
362
|
if (!ready) {
|
|
376
363
|
console.log(`Feature #${feature.number} mantida em desenvolvimento — ainda há Stories pendentes (fora de "${CODE_REVIEW_STAGE}").`);
|
|
377
364
|
} else if (!seen.has(feature.number)) {
|
|
@@ -385,6 +372,20 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
385
372
|
} else {
|
|
386
373
|
console.log(`Feature #${feature.number} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior.`);
|
|
387
374
|
}
|
|
375
|
+
// Plano B do desrascunho. O caminho normal é o `implement` marcar os
|
|
376
|
+
// PRs ao concluir a última Story; se ele não chegou lá (execução
|
|
377
|
+
// interrompida, PR aberto depois), a Feature avançaria de Etapa aqui
|
|
378
|
+
// com os PRs ainda em rascunho — pronta para review no board e
|
|
379
|
+
// impossível de mergear no GitHub. Best-effort, como o resto.
|
|
380
|
+
const marcados = await markFeaturePrsReady({
|
|
381
|
+
token, owner, repo, feature, stories: featureStories, linkMode,
|
|
382
|
+
// `updated` vira a lista "Board atualizado" no comentário do PR;
|
|
383
|
+
// desrascunhar não é movimento de board e ganha parágrafo próprio.
|
|
384
|
+
log: { info: console.log, success: console.log, warn: console.warn },
|
|
385
|
+
});
|
|
386
|
+
if (marcados.length > 0) {
|
|
387
|
+
prontos.push(...marcados);
|
|
388
|
+
}
|
|
388
389
|
}
|
|
389
390
|
} catch (err) {
|
|
390
391
|
console.warn(`Falha ao avaliar a Feature #${feature.number}: ${err.message}`);
|
|
@@ -392,7 +393,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
392
393
|
}
|
|
393
394
|
}
|
|
394
395
|
|
|
395
|
-
if (updated.length > 0 || deferred.size > 0) {
|
|
396
|
+
if (updated.length > 0 || deferred.size > 0 || prontos.length > 0) {
|
|
396
397
|
const partes = [];
|
|
397
398
|
if (updated.length > 0) {
|
|
398
399
|
partes.push(
|
|
@@ -401,6 +402,16 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
401
402
|
updated.map(f => `- ${f}`).join('\n')
|
|
402
403
|
);
|
|
403
404
|
}
|
|
405
|
+
// Quem revisa precisa saber POR QUE os PRs saíram do rascunho de uma vez:
|
|
406
|
+
// é o sinal de que a feature inteira acabou e pode ser revisada.
|
|
407
|
+
if (prontos.length > 0) {
|
|
408
|
+
partes.push(
|
|
409
|
+
`✅ **Feature concluída — PRs prontos para revisão:** ` +
|
|
410
|
+
`${[...new Set(prontos)].sort((a, b) => a - b).map(n => `#${n}`).join(', ')}.\n\n` +
|
|
411
|
+
'Todas as Stories terminaram, então os PRs saíram do rascunho juntos. ' +
|
|
412
|
+
'Enquanto uma feature está em desenvolvimento, os PRs dela ficam em rascunho de propósito.'
|
|
413
|
+
);
|
|
414
|
+
}
|
|
404
415
|
// O que ficou de fora precisa ser dito: silêncio aqui vira "o board está
|
|
405
416
|
// certo" na cabeça de quem lê, que é exatamente o erro que se quer evitar.
|
|
406
417
|
if (ignored.length > 0) {
|
|
@@ -415,7 +426,7 @@ export async function codeReview({ prNumber, resolveOnly = false }) {
|
|
|
415
426
|
`\`npx @spec-wave/cli@latest code-review --pr-number ${prNumber}\`.`
|
|
416
427
|
);
|
|
417
428
|
}
|
|
418
|
-
await commentOnIssue(token, owner, repo,
|
|
429
|
+
await commentOnIssue(token, prRepo.owner, prRepo.repo, prNum, partes.join('\n\n')).catch(() => {});
|
|
419
430
|
}
|
|
420
431
|
|
|
421
432
|
console.log(`code-review: ${updated.length} item(ns) atualizado(s) no board.`);
|
|
@@ -19,9 +19,10 @@
|
|
|
19
19
|
import { execSync } from 'node:child_process';
|
|
20
20
|
import { resolveToken } from '../api/auth.mjs';
|
|
21
21
|
import {
|
|
22
|
-
getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
|
|
22
|
+
getIssue, createIssue, createLabel, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
|
|
23
23
|
getRepoDefaultBranch,
|
|
24
24
|
} from '../api/github-rest.mjs';
|
|
25
|
+
import { codeRepositories, repoLabel } from '../lib/repo-role.mjs';
|
|
25
26
|
import { addSubIssue, listSubIssues, getProjectSnapshot } from '../api/github-graphql.mjs';
|
|
26
27
|
import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
|
|
27
28
|
import { generateDocument } from '../lib/claude.mjs';
|
|
@@ -282,6 +283,23 @@ async function publishFile(ctx, { doc, pathRel, content, nextLabel = null, extra
|
|
|
282
283
|
// Etapa 1: rascunho (label spec-wave:decompose)
|
|
283
284
|
// ---------------------------------------------------------------------------
|
|
284
285
|
|
|
286
|
+
/**
|
|
287
|
+
* Seção "Repositórios de código" da entrada do modelo (função PURA). Só existe
|
|
288
|
+
* no multi-repo: sem ela o prompt manda omitir `repos`, e é isso que mantém o
|
|
289
|
+
* rascunho do mono-repo idêntico ao de antes da RFC-005.
|
|
290
|
+
*
|
|
291
|
+
* @returns {string} '' no mono-repo
|
|
292
|
+
*/
|
|
293
|
+
export function codeReposPromptSection(config) {
|
|
294
|
+
const repos = codeRepositories(config);
|
|
295
|
+
if (repos.length === 0) return '';
|
|
296
|
+
return [
|
|
297
|
+
'\n## Repositórios de código',
|
|
298
|
+
'Este Project tem mais de um repositório. Cada Story precisa declarar em `repos` os slugs dos repositórios que ela toca, EXATAMENTE como listados:',
|
|
299
|
+
...repos.map(r => `- \`${r.slug}\` — ${r.owner}/${r.repo}`),
|
|
300
|
+
].join('\n');
|
|
301
|
+
}
|
|
302
|
+
|
|
285
303
|
async function draftDecomposition(ctx) {
|
|
286
304
|
const {
|
|
287
305
|
token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode,
|
|
@@ -357,7 +375,8 @@ async function draftDecomposition(ctx) {
|
|
|
357
375
|
`Issue #${issueNumber}`,
|
|
358
376
|
`\n## spec.md\n${specContent || '(spec.md não encontrado)'}`,
|
|
359
377
|
`\n## plan.md\n${planContent || '(plan.md não encontrado)'}`,
|
|
360
|
-
|
|
378
|
+
codeReposPromptSection(ctx.config),
|
|
379
|
+
].filter(Boolean).join('\n');
|
|
361
380
|
|
|
362
381
|
const decomposePrompt = loadPrompt(
|
|
363
382
|
type === 'RFC' ? 'decompose/rfc' : 'decompose/feature',
|
|
@@ -770,6 +789,49 @@ async function resolveExternalDeps({ token, owner, repo }, doc) {
|
|
|
770
789
|
return resolvidas;
|
|
771
790
|
}
|
|
772
791
|
|
|
792
|
+
/**
|
|
793
|
+
* Labels `repo:<slug>` que cada Story vai receber (RFC-005 §3.3), validadas
|
|
794
|
+
* ANTES da primeira criação — mesma razão do resolveExternalDeps: um slug que
|
|
795
|
+
* não está em `repositories[]` do hub é erro de escrita do rascunho, e o lugar
|
|
796
|
+
* de reprovar é antes de criar metade das Stories.
|
|
797
|
+
*
|
|
798
|
+
* As labels são criadas no hub best-effort (R4): `createIssue` recusa label
|
|
799
|
+
* inexistente com 422, e a UI cria a label ao vincular o repo, mas um hub
|
|
800
|
+
* editado à mão não passou por lá.
|
|
801
|
+
*
|
|
802
|
+
* @returns {Promise<Map<string, string[]>>} anchor da Story → labels
|
|
803
|
+
*/
|
|
804
|
+
async function resolveRepoLabels({ token, owner, repo, config }, doc) {
|
|
805
|
+
const porStory = new Map();
|
|
806
|
+
const slugs = [...new Set((doc.stories || []).flatMap(s => s.repos || []))].sort();
|
|
807
|
+
if (slugs.length === 0) return porStory;
|
|
808
|
+
|
|
809
|
+
const conhecidos = new Set(codeRepositories(config).map(r => r.slug));
|
|
810
|
+
const desconhecidos = slugs.filter(s => !conhecidos.has(s));
|
|
811
|
+
if (desconhecidos.length > 0) {
|
|
812
|
+
throw new Error(
|
|
813
|
+
`o rascunho declara repositório(s) que o hub não conhece: ${desconhecidos.join(', ')}. ` +
|
|
814
|
+
'Em "**Repos:**" só valem os slugs de `repositories[]` do .spec-wave.json' +
|
|
815
|
+
(conhecidos.size ? ` (${[...conhecidos].sort().join(', ')})` : ' — que está vazio: vincule o repo de código primeiro') +
|
|
816
|
+
'. Corrija o decomposition.md.'
|
|
817
|
+
);
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
for (const slug of slugs) {
|
|
821
|
+
const name = repoLabel(slug);
|
|
822
|
+
try {
|
|
823
|
+
// createLabel já engole o 422 de "já existe".
|
|
824
|
+
await createLabel(token, owner, repo, { name, color: '0e8a16', description: `Story toca o repositório ${slug}` });
|
|
825
|
+
} catch (err) {
|
|
826
|
+
console.warn(` Não consegui garantir a label ${name}: ${err.message}`);
|
|
827
|
+
}
|
|
828
|
+
}
|
|
829
|
+
for (const story of doc.stories || []) {
|
|
830
|
+
porStory.set(story.anchor, (story.repos || []).map(repoLabel));
|
|
831
|
+
}
|
|
832
|
+
return porStory;
|
|
833
|
+
}
|
|
834
|
+
|
|
773
835
|
async function createStoriesFromDoc(ctx, doc) {
|
|
774
836
|
const { token, projectToken, owner, repo, issue, issueNumber, project, docRel } = ctx;
|
|
775
837
|
const fields = { etapaField: ctx.etapaField, statusField: ctx.statusField, typeField: ctx.typeField };
|
|
@@ -780,6 +842,7 @@ async function createStoriesFromDoc(ctx, doc) {
|
|
|
780
842
|
// Antes da primeira criação: rascunho que aponta para issue inexistente é
|
|
781
843
|
// erro de escrita, e o lugar de reprovar é aqui.
|
|
782
844
|
const externas = await resolveExternalDeps(ctx, doc);
|
|
845
|
+
const repoLabels = await resolveRepoLabels(ctx, doc);
|
|
783
846
|
const created = [];
|
|
784
847
|
const createdStories = []; // issues criadas, na ordem dos índices das stories
|
|
785
848
|
const generatedTexts = []; // títulos+corpos para o lint de idioma final
|
|
@@ -806,7 +869,10 @@ async function createStoriesFromDoc(ctx, doc) {
|
|
|
806
869
|
const depLine = formatDependencyLine(depIssues.map(d => d.number));
|
|
807
870
|
if (depLine) storyBody += `\n\n${depLine}`;
|
|
808
871
|
|
|
809
|
-
|
|
872
|
+
// `repo:<slug>` já na criação (RFC-005 §6.2 item 6) — a label é a fonte de
|
|
873
|
+
// verdade de quais repositórios a Story toca; o campo do board é só espelho.
|
|
874
|
+
const labelsDoRepo = repoLabels.get(story.anchor) || [];
|
|
875
|
+
const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]', ...labelsDoRepo], { milestone });
|
|
810
876
|
ctx.createdItems.push(createdStory.number);
|
|
811
877
|
// Anota no doc em memória: é daqui que sai o `**Issue:** #N` gravado no
|
|
812
878
|
// arquivo no fim do apply.
|
|
@@ -840,7 +906,9 @@ async function createStoriesFromDoc(ctx, doc) {
|
|
|
840
906
|
console.log(` Criando task: ${task.title}`);
|
|
841
907
|
const taskTitle = `[TASK] ${task.title}`;
|
|
842
908
|
const taskBody = `${task.body}\n\n_Story pai: ${createdStory.url}_`;
|
|
843
|
-
|
|
909
|
+
// A Task herda os repos da Story (RFC-005 §5.2, `effectiveRepoSlugs`) —
|
|
910
|
+
// gravado na label em vez de inferido, para `order`/`implement` lerem direto.
|
|
911
|
+
const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]', ...labelsDoRepo], { milestone });
|
|
844
912
|
ctx.createdItems.push(createdTask.number);
|
|
845
913
|
task.issue = createdTask.number;
|
|
846
914
|
generatedTexts.push(taskTitle, taskBody);
|
|
@@ -1166,6 +1234,9 @@ export async function decompose({ issueNumber, apply }) {
|
|
|
1166
1234
|
// com o applyCtx: o catch externo precisa saber se houve criação para não
|
|
1167
1235
|
// aconselhar um retry que duplicaria itens.
|
|
1168
1236
|
createdItems: [],
|
|
1237
|
+
// `repositories[]` do hub: é contra ela que o apply valida os slugs de
|
|
1238
|
+
// "**Repos:**" antes de criar qualquer issue.
|
|
1239
|
+
config,
|
|
1169
1240
|
escalationModel: config?.ai?.escalationModel || null,
|
|
1170
1241
|
maxCritiqueAttempts:
|
|
1171
1242
|
Number.isInteger(config?.ai?.maxCritiqueAttempts) && config.ai.maxCritiqueAttempts > 0
|