devmemory-cli 0.1.0.dev0__py3-none-any.whl

devmemory/domain/enums.py

@@ -0,0 +1,151 @@
+"""Enumerations shared across the domain.
+
+All are ``str`` enums so they serialize transparently to JSON and SQLite.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class VersionStatus(StrEnum):
+    """The development result a version represents - not merely whether a commit exists."""
+
+    SUCCESS = "SUCCESS"
+    PARTIAL_SUCCESS = "PARTIAL_SUCCESS"
+    ERROR = "ERROR"
+    REGRESSION = "REGRESSION"
+    IN_PROGRESS = "IN_PROGRESS"
+    NEEDS_REVIEW = "NEEDS_REVIEW"
+
+    @property
+    def is_adverse(self) -> bool:
+        return self in {VersionStatus.ERROR, VersionStatus.REGRESSION}
+
+
+class FeatureStatus(StrEnum):
+    """Roll-up health of a logical feature area across its versions."""
+
+    COMPLETE = "COMPLETE"
+    PARTIAL = "PARTIAL"
+    IN_PROGRESS = "IN_PROGRESS"
+    FAILED = "FAILED"
+    NOT_STARTED = "NOT_STARTED"
+
+
+class ChangeType(StrEnum):
+    """How a single file changed between two commits (git name-status)."""
+
+    ADDED = "added"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    RENAMED = "renamed"
+    COPIED = "copied"
+    TYPE_CHANGED = "type_changed"
+
+    @classmethod
+    def from_git_status(cls, code: str) -> ChangeType:
+        """Map a git ``--name-status`` letter (``A``/``M``/``D``/``R``/``C``/``T``)."""
+        return {
+            "A": cls.ADDED,
+            "M": cls.MODIFIED,
+            "D": cls.DELETED,
+            "R": cls.RENAMED,
+            "C": cls.COPIED,
+            "T": cls.TYPE_CHANGED,
+        }.get(code[:1].upper(), cls.MODIFIED)
+
+
+class MetricDirection(StrEnum):
+    """Which way a metric should move to count as an improvement."""
+
+    HIGHER_IS_BETTER = "higher_is_better"
+    LOWER_IS_BETTER = "lower_is_better"
+    NEUTRAL = "neutral"
+
+
+class AssociationMethod(StrEnum):
+    """How a checkpoint was linked to a commit, ordered by decreasing confidence."""
+
+    TRAILER = "trailer"
+    ENTIRE_CLI = "entire_cli"
+    GIT_REF = "git_ref"
+    HEURISTIC_TIME = "heuristic_time"
+    MANUAL = "manual"
+    NONE = "none"
+
+    @property
+    def default_confidence(self) -> float:
+        return {
+            AssociationMethod.TRAILER: 1.0,
+            AssociationMethod.ENTIRE_CLI: 1.0,
+            AssociationMethod.GIT_REF: 1.0,
+            AssociationMethod.HEURISTIC_TIME: 0.5,
+            AssociationMethod.MANUAL: 0.9,
+            AssociationMethod.NONE: 0.0,
+        }[self]
+
+
+class TaskStatus(StrEnum):
+    """Where a task stands in the state-aware coding loop.
+
+    Evidence-based, never a claim of certainty: ``READY`` means the collected
+    evidence supports completion, not that completion is proven.
+    """
+
+    IN_PROGRESS = "IN_PROGRESS"
+    NEEDS_WORK = "NEEDS_WORK"
+    READY = "READY"
+    BLOCKED = "BLOCKED"
+
+    @property
+    def is_terminal(self) -> bool:
+        """``READY``/``BLOCKED`` end the loop; the agent must stop or ask a human."""
+        return self in {TaskStatus.READY, TaskStatus.BLOCKED}
+
+
+class RequirementStatus(StrEnum):
+    """Whether one normalized requirement is satisfied by the evidence."""
+
+    COMPLETE = "COMPLETE"
+    PARTIAL = "PARTIAL"
+    INCOMPLETE = "INCOMPLETE"
+    UNKNOWN = "UNKNOWN"
+
+    @property
+    def is_satisfied(self) -> bool:
+        return self is RequirementStatus.COMPLETE
+
+
+class IssueStatus(StrEnum):
+    """An unresolved item raised by the agent or the engine."""
+
+    OPEN = "OPEN"
+    RESOLVED = "RESOLVED"
+
+
+class TestRunStatus(StrEnum):
+    """Outcome of the configured test command for one state refresh.
+
+    ``FAILED_TO_PARSE`` is deliberate: the command ran but its output could not
+    be parsed, so counts are unknown rather than invented.
+    """
+
+    NOT_RUN = "NOT_RUN"
+    PASSED = "PASSED"
+    FAILED = "FAILED"
+    FAILED_TO_PARSE = "FAILED_TO_PARSE"
+    ERROR = "ERROR"
+
+
+__all__ = [
+    "AssociationMethod",
+    "ChangeType",
+    "FeatureStatus",
+    "IssueStatus",
+    "MetricDirection",
+    "RequirementStatus",
+    "TaskStatus",
+    "TestRunStatus",
+    "VersionStatus",
+]

devmemory/domain/errors.py

@@ -0,0 +1,188 @@
+"""Typed error taxonomy.
+
+Every failure DevMemory raises carries a human-readable ``message`` and, where we
+can, a ``hint`` telling the user what to do next. The CLI renders these; adapters
+and services raise them instead of leaking ``subprocess`` / ``sqlite3`` details.
+"""
+
+from __future__ import annotations
+
+_GIT_INIT_HINT = "DevMemory records versions against real git commits. Run `git init` first."
+_ENTIRE_INSTALL_HINT = (
+    "Install it from https://entire.io or set `entire.binary` in .devmemory/config.json. "
+    "Use `--allow-no-entire` to record a version without checkpoint context."
+)
+
+
+class DevMemoryError(Exception):
+    """Base class for every error DevMemory raises deliberately.
+
+    ``exit_code`` is used by the CLI as the process exit status. ``hint`` is an
+    optional next-step suggestion shown to the user beneath the message.
+    """
+
+    exit_code: int = 1
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.message
+
+
+# --- configuration / project lifecycle -------------------------------------------------
+
+
+class ConfigError(DevMemoryError):
+    """The DevMemory configuration is missing, malformed, or invalid."""
+
+    exit_code = 2
+
+
+class ProjectNotInitializedError(DevMemoryError):
+    """No ``.devmemory/`` directory was found at or above the working directory."""
+
+    exit_code = 3
+
+    def __init__(
+        self,
+        message: str = "DevMemory is not initialized in this directory.",
+        *,
+        hint: str | None = "Run `devmemory init` in your project root.",
+    ) -> None:
+        super().__init__(message, hint=hint)
+
+
+class ProjectAlreadyInitializedError(DevMemoryError):
+    """``devmemory init`` was run where DevMemory is already set up."""
+
+    exit_code = 3
+
+
+# --- storage --------------------------------------------------------------------------
+
+
+class StorageError(DevMemoryError):
+    """A local persistence operation failed."""
+
+
+class MigrationError(StorageError):
+    """A schema migration could not be applied."""
+
+
+# --- git -----------------------------------------------------------------------------
+
+
+class GitError(DevMemoryError):
+    """A git operation failed."""
+
+
+class GitRepositoryNotFoundError(GitError):
+    """The target path is not inside a git repository."""
+
+    exit_code = 4
+
+    def __init__(
+        self,
+        message: str = "This directory is not inside a git repository.",
+        *,
+        hint: str | None = _GIT_INIT_HINT,
+    ) -> None:
+        super().__init__(message, hint=hint)
+
+
+# --- entire --------------------------------------------------------------------------
+
+
+class EntireError(DevMemoryError):
+    """An Entire integration operation failed."""
+
+
+class EntireNotInstalledError(EntireError):
+    """The Entire CLI could not be located."""
+
+    exit_code = 5
+
+    def __init__(
+        self,
+        message: str = "The Entire CLI was not found on PATH.",
+        *,
+        hint: str | None = _ENTIRE_INSTALL_HINT,
+    ) -> None:
+        super().__init__(message, hint=hint)
+
+
+class EntireNotEnabledError(EntireError):
+    """Entire is installed but not enabled in this repository."""
+
+    exit_code = 5
+
+    def __init__(
+        self,
+        message: str = "Entire is not enabled in this repository.",
+        *,
+        hint: str | None = "Run `entire enable` so AI sessions are captured as checkpoints.",
+    ) -> None:
+        super().__init__(message, hint=hint)
+
+
+class CheckpointNotFoundError(EntireError):
+    """No Entire checkpoint could be associated with the target commit."""
+
+    exit_code = 6
+
+
+class CheckpointAmbiguousError(EntireError):
+    """More than one checkpoint plausibly matches and no explicit link exists."""
+
+    exit_code = 6
+
+
+# --- collection / analysis ----------------------------------------------------------
+
+
+class CollectionError(DevMemoryError):
+    """A test or metric collection step failed to run (not: the tests failed)."""
+
+
+class AnalysisError(DevMemoryError):
+    """The analysis provider could not produce a result."""
+
+
+# --- restore ----------------------------------------------------------------------
+
+
+class RestoreSafetyError(DevMemoryError):
+    """A restore was refused because it would risk losing uncommitted work."""
+
+    exit_code = 7
+
+
+# --- external services ----------------------------------------------------------
+
+
+class DatabricksError(DevMemoryError):
+    """A Databricks operation failed. Never fatal to local history."""
+
+
+__all__ = [
+    "AnalysisError",
+    "CheckpointAmbiguousError",
+    "CheckpointNotFoundError",
+    "CollectionError",
+    "ConfigError",
+    "DatabricksError",
+    "DevMemoryError",
+    "EntireError",
+    "EntireNotEnabledError",
+    "EntireNotInstalledError",
+    "GitError",
+    "GitRepositoryNotFoundError",
+    "MigrationError",
+    "ProjectAlreadyInitializedError",
+    "ProjectNotInitializedError",
+    "RestoreSafetyError",
+    "StorageError",
+]