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

{blockwatch_cli-0.14.1 → blockwatch_cli-0.15.0}/.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.1 → blockwatch_cli-0.15.0}/.pre-commit-config.yaml

@@ -43,6 +43,14 @@ repos:
         types: [ rust ]
         stages: [ pre-commit ]
         pass_filenames: false
+      - id: cargo-test
+        name: cargo test
+        description: Run the unit, integration and doc tests.
+        entry: cargo test --quiet
+        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.1 → blockwatch_cli-0.15.0}/AGENTS.md

@@ -65,9 +65,9 @@ For example:
 - *Always* handle the variants of an enum with an exhaustive `match`. A `let ... else`, or an `if` that handles one
   variant and sends the rest to a single branch, quietly gives any new variant whatever that branch does. With a
   `match`, the compiler makes you decide what to do with each new variant. One exception: a `match` on another
-  crate's enum can end with `_` when it only asks whether a value is one variant, and no new variant could be that
-  one. For example, every Markdown heading is `mdast::Node::Heading`, so the other node types can go to `_ => None`.
-  Say why in a comment next to the `_`.
+  crate's enum can end with `_` when it only picks out one or a few variants, and no new variant could be one of
+  them. For example, every Markdown heading is `mdast::Node::Heading`, so the other node types can go to
+  `_ => None`. Say why in a comment next to the `_`.
 - *Always* give an item the narrowest visibility that compiles: private, then `pub(super)`, then `pub(crate)`.
   blockwatch is a program, not a library. Only `run` and `count_rust_blocks` in `lib.rs` are `pub`, for `main.rs` and
   the fuzz target. The `unreachable_pub` lint makes `cargo clippy -- -D warnings` fail on any other `pub`.
@@ -173,8 +173,9 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    from the command line select, and that don't match the settings' ignore globs. `PathArguments::resolve` turns an
    existing file or directory into a glob first, so `src` selects `src/**`. Pick each file's language by its
    extension, using the settings' extension mappings too.
-6. For each file, the matching `language_parsers::<lang>` (a tree-sitter grammar) finds the comments. `tag_parser` and
-   `block_parser` turn the comment text into `Block` values, with their attributes and their byte and line ranges.
+6. For each file, the matching `language_parsers::<lang>` (usually a tree-sitter grammar) finds the comments.
+   `tag_parser` and `block_parser` turn the comment text into `Block` values, with their attributes and their byte and
+   line ranges.
    `VirtualBlock::resolve` finds each virtual block in the file, by its `Locator`, and adds it as a `Block` too. A file
    without a grammar is read as plain text: it has no tags, only its virtual blocks. A target that does not resolve
    stops the run. `--only-changed` also parses the file of a virtual block whose entry the diff
@@ -193,7 +194,8 @@ 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:
 
@@ -223,7 +225,8 @@ The main modules:
 - `src/repo_path.rs` — `RepoPath`, the one way to write a path relative to the repository root. A diff header
   (`b/src/main.rs`), a path found in the walk and a `file:name` attribute all become a `RepoPath`. So the same file is
   always the same map key.
-- `src/language_parsers/` — one tree-sitter grammar for each language. Each language has a `parser()` that returns a
+- `src/language_parsers/` — one parser for each language, most of them a tree-sitter grammar. Markdown and MDX use
+  the `markdown` crate, and Lean has its own scanner. 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 `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
@@ -237,8 +240,7 @@ The main modules:
     syntax tree is nested.
   - YAML walks its syntax tree itself. An alias has a position in a sequence but can't be addressed, and a query can't
     express that.
-  - Markdown finds its sections with the `markdown` crate. The `section` nodes of `tree-sitter-md` don't end at a
-    heading underlined with `---`.
+  - Markdown finds its sections with the `markdown` crate, the same parser that finds its comments.
 
   Each language's tests list every symbol it finds. When you give a language symbols, also document its paths in
   `docs/symbols.md` and in the "Symbols" section of the skill, `src/skill.md`. A test in `language_parsers/mod.rs` and the

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

@@ -12,6 +12,57 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.15.0] - 2026-10-21
+
+### Changed
+
+- In Markdown, a `<!--` is a comment only where HTML is kept as it is: in an HTML block or in raw HTML in a line of
+  text. These were read as comments before and are not now:
+  - the alt text of an image: `![Logo <!-- x -->](logo.png)`;
+  - the title of a link: `[Docs](docs.md "<!-- x -->")`;
+  - an escaped `<`: `\<!-- x -->`.
+
+  In a line of text, `<!-->` is now a whole comment, so a tag after it on that line is not read.
+
+### Fixed
+
+- In Markdown, blockwatch skipped every tag after a fenced code block that holds a line like `` ``` `` indented by 4
+  spaces or a tab, or `` echo x``` ``. Such a line closed the code block too early, so the rest of the file became
+  code. The run gave no error. Now such a line stays in the code block, as CommonMark says
+  ([#176](https://github.com/mennanov/blockwatch/issues/176)).
+
+## [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

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

@@ -65,9 +65,9 @@ For example:
 - *Always* handle the variants of an enum with an exhaustive `match`. A `let ... else`, or an `if` that handles one
   variant and sends the rest to a single branch, quietly gives any new variant whatever that branch does. With a
   `match`, the compiler makes you decide what to do with each new variant. One exception: a `match` on another
-  crate's enum can end with `_` when it only asks whether a value is one variant, and no new variant could be that
-  one. For example, every Markdown heading is `mdast::Node::Heading`, so the other node types can go to `_ => None`.
-  Say why in a comment next to the `_`.
+  crate's enum can end with `_` when it only picks out one or a few variants, and no new variant could be one of
+  them. For example, every Markdown heading is `mdast::Node::Heading`, so the other node types can go to
+  `_ => None`. Say why in a comment next to the `_`.
 - *Always* give an item the narrowest visibility that compiles: private, then `pub(super)`, then `pub(crate)`.
   blockwatch is a program, not a library. Only `run` and `count_rust_blocks` in `lib.rs` are `pub`, for `main.rs` and
   the fuzz target. The `unreachable_pub` lint makes `cargo clippy -- -D warnings` fail on any other `pub`.
@@ -173,8 +173,9 @@ The whole pipeline is in `src/cli.rs`. `src/main.rs` only calls `blockwatch::run
    from the command line select, and that don't match the settings' ignore globs. `PathArguments::resolve` turns an
    existing file or directory into a glob first, so `src` selects `src/**`. Pick each file's language by its
    extension, using the settings' extension mappings too.
-6. For each file, the matching `language_parsers::<lang>` (a tree-sitter grammar) finds the comments. `tag_parser` and
-   `block_parser` turn the comment text into `Block` values, with their attributes and their byte and line ranges.
+6. For each file, the matching `language_parsers::<lang>` (usually a tree-sitter grammar) finds the comments.
+   `tag_parser` and `block_parser` turn the comment text into `Block` values, with their attributes and their byte and
+   line ranges.
    `VirtualBlock::resolve` finds each virtual block in the file, by its `Locator`, and adds it as a `Block` too. A file
    without a grammar is read as plain text: it has no tags, only its virtual blocks. A target that does not resolve
    stops the run. `--only-changed` also parses the file of a virtual block whose entry the diff
@@ -193,7 +194,8 @@ 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:
 
@@ -223,7 +225,8 @@ The main modules:
 - `src/repo_path.rs` — `RepoPath`, the one way to write a path relative to the repository root. A diff header
   (`b/src/main.rs`), a path found in the walk and a `file:name` attribute all become a `RepoPath`. So the same file is
   always the same map key.
-- `src/language_parsers/` — one tree-sitter grammar for each language. Each language has a `parser()` that returns a
+- `src/language_parsers/` — one parser for each language, most of them a tree-sitter grammar. Markdown and MDX use
+  the `markdown` crate, and Lean has its own scanner. 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 `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
@@ -237,8 +240,7 @@ The main modules:
     syntax tree is nested.
   - YAML walks its syntax tree itself. An alias has a position in a sequence but can't be addressed, and a query can't
     express that.
-  - Markdown finds its sections with the `markdown` crate. The `section` nodes of `tree-sitter-md` don't end at a
-    heading underlined with `---`.
+  - Markdown finds its sections with the `markdown` crate, the same parser that finds its comments.
 
   Each language's tests list every symbol it finds. When you give a language symbols, also document its paths in
   `docs/symbols.md` and in the "Symbols" section of the skill, `src/skill.md`. A test in `language_parsers/mod.rs` and the

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

@@ -274,7 +274,7 @@ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
 [[package]]
 name = "blockwatch"
-version = "0.14.1"
+version = "0.15.0"
 dependencies = [
  "anyhow",
  "assert-json-diff",
@@ -327,7 +327,6 @@ dependencies = [
  "tree-sitter-kotlin-ng",
  "tree-sitter-lua",
  "tree-sitter-make",
- "tree-sitter-md",
  "tree-sitter-nix",
  "tree-sitter-ocaml",
  "tree-sitter-php",
@@ -2637,16 +2636,6 @@ dependencies = [
  "tree-sitter-language",
 ]
 
-[[package]]
-name = "tree-sitter-md"
-version = "0.5.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2efd398be546456c814598ee56c0f51769a77241511b4a58077815d120afa882"
-dependencies = [
- "cc",
- "tree-sitter-language",
-]
-
 [[package]]
 name = "tree-sitter-nix"
 version = "0.3.0"

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

@@ -1,6 +1,6 @@
 [package]
 name = "blockwatch"
-version = "0.14.1"
+version = "0.15.0"
 edition = "2024"
 repository = "https://github.com/mennanov/blockwatch"
 description = "Language agnostic linter that keeps your code and documentation in sync and valid"
@@ -62,7 +62,6 @@ tree-sitter-json = "0.24.8"
 tree-sitter-kotlin-ng = "1.1"
 tree-sitter-lua = "0.5"
 tree-sitter-make = "1.1"
-tree-sitter-md = "0.5"
 tree-sitter-nix = "0.3.0"
 tree-sitter-ocaml = "0.26"
 tree-sitter-php = "0.25"

{blockwatch_cli-0.14.1 → blockwatch_cli-0.15.0}/PKG-INFO

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

@@ -104,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`                           |
 
@@ -173,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
@@ -215,7 +218,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.14.1  # Use latest release
+  rev: v0.15.0  # Use latest release
   hooks:
     - id: blockwatch
 ```

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

{blockwatch_cli-0.14.1 → blockwatch_cli-0.15.0}/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`)
@@ -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.1",
-          "semanticVersion": "0.14.1",
+          "version": "0.15.0",
+          "semanticVersion": "0.15.0",
           "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.1/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.15.0/docs/validators/keep-sorted.md"
             }
           ]
         }
@@ -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.15.0/docs/validators/line-count.md

@@ -0,0 +1,48 @@
+# `line-count`
+
+Constrains how many lines a block may contain. Flags unbounded growth in a public API surface, or pins a switch to the
+size of the enum it maps.
+
+## Syntax
+
+| Attribute            | Value                                      | Default                  |
+|----------------------|--------------------------------------------|--------------------------|
+| `line-count`         | `<N`, `<=N`, `==N`, `>=N`, `>N`            | —                        |
+| `line-count-pattern` | regex; a line counts when it gives a value | every line that has text |
+
+## Example
+
+```python
+# <block line-count="<=5">
+"a",
+"b",
+"c"
+# </block>
+```
+
+## Counting only some lines
+
+`line-count-pattern` counts only the lines it matches:
+
+```python
+# <block line-count="<=2" line-count-pattern='^"\w+",$'>
+"a",
+# a comment
+"b",
+# </block>
+```
+
+The block above counts 2: the comment line doesn't match.
+
+Lines that do not match are skipped, as are lines whose match is empty. So is a line that matches a branch without the
+`value` group: `^(?:none|(?P<value>\w+))$` skips the line `none`. The pattern runs on the trimmed line, so `^` and `$`
+match at the text, not at the indentation.
+
+## Notes
+
+- **Blank lines are not counted.** The block above counts 3.
+- A malformed comparator is a hard error, not a violation.
+
+---
+
+← [Validators](README.md) · [README](../../README.md)

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

{blockwatch_cli-0.14.1 → blockwatch_cli-0.15.0}/src/blocks.rs

@@ -184,6 +184,15 @@ impl Content {
         }
     }
 
+    /// Describes the content for JSON. `source` must be the text of the block's file.
+    pub(crate) fn listing<'a>(&'a self, source: &'a str) -> ContentListing<'a> {
+        ContentListing {
+            start: self.positions.start,
+            end: self.positions.end,
+            text: self.text(source),
+        }
+    }
+
     /// Returns the content's text. `source` must be the text of the block's file.
     pub(crate) fn text<'a>(&'a self, source: &'a str) -> &'a str {
         match &self.text {
@@ -424,6 +433,19 @@ pub(crate) struct BlockListing<'a> {
 }
 // </block>
 
+/// The content of a block, as it is written in JSON: its text, and where the block's file writes
+/// it.
+#[derive(Serialize, Debug)]
+pub(crate) struct ContentListing<'a> {
+    /// The position of the content's first character.
+    start: Position,
+    /// The first position after the content.
+    end: Position,
+    /// The text the validators read. For a virtual block around a quoted or escaped value, it is
+    /// the decoded value.
+    text: &'a str,
+}
+
 impl<'a> From<&'a BlockWithContext> for BlockListing<'a> {
     /// Describes the block, with no `checks`.
     fn from(block_with_context: &'a BlockWithContext) -> Self {
@@ -461,6 +483,7 @@ const RECOGNIZED_ATTRIBUTES: &[&str] = &[
     "keep-sorted-pattern",
     "keep-unique",
     "line-count",
+    "line-count-pattern",
     "line-pattern",
     "line-pattern-forbidden",
     "name",