diffgenome 0.1.0__py3-none-any.whl

diffgenome/runtime_evidence.py

@@ -0,0 +1,261 @@
+"""Runtime evidence about a change: the stable contract consumers depend on.
+
+`diffgenome-runtime/1` reports only facts the collectors observed while the repository's own
+tests ran against the change, plus the static decision sites needed to place branch outcomes on
+changed lines. No model and no genome are involved. A consumer (Sydes) reads this section of the
+change artifact; it never needs the trace files, the mechanics file or DiffGenome internals.
+
+Per changed function (a changed symbol whose definition is a function):
+  executed / not executed, number of calls, the exact tests (subtests included) that ran it,
+  exits observed (returned, returned-error, raised:<type>, ...), exceptions raised by calls made
+  inside it, distinct argument type shapes, its nearest observed callers, the stand-ins (mocks,
+  fakes) it reached, and the outcomes observed at every decision site on a changed line.
+Edges: observed caller -> callee pairs on the call chains that reached changed functions, with
+  closures, lambdas and decorator wrappers looked through, each end located (file, line).
+Boundaries: where observation stopped (external, unresolved stand-in).
+Gaps: changed functions no test executed, changed-line decision outcomes never observed, and
+  stand-ins reached directly from changed code. Coverage is never inferred: only these
+  observable kinds are reported.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from collections.abc import Iterable
+from typing import Any
+
+from diffgenome.change import ChangeSet
+from diffgenome.model import CallNode, Execution, SubstitutionNode
+from diffgenome.runtime import SymbolIndex
+
+FORMAT = "diffgenome-runtime/1"
+MAX_TESTS = 200
+MAX_SHAPES = 5
+MAX_CALLERS = 12
+MAX_EDGE_TESTS = 5
+_WRAPPER_MARKERS = ("<locals>", "<lambda>", "<anon>")
+
+
+def _is_wrapper(symbol: str) -> bool:
+    return any(m in symbol for m in _WRAPPER_MARKERS)
+
+
+def _changed_functions(change: ChangeSet, index: SymbolIndex) -> dict[str, dict[str, Any]]:
+    out: dict[str, dict[str, Any]] = {}
+    for s in change.symbols:
+        d = index.find(s)
+        # application code only: changed tests (and closures inside them) are stimuli, not
+        # behavior under change
+        if d is not None and d.kind == "function" and not index.is_test(s):
+            out[s] = {"file": d.path, "line": d.start, "end": d.end}
+    return out
+
+
+def _changed_lines(change: ChangeSet) -> dict[str, set[int]]:
+    lines: dict[str, set[int]] = defaultdict(set)
+    for r in change.ranges:
+        lines[r.path].update(r.lines)
+    return lines
+
+
+def build_runtime_evidence(
+    executions: Iterable[Execution],
+    change: ChangeSet,
+    index: SymbolIndex,
+    mechanics_functions: list[dict[str, Any]] | None = None,
+    boundaries: list[dict[str, Any]] | None = None,
+    test_scope: str | None = None,
+) -> dict[str, Any]:
+    """`test_scope` names what was run (e.g. a test directory or package): every "not
+    executed" statement is relative to it."""
+    execs = list(executions)
+    changed = _changed_functions(change, index)
+    lines = _changed_lines(change)
+    mech = {f["symbol"]: f for f in mechanics_functions or []}
+
+    calls: Counter[str] = Counter()
+    tests: dict[str, set[str]] = defaultdict(set)
+    exits: dict[str, Counter[str]] = defaultdict(Counter)
+    raised_inside: dict[str, Counter[str]] = defaultdict(Counter)
+    shapes: dict[str, Counter[tuple[tuple[str, str], ...]]] = defaultdict(Counter)
+    callers: dict[str, Counter[str]] = defaultdict(Counter)
+    caller_tests: dict[tuple[str, str], set[str]] = defaultdict(set)
+    stand_ins: dict[str, Counter[str]] = defaultdict(Counter)
+    site_out: dict[str, Counter[bool]] = defaultdict(Counter)
+    edges: dict[tuple[str, str], set[str]] = defaultdict(set)
+    edge_count: Counter[tuple[str, str]] = Counter()
+    locations: dict[str, tuple[str, int] | None] = {}
+    origins: dict[str, str] = {}
+    universe = []
+
+    for ex in execs:
+        universe.append(ex.stimulus_ref)
+        for symbol_rec in ex.symbols:
+            origins.setdefault(symbol_rec.id, symbol_rec.origin.value)
+            if symbol_rec.location is not None:
+                locations.setdefault(
+                    symbol_rec.id, (symbol_rec.location.path, symbol_rec.location.line)
+                )
+        nodes = {n.id: n for n in ex.nodes}
+
+        def real_parent(n: Any, nodes: dict[int, Any] = nodes) -> CallNode | None:
+            p = nodes.get(n.parent) if n.parent is not None else None
+            while isinstance(p, CallNode) and _is_wrapper(p.symbol):
+                p = nodes.get(p.parent) if p.parent is not None else None
+            return p if isinstance(p, CallNode) else None
+
+        for n in ex.nodes:
+            if isinstance(n, SubstitutionNode):
+                p = real_parent(n)
+                if p is not None and p.symbol in changed:
+                    target = n.claimed_target or n.substitute or "?"
+                    stand_ins[p.symbol][str(target)] += 1
+                continue
+            if not isinstance(n, CallNode):
+                continue
+            p = real_parent(n)
+            if (
+                p is not None
+                and p.symbol in changed
+                and str(n.outcome).startswith(("raised", "panic", "returned-error"))
+            ):
+                raised_inside[p.symbol][str(n.outcome)] += 1
+            if n.symbol not in changed:
+                continue
+            calls[n.symbol] += 1
+            tests[n.symbol].add(ex.stimulus_ref)
+            exits[n.symbol][str(n.outcome)] += 1
+            shapes[n.symbol][tuple((a[0], a[1]) for a in n.args)] += 1
+            if p is not None:
+                callers[n.symbol][p.symbol] += 1
+                caller_tests[(n.symbol, p.symbol)].add(ex.stimulus_ref)
+            # the observed chain into this changed call, wrappers looked through
+            child: Any = n
+            while True:
+                parent = real_parent(child)
+                if parent is None:
+                    break
+                key = (parent.symbol, child.symbol)
+                if key[0] != key[1]:
+                    edges[key].add(ex.stimulus_ref)
+                    edge_count[key] += 1
+                child = parent
+        for b in ex.branches:
+            site_out[b.site][b.outcome] += 1
+
+    outcomes = {ex.stimulus_ref: ex.outcome for ex in execs}
+
+    def loc(symbol: str) -> dict[str, Any]:
+        """Where a symbol is defined, and its origin (repo, test, ...) as observed."""
+        where = locations.get(symbol)
+        d = index.find(symbol)
+        origin = "test" if index.is_test(symbol) else origins.get(symbol, "unknown")
+        if d is not None:
+            return {"symbol": symbol, "file": d.path, "line": d.start, "origin": origin}
+        return {
+            "symbol": symbol,
+            "file": where[0] if where else None,
+            "line": where[1] if where else None,
+            "origin": origin,
+        }
+
+    functions = []
+    gaps: list[dict[str, Any]] = []
+    for sym, info in sorted(changed.items()):
+        f = mech.get(sym)
+        cl = lines.get(info["file"], set())
+        sites = [
+            {
+                "site": s["site"],
+                "line": s["line"],
+                "predicate": s["pred"],
+                "true": site_out[s["site"]].get(True, 0),
+                "false": site_out[s["site"]].get(False, 0),
+            }
+            for s in (f["sites"] if f else [])
+            if s["line"] in cl
+        ]
+        executed = calls[sym] > 0
+        functions.append(
+            {
+                **loc(sym),
+                "executed": executed,
+                "calls": calls[sym],
+                "tests": sorted(tests[sym])[:MAX_TESTS],
+                "tests_total": len(tests[sym]),
+                "exits": dict(exits[sym]),
+                "raised_inside": dict(raised_inside[sym]),
+                "arg_shapes": [
+                    [list(a) for a in shape] for shape, _ in shapes[sym].most_common(MAX_SHAPES)
+                ],
+                "callers": [
+                    {**loc(c), "calls": k, "tests": len(caller_tests[(sym, c)])}
+                    for c, k in callers[sym].most_common(MAX_CALLERS)
+                ],
+                "stand_ins": dict(stand_ins[sym]),
+                "changed_sites": sites,
+            }
+        )
+        if not executed:
+            gaps.append({"kind": "function_not_executed", **loc(sym)})
+            continue
+        for s in sites:
+            missing = [o for o, k in (("true", s["true"]), ("false", s["false"])) if k == 0]
+            if len(missing) == 2:
+                gaps.append(
+                    {
+                        "kind": "branch_not_evaluated",
+                        **loc(sym),
+                        "line": s["line"],
+                        "predicate": s["predicate"],
+                    }
+                )
+            elif missing:
+                gaps.append(
+                    {
+                        "kind": "branch_outcome_not_observed",
+                        **loc(sym),
+                        "line": s["line"],
+                        "predicate": s["predicate"],
+                        "outcome": missing[0],
+                    }
+                )
+        for target, k in stand_ins[sym].items():
+            gaps.append({"kind": "stand_in_reached", **loc(sym), "target": target, "calls": k})
+
+    return {
+        "format": FORMAT,
+        "universe": {
+            "test_scope": test_scope,
+            "executions": len(universe),
+            "passed": sum(1 for o in outcomes.values() if o == "passed"),
+            "failed": sum(1 for o in outcomes.values() if o != "passed"),
+            "tests": [{"id": t, "outcome": outcomes[t]} for t in sorted(outcomes)][:2000],
+        },
+        "changed_functions": functions,
+        "edges": [
+            {
+                "caller": loc(a),
+                "callee": loc(b),
+                "executions": edge_count[(a, b)],
+                "tests": sorted(edges[(a, b)])[:MAX_EDGE_TESTS],
+                "tests_total": len(edges[(a, b)]),
+            }
+            for (a, b) in sorted(edges)
+        ],
+        "boundaries": [
+            {
+                "kind": b.get("kind"),
+                "caller": b.get("caller"),
+                "target": b.get("target"),
+                "tests": len(b.get("executions") or []),
+            }
+            for b in boundaries or []
+        ],
+        "gaps": gaps,
+        "not_reported": [
+            "values (only type shapes and opaque fingerprints are recorded)",
+            "except-handler coverage (handlers are not decision sites)",
+            "per-line coverage",
+        ],
+    }

diffgenome/sandbox.py

@@ -0,0 +1,166 @@
+"""Disposable workspace and confined execution for untrusted target code and probes.
+
+The target repository is copied (never mounted writable) into a workspace; commands run
+with a scrubbed environment, resource limits, and, where the host supports it, an OS
+sandbox that denies network access and writes outside the workspace. On macOS that is
+`sandbox-exec` (Seatbelt); on Linux a container/namespace runner belongs here later. If no
+OS sandbox is available the runner refuses to execute rather than run unconfined.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_IGNORE = shutil.ignore_patterns(
+    ".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache", ".mypy_cache",
+    ".ruff_cache", ".diffgenome", "*.pyc",
+)  # fmt: skip
+
+
+@dataclass
+class RunResult:
+    returncode: int
+    stdout: str
+    stderr: str
+    seconds: float
+    confined: bool
+
+
+@dataclass
+class Workspace:
+    root: Path  # disposable directory owned by diffgenome
+    repo: Path  # copy of the target inside root
+    home: Path
+    tmp: Path
+    extra_read_paths: list[Path] = field(default_factory=list)  # e.g. the target's interpreter
+
+    @classmethod
+    def create(
+        cls,
+        target_repo: Path,
+        base: Path,
+        extra_read_paths: list[Path] | None = None,
+        rev: str | None = None,
+    ) -> Workspace:
+        root = base / f"ws-{int(time.time() * 1000)}"
+        repo = root / "repo"
+        if rev:
+            # A specific revision without touching the checkout: `git archive` into the copy.
+            repo.mkdir(parents=True)
+            archive = subprocess.run(
+                ["git", "archive", "--format=tar", rev],
+                cwd=target_repo,
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(["tar", "-x", "-C", str(repo)], input=archive.stdout, check=True)
+        else:
+            shutil.copytree(target_repo, repo, ignore=_IGNORE, symlinks=False)
+        home, tmp = root / "home", root / "tmp"
+        home.mkdir()
+        tmp.mkdir()
+        return cls(root, repo, home, tmp, list(extra_read_paths or []))
+
+    def destroy(self) -> None:
+        shutil.rmtree(self.root, ignore_errors=True)
+
+    # ------------------------------------------------------------------ confinement
+
+    def _seatbelt_profile(self, allow_loopback: bool = False) -> str:
+        ws = str(self.root.resolve())
+        loopback = (
+            '(allow network-bind (local ip "localhost:*"))\n'
+            '(allow network-inbound (local ip "localhost:*"))\n'
+            '(allow network-outbound (remote ip "localhost:*"))\n'
+            if allow_loopback
+            else ""
+        )
+        return f"""(version 1)
+(deny default)
+(allow process-fork)
+(allow process-exec)
+(allow signal (target self))
+(allow sysctl-read)
+(allow mach-lookup)
+(allow ipc-posix-shm*)
+(allow file-read*)
+(allow file-write* (subpath "{ws}"))
+(allow file-write* (literal "/dev/null") (literal "/dev/dtracehelper") (regex #"^/dev/tty"))
+(deny network*)
+{loopback}"""
+
+    def command(
+        self,
+        argv: list[str],
+        cpu_seconds: int = 600,
+        max_procs: int = 4096,  # macOS counts the whole user; 256 broke Jest's `find` spawn
+        allow_loopback: bool = False,
+    ) -> list[str] | None:
+        """Wrap argv for confined execution, or None if the host has no supported sandbox.
+        `allow_loopback` permits localhost sockets only (in-process test servers); every
+        other network access stays denied."""
+        limits = f'ulimit -t {cpu_seconds}; ulimit -u {max_procs}; ulimit -f 1048576; exec "$@"'
+        inner = ["/bin/sh", "-c", limits, "sh", *argv]
+        if platform.system() == "Darwin" and shutil.which("sandbox-exec"):
+            return ["/usr/bin/sandbox-exec", "-p", self._seatbelt_profile(allow_loopback), *inner]
+        return None
+
+    def environment(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        """No inherited variables: no credentials, no proxies, no shell state."""
+        env = {
+            "PATH": "/usr/bin:/bin",
+            "HOME": str(self.home),
+            "TMPDIR": str(self.tmp),
+            "PYTHONDONTWRITEBYTECODE": "1",
+            "PYTHONNOUSERSITE": "1",
+            "MPLCONFIGDIR": str(self.tmp),
+            "LANG": "C.UTF-8",
+        }
+        env.update(extra or {})
+        return env
+
+    def run(
+        self,
+        argv: list[str],
+        cwd: Path | None = None,
+        env: dict[str, str] | None = None,
+        timeout: int = 900,
+        allow_loopback: bool = False,
+    ) -> RunResult:
+        wrapped = self.command(argv, allow_loopback=allow_loopback)
+        if wrapped is None:
+            raise RuntimeError("no OS sandbox available on this host; refusing to run unconfined")
+        start = time.monotonic()
+        try:
+            proc = subprocess.run(
+                wrapped,
+                cwd=cwd or self.repo,
+                env=self.environment(env),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                stdin=subprocess.DEVNULL,
+            )
+            return RunResult(
+                proc.returncode, proc.stdout, proc.stderr, time.monotonic() - start, True
+            )
+        except subprocess.TimeoutExpired as exc:
+            out = exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+            err = exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or "")
+            return RunResult(
+                -1, out, err + f"\ntimeout after {timeout}s", time.monotonic() - start, True
+            )
+
+
+def host_supports_confinement() -> bool:
+    return (
+        platform.system() == "Darwin"
+        and shutil.which("sandbox-exec") is not None
+        and os.access("/usr/bin/sandbox-exec", os.X_OK)
+    )

diffgenome/serialize.py

@@ -0,0 +1,96 @@
+"""JSON encoding of the event protocol. One `Execution` per document; deterministic output."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from enum import Enum
+from typing import Any
+
+from diffgenome.model import (
+    BranchObs,
+    CallNode,
+    Collector,
+    Execution,
+    Fidelity,
+    Node,
+    Origin,
+    OsEventKind,
+    OsEventNode,
+    Plane,
+    SourceLocation,
+    Stimulus,
+    SubstitutionMechanism,
+    SubstitutionNode,
+    Symbol,
+)
+
+_NODE_TYPES: dict[str, type[Node]] = {
+    "call": CallNode,
+    "substitution": SubstitutionNode,
+    "os_event": OsEventNode,
+}
+_TYPE_NAMES: dict[type, str] = {cls: name for name, cls in _NODE_TYPES.items()}
+
+
+def _encode(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        out = {f.name: _encode(getattr(value, f.name)) for f in dataclasses.fields(value)}
+        node_type = _TYPE_NAMES.get(type(value))
+        return {"type": node_type, **out} if node_type else out
+    if isinstance(value, tuple | list):
+        return [_encode(v) for v in value]
+    return value
+
+
+def execution_to_json(execution: Execution) -> str:
+    return json.dumps(_encode(execution), indent=1, sort_keys=False) + "\n"
+
+
+def _node_from_dict(d: dict[str, Any]) -> Node:
+    d = dict(d)
+    cls = _NODE_TYPES[d.pop("type")]
+    if "args" in d:
+        d["args"] = tuple((n, sh, dg) for n, sh, dg in d["args"])
+    if "state" in d:
+        d["state"] = tuple((n, b, dg) for n, b, dg in d["state"])
+    if "state_after" in d:
+        d["state_after"] = tuple((n, b, dg) for n, b, dg in d["state_after"])
+    if cls is SubstitutionNode:
+        d["mechanism"] = SubstitutionMechanism(d["mechanism"])
+        d["path"] = tuple(d["path"])
+    elif cls is OsEventNode:
+        d["kind"] = OsEventKind(d["kind"])
+    return cls(**d)
+
+
+def execution_from_json(text: str) -> Execution:
+    d = json.loads(text)
+    return Execution(
+        id=d["id"],
+        stimulus=Stimulus(d["stimulus"]),
+        stimulus_ref=d["stimulus_ref"],
+        outcome=d["outcome"],
+        revision=d["revision"],
+        collectors=tuple(
+            Collector(c["name"], Plane(c["plane"]), Fidelity(c["fidelity"]))
+            for c in d["collectors"]
+        ),
+        symbols=tuple(
+            Symbol(
+                s["id"],
+                Origin(s["origin"]),
+                SourceLocation(**s["location"]) if s["location"] else None,
+                s.get("kind", "callable"),
+            )
+            for s in d["symbols"]
+        ),
+        nodes=tuple(_node_from_dict(n) for n in d["nodes"]),
+        diagnostics=tuple((k, v) for k, v in d.get("diagnostics", [])),
+        branches=tuple(
+            BranchObs(b["site"], bool(b["outcome"]), int(b["node"]), int(b["seq"]))
+            for b in d.get("branches") or []
+        ),
+    )

diffgenome/sites.py

@@ -0,0 +1,19 @@
+"""Stable identity of decision (branch) sites.
+
+A site is identified by the repository-relative file and the span of its condition in
+the ORIGINAL source: 1-based line and 1-based byte column of the first character, and
+1-based line and 1-based byte column just past the last character. Every runtime
+(instrumenter or monitor) and every static front end computes the id from the original
+source independently, so instrumentation that rewrites code cannot change it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+Span = tuple[int, int, int, int]  # start line, start col, end line, end col (exclusive)
+
+
+def site_id(rel_path: str, span: Span) -> str:
+    l1, c1, l2, c2 = span
+    return "br:" + hashlib.sha256(f"{rel_path}:{l1}:{c1}:{l2}:{c2}".encode()).hexdigest()[:12]

diffgenome/static_types.py

@@ -0,0 +1,69 @@
+"""Static return-type resolution for `factory().member` stand-ins.
+
+A stand-in whose path crosses a return value (``get_manager.().ensure_backend``) claims the
+factory; what the factory returns was never observed. When the source declares the return
+type unambiguously, the member on that type is the claim, entered with relation
+``static-return-type`` so the resolver reports the rule and the evidence says so. Static
+evidence, never observed; the composer still needs a real fragment to continue.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from diffgenome.model import Execution, Origin, SubstitutionNode, Symbol
+from diffgenome.runtime import SymbolIndex
+
+
+def apply_static_return_types(
+    executions: list[Execution], index: SymbolIndex
+) -> tuple[list[Execution], int]:
+    resolved = 0
+    out: list[Execution] = []
+    cache: dict[str, str | None] = {}
+    for ex in executions:
+        symbols = dict((s.id, s) for s in ex.symbols)
+        nodes = list(ex.nodes)
+        changed = False
+        for i, n in enumerate(nodes):
+            if (
+                not isinstance(n, SubstitutionNode)
+                or n.claimed_target is None
+                or "()" not in n.path
+            ):
+                continue
+            # path: (factory, "()", member, ...) — only one hop through a return value
+            try:
+                k = n.path.index("()")
+            except ValueError:
+                continue
+            if k + 1 >= len(n.path) or "()" in n.path[k + 1 :]:
+                continue
+            member = n.path[k + 1]
+            if n.claimed_target not in cache:
+                cache[n.claimed_target] = index.return_type_of(n.claimed_target)
+            cls = cache[n.claimed_target]
+            if cls is None:
+                continue
+            target = f"{cls}.{member}"
+            d = index.find(target)
+            if d is None:
+                continue
+            nodes[i] = dataclasses.replace(
+                n,
+                claimed_target=target,
+                relation=f"static-return-type;{n.relation}",
+                path=n.path[k + 1 :],
+            )
+            if target not in symbols:
+                symbols[target] = Symbol(target, Origin.REPO, None)
+            resolved += 1
+            changed = True
+        out.append(
+            dataclasses.replace(
+                ex, nodes=tuple(nodes), symbols=tuple(symbols[k] for k in sorted(symbols))
+            )
+            if changed
+            else ex
+        )
+    return out, resolved