@konvert7/klint 0.19.2 → 0.21.0

package/README.md

@@ -127,23 +127,30 @@ 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:
 
 - `arch` rules: imports, forbidden patterns, singleton locations
 - `no-unguarded-json-parse`
+- `no-sync-in-async`
 - `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:
 
@@ -280,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,11 +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 {
@@ -105,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 (
@@ -162,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;
   }
 
@@ -245,14 +259,13 @@ function writeTextOutput(
 }
 
 function runRustEngine({
-  configDir,
   fix,
   json,
   raw,
+  root,
   rulesFile,
   startedAt,
 }: {
-  configDir: string;
   fix: boolean;
   json: boolean;
   raw: {
@@ -260,6 +273,7 @@ function runRustEngine({
     rules?: Record<string, RuleConfigValue>;
     arch?: unknown;
   };
+  root: string;
   rulesFile?: string;
   startedAt: number;
 }): void {
@@ -274,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) {
@@ -300,14 +320,13 @@ function runRustEngine({
 }
 
 function runCompareEngine({
-  configDir,
   fix,
   json,
   raw,
+  root,
   rulesFile,
   tsViolations,
 }: {
-  configDir: string;
   fix: boolean;
   json: boolean;
   raw: {
@@ -315,6 +334,7 @@ function runCompareEngine({
     rules?: Record<string, RuleConfigValue>;
     arch?: unknown;
   };
+  root: string;
   rulesFile?: string;
   tsViolations: ReturnType<typeof runKlint>;
 }): void {
@@ -335,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);
@@ -366,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,
@@ -400,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
@@ -433,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;
   }
 
@@ -642,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;
@@ -685,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/core/arch.ts

@@ -1,10 +1,9 @@
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import ts from "typescript";
 import { walkAst } from "./ast";
+import { relativeSlashPath, toSlashPath } from "./paths";
 import type { ArchConfig, Severity, Violation } from "./types";
 
-const toSlash = (p: string) => p.replaceAll("\\", "/");
-
 interface AliasEntry {
   /** The prefix to match (pattern with `/*` stripped, e.g. `"@"` from `"@/*"`). */
   prefix: string;
@@ -31,7 +30,7 @@ function loadPathAliases(root: string): AliasEntry[] {
     const prefix = isWildcard ? pattern.slice(0, -2) : pattern;
     const targetStr = targets[0];
     const targetBase = targetStr.endsWith("/*") ? targetStr.slice(0, -2) : targetStr;
-    entries.push({ prefix, base: toSlash(resolve(base, targetBase)), isWildcard });
+    entries.push({ prefix, base: toSlashPath(resolve(base, targetBase)), isWildcard });
   }
   return entries;
 }
@@ -41,7 +40,7 @@ function resolveAlias(importPath: string, aliases: AliasEntry[]): string | undef
     if (alias.isWildcard) {
       const matchPrefix = `${alias.prefix}/`;
       if (importPath.startsWith(matchPrefix)) {
-        return toSlash(resolve(alias.base, importPath.slice(matchPrefix.length)));
+        return toSlashPath(resolve(alias.base, importPath.slice(matchPrefix.length)));
       }
     } else if (importPath === alias.prefix) {
       return alias.base;
@@ -62,7 +61,7 @@ function isBareSpecifier(path: string): boolean {
 }
 
 function globToPrefix(glob: string, root: string): string {
-  return toSlash(resolve(root, glob.split("/**")[0].split("/*")[0].split("*")[0]));
+  return toSlashPath(resolve(root, glob.split("/**")[0].split("/*")[0].split("*")[0]));
 }
 
 function resolveGlobs(
@@ -145,7 +144,7 @@ function scanImports(
     if (isBareSpecifier(path)) {
       resolved = resolveAlias(path, aliases) ?? path;
     } else {
-      resolved = toSlash(resolve(fileDir, path));
+      resolved = toSlashPath(resolve(fileDir, path));
     }
     const { line } = src.getLineAndCharacterOfPosition(specifierNode.getStart());
     records.push({ path, resolved, isTypeOnly, line: line + 1 });
@@ -176,7 +175,7 @@ export function runArchRules(
         if (isBareSpecifier(imp.resolved)) continue;
         if (rule["type-only"] === "allow" && imp.isTypeOnly) continue;
 
-        const relFile = relative(root, file).replaceAll("\\", "/");
+        const relFile = relativeSlashPath(root, file);
 
         if (rule.deny !== undefined) {
           const denyPrefixes = resolveLayerPrefixes(rule.deny, layers, root);
@@ -235,7 +234,7 @@ export function runArchRules(
 
   for (const rule of arch.singleton ?? []) {
     const severity: Severity = rule.severity ?? "error";
-    const onlyFile = toSlash(resolve(root, rule.only));
+    const onlyFile = toSlashPath(resolve(root, rule.only));
     const inFiles = rule.in
       ? resolveLayerFiles(rule.in, layers, root, allFiles)
       : allFiles;
@@ -294,7 +293,7 @@ function scanJsxElements(
       if (!targets.has(tagName.text)) return;
       const { line } = src.getLineAndCharacterOfPosition(tagName.getStart());
       violations.push({
-        file: relative(root, file).replaceAll("\\", "/"),
+        file: relativeSlashPath(root, file),
         line: line + 1,
         message,
         rule: ruleName,
@@ -321,7 +320,7 @@ function scanLinesForPattern(
     for (let i = 0; i < lines.length; i++) {
       if (lines[i].includes(pattern)) {
         violations.push({
-          file: relative(root, file).replaceAll("\\", "/"),
+          file: relativeSlashPath(root, file),
           line: i + 1,
           message,
           rule: ruleName,

package/core/paths.ts

@@ -0,0 +1,9 @@
+import { relative } from "node:path";
+
+export function toSlashPath(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+export function relativeSlashPath(from: string, to: string): string {
+  return toSlashPath(relative(from, to));
+}

package/core/rule-helpers.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { createProgram } from "./ast";
+import { relativeSlashPath } from "./paths";
 import type { KlintRule, RawViolation, RuleMeta } from "./types";
 import { defineRule } from "./types";
 
@@ -34,7 +34,7 @@ export function defineAstRule(opts: {
           report(node, message) {
             const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
             violations.push({
-              file: relative(root, sourceFile.fileName),
+              file: relativeSlashPath(root, sourceFile.fileName),
               line: line + 1,
               message,
             });

package/core/runner.ts

@@ -1,9 +1,10 @@
 import { readdirSync, readFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { BUILT_IN_PLUGINS } from "../plugins/index";
 import { BUILT_IN_RULES } from "../rules/index";
 import { runArchRules } from "./arch";
 import { clearAstCache } from "./ast";
+import { relativeSlashPath, toSlashPath } from "./paths";
 import type {
   KlintConfig,
   KlintRule,
@@ -29,7 +30,7 @@ function walk(dir: string, root: string, excludes: string[] = []): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const full = join(dir, entry.name);
-    const rel = relative(root, full).replaceAll("\\", "/");
+    const rel = relativeSlashPath(root, full);
     if (entry.isDirectory()) {
       if (
         excludes.some(
@@ -38,8 +39,7 @@ function walk(dir: string, root: string, excludes: string[] = []): string[] {
       )
         continue;
       out.push(...walk(full, root, excludes));
-    } else if (/\.(tsx?|jsx?|mts|cts)$/.test(entry.name))
-      out.push(full.replaceAll("\\", "/"));
+    } else if (/\.(tsx?|jsx?|mts|cts)$/.test(entry.name)) out.push(toSlashPath(full));
   }
   return out;
 }
@@ -68,8 +68,8 @@ function resolveFiles(
 }
 
 function matchPattern(relPath: string, pattern: string): boolean {
-  const norm = relPath.replaceAll("\\", "/");
-  const p = pattern.replaceAll("\\", "/");
+  const norm = toSlashPath(relPath);
+  const p = toSlashPath(pattern);
   if (p === "." || p === "**") return true;
   if (!p.includes("*")) return norm === p || norm.startsWith(`${p}/`);
   return globToRegExp(p).test(norm);
@@ -107,7 +107,7 @@ function applyPatterns(files: string[], patterns: string[], root: string): strin
   const includes = patterns.filter((p) => !p.startsWith("!"));
   const excludes = patterns.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
   return files.filter((file) => {
-    const rel = relative(root, file).replaceAll("\\", "/");
+    const rel = relativeSlashPath(root, file);
     const included = includes.length === 0 || includes.some((p) => matchPattern(rel, p));
     const excluded = excludes.some((p) => matchPattern(rel, p));
     return included && !excluded;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.19.2",
+  "version": "0.21.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.19.2",
-    "@konvert7/klint-darwin-x64": "0.19.2",
-    "@konvert7/klint-linux-x64": "0.19.2",
-    "@konvert7/klint-win32-x64": "0.19.2"
+    "@konvert7/klint-darwin-arm64": "0.21.0",
+    "@konvert7/klint-darwin-x64": "0.21.0",
+    "@konvert7/klint-linux-x64": "0.21.0",
+    "@konvert7/klint-win32-x64": "0.21.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

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

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import type { KlintRule } from "../core/types";
 
 export const noConsecutiveArrayPush: KlintRule = {
@@ -26,7 +26,7 @@ export const noConsecutiveArrayPush: KlintRule = {
               statements[runStart].getStart()
             );
             violations.push({
-              file: relative(root, file).replaceAll("\\", "/"),
+              file: relativeSlashPath(root, file),
               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

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import type { KlintRule } from "../core/types";
 
 export const noNestedTemplateLiterals: KlintRule = {
@@ -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).replaceAll("\\", "/"),
+      file: relativeSlashPath(root, file),
       line: line + 1,
       message:
         "Nested template literal — extract the inner template to a variable to improve readability.",

package/rules/no-object-in-template.ts

@@ -87,7 +87,7 @@ function wouldRenderAsObjectObject(type: ts.Type, checker: ts.TypeChecker): bool
     const fileName = d.getSourceFile().fileName;
     return (
       !fileName.includes("/typescript/lib/lib") &&
-      !fileName.includes("\\typescript\\lib\\lib")
+      !fileName.includes(String.raw`\typescript\lib\lib`)
     );
   });
 

package/rules/no-single-char-class.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
@@ -99,7 +99,7 @@ export const noSingleCharClass: KlintRule = {
         const fix = buildNodeReplacementFix(src, node, fixedRegex);
 
         violations.push({
-          file: relative(root, file),
+          file: relativeSlashPath(root, file),
           line: fix.startLine,
           message: `Character class [${toFix[0].inner}] contains a single element — remove the brackets.`,
           fix,

package/rules/no-string-match.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import type { KlintRule } from "../core/types";
 
 export const noStringMatch: KlintRule = {
@@ -45,7 +45,7 @@ export const noStringMatch: KlintRule = {
                   })()
                 : undefined;
             violations.push({
-              file: relative(root, file).replaceAll("\\", "/"),
+              file: relativeSlashPath(root, file),
               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-sync-in-async.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { nearestFunctionIsAsync, walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import type { KlintRule } from "../core/types";
 
 export const noSyncInAsync: KlintRule = {
@@ -31,7 +31,7 @@ export const noSyncInAsync: KlintRule = {
           ) {
             const { line } = src.getLineAndCharacterOfPosition(node.getStart());
             violations.push({
-              file: relative(root, file),
+              file: relativeSlashPath(root, file),
               line: line + 1,
               message: `${name}() blocks the event loop inside an async function — use the async equivalent from node:fs/promises.`,
             });

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

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { isInsideTry, walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import type { KlintRule } from "../core/types";
 
 export const noUnguardedJsonParse: KlintRule = {
@@ -23,7 +23,7 @@ export const noUnguardedJsonParse: KlintRule = {
         ) {
           const { line } = src.getLineAndCharacterOfPosition(node.getStart());
           violations.push({
-            file: relative(root, file).replaceAll("\\", "/"),
+            file: relativeSlashPath(root, file),
             line: line + 1,
             message:
               "JSON.parse() called without a surrounding try/catch — a malformed payload will throw an unhandled exception.",

package/rules/prefer-at.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
@@ -35,7 +35,7 @@ export const preferAt: KlintRule = {
         const fix = buildNodeReplacementFix(src, node, fixedCall);
 
         violations.push({
-          file: relative(root, file),
+          file: relativeSlashPath(root, file),
           line: fix.startLine,
           message: `Prefer ${baseText}.at(-${n}) over ${baseText}[${baseText}.length - ${n}] for cleaner negative indexing.`,
           fix,

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

@@ -1,30 +1,25 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 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);
@@ -33,9 +28,9 @@ export const preferNullishCoalescingAssign: KlintRule = {
         const indent = getIndent(src, node);
 
         violations.push({
-          file: relative(root, file),
+          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/rules/prefer-string-raw-regexp.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import type { KlintRule } from "../core/types";
 
 export const preferStringRawRegexp: KlintRule = {
@@ -47,7 +47,7 @@ export const preferStringRawRegexp: KlintRule = {
           linesText.slice(0, argOffset) + fixedArg + linesText.slice(argEndOffset);
 
         violations.push({
-          file: relative(root, file),
+          file: relativeSlashPath(root, file),
           line: line + 1,
           message:
             "Use String.raw`...` for RegExp template argument to avoid double backslashes (Sonar S7780).",

package/rules/prefer-string-raw.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
@@ -27,7 +27,7 @@ export const preferStringRaw: KlintRule = {
         const fix = buildNodeReplacementFix(src, node, fixedNode);
 
         violations.push({
-          file: relative(root, file),
+          file: relativeSlashPath(root, file),
           line: fix.startLine,
           message:
             "String literal with escaped backslashes — use String.raw`...` for clarity (Sonar S6535).",

package/rules/prefer-string-replaceall.ts

@@ -1,6 +1,6 @@
-import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { relativeSlashPath } from "../core/paths";
 import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
@@ -35,13 +35,13 @@ export const preferStringReplaceall: KlintRule = {
         ).expression.getText(src);
         const replacementText = node.arguments[1].getText(src);
         const patternLit = pattern.includes('"')
-          ? `'${pattern.replaceAll("'", "\\'")}'`
+          ? `'${pattern.replaceAll("'", String.raw`\'`)}'`
           : `"${pattern}"`;
         const fixedCall = `${strText}.replaceAll(${patternLit}, ${replacementText})`;
         const fix = buildNodeReplacementFix(src, node, fixedCall);
 
         violations.push({
-          file: relative(root, file),
+          file: relativeSlashPath(root, file),
           line: fix.startLine,
           message: `Prefer \`${strText}.replaceAll(${patternLit}, ...)\` over \`.replace(/${pattern}/g, ...)\` — replaceAll() with a string is clearer and avoids regex escaping pitfalls.`,
           fix,

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

@@ -28,22 +28,31 @@ 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);
 }
 
-export async function publish(_, context) {
+export async function publish(pluginConfig = {}, context) {
   const cwd = context.cwd ?? process.cwd();
+  const spawn = pluginConfig.spawnSync ?? spawnSync;
+  const version = context.nextRelease?.version;
 
   if (context.options?.dryRun) {
     context.logger?.log("Dry run: skipping npm publish");
     return;
   }
 
-  const result = spawnSync("npm", ["publish", "--access", "public"], {
+  if (!version) {
+    throw new Error("semantic-release did not provide nextRelease.version");
+  }
+
+  const packageJson = readPackageJson(cwd);
+  packageJson.optionalDependencies ??= {};
+  for (const packageName of NATIVE_PACKAGE_NAMES) {
+    packageJson.optionalDependencies[packageName] = version;
+  }
+  writePackageJson(cwd, packageJson);
+
+  const result = spawn("npm", ["publish", "--access", "public"], {
     cwd,
     encoding: "utf-8",
     stdio: "inherit",