forjajs 1.1.5 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +50 -0
- package/README.en.md +310 -0
- package/README.md +37 -6
- package/bin/forja.mjs +3 -3
- package/boilerplates/06-clean-arch/README.md +48 -0
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
- package/boilerplates/06-clean-arch/backend/package.json +43 -0
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
- package/boilerplates/README.md +20 -0
- package/docs/personas/architect/README.md +4 -4
- package/docs/personas/developer/README.md +3 -3
- package/docs/personas/qa/README.md +3 -3
- package/docs/quick-reference.md +9 -9
- package/docs/structure.md +3 -3
- package/lib/core/checks.mjs +20 -3
- package/lib/core/doc-graph.mjs +231 -0
- package/lib/core/health.mjs +131 -29
- package/lib/core/registry.mjs +23 -0
- package/lib/core/release.mjs +48 -8
- package/lib/templates/harness/code-intel.mjs +2 -2
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
- package/package.json +8 -1
- package/scripts/agent-harness.mjs +7 -5
- package/scripts/context-ops.mjs +7 -4
- package/scripts/dev.mjs +2 -2
- package/scripts/hook-guard-paths.mjs +1 -0
- package/scripts/hook-user-prompt.mjs +1 -1
- package/scripts/spec-cli.mjs +4 -3
- package/scripts/tools-doctor.mjs +1 -1
- package/specs/clean-arch-boilerplate/plan.md +137 -0
- package/specs/clean-arch-boilerplate/spec.md +121 -0
- package/specs/clean-arch-boilerplate/tasks.md +70 -0
- package/specs/coerencia-do-sistema/plan.md +155 -0
- package/specs/coerencia-do-sistema/spec.md +15 -14
- package/specs/coerencia-do-sistema/tasks.md +115 -0
- package/specs/ts-migration/plan.md +188 -0
- package/specs/ts-migration/spec.md +119 -0
- package/specs/ts-migration/tasks.md +110 -0
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Plan: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Criado em**: 2026-07-15
|
|
6
|
+
|
|
7
|
+
> Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
|
|
8
|
+
|
|
9
|
+
## 1. Abordagem técnica
|
|
10
|
+
|
|
11
|
+
Três checks novos no catálogo de `health.mjs`, no molde dos que já existem (`runtime-deps`,
|
|
12
|
+
`mcp-json`): `scope: repo`, guardados por `isFrameworkRepo(env)`, cada um nomeando arquivo, linha e
|
|
13
|
+
correção. **Nenhuma máquina nova** — o runner de `checks.mjs` já roda tudo isso.
|
|
14
|
+
|
|
15
|
+
O que é genuinamente novo é a **leitura da documentação como dado**. Hoje o `health.mjs` lê código
|
|
16
|
+
(imports, `package.json`, `.mcp.json`); agora precisa ler os `.md` e extrair duas coisas: comandos
|
|
17
|
+
citados e links relativos. Isso vira `lib/core/doc-graph.mjs` — um scanner puro, sem opinião sobre
|
|
18
|
+
severidade, testável isoladamente. Os três checks são finos: chamam o scanner e comparam com a
|
|
19
|
+
verdade (o registry, o sistema de arquivos).
|
|
20
|
+
|
|
21
|
+
O ponto que decide se a spec vale a pena é o **AC-2**: a allowlist de comandos do projeto gerado
|
|
22
|
+
tem que ser *derivada*, não escrita. Confirmei em campo que dá: parsear o bloco `"scripts"` dos
|
|
23
|
+
`lib/generators/*.js` produz exatamente `start:dev`, `test:cov`, `memory:db:*` etc. — os 7 falsos
|
|
24
|
+
positivos que a auditoria manual pegou. Lista manual mente com o tempo; a derivada acompanha o
|
|
25
|
+
gerador sozinha.
|
|
26
|
+
|
|
27
|
+
## 2. Módulos afetados
|
|
28
|
+
|
|
29
|
+
| Caminho | Mudança | Risco |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `lib/core/doc-graph.mjs` | **criar** — scanner puro: cita comandos, coleta links, deriva allowlist | M |
|
|
32
|
+
| `lib/core/health.mjs` | editar — 3 checks novos no `CHECKS[]` | B |
|
|
33
|
+
| `test/doc-graph.test.js` | **criar** — o scanner, isolado | B |
|
|
34
|
+
| `test/health.test.js` | editar — os 3 checks nos dois estados, incluindo o falso positivo do AC-2 | B |
|
|
35
|
+
| `docs/token-optimization.md` etc. | corrigir o que o check acusar (já limpo na v1.1.4, mas o gate é quem confirma) | B |
|
|
36
|
+
| `README`/`docs` | documentar `memory:extract` (AC-10) | B |
|
|
37
|
+
| `memory/90-decisions/0025-*.md` | **criar** — ADR | B |
|
|
38
|
+
|
|
39
|
+
Risco no `doc-graph.mjs`, não no `health.mjs`: os checks são triviais; a dificuldade toda é o
|
|
40
|
+
scanner não gerar falso positivo. Um `docs-commands` que acusa demais reprova a documentação
|
|
41
|
+
inteira e é desligado no primeiro dia — pior que não existir.
|
|
42
|
+
|
|
43
|
+
## 3. Diagrama de fluxo
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
tools:doctor (scope: repo)
|
|
47
|
+
│
|
|
48
|
+
▼
|
|
49
|
+
┌──────────────── lib/core/doc-graph.mjs ────────────────┐
|
|
50
|
+
│ scanDocs(env) → [{ file, line, command }] │ citações forja/npm run
|
|
51
|
+
│ scanLinks(env) → [{ file, line, target }] │ links markdown relativos
|
|
52
|
+
│ projectCommands(env) → Set<string> │ derivada de lib/generators/
|
|
53
|
+
└────────────────────────────────────────────────────────┘
|
|
54
|
+
│ │ │
|
|
55
|
+
▼ ▼ ▼
|
|
56
|
+
docs-commands docs-links commands-documented
|
|
57
|
+
(critical) (warn) (warn)
|
|
58
|
+
citado ∈ registry target existe registry ⊆ citados
|
|
59
|
+
∪ projectCommands nos .md
|
|
60
|
+
│ │ │
|
|
61
|
+
└──────────── Result[] { file, line, detail, fix } ──────────┘
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## 4. Contratos (API/CLI/Schema)
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
// lib/core/doc-graph.mjs — leitura pura, sem juízo de severidade
|
|
68
|
+
|
|
69
|
+
/** Superfícies de instrução escaneadas. docs/archive, boilerplates e specs ficam de fora (§5 D3). */
|
|
70
|
+
export const DOC_SURFACES; // ['docs', 'prompts', '.claude/agents', 'AGENTS.md', 'CLAUDE.md', 'README.md', 'README.en.md', 'DOC-MAP.md']
|
|
71
|
+
|
|
72
|
+
/** Comandos citados como `forja x:y` ou `npm run x:y` em bloco de código. { file, line, command } */
|
|
73
|
+
export function scanCommands(env);
|
|
74
|
+
|
|
75
|
+
/** Links markdown relativos (não http, âncora ignorada). { file, line, target } */
|
|
76
|
+
export function scanLinks(env);
|
|
77
|
+
|
|
78
|
+
/** Allowlist DERIVADA: keys do bloco "scripts" dos geradores. Nunca uma lista literal. */
|
|
79
|
+
export function projectCommands(env); // -> Set<string>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Regex de comando** — casa `(?:forja |npm run )` seguido de um token **com ao menos um `:`**
|
|
83
|
+
(`spec:new`, `code:impact`). O `:` é o discriminador: todo comando do registry o tem, e nenhuma
|
|
84
|
+
prosa (`"forja does X"`) o casa por acidente. Só dentro de bloco/span de código — prosa livre.
|
|
85
|
+
|
|
86
|
+
**Contrato dos checks** (severidade honesta, AC-6):
|
|
87
|
+
|
|
88
|
+
| Check | Severity | Reprova quando | Fix prescrito |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| `docs-commands` | critical | comando citado ∉ registry ∪ `projectCommands` | "renomeie para `<x>` ou remova a citação em `file:line`" |
|
|
91
|
+
| `commands-documented` | warn | comando do registry citado em nenhum `.md` | "documente `<cmd>` em algum `.md` (ou remova do registry)" |
|
|
92
|
+
| `docs-links` | warn | link relativo aponta para inexistente | "crie o alvo ou corrija o link em `file:line`" |
|
|
93
|
+
|
|
94
|
+
## 5. Decisões e alternativas
|
|
95
|
+
|
|
96
|
+
**D1: Scanner puro separado dos checks.** `doc-graph.mjs` lê e devolve dados; os checks julgam.
|
|
97
|
+
Permite testar o parsing (a parte difícil) sem montar o ambiente do doctor, e permite que um quarto
|
|
98
|
+
consumidor use o mesmo scan amanhã. Alternativa rejeitada: lógica de parsing embutida em cada check
|
|
99
|
+
— foi assim que o `runtime-deps` e o `release.mjs` acabaram com dois parsers de import quase iguais.
|
|
100
|
+
|
|
101
|
+
**D2: Allowlist derivada dos geradores (AC-2).** A prova de fogo da spec. `projectCommands(env)`
|
|
102
|
+
parseia o bloco `"scripts"` dos `lib/generators/*.js`. Alternativa rejeitada: lista literal no
|
|
103
|
+
código — é a armadilha do `.gitignore` da SPEC-009, onde a allow-list manual engoliu uma spec em
|
|
104
|
+
silêncio. Uma lista que não acompanha o gerador vira mentira no primeiro comando novo do boilerplate.
|
|
105
|
+
|
|
106
|
+
**D3: Escopo do scan — instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
|
|
107
|
+
`.claude/agents/` e os `.md` de raiz. **Fora**: `docs/archive/` (legado, off-limits), `boilerplates/`
|
|
108
|
+
(é conteúdo do projeto gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/90-*`
|
|
109
|
+
(registro histórico: uma spec ou ADR pode legitimamente citar um comando proposto ou já removido).
|
|
110
|
+
O gate protege o que instrui o agente *agora*, não o que registrou o passado.
|
|
111
|
+
|
|
112
|
+
**D4: `:` como discriminador de comando.** Em vez de tentar entender a gramática do CLI, exijo o
|
|
113
|
+
`:`. Simples, e cobre 42/42 do registry. Um comando futuro sem `:` escaparia — mas hoje nenhum
|
|
114
|
+
existe, e inventar parser de gramática para um caso inexistente é criar o problema que não temos.
|
|
115
|
+
|
|
116
|
+
**D5: `docs-commands` é o único crítico.** Comando fantasma faz o agente agir errado — trava.
|
|
117
|
+
Comando não-documentado e link quebrado atrapalham mas não param ninguém: `warn`. Reprovar release
|
|
118
|
+
por um link quebrado num doc é como o `deps-unused` seria se fosse crítico — ensina o time a ignorar
|
|
119
|
+
o gate.
|
|
120
|
+
|
|
121
|
+
**D6: `memory:extract` — decisão adiada para as tasks.** É o único órfão real. Documentar ou remover
|
|
122
|
+
é chamada de quem conhece o uso dele; o plano não força a mão. O que o plano garante é que, depois,
|
|
123
|
+
o `commands-documented` não deixa nascer um órfão novo.
|
|
124
|
+
|
|
125
|
+
D1, D2 e D3 são estruturais → **ADR-0025**, referenciando ADR-0023/0024 (mesma família de gate,
|
|
126
|
+
terceira fronteira: a instrução) e ADR-0021 (a classe "erra sem avisar").
|
|
127
|
+
|
|
128
|
+
## 6. Dependências
|
|
129
|
+
|
|
130
|
+
- **Specs**: SPEC-009 (`health.mjs`/`checks.mjs` são a base). Já `done`.
|
|
131
|
+
- **Pacotes npm**: **nenhum novo.** `node:fs` e regex. Parsear markdown com um lexer completo seria
|
|
132
|
+
peso morto — precisamos de citações em code-span e links, não de um AST de CommonMark.
|
|
133
|
+
- **Migrações**: nenhuma.
|
|
134
|
+
|
|
135
|
+
## 7. Rollout
|
|
136
|
+
|
|
137
|
+
- [ ] **Ordem**: `doc-graph.mjs` + seus testes primeiro (nada o consome ainda) → os 3 checks →
|
|
138
|
+
rodar o doctor e **corrigir o que ele acusar** → CI já pega de graça (o doctor já é step, ADR-0024).
|
|
139
|
+
- [x] Doc/persona: governança ganha mais um critério; nenhuma persona muda de fluxo.
|
|
140
|
+
- [ ] **Validar o AC-2 de verdade**: adicionar um `"foo:bar"` temporário aos scripts de um gerador e
|
|
141
|
+
confirmar que `docs-commands` **não** passa a exigir `foo:bar` na doc. Se exigir, a derivação
|
|
142
|
+
não está pegando o gerador certo.
|
|
143
|
+
- [ ] O primeiro `npm run tools:doctor` depois disto é o teste real: ele deve passar (a doc já foi
|
|
144
|
+
limpa na v1.1.4), provando que o gate concorda com a correção manual — não inventa trabalho.
|
|
145
|
+
|
|
146
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
147
|
+
|
|
148
|
+
- **`docs-commands` gera um falso positivo crítico.** Se acontecer uma vez com comando legítimo, ele
|
|
149
|
+
é rebaixado a `warn` até o scanner ser corrigido — um crítico que mente é pior que um warning
|
|
150
|
+
honesto, e aqui ele bloquearia o CI de todo mundo.
|
|
151
|
+
- **O scanner fica caro.** Se ler os `.md` todos passar de ~1s, o scan vira lazy/cacheado por mtime —
|
|
152
|
+
mas os checks são `scope: repo`, fora do `SessionStart`, então a folga é grande.
|
|
153
|
+
- **A regra vira desincentivo a documentar.** Se alguém parar de escrever doc para não "brigar com o
|
|
154
|
+
gate", erramos: o gate só cobre citação de *comando*, e isso precisa estar claro na mensagem de
|
|
155
|
+
erro (que aponta a linha e diz "renomeie ou remova a citação", nunca "não escreva").
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Spec: coerencia-do-sistema
|
|
2
2
|
|
|
3
3
|
- **ID**: SPEC-011
|
|
4
|
-
- **Status**:
|
|
4
|
+
- **Status**: done
|
|
5
5
|
- **Owner**: apk
|
|
6
6
|
- **Criado em**: 2026-07-14
|
|
7
7
|
- **Sprint alvo**: S?
|
|
@@ -53,28 +53,29 @@ agente.
|
|
|
53
53
|
|
|
54
54
|
## 4. Critérios de aceite (Definition of Done)
|
|
55
55
|
|
|
56
|
-
- [
|
|
56
|
+
- [x] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
|
|
57
57
|
`forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
|
|
58
58
|
`README.md` existe no registry (ADR-0020).
|
|
59
|
-
- [
|
|
59
|
+
- [x] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
|
|
60
60
|
afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
|
|
61
61
|
dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
|
|
62
62
|
`.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
|
|
63
|
-
- [
|
|
64
|
-
mencionado em pelo menos um `.md` versionado. Hoje
|
|
65
|
-
|
|
63
|
+
- [x] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
|
|
64
|
+
mencionado em pelo menos um `.md` versionado. Hoje 1 de 42 não é (`memory:extract`) — a
|
|
65
|
+
reescrita canônica do README na v1.1.5 já documentou `workspace:project:check`.
|
|
66
|
+
- [x] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
|
|
66
67
|
versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
|
|
67
|
-
- [
|
|
68
|
+
- [x] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
|
|
68
69
|
doctor na matriz (ADR-0024).
|
|
69
|
-
- [
|
|
70
|
+
- [x] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
|
|
70
71
|
agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
|
|
71
72
|
gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
|
|
72
|
-
- [
|
|
73
|
+
- [x] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
|
|
73
74
|
está errado" sem dizer onde é só mais um step obscuro.
|
|
74
|
-
- [
|
|
75
|
-
- [
|
|
76
|
-
- [
|
|
77
|
-
|
|
75
|
+
- [x] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
|
|
76
|
+
- [x] AC-9: ADR-0025 registrando a decisão.
|
|
77
|
+
- [x] AC-10: O comando órfão restante (`memory:extract`) é documentado — ou removido do registry,
|
|
78
|
+
se não servir mais. Capacidade obscura é capacidade morta.
|
|
78
79
|
|
|
79
80
|
## 5. Escopo
|
|
80
81
|
|
|
@@ -82,7 +83,7 @@ agente.
|
|
|
82
83
|
- `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
|
|
83
84
|
- `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
|
|
84
85
|
- Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
|
|
85
|
-
- Documentar
|
|
86
|
+
- Documentar o comando órfão restante (`memory:extract`), ou removê-lo.
|
|
86
87
|
- ADR-0025 + testes.
|
|
87
88
|
|
|
88
89
|
**Fora** (explícito):
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Tasks: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: done
|
|
6
|
+
- **Criado em**: 2026-07-15
|
|
7
|
+
|
|
8
|
+
> Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
|
|
9
|
+
|
|
10
|
+
Ordem do plano §7: o scanner e seus testes primeiro (nada o consome), depois os três checks, depois
|
|
11
|
+
rodar o doctor e corrigir o que ele acusar. O CI pega de graça — `tools:doctor` já é step (ADR-0024).
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## T1 — `doc-graph.mjs`: o scanner puro
|
|
16
|
+
- **Owner**: Worker
|
|
17
|
+
- **Estimativa**: M
|
|
18
|
+
- **Depende de**: —
|
|
19
|
+
- **Paths**: `lib/core/doc-graph.mjs`, `test/doc-graph.test.js`
|
|
20
|
+
- **Escopo**: leitura pura, zero juízo de severidade. É a parte difícil — todo o risco da spec mora
|
|
21
|
+
aqui, no não-gerar-falso-positivo.
|
|
22
|
+
- **Done quando**:
|
|
23
|
+
- [ ] `scanCommands(env)` devolve `{ file, line, command }` para cada `forja <cmd>` / `npm run <cmd>`
|
|
24
|
+
onde `<cmd>` tem ao menos um `:` (o discriminador do plano §D4)
|
|
25
|
+
- [ ] `scanLinks(env)` devolve `{ file, line, target }` para links markdown **relativos**; ignora
|
|
26
|
+
`http(s)://` e âncoras (`#sec`). Link para diretório (`memory/90-decisions/`) conta como alvo
|
|
27
|
+
- [ ] `projectCommands(env)` **deriva** a allowlist das keys do bloco `"scripts"` dos
|
|
28
|
+
`lib/generators/*.js` — nunca uma lista literal (plano §D2). Retorna Set
|
|
29
|
+
- [ ] `DOC_SURFACES` exportado; escaneia `docs/` (menos `archive/`), `prompts/`, `.claude/agents/`
|
|
30
|
+
e os `.md` de raiz. **Não** varre `boilerplates/`, `specs/`, `memory/` (plano §D3)
|
|
31
|
+
- [ ] `env` injetável (`{ root, fs }`) no padrão de `checks.mjs`, para os testes não tocarem o disco
|
|
32
|
+
- [ ] `test/doc-graph.test.js`: fixtures cobrindo comando com/sem `:`, link relativo/http/âncora/
|
|
33
|
+
diretório, e a derivação pegando um `"foo:bar"` de um gerador de fixture
|
|
34
|
+
|
|
35
|
+
## T2 — Check `docs-commands` (critical)
|
|
36
|
+
- **Owner**: Worker
|
|
37
|
+
- **Estimativa**: P
|
|
38
|
+
- **Depende de**: T1
|
|
39
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
40
|
+
- **Done quando**:
|
|
41
|
+
- [ ] `scope: 'repo'`, guardado por `isFrameworkRepo(env)` — não roda numa instalação `forjajs`
|
|
42
|
+
- [ ] Reprova (critical) quando comando citado ∉ `registry ∪ projectCommands` (AC-1, AC-2)
|
|
43
|
+
- [ ] `detail` nomeia `file:line` e o comando ofensor; `fix` diz "renomeie ou remova a citação"
|
|
44
|
+
— nunca "não escreva" (kill criteria do plano §8)
|
|
45
|
+
- [ ] **Teste do falso positivo (AC-2, a prova de fogo)**: doc citando `npm run start:dev` (comando
|
|
46
|
+
do projeto gerado) **não** reprova; doc citando `forja fantasma:x` reprova
|
|
47
|
+
- [ ] Teste: comando real do registry citado passa
|
|
48
|
+
|
|
49
|
+
## T3 — Checks `commands-documented` e `docs-links` (warn)
|
|
50
|
+
- **Owner**: Worker
|
|
51
|
+
- **Estimativa**: P
|
|
52
|
+
- **Depende de**: T1
|
|
53
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
54
|
+
- **Done quando**:
|
|
55
|
+
- [ ] `commands-documented` (**warn**): comando do registry citado em nenhuma superfície → aviso
|
|
56
|
+
com "documente em algum `.md` ou remova do registry" (AC-3). `worstStatus` não escala warn
|
|
57
|
+
- [ ] `docs-links` (**warn**): link relativo sem alvo → aviso com `file:line` e o alvo (AC-4)
|
|
58
|
+
- [ ] Ambos `scope: 'repo'`, guardados por `isFrameworkRepo`
|
|
59
|
+
- [ ] Teste de cada um nos dois estados (são/quebrado)
|
|
60
|
+
- [ ] Teste garantindo que os três checks novos são `skipped` fora do repo do framework
|
|
61
|
+
|
|
62
|
+
## T4 — Rodar o gate e reconciliar a realidade
|
|
63
|
+
- **Owner**: Worker
|
|
64
|
+
- **Estimativa**: P
|
|
65
|
+
- **Depende de**: T2, T3
|
|
66
|
+
- **Paths**: `docs/`, `README.md`/`README.en.md`, conforme o gate acusar
|
|
67
|
+
- **Escopo**: o primeiro `tools:doctor` com os checks ligados é o teste real — ele deve **concordar
|
|
68
|
+
com as correções manuais** já feitas (a doc foi limpa na v1.1.4), não inventar trabalho novo.
|
|
69
|
+
- **Done quando**:
|
|
70
|
+
- [ ] `forja tools:doctor` roda com os 3 checks e o núcleo fica **verde ou só com warns**
|
|
71
|
+
- [ ] Qualquer `docs-commands` crítico remanescente é corrigido na fonte (renomear/remover citação)
|
|
72
|
+
- [ ] AC-10: `memory:extract` — documentar numa superfície escaneada **ou** remover do registry.
|
|
73
|
+
Decisão de quem conhece o uso; qualquer das duas fecha o `commands-documented` warn
|
|
74
|
+
- [ ] `docs-links` warns zerados ou reduzidos a alvos que se decide criar depois (registrar quais)
|
|
75
|
+
|
|
76
|
+
## T5 — Validação executável do AC-2
|
|
77
|
+
- **Owner**: Worker
|
|
78
|
+
- **Estimativa**: P
|
|
79
|
+
- **Depende de**: T2
|
|
80
|
+
- **Paths**: `test/health.test.js` (ou um teste dedicado)
|
|
81
|
+
- **Escopo**: garantir que a derivação é *real*, não que o teste passou por sorte.
|
|
82
|
+
- **Done quando**:
|
|
83
|
+
- [ ] Teste que injeta um `"foo:bar"` no bloco `scripts` de um gerador de fixture e confirma que
|
|
84
|
+
`docs-commands` passa a **aceitar** `foo:bar` na doc — provando que a allowlist segue o
|
|
85
|
+
gerador, não uma lista congelada (plano §7)
|
|
86
|
+
|
|
87
|
+
## T6 — ADR-0025 e CI
|
|
88
|
+
- **Owner**: SDD Architect + Worker
|
|
89
|
+
- **Estimativa**: P
|
|
90
|
+
- **Depende de**: T2, T3, T4
|
|
91
|
+
- **Paths**: `memory/90-decisions/0025-*.md`, `.github/workflows/ci.yml` (verificar)
|
|
92
|
+
- **Done quando**:
|
|
93
|
+
- [ ] ADR-0025 registra D1 (scanner puro), D2 (allowlist derivada) e D3 (escopo = instrução, não
|
|
94
|
+
histórico); referencia ADR-0023/0024 (a família de gate, terceira fronteira) e ADR-0021
|
|
95
|
+
- [ ] Confirmar que o CI **já** exercita os checks via `tools:doctor` (step do ADR-0024) — não deve
|
|
96
|
+
precisar de mudança no workflow; se precisar, ajustar
|
|
97
|
+
- [ ] `npm test` verde, `spec:check` verde
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Validação final
|
|
102
|
+
- [ ] Renomear um comando do registry num teste e confirmar que `docs-commands` **acusa** a doc que
|
|
103
|
+
ainda usa o nome antigo — a métrica de sucesso da spec (renomear vira ato detectável)
|
|
104
|
+
- [ ] Suíte completa verde; `tools:doctor` verde/warn; spec → `done`
|
|
105
|
+
|
|
106
|
+
## Nota de implementação — o code-span é endurecimento, não requisito
|
|
107
|
+
O plano §4 menciona "só dentro de bloco/span de código". A auditoria manual que originou esta spec
|
|
108
|
+
usou **scan de arquivo inteiro** + discriminador `:` e funcionou — os únicos falsos positivos foram
|
|
109
|
+
os comandos do projeto gerado, tratados pela allowlist (T2). Começar pelo scan de arquivo inteiro; só
|
|
110
|
+
adicionar consciência de code-span **se** T2/T4 revelarem um falso positivo que o `:` não filtre. Não
|
|
111
|
+
construir parser de markdown para um problema que ainda não apareceu (plano §6).
|
|
112
|
+
|
|
113
|
+
## Handoffs entre agentes
|
|
114
|
+
Worker (T1-T5), SDD Architect (T6). Handoff a cada fronteira via `forja agent:route` — 7 campos
|
|
115
|
+
(ADR-0005).
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# Plan: ts-migration
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-07-18
|
|
6
|
+
|
|
7
|
+
> Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
|
|
8
|
+
|
|
9
|
+
## 1. Abordagem técnica
|
|
10
|
+
|
|
11
|
+
O nó da migração não é renomear `.mjs → .ts` — é **como o core acha o script de um comando em dois
|
|
12
|
+
runtimes**. Hoje `bin/forja.mjs:118` faz `spawnSync('node', [path.join(root, cmd.node)])`, e o
|
|
13
|
+
registry guarda a extensão literal (`scripts/tools-doctor.mjs`). Em dev o alvo é `.ts`; no pacote
|
|
14
|
+
publicado é `dist/scripts/tools-doctor.js`. O mesmo registry não pode cravar as duas.
|
|
15
|
+
|
|
16
|
+
A saída é **desacoplar o registry da extensão**: a entrada passa a ser `scripts/tools-doctor` (sem
|
|
17
|
+
extensão), e o core resolve o arquivo real tentando `.ts → .js → .mjs` conforme o que existe. Em dev
|
|
18
|
+
acha o `.ts`; no publicado acha o `.js` sob `dist/`. Isso resolve o runtime duplo com uma mudança
|
|
19
|
+
pequena e contida, e ainda limpa o registry.
|
|
20
|
+
|
|
21
|
+
Tudo o mais é disciplina: `checkJs` primeiro para achar os erros de tipo com os arquivos ainda
|
|
22
|
+
rodando como `.mjs`, depois renomear **leaf-first** com a suíte verde a cada passo. A rede de
|
|
23
|
+
segurança é que a migração não muda semântica — se os 109 testes passam sem edição de lógica, a
|
|
24
|
+
renomeação não quebrou nada.
|
|
25
|
+
|
|
26
|
+
## 2. Módulos afetados
|
|
27
|
+
|
|
28
|
+
| Caminho | Mudança | Risco |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| `tsconfig.json` | **criar** — `checkJs` on-ramp, depois `outDir: dist`, `.d.ts` | M |
|
|
31
|
+
| `lib/core/registry.mjs` → `.ts` | `node:` sem extensão; tipos `Command`/`Domain` | **A** |
|
|
32
|
+
| `bin/forja.mjs` → `.ts` | resolver extension-agnostic (`.ts→.js→.mjs`) no dispatch | **A** |
|
|
33
|
+
| `lib/core/checks.mjs` → `.ts` | `Check`/`Probe`/`Result`/`Env` viram tipos reais | M |
|
|
34
|
+
| `lib/core/{health,release,doc-graph,workspace}.mjs` → `.ts` | tipam contra `checks.ts` | M |
|
|
35
|
+
| `lib/core/release` | `build-fresh` novo; `smoke-commands` usa o `bin` do package.json, não path fixo | M |
|
|
36
|
+
| `scripts/*.{mjs,js}` → `.ts` | ~20 arquivos, leaf-first; hooks incluídos | M |
|
|
37
|
+
| `lib/generators/*.js` → `.ts` | tipa a assinatura; o **conteúdo** (template string) fica string | B |
|
|
38
|
+
| `package.json` | `main`/`types`/`exports`/`bin` → `dist/`; `build`; `files[]` dist; `prepublishOnly` | **A** |
|
|
39
|
+
| `.claude/settings.json` | hooks → `.ts` (dev roda nativo) | B |
|
|
40
|
+
| `.github/workflows/ci.yml` | steps `types:check` e `build` | B |
|
|
41
|
+
| `memory/90-decisions/0026-*.md` | **criar** — ADR | B |
|
|
42
|
+
|
|
43
|
+
Os três `A` são o registry, o dispatch e o `package.json` — a tríade que decide se o comando roda
|
|
44
|
+
nos dois runtimes. Tudo passa por eles.
|
|
45
|
+
|
|
46
|
+
## 3. Diagrama de fluxo
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
DEV (Node 26, sem build) PUBLICADO (Node >=20, dist/)
|
|
50
|
+
────────────────────── ────────────────────────────
|
|
51
|
+
node bin/forja.ts forja → dist/bin/forja.js
|
|
52
|
+
│ │
|
|
53
|
+
│ registry: 'scripts/tools-doctor' │ (mesma entrada, sem extensão)
|
|
54
|
+
▼ ▼
|
|
55
|
+
resolve('<root>/scripts/tools-doctor')
|
|
56
|
+
tenta .ts → .js → .mjs
|
|
57
|
+
│ dev: acha .ts │ publicado: root=dist/, acha dist/scripts/tools-doctor.js
|
|
58
|
+
▼ ▼
|
|
59
|
+
spawn node <arquivo resolvido> spawn node <arquivo resolvido>
|
|
60
|
+
|
|
61
|
+
build (só p/ publicar): tsc rootDir=. outDir=dist → dist/ espelha a árvore
|
|
62
|
+
build-fresh (release:check): recompila e compara com dist/ commitado → reprova se difere
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## 4. Contratos (API/CLI/Schema)
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
// lib/core/registry.ts
|
|
69
|
+
export interface Command {
|
|
70
|
+
domain: string;
|
|
71
|
+
desc: string;
|
|
72
|
+
node?: string; // caminho SEM extensão, relativo à raiz (dev) / a dist/ (publicado)
|
|
73
|
+
bin?: string;
|
|
74
|
+
args?: string[];
|
|
75
|
+
}
|
|
76
|
+
export const COMMANDS: Record<string, Command>;
|
|
77
|
+
|
|
78
|
+
// lib/core/checks.ts — os contratos que hoje são @typedef viram tipos verificados
|
|
79
|
+
export type Severity = 'critical' | 'warn';
|
|
80
|
+
export type Status = 'ok' | 'warn' | 'fail' | 'skipped';
|
|
81
|
+
export interface Probe { status: Status; detail: string; fix?: string | null; }
|
|
82
|
+
export interface Check { id: string; title: string; severity: Severity; scope?: string;
|
|
83
|
+
dependsOn?: string; probe: (env: Env) => Probe | Promise<Probe>; }
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Resolução de script (o coração)** — `bin/forja.ts` calcula `root = dirname(selfPath)/..`
|
|
87
|
+
(dev: repo; publicado: `dist/`) e resolve `cmd.node` tentando as extensões na ordem `.ts, .js,
|
|
88
|
+
.mjs`. A primeira que existe vence. Sem extensão no registry, sem `if (isDev)`.
|
|
89
|
+
|
|
90
|
+
**`package.json`**:
|
|
91
|
+
|
|
92
|
+
| Campo | Valor |
|
|
93
|
+
|---|---|
|
|
94
|
+
| `bin.forja` | `dist/bin/forja.js` |
|
|
95
|
+
| `main` / `types` | `dist/lib/index.js` / `.d.ts` |
|
|
96
|
+
| `files[]` | troca `bin/ lib/ scripts/` por `dist/` (o resto — memory/, docs/, boilerplates/ — fica) |
|
|
97
|
+
| `scripts.build` | `tsc` |
|
|
98
|
+
| `scripts.prepublishOnly` | `npm run build && node bin/forja.ts release:check -- --publish` |
|
|
99
|
+
|
|
100
|
+
## 5. Decisões e alternativas
|
|
101
|
+
|
|
102
|
+
**D1: Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
|
|
103
|
+
`dist/lib`, `dist/scripts`. Alternativa rejeitada: mover a fonte para `src/`. Isso trocaria todo
|
|
104
|
+
import, todo path do registry, os hooks do `settings.json`, o `files[]` e as smoke-commands do
|
|
105
|
+
release — blast radius enorme, contra o "verde contínuo". O layout plano mantém a migração mecânica.
|
|
106
|
+
|
|
107
|
+
**D2: Registry sem extensão + resolver (o coração).** `node: 'scripts/tools-doctor'`; o core tenta
|
|
108
|
+
`.ts→.js→.mjs`. Desacopla o registry do runtime e limpa a entrada. Alternativa rejeitada: guardar
|
|
109
|
+
`.js` e exigir build em dev — mata o "roda sem build" (o NFR inegociável). Alternativa rejeitada:
|
|
110
|
+
dois registries — é como se chega a duas verdades divergentes, o defeito que a SPEC-009 matou.
|
|
111
|
+
|
|
112
|
+
**D3: Runtime duplo.** Dev roda `.ts` nativo (confirmado: Node 26 executa `.ts` e `node --test`
|
|
113
|
+
roda `.ts`); publicado roda `dist/.js`. `engines.node` fica `>=20` — por isso publicamos compilado.
|
|
114
|
+
O usuário final não é obrigado a Node novo; o dev sim.
|
|
115
|
+
|
|
116
|
+
**D4: `build-fresh` no `RELEASE_CHECKS`.** Sem ele, a migração reintroduz a classe do ADR-0021: um
|
|
117
|
+
`dist/` que mente sobre o `src/`. O gate recompila num temp e faz diff com o `dist/` commitado;
|
|
118
|
+
diferente → reprova com `npm run build`. É o `memory-fresh`, um nível abaixo.
|
|
119
|
+
|
|
120
|
+
**D5: `checkJs` antes de renomear; leaf-first depois.** Ordem por dependência:
|
|
121
|
+
`workspace → checks → registry → doc-graph → health/release → scripts → hooks → bin → generators`.
|
|
122
|
+
Verde a cada arquivo. Alternativa rejeitada: renomear tudo e consertar no fim — big-bang, sinal sujo.
|
|
123
|
+
|
|
124
|
+
**D6: `tsc` com `rewriteRelativeImportExtensions` (TS 5.7+).** A fonte importa `./x.ts`; o `tsc`
|
|
125
|
+
reescreve para `./x.js` no emit. É o mecanismo oficial para fonte-`.ts`-roda-nativo + build. Sem
|
|
126
|
+
ele, os imports estáticos não resolveriam nos dois mundos.
|
|
127
|
+
|
|
128
|
+
**D7: `smoke-commands` do release usa o `bin` do package.json.** Hoje ele monta
|
|
129
|
+
`path.join(pkgDir, 'bin', 'forja.mjs')` — quebraria com `dist/bin/forja.js`. Passa a ler o campo
|
|
130
|
+
`bin`. Correção de robustez que a migração torna obrigatória.
|
|
131
|
+
|
|
132
|
+
**D8: Fase 2 e Fase 3 se fundem (achado da implementação).** O plano tratava renomear (Fase 2) e
|
|
133
|
+
buildar (Fase 3) como fases separadas. Não são: `.ts` **não roda em Node < 22.18**, e o
|
|
134
|
+
`engines.node` é `>=20`. No instante em que a fonte vira `.ts`, um pacote publicado **sem `dist/`**
|
|
135
|
+
quebra para quem está em Node 20/21, e o `release:check` (instalação limpa no CI) reprova. Não
|
|
136
|
+
existe estado intermediário *publicável* meio-renomeado. Então a renomeação e o `dist/` andam
|
|
137
|
+
juntos, mantendo o `release:check` verde o tempo todo. Em dev nada muda (Node 26 roda `.ts`); o
|
|
138
|
+
acoplamento é só na fronteira do publicado. Estratégia de menor risco: **provar o pipeline de build
|
|
139
|
+
+ runtime duplo primeiro** (a parte nova e arriscada), depois a renomeação leaf-first vira grind
|
|
140
|
+
mecânico sobre trilho provado.
|
|
141
|
+
|
|
142
|
+
**D9: Publicar `dist/` desde já desacopla o risco (achado ao provar o pipeline).** O `tsc` emite um
|
|
143
|
+
`dist/` que espelha a árvore, e `node dist/bin/forja.mjs` roda (o `resolveScript` acha
|
|
144
|
+
`dist/scripts/`). A consequência: se o pacote **sempre embarca `dist/`** — mesmo enquanto a fonte
|
|
145
|
+
ainda é `.mjs` (o build vira uma cópia) — o artefato publicado é sempre JS runnable, e o
|
|
146
|
+
acoplamento de Node-floor do D8 **nunca morde**. Então a ordem certa inverte a intuição: primeiro a
|
|
147
|
+
**infra de release** (build → `dist/`, `package.json` apontando para `dist/`, `prepublishOnly`),
|
|
148
|
+
com a fonte ainda `.mjs` — a plumbing de release provada sobre código que não pode quebrar em
|
|
149
|
+
runtime. **Depois** a renomeação `.mjs → .ts` vira mudança **interna**: a fonte muda, o `dist/`
|
|
150
|
+
regenera como `.js`, e o publicado nunca vê `.ts` cru. O `.ts`-não-roda-em-Node-20 deixa de ser
|
|
151
|
+
risco porque o publicado é sempre `dist/`.
|
|
152
|
+
|
|
153
|
+
D2, D3 e D4 são estruturais → **ADR-0026**, referenciando ADR-0021 (o NFR "roda sem build" e a
|
|
154
|
+
classe "dist mente") e ADR-0024 (o gate que ganha o `build-fresh`).
|
|
155
|
+
|
|
156
|
+
## 6. Dependências
|
|
157
|
+
|
|
158
|
+
- **Specs**: SPEC-011 (o catálogo de doc-graph já na main — migra junto). Já `done`.
|
|
159
|
+
- **Pacotes npm**: `typescript` como **devDependency** (≥ 5.7, por D6). Zero dependência de runtime
|
|
160
|
+
nova — o publicado segue só com `better-sqlite3`.
|
|
161
|
+
- **Migrações de dado**: nenhuma.
|
|
162
|
+
|
|
163
|
+
## 7. Rollout
|
|
164
|
+
|
|
165
|
+
- [ ] **Fase 0 — on-ramp.** `tsconfig` com `checkJs, strict, noEmit`; `types:check` no registry e
|
|
166
|
+
no CI. Corrigir os erros com os arquivos ainda `.mjs`. Nada renomeado ainda.
|
|
167
|
+
- [ ] **Fase 1 — resolver.** Trocar o registry para paths sem extensão e o dispatch para o resolver
|
|
168
|
+
`.ts/.js/.mjs`, **ainda em `.mjs`**. Suíte verde. É a mudança de comportamento de menor risco,
|
|
169
|
+
isolada e testável antes de qualquer renomeação.
|
|
170
|
+
- [ ] **Fase 2 — renomear leaf-first.** Um módulo por vez (D5), `npm test` verde a cada um.
|
|
171
|
+
- [ ] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `build-fresh`; `package.json` apontando
|
|
172
|
+
para `dist/`; `prepublishOnly` build→gate. Validar com `release:check --publish` e
|
|
173
|
+
`npm publish --dry-run`.
|
|
174
|
+
- [x] Doc/persona: governança ganha o `build-fresh`; `docs/` e `CONTRIBUTING` ganham o "dev roda
|
|
175
|
+
`.ts`, publicado roda `dist`".
|
|
176
|
+
- [ ] **Prova final**: `release:check` aprova o tarball com `dist/` fresco; reintroduzir um `dist/`
|
|
177
|
+
defasado e confirmar que o `build-fresh` reprova.
|
|
178
|
+
|
|
179
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
180
|
+
|
|
181
|
+
- **O hook passa a exigir build em dev.** Se em algum ponto o `SessionStart` não rodar sem `dist/`,
|
|
182
|
+
o design falhou o NFR inegociável — pausa e reavalia o runtime duplo antes de seguir.
|
|
183
|
+
- **O resolver de extensão fica ambíguo** (um `.ts` e um `.js` do mesmo nome convivendo em dev).
|
|
184
|
+
Mitigação: `.gitignore` do `dist/` em dev + o `build-fresh` garante que dist não anda solto.
|
|
185
|
+
- **`strict` vira um poço sem fundo.** Se a Fase 0 não estabilizar em tempo razoável, afrouxa para
|
|
186
|
+
`strict` incremental (por arquivo via `// @ts-expect-error` pontual), nunca desligando o gate.
|
|
187
|
+
- **A migração começa a mudar comportamento pra agradar o compilador.** Se um teste precisar mudar
|
|
188
|
+
de semântica, parou de ser migração — isola aquela mudança numa spec própria e segue.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Spec: ts-migration
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-012
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-18
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
O framework tem ~8.500 LOC em 38 arquivos, e **os contratos que o sustentam são convenção, não
|
|
13
|
+
código**. A forma de um check (`{ id, severity, probe, fix }`), o handoff de 7 campos (ADR-0005), o
|
|
14
|
+
`Env` injetável, as entradas do registry — nada disso é verificado até rodar. Nesta sessão, três
|
|
15
|
+
frentes seguidas (ADR-0023/0024/0025) fizeram o mesmo movimento: converter conhecimento que vivia em
|
|
16
|
+
prosa num invariante executável. **A migração para TypeScript é esse movimento aplicado aos
|
|
17
|
+
contratos do próprio código** — drift de contrato deixa de ser surpresa em runtime e vira erro de
|
|
18
|
+
compilação.
|
|
19
|
+
|
|
20
|
+
Já há 9 arquivos com `@typedef` de JSDoc: a tipagem manual já começou, só não é verificada. E o repo
|
|
21
|
+
está a meio caminho de `.js → .mjs` (21 vs 16), então já se mexe na camada de módulos.
|
|
22
|
+
|
|
23
|
+
**A tensão que a migração precisa respeitar.** Um princípio carrega o framework desde o ADR-0021: o
|
|
24
|
+
`tools:doctor` e o hook `SessionStart` rodam **sem build e sem `node_modules`**. Foi isso que tornou
|
|
25
|
+
a morte da memória (ABI) sobrevivível e o hook resiliente. Uma migração ingênua ("compila pra
|
|
26
|
+
`dist/`, roda `dist/`") fritaria esse princípio — e pior, reintroduziria a classe que passamos a
|
|
27
|
+
sessão matando: **um `dist/` que mente sobre o `src/`.**
|
|
28
|
+
|
|
29
|
+
## 2. Proposta de valor
|
|
30
|
+
|
|
31
|
+
TypeScript de verdade — tipos exportáveis para quem consome o `forjajs` — **sem** perder o "roda sem
|
|
32
|
+
build" que faz o Forja resiliente, e **sem** deixar o artefato compilado divergir da fonte.
|
|
33
|
+
|
|
34
|
+
## 3. User stories
|
|
35
|
+
|
|
36
|
+
- **Como** quem mantém o framework, **quero** que um `probe` que devolve a forma errada seja **erro
|
|
37
|
+
de compilação**, não bug silencioso, **para que** o contrato dos checks pare de ser convenção.
|
|
38
|
+
- **Como** quem instala `forjajs`, **quero** tipos (`.d.ts`) no pacote, **para que** meu editor
|
|
39
|
+
saiba a forma da API.
|
|
40
|
+
- **Como** agente rodando o hook `SessionStart`, **quero** que ele funcione **sem build e sem
|
|
41
|
+
`node_modules`**, **para que** o diagnóstico sobreviva ao ambiente quebrado (ADR-0021).
|
|
42
|
+
- **Como** quem publica, **quero** que `dist/` desatualizado **reprove** o `release:check`, **para
|
|
43
|
+
que** o pacote publicado nunca minta sobre a fonte.
|
|
44
|
+
|
|
45
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
46
|
+
|
|
47
|
+
- [ ] AC-1: **Runtime duplo.** Em dev e nos hooks, o Forja roda a fonte `.ts` via type-stripping do
|
|
48
|
+
Node (confirmado: Node 26 executa `.ts` nativo). **Zero build em dev.** O pacote publicado
|
|
49
|
+
embarca `dist/` compilado por `tsc`, para o piso `engines.node >= 20`.
|
|
50
|
+
- [ ] AC-2: **`build-fresh` no catálogo `RELEASE_CHECKS`** (ADR-0024): recompila e compara com o
|
|
51
|
+
`dist/` versionado; se `src/` mudou e `dist/` não, **reprova** com `fix: "npm run build"`. O
|
|
52
|
+
artefato compilado não pode ser publicado defasado.
|
|
53
|
+
- [ ] AC-3: **On-ramp por `checkJs` antes de renomear.** `tsconfig` com `checkJs: true, strict: true,
|
|
54
|
+
noEmit` roda sobre os `.mjs` atuais; os erros de tipo são corrigidos **antes** de qualquer
|
|
55
|
+
renomeação. `types:check` vira **npm script** (como `test`) e step do CI — **fora do registry
|
|
56
|
+
publicado**, porque precisa do devDep `typescript` e seria comando quebrado numa instalação
|
|
57
|
+
`forjajs` (a classe da v1.1.3). *(Correção de rota da Fase 0.)*
|
|
58
|
+
- [ ] AC-4: **Contratos tipados.** `Check`, `Probe`, `Result`, `Env`, `Command` (registry) e o
|
|
59
|
+
handoff de 7 campos (ADR-0005) viram tipos reais, não `@typedef` de convenção.
|
|
60
|
+
- [ ] AC-5: `tsc` emite `.d.ts` no `dist/`; o `package.json` aponta `types`/`exports` para eles.
|
|
61
|
+
- [ ] AC-6: **`release:check` cobre o build.** O gate compila antes de empacotar; `prepublishOnly`
|
|
62
|
+
roda build → gate (ordem correta, sem recursão — o gate não dispara `prepack`, ADR-0024).
|
|
63
|
+
- [ ] AC-7: Suíte verde em cada passo da renomeação (leaf-first). O `node --test` roda sobre `.ts`.
|
|
64
|
+
**É a rede de segurança da migração**: se todos os testes passam sem edição de semântica, a
|
|
65
|
+
renomeação não mudou nada.
|
|
66
|
+
- [ ] AC-8: `tools:doctor`, `release:check` e `spec:check` verdes ao final; instalação limpa do
|
|
67
|
+
tarball funciona (o próprio `release:check` prova).
|
|
68
|
+
- [ ] AC-9: ADR-0026 registrando a decisão (runtime duplo, `build-fresh`, `tsc`).
|
|
69
|
+
|
|
70
|
+
## 5. Escopo
|
|
71
|
+
|
|
72
|
+
**Dentro**:
|
|
73
|
+
- `tsconfig.json` + `checkJs` on-ramp; migração `.mjs/.js → .ts` leaf-first.
|
|
74
|
+
- `tsc` como toolchain (build → `dist/`, emite `.d.ts`).
|
|
75
|
+
- `build-fresh` em `lib/core/release`; `types:check` no registry; steps no CI.
|
|
76
|
+
- `package.json`: `main`/`types`/`exports`/`bin` → `dist/`; `build`; `prepublishOnly` build→gate.
|
|
77
|
+
- ADR-0026 + ajustes de teste.
|
|
78
|
+
|
|
79
|
+
**Fora** (explícito):
|
|
80
|
+
- **Bumpar o piso de Node.** Fica em `>= 20`; por isso publicamos `dist/` compilado. Dev usa Node
|
|
81
|
+
novo (strip nativo), mas o usuário final não é obrigado.
|
|
82
|
+
- **Geradores como template string.** A fragilidade real (o `@nestjs` falso-positivo, o
|
|
83
|
+
`stripTemplateLiterals`) é separável e ganha spec própria — misturá-la aqui explode o escopo.
|
|
84
|
+
- **Reescrever lógica.** É migração de tipos, não refator de comportamento. Todo teste existente
|
|
85
|
+
passa sem mudança de semântica.
|
|
86
|
+
- **Consolidar o scanner duplicado** (`IMPORT_RE` em `health` e `release`). Vale, mas é refactor —
|
|
87
|
+
e misturá-lo à migração polui o sinal "todos os testes passam sem mudança de semântica", que é a
|
|
88
|
+
rede de segurança da migração inteira (AC-7). Vira fast-follow, spec própria.
|
|
89
|
+
- **esbuild/swc.** `tsc` basta — é framework, não hot path; e precisamos do type-check de qualquer
|
|
90
|
+
forma.
|
|
91
|
+
|
|
92
|
+
## 6. NFRs / restrições
|
|
93
|
+
|
|
94
|
+
- **"Roda sem build" preservado (inegociável).** O `SessionStart` e o `tools:doctor` nunca podem
|
|
95
|
+
depender de `dist/` nem de `node_modules` para funcionar em dev. É o NFR que mata ou aprova o
|
|
96
|
+
design (AC-1).
|
|
97
|
+
- **`dist/` nunca mente.** Coberto pelo `build-fresh` (AC-2). Sem esse check, a migração reintroduz
|
|
98
|
+
a classe do ADR-0021 — e aí não vale a pena.
|
|
99
|
+
- **Verde contínuo.** Renomeação leaf-first, suíte verde a cada arquivo. Nada de big-bang.
|
|
100
|
+
- **Zero dependência de runtime nova.** `typescript` é `devDependency` (só o build a usa); o pacote
|
|
101
|
+
publicado continua com uma dependência de runtime (`better-sqlite3`).
|
|
102
|
+
|
|
103
|
+
## 7. Riscos e mitigação
|
|
104
|
+
|
|
105
|
+
| Risco | Prob | Impacto | Mitigação |
|
|
106
|
+
|---|---|---|---|
|
|
107
|
+
| `dist/` publicado defasado da fonte | M | **A** | `build-fresh` no `release:check` (AC-2) — a classe do ADR-0021, fechada |
|
|
108
|
+
| Hook passa a exigir build/`dist` em dev | M | A | Runtime duplo: dev roda `.ts` nativo; `dist/` só no tarball (AC-1). NFR de bloqueio |
|
|
109
|
+
| `bin` aponta pra `dist/` e dev roda sem build | M | M | Dev usa `node bin/forja.ts` / script; `bin` do published → `dist/` |
|
|
110
|
+
| Migração big-bang quebra tudo de uma vez | M | A | `checkJs` primeiro, renomeia leaf-first, verde a cada passo (AC-3, AC-8) |
|
|
111
|
+
| `node --test` não roda `.ts` | B | A | Confirmar cedo; Node novo roda `.ts` de teste nativo (mesmo strip) |
|
|
112
|
+
| `strict` acusa centenas de erros de uma vez | M | M | On-ramp `checkJs` isola os erros antes da renomeação; corrige incremental |
|
|
113
|
+
|
|
114
|
+
## 8. Métricas de sucesso
|
|
115
|
+
|
|
116
|
+
- Um `probe` com a forma errada **não compila** — o contrato dos checks deixou de ser convenção.
|
|
117
|
+
- `dist/` publicado é sempre igual ao `src/` compilado, provado pelo `build-fresh` a cada release.
|
|
118
|
+
- O `tools:doctor` e o `SessionStart` seguem rodando **sem build** em dev — o NFR inegociável, medido.
|
|
119
|
+
- Consumidores do `forjajs` recebem `.d.ts` — a API deixa de ser adivinhação.
|