ara-cli 0.1.9.69__py3-none-any.whl → 0.1.10.8__py3-none-any.whl

ara_cli/artefact_models/artefact_model.py

@@ -1,5 +1,5 @@
 from pydantic import BaseModel, Field, field_validator, model_validator
-from typing import Optional, List, Literal, Union, Dict
+from typing import Optional, List, Literal, Union, Dict, ClassVar
 from typing_extensions import Self
 from enum import Enum
 from abc import ABC, abstractmethod
@@ -47,13 +47,23 @@ class Contribution(BaseModel):
         description="Rule the contribution is using. The classifier of the parent must be userstory or epic if this is used"
     )
 
+    PLACEHOLDER_NAME: ClassVar[str] = "<filename or title of the artefact>"
+    PLACEHOLDER_CLASSIFIER: ClassVar[str] = "<agile requirement artefact category> <(optional in case the contribution is to an artefact that is detailed with rules)"
+    PLACEHOLDER_RULE: ClassVar[str] = "<rule as it is formulated>"
+
     @model_validator(mode="after")
     def validate_parent(self) -> Self:
-
         artefact_name = self.artefact_name
         classifier = self.classifier
         rule = self.rule
 
+        if (
+            artefact_name == Contribution.PLACEHOLDER_NAME
+            or classifier == Contribution.PLACEHOLDER_CLASSIFIER
+            or rule == Contribution.PLACEHOLDER_RULE
+        ):
+            return self
+
         if artefact_name:
             artefact_name = replace_space_with_underscore(artefact_name)
         if not artefact_name or not classifier:
@@ -68,7 +78,7 @@ class Contribution(BaseModel):
 
     @field_validator('artefact_name')
     def validate_artefact_name(cls, value):
-        if not value:
+        if not value or value == Contribution.PLACEHOLDER_NAME:
             return value
         if ' ' in value:
             warnings.warn(message="artefact_name can not contain spaces. Replacing spaces with '_'")
@@ -77,7 +87,7 @@ class Contribution(BaseModel):
 
     @field_validator('classifier', mode='after')
     def validate_classifier(cls, v):
-        if not v:
+        if not v or v == Contribution.PLACEHOLDER_CLASSIFIER:
             return v
         try:
             return ArtefactType(v)
@@ -91,12 +101,21 @@ class Contribution(BaseModel):
         if not line.startswith(contribution_line_start):
             raise ValueError(f"Contribution line '{line}' does not start with '{contribution_line_start}'")
 
+        parent_text = line[len(contribution_line_start):].strip()
+        rule_specifier = " using rule "
+
+        placeholder_line = f"{cls.PLACEHOLDER_NAME} {cls.PLACEHOLDER_CLASSIFIER}{rule_specifier}{cls.PLACEHOLDER_RULE}"
+        if parent_text == placeholder_line:
+            return cls(
+                artefact_name=cls.PLACEHOLDER_NAME,
+                classifier=cls.PLACEHOLDER_CLASSIFIER,
+                rule=cls.PLACEHOLDER_RULE
+            )
+
         artefact_name = None
         classifier = None
         rule = None
 
-        parent_text = line[len(contribution_line_start):].strip()
-        rule_specifier = " using rule "
         if rule_specifier in parent_text:
             parent_text, rule_text = parent_text.split(rule_specifier, 1)
             rule = rule_text
@@ -113,7 +132,7 @@ class Contribution(BaseModel):
     def serialize(self) -> str:
         if not self.classifier or not self.artefact_name:
             return ""
-        artefact_type = Classifier.get_artefact_title(self.classifier)
+        artefact_type = Classifier.get_artefact_title(self.classifier) or self.classifier
         artefact_name = replace_underscore_with_space(self.artefact_name)
         contribution = f"{artefact_name} {artefact_type}"
         if self.rule:
@@ -165,6 +184,10 @@ class Artefact(BaseModel, ABC):
         default=[],
         description="Optional list of tags (0-many)",
     )
+    author: Optional[str] = Field(
+        default="creator_unknown",
+        description="Author of the artefact, must be a single entry of the form 'creator_<someone>'."
+    )
     title: str = Field(
         ...,
         description="Descriptive Artefact title (mandatory)",
@@ -197,6 +220,15 @@ class Artefact(BaseModel, ABC):
         self._file_path = file_path
         return self
 
+    @model_validator(mode="after")
+    def validate_contribution(self):
+        contribution = self.contribution
+        classifier = self.artefact_type.value
+        name = self.title
+        if not contribution:
+            warnings.warn(f"Contribution of {classifier} '{name}' is not set and will be empty")
+        return self
+
     @field_validator('artefact_type')
     def validate_artefact_type(cls, v):
         if not isinstance(v, ArtefactType):
@@ -224,13 +256,28 @@ class Artefact(BaseModel, ABC):
                 raise ValueError(f"Tag '{tag}' has the form of a status tag. Set `status` field instead of passing it with other tags")
             if tag.startswith("user_"):
                 raise ValueError(f"Tag '{tag} has the form of a user tag. Set `users` field instead of passing it with other tags")
+            if tag.startswith("creator_"):
+                raise ValueError(f"Tag '{tag}' has the form of an author tag. Set `author` field instead of passing it with other tags")
+        return v
+
+    @field_validator('author')
+    def validate_author(cls, v):
+        if v:
+            if not v.startswith("creator_"):
+                raise ValueError(f"Author '{v}' must start with 'creator_'.")
+            if len(v) <= len("creator_"):
+                raise ValueError("Creator name cannot be empty in author tag.")
         return v
 
     @field_validator('title')
     def validate_title(cls, v):
         if not v.strip():
             raise ValueError("artefact_title must not be empty")
-        v = replace_space_with_underscore(v)
+        v = replace_space_with_underscore(v).strip()
+
+        whitelisted_placeholder = "<descriptive_title>"
+        if v == whitelisted_placeholder:
+            return v
 
         letters = list(string.ascii_letters)
         digits = list(string.digits)
@@ -243,12 +290,6 @@ class Artefact(BaseModel, ABC):
 
         return v
 
-    @field_validator('contribution')
-    def validate_contribution(cls, v):
-        if not v:
-            warnings.warn("Contribution is not set and will be empty")
-        return v
-
     @classmethod
     @abstractmethod
     def _title_prefix(cls) -> str:    # pragma: no cover
@@ -265,32 +306,81 @@ class Artefact(BaseModel, ABC):
         tag_line = lines[0]
         if not tag_line.startswith('@'):
             return {}, lines
+
         tags = tag_line.split()
+        tag_dict = cls._process_tags(tags)
+        return tag_dict, lines[1:]
+
+    @classmethod
+    def _process_tags(cls, tags) -> Dict[str, str]:
+        """Process a list of tags and return a dictionary with categorized tags."""
         status = None
         regular_tags = []
         users = []
-        status_list = ["@to-do", "@in-progress", "@review", "@done", "@closed"]
-        user_prefix = "@user_"
-        user_prefix_length = len(user_prefix)
-
+        author = None
+        
         for tag in tags:
-            if not tag.startswith('@'):
-                raise ValueError(f"Tag '{tag}' should start with '@' but started with '{tag[0]}'")
-            if tag in status_list and status is not None:
-                raise ValueError(f"Multiple status tags found: '@{status}' and '{tag}'")
-            if tag in status_list:
-                status = tag[1:]
-                continue
-            if tag.startswith("@user_") and len(tag) > user_prefix_length + 1:
-                users.append(tag[user_prefix_length:])
-                continue
-            regular_tags.append(tag[1:])
-        tag_dict = {
+            cls._validate_tag_format(tag)
+            
+            if cls._is_status_tag(tag):
+                status = cls._process_status_tag(tag, status)
+            elif cls._is_user_tag(tag):
+                users.append(cls._extract_user_from_tag(tag))
+            elif cls._is_author_tag(tag):
+                author = cls._process_author_tag(tag, author)
+            else:
+                regular_tags.append(tag[1:])
+        
+        return {
             "status": status,
             "users": users,
-            "tags": regular_tags
+            "tags": regular_tags,
+            "author": author
         }
-        return tag_dict, lines[1:]
+
+    @classmethod
+    def _validate_tag_format(cls, tag):
+        """Validate that tag starts with @."""
+        if not tag.startswith('@'):
+            raise ValueError(f"Tag '{tag}' should start with '@' but started with '{tag[0]}'")
+
+    @classmethod
+    def _is_status_tag(cls, tag) -> bool:
+        """Check if tag is a status tag."""
+        status_list = ["@to-do", "@in-progress", "@review", "@done", "@closed"]
+        return tag in status_list
+
+    @classmethod
+    def _process_status_tag(cls, tag, current_status):
+        """Process status tag and check for duplicates."""
+        if current_status is not None:
+            raise ValueError(f"Multiple status tags found: '@{current_status}' and '{tag}'")
+        return tag[1:]  # Remove @ prefix
+
+    @classmethod
+    def _is_user_tag(cls, tag) -> bool:
+        """Check if tag is a user tag."""
+        user_prefix = "@user_"
+        return tag.startswith(user_prefix) and len(tag) > len(user_prefix)
+
+    @classmethod
+    def _extract_user_from_tag(cls, tag) -> str:
+        """Extract username from user tag."""
+        user_prefix = "@user_"
+        return tag[len(user_prefix):]
+
+    @classmethod
+    def _is_author_tag(cls, tag) -> bool:
+        """Check if tag is an author tag."""
+        creator_prefix = "@creator_"
+        return tag.startswith(creator_prefix) and len(tag) > len(creator_prefix)
+
+    @classmethod
+    def _process_author_tag(cls, tag, current_author):
+        """Process author tag and check for duplicates."""
+        if current_author is not None:
+            raise ValueError(f"Multiple author tags found: '@{current_author}' and '@{tag[1:]}'")
+        return tag[1:] 
 
     @classmethod
     def _deserialize_title(cls, lines) -> (str, List[str]):
@@ -320,14 +410,26 @@ class Artefact(BaseModel, ABC):
         return contribution, lines
 
     @classmethod
-    def _deserialize_description(cls, lines) -> (Optional[str], List[str]):
+    def _deserialize_description(cls, lines: List[str]) -> (Optional[str], List[str]):
         description_start = cls._description_starts_with()
+        start_index = -1
         for i, line in enumerate(lines):
             if line.startswith(description_start):
-                description = line[len(description_start):].strip()
-                del lines[i]
-                return description, lines
-        return None, lines
+                start_index = i
+                break
+
+        if start_index == -1:
+            return None, lines
+
+        first_line_content = lines[start_index][len(description_start):].strip()
+
+        description_lines = ([first_line_content] if first_line_content else []) + lines[start_index + 1:]
+
+        description = "\n".join(description_lines)
+
+        remaining_lines = lines[:start_index]
+
+        return (description if description else None), remaining_lines
 
     @classmethod
     def _parse_common_fields(cls, text: str) -> dict:
@@ -341,7 +443,7 @@ class Artefact(BaseModel, ABC):
         contribution, remaining_lines = cls._deserialize_contribution(remaining_lines)
         description, remaining_lines = cls._deserialize_description(remaining_lines)
 
-        return {
+        fields = {
             'artefact_type': cls._artefact_type(),
             'tags': tags.get('tags', []),
             'users': tags.get('users', []),
@@ -350,6 +452,9 @@ class Artefact(BaseModel, ABC):
             'contribution': contribution,
             'description': description,
         }
+        if tags.get("author"):
+            fields["author"] = tags.get("author")
+        return fields
 
     @classmethod
     def deserialize(cls, text: str) -> 'Artefact':
@@ -381,6 +486,8 @@ class Artefact(BaseModel, ABC):
             tags.append(f"@{self.status}")
         for user in self.users:
             tags.append(f"@user_{user}")
+        if self.author:
+            tags.append(f"@{self.author}")
         for tag in self.tags:
             tags.append(f"@{tag}")
         return ' '.join(tags)
@@ -404,4 +511,4 @@ class Artefact(BaseModel, ABC):
             classifier=classifier,
             rule=rule
         )
-        self.contribution = contribution
+        self.contribution = contribution

ara_cli/artefact_models/artefact_templates.py

@@ -1,4 +1,4 @@
-from ara_cli.artefact_models.artefact_model import ArtefactType, Artefact
+from ara_cli.artefact_models.artefact_model import ArtefactType, Artefact, Contribution
 from ara_cli.artefact_models.vision_artefact_model import VisionArtefact, VisionIntent
 from ara_cli.artefact_models.businessgoal_artefact_model import BusinessgoalArtefact, BusinessgoalIntent
 from ara_cli.artefact_models.capability_artefact_model import CapabilityArtefact, CapabilityIntent
@@ -11,7 +11,15 @@ from ara_cli.artefact_models.task_artefact_model import TaskArtefact
 from ara_cli.artefact_models.issue_artefact_model import IssueArtefact
 
 
-def _default_vision(title: str) -> VisionArtefact:
+def default_contribution() -> Contribution:
+    return Contribution(
+        artefact_name=Contribution.PLACEHOLDER_NAME,
+        classifier=Contribution.PLACEHOLDER_CLASSIFIER,
+        rule=Contribution.PLACEHOLDER_RULE
+    )
+
+
+def _default_vision(title: str, use_default_contribution: bool) -> VisionArtefact:
     intent = VisionIntent(
         for_="<target customer>",
         who="<needs something>",
@@ -21,42 +29,46 @@ def _default_vision(title: str) -> VisionArtefact:
         our_product="<statement of primary differentiation>"
     )
     return VisionArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description="<further optional description to understand the vision, markdown capable text formatting>",
-        intent=intent
+        intent=intent,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_businessgoal(title: str) -> BusinessgoalArtefact:
+def _default_businessgoal(title: str, use_default_contribution: bool) -> BusinessgoalArtefact:
     intent = BusinessgoalIntent(
         in_order_to="<reach primarily a monetary business goal>",
         as_a="<business related role>",
         i_want="<something that helps me to reach my monetary goal>"
     )
     return BusinessgoalArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
-        description="<further optional description to understand the vision, markdown capable text formatting>",
-        intent=intent
+        description="<further optional description to understand the businessgoal, markdown capable text formatting>",
+        intent=intent,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_capability(title: str) -> CapabilityArtefact:
+def _default_capability(title: str, use_default_contribution: bool) -> CapabilityArtefact:
     intent = CapabilityIntent(
-        in_order_to="<reach primarily a monetary business goal>",
-        as_a="<business related role>",
-        to_be_able_to="<something that helps me to reach my monetary goal>"
+        to_be_able_to="<needed capability for stakeholders that are the enablers/relevant for reaching the business goal>"
     )
     return CapabilityArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description="<further optional description to understand the capability, markdown capable text formatting>",
-        intent=intent
+        intent=intent,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_epic(title: str) -> EpicArtefact:
+def _default_epic(title: str, use_default_contribution: bool) -> EpicArtefact:
     intent = EpicIntent(
         in_order_to="<achieve a benefit>",
         as_a="<(user) role>",
@@ -68,15 +80,17 @@ def _default_epic(title: str) -> EpicArtefact:
         "<rule needed to fulfill the wanted product behavior>"
     ]
     return EpicArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
-        description="<further optional description to understand the vision, markdown capable text formatting>",
+        description="<further optional description to understand the epic, markdown capable text formatting>",
         intent=intent,
-        rules=rules
+        rules=rules,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_userstory(title: str) -> UserstoryArtefact:
+def _default_userstory(title: str, use_default_contribution: bool) -> UserstoryArtefact:
     intent = UserstoryIntent(
         in_order_to="<achieve a benefit>",
         as_a="<(user) role>",
@@ -88,44 +102,50 @@ def _default_userstory(title: str) -> UserstoryArtefact:
         "<rule needed to fulfill the wanted product behavior>"
     ]
     return UserstoryArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description="<further optional description to understand the userstory, markdown capable text formatting>",
         intent=intent,
         rules=rules,
-        estimate="<story points, scale?>"
+        estimate="<story points, scale?>",
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_example(title: str) -> ExampleArtefact:
+def _default_example(title: str, use_default_contribution: bool) -> ExampleArtefact:
     return ExampleArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description="<further optional description to understand the example, markdown capable text formatting>",
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_keyfeature(title: str) -> KeyfeatureArtefact:
+def _default_keyfeature(title: str, use_default_contribution: bool) -> KeyfeatureArtefact:
     intent = KeyfeatureIntent(
         in_order_to="<support a capability or business goal>",
         as_a="<main stakeholder who will benefit>",
         i_want="<a product feature that helps me doing something so that I can achieve my named goal>"
     )
-    description = """<further optional description to understand the capability, markdown capable text formatting, best practice is using
+    description = """<further optional description to understand the keyfeature, markdown capable text formatting, best practice is using
     GIVEN any precondition
     AND another precondition
     WHEN some action takes place
     THEN some result is to be expected
     AND some other result is to be expected>"""
     return KeyfeatureArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description=description,
-        intent=intent
+        intent=intent,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_feature(title: str) -> FeatureArtefact:
+def _default_feature(title: str, use_default_contribution: bool) -> FeatureArtefact:
     intent = FeatureIntent(
         as_a="<user>",
         i_want_to="<do something | need something>",
@@ -135,9 +155,9 @@ def _default_feature(title: str) -> FeatureArtefact:
         Scenario(
             title="<descriptive_scenario_title>",
             steps=[
-                "Given <precondition>",
-                "When <action>",
-                "Then <expected result>"
+                "Given [precondition]",
+                "When [action]",
+                "Then [expected result]"
             ],
         ),
         ScenarioOutline(
@@ -169,27 +189,30 @@ def _default_feature(title: str) -> FeatureArtefact:
             ]
         )
     ]
-    description = """<further optional description to understand
-  the rule, no format defined, the example artefact is only a placeholder>"""
+    description = """<further optional description to understand the feature, no format defined, the example artefact is only a placeholder>"""
 
     return FeatureArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description=description,
         intent=intent,
-        scenarios=scenarios
+        scenarios=scenarios,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_task(title: str) -> TaskArtefact:
+def _default_task(title: str, use_default_contribution: bool) -> TaskArtefact:
     return TaskArtefact(
-        status="to-do",
+        tags=[],
+        status=None,
         title=title,
-        description="<further optional description to understand the task, no format defined>"
+        description="<further optional description to understand the task, no format defined>",
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def _default_issue(title: str) -> IssueArtefact:
+def _default_issue(title: str, use_default_contribution: bool) -> IssueArtefact:
     description = "<further free text description to understand the issue, no format defined>"
     additional_description = """*Optional descriptions of the issue in Gherkin style*
 
@@ -200,14 +223,16 @@ def _default_issue(title: str) -> IssueArtefact:
     *or optional free text description*"""
 
     return IssueArtefact(
-        tags=["sample_tag"],
+        tags=[],
+        author="creator_unknown",
         title=title,
         description=description,
-        additional_description=additional_description
+        additional_description=additional_description,
+        contribution=default_contribution() if use_default_contribution else None
     )
 
 
-def template_artefact_of_type(artefact_type: ArtefactType, title: str) -> Artefact:
+def template_artefact_of_type(artefact_type: ArtefactType, title: str = "<descriptive_title>", use_default_contribution: bool = True) -> Artefact:
     default_creation_functions = {
         ArtefactType.vision: _default_vision,
         ArtefactType.businessgoal: _default_businessgoal,
@@ -220,5 +245,6 @@ def template_artefact_of_type(artefact_type: ArtefactType, title: str) -> Artefa
         ArtefactType.task: _default_task,
         ArtefactType.issue: _default_issue
     }
-
-    return default_creation_functions[artefact_type](title)
+    if artefact_type not in default_creation_functions.keys():
+        return None
+    return default_creation_functions[artefact_type](title, use_default_contribution)

ara_cli/artefact_models/businessgoal_artefact_model.py

@@ -38,7 +38,7 @@ class BusinessgoalIntent(Intent):
         lines = []
 
         as_a_line = as_a_serializer(self.as_a)
-        
+
         lines.append(f"In order to {self.in_order_to}")
         lines.append(as_a_line)
         lines.append(f"I want {self.i_want}")
@@ -47,39 +47,37 @@ class BusinessgoalIntent(Intent):
 
     @classmethod
     def deserialize_from_lines(cls, lines: List[str], start_index: int = 0) -> 'BusinessgoalIntent':
-        in_order_to = None
-        as_a = None
-        i_want = None
-
-        in_order_to_prefix = "In order to "
-        as_a_prefix = "As a "
-        as_a_prefix_alt = "As an "
-        i_want_prefix = "I want "
+        prefixes = [
+            ("In order to ", "in_order_to"),
+            ("As a ", "as_a"),
+            ("As an ", "as_a"),
+            ("I want ", "i_want"),
+        ]
+        found = {"in_order_to": None, "as_a": None, "i_want": None}
+
+        def match_and_store(line):
+            for prefix, field in prefixes:
+                if line.startswith(prefix) and found[field] is None:
+                    found[field] = line[len(prefix):].strip()
+                    return True
+            return False
 
         index = start_index
-        while index < len(lines) and (not in_order_to or not as_a or not i_want):
-            line = lines[index]
-            if line.startswith(in_order_to_prefix) and not in_order_to:
-                in_order_to = line[len(in_order_to_prefix):].strip()
-            elif line.startswith(as_a_prefix) and not as_a:
-                as_a = line[len(as_a_prefix):].strip()
-            elif line.startswith(as_a_prefix_alt) and not as_a:
-                as_a = line[len(as_a_prefix_alt):].strip()
-            elif line.startswith(i_want_prefix) and not i_want:
-                i_want = line[len(i_want_prefix):].strip()
+        while index < len(lines) and any(v is None for v in found.values()):
+            match_and_store(lines[index])
             index += 1
 
-        if not in_order_to:
+        if not found["in_order_to"]:
             raise ValueError("Could not find 'In order to' line")
-        if not as_a:
+        if not found["as_a"]:
             raise ValueError("Could not find 'As a' line")
-        if not i_want:
+        if not found["i_want"]:
             raise ValueError("Could not find 'I want' line")
 
         return cls(
-            in_order_to=in_order_to,
-            as_a=as_a,
-            i_want=i_want
+            in_order_to=found["in_order_to"],
+            as_a=found["as_a"],
+            i_want=found["i_want"]
         )