athena-code 0.0.14__py3-none-any.whl

athena/README.md

@@ -0,0 +1,132 @@
+# Athena Code Knowledge
+
+A semantic code analysis tool designed to help Claude Code navigate repositories efficiently while dramatically reducing token consumption.
+
+## Motivation
+
+Claude Code currently incurs significant token costs during repository navigation. A typical planning phase involves reading 10-20 files to understand codebase architecture, consuming substantially more tokens than the targeted modifications themselves. This linear scaling with codebase size makes work on large repositories inefficient.
+
+Most discovery queries ("What does this file contain?", "Where is function X?") don't require reading entire source files. By building a queryable semantic index, we can answer these questions using structured metadata instead, potentially reducing planning token costs by 15-30x.
+
+## What's the deal with the name?
+Athena was an Ancient Greek goddess associated with strategic wisdom, logic, crafts, architecture and discipline. She is a patron of engineers and planners, not dreamers. Seemed appropriate.
+
+One of her symbolic animals was the owl.
+
+## Installation
+
+NOTE: Athena currently only works in a Python codebase. More supported languages coming soon!
+
+Install with pipx:
+```bash
+pipx install athena-code
+```
+Requires at least Python 3.12, so if that's not installed you should do that with your system package manager. It doesn't need to be the default Python, you can leave that at whatever you want and point Pipx at Python 3.12 explicitly:
+```bash
+pipx install --python python3.12 athena-code
+```
+
+## Usage
+use `athena --help` to see up-to-date information about the available features:
+
+```
+╭─ Commands ─────────────────────────────────────────────────────────────────────╮
+│ locate          Locate entities (functions, classes, methods) by name.         │
+│ info            Get detailed information about a code entity or package.       │
+│ mcp-server      Start the MCP server for Claude Code integration.              │
+│ install-mcp     Install MCP server configuration for Claude Code.              │
+│ sync            Update @athena hash tags in docstrings.                        │
+│ status          Check docstring hash synchronization status.                   │
+│ uninstall-mcp   Remove MCP server configuration from Claude Code.              │
+╰────────────────────────────────────────────────────────────────────────────────╯
+```
+
+Generally, you will install `athena` and then:
+- Run `athena sync` in your codebase. This will add Athena's hashes to all the docstrings and allow `athena` to detect code changes that have invalidated the docstrings.
+- After code changes, run `athena status` to see a table of all the functions that have been updated and may have had their docstrings invalidated.
+- Update the necessary docstrings and then run `athena sync` again to update all the necessary hashes.
+
+If you want to find an entity in the codebase, then just run `athena locate <entity>` to get details on the file and lines the entity occupies:
+```bash
+> athena locate get_task
+ Kind    Path                    Extent  
+ method  src/tasktree/parser.py  277-286
+```
+
+Once you know where a thing is, then you can ask for info about it:
+```bash
+> athena info src/tasktree/parser.py:get_task
+{
+  "method": {
+    "name": "Recipe.get_task",
+    "path": "src/tasktree/parser.py",
+    "extent": {
+      "start": 277,
+      "end": 286
+    },
+    "sig": {
+      "name": "get_task",
+      "args": [
+        {
+          "name": "self"
+        },
+        {
+          "name": "name",
+          "type": "str"
+        }
+      ],
+      "return_type": "Task | None"
+    },
+    "summary": "Get task by name.\n\n        Args:\n            name: Task name (may be namespaced like 'build.compile')\n\n        Returns:\n            Task if found, None otherwise\n        "
+  }
+}
+```
+
+## Install Claude MCP integrations
+
+Athena includes Model Context Protocol (MCP) integration, exposing code navigation capabilities as first-class tools in Claude Code.
+
+### Benefits
+
+- **Native tool discovery** — Tools appear in Claude Code's capabilities list
+- **Structured I/O** — Type-safe parameters and responses
+
+### Available Tools
+
+- **`ack_locate`** — Find Python entity location (file path + line range)
+
+### Installation
+
+```bash
+athena install-mcp
+```
+
+This automatically configures Claude Code by adding the MCP server entry to your config file. You will need to restart Claude Code for changes to take effect.
+
+**Uninstalling:**
+
+If you don't like using your Anthropic tokens more efficiently to generate better code, for some reason, then:
+```bash
+athena uninstall-mcp
+```
+to remove the MCP integration
+
+## Usage Workflow
+
+```bash
+cd /path/to/repository
+athena locate validateSession  # Find the locations of entities in the codebase
+```
+
+## Contributing
+
+This is an active development project. Early-stage contributions welcome, particularly:
+
+- Tree-sitter AST extraction improvements
+- Language-specific signature formatting
+- LLM prompt engineering for summary quality
+- Performance benchmarking
+
+## License
+
+MIT - See LICENSE

athena/__init__.py

@@ -0,0 +1,8 @@
+"""Athena - A semantic code analysis tool designed to help Claude Code navigate repositories efficiently while dramatically reducing token consumption."""
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("athena")
+except Exception:
+    __version__ = "0.0.0.dev0+local"  # Fallback for development

athena/__main__.py

@@ -0,0 +1,5 @@
+from athena.cli import app
+
+
+if __name__ == "__main__":
+    app()

athena/cli.py

@@ -0,0 +1,347 @@
+import asyncio
+import json as json_module
+
+from dataclasses import asdict
+from rich.console import Console
+from typing import Optional
+
+import typer
+
+from athena import __version__
+from athena.info import get_entity_info
+from athena.locate import locate_entity
+from athena.models import ClassInfo, FunctionInfo, MethodInfo, ModuleInfo, PackageInfo
+from athena.repository import RepositoryNotFoundError, find_repository_root
+
+app = typer.Typer(
+    help="Athena Code Knowledge - semantic code analysis tool",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+@app.command()
+def locate(
+    entity_name: str,
+    json: bool = typer.Option(False, "--json", "-j", help="Output as JSON instead of table")
+):
+    """Locate entities (functions, classes, methods) by name.
+
+    Args:
+        entity_name: The name of the entity to search for
+        json: If True, output JSON format; otherwise output as table (default)
+    """
+    try:
+        entities = locate_entity(entity_name)
+
+        if json:
+            # Convert entities to dictionaries and remove the name field (internal only)
+            results = []
+            for entity in entities:
+                entity_dict = asdict(entity)
+                del entity_dict["name"]  # Name is only for internal filtering
+                results.append(entity_dict)
+
+            # Output as JSON
+            typer.echo(json_module.dumps(results, indent=2))
+        else:
+            # Output as table
+            from rich.table import Table
+
+            table = Table(show_header=True, header_style="bold cyan", box=None)
+            table.add_column("Kind", style="green")
+            table.add_column("Path", style="blue")
+            table.add_column("Extent", style="yellow")
+
+            for entity in entities:
+                extent_str = f"{entity.extent.start}-{entity.extent.end}"
+                table.add_row(entity.kind, entity.path, extent_str)
+
+            console.print(table)
+
+    except RepositoryNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=2)
+
+
+@app.command()
+def info(location: str):
+    """Get detailed information about a code entity or package.
+
+    Args:
+        location: Path to entity in format "file_path:entity_name",
+                 "file_path" for module-level info,
+                 or "directory_path" for package info
+
+    Examples:
+        ack info src/auth/session.py:validateSession
+        ack info src/auth/session.py
+        ack info src/athena
+    """
+    # Parse location string
+    if ":" in location:
+        file_path, entity_name = location.rsplit(":", 1)
+        # Handle empty entity name after colon
+        if not entity_name:
+            entity_name = None
+    else:
+        file_path = location
+        entity_name = None
+
+    try:
+        # Get entity info
+        entity_info = get_entity_info(file_path, entity_name)
+    except (FileNotFoundError, ValueError, RepositoryNotFoundError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=2)
+
+    # Check if entity was found
+    if entity_info is None:
+        typer.echo(f"Error: Entity '{entity_name}' not found in {file_path}", err=True)
+        raise typer.Exit(code=1)
+
+    # Wrap in discriminated structure
+    if isinstance(entity_info, FunctionInfo):
+        output = {"function": asdict(entity_info)}
+    elif isinstance(entity_info, ClassInfo):
+        output = {"class": asdict(entity_info)}
+    elif isinstance(entity_info, MethodInfo):
+        output = {"method": asdict(entity_info)}
+    elif isinstance(entity_info, ModuleInfo):
+        output = {"module": asdict(entity_info)}
+    elif isinstance(entity_info, PackageInfo):
+        output = {"package": asdict(entity_info)}
+    else:
+        typer.echo(f"Error: Unknown entity type: {type(entity_info)}", err=True)
+        raise typer.Exit(code=2)
+
+    # Filter out None values (especially summary field)
+    # When summary is None, we want to omit it entirely from JSON
+    def filter_none(d):
+        if isinstance(d, dict):
+            return {k: filter_none(v) for k, v in d.items() if v is not None}
+        elif isinstance(d, list):
+            return [filter_none(item) for item in d]
+        else:
+            return d
+
+    output = filter_none(output)
+
+    # Output as JSON
+    typer.echo(json_module.dumps(output, indent=2))
+
+
+@app.command()
+def mcp_server():
+    """Start the MCP server for Claude Code integration.
+
+    This command starts the Model Context Protocol server that exposes
+    Athena's code navigation tools to Claude Code via structured JSON-RPC.
+    """
+    from athena.mcp_server import main
+
+    asyncio.run(main())
+
+
+@app.command()
+def install_mcp():
+    """Install MCP server configuration for Claude Code.
+
+    This command automatically configures Claude Code to use the Athena
+    MCP server by adding the appropriate entry to the Claude config file.
+    """
+    from athena.mcp_config import install_mcp_config
+
+    success, message = install_mcp_config()
+
+    if success:
+        typer.echo(f"✓ {message}")
+        typer.echo("\nRestart Claude Code for changes to take effect.")
+    else:
+        typer.echo(f"✗ {message}", err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def sync(
+    entity: Optional[str] = typer.Argument(None, help="Entity to sync (module, class, function, etc.)"),
+    force: bool = typer.Option(False, "--force", "-f", help="Force hash recalculation even if valid"),
+    recursive: bool = typer.Option(False, "--recursive", "-r", help="Apply recursively to sub-entities"),
+):
+    """Update @athena hash tags in docstrings.
+
+    Updates or inserts @athena hash tags in entity docstrings based on their
+    current code structure. Hashes are computed from the AST and embedded
+    in docstrings for staleness detection.
+
+    If no entity is specified, syncs the entire project recursively.
+
+    Examples:
+        athena sync                                   # Sync entire project
+        athena sync src/module.py                     # Sync all entities in module
+        athena sync src/module.py:MyClass             # Sync specific class
+        athena sync src/module.py:MyClass.method      # Sync specific method
+        athena sync src/package --recursive           # Sync package recursively
+        athena sync src/module.py:func --force        # Force update even if hash matches
+    """
+    from athena.sync import sync_entity, sync_recursive
+
+    try:
+        repo_root = find_repository_root()
+    except RepositoryNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=255)
+
+    # If no entity specified, sync entire project
+    if entity is None:
+        entity = "."
+        recursive = True
+
+    try:
+        if recursive:
+            # Use recursive sync
+            update_count = sync_recursive(entity, force, repo_root)
+            if update_count > 0:
+                typer.echo(f"Updated {update_count} entities")
+            else:
+                typer.echo("No updates needed")
+        else:
+            # Use single entity sync
+            updated = sync_entity(entity, force, repo_root)
+            if updated:
+                typer.echo("Updated 1 entity")
+            else:
+                typer.echo("No updates needed")
+
+    except NotImplementedError as e:
+        typer.echo(f"Error: {e}", err=True)
+        typer.echo("\nNote: Module and package-level sync requires --recursive flag")
+        raise typer.Exit(code=1)
+    except (ValueError, FileNotFoundError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=2)
+
+
+@app.command()
+def status(
+    entity: Optional[str] = typer.Argument(None, help="Entity to check status for"),
+    recursive: bool = typer.Option(False, "--recursive", "-r", help="Check entity and all sub-entities"),
+):
+    """Check docstring hash synchronization status.
+
+    Displays which entities have out-of-sync @athena hash tags. An entity is
+    out-of-sync if it has no hash tag or if the tag doesn't match the current
+    code structure.
+
+    If no entity is specified, checks the entire project.
+
+    Examples:
+        athena status src/module.py:MyClass            # Check specific class
+        athena status src/module.py:MyClass -r         # Check class and methods
+        athena status src/module.py --recursive        # Check all entities in module
+    """
+    from athena.status import check_status, check_status_recursive, filter_out_of_sync
+    from rich.table import Table
+
+    try:
+        repo_root = find_repository_root()
+    except RepositoryNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=255)
+
+    # If no entity specified, check entire project recursively
+    if entity is None:
+        entity = "."
+        recursive = True
+
+    try:
+        if recursive:
+            statuses = check_status_recursive(entity, repo_root)
+        else:
+            statuses = check_status(entity, repo_root)
+        out_of_sync = filter_out_of_sync(statuses)
+
+        if not out_of_sync:
+            typer.echo("All entities are in sync")
+            return
+
+        typer.echo(f"{len(out_of_sync)} entities need updating")
+        typer.echo()
+
+        table = Table(show_header=True, header_style="bold cyan", box=None)
+        table.add_column("Kind", style="green")
+        table.add_column("Path", style="blue")
+        table.add_column("Extent", style="yellow")
+        table.add_column("Recorded Hash", style="magenta")
+        table.add_column("Calc. Hash", style="magenta")
+
+        for status_item in out_of_sync:
+            recorded = status_item.recorded_hash or "<NONE>"
+            table.add_row(
+                status_item.kind,
+                status_item.path,
+                status_item.extent,
+                recorded,
+                status_item.calculated_hash
+            )
+
+        console.print(table)
+
+    except NotImplementedError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+    except (ValueError, FileNotFoundError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=2)
+
+
+@app.command()
+def uninstall_mcp():
+    """Remove MCP server configuration from Claude Code.
+
+    This command removes the Athena MCP server entry from the Claude
+    configuration file.
+    """
+    from athena.mcp_config import uninstall_mcp_config
+
+    success, message = uninstall_mcp_config()
+
+    if success:
+        typer.echo(f"✓ {message}")
+        typer.echo("\nRestart Claude Code for changes to take effect.")
+    else:
+        typer.echo(f"✗ {message}", err=True)
+        raise typer.Exit(code=1)
+
+
+def _version_callback(value: bool):
+    """Show version and exit."""
+    if value:
+        console.print(f"athena version {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit",
+    )):
+    pass

athena/docstring_updater.py

@@ -0,0 +1,133 @@
+"""Module for updating docstrings in source code files."""
+
+from athena.models import Location
+
+
+def update_docstring_in_source(
+    source_code: str, entity_location: Location, new_docstring: str
+) -> str:
+    """Replace or insert docstring in source code for a given entity.
+
+    This function updates the docstring at the specified location in the source code.
+    It handles:
+    - Entities with existing docstrings (updates them)
+    - Entities without docstrings (inserts new docstring)
+    - Preservation of indentation and formatting
+
+    Args:
+        source_code: Full source code string
+        entity_location: Location of the entity (start/end line numbers, 0-indexed)
+        new_docstring: New docstring content (without triple quotes)
+
+    Returns:
+        Updated source code with new docstring
+
+    Raises:
+        ValueError: If entity_location is invalid
+    """
+    lines = source_code.splitlines(keepends=True)
+
+    # Validate location
+    if entity_location.start < 0 or entity_location.end >= len(lines):
+        raise ValueError(f"Invalid entity location: {entity_location}")
+
+    # Find the definition line (function/class declaration)
+    # The entity location may include decorators, so we need to find the actual def/class line
+    def_line_idx = entity_location.start
+
+    # Search for the actual def/class line (skip any decorators)
+    for i in range(entity_location.start, min(entity_location.end + 1, len(lines))):
+        stripped = lines[i].lstrip()
+        if stripped.startswith('def ') or stripped.startswith('class '):
+            def_line_idx = i
+            break
+
+    # Determine indentation of the entity
+    def_line = lines[def_line_idx]
+    indent = len(def_line) - len(def_line.lstrip())
+    entity_indent = " " * indent
+
+    # Determine the body start (line after def/class declaration)
+    # For multi-line signatures, we need to find the line with the closing colon
+    # Search forward from def_line_idx to find a line ending with ':'
+    body_start_idx = def_line_idx + 1
+    for i in range(def_line_idx, min(entity_location.end + 1, len(lines))):
+        line = lines[i]
+        # Check if line ends with ':' (ignoring trailing whitespace and comments)
+        stripped = line.rstrip()
+        if stripped.endswith(':'):
+            body_start_idx = i + 1
+            break
+
+    # Check if there's already a docstring
+    # A docstring is the first non-empty statement in the body
+    docstring_start_idx = None
+    docstring_end_idx = None
+
+    # Skip empty lines after definition
+    search_idx = body_start_idx
+    while search_idx <= entity_location.end and search_idx < len(lines):
+        line = lines[search_idx]
+        stripped = line.strip()
+
+        if not stripped:
+            # Empty line, continue
+            search_idx += 1
+            continue
+
+        # Check if this line starts a docstring (triple quotes)
+        if stripped.startswith('"""') or stripped.startswith("'''"):
+            # Found docstring start
+            docstring_start_idx = search_idx
+            quote_type = '"""' if stripped.startswith('"""') else "'''"
+
+            # Check if it's a single-line docstring
+            # Remove leading quote
+            after_start_quote = stripped[3:]
+            if after_start_quote.endswith(quote_type):
+                # Single-line docstring
+                docstring_end_idx = search_idx
+            else:
+                # Multi-line docstring - find the end
+                search_idx += 1
+                while search_idx <= entity_location.end and search_idx < len(lines):
+                    if quote_type in lines[search_idx]:
+                        docstring_end_idx = search_idx
+                        break
+                    search_idx += 1
+
+            break
+        else:
+            # Non-docstring statement found, no docstring exists
+            break
+
+    # Format the new docstring with proper indentation
+    docstring_indent = entity_indent + "    "  # One level deeper than entity
+    formatted_lines = []
+    formatted_lines.append(f'{docstring_indent}"""\n')
+
+    # Add docstring content with proper indentation
+    # Strip existing indentation from each line and apply consistent indentation
+    for line in new_docstring.splitlines():
+        stripped = line.lstrip()
+        if stripped:  # Non-empty line
+            formatted_lines.append(f"{docstring_indent}{stripped}\n")
+        else:  # Empty line
+            formatted_lines.append("\n")
+
+    formatted_lines.append(f'{docstring_indent}"""\n')
+
+    # Now insert or replace the docstring
+    if docstring_start_idx is not None and docstring_end_idx is not None:
+        # Replace existing docstring
+        # Remove old docstring lines
+        result_lines = (
+            lines[:docstring_start_idx]
+            + formatted_lines
+            + lines[docstring_end_idx + 1 :]
+        )
+    else:
+        # Insert new docstring after definition line
+        result_lines = lines[:body_start_idx] + formatted_lines + lines[body_start_idx:]
+
+    return "".join(result_lines)