@spec-wave/cli 1.0.8 → 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.
- package/package.json +1 -1
- package/src/commands/audit.mjs +24 -18
- package/src/commands/code-review.mjs +89 -58
- package/src/commands/decompose.mjs +254 -218
- package/src/commands/generate-bug.mjs +51 -44
- package/src/commands/generate-plan.mjs +83 -63
- package/src/commands/generate-qa-plan.mjs +144 -117
- package/src/commands/generate-spec.mjs +33 -28
- package/src/commands/implement.mjs +154 -79
- package/src/commands/init.mjs +8 -3
- package/src/commands/issue.mjs +26 -39
- package/src/commands/merge.mjs +71 -20
- package/src/commands/mode.mjs +8 -4
- package/src/commands/move.mjs +16 -20
- package/src/commands/order.mjs +33 -22
- package/src/commands/preflight.mjs +24 -13
- package/src/commands/qa-lead.mjs +28 -16
- package/src/commands/qa-run.mjs +122 -101
- package/src/commands/qa.mjs +55 -44
- package/src/commands/refresh.mjs +24 -16
- package/src/commands/repair-stage.mjs +29 -16
- package/src/commands/repo.mjs +10 -3
- package/src/commands/run.mjs +23 -11
- package/src/commands/story.mjs +20 -25
- package/src/commands/task.mjs +21 -27
- package/src/commands/triage.mjs +33 -31
- package/src/commands/uninstall.mjs +7 -3
- package/src/commands/update.mjs +29 -21
- package/src/commands/validate.mjs +60 -52
- package/src/commands/workspace.mjs +7 -5
- package/src/config.mjs +7 -1
- package/src/lib/artifact-publish.mjs +20 -18
- package/src/lib/board-policy.mjs +144 -0
- package/src/lib/board.mjs +134 -233
- package/src/lib/doc-availability.mjs +10 -3
- package/src/lib/doc-source.mjs +9 -9
- package/src/lib/implement-board.mjs +23 -26
- package/src/lib/issue-type.mjs +5 -1
- package/src/lib/pr-ready.mjs +48 -10
- package/src/lib/pr-step.mjs +3 -1
- package/src/lib/qa-exec.mjs +3 -1
- package/src/lib/qa-lead.mjs +11 -3
- package/src/lib/qa-plan-doc.mjs +10 -4
- package/src/lib/spec-audit.mjs +1 -1
- package/src/lib/story-graph.mjs +62 -8
- package/src/lib/usage-report.mjs +8 -5
- package/src/lib/work-item-ref.mjs +176 -0
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugins/scm-github/index.mjs +439 -0
- package/src/plugins/tracker-github-projects/fields.mjs +73 -0
- package/src/plugins/tracker-github-projects/index.mjs +625 -0
- package/src/ports/scm.mjs +197 -0
- package/src/ports/tracker.mjs +239 -0
- package/src/ports/types.mjs +254 -0
- package/src/setup/files.mjs +14 -12
- package/src/setup/labels.mjs +17 -12
- 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,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
|
+
}
|