serenecode 0.1.0__py3-none-any.whl

serenecode/init.py

@@ -0,0 +1,307 @@
+"""Project initialization logic for Serenecode.
+
+This module handles the `serenecode init` command logic. It generates
+SERENECODE.md and CLAUDE.md files from templates and manages the
+initialization workflow.
+
+Core logic functions are pure (no I/O). The initialize_project
+orchestrator uses ports for file system access.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import icontract
+
+from serenecode.contracts.predicates import is_valid_template_name
+from serenecode.ports.file_system import FileReader, FileWriter
+
+# ---------------------------------------------------------------------------
+# SERENECODE.md template content (embedded as string constants)
+# ---------------------------------------------------------------------------
+
+_CLAUDE_MD_SECTIONS = {
+    "default": """\
+## Serenecode
+
+All code in this project MUST follow the standards defined in SERENECODE.md. \
+Read SERENECODE.md before writing or modifying any code. Every public function \
+with caller-supplied inputs must have icontract preconditions, and every \
+public function must have postconditions. Every class must have invariants. \
+Follow the architectural patterns specified in SERENECODE.md.
+
+### Verification
+
+After each work iteration (implementing a feature, fixing a bug, refactoring), \
+offer to run verification before considering the task complete.
+
+**Quick structural check (seconds):**
+```bash
+serenecode check src/ --structural
+```
+
+**Full verification with property testing (minutes):**
+```bash
+serenecode check src/ --level 4 --allow-code-execution
+```
+
+**Generate an HTML report:**
+```bash
+serenecode report src/ --format html --output report.html --allow-code-execution
+```
+
+Levels 3-6 import and execute project modules. Only use \
+`--allow-code-execution` for trusted code.
+
+If verification fails, read the error messages and fix the issues. Each failure \
+includes the function name, file, line number, and a suggested fix. Iterate \
+until all checks pass.
+""",
+    "strict": """\
+## Serenecode (Strict Mode)
+
+All code in this project MUST follow the standards defined in SERENECODE.md. \
+Read SERENECODE.md before writing or modifying any code. Every function — \
+public and private — with caller-supplied inputs must have icontract \
+preconditions, and every function must have postconditions. Every class must \
+have invariants. No exemptions.
+
+### Verification
+
+After each work iteration (implementing a feature, fixing a bug, refactoring), \
+you MUST run verification before considering the task complete. Do not skip this.
+
+**Quick structural check (seconds):**
+```bash
+serenecode check src/ --structural
+```
+
+**Full verification with property testing (minutes):**
+```bash
+serenecode check src/ --level 4 --allow-code-execution
+```
+
+**Full verification including symbolic and compositional (minutes):**
+```bash
+serenecode check src/ --level 6 --allow-code-execution
+```
+
+**Generate an HTML report:**
+```bash
+serenecode report src/ --format html --output report.html --allow-code-execution
+```
+
+Levels 3-6 import and execute project modules. Only use \
+`--allow-code-execution` for trusted code.
+
+If verification fails, read the error messages and fix the issues. Each failure \
+includes the function name, file, line number, and a suggested fix. Iterate \
+until all checks pass. Do not commit code that fails verification.
+""",
+    "minimal": """\
+## Serenecode
+
+All code in this project should follow the conventions in SERENECODE.md. \
+Public functions with caller-supplied inputs must have icontract \
+preconditions, and public functions should have postconditions.
+
+### Verification
+
+After completing a feature or fix, consider running a quick check:
+
+```bash
+serenecode check src/ --structural
+```
+
+If issues are found, fix them before moving on.
+""",
+}
+
+
+# ---------------------------------------------------------------------------
+# Result dataclass
+# ---------------------------------------------------------------------------
+
+
+@icontract.invariant(
+    lambda self: not (self.claude_md_created and self.claude_md_updated),
+    "CLAUDE.md cannot be both created and updated in the same operation",
+)
+@dataclass(frozen=True)
+class InitResult:
+    """Result of project initialization.
+
+    Indicates which files were created or updated during init.
+    """
+
+    serenecode_md_created: bool
+    claude_md_created: bool
+    claude_md_updated: bool
+    template_used: str
+
+
+# ---------------------------------------------------------------------------
+# Pure functions
+# ---------------------------------------------------------------------------
+
+
+@icontract.require(
+    lambda template: is_valid_template_name(template),
+    "template must be a valid template name",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str) and len(result) > 0,
+    "result must be a non-empty string",
+)
+def generate_serenecode_md(template: str) -> str:
+    """Return the SERENECODE.md content for the given template name.
+
+    Args:
+        template: One of 'default', 'strict', or 'minimal'.
+
+    Returns:
+        The SERENECODE.md markdown content.
+    """
+    from serenecode.templates import content as template_content
+
+    return template_content.get_template(template)
+
+
+@icontract.require(
+    lambda template: is_valid_template_name(template),
+    "template must be a valid template name",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str) and len(result) > 0,
+    "result must be a non-empty string",
+)
+def generate_claude_md_section(template: str = "default") -> str:
+    """Return the Serenecode directive section for CLAUDE.md.
+
+    The section content varies by template — strict mode uses stronger
+    language and requires verification before commits.
+
+    Args:
+        template: The template name ('default', 'strict', or 'minimal').
+
+    Returns:
+        The markdown section to add to CLAUDE.md.
+    """
+    return _CLAUDE_MD_SECTIONS[template]
+
+
+@icontract.require(
+    lambda serenecode_section: isinstance(serenecode_section, str) and len(serenecode_section) > 0,
+    "serenecode_section must be a non-empty string",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str),
+    "result must be a string",
+)
+def merge_claude_md(existing_content: str | None, serenecode_section: str) -> str:
+    """Merge the Serenecode section into existing CLAUDE.md content.
+
+    If the existing content already contains "## Serenecode", do not
+    add a duplicate. Otherwise, append the section.
+
+    Args:
+        existing_content: Current CLAUDE.md content, or None if no file exists.
+        serenecode_section: The Serenecode directive section to add.
+
+    Returns:
+        The merged CLAUDE.md content.
+    """
+    if existing_content is None:
+        return serenecode_section
+
+    if "## Serenecode" in existing_content:
+        return existing_content
+
+    return existing_content.rstrip() + "\n\n" + serenecode_section
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator (uses ports)
+# ---------------------------------------------------------------------------
+
+
+@icontract.require(
+    lambda template: is_valid_template_name(template),
+    "template must be a valid template name",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, InitResult),
+    "result must be an InitResult",
+)
+def initialize_project(
+    directory: str,
+    template: str,
+    file_reader: FileReader,
+    file_writer: FileWriter,
+    confirm_callback: Callable[[str], bool] | None = None,
+) -> InitResult:
+    """Initialize a Serenecode project in the given directory.
+
+    Creates SERENECODE.md from the selected template and sets up
+    CLAUDE.md with the Serenecode directive.
+
+    Args:
+        directory: Project root directory path.
+        template: Template name ('default', 'strict', or 'minimal').
+        file_reader: A FileReader implementation.
+        file_writer: A FileWriter implementation.
+        confirm_callback: Optional callback for user confirmation prompts.
+            If None, proceeds without confirmation.
+
+    Returns:
+        An InitResult describing what was created/modified.
+    """
+    import os
+
+    serenecode_path = os.path.join(directory, "SERENECODE.md")
+    claude_path = os.path.join(directory, "CLAUDE.md")
+
+    serenecode_md_created = False
+    claude_md_created = False
+    claude_md_updated = False
+
+    # Generate and write SERENECODE.md
+    serenecode_exists = file_reader.file_exists(serenecode_path)
+    should_write_serenecode = True
+    if serenecode_exists and confirm_callback is not None:
+        should_write_serenecode = confirm_callback(
+            "SERENECODE.md already exists. Overwrite?"
+        )
+
+    if should_write_serenecode:
+        content = generate_serenecode_md(template)
+        file_writer.write_file(serenecode_path, content)
+        serenecode_md_created = True
+
+    # Generate and write/update CLAUDE.md
+    claude_section = generate_claude_md_section(template)
+    claude_exists = file_reader.file_exists(claude_path)
+    if claude_exists:
+        existing = file_reader.read_file(claude_path)
+        if "## Serenecode" not in existing:
+            should_update = True
+            if confirm_callback is not None:
+                should_update = confirm_callback(
+                    "Add Serenecode directive to existing CLAUDE.md?"
+                )
+            if should_update:
+                merged = merge_claude_md(existing, claude_section)
+                file_writer.write_file(claude_path, merged)
+                claude_md_updated = True
+    else:
+        file_writer.write_file(claude_path, claude_section)
+        claude_md_created = True
+
+    return InitResult(
+        serenecode_md_created=serenecode_md_created,
+        claude_md_created=claude_md_created,
+        claude_md_updated=claude_md_updated,
+        template_used=template,
+    )

serenecode/models.py

@@ -0,0 +1,308 @@
+"""Data models for Serenecode verification results.
+
+This module defines the core data structures used throughout Serenecode
+to represent verification results. All models are frozen dataclasses
+with icontract invariants to enforce correctness.
+
+This is a core module — no I/O imports are permitted.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
+
+import icontract
+
+from serenecode.contracts.predicates import is_non_empty_string, is_non_negative_int
+
+
+class VerificationLevel(Enum):
+    """Verification levels in the Serenecode pipeline."""
+
+    STRUCTURAL = 1
+    TYPES = 2
+    COVERAGE = 3
+    PROPERTIES = 4
+    SYMBOLIC = 5
+    COMPOSITIONAL = 6
+
+
+class CheckStatus(Enum):
+    """Status of a verification check."""
+
+    PASSED = "passed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    EXEMPT = "exempt"
+
+
+class ExitCode(IntEnum):
+    """Exit codes for the Serenecode CLI."""
+
+    PASSED = 0
+    STRUCTURAL = 1
+    TYPES = 2
+    COVERAGE = 3
+    PROPERTIES = 4
+    SYMBOLIC = 5
+    COMPOSITIONAL = 6
+    INTERNAL = 10
+
+
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.message),
+    "message must be a non-empty string",
+)
+@dataclass(frozen=True)
+class Detail:
+    """A single verification finding.
+
+    Represents one specific issue or confirmation found during
+    verification at a particular level.
+    """
+
+    level: VerificationLevel
+    tool: str
+    finding_type: str
+    message: str
+    counterexample: dict[str, object] | None = None
+    suggestion: str | None = None
+
+    @icontract.ensure(
+        lambda result: isinstance(result, dict),
+        "result must be a dictionary",
+    )
+    def to_dict(self) -> dict[str, object]:
+        """Convert to a plain dictionary for serialization."""
+        result: dict[str, object] = {
+            "level": self.level.value,
+            "tool": self.tool,
+            "type": self.finding_type,
+            "message": self.message,
+        }
+        if self.counterexample is not None:
+            result["counterexample"] = self.counterexample
+        if self.suggestion is not None:
+            result["suggestion"] = self.suggestion
+        return result
+
+
+@icontract.invariant(
+    lambda self: self.line >= 1,
+    "line number must be at least 1",
+)
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.function),
+    "function name must be non-empty",
+)
+@icontract.invariant(
+    lambda self: is_non_empty_string(self.file),
+    "file path must be non-empty",
+)
+@dataclass(frozen=True)
+class FunctionResult:
+    """Verification result for a single function.
+
+    Aggregates all findings across verification levels for one function.
+    """
+
+    function: str
+    file: str
+    line: int
+    level_requested: int
+    level_achieved: int
+    status: CheckStatus
+    details: tuple[Detail, ...] = ()
+
+    @icontract.ensure(
+        lambda result: isinstance(result, dict),
+        "result must be a dictionary",
+    )
+    def to_dict(self) -> dict[str, object]:
+        """Convert to a plain dictionary matching the JSON output spec."""
+        return {
+            "function": self.function,
+            "file": self.file,
+            "line": self.line,
+            "level_requested": self.level_requested,
+            "level_achieved": self.level_achieved,
+            "status": self.status.value,
+            "details": [d.to_dict() for d in self.details],
+        }
+
+
+@icontract.invariant(
+    lambda self: is_non_negative_int(self.total_functions),
+    "total_functions must be non-negative",
+)
+@icontract.invariant(
+    lambda self: is_non_negative_int(self.passed_count),
+    "passed_count must be non-negative",
+)
+@icontract.invariant(
+    lambda self: is_non_negative_int(self.failed_count),
+    "failed_count must be non-negative",
+)
+@icontract.invariant(
+    lambda self: is_non_negative_int(self.skipped_count),
+    "skipped_count must be non-negative",
+)
+@icontract.invariant(
+    lambda self: is_non_negative_int(self.exempt_count),
+    "exempt_count must be non-negative",
+)
+@icontract.invariant(
+    lambda self: self.total_functions == self.passed_count + self.failed_count + self.skipped_count + self.exempt_count,
+    "counts must sum to total",
+)
+@dataclass(frozen=True)
+class CheckSummary:
+    """Summary statistics for a verification run."""
+
+    total_functions: int
+    passed_count: int
+    failed_count: int
+    skipped_count: int
+    exempt_count: int = 0
+    duration_seconds: float = 0.0
+
+    @icontract.ensure(
+        lambda result: isinstance(result, dict),
+        "result must be a dictionary",
+    )
+    def to_dict(self) -> dict[str, object]:
+        """Convert to the summary dict matching the JSON output spec."""
+        return {
+            "total_functions": self.total_functions,
+            "passed": self.passed_count,
+            "failed": self.failed_count,
+            "skipped": self.skipped_count,
+            "exempt": self.exempt_count,
+        }
+
+
+@icontract.invariant(
+    lambda self: self.level_achieved <= self.level_requested,
+    "level_achieved must not exceed level_requested",
+)
+@dataclass(frozen=True)
+class CheckResult:
+    """Complete result of a verification run.
+
+    Contains the overall pass/fail status, all per-function results,
+    and summary statistics.
+    """
+
+    passed: bool
+    level_requested: int
+    level_achieved: int
+    results: tuple[FunctionResult, ...]
+    summary: CheckSummary
+    version: str = "0.1.0"
+
+    @property
+    def failures(self) -> list[FunctionResult]:
+        """Return only the failed function results."""
+        # Loop invariant: accumulated list contains only FAILED results seen so far
+        return [r for r in self.results if r.status == CheckStatus.FAILED]
+
+    @icontract.ensure(
+        lambda result: isinstance(result, dict),
+        "result must be a dictionary",
+    )
+    def to_dict(self) -> dict[str, object]:
+        """Convert to a plain dictionary matching the JSON output spec."""
+        return {
+            "version": self.version,
+            "passed": self.passed,
+            "level_requested": self.level_requested,
+            "level_achieved": self.level_achieved,
+            "summary": self.summary.to_dict(),
+            "results": [r.to_dict() for r in self.results],
+        }
+
+    @icontract.ensure(
+        lambda result: isinstance(result, str),
+        "result must be a string",
+    )
+    def to_json(self) -> str:
+        """Convert to a JSON string matching the spec output format."""
+        return json.dumps(self.to_dict(), indent=2)
+
+
+@icontract.require(
+    lambda results: isinstance(results, tuple),
+    "results must be a tuple",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, CheckResult),
+    "result must be a CheckResult",
+)
+def make_check_result(
+    results: tuple[FunctionResult, ...],
+    level_requested: int,
+    duration_seconds: float,
+    level_achieved: int | None = None,
+) -> CheckResult:
+    """Create a CheckResult from a tuple of FunctionResults.
+
+    Automatically computes passed/failed/skipped counts and overall status.
+
+    Args:
+        results: Tuple of per-function results.
+        level_requested: The verification level that was requested.
+        duration_seconds: How long the check took.
+        level_achieved: Optional aggregate level achieved override.
+
+    Returns:
+        A fully constructed CheckResult.
+    """
+    passed_count = 0
+    failed_count = 0
+    skipped_count = 0
+    exempt_count = 0
+    min_achieved = level_requested
+
+    # Loop invariant: counts reflect classifications of results[0..i]
+    for r in results:
+        if r.status == CheckStatus.EXEMPT:
+            exempt_count += 1
+            continue
+        if r.level_achieved < min_achieved:
+            min_achieved = r.level_achieved
+        if r.status == CheckStatus.PASSED:
+            passed_count += 1
+        elif r.status == CheckStatus.FAILED:
+            failed_count += 1
+        else:
+            skipped_count += 1
+
+    overall_level_achieved = (
+        min_achieved if level_achieved is None else level_achieved
+    )
+
+    summary = CheckSummary(
+        total_functions=len(results),
+        passed_count=passed_count,
+        failed_count=failed_count,
+        skipped_count=skipped_count,
+        exempt_count=exempt_count,
+        duration_seconds=duration_seconds,
+    )
+
+    # Exempt results are visible but do not block a passing result.
+    passed = (
+        failed_count == 0
+        and skipped_count == 0
+        and overall_level_achieved == level_requested
+    )
+
+    return CheckResult(
+        passed=passed,
+        level_requested=level_requested,
+        level_achieved=overall_level_achieved,
+        results=results,
+        summary=summary,
+    )

serenecode/ports/__init__.py

@@ -0,0 +1,6 @@
+"""Port definitions for Serenecode.
+
+This package contains Protocol definitions (interfaces) that define
+the boundaries between core domain logic and external I/O operations.
+No implementations exist here — only abstract contracts.
+"""