diffcone 0.1.0__py3-none-any.whl

diffcone/declarations.py

@@ -0,0 +1,111 @@
+"""Dependencies a project declares that the analysis cannot see.
+
+A registry filled at import time, a plugin resolved through entry points, a
+handler named in a YAML file: the dependency is real and no static rule can
+find it, so the project states it in ``diffcone.toml`` at the repository
+root. The file is read from both snapshots being compared, so a declaration
+is versioned with the code it describes, and one the change deletes still
+counts.
+
+    # diffcone.toml
+    [[edges]]
+    from = "pkg.registry.dispatch"   # a symbol or a module, in either revision
+    to = "pkg.handlers.json"
+    why = "handlers register themselves through entry points"
+
+Declarations only *add* edges, so they can only widen selection: a wrong one
+costs a test that runs anyway, and none of them can make the plan miss. A
+declaration whose endpoints resolve to nothing, or a file that does not
+parse, is an analysis error -- a typo that silently declares nothing is the
+outcome worth failing on.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from diffcone.snapshot import INDEX, WORKTREE, GitError, read_files, resolve_commit
+
+FILENAME = "diffcone.toml"
+
+
+@dataclass(frozen=True, order=True)
+class Declaration:
+    source: str
+    target: str
+    why: str = ""
+
+    @property
+    def detail(self) -> str:
+        return f"declared in {FILENAME}" + (f": {self.why}" if self.why else "")
+
+
+class Unreadable(Exception):
+    """The file is there (or the snapshot cannot be read) but we could not
+    get at it. Distinct from absent, which is the normal case: silently
+    treating a read failure as "no declarations" narrows the plan."""
+
+
+def read_file(repo: Path, revision: str) -> bytes | None:
+    """``diffcone.toml`` as the given snapshot has it, or None when absent."""
+    if revision == WORKTREE:
+        path = repo / FILENAME
+        if not path.is_file():
+            return None
+        try:
+            return path.read_bytes()
+        except OSError as exc:
+            raise Unreadable(f"{FILENAME}: {exc}") from exc
+    try:
+        commit = "" if revision == INDEX else resolve_commit(repo, revision)
+    except GitError as exc:  # an unknown revision is the caller's problem
+        raise Unreadable(f"{FILENAME}: {exc}") from exc
+    try:
+        return read_files(repo, commit, [FILENAME], label=revision).get(FILENAME)
+    except GitError:
+        return None  # not in this snapshot: the ordinary case
+
+
+def parse(raw: bytes) -> tuple[list[Declaration], list[str]]:
+    """Declarations and the problems found; a problem is an analysis error."""
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        return [], [f"{FILENAME}: {exc}"]
+    problems: list[str] = []
+    edges: list[Declaration] = []
+    unknown_tables = sorted(set(data) - {"edges"})
+    if unknown_tables:
+        # A singular ``[[edge]]`` or a capitalisation slip would otherwise
+        # declare nothing at all, quietly.
+        problems.append(f"{FILENAME}: unknown top-level key(s) {', '.join(unknown_tables)}")
+    entries = data.get("edges", [])
+    if not isinstance(entries, list):
+        return [], [f"{FILENAME}: 'edges' must be a list of tables"]
+    for i, entry in enumerate(entries, start=1):
+        if not isinstance(entry, dict):
+            problems.append(f"{FILENAME}: edge {i} is not a table")
+            continue
+        unknown = sorted(set(entry) - {"from", "to", "why"})
+        if unknown:
+            problems.append(f"{FILENAME}: edge {i} has unknown key(s) {', '.join(unknown)}")
+            continue
+        source, target, why = entry.get("from"), entry.get("to"), entry.get("why", "")
+        if not isinstance(source, str) or not isinstance(target, str) or not (source and target):
+            problems.append(f"{FILENAME}: edge {i} needs a 'from' and a 'to'")
+            continue
+        if not isinstance(why, str):
+            problems.append(f"{FILENAME}: edge {i} has a non-string 'why'")
+            continue
+        edges.append(Declaration(source, target, why))
+    return edges, problems
+
+
+def load(repo: Path, revision: str) -> tuple[list[Declaration], list[str]]:
+    try:
+        raw = read_file(repo, revision)
+    except Unreadable as exc:
+        return [], [str(exc)]
+    return parse(raw) if raw is not None else ([], [])

diffcone/discovery/__init__.py

@@ -0,0 +1,121 @@
+"""Static runner discovery.
+
+Discovery turns a head snapshot into manifest targets without importing or
+executing project code. Each runner module documents the subset of its
+runner's collection rules that it reproduces; anything outside that subset
+surfaces as a note or as an unresolved lifecycle dependency, which the
+planner treats conservatively.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from diffcone.manifest import Target
+from diffcone.model import SourceIndex
+from diffcone.snapshot import Snapshot
+
+RUNNERS = ("pytest", "asv")
+
+# Modules the runner's own process imports and runs, whoever the project
+# is: when one of them (or anything under it) is in the source roots, the
+# runner executes project code for every target it runs. pytest imports
+# only ``packaging.version``/``packaging.requirements`` from packaging.
+RUNNER_MODULES: dict[str, tuple[str, ...]] = {
+    "pytest": (
+        "_pytest",
+        "pytest",
+        "pluggy",
+        "iniconfig",
+        "exceptiongroup",
+        "tomli",
+        "colorama",
+        "packaging.version",
+        "packaging.requirements",
+    ),
+}
+
+
+@dataclass(frozen=True, order=True)
+class DiscoveryNote:
+    runner: str
+    kind: str
+    detail: str
+    # The file the note is about, for the notes that mean the target list
+    # may be short: evidence mode checks whether it changed since a
+    # recording settled the note (roadmap item 9).
+    path: str = ""
+
+
+@dataclass
+class DiscoveryOptions:
+    # Fixture names supplied by installed plugins that should not be treated
+    # as unresolved, in addition to the well-known ones
+    # (``pytest_static.WELL_KNOWN_PLUGIN_FIXTURES``).
+    external_fixtures: frozenset[str] = frozenset()
+    # Consult the well-known plugin fixture table; every assumed name is
+    # reported in an ``external_fixture`` discovery note.
+    well_known_fixtures: bool = True
+    # pytest options the run adds after ``--``, read as if they were in
+    # ``addopts`` (``--doctest-modules`` collects doctests; options discovery
+    # cannot model make it incomplete).
+    runner_args: tuple[str, ...] = ()
+
+
+# Note kinds that mean the target list may be short of what the runner
+# collects. The others are conservative: an unknown fixture or an unparsed
+# file makes a target's dependencies wider, never the target list shorter.
+INCOMPLETE_NOTE_KINDS = frozenset(
+    {
+        "uncollected_test_class",
+        "imported_test_out_of_scope",
+        "unknown_base_class",
+        "plugin_collects_files",
+        # A file pytest collects that could not be parsed or named: whatever
+        # tests it holds are not targets.
+        "unparsed_file",
+        # A file pytest collects lies outside the source roots, so it was
+        # never read: its tests are not targets.
+        "test_file_outside_roots",
+        # A module or class attribute with a test's name bound to something
+        # discovery cannot follow (``TestMachine = Machine.TestCase``).
+        "unmodelled_test_binding",
+        # An option given to pytest after ``--`` that discovery cannot model.
+        "unmodelled_runner_option",
+        # Evidence mode: pytest collected tests at the recorded commit that
+        # were not targets there.
+        "collected_not_target",
+    }
+)
+
+
+@dataclass
+class DiscoveryResult:
+    runner: str
+    targets: list[Target] = field(default_factory=list)
+    notes: list[DiscoveryNote] = field(default_factory=list)
+    config: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def incomplete(self) -> list[DiscoveryNote]:
+        """Notes saying this runner may collect tests that are not targets."""
+        return [n for n in self.notes if n.kind in INCOMPLETE_NOTE_KINDS]
+
+
+def discover(
+    runner: str,
+    snapshot: Snapshot,
+    index: SourceIndex,
+    options: DiscoveryOptions | None = None,
+) -> DiscoveryResult:
+    options = options or DiscoveryOptions()
+    if runner == "pytest":
+        from diffcone.discovery.pytest_static import discover_pytest
+
+        return discover_pytest(snapshot, index, options)
+    if runner == "asv":
+        from diffcone.discovery.asv_static import discover_asv
+
+        return discover_asv(snapshot, index, options)
+    raise ValueError(f"unknown runner {runner!r}; expected one of {', '.join(RUNNERS)}")