raise-cli 2.2.1__py3-none-any.whl

raise_cli/governance/parsers/epic.py

@@ -0,0 +1,323 @@
+"""Parser for epic scope documents.
+
+Extracts detailed Epic and Story concepts from work/epics/*/scope.md files.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from raise_cli.adapters.models import ArtifactLocator, CoreArtifactType
+from raise_cli.compat import portable_path
+from raise_cli.governance.models import Concept, ConceptType
+from raise_cli.governance.parsers._convert import concept_to_node
+from raise_cli.governance.parsers.backlog import normalize_status
+from raise_core.graph.models import GraphNode
+
+
+def _extract_frontmatter(text: str) -> dict[str, str | None]:
+    """Extract frontmatter metadata from epic scope document.
+
+    Parses blockquote lines like:
+    > **Status:** COMPLETE
+    > **Target:** Feb 9, 2026
+
+    Args:
+        text: Full epic scope document content.
+
+    Returns:
+        Dictionary with extracted metadata (status, target, branch, etc.).
+    """
+    metadata: dict[str, str | None] = {
+        "status": None,
+        "target": None,
+        "branch": None,
+        "created": None,
+        "completed": None,
+    }
+
+    # Pattern: > **Key:** Value or > Key: Value
+    # Note: Markdown bold is **Key:** with colon inside, so pattern is :**
+    frontmatter_pattern = re.compile(
+        r"^>\s*\*?\*?([^:*]+?):\*?\*?\s*(.+)$", re.MULTILINE
+    )
+
+    for match in frontmatter_pattern.finditer(text):
+        key = match.group(1).strip().lower()
+        value = match.group(2).strip()
+
+        if key == "status":
+            # Remove emoji and extra text after status
+            status_match = re.match(r"^([A-Z]+)", value)
+            if status_match:
+                metadata["status"] = status_match.group(1).lower()
+            else:
+                metadata["status"] = normalize_status(value)
+        elif key == "target":
+            metadata["target"] = value
+        elif key == "branch":
+            metadata["branch"] = value
+        elif key == "created":
+            metadata["created"] = value
+        elif key == "completed":
+            metadata["completed"] = value
+
+    return metadata
+
+
+def extract_epic_details(
+    file_path: Path, project_root: Path | None = None
+) -> Concept | None:
+    """Extract detailed Epic concept from epic scope document.
+
+    Parses the epic scope document to extract full epic metadata including
+    objective, status, target date, and story count.
+
+    Args:
+        file_path: Path to epic scope document (work/epics/*/scope.md).
+        project_root: Project root for relative path calculation.
+            If None, uses file_path.parent.parent.parent.
+
+    Returns:
+        Epic Concept with full details if successfully parsed, None if file
+        doesn't exist or can't be parsed.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> scope_doc = Path("work/epics/e08-backlog/scope.md")
+        >>> epic = extract_epic_details(scope_doc)
+        >>> epic.id
+        'epic-e8'
+        >>> epic.metadata["name"]
+        'Work Tracking Graph'
+    """
+    if not file_path.exists():
+        return None
+
+    if project_root is None:
+        # work/epics/e08-name/scope.md -> project root is 4 levels up
+        project_root = file_path.parent.parent.parent.parent
+
+    text = file_path.read_text(encoding="utf-8")
+    lines = text.split("\n")
+
+    # Extract epic ID from parent directory: e08-backlog -> E8
+    parent_dir = file_path.parent.name  # e08-backlog
+    epic_id_match = re.search(r"^e(\d+)", parent_dir, re.IGNORECASE)
+    if not epic_id_match:
+        return None
+
+    epic_id = f"E{int(epic_id_match.group(1))}"  # E8 (normalize: e08 -> E8)
+
+    # Extract epic name from H1: # Epic E8: Work Tracking Graph - Scope
+    epic_name = None
+    header_line = 1
+    for i, line in enumerate(lines, 1):
+        match = re.match(r"^#\s*Epic\s+E\d+[:\s]+(.+?)(?:\s*-\s*Scope)?$", line)
+        if match:
+            epic_name = match.group(1).strip()
+            header_line = i
+            break
+
+    if not epic_name:
+        # Fallback: use epic ID
+        epic_name = f"Epic {epic_id}"
+
+    # Extract frontmatter
+    frontmatter = _extract_frontmatter(text)
+
+    # Count stories in table
+    story_count = len(re.findall(r"^\|\s*F\d+\.\d+\s*\|", text, re.MULTILINE))
+
+    # Calculate relative file path
+    try:
+        relative_path = portable_path(file_path, project_root)
+    except ValueError:
+        relative_path = file_path.name
+
+    # Extract objective (first paragraph after ## Objective)
+    objective = None
+    objective_match = re.search(
+        r"##\s*Objective\s*\n+(.+?)(?=\n\n|\n##|\Z)", text, re.DOTALL
+    )
+    if objective_match:
+        objective = objective_match.group(1).strip()
+        # Truncate if too long
+        if len(objective) > 300:
+            objective = objective[:297] + "..."
+
+    # Build content summary
+    content = f"Epic {epic_id}: {epic_name}"
+    if frontmatter["status"]:
+        content += f" ({frontmatter['status']})"
+    if objective:
+        content += f". {objective}"
+
+    return Concept(
+        id=f"epic-{epic_id.lower()}",
+        type=ConceptType.EPIC,
+        file=relative_path,
+        section=f"Epic {epic_id}: {epic_name}",
+        lines=(header_line, min(header_line + 20, len(lines))),
+        content=content[:500],  # Truncate to 500 chars
+        metadata={
+            "epic_id": epic_id,
+            "name": epic_name,
+            "status": frontmatter["status"] or "draft",
+            "target": frontmatter["target"],
+            "branch": frontmatter["branch"],
+            "created": frontmatter["created"],
+            "completed": frontmatter["completed"],
+            "story_count": story_count,
+            "scope_doc": relative_path,
+        },
+    )
+
+
+def extract_stories(file_path: Path, project_root: Path | None = None) -> list[Concept]:
+    """Extract Story concepts from epic scope document.
+
+    Parses the "Stories" table to extract story metadata. Supports
+    various table formats found in epic scope documents.
+
+    Args:
+        file_path: Path to epic scope document (work/epics/*/scope.md).
+        project_root: Project root for relative path calculation.
+            If None, uses file_path.parent.parent.parent.parent.
+
+    Returns:
+        List of Story Concepts extracted from the table. Returns empty list
+        if file doesn't exist or no stories found.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> scope_doc = Path("work/epics/e08-backlog/scope.md")
+        >>> stories = extract_stories(scope_doc)
+        >>> len(stories)
+        4
+        >>> features[0].metadata["story_id"]
+        'F8.1'
+    """
+    if not file_path.exists():
+        return []
+
+    if project_root is None:
+        project_root = file_path.parent.parent.parent.parent
+
+    text = file_path.read_text(encoding="utf-8")
+    lines = text.split("\n")
+
+    # Extract epic ID from parent directory: e08-backlog -> E8
+    parent_dir = file_path.parent.name
+    epic_id_match = re.search(r"^e(\d+)", parent_dir, re.IGNORECASE)
+    epic_id = f"E{int(epic_id_match.group(1))}" if epic_id_match else "E0"
+
+    # Calculate relative file path
+    try:
+        relative_path = portable_path(file_path, project_root)
+    except ValueError:
+        relative_path = file_path.name
+
+    concepts: list[Concept] = []
+
+    # Parse story table rows
+    # Pattern variants:
+    # | F8.1 | Backlog Parser | S | Pending | Description |
+    # | F8.1 | Backlog Parser | S | 2 | Pending | Description |
+    # | F2.1 | Concept Extraction | 3 | ✅ Complete | 52 min | 3.5x |
+    story_pattern = re.compile(
+        r"^\|\s*(F\d+\.\d+)\s*\|"  # Story ID
+        r"\s*\*?\*?([^|*]+?)\*?\*?\s*\|"  # Story name (with optional bold)
+        r"\s*([^|]+?)\s*\|"  # Size or SP
+        r"\s*([^|]+?)\s*\|"  # Status or SP (depends on format)
+        r"(?:\s*([^|]*?)\s*\|)?"  # Optional: Description or Status or Time
+    )
+
+    for i, line in enumerate(lines, 1):
+        match = story_pattern.match(line)
+        if match:
+            story_id = match.group(1).strip()
+            name = match.group(2).strip()
+            col3 = match.group(3).strip()
+            col4 = match.group(4).strip()
+            col5 = match.group(5).strip() if match.group(5) else ""
+
+            # Determine column mapping based on content
+            # If col3 looks like size (XS/S/M/L) or small number (1-3), it's size
+            # If col4 looks like status, use col3 as size and col4 as status
+            size = None
+            status = None
+            sp = None
+            description = None
+
+            # Check if col3 is size (XS/S/M/L)
+            if re.match(r"^(XS|S|M|L)$", col3, re.IGNORECASE):
+                size = col3.upper()
+                # col4 could be SP or Status
+                if re.match(r"^\d+$", col4):
+                    sp = int(col4)
+                    status = normalize_status(col5) if col5 else "pending"
+                else:
+                    status = normalize_status(col4)
+                    description = col5
+            # Check if col3 is SP (number)
+            elif re.match(r"^\d+$", col3):
+                sp = int(col3)
+                status = normalize_status(col4)
+                # col5 might be actual time or description
+                if col5 and not re.match(r"^\d+\s*min", col5):
+                    description = col5
+            else:
+                # Fallback: treat col3 as size text, col4 as status
+                size = col3[:2].upper() if col3 else None
+                status = normalize_status(col4)
+                description = col5
+
+            # Build content
+            content = f"{story_id}: {name}"
+            if status:
+                content += f" ({status})"
+            if description:
+                content += f" - {description}"
+
+            concept = Concept(
+                id=f"story-{story_id.lower().replace('.', '-')}",
+                type=ConceptType.STORY,
+                file=relative_path,
+                section=f"{story_id}: {name}",
+                lines=(i, i),
+                content=content[:500],
+                metadata={
+                    "story_id": story_id,
+                    "name": name,
+                    "status": status or "pending",
+                    "size": size,
+                    "sp": sp,
+                    "description": description,
+                    "epic_id": epic_id,
+                },
+            )
+            concepts.append(concept)
+
+    return concepts
+
+
+class EpicScopeParser:
+    """GovernanceParser wrapper for Epic scope docs (details + stories)."""
+
+    def can_parse(self, locator: ArtifactLocator) -> bool:
+        """Match Epic scope artifact type."""
+        return locator.artifact_type == CoreArtifactType.EPIC_SCOPE
+
+    def parse(self, locator: ArtifactLocator) -> list[GraphNode]:
+        """Parse Epic scope file into GraphNode list (epic + stories)."""
+        root = Path(locator.metadata["project_root"])
+        path = root / locator.path
+        nodes: list[GraphNode] = []
+        epic_detail = extract_epic_details(path, root)
+        if epic_detail:
+            nodes.append(concept_to_node(epic_detail))
+        stories = extract_stories(path, root)
+        nodes.extend(concept_to_node(s) for s in stories)
+        return nodes

raise_cli/governance/parsers/glossary.py

@@ -0,0 +1,316 @@
+"""Parser for Glossary terms from framework documents.
+
+Extracts term definitions from markdown glossary files.
+Supports version tags, translations, and deprecated markers.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from raise_cli.adapters.models import ArtifactLocator, CoreArtifactType
+from raise_cli.compat import portable_path
+from raise_cli.governance.models import Concept, ConceptType
+from raise_cli.governance.parsers._convert import concept_to_node
+from raise_core.graph.models import GraphNode
+
+# Sections that contain term definitions (extract from these)
+DEFINITION_SECTIONS = {
+    "Términos Core de RaiSE",
+    "Ontología Agentic AI",
+    "Artefactos del Flujo de Trabajo",
+    "Conceptos de Preventa/Proyectos",
+}
+
+# Sections to skip (tables, references, changelog)
+SKIP_SECTIONS = {
+    "Mapeo Español-Inglés",
+    "Anti-Términos",
+    "Changelog",
+    "Jerarquías de Referencia",
+    "Métricas de Calidad AI",
+    "Formato de Referencia a Principios",
+}
+
+
+def _parse_term_header(header: str) -> tuple[str | None, str | None, str | None]:
+    """Parse a term header line.
+
+    Extracts term name, optional translation, and optional version/status.
+
+    Args:
+        header: Header line like "### Agent (Agente)" or "### Kata [v2.3: ...]"
+
+    Returns:
+        Tuple of (name, translation, version) where any can be None.
+
+    Examples:
+        >>> _parse_term_header("### Agent (Agente)")
+        ('Agent', 'Agente', None)
+        >>> _parse_term_header("### Kata [v2.3: Work Cycles]")
+        ('Kata', None, 'v2.3: Work Cycles')
+        >>> _parse_term_header("### Gate Engine ⚠️ **DEPRECATED v2.6**")
+        ('Gate Engine', None, 'DEPRECATED v2.6')
+    """
+    if not header.startswith("###"):
+        return None, None, None
+
+    # Remove ### prefix and strip
+    text = header[3:].strip()
+
+    name: str | None = None
+    translation: str | None = None
+    version: str | None = None
+
+    # Check for DEPRECATED marker (with or without emoji)
+    deprecated_match = re.search(r"\*\*DEPRECATED\s+(v[\d.]+)\*\*", text)
+    if deprecated_match:
+        version = f"DEPRECATED {deprecated_match.group(1)}"
+        # Remove deprecated marker from text
+        text = text[: deprecated_match.start()].strip()
+        # Remove emoji if present
+        text = text.replace("⚠️", "").strip()
+
+    # Check for **[ACTUALIZADO vX.X]** or **[NUEVO vX.X]** pattern
+    update_match = re.search(r"\*\*\[(ACTUALIZADO|NUEVO)\s+(v[\d.]+)\]\*\*", text)
+    if update_match and not version:
+        version = update_match.group(2)  # Just the version number
+        text = text[: update_match.start()].strip()
+
+    # Check for [vX.X: description] version tag
+    version_match = re.search(r"\[(v[\d.]+[^\]]*)\]", text)
+    if version_match and not version:  # Don't override DEPRECATED or ACTUALIZADO
+        version = version_match.group(1)
+        text = text[: version_match.start()].strip()
+
+    # Check for (Translation) pattern
+    trans_match = re.search(r"\(([^)]+)\)$", text)
+    if trans_match:
+        translation = trans_match.group(1)
+        text = text[: trans_match.start()].strip()
+
+    name = text if text else None
+
+    return name, translation, version
+
+
+def _extract_term_content(content: str) -> tuple[str, str | None]:
+    """Extract definition and version tag from term content.
+
+    Args:
+        content: Content text after the term header.
+
+    Returns:
+        Tuple of (definition, version_tag) where version_tag may be None.
+
+    Examples:
+        >>> definition, version = _extract_term_content("**[NUEVO v2.0]** Discipline...")
+        >>> version
+        'v2.0'
+    """
+    version_tag: str | None = None
+
+    # Check for **[NUEVO vX.X]** at start
+    bold_match = re.match(r"\*\*\[NUEVO\s+(v[\d.]+)\]\*\*\s*", content)
+    if bold_match:
+        version_tag = bold_match.group(1)
+        content = content[bold_match.end() :]
+
+    # Check for [NUEVO vX.X] at start (without bold)
+    if not version_tag:
+        plain_match = re.match(r"\[NUEVO\s+(v[\d.]+)\]\s*", content)
+        if plain_match:
+            version_tag = plain_match.group(1)
+            content = content[plain_match.end() :]
+
+    # Clean up content - take first paragraph or up to 500 chars
+    definition = content.strip()
+
+    return definition, version_tag
+
+
+def _find_terms_in_section(
+    content: str, section_start: int, section_end: int, lines: list[str]
+) -> list[tuple[int, str, str]]:
+    """Find all term definitions within a section.
+
+    Args:
+        content: Full file content.
+        section_start: Character offset where section starts.
+        section_end: Character offset where section ends.
+        lines: List of lines in the file.
+
+    Returns:
+        List of (line_number, term_header, term_content) tuples.
+    """
+    section_text = content[section_start:section_end]
+    terms: list[tuple[int, str, str]] = []
+
+    # Find all ### headers in section
+    term_pattern = re.compile(r"^###\s+.+$", re.MULTILINE)
+    matches = list(term_pattern.finditer(section_text))
+
+    for i, match in enumerate(matches):
+        header = match.group(0)
+
+        # Find content (until next ### or end of section)
+        content_start = match.end()
+        content_end = (
+            matches[i + 1].start() if i + 1 < len(matches) else len(section_text)
+        )
+        term_content = section_text[content_start:content_end].strip()
+
+        # Calculate line number
+        # Count newlines from start of section to match
+        line_offset = section_text[: match.start()].count("\n")
+        # Count newlines from start of file to section
+        section_line = content[:section_start].count("\n") + 1
+        term_line = section_line + line_offset
+
+        terms.append((term_line, header, term_content))
+
+    return terms
+
+
+def extract_glossary_terms(
+    file_path: Path, project_root: Path | None = None
+) -> list[Concept]:
+    """Extract glossary terms from a glossary markdown file.
+
+    Parses term definitions from sections like "Términos Core de RaiSE".
+    Each term becomes a Concept with type TERM.
+
+    Args:
+        file_path: Path to glossary markdown file.
+        project_root: Project root for relative path calculation.
+
+    Returns:
+        List of Concept objects representing glossary terms.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> terms = extract_glossary_terms(Path("framework/reference/glossary.md"))
+        >>> len(terms) > 0
+        True
+        >>> terms[0].type
+        <ConceptType.TERM: 'term'>
+    """
+    if not file_path.exists():
+        return []
+
+    if project_root is None:
+        project_root = file_path.parent.parent.parent  # framework/reference/ -> root
+
+    content = file_path.read_text(encoding="utf-8")
+    lines = content.split("\n")
+    concepts: list[Concept] = []
+
+    # Calculate relative path
+    try:
+        relative_path = portable_path(file_path, project_root)
+    except ValueError:
+        relative_path = file_path.name
+
+    # Find ## section boundaries
+    section_pattern = re.compile(r"^##\s+(.+?)$", re.MULTILINE)
+    section_matches = list(section_pattern.finditer(content))
+
+    for i, match in enumerate(section_matches):
+        section_name = match.group(1).strip()
+
+        # Skip non-definition sections
+        if section_name in SKIP_SECTIONS:
+            continue
+
+        # Only process definition sections (or any section not explicitly skipped)
+        # This allows for flexibility if new sections are added
+        section_start = match.end()
+        section_end = (
+            section_matches[i + 1].start()
+            if i + 1 < len(section_matches)
+            else len(content)
+        )
+
+        # Find terms in this section
+        terms = _find_terms_in_section(content, section_start, section_end, lines)
+
+        for term_line, header, term_content in terms:
+            name, translation, header_version = _parse_term_header(header)
+
+            if not name:
+                continue
+
+            # Extract definition and check for version tag in content
+            definition, content_version = _extract_term_content(term_content)
+
+            # Use header version if present, else content version
+            version = header_version or content_version
+
+            # Generate ID from name (lowercase, hyphenated)
+            term_id = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+            # Truncate definition if needed
+            if len(definition) > 500:
+                definition = definition[:500] + "..."
+
+            concept = Concept(
+                id=f"term-{term_id}",
+                type=ConceptType.TERM,
+                file=relative_path,
+                section=f"{section_name}: {name}",
+                lines=(term_line, term_line + 10),  # Approximate end
+                content=definition,
+                metadata={
+                    "name": name,
+                    "translation": translation,
+                    "version": version,
+                    "section": section_name,
+                },
+            )
+            concepts.append(concept)
+
+    return concepts
+
+
+def extract_all_terms(project_root: Path | None = None) -> list[Concept]:
+    """Extract all glossary terms from standard location.
+
+    Looks for framework/reference/glossary.md.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        List of all extracted term Concepts.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> terms = extract_all_terms(Path("."))
+        >>> len(terms) >= 30
+        True
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    glossary_file = project_root / "framework" / "reference" / "glossary.md"
+
+    if glossary_file.exists():
+        return extract_glossary_terms(glossary_file, project_root)
+
+    return []
+
+
+class GlossaryParser:
+    """GovernanceParser wrapper for glossary terms."""
+
+    def can_parse(self, locator: ArtifactLocator) -> bool:
+        """Match Glossary artifact type."""
+        return locator.artifact_type == CoreArtifactType.GLOSSARY
+
+    def parse(self, locator: ArtifactLocator) -> list[GraphNode]:
+        """Parse Glossary file into GraphNode list."""
+        root = Path(locator.metadata["project_root"])
+        path = root / locator.path
+        concepts = extract_glossary_terms(path, root)
+        return [concept_to_node(c) for c in concepts]