@konvert7/klint 0.24.0 → 0.25.0

package/README.md

@@ -97,6 +97,8 @@ klint is for rules that are too project-specific or context-heavy for a formatte
 | Layer boundaries | `src/components/**` must not import from `src/data/**` |
 | Singleton ownership | `process.env.API_KEY` may only appear in `src/lib/auth.ts` |
 | Forbidden patterns | `console.log(` is blocked inside hook libraries |
+| Raw JSX elements | `<button>` is blocked outside `src/components/ui/**` |
+| File length | No file in `src/**` may exceed 300 lines |
 | Type-aware mistakes | Promise-returning calls cannot be silently discarded |
 | Repository policy | Custom `klint.rules.ts` rules run with the same severity/config system |
 
@@ -146,7 +148,7 @@ klint --engine compare --json  # parity check; rejects unsupported rules
 
 Rust currently supports:
 
-- `arch` rules: imports, forbidden patterns, singleton locations
+- `arch` rules: imports, forbidden patterns (literal + `re:` regex), singleton locations, `maxLines` file limits
 - `no-unguarded-json-parse`
 - `no-sync-in-async`
 - `no-nested-template-literals`
@@ -273,6 +275,30 @@ arch:
       message: "Libraries should return or throw, not terminate the process"
 ```
 
+Match a **regular expression** instead of a literal by prefixing the pattern with `re:` — useful for value-shaped policies such as off-system utility classes. Regexes use the common JS/RE2 subset (no lookaround or backreferences) so the TS and Rust engines agree:
+
+```yaml
+arch:
+  forbidden:
+    - pattern: 're:\b(?:p|gap)-\[' # reject Tailwind arbitrary values like p-[18px]
+      in: ["src/**/*.tsx"]
+      message: "Use the spacing scale, not arbitrary bracket values"
+```
+
+A literal pattern that itself begins with `re:` cannot be expressed — such a value is always read as a regex.
+
+Block raw JSX/HTML elements with `jsx-element` to push consumers onto design-system primitives. It is AST-matched on intrinsic (lowercase) tag names, so it is robust to whitespace, attributes, and lookalikes like `<buttonGroup>`:
+
+```yaml
+arch:
+  forbidden:
+    - jsx-element: ["button", "input", "label"]
+      in: ["src/app/**/*.tsx", "src/components/**/*.tsx", "!src/components/ui/**"]
+      message: "Use the design-system primitives in @/components/ui/* instead of raw HTML elements"
+```
+
+`jsx-element` matches intrinsic HTML elements only — not custom components like `<Button>`. Use `arch.imports` to restrict those.
+
 ### Singleton Locations
 
 Enforce that a pattern appears only in one designated file:
@@ -286,6 +312,36 @@ arch:
       message: "Use the auth module"
 ```
 
+Like `forbidden`, a singleton `pattern` may use the `re:` regex prefix for value-shaped matches.
+
+`singleton` accepts `jsx-element` too — pin a raw element to the one primitive file that is allowed to render it:
+
+```yaml
+arch:
+  singleton:
+    - jsx-element: "button"
+      only: "src/components/ui/button.tsx"
+      in: ["src/**/*.tsx"]
+      message: "Raw <button> belongs only to the Button primitive"
+```
+
+### Max File Length
+
+Cap how long any file in a layer may grow. The limit counts every physical line — blanks and comments included — and a file over it is flagged at the first line past the limit:
+
+```yaml
+arch:
+  maxLines:
+    - limit: 300
+      in: ["src/**"]
+      message: "Split this module"   # optional — defaults to a message naming the limit
+
+    - limit: 600                      # different ceilings per scope
+      in: ["tests/**"]
+```
+
+`maxLines` is enforced in both the TS and Rust engines and applies to every language klint scans, with no formatter dependency.
+
 ### Python Architecture Checks
 
 The Rust engine can apply architecture rules to Python projects:

package/cli/help.ts

@@ -0,0 +1,41 @@
+import { BUILT_IN_PLUGINS } from "../plugins/index";
+import { BUILT_IN_RULES } from "../rules/index";
+
+export function printHelp(): void {
+  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]",
+      "       klint install-skill [--agents <list>] [--symlink | --copy]",
+      "",
+      "  --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",
+      "",
+      "  install-skill    install the rule-authoring skill into agent config directories",
+      "                   --agents <list>  comma-separated: claude,opencode,cursor,codex (default: all)",
+      "                   --symlink        install as symlink (stays in sync with updates)",
+      "                   --copy           install as copy (default in non-TTY)",
+      "",
+      `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")
+  );
+}

package/cli/install-skill.ts

@@ -0,0 +1,102 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm, symlink } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import * as clack from "@clack/prompts";
+import { PACKAGE_ROOT } from "./paths";
+
+const AGENT_TARGETS = [
+  { value: "claude", label: "Claude Code" },
+  { value: "opencode", label: "opencode" },
+  { value: "cursor", label: "Cursor" },
+  { value: "codex", label: "Codex" },
+] as const;
+
+type AgentKey = (typeof AGENT_TARGETS)[number]["value"];
+
+const AGENT_DIRS: Record<AgentKey, string> = {
+  claude: ".claude/skills",
+  opencode: ".agents/skills",
+  cursor: ".cursor/skills",
+  codex: ".agents/skills",
+};
+
+export async function installSkill(args: string[]): Promise<void> {
+  const skillSrc = join(PACKAGE_ROOT, "skill", "klint-rules");
+  if (!existsSync(skillSrc)) {
+    process.stderr.write(`klint: skill source not found at ${skillSrc}\n`);
+    process.exit(1);
+  }
+
+  // Parse non-interactive flags
+  let flagAgents: AgentKey[] | undefined;
+  let flagSymlink: boolean | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--agents" && args[i + 1])
+      flagAgents = args[++i].split(",") as AgentKey[];
+    else if (args[i] === "--symlink") flagSymlink = true;
+    else if (args[i] === "--copy") flagSymlink = false;
+  }
+
+  let selectedAgents: AgentKey[];
+  let useSymlink: boolean;
+
+  if (!process.stdin.isTTY || flagAgents !== undefined || flagSymlink !== undefined) {
+    selectedAgents = flagAgents ?? (AGENT_TARGETS.map((a) => a.value) as AgentKey[]);
+    useSymlink = flagSymlink ?? false;
+  } else {
+    clack.intro("klint install-skill");
+
+    const agents = await clack.multiselect<AgentKey>({
+      message: "Which agents should the skill be installed for?",
+      options: AGENT_TARGETS.map((a) => ({ value: a.value, label: a.label })),
+      initialValues: AGENT_TARGETS.map((a) => a.value) as AgentKey[],
+    });
+    if (clack.isCancel(agents)) {
+      clack.cancel("Cancelled.");
+      process.exit(0);
+    }
+    selectedAgents = agents as AgentKey[];
+
+    const mode = await clack.select<"symlink" | "copy">({
+      message: "Install as symlink or copy?",
+      options: [
+        {
+          value: "symlink",
+          label: "Symlink",
+          hint: "stays in sync when klint updates",
+        },
+        {
+          value: "copy",
+          label: "Copy",
+          hint: "one-time snapshot, no ongoing dependency",
+        },
+      ],
+    });
+    if (clack.isCancel(mode)) {
+      clack.cancel("Cancelled.");
+      process.exit(0);
+    }
+    useSymlink = mode === "symlink";
+  }
+
+  const cwd = process.cwd();
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  for (const key of selectedAgents) {
+    const dest = resolve(cwd, AGENT_DIRS[key], "klint-rules");
+    await mkdir(dirname(dest), { recursive: true });
+    try {
+      await rm(dest, { recursive: true, force: true });
+    } catch {
+      /* already gone */
+    }
+    if (useSymlink) {
+      await symlink(relative(dirname(dest), skillSrc), dest, linkType);
+    } else {
+      await cp(skillSrc, dest, { recursive: true });
+    }
+  }
+
+  if (process.stdin.isTTY) {
+    clack.outro("Done.");
+  }
+}

package/cli/output.ts

@@ -0,0 +1,159 @@
+import type { KlintDebugEvent, runKlint } from "../core/runner";
+import type { Violation } from "../core/types";
+
+export function formatDuration(startedAt: number): string {
+  const elapsedMs = performance.now() - startedAt;
+  if (elapsedMs < 1000) return `${Math.round(elapsedMs)}ms`;
+  return `${(elapsedMs / 1000).toFixed(elapsedMs < 10_000 ? 2 : 1)}s`;
+}
+
+export function writeTextOutput(
+  violations: Array<Omit<Violation, "fix">>,
+  startedAt: number
+): never {
+  const errors = violations.filter((v) => v.severity === "error");
+  const warns = violations.filter((v) => v.severity === "warn");
+
+  if (errors.length === 0 && warns.length === 0) {
+    process.stdout.write(`klint: 0 violations in ${formatDuration(startedAt)}\n`);
+    process.exit(0);
+  }
+
+  const formatBlock = (v: (typeof violations)[number]) => {
+    const prefix = v.severity === "warn" ? "⚠" : "×";
+    const header = `${v.file}:${v.line}  [${v.rule}]`;
+    const sep = "━".repeat(Math.max(0, 80 - header.length));
+    return `${header} ${sep}\n\n  ${prefix} ${v.message}\n`;
+  };
+
+  if (warns.length > 0) {
+    process.stderr.write(
+      `klint: ${warns.length} warning(s)\n\n${warns.map(formatBlock).join("\n")}`
+    );
+  }
+  if (errors.length > 0) {
+    process.stderr.write(
+      `klint: ${errors.length} error(s)\n\n${errors.map(formatBlock).join("\n")}`
+    );
+    process.stderr.write(`\nklint: finished in ${formatDuration(startedAt)}\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`\nklint: finished in ${formatDuration(startedAt)}\n`);
+  process.exit(0);
+}
+
+export interface JsonPayload {
+  violations: Array<Omit<Violation, "fix"> & { fix: unknown }>;
+  summary: {
+    errors: number;
+    warnings: number;
+  };
+}
+
+export function emptyJsonPayload(): JsonPayload {
+  return {
+    violations: [],
+    summary: { errors: 0, warnings: 0 },
+  };
+}
+
+export function toJsonPayload(violations: ReturnType<typeof runKlint>): JsonPayload {
+  const errors = violations.filter((v) => v.severity === "error");
+  return {
+    violations: violations.map((v) => ({ ...v, fix: v.fix ?? null })),
+    summary: { errors: errors.length, warnings: violations.length - errors.length },
+  };
+}
+
+export function mergeJsonOutputs(...outputs: JsonPayload[]): JsonPayload {
+  const violations = outputs
+    .flatMap((output) => output.violations)
+    .sort(
+      (a, b) =>
+        a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        a.rule.localeCompare(b.rule) ||
+        a.message.localeCompare(b.message)
+    );
+  const errors = violations.filter((violation) => violation.severity === "error").length;
+  return {
+    violations,
+    summary: {
+      errors,
+      warnings: violations.length - errors,
+    },
+  };
+}
+
+export function isJsonPayload(value: unknown): value is JsonPayload {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<JsonPayload>;
+  return Array.isArray(candidate.violations) && typeof candidate.summary === "object";
+}
+
+export function toJsonCliResult(violations: ReturnType<typeof runKlint>): {
+  stdout: string;
+  status: number;
+} {
+  const payload = toJsonPayload(violations);
+  return {
+    stdout: JSON.stringify(payload),
+    status: payload.summary.errors > 0 ? 2 : 0,
+  };
+}
+
+export function writeDebugEvent(event: KlintDebugEvent): void {
+  switch (event.type) {
+    case "walk:start":
+      process.stderr.write(`[klint:debug] walk ${event.dir}\n`);
+      break;
+    case "walk:done":
+      process.stderr.write(`[klint:debug] walked ${event.dir} (${event.files} files)\n`);
+      break;
+    case "files:resolved":
+      process.stderr.write(`[klint:debug] resolved ${event.files} files\n`);
+      break;
+    case "rule:start":
+      process.stderr.write(
+        `[klint:debug] rule ${event.rule} start (${event.files} files)\n`
+      );
+      break;
+    case "rule:done":
+      process.stderr.write(
+        `[klint:debug] rule ${event.rule} done (${event.violations} violations)\n`
+      );
+      break;
+    case "arch:start":
+      process.stderr.write(`[klint:debug] arch start (${event.files} files)\n`);
+      break;
+    case "arch:done":
+      process.stderr.write(`[klint:debug] arch done (${event.violations} violations)\n`);
+      break;
+  }
+}
+
+export function parseJsonPayload(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+}
+
+export function jsonPayloadEquals(a: unknown, b: unknown): boolean {
+  return JSON.stringify(canonicalJson(a)) === JSON.stringify(canonicalJson(b));
+}
+
+function canonicalJson(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value
+      .map(canonicalJson)
+      .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  }
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, canonicalJson(entry)])
+  );
+}

package/cli/paths.ts

@@ -0,0 +1,3 @@
+import { resolve } from "node:path";
+
+export const PACKAGE_ROOT = resolve(import.meta.dir, "..");

package/cli/rust-config.ts

@@ -0,0 +1,144 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveNativePackageBinary } from "../core/native-binary";
+import type { RuleConfigValue } from "../core/types";
+import { BUILT_IN_PLUGINS } from "../plugins/index";
+import { PACKAGE_ROOT } from "./paths";
+
+const RUST_SUPPORTED_RULES = new Set([
+  "no-consecutive-array-push",
+  "no-nested-template-literals",
+  "no-string-match",
+  "no-sync-in-async",
+  "no-unguarded-json-parse",
+  "sonar/no-single-char-class",
+  "sonar/prefer-at",
+  "sonar/prefer-nullish-coalescing-assign",
+  "sonar/prefer-string-replaceall",
+  "sonar/prefer-string-raw",
+  "sonar/prefer-string-raw-regexp",
+]);
+
+export function splitRulesForAuto(rules: Record<string, RuleConfigValue>): {
+  rustRules: Record<string, RuleConfigValue>;
+  tsRules: Record<string, RuleConfigValue>;
+} {
+  const rustRules: Record<string, RuleConfigValue> = {};
+  const tsRules: Record<string, RuleConfigValue> = {};
+
+  for (const [name, value] of Object.entries(rules)) {
+    if (RUST_SUPPORTED_RULES.has(name)) rustRules[name] = value;
+    else tsRules[name] = value;
+  }
+
+  return { rustRules, tsRules };
+}
+
+export interface RustEngineCommand {
+  bin: string;
+  args: string[];
+}
+
+export function resolveRustEngineCommand(configDir: string): RustEngineCommand {
+  const args = ["--config", configDir, "--json"];
+  const explicitBin = process.env.KLINT_RUST_BIN;
+  if (explicitBin) {
+    return { bin: explicitBin, args };
+  }
+
+  const localBin = join(
+    PACKAGE_ROOT,
+    "target",
+    "debug",
+    process.platform === "win32" ? "klint-rs.exe" : "klint-rs"
+  );
+  if (isSourceCheckout() && existsSync(localBin)) {
+    return { bin: localBin, args };
+  }
+
+  const nativePackageBin = resolveNativePackageBinary({ packageRoot: PACKAGE_ROOT });
+  if (nativePackageBin) {
+    return { bin: nativePackageBin, args };
+  }
+
+  if (!isSourceCheckout()) {
+    process.stderr.write(
+      "klint: native Rust engine binary is unavailable for this package version\n"
+    );
+    process.exit(1);
+  }
+
+  return {
+    bin: "cargo",
+    args: ["run", "--quiet", "-p", "klint-rs", "--", ...args],
+  };
+}
+
+function isSourceCheckout(): boolean {
+  return existsSync(join(PACKAGE_ROOT, "crates", "klint-rs", "Cargo.toml"));
+}
+
+export function rustEngineUnsupportedReason({
+  fix,
+  raw,
+  rulesFile,
+}: {
+  fix: boolean;
+  raw: {
+    plugins?: string[];
+    rules?: Record<string, RuleConfigValue>;
+    arch?: unknown;
+  };
+  rulesFile?: string;
+}): string | undefined {
+  if (fix) return "KLINT_ENGINE=rust does not support --fix";
+  if (rulesFile) return "KLINT_ENGINE=rust does not support --rules";
+  let effectiveRules: Record<string, RuleConfigValue>;
+  try {
+    effectiveRules = resolveEffectiveRules(raw.plugins, raw.rules ?? {});
+  } catch (error) {
+    return error instanceof Error
+      ? error.message
+      : "KLINT_ENGINE=rust failed to load plugins";
+  }
+  const activeSupportedRules = Object.entries(effectiveRules).filter(
+    ([name, value]) =>
+      ruleConfigSeverity(value) !== "off" && RUST_SUPPORTED_RULES.has(name)
+  );
+  const unsupportedRules = Object.entries(effectiveRules)
+    .filter(
+      ([name, value]) =>
+        ruleConfigSeverity(value) !== "off" && !RUST_SUPPORTED_RULES.has(name)
+    )
+    .map(([name]) => name);
+  if (!raw.arch && activeSupportedRules.length === 0 && unsupportedRules.length === 0) {
+    return "KLINT_ENGINE=rust requires an arch config or supported rule";
+  }
+  if (unsupportedRules.length > 0) {
+    return [
+      "Rust engine currently supports arch rules and selected rules only",
+      "",
+      "Unsupported rules:",
+      ...unsupportedRules.map((rule) => `- ${rule}`),
+    ].join("\n");
+  }
+  return undefined;
+}
+
+export function resolveEffectiveRules(
+  plugins: string[] | undefined,
+  rules: Record<string, RuleConfigValue>
+): Record<string, RuleConfigValue> {
+  const pluginDefaults: Record<string, RuleConfigValue> = {};
+  for (const pluginName of plugins ?? []) {
+    const plugin = BUILT_IN_PLUGINS[pluginName];
+    if (!plugin) throw new Error(`Unknown klint plugin: "${pluginName}"`);
+    Object.assign(pluginDefaults, plugin.rules);
+  }
+  return { ...pluginDefaults, ...rules };
+}
+
+export function ruleConfigSeverity(value: RuleConfigValue): string | undefined {
+  if (typeof value === "string") return value;
+  return value.severity;
+}