raise-cli 2.2.1__py3-none-any.whl

raise_cli/cli/commands/discover.py

@@ -0,0 +1,551 @@
+"""Discovery CLI commands for codebase scanning and graph integration.
+
+This module provides commands to scan codebases, extract structural
+information, and integrate discovered components into the unified context graph.
+
+Supports Python, TypeScript, JavaScript, PHP, Svelte, and C#.
+
+Example:
+    $ raise discover scan src/
+    $ raise discover scan . --language typescript --output json
+    $ raise discover build --input work/discovery/components-validated.json
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from raise_cli.cli.error_handler import cli_error
+from raise_cli.discovery.scanner import Language, ScanResult, scan_directory
+from raise_cli.hooks.emitter import create_emitter
+from raise_cli.hooks.events import DiscoverScanEvent
+from raise_cli.output.formatters.discover import (
+    format_analyze_result,
+    format_build_result,
+    format_drift_result,
+    format_scan_result,
+)
+
+discover_app = typer.Typer(
+    name="discover",
+    help="Codebase discovery and analysis commands",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+
+@discover_app.command("scan")
+def scan_command(
+    path: Annotated[
+        Path,
+        typer.Argument(
+            help="Directory to scan for source files",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+    ] = Path("."),
+    language: Annotated[
+        str | None,
+        typer.Option(
+            "--language",
+            "-l",
+            help="Language to scan: python, typescript, javascript, php, svelte, csharp (auto-detect if not set)",
+        ),
+    ] = None,
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: human, json, or summary",
+        ),
+    ] = "human",
+    pattern: Annotated[
+        str | None,
+        typer.Option(
+            "--pattern",
+            "-p",
+            help="Glob pattern for files (default: language-specific)",
+        ),
+    ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--exclude",
+            "-e",
+            help="Patterns to exclude (can be repeated)",
+        ),
+    ] = None,
+) -> None:
+    """Scan a directory and extract code symbols.
+
+    Extracts classes, functions, methods, interfaces, and module docstrings
+    from source files. Supports Python, TypeScript, JavaScript, PHP, Svelte, and C#.
+
+    Output can be human-readable table, JSON, or summary statistics.
+
+    Examples:
+        # Scan current directory (auto-detect languages)
+        raise discover scan
+
+        # Scan Python files only
+        raise discover scan src/ --language python
+
+        # Scan TypeScript project
+        raise discover scan ./app --language typescript --output json
+
+        # Auto-detect but exclude tests
+        raise discover scan . --exclude "**/test_*" --exclude "**/__tests__/**"
+    """
+    # Validate language if provided
+    lang: Language | None = None
+    if language:
+        if language not in (
+            "python",
+            "typescript",
+            "javascript",
+            "php",
+            "svelte",
+            "csharp",
+        ):
+            cli_error(
+                f"Unsupported language: {language}",
+                hint="Supported: python, typescript, javascript, php, svelte, csharp",
+                exit_code=7,
+            )
+        lang = language  # type: ignore[assignment]
+
+    # Pass user excludes or None to use DEFAULT_EXCLUDE_PATTERNS from scanner
+    exclude_patterns = exclude if exclude else None
+
+    result = scan_directory(
+        path,
+        language=lang,
+        pattern=pattern,
+        exclude_patterns=exclude_patterns,
+    )
+
+    # Emit discover:scan event
+    emitter = create_emitter()
+    emitter.emit(
+        DiscoverScanEvent(
+            project_path=path,
+            language=lang or "auto",
+            component_count=len(result.symbols),
+        )
+    )
+
+    format_scan_result(result, path, output, language=lang)
+
+
+@discover_app.command("analyze")
+def analyze_command(
+    input_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--input",
+            "-i",
+            help="Path to scan result JSON (reads stdin if not provided)",
+        ),
+    ] = None,
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: human, json, or summary",
+        ),
+    ] = "human",
+    category_map_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--category-map",
+            "-c",
+            help="YAML file with custom path-to-category mappings",
+        ),
+    ] = None,
+) -> None:
+    """Analyze scan results with confidence scoring and module grouping.
+
+    Takes raw scan output (from `raise discover scan --output json`) and
+    produces an analysis with confidence scores, auto-categorization,
+    hierarchical folding, and module grouping for parallel AI synthesis.
+
+    All analysis is deterministic — no AI inference required.
+
+    Examples:
+        # Analyze from file
+        raise discover analyze --input scan-result.json
+
+        # Pipe from scan
+        raise discover scan src/ -l python -o json | raise discover analyze
+
+        # JSON output
+        raise discover analyze --input scan-result.json --output json
+
+        # Summary only
+        raise discover analyze --input scan-result.json --output summary
+    """
+    import sys
+
+    from raise_cli.discovery.analyzer import analyze
+
+    # Load scan result JSON
+    scan_json: str = ""
+    if input_file:
+        if not input_file.exists():
+            cli_error(
+                f"Input file not found: {input_file}",
+                hint="Run 'raise discover scan --output json' first",
+                exit_code=4,
+            )
+        scan_json = input_file.read_text(encoding="utf-8")
+    else:
+        # Read from stdin
+        if sys.stdin.isatty():
+            cli_error(
+                "No input provided",
+                hint="Pipe from scan: raise discover scan -o json | raise discover analyze\n"
+                "Or use --input: raise discover analyze --input scan-result.json",
+                exit_code=7,
+            )
+        scan_json = sys.stdin.read()
+
+    # Parse scan result
+    scan_result = ScanResult(symbols=[], files_scanned=0, errors=[])
+    try:
+        scan_data: dict[str, Any] = json.loads(scan_json)
+        scan_result = ScanResult(
+            symbols=[],
+            files_scanned=scan_data.get("files_scanned", 0),
+            errors=scan_data.get("errors", []),
+        )
+        # Parse symbols from JSON
+        from raise_cli.discovery.scanner import Symbol
+
+        for sym_data in scan_data.get("symbols", []):
+            scan_result.symbols.append(Symbol.model_validate(sym_data))
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        cli_error(
+            f"Invalid scan result JSON: {e}",
+            hint="Input must be JSON from 'raise discover scan --output json'",
+            exit_code=7,
+        )
+
+    # Load custom category map if provided
+    category_map: dict[str, str] | None = None
+    if category_map_file:
+        if not category_map_file.exists():
+            cli_error(
+                f"Category map file not found: {category_map_file}",
+                exit_code=4,
+            )
+        try:
+            import yaml
+
+            category_map = yaml.safe_load(category_map_file.read_text(encoding="utf-8"))
+        except ImportError:
+            cli_error(
+                "PyYAML required for --category-map",
+                hint="Install with: pip install pyyaml",
+                exit_code=6,
+            )
+        except Exception as e:
+            cli_error(f"Error reading category map: {e}", exit_code=7)
+
+    # Run analysis
+    result = analyze(scan_result, category_map=category_map)
+
+    # Save analysis.json
+    output_dir = Path("work/discovery")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_path = output_dir / "analysis.json"
+    output_path.write_text(
+        json.dumps(result.model_dump(), indent=2, default=str),
+        encoding="utf-8",
+    )
+
+    # Format and print
+    format_analyze_result(result, output)
+
+    if output != "json":
+        console.print(f"\n[dim]Saved: {output_path}[/dim]")
+
+
+@discover_app.command("build")
+def build_command(
+    input_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--input",
+            "-i",
+            help="Path to validated components JSON (default: work/discovery/components-validated.json)",
+        ),
+    ] = None,
+    project_root: Annotated[
+        Path,
+        typer.Option(
+            "--project-root",
+            "-r",
+            help="Project root directory (default: current directory)",
+        ),
+    ] = Path("."),
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: human, json, or summary",
+        ),
+    ] = "human",
+) -> None:
+    """Build unified graph with discovered components.
+
+    Reads validated components from JSON and integrates them into the unified
+    context graph. Components become queryable via `raise context query`.
+
+    The graph is rebuilt from all sources (governance, memory, work, skills,
+    and components) and saved to `.raise/graph/unified.json`.
+
+    Examples:
+        # Build with default input file
+        raise discover build
+
+        # Build with custom input
+        raise discover build --input my-components.json
+
+        # Build and show JSON output
+        raise discover build --output json
+    """
+    root = project_root.resolve()
+
+    # Resolve input file path
+    if input_file is None:
+        input_path = root / "work" / "discovery" / "components-validated.json"
+    else:
+        input_path = input_file.resolve()
+
+    # Check input file exists
+    if not input_path.exists():
+        cli_error(
+            f"Components file not found: {input_path}",
+            hint="Run /rai-discover-validate to generate validated components",
+            exit_code=4,
+        )
+
+    # Load components to validate and count
+    component_count = 0
+    try:
+        data: dict[str, Any] = json.loads(input_path.read_text(encoding="utf-8"))
+        components: list[dict[str, Any]] = data.get("components", [])
+        component_count = len(components)
+    except (json.JSONDecodeError, KeyError) as e:
+        cli_error(f"Invalid JSON in {input_path}: {e}")
+
+    if component_count == 0:
+        cli_error(
+            "No components found in input file",
+            hint="Run /rai-discover-validate to validate components first",
+        )
+
+    # Build unified graph (includes components automatically)
+    from raise_cli.context.builder import GraphBuilder
+
+    builder = GraphBuilder(project_root=root)
+    graph = builder.build()
+
+    # Save graph via backend
+    from raise_cli.graph.backends import get_active_backend
+
+    graph_path = root / ".raise" / "graph" / "unified.json"
+    get_active_backend(graph_path).persist(graph)
+
+    # Count component nodes in graph
+    component_nodes = [n for n in graph.iter_concepts() if n.type == "component"]
+    components_in_graph = len(component_nodes)
+
+    # Build categories dict
+    categories: dict[str, int] = {}
+    for comp in component_nodes:
+        category = comp.metadata.get("category", "unknown")
+        categories[category] = categories.get(category, 0) + 1
+
+    # Build sample components list
+    sample_components = [
+        (
+            comp.metadata.get("name", comp.id),
+            comp.metadata.get("kind", ""),
+            comp.content[:60],
+        )
+        for comp in component_nodes[:3]
+    ]
+
+    format_build_result(
+        input_path=input_path,
+        graph_path=graph_path,
+        component_count=component_count,
+        components_in_graph=components_in_graph,
+        node_count=graph.node_count,
+        edge_count=graph.edge_count,
+        categories=categories,
+        sample_components=sample_components,
+        output_format=output,
+    )
+
+
+@discover_app.command("drift")
+def drift_command(
+    path: Annotated[
+        Path | None,
+        typer.Argument(
+            help="Directory to scan for drift (default: src/)",
+        ),
+    ] = None,
+    project_root: Annotated[
+        Path,
+        typer.Option(
+            "--project-root",
+            "-r",
+            help="Project root directory (default: current directory)",
+        ),
+    ] = Path("."),
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: human, json, or summary",
+        ),
+    ] = "human",
+) -> None:
+    """Check for architectural drift against baseline components.
+
+    Compares scanned code against the validated component baseline to
+    identify potential architectural drift (files in wrong locations,
+    naming convention violations, missing documentation).
+
+    Exit codes:
+        0 - No drift detected
+        1 - Drift warnings found
+
+    Examples:
+        # Check entire project
+        raise discover drift
+
+        # Check specific directory
+        raise discover drift src/new_module/
+
+        # Output as JSON
+        raise discover drift --output json
+    """
+    from raise_cli.discovery.drift import BaselineComponent, DriftWarning, detect_drift
+
+    root = project_root.resolve()
+    scan_path = path.resolve() if path else root / "src"
+
+    # Load baseline components
+    baseline_file = root / "work" / "discovery" / "components-validated.json"
+
+    if not baseline_file.exists():
+        if output == "json":
+            console.print_json(
+                json.dumps(
+                    {
+                        "status": "no_baseline",
+                        "warnings": [],
+                        "warning_count": 0,
+                        "message": "No baseline components found",
+                    }
+                )
+            )
+        else:
+            console.print(
+                "[yellow]No baseline components found.[/yellow]\n"
+                "[dim]Run /rai-discover-validate to create a baseline first.[/dim]"
+            )
+        raise typer.Exit(0)
+
+    # Load baseline
+    baseline: list[BaselineComponent] = []
+    try:
+        baseline_data: dict[str, Any] = json.loads(
+            baseline_file.read_text(encoding="utf-8")
+        )
+        baseline_dicts: list[dict[str, Any]] = baseline_data.get("components", [])
+        baseline = [BaselineComponent.model_validate(comp) for comp in baseline_dicts]
+    except (json.JSONDecodeError, KeyError) as e:
+        cli_error(f"Error reading baseline: {e}")
+
+    if not baseline:
+        if output == "json":
+            console.print_json(
+                json.dumps(
+                    {
+                        "status": "empty_baseline",
+                        "warnings": [],
+                        "warning_count": 0,
+                        "message": "Baseline has no components",
+                    }
+                )
+            )
+        else:
+            console.print(
+                "[yellow]Baseline has no components.[/yellow]\n"
+                "[dim]Run /rai-discover-validate to add components.[/dim]"
+            )
+        raise typer.Exit(0)
+
+    # Warn if baseline is too small for meaningful drift detection
+    min_baseline_size = 10
+    if len(baseline) < min_baseline_size and output == "human":
+        console.print(
+            f"[yellow]Note: Baseline has only {len(baseline)} component(s).[/yellow]\n"
+            f"[dim]Drift detection works best with {min_baseline_size}+ components "
+            "for meaningful patterns.[/dim]\n"
+            "[dim]Run /rai-discover-scan and /rai-discover-validate to expand the baseline.[/dim]\n"
+        )
+
+    # Scan for new symbols
+    if not scan_path.exists():
+        if output == "json":
+            console.print_json(
+                json.dumps(
+                    {
+                        "status": "no_source",
+                        "warnings": [],
+                        "warning_count": 0,
+                        "message": f"Scan path not found: {scan_path}",
+                    }
+                )
+            )
+        else:
+            console.print(f"[yellow]Scan path not found: {scan_path}[/yellow]")
+        raise typer.Exit(0)
+
+    scan_result = scan_directory(scan_path)
+
+    # Detect drift
+    warnings: list[DriftWarning] = detect_drift(
+        baseline=baseline,
+        scanned=scan_result.symbols,
+    )
+
+    # Output results
+    format_drift_result(
+        warnings=warnings,
+        files_scanned=scan_result.files_scanned,
+        symbols_checked=len(scan_result.symbols),
+        output_format=output,
+    )
+
+    # Exit with 1 if warnings found
+    if warnings:
+        raise typer.Exit(1)

raise_cli/cli/commands/docs.py

@@ -0,0 +1,130 @@
+"""CLI commands for governance documentation via DocumentationTarget.
+
+Provides the ``rai docs`` command group. All commands delegate to a
+DocumentationTarget discovered via entry points. The target is resolved
+automatically when exactly one is registered, or selected explicitly
+via ``--target NAME``.
+
+CLI owns domain logic (artifact type → local path convention).
+Adapter owns platform config (space mapping, parent pages).
+
+Architecture: E301 (Agent Tool Abstraction), ADR-034 (Governance)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from raise_cli.cli.commands._resolve import resolve_docs_target
+
+docs_app = typer.Typer(
+    name="docs",
+    help="Manage governance documentation via DocumentationTarget",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+# Common option for target override (D5)
+TargetOption = Annotated[
+    str | None,
+    typer.Option(
+        "--target", "-t", help="Target name override (auto-detect if omitted)"
+    ),
+]
+
+# Convention: governance artifacts live at governance/{type}.md
+GOVERNANCE_DIR = "governance"
+
+
+def _resolve_artifact_path(artifact_type: str) -> Path:
+    """Resolve artifact type to local file path by convention.
+
+    Convention: ``governance/{artifact_type}.md``
+
+    Args:
+        artifact_type: Governance artifact type (e.g., "roadmap", "adr").
+
+    Returns:
+        Path to the governance file.
+
+    Raises:
+        typer.Exit: If the file does not exist.
+    """
+    path = Path(GOVERNANCE_DIR) / f"{artifact_type}.md"
+    if not path.exists():
+        console.print(f"[red]Error:[/red] File not found: {path}")
+        raise typer.Exit(1)
+    return path
+
+
+@docs_app.command()
+def publish(
+    artifact_type: Annotated[
+        str, typer.Argument(help="Governance artifact type (e.g., roadmap, adr)")
+    ],
+    title: Annotated[
+        str | None, typer.Option("--title", help="Page title (default: artifact type)")
+    ] = None,
+    target: TargetOption = None,
+) -> None:
+    """Publish a governance artifact to a documentation target."""
+    path = _resolve_artifact_path(artifact_type)
+    content = path.read_text(encoding="utf-8")
+    doc_target = resolve_docs_target(target)
+
+    page_title = title or artifact_type
+    metadata = {"title": page_title, "path": str(path)}
+
+    result = doc_target.publish(
+        doc_type=artifact_type, content=content, metadata=metadata
+    )
+    if result.success:
+        console.print(f"Published: {artifact_type} → {result.url}")
+    else:
+        console.print(f"[red]Error:[/red] {result.message}")
+        raise typer.Exit(1)
+
+
+@docs_app.command()
+def get(
+    identifier: Annotated[str, typer.Argument(help="Page ID on the remote target")],
+    target: TargetOption = None,
+) -> None:
+    """Retrieve a page from the documentation target."""
+    doc_target = resolve_docs_target(target)
+    page = doc_target.get_page(identifier)
+    # Compact header + content
+    header_parts = [f"# {page.title}"]
+    if page.space_key:
+        header_parts.append(f"Space: {page.space_key}")
+    if page.version > 1:
+        header_parts.append(f"Version: {page.version}")
+    if page.url:
+        header_parts.append(page.url)
+
+    console.print(header_parts[0])
+    if len(header_parts) > 1:
+        console.print(" | ".join(header_parts[1:]))
+    console.print()
+    console.print(page.content)
+
+
+@docs_app.command()
+def search(
+    query: Annotated[str, typer.Argument(help="Search query")],
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Max results")] = 10,
+    target: TargetOption = None,
+) -> None:
+    """Search documentation pages on the remote target."""
+    doc_target = resolve_docs_target(target)
+    results = doc_target.search(query, limit=limit)
+    if not results:
+        console.print("No results.")
+        return
+    for page in results:
+        console.print(f"{page.id:<8} {page.space_key:<8} {page.title}")