@konvert7/klint 1.0.2 → 1.1.0

package/README.md

@@ -525,11 +525,13 @@ klint scans TypeScript/JavaScript, Python, Swift, Rust, and C#. Every architectu
 | `arch.forbidden` / `singleton` — `jsx-element` | ✅ | — | — | — | — |
 | `arch.maxLines` | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `arch.maxCommentDensity` / `maxCommentBlock` | ✅ `//`, `/* */`, `/** */` docs | ✅ `#` | ✅ `//`, `/* */`, `///` and `/** */` docs | ✅ `//`, `/* */`, `///` and `//!` docs | ✅ `//`, `/* */`, `///` and `/** */` docs |
-| Built-in rules and plugins | ✅ | ✗ | ✗ | ✗ | ✗ |
+| Built-in rules and plugins | ✅ | ✗ ¹ | ✗ ¹ | ✗ ¹ | ✗ ¹ |
 
 **✅** supported · **—** the language has no equivalent construct · **✗** not supported yet
 
-A dash is not a gap. Swift has no dynamic import expression, no `import type`, and one module per declaration; Rust has no dynamic import and no type-only import; C# has no dynamic `using`, no type-only import, and one namespace per `using`. Those rows can never be filled. The `✗` rows are real limits: the rule set and custom rules are written against the TypeScript AST, and type-aware rules need a type checker that only the TS engine has.
+¹ except `blank-line-before-control-flow` and `blank-line-after-block`, which run on all five languages.
+
+A dash is not a gap. Swift has no dynamic import expression, no `import type`, and one module per declaration; Rust has no dynamic import and no type-only import; C# has no dynamic `using`, no type-only import, and one namespace per `using`. Those rows can never be filled. The `✗` rows are real limits: the rule set and custom rules are written against the TypeScript AST, and type-aware rules need a type checker that only the TS engine has. The one exception is the pair of blank-line rules, which read each language's own syntax tree and so run on all five.
 
 Imports are read off the AST in every language, so a specifier written inside a comment or a string is never an import — including nested Swift block comments.
 
@@ -729,9 +731,57 @@ doc-comments alongside `/** */`.
 | `no-nested-template-literals` | Template literals nested inside template literals |
 | `no-consecutive-array-push` | Multiple consecutive `push()` calls that should be grouped |
 | `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 |
 
 Rules that needed TypeScript's type checker were removed in 1.0; see [Upgrading from klint 0.x](#upgrading-from-klint-0x).
 
+### Blank lines around control flow
+
+`blank-line-before-control-flow` asks for a blank line above a control-flow statement that follows another statement in its block. `blank-line-after-block` asks for a blank line below a block statement when another statement follows it in the same block. Both work on TypeScript/JavaScript, Python, Swift, Rust and C#. They are opt-in, and `klint --fix` inserts the missing line.
+
+```yaml
+rules:
+  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]
+```
+
+- `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.
+- `allowSetup` (before rule only, default `true`) turns the setup exception on or off, described below.
+
+| keyword | TypeScript / JavaScript | Python | Swift | Rust | C# |
+|---|---|---|---|---|---|
+| `if` | `if` | `if` | `if` | `if`, `if let` | `if` |
+| `for` | `for`, `for…in`, `for…of` | `for` | `for…in` | `for` | `for`, `foreach` |
+| `while` | `while`, `do…while` | `while` | `while`, `repeat…while` | `while`, `while let` | `while`, `do…while` |
+| `switch` (alias `match`) | `switch` | `match` | `switch` | `match` | `switch` statement |
+| `try` | `try` | `try` | `do` | — | `try` |
+| `return` (before rule only) | `return` | `return` | `return` | `return` | `return` |
+| `guard` | — | — | `guard` | — | — |
+| `loop` | — | — | — | `loop` | — |
+| `with` | — | `with` | — | — | — |
+
+**Comments.** A comment that starts its own line directly above a statement belongs to that statement. The before rule puts the blank line above the comment. The after rule puts the blank line between the block and a comment that follows the block, so the comment stays with the statement below.
+
+**Setup exception.** With `allowSetup: true`, the before rule skips an `if`, `guard` or `switch` whose condition uses a name assigned by the statement directly above it. For example, `x = f();` followed by `if (x) …` is not reported. Only the statement directly above counts (comment lines are skipped), only plain names count (`self.x = f()` does not), and only the condition is searched, not the body.
+
+**Autofix.** `klint --fix` inserts one empty line with the line ending of the line above it, and changes nothing else. A second run changes nothing.
+
+**Not checked.** A file with a syntax error gets no report and no fix. A braceless body (`if (a) return 1;`) is not a block for the after rule. `do…while` and `repeat…while` are never reported by the after rule. A statement that shares its line with the previous statement is not reported, because the fix would have to split that line. Expression forms are not statements: `let x = if …` and `let r = match …` in Rust, `let x = if …` in Swift, a C# switch expression, and control flow inside a call are never reported. A Python docstring is documentation, not a statement, so the statement after it counts as first in its block. A C# preprocessor line (`#region`, `#if`, `#pragma`, …) or a Swift `#if`/`#elseif`/`#else`/`#endif` line separates statements like a blank line, so neither rule inserts a line next to one.
+
 ## Plugins
 
 Enable plugin rules with `plugins: [sonar]`, then override individual severities in `rules` when needed.

package/klint.schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://raw.githubusercontent.com/konvert7/klint/refs/tags/v1.0.2/klint.schema.json",
+  "$id": "https://raw.githubusercontent.com/konvert7/klint/refs/tags/v1.1.0/klint.schema.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "additionalProperties": false,
   "description": "klint configuration. Lives at klint.yaml (or klint.config.json) next to biome.json and knip.json.",
@@ -598,6 +598,133 @@
       },
       "description": "Map of rule name → severity or options. Example: { \"no-floating-promise\": \"error\", \"no-sync-in-async\": { \"severity\": \"warn\", \"include\": [\"src/hooks/**\"] } }.",
       "properties": {
+        "blank-line-after-block": {
+          "anyOf": [
+            {
+              "description": "Rule severity. \"error\" exits with code 2; \"warn\" reports but exits 0; \"off\" silences.",
+              "enum": [
+                "error",
+                "warn",
+                "off"
+              ],
+              "type": "string"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Rule options object. Omit severity to default to \"error\". Add include to scope the rule to specific files.",
+              "properties": {
+                "include": {
+                  "description": "Glob patterns scoping this rule to a subset of files. Prefix with ! to exclude. Example: [\"src/hooks/**\", \"!src/hooks/scripts/**\"]",
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "severity": {
+                  "description": "Rule severity. \"error\" exits with code 2; \"warn\" reports but exits 0; \"off\" silences.",
+                  "enum": [
+                    "error",
+                    "warn",
+                    "off",
+                    null
+                  ],
+                  "type": "string"
+                },
+                "statements": {
+                  "description": "Block statement kinds this rule targets. Defaults to every kind: if, for, while, switch, try, guard, loop, with. match is an alias of switch. return is not a block statement. An empty list turns the rule off.",
+                  "items": {
+                    "description": "A block statement kind the rule targets. match is an alias of switch.",
+                    "enum": [
+                      "if",
+                      "for",
+                      "while",
+                      "switch",
+                      "match",
+                      "try",
+                      "guard",
+                      "loop",
+                      "with"
+                    ],
+                    "type": "string"
+                  },
+                  "type": "array"
+                }
+              },
+              "type": "object"
+            }
+          ],
+          "description": "Requires a blank line below a block statement (if, for, while, switch/match, try, guard, loop, with) when another statement follows it in the same block, like C# IDE2003. Works on TypeScript/JavaScript, Python, Swift, Rust and C#; `klint --fix` inserts the line.",
+          "examples": [
+            "blank-line-after-block: warn",
+            "blank-line-after-block:\n  severity: warn\n  include: [\"src/**\"]\n  statements: [if, for, while, switch, try, guard, loop, with]"
+          ]
+        },
+        "blank-line-before-control-flow": {
+          "anyOf": [
+            {
+              "description": "Rule severity. \"error\" exits with code 2; \"warn\" reports but exits 0; \"off\" silences.",
+              "enum": [
+                "error",
+                "warn",
+                "off"
+              ],
+              "type": "string"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Rule options object. Omit severity to default to \"error\". Add include to scope the rule to specific files.",
+              "properties": {
+                "allowSetup": {
+                  "description": "Skip an if, guard or switch statement whose condition uses a name assigned by the statement directly above it. Defaults to true.",
+                  "type": "boolean"
+                },
+                "include": {
+                  "description": "Glob patterns scoping this rule to a subset of files. Prefix with ! to exclude. Example: [\"src/hooks/**\", \"!src/hooks/scripts/**\"]",
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "severity": {
+                  "description": "Rule severity. \"error\" exits with code 2; \"warn\" reports but exits 0; \"off\" silences.",
+                  "enum": [
+                    "error",
+                    "warn",
+                    "off",
+                    null
+                  ],
+                  "type": "string"
+                },
+                "statements": {
+                  "description": "Statement kinds this rule targets. Defaults to every kind: if, for, while, switch, try, return, guard, loop, with. match is an alias of switch. An empty list turns the rule off.",
+                  "items": {
+                    "description": "A statement kind the rule targets. match is an alias of switch.",
+                    "enum": [
+                      "if",
+                      "for",
+                      "while",
+                      "switch",
+                      "match",
+                      "try",
+                      "return",
+                      "guard",
+                      "loop",
+                      "with"
+                    ],
+                    "type": "string"
+                  },
+                  "type": "array"
+                }
+              },
+              "type": "object"
+            }
+          ],
+          "description": "Requires a blank line above a control-flow statement (if, for, while, switch/match, try, return, guard, loop, with) that follows another statement in the same block. Works on TypeScript/JavaScript, Python, Swift, Rust and C#; `klint --fix` inserts the line.",
+          "examples": [
+            "blank-line-before-control-flow: error",
+            "blank-line-before-control-flow:\n  severity: error\n  include: [\"src/**\", \"!src/generated/**\"]\n  statements: [if, for, while, switch, try, return, guard, loop, with]\n  allowSetup: true"
+          ]
+        },
         "no-async-predicate": {
           "anyOf": [
             {

package/klint.schema.yaml

@@ -1,4 +1,4 @@
-$id: https://raw.githubusercontent.com/konvert7/klint/refs/tags/v1.0.2/klint.schema.json
+$id: https://raw.githubusercontent.com/konvert7/klint/refs/tags/v1.1.0/klint.schema.json
 $schema: http://json-schema.org/draft-07/schema#
 additionalProperties: false
 description: klint configuration. Lives at klint.yaml (or klint.config.json) next to biome.json and knip.json.
@@ -449,6 +449,109 @@ properties:
         type: object
     description: 'Map of rule name → severity or options. Example: { "no-floating-promise": "error", "no-sync-in-async": { "severity": "warn", "include": ["src/hooks/**"] } }.'
     properties:
+      blank-line-after-block:
+        anyOf:
+        - description: Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.
+          enum:
+          - error
+          - warn
+          - off
+          type: string
+        - additionalProperties: false
+          description: Rule options object. Omit severity to default to "error". Add include to scope the rule to specific files.
+          properties:
+            include:
+              description: 'Glob patterns scoping this rule to a subset of files. Prefix with ! to exclude. Example: ["src/hooks/**", "!src/hooks/scripts/**"]'
+              items:
+                type: string
+              type: array
+            severity:
+              description: Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.
+              enum:
+              - error
+              - warn
+              - off
+              - null
+              type: string
+            statements:
+              description: 'Block statement kinds this rule targets. Defaults to every kind: if, for, while, switch, try, guard, loop, with. match is an alias of switch. return is not a block statement. An empty list turns the rule off.'
+              items:
+                description: A block statement kind the rule targets. match is an alias of switch.
+                enum:
+                - if
+                - for
+                - while
+                - switch
+                - match
+                - try
+                - guard
+                - loop
+                - with
+                type: string
+              type: array
+          type: object
+        description: Requires a blank line below a block statement (if, for, while, switch/match, try, guard, loop, with) when another statement follows it in the same block, like C# IDE2003. Works on TypeScript/JavaScript, Python, Swift, Rust and C#; `klint --fix` inserts the line.
+        examples:
+        - 'blank-line-after-block: warn'
+        - |-
+          blank-line-after-block:
+            severity: warn
+            include: ["src/**"]
+            statements: [if, for, while, switch, try, guard, loop, with]
+      blank-line-before-control-flow:
+        anyOf:
+        - description: Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.
+          enum:
+          - error
+          - warn
+          - off
+          type: string
+        - additionalProperties: false
+          description: Rule options object. Omit severity to default to "error". Add include to scope the rule to specific files.
+          properties:
+            allowSetup:
+              description: Skip an if, guard or switch statement whose condition uses a name assigned by the statement directly above it. Defaults to true.
+              type: boolean
+            include:
+              description: 'Glob patterns scoping this rule to a subset of files. Prefix with ! to exclude. Example: ["src/hooks/**", "!src/hooks/scripts/**"]'
+              items:
+                type: string
+              type: array
+            severity:
+              description: Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.
+              enum:
+              - error
+              - warn
+              - off
+              - null
+              type: string
+            statements:
+              description: 'Statement kinds this rule targets. Defaults to every kind: if, for, while, switch, try, return, guard, loop, with. match is an alias of switch. An empty list turns the rule off.'
+              items:
+                description: A statement kind the rule targets. match is an alias of switch.
+                enum:
+                - if
+                - for
+                - while
+                - switch
+                - match
+                - try
+                - return
+                - guard
+                - loop
+                - with
+                type: string
+              type: array
+          type: object
+        description: Requires a blank line above a control-flow statement (if, for, while, switch/match, try, return, guard, loop, with) that follows another statement in the same block. Works on TypeScript/JavaScript, Python, Swift, Rust and C#; `klint --fix` inserts the line.
+        examples:
+        - 'blank-line-before-control-flow: error'
+        - |-
+          blank-line-before-control-flow:
+            severity: error
+            include: ["src/**", "!src/generated/**"]
+            statements: [if, for, while, switch, try, return, guard, loop, with]
+            allowSetup: true
       no-async-predicate:
         anyOf:
         - description: Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -56,12 +56,12 @@
     ]
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "1.0.2",
-    "@konvert7/klint-darwin-x64": "1.0.2",
-    "@konvert7/klint-linux-arm64": "1.0.2",
-    "@konvert7/klint-linux-x64": "1.0.2",
-    "@konvert7/klint-linux-x64-musl": "1.0.2",
-    "@konvert7/klint-win32-x64": "1.0.2"
+    "@konvert7/klint-darwin-arm64": "1.1.0",
+    "@konvert7/klint-darwin-x64": "1.1.0",
+    "@konvert7/klint-linux-arm64": "1.1.0",
+    "@konvert7/klint-linux-x64": "1.1.0",
+    "@konvert7/klint-linux-x64-musl": "1.1.0",
+    "@konvert7/klint-win32-x64": "1.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.6.5",