forjajs 1.2.0 → 1.3.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 (132) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +25 -0
  3. package/README.en.md +5 -0
  4. package/README.md +5 -0
  5. package/dist/bin/create-memory-nest-kit.d.ts +2 -0
  6. package/dist/bin/create-memory-nest-kit.js +110 -0
  7. package/dist/bin/forja.d.ts +13 -0
  8. package/dist/bin/forja.js +136 -0
  9. package/dist/bin/init-project.d.ts +2 -0
  10. package/dist/bin/init-project.js +516 -0
  11. package/dist/lib/audit.d.ts +67 -0
  12. package/dist/lib/audit.js +143 -0
  13. package/dist/lib/context-builder.d.ts +58 -0
  14. package/dist/lib/context-builder.js +233 -0
  15. package/dist/lib/core/checks.d.ts +91 -0
  16. package/dist/lib/core/checks.js +119 -0
  17. package/dist/lib/core/doc-graph.d.ts +60 -0
  18. package/dist/lib/core/doc-graph.js +235 -0
  19. package/dist/lib/core/health.d.ts +103 -0
  20. package/dist/lib/core/health.js +538 -0
  21. package/dist/lib/core/registry.d.ts +296 -0
  22. package/dist/lib/core/registry.js +317 -0
  23. package/dist/lib/core/release.d.ts +334 -0
  24. package/dist/lib/core/release.js +465 -0
  25. package/dist/lib/generators/memory-generator.d.ts +83 -0
  26. package/{lib → dist/lib}/generators/memory-generator.js +107 -178
  27. package/dist/lib/generators/nest-generator.d.ts +15 -0
  28. package/{lib → dist/lib}/generators/nest-generator.js +47 -71
  29. package/dist/lib/generators/readme-generator.d.ts +15 -0
  30. package/{lib → dist/lib}/generators/readme-generator.js +9 -14
  31. package/dist/lib/governance-report.d.ts +49 -0
  32. package/dist/lib/governance-report.js +170 -0
  33. package/dist/lib/templates/harness/code-intel.d.mts +2 -0
  34. package/dist/lib/templates/harness/code-intel.mjs +126 -0
  35. package/dist/lib/utils/file-helpers.d.ts +9 -0
  36. package/dist/lib/utils/file-helpers.js +34 -0
  37. package/dist/lib/validators/structure-validator.d.ts +48 -0
  38. package/dist/lib/validators/structure-validator.js +232 -0
  39. package/dist/lib/workspace.d.ts +40 -0
  40. package/dist/lib/workspace.js +174 -0
  41. package/dist/scripts/agent-harness.d.ts +2 -0
  42. package/dist/scripts/agent-harness.js +556 -0
  43. package/dist/scripts/agent-router.d.ts +30 -0
  44. package/dist/scripts/agent-router.js +208 -0
  45. package/dist/scripts/audit-query.d.ts +2 -0
  46. package/dist/scripts/audit-query.js +43 -0
  47. package/dist/scripts/audit-sync.d.ts +2 -0
  48. package/dist/scripts/audit-sync.js +19 -0
  49. package/dist/scripts/build-smart-context.d.ts +1 -0
  50. package/dist/scripts/build-smart-context.js +75 -0
  51. package/dist/scripts/check-standards.d.ts +1 -0
  52. package/dist/scripts/check-standards.js +87 -0
  53. package/dist/scripts/compress-memory.d.ts +16 -0
  54. package/dist/scripts/compress-memory.js +157 -0
  55. package/dist/scripts/compress-project-memory.d.ts +1 -0
  56. package/dist/scripts/compress-project-memory.js +48 -0
  57. package/dist/scripts/context-ops.d.ts +2 -0
  58. package/dist/scripts/context-ops.js +464 -0
  59. package/dist/scripts/dev.d.ts +96 -0
  60. package/dist/scripts/dev.js +312 -0
  61. package/dist/scripts/extract-global-knowledge.d.ts +1 -0
  62. package/dist/scripts/extract-global-knowledge.js +43 -0
  63. package/dist/scripts/generate-dashboard.d.ts +1 -0
  64. package/dist/scripts/generate-dashboard.js +48 -0
  65. package/dist/scripts/governance-dashboard.d.ts +2 -0
  66. package/dist/scripts/governance-dashboard.js +36 -0
  67. package/dist/scripts/hook-guard-paths.d.ts +17 -0
  68. package/dist/scripts/hook-guard-paths.js +68 -0
  69. package/dist/scripts/hook-post-edit.d.ts +20 -0
  70. package/dist/scripts/hook-post-edit.js +70 -0
  71. package/dist/scripts/hook-session-start.d.ts +17 -0
  72. package/dist/scripts/hook-session-start.js +108 -0
  73. package/dist/scripts/hook-user-prompt.d.ts +22 -0
  74. package/dist/scripts/hook-user-prompt.js +193 -0
  75. package/dist/scripts/memory-schema.d.ts +6 -0
  76. package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
  77. package/dist/scripts/query-universal-memory.d.ts +1 -0
  78. package/dist/scripts/query-universal-memory.js +44 -0
  79. package/dist/scripts/release-check.d.ts +14 -0
  80. package/dist/scripts/release-check.js +48 -0
  81. package/dist/scripts/spec-cli.d.ts +29 -0
  82. package/dist/scripts/spec-cli.js +261 -0
  83. package/dist/scripts/sprint-manager.d.ts +1 -0
  84. package/dist/scripts/sprint-manager.js +187 -0
  85. package/dist/scripts/sync-universal-memory.d.ts +1 -0
  86. package/dist/scripts/sync-universal-memory.js +277 -0
  87. package/dist/scripts/token-benchmark.d.ts +20 -0
  88. package/dist/scripts/token-benchmark.js +181 -0
  89. package/dist/scripts/tools-doctor.d.ts +20 -0
  90. package/dist/scripts/tools-doctor.js +120 -0
  91. package/memory/90-decisions/0028-governanca-visivel.md +84 -0
  92. package/package.json +54 -56
  93. package/specs/governanca-visivel/plan.md +122 -0
  94. package/specs/governanca-visivel/spec.md +112 -0
  95. package/specs/governanca-visivel/tasks.md +60 -0
  96. package/specs/ts-migration/plan.md +24 -13
  97. package/bin/create-memory-nest-kit.js +0 -125
  98. package/bin/forja.mjs +0 -143
  99. package/bin/init-project.js +0 -612
  100. package/lib/context-builder.js +0 -257
  101. package/lib/core/checks.mjs +0 -155
  102. package/lib/core/doc-graph.mjs +0 -231
  103. package/lib/core/health.mjs +0 -577
  104. package/lib/core/registry.mjs +0 -312
  105. package/lib/core/release.mjs +0 -492
  106. package/lib/templates/harness/code-intel.mjs +0 -119
  107. package/lib/templates/harness/mcp.json +0 -10
  108. package/lib/utils/file-helpers.js +0 -40
  109. package/lib/validators/structure-validator.js +0 -253
  110. package/lib/workspace.mjs +0 -213
  111. package/scripts/agent-harness.mjs +0 -580
  112. package/scripts/agent-router.mjs +0 -189
  113. package/scripts/build-smart-context.js +0 -87
  114. package/scripts/check-standards.js +0 -98
  115. package/scripts/compress-memory.mjs +0 -198
  116. package/scripts/compress-project-memory.js +0 -58
  117. package/scripts/context-ops.mjs +0 -466
  118. package/scripts/dev.mjs +0 -349
  119. package/scripts/extract-global-knowledge.js +0 -52
  120. package/scripts/generate-dashboard.js +0 -59
  121. package/scripts/hook-guard-paths.mjs +0 -76
  122. package/scripts/hook-post-edit.mjs +0 -79
  123. package/scripts/hook-session-start.mjs +0 -104
  124. package/scripts/hook-user-prompt.mjs +0 -185
  125. package/scripts/pre-commit.sh +0 -102
  126. package/scripts/query-universal-memory.js +0 -50
  127. package/scripts/release-check.mjs +0 -56
  128. package/scripts/spec-cli.mjs +0 -261
  129. package/scripts/sprint-manager.js +0 -200
  130. package/scripts/sync-universal-memory.js +0 -286
  131. package/scripts/token-benchmark.mjs +0 -203
  132. package/scripts/tools-doctor.mjs +0 -132
@@ -1,257 +0,0 @@
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
-
12
- import fs from 'node:fs';
13
- import path from 'node:path';
14
- import Database from 'better-sqlite3';
15
- import { getDbPath, ensureSchema } from '../scripts/memory-schema.mjs';
16
-
17
- export class ContextBuilder {
18
- constructor(projectPath, dbPath) {
19
- this.projectPath = projectPath;
20
- this.dbPath = dbPath;
21
- this.db = null;
22
- this.cache = new Map();
23
- this.maxCacheSize = 50; // MB
24
- }
25
-
26
- /**
27
- * Abrir conexão com banco de dados (readonly)
28
- */
29
- connect() {
30
- if (this.db) return;
31
-
32
- if (!fs.existsSync(this.dbPath)) {
33
- throw new Error(`Database not found: ${this.dbPath}`);
34
- }
35
-
36
- this.db = new Database(this.dbPath, { readonly: true });
37
- }
38
-
39
- /**
40
- * Fechar conexão
41
- */
42
- close() {
43
- if (this.db) {
44
- this.db.close();
45
- this.db = null;
46
- }
47
- }
48
-
49
- /**
50
- * Construir contexto no modo especificado
51
- *
52
- * @param {string} mode - 'global', 'domain', 'task'
53
- * @param {string} project - Nome do projeto
54
- * @param {string} keyword - Palavra-chave para busca (modo 'task')
55
- * @returns {string} Conteúdo do contexto em markdown
56
- */
57
- build(mode, project, keyword = '') {
58
- this.connect();
59
-
60
- const started = Date.now();
61
- const nodes = [];
62
- const seenPaths = new Set();
63
-
64
- // 1. Contexto global obrigatório
65
- const globalNodes = this._getGlobalNodes();
66
- nodes.push(...globalNodes);
67
-
68
- // 2. Contexto específico por modo
69
- if (mode === 'domain' || mode === 'task') {
70
- const domainNodes = this._getDomainNodes(project);
71
- nodes.push(...domainNodes);
72
- }
73
-
74
- if (mode === 'task' && keyword) {
75
- const taskNodes = this._getTaskNodes(project, keyword);
76
- nodes.push(...taskNodes);
77
- }
78
-
79
- // 3. Gerar markdown deduplicado
80
- let context = this._generateMarkdown(mode, project, keyword, nodes, seenPaths);
81
- const duration = Date.now() - started;
82
-
83
- // 4. Adicionar footer com metadata
84
- const footer = `\n\n---\n\n## 📊 Context Metadata\n\n` +
85
- `- **Mode**: ${mode}\n` +
86
- `- **Project**: ${project}\n` +
87
- `- **Keyword**: ${keyword || 'none'}\n` +
88
- `- **Generated**: ${new Date().toISOString()}\n` +
89
- `- **Duration**: ${duration}ms\n` +
90
- `- **Files**: ${seenPaths.size}\n` +
91
- `- **Size**: ${Math.round(context.length / 1024)}KB\n`;
92
-
93
- return context + footer;
94
- }
95
-
96
- /**
97
- * Obter contexto global (mission, standards, padrões)
98
- */
99
- _getGlobalNodes() {
100
- try {
101
- const stmt = this.db.prepare(`
102
- SELECT title, content, path FROM memory_nodes
103
- WHERE project_id IS NULL
104
- AND (
105
- path LIKE '%mission.md'
106
- OR path LIKE '%standards.md'
107
- OR path LIKE '%ADR-%'
108
- )
109
- ORDER BY updated_at DESC
110
- LIMIT 10
111
- `);
112
- return stmt.all() || [];
113
- } catch (e) {
114
- console.warn('⚠️ No global nodes found:', e.message);
115
- return [];
116
- }
117
- }
118
-
119
- /**
120
- * Obter contexto de domínio (vision, design, rules do projeto)
121
- */
122
- _getDomainNodes(project) {
123
- try {
124
- const stmt = this.db.prepare(`
125
- SELECT DISTINCT n.title, n.content, n.path
126
- FROM memory_nodes n
127
- JOIN projects p ON p.id = n.project_id
128
- WHERE p.name = ?
129
- AND (
130
- n.path LIKE '%vision.md'
131
- OR n.path LIKE '%design%'
132
- OR n.path LIKE '%rules.md'
133
- OR n.path LIKE '%summary%'
134
- )
135
- ORDER BY n.updated_at DESC
136
- LIMIT 15
137
- `);
138
- return stmt.all(project) || [];
139
- } catch (e) {
140
- console.warn(`⚠️ No domain nodes found for ${project}:`, e.message);
141
- return [];
142
- }
143
- }
144
-
145
- /**
146
- * Obter contexto orientado a tarefa (busca por FTS5)
147
- */
148
- _getTaskNodes(project, keyword) {
149
- try {
150
- const stmt = this.db.prepare(`
151
- SELECT DISTINCT n.title, n.content, n.path
152
- FROM memory_nodes n
153
- JOIN projects p ON p.id = n.project_id
154
- LEFT JOIN search_idx s ON s.node_id = n.id
155
- WHERE p.name = ?
156
- AND (n.content LIKE ? OR s.content MATCH ?)
157
- ORDER BY n.updated_at DESC
158
- LIMIT 20
159
- `);
160
- const pattern = `%${keyword}%`;
161
- return stmt.all(project, pattern, keyword) || [];
162
- } catch (e) {
163
- console.warn(`⚠️ No task nodes found for "${keyword}":`, e.message);
164
- return [];
165
- }
166
- }
167
-
168
- /**
169
- * Gerar markdown deduplicado
170
- */
171
- _generateMarkdown(mode, project, keyword, nodes, seenPaths) {
172
- let md = `# CONTEXT PACK: ${project.toUpperCase()}\n\n`;
173
- md += `**Mode**: \`${mode}\`\n`;
174
- if (keyword) md += `**Search**: \`${keyword}\`\n`;
175
- md += `\n`;
176
-
177
- for (const node of nodes) {
178
- if (seenPaths.has(node.path)) continue;
179
- seenPaths.add(node.path);
180
-
181
- md += `## 📄 ${node.title}\n`;
182
- md += `**Path**: \`${node.path}\`\n\n`;
183
- md += `${node.content}\n\n`;
184
- md += `---\n\n`;
185
- }
186
-
187
- return md;
188
- }
189
-
190
- /**
191
- * Salvar contexto em arquivo
192
- */
193
- save(content, outputPath) {
194
- const dir = path.dirname(outputPath);
195
- if (!fs.existsSync(dir)) {
196
- fs.mkdirSync(dir, { recursive: true });
197
- }
198
- fs.writeFileSync(outputPath, content, 'utf8');
199
- }
200
-
201
- /**
202
- * Estatísticas de contexto
203
- */
204
- stats(mode, project, keyword = '') {
205
- const content = this.build(mode, project, keyword);
206
- const lines = content.split('\n').length;
207
- const tokens = Math.round(content.length / 4); // Aproximação simples
208
-
209
- return {
210
- mode,
211
- project,
212
- keyword,
213
- bytes: content.length,
214
- lines,
215
- tokens,
216
- estimatedCost: (tokens * 0.00001).toFixed(4), // Assumindo $0.00001 por token
217
- };
218
- }
219
- }
220
-
221
- /**
222
- * Modo CLI - Executar via node scripts/context-builder.mjs
223
- */
224
- if (import.meta.url === `file://${process.argv[1]}`) {
225
- const [mode, project, keyword] = process.argv.slice(2);
226
-
227
- if (!mode || !project) {
228
- console.error('Usage: node context-builder.mjs <mode> <project> [keyword]');
229
- console.error('Modes: global, domain, task');
230
- process.exit(1);
231
- }
232
-
233
- ensureSchema({ silent: true });
234
- const dbPath = getDbPath();
235
- const builder = new ContextBuilder(process.cwd(), dbPath);
236
-
237
- try {
238
- console.log(`🔨 Building ${mode} context for ${project}...`);
239
- const content = builder.build(mode, project, keyword);
240
- const stats = builder.stats(mode, project, keyword);
241
-
242
- const outDir = path.join(process.cwd(), '.context');
243
- const outFile = path.join(outDir, `context-${mode}.md`);
244
-
245
- builder.save(content, outFile);
246
-
247
- console.log(`✅ Context saved: ${outFile}`);
248
- console.log(`📊 Stats:`, stats);
249
- } catch (e) {
250
- console.error('❌ Error:', e.message);
251
- process.exit(1);
252
- } finally {
253
- builder.close();
254
- }
255
- }
256
-
257
- export default ContextBuilder;
@@ -1,155 +0,0 @@
1
- /**
2
- * lib/core/checks.mjs — o runner de checks. Sem opinião sobre o que se checa.
3
- *
4
- * Máquina compartilhada por dois catálogos, cada um guardando uma fronteira:
5
- *
6
- * health.mjs o núcleo — o que impede o framework de trabalhar aqui (SPEC-009, ADR-0023)
7
- * release.mjs o tarball — o que impede o pacote de funcionar na máquina de quem instala (SPEC-010)
8
- *
9
- * O runner foi extraído, e não copiado, de propósito: duas máquinas iguais divergem com o tempo, e
10
- * divergência entre superfícies que deveriam concordar é exatamente o defeito que a SPEC-009
11
- * existiu para matar (o doctor e o hook diziam coisas diferentes sobre a mesma memória).
12
- *
13
- * Dois princípios, que valem para qualquer check novo em qualquer catálogo:
14
- *
15
- * 1. **Nunca colapsar causas distintas num booleano.** Um probe classifica a causa e devolve a
16
- * correção *dela*. O bug que originou tudo isso era um `catch { return null }` que engolia três
17
- * causas e prescrevia a correção de uma.
18
- * 2. **Uma causa, uma linha vermelha.** Check cuja dependência falhou é `skipped`, não `fail` —
19
- * senão uma raiz vira três erros vermelhos e o operador não sabe qual perseguir.
20
- */
21
-
22
- /** @typedef {'critical'|'warn'} Severity */
23
- /** @typedef {'runtime'|'repo'} Scope */
24
- /** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
25
-
26
- /**
27
- * @typedef {object} Check
28
- * @property {string} id
29
- * @property {string} title
30
- * @property {Severity} severity `critical` trava o gate; `warn` informa.
31
- * @property {Scope=} scope Filtro opcional do runner.
32
- * @property {string=} dependsOn Id de outro check. Se ele não passar, este vira `skipped`.
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).
35
- */
36
-
37
- /**
38
- * @typedef {object} Probe
39
- * @property {Status} status
40
- * @property {string} detail O que foi observado, em uma linha.
41
- * @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
42
- */
43
-
44
- /** @typedef {{ id: string, title: string, severity: Severity, scope?: Scope, status: Status, detail: string, fix: string|null }} Result */
45
-
46
- /** @type {Severity} */
47
- const SEVERITY_FALLBACK = 'critical';
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
-
61
- /**
62
- * Um probe que estoura é pior que probe nenhum: derrubaria o diagnóstico justamente no ambiente
63
- * quebrado que ele existe para diagnosticar. O runner blinda cada um e segue para o próximo.
64
- */
65
- async function runProbe(check, env) {
66
- try {
67
- const probe = await check.probe(env);
68
- return {
69
- status: probe.status,
70
- detail: probe.detail,
71
- fix: probe.fix ?? null,
72
- };
73
- } catch (err) {
74
- const e = asErrno(err);
75
- return {
76
- status: 'fail',
77
- detail: `probe falhou: ${e.message || e}`,
78
- fix: null,
79
- };
80
- }
81
- }
82
-
83
- /**
84
- * Executa os checks na ordem declarada.
85
- *
86
- * @param {{ checks: Check[], scope?: Scope|'all', env?: object }} opts
87
- * @returns {Promise<Result[]>}
88
- */
89
- export async function runChecks({ checks, scope = 'all', env = {} }) {
90
- const selected = checks.filter((c) => scope === 'all' || c.scope === scope);
91
- /** @type {Map<string, Status>} */
92
- const statusById = new Map();
93
- /** @type {Result[]} */
94
- const results = [];
95
-
96
- for (const check of selected) {
97
- const base = {
98
- id: check.id,
99
- title: check.title,
100
- severity: check.severity || SEVERITY_FALLBACK,
101
- scope: check.scope,
102
- };
103
-
104
- // Cascata: sem a dependência de pé, este probe não tem o que observar. Propaga por cadeia, não
105
- // só um nível — `skipped` conta como "não verificado" para quem depende dele.
106
- const depStatus = check.dependsOn ? statusById.get(check.dependsOn) : null;
107
- if (depStatus === 'fail' || depStatus === 'skipped') {
108
- const motivo = depStatus === 'fail' ? 'que falhou' : 'que não foi verificado';
109
- results.push({
110
- ...base,
111
- status: 'skipped',
112
- detail: `não verificado: depende de "${check.dependsOn}", ${motivo}`,
113
- fix: null,
114
- });
115
- statusById.set(check.id, 'skipped');
116
- continue;
117
- }
118
-
119
- const probe = await runProbe(check, env);
120
- statusById.set(check.id, probe.status);
121
- results.push({ ...base, ...probe });
122
- }
123
-
124
- return results;
125
- }
126
-
127
- /**
128
- * Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
129
- * é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
130
- *
131
- * @param {Result[]} results
132
- * @returns {'ok'|'warn'|'fail'}
133
- */
134
- export function worstStatus(results) {
135
- let seenWarn = false;
136
-
137
- for (const r of results) {
138
- if (r.status === 'fail' && r.severity === 'critical') return 'fail';
139
- if (r.status === 'fail' || r.status === 'warn') seenWarn = true;
140
- }
141
-
142
- return seenWarn ? 'warn' : 'ok';
143
- }
144
-
145
- /**
146
- * Remove template literals do fonte antes de qualquer análise estática de `import`.
147
- *
148
- * Os geradores do Forja *escrevem* código NestJS dentro de crases — `import { Module } from
149
- * '@nestjs/common'` é texto que eles emitem, não dependência que eles usam. Contá-lo faz o check
150
- * acusar `@nestjs/core` como dependência não declarada e `./app.module` como import quebrado.
151
- * Observado em campo ao auditar o tarball da 1.1.3.
152
- */
153
- export function stripTemplateLiterals(source) {
154
- return source.replace(/`(?:\\.|[^`\\])*`/gs, '``');
155
- }
@@ -1,231 +0,0 @@
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
- }