deadtrace 0.1.0a1__py3-none-any.whl

deadtrace/__init__.py

@@ -0,0 +1,10 @@
+"""Deadtrace public package metadata."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("deadtrace")
+except PackageNotFoundError:  # pragma: no cover - source-tree fallback
+    __version__ = "0.1.0a1"
+
+__all__ = ["__version__"]

deadtrace/__main__.py

@@ -0,0 +1,6 @@
+"""Support ``python -m deadtrace``."""
+
+from deadtrace.cli import app
+
+if __name__ == "__main__":
+    app()

deadtrace/analysis.py

@@ -0,0 +1,223 @@
+"""End-to-end static analysis orchestration."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field, replace
+from hashlib import sha256
+from pathlib import Path
+from time import perf_counter
+
+from deadtrace.config import Config
+from deadtrace.core import AnalysisSnapshot, AssemblyState, Limitation, solve
+from deadtrace.deployment import read_deployment_references
+from deadtrace.entry_points import read_project_entry_points
+from deadtrace.findings import Finding, build_findings
+from deadtrace.frameworks import FrameworkModel, build_framework_model
+from deadtrace.model import InventoryReport
+from deadtrace.pytest_semantics import apply_pytest_model, read_pytest_collection
+from deadtrace.python_frontend import PythonProgram, build_python_program
+from deadtrace.scanner import (
+    SourceCollection,
+    collect_sources,
+    inventory_collection,
+    parse_collection,
+)
+from deadtrace.target_environment import (
+    UNTESTED_VERSION,
+    TargetEnvironment,
+    read_target_environment,
+)
+from deadtrace.timing import StageTimings
+
+MODEL_REVISION = "python-fastapi-dishka/31"
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisMetrics:
+    files: int
+    lines: int
+    nodes: int
+    edges: int
+    worlds: int
+    collect_seconds: float
+    frontend_seconds: float
+    solve_seconds: float
+    total_seconds: float
+    stage_seconds: Mapping[str, float] = field(default_factory=dict)
+    counters: Mapping[str, int] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class AnalysisResult:
+    collection: SourceCollection
+    inventory: InventoryReport
+    program: PythonProgram
+    model: FrameworkModel
+    snapshot: AnalysisSnapshot
+    findings: tuple[Finding, ...]
+    source_digest: str
+    config_digest: str
+    model_revision: str
+    target_environment: TargetEnvironment
+    metrics: AnalysisMetrics
+
+    @property
+    def complete(self) -> bool:
+        return bool(self.snapshot.worlds) and all(
+            world.assembly_state is AssemblyState.COMPLETE and not world.exhausted_budget
+            for world in self.snapshot.worlds
+        )
+
+    @property
+    def has_operational_errors(self) -> bool:
+        return self.inventory.has_errors or any(
+            world.assembly_state is AssemblyState.INVALID for world in self.snapshot.worlds
+        )
+
+
+def analyze(scan_path: Path, config: Config) -> AnalysisResult:
+    """Run one immutable, read-only analysis snapshot."""
+
+    timings = StageTimings()
+    started = perf_counter()
+    collection = collect_sources(scan_path, timings=timings, exclude=config.exclude)
+    parsed = parse_collection(collection, timings=timings)
+    inventory = inventory_collection(collection, config, timings=timings, parsed=parsed)
+    collected_at = perf_counter()
+    program = build_python_program(
+        collection, report_exclude=config.report_exclude, timings=timings, parsed=parsed
+    )
+    with timings.stage("frontend.entry_points"):
+        entry_points, entry_point_issues = read_project_entry_points(collection.root)
+    with timings.stage("frontend.deployment"):
+        deployment = (
+            () if config.worlds else read_deployment_references(collection.root, config.exclude)
+        )
+    model = build_framework_model(
+        program,
+        config,
+        entry_points=entry_points,
+        entry_point_issues=entry_point_issues,
+        deployment=deployment,
+        timings=timings,
+    )
+    with timings.stage("frontend.pytest"):
+        model = apply_pytest_model(
+            program,
+            model,
+            config,
+            plugin_modules=tuple(
+                entry_point.target.partition(":")[0]
+                for entry_point in entry_points
+                if entry_point.group == "pytest11"
+            ),
+            collection=read_pytest_collection(collection.root),
+        )
+    with timings.stage("frontend.target_environment"):
+        target_environment = read_target_environment(
+            collection.root,
+            {
+                binding.target.split(".", 1)[0]
+                for module in program.modules.values()
+                for binding in module.imports.values()
+            },
+        )
+    if target_environment.issues:
+        model.plans = tuple(
+            replace(
+                plan,
+                assembly_state=(
+                    plan.assembly_state
+                    if plan.assembly_state is AssemblyState.INVALID
+                    or all(issue.code == UNTESTED_VERSION for issue in target_environment.issues)
+                    else AssemblyState.PARTIAL
+                ),
+                limitations=tuple(
+                    (
+                        *plan.limitations,
+                        *(
+                            Limitation(
+                                code=issue.code,
+                                message=issue.message,
+                                world=plan.id,
+                            )
+                            for issue in target_environment.issues
+                        ),
+                    )
+                ),
+            )
+            for plan in model.plans
+        )
+    if inventory.issues:
+        model.plans = tuple(
+            replace(
+                plan,
+                assembly_state=(
+                    AssemblyState.INVALID
+                    if plan.assembly_state is AssemblyState.INVALID
+                    else AssemblyState.PARTIAL
+                ),
+                limitations=tuple(
+                    (
+                        *plan.limitations,
+                        *(
+                            Limitation(
+                                code=issue.code,
+                                message=f"{issue.path}: {issue.message}",
+                                world=plan.id,
+                            )
+                            for issue in inventory.issues
+                        ),
+                    )
+                ),
+            )
+            for plan in model.plans
+        )
+    frontend_at = perf_counter()
+    with timings.stage("solve.reachability"):
+        snapshot = solve(model.graph, model.plans, max_steps=config.max_steps)
+    with timings.stage("solve.findings"):
+        findings = build_findings(program, model, snapshot)
+    solved_at = perf_counter()
+    timings.count("findings", len(findings))
+    metrics = AnalysisMetrics(
+        files=len(collection.files),
+        lines=sum(unit.source.count("\n") + 1 for unit in collection.units),
+        nodes=len(model.graph.nodes),
+        edges=len(model.graph.edges),
+        worlds=len(snapshot.worlds),
+        collect_seconds=collected_at - started,
+        frontend_seconds=frontend_at - collected_at,
+        solve_seconds=solved_at - frontend_at,
+        total_seconds=solved_at - started,
+        stage_seconds=timings.frozen_seconds(),
+        counters=timings.frozen_counts(),
+    )
+    return AnalysisResult(
+        collection=collection,
+        inventory=inventory,
+        program=program,
+        model=model,
+        snapshot=snapshot,
+        findings=findings,
+        source_digest=_source_digest(collection),
+        config_digest=_config_digest(config),
+        model_revision=MODEL_REVISION,
+        target_environment=target_environment,
+        metrics=metrics,
+    )
+
+
+def _source_digest(collection: SourceCollection) -> str:
+    canonical = "\n".join(f"{unit.path}:{unit.digest}" for unit in collection.units)
+    return sha256(canonical.encode()).hexdigest()
+
+
+def _config_digest(config: Config) -> str:
+    fields = asdict(config)
+    if not fields["exclude"]:
+        del fields["exclude"]  # configurations without it keep their earlier digest
+    canonical = json.dumps(fields, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return sha256(canonical.encode()).hexdigest()

deadtrace/artifacts.py

@@ -0,0 +1,87 @@
+"""Safe helpers for user-selected JSON artifacts."""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Any, NoReturn
+
+MAX_ARTIFACT_BYTES = 16 * 1024 * 1024
+"""Largest project input, such as ``pyproject.toml`` or ``uv.lock``, that analysis reads."""
+MAX_REPORT_BYTES = 256 * 1024 * 1024
+"""Largest Deadtrace report or baseline read back; a 624k-line monorepo writes about 113 MB."""
+
+
+class ArtifactError(ValueError):
+    """Raised when a report-like artifact is missing, oversized, or malformed."""
+
+
+class InputTooLargeError(ValueError):
+    """An opened input exceeded its reader's byte limit."""
+
+
+def read_bounded_bytes(path: Path, *, limit: int) -> bytes:
+    """Read at most ``limit + 1`` bytes, even if file size metadata is stale.
+
+    Small chunks avoid reserving the full report allowance for a small file. The extra byte
+    distinguishes an input exactly at the limit from one that is too large.
+    """
+
+    if limit < 0:
+        raise ValueError("byte limit must be nonnegative")
+    chunks: list[bytes] = []
+    size = 0
+    with path.open("rb") as stream:
+        while chunk := stream.read(min(64 * 1024, limit + 1 - size)):
+            size += len(chunk)
+            if size > limit:
+                raise InputTooLargeError(f"input {path} is too large; limit is {limit} bytes")
+            chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def read_json_artifact(path: Path) -> dict[str, Any]:
+    """Read a bounded JSON object without executing project code."""
+
+    try:
+        source = read_bounded_bytes(path, limit=MAX_REPORT_BYTES).decode("utf-8")
+        payload = json.loads(
+            source,
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_constant,
+            parse_float=_finite_float,
+        )
+    except ArtifactError:
+        raise
+    except (OSError, UnicodeError, ValueError, RecursionError) as error:
+        raise ArtifactError(f"cannot read artifact {path}: {error}") from error
+    if not isinstance(payload, dict):
+        raise ArtifactError(f"artifact {path} must contain a JSON object")
+    return payload
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ArtifactError(f"duplicate JSON key: {key!r}")
+        result[key] = value
+    return result
+
+
+def _reject_constant(value: str) -> NoReturn:
+    raise ArtifactError(f"non-finite JSON number: {value}")
+
+
+def _finite_float(value: str) -> float:
+    number = float(value)
+    if not math.isfinite(number):
+        raise ArtifactError(f"non-finite JSON number: {value}")
+    return number
+
+
+def render_json_artifact(payload: dict[str, Any]) -> str:
+    """Render deterministic UTF-8 JSON text."""
+
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"

deadtrace/baseline.py

@@ -0,0 +1,199 @@
+"""Baseline existing review findings without changing semantic analysis."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+
+from deadtrace.artifacts import ArtifactError, render_json_artifact
+from deadtrace.comparison import (
+    method_change_reasons,
+    method_descriptor,
+    validate_semantic_report,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class BaselineApplication:
+    payload: dict[str, Any]
+    comparable: bool
+    accepted: int
+    new: int
+    stale: int
+    reasons: tuple[str, ...] = ()
+
+
+def create_baseline(report: dict[str, Any], reason: str) -> dict[str, Any]:
+    """Create an explicit debt ledger from one reviewed semantic report."""
+
+    validate_semantic_report(report)
+    if not reason.strip():
+        raise ArtifactError("baseline reason must not be empty")
+    findings = report["findings"]
+    assert isinstance(findings, list)
+    return {
+        "schema_version": 1,
+        "kind": "deadtrace-baseline",
+        "method": method_descriptor(report),
+        "source_digest": report["descriptor"].get("source_digest"),
+        "entries": [
+            {
+                "fingerprint": finding["fingerprint"],
+                "code": finding.get("code"),
+                "members": finding.get("members", []),
+                "reason": reason,
+            }
+            for finding in findings
+            if isinstance(finding, dict)
+        ],
+    }
+
+
+def update_baseline(
+    baseline: dict[str, Any],
+    report: dict[str, Any],
+    *,
+    accept_new: bool = False,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """Rebase reviewed entries; accepting new findings always requires an explicit reason.
+
+    An entry carries over to a finding with its fingerprint, or with its code and exactly its
+    members when a method change renewed the fingerprint.
+    """
+
+    validate_baseline(baseline)
+    validate_semantic_report(report)
+    if accept_new and (reason is None or not reason.strip()):
+        raise ArtifactError("accepting new baseline findings requires a non-empty reason")
+    old_entries = baseline["entries"]
+    findings = report["findings"]
+    assert isinstance(old_entries, list)
+    assert isinstance(findings, list)
+    by_fingerprint = {
+        entry["fingerprint"]: entry for entry in old_entries if isinstance(entry, dict)
+    }
+    by_content = {_content_key(entry): entry for entry in old_entries if isinstance(entry, dict)}
+    entries: list[dict[str, Any]] = []
+    for finding in findings:
+        assert isinstance(finding, dict)
+        fingerprint = finding["fingerprint"]
+        old = by_fingerprint.get(fingerprint) or by_content.get(_content_key(finding))
+        if old is not None:
+            entries.append(
+                {
+                    **deepcopy(old),
+                    "fingerprint": fingerprint,
+                    "members": deepcopy(finding.get("members", [])),
+                }
+            )
+        elif accept_new:
+            entries.append(
+                {
+                    "fingerprint": fingerprint,
+                    "code": finding.get("code"),
+                    "members": finding.get("members", []),
+                    "reason": reason,
+                }
+            )
+    return {
+        "schema_version": 1,
+        "kind": "deadtrace-baseline",
+        "method": method_descriptor(report),
+        "source_digest": report["descriptor"].get("source_digest"),
+        "entries": entries,
+    }
+
+
+def validate_baseline(payload: dict[str, Any]) -> None:
+    if payload.get("schema_version") != 1 or payload.get("kind") != "deadtrace-baseline":
+        raise ArtifactError("baseline must use deadtrace-baseline schema 1")
+    if not isinstance(payload.get("method"), dict):
+        raise ArtifactError("baseline method must be an object")
+    entries = payload.get("entries")
+    if not isinstance(entries, list):
+        raise ArtifactError("baseline entries must be an array")
+    fingerprints: set[str] = set()
+    for entry in entries:
+        if not isinstance(entry, dict) or not isinstance(entry.get("fingerprint"), str):
+            raise ArtifactError("every baseline entry must have a string fingerprint")
+        fingerprint = entry["fingerprint"]
+        if fingerprint in fingerprints:
+            raise ArtifactError(f"duplicate baseline fingerprint: {fingerprint}")
+        fingerprints.add(fingerprint)
+
+
+def apply_baseline(report: dict[str, Any], baseline: dict[str, Any]) -> BaselineApplication:
+    """Annotate a report; never remove findings or limitations."""
+
+    validate_semantic_report(report)
+    validate_baseline(baseline)
+    reasons = method_change_reasons(baseline["method"], method_descriptor(report))
+    comparable = not reasons
+    entries = baseline["entries"]
+    assert isinstance(entries, list)
+    baseline_fingerprints = {entry["fingerprint"] for entry in entries if isinstance(entry, dict)}
+    projected = deepcopy(report)
+    findings = projected["findings"]
+    assert isinstance(findings, list)
+    current = {
+        finding["fingerprint"]
+        for finding in findings
+        if isinstance(finding, dict) and isinstance(finding.get("fingerprint"), str)
+    }
+    accepted = current.intersection(baseline_fingerprints) if comparable else set()
+    for finding in findings:
+        assert isinstance(finding, dict)
+        finding["baseline_status"] = "accepted" if finding["fingerprint"] in accepted else "new"
+    stale = baseline_fingerprints - current
+    summary = projected.get("summary")
+    if not isinstance(summary, dict):
+        summary = {}
+        projected["summary"] = summary
+    summary.update(
+        {
+            "baselined_finding_count": len(accepted),
+            "new_finding_count": len(current - accepted),
+            "stale_baseline_count": len(stale),
+        }
+    )
+    projected["baseline"] = {
+        "status": "comparable" if comparable else "incomparable",
+        "reasons": list(reasons),
+        "source_digest": baseline.get("source_digest"),
+        "stale_fingerprints": sorted(stale),
+    }
+    return BaselineApplication(
+        payload=projected,
+        comparable=comparable,
+        accepted=len(accepted),
+        new=len(current - accepted),
+        stale=len(stale),
+        reasons=reasons,
+    )
+
+
+def _content_key(item: dict[str, Any]) -> tuple[object, ...]:
+    """A finding's code and member identities, the content its fingerprint hashes."""
+
+    members = item.get("members", [])
+    return (
+        item.get("code"),
+        tuple(
+            sorted(
+                (
+                    str(member.get("path")),
+                    str(member.get("qualified_name")),
+                    str(member.get("kind")),
+                    str(member.get("occurrence")),
+                )
+                for member in (members if isinstance(members, list) else [])
+                if isinstance(member, dict)
+            )
+        ),
+    )
+
+
+def render_baseline_json(payload: dict[str, Any]) -> str:
+    return render_json_artifact(payload)