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

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/AGENTS.md

@@ -62,7 +62,10 @@ For example:
 - *Prefer* the harness's editing tools to one-off scripts.
 - *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.
+  `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 `_`.
 - *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`.
@@ -200,8 +203,9 @@ The main modules:
 - `src/virtual_blocks.rs` — `VirtualBlock`, a block that the config file declares in one file, instead of tags in a
   comment. A file that can't or must not hold a tag, such as `package.json` or a prompt, can only get blocks this way.
   It is a block of the file it wraps. Its `Locator` says how to find it:
-  - `Symbol`: the content is what a reference to the symbol reads: a scalar's decoded value
-    (`ContentText::Decoded`), or else the definition's text.
+  - `Symbol`: the content is what a reference to the symbol reads: its value, or else the definition's text. A value
+    written as is, such as a number or a Markdown section, keeps its place in the file. A value with quotes or escapes
+    is decoded (`ContentText::Decoded`), so every line of it reports the value's start.
   - `Pattern`: the `target-pattern` regex must match once. The content is its `value` group, or else the whole match.
   - `File`: the content is the whole file.
 
@@ -224,6 +228,8 @@ 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 `---`.
 
   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
@@ -269,8 +275,11 @@ skill this project ships, so that agents can add blocks to **other** repositorie
 They are not instructions for working on blockwatch, and changing them changes what users get. This file is the
 guidance for working on blockwatch.
 
-A block tag in `src/skill.md` can have a name and a pattern, but no rule. A project that saves the skill parses its
-tags too, and a rule's target exists only in this repository. Put the rule on the block at the other end instead.
+`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, 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
@@ -279,8 +288,8 @@ needs belongs in this file.
 ## Release
 
 The GitHub Actions workflows in `.github/workflows/` build releases with `cargo-dist`, configured in
-`dist-workspace.toml`. The version is bumped in `Cargo.toml`, in a commit titled
-`chore: Release blockwatch version X.Y.Z`.
+`dist-workspace.toml`. `cargo release` bumps the version in `Cargo.toml`, in a commit titled `chore: Release`, and
+tags that commit `vX.Y.Z`.
 
 `pypi.yml` builds the same tag for PyPI, as `blockwatch-cli`. The pre-commit hooks install that package through the
 root `setup.py`. So if the upload for a tag fails, the hooks at that tag can't install.

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

@@ -12,6 +12,51 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [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
+
+- A symbol path can point at a section of a Markdown file (`.md`, `.markdown`, `.mdx`) by its headings. For example,
+  `docs/cli.md#/CLI Reference/Run Modes` is the `## Run Modes` section under the `# CLI Reference` title. So
+  `affects` and `same-as` can point at a section, and a `[[block]]` entry can wrap one, with no tags in the file. See
+  [Markdown](docs/symbols.md#markdown) ([#175](https://github.com/mennanov/blockwatch/issues/175)).
+
+### Changed
+
+- Messages now show a space inside a key of a symbol path as written. Markdown headings almost always hold spaces, so
+  a path to a section reads like the file: `docs/cli.md#/CLI Reference/Run Modes`, not
+  `docs/cli.md#/CLI%20Reference/Run%20Modes`. A space at the start or end of a key still shows as `%20`. In any file,
+  an `affects` or `same-as` violation on a key with a space gets a new hash, so update any `--suppress` address with
+  four parts that points at it.
+
+### Fixed
+
+- The skill that `blockwatch skill` prints no longer adds blocks to the project that saves it. Before, a saved skill
+  added six named blocks, such as `validator-catalog` and `json-paths`, to `blockwatch list` and to the
+  `--verbosity summary` counts. Save the skill again with `blockwatch skill` to remove them
+  ([#174](https://github.com/mennanov/blockwatch/issues/174)).
+
 ## [0.12.0] - 2026-10-15
 
 ### Changed

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/CLAUDE.md

@@ -62,7 +62,10 @@ For example:
 - *Prefer* the harness's editing tools to one-off scripts.
 - *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.
+  `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 `_`.
 - *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`.
@@ -200,8 +203,9 @@ The main modules:
 - `src/virtual_blocks.rs` — `VirtualBlock`, a block that the config file declares in one file, instead of tags in a
   comment. A file that can't or must not hold a tag, such as `package.json` or a prompt, can only get blocks this way.
   It is a block of the file it wraps. Its `Locator` says how to find it:
-  - `Symbol`: the content is what a reference to the symbol reads: a scalar's decoded value
-    (`ContentText::Decoded`), or else the definition's text.
+  - `Symbol`: the content is what a reference to the symbol reads: its value, or else the definition's text. A value
+    written as is, such as a number or a Markdown section, keeps its place in the file. A value with quotes or escapes
+    is decoded (`ContentText::Decoded`), so every line of it reports the value's start.
   - `Pattern`: the `target-pattern` regex must match once. The content is its `value` group, or else the whole match.
   - `File`: the content is the whole file.
 
@@ -224,6 +228,8 @@ 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 `---`.
 
   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
@@ -269,8 +275,11 @@ skill this project ships, so that agents can add blocks to **other** repositorie
 They are not instructions for working on blockwatch, and changing them changes what users get. This file is the
 guidance for working on blockwatch.
 
-A block tag in `src/skill.md` can have a name and a pattern, but no rule. A project that saves the skill parses its
-tags too, and a rule's target exists only in this repository. Put the rule on the block at the other end instead.
+`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, 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
@@ -279,8 +288,8 @@ needs belongs in this file.
 ## Release
 
 The GitHub Actions workflows in `.github/workflows/` build releases with `cargo-dist`, configured in
-`dist-workspace.toml`. The version is bumped in `Cargo.toml`, in a commit titled
-`chore: Release blockwatch version X.Y.Z`.
+`dist-workspace.toml`. `cargo release` bumps the version in `Cargo.toml`, in a commit titled `chore: Release`, and
+tags that commit `vX.Y.Z`.
 
 `pypi.yml` builds the same tag for PyPI, as `blockwatch-cli`. The pre-commit hooks install that package through the
 root `setup.py`. So if the upload for a tag fails, the hooks at that tag can't install.

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

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

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

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

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

@@ -88,9 +88,9 @@ Two validators work across files:
 - `affects` fails when a diff touches a block without also changing what it points to.
 - `same-as` fails when a block and its target hold different values. It needs no diff.
 
-Both can point to a block, a whole file, or a specific value in a file like `package.json#/version`
-(see [Symbols](docs/symbols.md)). The other validators check a single block on their own: the things you'd otherwise
-have to nitpick in code review.
+Both can point to a block, a whole file, a specific value in a file like `package.json#/version`, or a section of a
+Markdown file (see [Symbols](docs/symbols.md)). The other validators check a single block on their own: the things
+you'd otherwise have to nitpick in code review.
 
 <!-- <block name="available-validators"
      same-as="src/validators/mod.rs:validator-registry, docs/validators/README.md:validators-index"
@@ -214,7 +214,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.12.0  # Use latest release
+  rev: v0.14.0  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/blockwatch.toml

@@ -38,3 +38,16 @@ same-as = '''.github/workflows/codeql.yml,
     .github/workflows/pypi.yml,
     .github/workflows/rust.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 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#/blockwatch/Validator reference'
+name = 'validator-reference'
+same-as-pattern = '^\|\s*`(?P<value>[a-z-]+)`'
+
+[[block]]
+target = 'src/skill.md#/blockwatch/Symbols/Files with symbols'
+name = 'extensions-with-symbols'
+same-as-pattern = '`\.?(?P<value>[A-Za-z]+)`'

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.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.12.0  # Use latest release
+  rev: v0.14.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.12.0  # Use latest release
+  rev: v0.14.0  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

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

@@ -555,15 +555,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.12.0",
-          "semanticVersion": "0.12.0",
+          "version": "0.14.0",
+          "semanticVersion": "0.14.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.12.0/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.14.0/docs/validators/keep-sorted.md"
             }
           ]
         }

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/docs/symbols.md

@@ -24,11 +24,12 @@ declares, instead of tags in a comment.
 <!-- <block name="extensions-with-symbols" same-as="src/language_parsers/mod.rs:extensions-with-symbols"
      same-as-pattern="`\.?(?P<value>[A-Za-z]+)`"> -->
 
-| Language | Files                             | Paths         |
-|----------|-----------------------------------|---------------|
-| JSON     | `.json`, `.jsonc`, `.webmanifest` | [JSON](#json) |
-| TOML     | `.toml`, `Pipfile`                | [TOML](#toml) |
-| YAML     | `.yaml`, `.yml`, `.cff`           | [YAML](#yaml) |
+| Language | Files                             | Paths                 |
+|----------|-----------------------------------|-----------------------|
+| JSON     | `.json`, `.jsonc`, `.webmanifest` | [JSON](#json)         |
+| TOML     | `.toml`, `Pipfile`                | [TOML](#toml)         |
+| YAML     | `.yaml`, `.yml`, `.cff`           | [YAML](#yaml)         |
+| Markdown | `.md`, `.markdown`, `.mdx`        | [Markdown](#markdown) |
 
 <!-- </block> -->
 
@@ -189,6 +190,49 @@ jobs:
 
 <!-- </block> -->
 
+## Markdown
+
+<!-- <block name="markdown-paths"> -->
+
+Every section is a symbol. A section is a heading and everything up to the next heading of the same or a higher level.
+Its path is the text of each heading it is under, then its own:
+
+```markdown
+# Guide
+
+## Install
+
+Run `cargo install blockwatch`.
+
+### From source
+
+Clone the repository.
+```
+
+| Path                          | Points at                                   |
+|-------------------------------|---------------------------------------------|
+| `#/Guide`                     | everything below `# Guide`                  |
+| `#/Guide/Install`             | `Run …` and the whole `From source` section |
+| `#/Guide/Install/From source` | `Clone the repository.`                     |
+
+- **The top `#` title is part of every path**, as above.
+- **A section holds its subsections.** `affects` counts a change to any of its lines, the heading included.
+- **A section's value is its text without the heading line.** `same-as` compares that text. The blank lines around it
+  don't count.
+- **A heading counts as a reader sees it.** ``## The `--diff` flag`` is `#/The --diff flag`. Code, emphasis and links
+  lose their markup.
+- **Headings underlined with `===` or `---` count.** A `#` line in a code block doesn't. Neither does a heading in a
+  quote, a list item or an HTML block.
+- **The same heading twice under one parent is a violation**, because blockwatch can't tell which one you mean. Two
+  `### Example` sections under different `##` headings are fine.
+- **Escape a heading like any key.** `## Input/Output` is `#/Input~1Output`, and `## Step 1: build` is
+  `#/Step 1%3A build`.
+- **An `.mdx` file gets the same paths.** The text of a JSX element in a heading counts, and so does the code in
+  braces: `## Red <Badge>new</Badge> {version}` is `#/Red new version`. A heading inside a JSX element doesn't count.
+  A file that isn't valid MDX stops the run.
+
+<!-- </block> -->
+
 ---
 
 [← Return to README](../README.md)

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

@@ -23,7 +23,8 @@ 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-pattern='\[`(?P<value>[a-z-]+)`\]\('> -->
 

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/docs/validators/same-as.md

@@ -8,13 +8,13 @@ It runs on every scan, with or without a diff.
 
 ## Syntax
 
-| Attribute         | Value                                               | Default           |
-|-------------------|-----------------------------------------------------|-------------------|
-| `same-as`         | One or more [targets](#targets), comma-separated    | —                 |
-| `same-as-paths`   | A [glob](#paths-as-targets) of paths to compare     | —                 |
-| `same-as-pattern` | A regex that picks the values to compare            | the whole content |
-| `same-as-mode`    | `set`, `sequence`, `single` or `subset`             | `set`             |
-| `same-as-format`  | `numeric`, `identifier` or `flat`                   | text              |
+| Attribute         | Value                                                                                | Default           |
+|-------------------|--------------------------------------------------------------------------------------|-------------------|
+| `same-as`         | One or more [targets](#targets), comma-separated                                     | —                 |
+| `same-as-paths`   | A [glob](#paths-as-targets) of paths to compare                                      | —                 |
+| `same-as-pattern` | A regex that picks the values to compare                                             | the whole content |
+| `same-as-mode`    | `set`, `sequence`, `single` or `subset`                                              | `set`             |
+| `same-as-format`  | `numeric`, `identifier` or `flat`, or [one for each group](#a-format-for-each-group) | text              |
 
 ## Targets
 
@@ -55,10 +55,10 @@ Usually, though, the two places don't hold the same text. Then each block says *
 
 ## Pick values with `same-as-pattern`
 
-Each block has its own regex. Every match is a value: the `(?P<value>…)` group if there is one, otherwise the whole
-match. A line can hold several values. Lines without a match are skipped, and so are empty matches. So is a match of a
-branch without the `value` group: `^(?:none|(?P<value>\w+))$` skips the line `none`. This lets you compare blocks
-written in different formats:
+Each block has its own regex. Every match is a value: the `(?P<value>…)` group if the pattern has one, otherwise the
+whole match. A pattern with [other named groups](#compare-several-groups) compares those too. A line can hold several
+values. Lines without a match are skipped, and so are empty matches. So is a match of a branch without the `value`
+group: `^(?:none|(?P<value>\w+))$` skips the line `none`. This lets you compare blocks written in different formats:
 
 ```rust
 // <block same-as="README.md:supported-env-vars" same-as-pattern="BLOCKWATCH_AI_[A-Z_]+">
@@ -76,6 +76,41 @@ const API_URL: &str = "BLOCKWATCH_AI_API_URL";
 [//]: # (</block>)
 ```
 
+### Compare several groups
+
+A pattern can have several named groups, such as a code and its message. Then each match is one record, and the
+records are compared whole. So a message that moves to another code fails, even though the messages alone still agree:
+
+```rust
+// <block same-as="docs/errors.md:errors" same-as-pattern='(?P<code>\d+) => "(?P<message>[^"]+)"'>
+404 => "not found",
+409 => "already exists",
+// </block>
+```
+
+```markdown
+<!-- <block name="errors" same-as-pattern="^- `(?P<code>\d+)`: (?P<message>.+)$"> -->
+- `404`: already exists
+- `409`: not found
+<!-- </block> -->
+```
+
+The run reports:
+
+```text
+[{code: "404", message: "not found"}, {code: "409", message: "already exists"}] != [{code: "404", message: "already exists"}, {code: "409", message: "not found"}]
+```
+
+- **Groups match by name**, not by their place in the pattern. So one side can write the message before the code.
+- **Both patterns need the same groups.** Otherwise the run reports
+  `same-as-pattern groups differ: code, message != message`.
+- **A pattern without named groups has one group, `value`.** So does a block without a pattern. Either can be compared
+  with a pattern whose only group is `value`.
+- **A match is skipped when one of its groups is not in the match, or is empty.**
+- **A record must fit on one line,** because the pattern reads one line at a time.
+- **`same-as-format` applies to every group,** unless you give [each group its own](#a-format-for-each-group).
+- **To group part of a pattern without comparing it, use `(?:…)`.** It captures nothing.
+
 ### Lines are not part of the comparison
 
 With a pattern, only the values count, not how they are split into lines. These two blocks agree, even in `sequence`
@@ -290,17 +325,45 @@ plain `s`, so `policies.yaml` gives `policie`, which doesn't equal `Policy`.
 - **Digits and accents count.** `Version2` equals `version-2`, but not `version`. `CAFÉ` equals `café`, but not `cafe`.
 - **Messages show each value as it is compared,** such as `crontab`.
 
+## A format for each group
+
+With [several groups](#compare-several-groups), each group can have its own format. Write `group:format` entries,
+separated by commas. Here the names differ in style and the numbers differ in spelling:
+
+```rust
+// <block same-as="docs/config.md:defaults" same-as-format="name:identifier,value:numeric" same-as-pattern="const (?P<name>\w+): \w+ = (?P<value>[\d.]+);">
+const MAX_RETRIES: u32 = 3;
+const TIMEOUT_SECS: f64 = 2.0;
+// </block>
+```
+
+```markdown
+<!-- <block name="defaults" same-as-pattern="^- `(?P<name>[a-z-]+)`: (?P<value>[\d.]+)$"> -->
+- `max-retries`: 3
+- `timeout-secs`: 2
+<!-- </block> -->
+```
+
+- **A group without an entry is compared as written.** With `same-as-format="value:numeric"`, `MAX_RETRIES` and
+  `max-retries` differ.
+- **A format without a group applies to every group.** With `same-as-format="numeric"`, the run reports that
+  `MAX_RETRIES` is not a number.
+- **The two forms don't mix.** `identifier,value:numeric` is an error.
+- **Each group must be a group of this block's pattern.** Otherwise the run stops, so a typo can't go unnoticed. A
+  block without a pattern, or a pattern without named groups, has the one group `value`. So `value:numeric` works
+  there too.
+
 ## Notes
 
 - **Which block's attributes count.** The referencing block's `same-as-mode` and `same-as-format` decide how to compare.
   Each block's `same-as-pattern` reads only that block. A whole file, a symbol or a list of paths has no block, so the
   referencing block's pattern reads it too.
 - **Violations:** a missing block, a missing or repeated key, a value that is not a number under `numeric`, a `single`
-  side without exactly one value, a pattern that matches nothing on either side, and a `same-as-paths` glob that
-  matches no path. Two empty sides do not count as equal.
-- **Errors that stop the run:** an unknown `same-as-mode` or `same-as-format`, an invalid regex or glob,
-  `same-as-paths` without `same-as-pattern`, a missing target file, and a symbol in a file with a syntax error, without
-  symbols, or with several YAML documents.
+  side without exactly one value, a pattern that matches nothing on either side, two patterns with different groups,
+  and a `same-as-paths` glob that matches no path. Two empty sides do not count as equal.
+- **Errors that stop the run:** an unknown `same-as-mode` or `same-as-format`, a `same-as-format` entry for a group
+  that the pattern doesn't have, an invalid regex or glob, `same-as-paths` without `same-as-pattern`, a missing target
+  file, and a symbol in a file with a syntax error, without symbols, or with several YAML documents.
 - **Run it on the whole tree now and then.** `same-as` needs no diff, so a plain `blockwatch` run catches drift that
   `--only-changed` misses. See [CI integration](../ci.md).
 - **A rename alone goes unnoticed in a diff.** Renaming a target file without changing it (a plain `git mv`) gives

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

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/src/blocks.rs

@@ -52,8 +52,9 @@ pub(crate) struct Content {
 /// The text of a block's [`Content`].
 #[derive(Debug, PartialEq, Eq, Clone)]
 enum ContentText {
-    /// The source text in this byte range: the lines between the block's tags, or the definition
-    /// of the object, list or table that a virtual block wraps.
+    /// The source text in this byte range: the lines between the block's tags, or the part of the
+    /// file that a virtual block wraps when it is written as is, such as a JSON object or a
+    /// Markdown section.
     Source(Range<usize>),
     /// The decoded value of the scalar that a virtual block wraps. Its quotes and escapes are
     /// gone, so it is not a part of the source text.

{blockwatch_cli-0.12.0 → blockwatch_cli-0.14.0}/src/language_parsers/json.rs

@@ -93,7 +93,7 @@ mod tests {
             "containers": [{"key": "value"}, ["item"]]
         }"#;
 
-        // <block affects="docs/symbols.md:json-paths, src/skill.md:json-paths">
+        // <block affects="docs/symbols.md:json-paths, src/skill.md#/blockwatch/Symbols/JSON">
         assert_eq!(
             derived_symbols(source)?,
             expected_symbols([