Fix/deduplicate clashing star import suggestions (#318)

* Fix duplicate explicit imports from multiple star imports with clashing names (#121)

When multiple star imports export the same name (e.g. defaultdict from
both _collections and collections), each star import independently
suggested that name, producing duplicate explicit imports after
refactoring. Add a post-processing deduplication step in MainAnalyzer
that iterates star imports in reverse (last-to-first, matching Python's
shadowing semantics) and removes already-claimed suggestions from
earlier star imports, so a single pass produces correct output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Extend dedup to handle star+explicit clashes and add edge case tests

Extend _deduplicate_star_suggestions() to also consider explicit (non-star)
imports in the seen set, preventing star imports from suggesting names that
already have an explicit import. This fixes duplicate output like:
  from json import JSONEncoder  (from star expansion)
  from json import JSONEncoder  (from explicit import)

Add two new edge case test cases:
- partial_overlap_star_imports: reverse order where each star import has
  both shared and unique names, verifying unique names are preserved
- star_import_with_explicit: star import + explicit import of same name,
  verifying star doesn't duplicate the explicit import

Update existing star_imports and 2 test expectations to reflect the fix
(json star import no longer suggests JSONEncoder when explicit import exists).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: hakancelikdev

CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in
+this repository.
+
+## Project Overview
+
+Unimport is a Python linter and formatter that detects and removes unused import
+statements. It uses `ast` for analysis and `libcst` for refactoring (preserving
+formatting). Supports Python 3.9–3.13.
+
+## Common Commands
+
+```bash
+# Install for development
+pip install -e ".[test]"
+
+# Run all tests
+pytest tests -x -v --disable-warnings
+
+# Run a single test file
+pytest tests/cases/test_cases.py -x -v
+
+# Run a single test by name
+pytest tests -x -v -k "test_name"
+
+# Run with coverage (used by tox)
+pytest -vv --cov unimport
+
+# Run the tool itself
+unimport [sources]
+```
+
+Linting uses pre-commit (black, isort, mypy, docformatter). Line length is 120
+characters.
+
+## Architecture
+
+### Pipeline
+
+The core flow is: **parse source → analyze AST → identify unused imports → refactor with
+libcst**.
+
+`Main.run()` in `src/unimport/main.py` orchestrates this:
+
+1. `Config` resolves settings from CLI args + config files (pyproject.toml/setup.cfg)
+2. `Config.get_paths()` yields Python files matching include/exclude/gitignore rules
+3. For each file, `MainAnalyzer.traverse()` parses and analyzes the AST
+4. `Import.get_unused_imports()` returns unused imports from class-level state
+5. `refactor_string()` uses libcst to produce the cleaned source
+
+### Statement Module (`src/unimport/statement.py`)
+
+Central data model using **class-level mutable state** (important pattern to
+understand):
+
+- `Import.imports` (ClassVar list) — all registered imports for current file
+- `Name.names` (ClassVar list) — all registered name usages for current file
+- `Scope.scopes` / `Scope.current_scope` (ClassVar lists) — scope tracking
+
+These are populated during analysis and cleared via `MainAnalyzer.clear()` after each
+file. The `MainAnalyzer` context manager handles this lifecycle.
+
+### Analyzers (`src/unimport/analyzers/`)
+
+Three AST visitors run in sequence during `MainAnalyzer.traverse()`:
+
+1. **`NameAnalyzer`** — collects all name usages (identifiers, attributes, type
+   comments, string annotations)
+2. **`ImportableNameWithScopeAnalyzer`** — collects names from `__all__` definitions
+   (for star import suggestions)
+3. **`ImportAnalyzer`** — collects import statements, handles `if`/`try` dispatch,
+   generates star import suggestions
+
+### Refactoring (`src/unimport/refactor.py`)
+
+Uses `libcst` with `_RemoveUnusedImportTransformer` (a `CSTTransformer` with
+`PositionProvider` metadata) to surgically remove unused imports while preserving
+formatting.
+
+### Commands (`src/unimport/commands/`)
+
+CLI actions: `check` (report), `diff` (show changes), `remove` (apply changes),
+`permission` (interactive prompt). The `--remove` and `--permission` options are
+mutually exclusive.
+
+### Config (`src/unimport/config.py`)
+
+Auto-discovers `setup.cfg` or `pyproject.toml` (under `[tool.unimport]`). Config keys
+support both underscore (`include_star_import`) and hyphen (`include-star-import`)
+forms.
+
+## Test Structure
+
+Tests in `tests/cases/` use a **three-directory convention**:
+
+- `tests/cases/source/<category>/<case>.py` — input Python source
+- `tests/cases/analyzer/<category>/<case>.py` — expected analysis results (`NAMES`,
+  `IMPORTS`, `UNUSED_IMPORTS` lists)
+- `tests/cases/refactor/<category>/<case>.py` — expected output after refactoring
+
+`test_cases.py` parametrizes over all source files and validates both analysis and
+refactoring. To add a new test case, create matching files in all three directories.
+
+The `# unimport: skip_file` comment in source files tells unimport to skip analysis.

src/unimport/analyzers/main.py

@@ -44,13 +44,31 @@ def traverse(self) -> None:
             source=self.source, include_star_import=self.include_star_import, defined_names=get_defined_names(tree)
         ).traverse(tree)
 
+        self._deduplicate_star_suggestions()
+
         Scope.remove_current_scope()  # remove global scope
 
     def skip_file(self) -> bool:
         SKIP_FILE_REGEX = "#.*(unimport: {0,1}skip_file)"
 
         return bool(re.search(SKIP_FILE_REGEX, self.source, re.IGNORECASE))
 
+    @staticmethod
+    def _deduplicate_star_suggestions() -> None:
+        """Remove duplicate suggestions across star and explicit imports.
+
+        When multiple imports provide the same name, the last one wins
+        (matching Python's shadowing semantics). Explicit imports also
+        claim their name so star imports don't produce duplicates.
+        """
+        seen: set[str] = set()
+        for imp in reversed(Import.imports):
+            if isinstance(imp, ImportFrom) and imp.star:
+                imp.suggestions = [s for s in imp.suggestions if s not in seen]
+                seen.update(imp.suggestions)
+            else:
+                seen.add(imp.name)
+
     @staticmethod
     def clear():
         Name.clear()

tests/cases/analyzer/star_import/2.py

@@ -96,7 +96,7 @@
         name="json",
         package="json",
         star=True,
-        suggestions=["JSONEncoder"],
+        suggestions=[],
     ),
     ImportFrom(
         lineno=14,
@@ -114,7 +114,7 @@
         name="json",
         package="json",
         star=True,
-        suggestions=["JSONEncoder"],
+        suggestions=[],
     ),
     ImportFrom(
         lineno=1,

tests/cases/analyzer/star_import/clashing_star_imports.py

@@ -0,0 +1,47 @@
+from typing import Union
+
+from unimport.statement import Import, ImportFrom, Name
+
+__all__ = ["NAMES", "IMPORTS", "UNUSED_IMPORTS"]
+
+
+NAMES: list[Name] = [
+    Name(lineno=4, name="print", is_all=False),
+    Name(lineno=4, name="defaultdict", is_all=False),
+]
+IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="_collections",
+        package="_collections",
+        star=True,
+        suggestions=[],
+    ),
+    ImportFrom(
+        lineno=2,
+        column=1,
+        name="collections",
+        package="collections",
+        star=True,
+        suggestions=["defaultdict"],
+    ),
+]
+UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=2,
+        column=1,
+        name="collections",
+        package="collections",
+        star=True,
+        suggestions=["defaultdict"],
+    ),
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="_collections",
+        package="_collections",
+        star=True,
+        suggestions=[],
+    ),
+]

tests/cases/analyzer/star_import/partial_overlap_star_imports.py

@@ -0,0 +1,51 @@
+from typing import Union
+
+from unimport.statement import Import, ImportFrom, Name
+
+__all__ = ["NAMES", "IMPORTS", "UNUSED_IMPORTS"]
+
+
+NAMES: list[Name] = [
+    Name(lineno=4, name="print", is_all=False),
+    Name(lineno=4, name="Counter", is_all=False),
+    Name(lineno=5, name="print", is_all=False),
+    Name(lineno=5, name="defaultdict", is_all=False),
+    Name(lineno=6, name="print", is_all=False),
+    Name(lineno=6, name="deque", is_all=False),
+]
+IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="collections",
+        package="collections",
+        star=True,
+        suggestions=["Counter"],
+    ),
+    ImportFrom(
+        lineno=2,
+        column=1,
+        name="_collections",
+        package="_collections",
+        star=True,
+        suggestions=["defaultdict", "deque"],
+    ),
+]
+UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=2,
+        column=1,
+        name="_collections",
+        package="_collections",
+        star=True,
+        suggestions=["defaultdict", "deque"],
+    ),
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="collections",
+        package="collections",
+        star=True,
+        suggestions=["Counter"],
+    ),
+]

tests/cases/analyzer/star_import/star_import_with_explicit.py

@@ -0,0 +1,39 @@
+from typing import Union
+
+from unimport.statement import Import, ImportFrom, Name
+
+__all__ = ["NAMES", "IMPORTS", "UNUSED_IMPORTS"]
+
+
+NAMES: list[Name] = [
+    Name(lineno=4, name="print", is_all=False),
+    Name(lineno=4, name="defaultdict", is_all=False),
+]
+IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="_collections",
+        package="_collections",
+        star=True,
+        suggestions=[],
+    ),
+    ImportFrom(
+        lineno=2,
+        column=1,
+        name="defaultdict",
+        package="collections",
+        star=False,
+        suggestions=[],
+    ),
+]
+UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="_collections",
+        package="_collections",
+        star=True,
+        suggestions=[],
+    ),
+]

tests/cases/analyzer/star_import/star_imports.py

@@ -52,7 +52,7 @@
         name="json",
         package="json",
         star=True,
-        suggestions=["JSONEncoder"],
+        suggestions=[],
     ),
     ImportFrom(
         lineno=6,
@@ -70,7 +70,7 @@
         name="json",
         package="json",
         star=True,
-        suggestions=["JSONEncoder"],
+        suggestions=[],
     ),
     ImportFrom(
         lineno=4,

tests/cases/refactor/star_import/2.py

@@ -1,5 +1,4 @@
 from json import JSONEncoder
-from json import JSONEncoder
 
 
 print(JSONEncoder)

tests/cases/refactor/star_import/clashing_star_imports.py

@@ -0,0 +1,3 @@
+from collections import defaultdict
+
+print(defaultdict)

tests/cases/refactor/star_import/partial_overlap_star_imports.py

@@ -0,0 +1,6 @@
+from collections import Counter
+from _collections import defaultdict, deque
+
+print(Counter)
+print(defaultdict)
+print(deque)