diffcone 0.1.0__py3-none-any.whl

diffcone/manifest.py

@@ -0,0 +1,166 @@
+"""Target manifest.
+
+Tells the planner which runnable targets exist, which symbol each one enters
+through, and which setup/fixture symbols it depends on: hand-written, or
+written by ``diffcone discover`` from static discovery. Unknown keys are
+errors, so a misspelt key cannot silently drop dependencies.
+
+Format (JSON)::
+
+    {
+      "source_roots": ["src", "tests"],          # optional, CLI overrides; "DIR=PREFIX" allowed
+      "targets": [
+        {
+          "runner": "pytest",
+          "runner_id": "tests/test_calc.py::test_add",
+          "entry_symbol": "tests.test_calc.test_add",
+          "lifecycle_dependencies": ["tests.conftest.db"]
+        }
+      ],
+      "discovery": {...}                         # optional, written by discover
+    }
+
+``discovery`` carries the notes discovery made (``runners[].notes``); notes
+saying the target list may be short keep a plan made from the manifest at
+exit code 3, as a plan that discovered the targets itself would be.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class ManifestError(Exception):
+    """The manifest is malformed."""
+
+
+@dataclass(frozen=True, order=True)
+class Target:
+    runner: str
+    runner_id: str
+    entry_symbol: str
+    lifecycle_dependencies: tuple[str, ...] = ()
+
+    @property
+    def node_id(self) -> str:
+        return f"target:{self.runner}:{self.runner_id}"
+
+
+@dataclass
+class Manifest:
+    targets: list[Target]
+    source_roots: list[str] | None = None
+    # (runner, kind, detail, path) for each note ``discover`` recorded.
+    notes: list[tuple[str, str, str, str]] = field(default_factory=list)
+
+
+MANIFEST_KEYS = frozenset({"source_roots", "targets", "discovery"})
+TARGET_KEYS = frozenset({"runner", "runner_id", "entry_symbol", "lifecycle_dependencies"})
+
+
+def _unknown_keys(obj: dict[str, Any], allowed: frozenset[str], where: str) -> None:
+    unknown = sorted(set(obj) - allowed)
+    if unknown:
+        raise ManifestError(
+            f"{where}: unknown key(s) {', '.join(map(repr, unknown))} "
+            f"(allowed: {', '.join(sorted(allowed))})"
+        )
+
+
+def _discovery_notes(discovery: Any) -> list[tuple[str, str, str, str]]:
+    if not isinstance(discovery, dict) or not isinstance(discovery.get("runners", []), list):
+        raise ManifestError("manifest: 'discovery' must be an object with a 'runners' list")
+    notes: list[tuple[str, str, str, str]] = []
+    for i, runner in enumerate(discovery.get("runners", [])):
+        where = f"discovery.runners[{i}]"
+        if not isinstance(runner, dict) or not isinstance(runner.get("notes", []), list):
+            raise ManifestError(f"{where}: must be an object with a 'notes' list")
+        name = _require_str(runner, "runner", where)
+        for j, note in enumerate(runner.get("notes", [])):
+            if not isinstance(note, dict):
+                raise ManifestError(f"{where}.notes[{j}]: must be an object")
+            path = note.get("path", "")
+            notes.append(
+                (
+                    name,
+                    _require_str(note, "kind", f"{where}.notes[{j}]"),
+                    _require_str(note, "detail", f"{where}.notes[{j}]"),
+                    path if isinstance(path, str) else "",
+                )
+            )
+    return notes
+
+
+def _require_str(obj: dict[str, Any], key: str, where: str) -> str:
+    value = obj.get(key)
+    if not isinstance(value, str) or not value:
+        raise ManifestError(f"{where}: {key!r} must be a non-empty string")
+    return value
+
+
+def parse_manifest(data: Any) -> Manifest:
+    if isinstance(data, list):
+        data = {"targets": data}
+    if not isinstance(data, dict):
+        raise ManifestError("manifest must be a JSON object or a list of targets")
+    _unknown_keys(data, MANIFEST_KEYS, "manifest")
+    raw_targets = data.get("targets")
+    if not isinstance(raw_targets, list):
+        raise ManifestError("manifest: 'targets' must be a list")
+    source_roots = data.get("source_roots")
+    if source_roots is not None and (
+        not isinstance(source_roots, list) or not all(isinstance(r, str) for r in source_roots)
+    ):
+        raise ManifestError("manifest: 'source_roots' must be a list of strings")
+
+    targets: list[Target] = []
+    seen: set[tuple[str, str]] = set()
+    for i, raw in enumerate(raw_targets):
+        where = f"targets[{i}]"
+        if not isinstance(raw, dict):
+            raise ManifestError(f"{where}: must be an object")
+        _unknown_keys(raw, TARGET_KEYS, where)
+        runner = _require_str(raw, "runner", where)
+        runner_id = _require_str(raw, "runner_id", where)
+        entry = _require_str(raw, "entry_symbol", where)
+        deps = raw.get("lifecycle_dependencies", [])
+        if not isinstance(deps, list) or not all(isinstance(d, str) and d for d in deps):
+            raise ManifestError(f"{where}: 'lifecycle_dependencies' must be a list of strings")
+        key = (runner, runner_id)
+        if key in seen:
+            raise ManifestError(f"{where}: duplicate target {runner}:{runner_id}")
+        seen.add(key)
+        targets.append(Target(runner, runner_id, entry, tuple(sorted(set(deps)))))
+    notes = _discovery_notes(data["discovery"]) if "discovery" in data else []
+    return Manifest(targets=targets, source_roots=source_roots, notes=notes)
+
+
+def manifest_to_dict(
+    targets: list[Target], source_roots: list[str] | None = None
+) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+    if source_roots:
+        data["source_roots"] = list(source_roots)
+    data["targets"] = [
+        {
+            "runner": t.runner,
+            "runner_id": t.runner_id,
+            "entry_symbol": t.entry_symbol,
+            "lifecycle_dependencies": list(t.lifecycle_dependencies),
+        }
+        for t in sorted(targets)
+    ]
+    return data
+
+
+def load_manifest(path: str | Path) -> Manifest:
+    try:
+        data = json.loads(Path(path).read_text("utf-8"))
+    except (OSError, ValueError) as exc:  # ValueError covers UnicodeDecodeError
+        raise ManifestError(f"cannot read manifest {path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"manifest {path} is not valid JSON: {exc}") from exc
+    return parse_manifest(data)

diffcone/model.py

@@ -0,0 +1,191 @@
+"""Explicit data structures shared by the indexer, classifier and planner.
+
+Symbol identity is the dotted qualified name (``pkg.mod``, ``pkg.mod.func``,
+``pkg.mod.Class.method``). Source locations are metadata only.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from diffcone.cython import CythonModule
+
+MODULE = "module"
+CLASS = "class"
+FUNCTION = "function"
+METHOD = "method"
+VARIABLE = "variable"  # a simple module-level assignment ``NAME = <expr>``
+
+# Edge kinds. ``source`` depends on ``target``.
+REFERENCES = "references"  # name/call/attribute reference resolved to a symbol
+DEFINED_IN = "defined_in"  # symbol is defined inside the target container
+IMPORTS = "imports"  # module-level import of a module (init-time dependency)
+IMPORTS_NAME = "imports_name"  # module-level ``from m import name`` of a symbol
+UNRESOLVED_NAME_MATCH = "unresolved_name_match"  # conservative edge synthesised by the planner
+DECLARED = "declared"  # dependency stated in diffcone.toml, not found by analysis
+ENTRY = "entry"  # target -> its entry symbol
+LIFECYCLE = "lifecycle"  # target -> declared setup/fixture dependency
+
+# Unresolved reference kinds.
+UNRESOLVED_NAME = "name"  # bare name that resolves to nothing known
+UNRESOLVED_ATTRIBUTE = "attribute"  # ``<unknown>.name`` — bounded by the attribute name
+UNRESOLVED_DYNAMIC = "dynamic"  # getattr/importlib/eval with non-literal arguments
+OPAQUE_ATTRIBUTE = "*"  # SourceIndex.class_attributes: class-body code binding nothing by name
+CLASS_STATEMENT = "(statement)"  # SourceIndex.class_attributes: bases, keywords, decorators
+
+
+@dataclass(frozen=True, order=True)
+class Symbol:
+    id: str
+    kind: str
+    module: str
+    name: str
+    path: str
+    lineno: int
+    body_hash: str
+    definition_hash: str
+    container: str | None
+    # Source line spans of every definition of this symbol (metadata, not
+    # identity); used by coverage-based validation to map executed lines back
+    # to symbols.
+    line_ranges: tuple[tuple[int, int], ...] = ()
+    # Modules only: canonical import bindings ("import a as b", "from m import n"),
+    # sorted. Lets the classifier tell additions from removals/redirections.
+    imports: tuple[str, ...] = ()
+    # Modules only: each import binding with the block it sits in, in source
+    # order. Moving an import (under ``if TYPE_CHECKING:``, into a ``try``)
+    # or reordering imports changes what runs at import, though the set of
+    # bindings is the same: only pure insertions are ``imports_added``.
+    import_layout: tuple[str, ...] = ()
+    # Hash of the docstring alone; body_hash excludes it. A docstring-only edit
+    # is reported as docstring_changed and carries no impact, except where
+    # code runs it: under a non-inert decorator (or a class decorator or
+    # metaclass) the docstring is part of the definition hash, and a module
+    # whose own code names ``__doc__`` has it in its body hash.
+    docstring_hash: str = ""
+    # Functions: hash of the parameter and return annotations, which
+    # definition_hash excludes, and whether they are never evaluated at
+    # import (``from __future__ import annotations``, no decorator that could
+    # read them, a plain class): an annotation-only change then does not run
+    # at import (annotations_changed).
+    annotation_hash: str = ""
+    deferred_annotations: bool = False
+    # Functions: the ``def`` statement runs no code at import beyond binding
+    # the name (inert decorators, literal defaults, deferred or no
+    # annotations, a plain class for methods).
+    inert_definition: bool = False
+    # Functions: the decorators and defaults alone run nothing (annotations
+    # aside): adding such a function registers nothing anywhere.
+    inert_header: bool = False
+    # The symbol's own code reads a docstring (``obj.__doc__``, ``__doc__``,
+    # ``getdoc(obj)``): a docstring change of what it references, or of its
+    # module, reaches it.
+    reads_docstrings: bool = False
+
+
+@dataclass(frozen=True, order=True)
+class Edge:
+    source: str
+    target: str
+    kind: str
+    detail: str = ""
+
+
+@dataclass(frozen=True, order=True)
+class UnresolvedReference:
+    symbol: str
+    kind: str
+    name: str
+    detail: str
+
+
+@dataclass(frozen=True, order=True)
+class ExternalReference:
+    symbol: str
+    module: str
+
+
+@dataclass(frozen=True, order=True)
+class AnalysisError:
+    revision: str
+    path: str
+    message: str
+
+
+KIND_COMMIT = "commit"
+KIND_INDEX = "index"
+KIND_WORKTREE = "worktree"
+
+
+@dataclass(frozen=True)
+class SnapshotInfo:
+    """What a snapshot is: carried unchanged from the reader to the report."""
+
+    revision: str
+    commit: str
+    kind: str = KIND_COMMIT
+    description: str = ""
+
+    @property
+    def committed(self) -> bool:
+        return self.kind == KIND_COMMIT
+
+    @property
+    def is_worktree(self) -> bool:
+        return self.kind == KIND_WORKTREE
+
+
+@dataclass
+class SourceIndex:
+    snapshot: SnapshotInfo
+    modules: set[str] = field(default_factory=set)
+    symbols: dict[str, Symbol] = field(default_factory=dict)
+    edges: set[Edge] = field(default_factory=set)
+    unresolved: set[UnresolvedReference] = field(default_factory=set)
+    external: set[ExternalReference] = field(default_factory=set)
+    errors: list[AnalysisError] = field(default_factory=list)
+    # Modules that failed to parse; their symbols are unknown in this revision.
+    failed_modules: set[str] = field(default_factory=set)
+    # Classes whose instances are passed to someone else, who may then read
+    # any attribute off them by a name nothing resolves.
+    escaped_classes: set[str] = field(default_factory=set)
+    # The non-Python files under the source roots: path -> git blob id. The
+    # index reads none of them, so the planner compares them whole.
+    other_files: dict[str, str] = field(default_factory=dict)
+    # Cython sources among them (.pyx, .pxd, .pxi) at function level: path ->
+    # module (diffcone.cython). Static planning does not use these; evidence
+    # mode diffs them to find the Cython functions a change touched.
+    cython: dict[str, CythonModule] = field(default_factory=dict)
+    # (symbol, detail): code that observes names or signatures reflectively
+    # without naming them (``dir``, ``hasattr``, ``inspect.signature``, a
+    # ``__dict__`` read). Static planning does not use these; evidence mode
+    # counts them as sites that notice an added, deleted or redefined name.
+    reflection: set[tuple[str, str]] = field(default_factory=set)
+    # Class -> {attribute bound in the class body: hash of its statements}.
+    # Class attributes are not symbols; evidence mode compares these to find
+    # which attribute names a class-body change touched. ``OPAQUE_ATTRIBUTE``
+    # hashes every other statement of the body (a loop, a call, a ``del``),
+    # ``CLASS_STATEMENT`` the bases, keywords and decorators.
+    class_attributes: dict[str, dict[str, str]] = field(default_factory=dict)
+    # Class -> the in-scope classes its statement names as bases (resolved).
+    # Evidence mode walks class hierarchies with it; static planning does not
+    # use it.
+    class_bases: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    # Classes whose creation may run code that reads their attributes:
+    # decorators, keywords (a metaclass), or a base the index cannot see
+    # (``Enum``, a dataclass-like framework base). Evidence mode escalates an
+    # attribute change of one rather than trusting readers of the name.
+    open_classes: set[str] = field(default_factory=set)
+    # Functions and classes whose decorators (or metaclass) may read their
+    # docstring: one the analysis cannot see, or in-scope code that reads
+    # ``__doc__`` (pandas' ``@doc``). A docstring-only change of one runs at
+    # import; of any other symbol it runs nothing.
+    doc_decorated: set[str] = field(default_factory=set)
+
+    @property
+    def revision(self) -> str:
+        return self.snapshot.revision
+
+    @property
+    def commit(self) -> str:
+        return self.snapshot.commit