@konvert7/klint 1.3.1 → 1.4.1

package/README.md

@@ -53,11 +53,12 @@ Then create `klint.yaml` in your project root.
 include: ["src", "!**/node_modules/**"]
 
 rules:
-  no-async-predicate: error
-  no-unguarded-json-parse: error
-  no-sync-in-async:
-    severity: error
-    include: ["src/hooks/**"]
+  core:
+    no-async-predicate: error
+    no-unguarded-json-parse: error
+    no-sync-in-async:
+      severity: error
+      include: ["src/hooks/**"]
 
 arch:
   layers:
@@ -121,6 +122,7 @@ Rules give agents room to move quickly because the unsafe moves are blocked stru
 ```sh
 klint [--config <dir>] [--fix] [--json] [--hook]
 klint stats [--config <dir>]
+klint migrate [--config <dir>] [--check]
 klint install-skill [--agents <list>] [--symlink | --copy] [--force]
 ```
 
@@ -130,6 +132,8 @@ klint install-skill [--agents <list>] [--symlink | --copy] [--force]
 | `--fix` | Apply auto-fixes for fixable violations in-place |
 | `--json` | Emit structured JSON to stdout for agents and CI |
 | `--hook` | Count this run as an agent hook run in `klint stats` |
+| `migrate` | Rewrite a v1 config to the v2 rule groups in place, keeping comments and blank lines |
+| `migrate --check` | Exit 1 when the config is v1 and 0 when it is v2; never writes |
 
 `klint install-skill` installs the bundled rule-authoring skill for agent environments:
 
@@ -224,15 +228,17 @@ The npm package needs Node.js 18+ and no longer installs `typescript`, `zod`, `y
 # yaml-language-server: $schema=./klint.schema.yaml
 
 include: ["src", "!**/node_modules/**"]
-plugins: [sonar]
 
 rules:
-  no-unguarded-json-parse: error
-  no-async-predicate: error
-  sonar/prefer-string-replaceall: warn
-  no-sync-in-async:
-    severity: error
-    include: ["src/server/**"]
+  recommended: true
+  core:
+    no-unguarded-json-parse: error
+    no-async-predicate: error
+    no-sync-in-async:
+      severity: error
+      include: ["src/server/**"]
+  sonar:
+    prefer-string-replaceall: warn
 
 arch:
   layers:
@@ -247,9 +253,15 @@ arch:
 
 `include` selects source files to lint. Patterns support `**` globs and `!` negation.
 
-`plugins` enables bundled rule groups. Today, `sonar` provides focused code-quality rules.
+`rules` has three parts. Each rule is `"error"`, `"warn"`, `"off"`, or an options object with `severity` and/or `include`.
+
+- `recommended: true` enables the six sonar rules at `error`.
+- `core` holds the built-in rules, by name.
+- `sonar` holds the sonar rules, by name without the `sonar/` prefix. An entry here overrides `recommended`.
+
+The rule ids in the output stay `sonar/…`, for example `sonar/prefer-at`.
 
-`rules` maps rule names to `"error"`, `"warn"`, `"off"`, or an options object with `severity` and/or `include`.
+**v1 still works.** The flat map under `rules` (with `sonar/` prefixes) and `plugins: [sonar]` are still read. A v1 config gets one `klint/config` warning. `klint migrate` or `klint --fix` upgrades it in place and keeps comments, blank lines and key order. It refuses, naming the line, when it cannot do that safely: YAML anchors, aliases, tags, a flow-map `rules`, duplicate keys, or a config that mixes v1 and v2 keys. A mixed config is read as v2 and the v1 entries are ignored, with one warning.
 
 `arch` declares architecture constraints without writing a custom rule.
 
@@ -733,7 +745,7 @@ doc-comments alongside `/** */`.
 | `no-string-match` | `String#match()` usage better expressed with clearer APIs |
 | `blank-line-before-control-flow` | Blank line above a control-flow statement that follows another statement; autofix |
 | `blank-line-after-block` | Blank line below a block statement when another statement follows; autofix |
-| `cognitive-complexity` | Function whose cognitive complexity (Biome / SonarSource model) is above `max`, in all five languages; opt-in, no autofix |
+| `cognitive-complexity` | Function whose cognitive complexity (SonarJS / SonarSource model) is above `max`, in all five languages; opt-in, no autofix |
 | `function-length` | Function whose body has more lines than `max` (counted like Biome's `noExcessiveLinesPerFunction`), in all five languages; opt-in, no autofix |
 
 Rules that needed TypeScript's type checker were removed in 1.0; see [Upgrading from klint 0.x](#upgrading-from-klint-0x).
@@ -744,21 +756,23 @@ Rules that needed TypeScript's type checker were removed in 1.0; see [Upgrading
 
 ```yaml
 rules:
-  blank-line-before-control-flow: error
-  blank-line-after-block: warn
+  core:
+    blank-line-before-control-flow: error
+    blank-line-after-block: warn
 ```
 
 ```yaml
 rules:
-  blank-line-before-control-flow:
-    severity: error
-    include: ["src/**", "!src/generated/**"]
-    statements: [if, for, while, switch, try, return, guard, loop, with]
-    allowSetup: true
-  blank-line-after-block:
-    severity: warn
-    include: ["src/**"]
-    statements: [if, for, while, switch, try, guard, loop, with]
+  core:
+    blank-line-before-control-flow:
+      severity: error
+      include: ["src/**", "!src/generated/**"]
+      statements: [if, for, while, switch, try, return, guard, loop, with]
+      allowSetup: true
+    blank-line-after-block:
+      severity: warn
+      include: ["src/**"]
+      statements: [if, for, while, switch, try, guard, loop, with]
 ```
 
 - `statements` lists the statement kinds a rule targets. The default is every kind the rule supports. `statements: []` turns the rule off. `match` is an alias of `switch`. `return` is valid only for `blank-line-before-control-flow`. An unknown keyword, or `return` on the after rule, produces one `klint/config` warning, and the remaining keywords still apply.
@@ -786,56 +800,59 @@ rules:
 
 ### Cognitive complexity
 
-`cognitive-complexity` reports every function whose cognitive complexity is above `max`, in TypeScript/JavaScript, Python, Swift, Rust and C#. It is opt-in and has no fix. It uses Biome 2.6.5's `noExcessiveCognitiveComplexity` scoring (the SonarSource Cognitive Complexity model, G. Ann Campbell 2017) for every language, so a TypeScript function gets the same score as in Biome.
+`cognitive-complexity` reports every function whose cognitive complexity is above `max`, in TypeScript/JavaScript, Python, Swift, Rust and C#. It is opt-in and has no fix. It scores like SonarSource's own implementation, `eslint-plugin-sonarjs` 3.0.5 rule S3776 (the SonarSource Cognitive Complexity model, G. Ann Campbell 2017), for every language, so a TypeScript function gets the same score as in SonarJS.
 
 ```yaml
 rules:
-  cognitive-complexity: error
+  core:
+    cognitive-complexity: error
 ```
 
 ```yaml
 rules:
-  cognitive-complexity:
-    severity: warn
-    include: ["src/**", "!src/generated/**"]
-    max: 14
+  core:
+    cognitive-complexity:
+      severity: warn
+      include: ["src/**", "!src/generated/**"]
+      max: 14
 ```
 
 - `max` is an integer of at least 1, default 15. A function is reported when its score is **greater than** `max`. Any other value (0, a negative number, a fraction, a string) gives one `klint/config` warning naming the rule and the value, and the rule uses 15.
 - The message has the form ``Function `big` has cognitive complexity 16 (max 15) — split it into smaller functions.``. The name is the declared name. For an anonymous function assigned to a variable or property it is that name. Otherwise it is `<anonymous>`. The line is the function's first line.
 - Each function starts at 0. Top-level code is not scored.
 
-**Scoring.** "Nesting" is how deep a construct sits: each enclosing `if`, loop, `switch`, `catch`, `guard`, `let … else` body and each enclosing function adds one.
+**Scoring.** "Nesting" is how deep a construct sits: nesting is added by each enclosing `if`, loop, `switch`, `catch`, `guard` and `let … else` body; a nested function starts again at 0. Only a construct's body is nested: its condition, loop head, `switch` value or ternary test sits at the construct's own nesting. For example, in `if (a ? b : c) {}` the ternary adds 1, not 2.
 
 | Increment | TypeScript / JavaScript | Python | Swift | Rust | C# |
 |---|---|---|---|---|---|
-| +1 plus nesting: `if`, and `else if` (which also gets the nesting) | `if`, `else if` | `if`, `elif` | `if`, `else if` | `if`, `if let`, `else if` | `if`, `else if` |
+| +1 plus nesting: `if` | `if` | `if` | `if`, `if let` | `if` |
+| +1, no nesting: `else if` (its body is nested like the `if` body) | `else if` | `elif` | `else if` | `else if` | `else if` |
 | +1 plus nesting: ternary | `?:` | `x if c else y` | `?:` | — | `?:` |
 | +1 plus nesting: switch / match | `switch` | `match` | `switch` | `match` | `switch` statement, `switch` expression |
 | +1 plus nesting: loops | `for`, `for…in`, `for…of`, `while`, `do…while` | `for`, `while` | `for`, `while`, `repeat…while` | `for`, `while`, `while let`, `loop` | `for`, `foreach`, `while`, `do` |
 | +1 plus nesting: `catch` | `catch` | `except` | `catch` | — | `catch` |
 | +1 plus nesting: `guard`, `let … else` (its `else` body is nested) | — | — | `guard` | `let … else` | — |
-| +1, no nesting: `finally` (its body is not nested) | `finally` | `finally` | — | — | `finally` |
-| nesting only: nested function (scored on its own, see below) | arrow, function expression, function declaration, method | `lambda`, `def` | closure | closure | lambda, local function, anonymous method |
+| no increment: nested function (scored on its own, starting at nesting 0) | arrow, function expression, function declaration, method | `lambda`, `def` | closure | closure | lambda, local function, anonymous method |
 | +1, no nesting: plain `else` (not `else if`/`elif`) | `else` | `else` of `if`, `try`, `for`, `while` | `else` | `else` | `else` |
 | +1: labeled `break` / `continue`, `goto` | `break label`, `continue label` | — | `break label`, `continue label` | `break 'label`, `continue 'label` | `goto` |
-| +1 per logical operator, unless its direct parent is the same operator | `&&`, `\|\|`, `??` | `and`, `or` | `&&`, `\|\|`, `??` | `&&`, `\|\|` | `&&`, `\|\|`, `??`, pattern `and`, `or` |
+| +1 per run of `&&` (see below); `\|\|`, `or`, `??` add nothing | `&&` | `and` | `&&` | `&&` | `&&`, pattern `and` |
 | +1: comprehension `if` | — | comprehension `if` | — | — | — |
 | +1: guard on a case or arm | — | — | `case … where` | match-arm guard | `when` clause |
 
-Each logical operator scores +1, unless its direct parent is a logical operator of the same kind. Parentheses break that link, so a parenthesised group scores on its own: `a && b || c` is 2, `a && (b || c) && a` is 2, `a && (b && c)` is 2, and `a ?? b ?? c` is 1. Negation (`!`, `not`) adds nothing.
+Logical operators form one sequence per expression, read in source order through parentheses; negation, calls and other expressions start a new sequence. Each `&&` (`and`) scores +1 unless the operator before it in the sequence is also `&&`. `||`, `or`, `??` and pattern `or` add nothing but end a run: `a && b || c` is 1, `a && (b || c) && a` is 2, `a && (b && c)` is 1, and `a ?? b ?? c` is 0. Negation (`!`, `not`) adds nothing. In TypeScript/JavaScript, a short-circuit directly inside a JSX expression that uses one operator and has no ternary operand (`{a && <X/>}`, `{a && b && <X/>}`) adds nothing; a mixed one (`{a && b || <X/>}`) is counted as usual. A function used as a branch of a conditional expression (`a ? () => {…} : b` in TypeScript/JavaScript and C#, a Swift closure in a ternary, `(lambda: …) if a else b` in Python) is scored on its own from nesting 0 like any nested function, and every later construct in the enclosing function that adds "plus nesting" in the table above scores one more.
+
+It adds nothing for `try` itself, `finally`, `return`, `throw`, recursion, Rust `?`, Python `with`, Swift `do` without `catch`, an `if let` or `while let` beyond the `if` or `while`, optional chaining `?.`, assignment operators `||=`, `&&=`, `??=`, and a Rust `let` without `else`.
+
+**Differences from the Sonar paper.** SonarJS, and so klint, departs from the 2017 paper in one place: `||` (Python `or`, C# pattern `or`) adds nothing; the paper counts it.
 
-It adds nothing for `try` itself, `return`, `throw`, recursion, Rust `?`, Python `with`, Swift `do` without `catch`, an `if let` or `while let` beyond the `if` or `while`, optional chaining `?.`, assignment operators `||=`, `&&=`, `??=`, and a Rust `let` without `else`.
+**Differences from Biome 2.6.5.** Biome's `noExcessiveCognitiveComplexity` differs from SonarJS in four ways, and klint follows SonarJS:
 
-**Differences from the Sonar paper.** This rule follows Biome, which differs from the paper in these places:
+- `else if` gets no nesting increment (Biome adds it).
+- `??` adds nothing (Biome counts it).
+- `||` adds nothing (Biome counts it).
+- Biome 2.6.5 lowers the nesting level of the code after a plain `else` (an unbalanced decrement). That is a Biome bug; klint keeps the nesting.
 
-- `else if` gets the nesting increment.
-- `finally` adds one and does not nest its body.
-- `??` counts as a boolean operator.
-- A logical operator is scored unless its direct parent is the same operator, so `a && (b && c)` is 2, not 1.
-- Recursion adds nothing.
-- Biome 2.6.5 lowers the nesting level of the code after a plain `else` (an unbalanced decrement), so it can score such functions lower; klint keeps the nesting.
-- A nested function (closure, lambda, arrow, local function) is scored and reported on its own. It starts at its enclosing nesting level plus one and does not add to the outer function.
+A nested function (closure, lambda, arrow, local function) is scored and reported on its own and does not add to the outer function.
 
 **What counts as a function.** TypeScript/JavaScript: `function` declarations and expressions, arrow functions, methods (including getters and setters), generator functions. Python: `def` and `lambda`. Swift: `func`, `init`, `deinit`, closures, computed getters and setters. Rust: `fn` items and closures. C#: methods, constructors, destructors, local functions, lambdas, anonymous methods, property and indexer accessors, operators and conversion operators.
 
@@ -847,16 +864,18 @@ It adds nothing for `try` itself, `return`, `throw`, recursion, Rust `?`, Python
 
 ```yaml
 rules:
-  function-length: error
+  core:
+    function-length: error
 ```
 
 ```yaml
 rules:
-  function-length:
-    severity: warn
-    include: ["src/**", "!src/generated/**"]
-    max: 40
-    skipBlankLines: true
+  core:
+    function-length:
+      severity: warn
+      include: ["src/**", "!src/generated/**"]
+      max: 40
+      skipBlankLines: true
 ```
 
 - `max` is an integer of at least 1, default 50. A function is reported when its count is **greater than** `max`. Any other value (0, a negative number, a fraction, a string) gives one `klint/config` warning naming the rule and the value, and the rule uses 50.
@@ -869,9 +888,9 @@ rules:
 
 **Not checked.** Bodyless declarations, and files with a syntax error.
 
-## Plugins
+## Sonar rules (`rules.sonar`)
 
-Enable plugin rules with `plugins: [sonar]`, then override individual severities in `rules` when needed.
+`recommended: true` enables these rules. Override each one under `rules.sonar` by its name without the prefix.
 
 | Rule | Description |
 |------|-------------|