https://github.com/mennanov/blockwatch
Language agnostic linter that keeps your code and documentation in sync and valid
https://github.com/mennanov/blockwatch
cli-tools documentation linter linters rust static-analysis
Last synced: 41 minutes ago
JSON representation
Language agnostic linter that keeps your code and documentation in sync and valid
- Host: GitHub
- URL: https://github.com/mennanov/blockwatch
- Owner: mennanov
- License: mit
- Created: 2025-03-14T03:31:30.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-13T04:49:03.000Z (4 months ago)
- Last Synced: 2026-02-13T12:39:59.198Z (4 months ago)
- Topics: cli-tools, documentation, linter, linters, rust, static-analysis
- Language: Rust
- Homepage:
- Size: 2.67 MB
- Stars: 22
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- static-analysis - BlockWatch - agnostic linter that keeps code, documentation, and configuration in sync and enforces strict formatting and validation rules. (Multiple languages)
- fucking-static-analysis - BlockWatch - agnostic linter that keeps code, documentation, and configuration in sync and enforces strict formatting and validation rules. (Multiple languages)
README
# BlockWatch
[](https://github.com/mennanov/blockwatch/actions)
[](https://codecov.io/gh/mennanov/blockwatch)
[](https://crates.io/crates/blockwatch)
[](https://crates.io/crates/blockwatch)
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, enforce sorted lists, ensure uniqueness, and even validate content with Regex, AI, or custom Lua scripts.
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.
## Annotate your project with an AI agent (recommended)
Adding the first `` tags by hand is the tedious part of picking up BlockWatch.
AI coding agents are good at this. An agent can read through the repo, pick reasonable spots, add the tags in the
correct comment syntax for each language, and run `blockwatch` to check its own work.
There's a skill in this repo for it: [`.agents/skills/blockwatch/SKILL.md`](.agents/skills/blockwatch/SKILL.md). It
tells
the agent where blocks are worth adding, documents the tag syntax, and explains how to verify the result.
**1. Install the binary** so the agent can run it:
```shell
cargo install blockwatch # or: brew install mennanov/blockwatch/blockwatch
```
**2. Give the skill to your agent.**
**Claude Code users:** install the plugin once and the skill is available in every project — no
per-project setup:
```text
/plugin marketplace add mennanov/blockwatch
/plugin install blockwatch@blockwatch
```
For other agents (or if you prefer a project-local copy), place `SKILL.md` where your tool looks
for instructions:
| Agent | Where to put the skill |
|--------------------|-------------------------------------------------------------------------------------------------------------------------|
| **Claude Code** | Use the plugin above (recommended), or `.claude/skills/blockwatch/SKILL.md` (project) / `~/.claude/skills/...` (global) |
| **Cursor** | `.cursor/rules/blockwatch.mdc` |
| **GitHub Copilot** | append to `.github/copilot-instructions.md` |
| **Codex / others** | append to `AGENTS.md` |
You can pull the file straight from this repo:
```shell
mkdir -p .claude/skills/blockwatch
curl -sL https://raw.githubusercontent.com/mennanov/blockwatch/main/.agents/skills/blockwatch/SKILL.md \
-o .claude/skills/blockwatch/SKILL.md
```
**3. Ask the agent to annotate the project**, for example:
> Using the BlockWatch skill, annotate this repository with `` tags. Focus on lists that should stay
> sorted/unique and on code that must stay in sync with docs or config. Add only high-value blocks, then run
> `blockwatch` to confirm they all pass.
Review the diff before you commit it: the agent's choices are a starting point.
**4. Turn on enforcement** so the rules stay in place: wire up the pre-commit hook and GitHub Action from
[CI Integration](#ci-integration).
## Features
[//]: # ()
- **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'").
- **Lua Scripting**: Write custom validation logic in Lua scripts (`check-lua`).
- **Flexible**: Run it on specific files, glob patterns, or just your unstaged changes.
[//]: # ()
## Installation
### Homebrew (macOS/Linux)
```shell
brew install mennanov/blockwatch/blockwatch
```
The fully-qualified name keeps working once Homebrew starts requiring
[explicit trust](https://docs.brew.sh/Tap-Trust) for third-party taps: it trusts only the
`blockwatch` formula, not the whole tap. If you install via a `Brewfile`, use:
```ruby
brew "mennanov/blockwatch/blockwatch", trusted: true
```
### From Source (Rust)
```shell
cargo install blockwatch
```
### Prebuilt Binaries
Check the [Releases](https://github.com/mennanov/blockwatch/releases) page for prebuilt binaries.
## Quick start example
1. Add a special `block` tag in the comments in any supported file ([See *Supported Languages*](#supported-languages))
like this:
```python
user_ids = [
#
"cherry",
"apple",
"apple",
"banana",
#
]
```
2. Run `blockwatch`:
```shell
blockwatch
```
BlockWatch will fail and tell you that the list is not sorted and has duplicate entries.
3. Fix the order and uniqueness:
```python
user_ids = [
#
"apple",
"banana",
"cherry",
#
]
```
4. Run `blockwatch` again:
```shell
blockwatch
```
Now it passes!
## How It Works
You define rules using HTML-like tags inside your comments.
### Linking Code Blocks (`affects`)
This ensures that if you change some block of code, you're forced to look at the other blocks too.
**src/lib.rs**:
```rust
//
pub enum Language {
Rust,
Python,
}
//
```
**README.html**:
```html
- Rust
- Python
```
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.
### Enforce Sort Order (`keep-sorted`)
Keep lists alphabetized. Default is `asc` (ascending).
```python
#
"apple",
"banana",
"cherry",
#
```
If the list is not sorted alphabetically, BlockWatch will fail until you fix the order.
#### Sort by Regex
You can sort by a specific part of the line using a regex capture group named `value`.
```python
items = [
#
"id: 1 apple",
"id: 2 banana",
"id: 10 orange",
#
]
```
#### Numeric Sort (`keep-sorted-format`)
By default, values are compared lexicographically (as strings). This means `"10"` sorts before `"2"` because `"1" < "2"`
character-by-character. Use `keep-sorted-format="numeric"` to compare values as numbers instead.
```python
numbers = [
#
2
10
20
#
]
```
This works with `keep-sorted-pattern` to extract numeric values from lines with mixed content:
```python
items = [
#
"id: 2 banana",
"id: 10 orange",
"id: 20 apple",
#
]
```
Without `keep-sorted-format="numeric"`, the example above would fail because `"10"` is lexicographically less than
`"2"`.
### Enforce Unique Lines (`keep-unique`)
Prevent duplicates in a list.
```python
#
"user_1",
"user_2",
"user_3",
#
```
#### Uniqueness by Regex
Just like sorting, you can check uniqueness based on a specific regex match.
```python
ids = [
#
"ID:1 Alice",
"ID:2 Bob",
"ID:1 Carol", # Violation: ID:1 is already used
#
]
```
### Regex Validation (`line-pattern`)
Ensure every line matches a specific regex pattern.
```python
slugs = [
#
"valid-slug",
"another-one",
#
]
```
### Enforce Line Count (`line-count`)
Enforce the number of lines in a block.
Supported operators: `<`, `>`, `<=`, `>=`, `==`.
```python
#
"a",
"b",
"c"
#
```
### Validate with AI (`check-ai`)
Use an LLM to validate logic or style.
```html
Welcome to Acme Corp!
```
#### Targeted AI Checks
Use `check-ai-pattern` to send only specific parts of the text to the LLM.
```python
prices = [
#
"Item A: $50",
"Item B: $150", # Violation
#
]
```
#### Supported environment variables
[//]: # ()
- `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 with Lua Scripts (`check-lua`)
Run custom validation logic using a Lua script. The script must define a global `validate(ctx, content)` function that
returns `nil` if validation passes or a string error message if it fails.
```python
colors = [
#
'red',
'green',
'blue',
#
]
```
**scripts/validate_colors.lua**:
```lua
function validate(ctx, content)
if content:find("purple") then
return "purple is not an allowed color"
end
return nil
end
```
The `validate` function receives two arguments:
- `ctx` — a table with the following fields:
- `ctx.file` — the source file path.
- `ctx.line` — the line number of the block's start tag.
- `ctx.attrs` — a table of all block attributes.
- `content` — the trimmed text content of the block.
#### Lua safety mode
By default, Lua scripts run in a **sandboxed** mode with only the `coroutine`, `table`, `string`, `utf8`, and `math`
standard libraries available. The `io`, `os`, and `package` libraries are **not** loaded, preventing file system access,
command execution, and loading of external modules.
You can change the security level by setting the `BLOCKWATCH_LUA_MODE` environment variable:
```shell
# Allow IO and OS libraries (memory-safe, but with file/system access)
BLOCKWATCH_LUA_MODE=safe blockwatch
# Allow all libraries including C module loading (unsafe)
BLOCKWATCH_LUA_MODE=unsafe blockwatch
```
| `BLOCKWATCH_LUA_MODE` | Libraries available | Security Level |
|-----------------------|-----------------------------------------------------------------------|-------------------------------------|
| `sandboxed` (default) | `coroutine`, `table`, `string`, `utf8`, `math` | Most secure - No file/OS access |
| `safe` | All memory-safe libraries (including `io`, `os`, `package`) | Memory-safe - Allows file/OS access |
| `unsafe` | All Lua standard libraries with no restrictions (including C modules) | Unsafe - Full system access |
## Usage
### Run Locally
Validate all blocks in your project:
```shell
# 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.
### Check Only What Changed
Pipe a git diff to BlockWatch to validate only the blocks you touched. This is perfect for pre-commit hooks.
```shell
# 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"
```
### Listing Blocks
You can list all blocks that BlockWatch finds without running any validation. This is useful for auditing your blocks or
debugging your configuration.
```shell
# 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 (reads the diff from stdin)
git diff | blockwatch list --diff
```
`blockwatch list` does not read stdin by default, so it never blocks waiting for
input. This makes it safe to run non-interactively — in CI, or when invoked by
another program such as an AI agent — and to feed its JSON output into a pipe,
e.g. `blockwatch list "src/**/*.ts" | jq`. Pass `--diff` to opt in to reading a
unified diff from stdin; `list` then reports which blocks the diff touched via
the `is_content_modified` field.
The output is a JSON object.
#### Example Output
[//]: # ()
```json
{
"README.md": [
{
"name": "available-validators",
"line": 18,
"column": 10,
"is_content_modified": false,
"attributes": {
"name": "available-validators"
}
}
]
}
```
[//]: # ()
### CI Integration
#### Pre-commit Hook
Add this to `.pre-commit-config.yaml` (pre-commit builds blockwatch from source with cargo on first run):
```yaml
- repo: https://github.com/mennanov/blockwatch
rev: v0.2.27 # use the latest release tag
hooks:
- id: blockwatch
```
If you already have the `blockwatch` binary installed (e.g. via Homebrew), you can use the local form instead:
```yaml
- repo: local
hooks:
- id: blockwatch
name: blockwatch
entry: bash -c 'git diff --cached --patch --unified=0 | blockwatch'
language: system
stages: [ pre-commit ]
pass_filenames: false
```
#### GitHub Action
Add this to `.github/workflows/your_workflow.yml`:
```yaml
- uses: mennanov/blockwatch-action@v1
```
## Supported Languages
BlockWatch supports comments in:
[//]: # ()
- Bash
- C#
- C/C++
- CSS
- Go (with `go.mod`, `go.sum` and `go.work` support)
- HTML
- Java
- JavaScript
- Kotlin
- Makefile
- Markdown
- PHP
- Python
- Ruby
- Rust
- SQL
- Swift
- TOML
- TypeScript
- XML
- YAML
[//]: # ()
## CLI Options
[//]: # ()
- **List Blocks**: `blockwatch list` outputs 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/**"`
[//]: # ()
## Known Limitations
- Deleted blocks are ignored.
- Files with unsupported grammar are ignored.
## Contributing
Contributions are welcome! A good place to start is
by [adding support for a new grammar](https://github.com/mennanov/blockwatch/pull/2).
### Run Tests
```shell
cargo test
```