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

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.5}/AGENTS.md

@@ -235,22 +235,18 @@ The main modules:
   Some languages also have symbols. Such a language has a `SymbolsParser`, which its `parser()` passes to
   `.with_symbols(...)`:
 
-  - JSON uses a `QuerySymbolsParser`, built from a tree-sitter query (`.scm`) and a `NodeDecoder`.
+  - JSON and YAML walk their syntax trees themselves, and refuse a file with a syntax error.
   - TOML finds its symbols with `toml_edit`. What a TOML key means depends on the order of the headers, not on how the
     syntax tree is nested.
-  - YAML walks its syntax tree itself. An alias has a position in a sequence but can't be addressed, and a query can't
-    express that.
   - Markdown finds its sections with the `markdown` crate, the same parser that finds its comments.
 
   Each language's tests list every symbol it finds. When you give a language symbols, also document its paths in
   `docs/symbols.md` and in the "Symbols" section of the skill, `src/skill.md`. A test in `language_parsers/mod.rs` and the
   repository's own blocks keep the list of file types with symbols, and each language's section, in sync with the
   code.
-- `src/symbols.rs` — `Symbol`, the `SymbolsParser` trait, and `resolve`, which finds the symbol a path refers to.
-  `QuerySymbolsParser` runs a language's query and finds every addressable `Symbol` in one walk of the tree, with its
-  path, its definition range and its decoded value. It suits a language whose structure is its syntax tree. It rejects
-  a file with a syntax error, instead of resolving a path through tree-sitter's error recovery. It doesn't check the
-  query itself.
+- `src/symbols/mod.rs` — `Symbol`, the `SymbolsParser` trait, and `resolve`, which finds the symbol a path refers to.
+  `ensure_no_syntax_error` refuses a file with a syntax error, instead of resolving a path through tree-sitter's error
+  recovery.
 - `src/validators/` — one file for each validator (`affects`, `check_ai`, `check_lua`, `keep_sorted`, `keep_unique`,
   `line_count`, `line_pattern`, `same_as`). Each file exports a `detect` function. `Validator::detect` in
   `validators/mod.rs` calls them from one `match`.

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

@@ -12,6 +12,38 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.16.5] - 2026-11-03
+
+### Added
+
+- Symbols in Protocol Buffers files (`.proto`). `item.proto#/Item/Color/RED` points at the number of an enum value,
+  and `#/Item/name` at the number of a field. Each message, enum and service is a symbol, and so is each field, oneof,
+  enum value and rpc in it. The package is not part of a path, and options are not symbols. See
+  [Protocol Buffers](docs/symbols.md#protocol-buffers).
+- Symbols in HCL files: Terraform and OpenTofu (`.tf`, `.tofu`, `.tfvars`), Nomad (`.nomad`), and `.hcl` files such
+  as Terragrunt's. See [HCL](docs/symbols.md#hcl).
+- blockwatch now checks the tags in Nomad job files (`.nomad`). Before, it skipped them.
+
+## [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.5}/CLAUDE.md

@@ -235,22 +235,18 @@ The main modules:
   Some languages also have symbols. Such a language has a `SymbolsParser`, which its `parser()` passes to
   `.with_symbols(...)`:
 
-  - JSON uses a `QuerySymbolsParser`, built from a tree-sitter query (`.scm`) and a `NodeDecoder`.
+  - JSON and YAML walk their syntax trees themselves, and refuse a file with a syntax error.
   - TOML finds its symbols with `toml_edit`. What a TOML key means depends on the order of the headers, not on how the
     syntax tree is nested.
-  - YAML walks its syntax tree itself. An alias has a position in a sequence but can't be addressed, and a query can't
-    express that.
   - Markdown finds its sections with the `markdown` crate, the same parser that finds its comments.
 
   Each language's tests list every symbol it finds. When you give a language symbols, also document its paths in
   `docs/symbols.md` and in the "Symbols" section of the skill, `src/skill.md`. A test in `language_parsers/mod.rs` and the
   repository's own blocks keep the list of file types with symbols, and each language's section, in sync with the
   code.
-- `src/symbols.rs` — `Symbol`, the `SymbolsParser` trait, and `resolve`, which finds the symbol a path refers to.
-  `QuerySymbolsParser` runs a language's query and finds every addressable `Symbol` in one walk of the tree, with its
-  path, its definition range and its decoded value. It suits a language whose structure is its syntax tree. It rejects
-  a file with a syntax error, instead of resolving a path through tree-sitter's error recovery. It doesn't check the
-  query itself.
+- `src/symbols/mod.rs` — `Symbol`, the `SymbolsParser` trait, and `resolve`, which finds the symbol a path refers to.
+  `ensure_no_syntax_error` refuses a file with a syntax error, instead of resolving a path through tree-sitter's error
+  recovery.
 - `src/validators/` — one file for each validator (`affects`, `check_ai`, `check_lua`, `keep_sorted`, `keep_unique`,
   `line_count`, `line_pattern`, `same_as`). Each file exports a `detect` function. `Validator::detect` in
   `validators/mod.rs` calls them from one `match`.

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

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

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

@@ -1,6 +1,6 @@
 [package]
 name = "blockwatch"
-version = "0.16.3"
+version = "0.16.5"
 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.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.16.3
+Version: 0.16.5
 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.5}/README.md

@@ -89,9 +89,9 @@ 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
-[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.
+Markdown file, a constant in a Go, C, C++, Python, Rust, TypeScript, JavaScript, Java, C#, Kotlin or Swift file, a
+field in a Protocol Buffers file, or a value in a Terraform or other HCL 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.
 
 <!-- <block name="available-validators"
      same-as="src/validators/mod.rs:validator-registry, docs/validators/README.md:validators-index"
@@ -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.5  # Use latest release
   hooks:
     - id: blockwatch
 ```
@@ -258,7 +258,7 @@ For plain git hooks, local pre-commit setups, and sandboxing untrusted Lua scrip
 - Go (with `go.mod`, `go.sum` and `go.work` support)
 - GraphQL (`.graphql`, `.graphqls`, `.gql`)
 - Groovy (with `.gradle` and `Jenkinsfile` support)
-- HCL (Terraform and OpenTofu: `.tf`, `.tfvars`, `.tofu`, `.hcl`)
+- HCL (Terraform and OpenTofu: `.tf`, `.tfvars`, `.tofu`, `.hcl`; Nomad: `.nomad`)
 - HTML (with `.xhtml` support)
 - JSON (`.json`, `.jsonc`, `.webmanifest`)
 - Java

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.5}/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.5  # 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.5  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.5}/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.5",
+          "semanticVersion": "0.16.5",
           "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.5/docs/validators/keep-sorted.md"
             }
           ]
         }

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

@@ -24,21 +24,25 @@ declares, instead of tags in a comment.
 <!-- <block name="extensions-with-symbols" same-as="src/language_parsers/mod.rs:extensions-with-symbols"
      same-as-pattern="`\.?(?P<value>[A-Za-z.]+)`"> -->
 
-| Language   | Files                                                                          | Paths                                                   |
-|------------|--------------------------------------------------------------------------------|---------------------------------------------------------|
-| JSON       | `.json`, `.jsonc`, `.webmanifest`                                              | [JSON](#json)                                           |
-| TOML       | `.toml`, `Pipfile`                                                             | [TOML](#toml)                                           |
-| YAML       | `.yaml`, `.yml`, `.cff`                                                        | [YAML](#yaml)                                           |
-| Markdown   | `.md`, `.markdown`, `.mdx`                                                     | [Markdown](#markdown)                                   |
-| Go         | `.go`                                                                          | [Go](#go)                                               |
-| C, C++     | `.c`, `.h`, `.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp`, `.hxx`                       | [C and C++](#c-and-c)                                   |
-| Python     | `.py`, `.pyi`, `.pyw`                                                          | [Python and Starlark](#python-and-starlark)             |
-| Starlark   | `.bzl`, `.bazel`, `.bzlmod`, `.star`, `BUILD`, `BUCK`, `WORKSPACE`, `Tiltfile` | [Python and Starlark](#python-and-starlark)             |
-| Rust       | `.rs`                                                                          | [Rust](#rust)                                           |
-| TypeScript | `.ts`, `.mts`, `.cts`, `.d.ts`, `.tsx`                                         | [TypeScript and JavaScript](#typescript-and-javascript) |
-| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx`                                                  | [TypeScript and JavaScript](#typescript-and-javascript) |
-| Java       | `.java`                                                                        | [Java](#java)                                           |
-| C#         | `.cs`                                                                          | [C#](#c)                                                |
+| Language         | Files                                                                          | Paths                                                   |
+|------------------|--------------------------------------------------------------------------------|---------------------------------------------------------|
+| JSON             | `.json`, `.jsonc`, `.webmanifest`                                              | [JSON](#json)                                           |
+| TOML             | `.toml`, `Pipfile`                                                             | [TOML](#toml)                                           |
+| YAML             | `.yaml`, `.yml`, `.cff`                                                        | [YAML](#yaml)                                           |
+| Markdown         | `.md`, `.markdown`, `.mdx`                                                     | [Markdown](#markdown)                                   |
+| Go               | `.go`                                                                          | [Go](#go)                                               |
+| C, C++           | `.c`, `.h`, `.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp`, `.hxx`                       | [C and C++](#c-and-c)                                   |
+| Python           | `.py`, `.pyi`, `.pyw`                                                          | [Python and Starlark](#python-and-starlark)             |
+| Starlark         | `.bzl`, `.bazel`, `.bzlmod`, `.star`, `BUILD`, `BUCK`, `WORKSPACE`, `Tiltfile` | [Python and Starlark](#python-and-starlark)             |
+| Rust             | `.rs`                                                                          | [Rust](#rust)                                           |
+| TypeScript       | `.ts`, `.mts`, `.cts`, `.d.ts`, `.tsx`                                         | [TypeScript and JavaScript](#typescript-and-javascript) |
+| 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)                                         |
+| Protocol Buffers | `.proto`                                                                       | [Protocol Buffers](#protocol-buffers)                   |
+| HCL (Terraform)  | `.tf`, `.tofu`, `.tfvars`, `.hcl`, `.nomad`                                    | [HCL](#hcl)                                             |
 
 <!-- </block> -->
 
@@ -249,8 +253,9 @@ 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, Swift and Protocol
+Buffers, the members of a type are symbols too, under the type's name: `Config.java#/Config/MAX_PORTS`. In HCL, each
+block, attribute and object key is a symbol: `main.tf#/variable/region/default`.
 
 - **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 +269,8 @@ 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, Swift, Protocol Buffers
+  and HCL.
 
 <!-- </block> -->
 
@@ -595,6 +601,261 @@ 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> -->
+
+## Protocol Buffers
+
+<!-- <block name="proto-paths"> -->
+
+```protobuf
+syntax = "proto3";
+
+package shop.v1;
+
+option go_package = "shop/v1";
+
+message Item {
+  string name = 1;
+  map<string, int32> counts = 2;
+  enum Color {
+    COLOR_UNSPECIFIED = 0;
+    RED = 1;
+    BLUE = -2;
+  }
+  oneof price {
+    int64 cents = 3;
+  }
+}
+
+service Items {
+  rpc Get(Item) returns (Item);
+}
+```
+
+| Path                 | Points at                    |
+|----------------------|------------------------------|
+| `#/Item`             | the whole message            |
+| `#/Item/name`        | `1`                          |
+| `#/Item/counts`      | `2`                          |
+| `#/Item/Color`       | the whole enum               |
+| `#/Item/Color/RED`   | `1`                          |
+| `#/Item/Color/BLUE`  | `-2`                         |
+| `#/Item/price`       | the whole oneof              |
+| `#/Item/cents`       | `3`                          |
+| `#/Items/Get`        | the whole rpc                |
+
+- **Each message, enum and service is a symbol, at any depth, and so is each field, map field, oneof, enum value and
+  rpc in it.** A proto2 group, such as `optional group Result = 4 { ... }` in `Item`, is a symbol too, with its
+  fields under it: `#/Item/Result/code`. It has no value, though it has a number.
+- **The package is not part of a path.** A file has only one, so `#/Item` is enough.
+- **An enum value sits under its enum:** `#/Item/Color/RED`.
+- **A field's value is its number, and an enum value's value is its number.** Both stay as written: `0x3` stays `0x3`,
+  and `- 2` stays `- 2`. Options after the number don't change it: `BLUE = -2 [deprecated = true]` is `-2`.
+- **A oneof's fields sit in its message**, as code reads them: `#/Item/cents`, not `#/Item/price/cents`.
+- **An extension field sits where its `extend` is written**, not in the message it extends.
+  `extend Other { int32 tag = 100; }` at the top of the file gives `#/tag`, and inside `Item` it gives `#/Item/tag`.
+- **A definition covers its whole statement**, with its label, its options and its `;`, but not the comments above it.
+- **Options are not symbols**, and neither are `syntax`, `package`, `import`, `extend` blocks, `reserved` and
+  `extensions`. To check an option such as `go_package`, wrap it in a `[[block]]` entry with a `target-pattern`.
+- **A syntax error stops the run for the definition that holds it, and for each message around it.** The other
+  definitions still resolve.
+
+<!-- </block> -->
+
+## HCL
+
+Terraform, OpenTofu, Terragrunt, Nomad and Packer files are HCL.
+
+<!-- <block name="hcl-paths"> -->
+
+```hcl
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+variable "region" {
+  default = "us-east-1"
+}
+
+locals {
+  name = "app-${var.env}"
+  tags = { Team = "core", "cost center" = 42 }
+}
+
+resource "aws_instance" "web" {
+  ami       = data.aws_ami.ubuntu.id
+  count     = (3)
+  user_data = <<-EOT
+    #!/bin/sh
+    echo hi
+  EOT
+}
+```
+
+| Path                                         | Points at                                 |
+|----------------------------------------------|-------------------------------------------|
+| `#/terraform/required_providers/aws/version` | `~> 5.0`                                  |
+| `#/variable/region`                          | the whole block                           |
+| `#/variable/region/default`                  | `us-east-1`                               |
+| `#/locals/name`                              | `"app-${var.env}"`, as written            |
+| `#/locals/tags`                              | the whole object, as written              |
+| `#/locals/tags/cost center`                  | `42`                                      |
+| `#/resource/aws_instance/web/ami`            | `data.aws_ami.ubuntu.id`                  |
+| `#/resource/aws_instance/web/count`          | `3`                                       |
+| `#/resource/aws_instance/web/user_data`      | `#!/bin/sh` and `echo hi`, each on a line |
+
+- **Each block is a symbol, at any depth, and so is each attribute and each key of an object.** A block's path is its
+  type, then each of its labels: `#/resource/aws_instance/web`. In a `.tfvars` file, each attribute sits at the top:
+  `#/region`.
+- **A path with only some of a block's labels points at nothing.** `#/resource/aws_instance` is no symbol.
+- **A block written twice in one body makes its path a violation**, such as two `ingress` blocks in a resource. Two
+  `locals` blocks make `#/locals` a violation, but `#/locals/name` still resolves when only one of them sets `name`.
+- **A key of an object is a segment when it is a name, a plain string, `true` or `false`**, such as `Team` or
+  `"cost center"`. A key written as a number or an expression, such as `3` or `(var.k)`, is not. The items of a list
+  are not symbols.
+- **A label or key with an escape, such as `"a\"b"`, gives no symbol**, and neither does anything under it.
+- **A value is the expression as written**, without parentheses around it: `count = (3)` is `3`.
+- **Strings follow HCL's escapes.** `"caf\u00e9"` is `café`, `$${` is `${`, and `%%{` is `%{`. A heredoc is its text,
+  with each line end. A `<<-` heredoc loses the indent that HCL removes. A string or heredoc with `${...}` or `%{...}`
+  stays as written. blockwatch doesn't turn text into Unicode NFC, as HCL does. A path to an escape that stands for no
+  character, such as `"\uD800"`, stops the run.
+- **A block covers its type, labels and body.** An attribute or a key covers its name and its value. Comments above
+  them are not part of them.
+- **A syntax error stops the run for the definition that holds it, and for each block around it.** After an error, the
+  parser can read the rest of the file wrongly, so a later path may not resolve.
+
+<!-- </block> -->
+
 ---
 
 [← Return to README](../README.md)

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.5}/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.5'],
     # </block>
     # Without it, setuptools takes the directories under src/ for Python packages.
     packages=[],

{blockwatch_cli-0.16.3 → blockwatch_cli-0.16.5}/src/blocks.rs

@@ -899,6 +899,10 @@ mod supported_languages_tests {
                 "tofu.tofu".to_string(),
                 "# <block>\nregion = \"eu-central-1\"\n# </block>".to_string(),
             ),
+            (
+                "nomad.nomad".to_string(),
+                "# <block>\ndatacenters = [\"dc1\"]\n# </block>".to_string(),
+            ),
             (
                 "htm.htm".to_string(),
                 "<!-- <block> -->\n<div>Content</div>\n<!-- </block> -->".to_string(),