docguard-cli 0.29.0 → 0.30.1

package/cli/scanners/speckit.mjs

@@ -23,8 +23,12 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync } from 'node:fs';
-import { resolve, join, relative } from 'node:path';
+import { resolve, join, relative, dirname, basename, extname } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { isGitRepo } from '../shared-git.mjs';
+import { walkFiles } from '../shared-ignore.mjs';
+import { readScannable } from '../shared-source.mjs';
 
 // ──── Spec Kit Mandatory Sections ────
 // Based on spec-kit's spec-template.md, plan-template.md, tasks-template.md
@@ -294,6 +298,304 @@ function validateTasksQuality(tasksPath) {
   return issues;
 }
 
+// ──── Phantom-Completion Detection (SPK008/SPK009, v0.30) ────
+//
+// A `- [x]` in tasks.md is a CLAIM that work landed. An agent (or human) that
+// checks a task without landing the artifact corrupts the project's memory:
+// every later session trusts the checkbox and skips the work. This check
+// verifies the claim deterministically — "lie detection" for tasks.md.
+//
+// PRECISION-FIRST DESIGN — a false accusation of lying is worse than a miss:
+//   • Only tasks that make a FALSIFIABLE artifact claim can be flagged: the
+//     task line must name at least one repo-relative path (slashed, or with an
+//     explicit trailing `/` for directories). Prose-only tasks ("Review the
+//     approach"), bare filenames ("buildspec.yml" may describe the DOMAIN, not
+//     a deliverable), and tasks whose only reference is a task ID are counted
+//     as unverifiable and never flagged — flagging them is FP soup.
+//   • A task is phantom only when EVERY evidence tier comes up empty:
+//       a. any named path exists (project root or the feature dir);
+//       b. a named basename exists anywhere in the repo (file was moved);
+//       c. a backticked code symbol from the task line appears in source;
+//       d. sibling plan.md/spec.md name an existing deliverable that the task
+//          text also mentions;
+//       e. the task ID (T001…) appears in a source/test file annotation;
+//       f. the task ID appears in a git commit message (skipped silently when
+//          the project is not a git repo or git is unavailable).
+//     Evidence false-positives are SAFE (they suppress an accusation), so the
+//     tiers are deliberately generous.
+
+const CHECKED_TASK_RE = /^\s*-\s*\[[xX]\]\s*(T\d{3,4})?\s*(.+)$/;
+const MAX_PHANTOM_FINDINGS = 10;
+
+/** Code-ish extensions whose content can carry task-ID / symbol evidence. */
+const EVIDENCE_CODE_EXTS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.go', '.rs', '.java', '.rb', '.php', '.kt', '.swift',
+  '.c', '.h', '.cpp', '.hpp', '.cs', '.sh', '.sql',
+  '.yml', '.yaml', '.json', '.toml',
+]);
+
+/**
+ * Parse checked tasks (`- [x] T001 …`) out of a tasks.md.
+ * Returns [{ id, text, line }] with 1-based line numbers. The task ID is also
+ * recovered from a leading bold/decorated form (`**T001**`) when the plain
+ * position doesn't match.
+ */
+export function parseCheckedTasks(content) {
+  const tasks = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(CHECKED_TASK_RE);
+    if (!m) continue;
+    const text = m[2].trim();
+    let id = m[1] || null;
+    if (!id) {
+      const decorated = text.match(/^[*_~[(]*\s*(T\d{3,4})\b/);
+      if (decorated) id = decorated[1];
+    }
+    tasks.push({ id, text, line: i + 1 });
+  }
+  return tasks;
+}
+
+/**
+ * Extract path-like tokens from a task line.
+ *
+ * `claims` — slashed paths (or explicit `dir/` syntax): falsifiable
+ *   deliverable claims. Only these can convict.
+ * `soft` — bare filenames (`CHANGELOG.md`) and extension-less slashed tokens
+ *   (`cli/commands`): positive evidence ONLY, never grounds for flagging —
+ *   prose mentions of foreign/domain filenames (and "and/or"-style prose
+ *   slashes, which the charset+extension rules reject as claims) must not
+ *   convict.
+ *
+ * Rejected outright (unverifiable or unsafe to resolve): tokens with spaces,
+ * globs/placeholders, absolute paths (URL routes like `/api/users` are not
+ * repo files), and `..` segments (never resolve outside the project).
+ */
+export function extractPathTokens(text) {
+  const claims = new Set();
+  const soft = new Set();
+  const consider = (tokRaw) => {
+    let tok = tokRaw.trim().replace(/^\.\//, '').replace(/:\d+(?::\d+)?$/, '');
+    if (!tok || tok.length > 200 || /\s/.test(tok)) return;
+    if (/[*?{}<>|]/.test(tok)) return;
+    if (tok.startsWith('/')) return;
+    if (/(^|\/)\.\.(\/|$)/.test(tok)) return;
+    const isDirSyntax = tok.endsWith('/');
+    tok = tok.replace(/\/+$/, '');
+    if (!tok || !/^\.?[\w@][\w@./-]*$/.test(tok)) return;
+    if (tok.includes('/')) {
+      const last = tok.slice(tok.lastIndexOf('/') + 1);
+      if (/\.[A-Za-z]\w{0,9}$/.test(last) || isDirSyntax) claims.add(tok);
+      else soft.add(tok);
+    } else if (/\.[A-Za-z]\w{0,9}$/.test(tok)) {
+      soft.add(tok); // bare filename — rejects version numbers like `18.0`
+    }
+  };
+  for (const m of text.matchAll(/`([^`]+)`/g)) consider(m[1]);
+  for (const m of text.matchAll(/(?:^|[\s("'[])((?:[\w@.-]+\/)+[\w@.-]+\/?)/g)) consider(m[1]);
+  return { claims, soft };
+}
+
+/**
+ * Backticked identifier-like tokens (`globMatch(relPath, patterns)` → globMatch,
+ * `IGNORE_DIRS` → IGNORE_DIRS). Used as an evidence tier: a task that names a
+ * function/constant that exists in source was plainly not skipped. Min length 4
+ * keeps trivially-common words from being extracted at all (an over-match here
+ * only suppresses an accusation, so the filter is intentionally loose).
+ */
+export function extractSymbolTokens(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/`([^`]+)`/g)) {
+    const tok = m[1].trim();
+    const call = tok.match(/^([A-Za-z_$][\w$]*)\s*\(/);
+    if (call && call[1].length >= 4) { out.add(call[1]); continue; }
+    if (/^[A-Za-z_$][\w$]*$/.test(tok) && tok.length >= 4) out.add(tok);
+  }
+  return out;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Does any of the named tokens exist relative to root or the feature dir? */
+function anyPathExists(projectDir, featureDir, tokens) {
+  for (const tok of tokens) {
+    if (existsSync(resolve(projectDir, tok))) return true;
+    if (featureDir && existsSync(resolve(featureDir, tok))) return true;
+  }
+  return false;
+}
+
+/**
+ * Existing deliverable paths named by the feature's sibling plan.md/spec.md.
+ * Returns { paths: Set<string>, basenames: Set<string> } — only tokens that
+ * exist on disk count (a plan mentioning a path is design, not evidence;
+ * a plan mentioning an EXISTING path ties the deliverable to reality).
+ */
+function collectSiblingArtifacts(projectDir, spec) {
+  const paths = new Set();
+  const basenames = new Set();
+  const featureDir = spec.tasksPath ? dirname(spec.tasksPath) : null;
+  for (const p of [spec.planPath, spec.specPath]) {
+    if (!p) continue;
+    let content;
+    try { content = readFileSync(p, 'utf-8'); } catch { continue; }
+    const { claims, soft } = extractPathTokens(content);
+    for (const tok of [...claims, ...soft]) {
+      if (existsSync(resolve(projectDir, tok)) || (featureDir && existsSync(resolve(featureDir, tok)))) {
+        paths.add(tok);
+        const base = basename(tok);
+        if (base.length >= 5) basenames.add(base); // ≥5 avoids `a.ts`-scale collisions
+      }
+    }
+  }
+  return { paths, basenames };
+}
+
+/**
+ * ONE repo walk that resolves every deferred needle at once: basenames of
+ * needed files (any extension, so a moved deliverable still evidences), and
+ * task-IDs / code symbols inside code-ish files. Dot-entries are skipped
+ * (so specs' own markdown never self-evidences) except .github, whose
+ * workflows are legitimate deliverables.
+ */
+function scanRepoForEvidence(projectDir, needles) {
+  const found = { basenames: new Set(), symbols: new Set(), ids: new Set() };
+  const symbolRes = new Map();
+  for (const sym of needles.symbols) symbolRes.set(sym, new RegExp(`\\b${escapeRe(sym)}\\b`));
+  const wantContent = needles.ids.size > 0 || symbolRes.size > 0;
+  walkFiles(projectDir, (absPath) => {
+    const base = basename(absPath);
+    if (needles.basenames.has(base)) found.basenames.add(base);
+    if (!wantContent) return;
+    if (!EVIDENCE_CODE_EXTS.has(extname(absPath).toLowerCase())) return;
+    if (found.ids.size === needles.ids.size && found.symbols.size === symbolRes.size) return;
+    const content = readScannable(absPath);
+    if (!content) return;
+    if (needles.ids.size > found.ids.size) {
+      for (const m of content.matchAll(/\bT\d{3,4}\b/g)) {
+        if (needles.ids.has(m[0])) found.ids.add(m[0]);
+      }
+    }
+    for (const [sym, re] of symbolRes) {
+      if (!found.symbols.has(sym) && re.test(content)) found.symbols.add(sym);
+    }
+  }, { keepDot: (entry) => entry === '.github' });
+  return found;
+}
+
+/**
+ * Is the task ID referenced in a commit message? `--grep` narrows in git;
+ * the JS word-boundary re-check drops substring hits (T001 vs T0010).
+ * `--format=%B` (not --oneline) so a body-only mention still counts.
+ * Fails closed to `false` — a missing git binary or empty history just
+ * means this tier contributes no evidence.
+ */
+function taskIdInGitLog(projectDir, id) {
+  try {
+    const out = execFileSync(
+      'git',
+      ['log', `--grep=${id}`, '--format=%B'],
+      { cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 8 * 1024 * 1024 }
+    );
+    return new RegExp(`\\b${id}(?!\\d)`).test(out);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run phantom-completion detection across all detected features.
+ *
+ * Two passes: cheap per-task tiers first (named paths on disk, sibling
+ * artifacts); tasks still unevidenced go into ONE batched repo scan
+ * (basenames + symbols + task-ID annotations), then a per-ID git-log lookup
+ * (cached; skipped silently when not a git repo).
+ *
+ * @returns {Array<{spec, relPath, checkedCount, unverifiableCount,
+ *                  phantoms: Array<{id, text, line, tiers: string[]}>}>}
+ */
+export function detectPhantomCompletions(projectDir, specs) {
+  const results = [];
+  const pending = [];
+  const siblingCache = new Map();
+
+  for (const spec of specs) {
+    if (!spec.hasTasks || !spec.tasksPath) continue;
+    let content;
+    try { content = readFileSync(spec.tasksPath, 'utf-8'); } catch { continue; } // SPK006 covers unreadable
+    const tasks = parseCheckedTasks(content);
+    const entry = {
+      spec,
+      relPath: relative(projectDir, spec.tasksPath),
+      checkedCount: tasks.length,
+      unverifiableCount: 0,
+      phantoms: [],
+    };
+    results.push(entry);
+    if (tasks.length === 0) continue;
+
+    const featureDir = dirname(spec.tasksPath);
+    for (const task of tasks) {
+      const { claims, soft } = extractPathTokens(task.text);
+      if (claims.size === 0) { entry.unverifiableCount++; continue; } // no falsifiable claim
+      // Tier a: any named path exists (claims convict; soft tokens only evidence)
+      if (anyPathExists(projectDir, featureDir, claims) || anyPathExists(projectDir, featureDir, soft)) continue;
+      // Tier d: sibling plan/spec name an existing deliverable this task mentions
+      if (!siblingCache.has(featureDir)) siblingCache.set(featureDir, collectSiblingArtifacts(projectDir, spec));
+      const sibling = siblingCache.get(featureDir);
+      const hasSiblingDocs = Boolean(spec.planPath || spec.specPath);
+      let rescued = false;
+      for (const p of sibling.paths) { if (task.text.includes(p)) { rescued = true; break; } }
+      if (!rescued) for (const b of sibling.basenames) { if (task.text.includes(b)) { rescued = true; break; } }
+      if (rescued) continue;
+      // Defer tiers b/c/e/f to the batched repo scan + git lookup
+      pending.push({
+        entry, task, hasSiblingDocs,
+        basenames: new Set([...claims].map((t) => basename(t)).concat([...soft].filter((t) => !t.includes('/')))),
+        symbols: extractSymbolTokens(task.text),
+      });
+    }
+  }
+
+  if (pending.length > 0) {
+    const needles = { basenames: new Set(), symbols: new Set(), ids: new Set() };
+    for (const p of pending) {
+      for (const b of p.basenames) needles.basenames.add(b);
+      for (const s of p.symbols) needles.symbols.add(s);
+      if (p.task.id) needles.ids.add(p.task.id);
+    }
+    const found = scanRepoForEvidence(projectDir, needles);
+    let repo = null; // lazy: only shell out when an ID actually needs the git tier
+    const gitCache = new Map();
+    for (const p of pending) {
+      if ([...p.basenames].some((b) => found.basenames.has(b))) continue; // tier b: moved file
+      if ([...p.symbols].some((s) => found.symbols.has(s))) continue;     // tier c: symbol landed
+      if (p.task.id && found.ids.has(p.task.id)) continue;                // tier e: source annotation
+      let gitTierRan = false;
+      if (p.task.id) {
+        if (repo === null) repo = isGitRepo(projectDir);
+        if (repo) {
+          gitTierRan = true;
+          if (!gitCache.has(p.task.id)) gitCache.set(p.task.id, taskIdInGitLog(projectDir, p.task.id));
+          if (gitCache.get(p.task.id)) continue;                          // tier f: commit trail
+        }
+      }
+      const tiers = ['named paths', 'repo file names'];
+      if (p.hasSiblingDocs) tiers.push('plan/spec artifacts');
+      if (p.symbols.size > 0) tiers.push('code symbols');
+      if (p.task.id) tiers.push('task-ID in source');
+      if (gitTierRan) tiers.push('git log');
+      p.entry.phantoms.push({ id: p.task.id, text: p.task.text, line: p.task.line, tiers });
+    }
+  }
+
+  return results;
+}
+
 // ──── CDD Mapping ────
 
 const SPECKIT_CDD_MAP = {
@@ -391,6 +693,12 @@ export function generateFromSpecKit(projectDir, config, flags) {
  * byte-identical to the legacy strings — resultFromFindings derives the
  * errors/warnings arrays from the same findings, so counts, exit codes, and
  * existing tests are unaffected; guard just renders richer output.
+ *
+ * v0.30: adds phantom-completion detection (SPK008, elision SPK009) — tasks
+ * marked [x] whose named deliverables don't exist and have no other
+ * implementation evidence (see the Phantom-Completion Detection section
+ * above for the tier design). Opt out per-project with
+ * `"specKit": { "phantomCheck": false }` in .docguard.json.
  */
 export function validateSpecKitIntegration(projectDir, config) {
   const findings = [];
@@ -527,6 +835,43 @@ export function validateSpecKitIntegration(projectDir, config) {
     }
   }
 
+  // ── Check 2d: Phantom completions — tasks checked [x] with no implementation evidence ──
+  // Opt out with `"specKit": { "phantomCheck": false }` in .docguard.json.
+  // Each tasks.md with at least one checked task counts as one check.
+  if (config?.specKit?.phantomCheck !== false) {
+    const phantomResults = detectPhantomCompletions(projectDir, speckit.specs);
+    const flagged = [];
+    for (const r of phantomResults) {
+      if (r.checkedCount === 0) continue;
+      total++;
+      if (r.phantoms.length === 0) { passed++; continue; }
+      for (const ph of r.phantoms) flagged.push({ r, ph });
+    }
+    for (const { r, ph } of flagged.slice(0, MAX_PHANTOM_FINDINGS)) {
+      const text = ph.text.length > 80 ? ph.text.slice(0, 77) + '...' : ph.text;
+      const label = ph.id ? `${ph.id} marked [x]` : 'task marked [x]';
+      findings.push(mkFinding({
+        code: 'SPK008',
+        validator: 'specKit',
+        severity: 'warn',
+        confidence: 'low',
+        message: `specs/${r.spec.name}/tasks.md: ${label} with no implementation evidence — "${text}" (checked: ${ph.tiers.join(', ')})`,
+        location: `${r.relPath}:${ph.line}`,
+        suggestion: { kind: 'review', text: 'Uncheck the task or land the implementation it claims — a checked task with no artifact is memory corruption for agents' },
+      }));
+    }
+    if (flagged.length > MAX_PHANTOM_FINDINGS) {
+      findings.push(mkFinding({
+        code: 'SPK009',
+        validator: 'specKit',
+        severity: 'warn',
+        message: `...and ${flagged.length - MAX_PHANTOM_FINDINGS} more checked tasks with no implementation evidence`,
+        location: null,
+        suggestion: { kind: 'review', text: 'Fix or uncheck the tasks above and re-run guard to surface the rest — or set specKit.phantomCheck=false in .docguard.json to disable' },
+      }));
+    }
+  }
+
   // ── Check 3: Constitution → AGENTS.md mapping ──
   if (speckit.constitution) {
     total++;

package/cli/shared-git.mjs

@@ -167,7 +167,14 @@ export function getHooksDir(dir) {
     ).trim();
     // --git-path returns a path relative to `dir` (cwd) or an absolute path;
     // resolve() handles both.
-    if (out) return resolve(dir, out);
+    //
+    // Guard `/dev/null`: when `core.hooksPath` is set to /dev/null (a common
+    // "disable all hooks" convention — and what Jules's sandbox VM does),
+    // git returns the literal `/dev/null`. resolve()-ing it and then writing
+    // `<hooksDir>/pre-commit` gives `ENOTDIR: /dev/null/pre-commit`. Treat it
+    // as "no usable hooks dir" and fall through to the `.git/hooks` check so
+    // hook install/list still works in that environment. (bug-200)
+    if (out && out !== '/dev/null') return resolve(dir, out);
   } catch {
     // git unavailable or not a repo — fall through to the literal-path check.
   }

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.29.0"
+  version: "0.30.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.29.0
+  version: 0.30.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.30.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.29.0
+  version: 0.30.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.30.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.29.0
+  version: 0.30.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.30.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.29.0
+  version: 0.30.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.30.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.29.0
+  version: 0.30.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.29.0 -->
+<!-- docguard:version: 0.30.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
     "url": "https://github.com/raccioly/docguard"
   },
   "homepage": "https://github.com/raccioly/docguard#readme",
+  "mcpName": "io.github.raccioly/docguard",
   "bugs": {
     "url": "https://github.com/raccioly/docguard/issues"
   },

package/schemas/docguard-config.schema.json

@@ -188,6 +188,17 @@
       },
       "additionalProperties": true
     },
+    "specKit": {
+      "type": "object",
+      "description": "Spec-Kit validator overrides.",
+      "properties": {
+        "phantomCheck": {
+          "type": "boolean",
+          "description": "If false, disable phantom-completion detection (SPK008/SPK009) — checked tasks in tasks.md whose named deliverables don't exist and carry no implementation evidence. On by default."
+        }
+      },
+      "additionalProperties": true
+    },
     "collections": {
       "type": "object",
       "description": "Project-declared collections (field report #6): maps a documentation noun (e.g. \"extractors\") to a glob whose matching-file count is the source of truth. Metrics-Consistency then flags a documented count that disagrees (\"16 extractors\" in prose vs 19 files on disk), deterministically and with no LLM. A declared collection IS the opt-in binding, so — unlike the built-in checks/validators counts — it does not require the noun's line to mention \"docguard\". An unresolved glob (0 matches) is skipped, never asserting \"0\". Reserved nouns (checks, validators, tests) keep their built-in meaning. Complements surfaceSync (WHICH members drift) with a count check (HOW MANY). Example: { \"extractors\": \"src/extractors/*.py\", \"commands\": \"cli/commands/*.mjs\" }.",

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