cursor-lint 0.5.0 → 0.7.0

package/package.json

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

package/src/cli.js

@@ -7,7 +7,7 @@ const { initProject } = require('./init');
 const { fixProject } = require('./fix');
 const { generateRules } = require('./generate');
 
-const VERSION = '0.5.0';
+const VERSION = '0.7.0';
 
 const RED = '\x1b[31m';
 const YELLOW = '\x1b[33m';
@@ -32,6 +32,7 @@ ${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
 
 ${YELLOW}What it checks (default):${RESET}
   • .cursorrules files (warns about agent mode compatibility)
@@ -88,8 +89,76 @@ async function main() {
   const isInit = args.includes('--init');
   const isFix = args.includes('--fix');
   const isGenerate = args.includes('--generate');
+  const isOrder = args.includes('--order');
 
-  if (isGenerate) {
+  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/index.js

@@ -76,7 +76,7 @@ async function lintMdcFile(filePath) {
     if (!fm.data.description) {
       issues.push({ severity: 'warning', message: 'Missing description in frontmatter', hint: 'Add a description so Cursor knows when to apply this rule' });
     }
-    if (fm.data.globs && typeof fm.data.globs === 'string' && fm.data.globs.includes(',')) {
+    if (fm.data.globs && typeof fm.data.globs === 'string' && fm.data.globs.includes(',') && !fm.data.globs.trim().startsWith('[')) {
       issues.push({ severity: 'error', message: 'Globs should be YAML array, not comma-separated string', hint: 'Use globs:\\n  - "*.ts"\\n  - "*.tsx"' });
     }
   }
@@ -141,7 +141,146 @@ async function lintProject(dir) {
     });
   }
 
+  // Conflict detection across .mdc files
+  const conflicts = detectConflicts(dir);
+  if (conflicts.length > 0) {
+    results.push({
+      file: path.join(dir, '.cursor/rules/'),
+      issues: conflicts,
+    });
+  }
+
   return results;
 }
 
-module.exports = { lintProject, lintMdcFile, lintCursorrules };
+function parseGlobs(globVal) {
+  if (!globVal) return [];
+  if (typeof globVal === 'string') {
+    // Handle both YAML array syntax and comma-separated
+    const trimmed = globVal.trim();
+    if (trimmed.startsWith('[')) {
+      // ["*.ts", "*.tsx"] format
+      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 globsOverlap(globsA, globsB) {
+  // If either has no globs (alwaysApply), they overlap with everything
+  if (globsA.length === 0 || globsB.length === 0) return true;
+
+  for (const a of globsA) {
+    for (const b of globsB) {
+      // Exact match
+      if (a === b) return true;
+      // Both are wildcards covering same extension
+      const extA = a.match(/^\*\.(\w+)$/);
+      const extB = b.match(/^\*\.(\w+)$/);
+      if (extA && extB && extA[1] === extB[1]) return true;
+      // One is a superset pattern like **/*.ts
+      if (a.includes('**') || b.includes('**')) {
+        const extA2 = a.match(/\*\.(\w+)$/);
+        const extB2 = b.match(/\*\.(\w+)$/);
+        if (extA2 && extB2 && extA2[1] === extB2[1]) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function extractDirectives(content) {
+  // Extract actionable instructions from rule body (after frontmatter)
+  const body = content.replace(/^---[\s\S]*?---\n?/, '').toLowerCase();
+  const directives = [];
+
+  // Look for contradictory patterns: "always use X" vs "never use X"
+  const alwaysMatch = body.match(/always\s+use\s+(\S+)/g) || [];
+  const neverMatch = body.match(/never\s+use\s+(\S+)/g) || [];
+  const preferMatch = body.match(/prefer\s+(\S+)/g) || [];
+  const avoidMatch = body.match(/avoid\s+(\S+)/g) || [];
+  const doNotMatch = body.match(/do\s+not\s+use\s+(\S+)/g) || [];
+
+  for (const m of alwaysMatch) directives.push({ type: 'require', subject: m.replace(/^always\s+use\s+/, '') });
+  for (const m of neverMatch) directives.push({ type: 'forbid', subject: m.replace(/^never\s+use\s+/, '') });
+  for (const m of preferMatch) directives.push({ type: 'prefer', subject: m.replace(/^prefer\s+/, '') });
+  for (const m of avoidMatch) directives.push({ type: 'avoid', subject: m.replace(/^avoid\s+/, '') });
+  for (const m of doNotMatch) directives.push({ type: 'forbid', subject: m.replace(/^do\s+not\s+use\s+/, '') });
+
+  return directives;
+}
+
+function detectConflicts(dir) {
+  const rulesDir = path.join(dir, '.cursor', 'rules');
+  if (!fs.existsSync(rulesDir) || !fs.statSync(rulesDir).isDirectory()) return [];
+
+  const files = fs.readdirSync(rulesDir).filter(f => f.endsWith('.mdc'));
+  if (files.length < 2) return [];
+
+  const parsed = [];
+  for (const file of files) {
+    const filePath = path.join(rulesDir, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const fm = parseFrontmatter(content);
+    const globs = fm.data ? parseGlobs(fm.data.globs) : [];
+    const alwaysApply = fm.data && fm.data.alwaysApply;
+    const directives = extractDirectives(content);
+    parsed.push({ file, filePath, globs, alwaysApply, directives, content });
+  }
+
+  const issues = [];
+
+  // Check for duplicate alwaysApply rules with overlapping globs
+  for (let i = 0; i < parsed.length; i++) {
+    for (let j = i + 1; j < parsed.length; j++) {
+      const a = parsed[i];
+      const b = parsed[j];
+
+      // Check glob overlap
+      const aGlobs = a.alwaysApply && a.globs.length === 0 ? [] : a.globs;
+      const bGlobs = b.alwaysApply && b.globs.length === 0 ? [] : b.globs;
+      const overlap = globsOverlap(aGlobs, bGlobs);
+
+      if (!overlap) continue;
+
+      // Check for contradictory directives
+      for (const dA of a.directives) {
+        for (const dB of b.directives) {
+          if (dA.subject !== dB.subject) continue;
+
+          const contradicts =
+            (dA.type === 'require' && (dB.type === 'forbid' || dB.type === 'avoid')) ||
+            (dA.type === 'forbid' && (dB.type === 'require' || dB.type === 'prefer')) ||
+            (dA.type === 'prefer' && dB.type === 'forbid') ||
+            (dA.type === 'avoid' && dB.type === 'require');
+
+          if (contradicts) {
+            issues.push({
+              severity: 'error',
+              message: `Conflicting rules: ${a.file} says "${dA.type} ${dA.subject}" but ${b.file} says "${dB.type} ${dB.subject}"`,
+              hint: 'Conflicting directives confuse the model. Remove or reconcile one of these rules.',
+            });
+          }
+        }
+      }
+
+      // Check for duplicate glob coverage (both alwaysApply targeting same files)
+      if (a.alwaysApply && b.alwaysApply && a.globs.length > 0 && b.globs.length > 0) {
+        const sharedGlobs = a.globs.filter(g => b.globs.includes(g));
+        if (sharedGlobs.length > 0) {
+          issues.push({
+            severity: 'warning',
+            message: `Overlapping globs: ${a.file} and ${b.file} both target ${sharedGlobs.join(', ')}`,
+            hint: 'Multiple rules targeting the same files may cause unpredictable behavior. Consider merging them.',
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+module.exports = { lintProject, lintMdcFile, lintCursorrules, detectConflicts };

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