trackfw 2.4.0 → 2.5.0

package/package.json

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

@@ -5,11 +5,31 @@ 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 => ({ message: v })),
+      warnings: warnings.map(w => ({ message: w })),
+    }
+    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:'],
@@ -126,7 +127,7 @@ function parse(content, cfg) {
         const colonIdx = line.indexOf(':');
         if (colonIdx > 0) {
           const k = line.slice(0, colonIdx).trim();
-          const v = line.slice(colonIdx + 1).trim();
+          const v = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
           if (k) rules[k] = v;
         }
         continue;
@@ -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
 
@@ -768,6 +769,12 @@ async function validateUnfiltered() {
   // warnings diretos do WIP limit (não configuráveis)
   warnings.push(...wipLimitResult.warnings)
 
+  // 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))
+  }
+
   return { violations, warnings }
 }
 
@@ -777,11 +784,13 @@ async function validate() {
   const result = await validateUnfiltered()
   let { violations, warnings } = result
 
-  // Ratchet: filtrar violations que já estavam no baseline
+  // Ratchet: filtrar violations e warnings que já estavam no baseline
   const baseline = loadBaseline()
   if (baseline) {
     const baselineSet = new Set(baseline.violations || [])
     violations = violations.filter(v => !baselineSet.has(v))
+    const baselineWarnSet = new Set(baseline.warnings || [])
+    warnings = warnings.filter(w => !baselineWarnSet.has(w))
   }
 
   // Modo lenient: mover violations para warnings, exit code 0

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 }