docs-drift 0.1.0__py3-none-any.whl

docs_drift/__init__.py

@@ -0,0 +1,7 @@
+"""Find drift between documentation and statically inspected code."""
+
+from importlib.metadata import version
+
+__version__ = version("docs-drift")
+
+__all__ = ["__version__"]

docs_drift/analysis.py

@@ -0,0 +1,52 @@
+"""Aggregate evidence-backed findings and select findings touched by a Git change."""
+
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from docs_drift.config import Config
+from docs_drift.docs.pipeline import _head
+from docs_drift.history import _run
+from docs_drift.models import ScanResult
+from docs_drift.scanning import run_scan
+
+
+def insights(result: ScanResult) -> dict[str, Any]:
+    drift = [f for f in result.findings if f.is_drift and f.confidence >= result.config_used.min_confidence]
+    return {
+        "head_sha": result.head_sha,
+        "claims": len(result.claims),
+        "verdicts": result.summary()["by_verdict"],
+        "drift_by_document": dict(sorted(Counter(f.claim.doc_path for f in drift).items())),
+        "drift_by_package": dict(sorted(Counter(f.package or "." for f in drift).items())),
+        "with_introducing_commit": sum(f.introduced_by is not None for f in drift),
+        "warnings": result.warnings,
+    }
+
+
+def changed_paths(repo: Path, base: str, head: str) -> list[str]:
+    for ref in (base, head):
+        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_./~^{}-]{0,199}", ref) or ".." in ref:
+            raise ValueError("Use a single Git revision without options, whitespace or revision ranges.")
+    result = _run(repo, ["diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", base, head, "--"])
+    if result is None:
+        raise ValueError("Cannot compare these revisions. Fetch the base commit or choose a revision that exists.")
+    return sorted(p.replace("\\", "/") for p in result.stdout.split("\0") if p)
+
+
+def impact(repo: Path, config: Config, base: str, head: str = "HEAD") -> ScanResult:
+    """Report current findings linked to changed docs/source; not a runtime dependency proof."""
+    paths = set(changed_paths(repo, base, head))
+    resolved = _run(repo, ["rev-parse", "--verify", head])
+    if not resolved or resolved.stdout.strip() != _head(repo):
+        raise ValueError("Impact scans the current checkout; --head must resolve to its HEAD.")
+    result = run_scan(repo, config)
+    selected = [
+        f
+        for f in result.findings
+        if f.claim.doc_path in paths
+        or (f.matched_symbol and f.matched_symbol.file in paths)
+        or any(e.file in paths for e in f.evidence)
+    ]
+    return result.model_copy(update={"findings": selected, "claims": [f.claim for f in selected]})

docs_drift/baseline.py

@@ -0,0 +1,70 @@
+"""Read and write explicit finding baselines without running scanned code."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from docs_drift.models import DecidedBy, Finding, Verdict
+from docs_drift.safe_files import metadata_text
+
+
+class BaselineEntry(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    finding_id: str = Field(min_length=1)
+    verdict: Verdict
+    doc_path: str = Field(min_length=1)
+    claim: str = Field(min_length=1)
+    decided_by: DecidedBy = DecidedBy.rules
+    replayed: bool = False
+
+
+class FindingBaseline(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    findings: list[BaselineEntry] = Field(default_factory=list)
+
+
+def finding_id(finding: Finding) -> str:
+    """Claim IDs are stable across line shifts and suitable for baseline updates."""
+    return finding.claim.claim_id
+
+
+def load_baseline(path: Path) -> FindingBaseline:
+    try:
+        return FindingBaseline.model_validate_json(metadata_text(path))
+    except ValidationError:
+        # Pydantic's default diagnostics can echo claim text from the input file.
+        raise ValueError(
+            f"Invalid baseline JSON or schema at {path}. Regenerate it from a reviewed scan with baseline update."
+        ) from None
+    except OSError as exc:
+        raise ValueError(f"Cannot read baseline {path}: {exc}. Check the path and permissions.") from exc
+
+
+def save_baseline(path: Path, findings: list[Finding]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    entries = [
+        BaselineEntry(
+            finding_id=finding_id(item),
+            verdict=item.verdict,
+            doc_path=item.claim.doc_path,
+            claim=item.claim.value,
+            decided_by=item.decided_by,
+            replayed=item.replayed,
+        )
+        for item in findings
+        if item.is_drift
+    ]
+    entries.sort(key=lambda item: (item.doc_path, item.claim, item.finding_id))
+    path.write_text(FindingBaseline(findings=entries).model_dump_json(indent=2) + "\n", encoding="utf-8")
+
+
+def new_findings(findings: list[Finding], baseline: FindingBaseline) -> list[Finding]:
+    # A changed verdict must be reviewed again even when the claim stayed put.
+    known = {(entry.finding_id, entry.verdict) for entry in baseline.findings}
+    return [item for item in findings if item.is_drift and (finding_id(item), item.verdict) not in known]