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
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
|
-
- [
|
|
284
|
-
|
|
285
|
-
- [
|
|
286
|
-
|
|
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
|
-
##
|
|
27
|
+
## O que a medição diz (e o que ela desmente)
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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 };
|