se-theory-reference-kit 0.1.0__py3-none-any.whl

se_theory_reference_kit/__init__.py

@@ -0,0 +1 @@
+"""se_theory_reference_kit package."""

se_theory_reference_kit/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

se_theory_reference_kit/base/__init__.py

@@ -0,0 +1,51 @@
+"""base/__init__.py - Shared base utilities for theory-reference tooling."""
+
+from se_theory_reference_kit.base.errors import (
+    ArtifactLoadError,
+    ConfigurationError,
+    ReferenceKitError,
+    RepositoryRootError,
+)
+from se_theory_reference_kit.base.paths import (
+    find_repository_root,
+    lean_module_to_path,
+    reference_artifact_path,
+    reference_dir,
+    reference_index_path,
+    resolve_repo_path,
+)
+from se_theory_reference_kit.base.results import (
+    CheckResult,
+    CheckSeverity,
+    CheckStatus,
+    JsonDetail,
+    cannot_verify,
+    failure,
+    ok,
+    partial,
+    warning,
+    worst_status,
+)
+
+__all__ = [
+    "ArtifactLoadError",
+    "ConfigurationError",
+    "ReferenceKitError",
+    "RepositoryRootError",
+    "find_repository_root",
+    "lean_module_to_path",
+    "reference_artifact_path",
+    "reference_dir",
+    "reference_index_path",
+    "resolve_repo_path",
+    "CheckResult",
+    "CheckSeverity",
+    "CheckStatus",
+    "JsonDetail",
+    "cannot_verify",
+    "failure",
+    "ok",
+    "partial",
+    "warning",
+    "worst_status",
+]

se_theory_reference_kit/base/errors.py

@@ -0,0 +1,25 @@
+"""base/errors.py - Exception types for theory-reference tooling."""
+
+
+class ReferenceKitError(Exception):
+    """Base exception for theory-reference-kit failures."""
+
+
+class RepositoryRootError(ReferenceKitError):
+    """Raised when a repository root cannot be resolved."""
+
+
+class ConfigurationError(ReferenceKitError):
+    """Raised when repo-provided reference configuration is invalid."""
+
+
+class ArtifactLoadError(ReferenceKitError):
+    """Raised when a reference artifact cannot be loaded."""
+
+
+class ArtifactWriteError(ReferenceKitError):
+    """Raised when a reference artifact cannot be written."""
+
+
+class PathResolutionError(ReferenceKitError):
+    """Raised when a repository-relative path is invalid."""

se_theory_reference_kit/base/io.py

@@ -0,0 +1,67 @@
+"""base/io.py - UTF-8 text and TOML loading helpers."""
+
+from pathlib import Path
+import tomllib
+
+from se_theory_reference_kit.base.errors import ArtifactLoadError, ArtifactWriteError
+
+TomlDocument = dict[str, object]
+
+
+def read_text(path: Path) -> str:
+    """Read a UTF-8 text file.
+
+    Args:
+        path: File path.
+
+    Returns:
+        File contents.
+
+    Raises:
+        ArtifactLoadError: If the file cannot be read.
+    """
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        msg = f"Unable to read text file: {path}"
+        raise ArtifactLoadError(msg) from exc
+
+
+def write_text(path: Path, content: str) -> None:
+    """Write a UTF-8 text file, creating parent directories if needed.
+
+    Args:
+        path: Output path.
+        content: Text content.
+
+    Raises:
+        ArtifactWriteError: If the file cannot be written.
+    """
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        msg = f"Unable to write text file: {path}"
+        raise ArtifactWriteError(msg) from exc
+
+
+def load_toml(path: Path) -> TomlDocument:
+    """Load a TOML file.
+
+    Args:
+        path: TOML file path.
+
+    Returns:
+        Parsed TOML document.
+
+    Raises:
+        ArtifactLoadError: If the file cannot be read or parsed.
+    """
+    try:
+        with path.open("rb") as file_obj:
+            data = tomllib.load(file_obj)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        msg = f"Unable to read TOML file: {path}"
+        raise ArtifactLoadError(msg) from exc
+
+    return data

se_theory_reference_kit/base/json_utils.py

@@ -0,0 +1,78 @@
+"""base/json_utils.py - Deterministic JSON helpers."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from se_theory_reference_kit.base.io import write_text
+
+JsonObject = dict[str, Any]
+
+
+def encode_json(payload: JsonObject) -> str:
+    """Encode a JSON payload deterministically.
+
+    The payload builder owns ordering. This encoder preserves insertion order
+    rather than sorting keys.
+
+    Args:
+        payload: JSON-compatible object.
+
+    Returns:
+        Encoded JSON text ending with a newline.
+    """
+    return (
+        json.dumps(
+            payload,
+            indent=2,
+            sort_keys=False,
+            ensure_ascii=True,
+        )
+        + "\n"
+    )
+
+
+def write_or_check_text(path: Path, content: str, *, check: bool) -> bool:
+    """Write a file or check whether it is current.
+
+    Returns true when the file is current or was written.
+    Returns false when check mode finds stale content.
+
+    Args:
+        path: Output path.
+        content: Expected file content.
+        check: If true, check freshness without writing.
+
+    Returns:
+        True when current or written, otherwise false.
+    """
+    if check:
+        if not path.exists():
+            print(f"[stale] {path.as_posix()} is missing")
+            return False
+
+        current = path.read_text(encoding="utf-8")
+        if current != content:
+            print(f"[stale] {path.as_posix()} is out of date")
+            return False
+
+        print(f"[ok   ] {path.as_posix()}")
+        return True
+
+    write_text(path, content)
+    print(f"[write] {path.as_posix()}")
+    return True
+
+
+def write_or_check_json(path: Path, payload: JsonObject, *, check: bool) -> bool:
+    """Write a JSON payload or check whether the file is current.
+
+    Args:
+        path: Output path.
+        payload: JSON payload.
+        check: If true, check freshness without writing.
+
+    Returns:
+        True when current or written, otherwise false.
+    """
+    return write_or_check_text(path, encode_json(payload), check=check)

se_theory_reference_kit/base/paths.py

@@ -0,0 +1,168 @@
+"""base/paths.py - Repository-relative path helpers."""
+
+from pathlib import Path
+
+from se_theory_reference_kit.base.errors import (
+    PathResolutionError,
+    RepositoryRootError,
+)
+
+ROOT_MARKERS: tuple[str, ...] = ("pyproject.toml", "SE_MANIFEST.toml", ".git")
+
+
+def find_repository_root(start: Path | None = None) -> Path:
+    """Find the nearest repository root from a starting path.
+
+    Args:
+        start: Starting path. Defaults to the current working directory.
+
+    Returns:
+        Resolved repository root path.
+
+    Raises:
+        RepositoryRootError: If no repository root marker is found.
+    """
+    current = (start or Path.cwd()).resolve()
+
+    if current.is_file():
+        current = current.parent
+
+    for candidate in (current, *current.parents):
+        if any((candidate / marker).exists() for marker in ROOT_MARKERS):
+            return candidate
+
+    msg = f"Could not resolve repository root from {current}"
+    raise RepositoryRootError(msg)
+
+
+def resolve_repo_path(path: str | Path, *, root: Path | None = None) -> Path:
+    """Resolve a path as repository-relative and contained within the repository.
+
+    Args:
+        path: Repository-relative path.
+        root: Repository root. Defaults to nearest detected repository root.
+
+    Returns:
+        Resolved absolute path.
+
+    Raises:
+        PathResolutionError: If the path escapes the repository root.
+    """
+    repo_root = find_repository_root(root)
+    resolved = (repo_root / path).resolve()
+
+    try:
+        resolved.relative_to(repo_root)
+    except ValueError as exc:
+        msg = f"Path escapes repository root: {path}"
+        raise PathResolutionError(msg) from exc
+
+    return resolved
+
+
+def reference_dir(
+    *,
+    root: Path | None = None,
+    reference_dir_name: str = "reference",
+) -> Path:
+    """Return the repository reference directory."""
+    return resolve_repo_path(reference_dir_name, root=root)
+
+
+def reference_index_path(
+    *,
+    root: Path | None = None,
+    reference_dir_name: str = "reference",
+    reference_index_name: str = "index.toml",
+) -> Path:
+    """Return the repository reference index path."""
+    return (
+        reference_dir(
+            root=root,
+            reference_dir_name=reference_dir_name,
+        )
+        / reference_index_name
+    )
+
+
+def reference_artifact_path(
+    path: str | Path,
+    *,
+    root: Path | None = None,
+    reference_dir_name: str = "reference",
+) -> Path:
+    """Resolve a declared reference artifact path.
+
+    The declared path must be repository-relative and under the reference
+    directory.
+
+    Args:
+        path: Declared repository-relative artifact path.
+        root: Repository root.
+        reference_dir_name: Name of the reference artifact directory.
+
+    Returns:
+        Resolved reference artifact path.
+
+    Raises:
+        PathResolutionError: If the path is outside the reference directory.
+    """
+    resolved = resolve_repo_path(path, root=root)
+    reference_root = reference_dir(
+        root=root,
+        reference_dir_name=reference_dir_name,
+    ).resolve()
+
+    try:
+        resolved.relative_to(reference_root)
+    except ValueError as exc:
+        msg = f"Reference artifact path is not under {reference_dir_name}/: {path}"
+        raise PathResolutionError(msg) from exc
+
+    return resolved
+
+
+def lean_module_to_path(
+    module: str,
+    *,
+    root: Path | None = None,
+    lean_public_root: str,
+) -> Path:
+    """Resolve a Lean module name to its repository source path.
+
+    Args:
+        module: Lean module name.
+        root: Repository root.
+        lean_public_root: Expected public Lean root for the owning repository.
+
+    Returns:
+        Repository-contained Lean source path.
+
+    Raises:
+        PathResolutionError: If the module name is empty, path-like, malformed,
+            or outside the declared public Lean root.
+    """
+    module_name = module.strip()
+
+    if not module_name:
+        msg = "Lean module name must be nonempty."
+        raise PathResolutionError(msg)
+
+    if "/" in module_name or "\\" in module_name:
+        msg = f"Expected Lean module name, got path-like value: {module}"
+        raise PathResolutionError(msg)
+
+    parts = module_name.split(".")
+
+    if any(not part for part in parts):
+        msg = f"Malformed Lean module name: {module}"
+        raise PathResolutionError(msg)
+
+    if module_name != lean_public_root and not module_name.startswith(
+        f"{lean_public_root}."
+    ):
+        msg = f"Expected Lean module under {lean_public_root}, got: {module_name}"
+        raise PathResolutionError(msg)
+
+    relative_path = Path(*parts).with_suffix(".lean")
+    return resolve_repo_path(relative_path, root=root)

se_theory_reference_kit/base/results.py

@@ -0,0 +1,183 @@
+"""validation/results.py - Result vocabulary for theory-reference checks."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+type JsonDetail = dict[str, object]
+
+__all__ = [
+    "CheckResult",
+    "CheckSeverity",
+    "CheckStatus",
+    "JsonDetail",
+    "cannot_verify",
+    "failure",
+    "ok",
+    "partial",
+    "warning",
+    "worst_status",
+]
+
+
+def empty_detail() -> JsonDetail:
+    """Return an empty result detail dictionary."""
+    return {}
+
+
+class CheckStatus(StrEnum):
+    """Status vocabulary for one validation finding."""
+
+    OK = "ok"
+    PARTIAL = "partial"
+    FAIL = "fail"
+    CANNOT_VERIFY = "cannot-verify"
+
+
+class CheckSeverity(StrEnum):
+    """Severity vocabulary for one validation finding."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResult:
+    """One validation finding emitted by one check.
+
+    Attributes:
+        check_id: Stable id of the check that emitted the finding.
+        status: Check status.
+        severity: Finding severity.
+        message: Human-readable finding message.
+        artifact_id: Optional artifact id associated with the finding.
+        path: Optional path associated with the finding.
+        detail: Optional structured detail for reports or downstream tooling.
+    """
+
+    check_id: str
+    status: CheckStatus
+    severity: CheckSeverity
+    message: str
+    artifact_id: str | None = None
+    path: Path | None = None
+    detail: JsonDetail = field(default_factory=empty_detail)
+
+
+def ok(
+    check_id: str,
+    message: str,
+    *,
+    artifact_id: str | None = None,
+    path: Path | None = None,
+    detail: JsonDetail | None = None,
+) -> CheckResult:
+    """Create an ok result."""
+    return CheckResult(
+        check_id=check_id,
+        status=CheckStatus.OK,
+        severity=CheckSeverity.INFO,
+        message=message,
+        artifact_id=artifact_id,
+        path=path,
+        detail={} if detail is None else detail,
+    )
+
+
+def partial(
+    check_id: str,
+    message: str,
+    *,
+    artifact_id: str | None = None,
+    path: Path | None = None,
+    detail: JsonDetail | None = None,
+) -> CheckResult:
+    """Create a partial result."""
+    return CheckResult(
+        check_id=check_id,
+        status=CheckStatus.PARTIAL,
+        severity=CheckSeverity.WARNING,
+        message=message,
+        artifact_id=artifact_id,
+        path=path,
+        detail={} if detail is None else detail,
+    )
+
+
+def warning(
+    check_id: str,
+    message: str,
+    *,
+    artifact_id: str | None = None,
+    path: Path | None = None,
+    detail: JsonDetail | None = None,
+) -> CheckResult:
+    """Create a warning failure result."""
+    return CheckResult(
+        check_id=check_id,
+        status=CheckStatus.FAIL,
+        severity=CheckSeverity.WARNING,
+        message=message,
+        artifact_id=artifact_id,
+        path=path,
+        detail={} if detail is None else detail,
+    )
+
+
+def failure(
+    check_id: str,
+    message: str,
+    *,
+    artifact_id: str | None = None,
+    path: Path | None = None,
+    detail: JsonDetail | None = None,
+) -> CheckResult:
+    """Create an error failure result."""
+    return CheckResult(
+        check_id=check_id,
+        status=CheckStatus.FAIL,
+        severity=CheckSeverity.ERROR,
+        message=message,
+        artifact_id=artifact_id,
+        path=path,
+        detail={} if detail is None else detail,
+    )
+
+
+def cannot_verify(
+    check_id: str,
+    message: str,
+    *,
+    artifact_id: str | None = None,
+    path: Path | None = None,
+    detail: JsonDetail | None = None,
+) -> CheckResult:
+    """Create a cannot-verify result."""
+    return CheckResult(
+        check_id=check_id,
+        status=CheckStatus.CANNOT_VERIFY,
+        severity=CheckSeverity.ERROR,
+        message=message,
+        artifact_id=artifact_id,
+        path=path,
+        detail={} if detail is None else detail,
+    )
+
+
+def worst_status(results: Iterable[CheckResult]) -> CheckStatus:
+    """Return the worst status across validation results."""
+    rank = {
+        CheckStatus.OK: 0,
+        CheckStatus.PARTIAL: 1,
+        CheckStatus.FAIL: 2,
+        CheckStatus.CANNOT_VERIFY: 3,
+    }
+
+    worst = CheckStatus.OK
+    for result in results:
+        if rank[result.status] > rank[worst]:
+            worst = result.status
+
+    return worst

se_theory_reference_kit/cli.py

@@ -0,0 +1,5 @@
+"""cli.py - Console entry point for se-theory-reference."""
+
+from se_theory_reference_kit.commands.root import main
+
+__all__ = ["main"]

se_theory_reference_kit/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations for cli."""