tree-police 0.2.0__tar.gz

tree_police-0.2.0/.dockerignore

@@ -0,0 +1,3 @@
+*
+!dist/amd64/tree-police
+!dist/arm64/tree-police

tree_police-0.2.0/.envrc

@@ -0,0 +1 @@
+use flake

tree_police-0.2.0/.github/workflows/cli-release.yml

@@ -0,0 +1,112 @@
+name: CLI release
+
+# Only on a version tag -- unlike the Docker image (release.yml), which
+# republishes `:latest` on every push to main, a GitHub Release should be a
+# deliberate, versioned act.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  build-linux:
+    # Cross-compiled via Nix (not Docker buildx/QEMU) on one amd64 runner --
+    # same musl-static binaries release.yml builds for the Docker image.
+    # Everything (all ~90 grammars, the embedded query files) is statically
+    # linked in; there's no separate grammars folder to ship.
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - nix_package: tree-police-static-x86_64
+            target: x86_64-unknown-linux-musl
+          - nix_package: tree-police-static-aarch64
+            target: aarch64-unknown-linux-musl
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Build (musl cross)
+        run: nix build ".#${{ matrix.nix_package }}" -o result
+
+      - name: Package
+        run: |
+          mkdir -p dist
+          install -m755 result/bin/tree-police tree-police
+          tar czf "dist/tree-police-${{ matrix.target }}.tar.gz" tree-police
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: tree-police-${{ matrix.target }}
+          path: dist/*.tar.gz
+
+  build-macos:
+    # Native builds, one job per arch -- GH's macos-15-intel runner is
+    # Intel, macos-14 is Apple Silicon (GH's "-latest"/bare "macos-NN"
+    # labels default to Apple Silicon now; Intel needs the explicit
+    # "-intel" suffix), so `cargo build --release` with no explicit
+    # --target already produces the right binary for each; no cross-compile
+    # or universal-binary step needed. Not Nix/musl: macOS has no musl
+    # equivalent, dynamic linking against system libs is normal here.
+    strategy:
+      matrix:
+        include:
+          - os: macos-15-intel
+            target: x86_64-apple-darwin
+          - os: macos-14
+            target: aarch64-apple-darwin
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Build
+        run: cargo build --release
+
+      - name: Package
+        run: |
+          mkdir -p dist
+          install -m755 target/release/tree-police tree-police
+          tar czf "dist/tree-police-${{ matrix.target }}.tar.gz" tree-police
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: tree-police-${{ matrix.target }}
+          path: dist/*.tar.gz
+
+  release:
+    needs: [build-linux, build-macos]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      # Same CycloneDX SBOM attached to the Docker image (release.yml) --
+      # describes the Cargo dependency graph, which is identical across all
+      # four binaries above, so one SBOM covers the whole release.
+      - name: Build SBOM (nix)
+        run: |
+          nix build .#sbom -o sbom-result
+          cp sbom-result/bom.json tree-police.cdx.json
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: tree-police-*
+          merge-multiple: true
+
+      - name: Checksums
+        run: (cd dist && sha256sum -- *.tar.gz > checksums.txt)
+
+      - name: Create release
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            dist/*.tar.gz dist/checksums.txt tree-police.cdx.json \
+            --title "${{ github.ref_name }}" \
+            --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

tree_police-0.2.0/.github/workflows/pypi-release.yml

@@ -0,0 +1,152 @@
+name: PyPI release
+
+# Wheels that wrap the `tree-police` binary (maturin `bindings = "bin"`, see
+# python/pyproject.toml), so `pip install tree-police` / `uv tool install
+# tree-police` works without Docker or a Rust toolchain. Published only from
+# a version tag (same trigger as cli-release.yml). Pull requests that touch
+# the packaging, and manual runs, build and smoke-test every wheel without
+# publishing.
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+    paths:
+      - pyproject.toml
+      - python/**
+      - .pre-commit-hooks.yaml
+      - .github/workflows/pypi-release.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    # manylinux wheels are for glibc distros, musllinux ones for Alpine & co.
+    # Not the Nix musl-static build cli-release.yml uses: pip only installs a
+    # wheel whose platform tag matches the host, so glibc hosts need a
+    # manylinux-tagged build from maturin's manylinux containers. aarch64
+    # builds natively on GitHub's arm runner rather than cross-compiling the
+    # C/C++ grammars.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { runner: ubuntu-latest, target: x86_64, manylinux: "2_28" }
+          - { runner: ubuntu-24.04-arm, target: aarch64, manylinux: "2_28" }
+          - { runner: ubuntu-latest, target: x86_64, manylinux: musllinux_1_2 }
+          - { runner: ubuntu-24.04-arm, target: aarch64, manylinux: musllinux_1_2 }
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux }}
+          working-directory: python
+          args: --release --out ../dist
+          sccache: "true"
+
+      # The runner is glibc, so only the manylinux wheel installs on it.
+      - name: Smoke test
+        if: matrix.manylinux != 'musllinux_1_2'
+        run: |
+          python3 -m venv .venv
+          .venv/bin/pip install --no-index --find-links dist tree-police
+          .venv/bin/tree-police --version
+          .venv/bin/tree-police --list-rules >/dev/null
+
+      # The `tree-police` hook (.pre-commit-hooks.yaml) installs the root
+      # pyproject.toml stub, which pins this version on PyPI. Point pip at the
+      # wheel just built instead, so the hook is tested before publishing.
+      - name: Pre-commit hook smoke test
+        if: matrix.target == 'x86_64' && matrix.manylinux == '2_28'
+        env:
+          PIP_FIND_LINKS: ${{ github.workspace }}/dist
+        run: |
+          .venv/bin/pip install pre-commit
+          .venv/bin/pre-commit try-repo . tree-police \
+            --files tests/fixtures/python/clean.py tests/fixtures/terraform/clean.tf
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}-${{ matrix.manylinux }}
+          path: dist/*.whl
+
+  macos:
+    # Same native Intel / Apple Silicon split as cli-release.yml.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { runner: macos-15-intel, target: x86_64 }
+          - { runner: macos-14, target: aarch64 }
+    runs-on: ${{ matrix.runner }}
+    env:
+      # Otherwise the wheel is tagged for the build host's macOS (a local
+      # build on macOS 14 came out as macosx_14_0) and pip refuses it on
+      # anything older. 11.0 is the first Apple Silicon release.
+      MACOSX_DEPLOYMENT_TARGET: ${{ matrix.target == 'x86_64' && '10.13' || '11.0' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          working-directory: python
+          args: --release --out ../dist
+          sccache: "true"
+
+      - name: Smoke test
+        run: |
+          python3 -m venv .venv
+          .venv/bin/pip install --no-index --find-links dist tree-police
+          .venv/bin/tree-police --version
+          .venv/bin/tree-police --list-rules >/dev/null
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist/*.whl
+
+  sdist:
+    # Fallback for platforms without a wheel (needs Rust + a C/C++ compiler
+    # on the installing machine).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          working-directory: python
+          args: --out ../dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    # PyPI trusted publishing (OIDC) -- no API token stored in the repo. Needs
+    # a one-time trusted-publisher entry on PyPI for this repo, this workflow
+    # file and the `pypi` environment.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [linux, macos, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/tree-police/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

tree_police-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Build and publish image
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      # Cross-compiled via Nix, not Docker buildx/QEMU: each is a genuine
+      # musl-static binary for its target, built once on this amd64 runner.
+      - name: Build static binaries (musl cross, both arches)
+        run: |
+          nix build .#tree-police-static-x86_64 -o result-amd64
+          nix build .#tree-police-static-aarch64 -o result-arm64
+
+      - name: Stage build context
+        run: |
+          mkdir -p dist/amd64 dist/arm64
+          install -m755 result-amd64/bin/tree-police dist/amd64/tree-police
+          install -m755 result-arm64/bin/tree-police dist/arm64/tree-police
+
+      # CycloneDX SBOM of the exact dependency set in Cargo.lock, built the
+      # same reproducible way as the binaries (see flake.nix's `sbom`
+      # package). One SBOM covers both architectures -- it describes the
+      # Cargo dependency graph, not per-arch binary contents.
+      - name: Build SBOM (nix)
+        run: nix build .#sbom -o sbom-result
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+
+      # Only sets up the container driver so buildx can assemble a
+      # multi-platform manifest list; no QEMU needed since the Dockerfile
+      # just COPYs a prebuilt static binary per `TARGETARCH` -- no RUN step
+      # ever executes in the target architecture.
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/build-push-action@v6
+        id: push
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - uses: sigstore/cosign-installer@v3
+
+      # Attaches to the exact digest just pushed (not a mutable tag), as an
+      # OCI referrer in the same registry -- `cosign download sbom
+      # ghcr.io/<repo>@<digest>` (or any OCI-referrers-aware scanner) finds
+      # it from the image alone, no separate URL to track.
+      - name: Attach SBOM to published image
+        run: |
+          cosign attach sbom \
+            --type cyclonedx \
+            --sbom sbom-result/bom.json \
+            "ghcr.io/${{ github.repository }}@${{ steps.push.outputs.digest }}"

tree_police-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.direnv/
+result
+sbom-result
+
+# Rust build artifacts (Cargo.lock is committed)
+/target/
+
+# docker-build staging dir (dereferenced copy of result/bin/tree-police)
+/dist/
+
+# generated by `just sbom` (see flake.nix's `sbom` package)
+/sbom.cdx.json

tree_police-0.2.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,16 @@
+{
+  // THIRD-PARTY-LICENSES.md is generated (`just third-party-licenses`) from
+  // upstream crates' own license texts -- not hand-authored prose, and not
+  // ours to reformat.
+  "ignores": ["THIRD-PARTY-LICENSES.md"],
+  "config": {
+    // Hard 80-column wrapping doesn't suit docs full of inline code, links,
+    // and tables; line content matters more than column count here.
+    "MD013": false,
+    // README.md's logo <img> comes before the H1 on purpose (float it
+    // right of the title); both rules exist to catch accidental HTML/
+    // missing titles, not this deliberate pattern.
+    "MD033": false,
+    "MD041": false
+  }
+}

tree_police-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+# This repo's own dev-workflow checks (not to be confused with
+# .pre-commit-hooks.yaml, which is what makes *this repo* usable as a
+# pre-commit hook source for other repos' Python/Terraform/etc. scanning).
+#
+# All hooks use `language: system` and run straight off the Nix devShell's
+# PATH (see flake.nix) -- no separate per-hook virtualenv/npm install, and
+# no tool version drifts from what `direnv allow`/`nix develop` already
+# pins. Run `direnv allow` (or `nix develop`) once, then `pre-commit install`.
+repos:
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt
+        language: system
+        entry: cargo fmt -- --check
+        files: \.rs$
+        pass_filenames: false
+
+      - id: cargo-clippy
+        name: cargo clippy (deny warnings)
+        language: system
+        entry: cargo clippy --all-targets --release -- --deny warnings
+        files: \.rs$
+        pass_filenames: false
+
+      - id: nix-fmt
+        name: alejandra (nix fmt, check only)
+        language: system
+        entry: alejandra --check
+        files: \.nix$
+
+      - id: nix-statix
+        name: statix (nix lint)
+        language: system
+        entry: statix check
+        files: \.nix$
+        pass_filenames: false
+
+      - id: nix-deadnix
+        name: deadnix (nix dead code)
+        language: system
+        entry: deadnix --fail
+        files: \.nix$
+        pass_filenames: false
+
+      - id: markdownlint
+        name: markdownlint-cli2
+        language: system
+        entry: markdownlint-cli2
+        files: \.md$
+
+      - id: actionlint
+        name: actionlint (GitHub Actions workflows)
+        language: system
+        entry: actionlint
+        files: ^\.github/workflows/.*\.ya?ml$
+        pass_filenames: false

tree_police-0.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,24 @@
+# Installs the prebuilt `tree-police` wheel from PyPI via the stub package in
+# the root pyproject.toml -- needs only Python, no Docker, no Rust toolchain.
+- id: tree-police
+  name: tree-police (AST pattern scan)
+  description: >-
+    Scan source files for forbidden AST patterns via tree-sitter queries.
+    Drop extra rules in a repo-local .tree-police/ directory to extend the
+    built-in ruleset with no image rebuild.
+  entry: tree-police --fail-on error
+  language: python
+  pass_filenames: true
+  # The binary already scans files in parallel; one process per batch of
+  # filenames is plenty.
+  require_serial: true
+
+# Same scan via the ghcr.io image, for machines that prefer Docker over a
+# Python environment.
+- id: tree-police-docker
+  name: tree-police (AST pattern scan, Docker)
+  description: >-
+    Same as `tree-police`, run from the ghcr.io/imochoa/tree-police image.
+  entry: ghcr.io/imochoa/tree-police:latest --fail-on error
+  language: docker_image
+  pass_filenames: true

tree_police-0.2.0/AGENTS.md

@@ -0,0 +1,191 @@
+# AGENTS.md (tree-police)
+
+Guide for AI coding agents working on `tree-police`. Human docs live in
+[`README.md`](README.md) and [`queries/README.md`](queries/README.md); this
+file is the fast path.
+
+## What this is
+
+A declarative linter, embeddable as a pre-commit `docker_image` hook: `.scm`
+query files in `queries/` are compiled and embedded into the `tree-police`
+binary at build time (`include_dir!` in `src/rules.rs`). Parses each file
+once, in parallel (`ignore` + `rayon`), with severity levels and
+pretty/JSON/JSONL output.
+
+Rules currently cover Python and Terraform/HCL. `src/registry.rs` also bakes
+in 90 other grammars (92 languages total) with no rule files yet — every
+tree-sitter grammar crate on crates.io compatible with this crate's pinned
+`tree-sitter` core version (see the comment above `registry::LANGUAGES` for
+what's excluded and why). A new rule file is all that's needed to start
+covering one of them, no Cargo/registry change required, and a pre-commit
+hook can pass every changed file without its own file-type allowlist
+(unrecognized extensions are just skipped).
+
+## Getting started
+
+```bash
+direnv allow   # or: nix develop
+```
+
+The dev shell provides the Rust toolchain (`rustc`, `cargo`, `clippy`,
+`rustfmt`), a C/C++ compiler (the grammar crates compile their grammars via
+their own `build.rs`), and `just`.
+
+## Commands
+
+All commands are recipes in the [`justfile`](justfile). Exit codes: `0` =
+no findings, `1` = findings detected (suitable for CI gates), `2` = internal error.
+
+| Command | Purpose |
+| --- | --- |
+| `just build` | `cargo build --release`. |
+| `just scan-bin [args]` | Run `tree-police`. Args pass through, e.g. `just scan-bin --format json src/`. |
+| `just query-test` | `cargo test --test query_cases` — per-rule annotated fixtures; see below. |
+| `just test` | `cargo test` — unit tests + black-box CLI tests (`tests/cli.rs`) + query-case tests. |
+| `just docker-build` | `nix build .#tree-police-static`, then `podman build` a `FROM scratch` image. |
+| `just docker-run [args]` | Run the built image (`-t` for color; see the recipe comment). |
+| `just wheel` | `maturin build --release`: the binary as a Python wheel in `target/wheels/` (see `python/pyproject.toml`). |
+| `just third-party-licenses` | Regenerate `THIRD-PARTY-LICENSES.md` from `Cargo.lock`. |
+| `just sbom` | Build a CycloneDX SBOM (`sbom.cdx.json`) via Nix. |
+| `just release X.Y.Z` | Bump the version, run the test/lint gate, commit, tag `vX.Y.Z`, and push — triggers the Docker, GitHub Release and PyPI workflows. Requires a clean `main` with no existing tag of that name. |
+
+## Layout
+
+```text
+.
+├── flake.nix                 # devShell: Rust toolchain; tree-police-static (musl) package
+├── Cargo.toml / Cargo.lock    # crate manifest (lockfile committed)
+├── Dockerfile / .dockerignore
+├── pyproject.toml             # pre-commit hook stub: only pins the `tree-police` PyPI wheel
+├── python/pyproject.toml      # maturin `bindings = "bin"`: ships the binary as a PyPI wheel
+├── .pre-commit-hooks.yaml     # `tree-police` (python, PyPI wheel) + `tree-police-docker` hooks
+├── .github/workflows/         # image (ghcr.io), CLI tarballs (GitHub Release), wheels (PyPI)
+├── src/                       # main, registry, rules, scan, report, severity, config, suppress
+├── tests/cli.rs               # black-box CLI tests
+├── tests/query_cases.rs       # per-rule annotated fixture tests (see below)
+├── .envrc                     # direnv: `use flake`
+├── justfile                   # build / scan-bin / test / docker-* commands
+├── queries/                   # flat: <label>-<code>.scm, see queries/README.md
+│   ├── rules-py.scm           # categories: forbidden, security, temporal, web
+│   └── rules-tf.scm           # categories: naming, conventions, security
+├── tests/fixtures/            # whole-file good/bad samples for tests/cli.rs
+│   ├── python/
+│   └── terraform/
+├── tests/query-cases/         # per-rule annotated fixtures for `just query-test`
+│   └── python/
+├── README.md
+└── queries/README.md          # rule conventions
+```
+
+## Adding a rule
+
+1. Add a pattern to `queries/<label>-<code>.scm` (`<code>` from
+   `src/registry.rs`, e.g. `py`, `tf`); embedded on the next `cargo build`.
+2. Give each pattern exactly **one** non-`_` `@capture` — it is the rule ID in output (e.g. `@s3_bucket_missing_sf_prefix`). Prefix every predicate-only helper capture with `_` (e.g. `@_block_type`) so `tree-police` doesn't report it. Declare severity with `(#set! severity "error|warning|log")` (defaults to `warning`); optionally add `(#set! category "…")` (groups `--list-rules` output) and `(#set! description "…")` (shown per-finding and in `--list-rules`).
+3. Add fixtures under `tests/fixtures/<language>/`:
+   - `*_violations.<ext>` — code that must trigger captures.
+   - `clean.<ext>` — code that must produce zero captures.
+4. Add an assertion to `tests/cli.rs` for the new rule.
+5. Add a `tests/query-cases/<language>/<topic>.<ext>` fixture (see below) and run `just query-test`.
+
+## Query-case tests
+
+`tests/query-cases/<lang>/<topic>.<ext>` are annotated fixtures, grouped by
+topic/category rather than by `.scm` file (there's one `.scm` file per
+language), checked by `tests/query_cases.rs` (`just query-test`, wired into
+`just test`). A comment names the capture expected on the line directly
+above it:
+
+```python
+print("debug")
+# <- @forbidden_print
+```
+
+Unlike `tree-sitter query --test` (same comment syntax, but it mis-pairs
+assertions once a query file defines more than one distinct capture name —
+confirmed by testing, not a guess), this harness checks each assertion
+against the actual capture spans directly, and — the other direction —
+fails if any capture fires on a line with no matching assertion. That gives
+both "should match" and "should not match" coverage from one file, which
+whole-file `tests/fixtures/*` checks don't: a rule firing on the wrong line
+of a big fixture still passes a file-level `assert_clean`/`assert_match`.
+
+An unannotated line is an *implicit* "nothing should fire here" assertion —
+there's no separate negative-assertion syntax, and no need for one. Put each
+rule's positive example directly above its negative counterexample (not in
+a separate "clean" section at the bottom); see any file under
+`tests/query-cases/python/` for the pattern.
+
+It runs the **compiled `tree-police` matcher** directly (via
+`tree_police::rules::load()`), not a subprocess. It caught a real bug when
+this engine's rule files were consolidated to one per language: because
+every rule now applies to every fixture, a rule's negative example in one
+topic's fixture started tripping an unrelated rule from another category —
+see the cross-category caveat in `queries/README.md`.
+
+## Adding a language
+
+1. Add the `tree-sitter-<lang>` crate to `Cargo.toml` and one `LangSpec`
+   entry (`name`, `code`, `extensions`, `LANGUAGE.into()`) to
+   [`src/registry.rs`](src/registry.rs).
+2. Add `queries/<label>-<code>.scm` rule file(s), matching the new `code`.
+3. Add fixtures and `tests/cli.rs` assertions as above.
+
+Adding just the grammar + registry entry with no rule file yet is fine and
+already done for several languages (see "What this is") — it costs nothing
+at scan time (files with no rules for their language are skipped) and means
+a future rule file needs no Cargo/registry change.
+
+## Path scoping and suppressions
+
+`src/config.rs` loads `.tree-police/config.toml` (or `--config FILE`). In it,
+`[[scope]]` entries restrict the selected rules to `paths` and/or keep them
+out of `exclude`, and `[[override]]` entries change severity per path.
+`src/suppress.rs` reads `tree-police: ignore` / `ignore-next-line` /
+`ignore-file` directives from comment nodes. Both run per file inside
+`scan::scan_file`, after matching. Selectors (`rule_id`,
+`category:<name>`, `file:<query-file-name>`) are checked against
+`config::Catalog`. An unknown selector is a hard error in the config but
+only a warning in a comment. User docs are in README "Config file" and
+"Suppressing findings".
+
+Renaming a rule ID or category also breaks any config file or suppression
+comment that refers to it, which is one more reason to keep them stable.
+
+## Gotchas
+
+- **The root `pyproject.toml` is not the real package.** pre-commit/prek install a `language: python` hook with `pip install .` on the repo root, so the root holds a stub that only depends on `tree-police==<version>` from PyPI. That way hook users get the prebuilt wheel instead of compiling 92 grammars. The maturin config lives in `python/pyproject.toml` (README and licenses are symlinked in). `just release` bumps the stub's pin, and `tests/packaging.rs` fails if it drifts from `Cargo.toml`. A new tag's hook can only be installed once `pypi-release.yml` has published that version.
+
+- **No regex lookaheads.** Rust's `regex` crate rejects `(?!...)` / `(?=...)`. Split into separate `#not-match?` / `#match?` predicates on the same capture instead.
+- **A predicate can't reference the capture on its own enclosing node.** A node's capture is only declared at its closing paren, so a predicate that's one of that node's *own children* comes before the capture exists, textually — `(node (child) (#pred? @x) ) @x` fails to compile ("Invalid capture name"). Wrap the captured node and the predicate together in one more pair of parens instead — `((node (child)) @x (#pred? @x ...))` — so they become siblings at the outer level, where ordering works. See `missing_route_validation` in `queries/rules-py.scm` (and `bare_except`/`todo`, which use the same wrapping).
+- **Only literal strings are visible to queries.** Interpolated expressions (`"${var.env}-thing"`) aren't matched against string predicates — those need runtime validation elsewhere.
+- **`#set!` severity + `_`-helper captures are load-bearing.** The one non-`_` capture per pattern is the reported rule ID; severity comes from `(#set! severity …)` (default `warning`).
+- **Non-core predicates don't just go unenforced — they zero out the whole match.** `#not-has-ancestor?` and similar are silently treated as unsatisfied by the embedded `tree_sitter::QueryCursor` matcher, dropping the match entirely rather than ignoring the predicate. Confirmed by testing (`tests/query_cases.rs`), not documented upstream. Avoid them.
+- **Rule IDs and `category` values are stable identifiers** — referenced by CI/config elsewhere, don't rename without a coordinated change.
+- **A query filename's code must match a registered `LangSpec::code`, or the binary fails to build the ruleset** — both for embedded queries and for `--rules-dir` repo-local ones. This is deliberate (fail fast on a typo) rather than silently dropping the file.
+- **`--list-rules`'s catalog-building text scan skips `;` comments and `"..."` string literals, nothing else.** `rules.rs::primary_capture_in` recovers a pattern's rule ID by scanning the raw source slice from one pattern's start byte to the *next* pattern's start byte for the last `@word`-shaped mention. Two confirmed bugs from this, both fixed with regression tests in `rules.rs`: a trailing comment reading "isn't @activity/@workflow decorated" got its `@workflow` mistaken for the *preceding* pattern's rule ID (misreported `os_popen_usage` as `workflow`); a `(#not-match? ... "@validate\\(")` regex argument got its `@validate` mistaken the same way (misreported `missing_route_validation` as `validate`). Both are skipped now — but nothing else is, so a future `@word`-shaped mention anywhere else non-obvious could reproduce this. If `--list-rules` ever shows a rule ID that doesn't match the capture you wrote, check here first.
+
+## Conventions when editing queries
+
+- Prefer declarative predicates (`#eq?`, `#match?`, `#not-match?`) over broad structural matches.
+- Capture names are the rule ID surfaced to users — make them descriptive (`hardcoded_provider_credentials`, not `bad1`).
+- Keep one logical rule per capture name; combine predicates rather than duplicating patterns.
+- Terraform rules are illustrative examples of naming/convention/security checks (e.g. a placeholder `acme-` bucket prefix, `-role`/`-sg` suffixes) — swap them for your own org's conventions rather than assuming they apply as-is.
+
+## Credits
+
+This crate's Rust architecture (parallel `ignore`+`rayon` scanning,
+git-ignore awareness, embedded-grammar-per-language design, the `_`-prefix
+capture convention) is built on and adapted from
+[tree-grepper](https://github.com/BrianHicks/tree-grepper) (archived) by
+Brian Hicks — it is the source and foundation for most of `src/`'s shape.
+Note tree-grepper is Hippocratic-licensed, not standard OSS; see the
+"Credits"/"License" sections in [`README.md`](README.md).
+
+## References
+
+- [`README.md`](README.md) — setup, pre-commit quickstart, repo-local rules, and credits/license.
+- [`queries/README.md`](queries/README.md) — rule conventions.
+- [Tree-sitter query syntax](https://tree-sitter.github.io/tree-sitter/using-parsers/queries/)
+- [tree-sitter-python grammar](https://github.com/tree-sitter/tree-sitter-python)
+- [tree-sitter-hcl grammar](https://github.com/tree-sitter-grammars/tree-sitter-hcl)