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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.1.0
+Version: 2.3.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
@@ -311,6 +322,44 @@ Run a comprehensive check-up on your project.
 pydoctor diagnose
 ```
 
+### In CI: GitHub Action
+
+Findings appear as code-scanning alerts on pull requests, and the job fails on new problems:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-python@v5
+    with: { python-version: "3.12" }
+  - run: pip install -r requirements.txt
+  - uses: iamAgbaCoder/pydoctor-cli@v2
+```
+
+Set `ci-only: "true"` to run only the secrets and workflow checks. Any CI system can use `pydoctor check --sarif pydoctor.sarif` directly.
+
+### Adopting it in an existing project: baselines
+
+```bash
+pydoctor baseline        # accept today's issues; commit .pydoctor-baseline.json
+pydoctor check           # now fails only on new issues
+```
+
+Problems with the scan itself (unreadable environment, unreachable vulnerability database) are never baselined.
+
+### pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/iamAgbaCoder/pydoctor-cli
+    rev: v2.3.0
+    hooks:
+      - id: pydoctor-ci      # blocks commits that add secrets or risky workflows
+```
+
 ### Automated Fixes
 
 Let PyDoctor perform the heavy lifting. It will offer to install missing packages, upgrade outdated ones, and clean up your environment.
@@ -323,6 +372,28 @@ pydoctor fix
 
 ## Release History
 
+### v2.3.0
+Built for CI: adopt pydoctor in an existing project without a wall of failures, and see findings where you review code.
+
+- **Baselines:** `pydoctor baseline` records today's issues in `.pydoctor-baseline.json`; scans then fail only on new ones and tell you when baselined issues are fixed. Fingerprints survive unrelated edits (a secret moved down by new lines stays known) and package upgrades. `--ci` updates only the CI-guard entries. `--baseline FILE` / `--no-baseline` on every scan command. Broken scans are never baselined.
+- **SARIF output:** `--sarif FILE` on every scan command (SARIF 2.1.0, schema-validated). Vulnerabilities carry their CVSS score as security severity and point at the line that declares the package; secrets and workflow findings point at their file and line.
+- **GitHub Action:** `uses: iamAgbaCoder/pydoctor-cli@v2` installs pydoctor in isolation, uploads findings to code scanning, and fails the job on new problems.
+- **pre-commit hooks:** `pydoctor-ci` blocks commits that add secrets, `.env` files or risky workflows; `pydoctor-check` runs the full scan at pre-push.
+- **Docs links:** every issue links to its page on pydoctor-docs.thally.app (`docs_url` in JSON; shown in the terminal for errors).
+
+### 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.3.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
@@ -62,6 +73,44 @@ Run a comprehensive check-up on your project.
 pydoctor diagnose
 ```
 
+### In CI: GitHub Action
+
+Findings appear as code-scanning alerts on pull requests, and the job fails on new problems:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-python@v5
+    with: { python-version: "3.12" }
+  - run: pip install -r requirements.txt
+  - uses: iamAgbaCoder/pydoctor-cli@v2
+```
+
+Set `ci-only: "true"` to run only the secrets and workflow checks. Any CI system can use `pydoctor check --sarif pydoctor.sarif` directly.
+
+### Adopting it in an existing project: baselines
+
+```bash
+pydoctor baseline        # accept today's issues; commit .pydoctor-baseline.json
+pydoctor check           # now fails only on new issues
+```
+
+Problems with the scan itself (unreadable environment, unreachable vulnerability database) are never baselined.
+
+### pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/iamAgbaCoder/pydoctor-cli
+    rev: v2.3.0
+    hooks:
+      - id: pydoctor-ci      # blocks commits that add secrets or risky workflows
+```
+
 ### Automated Fixes
 
 Let PyDoctor perform the heavy lifting. It will offer to install missing packages, upgrade outdated ones, and clean up your environment.
@@ -74,6 +123,28 @@ pydoctor fix
 
 ## Release History
 
+### v2.3.0
+Built for CI: adopt pydoctor in an existing project without a wall of failures, and see findings where you review code.
+
+- **Baselines:** `pydoctor baseline` records today's issues in `.pydoctor-baseline.json`; scans then fail only on new ones and tell you when baselined issues are fixed. Fingerprints survive unrelated edits (a secret moved down by new lines stays known) and package upgrades. `--ci` updates only the CI-guard entries. `--baseline FILE` / `--no-baseline` on every scan command. Broken scans are never baselined.
+- **SARIF output:** `--sarif FILE` on every scan command (SARIF 2.1.0, schema-validated). Vulnerabilities carry their CVSS score as security severity and point at the line that declares the package; secrets and workflow findings point at their file and line.
+- **GitHub Action:** `uses: iamAgbaCoder/pydoctor-cli@v2` installs pydoctor in isolation, uploads findings to code scanning, and fails the job on new problems.
+- **pre-commit hooks:** `pydoctor-ci` blocks commits that add secrets, `.env` files or risky workflows; `pydoctor-check` runs the full scan at pre-push.
+- **Docs links:** every issue links to its page on pydoctor-docs.thally.app (`docs_url` in JSON; shown in the terminal for errors).
+
+### 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.3.0}/pydoctor/__init__.py

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

{pydoctor_cli-2.1.0 → pydoctor_cli-2.3.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.3.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: