Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
12 changes: 11 additions & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
163 changes: 152 additions & 11 deletions hooks/enforce-rules.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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() {
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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))}"
Expand Down Expand Up @@ -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[@]}
Expand Down Expand Up @@ -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[@]}"
;;
Expand Down
66 changes: 66 additions & 0 deletions tests/test-hooks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading