coltrace 0.1.0.dev4__py3-none-any.whl

coltrace/callbacks.py

@@ -0,0 +1,579 @@
+"""Bounded value-dependency summaries for explicitly resolved scalar callbacks.
+
+This module inspects syntax only. Text and regex methods are an *inferred*
+scalar-text contract, not a proof about arbitrary Python objects or monkey
+patching. Calls outside that contract are rejected. Callers must supply resolved
+import names in ``symbols``; spelling a global ``re`` does not establish its API.
+General control flow is rejected. A constant isinstance fallback is accepted
+only when every returned component also has an explicit input value dependency;
+otherwise omitting the condition could hide an actual dependency.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+from .lineage_models import Completeness, Confidence
+
+
+@dataclass(frozen=True)
+class CallbackComponent:
+    depends_on_input: bool
+    completeness: Completeness = "complete"
+    evidence: Confidence = "confirmed"
+    steps: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class CallbackStep:
+    """A callback step with a semantic display role, separate from column edges."""
+
+    id: str
+    line: int
+    column: int
+    end_line: int | None
+    end_column: int | None
+    label: str
+    expression: str
+    parents: tuple[str, ...] = ()
+    depends_on_input: bool = False
+    role: Literal["value", "control", "configuration", "context"] = "value"
+
+
+@dataclass(frozen=True)
+class CallbackSummary:
+    components: tuple[CallbackComponent, ...] | None
+    supported: bool
+    may_mutate: bool
+    reason: str
+    steps: tuple[CallbackStep, ...] = ()
+
+
+@dataclass(frozen=True)
+class _HistoryValue:
+    parents: tuple[str, ...] = ()
+    direct: bool = False
+    items: tuple[_HistoryValue, ...] | None = None
+    depends: bool = False
+    known: bool = False
+
+
+class _CallbackHistory:
+    """Record references and semantic roles after the bounded summary accepts it.
+
+    Control parents describe why a step may run. They do not turn a known,
+    input-independent preparation into a value transformation.
+    """
+
+    def __init__(self, parameter: str, symbols: Mapping[str, str], local_names: set[str]) -> None:
+        self.parameter = parameter
+        self.env: dict[str, _HistoryValue] = {
+            parameter: _HistoryValue(direct=True, depends=True, known=True)
+        }
+        self.semantic = _Summarizer(parameter, symbols)
+        self.semantic.local_names.update(local_names)
+        self.steps: list[CallbackStep] = []
+        self.guards: tuple[str, ...] = ()
+
+    def _references(self, node: ast.AST) -> _HistoryValue:
+        if isinstance(node, ast.Name):
+            return self.env.get(node.id, _HistoryValue())
+        if isinstance(node, ast.Subscript):
+            value = self._references(node.value)
+            if value.items is not None and isinstance(node.slice, ast.Constant):
+                index = node.slice.value
+                if type(index) is int and -len(value.items) <= index < len(value.items):
+                    return value.items[index]
+        children = tuple(self._references(child) for child in ast.iter_child_nodes(node))
+        return _HistoryValue(
+            tuple(dict.fromkeys(parent for child in children for parent in child.parents)),
+            any(child.direct for child in children),
+            tuple(self._references(item) for item in node.elts)
+            if isinstance(node, ast.Tuple)
+            else None,
+        )
+
+    def _semantic_value(self, value: _HistoryValue, semantic: _Value) -> _HistoryValue:
+        items = (
+            tuple(
+                self._semantic_value(item, component)
+                for item, component in zip(value.items, semantic.items, strict=True)
+            )
+            if value.items is not None and semantic.kind == "tuple"
+            else value.items
+        )
+        return _HistoryValue(
+            value.parents,
+            value.direct,
+            items,
+            semantic.depends,
+            semantic.completeness == "complete" and semantic.evidence != "unresolved",
+        )
+
+    def expression(self, node: ast.AST) -> _HistoryValue:
+        return self._semantic_value(self._references(node), self.semantic.expression(node))
+
+    def record(
+        self,
+        node: ast.AST,
+        label: str,
+        value: _HistoryValue,
+        *,
+        role: Literal["value", "control", "configuration", "context"] | None = None,
+    ) -> _HistoryValue:
+        line, column = getattr(node, "lineno", 1), getattr(node, "col_offset", 0)
+        identifier = f"callback:{line}:{column}:{len(self.steps)}"
+        self.steps.append(
+            CallbackStep(
+                identifier,
+                line,
+                column,
+                getattr(node, "end_lineno", None),
+                getattr(node, "end_col_offset", None),
+                label,
+                ast.unparse(node),
+                tuple(dict.fromkeys(self.guards + value.parents)),
+                value.direct,
+                role
+                or ("value" if value.depends else "configuration" if value.known else "context"),
+            )
+        )
+        return _HistoryValue(
+            (identifier,), items=value.items, depends=value.depends, known=value.known
+        )
+
+    def assign(self, target: ast.AST, value: _HistoryValue, expression: ast.AST) -> None:
+        if isinstance(target, ast.Name):
+            if value.items is not None:
+                parts = tuple(
+                    self.record(
+                        expression.elts[index] if isinstance(expression, ast.Tuple) else expression,
+                        f"{target.id}[{index}] = tuple component {index + 1}",
+                        item,
+                    )
+                    for index, item in enumerate(value.items)
+                )
+                self.env[target.id] = _HistoryValue(
+                    tuple(parent for part in parts for parent in part.parents),
+                    items=parts,
+                    depends=any(part.depends for part in parts),
+                    known=all(part.known for part in parts),
+                )
+                return
+            self.env[target.id] = self.record(
+                expression, f"{target.id} = {ast.unparse(expression)}", value
+            )
+        elif isinstance(target, (ast.Tuple, ast.List)) and value.items is not None:
+            for item, component in zip(target.elts, value.items, strict=True):
+                self.assign(item, component, expression)
+
+    def body(self, statements: list[ast.stmt]) -> tuple[tuple[str, ...], ...]:
+        for statement in statements:
+            if isinstance(statement, ast.Assign):
+                semantic = self.semantic.expression(statement.value)
+                value = self.expression(statement.value)
+                for target in statement.targets:
+                    self.assign(target, value, statement.value)
+                    self.semantic.assign(target, semantic)
+            elif isinstance(statement, ast.AnnAssign) and statement.value is not None:
+                self.assign(statement.target, self.expression(statement.value), statement.value)
+                self.semantic.assign(statement.target, self.semantic.expression(statement.value))
+            elif isinstance(statement, ast.If):
+                # The semantic summary already proved this exact type guard.
+                # Its dependency controls execution rather than transforming values.
+                guard = self.record(
+                    statement,
+                    "Type guard; non-string input returns fallback constants",
+                    self._references(statement.test),
+                    role="control",
+                )
+                self.guards += guard.parents
+                self.semantic.env[self.parameter] = _Value(depends=True, kind="string")
+            elif isinstance(statement, ast.Return):
+                if statement.value is None:
+                    return (
+                        self.record(
+                            statement, "Return None", _HistoryValue(known=True), role="value"
+                        ).parents,
+                    )
+                value = self.expression(statement.value)
+                parts = value.items if value.items is not None else (value,)
+                expressions = (
+                    statement.value.elts
+                    if isinstance(statement.value, ast.Tuple)
+                    else [statement.value] * len(parts)
+                )
+                return tuple(
+                    self.record(
+                        expression, f"Return component {index + 1}", part, role="value"
+                    ).parents
+                    for index, (part, expression) in enumerate(zip(parts, expressions, strict=True))
+                )
+        return ()
+
+
+@dataclass(frozen=True)
+class _Value:
+    depends: bool = False
+    completeness: Completeness = "complete"
+    evidence: Confidence = "confirmed"
+    kind: Literal["scalar", "string", "collection", "tuple", "regex", "unknown"] = "scalar"
+    items: tuple[_Value, ...] = ()
+
+
+class _Unsupported(Exception):
+    def __init__(self, reason: str, *, may_mutate: bool = False) -> None:
+        super().__init__(reason)
+        self.may_mutate = may_mutate
+
+
+def _combine(values: tuple[_Value, ...], *, inferred: bool = False) -> _Value:
+    complete: Completeness = "complete"
+    if any(value.completeness != "complete" for value in values):
+        complete = "partial" if any(value.depends for value in values) else "unresolved"
+    evidence: Confidence = "inferred" if inferred else "confirmed"
+    if any(value.evidence == "unresolved" for value in values):
+        evidence = "inferred" if any(value.depends for value in values) else "unresolved"
+    elif any(value.evidence == "inferred" for value in values):
+        evidence = "inferred"
+    return _Value(any(value.depends for value in values), complete, evidence)
+
+
+class _Summarizer:
+    TEXT_METHODS = frozenset(
+        {
+            "lower",
+            "upper",
+            "casefold",
+            "strip",
+            "lstrip",
+            "rstrip",
+            "replace",
+            "removeprefix",
+            "removesuffix",
+            "capitalize",
+            "title",
+            "swapcase",
+            "split",
+            "rsplit",
+            "splitlines",
+            "join",
+            "startswith",
+            "endswith",
+            "find",
+            "rfind",
+            "count",
+            "isalnum",
+            "isalpha",
+            "isdigit",
+            "isspace",
+        }
+    )
+    REGEX_CALLS = frozenset({"sub", "subn", "findall", "split", "escape", "compile"})
+    REGEX_METHODS = frozenset({"sub", "subn", "findall", "split"})
+
+    def __init__(self, parameter: str, symbols: Mapping[str, str]) -> None:
+        self.parameter = parameter
+        self.symbols = symbols
+        self.env = {parameter: _Value(depends=True)}
+        self.local_names: set[str] = {parameter}
+        self.inferred = False
+
+    def _builtin(self, name: str) -> bool:
+        return name not in self.local_names and self.symbols.get(name, f"builtins.{name}") == (
+            f"builtins.{name}"
+        )
+
+    def _qualified(self, node: ast.AST) -> str | None:
+        if isinstance(node, ast.Name) and node.id not in self.local_names:
+            return self.symbols.get(node.id)
+        if isinstance(node, ast.Attribute):
+            base = self._qualified(node.value)
+            return f"{base}.{node.attr}" if base else None
+        return None
+
+    def expression(self, node: ast.AST) -> _Value:
+        if isinstance(node, ast.Constant):
+            return _Value(kind="string" if isinstance(node.value, str) else "scalar")
+        if isinstance(node, ast.Name):
+            return self.env.get(
+                node.id, _Value(completeness="unresolved", evidence="unresolved", kind="unknown")
+            )
+        if isinstance(node, (ast.Tuple, ast.List, ast.Set)):
+            values = tuple(self.expression(item) for item in node.elts)
+            combined = _combine(values)
+            return _Value(
+                combined.depends,
+                combined.completeness,
+                combined.evidence,
+                "tuple" if isinstance(node, ast.Tuple) else "collection",
+                values,
+            )
+        if isinstance(node, ast.Dict):
+            values = tuple(
+                self.expression(item) for item in (*node.keys, *node.values) if item is not None
+            )
+            combined = _combine(values)
+            return _Value(combined.depends, combined.completeness, combined.evidence, "collection")
+        if isinstance(node, ast.BinOp):
+            values = (self.expression(node.left), self.expression(node.right))
+            combined = _combine(values)
+            if any(value.kind in {"collection", "tuple"} for value in values):
+                return _Value(combined.depends, combined.completeness, combined.evidence, "unknown")
+            return combined
+        if isinstance(node, ast.UnaryOp):
+            return self.expression(node.operand)
+        if isinstance(node, ast.Subscript):
+            value = self.expression(node.value)
+            index = self.expression(node.slice)
+            if value.kind == "tuple" and isinstance(node.slice, ast.Constant):
+                position = node.slice.value
+                if isinstance(position, int) and -len(value.items) <= position < len(value.items):
+                    return value.items[position]
+            combined = _combine((value, index), inferred=True)
+            self.inferred = True
+            return combined
+        if isinstance(node, ast.Slice):
+            return _combine(
+                tuple(
+                    self.expression(item)
+                    for item in (node.lower, node.upper, node.step)
+                    if item is not None
+                )
+            )
+        if isinstance(node, ast.JoinedStr):
+            combined = _combine(tuple(self.expression(item) for item in node.values), inferred=True)
+            self.inferred = True
+            return _Value(combined.depends, combined.completeness, combined.evidence, "string")
+        if isinstance(node, ast.FormattedValue):
+            value = self.expression(node.value)
+            if node.format_spec is None:
+                return value
+            # A format spec is itself an f-string: nested replacement fields
+            # may execute calls and must not disappear from the summary.
+            return _combine((value, self.expression(node.format_spec)), inferred=True)
+        if isinstance(node, ast.Call):
+            return self.call(node)
+        raise _Unsupported(f"Unsupported callback expression: {type(node).__name__}.")
+
+    def call(self, node: ast.Call) -> _Value:
+        if any(isinstance(arg, ast.Starred) for arg in node.args) or any(
+            keyword.arg is None for keyword in node.keywords
+        ):
+            raise _Unsupported("Dynamic callback arguments are not summarized.", may_mutate=True)
+        qualified = self._qualified(node.func)
+        method: str | None = None
+        receiver: _Value | None = None
+        if qualified and (
+            qualified in {f"re.{name}" for name in self.REGEX_CALLS}
+            or qualified in {"emoji.replace_emoji", "emoji.demojize"}
+        ):
+            method = qualified
+        elif isinstance(node.func, ast.Attribute):
+            receiver = self.expression(node.func.value)
+            if receiver.kind == "regex" and node.func.attr in self.REGEX_METHODS:
+                method = f"regex.{node.func.attr}"
+            elif receiver.kind in {"scalar", "string"} and node.func.attr in self.TEXT_METHODS:
+                method = f"str.{node.func.attr}"
+        elif isinstance(node.func, ast.Name) and node.func.id in {"len", "str"}:
+            if self._builtin(node.func.id):
+                method = f"builtins.{node.func.id}"
+        if method is None:
+            raise _Unsupported(
+                "Callback calls an unresolved or unsupported callable.", may_mutate=True
+            )
+        arguments = tuple(self.expression(arg) for arg in node.args) + tuple(
+            self.expression(keyword.value) for keyword in node.keywords
+        )
+        # re.sub and emoji.replace_emoji explicitly accept callable replacements.
+        # A trusted library identity does not establish that argument's purity.
+        if method in {"re.sub", "re.subn", "regex.sub", "regex.subn", "emoji.replace_emoji"}:
+            position = 1 if method.startswith("re.") else 0
+            if method == "emoji.replace_emoji":
+                position = 1
+            replacement = None
+            if len(node.args) > position:
+                replacement = self.expression(node.args[position])
+            keyword_name = "replace" if method.startswith("emoji.") else "repl"
+            for keyword in node.keywords:
+                if keyword.arg == keyword_name:
+                    replacement = self.expression(keyword.value)
+            if replacement is not None and replacement.kind == "unknown":
+                raise _Unsupported(
+                    "Callback replacement may invoke an unresolved callable.", may_mutate=True
+                )
+        values = arguments if receiver is None else (receiver, *arguments)
+        combined = _combine(values, inferred=True)
+        self.inferred = True
+        kind: Literal["scalar", "string", "collection", "tuple", "regex", "unknown"] = "string"
+        if method == "re.compile":
+            kind = "regex"
+        elif method.rsplit(".", 1)[-1] in {"findall", "split", "rsplit", "splitlines"}:
+            kind = "collection"
+        elif method.endswith(".subn"):
+            # Its result is a tuple, but its component contracts need a separate rule.
+            kind = "unknown"
+        return _Value(combined.depends, combined.completeness, combined.evidence, kind)
+
+    def assign(self, target: ast.AST, value: _Value) -> None:
+        if isinstance(target, ast.Name):
+            self.env[target.id] = value
+            return
+        if isinstance(target, (ast.Tuple, ast.List)):
+            if value.kind != "tuple" or len(target.elts) != len(value.items):
+                raise _Unsupported("Callback unpacking has an unresolved shape.")
+            for child, item in zip(target.elts, value.items, strict=True):
+                self.assign(child, item)
+            return
+        raise _Unsupported("Callback writes through an object or subscript.", may_mutate=True)
+
+    def _guard(self, node: ast.If) -> bool:
+        test = node.test
+        if not (
+            isinstance(test, ast.UnaryOp)
+            and isinstance(test.op, ast.Not)
+            and isinstance(test.operand, ast.Call)
+        ):
+            return False
+        call = test.operand
+        return (
+            isinstance(call.func, ast.Name)
+            and call.func.id == "isinstance"
+            and self._builtin("isinstance")
+            and self._builtin("str")
+            and len(call.args) == 2
+            and not call.keywords
+            and isinstance(call.args[0], ast.Name)
+            and call.args[0].id == self.parameter
+            and isinstance(call.args[1], ast.Name)
+            and call.args[1].id == "str"
+            and len(node.body) == 1
+            and isinstance(node.body[0], ast.Return)
+            and not node.orelse
+        )
+
+    def body(self, statements: list[ast.stmt]) -> tuple[_Value, ...]:
+        returns: list[_Value] = []
+        for statement in statements:
+            if isinstance(statement, ast.Assign):
+                value = self.expression(statement.value)
+                for target in statement.targets:
+                    self.assign(target, value)
+            elif isinstance(statement, ast.AnnAssign):
+                if statement.value is not None:
+                    self.assign(statement.target, self.expression(statement.value))
+            elif isinstance(statement, ast.Return):
+                returns.append(self.expression(statement.value) if statement.value else _Value())
+                break
+            elif isinstance(statement, ast.Expr):
+                self.expression(statement.value)
+            elif isinstance(statement, ast.Pass):
+                continue
+            elif isinstance(statement, ast.If) and self._guard(statement):
+                early = statement.body[0]
+                assert isinstance(early, ast.Return)
+                result = self.expression(early.value) if early.value else _Value()
+                if result.depends or result.completeness != "complete":
+                    raise _Unsupported("The isinstance fallback must return only local constants.")
+                returns.append(result)
+                self.env[self.parameter] = _Value(depends=True, kind="string")
+            else:
+                raise _Unsupported(
+                    f"Unsupported callback statement: {type(statement).__name__}.",
+                    may_mutate=True,
+                )
+        else:
+            returns.append(_Value())
+        return tuple(returns)
+
+
+def summarize_callback(
+    node: ast.FunctionDef,
+    *,
+    input_parameter: str | None = None,
+    symbols: Mapping[str, str] | None = None,
+) -> CallbackSummary:
+    """Summarize a direct, scalar callback without evaluating any project code.
+
+    Tuple return components are positionally distinct. Scalar returns have one
+    component; dynamic or inconsistent return arity is rejected. ``symbols``
+    maps names to statically resolved imports, not guessed module spellings.
+    """
+    parameters = (*node.args.posonlyargs, *node.args.args)
+    if (
+        len(parameters) != 1
+        or node.args.vararg
+        or node.args.kwarg
+        or node.args.kwonlyargs
+        or node.args.defaults
+        or node.decorator_list
+    ):
+        return CallbackSummary(None, False, False, "Callback requires one plain scalar parameter.")
+    parameter = parameters[0].arg
+    if input_parameter is not None and parameter != input_parameter:
+        return CallbackSummary(None, False, False, "Callback parameter could not be bound.")
+    nodes = list(ast.walk(node))
+    if len(nodes) > 1000:
+        return CallbackSummary(None, False, False, "Callback exceeds the static summary budget.")
+    if any(isinstance(item, (ast.Global, ast.Nonlocal)) for item in nodes):
+        return CallbackSummary(None, False, True, "Callback declares global or nonlocal state.")
+    if any(
+        isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef))
+        for item in nodes
+        if item is not node
+    ):
+        return CallbackSummary(None, False, False, "Nested callback scopes are not summarized.")
+    summarizer = _Summarizer(parameter, symbols or {})
+    summarizer.local_names.update(
+        item.id for item in nodes if isinstance(item, ast.Name) and isinstance(item.ctx, ast.Store)
+    )
+    try:
+        returned = summarizer.body(node.body)
+    except (_Unsupported, RecursionError) as error:
+        return CallbackSummary(
+            None,
+            False,
+            error.may_mutate if isinstance(error, _Unsupported) else False,
+            str(error)
+            if isinstance(error, _Unsupported)
+            else "Callback nesting exceeds the budget.",
+        )
+    shapes = {len(value.items) if value.kind == "tuple" else 1 for value in returned}
+    if len(shapes) != 1 or any(value.kind in {"collection", "unknown"} for value in returned):
+        return CallbackSummary(
+            None, False, False, "Callback return shape is not statically stable."
+        )
+    arity = shapes.pop()
+    rows = tuple(value.items if value.kind == "tuple" else (value,) for value in returned)
+    components = tuple(
+        CallbackComponent(merged.depends, merged.completeness, merged.evidence)
+        for index in range(arity)
+        for merged in (_combine(tuple(row[index] for row in rows)),)
+    )
+    if len(returned) > 1 and any(not component.depends_on_input for component in components):
+        return CallbackSummary(
+            None,
+            False,
+            False,
+            "Conditional callback components require unsupported control dependencies.",
+        )
+    reason = (
+        "Inferred value dependencies under the bounded scalar-text API contract."
+        if summarizer.inferred
+        else "Explicit callback return value dependencies."
+    )
+    history = _CallbackHistory(parameter, symbols or {}, summarizer.local_names)
+    outputs = history.body(node.body)
+    components = tuple(
+        CallbackComponent(
+            component.depends_on_input,
+            component.completeness,
+            component.evidence,
+            outputs[index] if index < len(outputs) else (),
+        )
+        for index, component in enumerate(components)
+    )
+    return CallbackSummary(components, True, False, reason, tuple(history.steps))