claude-dev-env 1.58.0 → 1.59.0

package/bin/install.test.mjs

@@ -1,14 +1,18 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { execFileSync } from 'node:child_process';
-import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 import {
     collectPackageSourceConflicts,
     CONTENT_DIRECTORIES,
     pythonCandidatesForPlatform,
+    isWindowsStorePythonStub,
+    interpreterCommandFromPath,
+    invokedAsEntryPoint,
     managedHookScriptRelativePaths,
     managedHookScriptRelativePathsFromSourceRoots,
     commandReferencesManagedHook,
@@ -202,6 +206,134 @@ test('pythonCandidatesForPlatform still offers python as a win32 fallback when p
 });
 
 
+test('isWindowsStorePythonStub flags the Microsoft Store WindowsApps alias paths', () => {
+    assert.equal(
+        isWindowsStorePythonStub('C:\\Program Files\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_3.13.3824.0_x64__qbz5n2kfra8p0\\python3.13.exe'),
+        true,
+    );
+    assert.equal(
+        isWindowsStorePythonStub('C:/Users/jon/AppData/Local/Microsoft/WindowsApps/python.exe'),
+        true,
+    );
+});
+
+
+test('isWindowsStorePythonStub does not flag a real interpreter install path', () => {
+    assert.equal(isWindowsStorePythonStub('C:\\Python313\\python.exe'), false);
+    assert.equal(isWindowsStorePythonStub('/usr/bin/python3'), false);
+});
+
+
+test('interpreterCommandFromPath forward-slashes a Windows interpreter path and leaves a space-free path unquoted', () => {
+    assert.equal(interpreterCommandFromPath('C:\\Python313\\python.exe'), 'C:/Python313/python.exe');
+});
+
+
+test('interpreterCommandFromPath quotes an interpreter path that contains a space', () => {
+    assert.equal(
+        interpreterCommandFromPath('C:\\Program Files\\Python313\\python.exe'),
+        '"C:/Program Files/Python313/python.exe"',
+    );
+});
+
+
+test('mergeHooksIntoSettings substitutes a quoted absolute interpreter path for the python3 prefix', () => {
+    const hooksConfig = {
+        hooks: {
+            PostToolUse: [
+                {
+                    matcher: 'Edit',
+                    hooks: [{ type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/auto_formatter.py' }],
+                },
+            ],
+        },
+    };
+    const settings = {};
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/x/.claude', '"C:/Program Files/Python313/python.exe"');
+    assert.equal(
+        settings.hooks.PostToolUse[0].hooks[0].command,
+        '"C:/Program Files/Python313/python.exe" C:/Users/x/.claude/hooks/workflow/auto_formatter.py',
+    );
+});
+
+
+test('mergeHooksIntoSettings prunes a prior py -3 managed hook when reinstalling with an absolute interpreter path', () => {
+    const hooksConfig = {
+        hooks: {
+            PostToolUse: [
+                {
+                    matcher: 'Edit',
+                    hooks: [{ type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/auto_formatter.py' }],
+                },
+            ],
+        },
+    };
+    const settings = {
+        hooks: {
+            PostToolUse: [
+                {
+                    matcher: 'Edit',
+                    hooks: [{ type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/workflow/auto_formatter.py' }],
+                },
+            ],
+        },
+    };
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/x/.claude', 'C:/Python313/python.exe');
+    assert.deepEqual(
+        settings.hooks.PostToolUse[0].hooks.map(hook => hook.command),
+        ['C:/Python313/python.exe C:/Users/x/.claude/hooks/workflow/auto_formatter.py'],
+    );
+});
+
+
+test('invokedAsEntryPoint is true when the module url matches the invoked script path', () => {
+    const scriptPath = process.platform === 'win32' ? 'C:\\pkg\\bin\\install.mjs' : '/pkg/bin/install.mjs';
+    assert.equal(invokedAsEntryPoint(pathToFileURL(scriptPath).href, scriptPath), true);
+});
+
+
+test('invokedAsEntryPoint is false when the module is imported by another script', () => {
+    const modulePath = process.platform === 'win32' ? 'C:\\pkg\\bin\\install.mjs' : '/pkg/bin/install.mjs';
+    const entryScriptPath = process.platform === 'win32' ? 'C:\\pkg\\bin\\install.test.mjs' : '/pkg/bin/install.test.mjs';
+    assert.equal(invokedAsEntryPoint(pathToFileURL(modulePath).href, entryScriptPath), false);
+});
+
+
+test('invokedAsEntryPoint is false when there is no invoked script path', () => {
+    assert.equal(invokedAsEntryPoint('file:///pkg/bin/install.mjs', undefined), false);
+});
+
+
+test('invokedAsEntryPoint is true when the module is reached through a bin symlink', () => {
+    const linkRoot = mkdtempSync(join(tmpdir(), 'cdev-bin-symlink-'));
+    try {
+        const realModulePath = join(linkRoot, 'install.mjs');
+        const symlinkLauncherPath = join(linkRoot, 'claude-dev-env');
+        writeFileSync(realModulePath, 'export const sentinel = true;\n');
+        symlinkSync(realModulePath, symlinkLauncherPath);
+        const realModuleUrl = pathToFileURL(realModulePath).href;
+        assert.equal(invokedAsEntryPoint(realModuleUrl, symlinkLauncherPath), true);
+    } finally {
+        rmSync(linkRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('invokedAsEntryPoint is false when a sibling script imports the real module', () => {
+    const importerRoot = mkdtempSync(join(tmpdir(), 'cdev-bin-importer-'));
+    try {
+        const realModulePath = join(importerRoot, 'install.mjs');
+        const importerScriptPath = join(importerRoot, 'install.test.mjs');
+        writeFileSync(realModulePath, 'export const sentinel = true;\n');
+        writeFileSync(importerScriptPath, 'import "./install.mjs";\n');
+        const realModuleUrl = pathToFileURL(realModulePath).href;
+        assert.equal(invokedAsEntryPoint(realModuleUrl, importerScriptPath), false);
+    } finally {
+        rmSync(importerRoot, { recursive: true, force: true });
+    }
+});
+
+
 const SAMPLE_HOOKS_CONFIG = {
     hooks: {
         Stop: [

package/docs/CODE_RULES.md

@@ -23,9 +23,9 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …)
 
-Test files are exempt from most checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
+Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. Ordinary test parameters stay exempt. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
 ---
 
@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.

package/hooks/blocking/code_rules_annotations_length.py

@@ -13,6 +13,7 @@ if _hooks_directory not in sys.path:
 
 from code_rules_shared import (  # noqa: E402
     _collect_annotated_arguments,
+    _collect_fixture_injection_arguments,
     _definition_docstring_line_span,
     _function_definition_line_span,
     _scope_violations_to_changed_lines,
@@ -24,8 +25,10 @@ from code_rules_shared import (  # noqa: E402
 
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_SELF_AND_CLS_PARAMETER_NAMES,
+    ANNOTATION_BY_PYTEST_FIXTURE,
     FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX,
     FUNCTION_LENGTH_BLOCKING_THRESHOLD,
+    KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX,
 )
 
 
@@ -52,6 +55,156 @@ def check_parameter_annotations(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _is_pytest_fixture_injection_site(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when a function node is a valid pytest fixture injection site.
+
+    A function qualifies as a fixture injection site when either its name begins
+    with the ``test`` prefix (matching pytest's default ``python_functions = test*``
+    collection rule) or it carries a ``@pytest.fixture`` / ``@fixture`` decorator,
+    with or without call arguments.  Ordinary helper functions that happen to share
+    a parameter name with a known pytest fixture are excluded by this predicate so
+    that ``check_known_pytest_fixture_annotations`` only enforces annotation
+    requirements on the functions where pytest actually performs fixture injection.
+
+    Args:
+        node: The function definition AST node to inspect.
+
+    Returns:
+        True when the node is a pytest test function or a fixture-decorated
+        function; False otherwise.
+    """
+    if node.name.startswith("test"):
+        return True
+    for each_decorator in node.decorator_list:
+        unwrapped = each_decorator.func if isinstance(each_decorator, ast.Call) else each_decorator
+        if isinstance(unwrapped, ast.Name) and unwrapped.id == "fixture":
+            return True
+        if isinstance(unwrapped, ast.Attribute) and unwrapped.attr == "fixture":
+            return True
+    return False
+
+
+def _normalize_fixture_annotation_text(annotation_text: str) -> str:
+    """Strip forward-reference string quoting from an unparsed annotation.
+
+    ``ast.unparse`` renders a forward-reference annotation such as
+    ``tmp_path: "Path"`` as the quoted literal ``'Path'``. Removing the
+    surrounding quotes recovers the bare type name so the quoted spelling
+    compares equal to its unquoted form.
+
+    Args:
+        annotation_text: The annotation as rendered by ``ast.unparse``.
+
+    Returns:
+        The annotation text with any single surrounding quote pair removed.
+    """
+    if len(annotation_text) >= 2 and annotation_text[0] in {'"', "'"}:
+        if annotation_text[-1] == annotation_text[0]:
+            return annotation_text[1:-1]
+    return annotation_text
+
+
+def _fixture_annotation_matches_expected(
+    actual_annotation: str, expected_annotation: str
+) -> bool:
+    """Return True when an annotation matches its fixture's documented type.
+
+    The match accepts every equally-correct spelling of the documented type:
+    the exact text, a forward-reference string form, and either the bare
+    attribute tail or the fully-qualified dotted form. Both ``tmp_path: Path``
+    and ``tmp_path: pathlib.Path`` satisfy an expected ``Path``, and both
+    ``monkeypatch: pytest.MonkeyPatch`` and ``monkeypatch: MonkeyPatch``
+    satisfy an expected ``pytest.MonkeyPatch``.
+
+    Args:
+        actual_annotation: The annotation as rendered by ``ast.unparse``.
+        expected_annotation: The fixture's single documented type spelling.
+
+    Returns:
+        True when the actual annotation is an accepted spelling of the
+        expected type; False otherwise.
+    """
+    normalized_actual = _normalize_fixture_annotation_text(actual_annotation)
+    if normalized_actual == expected_annotation:
+        return True
+    return normalized_actual.rsplit(".", 1)[-1] == expected_annotation.rsplit(
+        ".", 1
+    )[-1]
+
+
+def check_known_pytest_fixture_annotations(content: str, file_path: str) -> list[str]:
+    """Flag well-known pytest fixture parameters lacking their type annotation.
+
+    The broad parameter-annotation rule exempts test files, so an ordinary
+    test parameter never needs a type hint. This narrower check restores
+    enforcement for exactly the pytest builtin fixtures whose injected type is
+    fixed and documented — ``tmp_path: Path``, ``monkeypatch:
+    pytest.MonkeyPatch``, and the rest of
+    ``ANNOTATION_BY_PYTEST_FIXTURE``. For these names the
+    correct annotation is unambiguous, so requiring it costs the author one
+    token and removes a recurring class of reviewer noise on test fixtures.
+    A non-test file produces no findings here: the broad check already covers
+    every parameter outside test files.
+
+    A known fixture parameter is flagged both when it carries no annotation and
+    when its annotation source differs from the fixture's single documented
+    type, so ``tmp_path: str`` is flagged exactly like ``tmp_path``. Only the
+    named injection slots pytest actually fills — undefaulted
+    positional-or-keyword and keyword-only parameters — are inspected. A
+    positional-only parameter is skipped because pytest passes fixtures by
+    keyword and can never bind one positionally; a defaulted parameter is
+    skipped because pytest leaves its default in place rather than injecting a
+    fixture; and a ``*args`` or ``**kwargs`` parameter that happens to share a
+    fixture name is never a fixture injection.
+
+    Args:
+        content: The Python source to analyze.
+        file_path: The path of the file being checked.
+
+    Returns:
+        One blocking issue per known fixture injection parameter whose
+        annotation is missing or differs from its single documented type,
+        naming the parameter and its expected type.
+    """
+    if not is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not _is_pytest_fixture_injection_site(each_node):
+            continue
+        for each_arg in _collect_fixture_injection_arguments(each_node):
+            expected_annotation = ANNOTATION_BY_PYTEST_FIXTURE.get(
+                each_arg.arg
+            )
+            if expected_annotation is None:
+                continue
+            actual_annotation = (
+                ast.unparse(each_arg.annotation)
+                if each_arg.annotation is not None
+                else None
+            )
+            if actual_annotation is not None and _fixture_annotation_matches_expected(
+                actual_annotation, expected_annotation
+            ):
+                continue
+            issues.append(
+                f"Line {each_arg.lineno}: parameter {each_arg.arg!r} on "
+                f"{each_node.name!r} - {KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX} "
+                f"(annotate as {expected_annotation!r})"
+            )
+    return issues
+
+
 def check_return_annotations(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []

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