@konvert7/klint 0.35.1 → 0.36.0

package/README.md

@@ -178,16 +178,19 @@ Every lint run is recorded in `.klint/stats.json` next to your config. `klint st
 ```
 klint stats (.klint/stats.json)
 
-  runs              42  (hook 30, direct 12)
-  errors prevented  17  (caught by hook 11, direct 6)
+  runs                 42  (hook 30, direct 12)
+  violations reported  61  (hook 48, direct 13)
+  errors prevented     17  (caught by hook 11, direct 6)
 
-  prevented by rule
-    no-floating-promise  9
-    arch/imports         5
-    no-string-match      3
+  by rule                reported  prevented
+    no-floating-promise        29          9
+    arch/imports               20          5
+    no-string-match            12          3
 ```
 
-An error counts as prevented once: when a run reports it and a later run no longer does. Errors match by rule, file, and message, so moving code to another line doesn't count as a fix, and running klint again on an unfixed error doesn't count twice. Warnings aren't tracked. A prevented error is credited to the run that first caught it: pass `--hook` from agent hooks, and every other run (an agent's own shell, a person, CI) counts as direct.
+Violations reported counts every error and warning each run shows, so an unfixed error reported by three runs counts three times. That is the measure of how often klint stepped in. klint's own `klint/*` advisories, such as a stale skill, aren't counted.
+
+Errors prevented is stricter: an error counts once, when a run reports it and a later run no longer does. Errors match by rule, file, and message, so moving code to another line doesn't count as a fix, and running klint again on an unfixed error doesn't count twice. Warnings aren't tracked as prevented. A prevented error is credited to the run that first caught it: pass `--hook` from agent hooks, and every other run (an agent's own shell, a person, CI) counts as direct.
 
 `.klint/` contains a `.gitignore` with `*`, so git ignores the whole folder and nothing needs adding to your own `.gitignore`. Set `KLINT_NO_STATS=1` to stop recording. Stats are best effort: a read-only checkout never fails a lint run.
 

package/cli/command.ts

@@ -0,0 +1,189 @@
+interface OptionSpec {
+  description: string;
+  value?: string;
+  short?: string;
+  aliases?: string[];
+}
+
+type OptionSpecs = Record<string, OptionSpec>;
+export type OptionValues = Record<string, string | true | undefined>;
+
+interface Leaf {
+  kind: "leaf";
+  summary: string;
+  options: OptionSpecs;
+  details?: () => string[];
+  run(values: OptionValues): unknown;
+}
+
+export interface Group {
+  kind: "group";
+  summary: string;
+  commands: Record<string, Leaf>;
+  aliases?: Record<string, string>;
+  defaultCommand?: Leaf;
+  details?: () => string[];
+}
+
+export type Command = Leaf | Group;
+
+const HELP_FLAGS = new Set(["-h", "--help"]);
+const HELP_WORD = "help";
+const HELP_OPTION: OptionSpec = { short: "h", description: "Show this help" };
+
+interface ParsedOptions {
+  values: OptionValues;
+  positionals: string[];
+  help: boolean;
+  error?: string;
+  rest: string[];
+}
+
+function findOption(
+  options: OptionSpecs,
+  token: string
+): [string, OptionSpec] | undefined {
+  return Object.entries(options).find(
+    ([name, spec]) =>
+      token === `--${name}` ||
+      (spec.short !== undefined && token === `-${spec.short}`) ||
+      (spec.aliases?.includes(token) ?? false)
+  );
+}
+
+function parseOptions(
+  args: string[],
+  options: OptionSpecs,
+  stopAtPositional: boolean
+): ParsedOptions {
+  const parsed: ParsedOptions = { values: {}, positionals: [], help: false, rest: [] };
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    const match = findOption(options, token);
+    if (HELP_FLAGS.has(token)) {
+      parsed.help = true;
+    } else if (match?.[1].value !== undefined) {
+      const [name, spec] = match;
+      const value = args[i + 1];
+      if (value === undefined) parsed.error ??= `option '--${name}' needs ${spec.value}`;
+      else parsed.values[name] = value;
+      i++;
+    } else if (match) {
+      parsed.values[match[0]] = true;
+    } else if (token.startsWith("-")) {
+      parsed.error ??= `unknown option '${token}'`;
+    } else if (stopAtPositional) {
+      parsed.positionals.push(token);
+      parsed.rest = args.slice(i + 1);
+      return parsed;
+    } else {
+      parsed.positionals.push(token);
+    }
+  }
+  return parsed;
+}
+
+export async function runCommand(
+  command: Command,
+  args: string[],
+  path: string[]
+): Promise<number> {
+  return command.kind === "group"
+    ? runGroup(command, args, path)
+    : runLeaf(command, args, helpText(command, path));
+}
+
+async function runGroup(group: Group, args: string[], path: string[]): Promise<number> {
+  const help = helpText(group, path);
+  const parsed = parseOptions(args, group.defaultCommand?.options ?? {}, true);
+  const [name] = parsed.positionals;
+  if (parsed.help || name === HELP_WORD || group.aliases?.[name] === HELP_WORD) {
+    return showHelp(help);
+  }
+  if (name !== undefined) {
+    const sub = group.commands[group.aliases?.[name] ?? name];
+    if (!sub) return usageFailure(`unknown command '${name}'`, help);
+    if (parsed.error) return usageFailure(parsed.error, help);
+    return runCommand(sub, parsed.rest, [...path, name]);
+  }
+  if (!group.defaultCommand) return showHelp(help);
+  return runLeaf(group.defaultCommand, args, help);
+}
+
+async function runLeaf(leaf: Leaf, args: string[], help: string): Promise<number> {
+  const parsed = parseOptions(args, leaf.options, false);
+  if (parsed.help || parsed.positionals.includes(HELP_WORD)) return showHelp(help);
+  if (parsed.error) return usageFailure(parsed.error, help);
+  const [extra] = parsed.positionals;
+  if (extra !== undefined) return usageFailure(`unexpected argument '${extra}'`, help);
+  const result = await leaf.run(parsed.values);
+  return typeof result === "number" ? result : 0;
+}
+
+function showHelp(help: string): number {
+  process.stdout.write(`${help}\n`);
+  return 0;
+}
+
+function usageFailure(message: string, help: string): number {
+  process.stderr.write(`error: ${message}\n\n${help}\n`);
+  return 1;
+}
+
+function helpText(command: Command, path: string[]): string {
+  return command.kind === "group" ? groupHelp(command, path) : leafHelp(command, path);
+}
+
+function optionLabel(name: string, spec: OptionSpec): string {
+  const short = spec.short ? `-${spec.short}, ` : "";
+  const value = spec.value ? ` ${spec.value}` : "";
+  return `${short}--${name}${value}`;
+}
+
+function optionRows(options: OptionSpecs): string[] {
+  return table(
+    Object.entries({ ...options, help: HELP_OPTION }).map(([name, spec]) => [
+      optionLabel(name, spec),
+      spec.description,
+    ])
+  );
+}
+
+function leafHelp(leaf: Leaf, path: string[]): string {
+  return [
+    `Usage: ${path.join(" ")} [options]`,
+    "",
+    `  ${leaf.summary}`,
+    "",
+    "Options:",
+    ...optionRows(leaf.options),
+    ...detailLines(leaf.details),
+  ].join("\n");
+}
+
+function groupHelp(group: Group, path: string[]): string {
+  const fallback = group.defaultCommand;
+  const synopsis = fallback ? `[<command>] [options]` : "<command>";
+  return [
+    `Usage: ${path.join(" ")} ${synopsis}`,
+    "",
+    `  ${group.summary}`,
+    "",
+    "Commands:",
+    ...table(Object.entries(group.commands).map(([name, sub]) => [name, sub.summary])),
+    ...(fallback ? ["", "Options:", ...optionRows(fallback.options)] : []),
+    "",
+    ...(fallback ? [`With no command, ${fallback.summary.toLowerCase()}.`] : []),
+    `Run '${path.join(" ")} <command> --help' for its options.`,
+    ...detailLines(group.details),
+  ].join("\n");
+}
+
+function detailLines(details: (() => string[]) | undefined): string[] {
+  return details ? ["", ...details()] : [];
+}
+
+function table(rows: string[][]): string[] {
+  const width = Math.max(...rows.map(([label]) => label.length));
+  return rows.map(([label, text]) => `  ${label.padEnd(width)}  ${text}`);
+}

package/cli/commands.ts

@@ -0,0 +1,90 @@
+import { AGENT_SKILL_DIRS } from "../core/skill";
+import type { Group, OptionValues } from "./command";
+import { builtInRuleLines } from "./help";
+
+interface CommandHandlers {
+  lint(values: OptionValues): unknown;
+  stats(values: OptionValues): unknown;
+  installSkill(values: OptionValues): unknown;
+}
+
+export function klintCommand(handlers: CommandHandlers): Group {
+  return {
+    kind: "group",
+    summary:
+      "Architecture-as-Code linter: layer boundaries, import rules and forbidden patterns",
+    aliases: { h: "help" },
+    defaultCommand: {
+      kind: "leaf",
+      summary: "Lints the project",
+      options: {
+        config: {
+          value: "<dir>",
+          description:
+            "Directory containing klint.yaml or klint.config.json (default: cwd)",
+        },
+        rules: {
+          value: "<file>",
+          description:
+            "Custom rules file (default: <configDir>/klint.rules.ts if present)",
+        },
+        engine: {
+          value: "<name>",
+          description:
+            "Engine to use: ts (default), rust, compare, or auto (experimental)",
+        },
+        fix: { description: "Apply auto-fixes for fixable violations in place" },
+        json: { description: "Emit structured JSON to stdout (for agent and CI use)" },
+        debug: {
+          aliases: ["-debug"],
+          description: "Print file resolution and rule progress to stderr",
+        },
+        hook: { description: "Count this run as an agent hook run in klint stats" },
+        version: { short: "V", description: "Print the installed klint version" },
+      },
+      run: handlers.lint,
+    },
+    commands: {
+      stats: {
+        kind: "leaf",
+        summary:
+          "Print runs, violations reported and errors prevented, in total and per rule",
+        options: {
+          config: {
+            value: "<dir>",
+            description: "Directory holding .klint/stats.json (default: cwd)",
+          },
+        },
+        details: () => ["Set KLINT_NO_STATS=1 to stop recording."],
+        run: handlers.stats,
+      },
+      "install-skill": {
+        kind: "leaf",
+        summary: "Install the rule-authoring skill into agent config directories",
+        options: {
+          agents: {
+            value: "<list>",
+            description: `Comma-separated: ${Object.keys(AGENT_SKILL_DIRS).join(",")} (default: all)`,
+          },
+          symlink: {
+            aliases: ["--shared"],
+            description:
+              "Keep one skill in .agents/skills and symlink the others to it (default)",
+          },
+          copy: { description: "Give every agent directory its own copy" },
+          force: { description: "Replace a skill directory klint did not install" },
+        },
+        details: () => [
+          "Asks which agents and how to store the skill when run on a terminal without",
+          "--agents, --symlink or --copy.",
+          "",
+          "Installed skills record the version and hash they came from. klint warns with",
+          "klint/skill-stale once the shipped skill moves on, and with",
+          "klint/skill-legacy-link for old symlinks that point into node_modules.",
+        ],
+        run: handlers.installSkill,
+      },
+    },
+    details: builtInRuleLines,
+  };
+}

package/cli/help.ts

@@ -1,52 +1,21 @@
 import { BUILT_IN_PLUGINS } from "../plugins/index";
 import { BUILT_IN_RULES } from "../rules/index";
 
-export function printHelp(): void {
+export function builtInRuleLines(): string[] {
   const pluginRules = new Set(
     Object.values(BUILT_IN_PLUGINS).flatMap((p) => Object.keys(p.rules))
   );
   const standaloneRules = Object.keys(BUILT_IN_RULES).filter((r) => !pluginRules.has(r));
   const pluginEntries = Object.entries(BUILT_IN_PLUGINS);
 
-  process.stdout.write(
-    [
-      "klint — agent harness for TypeScript architecture rules",
-      "",
-      "Usage: klint [--config <dir>] [--rules <file>] [--engine ts|rust|compare|auto] [--fix] [--json] [--hook]",
-      "       klint stats [--config <dir>]",
-      "       klint install-skill [--agents <list>] [--symlink | --copy] [--force]",
-      "",
-      "  --config <dir>   directory containing klint.yaml or klint.config.json (default: cwd)",
-      "  --rules  <file>  custom rules file (default: <configDir>/klint.rules.ts if present)",
-      "  --engine <name>  engine to use: ts (default), rust, compare, or auto (experimental)",
-      "  --fix            apply auto-fixes for fixable violations in-place",
-      "  --json           emit structured JSON to stdout (for agent/CI consumption)",
-      "  --debug          print file resolution and rule progress to stderr",
-      "  --hook           count this run as an agent hook run in klint stats",
-      "",
-      "  stats            print runs and errors prevented, in total and per rule, from",
-      "                   .klint/stats.json (set KLINT_NO_STATS=1 to stop recording)",
-      "",
-      "  install-skill    install the rule-authoring skill into agent config directories",
-      "                   --agents <list>  comma-separated: claude,opencode,cursor,codex,copilot (default: all)",
-      "                   --symlink        keep one skill in .agents/skills and symlink the",
-      "                                    other agents to it (default)",
-      "                   --copy           give every agent directory its own copy",
-      "                   --force          replace a skill directory klint did not install",
-      "",
-      "  Installed skills record the version and hash they came from. klint warns with",
-      "  klint/skill-stale once the shipped skill moves on, and with",
-      "  klint/skill-legacy-link for old symlinks that point into node_modules.",
-      "",
-      `Built-in rules (${standaloneRules.length}):`,
-      ...standaloneRules.map((r) => `  ${r}`),
-      "",
-      `Plugins (${pluginEntries.length}):`,
-      ...pluginEntries.flatMap(([name, plugin]) => [
-        `  ${name}`,
-        ...Object.keys(plugin.rules).map((r) => `    ${r}`),
-      ]),
-      "",
-    ].join("\n")
-  );
+  return [
+    `Built-in rules (${standaloneRules.length}):`,
+    ...standaloneRules.map((r) => `  ${r}`),
+    "",
+    `Plugins (${pluginEntries.length}):`,
+    ...pluginEntries.flatMap(([name, plugin]) => [
+      `  ${name}`,
+      ...Object.keys(plugin.rules).map((r) => `    ${r}`),
+    ]),
+  ];
 }

package/cli/install-skill.ts

@@ -13,6 +13,7 @@ import {
   type SkillReceipt,
   skillHash,
 } from "../core/skill";
+import type { OptionValues } from "./command";
 import { installedVersion, PACKAGE_ROOT } from "./paths";
 
 const AGENT_TARGETS = [
@@ -29,14 +30,14 @@ interface InstallPlan {
   force: boolean;
 }
 
-export async function installSkill(args: string[]): Promise<void> {
+export async function installSkill(values: OptionValues): Promise<void> {
   const skillSrc = join(PACKAGE_ROOT, "skill", SKILL_DIR_NAME);
   if (!existsSync(skillSrc)) {
     process.stderr.write(`klint: skill source not found at ${skillSrc}\n`);
     process.exit(1);
   }
 
-  const plan = await resolvePlan(args);
+  const plan = await resolvePlan(values);
   const dirs = agentSkillDirs(plan.agents);
 
   try {
@@ -164,8 +165,8 @@ async function writeReceipt(dest: string, skillSrc: string): Promise<void> {
   await writeFile(join(dest, RECEIPT_FILE_NAME), `${JSON.stringify(receipt, null, 2)}\n`);
 }
 
-async function resolvePlan(args: string[]): Promise<InstallPlan> {
-  const flags = parseFlags(args);
+async function resolvePlan(values: OptionValues): Promise<InstallPlan> {
+  const flags = parseFlags(values);
   const decided = flags.agents !== undefined || flags.shared !== undefined;
 
   if (!process.stdin.isTTY || decided) {
@@ -184,27 +185,21 @@ async function resolvePlan(args: string[]): Promise<InstallPlan> {
   };
 }
 
-function parseFlags(args: string[]): {
+function parseFlags(values: OptionValues): {
   agents?: AgentKey[];
   shared?: boolean;
   force: boolean;
 } {
-  let agents: AgentKey[] | undefined;
-  let shared: boolean | undefined;
-  let force = false;
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--agents" && args[i + 1]) agents = parseAgents(args[++i]);
-    else if (args[i] === "--symlink" || args[i] === "--shared") shared = true;
-    else if (args[i] === "--copy") shared = false;
-    else if (args[i] === "--force") force = true;
-    else {
-      process.stderr.write(`klint: unknown install-skill argument "${args[i]}"\n`);
-      process.exit(1);
-    }
-  }
+  return {
+    agents: typeof values.agents === "string" ? parseAgents(values.agents) : undefined,
+    shared: sharedChoice(values),
+    force: values.force === true,
+  };
+}
 
-  return { agents, force, shared };
+function sharedChoice(values: OptionValues): boolean | undefined {
+  if (values.copy) return false;
+  return values.symlink ? true : undefined;
 }
 
 function parseAgents(value: string): AgentKey[] {

package/cli/stats.ts

@@ -1,34 +1,92 @@
 import { resolve } from "node:path";
 import { type KlintStats, readStats, STATS_DIR, STATS_FILE } from "../core/stats";
+import type { OptionValues } from "./command";
 
-function rulesByCount(byRule: Record<string, number>): Array<[string, number]> {
+const RULE_HEADING = "by rule";
+const REPORTED_HEADING = "reported";
+const PREVENTED_HEADING = "prevented";
+const LABEL_WIDTH = "violations reported".length;
+
+interface RuleRow {
+  rule: string;
+  reported: number;
+  prevented: number;
+}
+
+function ruleRows(stats: KlintStats): RuleRow[] {
+  const rules = new Set([
+    ...Object.keys(stats.reported.byRule),
+    ...Object.keys(stats.prevented.byRule),
+  ]);
   const byCodePoint = (a: string, b: string) => Number(a > b) - Number(a < b);
-  return Object.entries(byRule).sort(([a, x], [b, y]) => y - x || byCodePoint(a, b));
+  return [...rules]
+    .map((rule) => ({
+      rule,
+      reported: stats.reported.byRule[rule] ?? 0,
+      prevented: stats.prevented.byRule[rule] ?? 0,
+    }))
+    .sort(
+      (a, b) =>
+        b.reported - a.reported ||
+        b.prevented - a.prevented ||
+        byCodePoint(a.rule, b.rule)
+    );
+}
+
+interface Summary {
+  label: string;
+  total: number;
+  detail: string;
+}
+
+function summaryLines(summaries: Summary[]): string[] {
+  const width = Math.max(...summaries.map(({ total }) => String(total).length));
+  return summaries.map(
+    ({ label, total, detail }) =>
+      `  ${label.padEnd(LABEL_WIDTH)}  ${String(total).padStart(width)}  (${detail})`
+  );
+}
+
+function ruleTable(rows: RuleRow[]): string[] {
+  const width = Math.max(RULE_HEADING.length - 2, ...rows.map(({ rule }) => rule.length));
+  const heading = `  ${RULE_HEADING.padEnd(width + 2)}  ${REPORTED_HEADING}  ${PREVENTED_HEADING}`;
+  const lines = rows.map(
+    ({ rule, reported, prevented }) =>
+      `    ${rule.padEnd(width)}  ${String(reported).padStart(REPORTED_HEADING.length)}  ${String(prevented).padStart(PREVENTED_HEADING.length)}`
+  );
+  return [heading, ...lines];
 }
 
 export function formatStats(stats: KlintStats): string {
-  const runs = stats.runs.hook + stats.runs.direct;
-  const prevented = stats.prevented.bySource.hook + stats.prevented.bySource.direct;
-  const rules = rulesByCount(stats.prevented.byRule);
-  const width = Math.max(0, ...rules.map(([rule]) => rule.length));
+  const { runs, reported, prevented } = stats;
   const lines = [
     `klint stats (${STATS_DIR}/${STATS_FILE})`,
     "",
-    `  runs              ${runs}  (hook ${stats.runs.hook}, direct ${stats.runs.direct})`,
-    `  errors prevented  ${prevented}  (caught by hook ${stats.prevented.bySource.hook}, direct ${stats.prevented.bySource.direct})`,
+    ...summaryLines([
+      {
+        label: "runs",
+        total: runs.hook + runs.direct,
+        detail: `hook ${runs.hook}, direct ${runs.direct}`,
+      },
+      {
+        label: "violations reported",
+        total: reported.bySource.hook + reported.bySource.direct,
+        detail: `hook ${reported.bySource.hook}, direct ${reported.bySource.direct}`,
+      },
+      {
+        label: "errors prevented",
+        total: prevented.bySource.hook + prevented.bySource.direct,
+        detail: `caught by hook ${prevented.bySource.hook}, direct ${prevented.bySource.direct}`,
+      },
+    ]),
   ];
-  if (rules.length > 0) {
-    lines.push("", "  prevented by rule");
-    for (const [rule, count] of rules) lines.push(`    ${rule.padEnd(width)}  ${count}`);
-  }
+  const rows = ruleRows(stats);
+  if (rows.length > 0) lines.push("", ...ruleTable(rows));
   return `${lines.join("\n")}\n`;
 }
 
-export function printStats(args: string[]): void {
-  const configFlag = args.indexOf("--config");
+export function printStats(values: OptionValues): void {
   const configDir =
-    configFlag !== -1 && args[configFlag + 1]
-      ? resolve(args[configFlag + 1])
-      : process.cwd();
+    typeof values.config === "string" ? resolve(values.config) : process.cwd();
   process.stdout.write(formatStats(readStats(configDir)));
 }

package/cli.ts

@@ -3,7 +3,8 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { printHelp } from "./cli/help";
+import { type OptionValues, runCommand } from "./cli/command";
+import { klintCommand } from "./cli/commands";
 import { installSkill } from "./cli/install-skill";
 import {
   formatDuration,
@@ -22,60 +23,33 @@ import { skillAdvisories } from "./core/skill";
 import { runRecorder } from "./core/stats";
 import type { ArchConfig, KlintConfig, KlintRule, RuleConfigValue } from "./core/types";
 
-interface CliOptions {
-  configDir?: string;
-  rulesFile?: string;
-}
-
-export async function main(opts: CliOptions = {}): Promise<void> {
+export async function main(): Promise<number> {
   const startedAt = performance.now();
-  const args = process.argv.slice(2);
-
-  if (args[0] === "help" || args[0] === "h") {
-    printHelp();
-    process.exit(0);
-  }
+  const command = klintCommand({
+    lint: (values) => lint(values, startedAt),
+    stats: printStats,
+    installSkill,
+  });
+  return runCommand(command, process.argv.slice(2), ["klint"]);
+}
 
-  if (args[0] === "stats") {
-    printStats(args.slice(1));
-    return;
-  }
+function optionalPath(value: string | true | undefined): string | undefined {
+  return typeof value === "string" ? resolve(value) : undefined;
+}
 
-  const subcommand = args.indexOf("install-skill");
-  if (subcommand !== -1) {
-    await installSkill(args.slice(subcommand + 1));
+async function lint(values: OptionValues, startedAt: number): Promise<void> {
+  if (values.version) {
+    process.stdout.write(`klint ${installedVersion()}\n`);
     return;
   }
-
-  let configDir = opts.configDir;
-  let rulesFile = opts.rulesFile;
-  let fix = false;
-  let json = false;
-  let debug = false;
-  let hook = false;
-  let engine = process.env.KLINT_ENGINE;
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--config" && args[i + 1]) configDir = resolve(args[++i]);
-    else if (args[i] === "--rules" && args[i + 1]) rulesFile = resolve(args[++i]);
-    else if (args[i] === "--engine" && args[i + 1]) engine = args[++i];
-    else if (args[i] === "--fix") fix = true;
-    else if (args[i] === "--json") json = true;
-    else if (args[i] === "--hook") hook = true;
-    else if (args[i] === "--debug" || args[i] === "-debug") debug = true;
-    else if (args[i] === "--help" || args[i] === "-h") {
-      printHelp();
-      process.exit(0);
-    } else if (args[i] === "--version" || args[i] === "-V") {
-      process.stdout.write(`klint ${installedVersion()}\n`);
-      process.exit(0);
-    } else {
-      process.stderr.write(`klint: unknown argument "${args[i]}"\n`);
-      process.exit(1);
-    }
-  }
-
-  configDir ??= process.cwd();
+  const rulesFile = optionalPath(values.rules);
+  const fix = values.fix === true;
+  const json = values.json === true;
+  const debug = values.debug === true;
+  const hook = values.hook === true;
+  const engine =
+    typeof values.engine === "string" ? values.engine : process.env.KLINT_ENGINE;
+  const configDir = optionalPath(values.config) ?? process.cwd();
   const record = runRecorder(configDir, hook ? "hook" : "direct");
 
   const yamlPath = resolve(configDir, "klint.yaml");
@@ -237,4 +211,4 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   writeTextOutput([...violations, ...advisories], startedAt);
 }
 
-if (import.meta.main) await main();
+if (import.meta.main) process.exitCode = await main();

package/core/stats.ts

@@ -6,6 +6,7 @@ export const STATS_DIR = ".klint";
 export const STATS_FILE = "stats.json";
 const SELF_IGNORE = "# Created by klint automatically.\n*\n";
 const STATS_VERSION = 1;
+const KLINT_ADVISORY_PREFIX = "klint/";
 
 export type RunSource = "hook" | "direct";
 
@@ -23,18 +24,31 @@ interface OpenError {
 export interface KlintStats {
   version: typeof STATS_VERSION;
   runs: Record<RunSource, number>;
-  prevented: {
-    byRule: Record<string, number>;
-    bySource: Record<RunSource, number>;
-  };
+  reported: RuleCounts;
+  prevented: RuleCounts;
   open: OpenError[];
 }
 
+interface RuleCounts {
+  byRule: Record<string, number>;
+  bySource: Record<RunSource, number>;
+}
+
+function emptyCounts(): RuleCounts {
+  return { byRule: {}, bySource: { hook: 0, direct: 0 } };
+}
+
+function bump(counts: RuleCounts, rule: string, source: RunSource): void {
+  counts.byRule[rule] = (counts.byRule[rule] ?? 0) + 1;
+  counts.bySource[source] += 1;
+}
+
 export function emptyStats(): KlintStats {
   return {
     version: STATS_VERSION,
     runs: { hook: 0, direct: 0 },
-    prevented: { byRule: {}, bySource: { hook: 0, direct: 0 } },
+    reported: emptyCounts(),
+    prevented: emptyCounts(),
     open: [],
   };
 }
@@ -43,6 +57,10 @@ function sameError(a: Omit<OpenError, "caughtBy">, b: Omit<OpenError, "caughtBy"
   return a.rule === b.rule && a.file === b.file && a.message === b.message;
 }
 
+function isCodeViolation(violation: CountedViolation): boolean {
+  return !violation.rule.startsWith(KLINT_ADVISORY_PREFIX);
+}
+
 function errorsOf(
   violations: readonly CountedViolation[]
 ): Omit<OpenError, "caughtBy">[] {
@@ -58,14 +76,16 @@ export function nextStats(
 ): KlintStats {
   const stats = structuredClone(previous);
   stats.runs[source] += 1;
+  for (const violation of violations.filter(isCodeViolation)) {
+    bump(stats.reported, violation.rule, source);
+  }
 
   const unmatched = errorsOf(violations);
   const stillOpen: OpenError[] = [];
   for (const error of previous.open) {
     const match = unmatched.findIndex((current) => sameError(current, error));
     if (match === -1) {
-      stats.prevented.byRule[error.rule] = (stats.prevented.byRule[error.rule] ?? 0) + 1;
-      stats.prevented.bySource[error.caughtBy] += 1;
+      bump(stats.prevented, error.rule, error.caughtBy);
       continue;
     }
     unmatched.splice(match, 1);
@@ -78,6 +98,15 @@ export function nextStats(
   return stats;
 }
 
+function isRuleCounts(value: unknown): value is RuleCounts {
+  const candidate = value as Partial<RuleCounts> | undefined;
+  return (
+    typeof candidate?.byRule === "object" &&
+    typeof candidate.bySource?.hook === "number" &&
+    typeof candidate.bySource.direct === "number"
+  );
+}
+
 function isStats(value: unknown): value is KlintStats {
   if (!value || typeof value !== "object") return false;
   const candidate = value as Partial<KlintStats>;
@@ -85,19 +114,22 @@ function isStats(value: unknown): value is KlintStats {
     candidate.version === STATS_VERSION &&
     typeof candidate.runs?.hook === "number" &&
     typeof candidate.runs.direct === "number" &&
-    typeof candidate.prevented?.byRule === "object" &&
-    typeof candidate.prevented.bySource?.hook === "number" &&
-    typeof candidate.prevented.bySource.direct === "number" &&
+    isRuleCounts(candidate.prevented) &&
+    (candidate.reported === undefined || isRuleCounts(candidate.reported)) &&
     Array.isArray(candidate.open)
   );
 }
 
+function withReportedCounts(stats: KlintStats): KlintStats {
+  return { ...stats, reported: stats.reported ?? emptyCounts() };
+}
+
 export function readStats(configDir: string): KlintStats {
   try {
     const parsed: unknown = JSON.parse(
       readFileSync(join(configDir, STATS_DIR, STATS_FILE), "utf-8")
     );
-    return isStats(parsed) ? parsed : emptyStats();
+    return isStats(parsed) ? withReportedCounts(parsed) : emptyStats();
   } catch {
     return emptyStats();
   }

package/klint.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.35.1/klint.schema.json",
+  "$id": "https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.36.0/klint.schema.json",
   "type": "object",
   "properties": {
     "$schema": {

package/klint.schema.yaml

@@ -1,5 +1,5 @@
 $schema: http://json-schema.org/draft-07/schema#
-$id: https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.35.1/klint.schema.json
+$id: https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.36.0/klint.schema.json
 type: object
 properties:
   $schema:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -70,10 +70,10 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "0.35.1",
-    "@konvert7/klint-darwin-x64": "0.35.1",
-    "@konvert7/klint-linux-x64": "0.35.1",
-    "@konvert7/klint-win32-x64": "0.35.1"
+    "@konvert7/klint-darwin-arm64": "0.36.0",
+    "@konvert7/klint-darwin-x64": "0.36.0",
+    "@konvert7/klint-linux-x64": "0.36.0",
+    "@konvert7/klint-win32-x64": "0.36.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

package/skill/klint-rules/SKILL.md

@@ -55,6 +55,18 @@ Wire it into `klint.yaml` for editor autocomplete and validation:
 
 7. **Write a break test** — prove the rule fires on a deliberate violation, and doesn't fire on clean code. Run the test suite to confirm.
 
+## Run tracking
+
+Every run is recorded in `.klint/stats.json` next to the config. The folder ignores itself, so never add it to `.gitignore`.
+
+| Command or flag | Use |
+|---|---|
+| `klint stats [--config <dir>]` | Print runs, violations reported and errors prevented, in total and per rule. Use it to answer "how much has klint caught?" |
+| `--hook` | Put it only in agent hook commands, e.g. `klint --json --hook`. Leave it off when you run klint yourself, so your runs count as direct. |
+| `KLINT_NO_STATS=1` | Turn recording off for a run, e.g. in a throwaway fixture. |
+
+Every violation a run reports counts as reported, repeats included; klint's own `klint/*` advisories do not. An error counts as prevented once, when a later run no longer reports it. Errors match by rule, file and message, so moving code to another line is not a fix. Warnings are not tracked.
+
 ## Primitive reference
 
 ### Layers