@yawlabs/ctxlint 0.2.1 → 0.3.0

package/dist/index.js

@@ -7,6 +7,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/index.ts
+import * as fs6 from "fs";
 import { Command } from "commander";
 import ora from "ora";
 
@@ -18,6 +19,14 @@ import { glob } from "glob";
 // src/utils/fs.ts
 import * as fs from "fs";
 import * as path from "path";
+function loadPackageJson(projectRoot) {
+  try {
+    const content = fs.readFileSync(path.join(projectRoot, "package.json"), "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
 function fileExists(filePath) {
   try {
     fs.accessSync(filePath);
@@ -85,37 +94,76 @@ function getAllProjectFiles(projectRoot) {
 
 // src/core/scanner.ts
 var CONTEXT_FILE_PATTERNS = [
+  // Claude Code
   "CLAUDE.md",
   "CLAUDE.local.md",
+  ".claude/rules/*.md",
+  // AGENTS.md (AAIF / Linux Foundation standard)
   "AGENTS.md",
+  "AGENT.md",
+  "AGENTS.override.md",
+  // Cursor
   ".cursorrules",
   ".cursor/rules/*.md",
   ".cursor/rules/*.mdc",
-  "copilot-instructions.md",
+  ".cursor/rules/*/RULE.md",
+  // GitHub Copilot
   ".github/copilot-instructions.md",
+  ".github/instructions/*.md",
+  ".github/git-commit-instructions.md",
+  // Windsurf
   ".windsurfrules",
   ".windsurf/rules/*.md",
+  // Gemini CLI
   "GEMINI.md",
-  "JULES.md",
+  // Cline
   ".clinerules",
-  "CONVENTIONS.md"
+  // Aider — note: .aiderules has no file extension; this is the intended format
+  ".aiderules",
+  // Aide / Codestory
+  ".aide/rules/*.md",
+  // Amazon Q Developer
+  ".amazonq/rules/*.md",
+  // Goose (Block)
+  ".goose/instructions.md",
+  ".goosehints",
+  // JetBrains Junie
+  ".junie/guidelines.md",
+  ".junie/AGENTS.md",
+  // JetBrains AI Assistant
+  ".aiassistant/rules/*.md",
+  // Continue
+  ".continuerules",
+  ".continue/rules/*.md",
+  // Zed
+  ".rules",
+  // Replit
+  "replit.md"
 ];
 var IGNORED_DIRS2 = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", "vendor"]);
-async function scanForContextFiles(projectRoot) {
+async function scanForContextFiles(projectRoot, options = {}) {
+  const maxDepth = options.depth ?? 2;
+  const patterns = [...CONTEXT_FILE_PATTERNS, ...options.extraPatterns || []];
   const found = [];
   const seen = /* @__PURE__ */ new Set();
   const dirsToScan = [projectRoot];
-  try {
-    const entries = fs2.readdirSync(projectRoot, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory() && !IGNORED_DIRS2.has(entry.name) && !entry.name.startsWith(".")) {
-        dirsToScan.push(path2.join(projectRoot, entry.name));
+  function collectDirs(dir, currentDepth) {
+    if (currentDepth >= maxDepth) return;
+    try {
+      const entries = fs2.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !IGNORED_DIRS2.has(entry.name) && !entry.name.startsWith(".")) {
+          const fullPath = path2.join(dir, entry.name);
+          dirsToScan.push(fullPath);
+          collectDirs(fullPath, currentDepth + 1);
+        }
       }
+    } catch {
     }
-  } catch {
   }
+  collectDirs(projectRoot, 0);
   for (const dir of dirsToScan) {
-    for (const pattern of CONTEXT_FILE_PATTERNS) {
+    for (const pattern of patterns) {
       const matches = await glob(pattern, {
         cwd: dir,
         absolute: true,
@@ -554,8 +602,9 @@ function findClosestMatch(target, files) {
 // src/core/checks/commands.ts
 import * as fs3 from "fs";
 import * as path4 from "path";
-var NPM_SCRIPT_PATTERN = /^(?:npm\s+run|pnpm(?:\s+run)?|yarn(?:\s+run)?)\s+(\S+)/;
+var NPM_SCRIPT_PATTERN = /^(?:npm\s+run|pnpm(?:\s+run)?|yarn(?:\s+run)?|bun(?:\s+run)?)\s+(\S+)/;
 var MAKE_PATTERN = /^make\s+(\S+)/;
+var NPX_PATTERN = /^npx\s+(\S+)/;
 async function checkCommands(file, projectRoot) {
   const issues = [];
   const pkgJson = loadPackageJson(projectRoot);
@@ -577,7 +626,9 @@ async function checkCommands(file, projectRoot) {
       }
       continue;
     }
-    const shorthandMatch = cmd.match(/^(npm|pnpm|yarn)\s+(test|start|build|dev|lint|format)\b/);
+    const shorthandMatch = cmd.match(
+      /^(npm|pnpm|yarn|bun)\s+(test|start|build|dev|lint|format|check|typecheck|clean|serve|preview|e2e)\b/
+    );
     if (shorthandMatch && pkgJson) {
       const scriptName = shorthandMatch[2];
       if (pkgJson.scripts && !(scriptName in pkgJson.scripts)) {
@@ -590,6 +641,30 @@ async function checkCommands(file, projectRoot) {
       }
       continue;
     }
+    const npxMatch = cmd.match(NPX_PATTERN);
+    if (npxMatch && pkgJson) {
+      const pkgName = npxMatch[1];
+      if (pkgName.startsWith("-")) continue;
+      const allDeps = {
+        ...pkgJson.dependencies,
+        ...pkgJson.devDependencies
+      };
+      if (!(pkgName in allDeps)) {
+        const binPath = path4.join(projectRoot, "node_modules", ".bin", pkgName);
+        try {
+          fs3.accessSync(binPath);
+        } catch {
+          issues.push({
+            severity: "warning",
+            check: "commands",
+            line: ref.line,
+            message: `"${cmd}" \u2014 "${pkgName}" not found in dependencies`,
+            suggestion: "If this is a global tool, consider adding it to devDependencies for reproducibility"
+          });
+        }
+      }
+      continue;
+    }
     const makeMatch = cmd.match(MAKE_PATTERN);
     if (makeMatch) {
       const target = makeMatch[1];
@@ -634,14 +709,6 @@ async function checkCommands(file, projectRoot) {
   }
   return issues;
 }
-function loadPackageJson(projectRoot) {
-  try {
-    const content = fs3.readFileSync(path4.join(projectRoot, "package.json"), "utf-8");
-    return JSON.parse(content);
-  } catch {
-    return null;
-  }
-}
 function loadMakefile(projectRoot) {
   try {
     return fs3.readFileSync(path4.join(projectRoot, "Makefile"), "utf-8");
@@ -764,7 +831,6 @@ function checkAggregateTokens(files) {
 }
 
 // src/core/checks/redundancy.ts
-import * as fs4 from "fs";
 import * as path6 from "path";
 var PACKAGE_TECH_MAP = {
   react: ["React", "react"],
@@ -817,46 +883,56 @@ var PACKAGE_TECH_MAP = {
   cypress: ["Cypress"],
   puppeteer: ["Puppeteer"]
 };
+function compilePatterns(allDeps) {
+  const compiled = [];
+  for (const [pkg, mentions] of Object.entries(PACKAGE_TECH_MAP)) {
+    if (!allDeps.has(pkg)) continue;
+    for (const mention of mentions) {
+      const escaped = escapeRegex(mention);
+      compiled.push({
+        pkg,
+        mention,
+        patterns: [
+          new RegExp(`\\b(?:use|using|built with|powered by|written in)\\s+${escaped}\\b`, "i"),
+          new RegExp(`\\bwe\\s+use\\s+${escaped}\\b`, "i"),
+          new RegExp(`\\b${escaped}\\s+(?:project|app|application|codebase)\\b`, "i"),
+          new RegExp(`\\bThis is a\\s+${escaped}\\b`, "i")
+        ]
+      });
+    }
+  }
+  return compiled;
+}
 async function checkRedundancy(file, projectRoot) {
   const issues = [];
-  const pkgJson = loadPackageJson2(projectRoot);
+  const pkgJson = loadPackageJson(projectRoot);
   if (pkgJson) {
     const allDeps = /* @__PURE__ */ new Set([
       ...Object.keys(pkgJson.dependencies || {}),
       ...Object.keys(pkgJson.devDependencies || {})
     ]);
+    const compiledPatterns = compilePatterns(allDeps);
     const lines2 = file.content.split("\n");
     for (let i = 0; i < lines2.length; i++) {
       const line = lines2[i];
-      for (const [pkg, mentions] of Object.entries(PACKAGE_TECH_MAP)) {
-        if (!allDeps.has(pkg)) continue;
-        for (const mention of mentions) {
-          const patterns = [
-            new RegExp(
-              `\\b(?:use|using|built with|powered by|written in)\\s+${escapeRegex(mention)}\\b`,
-              "i"
-            ),
-            new RegExp(`\\bwe\\s+use\\s+${escapeRegex(mention)}\\b`, "i"),
-            new RegExp(
-              `\\b${escapeRegex(mention)}\\s+(?:project|app|application|codebase)\\b`,
-              "i"
-            ),
-            new RegExp(`\\bThis is a\\s+${escapeRegex(mention)}\\b`, "i")
-          ];
-          for (const pattern of patterns) {
-            if (pattern.test(line)) {
-              const wastedTokens = countTokens(line.trim());
-              issues.push({
-                severity: "info",
-                check: "redundancy",
-                line: i + 1,
-                message: `"${mention}" is in package.json ${pkgJson.dependencies?.[pkg] ? "dependencies" : "devDependencies"} \u2014 agent can infer this`,
-                suggestion: `~${wastedTokens} tokens could be saved`
-              });
-              break;
-            }
+      for (const { pkg, mention, patterns } of compiledPatterns) {
+        let matched = false;
+        for (const pattern of patterns) {
+          if (pattern.test(line)) {
+            matched = true;
+            break;
           }
         }
+        if (matched) {
+          const wastedTokens = countTokens(line.trim());
+          issues.push({
+            severity: "info",
+            check: "redundancy",
+            line: i + 1,
+            message: `"${mention}" is in package.json ${pkgJson.dependencies?.[pkg] ? "dependencies" : "devDependencies"} \u2014 agent can infer this`,
+            suggestion: `~${wastedTokens} tokens could be saved`
+          });
+        }
       }
     }
   }
@@ -914,18 +990,431 @@ function calculateLineOverlap(contentA, contentB) {
   }
   return overlap / Math.min(linesA.size, linesB.size);
 }
-function loadPackageJson2(projectRoot) {
-  try {
-    const content = fs4.readFileSync(path6.join(projectRoot, "package.json"), "utf-8");
-    return JSON.parse(content);
-  } catch {
-    return null;
-  }
-}
 function escapeRegex(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// src/core/checks/contradictions.ts
+var DIRECTIVE_CATEGORIES = [
+  {
+    name: "testing framework",
+    options: [
+      {
+        label: "Jest",
+        patterns: [/\buse\s+jest\b/i, /\bjest\s+for\s+test/i, /\btest.*with\s+jest\b/i]
+      },
+      {
+        label: "Vitest",
+        patterns: [/\buse\s+vitest\b/i, /\bvitest\s+for\s+test/i, /\btest.*with\s+vitest\b/i]
+      },
+      {
+        label: "Mocha",
+        patterns: [/\buse\s+mocha\b/i, /\bmocha\s+for\s+test/i, /\btest.*with\s+mocha\b/i]
+      },
+      {
+        label: "pytest",
+        patterns: [/\buse\s+pytest\b/i, /\bpytest\s+for\s+test/i, /\btest.*with\s+pytest\b/i]
+      },
+      {
+        label: "Playwright",
+        patterns: [/\buse\s+playwright\b/i, /\bplaywright\s+for\s+(?:e2e|test)/i]
+      },
+      { label: "Cypress", patterns: [/\buse\s+cypress\b/i, /\bcypress\s+for\s+(?:e2e|test)/i] }
+    ]
+  },
+  {
+    name: "package manager",
+    options: [
+      {
+        label: "npm",
+        patterns: [
+          /\buse\s+npm\b/i,
+          /\bnpm\s+as\s+(?:the\s+)?package\s+manager/i,
+          /\balways\s+use\s+npm\b/i
+        ]
+      },
+      {
+        label: "pnpm",
+        patterns: [
+          /\buse\s+pnpm\b/i,
+          /\bpnpm\s+as\s+(?:the\s+)?package\s+manager/i,
+          /\balways\s+use\s+pnpm\b/i
+        ]
+      },
+      {
+        label: "yarn",
+        patterns: [
+          /\buse\s+yarn\b/i,
+          /\byarn\s+as\s+(?:the\s+)?package\s+manager/i,
+          /\balways\s+use\s+yarn\b/i
+        ]
+      },
+      {
+        label: "bun",
+        patterns: [
+          /\buse\s+bun\b/i,
+          /\bbun\s+as\s+(?:the\s+)?package\s+manager/i,
+          /\balways\s+use\s+bun\b/i
+        ]
+      }
+    ]
+  },
+  {
+    name: "indentation style",
+    options: [
+      {
+        label: "tabs",
+        patterns: [/\buse\s+tabs\b/i, /\btab\s+indentation\b/i, /\bindent\s+with\s+tabs\b/i]
+      },
+      {
+        label: "2 spaces",
+        patterns: [
+          /\b2[\s-]?space\s+indent/i,
+          /\bindent\s+with\s+2\s+spaces/i,
+          /\b2[\s-]?space\s+tabs?\b/i
+        ]
+      },
+      {
+        label: "4 spaces",
+        patterns: [
+          /\b4[\s-]?space\s+indent/i,
+          /\bindent\s+with\s+4\s+spaces/i,
+          /\b4[\s-]?space\s+tabs?\b/i
+        ]
+      }
+    ]
+  },
+  {
+    name: "semicolons",
+    options: [
+      {
+        label: "semicolons",
+        patterns: [
+          /\buse\s+semicolons\b/i,
+          /\balways\s+(?:use\s+)?semicolons\b/i,
+          /\bsemicolons:\s*(?:true|yes)\b/i
+        ]
+      },
+      {
+        label: "no semicolons",
+        patterns: [
+          /\bno\s+semicolons\b/i,
+          /\bavoid\s+semicolons\b/i,
+          /\bomit\s+semicolons\b/i,
+          /\bsemicolons:\s*(?:false|no)\b/i
+        ]
+      }
+    ]
+  },
+  {
+    name: "quote style",
+    options: [
+      {
+        label: "single quotes",
+        patterns: [
+          /\bsingle\s+quotes?\b/i,
+          /\buse\s+(?:single\s+)?['']single['']?\s+quotes?\b/i,
+          /\bprefer\s+single\s+quotes?\b/i
+        ]
+      },
+      {
+        label: "double quotes",
+        patterns: [
+          /\bdouble\s+quotes?\b/i,
+          /\buse\s+(?:double\s+)?[""]double[""]?\s+quotes?\b/i,
+          /\bprefer\s+double\s+quotes?\b/i
+        ]
+      }
+    ]
+  },
+  {
+    name: "naming convention",
+    options: [
+      {
+        label: "camelCase",
+        patterns: [/\bcamelCase\b/, /\bcamel[\s-]?case\s+(?:for|naming|convention)/i]
+      },
+      {
+        label: "snake_case",
+        patterns: [/\bsnake_case\b/, /\bsnake[\s-]?case\s+(?:for|naming|convention)/i]
+      },
+      {
+        label: "PascalCase",
+        patterns: [/\bPascalCase\b/, /\bpascal[\s-]?case\s+(?:for|naming|convention)/i]
+      },
+      {
+        label: "kebab-case",
+        patterns: [/\bkebab-case\b/, /\bkebab[\s-]?case\s+(?:for|naming|convention)/i]
+      }
+    ]
+  },
+  {
+    name: "CSS approach",
+    options: [
+      { label: "Tailwind", patterns: [/\buse\s+tailwind/i, /\btailwind\s+for\s+styl/i] },
+      {
+        label: "CSS Modules",
+        patterns: [/\buse\s+css\s+modules\b/i, /\bcss\s+modules\s+for\s+styl/i]
+      },
+      {
+        label: "styled-components",
+        patterns: [/\buse\s+styled[\s-]?components\b/i, /\bstyled[\s-]?components\s+for\s+styl/i]
+      },
+      { label: "CSS-in-JS", patterns: [/\buse\s+css[\s-]?in[\s-]?js\b/i] }
+    ]
+  },
+  {
+    name: "state management",
+    options: [
+      { label: "Redux", patterns: [/\buse\s+redux\b/i, /\bredux\s+for\s+state/i] },
+      { label: "Zustand", patterns: [/\buse\s+zustand\b/i, /\bzustand\s+for\s+state/i] },
+      { label: "MobX", patterns: [/\buse\s+mobx\b/i, /\bmobx\s+for\s+state/i] },
+      { label: "Jotai", patterns: [/\buse\s+jotai\b/i, /\bjotai\s+for\s+state/i] },
+      { label: "Recoil", patterns: [/\buse\s+recoil\b/i, /\brecoil\s+for\s+state/i] }
+    ]
+  }
+];
+function detectDirectives(file) {
+  const directives = [];
+  const lines = file.content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const category of DIRECTIVE_CATEGORIES) {
+      for (const option of category.options) {
+        for (const pattern of option.patterns) {
+          if (pattern.test(line)) {
+            directives.push({
+              file: file.relativePath,
+              category: category.name,
+              label: option.label,
+              line: i + 1,
+              text: line.trim()
+            });
+            break;
+          }
+        }
+      }
+    }
+  }
+  return directives;
+}
+function checkContradictions(files) {
+  if (files.length < 2) return [];
+  const issues = [];
+  const allDirectives = [];
+  for (const file of files) {
+    allDirectives.push(...detectDirectives(file));
+  }
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const d of allDirectives) {
+    const existing = byCategory.get(d.category) || [];
+    existing.push(d);
+    byCategory.set(d.category, existing);
+  }
+  for (const [category, directives] of byCategory) {
+    const byFile = /* @__PURE__ */ new Map();
+    for (const d of directives) {
+      const existing = byFile.get(d.file) || [];
+      existing.push(d);
+      byFile.set(d.file, existing);
+    }
+    const labels = new Set(directives.map((d) => d.label));
+    if (labels.size <= 1) continue;
+    const fileLabels = /* @__PURE__ */ new Map();
+    for (const d of directives) {
+      const existing = fileLabels.get(d.file) || /* @__PURE__ */ new Set();
+      existing.add(d.label);
+      fileLabels.set(d.file, existing);
+    }
+    const fileEntries = [...fileLabels.entries()];
+    for (let i = 0; i < fileEntries.length; i++) {
+      for (let j = i + 1; j < fileEntries.length; j++) {
+        const [fileA, labelsA] = fileEntries[i];
+        const [fileB, labelsB] = fileEntries[j];
+        for (const labelA of labelsA) {
+          for (const labelB of labelsB) {
+            if (labelA !== labelB) {
+              const directiveA = directives.find((d) => d.file === fileA && d.label === labelA);
+              const directiveB = directives.find((d) => d.file === fileB && d.label === labelB);
+              issues.push({
+                severity: "warning",
+                check: "contradictions",
+                line: directiveA.line,
+                message: `${category} conflict: "${directiveA.label}" in ${fileA} vs "${directiveB.label}" in ${fileB}`,
+                suggestion: `Align on one ${category} across all context files`,
+                detail: `${fileA}:${directiveA.line} says "${directiveA.text}" but ${fileB}:${directiveB.line} says "${directiveB.text}"`
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+// src/core/checks/frontmatter.ts
+function parseFrontmatter(content) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return { found: false, fields: {}, endLine: 0 };
+  }
+  const fields = {};
+  let endLine = 0;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "---") {
+      endLine = i + 1;
+      break;
+    }
+    const match = line.match(/^(\w+)\s*:\s*(.*)$/);
+    if (match) {
+      fields[match[1]] = match[2].trim();
+    }
+  }
+  if (endLine === 0) {
+    return { found: true, fields, endLine: lines.length };
+  }
+  return { found: true, fields, endLine };
+}
+function isCursorMdc(file) {
+  return file.relativePath.endsWith(".mdc");
+}
+function isCopilotInstructions(file) {
+  return file.relativePath.includes(".github/instructions/") && file.relativePath.endsWith(".md");
+}
+function isWindsurfRule(file) {
+  return file.relativePath.includes(".windsurf/rules/") && file.relativePath.endsWith(".md");
+}
+var VALID_WINDSURF_TRIGGERS = ["always_on", "glob", "manual", "model"];
+async function checkFrontmatter(file, _projectRoot) {
+  const issues = [];
+  if (isCursorMdc(file)) {
+    issues.push(...validateCursorMdc(file));
+  } else if (isCopilotInstructions(file)) {
+    issues.push(...validateCopilotInstructions(file));
+  } else if (isWindsurfRule(file)) {
+    issues.push(...validateWindsurfRule(file));
+  }
+  return issues;
+}
+function validateCursorMdc(file) {
+  const issues = [];
+  const fm = parseFrontmatter(file.content);
+  if (!fm.found) {
+    issues.push({
+      severity: "warning",
+      check: "frontmatter",
+      line: 1,
+      message: "Cursor .mdc file is missing frontmatter",
+      suggestion: "Add YAML frontmatter with description, globs, and alwaysApply fields"
+    });
+    return issues;
+  }
+  if (!fm.fields["description"]) {
+    issues.push({
+      severity: "warning",
+      check: "frontmatter",
+      line: 1,
+      message: 'Missing "description" field in Cursor .mdc frontmatter',
+      suggestion: "Add a description so Cursor knows when to apply this rule"
+    });
+  }
+  if (!("alwaysApply" in fm.fields) && !("globs" in fm.fields)) {
+    issues.push({
+      severity: "info",
+      check: "frontmatter",
+      line: 1,
+      message: 'No "alwaysApply" or "globs" field \u2014 rule may not be applied automatically',
+      suggestion: "Set alwaysApply: true or specify globs for targeted activation"
+    });
+  }
+  if ("alwaysApply" in fm.fields) {
+    const val = fm.fields["alwaysApply"].toLowerCase();
+    if (!["true", "false"].includes(val)) {
+      issues.push({
+        severity: "error",
+        check: "frontmatter",
+        line: 1,
+        message: `Invalid alwaysApply value: "${fm.fields["alwaysApply"]}"`,
+        suggestion: "alwaysApply must be true or false"
+      });
+    }
+  }
+  if ("globs" in fm.fields) {
+    const val = fm.fields["globs"];
+    if (val && !val.startsWith("[") && !val.startsWith('"') && !val.includes("*") && !val.includes("/")) {
+      issues.push({
+        severity: "warning",
+        check: "frontmatter",
+        line: 1,
+        message: `Possibly invalid globs value: "${val}"`,
+        suggestion: 'globs should be a glob pattern like "src/**/*.ts" or an array like ["*.ts", "*.tsx"]'
+      });
+    }
+  }
+  return issues;
+}
+function validateCopilotInstructions(file) {
+  const issues = [];
+  const fm = parseFrontmatter(file.content);
+  if (!fm.found) {
+    issues.push({
+      severity: "info",
+      check: "frontmatter",
+      line: 1,
+      message: "Copilot instructions file has no frontmatter",
+      suggestion: "Add applyTo frontmatter to target specific file patterns"
+    });
+    return issues;
+  }
+  if (!fm.fields["applyTo"]) {
+    issues.push({
+      severity: "warning",
+      check: "frontmatter",
+      line: 1,
+      message: 'Missing "applyTo" field in Copilot instructions frontmatter',
+      suggestion: 'Add applyTo to specify which files this instruction applies to (e.g., applyTo: "**/*.ts")'
+    });
+  }
+  return issues;
+}
+function validateWindsurfRule(file) {
+  const issues = [];
+  const fm = parseFrontmatter(file.content);
+  if (!fm.found) {
+    issues.push({
+      severity: "info",
+      check: "frontmatter",
+      line: 1,
+      message: "Windsurf rule file has no frontmatter",
+      suggestion: "Add YAML frontmatter with a trigger field (always_on, glob, manual, model)"
+    });
+    return issues;
+  }
+  if (!fm.fields["trigger"]) {
+    issues.push({
+      severity: "warning",
+      check: "frontmatter",
+      line: 1,
+      message: 'Missing "trigger" field in Windsurf rule frontmatter',
+      suggestion: `Set trigger to one of: ${VALID_WINDSURF_TRIGGERS.join(", ")}`
+    });
+  } else {
+    const trigger = fm.fields["trigger"].replace(/['"]/g, "");
+    if (!VALID_WINDSURF_TRIGGERS.includes(trigger)) {
+      issues.push({
+        severity: "error",
+        check: "frontmatter",
+        line: 1,
+        message: `Invalid trigger value: "${trigger}"`,
+        suggestion: `Valid triggers: ${VALID_WINDSURF_TRIGGERS.join(", ")}`
+      });
+    }
+  }
+  return issues;
+}
+
 // src/core/reporter.ts
 import chalk from "chalk";
 function formatText(result, verbose = false) {
@@ -984,6 +1473,9 @@ function formatTokenReport(result) {
   const lines = [];
   lines.push("");
   lines.push(chalk.bold("Token Usage Report"));
+  lines.push(
+    chalk.dim("  (counts use GPT-4 cl100k_base tokenizer \u2014 Claude counts may vary slightly)")
+  );
   lines.push("");
   const maxPathLen = Math.max(...result.files.map((f) => f.path.length), 4);
   lines.push(
@@ -1010,6 +1502,100 @@ function formatTokenReport(result) {
   lines.push("");
   return lines.join("\n");
 }
+function formatSarif(result) {
+  const severityToLevel = {
+    error: "error",
+    warning: "warning",
+    info: "note"
+  };
+  const results = [];
+  for (const file of result.files) {
+    for (const issue of file.issues) {
+      const sarifResult = {
+        ruleId: `ctxlint/${issue.check}`,
+        level: severityToLevel[issue.severity] || "note",
+        message: {
+          text: issue.message + (issue.suggestion ? ` (${issue.suggestion})` : "")
+        },
+        locations: [
+          {
+            physicalLocation: {
+              artifactLocation: {
+                uri: file.path,
+                uriBaseId: "%SRCROOT%"
+              },
+              region: {
+                startLine: Math.max(issue.line, 1)
+              }
+            }
+          }
+        ]
+      };
+      if (issue.detail) {
+        sarifResult.message.text += `
+${issue.detail}`;
+      }
+      results.push(sarifResult);
+    }
+  }
+  const sarif = {
+    version: "2.1.0",
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "ctxlint",
+            version: result.version,
+            informationUri: "https://github.com/yawlabs/ctxlint",
+            rules: buildRuleDescriptors()
+          }
+        },
+        results
+      }
+    ]
+  };
+  return JSON.stringify(sarif, null, 2);
+}
+function buildRuleDescriptors() {
+  return [
+    {
+      id: "ctxlint/paths",
+      shortDescription: { text: "File path does not exist in project" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
+    {
+      id: "ctxlint/commands",
+      shortDescription: { text: "Command does not match project scripts" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
+    {
+      id: "ctxlint/staleness",
+      shortDescription: { text: "Context file is stale relative to referenced code" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
+    {
+      id: "ctxlint/tokens",
+      shortDescription: { text: "Context file token usage" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
+    {
+      id: "ctxlint/redundancy",
+      shortDescription: { text: "Content is redundant or inferable" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
+    {
+      id: "ctxlint/contradictions",
+      shortDescription: { text: "Conflicting directives across context files" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    },
+    {
+      id: "ctxlint/frontmatter",
+      shortDescription: { text: "Invalid or missing frontmatter" },
+      helpUri: "https://github.com/yawlabs/ctxlint#what-it-checks"
+    }
+  ];
+}
 function formatIssue(issue) {
   const icon = issue.severity === "error" ? chalk.red("\u2717") : issue.severity === "warning" ? chalk.yellow("\u26A0") : chalk.blue("\u2139");
   const lineRef = issue.line > 0 ? `Line ${issue.line}: ` : "";
@@ -1026,7 +1612,7 @@ function formatIssue(issue) {
 }
 
 // src/core/fixer.ts
-import * as fs5 from "fs";
+import * as fs4 from "fs";
 import chalk2 from "chalk";
 function applyFixes(result) {
   const fixesByFile = /* @__PURE__ */ new Map();
@@ -1042,7 +1628,7 @@ function applyFixes(result) {
   let totalFixes = 0;
   const filesModified = [];
   for (const [filePath, fixes] of fixesByFile) {
-    const content = fs5.readFileSync(filePath, "utf-8");
+    const content = fs4.readFileSync(filePath, "utf-8");
     const lines = content.split("\n");
     let modified = false;
     const sortedFixes = [...fixes].sort((a, b) => b.line - a.line);
@@ -1060,7 +1646,7 @@ function applyFixes(result) {
       }
     }
     if (modified) {
-      fs5.writeFileSync(filePath, lines.join("\n"), "utf-8");
+      fs4.writeFileSync(filePath, lines.join("\n"), "utf-8");
       filesModified.push(filePath);
     }
   }
@@ -1068,14 +1654,14 @@ function applyFixes(result) {
 }
 
 // src/core/config.ts
-import * as fs6 from "fs";
+import * as fs5 from "fs";
 import * as path7 from "path";
 var CONFIG_FILENAMES = [".ctxlintrc", ".ctxlintrc.json"];
 function loadConfig(projectRoot) {
   for (const filename of CONFIG_FILENAMES) {
     const filePath = path7.join(projectRoot, filename);
     try {
-      const content = fs6.readFileSync(filePath, "utf-8");
+      const content = fs5.readFileSync(filePath, "utf-8");
       return JSON.parse(content);
     } catch {
       continue;
@@ -1089,7 +1675,7 @@ import * as path8 from "path";
 
 // src/version.ts
 function loadVersion() {
-  if (true) return "0.2.1";
+  if (true) return "0.3.0";
   const fs7 = __require("fs");
   const path9 = __require("path");
   const pkgPath = path9.resolve(__dirname, "../package.json");
@@ -1099,13 +1685,22 @@ function loadVersion() {
 var VERSION = loadVersion();
 
 // src/index.ts
-var ALL_CHECKS = ["paths", "commands", "staleness", "tokens", "redundancy"];
+var ALL_CHECKS = [
+  "paths",
+  "commands",
+  "staleness",
+  "tokens",
+  "redundancy",
+  "contradictions",
+  "frontmatter"
+];
 var program = new Command();
 program.name("ctxlint").description(
   "Lint your AI agent context files (CLAUDE.md, AGENTS.md, etc.) against your actual codebase"
-).version(VERSION).argument("[path]", "Project directory to scan", ".").option("--strict", "Exit code 1 on any warning or error (for CI)", false).option("--checks <checks>", "Comma-separated list of checks to run", "").option("--format <format>", "Output format: text or json", "text").option("--tokens", "Show token breakdown per file", false).option("--verbose", "Show passing checks too", false).option("--fix", "Auto-fix broken paths using git history and fuzzy matching", false).option("--ignore <checks>", "Comma-separated list of checks to ignore", "").action(async (projectPath, opts) => {
+).version(VERSION).argument("[path]", "Project directory to scan", ".").option("--strict", "Exit code 1 on any warning or error (for CI)", false).option("--checks <checks>", "Comma-separated list of checks to run", "").option("--format <format>", "Output format: text, json, or sarif", "text").option("--tokens", "Show token breakdown per file", false).option("--verbose", "Show passing checks too", false).option("--fix", "Auto-fix broken paths using git history and fuzzy matching", false).option("--ignore <checks>", "Comma-separated list of checks to ignore", "").option("--quiet", "Suppress all output except errors (exit code only)", false).option("--config <path>", "Path to config file (default: .ctxlintrc in project root)").option("--depth <n>", "Max subdirectory depth to scan (default: 2)", "2").action(async (projectPath, opts) => {
   const resolvedPath = path8.resolve(projectPath);
-  const config = loadConfig(resolvedPath);
+  const configPath = opts.config ? path8.resolve(opts.config) : void 0;
+  const config = configPath ? loadConfigFromPath(configPath) : loadConfig(resolvedPath);
   const options = {
     projectPath: resolvedPath,
     checks: opts.checks ? opts.checks.split(",").map((c) => c.trim()) : config?.checks || ALL_CHECKS,
@@ -1114,29 +1709,46 @@ program.name("ctxlint").description(
     verbose: opts.verbose,
     fix: opts.fix,
     ignore: opts.ignore ? opts.ignore.split(",").map((c) => c.trim()) : config?.ignore || [],
-    tokensOnly: opts.tokens
+    tokensOnly: opts.tokens,
+    quiet: opts.quiet,
+    depth: parseInt(opts.depth, 10) || 2
   };
   if (config?.tokenThresholds) {
     setTokenThresholds(config.tokenThresholds);
   }
   const activeChecks = options.checks.filter((c) => !options.ignore.includes(c));
-  const spinner = options.format === "text" ? ora("Scanning for context files...").start() : void 0;
+  const spinner = options.format === "text" && !options.quiet ? ora("Scanning for context files...").start() : void 0;
   try {
-    const discovered = await scanForContextFiles(options.projectPath);
+    const discovered = await scanForContextFiles(options.projectPath, {
+      depth: options.depth,
+      extraPatterns: config?.contextFiles
+    });
     if (discovered.length === 0) {
       spinner?.stop();
-      if (options.format === "json") {
-        console.log(
-          JSON.stringify({
-            version: VERSION,
-            scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
-            projectRoot: options.projectPath,
-            files: [],
-            summary: { errors: 0, warnings: 0, info: 0, totalTokens: 0, estimatedWaste: 0 }
-          })
-        );
-      } else {
-        console.log("\nNo context files found.\n");
+      if (!options.quiet) {
+        if (options.format === "json") {
+          console.log(
+            JSON.stringify({
+              version: VERSION,
+              scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              projectRoot: options.projectPath,
+              files: [],
+              summary: { errors: 0, warnings: 0, info: 0, totalTokens: 0, estimatedWaste: 0 }
+            })
+          );
+        } else if (options.format === "sarif") {
+          console.log(
+            formatSarif({
+              version: VERSION,
+              scannedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              projectRoot: options.projectPath,
+              files: [],
+              summary: { errors: 0, warnings: 0, info: 0, totalTokens: 0, estimatedWaste: 0 }
+            })
+          );
+        } else {
+          console.log("\nNo context files found.\n");
+        }
       }
       process.exit(0);
     }
@@ -1162,6 +1774,9 @@ program.name("ctxlint").description(
       if (activeChecks.includes("redundancy")) {
         issues.push(...await checkRedundancy(file, options.projectPath));
       }
+      if (activeChecks.includes("frontmatter")) {
+        issues.push(...await checkFrontmatter(file, options.projectPath));
+      }
       fileResults.push({
         path: file.relativePath,
         isSymlink: file.isSymlink,
@@ -1185,6 +1800,12 @@ program.name("ctxlint").description(
         fileResults[0].issues.push(...dupIssues);
       }
     }
+    if (activeChecks.includes("contradictions")) {
+      const contradictionIssues = checkContradictions(parsed);
+      if (contradictionIssues.length > 0 && fileResults.length > 0) {
+        fileResults[0].issues.push(...contradictionIssues);
+      }
+    }
     let estimatedWaste = 0;
     for (const fr of fileResults) {
       for (const issue of fr.issues) {
@@ -1221,7 +1842,7 @@ program.name("ctxlint").description(
     spinner?.stop();
     if (options.fix) {
       const fixSummary = applyFixes(result);
-      if (fixSummary.totalFixes > 0) {
+      if (fixSummary.totalFixes > 0 && !options.quiet) {
         console.log(
           `
 Fixed ${fixSummary.totalFixes} issue${fixSummary.totalFixes !== 1 ? "s" : ""} in ${fixSummary.filesModified.length} file${fixSummary.filesModified.length !== 1 ? "s" : ""}.
@@ -1229,12 +1850,16 @@ Fixed ${fixSummary.totalFixes} issue${fixSummary.totalFixes !== 1 ? "s" : ""} in
         );
       }
     }
-    if (options.tokensOnly) {
-      console.log(formatTokenReport(result));
-    } else if (options.format === "json") {
-      console.log(formatJson(result));
-    } else {
-      console.log(formatText(result, options.verbose));
+    if (!options.quiet) {
+      if (options.tokensOnly) {
+        console.log(formatTokenReport(result));
+      } else if (options.format === "json") {
+        console.log(formatJson(result));
+      } else if (options.format === "sarif") {
+        console.log(formatSarif(result));
+      } else {
+        console.log(formatText(result, options.verbose));
+      }
     }
     if (options.strict && (result.summary.errors > 0 || result.summary.warnings > 0)) {
       process.exit(1);
@@ -1251,32 +1876,40 @@ Fixed ${fixSummary.totalFixes} issue${fixSummary.totalFixes !== 1 ? "s" : ""} in
   }
 });
 program.command("init").description("Set up a git pre-commit hook that runs ctxlint --strict").action(async () => {
-  const fs7 = await import("fs");
   const hooksDir = path8.resolve(".git", "hooks");
-  if (!fs7.existsSync(path8.resolve(".git"))) {
+  if (!fs6.existsSync(path8.resolve(".git"))) {
     console.error('Error: not a git repository. Run "git init" first.');
     process.exit(1);
   }
-  if (!fs7.existsSync(hooksDir)) {
-    fs7.mkdirSync(hooksDir, { recursive: true });
+  if (!fs6.existsSync(hooksDir)) {
+    fs6.mkdirSync(hooksDir, { recursive: true });
   }
   const hookPath = path8.join(hooksDir, "pre-commit");
   const hookContent = `#!/bin/sh
 # ctxlint pre-commit hook
 npx @yawlabs/ctxlint --strict
 `;
-  if (fs7.existsSync(hookPath)) {
-    const existing = fs7.readFileSync(hookPath, "utf-8");
+  if (fs6.existsSync(hookPath)) {
+    const existing = fs6.readFileSync(hookPath, "utf-8");
     if (existing.includes("ctxlint")) {
       console.log("Pre-commit hook already includes ctxlint.");
       return;
     }
-    fs7.appendFileSync(hookPath, "\n" + hookContent);
+    fs6.appendFileSync(hookPath, "\n" + hookContent);
     console.log("Added ctxlint to existing pre-commit hook.");
   } else {
-    fs7.writeFileSync(hookPath, hookContent, { mode: 493 });
+    fs6.writeFileSync(hookPath, hookContent, { mode: 493 });
     console.log("Created pre-commit hook at .git/hooks/pre-commit");
   }
   console.log("ctxlint will now run automatically before each commit.");
 });
 program.parse();
+function loadConfigFromPath(configPath) {
+  try {
+    const content = fs6.readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    console.error(`Error: could not load config from ${configPath}`);
+    process.exit(2);
+  }
+}