claude-dev-env 1.78.0 → 1.79.0

package/hooks/blocking/code_rules_enforcer.py

@@ -72,11 +72,15 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_args_match_signature,
     check_docstring_args_single_line_scope_vs_span,
     check_docstring_cardinal_count_matches_constant_family,
+    check_docstring_documents_unreferenced_parameter,
     check_docstring_fallback_branch_coverage,
+    check_docstring_field_runmode_outcome,
     check_docstring_format,
+    check_docstring_length_constant_superlative_vs_exact_gate,
     check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
+    check_docstring_no_network_claim_with_metadata_access,
     check_docstring_punctuation_mark_enumeration_coverage,
     check_docstring_raises_unraisable_largezipfile,
     check_docstring_returns_plural_cardinality,
@@ -85,6 +89,7 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_tuple_enumeration_match,
     check_docstring_unguarded_malformed_payload_claim,
     check_module_docstring_names_public_checks,
+    check_module_docstring_scope_omits_data_schema_constants,
 )
 from code_rules_duplicate_body import (  # noqa: E402
     advise_cross_skill_duplicate_helper,
@@ -112,6 +117,7 @@ from code_rules_mock_completeness import (  # noqa: E402
 from code_rules_naming_collection import (  # noqa: E402
     check_collection_prefix,
     check_loop_variable_naming,
+    check_polarity_name_contradiction,
     check_stuttering_collection_prefix,
 )
 from code_rules_optional_params import (  # noqa: E402
@@ -123,6 +129,7 @@ from code_rules_orphan_css_class import (  # noqa: E402
 )
 from code_rules_paired_test import (  # noqa: E402
     check_public_function_missing_paired_test,
+    check_test_file_omits_module_public_function,
 )
 from code_rules_paths_syspath import (  # noqa: E402
     check_hardcoded_user_paths,
@@ -147,6 +154,7 @@ from code_rules_test_assertions import (  # noqa: E402
     check_flag_gated_scenario_test_naming,
     check_skip_decorators_in_tests,
     check_stale_test_name_target,
+    check_vacuous_cleanup_assertion_tests,
 )
 from code_rules_test_branching_except import (  # noqa: E402
     check_bare_except,
@@ -294,8 +302,16 @@ def validate_content(
         all_issues.extend(check_boundary_types(effective_content, file_path))
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
+        all_issues.extend(
+            check_docstring_documents_unreferenced_parameter(effective_content, file_path)
+        )
         all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
         all_issues.extend(check_docstring_no_consumer_claim(effective_content, file_path))
+        all_issues.extend(
+            check_docstring_no_network_claim_with_metadata_access(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_unguarded_malformed_payload_claim(
                 effective_content, file_path
@@ -311,6 +327,11 @@ def validate_content(
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
         )
+        all_issues.extend(
+            check_module_docstring_scope_omits_data_schema_constants(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_tuple_enumeration_match(effective_content, file_path)
         )
@@ -327,6 +348,14 @@ def validate_content(
         all_issues.extend(
             check_docstring_returns_plural_cardinality(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_length_constant_superlative_vs_exact_gate(
+                effective_content, file_path
+            )
+        )
+        all_issues.extend(
+            check_docstring_field_runmode_outcome(effective_content, file_path)
+        )
         all_issues.extend(
             check_docstring_raises_unraisable_largezipfile(effective_content, file_path)
         )
@@ -368,6 +397,7 @@ def validate_content(
         )
         all_issues.extend(check_existence_check_tests(content, file_path))
         all_issues.extend(check_constant_equality_tests(content, file_path))
+        all_issues.extend(check_vacuous_cleanup_assertion_tests(content, file_path))
         all_issues.extend(check_stale_test_name_target(content, file_path))
         check_flag_gated_scenario_test_naming(content, file_path)
         all_issues.extend(check_unused_optional_parameters(content, file_path))
@@ -414,7 +444,14 @@ def validate_content(
                 defer_scope_to_caller,
             )
         )
+        all_issues.extend(
+            check_test_file_omits_module_public_function(
+                effective_content,
+                file_path,
+            )
+        )
         all_issues.extend(check_loop_variable_naming(content, file_path))
+        all_issues.extend(check_polarity_name_contradiction(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
         all_issues.extend(check_string_literal_magic(content, file_path))

package/hooks/blocking/code_rules_naming_collection.py

@@ -1,6 +1,7 @@
-"""Collection-prefix, stuttering-prefix, and loop-variable naming checks."""
+"""Collection-prefix, stuttering-prefix, loop-variable, and polarity-name-contradiction naming checks."""
 
 import ast
+import re
 import sys
 from pathlib import Path
 
@@ -11,6 +12,7 @@ if _blocking_directory not in sys.path:
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
+from code_rules_boolean_mustcheck import _called_terminal_name  # noqa: E402
 from code_rules_shared import (  # noqa: E402
     _collect_annotated_arguments,
     _collect_target_names,
@@ -22,11 +24,13 @@ from code_rules_shared import (  # noqa: E402
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_COLLECTION_TYPE_NAMES,
     ALL_LOOP_INDEX_LETTER_EXEMPTIONS,
+    ALL_POLARITY_ANTONYM_TOKEN_PAIRS,
     ALL_SUBSCRIPT_ONLY_COLLECTION_TYPE_NAMES,
     ALL_UNION_TYPING_NAMES,
     BARE_EACH_TOKEN,
     COLLECTION_BY_NAME_PATTERN,
     EACH_PREFIX,
+    POLARITY_TOKEN_BOUNDARY_PATTERN,
     UPPER_SNAKE_CONSTANT_PATTERN,
 )
 from hooks_constants.stuttering_check_config import (  # noqa: E402
@@ -262,3 +266,74 @@ def check_loop_variable_naming(content: str, file_path: str) -> list[str]:
                 f"Line {each_name_node.lineno}: loop variable {target_name!r} - prefix with each_ (CODE_RULES §5)"
             )
     return issues
+
+
+def _name_carries_token(name: str, token: str) -> bool:
+    """True when name carries token as a whole underscore-delimited word."""
+    return re.search(POLARITY_TOKEN_BOUNDARY_PATTERN % re.escape(token), name) is not None
+
+
+def _contradicting_polarity_pair(target_name: str, called_name: str) -> tuple[str, str] | None:
+    """The (target_token, called_token) antonym pair when target and callee assert opposite polarity."""
+    target_lower = target_name.lower()
+    called_lower = called_name.lower()
+    for each_positive_token, each_negative_token in ALL_POLARITY_ANTONYM_TOKEN_PAIRS:
+        if _name_carries_token(target_lower, each_positive_token) and _name_carries_token(
+            called_lower, each_negative_token
+        ):
+            return each_positive_token, each_negative_token
+        if _name_carries_token(target_lower, each_negative_token) and _name_carries_token(
+            called_lower, each_positive_token
+        ):
+            return each_negative_token, each_positive_token
+    return None
+
+
+def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]:
+    """Flag a boolean assignment whose target and callee assert opposite polarity.
+
+    Catches the self-contradicting statement ``is_inside_allowed =
+    _point_hits_any_forbidden(...)`` — a target name carrying one polarity token
+    (``allowed``) assigned directly from a single call whose callee name carries
+    the antonym token (``forbidden``). One side lies about the behavior, so the
+    reader cannot trust either name. Rename the callee to a neutral form that
+    reads truthfully at every call site.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        target_name: str | None = None
+        value_node: ast.expr | None = None
+        target_line = 0
+        if isinstance(each_node, ast.Assign) and len(each_node.targets) == 1 and isinstance(
+            each_node.targets[0], ast.Name
+        ):
+            target_name = each_node.targets[0].id
+            value_node = each_node.value
+            target_line = each_node.lineno
+        elif isinstance(each_node, ast.AnnAssign) and isinstance(each_node.target, ast.Name):
+            target_name = each_node.target.id
+            value_node = each_node.value
+            target_line = each_node.lineno
+        if target_name is None or not isinstance(value_node, ast.Call):
+            continue
+        called_name = _called_terminal_name(value_node)
+        if called_name is None:
+            continue
+        contradicting_pair = _contradicting_polarity_pair(target_name, called_name)
+        if contradicting_pair is None:
+            continue
+        target_token, called_token = contradicting_pair
+        issues.append(
+            f"Line {target_line}: {target_name!r} (says {target_token!r}) is assigned from"
+            f" {called_name!r} (says {called_token!r}) - the name contradicts the value; rename the"
+            f" callee to a neutral form so each call site reads truthfully (CODE_RULES §5)"
+        )
+    return issues

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
+