forjajs 5.1.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/CHANGELOG.md +76 -0
  2. package/README.md +37 -4
  3. package/README.pt-BR.md +39 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +349 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/project-wiring.js +6 -2
  36. package/dist/lib/session-memory.d.ts +38 -0
  37. package/dist/lib/session-memory.js +206 -0
  38. package/dist/lib/spec-trace.d.ts +46 -0
  39. package/dist/lib/spec-trace.js +184 -0
  40. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  41. package/dist/packages/adapter-nest/src/index.js +59 -1
  42. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  43. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  44. package/dist/packages/context/src/index.d.ts +2 -0
  45. package/dist/packages/context/src/index.js +36 -15
  46. package/dist/packages/contracts/src/index.d.ts +64 -0
  47. package/dist/packages/core/src/index.d.ts +9 -1
  48. package/dist/packages/core/src/index.js +28 -3
  49. package/dist/packages/graph/src/index.js +14 -5
  50. package/dist/packages/mcp/src/index.d.ts +8 -0
  51. package/dist/packages/mcp/src/index.js +12 -1
  52. package/dist/packages/observability/src/index.d.ts +11 -0
  53. package/dist/packages/observability/src/index.js +3 -0
  54. package/dist/packages/orchestration/src/index.d.ts +15 -1
  55. package/dist/packages/orchestration/src/index.js +127 -21
  56. package/dist/packages/planner/src/index.d.ts +7 -1
  57. package/dist/packages/planner/src/index.js +67 -10
  58. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  59. package/dist/packages/planner/src/proposal-store.js +109 -0
  60. package/dist/packages/policy/src/index.d.ts +9 -16
  61. package/dist/packages/policy/src/index.js +114 -31
  62. package/dist/packages/runtime/src/index.d.ts +16 -2
  63. package/dist/packages/runtime/src/index.js +176 -61
  64. package/dist/scripts/build-smart-context.d.ts +2 -0
  65. package/dist/scripts/build-smart-context.js +12 -3
  66. package/dist/scripts/code-context.d.ts +3 -1
  67. package/dist/scripts/code-context.js +13 -3
  68. package/dist/scripts/coverage-gate.d.ts +2 -0
  69. package/dist/scripts/coverage-gate.js +101 -0
  70. package/dist/scripts/eval-agents.d.ts +11 -0
  71. package/dist/scripts/eval-agents.js +96 -0
  72. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  73. package/dist/scripts/gen-commands-doc.js +18 -0
  74. package/dist/scripts/hook-session-memory.d.ts +9 -0
  75. package/dist/scripts/hook-session-memory.js +20 -0
  76. package/dist/scripts/hook-session-start.js +34 -0
  77. package/dist/scripts/spec-trace.d.ts +10 -0
  78. package/dist/scripts/spec-trace.js +73 -0
  79. package/dist/scripts/sync-universal-memory.js +69 -4
  80. package/dist/scripts/token-benchmark.d.ts +33 -1
  81. package/dist/scripts/token-benchmark.js +179 -5
  82. package/dist/scripts/token-economy.js +3 -1
  83. package/dist/scripts/tools-doctor.d.ts +16 -1
  84. package/dist/scripts/tools-doctor.js +58 -17
  85. package/docs/commands.md +155 -0
  86. package/docs/fluxo.md +11 -7
  87. package/docs/init-project.md +3 -1
  88. package/docs/llm-fit-loop.md +20 -0
  89. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  90. package/docs/produto/factsheet-marketing.md +7 -5
  91. package/docs/produto/roteiro-demo.md +14 -5
  92. package/docs/quick-reference.md +3 -3
  93. package/docs/token-optimization.md +10 -6
  94. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  95. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  96. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  97. package/package.json +4 -2
  98. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  99. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  100. package/specs/memoria-de-sessao/spec.md +48 -0
  101. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  102. package/specs/v6-core-consolidation/spec.md +70 -0
  103. package/specs/v6-docs-drift/spec.md +85 -0
  104. package/specs/v6-quality-gates/spec.md +99 -0
  105. package/specs/v6-token-economy/spec.md +84 -0
  106. package/templates/evals/agents/adr.json +25 -0
  107. package/templates/evals/agents/memoria.json +32 -0
  108. package/templates/evals/agents/proxima-acao.json +29 -0
  109. package/templates/evals/agents/spec-nova.json +26 -0
  110. package/templates/evals/agents/teste-do-criterio.json +29 -0
  111. package/templates/project/AGENTS.md +7 -0
  112. package/templates/project/CLAUDE.md +3 -2
  113. package/templates/project/skills/testing/SKILL.md +1 -1
@@ -11,7 +11,6 @@
11
11
  import fs from 'node:fs';
12
12
  import path from 'node:path';
13
13
  import Database from 'better-sqlite3';
14
- import { getDbPath, ensureSchema } from '../scripts/memory-schema.js';
15
14
  /**
16
15
  * Termo livre → consulta FTS5 segura: cada palavra vira frase entre aspas. Sem isto, `pix-qr` ou
17
16
  * `auth:jwt` são sintaxe FTS inválida e a query inteira lança — e o modo task voltava vazio.
@@ -20,6 +19,66 @@ export function ftsQuery(keyword) {
20
19
  const terms = String(keyword).split(/\s+/).filter(Boolean).map((t) => `"${t.replace(/"/g, '""')}"`);
21
20
  return terms.join(' ') || '""';
22
21
  }
22
+ /**
23
+ * Nó curto entra inteiro (SPEC-057 AC-1). ~400 tokens na régua bytes/4 que o framework usa em todo
24
+ * lugar: abaixo disso, cortar economiza migalha e perde o contexto que dava sentido ao trecho.
25
+ */
26
+ export const FULL_CONTENT_MAX_CHARS = Number(process.env.FORJA_CONTEXT_FULL_MAX_CHARS) || 1600;
27
+ /** Raio do `snippet()` do FTS5 — em tokens, não em chars: ±24 tokens em volta de cada casamento. */
28
+ export const SNIPPET_RADIUS_TOKENS = 24;
29
+ /** Marcador de casamento no trecho injetado; o agente vê onde a busca bateu. */
30
+ const MARK = '**';
31
+ /**
32
+ * Constituição do pack: missão e padrões entram inteiros por tamanho que tenham. Um trecho solto de
33
+ * `standards.md` orienta pior do que nada — é a única classe de nó que o corte piora sempre.
34
+ */
35
+ const ALWAYS_FULL_RE = /(?:mission|standards)\.md$/i;
36
+ function elision(omitted) {
37
+ return `\n\n> ⋯ ${omitted} chars omitidos — leia o arquivo acima ou rode com \`--full-context\``;
38
+ }
39
+ /** Cabeça do nó cortada em fronteira de linha: corte no meio de uma linha parece arquivo corrompido. */
40
+ export function headExcerpt(content, max = FULL_CONTENT_MAX_CHARS) {
41
+ const cut = content.slice(0, max);
42
+ const nl = cut.lastIndexOf('\n');
43
+ return (nl > 0 ? cut.slice(0, nl) : cut).trimEnd();
44
+ }
45
+ /**
46
+ * Janela em volta da primeira ocorrência do termo — para os nós que o LIKE acha e o FTS não (o
47
+ * porter não casa substring no meio de palavra, e é justamente esse o caso que cai aqui). O raio é o
48
+ * mesmo do `snippet()` em chars (tokens × 4, a régua do repo): dois produtores de trecho, um orçamento.
49
+ */
50
+ export function excerptAround(content, needle, radius = SNIPPET_RADIUS_TOKENS * 4) {
51
+ const at = needle ? content.toLowerCase().indexOf(needle.toLowerCase()) : -1;
52
+ if (at < 0)
53
+ return headExcerpt(content);
54
+ let start = Math.max(0, at - radius);
55
+ let end = Math.min(content.length, at + needle.length + radius);
56
+ if (start > 0) {
57
+ const word = /^\S*/.exec(content.slice(start))?.[0].length ?? 0;
58
+ start = Math.min(at, start + word);
59
+ }
60
+ if (end < content.length) {
61
+ const word = /\S*$/.exec(content.slice(0, end))?.[0].length ?? 0;
62
+ end = Math.max(at + needle.length, end - word);
63
+ }
64
+ const prefix = start > 0 ? '… ' : '';
65
+ const suffix = end < content.length ? ' …' : '';
66
+ return prefix + content.slice(start, end).trim() + suffix;
67
+ }
68
+ /**
69
+ * O que entra no pack por nó. Retorna também quantos chars ficaram de fora — a omissão é sempre
70
+ * visível, porque corte calado é o agente raciocinando sobre metade da regra e não sabendo.
71
+ */
72
+ export function nodeBody(node, opts = {}) {
73
+ const total = node.content.length;
74
+ if (opts.full || total <= FULL_CONTENT_MAX_CHARS || ALWAYS_FULL_RE.test(node.path)) {
75
+ return { text: node.content, omitted: 0 };
76
+ }
77
+ const text = node.excerpt ?? headExcerpt(node.content);
78
+ const kept = text.replaceAll(MARK, '').replaceAll('…', '').trim().length;
79
+ const omitted = Math.max(0, total - kept);
80
+ return { text: text + elision(omitted), omitted };
81
+ }
23
82
  export class ContextBuilder {
24
83
  projectPath;
25
84
  dbPath;
@@ -61,7 +120,7 @@ export class ContextBuilder {
61
120
  * @param {string} keyword - Palavra-chave para busca (modo 'task')
62
121
  * @returns {string} Conteúdo do contexto em markdown
63
122
  */
64
- build(mode, project, keyword = '') {
123
+ build(mode, project, keyword = '', opts = {}) {
65
124
  this.connect();
66
125
  const started = Date.now();
67
126
  const nodes = [];
@@ -79,7 +138,7 @@ export class ContextBuilder {
79
138
  nodes.push(...taskNodes);
80
139
  }
81
140
  // 3. Gerar markdown deduplicado
82
- let context = this._generateMarkdown(mode, project, keyword, nodes, seenPaths);
141
+ const { markdown: context, shown, excerpted } = this._generateMarkdown(mode, project, keyword, nodes, seenPaths, opts);
83
142
  const duration = Date.now() - started;
84
143
  // 4. Adicionar footer com metadata
85
144
  const footer = `\n\n---\n\n## 📊 Context Metadata\n\n` +
@@ -89,6 +148,7 @@ export class ContextBuilder {
89
148
  `- **Generated**: ${new Date().toISOString()}\n` +
90
149
  `- **Duration**: ${duration}ms\n` +
91
150
  `- **Files**: ${seenPaths.size}\n` +
151
+ `- **Excerpts**: ${excerpted}/${shown} nodes\n` +
92
152
  `- **Size**: ${Math.round(context.length / 1024)}KB\n`;
93
153
  return context + footer;
94
154
  }
@@ -145,20 +205,52 @@ export class ContextBuilder {
145
205
  }
146
206
  /**
147
207
  * Obter contexto orientado a tarefa (busca por FTS5)
208
+ *
209
+ * Duas consultas, não uma: a do FTS já devolve o trecho casado via `snippet()` — injetar o nó
210
+ * inteiro era o maior sorvedouro de token do pack (SPEC-057). O `LIKE` cobre o que o porter não
211
+ * casa (substring no meio de palavra) e ganha uma janela calculada aqui, porque fora do FTS não
212
+ * existe `snippet()` para destacar o casamento.
148
213
  */
149
- _getTaskNodes(project, keyword) {
214
+ _getTaskNodes(project, keyword, limit = 20) {
215
+ const fts = this._ftsTaskNodes(project, keyword, limit);
216
+ if (fts.length >= limit)
217
+ return fts;
218
+ return [...fts, ...this._likeTaskNodes(project, keyword, ftsQuery(keyword), limit - fts.length)];
219
+ }
220
+ _ftsTaskNodes(project, keyword, limit) {
150
221
  try {
151
222
  const stmt = this.db.prepare(`
152
- SELECT DISTINCT n.title, n.content, n.path
223
+ SELECT n.title, n.path, n.content,
224
+ snippet(search_idx, 2, '${MARK}', '${MARK}', ' … ', ?) AS excerpt
225
+ FROM search_idx
226
+ JOIN memory_nodes n ON n.id = search_idx.node_id
227
+ JOIN projects p ON p.id = n.project_id
228
+ WHERE search_idx MATCH ? AND p.name = ?
229
+ ORDER BY rank
230
+ LIMIT ?
231
+ `);
232
+ return stmt.all(SNIPPET_RADIUS_TOKENS, ftsQuery(keyword), project, limit) || [];
233
+ }
234
+ catch (e) {
235
+ console.warn(`⚠️ No task nodes found for "${keyword}":`, e.message);
236
+ return [];
237
+ }
238
+ }
239
+ _likeTaskNodes(project, keyword, fts, limit) {
240
+ if (limit <= 0)
241
+ return [];
242
+ try {
243
+ const stmt = this.db.prepare(`
244
+ SELECT n.title, n.path, n.content
153
245
  FROM memory_nodes n
154
246
  JOIN projects p ON p.id = n.project_id
155
- WHERE p.name = ?
156
- AND (n.content LIKE ? OR n.id IN (SELECT node_id FROM search_idx WHERE search_idx MATCH ?))
247
+ WHERE p.name = ? AND n.content LIKE ?
248
+ AND n.id NOT IN (SELECT node_id FROM search_idx WHERE search_idx MATCH ?)
157
249
  ORDER BY n.updated_at DESC
158
- LIMIT 20
250
+ LIMIT ?
159
251
  `);
160
- const pattern = `%${keyword}%`;
161
- return stmt.all(project, pattern, ftsQuery(keyword)) || [];
252
+ const rows = stmt.all(project, `%${keyword}%`, fts, limit) || [];
253
+ return rows.map((n) => ({ ...n, excerpt: excerptAround(n.content, keyword) }));
162
254
  }
163
255
  catch (e) {
164
256
  console.warn(`⚠️ No task nodes found for "${keyword}":`, e.message);
@@ -168,22 +260,28 @@ export class ContextBuilder {
168
260
  /**
169
261
  * Gerar markdown deduplicado
170
262
  */
171
- _generateMarkdown(mode, project, keyword, nodes, seenPaths) {
263
+ _generateMarkdown(mode, project, keyword, nodes, seenPaths, opts = {}) {
172
264
  let md = `# CONTEXT PACK: ${project.toUpperCase()}\n\n`;
173
265
  md += `**Mode**: \`${mode}\`\n`;
174
266
  if (keyword)
175
267
  md += `**Search**: \`${keyword}\`\n`;
176
268
  md += `\n`;
269
+ let shown = 0;
270
+ let excerpted = 0;
177
271
  for (const node of nodes) {
178
272
  if (seenPaths.has(node.path))
179
273
  continue;
180
274
  seenPaths.add(node.path);
275
+ const body = nodeBody(node, opts);
276
+ if (body.omitted > 0)
277
+ excerpted++;
278
+ shown++;
181
279
  md += `## 📄 ${node.title}\n`;
182
- md += `**Path**: \`${node.path}\`\n\n`;
183
- md += `${node.content}\n\n`;
280
+ md += `**Path**: \`${node.path.split(path.sep).join('/')}\`\n\n`;
281
+ md += `${body.text}\n\n`;
184
282
  md += `---\n\n`;
185
283
  }
186
- return md;
284
+ return { markdown: md, shown, excerpted };
187
285
  }
188
286
  /**
189
287
  * Salvar contexto em arquivo
@@ -198,8 +296,8 @@ export class ContextBuilder {
198
296
  /**
199
297
  * Estatísticas de contexto
200
298
  */
201
- stats(mode, project, keyword = '') {
202
- const content = this.build(mode, project, keyword);
299
+ stats(mode, project, keyword = '', opts = {}) {
300
+ const content = this.build(mode, project, keyword, opts);
203
301
  const lines = content.split('\n').length;
204
302
  const tokens = Math.round(content.length / 4); // Aproximação simples
205
303
  return {
@@ -213,35 +311,4 @@ export class ContextBuilder {
213
311
  };
214
312
  }
215
313
  }
216
- /**
217
- * Modo CLI - Executar via node scripts/context-builder.mjs
218
- */
219
- if (import.meta.url === `file://${process.argv[1]}`) {
220
- const [mode, project, keyword] = process.argv.slice(2);
221
- if (!mode || !project) {
222
- console.error('Uso: forja context:smart [--mode global|domain|task] [--task <termo>]');
223
- console.error('Modes: global, domain, task');
224
- process.exit(1);
225
- }
226
- ensureSchema({ silent: true });
227
- const dbPath = getDbPath();
228
- const builder = new ContextBuilder(process.cwd(), dbPath);
229
- try {
230
- console.log(`🔨 Building ${mode} context for ${project}...`);
231
- const content = builder.build(mode, project, keyword);
232
- const stats = builder.stats(mode, project, keyword);
233
- const outDir = path.join(process.cwd(), '.context');
234
- const outFile = path.join(outDir, `context-${mode}.md`);
235
- builder.save(content, outFile);
236
- console.log(`✅ Context saved: ${outFile}`);
237
- console.log(`📊 Stats:`, stats);
238
- }
239
- catch (e) {
240
- console.error('❌ Error:', e.message);
241
- process.exit(1);
242
- }
243
- finally {
244
- builder.close();
245
- }
246
- }
247
314
  export default ContextBuilder;
@@ -0,0 +1,59 @@
1
+ /**
2
+ * lib/core/coverage-gate.ts — a régua de cobertura da SPEC-056 AC-3, sem rodar a suíte.
3
+ *
4
+ * `scripts/coverage-gate.ts` precisa spawnar `node --test --experimental-test-coverage` inteiro para
5
+ * chegar num veredito, o que o torna impossível de testar: um teste dele rodaria a suíte dentro da
6
+ * suíte. Aqui fica só o que dá para provar sozinho — ler a linha `all files` da tabela do Node, ler o
7
+ * piso versionado e decidir o código de saída. O script vira um adaptador fino: coleta as quatro
8
+ * entradas, chama `decideCoverage()` e emite no contrato do ADR-0082.
9
+ *
10
+ * A ordem das decisões é o contrato, não um detalhe: suíte que falha é mais grave que piso baixo (não
11
+ * adianta cobrar cobertura de uma suíte vermelha), e tabela ausente é falha operacional do gate — o
12
+ * formato do Node mudou —, nunca um "OK" silencioso.
13
+ */
14
+ export type CoverageTotal = {
15
+ readonly lines: number;
16
+ readonly branches: number;
17
+ readonly funcs: number;
18
+ };
19
+ export type CoverageInput = {
20
+ /** Mensagem do erro de spawn, ou `null` quando a suíte chegou a rodar. */
21
+ readonly spawnError: string | null;
22
+ /** Tabela já lida, ou `null` quando a linha `all files` não apareceu na saída. */
23
+ readonly total: CoverageTotal | null;
24
+ /** Código de saída da suíte; `null` quando o processo morreu por sinal. */
25
+ readonly suiteStatus: number | null;
26
+ readonly floor: number;
27
+ };
28
+ export type CoverageOutcome = {
29
+ readonly kind: 'spawn-failed';
30
+ readonly exitCode: 1;
31
+ readonly code: 'ESPAWN';
32
+ } | {
33
+ readonly kind: 'table-missing';
34
+ readonly exitCode: 1;
35
+ readonly code: 'EPARSE';
36
+ } | {
37
+ readonly kind: 'suite-failed';
38
+ readonly exitCode: number;
39
+ readonly code: 'ESUITE';
40
+ } | {
41
+ readonly kind: 'below-floor';
42
+ readonly exitCode: 2;
43
+ readonly code: 'EFLOOR';
44
+ } | {
45
+ readonly kind: 'ok';
46
+ readonly exitCode: 0;
47
+ readonly code: 'OK';
48
+ };
49
+ /** Devolve os três percentuais da linha `all files`, ou `null` se a tabela não está lá. */
50
+ export declare function parseCoverageTotal(stdout: string): CoverageTotal | null;
51
+ /**
52
+ * Lê `coverageLineFloor` do texto do orçamento. Recebe o texto, não o caminho: quem lê o arquivo é o
53
+ * script, que é quem sabe transformar ENOENT em receita de criação do arquivo.
54
+ */
55
+ export declare function coverageFloorFrom(budgetText: string, label: string): number;
56
+ /** A tabela de decisão do gate — cada ramo tem um código de saída próprio e nenhum deles é 0 por omissão. */
57
+ export declare function decideCoverage(input: CoverageInput): CoverageOutcome;
58
+ /** Linha humana única, igual nos três desfechos — o CI lê o mesmo formato seja verde ou vermelho. */
59
+ export declare function coverageSummary(total: CoverageTotal, floor: number): string;
@@ -0,0 +1,58 @@
1
+ /**
2
+ * lib/core/coverage-gate.ts — a régua de cobertura da SPEC-056 AC-3, sem rodar a suíte.
3
+ *
4
+ * `scripts/coverage-gate.ts` precisa spawnar `node --test --experimental-test-coverage` inteiro para
5
+ * chegar num veredito, o que o torna impossível de testar: um teste dele rodaria a suíte dentro da
6
+ * suíte. Aqui fica só o que dá para provar sozinho — ler a linha `all files` da tabela do Node, ler o
7
+ * piso versionado e decidir o código de saída. O script vira um adaptador fino: coleta as quatro
8
+ * entradas, chama `decideCoverage()` e emite no contrato do ADR-0082.
9
+ *
10
+ * A ordem das decisões é o contrato, não um detalhe: suíte que falha é mais grave que piso baixo (não
11
+ * adianta cobrar cobertura de uma suíte vermelha), e tabela ausente é falha operacional do gate — o
12
+ * formato do Node mudou —, nunca um "OK" silencioso.
13
+ */
14
+ /** `all files | line % | branch % | funcs %` — a régua cobrada é a de linhas. */
15
+ const TOTAL_RE = /all files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|/;
16
+ /** Devolve os três percentuais da linha `all files`, ou `null` se a tabela não está lá. */
17
+ export function parseCoverageTotal(stdout) {
18
+ const total = TOTAL_RE.exec(stdout);
19
+ if (total === null)
20
+ return null;
21
+ const [lines, branches, funcs] = [total[1], total[2], total[3]].map(Number);
22
+ return { lines, branches, funcs };
23
+ }
24
+ /**
25
+ * Lê `coverageLineFloor` do texto do orçamento. Recebe o texto, não o caminho: quem lê o arquivo é o
26
+ * script, que é quem sabe transformar ENOENT em receita de criação do arquivo.
27
+ */
28
+ export function coverageFloorFrom(budgetText, label) {
29
+ let parsed;
30
+ try {
31
+ parsed = JSON.parse(budgetText);
32
+ }
33
+ catch (err) {
34
+ throw new Error(`orçamento ilegível (${label}): ${err instanceof Error ? err.message : String(err)}`);
35
+ }
36
+ const value = parsed?.coverageLineFloor;
37
+ if (typeof value !== 'number')
38
+ throw new Error(`${label} sem coverageLineFloor numérico`);
39
+ return value;
40
+ }
41
+ /** A tabela de decisão do gate — cada ramo tem um código de saída próprio e nenhum deles é 0 por omissão. */
42
+ export function decideCoverage(input) {
43
+ if (input.spawnError !== null)
44
+ return { kind: 'spawn-failed', exitCode: 1, code: 'ESPAWN' };
45
+ if (input.total === null)
46
+ return { kind: 'table-missing', exitCode: 1, code: 'EPARSE' };
47
+ // `null` = morto por sinal: não há código para repassar, e o gate não pode sair 0 por isso.
48
+ const status = input.suiteStatus ?? 1;
49
+ if (status !== 0)
50
+ return { kind: 'suite-failed', exitCode: status, code: 'ESUITE' };
51
+ if (input.total.lines < input.floor)
52
+ return { kind: 'below-floor', exitCode: 2, code: 'EFLOOR' };
53
+ return { kind: 'ok', exitCode: 0, code: 'OK' };
54
+ }
55
+ /** Linha humana única, igual nos três desfechos — o CI lê o mesmo formato seja verde ou vermelho. */
56
+ export function coverageSummary(total, floor) {
57
+ return `cobertura de linhas ${total.lines.toFixed(2)}% (piso ${floor}%) · branches ${total.branches.toFixed(2)}% · funções ${total.funcs.toFixed(2)}%`;
58
+ }
@@ -77,3 +77,41 @@ export declare function defaultEnv(overrides?: {}): {
77
77
  root: string;
78
78
  fs: typeof fs;
79
79
  };
80
+ /**
81
+ * Tokens de flag de um trecho (`usage` do registry, linha de doc). Único tokenizer de flags do
82
+ * framework: quem precisa dos índices usa `scanFlags`; quem precisa só do conjunto chama isto.
83
+ */
84
+ export declare function flagTokens(text: string): string[];
85
+ /**
86
+ * Flags citadas junto de uma *invocação* de comando do Forja nas superfícies de instrução.
87
+ *
88
+ * Duas decisões que valem o comentário:
89
+ * - **Dono = última invocação prefixada antes da flag** (`forja x:y`, `npm run x:y`). Citação sem
90
+ * prefixo não é invocação: na prosa ("`llm:run --profile claude` → `claude -p …`") a flag pertence
91
+ * ao binário do provedor, e atribuí-la ao Forja é falso positivo.
92
+ * - **`mentions` devolve toda citação da linha**, com ou sem prefixo, para o check poder absolver a
93
+ * flag que a linha atribui a outro comando do Forja ("Lista os boilerplates (project:new
94
+ * --template)" na célula de `project:templates`).
95
+ *
96
+ * Comentário de fim de linha é cortado: ali a prosa cita flag de *outro* comando.
97
+ *
98
+ * Leitura pura — quem decide se a flag existe é o check `docs-flags`, contra o registry.
99
+ * @returns {{ file: string, line: number, command: string, flag: string, mentions: string[] }[]}
100
+ */
101
+ export declare function scanFlags(env: any): {
102
+ file: string;
103
+ line: number;
104
+ command: string;
105
+ flag: string;
106
+ mentions: string[];
107
+ }[];
108
+ /**
109
+ * Contagens de skills afirmadas na doc (`# 34 skills …`), para comparar com as pastas reais de
110
+ * `templates/project/skills/`. Leitura pura — o juízo é do check `docs-skills-count`.
111
+ * @returns {{ file: string, line: number, claimed: number }[]}
112
+ */
113
+ export declare function scanSkillCounts(env: any): {
114
+ file: string;
115
+ line: number;
116
+ claimed: number;
117
+ }[];
@@ -29,6 +29,7 @@ export const DOC_SURFACES = [
29
29
  'AGENTS.md',
30
30
  'CLAUDE.md',
31
31
  'README.md',
32
+ 'README.pt-BR.md',
32
33
  'README.en.md',
33
34
  'DOC-MAP.md',
34
35
  ];
@@ -296,3 +297,85 @@ export function defaultEnv(overrides = {}) {
296
297
  ...overrides,
297
298
  };
298
299
  }
300
+ /**
301
+ * Flag CLI: `--long` ou `-h`. Duas restrições de propósito:
302
+ * - lookbehind (e não classe de chars) para pegar `[--ai <lista>]` dentro de um usage;
303
+ * - traço simples só casa com UMA letra — senão o pronome clítico do português ("consultá-lo",
304
+ * "rode-o") vira flag `-lo`/`-o`.
305
+ */
306
+ const FLAG_RE = /(?<![A-Za-z0-9_-])(--[a-z][a-z0-9-]*|-[a-z])(?![a-z0-9-])/g;
307
+ const SKILL_COUNT_RE = /(\d+)[ \t]+skills?\b/gi;
308
+ /**
309
+ * Tokens de flag de um trecho (`usage` do registry, linha de doc). Único tokenizer de flags do
310
+ * framework: quem precisa dos índices usa `scanFlags`; quem precisa só do conjunto chama isto.
311
+ */
312
+ export function flagTokens(text) {
313
+ return [...text.matchAll(FLAG_RE)].map((m) => m[1]);
314
+ }
315
+ /** Citação de comando sem o prefixo `forja`/`npm run` — contexto da linha, nunca dono de flag. */
316
+ const MENTION_RE = /\b([a-z][a-z0-9]*(?::[a-z0-9-]+)+)\b/g;
317
+ /** Corta o comentário de fim de linha — ali a prosa fala, não documenta uso. */
318
+ function executablePart(line) {
319
+ const at = line.search(/\s#/);
320
+ return at === -1 ? line : line.slice(0, at);
321
+ }
322
+ /**
323
+ * Flags citadas junto de uma *invocação* de comando do Forja nas superfícies de instrução.
324
+ *
325
+ * Duas decisões que valem o comentário:
326
+ * - **Dono = última invocação prefixada antes da flag** (`forja x:y`, `npm run x:y`). Citação sem
327
+ * prefixo não é invocação: na prosa ("`llm:run --profile claude` → `claude -p …`") a flag pertence
328
+ * ao binário do provedor, e atribuí-la ao Forja é falso positivo.
329
+ * - **`mentions` devolve toda citação da linha**, com ou sem prefixo, para o check poder absolver a
330
+ * flag que a linha atribui a outro comando do Forja ("Lista os boilerplates (project:new
331
+ * --template)" na célula de `project:templates`).
332
+ *
333
+ * Comentário de fim de linha é cortado: ali a prosa cita flag de *outro* comando.
334
+ *
335
+ * Leitura pura — quem decide se a flag existe é o check `docs-flags`, contra o registry.
336
+ * @returns {{ file: string, line: number, command: string, flag: string, mentions: string[] }[]}
337
+ */
338
+ export function scanFlags(env) {
339
+ const hits = [];
340
+ for (const rel of docFiles(env)) {
341
+ const src = safeRead(env, path.join(env.root, rel));
342
+ if (src == null)
343
+ continue;
344
+ src.split('\n').forEach((raw, i) => {
345
+ const text = executablePart(String(raw));
346
+ const invoked = [];
347
+ for (const m of text.matchAll(COMMAND_RE))
348
+ invoked.push({ at: m.index ?? 0, name: m[1] });
349
+ if (invoked.length === 0)
350
+ return;
351
+ const mentions = [...new Set([...text.matchAll(MENTION_RE)].map((m) => m[1]))];
352
+ for (const m of text.matchAll(FLAG_RE)) {
353
+ const at = m.index ?? 0;
354
+ const owner = [...invoked].reverse().find((c) => c.at < at);
355
+ if (!owner)
356
+ continue;
357
+ hits.push({ file: rel, line: i + 1, command: owner.name, flag: m[1], mentions });
358
+ }
359
+ });
360
+ }
361
+ return hits;
362
+ }
363
+ /**
364
+ * Contagens de skills afirmadas na doc (`# 34 skills …`), para comparar com as pastas reais de
365
+ * `templates/project/skills/`. Leitura pura — o juízo é do check `docs-skills-count`.
366
+ * @returns {{ file: string, line: number, claimed: number }[]}
367
+ */
368
+ export function scanSkillCounts(env) {
369
+ const hits = [];
370
+ for (const rel of docFiles(env)) {
371
+ const src = safeRead(env, path.join(env.root, rel));
372
+ if (src == null)
373
+ continue;
374
+ src.split('\n').forEach((text, i) => {
375
+ for (const m of String(text).matchAll(SKILL_COUNT_RE)) {
376
+ hits.push({ file: rel, line: i + 1, claimed: Number(m[1]) });
377
+ }
378
+ });
379
+ }
380
+ return hits;
381
+ }