pydoctor-cli 2.1.0__tar.gz → 2.2.0__tar.gz

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Premium Python environment diagnostic CLI — your project's personal physician.
 Author-email: Favour Bamgboye <demiladebamgboye@gmail.com>
 Maintainer-email: Favour Bamgboye <demiladebamgboye@gmail.com>
@@ -206,9 +206,9 @@ License:                                  Apache License
         See the License for the specific language governing permissions and
         limitations under the License.
         
-Project-URL: Homepage, https://pydoctor.vercel.app
+Project-URL: Homepage, https://pydoctor-docs.thally.app
 Project-URL: Repository, https://github.com/iamAgbaCoder/pydoctor-cli
-Project-URL: Documentation, https://pydoctor.vercel.app/docs
+Project-URL: Documentation, https://pydoctor-docs.thally.app
 Project-URL: Bug Tracker, https://github.com/iamAgbaCoder/pydoctor-cli/issues
 Project-URL: Changelog, https://github.com/iamAgbaCoder/pydoctor-cli/releases
 Keywords: pydoctor,diagnosis,dependency-checker,vulnerability-scanner,python-health,cli-tool,security-audit,static-analysis
@@ -253,6 +253,7 @@ Dynamic: license-file
 
 **PyDoctor** is a standalone, developer-friendly diagnostic assistant for Python environments. It acts like a personal physician for your code — scanning your project and environment to prescribe fixes for misconfigurations, dependencies, and security vulnerabilities.
 
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pydoctor-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/pydoctor-cli)
 [![CI Status](https://github.com/iamAgbaCoder/pydoctor-cli/actions/workflows/publish.yml/badge.svg)](https://github.com/iamAgbaCoder/pydoctor-cli/actions)
 [![PyPI version](https://img.shields.io/pypi/v/pydoctor-cli.svg?color=blue&style=flat-square)](https://pypi.org/project/pydoctor-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pydoctor-cli.svg?style=flat-square)](https://pypi.org/project/pydoctor-cli/)
@@ -299,6 +300,16 @@ pipx install pydoctor-cli
 pip install pydoctor-cli
 ```
 
+> Install `pydoctor-cli`, not `pydoctor`: that is an unrelated project (Twisted's API doc generator) that installs a command with the same name.
+
+PyDoctor scans your **project's** Python, wherever PyDoctor itself is installed. It uses the active virtualenv, or a `.venv`/`venv` in the project, and tells you which interpreter it chose. To choose one yourself:
+
+```bash
+pydoctor diagnose --python .venv/bin/python   # or set PYDOCTOR_PYTHON
+```
+
+📖 Full documentation: **https://pydoctor-docs.thally.app**
+
 ---
 
 ## ⚡ Usage
@@ -323,6 +334,19 @@ pydoctor fix
 
 ## Release History
 
+### v2.2.0
+Results you can trust: every fix in this release removes a case where PyDoctor reported a problem as fine, or got a severity wrong.
+
+- **Scans the right environment:** facts come from your project's interpreter, not PyDoctor's. Under pipx or `uv tool`, and in uv environments (which have no pip), 2.1.0 saw 0 packages and reported everything as OK. Works without pip (package metadata, `uv pip list --outdated`). New `--python` / `PYDOCTOR_PYTHON`; the report shows which interpreter was scanned and why.
+- **Fails loudly:** `ENV_PACKAGES_UNAVAILABLE` (error) when the environment can't be read, `ENV_DEPS_NOT_INSTALLED` when the scanned Python has none of your dependencies, and outdated checks that can't run say so instead of "all up to date".
+- **Virtualenv detection works:** it was always "active". The `diagnose` no-venv prompt now appears, and never blocks CI or piped runs.
+- **Real CVSS scores:** severity is computed from the CVSS v3 vector. Previously a 3.1 (Low) and a 9.8 (Critical) vulnerability were both shown as critical. GitHub's `MODERATE` is now medium.
+- **Right fix version:** for advisories with one fix per release line, `fix` targets your line (Django 5.1.2 → 5.1.4, not 4.2.17).
+- **CI guard finds real leaks:** scans every committed text file, adds Stripe, OpenAI, Anthropic, Slack, Google, private-key, database-URL and `SECRET_KEY` rules, flags committed `.env` files, and checks workflows for `pull_request_target` "pwn requests", script injection and `write-all` permissions. Findings have line numbers; add `# pydoctor: ignore` to silence one. Zero findings on Flask, Django, requests, httpx, FastAPI, DRF and pip.
+- **A score that moves:** a package's advisories count once, categories have diminishing returns, and any critical issue keeps the score below "Good". Expect different (usually higher) scores than 2.1.0.
+- **JSON:** includes `health`; `scan-security --json` reports advisory IDs, aliases, fixed version and CVSS score.
+- Smaller: database drivers, hashers and cache clients picked by Django settings count as used; faster advisory fetching; `--no-cache` no longer wipes the cache; circular import fixed; `github <repo>` and `docker` describe what they actually do.
+
 ### v2.1.0
 - **`pydoctor fix` reports what really happened:** upgrades are verified against the installed version. If a pin in `pyproject.toml` blocks an upgrade, pydoctor says so and shows the constraint instead of printing "fixed".
 - **One prompt per package:** vulnerable packages are offered once, with the advisory count, and upgraded to the lowest version that fixes every advisory.

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/README.md

@@ -4,6 +4,7 @@
 
 **PyDoctor** is a standalone, developer-friendly diagnostic assistant for Python environments. It acts like a personal physician for your code — scanning your project and environment to prescribe fixes for misconfigurations, dependencies, and security vulnerabilities.
 
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pydoctor-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/pydoctor-cli)
 [![CI Status](https://github.com/iamAgbaCoder/pydoctor-cli/actions/workflows/publish.yml/badge.svg)](https://github.com/iamAgbaCoder/pydoctor-cli/actions)
 [![PyPI version](https://img.shields.io/pypi/v/pydoctor-cli.svg?color=blue&style=flat-square)](https://pypi.org/project/pydoctor-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pydoctor-cli.svg?style=flat-square)](https://pypi.org/project/pydoctor-cli/)
@@ -50,6 +51,16 @@ pipx install pydoctor-cli
 pip install pydoctor-cli
 ```
 
+> Install `pydoctor-cli`, not `pydoctor`: that is an unrelated project (Twisted's API doc generator) that installs a command with the same name.
+
+PyDoctor scans your **project's** Python, wherever PyDoctor itself is installed. It uses the active virtualenv, or a `.venv`/`venv` in the project, and tells you which interpreter it chose. To choose one yourself:
+
+```bash
+pydoctor diagnose --python .venv/bin/python   # or set PYDOCTOR_PYTHON
+```
+
+📖 Full documentation: **https://pydoctor-docs.thally.app**
+
 ---
 
 ## ⚡ Usage
@@ -74,6 +85,19 @@ pydoctor fix
 
 ## Release History
 
+### v2.2.0
+Results you can trust: every fix in this release removes a case where PyDoctor reported a problem as fine, or got a severity wrong.
+
+- **Scans the right environment:** facts come from your project's interpreter, not PyDoctor's. Under pipx or `uv tool`, and in uv environments (which have no pip), 2.1.0 saw 0 packages and reported everything as OK. Works without pip (package metadata, `uv pip list --outdated`). New `--python` / `PYDOCTOR_PYTHON`; the report shows which interpreter was scanned and why.
+- **Fails loudly:** `ENV_PACKAGES_UNAVAILABLE` (error) when the environment can't be read, `ENV_DEPS_NOT_INSTALLED` when the scanned Python has none of your dependencies, and outdated checks that can't run say so instead of "all up to date".
+- **Virtualenv detection works:** it was always "active". The `diagnose` no-venv prompt now appears, and never blocks CI or piped runs.
+- **Real CVSS scores:** severity is computed from the CVSS v3 vector. Previously a 3.1 (Low) and a 9.8 (Critical) vulnerability were both shown as critical. GitHub's `MODERATE` is now medium.
+- **Right fix version:** for advisories with one fix per release line, `fix` targets your line (Django 5.1.2 → 5.1.4, not 4.2.17).
+- **CI guard finds real leaks:** scans every committed text file, adds Stripe, OpenAI, Anthropic, Slack, Google, private-key, database-URL and `SECRET_KEY` rules, flags committed `.env` files, and checks workflows for `pull_request_target` "pwn requests", script injection and `write-all` permissions. Findings have line numbers; add `# pydoctor: ignore` to silence one. Zero findings on Flask, Django, requests, httpx, FastAPI, DRF and pip.
+- **A score that moves:** a package's advisories count once, categories have diminishing returns, and any critical issue keeps the score below "Good". Expect different (usually higher) scores than 2.1.0.
+- **JSON:** includes `health`; `scan-security --json` reports advisory IDs, aliases, fixed version and CVSS score.
+- Smaller: database drivers, hashers and cache clients picked by Django settings count as used; faster advisory fetching; `--no-cache` no longer wipes the cache; circular import fixed; `github <repo>` and `docker` describe what they actually do.
+
 ### v2.1.0
 - **`pydoctor fix` reports what really happened:** upgrades are verified against the installed version. If a pin in `pyproject.toml` blocks an upgrade, pydoctor says so and shows the constraint instead of printing "fixed".
 - **One prompt per package:** vulnerable packages are offered once, with the advisory count, and upgraded to the lowest version that fixes every advisory.

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/pydoctor/__init__.py

@@ -9,6 +9,6 @@ Author: Favour Bamgboye
 License: MIT
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 __author__ = "Favour Bamgboye"
 __description__ = "Python environment diagnostic CLI — your project's doctor."

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/pydoctor/analysis/health_score.py

@@ -6,6 +6,7 @@ Calculates the numerical project health score and verdict.
 
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass
 
 from pydoctor.core.report import DiagnosisReport, Issue
@@ -18,20 +19,62 @@ class HealthMetrics:
     message: str
 
 
+# Each category can cost at most this many points. Within a category every
+# extra issue still lowers the score, but by less (diminishing returns), so
+# fixing issues in a project with dozens of them visibly moves the score.
+CATEGORY_CAPS: dict[str, float] = {
+    "security": 60,
+    "ci": 50,
+    "dependencies": 40,
+    "environment": 30,
+    "outdated": 15,
+    "unused": 10,
+}
+
+# A project with any critical issue can't be rated Good or Excellent.
+CRITICAL_CEILING = 69
+
+# Issues that mean part of the scan didn't run.
+INCOMPLETE_CODES = {"ENV_PACKAGES_UNAVAILABLE", "SEC_SCAN_INCOMPLETE"}
+
+
 def calculate_health(report: DiagnosisReport) -> HealthMetrics:
     """
     Calculate project health score (0-100) based on identified issues.
     """
     score = _compute_score(report)
-    categories = list({i.category for i in report.issues})
-    return _get_verdict(score, categories)
+    categories = list({i.category for i in report.issues if i.code not in INCOMPLETE_CODES})
+    metrics = _get_verdict(score, categories)
+    if any(i.code in INCOMPLETE_CODES for i in report.issues):
+        metrics.verdict = "Incomplete"
+        metrics.message = (
+            "Some checks couldn't run, so this score only covers what was checked. "
+            "See the errors above."
+        )
+    return metrics
 
 
 def _compute_score(report: DiagnosisReport) -> int:
-    score = 100
+    raw: dict[str, float] = {}
+    # One upgrade usually fixes every advisory for a package, so a package
+    # costs the penalty of its worst advisory, not one penalty per advisory.
+    per_package: dict[str, int] = {}
     for issue in report.issues:
-        score -= _calculate_issue_penalty(issue)
-    return max(0, score)
+        penalty = _calculate_issue_penalty(issue)
+        if issue.code == "SEC_VULNERABILITY" and issue.package:
+            per_package[issue.package] = max(per_package.get(issue.package, 0), penalty)
+            continue
+        raw[issue.category] = raw.get(issue.category, 0) + penalty
+    if per_package:
+        raw["security"] = raw.get("security", 0) + sum(per_package.values())
+    lost = 0.0
+    for category, points in raw.items():
+        cap = CATEGORY_CAPS.get(category)
+        lost += cap * (1 - math.exp(-points / cap)) if cap else points
+    score = max(0, round(100 - lost))
+    if any(i.severity.lower() == "critical" for i in report.issues):
+        score = min(score, CRITICAL_CEILING)
+    return score
 
 
 def _calculate_issue_penalty(issue: Issue) -> int:

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/pydoctor/cache/cache_manager.py

@@ -79,7 +79,7 @@ class CacheManager:
 
         return entry.get("value")
 
-    def set(self, key: str, value: Any) -> None:
+    def set(self, key: str, value: Any, save: bool = True) -> None:
         """
         Store a value in the cache with the current timestamp.
 
@@ -87,8 +87,15 @@ class CacheManager:
         ----------
         key:   Cache key.
         value: Any JSON-serialisable value.
+        save:  Write to disk now. Pass False when setting many keys, then call
+               ``save()`` once (writing the whole file per key is quadratic).
         """
         self._data[key] = {"_ts": time.time(), "value": value}
+        if save:
+            self._save()
+
+    def save(self) -> None:
+        """Persist the cache to disk."""
         self._save()
 
     def invalidate(self, key: str) -> None:

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/pydoctor/cli/main.py

@@ -84,8 +84,8 @@ _HELP_EPILOG = """
 
 [section]🏥  COMMUNITY & SUPPORT[/]
 
-  [label]Docs:[/][pkg] https://pydoctor.vercel.app/docs[/]
-  [label]Version:[/][info] v2.1.0 (Premium Kernel Edition)[/]
+  [label]Docs:[/][pkg] https://pydoctor-docs.thally.app[/]
+  [label]Version:[/][info] v2.2.0 (Premium Kernel Edition)[/]
 
 [kernel]Healthy code leads to healthy deployments. Keep your environment sterile.[/]
 """
@@ -122,6 +122,12 @@ _PATH_ARG = typer.Option(..., "--path", "-p", help="Project directory to scan.")
 _JSON_ARG = typer.Option(..., "--json", "-j", help="Output results as JSON.")
 _VERBOSE_ARG = typer.Option(..., "--verbose", "-v", help="Show detailed output and timing.")
 _NO_CACHE_ARG = typer.Option(..., "--no-cache", help="Bypass the local vulnerability cache.")
+_PYTHON_ARG = typer.Option(
+    ...,
+    "--python",
+    help="Python interpreter of the project to scan (default: auto-detect). "
+    "Also settable with PYDOCTOR_PYTHON.",
+)
 
 
 # ──────────────────────────────────────────────────────────────
@@ -137,11 +143,10 @@ def _run_scan(
     as_json: bool = False,
     ci_mode: bool = False,
     command: str | None = None,
+    python: str | None = None,
+    ctx: ProjectContext | None = None,
 ) -> DiagnosisReport:  # noqa: C901
     """Run the Analyzer with Rich progress indicators."""
-    if no_cache:
-        CacheManager().clear()
-
     if not as_json:
         console.print("[section]Scanning project...[/]")
 
@@ -158,7 +163,14 @@ def _run_scan(
             console.print(f"[kernel]»[/] Checking {label.lower().replace(' ', ' ')}")
 
     if as_json:
-        analyzer = Analyzer(project_path=path, scanners=scanners, verbose=verbose)
+        analyzer = Analyzer(
+            project_path=path,
+            scanners=scanners,
+            verbose=verbose,
+            python=python,
+            ctx=ctx,
+            no_cache=no_cache,
+        )
         report = analyzer.run(on_progress=None)
         report.command = command
         return report
@@ -175,6 +187,9 @@ def _run_scan(
             project_path=path,
             scanners=scanners,
             verbose=verbose,
+            python=python,
+            ctx=ctx,
+            no_cache=no_cache,
         )
         report = analyzer.run(on_progress=progress_callback)
         report.command = command
@@ -182,6 +197,14 @@ def _run_scan(
     return report
 
 
+def _is_interactive() -> bool:
+    """True when a person can answer prompts (not CI, not piped input)."""
+    try:
+        return sys.stdin.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
 def _output(report: DiagnosisReport, as_json: bool, verbose: bool = False) -> None:
     if as_json:
         render_json(report)
@@ -213,23 +236,37 @@ def _exit_code(report: DiagnosisReport, path: str = ".") -> int:
 @app.command(rich_help_panel="CORE COMMANDS")
 def diagnose(
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
     no_cache: Annotated[bool, _NO_CACHE_ARG] = False,
 ) -> None:  # noqa: C901
     """🩺  Run a **full** diagnosis of your Python project."""
+    ctx = None
     if not json:
-        ctx = ProjectContext.from_path(path)
-        if not ctx.in_virtualenv:
-            console.print("[warning]⚠ No virtual environment detected in this project.[/]")
-            if not Confirm.ask("Do you want to proceed using global system packages?"):
+        ctx = ProjectContext.from_path(path, python=python)
+        if not ctx.env_error and not ctx.in_virtualenv:
+            console.print(
+                "[warning]⚠ No virtual environment detected. Scanning "
+                f"{ctx.python_executable} ({ctx.python_source}).[/]"
+            )
+            # Never block a non-interactive run (CI, pipes) on a prompt.
+            if _is_interactive() and not Confirm.ask(
+                "Do you want to proceed using global system packages?"
+            ):
                 console.print(
                     "\n[info]ℹ Cancelled. Please activate a virtual environment and try again.[/]"
                 )
                 raise typer.Exit()
 
     report = _run_scan(
-        path=path, verbose=verbose, no_cache=no_cache, as_json=json, command="diagnose"
+        path=path,
+        verbose=verbose,
+        no_cache=no_cache,
+        as_json=json,
+        command="diagnose",
+        python=python,
+        ctx=ctx,
     )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
@@ -238,12 +275,15 @@ def diagnose(
 @app.command(rich_help_panel="CORE COMMANDS")
 def check(
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     ci: bool = typer.Option(False, "--ci", help="Run in CI/CD guard mode."),
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
     """🛡️  Perform security and health checks. Use --ci for pipeline shielding."""
-    report = _run_scan(path=path, ci_mode=ci, verbose=verbose, as_json=json, command="check")
+    report = _run_scan(
+        path=path, ci_mode=ci, verbose=verbose, as_json=json, command="check", python=python
+    )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
 
@@ -253,7 +293,7 @@ def docker(
     image: Annotated[str | None, typer.Argument(help="Docker image to scan (optional).")] = None,
     path: Annotated[str, _PATH_ARG] = ".",
 ) -> None:
-    """🐳  Diagnose Python issues inside **Docker** containers."""
+    """🐳  [Preview] Check that a Dockerfile exists and uses a Python base image."""
     console.print(Panel("[section]🐳 Docker Environment Doctor[/]", border_style="rule"))
     console.print("[kernel]Scanning for Dockerfile and container runtime...[/]")
     dockerfile = Path(path) / "Dockerfile"
@@ -268,17 +308,26 @@ def docker(
             )
         else:
             console.print("[ok]✔[/] Python base image identified.")
-    console.print("\n[info]ℹ This feature is in beta. Full container introspection coming soon.[/]")
+    console.print(
+        "\n[info]ℹ Preview: this only checks the Dockerfile. It doesn't inspect images or "
+        "containers yet.[/]"
+    )
 
 
 @app.command(rich_help_panel="SECURITY & CI/CD")
 def github(
     repo: Annotated[str | None, typer.Argument(help="GitHub repository URL (optional).")] = None,
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
-    """🐙  Integrate with **GitHub** for repository-wide health scans."""
+    """🐙  Run the CI/CD guard on a local git checkout."""
+    if repo:
+        err_console.print(
+            "[warning]⚠ Scanning remote repositories isn't supported yet; "
+            f"ignoring {repo} and scanning {path}.[/]"
+        )
     if not json:
         console.print(Panel("[section]🐙 GitHub Repository Doctor[/]", border_style="rule"))
         if not repo:
@@ -295,7 +344,9 @@ def github(
                 console.print("[ok]✔[/] Local git repository detected.")
         console.print("\n[info]ℹ Running pydoctor on the current branch...[/]")
 
-    report = _run_scan(path=path, ci_mode=True, verbose=verbose, as_json=json, command="github")
+    report = _run_scan(
+        path=path, ci_mode=True, verbose=verbose, as_json=json, command="github", python=python
+    )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
 
@@ -306,12 +357,18 @@ def github(
 @app.command(name="scan-security", rich_help_panel="SECURITY & CI/CD")
 def scan_security(
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
     """🔒 Scan installed packages for known vulnerabilities (OSV)."""
     report = _run_scan(
-        scanners=["security"], path=path, verbose=verbose, as_json=json, command="scan-security"
+        scanners=["security"],
+        path=path,
+        verbose=verbose,
+        as_json=json,
+        command="scan-security",
+        python=python,
     )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
@@ -325,12 +382,18 @@ def scan_security(
 @app.command(name="scan-unused", rich_help_panel="RESOURCE HYGIENE")
 def scan_unused(
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
     """🧹 Detect unused packages via AST analysis."""
     report = _run_scan(
-        scanners=["unused"], path=path, verbose=verbose, as_json=json, command="scan-unused"
+        scanners=["unused"],
+        path=path,
+        verbose=verbose,
+        as_json=json,
+        command="scan-unused",
+        python=python,
     )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
@@ -339,12 +402,18 @@ def scan_unused(
 @app.command(name="scan-deps", rich_help_panel="RESOURCE HYGIENE")
 def scan_deps(
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
     """📦 Scan for dependency version conflicts."""
     report = _run_scan(
-        scanners=["dependencies"], path=path, verbose=verbose, as_json=json, command="scan-deps"
+        scanners=["dependencies"],
+        path=path,
+        verbose=verbose,
+        as_json=json,
+        command="scan-deps",
+        python=python,
     )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
@@ -353,12 +422,18 @@ def scan_deps(
 @app.command(name="check-env", rich_help_panel="RESOURCE HYGIENE")
 def check_env(
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
     """🌍 Verify Python and virtual environment health."""
     report = _run_scan(
-        scanners=["environment"], path=path, verbose=verbose, as_json=json, command="check-env"
+        scanners=["environment"],
+        path=path,
+        verbose=verbose,
+        as_json=json,
+        command="check-env",
+        python=python,
     )
     _output(report, as_json=json, verbose=verbose)
     raise typer.Exit(code=_exit_code(report, path))
@@ -373,6 +448,7 @@ def fix(
         list[str] | None, typer.Argument(help="Specific packages to fix (optional).")
     ] = None,
     path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
     safe: bool = typer.Option(True, "--safe/--no-safe", help="Confirm each action."),
     upgrade: bool = typer.Option(True, "--upgrade/--no-upgrade", help="Upgrade outdated."),
     remove: bool = typer.Option(False, "--remove/--no-remove", help="Remove unused."),
@@ -383,8 +459,8 @@ def fix(
             "[section]🔧 PyDoctor Auto-Fix[/]\n\nScanning for fixable issues …", border_style="rule"
         )
     )
-    report_data = _run_scan(path=path)
-    ctx = ProjectContext.from_path(path)
+    report_data = _run_scan(path=path, python=python)
+    ctx = report_data.ctx  # reuse the scan's context instead of probing again
     if packages:
         _filter_issues_by_targets(report_data, packages)
     actions = 0
@@ -463,8 +539,16 @@ def _norm(name: str) -> str:
 
 def _installed_version(ctx, pkg: str) -> str | None:
     """Return the version of ``pkg`` installed in the project's environment."""
+    from pydoctor.utils.env_probe import probe_environment
+
+    probe, _ = probe_environment(ctx.project_python)
+    packages = (
+        probe.packages
+        if probe
+        else get_installed_packages(python_executable=ctx.project_python)  # fallback: pip
+    )
     target = _norm(pkg)
-    for name, version in get_installed_packages(python_executable=ctx.project_python).items():
+    for name, version in packages.items():
         if _norm(name) == target:
             return version
     return None

pydoctor_cli-2.2.0/pydoctor/core/__init__.py

@@ -0,0 +1,17 @@
+"""pydoctor/core/__init__.py"""
+
+from pydoctor.core.project import ProjectContext
+from pydoctor.core.report import DiagnosisReport, Issue
+
+__all__ = ["Issue", "DiagnosisReport", "ProjectContext", "Analyzer"]
+
+
+def __getattr__(name: str):
+    # Imported lazily: Analyzer imports every scanner, and scanners import
+    # pydoctor.core, so an eager import here made
+    # `import pydoctor.scanners.vulnerability_scanner` fail with a circular import.
+    if name == "Analyzer":
+        from pydoctor.core.analyzer import Analyzer
+
+        return Analyzer
+    raise AttributeError(name)

{pydoctor_cli-2.1.0 → pydoctor_cli-2.2.0}/pydoctor/core/analyzer.py

@@ -48,6 +48,64 @@ SCANNER_REGISTRY: dict[str, Callable[[ProjectContext], list[Issue]]] = {
 }
 
 
+# Scanners that read the installed environment (everything except "ci").
+_ENV_SCANNERS = {"environment", "dependencies", "outdated", "security", "unused"}
+
+
+def context_issues(ctx: ProjectContext, scanner_keys: list[str]) -> list[Issue]:
+    """
+    Problems with the scan itself, reported once regardless of which scanners run.
+
+    These exist so that a scan which couldn't see the project's packages fails
+    loudly instead of returning a clean bill of health.
+    """
+    if not _ENV_SCANNERS.intersection(scanner_keys):
+        return []
+    if ctx.env_error:
+        return [
+            Issue(
+                category="environment",
+                code="ENV_PACKAGES_UNAVAILABLE",
+                severity=Severity.ERROR,
+                title="Couldn't read the project's installed packages",
+                description=(
+                    f"PyDoctor tried {ctx.project_python} ({ctx.python_source}) and got: "
+                    f"{ctx.env_error}. Security, dependency, outdated and unused checks "
+                    "were not run."
+                ),
+                recommendation=(
+                    "Activate the project's virtualenv, or point PyDoctor at its interpreter "
+                    "with --python path/to/python (or PYDOCTOR_PYTHON)."
+                ),
+                extra={"python": ctx.project_python, "source": ctx.python_source},
+            )
+        ]
+    if ctx.declared_deps:
+        from pydoctor.utils.env_probe import normalise_name
+
+        missing = [d for d in ctx.declared_deps if normalise_name(d) not in ctx.installed_packages]
+        if len(missing) == len(ctx.declared_deps):
+            return [
+                Issue(
+                    category="environment",
+                    code="ENV_DEPS_NOT_INSTALLED",
+                    severity=Severity.WARNING,
+                    title="None of the project's dependencies are installed in the scanned Python",
+                    description=(
+                        f"Scanned {ctx.python_executable} ({ctx.python_source}), which has none "
+                        f"of the {len(ctx.declared_deps)} declared dependencies installed. "
+                        "Results describe that interpreter, not your project."
+                    ),
+                    recommendation=(
+                        "Install the dependencies, activate the project's virtualenv, or use "
+                        "--python path/to/python."
+                    ),
+                    extra={"python": ctx.project_python, "missing": sorted(missing)},
+                )
+            ]
+    return []
+
+
 # ──────────────────────────────────────────────────────────────
 # Analyzer
 # ──────────────────────────────────────────────────────────────
@@ -70,10 +128,16 @@ class Analyzer:
         project_path: str = ".",
         scanners: list[str] | None = None,
         verbose: bool = False,
+        python: str | None = None,
+        ctx: ProjectContext | None = None,
+        no_cache: bool = False,
     ) -> None:
         self._project_path = project_path
         self._scanner_keys = scanners or list(SCANNER_REGISTRY.keys())
         self._verbose = verbose
+        self._python = python
+        self._ctx = ctx
+        self._no_cache = no_cache
 
     # ── Public API ─────────────────────────────────────────────
 
@@ -92,9 +156,11 @@ class Analyzer:
         wall_start = time.perf_counter()
 
         # Build project context once — shared across all scanners
-        ctx = ProjectContext.from_path(self._project_path)
+        ctx = self._ctx or ProjectContext.from_path(self._project_path, python=self._python)
+        ctx.no_cache = self._no_cache
         report = DiagnosisReport(scan_path=str(ctx.root), ctx=ctx)
         scanner_timings: dict[str, float] = {}
+        report.extend(context_issues(ctx, self._scanner_keys))
 
         # Parallel execution for independence (each scanner gets its own thread)
         with ThreadPoolExecutor(max_workers=min(MAX_WORKERS, len(self._scanner_keys))) as pool: