treegetter 2.0.0__tar.gz

treegetter-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rupam Manna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

treegetter-2.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include treegetter *.py py.typed

treegetter-2.0.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: treegetter
+Version: 2.0.0
+Summary: AI-Ready Repository Intelligence Engine for Agents
+Author-email: Rupam Manna <rupammanna8@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/RupamManna8/TreeGetter
+Project-URL: Documentation, https://rupammanna8.github.io/TreeGetter/
+Project-URL: Repository, https://github.com/RupamManna8/TreeGetter.git
+Project-URL: Bug Tracker, https://github.com/RupamManna8/TreeGetter/issues
+Project-URL: Changelog, https://github.com/RupamManna8/TreeGetter/blob/main/CHANGELOG.md
+Keywords: repository,directory-tree,ai-agent,codebase-intelligence,llm-context,token-optimizer,repo-parser,ast-analyzer,dependency-parser,architecture-detector
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TreeGetter Python Package
+
+[![PyPI Version](https://img.shields.io/pypi/v/treegetter.svg)](https://pypi.org/project/treegetter/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/treegetter.svg)](https://pypi.org/project/treegetter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**TreeGetter** is an AI-Ready Repository Intelligence Engine for Python. It transforms raw directory trees into compact, structured, token-optimized context payloads for AI coding agents.
+
+## Installation
+
+```bash
+pip install treegetter
+```
+
+## Usage
+
+```python
+from treegetter import Repository, get_tree
+
+# Backward compatible legacy API
+print(get_tree("./"))
+
+# High-Level AI Repository Intelligence Engine
+repo = Repository("./")
+
+# Repository Overview Summary
+print(repo.summary())
+
+# Token-optimized context for LLM agents
+print(repo.export_llm(max_tokens=4000))
+
+# Indexed O(1) Search
+results = repo.search("AuthController")
+```
+
+For full documentation, visit [https://rupammanna8.github.io/TreeGetter/](https://rupammanna8.github.io/TreeGetter/).

treegetter-2.0.0/README.md

@@ -0,0 +1,36 @@
+# TreeGetter Python Package
+
+[![PyPI Version](https://img.shields.io/pypi/v/treegetter.svg)](https://pypi.org/project/treegetter/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/treegetter.svg)](https://pypi.org/project/treegetter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**TreeGetter** is an AI-Ready Repository Intelligence Engine for Python. It transforms raw directory trees into compact, structured, token-optimized context payloads for AI coding agents.
+
+## Installation
+
+```bash
+pip install treegetter
+```
+
+## Usage
+
+```python
+from treegetter import Repository, get_tree
+
+# Backward compatible legacy API
+print(get_tree("./"))
+
+# High-Level AI Repository Intelligence Engine
+repo = Repository("./")
+
+# Repository Overview Summary
+print(repo.summary())
+
+# Token-optimized context for LLM agents
+print(repo.export_llm(max_tokens=4000))
+
+# Indexed O(1) Search
+results = repo.search("AuthController")
+```
+
+For full documentation, visit [https://rupammanna8.github.io/TreeGetter/](https://rupammanna8.github.io/TreeGetter/).

treegetter-2.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "treegetter"
+version = "2.0.0"
+description = "AI-Ready Repository Intelligence Engine for Agents"
+readme = "README.md"
+authors = [
+    { name = "Rupam Manna", email = "rupammanna8@gmail.com" }
+]
+license = { text = "MIT" }
+keywords = [
+    "repository",
+    "directory-tree",
+    "ai-agent",
+    "codebase-intelligence",
+    "llm-context",
+    "token-optimizer",
+    "repo-parser",
+    "ast-analyzer",
+    "dependency-parser",
+    "architecture-detector"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities"
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/RupamManna8/TreeGetter"
+Documentation = "https://rupammanna8.github.io/TreeGetter/"
+Repository = "https://github.com/RupamManna8/TreeGetter.git"
+"Bug Tracker" = "https://github.com/RupamManna8/TreeGetter/issues"
+Changelog = "https://github.com/RupamManna8/TreeGetter/blob/main/CHANGELOG.md"
+
+[project.scripts]
+treegetter = "treegetter.api:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["treegetter*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

treegetter-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

treegetter-2.0.0/tests/test_api.py

@@ -0,0 +1,44 @@
+"""Unit tests for backward compatible treegetter public API functions."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from treegetter import generate_tree, get_tree
+from treegetter.exceptions import InvalidPathError
+
+
+class TestApi(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        (self.root / "src").mkdir()
+        (self.root / "src" / "main.py").write_text("print('hello')")
+        (self.root / "README.md").write_text("# Test Repo")
+
+    def tearDown(self) -> None:
+        self.tmp.cleanup()
+
+    def test_get_tree_basic(self) -> None:
+        output = get_tree(self.root)
+        self.assertIn("src", output)
+        self.assertIn("main.py", output)
+        self.assertIn("README.md", output)
+
+    def test_generate_tree_json_format(self) -> None:
+        output = generate_tree(self.root, output_format="json", show_stats=True)
+        data = json.loads(output)
+        self.assertIn("tree", data)
+        self.assertIn("statistics", data)
+        self.assertEqual(data["tree"]["name"], self.root.name)
+
+    def test_invalid_path(self) -> None:
+        with self.assertRaises(InvalidPathError):
+            get_tree("/non/existent/path/for/test")
+
+
+if __name__ == "__main__":
+    unittest.main()

treegetter-2.0.0/tests/test_repository.py

@@ -0,0 +1,109 @@
+"""Unit tests for Repository intelligence class."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from treegetter import Repository
+from treegetter.models import (
+    AIContext,
+    ArchitectureInfo,
+    DependencyInfo,
+    FrameworkInfo,
+    RepositorySummary,
+)
+
+
+class TestRepository(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+
+        (self.root / "src" / "controllers").mkdir(parents=True)
+        (self.root / "src" / "services").mkdir(parents=True)
+        (self.root / "tests").mkdir(parents=True)
+
+        (self.root / "src" / "controllers" / "user_controller.py").write_text("# user controller\n" * 5)
+        (self.root / "src" / "services" / "user_service.py").write_text("# user service\n" * 10)
+        (self.root / "tests" / "test_user.py").write_text("# unit tests\n" * 3)
+
+        (self.root / "pyproject.toml").write_text('[tool.poetry.dependencies]\nfastapi = "^0.95.0"\n')
+        (self.root / "main.py").write_text("import fastapi\napp = fastapi.FastAPI()\n")
+        (self.root / "README.md").write_text("# Project Documentation\n")
+
+        self.repo = Repository(self.root)
+
+    def tearDown(self) -> None:
+        self.tmp.cleanup()
+
+    def test_tree(self) -> None:
+        tree_out = self.repo.tree()
+        self.assertIn("src", tree_out)
+        self.assertIn("main.py", tree_out)
+
+    def test_files_and_directories(self) -> None:
+        files = self.repo.files()
+        self.assertGreaterEqual(len(files), 4)
+
+        dirs = self.repo.directories()
+        self.assertIn("src", dirs)
+
+    def test_framework_and_detect(self) -> None:
+        fw = self.repo.framework()
+        self.assertIsInstance(fw, FrameworkInfo)
+
+        all_detected = self.repo.detect()
+        self.assertGreater(len(all_detected), 0)
+
+    def test_language(self) -> None:
+        langs = self.repo.language()
+        self.assertIn("Python", langs)
+
+    def test_dependencies(self) -> None:
+        deps = self.repo.dependencies()
+        self.assertIsInstance(deps, DependencyInfo)
+        self.assertIn("fastapi", deps.dependencies)
+
+    def test_architecture(self) -> None:
+        arch = self.repo.architecture()
+        self.assertIsInstance(arch, ArchitectureInfo)
+
+    def test_entrypoints(self) -> None:
+        eps = self.repo.entrypoints()
+        self.assertTrue(any(ep.path == "main.py" for ep in eps))
+
+    def test_statistics(self) -> None:
+        stats = self.repo.statistics()
+        self.assertEqual(stats["file_count"], len(self.repo.files()))
+
+    def test_summary(self) -> None:
+        summ = self.repo.summary()
+        self.assertIsInstance(summ, RepositorySummary)
+        self.assertEqual(summ.name, self.root.name)
+
+    def test_project_map(self) -> None:
+        pmap = self.repo.project_map()
+        self.assertIn("Controllers", pmap)
+
+    def test_search(self) -> None:
+        res = self.repo.search("user")
+        self.assertGreater(len(res), 0)
+
+    def test_context(self) -> None:
+        ctx = self.repo.context()
+        self.assertIsInstance(ctx, AIContext)
+
+    def test_readme(self) -> None:
+        rm = self.repo.readme()
+        self.assertIsNotNone(rm)
+
+    def test_exporters(self) -> None:
+        self.assertIn("{", self.repo.export_json())
+        self.assertIn("#", self.repo.export_markdown())
+        self.assertIn("REPOSITORY", self.repo.export_llm())
+
+
+if __name__ == "__main__":
+    unittest.main()

treegetter-2.0.0/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-2.0.0/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-2.0.0/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-2.0.0/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"},
+        )