cursor-lint 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-lint",
-  "version": "0.13.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

@@ -7,6 +7,10 @@ const { initProject } = require('./init');
 const { fixProject } = require('./fix');
 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.13.0';
 
@@ -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}
@@ -38,6 +44,11 @@ ${YELLOW}Options:${RESET}
   --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)
@@ -105,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`);
@@ -142,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`);

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/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 };