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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.0.0
+Version: 2.1.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>
@@ -323,6 +323,16 @@ pydoctor fix
 
 ## Release History
 
+### 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.
+- **No accidental removals:** `pydoctor fix <package>` no longer offers to uninstall it. Removal only runs with `--remove`.
+- **Fewer false "unused" reports:** packages imported under a different name (`decouple`), loaded from strings (Django `INSTALLED_APPS`, `MIDDLEWARE`, backends), or run from a Procfile/Dockerfile (`gunicorn`) are recognised as used. Remaining findings are labelled "Possibly unused".
+
+### v2.0.1
+- **Security scans fail closed:** if the OSV database can't be reached, pydoctor now reports `SEC_SCAN_INCOMPLETE` (error, exit 1) instead of a clean result.
+- **No more double-counted advisories:** advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.
+
 ### v2.0.0
 
 - **🚀 Major UI/UX Revamp**: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.

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

@@ -74,6 +74,16 @@ pydoctor fix
 
 ## Release History
 
+### 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.
+- **No accidental removals:** `pydoctor fix <package>` no longer offers to uninstall it. Removal only runs with `--remove`.
+- **Fewer false "unused" reports:** packages imported under a different name (`decouple`), loaded from strings (Django `INSTALLED_APPS`, `MIDDLEWARE`, backends), or run from a Procfile/Dockerfile (`gunicorn`) are recognised as used. Remaining findings are labelled "Possibly unused".
+
+### v2.0.1
+- **Security scans fail closed:** if the OSV database can't be reached, pydoctor now reports `SEC_SCAN_INCOMPLETE` (error, exit 1) instead of a clean result.
+- **No more double-counted advisories:** advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.
+
 ### v2.0.0
 
 - **🚀 Major UI/UX Revamp**: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.

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

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

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

@@ -24,6 +24,7 @@ Global flags
 
 from __future__ import annotations
 
+import re
 import subprocess
 import sys
 from pathlib import Path
@@ -37,6 +38,7 @@ if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
         pass
 
 import typer
+from packaging.version import InvalidVersion, Version
 from rich.console import Console
 from rich.panel import Panel
 from rich.progress import (
@@ -60,6 +62,7 @@ from pydoctor.reports.table_formatter import (
 )
 from pydoctor.reports.terminal_colors import PYDOCTOR_THEME
 from pydoctor.utils.pip_utils import (
+    get_installed_packages,
     remove_from_requirements_file,
     update_requirements_file,
 )
@@ -82,7 +85,7 @@ _HELP_EPILOG = """
 [section]🏥  COMMUNITY & SUPPORT[/]
 
   [label]Docs:[/][pkg] https://pydoctor.vercel.app/docs[/]
-  [label]Version:[/][info] v2.0.0 (Premium Kernel Edition)[/]
+  [label]Version:[/][info] v2.1.0 (Premium Kernel Edition)[/]
 
 [kernel]Healthy code leads to healthy deployments. Keep your environment sterile.[/]
 """
@@ -385,12 +388,18 @@ def fix(
     if packages:
         _filter_issues_by_targets(report_data, packages)
     actions = 0
-    actions += _fix_vulnerabilities(report_data, ctx, safe)
+    handled: set[str] = set()
+    actions += _fix_vulnerabilities(report_data, ctx, safe, handled)
     if upgrade:
-        actions += _fix_outdated(report_data, ctx, safe)
+        actions += _fix_outdated(report_data, ctx, safe, handled)
     actions += _fix_dependencies(report_data, ctx, safe)
-    if remove or packages:
+    if remove:
         actions += _fix_unused(report_data, ctx, safe)
+    elif any(i.code == "UNUSED_PACKAGE" for i in report_data.issues):
+        console.print(
+            "\n[dim_text]Possibly unused packages were found but not removed. "
+            "Review them, then run `pydoctor fix --remove` to remove them.[/]"
+        )
     actions += _fix_venv(report_data, path, safe)
     _render_fix_summary(actions)
 
@@ -405,34 +414,117 @@ def _filter_issues_by_targets(report_data, packages):
         raise typer.Exit()
 
 
-def _run_package_manager_command(ctx, pkg, action, upgrade=False):
-    path = str(ctx.root)
-    if ctx.is_poetry:
-        cmd = ["poetry", "add", pkg] if action == "add" else ["poetry", "remove", pkg]
-        if action == "update":
-            cmd = ["poetry", "update", pkg]
-        console.print(f"  [dim_text]Running: {' '.join(cmd)}[/]")
-        return subprocess.run(cmd, cwd=path)
+def _manager_command(ctx, pkg, action, upgrade=False, min_version=None):
+    """
+    Build the uv / Poetry / pdm command for one package, or None for plain pip.
+
+    When ``min_version`` is given for an add/update, the requirement is passed as
+    ``pkg>=min_version`` so the constraint in pyproject.toml is rewritten. A bare
+    ``uv add --upgrade pkg`` keeps an existing pin such as ``pkg==1.0`` and
+    silently changes nothing.
+    """
+    requirement = f"{pkg}>={min_version}" if min_version else pkg
     if ctx.is_uv:
-        cmd = ["uv", "add", pkg] if action == "add" else ["uv", "remove", pkg]
-        if upgrade:
-            cmd = ["uv", "add", "--upgrade", pkg]
-        console.print(f"  [dim_text]Running: {' '.join(cmd)}[/]")
-        return subprocess.run(cmd, cwd=path)
-    if ctx.is_pdm:
-        cmd = ["pdm", "add", pkg] if action == "add" else ["pdm", "remove", pkg]
-        if action == "update":
-            cmd = ["pdm", "update", pkg]
+        if action == "remove":
+            return ["uv", "remove", pkg]
+        if upgrade and not min_version:
+            return ["uv", "add", "--upgrade-package", pkg, pkg]
+        return ["uv", "add", requirement]
+    for tool, enabled in (("poetry", ctx.is_poetry), ("pdm", ctx.is_pdm)):
+        if enabled:
+            if action == "remove":
+                return [tool, "remove", pkg]
+            if action == "update" and not min_version:
+                return [tool, "update", pkg]
+            return [tool, "add", requirement]
+    return None
+
+
+def _run_package_manager_command(ctx, pkg, action, upgrade=False, min_version=None):
+    """Run the project's package manager (or pip) for one package."""
+    cmd = _manager_command(ctx, pkg, action, upgrade, min_version)
+    if cmd:
         console.print(f"  [dim_text]Running: {' '.join(cmd)}[/]")
-        return subprocess.run(cmd, cwd=path)
+        return subprocess.run(cmd, cwd=str(ctx.root))
     if action == "remove":
         return run_pip_command(["uninstall", "-y", pkg], python_executable=ctx.project_python)
-    else:
-        args = ["install"]
-        if upgrade:
-            args.append("--upgrade")
-        args.append(pkg)
-        return run_pip_command(args, python_executable=ctx.project_python)
+    args = ["install"]
+    if upgrade:
+        args.append("--upgrade")
+    args.append(f"{pkg}>={min_version}" if min_version else pkg)
+    console.print(f"  [dim_text]Running: pip {' '.join(args)}[/]")
+    return run_pip_command(args, python_executable=ctx.project_python)
+
+
+def _norm(name: str) -> str:
+    """Normalise a distribution name (PEP 503)."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _installed_version(ctx, pkg: str) -> str | None:
+    """Return the version of ``pkg`` installed in the project's environment."""
+    target = _norm(pkg)
+    for name, version in get_installed_packages(python_executable=ctx.project_python).items():
+        if _norm(name) == target:
+            return version
+    return None
+
+
+def _declared_constraint(ctx, pkg: str) -> str | None:
+    """Find how ``pkg`` is declared in pyproject.toml or requirements.txt, if at all."""
+    name = re.escape(pkg).replace(r"\-", "[-_.]").replace(r"\_", "[-_.]")
+    pattern = re.compile(
+        rf"""^\s*["']?({name}\s*(\[[^\]]*\])?\s*[<>=!~^][^"'#,\n]*(,[^"'#\n]*)?)""", re.I | re.M
+    )
+    for fname in ("pyproject.toml", "requirements.txt"):
+        fpath = ctx.root / fname
+        if fpath.is_file():
+            match = pattern.search(fpath.read_text(encoding="utf-8", errors="ignore"))
+            if match:
+                return match.group(1).strip().rstrip(",").strip()
+    return None
+
+
+def _max_version(versions):
+    best = None
+    for v in versions:
+        try:
+            parsed = Version(v)
+        except (InvalidVersion, TypeError):
+            continue
+        if best is None or parsed > best:
+            best = parsed
+    return str(best) if best else None
+
+
+def _apply_and_verify(ctx, pkg, action, min_version, verb):
+    """
+    Run the upgrade, then confirm the installed version actually changed.
+
+    A package manager can exit 0 without changing anything (for example when a
+    pin in pyproject.toml blocks the upgrade), so the exit code alone is not
+    proof of a fix.
+    """
+    before = _installed_version(ctx, pkg)
+    result = _run_package_manager_command(ctx, pkg, action, True, min_version)
+    if result.returncode != 0:
+        console.print(f" [error]✖ {pkg} could not be {verb} (exit code {result.returncode}).[/]")
+        return False
+    after = _installed_version(ctx, pkg)
+    if before and after == before:
+        console.print(
+            f" [warning]⚠ {pkg} is still {after}. The command succeeded but nothing changed.[/]"
+        )
+        constraint = _declared_constraint(ctx, pkg)
+        if constraint:
+            console.print(
+                f'   [dim_text]Your project declares "{constraint}", which blocks the upgrade. '
+                f"Loosen it, then run `pydoctor fix {pkg}` again.[/]"
+            )
+        return False
+    change = f"{before} → {after}" if before and after else (after or "")
+    console.print(f" [ok]✔ {pkg} {verb}{f' ({change})' if change else ''}.[/]")
+    return True
 
 
 def _update_pip_requirements(ctx, pkg, safe, action, version_spec=""):
@@ -449,27 +541,51 @@ def _update_pip_requirements(ctx, pkg, safe, action, version_spec=""):
             update_requirements_file(req_file, pkg, version_spec)
 
 
-def _fix_vulnerabilities(report, ctx, safe):
-    vulnerable = [i for i in report.issues if i.code == "SEC_VULNERABILITY"]
-    if not vulnerable:
+def _fix_vulnerabilities(report, ctx, safe, handled=None):
+    """Offer one upgrade per vulnerable package, to the lowest version that fixes every advisory."""
+    handled = handled if handled is not None else set()
+    groups: dict[str, list] = {}
+    for i in report.issues:
+        if i.code == "SEC_VULNERABILITY" and i.package:
+            groups.setdefault(i.package, []).append(i)
+    if not groups:
         return 0
+    latest = {
+        _norm(i.package): i.extra.get("latest_version")
+        for i in report.issues
+        if i.code == "PKG_OUTDATED" and i.package
+    }
     actions = 0
-    for i in vulnerable:
-        if i.package and (not safe or Confirm.ask(f" Fix {i.package}?")):
-            if _run_package_manager_command(ctx, i.package, "add", True).returncode == 0:
-                console.print(f" [ok]✔ {i.package} fixed.[/]")
+    for pkg, issues in groups.items():
+        fixed = [i.extra.get("fixed_in") for i in issues if i.extra.get("fixed_in")]
+        target = _max_version(fixed) or latest.get(_norm(pkg))
+        critical = sum(1 for i in issues if i.severity == "critical")
+        summary = f"{len(issues)} advisor{'y' if len(issues) == 1 else 'ies'}"
+        if critical:
+            summary += f", {critical} critical"
+        if len(fixed) < len(issues):
+            summary += f", {len(issues) - len(fixed)} with no fix released yet"
+        to = f" to {target}" if target else ""
+        handled.add(_norm(pkg))
+        if not safe or Confirm.ask(f" Upgrade {pkg}{to}? ({summary})"):
+            if _apply_and_verify(ctx, pkg, "add", target, "upgraded"):
                 actions += 1
     return actions
 
 
-def _fix_outdated(report, ctx, safe):
+def _fix_outdated(report, ctx, safe, handled=None):
+    handled = handled if handled is not None else set()
     outdated = [i for i in report.issues if i.code == "PKG_OUTDATED"]
     actions = 0
     for i in outdated:
         pkg = i.package
-        if pkg and (not safe or Confirm.ask(f" Upgrade {pkg}?")):
-            if _run_package_manager_command(ctx, pkg, "update", True).returncode == 0:
-                console.print(f" [ok]✔ {pkg} upgraded.[/]")
+        if not pkg or _norm(pkg) in handled:
+            continue
+        handled.add(_norm(pkg))
+        target = i.extra.get("latest_version")
+        to = f" to {target}" if target else ""
+        if not safe or Confirm.ask(f" Upgrade {pkg}{to}?"):
+            if _apply_and_verify(ctx, pkg, "update", target, "upgraded"):
                 actions += 1
     return actions
 

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pydoctor/scanners/unused_package_scanner.py

@@ -13,16 +13,30 @@ Algorithm
    (requirements.txt / pyproject.toml).
 5. Packages that are declared but never imported are flagged as unused.
 
+Import names are mapped to distributions with the project's own
+``importlib.metadata.packages_distributions()``, so packages whose import
+name differs from their PyPI name (``decouple`` → ``python-decouple``,
+``jwt`` → ``pyjwt``) are matched correctly.
+
+A dependency also counts as used when:
+- a string constant in the code names one of its modules
+  (Django ``INSTALLED_APPS``, ``MIDDLEWARE``, ``CACHES`` backends, …), or
+- it is named in a deploy or run file (Procfile, Dockerfile, compose files,
+  Makefile, shell scripts, CI workflows), e.g. ``gunicorn`` or ``uvicorn``.
+
 Limitations
 ───────────
-- Dynamic imports (``importlib.import_module``, ``__import__``) are not
-  tracked — false positives may occur for packages loaded dynamically.
+- Dynamic imports built at runtime (``importlib.import_module(f"...")``)
+  are not tracked, so findings are reported as *possibly* unused.
 - Standard library modules are excluded automatically.
 - Only *declared* dependencies are checked; transitive installs are not.
 """
 
 from __future__ import annotations
 
+import json
+import re
+import subprocess
 import sys
 
 from pydoctor.config.settings import Severity
@@ -30,6 +44,7 @@ from pydoctor.core.project import ProjectContext
 from pydoctor.core.report import Issue
 from pydoctor.utils.parser_utils import (
     extract_imports_from_project,
+    extract_string_module_refs,
     import_name_to_package,
 )
 
@@ -72,9 +87,17 @@ def scan(ctx: ProjectContext) -> list[Issue]:
                 category=CATEGORY,
                 code="UNUSED_PACKAGE",
                 severity=Severity.WARNING,
-                title=f"Unused dependency: {pkg}",
-                description=f"No imports corresponding to '{pkg}' were found, and it is not required by any used packages.",
-                recommendation=f"pip uninstall {pkg}",
+                title=f"Possibly unused dependency: {pkg}",
+                description=(
+                    f"No import, module-path string, or run command referencing '{pkg}' "
+                    "was found, and no used package depends on it. Packages loaded "
+                    "dynamically or by plugins can still be missed."
+                ),
+                recommendation=(
+                    f"Confirm '{pkg}' is unused, then remove it with your package manager "
+                    "(or `pydoctor fix --remove`). If it is used, add it to "
+                    "ignored_packages in [tool.pydoctor]."
+                ),
                 package=pkg,
             )
         )
@@ -89,7 +112,7 @@ def scan(ctx: ProjectContext) -> list[Issue]:
                 category=CATEGORY,
                 code="UNUSED_TRANSITIVE",
                 severity=Severity.INFO,
-                title=f"Transitive dependency: {pkg} [dim](required by {parent_str})[/]",
+                title=f"Transitive dependency: {pkg} (required by {parent_str})",
                 description=f"'{pkg}' is declared explicitly but only used indirectly via {parent_str}.",
                 recommendation="Consider removing from requirements to keep dependencies lean.",
                 package=pkg,
@@ -125,15 +148,95 @@ def _check_preconditions(ctx: ProjectContext) -> list[Issue]:
     return []
 
 
+def _norm(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
 def _get_imported_packages(ctx: ProjectContext) -> set[str]:
     names = extract_imports_from_project(ctx.python_files)
-    pkgs = set()
+    dist_map = _distribution_map(ctx)
+    pkgs: set[str] = set()
     for n in names:
         pkgs.add(import_name_to_package(n))
         pkgs.add(n.lower().replace("_", "-"))
+        pkgs.update(_norm(d) for d in dist_map.get(n, []))
+    # Module paths held in strings only count when they match an installed
+    # distribution, so arbitrary strings can't mark random packages as used.
+    for n in extract_string_module_refs(ctx.python_files):
+        pkgs.update(_norm(d) for d in dist_map.get(n, []))
+    pkgs.update(_packages_named_in_run_files(ctx))
     return pkgs
 
 
+_DIST_MAP_SNIPPET = (
+    "import json, importlib.metadata as m; print(json.dumps(m.packages_distributions()))"
+)
+
+
+def _distribution_map(ctx: ProjectContext) -> dict[str, list[str]]:
+    """
+    Map top-level import names to distribution names in the *project's* environment.
+
+    Runs in the project interpreter, not pydoctor's own, so it is correct even
+    when pydoctor is installed with pipx. Returns {} if that fails.
+    """
+    python = getattr(ctx, "project_python", None) or sys.executable
+    try:
+        result = subprocess.run(
+            [python, "-c", _DIST_MAP_SNIPPET],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode == 0:
+            data = json.loads(result.stdout)
+            if isinstance(data, dict):
+                return {k: list(v) for k, v in data.items()}
+    except (OSError, subprocess.SubprocessError, ValueError):
+        pass
+    return {}
+
+
+_RUN_FILE_GLOBS = (
+    "Procfile",
+    "Dockerfile*",
+    "*.dockerfile",
+    "docker-compose*.yml",
+    "docker-compose*.yaml",
+    "compose*.yml",
+    "compose*.yaml",
+    "Makefile",
+    "*.sh",
+    "fly.toml",
+    "render.yaml",
+    "app.yaml",
+    ".github/workflows/*.yml",
+    ".github/workflows/*.yaml",
+)
+
+
+def _packages_named_in_run_files(ctx: ProjectContext) -> set[str]:
+    """Declared dependencies named in deploy/run files (e.g. `gunicorn app.wsgi`)."""
+    text_parts: list[str] = []
+    for pattern in _RUN_FILE_GLOBS:
+        for fpath in ctx.root.glob(pattern):
+            if fpath.is_file():
+                try:
+                    text_parts.append(fpath.read_text(encoding="utf-8", errors="ignore"))
+                except OSError:
+                    continue
+    if not text_parts:
+        return set()
+    text = "\n".join(text_parts).lower()
+    found: set[str] = set()
+    for dep in ctx.declared_deps:
+        norm = _norm(dep)
+        variants = {norm, norm.replace("-", "_")}
+        if any(re.search(rf"(?<![\w-]){re.escape(v)}(?![\w-])", text) for v in variants):
+            found.add(norm)
+    return found
+
+
 def _get_implicitly_used_packages(ctx: ProjectContext, imported: set[str]) -> dict[str, list[str]]:
     used: dict[str, list[str]] = {}
 
@@ -203,7 +306,7 @@ def _identify_unused(
     transitive = []
 
     for dep in ctx.declared_deps:
-        norm = dep.lower().replace("_", "-")
+        norm = _norm(dep)
         if norm in imported or norm in ignored:
             continue
 

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pydoctor/scanners/vulnerability_scanner.py

@@ -50,9 +50,19 @@ def scan(ctx: ProjectContext) -> list[Issue]:
     client = OSVClient(cache=cache)
 
     # Query OSV for all installed packages
-    records = client.query_packages(ctx.installed_packages)
+    records = _dedupe_records(client.query_packages(ctx.installed_packages))
+    failed = list(getattr(client, "failed_packages", []) or [])
+
+    issues: list[Issue] = []
+
+    if failed:
+        # Fail closed: a security scan that could not reach the vulnerability
+        # database must never report the project as healthy.
+        issues.append(_incomplete_scan_issue(failed, len(ctx.installed_packages)))
 
     if not records:
+        if failed:
+            return issues
         return [
             Issue(
                 category=CATEGORY,
@@ -67,8 +77,6 @@ def scan(ctx: ProjectContext) -> list[Issue]:
             )
         ]
 
-    issues: list[Issue] = []
-
     # Add environment context info
     issues.append(
         Issue(
@@ -90,6 +98,66 @@ def scan(ctx: ProjectContext) -> list[Issue]:
     return issues
 
 
+_SEVERITY_RANK = {"CRITICAL": 4, "HIGH": 3, "MEDIUM": 2, "LOW": 1, "UNKNOWN": 0}
+
+
+def _dedupe_records(records: list[VulnerabilityRecord]) -> list[VulnerabilityRecord]:
+    """
+    Collapse records that describe the same advisory.
+
+    OSV often returns one advisory under several databases (for example a
+    GHSA entry and a PYSEC entry that list each other as aliases). Without
+    this step each copy is reported and penalised separately, so a single
+    vulnerability can cost the health score twice. Records for the same
+    package and version are merged when their IDs or aliases overlap; the
+    highest severity among the duplicates is kept.
+    """
+    kept: list[VulnerabilityRecord] = []
+    kept_ids: list[set[str]] = []
+    for rec in records:
+        ids = {rec.vuln_id, *rec.aliases}
+        for idx, existing in enumerate(kept):
+            if (
+                existing.package == rec.package
+                and existing.version == rec.version
+                and kept_ids[idx] & ids
+            ):
+                kept_ids[idx] |= ids
+                if _SEVERITY_RANK.get(rec.severity.upper(), 0) > _SEVERITY_RANK.get(
+                    existing.severity.upper(), 0
+                ):
+                    existing.severity = rec.severity
+                existing.aliases = sorted(kept_ids[idx] - {existing.vuln_id})
+                break
+        else:
+            kept.append(rec)
+            kept_ids.append(ids)
+    return kept
+
+
+def _incomplete_scan_issue(failed: list[str], total: int) -> Issue:
+    """Build the ERROR issue reported when OSV lookups did not complete."""
+    preview = ", ".join(sorted(failed)[:5])
+    if len(failed) > 5:
+        preview += f", and {len(failed) - 5} more"
+    return Issue(
+        category=CATEGORY,
+        code="SEC_SCAN_INCOMPLETE",
+        severity=Severity.ERROR,
+        title=f"Security scan incomplete: {len(failed)} of {total} packages not checked",
+        description=(
+            "pydoctor could not reach the OSV vulnerability database "
+            f"(https://api.osv.dev) for: {preview}. These packages were not "
+            "checked, so the absence of findings is not evidence that they are safe."
+        ),
+        recommendation=(
+            "Check network or proxy access to api.osv.dev, or raise "
+            "PYDOCTOR_REQUEST_TIMEOUT, then run `pydoctor scan-security` again."
+        ),
+        extra={"unchecked_packages": sorted(failed)},
+    )
+
+
 def _record_to_issue(rec: VulnerabilityRecord) -> Issue:
     """
     Convert a VulnerabilityRecord into a structured Issue.

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pydoctor/security/osv_client.py

@@ -99,6 +99,11 @@ class OSVClient:
         self._cache = cache or CacheManager()
         self._timeout = timeout
         self._session = requests.Session()
+        # Packages whose OSV lookup could not be completed (network error,
+        # timeout, or a non-2xx response after all retries). Callers must
+        # check this: an empty result list does NOT mean "no vulnerabilities"
+        # when this list is non-empty.
+        self.failed_packages: list[str] = []
         self._session.headers.update(
             {
                 "Content-Type": "application/json",
@@ -123,8 +128,10 @@ class OSVClient:
         Returns
         -------
         list[VulnerabilityRecord]
-            All vulnerabilities found.  Empty list if none / network error.
+            All vulnerabilities found. Packages that could not be checked
+            are recorded in ``self.failed_packages``.
         """
+        self.failed_packages = []
         if not packages:
             return []
 
@@ -196,7 +203,10 @@ class OSVClient:
                 break
             except (requests.RequestException, ValueError):
                 if attempt == retries - 1:
-                    # Final attempt failed — return whatever we got from cache
+                    # Final attempt failed. Record the packages we could not
+                    # check so the scanner can report an incomplete scan
+                    # instead of a clean bill of health.
+                    self.failed_packages.extend(name for name, _ in to_fetch)
                     return records
                 # Simple exponential backoff: 1s, 2s, 4s...
                 time.sleep(2**attempt)

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pydoctor/utils/parser_utils.py

@@ -10,6 +10,7 @@ actually imported somewhere in the project source.
 from __future__ import annotations
 
 import ast
+import re
 from pathlib import Path
 
 from pydoctor.utils.file_utils import read_file_safe
@@ -72,6 +73,36 @@ def extract_imports_from_project(python_files: list[Path]) -> set[str]:
     return all_imports
 
 
+_MODULE_STRING = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+def extract_string_module_refs(python_files: list[Path]) -> set[str]:
+    """
+    Collect top-level names from string constants that look like module paths.
+
+    Frameworks load many dependencies by name rather than by ``import``:
+    Django's ``INSTALLED_APPS = ["corsheaders"]``, ``MIDDLEWARE = ["whitenoise.middleware..."]``
+    and ``"BACKEND": "django_redis.cache.RedisCache"`` are all plain strings.
+    Callers should only treat a returned name as a dependency reference when it
+    matches the import name of an installed distribution.
+    """
+    names: set[str] = set()
+    for fpath in python_files:
+        source = read_file_safe(fpath)
+        if source is None:
+            continue
+        try:
+            tree = ast.parse(source)
+        except (SyntaxError, ValueError):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                value = node.value.strip()
+                if 0 < len(value) <= 200 and _MODULE_STRING.match(value):
+                    names.add(value.split(".", 1)[0])
+    return names
+
+
 # ──────────────────────────────────────────────────────────────
 # AST walking
 # ──────────────────────────────────────────────────────────────

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pydoctor_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.0.0
+Version: 2.1.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>
@@ -323,6 +323,16 @@ pydoctor fix
 
 ## Release History
 
+### 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.
+- **No accidental removals:** `pydoctor fix <package>` no longer offers to uninstall it. Removal only runs with `--remove`.
+- **Fewer false "unused" reports:** packages imported under a different name (`decouple`), loaded from strings (Django `INSTALLED_APPS`, `MIDDLEWARE`, backends), or run from a Procfile/Dockerfile (`gunicorn`) are recognised as used. Remaining findings are labelled "Possibly unused".
+
+### v2.0.1
+- **Security scans fail closed:** if the OSV database can't be reached, pydoctor now reports `SEC_SCAN_INCOMPLETE` (error, exit 1) instead of a clean result.
+- **No more double-counted advisories:** advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.
+
 ### v2.0.0
 
 - **🚀 Major UI/UX Revamp**: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pydoctor_cli.egg-info/SOURCES.txt

@@ -46,5 +46,6 @@ tests/test_ci_scanner.py
 tests/test_cli_ux.py
 tests/test_dependency_scanner.py
 tests/test_env_scanner.py
+tests/test_fix_command.py
 tests/test_unused_scanner.py
 tests/test_vulnerability_scanner.py

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name        = "pydoctor-cli"
-version     = "2.0.0"
+version     = "2.1.0"
 description = "Premium Python environment diagnostic CLI — your project's personal physician."
 readme      = "README.md"
 license     = { file = "LICENSE" }

pydoctor_cli-2.1.0/tests/test_fix_command.py

@@ -0,0 +1,141 @@
+"""
+tests/test_fix_command.py
+─────────────────────────
+Unit tests for `pydoctor fix`: per-package prompts, verified upgrades,
+and no implicit removals.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from types import SimpleNamespace
+
+from typer.testing import CliRunner
+
+from pydoctor.cli import main
+from pydoctor.core.report import DiagnosisReport, Issue
+
+
+def _vuln(pkg, fixed_in, severity="critical"):
+    return Issue(
+        category="security",
+        code="SEC_VULNERABILITY",
+        severity=severity,
+        title=f"{pkg} advisory",
+        description="",
+        recommendation="",
+        package=pkg,
+        extra={"fixed_in": fixed_in},
+    )
+
+
+def test_one_prompt_per_vulnerable_package(monkeypatch):
+    report = DiagnosisReport(
+        issues=[
+            _vuln("pillow", "12.3.0"),
+            _vuln("pillow", "13.0.0"),
+            _vuln("pillow", "12.2.1", severity="warning"),
+            _vuln("cryptography", "46.0.5"),
+        ]
+    )
+    prompts, applied = [], []
+    monkeypatch.setattr(main.Confirm, "ask", lambda msg, *a, **k: prompts.append(msg) or True)
+    monkeypatch.setattr(
+        main,
+        "_apply_and_verify",
+        lambda ctx, pkg, action, target, verb: applied.append((pkg, target)) or True,
+    )
+
+    handled: set[str] = set()
+    actions = main._fix_vulnerabilities(report, SimpleNamespace(), True, handled)
+
+    assert len(prompts) == 2
+    assert "3 advisories, 2 critical" in prompts[0]
+    assert applied == [("pillow", "13.0.0"), ("cryptography", "46.0.5")]
+    assert actions == 2
+    assert handled == {"pillow", "cryptography"}
+
+
+def test_outdated_skips_packages_already_handled(monkeypatch):
+    report = DiagnosisReport(
+        issues=[
+            Issue(
+                category="outdated",
+                code="PKG_OUTDATED",
+                severity="warning",
+                title="",
+                description="",
+                recommendation="",
+                package="pillow",
+                extra={"latest_version": "13.0.0"},
+            )
+        ]
+    )
+    monkeypatch.setattr(main.Confirm, "ask", lambda *a, **k: (_ for _ in ()).throw(AssertionError))
+    assert main._fix_outdated(report, SimpleNamespace(), True, {"pillow"}) == 0
+
+
+def test_unchanged_version_is_not_reported_as_fixed(monkeypatch, tmp_path, capsys):
+    (tmp_path / "pyproject.toml").write_text(
+        '[project]\ndependencies = [\n    "pillow==12.2.0",\n]\n', encoding="utf-8"
+    )
+    ctx = SimpleNamespace(root=tmp_path)
+    monkeypatch.setattr(main, "_installed_version", lambda ctx, pkg: "12.2.0")
+    monkeypatch.setattr(
+        main,
+        "_run_package_manager_command",
+        lambda *a, **k: subprocess.CompletedProcess(args=[], returncode=0),
+    )
+
+    assert main._apply_and_verify(ctx, "pillow", "add", None, "upgraded") is False
+    out = capsys.readouterr().out
+    assert "still 12.2.0" in out
+    assert "pillow==12.2.0" in out
+    assert "✔" not in out
+
+
+def test_changed_version_is_reported(monkeypatch, capsys):
+    versions = iter(["12.2.0", "13.0.0"])
+    monkeypatch.setattr(main, "_installed_version", lambda ctx, pkg: next(versions))
+    monkeypatch.setattr(
+        main,
+        "_run_package_manager_command",
+        lambda *a, **k: subprocess.CompletedProcess(args=[], returncode=0),
+    )
+    assert main._apply_and_verify(SimpleNamespace(), "pillow", "add", "13.0.0", "upgraded")
+    assert "12.2.0 → 13.0.0" in capsys.readouterr().out
+
+
+def test_uv_uses_minimum_version_requirement(monkeypatch):
+    calls = []
+    monkeypatch.setattr(
+        main.subprocess,
+        "run",
+        lambda cmd, cwd=None: calls.append(cmd) or subprocess.CompletedProcess(cmd, 0),
+    )
+    ctx = SimpleNamespace(root=".", is_poetry=False, is_uv=True, is_pdm=False)
+    main._run_package_manager_command(ctx, "pillow", "add", True, "13.0.0")
+    assert calls == [["uv", "add", "pillow>=13.0.0"]]
+
+
+def test_naming_a_package_does_not_remove_it(monkeypatch, tmp_path):
+    report = DiagnosisReport(
+        issues=[
+            Issue(
+                category="unused",
+                code="UNUSED_PACKAGE",
+                severity="warning",
+                title="",
+                description="",
+                recommendation="",
+                package="redis",
+            )
+        ]
+    )
+    monkeypatch.setattr(main, "_run_scan", lambda **k: report)
+    monkeypatch.setattr(main, "_fix_unused", lambda *a: (_ for _ in ()).throw(AssertionError))
+    monkeypatch.setattr(main, "_fix_venv", lambda *a: 0)
+
+    result = CliRunner().invoke(main.app, ["fix", "redis", "--path", str(tmp_path)])
+    assert result.exit_code == 0, result.stdout
+    assert "pydoctor fix --remove" in result.stdout

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/tests/test_unused_scanner.py

@@ -104,3 +104,70 @@ class TestUnusedPackageScanner:
         # flask is imported via from-import, requests is not
         assert "requests" in pkg_names
         assert "flask" not in pkg_names
+
+
+class TestFrameworkAwareDetection:
+    """Dependencies used without a plain ``import`` must not be flagged."""
+
+    def test_import_name_differs_from_distribution(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(
+            unused_package_scanner,
+            "_distribution_map",
+            lambda ctx: {"decouple": ["python-decouple"]},
+        )
+        ctx = _make_ctx(
+            tmp_path,
+            py_files=[("settings.py", "from decouple import config\n")],
+            declared={"python-decouple": ""},
+        )
+        unused = [i.package for i in unused_package_scanner.scan(ctx) if i.code == "UNUSED_PACKAGE"]
+        assert "python-decouple" not in unused
+
+    def test_module_path_strings_count_as_usage(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(
+            unused_package_scanner,
+            "_distribution_map",
+            lambda ctx: {
+                "whitenoise": ["whitenoise"],
+                "corsheaders": ["django-cors-headers"],
+                "django_redis": ["django-redis"],
+            },
+        )
+        settings = (
+            'INSTALLED_APPS = ["corsheaders"]\n'
+            'MIDDLEWARE = ["whitenoise.middleware.WhiteNoiseMiddleware"]\n'
+            'CACHES = {"default": {"BACKEND": "django_redis.cache.RedisCache"}}\n'
+        )
+        ctx = _make_ctx(
+            tmp_path,
+            py_files=[("settings.py", settings)],
+            declared={"whitenoise": "", "django-cors-headers": "", "django-redis": "", "six": ""},
+        )
+        unused = [i.package for i in unused_package_scanner.scan(ctx) if i.code == "UNUSED_PACKAGE"]
+        assert unused == ["six"]
+
+    def test_arbitrary_strings_do_not_mark_packages_used(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(unused_package_scanner, "_distribution_map", lambda ctx: {})
+        ctx = _make_ctx(
+            tmp_path,
+            py_files=[("main.py", 'GREETING = "six"\n')],
+            declared={"six": ""},
+        )
+        unused = [i.package for i in unused_package_scanner.scan(ctx) if i.code == "UNUSED_PACKAGE"]
+        assert unused == ["six"]
+
+    def test_server_named_in_procfile_is_used(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(unused_package_scanner, "_distribution_map", lambda ctx: {})
+        (tmp_path / "Procfile").write_text("web: gunicorn app.wsgi\n", encoding="utf-8")
+        ctx = _make_ctx(
+            tmp_path,
+            py_files=[("main.py", "x = 1\n")],
+            declared={"gunicorn": "", "uvicorn": ""},
+        )
+        unused = [i.package for i in unused_package_scanner.scan(ctx) if i.code == "UNUSED_PACKAGE"]
+        assert unused == ["uvicorn"]
+
+    def test_title_has_no_rich_markup(self, tmp_path):
+        ctx = _make_ctx(tmp_path, py_files=[("main.py", "import os\n")], declared={"pandas": ""})
+        for issue in unused_package_scanner.scan(ctx):
+            assert "[dim]" not in issue.title and "[/]" not in issue.title

{pydoctor_cli-2.0.0 → pydoctor_cli-2.1.0}/tests/test_vulnerability_scanner.py

@@ -80,3 +80,78 @@ def test_vulns_detected_and_mapped(basic_ctx, monkeypatch):
     assert critical_issue.package == "requests"
     assert critical_issue.code == "SEC_VULNERABILITY"
     assert warning_issue.package == "flask"
+
+
+def test_unreachable_osv_fails_closed(basic_ctx, monkeypatch):
+    """When OSV cannot be reached, report an ERROR instead of 'no vulnerabilities'."""
+
+    class FakeClient:
+        def __init__(self, **kwargs):
+            self.failed_packages = []
+
+        def query_packages(self, pkgs):
+            self.failed_packages = list(pkgs)
+            return []
+
+    monkeypatch.setattr("pydoctor.scanners.vulnerability_scanner.OSVClient", FakeClient)
+
+    issues = vulnerability_scanner.scan(basic_ctx)
+    codes = [i.code for i in issues]
+    assert "SEC_SCAN_INCOMPLETE" in codes
+    assert "SEC_NO_VULNS" not in codes
+    incomplete = next(i for i in issues if i.code == "SEC_SCAN_INCOMPLETE")
+    assert incomplete.severity == Severity.ERROR
+
+
+def test_osv_client_records_failed_packages(monkeypatch, tmp_path):
+    """OSVClient records unchecked packages when every retry fails."""
+    import requests
+
+    from pydoctor.cache.cache_manager import CacheManager
+    from pydoctor.security import osv_client as osv_module
+
+    monkeypatch.setattr(osv_module.time, "sleep", lambda _s: None)
+    client = osv_module.OSVClient(cache=CacheManager(cache_file=tmp_path / "c.json"))
+
+    def boom(*args, **kwargs):
+        raise requests.ConnectionError("offline")
+
+    monkeypatch.setattr(client._session, "post", boom)
+    records = client.query_packages({"requests": "2.31.0"})
+    assert records == []
+    assert client.failed_packages == ["requests"]
+
+
+def test_aliased_advisories_reported_once(basic_ctx, monkeypatch):
+    """A GHSA and a PYSEC record that alias each other count as one vulnerability."""
+
+    class FakeClient:
+        def __init__(self, **kwargs):
+            self.failed_packages = []
+
+        def query_packages(self, pkgs):
+            return [
+                VulnerabilityRecord(
+                    vuln_id="GHSA-6q48-6c7w-9gw2",
+                    package="certifi",
+                    version="2026.7.22",
+                    summary="certifi bundles emSign roots with compromised keys",
+                    severity="HIGH",
+                    aliases=["PYSEC-2026-4320"],
+                ),
+                VulnerabilityRecord(
+                    vuln_id="PYSEC-2026-4320",
+                    package="certifi",
+                    version="2026.7.22",
+                    summary="certifi bundles emSign roots with compromised keys",
+                    severity="CRITICAL",
+                    aliases=["GHSA-6q48-6c7w-9gw2"],
+                ),
+            ]
+
+    monkeypatch.setattr("pydoctor.scanners.vulnerability_scanner.OSVClient", FakeClient)
+
+    issues = vulnerability_scanner.scan(basic_ctx)
+    vulns = [i for i in issues if i.code == "SEC_VULNERABILITY"]
+    assert len(vulns) == 1
+    assert vulns[0].severity == Severity.CRITICAL