BlockWatch is a linter that keeps your code, documentation, and configuration in sync and enforces strict formatting and validation rules.
It helps you avoid broken docs and messy config files by enforcing rules directly in your comments. You can link code to documentation, auto-sort lists, ensure uniqueness, and even validate content with Regex or AI.
It works with almost any language (Rust, Python, JS, Go, Markdown, YAML, etc.) and can run on your entire repo or just your VCS diffs.
- Drift Detection: Link a block of code to its documentation. If you change the code but forget the docs, BlockWatch alerts you.
- Strict Formatting: Enforce sorted lists (
keep-sorted) and unique entries (keep-unique) so you don't have to nitpick in code reviews. - Content Validation: Check lines against Regex patterns (
line-pattern) or enforce block size limits (line-count). - AI Rules: Use natural language to validate code or text (e.g., "Must mention 'banana'").
- Flexible: Run it on specific files, glob patterns, or just your unstaged changes.
brew tap mennanov/blockwatch
brew install blockwatchcargo install blockwatchCheck the Releases page for prebuilt binaries.
-
Add a special
blocktag in the comments in any supported file (See Supported Languages) like this:user_ids = [ # <block keep-sorted keep-unique> "cherry", "apple", "apple", "banana", # </block> ]
-
Run
blockwatch:blockwatch
BlockWatch will fail and tell you that the list is not sorted and has duplicate entries.
-
Fix the order and uniqueness:
user_ids = [ # <block keep-sorted keep-unique> "apple", "banana", "cherry", # </block> ]
-
Run
blockwatchagain:blockwatch
Now it passes!
You define rules using HTML-like tags inside your comments.
This ensures that if you change some block of code, you're forced to look at the other blocks too.
src/lib.rs:
// <block affects="README.html:supported-langs">
pub enum Language {
Rust,
Python,
}
// </block>README.html:
<!-- <block name="supported-langs"> -->
<ul>
<li>Rust</li>
<li>Python</li>
</ul>
<!-- </block> -->If you modify the enum in src/lib.rs, BlockWatch will fail until you touch the corresponding block supported-langs
in README.html as well.
Keep lists alphabetized. Default is asc (ascending).
# <block keep-sorted>
"apple",
"banana",
"cherry",
# </block>If the list is not sorted alphabetically, BlockWatch will fail until you fix the order.
You can sort by a specific part of the line using a regex capture group named value.
items = [
# <block keep-sorted="asc" keep-sorted-pattern="id: (?P<value>\d+)">
"id: 1 apple",
"id: 2 banana",
"id: 10 orange",
# </block>
]Prevent duplicates in a list.
# <block keep-unique>
"user_1",
"user_2",
"user_3",
# </block>Just like sorting, you can check uniqueness based on a specific regex match.
ids = [
# <block keep-unique="^ID:(?P<value>\d+)">
"ID:1 Alice",
"ID:2 Bob",
"ID:1 Carol", # Violation: ID:1 is already used
# </block>
]Ensure every line matches a specific regex pattern.
slugs = [
# <block line-pattern="^[a-z0-9-]+$">
"valid-slug",
"another-one",
# </block>
]Enforce the number of lines in a block.
Supported operators: <, >, <=, >=, ==.
# <block line-count="<=5">
"a",
"b",
"c"
# </block>Use an LLM to validate logic or style.
<!-- <block check-ai="Must mention the company name 'Acme Corp'"> -->
<p>Welcome to Acme Corp!</p>
<!-- </block> -->Use check-ai-pattern to send only specific parts of the text to the LLM.
prices = [
# <block check-ai="Prices must be under $100" check-ai-pattern="\$(?P<value>\d+)">
"Item A: $50",
"Item B: $150", # Violation
# </block>
]BLOCKWATCH_AI_API_KEY: API Key.BLOCKWATCH_AI_MODEL: Model name (default:gpt-5-nano).BLOCKWATCH_AI_API_URL: Custom OpenAI compatible API URL (optional).
Validate all blocks in your project:
# Check everything
blockwatch
# Check specific files
blockwatch "src/**/*.rs" "**/*.md"
# Ignore stuff
blockwatch "**/*.rs" --ignore "**/generated/**"Tip: Glob patterns should be quoted to avoid shell expanding them.
Pipe a git diff to BlockWatch to validate only the blocks you touched. This is perfect for pre-commit hooks.
# Check unstaged changes
git diff --patch | blockwatch
# Check staged changes
git diff --cached --patch | blockwatch
# Check changes in a specific file only
git diff --patch path/to/file | blockwatch
# Check changes and some other (possibly unchanged) files
git diff --patch | blockwatch "src/always_checked.rs" "**/*.md"You can list all blocks that BlockWatch finds without running any validation. This is useful for auditing your blocks or debugging your configuration.
# List all blocks in the current directory
blockwatch list
# List blocks in specific files
blockwatch list "src/**/*.rs" "**/*.md"
# List only blocks affected by current changes
git diff | blockwatch listThe output is a JSON object.
{
"README.md": [
{
"name": "available-validators",
"line": 18,
"column": 10,
"is_content_modified": false,
"attributes": {
"name": "available-validators"
}
}
]
}Add this to .pre-commit-config.yaml:
- repo: local
hooks:
- id: blockwatch
name: blockwatch
entry: bash -c 'git diff --patch --cached --unified=0 | blockwatch'
language: system
stages: [ pre-commit ]
pass_filenames: falseAdd this to .github/workflows/your_workflow.yml:
- uses: mennanov/blockwatch-action@v1BlockWatch supports comments in:
- Bash
- C#
- C/C++
- CSS
- Go (with
go.mod,go.sumandgo.worksupport) - HTML
- Java
- JavaScript
- Kotlin
- Makefile
- Markdown
- PHP
- Python
- Ruby
- Rust
- SQL
- Swift
- TOML
- TypeScript
- XML
- YAML
- List Blocks:
blockwatch listoutputs a JSON report of all found blocks. - Extensions: Map custom extensions:
blockwatch -E cxx=cpp - Disable Validators:
blockwatch -d check-ai - Enable Validators:
blockwatch -e keep-sorted - Ignore Files:
blockwatch --ignore "**/generated/**"
- Deleted blocks are ignored.
- Files with unsupported grammar are ignored.
Contributions are welcome! A good place to start is by adding support for a new grammar.
cargo test