From a249936a894c6ff3d81df193cf7b15dd0f0a0538 Mon Sep 17 00:00:00 2001 From: Anwai Archit Date: Sat, 25 Jul 2026 16:40:30 +0200 Subject: [PATCH] Scope the linter rule to Python and guard the formatters The rule made flake8 the only linter for every language, so it forbade shellcheck and left a Go or Rust repository with no allowed linter. It now covers the style linters and the formatters of Python only. The hand-fix mandate applies to the code you add. The read-only forms stay allowed, because `black --check` and `isort --check-only` never write a file. The write forms stay forbidden, and hooks/enforce-rules.sh now denies black, isort, `ruff format`, and `ruff check --fix`. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 6 +- docs/design.md | 12 ++- hooks/enforce-rules.sh | 163 ++++++++++++++++++++++++++++++++++++++--- tests/test-hooks.sh | 66 +++++++++++++++++ 4 files changed, 233 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b4a1e76..0062667 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,8 +26,10 @@ If an instruction of the repository disagrees with a rule below, the rule below ## Code quality -- Always run `flake8 --max-line-length=120` on any code you add before considering the task done. -- Use flake8 as the only linter. Do not run ruff, black, isort, or any other linter or formatter. Do not run them even to check, because some reformat files on a check run. Fix every issue by hand. +- Always run `flake8 --max-line-length=120` on the Python code you add, before you consider the task done. Fix by hand every issue that it reports in that code. Leave the issues in code that you did not touch. Leave an issue in an `__init__.py` file, because you must not edit that file. Leave an issue that the formatter of the repository produces, such as E203 next to a slice colon under black. +- Use flake8 as the only Python linter. Never let another tool rewrite a file. Never run `black`, `isort`, `ruff format`, or `ruff check --fix`. Never run a wrapper that calls them, such as `make lint` or `pre-commit run`. You can run the read-only forms, because `black --check`, `ruff check`, and `isort --check-only` never write a file. Use such a run to see what CI reports, then fix the code by hand. +- These two rules cover Python only. They do not cover the linter of another language, a type checker, a manifest validator, or a test runner. Run what the repository requires for the language that you changed, such as `shellcheck` for its shell scripts. +- If flake8 is absent, report this and stop. Do not install it, and do not put another tool in its place. If the user asks for a command that these rules forbid, run that command. - Never modify `__init__.py` files unless explicitly asked to. - When adding a `# noqa` comment, never include the error type: write `# noqa`, not `# noqa: E402`. diff --git a/docs/design.md b/docs/design.md index a6815c0..4cb4018 100644 --- a/docs/design.md +++ b/docs/design.md @@ -82,11 +82,21 @@ in the attached form `-mpip` and inside a bundle of short options such as `-um p hook does not cover remain instructions. A conflicting repository rule can still make their result less certain. +The hook also blocks a formatter that rewrites files. It denies `black`, `isort`, `ruff format`, and +`ruff check --fix`. It allows the read-only forms, such as `black --check`, `isort --check-only`, +`ruff check`, and `ruff format --diff`. A read-only flag counts only in an option position, as a +preview flag does, because `black --exclude --check .` still rewrites files. The hook finds these +commands after a runner, after `python -m`, and after `uvx` or `uv tool run`. It does not block a wrapper such as `make lint` or +`pre-commit run`, because it cannot see which tool the wrapper calls. That part of the rule stays an +instruction. The hook blocks these three tools only. A linter for another language, a type checker, +and a manifest validator stay allowed, because `AGENTS.md` restricts the style linters and the +formatters of Python and nothing else. + The hook reads the text of the command, so it has limits. It tokenizes simple shell commands, respects quoted text, ignores heredoc bodies, checks each part of a compound command, and skips assignment and redirection prefixes before finding the executable. It inspects commands inside shell invokers such as `bash -lc "..."` and inside runners such as -`micromamba run -n super ...`. It lists the options that take a value for each runner, so it can +`micromamba run -n super ...`, `uv run ...`, `uv tool run ...`, and `uvx ...`. It lists the options that take a value for each runner, so it can find the nested command. An unknown option that takes a value shifts this position and hides the nested command. Preview flags are checked after resolving a nested command. A `--help` or a `--dry-run` counts only in an option position, so `git commit -m --help` stays a real commit. The diff --git a/hooks/enforce-rules.sh b/hooks/enforce-rules.sh index ae2af3a..f0b11e7 100755 --- a/hooks/enforce-rules.sh +++ b/hooks/enforce-rules.sh @@ -20,6 +20,8 @@ PYTHON_SAFE_PREVIEW=0 PIP_REASON="The environment is managed by the user. Do not install packages with pip." CONDA_REASON="The environment is managed by the user. Do not install packages with conda or micromamba." UV_REASON="The environment is managed by the user. Do not install packages with uv." +FORMATTER_REASON="A formatter rewrites files. Use flake8 and fix every issue by hand. A read-only run\ + such as \`black --check\` is allowed." json_field() { local input=$1 field=$2 @@ -430,16 +432,27 @@ find_python_module() { } inspect_python() { - local pip_args + local module_args find_python_module "$@" [ "$PYTHON_SAFE_PREVIEW" -eq 0 ] || return - [ "$PYTHON_MODULE" = "pip" ] || return + [ -n "$PYTHON_MODULE" ] || return [ "$PYTHON_MODULE_INDEX" -lt "$#" ] || return - pip_args=("${@:$((PYTHON_MODULE_INDEX + 1))}") - find_subcommand pip "${pip_args[@]}" - if ! is_safe_preview pip "${pip_args[@]}" && [ "$SUBCOMMAND" = "install" ]; then - set_decision deny "$PIP_REASON" - fi + module_args=("${@:$((PYTHON_MODULE_INDEX + 1))}") + + case "$PYTHON_MODULE" in + pip) + find_subcommand pip "${module_args[@]}" + if ! is_safe_preview pip "${module_args[@]}" && [ "$SUBCOMMAND" = "install" ]; then + set_decision deny "$PIP_REASON" + fi + ;; + black|isort) + inspect_formatter "$PYTHON_MODULE" "${module_args[@]}" + ;; + ruff) + inspect_ruff "${module_args[@]}" + ;; + esac } option_takes_value() { @@ -463,7 +476,7 @@ option_takes_value() { uv:--directory|uv:--project|uv:--config-file|uv:--color|uv:--python|uv:--python-preference) return 0 ;; - uv:--with|uv:--with-requirements|uv:--extra|uv:--env-file) + uv:--with|uv:--with-requirements|uv:--extra|uv:--env-file|uv:--from) return 0 ;; git-commit:-m|git-commit:--message|git-commit:-F|git-commit:--file|git-commit:--author) @@ -514,10 +527,71 @@ option_takes_value() { conda-upgrade:--channel|conda-upgrade:--file) return 0 ;; + black:-l|black:--line-length|black:-t|black:--target-version|black:--include|black:--exclude) + return 0 + ;; + black:--extend-exclude|black:--force-exclude|black:--stdin-filename|black:-W|black:--workers) + return 0 + ;; + black:--config|black:--required-version) + return 0 + ;; + isort:--sp|isort:--settings-path|isort:--settings-file|isort:--settings|isort:--profile) + return 0 + ;; + isort:-l|isort:--line-length|isort:-w|isort:--line-width|isort:-m|isort:--multi-line) + return 0 + ;; + isort:-p|isort:--project|isort:--src|isort:--src-path|isort:-s|isort:--skip|isort:--skip-glob) + return 0 + ;; + isort:--extend-skip|isort:-o|isort:--thirdparty|isort:--known-first-party) + return 0 + ;; + ruff:--config|ruff-check:--config|ruff-format:--config) + return 0 + ;; + ruff-check:--select|ruff-check:--ignore|ruff-check:--extend-select|ruff-check:--per-file-ignores) + return 0 + ;; + ruff-check:--exclude|ruff-check:--extend-exclude|ruff-check:--output-format|ruff-check:--cache-dir) + return 0 + ;; + ruff-check:--target-version|ruff-check:--line-length|ruff-check:--stdin-filename) + return 0 + ;; + ruff-format:--exclude|ruff-format:--extend-exclude|ruff-format:--cache-dir|ruff-format:--range) + return 0 + ;; + ruff-format:--target-version|ruff-format:--line-length|ruff-format:--stdin-filename) + return 0 + ;; esac return 1 } +# An option counts only in an option position. In `black --exclude --check .` the flag is the value +# of --exclude, so the command still rewrites files. The wanted options are separated by a bar. +has_option() { + local kind=$1 wanted=$2 args count i word + shift 2 + args=("$@") + count=${#args[@]} + + for ((i = 0; i < count; i++)); do + word=${args[$i]} + [ "$word" = "--" ] && return 1 + [[ "$word" = -* ]] || continue + case "|$wanted|" in + *"|$word|"*) + return 0 + ;; + esac + option_takes_value "$kind" "$word" && i=$((i + 1)) + done + return 1 +} + find_subcommand() { local kind=$1 args i count word shift @@ -600,9 +674,16 @@ inspect_uv() { tool) nested=("${args[@]:$((index + 1))}") find_subcommand uv "${nested[@]}" - if ! is_safe_preview uv "${nested[@]}" && [ "$SUBCOMMAND" = "install" ]; then - set_decision deny "$UV_REASON" - fi + is_safe_preview uv "${nested[@]}" && return + case "$SUBCOMMAND" in + install) + set_decision deny "$UV_REASON" + ;; + run) + [ $((SUBCOMMAND_INDEX + 1)) -lt "${#nested[@]}" ] || return + inspect_runner uv "${nested[@]:$((SUBCOMMAND_INDEX + 1))}" + ;; + esac ;; run) inspect_runner uv "${args[@]:$((index + 1))}" @@ -650,6 +731,57 @@ inspect_conda() { esac } +# black and isort rewrite the files they read. Only the read-only forms stay allowed. +inspect_formatter() { + local kind=$1 read_only= + shift + case "$kind" in + black) + read_only="--check|--diff|--version" + ;; + isort) + read_only="--check-only|--check|-c|--diff|-d|--version" + ;; + esac + is_safe_preview "$kind" "$@" && return + has_option "$kind" "$read_only" "$@" && return + set_decision deny "$FORMATTER_REASON" +} + +# `ruff format` writes unless it checks, and `ruff check` writes only with a fix flag. Both +# subcommands default to the current directory, so a bare `ruff format` rewrites the whole tree. +inspect_ruff() { + local args=("$@") nested count index + count=${#args[@]} + find_subcommand ruff "${args[@]}" + index=$SUBCOMMAND_INDEX + [ "$index" -ge 0 ] || return + if [ "$index" -gt 0 ]; then + nested=("${args[@]:0:$index}") + is_safe_preview ruff "${nested[@]}" && return + fi + + nested=() + [ $((index + 1)) -lt "$count" ] && nested=("${args[@]:$((index + 1))}") + + case "$SUBCOMMAND" in + format) + if [ "${#nested[@]}" -gt 0 ]; then + is_safe_preview ruff-format "${nested[@]}" && return + has_option ruff-format "--check|--diff|--version" "${nested[@]}" && return + fi + set_decision deny "$FORMATTER_REASON" + ;; + check) + [ "${#nested[@]}" -gt 0 ] || return + is_safe_preview ruff-check "${nested[@]}" && return + if has_option ruff-check "--fix|--fix-only" "${nested[@]}"; then + set_decision deny "$FORMATTER_REASON" + fi + ;; + esac +} + inspect_shell_invoker() { local args=("$@") count i option count=${#args[@]} @@ -756,6 +888,15 @@ inspect_simple_command() { uv) inspect_uv "${args[@]}" ;; + uvx) + inspect_runner uv "${args[@]}" + ;; + black|isort) + inspect_formatter "$executable" "${args[@]}" + ;; + ruff) + inspect_ruff "${args[@]}" + ;; micromamba|mamba|conda) inspect_conda "${args[@]}" ;; diff --git a/tests/test-hooks.sh b/tests/test-hooks.sh index aff4a56..85f21fe 100755 --- a/tests/test-hooks.sh +++ b/tests/test-hooks.sh @@ -206,6 +206,69 @@ test_runner_commands_are_inspected() { expect_decision "micromamba run -n super flake8 --max-line-length=120 ." allow } +test_formatter_writes_are_denied() { + expect_decision "black ." deny + expect_decision "black src/module.py" deny + expect_decision "isort ." deny + expect_decision "ruff format" deny + expect_decision "ruff format ." deny + expect_decision "ruff check --fix ." deny + expect_decision "ruff check --fix-only ." deny + expect_decision "python -m black ." deny + expect_decision "python -m isort ." deny + expect_decision "python -m ruff format ." deny + expect_decision "/usr/bin/black ." deny + expect_decision "X=1 isort ." deny + expect_decision "micromamba run -n super black ." deny + expect_decision "uv run ruff format ." deny + expect_decision "uvx black ." deny + expect_decision "uvx ruff format ." deny + expect_decision "uvx --from black black ." deny + expect_decision "uv tool run isort ." deny + expect_decision "uv tool run pip install torch" deny + expect_decision "bash -c 'black .'" deny + expect_decision "du -h && black ." deny + expect_decision "black ." deny codex +} + +test_read_only_formatter_runs_are_allowed() { + expect_decision "black --check ." allow + expect_decision "black --diff ." allow + expect_decision "isort --check-only ." allow + expect_decision "isort -c ." allow + expect_decision "isort --diff ." allow + expect_decision "ruff check" allow + expect_decision "ruff check ." allow + expect_decision "ruff check --statistics ." allow + expect_decision "ruff format --check ." allow + expect_decision "ruff format --diff ." allow + expect_decision "ruff rule E501" allow + expect_decision "black --help" allow + expect_decision "black --version" allow + expect_decision "ruff --version" allow + expect_decision "black" allow + expect_decision "isort" allow + expect_decision "ruff" allow + expect_decision "ruff format --help" allow + expect_decision "micromamba run -n super black --check ." allow + expect_decision "uvx black --check ." allow + expect_decision "uv tool run ruff format --check ." allow + expect_decision "uv tool install ruff --help" allow + expect_decision "uvx" allow + expect_decision "uv tool run" allow + expect_decision "flake8 --max-line-length=120 ." allow + expect_decision "echo black ." allow +} + +# A read-only flag counts only in an option position. `--check` is the value of `--exclude` here. +test_formatter_flags_only_count_as_options() { + expect_decision "black --exclude --check ." deny + expect_decision "black --line-length --diff ." deny + expect_decision "isort --profile --check-only ." deny + expect_decision "ruff format --config --check ." deny + expect_decision "ruff check --select --fix ." allow +} + test_shell_invoker_is_inspected() { expect_decision "bash -c 'pip install torch'" deny expect_decision "sh -c \"micromamba install numpy\"" deny @@ -469,6 +532,9 @@ main() { test_heredoc_bodies_are_not_commands test_compound_commands_cannot_hide_a_violation test_runner_commands_are_inspected + test_formatter_writes_are_denied + test_read_only_formatter_runs_are_allowed + test_formatter_flags_only_count_as_options test_shell_invoker_is_inspected test_enforcement_survives_without_jq test_allowed