Eliminate Documentation Drift with BlockWatch Linter

Your Docs Are Likely Obsolete

Developer Renat has introduced BlockWatch, a linter designed to create machine-enforced links between code and documentation. The tool utilizes HTML-like tags in comments to fail CI builds if code changes occur without corresponding documentation updates.

Why This Matters

In typical engineering workflows, documentation accuracy decays immediately after a PR is merged because manual verification of README updates is tedious and easily overlooked during code reviews. By shifting from human discipline to machine-enforced dependencies, teams can prevent the ‘new hire’ scenario where following documented steps fails due to unrecorded code changes, significantly reducing technical debt and onboarding friction.

Key Insights

• The ‘affects’ validator establishes a directional dependency graph where code changes trigger failures if dependent documentation blocks remain untouched.
• BlockWatch leverages Tree-sitter grammars rather than regex to support 20+ languages including Rust, Go, Python, and TypeScript, ensuring robust comment parsing.
• The ‘keep-sorted’ and ‘keep-unique’ validators automate common code review requests, such as maintaining alphabetized configuration lists or unique ID constraints.
• Incremental adoption is supported via ‘git diff’ piping, allowing teams to validate only modified blocks in pre-commit hooks rather than refactoring entire repositories.
• An experimental ‘check-ai’ validator allows for natural language rule enforcement, such as verifying price limits within a specific block of text.

Working Examples

Configuring a code block to trigger a README update requirement.

SUPPORTED_FORMATS = [
# <block affects="README.md:formats" keep-sorted>
"json",
"toml",
"yaml",
# </block>
]

A documentation block that mirrors the Python configuration.

## Supported Formats
<!-- <block name="formats" keep-sorted keep-unique> -->
- JSON
- TOML
- YAML
<!-- </block> -->

Pre-commit hook configuration for incremental validation.

- repo: local
  hooks:
    - id: blockwatch
      name: blockwatch
      entry: bash -c 'git diff --patch --cached --unified=0 | blockwatch'
      language: system
      stages: [pre-commit]
      pass_filenames: false

Practical Applications

• System: API configuration management. Use case: Syncing enum variants in source code with markdown documentation to ensure third-party developers see accurate parameters. Pitfall: Forgetting to update documentation leads to broken integrations and increased support tickets.
• System: CI/CD Pipelines. Use case: Enforcing alphabetized allowed_origins lists in YAML using ‘keep-sorted’ to minimize merge conflicts. Pitfall: Manual sorting is often ignored in high-velocity teams, leading to disorganized and redundant configuration files.

References:

• https://dev.to/mennanov/your-docs-are-likely-obsolete-a17
• https://github.com/mennanov/blockwatch
• https://github.com/mennanov/blockwatch-action@v1