fushinryu-model 0.1.0__py3-none-any.whl

fushinryu_model/__init__.py

@@ -0,0 +1,25 @@
+"""Domain model for the Fūshinryū (風心流) development projects management methodology."""
+
+from fushinryu_model.acceptance_criterion import AcceptanceCriterion
+from fushinryu_model.acceptance_criterion_validation import (
+    AutomatedValidation,
+    ManualValidation,
+    ValidationEntry,
+)
+from fushinryu_model.scope import Scope
+from fushinryu_model.user_story import UserStory, UserStoryType
+
+NAME = "fushinryu-model"
+VERSION = "0.1.0"
+
+__all__ = [
+    "AcceptanceCriterion",
+    "AutomatedValidation",
+    "ManualValidation",
+    "NAME",
+    "Scope",
+    "UserStory",
+    "UserStoryType",
+    "ValidationEntry",
+    "VERSION",
+]

fushinryu_model/_merge_utils.py

@@ -0,0 +1,31 @@
+"""Private utilities for merging collections of domain entities by integer id."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pleroma.contrib.pydantic import MergeableModel
+
+T = TypeVar("T", bound=MergeableModel)
+
+
+def merge_by_id(parent: frozenset[T], child: frozenset[T]) -> frozenset[T]:
+    """Merges two frozensets of entities keyed by their integer ``id`` field.
+
+    For entities present in both sets (same id), the child entity is merged into
+    the parent using the entity's own :meth:`~pleroma.MergeableModel.merge` method,
+    so child field values override parent field values. Entities present in only one
+    set are included as-is.
+
+    :param parent: The base collection.
+    :param child: The overriding collection.
+    :return: A new frozenset containing all entities from both collections.
+    """
+    result: dict[int, Any] = {item.id: item for item in parent}  # type: ignore[attr-defined]
+    for item in child:
+        item_id: int = item.id  # type: ignore[attr-defined]
+        if item_id in result:
+            result[item_id] = type(item).merge([result[item_id], item])
+        else:
+            result[item_id] = item
+    return frozenset(result.values())

fushinryu_model/acceptance_criterion.py

@@ -0,0 +1,69 @@
+"""AcceptanceCriterion domain entity for the fushinryu methodology model."""
+
+from __future__ import annotations
+
+from typing import Any, Self
+
+from pleroma.contrib.pydantic import MergeableModel
+
+from fushinryu_model.acceptance_criterion_validation import (
+    AutomatedValidation,
+    ManualValidation,
+    ValidationEntry,
+)
+
+
+def _merge_validations(
+    parent: frozenset[ValidationEntry],
+    child: frozenset[ValidationEntry],
+) -> frozenset[ValidationEntry]:
+    manual: set[ManualValidation] = set()
+    auto_by_key: dict[tuple[str, str], AutomatedValidation] = {}
+
+    for v in parent | child:
+        if isinstance(v, ManualValidation):
+            manual.add(v)
+        else:
+            key = (v.source, v.name)
+            if key not in auto_by_key or v.timestamp > auto_by_key[key].timestamp:
+                auto_by_key[key] = v
+
+    return frozenset(manual | set(auto_by_key.values()))
+
+
+class AcceptanceCriterion(MergeableModel):
+    """A testable condition attached to a UserStory.
+
+    :param id: Integer identifier, unique within the enclosing UserStory.
+    :param given: Optional description of the initial context or state.
+    :param when: Optional description of the trigger condition.
+    :param then: Mandatory description of the expected outcome.
+    :param active: Whether this criterion is an active requirement.
+        Set to ``False`` when a criterion is discarded without removing it.
+    :param validations: Validation records attached to this criterion.
+        An AC is considered validated when this set is non-empty and every
+        record has ``passed=True``.
+    """
+
+    id: int
+    given: str | None = None
+    when: str | None = None
+    then: str
+    active: bool = True
+    validations: frozenset[ValidationEntry] = frozenset()
+
+    @property
+    def is_validated(self) -> bool:
+        """Return True when all validations are present and passed."""
+        return bool(self.validations) and all(v.passed for v in self.validations)
+
+    def _merge_two(self, other: Self, *, overwrite_none: bool = False) -> Self:
+        kwargs: dict[str, Any] = {}
+        for name in type(self).model_fields:
+            if name == "validations":
+                continue
+            self_val: Any = getattr(self, name)
+            other_val: Any = getattr(other, name)
+            kwargs[name] = other_val if (overwrite_none or other_val is not None) else self_val
+        kwargs["validations"] = _merge_validations(self.validations, other.validations)
+        return type(self)(**kwargs)

fushinryu_model/acceptance_criterion_validation.py

@@ -0,0 +1,61 @@
+"""Validation record types for AcceptanceCriterion fulfillment tracking."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class AcceptanceCriterionValidation(BaseModel):
+    """Base class for a validation record attached to an AcceptanceCriterion.
+
+    :param passed: Whether the criterion passed this validation.
+    :param timestamp: When the validation was recorded (must be timezone-aware).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    passed: bool = False
+    timestamp: datetime
+
+    @field_validator("timestamp")
+    @classmethod
+    def _require_timezone(cls, v: datetime) -> datetime:
+        if v.tzinfo is None:
+            raise ValueError("timestamp must be timezone-aware")
+        return v
+
+
+class ManualValidation(AcceptanceCriterionValidation):
+    """A human-authored validation record.
+
+    :param verdict: Description of why the criterion passed or failed.
+    :param kind: Discriminator field, always ``"manual"``.
+    """
+
+    kind: Literal["manual"] = "manual"
+    verdict: str
+
+
+class AutomatedValidation(AcceptanceCriterionValidation):
+    """A test-linked validation record.
+
+    When two automated validations share the same ``source`` and ``name`` for a
+    given criterion, the one with the most recent ``timestamp`` prevails on merge.
+
+    :param source: The file, class, or module where the validation procedure lives.
+    :param name: The test or check name within that source.
+    :param kind: Discriminator field, always ``"automated"``.
+    """
+
+    kind: Literal["automated"] = "automated"
+    source: str
+    name: str
+
+
+ValidationEntry = Annotated[
+    ManualValidation | AutomatedValidation,
+    Field(discriminator="kind"),
+]

fushinryu_model/scope.py

@@ -0,0 +1,114 @@
+"""Scope domain entity for the fushinryu methodology model."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Self
+
+from pydantic import field_validator
+from pleroma.contrib.pydantic import MergeableModel
+
+from fushinryu_model._merge_utils import merge_by_id
+from fushinryu_model.user_story import UserStory
+
+_ID_PATTERN = re.compile(r"(_[a-zA-Z]|[a-zA-Z])[a-zA-Z0-9_]*")
+
+
+def _dfs_linearize(root: Scope) -> list[Scope]:
+    """Returns scopes in decreasing precedence order (root first, base last).
+
+    Uses DFS pre-order traversal with last-occurrence deduplication: when a
+    scope is visited more than once (shared ancestor), the later visit wins,
+    pushing the ancestor toward the end (lowest precedence).
+
+    :param root: The scope to linearise.
+    :return: List of scopes from highest to lowest merge precedence.
+    :raises ValueError: If a cycle is detected in the parent graph.
+    """
+    last_visit: dict[str, int] = {}
+    scope_map: dict[str, Scope] = {}
+    visiting: set[str] = set()
+    counter: list[int] = [0]
+
+    def _visit(scope: Scope) -> None:
+        if scope.id in visiting:
+            raise ValueError(f"Cycle detected involving scope '{scope.id}'")
+        visiting.add(scope.id)
+        last_visit[scope.id] = counter[0]
+        scope_map[scope.id] = scope
+        counter[0] += 1
+        for parent in scope.parents:
+            _visit(parent)
+        visiting.discard(scope.id)
+
+    _visit(root)
+    return sorted(scope_map.values(), key=lambda s: last_visit[s.id])
+
+
+class Scope(MergeableModel):
+    """An organizational unit grouping related project artifacts.
+
+    :param name: Human-readable display name for the scope.
+    :param id: Identifier following programming variable naming conventions:
+        starts with a letter or underscore-then-letter, followed by letters,
+        digits, or underscores.
+    :param description: A description of the scope's purpose.
+    :param user_stories: The high-level requirements belonging to this scope.
+        Each story's id must be unique within this scope.
+    :param parents: Ordered parent scopes forming a directed acyclic graph.
+        The first parent takes precedence over subsequent parents during
+        collapse. Defaults to an empty sequence (no parents).
+    """
+
+    name: str
+    id: str
+    description: str
+    user_stories: frozenset[UserStory] = frozenset()
+    parents: tuple[Scope, ...] = ()
+
+    @field_validator("id")
+    @classmethod
+    def _validate_id(cls, v: str) -> str:
+        if not _ID_PATTERN.fullmatch(v):
+            raise ValueError(
+                "id must follow identifier naming: starts with a letter or _+letter, "
+                "followed by letters, digits, or underscores"
+            )
+        return v
+
+    @field_validator("user_stories")
+    @classmethod
+    def _validate_unique_us_ids(cls, v: frozenset[UserStory]) -> frozenset[UserStory]:
+        ids = [us.id for us in v]
+        if len(ids) != len(set(ids)):
+            raise ValueError("user_stories ids must be unique within a Scope")
+        return v
+
+    def _merge_two(self, other: Self, *, overwrite_none: bool = False) -> Self:
+        kwargs: dict[str, Any] = {}
+        for name in type(self).model_fields:
+            self_val: Any = getattr(self, name)
+            other_val: Any = getattr(other, name)
+            kwargs[name] = other_val if (overwrite_none or other_val is not None) else self_val
+        kwargs["user_stories"] = merge_by_id(self.user_stories, other.user_stories)
+        return type(self)(**kwargs)
+
+    def collapse(self) -> Scope:
+        """Merges the full scope hierarchy into a single flat Scope.
+
+        Linearises the ancestor DAG using DFS pre-order with last-occurrence
+        deduplication, then merges all scopes from lowest to highest precedence.
+        The returned scope has no parents.
+
+        :return: A new Scope representing the effective merged scope.
+        :raises ValueError: If a cycle is detected in the parent graph.
+        """
+        order = _dfs_linearize(self)
+        flat = [s.model_copy(update={"parents": ()}) for s in order]
+        result = flat[-1]
+        for scope in flat[-2::-1]:
+            result = type(self).merge([result, scope])
+        return result
+
+
+Scope.model_rebuild()

fushinryu_model/user_story.py

@@ -0,0 +1,73 @@
+"""UserStory domain entity for the fushinryu methodology model."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Self
+
+from pydantic import field_validator
+from pleroma.contrib.pydantic import MergeableModel
+
+from fushinryu_model._merge_utils import merge_by_id
+from fushinryu_model.acceptance_criterion import AcceptanceCriterion
+
+
+class UserStoryType(str, Enum):
+    """Classifies a UserStory as functional or technical."""
+
+    FUNCTIONAL = "functional"
+    TECHNICAL = "technical"
+
+
+class UserStory(MergeableModel):
+    """A high-level requirement scoped to an organizational unit.
+
+    :param id: Integer identifier, unique within the enclosing Scope.
+    :param who: The role or persona that wants the feature.
+    :param what: The capability or behaviour desired.
+    :param why: The business or technical justification.
+    :param type: Whether the story is functional or technical.
+    :param active: Whether this story is an active requirement.
+        Set to ``False`` when a story is retired without removing it.
+        An inactive story implicitly deactivates all its acceptance criteria
+        for validation purposes.
+    :param acceptance_criteria: The testable conditions defining completion.
+        Each criterion's id must be unique within this story.
+    """
+
+    id: int
+    who: str
+    what: str
+    why: str
+    type: UserStoryType
+    active: bool = True
+    acceptance_criteria: frozenset[AcceptanceCriterion] = frozenset()
+
+    @field_validator("acceptance_criteria")
+    @classmethod
+    def _validate_unique_ac_ids(
+        cls, v: frozenset[AcceptanceCriterion]
+    ) -> frozenset[AcceptanceCriterion]:
+        ids = [ac.id for ac in v]
+        if len(ids) != len(set(ids)):
+            raise ValueError("acceptance_criteria ids must be unique within a UserStory")
+        return v
+
+    @property
+    def is_validated(self) -> bool:
+        """Return True when the story is active, has active criteria, and all are validated."""
+        if not self.active:
+            return False
+        active = [ac for ac in self.acceptance_criteria if ac.active]
+        return bool(active) and all(ac.is_validated for ac in active)
+
+    def _merge_two(self, other: Self, *, overwrite_none: bool = False) -> Self:
+        kwargs: dict[str, Any] = {}
+        for name in type(self).model_fields:
+            self_val: Any = getattr(self, name)
+            other_val: Any = getattr(other, name)
+            kwargs[name] = other_val if (overwrite_none or other_val is not None) else self_val
+        kwargs["acceptance_criteria"] = merge_by_id(
+            self.acceptance_criteria, other.acceptance_criteria
+        )
+        return type(self)(**kwargs)

fushinryu_model-0.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: fushinryu-model
+Version: 0.1.0
+Summary: Model of the Fushinryu development projects management methodology.
+Project-URL: Repository, https://gitlab.com/Kencho1/fushinryu-model
+Project-URL: Documentation, https://fushinryu-model.readthedocs.io
+Author: Jesús Alonso Abad
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.11
+Requires-Dist: pleroma>=0.2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: mypy~=1.8; extra == 'test'
+Requires-Dist: pytest-cov~=6.0; extra == 'test'
+Requires-Dist: pytest-mark-ac~=1.1; extra == 'test'
+Requires-Dist: pytest~=8.3; extra == 'test'
+Requires-Dist: pyyaml~=6.0; extra == 'test'
+Requires-Dist: ruff~=0.8; extra == 'test'
+Requires-Dist: tox~=4.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# fushinryu-model
+
+Model of the Fūshinryū (風心流) development projects management methodology.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
+[![Documentation](https://readthedocs.org/projects/fushinryu-model/badge/?version=latest)](https://fushinryu-model.readthedocs.io)
+
+## Install
+
+```
+pip install fushinryu-model
+```
+
+## Quick example
+
+```python
+from datetime import datetime, timezone
+from fushinryu_model import AcceptanceCriterion, ManualValidation
+
+ac = AcceptanceCriterion(id=1, then="the system returns HTTP 200")
+validation = ManualValidation(verdict="verified manually", passed=True, timestamp=datetime.now(timezone.utc))
+ac = ac.model_copy(update={"validations": frozenset([validation])})
+assert ac.is_validated
+```
+
+Full documentation: <https://fushinryu-model.readthedocs.io>

fushinryu_model-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fushinryu_model/__init__.py,sha256=sj7dqQcvXPhcBZkZ5AFxk6HP2glhShWNLwzwGQXsFnM,640
+fushinryu_model/_merge_utils.py,sha256=y8SJCZSDfJQHFRpLx4xq-Y11ZFPdd3t6eNOmxna2guQ,1216
+fushinryu_model/acceptance_criterion.py,sha256=L2gtyjIHfRquz8OqgDI4y4m2yBbDey5hnONuZNbmG1I,2523
+fushinryu_model/acceptance_criterion_validation.py,sha256=oEN9-hNWvHznz4Ng6Xl3ouhBiIMgbf7OhUv0CFMRLFs,1807
+fushinryu_model/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fushinryu_model/scope.py,sha256=-X5gLw0OOy3npOfFKAu47Q1o9w3VRjB_EJqCA_KYcrQ,4278
+fushinryu_model/user_story.py,sha256=0pER3SgDNt9EgZ7lE6G2S-5bUH6l3ms8mwhvEcZJyCo,2711
+fushinryu_model-0.1.0.dist-info/METADATA,sha256=IApfJ4zkYIF-qmqtnbmew78H2yt_R6faNykZAGuNP7g,2301
+fushinryu_model-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fushinryu_model-0.1.0.dist-info/licenses/LICENSE.md,sha256=uRNHhD7Ir7jDL77vGaOfzh-omRzVWtlIf7FZED1oXzA,1075
+fushinryu_model-0.1.0.dist-info/RECORD,,

fushinryu_model-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fushinryu_model-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesús Alonso Abad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.