@konvert7/klint 0.19.0 → 0.19.2

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

@@ -610,6 +610,13 @@ function resolveRustEngineCommand(configDir: string): RustEngineCommand {
     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],

package/core/native-binary.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 
@@ -44,6 +44,7 @@ interface NativeBinaryOptions {
   platform?: string;
   arch?: string;
   exists?: (path: string) => boolean;
+  readPackageJson?: (path: string) => { version?: string };
   resolvePackageJson?: (packageName: string) => string;
 }
 
@@ -63,6 +64,7 @@ export function resolveNativePackageBinary({
   platform = process.platform,
   arch = process.arch,
   exists = existsSync,
+  readPackageJson = readJsonFile,
   resolvePackageJson,
 }: NativeBinaryOptions): string | undefined {
   const nativePackage = nativePackageForPlatform(platform, arch);
@@ -74,11 +76,33 @@ export function resolveNativePackageBinary({
     resolvePackageJson
   );
   if (!packageJsonPath) return undefined;
+  if (!nativePackageVersionMatches(packageRoot, packageJsonPath, readPackageJson)) {
+    return undefined;
+  }
 
   const binaryPath = join(dirname(packageJsonPath), nativePackage.binaryPath);
   return exists(binaryPath) ? binaryPath : undefined;
 }
 
+function nativePackageVersionMatches(
+  packageRoot: string,
+  nativePackageJsonPath: string,
+  readPackageJson: (path: string) => { version?: string }
+): boolean {
+  try {
+    const rootVersion = readPackageJson(join(packageRoot, "package.json")).version;
+    const nativeVersion = readPackageJson(nativePackageJsonPath).version;
+    if (!rootVersion || !nativeVersion) return true;
+    return rootVersion === nativeVersion;
+  } catch {
+    return true;
+  }
+}
+
+function readJsonFile(path: string): { version?: string } {
+  return JSON.parse(readFileSync(path, "utf-8")) as { version?: string };
+}
+
 function resolveOptionalPackageJson(
   packageRoot: string,
   packageName: string,

package/package.json

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

package/tools/semantic-release-root-npm.js

@@ -2,6 +2,13 @@ import { spawnSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+const NATIVE_PACKAGE_NAMES = [
+  "@konvert7/klint-darwin-arm64",
+  "@konvert7/klint-darwin-x64",
+  "@konvert7/klint-linux-x64",
+  "@konvert7/klint-win32-x64",
+];
+
 export async function verifyConditions(_, context) {
   const cwd = context.cwd ?? process.cwd();
   const packageJson = readPackageJson(cwd);
@@ -21,6 +28,10 @@ export async function prepare(_, context) {
 
   const packageJson = readPackageJson(cwd);
   packageJson.version = version;
+  packageJson.optionalDependencies ??= {};
+  for (const packageName of NATIVE_PACKAGE_NAMES) {
+    packageJson.optionalDependencies[packageName] = version;
+  }
   writePackageJson(cwd, packageJson);
 }