forjajs 1.3.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.en.md +1 -0
  3. package/README.md +10 -4
  4. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  5. package/dist/bin/create-memory-nest-kit.d.ts +11 -0
  6. package/dist/bin/create-memory-nest-kit.js +5 -5
  7. package/dist/bin/forja.js +1 -1
  8. package/dist/bin/init-project.d.ts +12 -0
  9. package/dist/bin/init-project.js +2 -2
  10. package/dist/lib/code-context.d.ts +41 -0
  11. package/dist/lib/code-context.js +108 -0
  12. package/dist/lib/context-builder.d.ts +15 -5
  13. package/dist/lib/context-builder.js +5 -0
  14. package/dist/lib/core/checks.d.ts +3 -3
  15. package/dist/lib/core/doc-graph.d.ts +13 -0
  16. package/dist/lib/core/doc-graph.js +48 -1
  17. package/dist/lib/core/health.d.ts +3 -32
  18. package/dist/lib/core/health.js +29 -15
  19. package/dist/lib/core/project-smoke.d.ts +46 -0
  20. package/dist/lib/core/project-smoke.js +248 -0
  21. package/dist/lib/core/registry.d.ts +25 -0
  22. package/dist/lib/core/registry.js +37 -12
  23. package/dist/lib/core/release.d.ts +27 -14
  24. package/dist/lib/core/release.js +0 -8
  25. package/dist/lib/generators/memory-generator.d.ts +11 -6
  26. package/dist/lib/generators/memory-generator.js +45 -1
  27. package/dist/lib/generators/nest-generator.d.ts +8 -4
  28. package/dist/lib/generators/nest-generator.js +1 -1
  29. package/dist/lib/generators/readme-generator.d.ts +7 -4
  30. package/dist/lib/generators/readme-generator.js +2 -1
  31. package/dist/lib/governance-report.d.ts +1 -1
  32. package/dist/lib/memory-audit.d.ts +31 -0
  33. package/dist/lib/memory-audit.js +81 -0
  34. package/dist/lib/project-upgrade.d.ts +28 -0
  35. package/dist/lib/project-upgrade.js +74 -0
  36. package/dist/lib/utils/file-helpers.d.ts +10 -6
  37. package/dist/lib/validators/structure-validator.d.ts +49 -27
  38. package/dist/scripts/code-context.d.ts +12 -0
  39. package/dist/scripts/code-context.js +73 -0
  40. package/dist/scripts/dev.d.ts +2 -2
  41. package/dist/scripts/dev.js +1 -1
  42. package/dist/scripts/memory-audit.d.ts +11 -0
  43. package/dist/scripts/memory-audit.js +49 -0
  44. package/dist/scripts/project-smoke.d.ts +14 -0
  45. package/dist/scripts/project-smoke.js +44 -0
  46. package/dist/scripts/project-upgrade.d.ts +11 -0
  47. package/dist/scripts/project-upgrade.js +61 -0
  48. package/dist/scripts/query-universal-memory.js +1 -1
  49. package/dist/scripts/sprint-manager.js +1 -1
  50. package/dist/scripts/token-benchmark.js +1 -1
  51. package/dist/scripts/token-economy.d.ts +20 -0
  52. package/dist/scripts/token-economy.js +140 -0
  53. package/memory/90-decisions/0025-coerencia-da-documentacao.md +4 -0
  54. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  55. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  56. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  57. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  58. package/package.json +1 -1
  59. package/specs/code-context/spec.md +56 -0
  60. package/specs/memory-audit/spec.md +54 -0
  61. package/specs/project-smoke/spec.md +96 -0
  62. package/specs/project-upgrade/spec.md +58 -0
  63. package/specs/ts-migration/plan.md +9 -8
  64. package/specs/ts-migration/spec.md +1 -1
  65. package/dist/lib/templates/harness/code-intel.d.mts +0 -2
  66. package/dist/lib/templates/harness/code-intel.mjs +0 -126
@@ -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;
@@ -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: string, options?: any): {
79
+ export declare function generateMemoryStructure(baseDir: any, options?: {}): {
75
80
  success: boolean;
76
81
  filesWritten: number;
77
82
  emptyDirsCreated: number;
78
83
  };
79
- declare namespace _default {
80
- export { generateMemoryStructure };
81
- export { getAllMemoryTemplates };
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 '../utils/file-helpers.js';
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: string, projectName: string, options?: any): {
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 namespace _default {
13
- export { generateNestStructure };
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 '../utils/file-helpers.js';
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: string, projectName: string, options?: any): {
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 namespace _default {
13
- export { generateReadme };
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 '../utils/file-helpers.js';
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
 
@@ -28,7 +28,7 @@ export declare function collect(env?: {
28
28
  state: string;
29
29
  checks: {
30
30
  id: string;
31
- severity: string;
31
+ severity: import("./core/checks.ts").Severity;
32
32
  }[];
33
33
  }[];
34
34
  specs: {
@@ -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?: {}): void;
6
- export function maybeGitkeep(dirPath: any, options?: {}): void;
7
- export function log(message: any): void;
8
- export function logError(message: any): void;
9
- export function logSuccess(message: any): void;
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: string): any;
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: string): any;
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: string, options?: any): any;
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 namespace _default {
26
- export { validateProjectStructure };
27
- export { validateMemoryStructure };
28
- export { validateNestStructure };
29
- export { printValidationReport };
30
- export { CRITICAL_FILES };
31
- export { CRITICAL_DIRS };
32
- export { NEST_CRITICAL_FILES };
33
- export { NEST_CRITICAL_DIRS };
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[];