raise-cli 2.2.1__py3-none-any.whl

raise_cli/gates/models.py

@@ -0,0 +1,40 @@
+"""Gate dataclasses — context and result types.
+
+Frozen dataclasses (not Pydantic) because these are internal infrastructure,
+not boundary objects. Same rationale as hook events (ADR-039 §2).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class GateContext:
+    """Context passed to a gate's ``evaluate()`` method.
+
+    Attributes:
+        gate_id: Identifier of the gate being evaluated.
+        working_dir: Project working directory. Defaults to ``Path.cwd()``.
+    """
+
+    gate_id: str
+    working_dir: Path = field(default_factory=Path.cwd)
+
+
+@dataclass(frozen=True)
+class GateResult:
+    """Result returned by a gate's ``evaluate()`` method.
+
+    Attributes:
+        passed: Whether the gate passed validation.
+        gate_id: Identifier of the gate that produced this result.
+        message: Human-readable summary (actionable for failures).
+        details: Additional detail lines (e.g. individual errors).
+    """
+
+    passed: bool
+    gate_id: str
+    message: str = ""
+    details: tuple[str, ...] = ()

raise_cli/gates/protocol.py

@@ -0,0 +1,41 @@
+"""WorkflowGate Protocol — contract for gate implementations.
+
+Gates guard workflow transitions. They validate and block operations.
+A gate failure prevents the operation with an actionable message.
+
+Architecture: ADR-039 §1 (WorkflowGate Protocol)
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Protocol, runtime_checkable
+
+from raise_cli.gates.models import GateContext, GateResult
+
+
+@runtime_checkable
+class WorkflowGate(Protocol):
+    """Contract for workflow gate implementations.
+
+    Attributes:
+        gate_id: Unique identifier (e.g. ``"gate-tests"``).
+        description: Human-readable purpose (e.g. ``"All tests pass"``).
+        workflow_point: When this gate runs (e.g. ``"before:release:publish"``).
+
+    Example::
+
+        class TestGate:
+            gate_id = "gate-tests"
+            description = "All tests pass"
+            workflow_point = "before:release:publish"
+
+            def evaluate(self, context: GateContext) -> GateResult:
+                # run pytest, return result...
+                return GateResult(passed=True, gate_id=self.gate_id)
+    """
+
+    gate_id: ClassVar[str]
+    description: ClassVar[str]
+    workflow_point: ClassVar[str]
+
+    def evaluate(self, context: GateContext) -> GateResult: ...

raise_cli/gates/registry.py

@@ -0,0 +1,141 @@
+"""Gate registry with entry point discovery.
+
+Discovers WorkflowGate implementations registered via Python entry points
+(``[project.entry-points."rai.gates"]`` in pyproject.toml). Validates
+Protocol conformance before accepting gates.
+
+Architecture: ADR-039 §3 (Entry point discovery, same as RAISE-211)
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+from raise_cli.gates.protocol import WorkflowGate
+
+logger = logging.getLogger(__name__)
+
+EP_GATES: str = "rai.gates"
+
+
+def _dist_name(ep: Any) -> str:
+    """Best-effort extraction of the distribution name for an entry point."""
+    try:
+        return ep.dist.name  # type: ignore[union-attr]
+    except AttributeError:
+        return "unknown"
+
+
+class GateRegistry:
+    """Discovers and manages WorkflowGate implementations.
+
+    Example::
+
+        registry = GateRegistry()
+        registry.discover()  # loads from rai.gates entry points
+
+        for gate in registry.gates:
+            print(f"{gate.gate_id}: {gate.description}")
+
+        gate = registry.get_gate("gate-tests")
+        release_gates = registry.get_gates_for_point("before:release:publish")
+    """
+
+    def __init__(self) -> None:
+        self._gates: list[WorkflowGate] = []
+
+    @property
+    def gates(self) -> list[WorkflowGate]:
+        """Return a copy of registered gates."""
+        return list(self._gates)
+
+    def discover(self) -> None:
+        """Load gates from ``rai.gates`` entry points.
+
+        Skips entry points that:
+        - Fail to load (ImportError, etc.)
+        - Are not classes
+        - Don't conform to the WorkflowGate Protocol
+        """
+        for ep in entry_points(group=EP_GATES):
+            try:
+                loaded: Any = ep.load()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Skipping gate entry point '%s' from '%s': %s",
+                    ep.name,
+                    _dist_name(ep),
+                    exc,
+                )
+                continue
+
+            if not inspect.isclass(loaded):
+                logger.warning(
+                    "Skipping gate entry point '%s' from '%s': expected a class, got %s",
+                    ep.name,
+                    _dist_name(ep),
+                    type(loaded).__name__,
+                )
+                continue
+
+            instance = loaded()
+            if not isinstance(instance, WorkflowGate):
+                logger.warning(
+                    "Skipping gate entry point '%s' from '%s': "
+                    "does not conform to WorkflowGate Protocol",
+                    ep.name,
+                    _dist_name(ep),
+                )
+                continue
+
+            existing = self.get_gate(instance.gate_id)
+            if existing is not None:
+                logger.warning(
+                    "Duplicate gate_id '%s' from entry point '%s' — replacing previous",
+                    instance.gate_id,
+                    ep.name,
+                )
+                self._gates = [g for g in self._gates if g.gate_id != instance.gate_id]
+            self._gates.append(instance)
+            logger.debug(
+                "Loaded gate '%s' (id=%s, point=%s)",
+                ep.name,
+                instance.gate_id,
+                instance.workflow_point,
+            )
+
+    def register(self, gate: WorkflowGate | Any) -> None:
+        """Manually register a gate instance (useful for testing).
+
+        Silently skips non-compliant objects. Warns on duplicate gate IDs.
+        """
+        if not isinstance(gate, WorkflowGate):
+            logger.warning(
+                "Skipping manual gate registration: %s does not conform to WorkflowGate Protocol",
+                type(gate).__name__,
+            )
+            return
+        existing = self.get_gate(gate.gate_id)
+        if existing is not None:
+            logger.warning(
+                "Duplicate gate_id '%s': replacing %s with %s",
+                gate.gate_id,
+                type(existing).__name__,
+                type(gate).__name__,
+            )
+            self._gates = [g for g in self._gates if g.gate_id != gate.gate_id]
+        self._gates.append(gate)
+
+    def get_gate(self, gate_id: str) -> WorkflowGate | None:
+        """Return the gate with the given ID, or ``None``."""
+        for gate in self._gates:
+            if gate.gate_id == gate_id:
+                return gate
+        return None
+
+    def get_gates_for_point(self, workflow_point: str) -> list[WorkflowGate]:
+        """Return gates registered for the given workflow point."""
+        return [g for g in self._gates if g.workflow_point == workflow_point]

raise_cli/governance/__init__.py

@@ -0,0 +1,11 @@
+"""Governance artifact extraction and parsing.
+
+This module provides tools to extract semantic concepts from governance
+markdown files (PRD, Vision, Constitution) to build concept-level graphs
+for Minimum Viable Context (MVC) queries.
+"""
+
+from raise_cli.governance.extractor import GovernanceExtractor
+from raise_cli.governance.models import Concept, ConceptType, ExtractionResult
+
+__all__ = ["Concept", "ConceptType", "ExtractionResult", "GovernanceExtractor"]

raise_cli/governance/extractor.py

@@ -0,0 +1,412 @@
+"""Governance concept extractor orchestrator.
+
+Coordinates multiple parsers to extract concepts from governance files.
+Supports two paths:
+- extract_all() → registry-based, returns list[GraphNode] (new)
+- extract_with_result() → legacy direct imports, returns ExtractionResult (backward compat)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from raise_cli.adapters.models import ArtifactLocator, CoreArtifactType
+from raise_cli.governance.models import Concept, ConceptType, ExtractionResult
+
+# Legacy imports — used only by extract_with_result() and extract_from_file()
+from raise_cli.governance.parsers.adr import extract_all_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.glossary import extract_all_terms
+from raise_cli.governance.parsers.guardrails import extract_all_guardrails
+from raise_cli.governance.parsers.prd import extract_requirements
+from raise_cli.governance.parsers.roadmap import extract_releases
+from raise_cli.governance.parsers.vision import extract_outcomes
+from raise_core.graph.models import GraphNode
+
+logger = logging.getLogger(__name__)
+
+
+class GovernanceExtractor:
+    """Orchestrates extraction of concepts from governance markdown files.
+
+    Two extraction paths:
+    - extract_all(): Uses registry-discovered parsers, returns list[GraphNode].
+    - extract_with_result(): Legacy path with direct imports, returns ExtractionResult
+      with list[Concept]. Maintained for backward compat with ``rai memory extract`` CLI.
+
+    Attributes:
+        project_root: Project root directory for relative path calculation.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> extractor = GovernanceExtractor()
+        >>> nodes = extractor.extract_all()
+        >>> len(nodes) >= 20
+        True
+    """
+
+    def __init__(
+        self,
+        project_root: Path | None = None,
+        parsers: dict[str, type] | None = None,
+    ) -> None:
+        """Initialize the governance extractor.
+
+        Args:
+            project_root: Project root directory. If None, uses current directory.
+            parsers: Optional parser classes for DI/testing. If None, discovers
+                via entry points at call time.
+        """
+        self.project_root = project_root or Path.cwd()
+        self._parser_classes = parsers
+
+    # --- New registry path ---
+
+    def extract_all(self) -> list[GraphNode]:
+        """Extract all governance concepts via registry parsers.
+
+        Builds ArtifactLocators for known artifact locations, discovers
+        parsers via entry points, and delegates parsing to matching parsers.
+
+        Returns:
+            List of GraphNode from all governance artifacts.
+        """
+        locators = self._build_locators()
+        parser_classes = self._get_parser_classes()
+
+        # Instantiate parser classes
+        parsers: list[Any] = []
+        for name, cls in parser_classes.items():
+            try:
+                parsers.append(cls())
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Failed to instantiate parser '%s': %s", name, exc)
+
+        nodes: list[GraphNode] = []
+        for locator in locators:
+            parser = self._find_parser(locator, parsers)
+            if parser is None:
+                logger.debug(
+                    "No parser found for artifact type '%s' at '%s'",
+                    locator.artifact_type,
+                    locator.path,
+                )
+                continue
+            try:
+                result = parser.parse(locator)
+                nodes.extend(result)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Error parsing '%s' with %s: %s",
+                    locator.path,
+                    type(parser).__name__,
+                    exc,
+                )
+
+        return nodes
+
+    def _build_locators(self) -> list[ArtifactLocator]:
+        """Build ArtifactLocators for all known governance artifact locations.
+
+        Hardcodes paths (same locations as the legacy path). For ADR and
+        epic_scope, globs to produce one locator per file.
+
+        Returns:
+            List of ArtifactLocators for existing files.
+        """
+        root = self.project_root
+        meta = {"project_root": str(root)}
+        locators: list[ArtifactLocator] = []
+
+        # Single-file artifacts
+        single_files: list[tuple[str, str]] = [
+            (CoreArtifactType.PRD, "governance/prd.md"),
+            (CoreArtifactType.VISION, "governance/vision.md"),
+            (CoreArtifactType.CONSTITUTION, "framework/reference/constitution.md"),
+            (CoreArtifactType.ROADMAP, "governance/roadmap.md"),
+            (CoreArtifactType.BACKLOG, "governance/backlog.md"),
+            (CoreArtifactType.GUARDRAILS, "governance/guardrails.md"),
+            (CoreArtifactType.GLOSSARY, "framework/reference/glossary.md"),
+        ]
+
+        for artifact_type, rel_path in single_files:
+            if (root / rel_path).exists():
+                locators.append(
+                    ArtifactLocator(
+                        path=rel_path,
+                        artifact_type=artifact_type,
+                        metadata=dict(meta),
+                    )
+                )
+
+        # ADR files — one locator per file (two directories)
+        for adr_dir in ["dev/decisions", "dev/decisions/v2"]:
+            full_dir = root / adr_dir
+            if full_dir.exists():
+                for adr_file in sorted(full_dir.glob("adr-*.md")):
+                    rel = str(adr_file.relative_to(root))
+                    locators.append(
+                        ArtifactLocator(
+                            path=rel,
+                            artifact_type=CoreArtifactType.ADR,
+                            metadata=dict(meta),
+                        )
+                    )
+
+        # Epic scope files — one locator per scope.md
+        for scope_file in sorted(root.glob("work/epics/*/scope.md")):
+            rel = str(scope_file.relative_to(root))
+            locators.append(
+                ArtifactLocator(
+                    path=rel,
+                    artifact_type=CoreArtifactType.EPIC_SCOPE,
+                    metadata=dict(meta),
+                )
+            )
+
+        return locators
+
+    def _find_parser(self, locator: ArtifactLocator, parsers: list[Any]) -> Any | None:
+        """Find first parser that can_parse this locator."""
+        for parser in parsers:
+            if parser.can_parse(locator):
+                return parser
+        return None
+
+    def _get_parser_classes(self) -> dict[str, type]:
+        """Get parser classes from DI or entry point discovery."""
+        if self._parser_classes is not None:
+            return self._parser_classes
+
+        from raise_cli.adapters.registry import get_governance_parsers
+
+        return get_governance_parsers()
+
+    # --- Legacy path (backward compat) ---
+
+    def extract_from_file(
+        self, file_path: Path, concept_type: ConceptType | None = None
+    ) -> list[Concept]:
+        """Extract concepts from a single governance file.
+
+        Args:
+            file_path: Path to governance markdown file.
+            concept_type: Type of concepts to extract. If None, infers from file path.
+
+        Returns:
+            List of extracted concepts.
+
+        Raises:
+            ValueError: If concept_type is None and cannot be inferred from file path.
+        """
+        if not file_path.exists():
+            logger.warning(f"File not found, skipping: {file_path}")
+            return []
+
+        if concept_type is None:
+            concept_type = self._infer_concept_type(file_path)
+
+        if concept_type == ConceptType.REQUIREMENT:
+            return extract_requirements(file_path, self.project_root)
+        elif concept_type == ConceptType.OUTCOME:
+            return extract_outcomes(file_path, self.project_root)
+        elif concept_type == ConceptType.PRINCIPLE:
+            return extract_principles(file_path, self.project_root)
+        else:
+            logger.warning(f"Unsupported concept type: {concept_type}")
+            return []
+
+    def extract_with_result(self) -> ExtractionResult:
+        """Extract all concepts and return detailed result.
+
+        Legacy path: uses direct parser imports, returns ExtractionResult
+        with list[Concept]. Maintained for ``rai memory extract`` CLI which
+        depends on Concept fields (file, section, lines).
+
+        Returns:
+            ExtractionResult with concepts, counts, and errors.
+        """
+        concepts: list[Concept] = []
+        errors: list[str] = []
+        files_processed = 0
+
+        # Extract from PRD
+        prd_file = self.project_root / "governance" / "prd.md"
+        if prd_file.exists():
+            try:
+                prd_concepts = extract_requirements(prd_file, self.project_root)
+                concepts.extend(prd_concepts)
+                files_processed += 1
+            except Exception as e:
+                errors.append(f"Error extracting from {prd_file}: {e}")
+
+        # Extract from Vision
+        vision_file = self.project_root / "governance" / "vision.md"
+        if vision_file.exists():
+            try:
+                vision_concepts = extract_outcomes(vision_file, self.project_root)
+                concepts.extend(vision_concepts)
+                files_processed += 1
+            except Exception as e:
+                errors.append(f"Error extracting from {vision_file}: {e}")
+
+        # Extract from Constitution
+        constitution_file = (
+            self.project_root / "framework" / "reference" / "constitution.md"
+        )
+        if constitution_file.exists():
+            try:
+                constitution_concepts = extract_principles(
+                    constitution_file, self.project_root
+                )
+                concepts.extend(constitution_concepts)
+                files_processed += 1
+            except Exception as e:
+                errors.append(f"Error extracting from {constitution_file}: {e}")
+
+        # Extract work concepts (E8)
+        work_concepts = self._extract_work_concepts()
+        concepts.extend(work_concepts)
+        backlog_file = self.project_root / "governance" / "backlog.md"
+        backlog_count = 1 if backlog_file.exists() else 0
+        epic_count = len(list(self.project_root.glob("work/epics/*/scope.md")))
+        files_processed += backlog_count + epic_count
+
+        # Extract ADR decisions (E12)
+        try:
+            adr_concepts = extract_all_decisions(self.project_root)
+            concepts.extend(adr_concepts)
+            adr_root_count = len(list(self.project_root.glob("dev/decisions/adr-*.md")))
+            adr_v2_count = len(
+                list(self.project_root.glob("dev/decisions/v2/adr-*.md"))
+            )
+            files_processed += adr_root_count + adr_v2_count
+        except Exception as e:
+            errors.append(f"Error extracting ADRs: {e}")
+
+        # Extract Guardrails (E12 F12.2)
+        guardrails_file = self.project_root / "governance" / "guardrails.md"
+        if guardrails_file.exists():
+            try:
+                guardrail_concepts = extract_all_guardrails(self.project_root)
+                concepts.extend(guardrail_concepts)
+                files_processed += 1
+            except Exception as e:
+                errors.append(f"Error extracting guardrails: {e}")
+
+        # Extract Glossary terms (E12 F12.3)
+        glossary_file = self.project_root / "framework" / "reference" / "glossary.md"
+        if glossary_file.exists():
+            try:
+                term_concepts = extract_all_terms(self.project_root)
+                concepts.extend(term_concepts)
+                files_processed += 1
+            except Exception as e:
+                errors.append(f"Error extracting glossary terms: {e}")
+
+        # Extract Releases from roadmap
+        roadmap_file = self.project_root / "governance" / "roadmap.md"
+        if roadmap_file.exists():
+            try:
+                release_concepts = extract_releases(roadmap_file, self.project_root)
+                concepts.extend(release_concepts)
+                files_processed += 1
+            except Exception as e:
+                errors.append(f"Error extracting from {roadmap_file}: {e}")
+
+        return ExtractionResult(
+            concepts=concepts,
+            total=len(concepts),
+            files_processed=files_processed,
+            errors=errors,
+        )
+
+    def _extract_work_concepts(self) -> list[Concept]:
+        """Extract work tracking concepts (Project, Epic, Story).
+
+        Extracts from:
+        - governance/backlog.md (Project + Epic index)
+        - work/epics/*/scope.md (Epic details + Stories)
+
+        Returns:
+            List of work tracking concepts.
+        """
+        concepts: list[Concept] = []
+
+        backlog_file = self.project_root / "governance" / "backlog.md"
+        if backlog_file.exists():
+            try:
+                project = extract_project(backlog_file, self.project_root)
+                if project:
+                    concepts.append(project)
+                    logger.info(f"Extracted project from {backlog_file.name}")
+
+                epic_index = extract_epics(backlog_file, self.project_root)
+                concepts.extend(epic_index)
+                logger.info(
+                    f"Extracted {len(epic_index)} epics from {backlog_file.name}"
+                )
+            except Exception as e:
+                logger.error(f"Error extracting from {backlog_file}: {e}")
+
+        for scope_file in self.project_root.glob("work/epics/*/scope.md"):
+            try:
+                epic_detail = extract_epic_details(scope_file, self.project_root)
+                if epic_detail:
+                    existing = next(
+                        (c for c in concepts if c.id == epic_detail.id), None
+                    )
+                    if existing:
+                        existing.metadata.update(epic_detail.metadata)
+                        existing.content = epic_detail.content
+                    else:
+                        concepts.append(epic_detail)
+                    logger.info(f"Extracted epic details from {scope_file.name}")
+
+                stories = extract_stories(scope_file, self.project_root)
+                concepts.extend(stories)
+                logger.info(f"Extracted {len(stories)} stories from {scope_file.name}")
+            except Exception as e:
+                logger.error(f"Error extracting from {scope_file}: {e}")
+
+        return concepts
+
+    def _infer_concept_type(self, file_path: Path) -> ConceptType:
+        """Infer concept type from file path.
+
+        Args:
+            file_path: Path to governance file.
+
+        Returns:
+            Inferred concept type.
+
+        Raises:
+            ValueError: If concept type cannot be inferred.
+        """
+        file_name = file_path.name.lower()
+
+        if "prd" in file_name or "requirements" in file_name:
+            return ConceptType.REQUIREMENT
+        elif "vision" in file_name:
+            return ConceptType.OUTCOME
+        elif "constitution" in file_name:
+            return ConceptType.PRINCIPLE
+        elif "backlog" in file_name:
+            return ConceptType.PROJECT
+        elif "epic" in file_name and "scope" in file_name:
+            return ConceptType.EPIC
+        elif "guardrails" in file_name:
+            return ConceptType.GUARDRAIL
+        elif "glossary" in file_name:
+            return ConceptType.TERM
+        elif "roadmap" in file_name:
+            return ConceptType.RELEASE
+        else:
+            raise ValueError(
+                f"Cannot infer concept type from file path: {file_path}. "
+                f"Specify concept_type explicitly."
+            )