cursor-lint 0.6.0 → 0.8.0

package/README.md

@@ -77,9 +77,42 @@ cursor-lint exits with code 1 when errors are found. Add it to your pipeline:
 ## Options
 
 ```
-cursor-lint [directory]    Lint rules in directory (default: current dir)
-cursor-lint --help         Show help
-cursor-lint --version      Show version
+cursor-lint [directory]       Lint rules in directory (default: current dir)
+cursor-lint --fix             Auto-fix common issues (missing frontmatter, alwaysApply)
+cursor-lint --generate        Auto-detect stack & download matching rules from collection
+cursor-lint --verify          Check if code follows rules with verify: blocks
+cursor-lint --order           Show rule load order, priority tiers, and token estimates
+cursor-lint --version-check   Detect installed versions, show relevant features & rule mismatches
+cursor-lint --init            Generate starter rules (auto-detects your stack)
+cursor-lint --help            Show help
+cursor-lint --version         Show version
+```
+
+### --version-check
+
+Reads your `package.json`, `requirements.txt`, or `pyproject.toml` and tells you:
+1. **Version-specific features** available in your installed packages (e.g., "React 19+: use useActionState")
+2. **Rule mismatches** — if your `.mdc` rules reference version features your installed packages don't support
+
+```bash
+npx cursor-lint --version-check
+```
+
+```
+📦 cursor-lint v0.8.0 --version-check
+
+Version-specific features available:
+
+  react (^19.0.0)
+    → React 19+: use useActionState (replaces useFormState), use() hook
+    → React 18+: useId, useSyncExternalStore, automatic batching
+
+  next (^14.2.0)
+    → Next.js 14+: Server Actions stable, partial prerendering (preview)
+
+Version mismatches in your rules:
+
+  ⚠ nextjs.mdc:5 — Rule references 15+ but next ^14.2.0 is installed
 ```
 
 ## Based on Real Testing
@@ -102,6 +135,6 @@ Made by [nedcodes](https://dev.to/nedcodes) · [Free rules collection](https://g
 
 ## Related
 
-- [cursorrules-collection](https://github.com/cursorrulespacks/cursorrules-collection) — 77+ free .mdc rules
+- [cursorrules-collection](https://github.com/cursorrulespacks/cursorrules-collection) — 104 free .mdc rules
 - [Cursor Setup Audit](https://cursorrulespacks.gumroad.com/l/cursor-setup-audit) — Professional review of your rules setup ($50)
 - [Articles on Dev.to](https://dev.to/nedcodes) — Guides on writing effective Cursor rules

package/package.json

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

package/src/cli.js

@@ -6,8 +6,9 @@ const { verifyProject } = require('./verify');
 const { initProject } = require('./init');
 const { fixProject } = require('./fix');
 const { generateRules } = require('./generate');
+const { checkVersions, checkRuleVersionMismatches } = require('./versions');
 
-const VERSION = '0.6.0';
+const VERSION = '0.8.0';
 
 const RED = '\x1b[31m';
 const YELLOW = '\x1b[33m';
@@ -32,6 +33,8 @@ ${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
+  --order        Show rule load order, priority tiers, and token estimates
+  --version-check  Detect installed package versions and show relevant rule tips
 
 ${YELLOW}What it checks (default):${RESET}
   • .cursorrules files (warns about agent mode compatibility)
@@ -88,8 +91,113 @@ async function main() {
   const isInit = args.includes('--init');
   const isFix = args.includes('--fix');
   const isGenerate = args.includes('--generate');
+  const isOrder = args.includes('--order');
+  const isVersionCheck = args.includes('--version-check');
 
-  if (isGenerate) {
+  if (isVersionCheck) {
+    console.log(`\n📦 cursor-lint v${VERSION} --version-check\n`);
+    console.log(`Detecting installed versions in ${cwd}...\n`);
+
+    const versionNotes = checkVersions(cwd);
+    const mismatches = checkRuleVersionMismatches(cwd);
+
+    if (versionNotes.length === 0 && mismatches.length === 0) {
+      console.log(`${YELLOW}No version-specific notes found.${RESET}`);
+      console.log(`${DIM}Supports: package.json, requirements.txt, pyproject.toml${RESET}\n`);
+      process.exit(0);
+    }
+
+    if (versionNotes.length > 0) {
+      console.log(`${CYAN}Version-specific features available:${RESET}\n`);
+      for (const item of versionNotes) {
+        console.log(`  ${GREEN}${item.package}${RESET} ${DIM}(${item.installedVersion})${RESET}`);
+        for (const note of item.notes) {
+          console.log(`    ${DIM}→${RESET} ${note}`);
+        }
+        console.log();
+      }
+    }
+
+    if (mismatches.length > 0) {
+      console.log(`${YELLOW}Version mismatches in your rules:${RESET}\n`);
+      for (const m of mismatches) {
+        console.log(`  ${YELLOW}⚠${RESET} ${m.file}:${m.line} — ${m.message}`);
+      }
+      console.log();
+    }
+
+    console.log('─'.repeat(50));
+    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 (isOrder) {
+    const { showLoadOrder } = require('./order');
+    console.log(`\n📋 cursor-lint v${VERSION} --order\n`);
+    const dir = args.find(a => !a.startsWith('-')) ? path.resolve(args.find(a => !a.startsWith('-'))) : cwd;
+    console.log(`Analyzing rule load order in ${dir}...\n`);
+
+    const results = showLoadOrder(dir);
+
+    if (results.rules.length === 0) {
+      console.log(`${YELLOW}No rules found.${RESET}\n`);
+      process.exit(0);
+    }
+
+    // Show .cursorrules warning if present
+    if (results.hasCursorrules) {
+      console.log(`${YELLOW}⚠ .cursorrules found${RESET} — overridden by any .mdc rule covering the same topic`);
+      console.log(`${DIM}  .mdc files always take precedence when both exist${RESET}\n`);
+    }
+
+    // Group by priority tier
+    const tiers = {
+      'always': { label: 'Always Active', color: GREEN, rules: [] },
+      'glob': { label: 'File-Scoped (glob match)', color: CYAN, rules: [] },
+      'manual': { label: 'Manual Only (no alwaysApply, no globs)', color: DIM, rules: [] },
+    };
+
+    for (const rule of results.rules) {
+      tiers[rule.tier].rules.push(rule);
+    }
+
+    let position = 1;
+    for (const [key, tier] of Object.entries(tiers)) {
+      if (tier.rules.length === 0) continue;
+      console.log(`${tier.color}── ${tier.label} ──${RESET}`);
+      for (const rule of tier.rules) {
+        const globs = rule.globs.length > 0 ? ` ${DIM}[${rule.globs.join(', ')}]${RESET}` : '';
+        const desc = rule.description ? ` ${DIM}— ${rule.description}${RESET}` : '';
+        const size = ` ${DIM}(${rule.lines} lines, ~${rule.tokens} tokens)${RESET}`;
+        console.log(`  ${position}. ${rule.file}${globs}${desc}${size}`);
+        position++;
+      }
+      console.log();
+    }
+
+    // Token budget warning
+    const totalTokens = results.rules.reduce((s, r) => s + r.tokens, 0);
+    const alwaysTokens = tiers.always.rules.reduce((s, r) => s + r.tokens, 0);
+    console.log('─'.repeat(50));
+    console.log(`${CYAN}Total rules:${RESET} ${results.rules.length}`);
+    console.log(`${CYAN}Always-active token estimate:${RESET} ~${alwaysTokens} tokens`);
+    console.log(`${CYAN}All rules token estimate:${RESET} ~${totalTokens} tokens`);
+
+    if (alwaysTokens > 4000) {
+      console.log(`\n${YELLOW}⚠ Your always-active rules use ~${alwaysTokens} tokens.${RESET}`);
+      console.log(`${DIM}  Large rule sets eat into your context window. Consider moving some to glob-scoped rules.${RESET}`);
+    }
+
+    if (results.warnings.length > 0) {
+      console.log();
+      for (const w of results.warnings) {
+        console.log(`${YELLOW}⚠ ${w}${RESET}`);
+      }
+    }
+
+    console.log();
+    process.exit(0);
+
+  } else if (isGenerate) {
     console.log(`\n🚀 cursor-lint v${VERSION} --generate\n`);
     console.log(`Detecting stack in ${cwd}...\n`);
 

package/src/order.js

@@ -0,0 +1,131 @@
+const fs = require('fs');
+const path = require('path');
+
+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);
+  }
+  return [];
+}
+
+function estimateTokens(text) {
+  // Rough estimate: ~4 chars per token for English text
+  return Math.ceil(text.length / 4);
+}
+
+function showLoadOrder(dir) {
+  const results = {
+    hasCursorrules: false,
+    rules: [],
+    warnings: [],
+  };
+
+  // Check for .cursorrules
+  const cursorrules = path.join(dir, '.cursorrules');
+  if (fs.existsSync(cursorrules)) {
+    results.hasCursorrules = true;
+    const content = fs.readFileSync(cursorrules, 'utf-8');
+    const lines = content.split('\n').length;
+    results.rules.push({
+      file: '.cursorrules',
+      tier: 'always',
+      globs: [],
+      description: '(legacy format)',
+      alwaysApply: true,
+      lines,
+      tokens: estimateTokens(content),
+      priority: 0, // lowest priority — overridden by .mdc
+    });
+  }
+
+  // Check .cursor/rules/*.mdc
+  const rulesDir = path.join(dir, '.cursor', 'rules');
+  if (fs.existsSync(rulesDir) && fs.statSync(rulesDir).isDirectory()) {
+    const files = fs.readdirSync(rulesDir).filter(f => f.endsWith('.mdc')).sort();
+
+    for (const file of files) {
+      const filePath = path.join(rulesDir, file);
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const fm = parseFrontmatter(content);
+      const lines = content.split('\n').length;
+      const tokens = estimateTokens(content);
+
+      if (!fm.found || !fm.data) {
+        results.rules.push({
+          file,
+          tier: 'manual',
+          globs: [],
+          description: '(no frontmatter)',
+          alwaysApply: false,
+          lines,
+          tokens,
+        });
+        results.warnings.push(`${file}: Missing frontmatter — rule may not load at all`);
+        continue;
+      }
+
+      const globs = parseGlobs(fm.data.globs);
+      const alwaysApply = fm.data.alwaysApply === true;
+      const description = fm.data.description || '';
+
+      let tier;
+      if (alwaysApply) {
+        tier = 'always';
+      } else if (globs.length > 0) {
+        tier = 'glob';
+      } else {
+        tier = 'manual';
+        results.warnings.push(`${file}: No alwaysApply and no globs — this rule may never activate in agent mode`);
+      }
+
+      results.rules.push({
+        file,
+        tier,
+        globs,
+        description,
+        alwaysApply,
+        lines,
+        tokens,
+      });
+    }
+  }
+
+  // Sort within tiers: always first, then glob, then manual
+  // Within each tier, sort by filename (alphabetical = filesystem order)
+  const tierOrder = { always: 0, glob: 1, manual: 2 };
+  results.rules.sort((a, b) => {
+    if (tierOrder[a.tier] !== tierOrder[b.tier]) return tierOrder[a.tier] - tierOrder[b.tier];
+    // .cursorrules always last within 'always' tier (lowest priority)
+    if (a.file === '.cursorrules') return -1;
+    if (b.file === '.cursorrules') return 1;
+    return a.file.localeCompare(b.file);
+  });
+
+  return results;
+}
+
+module.exports = { showLoadOrder };

package/src/versions.js

@@ -0,0 +1,225 @@
+const fs = require('fs');
+const path = require('path');
+
+// Map of package names to their version-specific rule notes
+// Each entry: { package, minVersion, note }
+const VERSION_NOTES = [
+  // React
+  { package: 'react', minVersion: '19.0.0', note: 'React 19+: use useActionState (replaces useFormState), use() hook for promises/context' },
+  { package: 'react', minVersion: '18.0.0', note: 'React 18+: useId, useSyncExternalStore, automatic batching, Suspense for data fetching' },
+
+  // Next.js
+  { package: 'next', minVersion: '15.0.0', note: 'Next.js 15+: async request APIs (cookies/headers/params are now async), Turbopack stable' },
+  { package: 'next', minVersion: '14.0.0', note: 'Next.js 14+: Server Actions stable, partial prerendering (preview), Metadata API improvements' },
+  { package: 'next', minVersion: '13.4.0', note: 'Next.js 13.4+: App Router stable, Server Components default. Pages Router is legacy' },
+
+  // Vue
+  { package: 'vue', minVersion: '3.4.0', note: 'Vue 3.4+: defineModel(), improved reactivity, v-bind shorthand' },
+  { package: 'vue', minVersion: '3.3.0', note: 'Vue 3.3+: generic components, defineSlots, defineOptions' },
+
+  // Angular
+  { package: '@angular/core', minVersion: '18.0.0', note: 'Angular 18+: stable signals, zoneless change detection (experimental), @let template syntax' },
+  { package: '@angular/core', minVersion: '17.0.0', note: 'Angular 17+: new control flow (@if/@for/@switch), deferrable views (@defer), signal inputs/outputs' },
+
+  // Prisma
+  { package: 'prisma', minVersion: '5.0.0', note: 'Prisma 5+: JSON protocol default, improved query engine, Prisma Client extensions stable' },
+  { package: '@prisma/client', minVersion: '5.0.0', note: 'Prisma 5+: $extends replaces middleware (deprecated), improved type safety' },
+
+  // Tailwind
+  { package: 'tailwindcss', minVersion: '4.0.0', note: 'Tailwind v4+: CSS-first config, no tailwind.config.js needed, @theme directive, automatic content detection' },
+  { package: 'tailwindcss', minVersion: '3.4.0', note: 'Tailwind 3.4+: size-* utility (replaces w-* h-* pairs), has-* and group-has-* variants' },
+  { package: 'tailwindcss', minVersion: '3.3.0', note: 'Tailwind 3.3+: ESM config support, logical properties, overflow-clip utility' },
+
+  // TypeScript
+  { package: 'typescript', minVersion: '5.5.0', note: 'TypeScript 5.5+: inferred type predicates, config extends from multiple files' },
+  { package: 'typescript', minVersion: '5.0.0', note: 'TypeScript 5+: decorators (TC39 standard), const type parameters, --moduleResolution bundler' },
+
+  // Express
+  { package: 'express', minVersion: '5.0.0', note: 'Express 5+: async error handling built-in (no more express-async-errors), path route matching changes' },
+
+  // Pydantic (Python)
+  { package: 'pydantic', minVersion: '2.0.0', note: 'Pydantic v2+: model_validator/field_validator replace validator/root_validator, ConfigDict replaces Config class, 5-50x faster' },
+
+  // FastAPI (Python)
+  { package: 'fastapi', minVersion: '0.100.0', note: 'FastAPI 0.100+: Annotated dependencies preferred, Pydantic v2 support, lifespan replaces on_event' },
+
+  // Django (Python)
+  { package: 'django', minVersion: '5.0', note: 'Django 5+: GeneratedField, Field.db_default, facet filters in admin, simplified templates' },
+  { package: 'django', minVersion: '4.2', note: 'Django 4.2+: psycopg 3 support, comments on columns/tables, custom file storage' },
+];
+
+/**
+ * Parse a semver-ish string into comparable parts.
+ * Handles: "5.0.0", "^5.0.0", "~5.0.0", ">=5.0.0", "5.0", "5"
+ */
+function parseVersion(v) {
+  if (!v) return null;
+  const cleaned = v.replace(/^[\^~>=<]+/, '').trim();
+  const parts = cleaned.split('.').map(Number);
+  return {
+    major: parts[0] || 0,
+    minor: parts[1] || 0,
+    patch: parts[2] || 0,
+  };
+}
+
+function versionGte(installed, required) {
+  const a = parseVersion(installed);
+  const b = parseVersion(required);
+  if (!a || !b) return false;
+  if (a.major !== b.major) return a.major > b.major;
+  if (a.minor !== b.minor) return a.minor > b.minor;
+  return a.patch >= b.patch;
+}
+
+/**
+ * Detect installed versions from package.json and Python config files.
+ * Returns Map<packageName, versionString>
+ */
+function detectVersions(cwd) {
+  const versions = new Map();
+
+  // package.json
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      for (const [name, version] of Object.entries(allDeps)) {
+        versions.set(name, version);
+      }
+    } catch {}
+  }
+
+  // pyproject.toml (basic parsing)
+  const pyprojectPath = path.join(cwd, 'pyproject.toml');
+  if (fs.existsSync(pyprojectPath)) {
+    try {
+      const content = fs.readFileSync(pyprojectPath, 'utf8');
+      // Match lines like: django = ">=4.2" or django = {version = ">=4.2"}
+      const depRegex = /^(\w[\w-]*)\s*=\s*"([^"]+)"/gm;
+      let match;
+      while ((match = depRegex.exec(content)) !== null) {
+        versions.set(match[1].toLowerCase(), match[2]);
+      }
+    } catch {}
+  }
+
+  // requirements.txt
+  const reqPath = path.join(cwd, 'requirements.txt');
+  if (fs.existsSync(reqPath)) {
+    try {
+      const lines = fs.readFileSync(reqPath, 'utf8').split('\n');
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        // Match: django>=4.2, django==4.2.0, django~=4.2
+        const match = trimmed.match(/^([\w-]+)\s*([><=~!]+)\s*([\d.]+)/);
+        if (match) {
+          versions.set(match[1].toLowerCase(), match[3]);
+        }
+      }
+    } catch {}
+  }
+
+  return versions;
+}
+
+/**
+ * Check installed versions against version notes.
+ * Returns array of { package, installedVersion, notes[] }
+ */
+function checkVersions(cwd) {
+  const versions = detectVersions(cwd);
+  const results = [];
+
+  // Group notes by package
+  const notesByPkg = new Map();
+  for (const note of VERSION_NOTES) {
+    if (!notesByPkg.has(note.package)) notesByPkg.set(note.package, []);
+    notesByPkg.get(note.package).push(note);
+  }
+
+  for (const [pkg, notes] of notesByPkg) {
+    const installed = versions.get(pkg);
+    if (!installed) continue;
+
+    const applicable = [];
+    for (const note of notes) {
+      if (versionGte(installed, note.minVersion)) {
+        applicable.push(note.note);
+      }
+    }
+
+    if (applicable.length > 0) {
+      results.push({
+        package: pkg,
+        installedVersion: installed,
+        notes: applicable,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Scan .mdc rules for version references that don't match installed versions.
+ * Returns array of { file, line, message }
+ */
+function checkRuleVersionMismatches(cwd) {
+  const versions = detectVersions(cwd);
+  const warnings = [];
+  const rulesDir = path.join(cwd, '.cursor', 'rules');
+
+  if (!fs.existsSync(rulesDir)) return warnings;
+
+  const files = fs.readdirSync(rulesDir).filter(f => f.endsWith('.mdc'));
+
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(rulesDir, file), 'utf8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Check for version references like "v14+", "v3.4+", "(v5+)", "17+"
+      const versionRefs = line.matchAll(/\b(?:v|version\s*)?([\d]+(?:\.[\d]+)*)\+/gi);
+      for (const match of versionRefs) {
+        const refVersion = match[1];
+        // Try to find which package this might relate to based on the file name
+        const fileBase = file.replace('.mdc', '').toLowerCase();
+
+        // Map filenames to package names
+        const fileToPackage = {
+          'nextjs': 'next',
+          'react': 'react',
+          'vue': 'vue',
+          'angular': '@angular/core',
+          'tailwind-css': 'tailwindcss',
+          'typescript': 'typescript',
+          'prisma': 'prisma',
+          'express': 'express',
+          'django': 'django',
+          'fastapi': 'fastapi',
+        };
+
+        const pkg = fileToPackage[fileBase];
+        if (pkg && versions.has(pkg)) {
+          const installed = versions.get(pkg);
+          if (!versionGte(installed, refVersion)) {
+            warnings.push({
+              file,
+              line: i + 1,
+              message: `Rule references ${refVersion}+ but ${pkg} ${installed} is installed`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return warnings;
+}
+
+module.exports = { detectVersions, checkVersions, checkRuleVersionMismatches, parseVersion, versionGte };