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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.2.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>
@@ -322,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.
@@ -334,6 +372,15 @@ 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.
 

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

@@ -73,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.
@@ -85,6 +123,15 @@ 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.
 

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

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

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

@@ -85,7 +85,7 @@ _HELP_EPILOG = """
 [section]🏥  COMMUNITY & SUPPORT[/]
 
   [label]Docs:[/][pkg] https://pydoctor-docs.thally.app[/]
-  [label]Version:[/][info] v2.2.0 (Premium Kernel Edition)[/]
+  [label]Version:[/][info] v2.3.0 (Premium Kernel Edition)[/]
 
 [kernel]Healthy code leads to healthy deployments. Keep your environment sterile.[/]
 """
@@ -122,6 +122,19 @@ _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.")
+_SARIF_ARG = typer.Option(
+    ...,
+    "--sarif",
+    help="Also write findings to this file in SARIF format (for GitHub code scanning).",
+)
+_BASELINE_ARG = typer.Option(
+    ...,
+    "--baseline",
+    help="Baseline file of accepted issues (default: .pydoctor-baseline.json if present).",
+)
+_NO_BASELINE_ARG = typer.Option(
+    ..., "--no-baseline", help="Report every issue, ignoring the baseline."
+)
 _PYTHON_ARG = typer.Option(
     ...,
     "--python",
@@ -212,6 +225,42 @@ def _output(report: DiagnosisReport, as_json: bool, verbose: bool = False) -> No
         render_report(report, verbose=verbose)
 
 
+def _finish(
+    report: DiagnosisReport,
+    path: str,
+    as_json: bool,
+    verbose: bool,
+    sarif: Path | None,
+    baseline: Path | None,
+    no_baseline: bool,
+) -> None:
+    """Apply the baseline, print the report, write SARIF, and exit with the right code."""
+    from pydoctor.core.baseline import BaselineError, apply_baseline, default_path
+
+    if not no_baseline:
+        path_to_use = baseline or default_path(report)
+        if baseline is not None and not path_to_use.is_file():
+            err_console.print(f"[error]✖ Baseline file not found: {path_to_use}[/]")
+            raise typer.Exit(code=2)
+        if path_to_use.is_file():
+            try:
+                apply_baseline(report, path_to_use, set(report.scanners))
+            except BaselineError as exc:
+                err_console.print(f"[error]✖ {exc}[/]")
+                raise typer.Exit(code=2) from exc
+
+    _output(report, as_json=as_json, verbose=verbose)
+
+    if sarif is not None:
+        from pydoctor.reports.sarif_formatter import write_sarif
+
+        write_sarif(report, sarif)
+        if not as_json:
+            console.print(f"[dim_text]SARIF report written to {sarif}[/]")
+
+    raise typer.Exit(code=_exit_code(report, path))
+
+
 def _exit_code(report: DiagnosisReport, path: str = ".") -> int:
     """
     Return a non-zero exit code if:
@@ -237,6 +286,9 @@ def _exit_code(report: DiagnosisReport, path: str = ".") -> int:
 def diagnose(
     path: Annotated[str, _PATH_ARG] = ".",
     python: Annotated[str | None, _PYTHON_ARG] = None,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
     no_cache: Annotated[bool, _NO_CACHE_ARG] = False,
@@ -268,14 +320,16 @@ def diagnose(
         python=python,
         ctx=ctx,
     )
-    _output(report, as_json=json, verbose=verbose)
-    raise typer.Exit(code=_exit_code(report, path))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 @app.command(rich_help_panel="CORE COMMANDS")
 def check(
     path: Annotated[str, _PATH_ARG] = ".",
     python: Annotated[str | None, _PYTHON_ARG] = None,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     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,
@@ -284,8 +338,7 @@ def 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))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 @app.command(rich_help_panel="SECURITY & CI/CD")
@@ -319,6 +372,9 @@ 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,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
@@ -347,8 +403,7 @@ def 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))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 # --- Individual Targeted Scans ---
@@ -358,6 +413,9 @@ def github(
 def scan_security(
     path: Annotated[str, _PATH_ARG] = ".",
     python: Annotated[str | None, _PYTHON_ARG] = None,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
@@ -370,8 +428,7 @@ def scan_security(
         command="scan-security",
         python=python,
     )
-    _output(report, as_json=json, verbose=verbose)
-    raise typer.Exit(code=_exit_code(report, path))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 # ──────────────────────────────────────────────────────────────
@@ -383,6 +440,9 @@ def scan_security(
 def scan_unused(
     path: Annotated[str, _PATH_ARG] = ".",
     python: Annotated[str | None, _PYTHON_ARG] = None,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
@@ -395,14 +455,16 @@ def scan_unused(
         command="scan-unused",
         python=python,
     )
-    _output(report, as_json=json, verbose=verbose)
-    raise typer.Exit(code=_exit_code(report, path))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 @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,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
@@ -415,14 +477,16 @@ def scan_deps(
         command="scan-deps",
         python=python,
     )
-    _output(report, as_json=json, verbose=verbose)
-    raise typer.Exit(code=_exit_code(report, path))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 @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,
+    sarif: Annotated[Path | None, _SARIF_ARG] = None,
+    baseline: Annotated[Path | None, _BASELINE_ARG] = None,
+    no_baseline: Annotated[bool, _NO_BASELINE_ARG] = False,
     json: Annotated[bool, _JSON_ARG] = False,
     verbose: Annotated[bool, _VERBOSE_ARG] = False,
 ) -> None:
@@ -435,13 +499,56 @@ def check_env(
         command="check-env",
         python=python,
     )
-    _output(report, as_json=json, verbose=verbose)
-    raise typer.Exit(code=_exit_code(report, path))
+    _finish(report, path, json, verbose, sarif, baseline, no_baseline)
 
 
 # --- Re-adding fix and other commands ---
 
 
+@app.command(rich_help_panel="CORE COMMANDS")
+def baseline(
+    path: Annotated[str, _PATH_ARG] = ".",
+    python: Annotated[str | None, _PYTHON_ARG] = None,
+    ci: bool = typer.Option(
+        False, "--ci", help="Only record CI/CD guard findings (keeps the rest of the file)."
+    ),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output", "-o", help="Where to write it (default: .pydoctor-baseline.json)."
+        ),
+    ] = None,
+) -> None:
+    """📌  Accept today's issues so CI only fails on new ones."""
+    from pydoctor.core.baseline import NEVER_BASELINE, default_path, write_baseline
+
+    report = _run_scan(
+        scanners=["ci"] if ci else None, path=path, python=python, command="baseline"
+    )
+    target = output or default_path(report)
+    count = write_baseline(report, target, __version__, set(report.scanners) if ci else None)
+    console.print(
+        Panel(
+            f"[ok]✔ {count} issue{'s' if count != 1 else ''} recorded in {target}[/]\n\n"
+            "Commit this file. Scans now hide these issues and fail only on new ones.\n"
+            "Run `pydoctor baseline` again after fixing issues to shrink it, or scan with "
+            "--no-baseline to see everything.",
+            border_style="ok",
+        )
+    )
+
+    incomplete = [i for i in report.issues if i.code in NEVER_BASELINE]
+    if incomplete:
+        for issue in incomplete:
+            err_console.print(f"[error]✖ {issue.title}[/]\n  {issue.description}")
+        err_console.print(
+            "\n[warning]⚠ Part of the scan didn't run, so its issues aren't in the baseline. "
+            "They will be reported as new once the scan can run. Fix the problems above and "
+            "run `pydoctor baseline` again.[/]"
+        )
+        raise typer.Exit(code=1)
+
+
 @app.command(rich_help_panel="CORE COMMANDS")
 def fix(
     packages: Annotated[

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

@@ -159,6 +159,7 @@ class Analyzer:
         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)
+        report.scanners = [k for k in self._scanner_keys if k in SCANNER_REGISTRY]
         scanner_timings: dict[str, float] = {}
         report.extend(context_issues(ctx, self._scanner_keys))
 

pydoctor_cli-2.3.0/pydoctor/core/baseline.py

@@ -0,0 +1,153 @@
+"""
+pydoctor/core/baseline.py
+──────────────────────────
+Baselines: accept today's issues so CI only fails on new ones.
+
+A project with dozens of existing findings can't turn on a pydoctor CI gate
+without it failing on every run. ``pydoctor baseline`` records the current
+issues in ``.pydoctor-baseline.json``; later scans hide issues whose
+fingerprint is in that file and report how many were hidden. Fixed issues
+drop out naturally, and the file can be refreshed at any time.
+
+Problems with the scan itself (an unreadable environment, an unreachable
+vulnerability database, a crashed scanner) are never baselined: accepting
+them would turn a broken scan into a passing one.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pydoctor.config.settings import Severity
+from pydoctor.core.report import DiagnosisReport, Issue
+from pydoctor.reports.fingerprint import fingerprint
+
+BASELINE_FILE = ".pydoctor-baseline.json"
+BASELINE_FORMAT = 1
+
+# Never accepted into a baseline.
+NEVER_BASELINE = {"ENV_PACKAGES_UNAVAILABLE", "SEC_SCAN_INCOMPLETE", "SCANNER_ERROR"}
+_IGNORED_SEVERITIES = {Severity.OK, Severity.INFO}
+
+
+class BaselineError(Exception):
+    """The baseline file exists but can't be used."""
+
+
+@dataclass
+class BaselineResult:
+    path: Path
+    suppressed: int = 0
+    stale: int = 0
+    suppressed_codes: dict[str, int] = field(default_factory=dict)
+
+
+def _root(report: DiagnosisReport) -> Path:
+    return Path(report.ctx.root) if report.ctx is not None else Path(report.scan_path)
+
+
+def baselinable(issue: Issue) -> bool:
+    return issue.severity not in _IGNORED_SEVERITIES and issue.code not in NEVER_BASELINE
+
+
+def default_path(report: DiagnosisReport) -> Path:
+    return _root(report) / BASELINE_FILE
+
+
+def write_baseline(
+    report: DiagnosisReport, path: Path, version: str, scanned_categories: set[str] | None = None
+) -> int:
+    """
+    Record every baselinable issue in ``report``. Returns how many are in the file.
+
+    When ``scanned_categories`` is given (a partial scan such as
+    `pydoctor baseline --ci`), entries for categories that weren't scanned are
+    kept from the existing file instead of being dropped.
+    """
+    root = _root(report)
+    entries: dict[str, dict] = {}
+    if scanned_categories is not None and path.is_file():
+        try:
+            previous = json.loads(path.read_text(encoding="utf-8")).get("issues", [])
+        except (OSError, ValueError):
+            previous = []
+        for e in previous:
+            if e.get("category") not in scanned_categories and "fingerprint" in e:
+                entries[e["fingerprint"]] = e
+    for issue in report.issues:
+        if not baselinable(issue):
+            continue
+        fp = fingerprint(issue, root)
+        entries[fp] = {
+            "fingerprint": fp,
+            "code": issue.code,
+            "category": issue.category,
+            "severity": issue.severity,
+            "title": issue.title,
+        }
+    data = {
+        "format": BASELINE_FORMAT,
+        "created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds"),
+        "pydoctor_version": version,
+        "issues": sorted(entries.values(), key=lambda e: (e["code"], e["title"])),
+    }
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return len(entries)
+
+
+def load_fingerprints(path: Path) -> set[str]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise BaselineError(f"{path} couldn't be read: {exc}") from exc
+    if not isinstance(data, dict) or data.get("format") != BASELINE_FORMAT:
+        raise BaselineError(
+            f"{path} isn't a pydoctor baseline (format {BASELINE_FORMAT}). "
+            "Recreate it with `pydoctor baseline`."
+        )
+    return {e["fingerprint"] for e in data.get("issues", []) if "fingerprint" in e}
+
+
+def apply_baseline(
+    report: DiagnosisReport, path: Path, scanned_categories: set[str]
+) -> BaselineResult:
+    """
+    Remove issues recorded in the baseline from ``report``.
+
+    ``scanned_categories`` limits stale-entry counting to what this scan
+    actually checked: `scan-security` can't tell whether a baselined secret
+    still exists.
+    """
+    known = load_fingerprints(path)
+    root = _root(report)
+    result = BaselineResult(path=path)
+    seen: set[str] = set()
+    kept: list[Issue] = []
+    for issue in report.issues:
+        fp = fingerprint(issue, root) if baselinable(issue) else None
+        if fp is not None and fp in known:
+            seen.add(fp)
+            result.suppressed += 1
+            result.suppressed_codes[issue.code] = result.suppressed_codes.get(issue.code, 0) + 1
+            continue
+        kept.append(issue)
+    report.issues = kept
+
+    try:
+        entries = json.loads(path.read_text(encoding="utf-8")).get("issues", [])
+    except (OSError, ValueError):
+        entries = []
+    result.stale = sum(
+        1
+        for e in entries
+        if e.get("fingerprint") not in seen and e.get("category") in scanned_categories
+    )
+    report.scanner_meta["baseline"] = {
+        "file": str(path),
+        "suppressed": result.suppressed,
+        "stale": result.stale,
+    }
+    return result

{pydoctor_cli-2.2.0 → pydoctor_cli-2.3.0}/pydoctor/core/report.py

@@ -60,8 +60,15 @@ class Issue:
             "recommendation": self.recommendation,
             "package": self.package,
             "extra": self.extra,
+            "docs_url": self.docs_url,
         }
 
+    @property
+    def docs_url(self) -> str:
+        from pydoctor.reports.docs_links import docs_url
+
+        return docs_url(self)
+
 
 # ──────────────────────────────────────────────────────────────
 # DiagnosisReport — aggregated result of all scans
@@ -89,6 +96,7 @@ class DiagnosisReport:
     scanner_meta: dict = field(default_factory=dict)
     ctx: Any = None
     command: str | None = None
+    scanners: list[str] = field(default_factory=list)  # scanner keys that ran
 
     # ── Convenience helpers ────────────────────────────────────
 

pydoctor_cli-2.3.0/pydoctor/reports/docs_links.py

@@ -0,0 +1,52 @@
+"""
+pydoctor/reports/docs_links.py
+───────────────────────────────
+Link every issue to the page of the documentation that explains it.
+
+Anchors here must exist on https://pydoctor-docs.thally.app. Specific
+troubleshooting entries win; otherwise the issue links to the section of
+the scanner reference that produced it.
+"""
+
+from __future__ import annotations
+
+from pydoctor.core.report import Issue
+
+DOCS_URL = "https://pydoctor-docs.thally.app"
+
+_BY_CODE: dict[str, str] = {
+    "ENV_PACKAGES_UNAVAILABLE": "/guides/troubleshooting#packages-unavailable",
+    "ENV_DEPS_NOT_INSTALLED": "/guides/troubleshooting#wrong-python",
+    "SEC_SCAN_INCOMPLETE": "/guides/troubleshooting#scan-incomplete",
+    "CI_ENV_FILE_COMMITTED": "/guides/troubleshooting#env-file-committed",
+    "CI_ENV_FILE_NOT_IGNORED": "/guides/troubleshooting#env-file-committed",
+    "CI_PULL_REQUEST_TARGET_CHECKOUT": "/scanners#workflow-checks",
+    "CI_SCRIPT_INJECTION": "/scanners#workflow-checks",
+    "CI_BROAD_PERMISSIONS": "/scanners#workflow-checks",
+    "CI_UNPINNED_ACTION": "/scanners#workflow-checks",
+    "CI_CLEARTEXT_ENV": "/scanners#workflow-checks",
+    "SEC_VULNERABILITY": "/scanners#severity",
+}
+
+_BY_PREFIX: dict[str, str] = {
+    "SECRET_EXPOSED_": "/scanners#secret-rules",
+}
+
+_BY_CATEGORY: dict[str, str] = {
+    "environment": "/scanners#environment",
+    "dependencies": "/scanners#dependencies",
+    "outdated": "/scanners#outdated-packages",
+    "security": "/scanners#security",
+    "unused": "/scanners#unused-packages",
+    "ci": "/scanners#ci-cd",
+}
+
+
+def docs_url(issue: Issue) -> str:
+    """The documentation page for ``issue`` (falls back to the docs home)."""
+    path = _BY_CODE.get(issue.code)
+    if path is None:
+        path = next((p for prefix, p in _BY_PREFIX.items() if issue.code.startswith(prefix)), None)
+    if path is None:
+        path = _BY_CATEGORY.get(issue.category, "")
+    return DOCS_URL + path