forjajs 1.1.5 → 1.2.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 +50 -0
- package/README.en.md +310 -0
- package/README.md +37 -6
- package/bin/forja.mjs +3 -3
- package/boilerplates/06-clean-arch/README.md +48 -0
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
- package/boilerplates/06-clean-arch/backend/package.json +43 -0
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
- package/boilerplates/README.md +20 -0
- package/docs/personas/architect/README.md +4 -4
- package/docs/personas/developer/README.md +3 -3
- package/docs/personas/qa/README.md +3 -3
- package/docs/quick-reference.md +9 -9
- package/docs/structure.md +3 -3
- package/lib/core/checks.mjs +20 -3
- package/lib/core/doc-graph.mjs +231 -0
- package/lib/core/health.mjs +131 -29
- package/lib/core/registry.mjs +23 -0
- package/lib/core/release.mjs +48 -8
- package/lib/templates/harness/code-intel.mjs +2 -2
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
- package/package.json +8 -1
- package/scripts/agent-harness.mjs +7 -5
- package/scripts/context-ops.mjs +7 -4
- package/scripts/dev.mjs +2 -2
- package/scripts/hook-guard-paths.mjs +1 -0
- package/scripts/hook-user-prompt.mjs +1 -1
- package/scripts/spec-cli.mjs +4 -3
- package/scripts/tools-doctor.mjs +1 -1
- package/specs/clean-arch-boilerplate/plan.md +137 -0
- package/specs/clean-arch-boilerplate/spec.md +121 -0
- package/specs/clean-arch-boilerplate/tasks.md +70 -0
- package/specs/coerencia-do-sistema/plan.md +155 -0
- package/specs/coerencia-do-sistema/spec.md +15 -14
- package/specs/coerencia-do-sistema/tasks.md +115 -0
- package/specs/ts-migration/plan.md +188 -0
- package/specs/ts-migration/spec.md +119 -0
- package/specs/ts-migration/tasks.md +110 -0
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Contexto: Orders (fatia rica)
|
|
2
|
+
|
|
3
|
+
> Leia **este arquivo antes do código**. Ele descreve o domínio na linguagem ubíqua. Você só precisa
|
|
4
|
+
> descer à implementação quando for *editar* — e aí sabe exatamente onde. Isso é a economia de token
|
|
5
|
+
> do boilerplate (ADR-0009): o resumo tipado do domínio, não a leitura da árvore inteira.
|
|
6
|
+
|
|
7
|
+
## Linguagem ubíqua
|
|
8
|
+
|
|
9
|
+
- **Order** (agregado) — um pedido de um cliente, com uma ou mais linhas.
|
|
10
|
+
- **OrderLine** — produto + preço unitário + quantidade.
|
|
11
|
+
- **OrderStatus** — máquina de estados: `DRAFT → CONFIRMED → PAID → SHIPPED`, e `CANCELLED` de
|
|
12
|
+
qualquer estado não-enviado.
|
|
13
|
+
- **Money** — value object em centavos; imutável, comparado por valor.
|
|
14
|
+
|
|
15
|
+
## Invariantes (moram em `domain/order.entity.ts`)
|
|
16
|
+
|
|
17
|
+
1. Um pedido **precisa de ao menos uma linha** para ser criado.
|
|
18
|
+
2. Toda quantidade é **positiva**.
|
|
19
|
+
3. O **total é derivado** das linhas — nunca setado de fora.
|
|
20
|
+
4. As transições de estado seguem a máquina; em especial: **não se envia sem pagamento** (`SHIPPED`
|
|
21
|
+
só a partir de `PAID`).
|
|
22
|
+
|
|
23
|
+
Se você vai mexer numa regra, ela está no agregado. Não procure no controller nem no service.
|
|
24
|
+
|
|
25
|
+
## Casos de uso (contratos em `application/`)
|
|
26
|
+
|
|
27
|
+
| Use-case | Input → Output | O que faz |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| `PlaceOrderUseCase` | `{ customerId, items[] }` → `{ orderId, totalCents }` | cria + confirma o pedido |
|
|
30
|
+
| `ShipOrderUseCase` | `{ orderId }` → `void` | envia — falha se não estiver pago |
|
|
31
|
+
|
|
32
|
+
A assinatura basta para saber o que a feature faz. O corpo só interessa ao editar.
|
|
33
|
+
|
|
34
|
+
## Onde as coisas ficam
|
|
35
|
+
|
|
36
|
+
- Regra nova → `domain/order.entity.ts` (e teste em `test/orders/place-order.spec.ts`, sem Nest).
|
|
37
|
+
- Caso de uso novo → `application/*.usecase.ts`.
|
|
38
|
+
- Persistência → `infrastructure/typeorm-order.repository.ts` (implementa a porta do domínio).
|
|
39
|
+
- Endpoint → `presentation/orders.controller.ts` (fino: traduz HTTP ↔ use-case).
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Contexto: Products (caminho enxuto)
|
|
2
|
+
|
|
3
|
+
> CRUD sem regra de negócio. **Uma camada.** Se você esperava as quatro camadas de `orders/`, leia o
|
|
4
|
+
> `WHEN-CLEAN-WHEN-LEAN.md` — a ausência delas aqui é decisão, não esquecimento.
|
|
5
|
+
|
|
6
|
+
## Linguagem ubíqua
|
|
7
|
+
|
|
8
|
+
- **Product** — nome + preço (centavos). Não há comportamento a proteger; o modelo é a tabela.
|
|
9
|
+
|
|
10
|
+
## Regras
|
|
11
|
+
|
|
12
|
+
Nenhuma além de validação de formato (nome string, preço inteiro positivo). Não há invariante, não
|
|
13
|
+
há transição de estado. Por isso o `controller` fala direto com o repositório do TypeORM.
|
|
14
|
+
|
|
15
|
+
## Quando isto vira `orders/`
|
|
16
|
+
|
|
17
|
+
No dia em que aparecer uma regra de verdade — por exemplo, *"não pode desativar um produto com pedido
|
|
18
|
+
em aberto"* — este contexto ganha um agregado de domínio e migra para o padrão de quatro camadas. Até
|
|
19
|
+
lá, promover seria pagar tokens adiantado por camadas vazias.
|
|
20
|
+
|
|
21
|
+
## Onde as coisas ficam
|
|
22
|
+
|
|
23
|
+
- Tudo em `modules/products/`: `product.entity.ts` (o modelo) e `products.controller.ts` (o CRUD).
|
package/boilerplates/README.md
CHANGED
|
@@ -119,6 +119,26 @@ node ../bin/init-project.js meu-projeto --template monorepo
|
|
|
119
119
|
|
|
120
120
|
---
|
|
121
121
|
|
|
122
|
+
### 🧱 6. Clean Architecture (Calibrada)
|
|
123
|
+
**Para**: Produtos com regra de negócio de verdade — DDD por camadas, sem cerimônia
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
node ../bin/init-project.js meu-projeto --template clean-arch
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**Inclui**:
|
|
130
|
+
- Fatia rica (Orders): domain / application / infrastructure / presentation, com inversão de dependência
|
|
131
|
+
- Caminho enxuto (Products): CRUD em 1 camada, lado a lado — a calibração visível
|
|
132
|
+
- Invariante de domínio testável **sem subir o Nest**
|
|
133
|
+
- Memória por bounded context (linguagem ubíqua) para leitura barata por agente
|
|
134
|
+
- `WHEN-CLEAN-WHEN-LEAN.md`: o critério de quando usar cada padrão
|
|
135
|
+
|
|
136
|
+
**Use quando**: há invariante de negócio ou máquina de estados. Para CRUD puro, prefira um dos flat acima.
|
|
137
|
+
|
|
138
|
+
[Abrir 📂](./06-clean-arch)
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
122
142
|
### 📊 6. Dashboard Admin
|
|
123
143
|
**Para**: Painel administrativo, gestão interna
|
|
124
144
|
|
|
@@ -309,10 +309,10 @@ Seguir [Guia de Developer](../developer/README.md)
|
|
|
309
309
|
|
|
310
310
|
| Documento | Quando ler |
|
|
311
311
|
|-----------|-----------|
|
|
312
|
-
| [
|
|
313
|
-
| [
|
|
314
|
-
| [
|
|
315
|
-
| [
|
|
312
|
+
| [AGENTS.md](../../../AGENTS.md) | Os 6 papéis e a topologia |
|
|
313
|
+
| [memory/90-decisions/](../../../memory/90-decisions/) | ADRs com rationale |
|
|
314
|
+
| [structure.md](../../structure.md) | Estrutura de diretórios |
|
|
315
|
+
| [agent-harnesses.md](../../agent-harnesses.md) | Harness e ferramentas de processo |
|
|
316
316
|
|
|
317
317
|
---
|
|
318
318
|
|
|
@@ -294,9 +294,9 @@ open coverage/index.html
|
|
|
294
294
|
|
|
295
295
|
| Recurso | Quando usar |
|
|
296
296
|
|---------|------------|
|
|
297
|
-
| [
|
|
298
|
-
| [
|
|
299
|
-
| [
|
|
297
|
+
| [boilerplates/](../../../boilerplates/README.md) | Padrões prontos por stack |
|
|
298
|
+
| [quick-reference.md](../../quick-reference.md) | Atalhos de comandos |
|
|
299
|
+
| [fluxo.md](../../fluxo.md) | Roteiro do ciclo CLI-first |
|
|
300
300
|
| [NestJS Docs](https://docs.nestjs.com) | Dúvidas NestJS |
|
|
301
301
|
|
|
302
302
|
---
|
|
@@ -339,9 +339,9 @@ POST /api/seu-endpoint com payload { "campo": "valor especial" }
|
|
|
339
339
|
|
|
340
340
|
| Recurso | Quando usar |
|
|
341
341
|
|---------|------------|
|
|
342
|
-
| [
|
|
343
|
-
| [
|
|
344
|
-
| [
|
|
342
|
+
| [agent-harnesses.md](../../agent-harnesses.md) | Gates e ferramentas de processo |
|
|
343
|
+
| [DOC-MAP.md](../../../DOC-MAP.md) | Mapa da documentação |
|
|
344
|
+
| [memory/90-decisions/](../../../memory/90-decisions/) | Decisões e rationale |
|
|
345
345
|
|
|
346
346
|
---
|
|
347
347
|
|
package/docs/quick-reference.md
CHANGED
|
@@ -345,11 +345,11 @@ logger.error('Auth failed', error); // Erro
|
|
|
345
345
|
|
|
346
346
|
| Recurso | Link |
|
|
347
347
|
|---------|------|
|
|
348
|
-
| Documentation Map | [DOC-MAP.md](DOC-MAP.md) |
|
|
349
|
-
|
|
|
350
|
-
|
|
|
351
|
-
| Architecture | [
|
|
352
|
-
| Personas | [
|
|
348
|
+
| Documentation Map | [DOC-MAP.md](../DOC-MAP.md) |
|
|
349
|
+
| Getting Started | [README.md](../README.md) |
|
|
350
|
+
| Boilerplates | [boilerplates/](../boilerplates/README.md) |
|
|
351
|
+
| Architecture | [AGENTS.md](../AGENTS.md) |
|
|
352
|
+
| Personas | [personas/](personas/) |
|
|
353
353
|
|
|
354
354
|
---
|
|
355
355
|
|
|
@@ -399,10 +399,10 @@ open http://localhost:3000/api/health
|
|
|
399
399
|
|
|
400
400
|
| Dúvida | Arquivo |
|
|
401
401
|
|--------|---------|
|
|
402
|
-
| "Como começar?" | [
|
|
403
|
-
| "Como codificar?" | [
|
|
404
|
-
| "Como arquitetar?" | [
|
|
405
|
-
| "Qual minha persona?" | [DOC-MAP.md](DOC-MAP.md) |
|
|
402
|
+
| "Como começar?" | [README.md](../README.md) |
|
|
403
|
+
| "Como codificar?" | [boilerplates/](../boilerplates/README.md) |
|
|
404
|
+
| "Como arquitetar?" | [AGENTS.md](../AGENTS.md) |
|
|
405
|
+
| "Qual minha persona?" | [DOC-MAP.md](../DOC-MAP.md) |
|
|
406
406
|
|
|
407
407
|
---
|
|
408
408
|
|
package/docs/structure.md
CHANGED
|
@@ -355,6 +355,6 @@ node backend/scripts/memory-db-query.mjs --table improvement_items
|
|
|
355
355
|
---
|
|
356
356
|
|
|
357
357
|
**Para mais detalhes**, veja:
|
|
358
|
-
- [
|
|
359
|
-
- [
|
|
360
|
-
- [
|
|
358
|
+
- [README.md](../README.md)
|
|
359
|
+
- [AGENTS.md](../AGENTS.md)
|
|
360
|
+
- [DOC-MAP.md](../DOC-MAP.md)
|
package/lib/core/checks.mjs
CHANGED
|
@@ -30,7 +30,8 @@
|
|
|
30
30
|
* @property {Severity} severity `critical` trava o gate; `warn` informa.
|
|
31
31
|
* @property {Scope=} scope Filtro opcional do runner.
|
|
32
32
|
* @property {string=} dependsOn Id de outro check. Se ele não passar, este vira `skipped`.
|
|
33
|
-
* @property {(env:
|
|
33
|
+
* @property {(env: any) => Promise<Probe>|Probe} probe `env` é injetado e polimórfico entre os
|
|
34
|
+
* catálogos (health/release/doc); tipagem por-catálogo com generics fica para a Fase 2 (.ts).
|
|
34
35
|
*/
|
|
35
36
|
|
|
36
37
|
/**
|
|
@@ -40,10 +41,23 @@
|
|
|
40
41
|
* @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
|
|
41
42
|
*/
|
|
42
43
|
|
|
43
|
-
/** @typedef {{ id, title, severity: Severity, scope
|
|
44
|
+
/** @typedef {{ id: string, title: string, severity: Severity, scope?: Scope, status: Status, detail: string, fix: string|null }} Result */
|
|
44
45
|
|
|
46
|
+
/** @type {Severity} */
|
|
45
47
|
const SEVERITY_FALLBACK = 'critical';
|
|
46
48
|
|
|
49
|
+
/**
|
|
50
|
+
* Estreita um valor capturado num `catch` (que o TS tipa como `unknown`) para a forma de erro do
|
|
51
|
+
* Node — `code`/`message` opcionais. Não muda comportamento: só dá ao compilador o que o runtime
|
|
52
|
+
* já assume ao ler `err.code`.
|
|
53
|
+
*
|
|
54
|
+
* @param {unknown} e
|
|
55
|
+
* @returns {NodeJS.ErrnoException}
|
|
56
|
+
*/
|
|
57
|
+
export function asErrno(e) {
|
|
58
|
+
return /** @type {NodeJS.ErrnoException} */ (e);
|
|
59
|
+
}
|
|
60
|
+
|
|
47
61
|
/**
|
|
48
62
|
* Um probe que estoura é pior que probe nenhum: derrubaria o diagnóstico justamente no ambiente
|
|
49
63
|
* quebrado que ele existe para diagnosticar. O runner blinda cada um e segue para o próximo.
|
|
@@ -57,9 +71,10 @@ async function runProbe(check, env) {
|
|
|
57
71
|
fix: probe.fix ?? null,
|
|
58
72
|
};
|
|
59
73
|
} catch (err) {
|
|
74
|
+
const e = asErrno(err);
|
|
60
75
|
return {
|
|
61
76
|
status: 'fail',
|
|
62
|
-
detail: `probe falhou: ${
|
|
77
|
+
detail: `probe falhou: ${e.message || e}`,
|
|
63
78
|
fix: null,
|
|
64
79
|
};
|
|
65
80
|
}
|
|
@@ -73,7 +88,9 @@ async function runProbe(check, env) {
|
|
|
73
88
|
*/
|
|
74
89
|
export async function runChecks({ checks, scope = 'all', env = {} }) {
|
|
75
90
|
const selected = checks.filter((c) => scope === 'all' || c.scope === scope);
|
|
91
|
+
/** @type {Map<string, Status>} */
|
|
76
92
|
const statusById = new Map();
|
|
93
|
+
/** @type {Result[]} */
|
|
77
94
|
const results = [];
|
|
78
95
|
|
|
79
96
|
for (const check of selected) {
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/doc-graph.mjs — a documentação lida como dado.
|
|
3
|
+
*
|
|
4
|
+
* O `health.mjs` já lê código (imports, package.json, .mcp.json). Este módulo lê os `.md` que
|
|
5
|
+
* **instruem** o agente e extrai o que é verificável contra o código: comandos citados e links
|
|
6
|
+
* relativos. Leitura pura — nenhum juízo de severidade mora aqui; os checks de `health.mjs` é que
|
|
7
|
+
* julgam (SPEC-011, ADR-0025).
|
|
8
|
+
*
|
|
9
|
+
* Por que existir: o Forja é operado por agentes que executam o que a doc manda. Quando a doc e o
|
|
10
|
+
* registry divergem, o agente não erra por burrice — erra por obediência. Em 2026-07-14 uma
|
|
11
|
+
* auditoria manual achou quatro comandos fantasma no doc que ensina a economia de tokens. Nada
|
|
12
|
+
* quebrou um teste. É a classe do ADR-0021 — erra sem avisar — na camada de instrução.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import fs from 'node:fs';
|
|
16
|
+
import path from 'node:path';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Superfícies de instrução. Escaneia o que orienta o agente **agora** — não o histórico.
|
|
20
|
+
*
|
|
21
|
+
* Fora de propósito (plano §D3): `docs/archive/` (legado), `boilerplates/` (conteúdo do projeto
|
|
22
|
+
* gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/` (registro histórico: uma
|
|
23
|
+
* spec ou ADR pode legitimamente citar um comando proposto ou já removido).
|
|
24
|
+
*/
|
|
25
|
+
export const DOC_SURFACES = [
|
|
26
|
+
'docs',
|
|
27
|
+
'prompts',
|
|
28
|
+
'.claude/agents',
|
|
29
|
+
'AGENTS.md',
|
|
30
|
+
'CLAUDE.md',
|
|
31
|
+
'README.md',
|
|
32
|
+
'README.en.md',
|
|
33
|
+
'DOC-MAP.md',
|
|
34
|
+
];
|
|
35
|
+
|
|
36
|
+
const EXCLUDED_DIRS = new Set(['archive', 'node_modules']);
|
|
37
|
+
|
|
38
|
+
/** Um comando do Forja: `forja x:y` ou `npm run x:y`, com ao menos um `:` (o discriminador, §D4). */
|
|
39
|
+
const COMMAND_RE = /(?:\bforja\s+|npm run\s+)([a-z][a-z0-9]*(?::[a-z0-9-]+)+)/g;
|
|
40
|
+
|
|
41
|
+
/** Link markdown relativo. Ignora http(s):// e âncoras puras; a âncora de um path é descartada. */
|
|
42
|
+
const LINK_RE = /\]\(([^)]+)\)/g;
|
|
43
|
+
|
|
44
|
+
function safeRead(env, file) {
|
|
45
|
+
try {
|
|
46
|
+
return env.fs.readFileSync(file, 'utf8');
|
|
47
|
+
} catch {
|
|
48
|
+
return null;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Coleta os `.md` sob uma superfície (arquivo direto ou diretório varrido, menos EXCLUDED_DIRS). */
|
|
53
|
+
function collectMarkdown(env, surface) {
|
|
54
|
+
const abs = path.join(env.root, surface);
|
|
55
|
+
const out = [];
|
|
56
|
+
|
|
57
|
+
const walk = (p) => {
|
|
58
|
+
let st;
|
|
59
|
+
try {
|
|
60
|
+
st = env.fs.statSync(p);
|
|
61
|
+
} catch {
|
|
62
|
+
return;
|
|
63
|
+
}
|
|
64
|
+
if (st.isDirectory()) {
|
|
65
|
+
let entries;
|
|
66
|
+
try {
|
|
67
|
+
entries = env.fs.readdirSync(p);
|
|
68
|
+
} catch {
|
|
69
|
+
return;
|
|
70
|
+
}
|
|
71
|
+
for (const entry of entries) {
|
|
72
|
+
if (EXCLUDED_DIRS.has(entry)) continue;
|
|
73
|
+
walk(path.join(p, entry));
|
|
74
|
+
}
|
|
75
|
+
} else if (p.endsWith('.md')) {
|
|
76
|
+
out.push(p);
|
|
77
|
+
}
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
walk(abs);
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Todos os `.md` das superfícies de instrução, caminhos relativos à raiz. */
|
|
85
|
+
export function docFiles(env) {
|
|
86
|
+
const seen = new Set();
|
|
87
|
+
for (const surface of DOC_SURFACES) {
|
|
88
|
+
for (const file of collectMarkdown(env, surface)) {
|
|
89
|
+
seen.add(path.relative(env.root, file));
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return [...seen];
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Comandos citados nas superfícies de instrução.
|
|
97
|
+
* @returns {{ file: string, line: number, command: string }[]}
|
|
98
|
+
*/
|
|
99
|
+
export function scanCommands(env) {
|
|
100
|
+
const hits = [];
|
|
101
|
+
for (const rel of docFiles(env)) {
|
|
102
|
+
const src = safeRead(env, path.join(env.root, rel));
|
|
103
|
+
if (src == null) continue;
|
|
104
|
+
const lines = src.split('\n');
|
|
105
|
+
lines.forEach((text, i) => {
|
|
106
|
+
for (const m of text.matchAll(COMMAND_RE)) {
|
|
107
|
+
hits.push({ file: rel, line: i + 1, command: m[1] });
|
|
108
|
+
}
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
return hits;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Links markdown relativos nas superfícies de instrução, com o alvo já resolvido à raiz.
|
|
116
|
+
* @returns {{ file: string, line: number, target: string, resolved: string }[]}
|
|
117
|
+
*/
|
|
118
|
+
export function scanLinks(env) {
|
|
119
|
+
const hits = [];
|
|
120
|
+
for (const rel of docFiles(env)) {
|
|
121
|
+
const src = safeRead(env, path.join(env.root, rel));
|
|
122
|
+
if (src == null) continue;
|
|
123
|
+
const dir = path.dirname(rel);
|
|
124
|
+
const lines = src.split('\n');
|
|
125
|
+
lines.forEach((text, i) => {
|
|
126
|
+
for (const m of text.matchAll(LINK_RE)) {
|
|
127
|
+
const raw = m[1].trim();
|
|
128
|
+
if (!raw || raw.startsWith('#')) continue; // âncora pura
|
|
129
|
+
if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) continue; // http:, mailto:, etc. — externo
|
|
130
|
+
const target = raw.split('#')[0]; // descarta âncora do path
|
|
131
|
+
if (!target) continue;
|
|
132
|
+
hits.push({
|
|
133
|
+
file: rel,
|
|
134
|
+
line: i + 1,
|
|
135
|
+
target,
|
|
136
|
+
resolved: path.normalize(path.join(dir, target)),
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
return hits;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Extrai as keys de todo bloco `"scripts": { … }` de um fonte de gerador. */
|
|
145
|
+
function scriptKeys(source) {
|
|
146
|
+
const keys = new Set();
|
|
147
|
+
const block = source.match(/"scripts"\s*:\s*\{([\s\S]*?)\}/g);
|
|
148
|
+
if (!block) return keys;
|
|
149
|
+
for (const b of block) {
|
|
150
|
+
for (const m of b.matchAll(/"([a-z][a-z0-9]*(?::[a-z0-9-]+)+)"\s*:/g)) {
|
|
151
|
+
keys.add(m[1]);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
return keys;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** Todo `package.json` sob um diretório (boilerplates têm vários, aninhados). */
|
|
158
|
+
function findPackageJsons(env, dir, acc = []) {
|
|
159
|
+
let entries;
|
|
160
|
+
try {
|
|
161
|
+
entries = env.fs.readdirSync(dir);
|
|
162
|
+
} catch {
|
|
163
|
+
return acc;
|
|
164
|
+
}
|
|
165
|
+
for (const entry of entries) {
|
|
166
|
+
if (EXCLUDED_DIRS.has(entry)) continue;
|
|
167
|
+
const p = path.join(dir, entry);
|
|
168
|
+
let st;
|
|
169
|
+
try {
|
|
170
|
+
st = env.fs.statSync(p);
|
|
171
|
+
} catch {
|
|
172
|
+
continue;
|
|
173
|
+
}
|
|
174
|
+
if (st.isDirectory()) findPackageJsons(env, p, acc);
|
|
175
|
+
else if (entry === 'package.json') acc.push(p);
|
|
176
|
+
}
|
|
177
|
+
return acc;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Allowlist **derivada** dos comandos que pertencem ao projeto que o Forja *gera* (`start:dev`,
|
|
182
|
+
* `test:cov`, `test:e2e`, `memory:db:*`), não ao Forja. Nunca uma lista literal — uma lista manual
|
|
183
|
+
* mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
|
|
184
|
+
*
|
|
185
|
+
* Duas fontes, porque o projeto gerado tem duas: os `"scripts"` inline que os **geradores** escrevem
|
|
186
|
+
* e os `package.json` dos **boilerplates**. Derivar de só uma delas produz falso positivo na outra —
|
|
187
|
+
* foi `test:e2e` (vive no boilerplate, não no gerador) que revelou isso.
|
|
188
|
+
*
|
|
189
|
+
* @returns {Set<string>}
|
|
190
|
+
*/
|
|
191
|
+
export function projectCommands(env) {
|
|
192
|
+
const commands = new Set();
|
|
193
|
+
|
|
194
|
+
// Fonte 1: blocos "scripts" inline dos geradores.
|
|
195
|
+
const genDir = path.join(env.root, 'lib', 'generators');
|
|
196
|
+
let genEntries = [];
|
|
197
|
+
try {
|
|
198
|
+
genEntries = env.fs.readdirSync(genDir);
|
|
199
|
+
} catch {
|
|
200
|
+
/* sem geradores — segue */
|
|
201
|
+
}
|
|
202
|
+
for (const entry of genEntries) {
|
|
203
|
+
if (!/\.(mjs|js)$/.test(entry)) continue;
|
|
204
|
+
const src = safeRead(env, path.join(genDir, entry));
|
|
205
|
+
if (src == null) continue;
|
|
206
|
+
for (const key of scriptKeys(src)) commands.add(key);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// Fonte 2: package.json dos boilerplates.
|
|
210
|
+
for (const pkgPath of findPackageJsons(env, path.join(env.root, 'boilerplates'))) {
|
|
211
|
+
const src = safeRead(env, pkgPath);
|
|
212
|
+
if (src == null) continue;
|
|
213
|
+
try {
|
|
214
|
+
const scripts = JSON.parse(src).scripts || {};
|
|
215
|
+
for (const key of Object.keys(scripts)) commands.add(key);
|
|
216
|
+
} catch {
|
|
217
|
+
/* package.json inválido no boilerplate — ignora */
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
return commands;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** Ambiente padrão para uso fora do runner de checks (o CLI, testes de integração). */
|
|
225
|
+
export function defaultEnv(overrides = {}) {
|
|
226
|
+
return {
|
|
227
|
+
root: path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..'),
|
|
228
|
+
fs,
|
|
229
|
+
...overrides,
|
|
230
|
+
};
|
|
231
|
+
}
|