forjajs 1.2.0 → 1.3.1

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 +41 -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
@@ -0,0 +1,538 @@
1
+ /**
2
+ * lib/core/health.mjs — saúde do núcleo do Forja.
3
+ *
4
+ * Fonte única de verdade sobre o que impede o framework de trabalhar. Consumida por
5
+ * `tools:doctor` (gate, com exit code), pelo hook `SessionStart` (aviso, nunca trava) e,
6
+ * futuramente, pelo release-auditor.
7
+ *
8
+ * Por que existir (SPEC-009):
9
+ *
10
+ * O `tools:doctor` auditava cinco ferramentas *opcionais* — sobre as quais ele mesmo dizia
11
+ * "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o `better-sqlite3`
12
+ * ficou com ABI de outra major do Node, a memória universal morreu inteira: o doctor reportou
13
+ * "2/5 ferramentas disponíveis", e o SessionStart prescreveu `npm install`, que não recompila
14
+ * binário nativo. A correção real era `npm rebuild better-sqlite3`. Cada superfície tinha sua
15
+ * própria heurística, e por isso uma delas pôde mentir sozinha.
16
+ *
17
+ * Dois princípios, que valem para qualquer check novo:
18
+ *
19
+ * 1. **Nunca colapsar causas distintas num booleano.** O bug original era um `catch { return
20
+ * null }` que engolia "sem node_modules", "ABI incompatível" e "banco ausente" no mesmo
21
+ * `null` — e então prescrevia a correção de apenas uma das três. Um probe classifica a causa
22
+ * e devolve a correção *dela*.
23
+ * 2. **Uma causa, uma linha vermelha.** Com o ABI quebrado, os checks de memória também
24
+ * falhariam, e o operador veria três erros sem saber qual é a raiz. Daí `dependsOn`: check
25
+ * cuja dependência falhou é `skipped`, não `fail`.
26
+ */
27
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
28
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
29
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
30
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
31
+ });
32
+ }
33
+ return path;
34
+ };
35
+ import fs from 'node:fs';
36
+ import path from 'node:path';
37
+ import { fileURLToPath } from 'node:url';
38
+ import { getWorkspaceDbPath, getWorkspaceInfo } from "../workspace.js";
39
+ import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from "./checks.js";
40
+ import { COMMANDS } from "./registry.js";
41
+ import { scanCommands, scanLinks, projectCommands } from "./doc-graph.js";
42
+ // Os contratos vivem em checks.mjs — importados, não redefinidos. As cópias locais eram resíduo da
43
+ // extração do runner (SPEC-010) e já divergiam.
44
+ /** @typedef {import('./checks.ts').Check} Check */
45
+ /** @typedef {import('./checks.ts').Result} Result */
46
+ /** @typedef {import('./checks.ts').Status} Status */
47
+ // O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
48
+ // aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
49
+ export { worstStatus };
50
+ const __filename = fileURLToPath(import.meta.url);
51
+ const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
52
+ /**
53
+ * Ambiente injetável. Existe para que os probes sejam testáveis sem mockar o loader de módulos
54
+ * do Node nem corromper `node_modules` de verdade — simular um ABI quebrado é passar um
55
+ * `importModule` que lança `ERR_DLOPEN_FAILED`.
56
+ *
57
+ * @typedef {object} Env
58
+ * @property {string} root Raiz do repo do framework.
59
+ * @property {typeof fs} fs
60
+ * @property {(specifier: string) => Promise<unknown>} importModule
61
+ * @property {object} process Só o que os probes leem: `versions`, `env`.
62
+ * @property {{ dbPath: () => string, info: () => object }} workspace
63
+ */
64
+ /** @returns {Env} */
65
+ export function defaultEnv(overrides = {}) {
66
+ return {
67
+ root: repoRoot,
68
+ fs,
69
+ importModule: (specifier) => import(__rewriteRelativeImportExtension(specifier)),
70
+ process: globalThis.process,
71
+ workspace: { dbPath: getWorkspaceDbPath, info: getWorkspaceInfo },
72
+ ...overrides,
73
+ };
74
+ }
75
+ // ---------------------------------------------------------------------------
76
+ // Probes
77
+ // ---------------------------------------------------------------------------
78
+ /**
79
+ * O check que teria pego a quebra de 2026-07-13.
80
+ *
81
+ * Importar `better-sqlite3` **não** basta: o binding nativo só é aberto no construtor — o
82
+ * `ERR_DLOPEN_FAILED` original vinha de `new Database`, não do import. Um probe que só importasse
83
+ * o módulo daria verde num ambiente quebrado.
84
+ *
85
+ * Classificamos por `err.code`, nunca pela mensagem: o texto do erro varia entre versões do Node,
86
+ * e este check existe precisamente para sobreviver a troca de versão do Node.
87
+ */
88
+ /** @type {Check} */
89
+ const nativeAbi = {
90
+ id: 'native-abi',
91
+ title: 'better-sqlite3 carrega no Node atual',
92
+ severity: 'critical',
93
+ scope: 'runtime',
94
+ async probe(env) {
95
+ let Database;
96
+ try {
97
+ ({ default: Database } = await env.importModule('better-sqlite3'));
98
+ }
99
+ catch (err) {
100
+ if (asErrno(err).code === 'ERR_MODULE_NOT_FOUND') {
101
+ return {
102
+ status: 'fail',
103
+ detail: 'better-sqlite3 não está instalado — toda a memória universal fica indisponível',
104
+ fix: 'npm install',
105
+ };
106
+ }
107
+ throw err;
108
+ }
109
+ try {
110
+ new Database(':memory:').close();
111
+ }
112
+ catch (err) {
113
+ if (asErrno(err).code === 'ERR_DLOPEN_FAILED') {
114
+ const node = env.process.versions.node;
115
+ return {
116
+ status: 'fail',
117
+ detail: `binário nativo compilado para outra versão do Node (rodando v${node}). ` +
118
+ 'A memória universal está morta: query:universal, sync:universal e context:smart não funcionam. ' +
119
+ 'npm install NÃO corrige isto — ele não recompila binário nativo quando o lock já bate.',
120
+ fix: 'npm rebuild better-sqlite3',
121
+ };
122
+ }
123
+ throw err;
124
+ }
125
+ return { status: 'ok', detail: `carrega em Node v${env.process.versions.node}`, fix: null };
126
+ },
127
+ };
128
+ /** @type {Check} */
129
+ const memoryDb = {
130
+ id: 'memory-db',
131
+ title: 'universal.db acessível',
132
+ severity: 'critical',
133
+ scope: 'runtime',
134
+ dependsOn: 'native-abi',
135
+ async probe(env) {
136
+ const dbPath = env.workspace.dbPath();
137
+ // Ausente ≠ quebrado. Num clone novo (ou num CI) a memória simplesmente nunca foi indexada:
138
+ // é o estado natural, não uma falha, e um comando resolve. Reprovar aqui faria o gate travar
139
+ // por aquilo que não impede trabalho — que é como um gate deixa de ser levado a sério.
140
+ if (!env.fs.existsSync(dbPath)) {
141
+ return {
142
+ status: 'warn',
143
+ detail: `banco ainda não indexado (${dbPath}) — normal em clone novo`,
144
+ fix: 'npm run sync:universal',
145
+ };
146
+ }
147
+ // Existir não é abrir: um banco corrompido ou sem permissão dá o mesmo `existsSync` de um
148
+ // banco saudável, e o operador merece saber qual dos dois é.
149
+ const { default: Database } = await env.importModule('better-sqlite3');
150
+ try {
151
+ const db = new Database(dbPath, { readonly: true });
152
+ const { n } = db.prepare('SELECT count(*) AS n FROM memory_nodes').get();
153
+ db.close();
154
+ return { status: 'ok', detail: `${n} nós indexados`, fix: null };
155
+ }
156
+ catch (err) {
157
+ return {
158
+ status: 'fail',
159
+ detail: `banco existe mas não abre (${asErrno(err).code || asErrno(err).message}) — provavelmente corrompido`,
160
+ fix: 'npm run sync:universal',
161
+ };
162
+ }
163
+ },
164
+ };
165
+ /** mtime do .md mais recente sob um diretório, ignorando arquivados. */
166
+ function newestMarkdownMtime(env, dir, acc = { t: 0 }) {
167
+ let entries;
168
+ try {
169
+ entries = env.fs.readdirSync(dir);
170
+ }
171
+ catch {
172
+ return acc.t;
173
+ }
174
+ for (const entry of entries) {
175
+ if (entry.startsWith('.') || entry === 'archive')
176
+ continue;
177
+ const p = path.join(dir, entry);
178
+ let st;
179
+ try {
180
+ st = env.fs.statSync(p);
181
+ }
182
+ catch {
183
+ continue;
184
+ }
185
+ if (st.isDirectory())
186
+ newestMarkdownMtime(env, p, acc);
187
+ else if (entry.endsWith('.md') && st.mtimeMs > acc.t)
188
+ acc.t = st.mtimeMs;
189
+ }
190
+ return acc.t;
191
+ }
192
+ /**
193
+ * Índice defasado é a falha mais barata de corrigir e a mais cara de ignorar: `query:universal`
194
+ * é o primeiro passo da economia de tokens (ADR-0009), então um índice velho alimenta os agentes
195
+ * com o documento errado — sem erro, sem log, sem sintoma.
196
+ *
197
+ * É `warn`, não `critical`: responder sobre memória velha atrapalha, mas não impede trabalho.
198
+ */
199
+ /** @type {Check} */
200
+ const memoryFresh = {
201
+ id: 'memory-fresh',
202
+ title: 'índice em dia com memory/',
203
+ severity: 'warn',
204
+ scope: 'runtime',
205
+ dependsOn: 'memory-db',
206
+ probe(env) {
207
+ const dbPath = env.workspace.dbPath();
208
+ // `memory-db` passa com aviso quando o banco nunca foi indexado, então a cascata não nos pula:
209
+ // um índice que não existe não pode estar defasado.
210
+ if (!env.fs.existsSync(dbPath)) {
211
+ return { status: 'skipped', detail: 'não há índice para comparar', fix: null };
212
+ }
213
+ const dbMtime = env.fs.statSync(dbPath).mtimeMs;
214
+ const newest = newestMarkdownMtime(env, path.join(env.root, 'memory'));
215
+ if (newest > dbMtime) {
216
+ const horas = Math.round((newest - dbMtime) / 36e5);
217
+ return {
218
+ status: 'warn',
219
+ detail: `memory/ mudou depois do último sync (${horas}h) — query:universal vai responder ` +
220
+ 'sobre memória velha, calado',
221
+ fix: 'npm run sync:universal',
222
+ };
223
+ }
224
+ return { status: 'ok', detail: 'índice em dia', fix: null };
225
+ },
226
+ };
227
+ /**
228
+ * `warn`, não `critical`: o framework trabalha sem workspace — só `project:new` e a memória de
229
+ * produto precisam dele.
230
+ *
231
+ * Reporta a **origem** da resolução (FORJA_WORKSPACE / ~/.forjarc.json / default), que é metade do
232
+ * diagnóstico: o modo de falha interessante não é "não existe", é "existe, mas não é o que você
233
+ * pensa" — um FORJA_WORKSPACE esquecido no ambiente aponta o framework para o workspace errado, e
234
+ * tudo parece funcionar.
235
+ */
236
+ /** @type {Check} */
237
+ const workspace = {
238
+ id: 'workspace',
239
+ title: 'workspace resolvido',
240
+ severity: 'warn',
241
+ scope: 'runtime',
242
+ probe(env) {
243
+ const { root, source, exists } = env.workspace.info();
244
+ if (!exists) {
245
+ return {
246
+ status: 'warn',
247
+ detail: `workspace não existe em ${root} (origem: ${source})`,
248
+ fix: 'npm run workspace:init',
249
+ };
250
+ }
251
+ return { status: 'ok', detail: `${root} (origem: ${source})`, fix: null };
252
+ },
253
+ };
254
+ /** Compara o Node em uso com o `engines.node` declarado. Abaixo do mínimo, o resto é loteria. */
255
+ /** @type {Check} */
256
+ const nodeEngines = {
257
+ id: 'node-engines',
258
+ title: 'Node dentro de engines',
259
+ severity: 'warn',
260
+ scope: 'runtime',
261
+ probe(env) {
262
+ const current = env.process.versions.node;
263
+ const pkgPath = path.join(env.root, 'package.json');
264
+ let range;
265
+ try {
266
+ range = JSON.parse(env.fs.readFileSync(pkgPath, 'utf8'))?.engines?.node;
267
+ }
268
+ catch {
269
+ return { status: 'ok', detail: 'package.json sem engines — nada a comparar', fix: null };
270
+ }
271
+ if (!range)
272
+ return { status: 'ok', detail: 'sem engines declarado', fix: null };
273
+ // Só o caso que importa: `>=N`. Ranges mais ricos não são usados aqui, e reimplementar semver
274
+ // para um caso que não existe seria inventar problema.
275
+ const min = /^>=\s*(\d+)/.exec(range)?.[1];
276
+ if (!min)
277
+ return { status: 'ok', detail: `engines: ${range}`, fix: null };
278
+ const major = Number(current.split('.')[0]);
279
+ if (major < Number(min)) {
280
+ return {
281
+ status: 'warn',
282
+ detail: `Node v${current} abaixo do declarado (engines: ${range})`,
283
+ fix: `atualize o Node para ${min} ou superior`,
284
+ };
285
+ }
286
+ return { status: 'ok', detail: `Node v${current} (engines: ${range})`, fix: null };
287
+ },
288
+ };
289
+ // ---------------------------------------------------------------------------
290
+ // Checks de regressão do repositório (scope: repo)
291
+ //
292
+ // Convertem em gate executável dois invariantes que o ADR-0021 corrigiu à mão e que hoje podem
293
+ // reincidir sem que nada perceba. São `scope: repo` porque não fazem sentido numa instalação
294
+ // `npm i -g forjajs` — lá não há devDependencies instaladas nem .mcp.json versionado, e rodá-los
295
+ // produziria falso positivo crítico na máquina do usuário final.
296
+ // ---------------------------------------------------------------------------
297
+ /** Estamos dentro do repo do framework, e não numa instalação do pacote? */
298
+ export function isFrameworkRepo(env) {
299
+ try {
300
+ if (!env.fs.existsSync(path.join(env.root, '.git')))
301
+ return false;
302
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.root, 'package.json'), 'utf8'));
303
+ return pkg.name === 'forjajs';
304
+ }
305
+ catch {
306
+ return false;
307
+ }
308
+ }
309
+ const IMPORT_RE = /^\s*import\s+(?:[\w*{}\n\r\t, ]+from\s+)?['"]([^'"]+)['"]/gm;
310
+ /** Pacote npm (não builtin, não relativo). `@scope/x/sub` → `@scope/x`; `x/sub` → `x`. */
311
+ function packageName(specifier) {
312
+ if (specifier.startsWith('.') || specifier.startsWith('/'))
313
+ return null;
314
+ if (specifier.startsWith('node:'))
315
+ return null;
316
+ const parts = specifier.split('/');
317
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
318
+ }
319
+ /**
320
+ * ADR-0021 §2: dez scripts sob `files[]` importavam `better-sqlite3` estaticamente, e o pacote
321
+ * declarava zero `dependencies`. Numa instalação limpa, metade dos comandos estourava com
322
+ * `ERR_MODULE_NOT_FOUND` — e o `forja` sem argumentos funcionava, o que mascarava a quebra.
323
+ *
324
+ * Conservador de propósito: só olha import **estático** de script publicado. Import dinâmico não
325
+ * conta (é o padrão do carregamento lazy, e lazy é justamente o que o ADR-0021 pediu).
326
+ */
327
+ /** @type {Check} */
328
+ const runtimeDeps = {
329
+ id: 'runtime-deps',
330
+ title: 'deps de runtime declaradas',
331
+ severity: 'critical',
332
+ scope: 'repo',
333
+ probe(env) {
334
+ if (!isFrameworkRepo(env)) {
335
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
336
+ }
337
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.root, 'package.json'), 'utf8'));
338
+ const deps = new Set(Object.keys(pkg.dependencies || {}));
339
+ const devDeps = new Set(Object.keys(pkg.devDependencies || {}));
340
+ // Diretórios publicados que contêm código executável.
341
+ const published = (pkg.files || [])
342
+ .filter((f) => !f.startsWith('!') && /^(bin|lib|scripts)\//.test(f))
343
+ .map((f) => path.join(env.root, f.replace(/\/+$/, '')));
344
+ const offenders = new Map();
345
+ const walk = (dir) => {
346
+ let entries;
347
+ try {
348
+ entries = env.fs.readdirSync(dir);
349
+ }
350
+ catch {
351
+ return;
352
+ }
353
+ for (const entry of entries) {
354
+ const p = path.join(dir, entry);
355
+ let st;
356
+ try {
357
+ st = env.fs.statSync(p);
358
+ }
359
+ catch {
360
+ continue;
361
+ }
362
+ if (st.isDirectory()) {
363
+ walk(p);
364
+ continue;
365
+ }
366
+ if (!/\.(mjs|js)$/.test(entry))
367
+ continue;
368
+ // Sem apagar os template literals, os geradores acusam a si mesmos: `nest-generator.js`
369
+ // emite `import { INestApplication } from '@nestjs/common'` dentro de crases — código que
370
+ // ele *escreve* para o projeto gerado, não que ele importa. Como a linha começa com
371
+ // `import`, a âncora do parser casa. Hoje passaria por sorte (`@nestjs/*` não está nas
372
+ // devDeps); no dia em que estivesse, este check travaria o gate sem motivo.
373
+ const src = stripTemplateLiterals(env.fs.readFileSync(p, 'utf8'));
374
+ for (const [, specifier] of src.matchAll(IMPORT_RE)) {
375
+ const name = packageName(specifier);
376
+ if (!name || deps.has(name))
377
+ continue;
378
+ if (devDeps.has(name)) {
379
+ offenders.set(name, path.relative(env.root, p));
380
+ }
381
+ }
382
+ }
383
+ };
384
+ published.forEach(walk);
385
+ if (offenders.size) {
386
+ const lista = [...offenders].map(([n, f]) => `${n} (${f})`).join(', ');
387
+ return {
388
+ status: 'fail',
389
+ detail: `importado por script publicado, mas declarado em devDependencies: ${lista}`,
390
+ fix: `npm i -S ${[...offenders.keys()].join(' ')}`,
391
+ };
392
+ }
393
+ return { status: 'ok', detail: 'imports de scripts publicados estão em dependencies', fix: null };
394
+ },
395
+ };
396
+ /**
397
+ * ADR-0021 §1: `.mcp.json` versionado com `-p /home/apk/.../projects/forja`, uma cópia parada do
398
+ * repo. O codegraph indexava código morto e respondia com confiança sobre ele. O path também
399
+ * quebrava para qualquer outro contribuidor.
400
+ */
401
+ /** @type {Check} */
402
+ const mcpJson = {
403
+ id: 'mcp-json',
404
+ title: '.mcp.json sem path absoluto',
405
+ severity: 'critical',
406
+ scope: 'repo',
407
+ probe(env) {
408
+ if (!isFrameworkRepo(env)) {
409
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
410
+ }
411
+ const file = path.join(env.root, '.mcp.json');
412
+ if (!env.fs.existsSync(file)) {
413
+ return { status: 'ok', detail: '.mcp.json ausente — nada a validar', fix: null };
414
+ }
415
+ const raw = env.fs.readFileSync(file, 'utf8');
416
+ // Um path absoluto num arquivo versionado só pode estar certo na máquina de quem escreveu.
417
+ const hits = raw.match(/["'](\/(?:home|Users)\/[^"']+)["']/g);
418
+ if (hits) {
419
+ return {
420
+ status: 'fail',
421
+ detail: `path absoluto versionado: ${hits.join(', ')} — aponta para a máquina de quem commitou`,
422
+ fix: 'remova o path de .mcp.json (o MCP resolve o projeto pelo rootUri do cliente)',
423
+ };
424
+ }
425
+ return { status: 'ok', detail: 'sem paths absolutos', fix: null };
426
+ },
427
+ };
428
+ // ---------------------------------------------------------------------------
429
+ // Coerência da documentação (SPEC-011, ADR-0025)
430
+ //
431
+ // O Forja é operado por agentes que executam o que a doc manda. Quando a doc e o registry divergem,
432
+ // o agente erra por obediência. Estes três checks trazem a classe "erra sem avisar" (ADR-0021) para
433
+ // a camada de instrução — a fronteira mais barata de corromper e a mais cara de perceber.
434
+ // ---------------------------------------------------------------------------
435
+ /**
436
+ * Comando fantasma na doc faz o agente executar o que não existe e concluir que o ambiente
437
+ * quebrou. É `critical`. A allowlist do projeto gerado é **derivada** dos geradores + boilerplates
438
+ * (nunca literal), senão `start:dev`/`test:e2e` e afins dariam falso positivo.
439
+ */
440
+ /** @type {Check} */
441
+ const docsCommands = {
442
+ id: 'docs-commands',
443
+ title: 'comandos citados na doc existem',
444
+ severity: 'critical',
445
+ scope: 'repo',
446
+ probe(env) {
447
+ if (!isFrameworkRepo(env)) {
448
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
449
+ }
450
+ const known = new Set([...Object.keys(COMMANDS), ...projectCommands(env)]);
451
+ const ghosts = scanCommands(env).filter((c) => !known.has(c.command));
452
+ if (ghosts.length) {
453
+ const amostra = ghosts.slice(0, 5).map((g) => `${g.command} (${g.file}:${g.line})`).join(', ');
454
+ return {
455
+ status: 'fail',
456
+ detail: `${ghosts.length} citação(ões) de comando inexistente: ${amostra}`,
457
+ fix: 'renomeie para um comando do registry ou remova a citação no arquivo:linha indicado',
458
+ };
459
+ }
460
+ return { status: 'ok', detail: 'toda citação de comando resolve no registry', fix: null };
461
+ },
462
+ };
463
+ /**
464
+ * Capacidade que ninguém documenta é capacidade obscura. `warn`, não `critical`: um comando
465
+ * não-documentado atrapalha (o operador não sabe que existe), mas não impede trabalho.
466
+ */
467
+ /** @type {Check} */
468
+ const commandsDocumented = {
469
+ id: 'commands-documented',
470
+ title: 'todo comando do registry é documentado',
471
+ severity: 'warn',
472
+ scope: 'repo',
473
+ probe(env) {
474
+ if (!isFrameworkRepo(env)) {
475
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
476
+ }
477
+ const citados = new Set(scanCommands(env).map((c) => c.command));
478
+ const orfaos = Object.keys(COMMANDS).filter((c) => !citados.has(c));
479
+ if (orfaos.length) {
480
+ return {
481
+ status: 'warn',
482
+ detail: `${orfaos.length} comando(s) do registry sem menção em doc/prompt/agente: ${orfaos.join(', ')}`,
483
+ fix: 'documente cada um numa superfície de instrução, ou remova do registry se morto',
484
+ };
485
+ }
486
+ return { status: 'ok', detail: 'todos os comandos do registry aparecem na doc', fix: null };
487
+ },
488
+ };
489
+ /** Link relativo para o nada é step obscuro. `warn`: atrapalha a navegação, não impede trabalho. */
490
+ /** @type {Check} */
491
+ const docsLinks = {
492
+ id: 'docs-links',
493
+ title: 'links relativos da doc resolvem',
494
+ severity: 'warn',
495
+ scope: 'repo',
496
+ probe(env) {
497
+ if (!isFrameworkRepo(env)) {
498
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
499
+ }
500
+ const quebrados = scanLinks(env).filter((l) => !env.fs.existsSync(path.join(env.root, l.resolved)));
501
+ if (quebrados.length) {
502
+ const amostra = quebrados.slice(0, 5).map((q) => `${q.target} (${q.file}:${q.line})`).join(', ');
503
+ return {
504
+ status: 'warn',
505
+ detail: `${quebrados.length} link(s) relativo(s) sem alvo: ${amostra}`,
506
+ fix: 'crie o alvo ou corrija o link no arquivo:linha indicado',
507
+ };
508
+ }
509
+ return { status: 'ok', detail: 'todo link relativo resolve', fix: null };
510
+ },
511
+ };
512
+ /** @type {Check[]} */
513
+ export const CHECKS = [
514
+ nativeAbi,
515
+ memoryDb,
516
+ memoryFresh,
517
+ workspace,
518
+ nodeEngines,
519
+ runtimeDeps,
520
+ mcpJson,
521
+ docsCommands,
522
+ commandsDocumented,
523
+ docsLinks,
524
+ ];
525
+ /**
526
+ * Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
527
+ * `defaultEnv` do framework, que o runner genérico não conhece nem deve conhecer.
528
+ *
529
+ * `scope: 'runtime'` roda só os checks baratos e portáveis — é o que o hook SessionStart usa, onde
530
+ * há orçamento de 5s e nenhuma tolerância a travar a sessão.
531
+ *
532
+ * @param {{ scope?: import('./checks.ts').Scope|'all', env?: Partial<Env>, checks?: Check[] }} [opts]
533
+ * @returns {Promise<Result[]>}
534
+ */
535
+ export async function runChecks(opts = {}) {
536
+ const { scope = 'all', checks = CHECKS } = opts;
537
+ return run({ checks, scope, env: defaultEnv(opts.env) });
538
+ }