claude-dev-env 1.78.0 → 1.80.0

package/hooks/blocking/code_rules_paired_test.py

@@ -3,29 +3,48 @@
 The TDD gate ``tdd_enforcer.py`` requires a fresh test file to exist before a
 production module is written, but it judges coverage at file granularity: a
 module whose dedicated test file exercises some public functions while leaving
-one untested still satisfies it. This check closes that gap. When a production
-module has an established paired test suite — a stem-matched ``test_<stem>.py``
-that already exercises at least one of the module's public functions — a public
-function that suite references nowhere is flagged, so the forgotten function
-gets a behavioral test before the partially-covered module lands.
-
-The check stays conservative to keep false positives near zero:
-
-- It runs only on a production module whose stem-matched test file already
-  exists; a module with no dedicated test file is out of scope and left to the
-  file-level TDD gate.
-- It fires only when the suite already covers at least one public function of
-  the same module — the signature of a maintained per-function suite rather than
-  an unrelated or placeholder test file.
-- A public function counts as covered when its name appears in any test file
-  beside the stem-matched one — imported, called, or named — so a function
-  exercised by a differently-named sibling test still counts.
+one untested still satisfies it. This check closes that gap from both write
+orders, so a forgotten function gets a behavioral test before the
+partially-covered module lands.
+
+``check_public_function_missing_paired_test`` fires on the production-module
+write: when a module has an established paired test suite — a stem-matched
+``test_<stem>.py`` that already exercises the module, either by covering at least
+one of its public functions or by referencing one of its private helpers — a
+public function that suite references nowhere is flagged.
+
+``check_test_file_omits_module_public_function`` fires on the stem-matched
+test-file write, covering the reverse order in which the production module is
+written before its test file exists. It resolves the production module the
+written ``test_<stem>.py`` or ``<stem>_test.py`` file pairs with and flags every
+public function the post-edit suite omits, so the gap that the production-side
+check cannot see — because no suite existed when the module was written — is
+caught when the test file lands.
+
+Both checks stay conservative to keep false positives near zero:
+
+- The production-side check runs only on a production module whose stem-matched
+  test file already exists; a module with no dedicated test file is out of scope
+  and left to the file-level TDD gate. The test-side check runs only on a
+  stem-matched test file whose paired production module exists on disk.
+- The production-side check fires only when the suite already exercises the
+  module — covering at least one of its public functions, or referencing one of
+  its private helpers by name — the signature of a maintained per-module suite
+  rather than an unrelated or placeholder test file. A suite that exercises only
+  a private helper while omitting the public surface is the exact shape the
+  private-helper establishment catches. The test-side check fires only when the
+  post-edit suite already covers at least one public function of the paired
+  module.
+- A public function counts as covered when its name appears in any test file in
+  the suite directory — imported, called, or named — so a function exercised by
+  a differently-named sibling test still counts.
 - ``main`` and underscore-prefixed functions are never required to carry a test.
 - Test modules, hook infrastructure, config modules, migrations, workflow
-  registries, and ``__init__`` modules are exempt.
+  registries, and ``__init__`` modules are exempt as production targets.
 """
 
 import ast
+import os
 import sys
 from pathlib import Path
 
@@ -59,6 +78,7 @@ from hooks_constants.paired_test_coverage_constants import (  # noqa: E402
     PYTHON_SOURCE_SUFFIX,
     STEM_TEST_FILENAME_PREFIX,
     STEM_TEST_FILENAME_SUFFIX,
+    TEST_SUITE_OMITS_FUNCTION_GUIDANCE,
     TESTS_DIRECTORY_NAME,
 )
 
@@ -97,6 +117,26 @@ def _public_function_definitions(tree: ast.Module) -> list[tuple[str, int]]:
     return all_definitions
 
 
+def _private_function_names(tree: ast.Module) -> set[str]:
+    """Return the names of module-scope underscore-prefixed function definitions.
+
+    Args:
+        tree: The parsed production module.
+
+    Returns:
+        Each module-scope function name that begins with an underscore - the
+        private helpers a paired test suite reaches when it exercises the
+        module's internals.
+    """
+    all_private_names: set[str] = set()
+    for each_statement in tree.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if each_statement.name.startswith("_"):
+            all_private_names.add(each_statement.name)
+    return all_private_names
+
+
 def _ancestor_tests_directories(start_directory: Path) -> list[Path]:
     """Return each ancestor's ``tests`` directory, nearest ancestor first.
 
@@ -235,7 +275,8 @@ def check_public_function_missing_paired_test(
     """Flag a public function the module's established paired test suite omits.
 
     Runs only on a production module whose stem-matched ``test_<stem>.py`` already
-    exists and already exercises at least one of the module's public functions.
+    exists and already exercises the module — by covering at least one of its
+    public functions, or by referencing one of its private helpers by name.
     Under that established-suite precondition, a public function the suite
     references nowhere is flagged, so the forgotten function gets a behavioral
     test before the partially-covered module lands. ``main`` and
@@ -255,8 +296,9 @@ def check_public_function_missing_paired_test(
     Returns:
         One violation per uncovered public function, capped at the configured
         maximum, scoped to the changed lines unless deferred or unscoped. Empty
-        when the module is exempt, has no dedicated test file, the suite covers
-        no public function, or the content fails to parse.
+        when the module is exempt, has no dedicated test file, the suite neither
+        covers a public function nor references a private helper of the module,
+        or the content fails to parse.
     """
     if _module_is_exempt(file_path):
         return []
@@ -276,7 +318,14 @@ def check_public_function_missing_paired_test(
         for each_name, _each_line in all_public_definitions
         if each_name in all_referenced_identifiers
     )
-    if covered_function_count < MINIMUM_COVERED_PUBLIC_FUNCTIONS:
+    suite_references_private_helper = bool(
+        _private_function_names(tree) & all_referenced_identifiers
+    )
+    suite_is_established = (
+        covered_function_count >= MINIMUM_COVERED_PUBLIC_FUNCTIONS
+        or suite_references_private_helper
+    )
+    if not suite_is_established:
         return []
     all_violations_in_walk_order: list[tuple[range, str]] = []
     for each_name, each_definition_line in all_public_definitions:
@@ -297,3 +346,172 @@ def check_public_function_missing_paired_test(
         defer_scope_to_caller,
     )
 
+
+def _production_stem_from_test_filename(test_filename: str) -> str | None:
+    """Return the production-module stem a stem-matched test filename pairs with.
+
+    Args:
+        test_filename: The basename of the written file.
+
+    Returns:
+        The production stem for a ``test_<stem>.py`` or ``<stem>_test.py`` name,
+        or None when the filename is not stem-matched or its stem is empty.
+    """
+    if test_filename.endswith(STEM_TEST_FILENAME_SUFFIX):
+        production_stem = test_filename[: -len(STEM_TEST_FILENAME_SUFFIX)]
+        return production_stem or None
+    if test_filename.startswith(STEM_TEST_FILENAME_PREFIX) and test_filename.endswith(
+        PYTHON_SOURCE_SUFFIX
+    ):
+        production_stem = test_filename[
+            len(STEM_TEST_FILENAME_PREFIX) : -len(PYTHON_SOURCE_SUFFIX)
+        ]
+        return production_stem or None
+    return None
+
+
+def _paired_production_module_path(
+    test_path: Path, production_stem: str
+) -> Path | None:
+    """Return the production module a stem-matched test file pairs with, or None.
+
+    Mirrors ``_stem_matched_test_path`` in reverse for the two common layouts: a
+    module beside the test file, and a module in the parent of the ``tests``
+    directory that directly holds the test file.
+
+    Args:
+        test_path: The resolved path of the written stem-matched test file.
+        production_stem: The production-module stem the test filename names.
+
+    Returns:
+        The first candidate production module path that exists on disk, or None
+        when no candidate module file exists.
+    """
+    production_filename = production_stem + PYTHON_SOURCE_SUFFIX
+    test_directory = test_path.parent
+    all_candidate_paths = [test_directory / production_filename]
+    if test_directory.name == TESTS_DIRECTORY_NAME:
+        all_candidate_paths.append(test_directory.parent / production_filename)
+    for each_candidate_path in all_candidate_paths:
+        if each_candidate_path.is_file():
+            return each_candidate_path
+    return None
+
+
+def _post_edit_suite_referenced_identifiers(
+    suite_directory: Path,
+    written_test_path: Path,
+    written_test_content: str,
+) -> set[str]:
+    """Return suite identifiers, reading the written test's post-edit content.
+
+    Scans every ``test_*.py`` and ``*_test.py`` file in the suite directory,
+    bounded by the scan cap, and unions the identifiers each references. The
+    written test file contributes ``written_test_content`` rather than its stale
+    on-disk text, so the post-edit suite is judged.
+
+    Args:
+        suite_directory: The directory holding the suite's test files.
+        written_test_path: The resolved path of the test file being written.
+        written_test_content: The post-edit text of the written test file.
+
+    Returns:
+        The union of referenced identifiers across the post-edit suite.
+    """
+    all_test_file_paths: list[Path] = []
+    for each_glob in ALL_TEST_FILENAME_GLOBS:
+        all_test_file_paths.extend(sorted(suite_directory.glob(each_glob)))
+    written_path_key = os.path.normcase(str(written_test_path))
+    all_referenced_identifiers = _collect_referenced_identifiers(written_test_content)
+    for each_test_file_path in all_test_file_paths[:MAX_TEST_FILES_SCANNED]:
+        if os.path.normcase(str(each_test_file_path.resolve())) == written_path_key:
+            continue
+        try:
+            test_source = each_test_file_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        all_referenced_identifiers |= _collect_referenced_identifiers(test_source)
+    return all_referenced_identifiers
+
+
+def check_test_file_omits_module_public_function(
+    content: str,
+    file_path: str,
+) -> list[str]:
+    """Flag a public function the written test file's paired suite omits.
+
+    The companion of ``check_public_function_missing_paired_test`` for the
+    reverse write order: when a production module is written before its test
+    file, the production-side check sees no suite yet and the omission slips
+    through, so this check fires on the stem-matched test-file write instead. It
+    resolves the production module the written ``test_<stem>.py`` or
+    ``<stem>_test.py`` file pairs with, and when the post-edit suite already
+    covers at least one of that module's public functions, flags every public
+    function the suite references nowhere. ``main`` and underscore-prefixed
+    functions are never required to carry a test, and a production module that is
+    itself exempt — a test module, hook infrastructure, config module, migration,
+    workflow registry, or ``__init__`` module — is skipped.
+
+    A stem-matched test-file write authors the whole pairing relationship, so
+    every omission is reported unscoped: the gap lives in the test file under
+    edit, while the omitted function's definition line lives in the production
+    module — a different file whose line numbers are not addressable against the
+    test file's changed lines. Diff-line intersection would compare the two
+    unrelated coordinate spaces, so this check returns each omission directly
+    and the commit/push gate treats it as blocking.
+
+    Args:
+        content: The reconstructed post-edit whole-file content of the test file.
+        file_path: The destination path of the written test file, used to resolve
+            its paired production module on disk.
+
+    Returns:
+        One violation per public function the suite omits, capped at the
+        configured maximum. Empty when the file is not a stem-matched test file,
+        no paired production module exists on disk, the production module is
+        exempt or defines no public function, or the suite covers none of the
+        module's public functions.
+    """
+    production_stem = _production_stem_from_test_filename(Path(file_path).name)
+    if production_stem is None:
+        return []
+    test_path = Path(file_path).resolve()
+    production_module_path = _paired_production_module_path(test_path, production_stem)
+    if production_module_path is None:
+        return []
+    if _module_is_exempt(str(production_module_path)):
+        return []
+    try:
+        production_source = production_module_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    try:
+        production_tree = ast.parse(production_source)
+    except SyntaxError:
+        return []
+    all_public_definitions = _public_function_definitions(production_tree)
+    if not all_public_definitions:
+        return []
+    all_referenced_identifiers = _post_edit_suite_referenced_identifiers(
+        test_path.parent, test_path, content
+    )
+    covered_function_count = sum(
+        1
+        for each_name, _each_line in all_public_definitions
+        if each_name in all_referenced_identifiers
+    )
+    if covered_function_count < MINIMUM_COVERED_PUBLIC_FUNCTIONS:
+        return []
+    production_module_name = production_module_path.name
+    all_omission_violations: list[str] = []
+    for each_name, _each_definition_line in all_public_definitions:
+        if each_name in all_referenced_identifiers:
+            continue
+        all_omission_violations.append(
+            f"{production_module_name} public function "
+            f"{each_name!r} {TEST_SUITE_OMITS_FUNCTION_GUIDANCE}"
+        )
+        if len(all_omission_violations) >= MAX_PAIRED_TEST_COVERAGE_ISSUES:
+            break
+    return all_omission_violations
+

package/hooks/blocking/code_rules_test_assertions.py

@@ -1,4 +1,4 @@
-"""Skip-decorator, existence-only, constant-equality, stale-test-name, and flag-gated scenario test-quality checks."""
+"""Skip-decorator, existence-only, constant-equality, stale-test-name, flag-gated scenario, and vacuous cleanup-assertion test-quality checks."""
 
 import ast
 import sys
@@ -6,6 +6,37 @@ from pathlib import Path
 
 _SCENARIO_NAME_CLAUSES = ("_when_", "_passes", "_succeeds", "_on_clean")
 _MINIMUM_SIBLING_PATCH_COUNT = 2
+_CLEANUP_REMOVAL_NAME_TOKENS = (
+    "remove",
+    "removes",
+    "removed",
+    "cleanup",
+    "clean_up",
+    "deletes",
+    "discards",
+    "no_tmp",
+    "no_temp",
+    "no_leftover",
+    "leftover",
+)
+_FAILURE_CONDITION_NAME_TOKENS = (
+    "on_failure",
+    "_failure",
+    "on_error",
+    "_fails",
+    "_failed",
+    "raises",
+    "bad_source",
+)
+_ARRANGEMENT_METHOD_NAMES = (
+    "setattr",
+    "mkdir",
+    "write_text",
+    "write_bytes",
+    "touch",
+    "symlink_to",
+    "exists",
+)
 
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
@@ -233,6 +264,133 @@ def check_constant_equality_tests(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _name_signals_cleanup_on_failure(test_name: str) -> bool:
+    """Return True when a test name pairs a removal token with a failure token."""
+    lowered_name = test_name.lower()
+    has_removal_token = any(
+        each_token in lowered_name for each_token in _CLEANUP_REMOVAL_NAME_TOKENS
+    )
+    has_failure_token = any(
+        each_token in lowered_name for each_token in _FAILURE_CONDITION_NAME_TOKENS
+    )
+    return has_removal_token and has_failure_token
+
+
+def _is_absence_assertion(assert_node: ast.Assert) -> bool:
+    """Return True when an assertion only checks that a collection is empty."""
+    test_expr = assert_node.test
+    if isinstance(test_expr, ast.UnaryOp) and isinstance(test_expr.op, ast.Not):
+        return True
+    if not isinstance(test_expr, ast.Compare):
+        return False
+    if len(test_expr.ops) != 1 or not isinstance(test_expr.ops[0], ast.Eq):
+        return False
+    comparator = test_expr.comparators[0]
+    if (
+        isinstance(comparator, ast.Constant)
+        and isinstance(comparator.value, int)
+        and not isinstance(comparator.value, bool)
+        and comparator.value == 0
+    ):
+        return True
+    return isinstance(comparator, ast.List) and not comparator.elts
+
+
+def _body_calls_attribute(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef, attribute_name: str
+) -> bool:
+    """Return True when the function body calls a method with the given attribute name."""
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Call):
+            continue
+        callee = each_node.func
+        if isinstance(callee, ast.Attribute) and callee.attr == attribute_name:
+            return True
+    return False
+
+
+def _body_arranges_temp_existence(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when the body creates a temp file or arranges a post-creation failure.
+
+    A sound cleanup-on-failure test proves the temp existed before asserting its
+    removal: it monkeypatches the operation to fail after the temp is created, or
+    it creates the temp directly and checks its presence. Either signal means the
+    leftover-absence assertion is not vacuous.
+
+    Args:
+        function_node: The test function whose body is inspected.
+
+    Returns:
+        True when the body references ``monkeypatch`` or calls a file-creation or
+        existence method that establishes the temp file before the cleanup runs.
+    """
+    for each_node in ast.walk(function_node):
+        if isinstance(each_node, ast.Name) and each_node.id == "monkeypatch":
+            return True
+        if not isinstance(each_node, ast.Call):
+            continue
+        callee = each_node.func
+        if isinstance(callee, ast.Attribute) and callee.attr in _ARRANGEMENT_METHOD_NAMES:
+            return True
+    return False
+
+
+def check_vacuous_cleanup_assertion_tests(content: str, file_path: str) -> list[str]:
+    """Flag a cleanup-on-failure test whose leftover-absence assertion is vacuous.
+
+    A test named for removal on failure that globs a directory and asserts the
+    result is empty, yet never creates the temp file nor arranges a failure after
+    the temp exists, passes even when the on-failure cleanup is entirely broken —
+    the leftover set is empty because nothing ever staged a leftover. The gate
+    fires when the test name pairs a removal token with a failure token, the body
+    globs a directory, every assertion only checks emptiness, and the body neither
+    monkeypatches a post-creation failure nor creates and checks the temp first.
+    Only applies to test files; production files are exempt.
+
+    Args:
+        content: The file body under validation.
+        file_path: Path to the file, used for the test-file gate.
+
+    Returns:
+        One issue per test whose cleanup-on-failure assertion passes vacuously.
+    """
+    if not is_test_file(file_path):
+        return []
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    issues: list[str] = []
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not each_node.name.startswith("test"):
+            continue
+        if not _name_signals_cleanup_on_failure(each_node.name):
+            continue
+        if not _body_calls_attribute(each_node, "glob"):
+            continue
+        if _body_arranges_temp_existence(each_node):
+            continue
+        body_assertions = _collect_body_assertions(each_node.body)
+        if not body_assertions:
+            continue
+        if not all(_is_absence_assertion(each_assert) for each_assert in body_assertions):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: vacuous cleanup-on-failure test"
+            f" — asserts no leftover temp file but never proves the temp was created,"
+            f" so it passes even when cleanup is broken; arrange a post-creation"
+            f" failure (e.g. monkeypatch os.replace to raise after the temp exists)"
+            f" then assert the temp was removed"
+        )
+
+    return issues
+
+
 def _flag_symbol_from_setattr_target(target_node: ast.expr) -> str | None:
     """Return the UPPER_SNAKE flag symbol a monkeypatch.setattr target names.
 

package/hooks/blocking/code_rules_unused_imports.py

@@ -20,13 +20,10 @@ from code_rules_shared import (  # noqa: E402
     _build_parent_map,
     is_migration_file,
     is_test_file,
-    is_workflow_registry_file,
 )
 
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
-    ALL_TYPING_MODULE_NAMES,
     MAX_UNUSED_IMPORT_ISSUES,
-    TYPE_CHECKING_IDENTIFIER,
     UNUSED_IMPORT_GUIDANCE,
     line_suppresses_unused_import_via_noqa,
 )
@@ -73,59 +70,6 @@ def _line_number_falls_in_import_ranges(
     return False
 
 
-def _type_checking_guard_aliases(tree: ast.Module) -> tuple[set[str], set[str]]:
-    all_type_checking_names = {TYPE_CHECKING_IDENTIFIER}
-    all_type_checking_module_aliases = set(ALL_TYPING_MODULE_NAMES)
-    for each_statement in tree.body:
-        if isinstance(each_statement, ast.Import):
-            for each_alias in each_statement.names:
-                if each_alias.name in ALL_TYPING_MODULE_NAMES:
-                    all_type_checking_module_aliases.add(
-                        each_alias.asname or each_alias.name
-                    )
-        elif isinstance(each_statement, ast.ImportFrom):
-            if each_statement.module not in ALL_TYPING_MODULE_NAMES:
-                continue
-            for each_alias in each_statement.names:
-                if each_alias.name == TYPE_CHECKING_IDENTIFIER:
-                    all_type_checking_names.add(each_alias.asname or each_alias.name)
-    return all_type_checking_names, all_type_checking_module_aliases
-
-
-def _expression_guards_type_checking_block(
-    test_expression: ast.expr,
-    all_type_checking_names: set[str],
-    all_type_checking_module_aliases: set[str],
-) -> bool:
-    if isinstance(test_expression, ast.Name):
-        return test_expression.id in all_type_checking_names
-    if isinstance(test_expression, ast.Attribute):
-        if test_expression.attr != TYPE_CHECKING_IDENTIFIER:
-            return False
-        receiver = test_expression.value
-        return (
-            isinstance(receiver, ast.Name)
-            and receiver.id in all_type_checking_module_aliases
-        )
-    return False
-
-
-def _module_body_declares_type_checking_gate(tree: ast.Module) -> bool:
-    (
-        all_type_checking_names,
-        all_type_checking_module_aliases,
-    ) = _type_checking_guard_aliases(tree)
-    return any(
-        isinstance(each_statement, ast.If)
-        and _expression_guards_type_checking_block(
-            each_statement.test,
-            all_type_checking_names,
-            all_type_checking_module_aliases,
-        )
-        for each_statement in tree.body
-    )
-
-
 def _collect_load_names_outside_import_ranges(
     tree: ast.Module,
     all_import_line_ranges: list[tuple[int, int]],
@@ -191,10 +135,12 @@ def check_unused_module_level_imports(
 
     References are detected from AST ``Name`` / ``Attribute`` loads outside import
     statements so mentions in comments or string literals do not count. Files
-    declaring ``__all__`` (including annotated assignments) are skipped. Files
-    whose module body includes ``if TYPE_CHECKING:`` (or
-    ``typing[._extensions].TYPE_CHECKING``) are skipped. Suppression honors bare
-    ``# noqa`` or an explicit ``F401`` code in the noqa list only.
+    declaring ``__all__`` (including annotated assignments) are skipped. A
+    ``if TYPE_CHECKING:`` block does not exempt the file: its guarded imports
+    are nested inside the ``If`` node and are never scanned as top-level
+    bindings, while a dead top-level runtime import in the same file is still
+    flagged. Suppression honors bare ``# noqa`` or an explicit ``F401`` code in
+    the noqa list only.
 
     When ``full_file_content`` is provided, ``content`` is treated as an Edit
     fragment containing the imports being added or replaced, while the
@@ -205,7 +151,7 @@ def check_unused_module_level_imports(
     """
     if is_test_file(file_path):
         return []
-    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+    if is_migration_file(file_path):
         return []
     try:
         fragment_tree = ast.parse(content)
@@ -218,8 +164,6 @@ def check_unused_module_level_imports(
         return []
     if _module_declares_dunder_all(reference_tree):
         return []
-    if _module_body_declares_type_checking_gate(reference_tree):
-        return []
     fragment_lines = content.splitlines()
     reference_import_ranges = _import_statement_line_ranges(reference_tree)
     referenced_names = _collect_load_names_outside_import_ranges(