.pre-commit-config.yaml

---
# Single source of tooling is uv; local hooks run tools through `uv run`
# so versions match the locked environment.
#   uv run pre-commit run --all-files       # apply to all files
#   uv run pre-commit autoupdate --freeze   # update pinned hook revs
minimum_pre_commit_version: "3.5.0"
default_install_hook_types: [pre-commit, commit-msg, pre-push]

# reference/ is the frozen Perl oracle (upstream ferm plus its golden
# files), tests/golden/expected/ holds byte-exact captures of the
# oracle's stderr (trailing whitespace is significant) and
# tests/corpus/configs/ carries third-party wild configs verbatim
# and docs/man/ holds generated troff that must stay byte-exact for
# the freshness gate: no hook may rewrite, lint, or spell-check them.
exclude: ^(reference/|tests/golden/expected/|tests/corpus/configs/|docs/man/)

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
    hooks:
      - id: check-ast
      - id: check-case-conflict
      - id: check-docstring-first
      - id: check-executables-have-shebangs
      - id: check-shebang-scripts-are-executable
      - id: check-yaml
      - id: check-toml
      - id: check-merge-conflict
      - id: check-added-large-files
        # Well above the largest tracked file (uv.lock), tight enough
        # to flag binary blobs or accidental dataset commits.
        args: [--maxkb=600]
      - id: detect-private-key
      - id: debug-statements
      - id: end-of-file-fixer
      - id: fix-byte-order-marker
      - id: mixed-line-ending
        args: [--fix=lf]
      - id: trailing-whitespace
        args: [--markdown-linebreak-ext=md]
      # Only "test_"-prefixed files inside tests/ may define test
      # classes; the golden-harness machinery and conftest are helpers.
      - id: name-tests-test
        args: ["--pytest-test-first"]
        exclude: |
          (?x)^tests/(
            conftest\.py$|
            .*__init__\.py$|
            _(oracle|netns)\.py$|
            unit/_(cli|parse|packaging|plan|nftrule)\.py$|
            golden/(conftest|runner|normalize|sortpl)\.py$|
            corpus/canon\.py$|
            e2e/lockout/driver\.py$|
            e2e/nft/driver\.py$|
            e2e/readback/driver\.py$|
            e2e/docker_coexist/driver\.py$|
            e2e/etckeeper/driver\.py$|
            e2e/datapath/(driver|netns|oracle|scenarios)\.py$|
            e2e/iptables_nft/normalize\.py$|
            property/oracle\.py$|
            property/differential_cli\.py$|
            conformance/nft/tdotparser\.py$
          )

  # Quick regex-based gotchas the linters cannot catch: Mock method
  # typos silently pass at runtime; `# type: ignore` without a code
  # suppresses every error; U+FFFD usually means encoding loss.
  - repo: https://github.com/pre-commit/pygrep-hooks
    rev: 3a6eb0fadf60b3cccfd80bad9dbb6fae7e47b316  # frozen: v1.10.0
    hooks:
      - id: python-check-mock-methods
      - id: python-no-log-warn
      - id: python-no-eval
      - id: text-unicode-replacement-char
      - id: python-check-blanket-type-ignore

  # Spelling for code, comments, and docs. The netfilter vocabulary
  # (iif, rsource, ect) is allow-listed under [tool.codespell].
  - repo: https://github.com/codespell-project/codespell
    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
    hooks:
      - id: codespell

  - repo: https://github.com/abravalheri/validate-pyproject
    rev: 4b2e70d08cb2ccd26d1fba73588de41c7a5d50b7  # frozen: v0.25
    hooks:
      - id: validate-pyproject
        additional_dependencies: ["validate-pyproject-schema-store[all]"]

  - repo: local
    hooks:
      - id: ruff-check
        name: ruff check (project venv)
        entry: uv
        language: system
        types: [python]
        args: ["run", "ruff", "check", "--fix", "--show-fixes"]

      - id: ruff-format
        name: ruff format (project venv)
        entry: uv
        language: system
        types: [python]
        args: ["run", "ruff", "format"]

      - id: mypy
        name: mypy (project venv)
        entry: uv
        language: system
        types: [python]
        pass_filenames: false
        args: ["run", "mypy"]

      - id: pyright
        name: pyright (project venv)
        entry: uv
        language: system
        types: [python]
        pass_filenames: false
        args: ["run", "pyright"]

      - id: vulture
        name: vulture (dead-code detection)
        entry: uv
        language: system
        types: [python]
        pass_filenames: false
        args: ["run", "vulture"]

      # deptry walks the AST and compares actual imports against
      # pyproject dependencies: catches a runtime import that only
      # works because a dev tool pulls it transitively, and stale pins
      # no code imports.
      - id: deptry
        name: deptry (project venv)
        entry: uv
        language: system
        types: [python]
        pass_filenames: false
        args: ["run", "deptry", "."]

      # Architectural contracts ([tool.importlinter]): the compiler
      # core must not grow an import of the backend, and the bottom-up
      # layering of the port stays as measured.
      - id: import-linter
        name: import-linter (project venv)
        entry: uv
        language: system
        types: [python]
        files: ^src/
        pass_filenames: false
        args: ["run", "lint-imports"]

      - id: bandit
        name: bandit (project venv)
        entry: uv
        language: system
        files: ^src/.*\.py$
        pass_filenames: false
        args: ["run", "bandit", "-q", "-c", "pyproject.toml", "-r", "src"]

      # A forgotten `uv lock` after editing pyproject.toml is a common
      # cause of CI-only failures.
      - id: uv-lock-check
        name: uv lock --check
        entry: uv
        language: system
        pass_filenames: false
        files: ^(pyproject\.toml|uv\.lock)$
        args: ["lock", "--check"]

      - id: shellcheck-completions
        name: shellcheck (generated bash completions)
        entry: shellcheck
        language: system
        files: ^packaging/completions/.*\.bash$

      # Fast gate at push time: the unit+golden suite against the port
      # (parallel under xdist, ~14s).  Stops a red push before it reaches
      # CI; the heavier preflight (matrix/coverage/fuzz/build) stays a
      # deliberate `nox -s preflight`.  Runs once per push, not per file.
      - id: tests
        name: pytest (port suite, pre-push)
        entry: uv
        language: system
        stages: [pre-push]
        pass_filenames: false
        always_run: true
        args: ["run", "nox", "-s", "tests"]

  # Conventional Commits gate on commit subjects, enforced at write
  # time so a malformed message never lands.
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: 3db014c16a9d31997ab8c07a4d61fcce936c8f0d  # frozen: v4.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args:
          - feat
          - fix
          - docs
          - style
          - refactor
          - perf
          - test
          - build
          - ci
          - chore
          - revert

  # Secret scanning beyond detect-private-key (API tokens, JWT, URLs
  # with embedded credentials). .secrets.baseline records accepted
  # findings; regenerate after intentional fixture edits with:
  #   uv run detect-secrets scan > .secrets.baseline
  - repo: https://github.com/Yelp/detect-secrets
    rev: 68e8b45440415753fff70a312ece8da92ba85b4a  # frozen: v1.5.0
    hooks:
      - id: detect-secrets
        args: ["--baseline", ".secrets.baseline"]
        # pre-commit autoupdate --freeze writes 40-char SHAs that the
        # entropy detector flags; uv.lock is hash soup by design, and the
        # corpus provenance manifest pins one 40-hex commit per config.
        exclude: |
          (?x)(
            ^uv\.lock$|
            ^\.secrets\.baseline$|
            ^\.pre-commit-config\.yaml$|
            ^tests/corpus/provenance\.yaml$
          )