agent-context-lint 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+interface LintFinding {
+    file: string;
+    rule: string;
+    line: number;
+    column: number;
+    severity: 'error' | 'warning';
+    message: string;
+}
+interface FileResult {
+    file: string;
+    findings: LintFinding[];
+    score: number;
+}
+interface LintResult {
+    files: FileResult[];
+    totalFindings: number;
+    errors: number;
+    warnings: number;
+}
+interface CLIOptions {
+    files: string[];
+    format: 'text' | 'json';
+    fix: boolean;
+    cwd: string;
+}
+interface Config {
+    tokenBudget: {
+        warn: number;
+        error: number;
+    };
+    requiredSections: string[];
+    staleDateYears: number;
+    vaguePatterns: string[];
+    ignore: string[];
+}
+
+declare function discoverContextFiles(cwd: string): string[];
+
+interface ParsedFile {
+    content: string;
+    lines: string[];
+    paths: PathReference[];
+    commands: CommandReference[];
+    sections: string[];
+    codeBlocks: CodeBlock[];
+    inlineCode: InlineCode[];
+}
+interface PathReference {
+    value: string;
+    line: number;
+    column: number;
+}
+interface CommandReference {
+    value: string;
+    line: number;
+    column: number;
+}
+interface CodeBlock {
+    content: string;
+    lang: string;
+    line: number;
+}
+interface InlineCode {
+    content: string;
+    line: number;
+    column: number;
+}
+declare function parseFile(filePath: string): ParsedFile;
+
+/**
+ * Computes a 0–100 quality score for a file based on its findings.
+ *
+ * Starts at 100 and deducts:
+ * - 15 points per error
+ * - 5 points per warning
+ *
+ * Minimum score is 0.
+ */
+declare function computeScore(findings: LintFinding[]): number;
+
+declare function loadConfig(cwd: string): Config;
+
+declare function formatText(result: LintResult, cwd: string): string;
+declare function formatJson(result: LintResult, cwd: string): string;
+
+declare function lintFile(filePath: string, cwd: string): FileResult;
+declare function lint(cwd: string, files?: string[]): LintResult;
+
+export { type CLIOptions, type Config, type FileResult, type LintFinding, type LintResult, computeScore, discoverContextFiles, formatJson, formatText, lint, lintFile, loadConfig, parseFile };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+interface LintFinding {
+    file: string;
+    rule: string;
+    line: number;
+    column: number;
+    severity: 'error' | 'warning';
+    message: string;
+}
+interface FileResult {
+    file: string;
+    findings: LintFinding[];
+    score: number;
+}
+interface LintResult {
+    files: FileResult[];
+    totalFindings: number;
+    errors: number;
+    warnings: number;
+}
+interface CLIOptions {
+    files: string[];
+    format: 'text' | 'json';
+    fix: boolean;
+    cwd: string;
+}
+interface Config {
+    tokenBudget: {
+        warn: number;
+        error: number;
+    };
+    requiredSections: string[];
+    staleDateYears: number;
+    vaguePatterns: string[];
+    ignore: string[];
+}
+
+declare function discoverContextFiles(cwd: string): string[];
+
+interface ParsedFile {
+    content: string;
+    lines: string[];
+    paths: PathReference[];
+    commands: CommandReference[];
+    sections: string[];
+    codeBlocks: CodeBlock[];
+    inlineCode: InlineCode[];
+}
+interface PathReference {
+    value: string;
+    line: number;
+    column: number;
+}
+interface CommandReference {
+    value: string;
+    line: number;
+    column: number;
+}
+interface CodeBlock {
+    content: string;
+    lang: string;
+    line: number;
+}
+interface InlineCode {
+    content: string;
+    line: number;
+    column: number;
+}
+declare function parseFile(filePath: string): ParsedFile;
+
+/**
+ * Computes a 0–100 quality score for a file based on its findings.
+ *
+ * Starts at 100 and deducts:
+ * - 15 points per error
+ * - 5 points per warning
+ *
+ * Minimum score is 0.
+ */
+declare function computeScore(findings: LintFinding[]): number;
+
+declare function loadConfig(cwd: string): Config;
+
+declare function formatText(result: LintResult, cwd: string): string;
+declare function formatJson(result: LintResult, cwd: string): string;
+
+declare function lintFile(filePath: string, cwd: string): FileResult;
+declare function lint(cwd: string, files?: string[]): LintResult;
+
+export { type CLIOptions, type Config, type FileResult, type LintFinding, type LintResult, computeScore, discoverContextFiles, formatJson, formatText, lint, lintFile, loadConfig, parseFile };

package/dist/index.js

@@ -0,0 +1,461 @@
+// 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 };
+}
+export {
+  computeScore,
+  discoverContextFiles,
+  formatJson,
+  formatText,
+  lint,
+  lintFile,
+  loadConfig,
+  parseFile
+};
+//# sourceMappingURL=index.js.map