raise-cli 2.2.1__py3-none-any.whl

raise_cli/governance/models.py

@@ -0,0 +1,134 @@
+"""Pydantic models for governance concept extraction.
+
+This module defines the core data structures for representing semantic
+concepts extracted from governance markdown files.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Self
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class ConceptType(StrEnum):
+    """Types of concepts extracted from governance documents.
+
+    Attributes:
+        REQUIREMENT: Functional requirements from PRD (RF-XX format).
+        OUTCOME: Desired outcomes from Vision document.
+        PRINCIPLE: Core principles from Constitution (§N format).
+        PATTERN: Design patterns from technical design (future).
+        PRACTICE: Process practices from katas (future).
+        PROJECT: Project from backlog (governance/backlog.md).
+        EPIC: Epic from backlog or epic scope documents.
+        STORY: Story from epic scope documents.
+        DECISION: Architecture decision records (ADR-XXX format).
+        GUARDRAIL: Code standards and quality rules.
+        TERM: Glossary definitions for canonical terminology.
+    """
+
+    REQUIREMENT = "requirement"
+    OUTCOME = "outcome"
+    PRINCIPLE = "principle"
+    PATTERN = "pattern"
+    PRACTICE = "practice"
+    # Work tracking types (E8)
+    PROJECT = "project"
+    EPIC = "epic"
+    STORY = "story"
+    # Knowledge graph completion types (E12)
+    DECISION = "decision"
+    GUARDRAIL = "guardrail"
+    TERM = "term"
+    # Release ontology
+    RELEASE = "release"
+
+
+class Concept(BaseModel):
+    """A semantic concept extracted from governance markdown.
+
+    Represents a single extractable unit of governance information
+    (e.g., a requirement, outcome, or principle) with its location
+    and metadata.
+
+    Attributes:
+        id: Unique identifier (e.g., 'req-rf-05', 'outcome-context-generation').
+        type: Type of concept (requirement, outcome, principle, etc.).
+        file: Source file relative path from project root.
+        section: Section heading where concept was found.
+        lines: Tuple of (start_line, end_line) in source file.
+        content: Extracted content, truncated if >500 chars.
+        metadata: Type-specific metadata (e.g., requirement_id, title).
+
+    Examples:
+        >>> concept = Concept(
+        ...     id="req-rf-05",
+        ...     type=ConceptType.REQUIREMENT,
+        ...     file="governance/prd.md",
+        ...     section="RF-05: Golden Context Generation",
+        ...     lines=(206, 214),
+        ...     content="The system MUST generate CLAUDE.md...",
+        ...     metadata={"requirement_id": "RF-05", "title": "Golden Context Generation"}
+        ... )
+        >>> concept.id
+        'req-rf-05'
+        >>> concept.type
+        <ConceptType.REQUIREMENT: 'requirement'>
+    """
+
+    id: str = Field(..., description="Unique identifier (e.g., 'req-rf-05')")
+    type: ConceptType = Field(..., description="Concept type")
+    file: str = Field(..., description="Source file relative path")
+    section: str = Field(..., description="Section heading")
+    lines: tuple[int, int] = Field(..., description="Line range (start, end)")
+    content: str = Field(..., description="Extracted content (truncated if long)")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Type-specific metadata"
+    )
+
+    @model_validator(mode="after")
+    def validate_line_range(self) -> Self:
+        """Validate that line range is valid (start <= end).
+
+        Returns:
+            Self if valid.
+
+        Raises:
+            ValueError: If line range is invalid (start > end).
+        """
+        if self.lines[0] > self.lines[1]:
+            raise ValueError(
+                f"Invalid line range: start ({self.lines[0]}) > end ({self.lines[1]})"
+            )
+        return self
+
+
+class ExtractionResult(BaseModel):
+    """Result of a concept extraction operation.
+
+    Contains the extracted concepts along with metadata about the
+    extraction process (files processed, errors encountered).
+
+    Attributes:
+        concepts: List of extracted concepts.
+        total: Total number of concepts extracted.
+        files_processed: Number of files successfully parsed.
+        errors: List of error messages from failed extractions.
+
+    Examples:
+        >>> result = ExtractionResult(
+        ...     concepts=[concept1, concept2],
+        ...     total=2,
+        ...     files_processed=1,
+        ...     errors=[]
+        ... )
+        >>> result.total
+        2
+    """
+
+    concepts: list[Concept] = Field(default_factory=lambda: list[Concept]())
+    total: int = Field(..., description="Total concepts extracted")
+    files_processed: int = Field(..., description="Number of files parsed")
+    errors: list[str] = Field(default_factory=list)

raise_cli/governance/parsers/__init__.py

@@ -0,0 +1,35 @@
+"""Parsers for governance markdown files.
+
+This module contains parsers for different governance document types
+(PRD, Vision, Constitution, Backlog, Epic, ADR, Guardrails) that extract semantic concepts.
+"""
+
+from raise_cli.governance.parsers.adr import (
+    extract_all_decisions,
+    extract_decision_from_file,
+    extract_decisions,
+)
+from raise_cli.governance.parsers.backlog import extract_epics, extract_project
+from raise_cli.governance.parsers.constitution import extract_principles
+from raise_cli.governance.parsers.epic import extract_epic_details, extract_stories
+from raise_cli.governance.parsers.guardrails import (
+    extract_all_guardrails,
+    extract_guardrails,
+)
+from raise_cli.governance.parsers.prd import extract_requirements
+from raise_cli.governance.parsers.vision import extract_outcomes
+
+__all__ = [
+    "extract_requirements",
+    "extract_outcomes",
+    "extract_principles",
+    "extract_project",
+    "extract_epics",
+    "extract_epic_details",
+    "extract_stories",
+    "extract_decisions",
+    "extract_decision_from_file",
+    "extract_all_decisions",
+    "extract_guardrails",
+    "extract_all_guardrails",
+]

raise_cli/governance/parsers/_convert.py

@@ -0,0 +1,38 @@
+"""Concept to GraphNode conversion utility.
+
+Extracted from GraphBuilder._concept_to_node() for reuse
+by GovernanceParser wrapper classes.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from raise_cli.governance.models import Concept
+from raise_core.graph.models import GraphNode
+
+
+def concept_to_node(concept: Concept) -> GraphNode:
+    """Convert governance Concept to GraphNode (GraphNode).
+
+    Preserves section and lines in metadata since GraphNode has no
+    dedicated fields for these (R3 from quality review).
+
+    Args:
+        concept: Governance concept to convert.
+
+    Returns:
+        GraphNode with mapped fields.
+    """
+    metadata = dict(concept.metadata)
+    metadata["section"] = concept.section
+    metadata["lines"] = concept.lines
+
+    return GraphNode(
+        id=concept.id,
+        type=concept.type.value,
+        content=concept.content,
+        source_file=concept.file,
+        created=datetime.now(tz=UTC).isoformat(),
+        metadata=metadata,
+    )

raise_cli/governance/parsers/adr.py

@@ -0,0 +1,274 @@
+"""Parser for Architecture Decision Records (ADRs).
+
+Extracts decisions from ADR markdown files with YAML frontmatter.
+Supports ADRs in dev/decisions/ (root and v2 subdirectory).
+Legacy v1 ADRs without frontmatter are skipped.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+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
+
+
+def _parse_frontmatter(text: str) -> tuple[dict[str, Any], str, int]:
+    """Parse YAML frontmatter from markdown text.
+
+    Args:
+        text: Full markdown text content.
+
+    Returns:
+        Tuple of (frontmatter dict, remaining content, frontmatter end line).
+        Returns empty dict if no frontmatter found.
+
+    Examples:
+        >>> text = "---\\nid: ADR-001\\n---\\n# Title"
+        >>> fm, content, end_line = _parse_frontmatter(text)
+        >>> fm["id"]
+        'ADR-001'
+    """
+    if not text.startswith("---"):
+        return {}, text, 0
+
+    # Find closing ---
+    lines = text.split("\n")
+    end_idx = None
+    for i, line in enumerate(lines[1:], 1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        return {}, text, 0
+
+    # Parse YAML
+    frontmatter_text = "\n".join(lines[1:end_idx])
+    try:
+        loaded = yaml.safe_load(frontmatter_text)
+        frontmatter: dict[str, Any] = cast(dict[str, Any], loaded) if loaded else {}
+    except yaml.YAMLError:
+        return {}, text, 0
+
+    remaining = "\n".join(lines[end_idx + 1 :])
+    return frontmatter, remaining, end_idx + 1
+
+
+def _extract_decision_summary(content: str) -> str:
+    """Extract the Decision section content as summary.
+
+    Args:
+        content: Markdown content after frontmatter.
+
+    Returns:
+        Decision section content, truncated to ~500 chars.
+
+    Examples:
+        >>> content = "## Context\\nSome context.\\n## Decision\\nWe decided X."
+        >>> _extract_decision_summary(content)
+        'We decided X.'
+    """
+    # Look for ## Decision or ## Decisión section
+    match = re.search(
+        r"^##\s+(?:Decision|Decisión)\s*\n(.*?)(?=^##\s|\Z)",
+        content,
+        re.MULTILINE | re.DOTALL | re.IGNORECASE,
+    )
+
+    if match:
+        decision_text = match.group(1).strip()
+        # Truncate if too long
+        if len(decision_text) > 500:
+            decision_text = decision_text[:500] + "..."
+        return decision_text
+
+    # Fallback: use first paragraph after title
+    lines = content.strip().split("\n")
+    for i, line in enumerate(lines):
+        if line.startswith("# "):
+            # Skip title, get next non-empty content
+            for j in range(i + 1, min(i + 10, len(lines))):
+                if lines[j].strip() and not lines[j].startswith("#"):
+                    return lines[j].strip()[:500]
+
+    return ""
+
+
+def extract_decisions(
+    directory: Path, project_root: Path | None = None
+) -> list[Concept]:
+    """Extract ADR decisions from a directory.
+
+    Parses ADR files with YAML frontmatter containing id, title, status, date.
+    Files without frontmatter are skipped (legacy v1 format).
+
+    Args:
+        directory: Directory containing ADR markdown files.
+        project_root: Project root for relative path calculation.
+
+    Returns:
+        List of Concept objects representing decisions.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> decisions = extract_decisions(Path("dev/decisions"))
+        >>> len(decisions) > 0
+        True
+        >>> decisions[0].type
+        <ConceptType.DECISION: 'decision'>
+    """
+    if not directory.exists():
+        return []
+
+    if project_root is None:
+        project_root = directory.parent
+
+    concepts: list[Concept] = []
+
+    # Process ADR files in directory
+    for adr_file in sorted(directory.glob("adr-*.md")):
+        concept = extract_decision_from_file(adr_file, project_root)
+        if concept:
+            concepts.append(concept)
+
+    return concepts
+
+
+def extract_decision_from_file(
+    file_path: Path, project_root: Path | None = None
+) -> Concept | None:
+    """Extract a single ADR decision from a file.
+
+    Args:
+        file_path: Path to ADR markdown file.
+        project_root: Project root for relative path calculation.
+
+    Returns:
+        Concept object if valid ADR with frontmatter, None otherwise.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> decision = extract_decision_from_file(Path("dev/decisions/adr-019.md"))
+        >>> decision.id if decision else None
+        'ADR-019'
+    """
+    if not file_path.exists():
+        return None
+
+    if project_root is None:
+        project_root = file_path.parent.parent
+
+    text = file_path.read_text(encoding="utf-8")
+    frontmatter, content, _ = _parse_frontmatter(text)
+
+    # Skip files without frontmatter (legacy format)
+    if not frontmatter:
+        return None
+
+    # Required fields
+    adr_id = frontmatter.get("id")
+    if not adr_id:
+        return None
+
+    title = frontmatter.get("title", "")
+    status = frontmatter.get("status", "unknown")
+    date = frontmatter.get("date", "")
+    related_to = frontmatter.get("related_to", [])
+
+    # Extract decision summary
+    decision_summary = _extract_decision_summary(content)
+
+    # Build content string
+    content_str = f"{title}"
+    if decision_summary:
+        content_str = f"{title} — {decision_summary}"
+
+    # Truncate if needed
+    if len(content_str) > 500:
+        content_str = content_str[:500] + "..."
+
+    # Calculate relative path
+    try:
+        relative_path = portable_path(file_path, project_root)
+    except ValueError:
+        relative_path = file_path.name
+
+    # Count lines for line range
+    total_lines = len(text.split("\n"))
+
+    return Concept(
+        id=f"decision-{adr_id.lower()}",
+        type=ConceptType.DECISION,
+        file=relative_path,
+        section=f"{adr_id}: {title}",
+        lines=(1, total_lines),
+        content=content_str,
+        metadata={
+            "adr_id": adr_id,
+            "title": title,
+            "status": status,
+            "date": str(date) if date else "",
+            "related_to": related_to if isinstance(related_to, list) else [],
+        },
+    )
+
+
+def extract_all_decisions(project_root: Path | None = None) -> list[Concept]:
+    """Extract all ADR decisions from standard locations.
+
+    Searches dev/decisions/ (root) and dev/decisions/v2/ for ADRs.
+    Skips dev/decisions/v1/ (legacy format without frontmatter).
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        List of all extracted decision Concepts.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> decisions = extract_all_decisions(Path("."))
+        >>> len(decisions) >= 20
+        True
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    concepts: list[Concept] = []
+
+    # Root level ADRs
+    root_decisions = project_root / "dev" / "decisions"
+    if root_decisions.exists():
+        concepts.extend(extract_decisions(root_decisions, project_root))
+
+    # v2 subdirectory ADRs
+    v2_decisions = project_root / "dev" / "decisions" / "v2"
+    if v2_decisions.exists():
+        concepts.extend(extract_decisions(v2_decisions, project_root))
+
+    # Note: v1 is intentionally skipped (legacy format without frontmatter)
+
+    return concepts
+
+
+class AdrParser:
+    """GovernanceParser wrapper for ADR decisions. Per-file parsing."""
+
+    def can_parse(self, locator: ArtifactLocator) -> bool:
+        """Match ADR artifact type."""
+        return locator.artifact_type == CoreArtifactType.ADR
+
+    def parse(self, locator: ArtifactLocator) -> list[GraphNode]:
+        """Parse single ADR file pointed to by locator."""
+        root = Path(locator.metadata["project_root"])
+        path = root / locator.path
+        concept = extract_decision_from_file(path, root)
+        return [concept_to_node(concept)] if concept else []