trackfw 2.5.0 → 2.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "CLI de governança para entrega de software: ADR → REQ → ROADMAP → kanban. Suporte nativo a agentes de IA (Claude Code, Gemini CLI, Cursor).",
   "keywords": [
     "cli",

package/src/commands/help.js

@@ -162,6 +162,48 @@ const configDocs = {
     description: 'Severidade: REQ bloqueada por ADR em rascunho.',
     example: 'rules:\n  blocked_by_draft_adr: warning',
     impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  trace_id_field: {
+    type: 'string',
+    default: '""',
+    description: 'Campo de frontmatter usado como trace ID para verificação bidirecional REQ↔Roadmap. Vazio desativa a verificação.',
+    example: 'trace_id_field: req_id',
+    impact: 'Quando configurado, ativa as regras traceid_* que garantem que toda REQ tem Roadmap correspondente e vice-versa.'
+  },
+  'rules.traceid_orphan_roadmap': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: Roadmap com trace ID sem REQ correspondente.',
+    example: 'rules:\n  traceid_orphan_roadmap: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.traceid_orphan_req': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: REQ com trace ID sem Roadmap correspondente.',
+    example: 'rules:\n  traceid_orphan_req: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.traceid_state_mismatch': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: REQ e Roadmap com mesmo trace ID em estados diferentes (ex: REQ em done, Roadmap em wip).',
+    example: 'rules:\n  traceid_state_mismatch: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.traceid_duplicate_req': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: mesmo trace ID aparece em mais de uma REQ.',
+    example: 'rules:\n  traceid_duplicate_req: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.traceid_duplicate_roadmap': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: mesmo trace ID aparece em mais de um Roadmap.',
+    example: 'rules:\n  traceid_duplicate_roadmap: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
   }
 }
 

package/src/commands/validate.js

@@ -1,6 +1,6 @@
 'use strict'
 const { Command } = require('commander')
-const { validate, isLenient, lenientUntilDate } = require('../validator')
+const { validate, isLenient, lenientUntilDate, getItemMeta } = require('../validator')
 const { t } = require('../i18n')
 
 const cmd = new Command('validate')
@@ -20,8 +20,8 @@ cmd.action(async (options) => {
         mode,
         exit_code: exitCode,
       },
-      violations: violations.map(v => ({ message: v })),
-      warnings: warnings.map(w => ({ message: w })),
+      violations: violations.map(v => { const m = getItemMeta(v); return { message: v, rule: m.rule, file: m.file } }),
+      warnings: warnings.map(w => { const m = getItemMeta(w); return { message: w, rule: m.rule, file: m.file } }),
     }
     console.log(JSON.stringify(output, null, 2))
     process.exit(exitCode)

package/src/validator/index.js

@@ -700,6 +700,27 @@ function validateFilenameUniqueness() {
   return violations
 }
 
+// _itemMeta: mapa de message → { rule, file } para enriquecer saída JSON.
+// Populado em applyRule e nos pushs diretos do validateUnfiltered.
+// Permanece em memória apenas durante a execução de uma chamada validate*.
+const _itemMeta = new Map()
+
+// _setMeta registra metadados de rule/file para uma mensagem.
+function _setMeta(msg, ruleName) {
+  const m = /"([^"]+)"/.exec(msg)
+  _itemMeta.set(msg, { rule: ruleName, file: m ? m[1] : '' })
+}
+
+// getItemMeta retorna { rule, file } para uma mensagem, ou { rule: '', file: '' } se ausente.
+function getItemMeta(msg) {
+  return _itemMeta.get(msg) || { rule: '', file: '' }
+}
+
+// resetMeta limpa o mapa entre execuções (usado internamente).
+function resetMeta() {
+  _itemMeta.clear()
+}
+
 // ruleSeverity retorna a severidade configurada para uma regra ('error'|'warning'|'off').
 function ruleSeverity(name) {
   const cfg = config.load()
@@ -708,14 +729,15 @@ function ruleSeverity(name) {
 
 // applyRule distribui msgs para violations ou warnings conforme a severidade configurada.
 // Se severidade for 'off', descarta silenciosamente.
+// Também popula _itemMeta com rule/file para cada mensagem aceita.
 function applyRule(ruleName, msgs, violations, warnings) {
   if (!msgs || msgs.length === 0) return
   const severity = ruleSeverity(ruleName)
   if (severity === 'off') return
   if (severity === 'warning') {
-    warnings.push(...msgs)
+    for (const msg of msgs) { _setMeta(msg, ruleName); warnings.push(msg) }
   } else {
-    violations.push(...msgs)
+    for (const msg of msgs) { _setMeta(msg, ruleName); violations.push(msg) }
   }
 }
 
@@ -745,11 +767,12 @@ function saveBaseline(violations, warnings) {
 
 // validateUnfiltered executa todas as validações e retorna { violations, warnings } sem ratchet.
 async function validateUnfiltered() {
+  resetMeta()
   const wipLimitResult = validateWIPLimit()
   const violations = []
   const warnings = []
 
-  // Regras com severidade configurável via applyRule
+  // Regras com severidade configurável via applyRule (popula _itemMeta automaticamente)
   applyRule('wip_has_req',          validateWIPHasREQ(),                   violations, warnings)
   applyRule('wip_acceptance',       validateWIPHasAcceptanceCriteria(),    violations, warnings)
   applyRule('wip_limit',            wipLimitResult.violations,             violations, warnings)
@@ -761,18 +784,24 @@ async function validateUnfiltered() {
   applyRule('blocked_by_draft_adr', validateREQsNotBlockedByDraftADRs(),  violations, warnings)
 
   // Regras diretas (sem configuração de severidade): violations sempre
-  violations.push(...validateREQsHaveADR())
-  violations.push(...validateBlockedHasREQ())
-  violations.push(...validateREQsHaveRoadmap())
-  violations.push(...validateFrontmatterPresence())
+  // Popular _itemMeta manualmente para manter rastreabilidade no JSON
+  for (const msg of validateREQsHaveADR())         { _setMeta(msg, 'req_has_adr');         violations.push(msg) }
+  for (const msg of validateBlockedHasREQ())        { _setMeta(msg, 'blocked_has_req');      violations.push(msg) }
+  for (const msg of validateREQsHaveRoadmap())      { _setMeta(msg, 'req_has_roadmap');      violations.push(msg) }
+  for (const msg of validateFrontmatterPresence())  { _setMeta(msg, 'frontmatter_presence'); violations.push(msg) }
 
   // warnings diretos do WIP limit (não configuráveis)
-  warnings.push(...wipLimitResult.warnings)
+  for (const msg of wipLimitResult.warnings) { _setMeta(msg, 'wip_limit'); warnings.push(msg) }
 
   // Verificação bidirecional de trace ID (somente se traceIdField configurado)
   const cfg = config.load()
   if (cfg.traceIdField) {
-    violations.push(...checkTraceIds(cfg.reqDir, cfg.roadmapDir, cfg.traceIdField))
+    for (const msg of checkTraceIds(cfg.reqDir, cfg.roadmapDir, cfg.traceIdField)) {
+      // O prefixo da mensagem traceid já carrega o nome da regra (ex: "traceid_orphan_roadmap: ...")
+      const ruleName = msg.split(':')[0].trim()
+      _setMeta(msg, ruleName)
+      violations.push(msg)
+    }
   }
 
   return { violations, warnings }
@@ -917,4 +946,7 @@ module.exports = {
   contentHasMarker,
   ruleSeverity,
   applyRule,
+  // novas funções ML-1B (v2.5.1)
+  getItemMeta,
+  resetMeta,
 }