docguard-cli 0.8.0 → 0.9.0

package/cli/scanners/speckit.mjs

@@ -0,0 +1,234 @@
+/**
+ * Spec Kit Scanner — Detect and integrate with GitHub Spec Kit artifacts
+ *
+ * Auto-detects .specify/ directory (Spec Kit projects) and maps Spec Kit
+ * artifacts to CDD canonical docs. Enables DocGuard to work seamlessly
+ * with Spec Kit-managed projects.
+ *
+ * Spec Kit artifact mapping:
+ *   .specify/           → Project uses Spec Kit
+ *   specs/[name]/spec.md  → Requirements (maps to REQUIREMENTS.md / docs-canonical/)
+ *   specs/[name]/plan.md  → Design decisions (maps to ARCHITECTURE.md)
+ *   specs/[name]/tasks.md → Work items (maps to ROADMAP.md)
+ *   constitution.md      → Project rules (maps to AGENTS.md)
+ *   memory/              → Learned context (maps to DRIFT-LOG.md)
+ *
+ * Credit: Integration inspired by GitHub's Spec Kit framework
+ *         (github.com/github/spec-kit)
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+/**
+ * Detect if a project uses Spec Kit.
+ * Returns details about detected Spec Kit artifacts.
+ */
+export function detectSpecKit(projectDir) {
+  const result = {
+    detected: false,
+    specifyDir: false,
+    specs: [],
+    constitution: false,
+    memory: false,
+  };
+
+  // Check for .specify/ directory
+  const specifyDir = resolve(projectDir, '.specify');
+  if (existsSync(specifyDir)) {
+    result.detected = true;
+    result.specifyDir = true;
+  }
+
+  // Check for specs/ directory with spec.md files
+  const specsDir = resolve(projectDir, 'specs');
+  if (existsSync(specsDir)) {
+    try {
+      const features = readdirSync(specsDir);
+      for (const feature of features) {
+        const featureDir = join(specsDir, feature);
+        try {
+        const fstat = statSync(featureDir);
+        if (!fstat.isDirectory()) continue;
+        } catch { continue; }
+
+        const specFile = join(featureDir, 'spec.md');
+        const planFile = join(featureDir, 'plan.md');
+        const tasksFile = join(featureDir, 'tasks.md');
+
+        if (existsSync(specFile) || existsSync(planFile) || existsSync(tasksFile)) {
+          result.detected = true;
+          result.specs.push({
+            name: feature,
+            hasSpec: existsSync(specFile),
+            hasPlan: existsSync(planFile),
+            hasTasks: existsSync(tasksFile),
+          });
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Check for constitution.md
+  const constitutionPath = resolve(projectDir, 'constitution.md');
+  if (existsSync(constitutionPath)) {
+    result.detected = true;
+    result.constitution = true;
+  }
+
+  // Check for memory/ directory
+  const memoryDir = resolve(projectDir, 'memory');
+  if (existsSync(memoryDir)) {
+    result.detected = true;
+    result.memory = true;
+  }
+
+  return result;
+}
+
+/**
+ * Map Spec Kit artifact to CDD equivalent.
+ * Returns the canonical doc name and section.
+ */
+const SPECKIT_CDD_MAP = {
+  'spec.md': { cddDoc: 'REQUIREMENTS.md', section: 'Requirements', type: 'requirement' },
+  'plan.md': { cddDoc: 'ARCHITECTURE.md', section: 'Design Decisions', type: 'design' },
+  'tasks.md': { cddDoc: 'ROADMAP.md', section: 'Task Backlog', type: 'roadmap' },
+};
+
+/**
+ * Generate CDD canonical docs from Spec Kit artifacts.
+ * Used by `docguard generate --from-speckit`.
+ *
+ * @param {string} projectDir - Project root
+ * @param {object} config - DocGuard config
+ * @param {object} flags - CLI flags
+ * @returns {object} - { generated: string[], skipped: string[], errors: string[] }
+ */
+export function generateFromSpecKit(projectDir, config, flags) {
+  const results = { generated: [], skipped: [], errors: [] };
+
+  const speckit = detectSpecKit(projectDir);
+  if (!speckit.detected) {
+    results.errors.push('No Spec Kit artifacts detected. This project does not use Spec Kit.');
+    return results;
+  }
+
+  // ── Generate REQUIREMENTS.md from spec.md files ──
+  if (speckit.specs.some(s => s.hasSpec)) {
+    const reqPath = resolve(projectDir, 'REQUIREMENTS.md');
+    if (existsSync(reqPath) && !flags.force) {
+      results.skipped.push('REQUIREMENTS.md already exists (use --force to overwrite)');
+    } else {
+      const lines = [
+        '# Requirements',
+        '',
+        '> Auto-generated from Spec Kit spec.md files by DocGuard',
+        '',
+      ];
+
+      for (const spec of speckit.specs) {
+        if (!spec.hasSpec) continue;
+        const specPath = join(projectDir, 'specs', spec.name, 'spec.md');
+        const content = readFileSync(specPath, 'utf-8');
+
+        lines.push(`## ${spec.name}`);
+        lines.push('');
+        lines.push(content.trim());
+        lines.push('');
+        lines.push('---');
+        lines.push('');
+      }
+
+      lines.push(`<!-- Generated by DocGuard from Spec Kit artifacts on ${new Date().toISOString().split('T')[0]} -->`);
+
+      writeFileSync(reqPath, lines.join('\n'), 'utf-8');
+      results.generated.push('REQUIREMENTS.md');
+    }
+  }
+
+  // ── Map constitution.md to AGENTS.md context ──
+  if (speckit.constitution) {
+    const constitutionPath = resolve(projectDir, 'constitution.md');
+    const agentsPath = resolve(projectDir, 'AGENTS.md');
+
+    if (existsSync(agentsPath)) {
+      const agentsContent = readFileSync(agentsPath, 'utf-8');
+
+      // Check if AGENTS.md already references constitution
+      if (!agentsContent.includes('constitution.md') && !agentsContent.includes('Constitution')) {
+        results.skipped.push('AGENTS.md exists but does not reference constitution.md — consider adding a reference');
+      } else {
+        results.skipped.push('AGENTS.md already references constitution.md');
+      }
+    }
+  }
+
+  // ── Map memory/ to DRIFT-LOG.md context ──
+  if (speckit.memory) {
+    results.skipped.push('memory/ directory detected — maps conceptually to DRIFT-LOG.md (no auto-generation needed)');
+  }
+
+  return results;
+}
+
+/**
+ * Validate Spec Kit artifact consistency.
+ * Used by guard to give CDD credit for Spec Kit artifacts.
+ *
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateSpecKitIntegration(projectDir, config) {
+  const results = { errors: [], warnings: [], passed: 0, total: 0 };
+
+  const speckit = detectSpecKit(projectDir);
+
+  // If no Spec Kit detected, silently pass
+  if (!speckit.detected) {
+    return results;
+  }
+
+  // Check 1: .specify/ directory exists → Spec Kit initialized
+  results.total++;
+  if (speckit.specifyDir) {
+    results.passed++;
+  } else {
+    results.warnings.push('Spec Kit artifacts detected but .specify/ directory missing. Run `specify init` to initialize');
+  }
+
+  // Check 2: Each spec has corresponding canonical doc coverage
+  for (const spec of speckit.specs) {
+    if (spec.hasSpec) {
+      results.total++;
+      // Check if spec.md content appears in any canonical doc
+      const specPath = join(projectDir, 'specs', spec.name, 'spec.md');
+      const content = readFileSync(specPath, 'utf-8');
+
+      // Look for requirement IDs in the spec
+      const hasReqIds = /\b(REQ|FR|NFR|US|STORY|AC)-\d{2,4}\b/.test(content);
+
+      if (hasReqIds) {
+        results.passed++;
+      } else {
+        results.warnings.push(
+          `specs/${spec.name}/spec.md has no requirement IDs. Add IDs (e.g., REQ-001) for traceability`
+        );
+      }
+    }
+  }
+
+  // Check 3: Constitution mapped to AGENTS.md
+  if (speckit.constitution) {
+    results.total++;
+    const agentsPath = resolve(projectDir, 'AGENTS.md');
+    if (existsSync(agentsPath)) {
+      results.passed++;
+    } else {
+      results.warnings.push('constitution.md exists but no AGENTS.md found. Create one for AI agent rules');
+    }
+  }
+
+  return results;
+}

package/cli/shared.mjs

@@ -62,4 +62,80 @@ export const PROFILES = {
       freshness: true,
     },
   },
+  'enterprise-ai': {
+    description: 'EU AI Act compliance — Annex IV documentation requirements, ALCOA+ alignment, strict freshness. For AI/ML projects under regulatory scrutiny.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+        'docs-canonical/DATA-MODEL.md',
+        'docs-canonical/SECURITY.md',
+        'docs-canonical/TEST-SPEC.md',
+        'docs-canonical/ENVIRONMENT.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+    validators: {
+      structure: true,
+      docsSync: true,
+      drift: true,
+      changelog: true,
+      architecture: true,
+      testSpec: true,
+      security: true,
+      environment: true,
+      freshness: true,
+      docQuality: true,
+      todoTracking: true,
+      schemaSync: true,
+    },
+    // Stricter freshness threshold — 14 days instead of 30
+    freshness: { maxDaysStale: 14 },
+    // SECURITY.md must have Risk Assessment section
+    requiredSections: {
+      'SECURITY.md': ['Risk Assessment', 'Threat Model'],
+    },
+  },
 };
+
+// ── .docguardignore Support ───────────────────────────────────────────────
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+
+/**
+ * Load ignore patterns from .docguardignore (like .gitignore).
+ * Returns a function that checks if a relative path should be ignored.
+ *
+ * Format: one pattern per line, # comments, blank lines skipped.
+ * Supports simple glob: * (any chars), ** (any path segments).
+ *
+ * @param {string} projectDir - Project root
+ * @returns {(relPath: string) => boolean} - Returns true if file should be ignored
+ */
+export function loadIgnorePatterns(projectDir) {
+  const ignorePath = resolve(projectDir, '.docguardignore');
+  if (!existsSync(ignorePath)) return () => false;
+
+  let content;
+  try { content = readFileSync(ignorePath, 'utf-8'); } catch { return () => false; }
+
+  const patterns = content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'))
+    .map(pattern => {
+      // Convert glob to regex:
+      // ** → match any path segments
+      // * → match any chars except /
+      // . → literal dot
+      const escaped = pattern
+        .replace(/\./g, '\\.')
+        .replace(/\*\*/g, '§§')     // temp placeholder
+        .replace(/\*/g, '[^/]*')
+        .replace(/§§/g, '.*');
+      return new RegExp(`^${escaped}$|/${escaped}$|^${escaped}/|/${escaped}/`);
+    });
+
+  return (relPath) => patterns.some(regex => regex.test(relPath));
+}