claude-dev-env 1.60.0 → 1.62.0

package/hooks/blocking/test_code_rules_enforcer_annotations.py

@@ -320,3 +320,243 @@ def test_should_flag_undefaulted_fixture_before_defaulted_one() -> None:
     )
 
 
+def test_should_flag_unused_known_fixture_parameter_in_test_file() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "def test_omits_config(tmp_path: Path) -> None:\n"
+        "    command = build_command('module.py', None)\n"
+        "    assert command[-1] == 'module.py'\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert any(
+        "tmp_path" in each_issue for each_issue in issues
+    ), f"Expected unused tmp_path fixture parameter flagged, got: {issues}"
+
+
+def test_should_not_flag_used_known_fixture_parameter() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "def test_includes_config(tmp_path: Path) -> None:\n"
+        "    config_file = tmp_path / 'pyproject.toml'\n"
+        "    assert config_file.name == 'pyproject.toml'\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A referenced fixture parameter must not be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_unused_ordinary_test_parameter() -> None:
+    source = "def test_thing(some_value):\n    return 1\n"
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"Only known pytest fixtures are checked, not arbitrary params, got: {issues}"
+    )
+
+
+def test_should_not_flag_unused_fixture_outside_test_files() -> None:
+    source = "def build(tmp_path):\n    return 1\n"
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"This check applies to test files only, got: {issues}"
+    )
+
+
+def test_should_flag_unused_monkeypatch_fixture_parameter() -> None:
+    source = (
+        "import pytest\n"
+        "def test_env(monkeypatch: pytest.MonkeyPatch) -> None:\n"
+        "    assert build_command('m.py', None)[-1] == 'm.py'\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert any(
+        "monkeypatch" in each_issue for each_issue in issues
+    ), f"Expected unused monkeypatch fixture parameter flagged, got: {issues}"
+
+
+def test_should_count_attribute_access_as_fixture_use() -> None:
+    source = (
+        "import pytest\n"
+        "def test_env(monkeypatch: pytest.MonkeyPatch) -> None:\n"
+        "    monkeypatch.setenv('A', 'B')\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"Attribute access on the fixture counts as a use, got: {issues}"
+    )
+
+
+def test_should_count_nested_function_reference_as_fixture_use() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "def test_board(tmp_path: Path) -> None:\n"
+        "    def inner() -> Path:\n"
+        "        return tmp_path\n"
+        "    assert inner().name\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A reference inside a nested function counts as a use, got: {issues}"
+    )
+
+
+def test_should_not_flag_unused_fixture_in_decorated_fixture_function() -> None:
+    source = (
+        "import pytest\n"
+        "from pathlib import Path\n"
+        "@pytest.fixture\n"
+        "def board(tmp_path: Path) -> int:\n"
+        "    return 1\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A fixture composing another fixture by injection alone is intentional "
+        f"and must not be flagged, got: {issues}"
+    )
+
+
+def test_should_count_comprehension_reference_as_fixture_use() -> None:
+    source = (
+        "import pytest\n"
+        "def test_log_lines(caplog: pytest.LogCaptureFixture) -> None:\n"
+        "    messages = [each_record.message for each_record in caplog.records]\n"
+        "    assert messages == []\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A reference inside a comprehension counts as a use, got: {issues}"
+    )
+
+
+def test_should_not_flag_unused_fixture_in_decorated_test_named_function() -> None:
+    source = (
+        "import pytest\n"
+        "from pathlib import Path\n"
+        "@pytest.fixture\n"
+        "def test_board(tmp_path: Path) -> int:\n"
+        "    return 1\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A @pytest.fixture-decorated function named test_* is a fixture, not a "
+        f"test, and must not be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_fixture_param_on_nested_test_named_helper() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "def test_outer(tmp_path: Path) -> None:\n"
+        "    assert tmp_path\n"
+        "    def test_inner(tmp_path) -> None:\n"
+        "        return None\n"
+        "    test_inner(tmp_path)\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A fixture-named parameter on a function nested inside a test body is a "
+        f"local helper argument pytest never injects, got: {issues}"
+    )
+
+
+def test_should_count_augmented_assignment_as_fixture_reference() -> None:
+    source = "def test_aug(request) -> None:\n    request += 1\n"
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"An augmented assignment to the fixture references it, got: {issues}"
+    )
+
+
+def test_should_count_del_as_fixture_reference() -> None:
+    source = "def test_d(tmp_path: Path) -> None:\n    del tmp_path\n"
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A del of the fixture references it, got: {issues}"
+    )
+
+
+def test_should_flag_unused_fixture_parameter_on_class_method() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "class TestThing:\n"
+        "    def test_method(self, tmp_path: Path) -> None:\n"
+        "        assert 1 == 1\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert any(
+        "tmp_path" in each_issue for each_issue in issues
+    ), f"An unused fixture on a class-body test method must be flagged, got: {issues}"
+
+
+def test_should_flag_unused_fixture_parameter_on_nested_class_method() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "class TestOuter:\n"
+        "    class TestInner:\n"
+        "        def test_method(self, tmp_path: Path) -> None:\n"
+        "            assert 1 == 1\n"
+    )
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert any(
+        "tmp_path" in each_issue for each_issue in issues
+    ), f"An unused fixture on a nested-class test method must be flagged, got: {issues}"
+
+
+def test_should_flag_fixture_when_body_only_plain_assigns_it() -> None:
+    source = "def test_x(tmp_path: Path) -> None:\n    tmp_path = 1\n"
+    issues = code_rules_enforcer.check_unused_known_pytest_fixture_parameters(
+        source, TEST_FILE_PATH
+    )
+    assert any(
+        "tmp_path" in each_issue for each_issue in issues
+    ), f"A plain Store target is not a reference, so tmp_path is unused, got: {issues}"
+
+
+def test_annotation_check_skips_fixture_param_on_function_nested_in_test() -> None:
+    source = (
+        "from pathlib import Path\n"
+        "def test_outer(tmp_path: Path) -> None:\n"
+        "    def inner(tmp_path) -> None:\n"
+        "        return None\n"
+        "    inner(tmp_path)\n"
+    )
+    issues = code_rules_enforcer.check_known_pytest_fixture_annotations(
+        source, TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A fixture-named param on a function nested in a test body is not an "
+        f"injection site, and the correctly annotated outer param is fine, "
+        f"got: {issues}"
+    )
+
+

package/hooks/blocking/test_code_rules_enforcer_cap_meta.py

@@ -77,6 +77,7 @@ KNOWN_UNCAPPED_CHECKS_PENDING_REVIEW: frozenset[str] = frozenset(
         "check_return_annotations",
         "check_skip_decorators_in_tests",
         "check_string_literal_magic",
+        "check_unused_known_pytest_fixture_parameters",
         "check_unused_optional_parameters",
     }
 )

package/hooks/blocking/test_code_rules_enforcer_dead_config_field.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import stat
+import tempfile
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+import pytest
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location("code_rules_enforcer", ENFORCER_PATH)
+assert specification is not None and specification.loader is not None
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_FILE_PATH = "packages/app/services/report.py"
+TEST_FILE_PATH = "packages/app/services/test_report.py"
+MIGRATION_FILE_PATH = "packages/app/migrations/0001_initial.py"
+
+THEME_UPDATE_CONFIG_BODY = (
+    "from dataclasses import dataclass\n"
+    "\n"
+    "@dataclass\n"
+    "class ThemeUpdateConfig:\n"
+    "    portal_url: str\n"
+    "    debug_port: int\n"
+    "    timeout_seconds: int\n"
+)
+
+
+def _strip_read_only_and_retry(
+    removal_function: Callable[[str], object],
+    target_path: str,
+    _exc_info: BaseException,
+) -> None:
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+@pytest.fixture
+def neutral_root() -> Iterator[Path]:
+    """Yield a temp directory whose path carries no ``test_`` segment.
+
+    The enforcer's ``is_test_file`` keys on the full path string, and pytest's
+    own ``tmp_path`` directory name embeds the test name, which would make every
+    synthetic config path look like a test file. A neutral ``mkdtemp`` root
+    mirrors how a production config module path looks.
+    """
+    neutral_directory = Path(tempfile.mkdtemp(prefix="deadcfg-")).resolve()
+    try:
+        yield neutral_directory
+    finally:
+        shutil.rmtree(neutral_directory, onexc=_strip_read_only_and_retry)
+
+
+def _check(source: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_config_dataclass_fields(source, file_path)
+
+
+def _build_config_package(
+    workflow_directory: Path,
+    config_body: str,
+    consumer_body: str,
+) -> Path:
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(config_body, encoding="utf-8")
+    (workflow_directory / "runner.py").write_text(consumer_body, encoding="utf-8")
+    return config_path
+
+
+def test_flags_config_field_read_by_no_production_module(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> None:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Expected dead 'debug_port' flagged, got: {issues}"
+    )
+    assert not any(
+        "'portal_url'" in each_issue or "'timeout_seconds'" in each_issue for each_issue in issues
+    ), f"Fields read in consumer must not be flagged, got: {issues}"
+
+
+def test_does_not_flag_field_read_as_attribute_in_sibling_module(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> None:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.debug_port)\n"
+        "    print(configuration.timeout_seconds)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], f"All fields are read in consumer, none must be flagged, got: {issues}"
+
+
+def test_flags_field_read_only_by_test_module(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(THEME_UPDATE_CONFIG_BODY, encoding="utf-8")
+    test_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def test_debug_port_default() -> None:\n"
+        "    cfg = ThemeUpdateConfig(portal_url='x', debug_port=9222, timeout_seconds=30)\n"
+        "    assert cfg.debug_port == 9222\n"
+        "    assert cfg.portal_url == 'x'\n"
+        "    assert cfg.timeout_seconds == 30\n"
+    )
+    (workflow_directory / "test_config.py").write_text(test_body, encoding="utf-8")
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field read only by test code must still be flagged as dead-in-production, got: {issues}"
+    )
+
+
+def test_ignores_non_config_named_dataclass(neutral_root: Path) -> None:
+    source = (
+        "from dataclasses import dataclass\n"
+        "\n"
+        "@dataclass\n"
+        "class ThemeMetadata:\n"
+        "    title: str\n"
+        "    debug_port: int\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    workflow_directory.mkdir(parents=True)
+    module_path = workflow_directory / "metadata.py"
+    module_path.write_text(source, encoding="utf-8")
+    issues = _check(source, str(module_path))
+    assert issues == [], (
+        f"Non-Config-named dataclasses are outside scope of this check, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_read_via_string_literal(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def read_field(configuration: ThemeUpdateConfig, field_name: str) -> object:\n"
+        "    return getattr(configuration, 'debug_port')\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"String literal getattr read must count as a field read, got: {issues}"
+    )
+
+
+def test_does_not_flag_when_consumer_serializes_whole_instance_via_asdict(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from dataclasses import asdict\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def serialize(configuration: ThemeUpdateConfig) -> dict[str, object]:\n"
+        "    return asdict(configuration)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"asdict reads every field at once, so no field may be flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_when_consumer_reads_instance_dict(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def serialize(configuration: ThemeUpdateConfig) -> dict[str, object]:\n"
+        "    return dict(configuration.__dict__)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"__dict__ read consumes every field at once, so none may be flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_used_only_as_replace_keyword(neutral_root: Path) -> None:
+    consumer_body = (
+        "from dataclasses import replace\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def repoint(configuration: ThemeUpdateConfig) -> ThemeUpdateConfig:\n"
+        "    return replace(configuration, debug_port=9999)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"replace keyword usage of debug_port must count as a read, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_used_only_as_constructor_keyword(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def build() -> ThemeUpdateConfig:\n"
+        "    return ThemeUpdateConfig(portal_url='x', debug_port=1, timeout_seconds=99)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"Constructor keyword arguments name every field, so none may be flagged, got: {issues}"
+    )
+
+
+def test_returns_empty_list_at_file_cap(
+    neutral_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("code_rules_dead_config_field.MAX_SCAN_ROOT_FILE_COUNT", 0)
+    config_path = _build_config_package(
+        neutral_root / "workflow",
+        THEME_UPDATE_CONFIG_BODY,
+        "def noop() -> None:\n    pass\n",
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], f"File cap hit must return [] (cannot prove dead), got: {issues}"
+
+
+def test_returns_empty_list_on_syntax_error(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    workflow_directory.mkdir(parents=True)
+    broken_path = workflow_directory / "config.py"
+    broken_source = "@dataclass\nclass BrokenConfig(\n"
+    broken_path.write_text(broken_source, encoding="utf-8")
+    issues = _check(broken_source, str(broken_path))
+    assert issues == [], f"SyntaxError must return [], got: {issues}"
+
+
+def test_is_skipped_on_test_file_destination() -> None:
+    issues = _check(THEME_UPDATE_CONFIG_BODY, TEST_FILE_PATH)
+    assert issues == [], f"Test file destinations are exempt, got: {issues}"
+
+
+def test_is_skipped_on_migration_file_destination() -> None:
+    issues = _check(THEME_UPDATE_CONFIG_BODY, MIGRATION_FILE_PATH)
+    assert issues == [], f"Migration file destinations are exempt, got: {issues}"
+
+
+def test_real_world_shape_theme_update_config_with_dead_debug_port(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(THEME_UPDATE_CONFIG_BODY, encoding="utf-8")
+    orchestrator_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def build_session(configuration: ThemeUpdateConfig) -> None:\n"
+        "    url = configuration.portal_url\n"
+        "    seconds = configuration.timeout_seconds\n"
+        "    print(url, seconds)\n"
+    )
+    (workflow_directory / "orchestrator.py").write_text(orchestrator_body, encoding="utf-8")
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"debug_port field unused in production must be flagged, got: {issues}"
+    )
+    assert not any(
+        "'portal_url'" in each_issue or "'timeout_seconds'" in each_issue for each_issue in issues
+    ), f"Fields read in orchestrator must not be flagged, got: {issues}"
+
+
+def test_does_not_flag_field_used_only_via_augmented_assignment(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> None:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+        "    configuration.debug_port += 1\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Augmented assignment reads debug_port before writing, so it is not dead, got: {issues}"
+    )
+
+
+def test_flags_field_read_only_via_whole_instance_comparison(neutral_root: Path) -> None:
+    """A field read ONLY via whole-instance comparison IS flagged (accepted limitation).
+
+    Unlike the per-file dead-dataclass-field check, this cross-module check does
+    not suppress on a dataclass-dunder whole-instance read: instance comparison
+    (``left == right``) is not bound to a config instance, and tree-wide one
+    incidental ``==`` anywhere would disable the check on any realistic package.
+    A ``*Config`` field whose only production read is this whole-instance
+    comparison, and that is never read directly, is therefore flagged — a
+    documented, rare limitation.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def is_same(left: ThemeUpdateConfig, right: ThemeUpdateConfig) -> bool:\n"
+        "    return left == right\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field read only via whole-instance comparison is flagged, got: {issues}"
+    )
+
+
+def test_flags_field_read_only_via_whole_instance_stringification(neutral_root: Path) -> None:
+    """A field read ONLY via whole-instance stringification IS flagged (accepted limitation).
+
+    The cross-module check does not suppress on a formatted-string conversion of
+    a whole instance (``f'{configuration}'``): the f-string is not bound to a
+    config instance, and tree-wide one incidental f-string anywhere would disable
+    the check on any realistic package. A ``*Config`` field whose only production
+    read is this whole-instance stringification, and that is never read directly,
+    is therefore flagged — a documented, rare limitation.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def describe(configuration: ThemeUpdateConfig) -> str:\n"
+        "    return f'{configuration}'\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field read only via whole-instance stringification is flagged, got: {issues}"
+    )
+
+
+def test_unrelated_string_method_does_not_suppress_so_dead_field_flagged(
+    neutral_root: Path,
+) -> None:
+    """An unrelated ``.replace(...)`` on a string must not suppress the tree.
+
+    ``"some text".replace("a", "b")`` is a string method, not a ``dataclasses``-
+    qualified reflective consumer, so it does not make the check treat the tree
+    as a whole-instance read. A genuinely dead ``debug_port`` is still flagged.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> str:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+        "    return 'some text'.replace('a', 'b')\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Unrelated string .replace must not suppress, so dead debug_port is flagged, got: {issues}"
+    )
+
+
+def test_dataclasses_qualified_replace_call_suppresses_so_no_field_flagged(
+    neutral_root: Path,
+) -> None:
+    """A ``dataclasses.replace(cfg, ...)`` call suppresses the whole tree.
+
+    A genuine ``dataclasses``-qualified reflective consumer reads every field at
+    once, so the check is suppressed for the whole tree and no field is flagged.
+    """
+    consumer_body = (
+        "import dataclasses\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def repoint(configuration: ThemeUpdateConfig) -> ThemeUpdateConfig:\n"
+        "    return dataclasses.replace(configuration, debug_port=9999)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"dataclasses.replace reads every field at once, so none may be flagged, got: {issues}"
+    )
+
+
+def test_validate_content_dispatch_runs_dead_config_field_check(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(THEME_UPDATE_CONFIG_BODY, encoding="utf-8")
+    (workflow_directory / "runner.py").write_text(
+        "def noop() -> None:\n    pass\n", encoding="utf-8"
+    )
+    issues = code_rules_enforcer.validate_content(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Expected the enforcer dispatch to surface the dead config field, got: {issues}"
+    )