@chimix/agentscan 0.1.0 → 0.2.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@chimix/agentscan",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Find broken agent configuration in a project — hooks whose scripts are gone, MCP servers that cannot start, skills that disagree with their lockfile",
   "type": "module",
   "bin": {
-    "agentscan": "./src/cli.ts"
+    "agentscan": "./dist/cli.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "src",
+    "dist",
     "README.md",
     "LICENSE"
   ],
@@ -34,14 +34,16 @@
   },
   "author": "Sima Alexandru <sima.alex33@gmail.com>",
   "scripts": {
-    "preinstall": "node -e \"try{require('child_process').execSync('bun --version',{stdio:'ignore'})}catch{console.error('\\n  agentscan runs on Bun. Install it: https://bun.sh\\n  (the CLI will not start without it)\\n')}\"",
     "agentscan": "bun run src/cli.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "check": "bun run src/cli.ts check",
-    "spec:check": "bun run scripts/spec-drift.ts"
+    "spec:check": "bun run scripts/spec-drift.ts",
+    "build": "bun build src/cli.ts --target=node --outfile dist/cli.js --banner '#!/usr/bin/env node'",
+    "prepublishOnly": "bun run build"
   },
   "engines": {
+    "node": ">=20.11.0",
     "bun": ">=1.1.0"
   },
   "license": "MIT",

package/src/analyze.ts

@@ -1,82 +0,0 @@
-import { resolve } from "node:path";
-import { runChecks } from "./checks/index";
-import { loadConfig } from "./config/load";
-import type { AgentscanConfig } from "./config/schema";
-import { resolveRoot } from "./discover/index";
-import { extractFacts } from "./facts/extract";
-import type { Facts, Finding } from "./facts/types";
-import { sortFindings } from "./report/sort";
-
-export type AnalyzeOptions = {
-  dir?: string;
-  global?: boolean;
-  configPath?: string;
-  failOn?: AgentscanConfig["failOn"];
-};
-
-export type Analysis = {
-  root: string;
-  /** Set only when the requested directory was not itself the project root. */
-  resolvedFrom?: string;
-  config: AgentscanConfig;
-  facts: Facts;
-  findings: Finding[];
-};
-
-/**
- * The one definition of "what is wrong with this project".
- *
- * Every command that reports on a project goes through here — `explain`
- * silently missed every structural finding while it built its own pipeline.
- */
-export function analyze(options: AnalyzeOptions = {}): Analysis {
-  const requested = resolve(options.dir ?? process.cwd());
-  const root = resolveRoot(requested);
-  const loaded = loadConfig(root, options.configPath);
-
-  const config: AgentscanConfig = {
-    ...loaded,
-    ...(options.failOn !== undefined ? { failOn: options.failOn } : {}),
-    ...(options.global !== undefined ? { includeGlobal: options.global } : {}),
-  };
-
-  const includeGlobal = options.global ?? config.includeGlobal;
-  const facts = extractFacts(root, config, { includeGlobal });
-
-  const ignoredSkills = new Set(config.ignoreSkills);
-  const ignoredRules = new Set(config.ignoreRules);
-
-  const structural = runChecks(facts, {
-    requireLock: config.requireLock,
-    skillDescriptionBytes: config.thresholds.skillDescriptionBytes,
-    budgets: {
-      agentsMdLines: config.thresholds.agentsMdLines,
-      claudeMdLines: config.thresholds.claudeMdLines,
-      agents: config.thresholds.agents,
-      mcp: config.thresholds.mcp,
-    },
-  }).filter(
-    (f) =>
-      !ignoredRules.has(f.ruleId) &&
-      !(
-        f.subject.startsWith("skill:") &&
-        ignoredSkills.has(f.subject.slice("skill:".length))
-      ),
-  );
-
-  // Suppression by exact finding id. Without it a single false positive costs
-  // an entire check via ignoreRules — and under the README's CI recipe that is
-  // the only way to get a build green again.
-  const ignoredFindings = new Set(config.ignoreFindings);
-  const findings = sortFindings(
-    structural.filter((f) => !ignoredFindings.has(f.id)),
-  );
-
-  return {
-    root,
-    ...(root === requested ? {} : { resolvedFrom: requested }),
-    config,
-    facts,
-    findings,
-  };
-}

package/src/checks/budgets.ts

@@ -1,189 +0,0 @@
-import { basename } from "node:path";
-import type { Facts, Finding } from "../facts/types";
-import { make } from "./make";
-
-type PolicyFile = Facts["policyFiles"][number];
-
-/**
- * Budget checks: the config is well-formed, but there is too much of it.
- *
- * These used to be five YAML files evaluated by a 581-line rule engine. Across
- * 21 real projects that engine produced 9 findings from 3 of its 5 rules, while
- * every actionable finding came from the structural checks next door. The
- * engine's one remaining job was letting users write their own rules — a
- * feature nobody had used, on a tool with no users, whose concrete case
- * (retuning a budget) `thresholds` in `.agentscanrc.json` already covered
- * without any YAML. It was deleted; see plans/010.
- *
- * Every finding these emit is byte-identical to what the rules produced,
- * including the `rule:` subjects, which is why the ids look the way they do.
- *
- * All of them are **info**. They are judgement calls about size, sourced to
- * docs/spec/thresholds.md, not defects — a project can sit over any of these
- * budgets deliberately. Nothing here should ever fail a build.
- */
-
-type BudgetOptions = {
-  agentsMdLines: number;
-  claudeMdLines: number;
-  agents: number;
-  mcp: number;
-};
-
-/**
- * Lines the way `wc -l` counts them: a trailing newline terminates the last
- * line, it does not start another one.
- */
-function lineCount(text: string): number {
-  return text.length === 0 ? 0 : text.replace(/\r?\n$/, "").split(/\r?\n/).length;
-}
-
-/** First policy file with this basename that is over `limit`, if any. */
-function overBudget(
-  facts: Facts,
-  file: string,
-  limit: number,
-): { policy: PolicyFile; lines: number } | null {
-  for (const policy of facts.policyFiles) {
-    if (basename(policy.path) !== file) {
-      continue;
-    }
-    const lines = lineCount(policy.text);
-    if (lines > limit) {
-      return { policy, lines };
-    }
-  }
-  return null;
-}
-
-function policyLengthFinding(args: {
-  ruleId: string;
-  file: string;
-  limit: number;
-  facts: Facts;
-  reason: string;
-  suggest: string;
-}): Finding[] {
-  const hit = overBudget(args.facts, args.file, args.limit);
-  if (hit === null) {
-    return [];
-  }
-  return [
-    make(args.ruleId, `rule:${args.ruleId}`, {
-      action: "warn",
-      severity: "info",
-      message: `${args.file} is long (${hit.lines} lines > ${args.limit})`,
-      reason: args.reason,
-      evidence: [
-        { kind: "policy", value: hit.policy.path },
-        { kind: "count", value: `lines=${hit.lines}` },
-        { kind: "threshold", value: String(args.limit) },
-      ],
-      suggest: args.suggest,
-    }),
-  ];
-}
-
-function countFinding(args: {
-  ruleId: string;
-  count: number;
-  limit: number;
-  message: string;
-  countLabel: string;
-  reason: string;
-  suggest: string;
-}): Finding[] {
-  if (args.count <= args.limit) {
-    return [];
-  }
-  return [
-    make(args.ruleId, `rule:${args.ruleId}`, {
-      action: "warn",
-      severity: "info",
-      message: args.message,
-      reason: args.reason,
-      evidence: [
-        { kind: "count", value: `${args.countLabel}=${args.count}` },
-        { kind: "threshold", value: String(args.limit) },
-      ],
-      suggest: args.suggest,
-    }),
-  ];
-}
-
-/**
- * The package manager a policy file tells an agent to use, versus the one the
- * project actually declares. Narrow on purpose: it fires only on the exact
- * string `npm install` in a project whose `packageManager` is bun, because a
- * looser match would flag every doc that mentions npm in passing.
- */
-function packageManagerDrift(facts: Facts): Finding[] {
-  if (facts.packageManager !== "bun") {
-    return [];
-  }
-  const hits = facts.policyFiles.filter((p) => p.text.includes("npm install"));
-  if (hits.length === 0) {
-    return [];
-  }
-  return [
-    make("policy.package-manager-drift", "policy:package-manager", {
-      action: "drift",
-      severity: "info",
-      message: "Policy mentions npm install but packageManager is bun",
-      reason: "Docs drift vs packageManager field / lockfile convention",
-      evidence: [
-        { kind: "packageManager", value: facts.packageManager },
-        ...hits.map((p) => ({ kind: "policy" as const, value: p.path })),
-      ],
-      suggest: "Prefer bun install in AGENTS.md / CLAUDE.md",
-    }),
-  ];
-}
-
-export function runBudgets(facts: Facts, options: BudgetOptions): Finding[] {
-  return [
-    ...policyLengthFinding({
-      ruleId: "budget.agents-md",
-      file: "AGENTS.md",
-      limit: options.agentsMdLines,
-      facts,
-      suggest:
-        "Delete rather than reorganise — keep only what an agent cannot infer from the code. Or set thresholds.agentsMdLines in .agentscanrc.json",
-      reason:
-        "Measured across 2,500+ repositories: past ~150 lines additional content delivers diminishing returns and raises inference cost 20-23% without improving agent performance. Unnecessary requirements actively hurt, by broadening exploration. A lean file is 40-60 lines of commands and boundaries.",
-    }),
-    ...policyLengthFinding({
-      ruleId: "budget.claude-md",
-      file: "CLAUDE.md",
-      limit: options.claudeMdLines,
-      facts,
-      suggest:
-        "Keep only what is true every session; move the rest into a skill, which loads on demand. Or set thresholds.claudeMdLines in .agentscanrc.json",
-      reason:
-        "Frontier models reliably follow roughly 150-200 instructions, and Claude Code's own system prompt already spends about 50 of them. Past that the file is skim-read rather than obeyed. Imports do not help: imported files load at launch too, so splitting organises the text without reducing what competes for attention.",
-    }),
-    ...countFinding({
-      ruleId: "budget.agents",
-      count: facts.agents.length,
-      limit: options.agents,
-      countLabel: "agents",
-      message: `Agent roster large (${facts.agents.length} > ${options.agents} definitions)`,
-      reason:
-        "Guidance converges on three or four specialised agents being the productive ceiling — past that, output drops rather than rises. That is about agents you run, not files on disk, so this counts definitions as a proxy: each one's description is loaded so the main session can choose between them, and a long roster dilutes that choice the same way a long skill list does. See docs/spec/thresholds.md.",
-      suggest:
-        "Archive definitions you do not dispatch, or set thresholds.agents in .agentscanrc.json",
-    }),
-    ...countFinding({
-      ruleId: "budget.mcp",
-      count: facts.mcp.length,
-      limit: options.mcp,
-      countLabel: "mcp",
-      message: `MCP surface above sweet spot (${facts.mcp.length} > ${options.mcp})`,
-      reason:
-        "What actually degrades an agent is the number of tool definitions in context, not the number of servers: benchmarks show large models near-perfect at ~20 tools and failing outright past ~100, and a typical server carries tens of tools. Server count is the only proxy available without connecting to them, so treat this as a hint to go count the tools, not as a measurement.",
-      suggest:
-        "Count the tools your servers actually expose; disable unused servers in mcp.json or set thresholds.mcp in .agentscanrc.json",
-    }),
-    ...packageManagerDrift(facts),
-  ];
-}