@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
@@ -4,7 +4,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
4
4
  import { homedir } from 'node:os';
5
5
  import path from 'node:path';
6
6
  import { resolveToken } from '../api/auth.mjs';
7
- import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
7
+ import { CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
8
8
  import { getProjectSnapshot } from '../api/github-graphql.mjs';
9
9
  import {
10
10
  getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
@@ -25,6 +25,7 @@ import {
25
25
  } from './install-skill.mjs';
26
26
  import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
27
27
  import { findConfigPath } from '../lib/project-root.mjs';
28
+ import { configuredRole } from '../lib/repo-role.mjs';
28
29
  import { currentGitBranch } from '../lib/repo-links.mjs';
29
30
 
30
31
  // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
@@ -33,6 +34,16 @@ const REPO_FILES = [
33
34
  ...ISSUE_TEMPLATE_FILES.map(f => ({ repoPath: `.github/ISSUE_TEMPLATE/${f}`, template: ['issue', f] })),
34
35
  ];
35
36
 
37
+ // Por papel (RFC-005 §7.4): num repo de código o update NÃO pode subir os
38
+ // workflows do fluxo nem os issue templates — isso o converteria em hub. O que
39
+ // ele recebe são só os despachantes (templates/workflows/code/).
40
+ const CODE_REPO_FILES = CODE_WORKFLOW_FILES.map(f => ({
41
+ repoPath: `.github/workflows/${f}`, template: ['workflows', 'code', f],
42
+ }));
43
+ function repoFilesFor(role) {
44
+ return role === 'code' ? CODE_REPO_FILES : REPO_FILES;
45
+ }
46
+
36
47
  // Detecta se a skill instalada em cada agente diverge da versão atual da CLI.
37
48
  // Retorna os alvos desatualizados (conteúdo diferente ou ausente).
38
49
  function detectSkill(parsed, baseDir, isGlobal) {
@@ -186,6 +197,10 @@ export function shouldDeleteOrphanLabel({ inUse, forceLabels = false }) {
186
197
  * @returns {Promise<{ content: string|null, error: string|null }>}
187
198
  */
188
199
  async function buildConfigContent(token, config) {
200
+ // Repo de código: nada a consultar — o Project é do hub. Só a versão muda.
201
+ if (configuredRole(config) === 'code') {
202
+ return { content: `${JSON.stringify({ ...config, version: CLI_VERSION }, null, 2)}\n`, error: null };
203
+ }
189
204
  const snapshot = await getProjectSnapshot(token, config.project.id);
190
205
  if (!snapshot) return { content: null, error: 'Project não encontrado' };
191
206
  const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
@@ -306,8 +321,15 @@ export async function update(options = {}) {
306
321
  }
307
322
  }
308
323
 
324
+ // Papel do repo (RFC-005): num repo de código não há labels, issue templates
325
+ // nem Project a consultar — só o config (versão) e a skill.
326
+ const role = configuredRole(config);
327
+ if (role === 'code') {
328
+ p.log.info(`${CONFIG_FILE} declara role "code": labels e workflows do fluxo ficam no hub ${config?.hub?.owner ?? '?'}/${config?.hub?.repo ?? '?'}.`);
329
+ }
330
+
309
331
  const doConfig = !options.skipConfig && !!config;
310
- const doRepo = !options.skipRepo && !!config?.owner && !!config?.repo;
332
+ const doRepo = !options.skipRepo && !!config?.owner && !!config?.repo && repoFilesFor(role).length > 0;
311
333
 
312
334
  // Token resolvido sob demanda (necessário só para repo/config remoto).
313
335
  let token;
@@ -325,11 +347,12 @@ export async function update(options = {}) {
325
347
  // 2a) Config desatualizado? (versão divergente ou formato legado).
326
348
  let configStale = null;
327
349
  if (doConfig) {
328
- const legacy = !config.project?.fields;
350
+ // Repo de código não tem bloco `project` — o teste de formato legado é do hub.
351
+ const legacy = role !== 'code' && !config.project?.fields;
329
352
  if (config.version !== CLI_VERSION || legacy) {
330
353
  configStale = {
331
354
  reason: legacy ? 'formato legado (sem project.fields)' : `versão ${config.version ?? '?'} ≠ ${CLI_VERSION}`,
332
- canApply: !!config.project?.id,
355
+ canApply: role === 'code' || !!config.project?.id,
333
356
  };
334
357
  }
335
358
  }
@@ -349,7 +372,7 @@ export async function update(options = {}) {
349
372
  p.log.warn(`Sem token do GitHub (${tokenError?.message ?? 'indisponível'}); pulando verificação do repo.`);
350
373
  } else {
351
374
  try {
352
- for (const f of REPO_FILES) {
375
+ for (const f of repoFilesFor(role)) {
353
376
  const remote = await getFileContent(tk, owner, repo, f.repoPath);
354
377
  const local = readTemplate(...f.template);
355
378
  if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
@@ -624,12 +647,12 @@ export async function update(options = {}) {
624
647
  if (!configStale.canApply) {
625
648
  p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx @spec-wave/cli@latest init\` (sem --skip-project).`);
626
649
  } else {
627
- const tk = await getToken();
628
- if (!tk) {
650
+ const tk = role === 'code' ? null : await getToken();
651
+ if (role !== 'code' && !tk) {
629
652
  p.log.warn(`${CONFIG_FILE}: sem token — pulei. (${tokenError?.message ?? ''})`);
630
653
  } else {
631
654
  const s = p.spinner();
632
- s.start('Consultando o Project para atualizar o .spec-wave.json...');
655
+ s.start(role === 'code' ? `Atualizando a versão do ${CONFIG_FILE}...` : 'Consultando o Project para atualizar o .spec-wave.json...');
633
656
  try {
634
657
  const { content, error } = await buildConfigContent(tk, config);
635
658
  if (error) throw new Error(error);
@@ -9,7 +9,7 @@ import {
9
9
  import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
10
10
  import { bugDocPaths, describeMissingSections } from '../lib/bug-doc.mjs';
11
11
  import { detectIssueType } from '../lib/issue-type.mjs';
12
- import { loadConfig } from '../lib/project-root.mjs';
12
+ import { resolveHubContext } from '../lib/project-root.mjs';
13
13
  import { executionMode } from '../lib/flow-run.mjs';
14
14
  import { docBlobUrl } from '../lib/repo-links.mjs';
15
15
  import { loadArtifact } from '../lib/doc-source.mjs';
@@ -161,10 +161,7 @@ export function renderMissingSection(doc, { section, found }) {
161
161
  */
162
162
  export async function validate({ issueNumber }) {
163
163
  const token = await resolveToken();
164
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
165
- const { config: cfg, root } = loadConfig();
166
- const owner = envOwner || cfg?.owner;
167
- const repo = envRepo || cfg?.repo;
164
+ const { owner, repo, config: cfg, root } = resolveHubContext();
168
165
 
169
166
  if (!owner || !repo) {
170
167
  throw new Error(
@@ -0,0 +1,112 @@
1
+ // `spec-wave workspace prepare --issue <n>` (RFC-005 §7.2): materializa, ao
2
+ // lado do hub, os repositórios de código que uma issue declara (labels
3
+ // `repo:<slug>`; uma Feature agrega os das Stories). Serve os três executores:
4
+ // no dev local resolve irmãos/override, no Action clona, e o `implement` lê o
5
+ // mesmo layout para preencher {workspaceDir}/{repoDirs}.
6
+ import * as p from '@clack/prompts';
7
+ import chalk from 'chalk';
8
+ import { resolveToken } from '../api/auth.mjs';
9
+ import { getIssue } from '../api/github-rest.mjs';
10
+ import { detectIssueType } from '../lib/issue-type.mjs';
11
+ import { resolveHubContext } from '../lib/project-root.mjs';
12
+ import { cachedSubIssues } from '../lib/story-graph.mjs';
13
+ import { resolveCacheTtl } from '../lib/net-cache.mjs';
14
+ import { codeRepositories } from '../lib/repo-role.mjs';
15
+ import {
16
+ slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, prepareWorkspace, renderRepoDirs,
17
+ WORKSPACE_OVERRIDE_FILE,
18
+ } from '../lib/workspace.mjs';
19
+ import { CONFIG_FILE } from '../config.mjs';
20
+
21
+ export async function workspace({ action, issue: issueArg, json = false, dryRun = false, refresh = false } = {}) {
22
+ if (action !== 'prepare') {
23
+ throw new Error(`Ação inválida: "${action}". Use \`spec-wave workspace prepare --issue <n>\`.`);
24
+ }
25
+ const issueNumber = parseInt(String(issueArg ?? '').replace('#', ''), 10);
26
+ if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
27
+ throw new Error('Informe a issue: `spec-wave workspace prepare --issue <n>` (Feature, Story ou Task).');
28
+ }
29
+
30
+ const { owner, repo, root, config, role, self, error } = resolveHubContext();
31
+ if (role === 'code') {
32
+ throw new Error(
33
+ `${self.owner}/${self.repo} é um repositório de código; o workspace é montado a partir do hub` +
34
+ (owner && repo ? ` ${owner}/${repo}.` : '.') + (error ? `\n${error}` : '')
35
+ );
36
+ }
37
+ if (!owner || !repo || !root) {
38
+ throw new Error(`Rode dentro do hub (diretório com ${CONFIG_FILE}) — ${error || 'owner/repo não resolvidos'}.`);
39
+ }
40
+
41
+ const log = json ? { info() {}, warn: (m) => console.error(m) } : { info: p.log.info, warn: p.log.warn };
42
+ const token = await resolveToken();
43
+ const issue = await getIssue(token, owner, repo, issueNumber);
44
+ const type = detectIssueType(issue);
45
+
46
+ let children = [];
47
+ if (type === 'Feature' || type === 'Epic') {
48
+ const { subs } = await cachedSubIssues({
49
+ token, owner, repo, root, refresh, ttlSec: resolveCacheTtl(config),
50
+ parent: { number: issue.number, nodeId: issue.node_id },
51
+ }).catch(() => ({ subs: [] }));
52
+ children = subs;
53
+ }
54
+ const slugs = slugsForItem({ labels: issue.labels, children });
55
+
56
+ // Feature sem repo declarado degrada para o hub (mono-repo), COM aviso: um
57
+ // Glob que não acha nada é indistinguível de um repo ausente (§7.2).
58
+ if (slugs.length === 0) {
59
+ const vinculados = codeRepositories(config);
60
+ log.warn(
61
+ `#${issueNumber} (${type ?? 'tipo não identificado'}) não declara repositório (label repo:<slug>)` +
62
+ (vinculados.length ? ` — o hub tem ${vinculados.map(r => r.slug).join(', ')} vinculado(s).` : ' — e o hub não tem repos de código vinculados (mono-repo).')
63
+ );
64
+ const layout = resolveWorkspaceLayout({ root, config, slugs: [] });
65
+ emit({ json, layout, issueNumber, cloned: [], missing: [], dryRun });
66
+ return { layout, cloned: [], missing: [] };
67
+ }
68
+
69
+ const layout = resolveWorkspaceLayout({ root, config, slugs, override: readWorkspaceOverride(root) });
70
+ if (layout.unknown.length > 0) {
71
+ throw new Error(
72
+ `#${issueNumber} declara repositório(s) que o hub não conhece: ${layout.unknown.join(', ')}. ` +
73
+ `Registre em \`repositories[]\` do ${CONFIG_FILE} do hub (slug, owner, repo).`
74
+ );
75
+ }
76
+
77
+ if (dryRun) {
78
+ log.info(`Dry-run: nada clonado. Workspace: ${layout.workspaceDir}`);
79
+ for (const r of layout.repos) {
80
+ log.info(` ${r.slug} → ${r.dir} (${r.source}${r.present ? '' : ', ausente — seria clonado'})`);
81
+ }
82
+ emit({ json, layout, issueNumber, cloned: [], missing: [], dryRun: true });
83
+ return { layout, cloned: [], missing: [] };
84
+ }
85
+
86
+ const isActions = process.env.GITHUB_ACTIONS === 'true';
87
+ const { cloned, missing } = await prepareWorkspace({
88
+ layout, token: isActions ? token : null, shallow: isActions, log,
89
+ });
90
+ if (!json) {
91
+ for (const r of layout.repos) {
92
+ p.log.success(`${r.slug} → ${chalk.cyan(r.dir)} (${cloned.includes(r.slug) ? 'clonado' : r.source})`);
93
+ }
94
+ if (missing.length > 0) p.log.warn(`Ausente(s): ${missing.join(', ')} — ajuste ${WORKSPACE_OVERRIDE_FILE} ou clone ao lado do hub.`);
95
+ }
96
+ emit({ json, layout, issueNumber, cloned, missing });
97
+ return { layout, cloned, missing };
98
+ }
99
+
100
+ function emit({ json, layout, issueNumber, cloned, missing, dryRun = false }) {
101
+ if (!json) return;
102
+ console.log(JSON.stringify({
103
+ issue: issueNumber,
104
+ dryRun,
105
+ workspaceDir: layout.workspaceDir,
106
+ hubDir: layout.hubDir,
107
+ repos: layout.repos.map(r => ({ slug: r.slug, owner: r.owner, repo: r.repo, dir: r.dir, source: r.source, present: r.present })),
108
+ repoDirs: renderRepoDirs(layout.repos),
109
+ cloned,
110
+ missing,
111
+ }, null, 2));
112
+ }
package/src/config.mjs CHANGED
@@ -600,8 +600,27 @@ export const WORKFLOW_FILES = [
600
600
  'generate-qa-plan.yml',
601
601
  'code-review.yml',
602
602
  'qa.yml',
603
+ 'pr-events.yml',
603
604
  ];
604
605
 
606
+ /**
607
+ * Workflows de um repositório de CÓDIGO (RFC-005 §7.1/§7.3): despachantes
608
+ * finos que não rodam a CLI nem tocam no board — só disparam um
609
+ * `repository_dispatch` para o hub, que recebe em `pr-events.yml`. Vivem em
610
+ * templates/workflows/code/ e têm os MESMOS nomes dos workflows do hub, para
611
+ * que um repo que troque de papel não fique com dois arquivos.
612
+ */
613
+ export const CODE_WORKFLOW_FILES = [
614
+ 'code-review.yml',
615
+ 'qa.yml',
616
+ ];
617
+
618
+ /** `event_type` do repository_dispatch que os despachantes mandam ao hub. */
619
+ export const HUB_DISPATCH_EVENT = 'spec-wave-pr';
620
+
621
+ /** Secret, no repo de código, com um token que pode despachar para o hub. */
622
+ export const HUB_DISPATCH_SECRET = 'SPEC_WAVE_HUB_TOKEN';
623
+
605
624
  /**
606
625
  * Workflows que PUBLICAM um documento gerado (branch própria + Pull Request).
607
626
  *
@@ -145,7 +145,7 @@ export function artifactCommitMessage({ doc, issueNumber, pathRel } = {}) {
145
145
  *
146
146
  * **A issue é referenciada SÓ pela URL completa.** Não é preciosismo: o
147
147
  * `code-review` extrai o vínculo do corpo do PR e MOVE O BOARD a partir dele
148
- * (`extractIssueNumbers`, commands/code-review.mjs). São duas regexes:
148
+ * (`extractIssueRefs`, lib/pr-link.mjs). São duas regexes:
149
149
  *
150
150
  * • `EXPLICIT_LINK_RE` exige um verbo (`closes|fixes|resolves|implements`);
151
151
  * • `ANY_MENTION_RE`, ativa sob `codeReview.linkMode: "any-mention"`, casa
@@ -18,12 +18,15 @@ import { slugify } from './slugify.mjs';
18
18
  *
19
19
  * @param {string} title título da issue (com ou sem o prefixo [BUG])
20
20
  * @param {string} [root] raiz do repositório; ausente = process.cwd()
21
- * @returns {{ slug: string, dirRel: string, fileRel: string, dirAbs: string, fileAbs: string }}
21
+ * @returns {{ slug: string, dirRel: string, fileRel: string, dirAbs: string, fileAbs: string, qaEvidenceDirRel: string, qaEvidenceDirAbs: string }}
22
22
  */
23
23
  export function bugDocPaths(title, root = null) {
24
24
  const slug = slugify(title);
25
25
  const dirRel = `docs/bugs/${slug}`;
26
26
  const fileRel = `${dirRel}/bug.md`;
27
+ // Evidência visual do `qa <bug>` (Teste de Regressão = cenário 1), no mesmo
28
+ // desenho de docs/features/<slug>/qa/ — ver featureDocPaths().
29
+ const qaEvidenceDirRel = `${dirRel}/qa`;
27
30
  const base = root || process.cwd();
28
31
  return {
29
32
  slug,
@@ -31,6 +34,8 @@ export function bugDocPaths(title, root = null) {
31
34
  fileRel,
32
35
  dirAbs: path.resolve(base, dirRel),
33
36
  fileAbs: path.resolve(base, fileRel),
37
+ qaEvidenceDirRel,
38
+ qaEvidenceDirAbs: path.resolve(base, qaEvidenceDirRel),
34
39
  };
35
40
  }
36
41
 
@@ -511,6 +511,10 @@ async function generateViaEngine(
511
511
  ) {
512
512
  const result = await runAgent(userContent, {
513
513
  provider: ai.backend,
514
+ // A credencial do provider escolhido. `anthropic` e `claude-oauth` caem no
515
+ // mesmo backend, e sem isto o Claude Code resolve credencial sozinho — com
516
+ // ANTHROPIC_API_KEY na frente do token da assinatura.
517
+ credentialVar: ai.secret,
514
518
  model: ai.model,
515
519
  systemPromptAppend: systemPrompt,
516
520
  // Sessão/usuário alimentam o agrupamento das traces no Langfuse. Sem
@@ -21,6 +21,7 @@
21
21
  //
22
22
  // **User story:** Como <perfil>, quero <objetivo>, para <benefício>
23
23
  // **Depende de:** Story 1, #412 (ou "—" para nenhuma)
24
+ // **Repos:** api, web (opcional — só no multi-repo, RFC-005)
24
25
  //
25
26
  // <corpo livre, multi-linha>
26
27
  //
@@ -49,6 +50,11 @@ const H1_RE = /^#[ \t]+(.*)$/;
49
50
  const MARKER_RE = /^<!--[ \t]*spec-wave:decomposition[ \t]+(.*?)-->[ \t]*$/i;
50
51
  const USER_STORY_RE = /^\*\*User story:?\*\*:?[ \t]*(.*)$/i;
51
52
  const DEPENDS_RE = /^\*\*Depende de:?\*\*:?[ \t]*(.*)$/i;
53
+ // Repositórios de código que a Story toca (RFC-005 §3.3): slugs de
54
+ // `repositories[]` do hub, que o apply transforma em labels `repo:<slug>`.
55
+ // Mesma gramática que a UI parseia (shared/src/decomposition.ts).
56
+ const REPOS_RE = /^\*\*Repos?(?:it[óo]rios?)?:?\*\*:?[ \t]*(.*)$/i;
57
+ const REPO_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38})$/;
52
58
  // Gravado pelo `decompose-apply` DEPOIS de criar a issue. É o que liga o
53
59
  // rascunho ao que existe de fato no GitHub — sem isso o arquivo continua
54
60
  // descrevendo a proposta original para sempre, e um rescopo feito nas issues
@@ -176,6 +182,17 @@ function normalizeDependsOnIssues(list) {
176
182
  return [...new Set(list.filter(n => Number.isInteger(n) && n > 0))].sort((a, b) => a - b);
177
183
  }
178
184
 
185
+ // Slugs de repositório: minúsculas, sem repetição, ordenados — canônico, para
186
+ // que duas escritas do mesmo conteúdo deem o mesmo arquivo. Slug inválido é
187
+ // descartado aqui (JSON do modelo); no parse de arquivo editado à mão é erro.
188
+ function normalizeRepos(list) {
189
+ if (!Array.isArray(list)) return [];
190
+ const slugs = list
191
+ .map(s => String(s ?? '').trim().toLowerCase())
192
+ .filter(s => REPO_SLUG_RE.test(s));
193
+ return [...new Set(slugs)].sort();
194
+ }
195
+
179
196
  /**
180
197
  * Renderiza o decomposition.md (função PURA — testável).
181
198
  *
@@ -248,6 +265,11 @@ export function renderDecompositionDoc({
248
265
  `**User story:** ${flatten(story?.userStory) || '—'}`,
249
266
  `**Depende de:** ${refs.length ? refs.join(', ') : '—'}`,
250
267
  ];
268
+ // Só quando há repos: no mono-repo o arquivo continua byte a byte igual
269
+ // ao de antes da RFC-005, e o parse de linha ausente dá [] — o round-trip
270
+ // fecha nos dois casos.
271
+ const repos = normalizeRepos(story?.repos);
272
+ if (repos.length > 0) campos.push(`**Repos:** ${repos.join(', ')}`);
251
273
  const linhaIssue = issueLine(story);
252
274
  if (linhaIssue) campos.push(linhaIssue);
253
275
  blocks.push(campos.join('\n'));
@@ -374,18 +396,23 @@ function splitStorySection(lines, anchor) {
374
396
  while (i < lines.length && !lines[i].trim()) i++;
375
397
  let userStory = null;
376
398
  let depends = null;
399
+ let repos = null;
377
400
  let issue = null;
378
401
  while (i < lines.length && lines[i].trim()) {
379
402
  const us = USER_STORY_RE.exec(lines[i]);
380
403
  const dep = us ? null : DEPENDS_RE.exec(lines[i]);
381
- const iss = us || dep ? null : ISSUE_RE.exec(lines[i]);
382
- if (!us && !dep && !iss) break;
404
+ const rep = us || dep ? null : REPOS_RE.exec(lines[i]);
405
+ const iss = us || dep || rep ? null : ISSUE_RE.exec(lines[i]);
406
+ if (!us && !dep && !rep && !iss) break;
383
407
  if (us) {
384
408
  if (userStory !== null) throw invalid(`${anchor} tem duas linhas "**User story:**"`);
385
409
  userStory = us[1].trim();
386
410
  } else if (dep) {
387
411
  if (depends !== null) throw invalid(`${anchor} tem duas linhas "**Depende de:**"`);
388
412
  depends = dep[1].trim();
413
+ } else if (rep) {
414
+ if (repos !== null) throw invalid(`${anchor} tem duas linhas "**Repos:**"`);
415
+ repos = rep[1].trim();
389
416
  } else {
390
417
  if (issue !== null) throw invalid(`${anchor} tem duas linhas "**Issue:**"`);
391
418
  issue = parseInt(iss[1], 10);
@@ -395,11 +422,36 @@ function splitStorySection(lines, anchor) {
395
422
  return {
396
423
  userStory: !userStory || EMPTY_VALUE_RE.test(userStory) ? '' : userStory,
397
424
  depends,
425
+ repos,
398
426
  issue,
399
427
  body: readBody(lines.slice(i)),
400
428
  };
401
429
  }
402
430
 
431
+ /**
432
+ * Interpreta o valor de "**Repos:**" (função PURA): slugs separados por
433
+ * vírgula, ou "—" para nenhum. Num arquivo editado à mão, slug inválido é
434
+ * ERRO citando a âncora — descartar em silêncio esconderia o engano, e a label
435
+ * `repo:<slug>` que o apply criaria não bateria com nenhum repositório.
436
+ *
437
+ * @returns {string[]} slugs canônicos (minúsculas, sem repetição, ordenados)
438
+ */
439
+ function parseReposValue(raw, anchor) {
440
+ if (raw === null || raw === undefined) return [];
441
+ const value = raw.trim();
442
+ if (!value || EMPTY_VALUE_RE.test(value)) return [];
443
+ const slugs = value.split(/[,;\s]+/).filter(Boolean).map(s => s.replace(/^`|`$/g, ''));
444
+ for (const slug of slugs) {
445
+ if (!REPO_SLUG_RE.test(slug)) {
446
+ throw invalid(
447
+ `não entendi "**Repos:** ${value}" em ${anchor} — "${slug}" não é um slug de repositório ` +
448
+ '(minúsculas, [a-z0-9-], até 39 caracteres). Use os slugs de `repositories[]` do .spec-wave.json, separados por vírgula, ou "—"'
449
+ );
450
+ }
451
+ }
452
+ return [...new Set(slugs)].sort();
453
+ }
454
+
403
455
  /**
404
456
  * Interpreta o decomposition.md (função PURA — testável).
405
457
  *
@@ -519,7 +571,7 @@ export function parseDecompositionDoc(markdown) {
519
571
  for (const section of sections) {
520
572
  if (section.type === 'story') {
521
573
  const anchor = `Story ${doc.stories.length + 1}`;
522
- const { userStory, depends, issue, body } = splitStorySection(section.lines, anchor);
574
+ const { userStory, depends, repos, issue, body } = splitStorySection(section.lines, anchor);
523
575
  doc.stories.push({
524
576
  anchor,
525
577
  title: requireTitle(section.title, anchor),
@@ -530,6 +582,7 @@ export function parseDecompositionDoc(markdown) {
530
582
  const { siblings, issues } = parseDependsValue(depends, doc.stories.length, anchor);
531
583
  return { dependsOn: siblings, dependsOnIssues: issues };
532
584
  })(),
585
+ repos: parseReposValue(repos, anchor),
533
586
  tasks: [],
534
587
  });
535
588
  continue;
@@ -118,6 +118,9 @@ export function storiesFromAppliedDoc(doc) {
118
118
  ...(s.dependsOnIssues || []),
119
119
  ])].filter(n => n !== s.issue).sort((a, b) => a - b),
120
120
  tasks: (s.tasks || []).map(t => t.issue).filter(n => Number.isInteger(n) && n > 0),
121
+ // Repositórios que a Story toca (RFC-005) — para order/implement lerem
122
+ // do mapa sem reparsear o doc. [] = mono-repo ou não declarado.
123
+ repos: Array.isArray(s.repos) ? [...s.repos] : [],
121
124
  index: i,
122
125
  })),
123
126
  };
@@ -35,7 +35,7 @@ export function resolveDocDir(root, issue, type) {
35
35
  * @param {string|null} root
36
36
  * @param {{title?: string}} issue
37
37
  * @param {string|null} [type]
38
- * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition, 'qa-plan'}} cada documento com {rel, abs}
38
+ * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition, 'qa-plan', 'dependency-map', qaEvidenceDir}} cada documento com {rel, abs}
39
39
  */
40
40
  export function featureDocPaths(root, issue, type) {
41
41
  const { slug, rel, dir } = resolveDocDir(root, issue, type);
@@ -54,5 +54,10 @@ export function featureDocPaths(root, issue, type) {
54
54
  // pelo decompose --apply, atualizado pelo `order --sync`, lido por
55
55
  // order/implement/merge/qa-lead no lugar de N chamadas de API.
56
56
  'dependency-map': doc('dependency-map.json'),
57
+ // Evidência visual da execução do QA (vídeo/foto por cenário), publicada
58
+ // pelo `qa <issue>` em `qa/cenario-<n>/` — <n> é o número POSICIONAL do
59
+ // cenário no qa-plan.md (o mesmo do `--only`). CONTRATO com a UI: arquivos
60
+ // planos dentro de cada `cenario-<n>/`, sem subpasta.
61
+ qaEvidenceDir: doc('qa'),
57
62
  };
58
63
  }
@@ -20,7 +20,7 @@
20
20
  // documento, e mora em lib/artifact-publish.mjs. As duas exceções eram
21
21
  // consequência de mexer em git local — some a causa, somem elas.
22
22
 
23
- import { resolveRepoContext } from './project-root.mjs';
23
+ import { resolveHubContext } from './project-root.mjs';
24
24
  import { CONFIG_FILE } from '../config.mjs';
25
25
 
26
26
  /** Rodando dentro do GitHub Actions? (função PURA) */
@@ -37,7 +37,8 @@ export function executionMode(env = process.env) {
37
37
  * Resolve owner/repo + modo, ou lança com a instrução certa para cada contexto.
38
38
  *
39
39
  * Nos Actions o `GITHUB_REPOSITORY` vem do runner; local, o `.spec-wave.json`
40
- * gravado pelo `init` é a fonte. `resolveRepoContext` já cobre os dois.
40
+ * gravado pelo `init` é a fonte. `resolveHubContext` já cobre os dois — e,
41
+ * num repo de código, devolve o hub declarado no config.
41
42
  *
42
43
  * @param {object} [opts]
43
44
  * @param {string} [opts.cwd]
@@ -53,9 +54,19 @@ export function executionMode(env = process.env) {
53
54
  export function resolveFlowContext({ cwd = process.cwd(), command = 'este comando', env = process.env, requireRoot = false } = {}) {
54
55
  // Repassa o `env` recebido: sem isso o modo local fica intestável dentro do
55
56
  // GitHub Actions, que define GITHUB_REPOSITORY em toda execução.
56
- const { owner, repo, root, config } = resolveRepoContext(cwd, env);
57
+ const { owner, repo, root, config, role, self, error } = resolveHubContext(cwd, env);
57
58
  const mode = executionMode(env);
58
59
 
60
+ // Os documentos e as issues vivem no hub; um repo de código não executa o
61
+ // fluxo (RFC-005 §7.5). Rodar aqui gravaria docs/features/ no lugar errado.
62
+ if (role === 'code') {
63
+ throw new Error(
64
+ `${self.owner}/${self.repo} é um repositório de código (role "code" no ${CONFIG_FILE}); ` +
65
+ `\`spec-wave ${command}\` roda no hub` + (owner && repo ? ` ${owner}/${repo}.` : '.') +
66
+ (error ? `\n${error}` : '')
67
+ );
68
+ }
69
+
59
70
  if (!owner || !repo) {
60
71
  throw new Error(
61
72
  'Não foi possível determinar owner/repo.\n' +
@@ -0,0 +1,109 @@
1
+ // Vínculo PR → issue: quais issues um PR declara implementar.
2
+ //
3
+ // Mora no lib porque três consumidores dependem da MESMA régua e não podem
4
+ // divergir: o `code-review` (o que mover no board), o `merge` (achar o PR de
5
+ // cada Story numa pilha) e o desrascunho (quais PRs são desta Feature). Estava
6
+ // em commands/code-review.mjs; quando lib/pr-ready.mjs passou a precisar dele,
7
+ // o import formava ciclo (code-review → pr-ready → code-review).
8
+ //
9
+ // Cada referência carrega o repositório: `Closes acme/hub#412` num PR de
10
+ // `acme/api` aponta para o hub, e um `#412` solto aponta para o próprio repo
11
+ // do PR. Descartar o repositório (como a versão antiga fazia) mandava o passo
12
+ // seguinte buscar `acme/api#412` — 404 silenciado, ou a issue errada.
13
+
14
+ // Vínculo EXPLÍCITO: o verbo é obrigatório. `Relacionado: #10` e `#10` solto
15
+ // deixaram de contar — referência cruzada em PR é prática comum (uma PR de
16
+ // documentação citando três Features moveu as três para 👀 Code Review, e uma
17
+ // delas nem plano tinha). Aceita `#N`, `owner/repo#N` e a URL completa da issue.
18
+ const EXPLICIT_LINK_RE =
19
+ /\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;
20
+
21
+ // Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`. Só `#N`,
22
+ // sempre no repo do PR.
23
+ const ANY_MENTION_RE = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
24
+
25
+ // Blocos de código não são vínculo: um `Closes #12` dentro de um exemplo de
26
+ // commit message é documentação, não promessa.
27
+ function stripCodeBlocks(body) {
28
+ return String(body)
29
+ .replace(/^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1[ \t]*$/gm, '\n')
30
+ .replace(/`[^`\n]*`/g, ' ');
31
+ }
32
+
33
+ /** @typedef {{ owner: string, repo: string, number: number }} IssueRef */
34
+
35
+ function refKey({ owner, repo, number }) {
36
+ return `${owner.toLowerCase()}/${repo.toLowerCase()}#${number}`;
37
+ }
38
+
39
+ /** Owner e repo do GitHub não diferenciam maiúsculas. */
40
+ export function sameRepo(a, b) {
41
+ return !!a && !!b &&
42
+ a.owner.toLowerCase() === b.owner.toLowerCase() &&
43
+ a.repo.toLowerCase() === b.repo.toLowerCase();
44
+ }
45
+
46
+ /**
47
+ * Issues que o PR declara implementar, com o repositório de cada uma
48
+ * (função PURA — testável).
49
+ *
50
+ * @param {string} body corpo do PR
51
+ * @param {object} opts
52
+ * @param {{ owner: string, repo: string }} opts.prRepo repositório onde o PR
53
+ * vive — é o que um `#N` sem qualificação significa
54
+ * @param {'explicit'|'any-mention'} [opts.linkMode='explicit']
55
+ * @returns {IssueRef[]} na ordem em que aparecem, sem repetição
56
+ */
57
+ export function extractIssueRefs(body, { prRepo, linkMode = 'explicit' } = {}) {
58
+ if (!prRepo?.owner || !prRepo?.repo) {
59
+ throw new TypeError('extractIssueRefs exige prRepo {owner, repo}: um `#N` solto só tem sentido dentro de um repositório.');
60
+ }
61
+ if (!body) return [];
62
+ const seen = new Set();
63
+ const refs = [];
64
+ const text = stripCodeBlocks(body);
65
+ const re = linkMode === 'any-mention' ? ANY_MENTION_RE : EXPLICIT_LINK_RE;
66
+ re.lastIndex = 0;
67
+ for (const m of text.matchAll(re)) {
68
+ const ref = linkMode === 'any-mention' ? anyMentionRef(m, prRepo) : explicitRef(m, prRepo);
69
+ if (!ref) continue;
70
+ const key = refKey(ref);
71
+ if (seen.has(key)) continue;
72
+ seen.add(key);
73
+ refs.push(ref);
74
+ }
75
+ return refs;
76
+ }
77
+
78
+ function explicitRef(m, prRepo) {
79
+ const [, urlOwner, urlRepo, urlNum, shortOwner, shortRepo, shortNum, bareNum] = m;
80
+ if (urlNum) return { owner: urlOwner, repo: urlRepo, number: parseInt(urlNum, 10) };
81
+ if (shortNum) return { owner: shortOwner, repo: shortRepo, number: parseInt(shortNum, 10) };
82
+ const n = parseInt(bareNum || '', 10);
83
+ return n ? { owner: prRepo.owner, repo: prRepo.repo, number: n } : null;
84
+ }
85
+
86
+ function anyMentionRef(m, prRepo) {
87
+ const n = parseInt(m[1] || m[2] || '', 10);
88
+ return n ? { owner: prRepo.owner, repo: prRepo.repo, number: n } : null;
89
+ }
90
+
91
+ /**
92
+ * Só os números das referências que apontam para `hub` — o repositório dono
93
+ * do board. Uma referência a outro repositório não é um vínculo deste fluxo.
94
+ *
95
+ * @param {IssueRef[]} refs
96
+ * @param {{ owner: string, repo: string }} hub
97
+ * @returns {number[]}
98
+ */
99
+ export function hubIssueNumbers(refs, hub) {
100
+ return refs.filter(r => sameRepo(r, hub)).map(r => r.number);
101
+ }
102
+
103
+ /**
104
+ * O `linkMode` configurado em `.spec-wave.json`, normalizado.
105
+ * Qualquer valor que não seja `any-mention` cai no padrão `explicit`.
106
+ */
107
+ export function resolveLinkMode(config) {
108
+ return config?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
109
+ }