claude-dev-env 1.58.0 → 1.60.0

package/hooks/blocking/code_rules_dead_dataclass_field.py

@@ -0,0 +1,319 @@
+"""Dead dataclass-field check: a @dataclass field assigned but never read in the same file."""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    is_migration_file,
+    is_test_file,
+)
+
+from hooks_constants.dead_dataclass_field_constants import (  # noqa: E402
+    ALL_DATACLASS_DECORATOR_NAMES,
+    ALL_WHOLE_INSTANCE_STRINGIFY_NAMES,
+    ATTRGETTER_FUNCTION_NAME,
+    CLASSVAR_ANNOTATION_NAME,
+    DEAD_DATACLASS_FIELD_GUIDANCE,
+    GETATTR_FUNCTION_NAME,
+    GETATTR_NAME_ARGUMENT_MINIMUM,
+    MAX_DEAD_DATACLASS_FIELD_ISSUES,
+    ALL_REFLECTIVE_FIELD_CONSUMER_NAMES,
+    WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME,
+)
+
+
+def _decorator_calls_dataclass(decorator_node: ast.expr) -> bool:
+    """Return whether a decorator expression applies @dataclass (bare or called)."""
+    target_node = (
+        decorator_node.func if isinstance(decorator_node, ast.Call) else decorator_node
+    )
+    if isinstance(target_node, ast.Name):
+        return target_node.id in ALL_DATACLASS_DECORATOR_NAMES
+    if isinstance(target_node, ast.Attribute):
+        return target_node.attr in ALL_DATACLASS_DECORATOR_NAMES
+    return False
+
+
+def _is_dataclass(class_node: ast.ClassDef) -> bool:
+    return any(
+        _decorator_calls_dataclass(each_decorator)
+        for each_decorator in class_node.decorator_list
+    )
+
+
+def _annotation_is_classvar(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Name):
+        return annotation_node.id == CLASSVAR_ANNOTATION_NAME
+    if isinstance(annotation_node, ast.Attribute):
+        return annotation_node.attr == CLASSVAR_ANNOTATION_NAME
+    if isinstance(annotation_node, ast.Subscript):
+        return _annotation_is_classvar(annotation_node.value)
+    return False
+
+
+def _dataclass_field_definitions(class_node: ast.ClassDef) -> list[tuple[str, int]]:
+    """Return (field_name, line) for each instance field declared in a dataclass body."""
+    fields: list[tuple[str, int]] = []
+    for each_statement in class_node.body:
+        if not isinstance(each_statement, ast.AnnAssign):
+            continue
+        if not isinstance(each_statement.target, ast.Name):
+            continue
+        if _annotation_is_classvar(each_statement.annotation):
+            continue
+        fields.append((each_statement.target.id, each_statement.lineno))
+    return fields
+
+
+def _string_constant_literal(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _dynamic_access_names(tree: ast.Module) -> tuple[set[str], bool]:
+    """Return literal attribute-name reads and whether the check must be suppressed.
+
+    Walks every ``getattr(obj, "name")`` and ``operator.attrgetter("a", "b")``
+    call, contributing each literal string name as a read attribute name —
+    ``getattr`` names its attribute in the second positional argument while
+    ``attrgetter`` names one attribute per positional argument. A non-literal
+    name argument, or any reflective whole-instance consumer (``asdict``,
+    ``astuple``, ``fields``, ``replace``, ``vars``) that reads every field at
+    once, means a field cannot be proven unread, so the boolean signals the
+    caller to suppress the check for the whole file.
+    """
+    literal_names: set[str] = set()
+    should_suppress_check = False
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        function_node = each_node.func
+        function_name = None
+        if isinstance(function_node, ast.Name):
+            function_name = function_node.id
+        elif isinstance(function_node, ast.Attribute):
+            function_name = function_node.attr
+        if function_name in ALL_REFLECTIVE_FIELD_CONSUMER_NAMES:
+            should_suppress_check = True
+            continue
+        if function_name not in {GETATTR_FUNCTION_NAME, ATTRGETTER_FUNCTION_NAME}:
+            continue
+        string_arguments = [
+            argument
+            for argument in each_node.args
+            if not isinstance(argument, ast.Starred)
+        ]
+        if function_name == GETATTR_FUNCTION_NAME:
+            name_arguments = (
+                [string_arguments[1]]
+                if len(string_arguments) >= GETATTR_NAME_ARGUMENT_MINIMUM
+                else []
+            )
+        else:
+            name_arguments = string_arguments
+        if not name_arguments:
+            should_suppress_check = True
+            continue
+        for each_name_argument in name_arguments:
+            literal_name = _string_constant_literal(each_name_argument)
+            if literal_name is None:
+                should_suppress_check = True
+            else:
+                literal_names.add(literal_name)
+    return literal_names, should_suppress_check
+
+
+def _augmented_assignment_attribute_names(tree: ast.Module) -> set[str]:
+    """Return attribute names that an augmented assignment reads before writing.
+
+    ``obj.field += value`` parses to an ``ast.Attribute`` target in Store
+    context, yet ``+=`` reads the current attribute value before storing the
+    result, so the target attribute counts as a read.
+    """
+    augmented_read_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.AugAssign):
+            continue
+        if isinstance(each_node.target, ast.Attribute):
+            augmented_read_names.add(each_node.target.attr)
+    return augmented_read_names
+
+
+def _attribute_read_names(tree: ast.Module) -> tuple[set[str], bool]:
+    """Return literal attribute-name reads and whether the check must be suppressed.
+
+    Walks every attribute read (Load context) and every augmented-assignment
+    target in the module, contributing each attribute name as a read name —
+    ``obj.field += value`` reads ``field`` before writing it. A read of
+    ``__dict__`` consumes every field of an instance at once, so it cannot prove
+    any single field unread and the boolean signals the caller to suppress the
+    check for the whole file.
+    """
+    read_names: set[str] = _augmented_assignment_attribute_names(tree)
+    should_suppress_check = False
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Attribute) or not isinstance(
+            each_node.ctx, ast.Load
+        ):
+            continue
+        if each_node.attr == WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME:
+            should_suppress_check = True
+            continue
+        read_names.add(each_node.attr)
+    return read_names, should_suppress_check
+
+
+def _match_pattern_attribute_names(tree: ast.Module) -> set[str]:
+    """Return field names that a class pattern reads in a ``match`` statement.
+
+    A class pattern ``case Row(url=found):`` reads the ``url`` field through
+    ``ast.MatchClass.kwd_attrs``, so each keyword-pattern attribute name counts
+    as a read name even though it never appears as an attribute access.
+    """
+    matched_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.MatchClass):
+            matched_names.update(each_node.kwd_attrs)
+    return matched_names
+
+
+def _exported_names(tree: ast.Module) -> set[str]:
+    """Return names listed in a module-level ``__all__`` literal."""
+    exported: set[str] = set()
+    for each_node in tree.body:
+        if not isinstance(each_node, ast.Assign):
+            continue
+        targets_all = any(
+            isinstance(each_target, ast.Name) and each_target.id == "__all__"
+            for each_target in each_node.targets
+        )
+        if not targets_all:
+            continue
+        if isinstance(each_node.value, (ast.List, ast.Tuple, ast.Set)):
+            for each_element in each_node.value.elts:
+                literal_name = _string_constant_literal(each_element)
+                if literal_name is not None:
+                    exported.add(literal_name)
+    return exported
+
+
+def _constructed_class_names(tree: ast.Module) -> set[str]:
+    """Return names of classes instantiated by a direct call anywhere in the module."""
+    constructed: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Call) and isinstance(each_node.func, ast.Name):
+            constructed.add(each_node.func.id)
+    return constructed
+
+
+def _is_whole_instance_stringify_call(node: ast.AST) -> bool:
+    """Return whether a call stringifies a whole instance via ``str``/``repr``/``format``."""
+    if not isinstance(node, ast.Call):
+        return False
+    function_node = node.func
+    if isinstance(function_node, ast.Name):
+        return function_node.id in ALL_WHOLE_INSTANCE_STRINGIFY_NAMES
+    if isinstance(function_node, ast.Attribute):
+        return function_node.attr in ALL_WHOLE_INSTANCE_STRINGIFY_NAMES
+    return False
+
+
+def _uses_dataclass_dunder_field_reads(tree: ast.Module) -> bool:
+    """Return whether the file relies on auto-generated dataclass dunders to read fields.
+
+    ``@dataclass`` synthesizes ``__eq__`` (and ``__lt__``/``__hash__`` under
+    ``order``/``frozen``) plus the always-present ``__repr__``, each of which
+    reads every field without naming it as an attribute access. Comparing two
+    instances, placing instances in a set or dict, formatted-string conversion,
+    or stringifying a whole instance therefore reads fields the static scan
+    cannot otherwise observe, so the check is suppressed for the whole file.
+    """
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Compare):
+            return True
+        if isinstance(each_node, (ast.Set, ast.SetComp, ast.Dict, ast.DictComp)):
+            return True
+        if isinstance(each_node, ast.FormattedValue):
+            return True
+        if _is_whole_instance_stringify_call(each_node):
+            return True
+    return False
+
+
+def check_dead_dataclass_fields(
+    content: str, file_path: str, full_file_content: str | None = None
+) -> list[str]:
+    """Flag a @dataclass field that the same file constructs but never reads.
+
+    A field is dead when its dataclass is instantiated somewhere in the file
+    (so the class is live), the field name never appears as an attribute read,
+    an augmented-assignment target, a class-pattern keyword, or a literal
+    ``getattr``/``attrgetter`` access anywhere in the file, and the file contains
+    no non-literal dynamic access, reflective whole-instance consumer
+    (``asdict``, ``astuple``, ``fields``, ``replace``, ``vars``), ``__dict__``
+    read, or auto-generated dataclass dunder field read (comparison, set/dict
+    membership, or whole-instance stringification) that could read it
+    indirectly. Whole-file analysis runs against ``full_file_content`` when
+    supplied so an Edit fragment is judged against the reconstructed post-edit
+    file.
+
+    Args:
+        content: The new content under validation (Edit fragment or whole file).
+        file_path: The destination path, used for the test/registry exemptions.
+        full_file_content: The reconstructed post-edit whole-file content for an
+            Edit, or None for a Write where ``content`` is already the whole file.
+
+    Returns:
+        One violation message per dead dataclass field, capped at the configured
+        maximum.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_migration_file(file_path):
+        return []
+    effective_content = content if full_file_content is None else full_file_content
+    try:
+        tree = ast.parse(effective_content)
+    except SyntaxError:
+        return []
+    if _uses_dataclass_dunder_field_reads(tree):
+        return []
+    dynamic_literal_names, dynamic_access_suppresses_check = _dynamic_access_names(tree)
+    attribute_read_names, instance_dict_suppresses_check = _attribute_read_names(tree)
+    if dynamic_access_suppresses_check or instance_dict_suppresses_check:
+        return []
+    read_names = (
+        attribute_read_names
+        | dynamic_literal_names
+        | _match_pattern_attribute_names(tree)
+        | _exported_names(tree)
+    )
+    constructed_class_names = _constructed_class_names(tree)
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.ClassDef) or not _is_dataclass(each_node):
+            continue
+        if each_node.name not in constructed_class_names:
+            continue
+        for each_field_definition in _dataclass_field_definitions(each_node):
+            field_name, field_line = each_field_definition
+            if field_name in read_names:
+                continue
+            issues.append(
+                f"Line {field_line}: dataclass field {field_name!r} on {each_node.name}"
+                f" - {DEAD_DATACLASS_FIELD_GUIDANCE}"
+            )
+            if len(issues) >= MAX_DEAD_DATACLASS_FIELD_ISSUES:
+                return issues
+    return issues

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -0,0 +1,321 @@
+"""Dead module-level constant check for dedicated constants modules.
+
+A constants module (`*_constants.py`, or any module under a ``config/``
+directory) exists to export named values to importer modules elsewhere in the
+project, so a constant defined there is never proven dead by a single-file scan
+alone. This check resolves the enclosing package tree — the scan root — and
+flags an UPPER_SNAKE constant defined in the written module whose name appears
+in no ``.py`` module anywhere under that root: not as an imported name, not as a
+read, not as a re-export. That is the ``MEDIUM_TEXT``-style dead constant the
+CODE_RULES §9.8 dead-code rule targets, caught at Write/Edit time before the
+unused constant lands.
+
+The scan is deliberately conservative to keep false positives near zero:
+
+- Only dedicated constants modules participate; ordinary production modules,
+  whose file-global constants are governed by the use-count rule, are skipped.
+- A module declaring ``__all__`` is skipped: the author has named its export
+  surface explicitly, so a name listed there is live by declaration and a name
+  absent there is the author's stated intent, neither of which this check second
+  guesses.
+- A constant is live when its name appears anywhere under the scan root —
+  imported, read, listed in ``__all__``, or referenced in a string annotation —
+  in any ``.py`` module, including the constants module itself.
+- Test modules under the scan root still count as references, so a constant used
+  only by a test stays live.
+"""
+
+import ast
+import os
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    is_migration_file,
+    is_test_file,
+)
+
+from hooks_constants.dead_module_constant_constants import (  # noqa: E402
+    CONFIG_DIRECTORY_SEGMENT,
+    CONSTANTS_MODULE_SUFFIX,
+    DEAD_MODULE_CONSTANT_GUIDANCE,
+    DUNDER_ALL_NAME,
+    DUNDER_INIT_FILENAME,
+    MAX_DEAD_MODULE_CONSTANT_ISSUES,
+    MAX_SCAN_ROOT_FILE_COUNT,
+    MINIMUM_UPPER_SNAKE_LENGTH,
+    PYTHON_SOURCE_SUFFIX,
+)
+
+
+def _is_dedicated_constants_module(file_path: str) -> bool:
+    """Return whether a path is a dedicated constants module.
+
+    A dedicated constants module is one whose filename ends in
+    ``_constants.py`` or whose path includes a ``config`` directory segment.
+    These modules export named values to importers, so their constants need a
+    cross-module scan to judge liveness.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True for a constants-suffixed module or a module under ``config/``.
+    """
+    normalized_path = file_path.replace("\\", "/").lower()
+    if normalized_path.endswith(CONSTANTS_MODULE_SUFFIX):
+        return True
+    path_segments = normalized_path.split("/")
+    return CONFIG_DIRECTORY_SEGMENT in path_segments[:-1]
+
+
+def _is_upper_snake_name(name: str) -> bool:
+    """Return whether a name is an UPPER_SNAKE_CASE constant identifier."""
+    if len(name) < MINIMUM_UPPER_SNAKE_LENGTH:
+        return False
+    if not name.replace("_", "").isalnum():
+        return False
+    return name == name.upper() and any(each_char.isalpha() for each_char in name)
+
+
+def _module_constant_definitions(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return (name, line) for each module-scope UPPER_SNAKE constant assignment.
+
+    Both plain assignments (``NAME = value``) and annotated assignments
+    (``NAME: type = value``) at module scope are collected. A name bound more
+    than once keeps the line of its first binding.
+
+    Args:
+        tree: The parsed constants module.
+
+    Returns:
+        One (name, line) pair per distinct module-scope constant, in source
+        order.
+    """
+    line_by_name: dict[str, int] = {}
+    for each_statement in tree.body:
+        targets: list[ast.expr] = []
+        if isinstance(each_statement, ast.Assign):
+            targets = list(each_statement.targets)
+        elif isinstance(each_statement, ast.AnnAssign) and each_statement.value is not None:
+            targets = [each_statement.target]
+        for each_target in targets:
+            if not isinstance(each_target, ast.Name):
+                continue
+            if not _is_upper_snake_name(each_target.id):
+                continue
+            if each_target.id not in line_by_name:
+                line_by_name[each_target.id] = each_statement.lineno
+    return list(line_by_name.items())
+
+
+def _statement_binds_dunder_all(statement: ast.stmt) -> bool:
+    """Return whether a single statement assigns or annotates ``__all__``."""
+    if isinstance(statement, ast.Assign):
+        return any(
+            isinstance(each_target, ast.Name) and each_target.id == DUNDER_ALL_NAME
+            for each_target in statement.targets
+        )
+    return (
+        isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and statement.target.id == DUNDER_ALL_NAME
+    )
+
+
+def _module_declares_dunder_all(tree: ast.Module) -> bool:
+    """Return whether the module body assigns or annotates ``__all__``."""
+    return any(_statement_binds_dunder_all(each_node) for each_node in tree.body)
+
+
+def _referenced_names_in_source(source: str, load_only: bool = False) -> set[str]:
+    """Return every name a module references — imported, read, or re-exported.
+
+    Collects imported binding names, ``from`` import member names, name
+    references, attribute roots, and string literals (so a name listed in an
+    ``__all__`` literal or named in a string annotation counts as a reference).
+    A module that fails to parse contributes no names. With ``load_only`` set,
+    only ``Load``-context names count, so a constant's own assignment target in
+    the module being judged does not count as a reference to itself.
+
+    Args:
+        source: The full text of a ``.py`` module under the scan root.
+        load_only: When True, count only ``Load``-context name references,
+            excluding ``Store``/``Del`` targets. Used for the written constants
+            module so a definition is not mistaken for its own consumer.
+
+    Returns:
+        The set of names the module references.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    referenced_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Name):
+            if load_only and not isinstance(each_node.ctx, ast.Load):
+                continue
+            referenced_names.add(each_node.id)
+        elif isinstance(each_node, ast.Import | ast.ImportFrom):
+            for each_alias in each_node.names:
+                referenced_names.add(each_alias.asname or each_alias.name)
+                referenced_names.add(each_alias.name)
+        elif isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            referenced_names.add(each_node.value)
+    return referenced_names
+
+
+def _scan_root_for_constants_module(file_path: str) -> Path:
+    """Return the directory tree to scan for references to the module's constants.
+
+    For a constants module inside a package subdirectory
+    (``pkg/foo_constants.py``), the scan root is the package's parent, so an
+    importer one directory up (``pkg/../consumer.py``) is in scope. For a
+    constants module at the top of a directory, the scan root is that directory.
+    A ``config/`` module's scan root is the parent of the ``config`` directory.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        The absolute directory to scan recursively for references.
+    """
+    written_path = Path(file_path).resolve()
+    enclosing_directory = written_path.parent
+    if enclosing_directory.name.lower() == CONFIG_DIRECTORY_SEGMENT:
+        return enclosing_directory.parent
+    if (enclosing_directory / DUNDER_INIT_FILENAME).is_file():
+        return enclosing_directory.parent
+    return enclosing_directory
+
+
+def _all_referenced_names_under_root(
+    scan_root: Path,
+    written_path: Path,
+    written_content: str,
+) -> tuple[set[str], bool]:
+    """Return referenced names under the scan root and whether the file cap was hit.
+
+    The written module's on-disk text is replaced by ``written_content`` so the
+    post-edit view is judged, never the stale disk copy. Sibling modules are
+    read from disk. Reading stops after the configured file cap so a write under
+    an unexpectedly large tree cannot stall the hook; the boolean signals the
+    caller to treat that case as "cannot prove dead".
+
+    Args:
+        scan_root: The directory tree to scan.
+        written_path: The resolved path of the module being written.
+        written_content: The post-edit text of the written module.
+
+    Returns:
+        A (referenced_names, cap_was_hit) pair. The name set is the union across
+        every scanned module; cap_was_hit is True when the scan stopped at the
+        configured file cap before scanning the whole tree.
+    """
+    all_referenced_names = _referenced_names_in_source(written_content, load_only=True)
+    written_path_key = os.path.normcase(str(written_path))
+    scanned_file_count = 1
+    for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
+        if not each_path.is_file():
+            continue
+        if os.path.normcase(str(each_path.resolve())) == written_path_key:
+            continue
+        scanned_file_count += 1
+        if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
+            return all_referenced_names, True
+        try:
+            sibling_source = each_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        all_referenced_names |= _referenced_names_in_source(sibling_source)
+    return all_referenced_names, False
+
+
+def _module_is_exempt_from_constant_check(file_path: str) -> bool:
+    """Return whether a path is exempt from the dead module-constant check.
+
+    Test modules and migration modules are exempt, and any module that is not a
+    dedicated constants module is out of scope because its file-global constants
+    are governed by the use-count rule instead.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True when the dead module-constant check must not run on this path.
+    """
+    if is_test_file(file_path):
+        return True
+    if is_migration_file(file_path):
+        return True
+    return not _is_dedicated_constants_module(file_path)
+
+
+def check_dead_module_constants(
+    content: str,
+    file_path: str,
+    full_file_content: str | None = None,
+) -> list[str]:
+    """Flag an UPPER_SNAKE constant in a constants module read by no module.
+
+    Runs only on a dedicated constants module (``*_constants.py`` or a module
+    under ``config/``); every other production module's file-global constants
+    are governed by the use-count rule instead. A constant is dead when its name
+    appears in no ``.py`` module anywhere under the enclosing package tree — not
+    imported, not read, not listed in an ``__all__`` literal, not named in a
+    string annotation. A module declaring its own ``__all__`` is skipped so the
+    author's explicit export surface is never second-guessed. Whole-file
+    analysis runs against ``full_file_content`` when supplied so an Edit fragment
+    is judged against the reconstructed post-edit file.
+
+    Args:
+        content: The new content under validation (Edit fragment or whole file).
+        file_path: The destination path, used for the constants-module gate and
+            the test/registry exemptions.
+        full_file_content: The reconstructed post-edit whole-file content for an
+            Edit, or None for a Write where ``content`` is already the whole file.
+
+    Returns:
+        One violation message per dead module-level constant, capped at the
+        configured maximum.
+    """
+    if _module_is_exempt_from_constant_check(file_path):
+        return []
+    effective_content = content if full_file_content is None else full_file_content
+    try:
+        tree = ast.parse(effective_content)
+    except SyntaxError:
+        return []
+    if _module_declares_dunder_all(tree):
+        return []
+    constant_definitions = _module_constant_definitions(tree)
+    if not constant_definitions:
+        return []
+    scan_root = _scan_root_for_constants_module(file_path)
+    written_path = Path(file_path).resolve()
+    all_referenced_names, cap_was_hit = _all_referenced_names_under_root(
+        scan_root,
+        written_path,
+        effective_content,
+    )
+    if cap_was_hit:
+        return []
+    issues: list[str] = []
+    for each_name, each_line in constant_definitions:
+        if each_name in all_referenced_names:
+            continue
+        issues.append(
+            f"Line {each_line}: module-level constant {each_name!r}"
+            f" - {DEAD_MODULE_CONSTANT_GUIDANCE}"
+        )
+        if len(issues) >= MAX_DEAD_MODULE_CONSTANT_ISSUES:
+            break
+    return issues