@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
package/src/commands/update.mjs
CHANGED
|
@@ -5,9 +5,7 @@ import { homedir } from 'node:os';
|
|
|
5
5
|
import path from 'node:path';
|
|
6
6
|
import { resolveToken } from '../api/auth.mjs';
|
|
7
7
|
import { CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
|
|
8
|
-
import {
|
|
9
|
-
import { createGithubScm } from '../plugins/scm-github/index.mjs';
|
|
10
|
-
import { resolveScmLink } from '../ports/index.mjs';
|
|
8
|
+
import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
|
|
11
9
|
import {
|
|
12
10
|
resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
|
|
13
11
|
decideConfigInPr, decideSkillInPr, composeConfigCleanupHint, explainGitWriteError,
|
|
@@ -25,6 +23,7 @@ import { findConfigPath } from '../lib/project-root.mjs';
|
|
|
25
23
|
import { configuredRole } from '../lib/repo-role.mjs';
|
|
26
24
|
import { currentGitBranch } from '../lib/repo-links.mjs';
|
|
27
25
|
import { cliRef } from '../lib/cli-ref.mjs';
|
|
26
|
+
import { tagRegistryPlan } from '../lib/tag-registry.mjs';
|
|
28
27
|
|
|
29
28
|
// Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
|
|
30
29
|
const REPO_FILES = [
|
|
@@ -201,9 +200,10 @@ async function buildConfigContent(token, config) {
|
|
|
201
200
|
}
|
|
202
201
|
// `provision: false` é leitura do schema vivo — a mesma operação que o
|
|
203
202
|
// `refresh --config` usa para regravar os ids do board.
|
|
204
|
-
const
|
|
205
|
-
token, owner: config.owner, repo: config.repo,
|
|
206
|
-
})
|
|
203
|
+
const trackerVivo = await requireTracker({
|
|
204
|
+
token, owner: config.owner, repo: config.repo, board: true,
|
|
205
|
+
});
|
|
206
|
+
const { config: vivo } = await trackerVivo.setup({ provision: false });
|
|
207
207
|
if (!vivo) return { content: null, error: 'Project não encontrado' };
|
|
208
208
|
const snapshot = {
|
|
209
209
|
id: vivo.projectId, number: vivo.projectNumber,
|
|
@@ -248,11 +248,22 @@ async function buildConfigContent(token, config) {
|
|
|
248
248
|
* só o que REALMENTE passou — é o que o corpo do PR vai afirmar a quem
|
|
249
249
|
* revisa, e ele não pode prometer o que falhou.
|
|
250
250
|
*/
|
|
251
|
-
/**
|
|
252
|
-
|
|
251
|
+
/**
|
|
252
|
+
* Porta de SCM do repositório-alvo — ASSÍNCRONA desde a leva 4 do bloco E.
|
|
253
|
+
*
|
|
254
|
+
* `tk` é lazy, e é por isso que ela fica mecânica (`await` duplo nos 8 call
|
|
255
|
+
* sites) em vez de resolver a porta uma vez: o token só existe depois de uma
|
|
256
|
+
* cadeia de decisões, e antecipá-la para resolver a porta mudaria a ordem em que
|
|
257
|
+
* o `update` pede credencial. O custo são 8 leituras de arquivo num comando que
|
|
258
|
+
* faz dezenas de chamadas de rede.
|
|
259
|
+
*
|
|
260
|
+
* (O comentário anterior dizia "memoizada" e ela nunca foi — construía uma porta
|
|
261
|
+
* por chamada. Corrigido de passagem.)
|
|
262
|
+
*/
|
|
263
|
+
const scmDe = (tk, owner, repo) => requireScm({ link: resolveScmLink({ owner, repo }), token: tk });
|
|
253
264
|
|
|
254
265
|
async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
|
|
255
|
-
const tracker =
|
|
266
|
+
const tracker = await requireTracker({ token, owner, repo });
|
|
256
267
|
const done = { created: [], updated: [], removed: [] };
|
|
257
268
|
for (const label of labelDiff.missing) {
|
|
258
269
|
try {
|
|
@@ -272,11 +283,22 @@ async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
|
|
|
272
283
|
p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
|
|
273
284
|
}
|
|
274
285
|
}
|
|
275
|
-
|
|
286
|
+
// `countOpenWithTag` e `deleteTag` são OPCIONAIS no contrato e nenhuma
|
|
287
|
+
// capability as liga — ver `lib/tag-registry.mjs`, que tem a razão inteira.
|
|
288
|
+
const registro = tagRegistryPlan(tracker);
|
|
289
|
+
if (labelDiff.orphan.length > 0 && !registro.canDelete) {
|
|
290
|
+
p.log.warn(`${labelDiff.orphan.length} label(s) descontinuada(s) a remover: ${registro.warning}`);
|
|
291
|
+
}
|
|
292
|
+
for (const label of registro.canDelete ? labelDiff.orphan : []) {
|
|
276
293
|
try {
|
|
294
|
+
// Sem contagem, o portão de segurança (não remover label em uso) não pode
|
|
295
|
+
// ser avaliado — e `null` é exatamente o que `shouldDeleteOrphanLabel` já
|
|
296
|
+
// trata como "não sei", que recusa sem `--force-labels`. Degradar para o
|
|
297
|
+
// valor mais conservador é o certo: o risco de apagar label em uso é maior
|
|
298
|
+
// que o incômodo de pedir a flag.
|
|
277
299
|
const inUse = forceLabels
|
|
278
300
|
? 0
|
|
279
|
-
: await tracker.countOpenWithTag({ tag: label.name }).catch(() => null);
|
|
301
|
+
: (registro.canCount ? await tracker.countOpenWithTag({ tag: label.name }).catch(() => null) : null);
|
|
280
302
|
const decision = shouldDeleteOrphanLabel({ inUse, forceLabels });
|
|
281
303
|
if (!decision.ok) {
|
|
282
304
|
p.log.warn(`Label ${label.name}: ${decision.motivo}. Use --force-labels para remover mesmo assim.`);
|
|
@@ -383,12 +405,13 @@ export async function update(options = {}) {
|
|
|
383
405
|
} else {
|
|
384
406
|
try {
|
|
385
407
|
for (const f of repoFilesFor(role)) {
|
|
386
|
-
const remote = await scmDe(tk, owner, repo).readFile({ path: f.repoPath });
|
|
408
|
+
const remote = await (await scmDe(tk, owner, repo)).readFile({ path: f.repoPath });
|
|
387
409
|
const local = readTemplate(...f.template);
|
|
388
410
|
if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
|
|
389
411
|
else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
|
|
390
412
|
}
|
|
391
|
-
|
|
413
|
+
const trackerLabels = await requireTracker({ token: tk, owner, repo });
|
|
414
|
+
labelDiff = diffLabels(await trackerLabels.listTags(), config?.ai, config?.devAgent);
|
|
392
415
|
repoChecked = true;
|
|
393
416
|
s.stop('Repositório comparado.');
|
|
394
417
|
} catch (err) {
|
|
@@ -408,7 +431,7 @@ export async function update(options = {}) {
|
|
|
408
431
|
if (prMode) {
|
|
409
432
|
const tk = await getToken();
|
|
410
433
|
try {
|
|
411
|
-
base = await scmDe(tk, owner, repo).defaultBranch();
|
|
434
|
+
base = await (await scmDe(tk, owner, repo)).defaultBranch();
|
|
412
435
|
if (branch === base) {
|
|
413
436
|
p.log.error(
|
|
414
437
|
`--branch "${branch}" é a própria branch default do repositório; ` +
|
|
@@ -417,8 +440,8 @@ export async function update(options = {}) {
|
|
|
417
440
|
p.cancel('Update cancelado.');
|
|
418
441
|
return;
|
|
419
442
|
}
|
|
420
|
-
remoteConfigRaw = await scmDe(tk, owner, repo).readFile({ path: CONFIG_FILE, ref: base });
|
|
421
|
-
const status = await scmDe(tk, owner, repo).compare({ base: base, head: branch });
|
|
443
|
+
remoteConfigRaw = await (await scmDe(tk, owner, repo)).readFile({ path: CONFIG_FILE, ref: base });
|
|
444
|
+
const status = await (await scmDe(tk, owner, repo)).compare({ base: base, head: branch });
|
|
422
445
|
branchExists = status !== null;
|
|
423
446
|
if (status === 'behind' || status === 'identical') {
|
|
424
447
|
// Não fazemos force-push: só avisamos. Empilhar um commit numa branch já
|
|
@@ -468,8 +491,12 @@ export async function update(options = {}) {
|
|
|
468
491
|
for (const { job, targets } of skillCandidates) {
|
|
469
492
|
// Em paralelo: o destino do Codex são 20+ arquivos, e um GET por vez
|
|
470
493
|
// transformaria a checagem na parte mais lenta do comando.
|
|
494
|
+
// A porta é resolvida UMA vez, fora do `map`: dentro dele cada `await`
|
|
495
|
+
// seria uma leitura de config por arquivo — 20+ no destino do Codex —, e
|
|
496
|
+
// o arrow teria de virar assíncrono só para isso.
|
|
497
|
+
const scmAlvo = await scmDe(tk, owner, repo);
|
|
471
498
|
const remotes = await Promise.all(
|
|
472
|
-
targets.map(t =>
|
|
499
|
+
targets.map(t => scmAlvo.readFile({ path: t.relPath, ref: base }))
|
|
473
500
|
);
|
|
474
501
|
targets.forEach((t, i) => {
|
|
475
502
|
const remote = remotes[i];
|
|
@@ -733,7 +760,7 @@ export async function update(options = {}) {
|
|
|
733
760
|
s.start(`Enviando ${treeFiles.length} arquivo(s) em um único commit para "${branch}"...`);
|
|
734
761
|
let commitOk = false;
|
|
735
762
|
try {
|
|
736
|
-
const res = await scmDe(tk, owner, repo).writeFiles({
|
|
763
|
+
const res = await (await scmDe(tk, owner, repo)).writeFiles({
|
|
737
764
|
branch,
|
|
738
765
|
base,
|
|
739
766
|
files: treeFiles.map(f => ({ path: f.path, content: f.content })),
|
|
@@ -753,7 +780,7 @@ export async function update(options = {}) {
|
|
|
753
780
|
// write" pode não ter "Pull requests: write" — permissão NOVA neste modo.
|
|
754
781
|
if (commitOk) {
|
|
755
782
|
try {
|
|
756
|
-
const { pr } = await scmDe(tk, owner, repo).ensurePullRequest({
|
|
783
|
+
const { pr } = await (await scmDe(tk, owner, repo)).ensurePullRequest({
|
|
757
784
|
branch,
|
|
758
785
|
base,
|
|
759
786
|
title: composePrTitle({ version: CLI_VERSION }),
|
|
@@ -792,7 +819,7 @@ export async function update(options = {}) {
|
|
|
792
819
|
const tk = await getToken();
|
|
793
820
|
for (const f of repoFiles) {
|
|
794
821
|
try {
|
|
795
|
-
await scmDe(tk, owner, repo).installAutomation({ files: [{ path: f.repoPath, content: f.local, message: `chore: update ${path.basename(f.repoPath)} [spec-wave]` }] });
|
|
822
|
+
await (await scmDe(tk, owner, repo)).installAutomation({ files: [{ path: f.repoPath, content: f.local, message: `chore: update ${path.basename(f.repoPath)} [spec-wave]` }] });
|
|
796
823
|
p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
|
|
797
824
|
} catch (err) {
|
|
798
825
|
p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { resolveToken } from '../api/auth.mjs';
|
|
2
|
-
import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
|
|
3
2
|
import { slugify } from '../lib/slugify.mjs';
|
|
4
3
|
import {
|
|
5
4
|
CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_BUG, LABEL_BUG_APPROVED,
|
|
@@ -15,8 +14,7 @@ import { docBlobUrl } from '../lib/repo-links.mjs';
|
|
|
15
14
|
import { loadArtifact } from '../lib/doc-source.mjs';
|
|
16
15
|
import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
|
|
17
16
|
import { isAwaitingMerge } from '../lib/doc-source.mjs';
|
|
18
|
-
import {
|
|
19
|
-
import { resolveScmLink } from '../ports/index.mjs';
|
|
17
|
+
import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
|
|
20
18
|
import { dependencySection } from '../lib/spec-audit.mjs';
|
|
21
19
|
|
|
22
20
|
/**
|
|
@@ -176,8 +174,8 @@ export async function validate({ issueNumber, deps = {} }) {
|
|
|
176
174
|
}
|
|
177
175
|
|
|
178
176
|
const n = parseInt(issueNumber, 10);
|
|
179
|
-
const tracker =
|
|
180
|
-
const scm =
|
|
177
|
+
const tracker = await requireTracker({ token, owner, repo, deps });
|
|
178
|
+
const scm = await requireScm({ link: resolveScmLink({ owner, repo }), token, deps });
|
|
181
179
|
const issue = await tracker.getWorkItem({ ref: { key: String(n) } });
|
|
182
180
|
|
|
183
181
|
// Branch base para a leitura em camadas. Best-effort: sem ela o resolvedor cai
|
|
@@ -6,7 +6,6 @@
|
|
|
6
6
|
import * as p from '@clack/prompts';
|
|
7
7
|
import chalk from 'chalk';
|
|
8
8
|
import { resolveToken } from '../api/auth.mjs';
|
|
9
|
-
import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
|
|
10
9
|
import { detectIssueType } from '../lib/issue-type.mjs';
|
|
11
10
|
import { resolveHubContext } from '../lib/project-root.mjs';
|
|
12
11
|
import { cachedSubIssues } from '../lib/story-graph.mjs';
|
|
@@ -17,6 +16,7 @@ import {
|
|
|
17
16
|
writeWorkspaceManifest, WORKSPACE_OVERRIDE_FILE,
|
|
18
17
|
} from '../lib/workspace.mjs';
|
|
19
18
|
import { CONFIG_FILE } from '../config.mjs';
|
|
19
|
+
import { requireTracker } from '../ports/index.mjs';
|
|
20
20
|
|
|
21
21
|
export async function workspace({ action, issue: issueArg, json = false, dryRun = false, refresh = false, deps = {} } = {}) {
|
|
22
22
|
if (action !== 'prepare') {
|
|
@@ -40,7 +40,7 @@ export async function workspace({ action, issue: issueArg, json = false, dryRun
|
|
|
40
40
|
|
|
41
41
|
const log = json ? { info() {}, warn: (m) => console.error(m) } : { info: p.log.info, warn: p.log.warn };
|
|
42
42
|
const token = await resolveToken();
|
|
43
|
-
const issue = await (
|
|
43
|
+
const issue = await (await requireTracker({ token, owner, repo, deps }))
|
|
44
44
|
.getWorkItem({ ref: { key: String(issueNumber) } });
|
|
45
45
|
const type = detectIssueType(issue);
|
|
46
46
|
|
|
@@ -22,8 +22,7 @@
|
|
|
22
22
|
// deixaria no clone um arquivo que o usuário não pediu e que colide no `git pull`
|
|
23
23
|
// depois do merge — justamente porque o merge pode trazer as edições do revisor.
|
|
24
24
|
|
|
25
|
-
import {
|
|
26
|
-
import { resolveScmLink } from '../ports/index.mjs';
|
|
25
|
+
import { requireScm, resolveScmLink } from '../ports/index.mjs';
|
|
27
26
|
import { resolveBranchName, explainGitWriteError } from './pr-branch.mjs';
|
|
28
27
|
import {
|
|
29
28
|
artifactBranch, composeArtifactPrTitle, composeArtifactPrBody, artifactCommitMessage,
|
|
@@ -88,8 +87,9 @@ export async function publishArtifact({
|
|
|
88
87
|
// `resolvePrToken` entra na CONSTRUÇÃO da porta, não numa chamada: a porta
|
|
89
88
|
// já sabe que só `ensurePullRequest` usa essa credencial. A política de qual
|
|
90
89
|
// token abre PR continua visível aqui, que é onde ela sempre esteve.
|
|
91
|
-
const porta =
|
|
90
|
+
const porta = await requireScm({
|
|
92
91
|
link: resolveScmLink({ owner, repo }), token, prToken: resolvePrToken(token),
|
|
92
|
+
deps: { scm },
|
|
93
93
|
});
|
|
94
94
|
|
|
95
95
|
const branch = artifactBranch({ issueNumber, doc });
|
package/src/lib/board.mjs
CHANGED
|
@@ -15,7 +15,9 @@
|
|
|
15
15
|
// é o Todo/In Progress/Done DENTRO dela, e os dois são dimensões separadas.
|
|
16
16
|
|
|
17
17
|
import { CONFIG_FILE, WORK_ITEM_TYPES } from '../config.mjs';
|
|
18
|
-
|
|
18
|
+
// Bloco E, leva 1: `openTracker` delega ao loader, então este arquivo saiu da
|
|
19
|
+
// lista de pendentes da barreira — não constrói mais porta nenhuma.
|
|
20
|
+
import { getTracker } from '../ports/index.mjs';
|
|
19
21
|
import { loadConfig } from './project-root.mjs';
|
|
20
22
|
import { invalidateCache } from './net-cache.mjs';
|
|
21
23
|
import { planStageMove } from './board-policy.mjs';
|
|
@@ -93,29 +95,25 @@ export function trackerAvailable({ cwd = process.cwd() } = {}) {
|
|
|
93
95
|
* saindo do config, porque os chamadores o usam para achar os documentos.
|
|
94
96
|
* @returns {{ tracker: object|null, root: string|null, error: string|null }}
|
|
95
97
|
*/
|
|
96
|
-
export function openTracker({
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
//
|
|
105
|
-
//
|
|
106
|
-
//
|
|
107
|
-
//
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
}),
|
|
116
|
-
root,
|
|
117
|
-
error: null,
|
|
118
|
-
};
|
|
98
|
+
export async function openTracker({
|
|
99
|
+
token, projectToken, owner, repo, cwd = process.cwd(), tracker: injetado = null,
|
|
100
|
+
} = {}) {
|
|
101
|
+
// ── Bloco E, leva 1: isto DELEGA ao loader e não constrói mais nada ────────
|
|
102
|
+
//
|
|
103
|
+
// Era o único ponto do core que construía tracker a partir do config, e é por
|
|
104
|
+
// isso que foi o primeiro a migrar: dez call sites passam por aqui, e o custo
|
|
105
|
+
// para eles é um `await` — todos já estavam em função assíncrona (medido).
|
|
106
|
+
//
|
|
107
|
+
// **`board: true` é daqui.** `getTracker` não exige o bloco `project`, porque
|
|
108
|
+
// os comandos constroem DUAS portas: uma para trabalho de issue, que num repo
|
|
109
|
+
// de papel `code` funciona sem bloco `project` nenhum, e esta, do BOARD, que
|
|
110
|
+
// sem o bloco não tem o que endereçar. Quem precisa do board é quem pede.
|
|
111
|
+
//
|
|
112
|
+
// owner/repo caem no config quando o chamador não os tem: o board é endereçado
|
|
113
|
+
// por `project.id`, mas a porta também faz REST de issue, que é endereçada por
|
|
114
|
+
// repositório. Quem TEM o par resolvido — os comandos, via `resolveHubContext`
|
|
115
|
+
// — passa o dele e vence. Esse fallback agora vive no `getTracker`.
|
|
116
|
+
return getTracker({ cwd, token, projectToken, owner, repo, board: true, deps: { tracker: injetado } });
|
|
119
117
|
}
|
|
120
118
|
|
|
121
119
|
/**
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
// Os blocos `tracker`/`scm` do `.spec-wave.json`, normalizados na LEITURA —
|
|
2
|
+
// RFC-006 §3.4, Fase 2 bloco D. Função PURA, zero imports.
|
|
3
|
+
//
|
|
4
|
+
// ── A regra, e o que ela proíbe exatamente ───────────────────────────────────
|
|
5
|
+
//
|
|
6
|
+
// §3.4: "normalizar na leitura, nunca regravar". A leitura que o plano fixou
|
|
7
|
+
// (§3.1) é que a regra proíbe **exigir** a regravação, não regravar: `refresh` e
|
|
8
|
+
// `update` seguem dropando legado, porque quem os roda já pediu para o config ser
|
|
9
|
+
// reescrito. O que a regra impede é o fluxo normal obrigar o usuário a migrar
|
|
10
|
+
// formato para continuar funcionando.
|
|
11
|
+
//
|
|
12
|
+
// Daí este arquivo: um `.spec-wave.json` da era 0.16.4 — sem bloco `tracker`, sem
|
|
13
|
+
// bloco `scm` — é LIDO como se os tivesse. Nada é gravado.
|
|
14
|
+
//
|
|
15
|
+
// ── Por que o `kind` entra por parâmetro ─────────────────────────────────────
|
|
16
|
+
//
|
|
17
|
+
// Seria mais curto escrever `kind: 'github-projects'` aqui. Mas isto é core, e o
|
|
18
|
+
// core não nomeia fornecedor — é o acoplamento que o bloco E0 passou 21 arquivos
|
|
19
|
+
// removendo, e `test/ports-boundary.test.mjs` o vigia. Os defaults vêm de
|
|
20
|
+
// `src/plugins/load.mjs` (`DEFAULT_TRACKER_KIND`/`DEFAULT_SCM_KIND`), que é o
|
|
21
|
+
// único lugar autorizado a saber qual é o fornecedor embutido.
|
|
22
|
+
//
|
|
23
|
+
// O que fica aqui é conhecimento sobre o FORMATO HISTÓRICO do nosso próprio
|
|
24
|
+
// arquivo — que o bloco `project` era a configuração de board e que `owner`/`repo`
|
|
25
|
+
// endereçavam o repositório. Isso é memória da spec-wave, não API de fornecedor.
|
|
26
|
+
//
|
|
27
|
+
// ── Nunca MUTA, e isso é o risco central ────────────────────────────────────
|
|
28
|
+
//
|
|
29
|
+
// Se um bloco derivado vazasse para uma gravação, TODO repositório passaria a
|
|
30
|
+
// acusar divergência no `update`, que faz diff byte a byte contra a cópia remota
|
|
31
|
+
// (`serializeConfig` é byte-exato por esse motivo — RFC §3.4). `updateConfig`
|
|
32
|
+
// relê o arquivo do disco, então o vazamento não pode vir por ali; o que pode
|
|
33
|
+
// vazar é uma mutação no objeto que o chamador ainda tem na mão. Por isso tudo
|
|
34
|
+
// aqui devolve objeto NOVO, e há teste ponta a ponta afirmando que o disco não
|
|
35
|
+
// muda.
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* O bloco `tracker`, com o que falta derivado do formato legado (função PURA).
|
|
39
|
+
*
|
|
40
|
+
* **Só preenche o que está AUSENTE.** Um `tracker.kind: "jira"` escrito à mão não
|
|
41
|
+
* ganha `config` derivada do bloco `project`: quem declarou Jira não quer a
|
|
42
|
+
* configuração do board do GitHub por baixo. Derivar sobre o que já está escrito
|
|
43
|
+
* é o oposto de normalizar.
|
|
44
|
+
*
|
|
45
|
+
* @param {object} config o `.spec-wave.json` lido
|
|
46
|
+
* @param {object} [opts]
|
|
47
|
+
* @param {string} [opts.defaultKind] o fornecedor embutido, vindo do loader
|
|
48
|
+
* @returns {{kind: string|null, package: string|undefined, config: object|null,
|
|
49
|
+
* stageMap: object|undefined, fieldMap: object|undefined,
|
|
50
|
+
* typeMap: object|undefined, derived: boolean}}
|
|
51
|
+
*/
|
|
52
|
+
export function deriveTrackerBlock(config, { defaultKind = null } = {}) {
|
|
53
|
+
const escrito = config?.tracker || null;
|
|
54
|
+
return {
|
|
55
|
+
kind: escrito?.kind || defaultKind,
|
|
56
|
+
package: escrito?.package,
|
|
57
|
+
// O bloco `project` É a configuração de tracker de um repo da era 0.x: id do
|
|
58
|
+
// Project, número, mapa de campos, e o par legado `etapaFieldId`/`stageOptions`
|
|
59
|
+
// que `plugins/tracker-github-projects/fields.mjs` ainda lê. Passar o bloco
|
|
60
|
+
// INTEIRO é o que mantém o caminho legado vivo sem este arquivo conhecê-lo.
|
|
61
|
+
config: escrito?.config ?? config?.project ?? null,
|
|
62
|
+
// Sem equivalente legado: os mapas nasceram com a Fase 2. Ausentes ficam
|
|
63
|
+
// ausentes — um `{}` diria "mapeado para nada", que não é a mesma coisa.
|
|
64
|
+
stageMap: escrito?.stageMap,
|
|
65
|
+
fieldMap: escrito?.fieldMap,
|
|
66
|
+
typeMap: escrito?.typeMap,
|
|
67
|
+
derived: !escrito?.kind,
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* O bloco `scm`, com o que falta derivado de `owner`/`repo` (função PURA).
|
|
73
|
+
*
|
|
74
|
+
* Num repo de papel `code` (RFC-005) não há bloco `project`, mas há `owner`/`repo`
|
|
75
|
+
* — então ele TEM um SCM próprio e nenhum tracker próprio. É por isso que as duas
|
|
76
|
+
* derivações são independentes em vez de uma só: elas não têm a mesma condição de
|
|
77
|
+
* existência, e juntá-las faria um repo de código parecer sem SCM.
|
|
78
|
+
*
|
|
79
|
+
* @param {object} config
|
|
80
|
+
* @param {object} [opts]
|
|
81
|
+
* @param {string} [opts.defaultKind]
|
|
82
|
+
* @returns {{kind: string|null, package: string|undefined,
|
|
83
|
+
* config: object|null, derived: boolean}}
|
|
84
|
+
*/
|
|
85
|
+
export function deriveScmBlock(config, { defaultKind = null } = {}) {
|
|
86
|
+
const escrito = config?.scm || null;
|
|
87
|
+
const owner = config?.owner;
|
|
88
|
+
const repo = config?.repo;
|
|
89
|
+
return {
|
|
90
|
+
kind: escrito?.kind || defaultKind,
|
|
91
|
+
package: escrito?.package,
|
|
92
|
+
// `{owner, repo}` é o endereço de repositório da era 0.x. Um par incompleto
|
|
93
|
+
// vira `null` em vez de `{owner: undefined, repo: 'x'}`: meio endereço é
|
|
94
|
+
// pior que nenhum, porque atravessa uma checagem de presença e falha depois.
|
|
95
|
+
config: escrito?.config ?? (owner && repo ? { owner, repo } : null),
|
|
96
|
+
derived: !escrito?.kind,
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Os dois blocos de uma vez (função PURA).
|
|
102
|
+
*
|
|
103
|
+
* @param {object} config
|
|
104
|
+
* @param {object} [opts]
|
|
105
|
+
* @param {string} [opts.trackerKind]
|
|
106
|
+
* @param {string} [opts.scmKind]
|
|
107
|
+
* @returns {{tracker: object, scm: object}}
|
|
108
|
+
*/
|
|
109
|
+
export function derivePortBlocks(config, { trackerKind = null, scmKind = null } = {}) {
|
|
110
|
+
return {
|
|
111
|
+
tracker: deriveTrackerBlock(config, { defaultKind: trackerKind }),
|
|
112
|
+
scm: deriveScmBlock(config, { defaultKind: scmKind }),
|
|
113
|
+
};
|
|
114
|
+
}
|
package/src/lib/doc-source.mjs
CHANGED
|
@@ -20,8 +20,7 @@
|
|
|
20
20
|
import { existsSync, readFileSync } from 'node:fs';
|
|
21
21
|
import path from 'node:path';
|
|
22
22
|
|
|
23
|
-
import {
|
|
24
|
-
import { resolveScmLink } from '../ports/index.mjs';
|
|
23
|
+
import { getScm, resolveScmLink } from '../ports/index.mjs';
|
|
25
24
|
import { artifactBranch } from './artifact-pr.mjs';
|
|
26
25
|
|
|
27
26
|
/**
|
|
@@ -94,7 +93,21 @@ export async function loadArtifact({
|
|
|
94
93
|
if (!token || !owner || !repo) {
|
|
95
94
|
return { content: null, state: 'unknown', ref: null, pr: null };
|
|
96
95
|
}
|
|
97
|
-
|
|
96
|
+
// `getScm` e não `requireScm`: esta função diz "I/O — NUNCA lança", e a
|
|
97
|
+
// construção da porta está FORA do `try` abaixo. Um plugin que não carrega tem
|
|
98
|
+
// de virar `state: 'unknown'` — "não consegui olhar" não é "não existe", e
|
|
99
|
+
// devolver `missing` faria o chamador REGERAR por cima de um documento que
|
|
100
|
+
// existe, pagando uma geração de IA para sobrescrever trabalho. É a mesma razão
|
|
101
|
+
// do caso sem token, três linhas acima.
|
|
102
|
+
//
|
|
103
|
+
// ⚠️ O ramo `erroPorta` é INALCANÇÁVEL HOJE, e está aqui de propósito:
|
|
104
|
+
// `resolveScmLink` ainda crava o fornecedor embutido (ver a nota nela), então o
|
|
105
|
+
// loader não tem como recusar. Ele passa a ser alcançável quando ela deixar de
|
|
106
|
+
// cravar — bloco F mais os call sites de E. Não é prosa prometendo garantia:
|
|
107
|
+
// é a guarda que impede a migração de quebrar um contrato ESCRITO no dia em que
|
|
108
|
+
// a porta puder falhar. Usar `requireScm` aqui seria plantar a violação.
|
|
109
|
+
const { scm: porta, error: erroPorta } = await getScm({ link: resolveScmLink({ owner, repo }), token, deps: { scm } });
|
|
110
|
+
if (erroPorta) return { content: null, state: 'unknown', ref: null, pr: null };
|
|
98
111
|
|
|
99
112
|
let naBase;
|
|
100
113
|
try {
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
// Quais checks do `doctor` fazem sentido para ESTE fornecedor — RFC-006 §7.4/§7.5,
|
|
2
|
+
// Fase 2 bloco G. Função PURA, zero imports.
|
|
3
|
+
//
|
|
4
|
+
// ── O problema que isto resolve ──────────────────────────────────────────────
|
|
5
|
+
//
|
|
6
|
+
// O `doctor` tem 15 checks, e vários diagnosticam coisas que só existem no GitHub:
|
|
7
|
+
// variável de repositório, permissão de workflow, proteção de branch, Projects v2
|
|
8
|
+
// de organização. Num tracker que não tem essas coisas — e a Fase 2 existe para que
|
|
9
|
+
// haja um — esses checks não podem sair como FALHA: o fornecedor está correto, é o
|
|
10
|
+
// diagnóstico que não se aplica.
|
|
11
|
+
//
|
|
12
|
+
// Mas também não podem sair como OK. "Está tudo bem" e "não olhei" com a mesma cara
|
|
13
|
+
// é a degradação que esta base persegue há sete blocos, e num comando de diagnóstico
|
|
14
|
+
// é pior: o `doctor` existe para o usuário confiar no que ele diz. Daí o status
|
|
15
|
+
// `skip`, com símbolo próprio e o MOTIVO no detalhe.
|
|
16
|
+
//
|
|
17
|
+
// ── Por que capability, e não `kind` ────────────────────────────────────────
|
|
18
|
+
//
|
|
19
|
+
// `if (kind === 'github')` no meio de um check recria por dentro o acoplamento que
|
|
20
|
+
// a Fase 1 desmontou — e `test/ports-boundary.test.mjs` reprova o padrão. O que
|
|
21
|
+
// decide é a capability declarada: `variables === 'repo'`, `automation !== 'none'`,
|
|
22
|
+
// `boardProvisioning === 'create'`. Um fornecedor novo não precisa ser conhecido
|
|
23
|
+
// aqui; precisa declarar o que faz.
|
|
24
|
+
//
|
|
25
|
+
// ── O que este arquivo NÃO resolve ──────────────────────────────────────────
|
|
26
|
+
//
|
|
27
|
+
// `doctor.mjs` segue com 14 chamadas de Octokit CRU (secrets do Actions, membership
|
|
28
|
+
// de org, permissões de workflow, proteção de branch) e por isso continua na
|
|
29
|
+
// allowlist da barreira. O gating impede que elas sejam apresentadas como falha de
|
|
30
|
+
// um fornecedor que não as tem; ele NÃO as remove. O lugar delas é o `verify()` de
|
|
31
|
+
// cada plugin, que já está no contrato — e é isso que tira a entrada da allowlist.
|
|
32
|
+
// Fica para a leva 2 do bloco G, porque mover diagnóstico de 1728 linhas é trabalho
|
|
33
|
+
// próprio, e o risco §6.1 do plano é justamente apressar isso e acabar
|
|
34
|
+
// acrescentando 14 operações GitHub-only ao contrato.
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Requisito de capability de um check, na forma `<porta>.<caminho><op><valor>`.
|
|
38
|
+
*
|
|
39
|
+
* Escrito como STRING e não como função para que a tabela seja legível de uma vez:
|
|
40
|
+
* o que interessa a quem lê o `doctor` é quais checks dependem de quê, e uma tabela
|
|
41
|
+
* de closures esconde isso.
|
|
42
|
+
*
|
|
43
|
+
* @typedef {string} Requisito
|
|
44
|
+
*/
|
|
45
|
+
|
|
46
|
+
/** Operadores aceitos, do mais específico para o menos. */
|
|
47
|
+
const OPERADORES = [
|
|
48
|
+
['!==', (a, b) => a !== b],
|
|
49
|
+
['===', (a, b) => a === b],
|
|
50
|
+
];
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Lê um caminho pontilhado (`pullRequests.draft`) num objeto (função PURA).
|
|
54
|
+
*/
|
|
55
|
+
function valorEm(obj, caminho) {
|
|
56
|
+
return caminho.split('.').reduce((atual, chave) => (atual == null ? undefined : atual[chave]), obj);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* O requisito está satisfeito? (função PURA)
|
|
61
|
+
*
|
|
62
|
+
* @param {Requisito} requisito ex.: `scm.variables === 'repo'`
|
|
63
|
+
* @param {{tracker?: object, scm?: object}} capabilities as declaradas por porta
|
|
64
|
+
* @returns {{ok: boolean, motivo: string|null}} `motivo` preenchido quando NÃO ok
|
|
65
|
+
*/
|
|
66
|
+
export function avaliarRequisito(requisito, capabilities = {}) {
|
|
67
|
+
const texto = String(requisito).trim();
|
|
68
|
+
const op = OPERADORES.find(([sinal]) => texto.includes(sinal));
|
|
69
|
+
if (!op) return { ok: false, motivo: `requisito sem operador reconhecido: "${texto}"` };
|
|
70
|
+
|
|
71
|
+
const [sinal, compara] = op;
|
|
72
|
+
const [esquerda, direita] = texto.split(sinal).map(x => x.trim());
|
|
73
|
+
const [porta, ...resto] = esquerda.split('.');
|
|
74
|
+
const caminho = resto.join('.');
|
|
75
|
+
if (!porta || !caminho) {
|
|
76
|
+
return { ok: false, motivo: `requisito sem porta e caminho: "${texto}"` };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const declaradas = capabilities[porta];
|
|
80
|
+
// Porta ausente é diferente de capability ausente: significa que nem deu para
|
|
81
|
+
// construir a porta (plugin faltando, config incompleta). O check é pulado, e o
|
|
82
|
+
// motivo diz QUAL das duas coisas aconteceu — senão o usuário procura no lugar
|
|
83
|
+
// errado.
|
|
84
|
+
if (!declaradas) {
|
|
85
|
+
return { ok: false, motivo: `a porta de ${porta} não pôde ser consultada` };
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const esperado = direita.replace(/^['"]|['"]$/g, '');
|
|
89
|
+
const atual = valorEm(declaradas, caminho);
|
|
90
|
+
// `true`/`false` chegam como palavra na string do requisito.
|
|
91
|
+
const alvo = esperado === 'true' ? true : esperado === 'false' ? false : esperado;
|
|
92
|
+
if (compara(atual, alvo)) return { ok: true, motivo: null };
|
|
93
|
+
|
|
94
|
+
return {
|
|
95
|
+
ok: false,
|
|
96
|
+
motivo: `este fornecedor declara \`${caminho}\` = ${JSON.stringify(atual)}, `
|
|
97
|
+
+ `e o check vale para ${sinal === '===' ? '' : 'qualquer valor exceto '}${JSON.stringify(alvo)}`,
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* O check deve rodar? (função PURA)
|
|
103
|
+
*
|
|
104
|
+
* Um check SEM `requires` roda sempre — é o caso da maioria, que diagnostica coisa
|
|
105
|
+
* local (arquivos, config, IA) e não depende de fornecedor.
|
|
106
|
+
*
|
|
107
|
+
* Com vários requisitos, TODOS têm de valer: um check que precisa de variável de
|
|
108
|
+
* repositório E de automação não diz nada útil com metade.
|
|
109
|
+
*
|
|
110
|
+
* @param {{name?: string, requires?: Requisito[]}} check
|
|
111
|
+
* @param {{tracker?: object, scm?: object}} capabilities
|
|
112
|
+
* @returns {{roda: boolean, motivo: string|null}}
|
|
113
|
+
*/
|
|
114
|
+
export function decidirCheck(check, capabilities = {}) {
|
|
115
|
+
const requisitos = check?.requires;
|
|
116
|
+
if (!Array.isArray(requisitos) || requisitos.length === 0) {
|
|
117
|
+
return { roda: true, motivo: null };
|
|
118
|
+
}
|
|
119
|
+
for (const requisito of requisitos) {
|
|
120
|
+
const { ok, motivo } = avaliarRequisito(requisito, capabilities);
|
|
121
|
+
if (!ok) return { roda: false, motivo };
|
|
122
|
+
}
|
|
123
|
+
return { roda: true, motivo: null };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Roda a lista de checks respeitando o `requires` de cada um.
|
|
128
|
+
*
|
|
129
|
+
* Extraída de `doctor()` porque lá ela é INTESTÁVEL: o comando tem 1728 linhas, 15
|
|
130
|
+
* checks e rede em quase todos. A mutação do bloco G mostrou o custo disso — tirar o
|
|
131
|
+
* motivo do check pulado, e mesmo IGNORAR o gating por inteiro, sobrevivia à suíte.
|
|
132
|
+
*
|
|
133
|
+
* Nunca lança: cada check é best-effort, e um que estoure vira "não verificável".
|
|
134
|
+
* Derrubar o `doctor` por causa de um check é o contrário do que ele existe para
|
|
135
|
+
* fazer — diagnosticar ambiente quebrado.
|
|
136
|
+
*
|
|
137
|
+
* @param {Array<Function & {requires?: string[]}>} checks
|
|
138
|
+
* @param {object} ctx contexto compartilhado dos checks
|
|
139
|
+
* @param {{tracker?: object, scm?: object}} capabilities
|
|
140
|
+
* @returns {Promise<Array<{name: string, status: string, detail?: string}>>}
|
|
141
|
+
*/
|
|
142
|
+
export async function rodarChecks(checks, ctx, capabilities = {}) {
|
|
143
|
+
const resultados = [];
|
|
144
|
+
for (const check of checks || []) {
|
|
145
|
+
const nome = String(check?.name || 'check').replace(/^check/, '');
|
|
146
|
+
const { roda, motivo } = decidirCheck(check, capabilities);
|
|
147
|
+
if (!roda) {
|
|
148
|
+
// O MOTIVO vai no detalhe, e é ele que separa "este fornecedor não faz isso"
|
|
149
|
+
// de "não consegui olhar". Sem ele, `○` é um símbolo sem informação.
|
|
150
|
+
resultados.push({
|
|
151
|
+
name: nome,
|
|
152
|
+
status: 'skip',
|
|
153
|
+
detail: `Não se aplica a este fornecedor: ${motivo}`,
|
|
154
|
+
});
|
|
155
|
+
continue;
|
|
156
|
+
}
|
|
157
|
+
try {
|
|
158
|
+
resultados.push(await check(ctx));
|
|
159
|
+
} catch (err) {
|
|
160
|
+
resultados.push({
|
|
161
|
+
name: nome,
|
|
162
|
+
status: 'warn',
|
|
163
|
+
detail: `Check falhou inesperadamente: ${err.message}`,
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
return resultados;
|
|
168
|
+
}
|
|
@@ -111,7 +111,7 @@ export async function applyBoardMoves({
|
|
|
111
111
|
try {
|
|
112
112
|
// PROJECT_TOKEN é a credencial do board — ver a tabela em
|
|
113
113
|
// src/plugins/tracker-github-projects/index.mjs.
|
|
114
|
-
const { tracker, error } = openTracker({
|
|
114
|
+
const { tracker, error } = await openTracker({
|
|
115
115
|
token, projectToken: process.env.PROJECT_TOKEN || token, cwd,
|
|
116
116
|
tracker: trackerInjetado,
|
|
117
117
|
});
|