blockwatch-cli 0.14.0__tar.gz → 0.14.2__tar.gz

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/.github/workflows/pypi.yml

@@ -24,9 +24,9 @@ jobs:
             target: x86_64-unknown-linux-gnu
           - runner: ubuntu-24.04-arm
             target: aarch64-unknown-linux-gnu
-          - runner: macos-14
+          - runner: macos-15
             target: aarch64-apple-darwin
-          - runner: macos-14
+          - runner: macos-15
             target: x86_64-apple-darwin
           - runner: windows-latest
             target: x86_64-pc-windows-msvc

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/.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.14.0 → blockwatch_cli-0.14.2}/.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.14.0 → blockwatch_cli-0.14.2}/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
@@ -187,16 +193,19 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    report goes to stdout. The exit code depends on the error-severity violations that are not suppressed.
 
 The `list` subcommand stops after step 6 and writes the blocks it found to stdout as JSON. The `skill` subcommand
-prints `src/skill.md` right after step 1.
+prints `src/skill.md` right after step 1. The `explain` subcommand runs like `--only-block` with the file of its
+address as the only path. It then writes that block to stdout as JSON.
 
 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 +226,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 +251,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

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/CHANGELOG.md

@@ -12,6 +12,56 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.14.2] - 2026-10-21
+
+### Added
+
+- `line-count-pattern` makes `line-count` count only the lines that match the regex. For example,
+  `line-count="<=20" line-count-pattern='^"\w+",$'` skips comments and blank lines in a list. See
+  [`line-count`](docs/validators/line-count.md).
+- `blockwatch explain FILE:BLOCK_NAME` checks one named block and prints it as JSON: its attributes, the text its
+  validators read and where that text is. For example: `blockwatch explain package.json:version`. The output also lists
+  the validators the block asks for but the settings turn off (`"disabled"`). Under `"checks"`, it shows what each
+  validator saw:
+  - `same-as`: each record the pattern matched, with its line, on both sides, and the reason of each mismatch.
+  - `keep-sorted` and `keep-unique`: the value each line gives, up to the first line out of order or repeated.
+  - `line-pattern`: what each pattern matched on each line, up to the first line that fails.
+  - `affects`: whether the block changed, and for each target, whether it changed or why it doesn't resolve.
+  - `line-count`: the value each line gives, how many lines count, and the rule they were checked against.
+  - `check-lua`: the `content` and `ctx.affects` the script got, and the message it returned.
+  - `check-ai`: the model, the prompt it was sent and its answer.
+
+  `"with_diff"` says whether `--diff` was given. Without it, no block counts as changed. Violations go to stderr, and
+  the exit code is the same as for a normal run. See [The `explain` Command](docs/cli.md#the-explain-command).
+
+### Changed
+
+- A message of `affects` or `same-as` about a whole-file target shows the path alone, without `file` in front. For
+  example: `Block a.py:b at line 1 is modified, but config.json is not`.
+
+### Fixed
+
+- A `check-lua` script got no `ctx.affects` entry for a block target that the run didn't check, such as with
+  `--only-block` or `--diff --only-changed`. Now `ctx.affects` holds the same targets in every run.
+
+## [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

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/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
@@ -187,16 +193,19 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    report goes to stdout. The exit code depends on the error-severity violations that are not suppressed.
 
 The `list` subcommand stops after step 6 and writes the blocks it found to stdout as JSON. The `skill` subcommand
-prints `src/skill.md` right after step 1.
+prints `src/skill.md` right after step 1. The `explain` subcommand runs like `--only-block` with the file of its
+address as the only path. It then writes that block to stdout as JSON.
 
 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 +226,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 +251,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

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/Cargo.lock

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

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/Cargo.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.14.0
+Version: 0.14.2
 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.14.0 → blockwatch_cli-0.14.2}/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                                                                      |
@@ -103,7 +104,7 @@ you'd otherwise have to nitpick in code review.
 | [`keep-sorted`](docs/validators/keep-sorted.md)   | Enforces alphabetical or numerical ordering on list items                                    | `keep-sorted`, `keep-sorted-pattern`, `keep-sorted-format`                      |
 | [`keep-unique`](docs/validators/keep-unique.md)   | Prevents duplicate lines within a block                                                      | `keep-unique`                                                                   |
 | [`line-pattern`](docs/validators/line-pattern.md) | Enforces that every line matches a regex, or that no line matches a forbidden one            | `line-pattern`, `line-pattern-forbidden`                                        |
-| [`line-count`](docs/validators/line-count.md)     | Enforces lower or upper bounds on the number of lines in a block                             | `line-count`                                                                    |
+| [`line-count`](docs/validators/line-count.md)     | Enforces lower or upper bounds on the number of lines in a block                             | `line-count`, `line-count-pattern`                                              |
 | [`check-ai`](docs/validators/check-ai.md)         | Validates content against natural language rules using an LLM                                | `check-ai`, `check-ai-pattern`                                                  |
 | [`check-lua`](docs/validators/check-lua.md)       | Runs custom validation logic written in Lua                                                  | `check-lua`, `check-lua-pattern`, `check-lua-timeout`                           |
 
@@ -172,6 +173,9 @@ git diff --patch HEAD | blockwatch --diff --only-changed
 
 # Dump all discovered blocks as JSON
 blockwatch list
+
+# Show what each validator of one named block read
+blockwatch explain src/lib.rs:languages
 ```
 
 Rules live in comments, next to the code they describe. Settings that apply to the whole project, such as ignored
@@ -214,7 +218,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.14.0  # Use latest release
+  rev: v0.14.2  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/dist-workspace.toml

@@ -27,7 +27,7 @@ publish-jobs = ["homebrew"]
 global = "ubuntu-latest"
 
 [dist.github-custom-runners.aarch64-apple-darwin]
-runner = "macos-14"
+runner = "macos-15"
 
 [dist.github-custom-runners.x86_64-unknown-linux-gnu]
 runner = "ubuntu-latest"

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/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.14.0  # Use latest release
+  rev: v0.14.2  # 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.14.0  # Use latest release
+  rev: v0.14.2  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/docs/cli.md

@@ -14,6 +14,8 @@ For command-line flag documentation directly in your terminal, run `blockwatch -
   every block in the repository.
 - **List Blocks**: `blockwatch list` outputs a JSON report of all discovered blocks. It takes `--diff`,
   `--only-changed`, `--config`, `-E` and `--ignore`.
+- **Explain a Block**: `blockwatch explain FILE:BLOCK_NAME` checks one named block and prints what each of its
+  validators read, as JSON. See [The `explain` Command](#the-explain-command).
 - **Print the Agent Skill**: `blockwatch skill` prints the [skill for AI agents](#the-skill-command), as a `SKILL.md`
 - **Config File**: `blockwatch --config FILE` reads the project's settings from FILE instead of `blockwatch.toml`
 - **Custom Extensions**: Map custom file extensions: `blockwatch -E ino=cpp` (config key: `extensions`)
@@ -172,7 +174,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 +557,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.14.0",
-          "semanticVersion": "0.14.0",
+          "version": "0.14.2",
+          "semanticVersion": "0.14.2",
           "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.14.0/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.14.2/docs/validators/keep-sorted.md"
             }
           ]
         }
@@ -574,7 +576,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": {
@@ -617,7 +619,7 @@ What to expect from the log:
 - **Lines and columns are 1-based, with an exclusive end column.** A column counts characters, which the run declares as
   `"columnKind": "unicodeCodePoints"` so that a consumer does not count UTF-16 code units instead.
 
-`--format` cannot be combined with the `list` subcommand, which reports blocks rather than violations. To upload a log
+`--format` cannot be combined with the `list` and `explain` subcommands, which write JSON of their own. To upload a log
 to GitHub code scanning, see [CI Integration](ci.md#github-code-scanning).
 
 ## The `list` Command
@@ -701,6 +703,104 @@ block's attributes are sorted by name; the files themselves are not ordered, and
 emit them differently. Sort by key downstream if you need to diff one run against another — or use
 [`--verbosity full`](#full-reports), which does order its files.
 
+## The `explain` Command
+
+`blockwatch explain FILE:BLOCK_NAME` checks one named block and prints what each of its validators read, as JSON. Run it
+after you write a rule, to see that the rule matches what you meant. A rule can be wrong and still pass. For example, a
+`same-as-pattern` can take the same wrong part of each line on both sides.
+
+```shell
+blockwatch explain src/colors.py:colors
+blockwatch explain package.json:version                              # a block from blockwatch.toml
+git diff --patch | blockwatch explain --diff src/colors.py:colors   # affects needs the diff
+```
+
+- It takes one address, as `--only-block` does. A block without a `name` can't be explained, so give it one first.
+- It takes `--diff`, `--config`, `-E` and `--ignore`, and rejects the other flags.
+- `only-blocks` and `skip-blocks` in `blockwatch.toml` play no part, because the address already picks the block.
+  `enable` and `disable` still apply.
+- The explanation goes to stdout. Violations go to stderr, and the [exit code](#exit-codes) is the one a normal run
+  gives. `check-ai` calls the API, as in a normal run.
+
+### Explain Output Example
+
+For this block:
+
+```python
+COLORS = [
+    # <block name="colors" keep-sorted="asc" keep-sorted-pattern='"(?P<value>\w+)"'>
+    "blue",
+    "red",
+    # </block>
+]
+```
+
+`blockwatch explain src/colors.py:colors` prints:
+
+[//]: # (<block name="explain-output-example">)
+
+```json
+{
+  "block": {
+    "attributes": {
+      "keep-sorted": "asc",
+      "keep-sorted-pattern": "\"(?P<value>\\w+)\"",
+      "name": "colors"
+    },
+    "column": 7,
+    "is_content_modified": false,
+    "line": 2,
+    "name": "colors"
+  },
+  "checks": {
+    "keep-sorted": {
+      "format": "lexicographic",
+      "lines": [
+        { "line": 3, "text": "\"blue\",", "value": "blue" },
+        { "line": 4, "text": "\"red\",", "value": "red" }
+      ],
+      "order": "asc"
+    }
+  },
+  "content": {
+    "start": { "line": 2, "character": 85 },
+    "end": { "line": 5, "character": 5 },
+    "text": "\n    \"blue\",\n    \"red\",\n    "
+  },
+  "disabled": [],
+  "file": "src/colors.py",
+  "with_diff": false
+}
+```
+
+[//]: # (</block>)
+
+| Key         | What it holds                                                                                                                                                                                                                                                                          |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `block`     | The block, as [`list`](#the-list-command) writes it.                                                                                                                                                                                                                                   |
+| `checks`    | What each validator read, by validator. See [What Each Validator Shows](#what-each-validator-shows).                                                                                                                                                                                   |
+| `content`   | The text the validators read. `start` is its first character, and `end` is the first character after it. The column is `character`, as in the `range` of a violation. For a [virtual block](#blocks-in-the-config-file) around a quoted or escaped value, `text` is the decoded value. |
+| `disabled`  | The validators that the block asks for, but the settings turn off. They have no entry in `checks`.                                                                                                                                                                                     |
+| `file`      | The block's file.                                                                                                                                                                                                                                                                      |
+| `with_diff` | Whether `--diff` was given. Without it, no block counts as changed, so `affects` can't fire.                                                                                                                                                                                           |
+
+### What Each Validator Shows
+
+A trace stops where its validator stops, such as at the first line out of order. A `line` is a line of the block's
+file, and `text` is that line trimmed, as the validator compares it. A key that holds what a violation reports has the
+name the violation's `data` gives it, such as `reason`.
+
+| Validator      | What it shows                                                                                                                                                                                                                                                                                                                                                                          |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `same-as`      | `records`: each match of `same-as-pattern` in the block, with its `line`, the text the regex matched (`match`), and each named group after `same-as-format` (`groups`). `targets`: the `records` of each target, and the `reason` of its violation, or `null` when the two agree. `paths`: with `same-as-paths`, the `glob`, the paths it `matched`, their `records` and the `reason`. |
+| `keep-sorted`  | `lines`: each line read, with the `value` it compares, or `null` when `keep-sorted-pattern` skips the line. `format` and `order`.                                                                                                                                                                                                                                                      |
+| `keep-unique`  | `lines`, as for `keep-sorted`. A repeated value has `duplicate_of`: the line where it first appeared.                                                                                                                                                                                                                                                                                  |
+| `line-pattern` | `lines`: each line read, with the text `line-pattern` matched (`match`). A line that fails has `fails`: the check it fails. `forbidden_match` is the text `line-pattern-forbidden` found.                                                                                                                                                                                              |
+| `line-count`   | `lines`, as for `keep-sorted`. A line counts when its `value` isn't `null`. The number of lines counted (`actual`), and the rule (`op` and `expected`).                                                                                                                                                                                                                                |
+| `affects`      | Whether the diff changed the block (`block_changed`). For each target: whether the diff `changed` it, or the `reason` it doesn't resolve.                                                                                                                                                                                                                                              |
+| `check-lua`    | The `content` and the `affects` the script got, and the message it returned (`lua_error`), or `null` when it passed. `affects` is `ctx.affects` without the content of each target.                                                                                                                                                                                                    |
+| `check-ai`     | The `model`, the `prompt` sent and the `response`. Both are `null` when `check-ai-pattern` matched nothing, so no request was sent.                                                                                                                                                                                                                                                    |
+
 ## Run Reports
 
 By default `blockwatch` prints nothing when a run succeeds. That makes a check that passed look exactly like a check

{blockwatch_cli-0.14.0 → blockwatch_cli-0.14.2}/docs/validators/README.md

@@ -26,6 +26,7 @@ between two references is fine.
 <!-- <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.14.0 → blockwatch_cli-0.14.2}/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,