trackfw 2.4.1 → 2.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.4.1",
+  "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/discover.js

@@ -330,14 +330,19 @@ cmd.action((opts) => {
   console.log(`\nGovernance Score: ${r.governanceScore}/100`);
 
   if (opts.init) {
-    const yaml = generateYAML(r);
-    fs.writeFileSync('trackfw.yaml', yaml, 'utf8');
-    console.log('\n✓ trackfw.yaml generated');
-    try {
-      installGates(r, cwd);
-      console.log('✓ governance gates installed');
-    } catch (e) {
-      console.log(`⚠ gates install partial: ${e.message}`);
+    const yamlPath = path.join(cwd, 'trackfw.yaml');
+    if (fs.existsSync(yamlPath)) {
+      console.log('\n⚠ trackfw.yaml already exists — skipping (remove it first to regenerate)');
+    } else {
+      const yaml = generateYAML(r);
+      fs.writeFileSync(yamlPath, yaml, 'utf8');
+      console.log('\n✓ trackfw.yaml generated');
+      try {
+        installGates(r, cwd);
+        console.log('✓ governance gates installed');
+      } catch (e) {
+        console.log(`⚠ gates install partial: ${e.message}`);
+      }
     }
   }
 

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,15 +1,35 @@
 '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')
 cmd.description(t('validate.description'))
-cmd.action(async () => {
+cmd.option('--json', 'output result as JSON')
+cmd.action(async (options) => {
   const { violations, warnings } = await validate()
+  const lenient = isLenient()
+  const mode = lenient ? 'lenient' : 'strict'
+  const exitCode = violations.length > 0 ? 1 : 0
+
+  if (options.json) {
+    const output = {
+      summary: {
+        violations: violations.length,
+        warnings: warnings.length,
+        mode,
+        exit_code: exitCode,
+      },
+      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)
+    return
+  }
 
   // Informar usuário sobre modo lenient
-  if (isLenient()) {
+  if (lenient) {
     const until = lenientUntilDate()
     if (until) {
       console.log(`[LENIENT MODE] ${t('validate.lenient_mode', { date: until })}`)

package/src/config/index.js

@@ -15,6 +15,7 @@ function defaults() {
     wipLimit: 1,
     wipBySquad: false,
     requireReqInCommit: false,
+    traceIdField: '',
     // NOVOS campos:
     linkFields: {
       req:     ['REQ:'],
@@ -165,8 +166,8 @@ function parse(content, cfg) {
 
     switch (key) {
       case 'adr_dirs':              inAdrDirs = true; adrDirs = []; break;
-      case 'req_dir':               cfg.reqDir = val; break;
-      case 'roadmap_dir':           cfg.roadmapDir = val; break;
+      case 'req_dir':               cfg.reqDir = val.replace(/^["']|["']$/g, ''); break;
+      case 'roadmap_dir':           cfg.roadmapDir = val.replace(/^["']|["']$/g, ''); break;
       case 'roadmap_namespacing':   cfg.roadmapNamespacing = val; break;
       case 'agents':                inAgents = true; agents = []; break;
       case 'governance_mode':       cfg.governanceMode = val; break;
@@ -174,6 +175,7 @@ function parse(content, cfg) {
       case 'wip_limit':             { const n = parseInt(val, 10); if (n > 0) cfg.wipLimit = n; break; }
       case 'wip_by_squad':          cfg.wipBySquad = val === 'true'; break;
       case 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
+      case 'trace_id_field':        cfg.traceIdField = val.replace(/^["']|["']$/g, ''); break;
       case 'link_fields':           inLinkFields = true; break;
       case 'acceptance_markers':    inAcceptanceMarkers = true; acceptanceMarkers = []; break;
       case 'rules':                 inRules = true; rules = {}; break;

package/src/validator/index.js

@@ -4,6 +4,7 @@ const fs = require('fs')
 const path = require('path')
 const { execSync } = require('child_process')
 const config = require('../config')
+const { checkTraceIds } = require('./traceid')
 
 const STALE_WIP_DAYS = 7
 
@@ -699,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()
@@ -707,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) }
   }
 }
 
@@ -744,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)
@@ -760,13 +784,25 @@ 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) {
+    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 }
 }
@@ -910,4 +946,7 @@ module.exports = {
   contentHasMarker,
   ruleSeverity,
   applyRule,
+  // novas funções ML-1B (v2.5.1)
+  getItemMeta,
+  resetMeta,
 }

package/src/validator/traceid.js

@@ -0,0 +1,142 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// ESTADOS reconhecidos para REQs e Roadmaps (baseado na pasta onde o arquivo reside)
+const KNOWN_STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+
+// extractFrontmatterField extrai o valor de um campo do frontmatter YAML simples de um arquivo .md.
+// Retorna string vazia se o campo não for encontrado ou o arquivo não tiver frontmatter.
+function extractFrontmatterField(filePath, fieldName) {
+  let content
+  try { content = fs.readFileSync(filePath, 'utf8') } catch (_) { return '' }
+  if (!content.startsWith('---')) return ''
+  const end = content.indexOf('\n---', 3)
+  const block = end > 0 ? content.slice(3, end) : content.slice(3)
+  for (const line of block.split('\n')) {
+    const trimmed = line.trim()
+    const prefix = fieldName + ':'
+    if (trimmed.startsWith(prefix)) {
+      return trimmed.slice(prefix.length).trim().replace(/^["']|["']$/g, '')
+    }
+  }
+  return ''
+}
+
+// stateFromPath extrai o estado (wip/backlog/blocked/done/abandoned) a partir do caminho do arquivo.
+// Percorre os segmentos de path de trás para frente e retorna o primeiro que for um estado reconhecido.
+// Retorna '' se nenhum segmento for reconhecido.
+function stateFromPath(filePath) {
+  const segments = filePath.split(path.sep)
+  for (let i = segments.length - 2; i >= 0; i--) {
+    if (KNOWN_STATES.includes(segments[i])) return segments[i]
+  }
+  return ''
+}
+
+// walkMd retorna array de caminhos absolutos de todos .md recursivamente dentro de dir.
+function walkMd(dir) {
+  const results = []
+  function walk(d) {
+    let entries
+    try { entries = fs.readdirSync(d) } catch (_) { return }
+    for (const name of entries) {
+      const full = path.join(d, name)
+      try {
+        if (fs.statSync(full).isDirectory()) { walk(full) }
+        else if (name.endsWith('.md')) { results.push(full) }
+      } catch (_) {}
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// checkTraceIds verifica a consistência bidirecional de req_id entre REQs e Roadmaps.
+// Parâmetros:
+//   reqDir     — caminho absoluto ou relativo do diretório de REQs
+//   roadmapDir — caminho absoluto ou relativo do diretório de Roadmaps
+//   fieldName  — nome do campo de frontmatter que contém o trace ID (ex: 'req_id')
+// Retorna array de strings de violation.
+function checkTraceIds(reqDir, roadmapDir, fieldName) {
+  if (!fieldName) return []
+
+  // --- Indexar REQs ---
+  // reqIndex: Map<traceId, [{file, state}]>
+  const reqIndex = new Map()
+  for (const filePath of walkMd(reqDir)) {
+    const traceId = extractFrontmatterField(filePath, fieldName)
+    if (!traceId) continue
+    const state = stateFromPath(filePath)
+    if (!reqIndex.has(traceId)) reqIndex.set(traceId, [])
+    reqIndex.get(traceId).push({ file: path.basename(filePath), state })
+  }
+
+  // --- Indexar Roadmaps ---
+  // roadmapIndex: Map<traceId, [{file, state}]>
+  const roadmapIndex = new Map()
+  for (const filePath of walkMd(roadmapDir)) {
+    const traceId = extractFrontmatterField(filePath, fieldName)
+    if (!traceId) continue
+    const state = stateFromPath(filePath)
+    if (!roadmapIndex.has(traceId)) roadmapIndex.set(traceId, [])
+    roadmapIndex.get(traceId).push({ file: path.basename(filePath), state })
+  }
+
+  const violations = []
+
+  // traceid_duplicate_req: mesmo req_id em >1 REQ
+  for (const [traceId, entries] of reqIndex.entries()) {
+    if (entries.length > 1) {
+      const files = entries.map(e => e.file).join(', ')
+      violations.push(`traceid_duplicate_req: req_id "${traceId}" appears in ${entries.length} REQs: ${files}`)
+    }
+  }
+
+  // traceid_duplicate_roadmap: mesmo req_id em >1 Roadmap
+  for (const [traceId, entries] of roadmapIndex.entries()) {
+    if (entries.length > 1) {
+      const files = entries.map(e => e.file).join(', ')
+      violations.push(`traceid_duplicate_roadmap: req_id "${traceId}" appears in ${entries.length} Roadmaps: ${files}`)
+    }
+  }
+
+  // traceid_orphan_roadmap: Roadmap com req_id sem REQ correspondente
+  for (const [traceId, entries] of roadmapIndex.entries()) {
+    if (!reqIndex.has(traceId)) {
+      for (const e of entries) {
+        violations.push(`traceid_orphan_roadmap: roadmap "${e.file}" has req_id "${traceId}" but no matching REQ`)
+      }
+    }
+  }
+
+  // traceid_orphan_req: REQ com req_id sem Roadmap correspondente
+  for (const [traceId, entries] of reqIndex.entries()) {
+    if (!roadmapIndex.has(traceId)) {
+      for (const e of entries) {
+        violations.push(`traceid_orphan_req: req "${e.file}" has req_id "${traceId}" but no matching Roadmap`)
+      }
+    }
+  }
+
+  // traceid_state_mismatch: REQ e Roadmap com mesmo req_id em estados diferentes
+  for (const [traceId, reqEntries] of reqIndex.entries()) {
+    if (!roadmapIndex.has(traceId)) continue
+    const roadmapEntries = roadmapIndex.get(traceId)
+    // Comparar todos os pares (normalmente 1x1, mas suporta duplicados já reportados acima)
+    for (const req of reqEntries) {
+      for (const rm of roadmapEntries) {
+        if (req.state && rm.state && req.state !== rm.state) {
+          violations.push(
+            `traceid_state_mismatch: req_id "${traceId}" — REQ "${req.file}" is in "${req.state}" but Roadmap "${rm.file}" is in "${rm.state}"`
+          )
+        }
+      }
+    }
+  }
+
+  return violations
+}
+
+module.exports = { checkTraceIds, extractFrontmatterField, stateFromPath }