tree2guide 1.0.0__py3-none-any.whl

tree2guide/renderers/html.py

@@ -0,0 +1,218 @@
+"""
+tree2guide.renderers.html — renders the tree as a self-contained HTML page.
+
+Produces a single .html file with:
+  - Collapsible folder nodes (pure CSS + minimal JS, no external deps)
+  - Expand/collapse all buttons
+  - A monospace tree with the same connector characters as the text/markdown renderers
+  - Clean, minimal styling that works in any modern browser
+  - An optional title shown as a <h1>
+  - An optional attribution footer
+
+No external CSS frameworks, fonts, or scripts are loaded — the file works
+fully offline.
+"""
+
+from __future__ import annotations
+from tree2guide.scanner import TreeNode
+
+_CSS = """\
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+    font-family: system-ui, -apple-system, sans-serif;
+    background: #0f1117;
+    color: #e2e8f0;
+    min-height: 100vh;
+    padding: 2rem;
+}
+h1 { font-size: 1.5rem; font-weight: 600; margin-bottom: 1.25rem; color: #f8fafc; }
+.controls { margin-bottom: 1rem; display: flex; gap: 0.5rem; }
+button {
+    background: #1e2433;
+    color: #94a3b8;
+    border: 1px solid #2d3748;
+    border-radius: 6px;
+    padding: 0.3rem 0.75rem;
+    font-size: 0.8rem;
+    cursor: pointer;
+    transition: background 0.15s, color 0.15s;
+}
+button:hover { background: #2d3748; color: #e2e8f0; }
+.tree {
+    font-family: 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+    font-size: 0.88rem;
+    line-height: 1.7;
+    background: #1a1f2e;
+    border: 1px solid #2d3748;
+    border-radius: 10px;
+    padding: 1.25rem 1.5rem;
+    overflow-x: auto;
+}
+ul { list-style: none; padding: 0; }
+li { white-space: nowrap; }
+.entry { display: inline-flex; align-items: center; gap: 0.3rem; }
+.connector { color: #4a5568; user-select: none; }
+.toggle {
+    cursor: pointer;
+    background: none;
+    border: none;
+    padding: 0;
+    font: inherit;
+    color: inherit;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.3rem;
+}
+.toggle:hover .dirname { color: #7dd3fc; }
+.icon { font-size: 0.8em; color: #64748b; user-select: none; transition: transform 0.15s; }
+.collapsed > .children { display: none; }
+.collapsed .icon { transform: rotate(-90deg); }
+.dirname { color: #93c5fd; font-weight: 500; }
+.filename { color: #e2e8f0; }
+.symlink { color: #a78bfa; }
+.symlink-arrow { color: #64748b; }
+.root { color: #34d399; font-weight: 600; }
+footer {
+    margin-top: 1.5rem;
+    font-size: 0.78rem;
+    color: #4a5568;
+}
+footer a { color: #64748b; }
+"""
+
+_JS = """\
+function expandAll() {
+    document.querySelectorAll('.dir-item').forEach(el => el.classList.remove('collapsed'));
+}
+function collapseAll() {
+    document.querySelectorAll('.dir-item').forEach(el => el.classList.add('collapsed'));
+}
+function toggle(el) {
+    el.closest('.dir-item').classList.toggle('collapsed');
+}
+"""
+
+FOOTER_HTML = (
+    '<footer>Generated with '
+    '<a href="https://github.com/law4percent/tree2guide">tree2guide</a> '
+    'by <a href="https://github.com/law4percent">Lawrence Roble</a> '
+    '— open source, MIT licensed.</footer>'
+)
+
+
+def _node_to_html(node: TreeNode, prefix: str = "", is_last: bool = True, is_root: bool = False) -> list[str]:
+    lines: list[str] = []
+
+    if is_root:
+        # Root node — no connector, special styling, always expanded
+        lines.append('<li class="dir-item">')
+        lines.append(
+            f'  <span class="entry">'
+            f'<button class="toggle" onclick="toggle(this)">'
+            f'<span class="icon">▾</span>'
+            f'<span class="root">{_esc(node.name)}/</span>'
+            f'</button></span>'
+        )
+        if node.children:
+            lines.append('  <ul class="children">')
+            for i, child in enumerate(node.children):
+                lines.extend(_node_to_html(child, prefix="", is_last=(i == len(node.children) - 1)))
+            lines.append("  </ul>")
+        lines.append("</li>")
+        return lines
+
+    connector = "└── " if is_last else "├── "
+    child_prefix = prefix + ("    " if is_last else "│   ")
+
+    if node.is_symlink:
+        lines.append("<li>")
+        lines.append(
+            f'  <span class="entry">'
+            f'<span class="connector">{_esc(prefix + connector)}</span>'
+            f'<span class="symlink">{_esc(node.name)}</span>'
+            f'<span class="symlink-arrow"> -> </span>'
+            f'<span class="symlink">{_esc(node.symlink_target or "")}</span>'
+            f'</span>'
+        )
+        lines.append("</li>")
+        return lines
+
+    if not node.is_dir:
+        lines.append("<li>")
+        lines.append(
+            f'  <span class="entry">'
+            f'<span class="connector">{_esc(prefix + connector)}</span>'
+            f'<span class="filename">{_esc(node.name)}</span>'
+            f'</span>'
+        )
+        lines.append("</li>")
+        return lines
+
+    # Directory — collapsible
+    lines.append('<li class="dir-item">')
+    lines.append(
+        f'  <span class="entry">'
+        f'<span class="connector">{_esc(prefix + connector)}</span>'
+        f'<button class="toggle" onclick="toggle(this)">'
+        f'<span class="icon">▾</span>'
+        f'<span class="dirname">{_esc(node.name)}/</span>'
+        f'</button></span>'
+    )
+    if node.children:
+        lines.append('  <ul class="children">')
+        for i, child in enumerate(node.children):
+            lines.extend(_node_to_html(child, prefix=child_prefix, is_last=(i == len(node.children) - 1)))
+        lines.append("  </ul>")
+    lines.append("</li>")
+    return lines
+
+
+def _esc(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def render_html(
+    tree: TreeNode,
+    title: str | None = None,
+    include_footer: bool = True,
+) -> str:
+    """
+    Render a TreeNode as a self-contained HTML page string with a trailing newline.
+    """
+    title_tag = title or f"{tree.name} — tree2guide"
+
+    body_parts: list[str] = []
+    if title:
+        body_parts.append(f"<h1>{_esc(title)}</h1>")
+    body_parts.append(
+        '<div class="controls">'
+        '<button onclick="expandAll()">Expand all</button>'
+        '<button onclick="collapseAll()">Collapse all</button>'
+        '</div>'
+    )
+    body_parts.append('<div class="tree"><ul>')
+    body_parts.extend(_node_to_html(tree, is_root=True))
+    body_parts.append("</ul></div>")
+    if include_footer:
+        body_parts.append(FOOTER_HTML)
+
+    body = "\n".join(body_parts)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>{_esc(title_tag)}</title>
+<style>
+{_CSS}
+</style>
+</head>
+<body>
+{body}
+<script>
+{_JS}
+</script>
+</body>
+</html>
+"""

tree2guide/renderers/json_renderer.py

@@ -0,0 +1,48 @@
+"""
+tree2guide.renderers.json_renderer — renders the tree as a JSON document.
+
+The JSON shape is designed to be stable and easy to consume by other tools
+(the --llm mode in Phase 4, web-based interactive visualizations, etc.):
+
+    {
+        "name": "src",
+        "type": "directory",
+        "children": [
+            { "name": "main.py", "type": "file" },
+            { "name": "api", "type": "directory", "children": [...] }
+        ]
+    }
+
+Symlinks carry an extra "target" key and have type "symlink".
+"""
+
+from __future__ import annotations
+import json
+from tree2guide.scanner import TreeNode
+
+
+def _node_to_dict(node: TreeNode) -> dict:
+    if node.is_symlink:
+        return {
+            "name": node.name,
+            "type": "symlink",
+            "target": node.symlink_target,
+        }
+    if node.is_dir:
+        result: dict = {
+            "name": node.name,
+            "type": "directory",
+        }
+        if node.children:
+            result["children"] = [_node_to_dict(c) for c in node.children]
+        else:
+            result["children"] = []
+        return result
+    return {"name": node.name, "type": "file"}
+
+
+def render_json(tree: TreeNode, indent: int = 2) -> str:
+    """
+    Render a TreeNode as a pretty-printed JSON string with a trailing newline.
+    """
+    return json.dumps(_node_to_dict(tree), indent=indent) + "\n"

tree2guide/renderers/llm.py

@@ -0,0 +1,81 @@
+"""
+tree2guide.renderers.llm — AI-consumption-friendly project summary renderer.
+
+Produces a structured plain-text document optimised for pasting into an LLM
+context window. The format is deliberately verbose and unambiguous: explicit
+labels, no markdown fences that an LLM might misread as code to execute,
+and a tree that uses the same connector characters humans are used to so
+spatial relationships are clear.
+
+No network calls, no API keys, no third-party dependencies.
+"""
+
+from __future__ import annotations
+from tree2guide.llm import LlmSummary, analyze
+from tree2guide.scanner import TreeNode, render_lines
+
+
+_SEPARATOR = "=" * 60
+
+
+def render_llm(tree: TreeNode, title: str | None = None) -> str:
+    """
+    Render a TreeNode as an LLM-friendly project summary.
+    Returns a string with a trailing newline.
+    """
+    summary: LlmSummary = analyze(tree)
+    project_name = title or tree.name
+    lines: list[str] = []
+
+    # ------------------------------------------------------------------ header
+    lines.append(_SEPARATOR)
+    lines.append(f"PROJECT STRUCTURE SUMMARY: {project_name}")
+    lines.append(_SEPARATOR)
+    lines.append("")
+
+    # ----------------------------------------------------------- detected stack
+    lines.append("DETECTED STACK / LANGUAGE:")
+    if summary.detected_stack:
+        for item in summary.detected_stack:
+            lines.append(f"  - {item}")
+    else:
+        lines.append("  (No known stack signals detected)")
+    lines.append("")
+
+    # ------------------------------------------------------------------ counts
+    lines.append("SIZE:")
+    lines.append(f"  Files      : {summary.file_count}")
+    lines.append(f"  Directories: {summary.dir_count}")
+    lines.append("")
+
+    # --------------------------------------------------------- top-level layout
+    lines.append("TOP-LEVEL LAYOUT:")
+    if summary.top_level_dirs:
+        lines.append("  Directories:")
+        for d in summary.top_level_dirs:
+            lines.append(f"    {d}")
+    if summary.top_level_files:
+        lines.append("  Files:")
+        for f in summary.top_level_files:
+            lines.append(f"    {f}")
+    lines.append("")
+
+    # --------------------------------------------------------------- flags
+    if summary.notable_flags:
+        lines.append("NOTABLE FLAGS:")
+        for flag in summary.notable_flags:
+            lines.append(f"  - {flag}")
+        lines.append("")
+
+    # --------------------------------------------------------------- full tree
+    lines.append(_SEPARATOR)
+    lines.append("FULL DIRECTORY TREE:")
+    lines.append(_SEPARATOR)
+    lines.append("")
+    lines.extend(render_lines(tree))
+    lines.append("")
+    lines.append(_SEPARATOR)
+    lines.append("END OF PROJECT STRUCTURE SUMMARY")
+    lines.append(_SEPARATOR)
+
+    return "\n".join(lines) + "\n"

tree2guide/renderers/markdown.py

@@ -0,0 +1,39 @@
+"""
+tree2guide.renderers.markdown — renders the tree as a markdown code block.
+"""
+
+from __future__ import annotations
+from tree2guide.scanner import TreeNode, render_lines
+
+FOOTER = (
+    "*Generated with [tree2guide](https://github.com/law4percent/tree2guide) "
+    "by Lawrence Roble ([@law4percent](https://github.com/law4percent)) "
+    "— open source, MIT licensed. Contributions welcome!*"
+)
+
+
+def render_markdown(
+    tree: "TreeNode | list[str]",
+    title: str | None = None,
+    include_footer: bool = True,
+) -> str:
+    """
+    Render a TreeNode (or raw line list for backward compat) as a markdown document.
+    Returns a string with a trailing newline.
+    """
+    if isinstance(tree, list):
+        lines = tree
+    else:
+        lines = render_lines(tree)
+
+    md: list[str] = []
+    if title:
+        md.append(f"# {title}\n")
+    md.append("```")
+    md.extend(lines)
+    md.append("```")
+    if include_footer:
+        md.append("")
+        md.append("---")
+        md.append(FOOTER)
+    return "\n".join(md) + "\n"

tree2guide/renderers/text.py

@@ -0,0 +1,29 @@
+"""
+tree2guide.renderers.text — renders the tree as plain text (no markdown fencing).
+
+Identical visual output to the markdown renderer but with no ``` fences,
+no title heading syntax, and no footer — just the raw tree lines.
+Useful for terminal output, clipboard piping, and non-markdown tools.
+"""
+
+from __future__ import annotations
+from tree2guide.scanner import TreeNode, render_lines
+
+
+def render_text(
+    tree: "TreeNode | list[str]",
+    title: str | None = None,
+) -> str:
+    """
+    Render a TreeNode as plain text. Returns a string with a trailing newline.
+    Title (if given) is printed as a plain line above the tree, not a heading.
+    """
+    lines: list[str] = []
+    if title:
+        lines.append(title)
+        lines.append("")
+    if isinstance(tree, list):
+        lines.extend(tree)
+    else:
+        lines.extend(render_lines(tree))
+    return "\n".join(lines) + "\n"

tree2guide/renderers/yaml_renderer.py

@@ -0,0 +1,64 @@
+"""
+tree2guide.renderers.yaml — renders the tree as YAML, zero third-party deps.
+
+Output shape mirrors the JSON renderer exactly, hand-serialized so the
+package stays dependency-free. Each node is a YAML mapping; children are
+a YAML sequence of nested mappings.
+
+    name: src
+    type: directory
+    children:
+      - name: main.py
+        type: file
+      - name: api
+        type: directory
+        children: []
+"""
+
+from __future__ import annotations
+from tree2guide.scanner import TreeNode
+
+
+def _node_to_yaml(node: TreeNode, indent: int) -> list[str]:
+    pad = " " * indent
+    lines: list[str] = []
+
+    if node.is_symlink:
+        lines.append(f"{pad}name: {_scalar(node.name)}")
+        lines.append(f"{pad}type: symlink")
+        lines.append(f"{pad}target: {_scalar(node.symlink_target or '')}")
+        return lines
+
+    lines.append(f"{pad}name: {_scalar(node.name)}")
+    if node.is_dir:
+        lines.append(f"{pad}type: directory")
+        lines.append(f"{pad}children:")
+        if node.children:
+            for child in node.children:
+                lines.append(f"{pad}  -")
+                lines.extend(_node_to_yaml(child, indent + 4))
+        else:
+            lines.append(f"{pad}  []")
+    else:
+        lines.append(f"{pad}type: file")
+
+    return lines
+
+
+def _scalar(value: str) -> str:
+    """Quote a scalar value if it contains YAML-unsafe characters."""
+    unsafe = {":", "#", "{", "}", "[", "]", ",", "&", "*", "?", "|", "-", "<", ">",
+               "=", "!", "%", "@", "`", "'", '"', "\n", "\r"}
+    if any(c in value for c in unsafe) or not value:
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return value
+
+
+def render_yaml(tree: TreeNode) -> str:
+    """
+    Render a TreeNode as a YAML string with a trailing newline.
+    No third-party dependencies — hand-serialized to keep the package zero-dep.
+    """
+    lines = _node_to_yaml(tree, indent=0)
+    return "\n".join(lines) + "\n"

tree2guide/scanner.py

@@ -0,0 +1,149 @@
+"""
+tree2guide.scanner — walks the filesystem and builds a tree model.
+"""
+
+from __future__ import annotations
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from tree2guide.ignore import ExcludeMatcher
+
+
+@dataclass
+class TreeNode:
+    """Internal tree model — one node per filesystem entry."""
+    name: str
+    is_dir: bool
+    is_symlink: bool = False
+    symlink_target: str | None = None
+    children: list["TreeNode"] = field(default_factory=list)
+
+
+@dataclass
+class TreeOptions:
+    max_depth: int | None = None
+    dirs_only: bool = False
+    files_only: bool = False
+    no_hidden: bool = False
+    sort: str = "dirs-first"  # "dirs-first" | "files-first" | "alpha"
+
+
+def _sort_key(sort_mode: str):
+    if sort_mode == "alpha":
+        return lambda p: p.name.lower()
+    if sort_mode == "files-first":
+        return lambda p: (p.is_dir(), p.name.lower())
+    return lambda p: (p.is_file(), p.name.lower())
+
+
+def build_node_tree(
+    root: Path,
+    matcher: ExcludeMatcher,
+    options: TreeOptions | None = None,
+) -> TreeNode:
+    """
+    Build and return a TreeNode tree rooted at `root`.
+
+    This is the canonical Scanner output — a single O(n) pass that
+    every renderer consumes. build_tree() is kept for backward compat
+    and simply calls render_lines() on the result.
+    """
+    options = options or TreeOptions()
+    sort_key = _sort_key(options.sort)
+
+    def rel_str(path: Path) -> str:
+        return path.relative_to(root).as_posix()
+
+    def is_excluded(path: Path, is_dir: bool) -> bool:
+        return matcher.is_excluded(rel_str(path), is_dir)
+
+    def recurse(dir_path: Path, depth: int) -> list[TreeNode]:
+        if options.max_depth is not None and depth > options.max_depth:
+            return []
+        try:
+            entries = sorted(dir_path.iterdir(), key=sort_key)
+        except PermissionError:
+            return []
+
+        children: list[TreeNode] = []
+        for entry in entries:
+            if options.no_hidden and entry.name.startswith("."):
+                continue
+
+            is_symlink = entry.is_symlink()
+            entry_is_dir = entry.is_dir() and not is_symlink
+            excluded = is_excluded(entry, entry.is_dir())
+
+            child_nodes = recurse(entry, depth + 1) if entry_is_dir else []
+
+            hide_for_type = (
+                (options.dirs_only and not entry.is_dir())
+                or (options.files_only and entry.is_dir() and not child_nodes)
+            )
+            if hide_for_type:
+                continue
+
+            if excluded and not (entry_is_dir and child_nodes):
+                continue
+
+            symlink_target: str | None = None
+            if is_symlink:
+                try:
+                    symlink_target = str(Path(os.readlink(entry)))
+                except OSError:
+                    symlink_target = str(entry.resolve())
+
+            node = TreeNode(
+                name=entry.name,
+                is_dir=entry.is_dir(),
+                is_symlink=is_symlink,
+                symlink_target=symlink_target,
+                children=child_nodes,
+            )
+            children.append(node)
+
+        return children
+
+    root_node = TreeNode(name=root.name, is_dir=True, children=recurse(root, depth=1))
+    return root_node
+
+
+def render_lines(node: TreeNode, prefix: str = "") -> list[str]:
+    """Flatten a TreeNode tree into connector-prefixed display lines (for text/markdown)."""
+    lines: list[str] = [f"{node.name}/"]
+    _render_children(node.children, prefix="", lines=lines)
+    return lines
+
+
+def _render_children(children: list[TreeNode], prefix: str, lines: list[str]) -> None:
+    for i, child in enumerate(children):
+        is_last = i == len(children) - 1
+        connector = "└── " if is_last else "├── "
+
+        if child.is_symlink:
+            display = f"{child.name} -> {child.symlink_target}"
+        elif child.is_dir:
+            display = f"{child.name}/"
+        else:
+            display = child.name
+
+        lines.append(f"{prefix}{connector}{display}")
+
+        if child.is_dir and not child.is_symlink and child.children:
+            extension = "    " if is_last else "│   "
+            _render_children(child.children, prefix + extension, lines)
+
+
+# ---------------------------------------------------------------------------
+# Backward-compatible API — kept so existing callers don't break
+# ---------------------------------------------------------------------------
+
+def build_tree(
+    root: Path,
+    matcher: ExcludeMatcher,
+    options: TreeOptions | None = None,
+) -> list[str]:
+    """Return tree display lines (backward-compatible wrapper around build_node_tree)."""
+    node = build_node_tree(root, matcher, options)
+    return render_lines(node)