framework-m 0.7.2__tar.gz → 0.8.0__tar.gz

{framework_m-0.7.2 → framework_m-0.8.0}/CHANGELOG.md

@@ -1,4 +1,15 @@
-**framework-m** v0.7.2: internal dependency bump due to **framework-m-core** update**framework-m** v0.7.1: internal dependency bump due to **framework-m-studio** update## framework-m v0.7.0
+## framework-m v0.8.0
+
+### Features
+
+- pagination, tabbed layout and dynamic fields in desk (86b5e66)
+
+### Bug Fixes
+
+- clarify use aiosqlite for db url in test (981c6c4)
+- typecheck error (1e06770)
+
+**framework-m** v0.7.3: internal dependency bump due to **framework-m-core** update**framework-m** v0.7.2: internal dependency bump due to **framework-m-core** update**framework-m** v0.7.1: internal dependency bump due to **framework-m-studio** update## framework-m v0.7.0
 
 ### Features
 

{framework_m-0.7.2 → framework_m-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framework-m
-Version: 0.7.2
+Version: 0.8.0
 Summary: A modular, metadata-driven business application framework
 Project-URL: Homepage, https://gitlab.com/castlecraft/framework-m
 Project-URL: Documentation, https://gitlab.com/castlecraft/framework-m#readme
@@ -18,8 +18,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: framework-m-core>=0.12.0
-Requires-Dist: framework-m-standard>=0.9.0
+Requires-Dist: framework-m-core>=0.14.0
+Requires-Dist: framework-m-standard>=0.11.0
 Description-Content-Type: text/markdown
 
 # Framework M

{framework_m-0.7.2 → framework_m-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "framework-m"
-version = "0.7.2"
+version = "0.8.0"
 description = "A modular, metadata-driven business application framework"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -21,8 +21,8 @@ classifiers = [
 ]
 
 dependencies = [
-    "framework-m-core>=0.12.0",
-    "framework-m-standard>=0.9.0",
+    "framework-m-core>=0.14.0",
+    "framework-m-standard>=0.11.0",
 ]
 
 [tool.uv.sources]
@@ -83,8 +83,11 @@ filterwarnings = [
 ]
 
 [tool.coverage.run]
-source = ["src/framework_m"]
 branch = true
+omit = [
+    "*/tests/*",
+    "*conftest.py",
+]
 
 [tool.coverage.report]
 exclude_lines = [

framework_m-0.8.0/src/framework_m/core/services/__init__.py

@@ -0,0 +1,5 @@
+"""Service-layer components for Framework M."""
+
+from framework_m.core.services.correction import CorrectionService
+
+__all__ = ["CorrectionService"]

framework_m-0.8.0/src/framework_m/core/services/correction.py

@@ -0,0 +1,179 @@
+"""Correction service implementing amend, restore, and in-place edit flows."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from framework_m_core.domain.base_controller import BaseController
+from framework_m_core.domain.base_doctype import BaseDocType
+from framework_m_core.domain.mixins import DocStatus
+from framework_m_core.interfaces.audit import AuditLogProtocol
+from framework_m_core.interfaces.auth_context import UserContext
+from framework_m_core.interfaces.repository import RepositoryProtocol
+
+
+class CorrectionService:
+    """Service for RFC-0008 correction workflows on submitted documents."""
+
+    def __init__(
+        self,
+        repository: RepositoryProtocol[BaseDocType],
+        audit: AuditLogProtocol,
+    ) -> None:
+        self._repository = repository
+        self._audit = audit
+
+    async def amend(
+        self,
+        doc: BaseDocType,
+        reason: str,
+        user: UserContext,
+    ) -> BaseDocType:
+        """Cancel submitted doc and create a new draft copy with incremented name."""
+        self._ensure_submitted(doc)
+
+        cancelled = doc.model_copy(deep=True)
+        if hasattr(cancelled, "docstatus"):
+            cancelled.docstatus = DocStatus.CANCELLED
+        await self._repository.save(cancelled)
+
+        amended = self._clone_with_updates(
+            source=doc,
+            new_name=self._next_amended_name(doc.name),
+            docstatus=DocStatus.DRAFT,
+            drop_id=True,
+        )
+        saved_amended = await self._repository.save(amended)
+
+        await self._audit.log(
+            user_id=user.id,
+            action="amend",
+            doctype=type(doc).__name__,
+            document_id=self._document_ref(doc),
+            changes=None,
+            metadata={"reason": reason},
+        )
+
+        return saved_amended
+
+    async def restore(
+        self,
+        doc: BaseDocType,
+        snapshot_data: dict[str, Any],
+        reason: str,
+        user: UserContext,
+    ) -> BaseDocType:
+        """Cancel submitted doc and recreate a submitted document from snapshot data."""
+        self._ensure_submitted(doc)
+        if not snapshot_data:
+            raise ValueError("snapshot_data cannot be empty")
+
+        cancelled = doc.model_copy(deep=True)
+        if hasattr(cancelled, "docstatus"):
+            cancelled.docstatus = DocStatus.CANCELLED
+        await self._repository.save(cancelled)
+
+        restored_data = dict(snapshot_data)
+        restored_data.pop("id", None)
+        restored_data["name"] = self._next_amended_name(doc.name)
+        restored_data["docstatus"] = DocStatus.SUBMITTED
+
+        restored_doc = type(doc).model_validate(restored_data)
+        saved_restored = await self._repository.save(restored_doc)
+
+        await self._audit.log(
+            user_id=user.id,
+            action="restore",
+            doctype=type(doc).__name__,
+            document_id=self._document_ref(doc),
+            changes=None,
+            metadata={"reason": reason},
+        )
+
+        return saved_restored
+
+    async def in_place_edit(
+        self,
+        doc: BaseDocType,
+        reason: str,
+        user: UserContext,
+    ) -> BaseDocType:
+        """Keep same document identity, snapshot history, then reset to draft."""
+        if not getattr(type(doc), "_versioning_enabled", False):
+            raise ValueError("in_place_edit requires VersionedMixin")
+
+        self._ensure_submitted(doc)
+
+        history_snapshot = doc.model_copy(deep=True)
+        await self._repository.save(history_snapshot)
+
+        editable = doc.model_copy(deep=True)
+        if hasattr(editable, "docstatus"):
+            editable.docstatus = DocStatus.DRAFT
+
+        controller: BaseController[BaseDocType] = BaseController(editable)
+        await controller._validate_submitted_changes(editable, doc)
+
+        saved_editable = await self._repository.save(editable)
+
+        await self._audit.log(
+            user_id=user.id,
+            action="in_place_edit",
+            doctype=type(doc).__name__,
+            document_id=self._document_ref(doc),
+            changes=None,
+            metadata={"reason": reason},
+        )
+
+        return saved_editable
+
+    def _next_amended_name(self, name: str | None) -> str:
+        """Return incremented amended name: INV-001 -> INV-001-1, INV-001-1 -> INV-001-2."""
+        base_name = name or "DOC"
+        # Only treat trailing numeric segment as amendment counter when
+        # a prior amendment segment already exists (at least 2 hyphens).
+        if base_name.count("-") < 2:
+            return f"{base_name}-1"
+
+        match = re.match(r"^(.*)-(\d+)$", base_name)
+        if match is None:
+            return f"{base_name}-1"
+
+        prefix = match.group(1)
+        number = int(match.group(2))
+        return f"{prefix}-{number + 1}"
+
+    def _ensure_submitted(self, doc: BaseDocType) -> None:
+        """Validate that the document is in submitted state."""
+        if not hasattr(doc, "docstatus"):
+            raise ValueError("Only submitted documents can be corrected")
+
+        if doc.docstatus != DocStatus.SUBMITTED:
+            raise ValueError("Only submitted documents can be corrected")
+
+    def _clone_with_updates(
+        self,
+        source: BaseDocType,
+        new_name: str,
+        docstatus: DocStatus,
+        *,
+        drop_id: bool,
+    ) -> BaseDocType:
+        """Clone a document and apply correction-flow identity/status updates."""
+        data = source.model_dump(mode="python")
+        if drop_id:
+            data.pop("id", None)
+        data["name"] = new_name
+        if "docstatus" in type(source).model_fields:
+            data["docstatus"] = docstatus
+        return type(source).model_validate(data)
+
+    def _document_ref(self, doc: BaseDocType) -> str:
+        """Return preferred audit document reference (name first, then id)."""
+        if doc.name:
+            return str(doc.name)
+        return str(doc.id)
+
+
+__all__ = ["CorrectionService"]

{framework_m-0.7.2 → framework_m-0.8.0}/tests/conftest.py

@@ -101,7 +101,7 @@ def configured_container() -> Container:
     container = Container()
     container.config.from_dict(
         {
-            "database_url": "sqlite:///:memory:",
+            "database_url": "sqlite+aiosqlite:///:memory:",
             "debug": True,
             "app_name": "TestApp",
         }

framework_m-0.8.0/tests/core/test_correction_service.py

@@ -0,0 +1,425 @@
+"""Tests for CorrectionService (RFC-0008 Step 8.1)."""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from framework_m_core.domain.base_doctype import BaseDocType, Field
+from framework_m_core.domain.mixins import DocStatus, SubmittableMixin, VersionedMixin
+from framework_m_core.interfaces.audit import AuditLogProtocol
+from framework_m_core.interfaces.auth_context import UserContext
+from framework_m_core.interfaces.repository import RepositoryProtocol
+from pydantic import ConfigDict
+
+from framework_m.core.services.correction import CorrectionService
+
+
+class Invoice(BaseDocType, SubmittableMixin):
+    """Test invoice doctype for correction-flow tests."""
+
+    customer: str = Field(description="Customer")
+    amount: float = Field(default=0.0, description="Amount")
+
+
+class VersionedInvoice(Invoice, VersionedMixin):
+    """Versioned invoice doctype for in-place correction tests."""
+
+
+class PlainDoc(BaseDocType):
+    """Plain doc without SubmittableMixin for edge cases."""
+
+    title: str = Field(default="Test")
+    model_config = ConfigDict(extra="ignore")
+
+
+class PlainVersionedDoc(PlainDoc, VersionedMixin):
+    """Versioned plain doc for in-place edge cases."""
+
+
+@pytest.fixture
+def mock_repository() -> AsyncMock:
+    """Repository mock implementing save semantics."""
+
+    def _save(entity: BaseDocType, version: int | None = None) -> BaseDocType:
+        _ = version
+        return entity
+
+    repo = AsyncMock(spec=RepositoryProtocol[BaseDocType])
+    repo.save = AsyncMock(side_effect=_save)
+    return repo
+
+
+@pytest.fixture
+def mock_audit_adapter() -> AsyncMock:
+    """Audit adapter mock for correction-flow logging."""
+    audit = AsyncMock(spec=AuditLogProtocol)
+    audit.log = AsyncMock(return_value="audit-entry-001")
+    return audit
+
+
+@pytest.fixture
+def service(
+    mock_repository: AsyncMock,
+    mock_audit_adapter: AsyncMock,
+) -> CorrectionService:
+    """CorrectionService under test."""
+    return CorrectionService(
+        repository=mock_repository,
+        audit=mock_audit_adapter,
+    )
+
+
+@pytest.fixture
+def user_context() -> UserContext:
+    """User context fixture for audit metadata."""
+    return UserContext(
+        id="user-001",
+        email="user-001@example.com",
+        name="Test User",
+        roles=["Employee"],
+    )
+
+
+@pytest.fixture
+def submitted_invoice() -> Invoice:
+    """Submitted invoice fixture for amend/restore tests."""
+    return Invoice(
+        name="INV-001",
+        customer="Acme",
+        amount=100.0,
+        docstatus=DocStatus.SUBMITTED,
+    )
+
+
+@pytest.fixture
+def versioned_submitted_invoice() -> VersionedInvoice:
+    """Submitted versioned invoice fixture for in-place edit tests."""
+    return VersionedInvoice(
+        name="INV-001",
+        customer="Acme",
+        amount=100.0,
+        docstatus=DocStatus.SUBMITTED,
+    )
+
+
+class TestCorrectionServiceAmend:
+    """Amend flow tests."""
+
+    @pytest.mark.asyncio
+    async def test_amend_cancels_original_and_creates_new_draft(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        mock_audit_adapter: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        result = await service.amend(
+            doc=submitted_invoice,
+            reason="Typo fix",
+            user=user_context,
+        )
+
+        assert result.docstatus == DocStatus.DRAFT
+        assert result.name == "INV-001-1"
+        assert result.id != submitted_invoice.id
+
+        assert mock_repository.save.await_count == 2
+
+        cancelled_doc = mock_repository.save.await_args_list[0].args[0]
+        amended_doc = mock_repository.save.await_args_list[1].args[0]
+
+        assert cancelled_doc.docstatus == DocStatus.CANCELLED
+        assert cancelled_doc.name == "INV-001"
+
+        assert amended_doc.docstatus == DocStatus.DRAFT
+        assert amended_doc.name == "INV-001-1"
+
+        mock_audit_adapter.log.assert_awaited_once_with(
+            user_id=user_context.id,
+            action="amend",
+            doctype="Invoice",
+            document_id="INV-001",
+            changes=None,
+            metadata={"reason": "Typo fix"},
+        )
+
+    def test_amend_name_increments_correctly(self, service: CorrectionService) -> None:
+        assert service._next_amended_name("INV-001") == "INV-001-1"
+        assert service._next_amended_name("INV-001-1") == "INV-001-2"
+
+    @pytest.mark.asyncio
+    async def test_amend_raises_if_not_submitted(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        draft = submitted_invoice.model_copy(deep=True)
+        draft.docstatus = DocStatus.DRAFT
+
+        with pytest.raises(ValueError):
+            await service.amend(
+                doc=draft,
+                reason="Need correction",
+                user=user_context,
+            )
+
+        mock_repository.save.assert_not_awaited()
+
+    @pytest.mark.asyncio
+    async def test_amend_audit_failure_propagates(
+        self,
+        service: CorrectionService,
+        mock_audit_adapter: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        mock_audit_adapter.log.side_effect = RuntimeError("audit write failed")
+
+        with pytest.raises(RuntimeError, match="audit write failed"):
+            await service.amend(
+                doc=submitted_invoice,
+                reason="Typo fix",
+                user=user_context,
+            )
+
+
+class TestCorrectionServiceRestore:
+    """Restore flow tests."""
+
+    @pytest.mark.asyncio
+    async def test_restore_cancels_original_and_creates_snapshot_doc(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        mock_audit_adapter: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        snapshot_data: dict[str, Any] = {
+            "customer": "Acme Restored",
+            "amount": 120.0,
+        }
+
+        result = await service.restore(
+            doc=submitted_invoice,
+            snapshot_data=snapshot_data,
+            reason="Rollback to prior snapshot",
+            user=user_context,
+        )
+
+        assert result.name == "INV-001-1"
+        assert result.docstatus == DocStatus.SUBMITTED
+
+        assert mock_repository.save.await_count == 2
+
+        cancelled_doc = mock_repository.save.await_args_list[0].args[0]
+        restored_doc = mock_repository.save.await_args_list[1].args[0]
+
+        assert cancelled_doc.docstatus == DocStatus.CANCELLED
+        assert restored_doc.docstatus == DocStatus.SUBMITTED
+        assert restored_doc.customer == "Acme Restored"
+
+        mock_audit_adapter.log.assert_awaited_once_with(
+            user_id=user_context.id,
+            action="restore",
+            doctype="Invoice",
+            document_id="INV-001",
+            changes=None,
+            metadata={"reason": "Rollback to prior snapshot"},
+        )
+
+    @pytest.mark.asyncio
+    async def test_restore_raises_if_not_submitted(
+        self,
+        service: CorrectionService,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        draft = submitted_invoice.model_copy(deep=True)
+        draft.docstatus = DocStatus.DRAFT
+
+        with pytest.raises(ValueError):
+            await service.restore(
+                doc=draft,
+                snapshot_data={"customer": "Acme"},
+                reason="Invalid state",
+                user=user_context,
+            )
+
+
+class TestCorrectionServiceEdgeCases:
+    """Coverage tests for defensive checks and edge cases."""
+
+    def test_next_amended_name_unmatchable_pattern(
+        self, service: CorrectionService
+    ) -> None:
+        """Cover branch where regex match is None."""
+        assert service._next_amended_name("INV-001-A") == "INV-001-A-1"
+
+    def test_ensure_submitted_without_docstatus(
+        self, service: CorrectionService
+    ) -> None:
+        """Cover branch where doc has no docstatus attribute."""
+        doc = PlainDoc(name="PLAIN-1")
+        with pytest.raises(
+            ValueError, match="Only submitted documents can be corrected"
+        ):
+            service._ensure_submitted(doc)
+
+    def test_clone_with_updates_keep_id_and_no_docstatus(
+        self, service: CorrectionService
+    ) -> None:
+        """Cover branches for drop_id=False and missing docstatus field."""
+        doc = PlainDoc(name="PLAIN-1")
+        cloned = service._clone_with_updates(
+            source=doc,
+            new_name="PLAIN-2",
+            docstatus=DocStatus.DRAFT,
+            drop_id=False,
+        )
+        assert cloned.id == doc.id
+        assert cloned.name == "PLAIN-2"
+        assert not hasattr(cloned, "docstatus")
+
+    def test_document_ref_without_name(self, service: CorrectionService) -> None:
+        """Cover branch where doc.name is None/empty."""
+        doc = PlainDoc(name="")
+        assert service._document_ref(doc) == str(doc.id)
+
+    @pytest.mark.asyncio
+    @patch.object(CorrectionService, "_ensure_submitted")
+    async def test_amend_without_copied_docstatus(
+        self,
+        mock_ensure: Any,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        user_context: UserContext,
+    ) -> None:
+        """Cover hasattr(cancelled, 'docstatus') == False branch."""
+        doc = PlainDoc(name="PLAIN-1")
+        await service.amend(doc, "Test", user_context)
+        cancelled_doc = mock_repository.save.await_args_list[0].args[0]
+        assert not hasattr(cancelled_doc, "docstatus")
+
+    @pytest.mark.asyncio
+    @patch.object(CorrectionService, "_ensure_submitted")
+    async def test_restore_without_copied_docstatus(
+        self,
+        mock_ensure: Any,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        user_context: UserContext,
+    ) -> None:
+        """Cover hasattr(cancelled, 'docstatus') == False branch."""
+        doc = PlainDoc(name="PLAIN-1")
+        await service.restore(doc, {"title": "Restored"}, "Test", user_context)
+        cancelled_doc = mock_repository.save.await_args_list[0].args[0]
+        assert not hasattr(cancelled_doc, "docstatus")
+
+    @pytest.mark.asyncio
+    @patch.object(CorrectionService, "_ensure_submitted")
+    async def test_in_place_edit_without_copied_docstatus(
+        self,
+        mock_ensure: Any,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        user_context: UserContext,
+    ) -> None:
+        """Cover hasattr(editable, 'docstatus') == False branch."""
+        doc = PlainVersionedDoc(name="PLAIN-1")
+        await service.in_place_edit(doc, "Test", user_context)
+        editable_doc = mock_repository.save.await_args_list[1].args[0]
+        assert not hasattr(editable_doc, "docstatus")
+
+    @pytest.mark.asyncio
+    async def test_restore_raises_if_snapshot_empty(
+        self,
+        service: CorrectionService,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        with pytest.raises(ValueError, match="snapshot_data cannot be empty"):
+            await service.restore(
+                doc=submitted_invoice,
+                snapshot_data={},
+                reason="Missing snapshot",
+                user=user_context,
+            )
+
+
+class TestCorrectionServiceInPlaceEdit:
+    """In-place edit flow tests."""
+
+    @pytest.mark.asyncio
+    async def test_in_place_edit_copies_to_history_and_resets_to_draft(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        mock_audit_adapter: AsyncMock,
+        versioned_submitted_invoice: VersionedInvoice,
+        user_context: UserContext,
+    ) -> None:
+        result = await service.in_place_edit(
+            doc=versioned_submitted_invoice,
+            reason="Operational correction",
+            user=user_context,
+        )
+
+        assert result.id == versioned_submitted_invoice.id
+        assert result.name == versioned_submitted_invoice.name
+        assert result.docstatus == DocStatus.DRAFT
+
+        assert mock_repository.save.await_count == 2
+
+        history_snapshot_doc = mock_repository.save.await_args_list[0].args[0]
+        editable_doc = mock_repository.save.await_args_list[1].args[0]
+
+        assert history_snapshot_doc.docstatus == DocStatus.SUBMITTED
+        assert editable_doc.docstatus == DocStatus.DRAFT
+        assert editable_doc.id == versioned_submitted_invoice.id
+        assert editable_doc.name == versioned_submitted_invoice.name
+
+        mock_audit_adapter.log.assert_awaited_once_with(
+            user_id=user_context.id,
+            action="in_place_edit",
+            doctype="VersionedInvoice",
+            document_id="INV-001",
+            changes=None,
+            metadata={"reason": "Operational correction"},
+        )
+
+    @pytest.mark.asyncio
+    async def test_in_place_edit_raises_if_not_versioned(
+        self,
+        service: CorrectionService,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        with pytest.raises(ValueError, match="in_place_edit requires VersionedMixin"):
+            await service.in_place_edit(
+                doc=submitted_invoice,
+                reason="Invalid flow",
+                user=user_context,
+            )
+
+    @pytest.mark.asyncio
+    async def test_in_place_edit_raises_if_not_submitted(
+        self,
+        service: CorrectionService,
+        versioned_submitted_invoice: VersionedInvoice,
+        user_context: UserContext,
+    ) -> None:
+        draft = versioned_submitted_invoice.model_copy(deep=True)
+        draft.docstatus = DocStatus.DRAFT
+
+        with pytest.raises(ValueError):
+            await service.in_place_edit(
+                doc=draft,
+                reason="Invalid state",
+                user=user_context,
+            )