tree2guide 1.0.0__py3-none-any.whl

tree2guide/__init__.py

@@ -0,0 +1,50 @@
+"""
+tree2guide — see your project structure clearly.
+
+Public API:
+    build_node_tree(root, matcher, options=None) -> TreeNode
+    build_tree(root, matcher, options=None) -> list[str]   # backward compat
+    TreeNode, TreeOptions
+    ExcludeMatcher, GitignoreRule, load_exclude_patterns
+    analyze(node) -> LlmSummary
+    render_markdown / render_text / render_json / render_yaml / render_html / render_llm
+"""
+
+from tree2guide.ignore import (
+    DEFAULT_EXCLUDES,
+    EXCLUDE_FILENAME,
+    ExcludeMatcher,
+    GitignoreRule,
+    load_exclude_patterns,
+)
+from tree2guide.llm import LlmSummary, analyze
+from tree2guide.renderers.html import render_html
+from tree2guide.renderers.json_renderer import render_json
+from tree2guide.renderers.llm import render_llm
+from tree2guide.renderers.markdown import render_markdown
+from tree2guide.renderers.text import render_text
+from tree2guide.renderers.yaml_renderer import render_yaml
+from tree2guide.scanner import TreeNode, TreeOptions, build_node_tree, build_tree
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "DEFAULT_EXCLUDES",
+    "EXCLUDE_FILENAME",
+    "ExcludeMatcher",
+    "GitignoreRule",
+    "load_exclude_patterns",
+    "TreeNode",
+    "TreeOptions",
+    "build_node_tree",
+    "build_tree",
+    "LlmSummary",
+    "analyze",
+    "render_markdown",
+    "render_text",
+    "render_json",
+    "render_yaml",
+    "render_html",
+    "render_llm",
+]

tree2guide/cli.py

@@ -0,0 +1,147 @@
+"""
+tree2guide.cli — argument parsing and the `tree2guide` command entry point.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from tree2guide.ignore import EXCLUDE_FILENAME, ExcludeMatcher, load_exclude_patterns
+from tree2guide.renderers.html import render_html
+from tree2guide.renderers.json_renderer import render_json
+from tree2guide.renderers.llm import render_llm
+from tree2guide.renderers.markdown import render_markdown
+from tree2guide.renderers.text import render_text
+from tree2guide.renderers.yaml_renderer import render_yaml
+from tree2guide.scanner import TreeOptions, build_node_tree
+
+_FORMAT_EXTENSIONS = {
+    "markdown": ".md",
+    "text":     ".txt",
+    "json":     ".json",
+    "yaml":     ".yaml",
+    "html":     ".html",
+    "llm":      ".txt",
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tree2guide",
+        description="Generate a structured tree view of a folder in multiple formats.",
+    )
+    parser.add_argument("target", help="Path to the target folder")
+    parser.add_argument(
+        "-o", "--output", default=None,
+        help="Output file path (default: <folder>_tree.<ext> based on --format)",
+    )
+    parser.add_argument(
+        "--exclude-file", default=None,
+        help=f"Path to exclude file (default: <target>/{EXCLUDE_FILENAME})",
+    )
+    parser.add_argument("--title", default=None, help="Optional title above the tree")
+    parser.add_argument(
+        "--no-footer", action="store_true",
+        help="Omit the author/license footer (markdown and html only)",
+    )
+    parser.add_argument(
+        "--stdout", action="store_true",
+        help="Print to stdout instead of writing a file",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["markdown", "text", "json", "yaml", "html", "llm"],
+        default="markdown",
+        help="Output format (default: markdown). Use 'llm' for an AI-friendly summary.",
+    )
+    parser.add_argument(
+        "--llm", action="store_true",
+        help="Shorthand for --format llm (AI-friendly project summary)",
+    )
+    parser.add_argument(
+        "--max-depth", type=int, default=None, metavar="N",
+        help="Limit recursion depth",
+    )
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--dirs-only", action="store_true", help="Only show directories")
+    group.add_argument("--files-only", action="store_true", help="Only show files")
+    parser.add_argument("--no-hidden", action="store_true", help="Skip dotfiles/dotfolders")
+    parser.add_argument(
+        "--sort",
+        choices=["dirs-first", "files-first", "alpha"],
+        default="dirs-first",
+        help="Sort order within each folder (default: dirs-first)",
+    )
+    return parser
+
+
+def _render(fmt: str, tree, title: str | None, include_footer: bool) -> str:
+    if fmt == "markdown":
+        return render_markdown(tree, title=title, include_footer=include_footer)
+    if fmt == "text":
+        return render_text(tree, title=title)
+    if fmt == "json":
+        return render_json(tree)
+    if fmt == "yaml":
+        return render_yaml(tree)
+    if fmt == "html":
+        return render_html(tree, title=title, include_footer=include_footer)
+    if fmt == "llm":
+        return render_llm(tree, title=title)
+    raise ValueError(f"Unknown format: {fmt}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # --llm is a shorthand for --format llm
+    fmt = "llm" if args.llm else args.format
+
+    root = Path(args.target).resolve()
+    if not root.is_dir():
+        print(f"Error: '{root}' is not a valid directory.", file=sys.stderr)
+        return 1
+
+    exclude_file = (
+        Path(args.exclude_file).resolve() if args.exclude_file else root / EXCLUDE_FILENAME
+    )
+    patterns = load_exclude_patterns(exclude_file)
+    matcher = ExcludeMatcher(patterns)
+
+    options = TreeOptions(
+        max_depth=args.max_depth,
+        dirs_only=args.dirs_only,
+        files_only=args.files_only,
+        no_hidden=args.no_hidden,
+        sort=args.sort,
+    )
+
+    tree = build_node_tree(root, matcher, options)
+    output = _render(fmt, tree, title=args.title, include_footer=not args.no_footer)
+
+    if args.stdout:
+        sys.stdout.buffer.write(output.encode("utf-8"))
+        return 0
+
+    ext = _FORMAT_EXTENSIONS[fmt]
+    # llm output gets a distinct suffix so it doesn't clobber a plain text file
+    suffix = "_llm" if fmt == "llm" else "_tree"
+    output_path = (
+        Path(args.output).resolve()
+        if args.output
+        else Path.cwd() / f"{root.name}{suffix}{ext}"
+    )
+    output_path.write_text(output, encoding="utf-8")
+
+    print(f"✅ Tree written to: {output_path}")
+    if exclude_file.is_file():
+        print(f"   Used exclude file: {exclude_file}")
+    else:
+        print(f"   No exclude file found at {exclude_file} (only defaults applied)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tree2guide/ignore.py

@@ -0,0 +1,92 @@
+"""
+tree2guide.ignore — gitignore-compatible pattern matching, zero dependencies.
+"""
+
+import re
+from pathlib import Path
+
+DEFAULT_EXCLUDES: list[str] = [
+    ".git",
+    ".tree2ignore",
+    "__pycache__",
+    "*.pyc",
+    ".DS_Store",
+]
+
+EXCLUDE_FILENAME = ".tree2ignore"
+
+
+def load_exclude_patterns(exclude_file: Path) -> list[str]:
+    patterns = list(DEFAULT_EXCLUDES)
+    if exclude_file.is_file():
+        for line in exclude_file.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            patterns.append(line.rstrip("\n"))
+    return patterns
+
+
+class GitignoreRule:
+    def __init__(self, raw: str):
+        pattern = raw
+        self.negate = pattern.startswith("!")
+        if self.negate:
+            pattern = pattern[1:]
+        self.dir_only = pattern.endswith("/")
+        if self.dir_only:
+            pattern = pattern[:-1]
+        self.anchored = pattern.startswith("/")
+        if self.anchored:
+            pattern = pattern[1:]
+        has_slash = "/" in pattern
+        if not has_slash and not self.anchored:
+            pattern = "**/" + pattern
+        self.regex = re.compile(self._translate(pattern))
+
+    @staticmethod
+    def _translate(pattern: str) -> str:
+        segments = pattern.split("/")
+        parts = []
+        for i, segment in enumerate(segments):
+            if segment == "**":
+                if i == 0 and i == len(segments) - 1:
+                    parts.append(".*")
+                elif i == 0:
+                    parts.append("(?:.*/)?")
+                elif i == len(segments) - 1:
+                    parts.append("(?:/.*)?" if parts else ".*")
+                else:
+                    parts.append("(?:[^/]+/)*")
+                continue
+            seg_regex = "".join(
+                "[^/]*" if c == "*" else "[^/]" if c == "?" else re.escape(c)
+                for c in segment
+            )
+            if parts and segments[i - 1] != "**":
+                parts.append("/")
+            parts.append(seg_regex)
+        body = "".join(parts)
+        return f"^{body}$"
+
+    def matches(self, rel_path: str, is_dir: bool) -> bool:
+        parts = rel_path.split("/")
+        if not (self.dir_only and not is_dir):
+            if self.regex.match(rel_path):
+                return True
+        for k in range(1, len(parts)):
+            if self.regex.match("/".join(parts[:k])):
+                return True
+        return False
+
+
+class ExcludeMatcher:
+    def __init__(self, patterns: list[str]):
+        self.rules: list[GitignoreRule] = [GitignoreRule(p) for p in patterns]
+
+    def is_excluded(self, rel_path: str, is_dir: bool) -> bool:
+        excluded = False
+        for rule in self.rules:
+            if rule.matches(rel_path, is_dir):
+                excluded = not rule.negate
+        return excluded

tree2guide/llm.py

@@ -0,0 +1,211 @@
+"""
+tree2guide.llm — rule-based project heuristics for --llm mode.
+
+Zero dependencies, zero network calls. All detection is done by inspecting
+the names present in the TreeNode tree that the scanner already built —
+no second filesystem pass is needed.
+
+Produces a structured LlmSummary dataclass that the LLM renderer uses to
+build its output.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from tree2guide.scanner import TreeNode
+
+
+# ---------------------------------------------------------------------------
+# Detection tables
+# ---------------------------------------------------------------------------
+
+# Maps a filename/pattern to (language_or_framework, display_label)
+_STACK_SIGNALS: list[tuple[str, str]] = [
+    # Python
+    ("pyproject.toml",        "Python (pyproject.toml)"),
+    ("setup.py",              "Python (setup.py)"),
+    ("requirements.txt",      "Python (requirements.txt)"),
+    ("Pipfile",               "Python (Pipfile)"),
+    ("poetry.lock",           "Python / Poetry"),
+    # JavaScript / TypeScript
+    ("package.json",          "Node.js / JavaScript"),
+    ("tsconfig.json",         "TypeScript"),
+    ("next.config.js",        "Next.js"),
+    ("next.config.ts",        "Next.js (TypeScript)"),
+    ("nuxt.config.ts",        "Nuxt.js"),
+    ("nuxt.config.js",        "Nuxt.js"),
+    ("vite.config.ts",        "Vite"),
+    ("vite.config.js",        "Vite"),
+    ("angular.json",          "Angular"),
+    ("svelte.config.js",      "SvelteKit"),
+    # Go
+    ("go.mod",                "Go"),
+    # Rust
+    ("Cargo.toml",            "Rust / Cargo"),
+    # Ruby
+    ("Gemfile",               "Ruby"),
+    ("Rakefile",              "Ruby / Rake"),
+    # Java / Kotlin / JVM
+    ("pom.xml",               "Java / Maven"),
+    ("build.gradle",          "Java / Gradle"),
+    ("build.gradle.kts",      "Kotlin / Gradle"),
+    # C / C++
+    ("CMakeLists.txt",        "C/C++ / CMake"),
+    ("Makefile",              "C/C++ / Make"),
+    # PHP
+    ("composer.json",         "PHP / Composer"),
+    # Swift / iOS
+    ("Package.swift",         "Swift / SPM"),
+    # Dart / Flutter
+    ("pubspec.yaml",          "Dart / Flutter"),
+    # .NET
+    ("*.csproj",              ".NET / C#"),
+    ("*.fsproj",              ".NET / F#"),
+    ("*.sln",                 ".NET Solution"),
+    # Elixir
+    ("mix.exs",               "Elixir / Mix"),
+    # Haskell
+    ("stack.yaml",            "Haskell / Stack"),
+    ("*.cabal",               "Haskell / Cabal"),
+    # Docker / infra
+    ("Dockerfile",            "Docker"),
+    ("docker-compose.yml",    "Docker Compose"),
+    ("docker-compose.yaml",   "Docker Compose"),
+]
+
+# Files/dirs whose presence is worth flagging
+_NOTABLE_FLAGS: list[tuple[str, str]] = [
+    (".env.example",          "Environment template (.env.example) present"),
+    (".env",                  "Live .env file present (check it's gitignored!)"),
+    ("tests",                 "Tests directory present"),
+    ("test",                  "Test directory present"),
+    ("__tests__",             "Jest-style __tests__ directory present"),
+    ("spec",                  "Spec directory present"),
+    (".github",               "GitHub Actions / workflows present"),
+    (".gitlab-ci.yml",        "GitLab CI config present"),
+    ("Jenkinsfile",           "Jenkins CI config present"),
+    (".circleci",             "CircleCI config present"),
+    ("azure-pipelines.yml",   "Azure Pipelines config present"),
+    ("LICENSE",               "LICENSE file present"),
+    ("LICENSE.md",            "LICENSE file present"),
+    ("CHANGELOG.md",          "CHANGELOG present"),
+    ("CONTRIBUTING.md",       "CONTRIBUTING guide present"),
+    ("Makefile",              "Makefile present (build/task automation)"),
+    ("docker-compose.yml",    "Docker Compose present"),
+    ("docker-compose.yaml",   "Docker Compose present"),
+    (".pre-commit-config.yaml", "Pre-commit hooks configured"),
+    ("renovate.json",         "Renovate dependency-update bot configured"),
+    (".editorconfig",         "EditorConfig present"),
+]
+
+
+# ---------------------------------------------------------------------------
+# Summary dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class LlmSummary:
+    """Structured heuristic summary of the project."""
+    detected_stack: list[str] = field(default_factory=list)
+    file_count: int = 0
+    dir_count: int = 0
+    notable_flags: list[str] = field(default_factory=list)
+    top_level_dirs: list[str] = field(default_factory=list)
+    top_level_files: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Detection logic
+# ---------------------------------------------------------------------------
+
+def _collect_all_names(node: TreeNode) -> tuple[set[str], set[str]]:
+    """
+    Walk the entire TreeNode tree and collect every file name and dir name
+    into two flat sets. Used for stack/flag detection without a second
+    filesystem pass.
+    """
+    files: set[str] = set()
+    dirs: set[str] = set()
+
+    def _walk(n: TreeNode) -> None:
+        for child in n.children:
+            if child.is_symlink:
+                continue
+            if child.is_dir:
+                dirs.add(child.name)
+                _walk(child)
+            else:
+                files.add(child.name)
+
+    _walk(node)
+    return files, dirs
+
+
+def _count_entries(node: TreeNode) -> tuple[int, int]:
+    """Return (total_files, total_dirs) recursively."""
+    files = dirs = 0
+    for child in node.children:
+        if child.is_symlink:
+            continue
+        if child.is_dir:
+            dirs += 1
+            f, d = _count_entries(child)
+            files += f
+            dirs += d
+        else:
+            files += 1
+    return files, dirs
+
+
+def _matches_pattern(name: str, pattern: str) -> bool:
+    """Simple glob-style match: supports leading/trailing '*' wildcards only."""
+    if pattern.startswith("*") and pattern.endswith("*"):
+        return pattern[1:-1] in name
+    if pattern.startswith("*"):
+        return name.endswith(pattern[1:])
+    if pattern.endswith("*"):
+        return name.startswith(pattern[:-1])
+    return name == pattern
+
+
+def analyze(node: TreeNode) -> LlmSummary:
+    """
+    Inspect a TreeNode tree and return an LlmSummary with detected stack,
+    counts, flags, and top-level structure. Pure rule-based, zero deps,
+    no filesystem access beyond the already-built tree.
+    """
+    summary = LlmSummary()
+
+    all_files, all_dirs = _collect_all_names(node)
+    all_names = all_files | all_dirs
+
+    # Stack detection — first match wins per signal, deduplicate labels
+    seen_labels: set[str] = set()
+    for pattern, label in _STACK_SIGNALS:
+        for name in all_names:
+            if _matches_pattern(name, pattern) and label not in seen_labels:
+                summary.detected_stack.append(label)
+                seen_labels.add(label)
+                break
+
+    # Notable flags
+    seen_flags: set[str] = set()
+    for pattern, message in _NOTABLE_FLAGS:
+        for name in all_names:
+            if _matches_pattern(name, pattern) and message not in seen_flags:
+                summary.notable_flags.append(message)
+                seen_flags.add(message)
+                break
+
+    # Counts
+    summary.file_count, summary.dir_count = _count_entries(node)
+
+    # Top-level structure
+    for child in node.children:
+        if child.is_symlink:
+            continue
+        if child.is_dir:
+            summary.top_level_dirs.append(child.name + "/")
+        else:
+            summary.top_level_files.append(child.name)
+
+    return summary

tree2guide/renderers/__init__.py

@@ -0,0 +1,7 @@
+"""
+tree2guide.renderers — output formatters for a tree built by tree2guide.scanner.
+
+Renderers: markdown (default), text, json, yaml, html, llm.
+Each takes a TreeNode and returns a string. Only the llm renderer also
+calls tree2guide.llm.analyze() to attach heuristic metadata.
+"""