@spec-wave/cli 1.0.8 → 1.2.0

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 (59) hide show
  1. package/package.json +1 -1
  2. package/src/api/github-graphql.mjs +51 -0
  3. package/src/api/github-rest.mjs +48 -0
  4. package/src/commands/audit.mjs +24 -18
  5. package/src/commands/code-review.mjs +89 -58
  6. package/src/commands/decompose.mjs +254 -218
  7. package/src/commands/generate-bug.mjs +51 -44
  8. package/src/commands/generate-plan.mjs +83 -63
  9. package/src/commands/generate-qa-plan.mjs +144 -117
  10. package/src/commands/generate-spec.mjs +33 -28
  11. package/src/commands/implement.mjs +154 -79
  12. package/src/commands/init.mjs +8 -3
  13. package/src/commands/issue.mjs +26 -39
  14. package/src/commands/merge.mjs +71 -20
  15. package/src/commands/mode.mjs +8 -4
  16. package/src/commands/move.mjs +16 -20
  17. package/src/commands/order.mjs +33 -22
  18. package/src/commands/preflight.mjs +24 -13
  19. package/src/commands/qa-lead.mjs +28 -16
  20. package/src/commands/qa-run.mjs +122 -101
  21. package/src/commands/qa.mjs +55 -44
  22. package/src/commands/refresh.mjs +24 -16
  23. package/src/commands/repair-stage.mjs +29 -16
  24. package/src/commands/repo.mjs +10 -3
  25. package/src/commands/run.mjs +23 -11
  26. package/src/commands/story.mjs +20 -25
  27. package/src/commands/task.mjs +21 -27
  28. package/src/commands/triage.mjs +33 -31
  29. package/src/commands/uninstall.mjs +7 -3
  30. package/src/commands/update.mjs +29 -21
  31. package/src/commands/validate.mjs +60 -52
  32. package/src/commands/workspace.mjs +7 -5
  33. package/src/config.mjs +7 -1
  34. package/src/lib/artifact-publish.mjs +20 -18
  35. package/src/lib/board-policy.mjs +144 -0
  36. package/src/lib/board.mjs +134 -233
  37. package/src/lib/doc-availability.mjs +10 -3
  38. package/src/lib/doc-source.mjs +9 -9
  39. package/src/lib/implement-board.mjs +23 -26
  40. package/src/lib/issue-type.mjs +5 -1
  41. package/src/lib/pr-ready.mjs +48 -10
  42. package/src/lib/pr-step.mjs +3 -1
  43. package/src/lib/qa-exec.mjs +3 -1
  44. package/src/lib/qa-lead.mjs +11 -3
  45. package/src/lib/qa-plan-doc.mjs +10 -4
  46. package/src/lib/spec-audit.mjs +1 -1
  47. package/src/lib/story-graph.mjs +62 -8
  48. package/src/lib/usage-report.mjs +8 -5
  49. package/src/lib/work-item-ref.mjs +176 -0
  50. package/src/plugin/.claude-plugin/plugin.json +1 -1
  51. package/src/plugins/scm-github/index.mjs +439 -0
  52. package/src/plugins/tracker-github-projects/fields.mjs +73 -0
  53. package/src/plugins/tracker-github-projects/index.mjs +662 -0
  54. package/src/ports/scm.mjs +197 -0
  55. package/src/ports/tracker.mjs +280 -0
  56. package/src/ports/types.mjs +295 -0
  57. package/src/setup/files.mjs +14 -12
  58. package/src/setup/labels.mjs +17 -12
  59. package/src/setup/project.mjs +40 -59
@@ -0,0 +1,197 @@
1
+ // Contrato da porta de SCM — quem hospeda o código, os documentos e os PRs.
2
+ //
3
+ // A porta existe porque **Jira não hospeda código**. `merge`, `fix-pr`,
4
+ // `artifact-publish`, `pr-ready` e todo o ciclo `docs/features/<slug>/*.md` →
5
+ // Pull Request são responsabilidade daqui, não do tracker — e hoje estão
6
+ // misturados com as chamadas de board no mesmo `src/api/github-rest.mjs`.
7
+ //
8
+ // **Uma instância é UM repositório.** O `merge` toca o hub, cada repo de código
9
+ // e o repo do próprio PR (RFC-005); `code-review` e `qa` tomam `--pr-repo`.
10
+ // Por isso a instância carrega o seu `ScmLink`, e por isso identificador `scm`
11
+ // pelado é proibido em arquivo que lida com mais de um: uma variável errada
12
+ // abre PR no repositório errado e nenhum teste pega.
13
+ //
14
+ // @see rfc/protocol/scm.v1.json — o contrato normativo
15
+ // @see src/ports/types.mjs — os tipos do domínio
16
+
17
+ /**
18
+ * @typedef {import('./types.mjs').ScmLink} ScmLink
19
+ * @typedef {import('./types.mjs').WorkItemRef} WorkItemRef
20
+ * @typedef {import('./types.mjs').PullRequestRef} PullRequestRef
21
+ * @typedef {import('./types.mjs').Review} Review
22
+ * @typedef {import('./types.mjs').ReviewDecision} ReviewDecision
23
+ * @typedef {import('./types.mjs').FileWrite} FileWrite
24
+ * @typedef {import('./types.mjs').CommitResult} CommitResult
25
+ * @typedef {import('./types.mjs').CompareStatus} CompareStatus
26
+ * @typedef {import('./types.mjs').AutomationRun} AutomationRun
27
+ * @typedef {import('./types.mjs').VerifyResult} VerifyResult
28
+ */
29
+
30
+ /**
31
+ * @typedef {object} ScmPort
32
+ * @property {string} kind `'github'`, `'azure-devops'`.
33
+ * @property {ScmLink} link A qual repositório esta instância está presa.
34
+ * @property {Readonly<object>} capabilities
35
+ *
36
+ * ── SEMPRE ────────────────────────────────────────────────────────────────
37
+ *
38
+ * @property {(o?: {log?: Function}) => Promise<{warnings: string[]}>} setup
39
+ * @property {() => Promise<VerifyResult>} verify
40
+ * Absorve a sonda de alcance do repositório — hoje `getRepoNodeId` chamada
41
+ * por `commands/repo.mjs` com o retorno descartado. `ok: false` é "não
42
+ * alcanço este repositório com esta credencial".
43
+ *
44
+ * @property {() => Promise<string>} defaultBranch
45
+ * @property {() => Promise<boolean>} isInitialized
46
+ * @property {(o: {path: string, ref?: string}) => Promise<string|null>} readFile
47
+ * `null` em 404 — é RESULTADO esperado (o documento pode não existir), não erro.
48
+ * @property {(o: {branch: string, base: string, files: FileWrite[], message: string}) => Promise<CommitResult>} writeFiles
49
+ * Atômico: N arquivos, um commit, ou nada. `fileWrites.mode`
50
+ * (`tree-commit-ref` × `push`) é detalhe INTERNO do plugin.
51
+ * @property {(o: {path: string, message: string}) => Promise<boolean>} deleteFile
52
+ * @property {(o: {branch: string}) => Promise<{commitSha: string, treeSha: string}|null>} branchHead
53
+ * @property {(o: {base: string, head: string}) => Promise<CompareStatus>} compare
54
+ * @property {(o: {branch: string}) => Promise<boolean>} deleteBranch
55
+ *
56
+ * @property {(o: {branch: string}) => Promise<PullRequestRef|null>} findOpenPullRequest
57
+ * @property {(o: {branch: string, base: string, title: string, body: string, draft?: boolean}) => Promise<{pr: PullRequestRef|null, created: boolean}>} ensurePullRequest
58
+ * Idempotente por contrato: rodar o mesmo passo duas vezes reaproveita o PR,
59
+ * nunca abre um segundo. `pr: null` = "não há nada entre base e head", que
60
+ * também não é erro.
61
+ * @property {(o: {number: string}) => Promise<PullRequestRef|null>} getPullRequest
62
+ * @property {(o: {number: string}) => Promise<string[]>} listPullRequestCommitMessages
63
+ * @property {(o: {number: string}) => Promise<Review[]>} listPullRequestReviews
64
+ * CRU, por revisor. Quem agrega é `reviewDecision()`, aqui no core.
65
+ * @property {() => Promise<PullRequestRef[]>} listOpenPullRequests
66
+ * @property {(o: {number: string, strategy?: 'merge'|'squash'|'rebase'}) => Promise<{merged: boolean, sha: string|null}>} mergePullRequest
67
+ *
68
+ * @property {(o: {ref: WorkItemRef, trackerKind: string, prLink: ScmLink, hubLink: ScmLink}) => string|null} closingKeyword
69
+ * Devolve a CLÁUSULA INTEIRA (`"Closes #123"`, `"Closes acme/hub#123"`) ou
70
+ * `null` quando tracker e SCM são de fornecedores diferentes — aí o
71
+ * fechamento passa a ser explícito, pela porta de tracker.
72
+ * Quatro campos e não dois: com a RFC-005 o PR de uma Story vive num repo e a
73
+ * issue vive no hub, e a forma curta num repo de código fecha a issue errada,
74
+ * ou nenhuma. Síncrona de propósito — é composição de texto.
75
+ * @property {(o: {ref: string, pathRel: string}) => string} fileUrl
76
+ * URL navegável de um arquivo numa ref. Existe porque a alternativa é cravar
77
+ * `https://github.com/<owner>/<repo>/blob/…` no core, string que entra em
78
+ * todo comentário de issue e corpo de PR que o fluxo gera.
79
+ * @property {(o?: {branch?: string, limit?: number}) => Promise<AutomationRun[]>} listAutomationRuns
80
+ * `[]` quando `automation: 'none'` — **nunca lança**. A tela que consome isto
81
+ * precisa tratar vazio como "sem automação", não como "nada rodou".
82
+ *
83
+ * ── CONDICIONAIS ──────────────────────────────────────────────────────────
84
+ *
85
+ * @property {(o: {id: string}) => Promise<void>} [markReadyForReview] pullRequests.draft
86
+ * @property {(o: {number: string, base: string}) => Promise<void>} [setPullRequestBase] pullRequests.retarget
87
+ * @property {(o: {ref: WorkItemRef, linkMode?: 'explicit'|'any-mention', hubLink?: ScmLink}) => Promise<PullRequestRef[]>} [findPullRequestsReferencing]
88
+ * pullRequests.referenceSearch
89
+ * @property {(o: {name: string}) => Promise<string|null>} [getVariable] variables: 'repo'
90
+ * @property {(o: {name: string, value: string}) => Promise<'created'|'updated'>} [setVariable]
91
+ * @property {(o: {name: string}) => Promise<boolean>} [deleteVariable]
92
+ * @property {(o: {role: 'hub'|'code', files: Array<{path: string, content: string, message?: string}>, log?: Function}) => Promise<{written: string[], skipped: string[]}>} [installAutomation]
93
+ * automation !== 'none'
94
+ * @property {(o: {action: string, key: string}) => Promise<void>} [dispatch] remoteDispatch.mechanism !== 'none'
95
+ */
96
+
97
+ /** Operações que todo SCM implementa. Ver a nota em `tracker.mjs`. */
98
+ export const SCM_REQUIRED_OPERATIONS = Object.freeze([
99
+ 'setup', 'verify',
100
+ 'defaultBranch', 'isInitialized',
101
+ 'readFile', 'writeFiles', 'deleteFile',
102
+ 'branchHead', 'compare', 'deleteBranch',
103
+ 'findOpenPullRequest', 'ensurePullRequest', 'getPullRequest',
104
+ 'listPullRequestCommitMessages', 'listPullRequestReviews', 'listOpenPullRequests',
105
+ 'mergePullRequest',
106
+ 'closingKeyword', 'fileUrl', 'listAutomationRuns',
107
+ ]);
108
+
109
+ /** @type {Readonly<Record<string, Readonly<string[]>>>} */
110
+ export const SCM_CONDITIONAL_OPERATIONS = Object.freeze({
111
+ 'pullRequests.draft=true': Object.freeze(['markReadyForReview']),
112
+ 'pullRequests.retarget=true': Object.freeze(['setPullRequestBase']),
113
+ 'pullRequests.referenceSearch=true': Object.freeze(['findPullRequestsReferencing']),
114
+ 'variables=repo': Object.freeze(['getVariable', 'setVariable', 'deleteVariable']),
115
+ 'automation!=none': Object.freeze(['installAutomation']),
116
+ 'remoteDispatch!=none': Object.freeze(['dispatch']),
117
+ });
118
+
119
+ /**
120
+ * As operações exigidas de um SCM com estas capabilities (função PURA).
121
+ *
122
+ * @param {object} [capabilities]
123
+ * @returns {string[]}
124
+ */
125
+ export function scmRequiredOperations(capabilities = {}) {
126
+ const exigidas = new Set(SCM_REQUIRED_OPERATIONS);
127
+ const pr = capabilities.pullRequests || {};
128
+ const ligada = {
129
+ 'pullRequests.draft=true': pr.draft === true,
130
+ 'pullRequests.retarget=true': pr.retarget === true,
131
+ 'pullRequests.referenceSearch=true': pr.referenceSearch === true,
132
+ 'variables=repo': capabilities.variables === 'repo',
133
+ 'automation!=none': Boolean(capabilities.automation) && capabilities.automation !== 'none',
134
+ 'remoteDispatch!=none': Boolean(capabilities.remoteDispatch?.mechanism)
135
+ && capabilities.remoteDispatch.mechanism !== 'none',
136
+ };
137
+ for (const [condicao, ops] of Object.entries(SCM_CONDITIONAL_OPERATIONS)) {
138
+ if (ligada[condicao]) for (const op of ops) exigidas.add(op);
139
+ }
140
+ return [...exigidas];
141
+ }
142
+
143
+ /**
144
+ * Confere um plugin de SCM contra as capabilities que ele declara.
145
+ *
146
+ * @param {ScmPort} port
147
+ * @returns {string[]} problemas; vazio = conforme
148
+ */
149
+ export function checkScmPort(port) {
150
+ const problemas = [];
151
+ if (!port || typeof port !== 'object') return ['porta de SCM ausente'];
152
+ if (!port.kind) problemas.push('porta de SCM sem `kind`');
153
+ if (!port.link?.id) problemas.push(`porta de SCM ${port.kind} sem \`link.id\``);
154
+ for (const op of scmRequiredOperations(port.capabilities || {})) {
155
+ if (typeof port[op] !== 'function') {
156
+ problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);
157
+ } else if (port[op].length > 1) {
158
+ problemas.push(`operação "${op}" tem aridade ${port[op].length}; o contrato é um argumento-objeto`);
159
+ }
160
+ }
161
+ return problemas;
162
+ }
163
+
164
+ /**
165
+ * Veredito agregado de revisão de um PR (função PURA).
166
+ *
167
+ * ⚠️ A regra mora no CORE, nunca no plugin. Ela está fixada no RFC-006 §7.2, e
168
+ * a razão é direta: dois plugins `vote` normalizariam diferente e `pr-ready`
169
+ * passaria a depender de qual está instalado — a mesma pilha de Stories seria
170
+ * liberada para revisão num cliente e não no outro.
171
+ *
172
+ * Os dois modelos:
173
+ * • `decision` — veredito agregado por revisor, enum fechado (GitHub).
174
+ * • `vote` — voto numérico por revisor (Azure DevOps): 10 aprovado, 5 aprovado
175
+ * com sugestões, 0 sem voto, −5 aguardando autor, −10 rejeitado.
176
+ *
177
+ * A regra é a mesma nos dois, e é assimétrica de propósito: **uma rejeição
178
+ * vence qualquer número de aprovações.** Quem pediu mudança precisa ser
179
+ * atendido antes de o PR andar; o contrário deixaria uma objeção ser enterrada
180
+ * por votos.
181
+ *
182
+ * @param {Review[]} reviews
183
+ * @param {'decision'|'vote'} [model='decision']
184
+ * @returns {ReviewDecision}
185
+ */
186
+ export function reviewDecision(reviews, model = 'decision') {
187
+ const lista = Array.isArray(reviews) ? reviews : [];
188
+ if (model === 'vote') {
189
+ if (lista.some(r => Number(r?.vote) <= -10)) return 'changes_requested';
190
+ if (lista.some(r => Number(r?.vote) >= 10)) return 'approved';
191
+ return 'pending';
192
+ }
193
+ const estado = r => String(r?.state || '').toUpperCase();
194
+ if (lista.some(r => estado(r) === 'CHANGES_REQUESTED')) return 'changes_requested';
195
+ if (lista.some(r => estado(r) === 'APPROVED')) return 'approved';
196
+ return 'pending';
197
+ }
@@ -0,0 +1,280 @@
1
+ // Contrato da porta de TRACKER — quem guarda os work items e o board.
2
+ //
3
+ // Este arquivo não conhece GitHub, Jira nem Projects v2, e isso é testado
4
+ // (test/ports-boundary.test.mjs). O que mora aqui é a forma; a implementação do
5
+ // GitHub vive em src/plugins/tracker-github-projects/.
6
+ //
7
+ // ── A fronteira que não pode vazar (RFC-006 §3.2) ─────────────────────────
8
+ //
9
+ // Fica no CORE | Fica no PLUGIN
10
+ // --------------------------------------|--------------------------------
11
+ // as 12 etapas e a ORDEM delas | como cada etapa é escrita
12
+ // "a Etapa só avança" (board-policy) | achar o caminho até a etapa pedida
13
+ // os 8 WORK_ITEM_TYPES, STAGE_TRACKS | para que entidade cada tipo mapeia
14
+ // as ~25 labels de gatilho e o sentido | como uma tag é gravada
15
+ // next-step, dependencies, story-graph | ler/escrever o vínculo de bloqueio
16
+ //
17
+ // O invariante mais importante: **direção de fluxo nunca é decisão de plugin.**
18
+ // Quando `setStage` é chamada, o guard de avanço JÁ RODOU no core. Um plugin
19
+ // que pudesse recusar ou inverter um avanço transformaria a regra central do
20
+ // RFC-001 em comportamento por fornecedor.
21
+ //
22
+ // ── Duas decisões de forma, e o que elas compram ──────────────────────────
23
+ //
24
+ // 1. **Um argumento-objeto por operação.** A aridade fica permanentemente em 1,
25
+ // então a conferência de conformidade da Fase 2 é
26
+ // `typeof port[op] === 'function' && port[op].length <= 1`. Posicional é o
27
+ // que força quebra de assinatura na primeira vez que o Jira precisar de um
28
+ // parâmetro a mais (caminho de transição, `resolution`, dica de fieldMap).
29
+ //
30
+ // 2. **A instância é presa a credencial e projeto.** Nada de `token` na
31
+ // assinatura das operações: é o que hoje faz `makeOctokit(token)` nascer por
32
+ // chamada e não haver ponto único onde trocar o fornecedor.
33
+ //
34
+ // @see rfc/protocol/tracker.v1.json — o contrato normativo
35
+ // @see src/ports/types.mjs — os tipos do domínio
36
+
37
+ /**
38
+ * @typedef {import('./types.mjs').WorkItemRef} WorkItemRef
39
+ * @typedef {import('./types.mjs').WorkItem} WorkItem
40
+ * @typedef {import('./types.mjs').MilestoneRef} MilestoneRef
41
+ * @typedef {import('./types.mjs').MilestoneKey} MilestoneKey
42
+ * @typedef {import('./types.mjs').CommentRef} CommentRef
43
+ * @typedef {import('./types.mjs').BoardItem} BoardItem
44
+ * @typedef {import('./types.mjs').FieldName} FieldName
45
+ * @typedef {import('./types.mjs').Progress} Progress
46
+ * @typedef {import('./types.mjs').VerifyResult} VerifyResult
47
+ */
48
+
49
+ /**
50
+ * @typedef {object} TrackerPort
51
+ * @property {string} kind `'github-projects'`, `'jira'`.
52
+ * @property {Readonly<object>} capabilities O que este tracker sabe fazer. O
53
+ * core LÊ isto para DEGRADAR em vez de falhar, e capability ausente vale
54
+ * `false`/mínima — um plugin nunca ganha poder por omissão.
55
+ *
56
+ * ── SEMPRE ────────────────────────────────────────────────────────────────
57
+ *
58
+ * @property {(o?: {provision?: boolean, log?: Function}) => Promise<{config: object, warnings: string[]}>} setup
59
+ * Provisiona (`boardProvisioning: 'create'`) ou mapeia (`'map-only'`) o board.
60
+ * Devolve o bloco a gravar no `.spec-wave.json` — **nunca escreve o arquivo**:
61
+ * quem serializa é `lib/config-file.mjs`, byte-exato, porque o `update` faz
62
+ * diff contra a cópia remota.
63
+ *
64
+ * @property {() => Promise<VerifyResult>} verify
65
+ * Diagnóstico SEM efeito. Absorve `getRateLimit`, `getProjectSnapshot`,
66
+ * `getSingleSelectField` e `getOwnerType` — esta última é a sonda org-vs-user
67
+ * que bloqueia o `init`, porque o GitHub App só alcança Projects v2 de
68
+ * organização. Num tracker sem noção de "owner" ela some de `facts`.
69
+ *
70
+ * @property {(o: {title: string, body: string, type: string, tags?: string[], milestone?: MilestoneRef|null, parent?: WorkItemRef|null}) => Promise<WorkItemRef>} createWorkItem
71
+ * @property {(o: {ref: WorkItemRef|string|number}) => Promise<WorkItem|null>} getWorkItem
72
+ * `ref` pode vir só com a chave — é o que o usuário digita. O plugin resolve
73
+ * `id`/`url` e devolve o ref completo em `WorkItem.ref`.
74
+ * @property {(o: {tag: string, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} listWorkItemsByTag
75
+ *
76
+ * @property {(o: {ref: WorkItemRef, body: string}) => Promise<CommentRef|null>} addComment
77
+ * @property {(o: {ref: WorkItemRef}) => Promise<CommentRef[]>} listComments
78
+ * @property {(o: {ref: WorkItemRef, commentId: string, body: string}) => Promise<void>} updateComment
79
+ *
80
+ * @property {(o: {ref: WorkItemRef, tag: string}) => Promise<void>} addTag
81
+ * @property {(o: {ref: WorkItemRef, tag: string}) => Promise<void>} removeTag
82
+ * @property {(o: {tags: Array<{name: string, color?: string, description?: string}>, overwrite?: boolean}) => Promise<{created: string[], updated: string[]}>} ensureTags
83
+ * `color`/`description` são IGNORADOS quando `tagConstraints.colors` /
84
+ * `.descriptions` é false. O core manda sempre; o plugin descarta. É mais
85
+ * barato que o core aprender o que cada tracker guarda.
86
+ * @property {() => Promise<Array<{name: string, color?: string, description?: string}>>} listTags
87
+ *
88
+ * @property {(o: {ref: WorkItemRef}) => Promise<string|null>} getStage
89
+ * Nome CANÔNICO de STATUS_OPTIONS, ou null quando o item ainda não tem etapa.
90
+ * @property {(o: {ref: WorkItemRef, stage: string, force?: boolean}) => Promise<void>} setStage
91
+ * ⚠️ O guard "a Etapa só avança" JÁ FOI aplicado pelo core (`lib/board.mjs`)
92
+ * antes desta chamada. `force: true` é `repair-stage` e exige
93
+ * `capabilities.stages.reopenable`. Em `stages.mode: 'transition'` é o plugin
94
+ * que acha o caminho — inclusive multi-salto — e falha de forma legível
95
+ * quando não houver nenhum; mas nunca decide a DIREÇÃO.
96
+ *
97
+ * @property {(o: {ref: WorkItemRef, field: FieldName}) => Promise<string|null>} getField
98
+ * @property {(o: {ref: WorkItemRef, field: FieldName, value: string, onlyIfEmpty?: boolean}) => Promise<boolean>} setField
99
+ * `onlyIfEmpty` existe porque o reparo de "Work Item Type" precisa
100
+ * exatamente disto — e fazê-lo no core custaria um get + um set, dois
101
+ * round-trips onde um tracker pode fazer um. Devolve `true` se escreveu.
102
+ *
103
+ * @property {() => Promise<BoardItem[]>} boardSnapshot
104
+ * @property {(o: {ref: WorkItemRef, reason?: 'completed'|'not-planned'|'duplicate'}) => Promise<void>} closeWorkItem
105
+ * `reason` existe porque em `closeSemantics: 'transition-and-resolution'` o
106
+ * Jira EXIGE resolution, e o `triage` já sabe o motivo (rejeitado × duplicata).
107
+ * Em `closeSemantics: 'state'` o plugin ignora.
108
+ *
109
+ * ── CONDICIONAIS ──────────────────────────────────────────────────────────
110
+ *
111
+ * @property {(o: {ref: WorkItemRef}) => Promise<Progress|null>} [getProgress] progress: 'native'
112
+ * @property {(o: {ref: WorkItemRef, progress: Progress}) => Promise<boolean>} [setProgress]
113
+ *
114
+ * @property {(o: {parent: WorkItemRef, child: WorkItemRef}) => Promise<void>} [addChild] hierarchy: 'native'
115
+ * @property {(o: {ref: WorkItemRef}) => Promise<WorkItem[]>} [listChildren]
116
+ * @property {(o: {ref: WorkItemRef}) => Promise<{ref: WorkItemRef, title: string}|null>} [getParent]
117
+ * Parcial de propósito: devolve `ref` + `title`, não um WorkItem inteiro.
118
+ * Quem sobe a cadeia Task→Story→Feature precisa do TÍTULO para reconhecer
119
+ * o tipo do pai, e só disso; devolver um WorkItem completo obrigaria o
120
+ * plugin a inventar `body`/`state`/`tags` que a consulta de parente não
121
+ * traz — ou a pagar uma segunda chamada por item da cadeia.
122
+ *
123
+ * @property {(o: {ref: WorkItemRef, blockedBy: WorkItemRef}) => Promise<void>} [addBlockedBy] dependencies: 'native'
124
+ * @property {(o: {ref: WorkItemRef}) => Promise<WorkItem[]>} [listBlockedBy]
125
+ *
126
+ * @property {() => Promise<MilestoneRef[]>} [listMilestones] milestones: 'native'
127
+ * @property {(o: {key: string}) => Promise<MilestoneRef|null>} [getMilestone]
128
+ * @property {(o: {key: string, description: string}) => Promise<void>} [setMilestoneDescription]
129
+ * ESTREITA de propósito, e não um caso particular de `updateMilestone`: o que
130
+ * ela promete é não tocar em mais nada. O `qa-lead` substitui um bloco
131
+ * delimitado dentro da descrição (`lib/qa-lead.mjs`), então precisa de uma
132
+ * escrita que não possa apagar título nem data-alvo por omissão.
133
+ * @property {(o: {milestone: MilestoneKey, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
134
+ * @property {(o: {ref: WorkItemRef, milestone: MilestoneKey|null}) => Promise<void>} [setMilestone]
135
+ * Atribui a milestone de um item que JÁ existe; `null` remove.
136
+ *
137
+ * Toma `MilestoneKey` — `{key}` basta — e não o `MilestoneRef` inteiro, pelo
138
+ * mesmo motivo que `getParent` devolve um parcial: quem só tem a chave não
139
+ * pode ser obrigado a INVENTAR `title` para chamar. Um chamador que forja
140
+ * `{key, title: ''}` está apostando que o plugin ignora o título, e essa
141
+ * aposta é sobre um plugin específico — o próximo pode não ignorar. Endereçar
142
+ * é pela chave; `title` e `dueOn` são o que a LEITURA devolve.
143
+ *
144
+ * Operação própria, e não `setField({field: 'release'})`, por duas razões que
145
+ * não são estéticas. `setField` carrega `value: string`, e identidade de
146
+ * milestone é `MilestoneRef {key, title}` — passar por string obrigaria a
147
+ * decidir AGORA qual dos dois endereça, que é exatamente a pendência de
148
+ * identidade de milestone ainda em aberto com a `spec-wave-ui`. E `null`
149
+ * precisa significar "remove", que um campo de texto não sabe expressar:
150
+ * string vazia é um valor, não uma ausência.
151
+ * @property {(o: {title: string, description?: string, dueOn?: string|null}) => Promise<MilestoneRef>} [createMilestone]
152
+ * @property {(o: {key: string, title?: string, description?: string, dueOn?: string|null, state?: 'open'|'closed'}) => Promise<MilestoneRef>} [updateMilestone]
153
+ * PARCIAL: campo não passado não é tocado. Fechar uma entrega é
154
+ * `state: 'closed'` aqui — não existe `closeMilestone`, porque fechar é uma
155
+ * transição de estado como as outras e um verbo separado convidaria um plugin
156
+ * a implementar só ele.
157
+ *
158
+ * NÃO existe `deleteMilestone`, e a ausência é decisão registrada: o GitHub
159
+ * apaga e desassocia as issues em silêncio, enquanto o Jira não deleta uma
160
+ * Version sem que se diga o destino do que aponta para ela. Uma assinatura
161
+ * `deleteMilestone({key})` seria implementável num fornecedor e impossível no
162
+ * outro — o dia em que entrar, entra com o destino dos itens no argumento.
163
+ *
164
+ * @property {(o: {stages: Array<{name: string, color?: string, id?: string}>}) => Promise<{fields: object}>} [syncStages]
165
+ * boardProvisioning: 'create'. Reescreve o vocabulário de etapas do board e
166
+ * devolve o schema RELIDO, para o chamador conferir a escrita em vez de
167
+ * confiar nela. Num tracker `map-only` reconciliar etapa é remapear
168
+ * (`stageMap`), não criar — por isso a operação não existe lá.
169
+ *
170
+ * @property {(o: {name: string}) => Promise<boolean>} [deleteTag] uninstall / update
171
+ * @property {(o: {tag: string}) => Promise<number>} [countOpenWithTag]
172
+ *
173
+ * @property {(o: {ref: WorkItemRef, key: string}) => Promise<object|null>} [getItemProperty] commentMarkers: false
174
+ * @property {(o: {ref: WorkItemRef, key: string, value: object}) => Promise<void>} [setItemProperty]
175
+ *
176
+ * @property {(o: {key: string}) => string} [branchToken] identity.branchSafe: false
177
+ */
178
+
179
+ /**
180
+ * As operações que um tracker precisa implementar SEMPRE.
181
+ *
182
+ * Lista, e não objeto, pelo mesmo motivo do manifesto: o que se confere antes
183
+ * da primeira chamada é PRESENÇA; a assinatura é problema do kit de
184
+ * conformidade. Está aqui, e não só no JSON normativo, para que o teste de
185
+ * contrato (test/tracker-port.test.mjs) não precise parsear prosa.
186
+ *
187
+ * `closeWorkItem` é sempre exigida porque todo valor de `closeSemantics`
188
+ * implica que fechar É possível — não existe valor do enum que desligue a
189
+ * operação; só o COMO varia.
190
+ */
191
+ export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
192
+ 'setup', 'verify',
193
+ 'createWorkItem', 'getWorkItem', 'listWorkItemsByTag',
194
+ 'addComment', 'listComments', 'updateComment',
195
+ 'addTag', 'removeTag', 'ensureTags', 'listTags',
196
+ 'getStage', 'setStage',
197
+ 'getField', 'setField',
198
+ 'boardSnapshot', 'closeWorkItem',
199
+ ]);
200
+
201
+ /**
202
+ * Capability → operações que ela passa a exigir.
203
+ *
204
+ * É o que transforma "declarei `dependencies: native` mas não implementei
205
+ * `addBlockedBy`" numa falha de CARGA em vez de uma falha no meio de um
206
+ * `decompose` — que é o pior momento possível, porque a chamada de modelo já
207
+ * foi paga.
208
+ *
209
+ * @type {Readonly<Record<string, Readonly<string[]>>>}
210
+ */
211
+ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
212
+ 'progress=native': Object.freeze(['getProgress', 'setProgress']),
213
+ 'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
214
+ 'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
215
+ // Leitura E escrita. A lista nasceu só com as quatro de leitura porque a CLI
216
+ // nunca escreveu milestone — quem as cria aqui é humano na UI do fornecedor —
217
+ // e um contrato derivado de um consumidor read-only herda o silêncio dele, não
218
+ // uma decisão. O sintoma de que era acidente estava no próprio contrato:
219
+ // `createWorkItem` aceita `milestone`, então um item podia NASCER numa entrega
220
+ // e não ter como sair dela.
221
+ 'milestones=native': Object.freeze([
222
+ 'listMilestones', 'getMilestone', 'setMilestoneDescription', 'listWorkItemsByMilestone',
223
+ 'setMilestone', 'createMilestone', 'updateMilestone',
224
+ ]),
225
+ 'boardProvisioning=create': Object.freeze(['syncStages']),
226
+ 'commentMarkers=false': Object.freeze(['getItemProperty', 'setItemProperty']),
227
+ 'identity.branchSafe=false': Object.freeze(['branchToken']),
228
+ });
229
+
230
+ /**
231
+ * As operações exigidas de um tracker com estas capabilities (função PURA).
232
+ *
233
+ * @param {object} [capabilities]
234
+ * @returns {string[]} nomes, sem repetição
235
+ */
236
+ export function trackerRequiredOperations(capabilities = {}) {
237
+ const exigidas = new Set(TRACKER_REQUIRED_OPERATIONS);
238
+ const ligada = {
239
+ 'progress=native': capabilities.progress === 'native',
240
+ 'hierarchy=native': capabilities.hierarchy === 'native',
241
+ 'dependencies=native': capabilities.dependencies === 'native',
242
+ 'milestones=native': capabilities.milestones === 'native',
243
+ 'boardProvisioning=create': capabilities.boardProvisioning === 'create',
244
+ // Ausente vale `false` — e `false` aqui EXIGE o par de propriedades, porque
245
+ // sem marcador embutido o estado precisa morar em algum lugar.
246
+ 'commentMarkers=false': capabilities.commentMarkers !== true,
247
+ 'identity.branchSafe=false': capabilities.identity?.branchSafe !== true,
248
+ };
249
+ for (const [condicao, ops] of Object.entries(TRACKER_CONDITIONAL_OPERATIONS)) {
250
+ if (ligada[condicao]) for (const op of ops) exigidas.add(op);
251
+ }
252
+ return [...exigidas];
253
+ }
254
+
255
+ /**
256
+ * Confere um plugin de tracker contra as capabilities que ele declara.
257
+ *
258
+ * Roda na CARGA, não no meio de um comando: as duas checagens são baratas, e um
259
+ * plugin publicado independentemente VAI ficar para trás do core — descobrir
260
+ * isso na primeira chamada de rede é o pior momento possível.
261
+ *
262
+ * @param {TrackerPort} port
263
+ * @returns {string[]} problemas; vazio = conforme
264
+ */
265
+ export function checkTrackerPort(port) {
266
+ const problemas = [];
267
+ if (!port || typeof port !== 'object') return ['porta de tracker ausente'];
268
+ if (!port.kind) problemas.push('porta de tracker sem `kind`');
269
+ for (const op of trackerRequiredOperations(port.capabilities || {})) {
270
+ if (typeof port[op] !== 'function') {
271
+ problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);
272
+ } else if (port[op].length > 1) {
273
+ // Aridade > 1 é assinatura posicional entrando pela porta dos fundos, e é
274
+ // ela que quebra na primeira vez que um fornecedor precisar de um campo a
275
+ // mais. Um argumento-objeto, sempre.
276
+ problemas.push(`operação "${op}" tem aridade ${port[op].length}; o contrato é um argumento-objeto`);
277
+ }
278
+ }
279
+ return problemas;
280
+ }