@konvert7/klint 0.16.0 → 0.18.0

package/cli.ts

@@ -18,6 +18,13 @@ import type { ArchConfig, KlintConfig, KlintRule, RuleConfigValue } from "./core
 import { BUILT_IN_PLUGINS } from "./plugins/index";
 import { BUILT_IN_RULES } from "./rules/index";
 
+const RUST_SUPPORTED_TYPESCRIPT_RULES = new Set([
+  "no-consecutive-array-push",
+  "no-nested-template-literals",
+  "no-string-match",
+  "no-unguarded-json-parse",
+]);
+
 interface CliOptions {
   configDir?: string;
   rulesFile?: string;
@@ -42,10 +49,12 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   let fix = false;
   let json = false;
   let debug = 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] === "--debug" || args[i] === "-debug") debug = true;
@@ -85,12 +94,17 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     process.exit(1);
   }
   const root = resolve(configDir, raw.root ?? ".");
-  const engine = process.env.KLINT_ENGINE;
 
   if (engine === "rust") {
     runRustEngine({ configDir, fix, json, raw, rulesFile });
     return;
   }
+  if (engine !== undefined && engine !== "ts" && engine !== "compare") {
+    process.stderr.write(
+      `klint: unknown engine "${engine}" (expected "ts", "rust", or "compare")\n`
+    );
+    process.exit(1);
+  }
 
   let customRules: Record<string, KlintRule> = {};
   const defaultRulesPath = resolve(configDir, "klint.rules.ts");
@@ -118,15 +132,15 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     { onDebug: debug ? writeDebugEvent : undefined }
   );
 
+  if (engine === "compare") {
+    runCompareEngine({ configDir, fix, json, raw, rulesFile, tsViolations: violations });
+    return;
+  }
+
   if (json) {
-    const errors = violations.filter((v) => v.severity === "error");
-    process.stdout.write(
-      JSON.stringify({
-        violations: violations.map((v) => ({ ...v, fix: v.fix ?? null })),
-        summary: { errors: errors.length, warnings: violations.length - errors.length },
-      })
-    );
-    process.exit(errors.length > 0 ? 2 : 0);
+    const tsResult = toJsonCliResult(violations);
+    process.stdout.write(tsResult.stdout);
+    process.exit(tsResult.status);
   }
 
   if (fix) {
@@ -240,6 +254,83 @@ function runRustEngine({
   process.exit(result.status ?? 1);
 }
 
+function runCompareEngine({
+  configDir,
+  fix,
+  json,
+  raw,
+  rulesFile,
+  tsViolations,
+}: {
+  configDir: string;
+  fix: boolean;
+  json: boolean;
+  raw: {
+    plugins?: string[];
+    rules?: Record<string, RuleConfigValue>;
+    arch?: unknown;
+  };
+  rulesFile?: string;
+  tsViolations: ReturnType<typeof runKlint>;
+}): void {
+  const unsupportedReason = rustEngineUnsupportedReason({
+    fix,
+    json,
+    raw,
+    rulesFile,
+  });
+
+  if (unsupportedReason) {
+    process.stderr.write(`klint: ${unsupportedReason}\n`);
+    process.exit(1);
+  }
+
+  const tsResult = toJsonCliResult(tsViolations);
+  const rustCommand = resolveRustEngineCommand(configDir);
+  const rustResult = spawnSync(rustCommand.bin, rustCommand.args, {
+    cwd: import.meta.dir,
+    encoding: "utf-8",
+  });
+
+  const rustStatus = rustResult.status ?? 1;
+  if (rustResult.stderr) process.stderr.write(rustResult.stderr);
+
+  const tsPayload = parseJsonPayload(tsResult.stdout);
+  const rustPayload = parseJsonPayload(rustResult.stdout);
+
+  if (
+    rustStatus !== tsResult.status ||
+    tsPayload === undefined ||
+    rustPayload === undefined ||
+    !jsonPayloadEquals(tsPayload, rustPayload)
+  ) {
+    const mismatchLines = [
+      "klint: compare engine mismatch",
+      `TypeScript exit: ${tsResult.status}`,
+      `Rust exit: ${rustStatus}`,
+    ];
+    process.stderr.write(`${mismatchLines.join("\n")}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(tsResult.stdout);
+  process.exit(tsResult.status);
+}
+
+function toJsonCliResult(violations: ReturnType<typeof runKlint>): {
+  stdout: string;
+  status: number;
+} {
+  const errors = violations.filter((v) => v.severity === "error");
+  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,
+  };
+}
+
 function writeDebugEvent(event: KlintDebugEvent): void {
   switch (event.type) {
     case "walk:start":
@@ -282,27 +373,31 @@ function resolveRustEngineCommand(configDir: string): RustEngineCommand {
     return { bin: explicitBin, args };
   }
 
-  const nativePackageBin = resolveNativePackageBinary({ packageRoot: import.meta.dir });
-  if (nativePackageBin) {
-    return { bin: nativePackageBin, args };
-  }
-
   const localBin = join(
     import.meta.dir,
     "target",
     "debug",
     process.platform === "win32" ? "klint-rs.exe" : "klint-rs"
   );
-  if (existsSync(localBin)) {
+  if (isSourceCheckout() && existsSync(localBin)) {
     return { bin: localBin, args };
   }
 
+  const nativePackageBin = resolveNativePackageBinary({ packageRoot: import.meta.dir });
+  if (nativePackageBin) {
+    return { bin: nativePackageBin, args };
+  }
+
   return {
     bin: "cargo",
     args: ["run", "--quiet", "-p", "klint-rs", "--", ...args],
   };
 }
 
+function isSourceCheckout(): boolean {
+  return existsSync(join(import.meta.dir, "crates", "klint-rs", "Cargo.toml"));
+}
+
 function rustEngineUnsupportedReason({
   fix,
   json,
@@ -321,14 +416,58 @@ function rustEngineUnsupportedReason({
   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.arch) return "KLINT_ENGINE=rust requires an arch config";
   if ((raw.plugins?.length ?? 0) > 0) return "KLINT_ENGINE=rust does not support plugins";
-  if (Object.values(raw.rules ?? {}).some((value) => value !== "off")) {
-    return "KLINT_ENGINE=rust does not support TypeScript rules";
+  const activeSupportedRules = Object.entries(raw.rules ?? {}).filter(
+    ([name, value]) =>
+      ruleConfigSeverity(value) !== "off" && RUST_SUPPORTED_TYPESCRIPT_RULES.has(name)
+  );
+  const unsupportedRules = Object.entries(raw.rules ?? {})
+    .filter(
+      ([name, value]) =>
+        ruleConfigSeverity(value) !== "off" && !RUST_SUPPORTED_TYPESCRIPT_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 TypeScript rule";
+  }
+  if (unsupportedRules.length > 0) {
+    return [
+      "Rust engine currently supports arch rules and selected TypeScript rules only",
+      "",
+      "Unsupported TypeScript rules:",
+      ...unsupportedRules.map((rule) => `- ${rule}`),
+    ].join("\n");
   }
   return undefined;
 }
 
+function ruleConfigSeverity(value: RuleConfigValue): string | undefined {
+  if (typeof value === "string") return value;
+  return value.severity;
+}
+
+function parseJsonPayload(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+}
+
+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);
+  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)])
+  );
+}
+
 const AGENT_TARGETS = [
   { value: "claude", label: "Claude Code" },
   { value: "opencode", label: "opencode" },
@@ -437,11 +576,12 @@ function printHelp(): void {
     [
       "klint — agent harness for TypeScript architecture rules",
       "",
-      "Usage: klint [--config <dir>] [--rules <file>] [--fix] [--json]",
+      "Usage: klint [--config <dir>] [--rules <file>] [--engine ts|rust|compare] [--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)",
       "  --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.16.0",
+  "version": "0.18.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {

package/rules/no-consecutive-array-push.ts

@@ -26,7 +26,7 @@ export const noConsecutiveArrayPush: KlintRule = {
               statements[runStart].getStart()
             );
             violations.push({
-              file: relative(root, file),
+              file: relative(root, file).replaceAll("\\", "/"),
               line: line + 1,
               message: `${upTo - runStart} consecutive .push() calls on \`${runReceiver}\` — combine into a single .push(a, b, …) call.`,
             });

package/rules/no-nested-template-literals.ts

@@ -32,7 +32,7 @@ function findNestedTemplate(
   if (ts.isTemplateExpression(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
     const { line } = src.getLineAndCharacterOfPosition(node.getStart());
     violations.push({
-      file: relative(root, file),
+      file: relative(root, file).replaceAll("\\", "/"),
       line: line + 1,
       message:
         "Nested template literal — extract the inner template to a variable to improve readability.",

package/rules/no-string-match.ts

@@ -45,7 +45,7 @@ export const noStringMatch: KlintRule = {
                   })()
                 : undefined;
             violations.push({
-              file: relative(root, file),
+              file: relative(root, file).replaceAll("\\", "/"),
               line: s + 1,
               message: `Use RegExp.exec() instead of String.match() for non-global regexes — use new RegExp(${regexText}).exec(${strText}) instead.`,
               fix,

package/rules/no-unguarded-json-parse.ts

@@ -23,7 +23,7 @@ export const noUnguardedJsonParse: KlintRule = {
         ) {
           const { line } = src.getLineAndCharacterOfPosition(node.getStart());
           violations.push({
-            file: relative(root, file),
+            file: relative(root, file).replaceAll("\\", "/"),
             line: line + 1,
             message:
               "JSON.parse() called without a surrounding try/catch — a malformed payload will throw an unhandled exception.",