@konvert7/klint 0.18.0 → 0.19.1

package/README.md

@@ -98,7 +98,7 @@ Rules give agents room to move quickly because the unsafe moves are blocked stru
 ## CLI
 
 ```sh
-klint [--config <dir>] [--rules <file>] [--fix] [--json]
+klint [--config <dir>] [--rules <file>] [--engine ts|rust|compare|auto] [--fix] [--json]
 klint install-skill [--agents <list>] [--symlink | --copy]
 ```
 
@@ -106,6 +106,7 @@ klint install-skill [--agents <list>] [--symlink | --copy]
 |------|-------------|
 | `--config <dir>` | Directory containing `klint.yaml` or `klint.config.json` (default: cwd) |
 | `--rules <file>` | Path to custom rules file (default: `<configDir>/klint.rules.ts` when present) |
+| `--engine <name>` | Engine mode: `ts` (default), `rust`, `compare`, or `auto` |
 | `--fix` | Apply auto-fixes for fixable violations in-place |
 | `--json` | Emit structured JSON to stdout for agents and CI |
 
@@ -115,6 +116,43 @@ klint install-skill [--agents <list>] [--symlink | --copy]
 klint install-skill --agents claude,opencode,cursor,codex --copy
 ```
 
+## Engines
+
+klint currently ships a TypeScript engine and an experimental Rust engine. The Rust path is built for portable architecture checks and syntax-local rules; type-aware checks stay in TypeScript for now.
+
+Maintainer migration notes live in [`docs/rust-engine.md`](docs/rust-engine.md).
+
+| Engine | What it does | When to use it |
+|--------|--------------|----------------|
+| `ts` | Runs the full TypeScript implementation. This is the default. | Maximum compatibility |
+| `rust` | Runs only rules supported by the Rust engine. Unsupported TS-only rules are rejected. | Strict Rust smoke tests and native-engine debugging |
+| `compare` | Runs TS and Rust on the same supported config and fails if JSON output differs. Requires `--json`. | Parity verification while porting rules |
+| `auto` | Runs Rust-supported rules in Rust, TS-only rules in TypeScript, then merges output. | Recommended experimental migration path |
+
+Examples:
+
+```sh
+klint --engine auto
+klint --engine rust --json     # strict Rust-only run; rejects unsupported TS-only rules
+klint --engine compare --json  # parity check; rejects unsupported TS-only rules
+```
+
+Rust currently supports:
+
+- `arch` rules: imports, forbidden patterns, singleton locations
+- `no-unguarded-json-parse`
+- `no-nested-template-literals`
+- `no-consecutive-array-push`
+- `no-string-match`
+
+These rules remain TypeScript-owned because they need TypeScript semantic information:
+
+- `no-floating-promise`
+- `no-misused-promises`
+- `no-date-equality`
+- `no-optional-chain-on-non-nullable`
+- `no-object-in-template`
+
 ## Configuration
 
 `klint.yaml` lives at your project root alongside tools like `biome.json`, `tsconfig.json`, and `knip.json`.

package/cli.ts

@@ -4,17 +4,26 @@ import {
   cpSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   rmSync,
   symlinkSync,
+  writeFileSync,
 } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import * as clack from "@clack/prompts";
 import { parse as parseYaml } from "yaml";
 import { applyFixes } from "./core/fixer";
 import { resolveNativePackageBinary } from "./core/native-binary";
 import { type KlintDebugEvent, runKlint } from "./core/runner";
-import type { ArchConfig, KlintConfig, KlintRule, RuleConfigValue } from "./core/types";
+import type {
+  ArchConfig,
+  KlintConfig,
+  KlintRule,
+  RuleConfigValue,
+  Violation,
+} from "./core/types";
 import { BUILT_IN_PLUGINS } from "./plugins/index";
 import { BUILT_IN_RULES } from "./rules/index";
 
@@ -96,12 +105,18 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   const root = resolve(configDir, raw.root ?? ".");
 
   if (engine === "rust") {
-    runRustEngine({ configDir, fix, json, raw, rulesFile });
+    runRustEngine({ configDir, fix, json, raw, rulesFile, startedAt });
     return;
   }
-  if (engine !== undefined && engine !== "ts" && engine !== "compare") {
+  if (
+    engine !== undefined &&
+    engine !== "ts" &&
+    engine !== "rust" &&
+    engine !== "compare" &&
+    engine !== "auto"
+  ) {
     process.stderr.write(
-      `klint: unknown engine "${engine}" (expected "ts", "rust", or "compare")\n`
+      `klint: unknown engine "${engine}" (expected "ts", "rust", "compare", or "auto")\n`
     );
     process.exit(1);
   }
@@ -120,6 +135,20 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   );
   const allRules: KlintConfig["rules"] = { ...customRulesMap, ...(raw.rules ?? {}) };
 
+  if (engine === "auto") {
+    runAutoEngine({
+      fix,
+      json,
+      raw,
+      root,
+      rulesFile,
+      startedAt,
+      customRules,
+      customRulesMap,
+    });
+    return;
+  }
+
   const violations = runKlint(
     {
       root,
@@ -171,7 +200,19 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     process.stdout.write(`${msg} Finished in ${formatDuration(startedAt)}.\n`);
     process.exit(0);
   }
+  writeTextOutput(violations, startedAt);
+}
+
+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`;
+}
 
+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");
 
@@ -203,18 +244,13 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   process.exit(0);
 }
 
-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`;
-}
-
 function runRustEngine({
   configDir,
   fix,
   json,
   raw,
   rulesFile,
+  startedAt,
 }: {
   configDir: string;
   fix: boolean;
@@ -225,10 +261,10 @@ function runRustEngine({
     arch?: unknown;
   };
   rulesFile?: string;
+  startedAt: number;
 }): void {
   const unsupportedReason = rustEngineUnsupportedReason({
     fix,
-    json,
     raw,
     rulesFile,
   });
@@ -249,9 +285,18 @@ function runRustEngine({
     encoding: "utf-8",
   });
 
-  if (result.stdout) process.stdout.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
-  process.exit(result.status ?? 1);
+  if (json) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    process.exit(result.status ?? 1);
+  }
+
+  const payload = parseJsonPayload(result.stdout);
+  if (!isJsonPayload(payload)) {
+    process.stderr.write("klint: --engine rust failed to parse Rust JSON output\n");
+    process.exit(1);
+  }
+  writeTextOutput(payload.violations, startedAt);
 }
 
 function runCompareEngine({
@@ -273,9 +318,13 @@ function runCompareEngine({
   rulesFile?: string;
   tsViolations: ReturnType<typeof runKlint>;
 }): void {
+  if (!json) {
+    process.stderr.write("klint: --engine compare currently requires --json\n");
+    process.exit(1);
+  }
+
   const unsupportedReason = rustEngineUnsupportedReason({
     fix,
-    json,
     raw,
     rulesFile,
   });
@@ -317,17 +366,190 @@ function runCompareEngine({
   process.exit(tsResult.status);
 }
 
+function runAutoEngine({
+  fix,
+  json,
+  raw,
+  root,
+  rulesFile,
+  startedAt,
+  customRules,
+  customRulesMap,
+}: {
+  fix: boolean;
+  json: boolean;
+  raw: {
+    root?: string;
+    include?: string[];
+    plugins?: string[];
+    rules?: Record<string, RuleConfigValue>;
+    arch?: unknown;
+  };
+  root: string;
+  rulesFile?: string;
+  startedAt: number;
+  customRules: Record<string, KlintRule>;
+  customRulesMap: Record<string, RuleConfigValue>;
+}): void {
+  if (fix) {
+    process.stderr.write("klint: --engine auto does not support --fix\n");
+    process.exit(1);
+  }
+  if (rulesFile) {
+    process.stderr.write("klint: --engine auto does not support --rules\n");
+    process.exit(1);
+  }
+
+  const { rustRules, tsRules } = splitRulesForAuto(raw.rules ?? {});
+  const tsViolations = runKlint(
+    {
+      root,
+      include: raw.include ?? ["."],
+      plugins: raw.plugins,
+      rules: { ...customRulesMap, ...tsRules },
+    },
+    customRules
+  );
+
+  const rustOutput = runAutoRustSubset({
+    raw,
+    root,
+    rustRules,
+  });
+  const tsOutput = toJsonPayload(tsViolations);
+  const merged = mergeJsonOutputs(rustOutput, tsOutput);
+  if (json) {
+    process.stdout.write(JSON.stringify(merged));
+    process.exit(merged.summary.errors > 0 ? 2 : 0);
+  }
+  writeTextOutput(merged.violations, startedAt);
+}
+
+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_TYPESCRIPT_RULES.has(name)) rustRules[name] = value;
+    else tsRules[name] = value;
+  }
+
+  return { rustRules, tsRules };
+}
+
+function runAutoRustSubset({
+  raw,
+  root,
+  rustRules,
+}: {
+  raw: {
+    include?: string[];
+    arch?: unknown;
+  };
+  root: string;
+  rustRules: Record<string, RuleConfigValue>;
+}): JsonPayload {
+  const hasRustRules = Object.values(rustRules).some(
+    (value) => ruleConfigSeverity(value) !== "off"
+  );
+  if (!raw.arch && !hasRustRules) {
+    return emptyJsonPayload();
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), "klint-auto-rust-"));
+  try {
+    writeFileSync(
+      join(tempDir, "klint.config.json"),
+      JSON.stringify({
+        root,
+        include: raw.include ?? ["."],
+        rules: rustRules,
+        arch: raw.arch,
+      })
+    );
+
+    const command = resolveRustEngineCommand(tempDir);
+    const result = spawnSync(command.bin, command.args, {
+      cwd: import.meta.dir,
+      encoding: "utf-8",
+    });
+    if (result.stderr) process.stderr.write(result.stderr);
+    if ((result.status ?? 1) !== 0 && (result.status ?? 1) !== 2) {
+      process.stderr.write(result.stdout);
+      process.exit(result.status ?? 1);
+    }
+
+    const payload = parseJsonPayload(result.stdout);
+    if (!isJsonPayload(payload)) {
+      process.stderr.write("klint: --engine auto failed to parse Rust JSON output\n");
+      process.exit(1);
+    }
+    return payload;
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+interface JsonPayload {
+  violations: Array<Omit<Violation, "fix"> & { fix: unknown }>;
+  summary: {
+    errors: number;
+    warnings: number;
+  };
+}
+
+function emptyJsonPayload(): JsonPayload {
+  return {
+    violations: [],
+    summary: { errors: 0, warnings: 0 },
+  };
+}
+
+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 },
+  };
+}
+
+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,
+    },
+  };
+}
+
+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";
+}
+
 function toJsonCliResult(violations: ReturnType<typeof runKlint>): {
   stdout: string;
   status: number;
 } {
-  const errors = violations.filter((v) => v.severity === "error");
+  const payload = toJsonPayload(violations);
   return {
-    stdout: JSON.stringify({
-      violations: violations.map((v) => ({ ...v, fix: v.fix ?? null })),
-      summary: { errors: errors.length, warnings: violations.length - errors.length },
-    }),
-    status: errors.length > 0 ? 2 : 0,
+    stdout: JSON.stringify(payload),
+    status: payload.summary.errors > 0 ? 2 : 0,
   };
 }
 
@@ -400,12 +622,10 @@ function isSourceCheckout(): boolean {
 
 function rustEngineUnsupportedReason({
   fix,
-  json,
   raw,
   rulesFile,
 }: {
   fix: boolean;
-  json: boolean;
   raw: {
     plugins?: string[];
     rules?: Record<string, RuleConfigValue>;
@@ -413,7 +633,6 @@ function rustEngineUnsupportedReason({
   };
   rulesFile?: string;
 }): string | undefined {
-  if (!json) return "KLINT_ENGINE=rust currently requires --json";
   if (fix) return "KLINT_ENGINE=rust does not support --fix";
   if (rulesFile) return "KLINT_ENGINE=rust does not support --rules";
   if ((raw.plugins?.length ?? 0) > 0) return "KLINT_ENGINE=rust does not support plugins";
@@ -576,12 +795,12 @@ function printHelp(): void {
     [
       "klint — agent harness for TypeScript architecture rules",
       "",
-      "Usage: klint [--config <dir>] [--rules <file>] [--engine ts|rust|compare] [--fix] [--json]",
+      "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, or compare (experimental, requires --json)",
+      "  --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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "type-check": "tsc --noEmit",
     "test": "bun test",
     "test:rust-engine": "bun test tests/rust-engine-cli.test.ts",
+    "test:auto-engine": "bun cli.ts --engine auto",
     "pack:check": "bun tests/pack-check.ts",
     "native:stage": "bun tests/stage-native-binary.ts",
     "native:smoke": "bun tests/smoke-native-binary.ts",
@@ -43,7 +44,7 @@
     "check": "biome check",
     "check-write": "biome check --write",
     "knip": "knip-bun",
-    "klint": "bun cli.ts",
+    "klint": "bun cli.ts --engine auto",
     "jscpd": "jscpd --noTips",
     "schema": "bun tools/generate-schema.ts",
     "lint-staged": "lint-staged",