assert-python-definition-is-used 20260829003946__tar.gz → 20260830020719__tar.gz

assert_python_definition_is_used-20260830020719/.claude/memories/pylint-refactor-messages-are-hard-failures.md

@@ -0,0 +1,9 @@
+# pylint refactor messages are hard failures
+
+`--fail-on=C,R,W` means pylint's R messages fail the job, so its default
+limits are hard limits here: 5 arguments, 15 locals, 12 branches, 50
+statements per function. Inline directives are banned, so the only route
+is to split the function.
+
+That is why `main` hands its work to `_findings_for` rather than growing
+another local for each mode it grew.

{assert_python_definition_is_used-20260829003946/src/assert_python_definition_is_used.egg-info → assert_python_definition_is_used-20260830020719}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assert-python-definition-is-used
-Version: 20260829003946
+Version: 20260830020719
 Summary: CLI tool to assert that every public Python definition in a tree is used somewhere else
 Author-email: 10U Labs <dev@10ulabs.com>
 License-Expression: Apache-2.0
@@ -76,6 +76,7 @@ tests written for it, which is what a coverage gate hides.
 | `--exclude PATTERNS` | Comma-separated globs to leave out of both trees. |
 | `--assume-used-matching PATTERNS` | Globs of names a runtime invokes. |
 | `--assume-used-decorated-with PATHS` | Decorators a runtime invokes. |
+| `--unimported-packages` | Report packages nothing imports, not definitions. |
 | `--quiet` | Print nothing; report through the exit code. |
 | `--count` | Print only how many findings there were. |
 | `--verbose` | Print each file scanned, each one read as text, and a summary. |
@@ -120,7 +121,8 @@ file rather than failing, and `--verbose` names each file that fell back.
 
 Reading a name is still not resolving it. A file that calls its own
 unrelated function of the same name counts as a use, so the count is a
-lower bound rather than an exact figure.
+lower bound rather than an exact figure. `--unimported-packages` below
+asks a question that survives that, one package at a time.
 
 Two dead functions in one file that call each other still read as used,
 because those calls are real code. Finding those needs reachability from
@@ -192,6 +194,53 @@ the run altogether, so its own definitions go unchecked too. A file left
 out of the search is still read for the definitions it holds; it just
 does not get a vote on whether anything else is used.
 
+## Packages nothing imports
+
+A function is reached by being named, so asking what names it is the
+right question. A package is reached by being imported, which is a
+different question with a different answer. A package can be entirely
+dead while every one of its names still appears somewhere, because the
+caller that reimplemented it picked the same ordinary words.
+
+The name search is blind in proportion to how ordinary a package's names
+are. A package of `get_client`, `set_client` and `reset_clients` is
+nearly invisible to it, those words appearing everywhere; a package of
+`resolve_terraform_interpolation` is fully visible, that word appearing
+nowhere else. That is backwards, because the packages most likely to be
+quietly reimplemented are exactly the ones whose names are ordinary
+enough for a caller to pick the same ones.
+
+`--unimported-packages` asks the other question. It reads every directory
+directly below a definition tree that holds an `__init__.py`, collects
+the top-level module of every `import` and `from ... import` in the
+searched files, and reports each package nothing imports. The finding is
+anchored on the package's `__init__.py` at line 1, in the same
+`path:line:name` form as the rest:
+
+```text
+lib/python/aws_clients/__init__.py:1:aws_clients
+```
+
+`--dont-search-in` applies here as it does elsewhere, so a package
+imported only by its own tests is reported:
+
+```bash
+assert-python-definition-is-used lib/python \
+  --search-in lib/python --search-in src --search-in test \
+  --dont-search-in 'test/lib/python/test_{package}' \
+  --unimported-packages
+```
+
+It is a mode rather than a check folded into every run, because the two
+questions have different answers for a directory with no `__init__.py`,
+and because a repository may want one without the other. Run it as a
+second job beside the definition run.
+
+A relative import names no top-level module, so `from . import helper`
+inside a package does not make that package imported. A file that will
+not parse credits nothing here either: a bare word in text is not an
+import, and guessing one from text would be worse than staying quiet.
+
 ## GitHub Actions
 
 ```yaml
@@ -204,6 +253,19 @@ does not get a vote on whether anything else is used.
     verbose: true
 ```
 
+Beside it, ask whether the packages are imported at all:
+
+```yaml
+- name: Assert every package is imported outside its own tests
+  uses: 10U-Labs/assert-python-definition-is-used@latest
+  with:
+    dont-search-in: test/lib/python/test_{package}
+    search-in: lib/python scripts src test
+    trees: lib/python
+    unimported-packages: true
+    verbose: true
+```
+
 Over a test tree, name what pytest invokes:
 
 ```yaml

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/README.md

@@ -52,6 +52,7 @@ tests written for it, which is what a coverage gate hides.
 | `--exclude PATTERNS` | Comma-separated globs to leave out of both trees. |
 | `--assume-used-matching PATTERNS` | Globs of names a runtime invokes. |
 | `--assume-used-decorated-with PATHS` | Decorators a runtime invokes. |
+| `--unimported-packages` | Report packages nothing imports, not definitions. |
 | `--quiet` | Print nothing; report through the exit code. |
 | `--count` | Print only how many findings there were. |
 | `--verbose` | Print each file scanned, each one read as text, and a summary. |
@@ -96,7 +97,8 @@ file rather than failing, and `--verbose` names each file that fell back.
 
 Reading a name is still not resolving it. A file that calls its own
 unrelated function of the same name counts as a use, so the count is a
-lower bound rather than an exact figure.
+lower bound rather than an exact figure. `--unimported-packages` below
+asks a question that survives that, one package at a time.
 
 Two dead functions in one file that call each other still read as used,
 because those calls are real code. Finding those needs reachability from
@@ -168,6 +170,53 @@ the run altogether, so its own definitions go unchecked too. A file left
 out of the search is still read for the definitions it holds; it just
 does not get a vote on whether anything else is used.
 
+## Packages nothing imports
+
+A function is reached by being named, so asking what names it is the
+right question. A package is reached by being imported, which is a
+different question with a different answer. A package can be entirely
+dead while every one of its names still appears somewhere, because the
+caller that reimplemented it picked the same ordinary words.
+
+The name search is blind in proportion to how ordinary a package's names
+are. A package of `get_client`, `set_client` and `reset_clients` is
+nearly invisible to it, those words appearing everywhere; a package of
+`resolve_terraform_interpolation` is fully visible, that word appearing
+nowhere else. That is backwards, because the packages most likely to be
+quietly reimplemented are exactly the ones whose names are ordinary
+enough for a caller to pick the same ones.
+
+`--unimported-packages` asks the other question. It reads every directory
+directly below a definition tree that holds an `__init__.py`, collects
+the top-level module of every `import` and `from ... import` in the
+searched files, and reports each package nothing imports. The finding is
+anchored on the package's `__init__.py` at line 1, in the same
+`path:line:name` form as the rest:
+
+```text
+lib/python/aws_clients/__init__.py:1:aws_clients
+```
+
+`--dont-search-in` applies here as it does elsewhere, so a package
+imported only by its own tests is reported:
+
+```bash
+assert-python-definition-is-used lib/python \
+  --search-in lib/python --search-in src --search-in test \
+  --dont-search-in 'test/lib/python/test_{package}' \
+  --unimported-packages
+```
+
+It is a mode rather than a check folded into every run, because the two
+questions have different answers for a directory with no `__init__.py`,
+and because a repository may want one without the other. Run it as a
+second job beside the definition run.
+
+A relative import names no top-level module, so `from . import helper`
+inside a package does not make that package imported. A file that will
+not parse credits nothing here either: a bare word in text is not an
+import, and guessing one from text would be worse than staying quiet.
+
 ## GitHub Actions
 
 ```yaml
@@ -180,6 +229,19 @@ does not get a vote on whether anything else is used.
     verbose: true
 ```
 
+Beside it, ask whether the packages are imported at all:
+
+```yaml
+- name: Assert every package is imported outside its own tests
+  uses: 10U-Labs/assert-python-definition-is-used@latest
+  with:
+    dont-search-in: test/lib/python/test_{package}
+    search-in: lib/python scripts src test
+    trees: lib/python
+    unimported-packages: true
+    verbose: true
+```
+
 Over a test tree, name what pytest invokes:
 
 ```yaml

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/action.yml

@@ -27,6 +27,10 @@ inputs:
   trees:
     description: Trees holding the definitions to check (space-separated)
     required: true
+  unimported-packages:
+    default: "false"
+    description: Report packages nothing imports, instead of definitions
+    required: false
   verbose:
     default: "false"
     description: Show trees read, definitions found, findings and a summary
@@ -46,6 +50,8 @@ runs:
         [ "${{ inputs.verbose }}" = "true" ] && ARGS="$ARGS --verbose"
         [ "${{ inputs.fail-fast }}" = "true" ] && ARGS="$ARGS --fail-fast"
         [ "${{ inputs.warn-only }}" = "true" ] && ARGS="$ARGS --warn-only"
+        [ "${{ inputs.unimported-packages }}" = "true" ] &&
+          ARGS="$ARGS --unimported-packages"
         if [ -n "${{ inputs.exclude }}" ]; then
           ARGS="$ARGS --exclude '${{ inputs.exclude }}'"
         fi

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/src/assert_python_definition_is_used/cli.py

@@ -15,6 +15,7 @@ from .scanner import (
     assumed_used,
     public_definitions,
     read_searched,
+    unimported_packages,
     unused_definitions,
 )
 
@@ -106,6 +107,16 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    parser.add_argument(
+        "--unimported-packages",
+        action="store_true",
+        help=(
+            "Ask the package question instead: report every package under the trees "
+            "that nothing outside its own tests imports. A package is reached by being "
+            "imported, so a name match says nothing about whether it is still wanted."
+        ),
+    )
+
     output_group = parser.add_mutually_exclusive_group()
     output_group.add_argument(
         "--quiet",
@@ -183,6 +194,14 @@ def package_of(path: str, tree: str) -> str | None:
     return parts[0]
 
 
+def package_root(path: str, tree: str) -> str | None:
+    package = package_of(path, tree)
+    if package is None:
+        return None
+    anchor = os.path.join(os.path.normpath(tree), package, "__init__.py")
+    return package if os.path.normpath(path) == anchor else None
+
+
 def _tree_root(path: str) -> str:
     if os.path.isdir(path):
         return path
@@ -261,6 +280,15 @@ def read_definitions(
     return definitions
 
 
+def read_packages(paths: dict[str, str]) -> list[Definition]:
+    packages: list[Definition] = []
+    for path in sorted(paths):
+        package = package_root(path, paths[path])
+        if package is not None:
+            packages.append(Definition(path=path, line_number=1, name=package, package=package))
+    return packages
+
+
 def report_unparsed(searched: Searched) -> None:
     for path in searched.unparsed:
         print(f"Searching as text (will not parse): {path}")
@@ -316,6 +344,22 @@ def _report(result: ScanResult, args: argparse.Namespace) -> None:
         output_findings(result.findings, args.count)
 
 
+def _findings_for(
+    args: argparse.Namespace,
+    result: ScanResult,
+    definition_paths: dict[str, str],
+    sources: dict[str, str],
+    searched: Searched,
+) -> list[Finding]:
+    if args.unimported_packages:
+        packages = read_packages(definition_paths)
+        result.files_scanned = result.definitions_read = len(packages)
+        return unimported_packages(packages, searched, args.dont_search_in)
+    definitions = read_definitions(definition_paths, sources, result, args.verbose)
+    checked = assume_used(definitions, args, result)
+    return unused_definitions(checked, searched, args.dont_search_in)
+
+
 def main(argv: Sequence[str] | None = None) -> None:
     args = create_parser().parse_args(argv)
     exclude_patterns = parse_patterns(args.exclude)
@@ -340,14 +384,12 @@ def main(argv: Sequence[str] | None = None) -> None:
         print()
 
     sources = read_sources({**search_paths, **definition_paths}, result, args.verbose)
-    definitions = read_definitions(definition_paths, sources, result, args.verbose)
-    definitions = assume_used(definitions, args, result)
     to_search = {path: content for path, content in sources.items() if path in search_paths}
     searched = read_searched(to_search)
     if args.verbose:
         report_unparsed(searched)
 
-    findings = unused_definitions(definitions, searched, args.dont_search_in)
+    findings = _findings_for(args, result, definition_paths, sources, searched)
     result.findings = findings[:1] if (args.fail_fast and findings) else findings
 
     _report(result, args)

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/src/assert_python_definition_is_used/scanner.py

@@ -8,7 +8,7 @@ from functools import lru_cache
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
 DEFINITION_NODES = (ast.AsyncFunctionDef, ast.ClassDef, ast.FunctionDef)
 DOCSTRING_HOLDERS = (ast.AsyncFunctionDef, ast.ClassDef, ast.FunctionDef, ast.Module)
@@ -54,6 +54,7 @@ class Finding:
 class Searched:
     uses: dict[str, frozenset[str]]
     unparsed: dict[str, str]
+    imports: dict[str, frozenset[str]]
 
 
 def is_public(name: str) -> bool:
@@ -163,8 +164,19 @@ def names_used(tree: ast.Module) -> frozenset[str]:
     return frozenset(names)
 
 
+def imported_modules(tree: ast.Module) -> frozenset[str]:
+    modules: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            modules.update(alias.name.split(".")[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and not node.level and node.module:
+            modules.add(node.module.split(".")[0])
+    return frozenset(modules)
+
+
 def read_searched(sources: dict[str, str]) -> Searched:
     uses: dict[str, frozenset[str]] = {}
+    imports: dict[str, frozenset[str]] = {}
     unparsed: dict[str, str] = {}
     for path in sorted(sources):
         try:
@@ -173,7 +185,8 @@ def read_searched(sources: dict[str, str]) -> Searched:
             unparsed[path] = sources[path]
             continue
         uses[path] = names_used(tree)
-    return Searched(uses=uses, unparsed=unparsed)
+        imports[path] = imported_modules(tree)
+    return Searched(uses=uses, unparsed=unparsed, imports=imports)
 
 
 def is_assumed_used_by_name(name: str, patterns: Sequence[str]) -> bool:
@@ -228,14 +241,41 @@ def is_used(
     return False
 
 
-def unused_definitions(
+def is_imported(
+    definition: Definition, searched: Searched, unsearched: str | None = None
+) -> bool:
+    return any(
+        definition.name in imported
+        for path, imported in searched.imports.items()
+        if not _is_unsearched(path, unsearched)
+    )
+
+
+def _findings_over(
     definitions: list[Definition],
     searched: Searched,
-    unsearched_template: str | None = None,
+    unsearched_template: str | None,
+    reached: Callable[[Definition, Searched, str | None], bool],
 ) -> list[Finding]:
     findings = []
     for definition in definitions:
         unsearched = unsearched_directory(unsearched_template, definition.package)
-        if not is_used(definition, searched, unsearched):
+        if not reached(definition, searched, unsearched):
             findings.append(Finding(definition=definition))
     return findings
+
+
+def unused_definitions(
+    definitions: list[Definition],
+    searched: Searched,
+    unsearched_template: str | None = None,
+) -> list[Finding]:
+    return _findings_over(definitions, searched, unsearched_template, is_used)
+
+
+def unimported_packages(
+    packages: list[Definition],
+    searched: Searched,
+    unsearched_template: str | None = None,
+) -> list[Finding]:
+    return _findings_over(packages, searched, unsearched_template, is_imported)

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719/src/assert_python_definition_is_used.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assert-python-definition-is-used
-Version: 20260829003946
+Version: 20260830020719
 Summary: CLI tool to assert that every public Python definition in a tree is used somewhere else
 Author-email: 10U Labs <dev@10ulabs.com>
 License-Expression: Apache-2.0
@@ -76,6 +76,7 @@ tests written for it, which is what a coverage gate hides.
 | `--exclude PATTERNS` | Comma-separated globs to leave out of both trees. |
 | `--assume-used-matching PATTERNS` | Globs of names a runtime invokes. |
 | `--assume-used-decorated-with PATHS` | Decorators a runtime invokes. |
+| `--unimported-packages` | Report packages nothing imports, not definitions. |
 | `--quiet` | Print nothing; report through the exit code. |
 | `--count` | Print only how many findings there were. |
 | `--verbose` | Print each file scanned, each one read as text, and a summary. |
@@ -120,7 +121,8 @@ file rather than failing, and `--verbose` names each file that fell back.
 
 Reading a name is still not resolving it. A file that calls its own
 unrelated function of the same name counts as a use, so the count is a
-lower bound rather than an exact figure.
+lower bound rather than an exact figure. `--unimported-packages` below
+asks a question that survives that, one package at a time.
 
 Two dead functions in one file that call each other still read as used,
 because those calls are real code. Finding those needs reachability from
@@ -192,6 +194,53 @@ the run altogether, so its own definitions go unchecked too. A file left
 out of the search is still read for the definitions it holds; it just
 does not get a vote on whether anything else is used.
 
+## Packages nothing imports
+
+A function is reached by being named, so asking what names it is the
+right question. A package is reached by being imported, which is a
+different question with a different answer. A package can be entirely
+dead while every one of its names still appears somewhere, because the
+caller that reimplemented it picked the same ordinary words.
+
+The name search is blind in proportion to how ordinary a package's names
+are. A package of `get_client`, `set_client` and `reset_clients` is
+nearly invisible to it, those words appearing everywhere; a package of
+`resolve_terraform_interpolation` is fully visible, that word appearing
+nowhere else. That is backwards, because the packages most likely to be
+quietly reimplemented are exactly the ones whose names are ordinary
+enough for a caller to pick the same ones.
+
+`--unimported-packages` asks the other question. It reads every directory
+directly below a definition tree that holds an `__init__.py`, collects
+the top-level module of every `import` and `from ... import` in the
+searched files, and reports each package nothing imports. The finding is
+anchored on the package's `__init__.py` at line 1, in the same
+`path:line:name` form as the rest:
+
+```text
+lib/python/aws_clients/__init__.py:1:aws_clients
+```
+
+`--dont-search-in` applies here as it does elsewhere, so a package
+imported only by its own tests is reported:
+
+```bash
+assert-python-definition-is-used lib/python \
+  --search-in lib/python --search-in src --search-in test \
+  --dont-search-in 'test/lib/python/test_{package}' \
+  --unimported-packages
+```
+
+It is a mode rather than a check folded into every run, because the two
+questions have different answers for a directory with no `__init__.py`,
+and because a repository may want one without the other. Run it as a
+second job beside the definition run.
+
+A relative import names no top-level module, so `from . import helper`
+inside a package does not make that package imported. A file that will
+not parse credits nothing here either: a bare word in text is not an
+import, and guessing one from text would be worse than staying quiet.
+
 ## GitHub Actions
 
 ```yaml
@@ -204,6 +253,19 @@ does not get a vote on whether anything else is used.
     verbose: true
 ```
 
+Beside it, ask whether the packages are imported at all:
+
+```yaml
+- name: Assert every package is imported outside its own tests
+  uses: 10U-Labs/assert-python-definition-is-used@latest
+  with:
+    dont-search-in: test/lib/python/test_{package}
+    search-in: lib/python scripts src test
+    trees: lib/python
+    unimported-packages: true
+    verbose: true
+```
+
 Over a test tree, name what pytest invokes:
 
 ```yaml

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/src/assert_python_definition_is_used.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ pyproject.toml
 .claude/memories/let-ci-run-the-checks.md
 .claude/memories/name-a-conftest-fixture-apart-from-what-it-asks-for.md
 .claude/memories/name-a-job-after-the-package-it-runs.md
+.claude/memories/pylint-refactor-messages-are-hard-failures.md
 .claude/memories/run-the-tool-before-writing-the-claim.md
 .claude/memories/start-over-when-the-user-does-not-understand.md
 .github/workflows/documentation.yml

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/src/assert_python_definition_is_used.egg-info/scm_file_list.json

@@ -9,6 +9,7 @@
     ".claude/memories/let-ci-run-the-checks.md",
     ".claude/memories/name-a-conftest-fixture-apart-from-what-it-asks-for.md",
     ".claude/memories/name-a-job-after-the-package-it-runs.md",
+    ".claude/memories/pylint-refactor-messages-are-hard-failures.md",
     ".claude/memories/run-the-tool-before-writing-the-claim.md",
     ".claude/memories/start-over-when-the-user-does-not-understand.md",
     ".github/workflows/documentation.yml",

assert_python_definition_is_used-20260830020719/src/assert_python_definition_is_used.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "20260830020719",
+  "distance": 0,
+  "node": "g5ff0194533d61d4bcd419fc6b86fb2e931ee4b26",
+  "dirty": false,
+  "branch": "main",
+  "node_date": "2026-08-30"
+}

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/test/integration/test_cli.py

@@ -9,11 +9,15 @@ from test.samples import (
     LIB_AND_TEST_RUN,
     NOTED_PROJECT,
     OUTER_BOUND,
+    PACKAGED_PROJECT,
+    PACKAGES_RUN,
     PROJECT,
     PROSE,
     RUNTIME_ASSUMED,
     RUNTIME_PROJECT,
     RUNTIME_RUN,
+    SHADOWED_PACKAGES_RUN,
+    SHADOWING_PROJECT,
 )
 from typing import TYPE_CHECKING
 
@@ -301,3 +305,43 @@ class TestAgainstARuntimeInvokedTree:
     def test_the_verbose_summary_is_unchanged_without_the_inputs(self, stdout_of: StdoutOf) -> None:
         stdout = stdout_of(RUNTIME_PROJECT, [*RUNTIME_RUN, "--verbose"])
         assert "Definitions read: 4\nFindings: 4\n" in stdout
+
+
+@pytest.mark.integration
+class TestAgainstATreeShadowingALibraryName:
+    def test_the_definition_check_credits_the_shadowed_name(self, stdout_of: StdoutOf) -> None:
+        assert "get_ssm_client" not in stdout_of(SHADOWING_PROJECT, CLEAN_RUN)
+
+    def test_the_definition_check_reports_what_nothing_shadows(self, stdout_of: StdoutOf) -> None:
+        assert "reset_clients" in stdout_of(SHADOWING_PROJECT, CLEAN_RUN)
+
+    def test_the_package_nothing_imports_is_reported(self, stdout_of: StdoutOf) -> None:
+        anchor = os.path.join("lib", "python", "aws_clients", "__init__.py")
+        stdout = stdout_of(SHADOWING_PROJECT, SHADOWED_PACKAGES_RUN)
+        assert stdout.splitlines() == [f"{anchor}:1:aws_clients"]
+
+    def test_the_package_check_fails_the_run(self, exit_code_of: ExitCodeOf) -> None:
+        assert exit_code_of(SHADOWING_PROJECT, SHADOWED_PACKAGES_RUN) == EXIT_FINDINGS
+
+
+@pytest.mark.integration
+class TestAgainstPackagesAndTheirImporters:
+    def test_reports_the_package_only_its_own_tests_import(self, stdout_of: StdoutOf) -> None:
+        anchor = os.path.join("lib", "python", "dead", "__init__.py")
+        assert stdout_of(PACKAGED_PROJECT, PACKAGES_RUN).splitlines() == [f"{anchor}:1:dead"]
+
+    def test_leaves_the_imported_package_alone(self, stdout_of: StdoutOf) -> None:
+        assert "live" not in stdout_of(PACKAGED_PROJECT, PACKAGES_RUN)
+
+    def test_a_loose_module_is_no_package(self, stdout_of: StdoutOf) -> None:
+        assert "loose" not in stdout_of(PACKAGED_PROJECT, PACKAGES_RUN)
+
+    def test_a_nested_package_is_not_reported_on_its_own(self, stdout_of: StdoutOf) -> None:
+        assert "inner" not in stdout_of(PACKAGED_PROJECT, PACKAGES_RUN)
+
+    def test_the_own_tests_count_without_the_template(self, stdout_of: StdoutOf) -> None:
+        assert stdout_of(PACKAGED_PROJECT, [*OUTER_BOUND, "--unimported-packages"]) == ""
+
+    def test_a_fully_imported_tree_exits_zero(self, exit_code_of: ExitCodeOf) -> None:
+        run = [*OUTER_BOUND, "--unimported-packages"]
+        assert exit_code_of(PACKAGED_PROJECT, run) == EXIT_SUCCESS

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/test/integration/test_helpers.py

@@ -6,8 +6,11 @@ import runpy
 import sys
 from test.samples import (
     CALLER,
+    HANDLER,
     LIBRARY,
+    PACKAGED_PROJECT,
     PROJECT,
+    RELATIVE,
     RUNTIME_ASSUMED,
     RUNTIME_INVOKED,
     RUNTIME_PROJECT,
@@ -36,8 +39,10 @@ from assert_python_definition_is_used.cli import (
     determine_exit_code,
     output_findings,
     package_of,
+    package_root,
     parse_patterns,
     read_definitions,
+    read_packages,
     read_sources,
     should_skip,
 )
@@ -45,13 +50,16 @@ from assert_python_definition_is_used.scanner import (
     Definition,
     Finding,
     assumed_used,
+    imported_modules,
     is_assumed_used_by_decorator,
     is_assumed_used_by_name,
+    is_imported,
     is_public,
     is_used,
     names_in_text,
     names_used,
     read_searched,
+    unimported_packages,
     unsearched_directory,
     public_definitions,
     unused_definitions,
@@ -347,3 +355,54 @@ class TestAssumptionsOverRealFiles:
     def test_the_parser_defaults_both_to_none(self) -> None:
         parsed = create_parser().parse_args(RUNTIME_RUN)
         assert (parsed.assume_used_matching, parsed.assume_used_decorated_with) == (None, None)
+
+
+@pytest.mark.integration
+class TestPackagesOverRealFiles:
+    def test_collect_finds_the_package_roots(self, write_tree: WriteTree) -> None:
+        write_tree(PACKAGED_PROJECT)
+        collected, _ = _collect(["lib/python"], [])
+        assert sorted(item.name for item in read_packages(collected)) == ["dead", "live"]
+
+    def test_a_nested_package_is_not_a_root(self) -> None:
+        assert package_root(os.path.join("lib", "python", "a", "b", "__init__.py"), "lib") is None
+
+    def test_a_package_init_is_a_root(self) -> None:
+        assert package_root(os.path.join("lib", "python", "__init__.py"), "lib") == "python"
+
+    def test_read_packages_anchors_on_line_one(self, write_tree: WriteTree) -> None:
+        write_tree(PACKAGED_PROJECT)
+        collected, _ = _collect(["lib/python"], [])
+        assert {item.line_number for item in read_packages(collected)} == {1}
+
+    def test_imported_modules_reads_an_import(self) -> None:
+        assert imported_modules(ast.parse(HANDLER)) == frozenset({"boto3"})
+
+    def test_imported_modules_reads_a_from_import(self) -> None:
+        assert imported_modules(ast.parse(CALLER)) == frozenset({"pkg"})
+
+    def test_imported_modules_skips_a_relative_import(self) -> None:
+        assert not imported_modules(ast.parse(RELATIVE))
+
+    def test_read_searched_keeps_the_imports(self) -> None:
+        assert read_searched({"src/app.py": CALLER}).imports["src/app.py"] == frozenset({"pkg"})
+
+    def test_is_imported_reads_the_sources(self) -> None:
+        package = Definition(path="lib/python/pkg/__init__.py", line_number=1, name="pkg",
+                             package="pkg")
+        assert is_imported(package, read_searched({"src/app.py": CALLER}))
+
+    def test_a_bare_name_is_not_an_import(self) -> None:
+        package = Definition(path="lib/python/pkg/__init__.py", line_number=1, name="pkg",
+                             package="pkg")
+        assert not is_imported(package, read_searched({"src/app.py": "pkg = 1\n"}))
+
+    def test_unimported_packages_reports(self) -> None:
+        package = Definition(path="lib/python/pkg/__init__.py", line_number=1, name="pkg",
+                             package="pkg")
+        found = unimported_packages([package], read_searched({"src/app.py": "pkg = 1\n"}))
+        assert len(found) == 1
+
+    def test_the_parser_reads_the_unimported_packages_flag(self) -> None:
+        parsed = create_parser().parse_args(["lib", "--unimported-packages"])
+        assert parsed.unimported_packages is True

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/test/samples.py

@@ -149,3 +149,55 @@ RUNTIME_ASSUMED = [
     "--assume-used-decorated-with",
     "pytest.fixture",
 ]
+
+CLIENTS = """\
+def get_client(service_name):
+    return service_name
+
+
+def get_ssm_client():
+    return get_client("ssm")
+
+
+def reset_clients():
+    return None
+"""
+
+HANDLER = """\
+import boto3
+
+
+def get_ssm_client():
+    return boto3.client("ssm")
+
+
+def handler(event, context):
+    return get_ssm_client()
+"""
+
+RELATIVE = """\
+from .helper import gadget
+
+
+def ring():
+    return gadget()
+"""
+
+SHADOWING_PROJECT = {
+    "lib/python/aws_clients/__init__.py": CLIENTS,
+    "src/handler.py": HANDLER,
+}
+
+PACKAGED_PROJECT = {
+    "lib/python/live/__init__.py": "def widget():\n    return 1\n",
+    "lib/python/live/inner/__init__.py": "def spin():\n    return 2\n",
+    "lib/python/dead/__init__.py": RELATIVE,
+    "lib/python/dead/helper.py": "def gadget():\n    return 3\n",
+    "lib/python/loose.py": "def solo():\n    return 4\n",
+    "src/app.py": "import live\n\nlive.widget()\n",
+    "test/lib/python/test_dead/test_it.py": "import dead\n\ndead.ring()\n",
+}
+
+PACKAGES_RUN = [*FULL_RUN, "--unimported-packages"]
+
+SHADOWED_PACKAGES_RUN = [*CLEAN_RUN, "--unimported-packages"]

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/test/unit/test_cli.py

@@ -22,8 +22,10 @@ from assert_python_definition_is_used.cli import (
     determine_exit_code,
     output_findings,
     package_of,
+    package_root,
     parse_patterns,
     read_definitions,
+    read_packages,
     read_sources,
     should_skip,
 )
@@ -47,12 +49,22 @@ RUNTIME_TREE = {
     ),
 }
 
+PACKAGE_TREE = {
+    "lib/python/held/__init__.py": "def widget():\n    pass\n",
+    "lib/python/adrift/__init__.py": "def gadget():\n    pass\n",
+    "src/app.py": "import held\n\nheld.widget()\ngadget()\n",
+}
+
 ASSUMED = ["--assume-used-matching", "test_*", "--assume-used-decorated-with", "pytest.fixture"]
 
 SEARCH_EVERYWHERE = ["--search-in", "lib/python", "--search-in", "src", "--search-in", "test"]
 
 FULL_RUN = ["lib/python", *SEARCH_EVERYWHERE, "--dont-search-in", "test/lib/python/test_{package}"]
 
+PACKAGE_SEARCH = ["lib/python", "--search-in", "lib/python", "--search-in", "src"]
+
+PACKAGE_RUN = [*PACKAGE_SEARCH, "--unimported-packages"]
+
 
 def _arguments(extra: list[str]) -> argparse.Namespace:
     return create_parser().parse_args(["lib/python", *extra])
@@ -118,6 +130,13 @@ class TestCreateParser:
         with pytest.raises(SystemExit):
             create_parser().parse_args(["lib", "--quiet", "--verbose"])
 
+    def test_reads_the_unimported_packages_flag(self) -> None:
+        parsed = create_parser().parse_args(["lib", "--unimported-packages"])
+        assert parsed.unimported_packages is True
+
+    def test_unimported_packages_defaults_to_false(self) -> None:
+        assert create_parser().parse_args(["lib"]).unimported_packages is False
+
     def test_reads_the_fail_fast_flag(self) -> None:
         assert create_parser().parse_args(["lib", "--fail-fast"]).fail_fast is True
 
@@ -180,6 +199,49 @@ class TestPackageOf:
         assert package_of("lib/python/pkg/__init__.py", "lib/python/") == "pkg"
 
 
+@pytest.mark.unit
+class TestPackageRoot:
+    def test_names_a_package_at_its_init(self) -> None:
+        assert package_root("lib/python/pkg/__init__.py", "lib/python") == "pkg"
+
+    def test_a_module_beside_the_init_is_not_a_root(self) -> None:
+        assert package_root("lib/python/pkg/mod.py", "lib/python") is None
+
+    def test_a_nested_package_is_not_a_root(self) -> None:
+        assert package_root("lib/python/pkg/inner/__init__.py", "lib/python") is None
+
+    def test_a_loose_file_is_not_a_root(self) -> None:
+        assert package_root("lib/python/mod.py", "lib/python") is None
+
+    def test_normalises_a_trailing_separator(self) -> None:
+        assert package_root("lib/python/pkg/__init__.py", "lib/python/") == "pkg"
+
+
+@pytest.mark.unit
+class TestReadPackages:
+    def test_names_the_package(self) -> None:
+        found = read_packages({"lib/python/pkg/__init__.py": "lib/python"})
+        assert [item.name for item in found] == ["pkg"]
+
+    def test_anchors_on_the_first_line(self) -> None:
+        found = read_packages({"lib/python/pkg/__init__.py": "lib/python"})
+        assert found[0].line_number == 1
+
+    def test_carries_the_package_through(self) -> None:
+        found = read_packages({"lib/python/pkg/__init__.py": "lib/python"})
+        assert found[0].package == "pkg"
+
+    def test_skips_a_module_that_is_not_an_init(self) -> None:
+        assert not read_packages({"lib/python/pkg/mod.py": "lib/python"})
+
+    def test_reads_the_packages_in_path_order(self) -> None:
+        paths = {
+            "lib/python/b/__init__.py": "lib/python",
+            "lib/python/a/__init__.py": "lib/python",
+        }
+        assert [item.name for item in read_packages(paths)] == ["a", "b"]
+
+
 @pytest.mark.unit
 class TestTreeRoot:
     def test_a_directory_is_its_own_root(self, write_tree: WriteTree) -> None:
@@ -526,3 +588,28 @@ class TestMainWithAssumptions:
     def test_a_name_outside_the_patterns_is_reported(self, exit_code_of: ExitCodeOf) -> None:
         tree = {"test/pkg/helpers.py": "def spare():\n    pass\n"}
         assert exit_code_of(tree, ["test", *ASSUMED]) == EXIT_FINDINGS
+
+
+@pytest.mark.unit
+class TestMainOverPackages:
+    def test_reports_the_package_nothing_imports(self, stdout_of: StdoutOf) -> None:
+        assert "adrift" in stdout_of(PACKAGE_TREE, PACKAGE_RUN)
+
+    def test_leaves_the_imported_package_alone(self, stdout_of: StdoutOf) -> None:
+        assert "held" not in stdout_of(PACKAGE_TREE, PACKAGE_RUN)
+
+    def test_anchors_the_finding_on_the_init_file(self, stdout_of: StdoutOf) -> None:
+        anchor = os.path.join("lib", "python", "adrift", "__init__.py")
+        assert stdout_of(PACKAGE_TREE, PACKAGE_RUN).splitlines() == [f"{anchor}:1:adrift"]
+
+    def test_the_finding_fails_the_run(self, exit_code_of: ExitCodeOf) -> None:
+        assert exit_code_of(PACKAGE_TREE, PACKAGE_RUN) == EXIT_FINDINGS
+
+    def test_the_definition_check_is_quiet_about_the_same_tree(self, stdout_of: StdoutOf) -> None:
+        assert stdout_of(PACKAGE_TREE, [*PACKAGE_SEARCH, "--count"]) == "0\n"
+
+    def test_verbose_counts_the_packages_read(self, stdout_of: StdoutOf) -> None:
+        assert "Definitions read: 2" in stdout_of(PACKAGE_TREE, [*PACKAGE_RUN, "--verbose"])
+
+    def test_verbose_counts_the_files_scanned(self, stdout_of: StdoutOf) -> None:
+        assert "Files scanned: 2" in stdout_of(PACKAGE_TREE, [*PACKAGE_RUN, "--verbose"])

{assert_python_definition_is_used-20260829003946 → assert_python_definition_is_used-20260830020719}/test/unit/test_scanner.py

@@ -8,13 +8,16 @@ from assert_python_definition_is_used.scanner import (
     Definition,
     Finding,
     assumed_used,
+    imported_modules,
     is_assumed_used_by_decorator,
     is_assumed_used_by_name,
+    is_imported,
     is_public,
     is_used,
     names_in_text,
     names_used,
     read_searched,
+    unimported_packages,
     unsearched_directory,
     public_definitions,
     unused_definitions,
@@ -27,6 +30,10 @@ def _uses(name: str, content: str) -> bool:
     return name in names_used(ast.parse(content))
 
 
+def _imports(content: str) -> frozenset[str]:
+    return imported_modules(ast.parse(content))
+
+
 def _definition(
     name: str = "widget",
     line: int = 1,
@@ -283,6 +290,13 @@ class TestReadSearched:
         searched = read_searched({"src/b.py": "", "src/a.py": ""})
         assert list(searched.uses) == ["src/a.py", "src/b.py"]
 
+    def test_reads_the_imports_of_a_file(self) -> None:
+        searched = read_searched({"src/app.py": "import pkg\n"})
+        assert searched.imports == {"src/app.py": frozenset({"pkg"})}
+
+    def test_a_file_that_will_not_parse_has_no_imports(self) -> None:
+        assert not read_searched({"src/bad.py": "def widget(:\n"}).imports
+
 
 @pytest.mark.unit
 class TestIsAssumedUsedByName:
@@ -477,3 +491,103 @@ class TestUnusedDefinitions:
 
     def test_no_definitions_means_no_findings(self) -> None:
         assert not unused_definitions([], read_searched({MODULE: ""}))
+
+
+@pytest.mark.unit
+class TestImportedModules:
+    def test_reads_a_plain_import(self) -> None:
+        assert _imports("import pkg\n") == frozenset({"pkg"})
+
+    def test_reads_only_the_top_level_of_a_dotted_import(self) -> None:
+        assert _imports("import pkg.inner.mod\n") == frozenset({"pkg"})
+
+    def test_reads_a_renamed_import(self) -> None:
+        assert _imports("import pkg as shortcut\n") == frozenset({"pkg"})
+
+    def test_reads_every_name_in_one_import(self) -> None:
+        assert _imports("import one, two\n") == frozenset({"one", "two"})
+
+    def test_reads_a_from_import(self) -> None:
+        assert _imports("from pkg import widget\n") == frozenset({"pkg"})
+
+    def test_reads_only_the_top_level_of_a_dotted_from_import(self) -> None:
+        assert _imports("from pkg.inner import widget\n") == frozenset({"pkg"})
+
+    def test_reads_an_import_buried_in_a_function(self) -> None:
+        assert _imports("def entry():\n    import pkg\n") == frozenset({"pkg"})
+
+    def test_a_bare_relative_import_names_no_package(self) -> None:
+        assert not _imports("from . import widget\n")
+
+    def test_a_relative_module_import_names_no_package(self) -> None:
+        assert not _imports("from .inner import widget\n")
+
+    def test_naming_a_module_is_not_importing_it(self) -> None:
+        assert not _imports("pkg.widget()\n")
+
+    def test_an_empty_file_imports_nothing(self) -> None:
+        assert not _imports("")
+
+
+@pytest.mark.unit
+class TestIsImported:
+    def test_a_sibling_module_importing_it_counts(self) -> None:
+        sources = {MODULE: "", "src/app.py": "import pkg\n"}
+        assert is_imported(_definition(name="pkg"), read_searched(sources)) is True
+
+    def test_a_from_import_counts(self) -> None:
+        sources = {MODULE: "", "src/app.py": "from pkg import widget\n"}
+        assert is_imported(_definition(name="pkg"), read_searched(sources)) is True
+
+    def test_a_name_written_as_a_bare_word_is_not_an_import(self) -> None:
+        sources = {MODULE: "", "src/app.py": "def get_client():\n    pass\n"}
+        package = _definition(name="get_client", package="get_client")
+        assert is_imported(package, read_searched(sources)) is False
+
+    def test_a_file_that_will_not_parse_does_not_import(self) -> None:
+        sources = {MODULE: "", "src/bad.py": "import pkg(\n"}
+        assert is_imported(_definition(name="pkg"), read_searched(sources)) is False
+
+    def test_an_unsearched_directory_is_discounted(self) -> None:
+        sources = {MODULE: "", "test/pkg/test_it.py": "import pkg\n"}
+        found = is_imported(_definition(name="pkg"), read_searched(sources), "test/pkg/")
+        assert found is False
+
+    def test_another_directory_still_counts(self) -> None:
+        sources = {MODULE: "", "test/other/test_it.py": "import pkg\n"}
+        found = is_imported(_definition(name="pkg"), read_searched(sources), "test/pkg/")
+        assert found is True
+
+    def test_nothing_to_search_means_unimported(self) -> None:
+        assert is_imported(_definition(name="pkg"), read_searched({})) is False
+
+
+@pytest.mark.unit
+class TestUnimportedPackages:
+    def test_reports_a_package_nothing_imports(self) -> None:
+        sources = {MODULE: "def widget():\n    pass\n"}
+        found = unimported_packages([_definition(name="pkg")], read_searched(sources))
+        assert len(found) == 1
+
+    def test_stays_quiet_about_a_package_a_sibling_imports(self) -> None:
+        sources = {MODULE: "", "src/app.py": "import pkg\n"}
+        assert not unimported_packages([_definition(name="pkg")], read_searched(sources))
+
+    def test_reports_a_package_only_its_own_tests_import(self) -> None:
+        sources = {MODULE: "", "test/lib/python/test_pkg/test_it.py": "import pkg\n"}
+        found = unimported_packages(
+            [_definition(name="pkg")], read_searched(sources), "test/lib/python/test_{package}"
+        )
+        assert len(found) == 1
+
+    def test_reports_the_package_whose_name_is_only_ever_a_bare_word(self) -> None:
+        sources = {MODULE: "", "src/app.py": "def get_client():\n    return 1\n"}
+        packages = [_definition(name="get_client", package="get_client")]
+        assert len(unimported_packages(packages, read_searched(sources))) == 1
+
+    def test_anchors_the_finding_on_the_init_file(self) -> None:
+        found = unimported_packages([_definition(name="pkg")], read_searched({MODULE: ""}))
+        assert str(found[0]) == f"{MODULE}:1:pkg"
+
+    def test_no_packages_means_no_findings(self) -> None:
+        assert not unimported_packages([], read_searched({MODULE: ""}))

assert_python_definition_is_used-20260829003946/src/assert_python_definition_is_used.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "20260829003946",
-  "distance": 0,
-  "node": "g8d74654a1663da2f08adbf9ca0278d7f2554fbd0",
-  "dirty": false,
-  "branch": "main",
-  "node_date": "2026-08-29"
-}