serenecode 0.1.0__py3-none-any.whl

serenecode/ports/coverage_analyzer.py

@@ -0,0 +1,124 @@
+"""Port definition for coverage analysis (Level 3).
+
+This module defines the Protocol interface for coverage analysis
+backends using coverage.py. The checker module depends on this
+protocol rather than concrete implementations.
+
+This is a ports module — no implementations, only abstract contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import icontract
+
+from serenecode.contracts.predicates import is_non_empty_string
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.name),
+    "dependency name must be non-empty",
+)
+@dataclass(frozen=True)
+class MockDependency:
+    """A dependency that must be mocked for a test to reach uncovered code.
+
+    Represents a call target found via AST analysis in an uncovered path.
+    """
+
+    name: str
+    import_module: str
+    is_external: bool
+    mock_necessary: bool
+    reason: str
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.description),
+    "test suggestion description must be non-empty",
+)
+@dataclass(frozen=True)
+class TestSuggestion:
+    """A suggested test to cover an uncovered code path.
+
+    Includes the mock setup code needed and whether each mock
+    could be replaced with a real implementation.
+    """
+
+    description: str
+    target_lines: tuple[int, ...]
+    suggested_test_code: str
+    required_mocks: tuple[MockDependency, ...]
+    all_mocks_necessary: bool
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.function_name)
+    and is_non_empty_string(self.module_path),
+    "finding names must be non-empty",
+)
+@icontract.invariant(
+    lambda self: 0.0 <= self.line_coverage_percent <= 100.0,
+    "line coverage must be a valid percentage",
+)
+@icontract.invariant(
+    lambda self: 0.0 <= self.branch_coverage_percent <= 100.0,
+    "branch coverage must be a valid percentage",
+)
+@dataclass(frozen=True)
+class CoverageFinding:
+    """A coverage analysis finding for a single function.
+
+    Contains coverage metrics, uncovered locations, test suggestions
+    with mock assessments, and the threshold pass/fail determination.
+    """
+
+    function_name: str
+    module_path: str
+    line_start: int
+    line_end: int
+    line_coverage_percent: float
+    branch_coverage_percent: float
+    uncovered_lines: tuple[int, ...]
+    uncovered_branches: tuple[tuple[int, int], ...]
+    suggestions: tuple[TestSuggestion, ...]
+    meets_threshold: bool
+    message: str
+
+
+# Protocol classes are exempt from @icontract.invariant — see ports/file_system.py.
+class CoverageAnalyzer(Protocol):
+    """Port for coverage analysis.
+
+    Implementations use coverage.py and AST analysis to measure
+    test coverage per function and generate test suggestions for
+    uncovered paths.
+    """
+
+    @icontract.require(
+        lambda module_path: is_non_empty_string(module_path),
+        "module_path must be a non-empty string",
+    )
+    @icontract.ensure(
+        lambda result: isinstance(result, list),
+        "result must be a list",
+    )
+    def analyze_module(
+        self,
+        module_path: str,
+        search_paths: tuple[str, ...] = (),
+        coverage_threshold: float = 80.0,
+    ) -> list[CoverageFinding]:
+        """Run coverage analysis on all functions in a module.
+
+        Args:
+            module_path: Importable Python module path to analyze.
+            search_paths: sys.path roots needed to import the module.
+            coverage_threshold: Minimum coverage percentage to pass.
+
+        Returns:
+            List of coverage findings per function.
+        """
+        ...

serenecode/ports/file_system.py

@@ -0,0 +1,95 @@
+"""Port definitions for file system operations.
+
+This module defines the Protocol interfaces for reading and writing
+files. Core modules depend on these protocols rather than concrete
+file system implementations, enabling dependency injection and
+testability.
+
+This is a ports module — no implementations, only abstract contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import icontract
+
+
+# Protocol classes are exempt from @icontract.invariant because invariants
+# are not inherited by Protocol implementors — they would only fire on the
+# Protocol itself, which is never instantiated directly.
+class FileReader(Protocol):
+    """Port for reading file contents.
+
+    Implementations must handle encoding and raise domain exceptions
+    for file system errors.
+    """
+
+    @icontract.require(lambda path: isinstance(path, str), "path must be a string")
+    @icontract.ensure(lambda result: isinstance(result, str), "result must be a string")
+    def read_file(self, path: str) -> str:
+        """Read a file and return its contents as a UTF-8 string.
+
+        Args:
+            path: Path to the file to read.
+
+        Returns:
+            The full file contents as a string.
+        """
+        ...
+
+    @icontract.require(lambda path: isinstance(path, str), "path must be a string")
+    @icontract.ensure(lambda result: isinstance(result, bool), "result must be a bool")
+    def file_exists(self, path: str) -> bool:
+        """Check whether a file exists at the given path.
+
+        Args:
+            path: Path to check.
+
+        Returns:
+            True if a file exists at path.
+        """
+        ...
+
+    @icontract.require(lambda directory: isinstance(directory, str), "directory must be a string")
+    @icontract.ensure(lambda result: isinstance(result, list), "result must be a list")
+    def list_python_files(self, directory: str) -> list[str]:
+        """List all Python (.py) files in a directory recursively.
+
+        Args:
+            directory: Root directory to search.
+
+        Returns:
+            List of absolute or relative paths to .py files.
+        """
+        ...
+
+
+class FileWriter(Protocol):
+    """Port for writing file contents.
+
+    Implementations must handle encoding and raise domain exceptions
+    for file system errors.
+    """
+
+    @icontract.require(lambda path: isinstance(path, str), "path must be a string")
+    @icontract.require(lambda content: isinstance(content, str), "content must be a string")
+    @icontract.ensure(lambda result: result is None, "result must be None")
+    def write_file(self, path: str, content: str) -> None:
+        """Write content to a file, creating it if it doesn't exist.
+
+        Args:
+            path: Path to the file to write.
+            content: Content to write as UTF-8.
+        """
+        ...
+
+    @icontract.require(lambda path: isinstance(path, str), "path must be a string")
+    @icontract.ensure(lambda result: result is None, "result must be None")
+    def ensure_directory(self, path: str) -> None:
+        """Ensure a directory exists, creating it if necessary.
+
+        Args:
+            path: Path to the directory.
+        """
+        ...

serenecode/ports/property_tester.py

@@ -0,0 +1,69 @@
+"""Port definition for property-based testing (Level 3).
+
+This module defines the Protocol interface for property-based testing
+backends such as Hypothesis. The checker module depends on this
+protocol rather than concrete implementations.
+
+This is a ports module — no implementations, only abstract contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import icontract
+
+from serenecode.contracts.predicates import is_non_empty_string
+
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.function_name) and is_non_empty_string(self.module_path),
+    "finding names must be non-empty",
+)
+@dataclass(frozen=True)
+class PropertyFinding:
+    """A single finding from property-based testing.
+
+    Represents either a successful verification or a counterexample
+    that violates a postcondition.
+    """
+
+    function_name: str
+    module_path: str
+    passed: bool
+    finding_type: str  # "postcondition_violated", "precondition_error", "crash", "verified"
+    message: str
+    counterexample: dict[str, object] | None = None
+    exception_type: str | None = None
+    exception_message: str | None = None
+
+
+# Protocol classes are exempt from @icontract.invariant — see ports/file_system.py.
+class PropertyTester(Protocol):
+    """Port for property-based testing.
+
+    Implementations use Hypothesis (or similar) to generate test inputs
+    from function contracts and verify postconditions hold.
+    """
+
+    @icontract.require(lambda module_path: is_non_empty_string(module_path), "module_path must be a non-empty string")
+    @icontract.ensure(lambda result: isinstance(result, list), "result must be a list")
+    def test_module(
+        self,
+        module_path: str,
+        max_examples: int | None = None,
+        search_paths: tuple[str, ...] = (),
+    ) -> list[PropertyFinding]:
+        """Run property-based tests on all contracted functions in a module.
+
+        Args:
+            module_path: Importable Python module path to test.
+            max_examples: Maximum number of test examples per function.
+            search_paths: sys.path roots needed to import the module.
+
+        Returns:
+            List of property findings.
+        """
+        ...

serenecode/ports/symbolic_checker.py

@@ -0,0 +1,70 @@
+"""Port definition for symbolic verification (Level 4).
+
+This module defines the Protocol interface for symbolic execution
+backends such as CrossHair. The checker module depends on this
+protocol rather than concrete implementations.
+
+This is a ports module — no implementations, only abstract contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import icontract
+
+from serenecode.contracts.predicates import is_non_empty_string
+
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.function_name) and is_non_empty_string(self.module_path),
+    "finding names must be non-empty",
+)
+@dataclass(frozen=True)
+class SymbolicFinding:
+    """A single finding from symbolic verification.
+
+    Represents one of three outcomes: verified (proven correct),
+    counterexample (violation found), or unknown (timeout/unsupported).
+    """
+
+    function_name: str
+    module_path: str
+    outcome: str  # "verified", "counterexample", "timeout", "unsupported", "error"
+    message: str
+    counterexample: dict[str, object] | None = None
+    condition: str | None = None  # which postcondition was violated
+    duration_seconds: float = 0.0
+
+
+# Protocol classes are exempt from @icontract.invariant — see ports/file_system.py.
+class SymbolicChecker(Protocol):
+    """Port for symbolic verification.
+
+    Implementations use CrossHair/Z3 (or similar) to symbolically
+    execute functions and prove contracts hold for all valid inputs.
+    """
+
+    @icontract.require(lambda module_path: is_non_empty_string(module_path), "module_path must be a non-empty string")
+    @icontract.ensure(lambda result: isinstance(result, list), "result must be a list")
+    def verify_module(
+        self,
+        module_path: str,
+        per_condition_timeout: int | None = None,
+        per_path_timeout: int | None = None,
+        search_paths: tuple[str, ...] = (),
+    ) -> list[SymbolicFinding]:
+        """Run symbolic verification on all contracted functions in a module.
+
+        Args:
+            module_path: Importable Python module path to verify.
+            per_condition_timeout: Max seconds per postcondition.
+            per_path_timeout: Max seconds per execution path.
+            search_paths: sys.path roots needed to import the module.
+
+        Returns:
+            List of symbolic findings.
+        """
+        ...

serenecode/ports/type_checker.py

@@ -0,0 +1,66 @@
+"""Port definition for type checking (Level 2).
+
+This module defines the Protocol interface for static type analysis
+backends such as mypy. The checker module depends on this protocol
+rather than concrete implementations.
+
+This is a ports module — no implementations, only abstract contracts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import icontract
+
+from serenecode.contracts.predicates import is_non_empty_string
+
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.file) and self.line >= 0 and self.column >= 0,
+    "type issues must reference a file and non-negative position",
+)
+@dataclass(frozen=True)
+class TypeIssue:
+    """A single type checking issue reported by a backend like mypy.
+
+    Represents one error, warning, or note from the type checker.
+    """
+
+    file: str
+    line: int
+    column: int
+    severity: str  # "error", "warning", "note"
+    message: str
+    code: str | None = None  # e.g. "arg-type", "return-value"
+
+
+# Protocol classes are exempt from @icontract.invariant — see ports/file_system.py.
+class TypeChecker(Protocol):
+    """Port for static type checking.
+
+    Implementations run a type checker (e.g. mypy) on source files
+    and return structured issue reports.
+    """
+
+    @icontract.require(lambda file_paths: isinstance(file_paths, list), "file_paths must be a list")
+    @icontract.ensure(lambda result: isinstance(result, list), "result must be a list")
+    def check(
+        self,
+        file_paths: list[str],
+        strict: bool = True,
+        search_paths: tuple[str, ...] = (),
+    ) -> list[TypeIssue]:
+        """Run type checking on the given files.
+
+        Args:
+            file_paths: Paths to Python files to check.
+            strict: Whether to use strict mode.
+            search_paths: Import roots needed to resolve local modules.
+
+        Returns:
+            List of type issues found.
+        """
+        ...