@konvert7/klint 0.20.0 → 0.22.0

package/README.md

@@ -127,14 +127,14 @@ Maintainer migration notes live in [`docs/rust-engine.md`](docs/rust-engine.md).
 | `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 |
+| `auto` | Runs Rust-supported rules in Rust, TS-only rules and unsupported plugin defaults 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
+klint --engine rust --json     # strict Rust-only run; rejects unsupported rules
+klint --engine compare --json  # parity check; rejects unsupported rules
 ```
 
 Rust currently supports:
@@ -145,6 +145,12 @@ Rust currently supports:
 - `no-nested-template-literals`
 - `no-consecutive-array-push`
 - `no-string-match`
+- `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`
 
 These rules remain TypeScript-owned because they need TypeScript semantic information:
 
@@ -281,8 +287,8 @@ arch:
 | `no-sync-in-async` | No | Sync filesystem calls inside async functions |
 | `no-floating-promise` | Yes | Promise-returning call whose result is discarded |
 | `no-misused-promises` | Yes | Async function passed where a sync callback is expected |
-| `no-async-predicate` | No | Async predicate passed to array filtering/search methods |
-| `no-date-equality` | No | Date values compared by object identity |
+| `no-async-predicate` | Yes | Async predicate passed to array filtering/search methods |
+| `no-date-equality` | Yes | Date values compared by object identity |
 | `no-optional-chain-on-non-nullable` | Yes | Optional chaining on values TypeScript knows are non-nullable |
 | `no-object-in-template` | Yes | Object values interpolated into template strings |
 | `no-nested-template-literals` | No | Template literals nested inside template literals |

package/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { spawnSync } from "node:child_process";
+import { type SpawnSyncReturns, spawnSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -27,12 +27,18 @@ import type {
 import { BUILT_IN_PLUGINS } from "./plugins/index";
 import { BUILT_IN_RULES } from "./rules/index";
 
-const RUST_SUPPORTED_TYPESCRIPT_RULES = new Set([
+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",
 ]);
 
 interface CliOptions {
@@ -106,7 +112,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   const root = resolve(configDir, raw.root ?? ".");
 
   if (engine === "rust") {
-    runRustEngine({ configDir, fix, json, raw, rulesFile, startedAt });
+    runRustEngine({ fix, json, raw, root, rulesFile, startedAt });
     return;
   }
   if (
@@ -163,7 +169,14 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   );
 
   if (engine === "compare") {
-    runCompareEngine({ configDir, fix, json, raw, rulesFile, tsViolations: violations });
+    runCompareEngine({
+      fix,
+      json,
+      raw,
+      root,
+      rulesFile,
+      tsViolations: violations,
+    });
     return;
   }
 
@@ -246,14 +259,13 @@ function writeTextOutput(
 }
 
 function runRustEngine({
-  configDir,
   fix,
   json,
   raw,
+  root,
   rulesFile,
   startedAt,
 }: {
-  configDir: string;
   fix: boolean;
   json: boolean;
   raw: {
@@ -261,6 +273,7 @@ function runRustEngine({
     rules?: Record<string, RuleConfigValue>;
     arch?: unknown;
   };
+  root: string;
   rulesFile?: string;
   startedAt: number;
 }): void {
@@ -275,16 +288,22 @@ function runRustEngine({
     process.exit(1);
   }
 
-  const command = resolveRustEngineCommand(configDir);
-  if (process.argv.includes("--debug") || process.argv.includes("-debug")) {
-    process.stderr.write(
-      `[klint:debug] rust engine: ${command.bin} ${command.args.join(" ")}\n`
-    );
+  const { configDir: rustConfigDir, cleanup } = writeRustEngineConfig({ raw, root });
+  const command = resolveRustEngineCommand(rustConfigDir);
+  let result: SpawnSyncReturns<string>;
+  try {
+    if (process.argv.includes("--debug") || process.argv.includes("-debug")) {
+      process.stderr.write(
+        `[klint:debug] rust engine: ${command.bin} ${command.args.join(" ")}\n`
+      );
+    }
+    result = spawnSync(command.bin, command.args, {
+      cwd: import.meta.dir,
+      encoding: "utf-8",
+    });
+  } finally {
+    cleanup();
   }
-  const result = spawnSync(command.bin, command.args, {
-    cwd: import.meta.dir,
-    encoding: "utf-8",
-  });
 
   if (result.stderr) process.stderr.write(result.stderr);
   if (json) {
@@ -301,14 +320,13 @@ function runRustEngine({
 }
 
 function runCompareEngine({
-  configDir,
   fix,
   json,
   raw,
+  root,
   rulesFile,
   tsViolations,
 }: {
-  configDir: string;
   fix: boolean;
   json: boolean;
   raw: {
@@ -316,6 +334,7 @@ function runCompareEngine({
     rules?: Record<string, RuleConfigValue>;
     arch?: unknown;
   };
+  root: string;
   rulesFile?: string;
   tsViolations: ReturnType<typeof runKlint>;
 }): void {
@@ -336,11 +355,17 @@ function runCompareEngine({
   }
 
   const tsResult = toJsonCliResult(tsViolations);
-  const rustCommand = resolveRustEngineCommand(configDir);
-  const rustResult = spawnSync(rustCommand.bin, rustCommand.args, {
-    cwd: import.meta.dir,
-    encoding: "utf-8",
-  });
+  const { configDir: rustConfigDir, cleanup } = writeRustEngineConfig({ raw, root });
+  const rustCommand = resolveRustEngineCommand(rustConfigDir);
+  let rustResult: SpawnSyncReturns<string>;
+  try {
+    rustResult = spawnSync(rustCommand.bin, rustCommand.args, {
+      cwd: import.meta.dir,
+      encoding: "utf-8",
+    });
+  } finally {
+    cleanup();
+  }
 
   const rustStatus = rustResult.status ?? 1;
   if (rustResult.stderr) process.stderr.write(rustResult.stderr);
@@ -367,6 +392,35 @@ function runCompareEngine({
   process.exit(tsResult.status);
 }
 
+function writeRustEngineConfig({
+  raw,
+  root,
+}: {
+  raw: {
+    include?: string[];
+    plugins?: string[];
+    rules?: Record<string, RuleConfigValue>;
+    arch?: unknown;
+  };
+  root: string;
+}): { configDir: string; cleanup: () => void } {
+  const tempDir = mkdtempSync(join(tmpdir(), "klint-rust-engine-"));
+  writeFileSync(
+    join(tempDir, "klint.config.json"),
+    JSON.stringify({
+      root,
+      include: raw.include ?? ["."],
+      plugins: [],
+      rules: resolveEffectiveRules(raw.plugins, raw.rules ?? {}),
+      arch: raw.arch,
+    })
+  );
+  return {
+    configDir: tempDir,
+    cleanup: () => rmSync(tempDir, { recursive: true, force: true }),
+  };
+}
+
 function runAutoEngine({
   fix,
   json,
@@ -401,12 +455,13 @@ function runAutoEngine({
     process.exit(1);
   }
 
-  const { rustRules, tsRules } = splitRulesForAuto(raw.rules ?? {});
+  const effectiveRules = resolveEffectiveRules(raw.plugins, raw.rules ?? {});
+  const { rustRules, tsRules } = splitRulesForAuto(effectiveRules);
   const tsViolations = runKlint(
     {
       root,
       include: raw.include ?? ["."],
-      plugins: raw.plugins,
+      plugins: [],
       rules: { ...customRulesMap, ...tsRules },
     },
     customRules
@@ -434,7 +489,7 @@ function splitRulesForAuto(rules: 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;
+    if (RUST_SUPPORTED_RULES.has(name)) rustRules[name] = value;
     else tsRules[name] = value;
   }
 
@@ -643,31 +698,51 @@ function rustEngineUnsupportedReason({
 }): string | undefined {
   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";
-  const activeSupportedRules = Object.entries(raw.rules ?? {}).filter(
+  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_TYPESCRIPT_RULES.has(name)
+      ruleConfigSeverity(value) !== "off" && RUST_SUPPORTED_RULES.has(name)
   );
-  const unsupportedRules = Object.entries(raw.rules ?? {})
+  const unsupportedRules = Object.entries(effectiveRules)
     .filter(
       ([name, value]) =>
-        ruleConfigSeverity(value) !== "off" && !RUST_SUPPORTED_TYPESCRIPT_RULES.has(name)
+        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 TypeScript rule";
+    return "KLINT_ENGINE=rust requires an arch config or supported rule";
   }
   if (unsupportedRules.length > 0) {
     return [
-      "Rust engine currently supports arch rules and selected TypeScript rules only",
+      "Rust engine currently supports arch rules and selected rules only",
       "",
-      "Unsupported TypeScript rules:",
+      "Unsupported rules:",
       ...unsupportedRules.map((rule) => `- ${rule}`),
     ].join("\n");
   }
   return undefined;
 }
 
+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 };
+}
+
 function ruleConfigSeverity(value: RuleConfigValue): string | undefined {
   if (typeof value === "string") return value;
   return value.severity;
@@ -686,7 +761,11 @@ function jsonPayloadEquals(a: unknown, b: unknown): boolean {
 }
 
 function canonicalJson(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(canonicalJson);
+  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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -40,6 +40,8 @@
     "pack:check": "bun tests/pack-check.ts",
     "native:stage": "bun tests/stage-native-binary.ts",
     "native:smoke": "bun tests/smoke-native-binary.ts",
+    "python:stage": "bun tests/stage-python-wheel.ts",
+    "python:smoke": "bun tests/smoke-python-wheel.ts",
     "native:release:dry-run": "bun tools/prepare-native-release.ts --version 0.0.0-dry-run",
     "check": "biome check",
     "check-write": "biome check --write",
@@ -62,10 +64,10 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "0.20.0",
-    "@konvert7/klint-darwin-x64": "0.20.0",
-    "@konvert7/klint-linux-x64": "0.20.0",
-    "@konvert7/klint-win32-x64": "0.20.0"
+    "@konvert7/klint-darwin-arm64": "0.22.0",
+    "@konvert7/klint-darwin-x64": "0.22.0",
+    "@konvert7/klint-linux-x64": "0.22.0",
+    "@konvert7/klint-win32-x64": "0.22.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

package/rules/prefer-nullish-coalescing-assign.ts

@@ -6,25 +6,20 @@ import type { KlintRule } from "../core/types";
 export const preferNullishCoalescingAssign: KlintRule = {
   meta: {
     description:
-      "Flags `x = x ?? y` patterns — `x ??= y` is the dedicated nullish assignment operator.",
+      "Flags explicit nullish assignment guards — `x ??= y` is the dedicated nullish assignment operator.",
     examples: ["sonar/prefer-nullish-coalescing-assign: warn"],
   },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";
       walkAst(file, content, (node, src) => {
-        if (
-          !ts.isIfStatement(node) ||
-          node.elseStatement !== undefined ||
-          !ts.isPrefixUnaryExpression(node.expression) ||
-          node.expression.operator !== ts.SyntaxKind.ExclamationToken
-        )
-          return;
+        if (!ts.isIfStatement(node) || node.elseStatement !== undefined) return;
 
         const assignExpr = extractAssignment(node.thenStatement);
         if (!assignExpr) return;
 
-        const xText = node.expression.operand.getText(src);
+        const xText = nullishGuardTarget(node.expression, src);
+        if (!xText) return;
         if (assignExpr.left.getText(src) !== xText) return;
 
         const yText = assignExpr.right.getText(src);
@@ -35,7 +30,7 @@ export const preferNullishCoalescingAssign: KlintRule = {
         violations.push({
           file: relativeSlashPath(root, file),
           line: s + 1,
-          message: `Prefer \`${xText} ??= ${yText}\` over \`if (!${xText}) ${xText} = ${yText}\` — ??= only assigns when null or undefined.`,
+          message: `Prefer \`${xText} ??= ${yText}\` over explicit nullish guard assignment — ??= only assigns when null or undefined.`,
           fix: {
             startLine: s + 1,
             endLine: e + 1,
@@ -66,6 +61,49 @@ function isAssign(node: ts.Expression): node is ts.BinaryExpression {
   );
 }
 
+function nullishGuardTarget(
+  expression: ts.Expression,
+  src: ts.SourceFile
+): string | undefined {
+  if (!ts.isBinaryExpression(expression)) return undefined;
+
+  const direct = equalityNullishTarget(expression, src);
+  if (direct) return direct.target;
+
+  if (expression.operatorToken.kind !== ts.SyntaxKind.BarBarToken) return undefined;
+
+  const left = equalityNullishTarget(expression.left, src);
+  const right = equalityNullishTarget(expression.right, src);
+  if (!left || !right || left.target !== right.target) return undefined;
+
+  const values = new Set([left.value, right.value]);
+  if (values.has("null") && values.has("undefined")) return left.target;
+  return undefined;
+}
+
+function equalityNullishTarget(
+  expression: ts.Expression,
+  src: ts.SourceFile
+): { target: string; value: "null" | "undefined" } | undefined {
+  if (!ts.isBinaryExpression(expression)) return undefined;
+
+  const operator = expression.operatorToken.kind;
+  if (
+    operator !== ts.SyntaxKind.EqualsEqualsToken &&
+    operator !== ts.SyntaxKind.EqualsEqualsEqualsToken
+  )
+    return undefined;
+
+  const left = expression.left.getText(src);
+  const right = expression.right.getText(src);
+
+  if (right === "null") return { target: left, value: "null" };
+  if (right === "undefined") return { target: left, value: "undefined" };
+  if (left === "null") return { target: right, value: "null" };
+  if (left === "undefined") return { target: right, value: "undefined" };
+  return undefined;
+}
+
 function getIndent(src: ts.SourceFile, node: ts.Node): string {
   const { line } = src.getLineAndCharacterOfPosition(node.getStart());
   const lineStart = src.getPositionOfLineAndCharacter(line, 0);

package/tools/prepare-python-release.ts

@@ -0,0 +1,76 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+interface Options {
+  name: string;
+  root: string;
+  version: string;
+}
+
+const repoRoot = fileURLToPath(new URL("..", import.meta.url));
+const options = parseArgs();
+const pythonRoot = join(options.root, "python");
+const pyprojectPath = join(pythonRoot, "pyproject.toml");
+const initPath = join(pythonRoot, "klint", "__init__.py");
+
+const pyproject = readFileSync(pyprojectPath, "utf-8");
+const nextPyproject = replaceRequired(
+  replaceRequired(pyproject, /^name = ".+"$/m, `name = "${options.name}"`, pyprojectPath),
+  /^version = ".+"$/m,
+  `version = "${options.version}"`,
+  pyprojectPath
+);
+writeFileSync(pyprojectPath, nextPyproject);
+
+const init = readFileSync(initPath, "utf-8");
+const nextInit = replaceRequired(
+  init,
+  /^__version__ = ".+"$/m,
+  `__version__ = "${options.version}"`,
+  initPath
+);
+writeFileSync(initPath, nextInit);
+
+process.stdout.write(
+  `prepared Python release metadata: ${options.name}@${options.version}\n`
+);
+
+function parseArgs(): Options {
+  const args = process.argv.slice(2);
+  const name = valueAfter(args, "--name");
+  const version = valueAfter(args, "--version");
+  if (!name || !version) {
+    fail(
+      "Usage: bun tools/prepare-python-release.ts --name <package-name> --version <version> [--root <repo-root>]"
+    );
+  }
+
+  return {
+    name,
+    version,
+    root: resolve(valueAfter(args, "--root") ?? repoRoot),
+  };
+}
+
+function replaceRequired(
+  input: string,
+  pattern: RegExp,
+  replacement: string,
+  path: string
+): string {
+  if (!pattern.test(input)) {
+    fail(`Expected release metadata pattern ${pattern} in ${path}`);
+  }
+  return input.replace(pattern, replacement);
+}
+
+function valueAfter(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}