@yawlabs/ctxlint 0.2.2 → 0.4.0

package/dist/cli-VYWAONGX.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+import {
+  ALL_CHECKS,
+  VERSION,
+  applyFixes,
+  freeEncoder,
+  resetGit,
+  resetPathsCache,
+  resetTokenThresholds,
+  runAudit,
+  setTokenThresholds
+} from "./chunk-WEYNMCAH.js";
+
+// src/cli.ts
+import * as fs2 from "fs";
+import { Command } from "commander";
+import ora from "ora";
+
+// src/core/reporter.ts
+import chalk from "chalk";
+function formatText(result, verbose = false) {
+  const lines = [];
+  lines.push("");
+  lines.push(chalk.bold(`ctxlint v${result.version}`));
+  lines.push("");
+  lines.push(`Scanning ${result.projectRoot}...`);
+  lines.push("");
+  const totalTokens = result.summary.totalTokens;
+  lines.push(
+    `Found ${result.files.length} context file${result.files.length !== 1 ? "s" : ""} (${totalTokens.toLocaleString()} tokens total)`
+  );
+  for (const file of result.files) {
+    let desc = `  ${file.path} (${file.tokens.toLocaleString()} tokens, ${file.lines} lines)`;
+    if (file.isSymlink && file.symlinkTarget) {
+      desc = `  ${file.path} ${chalk.dim(`\u2192 ${file.symlinkTarget} (symlink)`)}`;
+    }
+    lines.push(desc);
+  }
+  lines.push("");
+  for (const file of result.files) {
+    const fileIssues = file.issues;
+    if (fileIssues.length === 0 && !verbose) continue;
+    lines.push(chalk.underline(file.path));
+    if (fileIssues.length === 0) {
+      lines.push(chalk.green("  \u2713 All checks passed"));
+    } else {
+      for (const issue of fileIssues) {
+        lines.push(formatIssue(issue));
+      }
+    }
+    lines.push("");
+  }
+  const { errors, warnings, info } = result.summary;
+  const parts = [];
+  if (errors > 0) parts.push(chalk.red(`${errors} error${errors !== 1 ? "s" : ""}`));
+  if (warnings > 0) parts.push(chalk.yellow(`${warnings} warning${warnings !== 1 ? "s" : ""}`));
+  if (info > 0) parts.push(chalk.blue(`${info} info`));
+  if (parts.length > 0) {
+    lines.push(`Summary: ${parts.join(", ")}`);
+  } else {
+    lines.push(chalk.green("No issues found!"));
+  }
+  lines.push(`  Token usage: ${totalTokens.toLocaleString()} tokens per agent session`);
+  if (result.summary.estimatedWaste > 0) {
+    lines.push(`  Estimated waste: ~${result.summary.estimatedWaste} tokens (redundant content)`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function formatJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+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(
+    `  ${chalk.dim("File".padEnd(maxPathLen))}  ${chalk.dim("Tokens".padStart(8))}  ${chalk.dim("Lines".padStart(6))}`
+  );
+  lines.push(`  ${"\u2500".repeat(maxPathLen)}  ${"\u2500".repeat(8)}  ${"\u2500".repeat(6)}`);
+  for (const file of result.files) {
+    const tokenStr = file.tokens.toLocaleString().padStart(8);
+    const lineStr = file.lines.toString().padStart(6);
+    lines.push(`  ${file.path.padEnd(maxPathLen)}  ${tokenStr}  ${lineStr}`);
+  }
+  lines.push(`  ${"\u2500".repeat(maxPathLen)}  ${"\u2500".repeat(8)}  ${"\u2500".repeat(6)}`);
+  lines.push(
+    `  ${"Total".padEnd(maxPathLen)}  ${result.summary.totalTokens.toLocaleString().padStart(8)}`
+  );
+  if (result.summary.estimatedWaste > 0) {
+    lines.push("");
+    lines.push(
+      chalk.yellow(
+        `  ~${result.summary.estimatedWaste} tokens estimated waste from redundant content`
+      )
+    );
+  }
+  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}: ` : "";
+  let line = `  ${icon} ${lineRef}${issue.message}`;
+  if (issue.suggestion) {
+    line += `
+    ${chalk.dim("\u2192")} ${chalk.dim(issue.suggestion)}`;
+  }
+  if (issue.detail) {
+    line += `
+    ${chalk.dim(issue.detail)}`;
+  }
+  return line;
+}
+
+// src/core/config.ts
+import * as fs from "fs";
+import * as path from "path";
+var CONFIG_FILENAMES = [".ctxlintrc", ".ctxlintrc.json"];
+function loadConfig(projectRoot) {
+  for (const filename of CONFIG_FILENAMES) {
+    const filePath = path.join(projectRoot, filename);
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// src/cli.ts
+import * as path2 from "path";
+async function runCli() {
+  const 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, 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 = path2.resolve(projectPath);
+    const configPath = opts.config ? path2.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,
+      strict: opts.strict || config?.strict || false,
+      format: opts.format,
+      verbose: opts.verbose,
+      fix: opts.fix,
+      ignore: opts.ignore ? opts.ignore.split(",").map((c) => c.trim()) : config?.ignore || [],
+      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" && !options.quiet ? ora("Scanning for context files...").start() : void 0;
+    try {
+      if (spinner) spinner.text = "Running checks...";
+      const result = await runAudit(resolvedPath, activeChecks, {
+        depth: options.depth,
+        extraPatterns: config?.contextFiles
+      });
+      spinner?.stop();
+      if (result.files.length === 0) {
+        if (!options.quiet) {
+          if (options.format === "json") {
+            console.log(JSON.stringify(result));
+          } else if (options.format === "sarif") {
+            console.log(formatSarif(result));
+          } else {
+            console.log("\nNo context files found.\n");
+          }
+        }
+        process.exit(0);
+      }
+      if (options.fix) {
+        const fixSummary = applyFixes(result);
+        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" : ""}.
+`
+          );
+        }
+      }
+      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);
+      }
+    } catch (err) {
+      spinner?.stop();
+      console.error("Error:", err instanceof Error ? err.message : err);
+      process.exit(2);
+    } finally {
+      freeEncoder();
+      resetGit();
+      resetPathsCache();
+      resetTokenThresholds();
+    }
+  });
+  program.command("init").description("Set up a git pre-commit hook that runs ctxlint --strict").action(async () => {
+    const hooksDir = path2.resolve(".git", "hooks");
+    if (!fs2.existsSync(path2.resolve(".git"))) {
+      console.error('Error: not a git repository. Run "git init" first.');
+      process.exit(1);
+    }
+    if (!fs2.existsSync(hooksDir)) {
+      fs2.mkdirSync(hooksDir, { recursive: true });
+    }
+    const hookPath = path2.join(hooksDir, "pre-commit");
+    const hookContent = `#!/bin/sh
+# ctxlint pre-commit hook
+npx @yawlabs/ctxlint --strict
+`;
+    if (fs2.existsSync(hookPath)) {
+      const existing = fs2.readFileSync(hookPath, "utf-8");
+      if (existing.includes("ctxlint")) {
+        console.log("Pre-commit hook already includes ctxlint.");
+        return;
+      }
+      fs2.appendFileSync(hookPath, "\n" + hookContent);
+      console.log("Added ctxlint to existing pre-commit hook.");
+    } else {
+      fs2.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 = fs2.readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    console.error(`Error: could not load config from ${configPath}`);
+    process.exit(2);
+  }
+}
+export {
+  runCli
+};