bexar 0.1.0__py3-none-any.whl

bexar/__init__.py

@@ -0,0 +1,3 @@
+"""BEXAR Python source protection and compilation toolkit."""
+
+__version__ = "0.1.0"

bexar/__main__.py

@@ -0,0 +1,6 @@
+"""Run BEXAR as a module."""
+
+from bexar.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bexar/analysis/__init__.py

@@ -0,0 +1 @@
+"""Static analysis helpers for Python source code."""

bexar/analysis/project.py

@@ -0,0 +1,529 @@
+
+"""Bounded, non-executing analysis of Python project imports."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import asdict, dataclass
+import os
+from pathlib import Path
+import sys
+
+from bexar.exceptions import BexarError, SourceReadError
+from bexar.parser import DEFAULT_MAX_SOURCE_BYTES, parse_file
+
+DEFAULT_MAX_PROJECT_FILES = 10_000
+DEFAULT_MAX_PROJECT_BYTES = 256 * 1024 * 1024
+
+EXCLUDED_DIRECTORIES = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ImportReference:
+    """A source-level import and its conservative resolution classification."""
+
+    source: str
+    line: int
+    name: str
+    resolution: str
+    target: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class DynamicImportReference:
+    """A syntactically recognized dynamic import call."""
+
+    source: str
+    line: int
+    expression: str
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectAnalysis:
+    """Import inventory and limits for one statically scanned source tree."""
+
+    root: str
+    source_root: str
+    files: tuple[str, ...]
+    imports: tuple[ImportReference, ...]
+    dynamic_imports: tuple[DynamicImportReference, ...]
+    total_source_bytes: int
+    target_python: str
+    grammar_compatible: bool
+    grammar_incompatible_files: tuple[str, ...]
+    python_files_scanned: int
+
+
+def analyze_project(
+    project: str | Path,
+    *,
+    max_files: int = DEFAULT_MAX_PROJECT_FILES,
+    max_bytes: int = DEFAULT_MAX_PROJECT_BYTES,
+    target_python: str = "3.11",
+) -> ProjectAnalysis:
+    """Inventory a source tree without importing or executing project code.
+
+    If ``project/src`` exists, it is treated as the import root; otherwise the
+    supplied directory is the import root. Only ``.py`` files are scanned.
+    """
+    if isinstance(max_files, bool) or not isinstance(max_files, int) or max_files <= 0:
+        raise ValueError("max_files must be a positive integer")
+
+    if isinstance(max_bytes, bool) or not isinstance(max_bytes, int) or max_bytes <= 0:
+        raise ValueError("max_bytes must be a positive integer")
+
+    target = _parse_target_version(target_python)
+
+    root = Path(project).resolve()
+    if not root.is_dir():
+        raise SourceReadError(f"project path is not a directory: {root}")
+
+    source_root = root / "src" if (root / "src").is_dir() else root
+
+    paths = _discover_python_files(source_root, max_files=max_files)
+    if not paths:
+        raise SourceReadError(f"no Python source files found under {source_root}")
+
+    total_bytes = 0
+    for path in paths:
+        try:
+            total_bytes += path.stat().st_size
+        except OSError as error:
+            raise SourceReadError(f"cannot inspect {path}: {error}") from error
+
+        if total_bytes > max_bytes:
+            raise SourceReadError(
+                f"project source exceeds the {max_bytes}-byte total limit"
+            )
+
+    module_by_path = {
+        path: _module_name(path, source_root)
+        for path in paths
+    }
+    module_names = {
+        name for name in module_by_path.values() if name
+    }
+    package_names = _package_names(paths, source_root)
+
+    imports: list[ImportReference] = []
+    dynamic_imports: list[DynamicImportReference] = []
+    incompatible_files: list[str] = []
+
+    for path in paths:
+        try:
+            parsed = parse_file(path, max_bytes=DEFAULT_MAX_SOURCE_BYTES)
+        except BexarError as error:
+            relative = path.relative_to(source_root).as_posix()
+            raise SourceReadError(f"cannot analyze {relative}: {error}") from error
+
+        source_name = (
+            module_by_path[path]
+            or path.relative_to(source_root).as_posix()
+        )
+
+        package_context = (
+            module_by_path[path]
+            if path.name == "__init__.py"
+            else source_name.rpartition(".")[0]
+        )
+
+        if not _supports_grammar(parsed.source, target):
+            incompatible_files.append(
+                path.relative_to(source_root).as_posix()
+            )
+
+        for node in ast.walk(parsed.tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append(
+                        _resolve_absolute_import(
+                            source_name,
+                            alias.name,
+                            module_names,
+                            package_names,
+                            node.lineno,
+                        )
+                    )
+
+            elif isinstance(node, ast.ImportFrom):
+                imports.extend(
+                    _resolve_from_import(
+                        source_name,
+                        node,
+                        module_names,
+                        package_names,
+                        package_context,
+                    )
+                )
+
+            elif (
+                isinstance(node, ast.Call)
+                and _is_dynamic_import(node.func)
+            ):
+                dynamic_imports.append(
+                    DynamicImportReference(
+                        source=source_name,
+                        line=node.lineno,
+                        expression=ast.unparse(node),
+                    )
+                )
+
+    return ProjectAnalysis(
+        root=str(root),
+        source_root=str(source_root),
+        files=tuple(
+            path.relative_to(source_root).as_posix()
+            for path in paths
+        ),
+        imports=tuple(imports),
+        dynamic_imports=tuple(dynamic_imports),
+        total_source_bytes=total_bytes,
+        target_python=f"{target[0]}.{target[1]}",
+        grammar_compatible=not incompatible_files,
+        grammar_incompatible_files=tuple(incompatible_files),
+        python_files_scanned=len(paths),
+    )
+
+
+def _discover_python_files(root: Path, *, max_files: int) -> list[Path]:
+    found: list[Path] = []
+
+    def raise_walk_error(error: OSError) -> None:
+        raise SourceReadError(
+            f"cannot scan project tree: {error}"
+        ) from error
+
+    for current, directories, filenames in os.walk(
+        root,
+        topdown=True,
+        followlinks=False,
+        onerror=raise_walk_error,
+    ):
+        current_path = Path(current)
+
+        directories[:] = sorted(
+            name
+            for name in directories
+            if name not in EXCLUDED_DIRECTORIES
+            and not (current_path / name).is_symlink()
+        )
+
+        for filename in sorted(filenames):
+            if filename.endswith(".py"):
+                path = current_path / filename
+
+                if path.is_symlink():
+                    continue
+
+                found.append(path)
+
+                if len(found) > max_files:
+                    raise SourceReadError(
+                        f"project contains more than the {max_files}-file limit"
+                    )
+
+    return found
+
+
+def _module_name(path: Path, source_root: Path) -> str:
+    relative = path.relative_to(source_root).with_suffix("")
+    parts = relative.parts
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+
+    if (source_root / "__init__.py").is_file():
+        return ".".join(
+            (source_root.name, *parts)
+        ) if parts else source_root.name
+
+    return ".".join(parts)
+
+
+def _package_names(
+    paths: list[Path],
+    source_root: Path,
+) -> set[str]:
+    packages = set()
+
+    if (source_root / "__init__.py").is_file():
+        packages.add(source_root.name)
+
+    for path in paths:
+        parts = path.relative_to(source_root).with_suffix("").parts
+        package_parts = parts[:-1]
+
+        if (source_root / "__init__.py").is_file():
+            package_parts = (source_root.name, *package_parts)
+
+        for index in range(1, len(package_parts) + 1):
+            packages.add(".".join(package_parts[:index]))
+
+    return packages
+
+
+def _resolve_absolute_import(
+    source: str,
+    name: str,
+    module_names: set[str],
+    package_names: set[str],
+    line: int,
+) -> ImportReference:
+    target = _find_project_target(
+        name,
+        module_names,
+        package_names,
+    )
+
+    if target is not None:
+        resolution = "project"
+    elif name.split(".", 1)[0] in sys.stdlib_module_names:
+        resolution = "stdlib"
+    else:
+        resolution = "external_or_unresolved"
+
+    return ImportReference(
+        source,
+        line,
+        name,
+        resolution,
+        target,
+    )
+
+
+def _resolve_from_import(
+    source: str,
+    node: ast.ImportFrom,
+    module_names: set[str],
+    package_names: set[str],
+    package_context: str,
+) -> list[ImportReference]:
+    if node.level:
+        package_parts = (
+            package_context.split(".")
+            if package_context
+            else []
+        )
+
+        if node.level > len(package_parts):
+            return [
+                ImportReference(
+                    source,
+                    node.lineno,
+                    _format_import_from(node),
+                    "invalid_relative",
+                    None,
+                )
+            ]
+
+        base_parts = package_parts[
+            : len(package_parts) - node.level + 1
+        ]
+
+        if node.module:
+            base_parts.extend(node.module.split("."))
+
+        base = ".".join(base_parts)
+
+        if not base and not node.names:
+            return [
+                ImportReference(
+                    source,
+                    node.lineno,
+                    _format_import_from(node),
+                    "invalid_relative",
+                    None,
+                )
+            ]
+
+        references = []
+
+        for alias in node.names:
+            name = ".".join(
+                part for part in (base, alias.name) if part
+            )
+
+            candidate = name if base else alias.name
+
+            target = _find_project_target(
+                candidate,
+                module_names,
+                package_names,
+            )
+
+            if target is None:
+                target = _find_project_target(
+                    base,
+                    module_names,
+                    package_names,
+                )
+
+            resolution = (
+                "project"
+                if target is not None
+                else "unresolved_relative"
+            )
+
+            references.append(
+                ImportReference(
+                    source,
+                    node.lineno,
+                    name,
+                    resolution,
+                    target,
+                )
+            )
+
+        return references
+
+    base = node.module or ""
+
+    if not base:
+        return [
+            ImportReference(
+                source,
+                node.lineno,
+                _format_import_from(node),
+                "unresolved",
+                None,
+            )
+        ]
+
+    base_target = _find_project_target(
+        base,
+        module_names,
+        package_names,
+    )
+
+    references = []
+
+    for alias in node.names:
+        candidate = f"{base}.{alias.name}"
+
+        target = _find_project_target(
+            candidate,
+            module_names,
+            package_names,
+        )
+
+        if target is None:
+            target = base_target
+
+        if target is not None:
+            resolution = "project"
+        elif base.split(".", 1)[0] in sys.stdlib_module_names:
+            resolution = "stdlib"
+        else:
+            resolution = "external_or_unresolved"
+
+        references.append(
+            ImportReference(
+                source,
+                node.lineno,
+                candidate,
+                resolution,
+                target,
+            )
+        )
+
+    return references
+
+
+def _find_project_target(
+    name: str,
+    module_names: set[str],
+    package_names: set[str],
+) -> str | None:
+    if not name:
+        return None
+
+    if name in module_names or name in package_names:
+        return name
+
+    parts = name.split(".")
+
+    for end in range(len(parts) - 1, 0, -1):
+        prefix = ".".join(parts[:end])
+
+        if prefix in module_names or prefix in package_names:
+            return prefix
+
+    return None
+
+
+def _format_import_from(node: ast.ImportFrom) -> str:
+    dots = "." * node.level
+    module = node.module or ""
+    names = ", ".join(alias.name for alias in node.names)
+
+    return f"from {dots}{module} import {names}"
+
+
+def _is_dynamic_import(function: ast.expr) -> bool:
+    if isinstance(function, ast.Name):
+        return function.id == "__import__"
+
+    return (
+        isinstance(function, ast.Attribute)
+        and function.attr == "import_module"
+    )
+
+
+def _parse_target_version(value: str) -> tuple[int, int]:
+    if not isinstance(value, str):
+        raise ValueError(
+            "target_python must use MAJOR.MINOR format, such as 3.11"
+        )
+
+    parts = value.split(".")
+
+    if (
+        len(parts) != 2
+        or not all(part.isdigit() for part in parts)
+        or any(len(part) > 1 and part.startswith("0") for part in parts)
+    ):
+        raise ValueError(
+            "target_python must use MAJOR.MINOR format, such as 3.11"
+        )
+
+    major, minor = (int(part) for part in parts)
+
+    if (
+        major != 3
+        or not 11 <= minor <= sys.version_info.minor
+    ):
+        raise ValueError(
+            f"target Python must be between 3.11 and the running Python "
+            f"({sys.version_info.major}.{sys.version_info.minor})"
+        )
+
+    return major, minor
+
+
+def _supports_grammar(
+    source: str,
+    version: tuple[int, int],
+) -> bool:
+    try:
+        ast.parse(source, feature_version=version)
+    except SyntaxError:
+        return False
+
+    return True
+
+
+def analysis_to_dict(
+    analysis: ProjectAnalysis,
+) -> dict[str, object]:
+    """Convert project analysis to a JSON-compatible dictionary."""
+    return asdict(analysis)

bexar/analysis/statistics.py

@@ -0,0 +1,130 @@
+"""AST-based source statistics that never execute inspected code."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SourceStatistics:
+    """Counts of selected Python syntax constructs in one source file."""
+
+    source_bytes: int
+    lines: int
+    ast_nodes: int
+    functions: int
+    async_functions: int
+    classes: int
+    imports: int
+    relative_imports: int
+    string_literals: int
+    numeric_literals: int
+    dynamic_import_calls: int
+
+
+def collect_statistics(
+    tree: ast.AST,
+    *,
+    source_bytes: int,
+    source: str,
+) -> SourceStatistics:
+    """Count syntax constructs without compiling or executing source."""
+
+    if not isinstance(tree, ast.AST):
+        raise TypeError("tree must be an ast.AST instance")
+
+    if isinstance(source_bytes, bool) or not isinstance(source_bytes, int):
+        raise TypeError("source_bytes must be an integer")
+
+    if source_bytes < 0:
+        raise ValueError("source_bytes cannot be negative")
+
+    if not isinstance(source, str):
+        raise TypeError("source must be a string")
+
+    counts = {
+        "ast_nodes": 0,
+        "functions": 0,
+        "async_functions": 0,
+        "classes": 0,
+        "imports": 0,
+        "relative_imports": 0,
+        "string_literals": 0,
+        "numeric_literals": 0,
+        "dynamic_import_calls": 0,
+    }
+
+    for node in ast.walk(tree):
+        counts["ast_nodes"] += 1
+
+        if isinstance(node, ast.AsyncFunctionDef):
+            counts["functions"] += 1
+            counts["async_functions"] += 1
+
+        elif isinstance(node, ast.FunctionDef):
+            counts["functions"] += 1
+
+        elif isinstance(node, ast.ClassDef):
+            counts["classes"] += 1
+
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            counts["imports"] += 1
+
+            if isinstance(node, ast.ImportFrom) and node.level > 0:
+                counts["relative_imports"] += 1
+
+        elif isinstance(node, ast.Constant):
+            value = node.value
+
+            if isinstance(value, str):
+                counts["string_literals"] += 1
+
+            elif (
+                isinstance(value, (int, float, complex))
+                and not isinstance(value, bool)
+            ):
+                counts["numeric_literals"] += 1
+
+        if isinstance(node, ast.Call) and _is_dynamic_import(node.func):
+            counts["dynamic_import_calls"] += 1
+
+    return SourceStatistics(
+        source_bytes=source_bytes,
+        lines=_count_lines(source),
+        **counts,
+    )
+
+
+def _count_lines(source: str) -> int:
+    """Count physical lines without allocating a list."""
+
+    if not source:
+        return 0
+
+    line_breaks = (
+        source.count("\n")
+        + source.count("\r")
+        - source.count("\r\n")
+    )
+
+    if not source.endswith(("\n", "\r")):
+        line_breaks += 1
+
+    return line_breaks
+
+
+def _is_dynamic_import(function: ast.expr) -> bool:
+    """Recognize common dynamic-import call expressions."""
+
+    if isinstance(function, ast.Name):
+        return function.id == "__import__"
+
+    if isinstance(function, ast.Attribute):
+        return (
+            function.attr == "import_module"
+            and isinstance(function.value, ast.Name)
+            and function.value.id == "importlib"
+        )
+
+    return False