claude-dev-env 1.72.0 → 1.73.0

package/hooks/blocking/code_rules_dead_config_field.py

@@ -1,17 +1,21 @@
-"""Dead config-dataclass field check: cross-module scan for ``*Config`` @dataclass fields.
-
-A config ``@dataclass`` (any class whose name ends in ``"Config"``) is defined
-in one module but constructed and consumed in others, so the per-file dead-field
-check in ``code_rules_dead_dataclass_field`` cannot judge its fields — it skips
-any class that is not constructed in the same file. This check resolves the
-enclosing package tree — the scan root — and flags a ``*Config`` dataclass field
-whose name appears as an attribute read (``obj.field``) in no production module
-anywhere under that root.
+"""Dead config-dataclass field check: cross-module scan for config-like @dataclass fields.
+
+A config-like ``@dataclass`` — any class whose name ends in ``"Config"`` or
+``"Selectors"`` — is defined in one module but constructed and consumed in
+others, so the per-file dead-field check in
+``code_rules_dead_dataclass_field`` cannot judge its fields — it skips any class
+that is not constructed in the same file. This check resolves the enclosing
+package tree — the scan root — and flags a config-like dataclass field whose
+name appears as an attribute read (``obj.field``) in no production module
+anywhere under that root. A selectors dataclass is the same shape as a config
+dataclass: it is bound to a module-level singleton (``binary_selectors =
+BinarySelectors()``) and its fields are read across files, so an unwired
+selector field is caught the same way as a dead config field.
 
 The scan is deliberately conservative to keep false positives near zero:
 
-- Only ``@dataclass`` classes whose name ends in ``"Config"`` participate; other
-  dataclasses are covered by the per-file check.
+- Only ``@dataclass`` classes whose name ends in ``"Config"`` or ``"Selectors"``
+  participate; other dataclasses are covered by the per-file check.
 - Test and migration files are exempt as write destinations, so a field added to
   a config dataclass inside a test is never flagged.
 - Production modules under the scan root are scanned for attribute reads; test
@@ -24,11 +28,11 @@ The scan is deliberately conservative to keep false positives near zero:
   ``replace(cfg, debug_port=1)``), and match-pattern keyword attribute names
   (``case Config(field=found)``). Two field-write forms are excluded because they
   name a field without consuming it: a keyword that writes a field in a constructor
-  of a known ``*Config`` dataclass defined under the scan root
+  of a known config-like dataclass defined under the scan root
   (``ThemeUpdateConfig(debug_port=1)``, excluded per keyword node so a same-named
   keyword on a ``replace`` call stays a read, and a factory function whose name
   merely ends in ``"Config"`` is not excluded), and a self-referential attribute
-  read inside a ``*Config`` field's own default-value expression in the class body
+  read inside a config-like field's own default-value expression in the class body
   whose attribute name equals the field being defined
   (``debug_port: int = source.debug_port``) — a field written only these ways and
   read by no module is the dead-config case this check exists to catch. A default
@@ -54,7 +58,7 @@ suppress on a dataclass-dunder whole-instance read — instance comparison
 (``str(cfg)``/``repr(cfg)``/``format(cfg)``). Those syntactic forms are not bound
 to a config instance, and tree-wide one incidental match anywhere would disable
 the check on any realistic package. The consequence is a documented, rare
-limitation: a ``*Config`` field read ONLY via whole-instance dunder comparison or
+limitation: a config-like field read ONLY via whole-instance dunder comparison or
 stringification, and never read directly anywhere in production, may be flagged.
 The augmented-assignment read mechanism (``cfg.field += 1`` reads ``field``
 before writing it) is precise and remains a counted read.
@@ -87,8 +91,8 @@ from code_rules_shared import (  # noqa: E402
 )
 
 from hooks_constants.dead_config_field_constants import (  # noqa: E402
+    ALL_CONFIG_CLASS_NAME_SUFFIXES,
     ALL_REFLECTIVE_FIELD_CONSUMER_NAMES,
-    CONFIG_CLASS_NAME_SUFFIX,
     DATACLASSES_MODULE_NAME,
     DEAD_CONFIG_FIELD_GUIDANCE,
     MAX_DEAD_CONFIG_FIELD_ISSUES,
@@ -99,16 +103,23 @@ from hooks_constants.dead_config_field_constants import (  # noqa: E402
 
 
 def _is_config_dataclass(class_node: ast.ClassDef) -> bool:
-    """Return whether a class is a @dataclass whose name ends in ``"Config"``.
+    """Return whether a class is a @dataclass whose name ends in a config-like suffix.
+
+    A config-like surface is a ``@dataclass`` whose name ends in ``"Config"`` or
+    ``"Selectors"``. Both shapes are defined in one module, bound to a
+    module-level singleton, and read across files, so the per-file dead-field
+    check cannot judge their fields and the cross-module scan covers them here.
 
     Args:
         class_node: The class definition node to test.
 
     Returns:
         True when the class carries a ``@dataclass`` decorator and its name ends
-        in ``"Config"``.
+        in one of ``ALL_CONFIG_CLASS_NAME_SUFFIXES``.
     """
-    return _is_dataclass(class_node) and class_node.name.endswith(CONFIG_CLASS_NAME_SUFFIX)
+    return _is_dataclass(class_node) and class_node.name.endswith(
+        ALL_CONFIG_CLASS_NAME_SUFFIXES
+    )
 
 
 def _reads_whole_instance_reflectively(tree: ast.Module) -> bool:
@@ -152,18 +163,18 @@ def _reads_whole_instance_reflectively(tree: ast.Module) -> bool:
 
 
 def _config_dataclass_names(tree: ast.Module) -> set[str]:
-    """Return names of ``*Config`` ``@dataclass`` classes defined in a module.
+    """Return names of config-like ``@dataclass`` classes defined in a module.
 
     A constructor-keyword exclusion fires only for a callee that names a genuine
-    config dataclass, so the caller first gathers the config dataclass names a
-    module defines, then unions those names across the scan root.
+    config-like dataclass, so the caller first gathers the config-like dataclass
+    names a module defines, then unions those names across the scan root.
 
     Args:
         tree: The parsed module to inspect.
 
     Returns:
         Every class name in the module that is a ``@dataclass`` whose name ends in
-        the config class name suffix.
+        one of ``ALL_CONFIG_CLASS_NAME_SUFFIXES``.
     """
     config_dataclass_names: set[str] = set()
     for each_node in ast.walk(tree):
@@ -175,22 +186,22 @@ def _config_dataclass_names(tree: ast.Module) -> set[str]:
 def _call_constructs_config_class(
     call_node: ast.Call, all_known_config_class_names: set[str]
 ) -> bool:
-    """Return whether a call constructs a known ``*Config`` dataclass.
+    """Return whether a call constructs a known config-like dataclass.
 
-    A call whose callee names a ``*Config`` dataclass defined under the scan root —
+    A call whose callee names a config-like dataclass defined under the scan root —
     ``AppInfoConfig(...)`` or a qualified ``module.AppInfoConfig(...)`` —
-    constructs a config instance, and its keyword arguments write the named fields
+    constructs the instance, and its keyword arguments write the named fields
     rather than read them. A factory function whose name merely ends in
-    ``"Config"`` (``getThemeConfig(...)``) is not a known config dataclass, so its
-    keyword arguments stay genuine reads.
+    ``"Config"`` (``getThemeConfig(...)``) is not a known config-like dataclass, so
+    its keyword arguments stay genuine reads.
 
     Args:
         call_node: The call expression to test.
-        all_known_config_class_names: Names of ``*Config`` dataclasses defined under
+        all_known_config_class_names: Names of config-like dataclasses defined under
             the scan root.
 
     Returns:
-        True when the callee names a known ``*Config`` dataclass.
+        True when the callee names a known config-like dataclass.
     """
     callee_node = call_node.func
     if isinstance(callee_node, ast.Name):
@@ -203,7 +214,7 @@ def _call_constructs_config_class(
 def _config_constructor_keyword_node_ids(
     tree: ast.Module, all_known_config_class_names: set[str]
 ) -> set[int]:
-    """Return ids of keyword nodes that write fields in a known ``*Config`` constructor.
+    """Return ids of keyword nodes that write fields in a known config-like constructor.
 
     A keyword in an ``AppInfoConfig(field=value)`` call sets ``field`` rather than
     reading it, so its node id is collected for the caller to exclude. The
@@ -213,11 +224,11 @@ def _config_constructor_keyword_node_ids(
 
     Args:
         tree: The parsed module to inspect.
-        all_known_config_class_names: Names of ``*Config`` dataclasses defined under
+        all_known_config_class_names: Names of config-like dataclasses defined under
             the scan root.
 
     Returns:
-        The ``id()`` of every keyword node passed to a known ``*Config``
+        The ``id()`` of every keyword node passed to a known config-like
         constructor call.
     """
     constructor_keyword_node_ids: set[int] = set()
@@ -237,7 +248,7 @@ def _self_referential_default_attribute_node_ids(
 ) -> set[int]:
     """Return ids of attribute reads in a default whose name equals the field.
 
-    Walks a ``*Config`` field's default-value expression and collects the ``id()``
+    Walks a config-like field's default-value expression and collects the ``id()``
     of each ``ast.Attribute`` read whose ``.attr`` equals ``field_name``. Such a
     read — ``sound_upload_timeout_ms: int = submission_timing.sound_upload_timeout_ms``
     — names the field being defined inside the class body, so it is not a consumer
@@ -261,15 +272,15 @@ def _self_referential_default_attribute_node_ids(
 
 
 def _config_field_default_value_nodes(tree: ast.Module) -> set[int]:
-    """Return ids of self-referential attribute reads in ``*Config`` field defaults.
+    """Return ids of self-referential attribute reads in config-like field defaults.
 
     A field default such as ``sound_upload_timeout_ms: int =``
     ``submission_timing.sound_upload_timeout_ms`` is an attribute read whose name
-    matches the field being defined. That self-referential read inside the config
-    class body is not a consumer of the field, so its node id is collected here for
-    the caller to exclude from the attribute-read set. Only the attribute read
-    whose ``.attr`` equals the field name is collected; a default that sources a
-    differently-named field on another object
+    matches the field being defined. That self-referential read inside the
+    config-like class body is not a consumer of the field, so its node id is
+    collected here for the caller to exclude from the attribute-read set. Only the
+    attribute read whose ``.attr`` equals the field name is collected; a default
+    that sources a differently-named field on another object
     (``timeout_ms: int = other_config.base_timeout``) leaves that read counted, so
     ``base_timeout`` stays a live consumer.
 
@@ -278,7 +289,7 @@ def _config_field_default_value_nodes(tree: ast.Module) -> set[int]:
 
     Returns:
         The ``id()`` of every self-referential attribute read within the
-        default-value expression of a field declared in a ``*Config`` dataclass
+        default-value expression of a field declared in a config-like dataclass
         body.
     """
     default_value_node_ids: set[int] = set()
@@ -311,14 +322,14 @@ def _attribute_read_names_in_tree(
     contributes ``"debug_port"``), and ``ast.MatchClass.kwd_attrs`` names (so
     ``case Config(field=x)`` contributes ``"field"``). Two field-write forms are
     excluded because they name a field without consuming it: a keyword that writes
-    a field in a known ``*Config`` constructor (``AppInfoConfig(field=value)``,
+    a field in a known config-like constructor (``AppInfoConfig(field=value)``,
     excluded per keyword node so a same-named ``replace`` keyword stays a read),
-    and a self-referential attribute read inside a ``*Config`` dataclass field's
+    and a self-referential attribute read inside a config-like dataclass field's
     own default-value expression (``field: int = source.field`` in the class body,
     excluded only when the read name equals the field name) — counting either
     would hide a field that is written but read by no module. A keyword passed to a
-    factory function whose name merely ends in ``"Config"`` is not a known config
-    constructor, so it stays a read. The boolean reports whether the module
+    factory function whose name merely ends in ``"Config"`` is not a known
+    config-like constructor, so it stays a read. The boolean reports whether the module
     suppresses the dead-field check, which it does only when it reflectively reads a
     whole instance — a bare or ``dataclasses``-qualified
     ``asdict``/``astuple``/``fields``/``replace``/``vars`` call, or an
@@ -328,14 +339,14 @@ def _attribute_read_names_in_tree(
 
     Args:
         tree: The parsed module to inspect.
-        all_known_config_class_names: Names of ``*Config`` dataclasses defined under
+        all_known_config_class_names: Names of config-like dataclasses defined under
             the scan root, used to scope the constructor-keyword exclusion to
-            genuine config constructors.
+            genuine config-like constructors.
 
     Returns:
         A (read_names, suppresses_dead_field_check) pair. The name set is every
         attribute name the module reads via the mechanisms above, excluding known
-        ``*Config`` constructor keyword nodes and self-referential config-field
+        config-like constructor keyword nodes and self-referential config-like-field
         default-value attribute reads; suppresses_dead_field_check is True only when
         a reflective whole-instance read is present.
     """
@@ -418,8 +429,8 @@ def _all_production_read_names_under_root(
     Reads and AST-parses every production ``.py`` module under ``scan_root``
     (excluding test and migration files) at most once: the module sources are
     materialized once, a first pass over the cached sources gathers every
-    ``*Config`` dataclass name defined under the root so the constructor-keyword
-    exclusion fires only for a genuine config constructor, and a second pass over
+    config-like dataclass name defined under the root so the constructor-keyword
+    exclusion fires only for a genuine config-like constructor, and a second pass over
     the same cached sources collects attribute reads. The written module's
     post-edit content replaces its on-disk text so the current edit is included.
     Scanning stops at the configured file cap. A module that reflectively reads a
@@ -472,15 +483,17 @@ def _all_production_read_names_under_root(
 def check_dead_config_dataclass_fields(
     content: str, file_path: str, full_file_content: str | None = None
 ) -> list[str]:
-    """Flag a ``*Config`` @dataclass field read by no production module in the package tree.
+    """Flag a config-like @dataclass field read by no production module in the package tree.
 
     Runs a cross-module scan restricted to ``@dataclass`` classes whose name ends
-    in ``"Config"``. For each such config dataclass in the written file, every
+    in ``"Config"`` or ``"Selectors"`` — both are config-like surfaces bound to a
+    module-level singleton and read across files. For each such dataclass in the
+    written file, every
     instance field whose name does not appear as an attribute read (``obj.field``),
     augmented-assignment target (``cfg.field += 1``), string literal,
     non-constructor keyword-argument name (``replace`` keyword), or match-pattern
     keyword attribute in any production module under the enclosing scan root is
-    flagged as dead. A keyword that writes a field in a ``*Config`` constructor
+    flagged as dead. A keyword that writes a field in a config-like constructor
     (``ThemeUpdateConfig(debug_port=1)``) is a write, not a read, so it does not
     clear a field — a field set by a constructor keyword and read by no module is
     flagged. When any production module under the scan root reflectively
@@ -507,10 +520,10 @@ def check_dead_config_dataclass_fields(
             Edit, or None for a Write where ``content`` is already the whole file.
 
     Returns:
-        One violation message per dead config dataclass field, capped at the
+        One violation message per dead config-like dataclass field, capped at the
         configured maximum. Returns an empty list when the file is exempt, no
-        qualifying config dataclass is found, the scan root exceeds the file cap,
-        or a SyntaxError prevents parsing.
+        qualifying config-like dataclass is found, the scan root exceeds the file
+        cap, or a SyntaxError prevents parsing.
     """
     if is_test_file(file_path):
         return []
@@ -547,7 +560,7 @@ def check_dead_config_dataclass_fields(
             if each_field_name in all_read_names:
                 continue
             all_issues.append(
-                f"Line {each_field_line}: config dataclass field {each_field_name!r}"
+                f"Line {each_field_line}: dataclass field {each_field_name!r}"
                 f" on {each_class.name} - {DEAD_CONFIG_FIELD_GUIDANCE}"
             )
             if len(all_issues) >= MAX_DEAD_CONFIG_FIELD_ISSUES: