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

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

@@ -276,9 +276,10 @@ They are not instructions for working on blockwatch, and changing them changes w
 guidance for working on blockwatch.
 
 `src/skill.md` must not hold block tags. A project that saves the skill parses it too, so each tag would become a block
-in that project. To point a block at a section of the skill, put the section between two plain comments, such as
-`<!-- json-paths -->` and `<!-- /json-paths -->`. Then add a `[[block]]` entry that matches them to `blockwatch.toml`,
-next to the others for `src/skill.md`.
+in that project. To point a block at a section of the skill, use the section's headings, such as
+`src/skill.md#/blockwatch/Symbols/JSON`. To point at only a part of a section, give that part a heading of its own.
+When the section needs a rule of its own, such as a `same-as-pattern`, add a `[[block]]` entry for it to
+`blockwatch.toml`, next to the others for `src/skill.md`.
 
 Each agent's local config directory is left out of git on purpose: `.claude/`, `.cursor/`, `.gemini/`, `.windsurf/`,
 `.aider*`, and the others listed in `.gitignore`. Don't commit agent-specific settings. Anything a future contributor

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

@@ -12,6 +12,27 @@ 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

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

@@ -276,9 +276,10 @@ They are not instructions for working on blockwatch, and changing them changes w
 guidance for working on blockwatch.
 
 `src/skill.md` must not hold block tags. A project that saves the skill parses it too, so each tag would become a block
-in that project. To point a block at a section of the skill, put the section between two plain comments, such as
-`<!-- json-paths -->` and `<!-- /json-paths -->`. Then add a `[[block]]` entry that matches them to `blockwatch.toml`,
-next to the others for `src/skill.md`.
+in that project. To point a block at a section of the skill, use the section's headings, such as
+`src/skill.md#/blockwatch/Symbols/JSON`. To point at only a part of a section, give that part a heading of its own.
+When the section needs a rule of its own, such as a `same-as-pattern`, add a `[[block]]` entry for it to
+`blockwatch.toml`, next to the others for `src/skill.md`.
 
 Each agent's local config directory is left out of git on purpose: `.claude/`, `.cursor/`, `.gemini/`, `.windsurf/`,
 `.aider*`, and the others listed in `.gitignore`. Don't commit agent-specific settings. Anything a future contributor

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

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

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

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

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

@@ -214,7 +214,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.13.0  # Use latest release
+  rev: v0.14.0  # Use latest release
   hooks:
     - id: blockwatch
 ```

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

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

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

{blockwatch_cli-0.13.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.13.0",
-          "semanticVersion": "0.13.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.13.0/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.14.0/docs/validators/keep-sorted.md"
             }
           ]
         }

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

{blockwatch_cli-0.13.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([

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.0}/src/language_parsers/markdown.rs

@@ -390,7 +390,7 @@ mod tests {
             .collect()
     }
 
-    // <block affects="docs/symbols.md:markdown-paths, src/skill.md:markdown-paths">
+    // <block affects="docs/symbols.md:markdown-paths, src/skill.md#/blockwatch/Symbols/Markdown">
     #[test]
     fn nested_sections_parse_symbols_returns_each_section_with_its_body() -> anyhow::Result<()> {
         let source = r"Text before the first heading.

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.0}/src/language_parsers/mdx.rs

@@ -431,7 +431,7 @@ title: <3 # not a comment
         Ok(())
     }
 
-    // <block affects="docs/symbols.md:markdown-paths, src/skill.md:markdown-paths">
+    // <block affects="docs/symbols.md:markdown-paths, src/skill.md#/blockwatch/Symbols/Markdown">
     #[test]
     fn document_with_esm_and_jsx_parse_symbols_returns_its_sections() -> anyhow::Result<()> {
         let source = r"import {Badge} from './badge.js'

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.0}/src/language_parsers/toml.rs

@@ -465,7 +465,7 @@ name = "plantain"
         let banana = "[[fruits]]\nname = \"banana\"\n";
         let plantain = "[[fruits.varieties]]\nname = \"plantain\"\n";
 
-        // <block affects="docs/symbols.md:toml-paths, src/skill.md:toml-paths">
+        // <block affects="docs/symbols.md:toml-paths, src/skill.md#/blockwatch/Symbols/TOML">
         assert_eq!(
             derived_symbols(source)?,
             expected_symbols(&[

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.0}/src/language_parsers/yaml.rs

@@ -779,7 +779,7 @@ multi: this is
 last: end
 "#;
 
-        // <block affects="docs/symbols.md:yaml-paths, src/skill.md:yaml-paths">
+        // <block affects="docs/symbols.md:yaml-paths, src/skill.md#/blockwatch/Symbols/YAML">
         assert_eq!(
             derived_symbols(source)?,
             expected_symbols(&[

{blockwatch_cli-0.13.0 → blockwatch_cli-0.14.0}/src/skill.md

@@ -49,8 +49,6 @@ Then run `git diff --patch | blockwatch --diff` to confirm the new tags pass (se
 
 ### Where blocks add value (catalog)
 
-<!-- validator-catalog -->
-
 | You see...                                                                                                                                   | Add                      | Why                                                                        |
 |----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|----------------------------------------------------------------------------|
 | A hand-maintained list/enum/match that should stay ordered (dependencies, CLI flags, feature lists, route tables)                            | `keep-sorted`            | Eliminates "please sort this" review nits                                  |
@@ -63,8 +61,6 @@ Then run `git diff --patch | blockwatch --diff` to confirm the new tags pass (se
 | Prose or config with a natural-language rule ("must mention X", "no TODOs left")                                                             | `check-ai="..."`         | Rules regex can't express                                                  |
 | Domain logic too complex for regex                                                                                                           | `check-lua="script.lua"` | Custom programmable checks                                                 |
 
-<!-- /validator-catalog -->
-
 Prefer the deterministic validators (`keep-sorted`, `keep-unique`, `affects`, `same-as`, `line-pattern`, `line-count`)
 first — they are free, fast, and need no API keys. Reserve `check-ai` for rules the cheaper validators genuinely can't
 express.
@@ -121,17 +117,15 @@ pub enum Language { Rust, Python }
 
 ## Validator reference
 
-<!-- validator-reference -->
-
 | Attribute                | Syntax                                                                                                                                | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `name`                   | `name="foo"`                                                                                                                          | Gives the block a name, so `affects` and `same-as` can point at it; shown by `blockwatch list`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `affects`                | `affects="file:foo"`, `":foo"` (same file), `"file"` (whole file) or `"file#/path"` (one [symbol](#symbols)); comma-separate multiple | If this block's content changes in a diff, each target must change too, else a violation. Only fires under `--diff`. One-way: put `affects` on **both** blocks, each with a `name`, to catch both directions. A whole-file target is satisfied by *any* change to the file; use it for files that cannot hold a comment (`.env`, lockfiles). If the file has symbols, point at one instead (`package.json#/version`): only a change to that key or its value counts. A missing target file fails the run; a missing block or key is a violation.                                                                                       |
 | `same-as`                | `same-as="file:foo"`, `":foo"` (same file), `"file"` (whole file) or `"file#/path"` (one [symbol](#symbols)); comma-separate multiple | This block and each target must hold the same **value**. Unlike `affects`, it also runs on a full-tree scan. Under `--only-changed`, only a changed block that *carries* `same-as` starts the check, so put `same-as` on both blocks if a change to either side must be caught. Compares the whole trimmed content by default. A whole-file or `#/path` target has no block of its own, so **this** block's `same-as-pattern` reads it. A `#/path` target is one value: a string compares as its unquoted text, any other value as written, and a value that holds other values (an object, a table, a mapping or a list) as its text. |
 | `same-as-paths`          | `same-as-paths="services/*/"`                                                                                                         | This block must hold the same values as the repository paths that match the glob: sorted, each once. A glob that ends with `/` lists directories (`services/auth/`), otherwise files. `*` stops at `/`, `**` crosses it. One glob; for several directories use braces: `{services,workers}/*/`. Needs `same-as-pattern`, which reads both this block and the paths; `.+` compares whole lines. Files that `.gitignore` leaves out and symlinks are not listed; the `ignore` setting doesn't apply. A glob that matches nothing is a violation.                                                                                         |
-| `same-as-pattern`        | `same-as-pattern="id: (?P<value>\d+)"`                                                                                                | Per line, compare the `value` capture group (or the whole match); **every** match on a line counts, and all lines flatten into one list — values are compared, not their layout. Each side reads *itself*, so put a pattern on both blocks when the two are in different formats.                                                                                                                                                                                                                                                                                                                                                      |
+| `same-as-pattern`        | `same-as-pattern="id: (?P<value>\d+)"`                                                                                                | Per line, compare the `value` capture group (or the whole match); **every** match on a line counts, and all lines flatten into one list — values are compared, not their layout. With several named groups, such as `(?P<key>\w+)=(?P<value>\d+)`, each match is one record, compared whole; both patterns need the same group names. Each side reads *itself*, so put a pattern on both blocks when the two are in different formats.                                                                                                                                                                                                 |
 | `same-as-mode`           | `same-as-mode="set"` (default) `/ sequence / single / subset`                                                                         | `set` order/duplicate-insensitive; `sequence` ordered; `single` exactly one token per side; `subset` this block's tokens must all appear in the target (directional). Governed by the source block.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `same-as-format`         | `same-as-format="numeric"` / `"identifier"` / `"flat"`                                                                                | `numeric`: parse tokens as numbers before comparing, so `8080` == `8080.0`. `identifier`: compare the words of a name, so `PreExistingFailure` == `pre-existing-failure` == `PRE_EXISTING_FAILURE`; a run of capitals is one word (`HTTPServer` == `http-server`). `flat`: compare only the lower-cased letters and digits, so `CronTab` == `crontab` == `cron-tab`; use it when one side has no word breaks, since `identifier` keeps `Signin` != `sign-in`. Governed by the source block.                                                                                                                                            |
+| `same-as-format`         | `same-as-format="numeric"` / `"identifier"` / `"flat"`                                                                                | `numeric`: parse tokens as numbers before comparing, so `8080` == `8080.0`. `identifier`: compare the words of a name, so `PreExistingFailure` == `pre-existing-failure` == `PRE_EXISTING_FAILURE`; a run of capitals is one word (`HTTPServer` == `http-server`). `flat`: compare only the lower-cased letters and digits, so `CronTab` == `crontab` == `cron-tab`; use it when one side has no word breaks, since `identifier` keeps `Signin` != `sign-in`. With several groups in `same-as-pattern`, each can have its own: `name:identifier,value:numeric`; a group left out compares as written. Governed by the source block.    |
 | `keep-sorted`            | `keep-sorted` / `keep-sorted="asc"` / `keep-sorted="desc"`                                                                            | Default `asc`, compared lexicographically.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `keep-sorted-pattern`    | `keep-sorted-pattern="id: (?P<value>\d+)"`                                                                                            | Sort by the regex capture group named `value` instead of the whole line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `keep-sorted-format`     | `keep-sorted-format="numeric"`                                                                                                        | Compare the value numerically rather than as text (`"10"` after `"2"`). Every line must then *be* a number, and a trailing comma is part of the trimmed line — on a real list literal pair this with `keep-sorted-pattern` to lift the number out, or the run is a hard error.                                                                                                                                                                                                                                                                                                                                                         |
@@ -146,20 +140,18 @@ pub enum Language { Rust, Python }
 | `check-lua-timeout`      | `check-lua-timeout="60"`                                                                                                              | Wall-clock budget for the script, in whole seconds; default `30`. A script that runs past it fails the run with an error, not a violation. A value below `1` is a hard error.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `severity`               | `severity="error"` (default) `/ warning / info / hint`                                                                                | Only `error` fails the run (exit 1); the others are reported but exit 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
-<!-- /validator-reference -->
-
 ## Symbols
 
 A symbol is one value inside a file, such as the `version` key in `package.json`. `affects` and `same-as` point at one
 with `file#/path`, or with `#/path` for the block's own file. Use a symbol when only one key in a file matters, or when
 the file cannot hold a comment. To put rules on the value itself, wrap it in a `[[block]]` entry in `blockwatch.toml`.
 
-<!-- extensions-with-symbols -->
+### Files with symbols
 
 Only these files have symbols: JSON (`.json`, `.jsonc`, `.webmanifest`), TOML (`.toml`, `Pipfile`), YAML (`.yaml`,
 `.yml`, `.cff`) and Markdown (`.md`, `.markdown`, `.mdx`). A path into any other file fails the run.
 
-<!-- /extensions-with-symbols -->
+### Writing a path
 
 - **Paths follow RFC 6901.** `/` separates keys. An array item is its position, counted from 0: `#/files/0`.
 - **Pick a list item by a key's value when items can be added above it:** `#/services/~[name=web]/port` is the `port`
@@ -170,19 +162,17 @@ Only these files have symbols: JSON (`.json`, `.jsonc`, `.webmanifest`), TOML (`
 - **A missing key is a violation.** The message suggests similar paths.
 - **A missing or broken file fails the run.** blockwatch does not guess what a broken file meant.
 
-<!-- json-paths -->
+### JSON
 
-**JSON.** Every key and every array item is a symbol.
+Every key and every array item is a symbol.
 
 - A comment is not an array item, so it does not shift the positions after it.
 - A trailing comma breaks the file, even in `.jsonc`.
 - A key written twice is a violation, because blockwatch can't tell which copy you mean.
 
-<!-- /json-paths -->
+### TOML
 
-<!-- toml-paths -->
-
-**TOML.** Every key, every table and every array item is a symbol.
+Every key, every table and every array item is a symbol.
 
 - A path follows the keys, however the file writes them. `[tool.ruff]` with `line-length = 88` below it is
   `#/tool/ruff/line-length`, and so is `tool.ruff.line-length = 88`.
@@ -192,11 +182,9 @@ Only these files have symbols: JSON (`.json`, `.jsonc`, `.webmanifest`), TOML (`
   each place, in order.
 - A key written twice breaks the file.
 
-<!-- /toml-paths -->
-
-<!-- yaml-paths -->
+### YAML
 
-**YAML.** Every key and every list item is a symbol. Block style and flow style give the same paths.
+Every key and every list item is a symbol. Block style and flow style give the same paths.
 
 - A string counts as the text YAML reads, `|` and `>` blocks included. Tags and anchors are not part of a value.
   An empty value (`key:`) is an empty string.
@@ -206,11 +194,9 @@ Only these files have symbols: JSON (`.json`, `.jsonc`, `.webmanifest`), TOML (`
 - A key written twice is a violation.
 - A file with several documents fails the run. Use a named block there instead.
 
-<!-- /yaml-paths -->
+### Markdown
 
-<!-- markdown-paths -->
-
-**Markdown.** Every section is a symbol: a heading and everything up to the next heading of the same or a higher
+Every section is a symbol: 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, the top `#` title included:
 `README.md#/My project/Install/From source`.
 
@@ -223,8 +209,6 @@ level. Its path is the text of each heading it is under, then its own, the top `
 - An `.mdx` file gets the same paths. JSX text and the code in braces count as heading text. A heading inside a JSX
   element doesn't count.
 
-<!-- /markdown-paths -->
-
 ## The config file (`blockwatch.toml`)
 
 Every run reads `blockwatch.toml` from the repository root, from any directory: the hook, CI and your own runs.