serenecode 0.1.0__py3-none-any.whl

serenecode/reporter.py

@@ -0,0 +1,346 @@
+"""Report generation for Serenecode verification results.
+
+This module provides pure formatting functions that convert CheckResult
+objects into human-readable terminal output or JSON strings matching
+the spec output format.
+
+This is a core module — no I/O imports are permitted.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import icontract
+
+from serenecode.models import CheckResult, CheckStatus, FunctionResult
+
+
+@icontract.require(
+    lambda check_result: isinstance(check_result, CheckResult),
+    "check_result must be a CheckResult",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str),
+    "output must be a string",
+)
+def format_human(check_result: CheckResult) -> str:
+    """Format a CheckResult as human-readable terminal output.
+
+    Condenses passing files into a single summary line and only
+    expands files that contain failures or skips with details.
+
+    Args:
+        check_result: The verification result to format.
+
+    Returns:
+        A formatted string suitable for terminal display.
+    """
+    lines: list[str] = []
+
+    # Header
+    status_marker = "PASSED" if check_result.passed else "FAILED"
+    lines.append(f"Serenecode Check — {status_marker}")
+    lines.append("=" * 50)
+    lines.append("")
+
+    # Group results by file
+    by_file: dict[str, list[FunctionResult]] = {}
+    # Loop invariant: by_file contains all results from results[0..i] grouped by file
+    for func_result in check_result.results:
+        by_file.setdefault(func_result.file, []).append(func_result)
+
+    # Loop invariant: lines contains formatted output for all files processed so far
+    for file_path, func_results in sorted(by_file.items()):
+        passed = [r for r in func_results if r.status == CheckStatus.PASSED]
+        failed = [r for r in func_results if r.status == CheckStatus.FAILED]
+        skipped = [r for r in func_results if r.status == CheckStatus.SKIPPED]
+        exempt = [r for r in func_results if r.status == CheckStatus.EXEMPT]
+
+        # Compact summary for all-pass files
+        if not failed and not skipped and not exempt:
+            lines.append(f"  {file_path} — {len(passed)} passed")
+            continue
+
+        # Compact summary for exempt-only files
+        if not failed and not skipped and not passed:
+            lines.append(f"  {file_path} — exempt")
+            continue
+
+        # File header with counts
+        parts = []
+        if passed:
+            parts.append(f"{len(passed)} passed")
+        if failed:
+            parts.append(f"{len(failed)} failed")
+        if skipped:
+            parts.append(f"{len(skipped)} skipped")
+        if exempt:
+            parts.append(f"{len(exempt)} exempt")
+        lines.append(f"  {file_path} — {', '.join(parts)}")
+
+        # Only show non-passing results with details
+        # Loop invariant: lines contains output for non-passing func_results[0..j]
+        for func_result in func_results:
+            if func_result.status in (CheckStatus.PASSED, CheckStatus.EXEMPT):
+                continue
+            marker = "FAIL" if func_result.status == CheckStatus.FAILED else "SKIP"
+            lines.append(f"    [{marker}] {func_result.function} (line {func_result.line})")
+
+            # Loop invariant: lines contains all details for details[0..k]
+            for detail in func_result.details:
+                lines.append(f"           {detail.message}")
+                if detail.suggestion:
+                    lines.append(f"           -> {detail.suggestion}")
+                if detail.counterexample:
+                    lines.append(f"           counterexample: {detail.counterexample}")
+
+        lines.append("")
+
+    # Summary
+    lines.append("-" * 50)
+    summary = check_result.summary
+    summary_parts = [
+        f"{summary.total_functions} checked",
+        f"{summary.passed_count} passed",
+        f"{summary.failed_count} failed",
+        f"{summary.skipped_count} skipped",
+    ]
+    if summary.exempt_count > 0:
+        summary_parts.append(f"{summary.exempt_count} exempt")
+    lines.append(", ".join(summary_parts))
+    lines.append(f"Duration: {summary.duration_seconds:.3f}s")
+
+    return "\n".join(lines)
+
+
+@icontract.require(
+    lambda check_result: isinstance(check_result, CheckResult),
+    "check_result must be a CheckResult",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str),
+    "output must be a string",
+)
+def format_json(check_result: CheckResult) -> str:
+    """Format a CheckResult as JSON matching the spec Section 4.3 format.
+
+    Args:
+        check_result: The verification result to format.
+
+    Returns:
+        A JSON string matching the specification output format.
+    """
+    timestamp = datetime.now(timezone.utc).isoformat()
+    base = check_result.to_dict()
+
+    output: dict[str, object] = {
+        "version": base["version"],
+        "timestamp": timestamp,
+        "passed": base["passed"],
+        "level_requested": base["level_requested"],
+        "level_achieved": base["level_achieved"],
+        "summary": base["summary"],
+        "results": base["results"],
+    }
+
+    return json.dumps(output, indent=2)
+
+
+@icontract.require(
+    lambda check_result: isinstance(check_result, CheckResult),
+    "check_result must be a CheckResult",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, str),
+    "output must be a string",
+)
+def format_html(check_result: CheckResult) -> str:
+    """Format a CheckResult as an HTML verification report.
+
+    Produces a self-contained HTML document with expandable sections,
+    verification level badges, and styled results suitable for
+    compliance documentation or CI/CD artifacts.
+
+    Args:
+        check_result: The verification result to format.
+
+    Returns:
+        A complete HTML document as a string.
+    """
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    status_class = "passed" if check_result.passed else "failed"
+    status_text = "PASSED" if check_result.passed else "FAILED"
+    summary = check_result.summary
+
+    # Group results by file
+    by_file: dict[str, list[FunctionResult]] = {}
+    # Loop invariant: by_file contains results grouped for results[0..i]
+    for func_result in check_result.results:
+        by_file.setdefault(func_result.file, []).append(func_result)
+
+    # Build file sections
+    file_sections: list[str] = []
+    # Loop invariant: file_sections contains HTML for files processed so far
+    for file_path, func_results in sorted(by_file.items()):
+        file_passed = all(r.status in (CheckStatus.PASSED, CheckStatus.EXEMPT) for r in func_results)
+        file_class = "passed" if file_passed else "failed"
+        file_icon = "✔" if file_passed else "✘"
+
+        rows: list[str] = []
+        # Loop invariant: rows contains table rows for func_results[0..j]
+        for fr in func_results:
+            row_class = "pass-row" if fr.status in (CheckStatus.PASSED, CheckStatus.EXEMPT) else "fail-row"
+            status_badge = _level_badge(fr.level_achieved)
+            detail_html = ""
+            if fr.details:
+                detail_parts: list[str] = []
+                # Loop invariant: detail_parts contains detail HTML for details[0..k]
+                for d in fr.details:
+                    part = f'<div class="detail">{_escape_html(d.message)}'
+                    if d.suggestion:
+                        escaped_suggestion = _escape_html(d.suggestion)
+                        if "\n" in d.suggestion:
+                            part += f'<br><pre class="suggestion">{escaped_suggestion}</pre>'
+                        else:
+                            part += f'<br><span class="suggestion">&#x27A1; {escaped_suggestion}</span>'
+                    if d.counterexample is not None and d.counterexample:
+                        try:
+                            ce_text = json.dumps(d.counterexample, default=str)
+                        except (TypeError, ValueError):
+                            ce_text = str(d.counterexample)
+                        part += f'<br><span class="counterexample">Counterexample: {_escape_html(ce_text)}</span>'
+                    part += "</div>"
+                    detail_parts.append(part)
+                detail_html = "".join(detail_parts)
+
+            rows.append(
+                f'<tr class="{row_class}">'
+                f'<td>{_escape_html(fr.function)}</td>'
+                f"<td>{fr.line}</td>"
+                f"<td>{status_badge}</td>"
+                f"<td>{fr.status.value}</td>"
+                f"<td>{detail_html}</td>"
+                f"</tr>"
+            )
+
+        table_html = "\n".join(rows)
+        file_sections.append(
+            f'<details class="file-section {file_class}">'
+            f"<summary>{file_icon} {_escape_html(file_path)}</summary>"
+            f'<table class="results-table">'
+            f"<thead><tr><th>Function</th><th>Line</th><th>Level</th><th>Status</th><th>Details</th></tr></thead>"
+            f"<tbody>{table_html}</tbody>"
+            f"</table>"
+            f"</details>"
+        )
+
+    files_html = "\n".join(file_sections)
+
+    return f"""\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Serenecode Verification Report</title>
+<style>
+  body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 2rem; color: #24292f; background: #f6f8fa; }}
+  .header {{ background: #fff; border: 1px solid #d0d7de; border-radius: 6px; padding: 1.5rem; margin-bottom: 1.5rem; }}
+  .header h1 {{ margin: 0 0 0.5rem; font-size: 1.5rem; }}
+  .status {{ display: inline-block; padding: 0.25rem 0.75rem; border-radius: 20px; font-weight: 600; font-size: 0.9rem; }}
+  .status.passed {{ background: #dafbe1; color: #116329; }}
+  .status.failed {{ background: #ffebe9; color: #82071e; }}
+  .summary {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 1rem; margin-top: 1rem; }}
+  .summary-item {{ text-align: center; }}
+  .summary-item .number {{ font-size: 2rem; font-weight: 700; }}
+  .summary-item .label {{ color: #656d76; font-size: 0.85rem; }}
+  .file-section {{ background: #fff; border: 1px solid #d0d7de; border-radius: 6px; margin-bottom: 0.75rem; }}
+  .file-section summary {{ padding: 0.75rem 1rem; cursor: pointer; font-weight: 500; }}
+  .file-section.failed summary {{ color: #82071e; }}
+  .file-section.passed summary {{ color: #116329; }}
+  .results-table {{ width: 100%; border-collapse: collapse; margin: 0; }}
+  .results-table th {{ background: #f6f8fa; padding: 0.5rem; text-align: left; border-bottom: 1px solid #d0d7de; font-size: 0.85rem; }}
+  .results-table td {{ padding: 0.5rem; border-bottom: 1px solid #eee; font-size: 0.85rem; vertical-align: top; }}
+  .pass-row {{ background: #f0fff4; }}
+  .fail-row {{ background: #fff5f5; }}
+  .badge {{ display: inline-block; padding: 0.15rem 0.5rem; border-radius: 10px; font-size: 0.75rem; font-weight: 600; }}
+  .badge-1 {{ background: #ddf4ff; color: #0550ae; }}
+  .badge-2 {{ background: #dafbe1; color: #116329; }}
+  .badge-3 {{ background: #fff8c5; color: #4d2d00; }}
+  .badge-4 {{ background: #fbefff; color: #5e3a8a; }}
+  .badge-5 {{ background: #ffebe9; color: #82071e; }}
+  .badge-6 {{ background: #fff0f0; color: #6e0b14; }}
+  .detail {{ margin: 0.25rem 0; }}
+  .suggestion {{ color: #0550ae; font-style: italic; }}
+  pre.suggestion {{ background: #f6f8fa; padding: 0.5rem; border-radius: 4px; font-size: 0.8rem; overflow-x: auto; white-space: pre-wrap; }}
+  .counterexample {{ color: #82071e; font-family: monospace; font-size: 0.8rem; }}
+  .footer {{ margin-top: 1.5rem; color: #656d76; font-size: 0.8rem; text-align: center; }}
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>Serenecode Verification Report</h1>
+  <span class="status {status_class}">{status_text}</span>
+  <span style="margin-left: 1rem; color: #656d76;">Generated {timestamp}</span>
+  <div class="summary">
+    <div class="summary-item"><div class="number">{summary.total_functions}</div><div class="label">Total</div></div>
+    <div class="summary-item"><div class="number" style="color:#116329">{summary.passed_count}</div><div class="label">Passed</div></div>
+    <div class="summary-item"><div class="number" style="color:#82071e">{summary.failed_count}</div><div class="label">Failed</div></div>
+    <div class="summary-item"><div class="number" style="color:#656d76">{summary.skipped_count}</div><div class="label">Skipped</div></div>
+    <div class="summary-item"><div class="number" style="color:#8b6914">{summary.exempt_count}</div><div class="label">Exempt</div></div>
+    <div class="summary-item"><div class="number">{summary.duration_seconds:.2f}s</div><div class="label">Duration</div></div>
+  </div>
+</div>
+{files_html}
+<div class="footer">
+  Serenecode v{check_result.version} &mdash; Formal verification for AI-generated Python code
+</div>
+</body>
+</html>"""
+
+
+@icontract.require(lambda level: isinstance(level, int), "level must be an integer")
+@icontract.ensure(lambda result: isinstance(result, str), "result must be a string")
+def _level_badge(level: int) -> str:
+    """Generate an HTML badge for a verification level.
+
+    Args:
+        level: The verification level (0-5).
+
+    Returns:
+        An HTML span element with the level badge.
+    """
+    level_names = {
+        0: "None",
+        1: "L1 Structural",
+        2: "L2 Types",
+        3: "L3 Coverage",
+        4: "L4 Properties",
+        5: "L5 Symbolic",
+        6: "L6 Compositional",
+    }
+    name = level_names.get(level, f"L{level}")
+    badge_class = f"badge-{min(level, 6)}" if level > 0 else "badge-1"
+    return f'<span class="badge {badge_class}">{name}</span>'
+
+
+@icontract.require(lambda text: isinstance(text, str), "text must be a string")
+@icontract.ensure(lambda result: isinstance(result, str), "result must be a string")
+def _escape_html(text: str) -> str:
+    """Escape HTML special characters.
+
+    Args:
+        text: Raw text to escape.
+
+    Returns:
+        HTML-safe text.
+    """
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#x27;")
+    )

serenecode/source_discovery.py

@@ -0,0 +1,319 @@
+"""Helpers for finding configuration files and building SourceFile objects.
+
+This module keeps the CLI and library API in sync when they discover
+source files, derive module references for higher verification levels,
+and locate SERENECODE.md in parent directories.
+"""
+
+from __future__ import annotations
+
+import keyword
+import os
+
+import icontract
+
+from serenecode.contracts.predicates import is_non_empty_string
+from serenecode.core.exceptions import ConfigurationError
+from serenecode.core.pipeline import SourceFile
+from serenecode.ports.file_system import FileReader
+
+_ARCHITECTURE_DIR_NAMES = frozenset({
+    "adapters",
+    "checker",
+    "contracts",
+    "core",
+    "ports",
+})
+
+_PROJECT_MARKERS = (
+    "SERENECODE.md",
+    "pyproject.toml",
+    ".git",
+)
+
+
+@icontract.require(
+    lambda search_root: is_non_empty_string(search_root),
+    "search_root must be a non-empty string",
+)
+@icontract.require(
+    lambda reader: reader is not None,
+    "reader must be provided",
+)
+@icontract.require(
+    lambda file_paths: all(is_non_empty_string(file_path) for file_path in file_paths),
+    "file_paths must contain only non-empty paths",
+)
+@icontract.ensure(
+    lambda result: isinstance(result, tuple),
+    "result must be a tuple",
+)
+def build_source_files(
+    file_paths: list[str],
+    reader: FileReader,
+    search_root: str,
+) -> tuple[SourceFile, ...]:
+    """Build SourceFile objects from file paths.
+
+    Args:
+        file_paths: Paths to Python files.
+        reader: File reader for reading contents.
+        search_root: Root path originally requested by the user.
+
+    Returns:
+        Tuple of SourceFile objects.
+
+    Raises:
+        ConfigurationError: If any discovered file cannot be read.
+    """
+    source_files: list[SourceFile] = []
+    normalized_root = _determine_context_root(search_root)
+
+    # Loop invariant: source_files contains SourceFile objects for file_paths[0..i]
+    for file_path in file_paths:
+        try:
+            source = reader.read_file(file_path)
+        except Exception as exc:
+            raise ConfigurationError(
+                f"Cannot prepare source file '{file_path}': {exc}"
+            ) from exc
+
+        source_files.append(SourceFile(
+            file_path=file_path,
+            module_path=_derive_module_path(file_path, normalized_root),
+            source=source,
+            importable_module=_derive_module_reference(file_path, normalized_root),
+            import_search_paths=_derive_import_search_paths(file_path, normalized_root),
+        ))
+
+    return tuple(source_files)
+
+
+@icontract.require(
+    lambda path: is_non_empty_string(path),
+    "path must be a non-empty string",
+)
+@icontract.require(
+    lambda reader: reader is not None,
+    "reader must be provided",
+)
+@icontract.ensure(
+    lambda result: result is None or result.endswith("SERENECODE.md"),
+    "result must be a SERENECODE.md path when present",
+)
+def find_serenecode_md(path: str, reader: FileReader) -> str | None:
+    """Find SERENECODE.md by searching up from the given path."""
+    current = _normalize_search_root(path)
+
+    # Loop invariant: no ancestor directory checked so far contains SERENECODE.md
+    while True:
+        candidate = os.path.join(current, "SERENECODE.md")
+        if reader.file_exists(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+
+    return None
+
+
+@icontract.require(lambda path: is_non_empty_string(path), "path must be a non-empty string")
+@icontract.ensure(lambda result: is_non_empty_string(result), "result must be a non-empty string")
+def _normalize_search_root(path: str) -> str:
+    """Normalize a user-supplied search path to a directory path."""
+    absolute = os.path.abspath(path)
+    if os.path.isdir(absolute):
+        return absolute
+    return os.path.dirname(absolute)
+
+
+@icontract.require(lambda path: is_non_empty_string(path), "path must be a non-empty string")
+@icontract.ensure(lambda result: is_non_empty_string(result), "result must be a non-empty string")
+def _determine_context_root(path: str) -> str:
+    """Determine the stable root used for module-path derivation."""
+    search_root = _normalize_search_root(path)
+
+    current = search_root
+    # Loop invariant: current is an ancestor of search_root already checked for markers
+    while True:
+        if _has_project_marker(current):
+            return current
+
+        if os.path.basename(current) == "src":
+            return os.path.dirname(current)
+
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+
+    if os.path.isfile(os.path.join(search_root, "__init__.py")):
+        return _walk_package_root(search_root)
+
+    if os.path.basename(search_root) in _ARCHITECTURE_DIR_NAMES:
+        return os.path.dirname(search_root)
+
+    return search_root
+
+
+@icontract.require(lambda path: is_non_empty_string(path), "path must be a non-empty string")
+@icontract.ensure(lambda result: isinstance(result, bool), "result must be a bool")
+def _has_project_marker(path: str) -> bool:
+    """Check whether a directory looks like a project root."""
+    # Loop invariant: no marker from _PROJECT_MARKERS[0..i] exists in path
+    for marker in _PROJECT_MARKERS:
+        if os.path.exists(os.path.join(path, marker)):
+            return True
+    return False
+
+
+@icontract.require(lambda path: is_non_empty_string(path), "path must be a non-empty string")
+@icontract.ensure(lambda result: is_non_empty_string(result), "result must be a non-empty string")
+def _walk_package_root(path: str) -> str:
+    """Walk up package directories and return the import root above them."""
+    current = os.path.abspath(path)
+
+    # Loop invariant: current is the directory above the deepest package chain seen so far
+    while os.path.isfile(os.path.join(current, "__init__.py")):
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+
+    return current
+
+
+@icontract.require(lambda file_path: is_non_empty_string(file_path), "file_path must be a non-empty string")
+@icontract.require(lambda search_root: is_non_empty_string(search_root), "search_root must be a non-empty string")
+@icontract.ensure(lambda result: is_non_empty_string(result), "result must be a non-empty string")
+def _derive_module_path(file_path: str, search_root: str) -> str:
+    """Derive a normalized module path for structural/compositional checks."""
+    relative = _relative_to_root(file_path, search_root)
+    normalized = relative.replace(os.sep, "/")
+
+    if normalized.startswith("src/"):
+        return normalized[4:]
+
+    return normalized
+
+
+@icontract.require(lambda file_path: is_non_empty_string(file_path), "file_path must be a non-empty string")
+@icontract.require(lambda search_root: is_non_empty_string(search_root), "search_root must be a non-empty string")
+@icontract.ensure(lambda result: result is None or isinstance(result, str), "result must be a string or None")
+def _derive_module_reference(file_path: str, search_root: str) -> str | None:
+    """Derive a module reference for Level 3/4 backends.
+
+    Returns dotted module names for common relative/project-local layouts and
+    absolute file paths for standalone files that are not importable packages.
+    """
+    if not file_path.endswith(".py"):
+        return None
+
+    relative = _relative_to_root(file_path, search_root)
+    normalized_relative = relative.replace(os.sep, "/")
+    normalized_file = os.path.abspath(file_path).replace(os.sep, "/")
+
+    if normalized_relative.startswith("src/"):
+        module_ref = _module_reference_from_relative(normalized_relative[4:])
+        if module_ref is not None:
+            return module_ref
+
+    module_ref = _module_reference_from_relative(normalized_relative)
+    if module_ref is not None:
+        return module_ref
+
+    return normalized_file
+
+
+@icontract.require(lambda file_path: is_non_empty_string(file_path), "file_path must be a non-empty string")
+@icontract.require(lambda search_root: is_non_empty_string(search_root), "search_root must be a non-empty string")
+@icontract.ensure(lambda result: isinstance(result, tuple), "result must be a tuple")
+def _derive_import_search_paths(file_path: str, search_root: str) -> tuple[str, ...]:
+    """Derive sys.path roots needed to import a discovered module."""
+    absolute_file = os.path.abspath(file_path)
+    normalized_relative = _relative_to_root(file_path, search_root).replace(os.sep, "/")
+
+    candidates: list[str] = []
+    if normalized_relative.startswith("src/"):
+        candidates.append(os.path.join(search_root, "src"))
+    else:
+        candidates.append(search_root)
+
+    candidates.append(_infer_import_root(absolute_file))
+
+    roots: list[str] = []
+    # Loop invariant: roots contains unique, existing paths from candidates[0..i]
+    for candidate in candidates:
+        absolute_candidate = os.path.abspath(candidate)
+        if not os.path.isdir(absolute_candidate):
+            continue
+        if any(
+            os.path.commonpath([absolute_candidate, root]) == root
+            for root in roots
+        ):
+            continue
+        if absolute_candidate not in roots:
+            roots.append(absolute_candidate)
+
+    return tuple(roots)
+
+
+@icontract.require(lambda relative_path: is_non_empty_string(relative_path), "relative_path must be a non-empty string")
+@icontract.ensure(lambda result: result is None or isinstance(result, str), "result must be a string or None")
+def _module_reference_from_relative(relative_path: str) -> str | None:
+    """Build a dotted module name from a root-relative path when valid."""
+    if not relative_path.endswith(".py"):
+        return None
+
+    module_part = relative_path[:-3]
+    if module_part.endswith("/__init__"):
+        module_part = module_part[:-9]
+
+    if not module_part:
+        return None
+
+    segments = [segment for segment in module_part.split("/") if segment]
+    if not segments:
+        return None
+
+    # Loop invariant: all segments in segments[0..i] are valid identifiers
+    for segment in segments:
+        if not segment.isidentifier() or keyword.iskeyword(segment):
+            return None
+
+    return ".".join(segments)
+
+
+@icontract.require(lambda absolute_file: is_non_empty_string(absolute_file), "absolute_file must be a non-empty string")
+@icontract.ensure(lambda result: is_non_empty_string(result), "result must be a non-empty string")
+def _infer_import_root(absolute_file: str) -> str:
+    """Infer the import root by walking above package directories."""
+    current = os.path.dirname(absolute_file)
+
+    # Loop invariant: current is the directory above the deepest package chain seen so far
+    while os.path.isfile(os.path.join(current, "__init__.py")):
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+
+    return current
+
+
+@icontract.require(lambda file_path: is_non_empty_string(file_path), "file_path must be a non-empty string")
+@icontract.require(lambda search_root: is_non_empty_string(search_root), "search_root must be a non-empty string")
+@icontract.ensure(lambda result: is_non_empty_string(result), "result must be a non-empty string")
+def _relative_to_root(file_path: str, search_root: str) -> str:
+    """Compute a root-relative path when possible."""
+    absolute_file = os.path.abspath(file_path)
+
+    try:
+        common = os.path.commonpath([absolute_file, search_root])
+    except ValueError:
+        common = ""
+
+    if common == search_root:
+        return os.path.relpath(absolute_file, search_root)
+
+    return os.path.relpath(absolute_file)

serenecode/templates/__init__.py

@@ -0,0 +1,5 @@
+"""Template files for SERENECODE.md initialization.
+
+This package contains the SERENECODE.md template content as embedded
+string constants, avoiding the need for file I/O at runtime.
+"""