raise-cli 2.2.1__py3-none-any.whl

raise_cli/context/diff.py

@@ -0,0 +1,213 @@
+"""Graph diff engine for detecting changes between unified graph builds.
+
+Compares two Graph instances by node presence and semantic fields
+(content, type, metadata). Produces a structured GraphDiff with impact
+classification and affected module list.
+
+Architecture: E16 Incremental Coherence — Layer 1 (deterministic)
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from raise_core.graph.engine import Graph
+from raise_core.graph.models import GraphNode, NodeType
+
+# Node types that indicate module-level impact
+_MODULE_IMPACT_TYPES: frozenset[NodeType] = frozenset({"module", "component"})
+
+# Node types that indicate architectural impact
+_ARCHITECTURAL_IMPACT_TYPES: frozenset[NodeType] = frozenset(
+    {"bounded_context", "layer"}
+)
+
+# Fields compared for modification detection
+_COMPARED_FIELDS: tuple[str, ...] = ("content", "type", "metadata")
+
+
+class NodeChange(BaseModel):
+    """A change to a single node between two graph builds.
+
+    Attributes:
+        node_id: The unique node identifier.
+        change_type: Whether the node was added, removed, or modified.
+        old_value: The node in the old graph (None for added).
+        new_value: The node in the new graph (None for removed).
+        changed_fields: Which semantic fields changed (for modified nodes).
+    """
+
+    node_id: str
+    change_type: Literal["added", "removed", "modified"]
+    old_value: GraphNode | None = None
+    new_value: GraphNode | None = None
+    changed_fields: list[str] = Field(default_factory=list)
+
+
+class GraphDiff(BaseModel):
+    """Structured diff between two unified graph builds.
+
+    Attributes:
+        node_changes: List of individual node changes.
+        impact: Overall impact level for downstream consumers.
+        affected_modules: Module node IDs that changed (sorted).
+        summary: Deterministic human-readable summary string.
+    """
+
+    node_changes: list[NodeChange] = Field(default_factory=lambda: [])
+    impact: Literal["none", "module", "architectural"] = "none"
+    affected_modules: list[str] = Field(default_factory=lambda: [])
+    summary: str = "no changes"
+
+
+def diff_graphs(old: Graph, new: Graph) -> GraphDiff:
+    """Compare two unified graphs and return structured diff.
+
+    Compares nodes by presence (added/removed) and by semantic fields
+    (content, type, metadata) for modification detection. Ignores
+    created and source_file fields.
+
+    Args:
+        old: The previous graph (before build).
+        new: The current graph (after build).
+
+    Returns:
+        GraphDiff with node changes, impact classification, and affected modules.
+    """
+    old_ids = {node.id for node in old.iter_concepts()}
+    new_ids = {node.id for node in new.iter_concepts()}
+
+    changes: list[NodeChange] = []
+
+    # Added nodes
+    for node_id in sorted(new_ids - old_ids):
+        node = new.get_concept(node_id)
+        changes.append(
+            NodeChange(
+                node_id=node_id,
+                change_type="added",
+                old_value=None,
+                new_value=node,
+                changed_fields=[],
+            )
+        )
+
+    # Removed nodes
+    for node_id in sorted(old_ids - new_ids):
+        node = old.get_concept(node_id)
+        changes.append(
+            NodeChange(
+                node_id=node_id,
+                change_type="removed",
+                old_value=node,
+                new_value=None,
+                changed_fields=[],
+            )
+        )
+
+    # Modified nodes
+    for node_id in sorted(old_ids & new_ids):
+        old_node = old.get_concept(node_id)
+        new_node = new.get_concept(node_id)
+        if old_node is None or new_node is None:
+            continue
+
+        changed_fields = _compare_nodes(old_node, new_node)
+        if changed_fields:
+            changes.append(
+                NodeChange(
+                    node_id=node_id,
+                    change_type="modified",
+                    old_value=old_node,
+                    new_value=new_node,
+                    changed_fields=changed_fields,
+                )
+            )
+
+    if not changes:
+        return GraphDiff()
+
+    impact = _classify_impact(changes)
+    affected_modules = _derive_affected_modules(changes)
+    summary = _build_summary(changes, affected_modules)
+
+    return GraphDiff(
+        node_changes=changes,
+        impact=impact,
+        affected_modules=affected_modules,
+        summary=summary,
+    )
+
+
+def _compare_nodes(old: GraphNode, new: GraphNode) -> list[str]:
+    """Compare two nodes on semantic fields only.
+
+    Returns list of field names that differ. Ignores created and source_file.
+    """
+    changed: list[str] = []
+    for field in _COMPARED_FIELDS:
+        old_val = getattr(old, field)
+        new_val = getattr(new, field)
+        if old_val != new_val:
+            changed.append(field)
+    return changed
+
+
+def _classify_impact(
+    changes: list[NodeChange],
+) -> Literal["none", "module", "architectural"]:
+    """Classify overall impact from node changes.
+
+    architectural > module > none.
+    """
+    has_module = False
+
+    for change in changes:
+        node = change.new_value or change.old_value
+        if node is None:
+            continue
+        if node.type in _ARCHITECTURAL_IMPACT_TYPES:
+            return "architectural"
+        if node.type in _MODULE_IMPACT_TYPES:
+            has_module = True
+
+    return "module" if has_module else "none"
+
+
+def _derive_affected_modules(changes: list[NodeChange]) -> list[str]:
+    """Extract sorted list of module IDs from changed nodes."""
+    modules: list[str] = []
+    for change in changes:
+        node = change.new_value or change.old_value
+        if node is not None and node.type == "module":
+            modules.append(change.node_id)
+    return sorted(modules)
+
+
+def _build_summary(changes: list[NodeChange], affected_modules: list[str]) -> str:
+    """Build deterministic summary string from changes."""
+    added = sum(1 for c in changes if c.change_type == "added")
+    removed = sum(1 for c in changes if c.change_type == "removed")
+    modified = sum(1 for c in changes if c.change_type == "modified")
+
+    total = len(changes)
+    parts: list[str] = []
+    if added:
+        parts.append(f"{added} added")
+    if removed:
+        parts.append(f"{removed} removed")
+    if modified:
+        parts.append(f"{modified} modified")
+
+    detail = ", ".join(parts)
+    summary = f"{total} nodes changed ({detail})"
+
+    if affected_modules:
+        mod_list = ", ".join(affected_modules)
+        count = len(affected_modules)
+        label = "module" if count == 1 else "modules"
+        summary += f", {count} {label} affected ({mod_list})"
+
+    return summary

raise_cli/context/extractors/__init__.py

@@ -0,0 +1,13 @@
+"""Context extractors for unified graph building."""
+
+from __future__ import annotations
+
+from raise_cli.context.extractors.skills import (
+    extract_all_skills,
+    extract_skill_metadata,
+)
+
+__all__ = [
+    "extract_all_skills",
+    "extract_skill_metadata",
+]

raise_cli/context/extractors/skills.py

@@ -0,0 +1,121 @@
+"""Skill metadata extraction from SKILL.md frontmatter.
+
+This module extracts skill metadata from YAML frontmatter in SKILL.md files
+and converts them to GraphNode for the unified context graph.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from raise_core.graph.models import GraphNode
+
+# Regex to match YAML frontmatter between --- markers
+FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+
+
+def extract_skill_metadata(skill_path: Path) -> GraphNode | None:
+    """Extract metadata from SKILL.md YAML frontmatter.
+
+    Args:
+        skill_path: Path to SKILL.md file.
+
+    Returns:
+        GraphNode for the skill, or None if parsing fails or file doesn't exist.
+
+    Examples:
+        >>> node = extract_skill_metadata(Path(".claude/skills/rai-story-plan/SKILL.md"))
+        >>> node.id if node else None
+        '/rai-story-plan'
+    """
+    if not skill_path.exists():
+        return None
+
+    try:
+        content = skill_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    # Extract YAML frontmatter
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        return None
+
+    try:
+        frontmatter = yaml.safe_load(match.group(1))
+    except yaml.YAMLError:
+        return None
+
+    if not isinstance(frontmatter, dict):
+        return None
+
+    # Cast to typed dict for pyright
+    fm: dict[str, Any] = cast(dict[str, Any], frontmatter)
+
+    # Name is required
+    name_value = fm.get("name")
+    if not name_value:
+        return None
+    name: str = str(name_value)
+
+    # Extract fields
+    desc_value = fm.get("description", "")
+    description: str = ""
+    if isinstance(desc_value, str):
+        # Clean up multiline YAML strings
+        description = " ".join(desc_value.split())
+
+    meta_value = fm.get("metadata", {})
+    metadata_section: dict[str, Any] = {}
+    if isinstance(meta_value, dict):
+        metadata_section = cast(dict[str, Any], meta_value)
+
+    # Get file modification time for created timestamp
+    try:
+        mtime = skill_path.stat().st_mtime
+        created = datetime.fromtimestamp(mtime, tz=UTC).isoformat()
+    except OSError:
+        created = datetime.now(tz=UTC).isoformat()
+
+    return GraphNode(
+        id=f"/{name}",
+        type="skill",
+        content=description,
+        source_file=str(skill_path),
+        created=created,
+        metadata=metadata_section,
+    )
+
+
+def extract_all_skills(skills_dir: Path) -> list[GraphNode]:
+    """Extract metadata from all skills in a directory.
+
+    Searches for SKILL.md files in subdirectories of the given path.
+
+    Args:
+        skills_dir: Path to skills directory (e.g., .claude/skills/).
+
+    Returns:
+        List of GraphNode for each valid skill found.
+
+    Examples:
+        >>> nodes = extract_all_skills(Path(".claude/skills"))
+        >>> len(nodes) > 0
+        True
+    """
+    if not skills_dir.exists():
+        return []
+
+    nodes: list[GraphNode] = []
+
+    for skill_md in skills_dir.glob("*/SKILL.md"):
+        node = extract_skill_metadata(skill_md)
+        if node is not None:
+            nodes.append(node)
+
+    return nodes

raise_cli/core/__init__.py

@@ -0,0 +1,37 @@
+"""Core utilities for raise-cli.
+
+This package provides:
+- tools: Subprocess wrappers for git, ast-grep, ripgrep
+"""
+
+from __future__ import annotations
+
+from raise_cli.core.tools import (
+    GitStatus,
+    SearchMatch,
+    ToolResult,
+    check_tool,
+    git_branch,
+    git_diff,
+    git_root,
+    git_status,
+    require_tool,
+    rg_search,
+    run_tool,
+    sg_search,
+)
+
+__all__ = [
+    "ToolResult",
+    "GitStatus",
+    "SearchMatch",
+    "check_tool",
+    "require_tool",
+    "run_tool",
+    "git_root",
+    "git_branch",
+    "git_status",
+    "git_diff",
+    "rg_search",
+    "sg_search",
+]

raise_cli/core/files.py

@@ -0,0 +1,66 @@
+"""File and directory utilities.
+
+Shared functions for file system operations used across the codebase.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Directories to exclude from scanning operations
+EXCLUDED_DIRS: frozenset[str] = frozenset(
+    {
+        # Version control
+        ".git",
+        ".svn",
+        ".hg",
+        # Package managers
+        "node_modules",
+        # Python
+        "__pycache__",
+        ".tox",
+        ".nox",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "venv",
+        ".venv",
+        "env",
+        ".env",
+        # Build outputs
+        "dist",
+        "build",
+        "target",
+        # IDE
+        ".idea",
+        ".vscode",
+    }
+)
+
+
+def should_exclude_dir(dir_path: Path) -> bool:
+    """Check if a directory should be excluded from scanning.
+
+    Excludes hidden directories (starting with .) and known non-project
+    directories like node_modules, __pycache__, etc.
+
+    Args:
+        dir_path: Path to check.
+
+    Returns:
+        True if the directory should be excluded.
+
+    Examples:
+        >>> should_exclude_dir(Path("node_modules"))
+        True
+        >>> should_exclude_dir(Path(".git"))
+        True
+        >>> should_exclude_dir(Path("src"))
+        False
+    """
+    name = dir_path.name
+    # Exclude hidden directories (starting with .)
+    if name.startswith("."):
+        return True
+    # Exclude known non-project directories
+    return name in EXCLUDED_DIRS

raise_cli/core/text.py

@@ -0,0 +1,174 @@
+"""Text processing utilities.
+
+Shared functions for text manipulation used across the codebase.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Comprehensive English stopwords for keyword extraction
+STOPWORDS: frozenset[str] = frozenset(
+    {
+        # Articles
+        "the",
+        "a",
+        "an",
+        # Conjunctions
+        "and",
+        "but",
+        "or",
+        "nor",
+        "so",
+        "yet",
+        "both",
+        "either",
+        "neither",
+        # Prepositions
+        "in",
+        "on",
+        "at",
+        "to",
+        "for",
+        "of",
+        "with",
+        "from",
+        "by",
+        "as",
+        "into",
+        "through",
+        "during",
+        "before",
+        "after",
+        "above",
+        "below",
+        "between",
+        "under",
+        # Demonstratives and pronouns
+        "this",
+        "that",
+        "these",
+        "those",
+        "it",
+        "its",
+        # Be verbs
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        # Have verbs
+        "have",
+        "has",
+        "had",
+        # Do verbs
+        "do",
+        "does",
+        "did",
+        # Modal verbs
+        "will",
+        "would",
+        "could",
+        "should",
+        "may",
+        "might",
+        "must",
+        "shall",
+        "can",
+        "need",
+        "dare",
+        "ought",
+        "used",
+        # Adverbs
+        "again",
+        "further",
+        "then",
+        "once",
+        "not",
+        "only",
+        "own",
+        "same",
+        "than",
+        "too",
+        "very",
+        "just",
+        "also",
+        "now",
+        "here",
+        "there",
+        "when",
+        "where",
+        "why",
+        "how",
+        # Quantifiers
+        "all",
+        "each",
+        "every",
+        "few",
+        "more",
+        "most",
+        "other",
+        "some",
+        "such",
+        "no",
+        "any",
+    }
+)
+
+
+def extract_keywords(text: str) -> set[str]:
+    """Extract meaningful keywords from text.
+
+    Filters out stopwords and keeps only words longer than 3 characters.
+
+    Args:
+        text: Text to extract keywords from.
+
+    Returns:
+        Set of lowercase keywords.
+
+    Examples:
+        >>> keywords = extract_keywords("The system MUST validate inputs")
+        >>> "system" in keywords
+        True
+        >>> "the" in keywords
+        False
+    """
+    words = re.findall(r"\b\w+\b", text.lower())
+    return {w for w in words if len(w) > 3 and w not in STOPWORDS}
+
+
+def sanitize_id(name: str) -> str:
+    """Sanitize a name for use as an ID.
+
+    Converts a human-readable name to a lowercase, hyphen-separated
+    identifier suitable for use in IDs and keys.
+
+    Args:
+        name: Human-readable name to sanitize.
+
+    Returns:
+        Sanitized ID string (lowercase, hyphens, alphanumeric only).
+
+    Examples:
+        >>> sanitize_id("Context Generation (MVC)")
+        'context-generation-mvc'
+        >>> sanitize_id("Governance as Code")
+        'governance-as-code'
+        >>> sanitize_id("Hello, World!")
+        'hello-world'
+    """
+    # Convert to lowercase
+    sanitized = name.lower()
+    # Replace spaces with hyphens
+    sanitized = sanitized.replace(" ", "-")
+    # Remove all non-alphanumeric characters except hyphens
+    sanitized = re.sub(r"[^a-z0-9-]", "", sanitized)
+    # Collapse multiple hyphens into one
+    sanitized = re.sub(r"-+", "-", sanitized)
+    # Remove leading/trailing hyphens
+    sanitized = sanitized.strip("-")
+
+    return sanitized