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

{blockwatch_cli-0.12.0 → blockwatch_cli-0.13.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,10 @@ 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, 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`.
 
 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 +287,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.13.0}/CHANGELOG.md

@@ -12,6 +12,30 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [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.13.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,10 @@ 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, 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`.
 
 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 +287,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.13.0}/Cargo.lock

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.12.0
+Version: 0.13.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.13.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.13.0  # Use latest release
   hooks:
     - id: blockwatch
 ```

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

@@ -38,3 +38,43 @@ 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 the file marks its sections with plain comments, which are not tags, and these
+# entries make each marked section a named block.
+[[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 -->'
+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 -->'
+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.12.0 → blockwatch_cli-0.13.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.13.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.13.0  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.12.0 → blockwatch_cli-0.13.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.13.0",
+          "semanticVersion": "0.13.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.13.0/docs/validators/keep-sorted.md"
             }
           ]
         }

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

{blockwatch_cli-0.12.0 → blockwatch_cli-0.13.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.