@spec-wave/cli 0.35.0 → 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 (41) hide show
  1. package/package.json +2 -2
  2. package/src/agent/anthropic-agent.mjs +35 -2
  3. package/src/api/github-rest.mjs +23 -0
  4. package/src/cli.mjs +23 -0
  5. package/src/commands/code-review.mjs +31 -17
  6. package/src/commands/decompose.mjs +75 -4
  7. package/src/commands/doctor.mjs +43 -3
  8. package/src/commands/implement.mjs +39 -6
  9. package/src/commands/init.mjs +147 -29
  10. package/src/commands/merge.mjs +11 -8
  11. package/src/commands/move.mjs +4 -7
  12. package/src/commands/order.mjs +2 -2
  13. package/src/commands/qa.mjs +22 -21
  14. package/src/commands/repair-stage.mjs +2 -5
  15. package/src/commands/story.mjs +2 -2
  16. package/src/commands/task.mjs +2 -2
  17. package/src/commands/triage.mjs +2 -5
  18. package/src/commands/update.mjs +31 -8
  19. package/src/commands/validate.mjs +2 -5
  20. package/src/commands/workspace.mjs +112 -0
  21. package/src/config.mjs +19 -0
  22. package/src/lib/artifact-pr.mjs +1 -1
  23. package/src/lib/claude.mjs +4 -0
  24. package/src/lib/decomposition-doc.mjs +56 -3
  25. package/src/lib/dependency-map.mjs +3 -0
  26. package/src/lib/flow-run.mjs +14 -3
  27. package/src/lib/pr-link.mjs +65 -10
  28. package/src/lib/pr-ready.mjs +6 -2
  29. package/src/lib/project-root.mjs +51 -0
  30. package/src/lib/repo-role.mjs +102 -0
  31. package/src/lib/workspace.mjs +151 -0
  32. package/src/plugin/.claude-plugin/plugin.json +1 -1
  33. package/src/plugin/skills/decompose/SKILL.md +1 -0
  34. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  35. package/src/plugin/skills/implement/SKILL.md +1 -1
  36. package/src/plugin/skills/setup/SKILL.md +12 -0
  37. package/src/setup/files.mjs +35 -13
  38. package/src/templates/skill/SKILL.md +14 -1
  39. package/src/templates/workflows/code/code-review.yml +60 -0
  40. package/src/templates/workflows/code/qa.yml +59 -0
  41. package/src/templates/workflows/pr-events.yml +116 -0
@@ -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
@@ -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
  };
@@ -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' +
@@ -5,15 +5,21 @@
5
5
  // cada Story numa pilha) e o desrascunho (quais PRs são desta Feature). Estava
6
6
  // em commands/code-review.mjs; quando lib/pr-ready.mjs passou a precisar dele,
7
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.
8
13
 
9
14
  // Vínculo EXPLÍCITO: o verbo é obrigatório. `Relacionado: #10` e `#10` solto
10
15
  // deixaram de contar — referência cruzada em PR é prática comum (uma PR de
11
16
  // documentação citando três Features moveu as três para 👀 Code Review, e uma
12
17
  // delas nem plano tinha). Aceita `#N`, `owner/repo#N` e a URL completa da issue.
13
18
  const EXPLICIT_LINK_RE =
14
- /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implement(?:s|ed)?)\b\s*:?\s+(?:https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/(\d+)|[\w.-]+\/[\w.-]+#(\d+)|#(\d+))/gi;
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;
15
20
 
16
- // Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`.
21
+ // Forma antiga, atrás do knob `codeReview.linkMode: "any-mention"`. Só `#N`,
22
+ // sempre no repo do PR.
17
23
  const ANY_MENTION_RE = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
18
24
 
19
25
  // Blocos de código não são vínculo: um `Closes #12` dentro de um exemplo de
@@ -24,25 +30,74 @@ function stripCodeBlocks(body) {
24
30
  .replace(/`[^`\n]*`/g, ' ');
25
31
  }
26
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
+
27
46
  /**
28
- * Números de issues que o PR declara implementar (função PURA — testável).
47
+ * Issues que o PR declara implementar, com o repositório de cada uma
48
+ * (função PURA — testável).
29
49
  *
30
50
  * @param {string} body corpo do PR
31
- * @param {object} [opts]
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
32
54
  * @param {'explicit'|'any-mention'} [opts.linkMode='explicit']
33
- * @returns {number[]} na ordem em que aparecem, sem repetição
55
+ * @returns {IssueRef[]} na ordem em que aparecem, sem repetição
34
56
  */
35
- export function extractIssueNumbers(body, { linkMode = 'explicit' } = {}) {
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
+ }
36
61
  if (!body) return [];
37
- const nums = new Set();
62
+ const seen = new Set();
63
+ const refs = [];
38
64
  const text = stripCodeBlocks(body);
39
65
  const re = linkMode === 'any-mention' ? ANY_MENTION_RE : EXPLICIT_LINK_RE;
40
66
  re.lastIndex = 0;
41
67
  for (const m of text.matchAll(re)) {
42
- const n = parseInt(m.slice(1).find(Boolean) || '', 10);
43
- if (n) nums.add(n);
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);
44
74
  }
45
- return [...nums];
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);
46
101
  }
47
102
 
48
103
  /**
@@ -18,7 +18,7 @@
18
18
 
19
19
  import * as p from '@clack/prompts';
20
20
  import { listIssuePullRequests, listOpenPullRequests, markPullRequestReadyForReview } from '../api/github-graphql.mjs';
21
- import { extractIssueNumbers } from './pr-link.mjs';
21
+ import { extractIssueRefs, hubIssueNumbers } from './pr-link.mjs';
22
22
 
23
23
  /**
24
24
  * Dos PRs coletados, quais devem sair do rascunho (função PURA — testável).
@@ -66,9 +66,13 @@ export async function collectFeaturePullRequests({
66
66
  const alvo = new Set(issueNumbers);
67
67
  const byNumber = new Map();
68
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 };
69
73
  const abertos = await listOpenPullRequests(token, owner, repo).catch(() => []);
70
74
  for (const pr of abertos) {
71
- const fecha = extractIssueNumbers(pr.body || '', { linkMode });
75
+ const fecha = hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo: hub, linkMode }), hub);
72
76
  if (fecha.some(n => alvo.has(n))) byNumber.set(pr.number, pr);
73
77
  }
74
78
 
@@ -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
+ }
@@ -0,0 +1,102 @@
1
+ // Papel do repositório no Project (RFC-005): um Project tem UM repositório
2
+ // hub — onde nascem as issues, os documentos e os workflows — e N repositórios
3
+ // de código, onde só acontecem branch e PR. Mono-repo é o caso degenerado:
4
+ // um hub sem repos de código, que é exatamente o estado de toda instalação
5
+ // anterior à RFC. Por isso a AUSÊNCIA de `role` no .spec-wave.json significa
6
+ // hub, e nenhum config antigo precisa ser regravado.
7
+ //
8
+ // hub: { role: 'hub', repositories: [{ slug, owner, repo }] } (repositories opcional)
9
+ // code: { role: 'code', hub: { owner, repo } }
10
+ //
11
+ // Funções PURAS — testáveis sem rede nem disco.
12
+
13
+ export const REPO_ROLES = ['hub', 'code'];
14
+ export const DEFAULT_REPO_ROLE = 'hub';
15
+
16
+ // Mesma regra do slug da UI (shared/src/projectRepos.ts): minúsculas,
17
+ // [a-z0-9-], até 39 caracteres — o limite de um login do GitHub. O slug vai
18
+ // na label `repo:<slug>` e é IMUTÁVEL depois do primeiro vínculo, porque está
19
+ // gravado em issues.
20
+ const REPO_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38})$/;
21
+
22
+ export function isValidRepoSlug(slug) {
23
+ return typeof slug === 'string' && REPO_SLUG_RE.test(slug);
24
+ }
25
+
26
+ /** @returns {'hub'|'code'} */
27
+ export function configuredRole(config) {
28
+ const role = String(config?.role || '').toLowerCase();
29
+ return REPO_ROLES.includes(role) ? role : DEFAULT_REPO_ROLE;
30
+ }
31
+
32
+ export function isCodeRepo(config) {
33
+ return configuredRole(config) === 'code';
34
+ }
35
+
36
+ /**
37
+ * O hub declarado por um repo de código, ou null quando o config não é de
38
+ * repo de código ou está incompleto.
39
+ * @returns {{ owner: string, repo: string }|null}
40
+ */
41
+ export function declaredHub(config) {
42
+ if (!isCodeRepo(config)) return null;
43
+ const hub = config?.hub;
44
+ if (!hub?.owner || !hub?.repo) return null;
45
+ return { owner: String(hub.owner), repo: String(hub.repo) };
46
+ }
47
+
48
+ /**
49
+ * Repositórios de código vinculados ao hub, já validados. Entradas
50
+ * malformadas são descartadas em vez de derrubar o comando — o hub continua
51
+ * funcionando como mono-repo enquanto o vínculo não estiver completo.
52
+ * @returns {{ slug: string, owner: string, repo: string }[]}
53
+ */
54
+ export function codeRepositories(config) {
55
+ if (isCodeRepo(config)) return [];
56
+ const list = Array.isArray(config?.repositories) ? config.repositories : [];
57
+ const out = [];
58
+ const seen = new Set();
59
+ for (const entry of list) {
60
+ if (!isValidRepoSlug(entry?.slug) || !entry?.owner || !entry?.repo) continue;
61
+ if (seen.has(entry.slug)) continue;
62
+ seen.add(entry.slug);
63
+ out.push({ slug: entry.slug, owner: String(entry.owner), repo: String(entry.repo) });
64
+ }
65
+ return out;
66
+ }
67
+
68
+ export function repositoryBySlug(config, slug) {
69
+ return codeRepositories(config).find(r => r.slug === slug) || null;
70
+ }
71
+
72
+ /**
73
+ * `owner/repo` → { owner, repo }; null para qualquer outra forma. É a
74
+ * gramática de `--repo`, `--hub` e `--pr-repo`.
75
+ */
76
+ export function parseRepoRef(value) {
77
+ const m = /^([\w.-]+)\/([\w.-]+)$/.exec(String(value ?? '').trim());
78
+ return m ? { owner: m[1], repo: m[2] } : null;
79
+ }
80
+
81
+ /** A label que uma Story usa para declarar que toca este repositório. */
82
+ export const REPO_LABEL_PREFIX = 'repo:';
83
+
84
+ export function repoLabel(slug) {
85
+ return `${REPO_LABEL_PREFIX}${slug}`;
86
+ }
87
+
88
+ /**
89
+ * Slugs declarados pelas labels de uma issue, na ordem em que aparecem.
90
+ * A label é a fonte de verdade (§3.3) — o campo do board é só espelho.
91
+ * @param {Array<string|{name?: string}>} labels
92
+ */
93
+ export function repoSlugsFromLabels(labels) {
94
+ const out = [];
95
+ for (const l of labels || []) {
96
+ const name = typeof l === 'string' ? l : l?.name;
97
+ if (!name || !name.startsWith(REPO_LABEL_PREFIX)) continue;
98
+ const slug = name.slice(REPO_LABEL_PREFIX.length);
99
+ if (isValidRepoSlug(slug) && !out.includes(slug)) out.push(slug);
100
+ }
101
+ return out;
102
+ }