coretrace-python-analyzer 0.1.0__py3-none-any.whl

coretrace_python/cfg/dominance.py

@@ -0,0 +1,183 @@
+"""Dominance and post-dominance over control-flow graphs (architecture §5).
+
+Both trees come from the same iterative algorithm (Cooper, Harvey and Kennedy) run on
+the forward graph from the entry, or on the reversed graph from a virtual ``EXIT``
+that follows every returning or raising block. The post-dominance frontier is the
+control-dependence relation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import ClassVar
+
+from coretrace_python.analysis import AnalysisContext, AnyAnalysis, FunctionAnalysis
+from coretrace_python.cfg.builder import CFGAnalysis
+from coretrace_python.cfg.model import CFG, BlockId
+from coretrace_python.hir import nodes
+
+EXIT = BlockId("<exit>")
+
+
+@dataclass(frozen=True)
+class DominatorTree:
+    root: BlockId
+    blocks: tuple[BlockId, ...]
+    _idom: Mapping[BlockId, BlockId | None]
+    _children: Mapping[BlockId, tuple[BlockId, ...]]
+    _frontier: Mapping[BlockId, frozenset[BlockId]]
+    _depth: Mapping[BlockId, int] = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        depth: dict[BlockId, int] = {}
+        for block in self.blocks:
+            parent = self._idom[block]
+            depth[block] = 0 if parent is None else depth[parent] + 1
+        object.__setattr__(self, "_depth", MappingProxyType(depth))
+
+    def idom(self, block: BlockId) -> BlockId | None:
+        return self._idom[block]
+
+    def children(self, block: BlockId) -> tuple[BlockId, ...]:
+        return self._children[block]
+
+    def frontier(self, block: BlockId) -> frozenset[BlockId]:
+        return self._frontier[block]
+
+    def dominates(self, dominator: BlockId, block: BlockId) -> bool:
+        if dominator not in self._idom or block not in self._idom:
+            return False
+        current: BlockId | None = block
+        while current is not None and self._depth[current] >= self._depth[dominator]:
+            if current == dominator:
+                return True
+            current = self._idom[current]
+        return False
+
+    def iterated_frontier(self, blocks: Iterable[BlockId]) -> frozenset[BlockId]:
+        result: set[BlockId] = set()
+        pending = list(blocks)
+        while pending:
+            for candidate in self._frontier[pending.pop()]:
+                if candidate not in result:
+                    result.add(candidate)
+                    pending.append(candidate)
+        return frozenset(result)
+
+
+def _build(
+    root: BlockId,
+    successors: Callable[[BlockId], tuple[BlockId, ...]],
+    order: Callable[[BlockId], int],
+) -> DominatorTree:
+    # Reverse postorder over the reachable nodes.
+    postorder: list[BlockId] = []
+    seen: set[BlockId] = set()
+
+    def visit(node: BlockId) -> None:
+        seen.add(node)
+        for successor in successors(node):
+            if successor not in seen:
+                visit(successor)
+        postorder.append(node)
+
+    visit(root)
+    rpo = list(reversed(postorder))
+    index = {node: position for position, node in enumerate(rpo)}
+    predecessors: dict[BlockId, list[BlockId]] = {node: [] for node in rpo}
+    for node in rpo:
+        for successor in successors(node):
+            predecessors[successor].append(node)
+
+    idom: dict[BlockId, BlockId | None] = {root: None}
+
+    def intersect(a: BlockId, b: BlockId) -> BlockId:
+        while a != b:
+            while index[a] > index[b]:
+                a = idom[a]  # type: ignore[assignment]
+            while index[b] > index[a]:
+                b = idom[b]  # type: ignore[assignment]
+        return a
+
+    changed = True
+    while changed:
+        changed = False
+        for node in rpo[1:]:
+            candidates = [p for p in predecessors[node] if p in idom]
+            new_idom = candidates[0]
+            for other in candidates[1:]:
+                new_idom = intersect(other, new_idom)
+            if idom.get(node) != new_idom:
+                idom[node] = new_idom
+                changed = True
+
+    children: dict[BlockId, list[BlockId]] = {node: [] for node in rpo}
+    for node in sorted(rpo, key=order):
+        parent = idom[node]
+        if parent is not None:
+            children[parent].append(node)
+
+    frontier: dict[BlockId, set[BlockId]] = {node: set() for node in rpo}
+    for node in rpo:
+        if node == root or len(predecessors[node]) < 2:
+            continue
+        for predecessor in predecessors[node]:
+            runner: BlockId | None = predecessor
+            while runner is not None and runner != idom[node]:
+                frontier[runner].add(node)
+                runner = idom[runner]
+
+    preorder: list[BlockId] = []
+
+    def walk(node: BlockId) -> None:
+        preorder.append(node)
+        for child in children[node]:
+            walk(child)
+
+    walk(root)
+    return DominatorTree(
+        root=root,
+        blocks=tuple(preorder),
+        _idom=MappingProxyType(dict(idom)),
+        _children=MappingProxyType({k: tuple(v) for k, v in children.items()}),
+        _frontier=MappingProxyType({k: frozenset(v) for k, v in frontier.items()}),
+    )
+
+
+def dominator_tree(cfg: CFG) -> DominatorTree:
+    order = {block_id: position for position, block_id in enumerate(cfg.blocks)}
+    return _build(cfg.entry, cfg.successors, lambda block: order[block])
+
+
+def post_dominator_tree(cfg: CFG) -> DominatorTree:
+    reachable = cfg.reachable()
+    order = {block_id: position for position, block_id in enumerate(cfg.blocks)}
+    order[EXIT] = -1
+    leaves = tuple(b for b in cfg.blocks if b in reachable and not cfg.successors(b))
+
+    def reversed_successors(block: BlockId) -> tuple[BlockId, ...]:
+        if block == EXIT:
+            return leaves
+        return tuple(p for p in cfg.predecessors(block) if p in reachable)
+
+    return _build(EXIT, reversed_successors, lambda block: order[block])
+
+
+class DominanceAnalysis(FunctionAnalysis[DominatorTree]):
+    name: ClassVar[str] = "cfg.dominance"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({CFGAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> DominatorTree:
+        return dominator_tree(ctx.get(CFGAnalysis, function))
+
+
+class PostDominanceAnalysis(FunctionAnalysis[DominatorTree]):
+    name: ClassVar[str] = "cfg.post_dominance"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({CFGAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> DominatorTree:
+        return post_dominator_tree(ctx.get(CFGAnalysis, function))

coretrace_python/cfg/model.py

@@ -0,0 +1,166 @@
+"""Control-flow graph model (architecture §5).
+
+A block holds straight-line PyHIR statements and ends in exactly one terminator.
+Python's iteration protocol stays explicit as ``ForEach`` instead of being encoded as
+a generic switch; the CFG must remain semantically faithful to Python.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TypeAlias
+
+from coretrace_python.hir import nodes
+from coretrace_python.source import SourceSpan
+
+
+class CFGError(Exception):
+    """A malformed graph or a control statement used outside its construct."""
+
+
+@dataclass(frozen=True, order=True)
+class BlockId:
+    value: str
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True)
+class Branch:
+    condition: nodes.Expression
+    then_block: BlockId
+    else_block: BlockId
+    span: SourceSpan
+
+
+@dataclass(frozen=True)
+class Jump:
+    target: BlockId
+    span: SourceSpan
+
+
+@dataclass(frozen=True)
+class Return:
+    value: nodes.Expression | None
+    span: SourceSpan
+
+
+@dataclass(frozen=True)
+class Raise:
+    exception: nodes.Expression | None
+    span: SourceSpan
+    cause: nodes.Expression | None = None
+
+
+@dataclass(frozen=True)
+class ForEach:
+    """Bind the next item of ``iterable`` to ``target`` and enter ``body``, or ``exit``."""
+
+    target: nodes.Name
+    iterable: nodes.Expression
+    body: BlockId
+    exit: BlockId
+    span: SourceSpan
+
+
+Terminator: TypeAlias = Branch | Jump | Return | Raise | ForEach
+
+
+def targets(terminator: Terminator) -> tuple[BlockId, ...]:
+    if isinstance(terminator, Branch):
+        return (terminator.then_block, terminator.else_block)
+    if isinstance(terminator, Jump):
+        return (terminator.target,)
+    if isinstance(terminator, ForEach):
+        return (terminator.body, terminator.exit)
+    return ()
+
+
+@dataclass(frozen=True)
+class BasicBlock:
+    id: BlockId
+    statements: tuple[nodes.Statement, ...]
+    terminator: Terminator
+    exception_targets: tuple[BlockId, ...] = ()
+    """Handler blocks control may reach if a statement of this block raises."""
+
+
+@dataclass(frozen=True)
+class CFG:
+    entry: BlockId
+    blocks: Mapping[BlockId, BasicBlock]
+    # Locals the builder introduced while laying out expression-level control flow
+    # (conditional expressions, comprehensions); the lowering treats them as locals.
+    synthetic_locals: frozenset[str] = frozenset()
+    _successors: Mapping[BlockId, tuple[BlockId, ...]] = field(
+        init=False, repr=False, compare=False
+    )
+    _predecessors: Mapping[BlockId, tuple[BlockId, ...]] = field(
+        init=False, repr=False, compare=False
+    )
+
+    def __post_init__(self) -> None:
+        blocks = MappingProxyType(dict(self.blocks))
+        if self.entry not in blocks:
+            raise CFGError(f"entry block {self.entry} does not exist")
+        predecessors: dict[BlockId, list[BlockId]] = {block_id: [] for block_id in blocks}
+        successors: dict[BlockId, tuple[BlockId, ...]] = {}
+        for block_id, block in blocks.items():
+            if block.id != block_id:
+                raise CFGError(f"block {block.id} is stored under {block_id}")
+            found = list(targets(block.terminator))
+            found.extend(t for t in block.exception_targets if t not in found)
+            successors[block_id] = tuple(found)
+            for target in successors[block_id]:
+                if target not in blocks:
+                    raise CFGError(f"block {block_id} targets unknown block {target}")
+                predecessors[target].append(block_id)
+        object.__setattr__(self, "blocks", blocks)
+        object.__setattr__(self, "_successors", MappingProxyType(successors))
+        object.__setattr__(
+            self,
+            "_predecessors",
+            MappingProxyType({k: tuple(v) for k, v in predecessors.items()}),
+        )
+
+    def block(self, block_id: BlockId) -> BasicBlock:
+        return self.blocks[block_id]
+
+    def successors(self, block_id: BlockId) -> tuple[BlockId, ...]:
+        return self._successors[block_id]
+
+    def predecessors(self, block_id: BlockId) -> tuple[BlockId, ...]:
+        return self._predecessors[block_id]
+
+    def reachable(self) -> frozenset[BlockId]:
+        seen: set[BlockId] = set()
+        pending = [self.entry]
+        while pending:
+            block_id = pending.pop()
+            if block_id not in seen:
+                seen.add(block_id)
+                pending.extend(self.successors(block_id))
+        return frozenset(seen)
+
+    def back_edges(self) -> frozenset[tuple[BlockId, BlockId]]:
+        """Edges whose target is on the depth-first path from the entry to their source."""
+
+        found: set[tuple[BlockId, BlockId]] = set()
+        on_path: set[BlockId] = set()
+        finished: set[BlockId] = set()
+
+        def visit(block_id: BlockId) -> None:
+            on_path.add(block_id)
+            for successor in self.successors(block_id):
+                if successor in on_path:
+                    found.add((block_id, successor))
+                elif successor not in finished:
+                    visit(successor)
+            on_path.remove(block_id)
+            finished.add(block_id)
+
+        visit(self.entry)
+        return frozenset(found)

coretrace_python/cli.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import zipfile
+from pathlib import Path
+
+from coretrace_python import __version__, engine
+from coretrace_python.analysis import AnalysisError
+from coretrace_python.cache import ProjectCache
+from coretrace_python.cfg import CFGError
+from coretrace_python.dependency import dump_advisories, import_osv, read_osv, render_sbom
+from coretrace_python.frontend import HIRBuildError, ParseError, build_hir
+from coretrace_python.ir.lowering import LoweringError, lower_module
+from coretrace_python.ir.printer import format_module
+from coretrace_python.plugins import IncompatiblePluginError, ManifestError
+from coretrace_python.reporters import FORMATS, render
+from coretrace_python.semantic.imports import ImportResolutionError
+from coretrace_python.semantic.scopes import ScopeError
+from coretrace_python.source import SourceManager
+
+EXIT_CLEAN = 0
+EXIT_FINDINGS = 1
+EXIT_ERROR = 2
+
+_ANALYSIS_ERRORS = (
+    OSError,
+    UnicodeError,
+    ParseError,
+    HIRBuildError,
+    ImportResolutionError,
+    ScopeError,
+    CFGError,
+    LoweringError,
+    AnalysisError,
+    ManifestError,
+    IncompatiblePluginError,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=engine.TOOL_NAME,
+        description="Analyze Python source with CoreTrace.",
+    )
+    parser.add_argument(
+        "path", type=Path, nargs="?", help="Python source file, or a directory for --check"
+    )
+    parser.add_argument(
+        "--emit-ir",
+        action="store_true",
+        help="print the lowered Python intermediate representation",
+    )
+    parser.add_argument(
+        "--ssa",
+        action="store_true",
+        help="with --emit-ir, print the static single assignment form",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="run the loaded plugins and report their findings",
+    )
+    parser.add_argument(
+        "--plugins",
+        action="append",
+        type=Path,
+        default=[],
+        metavar="DIR",
+        help="with --check, a directory searched recursively for plugin.toml, loaded on "
+        "top of the bundled plugins (repeatable)",
+    )
+    parser.add_argument(
+        "--no-bundled-plugins",
+        action="store_true",
+        help="with --check, do not load the plugins shipped with the package",
+    )
+    parser.add_argument(
+        "--format",
+        choices=sorted(FORMATS),
+        default=None,
+        help="with --check, the report format (default: text)",
+    )
+    parser.add_argument(
+        "--cache",
+        type=Path,
+        default=None,
+        metavar="DIR",
+        help="with --check on a directory, keep per-module results under DIR and reuse "
+        "them for modules unchanged since the previous run",
+    )
+    parser.add_argument(
+        "--jobs",
+        type=int,
+        default=None,
+        metavar="N",
+        help="with --check on a directory, analyse independent modules in N processes",
+    )
+    parser.add_argument(
+        "--sbom",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="with --check on a directory, write a CycloneDX bill of materials to PATH",
+    )
+    parser.add_argument(
+        "--advisories",
+        action="append",
+        type=Path,
+        default=[],
+        metavar="FILE",
+        help="with --check on a directory, a local advisory file to read in addition to "
+        "advisories.json at the root (repeatable)",
+    )
+    parser.add_argument(
+        "--policy",
+        type=Path,
+        default=None,
+        metavar="FILE",
+        help="with --check on a directory, the dependency policy to apply instead of "
+        "coretrace-policy.toml at the root",
+    )
+    parser.add_argument(
+        "--import-advisories",
+        nargs=2,
+        type=Path,
+        default=None,
+        metavar=("SRC", "OUT"),
+        help="convert an OSV dump (a JSON file, a directory of them or a zip archive) "
+        "into the local advisory file OUT, then exit",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.import_advisories is not None:
+        source, out = args.import_advisories
+        try:
+            out.write_text(dump_advisories(import_osv(read_osv(source))), encoding="utf-8")
+        except (OSError, ValueError, zipfile.BadZipFile) as error:
+            print(f"error: {error}", file=sys.stderr)
+            return EXIT_ERROR
+        return EXIT_CLEAN
+    if not (args.emit_ir or args.check):
+        print("error: no action selected; pass --emit-ir or --check", file=sys.stderr)
+        return EXIT_ERROR
+    if args.path is None:
+        print("error: a path is required", file=sys.stderr)
+        return EXIT_ERROR
+    if args.format is not None and not args.check:
+        print("error: --format only applies to --check", file=sys.stderr)
+        return EXIT_ERROR
+    if args.cache is not None and not (args.check and args.path.is_dir()):
+        print("error: --cache only applies to --check on a directory", file=sys.stderr)
+        return EXIT_ERROR
+    if args.jobs is not None and not (args.check and args.path.is_dir()):
+        print("error: --jobs only applies to --check on a directory", file=sys.stderr)
+        return EXIT_ERROR
+    if args.jobs is not None and args.jobs < 1:
+        print("error: --jobs must be at least 1", file=sys.stderr)
+        return EXIT_ERROR
+    if args.sbom is not None and not (args.check and args.path.is_dir()):
+        print("error: --sbom only applies to --check on a directory", file=sys.stderr)
+        return EXIT_ERROR
+    if args.advisories and not (args.check and args.path.is_dir()):
+        print("error: --advisories only applies to --check on a directory", file=sys.stderr)
+        return EXIT_ERROR
+    if args.policy is not None and not (args.check and args.path.is_dir()):
+        print("error: --policy only applies to --check on a directory", file=sys.stderr)
+        return EXIT_ERROR
+
+    if args.no_bundled_plugins and not args.check:
+        print("error: --no-bundled-plugins only applies to --check", file=sys.stderr)
+        return EXIT_ERROR
+    plugin_roots = ([] if args.no_bundled_plugins else [engine.BUNDLED_PLUGINS]) + list(args.plugins)
+
+    if args.path.is_dir() and args.emit_ir:
+        print(f"error: {args.path} is a directory; --emit-ir needs a file", file=sys.stderr)
+        return EXIT_ERROR
+
+    try:
+        if args.emit_ir:
+            source = SourceManager().load_file(args.path)
+            print(format_module(lower_module(build_hir(source), ssa=args.ssa)))
+        if args.check:
+            if args.path.is_dir():
+                cache = None if args.cache is None else ProjectCache(args.cache)
+                analysis = engine.analyze_project(
+                    args.path,
+                    plugin_roots,
+                    cache=cache,
+                    jobs=args.jobs or 1,
+                    advisory_files=args.advisories,
+                    policy_file=args.policy,
+                )
+                findings = analysis.findings
+                coverage = analysis.coverage
+                if args.sbom is not None:
+                    args.sbom.write_text(
+                        render_sbom(analysis.dependencies, analysis.advisories, engine.TOOL_NAME, __version__),
+                        encoding="utf-8",
+                    )
+            else:
+                file_analysis = engine.analyze_file(SourceManager().load_file(args.path), plugin_roots)
+                findings, coverage = file_analysis.findings, file_analysis.coverage
+            print(render(args.format or "text", engine.report(findings, coverage)), end="")
+            return EXIT_FINDINGS if findings else EXIT_CLEAN
+    except _ANALYSIS_ERRORS as error:
+        print(f"error: {error}", file=sys.stderr)
+        return EXIT_ERROR
+    return EXIT_CLEAN
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

coretrace_python/dataflow/__init__.py

@@ -0,0 +1,29 @@
+"""Generic data-flow framework: lattices and a bidirectional worklist solver."""
+
+from coretrace_python.dataflow.lattice import (
+    BOTTOM,
+    TOP,
+    Bottom,
+    Element,
+    FlatLattice,
+    Lattice,
+    Top,
+    same_element,
+)
+from coretrace_python.dataflow.solver import ENTRY, DataflowProblem, Direction, Solution, solve
+
+__all__ = [
+    "BOTTOM",
+    "ENTRY",
+    "TOP",
+    "Bottom",
+    "DataflowProblem",
+    "Direction",
+    "Element",
+    "FlatLattice",
+    "Lattice",
+    "Solution",
+    "Top",
+    "same_element",
+    "solve",
+]

coretrace_python/dataflow/lattice.py

@@ -0,0 +1,78 @@
+"""Lattice vocabulary shared by data-flow problems (architecture §37 dataflow/lattice).
+
+``BOTTOM`` means "no information yet" and ``TOP`` means "anything". A ``FlatLattice``
+places every other element between the two: equal elements join to themselves, different
+ones to ``TOP``. Elements are compared by type as well as value, so ``1`` and ``True``
+are different constants.
+"""
+
+from __future__ import annotations
+
+from typing import Final, Generic, Protocol, TypeAlias, TypeVar
+
+
+class Bottom:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "BOTTOM"
+
+
+class Top:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "TOP"
+
+
+BOTTOM: Final = Bottom()
+TOP: Final = Top()
+
+T = TypeVar("T")
+Element: TypeAlias = T | Bottom | Top
+
+
+def same_element(a: object, b: object) -> bool:
+    """Equality that also requires equal types, so ``1 == True`` does not conflate."""
+
+    return type(a) is type(b) and bool(a == b)
+
+
+class Lattice(Protocol[T]):
+    @property
+    def bottom(self) -> Element[T]: ...
+
+    @property
+    def top(self) -> Element[T]: ...
+
+    def join(self, a: Element[T], b: Element[T]) -> Element[T]: ...
+
+    def leq(self, a: Element[T], b: Element[T]) -> bool: ...
+
+
+class FlatLattice(Generic[T]):
+    """Bottom < every element < Top, with no order between elements."""
+
+    @property
+    def bottom(self) -> Element[T]:
+        return BOTTOM
+
+    @property
+    def top(self) -> Element[T]:
+        return TOP
+
+    def join(self, a: Element[T], b: Element[T]) -> Element[T]:
+        if a is BOTTOM:
+            return b
+        if b is BOTTOM:
+            return a
+        if a is TOP or b is TOP:
+            return TOP
+        return a if same_element(a, b) else TOP
+
+    def leq(self, a: Element[T], b: Element[T]) -> bool:
+        if a is BOTTOM or b is TOP:
+            return True
+        if a is TOP or b is BOTTOM:
+            return False
+        return same_element(a, b)