reveal-cli 0.8.0__py3-none-any.whl

reveal/base.py

@@ -0,0 +1,267 @@
+"""Base analyzer class for reveal - clean, simple design."""
+
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+import hashlib
+
+
+class FileAnalyzer:
+    """Base class for all file analyzers.
+
+    Provides automatic functionality:
+    - File reading with encoding detection
+    - Metadata extraction
+    - Line number formatting
+    - Source extraction helpers
+
+    Subclasses only need to implement:
+    - get_structure(): Return dict of file elements
+    - extract_element(type, name): Extract specific element (optional)
+    """
+
+    def __init__(self, path: str):
+        self.path = Path(path)
+        self.lines = self._read_file()
+        self.content = '\n'.join(self.lines)
+
+    def _read_file(self) -> List[str]:
+        """Read file with automatic encoding detection."""
+        encodings = ['utf-8', 'utf-8-sig', 'latin-1', 'cp1252']
+
+        for encoding in encodings:
+            try:
+                with open(self.path, 'r', encoding=encoding) as f:
+                    return f.read().splitlines()
+            except (UnicodeDecodeError, LookupError):
+                continue
+
+        # Last resort: read as binary and decode with errors='replace'
+        with open(self.path, 'rb') as f:
+            content = f.read().decode('utf-8', errors='replace')
+            return content.splitlines()
+
+    def get_metadata(self) -> Dict[str, Any]:
+        """Return file metadata.
+
+        Automatic - works for all file types.
+        """
+        stat = os.stat(self.path)
+
+        return {
+            'path': str(self.path),
+            'name': self.path.name,
+            'size': stat.st_size,
+            'size_human': self._format_size(stat.st_size),
+            'lines': len(self.lines),
+            'encoding': self._detect_encoding(),
+        }
+
+    def get_structure(self) -> Dict[str, List[Dict[str, Any]]]:
+        """Return file structure (imports, functions, classes, etc.).
+
+        Override in subclasses for custom extraction.
+        Default: Returns empty structure.
+        """
+        return {}
+
+    def extract_element(self, element_type: str, name: str) -> Optional[Dict[str, Any]]:
+        """Extract a specific element from the file.
+
+        Args:
+            element_type: Type of element ('function', 'class', 'section', etc.)
+            name: Name of the element
+
+        Returns:
+            Dict with 'line_start', 'line_end', 'source', etc. or None
+
+        Override in subclasses for semantic extraction.
+        Default: Falls back to grep-based search.
+        """
+        # Default: simple grep-based extraction
+        return self._grep_extract(name)
+
+    def _grep_extract(self, name: str) -> Optional[Dict[str, Any]]:
+        """Fallback: Extract by grepping for name."""
+        for i, line in enumerate(self.lines, 1):
+            if name in line:
+                # Found it - extract this line and a few after
+                line_start = i
+                line_end = min(i + 20, len(self.lines))  # Up to 20 lines
+
+                return {
+                    'name': name,
+                    'line_start': line_start,
+                    'line_end': line_end,
+                    'source': '\n'.join(self.lines[line_start-1:line_end]),
+                }
+        return None
+
+    def format_with_lines(self, source: str, start_line: int) -> str:
+        """Format source code with line numbers.
+
+        Args:
+            source: Source code to format
+            start_line: Starting line number
+
+        Returns:
+            Formatted string with line numbers
+        """
+        lines = source.split('\n')
+        result = []
+
+        for i, line in enumerate(lines):
+            line_num = start_line + i
+            result.append(f"   {line_num:4d}  {line}")
+
+        return '\n'.join(result)
+
+    def _format_size(self, size: int) -> str:
+        """Format file size in human-readable form."""
+        for unit in ['B', 'KB', 'MB', 'GB']:
+            if size < 1024.0:
+                return f"{size:.1f} {unit}"
+            size /= 1024.0
+        return f"{size:.1f} TB"
+
+    def _detect_encoding(self) -> str:
+        """Detect file encoding."""
+        # Simple heuristic for now
+        try:
+            self.content.encode('ascii')
+            return 'ASCII'
+        except UnicodeEncodeError:
+            return 'UTF-8'
+
+    def get_directory_entry(self) -> Dict[str, Any]:
+        """Return info for directory listing.
+
+        Automatic - works for all file types.
+        """
+        meta = self.get_metadata()
+        file_type = self.__class__.__name__.replace('Analyzer', '')
+
+        return {
+            'path': str(self.path),
+            'name': self.path.name,
+            'size': meta['size_human'],
+            'lines': meta['lines'],
+            'type': file_type,
+        }
+
+
+# Registry for file type analyzers
+_ANALYZER_REGISTRY: Dict[str, type] = {}
+
+
+def register(*extensions, name: str = '', icon: str = '📄'):
+    """Decorator to register an analyzer for file extensions.
+
+    Usage:
+        @register('.py', name='Python', icon='🐍')
+        class PythonAnalyzer(FileAnalyzer):
+            ...
+
+    Args:
+        extensions: File extensions to register (e.g., '.py', '.rs')
+        name: Display name for this file type
+        icon: Emoji icon for this file type
+    """
+    def decorator(cls):
+        for ext in extensions:
+            _ANALYZER_REGISTRY[ext.lower()] = cls
+
+        # Store metadata on class
+        cls.type_name = name or cls.__name__.replace('Analyzer', '')
+        cls.icon = icon
+
+        return cls
+
+    return decorator
+
+
+def get_analyzer(path: str) -> Optional[type]:
+    """Get analyzer class for a file path.
+
+    Args:
+        path: File path
+
+    Returns:
+        Analyzer class or None if not found
+    """
+    file_path = Path(path)
+    ext = file_path.suffix.lower()
+
+    # If we have an extension, use it
+    if ext and ext in _ANALYZER_REGISTRY:
+        return _ANALYZER_REGISTRY.get(ext)
+
+    # No extension or not found - check special filenames (Dockerfile, Makefile)
+    filename = file_path.name.lower()
+    if filename in _ANALYZER_REGISTRY:
+        return _ANALYZER_REGISTRY.get(filename)
+
+    # Still no match - check shebang for extensionless scripts
+    if not ext or ext not in _ANALYZER_REGISTRY:
+        shebang_ext = _detect_shebang(path)
+        if shebang_ext:
+            return _ANALYZER_REGISTRY.get(shebang_ext)
+
+    return None
+
+
+def _detect_shebang(path: str) -> Optional[str]:
+    """Detect file type from shebang line.
+
+    Args:
+        path: File path
+
+    Returns:
+        Extension to use (e.g., '.py', '.sh') or None
+    """
+    try:
+        with open(path, 'rb') as f:
+            first_line = f.readline()
+
+        # Decode with error handling
+        try:
+            shebang = first_line.decode('utf-8', errors='ignore').strip()
+        except:
+            return None
+
+        if not shebang.startswith('#!'):
+            return None
+
+        # Map shebangs to extensions
+        shebang_lower = shebang.lower()
+
+        # Python
+        if 'python' in shebang_lower:
+            return '.py'
+
+        # Shell scripts (bash, sh, zsh)
+        if any(shell in shebang_lower for shell in ['bash', '/sh', 'zsh']):
+            return '.sh'
+
+        return None
+
+    except (IOError, OSError):
+        return None
+
+
+def get_all_analyzers() -> Dict[str, Dict[str, Any]]:
+    """Get all registered analyzers with metadata.
+
+    Returns:
+        Dict mapping extension to analyzer metadata
+        e.g., {'.py': {'name': 'Python', 'icon': '🐍', 'class': PythonAnalyzer}}
+    """
+    result = {}
+    for ext, cls in _ANALYZER_REGISTRY.items():
+        result[ext] = {
+            'extension': ext,
+            'name': getattr(cls, 'type_name', cls.__name__.replace('Analyzer', '')),
+            'icon': getattr(cls, 'icon', '📄'),
+            'class': cls,
+        }
+    return result

reveal/main.py

@@ -0,0 +1,355 @@
+"""Clean, simple CLI for reveal."""
+
+import sys
+import os
+import argparse
+from pathlib import Path
+from typing import Optional
+from datetime import datetime, timedelta
+from .base import get_analyzer, get_all_analyzers, FileAnalyzer
+from .tree_view import show_directory_tree
+from . import __version__
+
+
+def check_for_updates():
+    """Check PyPI for newer version (once per day, non-blocking).
+
+    - Checks at most once per day (cached in ~/.config/reveal/last_update_check)
+    - 1-second timeout (doesn't slow down CLI)
+    - Fails silently (no errors shown to user)
+    - Opt-out: Set REVEAL_NO_UPDATE_CHECK=1 environment variable
+    """
+    # Opt-out check
+    if os.environ.get('REVEAL_NO_UPDATE_CHECK'):
+        return
+
+    try:
+        # Setup cache directory
+        cache_dir = Path.home() / '.config' / 'reveal'
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_file = cache_dir / 'last_update_check'
+
+        # Check if we should update (once per day)
+        if cache_file.exists():
+            last_check_str = cache_file.read_text().strip()
+            try:
+                last_check = datetime.fromisoformat(last_check_str)
+                if datetime.now() - last_check < timedelta(days=1):
+                    return  # Checked recently, skip
+            except (ValueError, OSError):
+                pass  # Invalid cache, continue with check
+
+        # Check PyPI (using urllib to avoid new dependencies)
+        import urllib.request
+        import json
+
+        req = urllib.request.Request(
+            'https://pypi.org/pypi/reveal-cli/json',
+            headers={'User-Agent': f'reveal-cli/{__version__}'}
+        )
+
+        with urllib.request.urlopen(req, timeout=1) as response:
+            data = json.loads(response.read().decode('utf-8'))
+            latest_version = data['info']['version']
+
+        # Update cache file
+        cache_file.write_text(datetime.now().isoformat())
+
+        # Compare versions (simple string comparison works for semver)
+        if latest_version != __version__:
+            # Parse versions for proper comparison
+            def parse_version(v):
+                return tuple(map(int, v.split('.')))
+
+            try:
+                if parse_version(latest_version) > parse_version(__version__):
+                    print(f"⚠️  Update available: reveal {latest_version} (you have {__version__})")
+                    print(f"💡 Update: pip install --upgrade reveal-cli\n")
+            except (ValueError, AttributeError):
+                pass  # Version comparison failed, ignore
+
+    except Exception:
+        # Fail silently - don't interrupt user's workflow
+        pass
+
+
+def main():
+    """Main CLI entry point."""
+    # Fix Windows console encoding for emoji/unicode support
+    if sys.platform == 'win32':
+        # Set environment variable for subprocess compatibility
+        os.environ.setdefault('PYTHONIOENCODING', 'utf-8')
+        # Reconfigure stdout/stderr to use UTF-8 with error handling
+        if hasattr(sys.stdout, 'reconfigure'):
+            sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+        if hasattr(sys.stderr, 'reconfigure'):
+            sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+
+    _main_impl()
+
+
+def _main_impl():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description='Reveal: Explore code semantically - The simplest way to understand code',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  # Directory exploration
+  reveal src/                    # Show directory tree
+  reveal src/ --depth=5          # Deeper tree view
+
+  # File structure
+  reveal app.py                  # Show structure (imports, functions, classes)
+  reveal app.py --meta           # Show metadata (size, lines, encoding)
+  reveal player.gd               # GDScript support (Godot engine)
+
+  # Element extraction
+  reveal app.py load_config      # Extract specific function
+  reveal app.py Database         # Extract class definition
+
+  # Output formats
+  reveal app.py --format=json    # JSON output for scripting
+  reveal app.py --format=grep    # Grep-compatible format
+
+  # Discovery
+  reveal --list-supported        # Show all supported file types
+  reveal --version               # Show version
+
+Perfect filename:line integration - works with vim, git, grep, sed, awk!
+        '''
+    )
+
+    parser.add_argument('path', nargs='?', help='File or directory to reveal')
+    parser.add_argument('element', nargs='?', help='Element to extract (function, class, etc.)')
+
+    # Optional flags
+    parser.add_argument('--version', action='version', version=f'reveal {__version__}')
+    parser.add_argument('--list-supported', '-l', action='store_true',
+                        help='List all supported file types')
+    parser.add_argument('--meta', action='store_true', help='Show metadata only')
+    parser.add_argument('--format', choices=['text', 'json', 'grep'], default='text',
+                        help='Output format (text, json, grep)')
+    parser.add_argument('--depth', type=int, default=3, help='Directory tree depth (default: 3)')
+
+    args = parser.parse_args()
+
+    # Check for updates (once per day, non-blocking, opt-out available)
+    check_for_updates()
+
+    # Handle --list-supported
+    if args.list_supported:
+        list_supported_types()
+        sys.exit(0)
+
+    # Path is required if not using --list-supported
+    if not args.path:
+        parser.print_help()
+        sys.exit(1)
+
+    # Check if path exists
+    path = Path(args.path)
+    if not path.exists():
+        print(f"Error: {args.path} not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Route based on path type
+    if path.is_dir():
+        # Directory → show tree
+        output = show_directory_tree(str(path), depth=args.depth)
+        print(output)
+
+    elif path.is_file():
+        # File → show structure or extract element
+        handle_file(str(path), args.element, args.meta, args.format)
+
+    else:
+        print(f"Error: {args.path} is neither file nor directory", file=sys.stderr)
+        sys.exit(1)
+
+
+def list_supported_types():
+    """List all supported file types."""
+    analyzers = get_all_analyzers()
+
+    if not analyzers:
+        print("No file types registered")
+        return
+
+    print(f"📋 Reveal v{__version__} - Supported File Types\n")
+
+    # Sort by name for nice display
+    sorted_analyzers = sorted(analyzers.items(), key=lambda x: x[1]['name'])
+
+    for ext, info in sorted_analyzers:
+        icon = info['icon']
+        name = info['name']
+        print(f"  {icon}  {name:15s} ({ext})")
+
+    print(f"\n✨ Total: {len(analyzers)} file types supported")
+    print(f"\n💡 Use 'reveal <file>' to explore any supported file")
+    print(f"💡 Use 'reveal --help' for usage examples")
+
+
+def handle_file(path: str, element: Optional[str], show_meta: bool, output_format: str):
+    """Handle file analysis.
+
+    Args:
+        path: File path
+        element: Optional element to extract
+        show_meta: Whether to show metadata only
+        output_format: Output format ('text', 'json', 'grep')
+    """
+    # Get analyzer
+    analyzer_class = get_analyzer(path)
+    if not analyzer_class:
+        ext = Path(path).suffix or '(no extension)'
+        print(f"Error: No analyzer found for {path} ({ext})", file=sys.stderr)
+        print(f"\n💡 Hint: File type '{ext}' is not supported yet", file=sys.stderr)
+        print(f"💡 Run 'reveal --list-supported' to see all supported file types", file=sys.stderr)
+        print(f"💡 Visit https://github.com/scottsen/reveal to request new file types", file=sys.stderr)
+        sys.exit(1)
+
+    analyzer = analyzer_class(path)
+
+    # Show metadata only?
+    if show_meta:
+        show_metadata(analyzer, output_format)
+        return
+
+    # Extract specific element?
+    if element:
+        extract_element(analyzer, element, output_format)
+        return
+
+    # Default: show structure
+    show_structure(analyzer, output_format)
+
+
+def show_metadata(analyzer: FileAnalyzer, output_format: str):
+    """Show file metadata."""
+    meta = analyzer.get_metadata()
+
+    if output_format == 'json':
+        import json
+        print(json.dumps(meta, indent=2))
+    else:
+        print(f"📄 {meta['name']}\n")
+        print(f"Path:     {meta['path']}")
+        print(f"Size:     {meta['size_human']}")
+        print(f"Lines:    {meta['lines']}")
+        print(f"Encoding: {meta['encoding']}")
+        print(f"\n→ reveal {meta['path']}")
+
+
+def show_structure(analyzer: FileAnalyzer, output_format: str):
+    """Show file structure."""
+    structure = analyzer.get_structure()
+    path = analyzer.path
+
+    if output_format == 'json':
+        import json
+        print(json.dumps(structure, indent=2))
+        return
+
+    if not structure:
+        print(f"📄 {path.name}\n")
+        print("No structure available for this file type")
+        return
+
+    print(f"📄 {path.name}\n")
+
+    # Show each category
+    for category, items in structure.items():
+        if not items:
+            continue
+
+        # Format category name (e.g., 'functions' → 'Functions')
+        category_name = category.capitalize()
+        print(f"{category_name} ({len(items)}):")
+
+        for item in items:
+            line = item.get('line', '?')
+            name = item.get('name', '')
+            signature = item.get('signature', '')
+            content = item.get('content', '')
+
+            # Format based on what's available
+            if signature and name:
+                # Function with signature
+                if output_format == 'grep':
+                    print(f"{path}:{line}:{name}{signature}")
+                else:
+                    print(f"  {path}:{line:<6} {name}{signature}")
+            elif name:
+                # Just name (class, struct, etc.)
+                if output_format == 'grep':
+                    print(f"{path}:{line}:{name}")
+                else:
+                    print(f"  {path}:{line:<6} {name}")
+            elif content:
+                # Just content (import, etc.)
+                if output_format == 'grep':
+                    print(f"{path}:{line}:{content}")
+                else:
+                    print(f"  {path}:{line:<6} {content}")
+
+        print()  # Blank line between categories
+
+    # Navigation hints
+    if output_format == 'text':
+        print(f"→ reveal {path} <element>")
+        print(f"→ vim {path}:<line>")
+
+
+def extract_element(analyzer: FileAnalyzer, element: str, output_format: str):
+    """Extract a specific element.
+
+    Args:
+        analyzer: File analyzer
+        element: Element name to extract
+        output_format: Output format
+    """
+    # Try common element types
+    for element_type in ['function', 'class', 'struct', 'section']:
+        result = analyzer.extract_element(element_type, element)
+        if result:
+            break
+    else:
+        # Not found
+        print(f"Error: Element '{element}' not found in {analyzer.path}", file=sys.stderr)
+        sys.exit(1)
+
+    # Format output
+    if output_format == 'json':
+        import json
+        print(json.dumps(result, indent=2))
+        return
+
+    path = analyzer.path
+    line_start = result.get('line_start', 1)
+    line_end = result.get('line_end', line_start)
+    source = result.get('source', '')
+    name = result.get('name', element)
+
+    # Header
+    print(f"{path}:{line_start}-{line_end} | {name}\n")
+
+    # Source with line numbers
+    if output_format == 'grep':
+        # Grep format: filename:linenum:content
+        for i, line in enumerate(source.split('\n')):
+            line_num = line_start + i
+            print(f"{path}:{line_num}:{line}")
+    else:
+        # Human-readable format
+        formatted = analyzer.format_with_lines(source, line_start)
+        print(formatted)
+
+        # Navigation hints
+        print(f"\n→ vim {path}:{line_start}")
+        print(f"→ reveal {path}")
+
+
+if __name__ == '__main__':
+    main()

reveal/tests/__init__.py

@@ -0,0 +1 @@
+"""Test suite for reveal."""