cursor-lint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nedcodes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# cursor-lint
+
+Lint your [Cursor](https://cursor.com) rules. Catch common mistakes before they silently break your workflow.
+
+```bash
+npx cursor-lint
+```
+
+```
+🔍 cursor-lint v0.1.0
+
+.cursorrules
+  ⚠ .cursorrules may be ignored in agent mode
+    → Use .cursor/rules/*.mdc with alwaysApply: true
+
+.cursor/rules/code.mdc
+  ✗ Missing alwaysApply: true
+    → Add alwaysApply: true to frontmatter for agent mode
+  ⚠ Vague rule detected: "write clean code" (line 6)
+
+.cursor/rules/memory.mdc
+  ✓ All checks passed
+
+──────────────────────────────────────────────────
+1 error, 2 warnings, 1 passed
+```
+
+## Why
+
+Cursor rules fail silently. You won't know your rules are broken until the AI ignores them. Common mistakes:
+
+- Using `.cursorrules` instead of `.mdc` files (agent mode ignores `.cursorrules`)
+- Missing `alwaysApply: true` (rules never load)
+- Vague instructions ("write clean code") that have zero effect
+- Files too long for the context window
+- Bad YAML frontmatter or glob syntax
+
+cursor-lint catches all of these in seconds.
+
+## Install
+
+```bash
+# Run directly (no install)
+npx cursor-lint
+
+# Or install globally
+npm install -g cursor-lint
+```
+
+## What It Checks
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| `.cursorrules` in agent mode | ⚠ Warning | Agent mode ignores `.cursorrules` — use `.mdc` files |
+| Missing `alwaysApply: true` | ✗ Error | `.mdc` files without this won't load in agent mode |
+| Missing `description` | ⚠ Warning | Cursor uses description to decide when to apply rules |
+| Bad glob syntax | ✗ Error | Comma-separated globs should be YAML arrays |
+| Vague rules | ⚠ Warning | Generic instructions like "follow best practices" have no effect |
+| File too long | ⚠/✗ | Files over 150 lines may not fit in context window |
+| Bad frontmatter | ✗ Error | Malformed YAML frontmatter won't parse |
+
+## CI/CD
+
+cursor-lint exits with code 1 when errors are found. Add it to your pipeline:
+
+```yaml
+# GitHub Actions
+- name: Lint Cursor rules
+  run: npx cursor-lint
+```
+
+## Options
+
+```
+cursor-lint [directory]    Lint rules in directory (default: current dir)
+cursor-lint --help         Show help
+cursor-lint --version      Show version
+```
+
+## Based on Real Testing
+
+Every check in cursor-lint comes from [actual experiments](https://dev.to/nedcodes) testing what Cursor does and doesn't follow. Not guesswork — data.
+
+## License
+
+MIT
+
+---
+
+Made by [nedcodes](https://dev.to/nedcodes)

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "cursor-lint",
+  "version": "0.1.0",
+  "description": "Lint your Cursor rules — catch common mistakes before they break your workflow",
+  "main": "src/index.js",
+  "bin": {
+    "cursor-lint": "src/cli.js"
+  },
+  "keywords": [
+    "cursor",
+    "cursor-ai",
+    "cursorrules",
+    "mdc",
+    "linter",
+    "developer-tools"
+  ],
+  "author": "nedcodes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cursorrulespacks/cursor-lint.git"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "src/"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { lintProject } = require('./index');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+cursor-lint — Lint your Cursor rules
+
+Usage:
+  cursor-lint [directory]    Lint rules in directory (default: current dir)
+  cursor-lint --help         Show this help
+  cursor-lint --version      Show version
+
+Checks:
+  ✗ Missing alwaysApply: true in .mdc files
+  ✗ Bad YAML frontmatter / glob syntax
+  ⚠ .cursorrules ignored in agent mode
+  ⚠ Vague rules ("write clean code", etc.)
+  ⚠ Files too long for context window
+`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../package.json');
+  console.log(`cursor-lint v${pkg.version}`);
+  process.exit(0);
+}
+
+const dir = args[0] ? path.resolve(args[0]) : process.cwd();
+
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const GREEN = '\x1b[32m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+async function main() {
+  console.log(`\n🔍 cursor-lint v${require('../package.json').version}\n`);
+  console.log(`Scanning ${dir}...\n`);
+
+  const results = await lintProject(dir);
+
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalPassed = 0;
+
+  for (const result of results) {
+    const relPath = path.relative(dir, result.file) || result.file;
+    console.log(relPath);
+
+    if (result.issues.length === 0) {
+      console.log(`  ${GREEN}✓ All checks passed${RESET}`);
+      totalPassed++;
+    } else {
+      for (const issue of result.issues) {
+        const icon = issue.severity === 'error' ? `${RED}✗${RESET}` : `${YELLOW}⚠${RESET}`;
+        const lineInfo = issue.line ? ` ${DIM}(line ${issue.line})${RESET}` : '';
+        console.log(`  ${icon} ${issue.message}${lineInfo}`);
+        if (issue.hint) {
+          console.log(`    ${DIM}→ ${issue.hint}${RESET}`);
+        }
+      }
+      const errors = result.issues.filter(i => i.severity === 'error').length;
+      const warnings = result.issues.filter(i => i.severity === 'warning').length;
+      totalErrors += errors;
+      totalWarnings += warnings;
+      if (errors === 0 && warnings === 0) totalPassed++;
+    }
+    console.log();
+  }
+
+  console.log('─'.repeat(50));
+  const parts = [];
+  if (totalErrors > 0) parts.push(`${RED}${totalErrors} error${totalErrors !== 1 ? 's' : ''}${RESET}`);
+  if (totalWarnings > 0) parts.push(`${YELLOW}${totalWarnings} warning${totalWarnings !== 1 ? 's' : ''}${RESET}`);
+  if (totalPassed > 0) parts.push(`${GREEN}${totalPassed} passed${RESET}`);
+  console.log(parts.join(', ') + '\n');
+
+  process.exit(totalErrors > 0 ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,165 @@
+const fs = require('fs');
+const path = require('path');
+
+const VAGUE_PATTERNS = [
+  'write clean code',
+  'follow best practices',
+  'be consistent',
+  'write maintainable code',
+  'handle errors properly',
+  'use proper naming',
+  'keep it simple',
+  'write readable code',
+  'follow conventions',
+  'use good patterns',
+  'write efficient code',
+  'be careful',
+  'think before coding',
+  'write good tests',
+  'follow solid principles',
+  'use common sense',
+  'write quality code',
+  'follow the style guide',
+  'be thorough',
+  'write robust code',
+  'use good naming',
+  'be helpful',
+  'use appropriate patterns',
+  'be concise',
+];
+
+const MAX_LINES_WARNING = 150;
+const MAX_LINES_ERROR = 300;
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { found: false, data: null, error: null };
+
+  try {
+    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();
+      // Check for bad indentation (key starts with space = likely nested/broken YAML)
+      if (line.match(/^\s+\S/) && !line.match(/^\s+-/)) {
+        // Indented non-list line where we don't expect it
+        const prevLine = lines[lines.indexOf(line) - 1];
+        if (prevLine && !prevLine.endsWith(':')) {
+          return { found: true, data: null, error: 'Invalid YAML indentation' };
+        }
+      }
+      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, error: null };
+  } catch (e) {
+    return { found: true, data: null, error: e.message };
+  }
+}
+
+async function lintMdcFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const issues = [];
+  const lines = content.split('\n');
+
+  const fm = parseFrontmatter(content);
+
+  if (!fm.found) {
+    issues.push({ severity: 'error', message: 'Missing YAML frontmatter', hint: 'Add --- block with description and alwaysApply: true' });
+  } else if (fm.error) {
+    issues.push({ severity: 'error', message: `YAML frontmatter error: ${fm.error}`, hint: 'Fix frontmatter indentation/syntax' });
+  } else {
+    if (!fm.data.alwaysApply) {
+      issues.push({ severity: 'error', message: 'Missing alwaysApply: true', hint: 'Add alwaysApply: true to frontmatter for agent mode' });
+    }
+    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(',')) {
+      issues.push({ severity: 'error', message: 'Globs should be YAML array, not comma-separated string', hint: 'Use globs:\\n  - "*.ts"\\n  - "*.tsx"' });
+    }
+  }
+
+  // Vague rules
+  const contentLower = content.toLowerCase();
+  for (const pattern of VAGUE_PATTERNS) {
+    const idx = contentLower.indexOf(pattern);
+    if (idx !== -1) {
+      const lineNum = content.slice(0, idx).split('\n').length;
+      issues.push({ severity: 'warning', message: `Vague rule detected: "${pattern}"`, line: lineNum });
+    }
+  }
+
+  // File length
+  if (lines.length > MAX_LINES_ERROR) {
+    issues.push({ severity: 'error', message: `File is ${lines.length} lines long — may exceed context window`, hint: 'Split into multiple .mdc files' });
+  } else if (lines.length > MAX_LINES_WARNING) {
+    issues.push({ severity: 'warning', message: `File is ${lines.length} lines long — consider splitting`, hint: 'Shorter files are more reliably loaded into context' });
+  }
+
+  return { file: filePath, issues };
+}
+
+async function lintCursorrules(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const issues = [];
+
+  issues.push({
+    severity: 'warning',
+    message: '.cursorrules may be ignored in agent mode',
+    hint: 'Use .cursor/rules/*.mdc with alwaysApply: true for agent mode compatibility',
+  });
+
+  // Vague rules
+  const contentLower = content.toLowerCase();
+  for (const pattern of VAGUE_PATTERNS) {
+    const idx = contentLower.indexOf(pattern);
+    if (idx !== -1) {
+      const lineNum = content.slice(0, idx).split('\n').length;
+      issues.push({ severity: 'warning', message: `Vague rule detected: "${pattern}"`, line: lineNum });
+    }
+  }
+
+  const lines = content.split('\n');
+  if (lines.length > MAX_LINES_ERROR) {
+    issues.push({ severity: 'error', message: `File is ${lines.length} lines long — may exceed context window` });
+  } else if (lines.length > MAX_LINES_WARNING) {
+    issues.push({ severity: 'warning', message: `File is ${lines.length} lines long — consider splitting` });
+  }
+
+  return { file: filePath, issues };
+}
+
+async function lintProject(dir) {
+  const results = [];
+
+  const cursorrules = path.join(dir, '.cursorrules');
+  if (fs.existsSync(cursorrules)) {
+    results.push(await lintCursorrules(cursorrules));
+  }
+
+  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')) {
+        results.push(await lintMdcFile(path.join(rulesDir, entry)));
+      }
+    }
+  }
+
+  if (results.length === 0) {
+    results.push({
+      file: dir,
+      issues: [{ severity: 'warning', message: 'No Cursor rules found in this directory' }],
+    });
+  }
+
+  return results;
+}
+
+module.exports = { lintProject, lintMdcFile, lintCursorrules };