@spec-wave/cli 1.4.0 → 1.5.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/protocol/scm.v1.json +154 -0
- package/protocol/tracker.v1.json +175 -0
- package/src/api/github-rest.mjs +109 -0
- package/src/commands/audit.mjs +3 -5
- package/src/commands/code-review.mjs +10 -6
- package/src/commands/decompose.mjs +7 -6
- package/src/commands/doctor.mjs +389 -220
- package/src/commands/generate-bug.mjs +2 -2
- package/src/commands/generate-plan.mjs +5 -7
- package/src/commands/generate-qa-plan.mjs +3 -5
- package/src/commands/generate-spec.mjs +2 -2
- package/src/commands/implement.mjs +33 -21
- package/src/commands/init.mjs +36 -7
- package/src/commands/issue.mjs +6 -2
- package/src/commands/merge.mjs +20 -15
- package/src/commands/mode.mjs +18 -11
- package/src/commands/move.mjs +3 -3
- package/src/commands/order.mjs +3 -3
- package/src/commands/preflight.mjs +10 -6
- package/src/commands/qa-lead.mjs +6 -8
- package/src/commands/qa-run.mjs +39 -27
- package/src/commands/qa.mjs +10 -7
- package/src/commands/refresh.mjs +6 -3
- package/src/commands/repair-stage.mjs +1 -1
- package/src/commands/repo.mjs +6 -7
- package/src/commands/run.mjs +7 -5
- package/src/commands/story.mjs +3 -3
- package/src/commands/task.mjs +3 -3
- package/src/commands/triage.mjs +3 -3
- package/src/commands/uninstall.mjs +14 -6
- package/src/commands/update.mjs +47 -20
- package/src/commands/validate.mjs +3 -5
- package/src/commands/workspace.mjs +2 -2
- package/src/lib/artifact-publish.mjs +3 -3
- package/src/lib/board.mjs +22 -24
- package/src/lib/config-ports.mjs +114 -0
- package/src/lib/doc-source.mjs +16 -3
- package/src/lib/doctor-capabilities.mjs +168 -0
- package/src/lib/implement-board.mjs +1 -1
- package/src/lib/pr-ready.mjs +23 -11
- package/src/lib/story-graph.mjs +19 -6
- package/src/lib/tag-registry.mjs +58 -0
- package/src/lib/usage-report.mjs +15 -2
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugins/load.mjs +427 -0
- package/src/plugins/scm-github/index.mjs +71 -2
- package/src/plugins/tracker-github-projects/index.mjs +52 -10
- package/src/ports/capabilities.mjs +47 -0
- package/src/ports/index.mjs +201 -46
- package/src/ports/scm.mjs +39 -2
- package/src/ports/tracker.mjs +43 -2
- package/src/ports/types.mjs +30 -6
- package/src/setup/files.mjs +2 -3
- package/src/setup/labels.mjs +2 -2
- package/src/setup/project.mjs +2 -2
- package/src/ui/wizard.mjs +76 -1
|
@@ -32,6 +32,11 @@ import {
|
|
|
32
32
|
getRepoNodeId,
|
|
33
33
|
getRepoVariable,
|
|
34
34
|
deleteRepoVariable,
|
|
35
|
+
// Diagnóstico do `verify({deep})` — bloco G leva 2.
|
|
36
|
+
getRepoInfo,
|
|
37
|
+
getRequiredStatusChecks,
|
|
38
|
+
listActionsSecretNames,
|
|
39
|
+
getActionsCanCreatePullRequests,
|
|
35
40
|
isRepoInitialized,
|
|
36
41
|
listPullRequestCommitMessages,
|
|
37
42
|
listPullRequestReviews,
|
|
@@ -57,7 +62,7 @@ import { refKey, refNumber } from '../../lib/work-item-ref.mjs';
|
|
|
57
62
|
export const SCM_KIND = 'github';
|
|
58
63
|
|
|
59
64
|
/**
|
|
60
|
-
* O que o GitHub sabe fazer, na forma do `
|
|
65
|
+
* O que o GitHub sabe fazer, na forma do `protocol/scm.v1.json`.
|
|
61
66
|
*
|
|
62
67
|
* Congelado: o core LÊ isto para degradar, e uma capability que pudesse ser
|
|
63
68
|
* mutada em runtime seria um plugin ganhando poder depois da carga.
|
|
@@ -226,6 +231,8 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
|
|
|
226
231
|
listPullRequestReviews, mergePR, findOpenPR, setRepoVariable, updatePRBase, upsertFile,
|
|
227
232
|
getPRClosingIssues, getRateLimit, listIssuePullRequests, listOpenPullRequests,
|
|
228
233
|
markPullRequestReadyForReview,
|
|
234
|
+
getRepoInfo, getRequiredStatusChecks, listActionsSecretNames,
|
|
235
|
+
getActionsCanCreatePullRequests,
|
|
229
236
|
...api,
|
|
230
237
|
};
|
|
231
238
|
|
|
@@ -240,16 +247,69 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
|
|
|
240
247
|
return { warnings: [] };
|
|
241
248
|
},
|
|
242
249
|
|
|
243
|
-
async verify() {
|
|
250
|
+
async verify({ deep = false } = {}) {
|
|
244
251
|
const problems = [];
|
|
245
252
|
const facts = {};
|
|
246
253
|
// Sonda de alcance: é o que `commands/repo.mjs` já faz hoje, chamando
|
|
247
254
|
// getRepoNodeId e descartando o retorno. O que importa é o 404/403.
|
|
248
255
|
try {
|
|
249
256
|
facts.repoNodeId = await a.getRepoNodeId(token, owner, repo);
|
|
257
|
+
facts.repoReachable = true;
|
|
250
258
|
} catch (err) {
|
|
259
|
+
facts.repoNodeId = null;
|
|
260
|
+
// TRÊS estados, não dois. `false` é "esta credencial não enxerga este
|
|
261
|
+
// repositório" — resposta definitiva, e a causa típica do erro silencioso
|
|
262
|
+
// na criação de issue. `null` é "não consegui verificar agora" (rede,
|
|
263
|
+
// 500, cota). Fundi-los faria o doctor acusar VERMELHO num repositório
|
|
264
|
+
// correto sempre que a API estivesse fora do ar.
|
|
265
|
+
facts.repoReachable = err.status === 404 ? false : null;
|
|
251
266
|
problems.push(`repositório ${link.label} inacessível: ${err.message}`);
|
|
252
267
|
}
|
|
268
|
+
|
|
269
|
+
// ── Fatos de AUTOMAÇÃO, só sob `deep` ─────────────────────────────────
|
|
270
|
+
//
|
|
271
|
+
// Três chamadas a mais, e nenhum outro chamador de `verify()` as imprime:
|
|
272
|
+
// o `init` e o `repo` usam esta operação como sonda de alcance. Cobrá-las
|
|
273
|
+
// de todo mundo seria pagar diagnóstico que ninguém lê.
|
|
274
|
+
//
|
|
275
|
+
// O plugin COLETA e não julga: quem decide se dá para publicar documento
|
|
276
|
+
// por PR é `inspectPrPublishing`, no core. E `null` aqui significa
|
|
277
|
+
// "consultei e NÃO pude ver" — as três consultas falham por permissão
|
|
278
|
+
// insuficiente com frequência, e tratar isso como "está desligado" viraria
|
|
279
|
+
// vermelho em repositório correto.
|
|
280
|
+
if (deep) {
|
|
281
|
+
try {
|
|
282
|
+
const info = await a.getRepoInfo(token, owner, repo);
|
|
283
|
+
facts.repoFullName = info.fullName;
|
|
284
|
+
facts.repoPrivate = info.isPrivate;
|
|
285
|
+
facts.defaultBranch = info.defaultBranch;
|
|
286
|
+
try {
|
|
287
|
+
facts.protectedChecks = await a.getRequiredStatusChecks(
|
|
288
|
+
token, owner, repo, info.defaultBranch);
|
|
289
|
+
} catch {
|
|
290
|
+
facts.protectedChecks = null;
|
|
291
|
+
}
|
|
292
|
+
} catch {
|
|
293
|
+
facts.repoFullName = null;
|
|
294
|
+
facts.repoPrivate = null;
|
|
295
|
+
facts.defaultBranch = null;
|
|
296
|
+
// Sem saber a branch default não há proteção a consultar — e isso é
|
|
297
|
+
// "não consegui", não "não há".
|
|
298
|
+
facts.protectedChecks = null;
|
|
299
|
+
}
|
|
300
|
+
try {
|
|
301
|
+
facts.automationSecretNames = await a.listActionsSecretNames(token, owner, repo);
|
|
302
|
+
} catch {
|
|
303
|
+
facts.automationSecretNames = null; // sem permissão: não afirmar ausência
|
|
304
|
+
}
|
|
305
|
+
try {
|
|
306
|
+
facts.automationCanOpenPullRequest =
|
|
307
|
+
await a.getActionsCanCreatePullRequests(token, owner, repo);
|
|
308
|
+
} catch {
|
|
309
|
+
facts.automationCanOpenPullRequest = null; // exige administration:read
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
|
|
253
313
|
const quota = (await a.getRateLimit(token)) || {};
|
|
254
314
|
return {
|
|
255
315
|
ok: problems.length === 0,
|
|
@@ -437,3 +497,12 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
|
|
|
437
497
|
|
|
438
498
|
/** Reexportado para quem precisa converter chave → número na fronteira. */
|
|
439
499
|
export { refNumber };
|
|
500
|
+
|
|
501
|
+
// ── O que o LOADER lê (RFC-006 §9.2, Fase 2 bloco A) ────────────────────────
|
|
502
|
+
// Mesma razão do plugin de tracker: o embutido percorre o caminho do loader, e
|
|
503
|
+
// declarar aqui é o que faz a validação conferir o módulo REAL em vez de um
|
|
504
|
+
// objeto-módulo sintético montado pelo próprio loader.
|
|
505
|
+
export const specWaveScmApi = 1;
|
|
506
|
+
export const scmKind = SCM_KIND;
|
|
507
|
+
export const capabilities = GITHUB_SCM_CAPABILITIES;
|
|
508
|
+
export const createScm = createGithubScm;
|
|
@@ -21,7 +21,6 @@
|
|
|
21
21
|
// `addProjectItem` uma vez. Sem memo, o par chamaria duas — em dez call sites.
|
|
22
22
|
// O memo por instância REPÕE a contagem de hoje; ele não a reduz abaixo dela.
|
|
23
23
|
|
|
24
|
-
import { Octokit } from '@octokit/rest';
|
|
25
24
|
|
|
26
25
|
import {
|
|
27
26
|
addBlockedBy,
|
|
@@ -35,6 +34,9 @@ import {
|
|
|
35
34
|
getIssue,
|
|
36
35
|
getMilestone,
|
|
37
36
|
getOwnerType,
|
|
37
|
+
listIssuesByLabel,
|
|
38
|
+
// Diagnóstico do `verify({deep})` — bloco G leva 2.
|
|
39
|
+
getOrgMembershipState,
|
|
38
40
|
listBlockedBy,
|
|
39
41
|
listIssueComments,
|
|
40
42
|
listIssuesByMilestone,
|
|
@@ -184,7 +186,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
184
186
|
addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
|
|
185
187
|
getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
|
|
186
188
|
linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
|
|
187
|
-
resolveField,
|
|
189
|
+
resolveField, getOrgMembershipState, listIssuesByLabel,
|
|
188
190
|
...api,
|
|
189
191
|
};
|
|
190
192
|
|
|
@@ -298,7 +300,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
298
300
|
return { config, warnings: [] };
|
|
299
301
|
},
|
|
300
302
|
|
|
301
|
-
async verify() {
|
|
303
|
+
async verify({ deep = false } = {}) {
|
|
302
304
|
const problems = [];
|
|
303
305
|
const facts = {};
|
|
304
306
|
try {
|
|
@@ -309,20 +311,38 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
309
311
|
problems.push(`o owner "${owner}" é uma conta pessoal; Projects v2 do spec-wave exige organização`);
|
|
310
312
|
}
|
|
311
313
|
} catch (err) {
|
|
314
|
+
// `null`, e não a ausência da chave: a diferença entre "este tracker não
|
|
315
|
+
// tem noção de owner" e "tem, e eu não consegui ler" é o que manda o
|
|
316
|
+
// usuário ao lugar certo (ver VerifyResult).
|
|
317
|
+
facts.ownerType = null;
|
|
312
318
|
problems.push(err.message);
|
|
313
319
|
}
|
|
314
320
|
if (project?.id) {
|
|
315
321
|
try {
|
|
316
322
|
const snap = await a.getProjectSnapshot(ptk, project.id);
|
|
323
|
+
facts.boardFound = !!snap;
|
|
317
324
|
if (!snap) problems.push('Project não encontrado com a credencial atual');
|
|
318
325
|
else {
|
|
319
|
-
facts.
|
|
320
|
-
facts.
|
|
326
|
+
facts.boardTitle = snap.title;
|
|
327
|
+
facts.boardKey = String(snap.number);
|
|
328
|
+
// Nome → id das etapas REAIS. O `doctor` compara com o config por
|
|
329
|
+
// NOME (coluna renomeada/apagada) e por ID (config defasado, que faz
|
|
330
|
+
// toda escrita de Etapa falhar em silêncio) — duas leituras do mesmo
|
|
331
|
+
// fato, e nenhuma delas é julgamento do plugin.
|
|
332
|
+
facts.stageOptions = snap.fields?.[ETAPA_FIELD.name]?.options ?? null;
|
|
321
333
|
}
|
|
322
334
|
} catch (err) {
|
|
335
|
+
facts.boardFound = null;
|
|
323
336
|
problems.push(err.message);
|
|
324
337
|
}
|
|
325
338
|
}
|
|
339
|
+
if (deep) {
|
|
340
|
+
// O usuário do token é membro ativo da organização dona do board? É o
|
|
341
|
+
// que separa "a conta ativa do `gh` não é o owner, e isso é normal numa
|
|
342
|
+
// org" de "esta credencial não pertence a esta organização". `null` =
|
|
343
|
+
// não dá para saber (conta pessoal, ou sem permissão de consultar).
|
|
344
|
+
facts.ownerMembership = await a.getOrgMembershipState(token, owner);
|
|
345
|
+
}
|
|
326
346
|
const quota = (await a.getRateLimit(ptk)) || {};
|
|
327
347
|
return {
|
|
328
348
|
ok: problems.length === 0,
|
|
@@ -383,14 +403,16 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
383
403
|
return { fields: snap?.fields || {} };
|
|
384
404
|
},
|
|
385
405
|
|
|
406
|
+
// Passa pelo `a`, e isso não é estilo: um `new Octokit` INLINE não tem
|
|
407
|
+
// costura, então o duplo do teste não o intercepta e a chamada vai à rede de
|
|
408
|
+
// verdade no meio da suíte. Era inofensivo enquanto ninguém chamava (o
|
|
409
|
+
// cabeçalho deste arquivo dizia isso); o `doctor` passou a chamar na leva 2
|
|
410
|
+
// do bloco G, e foi o bloqueio de rede do teste de fumaça que acusou.
|
|
386
411
|
async listWorkItemsByTag({ tag, state = 'open' } = {}) {
|
|
387
|
-
const
|
|
388
|
-
const issues = await octokit.paginate('GET /repos/{owner}/{repo}/issues', {
|
|
389
|
-
owner, repo, labels: tag, state, per_page: 100,
|
|
390
|
-
});
|
|
412
|
+
const issues = await a.listIssuesByLabel(token, owner, repo, { labels: tag, state });
|
|
391
413
|
// A REST devolve Pull Request junto — eles são issues para a API, e não
|
|
392
414
|
// para o fluxo.
|
|
393
|
-
return issues.filter(i => !i.pull_request).map(toWorkItem);
|
|
415
|
+
return (issues || []).filter(i => !i.pull_request).map(toWorkItem);
|
|
394
416
|
},
|
|
395
417
|
|
|
396
418
|
async addComment({ ref, body } = {}) {
|
|
@@ -679,3 +701,23 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
679
701
|
}
|
|
680
702
|
|
|
681
703
|
export { FIELD_LABEL };
|
|
704
|
+
|
|
705
|
+
// ── O que o LOADER lê (RFC-006 §9.2, Fase 2 bloco A) ────────────────────────
|
|
706
|
+
//
|
|
707
|
+
// O plugin embutido declara exatamente o que um plugin de terceiro declara, e
|
|
708
|
+
// `src/plugins/load.mjs` o carrega pelo MESMO caminho — inclusive passando por
|
|
709
|
+
// `checkPluginModule` e `checkTrackerPort`.
|
|
710
|
+
//
|
|
711
|
+
// Os nomes são canônicos e não os locais (`TRACKER_KIND`, `createGithubTracker`)
|
|
712
|
+
// porque é o loader que os lê, e ele não pode saber o nome interno de cada
|
|
713
|
+
// fornecedor. Os locais ficam: 37 arquivos e a suíte os usam, e renomeá-los é o
|
|
714
|
+
// bloco E.
|
|
715
|
+
//
|
|
716
|
+
// Isto não é enfeite. A alternativa era o loader montar um objeto-módulo
|
|
717
|
+
// sintético para o embutido — um falso que passa por construção, que é o mesmo
|
|
718
|
+
// defeito da porta falsa escrita à mão: valida o que quem o escreveu imaginou.
|
|
719
|
+
// Declarando aqui, quem reprova é o módulo REAL.
|
|
720
|
+
export const specWaveTrackerApi = 1;
|
|
721
|
+
export const trackerKind = TRACKER_KIND;
|
|
722
|
+
export const capabilities = GITHUB_TRACKER_CAPABILITIES;
|
|
723
|
+
export const createTracker = createGithubTracker;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
// A regra de vocabulário das `capabilities`, compartilhada pelas duas portas.
|
|
2
|
+
//
|
|
3
|
+
// Mora em módulo próprio e não em `types.mjs` porque aquele é declaradamente sem
|
|
4
|
+
// runtime, e não em `tracker.mjs` porque `scm.mjs` também a usa — uma porta
|
|
5
|
+
// importando a outra seria acoplamento sem razão.
|
|
6
|
+
//
|
|
7
|
+
// ── Por que a regra existe ───────────────────────────────────────────────────
|
|
8
|
+
//
|
|
9
|
+
// Uma chave de capability DESCONHECIDA é silenciosa e cara. `trackerRequiredOperations`
|
|
10
|
+
// lê `capabilities.commentMarkers`; quem escrever `markers` cai no ramo default
|
|
11
|
+
// sem nenhum sinal, e a validação da carga passa a cobrar o conjunto ERRADO de
|
|
12
|
+
// operações — o plugin carrega "conforme" e falta uma operação que ninguém
|
|
13
|
+
// pediu. No SCM é mais afiado ainda: `pullRequests.draft` é o que exige
|
|
14
|
+
// `markReadyForReview`, e um `pullRequest` no singular carregaria conforme e não
|
|
15
|
+
// saberia tirar PR de rascunho.
|
|
16
|
+
//
|
|
17
|
+
// Aconteceu comigo escrevendo o teste do loader: quatro chaves inventadas
|
|
18
|
+
// (`markers`, `board`, `comments`, `tags`) mudaram a lista de operações exigidas
|
|
19
|
+
// de 35 para 37, e o que me avisou foi a lista de operações faltando — não a
|
|
20
|
+
// causa. Isto é o que transforma o sintoma em causa.
|
|
21
|
+
//
|
|
22
|
+
// `protocol/{tracker,scm}.v1.json` têm `additionalProperties: true`, que é o
|
|
23
|
+
// que deixa o erro passar do lado do manifesto. Aqui a lista é fechada, e
|
|
24
|
+
// `test/protocol-schemas.test.mjs` afirma que ela não divergiu do schema: uma
|
|
25
|
+
// fonte em runtime, com guarda contra deriva.
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Chave de capability fora do vocabulário (função PURA).
|
|
29
|
+
*
|
|
30
|
+
* Exportada, e não embutida em `checkTrackerPort`, pela mesma razão de
|
|
31
|
+
* `checkKeyPattern`: o kit de conformidade da §9.4 tem de cobrar a MESMA regra,
|
|
32
|
+
* e duas cópias divergem.
|
|
33
|
+
*
|
|
34
|
+
* @param {object} capabilities
|
|
35
|
+
* @param {readonly string[]} conhecidas
|
|
36
|
+
* @returns {string[]} problemas; vazio = vocabulário limpo
|
|
37
|
+
*/
|
|
38
|
+
export function checkCapabilityKeys(capabilities, conhecidas) {
|
|
39
|
+
if (!capabilities || typeof capabilities !== 'object') return ['`capabilities` ausente'];
|
|
40
|
+
const desconhecidas = Object.keys(capabilities).filter(k => !conhecidas.includes(k));
|
|
41
|
+
if (desconhecidas.length === 0) return [];
|
|
42
|
+
return [
|
|
43
|
+
`capability desconhecida: ${desconhecidas.map(k => `\`${k}\``).join(', ')}. `
|
|
44
|
+
+ 'Uma chave que o contrato não lê é IGNORADA em silêncio, e a operação que ela '
|
|
45
|
+
+ `deveria exigir deixa de ser cobrada. O vocabulário é: ${conhecidas.join(', ')}`,
|
|
46
|
+
];
|
|
47
|
+
}
|
package/src/ports/index.mjs
CHANGED
|
@@ -31,13 +31,16 @@
|
|
|
31
31
|
// qualquer resolução. Sem isso, cada comando migrado precisaria de um seam
|
|
32
32
|
// próprio de novo.
|
|
33
33
|
//
|
|
34
|
-
// ──
|
|
34
|
+
// ── A resolução mora no loader (bloco A) ────────────────────────────────────
|
|
35
35
|
//
|
|
36
|
-
//
|
|
37
|
-
//
|
|
38
|
-
//
|
|
39
|
-
//
|
|
40
|
-
//
|
|
36
|
+
// Até o bloco 0 este arquivo importava as duas fábricas do GitHub direto. Agora
|
|
37
|
+
// ele não conhece fornecedor nenhum: `src/plugins/load.mjs` faz a resolução da
|
|
38
|
+
// §9.2, valida `specWaveTrackerApi === 1` e as `capabilities` × `operations` na
|
|
39
|
+
// CARGA, e devolve a porta já conferida por `checkTrackerPort`/`checkScmPort`.
|
|
40
|
+
//
|
|
41
|
+
// ⚠️ E isso só vale para quem passar por AQUI. Hoje ninguém passa: estas duas
|
|
42
|
+
// funções não têm chamador em produção, e é o bloco E que traz os ~35 call sites.
|
|
43
|
+
// A validação existe e está testada; ela ainda não protege um comando real.
|
|
41
44
|
//
|
|
42
45
|
// `getScm` toma um `ScmLink` já pronto de propósito: `ScmLink` é tipo do
|
|
43
46
|
// CONTRATO e qualquer plugin sabe produzir um, então a assinatura sobrevive ao
|
|
@@ -45,10 +48,35 @@
|
|
|
45
48
|
// core importavam `githubLink` do plugin —, e o bloco E0 o fechou com
|
|
46
49
|
// `resolveScmLink` (no fim deste arquivo) mais a extensão da barreira.
|
|
47
50
|
|
|
48
|
-
import {
|
|
49
|
-
|
|
51
|
+
import {
|
|
52
|
+
buildPort, listPluginKinds, DEFAULT_TRACKER_KIND, DEFAULT_SCM_KIND,
|
|
53
|
+
} from '../plugins/load.mjs';
|
|
54
|
+
|
|
55
|
+
// Reexportados: o core precisa nomear o fornecedor embutido em DOIS lugares — o
|
|
56
|
+
// `init`, que pergunta antes de haver config, e o default de leitura do bloco D —
|
|
57
|
+
// e a barreira só autoriza este arquivo a falar com `src/plugins/`. Sem isto, um
|
|
58
|
+
// comando importaria o loader direto para pegar a constante.
|
|
59
|
+
export { DEFAULT_TRACKER_KIND, DEFAULT_SCM_KIND };
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Os fornecedores DISPONÍVEIS para uma porta — RFC-006 §9.3, bloco F.
|
|
63
|
+
*
|
|
64
|
+
* Reexportada por aqui e não importada do loader, e o portão da barreira pegou
|
|
65
|
+
* isso na hora: o wizard é CORE, e descobrir de onde vem um plugin é do
|
|
66
|
+
* `ports/index.mjs`. Deixar o wizard importar `src/plugins/load.mjs` teria
|
|
67
|
+
* reaberto a porta que o bloco E acabou de fechar — por uma constante.
|
|
68
|
+
*/
|
|
69
|
+
export { listPluginKinds };
|
|
70
|
+
import { githubLink, SCM_KIND } from '../plugins/scm-github/index.mjs';
|
|
50
71
|
import { CONFIG_FILE } from '../config.mjs';
|
|
51
72
|
import { loadConfig } from '../lib/project-root.mjs';
|
|
73
|
+
// Bloco D: normalização do bloco `tracker` na LEITURA (§3.4). O default de
|
|
74
|
+
// `kind` vem do loader, não daqui — o core não nomeia fornecedor.
|
|
75
|
+
//
|
|
76
|
+
// `deriveScmBlock` existe no mesmo módulo e NÃO é importada aqui: `getScm` toma
|
|
77
|
+
// um `link` e não sabe de qual repositório é o `cwd` (ver a nota dentro dela). O
|
|
78
|
+
// consumidor dela é o bloco F (`init` gravando o bloco) e os call sites de E.
|
|
79
|
+
import { deriveTrackerBlock } from '../lib/config-ports.mjs';
|
|
52
80
|
|
|
53
81
|
/** @typedef {import('./tracker.mjs').TrackerPort} TrackerPort */
|
|
54
82
|
/** @typedef {import('./scm.mjs').ScmPort} ScmPort */
|
|
@@ -69,11 +97,19 @@ import { loadConfig } from '../lib/project-root.mjs';
|
|
|
69
97
|
* @param {string} [params.projectToken] credencial de board; ausente = `token`
|
|
70
98
|
* @param {string} [params.owner] vence o que estiver no config
|
|
71
99
|
* @param {string} [params.repo] idem
|
|
100
|
+
* @param {boolean} [params.board=false] exigir o bloco `project`? Só quem vai
|
|
101
|
+
* MEXER no board passa `true` — ver a nota no corpo. Um repo de papel `code`
|
|
102
|
+
* não tem o bloco e ainda assim usa a porta para issue.
|
|
103
|
+
* @param {string} [params.kind] fornecedor EXPLÍCITO, dispensando o config. Só o
|
|
104
|
+
* `init` usa hoje, porque é o único comando que roda antes de o
|
|
105
|
+
* `.spec-wave.json` existir — ver a nota no corpo.
|
|
106
|
+
* @param {string} [params.pkg] pacote explícito, junto com `kind`
|
|
72
107
|
* @param {object} [params.deps] `deps.tracker` injeta uma porta já construída
|
|
73
108
|
* @returns {Promise<{tracker: TrackerPort|null, root: string|null, error: string|null}>}
|
|
74
109
|
*/
|
|
75
110
|
export async function getTracker({
|
|
76
|
-
cwd = process.cwd(), token, projectToken, owner, repo,
|
|
111
|
+
cwd = process.cwd(), token, projectToken, owner, repo, board = false,
|
|
112
|
+
kind: kindExplicito, pkg: pkgExplicito, deps = {},
|
|
77
113
|
} = {}) {
|
|
78
114
|
const { config, root, error: configError } = loadConfig(cwd);
|
|
79
115
|
|
|
@@ -82,10 +118,57 @@ export async function getTracker({
|
|
|
82
118
|
// chamadores o usam para achar os documentos.
|
|
83
119
|
if (deps.tracker) return { tracker: deps.tracker, root, error: null };
|
|
84
120
|
|
|
121
|
+
// ── `kind` EXPLÍCITO dispensa o config, e o `init` é por que isso existe ────
|
|
122
|
+
//
|
|
123
|
+
// `init` roda ANTES de haver `.spec-wave.json` — ele o grava no fim. Exigir o
|
|
124
|
+
// config ali tornaria o único comando que ainda constrói porta à mão o único que
|
|
125
|
+
// não pode deixar de construir. A leva 5 do bloco E descobriu isso ao tentar
|
|
126
|
+
// migrá-lo: o plano falava de "colisão com o bloco F no mesmo arquivo", e o
|
|
127
|
+
// motivo real é mais afiado — não há config a ler.
|
|
128
|
+
//
|
|
129
|
+
// É também a API de que o bloco F precisa: as duas perguntas do `init`
|
|
130
|
+
// (§9.3) escolhem o fornecedor ANTES de gravar qualquer coisa, e é este
|
|
131
|
+
// parâmetro que carrega a escolha até o loader.
|
|
132
|
+
if (kindExplicito) {
|
|
133
|
+
const { porta, error } = await buildPort({
|
|
134
|
+
port: 'tracker',
|
|
135
|
+
kind: kindExplicito,
|
|
136
|
+
pkg: pkgExplicito,
|
|
137
|
+
root: root || cwd,
|
|
138
|
+
params: { token, projectToken, owner, repo },
|
|
139
|
+
});
|
|
140
|
+
return { tracker: porta, root, error };
|
|
141
|
+
}
|
|
142
|
+
|
|
85
143
|
if (configError) return { tracker: null, root, error: configError };
|
|
86
144
|
|
|
87
|
-
|
|
88
|
-
|
|
145
|
+
// Bloco D: o bloco `tracker` é NORMALIZADO na leitura, ANTES de qualquer
|
|
146
|
+
// guarda. Um config da era 0.16.4 não o tem, e é lido como se tivesse — `kind`
|
|
147
|
+
// do fornecedor embutido, `config` vinda do bloco `project`. Nada é gravado
|
|
148
|
+
// (§3.4).
|
|
149
|
+
//
|
|
150
|
+
// A normalização vem antes do guard de propósito: guardar contra
|
|
151
|
+
// `config.project` e entregar `bloco.config` à fábrica seria meia-migração — um
|
|
152
|
+
// `tracker.config` escrito à mão, com o id lá dentro, seria recusado por falta
|
|
153
|
+
// de um bloco `project` que ele veio justamente substituir.
|
|
154
|
+
const bloco = deriveTrackerBlock(config, { defaultKind: DEFAULT_TRACKER_KIND });
|
|
155
|
+
|
|
156
|
+
// ── `board` é OPT-IN, e o bloco E é que mostrou por quê ────────────────────
|
|
157
|
+
//
|
|
158
|
+
// O bloco 0 congelou esta função exigindo `project.id` sempre. Errado, e o
|
|
159
|
+
// sintoma só apareceu ao migrar os call sites: os comandos constroem DUAS
|
|
160
|
+
// portas de tracker — uma para trabalho de ISSUE (`createGithubTracker({token,
|
|
161
|
+
// owner, repo})`, sem `project`, porque o plugin resolve o board de forma
|
|
162
|
+
// preguiçosa) e uma para o BOARD (via `openTracker`, que exige o bloco).
|
|
163
|
+
//
|
|
164
|
+
// Exigir `project.id` na porta de issue quebraria todo repositório de papel
|
|
165
|
+
// `code` (RFC-005): ele não tem bloco `project` — o board é do hub — e ainda
|
|
166
|
+
// assim comenta, etiqueta e lê issue do hub. `preflight`, `workspace`,
|
|
167
|
+
// `code-review` e `qa` rodam lá.
|
|
168
|
+
//
|
|
169
|
+
// Quem exige o board é quem precisa dele, e diz isso: `board: true`. É o que
|
|
170
|
+
// `openTracker` passa.
|
|
171
|
+
if (board && !bloco.config?.id) {
|
|
89
172
|
return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
|
|
90
173
|
}
|
|
91
174
|
|
|
@@ -99,25 +182,32 @@ export async function getTracker({
|
|
|
99
182
|
};
|
|
100
183
|
}
|
|
101
184
|
|
|
102
|
-
//
|
|
103
|
-
//
|
|
185
|
+
// O argumento-objeto vai inteiro para a fábrica, e cada plugin lê as chaves
|
|
186
|
+
// que conhece: o embutido lê `project`; um plugin de Jira leria `config`,
|
|
187
|
+
// `fieldMap` e `stageMap`. É para isso que a aridade está presa em 1.
|
|
104
188
|
//
|
|
105
|
-
//
|
|
106
|
-
//
|
|
107
|
-
//
|
|
108
|
-
//
|
|
109
|
-
|
|
110
|
-
|
|
189
|
+
// `project` sai de `bloco.config` e NÃO de `config.project`: depois da
|
|
190
|
+
// normalização existe uma fonte só, e um `tracker.config` escrito à mão vence
|
|
191
|
+
// o bloco legado em vez de conviver com ele. Duas fontes com o mesmo conteúdo
|
|
192
|
+
// divergem no dia em que uma das duas é editada.
|
|
193
|
+
const { porta, error } = await buildPort({
|
|
194
|
+
port: 'tracker',
|
|
195
|
+
kind: bloco.kind,
|
|
196
|
+
pkg: bloco.package,
|
|
197
|
+
root: root || cwd,
|
|
198
|
+
params: {
|
|
111
199
|
token,
|
|
112
200
|
projectToken,
|
|
113
201
|
owner: donoResolvido,
|
|
114
202
|
repo: repoResolvido,
|
|
115
|
-
project,
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
203
|
+
project: bloco.config,
|
|
204
|
+
config: bloco.config,
|
|
205
|
+
stageMap: bloco.stageMap,
|
|
206
|
+
fieldMap: bloco.fieldMap,
|
|
207
|
+
typeMap: bloco.typeMap,
|
|
208
|
+
},
|
|
209
|
+
});
|
|
210
|
+
return { tracker: porta, root, error };
|
|
121
211
|
}
|
|
122
212
|
|
|
123
213
|
/**
|
|
@@ -142,28 +232,81 @@ export async function getTracker({
|
|
|
142
232
|
* @param {object} [params.deps] `deps.scm` injeta uma porta já construída
|
|
143
233
|
* @returns {Promise<{scm: ScmPort|null, error: string|null}>}
|
|
144
234
|
*/
|
|
145
|
-
export async function getScm({
|
|
235
|
+
export async function getScm({
|
|
236
|
+
link, token, prToken, trackerKind, cwd = process.cwd(), pkg, deps = {},
|
|
237
|
+
} = {}) {
|
|
146
238
|
if (deps.scm) return { scm: deps.scm, error: null };
|
|
147
239
|
if (!link?.kind) return { scm: null, error: 'getScm: `link` sem `kind`' };
|
|
148
240
|
|
|
149
|
-
//
|
|
150
|
-
//
|
|
151
|
-
//
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
241
|
+
// ⚠️ `getScm` NÃO lê o config, e isso é decisão do bloco D e não omissão.
|
|
242
|
+
//
|
|
243
|
+
// Eu tinha escrito a leitura aqui — `scm.package` e `trackerKind` saindo do
|
|
244
|
+
// `.spec-wave.json` quando o chamador não os passa — e ela estava errada por
|
|
245
|
+
// dois motivos que só apareceram ao conferir o teste:
|
|
246
|
+
//
|
|
247
|
+
// 1. **`cwd` é ambíguo em multi-repo.** Uma instância de SCM é UM repositório,
|
|
248
|
+
// e `merge`/`code-review`/`qa` constroem portas para o hub E para repos de
|
|
249
|
+
// código com o mesmo `cwd` — o do hub. Ler `scm.package` dali e aplicá-lo
|
|
250
|
+
// ao repo de código é supor que há um plugin só para todos, o que a
|
|
251
|
+
// RFC-005 §12 vai reexpressar como LISTA. Adivinhar agora congela a forma
|
|
252
|
+
// errada;
|
|
253
|
+
// 2. **o teste passou lendo o config deste repositório.** `getScm({link})` sem
|
|
254
|
+
// `cwd` cai em `process.cwd()`, e a suíte roda na raiz, que tem
|
|
255
|
+
// `.spec-wave.json`. Verde por dependência escondida em estado real.
|
|
256
|
+
//
|
|
257
|
+
// `pkg` e `trackerKind` continuam vindo do CHAMADOR. Quem tem o config na mão é
|
|
258
|
+
// o comando, e é ele que sabe qual repositório está endereçando.
|
|
259
|
+
const { porta, error } = await buildPort({
|
|
260
|
+
port: 'scm',
|
|
261
|
+
kind: link.kind,
|
|
262
|
+
pkg,
|
|
263
|
+
root: cwd,
|
|
264
|
+
params: { link, token, prToken, trackerKind: trackerKind || DEFAULT_TRACKER_KIND },
|
|
265
|
+
});
|
|
266
|
+
return { scm: porta, error };
|
|
267
|
+
}
|
|
155
268
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
269
|
+
/**
|
|
270
|
+
* A porta de tracker, ou LANÇA — Fase 2 bloco E, leva 2.
|
|
271
|
+
*
|
|
272
|
+
* Os ~27 call sites do padrão A (`deps.tracker ?? create…`) não tinham caminho de
|
|
273
|
+
* erro, porque construir a porta era montar um objeto local e não podia falhar.
|
|
274
|
+
* Com o loader, pode: plugin ausente, quebrado, ou de versão de contrato errada.
|
|
275
|
+
*
|
|
276
|
+
* **Lançar é o tratamento uniforme, e é uniforme por uma razão, não por
|
|
277
|
+
* conveniência:** nesses sites o erro só pode vir do LOADER. O `deps` faz
|
|
278
|
+
* curto-circuito antes de qualquer leitura, `board` é false (então nada exige o
|
|
279
|
+
* bloco `project`) e `owner`/`repo` chegam do chamador, que já validou estar num
|
|
280
|
+
* repositório. Sobra "o plugin não carregou" — que não é condição de fluxo, é a
|
|
281
|
+
* CLI inutilizável, e a resposta certa é a mesma em todos.
|
|
282
|
+
*
|
|
283
|
+
* E lançar chega bem ao usuário: `src/cli.mjs` envolve cada comando em
|
|
284
|
+
* `.catch(err => { console.error(err.message); process.exit(1); })`, então sai a
|
|
285
|
+
* mensagem do loader — que nomeia o plugin e lista o que foi tentado — sem stack
|
|
286
|
+
* trace. Dar a cada site um `if (error)` próprio seria 27 decisões para uma
|
|
287
|
+
* falha só, e é assim que uma delas sai errada.
|
|
288
|
+
*
|
|
289
|
+
* @param {object} params o mesmo de `getTracker`
|
|
290
|
+
* @returns {Promise<object>} a porta
|
|
291
|
+
* @throws {Error} com a mensagem do loader
|
|
292
|
+
*/
|
|
293
|
+
export async function requireTracker(params = {}) {
|
|
294
|
+
const { tracker, error } = await getTracker(params);
|
|
295
|
+
if (error) throw new Error(error);
|
|
296
|
+
return tracker;
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* A porta de SCM, ou LANÇA. Mesma razão de `requireTracker`.
|
|
301
|
+
*
|
|
302
|
+
* @param {object} params o mesmo de `getScm`
|
|
303
|
+
* @returns {Promise<object>} a porta
|
|
304
|
+
* @throws {Error}
|
|
305
|
+
*/
|
|
306
|
+
export async function requireScm(params = {}) {
|
|
307
|
+
const { scm, error } = await getScm(params);
|
|
308
|
+
if (error) throw new Error(error);
|
|
309
|
+
return scm;
|
|
167
310
|
}
|
|
168
311
|
|
|
169
312
|
/**
|
|
@@ -175,9 +318,21 @@ export async function getScm({ link, token, prToken, trackerKind, deps = {} } =
|
|
|
175
318
|
* e este entrava por outra porta. O bloco E0 migrou os 21 para cá e estendeu a
|
|
176
319
|
* barreira, que hoje tem um guard só para `githubLink` no core.
|
|
177
320
|
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
321
|
+
* **Continua SÍNCRONA e com import estático do embutido, e o bloco A não mudou
|
|
322
|
+
* isso.** Duas razões, e a segunda é a que decide:
|
|
323
|
+
*
|
|
324
|
+
* 1. os 21 call sites que o E0 migrou são síncronos. Torná-la assíncrona os
|
|
325
|
+
* tocaria uma segunda vez, que é exatamente o que o bloco 0 existe para
|
|
326
|
+
* evitar — e sem ganho nenhum hoje;
|
|
327
|
+
* 2. a assinatura **já é** específica de fornecedor: ela toma `owner`/`repo`,
|
|
328
|
+
* que é o endereço de um repositório do GitHub. Um Azure DevOps precisa de
|
|
329
|
+
* `org/project/repo`. Rotear isto pelo loader não a generalizaria — só
|
|
330
|
+
* esconderia a especificidade atrás de um `await`. Generalizar é trabalho
|
|
331
|
+
* próprio: quem chama precisa deixar de saber o FORMATO do endereço, e isso
|
|
332
|
+
* é o bloco F (`init` grava o `config` do SCM) mais os call sites de E.
|
|
333
|
+
*
|
|
334
|
+
* O `throw` para `kind` desconhecido fica: é a única coisa aqui que diz a
|
|
335
|
+
* verdade sobre o alcance da função.
|
|
181
336
|
*
|
|
182
337
|
* @param {object} params
|
|
183
338
|
* @param {string} params.owner
|