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

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

@@ -235,7 +235,7 @@ The main modules:
   Some languages also have symbols. Such a language has a `SymbolsParser`, which its `parser()` passes to
   `.with_symbols(...)`:
 
-  - JSON and YAML walk their syntax trees themselves, and refuse a file with a syntax error.
+  - JSON, YAML and XML 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.
   - Markdown finds its sections with the `markdown` crate, the same parser that finds its comments.

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

@@ -12,6 +12,41 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.16.7] - 2026-11-04
+
+### Added
+
+- Symbols in PHP files (`.php` and `.phtml`). `Invoice.php#/Invoice/STATUS_PAID` points at a class constant,
+  `#/Invoice/$perPage` at a property, and `version.php#/$wp_version` at a top-level variable. A
+  `define('NAME', value)` call is a symbol too, at `#/NAME`. The namespace is not part of a path. See
+  [PHP](docs/symbols.md#php).
+- Symbols in shell scripts (`.sh`, `.bash`, `.bashrc`, `.bash_profile` and `.envrc`). `install.sh#/GO_VERSION`
+  points at the value of a variable, and `#/log` at a function. A name counts when it is set outside functions, loops
+  and subshells. zsh files have no symbols. See [Shell](docs/symbols.md#shell).
+
+### Fixed
+
+- A Python or Starlark string with an escape that Python rejects, such as `"\x4"` or `"\N"`, gave its text as the
+  value. Now a path to it stops the run, as a path to a string with a `\N{...}` escape does.
+
+## [0.16.6] - 2026-11-04
+
+### Added
+
+- Symbols in XML files: `.xml`, the MSBuild files (`.csproj`, `.fsproj`, `.vbproj`, `.vcxproj`, `.props`,
+  `.targets`), `.xaml`, `.xsd`, `.xsl` and `.xslt`. `pom.xml#/project/version` points at the text of an element, and
+  `#/Project/@Sdk` at the value of an attribute. A filter picks one of several elements with one name:
+  `#/project/dependencies/~[artifactId=guava]/version`. See [XML](docs/symbols.md#xml).
+- A filter picks one of several items that share a path, such as two `ingress` blocks in HCL:
+  `#/resource/aws_security_group/web/~[from_port=443]/to_port`. Before, the path was ambiguous. See
+  [Picking an item by a key's value](docs/symbols.md#picking-an-item-by-a-keys-value).
+
+### Fixed
+
+- A filter over several items that share a path could read a key of another item, when only that item had the key.
+- A filter could pick the wrong item when an item had a syntax error or a string that blockwatch can't decode. Now
+  such a path stops the run, as a path to that item does.
+
 ## [0.16.5] - 2026-11-03
 
 ### Added

{blockwatch_cli-0.16.5 → blockwatch_cli-0.16.7}/CLAUDE.md

@@ -235,7 +235,7 @@ The main modules:
   Some languages also have symbols. Such a language has a `SymbolsParser`, which its `parser()` passes to
   `.with_symbols(...)`:
 
-  - JSON and YAML walk their syntax trees themselves, and refuse a file with a syntax error.
+  - JSON, YAML and XML 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.
   - Markdown finds its sections with the `markdown` crate, the same parser that finds its comments.

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

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

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

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

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

@@ -89,9 +89,10 @@ 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, 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.
+Markdown file, an element or attribute in an XML file such as `pom.xml` or a `.csproj`, a constant in a Go, C, C++,
+Python, Rust, TypeScript, JavaScript, Java, C#, Kotlin, Swift or PHP file, a variable in a shell script, 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 +220,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.5  # Use latest release
+  rev: v0.16.7  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.16.5 → blockwatch_cli-0.16.7}/blockwatch.toml

@@ -50,4 +50,4 @@ same-as-pattern = '^\|\s*`(?P<value>[a-z-]+)`'
 [[block]]
 target = 'src/skill.md#/blockwatch/Symbols/Files with symbols'
 name = 'extensions-with-symbols'
-same-as-pattern = '`\.?(?P<value>[A-Za-z.]+)`'
+same-as-pattern = '`\.?(?P<value>[A-Za-z._]+)`'

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

{blockwatch_cli-0.16.5 → blockwatch_cli-0.16.7}/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.5",
-          "semanticVersion": "0.16.5",
+          "version": "0.16.7",
+          "semanticVersion": "0.16.7",
           "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.5/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.16.7/docs/validators/keep-sorted.md"
             }
           ]
         }

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

@@ -22,27 +22,30 @@ declares, instead of tags in a comment.
 ## Files with symbols
 
 <!-- <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)                                                |
-| 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)                                             |
+     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)                                   |
+| XML              | `.xml`, `.csproj`, `.fsproj`, `.vbproj`, `.vcxproj`, `.props`, `.targets`, `.xaml`, `.xsd`, `.xsl`, `.xslt` | [XML](#xml)                                             |
+| 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)                                             |
+| PHP              | `.php`, `.phtml`                                                                                            | [PHP](#php)                                             |
+| Shell            | `.sh`, `.bash`, `.bashrc`, `.bash_profile`, `.envrc`                                                        | [Shell](#shell)                                         |
 
 <!-- </block> -->
 
@@ -97,6 +100,12 @@ services:
 - **A filter picks a map entry too.** In `{"a": {"name": "x"}}`, `#/~[name=x]` is `#/a`.
 - **A path can hold several filters**, such as `#/groups/~[name=api]/services/~[name=web]/port`. A filter can come
   first, in a file that is a list: `#/~[name=web]`.
+- **When several items share a path, the rest of the path looks only inside the item the filter picked.** For
+  example, two `ingress` blocks in an HCL resource share a path.
+  `#/resource/aws_security_group/web/~[from_port=443]/to_port` is the `to_port` of the block whose `from_port` is
+  `443`.
+- **A filter that reaches an unreadable path stops the run**, as that path does. An item blockwatch can't read, such
+  as one with a syntax error, also stops a filter that compares its key, because that item could match too.
 - **The value starts after the first `=` and ends at the last `]`,** so it can hold both. The key can't hold `=`.
   Inside a filter, escape the key and the value like any key: `/` as `~1`, `,` as `%2C`, and so on.
 
@@ -247,15 +256,78 @@ Clone the repository.
 
 <!-- </block> -->
 
+## XML
+
+`.xml` files have symbols, and so do the MSBuild files (`.csproj`, `.fsproj`, `.vbproj`, `.vcxproj`, `.props`,
+`.targets`), `.xaml`, `.xsd`, `.xsl` and `.xslt`.
+
+<!-- <block name="xml-paths"> -->
+
+Every element and every attribute is a symbol. A path is each element's name, from the root element down. An attribute
+is `@` and its name, under its element:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+  <version>1.4.2</version>
+  <dependencies>
+    <dependency>
+      <artifactId>junit</artifactId>
+      <version>5.10.0</version>
+    </dependency>
+    <dependency scope="test">
+      <artifactId>guava</artifactId>
+      <version>33.0.0-jre</version>
+    </dependency>
+  </dependencies>
+  <description>
+    Tools &amp; helpers
+  </description>
+</project>
+```
+
+| Path                                                 | Points at                       |
+|------------------------------------------------------|---------------------------------|
+| `#/project/version`                                  | `1.4.2`                         |
+| `#/project/dependencies`                             | the whole element               |
+| `#/project/dependencies/dependency/version`          | a violation: two elements match |
+| `#/project/dependencies/~[artifactId=guava]/version` | `33.0.0-jre`                    |
+| `#/project/dependencies/~[artifactId=guava]/@scope`  | `test`                          |
+| `#/project/description`                              | `Tools & helpers`               |
+
+- **Elements with one name under one parent share a path**, such as the two `dependency` elements above. A path through
+  them is a violation, so pick one with a [filter](#picking-an-item-by-a-keys-value). Its key can be a child element,
+  such as `artifactId`, or an attribute. In a `.csproj` file, `#/Project/ItemGroup/~[@Include=Serilog]/@Version` is
+  the `Version` of the `PackageReference` whose `Include` is `Serilog`. A position, such as
+  `#/project/modules/module/1`, is not found.
+- **A prefix is part of the name, as written.** Escape its `:` as `%3A`: `#/manifest/application/@android%3Aname`.
+  Namespaces play no part, and `xmlns` attributes are not symbols. Names compare as written, case included.
+- **An element without child elements is its text.** Entities and character references are decoded, CDATA stays as
+  written, and comments are left out. The white space around the text is removed, but the line breaks and indents
+  inside it stay. `<a/>` and `<a></a>` are empty strings.
+- **An element with child elements has no value.** It gives its whole text, tags included, even when it also holds
+  text.
+- **An attribute is its decoded value.** Each tab and line break in it becomes a space, as XML requires. The white
+  space around it stays.
+- **An entity that the DOCTYPE declares stops the run for its path**, because it can stand for any text, even
+  elements. So does a reference to a character that XML forbids, such as `&#0;`.
+- **The XML declaration, the DOCTYPE, comments and processing instructions are not symbols.**
+- **An element covers its start tag, its content and its end tag.** An attribute covers `name="value"`. A comment
+  above an element is not part of it.
+- **A syntax error anywhere stops the run**, and so does an empty file. A few valid files stop it too, because of the
+  parser: a DOCTYPE without white space before its `]`, as in `[<!ENTITY e "x">]`, and a processing instruction with
+  data, such as `<?pi x?>`, inside an element.
+
+<!-- </block> -->
+
 ## Code files
 
 <!-- <block name="code-files"> -->
 
 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, 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`.
+With `const MaxPorts = 8` in `consts.go`, `consts.go#/MaxPorts` points at `8`. In Java, C#, Kotlin, Swift, Protocol
+Buffers and PHP, 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.
@@ -269,8 +341,8 @@ block, attribute and object key is a symbol: `main.tf#/variable/region/default`.
   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, C#, Kotlin, Swift, Protocol Buffers
-  and HCL.
+- **Members are not symbols yet**, such as a method or a field, except in Java, C#, Kotlin, Swift, Protocol Buffers,
+  HCL and PHP.
 
 <!-- </block> -->
 
@@ -396,7 +468,8 @@ def load(path):
   value: `type Pair[T] = tuple[T, T]` is `#/Pair`.
 - **Strings follow Python's escapes.** `"\xe9"` is `é`. An escape Python doesn't know, such as `\d`, stays as written.
   A raw string is its text. An f-string without a field is its text, with `{{` as `{`. An f-string with a field and
-  bytes stay as written. A path to a string with a `\N{...}` escape stops the run.
+  bytes stay as written. A path to a string with a `\N{...}` escape stops the run, and so does a path to a string
+  with an escape that Python rejects, such as `"\x4"` or `"\N"`.
 - **Starlark files, such as `BUILD` and `.bzl`, follow the same rules.** A rule call, such as
   `cc_library(name = "lib")`, is not a symbol.
 - **Class members are not symbols yet.**
@@ -840,6 +913,7 @@ resource "aws_instance" "web" {
 - **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 filter picks one of the blocks: `#/resource/aws_security_group/web/~[from_port=443]/to_port`.
 - **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.
@@ -856,6 +930,159 @@ resource "aws_instance" "web" {
 
 <!-- </block> -->
 
+## PHP
+
+<!-- <block name="php-paths"> -->
+
+```php
+<?php
+namespace App\Billing;
+
+const MAX_RETRIES = 3;
+define('API_URL', 'https://api.example.com');
+$version = '2.4.1';
+
+if (!function_exists('money')) {
+    function money(int $cents): string { return number_format($cents / 100, 2); }
+}
+
+#[Entity]
+final class Invoice extends Model
+{
+    public const STATUS_PAID = 'paid';
+    protected static int $perPage = 25;
+    protected $table;
+
+    public function __construct(private readonly string $currency = "EUR") {}
+
+    public function table(): string { return $this->table; }
+}
+
+enum Status: string
+{
+    case Open = 'open';
+    case Paid = 'paid';
+}
+```
+
+| Path                    | Points at                                       |
+|-------------------------|-------------------------------------------------|
+| `#/MAX_RETRIES`         | `3`                                             |
+| `#/API_URL`             | `https://api.example.com`                       |
+| `#/$version`            | `2.4.1`                                         |
+| `#/money`               | the whole function                              |
+| `#/Invoice`             | the whole class, with `#[Entity]`               |
+| `#/Invoice/STATUS_PAID` | `paid`                                          |
+| `#/Invoice/$perPage`    | `25`                                            |
+| `#/Invoice/$table`      | `protected $table;`, as it has no default       |
+| `#/Invoice/$currency`   | `EUR`                                           |
+| `#/Invoice/table`       | the whole method                                |
+| `#/Status/Paid`         | `paid`                                          |
+| `#/App`                 | nothing, as a namespace is not a symbol         |
+
+- **Each top-level constant, variable, function, class, interface, trait and enum is a symbol, and so is each member
+  of a type**: a constant, a property, a method or an enum case. Both `const NAME = value;` and
+  `define('NAME', value);` define a constant.
+- **The namespace is not part of a path.** Two namespaces in one file that define one name make that path a
+  violation.
+- **A property and a variable keep their `$`**: `#/Invoice/$perPage`. So `$table` and `table()` have different paths.
+- **A top-level variable is a symbol**: `$version = '2.4.1';` is `#/$version`. Only `$name = value` counts, not
+  `$items['key'] = 1` or `$object->name = 1`. In `$a = $b = 1`, only `$a` is a symbol, and its value is `$b = 1`.
+- **A constructor parameter with a visibility is a property**: `private readonly string $currency` gives
+  `#/Invoice/$currency`. Its value is its default.
+- **A definition in an `if`, `else`, `try`, `catch`, `finally`, `switch`, `declare` or `{ }` block counts**, such as a
+  function in `if (!function_exists('money'))`. One in a loop doesn't. A name defined in both branches of an `if` is a
+  violation.
+- **Inside a function or a method, only a `define` is a symbol, and its path has no parent.** `define('BOOTED', 1);`
+  in the method `Kernel::boot()` gives `#/BOOTED`. Local variables, and functions and classes declared in a function,
+  are not symbols. Neither are closures, arrow functions and anonymous classes, or a `define` in them.
+- **A `define` counts only as a whole statement whose name is plain text.** It covers the statement, with its `;`.
+  `define($name, 1)`, `define('A\\', 1)`, `defined('X') or define('X', 1)` and a call with named arguments are not
+  symbols.
+- **Names compare as written.** PHP ignores the case of class, function and method names, but `#/MONEY` doesn't find
+  `function money`.
+- **Attributes are part of a definition. Doc comments are not.** In `const A = 1, B = 2;` and `public $a = 1, $b;`,
+  each name covers only its own part.
+- **`namespace`, `use` imports, trait uses and `declare(strict_types=1)` are not symbols.** A trait's members sit under
+  the trait, not under the classes that use it. The keys of an array, such as `return ['timezone' => 'UTC']` in a
+  Laravel config file, are not symbols yet.
+- **Strings follow PHP's escapes.** `'it\'s'` is `it's`, and `"caf\u{e9}"` is `café`. A heredoc or a nowdoc loses the
+  closing marker's indent on each line. A string with a variable, such as `"v$major"` or `"{$a}"`, stays as written.
+  So does a string whose bytes are not UTF-8, such as `"\xFF"`, and a string that PHP rejects.
+- **In a template, the symbols come from the PHP code.** The HTML around it is skipped.
+- **A syntax error stops the run for the definition that holds it, and for each type around it.** The other
+  definitions still resolve. The parser fails on a constructor parameter with `readonly` but no visibility, such as
+  `__construct(readonly int $id)`, so a path into its class stops the run.
+
+<!-- </block> -->
+
+## Shell
+
+<!-- <block name="shell-paths"> -->
+
+```bash
+#!/usr/bin/env bash
+GO_VERSION=1.22.5
+export REGISTRY='ghcr.io/acme'
+readonly IMAGE="${REGISTRY}/app:${GO_VERSION}"
+PORT="${PORT:-8080}"
+TARGETS=(linux darwin)
+
+if [[ "$(uname)" == Darwin ]]; then
+  SED=gsed
+else
+  SED=sed
+fi
+
+log() { echo "$@" >&2; }
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --go) GO_VERSION="$2"; shift 2 ;;
+  esac
+done
+```
+
+| Path           | Points at                                            |
+|----------------|------------------------------------------------------|
+| `#/GO_VERSION` | `1.22.5`, as the copy in the loop doesn't count      |
+| `#/REGISTRY`   | `ghcr.io/acme`                                       |
+| `#/IMAGE`      | `"${REGISTRY}/app:${GO_VERSION}"`, as written        |
+| `#/PORT`       | `"${PORT:-8080}"`, as written                        |
+| `#/TARGETS`    | `(linux darwin)`, as written                         |
+| `#/SED`        | a violation, as both branches define it              |
+| `#/log`        | the whole function                                   |
+
+- **A variable or a function set outside functions, loops and subshells is a symbol.** The conditions and bodies of
+  `if`, the items of `case`, `{ ... }` groups and the commands of `&&` and `||` count. So a name set in two branches
+  is defined twice. Names set in `for`, `while` and `until` loops, in `( ... )`, in functions and in a statement that
+  ends with `&` don't count, as bash sets them in a subshell or each time the loop runs.
+- **`export`, `readonly`, `declare` and `typeset` set a name too**, with or without flags such as `-r`. When the
+  statement sets one name, the symbol covers the whole statement. In `export A=1 B=2`, `A` covers only `A=1`. The
+  value is still the one written: bash stores `abc` for `declare -l X=ABC` and `3` for `declare -i X=1+2`, but the
+  path gives `ABC` and `1+2`.
+- **These are not symbols:** `NAME+=value`, `A[0]=x`, `FOO=1 make` (it sets `FOO` only for `make`), `export NAME`
+  without `=`, `local`, `: "${NAME:=default}"`, and names set by `read`, `for` or `getopts`.
+- **Strings follow bash's quoting.** `'a b'` is `a b`. In `"..."`, only `\$`, `` \` ``, `\"` and `\\` lose their
+  backslash, and a `\` at the end of a line goes away with the line end. Outside quotes, every backslash goes:
+  `a\ b` is `a b`. Parts written together are joined: `"a"'b'c` is `abc`. `X=` is the empty string.
+- **A value that bash expands stays as written**, such as `$HOME`, `$(cmd)`, `` `cmd` `` or `~/bin`. So does a word
+  that starts with `~` after a quote, such as `"a"~/b`, and an array. Use `same-as-pattern` to take `8080` out of
+  `"${PORT:-8080}"`.
+- **A path to a `$'...'` or `$"..."` string stops the run.**
+- **A function's name can hold `-`, `.` and `:`.** Write each `:` as `%3A`: `ns::helper` is `#/ns%3A%3Ahelper`.
+- **zsh files (`.zsh`, `.zshrc`) have no symbols.** The parser misreads much of zsh's syntax.
+- **After a syntax error, the parser often skips a large part of the file**, and every name in that part stops the
+  run. It fails on `sed -e /^$/d`, on `${x/#$/y}`, and on a command whose name holds `::` after an assignment, such as
+  `V=2 ns::log "x"`. A comment in backticks, such as `` find . `# skip vendor` -name x ``, is worse: the parser reads
+  the rest of the file as the command's argument, so no name after it is found.
+- **A value outside quotes that goes on to the next line after a `\` is not found.** The parser reads `X=a\` and `b`
+  on the next line as `X=a` set only for a command `b`. Bash sets `X=ab`. Put the value in quotes instead.
+- **A value that ends with a lone `$` takes in the next line.** In `Z=$` followed by `W=1`, `#/Z` gives `$`, the line
+  end and `W=1`, as written, and `#/W` is not found. Bash sets `Z` to `$`. Write `Z='$'` instead.
+
+<!-- </block> -->
+
 ---
 
 [← Return to README](../README.md)

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