blockwatch-cli 0.13.0__tar.gz → 0.14.1__tar.gz

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/.github/workflows/rust.yml

@@ -33,6 +33,14 @@ jobs:
         run: cargo fmt --check
       - name: Run Clippy lint
         run: cargo clippy --all-targets -- -D warnings
+      - name: Check the doc comments
+        # Nearly every item is private, so without the flag rustdoc would skip their docs.
+        run: cargo doc --no-deps --document-private-items
+        env:
+          RUSTDOCFLAGS: -D warnings
+      # `cargo llvm-cov` below does not run doctests.
+      - name: Run doctests
+        run: cargo test --doc
       - name: Run tests
         run: cargo llvm-cov --lcov --output-path coverage.lcov
       - name: Upload coverage report to Codecov

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/.pre-commit-config.yaml

@@ -34,6 +34,15 @@ repos:
         types: [ rust ]
         stages: [ pre-commit ]
         pass_filenames: false
+      - id: cargo-doc
+        name: cargo doc
+        description: Check the doc comments with rustdoc, private items included.
+        # Nearly every item is private, so without the flag rustdoc would skip their docs.
+        entry: bash -c 'RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items'
+        language: system
+        types: [ rust ]
+        stages: [ pre-commit ]
+        pass_filenames: false
 
   # Rules and the set of files linted live in `.markdownlint-cli2.yaml`, which the tool picks up
   # from the repository root. The hook passes only the staged Markdown files, so a commit is judged

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/AGENTS.md

@@ -15,6 +15,8 @@ only the lines changed in a unified diff piped into it.
 cargo run -- list '<path or glob>'         # print the blocks parsed from matching files, as JSON
 cargo llvm-cov                             # run the tests and report coverage
 cargo clippy --all-targets -- -D warnings  # lint
+cargo test --doc                           # run the examples in the doc comments (cargo llvm-cov skips them)
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items  # check the doc comments
 markdownlint-cli2                          # lint Markdown (config: .markdownlint-cli2.yaml)
 pre-commit run --all-files                 # run every hook the repository installs
 ```
@@ -105,6 +107,8 @@ The goal is a test suite that fails when behavior changes. Running every line is
 - *Always* mutation-test a new test before you call the work done. For example, flip each comparison or boundary the
   change touched, run the tests, check that one fails, then undo the flip. If the tests pass either way, they are too
   weak.
+- *Always* delete a scratch copy you made for mutation testing, with its own `target/` directory, as soon as the
+  mutation run ends. A `target/` directory takes gigabytes.
 - *Always* run the tests with coverage as the last check before you call the work done.
 - *Prefer* to read a coverage report (`cargo llvm-cov`) as a list of questions, not as a number to raise. An uncovered
   branch asks why nobody needed it. The answer is either a case worth testing or code worth deleting. *Never* add a
@@ -151,12 +155,14 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
 
 1. Parse the command-line flags (`flags.rs`, built with clap). The flags that `list` also takes are `global`, so they
    can go before or after `list`. The flags only validation uses are in `ValidationFlags`, so `list --help` doesn't
-   show them.
+   show them. `Args::validate` rejects them for `list` and `skill`. A validation run then reads the `--suppress-from`
+   files, once. Both happen before stdin or the config file is read, so a bad flag is reported first.
 2. Find the repository root and build a `fs::FileSystemImpl` limited to it. Every file read goes through it, so a path
    in a block attribute can't reach outside the repository.
 3. Decide what the run works on. With `--diff`, a unified diff is read from stdin, and
-   `diff_parser::line_changes_from_diff` turns it into a `HashMap<RepoPath, Vec<LineChange>>`. `--only-changed` also
-   limits the run to the files in that diff. Without `--diff`, stdin is never read and no block counts as changed.
+   `diff_parser::line_changes_from_diff` turns it into `DiffChanges`: a sorted `LineChanges` for each file.
+   `--only-changed` also limits the run to the files in that diff. Without `--diff`, stdin is never read and no block
+   counts as changed.
 4. Resolve the run's settings. `config::read` reads `blockwatch.toml` from the repository root, or the file given by
    `--config`. `Args::raw_settings` returns the settings given as flags. `settings::Settings::resolve` validates both
    with the same rules and merges them: the ignore globs, the extension mappings and the validator selection.
@@ -175,9 +181,9 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    touches, even when the diff does not touch that file. The result is a `blocks::FileBlocks` for each file, kept in a
    `validators::ValidationContext`. Each path or glob argument must select at least one parsed file, or the run
    stops. Under `--only-changed`, an argument that selects no file in the diff is checked against a walk of the tree.
-7. `validators::detect_validators` passes each block to the `ValidatorDetector`s, one for each validator. A detector
-   returns either `ValidatorType::Sync` or `ValidatorType::Async`. Async validators, such as `check-ai`, run on Tokio.
-   The Tokio runtime only starts if at least one async validator is needed.
+7. `validators::detect_validators` asks `Validator::detect` about each block, once for each validator. It returns
+   either `ValidatorType::Sync` or `ValidatorType::Async`. Async validators, such as `check-ai`, run on Tokio. The Tokio
+   runtime only starts if at least one async validator is needed.
 8. Validators produce `Violation`s, each with a `ViolationRange` and a `BlockSeverity` (error or warning). A symbol
    reference such as `file#/path` is found with `symbols::resolve`. It searches the symbols that
    `LanguageParser::parse_symbols` finds in the target file, once per file. A missing or ambiguous symbol is a
@@ -191,12 +197,14 @@ prints `src/skill.md` right after step 1.
 
 The main modules:
 
-- `src/fs.rs` — the `FileSystem` and `PathChecker` traits, and their real implementations. Tests use these traits to
-  swap in fakes: `FakeFileSystem` and `FakePathChecker` in `fs::test_utils`.
+- `src/fs.rs` — the `FileSystem` trait and its real implementation, and `PathFilter`, which decides whether a run
+  reads a path: it must match an allow glob and no ignore glob. Tests swap in `FakeFileSystem` from `fs::test_utils`.
+  They build a real `PathFilter` with `PathFilter::allow_all()`, `allow_only` or `with_ignored_paths`.
 - `src/settings.rs` — `RawSettings` holds the settings read from one place: the config file or the flags. `Settings` is
-  the validated and merged result. `RawSettings::validate` is the only place the rules for a setting live, so the
-  flags and the config file can't drift apart. Its errors quote the bad value but don't show a line and column.
-  Tracking where each value is written would cost more code than it saves the reader.
+  the validated and merged result. `RawSettings::parse` is the only place the rules for a setting live, so the flags
+  and the config file can't drift apart. It returns the parsed values, so nothing is parsed twice. Its errors quote the
+  bad value but don't show a line and column. Tracking where each value is written would cost more code than it saves
+  the reader.
 - `src/config.rs` — reads the config file into a `RawSettings` and the virtual blocks, using `toml_edit`'s serde
   support. Only the errors that `toml_edit` raises itself, such as an unknown key, show a line and column. An error
   about a `[[block]]` entry shows the line of its header, which `serde_spanned` gives.
@@ -217,8 +225,9 @@ The main modules:
   always the same map key.
 - `src/language_parsers/` — one tree-sitter grammar for each language. Each language has a `parser()` that returns a
   `LanguageParser`, which knows which syntax nodes are comments. `src/block_parser.rs` turns those comments into
-  blocks. `language_parsers()` in `language_parsers/mod.rs` returns the map from extension to parser. **To add a
-  language, add a module here and register it in that function.**
+  blocks. `language_parsers()` in `language_parsers/mod.rs` returns `LanguageParsers`: the parser of each extension.
+  Its `parser_for` picks the parser of a file, using the settings' extension mappings too. **To add a language, add a
+  module here and register it in that function.**
 
   Some languages also have symbols. Such a language has a `SymbolsParser`, which its `parser()` passes to
   `.with_symbols(...)`:
@@ -241,12 +250,13 @@ The main modules:
   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/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 `*ValidatorDetector`. `validators/mod.rs` registers
-  all of them.
-- `src/diff_parser.rs` — wraps `unidiff` to produce `LineChange`s. `range_intersects_any` decides whether they touch a
-  range of the file, such as a block's start tag or a symbol's definition. A block's content has its own check in
-  `blocks.rs`, because a deletion right where the content starts removes content. The results end up in
-  `is_content_modified` and `is_start_tag_modified` on `BlockWithContext`, which decide which blocks count as changed.
+  `line_count`, `line_pattern`, `same_as`). Each file exports a `detect` function. `Validator::detect` in
+  `validators/mod.rs` calls them from one `match`.
+- `src/diff_parser.rs` — wraps `unidiff` to produce `LineChange`s, kept in `LineChanges` for a file and in
+  `DiffChanges` for the whole diff. `LineChanges::touches` decides whether they touch a range of the file, such as a
+  block's start tag or a symbol's definition. A block's content has its own check in `blocks.rs`, because a deletion
+  right where the content starts removes content. The results end up in `is_content_modified` and
+  `is_start_tag_modified` on `BlockWithContext`, which decide which blocks count as changed.
 
 A block counts as changed only when its content or its start tag overlaps a `LineChange`. With
 `--diff --only-changed`, only changed blocks are validated. With `--diff` alone, every block is validated, but rules
@@ -276,9 +286,10 @@ They are not instructions for working on blockwatch, and changing them changes w
 guidance for working on blockwatch.
 
 `src/skill.md` must not hold block tags. A project that saves the skill parses it too, so each tag would become a block
-in that project. To point a block at a section of the skill, put the section between two plain comments, such as
-`<!-- json-paths -->` and `<!-- /json-paths -->`. Then add a `[[block]]` entry that matches them to `blockwatch.toml`,
-next to the others for `src/skill.md`.
+in that project. To point a block at a section of the skill, use the section's headings, such as
+`src/skill.md#/blockwatch/Symbols/JSON`. To point at only a part of a section, give that part a heading of its own.
+When the section needs a rule of its own, such as a `same-as-pattern`, add a `[[block]]` entry for it to
+`blockwatch.toml`, next to the others for `src/skill.md`.
 
 Each agent's local config directory is left out of git on purpose: `.claude/`, `.cursor/`, `.gemini/`, `.windsurf/`,
 `.aider*`, and the others listed in `.gitignore`. Don't commit agent-specific settings. Anything a future contributor

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/CHANGELOG.md

@@ -12,6 +12,45 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.14.1] - 2026-10-17
+
+### Changed
+
+- The error for a wrong `keep-sorted`, `keep-sorted-format`, `same-as-mode`, `same-as-format` or `BLOCKWATCH_LUA_MODE`
+  value now has one form, such as `invalid keep-sorted "up" (expected asc or desc)`. It lists the valid values.
+  `keep-sorted-format` did not list them before.
+- `same-as-mode`, `same-as-format` and `BLOCKWATCH_LUA_MODE` ignore upper and lower case, so `Numeric` and `Safe` work
+  like `numeric` and `safe`. `keep-sorted` and `keep-sorted-format` already did.
+- A message about a block of `keep-sorted`, `keep-unique`, `line-count`, `line-pattern`, `check-ai` or `check-lua` now
+  says `at line 3` where it said `defined at line 3`, as the messages of `affects` and `same-as` always did. For
+  example: `Block src/a.rs:limits at line 3 has an out-of-order line 5 (asc)`.
+- Every error now starts with a lowercase letter and has no period at the end. Before, about 30 started with a capital
+  letter or ended with a period. For example: `failed to read file "a.py"`, `could not find the repository root
+  directory` and `malformed block tag at line 1, column 4. If this is not meant as a tag, put it in backticks`. An
+  error that gives advice in a second sentence keeps that sentence. An error that starts with a name, such as `API` or
+  `Lua`, keeps its capital letter.
+
+## [0.14.0] - 2026-10-16
+
+### Added
+
+- `same-as-pattern` can compare a key with its value. Every named group, such as `(?P<code>\d+)` and
+  `(?P<message>.+)`, takes part, and each match is one record. So a message that moves to another code fails, even
+  though the messages alone still agree. Both patterns need the same groups. Each group can have its own
+  `same-as-format`, such as `name:identifier,value:numeric`. See
+  [Compare several groups](docs/validators/same-as.md#compare-several-groups) and
+  [A format for each group](docs/validators/same-as.md#a-format-for-each-group)
+  ([#99](https://github.com/mennanov/blockwatch/issues/99)).
+
+### Changed
+
+- A `same-as-pattern` with named groups other than `value` now compares them too. Before, only `value` counted, or the
+  whole match when the pattern had no `value` group. To keep comparing only `value`, change the other groups to
+  `(?:…)`.
+- An error about the `same-as-mode`, `same-as-format` or `same-as-pattern` of a block with `same-as` or
+  `same-as-paths` now shows the block, such as `invalid same-as attributes on block src/config.rs:limits at line 3`.
+  Before, it showed only the bad value.
+
 ## [0.13.0] - 2026-10-15
 
 ### Added

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/CLAUDE.md

@@ -15,6 +15,8 @@ only the lines changed in a unified diff piped into it.
 cargo run -- list '<path or glob>'         # print the blocks parsed from matching files, as JSON
 cargo llvm-cov                             # run the tests and report coverage
 cargo clippy --all-targets -- -D warnings  # lint
+cargo test --doc                           # run the examples in the doc comments (cargo llvm-cov skips them)
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items  # check the doc comments
 markdownlint-cli2                          # lint Markdown (config: .markdownlint-cli2.yaml)
 pre-commit run --all-files                 # run every hook the repository installs
 ```
@@ -105,6 +107,8 @@ The goal is a test suite that fails when behavior changes. Running every line is
 - *Always* mutation-test a new test before you call the work done. For example, flip each comparison or boundary the
   change touched, run the tests, check that one fails, then undo the flip. If the tests pass either way, they are too
   weak.
+- *Always* delete a scratch copy you made for mutation testing, with its own `target/` directory, as soon as the
+  mutation run ends. A `target/` directory takes gigabytes.
 - *Always* run the tests with coverage as the last check before you call the work done.
 - *Prefer* to read a coverage report (`cargo llvm-cov`) as a list of questions, not as a number to raise. An uncovered
   branch asks why nobody needed it. The answer is either a case worth testing or code worth deleting. *Never* add a
@@ -151,12 +155,14 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
 
 1. Parse the command-line flags (`flags.rs`, built with clap). The flags that `list` also takes are `global`, so they
    can go before or after `list`. The flags only validation uses are in `ValidationFlags`, so `list --help` doesn't
-   show them.
+   show them. `Args::validate` rejects them for `list` and `skill`. A validation run then reads the `--suppress-from`
+   files, once. Both happen before stdin or the config file is read, so a bad flag is reported first.
 2. Find the repository root and build a `fs::FileSystemImpl` limited to it. Every file read goes through it, so a path
    in a block attribute can't reach outside the repository.
 3. Decide what the run works on. With `--diff`, a unified diff is read from stdin, and
-   `diff_parser::line_changes_from_diff` turns it into a `HashMap<RepoPath, Vec<LineChange>>`. `--only-changed` also
-   limits the run to the files in that diff. Without `--diff`, stdin is never read and no block counts as changed.
+   `diff_parser::line_changes_from_diff` turns it into `DiffChanges`: a sorted `LineChanges` for each file.
+   `--only-changed` also limits the run to the files in that diff. Without `--diff`, stdin is never read and no block
+   counts as changed.
 4. Resolve the run's settings. `config::read` reads `blockwatch.toml` from the repository root, or the file given by
    `--config`. `Args::raw_settings` returns the settings given as flags. `settings::Settings::resolve` validates both
    with the same rules and merges them: the ignore globs, the extension mappings and the validator selection.
@@ -175,9 +181,9 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    touches, even when the diff does not touch that file. The result is a `blocks::FileBlocks` for each file, kept in a
    `validators::ValidationContext`. Each path or glob argument must select at least one parsed file, or the run
    stops. Under `--only-changed`, an argument that selects no file in the diff is checked against a walk of the tree.
-7. `validators::detect_validators` passes each block to the `ValidatorDetector`s, one for each validator. A detector
-   returns either `ValidatorType::Sync` or `ValidatorType::Async`. Async validators, such as `check-ai`, run on Tokio.
-   The Tokio runtime only starts if at least one async validator is needed.
+7. `validators::detect_validators` asks `Validator::detect` about each block, once for each validator. It returns
+   either `ValidatorType::Sync` or `ValidatorType::Async`. Async validators, such as `check-ai`, run on Tokio. The Tokio
+   runtime only starts if at least one async validator is needed.
 8. Validators produce `Violation`s, each with a `ViolationRange` and a `BlockSeverity` (error or warning). A symbol
    reference such as `file#/path` is found with `symbols::resolve`. It searches the symbols that
    `LanguageParser::parse_symbols` finds in the target file, once per file. A missing or ambiguous symbol is a
@@ -191,12 +197,14 @@ prints `src/skill.md` right after step 1.
 
 The main modules:
 
-- `src/fs.rs` — the `FileSystem` and `PathChecker` traits, and their real implementations. Tests use these traits to
-  swap in fakes: `FakeFileSystem` and `FakePathChecker` in `fs::test_utils`.
+- `src/fs.rs` — the `FileSystem` trait and its real implementation, and `PathFilter`, which decides whether a run
+  reads a path: it must match an allow glob and no ignore glob. Tests swap in `FakeFileSystem` from `fs::test_utils`.
+  They build a real `PathFilter` with `PathFilter::allow_all()`, `allow_only` or `with_ignored_paths`.
 - `src/settings.rs` — `RawSettings` holds the settings read from one place: the config file or the flags. `Settings` is
-  the validated and merged result. `RawSettings::validate` is the only place the rules for a setting live, so the
-  flags and the config file can't drift apart. Its errors quote the bad value but don't show a line and column.
-  Tracking where each value is written would cost more code than it saves the reader.
+  the validated and merged result. `RawSettings::parse` is the only place the rules for a setting live, so the flags
+  and the config file can't drift apart. It returns the parsed values, so nothing is parsed twice. Its errors quote the
+  bad value but don't show a line and column. Tracking where each value is written would cost more code than it saves
+  the reader.
 - `src/config.rs` — reads the config file into a `RawSettings` and the virtual blocks, using `toml_edit`'s serde
   support. Only the errors that `toml_edit` raises itself, such as an unknown key, show a line and column. An error
   about a `[[block]]` entry shows the line of its header, which `serde_spanned` gives.
@@ -217,8 +225,9 @@ The main modules:
   always the same map key.
 - `src/language_parsers/` — one tree-sitter grammar for each language. Each language has a `parser()` that returns a
   `LanguageParser`, which knows which syntax nodes are comments. `src/block_parser.rs` turns those comments into
-  blocks. `language_parsers()` in `language_parsers/mod.rs` returns the map from extension to parser. **To add a
-  language, add a module here and register it in that function.**
+  blocks. `language_parsers()` in `language_parsers/mod.rs` returns `LanguageParsers`: the parser of each extension.
+  Its `parser_for` picks the parser of a file, using the settings' extension mappings too. **To add a language, add a
+  module here and register it in that function.**
 
   Some languages also have symbols. Such a language has a `SymbolsParser`, which its `parser()` passes to
   `.with_symbols(...)`:
@@ -241,12 +250,13 @@ The main modules:
   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/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 `*ValidatorDetector`. `validators/mod.rs` registers
-  all of them.
-- `src/diff_parser.rs` — wraps `unidiff` to produce `LineChange`s. `range_intersects_any` decides whether they touch a
-  range of the file, such as a block's start tag or a symbol's definition. A block's content has its own check in
-  `blocks.rs`, because a deletion right where the content starts removes content. The results end up in
-  `is_content_modified` and `is_start_tag_modified` on `BlockWithContext`, which decide which blocks count as changed.
+  `line_count`, `line_pattern`, `same_as`). Each file exports a `detect` function. `Validator::detect` in
+  `validators/mod.rs` calls them from one `match`.
+- `src/diff_parser.rs` — wraps `unidiff` to produce `LineChange`s, kept in `LineChanges` for a file and in
+  `DiffChanges` for the whole diff. `LineChanges::touches` decides whether they touch a range of the file, such as a
+  block's start tag or a symbol's definition. A block's content has its own check in `blocks.rs`, because a deletion
+  right where the content starts removes content. The results end up in `is_content_modified` and
+  `is_start_tag_modified` on `BlockWithContext`, which decide which blocks count as changed.
 
 A block counts as changed only when its content or its start tag overlaps a `LineChange`. With
 `--diff --only-changed`, only changed blocks are validated. With `--diff` alone, every block is validated, but rules
@@ -276,9 +286,10 @@ They are not instructions for working on blockwatch, and changing them changes w
 guidance for working on blockwatch.
 
 `src/skill.md` must not hold block tags. A project that saves the skill parses it too, so each tag would become a block
-in that project. To point a block at a section of the skill, put the section between two plain comments, such as
-`<!-- json-paths -->` and `<!-- /json-paths -->`. Then add a `[[block]]` entry that matches them to `blockwatch.toml`,
-next to the others for `src/skill.md`.
+in that project. To point a block at a section of the skill, use the section's headings, such as
+`src/skill.md#/blockwatch/Symbols/JSON`. To point at only a part of a section, give that part a heading of its own.
+When the section needs a rule of its own, such as a `same-as-pattern`, add a `[[block]]` entry for it to
+`blockwatch.toml`, next to the others for `src/skill.md`.
 
 Each agent's local config directory is left out of git on purpose: `.claude/`, `.cursor/`, `.gemini/`, `.windsurf/`,
 `.aider*`, and the others listed in `.gitignore`. Don't commit agent-specific settings. Anything a future contributor

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/Cargo.lock

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

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/Cargo.toml

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

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

@@ -94,6 +94,7 @@ 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"
+     same-as-format="identifier"
      same-as-pattern='^\|\s*\[`(?P<value>[a-z-]+)`\]'> -->
 
 | Validator                                         | Description                                                                                  | Attributes                                                                      |
@@ -214,7 +215,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.13.0  # Use latest release
+  rev: v0.14.1  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/blockwatch.toml

@@ -40,41 +40,14 @@ same-as = '''.github/workflows/codeql.yml,
 same-as-pattern = '(?:actions/checkout@|^)(?P<value>v\d+)$'
 
 # `blockwatch skill` prints src/skill.md, and projects save that output. A tag in that file would become a block in
-# every one of those projects. So the file marks its sections with plain comments, which are not tags, and these
-# entries make each marked section a named block.
+# every one of those projects. So blocks point at its sections by their headings, and these entries hold the pattern
+# that reads a section, which the section can't hold itself.
 [[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- validator-catalog -->.*<!-- /validator-catalog -->'
-name = 'validator-catalog'
-
-[[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- validator-reference -->.*<!-- /validator-reference -->'
+target = 'src/skill.md#/blockwatch/Validator reference'
 name = 'validator-reference'
 same-as-pattern = '^\|\s*`(?P<value>[a-z-]+)`'
 
 [[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- extensions-with-symbols -->.*<!-- /extensions-with-symbols -->'
+target = 'src/skill.md#/blockwatch/Symbols/Files with symbols'
 name = 'extensions-with-symbols'
 same-as-pattern = '`\.?(?P<value>[A-Za-z]+)`'
-
-[[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- json-paths -->.*<!-- /json-paths -->'
-name = 'json-paths'
-
-[[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- toml-paths -->.*<!-- /toml-paths -->'
-name = 'toml-paths'
-
-[[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- yaml-paths -->.*<!-- /yaml-paths -->'
-name = 'yaml-paths'
-
-[[block]]
-target = 'src/skill.md'
-target-pattern = '(?s)<!-- markdown-paths -->.*<!-- /markdown-paths -->'
-name = 'markdown-paths'

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/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.13.0  # Use latest release
+  rev: v0.14.1  # 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.13.0  # Use latest release
+  rev: v0.14.1  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/docs/cli.md

@@ -172,7 +172,7 @@ describe the input rather than the command that produced it, since a diff need n
 
 ```console
 $ git diff --no-prefix | blockwatch --diff
-Error: diff target "rules.py" has no recognized path prefix (a/, b/, i/, w/, c/, o/).
+Error: diff target "rules.py" has no recognized path prefix (a/, b/, i/, w/, c/, o/)
 ```
 
 With Git, that means `--no-prefix`, `diff.noprefix`, or a custom `diff.srcPrefix` / `diff.dstPrefix`. To produce
@@ -555,15 +555,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.13.0",
-          "semanticVersion": "0.13.0",
+          "version": "0.14.1",
+          "semanticVersion": "0.14.1",
           "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.13.0/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.14.1/docs/validators/keep-sorted.md"
             }
           ]
         }
@@ -574,7 +574,7 @@ Nothing else about the run changes: the same violations are found, and the exit
           "ruleId": "keep-sorted",
           "ruleIndex": 0,
           "level": "error",
-          "message": { "text": "Block fruits.py:fruits defined at line 2 has an out-of-order line 4 (asc)" },
+          "message": { "text": "Block fruits.py:fruits at line 2 has an out-of-order line 4 (asc)" },
           "locations": [
             {
               "physicalLocation": {

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/docs/validators/README.md

@@ -23,8 +23,10 @@ between two references is fine.
 
 ## Which validator do I want?
 
-<!-- <block name="validators-index" affects="src/skill.md:validator-catalog"
+<!-- <block name="validators-index"
+     affects="src/skill.md#/blockwatch/Annotating a new project/Where blocks add value (catalog)"
      same-as="src/validators/mod.rs:validator-registry, README.md:available-validators"
+     same-as-format="identifier"
      same-as-pattern='\[`(?P<value>[a-z-]+)`\]\('> -->
 
 | I want to...                                                  | Use                               |

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.1}/docs/validators/check-lua.md

@@ -158,7 +158,7 @@ end
 ```
 
 <!-- <block name="lua-safety-modes" same-as="src/validators/check_lua.rs:lua-safety-modes"
-     same-as-pattern='^\|\s*`(?P<value>[a-z]+)`'> -->
+     same-as-format="identifier" same-as-pattern='^\|\s*`(?P<value>[a-z]+)`'> -->
 
 ## Safety modes
 
@@ -182,8 +182,9 @@ BLOCKWATCH_LUA_MODE=unsafe blockwatch
 | `safe`                | All memory-safe libraries (including `io`, `os`, `package`)           | Memory-safe - Allows file/OS access |
 | `unsafe`              | All Lua standard libraries with no restrictions (including C modules) | Unsafe - Full system access         |
 
-An empty value means `sandboxed`, the same as an unset variable. Any other value, such as `Safe`, stops a run that
-checks a `check-lua` block. The error lists the valid values.
+An empty value means `sandboxed`, the same as an unset variable. Upper and lower case do not matter, so `Safe` works
+like `safe`. Any other value, such as `sandbox`, stops a run that checks a `check-lua` block. The error lists the valid
+values.
 
 If a script uses a library that is not available in the selected mode, the run stops with a Lua error. The block is not
 reported as a violation — the whole run fails. So a script that needs `io` or `os` will fail every `sandboxed` run,