claude-dev-env 1.77.0 → 1.78.0

package/hooks/blocking/CLAUDE.md

@@ -29,6 +29,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
 | `code_rules_dead_dataclass_field.py` | Dataclass fields with no consuming references |
 | `code_rules_dead_module_constant.py` | `UPPER_SNAKE` constants in `*_constants.py` modules with no importers |
+| `code_rules_dead_split_branch.py` | A conditional whose falsy branch is unreachable because the tested value comes from a separator `str.split()`, which never returns an empty list |
 | `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
 | `code_rules_duplicate_body.py` | A function body copied from a sibling module, or a helper body inlined as a block inside a larger function in the same file |
 | `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style; printf tokens in `str.format`-logger messages |
@@ -37,6 +38,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |
 | `code_rules_optional_params.py` | No optional parameters where a required one would do |
 | `code_rules_orphan_css_class.py` | CSS class attributes in Python markup with no matching `.<class>` selector |
+| `code_rules_paired_test.py` | A public function omitted by a module's established paired test suite must get a behavioral test |
 | `code_rules_path_utils.py` | Path utility helpers shared across check modules |
 | `code_rules_paths_syspath.py` | `sys.path.insert` must be guarded |
 | `code_rules_probe_chains.py` | Probe-chain detection logic |
@@ -44,7 +46,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_probe_recording.py` | Probe recording utilities |
 | `code_rules_scope_binding.py` | Scope/binding analysis utilities |
 | `code_rules_shared.py` | Shared dataclasses and helpers used by multiple check modules |
-| `code_rules_string_magic.py` | Magic string detection with masking and f-string support |
+| `code_rules_string_magic.py` | Magic string detection with masking and f-string support; whitespace-only indentation literals in function bodies |
 | `code_rules_test_assertions.py` | Test assertion style rules |
 | `code_rules_test_branching_except.py` | No bare or broad `except` in test branches |
 | `code_rules_test_isolation.py` | Tests must not rely on home-dir or temp-dir side effects |

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -16,18 +16,26 @@ 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 the scan reaches —
-  imported, read, listed in ``__all__``, or referenced in a string annotation —
-  in any ``.py`` module, including the constants module itself.
+- A module declaring ``__all__`` narrows the check to the constants its
+  ``__all__`` list names — the explicit export surface. Each exported constant
+  must be imported or read by some other module, since a name an author exports
+  yet no module consumes is dead by §9.8; the module's own ``__all__`` entry
+  never counts as that consumer. A constant the module defines but ``__all__``
+  omits is the author's stated private value and is left alone.
+- A constant is live when its name appears in another ``.py`` module the scan
+  reaches — imported, read, listed in that module's ``__all__``, or referenced
+  in a string annotation — or when the constants module itself reads it in code;
+  a name listed only in the constants module's own ``__all__`` does not keep an
+  exported constant live.
 - When the package-tree scan leaves a constant unreferenced, the scan widens to
-  the repository root (the nearest ``.git`` ancestor) so a consumer in a sibling
-  tree of the same repository counts; a module outside any repository is judged
-  on the package-tree scan alone. The widened pass skips the package subtree the
-  first pass already covered, so no file is read twice.
+  the repository root (the nearest ``.git`` ancestor). The widened pass counts a
+  sibling-tree reference only when a module imports the name through a
+  ``from <module> import`` whose final dotted segment equals the written
+  module's filename stem, so a genuine cross-tree consumer of this constants
+  module keeps the constant live while a same-named constant exported by an
+  unrelated module never masks a dead one. A module outside any repository is
+  judged on the package-tree scan alone, and the widened pass skips the package
+  subtree the first pass already covered, so no file is read twice.
 - The combined file count of the package-tree and widened passes is bounded by a
   cap, so a write under an unexpectedly large tree cannot stall the hook; a write
   whose scan hits the cap is treated as "cannot prove dead" and flags nothing.
@@ -38,6 +46,8 @@ The scan is deliberately conservative to keep false positives near zero:
 import ast
 import os
 import sys
+from collections.abc import Callable
+from functools import partial
 from pathlib import Path
 
 _blocking_directory = str(Path(__file__).resolve().parent)
@@ -146,21 +156,61 @@ def _module_declares_dunder_all(tree: ast.Module) -> bool:
     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]:
+def _dunder_all_member_names(tree: ast.Module) -> set[str]:
+    """Return the string member names a module's ``__all__`` sequence lists.
+
+    Reads the value of each ``__all__`` assignment whose value is a list, tuple,
+    or set literal and collects every string element. A non-literal ``__all__``
+    value (built by concatenation or a comprehension) contributes no names, so a
+    constant the check cannot prove is exported stays out of the exported set.
+
+    Args:
+        tree: The parsed constants module.
+
+    Returns:
+        The set of names the module names in its ``__all__`` literal.
+    """
+    member_names: set[str] = set()
+    for each_statement in tree.body:
+        if not _statement_binds_dunder_all(each_statement):
+            continue
+        value_node: ast.expr | None = None
+        if isinstance(each_statement, ast.Assign):
+            value_node = each_statement.value
+        elif isinstance(each_statement, ast.AnnAssign):
+            value_node = each_statement.value
+        if not isinstance(value_node, ast.List | ast.Tuple | ast.Set):
+            continue
+        for each_element in value_node.elts:
+            if isinstance(each_element, ast.Constant) and isinstance(each_element.value, str):
+                member_names.add(each_element.value)
+    return member_names
+
+
+def _referenced_names_in_source(
+    source: str,
+    load_only: bool = False,
+    collect_string_literals: bool = True,
+) -> 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.
+    references, attribute roots, and (when ``collect_string_literals`` is set)
+    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.
+        collect_string_literals: When True, count every string literal as a
+            referenced name. Set False for the written module under an ``__all__``
+            export check so the module's own ``__all__`` entry never shields an
+            exported constant that no other module consumes.
 
     Returns:
         The set of names the module references.
@@ -179,11 +229,63 @@ def _referenced_names_in_source(source: str, load_only: bool = False) -> set[str
             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):
+        elif (
+            collect_string_literals
+            and isinstance(each_node, ast.Constant)
+            and isinstance(each_node.value, str)
+        ):
             referenced_names.add(each_node.value)
     return referenced_names
 
 
+def _module_final_segment(module_path: str | None) -> str:
+    """Return the final dotted segment of an import module path.
+
+    Args:
+        module_path: The ``module`` attribute of a ``from ... import`` node, or
+            None for a bare relative import (``from . import x``).
+
+    Returns:
+        The text after the last dot, the whole string when it carries no dot, or
+        the empty string when ``module_path`` is None or empty.
+    """
+    if not module_path:
+        return ""
+    return module_path.rsplit(".", 1)[-1]
+
+
+def _qualified_import_member_names(source: str, module_stem: str) -> set[str]:
+    """Return names imported from a module whose filename stem is ``module_stem``.
+
+    A cross-package consumer of an exported constant imports it through an
+    explicit ``from <module> import NAME`` whose module path ends in the defining
+    module's filename stem. Collecting only those member names binds a
+    widened-scan reference to the module that actually defines the constant, so a
+    same-named constant exported by an unrelated module never masks a dead one.
+
+    Args:
+        source: The full text of a ``.py`` module under the repository root.
+        module_stem: The filename stem of the constants module being judged.
+
+    Returns:
+        The member names imported from a module whose final dotted segment equals
+        ``module_stem``. A module that fails to parse contributes no names.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    member_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if _module_final_segment(each_node.module) != module_stem:
+            continue
+        for each_alias in each_node.names:
+            member_names.add(each_alias.name)
+    return member_names
+
+
 def _scan_root_for_constants_module(file_path: str) -> Path:
     """Return the directory tree to scan for references to the module's constants.
 
@@ -226,41 +328,48 @@ def _is_under_directory(candidate_path: Path, ancestor_directory: Path) -> bool:
     return True
 
 
-def _all_referenced_names_under_root(
+def _collect_names_under_root(
     scan_root: Path,
     written_path: Path,
-    written_content: str,
+    all_seed_names: set[str],
+    extract_names: Callable[[str], set[str]],
     already_scanned_count: int = 0,
     excluded_subtree: Path | None = None,
 ) -> tuple[set[str], int, bool]:
-    """Return referenced names under the scan root, the running count, and a cap flag.
-
-    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 once the running file count exceeds the configured
-    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". When
-    ``excluded_subtree`` is supplied, every ``.py`` module under that directory is
-    skipped, so the widened repository scan never re-reads a file the
+    """Collect referenced names under the scan root via a per-module extractor.
+
+    Walks every ``.py`` module under ``scan_root`` (excluding the written module
+    itself, and any module under ``excluded_subtree``), applies ``extract_names``
+    to each module's text, and unions the result onto ``all_seed_names``. Reading
+    stops once the running file count exceeds the configured 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". The ``excluded_subtree``
+    skip keeps the widened repository scan from re-reading a file the
     package-tree scan already covered.
 
     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.
+        written_path: The resolved path of the module being written, skipped so
+            its own text is judged through ``all_seed_names`` rather than the
+            stale disk copy.
+        all_seed_names: The names the written module itself contributes, unioned
+            in before the walk begins.
+        extract_names: Maps one module's source text to the set of names it
+            contributes — the generous reference collector for the package-tree
+            pass, the stem-bound import collector for the widened pass.
         already_scanned_count: The file count accumulated by a prior pass, so the
             cap bounds the combined work of the package-tree and widened passes.
         excluded_subtree: A resolved directory whose ``.py`` modules are skipped,
             or None to scan every file under the root.
 
     Returns:
-        A (referenced_names, running_count, cap_was_hit) triple. The name set is
-        the union across every scanned module, unioned with the names the written
-        module itself references; running_count is the cumulative file count
-        including ``already_scanned_count``; cap_was_hit is True when the scan
-        stopped at the configured file cap before scanning the whole tree.
+        A (collected_names, running_count, cap_was_hit) triple. collected_names
+        is ``all_seed_names`` unioned with every scanned module's contribution;
+        running_count is the cumulative file count including
+        ``already_scanned_count``; 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)
+    collected_names = set(all_seed_names)
     written_path_key = os.path.normcase(str(written_path))
     scanned_file_count = already_scanned_count
     for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
@@ -273,13 +382,13 @@ def _all_referenced_names_under_root(
             continue
         scanned_file_count += 1
         if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
-            return all_referenced_names, scanned_file_count, True
+            return collected_names, scanned_file_count, 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, scanned_file_count, False
+        collected_names |= extract_names(sibling_source)
+    return collected_names, scanned_file_count, False
 
 
 def _repository_root_for(written_path: Path) -> Path | None:
@@ -324,6 +433,37 @@ def _module_is_exempt_from_constant_check(file_path: str) -> bool:
     return not _is_dedicated_constants_module(file_path)
 
 
+def _constants_under_check(tree: ast.Module) -> tuple[list[tuple[str, int]], bool]:
+    """Return the constants to judge and whether the seed counts string literals.
+
+    A module without ``__all__`` judges every module-scope constant and lets its
+    own string literals seed the reference scan. A module declaring ``__all__``
+    judges only the constants its ``__all__`` list names — the explicit export
+    surface — and withholds its own string literals from the seed, so an
+    ``__all__`` entry never counts as the consumer that keeps an exported constant
+    live. A constant the module defines but ``__all__`` omits is the author's
+    stated private value and is left out of the judged set.
+
+    Args:
+        tree: The parsed constants module.
+
+    Returns:
+        A (definitions, seed_collect_string_literals) pair: the (name, line)
+        constants to judge, and whether the written module's string literals seed
+        the referenced-name set.
+    """
+    constant_definitions = _module_constant_definitions(tree)
+    if not _module_declares_dunder_all(tree):
+        return constant_definitions, True
+    exported_names = _dunder_all_member_names(tree)
+    exported_definitions = [
+        (each_name, each_line)
+        for each_name, each_line in constant_definitions
+        if each_name in exported_names
+    ]
+    return exported_definitions, False
+
+
 def check_dead_module_constants(
     content: str,
     file_path: str,
@@ -334,16 +474,23 @@ def check_dead_module_constants(
     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 under the enclosing package tree, nor anywhere
-    in the repository the scan widens to when the package-tree scan leaves the
-    constant unreferenced — 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. A scan whose combined package-tree and widened file count
-    exceeds the configured cap returns ``[]`` (cannot prove dead), bounding the
-    work so the blocking hook cannot stall under a large tree. Whole-file
-    analysis runs against ``full_file_content`` when supplied so an Edit fragment
-    is judged against the reconstructed post-edit file.
+    appears in no ``.py`` module under the enclosing package tree — not imported,
+    not read, not listed in another module's ``__all__`` literal, not named in a
+    string annotation — and, in the repository-wide scan the check widens to when
+    the package-tree scan leaves the constant unreferenced, no module imports the
+    name from a ``from <module> import`` whose final dotted segment equals this
+    module's filename stem. Binding the widened scan to the stem keeps a genuine
+    cross-tree consumer counting while a same-named constant exported by an
+    unrelated module never masks a dead one. A module declaring ``__all__``
+    narrows the check to the constants its ``__all__`` list names: each must be
+    imported or read by another module, and the module's own ``__all__`` entry
+    never counts as that consumer, so an exported constant no module consumes is
+    flagged; a constant the module defines but ``__all__`` omits is the author's
+    private value and is left alone. A scan whose combined package-tree and
+    widened file count exceeds the configured cap returns ``[]`` (cannot prove
+    dead), bounding the work so the blocking hook cannot stall under a large tree.
+    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).
@@ -355,8 +502,9 @@ def check_dead_module_constants(
     Returns:
         One violation message per dead module-level constant, capped at the
         configured maximum. Returns an empty list when the file is exempt, no
-        constant is defined, the module declares ``__all__``, the scan exceeds the
-        file cap, or a SyntaxError prevents parsing.
+        constant is in scope (none defined, or none exported when ``__all__`` is
+        declared), the scan exceeds the file cap, or a SyntaxError prevents
+        parsing.
     """
     if _module_is_exempt_from_constant_check(file_path):
         return []
@@ -365,17 +513,21 @@ def check_dead_module_constants(
         tree = ast.parse(effective_content)
     except SyntaxError:
         return []
-    if _module_declares_dunder_all(tree):
-        return []
-    constant_definitions = _module_constant_definitions(tree)
+    constant_definitions, seed_collect_string_literals = _constants_under_check(tree)
     if not constant_definitions:
         return []
     scan_root = _scan_root_for_constants_module(file_path)
     written_path = Path(file_path).resolve()
-    all_referenced_names, scanned_file_count, cap_was_hit = _all_referenced_names_under_root(
+    written_seed_names = _referenced_names_in_source(
+        effective_content,
+        load_only=True,
+        collect_string_literals=seed_collect_string_literals,
+    )
+    all_referenced_names, scanned_file_count, cap_was_hit = _collect_names_under_root(
         scan_root,
         written_path,
-        effective_content,
+        written_seed_names,
+        _referenced_names_in_source,
     )
     if cap_was_hit:
         return []
@@ -385,10 +537,14 @@ def check_dead_module_constants(
     if has_unreferenced_constant:
         repository_root = _repository_root_for(written_path)
         if repository_root is not None and repository_root != scan_root:
-            widened_names, _widened_count, widened_cap_was_hit = _all_referenced_names_under_root(
+            collect_qualified_imports = partial(
+                _qualified_import_member_names, module_stem=written_path.stem
+            )
+            widened_names, _widened_count, widened_cap_was_hit = _collect_names_under_root(
                 repository_root,
                 written_path,
-                effective_content,
+                set(),
+                collect_qualified_imports,
                 already_scanned_count=scanned_file_count,
                 excluded_subtree=scan_root,
             )

package/hooks/blocking/code_rules_dead_split_branch.py

@@ -0,0 +1,225 @@
+"""Dead-conditional-branch check for a truthiness test on an always-non-empty split."""
+
+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_path_utils import (  # noqa: E402
+    is_config_file,
+)
+from code_rules_shared import (  # noqa: E402
+    _collect_annotated_arguments,
+    _walk_skipping_nested_function_defs,
+    is_test_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_ALWAYS_NONEMPTY_SPLIT_METHOD_NAMES,
+    DEAD_SPLIT_BRANCH_MESSAGE_SUFFIX,
+    MAX_DEAD_SPLIT_BRANCH_ISSUES,
+)
+
+
+def _is_separator_split_call(call_node: ast.Call) -> bool:
+    """Return True for an ``x.split(sep)`` / ``x.rsplit(sep)`` with a non-empty separator.
+
+    ``str.split`` and ``bytes.split`` return a list holding at least one element
+    whenever a separator argument is supplied, so the result is always truthy.
+    Requiring a non-empty string or bytes literal separator keeps the guarantee
+    airtight: ``split()`` with no argument can return an empty list, and an
+    empty separator raises at runtime. The receiver is restricted to a bare
+    ``Name`` or a string/bytes literal so an intermediate attribute chain such
+    as a pandas ``s.str.split(",")`` — whose result is a Series, not a list —
+    is not treated as an always-non-empty split.
+
+    Args:
+        call_node: The call expression on the right-hand side of an assignment.
+
+    Returns:
+        True when the call is a separator-bearing split that never returns an
+        empty list.
+    """
+    function_node = call_node.func
+    if not isinstance(function_node, ast.Attribute):
+        return False
+    if function_node.attr not in ALL_ALWAYS_NONEMPTY_SPLIT_METHOD_NAMES:
+        return False
+    receiver_node = function_node.value
+    if isinstance(receiver_node, ast.Constant):
+        if not isinstance(receiver_node.value, (str, bytes)):
+            return False
+    elif not isinstance(receiver_node, ast.Name):
+        return False
+    if not call_node.args:
+        return False
+    first_argument = call_node.args[0]
+    if not isinstance(first_argument, ast.Constant):
+        return False
+    separator_value = first_argument.value
+    if not isinstance(separator_value, (str, bytes)):
+        return False
+    return len(separator_value) > 0
+
+
+def _separator_split_target_names(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> set[str]:
+    """Return names bound exactly once in the function from a separator split.
+
+    A name qualifies when its single binding in the function body is an
+    assignment whose value is a separator-bearing ``split`` / ``rsplit`` call,
+    so the bound list is always truthy. A name bound more than once, or also a
+    parameter, is excluded because a later rebinding could make it falsy.
+
+    Args:
+        function_node: The function whose body is inspected.
+
+    Returns:
+        The set of always-truthy split-result names safe to reason about.
+    """
+    all_store_counts: dict[str, int] = {}
+    all_split_names: set[str] = set()
+    for each_statement in function_node.body:
+        for each_node in _walk_skipping_nested_function_defs(each_statement):
+            if isinstance(each_node, ast.Name) and isinstance(each_node.ctx, ast.Store):
+                all_store_counts[each_node.id] = (
+                    all_store_counts.get(each_node.id, 0) + 1
+                )
+            if not isinstance(each_node, ast.Assign):
+                continue
+            if len(each_node.targets) != 1:
+                continue
+            assignment_target = each_node.targets[0]
+            if not isinstance(assignment_target, ast.Name):
+                continue
+            if isinstance(each_node.value, ast.Call) and _is_separator_split_call(
+                each_node.value
+            ):
+                all_split_names.add(assignment_target.id)
+    all_parameter_names = {
+        each_argument.arg
+        for each_argument in _collect_annotated_arguments(function_node)
+    }
+    return {
+        each_name
+        for each_name in all_split_names
+        if all_store_counts.get(each_name, 0) == 1
+        and each_name not in all_parameter_names
+    }
+
+
+def _truthiness_target(
+    test_node: ast.expr, all_candidate_names: set[str]
+) -> str | None:
+    """Return the candidate name a bare ``Name`` truthiness test reads, else None."""
+    if isinstance(test_node, ast.Name) and test_node.id in all_candidate_names:
+        return test_node.id
+    return None
+
+
+def _negated_truthiness_target(
+    test_node: ast.expr, all_candidate_names: set[str]
+) -> str | None:
+    """Return the candidate name a ``not Name`` test reads, else None."""
+    if not isinstance(test_node, ast.UnaryOp) or not isinstance(test_node.op, ast.Not):
+        return None
+    operand = test_node.operand
+    if isinstance(operand, ast.Name) and operand.id in all_candidate_names:
+        return operand.id
+    return None
+
+
+def _branch_finding_for_node(
+    node: ast.AST, all_candidate_names: set[str]
+) -> tuple[int, str] | None:
+    """Return ``(line, name)`` when a node carries a dead branch, else None.
+
+    A conditional expression always carries an else arm, so any truthiness test
+    on a candidate name is a dead branch. An ``if`` statement only carries a
+    dead else when it has one, while an ``if not name`` statement always has a
+    dead body.
+    """
+    if isinstance(node, ast.IfExp):
+        truthy_name = _truthiness_target(node.test, all_candidate_names)
+        if truthy_name is not None:
+            return node.lineno, truthy_name
+        return _negated_branch_finding(node.test, node.lineno, all_candidate_names)
+    if isinstance(node, ast.If):
+        truthy_name = _truthiness_target(node.test, all_candidate_names)
+        if truthy_name is not None and node.orelse:
+            return node.lineno, truthy_name
+        return _negated_branch_finding(node.test, node.lineno, all_candidate_names)
+    return None
+
+
+def _negated_branch_finding(
+    test_node: ast.expr, line_number: int, all_candidate_names: set[str]
+) -> tuple[int, str] | None:
+    negated_name = _negated_truthiness_target(test_node, all_candidate_names)
+    if negated_name is not None:
+        return line_number, negated_name
+    return None
+
+
+def _dead_branch_findings(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    all_candidate_names: set[str],
+) -> list[tuple[int, str]]:
+    """Return every ``(line, name)`` dead-branch finding in the function body."""
+    all_findings: list[tuple[int, str]] = []
+    for each_statement in function_node.body:
+        for each_node in _walk_skipping_nested_function_defs(each_statement):
+            finding = _branch_finding_for_node(each_node, all_candidate_names)
+            if finding is not None:
+                all_findings.append(finding)
+    return all_findings
+
+
+def check_dead_split_truthiness_branch(content: str, file_path: str) -> list[str]:
+    """Flag a conditional whose branch is unreachable after a separator split.
+
+    ``str.split(sep)`` and ``bytes.split(sep)`` with a separator always return a
+    list holding at least one element, so a value bound from such a call is
+    always truthy. A conditional that tests that value's truthiness carries a
+    dead branch: ``parts[0] if parts else fallback`` never reaches ``fallback``,
+    and ``if not parts:`` never runs its body. Both the conditional-expression
+    form and the ``if`` / ``if not`` statement form are reported, scoped to a
+    value bound exactly once in the function from a separator split. Config
+    files and test files are exempt.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per dead conditional branch found, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_config_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        all_candidate_names = _separator_split_target_names(each_function_node)
+        if not all_candidate_names:
+            continue
+        for each_line, each_name in _dead_branch_findings(
+            each_function_node, all_candidate_names
+        ):
+            issues.append(
+                f"Line {each_line}: {each_name!r} {DEAD_SPLIT_BRANCH_MESSAGE_SUFFIX}"
+            )
+            if len(issues) >= MAX_DEAD_SPLIT_BRANCH_ISSUES:
+                return issues
+    return issues