@yawlabs/ctxlint 0.1.1 → 0.2.0

package/README.md

@@ -75,11 +75,15 @@ Options:
   --strict             Exit code 1 on any warning or error (for CI)
   --checks <list>      Comma-separated: paths, commands, staleness, tokens, redundancy
   --ignore <list>      Comma-separated checks to skip
+  --fix                Auto-fix broken paths using git history and fuzzy matching
   --format json        Output as JSON (for programmatic use)
   --tokens             Show token breakdown per file
   --verbose            Show passing checks too
   -V, --version        Output the version number
   -h, --help           Display help
+
+Commands:
+  init                 Set up a git pre-commit hook
 ```
 
 ## Use in CI
@@ -91,6 +95,42 @@ Options:
 
 Exits with code 1 if any errors or warnings are found.
 
+## Auto-fix
+
+```bash
+npx @yawlabs/ctxlint --fix
+```
+
+When a broken path was renamed in git or has a close match in the project, `--fix` rewrites the context file automatically.
+
+## Pre-commit Hook
+
+```bash
+npx @yawlabs/ctxlint init
+```
+
+Sets up a git pre-commit hook that runs `ctxlint --strict` before each commit.
+
+## Config File
+
+Create a `.ctxlintrc` or `.ctxlintrc.json` in your project root:
+
+```json
+{
+  "checks": ["paths", "commands", "tokens"],
+  "ignore": ["redundancy"],
+  "strict": true,
+  "tokenThresholds": {
+    "info": 500,
+    "warning": 2000,
+    "error": 5000,
+    "aggregate": 4000
+  }
+}
+```
+
+CLI flags override config file settings.
+
 ## Use as MCP Server
 
 ctxlint ships with an MCP server that exposes three tools (`ctxlint_audit`, `ctxlint_validate_path`, `ctxlint_token_report`):

package/dist/index.js

@@ -498,13 +498,16 @@ async function checkPaths(file, projectRoot) {
     }
     let suggestion;
     let detail;
+    let fixTarget;
     const rename = await findRenames(projectRoot, ref.value);
     if (rename) {
+      fixTarget = rename.newPath;
       suggestion = `Did you mean ${rename.newPath}?`;
       detail = `Renamed ${rename.daysAgo} days ago in commit ${rename.commitHash}`;
     } else {
       const match = findClosestMatch(normalizedRef, projectFiles);
       if (match) {
+        fixTarget = match;
         suggestion = `Did you mean ${match}?`;
       }
     }
@@ -514,7 +517,8 @@ async function checkPaths(file, projectRoot) {
       line: ref.line,
       message: `${ref.value} does not exist`,
       suggestion,
-      detail
+      detail,
+      fix: fixTarget ? { file: file.filePath, line: ref.line, oldText: ref.value, newText: fixTarget } : void 0
     });
   }
   return issues;
@@ -703,13 +707,23 @@ async function checkStaleness(file, projectRoot) {
 }
 
 // src/core/checks/tokens.ts
-var INFO_THRESHOLD = 1e3;
-var WARNING_THRESHOLD = 3e3;
-var ERROR_THRESHOLD = 8e3;
+var DEFAULT_THRESHOLDS = {
+  info: 1e3,
+  warning: 3e3,
+  error: 8e3,
+  aggregate: 5e3
+};
+var currentThresholds = DEFAULT_THRESHOLDS;
+function setTokenThresholds(overrides) {
+  currentThresholds = { ...DEFAULT_THRESHOLDS, ...overrides };
+}
+function resetTokenThresholds() {
+  currentThresholds = DEFAULT_THRESHOLDS;
+}
 async function checkTokens(file, _projectRoot) {
   const issues = [];
   const tokens = file.totalTokens;
-  if (tokens >= ERROR_THRESHOLD) {
+  if (tokens >= currentThresholds.error) {
     issues.push({
       severity: "error",
       check: "tokens",
@@ -717,7 +731,7 @@ async function checkTokens(file, _projectRoot) {
       message: `${tokens.toLocaleString()} tokens \u2014 consumes significant context window space`,
       suggestion: "Consider splitting into focused sections or removing redundant content."
     });
-  } else if (tokens >= WARNING_THRESHOLD) {
+  } else if (tokens >= currentThresholds.warning) {
     issues.push({
       severity: "warning",
       check: "tokens",
@@ -725,7 +739,7 @@ async function checkTokens(file, _projectRoot) {
       message: `${tokens.toLocaleString()} tokens \u2014 large context file`,
       suggestion: "Consider trimming \u2014 research shows diminishing returns past ~300 lines."
     });
-  } else if (tokens >= INFO_THRESHOLD) {
+  } else if (tokens >= currentThresholds.info) {
     issues.push({
       severity: "info",
       check: "tokens",
@@ -737,7 +751,7 @@ async function checkTokens(file, _projectRoot) {
 }
 function checkAggregateTokens(files) {
   const total = files.reduce((sum, f) => sum + f.tokens, 0);
-  if (total > 5e3 && files.length > 1) {
+  if (total > currentThresholds.aggregate && files.length > 1) {
     return {
       severity: "warning",
       check: "tokens",
@@ -1011,16 +1025,75 @@ function formatIssue(issue) {
   return line;
 }
 
-// src/index.ts
+// src/core/fixer.ts
+import * as fs5 from "fs";
+import chalk2 from "chalk";
+function applyFixes(result) {
+  const fixesByFile = /* @__PURE__ */ new Map();
+  for (const file of result.files) {
+    for (const issue of file.issues) {
+      if (issue.fix) {
+        const existing = fixesByFile.get(issue.fix.file) || [];
+        existing.push(issue.fix);
+        fixesByFile.set(issue.fix.file, existing);
+      }
+    }
+  }
+  let totalFixes = 0;
+  const filesModified = [];
+  for (const [filePath, fixes] of fixesByFile) {
+    const content = fs5.readFileSync(filePath, "utf-8");
+    const lines = content.split("\n");
+    let modified = false;
+    const sortedFixes = [...fixes].sort((a, b) => b.line - a.line);
+    for (const fix of sortedFixes) {
+      const lineIdx = fix.line - 1;
+      if (lineIdx < 0 || lineIdx >= lines.length) continue;
+      const line = lines[lineIdx];
+      if (line.includes(fix.oldText)) {
+        lines[lineIdx] = line.replace(fix.oldText, fix.newText);
+        modified = true;
+        totalFixes++;
+        console.log(
+          chalk2.green("  Fixed") + ` Line ${fix.line}: ${chalk2.dim(fix.oldText)} ${chalk2.dim("\u2192")} ${fix.newText}`
+        );
+      }
+    }
+    if (modified) {
+      fs5.writeFileSync(filePath, lines.join("\n"), "utf-8");
+      filesModified.push(filePath);
+    }
+  }
+  return { totalFixes, filesModified };
+}
+
+// src/core/config.ts
+import * as fs6 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");
+      return JSON.parse(content);
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// src/index.ts
+import * as path8 from "path";
 
 // src/version.ts
 function loadVersion() {
-  if (true) return "0.1.1";
-  const fs5 = __require("fs");
-  const path8 = __require("path");
-  const pkgPath = path8.resolve(__dirname, "../package.json");
-  const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+  if (true) return "0.2.0";
+  const fs7 = __require("fs");
+  const path9 = __require("path");
+  const pkgPath = path9.resolve(__dirname, "../package.json");
+  const pkg = JSON.parse(fs7.readFileSync(pkgPath, "utf-8"));
   return pkg.version;
 }
 var VERSION = loadVersion();
@@ -1030,18 +1103,22 @@ var ALL_CHECKS = ["paths", "commands", "staleness", "tokens", "redundancy"];
 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("--ignore <checks>", "Comma-separated list of checks to ignore", "").action(async (projectPath, opts) => {
-  const resolvedPath = path7.resolve(projectPath);
+).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) => {
+  const resolvedPath = path8.resolve(projectPath);
+  const config = loadConfig(resolvedPath);
   const options = {
     projectPath: resolvedPath,
-    checks: opts.checks ? opts.checks.split(",").map((c) => c.trim()) : ALL_CHECKS,
-    strict: opts.strict,
+    checks: opts.checks ? opts.checks.split(",").map((c) => c.trim()) : config?.checks || ALL_CHECKS,
+    strict: opts.strict || config?.strict || false,
     format: opts.format,
     verbose: opts.verbose,
-    fix: false,
-    ignore: opts.ignore ? opts.ignore.split(",").map((c) => c.trim()) : [],
+    fix: opts.fix,
+    ignore: opts.ignore ? opts.ignore.split(",").map((c) => c.trim()) : config?.ignore || [],
     tokensOnly: opts.tokens
   };
+  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;
   try {
@@ -1142,6 +1219,16 @@ program.name("ctxlint").description(
       }
     };
     spinner?.stop();
+    if (options.fix) {
+      const fixSummary = applyFixes(result);
+      if (fixSummary.totalFixes > 0) {
+        console.log(
+          `
+Fixed ${fixSummary.totalFixes} issue${fixSummary.totalFixes !== 1 ? "s" : ""} in ${fixSummary.filesModified.length} file${fixSummary.filesModified.length !== 1 ? "s" : ""}.
+`
+        );
+      }
+    }
     if (options.tokensOnly) {
       console.log(formatTokenReport(result));
     } else if (options.format === "json") {
@@ -1160,6 +1247,36 @@ program.name("ctxlint").description(
     freeEncoder();
     resetGit();
     resetPathsCache();
+    resetTokenThresholds();
+  }
+});
+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"))) {
+    console.error('Error: not a git repository. Run "git init" first.');
+    process.exit(1);
+  }
+  if (!fs7.existsSync(hooksDir)) {
+    fs7.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 (existing.includes("ctxlint")) {
+      console.log("Pre-commit hook already includes ctxlint.");
+      return;
+    }
+    fs7.appendFileSync(hookPath, "\n" + hookContent);
+    console.log("Added ctxlint to existing pre-commit hook.");
+  } else {
+    fs7.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();

package/dist/mcp/server.js

@@ -495,13 +495,16 @@ async function checkPaths(file, projectRoot) {
     }
     let suggestion;
     let detail;
+    let fixTarget;
     const rename = await findRenames(projectRoot, ref.value);
     if (rename) {
+      fixTarget = rename.newPath;
       suggestion = `Did you mean ${rename.newPath}?`;
       detail = `Renamed ${rename.daysAgo} days ago in commit ${rename.commitHash}`;
     } else {
       const match = findClosestMatch(normalizedRef, projectFiles);
       if (match) {
+        fixTarget = match;
         suggestion = `Did you mean ${match}?`;
       }
     }
@@ -511,7 +514,8 @@ async function checkPaths(file, projectRoot) {
       line: ref.line,
       message: `${ref.value} does not exist`,
       suggestion,
-      detail
+      detail,
+      fix: fixTarget ? { file: file.filePath, line: ref.line, oldText: ref.value, newText: fixTarget } : void 0
     });
   }
   return issues;
@@ -700,13 +704,17 @@ async function checkStaleness(file, projectRoot) {
 }
 
 // src/core/checks/tokens.ts
-var INFO_THRESHOLD = 1e3;
-var WARNING_THRESHOLD = 3e3;
-var ERROR_THRESHOLD = 8e3;
+var DEFAULT_THRESHOLDS = {
+  info: 1e3,
+  warning: 3e3,
+  error: 8e3,
+  aggregate: 5e3
+};
+var currentThresholds = DEFAULT_THRESHOLDS;
 async function checkTokens(file, _projectRoot) {
   const issues = [];
   const tokens = file.totalTokens;
-  if (tokens >= ERROR_THRESHOLD) {
+  if (tokens >= currentThresholds.error) {
     issues.push({
       severity: "error",
       check: "tokens",
@@ -714,7 +722,7 @@ async function checkTokens(file, _projectRoot) {
       message: `${tokens.toLocaleString()} tokens \u2014 consumes significant context window space`,
       suggestion: "Consider splitting into focused sections or removing redundant content."
     });
-  } else if (tokens >= WARNING_THRESHOLD) {
+  } else if (tokens >= currentThresholds.warning) {
     issues.push({
       severity: "warning",
       check: "tokens",
@@ -722,7 +730,7 @@ async function checkTokens(file, _projectRoot) {
       message: `${tokens.toLocaleString()} tokens \u2014 large context file`,
       suggestion: "Consider trimming \u2014 research shows diminishing returns past ~300 lines."
     });
-  } else if (tokens >= INFO_THRESHOLD) {
+  } else if (tokens >= currentThresholds.info) {
     issues.push({
       severity: "info",
       check: "tokens",
@@ -734,7 +742,7 @@ async function checkTokens(file, _projectRoot) {
 }
 function checkAggregateTokens(files) {
   const total = files.reduce((sum, f) => sum + f.tokens, 0);
-  if (total > 5e3 && files.length > 1) {
+  if (total > currentThresholds.aggregate && files.length > 1) {
     return {
       severity: "warning",
       check: "tokens",
@@ -914,7 +922,7 @@ import * as path7 from "path";
 
 // src/version.ts
 function loadVersion() {
-  if (true) return "0.1.1";
+  if (true) return "0.2.0";
   const fs5 = __require("fs");
   const path8 = __require("path");
   const pkgPath = path8.resolve(__dirname, "../package.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ctxlint",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Lint your AI agent context files (CLAUDE.md, AGENTS.md, etc.) against your actual codebase",
   "bin": {
     "ctxlint": "dist/index.js"