@spec-wave/cli 1.1.0 → 1.3.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
CHANGED
|
@@ -550,6 +550,57 @@ export async function setItemSingleSelect(token, projectId, itemId, fieldId, opt
|
|
|
550
550
|
`, { projectId, itemId, fieldId, optionId });
|
|
551
551
|
}
|
|
552
552
|
|
|
553
|
+
// Define o valor de um campo TEXT para um item do Project.
|
|
554
|
+
//
|
|
555
|
+
// Rota separada da de single-select porque a mutation exige `value: { text: }`
|
|
556
|
+
// contra `value: { singleSelectOptionId: }` — não é o mesmo payload com outro
|
|
557
|
+
// argumento.
|
|
558
|
+
export async function setItemText(token, projectId, itemId, fieldId, text) {
|
|
559
|
+
const client = makeClient(token);
|
|
560
|
+
await client(`
|
|
561
|
+
mutation SetTextField($projectId: ID!, $itemId: ID!, $fieldId: ID!, $text: String!) {
|
|
562
|
+
updateProjectV2ItemFieldValue(input: {
|
|
563
|
+
projectId: $projectId
|
|
564
|
+
itemId: $itemId
|
|
565
|
+
fieldId: $fieldId
|
|
566
|
+
value: { text: $text }
|
|
567
|
+
}) {
|
|
568
|
+
projectV2Item { id }
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
`, { projectId, itemId, fieldId, text: String(text ?? '') });
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
// Lê o valor atual de um campo TEXT.
|
|
575
|
+
//
|
|
576
|
+
// Função NOVA em vez de um fragmento a mais em `getItemSingleSelectValue`: essa
|
|
577
|
+
// query é a leitura que o guard "a Etapa só avança" faz em todo movimento de
|
|
578
|
+
// board, e nenhum teste desta suíte fala GraphQL de verdade. Mexer nela para
|
|
579
|
+
// atender um campo que nada escreve hoje seria arriscar o caminho mais
|
|
580
|
+
// carregado do sistema pelo menos carregado.
|
|
581
|
+
export async function getItemTextValue(token, itemId, fieldId) {
|
|
582
|
+
const client = makeClient(token);
|
|
583
|
+
const result = await client(`
|
|
584
|
+
query ItemTextValue($itemId: ID!) {
|
|
585
|
+
node(id: $itemId) {
|
|
586
|
+
... on ProjectV2Item {
|
|
587
|
+
fieldValues(first: 50) {
|
|
588
|
+
nodes {
|
|
589
|
+
... on ProjectV2ItemFieldTextValue {
|
|
590
|
+
text
|
|
591
|
+
field { ... on ProjectV2Field { id } }
|
|
592
|
+
}
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
}
|
|
598
|
+
`, { itemId });
|
|
599
|
+
const nodes = result.node?.fieldValues?.nodes || [];
|
|
600
|
+
const value = nodes.find(n => n && n.field?.id === fieldId);
|
|
601
|
+
return value?.text ?? null;
|
|
602
|
+
}
|
|
603
|
+
|
|
553
604
|
export async function createTextField(token, projectId, name) {
|
|
554
605
|
const client = makeClient(token);
|
|
555
606
|
const result = await client(`
|
package/src/api/github-rest.mjs
CHANGED
|
@@ -351,6 +351,69 @@ export async function updateMilestoneDescription(token, owner, repo, milestoneNu
|
|
|
351
351
|
return res.data;
|
|
352
352
|
}
|
|
353
353
|
|
|
354
|
+
// Cria uma milestone. `dueOn` é ISO-8601 e vai como `due_on`.
|
|
355
|
+
//
|
|
356
|
+
// O GitHub recusa (422) título repetido, e isso é RESULTADO, não falha de rede:
|
|
357
|
+
// quem chama decide entre reusar a existente e reclamar. Devolver `null` aqui
|
|
358
|
+
// apagaria a diferença entre "já existe" e "não consegui falar com a API", que
|
|
359
|
+
// é justamente a distinção que o chamador precisa — então o 422 sobe.
|
|
360
|
+
export async function createMilestone(token, owner, repo, { title, description, dueOn } = {}) {
|
|
361
|
+
const octokit = makeOctokit(token);
|
|
362
|
+
const res = await octokit.rest.issues.createMilestone({
|
|
363
|
+
owner, repo, title,
|
|
364
|
+
...(description == null ? {} : { description }),
|
|
365
|
+
...(dueOn ? { due_on: dueOn } : {}),
|
|
366
|
+
});
|
|
367
|
+
return res.data;
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
// Atualiza campos de uma milestone. PATCH parcial: campo não passado não é
|
|
371
|
+
// tocado — por isso cada um só entra no payload quando veio.
|
|
372
|
+
//
|
|
373
|
+
// `updateMilestoneDescription` continua existindo e NÃO é um caso particular
|
|
374
|
+
// desta: ela promete mexer só na descrição, e é dessa promessa estreita que o
|
|
375
|
+
// `qa-lead` depende ao substituir o bloco de trilha.
|
|
376
|
+
export async function updateMilestone(token, owner, repo, milestoneNumber, { title, description, dueOn, state } = {}) {
|
|
377
|
+
const octokit = makeOctokit(token);
|
|
378
|
+
const res = await octokit.rest.issues.updateMilestone({
|
|
379
|
+
owner, repo, milestone_number: milestoneNumber,
|
|
380
|
+
...(title == null ? {} : { title }),
|
|
381
|
+
...(description == null ? {} : { description }),
|
|
382
|
+
...(dueOn === undefined ? {} : { due_on: dueOn }),
|
|
383
|
+
...(state == null ? {} : { state }),
|
|
384
|
+
});
|
|
385
|
+
return res.data;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
// Atribui (ou REMOVE, com `null`) a milestone de uma issue que já existe.
|
|
389
|
+
//
|
|
390
|
+
// Edita campos de uma issue. `campos` vai CRU para o PATCH: quem chama decide o
|
|
391
|
+
// que entra, e o que não entra não é tocado.
|
|
392
|
+
//
|
|
393
|
+
// A seleção mora no chamador de propósito. A parcialidade aqui é uma garantia
|
|
394
|
+
// de contrato — o corpo de uma Story carrega a linha `Depende de: #N` que o
|
|
395
|
+
// `implement` e o `merge` leem (lib/dependencies.mjs), e uma escrita que
|
|
396
|
+
// mandasse o corpo junto num renomear de título apagaria a dependência com
|
|
397
|
+
// sucesso na chamada e silêncio no efeito. Decidir aqui dentro tornaria essa
|
|
398
|
+
// garantia intestável: esta camada não tem mock de HTTP, e a mutação que a
|
|
399
|
+
// quebra passa verde. Um nível acima, o teste vê o payload.
|
|
400
|
+
export async function updateIssue(token, owner, repo, issueNumber, campos = {}) {
|
|
401
|
+
const octokit = makeOctokit(token);
|
|
402
|
+
await octokit.rest.issues.update({ owner, repo, issue_number: issueNumber, ...campos });
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
// A assimetria com `createIssue` é da API e é fácil de trocar: lá `milestone:
|
|
406
|
+
// null` leva 422 e por isso o campo só entra quando existe; aqui `null` é
|
|
407
|
+
// justamente como se remove, e omitir o campo é que seria "não mexe". Um `...(m
|
|
408
|
+
// ? {m} : {})` copiado de lá tornaria a remoção silenciosamente inócua.
|
|
409
|
+
export async function setIssueMilestone(token, owner, repo, issueNumber, milestoneNumber) {
|
|
410
|
+
const octokit = makeOctokit(token);
|
|
411
|
+
await octokit.rest.issues.update({
|
|
412
|
+
owner, repo, issue_number: issueNumber,
|
|
413
|
+
milestone: milestoneNumber == null ? null : Number(milestoneNumber),
|
|
414
|
+
});
|
|
415
|
+
}
|
|
416
|
+
|
|
354
417
|
// Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
|
|
355
418
|
//
|
|
356
419
|
// `state: 'all'` de propósito: uma Feature fechada continua contando para o
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-wave",
|
|
3
3
|
"displayName": "Spec Wave",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.3.0",
|
|
5
5
|
"description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Astratech",
|
|
@@ -30,6 +30,7 @@ import {
|
|
|
30
30
|
countOpenIssuesWithLabel,
|
|
31
31
|
createIssue,
|
|
32
32
|
createLabel,
|
|
33
|
+
createMilestone,
|
|
33
34
|
deleteLabel,
|
|
34
35
|
getIssue,
|
|
35
36
|
getMilestone,
|
|
@@ -40,9 +41,12 @@ import {
|
|
|
40
41
|
listLabels,
|
|
41
42
|
listMilestones,
|
|
42
43
|
removeLabel,
|
|
44
|
+
setIssueMilestone,
|
|
43
45
|
setIssueState,
|
|
44
46
|
updateComment,
|
|
47
|
+
updateIssue,
|
|
45
48
|
updateLabel,
|
|
49
|
+
updateMilestone,
|
|
46
50
|
updateMilestoneDescription,
|
|
47
51
|
getOwnerNodeId,
|
|
48
52
|
getRepoNodeId,
|
|
@@ -55,6 +59,8 @@ import {
|
|
|
55
59
|
createTextField,
|
|
56
60
|
getIssueParent,
|
|
57
61
|
getItemSingleSelectValue,
|
|
62
|
+
getItemTextValue,
|
|
63
|
+
setItemText,
|
|
58
64
|
getProjectSnapshot,
|
|
59
65
|
getRateLimit,
|
|
60
66
|
linkProjectToRepo,
|
|
@@ -77,6 +83,7 @@ export const GITHUB_TRACKER_CAPABILITIES = Object.freeze({
|
|
|
77
83
|
hierarchy: 'native', // sub-issues
|
|
78
84
|
dependencies: 'native', // API de dependencies (blocked_by)
|
|
79
85
|
milestones: 'native',
|
|
86
|
+
reopen: 'native', // `setIssueState(..., 'open')` — sem workflow no caminho
|
|
80
87
|
stages: Object.freeze({ mode: 'set', multiHop: false, reopenable: true }),
|
|
81
88
|
progress: 'native', // o campo nativo "Status" do Projects v2
|
|
82
89
|
fields: Object.freeze({
|
|
@@ -170,12 +177,13 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
170
177
|
|
|
171
178
|
const a = {
|
|
172
179
|
addBlockedBy, addLabel, commentOnIssue, countOpenIssuesWithLabel, createIssue, createLabel,
|
|
173
|
-
deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy,
|
|
174
|
-
listIssuesByMilestone, listLabels, listMilestones, removeLabel,
|
|
175
|
-
|
|
180
|
+
createMilestone, deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy,
|
|
181
|
+
listIssueComments, listIssuesByMilestone, listLabels, listMilestones, removeLabel,
|
|
182
|
+
setIssueMilestone, setIssueState, updateComment, updateIssue, updateLabel, updateMilestone,
|
|
183
|
+
updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
|
|
176
184
|
addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
|
|
177
|
-
getIssueParent, getItemSingleSelectValue, getProjectSnapshot, getRateLimit,
|
|
178
|
-
listProjectItems, listSubIssues, setItemSingleSelect,
|
|
185
|
+
getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
|
|
186
|
+
linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
|
|
179
187
|
resolveField,
|
|
180
188
|
...api,
|
|
181
189
|
};
|
|
@@ -502,17 +510,28 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
502
510
|
async setField({ ref, field, value, onlyIfEmpty = false } = {}) {
|
|
503
511
|
const f = await campo(field);
|
|
504
512
|
if (!f?.id) return false;
|
|
505
|
-
|
|
506
|
-
|
|
513
|
+
// Dos seis campos do RFC-001, cinco são SINGLE_SELECT e `release` é TEXT
|
|
514
|
+
// (config.mjs). Sem este ramo, `optionId` devolvia null num campo sem
|
|
515
|
+
// `options` e a escrita virava `return false` — com `release: 'native'`
|
|
516
|
+
// declarado nas capabilities. Ninguém percebia porque nada escreve
|
|
517
|
+
// `release` hoje, e o chamador não distingue "recusei" de "já estava
|
|
518
|
+
// preenchido": os dois são `false`.
|
|
519
|
+
const select = Boolean(f.options && Object.keys(f.options).length);
|
|
520
|
+
const opt = select ? optionId(f, value) : null;
|
|
521
|
+
if (select && !opt) return false;
|
|
522
|
+
|
|
507
523
|
const itemId = await itemDoBoard(ref);
|
|
508
524
|
if (onlyIfEmpty) {
|
|
509
525
|
// Escreve só no vazio: o tipo inferido do título é um palpite, e
|
|
510
526
|
// sobrescrever o que um humano ajustou no board trocaria dado bom por
|
|
511
527
|
// palpite.
|
|
512
|
-
const atual =
|
|
528
|
+
const atual = select
|
|
529
|
+
? await a.getItemSingleSelectValue(ptk, itemId, f.id)
|
|
530
|
+
: await a.getItemTextValue(ptk, itemId, f.id);
|
|
513
531
|
if (atual) return false;
|
|
514
532
|
}
|
|
515
|
-
await a.setItemSingleSelect(ptk, project.id, itemId, f.id, opt);
|
|
533
|
+
if (select) await a.setItemSingleSelect(ptk, project.id, itemId, f.id, opt);
|
|
534
|
+
else await a.setItemText(ptk, project.id, itemId, f.id, String(value ?? ''));
|
|
516
535
|
return true;
|
|
517
536
|
},
|
|
518
537
|
|
|
@@ -543,12 +562,29 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
543
562
|
});
|
|
544
563
|
},
|
|
545
564
|
|
|
565
|
+
// A parcialidade é decidida AQUI, e não na rota: campo ausente não entra no
|
|
566
|
+
// payload. É o único nível em que um teste consegue ver o que foi enviado —
|
|
567
|
+
// ver a nota em `updateIssue` (github-rest.mjs).
|
|
568
|
+
async updateWorkItem({ ref, title, body } = {}) {
|
|
569
|
+
const campos = {};
|
|
570
|
+
if (title !== undefined) campos.title = title;
|
|
571
|
+
if (body !== undefined) campos.body = body;
|
|
572
|
+
await a.updateIssue(token, owner, repo, refNumber(refKey(ref)), campos);
|
|
573
|
+
},
|
|
574
|
+
|
|
546
575
|
closeWorkItem({ ref } = {}) {
|
|
547
576
|
// `reason` é ignorado: no GitHub fechar é um ESTADO, e a distinção
|
|
548
577
|
// rejeitado × duplicata já vive nas labels (`closeSemantics: 'state'`).
|
|
549
578
|
return a.setIssueState(token, owner, repo, refNumber(ref), 'closed');
|
|
550
579
|
},
|
|
551
580
|
|
|
581
|
+
// A mesma rota, o outro estado. O `state_reason: 'reopened'` é o GitHub que
|
|
582
|
+
// escreve — o contrato já o lia (`WorkItem.stateReason`) antes de existir
|
|
583
|
+
// qualquer forma de produzi-lo.
|
|
584
|
+
reopenWorkItem({ ref } = {}) {
|
|
585
|
+
return a.setIssueState(token, owner, repo, refNumber(ref), 'open');
|
|
586
|
+
},
|
|
587
|
+
|
|
552
588
|
async addChild({ parent, child } = {}) {
|
|
553
589
|
const p = await hidratar(parent);
|
|
554
590
|
const c = await hidratar(child);
|
|
@@ -617,6 +653,26 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
617
653
|
const issues = await a.listIssuesByMilestone(token, owner, repo, refNumber(milestone.key));
|
|
618
654
|
return (issues || []).map(toWorkItem);
|
|
619
655
|
},
|
|
656
|
+
|
|
657
|
+
// `milestone: null` remove. A rota de escrita distingue os dois (ver o
|
|
658
|
+
// comentário em setIssueMilestone, github-rest.mjs): aqui `null` PRECISA
|
|
659
|
+
// chegar como null, não ser omitido.
|
|
660
|
+
async setMilestone({ ref, milestone = null } = {}) {
|
|
661
|
+
await a.setIssueMilestone(
|
|
662
|
+
token, owner, repo, refNumber(refKey(ref)),
|
|
663
|
+
milestone ? refNumber(milestone.key) : null,
|
|
664
|
+
);
|
|
665
|
+
},
|
|
666
|
+
|
|
667
|
+
async createMilestone({ title, description, dueOn = null } = {}) {
|
|
668
|
+
return toMilestone(await a.createMilestone(token, owner, repo, { title, description, dueOn }));
|
|
669
|
+
},
|
|
670
|
+
|
|
671
|
+
async updateMilestone({ key, title, description, dueOn, state } = {}) {
|
|
672
|
+
return toMilestone(
|
|
673
|
+
await a.updateMilestone(token, owner, repo, refNumber(key), { title, description, dueOn, state }),
|
|
674
|
+
);
|
|
675
|
+
},
|
|
620
676
|
};
|
|
621
677
|
|
|
622
678
|
return porta;
|
package/src/ports/tracker.mjs
CHANGED
|
@@ -38,6 +38,7 @@
|
|
|
38
38
|
* @typedef {import('./types.mjs').WorkItemRef} WorkItemRef
|
|
39
39
|
* @typedef {import('./types.mjs').WorkItem} WorkItem
|
|
40
40
|
* @typedef {import('./types.mjs').MilestoneRef} MilestoneRef
|
|
41
|
+
* @typedef {import('./types.mjs').MilestoneKey} MilestoneKey
|
|
41
42
|
* @typedef {import('./types.mjs').CommentRef} CommentRef
|
|
42
43
|
* @typedef {import('./types.mjs').BoardItem} BoardItem
|
|
43
44
|
* @typedef {import('./types.mjs').FieldName} FieldName
|
|
@@ -99,6 +100,18 @@
|
|
|
99
100
|
* exatamente disto — e fazê-lo no core custaria um get + um set, dois
|
|
100
101
|
* round-trips onde um tracker pode fazer um. Devolve `true` se escreveu.
|
|
101
102
|
*
|
|
103
|
+
* @property {(o: {ref: WorkItemRef, title?: string, body?: string}) => Promise<void>} updateWorkItem
|
|
104
|
+
* PARCIAL: campo não passado não é tocado, e isso é requisito, não
|
|
105
|
+
* conveniência. O `body` de uma Story carrega a linha `Depende de: #N` que
|
|
106
|
+
* `lib/dependencies.mjs` analisa e que `implement` e `merge` leem — uma
|
|
107
|
+
* escrita que exigisse o corpo inteiro faria um renomear de título apagar
|
|
108
|
+
* dependência, com sucesso na chamada e silêncio no efeito.
|
|
109
|
+
*
|
|
110
|
+
* OBRIGATÓRIA, e sem capability que a desligue: `createWorkItem` já toma
|
|
111
|
+
* `title` e `body`, então todo tracker que implementa a criação sabe escrever
|
|
112
|
+
* os dois. Não existe fornecedor onde nascer com título seja possível e
|
|
113
|
+
* renomear não.
|
|
114
|
+
*
|
|
102
115
|
* @property {() => Promise<BoardItem[]>} boardSnapshot
|
|
103
116
|
* @property {(o: {ref: WorkItemRef, reason?: 'completed'|'not-planned'|'duplicate'}) => Promise<void>} closeWorkItem
|
|
104
117
|
* `reason` existe porque em `closeSemantics: 'transition-and-resolution'` o
|
|
@@ -107,6 +120,26 @@
|
|
|
107
120
|
*
|
|
108
121
|
* ── CONDICIONAIS ──────────────────────────────────────────────────────────
|
|
109
122
|
*
|
|
123
|
+
* @property {(o: {ref: WorkItemRef}) => Promise<void>} [reopenWorkItem] reopen: 'native'
|
|
124
|
+
* A inversa de `closeWorkItem`. O contrato já sabia LER um item reaberto —
|
|
125
|
+
* `WorkItem.stateReason` tem `'reopened'` no enum desde a Fase 1 — e não
|
|
126
|
+
* tinha como produzir um: a rota existia (`setIssueState` aceita o estado) e
|
|
127
|
+
* só era chamada com `'closed'`, pelo único consumidor que havia.
|
|
128
|
+
*
|
|
129
|
+
* Sem argumento de destino, e isso só é possível porque `state`, `stage` e
|
|
130
|
+
* `progress` são três dimensões SEPARADAS aqui: reabrir não decide para qual
|
|
131
|
+
* Etapa o item volta, porque a Etapa não muda. Num tracker
|
|
132
|
+
* `closeSemantics: 'transition-and-resolution'` o plugin transiciona para o
|
|
133
|
+
* status não-Done que corresponde à Etapa atual e limpa a `resolution` — a
|
|
134
|
+
* informação necessária já está no item.
|
|
135
|
+
*
|
|
136
|
+
* CONDICIONAL, e não obrigatória junto com `closeWorkItem`, por uma
|
|
137
|
+
* assimetria real: `closeSemantics` garante que fechar é sempre possível
|
|
138
|
+
* (todo valor do enum implica isso), mas sair de Done depende de existir a
|
|
139
|
+
* transição no workflow do site — no Jira isso é configuração de quem
|
|
140
|
+
* instalou, não do fornecedor. `reopen: 'none'` é a declaração honesta desse
|
|
141
|
+
* caso, e o core recusa com mensagem em vez de tentar e estourar.
|
|
142
|
+
*
|
|
110
143
|
* @property {(o: {ref: WorkItemRef}) => Promise<Progress|null>} [getProgress] progress: 'native'
|
|
111
144
|
* @property {(o: {ref: WorkItemRef, progress: Progress}) => Promise<boolean>} [setProgress]
|
|
112
145
|
*
|
|
@@ -125,7 +158,40 @@
|
|
|
125
158
|
* @property {() => Promise<MilestoneRef[]>} [listMilestones] milestones: 'native'
|
|
126
159
|
* @property {(o: {key: string}) => Promise<MilestoneRef|null>} [getMilestone]
|
|
127
160
|
* @property {(o: {key: string, description: string}) => Promise<void>} [setMilestoneDescription]
|
|
128
|
-
*
|
|
161
|
+
* ESTREITA de propósito, e não um caso particular de `updateMilestone`: o que
|
|
162
|
+
* ela promete é não tocar em mais nada. O `qa-lead` substitui um bloco
|
|
163
|
+
* delimitado dentro da descrição (`lib/qa-lead.mjs`), então precisa de uma
|
|
164
|
+
* escrita que não possa apagar título nem data-alvo por omissão.
|
|
165
|
+
* @property {(o: {milestone: MilestoneKey, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
|
|
166
|
+
* @property {(o: {ref: WorkItemRef, milestone: MilestoneKey|null}) => Promise<void>} [setMilestone]
|
|
167
|
+
* Atribui a milestone de um item que JÁ existe; `null` remove.
|
|
168
|
+
*
|
|
169
|
+
* Toma `MilestoneKey` — `{key}` basta — e não o `MilestoneRef` inteiro, pelo
|
|
170
|
+
* mesmo motivo que `getParent` devolve um parcial: quem só tem a chave não
|
|
171
|
+
* pode ser obrigado a INVENTAR `title` para chamar. Um chamador que forja
|
|
172
|
+
* `{key, title: ''}` está apostando que o plugin ignora o título, e essa
|
|
173
|
+
* aposta é sobre um plugin específico — o próximo pode não ignorar. Endereçar
|
|
174
|
+
* é pela chave; `title` e `dueOn` são o que a LEITURA devolve.
|
|
175
|
+
*
|
|
176
|
+
* Operação própria, e não `setField({field: 'release'})`, por duas razões que
|
|
177
|
+
* não são estéticas. `setField` carrega `value: string`, e identidade de
|
|
178
|
+
* milestone é `MilestoneRef {key, title}` — passar por string obrigaria a
|
|
179
|
+
* decidir AGORA qual dos dois endereça, que é exatamente a pendência de
|
|
180
|
+
* identidade de milestone ainda em aberto com a `spec-wave-ui`. E `null`
|
|
181
|
+
* precisa significar "remove", que um campo de texto não sabe expressar:
|
|
182
|
+
* string vazia é um valor, não uma ausência.
|
|
183
|
+
* @property {(o: {title: string, description?: string, dueOn?: string|null}) => Promise<MilestoneRef>} [createMilestone]
|
|
184
|
+
* @property {(o: {key: string, title?: string, description?: string, dueOn?: string|null, state?: 'open'|'closed'}) => Promise<MilestoneRef>} [updateMilestone]
|
|
185
|
+
* PARCIAL: campo não passado não é tocado. Fechar uma entrega é
|
|
186
|
+
* `state: 'closed'` aqui — não existe `closeMilestone`, porque fechar é uma
|
|
187
|
+
* transição de estado como as outras e um verbo separado convidaria um plugin
|
|
188
|
+
* a implementar só ele.
|
|
189
|
+
*
|
|
190
|
+
* NÃO existe `deleteMilestone`, e a ausência é decisão registrada: o GitHub
|
|
191
|
+
* apaga e desassocia as issues em silêncio, enquanto o Jira não deleta uma
|
|
192
|
+
* Version sem que se diga o destino do que aponta para ela. Uma assinatura
|
|
193
|
+
* `deleteMilestone({key})` seria implementável num fornecedor e impossível no
|
|
194
|
+
* outro — o dia em que entrar, entra com o destino dos itens no argumento.
|
|
129
195
|
*
|
|
130
196
|
* @property {(o: {stages: Array<{name: string, color?: string, id?: string}>}) => Promise<{fields: object}>} [syncStages]
|
|
131
197
|
* boardProvisioning: 'create'. Reescreve o vocabulário de etapas do board e
|
|
@@ -156,7 +222,7 @@
|
|
|
156
222
|
*/
|
|
157
223
|
export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
|
|
158
224
|
'setup', 'verify',
|
|
159
|
-
'createWorkItem', 'getWorkItem', 'listWorkItemsByTag',
|
|
225
|
+
'createWorkItem', 'getWorkItem', 'updateWorkItem', 'listWorkItemsByTag',
|
|
160
226
|
'addComment', 'listComments', 'updateComment',
|
|
161
227
|
'addTag', 'removeTag', 'ensureTags', 'listTags',
|
|
162
228
|
'getStage', 'setStage',
|
|
@@ -175,11 +241,19 @@ export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
|
|
|
175
241
|
* @type {Readonly<Record<string, Readonly<string[]>>>}
|
|
176
242
|
*/
|
|
177
243
|
export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
|
|
244
|
+
'reopen=native': Object.freeze(['reopenWorkItem']),
|
|
178
245
|
'progress=native': Object.freeze(['getProgress', 'setProgress']),
|
|
179
246
|
'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
|
|
180
247
|
'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
|
|
248
|
+
// Leitura E escrita. A lista nasceu só com as quatro de leitura porque a CLI
|
|
249
|
+
// nunca escreveu milestone — quem as cria aqui é humano na UI do fornecedor —
|
|
250
|
+
// e um contrato derivado de um consumidor read-only herda o silêncio dele, não
|
|
251
|
+
// uma decisão. O sintoma de que era acidente estava no próprio contrato:
|
|
252
|
+
// `createWorkItem` aceita `milestone`, então um item podia NASCER numa entrega
|
|
253
|
+
// e não ter como sair dela.
|
|
181
254
|
'milestones=native': Object.freeze([
|
|
182
255
|
'listMilestones', 'getMilestone', 'setMilestoneDescription', 'listWorkItemsByMilestone',
|
|
256
|
+
'setMilestone', 'createMilestone', 'updateMilestone',
|
|
183
257
|
]),
|
|
184
258
|
'boardProvisioning=create': Object.freeze(['syncStages']),
|
|
185
259
|
'commentMarkers=false': Object.freeze(['getItemProperty', 'setItemProperty']),
|
|
@@ -195,6 +269,9 @@ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
|
|
|
195
269
|
export function trackerRequiredOperations(capabilities = {}) {
|
|
196
270
|
const exigidas = new Set(TRACKER_REQUIRED_OPERATIONS);
|
|
197
271
|
const ligada = {
|
|
272
|
+
// Ausente vale `none`: um plugin que não declara reabrir não ganha a
|
|
273
|
+
// operação por omissão, e o core tem de perguntar antes de oferecer.
|
|
274
|
+
'reopen=native': capabilities.reopen === 'native',
|
|
198
275
|
'progress=native': capabilities.progress === 'native',
|
|
199
276
|
'hierarchy=native': capabilities.hierarchy === 'native',
|
|
200
277
|
'dependencies=native': capabilities.dependencies === 'native',
|
package/src/ports/types.mjs
CHANGED
|
@@ -66,6 +66,25 @@
|
|
|
66
66
|
* @property {string} [description]
|
|
67
67
|
*/
|
|
68
68
|
|
|
69
|
+
/**
|
|
70
|
+
* ENDEREÇO de uma milestone — a chave, e só.
|
|
71
|
+
*
|
|
72
|
+
* Existe para que as operações que apenas apontam para uma entrega
|
|
73
|
+
* (`setMilestone`, `listWorkItemsByMilestone`) não exijam o `MilestoneRef`
|
|
74
|
+
* inteiro. Um chamador que tem só o número — o snapshot de board devolve
|
|
75
|
+
* `{key, title}`, mas uma cascata Feature→Stories costuma ter só números —
|
|
76
|
+
* teria de FORJAR `title: ''` para satisfazer o tipo, e isso é uma aposta de
|
|
77
|
+
* que o plugin ignora o campo forjado. Aposta sobre um plugin específico: o
|
|
78
|
+
* próximo pode não ignorar, e aí o título vazio sobrescreve o de verdade.
|
|
79
|
+
*
|
|
80
|
+
* Mesma razão do parcial de `getParent`: ninguém deve inventar dado para
|
|
81
|
+
* conseguir chamar. Endereçar é pela chave; `title` e `dueOn` são o que a
|
|
82
|
+
* LEITURA devolve. Um `MilestoneRef` satisfaz `MilestoneKey` por construção.
|
|
83
|
+
*
|
|
84
|
+
* @typedef {object} MilestoneKey
|
|
85
|
+
* @property {string} key
|
|
86
|
+
*/
|
|
87
|
+
|
|
69
88
|
/**
|
|
70
89
|
* @typedef {object} CommentRef
|
|
71
90
|
* @property {string} id
|
|
@@ -84,6 +103,28 @@
|
|
|
84
103
|
* que o `fieldMap` do Jira resolve (lá `storyPoints` é `customfield_1XXXX`,
|
|
85
104
|
* variável por site).
|
|
86
105
|
*
|
|
106
|
+
* ⚠️ **`release` NÃO é o milestone.** São dois eixos independentes, e um item
|
|
107
|
+
* pode ter os dois, um ou nenhum:
|
|
108
|
+
*
|
|
109
|
+
* - `release` é um campo ANOTADO no item, de texto livre, sem entidade própria
|
|
110
|
+
* — não se lista, não se cria, não tem data-alvo. Aqui ele é um campo TEXT do
|
|
111
|
+
* Projects v2 (`config.mjs`); na `spec-wave-ui` é uma label (`v1.2`). Três
|
|
112
|
+
* implementações já escolheram três mecanismos, e isso está certo: o
|
|
113
|
+
* mecanismo é do plugin.
|
|
114
|
+
* - O milestone é uma ENTIDADE do tracker, com `key`, título e `dueOn`, que se
|
|
115
|
+
* lista (`listMilestones`) e pela qual se filtra (`listWorkItemsByMilestone`).
|
|
116
|
+
* É o que `preflight`, `audit` e `qa-lead` consomem. Escreve-se com
|
|
117
|
+
* `setMilestone`, nunca por aqui.
|
|
118
|
+
*
|
|
119
|
+
* A distinção é normativa, e não descritiva do GitHub: sem ela, um plugin pode
|
|
120
|
+
* representar `release` COMO o milestone de boa-fé, e aí `setField({field:
|
|
121
|
+
* 'release'})` e `setMilestone()` viram dois caminhos de escrita para o mesmo
|
|
122
|
+
* valor, sem nada que os mantenha coerentes. Um plugin que só tenha um dos dois
|
|
123
|
+
* declara o outro ausente em `capabilities` — não os funde.
|
|
124
|
+
*
|
|
125
|
+
* O sintoma de confundir os dois é mudo: a escrita tem SUCESSO, o texto entra
|
|
126
|
+
* no campo anotado e os filtros por milestone seguem sem enxergar o item.
|
|
127
|
+
*
|
|
87
128
|
* @typedef {'workItemType'|'priority'|'storyPoints'|'area'|'release'} FieldName
|
|
88
129
|
*/
|
|
89
130
|
|