docguard-cli 0.28.0 → 0.30.0

package/templates/ci/gitlab-component.yml

@@ -0,0 +1,90 @@
+# DocGuard — GitLab CI/CD component (CI/CD Catalog style, spec:inputs syntax).
+# Docs: https://docs.gitlab.com/ci/components/ and https://docs.gitlab.com/ci/inputs/
+#
+# This file STAGES the component. Actual catalog publishing requires a GitLab
+# account and a dedicated component project (see packaging/submissions.md):
+#   1. Create a GitLab project (e.g. gitlab.com/raccioly/docguard-component).
+#   2. Copy this file to `templates/docguard.yml` at that project's root
+#      (components must live in a top-level templates/ directory).
+#   3. Set the project as a CI/CD Catalog project (Settings > General > Visibility,
+#      "CI/CD Catalog project" toggle) and add a release job that tags a version.
+#
+# Consumers then include it as:
+#
+#     include:
+#       - component: gitlab.com/raccioly/docguard-component/docguard@0.29.0
+#         inputs:
+#           command: guard
+#           fail_on_warning: true
+#
+# Or, without the catalog, this works today from any repo via a plain include:
+#
+#     include:
+#       - remote: https://raw.githubusercontent.com/raccioly/docguard/v0.29.0/templates/ci/gitlab-component.yml
+
+spec:
+  inputs:
+    command:
+      description: DocGuard command to run.
+      type: string
+      default: guard
+      options: [guard, score, ci]
+    threshold:
+      description: Minimum CDD score (0-100) to pass. Only enforced by the `ci` command; 0 disables.
+      type: number
+      default: 0
+    fail_on_warning:
+      description: Fail the job on warnings, not just errors.
+      type: boolean
+      default: false
+    version:
+      description: docguard-cli version to run (npm dist-tag or exact version).
+      type: string
+      default: '0.29.0'
+    node_image:
+      description: Node.js image for the job (needs git available, so prefer the non-alpine tags).
+      type: string
+      default: 'node:20'
+---
+docguard:
+  image: '$[[ inputs.node_image ]]'
+  stage: test
+  variables:
+    # Several validators diff against git history — avoid a shallow clone.
+    GIT_DEPTH: '0'
+  script:
+    - |
+      set +e
+      CMD="$[[ inputs.command ]]"
+      FAIL_ON_WARNING="$[[ inputs.fail_on_warning ]]"
+      THRESHOLD="$[[ inputs.threshold ]]"
+      FLAGS=""
+      if [ "$CMD" = "ci" ] && [ "$THRESHOLD" -gt 0 ]; then
+        FLAGS="$FLAGS --threshold $THRESHOLD"
+      fi
+      if [ "$CMD" = "ci" ] && [ "$FAIL_ON_WARNING" = "true" ]; then
+        FLAGS="$FLAGS --fail-on-warning"
+      fi
+
+      npx "docguard-cli@$[[ inputs.version ]]" "$CMD" $FLAGS
+      RC=$?
+
+      # guard exit code 2 = warnings only. Not a failure unless asked for.
+      if [ "$CMD" = "guard" ] && [ "$RC" = "2" ]; then
+        if [ "$FAIL_ON_WARNING" = "true" ]; then
+          echo "DocGuard guard found warnings (fail_on_warning is enabled)."
+          RC=1
+        else
+          echo "DocGuard guard found warnings — passing (set fail_on_warning: true to fail)."
+          RC=0
+        fi
+      fi
+
+      # SARIF report as a browsable artifact — best-effort, never changes the verdict.
+      npx "docguard-cli@$[[ inputs.version ]]" guard --format sarif > docguard.sarif || true
+
+      exit $RC
+  artifacts:
+    when: always
+    paths:
+      - docguard.sarif

package/templates/commands/docguard.fix.md

@@ -13,29 +13,47 @@ handoffs:
 
 You are an AI agent responsible for maintaining documentation quality using DocGuard.
 
-## Step 1: Assess Current State
+## Step 1: Mechanical fixes first (no AI judgment needed)
 
 ```bash
-npx docguard-cli diagnose
+npx docguard-cli fix --write
 ```
 
-Parse the output to identify all issues — categorized as errors or warnings with AI-ready fix prompts.
+This deterministically applies the safe fix class: broken doc anchors, stale
+counts bound to code collections, stale version references. Each fix is
+provenance-checked and fail-closed — it never rewrites content whose source of
+truth it cannot verify. Doing this first shrinks the issue list you research.
 
-If no issues found, report "All CDD documentation is up to date" and stop.
+## Step 2: Assess what remains
 
-## Step 2: Fix Each Issue
+```bash
+npx docguard-cli diagnose
+```
 
-For each issue, determine the fix type:
+Parse the output — issues are categorized with AI-ready fix prompts. Every
+finding carries a stable code; run `npx docguard-cli explain <CODE>` whenever
+the right remediation isn't obvious from the message.
+
+If no issues remain, report "All CDD documentation is up to date" and stop.
+
+## Step 3: Fix each issue
 
 | Issue Type | Action |
 |-----------|--------|
 | `missing-file` | Run `npx docguard-cli fix --doc <name>` to generate |
-| `empty-doc` / `partial-doc` | Proceed to Step 3 for codebase research |
+| `empty-doc` / `partial-doc` | Proceed to Step 4 for codebase research |
 | `missing-config` | Create `.docguard.json` based on project type |
 | `stale-doc` | Update `docguard:last-reviewed` date and content |
 | `quality-issue` | Fix negation language, add missing sections |
+| false positive | Suppress at the site: `// docguard:ignore <CODE>` (with a reason comment), and report it: `npx docguard-cli feedback` |
+
+**Doc wrong vs code wrong:** a doc/code mismatch does not automatically mean
+the doc is stale. Canonical docs are the spec — if the code drifted from a
+documented decision, flag the code (or record the deviation with a
+`// DRIFT: reason` comment + DRIFT-LOG.md entry) instead of silently rewriting
+the doc to match the regression.
 
-## Step 3: Write Real Content
+## Step 4: Write real content
 
 For each document that needs content:
 
@@ -50,12 +68,17 @@ Read the output carefully — it contains:
 - **WRITE THE DOCUMENT**: Expected structure and content for each section
 
 Execute the research steps, then write with REAL project content. No placeholders.
+Never edit inside `<!-- docguard:section ... source=code -->` markers by hand —
+those bodies are regenerated from code by `docguard sync --write`; pin them
+(`pinned="reason"`) if a hand-maintained exception is genuinely needed.
 
-## Step 4: Verify (Iterate up to 3 times)
+## Step 5: Verify (iterate up to 3 times)
 
 ```bash
 npx docguard-cli guard
 npx docguard-cli score
 ```
 
-All checks should pass. If any fail, read the output and fix remaining issues. Report the final CDD score.
+All checks should pass. If any fail, read the output and fix remaining issues.
+Report the final CDD score, plus anything you suppressed (with reasons) or
+reported as a false positive.

package/templates/commands/docguard.guard.md

@@ -13,41 +13,55 @@ handoffs:
 
 You are an AI agent enforcing Canonical-Driven Development (CDD) compliance using DocGuard.
 
-## Step 1: Run Guard
+## Step 1: Run Guard (machine-readable)
 
 ```bash
-npx docguard-cli guard
+npx docguard-cli guard --format json
 ```
 
-Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the validators:
+Read the JSON contract — do not parse prose:
 
-| Priority | Validators |
-|----------|-----------|
-| CRITICAL | Structure, Security, Test-Spec |
-| HIGH | Doc Sections, Drift-Comments, Changelog, Traceability, API-Surface |
-| MEDIUM | Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency |
-| LOW | TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync |
+| Field | Meaning |
+|-------|---------|
+| `status` | `PASS` / `WARN` / `FAIL` (severity-aware; matches the exit code: 0/2/1) |
+| `findings[]` | Structured issues: `{code, severity, confidence, message, location, suggestion}` |
+| `nextStep` | The single suggested follow-up command (`null` on PASS) |
+| `reportable[]` | Low-confidence findings (possible false positives) — verify before acting |
+| `coverage` | Markdown tier map: `canonical / tracked / ignored / unclassified[]` |
+| `semanticClaims.count` | Documented counts/limits/enums NOT yet verified against code |
+| `validators[]` | Per-validator results, including `na` (nothing to validate ≠ pass) |
 
-## Step 2: Handle Results
+## Step 2: Understand each finding before fixing
 
-### If all checks pass:
-Report success and the score:
-```bash
-npx docguard-cli score
-```
+- Every finding carries a stable code (e.g. `STR001`, `ENV003`, `XRF002`). Run
+  `npx docguard-cli explain <CODE>` for its contract, cause, and remediation.
+- `confidence: "low"` means the scanner itself is unsure — verify against the
+  code before changing anything, and report real false positives with
+  `npx docguard-cli feedback`.
+- A finding's `suggestion` may include a ready-to-run `command` or an inline
+  `pragma`. Prefer those over inventing your own fix.
 
-### If checks fail:
-For each failing check, provide an **exact fix** — specific file, section, and content.
-Then run the fix workflow:
-```bash
-npx docguard-cli fix --doc <name>
-```
+## Step 3: Fix, suppress, or escalate
 
-Execute the research steps in the output, write real content, then re-run guard to verify.
+1. **Mechanical issues first**: `npx docguard-cli fix --write` applies safe,
+   provenance-checked fixes (broken anchors, stale counts/versions). Never
+   hand-edit what the tool can fix deterministically.
+2. **Prose/content issues**: follow the `/docguard.fix` workflow (research →
+   write real content).
+3. **Genuine false positives**: suppress at the finding site with the code —
+   `// docguard:ignore <CODE>` on (or above) the flagged line — or mark a whole
+   validator not-applicable in a doc:
+   `<!-- docguard:validator <key> n/a — reason -->`. Always include the reason.
+   Never suppress to silence a real issue.
+4. If `semanticClaims.count > 0`, offer to run `npx docguard-cli verify --semantic`
+   and check each extracted claim against the code — a green guard asserts
+   structure, not the truth of documented numbers.
 
-## Step 3: Report
+## Step 4: Report
 
 Show the user:
-1. Which checks passed/failed (with severity)
-2. What was fixed
-3. Final CDD score
+1. `status` and pass/total, plus anything in `coverage.unclassified` (docs no
+   validator watches — suggest enrolling or ignoring them)
+2. Each finding fixed (by code), each suppressed (with reason), each reported
+   as a false positive
+3. Final score: `npx docguard-cli score`

package/templates/commands/docguard.init.md

@@ -21,21 +21,33 @@ npx docguard-cli init
 
 This creates the folder structure and template files. The templates are skeletons — they need real content.
 
-## Step 2: Detect and Configure Project Type
+## Step 2: Pick the Right Profile
+
+`init` auto-detects the project type, but verify the profile fits — it sets
+which docs are required (a CLI shouldn't be forced to document an HTTP API):
+
+| Signal | Profile in `.docguard.json` |
+|--------|------------------------------|
+| Has `bin` field / CLI tool | `"profile": "cli"` |
+| Publishable package | `"profile": "library"` |
+| Side project / prototype | `"profile": "starter"` |
+| Team web app / API | `"profile": "standard"` (default) |
+| Regulated / strict | `"profile": "enterprise"` |
+
+Only schema-valid keys belong in `.docguard.json` — check
+`schemas/docguard-config.schema.json` (shipped in the package) before adding
+anything. If the project has domain collections (extractors, plugins, rules…),
+declare them so documented counts are verified against code:
+`"collections": { "extractors": "src/extractors/*.py" }`.
+
+For an EXISTING codebase, prefer reverse-engineering over blank skeletons:
 
 ```bash
-cat package.json
+npx docguard-cli generate --plan --write
 ```
 
-Create `.docguard.json` based on what you find:
-
-| Signal | Setting |
-|--------|---------|
-| Has `bin` field | `projectType: "cli"` |
-| Has react/next/vue | `projectType: "webapp"`, `needsE2E: true` |
-| Has express/fastify | `projectType: "api"`, `needsEnvVars: true` |
-| Has database deps | `needsDatabase: true` |
-| Default | `projectType: "library"` |
+This pre-fills code-truth sections (routes, schemas, env vars) and leaves you
+an agent-task list for the prose.
 
 ## Step 3: Write Real Documentation
 

package/templates/commands/docguard.review.md

@@ -22,8 +22,21 @@ npx docguard-cli score
 ```
 
 Read all output. Identify where documentation no longer matches the codebase.
+Findings carry stable codes — `npx docguard-cli explain <CODE>` when unclear.
 
-## Step 2: Semantic Analysis (Beyond CLI)
+## Step 2: Verify Documented Claims Against Code
+
+```bash
+npx docguard-cli verify --semantic
+```
+
+This extracts every checkable claim in the canonical docs — counts, limits,
+rate numbers, retention windows, status enums — as a task list with the nearest
+cited code path. **You perform each verification**: read the cited code, compare
+the value, and report every mismatch with both values. This is the highest-value
+review step; deterministic validators cannot judge these.
+
+## Step 3: Semantic Analysis (Beyond CLI)
 
 For each canonical doc, verify alignment with actual code:
 
@@ -35,16 +48,20 @@ For each canonical doc, verify alignment with actual code:
 | Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
 | Terminology | Same concepts named consistently across all docs |
 
-## Step 3: Update Stale Docs
+## Step 4: Update Stale Docs
 
 For each stale or drifted document:
-1. Read the relevant source code files
-2. Update the specific section that changed
-3. Update the `docguard:last-reviewed` date to today
-4. If the change is intentional drift, add an entry to DRIFT-LOG.md
-5. Add entry to CHANGELOG.md under [Unreleased]
+1. **Decide which side is wrong first.** Canonical docs are the spec — if the
+   code regressed from a documented decision, flag the code (or record a
+   `// DRIFT: reason` + DRIFT-LOG.md entry); don't rewrite the doc to match a
+   regression.
+2. Sections inside `<!-- docguard:section ... source=code -->` markers are
+   regenerated — run `npx docguard-cli sync --write` instead of editing by hand.
+3. For hand-maintained sections: read the relevant source, update the specific
+   section, refresh `docguard:last-reviewed` to today.
+4. Add entry to CHANGELOG.md under [Unreleased].
 
-## Step 4: Verify
+## Step 5: Verify
 
 ```bash
 npx docguard-cli guard

package/templates/commands/docguard.update.md

@@ -16,11 +16,12 @@ You are an AI agent that updates documentation to reflect recent code changes.
 ## Step 1: Identify What Changed
 
 ```bash
+npx docguard-cli diff --since HEAD~5
 git log --oneline -10
-git diff HEAD~5 --stat
 ```
 
-Read the recent commits. Understand what code changed and why.
+`diff --since` maps the changed files directly to the canonical docs they
+affect — read its output first; the git log supplies the "why".
 
 ## Step 2: Check Which Docs Are Affected
 
@@ -38,10 +39,19 @@ For each changed file, determine which canonical doc it affects:
 
 ## Step 3: Update Each Affected Doc
 
-For each affected document:
+Mechanical layers first — they update marked sections and counts without AI
+judgment:
+
+```bash
+npx docguard-cli sync --write
+npx docguard-cli fix --write
+```
+
+Then, for each remaining affected document:
 1. Read the current document
 2. Read the relevant source code changes
-3. Update the specific section that changed
+3. Update the specific section that changed (never hand-edit inside
+   `<!-- docguard:section ... source=code -->` markers — sync owns those)
 4. Update the `docguard:last-reviewed` date to today
 5. Add entry to CHANGELOG.md under [Unreleased]