{"id":37514211,"url":"https://github.com/mennanov/blockwatch","last_synced_at":"2026-08-04T05:00:43.522Z","repository":{"id":286655675,"uuid":"948277352","full_name":"mennanov/blockwatch","owner":"mennanov","description":"Language agnostic linter that keeps your code and documentation in sync and valid","archived":false,"fork":false,"pushed_at":"2026-07-18T17:39:52.000Z","size":3055,"stargazers_count":29,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-18T19:22:58.206Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","cli-tools","code-drift","documentation","keep-sorted","linter","linters","pre-commit","rust","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mennanov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-14T03:31:30.000Z","updated_at":"2026-07-18T17:39:56.000Z","dependencies_parsed_at":"2025-06-03T05:05:51.175Z","dependency_job_id":"0cab8a0b-a396-4c6e-b869-89318cae8fe4","html_url":"https://github.com/mennanov/blockwatch","commit_stats":null,"previous_names":["mennanov/blockwatch"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/mennanov/blockwatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mennanov%2Fblockwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mennanov%2Fblockwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mennanov%2Fblockwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mennanov%2Fblockwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mennanov","download_url":"https://codeload.github.com/mennanov/blockwatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mennanov%2Fblockwatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36261000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-04T02:00:06.901Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude-code","cli-tools","code-drift","documentation","keep-sorted","linter","linters","pre-commit","rust","static-analysis"],"created_at":"2026-01-16T08:05:44.257Z","updated_at":"2026-08-04T05:00:43.514Z","avatar_url":"https://github.com/mennanov.png","language":"Rust","funding_links":[],"categories":["Multiple languages","Linting"],"sub_categories":[],"readme":"# BlockWatch\n\n[![Build Status](https://github.com/mennanov/blockwatch/actions/workflows/rust.yml/badge.svg)](https://github.com/mennanov/blockwatch/actions)\n[![codecov](https://codecov.io/gh/mennanov/blockwatch/graph/badge.svg?token=LwUfGTZ551)](https://codecov.io/gh/mennanov/blockwatch)\n[![Crates.io](https://img.shields.io/crates/v/blockwatch)](https://crates.io/crates/blockwatch)\n[![Downloads](https://img.shields.io/crates/d/blockwatch)](https://crates.io/crates/blockwatch)\n\nBlockWatch is a language-agnostic linter that keeps co-dependent code, documentation, and configuration files in sync.\nRules are declared in comments right next to the code they protect.\n\n\u003cp\u003e\n  \u003cimg src=\"demo.gif\" alt=\"BlockWatch Demo\"\u003e\n\u003c/p\u003e\n\n## Quick Start\n\nAdd `\u003cblock\u003e` tags inside comments in any [supported file](#supported-languages):\n\n**src/lib.rs**:\n\n```rust\n// \u003cblock affects=\"README.html:supported-langs\"\u003e\npub enum Language {\n    Rust,\n    Python,\n}\n// \u003c/block\u003e\n```\n\n**README.html**:\n\n```html\n\u003c!-- \u003cblock name=\"supported-langs\"\u003e --\u003e\n\u003cul\u003e\n    \u003cli\u003eRust\u003c/li\u003e\n    \u003cli\u003ePython\u003c/li\u003e\n\u003c/ul\u003e\n\u003c!-- \u003c/block\u003e --\u003e\n```\n\nIf you add a new variant to `Language` in `src/lib.rs` without modifying `README.html`, BlockWatch will report an error.\n\nThe [`affects`](docs/validators/affects.md) validator ensures linked blocks are modified together, while [\n`same-as`](docs/validators/same-as.md) verifies that they agree.\n\nWhen a diff is piped in, only the blocks that diff touched are validated. Adding a rule never fails anyone else's work,\nso you can annotate an existing codebase one file at a time instead of fixing every pre-existing violation up front.\n\n## Validators\n\n[//]: # (\u003cblock name=\"available-validators\"\u003e)\n\n| Attribute                                         | Description                                                      |\n|---------------------------------------------------|------------------------------------------------------------------|\n| [`affects`](docs/validators/affects.md)           | Ensures linked blocks are updated together (e.g. code and docs)  |\n| [`same-as`](docs/validators/same-as.md)           | Verifies that two or more blocks contain identical values        |\n| [`keep-sorted`](docs/validators/keep-sorted.md)   | Enforces alphabetical or numerical ordering on list items        |\n| [`keep-unique`](docs/validators/keep-unique.md)   | Prevents duplicate lines within a block                          |\n| [`line-pattern`](docs/validators/line-pattern.md) | Enforces that every line matches a specified regex               |\n| [`line-count`](docs/validators/line-count.md)     | Enforces lower or upper bounds on the number of lines in a block |\n| [`check-ai`](docs/validators/check-ai.md)         | Validates content against natural language rules using an LLM    |\n| [`check-lua`](docs/validators/check-lua.md)       | Runs custom validation logic written in Lua                      |\n\n[//]: # (\u003c/block\u003e)\n\nBlocks also support `name` (for reference by `affects` or `same-as`) and [\n`severity`](docs/validators/README.md#severity) (e.g., `severity=\"warning\"` to log warnings without breaking builds\nduring gradual rollouts).\n\nSee the [Validators Reference](docs/validators/README.md) for full details.\n\n## Installation\n\n```shell\nbrew install mennanov/blockwatch/blockwatch   # macOS / Linux\ncargo install blockwatch                      # from source\n```\n\nPrebuilt binaries are also available on the [Releases](https://github.com/mennanov/blockwatch/releases) page.\n\n## AI Agent Integration\n\nAdding `\u003cblock\u003e` tags to an existing codebase can be automated using AI coding tools. This repository includes\na [skill](.agents/skills/blockwatch/SKILL.md) that instructs agents on how to identify candidate blocks and verify their\nedits.\n\nFor **Claude Code**:\n\n```text\n/plugin marketplace add mennanov/blockwatch\n/plugin install blockwatch@blockwatch\n```\n\nFor Cursor, Copilot, Codex, and other setup options, see [docs/agents.md](docs/agents.md).\n\n## Usage\n\n```shell\nblockwatch                              # Check all blocks in the repository\nblockwatch \"src/**/*.rs\" \"**/*.md\"      # Check specific globs\ngit diff --patch | blockwatch           # Check only blocks modified in uncommitted changes\ngit diff --cached --patch | blockwatch  # Check only staged changes\nblockwatch list                         # Dump all discovered blocks as JSON\n```\n\nSee [docs/cli.md](docs/cli.md) for CLI flags, path exclusions, and custom extension mappings.\n\n## CI Integration\n\n**pre-commit** (`.pre-commit-config.yaml`):\n\n```yaml\n- repo: https://github.com/mennanov/blockwatch\n  rev: v0.2.27  # Use latest release\n  hooks:\n    - id: blockwatch\n```\n\n**GitHub Actions**:\n\n```yaml\n- uses: mennanov/blockwatch-action@v1\n```\n\nFor plain git hooks, local pre-commit setups, and sandboxing untrusted Lua scripts in fork PRs,\nsee [docs/ci.md](docs/ci.md).\n\n## Supported Languages\n\n[//]: # (\u003cblock name=\"supported-grammar\" keep-sorted=\"asc\"\u003e)\n\n- Bash\n- C#\n- C/C++\n- CMake (`CMakeLists.txt`, `.cmake`)\n- CSS\n- Dart\n- Dockerfile (with `Containerfile` and `.dockerfile` support)\n- Elixir (`.ex`, `.exs`)\n- Go (with `go.mod`, `go.sum` and `go.work` support)\n- GraphQL (`.graphql`, `.gql`)\n- Groovy (with `.gradle` and `Jenkinsfile` support)\n- HCL (Terraform: `.tf`, `.tfvars`, `.hcl`)\n- HTML\n- Java\n- JavaScript\n- Kotlin\n- Lua\n- Makefile\n- Markdown\n- Nix\n- PHP\n- Protocol Buffers (`.proto`)\n- Python\n- Ruby\n- Rust\n- SQL\n- Scala (with `.sbt` support)\n- Starlark (Bazel: `BUILD`, `WORKSPACE`, `MODULE.bazel`, `.bzl`, `.bzlmod`, `.star`)\n- Swift\n- TOML\n- TypeScript\n- XML\n- YAML\n\n[//]: # (\u003c/block\u003e)\n\nTo map custom or unknown extensions to a supported syntax, use `-E`:\n\n```shell\nblockwatch -E cxx=cpp\n```\n\n## Known Limitations\n\n- Deleted blocks are currently ignored.\n- Files with unsupported comment syntaxes are ignored.\n\n## Contributing\n\nContributions are welcome! A great first issue\nis [adding support for a new grammar](https://github.com/mennanov/blockwatch/pull/2).\n\nTo run tests locally:\n\n```shell\ncargo test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmennanov%2Fblockwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmennanov%2Fblockwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmennanov%2Fblockwatch/lists"}