raise-cli 2.2.1__py3-none-any.whl

raise_cli/config/settings.py

@@ -0,0 +1,180 @@
+"""Configuration settings for raise-cli using Pydantic Settings.
+
+Implements configuration cascade with proper precedence:
+1. CLI arguments (highest priority)
+2. Environment variables (RAI_* prefix)
+3. Project config (pyproject.toml)
+4. User config (~/.config/rai/config.toml)
+5. Defaults (lowest priority)
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+)
+
+if sys.version_info >= (3, 11):  # noqa: UP036
+    import tomllib
+else:
+    import tomli as tomllib
+
+from raise_cli.config.paths import get_config_dir
+
+
+class TomlConfigSource(PydanticBaseSettingsSource):
+    """Custom settings source for TOML configuration files."""
+
+    def __init__(
+        self,
+        settings_cls: type[BaseSettings],
+        toml_file: Path | None = None,
+        toml_table: str = "rai",
+    ):
+        """Initialize TOML config source.
+
+        Args:
+            settings_cls: The settings class
+            toml_file: Path to TOML file (None = auto-detect)
+            toml_table: Table name in TOML file (default: "rai")
+        """
+        super().__init__(settings_cls)
+        self.toml_file = toml_file
+        self.toml_table = toml_table
+
+    def get_field_value(self, field: Any, field_name: str) -> tuple[Any, str, bool]:
+        """Get field value from TOML file."""
+        # Not used in newer pydantic-settings
+        return None, "", False
+
+    def __call__(self) -> dict[str, Any]:
+        """Load settings from TOML file."""
+        if self.toml_file is None or not self.toml_file.exists():
+            return {}
+
+        try:
+            with open(self.toml_file, "rb") as f:
+                data = tomllib.load(f)
+
+            # Handle pyproject.toml with [tool.rai] section
+            if self.toml_file.name == "pyproject.toml":
+                return data.get("tool", {}).get(self.toml_table, {})
+            # Handle user config with [rai] section
+            else:
+                return data.get(self.toml_table, {})
+        except Exception:
+            # Silently ignore TOML parsing errors (graceful degradation)
+            return {}
+
+
+class RaiSettings(BaseSettings):
+    """Configuration settings for raise-cli with proper cascade precedence.
+
+    Settings are loaded in order of precedence (highest to lowest):
+    1. Constructor arguments (from CLI)
+    2. Environment variables (RAI_* prefix)
+    3. Project pyproject.toml [tool.rai] section
+    4. User config file (~/.config/rai/config.toml)
+    5. Field defaults
+
+    Example:
+        >>> # Load with defaults and env vars
+        >>> settings = RaiSettings()
+        >>> # Override specific values (e.g., from CLI)
+        >>> settings = RaiSettings(output_format="json", verbosity=2)
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="RAI_",
+        extra="ignore",
+    )
+
+    # Output settings
+    output_format: Literal["human", "json", "table"] = Field(
+        default="human",
+        description="Output format for CLI commands",
+    )
+    color: bool = Field(
+        default=True,
+        description="Enable colored output",
+    )
+    verbosity: int = Field(
+        default=0,
+        ge=-1,
+        le=3,
+        description="Verbosity level: -1=quiet, 0=normal, 1-3=verbose",
+    )
+
+    # Paths (project-level)
+    raise_dir: Path = Field(
+        default=Path(".raise"),
+        description="Directory containing RaiSE framework files",
+    )
+    governance_dir: Path = Field(
+        default=Path("governance"),
+        description="Directory containing governance artifacts",
+    )
+    work_dir: Path = Field(
+        default=Path("work"),
+        description="Directory containing active work",
+    )
+
+    # External tools (graceful degradation handled by core utilities)
+    ast_grep_path: str | None = Field(
+        default=None,
+        description="Path to ast-grep binary (auto-detected if None)",
+    )
+    ripgrep_path: str | None = Field(
+        default=None,
+        description="Path to ripgrep binary (auto-detected if None)",
+    )
+
+    # Feature flags
+    interactive: bool = Field(
+        default=False,
+        description="Enable interactive prompts",
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Customize settings sources to include TOML files.
+
+        Order (highest to lowest priority):
+        1. init_settings (constructor args / CLI)
+        2. env_settings (environment variables)
+        3. project_toml (pyproject.toml)
+        4. user_toml (~/.config/rai/config.toml)
+        5. file defaults (from Field definitions)
+        """
+        # Project-level config
+        project_toml = TomlConfigSource(
+            settings_cls, toml_file=Path("pyproject.toml"), toml_table="rai"
+        )
+
+        # User-level config
+        user_config_file = get_config_dir() / "config.toml"
+        user_toml = TomlConfigSource(
+            settings_cls, toml_file=user_config_file, toml_table="rai"
+        )
+
+        return (
+            init_settings,  # CLI args (highest priority)
+            env_settings,  # Environment variables
+            project_toml,  # pyproject.toml
+            user_toml,  # User config
+            # Field defaults are always last (implicit)
+        )

raise_cli/context/__init__.py

@@ -0,0 +1,42 @@
+"""Context module for cross-domain knowledge retrieval.
+
+Re-exports graph domain types from raise_core and local context components.
+"""
+
+from __future__ import annotations
+
+from raise_cli.context.builder import GraphBuilder
+from raise_cli.context.diff import GraphDiff, NodeChange, diff_graphs
+from raise_core.graph.engine import Graph
+from raise_core.graph.models import (
+    CoreEdgeTypes,
+    EdgeType,
+    GraphEdge,
+    GraphNode,
+    NodeType,
+)
+from raise_core.graph.query import (
+    Query,
+    QueryEngine,
+    QueryMetadata,
+    QueryResult,
+    QueryStrategy,
+)
+
+__all__ = [
+    "CoreEdgeTypes",
+    "EdgeType",
+    "Graph",
+    "GraphDiff",
+    "GraphEdge",
+    "GraphNode",
+    "NodeChange",
+    "NodeType",
+    "Query",
+    "QueryEngine",
+    "QueryMetadata",
+    "QueryResult",
+    "QueryStrategy",
+    "GraphBuilder",
+    "diff_graphs",
+]

raise_cli/context/analyzers/__init__.py

@@ -0,0 +1,16 @@
+"""Code analyzers for extracting module structure from source code.
+
+This package provides language-specific analyzers that extract imports,
+exports, and component counts from source modules. Results enrich the
+unified graph with real code data alongside manually-maintained frontmatter.
+
+Architecture: S16.1 — Code-Aware Graph
+"""
+
+from __future__ import annotations
+
+from raise_cli.context.analyzers.models import ModuleInfo
+from raise_cli.context.analyzers.protocol import CodeAnalyzer
+from raise_cli.context.analyzers.python import PythonAnalyzer
+
+__all__ = ["CodeAnalyzer", "ModuleInfo", "PythonAnalyzer"]

raise_cli/context/analyzers/models.py

@@ -0,0 +1,36 @@
+"""Pydantic models for code analysis results.
+
+Architecture: S16.1 — Code-Aware Graph
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModuleInfo(BaseModel):
+    """Language-agnostic module analysis result.
+
+    Attributes:
+        name: Module name (e.g., 'memory', 'config').
+        language: Programming language (e.g., 'python').
+        source_path: Relative path to the module directory.
+        imports: Other modules this one imports from.
+        exports: Public API names exported by this module.
+        component_count: Number of classes + top-level functions.
+        entry_points: CLI commands or other entry points, if detectable.
+    """
+
+    name: str = Field(..., description="Module name")
+    language: str = Field(..., description="Programming language")
+    source_path: str = Field(..., description="Relative path to module directory")
+    imports: list[str] = Field(
+        default_factory=lambda: list[str](), description="Imported module names"
+    )
+    exports: list[str] = Field(
+        default_factory=lambda: list[str](), description="Exported public API names"
+    )
+    component_count: int = Field(..., description="Classes + top-level functions")
+    entry_points: list[str] = Field(
+        default_factory=lambda: list[str](), description="CLI commands or entry points"
+    )

raise_cli/context/analyzers/protocol.py

@@ -0,0 +1,43 @@
+"""Protocol definition for code analyzers.
+
+Architecture: S16.1 — Code-Aware Graph
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from raise_cli.context.analyzers.models import ModuleInfo
+
+
+@runtime_checkable
+class CodeAnalyzer(Protocol):
+    """Contract for language-specific code analyzers.
+
+    Implementations must provide:
+    - detect(): Check if the project uses this language.
+    - analyze_modules(): Extract module-level structure.
+    """
+
+    def detect(self, project_root: Path) -> bool:
+        """Check if this analyzer applies to the given project.
+
+        Args:
+            project_root: Root directory of the project.
+
+        Returns:
+            True if the project uses this language.
+        """
+        ...
+
+    def analyze_modules(self, project_root: Path) -> list[ModuleInfo]:
+        """Extract module-level structure from source code.
+
+        Args:
+            project_root: Root directory of the project.
+
+        Returns:
+            List of ModuleInfo for each detected module.
+        """
+        ...

raise_cli/context/analyzers/python.py

@@ -0,0 +1,292 @@
+"""Python-specific code analyzer using ast module.
+
+Extracts imports, exports, and component counts from Python modules
+by parsing source files with ast.parse().
+
+Architecture: S16.1 — Code-Aware Graph
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from raise_cli.compat import portable_path
+from raise_cli.context.analyzers.models import ModuleInfo
+
+
+class PythonAnalyzer:
+    """Analyzes Python modules using ast to extract structure.
+
+    Attributes:
+        src_dir: Relative path to the source directory (e.g., 'src/raise_cli').
+    """
+
+    def __init__(self, src_dir: str) -> None:
+        self.src_dir = src_dir
+        self._package_name = Path(src_dir).name
+
+    def detect(self, project_root: Path) -> bool:
+        """Check if the project is a Python project.
+
+        Args:
+            project_root: Root directory of the project.
+
+        Returns:
+            True if pyproject.toml or setup.py exists.
+        """
+        return (project_root / "pyproject.toml").exists() or (
+            project_root / "setup.py"
+        ).exists()
+
+    def analyze_modules(self, project_root: Path) -> list[ModuleInfo]:
+        """Extract module-level structure from all Python modules.
+
+        Args:
+            project_root: Root directory of the project.
+
+        Returns:
+            List of ModuleInfo for each module directory.
+        """
+        src_path = project_root / self.src_dir
+        if not src_path.exists():
+            return []
+
+        modules: list[ModuleInfo] = []
+        for entry in sorted(src_path.iterdir()):
+            if not entry.is_dir():
+                continue
+            if entry.name.startswith("__"):
+                continue
+            if not (entry / "__init__.py").exists():
+                continue
+
+            info = self._analyze_module(entry, project_root)
+            modules.append(info)
+
+        return modules
+
+    def _analyze_module(self, module_dir: Path, project_root: Path) -> ModuleInfo:
+        """Analyze a single module directory.
+
+        Args:
+            module_dir: Path to the module directory.
+            project_root: Root directory of the project.
+
+        Returns:
+            ModuleInfo with extracted data.
+        """
+        module_name = module_dir.name
+        py_files = sorted(module_dir.rglob("*.py"))
+
+        imports: set[str] = set()
+        component_count = 0
+
+        for py_file in py_files:
+            tree = self._parse_file(py_file)
+            if tree is None:
+                continue
+
+            # Skip __init__.py for imports (handled separately for exports)
+            if py_file.name != "__init__.py":
+                file_imports = self._extract_imports(tree, module_name)
+                imports.update(file_imports)
+            else:
+                # __init__.py imports from siblings also count as module deps
+                file_imports = self._extract_imports(tree, module_name)
+                imports.update(file_imports)
+
+            component_count += self._count_components(tree)
+
+        exports = self._extract_exports(module_dir)
+
+        try:
+            source_path = portable_path(module_dir, project_root)
+        except ValueError:
+            source_path = str(module_dir)
+
+        return ModuleInfo(
+            name=module_name,
+            language="python",
+            source_path=source_path,
+            imports=sorted(imports),
+            exports=sorted(exports),
+            component_count=component_count,
+            entry_points=[],
+        )
+
+    def _parse_file(self, py_file: Path) -> ast.Module | None:
+        """Parse a Python file into AST.
+
+        Args:
+            py_file: Path to the .py file.
+
+        Returns:
+            Parsed AST or None on failure.
+        """
+        try:
+            source = py_file.read_text(encoding="utf-8")
+            return ast.parse(source, filename=str(py_file))
+        except (SyntaxError, UnicodeDecodeError):
+            return None
+
+    def _extract_imports(self, tree: ast.Module, module_name: str) -> set[str]:
+        """Extract internal module imports, skipping TYPE_CHECKING blocks.
+
+        Args:
+            tree: Parsed AST.
+            module_name: Name of the current module (to exclude self-imports).
+
+        Returns:
+            Set of imported module names (siblings only).
+        """
+        visitor = _ImportVisitor(self._package_name, module_name)
+        visitor.visit(tree)
+        return visitor.imports
+
+    def _extract_exports(self, module_dir: Path) -> list[str]:
+        """Extract public API from __init__.py.
+
+        Uses __all__ if present, otherwise imported names.
+
+        Args:
+            module_dir: Path to the module directory.
+
+        Returns:
+            List of exported names.
+        """
+        init_file = module_dir / "__init__.py"
+        if not init_file.exists():
+            return []
+
+        tree = self._parse_file(init_file)
+        if tree is None:
+            return []
+
+        # Check for __all__
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == "__all__":
+                        return self._extract_all_list(node.value)
+
+        # Fallback: extract imported names from __init__.py
+        names: list[str] = []
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, ast.ImportFrom) and node.names:
+                for alias in node.names:
+                    name = alias.asname if alias.asname else alias.name
+                    if not name.startswith("_"):
+                        names.append(name)
+        return names
+
+    def _extract_all_list(self, node: ast.expr) -> list[str]:
+        """Extract string values from an __all__ assignment.
+
+        Args:
+            node: The value node of the __all__ assignment.
+
+        Returns:
+            List of names from __all__.
+        """
+        names: list[str] = []
+        if isinstance(node, (ast.List, ast.Tuple)):
+            for elt in node.elts:
+                if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                    names.append(elt.value)
+        return names
+
+    def _count_components(self, tree: ast.Module) -> int:
+        """Count top-level classes and functions in a module.
+
+        Args:
+            tree: Parsed AST.
+
+        Returns:
+            Count of top-level class and function definitions.
+        """
+        count = 0
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+                count += 1
+        return count
+
+
+class _ImportVisitor(ast.NodeVisitor):
+    """AST visitor that extracts imports while skipping TYPE_CHECKING blocks.
+
+    Attributes:
+        package_name: Top-level package name (e.g., 'raise_cli').
+        module_name: Current module name (to exclude self-imports).
+        imports: Set of discovered sibling module names.
+    """
+
+    def __init__(self, package_name: str, module_name: str) -> None:
+        self.package_name = package_name
+        self.module_name = module_name
+        self.imports: set[str] = set()
+        self._in_type_checking = False
+
+    def visit_If(self, node: ast.If) -> None:  # noqa: N802
+        """Skip imports inside TYPE_CHECKING blocks."""
+        if self._is_type_checking(node.test):
+            # Don't visit the body — skip TYPE_CHECKING imports
+            for child in node.orelse:
+                self.visit(child)
+        else:
+            self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:  # noqa: N802
+        """Extract module name from 'from X import Y' statements."""
+        if self._in_type_checking:
+            return
+
+        if node.module and node.level == 0:
+            # Absolute import: from pkg.sibling.foo import bar
+            self._resolve_absolute(node.module)
+        elif node.level > 0 and node.module:
+            # Relative import: from ..sibling import bar
+            self._resolve_relative(node.module, node.level)
+        elif node.level > 0 and node.names:
+            # Relative import without module: from .. import sibling
+            for alias in node.names:
+                if node.level >= 2:
+                    # from ..sibling means the name IS the sibling module
+                    imported = alias.name
+                    if imported != self.module_name:
+                        self.imports.add(imported)
+
+    def visit_Import(self, node: ast.Import) -> None:  # noqa: N802
+        """Extract module name from 'import X' statements."""
+        if self._in_type_checking:
+            return
+
+        for alias in node.names:
+            self._resolve_absolute(alias.name)
+
+    def _resolve_absolute(self, module_path: str) -> None:
+        """Resolve an absolute import to a sibling module name."""
+        parts = module_path.split(".")
+        # Must start with our package name
+        if parts[0] != self.package_name:
+            return
+        if len(parts) < 2:
+            return
+        sibling = parts[1]
+        if sibling != self.module_name:
+            self.imports.add(sibling)
+
+    def _resolve_relative(self, module_path: str, level: int) -> None:
+        """Resolve a relative import to a sibling module name."""
+        if level >= 2:
+            # from ..sibling.foo import bar → sibling is the module
+            parts = module_path.split(".")
+            sibling = parts[0]
+            if sibling != self.module_name:
+                self.imports.add(sibling)
+
+    def _is_type_checking(self, test: ast.expr) -> bool:
+        """Check if an if-test is TYPE_CHECKING."""
+        return (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING") or (
+            isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"
+        )