codegraph-nav 0.1.0__py3-none-any.whl

codegraph_nav/colors.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Terminal color utilities for Code Navigator.
+
+Provides ANSI color support with automatic detection of terminal capabilities.
+Respects the NO_COLOR environment variable (https://no-color.org/).
+
+Example:
+    >>> from codegraph_nav.colors import Colors
+    >>> c = Colors()
+    >>> print(c.green("Success!"))
+    >>> print(c.cyan("Line 42"))
+"""
+
+import os
+import sys
+import threading
+
+__version__ = "0.1.0"
+
+
+class Colors:
+    """ANSI color utility class with automatic terminal detection.
+
+    Attributes:
+        enabled: Whether colors are enabled (auto-detected or manually set).
+
+    Example:
+        >>> c = Colors()
+        >>> print(c.green("found") + " in " + c.cyan("file.py"))
+    """
+
+    # ANSI escape codes
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+
+    # Foreground colors
+    BLACK = "\033[30m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+
+    # Bright foreground colors
+    BRIGHT_BLACK = "\033[90m"
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+    def __init__(self, enabled: bool | None = None):
+        """Initialize Colors with optional override.
+
+        Args:
+            enabled: Force colors on/off. If None, auto-detect.
+        """
+        if enabled is not None:
+            self.enabled = enabled
+        else:
+            self.enabled = self._should_enable_colors()
+
+    def _should_enable_colors(self) -> bool:
+        """Determine if colors should be enabled based on environment."""
+        # Respect NO_COLOR environment variable (https://no-color.org/)
+        if os.environ.get("NO_COLOR"):
+            return False
+
+        # Check FORCE_COLOR for explicit enable
+        if os.environ.get("FORCE_COLOR"):
+            return True
+
+        # Check if stdout is a TTY
+        if not hasattr(sys.stdout, "isatty") or not sys.stdout.isatty():
+            return False
+
+        # Check TERM environment variable
+        term = os.environ.get("TERM", "")
+        if term == "dumb":
+            return False
+
+        # Windows: check for Windows Terminal or newer cmd
+        if sys.platform == "win32":
+            # Windows Terminal and modern Windows 10+ support ANSI
+            return (
+                os.environ.get("WT_SESSION")  # Windows Terminal
+                or os.environ.get("ANSICON")  # ANSICON
+                or "256color" in term
+                or os.environ.get("TERM_PROGRAM") == "vscode"
+            )
+
+        return True
+
+    def _colorize(self, text: str, color: str) -> str:
+        """Apply color to text if colors are enabled."""
+        if not self.enabled:
+            return text
+        return f"{color}{text}{self.RESET}"
+
+    # Basic colors
+    def red(self, text: str) -> str:
+        """Red text (errors, warnings)."""
+        return self._colorize(text, self.RED)
+
+    def green(self, text: str) -> str:
+        """Green text (success, found items)."""
+        return self._colorize(text, self.GREEN)
+
+    def yellow(self, text: str) -> str:
+        """Yellow text (context, warnings)."""
+        return self._colorize(text, self.YELLOW)
+
+    def blue(self, text: str) -> str:
+        """Blue text."""
+        return self._colorize(text, self.BLUE)
+
+    def magenta(self, text: str) -> str:
+        """Magenta text (types, decorators)."""
+        return self._colorize(text, self.MAGENTA)
+
+    def cyan(self, text: str) -> str:
+        """Cyan text (line numbers, file paths)."""
+        return self._colorize(text, self.CYAN)
+
+    def white(self, text: str) -> str:
+        """White text."""
+        return self._colorize(text, self.WHITE)
+
+    # Bright colors
+    def bright_green(self, text: str) -> str:
+        """Bright green text."""
+        return self._colorize(text, self.BRIGHT_GREEN)
+
+    def bright_yellow(self, text: str) -> str:
+        """Bright yellow text."""
+        return self._colorize(text, self.BRIGHT_YELLOW)
+
+    def bright_cyan(self, text: str) -> str:
+        """Bright cyan text."""
+        return self._colorize(text, self.BRIGHT_CYAN)
+
+    # Styles
+    def bold(self, text: str) -> str:
+        """Bold text."""
+        return self._colorize(text, self.BOLD)
+
+    def dim(self, text: str) -> str:
+        """Dim text (less prominent)."""
+        return self._colorize(text, self.DIM)
+
+    # Combined styles
+    def success(self, text: str) -> str:
+        """Success message (bold green)."""
+        if not self.enabled:
+            return text
+        return f"{self.BOLD}{self.GREEN}{text}{self.RESET}"
+
+    def error(self, text: str) -> str:
+        """Error message (bold red)."""
+        if not self.enabled:
+            return text
+        return f"{self.BOLD}{self.RED}{text}{self.RESET}"
+
+    def warning(self, text: str) -> str:
+        """Warning message (yellow)."""
+        return self.yellow(text)
+
+    def info(self, text: str) -> str:
+        """Info message (cyan)."""
+        return self.cyan(text)
+
+
+# Global instance for convenience (thread-safe singleton)
+_colors = None
+_colors_lock = threading.Lock()
+
+
+def get_colors(no_color: bool = False) -> Colors:
+    """Get a Colors instance, optionally disabling colors.
+
+    Thread-safe singleton pattern: the global instance is created once
+    and reused across all threads.
+
+    Args:
+        no_color: If True, return a new disabled Colors instance
+                  (not cached, allows per-call override).
+
+    Returns:
+        Colors instance configured appropriately.
+    """
+    global _colors
+
+    # For no_color=True, always return a fresh disabled instance
+    # This allows callers to override colors on a per-call basis
+    if no_color:
+        return Colors(enabled=False)
+
+    # Double-checked locking pattern for thread-safe lazy initialization
+    if _colors is None:
+        with _colors_lock:
+            # Check again inside the lock (another thread may have initialized)
+            if _colors is None:
+                _colors = Colors()
+    return _colors

codegraph_nav/completions.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""Shell completion scripts generator for Code Navigator.
+
+Generates bash and zsh completion scripts that provide autocompletion
+for codegraph-nav commands and symbol names from the code map.
+
+Example:
+    # Generate bash completion
+    $ codegraph-nav completion bash > ~/.bash_completion.d/codegraph-nav
+
+    # Generate zsh completion
+    $ codegraph-nav completion zsh > ~/.zfunc/_codegraph_nav
+
+    # Source directly (bash)
+    $ eval "$(codegraph-nav completion bash)"
+"""
+
+import json
+import sys
+
+__version__ = "0.1.0"
+
+BASH_COMPLETION_TEMPLATE = """# Bash completion for codegraph-nav
+# Generated by codegraph-nav
+
+_codegraph_completions() {
+    local cur prev words cword
+    _init_completion || return
+
+    local commands="map search read stats completion watch export"
+    local map_opts="-o --output -i --ignore --incremental --git-only --use-gitignore --compact --no-color -h --help"
+    local search_opts="-m --map -t --type -f --file --files --structure --deps --stats --check-stale --warn-stale --since-commit -l --limit --no-fuzzy --compact -o --output --no-color -h --help"
+    local read_opts="-c --context --symbol -r --root --compact -o --output --no-color -h --help"
+    local export_opts="-m --map -f --format -o --output --no-color -h --help"
+    local watch_opts="-o --output -i --ignore --git-only --use-gitignore --compact --no-color --debounce -h --help"
+    local completion_opts="bash zsh"
+    local types="function class method interface struct trait enum type"
+
+    case "${cword}" in
+        1)
+            COMPREPLY=($(compgen -W "${commands}" -- "${cur}"))
+            return
+            ;;
+    esac
+
+    case "${words[1]}" in
+        map)
+            if [[ "${cur}" == -* ]]; then
+                COMPREPLY=($(compgen -W "${map_opts}" -- "${cur}"))
+            else
+                _filedir -d
+            fi
+            ;;
+        search)
+            case "${prev}" in
+                -t|--type)
+                    COMPREPLY=($(compgen -W "${types}" -- "${cur}"))
+                    ;;
+                -m|--map)
+                    _filedir json
+                    ;;
+                -o|--output)
+                    COMPREPLY=($(compgen -W "json table" -- "${cur}"))
+                    ;;
+                *)
+                    if [[ "${cur}" == -* ]]; then
+                        COMPREPLY=($(compgen -W "${search_opts}" -- "${cur}"))
+                    else
+                        # Try to complete symbol names from codegraph-nav
+                        _codegraph_complete_symbols
+                    fi
+                    ;;
+            esac
+            ;;
+        read)
+            if [[ "${cur}" == -* ]]; then
+                COMPREPLY=($(compgen -W "${read_opts}" -- "${cur}"))
+            else
+                _filedir
+            fi
+            ;;
+        stats)
+            if [[ "${cur}" == -* ]]; then
+                COMPREPLY=($(compgen -W "-m --map --compact -o --output --no-color -h --help" -- "${cur}"))
+            fi
+            ;;
+        completion)
+            COMPREPLY=($(compgen -W "${completion_opts}" -- "${cur}"))
+            ;;
+        watch)
+            if [[ "${cur}" == -* ]]; then
+                COMPREPLY=($(compgen -W "${watch_opts}" -- "${cur}"))
+            else
+                _filedir -d
+            fi
+            ;;
+        export)
+            case "${prev}" in
+                -f|--format)
+                    COMPREPLY=($(compgen -W "markdown html graphviz" -- "${cur}"))
+                    ;;
+                -m|--map)
+                    _filedir json
+                    ;;
+                -o|--output)
+                    _filedir
+                    ;;
+                *)
+                    if [[ "${cur}" == -* ]]; then
+                        COMPREPLY=($(compgen -W "${export_opts}" -- "${cur}"))
+                    fi
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_codegraph_complete_symbols() {
+    # Try to read symbols from .codegraph.json in current directory
+    local mapfile=".codegraph.json"
+    if [[ -f "${mapfile}" ]]; then
+        local symbols=$(python3 -c "
+import json
+try:
+    with open('${mapfile}') as f:
+        data = json.load(f)
+    symbols = set()
+    for file_info in data.get('files', {}).values():
+        for sym in file_info.get('symbols', []):
+            symbols.add(sym['name'])
+    print(' '.join(sorted(symbols)[:50]))
+except (OSError, json.JSONDecodeError, KeyError, TypeError):
+    pass
+" 2>/dev/null)
+        COMPREPLY=($(compgen -W "${symbols}" -- "${cur}"))
+    fi
+}
+
+complete -F _codegraph_completions codegraph-nav
+"""
+
+ZSH_COMPLETION_TEMPLATE = """#compdef codegraph-nav
+# Zsh completion for codegraph-nav
+# Generated by codegraph-nav
+
+_codegraph_nav() {
+    local -a commands
+    commands=(
+        'map:Generate a code map of a codebase'
+        'search:Search for symbols in the code map'
+        'read:Read specific lines from files'
+        'stats:Show codebase statistics'
+        'completion:Generate shell completion script'
+        'watch:Watch for changes and auto-update map'
+        'export:Export code map to different formats'
+    )
+
+    local -a types
+    types=(function class method interface struct trait enum type)
+
+    local -a formats
+    formats=(markdown html graphviz)
+
+    _arguments -C \\
+        '1:command:->command' \\
+        '*::arg:->args'
+
+    case "$state" in
+        command)
+            _describe -t commands 'codegraph-nav command' commands
+            ;;
+        args)
+            case "$words[1]" in
+                map)
+                    _arguments \\
+                        '1:path:_files -/' \\
+                        '-o[Output file path]:file:_files' \\
+                        '--output[Output file path]:file:_files' \\
+                        '*-i[Patterns to ignore]:pattern:' \\
+                        '*--ignore[Patterns to ignore]:pattern:' \\
+                        '--incremental[Only update changed files]' \\
+                        '--git-only[Only scan git-tracked files]' \\
+                        '--use-gitignore[Use .gitignore patterns]' \\
+                        '--compact[Output compact JSON]' \\
+                        '--no-color[Disable colored output]' \\
+                        '(-h --help)'{-h,--help}'[Show help]'
+                    ;;
+                search)
+                    _arguments \\
+                        '1:query:_codegraph_symbols' \\
+                        '-m[Path to code map]:file:_files -g "*.json"' \\
+                        '--map[Path to code map]:file:_files -g "*.json"' \\
+                        '-t[Filter by symbol type]:type:(${types})' \\
+                        '--type[Filter by symbol type]:type:(${types})' \\
+                        '-f[Filter by file pattern]:pattern:' \\
+                        '--file[Filter by file pattern]:pattern:' \\
+                        '--files[Search for files instead of symbols]' \\
+                        '--structure[Show structure of a file]:file:_files' \\
+                        '--deps[Show dependencies of a symbol]:symbol:_codegraph_symbols' \\
+                        '--stats[Show codebase statistics]' \\
+                        '--check-stale[Check if files have changed]' \\
+                        '--warn-stale[Warn if files are stale]' \\
+                        '--since-commit[Show changes since commit]:commit:' \\
+                        '-l[Maximum results]:number:' \\
+                        '--limit[Maximum results]:number:' \\
+                        '--no-fuzzy[Disable fuzzy matching]' \\
+                        '--compact[Output compact JSON]' \\
+                        '-o[Output format]:format:(json table)' \\
+                        '--output[Output format]:format:(json table)' \\
+                        '--no-color[Disable colored output]' \\
+                        '(-h --help)'{-h,--help}'[Show help]'
+                    ;;
+                read)
+                    _arguments \\
+                        '1:file:_files' \\
+                        '2:lines:' \\
+                        '-c[Context lines]:number:' \\
+                        '--context[Context lines]:number:' \\
+                        '--symbol[Read entire symbol]' \\
+                        '-r[Root path]:path:_files -/' \\
+                        '--root[Root path]:path:_files -/' \\
+                        '--compact[Output compact JSON]' \\
+                        '-o[Output format]:format:(json code)' \\
+                        '--output[Output format]:format:(json code)' \\
+                        '--no-color[Disable colored output]' \\
+                        '(-h --help)'{-h,--help}'[Show help]'
+                    ;;
+                stats)
+                    _arguments \\
+                        '-m[Path to code map]:file:_files -g "*.json"' \\
+                        '--map[Path to code map]:file:_files -g "*.json"' \\
+                        '--compact[Output compact JSON]' \\
+                        '-o[Output format]:format:(json table)' \\
+                        '--output[Output format]:format:(json table)' \\
+                        '--no-color[Disable colored output]' \\
+                        '(-h --help)'{-h,--help}'[Show help]'
+                    ;;
+                completion)
+                    _arguments '1:shell:(bash zsh)'
+                    ;;
+                watch)
+                    _arguments \\
+                        '1:path:_files -/' \\
+                        '-o[Output file path]:file:_files' \\
+                        '--output[Output file path]:file:_files' \\
+                        '*-i[Patterns to ignore]:pattern:' \\
+                        '*--ignore[Patterns to ignore]:pattern:' \\
+                        '--git-only[Only scan git-tracked files]' \\
+                        '--use-gitignore[Use .gitignore patterns]' \\
+                        '--compact[Output compact JSON]' \\
+                        '--no-color[Disable colored output]' \\
+                        '--debounce[Debounce time in seconds]:seconds:' \\
+                        '(-h --help)'{-h,--help}'[Show help]'
+                    ;;
+                export)
+                    _arguments \\
+                        '-m[Path to code map]:file:_files -g "*.json"' \\
+                        '--map[Path to code map]:file:_files -g "*.json"' \\
+                        '-f[Export format]:format:(${formats})' \\
+                        '--format[Export format]:format:(${formats})' \\
+                        '-o[Output file]:file:_files' \\
+                        '--output[Output file]:file:_files' \\
+                        '--no-color[Disable colored output]' \\
+                        '(-h --help)'{-h,--help}'[Show help]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_codegraph_symbols() {
+    local mapfile=".codegraph.json"
+    if [[ -f "$mapfile" ]]; then
+        local -a symbols
+        symbols=(${(f)"$(python3 -c "
+import json
+try:
+    with open('$mapfile') as f:
+        data = json.load(f)
+    symbols = set()
+    for file_info in data.get('files', {}).values():
+        for sym in file_info.get('symbols', []):
+            symbols.add(sym['name'])
+    print('\\n'.join(sorted(symbols)[:100]))
+except (OSError, json.JSONDecodeError, KeyError, TypeError):
+    pass
+" 2>/dev/null)"})
+        _describe -t symbols 'symbol' symbols
+    fi
+}
+
+_codegraph_nav "$@"
+"""
+
+
+def generate_bash_completion() -> str:
+    """Generate bash completion script.
+
+    Returns:
+        Bash completion script as a string.
+    """
+    return BASH_COMPLETION_TEMPLATE
+
+
+def generate_zsh_completion() -> str:
+    """Generate zsh completion script.
+
+    Returns:
+        Zsh completion script as a string.
+    """
+    return ZSH_COMPLETION_TEMPLATE
+
+
+def get_symbols_from_map(map_path: str, limit: int = 100) -> list[str]:
+    """Extract symbol names from a code map for completion.
+
+    Args:
+        map_path: Path to the .codegraph.json file.
+        limit: Maximum number of symbols to return.
+
+    Returns:
+        List of symbol names.
+    """
+    try:
+        with open(map_path, encoding="utf-8") as f:
+            data = json.load(f)
+
+        symbols = set()
+        for file_info in data.get("files", {}).values():
+            for sym in file_info.get("symbols", []):
+                symbols.add(sym["name"])
+                if len(symbols) >= limit:
+                    break
+            if len(symbols) >= limit:
+                break
+
+        return sorted(symbols)[:limit]
+    except Exception:
+        return []
+
+
+def run_completion(shell: str) -> None:
+    """Generate and print completion script for the specified shell.
+
+    Args:
+        shell: Shell type ('bash' or 'zsh').
+    """
+    if shell == "bash":
+        print(generate_bash_completion())
+    elif shell == "zsh":
+        print(generate_zsh_completion())
+    else:
+        print(f"Unknown shell: {shell}. Supported: bash, zsh", file=sys.stderr)
+        sys.exit(1)