@spec-wave/cli 1.3.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 -4
- package/src/commands/code-review.mjs +11 -6
- package/src/commands/decompose.mjs +29 -9
- package/src/commands/doctor.mjs +389 -220
- package/src/commands/generate-bug.mjs +17 -7
- package/src/commands/generate-plan.mjs +21 -13
- package/src/commands/generate-qa-plan.mjs +19 -11
- package/src/commands/generate-spec.mjs +19 -6
- package/src/commands/implement.mjs +105 -49
- package/src/commands/init.mjs +36 -6
- package/src/commands/issue.mjs +6 -2
- package/src/commands/merge.mjs +31 -18
- package/src/commands/mode.mjs +18 -10
- package/src/commands/move.mjs +3 -3
- package/src/commands/order.mjs +30 -20
- package/src/commands/preflight.mjs +10 -5
- package/src/commands/qa-lead.mjs +41 -31
- package/src/commands/qa-run.mjs +83 -55
- package/src/commands/qa.mjs +10 -6
- package/src/commands/refresh.mjs +6 -3
- package/src/commands/repair-stage.mjs +1 -1
- package/src/commands/repo.mjs +7 -7
- package/src/commands/run.mjs +7 -4
- 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 -5
- package/src/commands/update.mjs +47 -19
- package/src/commands/validate.mjs +3 -4
- package/src/commands/workspace.mjs +2 -2
- package/src/lib/artifact-publish.mjs +4 -3
- package/src/lib/board.mjs +22 -24
- package/src/lib/config-ports.mjs +114 -0
- package/src/lib/critique.mjs +11 -1
- package/src/lib/doc-source.mjs +16 -2
- package/src/lib/doctor-capabilities.mjs +168 -0
- package/src/lib/implement-board.mjs +6 -1
- package/src/lib/implement-stream.mjs +87 -0
- package/src/lib/pr-ready.mjs +24 -11
- package/src/lib/story-graph.mjs +26 -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 +347 -0
- package/src/ports/scm.mjs +39 -2
- package/src/ports/tracker.mjs +94 -3
- package/src/ports/types.mjs +59 -6
- package/src/setup/files.mjs +2 -2
- package/src/setup/labels.mjs +2 -2
- package/src/setup/project.mjs +2 -2
- package/src/ui/wizard.mjs +76 -1
|
@@ -0,0 +1,427 @@
|
|
|
1
|
+
// O loader de plugins — RFC-006 §9.2, Fase 2 bloco A.
|
|
2
|
+
//
|
|
3
|
+
// Este é o único arquivo que sabe DE ONDE um plugin vem. Mora em
|
|
4
|
+
// `src/plugins/` de propósito: `test/ports-boundary.test.mjs` isenta esse
|
|
5
|
+
// diretório das duas regras de barreira, e é aqui que o nome de um fornecedor
|
|
6
|
+
// pode aparecer sem ser acoplamento.
|
|
7
|
+
//
|
|
8
|
+
// ── O plugin embutido percorre o MESMO caminho ───────────────────────────────
|
|
9
|
+
//
|
|
10
|
+
// `github-projects` e `github` entram por uma tabela de embutidos e daí seguem
|
|
11
|
+
// pela mesma validação de um plugin de terceiro. Curto-circuitá-los faria todo
|
|
12
|
+
// este arquivo ser código morto até o primeiro plugin publicado — a classe de
|
|
13
|
+
// coisa que quebra em silêncio, e que os 1424 testes de hoje não exercitariam.
|
|
14
|
+
// Com a tabela, a suíte inteira passa por aqui.
|
|
15
|
+
//
|
|
16
|
+
// ── "não instalado" × "instalado e QUEBRADO" ─────────────────────────────────
|
|
17
|
+
//
|
|
18
|
+
// Os dois dão `ERR_MODULE_NOT_FOUND`, e só a MENSAGEM diz qual pacote faltou
|
|
19
|
+
// (medido, não suposto: um plugin que importa um pacote ausente reporta o pacote
|
|
20
|
+
// DELE). Ler o código do erro e seguir para o próximo candidato mandaria o
|
|
21
|
+
// usuário instalar algo que ele já tem.
|
|
22
|
+
//
|
|
23
|
+
// A separação é feita sem parsear mensagem: RESOLVER é uma etapa, CARREGAR é
|
|
24
|
+
// outra. Resolver falhou = não instalado, próximo candidato. Resolveu e carregar
|
|
25
|
+
// falhou = existe e está quebrado, PARA e reporta.
|
|
26
|
+
//
|
|
27
|
+
// ── E a resolução parte da RAIZ DO PROJETO ───────────────────────────────────
|
|
28
|
+
//
|
|
29
|
+
// `import.meta.resolve` resolve relativo a ESTE módulo. Rodando por `npx`, este
|
|
30
|
+
// módulo está num diretório temporário e o plugin que o usuário instalou está no
|
|
31
|
+
// `node_modules` dele — nunca seria encontrado. `createRequire(<root>/package.json)`
|
|
32
|
+
// resolve a partir do projeto, é estável, e honra `exports` inclusive de pacote
|
|
33
|
+
// ESM-only, porque resolver não é carregar.
|
|
34
|
+
|
|
35
|
+
import { createRequire } from 'node:module';
|
|
36
|
+
import { existsSync, readdirSync } from 'node:fs';
|
|
37
|
+
import path from 'node:path';
|
|
38
|
+
import { pathToFileURL } from 'node:url';
|
|
39
|
+
|
|
40
|
+
// Namespace do MÓDULO, não os símbolos soltos: é o módulo real que a validação
|
|
41
|
+
// tem de conferir. Montar aqui um objeto `{specWaveTrackerApi: 1, …}` a partir
|
|
42
|
+
// dos símbolos seria um falso que passa por construção — o mesmo defeito da
|
|
43
|
+
// porta falsa escrita à mão, e o embutido deixaria de exercitar o loader.
|
|
44
|
+
import * as trackerGithubProjects from './tracker-github-projects/index.mjs';
|
|
45
|
+
import * as scmGithub from './scm-github/index.mjs';
|
|
46
|
+
import { checkTrackerPort } from '../ports/tracker.mjs';
|
|
47
|
+
import { checkScmPort } from '../ports/scm.mjs';
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* A versão do contrato que este core fala.
|
|
51
|
+
*
|
|
52
|
+
* Um plugin publicado independentemente **vai** ficar para trás, e descobrir
|
|
53
|
+
* isso na primeira chamada de rede — no meio de um `decompose` que já gastou uma
|
|
54
|
+
* geração de IA — é o pior momento possível. Por isso a checagem é na carga.
|
|
55
|
+
*/
|
|
56
|
+
export const TRACKER_API_VERSION = 1;
|
|
57
|
+
export const SCM_API_VERSION = 1;
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* O que um módulo de plugin exporta. O embutido declara o mesmo — ver o bloco
|
|
61
|
+
* "O que o LOADER lê" no fim de cada `index.mjs` de plugin.
|
|
62
|
+
*/
|
|
63
|
+
const FORMA = Object.freeze({
|
|
64
|
+
tracker: Object.freeze({
|
|
65
|
+
versao: 'specWaveTrackerApi', esperada: TRACKER_API_VERSION,
|
|
66
|
+
kind: 'trackerKind', fabrica: 'createTracker', conferir: checkTrackerPort,
|
|
67
|
+
// Convenção de pacote da §9.2, nível 2.
|
|
68
|
+
escopado: k => `@spec-wave/tracker-${k}`,
|
|
69
|
+
}),
|
|
70
|
+
scm: Object.freeze({
|
|
71
|
+
versao: 'specWaveScmApi', esperada: SCM_API_VERSION,
|
|
72
|
+
kind: 'scmKind', fabrica: 'createScm', conferir: checkScmPort,
|
|
73
|
+
escopado: k => `@spec-wave/scm-${k}`,
|
|
74
|
+
}),
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
/** Os embutidos, indexados pelo `kind` que o próprio módulo declara. */
|
|
78
|
+
const EMBUTIDOS = Object.freeze({
|
|
79
|
+
tracker: Object.freeze({ [trackerGithubProjects.trackerKind]: trackerGithubProjects }),
|
|
80
|
+
scm: Object.freeze({ [scmGithub.scmKind]: scmGithub }),
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* O `kind` que o core assume enquanto o bloco D não o deriva do config legado.
|
|
85
|
+
*
|
|
86
|
+
* Exportados DAQUI para que `src/ports/index.mjs` não escreva um nome de
|
|
87
|
+
* fornecedor: o core não ramifica nem defaulta por fornecedor, e este arquivo é
|
|
88
|
+
* o único lugar onde esse nome pode aparecer (a barreira isenta `src/plugins/`).
|
|
89
|
+
*/
|
|
90
|
+
export const DEFAULT_TRACKER_KIND = trackerGithubProjects.trackerKind;
|
|
91
|
+
export const DEFAULT_SCM_KIND = scmGithub.scmKind;
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Os `kind` de plugin DISPONÍVEIS neste projeto — RFC-006 §9.3, Fase 2 bloco F.
|
|
95
|
+
*
|
|
96
|
+
* O embutido sempre entra. Os demais são descobertos pelas mesmas convenções da
|
|
97
|
+
* §9.2, na ordem inversa: em vez de resolver um `kind` conhecido, varre-se o que
|
|
98
|
+
* está instalado e deduz-se o `kind` do NOME.
|
|
99
|
+
*
|
|
100
|
+
* ── Por que o `init` precisa disto ──────────────────────────────────────────
|
|
101
|
+
*
|
|
102
|
+
* As duas perguntas da §9.3 só fazem sentido com mais de uma resposta. Com um
|
|
103
|
+
* fornecedor só — o caso de hoje — perguntar "qual tracker?" é ruído, e pior:
|
|
104
|
+
* sugere que os outros existem e que a escolha tem consequência. O `init` chama
|
|
105
|
+
* isto e **só pergunta quando há o que escolher**.
|
|
106
|
+
*
|
|
107
|
+
* Varredura de diretório, não `import()`: descobrir o que existe não pode custar
|
|
108
|
+
* carregar código de terceiro. A validação acontece na CARGA, depois da escolha.
|
|
109
|
+
*
|
|
110
|
+
* @param {object} params
|
|
111
|
+
* @param {'tracker'|'scm'} params.port
|
|
112
|
+
* @param {string} [params.root] raiz do projeto
|
|
113
|
+
* @returns {Array<{kind: string, origem: 'embutido'|'pacote'|'local', spec: string|null}>}
|
|
114
|
+
*/
|
|
115
|
+
export function listPluginKinds({ port, root = process.cwd() }) {
|
|
116
|
+
const forma = FORMA[port];
|
|
117
|
+
if (!forma) return [];
|
|
118
|
+
|
|
119
|
+
const achados = Object.keys(EMBUTIDOS[port])
|
|
120
|
+
.map(kind => ({ kind, origem: 'embutido', spec: null }));
|
|
121
|
+
const vistos = new Set(achados.map(a => a.kind));
|
|
122
|
+
|
|
123
|
+
const acrescentar = (kind, origem, spec) => {
|
|
124
|
+
if (!kind || vistos.has(kind)) return;
|
|
125
|
+
vistos.add(kind);
|
|
126
|
+
achados.push({ kind, origem, spec });
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
// Nível 2: `@spec-wave/<porta>-<kind>` no escopo instalado.
|
|
130
|
+
const escopo = path.join(root, 'node_modules', '@spec-wave');
|
|
131
|
+
const prefixoEscopado = `${port}-`;
|
|
132
|
+
for (const nome of lerDir(escopo)) {
|
|
133
|
+
if (nome.startsWith(prefixoEscopado)) {
|
|
134
|
+
acrescentar(nome.slice(prefixoEscopado.length), 'pacote', `@spec-wave/${nome}`);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
// Nível 3: `spec-wave-<kind>-plugin`. Ambíguo entre as portas por construção
|
|
139
|
+
// (o nome não diz a porta), então entra só se AINDA não houver esse `kind` —
|
|
140
|
+
// é o mesmo motivo pelo qual ele é o terceiro na resolução.
|
|
141
|
+
for (const nome of lerDir(path.join(root, 'node_modules'))) {
|
|
142
|
+
const m = /^spec-wave-(.+)-plugin$/.exec(nome);
|
|
143
|
+
if (m) acrescentar(m[1], 'pacote', nome);
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// Nível 4: a fenda de desenvolvimento.
|
|
147
|
+
const fenda = path.join(root, '.spec-wave', 'plugins');
|
|
148
|
+
for (const nome of lerDir(fenda)) {
|
|
149
|
+
if (nome.startsWith(prefixoEscopado)) {
|
|
150
|
+
acrescentar(nome.slice(prefixoEscopado.length), 'local',
|
|
151
|
+
`./.spec-wave/plugins/${nome}/index.mjs`);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
return achados;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** `readdirSync` que devolve `[]` em vez de lançar — diretório ausente é normal. */
|
|
159
|
+
function lerDir(dir) {
|
|
160
|
+
try {
|
|
161
|
+
return readdirSync(dir);
|
|
162
|
+
} catch {
|
|
163
|
+
return [];
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Os especificadores a tentar, em ordem (§9.2) — função PURA.
|
|
169
|
+
*
|
|
170
|
+
* **`package` explícito NÃO tem fallback.** Quem nomeia um pacote quer aquele
|
|
171
|
+
* pacote: cair na convenção em silêncio entrega uma porta diferente da pedida, e
|
|
172
|
+
* o sintoma aparece longe da causa. Falhar dizendo o nome é uma linha; descobrir
|
|
173
|
+
* que o fork não estava sendo usado é uma hora.
|
|
174
|
+
*
|
|
175
|
+
* O nível 3 (`spec-wave-<kind>-plugin`) vem DEPOIS do nível 2 porque não tem o
|
|
176
|
+
* nome da porta dentro: um `kind` que sirva às duas portas resolveria para o
|
|
177
|
+
* mesmo pacote nas duas. O nível 2 é o que desambigua, então é o preferido.
|
|
178
|
+
*
|
|
179
|
+
* O nível 4 é a fenda de desenvolvimento do plugin, dentro do projeto —
|
|
180
|
+
* `.spec-wave/plugins/<porta>-<kind>/index.mjs`. Fica sob `.spec-wave/` porque
|
|
181
|
+
* é onde já vivem o cache e os prompts do projeto.
|
|
182
|
+
*
|
|
183
|
+
* @param {object} params
|
|
184
|
+
* @param {'tracker'|'scm'} params.port
|
|
185
|
+
* @param {string} params.kind
|
|
186
|
+
* @param {string} [params.pkg] `tracker.package` / `scm.package` do config
|
|
187
|
+
* @returns {string[]}
|
|
188
|
+
*/
|
|
189
|
+
export function candidateSpecifiers({ port, kind, pkg }) {
|
|
190
|
+
if (pkg) return [pkg];
|
|
191
|
+
if (!kind) return [];
|
|
192
|
+
return [
|
|
193
|
+
FORMA[port].escopado(kind),
|
|
194
|
+
`spec-wave-${kind}-plugin`,
|
|
195
|
+
`./.spec-wave/plugins/${port}-${kind}/index.mjs`,
|
|
196
|
+
];
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Especificador de CAMINHO (`.` ou `/`) em vez de nome de pacote. */
|
|
200
|
+
const eCaminho = spec => spec.startsWith('.') || spec.startsWith('/');
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* O módulo tem a forma que o loader exige? — função PURA.
|
|
204
|
+
*
|
|
205
|
+
* Quatro coisas, e a ordem importa: sem a versão do contrato não há garantia
|
|
206
|
+
* nenhuma sobre o resto, então ela vem primeiro.
|
|
207
|
+
*
|
|
208
|
+
* @param {object} params
|
|
209
|
+
* @param {'tracker'|'scm'} params.port
|
|
210
|
+
* @param {object} params.mod o módulo importado
|
|
211
|
+
* @param {string} params.kind o `kind` que o config pediu
|
|
212
|
+
* @param {string} [params.origem] para a mensagem
|
|
213
|
+
* @returns {string[]} problemas; vazio = conforme
|
|
214
|
+
*/
|
|
215
|
+
export function checkPluginModule({ port, mod, kind, origem = 'plugin' }) {
|
|
216
|
+
const forma = FORMA[port];
|
|
217
|
+
if (!mod || typeof mod !== 'object') return [`${origem}: não exporta nada`];
|
|
218
|
+
const problemas = [];
|
|
219
|
+
|
|
220
|
+
const versao = mod[forma.versao];
|
|
221
|
+
if (versao === undefined) {
|
|
222
|
+
problemas.push(
|
|
223
|
+
`${origem}: não exporta \`${forma.versao}\` — não é um plugin de ${port} da spec-wave `
|
|
224
|
+
+ '(ou é de uma versão anterior ao contrato versionado)'
|
|
225
|
+
);
|
|
226
|
+
// Sem a versão, cobrar o resto é adivinhação: um módulo qualquer não tem por
|
|
227
|
+
// que ter `createTracker`, e listar cinco problemas esconde o único que é o
|
|
228
|
+
// problema.
|
|
229
|
+
return problemas;
|
|
230
|
+
}
|
|
231
|
+
if (versao !== forma.esperada) {
|
|
232
|
+
problemas.push(
|
|
233
|
+
`${origem}: fala a versão ${versao} do contrato de ${port} e este core fala a `
|
|
234
|
+
+ `${forma.esperada}. ${versao > forma.esperada
|
|
235
|
+
? 'Atualize a spec-wave (`spec-wave update`).'
|
|
236
|
+
: 'Atualize o plugin.'}`
|
|
237
|
+
);
|
|
238
|
+
// Também para aqui: cobrar a forma da v1 de um módulo que declara outra
|
|
239
|
+
// versão produziria uma lista de problemas que não são o problema.
|
|
240
|
+
return problemas;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
if (typeof mod[forma.fabrica] !== 'function') {
|
|
244
|
+
problemas.push(`${origem}: não exporta a fábrica \`${forma.fabrica}\``);
|
|
245
|
+
}
|
|
246
|
+
const declarado = mod[forma.kind];
|
|
247
|
+
if (!declarado) {
|
|
248
|
+
problemas.push(`${origem}: não exporta \`${forma.kind}\``);
|
|
249
|
+
} else if (kind && declarado !== kind) {
|
|
250
|
+
// Divergência silenciosa com efeito máximo: o config pede `jira`, o pacote
|
|
251
|
+
// instalado é de outro tracker, e tudo "funciona" contra o site errado.
|
|
252
|
+
problemas.push(
|
|
253
|
+
`${origem}: declara \`${forma.kind}\` = "${declarado}" e o config pede "${kind}"`
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
if (!mod.capabilities || typeof mod.capabilities !== 'object') {
|
|
257
|
+
problemas.push(`${origem}: não exporta \`capabilities\``);
|
|
258
|
+
}
|
|
259
|
+
return problemas;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Memo da RESOLUÇÃO, não da porta.
|
|
264
|
+
*
|
|
265
|
+
* `import()` já é cacheado pelo runtime, mas o LAÇO de candidatos não é: dois
|
|
266
|
+
* dos três candidatos de convenção normalmente não existem, e pagar duas falhas
|
|
267
|
+
* de resolução por comando é desperdício puro. A porta continua sendo construída
|
|
268
|
+
* a cada chamada — "nada de reuso de instância" (CLAUDE.md) é sobre contagem de
|
|
269
|
+
* chamadas e rate limit, e não muda aqui.
|
|
270
|
+
*/
|
|
271
|
+
const memo = new Map();
|
|
272
|
+
|
|
273
|
+
/** Para os testes: o memo é global ao processo. */
|
|
274
|
+
export function resetPluginCache() {
|
|
275
|
+
memo.clear();
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* Resolve e carrega o módulo do plugin.
|
|
280
|
+
*
|
|
281
|
+
* @param {object} params
|
|
282
|
+
* @param {'tracker'|'scm'} params.port
|
|
283
|
+
* @param {string} params.kind
|
|
284
|
+
* @param {string} [params.pkg]
|
|
285
|
+
* @param {string} [params.root] raiz do projeto — de onde a resolução parte
|
|
286
|
+
* @returns {Promise<{mod: object|null, origem: string|null, error: string|null}>}
|
|
287
|
+
*/
|
|
288
|
+
export async function loadPluginModule({ port, kind, pkg, root = process.cwd() }) {
|
|
289
|
+
if (!FORMA[port]) return { mod: null, origem: null, error: `porta desconhecida: "${port}"` };
|
|
290
|
+
|
|
291
|
+
const chave = `${port}|${kind || ''}|${pkg || ''}|${root}`;
|
|
292
|
+
if (memo.has(chave)) return memo.get(chave);
|
|
293
|
+
|
|
294
|
+
const guardar = (r) => { memo.set(chave, r); return r; };
|
|
295
|
+
|
|
296
|
+
// Embutido — mas só quando o config não nomeou um pacote. `package` explícito
|
|
297
|
+
// vence até para um `kind` embutido: é assim que se usa um fork.
|
|
298
|
+
if (!pkg && EMBUTIDOS[port][kind]) {
|
|
299
|
+
const mod = EMBUTIDOS[port][kind];
|
|
300
|
+
const problemas = checkPluginModule({ port, mod, kind, origem: `embutido "${kind}"` });
|
|
301
|
+
// Um embutido que não passe é defeito NOSSO, não do usuário — daí a
|
|
302
|
+
// mensagem diferente. A suíte reprova antes de chegar aqui.
|
|
303
|
+
if (problemas.length) {
|
|
304
|
+
return guardar({ mod: null, origem: null, error: `plugin embutido inconsistente: ${problemas.join('; ')}` });
|
|
305
|
+
}
|
|
306
|
+
return guardar({ mod, origem: `embutido "${kind}"`, error: null });
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
const candidatos = candidateSpecifiers({ port, kind, pkg });
|
|
310
|
+
if (candidatos.length === 0) {
|
|
311
|
+
return guardar({ mod: null, origem: null, error: `${port}: nem \`kind\` nem \`package\` no config` });
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
const req = createRequire(path.join(root, 'package.json'));
|
|
315
|
+
const naoAchados = [];
|
|
316
|
+
|
|
317
|
+
for (const spec of candidatos) {
|
|
318
|
+
// Etapa 1 — RESOLVER. Falha aqui = não instalado, próximo candidato.
|
|
319
|
+
let url;
|
|
320
|
+
try {
|
|
321
|
+
if (eCaminho(spec)) {
|
|
322
|
+
const abs = path.resolve(root, spec);
|
|
323
|
+
// `import.meta.resolve` NÃO confere existência de caminho (medido), então
|
|
324
|
+
// para caminho a sonda é o disco.
|
|
325
|
+
if (!existsSync(abs)) { naoAchados.push(spec); continue; }
|
|
326
|
+
url = pathToFileURL(abs).href;
|
|
327
|
+
} else {
|
|
328
|
+
url = pathToFileURL(req.resolve(spec)).href;
|
|
329
|
+
}
|
|
330
|
+
} catch {
|
|
331
|
+
naoAchados.push(spec);
|
|
332
|
+
continue;
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
// Etapa 2 — CARREGAR. Falha aqui é outro bicho: o plugin EXISTE e está
|
|
336
|
+
// quebrado. Seguir para o próximo candidato esconderia o defeito e mandaria
|
|
337
|
+
// o usuário instalar o que ele já tem.
|
|
338
|
+
let mod;
|
|
339
|
+
try {
|
|
340
|
+
mod = await import(url);
|
|
341
|
+
} catch (err) {
|
|
342
|
+
return guardar({
|
|
343
|
+
mod: null,
|
|
344
|
+
origem: spec,
|
|
345
|
+
error: `plugin de ${port} "${spec}" está instalado mas não carrega: ${err.message.split('\n')[0]}`,
|
|
346
|
+
});
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
const problemas = checkPluginModule({ port, mod, kind, origem: `plugin de ${port} "${spec}"` });
|
|
350
|
+
// Forma errada também PARA: achamos o pacote que o usuário pediu, e mandá-lo
|
|
351
|
+
// procurar outro seria mentir sobre o que aconteceu.
|
|
352
|
+
if (problemas.length) {
|
|
353
|
+
return guardar({ mod: null, origem: spec, error: problemas.join('\n ') });
|
|
354
|
+
}
|
|
355
|
+
return guardar({ mod, origem: spec, error: null });
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
// Nada resolveu. A mensagem LISTA o que foi tentado — sem isso, "plugin não
|
|
359
|
+
// encontrado" manda o usuário adivinhar qual nome a spec-wave esperava.
|
|
360
|
+
return guardar({
|
|
361
|
+
mod: null,
|
|
362
|
+
origem: null,
|
|
363
|
+
error: pkg
|
|
364
|
+
? `plugin de ${port} "${pkg}" não encontrado a partir de ${root}. `
|
|
365
|
+
+ 'Instale-o no projeto (`npm i -D ' + pkg + '`) ou corrija o `package` no config.'
|
|
366
|
+
: `nenhum plugin de ${port} para \`kind: "${kind}"\`. Tentei, nesta ordem:\n `
|
|
367
|
+
+ naoAchados.join('\n ')
|
|
368
|
+
+ '\nInstale um deles, ou nomeie o pacote em `'
|
|
369
|
+
+ port + '.package` no config.',
|
|
370
|
+
});
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* O módulo já validado, com a porta construída e CONFERIDA.
|
|
375
|
+
*
|
|
376
|
+
* A conferência da porta (`checkTrackerPort`/`checkScmPort`) roda uma vez por
|
|
377
|
+
* módulo, não por chamada: o que pode estar defasado é o MÓDULO, e a forma da
|
|
378
|
+
* porta não depende do token.
|
|
379
|
+
*
|
|
380
|
+
* ⚠️ Este é o caminho por onde essas funções vão passar a rodar em PRODUÇÃO — e
|
|
381
|
+
* AINDA NÃO rodam: `getTracker`/`getScm` não têm chamador fora dos testes, e é o
|
|
382
|
+
* bloco E que afunila os ~35 call sites para cá. Até lá, quem constrói porta em
|
|
383
|
+
* produção é o próprio comando, sem passar por validação nenhuma. Escrever isto
|
|
384
|
+
* no presente seria o defeito do PR #146 de novo: prosa afirmando uma garantia
|
|
385
|
+
* que nada cumpre.
|
|
386
|
+
*
|
|
387
|
+
* `params` é repassado à fábrica como UM objeto, e cada plugin lê as chaves que
|
|
388
|
+
* conhece — é para isso que a aridade está presa em 1. O embutido lê `project`;
|
|
389
|
+
* um plugin de Jira leria `config`/`fieldMap` e ignoraria o resto.
|
|
390
|
+
*
|
|
391
|
+
* @param {object} args
|
|
392
|
+
* @param {'tracker'|'scm'} args.port
|
|
393
|
+
* @param {string} args.kind
|
|
394
|
+
* @param {string} [args.pkg]
|
|
395
|
+
* @param {string} [args.root]
|
|
396
|
+
* @param {object} args.params argumento-objeto da fábrica
|
|
397
|
+
* @returns {Promise<{porta: object|null, origem: string|null, error: string|null}>}
|
|
398
|
+
*/
|
|
399
|
+
export async function buildPort({ port, kind, pkg, root, params }) {
|
|
400
|
+
const { mod, origem, error } = await loadPluginModule({ port, kind, pkg, root });
|
|
401
|
+
if (error) return { porta: null, origem, error };
|
|
402
|
+
|
|
403
|
+
const forma = FORMA[port];
|
|
404
|
+
let porta;
|
|
405
|
+
try {
|
|
406
|
+
porta = mod[forma.fabrica](params);
|
|
407
|
+
} catch (err) {
|
|
408
|
+
// A fábrica é código de TERCEIRO a partir daqui. Um throw viraria stack
|
|
409
|
+
// trace no terminal de quem só instalou um plugin quebrado.
|
|
410
|
+
return { porta: null, origem, error: `${origem}: a fábrica lançou: ${err.message.split('\n')[0]}` };
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
const chaveVerificada = `verificada|${port}|${origem}`;
|
|
414
|
+
if (!memo.has(chaveVerificada)) {
|
|
415
|
+
const problemas = forma.conferir(porta);
|
|
416
|
+
memo.set(chaveVerificada, problemas);
|
|
417
|
+
}
|
|
418
|
+
const problemas = memo.get(chaveVerificada);
|
|
419
|
+
if (problemas.length) {
|
|
420
|
+
return {
|
|
421
|
+
porta: null,
|
|
422
|
+
origem,
|
|
423
|
+
error: `${origem} não cumpre o contrato de ${port}:\n ${problemas.join('\n ')}`,
|
|
424
|
+
};
|
|
425
|
+
}
|
|
426
|
+
return { porta, origem, error: null };
|
|
427
|
+
}
|
|
@@ -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;
|