cursor-lint 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-lint",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Lint your Cursor rules — catch common mistakes before they break your workflow",
   "main": "src/index.js",
   "bin": {

package/src/cli.js

@@ -5,10 +5,14 @@ const { lintProject } = require('./index');
 const { verifyProject } = require('./verify');
 const { initProject } = require('./init');
 const { fixProject } = require('./fix');
-const { generateRules, suggestSkills } = require('./generate');
+const { generateRules, suggestSkills, listPresets, generateFromPreset } = require('./generate');
 const { checkVersions, checkRuleVersionMismatches } = require('./versions');
+const { showStats } = require('./stats');
+const { migrate } = require('./migrate');
+const { doctor } = require('./doctor');
+const { saveSnapshot, diffSnapshot } = require('./diff');
 
-const VERSION = '0.12.0';
+const VERSION = '0.13.0';
 
 const RED = '\x1b[31m';
 const YELLOW = '\x1b[33m';
@@ -18,6 +22,8 @@ const BLUE = '\x1b[34m';
 const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 
+const SNAPSHOT_FILE = '.cursor-lint-snapshot.json';
+
 function showHelp() {
   console.log(`
 ${CYAN}cursor-lint${RESET} v${VERSION}
@@ -34,8 +40,15 @@ ${YELLOW}Options:${RESET}
   --init         Generate starter .mdc rules (auto-detects your stack)
   --fix          Auto-fix common issues (missing frontmatter, alwaysApply)
   --generate     Auto-detect stack & download matching .mdc rules from GitHub
+  --generate --preset <name>  Install rules for a popular stack preset
+  --generate --preset list    Show available presets
   --order        Show rule load order, priority tiers, and token estimates
   --version-check  Detect installed package versions and show relevant rule tips
+  --stats        Show rule health dashboard (counts, tokens, coverage)
+  --migrate      Convert .cursorrules to .cursor/rules/*.mdc format
+  --doctor       Full project health check with letter grade
+  --diff save    Save current rules as snapshot
+  --diff         Compare current rules to saved snapshot
 
 ${YELLOW}What it checks (default):${RESET}
   • .cursorrules files (warns about agent mode compatibility)
@@ -103,6 +116,10 @@ async function main() {
   const isGenerate = args.includes('--generate');
   const isOrder = args.includes('--order');
   const isVersionCheck = args.includes('--version-check');
+  const isStats = args.includes('--stats');
+  const isMigrate = args.includes('--migrate');
+  const isDoctor = args.includes('--doctor');
+  const isDiff = args.includes('--diff');
 
   if (isVersionCheck) {
     console.log(`\n📦 cursor-lint v${VERSION} --version-check\n`);
@@ -140,6 +157,186 @@ async function main() {
     console.log(`${DIM}Use these notes to customize your .mdc rules for your exact versions.${RESET}\n`);
     process.exit(mismatches.length > 0 ? 1 : 0);
 
+  } else if (isStats) {
+    console.log(`\n📊 cursor-lint v${VERSION} --stats\n`);
+    console.log(`Scanning ${cwd}...\n`);
+    const stats = showStats(cwd);
+    
+    // Summary
+    console.log(`${CYAN}Rule files:${RESET}`);
+    console.log(`  .mdc files:     ${stats.mdcFiles.length}`);
+    if (stats.hasCursorrules) console.log(`  .cursorrules:   1 (legacy — run --migrate)`);
+    console.log(`  Skill files:    ${stats.skillFiles.length}`);
+    console.log(`  Total tokens:   ~${stats.totalTokens}`);
+    console.log();
+    
+    // Tier breakdown
+    console.log(`${CYAN}Rule tiers:${RESET}`);
+    console.log(`  Always active:  ${stats.tiers.always}`);
+    console.log(`  Glob-matched:   ${stats.tiers.glob}`);
+    console.log(`  Manual only:    ${stats.tiers.manual}`);
+    console.log();
+    
+    // Token breakdown by file
+    if (stats.mdcFiles.length > 0) {
+      console.log(`${CYAN}Token breakdown:${RESET}`);
+      const sorted = [...stats.mdcFiles].sort((a, b) => b.tokens - a.tokens);
+      for (const f of sorted) {
+        const bar = '█'.repeat(Math.max(1, Math.round(f.tokens / 50)));
+        const pct = Math.round((f.tokens / stats.totalTokens) * 100);
+        console.log(`  ${f.file.padEnd(30)} ${String(f.tokens).padStart(5)} tokens (${String(pct).padStart(2)}%) ${DIM}${bar}${RESET}`);
+      }
+      console.log();
+    }
+    
+    // Coverage gaps
+    if (stats.coverageGaps.length > 0) {
+      console.log(`${YELLOW}Coverage gaps:${RESET}`);
+      for (const gap of stats.coverageGaps) {
+        console.log(`  ${YELLOW}⚠${RESET} ${gap.ext} files found but no matching rule`);
+        console.log(`    ${DIM}→ Try: --generate (suggests ${gap.suggestedRules.join(', ')})${RESET}`);
+      }
+    } else if (stats.mdcFiles.length > 0) {
+      console.log(`${GREEN}✓ No coverage gaps detected${RESET}`);
+    }
+    
+    console.log();
+    process.exit(0);
+
+  } else if (isMigrate) {
+    console.log(`\n🔄 cursor-lint v${VERSION} --migrate\n`);
+    const result = migrate(cwd);
+    
+    if (result.error) {
+      console.log(`${RED}✗${RESET} ${result.error}`);
+      process.exit(1);
+    }
+    
+    console.log(`${CYAN}Source:${RESET} .cursorrules (${result.source.lines} lines, ${result.source.chars} chars)\n`);
+    
+    if (result.created.length > 0) {
+      console.log(`${GREEN}Created:${RESET}`);
+      for (const f of result.created) {
+        console.log(`  ${GREEN}✓${RESET} .cursor/rules/${f}`);
+      }
+    }
+    
+    if (result.skipped.length > 0) {
+      console.log(`${YELLOW}Skipped (already exists):${RESET}`);
+      for (const f of result.skipped) {
+        console.log(`  ${YELLOW}⚠${RESET} .cursor/rules/${f}`);
+      }
+    }
+    
+    console.log();
+    console.log(`${DIM}Your .cursorrules file was NOT deleted — verify the migration, then remove it manually.${RESET}`);
+    console.log(`${DIM}Run cursor-lint to check the new rules.${RESET}\n`);
+    process.exit(0);
+
+  } else if (isDoctor) {
+    console.log(`\n🏥 cursor-lint v${VERSION} --doctor\n`);
+    console.log(`Running full health check on ${cwd}...\n`);
+    const report = await doctor(cwd);
+    
+    // Grade display
+    const gradeColors = { A: GREEN, B: GREEN, C: YELLOW, D: YELLOW, F: RED };
+    const gradeColor = gradeColors[report.grade] || RESET;
+    console.log(`  ${gradeColor}${'━'.repeat(30)}${RESET}`);
+    console.log(`  ${gradeColor}  Project Health: ${report.grade} (${report.percentage}%)  ${RESET}`);
+    console.log(`  ${gradeColor}${'━'.repeat(30)}${RESET}\n`);
+    
+    // Check results
+    for (const check of report.checks) {
+      let icon;
+      if (check.status === 'pass') icon = `${GREEN}✓${RESET}`;
+      else if (check.status === 'warn') icon = `${YELLOW}⚠${RESET}`;
+      else if (check.status === 'fail') icon = `${RED}✗${RESET}`;
+      else icon = `${BLUE}ℹ${RESET}`;
+      
+      console.log(`  ${icon} ${check.name}`);
+      console.log(`    ${DIM}${check.detail}${RESET}`);
+    }
+    
+    console.log();
+    
+    // Suggestions based on grade
+    if (report.grade === 'F' || report.grade === 'D') {
+      console.log(`${YELLOW}Quick wins:${RESET}`);
+      console.log(`  • Run ${CYAN}cursor-lint --init${RESET} to create starter rules`);
+      console.log(`  • Run ${CYAN}cursor-lint --generate${RESET} to download rules for your stack`);
+      if (report.checks.some(c => c.name === 'No legacy .cursorrules' && c.status === 'warn')) {
+        console.log(`  • Run ${CYAN}cursor-lint --migrate${RESET} to convert .cursorrules to .mdc`);
+      }
+    } else if (report.grade === 'C') {
+      console.log(`${YELLOW}Improvements:${RESET}`);
+      console.log(`  • Run ${CYAN}cursor-lint --fix${RESET} to auto-repair common issues`);
+      console.log(`  • Run ${CYAN}cursor-lint --stats${RESET} to find token waste`);
+    }
+    
+    console.log();
+    process.exit(report.grade === 'F' ? 1 : 0);
+
+  } else if (isDiff) {
+    const isDiffSave = args.includes('save');
+    
+    if (isDiffSave) {
+      console.log(`\n📸 cursor-lint v${VERSION} --diff save\n`);
+      const { path: snapPath, state } = saveSnapshot(cwd);
+      const ruleCount = Object.keys(state.rules).length;
+      console.log(`${GREEN}✓${RESET} Snapshot saved to ${path.basename(snapPath)}`);
+      console.log(`  ${DIM}${ruleCount} rule${ruleCount !== 1 ? 's' : ''} captured at ${state.timestamp}${RESET}\n`);
+      console.log(`${DIM}Add ${SNAPSHOT_FILE} to .gitignore, or commit it to track rule changes.${RESET}\n`);
+      process.exit(0);
+    }
+    
+    console.log(`\n📊 cursor-lint v${VERSION} --diff\n`);
+    const changes = diffSnapshot(cwd);
+    
+    if (changes.error) {
+      console.log(`${RED}✗${RESET} ${changes.error}\n`);
+      process.exit(1);
+    }
+    
+    console.log(`${DIM}Comparing to snapshot from ${changes.savedAt}${RESET}\n`);
+    
+    if (!changes.hasChanges) {
+      console.log(`${GREEN}✓ No changes since last snapshot${RESET}\n`);
+      process.exit(0);
+    }
+    
+    if (changes.added.length > 0) {
+      console.log(`${GREEN}Added:${RESET}`);
+      for (const f of changes.added) {
+        console.log(`  ${GREEN}+${RESET} ${f.file} (${f.tokens} tokens, ${f.lines} lines)`);
+      }
+      console.log();
+    }
+    
+    if (changes.removed.length > 0) {
+      console.log(`${RED}Removed:${RESET}`);
+      for (const f of changes.removed) {
+        console.log(`  ${RED}-${RESET} ${f.file} (${f.tokens} tokens, ${f.lines} lines)`);
+      }
+      console.log();
+    }
+    
+    if (changes.modified.length > 0) {
+      console.log(`${YELLOW}Modified:${RESET}`);
+      for (const f of changes.modified) {
+        const tokenDiff = f.newTokens - f.oldTokens;
+        const sign = tokenDiff >= 0 ? '+' : '';
+        console.log(`  ${YELLOW}~${RESET} ${f.file} (${sign}${tokenDiff} tokens, ${f.oldLines}→${f.newLines} lines)`);
+      }
+      console.log();
+    }
+    
+    // Summary
+    const sign = changes.tokenDelta >= 0 ? '+' : '';
+    console.log(`${CYAN}Summary:${RESET} ${changes.added.length} added, ${changes.removed.length} removed, ${changes.modified.length} modified (${sign}${changes.tokenDelta} tokens)\n`);
+    
+    // Exit 1 if changes detected (useful for CI)
+    process.exit(1);
+
   } else if (isOrder) {
     const { showLoadOrder } = require('./order');
     console.log(`\n📋 cursor-lint v${VERSION} --order\n`);
@@ -208,13 +405,85 @@ async function main() {
     process.exit(0);
 
   } else if (isGenerate) {
+    // Check for --preset flag
+    const presetIndex = args.indexOf('--preset');
+    const hasPreset = presetIndex !== -1;
+    const presetValue = hasPreset ? args[presetIndex + 1] : null;
+
+    // Handle --preset list
+    if (hasPreset && presetValue === 'list') {
+      console.log(`\n🚀 cursor-lint v${VERSION} --generate --preset list\n`);
+      console.log(`${CYAN}Available presets:${RESET}\n`);
+      
+      const presets = listPresets();
+      for (const [key, preset] of Object.entries(presets)) {
+        const paddedKey = key.padEnd(12);
+        console.log(`  ${GREEN}${paddedKey}${RESET} ${preset.name} — ${DIM}${preset.description}${RESET}`);
+      }
+      
+      console.log(`\n${YELLOW}Usage:${RESET} cursor-lint --generate --preset t3\n`);
+      process.exit(0);
+    }
+
+    // Handle --preset <name>
+    if (hasPreset && presetValue && presetValue !== 'list') {
+      console.log(`\n🚀 cursor-lint v${VERSION} --generate --preset ${presetValue}\n`);
+      
+      const presets = listPresets();
+      if (!presets[presetValue]) {
+        console.log(`${RED}Unknown preset: ${presetValue}${RESET}\n`);
+        console.log(`Run ${CYAN}cursor-lint --generate --preset list${RESET} to see available presets\n`);
+        process.exit(1);
+      }
+
+      const results = await generateFromPreset(cwd, presetValue);
+      
+      console.log(`${CYAN}Preset:${RESET} ${results.presetInfo.name}`);
+      console.log(`${DIM}${results.presetInfo.description}${RESET}\n`);
+
+      if (results.created.length > 0) {
+        console.log(`${GREEN}Downloaded:${RESET}`);
+        for (const r of results.created) {
+          console.log(`  ${GREEN}✓${RESET} .cursor/rules/${r.file}`);
+        }
+      }
+
+      if (results.skipped.length > 0) {
+        console.log(`\n${YELLOW}Skipped (already exist):${RESET}`);
+        for (const r of results.skipped) {
+          console.log(`  ${YELLOW}⚠${RESET} .cursor/rules/${r.file}`);
+        }
+      }
+
+      if (results.failed.length > 0) {
+        console.log(`\n${RED}Failed:${RESET}`);
+        for (const r of results.failed) {
+          console.log(`  ${RED}✗${RESET} ${r.file} — ${r.error}`);
+        }
+      }
+
+      if (results.created.length > 0) {
+        console.log(`\n${DIM}Run cursor-lint to check these rules${RESET}\n`);
+      }
+
+      process.exit(results.failed.length > 0 ? 1 : 0);
+    }
+
+    // Regular --generate (no preset)
     console.log(`\n🚀 cursor-lint v${VERSION} --generate\n`);
     console.log(`Detecting stack in ${cwd}...\n`);
 
     const results = await generateRules(cwd);
 
     if (results.detected.length > 0) {
-      console.log(`${CYAN}Detected:${RESET} ${results.detected.join(', ')}\n`);
+      console.log(`${CYAN}Detected stack:${RESET} ${results.detected.join(', ')}`);
+      
+      // Show versions if available
+      if (results.versions && Object.keys(results.versions).length > 0) {
+        const versionStrs = Object.entries(results.versions).map(([dep, ver]) => `${dep}@${ver}`);
+        console.log(`${CYAN}Versions:${RESET} ${versionStrs.join(', ')}`);
+      }
+      console.log();
     } else {
       console.log(`${YELLOW}No recognized stack detected.${RESET}`);
       console.log(`${DIM}Supports: package.json, tsconfig.json, requirements.txt, pyproject.toml,${RESET}`);
@@ -250,6 +519,13 @@ async function main() {
       }
     }
 
+    if (results.fallbacks && results.fallbacks.length > 0) {
+      console.log(`\n${YELLOW}Fallbacks (version-specific rule not found):${RESET}`);
+      for (const r of results.fallbacks) {
+        console.log(`  ${YELLOW}⚠${RESET} ${r.from} → ${r.to} ${DIM}(${r.stack})${RESET}`);
+      }
+    }
+
     if (results.failed.length > 0) {
       console.log(`\n${RED}Failed:${RESET}`);
       for (const r of results.failed) {

package/src/diff.js

@@ -0,0 +1,93 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const SNAPSHOT_FILE = '.cursor-lint-snapshot.json';
+
+function hashContent(content) {
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+function captureState(dir) {
+  const state = { rules: {}, cursorrules: null, timestamp: new Date().toISOString() };
+
+  // .cursorrules
+  const cursorrules = path.join(dir, '.cursorrules');
+  if (fs.existsSync(cursorrules)) {
+    const content = fs.readFileSync(cursorrules, 'utf-8');
+    state.cursorrules = { hash: hashContent(content), tokens: estimateTokens(content), lines: content.split('\n').length };
+  }
+
+  // .cursor/rules/*.mdc
+  const rulesDir = path.join(dir, '.cursor', 'rules');
+  if (fs.existsSync(rulesDir) && fs.statSync(rulesDir).isDirectory()) {
+    for (const entry of fs.readdirSync(rulesDir).filter(f => f.endsWith('.mdc')).sort()) {
+      const content = fs.readFileSync(path.join(rulesDir, entry), 'utf-8');
+      state.rules[entry] = { hash: hashContent(content), tokens: estimateTokens(content), lines: content.split('\n').length };
+    }
+  }
+
+  return state;
+}
+
+function saveSnapshot(dir) {
+  const state = captureState(dir);
+  const snapshotPath = path.join(dir, SNAPSHOT_FILE);
+  fs.writeFileSync(snapshotPath, JSON.stringify(state, null, 2), 'utf-8');
+  return { path: snapshotPath, state };
+}
+
+function diffSnapshot(dir) {
+  const snapshotPath = path.join(dir, SNAPSHOT_FILE);
+  if (!fs.existsSync(snapshotPath)) {
+    return { error: 'No snapshot found. Run cursor-lint --diff save first.' };
+  }
+
+  const saved = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
+  const current = captureState(dir);
+
+  const changes = { added: [], removed: [], modified: [], unchanged: [], tokenDelta: 0, savedAt: saved.timestamp };
+
+  // Compare rules
+  const allFiles = new Set([...Object.keys(saved.rules), ...Object.keys(current.rules)]);
+  
+  for (const file of allFiles) {
+    const s = saved.rules[file];
+    const c = current.rules[file];
+
+    if (!s && c) {
+      changes.added.push({ file, tokens: c.tokens, lines: c.lines });
+      changes.tokenDelta += c.tokens;
+    } else if (s && !c) {
+      changes.removed.push({ file, tokens: s.tokens, lines: s.lines });
+      changes.tokenDelta -= s.tokens;
+    } else if (s.hash !== c.hash) {
+      changes.modified.push({ file, oldTokens: s.tokens, newTokens: c.tokens, oldLines: s.lines, newLines: c.lines });
+      changes.tokenDelta += (c.tokens - s.tokens);
+    } else {
+      changes.unchanged.push(file);
+    }
+  }
+
+  // .cursorrules changes
+  if (!saved.cursorrules && current.cursorrules) {
+    changes.added.push({ file: '.cursorrules', tokens: current.cursorrules.tokens, lines: current.cursorrules.lines });
+    changes.tokenDelta += current.cursorrules.tokens;
+  } else if (saved.cursorrules && !current.cursorrules) {
+    changes.removed.push({ file: '.cursorrules', tokens: saved.cursorrules.tokens, lines: saved.cursorrules.lines });
+    changes.tokenDelta -= saved.cursorrules.tokens;
+  } else if (saved.cursorrules && current.cursorrules && saved.cursorrules.hash !== current.cursorrules.hash) {
+    changes.modified.push({ file: '.cursorrules', oldTokens: saved.cursorrules.tokens, newTokens: current.cursorrules.tokens, oldLines: saved.cursorrules.lines, newLines: current.cursorrules.lines });
+    changes.tokenDelta += (current.cursorrules.tokens - saved.cursorrules.tokens);
+  }
+
+  changes.hasChanges = changes.added.length > 0 || changes.removed.length > 0 || changes.modified.length > 0;
+
+  return changes;
+}
+
+module.exports = { saveSnapshot, diffSnapshot, captureState };

package/src/doctor.js

@@ -0,0 +1,134 @@
+const fs = require('fs');
+const path = require('path');
+const { lintProject } = require('./index');
+const { showStats } = require('./stats');
+
+async function doctor(dir) {
+  const report = {
+    checks: [],
+    score: 0,
+    maxScore: 0,
+    grade: 'F',
+  };
+
+  // 1. Check if any rules exist at all
+  report.maxScore += 20;
+  const rulesDir = path.join(dir, '.cursor', 'rules');
+  const hasMdc = fs.existsSync(rulesDir) && fs.readdirSync(rulesDir).filter(f => f.endsWith('.mdc')).length > 0;
+  const hasCursorrules = fs.existsSync(path.join(dir, '.cursorrules'));
+  
+  if (hasMdc) {
+    report.score += 20;
+    report.checks.push({ name: 'Rules exist', status: 'pass', detail: '.cursor/rules/ found with .mdc files' });
+  } else if (hasCursorrules) {
+    report.score += 5;
+    report.checks.push({ name: 'Rules exist', status: 'warn', detail: 'Only .cursorrules found — run --migrate to convert to .mdc format' });
+  } else {
+    report.checks.push({ name: 'Rules exist', status: 'fail', detail: 'No rules found. Run --init or --generate to create rules.' });
+  }
+
+  // 2. Check for .cursorrules (should be migrated)
+  report.maxScore += 10;
+  if (hasCursorrules && hasMdc) {
+    report.score += 5;
+    report.checks.push({ name: 'No legacy .cursorrules', status: 'warn', detail: '.cursorrules exists alongside .mdc rules — may cause conflicts. Consider removing it.' });
+  } else if (!hasCursorrules) {
+    report.score += 10;
+    report.checks.push({ name: 'No legacy .cursorrules', status: 'pass', detail: 'Good — using modern .mdc format only' });
+  } else {
+    report.checks.push({ name: 'No legacy .cursorrules', status: 'warn', detail: 'Using legacy .cursorrules — run --migrate to convert' });
+  }
+
+  // 3. Run lint checks and count issues
+  report.maxScore += 30;
+  const lintResults = await lintProject(dir);
+  let errors = 0;
+  let warnings = 0;
+  for (const r of lintResults) {
+    for (const i of r.issues) {
+      if (i.severity === 'error') errors++;
+      else if (i.severity === 'warning') warnings++;
+    }
+  }
+  
+  if (errors === 0 && warnings === 0) {
+    report.score += 30;
+    report.checks.push({ name: 'Lint checks', status: 'pass', detail: 'All rules pass lint checks' });
+  } else if (errors === 0) {
+    report.score += 20;
+    report.checks.push({ name: 'Lint checks', status: 'warn', detail: `${warnings} warning${warnings !== 1 ? 's' : ''} found. Run cursor-lint to see details.` });
+  } else {
+    report.score += Math.max(0, 10 - errors * 2);
+    report.checks.push({ name: 'Lint checks', status: 'fail', detail: `${errors} error${errors !== 1 ? 's' : ''}, ${warnings} warning${warnings !== 1 ? 's' : ''}. Run cursor-lint to fix.` });
+  }
+
+  // 4. Token budget check
+  report.maxScore += 15;
+  const stats = showStats(dir);
+  if (stats.totalTokens === 0) {
+    report.checks.push({ name: 'Token budget', status: 'info', detail: 'No rules to measure' });
+  } else if (stats.totalTokens < 2000) {
+    report.score += 15;
+    report.checks.push({ name: 'Token budget', status: 'pass', detail: `~${stats.totalTokens} tokens — well within budget` });
+  } else if (stats.totalTokens < 5000) {
+    report.score += 10;
+    report.checks.push({ name: 'Token budget', status: 'warn', detail: `~${stats.totalTokens} tokens — getting heavy. Consider trimming or splitting rules.` });
+  } else {
+    report.score += 5;
+    report.checks.push({ name: 'Token budget', status: 'fail', detail: `~${stats.totalTokens} tokens — very heavy. This eats into your context window every request.` });
+  }
+
+  // 5. Coverage gaps
+  report.maxScore += 15;
+  if (stats.coverageGaps.length === 0) {
+    report.score += 15;
+    report.checks.push({ name: 'Coverage', status: 'pass', detail: 'Rules cover your project file types' });
+  } else if (stats.coverageGaps.length <= 2) {
+    report.score += 10;
+    const gaps = stats.coverageGaps.map(g => g.ext).join(', ');
+    report.checks.push({ name: 'Coverage', status: 'warn', detail: `Missing rules for: ${gaps}. Run --generate to add them.` });
+  } else {
+    report.score += 5;
+    const gaps = stats.coverageGaps.map(g => g.ext).join(', ');
+    report.checks.push({ name: 'Coverage', status: 'fail', detail: `Missing rules for: ${gaps}. Run --generate to add them.` });
+  }
+
+  // 6. Skills check
+  report.maxScore += 10;
+  const skillDirs = [
+    path.join(dir, '.claude', 'skills'),
+    path.join(dir, '.cursor', 'skills'),
+    path.join(dir, 'skills'),
+  ];
+  const hasSkills = skillDirs.some(sd => {
+    if (!fs.existsSync(sd)) return false;
+    try {
+      return fs.readdirSync(sd).some(e => {
+        const sub = path.join(sd, e);
+        return fs.statSync(sub).isDirectory() && fs.existsSync(path.join(sub, 'SKILL.md'));
+      });
+    } catch { return false; }
+  });
+  
+  if (hasSkills) {
+    report.score += 10;
+    report.checks.push({ name: 'Agent skills', status: 'pass', detail: 'Skills directory found' });
+  } else {
+    report.score += 5; // not having skills is fine, just not optimal
+    report.checks.push({ name: 'Agent skills', status: 'info', detail: 'No agent skills found. Skills are optional but can improve agent behavior for complex workflows.' });
+  }
+
+  // Calculate grade
+  const pct = (report.score / report.maxScore) * 100;
+  if (pct >= 90) report.grade = 'A';
+  else if (pct >= 75) report.grade = 'B';
+  else if (pct >= 60) report.grade = 'C';
+  else if (pct >= 40) report.grade = 'D';
+  else report.grade = 'F';
+  
+  report.percentage = Math.round(pct);
+
+  return report;
+}
+
+module.exports = { doctor };

package/src/generate.js

@@ -4,6 +4,32 @@ const https = require('https');
 
 const BASE_URL = 'https://raw.githubusercontent.com/nedcodes-ok/cursorrules-collection/main/rules-mdc/';
 
+// Version-specific rule overrides: if user has react 19, use react-19.mdc instead of react.mdc
+const VERSION_RULES = {
+  'react': {
+    '19': 'frameworks/react-19.mdc',
+    '18': 'frameworks/react-18.mdc',
+  },
+  'next': {
+    '15': 'frameworks/nextjs-15.mdc',
+    '14': 'frameworks/nextjs-14.mdc',
+    '13': 'frameworks/nextjs-13.mdc',
+  },
+  'vue': {
+    '3': 'frameworks/vue-3.mdc',
+    '2': 'frameworks/vue-2.mdc',
+  },
+  '@angular/core': {
+    '19': 'frameworks/angular-19.mdc',
+    '18': 'frameworks/angular-18.mdc',
+    '17': 'frameworks/angular-17.mdc',
+  },
+  'svelte': {
+    '5': 'frameworks/svelte-5.mdc',
+    '4': 'frameworks/svelte-4.mdc',
+  },
+};
+
 // package.json dependencies → rule files
 const PKG_DEP_MAP = {
   // Frameworks
@@ -189,6 +215,7 @@ function detectStack(cwd) {
   const detected = [];
   const rules = new Map(); // rulePath -> stackName
   const allDetectedDeps = [];
+  const versions = {}; // dep -> version string
 
   // package.json
   const pkgPath = path.join(cwd, 'package.json');
@@ -201,7 +228,21 @@ function detectStack(cwd) {
         if (pkgDeps[dep]) {
           detected.push(dep);
           allDetectedDeps.push(dep);
-          rules.set(rule, dep);
+          
+          // Extract version
+          const rawVersion = pkgDeps[dep];
+          versions[dep] = rawVersion;
+          
+          // Parse major version (strip ^, ~, >=, etc.)
+          const versionMatch = rawVersion.match(/(\d+)/);
+          const majorVersion = versionMatch ? versionMatch[1] : null;
+          
+          // Check if version-specific rule exists
+          if (majorVersion && VERSION_RULES[dep] && VERSION_RULES[dep][majorVersion]) {
+            rules.set(VERSION_RULES[dep][majorVersion], dep);
+          } else {
+            rules.set(rule, dep);
+          }
         }
       }
     } catch {}
@@ -406,18 +447,19 @@ function detectStack(cwd) {
     }
   }
 
-  return { detected, rules };
+  return { detected, rules, versions };
 }
 
 async function generateRules(cwd) {
-  const { detected, rules } = detectStack(cwd);
+  const { detected, rules, versions } = detectStack(cwd);
   const rulesDir = path.join(cwd, '.cursor', 'rules');
   const created = [];
   const skipped = [];
   const failed = [];
+  const fallbacks = [];
 
   if (rules.size === 0) {
-    return { detected, created, skipped, failed };
+    return { detected, created, skipped, failed, versions };
   }
 
   fs.mkdirSync(rulesDir, { recursive: true });
@@ -437,13 +479,130 @@ async function generateRules(cwd) {
       fs.writeFileSync(destPath, content, 'utf8');
       created.push({ file: filename, stack: stackName });
     } catch (err) {
-      failed.push({ file: filename, stack: stackName, error: err.message });
+      // Try fallback to generic rule if this was a version-specific rule
+      const genericRule = PKG_DEP_MAP[stackName];
+      if (genericRule && genericRule !== rulePath) {
+        try {
+          const fallbackUrl = BASE_URL + genericRule;
+          const content = await fetchFile(fallbackUrl);
+          const genericFilename = path.basename(genericRule);
+          const genericDestPath = path.join(rulesDir, genericFilename);
+          fs.writeFileSync(genericDestPath, content, 'utf8');
+          created.push({ file: genericFilename, stack: stackName });
+          fallbacks.push({ from: filename, to: genericFilename, stack: stackName });
+        } catch (fallbackErr) {
+          failed.push({ file: filename, stack: stackName, error: err.message });
+        }
+      } else {
+        failed.push({ file: filename, stack: stackName, error: err.message });
+      }
     }
   }
 
-  return { detected, created, skipped, failed };
+  return { detected, created, skipped, failed, versions, fallbacks };
 }
 
+const STACK_PRESETS = {
+  't3': {
+    name: 'T3 Stack',
+    description: 'Next.js + TypeScript + Tailwind + tRPC + Prisma + NextAuth',
+    rules: [
+      'languages/typescript.mdc',
+      'frameworks/nextjs.mdc',
+      'frameworks/tailwind-css.mdc',
+      'frameworks/zod.mdc',
+      'frameworks/t3-stack.mdc',
+      'tools/trpc.mdc',
+      'tools/prisma.mdc',
+      'tools/nextauth.mdc',
+      'practices/clean-code.mdc',
+      'practices/error-handling.mdc',
+    ],
+  },
+  'mern': {
+    name: 'MERN Stack',
+    description: 'MongoDB + Express + React + Node.js',
+    rules: [
+      'languages/typescript.mdc',
+      'languages/javascript.mdc',
+      'frameworks/react.mdc',
+      'frameworks/express.mdc',
+      'tools/mongodb.mdc',
+      'practices/api-design.mdc',
+      'practices/error-handling.mdc',
+      'practices/clean-code.mdc',
+    ],
+  },
+  'fastapi': {
+    name: 'Python FastAPI',
+    description: 'FastAPI + Pydantic + SQLAlchemy + pytest',
+    rules: [
+      'languages/python.mdc',
+      'frameworks/fastapi.mdc',
+      'tools/pydantic.mdc',
+      'tools/sqlalchemy.mdc',
+      'tools/pytest.mdc',
+      'practices/api-design.mdc',
+      'practices/error-handling.mdc',
+      'practices/clean-code.mdc',
+    ],
+  },
+  'sveltekit': {
+    name: 'SvelteKit Full Stack',
+    description: 'SvelteKit + Svelte + Tailwind + Prisma + TypeScript',
+    rules: [
+      'languages/typescript.mdc',
+      'frameworks/sveltekit.mdc',
+      'frameworks/svelte.mdc',
+      'frameworks/tailwind-css.mdc',
+      'tools/prisma.mdc',
+      'practices/clean-code.mdc',
+      'practices/error-handling.mdc',
+    ],
+  },
+  'rails': {
+    name: 'Ruby on Rails',
+    description: 'Rails + Ruby + PostgreSQL + Testing',
+    rules: [
+      'languages/ruby.mdc',
+      'frameworks/rails.mdc',
+      'tools/postgresql.mdc',
+      'practices/testing.mdc',
+      'practices/api-design.mdc',
+      'practices/database-migrations.mdc',
+      'practices/clean-code.mdc',
+    ],
+  },
+  'nextjs': {
+    name: 'Next.js Full Stack',
+    description: 'Next.js + React + TypeScript + Tailwind + Prisma',
+    rules: [
+      'languages/typescript.mdc',
+      'frameworks/nextjs.mdc',
+      'frameworks/react.mdc',
+      'frameworks/tailwind-css.mdc',
+      'tools/prisma.mdc',
+      'practices/clean-code.mdc',
+      'practices/performance.mdc',
+      'practices/error-handling.mdc',
+    ],
+  },
+  'django': {
+    name: 'Django Full Stack',
+    description: 'Django + Python + PostgreSQL + pytest',
+    rules: [
+      'languages/python.mdc',
+      'frameworks/django.mdc',
+      'tools/postgresql.mdc',
+      'tools/pytest.mdc',
+      'practices/api-design.mdc',
+      'practices/database-migrations.mdc',
+      'practices/security.mdc',
+      'practices/clean-code.mdc',
+    ],
+  },
+};
+
 const SKILLS_API = 'https://skills.sh/api/search';
 
 function searchSkillsAPI(query, limit) {
@@ -497,4 +656,43 @@ async function suggestSkills(detected) {
   return allResults.slice(0, 10);
 }
 
-module.exports = { generateRules, suggestSkills };
+function listPresets() {
+  return STACK_PRESETS;
+}
+
+async function generateFromPreset(cwd, presetName) {
+  const preset = STACK_PRESETS[presetName];
+  if (!preset) {
+    throw new Error(`Unknown preset: ${presetName}`);
+  }
+
+  const rulesDir = path.join(cwd, '.cursor', 'rules');
+  const created = [];
+  const skipped = [];
+  const failed = [];
+
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  for (const rulePath of preset.rules) {
+    const filename = path.basename(rulePath);
+    const destPath = path.join(rulesDir, filename);
+
+    if (fs.existsSync(destPath)) {
+      skipped.push({ file: filename, rule: rulePath });
+      continue;
+    }
+
+    try {
+      const url = BASE_URL + rulePath;
+      const content = await fetchFile(url);
+      fs.writeFileSync(destPath, content, 'utf8');
+      created.push({ file: filename, rule: rulePath });
+    } catch (err) {
+      failed.push({ file: filename, rule: rulePath, error: err.message });
+    }
+  }
+
+  return { preset: presetName, presetInfo: preset, created, skipped, failed };
+}
+
+module.exports = { generateRules, suggestSkills, listPresets, generateFromPreset };

package/src/migrate.js

@@ -0,0 +1,118 @@
+const fs = require('fs');
+const path = require('path');
+
+function migrate(dir) {
+  const cursorrules = path.join(dir, '.cursorrules');
+  const result = { created: [], skipped: [], source: null, error: null };
+
+  if (!fs.existsSync(cursorrules)) {
+    result.error = 'No .cursorrules file found in this directory';
+    return result;
+  }
+
+  const content = fs.readFileSync(cursorrules, 'utf-8').trim();
+  result.source = { file: '.cursorrules', chars: content.length, lines: content.split('\n').length };
+
+  if (content.length === 0) {
+    result.error = '.cursorrules file is empty';
+    return result;
+  }
+
+  const rulesDir = path.join(dir, '.cursor', 'rules');
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  // Try to split by markdown headings (## or #)
+  const sections = splitBySections(content);
+
+  if (sections.length <= 1) {
+    // Single file migration
+    const filename = 'project-rules.mdc';
+    const destPath = path.join(rulesDir, filename);
+    if (fs.existsSync(destPath)) {
+      result.skipped.push(filename);
+    } else {
+      const mdc = wrapInMdc(content, 'Project rules migrated from .cursorrules');
+      fs.writeFileSync(destPath, mdc, 'utf-8');
+      result.created.push(filename);
+    }
+  } else {
+    // Multi-file migration
+    for (const section of sections) {
+      const filename = slugify(section.title) + '.mdc';
+      const destPath = path.join(rulesDir, filename);
+      if (fs.existsSync(destPath)) {
+        result.skipped.push(filename);
+      } else {
+        const mdc = wrapInMdc(section.body, section.title);
+        fs.writeFileSync(destPath, mdc, 'utf-8');
+        result.created.push(filename);
+      }
+    }
+  }
+
+  return result;
+}
+
+function splitBySections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let currentTitle = null;
+  let currentBody = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^#{1,2}\s+(.+)/);
+    if (headingMatch) {
+      if (currentTitle !== null) {
+        sections.push({ title: currentTitle, body: currentBody.join('\n').trim() });
+      }
+      currentTitle = headingMatch[1].trim();
+      currentBody = [];
+    } else {
+      currentBody.push(line);
+    }
+  }
+
+  // Push last section
+  if (currentTitle !== null) {
+    sections.push({ title: currentTitle, body: currentBody.join('\n').trim() });
+  }
+
+  // If no headings found, check for content before first heading
+  if (sections.length === 0) {
+    return [{ title: 'Project Rules', body: content }];
+  }
+
+  // If there's content before the first heading, include it
+  const firstHeadingIdx = content.search(/^#{1,2}\s+/m);
+  if (firstHeadingIdx > 0) {
+    const preamble = content.slice(0, firstHeadingIdx).trim();
+    if (preamble.length > 20) {
+      sections.unshift({ title: 'General', body: preamble });
+    }
+  }
+
+  // Filter out empty sections
+  return sections.filter(s => s.body.length > 10);
+}
+
+function slugify(title) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'rule';
+}
+
+function wrapInMdc(body, description) {
+  return `---
+description: "${description.replace(/"/g, '\\"')}"
+alwaysApply: true
+---
+
+${body}
+`;
+}
+
+module.exports = { migrate };

package/src/stats.js

@@ -0,0 +1,183 @@
+const fs = require('fs');
+const path = require('path');
+
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { found: false, data: null };
+  const data = {};
+  const lines = match[1].split('\n');
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const rawVal = line.slice(colonIdx + 1).trim();
+    if (rawVal === 'true') data[key] = true;
+    else if (rawVal === 'false') data[key] = false;
+    else if (rawVal.startsWith('"') && rawVal.endsWith('"')) data[key] = rawVal.slice(1, -1);
+    else data[key] = rawVal;
+  }
+  return { found: true, data };
+}
+
+function parseGlobs(globVal) {
+  if (!globVal) return [];
+  if (typeof globVal === 'string') {
+    const trimmed = globVal.trim();
+    if (trimmed.startsWith('[')) {
+      return trimmed.slice(1, -1).split(',').map(g => g.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    }
+    return trimmed.split(',').map(g => g.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  }
+  if (Array.isArray(globVal)) return globVal;
+  return [];
+}
+
+function getProjectFileExtensions(dir) {
+  const extensions = new Set();
+  const ignoreDirs = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.cursor', '__pycache__', '.venv', 'venv']);
+  
+  function walk(d, depth) {
+    if (depth > 3) return; // don't go too deep
+    try {
+      for (const entry of fs.readdirSync(d)) {
+        if (ignoreDirs.has(entry)) continue;
+        const full = path.join(d, entry);
+        try {
+          const stat = fs.statSync(full);
+          if (stat.isDirectory()) {
+            walk(full, depth + 1);
+          } else {
+            const ext = path.extname(entry);
+            if (ext) extensions.add(ext);
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+  walk(dir, 0);
+  return extensions;
+}
+
+// Map file extensions to what kind of rules would cover them
+const EXT_TO_CATEGORY = {
+  '.ts': ['typescript', 'react', 'nextjs', 'angular', 'nestjs'],
+  '.tsx': ['typescript', 'react', 'nextjs'],
+  '.js': ['javascript', 'react', 'nextjs', 'express', 'node'],
+  '.jsx': ['javascript', 'react'],
+  '.py': ['python', 'django', 'fastapi', 'flask'],
+  '.rb': ['ruby', 'rails'],
+  '.go': ['go'],
+  '.rs': ['rust'],
+  '.java': ['java', 'spring-boot'],
+  '.kt': ['kotlin'],
+  '.swift': ['swift'],
+  '.php': ['php', 'laravel'],
+  '.vue': ['vue', 'nuxt'],
+  '.svelte': ['svelte', 'sveltekit'],
+  '.css': ['tailwind-css'],
+  '.scss': ['tailwind-css'],
+  '.html': [],
+  '.json': [],
+  '.yaml': [],
+  '.yml': [],
+  '.md': [],
+  '.mdc': [],
+};
+
+function showStats(dir) {
+  const stats = {
+    mdcFiles: [],
+    hasCursorrules: false,
+    cursorrulesTokens: 0,
+    skillFiles: [],
+    totalTokens: 0,
+    tiers: { always: 0, glob: 0, manual: 0 },
+    coverageGaps: [],
+    projectExtensions: new Set(),
+    coveredExtensions: new Set(),
+  };
+
+  // .cursorrules
+  const cursorrules = path.join(dir, '.cursorrules');
+  if (fs.existsSync(cursorrules)) {
+    stats.hasCursorrules = true;
+    const content = fs.readFileSync(cursorrules, 'utf-8');
+    stats.cursorrulesTokens = estimateTokens(content);
+    stats.totalTokens += stats.cursorrulesTokens;
+  }
+
+  // .cursor/rules/*.mdc
+  const rulesDir = path.join(dir, '.cursor', 'rules');
+  if (fs.existsSync(rulesDir) && fs.statSync(rulesDir).isDirectory()) {
+    for (const entry of fs.readdirSync(rulesDir)) {
+      if (!entry.endsWith('.mdc')) continue;
+      const filePath = path.join(rulesDir, entry);
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const tokens = estimateTokens(content);
+      const fm = parseFrontmatter(content);
+      
+      let tier = 'manual';
+      let globs = [];
+      if (fm.found && fm.data) {
+        globs = parseGlobs(fm.data.globs);
+        if (fm.data.alwaysApply === true) tier = 'always';
+        else if (globs.length > 0) tier = 'glob';
+      }
+      
+      stats.tiers[tier]++;
+      stats.totalTokens += tokens;
+      stats.mdcFiles.push({ file: entry, tokens, tier, globs });
+      
+      // Track covered extensions from globs
+      for (const g of globs) {
+        const extMatch = g.match(/\*\.(\w+)$/);
+        if (extMatch) stats.coveredExtensions.add('.' + extMatch[1]);
+      }
+    }
+  }
+
+  // Skill files
+  const skillDirs = [
+    path.join(dir, '.claude', 'skills'),
+    path.join(dir, '.cursor', 'skills'),
+    path.join(dir, 'skills'),
+  ];
+  for (const sd of skillDirs) {
+    if (!fs.existsSync(sd)) continue;
+    try {
+      for (const entry of fs.readdirSync(sd)) {
+        const sub = path.join(sd, entry);
+        if (fs.statSync(sub).isDirectory()) {
+          const skillMd = path.join(sub, 'SKILL.md');
+          if (fs.existsSync(skillMd)) {
+            const content = fs.readFileSync(skillMd, 'utf-8');
+            stats.skillFiles.push({ file: path.relative(dir, skillMd), tokens: estimateTokens(content) });
+            stats.totalTokens += estimateTokens(content);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  // Coverage analysis
+  stats.projectExtensions = getProjectFileExtensions(dir);
+  
+  // Find gaps: project has files of type X but no rule covers them
+  const ruleNames = stats.mdcFiles.map(f => f.file.replace('.mdc', '').toLowerCase());
+  for (const ext of stats.projectExtensions) {
+    const categories = EXT_TO_CATEGORY[ext];
+    if (!categories || categories.length === 0) continue;
+    const covered = categories.some(cat => ruleNames.some(r => r.includes(cat)));
+    if (!covered && !stats.coveredExtensions.has(ext)) {
+      stats.coverageGaps.push({ ext, suggestedRules: categories });
+    }
+  }
+
+  return stats;
+}
+
+module.exports = { showStats };