forjajs 1.3.2 → 1.6.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/AGENTS.md +5 -0
- package/CHANGELOG.md +74 -0
- package/README.en.md +1 -0
- package/README.md +11 -4
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
- package/dist/lib/agent-topology.d.ts +38 -0
- package/dist/lib/agent-topology.js +65 -0
- package/dist/lib/code-context.d.ts +41 -0
- package/dist/lib/code-context.js +108 -0
- package/dist/lib/core/doc-graph.d.ts +13 -0
- package/dist/lib/core/doc-graph.js +47 -0
- package/dist/lib/core/gates.d.ts +36 -0
- package/dist/lib/core/gates.js +35 -0
- package/dist/lib/core/health.js +64 -1
- 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 +30 -0
- package/dist/lib/core/registry.js +30 -0
- package/dist/lib/core/release.d.ts +30 -0
- package/dist/lib/generators/memory-generator.d.ts +1 -0
- package/dist/lib/generators/memory-generator.js +44 -0
- package/dist/lib/generators/readme-generator.js +1 -0
- 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/scripts/agent-router.js +1 -1
- package/dist/scripts/code-context.d.ts +12 -0
- package/dist/scripts/code-context.js +73 -0
- package/dist/scripts/gates.d.ts +10 -0
- package/dist/scripts/gates.js +44 -0
- 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/token-economy.d.ts +20 -0
- package/dist/scripts/token-economy.js +140 -0
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +10 -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/gates/spec.md +63 -0
- package/specs/memory-audit/spec.md +54 -0
- package/specs/orchestration-coherent/spec.md +95 -0
- package/specs/project-smoke/spec.md +96 -0
- package/specs/project-upgrade/spec.md +58 -0
package/dist/lib/core/health.js
CHANGED
|
@@ -38,7 +38,8 @@ import { fileURLToPath } from 'node:url';
|
|
|
38
38
|
import { getWorkspaceDbPath, getWorkspaceInfo } from "../workspace.js";
|
|
39
39
|
import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from "./checks.js";
|
|
40
40
|
import { COMMANDS } from "./registry.js";
|
|
41
|
-
import { scanCommands, scanLinks, projectCommands } from "./doc-graph.js";
|
|
41
|
+
import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers } from "./doc-graph.js";
|
|
42
|
+
import { topologyIssues } from "../agent-topology.js";
|
|
42
43
|
/** @typedef {import('./checks.ts').Status} Status */
|
|
43
44
|
// O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
|
|
44
45
|
// aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
|
|
@@ -495,6 +496,66 @@ const docsLinks = {
|
|
|
495
496
|
return { status: 'ok', detail: 'todo link relativo resolve', fix: null };
|
|
496
497
|
},
|
|
497
498
|
};
|
|
499
|
+
/**
|
|
500
|
+
* Referência a decisão que não existe é trilha que apodrece. Uma spec ou doc cita `ADR-0026`, o ADR
|
|
501
|
+
* nunca foi escrito (ou foi renumerado), e o paper trail mente em silêncio. `warn`, não `critical`:
|
|
502
|
+
* confunde o registro, não impede o framework de trabalhar — mesma família de `docs-links`.
|
|
503
|
+
*/
|
|
504
|
+
const adrRefs = {
|
|
505
|
+
id: 'adr-refs',
|
|
506
|
+
title: 'toda citação ADR-NNNN aponta para um ADR existente',
|
|
507
|
+
severity: 'warn',
|
|
508
|
+
scope: 'repo',
|
|
509
|
+
probe(env) {
|
|
510
|
+
if (!isFrameworkRepo(env)) {
|
|
511
|
+
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
512
|
+
}
|
|
513
|
+
const existing = adrNumbers(env);
|
|
514
|
+
const dangling = scanAdrRefs(env).filter((r) => !existing.has(r.num));
|
|
515
|
+
if (dangling.length) {
|
|
516
|
+
const amostra = dangling.slice(0, 5).map((d) => `${d.ref} (${d.file}:${d.line})`).join(', ');
|
|
517
|
+
return {
|
|
518
|
+
status: 'warn',
|
|
519
|
+
detail: `${dangling.length} citação(ões) de ADR inexistente: ${amostra}`,
|
|
520
|
+
fix: 'escreva o ADR referenciado ou corrija o número no arquivo:linha indicado',
|
|
521
|
+
};
|
|
522
|
+
}
|
|
523
|
+
return { status: 'ok', detail: `toda referência a ADR resolve (${existing.size} ADRs)`, fix: null };
|
|
524
|
+
},
|
|
525
|
+
};
|
|
526
|
+
/**
|
|
527
|
+
* A topologia de orquestração é descrita em três lugares (router, `.claude/agents`, `AGENTS.md`) e
|
|
528
|
+
* pode divergir em silêncio (SPEC-019): um sub-agent que o router não roteia, um papel roteável sem
|
|
529
|
+
* executor, um agente não documentado. É a coerência da orquestração — o namesake do framework —
|
|
530
|
+
* feita invariante. `warn`: confunde a topologia, não trava o núcleo. Mesma família de `adr-refs`.
|
|
531
|
+
*/
|
|
532
|
+
const agentTopology = {
|
|
533
|
+
id: 'agent-topology',
|
|
534
|
+
title: 'a topologia de agentes concorda entre router, .claude/agents e AGENTS.md',
|
|
535
|
+
severity: 'warn',
|
|
536
|
+
scope: 'repo',
|
|
537
|
+
probe(env) {
|
|
538
|
+
if (!isFrameworkRepo(env)) {
|
|
539
|
+
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
540
|
+
}
|
|
541
|
+
const { unrouted, missingExecutor, undocumented } = topologyIssues({ fs: env.fs, root: env.root });
|
|
542
|
+
const problemas = [];
|
|
543
|
+
if (unrouted.length)
|
|
544
|
+
problemas.push(`sem rota no router: ${unrouted.join(', ')}`);
|
|
545
|
+
if (missingExecutor.length)
|
|
546
|
+
problemas.push(`roteável sem .claude/agent: ${missingExecutor.join(', ')}`);
|
|
547
|
+
if (undocumented.length)
|
|
548
|
+
problemas.push(`não documentado no AGENTS.md: ${undocumented.join(', ')}`);
|
|
549
|
+
if (problemas.length) {
|
|
550
|
+
return {
|
|
551
|
+
status: 'warn',
|
|
552
|
+
detail: `topologia incoerente — ${problemas.join('; ')}`,
|
|
553
|
+
fix: 'alinhe VALID_AGENTS (agent-router.ts), .claude/agents/ e AGENTS.md',
|
|
554
|
+
};
|
|
555
|
+
}
|
|
556
|
+
return { status: 'ok', detail: 'router, .claude/agents e AGENTS.md concordam', fix: null };
|
|
557
|
+
},
|
|
558
|
+
};
|
|
498
559
|
/** @type {Check[]} */
|
|
499
560
|
export const CHECKS = [
|
|
500
561
|
nativeAbi,
|
|
@@ -507,6 +568,8 @@ export const CHECKS = [
|
|
|
507
568
|
docsCommands,
|
|
508
569
|
commandsDocumented,
|
|
509
570
|
docsLinks,
|
|
571
|
+
adrRefs,
|
|
572
|
+
agentTopology,
|
|
510
573
|
];
|
|
511
574
|
/**
|
|
512
575
|
* Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/project-smoke.ts — o gate do projeto gerado.
|
|
3
|
+
*
|
|
4
|
+
* Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
|
|
5
|
+
* O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
|
|
6
|
+
* — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
|
|
7
|
+
*
|
|
8
|
+
* O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
|
|
9
|
+
* `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
|
|
10
|
+
* princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
|
|
11
|
+
*
|
|
12
|
+
* O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
|
|
13
|
+
*/
|
|
14
|
+
import fs from 'node:fs';
|
|
15
|
+
import { worstStatus } from './checks.ts';
|
|
16
|
+
import type { Check } from './checks.ts';
|
|
17
|
+
export { worstStatus };
|
|
18
|
+
interface SmokeEnv {
|
|
19
|
+
root: string;
|
|
20
|
+
fs: typeof fs;
|
|
21
|
+
projectDir?: string;
|
|
22
|
+
full: boolean;
|
|
23
|
+
spawn: (cmd: string, args: string[], opts?: any) => {
|
|
24
|
+
stdout: string;
|
|
25
|
+
stderr: string;
|
|
26
|
+
code: number;
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
|
|
31
|
+
* temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
|
|
32
|
+
*/
|
|
33
|
+
export declare function withGeneratedProject<T>(fn: (ctx: {
|
|
34
|
+
projectDir: string;
|
|
35
|
+
}) => Promise<T> | T, { root, spawn }: {
|
|
36
|
+
root?: string;
|
|
37
|
+
spawn: SmokeEnv['spawn'];
|
|
38
|
+
}): Promise<T>;
|
|
39
|
+
/** @type {Check[]} */
|
|
40
|
+
export declare const SMOKE_CHECKS: Check[];
|
|
41
|
+
export declare function defaultEnv(overrides?: Partial<SmokeEnv>): SmokeEnv;
|
|
42
|
+
/** Gera um projeto isolado, roda os checks, limpa. */
|
|
43
|
+
export declare function runProjectSmoke({ full, env: overrides }?: {
|
|
44
|
+
full?: boolean;
|
|
45
|
+
env?: Partial<SmokeEnv>;
|
|
46
|
+
}): Promise<import("./checks.ts").Result[]>;
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/project-smoke.ts — o gate do projeto gerado.
|
|
3
|
+
*
|
|
4
|
+
* Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
|
|
5
|
+
* O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
|
|
6
|
+
* — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
|
|
7
|
+
*
|
|
8
|
+
* O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
|
|
9
|
+
* `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
|
|
10
|
+
* princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
|
|
11
|
+
*
|
|
12
|
+
* O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
|
|
13
|
+
*/
|
|
14
|
+
import { execFileSync } from 'node:child_process';
|
|
15
|
+
import fs from 'node:fs';
|
|
16
|
+
import os from 'node:os';
|
|
17
|
+
import path from 'node:path';
|
|
18
|
+
import { fileURLToPath } from 'node:url';
|
|
19
|
+
import { runChecks as run, worstStatus } from "./checks.js";
|
|
20
|
+
// @ts-ignore — validador legado sem tipos exportados; usado só pela forma { isValid, errors }.
|
|
21
|
+
import { validateProjectStructure } from "../validators/structure-validator.js";
|
|
22
|
+
export { worstStatus };
|
|
23
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
24
|
+
const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
|
|
25
|
+
/** Placeholders do gerador: identificadores MAIÚSCULOS entre chaves duplas (`{{FEATURE}}`). */
|
|
26
|
+
const PLACEHOLDER_RE = /\{\{[A-Z][A-Z0-9_]*\}\}/;
|
|
27
|
+
/**
|
|
28
|
+
* Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
|
|
29
|
+
* temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
|
|
30
|
+
*/
|
|
31
|
+
export async function withGeneratedProject(fn, { root = repoRoot, spawn }) {
|
|
32
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-smoke-'));
|
|
33
|
+
const projectDir = path.join(dir, 'smoke-proj');
|
|
34
|
+
try {
|
|
35
|
+
const gen = path.join(root, 'bin', 'create-memory-nest-kit.ts');
|
|
36
|
+
const res = spawn(process.execPath, [gen, projectDir, '--force'], { cwd: dir });
|
|
37
|
+
if (res.code !== 0) {
|
|
38
|
+
throw new Error(`o gerador saiu com código ${res.code}:\n${(res.stderr || res.stdout).slice(0, 800)}`);
|
|
39
|
+
}
|
|
40
|
+
return await fn({ projectDir });
|
|
41
|
+
}
|
|
42
|
+
finally {
|
|
43
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
// ---------------------------------------------------------------------------
|
|
47
|
+
// Walk — arquivos de texto do projeto, menos node_modules
|
|
48
|
+
// ---------------------------------------------------------------------------
|
|
49
|
+
function walkFiles(env, dir, out) {
|
|
50
|
+
let entries;
|
|
51
|
+
try {
|
|
52
|
+
entries = env.fs.readdirSync(dir);
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return out;
|
|
56
|
+
}
|
|
57
|
+
for (const entry of entries) {
|
|
58
|
+
if (entry === 'node_modules' || entry === '.git')
|
|
59
|
+
continue;
|
|
60
|
+
const p = path.join(dir, entry);
|
|
61
|
+
let st;
|
|
62
|
+
try {
|
|
63
|
+
st = env.fs.statSync(p);
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
continue;
|
|
67
|
+
}
|
|
68
|
+
if (st.isDirectory())
|
|
69
|
+
walkFiles(env, p, out);
|
|
70
|
+
else
|
|
71
|
+
out.push(p);
|
|
72
|
+
}
|
|
73
|
+
return out;
|
|
74
|
+
}
|
|
75
|
+
/** Lê como texto; devolve null para binário/ilegível (não é competência deste gate). */
|
|
76
|
+
function readText(env, file) {
|
|
77
|
+
try {
|
|
78
|
+
const buf = env.fs.readFileSync(file);
|
|
79
|
+
if (buf.includes(0))
|
|
80
|
+
return null; // binário
|
|
81
|
+
return buf.toString('utf8');
|
|
82
|
+
}
|
|
83
|
+
catch {
|
|
84
|
+
return null;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
// ---------------------------------------------------------------------------
|
|
88
|
+
// Checks
|
|
89
|
+
// ---------------------------------------------------------------------------
|
|
90
|
+
/** Se o projeto não nasceu, todo o resto é irrelevante — daí os outros dependerem deste. */
|
|
91
|
+
const generated = {
|
|
92
|
+
id: 'generated',
|
|
93
|
+
title: 'o gerador produz um projeto',
|
|
94
|
+
severity: 'critical',
|
|
95
|
+
probe(env) {
|
|
96
|
+
const marker = path.join(env.projectDir, 'AGENTS.md');
|
|
97
|
+
return env.fs.existsSync(marker)
|
|
98
|
+
? { status: 'ok', detail: `projeto gerado em ${path.basename(env.projectDir)}`, fix: null }
|
|
99
|
+
: { status: 'fail', detail: 'o gerador rodou mas não produziu AGENTS.md', fix: 'investigue create-memory-nest-kit' };
|
|
100
|
+
},
|
|
101
|
+
};
|
|
102
|
+
/** O bug mais barato de introduzir e o mais visível ao usuário: um template não substituído. */
|
|
103
|
+
const noPlaceholders = {
|
|
104
|
+
id: 'no-placeholders',
|
|
105
|
+
title: 'nenhum placeholder {{...}} vazou',
|
|
106
|
+
severity: 'critical',
|
|
107
|
+
dependsOn: 'generated',
|
|
108
|
+
probe(env) {
|
|
109
|
+
const leaked = [];
|
|
110
|
+
for (const file of walkFiles(env, env.projectDir, [])) {
|
|
111
|
+
const src = readText(env, file);
|
|
112
|
+
if (src == null)
|
|
113
|
+
continue;
|
|
114
|
+
const m = src.match(PLACEHOLDER_RE);
|
|
115
|
+
if (m)
|
|
116
|
+
leaked.push(`${path.relative(env.projectDir, file)} → ${m[0]}`);
|
|
117
|
+
}
|
|
118
|
+
if (leaked.length) {
|
|
119
|
+
return {
|
|
120
|
+
status: 'fail',
|
|
121
|
+
detail: `${leaked.length} placeholder(s) não substituído(s): ${leaked.slice(0, 3).join('; ')}`,
|
|
122
|
+
fix: 'o gerador esqueceu um replace — confira o fillTemplate do gerador correspondente',
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
return { status: 'ok', detail: 'todo template foi substituído', fix: null };
|
|
126
|
+
},
|
|
127
|
+
};
|
|
128
|
+
/** `package.json` gerado que não parseia entrega um projeto morto no `npm install`. */
|
|
129
|
+
const jsonValid = {
|
|
130
|
+
id: 'json-valid',
|
|
131
|
+
title: 'todo package.json gerado é JSON válido',
|
|
132
|
+
severity: 'critical',
|
|
133
|
+
dependsOn: 'generated',
|
|
134
|
+
probe(env) {
|
|
135
|
+
const broken = [];
|
|
136
|
+
let total = 0;
|
|
137
|
+
for (const file of walkFiles(env, env.projectDir, [])) {
|
|
138
|
+
if (path.basename(file) !== 'package.json')
|
|
139
|
+
continue;
|
|
140
|
+
total += 1;
|
|
141
|
+
const src = readText(env, file);
|
|
142
|
+
try {
|
|
143
|
+
JSON.parse(src ?? '');
|
|
144
|
+
}
|
|
145
|
+
catch (e) {
|
|
146
|
+
broken.push(`${path.relative(env.projectDir, file)}: ${e.message}`);
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
if (broken.length) {
|
|
150
|
+
return { status: 'fail', detail: `package.json inválido: ${broken.join('; ')}`, fix: 'corrija o template do package.json no gerador' };
|
|
151
|
+
}
|
|
152
|
+
return { status: 'ok', detail: `${total} package.json válido(s)`, fix: null };
|
|
153
|
+
},
|
|
154
|
+
};
|
|
155
|
+
/** Reusa o validador que o próprio gerador roda no fim — uma máquina, não duas (SPEC-009). */
|
|
156
|
+
const structure = {
|
|
157
|
+
id: 'structure',
|
|
158
|
+
title: 'a estrutura do projeto gerado é íntegra',
|
|
159
|
+
severity: 'critical',
|
|
160
|
+
dependsOn: 'generated',
|
|
161
|
+
probe(env) {
|
|
162
|
+
const report = validateProjectStructure(env.projectDir, { includeNest: true });
|
|
163
|
+
if (!report.isValid) {
|
|
164
|
+
return {
|
|
165
|
+
status: 'fail',
|
|
166
|
+
detail: `${report.errors.length} problema(s): ${report.errors.slice(0, 3).join('; ')}`,
|
|
167
|
+
fix: 'um arquivo/diretório crítico não foi gerado — confira o gerador de estrutura',
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
return { status: 'ok', detail: 'estrutura de memória e backend completas', fix: null };
|
|
171
|
+
},
|
|
172
|
+
};
|
|
173
|
+
/**
|
|
174
|
+
* O projeto gerado **herda o gate** dos mapas (ADR-0030): `scripts/check-memory-maps.mjs` viaja com
|
|
175
|
+
* ele. Sem isso, a coerência mapa↔código do usuário volta a viver por disciplina. Este check prova
|
|
176
|
+
* que a propagação aconteceu — o framework não só tem gates, ele os transmite.
|
|
177
|
+
*/
|
|
178
|
+
const gateInherited = {
|
|
179
|
+
id: 'gate-inherited',
|
|
180
|
+
title: 'o projeto gerado carrega o gate dos mapas (ADR-0030)',
|
|
181
|
+
severity: 'critical',
|
|
182
|
+
dependsOn: 'generated',
|
|
183
|
+
probe(env) {
|
|
184
|
+
const gate = path.join(env.projectDir, 'scripts', 'check-memory-maps.mjs');
|
|
185
|
+
return env.fs.existsSync(gate)
|
|
186
|
+
? { status: 'ok', detail: 'scripts/check-memory-maps.mjs presente — o invariante viaja com o projeto', fix: null }
|
|
187
|
+
: { status: 'fail', detail: 'o projeto gerado não trouxe o gate dos mapas', fix: 'confira o scriptTemplates do memory-generator' };
|
|
188
|
+
},
|
|
189
|
+
};
|
|
190
|
+
/**
|
|
191
|
+
* A prova final, e a mais cara: o backend gerado **buildar de verdade**. Só no tier `--full` —
|
|
192
|
+
* `npm install` de um projeto NestJS é lento e usa rede, então roda antes de release, não a cada
|
|
193
|
+
* commit. É o análogo do clean-install do `release:check`, na saída do gerador.
|
|
194
|
+
*/
|
|
195
|
+
const builds = {
|
|
196
|
+
id: 'builds',
|
|
197
|
+
title: 'o backend gerado instala e buildar (--full)',
|
|
198
|
+
severity: 'critical',
|
|
199
|
+
dependsOn: 'structure',
|
|
200
|
+
probe(env) {
|
|
201
|
+
if (!env.full) {
|
|
202
|
+
return { status: 'skipped', detail: 'tier --full desligado (custo de rede); rode com --full antes de publicar', fix: null };
|
|
203
|
+
}
|
|
204
|
+
const backend = path.join(env.projectDir, 'backend');
|
|
205
|
+
if (!env.fs.existsSync(path.join(backend, 'package.json'))) {
|
|
206
|
+
return { status: 'skipped', detail: 'sem backend/ (projeto só-memória)', fix: null };
|
|
207
|
+
}
|
|
208
|
+
const install = env.spawn('npm', ['install', '--no-audit', '--no-fund'], { cwd: backend });
|
|
209
|
+
if (install.code !== 0) {
|
|
210
|
+
return { status: 'fail', detail: `npm install falhou no backend gerado:\n${(install.stderr || install.stdout).slice(0, 500)}`, fix: 'confira as dependências no template do package.json' };
|
|
211
|
+
}
|
|
212
|
+
const build = env.spawn('npm', ['run', 'build'], { cwd: backend });
|
|
213
|
+
if (build.code !== 0) {
|
|
214
|
+
return { status: 'fail', detail: `npm run build falhou no backend gerado:\n${(build.stderr || build.stdout).slice(0, 500)}`, fix: 'o código gerado não compila — confira os templates do nest-generator' };
|
|
215
|
+
}
|
|
216
|
+
return { status: 'ok', detail: 'backend gerado instala e compila', fix: null };
|
|
217
|
+
},
|
|
218
|
+
};
|
|
219
|
+
/** @type {Check[]} */
|
|
220
|
+
export const SMOKE_CHECKS = [generated, noPlaceholders, jsonValid, structure, gateInherited, builds];
|
|
221
|
+
export function defaultEnv(overrides = {}) {
|
|
222
|
+
return {
|
|
223
|
+
root: repoRoot,
|
|
224
|
+
fs,
|
|
225
|
+
full: false,
|
|
226
|
+
spawn: (cmd, args, opts) => {
|
|
227
|
+
// Isolamento como no release: sem NODE_PATH nem npm_config_* herdados vazando para o install.
|
|
228
|
+
const env = { ...process.env };
|
|
229
|
+
delete env.NODE_PATH;
|
|
230
|
+
for (const key of Object.keys(env))
|
|
231
|
+
if (key.startsWith('npm_'))
|
|
232
|
+
delete env[key];
|
|
233
|
+
try {
|
|
234
|
+
return { stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', env, ...opts }), stderr: '', code: 0 };
|
|
235
|
+
}
|
|
236
|
+
catch (err) {
|
|
237
|
+
const e = err;
|
|
238
|
+
return { stdout: e.stdout || '', stderr: e.stderr || String(err), code: e.status ?? 1 };
|
|
239
|
+
}
|
|
240
|
+
},
|
|
241
|
+
...overrides,
|
|
242
|
+
};
|
|
243
|
+
}
|
|
244
|
+
/** Gera um projeto isolado, roda os checks, limpa. */
|
|
245
|
+
export async function runProjectSmoke({ full = false, env: overrides = {} } = {}) {
|
|
246
|
+
const base = defaultEnv({ full, ...overrides });
|
|
247
|
+
return withGeneratedProject(({ projectDir }) => run({ checks: SMOKE_CHECKS, env: { ...base, projectDir } }), { root: base.root, spawn: base.spawn });
|
|
248
|
+
}
|
|
@@ -54,6 +54,11 @@ export declare const COMMANDS: {
|
|
|
54
54
|
node: string;
|
|
55
55
|
args: string[];
|
|
56
56
|
};
|
|
57
|
+
'project:upgrade': {
|
|
58
|
+
domain: string;
|
|
59
|
+
desc: string;
|
|
60
|
+
node: string;
|
|
61
|
+
};
|
|
57
62
|
'workspace:project:check': {
|
|
58
63
|
domain: string;
|
|
59
64
|
desc: string;
|
|
@@ -156,6 +161,11 @@ export declare const COMMANDS: {
|
|
|
156
161
|
node: string;
|
|
157
162
|
args: string[];
|
|
158
163
|
};
|
|
164
|
+
'code:context': {
|
|
165
|
+
domain: string;
|
|
166
|
+
desc: string;
|
|
167
|
+
node: string;
|
|
168
|
+
};
|
|
159
169
|
'code:index': {
|
|
160
170
|
domain: string;
|
|
161
171
|
desc: string;
|
|
@@ -212,6 +222,11 @@ export declare const COMMANDS: {
|
|
|
212
222
|
desc: string;
|
|
213
223
|
node: string;
|
|
214
224
|
};
|
|
225
|
+
'memory:audit': {
|
|
226
|
+
domain: string;
|
|
227
|
+
desc: string;
|
|
228
|
+
node: string;
|
|
229
|
+
};
|
|
215
230
|
'context:smart': {
|
|
216
231
|
domain: string;
|
|
217
232
|
desc: string;
|
|
@@ -253,6 +268,11 @@ export declare const COMMANDS: {
|
|
|
253
268
|
desc: string;
|
|
254
269
|
node: string;
|
|
255
270
|
};
|
|
271
|
+
'token:economy': {
|
|
272
|
+
domain: string;
|
|
273
|
+
desc: string;
|
|
274
|
+
node: string;
|
|
275
|
+
};
|
|
256
276
|
'project:check': {
|
|
257
277
|
domain: string;
|
|
258
278
|
desc: string;
|
|
@@ -268,6 +288,16 @@ export declare const COMMANDS: {
|
|
|
268
288
|
desc: string;
|
|
269
289
|
node: string;
|
|
270
290
|
};
|
|
291
|
+
'project:smoke': {
|
|
292
|
+
domain: string;
|
|
293
|
+
desc: string;
|
|
294
|
+
node: string;
|
|
295
|
+
};
|
|
296
|
+
'check:all': {
|
|
297
|
+
domain: string;
|
|
298
|
+
desc: string;
|
|
299
|
+
node: string;
|
|
300
|
+
};
|
|
271
301
|
'project:dashboard': {
|
|
272
302
|
domain: string;
|
|
273
303
|
desc: string;
|
|
@@ -67,6 +67,11 @@ export const COMMANDS = {
|
|
|
67
67
|
node: 'scripts/agent-harness.ts',
|
|
68
68
|
args: ['project:list'],
|
|
69
69
|
},
|
|
70
|
+
'project:upgrade': {
|
|
71
|
+
domain: 'workspace',
|
|
72
|
+
desc: 'Traz peças novas de scaffold para um projeto gerado — aditivo (SPEC-018). --apply para copiar',
|
|
73
|
+
node: 'scripts/project-upgrade.ts',
|
|
74
|
+
},
|
|
70
75
|
'workspace:project:check': {
|
|
71
76
|
domain: 'workspace',
|
|
72
77
|
desc: 'Valida padrões em um projeto do workspace',
|
|
@@ -173,6 +178,11 @@ export const COMMANDS = {
|
|
|
173
178
|
node: 'scripts/agent-harness.ts',
|
|
174
179
|
args: ['code:impact'],
|
|
175
180
|
},
|
|
181
|
+
'code:context': {
|
|
182
|
+
domain: 'code',
|
|
183
|
+
desc: 'Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009)',
|
|
184
|
+
node: 'scripts/code-context.ts',
|
|
185
|
+
},
|
|
176
186
|
'code:index': {
|
|
177
187
|
domain: 'code',
|
|
178
188
|
desc: 'Inicializa índice codegraph',
|
|
@@ -230,6 +240,11 @@ export const COMMANDS = {
|
|
|
230
240
|
desc: 'Extrai conhecimento global da memória',
|
|
231
241
|
node: 'scripts/extract-global-knowledge.ts',
|
|
232
242
|
},
|
|
243
|
+
'memory:audit': {
|
|
244
|
+
domain: 'memoria',
|
|
245
|
+
desc: 'Coerência mapa↔código: mapa não cita código morto (falha) + módulo sem mapa (aviso). SPEC-017',
|
|
246
|
+
node: 'scripts/memory-audit.ts',
|
|
247
|
+
},
|
|
233
248
|
// --- Contexto & token economy ---------------------------------------------
|
|
234
249
|
'context:smart': {
|
|
235
250
|
domain: 'contexto',
|
|
@@ -272,6 +287,11 @@ export const COMMANDS = {
|
|
|
272
287
|
desc: 'Benchmark de consumo de tokens',
|
|
273
288
|
node: 'scripts/token-benchmark.ts',
|
|
274
289
|
},
|
|
290
|
+
'token:economy': {
|
|
291
|
+
domain: 'contexto',
|
|
292
|
+
desc: 'Economia de token: eixos arquitetura + memória; --project mede seus domínios reais (ADR-0009/0027)',
|
|
293
|
+
node: 'scripts/token-economy.ts',
|
|
294
|
+
},
|
|
275
295
|
// --- Governança & qualidade ---------------------------------------------------
|
|
276
296
|
'project:check': {
|
|
277
297
|
domain: 'governanca',
|
|
@@ -288,6 +308,16 @@ export const COMMANDS = {
|
|
|
288
308
|
desc: 'Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito',
|
|
289
309
|
node: 'scripts/release-check.ts',
|
|
290
310
|
},
|
|
311
|
+
'project:smoke': {
|
|
312
|
+
domain: 'governanca',
|
|
313
|
+
desc: 'Gate do projeto gerado: gera isolado e prova que é coerente (SPEC-015). --full instala e builda o backend',
|
|
314
|
+
node: 'scripts/project-smoke.ts',
|
|
315
|
+
},
|
|
316
|
+
'check:all': {
|
|
317
|
+
domain: 'governanca',
|
|
318
|
+
desc: 'Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build',
|
|
319
|
+
node: 'scripts/gates.ts',
|
|
320
|
+
},
|
|
291
321
|
'project:dashboard': {
|
|
292
322
|
domain: 'governanca',
|
|
293
323
|
desc: 'Gera dashboard estático de status',
|
|
@@ -62,6 +62,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
62
62
|
node: string;
|
|
63
63
|
args: string[];
|
|
64
64
|
};
|
|
65
|
+
'project:upgrade': {
|
|
66
|
+
domain: string;
|
|
67
|
+
desc: string;
|
|
68
|
+
node: string;
|
|
69
|
+
};
|
|
65
70
|
'workspace:project:check': {
|
|
66
71
|
domain: string;
|
|
67
72
|
desc: string;
|
|
@@ -164,6 +169,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
164
169
|
node: string;
|
|
165
170
|
args: string[];
|
|
166
171
|
};
|
|
172
|
+
'code:context': {
|
|
173
|
+
domain: string;
|
|
174
|
+
desc: string;
|
|
175
|
+
node: string;
|
|
176
|
+
};
|
|
167
177
|
'code:index': {
|
|
168
178
|
domain: string;
|
|
169
179
|
desc: string;
|
|
@@ -220,6 +230,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
220
230
|
desc: string;
|
|
221
231
|
node: string;
|
|
222
232
|
};
|
|
233
|
+
'memory:audit': {
|
|
234
|
+
domain: string;
|
|
235
|
+
desc: string;
|
|
236
|
+
node: string;
|
|
237
|
+
};
|
|
223
238
|
'context:smart': {
|
|
224
239
|
domain: string;
|
|
225
240
|
desc: string;
|
|
@@ -261,6 +276,11 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
261
276
|
desc: string;
|
|
262
277
|
node: string;
|
|
263
278
|
};
|
|
279
|
+
'token:economy': {
|
|
280
|
+
domain: string;
|
|
281
|
+
desc: string;
|
|
282
|
+
node: string;
|
|
283
|
+
};
|
|
264
284
|
'project:check': {
|
|
265
285
|
domain: string;
|
|
266
286
|
desc: string;
|
|
@@ -276,6 +296,16 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
276
296
|
desc: string;
|
|
277
297
|
node: string;
|
|
278
298
|
};
|
|
299
|
+
'project:smoke': {
|
|
300
|
+
domain: string;
|
|
301
|
+
desc: string;
|
|
302
|
+
node: string;
|
|
303
|
+
};
|
|
304
|
+
'check:all': {
|
|
305
|
+
domain: string;
|
|
306
|
+
desc: string;
|
|
307
|
+
node: string;
|
|
308
|
+
};
|
|
279
309
|
'project:dashboard': {
|
|
280
310
|
domain: string;
|
|
281
311
|
desc: string;
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
export declare function getAllMemoryTemplates(): {
|
|
9
9
|
'scripts/build-context-pack.mjs': string;
|
|
10
10
|
'scripts/append-handoff.mjs': string;
|
|
11
|
+
'scripts/check-memory-maps.mjs': string;
|
|
11
12
|
'scripts/lib/skill-loader.mjs': string;
|
|
12
13
|
'scripts/memory-vacuum.mjs': string;
|
|
13
14
|
'scripts/memory-watcher.mjs': string;
|
|
@@ -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';
|
|
@@ -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[];
|