claude-dev-env 1.78.0 → 1.80.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,
@@ -97,6 +102,7 @@ from code_rules_imports_logging import (  # noqa: E402
     check_import_block_sorted,
     check_imports_at_top,
     check_js_resume_task_enumeration_coverage,
+    check_js_returns_object_schemaless_branch,
     check_library_print,
     check_logging_fstrings,
     check_logging_printf_tokens,
@@ -112,6 +118,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 +130,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 +155,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 +303,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 +328,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 +349,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 +398,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 +445,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))
@@ -431,6 +469,9 @@ def validate_content(
         all_issues.extend(
             check_js_resume_task_enumeration_coverage(content, file_path)
         )
+        all_issues.extend(
+            check_js_returns_object_schemaless_branch(content, file_path)
+        )
 
     if extension in ALL_CODE_EXTENSIONS:
         advise_file_line_count(content, file_path)

package/hooks/blocking/code_rules_imports_logging.py

@@ -1,4 +1,4 @@
-"""Imports-at-top, import-block-sorted, logging f-string, win32gui None, E2E spec naming, JS resume-task enumeration coverage, file-length advisory, and library-print checks."""
+"""Imports-at-top, import-block-sorted, logging f-string, win32gui None, E2E spec naming, JS resume-task enumeration coverage, JS returns-object schema-less branch, file-length advisory, and library-print checks."""
 
 import ast
 import json
@@ -34,6 +34,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_E2E_TEST_NAMING_ISSUES,
     MAX_IMPORT_BLOCK_SORT_ISSUES,
     MAX_JS_RESUME_TASK_ENUMERATION_ISSUES,
+    MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES,
     MAX_LOGGING_FSTRING_ISSUES,
     MAX_LOGGING_PRINTF_TOKEN_ISSUES,
     MAX_WINDOWS_API_NONE_ISSUES,
@@ -55,17 +56,21 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ENUMERATION_LEADING_CONJUNCTION_PATTERN,
     ENUMERATION_LIST_ITEM_SEPARATOR_PATTERN,
     ENUMERATION_TASK_ITEM_PATTERN,
+    FUNCTION_WITH_JSDOC_PATTERN,
     HYPHENATED_TASK_ITEM_PATTERN,
     JAVASCRIPT_BLOCK_COMMENT_CLOSER,
     JAVASCRIPT_BLOCK_COMMENT_OPENER,
     JAVASCRIPT_LINE_COMMENT_OPENER,
     JAVASCRIPT_REGEX_DELIMITER,
     JAVASCRIPT_STRING_ESCAPE_CHARACTER,
+    JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     LOGGING_FSTRING_PATTERN,
     LOGGING_PRINTF_TOKEN_PATTERN,
     MINIMUM_FORMAT_LOGGER_ARGUMENT_COUNT,
     NOT_INSIDE_TYPE_CHECKING_BLOCK,
     RESUME_TASK_ENUMERATION_PATTERN,
+    RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
+    SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
     SPAWN_AGENT_WITH_JSDOC_PATTERN,
     TASK_DISPATCH_NAME_PATTERN,
     TRIPLE_DOUBLE_QUOTE_DELIMITER,
@@ -919,6 +924,136 @@ def check_js_resume_task_enumeration_coverage(
     return issues[:MAX_JS_RESUME_TASK_ENUMERATION_ISSUES]
 
 
+def _parameter_list_end_index(blanked_content: str, after_open_parenthesis_index: int) -> int:
+    """Return the index just past the ``)`` that closes an opened parameter list.
+
+    ``after_open_parenthesis_index`` sits just past the opening ``(``, so the scan
+    starts one level deep and walks paren-balanced. A nested ``(`` inside the list
+    — a default-value call, a destructure default — does not close the list early.
+    """
+    depth = 1
+    for each_position in range(after_open_parenthesis_index, len(blanked_content)):
+        character = blanked_content[each_position]
+        if character == "(":
+            depth += 1
+        elif character == ")":
+            depth -= 1
+            if depth == 0:
+                return each_position + 1
+    return len(blanked_content)
+
+
+def _javascript_function_body(content: str, header_end_index: int) -> str | None:
+    """Return the brace-balanced body of the function whose header ends at the index.
+
+    ``header_end_index`` sits just past the opening ``(`` of the parameter list, so
+    the scan advances past the paren-balanced parameter list before finding the body
+    brace. A destructured parameter (``function f({ ... }) { ... }``) opens a brace
+    inside that list; the body brace is the first ``{`` after the list closes, not
+    the destructure brace.
+    """
+    body_search_index = _parameter_list_end_index(
+        _blank_non_code_regions(content), header_end_index
+    )
+    bounded_content = content[: _next_top_level_function_index(content, body_search_index)]
+    return _balanced_brace_body(bounded_content, body_search_index)
+
+
+def _balanced_parenthesis_span(blanked_content: str, opening_index: int) -> str:
+    """Return the paren-balanced slice of blanked source starting at an opening ``(``."""
+    depth = 0
+    for each_position in range(opening_index, len(blanked_content)):
+        character = blanked_content[each_position]
+        if character == "(":
+            depth += 1
+        elif character == ")":
+            depth -= 1
+            if depth == 0:
+                return blanked_content[opening_index : each_position + 1]
+    return blanked_content[opening_index:]
+
+
+def _mixed_schema_return_callees(function_body: str) -> set[str]:
+    """Return callees a function returns both with and without a schema options object.
+
+    The body is blanked so a brace or keyword inside a prompt string never counts.
+    Each ``return <callee>(...)`` whose argument list carries an object literal is
+    grouped by whether that argument list also carries a ``schema`` key. A callee
+    that appears on both sides marks a function that returns a schema object in one
+    branch and a schema-less transcript in another.
+    """
+    blanked_body = _blank_non_code_regions(function_body)
+    schema_bearing_callees: set[str] = set()
+    schema_less_callees: set[str] = set()
+    for each_return_match in RETURN_CALL_OPENING_PARENTHESIS_PATTERN.finditer(blanked_body):
+        argument_span = _balanced_parenthesis_span(blanked_body, each_return_match.end() - 1)
+        if "{" not in argument_span:
+            continue
+        callee_name = each_return_match.group("callee")
+        if SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN.search(argument_span) is not None:
+            schema_bearing_callees.add(callee_name)
+        else:
+            schema_less_callees.add(callee_name)
+    return schema_bearing_callees & schema_less_callees
+
+
+def check_js_returns_object_schemaless_branch(content: str, file_path: str) -> list[str]:
+    """Flag a JSDoc @returns Promise<object> whose branch returns a transcript string.
+
+    Picture a dispatcher that spawns an agent and returns whatever the agent
+    resolves to. Most branches pass a ``schema`` in the agent options, so the agent
+    resolves to a structured object — and the JSDoc reads
+    ``@returns {Promise<object>}``. But one branch spawns the same agent with no
+    schema, so that branch resolves to a plain transcript string. A caller who
+    trusts the object contract and reads a field off the result gets undefined on
+    that branch.
+
+    The check reads each ``function`` declaration that carries a JSDoc block. When
+    the JSDoc promises a ``Promise<object>`` and the body returns one agent helper
+    both with a ``schema`` options object and without one, the schema-less branch
+    contradicts the object claim and the function is flagged. A function whose every
+    return passes a schema, one that returns plain object literals, and one whose
+    ``@returns`` already admits a string are all left alone. This is the JS/.mjs
+    slice of Category O6 docstring-prose-vs-implementation drift; the Python
+    enforcer's AST docstring checks never inspect JavaScript source.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose object return-type claim a schema-less branch
+        contradicts, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    if get_file_extension(file_path) not in ALL_JAVASCRIPT_EXTENSIONS:
+        return []
+    issues: list[str] = []
+    for each_match in FUNCTION_WITH_JSDOC_PATTERN.finditer(content):
+        if JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search(each_match.group("jsdoc")) is None:
+            continue
+        function_body = _javascript_function_body(content, each_match.end())
+        if function_body is None:
+            continue
+        mixed_callees = _mixed_schema_return_callees(function_body)
+        if not mixed_callees:
+            continue
+        function_name = each_match.group("name")
+        line_number = content.count("\n", 0, each_match.start("name")) + 1
+        joined_callees = ", ".join(sorted(mixed_callees))
+        issues.append(
+            f"Line {line_number}: {function_name}() JSDoc @returns a Promise<object> but a "
+            f"branch returns {joined_callees}(...) with a schema-less options object — that "
+            "branch resolves to a transcript string, not the structured object the @returns "
+            "claims; widen the @returns type to admit the string transcript, or pass a schema "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES:
+            break
+    return issues[:MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES]
+
+
 def _is_cli_entry_point(file_path: str) -> bool:
     path_lower = file_path.lower().replace("\\", "/")
     return any(marker.replace("\\", "/") in path_lower for marker in ALL_CLI_FILE_PATH_MARKERS)

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