@spec-wave/cli 1.0.7 → 1.1.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 (68) hide show
  1. package/package.json +1 -1
  2. package/src/commands/audit.mjs +24 -18
  3. package/src/commands/code-review.mjs +91 -59
  4. package/src/commands/decompose.mjs +258 -221
  5. package/src/commands/doctor.mjs +16 -11
  6. package/src/commands/generate-bug.mjs +51 -44
  7. package/src/commands/generate-plan.mjs +83 -63
  8. package/src/commands/generate-qa-plan.mjs +145 -117
  9. package/src/commands/generate-spec.mjs +33 -28
  10. package/src/commands/implement.mjs +155 -79
  11. package/src/commands/info.mjs +4 -3
  12. package/src/commands/init.mjs +11 -5
  13. package/src/commands/install-skill.mjs +19 -0
  14. package/src/commands/issue.mjs +26 -39
  15. package/src/commands/merge.mjs +71 -20
  16. package/src/commands/mode.mjs +11 -6
  17. package/src/commands/move.mjs +16 -20
  18. package/src/commands/order.mjs +33 -22
  19. package/src/commands/preflight.mjs +24 -13
  20. package/src/commands/qa-lead.mjs +30 -17
  21. package/src/commands/qa-run.mjs +125 -103
  22. package/src/commands/qa.mjs +55 -44
  23. package/src/commands/refresh.mjs +24 -16
  24. package/src/commands/repair-stage.mjs +29 -16
  25. package/src/commands/repo.mjs +12 -4
  26. package/src/commands/run.mjs +23 -11
  27. package/src/commands/story.mjs +20 -25
  28. package/src/commands/task.mjs +21 -27
  29. package/src/commands/triage.mjs +33 -31
  30. package/src/commands/uninstall.mjs +7 -3
  31. package/src/commands/update.mjs +31 -22
  32. package/src/commands/validate.mjs +60 -52
  33. package/src/commands/workspace.mjs +7 -5
  34. package/src/config.mjs +7 -1
  35. package/src/lib/artifact-publish.mjs +20 -18
  36. package/src/lib/board-policy.mjs +144 -0
  37. package/src/lib/board.mjs +134 -233
  38. package/src/lib/cli-ref.mjs +75 -0
  39. package/src/lib/config-file.mjs +2 -1
  40. package/src/lib/doc-availability.mjs +10 -3
  41. package/src/lib/doc-source.mjs +9 -9
  42. package/src/lib/execution-mode.mjs +5 -3
  43. package/src/lib/implement-board.mjs +23 -26
  44. package/src/lib/issue-type.mjs +5 -1
  45. package/src/lib/plugin-skills.mjs +10 -0
  46. package/src/lib/pr-ready.mjs +48 -10
  47. package/src/lib/pr-step.mjs +3 -1
  48. package/src/lib/qa-exec.mjs +3 -1
  49. package/src/lib/qa-lead.mjs +11 -3
  50. package/src/lib/qa-plan-doc.mjs +10 -4
  51. package/src/lib/qa-report.mjs +2 -1
  52. package/src/lib/skill-compose.mjs +3 -0
  53. package/src/lib/spec-audit.mjs +1 -1
  54. package/src/lib/story-graph.mjs +62 -8
  55. package/src/lib/usage-report.mjs +8 -5
  56. package/src/lib/work-item-ref.mjs +176 -0
  57. package/src/plugin/.claude-plugin/plugin.json +1 -1
  58. package/src/plugins/scm-github/index.mjs +439 -0
  59. package/src/plugins/tracker-github-projects/fields.mjs +73 -0
  60. package/src/plugins/tracker-github-projects/index.mjs +625 -0
  61. package/src/ports/scm.mjs +197 -0
  62. package/src/ports/tracker.mjs +239 -0
  63. package/src/ports/types.mjs +254 -0
  64. package/src/setup/files.mjs +14 -12
  65. package/src/setup/labels.mjs +17 -12
  66. package/src/setup/project.mjs +40 -59
  67. package/src/templates/workflows/code/code-review.yml +1 -1
  68. package/src/templates/workflows/code/qa.yml +1 -1
@@ -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,239 @@
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').CommentRef} CommentRef
42
+ * @typedef {import('./types.mjs').BoardItem} BoardItem
43
+ * @typedef {import('./types.mjs').FieldName} FieldName
44
+ * @typedef {import('./types.mjs').Progress} Progress
45
+ * @typedef {import('./types.mjs').VerifyResult} VerifyResult
46
+ */
47
+
48
+ /**
49
+ * @typedef {object} TrackerPort
50
+ * @property {string} kind `'github-projects'`, `'jira'`.
51
+ * @property {Readonly<object>} capabilities O que este tracker sabe fazer. O
52
+ * core LÊ isto para DEGRADAR em vez de falhar, e capability ausente vale
53
+ * `false`/mínima — um plugin nunca ganha poder por omissão.
54
+ *
55
+ * ── SEMPRE ────────────────────────────────────────────────────────────────
56
+ *
57
+ * @property {(o?: {provision?: boolean, log?: Function}) => Promise<{config: object, warnings: string[]}>} setup
58
+ * Provisiona (`boardProvisioning: 'create'`) ou mapeia (`'map-only'`) o board.
59
+ * Devolve o bloco a gravar no `.spec-wave.json` — **nunca escreve o arquivo**:
60
+ * quem serializa é `lib/config-file.mjs`, byte-exato, porque o `update` faz
61
+ * diff contra a cópia remota.
62
+ *
63
+ * @property {() => Promise<VerifyResult>} verify
64
+ * Diagnóstico SEM efeito. Absorve `getRateLimit`, `getProjectSnapshot`,
65
+ * `getSingleSelectField` e `getOwnerType` — esta última é a sonda org-vs-user
66
+ * que bloqueia o `init`, porque o GitHub App só alcança Projects v2 de
67
+ * organização. Num tracker sem noção de "owner" ela some de `facts`.
68
+ *
69
+ * @property {(o: {title: string, body: string, type: string, tags?: string[], milestone?: MilestoneRef|null, parent?: WorkItemRef|null}) => Promise<WorkItemRef>} createWorkItem
70
+ * @property {(o: {ref: WorkItemRef|string|number}) => Promise<WorkItem|null>} getWorkItem
71
+ * `ref` pode vir só com a chave — é o que o usuário digita. O plugin resolve
72
+ * `id`/`url` e devolve o ref completo em `WorkItem.ref`.
73
+ * @property {(o: {tag: string, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} listWorkItemsByTag
74
+ *
75
+ * @property {(o: {ref: WorkItemRef, body: string}) => Promise<CommentRef|null>} addComment
76
+ * @property {(o: {ref: WorkItemRef}) => Promise<CommentRef[]>} listComments
77
+ * @property {(o: {ref: WorkItemRef, commentId: string, body: string}) => Promise<void>} updateComment
78
+ *
79
+ * @property {(o: {ref: WorkItemRef, tag: string}) => Promise<void>} addTag
80
+ * @property {(o: {ref: WorkItemRef, tag: string}) => Promise<void>} removeTag
81
+ * @property {(o: {tags: Array<{name: string, color?: string, description?: string}>, overwrite?: boolean}) => Promise<{created: string[], updated: string[]}>} ensureTags
82
+ * `color`/`description` são IGNORADOS quando `tagConstraints.colors` /
83
+ * `.descriptions` é false. O core manda sempre; o plugin descarta. É mais
84
+ * barato que o core aprender o que cada tracker guarda.
85
+ * @property {() => Promise<Array<{name: string, color?: string, description?: string}>>} listTags
86
+ *
87
+ * @property {(o: {ref: WorkItemRef}) => Promise<string|null>} getStage
88
+ * Nome CANÔNICO de STATUS_OPTIONS, ou null quando o item ainda não tem etapa.
89
+ * @property {(o: {ref: WorkItemRef, stage: string, force?: boolean}) => Promise<void>} setStage
90
+ * ⚠️ O guard "a Etapa só avança" JÁ FOI aplicado pelo core (`lib/board.mjs`)
91
+ * antes desta chamada. `force: true` é `repair-stage` e exige
92
+ * `capabilities.stages.reopenable`. Em `stages.mode: 'transition'` é o plugin
93
+ * que acha o caminho — inclusive multi-salto — e falha de forma legível
94
+ * quando não houver nenhum; mas nunca decide a DIREÇÃO.
95
+ *
96
+ * @property {(o: {ref: WorkItemRef, field: FieldName}) => Promise<string|null>} getField
97
+ * @property {(o: {ref: WorkItemRef, field: FieldName, value: string, onlyIfEmpty?: boolean}) => Promise<boolean>} setField
98
+ * `onlyIfEmpty` existe porque o reparo de "Work Item Type" precisa
99
+ * exatamente disto — e fazê-lo no core custaria um get + um set, dois
100
+ * round-trips onde um tracker pode fazer um. Devolve `true` se escreveu.
101
+ *
102
+ * @property {() => Promise<BoardItem[]>} boardSnapshot
103
+ * @property {(o: {ref: WorkItemRef, reason?: 'completed'|'not-planned'|'duplicate'}) => Promise<void>} closeWorkItem
104
+ * `reason` existe porque em `closeSemantics: 'transition-and-resolution'` o
105
+ * Jira EXIGE resolution, e o `triage` já sabe o motivo (rejeitado × duplicata).
106
+ * Em `closeSemantics: 'state'` o plugin ignora.
107
+ *
108
+ * ── CONDICIONAIS ──────────────────────────────────────────────────────────
109
+ *
110
+ * @property {(o: {ref: WorkItemRef}) => Promise<Progress|null>} [getProgress] progress: 'native'
111
+ * @property {(o: {ref: WorkItemRef, progress: Progress}) => Promise<boolean>} [setProgress]
112
+ *
113
+ * @property {(o: {parent: WorkItemRef, child: WorkItemRef}) => Promise<void>} [addChild] hierarchy: 'native'
114
+ * @property {(o: {ref: WorkItemRef}) => Promise<WorkItem[]>} [listChildren]
115
+ * @property {(o: {ref: WorkItemRef}) => Promise<{ref: WorkItemRef, title: string}|null>} [getParent]
116
+ * Parcial de propósito: devolve `ref` + `title`, não um WorkItem inteiro.
117
+ * Quem sobe a cadeia Task→Story→Feature precisa do TÍTULO para reconhecer
118
+ * o tipo do pai, e só disso; devolver um WorkItem completo obrigaria o
119
+ * plugin a inventar `body`/`state`/`tags` que a consulta de parente não
120
+ * traz — ou a pagar uma segunda chamada por item da cadeia.
121
+ *
122
+ * @property {(o: {ref: WorkItemRef, blockedBy: WorkItemRef}) => Promise<void>} [addBlockedBy] dependencies: 'native'
123
+ * @property {(o: {ref: WorkItemRef}) => Promise<WorkItem[]>} [listBlockedBy]
124
+ *
125
+ * @property {() => Promise<MilestoneRef[]>} [listMilestones] milestones: 'native'
126
+ * @property {(o: {key: string}) => Promise<MilestoneRef|null>} [getMilestone]
127
+ * @property {(o: {key: string, description: string}) => Promise<void>} [setMilestoneDescription]
128
+ * @property {(o: {milestone: MilestoneRef, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
129
+ *
130
+ * @property {(o: {stages: Array<{name: string, color?: string, id?: string}>}) => Promise<{fields: object}>} [syncStages]
131
+ * boardProvisioning: 'create'. Reescreve o vocabulário de etapas do board e
132
+ * devolve o schema RELIDO, para o chamador conferir a escrita em vez de
133
+ * confiar nela. Num tracker `map-only` reconciliar etapa é remapear
134
+ * (`stageMap`), não criar — por isso a operação não existe lá.
135
+ *
136
+ * @property {(o: {name: string}) => Promise<boolean>} [deleteTag] uninstall / update
137
+ * @property {(o: {tag: string}) => Promise<number>} [countOpenWithTag]
138
+ *
139
+ * @property {(o: {ref: WorkItemRef, key: string}) => Promise<object|null>} [getItemProperty] commentMarkers: false
140
+ * @property {(o: {ref: WorkItemRef, key: string, value: object}) => Promise<void>} [setItemProperty]
141
+ *
142
+ * @property {(o: {key: string}) => string} [branchToken] identity.branchSafe: false
143
+ */
144
+
145
+ /**
146
+ * As operações que um tracker precisa implementar SEMPRE.
147
+ *
148
+ * Lista, e não objeto, pelo mesmo motivo do manifesto: o que se confere antes
149
+ * da primeira chamada é PRESENÇA; a assinatura é problema do kit de
150
+ * conformidade. Está aqui, e não só no JSON normativo, para que o teste de
151
+ * contrato (test/tracker-port.test.mjs) não precise parsear prosa.
152
+ *
153
+ * `closeWorkItem` é sempre exigida porque todo valor de `closeSemantics`
154
+ * implica que fechar É possível — não existe valor do enum que desligue a
155
+ * operação; só o COMO varia.
156
+ */
157
+ export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
158
+ 'setup', 'verify',
159
+ 'createWorkItem', 'getWorkItem', 'listWorkItemsByTag',
160
+ 'addComment', 'listComments', 'updateComment',
161
+ 'addTag', 'removeTag', 'ensureTags', 'listTags',
162
+ 'getStage', 'setStage',
163
+ 'getField', 'setField',
164
+ 'boardSnapshot', 'closeWorkItem',
165
+ ]);
166
+
167
+ /**
168
+ * Capability → operações que ela passa a exigir.
169
+ *
170
+ * É o que transforma "declarei `dependencies: native` mas não implementei
171
+ * `addBlockedBy`" numa falha de CARGA em vez de uma falha no meio de um
172
+ * `decompose` — que é o pior momento possível, porque a chamada de modelo já
173
+ * foi paga.
174
+ *
175
+ * @type {Readonly<Record<string, Readonly<string[]>>>}
176
+ */
177
+ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
178
+ 'progress=native': Object.freeze(['getProgress', 'setProgress']),
179
+ 'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
180
+ 'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
181
+ 'milestones=native': Object.freeze([
182
+ 'listMilestones', 'getMilestone', 'setMilestoneDescription', 'listWorkItemsByMilestone',
183
+ ]),
184
+ 'boardProvisioning=create': Object.freeze(['syncStages']),
185
+ 'commentMarkers=false': Object.freeze(['getItemProperty', 'setItemProperty']),
186
+ 'identity.branchSafe=false': Object.freeze(['branchToken']),
187
+ });
188
+
189
+ /**
190
+ * As operações exigidas de um tracker com estas capabilities (função PURA).
191
+ *
192
+ * @param {object} [capabilities]
193
+ * @returns {string[]} nomes, sem repetição
194
+ */
195
+ export function trackerRequiredOperations(capabilities = {}) {
196
+ const exigidas = new Set(TRACKER_REQUIRED_OPERATIONS);
197
+ const ligada = {
198
+ 'progress=native': capabilities.progress === 'native',
199
+ 'hierarchy=native': capabilities.hierarchy === 'native',
200
+ 'dependencies=native': capabilities.dependencies === 'native',
201
+ 'milestones=native': capabilities.milestones === 'native',
202
+ 'boardProvisioning=create': capabilities.boardProvisioning === 'create',
203
+ // Ausente vale `false` — e `false` aqui EXIGE o par de propriedades, porque
204
+ // sem marcador embutido o estado precisa morar em algum lugar.
205
+ 'commentMarkers=false': capabilities.commentMarkers !== true,
206
+ 'identity.branchSafe=false': capabilities.identity?.branchSafe !== true,
207
+ };
208
+ for (const [condicao, ops] of Object.entries(TRACKER_CONDITIONAL_OPERATIONS)) {
209
+ if (ligada[condicao]) for (const op of ops) exigidas.add(op);
210
+ }
211
+ return [...exigidas];
212
+ }
213
+
214
+ /**
215
+ * Confere um plugin de tracker contra as capabilities que ele declara.
216
+ *
217
+ * Roda na CARGA, não no meio de um comando: as duas checagens são baratas, e um
218
+ * plugin publicado independentemente VAI ficar para trás do core — descobrir
219
+ * isso na primeira chamada de rede é o pior momento possível.
220
+ *
221
+ * @param {TrackerPort} port
222
+ * @returns {string[]} problemas; vazio = conforme
223
+ */
224
+ export function checkTrackerPort(port) {
225
+ const problemas = [];
226
+ if (!port || typeof port !== 'object') return ['porta de tracker ausente'];
227
+ if (!port.kind) problemas.push('porta de tracker sem `kind`');
228
+ for (const op of trackerRequiredOperations(port.capabilities || {})) {
229
+ if (typeof port[op] !== 'function') {
230
+ problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);
231
+ } else if (port[op].length > 1) {
232
+ // Aridade > 1 é assinatura posicional entrando pela porta dos fundos, e é
233
+ // ela que quebra na primeira vez que um fornecedor precisar de um campo a
234
+ // mais. Um argumento-objeto, sempre.
235
+ problemas.push(`operação "${op}" tem aridade ${port[op].length}; o contrato é um argumento-objeto`);
236
+ }
237
+ }
238
+ return problemas;
239
+ }