zerottmm 0.1.0__py3-none-any.whl

zerottmm/__init__.py

@@ -0,0 +1,38 @@
+"""Top‑level package for ttmm.
+
+`ttmm` (Time‑to‑Mental‑Model) helps you build a mental model of a Python codebase
+faster.  It can index a repository, compute hotspots, navigate static call graphs,
+run dynamic traces and answer natural language questions about your code.  The core
+functionality lives in submodules:
+
+* `ttmm.index` – parse and index a Python repository
+* `ttmm.store` – SQLite persistence layer
+* `ttmm.metrics` – compute cyclomatic complexity and other metrics
+* `ttmm.gitutils` – git churn calculations
+* `ttmm.trace` – runtime tracing using `sys.settrace`
+* `ttmm.search` – tiny TF‑IDF search over your codebase
+* `ttmm.cli` – command line entry point
+
+Importing this package will expose the `__version__` attribute.  For most use cases
+you should call into `ttmm.cli` via the `ttmm` command line, or import functions
+from the specific submodules.
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:  # pragma: no cover - during development version metadata may be missing
+    __version__ = version(__name__)
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "index",
+    "store",
+    "metrics",
+    "gitutils",
+    "trace",
+    "search",
+    "gitingest",
+    "ai_analysis",
+    "cli",
+]

zerottmm/ai_analysis.py

@@ -0,0 +1,149 @@
+"""AI-powered code analysis using OpenAI API.
+
+This module provides AI-enhanced analysis capabilities for ttmm,
+allowing users to get natural language explanations and insights
+about their codebases using OpenAI's GPT models.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+
+def analyze_code_with_ai(
+    api_key: str,
+    analysis_type: str,
+    hotspots_context: List[str],
+    repo_info: Dict,
+    custom_prompt: Optional[str] = None,
+) -> str:
+    """Analyze code using OpenAI API.
+
+    Parameters
+    ----------
+    api_key : str
+        OpenAI API key
+    analysis_type : str
+        Type of analysis to perform
+    hotspots_context : List[str]
+        List of hotspot descriptions
+    repo_info : Dict
+        Repository metadata
+    custom_prompt : str, optional
+        Custom analysis prompt
+
+    Returns
+    -------
+    str
+        AI analysis result
+    """
+    try:
+        import openai
+    except ImportError:
+        return ("❌ **OpenAI library not installed**\n\n"
+                "Please install it with: `pip install openai`")
+
+    # Set up OpenAI client
+    client = openai.OpenAI(api_key=api_key)
+
+    # Prepare context
+    repo_context = f"""
+Repository Information:
+- Path: {repo_info.get('path', 'Unknown')}
+- Remote URL: {repo_info.get('remote_url', 'Local repository')}
+- Branch: {repo_info.get('branch', 'Unknown')}
+- Commit: {repo_info.get('commit', 'Unknown')}
+
+Top Code Hotspots (high complexity functions):
+{chr(10).join(hotspots_context[:5])}
+"""
+
+    # Define analysis prompts
+    analysis_prompts = {
+        "Explain hotspots": (
+            "Analyze the code hotspots listed above. Explain what makes these functions "
+            "complex and suggest potential improvements or areas that might need attention. "
+            "Focus on maintainability and potential refactoring opportunities."
+        ),
+        "Summarize architecture": (
+            "Based on the hotspots and repository information, provide a high-level "
+            "architectural summary of this codebase. Identify the main components, "
+            "patterns, and overall structure."
+        ),
+        "Identify design patterns": (
+            "Analyze the code hotspots and identify any design patterns being used. "
+            "Comment on the appropriateness of these patterns and suggest alternatives "
+            "if beneficial."
+        ),
+        "Find potential issues": (
+            "Review the code hotspots for potential issues like performance bottlenecks, "
+            "security concerns, maintainability problems, or technical debt. Provide "
+            "specific recommendations."
+        ),
+        "Custom analysis": custom_prompt or "Provide a general analysis of the codebase.",
+    }
+
+    prompt = analysis_prompts.get(analysis_type, analysis_prompts["Custom analysis"])
+
+    try:
+        response = client.chat.completions.create(
+            model="gpt-3.5-turbo",
+            messages=[
+                {
+                    "role": "system",
+                    "content": (
+                        "You are a senior software engineer helping to analyze a Python "
+                        "codebase. Provide clear, actionable insights based on the code "
+                        "metrics and hotspots provided. Be concise but thorough."
+                    )
+                },
+                {
+                    "role": "user",
+                    "content": f"{repo_context}\n\nAnalysis Request: {prompt}"
+                }
+            ],
+            max_tokens=1000,
+            temperature=0.3,
+        )
+
+        return response.choices[0].message.content or "No analysis generated."
+
+    except openai.OpenAIError as e:
+        return f"❌ **OpenAI API Error**: {str(e)}"
+    except Exception as e:
+        return f"❌ **Analysis Error**: {str(e)}"
+
+
+def test_openai_connection(api_key: str) -> tuple[bool, str]:
+    """Test if OpenAI API key is valid.
+
+    Parameters
+    ----------
+    api_key : str
+        OpenAI API key to test
+
+    Returns
+    -------
+    tuple[bool, str]
+        (success, message)
+    """
+    try:
+        import openai
+    except ImportError:
+        return False, "OpenAI library not installed"
+
+    try:
+        client = openai.OpenAI(api_key=api_key)
+        # Make a minimal API call to test the key
+        client.chat.completions.create(
+            model="gpt-3.5-turbo",
+            messages=[{"role": "user", "content": "Hello"}],
+            max_tokens=5
+        )
+        return True, "API key is valid"
+    except openai.AuthenticationError:
+        return False, "Invalid API key"
+    except openai.OpenAIError as e:
+        return False, f"OpenAI API error: {str(e)}"
+    except Exception as e:
+        return False, f"Connection error: {str(e)}"

zerottmm/cli.py

@@ -0,0 +1,212 @@
+"""Command line interface for ttmm.
+
+This module exposes a ``main`` function that can be installed as a
+console script entry point.  It supports subcommands for indexing,
+listing hotspots, resolving callers/callees, running traces and
+answering questions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List
+
+from . import index, store, trace, search, gitingest
+
+
+def do_index(args: argparse.Namespace) -> None:
+    repo_path = _resolve_repo_path(args.path)
+    if repo_path is None:
+        print(f"Failed to fetch repository: {args.path}")
+        sys.exit(1)
+
+    try:
+        index.index_repo(repo_path)
+        print(f"Indexed repository {args.path}")
+    finally:
+        # Clean up temp directory if it was a remote fetch
+        if repo_path != args.path and repo_path.startswith('/tmp'):
+            gitingest.cleanup_temp_repo(repo_path)
+
+
+def do_hotspots(args: argparse.Namespace) -> None:
+    repo_path = _resolve_repo_path(args.path, temp_ok=False)
+    if repo_path is None:
+        print(f"Repository not found or not indexed: {args.path}")
+        sys.exit(1)
+
+    conn = store.connect(repo_path)
+    try:
+        rows = store.get_hotspots(conn, limit=args.limit)
+        if not rows:
+            print("No hotspot data found. Did you index the repository?")
+            return
+        for row in rows:
+            score = row["complexity"] * (1.0 + (row["churn"] or 0) ** 0.5)
+            complexity_info = f"complexity={row['complexity']:.1f}"
+            churn_info = f"churn={row['churn']:.3f}, score={score:.2f}"
+            print(
+                f"{row['qualname']} ({row['file_path']}:{row['lineno']}) – {complexity_info}, "
+                f"{churn_info}"
+            )
+    finally:
+        store.close(conn)
+
+
+def do_callers(args: argparse.Namespace) -> None:
+    repo_path = _resolve_repo_path(args.path, temp_ok=False)
+    if repo_path is None:
+        print(f"Repository not found or not indexed: {args.path}")
+        sys.exit(1)
+
+    conn = store.connect(repo_path)
+    try:
+        sid = store.resolve_symbol(conn, args.symbol)
+        if sid is None:
+            print(f"Symbol '{args.symbol}' not found")
+            return
+        callers = store.get_callers(conn, sid)
+        if not callers:
+            print("No callers found.")
+        else:
+            for qualname, path in callers:
+                print(f"{qualname} ({path})")
+    finally:
+        store.close(conn)
+
+
+def do_callees(args: argparse.Namespace) -> None:
+    repo_path = _resolve_repo_path(args.path, temp_ok=False)
+    if repo_path is None:
+        print(f"Repository not found or not indexed: {args.path}")
+        sys.exit(1)
+
+    conn = store.connect(repo_path)
+    try:
+        sid = store.resolve_symbol(conn, args.symbol)
+        if sid is None:
+            print(f"Symbol '{args.symbol}' not found")
+            return
+        callees = store.get_callees(conn, sid)
+        if not callees:
+            print("No callees found.")
+        else:
+            for name, path, unresolved in callees:
+                suffix = " (unresolved)" if unresolved else ""
+                loc = f" ({path})" if path else ""
+                print(f"{name}{loc}{suffix}")
+    finally:
+        store.close(conn)
+
+
+def do_trace(args: argparse.Namespace) -> None:
+    repo_path = _resolve_repo_path(args.path, temp_ok=False)
+    if repo_path is None:
+        print(f"Repository not found or not indexed: {args.path}")
+        sys.exit(1)
+
+    # Flatten args after '--'
+    target_args: List[str] = args.args if hasattr(args, "args") else []
+    trace.run_tracing(repo_path, module=args.module, script=args.script, args=target_args)
+    print("Trace completed")
+
+
+def do_answer(args: argparse.Namespace) -> None:
+    repo_path = _resolve_repo_path(args.path, temp_ok=False)
+    if repo_path is None:
+        print(f"Repository not found or not indexed: {args.path}")
+        sys.exit(1)
+
+    results = search.answer_question(repo_path, args.question, top=args.limit, include_scores=True)
+    if not results:
+        print("No relevant symbols found.")
+    else:
+        for qualname, path, lineno, score in results:
+            print(f"{qualname} ({path}:{lineno}) – score={score:.2f}")
+
+
+def _resolve_repo_path(path_or_url: str, temp_ok: bool = True) -> str | None:
+    """Resolve a path or URL to a local repository path.
+
+    For URLs, fetches the repository. For local paths, validates existence.
+
+    Parameters
+    ----------
+    path_or_url : str
+        Local path, Git URL, or GitIngest URL
+    temp_ok : bool
+        Whether to allow temporary directory creation for remote repos
+
+    Returns
+    -------
+    str or None
+        Local path to repository, or None if resolution failed
+    """
+    import os
+
+    # If it's a local path that exists, return it
+    if os.path.exists(path_or_url):
+        return os.path.abspath(path_or_url)
+
+    # If temp directories are not allowed, only work with local paths
+    if not temp_ok:
+        return None
+
+    # Try to fetch as a remote repository
+    return gitingest.fetch_repository(path_or_url)
+
+
+def main(argv: List[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="ttmm", description="Time‑to‑Mental‑Model code reading assistant"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    # index
+    p_index = sub.add_parser("index", help="Index a Python repository")
+    p_index.add_argument(
+        "path", help="Path, Git URL, or GitIngest URL of repository"
+    )
+    p_index.set_defaults(func=do_index)
+    # hotspots
+    p_hot = sub.add_parser("hotspots", help="Show hottest functions/methods")
+    p_hot.add_argument("path", help="Path to repository")
+    p_hot.add_argument("--limit", type=int, default=10, help="Number of results to show")
+    p_hot.set_defaults(func=do_hotspots)
+    # callers
+    p_callers = sub.add_parser("callers", help="Show functions that call the given symbol")
+    p_callers.add_argument("path", help="Path to repository")
+    p_callers.add_argument("symbol", help="Fully qualified or simple symbol name")
+    p_callers.set_defaults(func=do_callers)
+    # callees
+    p_callees = sub.add_parser("callees", help="Show functions called by the given symbol")
+    p_callees.add_argument("path", help="Path to repository")
+    p_callees.add_argument("symbol", help="Fully qualified or simple symbol name")
+    p_callees.set_defaults(func=do_callees)
+    # trace
+    p_trace = sub.add_parser(
+        "trace", help="Trace runtime execution of a module function or script"
+    )
+    p_trace.add_argument("path", help="Path to repository")
+    group = p_trace.add_mutually_exclusive_group(required=True)
+    group.add_argument(
+        "--module", help="Module entry point in form pkg.module:func or pkg.module to run"
+    )
+    group.add_argument("--script", help="Relative path to a Python script to run")
+    p_trace.add_argument(
+        "args", nargs=argparse.REMAINDER,
+        help="Arguments passed to the module function or script"
+    )
+    p_trace.set_defaults(func=do_trace)
+    # answer
+    p_answer = sub.add_parser("answer", help="Answer a question about the codebase")
+    p_answer.add_argument("path", help="Path to repository")
+    p_answer.add_argument("question", help="Natural language question or keywords")
+    p_answer.add_argument("--limit", type=int, default=5, help="Number of answers to return")
+    p_answer.set_defaults(func=do_answer)
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

zerottmm/gitingest.py

@@ -0,0 +1,219 @@
+"""GitIngest integration for ttmm.
+
+This module handles fetching repositories from GitIngest URLs and other
+remote sources. It parses various Git hosting URLs (GitHub, GitLab, etc.)
+and provides functionality to download and extract repositories for analysis.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+import shutil
+import subprocess
+from typing import Optional, Tuple
+from urllib.parse import urlparse, parse_qs
+
+
+def _is_git_url(url: str) -> bool:
+    """Check if a string looks like a Git repository URL."""
+    git_patterns = [
+        r'https?://github\.com/[^/]+/[^/]+',
+        r'https?://gitlab\.com/[^/]+/[^/]+',
+        r'https?://bitbucket\.org/[^/]+/[^/]+',
+        r'git@github\.com:[^/]+/[^/]+\.git',
+        r'git@gitlab\.com:[^/]+/[^/]+\.git',
+        r'https?://.*\.git$',
+    ]
+    return any(re.match(pattern, url) for pattern in git_patterns)
+
+
+def _parse_gitingest_url(url: str) -> Optional[Tuple[str, Optional[str], Optional[str]]]:
+    """Parse a GitIngest URL to extract repository info.
+
+    Returns (repo_url, branch, subpath) or None if not a GitIngest URL.
+    """
+    if 'gitingest.com' not in url:
+        return None
+
+    parsed = urlparse(url)
+    if not parsed.query:
+        return None
+
+    query_params = parse_qs(parsed.query)
+    repo_url = query_params.get('url', [None])[0]
+    branch = query_params.get('branch', [None])[0]
+    subpath = query_params.get('subpath', [None])[0]
+
+    if repo_url:
+        return repo_url, branch, subpath
+    return None
+
+
+def _normalize_repo_url(url: str) -> str:
+    """Normalize a repository URL for cloning."""
+    # Convert SSH URLs to HTTPS for easier cloning
+    if url.startswith('git@'):
+        # git@github.com:owner/repo.git -> https://github.com/owner/repo.git
+        ssh_pattern = r'git@([^:]+):([^/]+)/([^/]+)(?:\.git)?'
+        match = re.match(ssh_pattern, url)
+        if match:
+            host, owner, repo = match.groups()
+            return f'https://{host}/{owner}/{repo}.git'
+
+    # Ensure .git suffix for HTTPS URLs
+    if not url.endswith('.git') and _is_git_url(url):
+        return url + '.git'
+
+    return url
+
+
+def _clone_repository(
+    repo_url: str, target_dir: str, branch: Optional[str] = None, shallow: bool = True
+) -> bool:
+    """Clone a repository to the target directory.
+
+    Returns True if successful, False otherwise.
+    """
+    try:
+        cmd = ['git', 'clone']
+        if shallow:
+            cmd.extend(['--depth', '1'])
+        if branch:
+            cmd.extend(['--branch', branch])
+        cmd.extend([repo_url, target_dir])
+
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=300
+        )
+        return result.returncode == 0
+    except (
+        subprocess.TimeoutExpired, subprocess.SubprocessError, FileNotFoundError
+    ):
+        return False
+
+
+def fetch_repository(url_or_path: str, target_dir: Optional[str] = None) -> Optional[str]:
+    """Fetch a repository from a URL or return a local path.
+
+    Handles GitIngest URLs, direct Git URLs, and local paths.
+
+    Parameters
+    ----------
+    url_or_path : str
+        GitIngest URL, Git repository URL, or local file path.
+    target_dir : str, optional
+        Directory to clone into. If None, uses a temporary directory.
+
+    Returns
+    -------
+    str or None
+        Path to the repository directory, or None if fetch failed.
+    """
+    # If it's a local path, return as-is
+    if os.path.exists(url_or_path):
+        return os.path.abspath(url_or_path)
+
+    # Parse GitIngest URL
+    gitingest_info = _parse_gitingest_url(url_or_path)
+    if gitingest_info:
+        repo_url, branch, subpath = gitingest_info
+        if not repo_url:
+            return None
+    else:
+        # Check if it's a direct Git URL
+        if _is_git_url(url_or_path):
+            repo_url = url_or_path
+            branch = None
+            subpath = None
+        else:
+            return None
+
+    # Normalize the repository URL
+    repo_url = _normalize_repo_url(repo_url)
+
+    # Create target directory
+    if target_dir is None:
+        target_dir = tempfile.mkdtemp(prefix='ttmm_repo_')
+    else:
+        os.makedirs(target_dir, exist_ok=True)
+
+    # Clone the repository
+    clone_success = _clone_repository(repo_url, target_dir, branch)
+    if not clone_success:
+        if target_dir.startswith(tempfile.gettempdir()):
+            shutil.rmtree(target_dir, ignore_errors=True)
+        return None
+
+    # Handle subpath if specified
+    if subpath:
+        subpath_full = os.path.join(target_dir, subpath)
+        if os.path.exists(subpath_full):
+            return subpath_full
+
+    return target_dir
+
+
+def cleanup_temp_repo(repo_path: str) -> None:
+    """Clean up a temporary repository directory."""
+    if repo_path and repo_path.startswith(tempfile.gettempdir()):
+        shutil.rmtree(repo_path, ignore_errors=True)
+
+
+def get_repo_info(repo_path: str) -> dict:
+    """Extract basic information about a repository.
+
+    Returns a dictionary with repository metadata.
+    """
+    info = {
+        'path': repo_path,
+        'is_git': False,
+        'remote_url': None,
+        'branch': None,
+        'commit': None,
+    }
+
+    # Check if it's a git repository
+    git_dir = os.path.join(repo_path, '.git')
+    if os.path.exists(git_dir):
+        info['is_git'] = True
+
+        try:
+            # Get remote URL
+            result = subprocess.run(
+                ['git', 'remote', 'get-url', 'origin'],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            if result.returncode == 0:
+                info['remote_url'] = result.stdout.strip()
+
+            # Get current branch
+            result = subprocess.run(
+                ['git', 'branch', '--show-current'],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            if result.returncode == 0:
+                info['branch'] = result.stdout.strip()
+
+            # Get current commit
+            result = subprocess.run(
+                ['git', 'rev-parse', 'HEAD'],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            if result.returncode == 0:
+                info['commit'] = result.stdout.strip()[:8]
+
+        except (subprocess.SubprocessError, FileNotFoundError):
+            pass
+
+    return info