docguard-cli 0.9.7__tar.gz → 0.9.8__tar.gz

docguard_cli-0.9.8/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Publish to npm + PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  # ── Run tests first ──
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Run Tests
+        run: npm test
+      - name: Guard (self-check)
+        run: node cli/docguard.mjs guard || [ $? -eq 2 ]
+
+  # ── Publish to npm ──
+  publish-npm:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Sync version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          npm version "$VERSION" --no-git-tag-version --allow-same-version
+          echo "Publishing version $VERSION"
+
+      - name: Publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # ── Publish to PyPI ──
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Sync version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          echo "Publishing version $VERSION"
+          grep 'version' pyproject.toml
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish
+        run: python -m twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

{docguard_cli-0.9.7 → docguard_cli-0.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.9.7
+Version: 0.9.8
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -46,6 +46,8 @@ Description-Content-Type: text/markdown
 - [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)
@@ -68,6 +70,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
@@ -359,6 +394,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
@@ -386,7 +459,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

{docguard_cli-0.9.7 → docguard_cli-0.9.8}/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

{docguard_cli-0.9.7 → docguard_cli-0.9.8}/SECURITY.md

@@ -4,15 +4,15 @@
 
 | Version | Supported |
 |---------|-----------|
-| 0.4.x   | ✅ Current |
-| < 0.4   | ❌ Not supported |
+| 0.9.x   | ✅ Current |
+| < 0.9   | ❌ Not supported |
 
 ## Reporting a Vulnerability
 
 If you discover a security vulnerability in DocGuard, please report it responsibly:
 
 1. **Do NOT** open a public GitHub issue for security vulnerabilities
-2. **Email** the maintainers directly (see repository contact info)
+2. **Report via** [GitHub Security Advisories](https://github.com/raccioly/docguard/security/advisories/new) (private, preferred)
 3. Include:
    - Description of the vulnerability
    - Steps to reproduce

{docguard_cli-0.9.7 → docguard_cli-0.9.8}/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}"`

docguard_cli-0.9.8/examples/01-express-api/README.md

@@ -0,0 +1,3 @@
+# Express API
+
+A simple REST API.

docguard_cli-0.9.8/examples/01-express-api/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "express-api-example",
+  "version": "1.0.0",
+  "description": "A simple Express API — intentionally undocumented for DocGuard demo",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "express": "^4.18.0"
+  }
+}

docguard_cli-0.9.8/examples/01-express-api/server.js

@@ -0,0 +1,37 @@
+const express = require('express');
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+app.use(express.json());
+
+// Health check
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', uptime: process.uptime() });
+});
+
+// List users
+app.get('/api/users', (req, res) => {
+  res.json([
+    { id: 1, name: 'Alice', role: 'admin' },
+    { id: 2, name: 'Bob', role: 'user' },
+  ]);
+});
+
+// Create user
+app.post('/api/users', (req, res) => {
+  const { name, role } = req.body;
+  if (!name) return res.status(400).json({ error: 'Name is required' });
+  res.status(201).json({ id: Date.now(), name, role: role || 'user' });
+});
+
+// Get user by ID
+app.get('/api/users/:id', (req, res) => {
+  const id = parseInt(req.params.id);
+  if (id === 1) return res.json({ id: 1, name: 'Alice', role: 'admin' });
+  if (id === 2) return res.json({ id: 2, name: 'Bob', role: 'user' });
+  res.status(404).json({ error: 'User not found' });
+});
+
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});

docguard_cli-0.9.8/examples/02-python-flask/README.md

@@ -0,0 +1,24 @@
+# Product Catalog API
+
+A Flask-based REST API for managing products. Provides **3 endpoints** for product listing and retrieval.
+
+## Stack
+
+- Python 3.10+
+- Flask
+- **SQLite** for local storage
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /health | Health check |
+| GET | /api/products | List all products |
+| GET | /api/products/:id | Get product by ID |
+
+## Running
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

docguard_cli-0.9.8/examples/02-python-flask/app.py

@@ -0,0 +1,50 @@
+from flask import Flask, request, jsonify
+import os
+
+app = Flask(__name__)
+
+# Database connection — uses PostgreSQL via psycopg2
+DATABASE_URL = os.environ.get('DATABASE_URL', 'postgresql://localhost:5432/myapp')
+
+
+@app.route('/health')
+def health():
+    return jsonify({'status': 'healthy', 'database': 'postgresql'})
+
+
+@app.route('/api/products')
+def list_products():
+    """List all products with optional category filter."""
+    category = request.args.get('category')
+    return jsonify([
+        {'id': 1, 'name': 'Widget', 'price': 9.99, 'category': 'tools'},
+        {'id': 2, 'name': 'Gadget', 'price': 19.99, 'category': 'electronics'},
+    ])
+
+
+@app.route('/api/products/<int:product_id>')
+def get_product(product_id):
+    """Get a single product by ID."""
+    return jsonify({'id': product_id, 'name': 'Widget', 'price': 9.99})
+
+
+@app.route('/api/products', methods=['POST'])
+def create_product():
+    """Create a new product."""
+    data = request.get_json()
+    if not data or 'name' not in data:
+        return jsonify({'error': 'Product name is required'}), 400
+    return jsonify({'id': 100, **data}), 201
+
+
+@app.route('/api/orders', methods=['POST'])
+def create_order():
+    """Place a new order — with inventory check."""
+    data = request.get_json()
+    if not data or 'product_id' not in data:
+        return jsonify({'error': 'Product ID is required'}), 400
+    return jsonify({'order_id': 500, 'status': 'confirmed'}), 201
+
+
+if __name__ == '__main__':
+    app.run(debug=True, port=5000)

docguard_cli-0.9.8/examples/02-python-flask/docs-canonical/ARCHITECTURE.md

@@ -0,0 +1,26 @@
+# Architecture
+
+## System Overview
+
+Product Catalog API — a simple Flask application.
+
+## Tech Stack
+
+- **Runtime**: Python 3.10+
+- **Framework**: Flask
+- **Database**: SQLite (local development)
+- **Deployment**: Docker
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| app.py | Main Flask application |
+| models.py | Database models |
+
+## Data Flow
+
+1. Client sends HTTP request
+2. Flask routes to handler
+3. Handler queries SQLite database
+4. Response returned as JSON

docguard_cli-0.9.8/examples/02-python-flask/requirements.txt

@@ -0,0 +1 @@
+flask>=3.0

docguard_cli-0.9.8/examples/03-spec-kit-project/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [1.0.0] - 2026-03-15
+
+### Added
+- Task management CLI (add, list, done)
+- JSON file-based storage
+- Status filtering
+- CDD-compliant documentation

docguard_cli-0.9.8/examples/03-spec-kit-project/README.md

@@ -0,0 +1,35 @@
+# Task Tracker
+
+A lightweight task management CLI built with Canonical-Driven Development (CDD).
+
+## Quick Start
+
+```bash
+node src/index.js add "Review pull request"
+node src/index.js list
+node src/index.js done 1
+```
+
+## Features
+
+- Add, list, and complete tasks
+- JSON file-based storage
+- Status filtering (pending, done)
+
+## Documentation
+
+All canonical documentation lives in `docs-canonical/`:
+
+| Document | Purpose |
+|----------|---------|
+| ARCHITECTURE.md | System design and components |
+| TEST-SPEC.md | Test requirements and coverage |
+
+## CDD Compliance
+
+This project uses [DocGuard](https://github.com/raccioly/docguard) for documentation enforcement:
+
+```bash
+npx docguard-cli guard    # Validate docs
+npx docguard-cli score    # Check maturity
+```

docguard_cli-0.9.8/examples/03-spec-kit-project/docs-canonical/ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# Architecture
+
+## System Overview
+
+Task Tracker is a CLI application for managing tasks via a JSON file store.
+
+## Tech Stack
+
+- **Language**: JavaScript (Node.js 18+)
+- **Storage**: JSON file (`tasks.json`)
+- **Testing**: `node:test` (built-in)
+- **Dependencies**: Zero — pure Node.js built-ins only
+
+## Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| CLI Entry | `src/index.js` | Command parsing and dispatch |
+| Task Store | `tasks.json` | Persistent task storage |
+
+## Layer Boundaries
+
+```
+CLI Arguments → Command Dispatch → File I/O → JSON Storage
+```
+
+## Data Flow
+
+### Adding a Task
+1. User runs `node src/index.js add "Task title"`
+2. CLI parses command and arguments
+3. `addTask()` loads existing tasks from `tasks.json`
+4. New task appended with auto-incremented ID
+5. Tasks array saved back to `tasks.json`
+
+### Completing a Task
+1. User runs `node src/index.js done <id>`
+2. `completeTask()` loads tasks, finds by ID
+3. Status changed to `done`, timestamp added
+4. Updated array saved to file

docguard_cli-0.9.8/examples/03-spec-kit-project/docs-canonical/TEST-SPEC.md

@@ -0,0 +1,28 @@
+# Test Specification
+
+## Test Strategy
+
+All tests use Node.js built-in test runner (`node:test`).
+
+## Test Categories
+
+### Unit Tests
+
+| Test | File | What It Verifies |
+|------|------|-----------------|
+| Add task | `tests/basic.test.js` | Task creation with correct fields |
+| List tasks | `tests/basic.test.js` | Retrieval of all tasks |
+| Complete task | `tests/basic.test.js` | Status transition to done |
+
+### Integration Tests
+
+| Test | What It Verifies |
+|------|-----------------|
+| CLI add | Running `node src/index.js add` produces correct output |
+| CLI list | Running `node src/index.js list` shows tasks |
+
+## Running Tests
+
+```bash
+npm test
+```

docguard_cli-0.9.8/examples/03-spec-kit-project/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "task-tracker",
+  "version": "1.0.0",
+  "description": "A spec-driven task tracker built with CDD practices",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test tests/"
+  }
+}

docguard_cli-0.9.8/examples/03-spec-kit-project/src/index.js

@@ -0,0 +1,50 @@
+const { readFileSync, writeFileSync, existsSync } = require('fs');
+const { resolve } = require('path');
+
+const TASKS_FILE = resolve(__dirname, '../tasks.json');
+
+function loadTasks() {
+  if (!existsSync(TASKS_FILE)) return [];
+  return JSON.parse(readFileSync(TASKS_FILE, 'utf-8'));
+}
+
+function saveTasks(tasks) {
+  writeFileSync(TASKS_FILE, JSON.stringify(tasks, null, 2) + '\n', 'utf-8');
+}
+
+function addTask(title) {
+  const tasks = loadTasks();
+  const task = { id: tasks.length + 1, title, status: 'pending', created: new Date().toISOString() };
+  tasks.push(task);
+  saveTasks(tasks);
+  console.log(`Added: [${task.id}] ${title}`);
+}
+
+function listTasks(filter) {
+  const tasks = loadTasks();
+  const filtered = filter ? tasks.filter(t => t.status === filter) : tasks;
+  if (filtered.length === 0) return console.log('No tasks found.');
+  for (const t of filtered) {
+    const mark = t.status === 'done' ? '✅' : '⬜';
+    console.log(`  ${mark} [${t.id}] ${t.title}`);
+  }
+}
+
+function completeTask(id) {
+  const tasks = loadTasks();
+  const task = tasks.find(t => t.id === parseInt(id));
+  if (!task) return console.log(`Task ${id} not found.`);
+  task.status = 'done';
+  task.completed = new Date().toISOString();
+  saveTasks(tasks);
+  console.log(`Done: [${task.id}] ${task.title}`);
+}
+
+const [,, cmd, ...args] = process.argv;
+
+switch (cmd) {
+  case 'add':   addTask(args.join(' ')); break;
+  case 'list':  listTasks(args[0]); break;
+  case 'done':  completeTask(args[0]); break;
+  default:      console.log('Usage: node src/index.js <add|list|done> [args]');
+}