@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.
- package/package.json +1 -1
- package/src/api/github-graphql.mjs +51 -0
- package/src/api/github-rest.mjs +48 -0
- 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 +662 -0
- package/src/ports/scm.mjs +197 -0
- package/src/ports/tracker.mjs +280 -0
- package/src/ports/types.mjs +295 -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,144 @@
|
|
|
1
|
+
// A POLÍTICA do board — pura, sem rede, sem fornecedor.
|
|
2
|
+
//
|
|
3
|
+
// Saiu de `lib/board.mjs` sem mudar de corpo. A separação é a fronteira do
|
|
4
|
+
// RFC-006 §3.2: o core decide PARA ONDE e SE o item anda; o plugin sabe COMO
|
|
5
|
+
// escrever isso no fornecedor.
|
|
6
|
+
//
|
|
7
|
+
// O invariante que justifica o arquivo existir separado: **direção de fluxo
|
|
8
|
+
// nunca é decisão de plugin.** Um tracker que pudesse recusar ou inverter um
|
|
9
|
+
// avanço de etapa transformaria a regra central do RFC-001 em comportamento por
|
|
10
|
+
// fornecedor — a mesma Feature andaria diferente em dois clientes.
|
|
11
|
+
|
|
12
|
+
import { STAGE_ORDER, STATUS_OPTIONS, STAGE_DONE } from '../config.mjs';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* A Etapa pode avançar de `current` para `target`? (função PURA)
|
|
16
|
+
*
|
|
17
|
+
* Regra do board: a Etapa só AVANÇA. Três casos param o movimento:
|
|
18
|
+
* • já está no destino ou adiante na ordem canônica;
|
|
19
|
+
* • a etapa ATUAL não está em STAGE_ORDER (coluna criada à mão no board, ou
|
|
20
|
+
* resíduo de uma versão anterior do config). Antes esse caso caía no
|
|
21
|
+
* `curIdx === -1` e DESLIGAVA o guard, permitindo retrocesso — sem saber onde
|
|
22
|
+
* o item está na ordem, o certo é não mexer;
|
|
23
|
+
* • a etapa de DESTINO não está em STAGE_ORDER (nome inválido).
|
|
24
|
+
*
|
|
25
|
+
* @param {string|null} current etapa atual do item (null = ainda sem etapa)
|
|
26
|
+
* @param {string} target etapa de destino
|
|
27
|
+
* @returns {boolean} true se deve escrever a nova Etapa
|
|
28
|
+
*/
|
|
29
|
+
export function shouldAdvanceStage(current, target) {
|
|
30
|
+
const tgtIdx = STAGE_ORDER.indexOf(target);
|
|
31
|
+
if (tgtIdx === -1) return false;
|
|
32
|
+
if (!current) return true; // item ainda sem Etapa definida
|
|
33
|
+
const curIdx = STAGE_ORDER.indexOf(current);
|
|
34
|
+
if (curIdx === -1) return false; // etapa atual desconhecida — não arrisca retroceder
|
|
35
|
+
return curIdx < tgtIdx;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* O movimento de etapa, decidido (função PURA).
|
|
40
|
+
*
|
|
41
|
+
* Mesma decisão de `shouldAdvanceStage`, com o MOTIVO junto. O motivo é o que
|
|
42
|
+
* permite a quem chama distinguir "já estava adiante" (normal, e o fluxo segue)
|
|
43
|
+
* de "não sei onde o item está" (board divergente, e alguém precisa olhar) —
|
|
44
|
+
* hoje os dois chegam como o mesmo `false`.
|
|
45
|
+
*
|
|
46
|
+
* Deliberadamente NÃO avisa sobre trilha (`isStageInTrack`): `advanceToStage`
|
|
47
|
+
* nunca avisou, e acrescentar saída nova aqui seria mudança de comportamento
|
|
48
|
+
* numa fase que promete não ter nenhuma. Quem quiser o aviso chama
|
|
49
|
+
* `isStageInTrack` no call site, como `move` já faz.
|
|
50
|
+
*
|
|
51
|
+
* @param {object} params
|
|
52
|
+
* @param {string|null} params.current
|
|
53
|
+
* @param {string} params.target
|
|
54
|
+
* @returns {{advance: boolean, reason: 'ok'|'ja-adiante'|'atual-desconhecida'|'destino-invalido'}}
|
|
55
|
+
*/
|
|
56
|
+
export function planStageMove({ current, target }) {
|
|
57
|
+
if (STAGE_ORDER.indexOf(target) === -1) return { advance: false, reason: 'destino-invalido' };
|
|
58
|
+
if (!current) return { advance: true, reason: 'ok' };
|
|
59
|
+
if (STAGE_ORDER.indexOf(current) === -1) return { advance: false, reason: 'atual-desconhecida' };
|
|
60
|
+
return shouldAdvanceStage(current, target)
|
|
61
|
+
? { advance: true, reason: 'ok' }
|
|
62
|
+
: { advance: false, reason: 'ja-adiante' };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// Normaliza para comparação: sem emoji/pontuação, minúsculo, espaços colapsados.
|
|
66
|
+
// "👀 Code Review" e "code review" precisam casar.
|
|
67
|
+
function stageKey(value) {
|
|
68
|
+
return String(value ?? '')
|
|
69
|
+
.normalize('NFD')
|
|
70
|
+
.replace(/[̀-ͯ]/g, '') // acentos (após NFD)
|
|
71
|
+
.replace(/[^\p{Letter}\p{Number}]+/gu, ' ') // emoji e pontuação
|
|
72
|
+
.trim()
|
|
73
|
+
.toLowerCase();
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Resolve o nome canônico de uma Etapa a partir de entrada humana (função PURA).
|
|
78
|
+
*
|
|
79
|
+
* Aceita o nome com ou sem emoji, com qualquer caixa e sem acento
|
|
80
|
+
* ("code review", "Homologacao", "🚧 Desenvolvimento"). Casa primeiro exato,
|
|
81
|
+
* depois por prefixo; prefixo que casa com mais de uma etapa é AMBÍGUO e vira
|
|
82
|
+
* erro listando as candidatas — melhor recusar que mover para a coluna errada.
|
|
83
|
+
*
|
|
84
|
+
* @param {string} input entrada do usuário
|
|
85
|
+
* @returns {{ stage: string|null, error: string|null }}
|
|
86
|
+
*/
|
|
87
|
+
export function resolveStageName(input) {
|
|
88
|
+
const key = stageKey(input);
|
|
89
|
+
const options = STATUS_OPTIONS.map(s => ({ name: s.name, key: stageKey(s.name) }));
|
|
90
|
+
const list = () => STATUS_OPTIONS.map(s => `"${s.name}"`).join(', ');
|
|
91
|
+
|
|
92
|
+
if (!key) {
|
|
93
|
+
return { stage: null, error: `Etapa não informada. Use uma destas: ${list()}.` };
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const exact = options.find(o => o.key === key);
|
|
97
|
+
if (exact) return { stage: exact.name, error: null };
|
|
98
|
+
|
|
99
|
+
const partial = options.filter(o => o.key.startsWith(key));
|
|
100
|
+
if (partial.length === 1) return { stage: partial[0].name, error: null };
|
|
101
|
+
if (partial.length > 1) {
|
|
102
|
+
return {
|
|
103
|
+
stage: null,
|
|
104
|
+
error:
|
|
105
|
+
`Etapa "${input}" é ambígua — casa com ${partial.map(o => `"${o.name}"`).join(' e ')}. ` +
|
|
106
|
+
'Seja mais específico.',
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Índice do board por número de issue (função PURA).
|
|
115
|
+
*
|
|
116
|
+
* @param {Array<{number:number}>} items saída de listProjectItems
|
|
117
|
+
* @returns {Map<number, object>}
|
|
118
|
+
*/
|
|
119
|
+
export function indexBoardItems(items) {
|
|
120
|
+
return new Map((items || []).filter(i => i?.number).map(i => [i.number, i]));
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* As Features que ainda têm trabalho (função PURA).
|
|
125
|
+
*
|
|
126
|
+
* "Ainda tem trabalho" = issue aberta e Etapa diferente de 🎉 Done. É este o
|
|
127
|
+
* conjunto do `order` sem argumento: o mapa de quem depende de quem quando o
|
|
128
|
+
* trabalho de uma onda inteira está espalhado por várias Features.
|
|
129
|
+
*
|
|
130
|
+
* O tipo sai do campo "Work Item Type", com FALLBACK no prefixo do título: o
|
|
131
|
+
* campo ficou vazio em todo item criado pelo apply até a v0.21.0, e um board com
|
|
132
|
+
* esse buraco não pode virar um mapa vazio em silêncio.
|
|
133
|
+
*
|
|
134
|
+
* @param {Array<object>} items saída de listProjectItems
|
|
135
|
+
* @returns {Array<object>} Features, em ordem crescente de número
|
|
136
|
+
*/
|
|
137
|
+
export function selectOpenFeatures(items) {
|
|
138
|
+
return (items || [])
|
|
139
|
+
.filter(i => i?.number
|
|
140
|
+
&& String(i.state || '').toUpperCase() !== 'CLOSED'
|
|
141
|
+
&& (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
|
|
142
|
+
&& i.fields?.Etapa !== STAGE_DONE)
|
|
143
|
+
.sort((a, b) => a.number - b.number);
|
|
144
|
+
}
|
package/src/lib/board.mjs
CHANGED
|
@@ -1,12 +1,37 @@
|
|
|
1
|
-
//
|
|
2
|
-
//
|
|
3
|
-
// (
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
// O SERVIÇO de fluxo do board.
|
|
2
|
+
//
|
|
3
|
+
// A política (quem pode andar para onde) saiu para `board-policy.mjs`; o
|
|
4
|
+
// endereçamento (ids de campo, ids de opção, item do project) saiu para
|
|
5
|
+
// `src/plugins/tracker-github-projects/`. O que sobra aqui é a ORQUESTRAÇÃO, e
|
|
6
|
+
// ela é a parte que não pode virar comportamento por fornecedor:
|
|
7
|
+
//
|
|
8
|
+
// ler a etapa atual → consultar a política → só então mandar escrever.
|
|
9
|
+
//
|
|
10
|
+
// Este é o único módulo do core autorizado a chamar `tracker.setStage`. Quando
|
|
11
|
+
// essa chamada acontece, o guard JÁ rodou — o plugin nunca recebe a pergunta
|
|
12
|
+
// "pode avançar?".
|
|
13
|
+
//
|
|
14
|
+
// Ver a distinção Etapa × Status em config.mjs: `stage` é a coluna, `progress`
|
|
15
|
+
// é o Todo/In Progress/Done DENTRO dela, e os dois são dimensões separadas.
|
|
16
|
+
|
|
17
|
+
import { CONFIG_FILE, WORK_ITEM_TYPES } from '../config.mjs';
|
|
18
|
+
import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
|
|
6
19
|
import { loadConfig } from './project-root.mjs';
|
|
7
20
|
import { invalidateCache } from './net-cache.mjs';
|
|
8
|
-
|
|
9
|
-
|
|
21
|
+
import { planStageMove } from './board-policy.mjs';
|
|
22
|
+
|
|
23
|
+
// A política continua exportada daqui: era daqui que ~10 módulos e 6 testes a
|
|
24
|
+
// importavam, e trocar o caminho de import em todos eles no mesmo commit em que
|
|
25
|
+
// o corpo muda de casa tornaria o diff impossível de conferir.
|
|
26
|
+
export {
|
|
27
|
+
indexBoardItems,
|
|
28
|
+
planStageMove,
|
|
29
|
+
resolveStageName,
|
|
30
|
+
selectOpenFeatures,
|
|
31
|
+
shouldAdvanceStage,
|
|
32
|
+
} from './board-policy.mjs';
|
|
33
|
+
|
|
34
|
+
// Toda ESCRITA de board passa por advanceToStage/forceStage/setProgress —
|
|
10
35
|
// invalidar aqui cobre todos os comandos de uma vez (move, qa, code-review,
|
|
11
36
|
// merge, implement…): o snapshot cacheado (`board-items`, lib/net-cache.mjs)
|
|
12
37
|
// não pode sobreviver a uma Etapa que acabou de mudar. Best-effort por
|
|
@@ -22,9 +47,6 @@ function dropBoardCache() {
|
|
|
22
47
|
* @param {object} [opts]
|
|
23
48
|
* @param {string} [opts.cwd=process.cwd()] diretório onde começar a busca
|
|
24
49
|
* @returns {{ project: object|null, root: string|null, error: string|null }}
|
|
25
|
-
* project = bloco com id/fields; root = diretório do config;
|
|
26
|
-
* error = motivo legível quando project é null (compõe os avisos
|
|
27
|
-
* "… — board não atualizado." dos chamadores).
|
|
28
50
|
*/
|
|
29
51
|
export function loadProjectConfig({ cwd = process.cwd() } = {}) {
|
|
30
52
|
const { config, root, error } = loadConfig(cwd);
|
|
@@ -37,142 +59,76 @@ export function loadProjectConfig({ cwd = process.cwd() } = {}) {
|
|
|
37
59
|
}
|
|
38
60
|
|
|
39
61
|
/**
|
|
40
|
-
*
|
|
41
|
-
* .spec-wave.json (bloco `fields`, ou o formato legado etapaFieldId/
|
|
42
|
-
* stageOptions para "Etapa") e cai na API GraphQL como fallback.
|
|
43
|
-
*
|
|
44
|
-
* @param {string} token
|
|
45
|
-
* @param {object} project bloco project do .spec-wave.json (precisa de .id)
|
|
46
|
-
* @param {string} name nome do campo (ex.: 'Etapa', 'Status')
|
|
47
|
-
* @returns {Promise<{ id: string, options: Record<string,string> }|null>}
|
|
48
|
-
*/
|
|
49
|
-
export async function resolveField(token, project, name) {
|
|
50
|
-
if (project.fields?.[name]) return project.fields[name];
|
|
51
|
-
if (name === 'Etapa' && project.etapaFieldId) {
|
|
52
|
-
return { id: project.etapaFieldId, options: project.stageOptions || {} };
|
|
53
|
-
}
|
|
54
|
-
return await getSingleSelectField(token, project.id, name);
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* A Etapa pode avançar de `current` para `target`? (função PURA — testável).
|
|
62
|
+
* Há um tracker utilizável a partir daqui? (só leitura de config)
|
|
59
63
|
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
* resíduo de uma versão anterior do config). Antes esse caso caía no
|
|
64
|
-
* `curIdx === -1` e DESLIGAVA o guard, permitindo retrocesso — sem saber onde
|
|
65
|
-
* o item está na ordem, o certo é não mexer;
|
|
66
|
-
* • a etapa de DESTINO não está em STAGE_ORDER (nome inválido).
|
|
64
|
+
* Substitui o uso de `loadProjectConfig` por quem só queria a STRING DE ERRO —
|
|
65
|
+
* `run`, `implement`, `qa-lead` e `order` a usavam assim, e nenhum deles
|
|
66
|
+
* precisa saber que existe um bloco `project` com ids do Projects v2.
|
|
67
67
|
*
|
|
68
|
-
* @param {
|
|
69
|
-
* @param {string}
|
|
70
|
-
* @returns {
|
|
68
|
+
* @param {object} [opts]
|
|
69
|
+
* @param {string} [opts.cwd=process.cwd()]
|
|
70
|
+
* @returns {{ ok: boolean, root: string|null, error: string|null }}
|
|
71
71
|
*/
|
|
72
|
-
export function
|
|
73
|
-
const
|
|
74
|
-
|
|
75
|
-
if (!current) return true; // item ainda sem Etapa definida
|
|
76
|
-
const curIdx = STAGE_ORDER.indexOf(current);
|
|
77
|
-
if (curIdx === -1) return false; // etapa atual desconhecida — não arrisca retroceder
|
|
78
|
-
return curIdx < tgtIdx;
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
// Normaliza para comparação: sem emoji/pontuação, minúsculo, espaços colapsados.
|
|
82
|
-
// "👀 Code Review" e "code review" precisam casar.
|
|
83
|
-
function stageKey(value) {
|
|
84
|
-
return String(value ?? '')
|
|
85
|
-
.normalize('NFD')
|
|
86
|
-
.replace(/[̀-ͯ]/g, '') // acentos (após NFD)
|
|
87
|
-
.replace(/[^\p{Letter}\p{Number}]+/gu, ' ') // emoji e pontuação
|
|
88
|
-
.trim()
|
|
89
|
-
.toLowerCase();
|
|
72
|
+
export function trackerAvailable({ cwd = process.cwd() } = {}) {
|
|
73
|
+
const { project, root, error } = loadProjectConfig({ cwd });
|
|
74
|
+
return { ok: Boolean(project), root, error };
|
|
90
75
|
}
|
|
91
76
|
|
|
92
77
|
/**
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
* @param {string}
|
|
101
|
-
* @
|
|
78
|
+
* Monta a porta de tracker a partir do config, com a credencial de board.
|
|
79
|
+
*
|
|
80
|
+
* `projectToken` é separado porque quatro comandos e uma lib usam
|
|
81
|
+
* `PROJECT_TOKEN || token` SÓ para Projects v2 — ver a nota em
|
|
82
|
+
* `src/plugins/tracker-github-projects/index.mjs`.
|
|
83
|
+
*
|
|
84
|
+
* @param {object} params
|
|
85
|
+
* @param {string} params.token
|
|
86
|
+
* @param {string} [params.projectToken]
|
|
87
|
+
* @param {string} params.owner
|
|
88
|
+
* @param {string} params.repo
|
|
89
|
+
* @param {string} [params.cwd]
|
|
90
|
+
* @param {object} [params.tracker] porta JÁ construída — é o seam dos testes de
|
|
91
|
+
* fumaça (`deps.tracker`). Quando vem, o bloco `project` do config nem é
|
|
92
|
+
* exigido: quem injeta a porta já decidiu de onde ela vem. `root` continua
|
|
93
|
+
* saindo do config, porque os chamadores o usam para achar os documentos.
|
|
94
|
+
* @returns {{ tracker: object|null, root: string|null, error: string|null }}
|
|
102
95
|
*/
|
|
103
|
-
export function
|
|
104
|
-
const
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
if (!
|
|
109
|
-
return {
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
const exact = options.find(o => o.key === key);
|
|
113
|
-
if (exact) return { stage: exact.name, error: null };
|
|
114
|
-
|
|
115
|
-
const partial = options.filter(o => o.key.startsWith(key));
|
|
116
|
-
if (partial.length === 1) return { stage: partial[0].name, error: null };
|
|
117
|
-
if (partial.length > 1) {
|
|
118
|
-
return {
|
|
119
|
-
stage: null,
|
|
120
|
-
error:
|
|
121
|
-
`Etapa "${input}" é ambígua — casa com ${partial.map(o => `"${o.name}"`).join(' e ')}. ` +
|
|
122
|
-
'Seja mais específico.',
|
|
123
|
-
};
|
|
96
|
+
export function openTracker({ token, projectToken, owner, repo, cwd = process.cwd(), tracker: injetado = null } = {}) {
|
|
97
|
+
const { config, root, error: configError } = loadConfig(cwd);
|
|
98
|
+
if (injetado) return { tracker: injetado, root, error: null };
|
|
99
|
+
if (configError) return { tracker: null, root, error: configError };
|
|
100
|
+
const project = config.project || {};
|
|
101
|
+
if (!project.id) {
|
|
102
|
+
return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
|
|
124
103
|
}
|
|
125
|
-
|
|
126
|
-
|
|
104
|
+
// owner/repo caem no config quando o chamador não os tem: `loadProjectConfig`
|
|
105
|
+
// nunca precisou deles (o board é endereçado por `project.id`), mas a porta
|
|
106
|
+
// também faz REST de issue, que é endereçada por repositório. Quem TEM o par
|
|
107
|
+
// resolvido — os comandos, via resolveHubContext — passa o dele e vence.
|
|
108
|
+
return {
|
|
109
|
+
tracker: createGithubTracker({
|
|
110
|
+
token,
|
|
111
|
+
projectToken,
|
|
112
|
+
owner: owner || config.owner,
|
|
113
|
+
repo: repo || config.repo,
|
|
114
|
+
project,
|
|
115
|
+
}),
|
|
116
|
+
root,
|
|
117
|
+
error: null,
|
|
118
|
+
};
|
|
127
119
|
}
|
|
128
120
|
|
|
129
121
|
/**
|
|
130
|
-
*
|
|
122
|
+
* Preenche um campo do item quando ele está VAZIO (best-effort).
|
|
131
123
|
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
|
|
135
|
-
export function indexBoardItems(items) {
|
|
136
|
-
return new Map((items || []).filter(i => i?.number).map(i => [i.number, i]));
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
/**
|
|
140
|
-
* As Features que ainda têm trabalho (função PURA).
|
|
141
|
-
*
|
|
142
|
-
* "Ainda tem trabalho" = issue aberta e Etapa diferente de 🎉 Done. É este o
|
|
143
|
-
* conjunto do `order` sem argumento: o mapa de quem depende de quem quando o
|
|
144
|
-
* trabalho de uma onda inteira está espalhado por várias Features.
|
|
124
|
+
* O "Work Item Type" existe no board desde o `init`, mas só o comando `issue` o
|
|
125
|
+
* escrevia: toda issue nascida do `decompose --apply` (dezenas por Feature)
|
|
126
|
+
* ficava com o tipo em branco, e as telas que agrupam por ele as perdiam.
|
|
145
127
|
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
* esse buraco não pode virar um mapa vazio em silêncio.
|
|
149
|
-
*
|
|
150
|
-
* @param {Array<object>} items saída de listProjectItems
|
|
151
|
-
* @returns {Array<object>} Features, em ordem crescente de número
|
|
152
|
-
*/
|
|
153
|
-
export function selectOpenFeatures(items) {
|
|
154
|
-
return (items || [])
|
|
155
|
-
.filter(i => i?.number
|
|
156
|
-
&& String(i.state || '').toUpperCase() !== 'CLOSED'
|
|
157
|
-
&& (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
|
|
158
|
-
&& i.fields?.Etapa !== STAGE_DONE)
|
|
159
|
-
.sort((a, b) => a.number - b.number);
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
/**
|
|
163
|
-
* Preenche o "Work Item Type" do item quando ele está VAZIO (best-effort).
|
|
164
|
-
*
|
|
165
|
-
* O campo existe no board desde o `init`, mas só o comando `issue` o escrevia:
|
|
166
|
-
* toda issue nascida do `decompose --apply` (dezenas por Feature) e todo item
|
|
167
|
-
* que entrou no board por outro caminho ficavam com o tipo em branco, e as
|
|
168
|
-
* telas que agrupam por Work Item Type os perdiam. Não é configuração faltando:
|
|
169
|
-
* os mesmos ids, project e token escrevem o campo sem falha quando alguém o faz
|
|
170
|
-
* à mão. O `move` também não o reparava, então nem passar pelo fluxo corrigia.
|
|
171
|
-
*
|
|
172
|
-
* Escreve só no vazio, de propósito: o tipo do título ("[STORY] …") é uma
|
|
173
|
-
* inferência, e sobrescrever um valor que um humano ajustou no board seria
|
|
128
|
+
* Escreve só no vazio, de propósito: o tipo inferido do título ("[STORY] …") é
|
|
129
|
+
* uma inferência, e sobrescrever um valor que um humano ajustou no board seria
|
|
174
130
|
* trocar um dado bom por um palpite. Por isso também roda ANTES do guard de
|
|
175
|
-
* avanço
|
|
131
|
+
* avanço — item já adiante não avança, mas continua merecendo o reparo.
|
|
176
132
|
*
|
|
177
133
|
* Nunca lança: campo ausente, opção inexistente ou falha de rede viram `false`.
|
|
178
134
|
* O tipo é informação de organização; derrubar por causa dele um comando que
|
|
@@ -180,16 +136,17 @@ export function selectOpenFeatures(items) {
|
|
|
180
136
|
*
|
|
181
137
|
* @returns {Promise<boolean>} true se escreveu o campo agora
|
|
182
138
|
*/
|
|
183
|
-
export async function ensureWorkItemType(
|
|
184
|
-
if (!
|
|
139
|
+
export async function ensureWorkItemType(tracker, ref, itemType) {
|
|
140
|
+
if (!tracker || !ref || !itemType) return false;
|
|
141
|
+
// O vocabulário é do RFC-001, não do fornecedor: quem decide que "Story" é um
|
|
142
|
+
// tipo e "Bugzinho" não é o core. Deixar a recusa por conta do plugin — que
|
|
143
|
+
// só sabe dizer "não tenho essa opção" — amarraria a regra ao board em uso: um
|
|
144
|
+
// board com uma opção extra passaria a aceitar tipo fora do vocabulário, e o
|
|
145
|
+
// `setField` é genérico para TODO campo, então não é lugar de conhecer o
|
|
146
|
+
// vocabulário de um deles.
|
|
185
147
|
if (!WORK_ITEM_TYPES.includes(itemType)) return false;
|
|
186
|
-
const optionId = typeField.options?.[itemType];
|
|
187
|
-
if (!optionId) return false;
|
|
188
148
|
try {
|
|
189
|
-
|
|
190
|
-
if (current) return false; // já tem tipo — nunca sobrescreve
|
|
191
|
-
await setItemSingleSelect(token, project.id, itemId, typeField.id, optionId);
|
|
192
|
-
return true;
|
|
149
|
+
return await tracker.setField({ ref, field: 'workItemType', value: itemType, onlyIfEmpty: true });
|
|
193
150
|
} catch (err) {
|
|
194
151
|
// Avisa em vez de calar: foi o silêncio que deixou 120 itens sem tipo por
|
|
195
152
|
// seis features seguidas sem ninguém perceber.
|
|
@@ -199,57 +156,31 @@ export async function ensureWorkItemType(token, project, typeField, itemId, item
|
|
|
199
156
|
}
|
|
200
157
|
|
|
201
158
|
/**
|
|
202
|
-
* Avança um item
|
|
203
|
-
* `targetStatus`. Uma issue só AVANÇA: se já estiver em `targetStage` ou em uma
|
|
204
|
-
* etapa posterior (pela ordem canônica STAGE_ORDER), não é tocada.
|
|
159
|
+
* Avança um item para `stage` e, opcionalmente, escreve o progresso.
|
|
205
160
|
*
|
|
206
|
-
*
|
|
207
|
-
*
|
|
208
|
-
*
|
|
209
|
-
* @param {
|
|
210
|
-
* @param {
|
|
211
|
-
* @param {string}
|
|
212
|
-
* @param {string}
|
|
213
|
-
* @param {
|
|
214
|
-
* @param {
|
|
215
|
-
* @param {string} [opts.itemType] tipo do item ('Story', 'Task', …) — escrito
|
|
216
|
-
* apenas se o campo estiver vazio (ver ensureWorkItemType)
|
|
161
|
+
* A POLÍTICA é aplicada aqui, antes de qualquer escrita: lê a etapa atual,
|
|
162
|
+
* consulta `planStageMove` (pura) e só então manda escrever.
|
|
163
|
+
*
|
|
164
|
+
* @param {object} params
|
|
165
|
+
* @param {object} params.tracker porta de tracker
|
|
166
|
+
* @param {object|string|number} params.ref work item
|
|
167
|
+
* @param {string} params.stage etapa de destino
|
|
168
|
+
* @param {string|null} [params.progress] Todo / In Progress / Done
|
|
169
|
+
* @param {string|null} [params.itemType] escrito só se o campo estiver vazio
|
|
217
170
|
* @returns {Promise<boolean>} true se avançou; false se já estava adiante
|
|
218
171
|
*/
|
|
219
|
-
export async function advanceToStage(
|
|
220
|
-
|
|
221
|
-
)
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
// Nunca retroceder — a decisão vive em shouldAdvanceStage (pura, testada).
|
|
228
|
-
const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
|
|
229
|
-
if (!shouldAdvanceStage(current, targetStage)) return false;
|
|
230
|
-
const optionId = etapaField.options?.[targetStage];
|
|
231
|
-
// Opção que não resolve é board divergente (coluna renomeada, init de outra
|
|
232
|
-
// versão) — pular a escrita e devolver true fazia o chamador imprimir ✅
|
|
233
|
-
// sem nada ter sido escrito. Melhor falhar nomeando o que faltou.
|
|
234
|
-
if (!optionId) {
|
|
235
|
-
throw new Error(
|
|
236
|
-
`A Etapa "${targetStage}" não existe no board (opções: ` +
|
|
237
|
-
`${Object.keys(etapaField.options || {}).join(', ') || 'nenhuma'}). ` +
|
|
238
|
-
'O board divergiu da config — rode `spec-wave refresh` ou renomeie a coluna de volta.'
|
|
239
|
-
);
|
|
240
|
-
}
|
|
241
|
-
await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
|
|
172
|
+
export async function advanceToStage({ tracker, ref, stage, progress = null, itemType = null }) {
|
|
173
|
+
// Antes do guard: item que não avança também precisa do reparo de tipo.
|
|
174
|
+
await ensureWorkItemType(tracker, ref, itemType);
|
|
175
|
+
|
|
176
|
+
if (stage) {
|
|
177
|
+
const current = await tracker.getStage({ ref }).catch(() => null);
|
|
178
|
+
if (!planStageMove({ current, target: stage }).advance) return false;
|
|
179
|
+
await tracker.setStage({ ref, stage });
|
|
242
180
|
dropBoardCache();
|
|
243
181
|
}
|
|
244
|
-
if (
|
|
245
|
-
|
|
246
|
-
if (!optionId) {
|
|
247
|
-
throw new Error(
|
|
248
|
-
`O Status "${targetStatus}" não existe no board (opções: ` +
|
|
249
|
-
`${Object.keys(statusField.options || {}).join(', ') || 'nenhuma'}).`
|
|
250
|
-
);
|
|
251
|
-
}
|
|
252
|
-
await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
|
|
182
|
+
if (progress) {
|
|
183
|
+
await tracker.setProgress({ ref, progress });
|
|
253
184
|
dropBoardCache();
|
|
254
185
|
}
|
|
255
186
|
return true;
|
|
@@ -262,65 +193,35 @@ export async function advanceToStage(
|
|
|
262
193
|
* escape hatch: a Etapa só avança. Esta função existe porque a automação erra —
|
|
263
194
|
* uma corrida entre o `decompose-apply` e o `code-review` já pôs duas Stories e
|
|
264
195
|
* duas Tasks em 🎉 Done no nascimento — e a única saída era mutação GraphQL
|
|
265
|
-
* crua: sem trava, sem confirmação e sem rastro.
|
|
266
|
-
* melhor que a mão livre.
|
|
196
|
+
* crua: sem trava, sem confirmação e sem rastro.
|
|
267
197
|
*
|
|
268
198
|
* Quem chama (`repair-stage`) é responsável pela confirmação e pelo registro na
|
|
269
199
|
* issue. Aqui só se escreve.
|
|
270
200
|
*
|
|
271
|
-
* @param {string} token token com scope project
|
|
272
|
-
* @param {object} project bloco project (precisa de .id)
|
|
273
|
-
* @param {{id,options}|null} etapaField campo "Etapa" (ver resolveField)
|
|
274
|
-
* @param {{id,options}|null} statusField campo nativo "Status"
|
|
275
|
-
* @param {string} nodeId node id da issue
|
|
276
|
-
* @param {string} targetStage etapa de destino (precisa existir em STAGE_ORDER)
|
|
277
|
-
* @param {string} [targetStatus] valor do Status; omitido = não mexe no Status
|
|
278
|
-
* @param {object} [opts] mesmo `{ typeField, itemType }` de advanceToStage
|
|
279
201
|
* @returns {Promise<{ from: string|null }>} etapa em que o item estava
|
|
280
202
|
*/
|
|
281
|
-
export async function
|
|
282
|
-
|
|
283
|
-
) {
|
|
284
|
-
|
|
285
|
-
if (STAGE_ORDER.indexOf(targetStage) === -1) {
|
|
286
|
-
throw new Error(`Etapa "${targetStage}" não faz parte do fluxo (${STAGE_ORDER.join(' → ')}).`);
|
|
287
|
-
}
|
|
288
|
-
const optionId = etapaField.options?.[targetStage];
|
|
289
|
-
if (!optionId) {
|
|
290
|
-
throw new Error(
|
|
291
|
-
`A opção "${targetStage}" não existe no campo Etapa deste Project. ` +
|
|
292
|
-
'Rode `spec-wave refresh --config` para sincronizar os ids.'
|
|
293
|
-
);
|
|
294
|
-
}
|
|
295
|
-
const itemId = await addProjectItem(token, project.id, nodeId);
|
|
296
|
-
await ensureWorkItemType(token, project, opts.typeField, itemId, opts.itemType);
|
|
297
|
-
const from = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
|
|
298
|
-
await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
|
|
299
|
-
if (statusField?.id && targetStatus) {
|
|
300
|
-
const statusOption = statusField.options?.[targetStatus];
|
|
301
|
-
if (statusOption) await setItemSingleSelect(token, project.id, itemId, statusField.id, statusOption);
|
|
203
|
+
export async function forceStage({ tracker, ref, stage, progress = null, itemType = null }) {
|
|
204
|
+
const { reason } = planStageMove({ current: null, target: stage });
|
|
205
|
+
if (reason === 'destino-invalido') {
|
|
206
|
+
throw new Error(`Etapa "${stage}" não faz parte do fluxo.`);
|
|
302
207
|
}
|
|
208
|
+
await ensureWorkItemType(tracker, ref, itemType);
|
|
209
|
+
const from = await tracker.getStage({ ref }).catch(() => null);
|
|
210
|
+
await tracker.setStage({ ref, stage, force: true });
|
|
211
|
+
if (progress) await tracker.setProgress({ ref, progress }).catch(() => false);
|
|
303
212
|
dropBoardCache();
|
|
304
213
|
return { from };
|
|
305
214
|
}
|
|
306
215
|
|
|
307
216
|
/**
|
|
308
|
-
* Define APENAS o
|
|
309
|
-
*
|
|
217
|
+
* Define APENAS o progresso (Todo/In Progress/Done), sem tocar na Etapa —
|
|
218
|
+
* usado para marcar trabalho em curso DENTRO da etapa atual.
|
|
310
219
|
*
|
|
311
|
-
* @
|
|
312
|
-
* @param {object} project bloco project (precisa de .id)
|
|
313
|
-
* @param {{id,options}|null} statusField campo nativo "Status"
|
|
314
|
-
* @param {string} nodeId node id da issue
|
|
315
|
-
* @param {string} status valor de destino (Todo/In Progress/Done)
|
|
316
|
-
* @returns {Promise<boolean>} true se definiu; false se campo/opção ausentes
|
|
220
|
+
* @returns {Promise<boolean>} true se definiu
|
|
317
221
|
*/
|
|
318
|
-
export async function
|
|
319
|
-
if (!
|
|
320
|
-
const
|
|
321
|
-
if (
|
|
322
|
-
|
|
323
|
-
await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
|
|
324
|
-
dropBoardCache();
|
|
325
|
-
return true;
|
|
222
|
+
export async function setProgress({ tracker, ref, progress }) {
|
|
223
|
+
if (!progress) return false;
|
|
224
|
+
const ok = await tracker.setProgress({ ref, progress }).catch(() => false);
|
|
225
|
+
if (ok) dropBoardCache();
|
|
226
|
+
return ok;
|
|
326
227
|
}
|
|
@@ -62,12 +62,19 @@ export function missingDocMessage({ pathRel, onRemote, fallback, pr = null, bran
|
|
|
62
62
|
/**
|
|
63
63
|
* O documento existe no remoto? Best-effort — NUNCA lança.
|
|
64
64
|
*
|
|
65
|
+
* A porta chega como PARÂMETRO, e não por import: esta função era, antes das
|
|
66
|
+
* portas, o melhor seam do repositório (recebia `getFileContent` como parâmetro
|
|
67
|
+
* nomeado), e a migração só a deixou menor. Sem porta o resultado é `null` —
|
|
68
|
+
* "não consegui olhar", que é diferente de "não existe" e é o que impede o
|
|
69
|
+
* chamador de regerar por cima.
|
|
70
|
+
*
|
|
71
|
+
* @param {{scm?: object, pathRel: string}} params
|
|
65
72
|
* @returns {Promise<boolean|null>} null quando não deu para consultar
|
|
66
73
|
*/
|
|
67
|
-
export async function existsOnRemote({
|
|
68
|
-
if (!
|
|
74
|
+
export async function existsOnRemote({ scm, pathRel }) {
|
|
75
|
+
if (!scm) return null;
|
|
69
76
|
try {
|
|
70
|
-
return (await
|
|
77
|
+
return (await scm.readFile({ path: pathRel })) != null;
|
|
71
78
|
} catch {
|
|
72
79
|
return null;
|
|
73
80
|
}
|