serenecode 0.1.0__py3-none-any.whl

serenecode/checker/coverage.py

@@ -0,0 +1,186 @@
+"""Coverage analysis checker for Serenecode (Level 3).
+
+This module implements Level 3 verification: it transforms results from
+coverage analysis backends into structured CheckResult objects.
+The actual analysis is delegated to adapters.
+
+This is a core module — no I/O operations are permitted. Coverage
+results are received as structured data, not generated here.
+"""
+
+from __future__ import annotations
+
+import icontract
+
+from serenecode.models import (
+    CheckResult,
+    CheckStatus,
+    Detail,
+    FunctionResult,
+    VerificationLevel,
+    make_check_result,
+)
+from serenecode.ports.coverage_analyzer import CoverageFinding
+
+
+@icontract.require(
+    lambda findings: isinstance(findings, list),
+    "findings must be a list",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, CheckResult),
+    "result must be a CheckResult",
+)
+@icontract.ensure(
+    lambda findings, result: len(result.results) == len(findings),
+    "output count must match input findings count",
+)
+def transform_coverage_results(
+    findings: list[CoverageFinding],
+    file_path: str,
+    duration_seconds: float,
+) -> CheckResult:
+    """Transform coverage analysis findings into a CheckResult.
+
+    Maps each CoverageFinding to a FunctionResult with appropriate
+    status and detailed suggestions for uncovered paths.
+
+    Args:
+        findings: List of coverage findings from an analysis adapter.
+        file_path: Source file path for reporting.
+        duration_seconds: How long the analysis took.
+
+    Returns:
+        A CheckResult containing all coverage analysis results.
+    """
+    func_results: list[FunctionResult] = []
+
+    # Loop invariant: func_results contains transformed results for findings[0..i]
+    for finding in findings:
+        details: list[Detail] = []
+        status: CheckStatus
+        level_achieved: int
+
+        if finding.meets_threshold:
+            status = CheckStatus.PASSED
+            level_achieved = 3
+            details.append(Detail(
+                level=VerificationLevel.COVERAGE,
+                tool="coverage",
+                finding_type="sufficient_coverage",
+                message=finding.message,
+            ))
+        else:
+            status = CheckStatus.FAILED
+            level_achieved = 2
+            details.append(Detail(
+                level=VerificationLevel.COVERAGE,
+                tool="coverage",
+                finding_type="insufficient_coverage",
+                message=finding.message,
+                suggestion=_build_suggestion(finding),
+            ))
+
+        func_results.append(FunctionResult(
+            function=finding.function_name,
+            file=file_path,
+            line=finding.line_start,
+            level_requested=3,
+            level_achieved=level_achieved,
+            status=status,
+            details=tuple(details),
+        ))
+
+    return make_check_result(
+        tuple(func_results),
+        level_requested=3,
+        duration_seconds=duration_seconds,
+    )
+
+
+@icontract.require(
+    lambda finding: isinstance(finding, CoverageFinding),
+    "finding must be a CoverageFinding",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str) and len(result) > 0,
+    "result must be a non-empty string",
+)
+def _build_suggestion(finding: CoverageFinding) -> str:
+    """Build an agent-friendly suggestion string from a coverage finding.
+
+    Args:
+        finding: The coverage finding to generate a suggestion for.
+
+    Returns:
+        A detailed suggestion string with coverage info and test suggestions.
+    """
+    parts: list[str] = []
+    parts.append(
+        f"Coverage: {finding.line_coverage_percent:.0f}% lines, "
+        f"{finding.branch_coverage_percent:.0f}% branches. "
+        f"Uncovered lines: {_format_line_ranges(finding.uncovered_lines)}."
+    )
+
+    # Loop invariant: parts contains formatted info for suggestions[0..i]
+    for suggestion in finding.suggestions:
+        parts.append(f"\nSuggested test ({suggestion.description}):")
+        parts.append(suggestion.suggested_test_code)
+        if suggestion.required_mocks:
+            mock_parts: list[str] = []
+            # Loop invariant: mock_parts contains assessments for mocks[0..j]
+            for mock in suggestion.required_mocks:
+                necessity = (
+                    "REQUIRED — external I/O"
+                    if mock.mock_necessary
+                    else "OPTIONAL — internal code, consider using real implementation"
+                )
+                mock_parts.append(f"  - mock {mock.name} ({mock.import_module}): {necessity} ({mock.reason})")
+            parts.append("Mock assessment:\n" + "\n".join(mock_parts))
+        else:
+            parts.append("No mocks needed — test can use real implementations.")
+
+    return "\n".join(parts)
+
+
+@icontract.require(
+    lambda lines: isinstance(lines, tuple)
+    and all(isinstance(l, int) and l >= 1 for l in lines),
+    "lines must be a tuple of positive integers",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str) and len(result) > 0,
+    "result must be a non-empty string",
+)
+@icontract.ensure(
+    lambda lines, result: result == "none" if not lines else len(result) > 0,
+    "empty input produces 'none', non-empty input produces non-empty output",
+)
+def _format_line_ranges(lines: tuple[int, ...]) -> str:
+    """Format a tuple of line numbers into compact ranges.
+
+    Args:
+        lines: Tuple of positive line numbers (need not be sorted).
+
+    Returns:
+        A string like "5-8, 12, 15-20".
+    """
+    if not lines:
+        return "none"
+    sorted_lines = sorted(lines)
+    ranges: list[str] = []
+    start = sorted_lines[0]
+    end = start
+
+    # Loop invariant: [start..end] is the current contiguous range,
+    # ranges contains all completed ranges before sorted_lines[i]
+    for line in sorted_lines[1:]:
+        if line == end + 1:
+            end = line
+        else:
+            ranges.append(f"{start}-{end}" if start != end else str(start))
+            start = line
+            end = line
+    ranges.append(f"{start}-{end}" if start != end else str(start))
+
+    return ", ".join(ranges)

serenecode/checker/properties.py

@@ -0,0 +1,154 @@
+"""Property-based testing checker for Serenecode (Level 3).
+
+This module implements Level 3 verification: it transforms results from
+property-based testing backends into structured CheckResult objects.
+The actual test execution is delegated to adapters.
+
+This is a core module — no I/O operations are permitted. Test results
+are received as structured data, not generated here.
+"""
+
+from __future__ import annotations
+
+import icontract
+
+from serenecode.models import (
+    CheckResult,
+    CheckStatus,
+    Detail,
+    FunctionResult,
+    VerificationLevel,
+    make_check_result,
+)
+from serenecode.ports.property_tester import PropertyFinding
+
+
+@icontract.require(
+    lambda findings: isinstance(findings, list),
+    "findings must be a list",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, CheckResult),
+    "result must be a CheckResult",
+)
+def transform_property_results(
+    findings: list[PropertyFinding],
+    file_path: str,
+    duration_seconds: float,
+) -> CheckResult:
+    """Transform property-based testing findings into a CheckResult.
+
+    Maps each PropertyFinding to a FunctionResult with appropriate
+    status and detail information including counterexamples.
+
+    Args:
+        findings: List of property findings from a testing adapter.
+        file_path: Source file path for reporting.
+        duration_seconds: How long the testing took.
+
+    Returns:
+        A CheckResult containing all property testing results.
+    """
+    func_results: list[FunctionResult] = []
+
+    # Loop invariant: func_results contains transformed results for findings[0..i]
+    for finding in findings:
+        details: list[Detail] = []
+        status: CheckStatus
+        level_achieved: int
+
+        if finding.passed and finding.finding_type == "verified":
+            status = CheckStatus.PASSED
+            level_achieved = 4
+            details.append(Detail(
+                level=VerificationLevel.PROPERTIES,
+                tool="hypothesis",
+                finding_type="verified",
+                message=finding.message,
+            ))
+        elif finding.passed and finding.finding_type == "excluded":
+            # Filter-excluded functions are visible but don't block passing.
+            status = CheckStatus.EXEMPT
+            level_achieved = 3
+            details.append(Detail(
+                level=VerificationLevel.PROPERTIES,
+                tool="hypothesis",
+                finding_type=finding.finding_type,
+                message=finding.message,
+            ))
+        elif finding.passed:
+            status = CheckStatus.SKIPPED
+            level_achieved = 3
+            details.append(Detail(
+                level=VerificationLevel.PROPERTIES,
+                tool="hypothesis",
+                finding_type=finding.finding_type,
+                message=finding.message,
+            ))
+        else:
+            status = CheckStatus.FAILED
+            level_achieved = 3
+            detail = Detail(
+                level=VerificationLevel.PROPERTIES,
+                tool="hypothesis",
+                finding_type=finding.finding_type,
+                message=finding.message,
+                counterexample=finding.counterexample,
+                suggestion=_suggest_fix(finding),
+            )
+            details.append(detail)
+
+        func_results.append(FunctionResult(
+            function=finding.function_name,
+            file=file_path,
+            line=1,  # line info not available from property testing
+            level_requested=4,
+            level_achieved=level_achieved,
+            status=status,
+            details=tuple(details),
+        ))
+
+    return make_check_result(
+        tuple(func_results),
+        level_requested=4,
+        duration_seconds=duration_seconds,
+    )
+
+
+@icontract.require(
+    lambda finding: isinstance(finding, PropertyFinding),
+    "finding must be a PropertyFinding",
+)
+@icontract.ensure(
+    lambda result: result is None or isinstance(result, str),
+    "result must be None or a string",
+)
+def _suggest_fix(finding: PropertyFinding) -> str | None:
+    """Generate a fix suggestion from a property finding.
+
+    Args:
+        finding: The property finding to generate a suggestion for.
+
+    Returns:
+        A suggestion string, or None if no suggestion can be generated.
+    """
+    if finding.finding_type == "postcondition_violated":
+        if finding.counterexample is not None and isinstance(finding.counterexample, dict) and finding.counterexample:
+            inputs = ", ".join(f"{k}={v}" for k, v in finding.counterexample.items())
+            return (
+                f"Postcondition violated with inputs: {inputs}. "
+                "To fix: (1) if these inputs are invalid, add a @icontract.require "
+                "precondition to exclude them; (2) if these inputs are valid, fix the "
+                "implementation so the postcondition holds"
+            )
+        return (
+            "Postcondition violated. Read the function's @icontract.ensure decorators "
+            "and fix the implementation to satisfy them, or narrow inputs with @icontract.require"
+        )
+    elif finding.finding_type == "crash":
+        return (
+            f"Function crashed with {finding.exception_type}: {finding.exception_message}. "
+            "To fix: (1) add a @icontract.require precondition to reject inputs that "
+            "cause this crash, or (2) handle the edge case in the implementation"
+        )
+    return None