claude-dev-env 1.79.0 → 1.80.0

package/_shared/pr-loop/scripts/tests/test_copilot_quota.py

@@ -0,0 +1,242 @@
+"""Direct unit tests for the copilot_quota pre-check.
+
+Every case drives the production ``main`` / ``evaluate_copilot_quota`` path with
+only the ``gh`` subprocess boundary (``_run_gh``) stubbed, fed a captured
+``copilot_internal/user`` JSON fixture in the jonecho shape.
+"""
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_copilot_quota_module() -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    if str(scripts_directory) not in sys.path:
+        sys.path.insert(0, str(scripts_directory))
+    module_path = scripts_directory / "copilot_quota.py"
+    specification = importlib.util.spec_from_file_location("copilot_quota", module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[specification.name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+copilot_quota = _load_copilot_quota_module()
+
+FIXTURE_PATH = Path(__file__).parent / "fixtures" / "copilot_internal_user_jonecho.json"
+AVAILABLE_USER_JSON = FIXTURE_PATH.read_text(encoding="utf-8")
+FAKE_TOKEN_RESULT = (0, "ghp_faketoken_value\n")
+
+
+def _exhausted_user_json() -> str:
+    user = json.loads(AVAILABLE_USER_JSON)
+    premium = user["quota_snapshots"]["premium_interactions"]
+    premium["remaining"] = 0
+    premium["quota_remaining"] = 0.0
+    premium["percent_remaining"] = 0.0
+    return json.dumps(user)
+
+
+def _user_json_without_premium_snapshot() -> str:
+    user = json.loads(AVAILABLE_USER_JSON)
+    del user["quota_snapshots"]
+    return json.dumps(user)
+
+
+def _gh_stub(token_result: tuple[int, str], api_result: tuple[int, str]):
+    def _fake_run_gh(
+        command_arguments: list[str],
+        extra_environment: dict[str, str] | None = None,
+    ) -> tuple[int, str]:
+        if command_arguments and command_arguments[0] == "auth":
+            return token_result
+        if command_arguments and command_arguments[0] == "api":
+            return api_result
+        raise AssertionError(f"unexpected gh command {command_arguments}")
+
+    return _fake_run_gh
+
+
+@pytest.fixture(autouse=True)
+def _isolate_account_sources(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.delenv("COPILOT_QUOTA_ACCOUNT", raising=False)
+    monkeypatch.setattr(
+        copilot_quota, "COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH", tmp_path / ".env"
+    )
+
+
+def test_main_runs_copilot_when_premium_quota_available(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota,
+        "_run_gh",
+        _gh_stub(FAKE_TOKEN_RESULT, (0, AVAILABLE_USER_JSON)),
+    )
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert "running Copilot" in captured.out
+    assert "6817" in captured.out
+
+
+def test_main_exits_out_of_quota_when_premium_exhausted(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota,
+        "_run_gh",
+        _gh_stub(FAKE_TOKEN_RESULT, (0, _exhausted_user_json())),
+    )
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == 1
+    assert "scenario A" in captured.err
+
+
+def test_main_exits_api_down_on_non_json_response(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota,
+        "_run_gh",
+        _gh_stub(FAKE_TOKEN_RESULT, (0, "not json at all")),
+    )
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == 2
+    assert "scenario B" in captured.err
+
+
+def test_main_exits_api_down_on_missing_premium_snapshot(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota,
+        "_run_gh",
+        _gh_stub(FAKE_TOKEN_RESULT, (0, _user_json_without_premium_snapshot())),
+    )
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == 2
+    assert "scenario B" in captured.err
+
+
+def test_main_exits_api_down_when_gh_token_unresolved(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota,
+        "_run_gh",
+        _gh_stub((1, ""), (0, AVAILABLE_USER_JSON)),
+    )
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == 2
+    assert "scenario B" in captured.err
+
+
+def test_main_exits_no_config_and_names_env_path_and_key(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _fail_if_called(
+        command_arguments: list[str],
+        extra_environment: dict[str, str] | None = None,
+    ) -> tuple[int, str]:
+        raise AssertionError("gh must not run when no account is configured")
+
+    monkeypatch.setattr(copilot_quota, "_run_gh", _fail_if_called)
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == 3
+    assert "scenario C" in captured.err
+    assert "COPILOT_QUOTA_ACCOUNT" in captured.err
+    assert ".env" in captured.err
+
+
+@pytest.mark.parametrize(
+    ("api_result", "expected_exit_code", "expected_scenario"),
+    [
+        ((0, _exhausted_user_json()), 1, "scenario A"),
+        ((0, "not json at all"), 2, "scenario B"),
+    ],
+)
+def test_every_gh_backed_skip_writes_a_log_line_naming_the_scenario(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    api_result: tuple[int, str],
+    expected_exit_code: int,
+    expected_scenario: str,
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota, "_run_gh", _gh_stub(FAKE_TOKEN_RESULT, api_result)
+    )
+    exit_code = copilot_quota.main([])
+    captured = capsys.readouterr()
+    assert exit_code == expected_exit_code
+    assert captured.out == ""
+    assert expected_scenario in captured.err
+    assert captured.err.strip() != ""
+
+
+def test_cli_account_takes_precedence_over_env_var(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "env-user")
+    accounts_seen: list[str] = []
+
+    def _fake_run_gh(
+        command_arguments: list[str],
+        extra_environment: dict[str, str] | None = None,
+    ) -> tuple[int, str]:
+        if command_arguments[0] == "auth":
+            accounts_seen.append(command_arguments[-1])
+            return FAKE_TOKEN_RESULT
+        return (0, AVAILABLE_USER_JSON)
+
+    monkeypatch.setattr(copilot_quota, "_run_gh", _fake_run_gh)
+    decision = copilot_quota.evaluate_copilot_quota(
+        cli_account="cli-user", env_file_path=tmp_path / ".env"
+    )
+    assert decision.exit_code == 0
+    assert accounts_seen == ["cli-user"]
+
+
+def test_account_resolves_from_env_file_when_flag_and_env_absent(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    env_file = tmp_path / ".env"
+    env_file.write_text(
+        "# local copilot quota account\nCOPILOT_QUOTA_ACCOUNT=file-user\n",
+        encoding="utf-8",
+    )
+    accounts_seen: list[str] = []
+
+    def _fake_run_gh(
+        command_arguments: list[str],
+        extra_environment: dict[str, str] | None = None,
+    ) -> tuple[int, str]:
+        if command_arguments[0] == "auth":
+            accounts_seen.append(command_arguments[-1])
+            return FAKE_TOKEN_RESULT
+        return (0, AVAILABLE_USER_JSON)
+
+    monkeypatch.setattr(copilot_quota, "_run_gh", _fake_run_gh)
+    decision = copilot_quota.evaluate_copilot_quota(
+        cli_account=None, env_file_path=env_file
+    )
+    assert decision.exit_code == 0
+    assert accounts_seen == ["file-user"]

package/_shared/pr-loop/scripts/tests/test_copilot_quota_constants.py

@@ -0,0 +1,63 @@
+"""Tests for copilot_quota_constants.py extracted constant set."""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_constants_module() -> ModuleType:
+    module_path = (
+        Path(__file__).parent.parent
+        / "pr_loop_shared_constants"
+        / "copilot_quota_constants.py"
+    )
+    specification = importlib.util.spec_from_file_location(
+        "pr_loop_shared_constants.copilot_quota_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+constants_module = _load_constants_module()
+
+
+def test_copilot_quota_account_env_var_name() -> None:
+    assert (
+        constants_module.COPILOT_QUOTA_ACCOUNT_ENV_VAR_NAME == "COPILOT_QUOTA_ACCOUNT"
+    )
+
+
+def test_gh_token_env_var_name() -> None:
+    assert constants_module.GH_TOKEN_ENV_VAR_NAME == "GH_TOKEN"
+
+
+def test_copilot_internal_user_api_path() -> None:
+    assert constants_module.COPILOT_INTERNAL_USER_API_PATH == "copilot_internal/user"
+
+
+def test_premium_interactions_gating_field_names() -> None:
+    assert constants_module.QUOTA_SNAPSHOTS_FIELD_NAME == "quota_snapshots"
+    assert constants_module.PREMIUM_INTERACTIONS_FIELD_NAME == "premium_interactions"
+    assert constants_module.PREMIUM_UNLIMITED_FIELD_NAME == "unlimited"
+    assert constants_module.PREMIUM_REMAINING_FIELD_NAME == "remaining"
+    assert constants_module.PREMIUM_OVERAGE_PERMITTED_FIELD_NAME == "overage_permitted"
+
+
+def test_exit_codes_are_the_four_distinct_scenarios() -> None:
+    all_exit_codes = (
+        constants_module.EXIT_CODE_QUOTA_AVAILABLE,
+        constants_module.EXIT_CODE_OUT_OF_QUOTA,
+        constants_module.EXIT_CODE_QUOTA_API_DOWN,
+        constants_module.EXIT_CODE_NO_ACCOUNT_CONFIGURED,
+    )
+    assert all_exit_codes == (0, 1, 2, 3)
+    assert len(set(all_exit_codes)) == len(all_exit_codes)
+
+
+def test_default_env_file_path_sits_at_the_package_root() -> None:
+    default_env_file_path = constants_module.COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH
+    assert default_env_file_path.name == ".env"
+    assert default_env_file_path.parent.name == "claude-dev-env"

package/hooks/blocking/code_rules_enforcer.py

@@ -102,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,
@@ -468,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_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(

package/hooks/blocking/test_code_rules_enforcer_js_returns_object.py

@@ -0,0 +1,72 @@
+"""Enforcer-dispatch tests for the JS returns-object schema-less branch check.
+
+These drive ``validate_content`` end-to-end on a ``.mjs`` payload, so they prove
+the check is wired into the JavaScript branch of the enforcer, not just callable
+in isolation. The drift: a ``function`` whose JSDoc ``@returns {Promise<object>}``
+promises a structured object while one branch returns the agent helper with an
+options object that omits ``schema`` and so resolves to a transcript string.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+_MJS_PATH = "skills/autoconverge/workflow/converge.mjs"
+
+
+def _mixed_schema_mjs() -> str:
+    return (
+        "/**\n"
+        " * Spawn a git-utility agent.\n"
+        " * @returns {Promise<object>} the structured output\n"
+        " */\n"
+        "function runGitTask(task, head) {\n"
+        "  if (task === 'resolve-head') {\n"
+        "    return convergeAgent(`head ${x}`, { label: 'g', schema: HEAD_SCHEMA, agentType: 'Explore' })\n"
+        "  }\n"
+        "  return convergeAgent(`fetch ${x}`, { label: 'g', agentType: 'Explore' })\n"
+        "}\n"
+    )
+
+
+def _all_schema_mjs() -> str:
+    return _mixed_schema_mjs().replace(
+        "{ label: 'g', agentType: 'Explore' })",
+        "{ label: 'g', schema: FETCH_SCHEMA, agentType: 'Explore' })",
+    )
+
+
+def _has_returns_object_finding(all_issues: list[str]) -> bool:
+    return any("runGitTask" in each_issue and "@returns" in each_issue for each_issue in all_issues)
+
+
+def test_enforcer_reports_schema_less_branch_under_returns_object() -> None:
+    drift_source = _mixed_schema_mjs()
+    all_issues = code_rules_enforcer.validate_content(drift_source, _MJS_PATH, drift_source)
+    assert _has_returns_object_finding(all_issues)
+
+
+def test_enforcer_accepts_every_branch_with_a_schema() -> None:
+    clean_source = _all_schema_mjs()
+    all_issues = code_rules_enforcer.validate_content(clean_source, _MJS_PATH, clean_source)
+    assert not _has_returns_object_finding(all_issues)