athena-code 0.0.14__py3-none-any.whl

athena/entity_path.py

@@ -0,0 +1,146 @@
+"""Entity path parsing and resolution.
+
+Entity path format: dir/package/module:class.method
+Examples:
+  - src/athena/cli.py:app
+  - src/athena/parsers/python_parser.py:PythonParser.parse_athena_tag
+  - models.py:Entity
+  - src/athena
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class EntityPath:
+    """Represents a parsed entity path.
+
+    Attributes:
+        file_path: Path to the file (without entity specification)
+        entity_name: Name of the entity within the file (class.method or function)
+                    None for module-level or package-level operations
+    """
+
+    file_path: str
+    entity_name: str | None = None
+
+    @property
+    def is_package(self) -> bool:
+        """Check if this path represents a package (directory)."""
+        return not self.file_path.endswith(".py") and self.entity_name is None
+
+    @property
+    def is_module(self) -> bool:
+        """Check if this path represents a module (file without entity)."""
+        return self.file_path.endswith(".py") and self.entity_name is None
+
+    @property
+    def is_class(self) -> bool:
+        """Check if this path represents a class (no dot in entity name)."""
+        return self.entity_name is not None and "." not in self.entity_name
+
+    @property
+    def is_method(self) -> bool:
+        """Check if this path represents a method (dot in entity name)."""
+        return self.entity_name is not None and "." in self.entity_name
+
+    @property
+    def class_name(self) -> str | None:
+        """Extract class name if this is a method path."""
+        if self.is_method:
+            return self.entity_name.split(".")[0]
+        return None
+
+    @property
+    def method_name(self) -> str | None:
+        """Extract method name if this is a method path."""
+        if self.is_method:
+            return self.entity_name.split(".")[1]
+        return None
+
+
+def parse_entity_path(path: str) -> EntityPath:
+    """Parse an entity path string into components.
+
+    Format: [directory/]file.py[:entity[.subentity]]
+
+    Args:
+        path: Entity path string to parse
+
+    Returns:
+        EntityPath object with parsed components
+
+    Raises:
+        ValueError: If path format is invalid
+
+    Examples:
+        >>> parse_entity_path("src/foo/bar.py:Baz.bax")
+        EntityPath(file_path='src/foo/bar.py', entity_name='Baz.bax')
+
+        >>> parse_entity_path("models.py:Entity")
+        EntityPath(file_path='models.py', entity_name='Entity')
+
+        >>> parse_entity_path("src/athena/cli.py")
+        EntityPath(file_path='src/athena/cli.py', entity_name=None)
+
+        >>> parse_entity_path("src/athena")
+        EntityPath(file_path='src/athena', entity_name=None)
+    """
+    if not path or not path.strip():
+        raise ValueError("Entity path cannot be empty")
+
+    # Split on colon to separate file path from entity name
+    if ":" in path:
+        file_path, entity_name = path.split(":", 1)
+        entity_name = entity_name.strip()
+        if not entity_name:
+            entity_name = None
+    else:
+        file_path = path
+        entity_name = None
+
+    file_path = file_path.strip()
+
+    if not file_path:
+        raise ValueError("File path component cannot be empty")
+
+    return EntityPath(file_path=file_path, entity_name=entity_name)
+
+
+def resolve_entity_path(entity_path: EntityPath, repo_root: Path) -> Path | None:
+    """Resolve an EntityPath to an actual file system path.
+
+    Args:
+        entity_path: Parsed entity path
+        repo_root: Root directory of the repository
+
+    Returns:
+        Resolved Path object if file/directory exists, None otherwise
+    """
+    # Construct full path
+    full_path = repo_root / entity_path.file_path
+
+    # If it's meant to be a package, check if it's a valid directory
+    if entity_path.is_package:
+        # Check if the directory exists
+        if not full_path.is_dir():
+            return None
+
+        # For the repository root (.), we don't require __init__.py
+        # For other directories, require __init__.py to be a valid package
+        if entity_path.file_path == ".":
+            return full_path
+
+        init_path = full_path / "__init__.py"
+        if init_path.exists():
+            # Return the directory path, not __init__.py
+            return full_path
+        return None
+
+    # For files, check if path exists
+    if full_path.exists():
+        return full_path
+
+    return None

athena/hashing.py

@@ -0,0 +1,156 @@
+"""Hash generation infrastructure for code entities using tree-sitter AST."""
+
+import hashlib
+import re
+
+
+def _is_docstring_node(node, parent_node) -> bool:
+    """Check if a node is a docstring (first statement in body that's a string).
+
+    Args:
+        node: The node to check
+        parent_node: The parent node (should be a block)
+
+    Returns:
+        True if this is a docstring node
+    """
+    # Docstrings are expression_statements containing a string
+    if node.type != "expression_statement":
+        return False
+
+    # Must be the first child of a block (body)
+    if parent_node is None or parent_node.type != "block":
+        return False
+
+    # Check if this is the first child of the block
+    if parent_node.children and parent_node.children[0] == node:
+        # Check if it contains a string
+        for child in node.children:
+            if child.type == "string":
+                return True
+
+    return False
+
+
+def serialize_ast_node(node, source_code: str) -> str:
+    """Serialize a tree-sitter AST node to a stable string representation.
+
+    This serialization includes node types and names, which forms the basis for
+    generating content hashes. The serialization is designed to be stable across
+    whitespace changes but sensitive to semantic changes.
+
+    Docstrings are excluded from serialization to ensure hash stability when
+    @athena tags are added or updated.
+
+    Args:
+        node: Tree-sitter AST node to serialize
+        source_code: Source code string for extracting identifiers
+
+    Returns:
+        Serialized string representation of the AST structure
+    """
+    parts = []
+
+    def serialize(n, parent=None, depth: int = 0):
+        """Recursively serialize the node and its children."""
+        # Skip docstring nodes
+        if _is_docstring_node(n, parent):
+            return
+
+        # For nodes with meaningful text content, include the text
+        if n.type in ("identifier", "integer", "float", "string"):
+            text = source_code.encode("utf8")[n.start_byte : n.end_byte].decode("utf8")
+            parts.append(f"{n.type}:{text}")
+        else:
+            # Add node type
+            parts.append(f"{n.type}")
+
+        # Recursively serialize children
+        for child in n.children:
+            serialize(child, n, depth + 1)
+
+    serialize(node)
+    return "|".join(parts)
+
+
+def compute_hash(content: str) -> str:
+    """Compute SHA-256 hash and truncate to 12 hex characters.
+
+    Args:
+        content: Content string to hash
+
+    Returns:
+        12-character hex hash string
+    """
+    hash_obj = hashlib.sha256(content.encode("utf8"))
+    return hash_obj.hexdigest()[:12]
+
+
+def compute_function_hash(node, source_code: str) -> str:
+    """Compute hash for a function (signature + body).
+
+    Args:
+        node: Tree-sitter function_definition node
+        source_code: Source code string
+
+    Returns:
+        12-character hex hash
+    """
+    # Serialize the entire function node (includes signature and body)
+    serialization = serialize_ast_node(node, source_code)
+    return compute_hash(serialization)
+
+
+def compute_class_hash(node, source_code: str) -> str:
+    """Compute hash for a class (declaration + method signatures + implementations).
+
+    Args:
+        node: Tree-sitter class_definition node
+        source_code: Source code string
+
+    Returns:
+        12-character hex hash
+    """
+    # Serialize the entire class node (includes declaration, methods, etc.)
+    serialization = serialize_ast_node(node, source_code)
+    return compute_hash(serialization)
+
+
+def compute_module_hash(entities_docstrings: list[str]) -> str:
+    """Compute hash for a module based on non-whitespace from entity docstrings.
+
+    Args:
+        entities_docstrings: List of docstring contents from module entities
+
+    Returns:
+        12-character hex hash
+    """
+    # Concatenate all docstrings with non-whitespace characters only
+    combined = ""
+    for docstring in entities_docstrings:
+        if docstring:
+            # Remove all whitespace
+            no_whitespace = re.sub(r"\s+", "", docstring)
+            combined += no_whitespace
+
+    return compute_hash(combined)
+
+
+def compute_package_hash(module_docstrings: list[str]) -> str:
+    """Compute hash for a package based on non-whitespace from module docstrings.
+
+    Args:
+        module_docstrings: List of module docstrings from package
+
+    Returns:
+        12-character hex hash
+    """
+    # Same logic as module hash - concatenate non-whitespace
+    combined = ""
+    for docstring in module_docstrings:
+        if docstring:
+            # Remove all whitespace
+            no_whitespace = re.sub(r"\s+", "", docstring)
+            combined += no_whitespace
+
+    return compute_hash(combined)

athena/info.py

@@ -0,0 +1,84 @@
+from pathlib import Path
+
+from athena.models import EntityInfo, PackageInfo
+from athena.parsers import get_parser_for_file
+from athena.repository import find_repository_root, get_relative_path
+
+
+def get_entity_info(
+    file_path: str,
+    entity_name: str | None = None,
+    root: Path | None = None
+) -> EntityInfo | None:
+    """Get detailed information about an entity in a file or package.
+
+    Args:
+        file_path: Path to file or directory (can be absolute or relative to repo root)
+        entity_name: Name of entity, or None for module/package-level info
+        root: Repository root (auto-detected if None)
+
+    Returns:
+        EntityInfo object, or None if file/entity not found
+
+    Raises:
+        FileNotFoundError: If file/directory doesn't exist
+        ValueError: If file type not supported or directory missing __init__.py
+    """
+    # Auto-detect repository root if not provided
+    if root is None:
+        root = find_repository_root(Path.cwd())
+
+    # Resolve file path
+    file_path_obj = Path(file_path)
+    if not file_path_obj.is_absolute():
+        file_path_obj = root / file_path_obj
+
+    # Check path exists
+    if not file_path_obj.exists():
+        raise FileNotFoundError(f"Path not found: {file_path}")
+
+    # Handle directory (package) case
+    if file_path_obj.is_dir():
+        if entity_name is not None:
+            raise ValueError(f"Cannot specify entity name for package: {file_path}")
+
+        # Look for __init__.py
+        init_file = file_path_obj / "__init__.py"
+        if not init_file.exists():
+            raise ValueError(f"Package missing __init__.py: {file_path}")
+
+        # Get parser and extract module docstring from __init__.py
+        parser = get_parser_for_file(init_file)
+        if parser is None:
+            raise ValueError(f"Cannot parse __init__.py in: {file_path}")
+
+        source_code = init_file.read_text()
+        # Get relative path for the directory
+        relative_path = get_relative_path(file_path_obj, root)
+
+        # Extract module-level info from __init__.py
+        module_info = parser.extract_entity_info(source_code, str(init_file), None)
+
+        # Convert to PackageInfo
+        if module_info is not None:
+            return PackageInfo(
+                path=relative_path,
+                summary=module_info.summary if hasattr(module_info, 'summary') else None
+            )
+        else:
+            return PackageInfo(path=relative_path, summary=None)
+
+    # Handle file case
+    # Get parser for file
+    parser = get_parser_for_file(file_path_obj)
+    if parser is None:
+        raise ValueError(f"Unsupported file type: {file_path}")
+
+    # Read source code
+    source_code = file_path_obj.read_text()
+
+    # Get relative path for EntityInfo.path
+    relative_path = get_relative_path(file_path_obj, root)
+
+    # Call parser to extract entity info
+    return parser.extract_entity_info(source_code, relative_path, entity_name)

athena/locate.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+
+from athena.models import Entity
+from athena.parsers import get_parser_for_file
+from athena.repository import find_python_files, find_repository_root, get_relative_path
+
+
+def locate_entity(name: str, root: Path | None = None) -> list[Entity]:
+    """Locate all entities with the given name in the repository.
+
+    For methods, the search matches both the full qualified name (ClassName.method_name)
+    and the short method name (method_name).
+
+    Args:
+        name: The entity name to search for
+        root: Repository root (defaults to auto-detected root)
+
+    Returns:
+        List of Entity objects matching the given name
+    """
+    if root is None:
+        root = find_repository_root()
+
+    entities = []
+
+    for file_path in find_python_files(root):
+        parser = get_parser_for_file(file_path)
+        if parser is None:
+            continue
+
+        try:
+            source_code = file_path.read_text(encoding="utf-8")
+            relative_path = get_relative_path(file_path, root)
+
+            file_entities = parser.extract_entities(source_code, relative_path)
+
+            # Filter entities by name
+            for entity in file_entities:
+                # Exact match
+                if entity.name == name:
+                    entities.append(entity)
+                # For methods, also match the short name (without class prefix)
+                elif entity.kind == "method" and "." in entity.name:
+                    method_name = entity.name.split(".", 1)[1]
+                    if method_name == name:
+                        entities.append(entity)
+        except Exception:
+            # Skip files that can't be read or parsed
+            # This allows the scan to continue even if some files fail
+            continue
+
+    return entities

athena/mcp_config.py

@@ -0,0 +1,103 @@
+"""MCP configuration management for Claude Code integration."""
+
+import json
+import os
+import platform
+from pathlib import Path
+
+
+def get_claude_config_path() -> Path:
+    """Get the Claude Code configuration file path for the current OS.
+
+    Returns:
+        Path to claude_desktop_config.json
+
+    Raises:
+        RuntimeError: If OS is not supported
+    """
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    elif system == "Linux":
+        return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+    elif system == "Windows":
+        return Path(os.environ["APPDATA"]) / "Claude" / "claude_desktop_config.json"
+    else:
+        raise RuntimeError(f"Unsupported operating system: {system}")
+
+
+def install_mcp_config() -> tuple[bool, str]:
+    """Install MCP server configuration for Claude Code.
+
+    Returns:
+        Tuple of (success, message)
+    """
+    try:
+        config_path = get_claude_config_path()
+
+        # Ensure config directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Load existing config or create new one
+        if config_path.exists():
+            with open(config_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+        else:
+            config = {}
+
+        # Ensure mcpServers section exists
+        if "mcpServers" not in config:
+            config["mcpServers"] = {}
+
+        # Check if ack is already configured
+        if "ack" in config["mcpServers"]:
+            return (False, "MCP server already configured")
+
+        # Add ack MCP server configuration
+        config["mcpServers"]["ack"] = {
+            "command": "ack",
+            "args": ["mcp-server"]
+        }
+
+        # Write updated config
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+
+        return (True, f"MCP server configured at {config_path}")
+
+    except Exception as e:
+        return (False, f"Failed to install MCP config: {e}")
+
+
+def uninstall_mcp_config() -> tuple[bool, str]:
+    """Remove MCP server configuration from Claude Code.
+
+    Returns:
+        Tuple of (success, message)
+    """
+    try:
+        config_path = get_claude_config_path()
+
+        if not config_path.exists():
+            return (False, "Claude config file not found")
+
+        # Load existing config
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+
+        # Check if ack is configured
+        if "mcpServers" not in config or "ack" not in config["mcpServers"]:
+            return (False, "MCP server not configured")
+
+        # Remove ack configuration
+        del config["mcpServers"]["ack"]
+
+        # Write updated config
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+
+        return (True, f"MCP server removed from {config_path}")
+
+    except Exception as e:
+        return (False, f"Failed to uninstall MCP config: {e}")