blockwatch-cli 0.16.3__tar.gz → 0.16.4__tar.gz

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/CHANGELOG.md

@@ -12,6 +12,26 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.16.4] - 2026-11-03
+
+### Added
+
+- Symbols in Kotlin files (`.kt` and `.kts`). `Config.kt#/Config/MAX_RETRIES` points at a property of the class
+  `Config`, and `#/MAX_RETRIES` at one at the top of the file. Each type is a symbol, and so is each property,
+  constructor property, function, enum entry and nested type in it. A companion object's members sit under the class.
+  See [Kotlin](docs/symbols.md#kotlin).
+- Symbols in Swift files. `Config.swift#/Config/maxRetries` points at a property of the type `Config`, and
+  `#/maxRetries` at one at the top of the file. Each type is a symbol, and so is each property, function, enum case and
+  nested type in it. An extension's members sit under the type it extends, and an enum case's value is its raw value.
+  See [Swift](docs/symbols.md#swift).
+
+### Fixed
+
+- A Java text block with `\u` and a sign, such as `\u+041`, counted as the character, here `A`. Java rejects this
+  escape, so a path to the text block now stops the run.
+- A Java string in `"` quotes with a line break in it counted as text. Java rejects it, so a path to it now stops the
+  run. Before, a string missing its closing quote took in the next line as its value.
+
 ## [0.16.3] - 2026-11-02
 
 ## [0.16.2] - 2026-10-30

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/Cargo.lock

@@ -274,7 +274,7 @@ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
 [[package]]
 name = "blockwatch"
-version = "0.16.3"
+version = "0.16.4"
 dependencies = [
  "anyhow",
  "assert-json-diff",

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "blockwatch"
-version = "0.16.3"
+version = "0.16.4"
 edition = "2024"
 repository = "https://github.com/mennanov/blockwatch"
 description = "Language agnostic linter that keeps your code and documentation in sync and valid"

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.16.3
+Version: 0.16.4
 Summary: Language agnostic linter that keeps your code and documentation in sync and valid
 Keywords: linter,sync,drift,comments,agents
 Home-Page: https://github.com/mennanov/blockwatch

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/README.md

@@ -89,7 +89,7 @@ Two validators work across files:
 - `same-as` fails when a block and its target hold different values. It needs no diff.
 
 Both can point to a block, a whole file, a specific value in a file like `package.json#/version`, a section of a
-Markdown file, or a constant in a Go, C, C++, Python, Rust, TypeScript, JavaScript, Java or C# file (see
+Markdown file, or a constant in a Go, C, C++, Python, Rust, TypeScript, JavaScript, Java, C#, Kotlin or Swift file (see
 [Symbols](docs/symbols.md)). The other validators check a single block on their own: the things you'd otherwise have to
 nitpick in code review.
 
@@ -219,7 +219,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.3  # Use latest release
+  rev: v0.16.4  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/docs/ci.md

@@ -19,7 +19,7 @@ To use [pre-commit](https://pre-commit.com), add the hook to `.pre-commit-config
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.3  # Use latest release
+  rev: v0.16.4  # Use latest release
   hooks:
     - id: blockwatch
 ```
@@ -59,7 +59,7 @@ The `blockwatch` hook runs before the commit message exists, so it cannot see a
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.3  # Use latest release
+  rev: v0.16.4  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/docs/cli.md

@@ -557,15 +557,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.16.3",
-          "semanticVersion": "0.16.3",
+          "version": "0.16.4",
+          "semanticVersion": "0.16.4",
           "informationUri": "https://github.com/mennanov/blockwatch",
           "rules": [
             {
               "id": "keep-sorted",
               "name": "keep-sorted",
               "shortDescription": { "text": "Requires the lines of a block to stay in order." },
-              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.16.3/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.16.4/docs/validators/keep-sorted.md"
             }
           ]
         }

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/docs/symbols.md

@@ -39,6 +39,8 @@ declares, instead of tags in a comment.
 | JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx`                                                  | [TypeScript and JavaScript](#typescript-and-javascript) |
 | Java       | `.java`                                                                        | [Java](#java)                                           |
 | C#         | `.cs`                                                                          | [C#](#c)                                                |
+| Kotlin     | `.kt`, `.kts`                                                                  | [Kotlin](#kotlin)                                       |
+| Swift      | `.swift`                                                                       | [Swift](#swift)                                         |
 
 <!-- </block> -->
 
@@ -249,8 +251,8 @@ Clone the repository.
 
 In a code file, each top-level name is a symbol: a constant, a variable, a type, a function or a macro. Its path is
 `#/NAME`.
-With `const MaxPorts = 8` in `consts.go`, `consts.go#/MaxPorts` points at `8`. In Java and C#, the members of a type
-are symbols too, under the type's name: `Config.java#/Config/MAX_PORTS`.
+With `const MaxPorts = 8` in `consts.go`, `consts.go#/MaxPorts` points at `8`. In Java, C#, Kotlin and Swift, the
+members of a type are symbols too, under the type's name: `Config.java#/Config/MAX_PORTS`.
 
 - **A value is the initializer as written.** blockwatch never works it out: `20 * 1024 * 1024` stays as it is, and so
   does `0x10`. Use `same-as-pattern` to take the part you need.
@@ -264,7 +266,7 @@ are symbols too, under the type's name: `Config.java#/Config/MAX_PORTS`.
   with a name from the text that the parser had to skip. Other names in the file still resolve. The message shows
   where the error is.
 - **A path to a string that blockwatch can't decode stops the run.** Other paths in the file still resolve.
-- **Members are not symbols yet**, such as a method or a field, except in Java and C#.
+- **Members are not symbols yet**, such as a method or a field, except in Java, C#, Kotlin and Swift.
 
 <!-- </block> -->
 
@@ -595,6 +597,133 @@ public class Config
 
 <!-- </block> -->
 
+## Kotlin
+
+<!-- <block name="kotlin-paths"> -->
+
+```kotlin
+const val MAX_RETRIES = 20 * 1024
+
+data class Config(val timeout: Int = 30, val name: String) {
+    @JvmField
+    val url = "https://example.com"
+
+    fun run() {}
+    fun run(times: Int) {}
+
+    companion object {
+        const val ORIGIN = 0
+    }
+
+    enum class Mode { RED, GREEN }
+}
+```
+
+| Path                  | Points at                                  |
+|-----------------------|--------------------------------------------|
+| `#/MAX_RETRIES`       | `20 * 1024`                                |
+| `#/Config`            | the whole class                            |
+| `#/Config/timeout`    | `30`                                       |
+| `#/Config/name`       | `val name: String`, as it has no default   |
+| `#/Config/url`        | `https://example.com`                      |
+| `#/Config/run`        | a violation, as `run` is defined twice     |
+| `#/Config/ORIGIN`     | `0`                                        |
+| `#/Config/Mode/GREEN` | `GREEN`, as it has no value                |
+
+- **Each top-level property, function, type and type alias is a symbol, and so is each member of a type**: a property,
+  a function, an enum entry, or a nested class, interface or object. A path goes from the top-level type down:
+  `#/Config/Mode/GREEN`.
+- **A constructor parameter with `val` or `var` is a symbol.** Its value is its default. A parameter without `val` or
+  `var` is not a symbol.
+- **A companion object's members sit under the class**, as code reads them: `#/Config/ORIGIN`. A companion with a
+  name works the same way: `companion object Builder` still gives `#/Config/ORIGIN`.
+- **Overloads are defined twice.** So are a property and a function with one name, and two extension functions with
+  one name, such as `fun Foo.toDto()` and `fun Bar.toDto()`. Wrap the one you mean in a block instead.
+- **A property's value is its initializer, or the `v` of `get() = v`.** A property with `by`, such as
+  `by lazy { 3 }`, has no value, and neither has one whose getter has a block body.
+- **A name in backticks loses them.** `` fun `parses empty input`() `` in `Config` is
+  `#/Config/parses empty input`.
+- **Annotations are part of a definition. KDoc is not.** One case is left out: at the top of a file, an annotation with
+  arguments on its own line, before a `fun` or `val` with no other modifier. The parser reads it as a separate
+  expression.
+- **Constructors, `init` blocks, the companion object itself, local declarations, and the members in the body of an
+  enum entry are not symbols.** In a `.kts` script, the top-level properties, functions and types are symbols. Calls
+  such as `plugins { ... }` and everything inside them are not.
+- **Strings follow Kotlin's escapes.** `"caf\u00e9"` is `café`. A raw string (`"""..."""`) has no escapes, and each line
+  end in it is a line feed. A string with a template, such as `"v$major"` or `"${a + b}"`, stays as written, and so
+  does a character such as `'a'`. A path to a string that Kotlin rejects stops the run, such as `"\q"`.
+- **A syntax error stops the run for the member that holds it, and for each type around that member.** The other
+  members still resolve. The parser doesn't read some newer syntax, such as context parameters and `$$"..."` strings.
+  It also fails on a class body on one line with a property in it, such as `class A { val x = 1 }`.
+
+<!-- </block> -->
+
+## Swift
+
+<!-- <block name="swift-paths"> -->
+
+```swift
+public let maxRetries = 20 * 1024
+
+struct Config {
+    static let timeout = 30
+    var name: String
+    var ready: Bool { timeout > 0 }
+
+    func run() {}
+    func run(times: Int) {}
+
+    enum Mode: String {
+        case red = "r", green
+    }
+}
+
+extension Config {
+    static let url = "https://example.com"
+}
+```
+
+| Path                  | Points at                                  |
+|-----------------------|--------------------------------------------|
+| `#/maxRetries`        | `20 * 1024`                                |
+| `#/Config`            | the whole struct, without its extension    |
+| `#/Config/timeout`    | `30`                                       |
+| `#/Config/name`       | `var name: String`, as it has no value     |
+| `#/Config/ready`      | `timeout > 0`                              |
+| `#/Config/run`        | a violation, as `run` is defined twice     |
+| `#/Config/Mode/red`   | `r`                                        |
+| `#/Config/Mode/green` | `green`, as its raw value is implicit      |
+| `#/Config/url`        | `https://example.com`                      |
+
+- **Each top-level property, function, type, type alias and macro is a symbol, and so is each member of a type**: a
+  property, a function, an enum case, an associated type or a nested type. A protocol is a type, and its requirements
+  are members. A path goes from the top-level type down: `#/Config/Mode/red`.
+- **An extension's members sit under the type it extends**, as code reads them: `#/Config/url`. The type can come from
+  another file too, so `String+Format.swift` can have `#/String/trimmed`. The path follows the type's name as written:
+  `extension Outer.Inner` gives `#/Outer/Inner/...`, and `extension Swift.String` gives `#/Swift/String/...`. An
+  extension of a type without a name, such as `extension [Int]`, has no symbols.
+- **Overloads are defined twice.** So are a property and a function with one name, copies of a name in `#if` and
+  `#else`, and a protocol requirement and its default in an extension. Wrap the one you mean in a block instead.
+- **A property's value is its initializer, or the `v` of `{ v }` or `{ return v }`.** A computed property with `get`
+  or `set`, with several statements, or with one statement that is not an expression, such as a `for` loop, has no
+  value. An enum case's value is its raw value, the `v` of `= v`. A case
+  without one has no value, even when Swift gives it one.
+- **In `let a = 1, b = 2` and `case a = 1, b`, each name covers only its own part.** The first part also covers the
+  attributes, the modifiers and `let`, `var` or `case`: `#/a` is `let a = 1`, and `#/b` is `b = 2`.
+- **A name in backticks loses them.** Attributes are part of a definition. Doc comments are not.
+- **`init`, `deinit`, `subscript`, operators, precedence groups, extensions themselves, local declarations and
+  top-level statements are not symbols.**
+- **Strings follow Swift's escapes.** `"caf\u{e9}"` is `café`. A raw string, such as `#"C:\new"#`, reads only the
+  escapes with as many `#` as its quotes, such as `\#n`. A multi-line string loses the white space before its closing
+  quotes on each line, and each line end in it is a line feed. A string with an interpolation, such as `"v\(major)"`,
+  stays as written, and so does a regex. A path to a string that Swift rejects stops the run, such as `"\u{D800}"`.
+- **A syntax error stops the run for the member that holds it, and for each type around that member.** The other
+  members still resolve. An extension is not part of the type it extends, so an error in an extension's member leaves
+  the type readable. The parser fails on an empty tuple passed to a function, as in `f(())`, so a function with one in
+  its body stops the run too.
+
+<!-- </block> -->
+
 ---
 
 [← Return to README](../README.md)

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/setup.py

@@ -6,7 +6,7 @@ setup(
     name='blockwatch-pre-commit-placeholder',
     version='0.0.0',
     # <block name="blockwatch-cli-version" same-as-pattern="blockwatch-cli==(?P<value>\d+\.\d+\.\d+)">
-    install_requires=['blockwatch-cli==0.16.3'],
+    install_requires=['blockwatch-cli==0.16.4'],
     # </block>
     # Without it, setuptools takes the directories under src/ for Python packages.
     packages=[],

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/src/language_parsers/c.rs

@@ -39,7 +39,13 @@ impl SymbolsParser for CSymbolsParser {
             .parse(fixed_directive_line_ends(source).as_ref(), None)
             .context("failed to parse syntax tree")?;
         let definitions = definitions(tree.root_node(), source, &mut self.parser)?;
-        Ok(code::symbols(&tree, source, &definitions, &decode_string))
+        Ok(code::symbols(
+            &tree,
+            source,
+            &definitions,
+            &decode_string,
+            None,
+        ))
     }
 }
 

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/src/language_parsers/c_sharp.rs

@@ -26,15 +26,7 @@ impl CodeLanguage for CSharp {
     /// document order. A type comes before its members. The names of the namespaces a type sits
     /// in are its first parents.
     fn definitions<'tree>(&self, root: Node<'tree>, _source: &str) -> Vec<Definition<'tree>> {
-        let mut definitions = Vec::new();
-        // The walk keeps its own stack, as deeply nested types could overflow the call stack.
-        let mut bodies = vec![(root, Vec::new())];
-        while let Some((body, parents)) = bodies.pop() {
-            push_members(body, parents, &mut definitions, &mut bodies);
-        }
-        // The walk reads all of a body before the bodies in it.
-        definitions.sort_by_key(|definition| definition.range.start);
-        definitions
+        code::nested_definitions(root, push_members)
     }
 
     /// Decodes a C# string, or an interpolated string without a hole. Returns `None` for any other
@@ -293,7 +285,7 @@ fn property_value(property: Node) -> Option<Node> {
     let value = property.child_by_field_name("value")?;
     // Code reads a property as it reads a field, so `X => v` has the value `v`.
     if value.kind() == "arrow_expression_clause" {
-        value_after(value, "=>")
+        code::value_after(value, "=>")
     } else {
         Some(value)
     }
@@ -333,21 +325,11 @@ fn push_fields<'tree>(
             parents.to_vec(),
             name,
             range,
-            value_after(declarator, "="),
+            code::value_after(declarator, "="),
         ));
     }
 }
 
-/// The value that follows the `token` in `node`, such as the `5` after the `=` in `x = 5`.
-/// Returns `None` when `node` has no `token`.
-fn value_after<'tree>(node: Node<'tree>, token: &str) -> Option<Node<'tree>> {
-    // The grammar gives the value no field name. A comment after the token is not the value.
-    let mut cursor = node.walk();
-    node.children(&mut cursor)
-        .skip_while(|child| child.kind() != token)
-        .find(|child| child.is_named() && !child.is_extra())
-}
-
 /// The definition of `member`, a declaration with one name, in the namespace or type at
 /// `parents`. It covers the whole declaration and has the initializer `value`, if any. Returns
 /// `None` if the parser found no name.

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.4}/src/language_parsers/java.rs

@@ -25,23 +25,16 @@ impl CodeLanguage for Java {
     /// The types under `root`, the root of a Java file's syntax tree, and their members, in
     /// document order. A type comes before its members.
     fn definitions<'tree>(&self, root: Node<'tree>, _source: &str) -> Vec<Definition<'tree>> {
-        let mut definitions = Vec::new();
-        // The walk keeps its own stack, as deeply nested types could overflow the call stack.
         // A compact source file holds methods and fields at its top level, as a class body does.
-        let mut bodies = vec![(root, Vec::new())];
-        while let Some((body, parents)) = bodies.pop() {
-            push_members(body, &parents, &mut definitions, &mut bodies);
-        }
-        // The walk reads all of a body before the bodies of the types in it.
-        definitions.sort_by_key(|definition| definition.range.start);
-        definitions
+        code::nested_definitions(root, push_members)
     }
 
     /// Decodes a Java string or text block. Returns `None` for any other node.
     ///
     /// # Errors
-    /// Returns an error if an escape is not one of Java's, if the string holds `\u005c`, or if the
-    /// string holds half of a character.
+    /// Returns an error if an escape is not one of Java's, if the string holds `\u005c`, if a
+    /// string that is not a text block holds a line break, or if the string holds half of a
+    /// character.
     fn decode_string(&self, node: &Node, source: &str) -> anyhow::Result<Option<String>> {
         if node.kind() != "string_literal" {
             return Ok(None);
@@ -51,11 +44,18 @@ impl CodeLanguage for Java {
             Some(block) => {
                 text_block_content(block.strip_suffix(TEXT_BLOCK_QUOTES).unwrap_or(block))
             }
-            None => literal
-                .strip_prefix('"')
-                .and_then(|content| content.strip_suffix('"'))
-                .unwrap_or(literal)
-                .to_string(),
+            None => {
+                let content = literal
+                    .strip_prefix('"')
+                    .and_then(|content| content.strip_suffix('"'))
+                    .unwrap_or(literal);
+                // The grammar lets a string run on to the next line, so a string missing its
+                // closing quote takes in the next line too.
+                if content.contains(['\r', '\n']) {
+                    bail!("Java allows a line break only in a text block");
+                }
+                content.to_string()
+            }
         };
         code::decode_utf16(&content, push_escape).map(Some)
     }
@@ -147,12 +147,11 @@ fn octal_digits(first: char, characters: &mut Peekable<Chars>) -> String {
 /// `u`. For `\u00e9`, it is the unit of `é`.
 ///
 /// # Errors
-/// Returns an error if the next 4 characters don't read as a hex number, or if the escape is
-/// `\u005c`.
+/// Returns an error if the next 4 characters are not hex digits, or if the escape is `\u005c`.
 fn unicode_unit(characters: &mut Peekable<Chars>) -> anyhow::Result<u16> {
     let digits: String = characters.by_ref().take(4).collect();
-    let unit = u16::from_str_radix(&digits, 16)
-        .map_err(|_| anyhow!("`\\u{digits}` is not an escape in a Java string"))?;
+    let unit = code::utf16_unit(&digits)
+        .ok_or_else(|| anyhow!("`\\u{digits}` is not an escape in a Java string"))?;
     // Java turns `\u005c` into a backslash before it reads the other escapes, so `\u005cn` is
     // a line feed, which one pass over the escapes can't give.
     if unit == u16::from(b'\\') {
@@ -166,7 +165,7 @@ fn unicode_unit(characters: &mut Peekable<Chars>) -> anyhow::Result<u16> {
 /// each type in `body` to `bodies`, with its own parents.
 fn push_members<'tree>(
     body: Node<'tree>,
-    parents: &[Node<'tree>],
+    parents: Vec<Node<'tree>>,
     definitions: &mut Vec<Definition<'tree>>,
     bodies: &mut Vec<(Node<'tree>, Vec<Node<'tree>>)>,
 ) {
@@ -177,10 +176,10 @@ fn push_members<'tree>(
             // A compact source file declares its fields as local variables, and an interface its
             // constants as constants.
             "field_declaration" | "local_variable_declaration" | "constant_declaration" => {
-                push_fields(member, parents, definitions);
+                push_fields(member, &parents, definitions);
             }
             // The members of an enum that come after its constants.
-            "enum_body_declarations" => bodies.push((member, parents.to_vec())),
+            "enum_body_declarations" => bodies.push((member, parents.clone())),
             "class_declaration"
             | "interface_declaration"
             | "enum_declaration"
@@ -196,7 +195,7 @@ fn push_members<'tree>(
                     None,
                 ));
                 if let Some(body) = member.child_by_field_name("body") {
-                    bodies.push((body, [parents, &[name]].concat()));
+                    bodies.push((body, [&parents[..], &[name]].concat()));
                 }
             }
             // The body of an enum constant is a class without a name, so its members are not
@@ -622,6 +621,8 @@ class Helper {}
     static final String HEX = "\x41";
     static final String HALF = "\uD800";
     static final String BACKSLASH = "\u005cn";
+    static final String SIGN = """
+        \u+041""";
     static final String FINE = "ok";
 }
 "#;
@@ -650,6 +651,28 @@ class Helper {}
                 r"Java turns `\u005c` into a backslash before it reads the other escapes"
             )
         );
+        // The grammar rejects this escape in a string, but not in a text block.
+        assert_eq!(
+            unresolved(&java(source)?, source, "/Broken/SIGN")?,
+            decode_error(5, 32, r"`\u+041` is not an escape in a Java string")
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn line_break_in_a_string_parse_symbols_makes_the_name_unreadable() -> anyhow::Result<()> {
+        // Java reads a carriage return alone as a line end too.
+        let source = "class A {\n    static final String LF = \"a\nb\";\n    static final String CR = \"a\rb\";\n}\n";
+
+        assert_eq!(values(&java(source)?, source).len(), 1, "only the class");
+        assert_eq!(
+            unresolved(&java(source)?, source, "/A/LF")?,
+            decode_error(2, 30, "Java allows a line break only in a text block")
+        );
+        assert_eq!(
+            unresolved(&java(source)?, source, "/A/CR")?,
+            decode_error(4, 30, "Java allows a line break only in a text block")
+        );
         Ok(())
     }