create-universal-ai-context 2.0.0 → 2.1.0

package/README.md

@@ -29,36 +29,68 @@ That's it. The CLI automatically:
 
 ```bash
 # Basic usage
-npx create-ai-context                    # Auto-detect and generate for all tools
+npx create-universal-ai-context                    # Auto-detect and generate for all tools
 
 # Select specific AI tools
-npx create-ai-context --ai claude        # Claude Code only
-npx create-ai-context --ai copilot       # GitHub Copilot only
-npx create-ai-context --ai cline         # Cline only
-npx create-ai-context --ai antigravity   # Antigravity only
-npx create-ai-context --ai all           # All tools (default)
+npx create-universal-ai-context --ai claude        # Claude Code only
+npx create-universal-ai-context --ai copilot       # GitHub Copilot only
+npx create-universal-ai-context --ai cline         # Cline only
+npx create-universal-ai-context --ai antigravity   # Antigravity only
+npx create-universal-ai-context --ai all           # All tools (default)
 
 # Analysis modes
-npx create-ai-context --static           # Force static analysis only
-npx create-ai-context --force-ai         # Require Claude Code session
+npx create-universal-ai-context --static           # Force static analysis only
+npx create-universal-ai-context --force-ai         # Require Claude Code session
 
 # Other options
-npx create-ai-context --yes              # Accept all defaults
-npx create-ai-context --dry-run          # Preview without changes
-npx create-ai-context my-project         # Create in new directory
+npx create-universal-ai-context --yes              # Accept all defaults
+npx create-universal-ai-context --dry-run          # Preview without changes
+npx create-universal-ai-context my-project         # Create in new directory
 ```
 
 ## Subcommands
 
 ```bash
 # Generate context for specific tools
-npx create-ai-context generate --ai copilot
+npx create-universal-ai-context generate --ai copilot
 
 # Check installation status
-npx create-ai-context status
+npx create-universal-ai-context status
 
 # Migrate from v1.x
-npx create-ai-context migrate
+npx create-universal-ai-context migrate
+
+# Check documentation drift
+npx create-universal-ai-context drift --all           # Check all docs
+npx create-universal-ai-context drift --file README.md  # Check specific file
+npx create-universal-ai-context drift --fix           # Auto-fix issues
+npx create-universal-ai-context drift --strict        # Exit 1 on issues (CI)
+```
+
+## Existing Documentation Detection
+
+The CLI automatically detects existing AI context files:
+
+```bash
+npx create-universal-ai-context
+
+# Found existing documentation: Claude context (v1), README.md
+# ? How would you like to proceed?
+#   > Merge: Use existing docs as base, add new structure (recommended)
+#     Fresh: Start fresh but import key values
+#     Overwrite: Replace everything with new templates
+#     Skip: Cancel initialization
+```
+
+### Merge Mode Options
+
+```bash
+npx create-universal-ai-context --mode merge          # Preserve customizations (default)
+npx create-universal-ai-context --mode fresh          # New structure, keep values
+npx create-universal-ai-context --mode overwrite      # Replace everything
+npx create-universal-ai-context --preserve-custom     # Keep user customizations
+npx create-universal-ai-context --update-refs         # Auto-fix line numbers
+npx create-universal-ai-context --backup              # Create backup first
 ```
 
 ## What Gets Analyzed
@@ -104,14 +136,14 @@ your-project/
 ## Tech Stack Presets
 
 ```bash
-npx create-ai-context -t python-fastapi
-npx create-ai-context -t python-django
-npx create-ai-context -t node-express
-npx create-ai-context -t node-nestjs
-npx create-ai-context -t typescript-nextjs
-npx create-ai-context -t go-gin
-npx create-ai-context -t rust-actix
-npx create-ai-context -t ruby-rails
+npx create-universal-ai-context -t python-fastapi
+npx create-universal-ai-context -t python-django
+npx create-universal-ai-context -t node-express
+npx create-universal-ai-context -t node-nestjs
+npx create-universal-ai-context -t typescript-nextjs
+npx create-universal-ai-context -t go-gin
+npx create-universal-ai-context -t rust-actix
+npx create-universal-ai-context -t ruby-rails
 ```
 
 ## Features
@@ -134,7 +166,7 @@ npx create-ai-context -t ruby-rails
 If you have an existing `.claude/` directory:
 
 ```bash
-npx create-ai-context migrate
+npx create-universal-ai-context migrate
 ```
 
 This will:

package/bin/create-ai-context.js

@@ -25,6 +25,12 @@ const { migrateV1ToV2, getMigrationStatus } = require('../lib/migrate');
 const { detectTechStack } = require('../lib/detector');
 const { analyzeCodebase } = require('../lib/static-analyzer');
 const { createSpinner } = require('../lib/spinner');
+const {
+  findDocumentationFiles,
+  generateDriftReport,
+  checkDocumentDrift,
+  formatDriftReportConsole
+} = require('../lib/drift-checker');
 const packageJson = require('../package.json');
 
 // ASCII Banner
@@ -70,6 +76,10 @@ program
   .option('--analyze-only', 'Run codebase analysis without installation')
   .option('--monorepo', 'Initialize in monorepo mode with federation support')
   .option('--federate', 'Run federation to generate context for subprojects')
+  .option('--mode <mode>', 'How to handle existing docs: merge, overwrite, interactive', 'merge')
+  .option('--preserve-custom', 'Keep user customizations when merging (default: true)', true)
+  .option('--update-refs', 'Auto-fix drifted line references')
+  .option('--backup', 'Create backup before modifying existing files')
   .action(async (projectName, options) => {
     console.log(banner);
 
@@ -94,7 +104,12 @@ program
         forceStatic: options.static,
         analyzeOnly: options.analyzeOnly,
         monorepo: options.monorepo,
-        federate: options.federate
+        federate: options.federate,
+        // Merge options
+        mode: options.mode,
+        preserveCustom: options.preserveCustom,
+        updateRefs: options.updateRefs,
+        backup: options.backup
       });
     } catch (error) {
       console.error(chalk.red('\n✖ Error:'), error.message);
@@ -334,4 +349,147 @@ program
     }
   });
 
+// Drift subcommand - check documentation drift
+program
+  .command('drift')
+  .description('Check documentation drift against codebase')
+  .option('-f, --file <path>', 'Check specific documentation file')
+  .option('-a, --all', 'Check all documentation files')
+  .option('--fix', 'Show suggested fixes for issues')
+  .option('--strict', 'Exit with error if drift detected')
+  .option('-o, --output <format>', 'Output format: console, json, markdown', 'console')
+  .option('-t, --threshold <percent>', 'Health score threshold for --strict', '70')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+    const spinner = createSpinner();
+
+    try {
+      // Determine which files to check
+      let filesToCheck = [];
+
+      if (options.file) {
+        // Single file mode
+        filesToCheck = [options.file];
+      } else if (options.all) {
+        // All documentation files
+        spinner.start('Finding documentation files...');
+        filesToCheck = await findDocumentationFiles(projectRoot);
+        spinner.succeed(`Found ${filesToCheck.length} documentation files`);
+      } else {
+        // Default: check main context files
+        const defaultFiles = ['CLAUDE.md', 'AI_CONTEXT.md', 'README.md'];
+        filesToCheck = defaultFiles.filter(f =>
+          fs.existsSync(path.join(projectRoot, f))
+        );
+
+        if (filesToCheck.length === 0) {
+          console.log(chalk.yellow('\nNo documentation files found.'));
+          console.log(chalk.gray('Use --all to scan for all markdown files, or --file to check a specific file.'));
+          process.exit(0);
+        }
+      }
+
+      // Generate drift report
+      spinner.start('Checking documentation drift...');
+      const report = generateDriftReport(filesToCheck, projectRoot);
+      spinner.succeed(`Checked ${report.summary.totalDocuments} documents`);
+
+      // Output results
+      if (options.output === 'json') {
+        console.log(JSON.stringify(report, null, 2));
+      } else if (options.output === 'markdown') {
+        console.log(formatDriftReportMarkdown(report));
+      } else {
+        // Console output
+        console.log(formatDriftReportConsole(report));
+      }
+
+      // Show suggested fixes if requested
+      if (options.fix && report.suggestedFixes.length > 0) {
+        console.log(chalk.bold('\nSuggested Fixes:'));
+        for (const fix of report.suggestedFixes) {
+          console.log(chalk.cyan(`\n  ${fix.document}:`));
+          console.log(chalk.red(`    - ${fix.original}`));
+          console.log(chalk.green(`    + ${fix.suggestion}`));
+        }
+      }
+
+      // Strict mode - exit with error if below threshold
+      if (options.strict) {
+        const threshold = parseInt(options.threshold, 10);
+        if (report.summary.overallHealthScore < threshold) {
+          console.log(chalk.red(`\n✖ Health score ${report.summary.overallHealthScore}% is below threshold ${threshold}%`));
+          process.exit(1);
+        } else {
+          console.log(chalk.green(`\n✓ Health score ${report.summary.overallHealthScore}% meets threshold ${threshold}%`));
+        }
+      }
+
+    } catch (error) {
+      spinner.fail('Drift check failed');
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      if (options.verbose) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+/**
+ * Format drift report as markdown
+ */
+function formatDriftReportMarkdown(report) {
+  const lines = [
+    '# Documentation Drift Report',
+    '',
+    `**Generated:** ${report.generatedAt}`,
+    `**Overall Health:** ${report.summary.overallHealthScore}%`,
+    '',
+    '## Summary',
+    '',
+    '| Metric | Value |',
+    '|--------|-------|',
+    `| Documents Analyzed | ${report.summary.totalDocuments} |`,
+    `| Healthy | ${report.summary.healthyDocuments} |`,
+    `| With Issues | ${report.summary.documentsWithIssues} |`,
+    `| References Valid | ${report.summary.validReferences}/${report.summary.totalReferences} |`,
+    ''
+  ];
+
+  if (report.documents.length > 0) {
+    lines.push('## Documents', '');
+    for (const doc of report.documents) {
+      const emoji = doc.status === 'healthy' ? '✓' :
+                    doc.status === 'needs_update' ? '⚠' : '✗';
+      lines.push(`### ${doc.document} (${doc.healthScore}% ${emoji})`);
+      lines.push('');
+
+      if (doc.references.invalid.length > 0) {
+        lines.push('**Issues:**', '');
+        for (const issue of doc.references.invalid) {
+          lines.push(`- \`${issue.original}\` - ${issue.issue}`);
+          if (issue.suggestion) {
+            lines.push(`  - Suggestion: ${issue.suggestion}`);
+          }
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  if (report.suggestedFixes.length > 0) {
+    lines.push('## Suggested Fixes', '');
+    for (const fix of report.suggestedFixes) {
+      lines.push(`- **${fix.document}**: \`${fix.original}\``);
+      lines.push(`  - → ${fix.suggestion}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
 program.parse();