@chimix/agentscan 0.1.0

package/src/checks/make.ts

@@ -0,0 +1,37 @@
+import type { Finding } from "../facts/types";
+
+/**
+ * Build a finding.
+ *
+ * `id` is `${ruleId}:${subject}` — a public contract: it is what the report
+ * prints, what `agentscan explain` resolves, and what `ignoreFindings` matches.
+ * Both structural checks and budget checks go through here so there is one
+ * place that decides the shape.
+ */
+export function make(
+  ruleId: string,
+  subject: string,
+  args: {
+    action: Finding["action"];
+    severity: Finding["severity"];
+    message: string;
+    reason: string;
+    evidence: Finding["evidence"];
+    suggest?: string;
+  },
+): Finding {
+  const finding: Finding = {
+    id: `${ruleId}:${subject}`,
+    ruleId,
+    action: args.action,
+    severity: args.severity,
+    subject,
+    message: args.message,
+    reason: args.reason,
+    evidence: args.evidence,
+  };
+  if (args.suggest !== undefined) {
+    finding.suggest = args.suggest;
+  }
+  return finding;
+}

package/src/cli.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { type OutputFormat, runCheck } from "./commands/check";
+import { runExplain } from "./commands/explain";
+import { runInit } from "./commands/init";
+import { runRulesCommand } from "./commands/rules";
+import { copyToClipboard } from "./report/clipboard";
+import { safe } from "./report/safe";
+import type { FailOn } from "./report/exit-code";
+import { VERSION } from "./version";
+
+function printHelp(): void {
+  const text = `agentscan v${VERSION}
+
+Usage:
+  agentscan check [dir] [options]
+  agentscan explain <findingId> [dir]
+  agentscan rules [dir]
+  agentscan init [dir] [--force]
+  agentscan --version
+  agentscan --help
+
+
+check options:
+  --json                 JSON report (alias for --output json)
+  --output <format>      human (default) | json | prompt
+                         prompt: a paste-ready handoff for a fixing agent
+  --copy                 Also copy the report to the system clipboard
+  --quiet                Summary only
+  --verbose              Show KEEP findings
+  --fail-on <level>      never | warning | error (default: never)
+  --fail-under <0-100>   Fail when the score drops below this floor
+  --global               Also scan global skill dirs
+  --config <path>        Config file path
+
+init options:
+  --force                Overwrite existing .agentscanrc.json
+`;
+  process.stdout.write(`${text}\n`);
+}
+
+function isOutput(value: string): value is OutputFormat {
+  return value === "human" || value === "json" || value === "prompt";
+}
+
+function isFailOn(value: string): value is FailOn {
+  return value === "never" || value === "warning" || value === "error";
+}
+
+export async function main(argv: string[]): Promise<number> {
+  let values: {
+    json?: boolean;
+    output?: string;
+    copy?: boolean;
+    quiet?: boolean;
+    verbose?: boolean;
+    "fail-on"?: string;
+    "fail-under"?: string;
+    global?: boolean;
+    config?: string;
+    force?: boolean;
+    help?: boolean;
+    version?: boolean;
+  };
+  let positionals: string[];
+
+  try {
+    const parsed = parseArgs({
+      args: argv,
+      options: {
+        json: { type: "boolean", default: false },
+        output: { type: "string" },
+        copy: { type: "boolean", default: false },
+        quiet: { type: "boolean", default: false },
+        verbose: { type: "boolean", default: false },
+        "fail-on": { type: "string" },
+        "fail-under": { type: "string" },
+        // No default: absent must be `undefined` so `?? config.includeGlobal`
+        // in analyze() can fall through. With `default: false` the flag always
+        // overwrote the config key, making `includeGlobal` unreachable.
+        global: { type: "boolean" },
+        config: { type: "string" },
+        force: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "V", default: false },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${safe(message)}\n`);
+    return 2;
+  }
+
+  if (values.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+
+  if (values.help || positionals.length === 0) {
+    printHelp();
+    return 0;
+  }
+
+  const command = positionals[0];
+  if (command === undefined) {
+    printHelp();
+    return 0;
+  }
+
+  try {
+    switch (command) {
+      case "check": {
+        const dir = positionals[1];
+        const failOnRaw = values["fail-on"];
+        if (failOnRaw !== undefined && !isFailOn(failOnRaw)) {
+          process.stderr.write(
+            `Invalid --fail-on value: ${safe(failOnRaw)} (use never|warning|error)\n`,
+          );
+          return 2;
+        }
+        const failUnderRaw = values["fail-under"];
+        let failUnder: number | undefined;
+        if (failUnderRaw !== undefined) {
+          failUnder = Number(failUnderRaw);
+          if (!Number.isInteger(failUnder) || failUnder < 0 || failUnder > 100) {
+            process.stderr.write(
+              `Invalid --fail-under value: ${safe(failUnderRaw)} (use 0-100)\n`,
+            );
+            return 2;
+          }
+        }
+        const outputRaw = values.output;
+        if (outputRaw !== undefined && !isOutput(outputRaw)) {
+          process.stderr.write(
+            `Invalid --output value: ${safe(outputRaw)} (use human|json|prompt)\n`,
+          );
+          return 2;
+        }
+        const result = await runCheck({
+          dir,
+          json: values.json,
+          ...(outputRaw === undefined ? {} : { output: outputRaw }),
+          quiet: values.quiet,
+          verbose: values.verbose,
+          failOn: failOnRaw,
+          ...(failUnder === undefined ? {} : { failUnder }),
+          global: values.global,
+          configPath: values.config,
+        });
+        process.stdout.write(result.stdout);
+        if (values.copy === true) {
+          // stderr, so `--copy` stays composable with `> file` and `| tool`.
+          // A clipboard miss does not change the exit code: the scan is what
+          // was asked for, and its result is already on stdout.
+          const copied = await copyToClipboard(result.stdout);
+          process.stderr.write(
+            copied.ok
+              ? `Copied to clipboard via ${copied.tool}.\n`
+              : `Could not copy: ${safe(copied.reason)}. Redirect instead: agentscan check > report.md\n`,
+          );
+        }
+        return result.exitCode;
+      }
+      case "explain": {
+        const findingId = positionals[1];
+        if (findingId === undefined || findingId.length === 0) {
+          process.stderr.write("Usage: agentscan explain <findingId> [dir]\n");
+          return 2;
+        }
+        const result = await runExplain(findingId, {
+          dir: positionals[2],
+          global: values.global,
+          configPath: values.config,
+        });
+        if (result.stderr.length > 0) {
+          process.stderr.write(result.stderr);
+        }
+        if (result.stdout.length > 0) {
+          process.stdout.write(result.stdout);
+        }
+        return result.exitCode;
+      }
+      case "rules": {
+        const result = await runRulesCommand({
+          dir: positionals[1],
+          configPath: values.config,
+        });
+        process.stdout.write(result.stdout);
+        return result.exitCode;
+      }
+      case "init": {
+        const result = await runInit(positionals[1], {
+          force: values.force,
+        });
+        if (result.stderr.length > 0) {
+          process.stderr.write(result.stderr);
+        }
+        if (result.stdout.length > 0) {
+          process.stdout.write(result.stdout);
+        }
+        return result.exitCode;
+      }
+      case "help":
+        printHelp();
+        return 0;
+      case "version":
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+      default:
+        process.stderr.write(`Unknown command: ${safe(command)}\n`);
+        printHelp();
+        return 2;
+    }
+  } catch (err) {
+    // A fatal message can quote a path from the scanned tree, and a POSIX
+    // filename may contain a newline or an escape sequence.
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${safe(message)}\n`);
+    return 2;
+  }
+}
+
+if (import.meta.main) {
+  const code = await main(process.argv.slice(2));
+  process.exit(code);
+}

package/src/commands/check.ts

@@ -0,0 +1,64 @@
+import { analyze } from "../analyze";
+import { exitCode, type FailOn } from "../report/exit-code";
+import { renderJson } from "../report/json";
+import { renderPrompt } from "../report/prompt";
+import { renderText } from "../report/text";
+import { VERSION } from "../version";
+
+export type OutputFormat = "human" | "json" | "prompt";
+
+export type CheckOptions = {
+  dir?: string;
+  /** Alias for `output: "json"`, kept for the documented `--json` flag. */
+  json?: boolean;
+  output?: OutputFormat;
+  quiet?: boolean;
+  verbose?: boolean;
+  failOn?: FailOn;
+  /** Fail when the 0-100 score drops below this. */
+  failUnder?: number;
+  global?: boolean;
+  configPath?: string;
+};
+
+export type CheckResult = {
+  exitCode: number;
+  stdout: string;
+};
+
+/**
+ * Run the full check pipeline (discover → facts → rules + checks → report).
+ * Returns exit code + stdout for testability; CLI prints and process.exit.
+ */
+export async function runCheck(options: CheckOptions): Promise<CheckResult> {
+  const { root, resolvedFrom, config, facts, findings } = analyze({
+    dir: options.dir,
+    global: options.global,
+    configPath: options.configPath,
+    failOn: options.failOn,
+  });
+
+  const format: OutputFormat =
+    options.output ?? (options.json === true ? "json" : "human");
+
+  let stdout: string;
+  if (format === "json") {
+    stdout = renderJson({ version: VERSION, root, facts, findings, resolvedFrom });
+  } else if (format === "prompt") {
+    stdout = renderPrompt({ version: VERSION, facts, findings });
+  } else {
+    stdout = renderText({
+      version: VERSION,
+      facts,
+      findings,
+      resolvedFrom,
+      verbose: options.verbose ?? false,
+      quiet: options.quiet ?? false,
+    });
+  }
+
+  return {
+    exitCode: exitCode(findings, config.failOn, options.failUnder),
+    stdout,
+  };
+}

package/src/commands/explain.ts

@@ -0,0 +1,64 @@
+import { analyze } from "../analyze";
+import type { Finding } from "../facts/types";
+import { safe } from "../report/safe";
+
+export type ExplainOptions = {
+  dir?: string;
+  global?: boolean;
+  configPath?: string;
+};
+
+export type ExplainResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+/**
+ * Re-run the check pipeline and print details for a finding by stable id.
+ * Exit 1 if the finding is not found.
+ */
+export async function runExplain(
+  findingId: string,
+  options: ExplainOptions = {},
+): Promise<ExplainResult> {
+  const { findings } = analyze(options);
+  const finding = findings.find((f) => f.id === findingId);
+
+  if (finding === undefined) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      // The argument is echoed back, so it is untrusted like anything else.
+      stderr: `Finding not found: ${safe(findingId)}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: formatExplain(finding),
+    stderr: "",
+  };
+}
+
+function formatExplain(f: Finding): string {
+  const lines: string[] = [];
+  lines.push(`id: ${safe(f.id)}`);
+  lines.push(`action: ${f.action}`);
+  lines.push(`severity: ${f.severity}`);
+  lines.push(`subject: ${safe(f.subject)}`);
+  lines.push(`rule: ${safe(f.ruleId)}`);
+  lines.push(`message: ${safe(f.message)}`);
+  lines.push(`reason: ${safe(f.reason)}`);
+  if (f.evidence.length > 0) {
+    const ev = f.evidence
+      .map((e) => `${safe(e.kind)} ${safe(e.value)}`)
+      .join(" · ");
+    lines.push(`evidence: ${ev}`);
+  }
+  if (f.suggest !== undefined && f.suggest.length > 0) {
+    lines.push(`suggest: ${safe(f.suggest)}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}

package/src/commands/init.ts

@@ -0,0 +1,42 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { defaultConfig } from "../config/schema";
+
+export type InitOptions = {
+  force?: boolean;
+};
+
+export type InitResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+/**
+ * Write `.agentscanrc.json` with defaultConfig.
+ * Refuses to overwrite an existing file unless `force` is true.
+ */
+export async function runInit(
+  dir?: string,
+  options: InitOptions = {},
+): Promise<InitResult> {
+  const root = resolve(dir ?? process.cwd());
+  const path = join(root, ".agentscanrc.json");
+
+  if (existsSync(path) && !options.force) {
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: `Refusing to overwrite existing ${path} (use --force)\n`,
+    };
+  }
+
+  const body = `${JSON.stringify(defaultConfig, null, 2)}\n`;
+  writeFileSync(path, body, "utf8");
+
+  return {
+    exitCode: 0,
+    stdout: `Wrote ${path}\n`,
+    stderr: "",
+  };
+}

package/src/commands/rules.ts

@@ -0,0 +1,36 @@
+import { STRUCTURAL_CHECKS } from "../checks/index";
+import { loadConfig } from "../config/load";
+import { resolveRoot } from "../discover/index";
+
+export type RulesCommandOptions = {
+  dir?: string;
+  configPath?: string;
+};
+
+export type RulesCommandResult = {
+  exitCode: number;
+  stdout: string;
+};
+
+/**
+ * Print every id that can produce a finding, as `id  description`, one per line.
+ *
+ * The ids are the ones `ignoreRules` takes, and each finding's id starts with
+ * one of them, so this is also the index for `ignoreFindings`.
+ */
+export async function runRulesCommand(
+  options: RulesCommandOptions = {},
+): Promise<RulesCommandResult> {
+  const root = resolveRoot(options.dir ?? process.cwd());
+  const config = loadConfig(root, options.configPath);
+
+  const ignored = new Set(config.ignoreRules);
+  const lines = STRUCTURAL_CHECKS.filter((c) => !ignored.has(c.id)).map(
+    (c) => `${c.id}  ${c.description}`,
+  );
+
+  return {
+    exitCode: 0,
+    stdout: lines.length > 0 ? `${lines.join("\n")}\n` : "",
+  };
+}

package/src/config/load.ts

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { configSchema, type AgentscanConfig } from "./schema";
+
+/**
+ * Load agentscan config from `.agentscanrc.json` under `root`, or from `configPath`.
+ * Missing file → defaults via schema. Invalid JSON throws Error with path (exit 2).
+ */
+export function loadConfig(root: string, configPath?: string): AgentscanConfig {
+  const path = configPath ?? join(root, ".agentscanrc.json");
+
+  if (!existsSync(path)) {
+    return configSchema.parse({});
+  }
+
+  let raw: unknown;
+  try {
+    const text = readFileSync(path, "utf8");
+    raw = JSON.parse(text) as unknown;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Invalid config JSON at ${path}: ${message}`);
+  }
+
+  return configSchema.parse(raw);
+}

package/src/config/schema.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+export const defaultThresholds = {
+  /** Bytes of skill name+description loaded at startup. The constraint is a
+   *  character budget (~1-2% of the context window) shared across all skills;
+   *  past it, descriptions are truncated and matching keywords are lost. */
+  skillDescriptionBytes: 16_000,
+  skills: 30,
+  mcp: 5,
+  agentsMdLines: 150,
+  claudeMdLines: 200,
+  agents: 8,
+};
+
+export const defaultConfig = {
+  skillPaths: [".agents/skills", ".claude/skills", "skills", ".cursor/skills"],
+  mcpPaths: [".mcp.json", ".claude/mcp.json", "mcp.json"],
+  policyFiles: ["AGENTS.md", "CLAUDE.md"],
+  ignoreSkills: [] as string[],
+  ignoreRules: [] as string[],
+  ignoreFindings: [] as string[],
+  failOn: "never" as const,
+  includeGlobal: false,
+  requireLock: false,
+  thresholds: defaultThresholds,
+};
+
+const thresholdsSchema = z.object({
+  skillDescriptionBytes: z
+    .number()
+    .int()
+    .positive()
+    .default(defaultThresholds.skillDescriptionBytes),
+  skills: z.number().int().positive().default(defaultThresholds.skills),
+  mcp: z.number().int().positive().default(defaultThresholds.mcp),
+  agentsMdLines: z
+    .number()
+    .int()
+    .positive()
+    .default(defaultThresholds.agentsMdLines),
+  claudeMdLines: z
+    .number()
+    .int()
+    .positive()
+    .default(defaultThresholds.claudeMdLines),
+  agents: z.number().int().positive().default(defaultThresholds.agents),
+});
+
+export const configSchema = z.object({
+  skillPaths: z.array(z.string()).default(defaultConfig.skillPaths),
+  mcpPaths: z.array(z.string()).default(defaultConfig.mcpPaths),
+  policyFiles: z.array(z.string()).default(defaultConfig.policyFiles),
+  ignoreSkills: z.array(z.string()).default([]),
+  ignoreRules: z.array(z.string()).default([]),
+  /** Exact finding ids, the same strings `agentscan explain` takes. */
+  ignoreFindings: z.array(z.string()).default([]),
+  failOn: z.enum(["never", "warning", "error"]).default("never"),
+  includeGlobal: z.boolean().default(false),
+  requireLock: z.boolean().default(false),
+  thresholds: thresholdsSchema.default(defaultThresholds),
+});
+
+export type AgentscanConfig = z.infer<typeof configSchema>;