fix(cli,audit): scan dedup, plain dirs, versions (#215)

- Fixed audit scans to deduplicate re-exported wrappers without dropping wrappers from non-recursive scans or external defining modules
- Fixed audit report formatting so chained proxy targets are read without emitting warnings, consuming warning budget, or fabricating module paths
- Fixed CLI plain-directory scans so successful checks exit 0 and nested-file skip warnings are reported on stderr
- Fixed CLI aggregate status handling so status-rendering failures do not change the overall exit code
- Improved CLI version detection for packages whose import names differ from distribution names, with a note when no version can be resolved
- Fixed expiry checks to propagate user-package import failures instead of misreporting them as missing version metadata
- Updated CI workflow permissions and link-check handling for release artifact downloads and timeout responses
- Updated documentation for CLI/audit behavior, public exports, FAQ metadata, contribution examples, troubleshooting anchors, and audit examples
- Updated project policy to allow bare `assert` statements inside pytest test functions
- Updated changelog entries for the shipped CLI and audit behavior fixes

---------

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 3 people

.github/CONTRIBUTING.md

@@ -330,15 +330,18 @@ pyDeprecate/
 ├── src/deprecate/              # Core library code
 │   ├── __about__.py            # Version and metadata
 │   ├── __init__.py             # Public API exports
-│   ├── docstring/              # Docstring utilities subpackage
-│   │   ├── inject.py           # Runtime injection helpers: TEMPLATE_DOC_*, _update_docstring_*()
-│   │   ├── griffe_ext.py       # Griffe extension for mkdocstrings / MkDocs (beta)
-│   │   └── sphinx_ext.py       # Sphinx autodoc extension (beta)
+│   ├── __main__.py             # python -m deprecate entry point
+│   ├── _cli.py                 # CLI subcommands: check, expiry, chains, all, status
+│   ├── _pkg.py                 # Version and path resolution helpers
 │   ├── _types.py               # Shared type definitions: DeprecationConfig, _ProxyConfig
 │   ├── deprecation.py          # @deprecated decorator and warning logic
-│   ├── audit.py                # Audit tools: validate_*, find_deprecation_wrappers()
 │   ├── proxy.py                # Instance/class proxy: deprecated_class(), deprecated_instance()
-│   └── utils.py                # Low-level helpers: void(), no_warning_call()
+│   ├── audit.py                # Audit tools: validate_*, find_deprecation_wrappers()
+│   ├── utils.py                # Low-level helpers: void(), assert_no_warnings()
+│   └── docstring/              # Docstring utilities subpackage
+│       ├── inject.py           # Runtime injection helpers: TEMPLATE_DOC_*, _update_docstring_*()
+│       ├── griffe_ext.py       # Griffe extension for mkdocstrings / MkDocs (beta)
+│       └── sphinx_ext.py       # Sphinx autodoc extension (beta)
 ├── tests/                      # Test suite
 │   ├── collection_targets.py       # Target functions (new implementations)
 │   ├── collection_deprecate.py     # Deprecated wrappers (@deprecated)
@@ -393,13 +396,13 @@ Tests live in `tests/` and follow a **three-layer separation**:
 > - Use `print()` for values you want to verify, paired with a `<details><summary>Output: <code>expression</code></summary>` block immediately after the code block. The `<summary>` label shows the **expression** being evaluated (e.g. `cfg.timeout`), not the `print()` wrapper.
 > - Only import and use `pytest.raises` when an example intentionally raises an exception — this prevents the extracted test from crashing. Do **not** use `pytest.warns`; deprecation warnings are emitted to stderr and do not cause test failures.
 > - **Never use `with warnings.catch_warnings(record=True) as w: warnings.simplefilter("always")`** in any `.md` code block (README, docs, docstrings). Use direct calls annotated with `# warns: FutureWarning` or `# silent` instead. Output blocks show only return values — not warning counts or `w[0].category.__name__`.
-> - Do **not** use bare `assert` statements — they crash the test with an unhelpful `AssertionError` if the value changes.
+> - Do **not** use bare `assert` statements in top-level example code — they crash the test with an unhelpful `AssertionError` if the value changes. **Exception:** bare `assert` statements inside `def test_...` function bodies shown as pytest integration examples are allowed and idiomatic — the test function itself is the test.
 > - Regenerate `test_readme.py` after any README change: `phmdoctest README.md --outfile tests/integration/test_readme.py`
 
 > **Docs examples must use `print()` + output blocks — no `assert`.** For all `docs/**/*.md` blocks that execute code:
 >
 > - Use `print()` to display values; follow immediately with a `<details><summary>Output: <code>expression</code></summary>` block showing expected output.
-> - Do **not** use bare `assert` statements (e.g. `assert pt.x == 1.0`, `assert isinstance(obj, MyClass)`) — use `print()` instead so the value is visible rather than crashing with `AssertionError`.
+> - Do **not** use bare `assert` statements in top-level example code (e.g. `assert pt.x == 1.0`, `assert isinstance(obj, MyClass)`) — use `print()` instead so the value is visible rather than crashing with `AssertionError`. **Exception:** bare `assert` statements inside `def test_...` function bodies shown as pytest integration examples are allowed and idiomatic.
 > - Avoid placeholders that do not validate behavior.
 > - **Never import a fictional package name** in runnable examples — executable examples must import from actual test collection modules (`from tests import collection_deprecate`, `collection_misconfigured`, or `collection_chains`). For CI-template snippets that intentionally show a placeholder import, add `# phmdoctest:skip — CI template: replace my_package with your actual package` as the first line of the code block so phmdoctest skips execution.
 
@@ -469,7 +472,7 @@ Examples:
 When adding a parametrized test that covers both forms, always add both fixtures and share the same `deprecated(...)` instance to guarantee identical configuration:
 
 ```python
-from deprecate import deprecated, void
+from deprecate import TargetMode, deprecated, void
 
 
 # original_* is declared first — _deprecation_* refers to it immediately after.
@@ -481,7 +484,7 @@ def original_sum_warn_only(a: int, b: int = 5) -> int:
 # The _deprecation_* variable is the deprecation tool (the decorator instance),
 # NOT a deprecated callable — that distinction is why it's named _deprecation_*
 # rather than _depr_* (which would imply the thing being deprecated).
-_deprecation_warn_only = deprecated(target=None, deprecated_in="0.2", remove_in="0.3")
+_deprecation_warn_only = deprecated(target=TargetMode.NOTIFY, deprecated_in="0.2", remove_in="0.3")
 
 
 @_deprecation_warn_only
@@ -526,7 +529,7 @@ WrappedWidget = _class_deprecation_widget(_OriginalWidget)
 
 > **Rule**: when a `Decorated<Name>` / `Wrapped<Name>` pair exists, both **must** share a single `_class_deprecation_<name>` instance. Duplicating the `deprecated_class(...)` kwargs is a bug — a silent config drift will cause the parametrized test to compare two different deprecations instead of the same one in two application forms.
 
-**Unification pattern — shared version kwargs and hoisted instances:**
+#### Unification pattern — shared version kwargs and hoisted instances
 
 When three or more `@deprecated(...)` or `@deprecated_class(...)` call sites share the same `(deprecated_in, remove_in[, num_warns])` combination, extract the repeated kwargs into a named `dict` constant and splat it at each call site. This eliminates silent version drift and makes bulk version-bump changes a one-line edit.
 
@@ -566,16 +569,16 @@ Functions in `collection_deprecate.py`, `collection_misconfigured.py`, `collecti
 Use a one-line summary of the deprecation pattern, then an `Examples:` section describing the user scenario:
 
 ```python
-from deprecate import deprecated
+from deprecate import TargetMode, deprecated
 
 
-@deprecated(target=None, deprecated_in="0.2", remove_in="0.3")
+@deprecated(target=TargetMode.NOTIFY, deprecated_in="0.2", remove_in="0.3")
 def decorated_sum_warn_only(a: int, b: int = 5) -> int:
     """Warning-only deprecation with no forwarding.
 
     Examples:
         The function is going away but has no replacement yet. The user gets
-        warned, but the original body still executes (`target=None`).
+        warned, but the original body still executes (TargetMode.NOTIFY).
     """
 ```
 
@@ -670,10 +673,10 @@ def test_deprecation_warning() -> None:
 <summary>Argument renaming</summary>
 
 ```python
-from deprecate import deprecated
+from deprecate import TargetMode, deprecated
 
 
-@deprecated(target=True, deprecated_in="1.0", remove_in="2.0", args_mapping={"old_param": "new_param"})
+@deprecated(target=TargetMode.ARGS_REMAP, deprecated_in="1.0", remove_in="2.0", args_mapping={"old_param": "new_param"})
 def my_func(old_param: int = 0, new_param: int = 0) -> int:
     """Function with renamed parameter."""
     return new_param
@@ -685,11 +688,11 @@ def my_func(old_param: int = 0, new_param: int = 0) -> int:
 <summary>Testing without warnings</summary>
 
 ```python
-from deprecate import no_warning_call
+from deprecate import assert_no_warnings
 
 
 def test_without_warning() -> None:
-    with no_warning_call(FutureWarning):
+    with assert_no_warnings(FutureWarning):
         # ... test code that should not emit warnings
         pass
 ```

.github/workflows/_create-pkg.yml

@@ -15,6 +15,9 @@ on:
         type: string
         default: "ubuntu-latest"
 
+permissions:
+  contents: read
+
 jobs:
   package:
     runs-on: ${{ inputs.os }}

.github/workflows/ci_check-links.yml

@@ -8,6 +8,9 @@ on:
     # Run once a week on Sundays
     - cron: "0 9 * * 0"
 
+permissions:
+  contents: read
+
 jobs:
   links-check:
     runs-on: ubuntu-latest
@@ -35,7 +38,7 @@ jobs:
             --no-progress
             --cache
             --max-cache-age 1d
-            --accept '100..=103,200..=299,429'
+            --accept '100..=103,200..=299,408,429'
             --cache-exclude-status 429
             './**/*.md'
             './**/*.rst'

.github/workflows/ci_install-pkg.yml

@@ -7,6 +7,9 @@ on: # Trigger the workflow on push or pull request, but only for the main branch
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 defaults:
   run:
     shell: bash

.github/workflows/ci_testing.yml

@@ -7,6 +7,9 @@ on: # Trigger the workflow on push or pull request, but only for the main branch
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   pytester:
     runs-on: ${{ matrix.os }}

.github/workflows/greetings.yml

@@ -3,6 +3,9 @@ name: Greetings
 
 on: [issues] # pull_request
 
+permissions:
+  issues: write
+
 jobs:
   greeting:
     runs-on: ubuntu-latest

.github/workflows/publish-pkg.yml

@@ -10,6 +10,9 @@ on: # Trigger the workflow on push or pull request for the main branch, tag push
   release:
     types: [published]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     uses: ./.github/workflows/_create-pkg.yml
@@ -46,6 +49,9 @@ jobs:
     if: github.event_name == 'release'
     runs-on: ubuntu-latest
     timeout-minutes: 5
+    permissions:
+      actions: read # required for actions/download-artifact
+      contents: write # required for uploading release assets
     steps:
       - name: 📥 Download artifact
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8

AGENTS.md

@@ -90,7 +90,7 @@ Write a clear explanation linking to both sources, then let maintainers decide o
 - **New troubleshooting item**: add to `docs/troubleshooting.md` AND the FAQPage JSON-LD in `docs/overrides/main.html`
 - **`docs/overrides/main.html`** is Jinja2 (prettier-excluded); do not put content files there
 - **`docs/robots.txt`** — AI crawler access policy; add a `User-agent: <bot> / Allow: /` block when a new mainstream AI crawler is released. The comment referencing the `docs/llms.txt` URL must stay current.
-- See [Documentation Site](.github/CONTRIBUTING.md#documentation-site) for the full consistency rules
+- See [Documentation Site](.github/CONTRIBUTING.md#-documentation-site) for the full consistency rules
 
 ## 🚫 Critical Constraints
 
@@ -101,7 +101,7 @@ Write a clear explanation linking to both sources, then let maintainers decide o
 - Use bare `except:` clauses
 - Define deprecated wrappers inside test files
 - Use `with warnings.catch_warnings(...)` in any `.md` documentation example in any form — neither `simplefilter("always")` for capturing nor `simplefilter("ignore", ...)` for suppressing; annotate the call with `# warns: FutureWarning` or `# warns: UserWarning` instead; output blocks show only return values
-- Use bare `assert` statements in `.md` documentation examples (e.g. `assert pt.x == 1.0`, `assert isinstance(obj, MyClass)`) — use `print()` instead and follow with a `<details><summary>Output: <code>expression</code></summary>` block showing expected output
+- Use bare `assert` statements in `.md` documentation examples outside of `def test_...` bodies (e.g. `assert pt.x == 1.0`, `assert isinstance(obj, MyClass)`) — use `print()` instead and follow with a `<details><summary>Output: <code>expression</code></summary>` block showing expected output. **Exception:** bare `assert` inside `def test_...` function bodies shown as pytest integration examples is allowed and idiomatic
 - Import a fictional package name in runnable `.md` examples — executable examples must import from actual test collection modules (`from tests import collection_deprecate`, `collection_misconfigured`, or `collection_chains`). For CI-template snippets that intentionally show a placeholder import, add `# phmdoctest:skip — CI template: replace my_package with your actual package` as the first line so phmdoctest skips execution
 - Skip test coverage for new features or bug fixes
 - Implement features without maintainer approval
@@ -156,4 +156,4 @@ This file provides quick reference for agents. For complete, authoritative guide
 - **PR review guidelines** → [Contributing: Reviewing PRs](.github/CONTRIBUTING.md#reviewing-prs)
 - **Security reporting** → [Security Policy](.github/SECURITY.md)
 - **Community guidelines** → [Code of Conduct](.github/CODE_OF_CONDUCT.md)
-- **Documentation site** → [Contributing: Documentation Site](.github/CONTRIBUTING.md#documentation-site)
+- **Documentation site** → [Contributing: Documentation Site](.github/CONTRIBUTING.md#-documentation-site)

CHANGELOG.md

@@ -22,6 +22,14 @@
 
 ### Fixed
 
+- **Audit scans no longer double-count re-exported wrappers.** Recursive `find_deprecation_wrappers` previously reported a wrapper once per importing module (e.g. once under the package root re-export and once under its defining submodule), inflating expiry counts and table rows; wrappers are now attributed to their defining module and deduplicated by identity across the scan. ([#215](https://github.com/Borda/pyDeprecate/pull/215))
+
+- **Audit report formatting no longer triggers chained proxies.** Formatting a report for a wrapper whose `target` is itself a deprecated proxy previously emitted a spurious `FutureWarning` from inside the audit tooling, consumed the proxy's warn budget, and printed a fabricated module path; proxy targets are now read via static metadata access. ([#215](https://github.com/Borda/pyDeprecate/pull/215))
+
+- **CLI: `all` and `status` no longer fail on plain directories.** Scanning a directory without `__init__.py` exited 1 from the status-table step even when every check passed; module-name resolution is now lazy and a status-rendering failure cannot change the aggregate exit code. ([#215](https://github.com/Borda/pyDeprecate/pull/215))
+
+- **CLI: version auto-detection resolves distributions whose name differs from the import name.** `importlib.metadata` lookup previously failed for packages like pyDeprecate itself (import `deprecate`, distribution `pyDeprecate`); the import name is now mapped via `packages_distributions()`, and expiry prints an explicit note when it runs without a resolved version. ([#215](https://github.com/Borda/pyDeprecate/pull/215))
+
 - **`num_warns` quota is now thread-safe.** Concurrent first calls to a shared wrapper could each pass the quota check before any counter increment, emitting up to one warning per thread instead of the configured budget; the warn path now synchronizes on a per-wrapper lock, so exactly `num_warns` warnings are emitted under concurrency. ([#214](https://github.com/Borda/pyDeprecate/pull/214))
 
 - **Cross-class forwarding between staticmethods no longer raises a spurious `TypeError`.** The cross-class guard exists to prevent `self` carrying the wrong type, but staticmethods have no `self`; `@deprecated(target=NewCls.compute)` on a staticmethod forwarding to another class's staticmethod is now allowed. ([#214](https://github.com/Borda/pyDeprecate/pull/214))

README.md

@@ -996,7 +996,7 @@ red
 
 </details>
 
-Each deprecated attribute name has its own independent warning counter — with `num_warns=1`, both `color` and `size` each emit one warning, not one shared across all entries. See [Selective attribute deprecation](https://borda.github.io/pyDeprecate/stable/guide/use-cases.html#selective-attribute-deprecation) in the docs for write/delete redirect and Enum member alias examples.
+Each deprecated attribute name has its own independent warning counter — with `num_warns=1`, both `color` and `size` each emit one warning, not one shared across all entries. See [Selective attribute deprecation](https://borda.github.io/pyDeprecate/stable/guide/classes.html#selective-attribute-deprecation) in the docs for write/delete redirect and Enum member alias examples.
 
 **Dataclass auto-expand** — when the wrapped class is a `@dataclass`, a single `deprecated_class(attrs_mapping={"old": "new"})` call automatically warns on both attribute access (`obj.old`) and constructor kwargs (`DC(old=5)`). No need to set `args_mapping` separately for a field rename. For non-`@dataclass` targets, `attrs_mapping` covers attribute access only — also set `args_mapping` to cover constructor kwargs.
 
@@ -1972,7 +1972,7 @@ print(MyClass(42).x)
 
 ### ❗ TypeError: `Failed mapping`
 
-**Problem:** `TypeError: Failed mapping of 'my_func', arguments missing in target source: ['old_arg']`
+**Problem:** `TypeError: Failed mapping of 'my_func', arguments not accepted by target: ['old_arg']`
 
 **Cause:** Your deprecated function has arguments that the target function doesn't accept.
 
@@ -2136,9 +2136,11 @@ True
 
 ### 📦 Deprecation Not Working Across Modules
 
-If you're moving functions to a different module or package, show the pattern rather than importing a non-existent package in the docs.
+**Problem:** The deprecation notice shows an unexpected path when a function is moved to a different module.
 
-The warning will correctly show the full path for real imports when used in your package.
+**Cause:** pyDeprecate resolves the target path from `target.__module__` and `target.__qualname__` at decoration time — not at call time. If the target is imported via an alias or re-export at the point where `@deprecated` is applied, the stored path reflects the alias, not the canonical location.
+
+**Solution:** Import the target from its canonical module location before applying `@deprecated`. The deprecation notice will then show the fully-qualified path where the function actually lives.
 
 ## 🤝 Contributing