blockwatch-cli 0.16.0__tar.gz → 0.16.2__tar.gz

blockwatch_cli-0.16.2/.agents/skills/blockwatch/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: blockwatch
+description: Use when a change touches something that another place must match, such as an enum and its docs, a constant and its config, a version written in two files, or a list that must stay sorted or unique. Also use it when a file you edit holds `<block ...>` tags, or `blockwatch.toml` points at it.
+allowed-tools: Bash(blockwatch skill)
+---
+
+# blockwatch skill
+
+`blockwatch skill` prints the skill for the installed version:
+
+!`blockwatch skill`
+
+If its output is not shown above, run `blockwatch skill` and follow what it prints. If `blockwatch` is not installed,
+run `uvx --from blockwatch-cli blockwatch skill` instead.

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/AGENTS.md

@@ -279,10 +279,11 @@ default), `safe` or `unsafe`.
 `src/skill.md`, `.agents/skills/blockwatch/SKILL.md` and `.claude-plugin/` are part of the *product*. They make up the
 skill this project ships, so that agents can add blocks to **other** repositories:
 
-- `src/skill.md` is the skill. `blockwatch skill` prints it with the version filled in, and users save that output in
-  their projects.
-- `.agents/skills/blockwatch/SKILL.md` is a stub for the plugin in `.claude-plugin/`. It runs `blockwatch skill` each
-  time it loads. It has its own copy of the description, and `tests/skill.rs` checks that the two copies match.
+- `src/skill.md` is the skill. `blockwatch skill` prints it with the version filled in. Its section "Installing this
+  skill" holds the stub that users save in their projects. The stub runs `blockwatch skill` each time an agent loads
+  it.
+- `.agents/skills/blockwatch/SKILL.md` is that stub, for the plugin in `.claude-plugin/`. `tests/skill.rs` checks that
+  it is the stub in `src/skill.md`, and that its description matches the one at the top of `src/skill.md`.
 
 They are not instructions for working on blockwatch, and changing them changes what users get. This file is the
 guidance for working on blockwatch.

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/CHANGELOG.md

@@ -12,6 +12,46 @@ Releases up to and including v0.3.11 predate this file. Their notes live on the
 
 ## [Unreleased] - ReleaseDate
 
+## [0.16.2] - 2026-10-30
+
+### Added
+
+- Symbols in Java files. `Config.java#/Config/MAX_RETRIES` points at a field of the class `Config`, and
+  `#/Config/Mode/RED` at an enum constant. Each type is a symbol, and so is each field, method, enum constant and
+  nested type in it. A text block counts as the text Java reads, without the indentation its lines share. See
+  [Java](docs/symbols.md#java).
+- Symbols in C# files. `Config.cs#/Acme/Billing/Config/MaxRetries` points at a constant of the class `Config` in the
+  namespace `Acme.Billing`. Each type is a symbol, and so is each field, property, method, event, enum member and
+  nested type in it. A raw string counts as the text C# reads, without the white space before its closing quotes. See
+  [C#](docs/symbols.md#c).
+
+### Changed
+
+- Projects now install the agent skill as a short stub that runs `blockwatch skill` each time an agent loads it. So the
+  skill always matches the installed version. Before, projects saved the whole skill, which went stale until an agent
+  saved it again after an upgrade. A saved copy now tells the agent to replace it with the stub. See
+  [Annotating Codebases with AI Agents](docs/agents.md).
+- The agent skill now loads when a change touches something that another place must match, such as an enum and its
+  docs, or a list that must stay sorted. It also loads for files with block tags, or that `blockwatch.toml` points at.
+  Before, it loaded for every code change. This applies to the Claude Code plugin too.
+
+### Fixed
+
+- A path into a YAML file with lists or mappings nested hundreds of levels deep, such as `a: [[[...]]]`, no longer
+  crashes blockwatch with a stack overflow.
+
+## [0.16.1] - 2026-10-28
+
+### Added
+
+- Symbols in Go, C, C++, Python, Starlark, Rust, TypeScript and JavaScript files. `consts.go#/MaxPorts` points at a
+  top-level constant, variable, type or function, and `limits.h#/MAX_PORTS` at a macro. A value is the initializer as
+  written, such as `20 * 1024 * 1024`, so `same-as` can compare it with a constant in another file without a
+  `target-pattern`. A syntax error stops the run only for the names near it. See [Code files](docs/symbols.md#code-files),
+  [Go](docs/symbols.md#go), [C and C++](docs/symbols.md#c-and-c),
+  [Python and Starlark](docs/symbols.md#python-and-starlark), [Rust](docs/symbols.md#rust) and
+  [TypeScript and JavaScript](docs/symbols.md#typescript-and-javascript).
+
 ## [0.16.0] - 2026-10-24
 
 ### Changed

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/CLAUDE.md

@@ -279,10 +279,11 @@ default), `safe` or `unsafe`.
 `src/skill.md`, `.agents/skills/blockwatch/SKILL.md` and `.claude-plugin/` are part of the *product*. They make up the
 skill this project ships, so that agents can add blocks to **other** repositories:
 
-- `src/skill.md` is the skill. `blockwatch skill` prints it with the version filled in, and users save that output in
-  their projects.
-- `.agents/skills/blockwatch/SKILL.md` is a stub for the plugin in `.claude-plugin/`. It runs `blockwatch skill` each
-  time it loads. It has its own copy of the description, and `tests/skill.rs` checks that the two copies match.
+- `src/skill.md` is the skill. `blockwatch skill` prints it with the version filled in. Its section "Installing this
+  skill" holds the stub that users save in their projects. The stub runs `blockwatch skill` each time an agent loads
+  it.
+- `.agents/skills/blockwatch/SKILL.md` is that stub, for the plugin in `.claude-plugin/`. `tests/skill.rs` checks that
+  it is the stub in `src/skill.md`, and that its description matches the one at the top of `src/skill.md`.
 
 They are not instructions for working on blockwatch, and changing them changes what users get. This file is the
 guidance for working on blockwatch.

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/Cargo.lock

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

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "blockwatch"
-version = "0.16.0"
+version = "0.16.2"
 edition = "2024"
 repository = "https://github.com/mennanov/blockwatch"
 description = "Language agnostic linter that keeps your code and documentation in sync and valid"

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockwatch-cli
-Version: 0.16.0
+Version: 0.16.2
 Summary: Language agnostic linter that keeps your code and documentation in sync and valid
 Keywords: linter,sync,drift,comments,agents
 Home-Page: https://github.com/mennanov/blockwatch

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/README.md

@@ -29,7 +29,7 @@ Then paste this prompt into your AI coding agent:
 <!-- <block name="agent-prompt"> -->
 
 ```text
-Run `blockwatch skill` and save its output as `blockwatch/SKILL.md` in this project's skills directory. Then use the
+Run `blockwatch skill` and install the skill in this project as its "Installing this skill" section says. Then use the
 skill to annotate the project and add `blockwatch.toml` if needed. List each block you added and the mistake it
 catches.
 ```
@@ -37,8 +37,8 @@ catches.
 <!-- </block> -->
 
 Review the suggested blocks and commit them. The skill stays in the project, so agents working on it later know
-the rules too. When you upgrade blockwatch, the skill tells the agent to save it again. To check every future change,
-add blockwatch to your [pre-commit hook or CI](#ci-integration).
+the rules too. It runs `blockwatch skill` each time it loads, so it always matches the installed version. To check every
+future change, add blockwatch to your [pre-commit hook or CI](#ci-integration).
 
 ## How it works
 
@@ -88,9 +88,10 @@ 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, 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.
+Both can point to a block, a whole file, a specific value in a file like `package.json#/version`, a section of a
+Markdown file, or a constant in a Go, C, C++, Python, Rust, TypeScript, JavaScript, Java or C# 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"
@@ -218,7 +219,7 @@ exclusions, and custom extension mappings.
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.0  # Use latest release
+  rev: v0.16.2  # Use latest release
   hooks:
     - id: blockwatch
 ```

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/blockwatch.toml

@@ -39,8 +39,8 @@ same-as = '''.github/workflows/codeql.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
+# `blockwatch skill` prints src/skill.md, and some projects hold a saved copy of 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'
@@ -50,4 +50,4 @@ 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]+)`'
+same-as-pattern = '`\.?(?P<value>[A-Za-z.]+)`'

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/docs/agents.md

@@ -20,16 +20,16 @@ Paste this prompt into your agent. The agent installs the skill in your project
 <!-- <block same-as="README.md:agent-prompt"> -->
 
 ```text
-Run `blockwatch skill` and save its output as `blockwatch/SKILL.md` in this project's skills directory. Then use the
+Run `blockwatch skill` and install the skill in this project as its "Installing this skill" section says. Then use the
 skill to annotate the project and add `blockwatch.toml` if needed. List each block you added and the mistake it
 catches.
 ```
 
 <!-- </block> -->
 
-The skill stays in the project, so agents that work on it later know the rules too. It records the version of
-blockwatch that wrote it. When `blockwatch --version` prints a newer one, the skill tells the agent to save it again.
-Always inspect the generated diff before committing to ensure the added blocks are necessary and accurate.
+The agent saves a short stub, not the whole skill. The stub runs `blockwatch skill` each time it loads, so it always
+matches the installed version. It stays in the project, so agents that work on it later know the rules too. Always
+inspect the generated diff before committing to ensure the added blocks are necessary and accurate.
 
 ## 3. Enable Automated Checks
 
@@ -52,21 +52,20 @@ The plugin's skill runs `blockwatch skill` each time it loads, so it always matc
 
 ### Other AI Tools
 
-For other environments or project-local setups, save the output of `blockwatch skill` to the expected skill location:
+To set up a project by hand, save the stub from
+[Installing this skill](../src/skill.md#installing-this-skill) where your agent reads it:
 
 | Agent               | Location                                               |
 |---------------------|--------------------------------------------------------|
 | **Claude Code**     | Plugin (above) or `.claude/skills/blockwatch/SKILL.md` |
 | **Cursor**          | `.cursor/rules/blockwatch.mdc`                         |
-| **GitHub Copilot**  | Append to `.github/copilot-instructions.md`            |
-| **Codex / generic** | Append to `AGENTS.md`                                  |
+| **GitHub Copilot**  | `.github/copilot-instructions.md`                      |
+| **Codex / generic** | `AGENTS.md`                                            |
 
-For example, for Claude Code:
+`.github/copilot-instructions.md` and `AGENTS.md` hold other instructions too. Add only the stub's description there,
+and the sentence "Then run `blockwatch skill` and follow what it prints."
 
-```shell
-mkdir -p .claude/skills/blockwatch
-blockwatch skill > .claude/skills/blockwatch/SKILL.md
-```
+Don't save the output of `blockwatch skill` itself. A saved copy goes stale when blockwatch is upgraded.
 
 ---
 

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/docs/ci.md

@@ -19,7 +19,7 @@ To use [pre-commit](https://pre-commit.com), add the hook to `.pre-commit-config
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.0  # Use latest release
+  rev: v0.16.2  # Use latest release
   hooks:
     - id: blockwatch
 ```
@@ -59,7 +59,7 @@ The `blockwatch` hook runs before the commit message exists, so it cannot see a
 
 ```yaml
 - repo: https://github.com/mennanov/blockwatch
-  rev: v0.16.0  # Use latest release
+  rev: v0.16.2  # Use latest release
   hooks:
     - id: blockwatch-commit-msg
 ```

{blockwatch_cli-0.16.0 → blockwatch_cli-0.16.2}/docs/cli.md

@@ -557,15 +557,15 @@ Nothing else about the run changes: the same violations are found, and the exit
       "tool": {
         "driver": {
           "name": "blockwatch",
-          "version": "0.16.0",
-          "semanticVersion": "0.16.0",
+          "version": "0.16.2",
+          "semanticVersion": "0.16.2",
           "informationUri": "https://github.com/mennanov/blockwatch",
           "rules": [
             {
               "id": "keep-sorted",
               "name": "keep-sorted",
               "shortDescription": { "text": "Requires the lines of a block to stay in order." },
-              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.16.0/docs/validators/keep-sorted.md"
+              "helpUri": "https://github.com/mennanov/blockwatch/blob/v0.16.2/docs/validators/keep-sorted.md"
             }
           ]
         }
@@ -980,14 +980,9 @@ stay on stderr, under the same file paths and line numbers.
 add value, how to write them, and how to check its work. The text is built into the binary, so it always matches the
 installed version. The command works in any directory, even outside a repository.
 
-Save it into your agent's skills directory:
-
-```shell
-blockwatch skill > .claude/skills/blockwatch/SKILL.md
-```
-
-The saved skill records the version that wrote it. When `blockwatch --version` prints a newer one, the skill tells the
-agent to save it again. See [Annotating Codebases with AI Agents](agents.md).
+Don't save the output itself, because a saved copy goes stale when blockwatch is upgraded. Save the stub from the
+[Installing this skill](../src/skill.md#installing-this-skill) section instead. The stub runs `blockwatch skill` each
+time an agent loads it. See [Annotating Codebases with AI Agents](agents.md).
 
 ## Exit Codes