crosshair-tool 0.0.99__cp312-cp312-macosx_10_13_x86_64.whl

crosshair/pathing_oracle.py

@@ -0,0 +1,271 @@
+import math
+from collections import defaultdict
+from typing import Counter, Dict, List, Optional, Sequence, Tuple
+
+from z3 import ExprRef  # type: ignore
+
+from crosshair.statespace import (
+    AbstractPathingOracle,
+    DetachedPathNode,
+    ModelValueNode,
+    NodeLike,
+    RootNode,
+    SearchTreeNode,
+    StateSpace,
+    WorstResultNode,
+)
+from crosshair.util import CrossHairInternal, debug, in_debug
+from crosshair.z3util import z3And, z3Not, z3Or
+
+CodeLoc = Tuple[str, ...]
+
+
+class CoveragePathingOracle(AbstractPathingOracle):
+    """
+    A heuristic that attempts to target under-explored code locations.
+
+    Code condition counts:
+        {code pos: {condition => count}}
+        Conditions should be
+            a count of conditions
+            that lead to the code location
+            on some previously explored path
+
+    When beginning an iteration:
+        Pick a code location to target, biasing for those with few visits.
+        Bias our decisions based on piror ones that led to the target location.
+
+    Risks:
+        *   Coupled decisions aren't understood, e.g. "a xor b" is challenging with underexplored
+            leaves in both branches.
+        *   We may target code locations that are impossible to reach because we've exhausted
+            every path that leads to them. (TODO: visit frequency may not be the only appropriate
+            metric for selecting target locations)
+        *   Biases for now-impossible branches "bleed" over into our path.
+            This sounds like a problem, but is at least partly intentional - we may hope to reach
+            some of the same code locations under different early decisions.
+
+    """
+
+    def __init__(self):
+        self.visits = Counter[CodeLoc]()
+        self.iters_since_discovery = 0
+        self.summarized_positions: Dict[CodeLoc, Counter[int]] = defaultdict(Counter)
+        self.current_path_probabilities: Dict[ExprRef, float] = {}
+        self.internalized_expressions: Tuple[Dict[ExprRef, int], Dict[int, int]] = (
+            {},
+            {},
+        )
+
+    # TODO: This falls apart for moderately sized with_equal_probabilities
+    # because that has many small probability decisions.
+    # (even just a 10% change could be much larger than it would be otherwise)
+    _delta_probabilities = {-1: 0.1, 0: 0.25, 1: 0.9}
+
+    def pre_path_hook(self, space: StateSpace) -> None:
+        root = space._root
+        visits = self.visits
+        _delta_probabilities = self._delta_probabilities
+
+        tweaks: Dict[ExprRef, int] = defaultdict(int)
+        rand = root._random
+        nondiscovery_iters = self.iters_since_discovery
+        summarized_positions = self.summarized_positions
+        num_positions = len(summarized_positions)
+        recent_discovery = rand.random() > nondiscovery_iters / (nondiscovery_iters + 3)
+        if recent_discovery or not num_positions:
+            debug("No coverage biasing in effect. (", num_positions, " code locations)")
+            self.current_path_probabilities = {}
+            return
+
+        options = list(summarized_positions.items())
+        options.sort(key=lambda pair: visits[pair[0]])
+        chosen_index = int((root._random.random() ** 2.5) * num_positions)
+        (loc, exprs) = options[chosen_index]
+        for expr in exprs.keys():
+            if expr >= 0:
+                tweaks[expr] += 1
+            else:
+                tweaks[-expr] -= 1
+        probabilities = {
+            expr: _delta_probabilities[delta] for expr, delta in tweaks.items()
+        }
+        if in_debug():
+            debug("Coverage biasing for code location:", loc)
+            debug("(", num_positions, " locations presently known)")
+            expr_id_map, _ = self.internalized_expressions
+            for expr, exprid in expr_id_map.items():
+                probability = probabilities.get(exprid)
+                if probability:
+                    debug("coverage tweaked probability", expr, probability)
+        self.current_path_probabilities = probabilities
+
+    def internalize(self, expr):
+        expr_id, id_id = self.internalized_expressions
+        myid = id(expr)
+        unified_id = id_id.get(myid)
+        if unified_id:
+            return unified_id
+        unified_id = expr_id.get(expr)
+        if unified_id:
+            id_id[myid] = unified_id
+            return unified_id
+        expr_id[expr] = myid
+        id_id[myid] = myid
+        return myid
+
+    def post_path_hook(self, path: Sequence[SearchTreeNode]) -> None:
+        leading_locs = []
+        leading_conditions: List[int] = []
+        for step, node in enumerate(path[:-1]):
+            if not isinstance(node, NodeLike):
+                continue
+            if isinstance(node, WorstResultNode):
+                key = node.stacktail
+                if (key not in leading_locs) and (not isinstance(node, ModelValueNode)):
+                    self.summarized_positions[key] += Counter(leading_conditions)
+                leading_locs.append(key)
+                next_node = path[step + 1]
+                if isinstance(next_node, DetachedPathNode):
+                    break
+                if step + 1 < len(path):
+                    (is_positive, root_expr) = node.normalized_expr
+                    expr_signature = (
+                        self.internalize(root_expr)
+                        if is_positive
+                        else -self.internalize(root_expr)
+                    )
+                    if next_node == node.positive:
+                        leading_conditions.append(expr_signature)
+                    elif next_node == node.negative:
+                        leading_conditions.append(-expr_signature)
+                    else:
+                        raise CrossHairInternal(
+                            f"{type(path[step])} was followed by {type(path[step+1])}"
+                        )
+        visits = self.visits
+        prev_len = len(visits)
+        visits += Counter(leading_locs)
+        if len(visits) > prev_len:
+            self.iters_since_discovery = 0
+        else:
+            self.iters_since_discovery += 1
+
+    def decide(
+        self,
+        root: RootNode,
+        node: "WorstResultNode",
+        engine_probability: Optional[float],
+    ) -> float:
+        if engine_probability in (0.0, 1.0):  # is not None:
+            return engine_probability
+        default_probability = 0.25
+
+        path_probabilities = self.current_path_probabilities
+        is_positive, n_expr = node.normalized_expr
+        n_expr_id = self.internalize(n_expr)
+        if n_expr_id not in path_probabilities:
+            return (
+                default_probability
+                if engine_probability is None
+                else engine_probability
+            )
+        true_probability = path_probabilities[n_expr_id]
+        return true_probability if is_positive else 1.0 - true_probability
+
+
+class BreadthFirstPathingOracle(AbstractPathingOracle):
+    def decide(
+        self,
+        root: RootNode,
+        node: "WorstResultNode",
+        engine_probability: Optional[float],
+    ) -> float:
+        branch_counter = root._open_coverage[node.stacktail]
+
+        # If we've never taken a branch at this code location, make sure we try it!
+        if bool(branch_counter.pos_ct) != bool(branch_counter.neg_ct):
+            if engine_probability != 0.0 and engine_probability != 1.0:
+                return 1.0 if branch_counter.neg_ct else 0.0
+        if engine_probability is None:
+            engine_probability = 0.25
+        if engine_probability != 0.0 and engine_probability != 1.0:
+            if branch_counter.pos_ct > branch_counter.neg_ct * 2 + 1:
+                engine_probability /= 2.0
+            elif branch_counter.neg_ct > branch_counter.pos_ct * 2 + 1:
+                engine_probability = (1.0 + engine_probability) / 2.0
+        return engine_probability
+
+
+class PreferNegativeOracle(AbstractPathingOracle):
+    def decide(
+        self,
+        root: RootNode,
+        node: "WorstResultNode",
+        engine_probability: Optional[float],
+    ) -> float:
+        # When both paths are unexplored, we bias for False.
+        # As a heuristic, this tends to prefer early completion:
+        # - Loop conditions tend to repeat on True.
+        # - Optional[X] turns into Union[X, None] and False conditions
+        #   biases for the last item in the union.
+        # We pick a False value more than 2/3rds of the time to avoid
+        # explosions while constructing binary-tree-like objects.
+        if engine_probability is not None:
+            return engine_probability
+        return 0.25
+
+
+class ConstrainedOracle(AbstractPathingOracle):
+    """
+    A pathing oracle that prefers to take a path that satisfies
+    explicitly provided constraints.
+    """
+
+    def __init__(self, inner_oracle: AbstractPathingOracle):
+        self.inner_oracle = inner_oracle
+        self.exprs: List[ExprRef] = []
+
+    def prefer(self, expr: ExprRef):
+        self.exprs.append(expr)
+
+    def pre_path_hook(self, space: StateSpace) -> None:
+        self.space = space
+        self.exprs = []
+        self.inner_oracle.pre_path_hook(space)
+
+    def post_path_hook(self, path: Sequence["SearchTreeNode"]) -> None:
+        self.inner_oracle.post_path_hook(path)
+
+    def decide(
+        self, root, node: "WorstResultNode", engine_probability: Optional[float]
+    ) -> float:
+        # We always run the inner oracle in case it's tracking something about the path.
+        default_probability = self.inner_oracle.decide(root, node, engine_probability)
+        if not self.space.is_possible(z3And(*[node.expr, *self.exprs])):
+            return 0.0
+        elif not self.space.is_possible(z3And(*[z3Not(node.expr), *self.exprs])):
+            return 1.0
+        else:
+            return default_probability
+
+
+class RotatingOracle(AbstractPathingOracle):
+    def __init__(self, oracles: List[AbstractPathingOracle]):
+        self.oracles = oracles
+        self.index = -1
+
+    def pre_path_hook(self, space: StateSpace) -> None:
+        oracles = self.oracles
+        self.index = (self.index + 1) % len(oracles)
+        for oracle in oracles:
+            oracle.pre_path_hook(space)
+
+    def post_path_hook(self, path: Sequence["SearchTreeNode"]) -> None:
+        for oracle in self.oracles:
+            oracle.post_path_hook(path)
+
+    def decide(
+        self, root, node: "WorstResultNode", engine_probability: Optional[float]
+    ) -> float:
+        return self.oracles[self.index].decide(root, node, engine_probability)

crosshair/pathing_oracle_test.py

@@ -0,0 +1,21 @@
+import random
+
+import z3  # type: ignore
+
+from crosshair.pathing_oracle import ConstrainedOracle, PreferNegativeOracle
+from crosshair.statespace import RootNode, SimpleStateSpace, WorstResultNode
+
+
+def test_constrained_oracle():
+    oracle = ConstrainedOracle(PreferNegativeOracle())
+    x = z3.Int("x")
+    root = RootNode()
+    space = SimpleStateSpace()
+    oracle.pre_path_hook(space)
+    oracle.prefer(x >= 7)
+    rand = random.Random()
+    assert oracle.decide(root, WorstResultNode(rand, x < 7, space.solver), None) == 0.0
+    assert oracle.decide(root, WorstResultNode(rand, x >= 3, space.solver), None) == 1.0
+    assert (
+        oracle.decide(root, WorstResultNode(rand, x == 7, space.solver), None) == 0.25
+    )

crosshair/pure_importer.py

@@ -0,0 +1,27 @@
+import sys
+from contextlib import contextmanager
+from dataclasses import dataclass
+from importlib.machinery import FileFinder
+from typing import Any, Callable
+
+
+@dataclass
+class PreferPureLoaderHook:
+    orig_hook: Callable[[str], Any]
+
+    def __call__(self, path: str):
+        finder = self.orig_hook(path)
+        if isinstance(finder, FileFinder):
+            # Move pure python file loaders to the front
+            finder._loaders.sort(key=lambda pair: 0 if pair[0] in (".py", ".pyc") else 1)  # type: ignore
+        return finder
+
+
+@contextmanager
+def prefer_pure_python_imports():
+    sys.path_hooks = [PreferPureLoaderHook(h) for h in sys.path_hooks]
+    sys.path_importer_cache.clear()
+    yield
+    assert all(isinstance(h, PreferPureLoaderHook) for h in sys.path_hooks)
+    sys.path_hooks = [h.orig_hook for h in sys.path_hooks]
+    sys.path_importer_cache.clear()

crosshair/pure_importer_test.py

@@ -0,0 +1,16 @@
+import importlib
+import sys
+from contextlib import contextmanager
+
+import pytest
+
+from crosshair.pure_importer import prefer_pure_python_imports
+
+
+@pytest.mark.skip(
+    reason="We used to test pydantic here, but current version doesn't use Cython"
+)
+def test_prefer_pure_python_imports():
+    with prefer_pure_python_imports():
+        pydantic = importlib.import_module("pydantic")
+        assert not pydantic.compiled

crosshair/register_contract.py

@@ -0,0 +1,273 @@
+"""API for registering contracts for external libraries."""
+
+from dataclasses import dataclass
+from inspect import Parameter, Signature, getmodule, ismethod, signature
+from types import MethodDescriptorType, ModuleType, WrapperDescriptorType
+from typing import Callable, Dict, FrozenSet, List, Optional, Set, Union
+from weakref import ReferenceType
+
+from crosshair.fnutil import resolve_signature
+from crosshair.stubs_parser import signature_from_stubs
+from crosshair.util import debug, warn
+
+# TODO: One might want to add more features to overloading. Currently contracts only
+# support multiple signatures, but not pre- and postconditions depending on the
+# overload. REGISTERED_CONTRACTS might become Dict[Callable, List[ContractOverride]].
+
+
+@dataclass
+class ContractOverride:
+    pre: Optional[Callable[..., bool]]
+    post: Optional[Callable[..., bool]]
+    sigs: List[Signature]
+    skip_body: bool
+    # TODO: Once supported, we might want to register Exceptions ("raises") as well
+
+
+REGISTERED_CONTRACTS: Dict[Callable, ContractOverride] = {}
+REGISTERED_MODULES: Set[ModuleType] = set()
+
+# Don't automatically register those functions.
+_NO_AUTO_REGISTER: FrozenSet[str] = frozenset(
+    {
+        "__init__",
+        "__init_subclass__",
+        "__new__",
+    }
+)
+
+
+def required_param_names(sig: Signature) -> Set[str]:
+    return {k for (k, v) in sig.parameters.items() if v.default is Parameter.empty}
+
+
+def _verify_signatures(
+    fn: Callable,
+    contract: ContractOverride,
+    ref_sig: Optional[Signature],
+) -> bool:
+    """Verify the provided signatures (including signatures of `pre` and `post`)."""
+    success = True
+    if ref_sig:
+        all_sigs = contract.sigs.copy()
+        all_sigs.append(ref_sig)
+    else:
+        all_sigs = contract.sigs
+    for sig in all_sigs:
+        params = set(sig.parameters.keys())
+        # First verify the parameters against the reference sig.
+        if ref_sig:
+            ref_params = set(ref_sig.parameters.keys())
+            # Cannot test for strict equality, because of overloads.
+            if not required_param_names(sig) <= ref_params:
+                warn(
+                    f"Malformed signature for function {fn.__name__}. "
+                    f"Expected parameters: {ref_params}, found: {params}",
+                )
+                success = False
+        # Verify the signature of the precondition.
+        if contract.pre:
+            pre_params = required_param_names(signature(contract.pre))
+            if not pre_params <= params:
+                warn(
+                    f"Malformated precondition for function {fn.__name__}. "
+                    f"Unexpected arguments: {pre_params - params}"
+                )
+                success = False
+        # Verify the signature of the postcondition.
+        if contract.post:
+            post_params = required_param_names(signature(contract.post))
+            params.add("__return__")
+            params.add("__old__")
+            if not post_params <= params:
+                warn(
+                    f"Malformated postcondition for function {fn.__name__}. "
+                    f"Unexpected parameters: {post_params - params}."
+                )
+                success = False
+    return success
+
+
+def _add_contract(
+    fn: Callable,
+    contract: ContractOverride,
+    ref_sig: Optional[Signature],
+) -> bool:
+    """Add a contract to the function and check for consistency."""
+    verified = _verify_signatures(fn, contract, ref_sig)
+    if not verified:
+        return False
+    old_contract = REGISTERED_CONTRACTS.get(fn)
+    if old_contract:
+        if (
+            old_contract.pre == contract.pre
+            and old_contract.post == contract.post
+            and old_contract.skip_body == contract.skip_body
+        ):
+            old_contract.sigs.extend(contract.sigs)
+        else:
+            warn(
+                "Pre- and postconditons and skip_body should not differ when "
+                f"registering multiple contracts for the same function: {fn.__name__}."
+            )
+            return False
+    else:
+        REGISTERED_CONTRACTS[fn] = contract
+    return True
+
+
+def _internal_register_contract(
+    fn: Callable,
+    pre: Optional[Callable[..., bool]] = None,
+    post: Optional[Callable[..., bool]] = None,
+    sig: Union[Signature, List[Signature], None] = None,
+    skip_body: bool = True,
+) -> bool:
+    reference_sig = None
+
+    sig_or_error = resolve_signature(fn)
+    if isinstance(sig_or_error, Signature):
+        reference_sig = sig_or_error
+
+    # In the case the signature is incomplete, look in the stubs.
+    if not sig and (
+        not reference_sig or reference_sig.return_annotation == Parameter.empty
+    ):
+        sigs, is_valid = signature_from_stubs(fn)
+        if sigs:
+            debug(f"Found {str(len(sigs))} signature(s) for {fn.__name__} in stubs")
+            if not is_valid or any(
+                sig.return_annotation == Parameter.empty for sig in sigs
+            ):
+                warn(
+                    f"Incomplete signature for {fn.__name__} in stubs, consider "
+                    f"registering the signature manually. Signatures found: "
+                    f"{str(sigs)}"
+                )
+            contract = ContractOverride(pre, post, sigs, skip_body)
+            return _add_contract(fn, contract, reference_sig)
+        else:
+            if reference_sig:
+                warn(
+                    f"No valid signature found for function {fn.__name__}, "
+                    "consider registering the signature manually."
+                )
+                contract = ContractOverride(pre, post, [], skip_body)
+                return _add_contract(fn, contract, reference_sig)
+            # No signature available at all, we cannot register the function.
+            else:
+                warn(
+                    f"Could not automatically register {fn.__name__}, reason: no "
+                    "signature found."
+                )
+                return False
+    else:
+        # Verify the contract and register it.
+        if sig is None:
+            sig = []
+        elif isinstance(sig, Signature):
+            sig = [sig]
+        contract = ContractOverride(pre, post, sig, skip_body)
+        return _add_contract(fn, contract, reference_sig)
+
+
+def register_contract(
+    fn: Callable,
+    *,
+    pre: Optional[Callable[..., bool]] = None,
+    post: Optional[Callable[..., bool]] = None,
+    sig: Union[Signature, List[Signature], None] = None,
+    skip_body: bool = True,
+) -> bool:
+    """
+    Register a contract for the given function.
+
+    :param fn: The function to add a contract for.
+    :param pre: The preconditon which should hold when entering the function.
+    :param post: The postcondition which should hold when returning from the function.
+    :param sig: If provided, CrossHair will use this signature for the function.\
+        Usefull for manually providing type annotation. You can provide multiple\
+        signatures for overloaded functions.
+    :param skip_body: By default registered functions will be skipped executing,\
+        assuming the postconditions hold. Set this to `False` to still execute the body.
+    :returns: A boolean indicating whether the contract was successfully registered.
+    """
+    # Don't allow registering bound methods.
+    if ismethod(fn):
+        cls = getattr(getattr(fn, "__self__", None), "__class__", "<not found>")
+        warn(
+            f"You registered the bound method {fn}. You should register the unbound "
+            f"function of the class {cls} instead."
+        )
+        return False
+    return _internal_register_contract(fn, pre, post, sig, skip_body)
+
+
+def clear_contract_registrations():
+    global REGISTERED_CONTRACTS
+    REGISTERED_CONTRACTS.clear()
+    global REGISTERED_MODULES
+    REGISTERED_MODULES.clear()
+
+
+def get_contract(fn: Callable) -> Optional[ContractOverride]:
+    """
+    Get the contract associated to the given function, it the function was registered.
+
+    :param fn: The function to retrieve the contract for.
+    :return: The contract associated with the function or None if the function was not\
+        registered.
+    """
+    # Weak references are not hashable: REGISTERED_CONTRACTS.get(fn) fails.
+    if isinstance(fn, ReferenceType):
+        return None
+    # Return the registered contract for the function, if any.
+    contract = REGISTERED_CONTRACTS.get(fn)
+    if contract:
+        return contract
+    fn_name = getattr(fn, "__name__", None)
+    # Some functions should not be automatically registered.
+    if fn_name in _NO_AUTO_REGISTER:
+        return None
+
+    # If the function belongs to a registered module, register it.
+    module = getmodule(fn)
+    # If this is a classmethod, look for the module in the mro.
+    fn_self = getattr(fn, "__self__", None)
+    if fn_name and fn_self and isinstance(fn_self, type):
+        for mro in fn_self.mro():
+            if fn_name in mro.__dict__:
+                module_name = mro.__module__
+                if module_name in map(lambda x: x.__name__, REGISTERED_MODULES):
+                    _internal_register_contract(fn)
+                    return REGISTERED_CONTRACTS.get(fn)
+                return None
+    if module and module in REGISTERED_MODULES:
+        _internal_register_contract(fn)
+        return REGISTERED_CONTRACTS.get(fn)
+    # Some builtins and some C functions are wrapped into Descriptors
+    if isinstance(fn, (MethodDescriptorType, WrapperDescriptorType)):
+        module_name = fn.__objclass__.__module__
+        if module_name in map(lambda x: x.__name__, REGISTERED_MODULES):
+            _internal_register_contract(fn)
+            return REGISTERED_CONTRACTS.get(fn)
+    return None
+
+
+def register_modules(*modules: ModuleType) -> None:
+    """
+    Specify a module whose functions should all be skipped at execution.
+
+    THIS IS AN EXPERIMENTAL FEATURE!
+    Registering a whole module might be too much in some cases and you might fallback to
+    register individual functions instead.
+
+    Note that functions `__init__`, `__init_subclass__` and `__new__` are never
+    registered automatically.
+
+    If you wish to register all functions, except function `foo`, register that function
+    manually with the option `skip_body=False`.
+
+    :param modules: one or multiple modules whose functions should be skipped.
+    """
+    REGISTERED_MODULES.update(modules)