docguard-cli 0.5.2 → 0.6.0

package/cli/commands/publish.mjs

@@ -0,0 +1,246 @@
+/**
+ * DocGuard Publish Command
+ * Scaffolds documentation publishing config for external doc platforms.
+ * Currently supports: Mintlify
+ * 
+ * Usage: docguard publish --platform mintlify [--dir .]
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const SUPPORTED_PLATFORMS = ['mintlify'];
+
+export function runPublish(projectDir, config, flags) {
+  const platform = flags.platform || 'mintlify';
+
+  if (!SUPPORTED_PLATFORMS.includes(platform)) {
+    console.error(`${c.red}✗ Unsupported platform: ${platform}${c.reset}`);
+    console.log(`  Supported: ${SUPPORTED_PLATFORMS.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`${c.bold}📚 DocGuard Publish — ${platform}${c.reset}`);
+  console.log(`${c.dim}   Scaffolding ${platform} docs from canonical documentation...${c.reset}\n`);
+
+  switch (platform) {
+    case 'mintlify':
+      scaffoldMintlify(projectDir, config, flags);
+      break;
+  }
+}
+
+function scaffoldMintlify(dir, config, flags) {
+  const docsDir = resolve(dir, 'docs');
+
+  // Check for existing Mintlify setup
+  if (existsSync(resolve(dir, 'docs.json')) && !flags.force) {
+    console.log(`  ${c.yellow}⚠️  docs.json already exists.${c.reset} Use --force to overwrite.`);
+    return;
+  }
+
+  // Create docs directory
+  if (!existsSync(docsDir)) {
+    mkdirSync(docsDir, { recursive: true });
+  }
+
+  let created = 0;
+
+  // ── 1. Generate docs.json (Mintlify v2 config) ──
+  const docsJson = {
+    "$schema": "https://mintlify.com/docs.json",
+    name: config.projectName || basename(dir),
+    logo: {
+      dark: "/logo/dark.svg",
+      light: "/logo/light.svg",
+    },
+    favicon: "/favicon.svg",
+    colors: {
+      primary: "#0D9373",
+      light: "#07C983",
+      dark: "#0D9373",
+    },
+    topbarLinks: [
+      {
+        name: "GitHub",
+        url: `https://github.com/${config.repository || 'your-org/your-repo'}`,
+      },
+    ],
+    topbarCtaButton: {
+      name: "Get Started",
+      url: "/quickstart",
+    },
+    tabs: [
+      {
+        name: "Architecture",
+        url: "architecture",
+      },
+      {
+        name: "API Reference",
+        url: "api-reference",
+      },
+    ],
+    navigation: buildMintlifyNavigation(dir),
+    footerSocials: {
+      github: `https://github.com/${config.repository || 'your-org/your-repo'}`,
+    },
+  };
+
+  writeFileSync(resolve(dir, 'docs.json'), JSON.stringify(docsJson, null, 2), 'utf-8');
+  console.log(`  ${c.green}✅ docs.json${c.reset} (Mintlify v2 config)`);
+  created++;
+
+  // ── 2. Generate introduction.mdx ──
+  const readmePath = resolve(dir, 'README.md');
+  let readmeContent = '';
+  if (existsSync(readmePath)) {
+    readmeContent = readFileSync(readmePath, 'utf-8');
+    // Extract first paragraph for description
+    const firstPara = readmeContent.split('\n\n').slice(1, 3).join('\n\n');
+    readmeContent = firstPara;
+  }
+
+  const introContent = `---
+title: Introduction
+description: "${config.projectName} documentation"
+---
+
+# ${config.projectName}
+
+${readmeContent || `Welcome to the ${config.projectName} documentation.`}
+
+## Quick Links
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/quickstart">
+    Get up and running in 5 minutes
+  </Card>
+  <Card title="Architecture" icon="building" href="/architecture">
+    Understand the system design
+  </Card>
+  <Card title="API Reference" icon="code" href="/api-reference">
+    Explore the API endpoints
+  </Card>
+  <Card title="Data Model" icon="database" href="/data-model">
+    Learn about the data structure
+  </Card>
+</CardGroup>
+`;
+
+  writeFileSync(resolve(docsDir, 'introduction.mdx'), introContent, 'utf-8');
+  console.log(`  ${c.green}✅ docs/introduction.mdx${c.reset}`);
+  created++;
+
+  // ── 3. Generate quickstart.mdx ──
+  const quickstartContent = `---
+title: Quick Start
+description: "Get started with ${config.projectName}"
+---
+
+# Quick Start
+
+## Prerequisites
+
+- Node.js 18+
+- npm or pnpm
+
+## Installation
+
+\`\`\`bash
+npm install
+\`\`\`
+
+## Setup
+
+\`\`\`bash
+cp .env.example .env.local
+# Fill in environment variables
+npm run dev
+\`\`\`
+
+## Verify
+
+\`\`\`bash
+npx docguard-cli guard    # Check documentation compliance
+npx docguard-cli score    # View CDD maturity score
+\`\`\`
+`;
+
+  writeFileSync(resolve(docsDir, 'quickstart.mdx'), quickstartContent, 'utf-8');
+  console.log(`  ${c.green}✅ docs/quickstart.mdx${c.reset}`);
+  created++;
+
+  // ── 4. Map canonical docs to Mintlify pages ──
+  const canonicalDir = resolve(dir, 'docs-canonical');
+  const mappings = [
+    { source: 'ARCHITECTURE.md', target: 'architecture.mdx', title: 'Architecture' },
+    { source: 'API-REFERENCE.md', target: 'api-reference.mdx', title: 'API Reference' },
+    { source: 'DATA-MODEL.md', target: 'data-model.mdx', title: 'Data Model' },
+    { source: 'SECURITY.md', target: 'security.mdx', title: 'Security' },
+    { source: 'ENVIRONMENT.md', target: 'environment.mdx', title: 'Environment' },
+    { source: 'TEST-SPEC.md', target: 'test-spec.mdx', title: 'Test Specification' },
+  ];
+
+  for (const mapping of mappings) {
+    const sourcePath = resolve(canonicalDir, mapping.source);
+    if (existsSync(sourcePath)) {
+      let content = readFileSync(sourcePath, 'utf-8');
+
+      // Add Mintlify frontmatter
+      const frontmatter = `---\ntitle: "${mapping.title}"\ndescription: "${config.projectName} ${mapping.title.toLowerCase()}"\n---\n\n`;
+
+      // Remove docguard metadata comments
+      content = content.replace(/<!--\s*docguard:\w+\s+[^>]+\s*-->\n?/g, '');
+      content = content.replace(/> \*\*Auto-generated by DocGuard\.\*\*[^\n]*\n?/g, '');
+
+      writeFileSync(resolve(docsDir, mapping.target), frontmatter + content, 'utf-8');
+      console.log(`  ${c.green}✅ docs/${mapping.target}${c.reset} ← ${mapping.source}`);
+      created++;
+    }
+  }
+
+  // ── Summary ──
+  console.log(`\n${c.bold}  ─────────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.green}Created: ${created} files${c.reset}`);
+  console.log(`\n  ${c.bold}Next steps:${c.reset}`);
+  console.log(`  ${c.cyan}1.${c.reset} Install Mintlify: ${c.dim}npm install -g mintlify${c.reset}`);
+  console.log(`  ${c.cyan}2.${c.reset} Preview locally: ${c.dim}mintlify dev${c.reset}`);
+  console.log(`  ${c.cyan}3.${c.reset} Push to GitHub → auto-deploys on Mintlify${c.reset}`);
+  console.log(`  ${c.dim}\n  Mintlify is free for open-source projects.${c.reset}`);
+  console.log(`  ${c.dim}  Docs: https://mintlify.com/docs${c.reset}\n`);
+}
+
+function buildMintlifyNavigation(dir) {
+  const nav = [
+    {
+      group: "Getting Started",
+      pages: ["introduction", "quickstart"],
+    },
+  ];
+
+  // Add architecture group if docs exist
+  const canonicalDir = resolve(dir, 'docs-canonical');
+  const architecturePages = [];
+  if (existsSync(resolve(canonicalDir, 'ARCHITECTURE.md'))) architecturePages.push("architecture");
+  if (existsSync(resolve(canonicalDir, 'DATA-MODEL.md'))) architecturePages.push("data-model");
+  if (existsSync(resolve(canonicalDir, 'SECURITY.md'))) architecturePages.push("security");
+  if (architecturePages.length > 0) {
+    nav.push({ group: "Architecture", pages: architecturePages });
+  }
+
+  // Add operations group
+  const opsPages = [];
+  if (existsSync(resolve(canonicalDir, 'ENVIRONMENT.md'))) opsPages.push("environment");
+  if (existsSync(resolve(canonicalDir, 'TEST-SPEC.md'))) opsPages.push("test-spec");
+  if (opsPages.length > 0) {
+    nav.push({ group: "Operations", pages: opsPages });
+  }
+
+  // Add API reference
+  if (existsSync(resolve(canonicalDir, 'API-REFERENCE.md'))) {
+    nav.push({ group: "API Reference", pages: ["api-reference"] });
+  }
+
+  return nav;
+}

package/cli/docguard.mjs

@@ -15,7 +15,13 @@
  */
 
 import { readFileSync, existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { resolve, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Read version from package.json (single source of truth)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
+const VERSION = PKG.version;
 import { runAudit } from './commands/audit.mjs';
 import { runInit } from './commands/init.mjs';
 import { runGuard } from './commands/guard.mjs';
@@ -29,6 +35,7 @@ import { runCI } from './commands/ci.mjs';
 import { runFix } from './commands/fix.mjs';
 import { runWatch } from './commands/watch.mjs';
 import { runDiagnose } from './commands/diagnose.mjs';
+import { runPublish } from './commands/publish.mjs';
 
 // ── Colors (ANSI escape codes, zero deps) ──────────────────────────────────
 export const c = {
@@ -253,7 +260,7 @@ function deepMerge(target, source) {
 function printBanner() {
   console.log(`
 ${c.cyan}${c.bold}  ╔═══════════════════════════════════════════╗
-  ║         DocGuard v0.5.0                  ║
+  ║         DocGuard v${VERSION.padEnd(27)}║
   ║   Canonical-Driven Development (CDD)      ║
   ╚═══════════════════════════════════════════╝${c.reset}
 `);
@@ -279,6 +286,7 @@ ${c.bold}Commands:${c.reset}
   ${c.green}ci${c.reset}         Single command for CI/CD pipelines (guard + score)
   ${c.green}fix${c.reset}        Find issues and generate AI fix instructions
   ${c.green}watch${c.reset}      Watch for file changes and re-run guard automatically
+  ${c.green}publish${c.reset}    Scaffold external docs (Mintlify, Docusaurus)
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -295,6 +303,7 @@ ${c.bold}Options:${c.reset}
   --auto          Auto-fix what's possible (used with fix command)
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
   --profile <p>   Compliance profile: starter, standard, enterprise (init command)
+  --platform <p>  Doc platform: mintlify (publish command)
   --tax           Show estimated documentation maintenance cost (with score)
   --help          Show this help message
   --version       Show version
@@ -384,6 +393,9 @@ function main() {
       flags.autoFix = true;
     } else if (args[i] === '--skip-prompts') {
       flags.skipPrompts = true;
+    } else if (args[i] === '--platform' && args[i + 1]) {
+      flags.platform = args[i + 1];
+      i++;
     }
   }
 
@@ -395,7 +407,7 @@ function main() {
   }
 
   if (command === '--version' || command === '-v') {
-    console.log('docguard v0.5.0');
+    console.log(`docguard v${VERSION}`);
     process.exit(0);
   }
 
@@ -448,6 +460,10 @@ function main() {
     case 'watch':
       runWatch(projectDir, config, flags);
       break;
+    case 'publish':
+    case 'pub':
+      runPublish(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/cli/scanners/doc-tools.mjs

@@ -0,0 +1,351 @@
+/**
+ * Doc Tool Detection Scanner
+ * Detects existing documentation tools in a project (OpenAPI, TypeDoc, JSDoc, Storybook, etc.)
+ * and extracts available data from their outputs.
+ * 
+ * Philosophy: Detect and leverage, never replace.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+/**
+ * Detect all documentation tools present in the project.
+ * @param {string} dir - Project root directory
+ * @returns {object} Detected tools with their config and extracted data
+ */
+export function detectDocTools(dir) {
+  const tools = {
+    openapi: detectOpenAPI(dir),
+    typedoc: detectTypeDoc(dir),
+    jsdoc: detectJSDoc(dir),
+    storybook: detectStorybook(dir),
+    docusaurus: detectDocusaurus(dir),
+    mintlify: detectMintlify(dir),
+    redocly: detectRedocly(dir),
+    swagger: detectSwagger(dir),
+  };
+
+  // Count detected tools
+  tools._detected = Object.entries(tools)
+    .filter(([k, v]) => k !== '_detected' && v.found)
+    .map(([k]) => k);
+
+  return tools;
+}
+
+// ── OpenAPI / Swagger Spec ─────────────────────────────────────────────────
+
+function detectOpenAPI(dir) {
+  const candidates = [
+    'openapi.yaml', 'openapi.yml', 'openapi.json',
+    'swagger.yaml', 'swagger.yml', 'swagger.json',
+    'api/openapi.yaml', 'api/openapi.yml', 'api/openapi.json',
+    'docs/openapi.yaml', 'docs/openapi.yml',
+    'spec/openapi.yaml', 'spec/openapi.yml',
+  ];
+
+  for (const candidate of candidates) {
+    const fullPath = resolve(dir, candidate);
+    if (existsSync(fullPath)) {
+      const content = readFileSync(fullPath, 'utf-8');
+      const spec = parseOpenAPISpec(content, candidate);
+      return {
+        found: true,
+        path: candidate,
+        version: spec.version,
+        endpoints: spec.endpoints,
+        schemas: spec.schemas,
+        info: spec.info,
+      };
+    }
+  }
+
+  return { found: false };
+}
+
+function parseOpenAPISpec(content, filename) {
+  const result = { version: null, endpoints: [], schemas: [], info: {} };
+
+  try {
+    let spec;
+    if (filename.endsWith('.json')) {
+      spec = JSON.parse(content);
+    } else {
+      // Simple YAML parsing for common patterns (no dependency)
+      spec = parseSimpleYAML(content);
+    }
+
+    // Version
+    result.version = spec.openapi || spec.swagger || 'unknown';
+
+    // Info
+    result.info = {
+      title: spec.info?.title || '',
+      description: spec.info?.description || '',
+      version: spec.info?.version || '',
+    };
+
+    // Endpoints
+    if (spec.paths) {
+      for (const [path, methods] of Object.entries(spec.paths)) {
+        for (const [method, details] of Object.entries(methods)) {
+          if (['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
+            result.endpoints.push({
+              method: method.toUpperCase(),
+              path,
+              summary: details?.summary || details?.description || '',
+              tags: details?.tags || [],
+              operationId: details?.operationId || '',
+              auth: !!(details?.security?.length),
+            });
+          }
+        }
+      }
+    }
+
+    // Schemas
+    const schemas = spec.components?.schemas || spec.definitions || {};
+    for (const [name, schema] of Object.entries(schemas)) {
+      const fields = [];
+      if (schema.properties) {
+        for (const [fieldName, fieldDef] of Object.entries(schema.properties)) {
+          fields.push({
+            name: fieldName,
+            type: fieldDef.type || fieldDef.$ref?.split('/').pop() || 'object',
+            required: (schema.required || []).includes(fieldName),
+            description: fieldDef.description || '',
+          });
+        }
+      }
+      result.schemas.push({ name, fields, description: schema.description || '' });
+    }
+  } catch { /* spec parsing failed, return empty */ }
+
+  return result;
+}
+
+/**
+ * Minimal YAML parser for OpenAPI specs.
+ * Handles the most common structures without external dependencies.
+ * NOT a full YAML parser — covers 80% of real-world OpenAPI files.
+ */
+function parseSimpleYAML(content) {
+  // Try JSON first (some .yaml files are actually JSON)
+  try { return JSON.parse(content); } catch { /* not JSON */ }
+
+  const result = {};
+  const lines = content.split('\n');
+  const stack = [{ obj: result, indent: -1 }];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+
+    // Pop stack to find parent
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1].obj;
+
+    // Array item
+    if (trimmed.startsWith('- ')) {
+      const value = trimmed.slice(2).trim();
+      if (Array.isArray(parent)) {
+        if (value.includes(':')) {
+          const obj = {};
+          const [k, ...rest] = value.split(':');
+          obj[k.trim()] = rest.join(':').trim().replace(/^['"]|['"]$/g, '');
+          parent.push(obj);
+          stack.push({ obj, indent });
+        } else {
+          parent.push(value.replace(/^['"]|['"]$/g, ''));
+        }
+      }
+      continue;
+    }
+
+    // Key-value pair
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx > 0) {
+      const key = trimmed.substring(0, colonIdx).trim();
+      const rawVal = trimmed.substring(colonIdx + 1).trim();
+
+      if (rawVal === '' || rawVal === '|' || rawVal === '>') {
+        // Nested object or block
+        const child = {};
+        if (typeof parent === 'object' && !Array.isArray(parent)) {
+          parent[key] = child;
+        }
+        stack.push({ obj: child, indent });
+      } else if (rawVal.startsWith('[')) {
+        // Inline array
+        try {
+          parent[key] = JSON.parse(rawVal);
+        } catch {
+          parent[key] = rawVal;
+        }
+      } else {
+        // Simple value
+        let val = rawVal.replace(/^['"]|['"]$/g, '');
+        if (val === 'true') val = true;
+        else if (val === 'false') val = false;
+        else if (/^\d+$/.test(val)) val = parseInt(val);
+        if (typeof parent === 'object' && !Array.isArray(parent)) {
+          parent[key] = val;
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// ── TypeDoc ────────────────────────────────────────────────────────────────
+
+function detectTypeDoc(dir) {
+  const configs = ['typedoc.json', 'typedoc.config.js', 'typedoc.config.mjs'];
+  for (const config of configs) {
+    if (existsSync(resolve(dir, config))) {
+      return { found: true, config };
+    }
+  }
+
+  // Check package.json devDeps
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    if (pkg.devDependencies?.typedoc) {
+      return { found: true, config: 'package.json (devDependency)' };
+    }
+  }
+
+  return { found: false };
+}
+
+// ── JSDoc ──────────────────────────────────────────────────────────────────
+
+function detectJSDoc(dir) {
+  const configs = ['jsdoc.json', '.jsdoc.json', 'jsdoc.conf.json'];
+  for (const config of configs) {
+    if (existsSync(resolve(dir, config))) {
+      return { found: true, config };
+    }
+  }
+
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    if (pkg.devDependencies?.jsdoc) {
+      return { found: true, config: 'package.json (devDependency)' };
+    }
+  }
+
+  return { found: false };
+}
+
+// ── Storybook ──────────────────────────────────────────────────────────────
+
+function detectStorybook(dir) {
+  if (existsSync(resolve(dir, '.storybook'))) {
+    // Count stories
+    let storyCount = 0;
+    const storyDirs = ['src', 'components', 'stories'];
+    for (const sd of storyDirs) {
+      const fullDir = resolve(dir, sd);
+      if (existsSync(fullDir)) {
+        storyCount += countFiles(fullDir, /\.(stories|story)\.(js|jsx|ts|tsx|mdx)$/);
+      }
+    }
+    return { found: true, config: '.storybook/', storyCount };
+  }
+
+  return { found: false };
+}
+
+// ── Docusaurus ─────────────────────────────────────────────────────────────
+
+function detectDocusaurus(dir) {
+  const configs = ['docusaurus.config.js', 'docusaurus.config.ts', 'docusaurus.config.mjs'];
+  for (const config of configs) {
+    if (existsSync(resolve(dir, config))) {
+      return { found: true, config };
+    }
+  }
+  return { found: false };
+}
+
+// ── Mintlify ───────────────────────────────────────────────────────────────
+
+function detectMintlify(dir) {
+  // Check for docs.json (new) or mint.json (legacy)
+  for (const config of ['docs.json', 'mint.json']) {
+    const fullPath = resolve(dir, config);
+    if (existsSync(fullPath)) {
+      try {
+        const content = JSON.parse(readFileSync(fullPath, 'utf-8'));
+        return {
+          found: true,
+          config,
+          name: content.name || '',
+          version: config === 'docs.json' ? 'v2' : 'v1',
+        };
+      } catch {
+        return { found: true, config };
+      }
+    }
+  }
+  return { found: false };
+}
+
+// ── Redocly ────────────────────────────────────────────────────────────────
+
+function detectRedocly(dir) {
+  const configs = ['redocly.yaml', 'redocly.yml', '.redocly.yaml', '.redocly.yml'];
+  for (const config of configs) {
+    if (existsSync(resolve(dir, config))) {
+      return { found: true, config };
+    }
+  }
+  return { found: false };
+}
+
+// ── Swagger UI ─────────────────────────────────────────────────────────────
+
+function detectSwagger(dir) {
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (allDeps['swagger-ui-express'] || allDeps['@fastify/swagger'] || allDeps['swagger-jsdoc']) {
+      return {
+        found: true,
+        middleware: allDeps['swagger-ui-express'] ? 'swagger-ui-express' :
+          allDeps['@fastify/swagger'] ? '@fastify/swagger' : 'swagger-jsdoc',
+      };
+    }
+  }
+  return { found: false };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function countFiles(dir, pattern) {
+  let count = 0;
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        count += countFiles(fullPath, pattern);
+      } else if (pattern.test(entry.name)) {
+        count++;
+      }
+    }
+  } catch { /* skip */ }
+  return count;
+}