From 7d38801ab78a8ebe4da90e970880db2593caee0c Mon Sep 17 00:00:00 2001 From: "developerz-ai[bot]" <286432749+developerz-ai[bot]@users.noreply.github.com> Date: Tue, 10 Nov 2026 02:48:37 +0000 Subject: [PATCH] docs: document gate ruff/mypy sources and fix the pre-commit hook Record where the gate's ruff and mypy versions come from, and make the contributor instructions match the gate. CI installs the project with `uv pip install -e ".[all]"` (.github/workflows/ci.yml:42,77,138), which ignores uv.lock, so CI resolves the newest ruff/mypy allowed by pyproject's dev extra (`ruff>=0.16.1,<0.17`, `mypy>=2.4.1,<2.5`); local `uv sync`/`uv run` resolve uv.lock's ruff 0.16.1 and mypy 2.4.1. CLAUDE.md and .claude/skills/verify-change/SKILL.md now say so, and that requirements.txt is not a gate input. CONTRIBUTING.md prescribed `mypy src/` while the gate runs `mypy .`, and prescribed the writing `ruff format .`; both now match bin/check. The pre-commit hook installed by scripts/setup-hooks.sh auto-fixed staged files and always exited 0; it now runs bin/check and propagates its exit status. Guards: tests/test_gate_documentation.py, tests/test_pre_commit_hook.py. Planned by the coordinator bot [bot]. Dz-Task-Id: tsk_d0c472512e73169961dbaff772b39f5e --- .claude/skills/verify-change/SKILL.md | 12 ++ CLAUDE.md | 12 +- CONTRIBUTING.md | 23 ++-- scripts/hooks/pre-commit | 36 ++---- scripts/setup-hooks.sh | 5 +- tests/test_gate_documentation.py | 167 ++++++++++++++++++++++++++ tests/test_pre_commit_hook.py | 145 ++++++++++++++++++++++ 7 files changed, 363 insertions(+), 37 deletions(-) create mode 100644 tests/test_gate_documentation.py create mode 100644 tests/test_pre_commit_hook.py diff --git a/.claude/skills/verify-change/SKILL.md b/.claude/skills/verify-change/SKILL.md index c2f8d82e..61d7eeb6 100644 --- a/.claude/skills/verify-change/SKILL.md +++ b/.claude/skills/verify-change/SKILL.md @@ -57,6 +57,18 @@ Use Python 3.14 and install all extras before proving a change: `uv sync --all-extras --python 3.14` (also performed by `bin/setup`). CI selects Python 3.14 and installs the editable package with `uv pip install -e ".[all]"`. +The two install paths do not resolve the same tool versions. CI's +`uv pip install -e ".[all]"` does not read `uv.lock`, so CI runs the newest +release inside pyproject's dev-extra ranges — `ruff>=0.16.1,<0.17` and +`mypy>=2.4.1,<2.5`. Local `uv sync --all-extras` and `uv run` do read `uv.lock`, +so they run the locked ruff 0.16.1 and mypy 2.4.1. A green local gate is +evidence for the locked versions only — it is not a guarantee that CI will pass. + +`requirements.txt` is a committed `uv pip compile` output of `pyproject.toml`, so it floats to the newest in-range releases (fastapi 0.149.0 against the lock's 0.139.2, pydantic 2.14.1 against 2.13.4); only claude-agent-sdk, ruff and mypy are held at `uv.lock`'s resolution, and it is not a gate input. + +The pre-commit hook installed by `scripts/setup-hooks.sh` runs `bin/check` and +propagates its exit status: a red gate blocks the commit. + | CI job | Local equivalent in `bin/check` | |--------|--------------------------------| | Lint | `uv run ruff check .`, `uv run ruff format --check .`, and `uv run mypy .` retain CI's whole-tree scope. | diff --git a/CLAUDE.md b/CLAUDE.md index 1f69b407..670df1a0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,9 +49,19 @@ Use `pyproject.toml` as dependency/tool configuration authority rather than dupl | `uv run pytest tests/` | Scoped tests when assigned; use the repository markers and fixtures. | | `python verify_docs_links.py` | Read-only repository Markdown path/anchor check; separate from `bin/check`. | | `uv sync --all-extras` | **Writes:** development dependency installation, not verification. | -| `./scripts/setup-hooks.sh` | **Writes:** installs development pre-commit hooks. | +| `./scripts/setup-hooks.sh` | **Writes:** installs the development pre-commit hook; the installed hook runs the gate (`bin/check`) and propagates its exit status. | | `uv run claudetm --help` | CLI smoke check; `doctor` and `status` may fail without credentials/state and are tolerated probes in `bin/check`. | +### Where the gate's tools come from + +CI installs the project with `uv pip install -e ".[all]"`, and that install path does not read +`uv.lock`: CI runs the newest release inside pyproject's dev-extra ranges — `ruff>=0.16.1,<0.17` +and `mypy>=2.4.1,<2.5`. Local `uv sync --all-extras` and `uv run` do read `uv.lock`, so they run +the locked ruff 0.16.1 and mypy 2.4.1. A green local `bin/check` is therefore evidence for the +locked versions only; it is not proof that CI is green. + +`requirements.txt` is a committed `uv pip compile` output of `pyproject.toml`, so it floats to the newest in-range releases (fastapi 0.149.0 against the lock's 0.139.2, pydantic 2.14.1 against 2.13.4); only claude-agent-sdk, ruff and mypy are held at `uv.lock`'s resolution, and it is not a gate input. + Follow the applicable skill before verification: `.claude/skills/verify-change/SKILL.md`, `.claude/skills/docs-links/SKILL.md` or `.claude/skills/local-install/SKILL.md`. Run the narrow reproducer first and the full gate once at the end; never weaken a test/type/lint guard diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3f4c424..5dd086e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,15 +35,18 @@ Thank you for your interest in contributing to Claude Task Master! This document ```bash # Run all tests -uv run pytest +uv run pytest tests/ --timeout=120 # Run specific test file -uv run pytest tests/core/test_agent.py +uv run pytest tests/core/test_agent_query.py --timeout=120 # Run with coverage report -uv run pytest --cov=claude_task_master --cov-report=html +uv run pytest tests/ --cov=claude_task_master --cov-report=html --timeout=120 ``` +pytest's addopts default to a 2-second timeout, so every command above +overrides it with `--timeout=120` — the value the gate (`bin/check`) uses. + ### Code Quality We use several tools to maintain code quality: @@ -52,16 +55,16 @@ We use several tools to maintain code quality: # Linting uv run ruff check . -# Formatting -uv run ruff format . +# Formatting (check only — it never rewrites files) +uv run ruff format --check . -# Type checking -uv run mypy src/ +# Type checking (the whole tree: src, tests and scripts) +uv run mypy . ``` -Run all checks before submitting a PR: +Run all checks before submitting a PR — this is the lint, type-check and test step of the gate; `bin/check` also runs pytest with coverage and two workers, builds the package and runs the CLI smoke probes: ```bash -uv run ruff check . && uv run ruff format --check . && uv run mypy src/ && uv run pytest +uv run ruff check . && uv run ruff format --check . && uv run mypy . && uv run pytest tests/ --timeout=120 ``` ### Code Style Guidelines @@ -104,7 +107,7 @@ Types: 3. **Run all checks**: ```bash - uv run ruff check . && uv run ruff format . && uv run mypy src/ && uv run pytest + uv run ruff check . && uv run ruff format --check . && uv run mypy . && uv run pytest tests/ --timeout=120 ``` 4. **Push and create PR**: diff --git a/scripts/hooks/pre-commit b/scripts/hooks/pre-commit index ed6d793b..abb702d8 100755 --- a/scripts/hooks/pre-commit +++ b/scripts/hooks/pre-commit @@ -1,29 +1,17 @@ #!/usr/bin/env bash -# Pre-commit hook to run lint and fix issues automatically +# Pre-commit gate — runs the SAME `bin/check` CI runs, so a commit that would +# fail CI fails here first. # Installed by: scripts/setup-hooks.sh # -# This hook auto-fixes lint/format issues without failing the commit. -# It silently fixes what it can and lets the commit proceed. +# The gate decides: the hook neither repairs the tree behind the committer's +# back nor reports success when the gate failed. The gate's exit status +# becomes the hook's, so a red gate blocks the commit. -# Get the staged Python files -STAGED_PY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$' || true) +set -euo pipefail -if [ -z "$STAGED_PY_FILES" ]; then - exit 0 -fi - -# Run ruff check with fix on staged files (ignore errors) -uv run ruff check --fix $STAGED_PY_FILES 2>/dev/null || true - -# Run ruff format on staged files (ignore errors) -uv run ruff format $STAGED_PY_FILES 2>/dev/null || true - -# Re-add the fixed files to staging -for file in $STAGED_PY_FILES; do - if [ -f "$file" ]; then - git add "$file" - fi -done - -# Always succeed - let the commit proceed -exit 0 +repo_root="$(git rev-parse --show-toplevel)" || { + echo "pre-commit: cannot locate the repository root" >&2 + exit 1 +} +cd "$repo_root" +exec "$repo_root/bin/check" diff --git a/scripts/setup-hooks.sh b/scripts/setup-hooks.sh index 55fe2e03..93b2c186 100755 --- a/scripts/setup-hooks.sh +++ b/scripts/setup-hooks.sh @@ -18,9 +18,10 @@ mkdir -p "$HOOKS_DIR" if [ -f "$SOURCE_HOOKS_DIR/pre-commit" ]; then cp "$SOURCE_HOOKS_DIR/pre-commit" "$HOOKS_DIR/pre-commit" chmod +x "$HOOKS_DIR/pre-commit" - echo " Installed: pre-commit (runs lint and fixes issues)" + echo " Installed: pre-commit (runs the full gate: bin/check)" fi echo "" echo "Git hooks installed successfully!" -echo "The pre-commit hook will automatically run lint and fix issues on staged Python files." +echo "The pre-commit hook runs the full gate (bin/check) and blocks the commit when it fails." +echo "It runs the same gate as .githooks/pre-commit (git config core.hooksPath .githooks)." diff --git a/tests/test_gate_documentation.py b/tests/test_gate_documentation.py new file mode 100644 index 00000000..f0bffe20 --- /dev/null +++ b/tests/test_gate_documentation.py @@ -0,0 +1,167 @@ +"""Guard: the gate documentation must state where the gate's tools come from. + +CI installs the project with `uv pip install -e ".[all]"`, an install path that does +not read `uv.lock`, so CI resolves the newest ruff and mypy release inside +pyproject's dev-extra ranges while a local `uv sync`/`uv run` resolves the versions +`uv.lock` pins. A green local gate is therefore not evidence about CI, and the docs +have to say so. This guard reads committed files only and derives its expectations +from pyproject.toml and uv.lock, so a bumped range or a re-locked version fails the +test until the documentation is updated. +""" + +from __future__ import annotations + +import re +import tomllib +from pathlib import Path + +import pytest +from packaging.requirements import InvalidRequirement, Requirement +from packaging.specifiers import SpecifierSet + +_ROOT = Path(__file__).resolve().parents[1] +_TOOLS = ("ruff", "mypy") + +_CLAUDE_MD = _ROOT / "CLAUDE.md" +_SKILL_MD = _ROOT / ".claude/skills/verify-change/SKILL.md" +_CONTRIBUTING_MD = _ROOT / "CONTRIBUTING.md" + +_CI_INSTALL = 'uv pip install -e ".[all]"' + +# A version specifier is built from these characters; the scan for the range a doc +# attaches to a tool name stops at the first character outside the set. +_SPECIFIER_CHARS = set("<>=!~,.*0123456789") + +# Each doc and the caveat it keeps about a local pass, quoted verbatim from that doc. +_DOC_CAVEATS = [ + (_CLAUDE_MD, "not proof that CI is green"), + (_SKILL_MD, "not a guarantee that CI will pass"), +] + + +def _squash(text: str) -> str: + """Drop every whitespace character: a doc may wrap one phrase over lines.""" + return "".join(text.split()) + + +def _declared(tool: str) -> Requirement: + """The single requirement pyproject's dev extra declares for ``tool``.""" + project = tomllib.loads((_ROOT / "pyproject.toml").read_text())["project"] + dev = project["optional-dependencies"]["dev"] + matches = [r for r in map(Requirement, dev) if r.name == tool] + assert len(matches) == 1, f"Declare {tool} in the dev extra exactly once" + return matches[0] + + +def _locked_version(tool: str) -> str: + """The version uv.lock resolves for ``tool``.""" + lock = tomllib.loads((_ROOT / "uv.lock").read_text()) + resolutions = [p for p in lock["package"] if p["name"] == tool] + assert len(resolutions) == 1, f"uv.lock must resolve {tool} exactly once" + return str(resolutions[0]["version"]) + + +def _states_range(text: str, tool: str, expected: SpecifierSet) -> bool: + """Whether ``text`` states ``tool`` with a specifier set equal to ``expected``.""" + squashed = _squash(text) + for match in re.finditer(re.escape(tool), squashed): + tail = squashed[match.end() :] + end = 0 + while end < len(tail) and tail[end] in _SPECIFIER_CHARS: + end += 1 + candidate = tail[:end] + if not candidate: + continue + try: + parsed = Requirement(f"{tool}{candidate}") + except InvalidRequirement: + continue + if parsed.specifier == expected: + return True + return False + + +def _has_line_with(text: str, *needles: str) -> bool: + """Whether one line of ``text`` holds every needle once whitespace is dropped.""" + for line in text.splitlines(): + squashed = _squash(line) + if all(_squash(needle) in squashed for needle in needles): + return True + return False + + +@pytest.mark.parametrize("tool", _TOOLS) +@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name) +def test_doc_names_the_declared_range(tool: str, doc: Path) -> None: + """The doc must state the range pyproject declares, not a stale copy of it.""" + declared = _declared(tool) + assert _states_range(doc.read_text(), tool, declared.specifier), ( + f"{doc.name} must state the {tool} range pyproject declares: {declared}" + ) + + +@pytest.mark.parametrize("tool", _TOOLS) +@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name) +def test_doc_names_the_locked_version(tool: str, doc: Path) -> None: + """The doc must state the version uv.lock pins, next to the tool name.""" + version = _locked_version(tool) + assert f"{tool}{version}" in _squash(doc.read_text()), ( + f"{doc.name} must state that {tool} {version} is the version uv.lock pins" + ) + + +@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name) +def test_doc_names_the_ci_install_source(doc: Path) -> None: + """The doc must name CI's install command and the lock it bypasses.""" + text = doc.read_text() + assert _squash(_CI_INSTALL) in _squash(text), ( + f"{doc.name} must name CI's install command {_CI_INSTALL}" + ) + assert "uv.lock" in _squash(text), f"{doc.name} must name uv.lock" + + +@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name) +def test_doc_says_requirements_txt_is_not_a_gate_input(doc: Path) -> None: + """The compiled artifact must be declared out of the gate's way.""" + assert _has_line_with(doc.read_text(), "requirements.txt", "not a gate input"), ( + f"{doc.name} must have a line stating requirements.txt is not a gate input" + ) + + +@pytest.mark.parametrize(("doc", "caveat"), _DOC_CAVEATS, ids=["claude", "skill"]) +def test_doc_keeps_the_local_pass_caveat(doc: Path, caveat: str) -> None: + """A local pass is not evidence about CI; the doc has to say so.""" + assert _squash(caveat) in _squash(doc.read_text()), ( + f"{doc.name} must keep the caveat '{caveat}'" + ) + + +@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name) +def test_doc_states_the_hook_runs_the_gate(doc: Path) -> None: + """The installed pre-commit hook runs the gate; the doc must say so.""" + assert _has_line_with(doc.read_text(), "setup-hooks.sh", "bin/check"), ( + f"{doc.name} must state that the hook installed by scripts/setup-hooks.sh runs bin/check" + ) + + +def test_contributing_prescribes_the_gate_scope() -> None: + """CONTRIBUTING.md must prescribe the checks the gate runs, not narrower ones.""" + squashed = _squash(_CONTRIBUTING_MD.read_text()) + assert _squash("uv run mypy .") in squashed, "CONTRIBUTING.md must prescribe `uv run mypy .`" + assert _squash("mypy src/") not in squashed, "CONTRIBUTING.md must not narrow mypy to src/" + assert _squash("uv run ruff format --check .") in squashed, ( + "CONTRIBUTING.md must prescribe `uv run ruff format --check .`" + ) + assert _squash("uv run ruff format .") not in squashed, ( + "CONTRIBUTING.md must not prescribe the rewriting formatter" + ) + + +def test_contributing_test_commands_use_the_gate_timeout() -> None: + """Every prescribed test command must carry the gate's pytest timeout.""" + lines = [line for line in _CONTRIBUTING_MD.read_text().splitlines() if "uv run pytest" in line] + assert lines, "CONTRIBUTING.md must prescribe the test command" + for line in lines: + assert "--timeout=120" in line, ( + f"CONTRIBUTING.md test command lacks the gate's --timeout=120: {line.strip()}" + ) diff --git a/tests/test_pre_commit_hook.py b/tests/test_pre_commit_hook.py new file mode 100644 index 00000000..872ee58b --- /dev/null +++ b/tests/test_pre_commit_hook.py @@ -0,0 +1,145 @@ +"""Guard: the pre-commit hook runs the gate and propagates its failure. + +A hook that repairs the tree behind the committer's back, or that swallows a +red gate, lets a commit CI would reject reach the branch. This guard copies the +hook into a throwaway git repository whose `bin/check` is a stub, runs it, and +asserts that the stub ran and that its exit status reached the caller. It also +runs the hook outside any git repository, where the hook must refuse loudly +instead of guessing a root. It reads committed files only and never runs the +real gate. +""" + +from __future__ import annotations + +import os +import shutil +import subprocess +from pathlib import Path + +import pytest + +_ROOT = Path(__file__).resolve().parents[1] +_HOOK = _ROOT / "scripts" / "hooks" / "pre-commit" +_SETUP = _ROOT / "scripts" / "setup-hooks.sh" + +# The hook must not repair the tree for the committer, and it must never report +# success when the gate failed. +_FORBIDDEN = ("--fix", "git add", "exit 0") + +# The promise the old hook made; the new one runs the gate instead. +_OLD_PROMISE = "runs lint and fixes issues" + +# Git exports these when it runs a hook, so the hook under test must find the +# repository by itself. The variants below cover the environments git uses. +_HOOK_ENV_DROP = ("GIT_DIR", "GIT_WORK_TREE") +_GIT_DIR_VARIANTS = (None, "absolute", "relative") + +# A distinctive status, so a swallowed or rewritten exit code cannot pass. +_STUB_EXIT_CODE = 3 + +# What the hook must say when it cannot find a repository to gate. +_REFUSAL_MESSAGE = "pre-commit: cannot locate the repository root" + +requires_git = pytest.mark.skipif(shutil.which("git") is None, reason="git is not installed") + + +def test_hook_source_carries_no_auto_fix_and_no_forced_success() -> None: + """The hook source must run the gate and nothing that hides a failure.""" + text = _HOOK.read_text() + for forbidden in _FORBIDDEN: + assert forbidden not in text, f"the pre-commit hook must not contain {forbidden!r}" + assert "bin/check" in text, "the pre-commit hook must run bin/check" + + +def test_setup_message_describes_the_gate() -> None: + """The install script must tell contributors the hook runs the gate.""" + text = _SETUP.read_text() + assert _OLD_PROMISE not in text, "setup-hooks.sh must not promise an auto-fix" + assert "bin/check" in text, "setup-hooks.sh must name the gate the hook runs" + + +@requires_git +@pytest.mark.parametrize("git_dir", _GIT_DIR_VARIANTS) +def test_hook_runs_gate_and_propagates_failure(tmp_path: Path, git_dir: str | None) -> None: + """The hook must run bin/check in the repository root and return its status.""" + repo = tmp_path / "repo" + repo.mkdir() + init = subprocess.run( + ["git", "init", "--quiet", str(repo)], + capture_output=True, + text=True, + timeout=30, + check=False, + ) + assert init.returncode == 0, init.stderr + + marker = repo / "gate-ran" + stub = repo / "bin" / "check" + stub.parent.mkdir() + stub.write_text(f"#!/usr/bin/env bash\ntouch {marker}\nexit {_STUB_EXIT_CODE}\n") + stub.chmod(0o755) + + hook = repo / ".git" / "hooks" / "pre-commit" + hook.write_text(_HOOK.read_text()) + hook.chmod(0o755) + + env = {k: v for k, v in os.environ.items() if k not in _HOOK_ENV_DROP} + if git_dir == "absolute": + env["GIT_DIR"] = str(repo / ".git") + elif git_dir == "relative": + env["GIT_DIR"] = ".git" + result = subprocess.run( + [str(hook)], + cwd=repo, + env=env, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + + assert marker.exists(), f"the hook did not run bin/check: {result.stderr}" + detail = f"hook returned {result.returncode}, gate stderr: {result.stderr}" + assert result.returncode == _STUB_EXIT_CODE, detail + + +@requires_git +def test_hook_refuses_to_run_outside_a_repository(tmp_path: Path) -> None: + """Outside a repository the hook must fail loudly, not gate the wrong tree.""" + outside = tmp_path / "not-a-repo" + outside.mkdir() + + hook = tmp_path / "pre-commit" + hook.write_text(_HOOK.read_text()) + hook.chmod(0o755) + + env = {k: v for k, v in os.environ.items() if k not in _HOOK_ENV_DROP} + # Keep discovery from walking above the temporary tree, so the case holds + # even where the temporary directory happens to sit inside a checkout. + env["GIT_CEILING_DIRECTORIES"] = str(tmp_path) + + probe = subprocess.run( + ["git", "rev-parse", "--show-toplevel"], + cwd=outside, + env=env, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + if probe.returncode == 0: + pytest.skip(f"the temporary directory is inside a repository: {probe.stdout.strip()}") + + result = subprocess.run( + [str(hook)], + cwd=outside, + env=env, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + + detail = f"hook returned {result.returncode}, hook stderr: {result.stderr}" + assert result.returncode == 1, detail + assert _REFUSAL_MESSAGE in result.stderr, detail