treegetter 2.0.0__py3-none-any.whl

treegetter/__init__.py

@@ -0,0 +1,64 @@
+"""TreeGetter – AI-Ready Repository Intelligence Engine."""
+
+from __future__ import annotations
+
+from .api import generate_tree, get_tree, main
+from .cache import CacheManager
+from .exceptions import (
+    AnalysisError,
+    CacheError,
+    CircularSymlinkError,
+    DirectoryTreeError,
+    InvalidPathError,
+    PermissionDeniedError,
+    PluginError,
+    ScannerError,
+    SearchError,
+)
+from .models import (
+    AIContext,
+    ArchitectureInfo,
+    DependencyInfo,
+    EntryPoint,
+    FileMetadata,
+    FrameworkInfo,
+    LanguageStat,
+    Node,
+    RepositorySummary,
+    SearchResult,
+    TreeConfig,
+    TreeStatistics,
+)
+from .plugins import BasePlugin, PluginRegistry
+from .repository import Repository
+
+__all__ = [
+    "get_tree",
+    "generate_tree",
+    "main",
+    "Repository",
+    "Node",
+    "TreeConfig",
+    "TreeStatistics",
+    "FileMetadata",
+    "FrameworkInfo",
+    "DependencyInfo",
+    "EntryPoint",
+    "ArchitectureInfo",
+    "LanguageStat",
+    "RepositorySummary",
+    "SearchResult",
+    "AIContext",
+    "BasePlugin",
+    "PluginRegistry",
+    "CacheManager",
+    "DirectoryTreeError",
+    "InvalidPathError",
+    "PermissionDeniedError",
+    "CircularSymlinkError",
+    "PluginError",
+    "CacheError",
+    "ScannerError",
+    "SearchError",
+    "AnalysisError",
+]

treegetter/__main__.py

@@ -0,0 +1,9 @@
+"""CLI entrypoint for treegetter package."""
+
+from __future__ import annotations
+
+import sys
+from .api import main
+
+if __name__ == "__main__":
+    sys.exit(main())

treegetter/api.py

@@ -0,0 +1,146 @@
+"""Public high-level API functions for treegetter backward compatibility and CLI."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from .config import DEFAULT_IGNORE_DIRS, DEFAULT_IGNORE_PATTERNS, SUPPORTED_FORMATS
+from .exceptions import DirectoryTreeError
+from .filters import PathFilter
+from .formatter import FormatterFactory
+from .models import TreeConfig, TreeStatistics
+from .scanner import DirectoryScanner
+from .statistics import StatisticsEngine
+from .utils import validate_path
+
+
+def generate_tree(
+    path: str | Path,
+    *,
+    max_depth: int | None = None,
+    include_hidden: bool = False,
+    follow_symlinks: bool = False,
+    show_size: bool = False,
+    dirs_first: bool = True,
+    output_format: str = "unicode",
+    ignore_dirs: frozenset[str] | None = None,
+    ignore_patterns: tuple[str, ...] | None = None,
+    use_gitignore: bool = False,
+    show_stats: bool = False,
+) -> str:
+    """Generate a formatted directory tree string."""
+    root = validate_path(path)
+
+    config = TreeConfig(
+        root=root,
+        max_depth=max_depth,
+        include_hidden=include_hidden,
+        follow_symlinks=follow_symlinks,
+        show_size=show_size,
+        dirs_first=dirs_first,
+        output_format=output_format,
+        ignore_dirs=frozenset(ignore_dirs) if ignore_dirs is not None else DEFAULT_IGNORE_DIRS,
+        ignore_patterns=(
+            tuple(ignore_patterns) if ignore_patterns is not None else DEFAULT_IGNORE_PATTERNS
+        ),
+        use_gitignore=use_gitignore,
+        show_stats=show_stats,
+    )
+
+    path_filter = PathFilter(config)
+    scanner = DirectoryScanner(config, path_filter)
+    tree = scanner.scan(root)
+
+    statistics: TreeStatistics | None = None
+    if config.show_stats:
+        statistics = StatisticsEngine().compute(tree)
+
+    formatter = FormatterFactory.create(config.output_format, show_size=config.show_size)
+    return formatter.format(tree, stats=statistics)
+
+
+def get_tree(path: str | Path, **kwargs: Any) -> str:
+    """Backward-compatible alias for generate_tree."""
+    return generate_tree(path, **kwargs)
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="treegetter",
+        description="Generate a directory tree in unicode, ascii, markdown or json format.",
+    )
+    parser.add_argument(
+        "path", nargs="?", default=".", help="Directory to scan (default: current directory)"
+    )
+    parser.add_argument("-d", "--max-depth", type=int, default=None, help="Maximum depth to traverse")
+    parser.add_argument("-a", "--all", action="store_true", help="Include hidden files and directories")
+    parser.add_argument(
+        "-L", "--follow-symlinks", action="store_true", help="Descend into symlinked directories"
+    )
+    parser.add_argument("-s", "--size", action="store_true", help="Show file sizes")
+    parser.add_argument(
+        "--no-dirs-first", action="store_true", help="Do not list directories before files"
+    )
+    parser.add_argument(
+        "-f", "--format", choices=SUPPORTED_FORMATS, default="unicode", help="Output format"
+    )
+    parser.add_argument(
+        "-i", "--ignore", action="append", default=[], metavar="GLOB",
+        help="Additional glob pattern to ignore (repeatable)",
+    )
+    parser.add_argument(
+        "--ignore-dir", action="append", default=[], metavar="NAME",
+        help="Additional directory name to ignore (repeatable)",
+    )
+    parser.add_argument(
+        "--gitignore", action="store_true", help="Respect a .gitignore file in the root directory"
+    )
+    parser.add_argument("--stats", action="store_true", help="Show summary statistics")
+    parser.add_argument(
+        "-o", "--output", type=Path, default=None, help="Write output to a file instead of stdout"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_arg_parser()
+    args = parser.parse_args(argv)
+
+    ignore_dirs = DEFAULT_IGNORE_DIRS | frozenset(args.ignore_dir)
+    ignore_patterns = DEFAULT_IGNORE_PATTERNS + tuple(args.ignore)
+
+    try:
+        rendered = generate_tree(
+            args.path,
+            max_depth=args.max_depth,
+            include_hidden=args.all,
+            follow_symlinks=args.follow_symlinks,
+            show_size=args.size,
+            dirs_first=not args.no_dirs_first,
+            output_format=args.format,
+            ignore_dirs=ignore_dirs,
+            ignore_patterns=ignore_patterns,
+            use_gitignore=args.gitignore,
+            show_stats=args.stats,
+        )
+    except DirectoryTreeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.output is not None:
+        args.output.write_text(rendered, encoding="utf-8")
+        print(f"Written to {args.output}")
+    else:
+        print(rendered)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

treegetter/architecture.py

@@ -0,0 +1,93 @@
+"""Architecture pattern analyzer using folder structure heuristics and configuration files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+from .models import ArchitectureInfo, FileMetadata
+
+
+class ArchitectureAnalyzer:
+    """Analyzes directory structure and file paths to identify architecture style."""
+
+    def analyze(self, root: Path, files: Sequence[FileMetadata] | None = None) -> ArchitectureInfo:
+        """Detect architecture pattern and calculate confidence score."""
+        dir_names = set()
+        for p in root.glob("*"):
+            if p.is_dir():
+                dir_names.add(p.name.lower())
+
+        if files:
+            for f in files:
+                for part in f.path.parts:
+                    dir_names.add(part.lower())
+
+        if (root / "packages").is_dir() or (root / "apps").is_dir() or (root / "lerna.json").is_file() or (root / "pnpm-workspace.yaml").is_file():
+            return ArchitectureInfo(
+                pattern="Monorepo",
+                confidence=0.95,
+                details={"indicator": "packages/apps workspace structure or configuration"},
+            )
+
+        clean_keywords = {"domain", "usecases", "adapters", "entities", "interfaces", "infrastructure"}
+        if len(clean_keywords.intersection(dir_names)) >= 3:
+            return ArchitectureInfo(
+                pattern="Clean Architecture",
+                confidence=0.90,
+                details={"matching_layers": list(clean_keywords.intersection(dir_names))},
+            )
+
+        hex_keywords = {"ports", "adapters", "domain", "application"}
+        if len(hex_keywords.intersection(dir_names)) >= 3:
+            return ArchitectureInfo(
+                pattern="Hexagonal Architecture",
+                confidence=0.90,
+                details={"matching_layers": list(hex_keywords.intersection(dir_names))},
+            )
+
+        ddd_keywords = {"domain", "aggregates", "bounded_contexts", "value_objects", "repositories"}
+        if len(ddd_keywords.intersection(dir_names)) >= 3:
+            return ArchitectureInfo(
+                pattern="Domain Driven Design",
+                confidence=0.85,
+                details={"matching_elements": list(ddd_keywords.intersection(dir_names))},
+            )
+
+        mvc_keywords = {"models", "views", "controllers"}
+        if mvc_keywords.issubset(dir_names) or {"model", "view", "controller"}.issubset(dir_names):
+            return ArchitectureInfo(
+                pattern="MVC",
+                confidence=0.95,
+                details={"matching_folders": ["models", "views", "controllers"]},
+            )
+
+        layered_keywords = {"controllers", "services", "repositories", "routes"}
+        matches = layered_keywords.intersection(dir_names)
+        if len(matches) >= 2:
+            return ArchitectureInfo(
+                pattern="Layered Architecture",
+                confidence=0.85,
+                details={"layers": list(matches)},
+            )
+
+        feature_keywords = {"features", "modules", "components"}
+        if len(feature_keywords.intersection(dir_names)) >= 1:
+            return ArchitectureInfo(
+                pattern="Feature-based",
+                confidence=0.75,
+                details={"matching_folders": list(feature_keywords.intersection(dir_names))},
+            )
+
+        if len([d for d in dir_names if "service" in d]) >= 2:
+            return ArchitectureInfo(
+                pattern="Microservices",
+                confidence=0.80,
+                details={"indicator": "multiple service directories"},
+            )
+
+        return ArchitectureInfo(
+            pattern="Modular / Standard Layout",
+            confidence=0.60,
+            details={"indicator": "standard package directory layout"},
+        )

treegetter/cache.py

@@ -0,0 +1,61 @@
+"""Thread-safe cache engine for repository scanning and intelligence."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+class CacheManager:
+    """Thread-safe cache manager supporting key-value operations and lazy get-or-set."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, Any] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a cached value by key."""
+        with self._lock:
+            return self._cache.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Store a key-value pair in cache."""
+        with self._lock:
+            self._cache[key] = value
+
+    def has(self, key: str) -> bool:
+        """Check if a key exists in cache."""
+        with self._lock:
+            return key in self._cache
+
+    def get_or_compute(self, key: str, compute_func: Callable[[], T]) -> T:
+        """Get cached value or compute and store it thread-safely."""
+        with self._lock:
+            if key in self._cache:
+                return self._cache[key]
+
+        value = compute_func()
+
+        with self._lock:
+            self._cache[key] = value
+            return value
+
+    def invalidate(self, key: str) -> bool:
+        """Remove a specific key from cache."""
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                return True
+            return False
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        with self._lock:
+            self._cache.clear()
+
+    def size(self) -> int:
+        """Return total number of cached entries."""
+        with self._lock:
+            return len(self._cache)

treegetter/config.py

@@ -0,0 +1,158 @@
+"""Default configuration values and constants for the treegetter package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .models import TreeConfig
+
+DEFAULT_IGNORE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".svn",
+        ".hg",
+        "__pycache__",
+        "node_modules",
+        ".venv",
+        "venv",
+        "env",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".idea",
+        ".vscode",
+        "dist",
+        "build",
+        ".tox",
+        "target",
+        "vendor",
+        ".next",
+        ".nuxt",
+        ".turbo",
+        ".cache",
+        "bin",
+        "obj",
+        ".gradle",
+        ".mvn",
+        ".dart_tool",
+    }
+)
+
+DEFAULT_IGNORE_PATTERNS: tuple[str, ...] = (
+    "*.pyc",
+    "*.pyo",
+    "*.egg-info",
+    "*.log",
+    "*.tmp",
+    "*.temp",
+    "*.swp",
+    "*.lock",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "Cargo.lock",
+    "poetry.lock",
+    "Pipfile.lock",
+    "composer.lock",
+)
+
+SUPPORTED_FORMATS: tuple[str, ...] = ("unicode", "ascii", "markdown", "json")
+
+EXTENSION_LANGUAGE_MAP: dict[str, str] = {
+    ".py": "Python",
+    ".pyw": "Python",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".java": "Java",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".cpp": "C++",
+    ".cxx": "C++",
+    ".cc": "C++",
+    ".hpp": "C++",
+    ".h": "C++",
+    ".c": "C",
+    ".cs": "C#",
+    ".php": "PHP",
+    ".rb": "Ruby",
+    ".html": "HTML",
+    ".htm": "HTML",
+    ".css": "CSS",
+    ".scss": "CSS",
+    ".sass": "CSS",
+    ".less": "CSS",
+    ".md": "Markdown",
+    ".markdown": "Markdown",
+    ".json": "JSON",
+    ".yaml": "YAML",
+    ".yml": "YAML",
+    ".xml": "XML",
+    ".dart": "Dart",
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    ".ps1": "PowerShell",
+    ".sql": "SQL",
+    ".dockerfile": "Dockerfile",
+    ".toml": "TOML",
+    ".env": "Config",
+    ".ini": "Config",
+}
+
+MIME_TYPE_MAP: dict[str, str] = {
+    ".py": "text/x-python",
+    ".js": "application/javascript",
+    ".ts": "application/typescript",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".md": "text/markdown",
+    ".xml": "text/xml",
+    ".yaml": "text/yaml",
+    ".yml": "text/yaml",
+    ".txt": "text/plain",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml",
+}
+
+PROJECT_MAP_PATTERNS: dict[str, list[str]] = {
+    "Controllers": ["*controller*", "*handler*", "*router*", "*endpoint*"],
+    "Services": ["*service*", "*usecase*", "*business*", "*logic*"],
+    "Repositories": ["*repository*", "*repo*", "*dao*", "*store*", "*db*"],
+    "Models": ["*model*", "*entity*", "*schema*", "*dto*", "*type*"],
+    "Routes": ["*route*", "*api*", "*url*", "*endpoint*"],
+    "Hooks": ["*hook*", "use*"],
+    "Components": ["*component*", "*view*", "*page*", "*screen*", "*widget*"],
+    "Tests": ["*test*", "*spec*", "test_*", "*_test.py", "*_test.go"],
+    "Utilities": ["*util*", "*helper*", "*tool*", "*common*", "*shared*"],
+    "Configuration": ["*config*", "*setting*", ".env*", "*.toml", "*.yaml", "*.json"],
+    "Documentation": ["*.md", "*doc*", "*readme*"],
+    "Assets": ["*asset*", "*image*", "*static*", "*public*", "*font*", "*icon*"],
+    "Scripts": ["*script*", "*build*", "*deploy*", "*.sh", "*.ps1"],
+}
+
+
+def build_default_config(root: Path, **overrides: Any) -> TreeConfig:
+    """Build a :class:`TreeConfig` seeded with package defaults."""
+    defaults: dict[str, Any] = dict(
+        root=root,
+        max_depth=None,
+        include_hidden=False,
+        follow_symlinks=False,
+        show_size=False,
+        dirs_first=True,
+        output_format="unicode",
+        ignore_dirs=DEFAULT_IGNORE_DIRS,
+        ignore_patterns=DEFAULT_IGNORE_PATTERNS,
+        use_gitignore=False,
+        show_stats=False,
+    )
+    defaults.update(overrides)
+    return TreeConfig(**defaults)

treegetter/context.py

@@ -0,0 +1,123 @@
+"""AI Context Builder generating compact, LLM-ready repository intelligence payloads."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+from .models import (
+    AIContext,
+    ArchitectureInfo,
+    DependencyInfo,
+    EntryPoint,
+    FileMetadata,
+    FrameworkInfo,
+    LanguageStat,
+    RepositorySummary,
+)
+from .tokenizer import TokenOptimizer
+
+
+class AIContextBuilder:
+    """Builds compact structured context for LLMs."""
+
+    def build_context(
+        self,
+        root: Path,
+        summary: RepositorySummary,
+        tree_str: str,
+        arch: ArchitectureInfo,
+        entrypoints: list[EntryPoint],
+        deps: DependencyInfo,
+        files: Sequence[FileMetadata],
+        stats: dict,
+        frameworks: list[FrameworkInfo],
+        languages: dict[str, LanguageStat],
+        max_tokens: int | None = None,
+    ) -> AIContext:
+        """Construct AIContext data model."""
+        project_map: dict[str, list[str]] = {
+            "Controllers": [],
+            "Services": [],
+            "Repositories": [],
+            "Models": [],
+            "Routes": [],
+            "Components": [],
+            "Tests": [],
+            "Utilities": [],
+            "Configuration": [],
+            "Documentation": [],
+        }
+
+        important_files: list[dict[str, str]] = []
+        ignored_files: list[str] = [".git", "node_modules", "__pycache__", "dist", "build", ".venv"]
+
+        for f in files:
+            rel = self._to_rel_posix(f.path, root)
+            rel_lower = rel.lower()
+
+            if "controller" in rel_lower or "handler" in rel_lower:
+                project_map["Controllers"].append(rel)
+            elif "service" in rel_lower or "usecase" in rel_lower:
+                project_map["Services"].append(rel)
+            elif "repository" in rel_lower or "repo" in rel_lower or "store" in rel_lower:
+                project_map["Repositories"].append(rel)
+            elif "model" in rel_lower or "schema" in rel_lower or "entity" in rel_lower:
+                project_map["Models"].append(rel)
+            elif "route" in rel_lower or "api" in rel_lower:
+                project_map["Routes"].append(rel)
+            elif "component" in rel_lower or "view" in rel_lower:
+                project_map["Components"].append(rel)
+            elif "test" in rel_lower or "spec" in rel_lower:
+                project_map["Tests"].append(rel)
+            elif "util" in rel_lower or "helper" in rel_lower:
+                project_map["Utilities"].append(rel)
+            elif f.extension in (".toml", ".yaml", ".yml", ".json", ".env") or "config" in rel_lower:
+                project_map["Configuration"].append(rel)
+            elif f.extension in (".md", ".txt"):
+                project_map["Documentation"].append(rel)
+
+            if (
+                f.name.lower().startswith("readme")
+                or f.name in ("package.json", "pyproject.toml", "Cargo.toml", "go.mod", "Dockerfile")
+                or any(ep.path == rel for ep in entrypoints[:3])
+            ):
+                content_snippet = ""
+                if f.size < 50_000:
+                    try:
+                        content_snippet = f.path.read_text(encoding="utf-8", errors="ignore")[:500]
+                    except OSError:
+                        pass
+
+                important_files.append({
+                    "path": rel,
+                    "language": f.language,
+                    "snippet": content_snippet,
+                })
+
+        context = AIContext(
+            summary=summary.to_dict(),
+            folder_tree=tree_str,
+            architecture=arch.to_dict(),
+            entrypoints=[ep.to_dict() for ep in entrypoints],
+            dependencies=deps.to_dict(),
+            project_map={k: v[:20] for k, v in project_map.items() if v},
+            important_files=important_files[:10],
+            statistics=stats,
+            framework=[fw.to_dict() for fw in frameworks],
+            languages={k: v.to_dict() for k, v in languages.items()},
+            ignored_files=ignored_files,
+        )
+
+        if max_tokens is not None:
+            tree_str_trimmed = TokenOptimizer.trim_to_token_limit(tree_str, int(max_tokens * 0.4))
+            context.folder_tree = tree_str_trimmed
+
+        return context
+
+    @staticmethod
+    def _to_rel_posix(path: Path, root: Path) -> str:
+        try:
+            return path.resolve().relative_to(root.resolve()).as_posix()
+        except (OSError, ValueError):
+            return path.name