@chimix/agentscan 0.1.0

package/src/facts/extract.ts

@@ -0,0 +1,273 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentscanConfig } from "../config/schema";
+import { discoverAgentSurface } from "../discover/index";
+import type { ConfigErrorFact, Facts } from "./types";
+
+type PackageJson = {
+  packageManager?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+};
+
+/**
+ * A package.json that will not parse is a config issue like any other — every
+ * dependency-based rule would otherwise silently evaluate against an empty
+ * project and report nothing wrong.
+ */
+function readPackageJson(
+  root: string,
+  errors: ConfigErrorFact[],
+): PackageJson {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) {
+    return {};
+  }
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    errors.push({
+      path,
+      kind: "unreadable",
+      detail: err instanceof Error ? err.message : String(err),
+    });
+    return {};
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text) as unknown;
+  } catch (err) {
+    errors.push({
+      path,
+      kind: "invalid-json",
+      detail: err instanceof Error ? err.message : String(err),
+    });
+    return {};
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push({
+      path,
+      kind: "unexpected-shape",
+      detail: "package.json is not a JSON object",
+    });
+    return {};
+  }
+
+  const obj = raw as Record<string, unknown>;
+  const pkg: PackageJson = {};
+  if (typeof obj.packageManager === "string") {
+    pkg.packageManager = obj.packageManager;
+  }
+  for (const field of ["dependencies", "devDependencies", "scripts"] as const) {
+    const raw = obj[field];
+    const kept = stringEntries(raw);
+    if (kept === undefined) {
+      // Present but not an object — `"dependencies": "notanobject"` would
+      // otherwise be reported as a project with zero dependencies.
+      if (raw !== undefined) {
+        errors.push({
+          path,
+          kind: "unexpected-shape",
+          detail: `${field} is not an object`,
+        });
+      }
+      continue;
+    }
+    if (kept.dropped > 0) {
+      // Name the field and the count — never the discarded value, which can be
+      // a token pasted into a script.
+      errors.push({
+        path,
+        kind: "unexpected-shape",
+        detail: `${field}: ${kept.dropped} entr${kept.dropped === 1 ? "y" : "ies"} ignored (value is not a string)`,
+      });
+    }
+    pkg[field] = kept.values;
+  }
+  return pkg;
+}
+
+/**
+ * Keep only string-valued entries. The `as PackageJson` assertion this replaces
+ * promised `Record<string, string>` and delivered whatever the file held, so a
+ * single `null` reached `.includes()` and killed the whole scan.
+ */
+function stringEntries(
+  value: unknown,
+): { values: Record<string, string>; dropped: number } | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const values: Record<string, string> = {};
+  let dropped = 0;
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof entry === "string") {
+      values[key] = entry;
+    } else {
+      dropped += 1;
+    }
+  }
+  return { values, dropped };
+}
+
+function inferPackageManager(
+  root: string,
+  pkg: PackageJson,
+): Facts["packageManager"] {
+  const field = pkg.packageManager;
+  if (typeof field === "string" && field.length > 0) {
+    const prefix = field.split("@")[0]?.toLowerCase() ?? "";
+    if (
+      prefix === "bun" ||
+      prefix === "npm" ||
+      prefix === "pnpm" ||
+      prefix === "yarn"
+    ) {
+      return prefix;
+    }
+  }
+
+  if (existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb"))) {
+    return "bun";
+  }
+  if (existsSync(join(root, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (existsSync(join(root, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (existsSync(join(root, "package-lock.json"))) {
+    return "npm";
+  }
+  return "unknown";
+}
+
+function hasNextConfig(root: string): boolean {
+  try {
+    const entries = readdirSync(root);
+    return entries.some(
+      (name) =>
+        name === "next.config.js" ||
+        name === "next.config.mjs" ||
+        name === "next.config.cjs" ||
+        name === "next.config.ts" ||
+        name === "next.config.mts",
+    );
+  } catch {
+    return false;
+  }
+}
+
+function readNextConfigText(root: string): string | undefined {
+  const candidates = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.mts",
+    "next.config.cjs",
+  ];
+  for (const name of candidates) {
+    const path = join(root, name);
+    if (!existsSync(path)) {
+      continue;
+    }
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+function extractConfigs(
+  root: string,
+  deps: Record<string, string>,
+  devDeps: Record<string, string>,
+  scripts: Record<string, string>,
+): Facts["configs"] {
+  const configs: Facts["configs"] = {};
+
+  if (existsSync(join(root, "components.json"))) {
+    configs.shadcn = true;
+  }
+
+  if (
+    existsSync(join(root, "biome.json")) ||
+    existsSync(join(root, "biome.jsonc"))
+  ) {
+    configs.biome = true;
+  }
+
+  const allDeps = { ...deps, ...devDeps };
+  const hasUltraciteDep = "ultracite" in allDeps;
+  const hasUltraciteScript = Object.values(scripts).some((s) =>
+    s.includes("ultracite"),
+  );
+  if (hasUltraciteDep || hasUltraciteScript) {
+    configs.ultracite = true;
+  }
+
+  if ("next" in allDeps) {
+    const next: NonNullable<Facts["configs"]["next"]> = {};
+    if (hasNextConfig(root)) {
+      next.appRouter = true;
+      const text = readNextConfigText(root);
+      if (text !== undefined) {
+        // best-effort: cacheComponents: true (or experimental.cacheComponents)
+        if (
+          /\bcacheComponents\s*:\s*true\b/.test(text) ||
+          /\bcacheComponents\s*:\s*!0\b/.test(text)
+        ) {
+          next.cacheComponents = true;
+        } else if (
+          /\bcacheComponents\s*:\s*false\b/.test(text) ||
+          /\bcacheComponents\s*:\s*!1\b/.test(text)
+        ) {
+          next.cacheComponents = false;
+        }
+      }
+    }
+    configs.next = next;
+  }
+
+  return configs;
+}
+
+/**
+ * Build immutable Facts snapshot from package.json + discovered agent surface.
+ * No network. No disk writes.
+ */
+export function extractFacts(
+  root: string,
+  config: AgentscanConfig,
+  opts?: { includeGlobal?: boolean },
+): Facts {
+  const includeGlobal = opts?.includeGlobal ?? config.includeGlobal;
+  const packageErrors: ConfigErrorFact[] = [];
+  const pkg = readPackageJson(root, packageErrors);
+  const dependencies = { ...(pkg.dependencies ?? {}) };
+  const devDependencies = { ...(pkg.devDependencies ?? {}) };
+  const scripts = { ...(pkg.scripts ?? {}) };
+
+  const surface = discoverAgentSurface(root, config, { includeGlobal });
+
+  return {
+    root,
+    packageManager: inferPackageManager(root, pkg),
+    dependencies,
+    devDependencies,
+    scripts,
+    configs: extractConfigs(root, dependencies, devDependencies, scripts),
+    skills: surface.skills,
+    agents: surface.agents,
+    hooks: surface.hooks,
+    mcp: surface.mcp,
+    policyFiles: surface.policyFiles,
+    lockedSkills: surface.lockedSkills,
+    hasSkillsLock: surface.hasSkillsLock,
+    configErrors: [...packageErrors, ...surface.configErrors],
+  };
+}

package/src/facts/semver.ts

@@ -0,0 +1,41 @@
+/** Strip range prefixes and take the first major.minor.patch token. */
+export function coerceVersion(range: string): string | null {
+  const cleaned = range.trim().replace(/^(?:>=|<=|>|<|=|\^|~)/, "");
+  const match = cleaned.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}
+
+function parseParts(version: string): number[] {
+  return version.split(".").map((part) => {
+    const n = Number.parseInt(part, 10);
+    return Number.isFinite(n) ? n : 0;
+  });
+}
+
+function compare(a: string, b: string): number {
+  const left = parseParts(a);
+  const right = parseParts(b);
+  const len = Math.max(left.length, right.length);
+  for (let i = 0; i < len; i++) {
+    const l = left[i] ?? 0;
+    const r = right[i] ?? 0;
+    if (l > r) {
+      return 1;
+    }
+    if (l < r) {
+      return -1;
+    }
+  }
+  return 0;
+}
+
+export function gte(version: string, min: string): boolean {
+  return compare(version, min) >= 0;
+}
+
+export function lt(version: string, max: string): boolean {
+  return compare(version, max) < 0;
+}

package/src/facts/types.ts

@@ -0,0 +1,113 @@
+export type Action = "keep" | "delete" | "add" | "refresh" | "warn" | "drift";
+export type Severity = "error" | "warning" | "info";
+
+export type SkillFact = {
+  id: string;
+  path: string;
+  description?: string;
+  source: "project" | "global";
+  /** SKILL.md present in the skill dir. */
+  hasSkillMd: boolean;
+  /** Frontmatter present and parseable as a `---` block. */
+  hasFrontmatter: boolean;
+  /** SKILL.md exists but could not be read; frontmatter facts are unknown. */
+  unreadable?: boolean;
+  /** A `---` block exists but does not parse; its fields are unknown. */
+  unparseableFrontmatter?: boolean;
+  /** Bundled files the body points at that resolve nowhere. */
+  brokenReferences?: string[];
+  /** `name:` from frontmatter, when present. */
+  frontmatterName?: string;
+};
+
+export type McpFact = {
+  name: string;
+  path: string;
+  hasCommand: boolean;
+  hasUrl: boolean;
+  /** Declared transport, if any: http | sse | ws | stdio. */
+  transport?: string;
+  /** env values that look like literal secrets rather than ${VAR} refs. */
+  literalEnvKeys: string[];
+  /** Raw entry text, for secret pattern matching. */
+  raw: string;
+};
+
+export type HookFact = {
+  name: string;
+  path: string;
+  event?: string;
+  command?: string;
+  /** Script path parsed out of `command`, resolved against the project root. */
+  scriptPath?: string;
+  /** false only when scriptPath was extracted and does not exist on disk. */
+  scriptExists?: boolean;
+};
+
+export type AgentFact = {
+  name: string;
+  path: string;
+  /** Frontmatter present and parseable as a `---` block. */
+  hasFrontmatter: boolean;
+  /** File exists but could not be read; its fields are unknown, not absent. */
+  unreadable?: boolean;
+  /** A `---` block exists but does not parse; its fields are unknown. */
+  unparseableFrontmatter?: boolean;
+  /**
+   * `name:` from frontmatter — a display name. Deliberately NOT compared to the
+   * filename: 16 of 34 real agent files differ intentionally and nothing keys
+   * on the filename. See plans/003 and docs/spec/skills.md.
+   */
+  frontmatterName?: string;
+  description?: string;
+};
+
+/** A config file agentscan could not read — itself a finding, never swallowed. */
+export type ConfigErrorFact = {
+  path: string;
+  kind: "invalid-json" | "unreadable" | "unexpected-shape";
+  detail: string;
+};
+
+/** One entry of skills-lock.json. */
+export type LockedSkillFact = {
+  id: string;
+  source?: string;
+  skillPath?: string;
+  computedHash?: string;
+};
+
+export type Facts = {
+  root: string;
+  packageManager: "bun" | "npm" | "pnpm" | "yarn" | "unknown";
+  dependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+  scripts: Record<string, string>;
+  configs: {
+    next?: { cacheComponents?: boolean; appRouter?: boolean };
+    shadcn?: boolean;
+    ultracite?: boolean;
+    biome?: boolean;
+  };
+  skills: SkillFact[];
+  agents: AgentFact[];
+  hooks: HookFact[];
+  mcp: McpFact[];
+  policyFiles: { path: string; text: string }[];
+  /** skills-lock.json entries; empty when the project has no lockfile. */
+  lockedSkills: LockedSkillFact[];
+  hasSkillsLock: boolean;
+  configErrors: ConfigErrorFact[];
+};
+
+export type Finding = {
+  id: string; // stable: `${ruleId}:${subject}`
+  ruleId: string;
+  action: Action;
+  severity: Severity;
+  subject: string; // e.g. skill:next-cache-components
+  message: string;
+  reason: string;
+  evidence: { kind: string; value: string }[];
+  suggest?: string;
+};

package/src/report/clipboard.ts

@@ -0,0 +1,90 @@
+/**
+ * Copying the report to the system clipboard.
+ *
+ * This is the only part of agentscan that starts a subprocess, and it runs only
+ * when `--copy` is passed. It writes to the clipboard and nowhere else — never
+ * to disk, and never into the project being scanned. Saving and piping do not
+ * need code: `agentscan check --output prompt > handoff.md` and
+ * `agentscan check --json | jq` already work. The clipboard is the one thing a
+ * shell cannot do portably, which is why it is the one thing built here.
+ */
+
+/** Ordered by preference; each entry is argv for a tool that reads stdin. */
+const TOOLS: readonly (readonly string[])[] = [
+  ["wl-copy"],
+  // xclip and xsel write to the PRIMARY selection unless told otherwise, and
+  // PRIMARY is not the clipboard a paste reads from.
+  ["xclip", "-selection", "clipboard"],
+  ["xsel", "--clipboard", "--input"],
+  ["pbcopy"],
+  // WSL: works with no display server at all, so it is the usual survivor here.
+  // Last because it round-trips through Windows and rewrites line endings.
+  ["clip.exe"],
+];
+
+const TIMEOUT_MS = 3000;
+
+export type CopyResult =
+  | { ok: true; tool: string }
+  | { ok: false; reason: string };
+
+/**
+ * Every clipboard tool present on PATH, in preference order.
+ *
+ * All of them, not the best one: being installed does not mean being usable.
+ * On a headless WSL shell `wl-copy` and `xclip` are both installed and both
+ * exit 1 for want of a display while `clip.exe` succeeds, so the caller has to
+ * try them in turn.
+ */
+export function clipboardCandidates(
+  onPath: (name: string) => boolean = (name) => resolve(name) !== null,
+): string[][] {
+  return TOOLS.filter((t) => onPath(t[0] as string)).map((t) => [...t]);
+}
+
+/**
+ * Absolute path to a tool, or null.
+ *
+ * PATH is read from the environment on every call rather than let Bun.which
+ * consult its own copy, so the lookup and the spawn agree on one answer.
+ */
+function resolve(name: string): string | null {
+  return Bun.which(name, { PATH: process.env.PATH ?? "" });
+}
+
+/** Try each installed tool until one exits 0. */
+export async function copyToClipboard(text: string): Promise<CopyResult> {
+  const candidates = clipboardCandidates();
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      reason: `no clipboard tool found (looked for ${TOOLS.map((t) => t[0]).join(", ")})`,
+    };
+  }
+
+  const failures: string[] = [];
+  for (const argv of candidates) {
+    const tool = argv[0] as string;
+    const bin = resolve(tool);
+    if (bin === null) {
+      continue;
+    }
+    try {
+      const proc = Bun.spawn([bin, ...argv.slice(1)], {
+        stdin: new TextEncoder().encode(text),
+        stdout: "ignore",
+        stderr: "ignore",
+        // A clipboard tool that hangs must not hang the scan. wl-copy in
+        // particular stays resident to serve the selection it just took.
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+      if ((await proc.exited) === 0) {
+        return { ok: true, tool };
+      }
+      failures.push(tool);
+    } catch {
+      failures.push(tool);
+    }
+  }
+  return { ok: false, reason: `clipboard tool failed: ${failures.join(", ")}` };
+}

package/src/report/exit-code.ts

@@ -0,0 +1,36 @@
+import type { Finding } from "../facts/types";
+import { score } from "./score";
+
+export type FailOn = "never" | "warning" | "error";
+
+/**
+ * - never → always 0
+ * - warning → 1 if any non-keep finding with severity warning|error
+ * - error → 1 if any finding with severity error
+ */
+export function exitCode(
+  findings: Finding[],
+  failOn: FailOn,
+  failUnder?: number,
+): 0 | 1 {
+  // A score floor and a severity gate answer different questions, so either
+  // can fail the run on its own.
+  if (failUnder !== undefined && score(findings) < failUnder) {
+    return 1;
+  }
+  if (failOn === "never") {
+    return 0;
+  }
+
+  if (failOn === "error") {
+    return findings.some((f) => f.severity === "error") ? 1 : 0;
+  }
+
+  // warning threshold: warning or error, excluding keep
+  const hits = findings.some(
+    (f) =>
+      f.action !== "keep" &&
+      (f.severity === "warning" || f.severity === "error"),
+  );
+  return hits ? 1 : 0;
+}

package/src/report/json.ts

@@ -0,0 +1,36 @@
+import type { Facts, Finding } from "../facts/types";
+import { score } from "./score";
+import { sortFindings } from "./sort";
+
+export function renderJson(args: {
+  version: string;
+  root: string;
+  facts: Facts;
+  findings: Finding[];
+  resolvedFrom?: string;
+}): string {
+  const { version, root, facts, findings } = args;
+  const depCount =
+    Object.keys(facts.dependencies).length +
+    Object.keys(facts.devDependencies).length;
+
+  const payload = {
+    version,
+    root,
+    ...(args.resolvedFrom === undefined
+      ? {}
+      : { resolvedFrom: args.resolvedFrom }),
+    factsSummary: {
+      packageManager: facts.packageManager,
+      depCount,
+      skillCount: facts.skills.length,
+      globalSkillCount: facts.skills.filter((s) => s.source === "global")
+        .length,
+    },
+    // max(0, 100 - 10*errors - 3*warnings); see src/report/score.ts
+    score: score(findings),
+    findings: sortFindings(findings),
+  };
+
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}

package/src/report/prompt.ts

@@ -0,0 +1,102 @@
+import { basename } from "node:path";
+import type { Facts, Finding, Severity } from "../facts/types";
+import { safe } from "./safe";
+import { score } from "./score";
+import { sortFindings } from "./sort";
+
+/**
+ * A paste-ready handoff for an agent that will fix the findings.
+ *
+ * Different from the text report, which is for a person deciding what to care
+ * about, and from `--json`, which is for a program. This one is for a model
+ * that is about to edit files: it carries the reason (so a judgement call lands
+ * the right way), the suggestion, and the finding id (so the honest answer to a
+ * false positive is suppression rather than a guess).
+ *
+ * Info-severity findings are left out on purpose. They are budgets and hygiene
+ * notes — things for a maintainer to weigh, not work items. Handing them to an
+ * executor invites churn on advice that was never a defect.
+ */
+export function renderPrompt(args: {
+  version: string;
+  facts: Facts;
+  findings: Finding[];
+}): string {
+  const { version, facts } = args;
+  const actionable = sortFindings(args.findings).filter(
+    (f) => f.severity !== "info",
+  );
+  const project = basename(facts.root) || facts.root;
+
+  if (actionable.length === 0) {
+    return [
+      `# agentscan v${version} — ${safe(project)}`,
+      "",
+      "No findings, score 100/100. The agent configuration in this project is intact;",
+      "there is nothing to fix.",
+      "",
+    ].join("\n");
+  }
+
+  const lines: string[] = [
+    `# Fix the agent configuration in ${safe(project)}`,
+    "",
+    `\`agentscan\` v${version} scores this project ${score(args.findings)}/100 and found`,
+    `${actionable.length} ${actionable.length === 1 ? "issue" : "issues"} in its agent configuration —`,
+    "hooks, MCP servers, skills, agent definitions. Each one below is a config file",
+    "saying something that is not true of the filesystem.",
+    "",
+    "## Work items",
+    "",
+  ];
+
+  for (const group of ["error", "warning"] as const) {
+    const items = actionable.filter((f) => f.severity === group);
+    if (items.length === 0) {
+      continue;
+    }
+    lines.push(`### ${headingFor(group)}`, "");
+    for (const f of items) {
+      lines.push(`- **${safe(f.message)}**`);
+      lines.push(`  - Why it matters: ${safe(f.reason)}`);
+      if (f.suggest !== undefined && f.suggest.length > 0) {
+        lines.push(`  - Suggested fix: ${safe(f.suggest)}`);
+      }
+      for (const e of f.evidence) {
+        lines.push(`  - ${safe(e.kind)}: \`${safe(e.value)}\``);
+      }
+      lines.push(`  - Finding id: \`${safe(f.id)}\``);
+      lines.push("");
+    }
+  }
+
+  lines.push(
+    "## Rules for this work",
+    "",
+    "- Fix the configuration, not the report. Do not silence a finding by deleting the",
+    "  file it names unless that is genuinely the right fix — several of these name a",
+    "  guard hook or a pinned skill that someone wanted.",
+    "- If a finding is wrong for this project, do not work around it: add its id to",
+    "  `ignoreFindings` in `.agentscanrc.json` and say why in the commit.",
+    "- Change nothing this list does not mention.",
+    "",
+    "## Verify",
+    "",
+    "```bash",
+    "agentscan check --fail-on error",
+    "```",
+    "",
+    "Exit 0 means every error-severity item above is resolved. Re-read the report",
+    "rather than trusting the exit code alone — a fix that removes the file instead",
+    "of repairing it also exits 0.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+function headingFor(severity: Severity): string {
+  return severity === "error"
+    ? "Broken — something configured here does not work"
+    : "Wrong — the config and the filesystem disagree";
+}