scantool 0.9.1__py3-none-any.whl

scantool/__init__.py

@@ -0,0 +1,7 @@
+"""File Scanner MCP - Beautiful file structure scanner with tree formatting."""
+
+__version__ = "0.1.0"
+
+from .server import main
+
+__all__ = ["main"]

scantool/directory_formatter.py

@@ -0,0 +1,364 @@
+"""Hierarchical directory tree formatter with integrated code structures."""
+
+from pathlib import Path
+from collections import defaultdict
+from typing import Optional
+from datetime import datetime
+from .scanners import StructureNode
+
+
+class DirectoryFormatter:
+    """Formats directory scans as hierarchical trees with code structures."""
+
+    # Tree drawing characters
+    BRANCH = "├─"
+    LAST_BRANCH = "└─"
+    VERTICAL = "│  "
+    SPACE = "   "
+
+    @staticmethod
+    def _format_relative_time(iso_timestamp: str) -> str:
+        """Format timestamp as relative time (e.g., '2 mins ago', '3 days ago')."""
+        try:
+            # Parse ISO timestamp
+            modified_time = datetime.fromisoformat(iso_timestamp)
+            now = datetime.now()
+            diff = now - modified_time
+
+            # Calculate time difference
+            seconds = diff.total_seconds()
+            if seconds < 60:
+                return "just now"
+            elif seconds < 3600:  # < 1 hour
+                mins = int(seconds / 60)
+                return f"{mins} min{'s' if mins != 1 else ''} ago"
+            elif seconds < 86400:  # < 1 day
+                hours = int(seconds / 3600)
+                return f"{hours} hour{'s' if hours != 1 else ''} ago"
+            elif seconds < 604800:  # < 1 week
+                days = int(seconds / 86400)
+                return f"{days} day{'s' if days != 1 else ''} ago"
+            elif seconds < 2592000:  # < 30 days
+                weeks = int(seconds / 604800)
+                return f"{weeks} week{'s' if weeks != 1 else ''} ago"
+            elif seconds < 31536000:  # < 1 year
+                months = int(seconds / 2592000)
+                return f"{months} month{'s' if months != 1 else ''} ago"
+            else:
+                years = int(seconds / 31536000)
+                return f"{years} year{'s' if years != 1 else ''} ago"
+        except Exception:
+            # If parsing fails, return empty string
+            return ""
+
+    def __init__(self, show_signatures: bool = True, show_decorators: bool = True,
+                 show_docstrings: bool = True, show_complexity: bool = False,
+                 include_structures: bool = True, flatten_structures: bool = False):
+        """
+        Initialize directory formatter with display options.
+
+        Args:
+            flatten_structures: Show only top-level structures (classes/functions)
+                               without nested children (methods). Reduces output by ~50%.
+        """
+        self.show_signatures = show_signatures
+        self.show_decorators = show_decorators
+        self.show_docstrings = show_docstrings
+        self.show_complexity = show_complexity
+        self.include_structures = include_structures
+        self.flatten_structures = flatten_structures
+
+    def format(self, base_dir: str, file_structures: dict[str, list[StructureNode]]) -> str:
+        """
+        Format directory scan as hierarchical tree.
+
+        Args:
+            base_dir: Base directory path
+            file_structures: Dict mapping file paths to their structure nodes
+
+        Returns:
+            Formatted hierarchical tree string
+        """
+        base_path = Path(base_dir).resolve()
+
+        # Build directory tree
+        tree = self._build_tree(base_path, file_structures)
+
+        # Format as text
+        lines = [f"{base_path.name}/ {self._format_stats(tree)}"]
+        lines.extend(self._format_tree_node(tree, ""))
+
+        return "\n".join(lines)
+
+    def _build_tree(self, base_path: Path, file_structures: dict[str, list[StructureNode]]) -> dict:
+        """Build hierarchical directory tree structure."""
+        tree = {
+            "type": "directory",
+            "name": base_path.name,
+            "path": base_path,
+            "children": {},
+            "files": {},
+            "stats": {"files": 0, "classes": 0, "functions": 0, "methods": 0}
+        }
+
+        for file_path_str, structures in file_structures.items():
+            if not structures:
+                continue
+
+            file_path = Path(file_path_str).resolve()
+
+            # Get relative path from base
+            try:
+                rel_path = file_path.relative_to(base_path)
+            except ValueError:
+                # File is outside base_path, skip it
+                continue
+
+            # Navigate/create directory structure
+            current = tree
+            parts = list(rel_path.parts[:-1])  # All but filename
+
+            for part in parts:
+                if part not in current["children"]:
+                    current["children"][part] = {
+                        "type": "directory",
+                        "name": part,
+                        "children": {},
+                        "files": {},
+                        "stats": {"files": 0, "classes": 0, "functions": 0, "methods": 0}
+                    }
+                current = current["children"][part]
+
+            # Add file to current directory
+            filename = rel_path.parts[-1]
+            current["files"][filename] = {
+                "type": "file",
+                "name": filename,
+                "path": file_path,
+                "structures": structures
+            }
+
+            # Update stats recursively up the tree
+            self._update_stats(tree, structures)
+
+        return tree
+
+    def _update_stats(self, node: dict, structures: list[StructureNode]):
+        """Update statistics for a node and count structures."""
+        node["stats"]["files"] += 1
+
+        def count_structures(structs):
+            for s in structs:
+                if s.type == "class":
+                    node["stats"]["classes"] += 1
+                elif s.type == "function":
+                    node["stats"]["functions"] += 1
+                elif s.type == "method":
+                    node["stats"]["methods"] += 1
+
+                if hasattr(s, "children") and s.children:
+                    count_structures(s.children)
+
+        count_structures(structures)
+
+    def _format_stats(self, node: dict) -> str:
+        """Format directory statistics."""
+        stats = node["stats"]
+        parts = []
+
+        if stats["files"] > 0:
+            parts.append(f"{stats['files']} file{'s' if stats['files'] != 1 else ''}")
+        if stats["classes"] > 0:
+            parts.append(f"{stats['classes']} class{'es' if stats['classes'] != 1 else ''}")
+        if stats["functions"] > 0:
+            parts.append(f"{stats['functions']} function{'s' if stats['functions'] != 1 else ''}")
+        if stats["methods"] > 0:
+            parts.append(f"{stats['methods']} method{'s' if stats['methods'] != 1 else ''}")
+
+        return f"({', '.join(parts)})" if parts else ""
+
+    def _format_tree_node(self, node: dict, prefix: str) -> list[str]:
+        """Recursively format a tree node and its children."""
+        lines = []
+
+        # Get sorted children and files
+        dirs = sorted(node["children"].items())
+        files = sorted(node["files"].items())
+
+        all_items = [(name, child, True) for name, child in dirs] + \
+                    [(name, child, False) for name, child in files]
+
+        for i, (name, child, is_dir) in enumerate(all_items):
+            is_last = i == len(all_items) - 1
+            connector = self.LAST_BRANCH if is_last else self.BRANCH
+
+            if is_dir:
+                # Directory
+                stats_str = self._format_stats(child)
+                lines.append(f"{prefix}{connector} {name}/ {stats_str}")
+
+                # Recurse into directory
+                child_prefix = prefix + (self.SPACE if is_last else self.VERTICAL)
+                lines.extend(self._format_tree_node(child, child_prefix))
+
+            else:
+                # File
+                structures = child["structures"]
+
+                # Check if this is an unsupported file (only has file-info with unsupported flag)
+                is_unsupported = (
+                    len(structures) == 1
+                    and structures[0].type == "file-info"
+                    and hasattr(structures[0], "file_metadata")
+                    and structures[0].file_metadata
+                    and structures[0].file_metadata.get("unsupported", False)
+                )
+
+                if is_unsupported:
+                    # Unsupported file - show with metadata (no extension needed, it's in the filename)
+                    metadata = structures[0].file_metadata
+                    size = metadata.get("size_formatted", "")
+
+                    # Format modified time as relative (e.g., "2 mins ago")
+                    modified_iso = metadata.get("modified", "")
+                    modified_relative = self._format_relative_time(modified_iso) if modified_iso else ""
+
+                    # Build metadata string: size, relative time
+                    meta_parts = [size, modified_relative]
+                    meta_str = ", ".join(p for p in meta_parts if p)
+                    lines.append(f"{prefix}{connector} {name} [{meta_str}]")
+                else:
+                    # Supported file - show structures with metadata
+                    min_line = min(s.start_line for s in self._flatten(structures)) if structures else 1
+                    max_line = max(s.end_line for s in self._flatten(structures)) if structures else 1
+
+                    # Extract metadata from file-info node if present
+                    file_metadata = None
+                    if structures and structures[0].type == "file-info":
+                        file_metadata = structures[0].file_metadata
+
+                    # Format metadata (size and modified time)
+                    metadata_str = ""
+                    if file_metadata:
+                        size = file_metadata.get("size_formatted", "")
+                        modified_iso = file_metadata.get("modified", "")
+                        modified_relative = self._format_relative_time(modified_iso) if modified_iso else ""
+
+                        meta_parts = [size, modified_relative]
+                        metadata_str = " [" + ", ".join(p for p in meta_parts if p) + "]"
+
+                    # Format file line
+                    if self.include_structures and self.flatten_structures:
+                        # Ultra-compact mode: show structures inline
+                        display_structures = self._flatten_top_level(structures)
+                        if display_structures:
+                            # Get just the names of classes and functions
+                            names = [s.name for s in display_structures]
+                            if len(names) > 5:
+                                # Truncate if too many
+                                structure_list = ", ".join(names[:5]) + f", ... ({len(names)} total)"
+                            else:
+                                structure_list = ", ".join(names)
+                            lines.append(f"{prefix}{connector} {name} ({min_line}-{max_line}){metadata_str} - {structure_list}")
+                        else:
+                            lines.append(f"{prefix}{connector} {name} ({min_line}-{max_line}){metadata_str}")
+                    elif self.include_structures:
+                        # Normal mode: show structures in tree below file
+                        lines.append(f"{prefix}{connector} {name} ({min_line}-{max_line}){metadata_str}")
+                        child_prefix = prefix + (self.SPACE if is_last else self.VERTICAL)
+                        lines.extend(self._format_structures(structures, child_prefix))
+                    else:
+                        # No structures mode
+                        lines.append(f"{prefix}{connector} {name} ({min_line}-{max_line}){metadata_str}")
+
+        return lines
+
+    def _format_structures(self, structures: list[StructureNode], prefix: str) -> list[str]:
+        """Format structure nodes with indentation."""
+        lines = []
+
+        for i, node in enumerate(structures):
+            is_last = i == len(structures) - 1
+            lines.extend(self._format_structure_node(node, prefix, is_last))
+
+        return lines
+
+    def _format_structure_node(self, node: StructureNode, prefix: str, is_last: bool) -> list[str]:
+        """Format a single structure node."""
+        lines = []
+        connector = self.LAST_BRANCH if is_last else self.BRANCH
+
+        # Build main line
+        parts = [f"{prefix}{connector} {node.type}: {node.name}"]
+
+        # Add signature if available
+        if self.show_signatures and hasattr(node, "signature") and node.signature:
+            parts.append(node.signature)
+
+        # Add line numbers
+        parts.append(f"({node.start_line}-{node.end_line})")
+
+        # Add modifiers if present
+        if hasattr(node, "modifiers") and node.modifiers:
+            modifiers_str = " ".join(node.modifiers)
+            parts.append(f"[{modifiers_str}]")
+
+        lines.append(" ".join(parts))
+
+        # Add decorators on separate lines
+        if self.show_decorators and hasattr(node, "decorators") and node.decorators:
+            decorator_prefix = prefix + (self.SPACE if is_last else self.VERTICAL) + "  "
+            for decorator in node.decorators:
+                lines.append(f"{decorator_prefix}{decorator}")
+
+        # Add docstring on separate line
+        if self.show_docstrings and hasattr(node, "docstring") and node.docstring:
+            docstring_prefix = prefix + (self.SPACE if is_last else self.VERTICAL) + "  "
+            lines.append(f'{docstring_prefix}"{node.docstring}"')
+
+        # Format children
+        if hasattr(node, "children") and node.children:
+            child_prefix = prefix + (self.SPACE if is_last else self.VERTICAL)
+            for j, child in enumerate(node.children):
+                is_last_child = j == len(node.children) - 1
+                lines.extend(self._format_structure_node(child, child_prefix, is_last_child))
+
+        return lines
+
+    def _flatten(self, structures: list[StructureNode]) -> list[StructureNode]:
+        """Flatten structure tree to get all nodes."""
+        result = []
+        for node in structures:
+            result.append(node)
+            if hasattr(node, "children") and node.children:
+                result.extend(self._flatten(node.children))
+        return result
+
+    def _flatten_top_level(self, structures: list[StructureNode]) -> list[StructureNode]:
+        """
+        Create shallow copies of structures without children.
+
+        Returns only top-level classes and functions, stripping nested methods.
+        Reduces output by ~50% while maintaining overview.
+        """
+        flattened = []
+        for node in structures:
+            # Skip non-code structures (file-info, imports)
+            if node.type in ('file-info', 'imports'):
+                continue
+
+            # Create shallow copy with no children
+            shallow = StructureNode(
+                type=node.type,
+                name=node.name,
+                start_line=node.start_line,
+                end_line=node.end_line,
+                signature=None,  # Strip signatures for compactness
+                decorators=[],   # Strip decorators
+                docstring=None,  # Strip docstrings
+                complexity=None,
+                modifiers=[],
+                children=[]  # No children - flattened!
+            )
+            flattened.append(shallow)
+        return flattened

scantool/formatter.py

@@ -0,0 +1,153 @@
+"""Pretty tree formatter for file structure with rich metadata display."""
+
+from pathlib import Path
+from datetime import datetime
+from .scanners import StructureNode
+
+
+class TreeFormatter:
+    """Formats structure nodes as a pretty tree with metadata."""
+
+    # Tree drawing characters
+    BRANCH = "├─"
+    LAST_BRANCH = "└─"
+    VERTICAL = "│  "
+    SPACE = "   "
+
+    def __init__(self, show_signatures: bool = True, show_decorators: bool = True,
+                 show_docstrings: bool = True, show_complexity: bool = False):
+        """
+        Initialize formatter with display options.
+
+        Args:
+            show_signatures: Display function signatures
+            show_decorators: Display decorators
+            show_docstrings: Display first line of docstrings
+            show_complexity: Display complexity metrics
+        """
+        self.show_signatures = show_signatures
+        self.show_decorators = show_decorators
+        self.show_docstrings = show_docstrings
+        self.show_complexity = show_complexity
+
+    def format(self, file_path: str, structures: list[StructureNode]) -> str:
+        """Format the structure as a pretty tree."""
+        if not structures:
+            return f"{Path(file_path).name} (empty file)"
+
+        # Get file line range (excluding metadata nodes with line 0)
+        content_nodes = [s for s in self._flatten(structures) if s.start_line > 0 or s.end_line > 0]
+        if content_nodes:
+            min_line = min(s.start_line for s in content_nodes)
+            max_line = max(s.end_line for s in content_nodes)
+            lines = [f"{Path(file_path).name} ({min_line}-{max_line})"]
+        else:
+            lines = [f"{Path(file_path).name}"]
+
+        for i, node in enumerate(structures):
+            is_last = i == len(structures) - 1
+            lines.extend(self._format_node(node, "", is_last))
+
+        return "\n".join(lines)
+
+    def _format_node(self, node: StructureNode, prefix: str, is_last: bool) -> list[str]:
+        """Format a single node and its children with metadata."""
+        lines = []
+
+        # Current node connector
+        connector = self.LAST_BRANCH if is_last else self.BRANCH
+
+        # Special formatting for file-info nodes
+        if node.type == "file-info" and node.file_metadata:
+            meta = node.file_metadata
+
+            # Format timestamp as readable datetime
+            modified_iso = meta.get('modified', '')
+            if modified_iso:
+                try:
+                    dt = datetime.fromisoformat(modified_iso)
+                    # Format as: 2025-10-17 14:30
+                    modified_str = dt.strftime('%Y-%m-%d %H:%M')
+                except Exception:
+                    # Fallback to just date if parsing fails
+                    modified_str = modified_iso.split('T')[0]
+            else:
+                modified_str = ""
+
+            parts = [
+                f"{prefix}{connector} {node.type}:",
+                meta['size_formatted'],
+                f"modified: {modified_str}" if modified_str else ""
+            ]
+            lines.append(" ".join(p for p in parts if p))
+            return lines
+
+        # Build the main node line
+        parts = [f"{prefix}{connector} {node.type}: {node.name}"]
+
+        # Add signature if available
+        if self.show_signatures and node.signature:
+            parts.append(node.signature)
+
+        # Add line numbers (skip for file-info nodes with line 0)
+        if node.start_line > 0 or node.end_line > 0:
+            parts.append(f"({node.start_line}-{node.end_line})")
+
+        # Add modifiers if present
+        if node.modifiers:
+            modifiers_str = " ".join(node.modifiers)
+            parts.append(f"[{modifiers_str}]")
+
+        # Add complexity indicator if enabled
+        if self.show_complexity and node.complexity:
+            complexity_str = self._format_complexity(node.complexity)
+            if complexity_str:
+                parts.append(complexity_str)
+
+        lines.append(" ".join(parts))
+
+        # Add decorators on separate lines (indented)
+        if self.show_decorators and node.decorators:
+            decorator_prefix = prefix + (self.SPACE if is_last else self.VERTICAL) + "  "
+            for decorator in node.decorators:
+                lines.append(f"{decorator_prefix}{decorator}")
+
+        # Add docstring on separate line (indented)
+        if self.show_docstrings and node.docstring:
+            docstring_prefix = prefix + (self.SPACE if is_last else self.VERTICAL) + "  "
+            lines.append(f'{docstring_prefix}"{node.docstring}"')
+
+        # Format children
+        if node.children:
+            # New prefix for children
+            child_prefix = prefix + (self.SPACE if is_last else self.VERTICAL)
+
+            for i, child in enumerate(node.children):
+                is_last_child = i == len(node.children) - 1
+                lines.extend(self._format_node(child, child_prefix, is_last_child))
+
+        return lines
+
+    def _format_complexity(self, complexity: dict) -> str:
+        """Format complexity metrics as a compact string."""
+        parts = []
+
+        if complexity.get("lines", 0) > 100:
+            parts.append(f"📏{complexity['lines']}")
+
+        if complexity.get("max_depth", 0) > 5:
+            parts.append(f"🔄{complexity['max_depth']}")
+
+        if complexity.get("branches", 0) > 10:
+            parts.append(f"🌿{complexity['branches']}")
+
+        return " ".join(parts) if parts else ""
+
+    def _flatten(self, structures: list[StructureNode]) -> list[StructureNode]:
+        """Flatten structure tree to get all nodes."""
+        result = []
+        for node in structures:
+            result.append(node)
+            if node.children:
+                result.extend(self._flatten(node.children))
+        return result

scantool/gitignore.py

@@ -0,0 +1,145 @@
+"""Gitignore parsing and path matching utilities."""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+
+class GitignoreParser:
+    """Parse and match paths against gitignore patterns."""
+
+    def __init__(self, patterns: list[str]):
+        """
+        Initialize gitignore parser with patterns.
+
+        Args:
+            patterns: List of gitignore pattern strings
+        """
+        self.patterns = []
+        for pattern in patterns:
+            pattern = pattern.strip()
+            # Skip empty lines and comments
+            if not pattern or pattern.startswith('#'):
+                continue
+            self.patterns.append(self._compile_pattern(pattern))
+
+    def _compile_pattern(self, pattern: str) -> tuple[re.Pattern, bool]:
+        """
+        Compile a gitignore pattern to regex.
+
+        Returns:
+            Tuple of (compiled_regex, is_negation)
+        """
+        is_negation = pattern.startswith('!')
+        if is_negation:
+            pattern = pattern[1:]
+
+        # Directory-only pattern
+        if pattern.endswith('/'):
+            pattern = pattern[:-1]
+            is_dir_only = True
+        else:
+            is_dir_only = False
+
+        # Anchored pattern (starts with /)
+        if pattern.startswith('/'):
+            pattern = pattern[1:]
+            anchored = True
+        else:
+            anchored = False
+
+        # Convert gitignore glob to regex
+        regex_parts = []
+        i = 0
+        while i < len(pattern):
+            char = pattern[i]
+            if char == '*':
+                if i + 1 < len(pattern) and pattern[i + 1] == '*':
+                    # ** matches any number of directories
+                    regex_parts.append('.*')
+                    i += 2
+                    # Skip following /
+                    if i < len(pattern) and pattern[i] == '/':
+                        i += 1
+                    continue
+                else:
+                    # * matches anything except /
+                    regex_parts.append('[^/]*')
+            elif char == '?':
+                regex_parts.append('[^/]')
+            elif char == '[':
+                # Character class
+                j = i + 1
+                while j < len(pattern) and pattern[j] != ']':
+                    j += 1
+                if j < len(pattern):
+                    regex_parts.append(pattern[i:j + 1])
+                    i = j
+                else:
+                    regex_parts.append(re.escape(char))
+            else:
+                regex_parts.append(re.escape(char))
+            i += 1
+
+        regex_str = ''.join(regex_parts)
+
+        # Build final pattern
+        # Pattern should match:
+        # 1. The exact name (.venv matches .venv)
+        # 2. The name as a directory (.venv matches .venv/)
+        # 3. Anything under it (.venv matches .venv/foo/bar.py)
+
+        if anchored:
+            # Must match from start
+            # Matches: exact name, or name followed by / and anything
+            final_pattern = f'^{regex_str}(?:/.*)?$'
+        else:
+            # Can match anywhere in path
+            # Matches at start or after /, then exact name or name/ with anything
+            final_pattern = f'(?:^|/){regex_str}(?:/.*)?$'
+
+        return (re.compile(final_pattern), is_negation)
+
+    def matches(self, path: str, is_dir: bool = False) -> bool:
+        """
+        Check if path matches any pattern.
+
+        Args:
+            path: Relative path to check
+            is_dir: Whether the path is a directory
+
+        Returns:
+            True if path should be ignored
+        """
+        # Normalize path (remove leading ./ if present)
+        if path.startswith('./'):
+            path = path[2:]
+
+        ignored = False
+        for regex, is_negation in self.patterns:
+            if regex.search(path):
+                ignored = not is_negation
+
+        return ignored
+
+
+def load_gitignore(directory: Path) -> Optional[GitignoreParser]:
+    """
+    Load .gitignore file from directory.
+
+    Args:
+        directory: Directory to search for .gitignore
+
+    Returns:
+        GitignoreParser or None if no .gitignore found
+    """
+    gitignore_path = directory / '.gitignore'
+    if not gitignore_path.exists():
+        return None
+
+    try:
+        with open(gitignore_path, 'r', encoding='utf-8') as f:
+            patterns = f.readlines()
+        return GitignoreParser(patterns)
+    except Exception:
+        return None