agent-context-lint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,114 @@
+# agent-context-lint
+
+Lint AI coding agent context files for staleness, broken paths, and semantic quality issues.
+
+Supports **CLAUDE.md**, **AGENTS.md**, **.cursorrules**, and **copilot-instructions.md**.
+
+## Quickstart
+
+```bash
+npx agent-context-lint
+```
+
+Auto-discovers context files in the current directory and runs both structural and semantic checks.
+
+## The problem
+
+Every engineering team using Claude Code, Cursor, Copilot, or Codex has context files that drift silently away from reality as the codebase changes. Broken paths, missing scripts, stale dates, and vague instructions degrade agent performance and inflate token costs.
+
+[Research shows](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) most AGENTS.md files lack the sections that most improve agent task performance. [Studies confirm](https://devcenter.upsun.com/posts/agents-md-less-is-more/) poor context files inflate token costs by 20%+.
+
+No existing tool does both structural validation (do referenced paths and scripts actually exist?) and semantic quality scoring (are instructions specific and actionable?).
+
+## What it checks
+
+### Layer 1 — Repo-state validation
+
+| Rule | Severity | What it catches |
+|------|----------|----------------|
+| `check:paths` | error | File/directory paths mentioned in context file that don't exist on disk |
+| `check:scripts` | error | npm/pnpm/yarn/bun scripts referenced that aren't in package.json |
+
+### Layer 2 — Semantic quality
+
+| Rule | Severity | What it catches |
+|------|----------|----------------|
+| `check:token-budget` | warn/error | Files exceeding token thresholds (warn: 2,000, error: 5,000) |
+| `check:vague` | warning | Vague instructions like "follow best practices" or "use good judgment" |
+| `check:required-sections` | warning | Missing recommended sections (Setup, Testing, Build) |
+| `check:stale-dates` | warning | Year references older than 2 years |
+| `check:contradictions` | warning | Contradictory directives ("always use X" + "never use X") |
+
+Each file gets a **0–100 quality score** based on findings.
+
+### Example output
+
+```
+  CLAUDE.md  (score: 70/100)
+    3:5  x Path does not exist: ./src/old-module.ts  [check:paths]
+    7:1  ! Vague instruction: "follow best practices"  [check:vague]
+    1:1  ! Missing recommended section: "Testing"  [check:required-sections]
+
+  1 problems (1 errors, 2 warnings)
+```
+
+## CLI options
+
+```
+npx agent-context-lint                  # auto-discover and lint all context files
+npx agent-context-lint CLAUDE.md        # lint a specific file
+npx agent-context-lint --format json    # machine-readable output for CI
+npx agent-context-lint --json           # shorthand for --format json
+npx agent-context-lint -V               # show version
+```
+
+Exit code 1 on any error (CI-compatible).
+
+## Configuration
+
+Create `.agent-context-lint.json` in your project root, or add an `agentContextLint` key to `package.json`:
+
+```json
+{
+  "tokenBudget": { "warn": 2000, "error": 5000 },
+  "requiredSections": ["Setup", "Testing", "Build"],
+  "staleDateYears": 2,
+  "vaguePatterns": ["follow best practices", "be careful", "use good judgment"],
+  "ignore": []
+}
+```
+
+## Programmatic API
+
+```typescript
+import { lint, lintFile } from 'agent-context-lint';
+
+const result = lint(process.cwd());
+// result.files[0].score → 85
+// result.files[0].findings → [{ rule: 'check:paths', ... }]
+
+const fileResult = lintFile('./CLAUDE.md', process.cwd());
+```
+
+## Prior art
+
+- [agents-lint](https://github.com/giacomo/agents-lint) — structural checks only (paths, scripts, freshness score). No semantic quality scoring.
+- [ai-context-kit](https://github.com/ofershap/ai-context-kit) — semantic checks only (token budget, vague instructions, contradictions). No repo-state validation.
+- [@carlrannaberg/cclint](https://github.com/carlrannaberg/cclint) — Claude Code-specific. Not useful for AGENTS.md or .cursorrules.
+
+agent-context-lint combines both structural and semantic checks in a single tool.
+
+## Contributing
+
+Contributions welcome. Please open an issue first to discuss what you'd like to change.
+
+```bash
+git clone https://github.com/mattschaller/agent-context-lint
+cd agent-context-lint
+npm install
+npm test
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { resolve as resolve4 } from "path";
+
+// src/checkers.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+function checkPaths(parsed, filePath) {
+  const findings = [];
+  const baseDir = dirname(filePath);
+  for (const ref of parsed.paths) {
+    const resolved = resolve(baseDir, ref.value);
+    if (!existsSync(resolved)) {
+      findings.push({
+        file: filePath,
+        rule: "check:paths",
+        line: ref.line,
+        column: ref.column,
+        severity: "error",
+        message: `Path does not exist: ${ref.value}`
+      });
+    }
+  }
+  return findings;
+}
+function checkScripts(parsed, filePath) {
+  const findings = [];
+  const baseDir = dirname(filePath);
+  const pkgPath = resolve(baseDir, "package.json");
+  let scripts = {};
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      scripts = pkg.scripts || {};
+    } catch {
+      return findings;
+    }
+  } else {
+    return findings;
+  }
+  for (const cmd of parsed.commands) {
+    const match = /(?:npm|pnpm|yarn|bun)\s+run\s+([\w:@./-]+)/.exec(cmd.value);
+    const directMatch = /(?:npm|pnpm|yarn|bun)\s+(test|start|build|lint)\b/.exec(
+      cmd.value
+    );
+    const scriptName = match?.[1] || directMatch?.[1];
+    if (scriptName && !(scriptName in scripts)) {
+      findings.push({
+        file: filePath,
+        rule: "check:scripts",
+        line: cmd.line,
+        column: cmd.column,
+        severity: "error",
+        message: `Script not found in package.json: "${scriptName}"`
+      });
+    }
+  }
+  return findings;
+}
+function checkTokenBudget(parsed, filePath, config) {
+  const findings = [];
+  const estimatedTokens = Math.ceil(parsed.content.length / 4);
+  if (estimatedTokens > config.tokenBudget.error) {
+    findings.push({
+      file: filePath,
+      rule: "check:token-budget",
+      line: 1,
+      column: 1,
+      severity: "error",
+      message: `File is ~${estimatedTokens} tokens (limit: ${config.tokenBudget.error}). Consider splitting or condensing.`
+    });
+  } else if (estimatedTokens > config.tokenBudget.warn) {
+    findings.push({
+      file: filePath,
+      rule: "check:token-budget",
+      line: 1,
+      column: 1,
+      severity: "warning",
+      message: `File is ~${estimatedTokens} tokens (warn threshold: ${config.tokenBudget.warn}). Consider condensing.`
+    });
+  }
+  return findings;
+}
+function checkVague(parsed, filePath, config) {
+  const findings = [];
+  for (let i = 0; i < parsed.lines.length; i++) {
+    const line = parsed.lines[i].toLowerCase();
+    for (const pattern of config.vaguePatterns) {
+      if (line.includes(pattern.toLowerCase())) {
+        findings.push({
+          file: filePath,
+          rule: "check:vague",
+          line: i + 1,
+          column: line.indexOf(pattern.toLowerCase()) + 1,
+          severity: "warning",
+          message: `Vague instruction: "${pattern}". Replace with specific, actionable guidance.`
+        });
+      }
+    }
+  }
+  return findings;
+}
+function checkRequiredSections(parsed, filePath, config) {
+  const findings = [];
+  const normalizedSections = parsed.sections.map((s) => s.toLowerCase());
+  for (const required of config.requiredSections) {
+    const found = normalizedSections.some(
+      (s) => s.includes(required.toLowerCase())
+    );
+    if (!found) {
+      findings.push({
+        file: filePath,
+        rule: "check:required-sections",
+        line: 1,
+        column: 1,
+        severity: "warning",
+        message: `Missing recommended section: "${required}"`
+      });
+    }
+  }
+  return findings;
+}
+function checkStaleDates(parsed, filePath, config) {
+  const findings = [];
+  const currentYear = (/* @__PURE__ */ new Date()).getFullYear();
+  const threshold = currentYear - config.staleDateYears;
+  const yearPattern = /\b(20[0-9]{2})\b/g;
+  for (let i = 0; i < parsed.lines.length; i++) {
+    let match;
+    yearPattern.lastIndex = 0;
+    while ((match = yearPattern.exec(parsed.lines[i])) !== null) {
+      const year = parseInt(match[1], 10);
+      if (year < threshold) {
+        findings.push({
+          file: filePath,
+          rule: "check:stale-dates",
+          line: i + 1,
+          column: match.index + 1,
+          severity: "warning",
+          message: `Possibly stale year reference: ${year} (older than ${config.staleDateYears} years)`
+        });
+      }
+    }
+  }
+  return findings;
+}
+function checkContradictions(parsed, filePath) {
+  const findings = [];
+  const contradictionPairs = [
+    [
+      /\balways use (\w+)/i,
+      /\bnever use (\w+)/i,
+      'Contradictory "always use" and "never use" directives'
+    ],
+    [
+      /\bdo not (?:use|add|include) (comments|docstrings|type annotations)/i,
+      /\b(?:always|must) (?:add|include|write) \1/i,
+      "Contradictory directives about adding/not adding"
+    ],
+    [
+      /\bprefer (\w+) over (\w+)/i,
+      /\bprefer \2 over \1/i,
+      "Contradictory preference directives"
+    ]
+  ];
+  const lineTexts = parsed.lines;
+  for (const [patternA, patternB, message] of contradictionPairs) {
+    const matchesA = [];
+    const matchesB = [];
+    for (let i = 0; i < lineTexts.length; i++) {
+      const lineText = lineTexts[i];
+      const a = patternA.exec(lineText);
+      if (a) matchesA.push({ line: i + 1, match: a });
+      const b = patternB.exec(lineText);
+      if (b) matchesB.push({ line: i + 1, match: b });
+    }
+    if (matchesA.length > 0 && matchesB.length > 0) {
+      for (const a of matchesA) {
+        for (const b of matchesB) {
+          if (a.match[1] && b.match[1] && a.match[1].toLowerCase() === b.match[1].toLowerCase()) {
+            findings.push({
+              file: filePath,
+              rule: "check:contradictions",
+              line: b.line,
+              column: 1,
+              severity: "warning",
+              message: `${message} (conflicts with line ${a.line})`
+            });
+          }
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+// src/config.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+
+// src/types.ts
+var DEFAULT_CONFIG = {
+  tokenBudget: { warn: 2e3, error: 5e3 },
+  requiredSections: ["Setup", "Testing", "Build"],
+  staleDateYears: 2,
+  vaguePatterns: [
+    "follow best practices",
+    "be careful",
+    "use good judgment",
+    "use common sense",
+    "as appropriate",
+    "when necessary",
+    "if needed",
+    "as needed",
+    "handle edge cases",
+    "write clean code",
+    "keep it simple",
+    "use proper",
+    "ensure quality"
+  ],
+  ignore: []
+};
+var CONTEXT_FILE_NAMES = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".cursorrules",
+  "copilot-instructions.md",
+  ".github/copilot-instructions.md"
+];
+
+// src/config.ts
+function loadConfig(cwd) {
+  const configPath = resolve2(cwd, ".agent-context-lint.json");
+  if (existsSync2(configPath)) {
+    try {
+      const raw = JSON.parse(readFileSync2(configPath, "utf-8"));
+      return mergeConfig(raw);
+    } catch {
+    }
+  }
+  const pkgPath = resolve2(cwd, "package.json");
+  if (existsSync2(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+      if (pkg.agentContextLint) {
+        return mergeConfig(pkg.agentContextLint);
+      }
+    } catch {
+    }
+  }
+  return { ...DEFAULT_CONFIG };
+}
+function mergeConfig(overrides) {
+  return {
+    tokenBudget: {
+      ...DEFAULT_CONFIG.tokenBudget,
+      ...overrides.tokenBudget
+    },
+    requiredSections: overrides.requiredSections ?? DEFAULT_CONFIG.requiredSections,
+    staleDateYears: overrides.staleDateYears ?? DEFAULT_CONFIG.staleDateYears,
+    vaguePatterns: overrides.vaguePatterns ?? DEFAULT_CONFIG.vaguePatterns,
+    ignore: overrides.ignore ?? DEFAULT_CONFIG.ignore
+  };
+}
+
+// src/discovery.ts
+import { existsSync as existsSync3 } from "fs";
+import { resolve as resolve3 } from "path";
+function discoverContextFiles(cwd) {
+  const found = [];
+  for (const name of CONTEXT_FILE_NAMES) {
+    const fullPath = resolve3(cwd, name);
+    if (existsSync3(fullPath)) {
+      found.push(fullPath);
+    }
+  }
+  return found;
+}
+
+// src/parser.ts
+import { readFileSync as readFileSync3 } from "fs";
+var PATH_PATTERN = /(?:^|\s|`)(\.?\.?\/[\w./@-]+[\w/@-])/g;
+var COMMAND_PATTERN = /(?:npm|npx|pnpm|yarn|bun|bunx)\s+(?:run\s+)?[\w:@./-]+/g;
+var HEADING_PATTERN = /^#{1,6}\s+(.+)$/;
+var FENCED_BLOCK_START = /^```(\w*)/;
+var FENCED_BLOCK_END = /^```\s*$/;
+var INLINE_CODE_PATTERN = /`([^`]+)`/g;
+function parseFile(filePath) {
+  const content = readFileSync3(filePath, "utf-8");
+  const lines = content.split("\n");
+  const paths = [];
+  const commands = [];
+  const sections = [];
+  const codeBlocks = [];
+  const inlineCode = [];
+  let inCodeBlock = false;
+  let codeBlockLang = "";
+  let codeBlockContent = "";
+  let codeBlockStart = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+    if (!inCodeBlock) {
+      const blockStart = FENCED_BLOCK_START.exec(line);
+      if (blockStart && line.trimStart().startsWith("```")) {
+        inCodeBlock = true;
+        codeBlockLang = blockStart[1] || "";
+        codeBlockContent = "";
+        codeBlockStart = lineNum;
+        continue;
+      }
+    } else {
+      if (FENCED_BLOCK_END.test(line) && line.trimStart() === "```") {
+        codeBlocks.push({
+          content: codeBlockContent,
+          lang: codeBlockLang,
+          line: codeBlockStart
+        });
+        inCodeBlock = false;
+        continue;
+      }
+      codeBlockContent += (codeBlockContent ? "\n" : "") + line;
+    }
+    const headingMatch = HEADING_PATTERN.exec(line);
+    if (headingMatch) {
+      sections.push(headingMatch[1].trim());
+    }
+    let pathMatch;
+    PATH_PATTERN.lastIndex = 0;
+    while ((pathMatch = PATH_PATTERN.exec(line)) !== null) {
+      const value = pathMatch[1];
+      if (value.includes("://")) continue;
+      paths.push({
+        value,
+        line: lineNum,
+        column: pathMatch.index + (pathMatch[0].length - value.length) + 1
+      });
+    }
+    let cmdMatch;
+    COMMAND_PATTERN.lastIndex = 0;
+    while ((cmdMatch = COMMAND_PATTERN.exec(line)) !== null) {
+      commands.push({
+        value: cmdMatch[0],
+        line: lineNum,
+        column: cmdMatch.index + 1
+      });
+    }
+    if (!inCodeBlock) {
+      let inlineMatch;
+      INLINE_CODE_PATTERN.lastIndex = 0;
+      while ((inlineMatch = INLINE_CODE_PATTERN.exec(line)) !== null) {
+        inlineCode.push({
+          content: inlineMatch[1],
+          line: lineNum,
+          column: inlineMatch.index + 2
+        });
+      }
+    }
+  }
+  return { content, lines, paths, commands, sections, codeBlocks, inlineCode };
+}
+
+// src/scorer.ts
+function computeScore(findings) {
+  let score = 100;
+  for (const finding of findings) {
+    if (finding.severity === "error") {
+      score -= 15;
+    } else {
+      score -= 5;
+    }
+  }
+  return Math.max(0, score);
+}
+
+// src/reporter.ts
+import { relative } from "path";
+function formatText(result, cwd) {
+  const lines = [];
+  for (const file of result.files) {
+    const relPath = relative(cwd, file.file);
+    lines.push(`
+  ${relPath}  (score: ${file.score}/100)`);
+    if (file.findings.length === 0) {
+      lines.push("    No issues found.");
+      continue;
+    }
+    for (const f of file.findings) {
+      const icon = f.severity === "error" ? "x" : "!";
+      lines.push(
+        `    ${f.line}:${f.column}  ${icon} ${f.message}  [${f.rule}]`
+      );
+    }
+  }
+  lines.push("");
+  lines.push(
+    `  ${result.totalFindings} problems (${result.errors} errors, ${result.warnings} warnings)`
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function formatJson(result, cwd) {
+  const output = {
+    ...result,
+    files: result.files.map((f) => ({
+      ...f,
+      file: relative(cwd, f.file)
+    }))
+  };
+  return JSON.stringify(output, null, 2);
+}
+
+// src/index.ts
+function lintFile(filePath, cwd) {
+  const config = loadConfig(cwd);
+  const parsed = parseFile(filePath);
+  const findings = [
+    ...checkPaths(parsed, filePath),
+    ...checkScripts(parsed, filePath),
+    ...checkTokenBudget(parsed, filePath, config),
+    ...checkVague(parsed, filePath, config),
+    ...checkRequiredSections(parsed, filePath, config),
+    ...checkStaleDates(parsed, filePath, config),
+    ...checkContradictions(parsed, filePath)
+  ];
+  return {
+    file: filePath,
+    findings,
+    score: computeScore(findings)
+  };
+}
+function lint(cwd, files) {
+  const targetFiles = files && files.length > 0 ? files.map((f) => resolve4(cwd, f)) : discoverContextFiles(cwd);
+  if (targetFiles.length === 0) {
+    return { files: [], totalFindings: 0, errors: 0, warnings: 0 };
+  }
+  const results = targetFiles.map((f) => lintFile(f, cwd));
+  const totalFindings = results.reduce(
+    (sum, r) => sum + r.findings.length,
+    0
+  );
+  const errors = results.reduce(
+    (sum, r) => sum + r.findings.filter((f) => f.severity === "error").length,
+    0
+  );
+  const warnings = results.reduce(
+    (sum, r) => sum + r.findings.filter((f) => f.severity === "warning").length,
+    0
+  );
+  return { files: results, totalFindings, errors, warnings };
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const options = {
+    files: [],
+    format: "text",
+    fix: false,
+    cwd: process.cwd()
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--format" && args[i + 1]) {
+      const fmt = args[++i];
+      if (fmt === "json" || fmt === "text") {
+        options.format = fmt;
+      }
+    } else if (arg === "--json") {
+      options.format = "json";
+    } else if (arg === "--fix") {
+      options.fix = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    } else if (arg === "--version" || arg === "-V") {
+      console.log("0.1.0");
+      process.exit(0);
+    } else if (!arg.startsWith("-")) {
+      options.files.push(arg);
+    }
+  }
+  return options;
+}
+function printHelp() {
+  console.log(`
+  agent-context-lint \u2014 Lint AI coding agent context files
+
+  Usage:
+    npx agent-context-lint              Auto-discover and lint all context files
+    npx agent-context-lint CLAUDE.md    Lint a specific file
+    npx agent-context-lint --format json  Machine-readable output for CI
+
+  Options:
+    --format <text|json>  Output format (default: text)
+    --json                Shorthand for --format json
+    --fix                 Auto-fix safe issues (not yet implemented)
+    -V, --version         Show version
+    -h, --help            Show this help
+
+  Context files detected:
+    CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md,
+    .github/copilot-instructions.md
+
+  Configuration:
+    .agent-context-lint.json or "agentContextLint" key in package.json
+`);
+}
+function main() {
+  const options = parseArgs(process.argv);
+  const result = lint(
+    options.cwd,
+    options.files.length > 0 ? options.files : void 0
+  );
+  if (result.files.length === 0) {
+    console.log("No context files found.");
+    process.exit(0);
+  }
+  const output = options.format === "json" ? formatJson(result, options.cwd) : formatText(result, options.cwd);
+  console.log(output);
+  process.exit(result.errors > 0 ? 1 : 0);
+}
+main();
+//# sourceMappingURL=cli.js.map