doit-toolkit-cli 0.1.9__py3-none-any.whl

doit_cli/services/template_reader.py

@@ -0,0 +1,158 @@
+"""Service to read and scan doit command templates."""
+
+import importlib.resources
+from pathlib import Path
+
+from ..models.sync_models import CommandTemplate
+
+
+class TemplateReader:
+    """Reads command templates from bundled or project templates directory.
+
+    Supports three template locations (checked in order):
+    1. CLI repo development: src/doit_cli/templates/commands/
+    2. Installed package: via importlib.resources (doit_cli.templates.commands)
+    3. Project templates: .doit/templates/commands/ (for end-user projects)
+
+    When running from an installed package, bundled templates are used.
+    """
+
+    BUNDLED_TEMPLATES_DIR = "src/doit_cli/templates/commands"
+    PROJECT_TEMPLATES_DIR = ".doit/templates/commands"
+    COMMAND_PATTERN = "doit.*.md"
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the template reader.
+
+        Args:
+            project_root: Root directory of the project. Defaults to current directory.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.templates_dir = self._resolve_templates_directory()
+
+    def _resolve_templates_directory(self) -> Path:
+        """Resolve the templates directory.
+
+        Priority order:
+        1. Project templates (.doit/templates/commands/) - allows customization
+        2. CLI repo development (src/doit_cli/templates/commands/)
+        3. Installed package templates (via importlib.resources)
+
+        Returns:
+            Path to the templates directory to use.
+        """
+        # First, check for project templates (allows customization)
+        project_dir = self.project_root / self.PROJECT_TEMPLATES_DIR
+        if project_dir.exists() and any(project_dir.glob(self.COMMAND_PATTERN)):
+            return project_dir
+
+        # Second, check for CLI repo development templates
+        bundled_dir = self.project_root / self.BUNDLED_TEMPLATES_DIR
+        if bundled_dir.exists() and any(bundled_dir.glob(self.COMMAND_PATTERN)):
+            return bundled_dir
+
+        # Third, try to find templates from installed package
+        package_templates = self._get_package_templates_directory()
+        if package_templates and package_templates.exists():
+            if any(package_templates.glob(self.COMMAND_PATTERN)):
+                return package_templates
+
+        # Fall back to project templates path (will be empty/not exist)
+        return project_dir
+
+    def _get_package_templates_directory(self) -> Path | None:
+        """Get the templates directory from the installed package.
+
+        Returns:
+            Path to bundled templates directory, or None if not found.
+        """
+        try:
+            # Use importlib.resources to find package templates
+            # Get the actual path from the package location
+            pkg_files = importlib.resources.files("doit_cli")
+            templates_path = pkg_files.joinpath("templates/commands")
+
+            # Check if it's a real path we can use
+            if hasattr(templates_path, "_path"):
+                # Direct filesystem path (editable install or source)
+                return Path(templates_path._path)
+
+            # Try to get path via traversable
+            # For installed packages, get the actual location
+            import doit_cli
+            pkg_location = Path(doit_cli.__file__).parent
+            templates_dir = pkg_location / "templates" / "commands"
+            if templates_dir.exists():
+                return templates_dir
+
+            return None
+        except (ImportError, TypeError, AttributeError, FileNotFoundError):
+            return None
+
+    def get_templates_directory(self) -> Path:
+        """Get the templates directory path."""
+        return self.templates_dir
+
+    def is_using_bundled_templates(self) -> bool:
+        """Check if using bundled templates (CLI repo) vs project templates.
+
+        Returns:
+            True if using bundled templates, False if using project templates.
+        """
+        return self.BUNDLED_TEMPLATES_DIR in str(self.templates_dir)
+
+    def scan_templates(self, filter_name: str | None = None) -> list[CommandTemplate]:
+        """Scan for command templates in the templates directory.
+
+        Args:
+            filter_name: Optional command name to filter by (e.g., "doit.checkin").
+
+        Returns:
+            List of CommandTemplate objects found.
+        """
+        if not self.templates_dir.exists():
+            return []
+
+        templates = []
+        pattern = self.COMMAND_PATTERN
+
+        for path in sorted(self.templates_dir.glob(pattern)):
+            if not path.is_file():
+                continue
+
+            # Apply name filter if specified
+            if filter_name:
+                # Allow matching with or without .md extension
+                filter_stem = filter_name.replace(".md", "")
+                if path.stem != filter_stem:
+                    continue
+
+            try:
+                template = CommandTemplate.from_path(path)
+                templates.append(template)
+            except (OSError, UnicodeDecodeError) as e:
+                # Log error but continue with other templates
+                print(f"Warning: Could not read template {path}: {e}")
+
+        return templates
+
+    def get_template(self, name: str) -> CommandTemplate | None:
+        """Get a specific command template by name.
+
+        Args:
+            name: Command name (e.g., "doit.checkin" or "doit.checkin.md").
+
+        Returns:
+            CommandTemplate if found, None otherwise.
+        """
+        templates = self.scan_templates(filter_name=name)
+        return templates[0] if templates else None
+
+    def list_template_names(self) -> list[str]:
+        """List all available template names.
+
+        Returns:
+            List of template names (e.g., ["doit.checkin", "doit.specit", ...]).
+        """
+        templates = self.scan_templates()
+        return [t.name for t in templates]

doit_cli/services/user_journey_generator.py

@@ -0,0 +1,214 @@
+"""Generator for User Journey flowchart diagrams from user stories."""
+
+from ..models.diagram_models import GeneratedDiagram, DiagramType, ParsedUserStory
+
+
+class UserJourneyGenerator:
+    """Generates Mermaid flowchart diagrams from user stories.
+
+    Converts ParsedUserStory objects into a flowchart with subgraphs
+    per story and nodes for each acceptance scenario.
+    """
+
+    def __init__(self, direction: str = "LR"):
+        """Initialize generator.
+
+        Args:
+            direction: Flowchart direction (LR, TB, RL, BT)
+        """
+        self.direction = direction
+
+    def generate(self, stories: list[ParsedUserStory]) -> str:
+        """Generate Mermaid flowchart from user stories.
+
+        Args:
+            stories: List of parsed user stories
+
+        Returns:
+            Mermaid flowchart syntax
+        """
+        if not stories:
+            return ""
+
+        lines = [f"flowchart {self.direction}"]
+
+        for story in stories:
+            story_lines = self._generate_story_subgraph(story)
+            lines.extend(story_lines)
+
+        # Add story connections (story to story flow)
+        connection_lines = self._generate_story_connections(stories)
+        if connection_lines:
+            lines.append("")
+            lines.extend(connection_lines)
+
+        return "\n".join(lines)
+
+    def generate_diagram(self, stories: list[ParsedUserStory]) -> GeneratedDiagram:
+        """Generate a GeneratedDiagram object from user stories.
+
+        Args:
+            stories: List of parsed user stories
+
+        Returns:
+            GeneratedDiagram with content and metadata
+        """
+        content = self.generate(stories)
+
+        # Count nodes
+        node_count = sum(
+            len(story.scenarios) + 1 for story in stories  # +1 for entry node
+        )
+
+        return GeneratedDiagram(
+            id="user-journey",
+            diagram_type=DiagramType.USER_JOURNEY,
+            mermaid_content=content,
+            is_valid=True,
+            node_count=node_count,
+        )
+
+    def _generate_story_subgraph(self, story: ParsedUserStory) -> list[str]:
+        """Generate subgraph for a single user story.
+
+        Args:
+            story: Parsed user story
+
+        Returns:
+            List of Mermaid syntax lines
+        """
+        lines = []
+        lines.append(f'    subgraph {story.subgraph_id}["{story.subgraph_label}"]')
+
+        if not story.scenarios:
+            # No scenarios - create a single placeholder node
+            node_id = f"{story.subgraph_id}_A"
+            lines.append(f'        {node_id}["{self._escape_label(story.title)}"]')
+        else:
+            # Create nodes for each scenario
+            prev_node_id = None
+            for i, scenario in enumerate(story.scenarios):
+                letter = chr(ord("A") + i)
+                node_id = f"{story.subgraph_id}_{letter}"
+
+                # Generate node based on scenario
+                given_label = self._truncate_label(scenario.given_clause, 50)
+                when_label = self._truncate_label(scenario.when_clause, 50)
+                then_label = self._truncate_label(scenario.then_clause, 50)
+
+                # Create nodes for Given, When, Then
+                given_node = f"{node_id}_G"
+                when_node = f"{node_id}_W"
+                then_node = f"{node_id}_T"
+
+                lines.append(f'        {given_node}["{self._escape_label(given_label)}"]')
+                lines.append(f'        {when_node}{{"{self._escape_label(when_label)}"}}')
+                lines.append(f'        {then_node}["{self._escape_label(then_label)}"]')
+
+                # Connect Given -> When -> Then
+                lines.append(f"        {given_node} --> {when_node}")
+                lines.append(f"        {when_node} --> {then_node}")
+
+                # Connect to previous scenario
+                if prev_node_id:
+                    lines.append(f"        {prev_node_id} -.-> {given_node}")
+
+                prev_node_id = then_node
+
+        lines.append("    end")
+        return lines
+
+    def _generate_story_connections(self, stories: list[ParsedUserStory]) -> list[str]:
+        """Generate connections between story subgraphs.
+
+        Args:
+            stories: List of parsed user stories
+
+        Returns:
+            List of connection lines
+        """
+        if len(stories) <= 1:
+            return []
+
+        lines = []
+        lines.append("    %% Story flow connections")
+
+        for i in range(len(stories) - 1):
+            current_story = stories[i]
+            next_story = stories[i + 1]
+
+            # Connect last node of current story to first node of next
+            if current_story.scenarios:
+                last_letter = chr(ord("A") + len(current_story.scenarios) - 1)
+                current_end = f"{current_story.subgraph_id}_{last_letter}_T"
+            else:
+                current_end = f"{current_story.subgraph_id}_A"
+
+            if next_story.scenarios:
+                next_start = f"{next_story.subgraph_id}_A_G"
+            else:
+                next_start = f"{next_story.subgraph_id}_A"
+
+            # Use dotted line for cross-story connections
+            lines.append(f"    {current_end} ==> {next_start}")
+
+        return lines
+
+    def _truncate_label(self, text: str, max_length: int = 40) -> str:
+        """Truncate label to maximum length.
+
+        Args:
+            text: Original label text
+            max_length: Maximum characters
+
+        Returns:
+            Truncated text with ellipsis if needed
+        """
+        if len(text) <= max_length:
+            return text
+        return text[: max_length - 3] + "..."
+
+    def _escape_label(self, text: str) -> str:
+        """Escape special characters for Mermaid labels.
+
+        Args:
+            text: Original label text
+
+        Returns:
+            Escaped text safe for Mermaid
+        """
+        # Escape quotes
+        text = text.replace('"', "'")
+        # Escape brackets that could be misinterpreted
+        text = text.replace("[", "(")
+        text = text.replace("]", ")")
+        # Remove newlines
+        text = text.replace("\n", " ")
+        # Clean up whitespace
+        text = " ".join(text.split())
+        return text
+
+    def generate_simple(self, stories: list[ParsedUserStory]) -> str:
+        """Generate a simplified flowchart with one node per story.
+
+        Args:
+            stories: List of parsed user stories
+
+        Returns:
+            Simplified Mermaid flowchart syntax
+        """
+        if not stories:
+            return ""
+
+        lines = [f"flowchart {self.direction}"]
+
+        for i, story in enumerate(stories):
+            node_id = story.subgraph_id
+            label = f"{story.id}: {self._truncate_label(story.title, 30)}"
+            lines.append(f'    {node_id}["{self._escape_label(label)}"]')
+
+            if i > 0:
+                prev_id = stories[i - 1].subgraph_id
+                lines.append(f"    {prev_id} --> {node_id}")
+
+        return "\n".join(lines)

doit_cli/services/user_story_parser.py

@@ -0,0 +1,232 @@
+"""Parser for user stories from spec.md files."""
+
+import re
+from typing import Optional
+
+from ..models.diagram_models import AcceptanceScenario, ParsedUserStory
+
+
+class UserStoryParser:
+    """Parses user stories from spec.md content.
+
+    Extracts user story headers, descriptions, and acceptance scenarios
+    following the doit spec template format.
+    """
+
+    # Pattern for user story header: ### User Story N - Title (Priority: PN)
+    STORY_HEADER_PATTERN = re.compile(
+        r"^###\s+User\s+Story\s+(\d+)\s*[-–—]\s*(.+?)\s*\(Priority:\s*(P\d+)\)\s*$",
+        re.IGNORECASE | re.MULTILINE,
+    )
+
+    # Pattern for Given/When/Then acceptance scenarios
+    # Supports both bold and plain text formats
+    SCENARIO_PATTERN = re.compile(
+        r"^\d+\.\s+\*?\*?(?:Given)\*?\*?\s+(.+?),\s*\*?\*?(?:When)\*?\*?\s+(.+?),\s*\*?\*?(?:Then)\*?\*?\s+(.+)$",
+        re.IGNORECASE | re.MULTILINE,
+    )
+
+    # Alternative pattern for bold keywords
+    SCENARIO_BOLD_PATTERN = re.compile(
+        r"^\d+\.\s+\*\*Given\*\*\s+(.+?),\s*\*\*When\*\*\s+(.+?),\s*\*\*Then\*\*\s+(.+)$",
+        re.IGNORECASE | re.MULTILINE,
+    )
+
+    def parse(self, content: str) -> list[ParsedUserStory]:
+        """Parse all user stories from spec content.
+
+        Args:
+            content: Full content of spec.md file
+
+        Returns:
+            List of ParsedUserStory objects
+        """
+        stories = []
+
+        # Find all story headers and their positions
+        header_matches = list(self.STORY_HEADER_PATTERN.finditer(content))
+
+        if not header_matches:
+            return stories
+
+        # Extract each story's content
+        for i, match in enumerate(header_matches):
+            story_number = int(match.group(1))
+            title = match.group(2).strip()
+            priority = match.group(3).strip().upper()
+
+            # Determine story content boundaries
+            start_pos = match.end()
+            if i + 1 < len(header_matches):
+                end_pos = header_matches[i + 1].start()
+            else:
+                # Last story - find next major section or end of file
+                next_section = self._find_next_section(content, start_pos)
+                end_pos = next_section if next_section else len(content)
+
+            story_content = content[start_pos:end_pos].strip()
+
+            # Extract description and scenarios
+            description = self._extract_description(story_content)
+            scenarios = self._extract_scenarios(story_content, story_number)
+
+            story = ParsedUserStory(
+                id=f"US{story_number}",
+                story_number=story_number,
+                title=title,
+                priority=priority,
+                description=description,
+                scenarios=scenarios,
+                raw_text=content[match.start() : end_pos],
+            )
+            stories.append(story)
+
+        return stories
+
+    def parse_single(self, content: str) -> Optional[ParsedUserStory]:
+        """Parse a single user story from content.
+
+        Args:
+            content: Content containing one user story
+
+        Returns:
+            ParsedUserStory if found, None otherwise
+        """
+        stories = self.parse(content)
+        return stories[0] if stories else None
+
+    def _extract_description(self, story_content: str) -> str:
+        """Extract user story description from content.
+
+        The description is typically the narrative before acceptance scenarios.
+
+        Args:
+            story_content: Content of a single user story section
+
+        Returns:
+            Description text
+        """
+        lines = story_content.split("\n")
+        description_lines = []
+
+        for line in lines:
+            stripped = line.strip()
+
+            # Stop at acceptance scenarios or numbered lists
+            if stripped.startswith("1.") or "**Given**" in stripped:
+                break
+
+            # Skip empty lines at the start
+            if not stripped and not description_lines:
+                continue
+
+            # Stop at sub-headers
+            if stripped.startswith("##"):
+                break
+
+            description_lines.append(stripped)
+
+        return " ".join(description_lines).strip()
+
+    def _extract_scenarios(
+        self, story_content: str, story_number: int
+    ) -> list[AcceptanceScenario]:
+        """Extract acceptance scenarios from story content.
+
+        Args:
+            story_content: Content of a single user story section
+            story_number: The story number for generating IDs
+
+        Returns:
+            List of AcceptanceScenario objects
+        """
+        scenarios = []
+
+        # Try bold pattern first (more specific)
+        matches = list(self.SCENARIO_BOLD_PATTERN.finditer(story_content))
+
+        # Fall back to general pattern
+        if not matches:
+            matches = list(self.SCENARIO_PATTERN.finditer(story_content))
+
+        for scenario_num, match in enumerate(matches, start=1):
+            given = self._clean_clause(match.group(1))
+            when = self._clean_clause(match.group(2))
+            then = self._clean_clause(match.group(3))
+
+            scenario = AcceptanceScenario(
+                id=f"US{story_number}_S{scenario_num}",
+                scenario_number=scenario_num,
+                given_clause=given,
+                when_clause=when,
+                then_clause=then,
+                raw_text=match.group(0),
+            )
+            scenarios.append(scenario)
+
+        return scenarios
+
+    def _clean_clause(self, text: str) -> str:
+        """Clean a Given/When/Then clause.
+
+        Args:
+            text: Raw clause text
+
+        Returns:
+            Cleaned text with markdown removed
+        """
+        # Remove bold markers
+        text = text.replace("**", "")
+        # Remove trailing punctuation
+        text = text.rstrip(".,;")
+        # Clean whitespace
+        text = " ".join(text.split())
+        return text.strip()
+
+    def _find_next_section(self, content: str, start_pos: int) -> Optional[int]:
+        """Find the position of the next major section.
+
+        Args:
+            content: Full file content
+            start_pos: Position to start searching from
+
+        Returns:
+            Position of next section header, or None if not found
+        """
+        # Look for ## or ### headers that aren't user stories
+        section_pattern = re.compile(r"^##\s+[^#]", re.MULTILINE)
+        match = section_pattern.search(content, start_pos)
+
+        if match:
+            return match.start()
+
+        return None
+
+    def get_story_by_number(
+        self, content: str, story_number: int
+    ) -> Optional[ParsedUserStory]:
+        """Get a specific user story by number.
+
+        Args:
+            content: Spec content to parse
+            story_number: Story number to find (1, 2, 3...)
+
+        Returns:
+            ParsedUserStory if found, None otherwise
+        """
+        stories = self.parse(content)
+        for story in stories:
+            if story.story_number == story_number:
+                return story
+        return None
+
+    def count_stories(self, content: str) -> int:
+        """Count user stories in content without full parsing.
+
+        Args:
+            content: Spec content to check
+
+        Returns:
+            Number of user stories found
+        """
+        return len(self.STORY_HEADER_PATTERN.findall(content))