trackfw 1.0.3 → 1.0.4

package/src/validator/index.js

@@ -0,0 +1,340 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const STALE_WIP_DAYS = 7
+
+// listDir retorna array de nomes de arquivo (não-diretórios) em dir.
+// Retorna [] se o diretório não existir.
+function listDir(dir) {
+  try {
+    return fs.readdirSync(dir).filter(name => {
+      try {
+        return !fs.statSync(path.join(dir, name)).isDirectory()
+      } catch (_) {
+        return false
+      }
+    })
+  } catch (_) {
+    return []
+  }
+}
+
+// parseBlockedADRs extrai basenames de ADRs da seção "## Blocked by ADRs" de um arquivo REQ.
+function parseBlockedADRs(filePath) {
+  let content
+  try {
+    content = fs.readFileSync(filePath, 'utf8')
+  } catch (_) {
+    return []
+  }
+  const lines = content.split('\n')
+  const adrs = []
+  let inSection = false
+  for (const line of lines) {
+    if (line === '## Blocked by ADRs') {
+      inSection = true
+      continue
+    }
+    if (inSection) {
+      if (line.startsWith('## ')) break
+      if (line.startsWith('- ')) {
+        const item = line.slice(2).trim()
+        const parts = item.split(/\s+/)
+        if (parts.length > 0 && parts[0].endsWith('.md')) {
+          adrs.push(parts[0])
+        }
+      }
+    }
+  }
+  return adrs
+}
+
+// adrIsDraft verifica se docs/adr/<basename> contém "Status: Draft".
+function adrIsDraft(basename) {
+  try {
+    const content = fs.readFileSync(path.join('docs', 'adr', basename), 'utf8')
+    return content.includes('Status: Draft')
+  } catch (_) {
+    return false
+  }
+}
+
+// validateWIPHasREQ — roadmaps em docs/roadmaps/wip/ sem "REQ:" no conteúdo → violation
+function validateWIPHasREQ() {
+  const entries = listDir('docs/roadmaps/wip')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/roadmaps/wip', name), 'utf8')
+      if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+        violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
+      }
+    } catch (_) {
+      // ignorar erro de leitura
+    }
+  }
+  return violations
+}
+
+// validateREQsHaveADR — REQs em docs/req/ sem "ADR:" no conteúdo → violation
+function validateREQsHaveADR() {
+  const entries = listDir('docs/req')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/req', name), 'utf8')
+      if (!content.includes('ADR:') || content.includes('ADR: \n')) {
+        violations.push(`req "${name}" has no linked ADR`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateBlockedHasREQ — roadmaps em docs/roadmaps/blocked/ sem "REQ:" → violation
+function validateBlockedHasREQ() {
+  const entries = listDir('docs/roadmaps/blocked')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/roadmaps/blocked', name), 'utf8')
+      if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+        violations.push(`roadmap "${name}" is in blocked but has no linked REQ`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateREQsHaveRoadmap — REQs sem "Roadmap:" → violation
+function validateREQsHaveRoadmap() {
+  const entries = listDir('docs/req')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/req', name), 'utf8')
+      if (!content.includes('Roadmap:') || content.includes('Roadmap: \n')) {
+        violations.push(`req "${name}" has no linked Roadmap`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateADRsAreReferenced — ADRs em docs/adr/ não referenciados em nenhuma REQ → violation
+function validateADRsAreReferenced() {
+  const adrs = listDir('docs/adr')
+  const reqEntries = listDir('docs/req')
+
+  let combined = ''
+  for (const name of reqEntries) {
+    try {
+      combined += fs.readFileSync(path.join('docs/req', name), 'utf8')
+    } catch (_) {
+      // ignorar
+    }
+  }
+
+  const violations = []
+  for (const adr of adrs) {
+    if (!combined.includes(adr)) {
+      violations.push(`adr "${adr}" is not referenced by any REQ`)
+    }
+  }
+  return violations
+}
+
+// validateWIPHasAcceptanceCriteria — roadmaps wip sem bloco de critérios de aceite → violation
+function validateWIPHasAcceptanceCriteria() {
+  const entries = listDir('docs/roadmaps/wip')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/roadmaps/wip', name), 'utf8')
+      const hasBlock =
+        content.includes('## Acceptance Criteria') ||
+        content.includes('## Critérios de Aceite') ||
+        content.includes('acceptance criteria') ||
+        content.includes('Acceptance Criteria:')
+      if (!hasBlock) {
+        violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateSingleWIP — mais de 1 roadmap em wip → warning
+function validateSingleWIP() {
+  const entries = listDir('docs/roadmaps/wip')
+  if (entries.length > 1) {
+    return [`${entries.length} roadmaps in wip/ (recommended: keep only 1 active at a time)`]
+  }
+  return []
+}
+
+// validateStaleWIP — roadmaps wip com mtime >= 7 dias → warning
+function validateStaleWIP() {
+  let files = []
+  try {
+    files = fs.readdirSync('docs/roadmaps/wip')
+      .filter(f => f.endsWith('.md'))
+      .map(f => path.join('docs/roadmaps/wip', f))
+  } catch (_) {
+    return []
+  }
+
+  const warnings = []
+  const now = Date.now()
+  for (const filePath of files) {
+    try {
+      const stat = fs.statSync(filePath)
+      const ageMs = now - stat.mtimeMs
+      const days = Math.floor(ageMs / (1000 * 60 * 60 * 24))
+      if (days >= STALE_WIP_DAYS) {
+        const lastModified = stat.mtime.toISOString().slice(0, 10)
+        const basename = path.basename(filePath)
+        warnings.push(
+          `roadmap/wip/${basename} has been in WIP for ${days} days (last modified ${lastModified})`
+        )
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return warnings
+}
+
+// validateREQsNotBlockedByDraftADRs — REQs Open com ADRs Draft na seção "## Blocked by ADRs" → violation
+function validateREQsNotBlockedByDraftADRs() {
+  const entries = listDir('docs/req')
+  const violations = []
+  for (const name of entries) {
+    const filePath = path.join('docs/req', name)
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch (_) {
+      continue
+    }
+    if (!content.includes('Status: Open')) continue
+
+    const blockedADRs = parseBlockedADRs(filePath)
+    for (const adrBasename of blockedADRs) {
+      if (adrIsDraft(adrBasename)) {
+        violations.push(`REQ ${name} is blocked by Draft ADR: ${adrBasename}`)
+      }
+    }
+  }
+  return violations
+}
+
+// blockedREQs retorna mapa de reqBasename → [adrBasenames Draft] para uso em getStatus()
+function blockedREQs() {
+  const entries = listDir('docs/req')
+  const result = {}
+  for (const name of entries) {
+    const filePath = path.join('docs/req', name)
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch (_) {
+      continue
+    }
+    if (!content.includes('Status: Open')) continue
+
+    const adrNames = parseBlockedADRs(filePath)
+    const draftADRs = adrNames.filter(a => adrIsDraft(a))
+    if (draftADRs.length > 0) {
+      result[name] = draftADRs
+    }
+  }
+  return result
+}
+
+// validate executa todas as validações e retorna { violations, warnings }
+async function validate() {
+  const violations = [
+    ...validateWIPHasREQ(),
+    ...validateREQsHaveADR(),
+    ...validateBlockedHasREQ(),
+    ...validateREQsHaveRoadmap(),
+    ...validateADRsAreReferenced(),
+    ...validateWIPHasAcceptanceCriteria(),
+    ...validateREQsNotBlockedByDraftADRs(),
+  ]
+  const warnings = [
+    ...validateSingleWIP(),
+    ...validateStaleWIP(),
+  ]
+  return { violations, warnings }
+}
+
+// getStatus retorna string formatada com o status de governança do projeto
+async function getStatus() {
+  const wip = listDir('docs/roadmaps/wip')
+  const blocked = listDir('docs/roadmaps/blocked')
+  const done = listDir('docs/roadmaps/done')
+
+  let out = ''
+  out += '── trackfw status ──────────────────────\n'
+
+  out += `\n🔄 WIP (${wip.length})\n`
+  for (const f of wip) out += `   ${f}\n`
+
+  out += `\n❌ Blocked (${blocked.length})\n`
+  for (const f of blocked) out += `   ${f}\n`
+
+  const staleWIPs = validateStaleWIP()
+  if (staleWIPs.length > 0) {
+    out += `\n⚠  Stale WIP (${staleWIPs.length})\n`
+    for (const w of staleWIPs) out += `   ${w}\n`
+  }
+
+  const blockedByDraft = blockedREQs()
+  const blockedKeys = Object.keys(blockedByDraft)
+  if (blockedKeys.length > 0) {
+    out += `\n⏳ REQs blocked by Draft ADRs (${blockedKeys.length})\n`
+    for (const reqFile of blockedKeys) {
+      out += `   ${reqFile}\n`
+      for (const adr of blockedByDraft[reqFile]) {
+        out += `     → ${adr} (Draft)\n`
+      }
+    }
+  }
+
+  out += `\n✅ Done (last 5)\n`
+  const last5 = done.length > 5 ? done.slice(done.length - 5) : done
+  for (const f of last5) out += `   ${f}\n`
+
+  out += '\n────────────────────────────────────────\n'
+  return out
+}
+
+module.exports = {
+  validate,
+  getStatus,
+  // exportadas para testes unitários
+  validateWIPHasREQ,
+  validateREQsHaveADR,
+  validateBlockedHasREQ,
+  validateREQsHaveRoadmap,
+  validateADRsAreReferenced,
+  validateWIPHasAcceptanceCriteria,
+  validateSingleWIP,
+  validateStaleWIP,
+  validateREQsNotBlockedByDraftADRs,
+  parseBlockedADRs,
+  adrIsDraft,
+  listDir,
+}

package/bin/README.md

@@ -1,301 +0,0 @@
-# trackfw
-
-> Governed software delivery — ADR → REQ → ROADMAP → backlog / wip / done
-
-[![Release](https://img.shields.io/github/v/release/kgsaran/trackfw)](https://github.com/kgsaran/trackfw/releases/latest)
-[![Go](https://img.shields.io/badge/go-1.21+-00ADD8?logo=go)](go.mod)
-[![License](https://img.shields.io/github/license/kgsaran/trackfw)](LICENSE)
-
-**trackfw** is an open-source CLI that enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.
-
-```
-ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
-```
-
-Every piece of work traces back to a decision. Every decision links to a requirement. Every requirement lands in a roadmap. No orphan work, no undocumented choices.
-
----
-
-## The problem
-
-Most teams accumulate technical debt not because they lack tools, but because they lack **governance traceability**. Decisions are made in Slack. Requirements live in someone's head. Roadmaps drift from what was actually shipped.
-
-- **ADR tools** manage decision records, but don't connect them to delivery.
-- **Kanban tools** track tasks, but don't enforce that tasks are backed by a decision.
-- **CI tools** validate code, but don't validate governance.
-
-trackfw closes the loop — connective tissue between *why*, *what*, and *when*.
-
----
-
-## Demo
-
-![trackfw demo](docs/demo.gif)
-
-```bash
-$ trackfw req new "Login screen"
-
-  ? Describe what you want to build  Login screen for the application
-  ? Motivation                       Users need to authenticate to access the system
-
-  Detected domains: authentication, ui
-
-  ? How will users authenticate?
-  > Local login (email + password)
-    SSO (Google, Azure AD, Okta...)
-    Not decided yet  ← generates ADR draft
-
-  ? Is there an existing UI framework or design system?
-    Yes, already chosen
-  > No, need to choose a UI framework  ← generates ADR draft
-
-ADR drafts created:
-  → ADR-2026-06-12-authentication-strategy.md
-  → ADR-2026-06-12-ui-framework.md
-
-Resolve these ADRs (set Status: Accepted) before creating a roadmap.
-created docs/req/REQ-2026-06-12-login-screen.md
-```
-
----
-
-## Installation
-
-### macOS / Linux — curl
-
-```bash
-curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
-```
-
-### Homebrew
-
-```bash
-brew install kgsaran/tap/trackfw
-```
-
-### Go
-
-```bash
-go install github.com/kgsaran/trackfw/cmd/trackfw@latest
-```
-
-### npm
-
-```bash
-npm install -g trackfw
-```
-
-### pip
-
-```bash
-pip install trackfw
-```
-
----
-
-## Quick start
-
-```bash
-# 1. Set up governance in your project (interactive wizard)
-trackfw init
-
-# 2. Document an architectural decision
-trackfw adr new "Use PostgreSQL as primary database"
-
-# 3. Create a requirement — wizard detects domains and proposes ADR drafts
-trackfw req new "User authentication"
-
-# 4. Once ADRs are accepted, plan the work
-trackfw roadmap new "Auth service"
-
-# 5. Check governance health
-trackfw validate
-
-# 6. See what is in flight
-trackfw status
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---|---|
-| `trackfw init` | Interactive wizard — scaffolds governance + AI integrations |
-| `trackfw adr new "title"` | Create a new Architecture Decision Record |
-| `trackfw adr list` | List all ADRs with status |
-| `trackfw req new "title"` | Create a REQ with guided ADR discovery |
-| `trackfw req list` | List all REQs with status |
-| `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
-| `trackfw roadmap move <name> <state>` | Move roadmap between states |
-| `trackfw roadmap list` | List all roadmaps grouped by state |
-| `trackfw validate` | Check governance consistency (use as CI gate) |
-| `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
-| `trackfw agents` | Install Claude Code subagents |
-| `trackfw gemini` | Install Gemini CLI skills and commands |
-| `trackfw cursor` | Install Cursor rules |
-| `trackfw copilot` | Install GitHub Copilot instructions |
-| `trackfw windsurf` | Install Windsurf rules and workflows |
-| `trackfw amazonq` | Install Amazon Q Developer rules |
-| `trackfw version` | Print version |
-
----
-
-## Governance chain
-
-| Layer | Artifact | Purpose |
-|---|---|---|
-| Decide | `ADR` | Document the *why* behind a technical decision |
-| Specify | `REQ` | Define *what* needs to be delivered, linked to an ADR |
-| Plan | `ROADMAP` | Break the requirement into microbatches with acceptance criteria |
-| Execute | `backlog → wip → done` | Folder position is the source of truth |
-
-### Roadmap states
-
-```
-docs/roadmaps/
-├── backlog/     queued, not started
-├── wip/         actively being worked on (one at a time)
-├── blocked/     waiting on a dependency or decision
-├── done/        completed and validated
-└── abandoned/   discontinued — reason required in file
-```
-
-Moving a file between folders **is** the state transition. No database, no API.
-
----
-
-## REQ-driven ADR discovery
-
-When you run `trackfw req new`, the wizard analyzes your intent and asks targeted questions for each detected domain — authentication, UI, persistence, API, deploy, events. Unanswered architectural decisions become ADR drafts automatically.
-
-```
-trackfw req new "checkout flow with payment integration"
-```
-
-Detected domains: **persistence**, **api**, **events**
-
-Questions asked:
-- Which database engine will be used? → *Not decided yet* → `ADR: database-engine (Draft)`
-- Which API protocol will be used? → *REST (already decided)* → no ADR
-- Which event broker will be used? → *Not decided yet* → `ADR: event-broker (Draft)`
-
-The REQ is linked to its blocking ADRs. `trackfw validate` enforces that no roadmap is created until every linked ADR reaches `Accepted` status.
-
-This is the difference between experienced architects (who know which decisions to make) and everyone else — trackfw brings the architectural checklist to the requirement.
-
----
-
-## `trackfw validate` — governance gate
-
-```bash
-$ trackfw validate
-
-✗ REQ-2026-06-12-login-screen.md is blocked by Draft ADR: ADR-authentication-strategy.md
-✗ roadmap/wip/auth-service.md has no linked REQ
-⚠  2 roadmaps in wip/ (recommended: 1)
-
-2 violation(s) found
-```
-
-Designed to run as a **pre-commit hook** and a **CI quality gate**. `trackfw init` wires both automatically for your stack.
-
----
-
-## `trackfw status` — current state at a glance
-
-```bash
-$ trackfw status
-
-── trackfw status ──────────────────────
-
-🔄 WIP (1)
-   roadmap-auth-service.md
-
-❌ Blocked (0)
-
-⏳ REQs blocked by Draft ADRs (1)
-   REQ-2026-06-12-login-screen.md
-     → ADR-2026-06-12-authentication-strategy.md (Draft)
-
-✅ Done (last 5)
-   roadmap-user-profile.md
-   roadmap-db-setup.md
-```
-
----
-
-## AI assistant integration
-
-`trackfw init` asks which AI tools your team uses and installs native governance context for each. Commands can also be run independently.
-
-| Command | Installs | Format |
-|---|---|---|
-| `trackfw agents` | 10 subagents in `~/.claude/agents/` | Claude Code `.md` with frontmatter |
-| `trackfw gemini` | GEMINI.md + 10 skills + 3 commands | `~/.gemini/` + project root |
-| `trackfw cursor` | 10 rules in `.cursor/rules/` | `.mdc` with YAML frontmatter |
-| `trackfw copilot` | `copilot-instructions.md` + 10 instructions + 10 prompts | `.github/` |
-| `trackfw windsurf` | 10 rules + workflows in `.windsurf/` + global rules | Appends to `~/.codeium/windsurf/memories/` |
-| `trackfw amazonq` | 10 rules in `.amazonq/rules/` | Plain Markdown |
-
-Each installer is idempotent — running it twice never overwrites your customizations.
-
-The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
-
----
-
-## `trackfw init` — stack-aware scaffolding
-
-```
-? Project type?          Full-stack / Frontend / Backend / Governance only
-? Frontend stack?        React / Vue / Angular
-? Backend stack?         Go / Java / Node / Python
-? Package manager?       npm / pnpm / yarn / bun
-? Git hooks?             husky / lefthook / none
-? CI system?             GitHub Actions / GitLab CI / none
-? Which AI assistants?   Claude Code / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q
-```
-
-The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.
-
----
-
-## Design principles
-
-1. **Files are state** — folder position is the source of truth. No database, no lock-in.
-2. **Traceability is mandatory** — `validate` is a gate, not a suggestion.
-3. **Framework-agnostic, integration-aware** — governance never changes; generated artifacts adapt to your stack.
-4. **One active roadmap at a time** — parallel work without traceability is the root of most delivery chaos.
-5. **Human-readable, machine-parseable** — every artifact is a Markdown file with a predictable structure.
-6. **Guided, not prescriptive** — the wizard surfaces decisions you might not know to ask; it never blocks work unnecessarily.
-
----
-
-## What trackfw is not
-
-- Not a project management SaaS — no UI, no accounts, no cloud sync
-- Not a replacement for Git history — it complements, not duplicates
-- Not a task tracker — use GitHub Issues, Linear, or Jira for tasks; trackfw governs the *why*
-- Not opinionated about how you write code — only about how you document decisions
-
----
-
-## Contributing
-
-```bash
-git clone https://github.com/kgsaran/trackfw
-cd trackfw
-make build   # compiles to bin/trackfw
-make test    # go test ./...
-make lint    # go vet ./...
-```
-
-Generators are the stack-specific components — you can add support for a new stack without touching core logic. See `internal/generators/` for examples.
-
-Issues and pull requests welcome at [github.com/kgsaran/trackfw](https://github.com/kgsaran/trackfw).
-
----
-
-## License
-
-MIT — see [LICENSE](LICENSE)