fix: scope CSS module class uses to their imported stylesheet

Author: Jaixii

src/deadcode/scanner.py

@@ -221,9 +221,11 @@ def scan(self) -> ScanResult:
         imports: dict[str, set[str]] = {}  # name -> set of files that import it
         css_classes: dict[str, list[tuple[str, int]]] = {}  # class -> [(file, line)]
         used_css_classes: set[str] = set()
+        used_css_module_classes: dict[Path, set[str]] = {}
         components: dict[str, str] = {}  # ComponentName -> file
         routes: list[tuple[str, str]] = []  # (route_path, file)
         star_reexports: list[tuple[str, str]] = []  # (barrel_file, module_spec)
+        file_set = {str(f.relative_to(self.project_dir)).replace("\\", "/") for f in all_files}
 
         for filepath in all_files:
             try:
@@ -251,16 +253,11 @@ def scan(self) -> ScanResult:
             # Parse className usage in TSX/JSX files
             if rel_path.endswith((".tsx", ".jsx")):
                 self._parse_classname_usage(content, used_css_classes)
-                # CSS-module accessor usage (styles.card / styles['card']).
-                # Only register accessors imported as a CSS module so we don't
-                # treat every object property access (e.g. `user.name`) as a
-                # CSS class.
-                self._parse_css_module_usage(content, used_css_classes)
 
             # CSS modules can also be consumed by plain TypeScript/JavaScript
             # files, for example when exporting class-name maps to components.
             if not self._is_css_file(rel_path):
-                self._parse_css_module_usage(content, used_css_classes)
+                self._parse_css_module_usage(content, rel_path, file_set, used_css_module_classes)
 
             # Parse components
             if rel_path.endswith((".tsx", ".jsx")):
@@ -276,7 +273,6 @@ def scan(self) -> ScanResult:
         # Resolve `export * from './mod'` specifiers to scanned files so that
         # every export forwarded by a barrel is treated as part of the public
         # API surface (never reported as removable).
-        file_set = {str(f.relative_to(self.project_dir)).replace("\\", "/") for f in all_files}
         star_reexported_files: set[str] = set()
         for barrel_file, module_spec in star_reexports:
             resolved = self._resolve_relative_module(barrel_file, module_spec, file_set)
@@ -290,7 +286,7 @@ def scan(self) -> ScanResult:
         self._find_dead_routes(routes, all_files, result)
 
         # 2c. Orphaned CSS
-        self._find_orphaned_css(css_classes, used_css_classes, result)
+        self._find_orphaned_css(css_classes, used_css_classes, used_css_module_classes, result)
 
         # 2d. Unreferenced components
         # Collect all names that are imported somewhere (i.e., actually used)
@@ -512,29 +508,40 @@ def _parse_classname_usage(self, content: str, used_css_classes: set[str]) -> No
                     for cls in group.split():
                         used_css_classes.add(cls)
 
-    def _parse_css_module_usage(self, content: str, used_css_classes: set[str]) -> None:
+    def _parse_css_module_usage(
+        self,
+        content: str,
+        rel_path: str,
+        file_set: set[str],
+        used_css_module_classes: dict[Path, set[str]],
+    ) -> None:
         """Extract CSS-module class names consumed via object accessors.
 
         The canonical Next.js/React pattern is::
 
             import styles from './Card.module.css';
             <div className={styles.card}>...</div>
 
-        We first find any ``*.module.css`` imports (binding name ``styles``)
-        so that accessor use ``styles.card`` registers ``card`` as a used
-        class. Bracket access ``styles['card-hover']`` is also captured.
+        Resolve each relative ``*.module.css`` import from its importing file
+        so that ``styles.card`` protects ``card`` only in that stylesheet.
+        Bracket access ``styles['card-hover']`` is also captured. Canonical
+        paths keep internal stylesheet symlinks and their targets consistent.
         Without this, every CSS-module class is falsely reported as orphaned
         and marked removable=True, risking deletion of live styles.
         """
         # Map the local binding (e.g. ``styles``) to a CSS-module import so
         # only module accessors are treated as class names.
-        module_bindings = {m.group(1) for m in _CSS_MODULE_IMPORT_PATTERN.finditer(content)}
+        module_bindings: dict[str, Path] = {}
+        for match in _CSS_MODULE_IMPORT_PATTERN.finditer(content):
+            stylesheet = self._resolve_relative_module(rel_path, match.group(2), file_set)
+            if stylesheet is not None and stylesheet.endswith(".module.css"):
+                module_bindings[match.group(1)] = (self.project_dir / stylesheet).resolve()
         if not module_bindings:
             return
         for m in _CSS_MODULE_USAGE_PATTERN.finditer(content):
             binding, dot_name, _, bracket_name = m.groups()
             if binding in module_bindings:
-                used_css_classes.add(dot_name or bracket_name)
+                used_css_module_classes.setdefault(module_bindings[binding], set()).add(dot_name or bracket_name)
 
     def _parse_components(self, content: str, rel_path: str, components: dict[str, str]) -> None:
         """Extract React component definitions."""
@@ -661,9 +668,11 @@ def _find_orphaned_css(
         self,
         css_classes: dict[str, list[tuple[str, int]]],
         used_css_classes: set[str],
+        used_css_module_classes: dict[Path, set[str]],
         result: ScanResult,
     ) -> None:
         """Find CSS classes defined but never used in JSX."""
+        module_usage_by_file: dict[str, set[str]] = {}
         for cls, locations in css_classes.items():
             # Skip common utility classes and pseudo-selectors
             if cls.startswith(
@@ -680,9 +689,16 @@ def _find_orphaned_css(
                 )
             ):
                 continue
-            if cls in used_css_classes:
-                continue
             for file, line in locations:
+                if file.endswith(".module.css"):
+                    if file not in module_usage_by_file:
+                        module_usage_by_file[file] = used_css_module_classes.get(
+                            (self.project_dir / file).resolve(), set()
+                        )
+                    if cls in module_usage_by_file[file]:
+                        continue
+                elif cls in used_css_classes:
+                    continue
                 result.findings.append(
                     Finding(
                         file=file,

tests/test_css_module_scopes.py

@@ -0,0 +1,107 @@
+"""CSS-module uses belong to one stylesheet, while literal classes stay global."""
+
+import pytest
+from click.testing import CliRunner
+
+from deadcode.cli import cli
+from deadcode.scanner import DeadCodeScanner
+
+
+def orphaned(project):
+    return {(finding.file, finding.name) for finding in DeadCodeScanner(project).scan().orphaned_css}
+
+
+@pytest.mark.parametrize("extension", ["ts", "js", "tsx", "jsx"])
+@pytest.mark.parametrize(
+    ("binding", "accessor", "class_name"),
+    [
+        ("styles", ".shared", "shared"),
+        ("styles", "[ 'card-hover' ]", "card-hover"),
+        ("$styles", "._active", "_active"),
+    ],
+)
+def test_module_accessor_only_protects_its_imported_stylesheet(tmp_path, extension, binding, accessor, class_name):
+    for name in ["A.module.css", "B.module.css", "global.css"]:
+        (tmp_path / name).write_text(f".{class_name} {{ color: red; }}\n")
+    (tmp_path / f"consumer.{extension}").write_text(
+        f"import {binding} from './B.module.css';\nconst selected = {binding}{accessor};\n"
+    )
+
+    assert orphaned(tmp_path) == {("A.module.css", class_name), ("global.css", class_name)}
+
+
+def test_nested_imports_distinguish_stylesheets_with_the_same_filename(tmp_path):
+    for directory in ["components", "first", "second"]:
+        (tmp_path / directory).mkdir()
+    for directory in ["first", "second"]:
+        (tmp_path / directory / "Card.module.css").write_text(".shared {}\n")
+    (tmp_path / "components" / "consumer.ts").write_text(
+        "import styles from '../second/./Card.module.css';\nconst selected = styles.shared;\n"
+    )
+
+    assert orphaned(tmp_path) == {("first/Card.module.css", "shared")}
+
+
+def test_bindings_are_local_to_each_importing_file(tmp_path):
+    for name in ["A.module.css", "B.module.css"]:
+        (tmp_path / name).write_text(".shared {}\n.other {}\n")
+    (tmp_path / "first.ts").write_text("import styles from './A.module.css';\nconst selected = styles.shared;\n")
+    (tmp_path / "second.ts").write_text("import styles from './B.module.css';\nconst selected = styles.other;\n")
+
+    assert orphaned(tmp_path) == {("A.module.css", "other"), ("B.module.css", "shared")}
+
+
+def test_literal_classes_protect_global_stylesheets_without_protecting_module_classes(tmp_path):
+    for name in ["first.css", "second.scss", "Card.module.css"]:
+        (tmp_path / name).write_text(".shared {}\n")
+    (tmp_path / "consumer.tsx").write_text('export const View = () => <div className="shared" />;\n')
+
+    assert orphaned(tmp_path) == {("Card.module.css", "shared")}
+
+
+def test_global_literal_and_module_accessor_uses_coexist(tmp_path):
+    for name in ["A.module.css", "B.module.css", "global.css"]:
+        (tmp_path / name).write_text(".shared {}\n.literal {}\n")
+    (tmp_path / "consumer.tsx").write_text(
+        "import styles from './B.module.css';\n"
+        'export const View = () => <div className="literal"><span className={styles.shared} /></div>;\n'
+    )
+
+    assert orphaned(tmp_path) == {
+        ("A.module.css", "shared"),
+        ("A.module.css", "literal"),
+        ("B.module.css", "literal"),
+        ("global.css", "shared"),
+    }
+
+
+@pytest.mark.parametrize("specifier", ["./missing.module.css", "package/Other.module.css"])
+def test_unresolved_imports_do_not_hide_unrelated_classes(tmp_path, specifier):
+    (tmp_path / "A.module.css").write_text(".shared {}\n")
+    (tmp_path / "global.css").write_text(".shared {}\n")
+    (tmp_path / "consumer.ts").write_text(f"import styles from '{specifier}';\nconst selected = styles.shared;\n")
+
+    assert orphaned(tmp_path) == {("A.module.css", "shared"), ("global.css", "shared")}
+
+
+def test_internal_stylesheet_symlink_keeps_live_target_and_alias_classes(tmp_path):
+    (tmp_path / "Actual.module.css").write_text(".shared {}\n.unused {}\n")
+    (tmp_path / "Linked.module.css").symlink_to(tmp_path / "Actual.module.css")
+    (tmp_path / "consumer.ts").write_text(
+        "import styles from './Linked.module.css';\nconst selected = styles.shared;\n"
+    )
+
+    assert orphaned(tmp_path) == {("Actual.module.css", "unused"), ("Linked.module.css", "unused")}
+
+
+def test_remove_preserves_live_module_and_only_removes_unused_definitions(tmp_path):
+    for name in ["A.module.css", "B.module.css", "global.css"]:
+        (tmp_path / name).write_text(".shared { color: red; }\n")
+    (tmp_path / "consumer.ts").write_text("import styles from './B.module.css';\nconst selected = styles.shared;\n")
+
+    result = CliRunner().invoke(cli, ["-p", str(tmp_path), "remove", "-c", "orphaned_css"], input="y\n")
+
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / "B.module.css").read_text() == ".shared { color: red; }\n"
+    assert ".shared" not in (tmp_path / "A.module.css").read_text()
+    assert ".shared" not in (tmp_path / "global.css").read_text()