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.
Files changed (51) hide show
  1. package/AGENTS.md +5 -0
  2. package/CHANGELOG.md +74 -0
  3. package/README.en.md +1 -0
  4. package/README.md +11 -4
  5. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  6. package/dist/lib/agent-topology.d.ts +38 -0
  7. package/dist/lib/agent-topology.js +65 -0
  8. package/dist/lib/code-context.d.ts +41 -0
  9. package/dist/lib/code-context.js +108 -0
  10. package/dist/lib/core/doc-graph.d.ts +13 -0
  11. package/dist/lib/core/doc-graph.js +47 -0
  12. package/dist/lib/core/gates.d.ts +36 -0
  13. package/dist/lib/core/gates.js +35 -0
  14. package/dist/lib/core/health.js +64 -1
  15. package/dist/lib/core/project-smoke.d.ts +46 -0
  16. package/dist/lib/core/project-smoke.js +248 -0
  17. package/dist/lib/core/registry.d.ts +30 -0
  18. package/dist/lib/core/registry.js +30 -0
  19. package/dist/lib/core/release.d.ts +30 -0
  20. package/dist/lib/generators/memory-generator.d.ts +1 -0
  21. package/dist/lib/generators/memory-generator.js +44 -0
  22. package/dist/lib/generators/readme-generator.js +1 -0
  23. package/dist/lib/memory-audit.d.ts +31 -0
  24. package/dist/lib/memory-audit.js +81 -0
  25. package/dist/lib/project-upgrade.d.ts +28 -0
  26. package/dist/lib/project-upgrade.js +74 -0
  27. package/dist/scripts/agent-router.js +1 -1
  28. package/dist/scripts/code-context.d.ts +12 -0
  29. package/dist/scripts/code-context.js +73 -0
  30. package/dist/scripts/gates.d.ts +10 -0
  31. package/dist/scripts/gates.js +44 -0
  32. package/dist/scripts/memory-audit.d.ts +11 -0
  33. package/dist/scripts/memory-audit.js +49 -0
  34. package/dist/scripts/project-smoke.d.ts +14 -0
  35. package/dist/scripts/project-smoke.js +44 -0
  36. package/dist/scripts/project-upgrade.d.ts +11 -0
  37. package/dist/scripts/project-upgrade.js +61 -0
  38. package/dist/scripts/token-economy.d.ts +20 -0
  39. package/dist/scripts/token-economy.js +140 -0
  40. package/memory/90-decisions/0025-coerencia-da-documentacao.md +10 -0
  41. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  42. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  43. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  44. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  45. package/package.json +1 -1
  46. package/specs/code-context/spec.md +56 -0
  47. package/specs/gates/spec.md +63 -0
  48. package/specs/memory-audit/spec.md +54 -0
  49. package/specs/orchestration-coherent/spec.md +95 -0
  50. package/specs/project-smoke/spec.md +96 -0
  51. package/specs/project-upgrade/spec.md +58 -0
package/AGENTS.md CHANGED
@@ -66,6 +66,11 @@ Handoffs entre eles passam pela tabela `handoffs` em `~/forja-workspace/memory/s
66
66
  **Faz**: roda `project:check`, audita handoffs por completude, valida 12-Factor/LGPD/segurança, bloqueia se algo falta.
67
67
  **Não faz**: aprovar "ficou bom" sem referência verificável.
68
68
 
69
+ ## 7. Release Auditor
70
+ **Quando**: antes de publicar no npm — o especialista de release da governança.
71
+ **Faz**: roda `release:check --publish`, interpreta o parecer e autoriza (ou barra) a publicação. Pega quebras que só apareceriam na máquina de quem instala (SPEC-010, ADR-0024).
72
+ **Não faz**: publicar — `npm publish` é ato humano. Ele diagnostica e autoriza.
73
+
69
74
  ---
70
75
 
71
76
  ## Fluxo SDD padrão
package/CHANGELOG.md CHANGED
@@ -4,6 +4,80 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.6.0] — 2026-07-20 — A orquestração coerente e a governança num comando
8
+
9
+ A governança do framework ganha um ponto de entrada e o namesake — orquestração multiagente — deixa
10
+ de viver por prosa.
11
+
12
+ ### Adicionado
13
+ - **`check:all`** (SPEC-020): roda a **bateria inteira de gates** e dá um veredito só. Tier barato:
14
+ coerência (`tools:doctor`) + `project:smoke`; `--full`: + tarball (`release:check`) + build do
15
+ gerado. Compõe os runners existentes — zero check reimplementado. "A casa está coerente?" num
16
+ comando, não num checklist lembrado.
17
+ - **`agent-topology`** (check no `tools:doctor`, SPEC-019): a topologia de orquestração é descrita em
18
+ três fontes (`VALID_AGENTS`, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio. O
19
+ check as cruza e reprova quando não concordam. Pegou o `release-auditor` (sub-agent executável sem
20
+ rota) na 1ª execução — agora first-class no router e documentado (AGENTS.md §7).
21
+
22
+ ### Corrigido / interno
23
+ - **`generators.test` migrado para `node:test`**: o harness custom legado não contava suas falhas no
24
+ tally do CI e vazava um `/tmp` por execução (588 diretórios acumulados). Agora é `node:test` com
25
+ cleanup — falha derruba o CI de verdade.
26
+
27
+ ---
28
+
29
+ ## [1.5.0] — 2026-07-19 — A memória como sistema fechado: medir → entregar → proteger → propagar
30
+
31
+ A economia de token do Forja sempre foi a memória persistente (ADR-0009), mas era uma promessa. Esta
32
+ release a torna um ciclo completo e verificável — cada peça fecha um elo.
33
+
34
+ ### Adicionado
35
+ - **`code:context <domínio>`** (SPEC-016): **entrega** o mapa da memória como pacote pronto para
36
+ colar (o `context.md`), com `--code` para o código da fatia e o custo em token à mostra. É o −61%
37
+ medido no `token:economy` virado ferramenta. Compõe com `code:impact` para o blast radius.
38
+ - **`memory:audit`** (SPEC-017): **protege** o mapa nas duas direções — reprova se um `context.md`
39
+ cita código que não existe (mapa que mente é pior que mapa nenhum) e avisa sobre módulo de código
40
+ sem mapa (economia perdida em silêncio). O `adr-refs` aplicado aos mapas de memória.
41
+ - **`token:economy --project <path>`**: mede o eixo memória nos **domínios reais do usuário** (mapa
42
+ vs código, por domínio) — o número fica dele, não da fixture.
43
+ - **`project:upgrade`** (SPEC-018): a metade que faltava do scaffolder. Traz peças novas de scaffold
44
+ para um projeto já gerado — **aditivo, nunca sobrescreve** (o código do usuário é intocável).
45
+ Dry-run por padrão; `--apply` copia.
46
+ - **O projeto gerado herda o gate** (ADR-0030): o gerador emite `scripts/check-memory-maps.mjs`, um
47
+ `memory:audit` self-contained (Node puro, zero dep), e o `project:smoke` prova a propagação. O
48
+ invariante da coerência mapa↔código passa a viajar com cada projeto.
49
+
50
+ ### Nota
51
+ - Comandos e gates novos do framework; nada muda para projetos já gerados até rodarem `project:upgrade`.
52
+
53
+ ---
54
+
55
+ ## [1.4.0] — 2026-07-19 — Governança que mede: gate do gerador, economia de token e integridade de ADR
56
+
57
+ Três fronteiras que viviam por disciplina viram harness — e cada uma provou seu valor pegando um
58
+ problema real na estreia.
59
+
60
+ ### Adicionado
61
+ - **`project:smoke`** (SPEC-015, ADR-0029): o gate do projeto gerado. Gera um projeto num tmp isolado
62
+ e prova que é coerente — zero placeholder `{{...}}` vazado, `package.json` válido, estrutura íntegra
63
+ (reusa o `structure-validator`). Tier `--full` (opt-in): `npm install` + `npm run build` do backend
64
+ gerado. É o `release:check` da saída do gerador, um nível acima do tarball.
65
+ - **`token:economy`** (fecha a dívida do ADR-0027; mede ADR-0009): mede a economia de token em dois
66
+ eixos, com file-sets explícitos. **Eixo arquitetura** (clean vs flat, mesma feature): camadas
67
+ custam **+56%** numa feature pequena — a versão ingênua de "Clean Architecture economiza tokens"
68
+ não se sustenta. **Eixo memória** (frio vs quente): o `context.md` (mapa) faz o contexto mínimo
69
+ custar **−61%** vs varrer a fatia no frio — e isso **compõe** a cada tarefa. A economia do Forja é
70
+ da memória persistente, amortizada no tempo, não das camadas. Narrativa corrigida no
71
+ `WHEN-CLEAN-WHEN-LEAN.md` e no ADR-0027.
72
+ - **`adr-refs`** (check no `tools:doctor`, ADR-0025): toda citação `ADR-NNNN` aponta para um ADR que
73
+ existe. Na 1ª execução pegou o `ADR-0026` pendurado (citado pela SPEC-012, nunca escrito) — fechado
74
+ escrevendo o **ADR-0026** (arquitetura da migração TS: resolver, runtime duplo, gate-builda-dist).
75
+
76
+ ### Nota
77
+ - Nada muda para quem já tem projetos gerados; são comandos e gates novos do framework.
78
+
79
+ ---
80
+
7
81
  ## [1.3.2] — 2026-07-19 — Migração TypeScript concluída (interno)
8
82
 
9
83
  **Sem mudança para quem instala** — o `dist/*.js` publicado é idêntico ao da 1.3.1. Fecha a SPEC-012.
package/README.en.md CHANGED
@@ -202,6 +202,7 @@ forja memory:extract # extract global knowledge from memor
202
202
  forja project:check # framework standards (pre-commit)
203
203
  forja tools:doctor # core X-ray; exit 1 if broken
204
204
  forja release:check --publish # tarball gate before publishing
205
+ forja project:smoke # generated-project gate; --full installs and builds the backend
205
206
  forja project:dashboard # static status report
206
207
 
207
208
  # Governance & audit
package/README.md CHANGED
@@ -165,6 +165,7 @@ Os scripts npm do repo são aliases finos que roteiam pelo core.
165
165
  forja workspace:init # cria ~/forja-workspace
166
166
  forja project:new <nome> --ai claude,copilot # cria projeto no workspace
167
167
  forja project:list # lista projetos do workspace
168
+ forja project:upgrade # traz peças novas de scaffold p/ um projeto (aditivo; --apply)
168
169
  forja workspace:project:check <nome> # valida padrões num projeto do workspace
169
170
 
170
171
  # Pipeline SDD
@@ -179,19 +180,24 @@ forja gsd:check <slug> # gates básicos do runbook
179
180
  # Análise de código (codegraph)
180
181
  forja code:check # índice confiável (worktree + freshness)
181
182
  forja code:impact <símbolo> # chamadores + blast radius antes de editar
183
+ forja code:context <domínio> # pacote de contexto mínimo (o mapa; --code p/ o código)
182
184
  forja code:query "<termo>" # também: code:index · code:sync · code:status
183
185
 
184
186
  # Memória & contexto (workspace)
185
187
  forja sync:universal # reindexa SQLite FTS5 do workspace
186
188
  forja query:universal "<query>" # busca FTS5
187
189
  forja context:smart # smart-context (3 modos, ADR-0003)
190
+ forja token:economy [--project <path>] # economia de token; --project mede seus domínios reais (ADR-0009)
188
191
  forja memory:compress # arquiva runs antigos + VACUUM
189
192
  forja memory:extract # extrai conhecimento global da memória
193
+ forja memory:audit # coerência mapa↔código: mapa não mente + módulo sem mapa (SPEC-017)
190
194
 
191
195
  # Qualidade & release
192
196
  forja project:check # standards do framework (pre-commit)
193
197
  forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
194
198
  forja release:check --publish # gate do tarball antes de publicar
199
+ forja project:smoke # gate do projeto gerado; --full instala e builda o backend
200
+ forja check:all # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
195
201
  forja project:dashboard # relatório estático de status
196
202
 
197
203
  # Governança & auditoria
@@ -280,10 +286,11 @@ gerados.
280
286
 
281
287
  **Próximos passos** (por dependência, não por desejo)
282
288
 
283
- - [ ] **Fechar a migração TypeScript** — publicar `dist/` e renomear `.mjs → .ts`. Pipeline provado;
284
- a fonte segue `.mjs` (Node ≥ 20) até lá.
285
- - [ ] **Benchmark de token do clean-arch** — a economia é argumentada, não provada (ADR-0027):
286
- medir a mesma feature nas duas arquiteturas via `context:smart`. Provar ou recalibrar.
289
+ - [x] **Migração TypeScript fechada** — fonte 100% `.ts`, publica `dist/`, `noImplicitAny` ON
290
+ (SPEC-012, v1.3.x).
291
+ - [x] **Benchmark de token do clean-arch** — medido, não mais argumentado (`forja token:economy`,
292
+ ADR-0027). Veredito honesto: para feature pequena o flat é mais barato; a economia do clean-arch é
293
+ função da escala, e a justificativa das camadas é **isolamento**, não token.
287
294
  - [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
288
295
  `release:check` em vez de reimplementar o procedimento em prosa.
289
296
  - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
@@ -24,16 +24,45 @@ Use o padrão de `products/` (uma camada) quando **todas** forem verdade:
24
24
  - O "modelo" é a tabela: não há comportamento a proteger.
25
25
  - Não há transição de estado que importe.
26
26
 
27
- ## Por que isso é economia de token, não estética
27
+ ## O que a medição diz (e o que ela desmente)
28
28
 
29
- Um agente que vai adicionar uma regra ao contexto `orders` lê o `context.md` do domínio (linguagem
30
- ubíqua) e a **assinatura** do use-case — e sabe o que fazer sem carregar a implementação inteira. As
31
- camadas dão pontos de entrada previsíveis: a regra vai no agregado, o caso de uso na aplicação, o
32
- mapeamento na infra. Menos exploração, menos tokens.
29
+ Rode `forja token:economy` — ele mede a **mesma feature** (place + ship, com a invariante "não envia
30
+ sem pagamento") nos dois estilos, por cenário. Os números, hoje, para a fatia `orders`:
33
31
 
34
- O mesmo agente, num CRUD, não deveria pagar esse preço de leitura. Por isso `products/` é raso: para
35
- um `GET /products`, quatro camadas seriam quatro arquivos a mais para ler, sem nada a proteger — o
36
- **oposto** de economia de token, com nome de arquitetura.
32
+ | Cenário | Clean (camadas) | Flat (uma camada) | Clean vs flat |
33
+ |---|---|---|---|
34
+ | Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
35
+ | Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
36
+
37
+ **Para uma feature pequena, o clean-arch custa MAIS tokens — nos dois cenários.** A camada cobra
38
+ adiantado, e para duas operações ela não se paga. Se alguém te vendeu "Clean Architecture economiza
39
+ tokens" como regra geral, os números acima desmentem — e tudo bem que desmintam.
40
+
41
+ Então **por que promover `orders` a camadas não é desperdício?** Porque a economia de token não é
42
+ função do total de arquivos; é função do **tamanho da feature e do número de casos de uso**. O ganho
43
+ aparece quando o service flat cresce: com dez casos de uso, mudar uma regra obriga a ler um service
44
+ gordo inteiro (tudo misturado), enquanto no clean o agregado isolado continua pequeno e o `context.md`
45
+ aponta direto para ele. O cruzamento existe; para a `orders` de duas operações, ele ainda não chegou.
46
+
47
+ O que justifica as camadas em `orders` **não é token** — é **isolamento e testabilidade**: a
48
+ invariante tem um lar único, testável sem subir o Nest, e sobrevive à troca de ORM. Token é
49
+ consequência a partir de certa escala, não a razão. Por isso o critério acima fala de invariante e
50
+ máquina de estados, não de contagem de linhas.
51
+
52
+ O `products/` raso segue certo pelo mesmo motivo invertido: um CRUD não tem invariante para isolar,
53
+ então as camadas seriam só custo — de token, medido, e de leitura.
54
+
55
+ ## Onde a economia de token realmente está: a memória, não as camadas
56
+
57
+ Se as camadas custam token, de onde vem a economia que o Forja promete? Da **memória persistente**,
58
+ não da arquitetura. O `token:economy` mede também esse eixo: para mexer numa regra da fatia, ler o
59
+ `context.md` (o mapa do domínio) + ir direto ao agregado custa **−61%** vs varrer a fatia inteira no
60
+ frio, sem mapa. E essa economia **compõe**: gerar o projeto do zero é custo único; o mapa poupa a
61
+ cada tarefa futura, pela vida do projeto. É a tese do ADR-0009, agora medida.
62
+
63
+ Ou seja: você paga tokens para levantar o scaffold, e a memória devolve a partir da segunda tarefa.
64
+ As camadas de `orders` são sobre isolamento; a economia de token é da memória. São coisas diferentes,
65
+ e confundi-las foi o erro que a medição corrigiu.
37
66
 
38
67
  ## A regra de ouro
39
68
 
@@ -0,0 +1,38 @@
1
+ /**
2
+ * lib/agent-topology.ts — a topologia de orquestração é uma só, descrita em três lugares (SPEC-019).
3
+ *
4
+ * O nome do framework é orquestração multiagente, e quem-orquestra-quem vive em três fontes que podem
5
+ * divergir em silêncio:
6
+ *
7
+ * 1. `scripts/agent-router.ts` (`VALID_AGENTS`) — para quem um handoff pode ser roteado.
8
+ * 2. `.claude/agents/*.md` — os sub-agents executáveis (quem faz o trabalho).
9
+ * 3. `AGENTS.md` — a prosa que documenta os papéis.
10
+ *
11
+ * Este módulo extrai as três e aponta onde não concordam. É o `adr-refs` da orquestração.
12
+ */
13
+ import fs from 'node:fs';
14
+ export interface TopologyEnv {
15
+ fs: typeof fs;
16
+ root: string;
17
+ }
18
+ /**
19
+ * Endpoints de handoff que NÃO são sub-agents especialistas e por isso não têm `.claude/agent`:
20
+ * - `user` — o humano.
21
+ * - `worker` — o agente implementador principal (o Claude que executa), não um especialista spawnado.
22
+ */
23
+ export declare const ENDPOINTS: Set<string>;
24
+ /** Os agentes para os quais o router aceita rotear (`VALID_AGENTS` de agent-router.ts). */
25
+ export declare function routerAgents(env: TopologyEnv): string[];
26
+ /** Os sub-agents executáveis: os arquivos `.claude/agents/*.md` (menos README). */
27
+ export declare function subAgents(env: TopologyEnv): string[];
28
+ /** True se `name` é citado no AGENTS.md (documentado na prosa da topologia). */
29
+ export declare function documentedInAgentsMd(env: TopologyEnv, name: string): boolean;
30
+ export interface TopologyIssues {
31
+ /** Sub-agent executável que o router não conhece — implementação que a orquestração não alcança. */
32
+ unrouted: string[];
33
+ /** Papel roteável (não-endpoint) sem `.claude/agent` — o router promete um destino sem executor. */
34
+ missingExecutor: string[];
35
+ /** Sub-agent não citado no AGENTS.md — implementação sem documentação na topologia. */
36
+ undocumented: string[];
37
+ }
38
+ export declare function topologyIssues(env: TopologyEnv): TopologyIssues;
@@ -0,0 +1,65 @@
1
+ /**
2
+ * lib/agent-topology.ts — a topologia de orquestração é uma só, descrita em três lugares (SPEC-019).
3
+ *
4
+ * O nome do framework é orquestração multiagente, e quem-orquestra-quem vive em três fontes que podem
5
+ * divergir em silêncio:
6
+ *
7
+ * 1. `scripts/agent-router.ts` (`VALID_AGENTS`) — para quem um handoff pode ser roteado.
8
+ * 2. `.claude/agents/*.md` — os sub-agents executáveis (quem faz o trabalho).
9
+ * 3. `AGENTS.md` — a prosa que documenta os papéis.
10
+ *
11
+ * Este módulo extrai as três e aponta onde não concordam. É o `adr-refs` da orquestração.
12
+ */
13
+ import path from 'node:path';
14
+ /**
15
+ * Endpoints de handoff que NÃO são sub-agents especialistas e por isso não têm `.claude/agent`:
16
+ * - `user` — o humano.
17
+ * - `worker` — o agente implementador principal (o Claude que executa), não um especialista spawnado.
18
+ */
19
+ export const ENDPOINTS = new Set(['user', 'worker']);
20
+ /** Os agentes para os quais o router aceita rotear (`VALID_AGENTS` de agent-router.ts). */
21
+ export function routerAgents(env) {
22
+ try {
23
+ const src = env.fs.readFileSync(path.join(env.root, 'scripts', 'agent-router.ts'), 'utf8');
24
+ const m = src.match(/VALID_AGENTS\s*=\s*\[([^\]]*)\]/);
25
+ if (!m)
26
+ return [];
27
+ return [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
28
+ }
29
+ catch {
30
+ return [];
31
+ }
32
+ }
33
+ /** Os sub-agents executáveis: os arquivos `.claude/agents/*.md` (menos README). */
34
+ export function subAgents(env) {
35
+ try {
36
+ return env.fs
37
+ .readdirSync(path.join(env.root, '.claude', 'agents'))
38
+ .filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md')
39
+ .map((f) => f.replace(/\.md$/, ''))
40
+ .sort();
41
+ }
42
+ catch {
43
+ return [];
44
+ }
45
+ }
46
+ /** True se `name` é citado no AGENTS.md (documentado na prosa da topologia). */
47
+ export function documentedInAgentsMd(env, name) {
48
+ try {
49
+ const src = env.fs.readFileSync(path.join(env.root, 'AGENTS.md'), 'utf8').toLowerCase();
50
+ // Casa o nome exato como palavra (sdd-architect, context-engineer, release-auditor).
51
+ return new RegExp(`\\b${name.replace(/[-]/g, '[- ]')}\\b`).test(src);
52
+ }
53
+ catch {
54
+ return false;
55
+ }
56
+ }
57
+ export function topologyIssues(env) {
58
+ const router = new Set(routerAgents(env));
59
+ const agents = subAgents(env);
60
+ const agentSet = new Set(agents);
61
+ const unrouted = agents.filter((a) => !router.has(a) && !ENDPOINTS.has(a));
62
+ const missingExecutor = [...router].filter((r) => !ENDPOINTS.has(r) && !agentSet.has(r));
63
+ const undocumented = agents.filter((a) => !ENDPOINTS.has(a) && !documentedInAgentsMd(env, a));
64
+ return { unrouted, missingExecutor, undocumented };
65
+ }
@@ -0,0 +1,41 @@
1
+ /**
2
+ * lib/code-context.ts — monta o pacote de contexto mínimo de um domínio (SPEC-016, ADR-0009).
3
+ *
4
+ * A economia de token do Forja é da memória persistente: o `context.md` (o mapa) faz um agente ir
5
+ * direto ao agregado em vez de varrer a fatia no frio — medido em −61% pelo `token:economy`. Mas até
6
+ * agora esse mapa era só um arquivo que alguém lembrava de ler. Este módulo o entrega como **pacote
7
+ * pronto**: o mapa por padrão, o código da fatia sob demanda, com o custo em token à mostra.
8
+ *
9
+ * É o `context:smart` do eixo código — o −61% virado ferramenta, não medição.
10
+ */
11
+ import fs from 'node:fs';
12
+ export interface CodeContextEnv {
13
+ fs: typeof fs;
14
+ }
15
+ /** Tokens ≈ bytes/4 — o mesmo proxy do resto do framework. */
16
+ export declare function estimateTokens(text: string): number;
17
+ /** Domínios disponíveis num projeto: os diretórios sob `memory/30-domains/`. */
18
+ export declare function domainsOf(projectRoot: string, env?: CodeContextEnv): string[];
19
+ export interface ContextPack {
20
+ domain: string;
21
+ found: boolean;
22
+ mapPath: string | null;
23
+ map: string | null;
24
+ mapTokens: number;
25
+ code: {
26
+ path: string;
27
+ tokens: number;
28
+ content: string;
29
+ }[];
30
+ codeTokens: number;
31
+ totalTokens: number;
32
+ }
33
+ /**
34
+ * Monta o pacote de um domínio. Por padrão só o mapa (`context.md`) — o contexto barato que substitui
35
+ * a exploração. Com `includeCode`, anexa o código da fatia — o que se lê ao *editar*.
36
+ */
37
+ export declare function buildContextPack({ projectRoot, domain, includeCode }: {
38
+ projectRoot: string;
39
+ domain: string;
40
+ includeCode?: boolean;
41
+ }, env?: CodeContextEnv): ContextPack;
@@ -0,0 +1,108 @@
1
+ /**
2
+ * lib/code-context.ts — monta o pacote de contexto mínimo de um domínio (SPEC-016, ADR-0009).
3
+ *
4
+ * A economia de token do Forja é da memória persistente: o `context.md` (o mapa) faz um agente ir
5
+ * direto ao agregado em vez de varrer a fatia no frio — medido em −61% pelo `token:economy`. Mas até
6
+ * agora esse mapa era só um arquivo que alguém lembrava de ler. Este módulo o entrega como **pacote
7
+ * pronto**: o mapa por padrão, o código da fatia sob demanda, com o custo em token à mostra.
8
+ *
9
+ * É o `context:smart` do eixo código — o −61% virado ferramenta, não medição.
10
+ */
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+ const defaultFsEnv = { fs };
14
+ /** Tokens ≈ bytes/4 — o mesmo proxy do resto do framework. */
15
+ export function estimateTokens(text) {
16
+ return Math.round(text.length / 4);
17
+ }
18
+ /** Domínios disponíveis num projeto: os diretórios sob `memory/30-domains/`. */
19
+ export function domainsOf(projectRoot, env = defaultFsEnv) {
20
+ const dir = path.join(projectRoot, 'memory', '30-domains');
21
+ try {
22
+ return env.fs
23
+ .readdirSync(dir)
24
+ .filter((e) => {
25
+ try {
26
+ return env.fs.statSync(path.join(dir, e)).isDirectory();
27
+ }
28
+ catch {
29
+ return false;
30
+ }
31
+ })
32
+ .sort();
33
+ }
34
+ catch {
35
+ return [];
36
+ }
37
+ }
38
+ /** Todo `.ts` sob o diretório do módulo (`backend/src/modules/<domain>/`), menos node_modules. */
39
+ function moduleFiles(projectRoot, domain, env) {
40
+ const base = path.join(projectRoot, 'backend', 'src', 'modules', domain);
41
+ const out = [];
42
+ const walk = (dir) => {
43
+ let entries;
44
+ try {
45
+ entries = env.fs.readdirSync(dir);
46
+ }
47
+ catch {
48
+ return;
49
+ }
50
+ for (const e of entries) {
51
+ if (e === 'node_modules')
52
+ continue;
53
+ const p = path.join(dir, e);
54
+ let st;
55
+ try {
56
+ st = env.fs.statSync(p);
57
+ }
58
+ catch {
59
+ continue;
60
+ }
61
+ if (st.isDirectory())
62
+ walk(p);
63
+ else if (e.endsWith('.ts'))
64
+ out.push(p);
65
+ }
66
+ };
67
+ walk(base);
68
+ return out.sort();
69
+ }
70
+ /**
71
+ * Monta o pacote de um domínio. Por padrão só o mapa (`context.md`) — o contexto barato que substitui
72
+ * a exploração. Com `includeCode`, anexa o código da fatia — o que se lê ao *editar*.
73
+ */
74
+ export function buildContextPack({ projectRoot, domain, includeCode = false }, env = defaultFsEnv) {
75
+ const mapPath = path.join(projectRoot, 'memory', '30-domains', domain, 'context.md');
76
+ let map = null;
77
+ try {
78
+ map = env.fs.readFileSync(mapPath, 'utf8');
79
+ }
80
+ catch {
81
+ map = null;
82
+ }
83
+ const code = [];
84
+ if (includeCode) {
85
+ for (const file of moduleFiles(projectRoot, domain, env)) {
86
+ let content = '';
87
+ try {
88
+ content = env.fs.readFileSync(file, 'utf8');
89
+ }
90
+ catch {
91
+ continue;
92
+ }
93
+ code.push({ path: path.relative(projectRoot, file), tokens: estimateTokens(content), content });
94
+ }
95
+ }
96
+ const mapTokens = map ? estimateTokens(map) : 0;
97
+ const codeTokens = code.reduce((acc, c) => acc + c.tokens, 0);
98
+ return {
99
+ domain,
100
+ found: map != null,
101
+ mapPath: map != null ? path.relative(projectRoot, mapPath) : null,
102
+ map,
103
+ mapTokens,
104
+ code,
105
+ codeTokens,
106
+ totalTokens: mapTokens + codeTokens,
107
+ };
108
+ }
@@ -41,6 +41,19 @@ export declare function scanLinks(env: any): {
41
41
  target: string;
42
42
  resolved: string;
43
43
  }[];
44
+ /** Números de ADR que existem de fato como arquivo (`NNNN-*.md`, sem `_template`). */
45
+ export declare function adrNumbers(env: any): Set<string>;
46
+ /**
47
+ * Toda citação `ADR-NNNN` nas superfícies de instrução, specs e ADRs. É o `scanLinks` das
48
+ * referências arquiteturais: um número que não existe é uma referência pendurada — trilha que apodrece.
49
+ * @returns {{ file: string, line: number, ref: string, num: string }[]}
50
+ */
51
+ export declare function scanAdrRefs(env: any): {
52
+ file: string;
53
+ line: number;
54
+ ref: string;
55
+ num: string;
56
+ }[];
44
57
  /**
45
58
  * Allowlist **derivada** dos comandos que pertencem ao projeto que o Forja *gera* (`start:dev`,
46
59
  * `test:cov`, `test:e2e`, `memory:db:*`), não ao Forja. Nunca uma lista literal — uma lista manual
@@ -138,6 +138,53 @@ export function scanLinks(env) {
138
138
  }
139
139
  return hits;
140
140
  }
141
+ /** Superfícies onde um ADR pode ser citado: as de instrução + as specs + os próprios ADRs. */
142
+ const ADR_REF_SURFACES = [...DOC_SURFACES, 'specs', 'memory/90-decisions'];
143
+ const ADR_REF_RE = /ADR-(\d{4})/g;
144
+ /** Números de ADR que existem de fato como arquivo (`NNNN-*.md`, sem `_template`). */
145
+ export function adrNumbers(env) {
146
+ const dir = path.join(env.root, 'memory', '90-decisions');
147
+ const out = new Set();
148
+ let entries;
149
+ try {
150
+ entries = env.fs.readdirSync(dir);
151
+ }
152
+ catch {
153
+ return out;
154
+ }
155
+ for (const e of entries) {
156
+ const m = e.match(/^(\d{4})-.*\.md$/);
157
+ if (m)
158
+ out.add(m[1]);
159
+ }
160
+ return out;
161
+ }
162
+ /**
163
+ * Toda citação `ADR-NNNN` nas superfícies de instrução, specs e ADRs. É o `scanLinks` das
164
+ * referências arquiteturais: um número que não existe é uma referência pendurada — trilha que apodrece.
165
+ * @returns {{ file: string, line: number, ref: string, num: string }[]}
166
+ */
167
+ export function scanAdrRefs(env) {
168
+ const hits = [];
169
+ const seen = new Set();
170
+ for (const surface of ADR_REF_SURFACES) {
171
+ for (const file of collectMarkdown(env, surface)) {
172
+ const rel = path.relative(env.root, file);
173
+ if (seen.has(rel))
174
+ continue;
175
+ seen.add(rel);
176
+ const src = safeRead(env, file);
177
+ if (src == null)
178
+ continue;
179
+ src.split('\n').forEach((text, i) => {
180
+ for (const m of text.matchAll(ADR_REF_RE)) {
181
+ hits.push({ file: rel, line: i + 1, ref: m[0], num: m[1] });
182
+ }
183
+ });
184
+ }
185
+ }
186
+ return hits;
187
+ }
141
188
  /** Extrai as keys de todo bloco `"scripts": { … }` de um fonte de gerador. */
142
189
  function scriptKeys(source) {
143
190
  const keys = new Set();
@@ -0,0 +1,36 @@
1
+ /**
2
+ * lib/core/gates.ts — a bateria inteira, um veredito (SPEC-020).
3
+ *
4
+ * O framework acumulou uma família de gates — doctor (núcleo + coerência), release (tarball), smoke
5
+ * (projeto gerado). Cada um guarda uma fronteira, mas rodá-los todos era disciplina: a governança que
6
+ * existe para não depender de memória dependia da memória de quem lembra de invocar os gates.
7
+ *
8
+ * Este módulo **compõe** os runners que já existem — não reimplementa nenhum check. Uma máquina que
9
+ * chama as outras máquinas, e reduz tudo a um `worstStatus`.
10
+ */
11
+ import { worstStatus } from './health.ts';
12
+ export interface GateGroup {
13
+ name: string;
14
+ results: any[];
15
+ }
16
+ /** Runners injetáveis — em produção, os catálogos reais; no teste, fakes com status conhecidos. */
17
+ export interface GatesDeps {
18
+ health?: () => Promise<any[]>;
19
+ smoke?: (opts: {
20
+ full: boolean;
21
+ }) => Promise<any[]>;
22
+ release?: () => Promise<any[]>;
23
+ }
24
+ /**
25
+ * Roda os gates aplicáveis ao framework e devolve os resultados agrupados por gate.
26
+ *
27
+ * Tier barato (default): coerência (doctor) + projeto gerado (smoke barato). `--full` adiciona os
28
+ * caros: o tarball (release) e o build do gerado (smoke --full).
29
+ */
30
+ export declare function runGates({ full, deps }?: {
31
+ full?: boolean;
32
+ deps?: GatesDeps;
33
+ }): Promise<GateGroup[]>;
34
+ /** O pior status entre todos os gates — o veredito único. */
35
+ export declare function overallStatus(groups: GateGroup[]): string;
36
+ export { worstStatus };
@@ -0,0 +1,35 @@
1
+ /**
2
+ * lib/core/gates.ts — a bateria inteira, um veredito (SPEC-020).
3
+ *
4
+ * O framework acumulou uma família de gates — doctor (núcleo + coerência), release (tarball), smoke
5
+ * (projeto gerado). Cada um guarda uma fronteira, mas rodá-los todos era disciplina: a governança que
6
+ * existe para não depender de memória dependia da memória de quem lembra de invocar os gates.
7
+ *
8
+ * Este módulo **compõe** os runners que já existem — não reimplementa nenhum check. Uma máquina que
9
+ * chama as outras máquinas, e reduz tudo a um `worstStatus`.
10
+ */
11
+ import { runChecks as runHealthChecks, worstStatus } from "./health.js";
12
+ import { runProjectSmoke } from "./project-smoke.js";
13
+ import { runReleaseChecks } from "./release.js";
14
+ /**
15
+ * Roda os gates aplicáveis ao framework e devolve os resultados agrupados por gate.
16
+ *
17
+ * Tier barato (default): coerência (doctor) + projeto gerado (smoke barato). `--full` adiciona os
18
+ * caros: o tarball (release) e o build do gerado (smoke --full).
19
+ */
20
+ export async function runGates({ full = false, deps = {} } = {}) {
21
+ const health = deps.health ?? (() => runHealthChecks());
22
+ const smoke = deps.smoke ?? ((o) => runProjectSmoke(o));
23
+ const release = deps.release ?? (() => runReleaseChecks({}));
24
+ const groups = [];
25
+ groups.push({ name: 'núcleo & coerência', results: await health() });
26
+ groups.push({ name: 'projeto gerado', results: await smoke({ full }) });
27
+ if (full)
28
+ groups.push({ name: 'tarball (instalação limpa)', results: await release() });
29
+ return groups;
30
+ }
31
+ /** O pior status entre todos os gates — o veredito único. */
32
+ export function overallStatus(groups) {
33
+ return worstStatus(groups.flatMap((g) => g.results));
34
+ }
35
+ export { worstStatus };