docguard-cli 0.9.7 → 0.9.8

package/README.md

@@ -22,6 +22,8 @@
 - [Templates](#-templates)
 - [AI Agent Support](#-ai-agent-support)
 - [Slash Commands](#-slash-commands)
+- [Examples](#-examples)
+- [Testing](#-testing)
 - [CI/CD Integration](#%EF%B8%8F-cicd-integration)
 - [File Structure](#-file-structure)
 - [Configuration](#%EF%B8%8F-configuration)
@@ -44,6 +46,39 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
 
+### Architecture
+
+```mermaid
+graph TD
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (15)"]
+    Commands --> guard["guard"]
+    Commands --> generate["generate"]
+    Commands --> score["score"]
+    Commands --> diagnose["diagnose"]
+    Commands --> setup["setup wizard"]
+    Commands --> other["diff · init · fix · trace<br/>agents · hooks · badge · ci · watch"]
+
+    guard --> Validators["Validators (19)"]
+    generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
+    score --> Scoring["Weighted Scoring<br/>8 categories"]
+    diagnose --> Validators
+    diagnose --> AIPrompts["AI-Ready<br/>Fix Prompts"]
+
+    Validators --> Output["Output"]
+    Scanners --> Output
+    Scoring --> Output
+    Output --> Terminal["Terminal"]
+    Output --> JSON["JSON"]
+    Output --> Badge["Badge"]
+
+    style CLI fill:#2d5016,color:#fff
+    style Validators fill:#1a3a5c,color:#fff
+    style Scanners fill:#1a3a5c,color:#fff
+    style Output fill:#5c3a1a,color:#fff
+```
+
+> **Distribution**: Node.js core (npm) · Python wrapper (PyPI) · GitHub Action (`action.yml`) · Spec Kit Extension (ZIP)
+
 ---
 
 ## ⚡ Quick Start
@@ -335,6 +370,44 @@ For advanced users and CI/CD pipelines, DocGuard includes bash scripts with `--j
 
 ---
 
+## 📁 Examples
+
+Three real-world projects to see DocGuard in action:
+
+| Example | Scenario | What You'll See |
+|---------|----------|----------------|
+| [01-express-api](examples/01-express-api/) | Node.js API with **zero docs** | Cold-start: `generate` → instant coverage |
+| [02-python-flask](examples/02-python-flask/) | Python app with **drifted docs** | Drift detection: catch when docs lie |
+| [03-spec-kit-project](examples/03-spec-kit-project/) | Full CDD + Spec Kit | Gold standard: what maturity looks like |
+
+See [examples/README.md](examples/README.md) for step-by-step instructions.
+
+---
+
+## 🧪 Testing
+
+### Test Suite
+
+```bash
+npm test    # 33 tests across 18 describe blocks
+```
+
+Covers all 15 CLI commands, project type detection, compliance profiles, JSON output format, and help completeness.
+
+### CI Matrix
+
+| Node.js | OS | Status |
+|---------|-----|--------|
+| 18 | ubuntu-latest | ✅ |
+| 20 | ubuntu-latest | ✅ |
+| 22 | ubuntu-latest | ✅ |
+
+### Self-Validation (Dogfooding)
+
+DocGuard runs its own `guard`, `score`, `diff`, `diagnose`, and `badge` commands against itself in CI — ensuring the tool passes its own checks.
+
+---
+
 ## ⚙️ CI/CD Integration
 
 ### GitHub Actions
@@ -362,7 +435,7 @@ npx docguard-cli hooks --type pre-commit
 ### GitHub Marketplace
 
 ```yaml
-- uses: raccioly/docguard@v0.9.5
+- uses: raccioly/docguard@v0.9.7
   with:
     command: guard
     fail-on-warning: true

package/cli/validators/metadata-sync.mjs

@@ -40,6 +40,7 @@ export function validateMetadataSync(projectDir, config) {
   const vParts = currentVersion.split('.');
   const major = parseInt(vParts[0], 10);
   const minor = parseInt(vParts[1], 10);
+  const patch = parseInt(vParts[2], 10);
 
   // ── Check 1: extension.yml version sync ──
   const extFiles = findExtensionYmls(projectDir);
@@ -101,9 +102,15 @@ export function validateMetadataSync(projectDir, config) {
         const fParts = foundVersion.split('.');
         const fMajor = parseInt(fParts[0], 10);
         const fMinor = parseInt(fParts[1], 10);
+        const fPatch = parseInt(fParts[2], 10);
 
-        // Only flag if same major but older minor (same package, stale ref)
-        if (fMajor === major && fMinor < minor && foundVersion !== currentVersion) {
+        // Only flag if same major but older version (same package, stale ref)
+        const isOlder = fMajor === major && (
+          fMinor < minor ||
+          (fMinor === minor && fPatch < patch)
+        );
+
+        if (isOlder && foundVersion !== currentVersion) {
           total++;
           warnings.push(
             `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.9.7"
+  version: "0.9.8"
   description: "Canonical-Driven Development enforcement with enterprise-grade AI skills. 19 automated validators, structured research workflows, quality validation loops, and spec-kit integration hooks. Zero dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {