forjajs 1.3.1 → 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.
Files changed (66) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.en.md +1 -0
  3. package/README.md +10 -4
  4. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  5. package/dist/bin/create-memory-nest-kit.d.ts +11 -0
  6. package/dist/bin/create-memory-nest-kit.js +5 -5
  7. package/dist/bin/forja.js +1 -1
  8. package/dist/bin/init-project.d.ts +12 -0
  9. package/dist/bin/init-project.js +2 -2
  10. package/dist/lib/code-context.d.ts +41 -0
  11. package/dist/lib/code-context.js +108 -0
  12. package/dist/lib/context-builder.d.ts +15 -5
  13. package/dist/lib/context-builder.js +5 -0
  14. package/dist/lib/core/checks.d.ts +3 -3
  15. package/dist/lib/core/doc-graph.d.ts +13 -0
  16. package/dist/lib/core/doc-graph.js +48 -1
  17. package/dist/lib/core/health.d.ts +3 -32
  18. package/dist/lib/core/health.js +29 -15
  19. package/dist/lib/core/project-smoke.d.ts +46 -0
  20. package/dist/lib/core/project-smoke.js +248 -0
  21. package/dist/lib/core/registry.d.ts +25 -0
  22. package/dist/lib/core/registry.js +37 -12
  23. package/dist/lib/core/release.d.ts +27 -14
  24. package/dist/lib/core/release.js +0 -8
  25. package/dist/lib/generators/memory-generator.d.ts +11 -6
  26. package/dist/lib/generators/memory-generator.js +45 -1
  27. package/dist/lib/generators/nest-generator.d.ts +8 -4
  28. package/dist/lib/generators/nest-generator.js +1 -1
  29. package/dist/lib/generators/readme-generator.d.ts +7 -4
  30. package/dist/lib/generators/readme-generator.js +2 -1
  31. package/dist/lib/governance-report.d.ts +1 -1
  32. package/dist/lib/memory-audit.d.ts +31 -0
  33. package/dist/lib/memory-audit.js +81 -0
  34. package/dist/lib/project-upgrade.d.ts +28 -0
  35. package/dist/lib/project-upgrade.js +74 -0
  36. package/dist/lib/utils/file-helpers.d.ts +10 -6
  37. package/dist/lib/validators/structure-validator.d.ts +49 -27
  38. package/dist/scripts/code-context.d.ts +12 -0
  39. package/dist/scripts/code-context.js +73 -0
  40. package/dist/scripts/dev.d.ts +2 -2
  41. package/dist/scripts/dev.js +1 -1
  42. package/dist/scripts/memory-audit.d.ts +11 -0
  43. package/dist/scripts/memory-audit.js +49 -0
  44. package/dist/scripts/project-smoke.d.ts +14 -0
  45. package/dist/scripts/project-smoke.js +44 -0
  46. package/dist/scripts/project-upgrade.d.ts +11 -0
  47. package/dist/scripts/project-upgrade.js +61 -0
  48. package/dist/scripts/query-universal-memory.js +1 -1
  49. package/dist/scripts/sprint-manager.js +1 -1
  50. package/dist/scripts/token-benchmark.js +1 -1
  51. package/dist/scripts/token-economy.d.ts +20 -0
  52. package/dist/scripts/token-economy.js +140 -0
  53. package/memory/90-decisions/0025-coerencia-da-documentacao.md +4 -0
  54. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  55. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  56. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  57. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  58. package/package.json +1 -1
  59. package/specs/code-context/spec.md +56 -0
  60. package/specs/memory-audit/spec.md +54 -0
  61. package/specs/project-smoke/spec.md +96 -0
  62. package/specs/project-upgrade/spec.md +58 -0
  63. package/specs/ts-migration/plan.md +9 -8
  64. package/specs/ts-migration/spec.md +1 -1
  65. package/dist/lib/templates/harness/code-intel.d.mts +0 -2
  66. package/dist/lib/templates/harness/code-intel.mjs +0 -126
package/CHANGELOG.md CHANGED
@@ -4,6 +4,75 @@ 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
+
59
+ ## [1.3.2] — 2026-07-19 — Migração TypeScript concluída (interno)
60
+
61
+ **Sem mudança para quem instala** — o `dist/*.js` publicado é idêntico ao da 1.3.1. Fecha a SPEC-012.
62
+
63
+ ### Alterado (interno)
64
+ - **Fonte 100% TypeScript**: os 16 `.js` restantes (entries públicos `init-project`/
65
+ `create-memory-nest-kit`, generators, validators, `context-builder`, scaffolding) viraram `.ts`.
66
+ - **`noImplicitAny: true`** — o ratchet está armado: daqui pra frente todo parâmetro novo precisa de
67
+ tipo explícito. Os ~285 params existentes foram anotados (tipo real onde agrega, `any` explícito
68
+ onde o valor é dinâmico). Os checks de `health`/`release` viram `Check[]` de verdade.
69
+ - Shim `lib/vendor.d.ts` para o `better-sqlite3` (sem tipos publicados); `lib/templates` fora do
70
+ type-check (é conteúdo copiado, não código do framework).
71
+ - Correção pega pelo `release:check`: um sed havia corrompido o array de fallback do `resolveScript`
72
+ (`['.ts','.js','.mjs']`→`['.ts','.ts','.ts']`), quebrando a resolução do `dist/*.js`.
73
+
74
+ ---
75
+
7
76
  ## [1.3.1] — 2026-07-19 — Migração TypeScript dos módulos do framework (interno)
8
77
 
9
78
  **Sem mudança para quem instala** — o `dist/*.js` publicado é idêntico ao da 1.3.0. A conversão é
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
- - [ ] **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.
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
- ## 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
 
@@ -1,2 +1,13 @@
1
1
  #!/usr/bin/env node
2
+ /**
3
+ * create-memory-nest-kit v0.6.0
4
+ * Orquestrador de geração de projetos com memória hierárquica
5
+ *
6
+ * Refatoração modular:
7
+ * - lib/generators/memory-generator.js
8
+ * - lib/generators/nest-generator.js
9
+ * - lib/generators/readme-generator.js
10
+ * - lib/validators/structure-validator.js
11
+ * - lib/utils/file-helpers.js
12
+ */
2
13
  export {};
@@ -13,11 +13,11 @@
13
13
  import path from 'node:path';
14
14
  import process from 'node:process';
15
15
  import { fileURLToPath } from 'node:url';
16
- import { generateMemoryStructure } from '../lib/generators/memory-generator.js';
17
- import { generateNestStructure } from '../lib/generators/nest-generator.js';
18
- import { generateReadme } from '../lib/generators/readme-generator.js';
19
- import { validateProjectStructure, printValidationReport } from '../lib/validators/structure-validator.js';
20
- import { ensureDir, logSuccess, logError } from '../lib/utils/file-helpers.js';
16
+ import { generateMemoryStructure } from "../lib/generators/memory-generator.js";
17
+ import { generateNestStructure } from "../lib/generators/nest-generator.js";
18
+ import { generateReadme } from "../lib/generators/readme-generator.js";
19
+ import { validateProjectStructure, printValidationReport } from "../lib/validators/structure-validator.js";
20
+ import { ensureDir, logSuccess, logError } from "../lib/utils/file-helpers.js";
21
21
  const __filename = fileURLToPath(import.meta.url);
22
22
  const __dirname = path.dirname(__filename);
23
23
  // Parse arguments
package/dist/bin/forja.js CHANGED
@@ -120,7 +120,7 @@ else {
120
120
  cwd: root,
121
121
  stdio: 'inherit',
122
122
  });
123
- if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') {
123
+ if (result.error && result.error.code === 'ENOENT') {
124
124
  console.error(`Binário não encontrado no PATH: ${cmd.bin}. Veja: forja tools:doctor`);
125
125
  result.status = 127;
126
126
  }
@@ -1,2 +1,14 @@
1
1
  #!/usr/bin/env node
2
+ /**
3
+ * init-project.js
4
+ *
5
+ * Comando universal para inicializar novo projeto com agentes orquestrados.
6
+ * Puxa configuração de Copilot, Claude, Gemini, Codex e outros.
7
+ *
8
+ * Uso:
9
+ * node bin/init-project.js meu-projeto
10
+ * node bin/init-project.js meu-projeto --ai copilot,claude,gemini
11
+ * node bin/init-project.js meu-projeto --skip-backend
12
+ * node bin/init-project.js --interactive
13
+ */
2
14
  export {};
@@ -16,7 +16,7 @@ import path from 'node:path';
16
16
  import process from 'node:process';
17
17
  import { execSync } from 'node:child_process';
18
18
  import { fileURLToPath } from 'node:url';
19
- import { getWorkspaceRoot, getProjectsDir, resolveProject, initWorkspace, getWorkspaceProjectsMemoryDir, assertOutsideFrameworkRepo, } from "../lib/workspace.js";
19
+ import { getWorkspaceRoot, resolveProject, initWorkspace, getWorkspaceProjectsMemoryDir, assertOutsideFrameworkRepo, } from "../lib/workspace.js";
20
20
  const __filename = fileURLToPath(import.meta.url);
21
21
  const __dirname = path.dirname(__filename);
22
22
  const kitRoot = path.resolve(__dirname, '..');
@@ -302,7 +302,7 @@ Para trocar de IA (ex: se acabar a cota), use o arquivo [models.json](./models.j
302
302
 
303
303
  ## IAs Configuradas
304
304
 
305
- ${opts.ai.map(ai => `- [${ai.toUpperCase()}](./${ai}.md)`).join('\n')}
305
+ ${opts.ai.map((ai) => `- [${ai.toUpperCase()}](./${ai}.md)`).join('\n')}
306
306
  `;
307
307
  fs.writeFileSync(path.join(instructionsDir, 'README.md'), indexContent);
308
308
  // Criar models.json para interoperabilidade
@@ -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
+ }
@@ -1,10 +1,20 @@
1
- export class ContextBuilder {
2
- constructor(projectPath: any, dbPath: any);
3
- projectPath: any;
4
- dbPath: any;
1
+ /**
2
+ * Context Builder - API Reutilizável para Construção de Contexto Inteligente
3
+ *
4
+ * Suporta 3 modos de contexto:
5
+ * - 'global': Apenas contexto global (mission, standards, decisões recentes)
6
+ * - 'domain': Contexto de domínio específico + globais
7
+ * - 'task': Contexto orientado a tarefa + domain + globais (mais compacto)
8
+ *
9
+ * Usa SQLite FTS5 para busca eficiente e cache local para reutilização.
10
+ */
11
+ export declare class ContextBuilder {
12
+ projectPath: string;
13
+ dbPath: string;
5
14
  db: any;
6
15
  cache: Map<any, any>;
7
16
  maxCacheSize: number;
17
+ constructor(projectPath: any, dbPath: any);
8
18
  /**
9
19
  * Abrir conexão com banco de dados (readonly)
10
20
  */
@@ -21,7 +31,7 @@ export class ContextBuilder {
21
31
  * @param {string} keyword - Palavra-chave para busca (modo 'task')
22
32
  * @returns {string} Conteúdo do contexto em markdown
23
33
  */
24
- build(mode: string, project: string, keyword?: string): string;
34
+ build(mode: any, project: any, keyword?: string): string;
25
35
  /**
26
36
  * Obter contexto global (mission, standards, padrões)
27
37
  */
@@ -13,6 +13,11 @@ import path from 'node:path';
13
13
  import Database from 'better-sqlite3';
14
14
  import { getDbPath, ensureSchema } from "../scripts/memory-schema.js";
15
15
  export class ContextBuilder {
16
+ projectPath;
17
+ dbPath;
18
+ db;
19
+ cache;
20
+ maxCacheSize;
16
21
  constructor(projectPath, dbPath) {
17
22
  this.projectPath = projectPath;
18
23
  this.dbPath = dbPath;
@@ -68,9 +68,9 @@ export declare function asErrno(e: any): any;
68
68
  * @returns {Promise<Result[]>}
69
69
  */
70
70
  export declare function runChecks({ checks, scope, env }: {
71
- checks: any;
72
- scope?: string | undefined;
73
- env?: {} | undefined;
71
+ checks: Check[];
72
+ scope?: Scope | 'all';
73
+ env?: any;
74
74
  }): Promise<Result[]>;
75
75
  /**
76
76
  * Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
@@ -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();
@@ -201,7 +248,7 @@ export function projectCommands(env) {
201
248
  /* sem geradores — segue */
202
249
  }
203
250
  for (const entry of genEntries) {
204
- if (!/\.(mjs|js)$/.test(entry))
251
+ if (!/\.(mjs|cjs|js|ts)$/.test(entry))
205
252
  continue;
206
253
  const src = safeRead(env, path.join(genDir, entry));
207
254
  if (src == null)
@@ -27,8 +27,7 @@
27
27
  import fs from 'node:fs';
28
28
  import { getWorkspaceDbPath, getWorkspaceInfo } from '../workspace.ts';
29
29
  import { worstStatus } from './checks.ts';
30
- /** @typedef {import('./checks.ts').Check} Check */
31
- /** @typedef {import('./checks.ts').Result} Result */
30
+ import type { Check, Result } from './checks.ts';
32
31
  /** @typedef {import('./checks.ts').Status} Status */
33
32
  export { worstStatus };
34
33
  /**
@@ -57,35 +56,7 @@ export declare function defaultEnv(overrides?: {}): {
57
56
  /** Estamos dentro do repo do framework, e não numa instalação do pacote? */
58
57
  export declare function isFrameworkRepo(env: any): boolean;
59
58
  /** @type {Check[]} */
60
- export declare const CHECKS: ({
61
- id: string;
62
- title: string;
63
- severity: string;
64
- scope: string;
65
- probe(env: any): Promise<{
66
- status: string;
67
- detail: string;
68
- fix: string;
69
- } | {
70
- status: string;
71
- detail: string;
72
- fix: null;
73
- }>;
74
- } | {
75
- id: string;
76
- title: string;
77
- severity: string;
78
- scope: string;
79
- probe(env: any): {
80
- status: string;
81
- detail: string;
82
- fix: string;
83
- } | {
84
- status: string;
85
- detail: string;
86
- fix: null;
87
- };
88
- })[];
59
+ export declare const CHECKS: Check[];
89
60
  /**
90
61
  * Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
91
62
  * `defaultEnv` do framework, que o runner genérico não conhece nem deve conhecer.
@@ -100,4 +71,4 @@ export declare function runChecks(opts?: {
100
71
  scope?: import('./checks.ts').Scope | 'all';
101
72
  env?: any;
102
73
  checks?: import('./checks.ts').Check[];
103
- }): Promise<import("./checks.ts").Result[]>;
74
+ }): Promise<Result[]>;