forjajs 1.3.2 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +52 -0
- package/README.en.md +1 -0
- package/README.md +10 -4
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
- 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/health.js +29 -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 +25 -0
- package/dist/lib/core/registry.js +25 -0
- package/dist/lib/core/release.d.ts +25 -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/code-context.d.ts +12 -0
- package/dist/scripts/code-context.js +73 -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 +4 -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/memory-audit/spec.md +54 -0
- package/specs/project-smoke/spec.md +96 -0
- package/specs/project-upgrade/spec.md +58 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,58 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.5.0] — 2026-07-19 — A memória como sistema fechado: medir → entregar → proteger → propagar
|
|
8
|
+
|
|
9
|
+
A economia de token do Forja sempre foi a memória persistente (ADR-0009), mas era uma promessa. Esta
|
|
10
|
+
release a torna um ciclo completo e verificável — cada peça fecha um elo.
|
|
11
|
+
|
|
12
|
+
### Adicionado
|
|
13
|
+
- **`code:context <domínio>`** (SPEC-016): **entrega** o mapa da memória como pacote pronto para
|
|
14
|
+
colar (o `context.md`), com `--code` para o código da fatia e o custo em token à mostra. É o −61%
|
|
15
|
+
medido no `token:economy` virado ferramenta. Compõe com `code:impact` para o blast radius.
|
|
16
|
+
- **`memory:audit`** (SPEC-017): **protege** o mapa nas duas direções — reprova se um `context.md`
|
|
17
|
+
cita código que não existe (mapa que mente é pior que mapa nenhum) e avisa sobre módulo de código
|
|
18
|
+
sem mapa (economia perdida em silêncio). O `adr-refs` aplicado aos mapas de memória.
|
|
19
|
+
- **`token:economy --project <path>`**: mede o eixo memória nos **domínios reais do usuário** (mapa
|
|
20
|
+
vs código, por domínio) — o número fica dele, não da fixture.
|
|
21
|
+
- **`project:upgrade`** (SPEC-018): a metade que faltava do scaffolder. Traz peças novas de scaffold
|
|
22
|
+
para um projeto já gerado — **aditivo, nunca sobrescreve** (o código do usuário é intocável).
|
|
23
|
+
Dry-run por padrão; `--apply` copia.
|
|
24
|
+
- **O projeto gerado herda o gate** (ADR-0030): o gerador emite `scripts/check-memory-maps.mjs`, um
|
|
25
|
+
`memory:audit` self-contained (Node puro, zero dep), e o `project:smoke` prova a propagação. O
|
|
26
|
+
invariante da coerência mapa↔código passa a viajar com cada projeto.
|
|
27
|
+
|
|
28
|
+
### Nota
|
|
29
|
+
- Comandos e gates novos do framework; nada muda para projetos já gerados até rodarem `project:upgrade`.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## [1.4.0] — 2026-07-19 — Governança que mede: gate do gerador, economia de token e integridade de ADR
|
|
34
|
+
|
|
35
|
+
Três fronteiras que viviam por disciplina viram harness — e cada uma provou seu valor pegando um
|
|
36
|
+
problema real na estreia.
|
|
37
|
+
|
|
38
|
+
### Adicionado
|
|
39
|
+
- **`project:smoke`** (SPEC-015, ADR-0029): o gate do projeto gerado. Gera um projeto num tmp isolado
|
|
40
|
+
e prova que é coerente — zero placeholder `{{...}}` vazado, `package.json` válido, estrutura íntegra
|
|
41
|
+
(reusa o `structure-validator`). Tier `--full` (opt-in): `npm install` + `npm run build` do backend
|
|
42
|
+
gerado. É o `release:check` da saída do gerador, um nível acima do tarball.
|
|
43
|
+
- **`token:economy`** (fecha a dívida do ADR-0027; mede ADR-0009): mede a economia de token em dois
|
|
44
|
+
eixos, com file-sets explícitos. **Eixo arquitetura** (clean vs flat, mesma feature): camadas
|
|
45
|
+
custam **+56%** numa feature pequena — a versão ingênua de "Clean Architecture economiza tokens"
|
|
46
|
+
não se sustenta. **Eixo memória** (frio vs quente): o `context.md` (mapa) faz o contexto mínimo
|
|
47
|
+
custar **−61%** vs varrer a fatia no frio — e isso **compõe** a cada tarefa. A economia do Forja é
|
|
48
|
+
da memória persistente, amortizada no tempo, não das camadas. Narrativa corrigida no
|
|
49
|
+
`WHEN-CLEAN-WHEN-LEAN.md` e no ADR-0027.
|
|
50
|
+
- **`adr-refs`** (check no `tools:doctor`, ADR-0025): toda citação `ADR-NNNN` aponta para um ADR que
|
|
51
|
+
existe. Na 1ª execução pegou o `ADR-0026` pendurado (citado pela SPEC-012, nunca escrito) — fechado
|
|
52
|
+
escrevendo o **ADR-0026** (arquitetura da migração TS: resolver, runtime duplo, gate-builda-dist).
|
|
53
|
+
|
|
54
|
+
### Nota
|
|
55
|
+
- Nada muda para quem já tem projetos gerados; são comandos e gates novos do framework.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
7
59
|
## [1.3.2] — 2026-07-19 — Migração TypeScript concluída (interno)
|
|
8
60
|
|
|
9
61
|
**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,23 @@ 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
|
|
195
200
|
forja project:dashboard # relatório estático de status
|
|
196
201
|
|
|
197
202
|
# Governança & auditoria
|
|
@@ -280,10 +285,11 @@ gerados.
|
|
|
280
285
|
|
|
281
286
|
**Próximos passos** (por dependência, não por desejo)
|
|
282
287
|
|
|
283
|
-
- [
|
|
284
|
-
|
|
285
|
-
- [
|
|
286
|
-
|
|
288
|
+
- [x] **Migração TypeScript fechada** — fonte 100% `.ts`, publica `dist/`, `noImplicitAny` ON
|
|
289
|
+
(SPEC-012, v1.3.x).
|
|
290
|
+
- [x] **Benchmark de token do clean-arch** — medido, não mais argumentado (`forja token:economy`,
|
|
291
|
+
ADR-0027). Veredito honesto: para feature pequena o flat é mais barato; a economia do clean-arch é
|
|
292
|
+
função da escala, e a justificativa das camadas é **isolamento**, não token.
|
|
287
293
|
- [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
|
|
288
294
|
`release:check` em vez de reimplementar o procedimento em prosa.
|
|
289
295
|
- [ ] **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,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();
|
package/dist/lib/core/health.js
CHANGED
|
@@ -38,7 +38,7 @@ import { fileURLToPath } from 'node:url';
|
|
|
38
38
|
import { getWorkspaceDbPath, getWorkspaceInfo } from "../workspace.js";
|
|
39
39
|
import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from "./checks.js";
|
|
40
40
|
import { COMMANDS } from "./registry.js";
|
|
41
|
-
import { scanCommands, scanLinks, projectCommands } from "./doc-graph.js";
|
|
41
|
+
import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers } from "./doc-graph.js";
|
|
42
42
|
/** @typedef {import('./checks.ts').Status} Status */
|
|
43
43
|
// O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
|
|
44
44
|
// aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
|
|
@@ -495,6 +495,33 @@ const docsLinks = {
|
|
|
495
495
|
return { status: 'ok', detail: 'todo link relativo resolve', fix: null };
|
|
496
496
|
},
|
|
497
497
|
};
|
|
498
|
+
/**
|
|
499
|
+
* Referência a decisão que não existe é trilha que apodrece. Uma spec ou doc cita `ADR-0026`, o ADR
|
|
500
|
+
* nunca foi escrito (ou foi renumerado), e o paper trail mente em silêncio. `warn`, não `critical`:
|
|
501
|
+
* confunde o registro, não impede o framework de trabalhar — mesma família de `docs-links`.
|
|
502
|
+
*/
|
|
503
|
+
const adrRefs = {
|
|
504
|
+
id: 'adr-refs',
|
|
505
|
+
title: 'toda citação ADR-NNNN aponta para um ADR existente',
|
|
506
|
+
severity: 'warn',
|
|
507
|
+
scope: 'repo',
|
|
508
|
+
probe(env) {
|
|
509
|
+
if (!isFrameworkRepo(env)) {
|
|
510
|
+
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
511
|
+
}
|
|
512
|
+
const existing = adrNumbers(env);
|
|
513
|
+
const dangling = scanAdrRefs(env).filter((r) => !existing.has(r.num));
|
|
514
|
+
if (dangling.length) {
|
|
515
|
+
const amostra = dangling.slice(0, 5).map((d) => `${d.ref} (${d.file}:${d.line})`).join(', ');
|
|
516
|
+
return {
|
|
517
|
+
status: 'warn',
|
|
518
|
+
detail: `${dangling.length} citação(ões) de ADR inexistente: ${amostra}`,
|
|
519
|
+
fix: 'escreva o ADR referenciado ou corrija o número no arquivo:linha indicado',
|
|
520
|
+
};
|
|
521
|
+
}
|
|
522
|
+
return { status: 'ok', detail: `toda referência a ADR resolve (${existing.size} ADRs)`, fix: null };
|
|
523
|
+
},
|
|
524
|
+
};
|
|
498
525
|
/** @type {Check[]} */
|
|
499
526
|
export const CHECKS = [
|
|
500
527
|
nativeAbi,
|
|
@@ -507,6 +534,7 @@ export const CHECKS = [
|
|
|
507
534
|
docsCommands,
|
|
508
535
|
commandsDocumented,
|
|
509
536
|
docsLinks,
|
|
537
|
+
adrRefs,
|
|
510
538
|
];
|
|
511
539
|
/**
|
|
512
540
|
* Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/project-smoke.ts — o gate do projeto gerado.
|
|
3
|
+
*
|
|
4
|
+
* Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
|
|
5
|
+
* O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
|
|
6
|
+
* — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
|
|
7
|
+
*
|
|
8
|
+
* O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
|
|
9
|
+
* `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
|
|
10
|
+
* princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
|
|
11
|
+
*
|
|
12
|
+
* O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
|
|
13
|
+
*/
|
|
14
|
+
import fs from 'node:fs';
|
|
15
|
+
import { worstStatus } from './checks.ts';
|
|
16
|
+
import type { Check } from './checks.ts';
|
|
17
|
+
export { worstStatus };
|
|
18
|
+
interface SmokeEnv {
|
|
19
|
+
root: string;
|
|
20
|
+
fs: typeof fs;
|
|
21
|
+
projectDir?: string;
|
|
22
|
+
full: boolean;
|
|
23
|
+
spawn: (cmd: string, args: string[], opts?: any) => {
|
|
24
|
+
stdout: string;
|
|
25
|
+
stderr: string;
|
|
26
|
+
code: number;
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
|
|
31
|
+
* temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
|
|
32
|
+
*/
|
|
33
|
+
export declare function withGeneratedProject<T>(fn: (ctx: {
|
|
34
|
+
projectDir: string;
|
|
35
|
+
}) => Promise<T> | T, { root, spawn }: {
|
|
36
|
+
root?: string;
|
|
37
|
+
spawn: SmokeEnv['spawn'];
|
|
38
|
+
}): Promise<T>;
|
|
39
|
+
/** @type {Check[]} */
|
|
40
|
+
export declare const SMOKE_CHECKS: Check[];
|
|
41
|
+
export declare function defaultEnv(overrides?: Partial<SmokeEnv>): SmokeEnv;
|
|
42
|
+
/** Gera um projeto isolado, roda os checks, limpa. */
|
|
43
|
+
export declare function runProjectSmoke({ full, env: overrides }?: {
|
|
44
|
+
full?: boolean;
|
|
45
|
+
env?: Partial<SmokeEnv>;
|
|
46
|
+
}): Promise<import("./checks.ts").Result[]>;
|