Distinguish same-named functions across modules

[ethanleifer]

Summary

This changes function tracking so functions with the same local name in different modules are treated as distinct definitions when Vulture can derive a module from the scanned filename.

Today, Vulture stores function definitions by bare name only. That means a use of load_config in one module can mark every load_config definition in the scanned project as used, including definitions in unrelated modules. This creates false negatives for projects that commonly reuse conventional function names across modules.

Motivation

For example, with two modules that each define a load_config function, calling one of them should not suppress the unused report for the other:

# package/commands/loaders.py
def load_config():
    pass

# package/reports/loaders.py
def load_config():
    pass

# package/main.py
from package.commands.loaders import load_config

load_config()

After this change, Vulture reports package.reports.loaders.load_config as unused while recognizing package.commands.loaders.load_config as used.

Approach

• Derive a module name from .py filenames, including __init__.py handling.
• Keep Item.name as the local identifier, e.g. load_config.
• Store the module separately on Item.module, e.g. package.commands.loaders.
• Expose Item.full_name for function matching/reporting, e.g. package.commands.loaders.load_config.
• Preserve the existing bare-name used_names set for current behavior and public test expectations.
• Add an internal full-name usage set populated from direct, relative, and module attribute imports.
• Keep classes, methods, properties, variables, attributes, and imports on their existing naming behavior.

Compatibility notes

This changes report and whitelist output for unused functions when Vulture is given filenames that can be converted to module names. For example, foo.py now reports foo.myfunc instead of myfunc.

I kept the change scoped to functions to address the cross-module false-negative case without attempting full scope-aware analysis. Methods with the same name on different classes are still intentionally outside the scope of this PR.

Related issues

This is related to the broader set of false negatives caused by name-only matching, including:

• "unused variable" does not appear when variable with same name in other file  #366
• False negative when two locals or a class attribute and global have the same name #371
• False negative: Method calling another method with same name not detected as unused #407
• Feature request: A way to more specifically target items for whitelisting #343

Tests

• python -m ruff format tests/test_item.py tests/test_scavenging.py
• python -m ruff check vulture/core.py tests/test_item.py tests/test_scavenging.py tests/test_report.py
• python -m pytest tests/test_item.py tests/test_scavenging.py tests/test_report.py
• python -m pytest
• python -m coverage report -m vulture/core.py

[codecov]

Codecov Report

❌ Patch coverage is 96.34146% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.77%. Comparing base (81fb2ac) to head (c845700).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
vulture/core.py	96.34%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #417      +/-   ##
==========================================
+ Coverage   93.46%   93.77%   +0.31%     
==========================================
  Files           9        9              
  Lines         597      675      +78     
==========================================
+ Hits          558      633      +75     
- Misses         39       42       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.