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.
- package/CHANGELOG.md +69 -0
- package/README.en.md +1 -0
- package/README.md +10 -4
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
- package/dist/bin/create-memory-nest-kit.d.ts +11 -0
- package/dist/bin/create-memory-nest-kit.js +5 -5
- package/dist/bin/forja.js +1 -1
- package/dist/bin/init-project.d.ts +12 -0
- package/dist/bin/init-project.js +2 -2
- package/dist/lib/code-context.d.ts +41 -0
- package/dist/lib/code-context.js +108 -0
- package/dist/lib/context-builder.d.ts +15 -5
- package/dist/lib/context-builder.js +5 -0
- package/dist/lib/core/checks.d.ts +3 -3
- package/dist/lib/core/doc-graph.d.ts +13 -0
- package/dist/lib/core/doc-graph.js +48 -1
- package/dist/lib/core/health.d.ts +3 -32
- package/dist/lib/core/health.js +29 -15
- package/dist/lib/core/project-smoke.d.ts +46 -0
- package/dist/lib/core/project-smoke.js +248 -0
- package/dist/lib/core/registry.d.ts +25 -0
- package/dist/lib/core/registry.js +37 -12
- package/dist/lib/core/release.d.ts +27 -14
- package/dist/lib/core/release.js +0 -8
- package/dist/lib/generators/memory-generator.d.ts +11 -6
- package/dist/lib/generators/memory-generator.js +45 -1
- package/dist/lib/generators/nest-generator.d.ts +8 -4
- package/dist/lib/generators/nest-generator.js +1 -1
- package/dist/lib/generators/readme-generator.d.ts +7 -4
- package/dist/lib/generators/readme-generator.js +2 -1
- package/dist/lib/governance-report.d.ts +1 -1
- package/dist/lib/memory-audit.d.ts +31 -0
- package/dist/lib/memory-audit.js +81 -0
- package/dist/lib/project-upgrade.d.ts +28 -0
- package/dist/lib/project-upgrade.js +74 -0
- package/dist/lib/utils/file-helpers.d.ts +10 -6
- package/dist/lib/validators/structure-validator.d.ts +49 -27
- package/dist/scripts/code-context.d.ts +12 -0
- package/dist/scripts/code-context.js +73 -0
- package/dist/scripts/dev.d.ts +2 -2
- package/dist/scripts/dev.js +1 -1
- package/dist/scripts/memory-audit.d.ts +11 -0
- package/dist/scripts/memory-audit.js +49 -0
- package/dist/scripts/project-smoke.d.ts +14 -0
- package/dist/scripts/project-smoke.js +44 -0
- package/dist/scripts/project-upgrade.d.ts +11 -0
- package/dist/scripts/project-upgrade.js +61 -0
- package/dist/scripts/query-universal-memory.js +1 -1
- package/dist/scripts/sprint-manager.js +1 -1
- package/dist/scripts/token-benchmark.js +1 -1
- package/dist/scripts/token-economy.d.ts +20 -0
- package/dist/scripts/token-economy.js +140 -0
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +4 -0
- package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
- package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
- package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
- package/package.json +1 -1
- package/specs/code-context/spec.md +56 -0
- package/specs/memory-audit/spec.md +54 -0
- package/specs/project-smoke/spec.md +96 -0
- package/specs/project-upgrade/spec.md +58 -0
- package/specs/ts-migration/plan.md +9 -8
- package/specs/ts-migration/spec.md +1 -1
- package/dist/lib/templates/harness/code-intel.d.mts +0 -2
- package/dist/lib/templates/harness/code-intel.mjs +0 -126
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
*/
|
|
20
20
|
import fs from 'node:fs';
|
|
21
21
|
import { worstStatus } from './checks.ts';
|
|
22
|
+
import type { Check } from './checks.ts';
|
|
22
23
|
export { worstStatus };
|
|
23
24
|
/**
|
|
24
25
|
* Empacota o repo e instala o tarball num diretório temporário isolado.
|
|
@@ -37,20 +38,7 @@ export declare function withCleanInstall(fn: any, { root }?: {
|
|
|
37
38
|
root?: string | undefined;
|
|
38
39
|
}): Promise<any>;
|
|
39
40
|
/** @type {import('./checks.ts').Check[]} */
|
|
40
|
-
export declare const RELEASE_CHECKS:
|
|
41
|
-
id: string;
|
|
42
|
-
title: string;
|
|
43
|
-
severity: string;
|
|
44
|
-
probe(env: any): {
|
|
45
|
-
status: string;
|
|
46
|
-
detail: string;
|
|
47
|
-
fix: null;
|
|
48
|
-
} | {
|
|
49
|
-
status: string;
|
|
50
|
-
detail: string;
|
|
51
|
-
fix: string;
|
|
52
|
-
};
|
|
53
|
-
}[];
|
|
41
|
+
export declare const RELEASE_CHECKS: Check[];
|
|
54
42
|
export declare function defaultEnv(overrides?: {}): {
|
|
55
43
|
root: string;
|
|
56
44
|
fs: typeof fs;
|
|
@@ -74,6 +62,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
74
62
|
node: string;
|
|
75
63
|
args: string[];
|
|
76
64
|
};
|
|
65
|
+
'project:upgrade': {
|
|
66
|
+
domain: string;
|
|
67
|
+
desc: string;
|
|
68
|
+
node: string;
|
|
69
|
+
};
|
|
77
70
|
'workspace:project:check': {
|
|
78
71
|
domain: string;
|
|
79
72
|
desc: string;
|
|
@@ -176,6 +169,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
176
169
|
node: string;
|
|
177
170
|
args: string[];
|
|
178
171
|
};
|
|
172
|
+
'code:context': {
|
|
173
|
+
domain: string;
|
|
174
|
+
desc: string;
|
|
175
|
+
node: string;
|
|
176
|
+
};
|
|
179
177
|
'code:index': {
|
|
180
178
|
domain: string;
|
|
181
179
|
desc: string;
|
|
@@ -232,6 +230,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
232
230
|
desc: string;
|
|
233
231
|
node: string;
|
|
234
232
|
};
|
|
233
|
+
'memory:audit': {
|
|
234
|
+
domain: string;
|
|
235
|
+
desc: string;
|
|
236
|
+
node: string;
|
|
237
|
+
};
|
|
235
238
|
'context:smart': {
|
|
236
239
|
domain: string;
|
|
237
240
|
desc: string;
|
|
@@ -273,6 +276,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
273
276
|
desc: string;
|
|
274
277
|
node: string;
|
|
275
278
|
};
|
|
279
|
+
'token:economy': {
|
|
280
|
+
domain: string;
|
|
281
|
+
desc: string;
|
|
282
|
+
node: string;
|
|
283
|
+
};
|
|
276
284
|
'project:check': {
|
|
277
285
|
domain: string;
|
|
278
286
|
desc: string;
|
|
@@ -288,6 +296,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
288
296
|
desc: string;
|
|
289
297
|
node: string;
|
|
290
298
|
};
|
|
299
|
+
'project:smoke': {
|
|
300
|
+
domain: string;
|
|
301
|
+
desc: string;
|
|
302
|
+
node: string;
|
|
303
|
+
};
|
|
291
304
|
'project:dashboard': {
|
|
292
305
|
domain: string;
|
|
293
306
|
desc: string;
|
package/dist/lib/core/release.js
CHANGED
|
@@ -23,7 +23,6 @@ import os from 'node:os';
|
|
|
23
23
|
import path from 'node:path';
|
|
24
24
|
import { fileURLToPath } from 'node:url';
|
|
25
25
|
import { runChecks as run, worstStatus, stripTemplateLiterals } from "./checks.js";
|
|
26
|
-
/** @typedef {import('./checks.ts').Check} Check */
|
|
27
26
|
import { COMMANDS, resolveScript } from "./registry.js";
|
|
28
27
|
export { worstStatus };
|
|
29
28
|
const __filename = fileURLToPath(import.meta.url);
|
|
@@ -112,7 +111,6 @@ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
|
|
|
112
111
|
* Severidade depende do modo: sob `--publish` é fatal; em dev é aviso — um gate que reprova todo
|
|
113
112
|
* desenvolvimento local é um gate que se contorna (a lição que o CI nos deu na SPEC-009).
|
|
114
113
|
*/
|
|
115
|
-
/** @type {Check} */
|
|
116
114
|
const treeClean = {
|
|
117
115
|
id: 'tree-clean',
|
|
118
116
|
title: 'árvore limpa (o tarball é o commit)',
|
|
@@ -135,7 +133,6 @@ const treeClean = {
|
|
|
135
133
|
},
|
|
136
134
|
};
|
|
137
135
|
/** Se o pacote não instala, todo o resto é irrelevante — daí todos dependerem deste. */
|
|
138
|
-
/** @type {Check} */
|
|
139
136
|
const install = {
|
|
140
137
|
id: 'install',
|
|
141
138
|
title: 'o pacote instala do zero',
|
|
@@ -150,7 +147,6 @@ const install = {
|
|
|
150
147
|
* Todo comando anunciado pelo registry precisa existir no tarball. É o bug da v1.1.3, generalizado:
|
|
151
148
|
* `npm run dashboard` era publicado, a pasta `dashboard/` não.
|
|
152
149
|
*/
|
|
153
|
-
/** @type {Check} */
|
|
154
150
|
const registryScripts = {
|
|
155
151
|
id: 'registry-scripts',
|
|
156
152
|
title: 'todo comando do registry existe no tarball',
|
|
@@ -266,7 +262,6 @@ function packageName(specifier) {
|
|
|
266
262
|
return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
|
|
267
263
|
}
|
|
268
264
|
/** Import relativo que não resolve dentro do tarball = arquivo fora do `files[]` (bug da v1.1.3). */
|
|
269
|
-
/** @type {Check} */
|
|
270
265
|
const importsResolve = {
|
|
271
266
|
id: 'imports-resolve',
|
|
272
267
|
title: 'imports relativos resolvem dentro do tarball',
|
|
@@ -296,7 +291,6 @@ const importsResolve = {
|
|
|
296
291
|
},
|
|
297
292
|
};
|
|
298
293
|
/** O bug do ADR-0021 §2: importado por script publicado, mas declarado como devDependency. */
|
|
299
|
-
/** @type {Check} */
|
|
300
294
|
const depsDeclared = {
|
|
301
295
|
id: 'deps-declared',
|
|
302
296
|
title: 'todo import externo está em dependencies',
|
|
@@ -326,7 +320,6 @@ const depsDeclared = {
|
|
|
326
320
|
},
|
|
327
321
|
};
|
|
328
322
|
/** Peso morto viaja no tarball de todo usuário. Incomoda; não quebra — por isso `warn` (D7). */
|
|
329
|
-
/** @type {Check} */
|
|
330
323
|
const depsUnused = {
|
|
331
324
|
id: 'deps-unused',
|
|
332
325
|
title: 'nenhuma dependency é peso morto',
|
|
@@ -367,7 +360,6 @@ const depsUnused = {
|
|
|
367
360
|
* code reprovaria um pacote saudável — a mesma armadilha do `memory-db` na SPEC-009, um nível
|
|
368
361
|
* acima.
|
|
369
362
|
*/
|
|
370
|
-
/** @type {Check} */
|
|
371
363
|
const smokeCommands = {
|
|
372
364
|
id: 'smoke-commands',
|
|
373
365
|
title: 'os comandos executam de verdade',
|
|
@@ -1,9 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Memory Generator - Gera estrutura completa de memória hierárquica
|
|
3
|
+
* Extraído de create-memory-nest-kit.js para modularização
|
|
4
|
+
*/
|
|
1
5
|
/**
|
|
2
6
|
* Retorna todos os templates combinados
|
|
3
7
|
*/
|
|
4
|
-
export function getAllMemoryTemplates(): {
|
|
8
|
+
export declare function getAllMemoryTemplates(): {
|
|
5
9
|
'scripts/build-context-pack.mjs': string;
|
|
6
10
|
'scripts/append-handoff.mjs': string;
|
|
11
|
+
'scripts/check-memory-maps.mjs': string;
|
|
7
12
|
'scripts/lib/skill-loader.mjs': string;
|
|
8
13
|
'scripts/memory-vacuum.mjs': string;
|
|
9
14
|
'scripts/memory-watcher.mjs': string;
|
|
@@ -71,13 +76,13 @@ export function getAllMemoryTemplates(): {
|
|
|
71
76
|
* @param {string} baseDir - Diretório base para geração
|
|
72
77
|
* @param {Object} options - Opções (force, noGitkeep)
|
|
73
78
|
*/
|
|
74
|
-
export function generateMemoryStructure(baseDir:
|
|
79
|
+
export declare function generateMemoryStructure(baseDir: any, options?: {}): {
|
|
75
80
|
success: boolean;
|
|
76
81
|
filesWritten: number;
|
|
77
82
|
emptyDirsCreated: number;
|
|
78
83
|
};
|
|
79
|
-
declare
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
}
|
|
84
|
+
declare const _default: {
|
|
85
|
+
generateMemoryStructure: typeof generateMemoryStructure;
|
|
86
|
+
getAllMemoryTemplates: typeof getAllMemoryTemplates;
|
|
87
|
+
};
|
|
83
88
|
export default _default;
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* Extraído de create-memory-nest-kit.js para modularização
|
|
4
4
|
*/
|
|
5
5
|
import path from 'node:path';
|
|
6
|
-
import { writeFileSafe, ensureDir, maybeGitkeep } from
|
|
6
|
+
import { writeFileSafe, ensureDir, maybeGitkeep } from "../utils/file-helpers.js";
|
|
7
7
|
/**
|
|
8
8
|
* Template de arquivos da estrutura de memória
|
|
9
9
|
* Organizado por categorias para facilitar manutenção
|
|
@@ -634,6 +634,50 @@ const template = '# Handoff: ' + from + ' -> ' + to + '\\n\\n'
|
|
|
634
634
|
|
|
635
635
|
fs.writeFileSync(file, template, 'utf8');
|
|
636
636
|
console.log('Handoff criado: ' + file);
|
|
637
|
+
`,
|
|
638
|
+
'scripts/check-memory-maps.mjs': `import fs from 'node:fs';
|
|
639
|
+
import path from 'node:path';
|
|
640
|
+
import { fileURLToPath } from 'node:url';
|
|
641
|
+
|
|
642
|
+
// Gate herdado do Forja (ADR-0030): os mapas de memoria (context.md) nao mentem sobre o codigo.
|
|
643
|
+
// Self-contained, zero dependencia. Rode no CI: node scripts/check-memory-maps.mjs
|
|
644
|
+
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
645
|
+
const domainsDir = path.join(root, 'memory/30-domains');
|
|
646
|
+
const modulesDir = path.join(root, 'backend/src/modules');
|
|
647
|
+
const BT = String.fromCharCode(96);
|
|
648
|
+
const CODE_REF = new RegExp(BT + '([a-z][a-zA-Z0-9/._-]*/[a-zA-Z0-9/._-]*[.]ts)' + BT, 'g');
|
|
649
|
+
|
|
650
|
+
function dirs(p) {
|
|
651
|
+
try { return fs.readdirSync(p).filter((e) => fs.statSync(path.join(p, e)).isDirectory()); }
|
|
652
|
+
catch { return []; }
|
|
653
|
+
}
|
|
654
|
+
function resolves(domain, ref) {
|
|
655
|
+
const bases = [path.join(modulesDir, domain), path.join(root, 'backend'), root];
|
|
656
|
+
return bases.some((b) => fs.existsSync(path.join(b, ref)));
|
|
657
|
+
}
|
|
658
|
+
|
|
659
|
+
let dangling = 0;
|
|
660
|
+
const domains = dirs(domainsDir);
|
|
661
|
+
for (const d of domains) {
|
|
662
|
+
let src;
|
|
663
|
+
try { src = fs.readFileSync(path.join(domainsDir, d, 'context.md'), 'utf8'); }
|
|
664
|
+
catch { continue; }
|
|
665
|
+
const refs = [...new Set([...src.matchAll(CODE_REF)].map((m) => m[1]))];
|
|
666
|
+
const bad = refs.filter((r) => !resolves(d, r));
|
|
667
|
+
if (bad.length) { dangling += bad.length; console.log('x ' + d + ': ' + bad.join(', ') + ' -- o mapa aponta, o arquivo nao existe'); }
|
|
668
|
+
else { console.log('ok ' + d + ' -- ' + refs.length + ' referencia(s)'); }
|
|
669
|
+
}
|
|
670
|
+
const mapped = new Set(domains);
|
|
671
|
+
for (const m of dirs(modulesDir)) {
|
|
672
|
+
if (!mapped.has(m)) console.log('! modulo ' + m + ' sem context.md -- economia de token perdida');
|
|
673
|
+
}
|
|
674
|
+
if (dangling) {
|
|
675
|
+
console.log('');
|
|
676
|
+
console.log('REPROVADO -- ' + dangling + ' referencia(s) pendurada(s). Corrija o context.md ou o path.');
|
|
677
|
+
process.exit(1);
|
|
678
|
+
}
|
|
679
|
+
console.log('');
|
|
680
|
+
console.log('OK -- os mapas de memoria batem com o codigo.');
|
|
637
681
|
`,
|
|
638
682
|
'scripts/lib/skill-loader.mjs': `import fs from 'node:fs';
|
|
639
683
|
import path from 'node:path';
|
|
@@ -1,15 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Nest Generator - Gera estrutura completa NestJS
|
|
3
|
+
* Extraído de create-memory-nest-kit.js para modularização
|
|
4
|
+
*/
|
|
1
5
|
/**
|
|
2
6
|
* Gera estrutura completa do NestJS backend
|
|
3
7
|
* @param {string} baseDir - Diretório base
|
|
4
8
|
* @param {string} projectName - Nome do projeto
|
|
5
9
|
* @param {Object} options - Opções (force, noGitkeep)
|
|
6
10
|
*/
|
|
7
|
-
export function generateNestStructure(baseDir:
|
|
11
|
+
export declare function generateNestStructure(baseDir: any, projectName: any, options?: {}): {
|
|
8
12
|
success: boolean;
|
|
9
13
|
filesWritten: number;
|
|
10
14
|
emptyDirsCreated: number;
|
|
11
15
|
};
|
|
12
|
-
declare
|
|
13
|
-
|
|
14
|
-
}
|
|
16
|
+
declare const _default: {
|
|
17
|
+
generateNestStructure: typeof generateNestStructure;
|
|
18
|
+
};
|
|
15
19
|
export default _default;
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* Extraído de create-memory-nest-kit.js para modularização
|
|
4
4
|
*/
|
|
5
5
|
import path from 'node:path';
|
|
6
|
-
import { writeFileSafe, ensureDir, maybeGitkeep } from
|
|
6
|
+
import { writeFileSafe, ensureDir, maybeGitkeep } from "../utils/file-helpers.js";
|
|
7
7
|
/**
|
|
8
8
|
* Factory de templates NestJS dinâmicos
|
|
9
9
|
* Recebe projectName para interpolar em package.json
|
|
@@ -1,15 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* README Generator - Gera README.md para novo projeto
|
|
3
|
+
*/
|
|
1
4
|
/**
|
|
2
5
|
* Escreve README.md para o projeto
|
|
3
6
|
* @param {string} baseDir - Diretório base
|
|
4
7
|
* @param {string} projectName - Nome do projeto
|
|
5
8
|
* @param {Object} options - Opções (force)
|
|
6
9
|
*/
|
|
7
|
-
export function generateReadme(baseDir:
|
|
10
|
+
export declare function generateReadme(baseDir: any, projectName: any, options?: {}): {
|
|
8
11
|
success: boolean;
|
|
9
12
|
path: string;
|
|
10
13
|
size: number;
|
|
11
14
|
};
|
|
12
|
-
declare
|
|
13
|
-
|
|
14
|
-
}
|
|
15
|
+
declare const _default: {
|
|
16
|
+
generateReadme: typeof generateReadme;
|
|
17
|
+
};
|
|
15
18
|
export default _default;
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* README Generator - Gera README.md para novo projeto
|
|
3
3
|
*/
|
|
4
4
|
import path from 'node:path';
|
|
5
|
-
import { writeFileSafe } from
|
|
5
|
+
import { writeFileSafe } from "../utils/file-helpers.js";
|
|
6
6
|
/**
|
|
7
7
|
* Factory para README dinâmico
|
|
8
8
|
*/
|
|
@@ -146,6 +146,7 @@ Mostra:
|
|
|
146
146
|
| \`append-handoff.mjs\` | Cria novo arquivo de handoff |
|
|
147
147
|
| \`memory-vacuum.mjs\` | Arquiva logs > 30 dias |
|
|
148
148
|
| \`memory-watcher.mjs\` | Auto-sync de markdown → SQLite |
|
|
149
|
+
| \`check-memory-maps.mjs\` | Gate: os mapas (context.md) não citam código morto. Rode no CI |
|
|
149
150
|
|
|
150
151
|
## 📚 Documentação Importante
|
|
151
152
|
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/memory-audit.ts — os mapas de memória não podem mentir sobre o código (SPEC-017, ADR-0009).
|
|
3
|
+
*
|
|
4
|
+
* A economia de token do Forja é o `context.md` como mapa (`token:economy` mede −61%). Mas um mapa
|
|
5
|
+
* que aponta "a regra mora em `domain/order.entity.ts`" **depois** que o arquivo foi renomeado é
|
|
6
|
+
* *pior* que mapa nenhum: engana com confiança, e um agente vai ler o lugar errado — pagando o custo
|
|
7
|
+
* e chegando à conclusão errada.
|
|
8
|
+
*
|
|
9
|
+
* Este módulo é o `adr-refs` dos mapas: extrai os paths de código que cada `context.md` cita e
|
|
10
|
+
* confere que eles existem. Referência pendurada num mapa é a economia de token se voltando contra si.
|
|
11
|
+
*/
|
|
12
|
+
import fs from 'node:fs';
|
|
13
|
+
export interface AuditEnv {
|
|
14
|
+
fs: typeof fs;
|
|
15
|
+
}
|
|
16
|
+
export interface DomainAudit {
|
|
17
|
+
domain: string;
|
|
18
|
+
mapPath: string;
|
|
19
|
+
refs: number;
|
|
20
|
+
dangling: string[];
|
|
21
|
+
}
|
|
22
|
+
/** Módulos de código de um projeto: os diretórios sob `backend/src/modules/`. */
|
|
23
|
+
export declare function modulesOf(projectRoot: string, env?: AuditEnv): string[];
|
|
24
|
+
/**
|
|
25
|
+
* A direção reversa da coerência: módulo de código **sem** `context.md`. Não é uma mentira (o mapa
|
|
26
|
+
* não existe para mentir), mas é a economia de token perdida em silêncio — um domínio que cresceu e
|
|
27
|
+
* ninguém mapeou. `warn`, não `fail`.
|
|
28
|
+
*/
|
|
29
|
+
export declare function modulesWithoutMap(projectRoot: string, env?: AuditEnv): string[];
|
|
30
|
+
/** Audita os mapas de todos os domínios de um projeto. */
|
|
31
|
+
export declare function auditMemoryMaps(projectRoot: string, env?: AuditEnv): DomainAudit[];
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/memory-audit.ts — os mapas de memória não podem mentir sobre o código (SPEC-017, ADR-0009).
|
|
3
|
+
*
|
|
4
|
+
* A economia de token do Forja é o `context.md` como mapa (`token:economy` mede −61%). Mas um mapa
|
|
5
|
+
* que aponta "a regra mora em `domain/order.entity.ts`" **depois** que o arquivo foi renomeado é
|
|
6
|
+
* *pior* que mapa nenhum: engana com confiança, e um agente vai ler o lugar errado — pagando o custo
|
|
7
|
+
* e chegando à conclusão errada.
|
|
8
|
+
*
|
|
9
|
+
* Este módulo é o `adr-refs` dos mapas: extrai os paths de código que cada `context.md` cita e
|
|
10
|
+
* confere que eles existem. Referência pendurada num mapa é a economia de token se voltando contra si.
|
|
11
|
+
*/
|
|
12
|
+
import fs from 'node:fs';
|
|
13
|
+
import path from 'node:path';
|
|
14
|
+
import { domainsOf } from "./code-context.js";
|
|
15
|
+
const defaultEnv = { fs };
|
|
16
|
+
/** Paths de código citados num mapa: tokens entre crases que terminam em `.ts` e têm ao menos um `/`. */
|
|
17
|
+
const CODE_REF_RE = /`([a-z][a-zA-Z0-9/._-]*\/[a-zA-Z0-9/._-]*\.ts)`/g;
|
|
18
|
+
/**
|
|
19
|
+
* Resolve um path citado num mapa contra as bases plausíveis: relativo ao módulo
|
|
20
|
+
* (`backend/src/modules/<domain>/`), ao `backend/`, e à raiz do projeto. Basta existir numa.
|
|
21
|
+
*/
|
|
22
|
+
function refResolves(projectRoot, domain, ref, env) {
|
|
23
|
+
const bases = [
|
|
24
|
+
path.join(projectRoot, 'backend', 'src', 'modules', domain),
|
|
25
|
+
path.join(projectRoot, 'backend'),
|
|
26
|
+
projectRoot,
|
|
27
|
+
];
|
|
28
|
+
return bases.some((base) => env.fs.existsSync(path.join(base, ref)));
|
|
29
|
+
}
|
|
30
|
+
/** Módulos de código de um projeto: os diretórios sob `backend/src/modules/`. */
|
|
31
|
+
export function modulesOf(projectRoot, env = defaultEnv) {
|
|
32
|
+
const dir = path.join(projectRoot, 'backend', 'src', 'modules');
|
|
33
|
+
try {
|
|
34
|
+
return env.fs
|
|
35
|
+
.readdirSync(dir)
|
|
36
|
+
.filter((e) => {
|
|
37
|
+
try {
|
|
38
|
+
return env.fs.statSync(path.join(dir, e)).isDirectory();
|
|
39
|
+
}
|
|
40
|
+
catch {
|
|
41
|
+
return false;
|
|
42
|
+
}
|
|
43
|
+
})
|
|
44
|
+
.sort();
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
return [];
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* A direção reversa da coerência: módulo de código **sem** `context.md`. Não é uma mentira (o mapa
|
|
52
|
+
* não existe para mentir), mas é a economia de token perdida em silêncio — um domínio que cresceu e
|
|
53
|
+
* ninguém mapeou. `warn`, não `fail`.
|
|
54
|
+
*/
|
|
55
|
+
export function modulesWithoutMap(projectRoot, env = defaultEnv) {
|
|
56
|
+
const mapped = new Set(domainsOf(projectRoot, env));
|
|
57
|
+
return modulesOf(projectRoot, env).filter((m) => !mapped.has(m));
|
|
58
|
+
}
|
|
59
|
+
/** Audita os mapas de todos os domínios de um projeto. */
|
|
60
|
+
export function auditMemoryMaps(projectRoot, env = defaultEnv) {
|
|
61
|
+
const out = [];
|
|
62
|
+
for (const domain of domainsOf(projectRoot, env)) {
|
|
63
|
+
const mapPath = path.join(projectRoot, 'memory', '30-domains', domain, 'context.md');
|
|
64
|
+
let src;
|
|
65
|
+
try {
|
|
66
|
+
src = env.fs.readFileSync(mapPath, 'utf8');
|
|
67
|
+
}
|
|
68
|
+
catch {
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
const refs = [...new Set([...src.matchAll(CODE_REF_RE)].map((m) => m[1]))];
|
|
72
|
+
const dangling = refs.filter((ref) => !refResolves(projectRoot, domain, ref, env));
|
|
73
|
+
out.push({
|
|
74
|
+
domain,
|
|
75
|
+
mapPath: path.relative(projectRoot, mapPath),
|
|
76
|
+
refs: refs.length,
|
|
77
|
+
dangling,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
return out;
|
|
81
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/project-upgrade.ts — a metade que falta do scaffolder (SPEC-018).
|
|
3
|
+
*
|
|
4
|
+
* O framework GERA projetos, mas nunca soube ATUALIZAR um projeto já gerado quando ele evolui: uma
|
|
5
|
+
* memória nova (`70-summaries/`), um agent novo, um config multi-IA novo. Quem gerou na v1.2 ficava
|
|
6
|
+
* preso na v1.2. Aqui a regra é simples e segura: **aditivo, nunca sobrescreve.** O upgrade só traz
|
|
7
|
+
* peças de scaffold que FALTAM no projeto; um arquivo que já existe pode ter edição do usuário, e o
|
|
8
|
+
* código do usuário é intocável.
|
|
9
|
+
*/
|
|
10
|
+
import fs from 'node:fs';
|
|
11
|
+
export interface UpgradeEnv {
|
|
12
|
+
fs: typeof fs;
|
|
13
|
+
}
|
|
14
|
+
/** Todos os arquivos (rel) sob um root, menos os SKIP_DIRS. */
|
|
15
|
+
export declare function listFiles(root: string, env?: UpgradeEnv): string[];
|
|
16
|
+
export interface UpgradePlan {
|
|
17
|
+
/** Arquivos que o scaffold atual traz e o projeto não tem — as peças novas, seguras de adicionar. */
|
|
18
|
+
newFiles: string[];
|
|
19
|
+
/** Presentes nos dois — não tocados (podem ter edição do usuário). */
|
|
20
|
+
existing: number;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Planeja o upgrade: o que o scaffold fresco tem que o projeto-alvo não tem. **Só adições** — nunca
|
|
24
|
+
* lista sobrescritas, porque um arquivo existente é território do usuário.
|
|
25
|
+
*/
|
|
26
|
+
export declare function planUpgrade(freshRoot: string, targetRoot: string, env?: UpgradeEnv): UpgradePlan;
|
|
27
|
+
/** Aplica o plano: copia as peças novas para o alvo, criando diretórios. Nunca sobrescreve. */
|
|
28
|
+
export declare function applyUpgrade(freshRoot: string, targetRoot: string, plan: UpgradePlan, env?: UpgradeEnv): string[];
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/project-upgrade.ts — a metade que falta do scaffolder (SPEC-018).
|
|
3
|
+
*
|
|
4
|
+
* O framework GERA projetos, mas nunca soube ATUALIZAR um projeto já gerado quando ele evolui: uma
|
|
5
|
+
* memória nova (`70-summaries/`), um agent novo, um config multi-IA novo. Quem gerou na v1.2 ficava
|
|
6
|
+
* preso na v1.2. Aqui a regra é simples e segura: **aditivo, nunca sobrescreve.** O upgrade só traz
|
|
7
|
+
* peças de scaffold que FALTAM no projeto; um arquivo que já existe pode ter edição do usuário, e o
|
|
8
|
+
* código do usuário é intocável.
|
|
9
|
+
*/
|
|
10
|
+
import fs from 'node:fs';
|
|
11
|
+
import path from 'node:path';
|
|
12
|
+
const defaultEnv = { fs };
|
|
13
|
+
/** Dirs que são runtime/build/deps — não são scaffold a copiar. */
|
|
14
|
+
const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.memory', '.context']);
|
|
15
|
+
/** Todos os arquivos (rel) sob um root, menos os SKIP_DIRS. */
|
|
16
|
+
export function listFiles(root, env = defaultEnv) {
|
|
17
|
+
const out = [];
|
|
18
|
+
const walk = (dir) => {
|
|
19
|
+
let entries;
|
|
20
|
+
try {
|
|
21
|
+
entries = env.fs.readdirSync(dir);
|
|
22
|
+
}
|
|
23
|
+
catch {
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
for (const e of entries) {
|
|
27
|
+
if (SKIP_DIRS.has(e))
|
|
28
|
+
continue;
|
|
29
|
+
const p = path.join(dir, e);
|
|
30
|
+
let st;
|
|
31
|
+
try {
|
|
32
|
+
st = env.fs.statSync(p);
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
if (st.isDirectory())
|
|
38
|
+
walk(p);
|
|
39
|
+
else
|
|
40
|
+
out.push(path.relative(root, p));
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
walk(root);
|
|
44
|
+
return out.sort();
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Planeja o upgrade: o que o scaffold fresco tem que o projeto-alvo não tem. **Só adições** — nunca
|
|
48
|
+
* lista sobrescritas, porque um arquivo existente é território do usuário.
|
|
49
|
+
*/
|
|
50
|
+
export function planUpgrade(freshRoot, targetRoot, env = defaultEnv) {
|
|
51
|
+
const fresh = listFiles(freshRoot, env);
|
|
52
|
+
const newFiles = [];
|
|
53
|
+
let existing = 0;
|
|
54
|
+
for (const rel of fresh) {
|
|
55
|
+
if (env.fs.existsSync(path.join(targetRoot, rel)))
|
|
56
|
+
existing += 1;
|
|
57
|
+
else
|
|
58
|
+
newFiles.push(rel);
|
|
59
|
+
}
|
|
60
|
+
return { newFiles, existing };
|
|
61
|
+
}
|
|
62
|
+
/** Aplica o plano: copia as peças novas para o alvo, criando diretórios. Nunca sobrescreve. */
|
|
63
|
+
export function applyUpgrade(freshRoot, targetRoot, plan, env = defaultEnv) {
|
|
64
|
+
const applied = [];
|
|
65
|
+
for (const rel of plan.newFiles) {
|
|
66
|
+
const dst = path.join(targetRoot, rel);
|
|
67
|
+
if (env.fs.existsSync(dst))
|
|
68
|
+
continue; // paranoia: nunca sobrescreve
|
|
69
|
+
env.fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
70
|
+
env.fs.copyFileSync(path.join(freshRoot, rel), dst);
|
|
71
|
+
applied.push(rel);
|
|
72
|
+
}
|
|
73
|
+
return applied;
|
|
74
|
+
}
|
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Funções utilitárias compartilhadas para geração de arquivos
|
|
3
3
|
*/
|
|
4
|
-
export function ensureDir(dirPath: any): void;
|
|
5
|
-
export function writeFileSafe(filePath: any, content: any, options?: {
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
export function
|
|
9
|
-
|
|
4
|
+
export declare function ensureDir(dirPath: any): void;
|
|
5
|
+
export declare function writeFileSafe(filePath: any, content: any, options?: {
|
|
6
|
+
force?: boolean;
|
|
7
|
+
}): void;
|
|
8
|
+
export declare function maybeGitkeep(dirPath: any, options?: {
|
|
9
|
+
noGitkeep?: boolean;
|
|
10
|
+
}): void;
|
|
11
|
+
export declare function log(message: any): void;
|
|
12
|
+
export declare function logError(message: any): void;
|
|
13
|
+
export declare function logSuccess(message: any): void;
|
|
@@ -1,48 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structure Validator - Valida integridade da estrutura gerada
|
|
3
|
+
* Garante que todos os diretórios e arquivos críticos foram criados
|
|
4
|
+
*/
|
|
1
5
|
/**
|
|
2
6
|
* Valida estrutura de memória
|
|
3
7
|
* @param {string} baseDir - Diretório base
|
|
4
8
|
* @returns {Object} Resultado da validação
|
|
5
9
|
*/
|
|
6
|
-
export function validateMemoryStructure(baseDir:
|
|
10
|
+
export declare function validateMemoryStructure(baseDir: any): {
|
|
11
|
+
isValid: boolean;
|
|
12
|
+
errors: string[];
|
|
13
|
+
warnings: string[];
|
|
14
|
+
checklist: {
|
|
15
|
+
memoryStructure: number;
|
|
16
|
+
memoryFiles: number;
|
|
17
|
+
};
|
|
18
|
+
};
|
|
7
19
|
/**
|
|
8
20
|
* Valida estrutura NestJS
|
|
9
21
|
* @param {string} baseDir - Diretório base
|
|
10
22
|
* @returns {Object} Resultado da validação
|
|
11
23
|
*/
|
|
12
|
-
export function validateNestStructure(baseDir:
|
|
24
|
+
export declare function validateNestStructure(baseDir: any): {
|
|
25
|
+
isValid: boolean;
|
|
26
|
+
errors: string[];
|
|
27
|
+
warnings: string[];
|
|
28
|
+
checklist: {
|
|
29
|
+
nestDirectories: number;
|
|
30
|
+
nestFiles: number;
|
|
31
|
+
};
|
|
32
|
+
};
|
|
13
33
|
/**
|
|
14
34
|
* Valida estrutura completa do projeto
|
|
15
35
|
* @param {string} baseDir - Diretório base
|
|
16
36
|
* @param {Object} options - Opções { includeNest: boolean }
|
|
17
37
|
* @returns {Object} Resultado completo
|
|
18
38
|
*/
|
|
19
|
-
export function validateProjectStructure(baseDir:
|
|
39
|
+
export declare function validateProjectStructure(baseDir: any, options?: {
|
|
40
|
+
includeNest?: boolean;
|
|
41
|
+
}): {
|
|
42
|
+
isValid: boolean;
|
|
43
|
+
errors: any[];
|
|
44
|
+
warnings: any[];
|
|
45
|
+
results: {
|
|
46
|
+
memory: any;
|
|
47
|
+
nest?: any;
|
|
48
|
+
};
|
|
49
|
+
summary: {
|
|
50
|
+
totalErrors: number;
|
|
51
|
+
hasNest: boolean;
|
|
52
|
+
timestamp: string;
|
|
53
|
+
};
|
|
54
|
+
};
|
|
20
55
|
/**
|
|
21
56
|
* Imprime relatório de validação de forma amigável
|
|
22
57
|
* @param {Object} report - Resultado de validateProjectStructure
|
|
23
58
|
*/
|
|
24
|
-
export function printValidationReport(report: any): void;
|
|
25
|
-
declare
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
}
|
|
59
|
+
export declare function printValidationReport(report: any): void;
|
|
60
|
+
declare const _default: {
|
|
61
|
+
validateProjectStructure: typeof validateProjectStructure;
|
|
62
|
+
validateMemoryStructure: typeof validateMemoryStructure;
|
|
63
|
+
validateNestStructure: typeof validateNestStructure;
|
|
64
|
+
printValidationReport: typeof printValidationReport;
|
|
65
|
+
CRITICAL_FILES: string[];
|
|
66
|
+
CRITICAL_DIRS: string[];
|
|
67
|
+
NEST_CRITICAL_FILES: string[];
|
|
68
|
+
NEST_CRITICAL_DIRS: string[];
|
|
69
|
+
};
|
|
35
70
|
export default _default;
|
|
36
|
-
/**
|
|
37
|
-
* Lista dos arquivos críticos que devem existir
|
|
38
|
-
*/
|
|
39
|
-
declare const CRITICAL_FILES: string[];
|
|
40
|
-
/**
|
|
41
|
-
* Lista de diretórios críticos
|
|
42
|
-
*/
|
|
43
|
-
declare const CRITICAL_DIRS: string[];
|
|
44
|
-
/**
|
|
45
|
-
* Validações específicas do NestJS backend
|
|
46
|
-
*/
|
|
47
|
-
declare const NEST_CRITICAL_FILES: string[];
|
|
48
|
-
declare const NEST_CRITICAL_DIRS: string[];
|