codexa 0.4.0__py3-none-any.whl

semantic_code_intelligence/cli/commands/summary_cmd.py

@@ -0,0 +1,78 @@
+"""CLI command: summary — generate structured repository summary."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from semantic_code_intelligence.analysis.ai_features import summarize_repository
+from semantic_code_intelligence.config.settings import load_config
+from semantic_code_intelligence.context.engine import ContextBuilder
+from semantic_code_intelligence.indexing.scanner import scan_repository
+from semantic_code_intelligence.utils.logging import (
+    console,
+    get_logger,
+    print_error,
+    print_info,
+    print_success,
+)
+
+logger = get_logger("cli.summary")
+
+
+@click.command("summary")
+@click.option(
+    "--path",
+    "-p",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Project root path.",
+)
+@click.option(
+    "--json-output",
+    "--json",
+    "json_mode",
+    is_flag=True,
+    default=False,
+    help="Output in JSON format.",
+)
+@click.pass_context
+def summary_cmd(ctx: click.Context, path: str, json_mode: bool) -> None:
+    """Generate a structured summary of the repository.
+
+    Shows language breakdown, symbol counts, and top functions/classes.
+
+    Examples:
+
+        codexa summary
+
+        codexa summary --json
+
+        codexa summary -p /path/to/project
+    """
+    root = Path(path).resolve()
+    config = load_config(root)
+    scanned = scan_repository(root, config.index)
+
+    if not scanned:
+        print_error("No source files found in the project.")
+        return
+
+    if not json_mode:
+        print_info(f"Analyzing {len(scanned)} files...")
+    builder = ContextBuilder()
+    for sf in scanned:
+        full_path = str(root / sf.relative_path)
+        try:
+            builder.index_file(full_path)
+        except Exception:
+            logger.debug("Could not parse %s", sf.relative_path)
+
+    summary = summarize_repository(builder)
+
+    if json_mode:
+        click.echo(summary.to_json())
+    else:
+        console.print(summary.render(), markup=False)
+        print_success(f"Summary generated for {summary.total_files} files.")

semantic_code_intelligence/cli/commands/tool_cmd.py

@@ -0,0 +1,282 @@
+"""CLI command: tool — invoke and manage AI agent tools."""
+
+from __future__ import annotations
+
+import json as json_mod
+from pathlib import Path
+
+import click
+
+from semantic_code_intelligence.utils.logging import (
+    console,
+    get_logger,
+    print_error,
+    print_header,
+    print_separator,
+    print_success,
+    print_warning,
+)
+
+logger = get_logger("cli.tool")
+
+
+@click.group("tool")
+def tool_cmd() -> None:
+    """AI Agent Tooling Protocol — invoke and inspect tools.
+
+    Provides a CLI interface to the same tool execution engine that
+    AI coding agents use over the Bridge HTTP API.
+
+    Examples:
+
+        codexa tool list
+        codexa tool run semantic_search --arg query="parse file"
+        codexa tool schema semantic_search
+    """
+
+
+@tool_cmd.command("list")
+@click.option(
+    "--json-output", "--json", "json_mode",
+    is_flag=True, default=False,
+    help="Output in JSON format.",
+)
+def tool_list(json_mode: bool) -> None:
+    """List all available tools with their descriptions."""
+    from semantic_code_intelligence.tools import TOOL_DEFINITIONS
+    from semantic_code_intelligence.tools.executor import ToolExecutor
+
+    from rich.table import Table
+
+    executor = ToolExecutor(Path(".").resolve())
+    tools = executor.available_tools
+
+    if json_mode:
+        click.echo(json_mod.dumps({"tools": tools, "count": len(tools)}, indent=2))
+        return
+
+    print_header("Available Tools", f"{len(tools)} registered")
+    table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 2))
+    table.add_column("Tool", style="bold")
+    table.add_column("Source", style="dim")
+    table.add_column("Parameters", style="yellow")
+    table.add_column("Description")
+
+    for t in tools:
+        source = t.get("source", "built-in")
+        params = t.get("parameters", {})
+        param_names = ", ".join(params.keys()) if params else "-"
+        desc = t.get("description", "No description")
+        if len(desc) > 60:
+            desc = desc[:57] + "..."
+        table.add_row(t["name"], source, param_names, desc)
+
+    console.print(table)
+    print_separator()
+
+
+@tool_cmd.command("run")
+@click.argument("tool_name")
+@click.option(
+    "--arg", "-a",
+    multiple=True,
+    help="Tool argument as key=value (repeatable).",
+)
+@click.option(
+    "--path", "-p",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Project root path.",
+)
+@click.option(
+    "--json-output", "--json", "json_mode",
+    is_flag=True, default=False,
+    help="Output in JSON format.",
+)
+@click.option(
+    "--pipe",
+    is_flag=True, default=False,
+    help="Plain text output for piping / CI.",
+)
+@click.pass_context
+def tool_run(
+    ctx: click.Context,
+    tool_name: str,
+    arg: tuple[str, ...],
+    path: str,
+    json_mode: bool,
+    pipe: bool,
+) -> None:
+    """Run TOOL_NAME with the given arguments.
+
+    Arguments are passed as --arg key=value pairs.
+
+    Examples:
+
+        codexa tool run semantic_search --arg query="parse file"
+        codexa tool run explain_symbol --arg symbol_name=ToolRegistry
+        codexa tool run summarize_repo --json
+    """
+    from semantic_code_intelligence.tools.executor import ToolExecutor
+    from semantic_code_intelligence.tools.protocol import ToolInvocation
+
+    project_root = Path(path).resolve()
+
+    # Parse arguments
+    arguments: dict[str, str] = {}
+    for a in arg:
+        if "=" not in a:
+            print_error(f"Invalid argument format: {a!r} (expected key=value)")
+            ctx.exit(1)
+            return
+        key, value = a.split("=", 1)
+        arguments[key.strip()] = value.strip()
+
+    executor = ToolExecutor(project_root)
+    invocation = ToolInvocation(tool_name=tool_name, arguments=arguments)
+
+    if not (json_mode or pipe):
+        print_separator(f"Running: {tool_name}")
+
+    result = executor.execute(invocation)
+
+    if json_mode or pipe:
+        click.echo(result.to_json(indent=2 if json_mode else None))
+        return
+
+    if result.success:
+        print_success(f"Tool '{tool_name}' completed in {result.execution_time_ms:.1f}ms")
+        print_separator()
+        payload = result.result_payload
+        if payload:
+            _render_tool_result(tool_name, payload)
+    else:
+        print_error(f"Tool '{tool_name}' failed")
+        if result.error:
+            console.print(f"  [red]Error code:[/red] {result.error.error_code}")
+            console.print(f"  [red]Message:[/red] {result.error.error_message}")
+        print_separator()
+
+
+def _render_tool_result(tool_name: str, payload: dict) -> None:
+    """Render a tool result payload with rich formatting."""
+    from rich.panel import Panel
+    from rich.syntax import Syntax
+    from rich.table import Table
+
+    # explanation results (explain_symbol, explain_file, get_context)
+    if "explanation" in payload:
+        console.print(Panel(payload["explanation"], title="Explanation", border_style="cyan"))
+        if payload.get("code_snippet"):
+            lang = payload.get("language", "python")
+            console.print(Syntax(payload["code_snippet"], lang, theme="monokai", line_numbers=True))
+        return
+
+    # search results
+    if "results" in payload and isinstance(payload["results"], list):
+        results = payload["results"]
+        console.print(f"  [bold]{len(results)} result(s)[/bold]\n")
+        for i, r in enumerate(results[:20], 1):
+            score = r.get("score", r.get("similarity", 0))
+            path = r.get("file_path", r.get("path", "?"))
+            console.print(f"  [cyan]{i}.[/cyan] [bold]{path}[/bold]  [dim](score: {score:.3f})[/dim]")
+            snippet = r.get("content", r.get("snippet", ""))
+            if snippet:
+                preview = snippet.strip()[:120].replace("\n", " ")
+                console.print(f"     [dim]{preview}[/dim]")
+        return
+
+    # call graph
+    if "call_graph" in payload or "callers" in payload or "callees" in payload:
+        if payload.get("callers"):
+            console.print("  [bold]Callers:[/bold]")
+            for c in payload["callers"]:
+                console.print(f"    [green]←[/green] {c}")
+        if payload.get("callees"):
+            console.print("  [bold]Callees:[/bold]")
+            for c in payload["callees"]:
+                console.print(f"    [magenta]→[/magenta] {c}")
+        return
+
+    # references
+    if "references" in payload:
+        refs = payload["references"]
+        console.print(f"  [bold]{len(refs)} reference(s)[/bold]\n")
+        for ref in refs[:30]:
+            path = ref.get("file_path", ref.get("path", "?"))
+            line = ref.get("line", "?")
+            console.print(f"    [cyan]{path}[/cyan]:[yellow]{line}[/yellow]")
+        return
+
+    # dependencies
+    if "dependencies" in payload or "imports" in payload:
+        deps = payload.get("dependencies", payload.get("imports", []))
+        console.print(f"  [bold]{len(deps)} dependenc(ies)[/bold]\n")
+        for d in deps:
+            if isinstance(d, str):
+                console.print(f"    [dim]→[/dim] {d}")
+            elif isinstance(d, dict):
+                console.print(f"    [dim]→[/dim] {d.get('name', d.get('module', str(d)))}")
+        return
+
+    # summary
+    if "summary" in payload:
+        console.print(Panel(payload["summary"], title="Summary", border_style="green"))
+        return
+
+    # fallback: pretty-print JSON
+    console.print(Syntax(json_mod.dumps(payload, indent=2), "json", theme="monokai"))
+
+
+@tool_cmd.command("schema")
+@click.argument("tool_name")
+@click.option(
+    "--json-output", "--json", "json_mode",
+    is_flag=True, default=False,
+    help="Output in JSON format.",
+)
+def tool_schema(tool_name: str, json_mode: bool) -> None:
+    """Show the schema definition for TOOL_NAME.
+
+    Examples:
+
+        codexa tool schema semantic_search
+        codexa tool schema explain_symbol --json
+    """
+    from semantic_code_intelligence.tools.executor import ToolExecutor
+
+    executor = ToolExecutor(Path(".").resolve())
+    schema = executor.get_tool_schema(tool_name)
+
+    if schema is None:
+        print_error(f"Unknown tool: {tool_name}")
+        available = [t["name"] for t in ToolExecutor(Path(".").resolve()).available_tools]
+        if available:
+            print_warning(f"Available tools: {', '.join(available)}")
+        return
+
+    if json_mode:
+        click.echo(json_mod.dumps(schema, indent=2))
+        return
+
+    from rich.table import Table
+
+    print_header(schema["name"], schema.get("description", ""))
+    params = schema.get("parameters", {})
+    if params:
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Parameter", style="cyan")
+        table.add_column("Type", style="yellow")
+        table.add_column("Required", style="red")
+        table.add_column("Default", style="dim")
+        table.add_column("Description")
+        for pname, pdef in params.items():
+            req = "yes" if pdef.get("required") else ""
+            ptype = pdef.get("type", "any")
+            desc = pdef.get("description", "")
+            default = str(pdef["default"]) if "default" in pdef and pdef["default"] is not None else ""
+            table.add_row(pname, ptype, req, default, desc)
+        console.print(table)
+    else:
+        console.print("  [dim]No parameters[/dim]")
+    print_separator()

semantic_code_intelligence/cli/commands/trace_cmd.py

@@ -0,0 +1,123 @@
+"""CLI command: trace — trace execution relationships of a symbol."""
+
+from __future__ import annotations
+
+import json as json_mod
+from pathlib import Path
+
+import click
+
+from semantic_code_intelligence.utils.logging import (
+    console,
+    get_logger,
+    print_error,
+    print_success,
+)
+
+logger = get_logger("cli.trace")
+
+
+@click.command("trace")
+@click.argument("symbol")
+@click.option(
+    "--path", "-p",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Project root path.",
+)
+@click.option(
+    "--json-output", "--json", "json_mode",
+    is_flag=True, default=False,
+    help="Output in JSON format.",
+)
+@click.option(
+    "--pipe",
+    is_flag=True, default=False,
+    help="Plain text output for piping / CI.",
+)
+@click.option(
+    "--max-depth", "-d",
+    type=int, default=5,
+    help="Maximum traversal depth (default: 5).",
+)
+@click.pass_context
+def trace_cmd(
+    ctx: click.Context,
+    symbol: str,
+    path: str,
+    json_mode: bool,
+    pipe: bool,
+    max_depth: int,
+) -> None:
+    """Trace execution relationships for SYMBOL.
+
+    Shows upstream callers and downstream callees to map the flow of
+    execution through the codebase.
+
+    Examples:
+
+        codexa trace parse_file
+
+        codexa trace MyClass.process --json
+
+        codexa trace build_context --max-depth 3 --pipe
+    """
+    from semantic_code_intelligence.ci.trace import trace_symbol
+    from semantic_code_intelligence.context.engine import CallGraph, ContextBuilder
+
+    root = Path(path).resolve()
+    builder = ContextBuilder()
+
+    py_files = sorted(root.rglob("*.py"))
+    py_files = [f for f in py_files if ".venv" not in f.parts and "__pycache__" not in f.parts]
+
+    for fp in py_files:
+        try:
+            content = fp.read_text(encoding="utf-8", errors="replace")
+            builder.index_file(str(fp), content)
+        except Exception:
+            logger.debug("Failed to index %s", fp)
+            continue
+
+    symbols = builder.get_all_symbols()
+    call_graph = CallGraph()
+    call_graph.build(symbols)
+    call_graph.build(symbols)
+
+    result = trace_symbol(symbol, symbols, call_graph, max_depth=max_depth)
+
+    if not result.target_file:
+        if json_mode:
+            click.echo(json_mod.dumps({"error": f"Symbol '{symbol}' not found"}, indent=2))
+        elif pipe:
+            click.echo(f"ERROR symbol_not_found {symbol}")
+        else:
+            print_error(f"Symbol '{symbol}' not found in the project.")
+        return
+
+    if json_mode:
+        click.echo(json_mod.dumps(result.to_dict(), indent=2))
+    elif pipe:
+        click.echo(f"target={result.target} file={result.target_file} up={len(result.upstream)} down={len(result.downstream)}")
+        for n in result.upstream:
+            click.echo(f"  UP    depth={n.depth}  {n.kind:<10}  {n.file_path}:{n.name}")
+        for n in result.downstream:
+            click.echo(f"  DOWN  depth={n.depth}  {n.kind:<10}  {n.file_path}:{n.name}")
+    else:
+        console.print(f"\n[bold]Symbol Trace[/bold] — [cyan]{result.target}[/cyan]  ({result.target_file})\n")
+        if not result.upstream and not result.downstream:
+            print_success("No execution relationships found.")
+            return
+
+        if result.upstream:
+            console.print(f"[bold]Upstream callers[/bold] (max depth {result.max_upstream_depth}):")
+            for n in result.upstream:
+                console.print(f"  [yellow]{n.name}[/yellow]  depth={n.depth}  ({n.kind})  [dim]{n.file_path}[/dim]")
+
+        if result.downstream:
+            console.print(f"\n[bold]Downstream callees[/bold] (max depth {result.max_downstream_depth}):")
+            for n in result.downstream:
+                console.print(f"  [green]{n.name}[/green]  depth={n.depth}  ({n.kind})  [dim]{n.file_path}[/dim]")
+
+        console.print(f"\n[bold]Edges:[/bold] {len(result.edges)}  |  [bold]Total nodes:[/bold] {result.total_nodes}")
+        console.print()

semantic_code_intelligence/cli/commands/tui_cmd.py

@@ -0,0 +1,58 @@
+"""CLI command: tui - Launch interactive terminal search interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from semantic_code_intelligence.config.settings import AppConfig
+from semantic_code_intelligence.utils.logging import get_logger, print_error
+
+logger = get_logger("cli.tui")
+
+
+@click.command("tui")
+@click.option(
+    "--path",
+    "-p",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Project root path.",
+)
+@click.option(
+    "--mode",
+    "-m",
+    type=click.Choice(["semantic", "keyword", "regex", "hybrid"], case_sensitive=False),
+    default="hybrid",
+    help="Default search mode.",
+)
+@click.option(
+    "--top-k",
+    "-k",
+    default=10,
+    type=int,
+    help="Results per query.",
+)
+@click.pass_context
+def tui_cmd(ctx: click.Context, path: str, mode: str, top_k: int) -> None:
+    """Launch the interactive terminal search interface.
+
+    Provides a live search REPL with mode switching and result preview.
+
+    Examples:
+
+    \b
+        codexa tui
+        codexa tui --mode hybrid -k 20
+    """
+    root = Path(path).resolve()
+    config_dir = AppConfig.config_dir(root)
+
+    if not config_dir.exists():
+        print_error(f"Project not initialized at {root}. Run 'codexa init' first.")
+        ctx.exit(1)
+        return
+
+    from semantic_code_intelligence.tui import run_tui
+    run_tui(root, mode=mode, top_k=top_k)  # type: ignore[arg-type]

semantic_code_intelligence/cli/commands/viz_cmd.py

@@ -0,0 +1,127 @@
+"""CLI command: viz — generate Mermaid-compatible visualizations."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from semantic_code_intelligence.utils.logging import (
+    get_logger,
+    print_error,
+    print_info,
+    console,
+)
+
+logger = get_logger("cli.viz")
+
+
+@click.command("viz")
+@click.argument(
+    "kind",
+    type=click.Choice(["callgraph", "deps", "symbols", "workspace"], case_sensitive=False),
+)
+@click.option(
+    "--target",
+    "-t",
+    default="",
+    type=str,
+    help="Symbol name or file path to visualize.",
+)
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    type=click.Path(dir_okay=False, resolve_path=True),
+    help="Write Mermaid output to a file instead of stdout.",
+)
+@click.option(
+    "--json-output",
+    "--json",
+    "json_mode",
+    is_flag=True,
+    default=False,
+    help="Output as JSON with a 'mermaid' field.",
+)
+@click.option(
+    "--path",
+    "-p",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Project root path.",
+)
+@click.pass_context
+def viz_cmd(
+    ctx: click.Context,
+    kind: str,
+    target: str,
+    output: str | None,
+    json_mode: bool,
+    path: str,
+) -> None:
+    """Generate Mermaid-compatible diagrams from codebase analysis.
+
+    KIND is one of: callgraph, deps, symbols, workspace.
+
+    Examples:
+
+        codexa viz callgraph
+
+        codexa viz deps --target src/main.py
+
+        codexa viz symbols --target auth.py -o symbols.mmd
+
+        codexa viz callgraph --json
+    """
+    from semantic_code_intelligence.bridge.context_provider import ContextProvider
+    from semantic_code_intelligence.web.visualize import (
+        render_call_graph,
+        render_dependency_graph,
+        render_symbol_map,
+        render_workspace_graph,
+    )
+
+    project_root = Path(path)
+    provider = ContextProvider(project_root)
+
+    kind_lower = kind.lower()
+
+    try:
+        if kind_lower == "callgraph":
+            data = provider.get_call_graph(symbol_name=target)
+            mermaid = render_call_graph(data.get("edges", []))
+        elif kind_lower == "deps":
+            data = provider.get_dependencies(file_path=target)
+            mermaid = render_dependency_graph(data)
+        elif kind_lower == "symbols":
+            builder = provider._ensure_indexed()
+            symbols = builder.get_all_symbols()
+            if target:
+                symbols = [s for s in symbols if target in s.file_path]
+            sym_dicts = [s.to_dict() for s in symbols[:100]]
+            mermaid = render_symbol_map(sym_dicts, file_path=target)
+        elif kind_lower == "workspace":
+            # Try to load workspace repos
+            try:
+                from semantic_code_intelligence.workspace import Workspace
+                ws = Workspace.load(project_root)
+                repos = [r.to_dict() for r in ws.repos] if ws.repos else []
+            except Exception:
+                repos = []
+            mermaid = render_workspace_graph(repos)
+        else:
+            print_error(f"Unknown visualization kind: {kind}")
+            return
+    except Exception as exc:
+        print_error(f"Visualization error: {exc}")
+        return
+
+    # Output
+    if json_mode:
+        click.echo(json.dumps({"kind": kind_lower, "mermaid": mermaid}, indent=2))
+    elif output:
+        Path(output).write_text(mermaid, encoding="utf-8")
+        print_info(f"Written to {output}")
+    else:
+        console.print(mermaid)