forjajs 1.3.2 → 1.6.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/AGENTS.md +5 -0
- package/CHANGELOG.md +74 -0
- package/README.en.md +1 -0
- package/README.md +11 -4
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
- package/dist/lib/agent-topology.d.ts +38 -0
- package/dist/lib/agent-topology.js +65 -0
- package/dist/lib/code-context.d.ts +41 -0
- package/dist/lib/code-context.js +108 -0
- package/dist/lib/core/doc-graph.d.ts +13 -0
- package/dist/lib/core/doc-graph.js +47 -0
- package/dist/lib/core/gates.d.ts +36 -0
- package/dist/lib/core/gates.js +35 -0
- package/dist/lib/core/health.js +64 -1
- package/dist/lib/core/project-smoke.d.ts +46 -0
- package/dist/lib/core/project-smoke.js +248 -0
- package/dist/lib/core/registry.d.ts +30 -0
- package/dist/lib/core/registry.js +30 -0
- package/dist/lib/core/release.d.ts +30 -0
- package/dist/lib/generators/memory-generator.d.ts +1 -0
- package/dist/lib/generators/memory-generator.js +44 -0
- package/dist/lib/generators/readme-generator.js +1 -0
- package/dist/lib/memory-audit.d.ts +31 -0
- package/dist/lib/memory-audit.js +81 -0
- package/dist/lib/project-upgrade.d.ts +28 -0
- package/dist/lib/project-upgrade.js +74 -0
- package/dist/scripts/agent-router.js +1 -1
- package/dist/scripts/code-context.d.ts +12 -0
- package/dist/scripts/code-context.js +73 -0
- package/dist/scripts/gates.d.ts +10 -0
- package/dist/scripts/gates.js +44 -0
- package/dist/scripts/memory-audit.d.ts +11 -0
- package/dist/scripts/memory-audit.js +49 -0
- package/dist/scripts/project-smoke.d.ts +14 -0
- package/dist/scripts/project-smoke.js +44 -0
- package/dist/scripts/project-upgrade.d.ts +11 -0
- package/dist/scripts/project-upgrade.js +61 -0
- package/dist/scripts/token-economy.d.ts +20 -0
- package/dist/scripts/token-economy.js +140 -0
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +10 -0
- package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
- package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
- package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
- package/package.json +1 -1
- package/specs/code-context/spec.md +56 -0
- package/specs/gates/spec.md +63 -0
- package/specs/memory-audit/spec.md +54 -0
- package/specs/orchestration-coherent/spec.md +95 -0
- package/specs/project-smoke/spec.md +96 -0
- package/specs/project-upgrade/spec.md +58 -0
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* token-economy — mede, não argumenta (fecha a dívida do ADR-0027; ADR-0009 e ADR-0003).
|
|
4
|
+
*
|
|
5
|
+
* Dois eixos, porque a economia de token do Forja tem dois eixos e eles são diferentes:
|
|
6
|
+
*
|
|
7
|
+
* 1. ARQUITETURA (clean vs flat) — camadas custam tokens. Numa feature pequena, o flat é mais
|
|
8
|
+
* barato. É honesto, e desmente a versão ingênua de "Clean Architecture economiza tokens".
|
|
9
|
+
*
|
|
10
|
+
* 2. MEMÓRIA (frio vs quente) — o `context.md` é o mapa. Sem ele, um agente varre o código da
|
|
11
|
+
* fatia para localizar a regra; com ele, vai direto ao agregado. AQUI está a economia real do
|
|
12
|
+
* framework (ADR-0009), e ela COMPÕE: paga-se o scaffold uma vez, e o mapa economiza a cada
|
|
13
|
+
* tarefa futura pela vida do projeto.
|
|
14
|
+
*
|
|
15
|
+
* O `token:economy` sozinho não captura o custo de gerar do zero (isso é custo líquido, único). Ele
|
|
16
|
+
* captura o regime permanente — o projeto já levantado, onde a memória persistente paga de volta.
|
|
17
|
+
*
|
|
18
|
+
* Token ≈ bytes/4 (o mesmo proxy do resto do framework). Não é preciso; é reproduzível e honesto.
|
|
19
|
+
*/
|
|
20
|
+
import fs from 'node:fs';
|
|
21
|
+
import path from 'node:path';
|
|
22
|
+
import { fileURLToPath } from 'node:url';
|
|
23
|
+
import { domainsOf, buildContextPack } from "../lib/code-context.js";
|
|
24
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
25
|
+
const root = path.resolve(path.dirname(__filename), '..');
|
|
26
|
+
/**
|
|
27
|
+
* Modo `--project <path>`: mede o eixo memória nos domínios REAIS do usuário, não na fixture. Para
|
|
28
|
+
* cada domínio, o mapa (`context.md`) vs ler todo o código da fatia — o número fica dele.
|
|
29
|
+
*/
|
|
30
|
+
function projectMode(projectRoot) {
|
|
31
|
+
const domains = domainsOf(projectRoot);
|
|
32
|
+
console.log(`\nToken economy — eixo memória nos domínios de ${projectRoot} (ADR-0009)\n`);
|
|
33
|
+
if (!domains.length) {
|
|
34
|
+
console.log(`Nenhum domínio em ${path.join(projectRoot, 'memory/30-domains')}. Rode dentro de um projeto gerado.`);
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
37
|
+
console.log('Para cada domínio: ler o mapa (context.md) vs ler todo o código da fatia.\n');
|
|
38
|
+
const rows = [];
|
|
39
|
+
for (const domain of domains) {
|
|
40
|
+
const pack = buildContextPack({ projectRoot, domain, includeCode: true });
|
|
41
|
+
const economy = pack.codeTokens === 0 ? '—' : `−${Math.round(((pack.codeTokens - pack.mapTokens) / pack.codeTokens) * 100)}%`;
|
|
42
|
+
rows.push({ domínio: domain, mapa_tok: pack.mapTokens, código_tok: pack.codeTokens, mapa_vs_código: economy });
|
|
43
|
+
console.log(`■ ${domain}`);
|
|
44
|
+
console.log(` mapa (context.md): ${String(pack.mapTokens).padStart(5)} tok`);
|
|
45
|
+
console.log(` código da fatia: ${String(pack.codeTokens).padStart(5)} tok (${pack.code.length} arq.)`);
|
|
46
|
+
console.log(` o mapa custa ${economy} do código — é o resumo que substitui a leitura da árvore\n`);
|
|
47
|
+
}
|
|
48
|
+
console.log('O mapa é o resumo do domínio: lê-lo custa uma fração de ler a fatia inteira. Essa é a');
|
|
49
|
+
console.log('economia da memória, medida no SEU projeto. (Sem mapa? rode `forja memory:audit`.)\n');
|
|
50
|
+
if (process.argv.includes('--json'))
|
|
51
|
+
console.log(JSON.stringify(rows, null, 2));
|
|
52
|
+
}
|
|
53
|
+
const CLEAN = 'boilerplates/06-clean-arch/backend/src/modules/orders';
|
|
54
|
+
const CLEAN_CTX = 'boilerplates/06-clean-arch/memory/30-domains/orders/context.md';
|
|
55
|
+
const SHARED = 'boilerplates/06-clean-arch/backend/src/shared/result.ts';
|
|
56
|
+
const FLAT = 'benchmarks/clean-vs-flat/orders-flat';
|
|
57
|
+
/** Todo o código da fatia Orders (clean) — o que se varre "no frio", sem mapa. */
|
|
58
|
+
const CLEAN_CODE = [
|
|
59
|
+
`${CLEAN}/domain/order.entity.ts`,
|
|
60
|
+
`${CLEAN}/domain/order-status.vo.ts`,
|
|
61
|
+
`${CLEAN}/domain/money.vo.ts`,
|
|
62
|
+
`${CLEAN}/domain/order.repository.ts`,
|
|
63
|
+
`${CLEAN}/application/place-order.usecase.ts`,
|
|
64
|
+
`${CLEAN}/application/ship-order.usecase.ts`,
|
|
65
|
+
`${CLEAN}/infrastructure/order.orm-entity.ts`,
|
|
66
|
+
`${CLEAN}/infrastructure/typeorm-order.repository.ts`,
|
|
67
|
+
`${CLEAN}/presentation/orders.controller.ts`,
|
|
68
|
+
`${CLEAN}/presentation/orders.http.dto.ts`,
|
|
69
|
+
`${CLEAN}/orders.module.ts`,
|
|
70
|
+
SHARED,
|
|
71
|
+
];
|
|
72
|
+
const SCENARIOS = [
|
|
73
|
+
{
|
|
74
|
+
axis: 'arquitetura',
|
|
75
|
+
name: 'entender a feature inteira',
|
|
76
|
+
question: 'ler todo o código da fatia para entender o que ela faz',
|
|
77
|
+
a: { label: 'clean', files: CLEAN_CODE },
|
|
78
|
+
b: {
|
|
79
|
+
label: 'flat',
|
|
80
|
+
files: [`${FLAT}/order.entity.ts`, `${FLAT}/orders.service.ts`, `${FLAT}/orders.controller.ts`],
|
|
81
|
+
},
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
axis: 'arquitetura',
|
|
85
|
+
name: 'mudar a regra de envio',
|
|
86
|
+
question: 'alterar a invariante "não envia sem pagamento" — o contexto mínimo suficiente',
|
|
87
|
+
a: { label: 'clean', files: [CLEAN_CTX, `${CLEAN}/domain/order.entity.ts`, `${CLEAN}/domain/order-status.vo.ts`] },
|
|
88
|
+
b: { label: 'flat', files: [`${FLAT}/orders.service.ts`] },
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
axis: 'memória',
|
|
92
|
+
name: 'trabalhar no domínio — com vs sem o mapa da memória',
|
|
93
|
+
question: 'localizar e mexer na regra numa fatia já existente (ADR-0009) — o regime permanente',
|
|
94
|
+
// Quente: a memória (context.md) aponta o agregado + a máquina de estados. Vai direto.
|
|
95
|
+
a: { label: 'quente (memória)', files: [CLEAN_CTX, `${CLEAN}/domain/order.entity.ts`, `${CLEAN}/domain/order-status.vo.ts`] },
|
|
96
|
+
// Frio: sem mapa, varre o código da fatia para descobrir onde a regra vive.
|
|
97
|
+
b: { label: 'frio (sem memória)', files: CLEAN_CODE },
|
|
98
|
+
},
|
|
99
|
+
];
|
|
100
|
+
const tokensOf = (rel) => {
|
|
101
|
+
try {
|
|
102
|
+
return Math.round(fs.readFileSync(path.join(root, rel), 'utf8').length / 4);
|
|
103
|
+
}
|
|
104
|
+
catch {
|
|
105
|
+
return 0;
|
|
106
|
+
}
|
|
107
|
+
};
|
|
108
|
+
const sum = (files) => files.reduce((acc, f) => acc + tokensOf(f), 0);
|
|
109
|
+
const pct = (a, b) => (b === 0 ? '—' : `${a <= b ? '−' : '+'}${Math.abs(Math.round(((a - b) / b) * 100))}%`);
|
|
110
|
+
// `--project <path>`: mede o eixo memória no projeto real e sai. Sem ele, o benchmark de fixture.
|
|
111
|
+
const projIdx = process.argv.indexOf('--project');
|
|
112
|
+
if (projIdx >= 0) {
|
|
113
|
+
projectMode(path.resolve(process.argv[projIdx + 1] || process.cwd()));
|
|
114
|
+
process.exit(0);
|
|
115
|
+
}
|
|
116
|
+
console.log('\nToken economy — o custo do CONTEXTO por cenário (ADR-0027, ADR-0009)\n');
|
|
117
|
+
console.log('Token ≈ bytes/4. Não mede o custo de gerar do zero (custo único); mede o regime permanente.\n');
|
|
118
|
+
const out = [];
|
|
119
|
+
for (const s of SCENARIOS) {
|
|
120
|
+
const a = sum(s.a.files);
|
|
121
|
+
const b = sum(s.b.files);
|
|
122
|
+
out.push({ eixo: s.axis, cenário: s.name, [s.a.label]: a, [s.b.label]: b, a_vs_b: pct(a, b) });
|
|
123
|
+
console.log(`■ [${s.axis}] ${s.name}`);
|
|
124
|
+
console.log(` ${s.question}`);
|
|
125
|
+
console.log(` ${s.a.label.padEnd(18)} ${String(a).padStart(5)} tok (${s.a.files.length} arq.)`);
|
|
126
|
+
console.log(` ${s.b.label.padEnd(18)} ${String(b).padStart(5)} tok (${s.b.files.length} arq.)`);
|
|
127
|
+
console.log(` ${s.a.label} vs ${s.b.label}: ${pct(a, b)}\n`);
|
|
128
|
+
}
|
|
129
|
+
const arch = out[1]; // mudar a regra, clean vs flat
|
|
130
|
+
const mem = out[2]; // frio vs quente
|
|
131
|
+
console.log('Veredito (derivado dos números):');
|
|
132
|
+
console.log(` • EIXO ARQUITETURA: numa feature pequena, camadas custam MAIS token (${arch.a_vs_b} para`);
|
|
133
|
+
console.log(` a mudança isolada). "Clean Architecture economiza tokens" não se sustenta nessa escala —`);
|
|
134
|
+
console.log(` a justificativa das camadas é isolamento e testabilidade, não token.`);
|
|
135
|
+
console.log(` • EIXO MEMÓRIA: o mapa (context.md) faz o contexto mínimo custar ${mem.a_vs_b} vs varrer`);
|
|
136
|
+
console.log(` a fatia no frio. É AQUI que a economia mora — e ela COMPÕE: o scaffold é custo único,`);
|
|
137
|
+
console.log(` o mapa economiza a cada tarefa futura. Depois do projeto levantado, a memória paga de volta.\n`);
|
|
138
|
+
if (process.argv.includes('--json')) {
|
|
139
|
+
console.log(JSON.stringify(out, null, 2));
|
|
140
|
+
}
|
|
@@ -33,6 +33,16 @@ Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanne
|
|
|
33
33
|
instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
|
|
34
34
|
- **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
|
|
35
35
|
- **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
|
|
36
|
+
- **`adr-refs`** (warn, adicionado depois): toda citação `ADR-NNNN` em doc/spec/ADR aponta para um
|
|
37
|
+
ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
|
|
38
|
+
lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
|
|
39
|
+
pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
|
|
40
|
+
- **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
|
|
41
|
+
(`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
|
|
42
|
+
namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
|
|
43
|
+
sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
|
|
44
|
+
endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
|
|
45
|
+
classe dos checks acima, aplicada a quem-orquestra-quem.
|
|
36
46
|
|
|
37
47
|
Princípios:
|
|
38
48
|
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# ADR-0026: Migração TypeScript com runtime duplo (fonte `.ts`, publicado `dist/`)
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-19
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: typescript, build, runtime, sdd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
A SPEC-012 migrou o framework de `.mjs`/checkJs para TypeScript de verdade. Dois requisitos em
|
|
11
|
+
tensão organizaram todas as decisões:
|
|
12
|
+
|
|
13
|
+
- **NFR inegociável**: o dev roda `sem build`. `node bin/forja.ts <cmd>` tem que funcionar direto,
|
|
14
|
+
ou o loop de desenvolvimento morre.
|
|
15
|
+
- **`engines.node >= 20`**: o pacote publicado precisa rodar em Node 20/21, que **não** executam
|
|
16
|
+
`.ts` (strip-types nativo só existe a partir do Node 22.6).
|
|
17
|
+
|
|
18
|
+
Essas duas verdades não cabem no mesmo artefato: no instante em que a fonte vira `.ts`, um pacote
|
|
19
|
+
publicado sem compilar quebra para quem está em Node 20.
|
|
20
|
+
|
|
21
|
+
## Decisão
|
|
22
|
+
|
|
23
|
+
**Runtime duplo, resolvido por um único ponto.**
|
|
24
|
+
|
|
25
|
+
1. **D1 — Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
|
|
26
|
+
`dist/lib`, `dist/scripts`. Não movemos a fonte para `src/`: trocaria todo import, path de
|
|
27
|
+
registry e hook — blast radius enorme, contra o "verde contínuo".
|
|
28
|
+
2. **D2 — Registry + `resolveScript` (o coração).** O registry nomeia os scripts; o `resolveScript`
|
|
29
|
+
tenta as extensões na ordem `['.ts', '.js', '.mjs']`, fazendo strip da extensão declarada. Em dev
|
|
30
|
+
acha o `.ts`; no publicado acha o `dist/*.js`. Um resolver, dois mundos — sem dois registries
|
|
31
|
+
(a divergência que a SPEC-009 matou).
|
|
32
|
+
3. **D3 — Dual runtime.** Dev roda `.ts` nativo (Node ≥22.6, exigência de contribuir); o publicado
|
|
33
|
+
embarca `dist/*.js` (Node ≥20). O acoplamento de Node-floor vive só na fronteira do publicado.
|
|
34
|
+
4. **D4 (revisado) — o gate constrói o `dist/`.** O `release:check` roda `npm run build` **antes de
|
|
35
|
+
empacotar** (quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
|
|
36
|
+
empacota o mesmo disco recém-buildado, o tarball provado é o publicado — sem `dist/` no git, sem
|
|
37
|
+
step de build no `ci.yml`, sem janela de staleness. O gate é self-contained.
|
|
38
|
+
5. **D9 — publicar `dist/` desde sempre desacopla o risco.** Enquanto a fonte ainda era `.mjs`, o
|
|
39
|
+
build era uma cópia; quando virou `.ts`, virou compilação. Em ambos os casos o publicado é JS
|
|
40
|
+
runnable, então o `.ts`-não-roda-em-Node-20 nunca morde o usuário final.
|
|
41
|
+
|
|
42
|
+
## Alternativas consideradas
|
|
43
|
+
|
|
44
|
+
- **Guardar `.js` compilado no git e exigir build em dev** — rejeitada: mata o NFR "roda sem build".
|
|
45
|
+
- **Publicar a fonte `.ts` crua** — rejeitada: quebra em Node 20/21; o `release:check` reprovaria.
|
|
46
|
+
- **Dois registries (dev/publicado)** — rejeitada: duas verdades que divergem (defeito da SPEC-009).
|
|
47
|
+
- **Mover a fonte para `src/`** — rejeitada: blast radius desproporcional para ganho estético.
|
|
48
|
+
|
|
49
|
+
## Consequências
|
|
50
|
+
|
|
51
|
+
**Positivas**:
|
|
52
|
+
- Dev roda `.ts` nativo, zero build; usuário final roda `dist/*.js`, Node ≥20. Cada um paga só o seu.
|
|
53
|
+
- Uma máquina (`resolveScript`) resolve os dois mundos; o gate prova o tarball real.
|
|
54
|
+
- `noImplicitAny` ligado ao fim: o ratchet força todo código futuro a ser tipado.
|
|
55
|
+
|
|
56
|
+
**Negativas / Trade-offs**:
|
|
57
|
+
- Contribuir passa a exigir Node ≥22.6; o job `test` do CI cai fora do Node 20 (o suporte a 20 do
|
|
58
|
+
publicado é provado pelo `release-gate`, que instala o tarball `.js`).
|
|
59
|
+
- O `resolveScript` carrega três extensões por dívida histórica (`.mjs` legado) — barato, mas é
|
|
60
|
+
estado que um dia se limpa.
|
|
61
|
+
|
|
62
|
+
## Rastreamento
|
|
63
|
+
- Spec: `specs/ts-migration/` (SPEC-012)
|
|
64
|
+
- Implementação: `lib/core/registry.ts` (resolveScript), `lib/core/release.ts` (gate builda),
|
|
65
|
+
`tsconfig.json` / `tsconfig.build.json`, `.github/workflows/ci.yml`
|
|
66
|
+
- ADRs relacionadas: ADR-0021 (NFR "roda sem build"; classe "dist mente"), ADR-0024 (gate do tarball)
|
|
@@ -62,9 +62,40 @@ rica com lógica pobre, não arquitetura com arquitetura.
|
|
|
62
62
|
|
|
63
63
|
**Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
|
|
64
64
|
não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
|
|
65
|
-
prova rigorosa precisa do
|
|
66
|
-
|
|
67
|
-
|
|
65
|
+
prova rigorosa precisa do benchmark sobre uma **mesma tarefa**, com a mesma feature nas duas
|
|
66
|
+
arquiteturas — o boilerplate flat não tinha um equivalente rico ao Order, então ficou como follow-up.
|
|
67
|
+
|
|
68
|
+
### Follow-up resolvido — o benchmark same-feature (`forja token:economy`)
|
|
69
|
+
|
|
70
|
+
A dívida acima foi fechada: existe um `benchmarks/clean-vs-flat/orders-flat/` (a MESMA feature —
|
|
71
|
+
place + ship + "não envia sem pagamento" — no estilo flat) e o comando `token:economy` mede **dois
|
|
72
|
+
eixos**, porque a economia de token do Forja tem dois eixos e eles são diferentes:
|
|
73
|
+
|
|
74
|
+
**Eixo 1 — arquitetura (clean vs flat).** Desmente a versão ingênua da claim:
|
|
75
|
+
|
|
76
|
+
| Cenário | Clean | Flat | Clean vs flat |
|
|
77
|
+
|---|---|---|---|
|
|
78
|
+
| Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
|
|
79
|
+
| Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
|
|
80
|
+
|
|
81
|
+
Para uma feature pequena, **o clean-arch custa MAIS tokens** — inclusive na mudança localizada. A
|
|
82
|
+
camada cobra adiantado e, com dois casos de uso, não se paga. **A justificativa de `orders` em
|
|
83
|
+
camadas passa a ser isolamento e testabilidade, não token.**
|
|
84
|
+
|
|
85
|
+
**Eixo 2 — memória (frio vs quente).** É aqui que a economia real do framework mora (ADR-0009):
|
|
86
|
+
|
|
87
|
+
| Cenário | Quente (com `context.md`) | Frio (sem mapa) | Economia |
|
|
88
|
+
|---|---|---|---|
|
|
89
|
+
| Localizar e mexer numa regra da fatia | ~1419 tok (3 arq.) | ~3684 tok (12 arq.) | **−61%** |
|
|
90
|
+
|
|
91
|
+
O `context.md` é o mapa: com ele, o agente vai direto ao agregado + à máquina de estados; sem ele,
|
|
92
|
+
varre a fatia inteira para descobrir onde a regra vive. **E essa economia COMPÕE**: gerar do zero é
|
|
93
|
+
custo único (o scaffold), mas o mapa poupa a cada tarefa futura, pela vida do projeto. O
|
|
94
|
+
`token:economy` não mede o custo de gerar — mede o regime permanente, depois do projeto levantado.
|
|
95
|
+
|
|
96
|
+
Conclusão corrigida: a economia de token do Forja **não é das camadas — é da memória persistente**,
|
|
97
|
+
amortizada no tempo. As camadas se pagam só a partir de certa escala (tamanho da feature × nº de
|
|
98
|
+
casos de uso); a memória se paga desde a segunda tarefa. Tudo reproduzível: `forja token:economy`.
|
|
68
99
|
|
|
69
100
|
## Alternativas consideradas
|
|
70
101
|
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# ADR-0029: Gate do projeto gerado (`project:smoke`)
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-19
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: quality, gates, generators, sdd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O `release:check` (ADR-0024) guarda uma fronteira com evidência: *o repositório mente sobre o
|
|
11
|
+
pacote*. Existe a **mesma classe de bug um nível acima, e estava descoberta**: nada provava que
|
|
12
|
+
`forja project:new` gera um projeto coerente.
|
|
13
|
+
|
|
14
|
+
O gerador escreve a partir de templates — `{{FEATURE}}`, blocos de `scripts`, configs. Cada
|
|
15
|
+
substituição é uma chance de mentira silenciosa: um placeholder que vaza, um `package.json` que não
|
|
16
|
+
parseia, uma estrutura incompleta. O `structure-validator` já sabia *validar* estrutura, mas nada
|
|
17
|
+
*executava* o gerador de ponta a ponta e reprovava. Conhecimento não faltava; execução, sim — o
|
|
18
|
+
mesmo diagnóstico da SPEC-010.
|
|
19
|
+
|
|
20
|
+
## Decisão
|
|
21
|
+
|
|
22
|
+
Criar `project:smoke` (SPEC-015): um gate que **gera um projeto num diretório temporário isolado e o
|
|
23
|
+
inspeciona**, reusando o runner de `checks.ts` — a mesma máquina de probes do doctor e do release.
|
|
24
|
+
|
|
25
|
+
Dois tiers, espelhando o `release:check`:
|
|
26
|
+
|
|
27
|
+
- **Barato (default, roda no CI)**: sem rede. Prova que nenhum placeholder `{{...}}` vazou, que todo
|
|
28
|
+
`package.json` parseia, e que a estrutura passa no `validateProjectStructure`.
|
|
29
|
+
- **`--full` (opt-in, pré-release)**: `npm install` + `npm run build` no backend gerado, num ambiente
|
|
30
|
+
isolado (sem `NODE_PATH`/`npm_config_*` herdados). É o clean-install do release, na saída do gerador.
|
|
31
|
+
|
|
32
|
+
O gerador não sabe que está sendo auditado — o gate só o observa via spawn do entry real
|
|
33
|
+
(`create-memory-nest-kit`), como o release empacota o tarball real.
|
|
34
|
+
|
|
35
|
+
## Alternativas consideradas
|
|
36
|
+
|
|
37
|
+
- **Importar as funções do gerador e chamá-las direto** — rejeitada: testaria as funções, não o
|
|
38
|
+
entry point que o usuário roda. O spawn do orquestrador pega bugs de orquestração também.
|
|
39
|
+
- **Rodar sempre o tier pesado (install+build)** — rejeitada: `npm install` de um NestJS é lento e
|
|
40
|
+
usa rede; um gate que reprova por flakiness de registry se contorna (a lição do CI na SPEC-009).
|
|
41
|
+
Por isso o tier barato é o gate de CI e o `--full` é opt-in.
|
|
42
|
+
- **Pôr no `tools:doctor`** — rejeitada: o doctor é o raio-x barato do núcleo; gerar um projeto tem
|
|
43
|
+
custo. É gate próprio, como o `release:check`.
|
|
44
|
+
|
|
45
|
+
## Consequências
|
|
46
|
+
|
|
47
|
+
**Positivas**:
|
|
48
|
+
- A última fronteira do gerador que vivia por disciplina passa a viver no harness.
|
|
49
|
+
- Reuso total: runner de `checks.ts` + `structure-validator` existente — uma máquina, não duas.
|
|
50
|
+
- O tier barato é rápido o bastante para o CI; o `--full` dá a prova forte antes de publicar.
|
|
51
|
+
|
|
52
|
+
**Negativas / Trade-offs**:
|
|
53
|
+
- Cobre o caminho *default* do gerador; a matriz de boilerplates de stack fica para iteração futura.
|
|
54
|
+
- O `--full` depende de rede — mitigado por ser opt-in, fora do gate de CI.
|
|
55
|
+
|
|
56
|
+
## Rastreamento
|
|
57
|
+
- Implementação: `lib/core/project-smoke.ts`, `scripts/project-smoke.ts`, `test/project-smoke.test.js`
|
|
58
|
+
- Spec: `specs/project-smoke/spec.md` (SPEC-015)
|
|
59
|
+
- ADRs relacionadas: ADR-0024 (gate do tarball — o padrão), ADR-0023 (doctor), ADR-0020 (core/registry)
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# ADR-0030: O projeto gerado herda os gates do framework
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-19
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: generators, gates, memory, governance
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O framework construiu uma família de invariantes-que-rodam: `project:smoke`, `memory:audit`,
|
|
11
|
+
`adr-refs`, o `release:check`. Mas todos guardam o **framework**. O **projeto do usuário** não
|
|
12
|
+
herdava nenhum — gerava com mapas de memória honestos e, com o tempo, um rename sem atualizar o
|
|
13
|
+
`context.md` fazia o mapa mentir, silenciosamente, sem nada avisar. A economia de token da memória
|
|
14
|
+
(ADR-0009) se degrada, e ninguém percebe. É a mesma classe "vive por disciplina" que o ADR-0021
|
|
15
|
+
combate — só que na máquina do usuário, onde o framework não alcança por gate próprio.
|
|
16
|
+
|
|
17
|
+
## Decisão
|
|
18
|
+
|
|
19
|
+
O gerador **emite um gate self-contained no projeto**: `scripts/check-memory-maps.mjs`, uma versão
|
|
20
|
+
sem dependências do `memory:audit` (coerência mapa↔código: mapa não cita código morto, módulo sem
|
|
21
|
+
mapa avisa). Zero acoplamento ao `forjajs` — Node puro, roda em qualquer CI com `node
|
|
22
|
+
scripts/check-memory-maps.mjs`. O `project:smoke` do framework passa a **verificar que o gate está
|
|
23
|
+
presente** no projeto gerado, fechando o laço: o framework prova que propaga o invariante.
|
|
24
|
+
|
|
25
|
+
A filosofia de invariantes deixa de ser só do mantenedor do Forja e passa a viajar com cada projeto.
|
|
26
|
+
|
|
27
|
+
## Alternativas consideradas
|
|
28
|
+
|
|
29
|
+
- **Projeto depende de `forjajs` e roda `npx forja memory:audit`** — rejeitada: acopla um app NestJS
|
|
30
|
+
ao framework inteiro (e ao `better-sqlite3`), pesado para um gate que é Node puro.
|
|
31
|
+
- **Emitir um workflow `.github/` pronto** — rejeitada (por ora): imporia GitHub Actions a todo
|
|
32
|
+
projeto (alguns usam GitLab/outros). O script é portável; o usuário o pluga no CI que usa. Um
|
|
33
|
+
workflow opcional pode vir em follow-up.
|
|
34
|
+
- **Não propagar (deixar como doc)** — rejeitada: é exatamente o "regra que depende de memória" que
|
|
35
|
+
o framework existe para eliminar.
|
|
36
|
+
|
|
37
|
+
## Consequências
|
|
38
|
+
|
|
39
|
+
**Positivas**:
|
|
40
|
+
- O invariante mapa↔código viaja com o projeto; a economia de token da memória fica protegida na
|
|
41
|
+
máquina do usuário, não só na do framework.
|
|
42
|
+
- Self-contained: sem dependência nova no projeto gerado.
|
|
43
|
+
- `project:smoke` prova a propagação (o gate está presente no output).
|
|
44
|
+
|
|
45
|
+
**Negativas / Trade-offs**:
|
|
46
|
+
- Duplicação de lógica (o `check-memory-maps.mjs` do projeto espelha o `lib/memory-audit.ts`). É o
|
|
47
|
+
preço de projetos independentes; a lógica é pequena e estável.
|
|
48
|
+
- O gate não roda sozinho até o usuário plugá-lo no CI — o script está presente, o wiring é dele.
|
|
49
|
+
|
|
50
|
+
## Rastreamento
|
|
51
|
+
- Implementação: `lib/generators/memory-generator.ts` (emite o script),
|
|
52
|
+
`lib/core/project-smoke.ts` (check `gate-inherited`)
|
|
53
|
+
- ADRs relacionadas: ADR-0009 (economia de token), ADR-0021 (invariante > disciplina), ADR-0029 (project:smoke), SPEC-017 (memory:audit)
|
package/package.json
CHANGED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Spec: code-context
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-016
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0009 (economia de token), ADR-0003 (smart-context), ADR-0020 (core/registry)
|
|
7
|
+
|
|
8
|
+
## 1. Problema
|
|
9
|
+
|
|
10
|
+
O `token:economy` mediu a economia real do framework: o `context.md` de um domínio (o mapa) faz o
|
|
11
|
+
contexto mínimo custar **−61%** vs varrer a fatia no frio. Mas essa economia era **potencial, não
|
|
12
|
+
entregue**: o mapa é só um arquivo que alguém precisa lembrar de ler, e ainda montar o contexto na
|
|
13
|
+
mão (mapa + os arquivos certos). A economia medida não vira lever até virar comando.
|
|
14
|
+
|
|
15
|
+
## 2. Proposta de valor
|
|
16
|
+
|
|
17
|
+
Um comando entrega o **pacote de contexto mínimo** de um domínio, pronto para colar, com o custo em
|
|
18
|
+
token à mostra: o −61% deixa de ser medição e vira ferramenta do dia a dia.
|
|
19
|
+
|
|
20
|
+
## 3. User stories
|
|
21
|
+
|
|
22
|
+
- **Como** agente que vai mexer num domínio, **quero** um comando que me dê o mapa + (sob demanda) o
|
|
23
|
+
código da fatia, **para que** eu não pague o custo de explorar a árvore no frio.
|
|
24
|
+
- **Como** dev, **quero** ver o custo em token do pacote, **para que** a economia seja visível e eu
|
|
25
|
+
escolha entre "só o mapa" e "mapa + código".
|
|
26
|
+
|
|
27
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
28
|
+
|
|
29
|
+
- [x] AC-1: `forja code:context <domínio>` imprime o `context.md` do domínio (o mapa), pronto para
|
|
30
|
+
colar, com os tokens do mapa no rodapé.
|
|
31
|
+
- [x] AC-2: `--code` anexa os `.ts` da fatia (`backend/src/modules/<domínio>/`) e soma os tokens.
|
|
32
|
+
- [x] AC-3: `--project <path>` aponta para outro projeto (default: `cwd`). Sem domínio, lista os
|
|
33
|
+
disponíveis; domínio inexistente reprova com a lista.
|
|
34
|
+
- [x] AC-4: A lógica de montagem é pura e testável (`lib/code-context.ts`), com fixtures — sem tocar
|
|
35
|
+
o disco real.
|
|
36
|
+
|
|
37
|
+
## 5. Escopo
|
|
38
|
+
|
|
39
|
+
**Dentro**: o mapa + o código da fatia, com custo em token. Composição com `code:impact` (blast
|
|
40
|
+
radius) documentada, não embutida.
|
|
41
|
+
|
|
42
|
+
**Fora** (explícito):
|
|
43
|
+
- Reindexar/consultar a memória via FTS5 — isso é `context:smart`/`query:universal`; este comando lê
|
|
44
|
+
o mapa direto do disco do projeto.
|
|
45
|
+
- Chamar codegraph internamente — o blast radius fica em `code:impact`, componível (`&&`).
|
|
46
|
+
- Editar ou resumir o código — entrega cru; resumir é decisão do agente que consome.
|
|
47
|
+
|
|
48
|
+
## 6. NFRs / restrições
|
|
49
|
+
|
|
50
|
+
- **Compatibilidade**: comando novo; não muda nada existente.
|
|
51
|
+
- **Sem dependência de rede ou de codegraph** no caminho principal (mapa + código são leitura de disco).
|
|
52
|
+
|
|
53
|
+
## 7. Métricas de sucesso
|
|
54
|
+
|
|
55
|
+
O pacote "só o mapa" de um domínio típico custa uma fração do "mapa + código" — e ambos, uma fração
|
|
56
|
+
de ler a fatia no frio. O `token:economy` já mostra o −61%; este comando o torna acionável.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Spec: gates
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-020
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0023 (doctor como gate), ADR-0024 (release gate), ADR-0029 (project:smoke), ADR-0020 (core/registry)
|
|
7
|
+
|
|
8
|
+
## 1. Problema
|
|
9
|
+
|
|
10
|
+
O framework acumulou uma família de gates — `tools:doctor` (núcleo + coerência de doc + topologia),
|
|
11
|
+
`release:check` (tarball), `project:smoke` (projeto gerado). Cada um guarda uma fronteira, mas estão
|
|
12
|
+
**espalhados**: ninguém lembra de rodar os três antes de um PR, e a governança do Forja — que existe
|
|
13
|
+
justamente para não depender de memória — depende da memória de quem publica para *invocar* os gates.
|
|
14
|
+
É a mesma ironia do ADR-0021, um nível acima: os gates existem, mas rodá-los ainda é disciplina.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
|
|
18
|
+
Um comando roda **todos os gates aplicáveis ao framework** e dá **um veredito só**. "A casa está
|
|
19
|
+
coerente?" deixa de ser quatro comandos lembrados e vira um: `forja check:all`.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
|
|
23
|
+
- **Como** mantenedor, **quero** um comando que rode a bateria inteira antes do PR, **para que** eu
|
|
24
|
+
não esqueça um gate e descubra a quebra no CI (ou depois).
|
|
25
|
+
- **Como** quem publica, **quero** `--full` que inclua os gates caros (tarball, build do gerado),
|
|
26
|
+
**para que** o pré-release seja um comando, não um checklist.
|
|
27
|
+
|
|
28
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
29
|
+
|
|
30
|
+
- [ ] AC-1: `forja check:all` roda os gates de coerência (o catálogo do `tools:doctor`) **+** o
|
|
31
|
+
`project:smoke` (tier barato) e reporta **um veredito** (exit ≠ 0 se qualquer crítico falhar).
|
|
32
|
+
- [ ] AC-2: `--full` adiciona os gates caros: `release:check` (tarball) e `project:smoke --full`
|
|
33
|
+
(instala + builda o backend gerado).
|
|
34
|
+
- [ ] AC-3: A saída **agrupa por gate** (núcleo & coerência / projeto gerado / tarball) e resume o
|
|
35
|
+
pior status ao final — legível, não um despejo.
|
|
36
|
+
- [ ] AC-4: **Compõe os runners existentes** (`health`, `project-smoke`, `release`) — uma máquina,
|
|
37
|
+
zero reimplementação de check. Reusa `worstStatus` de `checks.ts`.
|
|
38
|
+
- [ ] AC-5: Lógica de composição pura e testável (env/runners injetáveis; teste com fakes que
|
|
39
|
+
devolvem status conhecidos, sem gerar projeto de verdade).
|
|
40
|
+
|
|
41
|
+
## 5. Escopo
|
|
42
|
+
|
|
43
|
+
**Dentro**: compor os gates do framework num comando com veredito único e tiers.
|
|
44
|
+
|
|
45
|
+
**Fora** (explícito):
|
|
46
|
+
- `memory:audit` — é gate de **projeto gerado** (precisa de `memory/30-domains` de produto), não do
|
|
47
|
+
framework. Fica de fora do `check:all` do framework; roda no CI do projeto (ADR-0030).
|
|
48
|
+
- Reimplementar qualquer check — este comando só orquestra os catálogos que já existem.
|
|
49
|
+
- Substituir `tools:doctor`/`release:check`/`project:smoke` — eles seguem existindo, focados; o
|
|
50
|
+
`check:all` é o agregador, não o dono.
|
|
51
|
+
|
|
52
|
+
## 6. NFRs / restrições
|
|
53
|
+
|
|
54
|
+
- **Custo consciente**: o tier barato inclui a geração de um projeto (`project:smoke`) — segundos, sem
|
|
55
|
+
rede. O `--full` é minutos (empacota o tarball, `npm install` do backend). O tier certo para o
|
|
56
|
+
momento certo, como no `release:check`.
|
|
57
|
+
- **Compatibilidade**: comando novo; não muda os gates que agrega.
|
|
58
|
+
|
|
59
|
+
## 7. Métricas de sucesso
|
|
60
|
+
|
|
61
|
+
Um `forja check:all` antes do PR pega uma quebra que passaria (um gate esquecido) — a prova de que
|
|
62
|
+
reunir a bateria num comando valeu. A governança do framework deixa de depender de lembrar quais
|
|
63
|
+
gates rodar.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Spec: memory-audit
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-017
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0009 (economia de token), ADR-0025 (coerência da doc — a mesma classe), ADR-0020 (core/registry)
|
|
7
|
+
|
|
8
|
+
## 1. Problema
|
|
9
|
+
|
|
10
|
+
A economia de token do Forja é o `context.md` como mapa do domínio (`token:economy` mede −61%). Mas
|
|
11
|
+
o mapa cita paths de código — "a regra mora em `domain/order.entity.ts`", "teste em
|
|
12
|
+
`test/orders/place-order.spec.ts`". Quando o código é renomeado ou movido e o mapa não acompanha, o
|
|
13
|
+
mapa passa a **mentir com confiança**: um agente lê o lugar errado, paga o custo, e chega à conclusão
|
|
14
|
+
errada. Um mapa desatualizado é *pior* que mapa nenhum. Nada verifica isso hoje — vive de disciplina.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
|
|
18
|
+
O mapa deixa de poder mentir em silêncio: **todo path de código citado num `context.md` é conferido**,
|
|
19
|
+
e uma referência pendurada reprova. É o `adr-refs` (ADR-0025) aplicado aos mapas de memória.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
|
|
23
|
+
- **Como** dev de um projeto gerado, **quero** um comando que reprove quando um mapa aponta para
|
|
24
|
+
arquivo que não existe mais, **para que** a economia de token da memória não se volte contra mim.
|
|
25
|
+
- **Como** CI de um projeto, **quero** rodar isso como gate, **para que** um rename sem atualizar o
|
|
26
|
+
mapa não passe batido.
|
|
27
|
+
|
|
28
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
29
|
+
|
|
30
|
+
- [x] AC-1: `forja memory:audit` varre `memory/30-domains/*/context.md`, extrai os paths de código
|
|
31
|
+
citados (entre crases, com `/` e terminando em `.ts`) e reprova (exit ≠ 0) se algum não existe.
|
|
32
|
+
- [x] AC-2: Resolve o path em múltiplas bases (relativo ao módulo, ao `backend/`, à raiz) — um mesmo
|
|
33
|
+
mapa cita as duas convenções (`domain/x.ts` e `test/x.spec.ts`).
|
|
34
|
+
- [x] AC-3: `--project <path>` aponta para outro projeto (default: `cwd`).
|
|
35
|
+
- [x] AC-4: Lógica pura e testável (`lib/memory-audit.ts`); reusa `domainsOf` de `code-context`.
|
|
36
|
+
|
|
37
|
+
## 5. Escopo
|
|
38
|
+
|
|
39
|
+
**Dentro**: conferir paths de código `.ts` citados nos mapas de domínio.
|
|
40
|
+
|
|
41
|
+
**Fora** (explícito):
|
|
42
|
+
- Validar que o *conteúdo* do mapa (a linguagem ubíqua, as regras) ainda bate com o código — isso é
|
|
43
|
+
julgamento, não path. Este gate pega o path pendurado, que é o sinal barato e objetivo.
|
|
44
|
+
- Rodar dentro do `project:smoke` — lá o projeto é recém-gerado, o mapa é fresco por definição. A
|
|
45
|
+
divergência mapa↔código acontece com o tempo, num projeto existente; é aí que este comando roda.
|
|
46
|
+
|
|
47
|
+
## 6. NFRs / restrições
|
|
48
|
+
|
|
49
|
+
- **Compatibilidade**: comando novo; não muda nada. Sem rede, sem codegraph — leitura de disco.
|
|
50
|
+
|
|
51
|
+
## 7. Métricas de sucesso
|
|
52
|
+
|
|
53
|
+
Pelo menos um rename sem atualização de mapa pego antes do merge num projeto real — a prova de que a
|
|
54
|
+
fronteira estava descoberta.
|