deploy-guard-engine 0.1.0__py3-none-any.whl

deploy_guard/ingest/discover.py

@@ -0,0 +1,166 @@
+"""Walk a product directory and build a :class:`Project` shell.
+
+Discovery is deliberately dumb: it finds source files, works out each Python
+module's dotted name from its package roots, and sniffs the build system.
+Parsing into functions and classes is the frontend's job.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from deploy_guard.ir.model import Module, Project
+
+# Directories we never descend into.
+SKIP_DIRS = {
+    ".git", ".hg", ".svn",
+    ".venv", "venv", "env", ".env",
+    "node_modules", "__pycache__",
+    ".idea", ".vscode",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox", ".nox",
+    "build", "dist", ".eggs", "site-packages",
+    ".deploy_guard",
+}
+
+TEST_DIR_NAMES = {"tests", "test", "testing"}
+
+
+def _looks_like_test(path: Path) -> bool:
+    name = path.name
+    if name == "conftest.py":
+        return True
+    if name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    return any(part in TEST_DIR_NAMES for part in path.parts)
+
+
+def _package_root(py_file: Path) -> Path:
+    """The directory to put on ``sys.path`` so ``py_file`` imports cleanly.
+
+    Walk up while each directory is a package (has ``__init__.py``); the first
+    ancestor that is not a package is the root.
+    """
+    parent = py_file.parent
+    while (parent.parent != parent) and (parent / "__init__.py").exists():
+        parent = parent.parent
+    return parent
+
+
+def _dotted_name(py_file: Path, root: Path) -> str:
+    rel = py_file.relative_to(root).with_suffix("")
+    parts = list(rel.parts)
+    if parts and parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts) if parts else py_file.stem
+
+
+def _detect_build_systems(root: Path) -> tuple[list[str], list[str]]:
+    """Return (build_systems, notes)."""
+    systems: list[str] = []
+    notes: list[str] = []
+    checks = {
+        "pyproject.toml": "pyproject",
+        "setup.py": "setuptools",
+        "setup.cfg": "setuptools",
+        "Pipfile": "pipenv",
+        "poetry.lock": "poetry",
+        "pdm.lock": "pdm",
+        "pom.xml": "maven",
+        "build.gradle": "gradle",
+        "build.gradle.kts": "gradle",
+    }
+    for fname, system in checks.items():
+        if (root / fname).exists() and system not in systems:
+            systems.append(system)
+    for req in sorted(root.glob("requirements*.txt")):
+        notes.append(f"found {req.name}")
+        if "pip-requirements" not in systems:
+            systems.append("pip-requirements")
+    return systems, notes
+
+
+def _inside_venv(directory: Path, root: Path, cache: dict[Path, bool]) -> bool:
+    """True if ``directory`` is at or below a virtualenv (a dir with pyvenv.cfg)."""
+    if directory in cache:
+        return cache[directory]
+    if directory != root and root not in directory.parents:
+        cache[directory] = False
+        return False
+    result = (directory / "pyvenv.cfg").exists()
+    if not result and directory != root:
+        result = _inside_venv(directory.parent, root, cache)
+    cache[directory] = result
+    return result
+
+
+def discover(
+    root: str | Path,
+    *,
+    include_tests: bool = False,
+    extra_exclude: list[str] | None = None,
+) -> Project:
+    root = Path(root).resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"not a directory: {root}")
+    _excluded = set(extra_exclude or ())
+
+    build_systems, notes = _detect_build_systems(root)
+    project = Project(root=root, build_systems=build_systems, notes=notes)
+
+    java_count = 0
+    package_roots: set[Path] = set()
+    venv_cache: dict[Path, bool] = {}
+
+    for path in sorted(root.rglob("*")):
+        if path.is_dir():
+            continue
+        rel_parts = path.relative_to(root).parts
+        if any(part in SKIP_DIRS for part in rel_parts):
+            continue
+        if _excluded and any(part in _excluded for part in rel_parts):
+            continue
+        # Skip any virtualenv regardless of its name (it carries a pyvenv.cfg).
+        if _inside_venv(path.parent, root, venv_cache):
+            continue
+
+        if path.suffix == ".java":
+            java_count += 1
+            project.languages.add("java")
+            continue
+
+        if path.suffix != ".py":
+            continue
+
+        project.languages.add("python")
+        if not include_tests and _looks_like_test(path):
+            continue
+
+        pkg_root = _package_root(path)
+        package_roots.add(pkg_root)
+        try:
+            source = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError) as exc:
+            project.modules.append(
+                Module(
+                    path=path,
+                    dotted_name=path.stem,
+                    parse_error=f"could not read file: {exc}",
+                )
+            )
+            continue
+
+        project.modules.append(
+            Module(
+                path=path,
+                dotted_name=_dotted_name(path, pkg_root),
+                is_package=(path.name == "__init__.py"),
+                source=source,
+            )
+        )
+
+    project.package_roots = sorted(package_roots)
+    if java_count:
+        project.notes.append(
+            f"{java_count} Java file(s) found - Java frontend lands in M4, skipped for now"
+        )
+    return project

deploy_guard/ir/__init__.py

@@ -0,0 +1,24 @@
+"""Language-neutral intermediate representation.
+
+Frontends (Python, Java) lower source into the dataclasses in
+:mod:`deploy_guard.ir.model`; every analysis pass then runs on this shared IR
+so the clever work is written once.
+"""
+
+from deploy_guard.ir.model import (
+    ClassDef,
+    FunctionDef,
+    Module,
+    Parameter,
+    Project,
+    SourceSpan,
+)
+
+__all__ = [
+    "Project",
+    "Module",
+    "ClassDef",
+    "FunctionDef",
+    "Parameter",
+    "SourceSpan",
+]

deploy_guard/ir/cfg.py

@@ -0,0 +1,114 @@
+"""Control-flow graph dataclasses.
+
+A :class:`CFG` is a set of :class:`BasicBlock` nodes connected by
+:class:`Edge` objects.  Blocks carry the source statements that run when the
+block is entered; the block's :class:`Terminator` says how control leaves it
+when it is not via a normal edge (a ``return``, ``raise``, ``break`` ...).
+
+The representation is language-neutral: ``Statement.node`` and ``Edge.guard``
+hold whatever native node the frontend produced.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class EdgeKind(str, Enum):
+    SEQ = "seq"            # unconditional fall-through
+    TRUE = "true"          # branch taken when the guard holds
+    FALSE = "false"        # branch taken when the guard fails
+    MATCH = "match"        # a match-case branch (guard is the pattern)
+    LOOP_BACK = "loop_back"  # back-edge to a loop header
+    EXCEPTION = "exception"  # an exception may transfer control here
+
+
+class Terminator(str, Enum):
+    NONE = "none"                      # leaves via its edges
+    RETURN = "return"                  # explicit ``return <value>``
+    IMPLICIT_RETURN = "implicit_return"  # control fell off the end -> returns None
+    RAISE = "raise"                    # explicit ``raise``
+    BREAK = "break"
+    CONTINUE = "continue"
+
+
+@dataclass
+class Statement:
+    node: Any            # native AST node
+    lineno: int
+    kind: str            # node class name, e.g. "Assign", "Expr", "If"
+    src: str = ""        # unparsed source, possibly truncated
+
+
+@dataclass
+class Edge:
+    target: int
+    kind: EdgeKind = EdgeKind.SEQ
+    guard: Any = None            # native expression node for TRUE/FALSE/MATCH
+    guard_src: str | None = None
+    negated: bool = False        # guard_src is the condition; negated => FALSE arm
+
+
+@dataclass
+class BasicBlock:
+    id: int
+    statements: list[Statement] = field(default_factory=list)
+    succ: list[Edge] = field(default_factory=list)
+    pred: list[int] = field(default_factory=list)
+    terminator: Terminator = Terminator.NONE
+    term_node: Any = None        # the return / raise node, when applicable
+    label: str = ""
+
+    @property
+    def first_line(self) -> int | None:
+        return self.statements[0].lineno if self.statements else None
+
+
+@dataclass
+class CFG:
+    func_qualname: str
+    entry: int
+    exit: int
+    blocks: dict[int, BasicBlock] = field(default_factory=dict)
+    notes: list[str] = field(default_factory=list)
+
+    def block(self, bid: int) -> BasicBlock:
+        return self.blocks[bid]
+
+    def iter_blocks(self) -> Iterator[BasicBlock]:
+        return iter(self.blocks.values())
+
+    def finalize(self) -> CFG:
+        """Recompute predecessor lists.  Call once the graph is fully built."""
+        for b in self.blocks.values():
+            b.pred = []
+        for b in self.blocks.values():
+            for e in b.succ:
+                if e.target in self.blocks and b.id not in self.blocks[e.target].pred:
+                    self.blocks[e.target].pred.append(b.id)
+        return self
+
+    def reachable_ids(self) -> set[int]:
+        seen: set[int] = set()
+        q: deque[int] = deque([self.entry])
+        while q:
+            bid = q.popleft()
+            if bid in seen or bid not in self.blocks:
+                continue
+            seen.add(bid)
+            for e in self.blocks[bid].succ:
+                q.append(e.target)
+        return seen
+
+    def unreachable_blocks(self) -> list[BasicBlock]:
+        reach = self.reachable_ids()
+        out = [
+            b
+            for bid, b in sorted(self.blocks.items())
+            if bid not in reach and b.statements
+        ]
+        return out

deploy_guard/ir/model.py

@@ -0,0 +1,128 @@
+"""The language-neutral IR dataclasses.
+
+A :class:`Project` holds many :class:`Module` objects, each of which exposes
+module-level :class:`FunctionDef` and :class:`ClassDef` nodes.  Frontends fill
+these in; analyses read them.  The ``raw`` field on a function carries the
+frontend's native AST node (a Python ``ast.FunctionDef`` today) and is only
+touched by language-specific passes such as the CFG builder.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class ParamKind(str, Enum):
+    POSITIONAL_ONLY = "positional_only"
+    POSITIONAL_OR_KEYWORD = "positional_or_keyword"
+    VAR_POSITIONAL = "var_positional"
+    KEYWORD_ONLY = "keyword_only"
+    VAR_KEYWORD = "var_keyword"
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    """A range in a source file.  1-indexed lines, 0-indexed columns."""
+
+    file: Path
+    lineno: int
+    end_lineno: int
+    col: int = 0
+    end_col: int = 0
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return f"{self.file}:{self.lineno}"
+
+
+@dataclass
+class Parameter:
+    name: str
+    kind: ParamKind = ParamKind.POSITIONAL_OR_KEYWORD
+    annotation: str | None = None
+    default: str | None = None  # source text of the default, if any
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not None or self.kind in (
+            ParamKind.VAR_POSITIONAL,
+            ParamKind.VAR_KEYWORD,
+        )
+
+
+@dataclass
+class FunctionDef:
+    name: str
+    qualname: str
+    span: SourceSpan
+    params: list[Parameter] = field(default_factory=list)
+    returns: str | None = None  # return annotation source text
+    decorators: list[str] = field(default_factory=list)
+    docstring: str | None = None
+    is_async: bool = False
+    is_method: bool = False
+    # The frontend's native node, e.g. an ``ast.FunctionDef``.  Only
+    # language-specific passes may read this.
+    raw: Any = None
+
+    @property
+    def is_public(self) -> bool:
+        return not self.name.startswith("_")
+
+    @property
+    def positional_params(self) -> list[Parameter]:
+        skip = ParamKind.VAR_POSITIONAL, ParamKind.VAR_KEYWORD, ParamKind.KEYWORD_ONLY
+        out = [p for p in self.params if p.kind not in skip]
+        if self.is_method and out and out[0].name in ("self", "cls"):
+            out = out[1:]
+        return out
+
+
+@dataclass
+class ClassDef:
+    name: str
+    qualname: str
+    span: SourceSpan
+    bases: list[str] = field(default_factory=list)
+    decorators: list[str] = field(default_factory=list)
+    docstring: str | None = None
+    methods: list[FunctionDef] = field(default_factory=list)
+
+
+@dataclass
+class Module:
+    path: Path
+    dotted_name: str
+    is_package: bool = False
+    source: str = ""
+    imports: list[str] = field(default_factory=list)
+    functions: list[FunctionDef] = field(default_factory=list)
+    classes: list[ClassDef] = field(default_factory=list)
+    parse_error: str | None = None
+    # (lineno, message) for SyntaxWarnings raised while parsing this module.
+    syntax_warnings: list[tuple[int, str]] = field(default_factory=list)
+
+    def iter_functions(self) -> Iterator[FunctionDef]:
+        """Every function in the module: module-level then per class."""
+        yield from self.functions
+        for cls in self.classes:
+            yield from cls.methods
+
+
+@dataclass
+class Project:
+    root: Path
+    languages: set[str] = field(default_factory=set)
+    build_systems: list[str] = field(default_factory=list)
+    package_roots: list[Path] = field(default_factory=list)
+    modules: list[Module] = field(default_factory=list)
+    entrypoints: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def iter_functions(self) -> Iterator[tuple[Module, FunctionDef]]:
+        for mod in self.modules:
+            for fn in mod.iter_functions():
+                yield mod, fn

deploy_guard/report/__init__.py

@@ -0,0 +1,5 @@
+"""Rendering of :class:`~deploy_guard.engine.ScanResult` for humans and machines."""
+
+from deploy_guard.report.render import render_json, render_markdown, render_text
+
+__all__ = ["render_text", "render_markdown", "render_json"]