Skip to content

Agent Zero AI framework

File Tree: Main implementation of helper + tests

Rafael Uzarowskic2b772875eda
diff --git a/python/helpers/files.py b/python/helpers/files.py
index ef8587ec6..5d210e1c3 100644
--- a/python/helpers/files.py
+++ b/python/helpers/files.py
@@ -1,25 +1,29 @@
+from __future__ import annotations
+
from abc import ABC, abstractmethod
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timezone
from fnmatch import fnmatch
import json
-from ntpath import isabs
import os
-import sys
import re
import base64
import shutil
import tempfile
-from typing import Any
+from typing import Any, Callable, Iterable, Literal, Optional, Sequence, Type, cast
import zipfile
-import importlib
-import importlib.util
-import inspect
import glob
import mimetypes
+from pathspec import PathSpec
+
class VariablesPlugin(ABC):
@abstractmethod
- def get_variables(self, file: str, backup_dirs: list[str] | None = None) -> dict[str, Any]: # type: ignore
+ def get_variables(
+ self, file: str, backup_dirs: list[str] | None = None
+ ) -> dict[str, Any]: # type: ignore[override]
pass
@@ -44,11 +48,14 @@ def load_plugin_variables(
from python.helpers import extract_tools
+ plugin_base: Any = VariablesPlugin
classes = extract_tools.load_classes_from_file(
- plugin_file, VariablesPlugin, one_per_file=False
+ plugin_file, plugin_base, one_per_file=False
)
for cls in classes:
- return cls().get_variables(file, backup_dirs) # type: ignore < abstract class here is ok, it is always a subclass
+ if isinstance(cls, type) and issubclass(cls, VariablesPlugin):
+ plugin_cls = cast(Type[VariablesPlugin], cls)
+ return plugin_cls().get_variables(file, backup_dirs)
# load python code and extract variables variables from it
# module = None
@@ -347,7 +354,7 @@ def delete_dir(relative_path: str):
# try again after changing permissions
shutil.rmtree(abs_path, ignore_errors=True)
- except:
+ except Exception:
# suppress all errors - we're ensuring no errors propagate
pass
@@ -530,3 +537,557 @@ def read_text_files_in_dir(
except Exception:
continue
return result
+
+
+SORT_BY_NAME = "name"
+SORT_BY_CREATED = "created"
+SORT_BY_MODIFIED = "modified"
+
+SORT_ASC = "asc"
+SORT_DESC = "desc"
+
+OUTPUT_MODE_STRING = "string"
+OUTPUT_MODE_FLAT = "flat"
+OUTPUT_MODE_NESTED = "nested"
+
+
+def file_tree(
+ relative_path: str,
+ *,
+ max_depth: int = 0,
+ max_lines: int = 0,
+ folders_first: bool = True,
+ max_folders: int | None = None,
+ max_files: int | None = None,
+ sort: tuple[str, str] = (SORT_BY_MODIFIED, SORT_DESC),
+ ignore: str | None = None,
+ output_mode: str = OUTPUT_MODE_STRING,
+) -> str | list[dict]:
+ """Render a directory tree relative to the repository base path.
+
+ Parameters:
+ relative_path: Base directory (relative to project root) to scan with :func:`get_abs_path`.
+ max_depth: Maximum depth of traversal (0 = unlimited). Depth starts at 1 for root entries.
+ max_lines: Global limit for rendered lines (0 = unlimited). When exceeded, the current depth
+ finishes rendering before deeper levels are skipped.
+ folders_first: When True, folders render before files within each directory.
+ max_folders: Optional per-directory cap (0 = unlimited) on rendered folder entries before adding a
+ ``# N more folders`` comment. When only a single folder exceeds the limit and ``max_folders`` is greater than zero, that folder is rendered
+ directly instead of emitting a summary comment.
+ max_files: Optional per-directory cap (0 = unlimited) on rendered file entries before adding a ``# N more files`` comment.
+ As with folders, a single excess file is rendered when ``max_files`` is greater than zero.
+ sort: Tuple of ``(key, direction)`` where key is one of :data:`SORT_BY_NAME`,
+ :data:`SORT_BY_CREATED`, or :data:`SORT_BY_MODIFIED`; direction is :data:`SORT_ASC`
+ or :data:`SORT_DESC`.
+ ignore: Inline ``.gitignore`` content or ``file:`` reference. Examples::
+
+ ignore=\"\"\"\\n*.pyc\\n__pycache__/\\n!important.py\\n\"\"\"
+ ignore=\"file:.gitignore\" # relative to scan root
+ ignore=\"file://.gitignore\" # URI-style relative path
+ ignore=\"file:/abs/path/.gitignore\"
+ ignore=\"file:///abs/path/.gitignore\"
+
+ output_mode: One of :data:`OUTPUT_MODE_STRING`, :data:`OUTPUT_MODE_FLAT`, or
+ :data:`OUTPUT_MODE_NESTED`.
+
+ Returns:
+ ``OUTPUT_MODE_STRING`` → ``str``: multi-line ASCII tree.
+ ``OUTPUT_MODE_FLAT`` → ``list[dict]``: flattened sequence of TreeItem dictionaries.
+ ``OUTPUT_MODE_NESTED`` → ``list[dict]``: nested TreeItem dictionaries where folders
+ include ``items`` arrays.
+
+ Notes:
+ * The utility is synchronous; avoid calling from latency-sensitive async loops.
+ * The ASCII renderer walks the established tree depth-first so connectors reflect parent/child structure,
+ while traversal and limit calculations remain breadth-first by depth.
+ * ``created`` and ``modified`` values in structured outputs are timezone-aware UTC
+ :class:`datetime.datetime` objects::
+
+ item = flat_items[0]
+ iso = item[\"created\"].isoformat()
+ epoch = item[\"created\"].timestamp()
+
+ """
+ abs_root = get_abs_path(relative_path)
+
+ if not os.path.exists(abs_root):
+ raise FileNotFoundError(f"Path does not exist: {relative_path!r}")
+ if not os.path.isdir(abs_root):
+ raise NotADirectoryError(f"Expected a directory, received: {relative_path!r}")
+
+ sort_key, sort_direction = sort
+ if sort_key not in {SORT_BY_NAME, SORT_BY_CREATED, SORT_BY_MODIFIED}:
+ raise ValueError(f"Unsupported sort key: {sort_key!r}")
+ if sort_direction not in {SORT_ASC, SORT_DESC}:
+ raise ValueError(f"Unsupported sort direction: {sort_direction!r}")
+ if output_mode not in {OUTPUT_MODE_STRING, OUTPUT_MODE_FLAT, OUTPUT_MODE_NESTED}:
+ raise ValueError(f"Unsupported output mode: {output_mode!r}")
+ if max_depth < 0:
+ raise ValueError("max_depth must be >= 0")
+ if max_lines < 0:
+ raise ValueError("max_lines must be >= 0")
+
+ ignore_spec = _resolve_ignore_patterns(ignore, abs_root)
+
+ root_stat = os.stat(abs_root, follow_symlinks=False)
+ root_name = os.path.basename(os.path.normpath(abs_root)) or os.path.basename(abs_root)
+ root_node = _TreeEntry(
+ name=root_name,
+ level=0,
+ item_type="folder",
+ created=datetime.fromtimestamp(root_stat.st_ctime, tz=timezone.utc),
+ modified=datetime.fromtimestamp(root_stat.st_mtime, tz=timezone.utc),
+ parent=None,
+ items=[],
+ rel_path="",
+ )
+
+ queue: deque[tuple[_TreeEntry, str, int]] = deque([(root_node, abs_root, 1)])
+ nodes_in_order: list[_TreeEntry] = []
+ limit_level: Optional[int] = None
+ visibility_cache: dict[str, bool] = {}
+
+ def make_entry(entry: os.DirEntry, parent: _TreeEntry, level: int, item_type: Literal["file", "folder"]) -> _TreeEntry:
+ stat = entry.stat(follow_symlinks=False)
+ rel_path = os.path.relpath(entry.path, abs_root)
+ rel_posix = _normalize_relative_path(rel_path)
+ return _TreeEntry(
+ name=entry.name,
+ level=level,
+ item_type=item_type,
+ created=datetime.fromtimestamp(stat.st_ctime, tz=timezone.utc),
+ modified=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc),
+ parent=parent,
+ items=[] if item_type == "folder" else None,
+ rel_path=rel_posix,
+ )
+
+ while queue:
+ parent_node, current_dir, level = queue.popleft()
+
+ if max_depth and level > max_depth:
+ continue
+
+ remaining_depth = max_depth - level if max_depth else -1
+ folders, files = _list_directory_children(
+ current_dir,
+ abs_root,
+ ignore_spec,
+ max_depth_remaining=remaining_depth,
+ cache=visibility_cache,
+ )
+
+ folder_entries = [make_entry(folder, parent_node, level, "folder") for folder in folders]
+ file_entries = [make_entry(file_entry, parent_node, level, "file") for file_entry in files]
+
+ children = _apply_sorting_and_limits(
+ folder_entries,
+ file_entries,
+ folders_first=folders_first,
+ sort=sort,
+ max_folders=max_folders,
+ max_files=max_files,
+ directory_node=parent_node,
+ )
+
+ parent_node.items = children
+ nodes_in_order.extend(children)
+
+ if max_lines and limit_level is None and len(nodes_in_order) >= max_lines:
+ limit_level = level
+
+ for child in children:
+ if child.item_type != "folder":
+ continue
+ if max_depth and level >= max_depth:
+ continue
+ if limit_level is not None and level >= limit_level:
+ continue
+ child_abs = os.path.join(current_dir, child.name)
+ queue.append((child, child_abs, level + 1))
+
+ pruned_nodes: list[_TreeEntry] = nodes_in_order
+ if max_lines and limit_level is not None:
+ _prune_nested_children(
+ root_node,
+ lambda entry: entry.level <= limit_level,
+ )
+ pruned_nodes = [node for node in nodes_in_order if node.level <= limit_level]
+
+ visible_nodes: list[_TreeEntry]
+ if max_lines and limit_level is None:
+ visible_nodes = pruned_nodes[:max_lines]
+ else:
+ visible_nodes = pruned_nodes
+
+ visible_ids = {id(node) for node in visible_nodes}
+ if visible_ids:
+ _prune_to_visible(root_node, visible_ids)
+
+ _mark_last_flags(root_node)
+ _refresh_render_metadata(root_node)
+
+ def iter_visible() -> Iterable[_TreeEntry]:
+ for node in _iter_depth_first(root_node.items or []):
+ if not visible_ids or id(node) in visible_ids:
+ yield node
+
+ if output_mode == OUTPUT_MODE_STRING:
+ display_name = relative_path.strip() or root_name
+ root_line = f"{display_name.rstrip(os.sep)}/"
+ lines = [root_line]
+ for node in iter_visible():
+ lines.append(node.text)
+ return "\n".join(lines)
+
+ if output_mode == OUTPUT_MODE_FLAT:
+ return _build_tree_items_flat(list(iter_visible()))
+
+ return _to_nested_structure(root_node.items or [])
+
+
+@dataclass(slots=True)
+class _TreeEntry:
+ name: str
+ level: int
+ item_type: Literal["file", "folder", "comment"]
+ created: datetime
+ modified: datetime
+ parent: Optional["_TreeEntry"] = None
+ items: Optional[list["_TreeEntry"]] = None
+ is_last: bool = False
+ rel_path: str = ""
+ text: str = ""
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "name": self.name,
+ "level": self.level,
+ "type": self.item_type,
+ "created": self.created,
+ "modified": self.modified,
+ "text": self.text,
+ "items": [child.as_dict() for child in self.items] if self.items is not None else None,
+ }
+
+
+def _normalize_relative_path(path: str) -> str:
+ normalized = path.replace(os.sep, "/")
+ if normalized in {".", ""}:
+ return ""
+ while normalized.startswith("./"):
+ normalized = normalized[2:]
+ return normalized
+
+
+def _directory_has_visible_entries(
+ directory: str,
+ root_abs_path: str,
+ ignore_spec: PathSpec,
+ cache: dict[str, bool],
+ max_depth_remaining: int,
+) -> bool:
+ if max_depth_remaining == 0:
+ return False
+
+ cached = cache.get(directory)
+ if cached is not None:
+ return cached
+
+ try:
+ with os.scandir(directory) as iterator:
+ for entry in iterator:
+ rel_path = os.path.relpath(entry.path, root_abs_path)
+ rel_posix = _normalize_relative_path(rel_path)
+ is_dir = entry.is_dir(follow_symlinks=False)
+
+ if is_dir:
+ ignored = ignore_spec.match_file(rel_posix) or ignore_spec.match_file(f"{rel_posix}/")
+ if ignored:
+ next_depth = max_depth_remaining - 1 if max_depth_remaining > 0 else -1
+ if next_depth == 0:
+ continue
+ if _directory_has_visible_entries(
+ entry.path,
+ root_abs_path,
+ ignore_spec,
+ cache,
+ next_depth,
+ ):
+ cache[directory] = True
+ return True
+ continue
+ else:
+ if ignore_spec.match_file(rel_posix):
+ continue
+
+ cache[directory] = True
+ return True
+ except FileNotFoundError:
+ cache[directory] = False
+ return False
+
+ cache[directory] = False
+ return False
+
+
+def _create_summary_comment(parent: _TreeEntry, noun: str, count: int) -> _TreeEntry:
+ label = noun
+ if count == 1 and noun.endswith("s"):
+ label = noun[:-1]
+ elif count > 1 and not noun.endswith("s"):
+ label = f"{noun}s"
+ return _TreeEntry(
+ name=f"{count} more {label}",
+ level=parent.level + 1,
+ item_type="comment",
+ created=parent.created,
+ modified=parent.modified,
+ parent=parent,
+ items=None,
+ rel_path=f"{parent.rel_path}#summary:{noun}:{count}",
+ )
+
+
+def _prune_nested_children(node: _TreeEntry, predicate: Callable[[_TreeEntry], bool]) -> None:
+ if node.items is None:
+ return
+ pruned: list[_TreeEntry] = []
+ for child in node.items:
+ if predicate(child):
+ _prune_nested_children(child, predicate)
+ pruned.append(child)
+ node.items = pruned
+
+
+def _prune_to_visible(node: _TreeEntry, visible_ids: set[int]) -> None:
+ if node.items is None:
+ return
+ filtered: list[_TreeEntry] = []
+ for child in node.items:
+ if not visible_ids or id(child) in visible_ids:
+ _prune_to_visible(child, visible_ids)
+ filtered.append(child)
+ node.items = filtered
+
+
+def _mark_last_flags(node: _TreeEntry) -> None:
+ if node.items is None:
+ return
+ total = len(node.items)
+ for index, child in enumerate(node.items):
+ child.is_last = index == total - 1
+ _mark_last_flags(child)
+
+
+def _refresh_render_metadata(node: _TreeEntry) -> None:
+ if node.items is None:
+ return
+ for child in node.items:
+ child.text = _format_line(child)
+ _refresh_render_metadata(child)
+
+
+def _resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optional[PathSpec]:
+ if ignore is None:
+ return None
+
+ content: str
+ if ignore.startswith("file:"):
+ reference = ignore[5:]
+ if reference.startswith("///"):
+ reference_path = reference[2:]
+ elif reference.startswith("//"):
+ reference_path = os.path.join(root_abs_path, reference[2:])
+ elif reference.startswith("/"):
+ reference_path = reference
+ else:
+ reference_path = os.path.join(root_abs_path, reference)
+
+ try:
+ with open(reference_path, "r", encoding="utf-8") as handle:
+ content = handle.read()
+ except FileNotFoundError as exc:
+ raise FileNotFoundError(f"Ignore file not found: {reference_path}") from exc
+ else:
+ content = ignore
+
+ lines = [
+ line.strip()
+ for line in content.splitlines()
+ if line.strip() and not line.strip().startswith("#")
+ ]
+
+ if not lines:
+ return None
+
+ return PathSpec.from_lines("gitwildmatch", lines)
+
+
+def _list_directory_children(
+ directory: str,
+ root_abs_path: str,
+ ignore_spec: Optional[PathSpec],
+ *,
+ max_depth_remaining: int,
+ cache: dict[str, bool],
+) -> tuple[list[os.DirEntry], list[os.DirEntry]]:
+ folders: list[os.DirEntry] = []
+ files: list[os.DirEntry] = []
+
+ try:
+ with os.scandir(directory) as iterator:
+ for entry in iterator:
+ if entry.name in (".", ".."):
+ continue
+ rel_path = os.path.relpath(entry.path, root_abs_path)
+ rel_posix = _normalize_relative_path(rel_path)
+ is_directory = entry.is_dir(follow_symlinks=False)
+
+ if ignore_spec:
+ if is_directory:
+ ignored = ignore_spec.match_file(rel_posix) or ignore_spec.match_file(f"{rel_posix}/")
+ if ignored:
+ if _directory_has_visible_entries(
+ entry.path,
+ root_abs_path,
+ ignore_spec,
+ cache,
+ max_depth_remaining - 1,
+ ):
+ folders.append(entry)
+ continue
+ else:
+ if ignore_spec.match_file(rel_posix):
+ continue
+
+ if is_directory:
+ folders.append(entry)
+ else:
+ files.append(entry)
+ except FileNotFoundError:
+ return ([], [])
+
+ return (folders, files)
+
+
+def _apply_sorting_and_limits(
+ folders: list[_TreeEntry],
+ files: list[_TreeEntry],
+ *,
+ folders_first: bool,
+ sort: tuple[str, str],
+ max_folders: int | None,
+ max_files: int | None,
+ directory_node: _TreeEntry,
+) -> list[_TreeEntry]:
+ sort_key, sort_dir = sort
+ reverse = sort_dir == SORT_DESC
+
+ def key_fn(node: _TreeEntry):
+ if sort_key == SORT_BY_NAME:
+ return node.name.casefold()
+ if sort_key == SORT_BY_CREATED:
+ return node.created
+ return node.modified
+
+ folders_sorted = sorted(folders, key=key_fn, reverse=reverse)
+ files_sorted = sorted(files, key=key_fn, reverse=reverse)
+ combined: list[_TreeEntry] = []
+
+ def append_group(group: list[_TreeEntry], limit: int | None, noun: str) -> None:
+ if limit == 0:
+ limit = None
+ if not group:
+ return
+ if limit is None:
+ combined.extend(group)
+ return
+
+ limit = max(limit, 0)
+ visible = group[:limit]
+ combined.extend(visible)
+
+ overflow = group[limit:]
+ if not overflow:
+ return
+
+ if len(overflow) == 1 and limit > 0:
+ combined.append(overflow[0])
+ return
+
+ combined.append(
+ _create_summary_comment(
+ directory_node,
+ noun,
+ len(overflow),
+ )
+ )
+
+ if folders_first:
+ append_group(folders_sorted, max_folders, "folder")
+ append_group(files_sorted, max_files, "file")
+ else:
+ append_group(files_sorted, max_files, "file")
+ append_group(folders_sorted, max_folders, "folder")
+
+ return combined
+
+
+def _format_line(node: _TreeEntry) -> str:
+ segments: list[str] = []
+ ancestor = node.parent
+ while ancestor and ancestor.parent is not None:
+ segments.append(" " if ancestor.is_last else "│ ")
+ ancestor = ancestor.parent
+ segments.reverse()
+
+ connector = "└── " if node.is_last else "├── "
+ if node.item_type == "folder":
+ label = f"{node.name}/"
+ elif node.item_type == "comment":
+ label = f"# {node.name}"
+ else:
+ label = node.name
+
+ return "".join(segments) + connector + label
+
+
+def _build_tree_items_flat(items: Sequence[_TreeEntry]) -> list[dict]:
+ return [
+ {
+ "name": node.name,
+ "level": node.level,
+ "type": node.item_type,
+ "created": node.created,
+ "modified": node.modified,
+ "text": node.text,
+ "items": None,
+ }
+ for node in items
+ ]
+
+
+def _to_nested_structure(items: Sequence[_TreeEntry]) -> list[dict]:
+ def convert(node: _TreeEntry) -> dict:
+ children = None
+ if node.items is not None:
+ children = [convert(child) for child in node.items]
+ return {
+ "name": node.name,
+ "level": node.level,
+ "type": node.item_type,
+ "created": node.created,
+ "modified": node.modified,
+ "text": node.text,
+ "items": children,
+ }
+
+ return [convert(item) for item in items]
+
+
+def _iter_depth_first(items: Sequence[_TreeEntry]) -> Iterable[_TreeEntry]:
+ for node in items:
+ yield node
+ if node.items:
+ yield from _iter_depth_first(node.items)
diff --git a/specs/001-file-tree-utility/checklists/requirements.md b/specs/001-file-tree-utility/checklists/requirements.md
new file mode 100644
index 000000000..f78f08339
--- /dev/null
+++ b/specs/001-file-tree-utility/checklists/requirements.md
@@ -0,0 +1,35 @@
+# Specification Quality Checklist: File Tree Utility
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-08
+**Feature**: [/home/rafael/Workspace/Repos/rafael/a0-local/specs/001-file-tree-utility/spec.md](/home/rafael/Workspace/Repos/rafael/a0-local/specs/001-file-tree-utility/spec.md)
+
+## Content Quality
+
+- [X] No implementation details (languages, frameworks, APIs)
+- [X] Focused on user value and business needs
+- [X] Written for non-technical stakeholders
+- [X] All mandatory sections completed
+
+## Requirement Completeness
+
+- [X] No [NEEDS CLARIFICATION] markers remain
+- [X] Requirements are testable and unambiguous
+- [X] Success criteria are measurable
+- [X] Success criteria are technology-agnostic (no implementation details)
+- [X] All acceptance scenarios are defined
+- [X] Edge cases are identified
+- [X] Scope is clearly bounded
+- [X] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [X] All functional requirements have clear acceptance criteria
+- [X] User scenarios cover primary flows
+- [X] Feature meets measurable outcomes defined in Success Criteria
+- [X] No implementation details leak into specification
+
+## Notes
+
+- Implementation-specific guidance (constants, helper layout, docstring content, filesystem helper usage) now lives in the contract and plan; the specification itself remains technology-agnostic.
+- If scope changes (e.g., additional output modes or metadata), revisit FR-002/FR-003 and Success Criteria accordingly.
diff --git a/specs/001-file-tree-utility/contracts/file_tree.md b/specs/001-file-tree-utility/contracts/file_tree.md
new file mode 100644
index 000000000..affe0f8b2
--- /dev/null
+++ b/specs/001-file-tree-utility/contracts/file_tree.md
@@ -0,0 +1,103 @@
+# Contract: file_tree() Utility
+
+## Location
+- Module: `python/helpers/files.py`
+- Exported function: `file_tree()`
+- Predefined constants (declared directly before function definition):
+ - Sort keys: `SORT_BY_NAME`, `SORT_BY_CREATED`, `SORT_BY_MODIFIED`
+ - Sort directions: `SORT_ASC`, `SORT_DESC`
+ - Output modes: `OUTPUT_MODE_STRING`, `OUTPUT_MODE_FLAT`, `OUTPUT_MODE_NESTED`
+
+## Signature (proposed)
+```python
+def file_tree(
+ relative_path: str,
+ *,
+ max_depth: int = 0,
+ max_lines: int = 0,
+ folders_first: bool = True,
+ max_folders: int | None = None,
+ max_files: int | None = None,
+ sort: tuple[str, str] = (SORT_BY_MODIFIED, SORT_DESC),
+ ignore: str | None = None,
+ output_mode: str = OUTPUT_MODE_STRING,
+) -> str | list[dict]:
+ ...
+```
+
+## Parameters
+- `relative_path`: Base folder to scan. The implementation MUST resolve with `get_abs_path(relative_path)` from helpers.
+- `max_depth`: Maximum depth to scan; `0` means unlimited.
+- `max_lines`: Maximum total output lines across the whole render; `0` means unlimited.
+- `folders_first`: If `True`, group folders before files when rendering/sorting (default per Clarifications).
+- `max_folders`: Per-directory maximum number of folder entries to render before emitting a summary comment (e.g., `# 6 more folders`).
+- `max_files`: Per-directory maximum number of file entries to render before emitting a summary comment (e.g., `# 23 more files`).
+- `sort`: Tuple `(key, direction)`:
+ - `key ∈ {SORT_BY_NAME, SORT_BY_CREATED, SORT_BY_MODIFIED}`
+ - `direction ∈ {SORT_ASC, SORT_DESC}`
+ - Default: `(SORT_BY_MODIFIED, SORT_DESC)`
+- `ignore`: `.gitignore`-style patterns as inline string, or `file:` reference:
+ - `file:/abs/path/.gitignore` or `file:///abs/path/.gitignore` → absolute path
+ - `file:relative/path/.gitignore` or `file://.gitignore` → resolved relative to `relative_path`
+ - Comments and blanks ignored; support `!` negation, trailing `/` (directory-only), and `**` recursion
+- `output_mode`: One of:
+ - `OUTPUT_MODE_STRING`: Return a single multi-line string
+ - `OUTPUT_MODE_FLAT`: Return a flat list of TreeItem dicts
+ - `OUTPUT_MODE_NESTED`: Return a top-level list where folder TreeItems include `items` arrays
+
+## Return Types
+- `OUTPUT_MODE_STRING` → `str` (multi-line ASCII)
+- `OUTPUT_MODE_FLAT` → `list[TreeItem]`
+- `OUTPUT_MODE_NESTED` → `list[TreeItem]`
+
+Where `TreeItem` has:
+- `name: str`
+- `level: int` (root entries start at 1)
+- `type: "file" | "folder" | "comment"`
+- `created: datetime` (timezone-aware UTC)
+- `modified: datetime` (timezone-aware UTC)
+- `text: str` (rendered single-line tree segment, e.g., `├── main.py`, `└── helpers/`, `# 6 more folders`)
+- `items: list[TreeItem] | None` (folders in nested mode contain children; files/comments are `None` or empty)
+
+## Behavior
+- Traversal order: Breadth-first by depth (FR‑006) for discovery and limit enforcement; string rendering walks the established tree depth-first so connector glyphs reflect parent/child structure.
+- Sorting/grouping: Respect `folders_first`; within each group, sort by requested key/direction (FR‑005).
+- Limits:
+ - Per-directory `max_folders` / `max_files` summarize omitted items with comment lines (FR‑007). When only a single entry exceeds the limit and the limit is greater than zero, that entry is rendered instead of emitting a summary comment. A value of `0` is treated as unlimited for each per-directory constraint.
+ - Global `max_lines` caps the total rendered lines; finish current depth level before stopping further descent.
+- ASCII format (FR‑008):
+ - Use `├──` / `└──` connectors, indentation guides, append `/` to folder names.
+ - Prefix comment lines with `# ` (e.g., `# 12 more files`).
+- Ignore semantics (FR‑004): Use Git wildmatch via `pathspec`, evaluate paths relative to the scanned root; honor negation `!` patterns and directory-only patterns.
+
+## Error Handling
+- Non-existent `relative_path` or inaccessible directories: Raise a clear, actionable error (FR‑009).
+
+## Datetime Conversions (docstring examples required)
+```python
+# item['created'] and item['modified'] are timezone-aware UTC datetime objects.
+iso = item['created'].isoformat() # e.g., '2025-11-09T00:21:00.123456+00:00'
+epoch = item['created'].timestamp() # e.g., 1762647660.123456
+```
+
+## Docstring Requirements
+- Document every parameter, including the predefined constants (`SORT_BY_*`, `SORT_*`, `OUTPUT_MODE_*`) so callers understand valid values.
+- Include code snippets demonstrating conversion of `created`/`modified` datetimes to ISO 8601 strings and Unix timestamps (see Datetime Conversions section).
+- Explain `ignore` resolution for inline patterns and `file:`/`file://`/`file:///` references with examples that match FR‑003 semantics.
+- Note that the utility is synchronous and should not be invoked on hot async event-loop paths.
+
+## Helper Functions (module-internal)
+- Implement helpers at end of module with single leading underscore:
+ - `_resolve_ignore_patterns(...)`
+ - `_list_directory_children(...)`
+ - `_apply_sorting_and_limits(...)`
+ - `_format_line(...)`
+ - `_build_tree_items_flat(...)`
+ - `_to_nested_structure(...)`
+
+## Implementation Notes
+- Perform filesystem operations via existing Agent Zero helpers in `python/helpers/files.py` (`get_abs_path`, `exists`, `list_files`, timestamp helpers, etc.); fall back to standard library only when no wrapper exists.
+- Keep helper definitions module-internal (single leading underscore) to preserve the public API surface.
+
+## Dependencies
+- `pathspec==0.12.1` for Git wildmatch semantics (FR‑004/Dependencies).
diff --git a/specs/001-file-tree-utility/data-model.md b/specs/001-file-tree-utility/data-model.md
new file mode 100644
index 000000000..41ea641fe
--- /dev/null
+++ b/specs/001-file-tree-utility/data-model.md
@@ -0,0 +1,49 @@
+# Data Model: File Tree Utility
+
+## Entity: TreeItem
+
+- `name: str` — filename or folder name (or comment label)
+- `level: int` — depth level starting from 1 at root entries
+- `type: \"file\" | \"folder\" | \"comment\"`
+- `created: datetime` — timezone-aware UTC
+- `modified: datetime` — timezone-aware UTC
+- `text: str` — one-line rendered tree segment (e.g., `├── main.py`, `└── helpers/`, `# 6 more folders`)
+- `items: list[TreeItem] | null` — present for folders in nested mode; empty or null for files and comments
+
+### Example (flat item)
+```json
+{
+ "name": "context_data.py",
+ "level": 1,
+ "type": "file",
+ "created": "datetime (UTC-aware)",
+ "modified": "datetime (UTC-aware)",
+ "text": "├── context_data.py",
+ "items": null
+}
+```
+
+### Example (nested folder)
+```json
+{
+ "name": "helpers",
+ "level": 1,
+ "type": "folder",
+ "created": "datetime (UTC-aware)",
+ "modified": "datetime (UTC-aware)",
+ "text": "└── helpers/",
+ "items": [
+ {
+ "name": "api.py",
+ "level": 2,
+ "type": "file",
+ "created": "datetime (UTC-aware)",
+ "modified": "datetime (UTC-aware)",
+ "text": " ├── api.py",
+ "items": null
+ }
+ ]
+}
+```
+
+
diff --git a/specs/001-file-tree-utility/plan.md b/specs/001-file-tree-utility/plan.md
new file mode 100644
index 000000000..87ac62503
--- /dev/null
+++ b/specs/001-file-tree-utility/plan.md
@@ -0,0 +1,83 @@
+# Implementation Plan: File Tree Utility
+
+**Branch**: `001-file-tree-utility` | **Date**: 2025-11-08 | **Spec**: `specs/001-file-tree-utility/spec.md`
+**Input**: Feature specification from `/specs/001-file-tree-utility/spec.md`
+
+**Note**: This plan is produced by the `/speckit.plan` workflow.
+
+## Summary
+
+Implement a `file_tree()` utility in `python/helpers/files.py` that generates a readable ASCII tree along with structured metadata. The function supports three output modes (`string`, `flat`, `nested`), breadth‑first traversal, `.gitignore`-style filtering via `pathspec`, sorting and grouping (folders vs files), depth and line limits, and summary comment lines when limits are reached. All filesystem access must use existing helpers in `python/helpers/files.py`. Convenience constants are defined adjacent to the function, and helper routines are implemented as module-internal functions with a single leading underscore.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+
+**Primary Dependencies**: `pathspec==0.12.1`, standard library `datetime`, existing helpers in `python/helpers/files.py`
+**Storage**: N/A (read-only filesystem traversal)
+**Testing**: `pytest` with temporary directories (mktemp family) and snapshot/assertion tests under `tests/`
+**Target Platform**: Linux (development + container), cross-platform filesystem semantics respected
+**Project Type**: Single-user backend helper within existing codebase
+**Performance Goals**: For ≥5,000 entries and `max_lines=200`, return within ~2 seconds with deterministic ordering (per SC-003)
+**Constraints**:
+- Use Agent Zero filesystem helpers (FR‑013) for path ops and listing
+- Honor `.gitignore` Git wildmatch semantics including negation and `**` (FR‑004)
+- Breadth‑first traversal order; folders grouped per `folders_first` (FR‑005/006)
+- Non-blocking async discipline: function is synchronous; avoid calling on event loop hot paths
+**Scale/Scope**: Should handle large directories (5k+ entries) with limits applied per directory and overall lines
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- Exploration-First Development: Using existing helpers in `python/helpers/files.py` and reading spec; PASS
+- Security-First: Read-only traversal, no secrets to UI, no new endpoints; PASS
+- Non-Blocking Async: Utility is synchronous; caller must not invoke on event loop hot paths; PASS
+- Architectural Boundaries: No new systems; extends helpers only; PASS
+- Environment Separation: Reuses helpers that abstract environment; PASS
+- PrintStyle Logging Only: No logging added; N/A
+- Project Scope & Simplicity: Single-user helper, no enterprise features; PASS
+
+## Project Structure
+
+### Documentation (this feature)
+```text
+specs/001-file-tree-utility/
+├── plan.md # This file (/speckit.plan output)
+├── research.md # Phase 0 output (/speckit.plan)
+├── data-model.md # Phase 1 output (/speckit.plan)
+├── quickstart.md # Phase 1 output (/speckit.plan)
+└── contracts/ # Phase 1 output (/speckit.plan)
+```
+
+### Source Code (repository root)
+```text
+python/
+└── helpers/
+ └── files.py # Add file_tree(), constants, and helper functions
+
+tests/
+├── test_file_tree_string.py
+├── test_file_tree_structured.py
+└── test_file_tree_ignore_and_limits.py
+```
+
+**Structure Decision**: Extend `python/helpers/files.py` with the new utility and add three pytest modules in `tests/` to validate string snapshot, structured outputs, ignore/limits, and sorting behaviors.
+
+- `tests/test_file_tree_string.py` also owns the breadth-first traversal regression test to ensure level N entries render before level N+1 across modes.
+- `tests/test_file_tree_structured.py` covers metadata assertions for flat/nested outputs, including ignore semantics for nested structures.
+- `tests/test_file_tree_ignore_and_limits.py` includes the performance guard using `time.perf_counter()` to assert the ≤2.0 s budget on ≥5k synthetic entries while exercising limit summaries.
+
+## Complexity Tracking
+
+No constitutional violations identified; section not applicable.
+
+## Constitution Check (Post-Design)
+
+Re-evaluated after drafting research, data model, contracts, and quickstart:
+- Exploration-First Development: PASS
+- Security-First Design: PASS
+- Non-Blocking Async: PASS (utility remains synchronous; callers should avoid hot event-loop contexts)
+- Architectural Boundaries: PASS
+- Environment Separation: PASS
+- PrintStyle Logging Only: PASS (no logging added)
+- Project Scope & Simplicity: PASS
diff --git a/specs/001-file-tree-utility/quickstart.md b/specs/001-file-tree-utility/quickstart.md
new file mode 100644
index 000000000..e4f362e0a
--- /dev/null
+++ b/specs/001-file-tree-utility/quickstart.md
@@ -0,0 +1,101 @@
+# Quickstart: File Tree Utility
+
+## Overview
+`file_tree()` in `python/helpers/files.py` renders a directory tree as:
+- Multi-line ASCII string (`OUTPUT_MODE_STRING`)
+- Flat list of items with metadata (`OUTPUT_MODE_FLAT`)
+- Nested list where folders contain `items` arrays (`OUTPUT_MODE_NESTED`)
+
+## Import
+```python
+from python.helpers.files import (
+ file_tree,
+ SORT_BY_NAME, SORT_BY_CREATED, SORT_BY_MODIFIED,
+ SORT_ASC, SORT_DESC,
+ OUTPUT_MODE_STRING, OUTPUT_MODE_FLAT, OUTPUT_MODE_NESTED,
+)
+```
+
+## Examples
+
+### 1) String mode (ASCII)
+```python
+tree_str = file_tree(
+ relative_path="my_project",
+ output_mode=OUTPUT_MODE_STRING,
+ max_depth=0,
+ max_lines=0,
+ folders_first=True,
+ sort=(SORT_BY_MODIFIED, SORT_DESC),
+)
+print(tree_str)
+```
+Sample output:
+```text
+my_project/
+├── context_data.py
+├── main.py
+└── helpers/
+ ├── api.py
+ └── utils/
+ ├── files.py
+ └── strings.py
+```
+
+### 2) Flat mode (structured list)
+```python
+items = file_tree(
+ relative_path="my_project",
+ output_mode=OUTPUT_MODE_FLAT,
+ max_depth=2,
+ max_lines=200,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+)
+
+# Convert datetimes:
+first = items[0]
+iso_created = first["created"].isoformat()
+ts_created = first["created"].timestamp()
+```
+
+### 3) Nested mode (hierarchical)
+```python
+nested = file_tree(
+ relative_path="my_project",
+ output_mode=OUTPUT_MODE_NESTED,
+ max_depth=2,
+ folders_first=True,
+)
+```
+
+## Ignore Patterns
+Inline patterns:
+```python
+ignore = \"\"\"\n*.pyc\n__pycache__/\n!important_file.py\n\"\"\"\n
+items = file_tree(\"my_project\", output_mode=OUTPUT_MODE_FLAT, ignore=ignore)
+```
+
+From file (resolved as specified):
+```python
+# Absolute path
+items = file_tree(\"my_project\", output_mode=OUTPUT_MODE_FLAT, ignore=\"file:/abs/path/.gitignore\")
+# Absolute (URI form)
+items = file_tree(\"my_project\", output_mode=OUTPUT_MODE_FLAT, ignore=\"file:///abs/path/.gitignore\")
+# Relative to scan root
+items = file_tree(\"my_project\", output_mode=OUTPUT_MODE_FLAT, ignore=\"file:.gitignore\")
+items = file_tree(\"my_project\", output_mode=OUTPUT_MODE_FLAT, ignore=\"file://.gitignore\")
+```
+
+## Limits and Summaries
+```python
+tree_str = file_tree(
+ relative_path=\"large_dir\",
+ output_mode=OUTPUT_MODE_STRING,
+ max_lines=200,
+ max_folders=10,
+ max_files=20,
+)
+```
+When limits are hit within a directory, summary comment lines are emitted, e.g.:
+```\n# 12 more files\n# 6 more folders\n```
diff --git a/specs/001-file-tree-utility/research.md b/specs/001-file-tree-utility/research.md
new file mode 100644
index 000000000..0f86c06c6
--- /dev/null
+++ b/specs/001-file-tree-utility/research.md
@@ -0,0 +1,37 @@
+# Research: File Tree Utility
+
+## Decisions
+
+- Ignore semantics implementation: Use `pathspec` with Git wildmatch patterns to evaluate `.gitignore`-style rules, including `!` negation, directory-only patterns (trailing `/`), and `**` recursion. Paths must be evaluated relative to the scanned root.
+- `ignore` input resolution:
+ - Inline patterns: treat the string as `.gitignore` content
+ - `file:/abs/path/.gitignore` and `file:///abs/path/.gitignore`: absolute file path
+ - `file:relative/path/.gitignore` and `file://.gitignore`: resolve relative to `relative_path` (the scan root)
+- Traversal strategy: Breadth-first by depth. For each directory, collect children (folders/files), apply limits (`max_folders`, `max_files`) and sorting, render lines and comments, then move to next directory at the same depth before descending.
+- Sorting: Group by folder/file depending on `folders_first` (default True). Within each group, sort by `modified` (default key) descending (default direction). Support keys: name, created, modified; directions: asc, desc.
+- Performance: Cap items per directory, cap total lines (`max_lines`), and short-circuit deeper traversal once `max_lines` is met after finishing the current depth pass. Ensure deterministic ordering with stable sorts.
+- Datetime fields: Use timezone-aware UTC `datetime` for `created` and `modified`. Consumers can convert with `.isoformat()` or `.timestamp()` as needed.
+- Output forms:
+ - `string`: join rendered `text` lines with newlines (no metadata returned)
+ - `flat`: return flat list of TreeItem dicts
+ - `nested`: return top-level list where folder TreeItems contain `items` arrays of children; files/comments have `items` as `null` or `[]`
+- Helper placement: Implement helpers at end of `python/helpers/files.py` with single leading underscore names (module-internal convention).
+
+## Rationale
+
+- `pathspec` is de facto for Git wildmatch semantics; it correctly handles edge cases and negations.
+- Breadth-first traversal matches spec requirements (FR‑006) and yields predictable depth-wise rendering.
+- Using existing helpers in `python/helpers/files.py` adheres to architecture and centralizes filesystem logic.
+- UTC-aware datetimes avoid ambiguity and make conversions straightforward.
+
+## Alternatives Considered
+
+- `gitignore_parser`: Simpler API but less explicit control vs `pathspec` and not the preferred dependency in spec.
+- Depth-first traversal: Simpler implementation, but violates FR‑006 breadth-first requirement and produces different visual grouping.
+- Returning only strings: Loses metadata needed by downstream automation; rejected in favor of multiple modes.
+
+## Clarifications Resolved
+
+- Python version: Target Python 3.11+ (tested under 3.12 on Linux). No features require newer than 3.11.
+- Default `folders_first`: True by default (per Clarifications), with parameter to toggle.
+- Large directory behavior: Per-directory `max_folders`/`max_files` with summary comment lines; stop descending when `max_lines` reached, but finish current depth scan.
diff --git a/specs/001-file-tree-utility/review.md b/specs/001-file-tree-utility/review.md
new file mode 100644
index 000000000..b778513fd
--- /dev/null
+++ b/specs/001-file-tree-utility/review.md
@@ -0,0 +1,193 @@
+# File Tree Utility – Formal Review & Remediation Plan
+
+## 1. Scope & Context
+- **Feature**: `file_tree()` helper and supporting internals in `python/helpers/files.py`
+- **Artifacts Reviewed**:
+ - Implementation source (`python/helpers/files.py`)
+ - Test modules (`tests/test_file_tree_string.py`, `tests/test_file_tree_structured.py`, `tests/test_file_tree_ignore_and_limits.py`, `tests/test_file_tree_invalid.py`)
+ - String fixtures under `tests/fixtures/file_tree/`
+ - Specification bundle in `specs/001-file-tree-utility/` (spec, plan, data-model, contracts, research, tasks)
+ - Constitution (`.specify/memory/constitution.md`)
+- **Environment**: Python 3.12.11 inside project `.venv`, pytest 8.4.2
+ `PYTHONPATH=. pytest tests/test_file_tree_string.py tests/test_file_tree_structured.py tests/test_file_tree_ignore_and_limits.py tests/test_file_tree_invalid.py`
+
+## 2. Specification References
+- **FR‑006** / **FR‑007** / **FR‑008** – `specs/001-file-tree-utility/spec.md`
+- `contracts/file_tree.md` – finish-current-depth requirement, summary semantics
+- Tasks `T013`, `T030`, `T031` – enforcement of depth-finish, limit summaries
+- Constitution Principles I & VII – verification of contractual behaviour
+
+## 3. Verified Behaviour & Reproduction
+```
+python - <<'PY'
+from python.helpers.files import file_tree, create_dir, delete_dir, write_file, get_abs_path
+import os
+
+def materialize(base, tree):
+ for name, value in tree.items():
+ rel = os.path.join(base, name)
+ if isinstance(value, dict):
+ create_dir(rel)
+ materialize(rel, value)
+ else:
+ write_file(rel, value or "")
+
+base = "tmp/tests/file_tree/string_breadth_first_check"
+delete_dir(base); create_dir(base)
+materialize(base, {
+ "alpha": {"alpha_file.txt": "alpha", "nested": {"inner.txt": "inner"}},
+ "beta": {"beta_file.txt": "beta"},
+ "zeta": {},
+ "a.txt": "A",
+ "b.txt": "B",
+})
+print(file_tree(base, folders_first=True, sort=("name","asc"), output_mode="string"))
+delete_dir(base)
+PY
+```
+Output shows stray leading `│` ahead of deeper nodes (`nested/`, `alpha_file.txt`, etc.), despite all level-one siblings already rendered.
+
+```
+python - <<'PY'
+from python.helpers.files import file_tree, create_dir, delete_dir, write_file
+import os
+
+def materialize(base, tree):
+ for name, value in tree.items():
+ rel = os.path.join(base, name)
+ if isinstance(value, dict):
+ create_dir(rel)
+ materialize(rel, value)
+ else:
+ write_file(rel, value or "")
+
+base = "tmp/tests/file_tree/string_ignore_limits_check"
+delete_dir(base); create_dir(base)
+materialize(base, {
+ "src": {
+ "main.py": "print('hello')",
+ "utils.py": "pass",
+ "tmp.tmp": "",
+ "cache": {"cached.txt": "", "keep.txt": ""},
+ "modules": {"a.py": "", "b.py": "", "c.py": ""},
+ },
+ "logs": {"2024.log": "", "2025.log": ""},
+ "notes.md": "",
+ "build.tmp": "",
+})
+write_file(os.path.join(base, ".treeignore"), "\n".join(
+ ["*.tmp", "cache/", "!src/cache/keep.txt", "logs/", "!logs/2025.log"]
+))
+print(file_tree(
+ base,
+ folders_first=False,
+ sort=("name","asc"),
+ ignore="file:.treeignore",
+ max_folders=1,
+ max_files=2,
+ max_lines=12,
+ output_mode="string",
+))
+delete_dir(base)
+PY
+```
+Produces:
+```
+tmp/tests/file_tree/string_ignore_limits_check/
+├── .treeignore
+├── notes.md
+├── logs/
+└── # 1 more folders
+│ └── 2025.log
+```
+- Comment precedes folder child (`2025.log`), implying a “comment node” with children.
+- Grammar shows “# 1 more folders” (singular noun mismatch).
+
+```
+python - <<'PY'
+from python.helpers.files import file_tree, create_dir, delete_dir, write_file
+import os
+
+def materialize(base, tree):
+ for name, value in tree.items():
+ rel = os.path.join(base, name)
+ if isinstance(value, dict):
+ create_dir(rel)
+ materialize(rel, value)
+ else:
+ write_file(rel, value or "")
+
+base = "tmp/tests/file_tree/string_max_lines_check"
+delete_dir(base); create_dir(base)
+materialize(base, {
+ "dirA": {f"a{i}.txt": "" for i in range(3)},
+ "dirB": {f"b{i}.txt": "" for i in range(3)},
+ "root.txt": "",
+})
+print(file_tree(base, max_lines=2, output_mode="string"))
+print(file_tree(base, max_lines=2, output_mode="flat"))
+delete_dir(base)
+PY
+```
+Only two top-level entries appear, violating the “finish current depth before stopping” contract.
+
+Pytest run (with corrected `PYTHONPATH`) currently passes, proving tests fail to cover these cases:
+```
+PYTHONPATH=. pytest tests/test_file_tree_string.py tests/test_file_tree_structured.py \
+ tests/test_file_tree_ignore_and_limits.py tests/test_file_tree_invalid.py
+```
+
+## 4. Findings (F1–F5)
+
+| ID | Description | Root Cause | Impacted Spec Items |
+|----|-------------|------------|---------------------|
+| **F1** | ASCII tree shows stray leading `│` for deeper nodes; visual connectors imply depth-first emission though actual order is breadth-first. | String renderer consumes breadth-first list (`nodes_in_order`) directly; `_format_line()` computes connector state from ancestors whose `is_last` flags were never recalculated for depth-first rendering. | FR‑006, FR‑008, Contract §Behavior (connector expectations) |
+| **F2** | Summary comments appear before descendants, giving “comment with children.” | `_apply_sorting_and_limits()` appends `_create_summary_comment()` to children list feeding BFS queue. Comments emitted before queue dequeues the folder they summarize. | FR‑007, Contract §Behavior |
+| **F3** | Singular omission reported as `# 1 more folders`; UX expects either singular noun or direct rendering of the lone item. | `name=f"{count} more {noun}"` uses plural noun regardless of count; limit logic never promotes single remaining entries. | FR‑007 (per-directory summaries) |
+| **F4** | `max_lines` stops mid-level, omitting siblings at same depth. | String/flat outputs slice `nodes_in_order[:limit]`; `limit_level` is ignored when rendering string/flat outputs. | FR‑007, Contract §Behavior (“finish current depth before stopping”) |
+| **F5** | Existing tests/fixtures miss defects above. | Test suite lacks low `max_lines`, connector validation, summary ordering, and singular cases. | Tasks T030, T031; SC-criteria in spec |
+
+## 5. Remediation Plan
+
+### 5.1 Renderer & Traversal
+1. Retain breadth-first traversal for limit computation but render ASCII via a depth-first serializer that walks the established `_TreeEntry` hierarchy recursively, calculating connectors in-context.
+2. Recompute/propagate `is_last` flags inside the depth-first renderer (children sorted by final render order).
+
+### 5.2 Summary Comment Semantics
+1. Store summary counts as metadata rather than queue entries, or render them after child subtrees (e.g., track pending comments and emit once child recursion finishes).
+2. Handle singular counts explicitly:
+ - If only one entry exceeds the per-directory limit, render the entry (preferred) or output `# 1 more folder`.
+ - Ensure comments never accumulate children; `items` stays `None`.
+
+### 5.3 `max_lines` Compliance
+1. Use `limit_level` to cap traversal depth instead of slicing output arrays:
+ - Build nodes breadth-first as today.
+ - Before rendering, prune the tree using `limit_level` so entire depths remain intact.
+ - For flat outputs, filter nodes by `level <= limit_level` (plus any summaries if retained).
+
+### 5.4 Documentation Updates
+1. Update `file_tree()` docstring with corrected examples (showing depth-first ASCII and revised summary semantics).
+2. If singular behaviour shifts to “render entry” rather than comment, reflect in `contracts/file_tree.md`.
+
+### 5.5 Testing Enhancements
+Add targeted cases:
+1. `test_file_tree_string_depth_render()` – verifies ASCII connectors with multi-level tree (no stray leading `│`).
+2. `test_file_tree_summary_comment_order()` – ensures comments render after child listings and never own children.
+3. `test_file_tree_summary_comment_singular()` – confirms either singular grammar or rendering of the lone item.
+4. `test_file_tree_max_lines_depth_finish()` – asserts string/flat/nested modes honour level completion when `max_lines` < number of level-one entries.
+
+## 6. Post-Fix Verification Checklist
+- Run enhanced pytest suite (`PYTHONPATH=. pytest ...`) ensuring new tests cover regressions.
+- Manual spot-check using reproduction scripts above.
+- Validate docstring/contract snippets compile and align with outputs.
+- Confirm summary comments contain zero children and appear only after their folder’s listings.
+- Verify singular grammar or item rendering meets UX decision.
+
+## 7. Handoff Notes
+- No schema changes required; `_TreeEntry` can remain dataclass.
+- Refactor should avoid altering traversal ordering semantics beyond rendering & limit handling.
+- Communicate final summary-comment decisions back into spec to keep documentation authoritative.
+
+---
+
+Prepared for follow-up implementation; provides reproduction commands, root causes, and actionable remediation to eliminate current defects without further clarification.
diff --git a/specs/001-file-tree-utility/spec.md b/specs/001-file-tree-utility/spec.md
new file mode 100644
index 000000000..774b5daba
--- /dev/null
+++ b/specs/001-file-tree-utility/spec.md
@@ -0,0 +1,152 @@
+# Feature Specification: File Tree Utility
+
+**Feature Branch**: `001-file-tree-utility`
+**Created**: 2025-11-08
+**Status**: Draft
+**Input**: User description: "File Tree Utility"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+ IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+ Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+ you should still have a viable MVP (Minimum Viable Product) that delivers value.
+
+ Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+ Think of each story as a standalone slice of functionality that can be:
+ - Developed independently
+ - Tested independently
+ - Deployed independently
+ - Demonstrated to users independently
+-->
+
+### User Story 1 - Readable Tree Overview (Priority: P1)
+
+As a developer, I want a fast, readable ASCII tree of a folder so I can quickly understand the structure without opening each directory.
+
+**Why this priority**: Immediate visualization of project layout is the most common need and unlocks rapid navigation and understanding, within the SC-003 performance target (~2 seconds for ≥5,000 entries with `max_lines=200`).
+
+**Independent Test**: Create a synthetic directory structure and call the utility with `mode=string`; verify the exact multi-line ASCII output matches the expected snapshot.
+
+**Acceptance Scenarios**:
+
+1. **Given** a base folder with subfolders and files, **When** I call the utility with default parameters and `mode=string`, **Then** it returns a multi-line ASCII tree with folders suffixed by `/`, and summary comment lines for truncated lists using the format `# N more files|folders`.
+2. **Given** an ignore pattern string using `.gitignore` syntax, **When** I call the utility, **Then** ignored entries are excluded while negation patterns re-include matching paths.
+3. **Given** nested folders at three or more depth levels, **When** I call the utility with `mode=string`, **Then** every level N renders before any entry from level N+1 (breadth-first ordering).
+
+---
+
+### User Story 2 - Flat Structured Listing (Priority: P2)
+
+As a developer, I want a flat list of items with metadata (name, type, level, created/modified datetimes, text) so I can programmatically filter, analyze, or render custom outputs.
+
+**Why this priority**: Enables downstream automation and analysis beyond visual inspection.
+
+**Independent Test**: Call the utility with `mode=flat` and verify the array of objects contains correct fields and values for a known synthetic structure.
+
+**Acceptance Scenarios**:
+
+1. **Given** a known directory with deterministic file timestamps, **When** I call `mode=flat`, **Then** each item includes `name`, `level`, `type ∈ {file, folder, comment}`, `created` (tz-aware UTC), `modified` (tz-aware UTC), and `text`, and ordering respects sort rules.
+
+---
+
+### User Story 3 - Nested Structured Listing (Priority: P3)
+
+As a developer, I want a nested structure where folder items contain an `items` array of their children so I can traverse the tree in-memory.
+
+**Why this priority**: Supports hierarchical processing and incremental rendering.
+
+**Independent Test**: Call the utility with `mode=nested` and verify parent folders contain `items` arrays while files and comments have `items` as `null` or `[]`.
+
+**Acceptance Scenarios**:
+
+1. **Given** a directory with multiple depths, **When** I call `mode=nested` with `max_depth=2`, **Then** the result contains children up to level 2 and deeper levels are represented by comment lines indicating remaining items.
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+- Empty directories should produce only the top-level line and no errors.
+- `max_depth=0` means unlimited depth; `max_lines=0` means unlimited lines.
+- `folders_first` ordering toggles whether folders are listed before files; sorting still applies within each group.
+- Very large directories apply `max_folders`/`max_files` per directory and append comment lines (e.g., `# 23 more files`).
+- Ignore patterns must follow `.gitignore` semantics including `!` negation, directory-only patterns (`/`), and `**` recursion.
+- Non-existent path results in a clear error surfaced to the caller.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Provide a folder tree utility that outputs one of three modes:
+ a) `string`: multi-line ASCII tree;
+ b) `flat`: flat array of items with metadata;
+ c) `nested`: array at root where folder items include `items` arrays for children.
+- **FR-002**: Each listed element must include: `name`, `level` (depth starting at 1 for root entries), `type` (`file` | `folder` | `comment`), `created` (timezone-aware UTC datetime), `modified` (timezone-aware UTC datetime), and `text` (the rendered single-line tree segment such as `├── file.py` or `└── # 6 more folders`).
+- **FR-003**: Accept parameters: `relative_path`, `max_depth` (0 = unlimited), `max_lines` (0 = unlimited), `folders_first` (bool), `max_folders`, `max_files`, `sort` (key: name | modified | created; dir: asc | desc), `ignore` (string with `.gitignore` semantics; if starts with `file:`, load patterns from that file), and `output_mode` (`string` | `flat` | `nested`).
+ - `ignore` resolution rules when using `file:`:
+ - `file:/abs/path/.gitignore` → absolute filesystem path (single slash after colon indicates absolute path)
+ - `file:relative/path/.gitignore` → path resolved relative to `relative_path` (scanned root)
+ - `file://.gitignore` → path resolved relative to `relative_path` (two slashes indicate URI form; still relative without the third slash)
+ - `file:///abs/path/.gitignore` → absolute filesystem path (classic URI absolute form with three slashes)
+ - If not prefixed with `file:`, treat `ignore` as inline `.gitignore` content string
+- **FR-004**: Apply ignore patterns using Git wildmatch semantics (comments, blanks ignored; support `!` negation, directory-only patterns, `**` recursion) against paths relative to the scanned root.
+- **FR-005**: Sorting: group by folder/file based on `folders_first`, then sort by the requested key and direction within each group. Default is sort by modification time descending; default `folders_first=True` (folders before files).
+- **FR-006**: Traversal order is breadth-first by depth: scan and render all directories at level N before descending to N+1, honoring `max_depth`, `max_files`, and `max_folders`.
+- **FR-007**: When limits are reached within a directory, render summary comment lines indicating the number of omitted files and/or folders (e.g., `# 12 more files`, `# 6 more folders`).
+- **FR-008**: The ASCII `text` format uses `├──`/`└──` with indentation guides, appends `/` to folders, and prefixes comments with `# `.
+- **FR-009**: Errors for invalid inputs (e.g., non-existent path) must be clear and actionable.
+- **FR-010**: Implementation MUST satisfy the detailed interface contract documented in `specs/001-file-tree-utility/contracts/file_tree.md`, including developer-facing ergonomics, helper structure, and docstring guidance.
+
+## Clarifications
+
+### Session 2025-11-08
+
+- Q: What should be the default for `folders_first` ordering? → A: `True` (folders before files) by default.
+- Q: Which filesystem access conventions should be followed? → A: Use Agent Zero wrappers in `python/helpers/files.py` (e.g., `get_abs_path`, `exists`, `list_files`) whenever possible; fallback to the same Python modules used in `files.py` only when no wrapper exists.
+- Q: How to resolve `ignore` when prefixed with `file:`? → A: Resolve relative to `relative_path` when the path after `file:` or `file://` is relative; treat as absolute when starting with `/` (support both `file:/abs/...` and `file:///abs/...`). Document with examples in the function docstring.
+
+### Key Entities *(include if feature involves data)*
+
+- **TreeItem**:
+ - `name: str` — filename or folder name (or comment label)
+ - `level: int` — depth level starting from 1 at root entries
+ - `type: "file" | "folder" | "comment"`
+ - `created: datetime` — timezone-aware UTC
+ - `modified: datetime` — timezone-aware UTC
+ - `text: str` — one-line rendered tree segment
+ - `items: list[TreeItem] | null` — present for folders in nested mode; empty or null for files and comments
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: For a known synthetic structure (≤ 50 nodes), `mode=string` output matches the stored snapshot exactly (whitespace and glyphs).
+- **SC-002**: Given ignore patterns with negations, excluded entries never appear and negated entries always appear in all modes.
+- **SC-003**: For a directory containing ≥ 5,000 entries, an automated test using a monotonic timer (`time.perf_counter()`) asserts that a call with `max_lines=200` completes within 2.0 seconds while rendering deterministic ordering and correct summary comment lines.
+- **SC-004**: `created`/`modified` fields are timezone-aware UTC datetimes and can be converted to ISO 8601 strings and Unix timestamps without loss of timezone information in all modes that include metadata.
+- **SC-005**: Automated tests create temporary top-level directories using the mktemp family (cross‑platform), generate synthetic structures, and validate:
+ - String snapshot equality for `mode=string`
+ - Structural and field correctness for `mode=flat` and `mode=nested`
+ - Ignore semantics including negation and directory-only patterns in all modes (string, flat, nested)
+ - Breadth-first ordering across multiple depth levels (fails if depth-first traversal occurs)
+ - Sorting and summary comment behaviors under limits
+ - Sorting for `name`, `created`, and `modified` keys in both ascending and descending directions across flat and nested outputs
+ - `created`/`modified` metadata returned by flat and nested modes matches the filesystem stats for the represented entries
+ - Invalid parameter paths (unsupported sort tuples, unknown output modes, negative limits, missing referenced ignore file) raise the documented exceptions
+ Tests reside under `tests/` and use the utility from `python/helpers/files.py`.
+
+## Testing
+
+- Tests MUST construct synthetic folder/file structures in temporary directories using mktemp family functions to ensure cross‑platform behavior.
+- Tests MUST import and exercise `file_tree()` from `python/helpers/files.py` (no duplicated logic).
+- Recommended organization:
+ - `tests/test_file_tree_string.py` — end‑to‑end snapshot tests for `mode=string`
+ - `tests/test_file_tree_structured.py` — validations for `mode=flat` and `mode=nested` (fields, levels, types, ordering)
+ - `tests/test_file_tree_ignore_and_limits.py` — `.gitignore` semantics, `max_files`/`max_folders`, `max_depth`, `max_lines`
+- For snapshots, store expected multi‑line strings as literals within tests or fixture files adjacent to tests; ensure glyphs (`├──`, `└──`) and folder suffix `/` and comment prefix `# ` are preserved.
+
+## Dependencies
+
+- `.gitignore` evaluation MUST use `pathspec` (Git wildmatch semantics). Target version: `pathspec==0.12.1` (or newer compatible) for implementation; exact pin may be set during dependency management.
diff --git a/specs/001-file-tree-utility/tasks.md b/specs/001-file-tree-utility/tasks.md
new file mode 100644
index 000000000..0052aa122
--- /dev/null
+++ b/specs/001-file-tree-utility/tasks.md
@@ -0,0 +1,92 @@
+# Tasks: File Tree Utility (`001-file-tree-utility`)
+
+This checklist is organized by phases and user stories. Each task is atomic, ordered, and includes explicit file paths. Tests are included because the feature specification mandates them.
+
+## Phase 1 — Setup
+
+- [X] T001 [P] Verify `pathspec==0.12.1` present in `requirements.txt` (/home/rafael/Workspace/Repos/rafael/a0-local/requirements.txt)
+- [X] T002 [P] Create pytest module scaffold for string mode tests (create file) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T003 [P] Create pytest module scaffold for structured modes tests (create file) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T004 [P] Create pytest module scaffold for ignore/limits tests (create file) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+
+## Phase 2 — Foundational
+
+- [X] T005 Add required imports for file tree utility (datetime, typing, pathspec usage; reuse existing helpers) (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T006 Define constants `SORT_BY_NAME`, `SORT_BY_CREATED`, `SORT_BY_MODIFIED`, `SORT_ASC`, `SORT_DESC`, `OUTPUT_MODE_STRING`, `OUTPUT_MODE_FLAT`, `OUTPUT_MODE_NESTED` directly above `file_tree()` (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T007 Add `file_tree()` signature and comprehensive docstring per contract (parameters, constants, ignore resolution examples, datetime conversion examples, async usage note) (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T008 Stub internal helpers (`_resolve_ignore_patterns`, `_list_directory_children`, `_apply_sorting_and_limits`, `_format_line`, `_build_tree_items_flat`, `_to_nested_structure`) at end of module (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+
+## Phase 3 — [US1] Readable Tree Overview (P1)
+
+- [X] T009 [US1] Implement breadth‑first traversal and directory scanning pipeline honoring `max_depth` (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T010 [US1] Implement `.gitignore` wildmatch filtering via `pathspec`; support `file:` resolution variants (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T011 [US1] Implement grouping/sorting with `folders_first` and `(key, direction)`; default `(modified, desc)` (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T012 [US1] Implement per‑directory `max_folders`/`max_files` summaries (`# N more files|folders`) (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T013 [US1] Implement global `max_lines` with finish‑current‑depth behavior before stopping descent (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T014 [US1] Implement ASCII render (`├──`/`└──`, folder `/`, `#` comment prefix) and return `OUTPUT_MODE_STRING` string (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T015 [P] [US1] Write snapshot tests for string mode output (glyphs, folder suffix, comments) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T016 [P] [US1] Write tests for ignore semantics and per‑directory/global limits (may exercise multiple modes) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+- [X] T024 [US1] Implement invalid-input error handling: raise clear exception for non-existent `relative_path` (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T025 [P] [US1] Add test asserting clear exception/message for non-existent `relative_path` (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T026 [P] [US1] Write test: empty directory renders top-level only, no errors (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T027 [P] [US1] Write test: `folders_first=False` ordering in string mode (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T028 [P] [US1] Write tests: sort variants (name/created/modified × asc/desc) in string mode (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T029 [P] [US1] Write tests: `max_depth` behaviors (0 unlimited, 1, 2) in string mode (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T030 [P] [US1] Write test: `max_lines` finishes current depth before stopping (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+- [X] T031 [P] [US1] Write tests: per-directory `max_folders`/`max_files` with correct summary comments (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+- [X] T032 [P] [US1] Write tests: ignore inline semantics including `!` negation, directory-only `/`, `**` recursion (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+- [X] T033 [P] [US1] Write tests: ignore from file using `file:`, `file://`, `file:///` resolution (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+- [X] T048 [P] [US1] Write regression test that fails when traversal output becomes depth-first (assert breadth-first ordering across multiple depths) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T034 [P] [US1] Execute US1 tests and record results (pytest selection) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/)
+- [X] T035 [P] [US1] Baseline/update snapshots using external fixture files; ensure glyphs and formatting preserved (/home/rafael/Workspace/Repos/rafael/a0-local/tests/fixtures/file_tree/)
+- [X] T046 [P] [US1] Create snapshot fixtures directory and baseline files (e.g., `us1_string_default.txt`, permutations) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/fixtures/file_tree/)
+- [X] T047 [P] [US1] Update string-mode tests to load expected snapshots from fixture files (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+
+## Phase 4 — [US2] Flat Structured Listing (P2)
+
+- [X] T017 [US2] Implement `OUTPUT_MODE_FLAT` returning list of dicts with fields (`name`, `level`, `type`, `created`, `modified`, `text`) (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T018 [P] [US2] Write tests validating flat items, tz‑aware UTC datetimes, ordering and levels (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T036 [P] [US2] Write test: all fields present and `created`/`modified` are tz-aware UTC (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T037 [P] [US2] Write test: levels align with hierarchy; files/comments have no `items` (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T038 [P] [US2] Write tests: ordering respects `folders_first` and sort variants in flat mode (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T039 [P] [US2] Write tests: ignore semantics mirrored in flat mode (inline and file-based) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T040 [P] [US2] Execute US2 tests and record results (pytest selection) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/)
+
+## Phase 5 — [US3] Nested Structured Listing (P3)
+
+- [X] T019 [US3] Implement `OUTPUT_MODE_NESTED` building hierarchical `items` arrays; honor `max_depth` (/home/rafael/Workspace/Repos/rafael/a0-local/python/helpers/files.py)
+- [X] T020 [P] [US3] Write tests validating nested structure, children arrays, and depth limiting (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T041 [P] [US3] Write test: nested items arrays for folders; files/comments have `None`/empty (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T042 [P] [US3] Write test: `max_depth` truncation represented appropriately (e.g., comment items) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T043 [P] [US3] Write test: deterministic ordering within each level in nested mode (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+- [X] T044 [P] [US3] Execute US3 tests and record results (pytest selection) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/)
+- [X] T049 [P] [US3] Write tests: ignore semantics (including `!`, `/`, `**`, file-based patterns) reflected in `OUTPUT_MODE_NESTED` results (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+
+## Final Phase — Polish & Cross‑Cutting
+
+- [X] T022 [P] Add automated performance guard test using `time.perf_counter()` to assert a ≥5k entry synthetic tree with `max_lines=200` completes within 2.0 seconds while verifying deterministic ordering and summary comments (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_ignore_and_limits.py)
+- [X] T023 [P] Align contract doc with final signature/details if needed (/home/rafael/Workspace/Repos/rafael/a0-local/specs/001-file-tree-utility/contracts/file_tree.md)
+- [X] T045 [P] Run full test suite and collect coverage report (target 100% for new code) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/)
+
+## Phase 6 — Extended Validation
+
+- [X] T050 [P] Expand string-mode coverage to validate all sorting key/direction combinations and deep `max_lines` truncation (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_string.py)
+- [X] T051 [P] Add negative/invalid parameter tests (unsupported sort tuples, invalid output modes, negative limits, missing ignore file) (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_invalid.py)
+- [X] T052 [P] Validate nested summary comment generation when per-directory limits truncate children (/home/rafael/Workspace/Repos/rafael/a0-local/tests/test_file_tree_structured.py)
+
+---
+
+## Dependencies (Story Order)
+- US1 → US2 → US3 (string mode first, then flat, then nested). Foundational Phase 2 must precede all stories.
+
+## Parallel Execution Examples
+- US1: Implement `_resolve_ignore_patterns` [P] in parallel with writing initial snapshot tests file.
+- US2: Add flat‑mode fields and write field assertions [P] concurrently.
+- US3: Build `_to_nested_structure` [P] while extending structured tests for nested validation.
+
+## Implementation Strategy
+- MVP scope: Complete US1 (string mode) with ignore/limits and snapshot tests.
+- Incrementally add US2 (flat) and US3 (nested), keeping tests green after each phase.
+
+## Validation
+- All tasks follow required checklist format with IDs, optional [P], optional [US?], and explicit file paths.
diff --git a/tests/fixtures/file_tree/string_breadth_first.txt b/tests/fixtures/file_tree/string_breadth_first.txt
new file mode 100644
index 000000000..feae4e0b9
--- /dev/null
+++ b/tests/fixtures/file_tree/string_breadth_first.txt
@@ -0,0 +1,10 @@
+tmp/tests/file_tree/string_breadth_first/
+├── alpha/
+│ ├── nested/
+│ │ └── inner.txt
+│ └── alpha_file.txt
+├── beta/
+│ └── beta_file.txt
+├── zeta/
+├── a.txt
+└── b.txt
diff --git a/tests/fixtures/file_tree/string_ignore_limits.txt b/tests/fixtures/file_tree/string_ignore_limits.txt
new file mode 100644
index 000000000..a987bee64
--- /dev/null
+++ b/tests/fixtures/file_tree/string_ignore_limits.txt
@@ -0,0 +1,14 @@
+tmp/tests/file_tree/string_ignore_limits/
+├── .treeignore
+├── notes.md
+├── logs/
+│ └── 2025.log
+└── src/
+ ├── main.py
+ ├── utils.py
+ ├── cache/
+ │ └── keep.txt
+ └── modules/
+ ├── a.py
+ ├── b.py
+ └── c.py
diff --git a/tests/test_file_tree_ignore_and_limits.py b/tests/test_file_tree_ignore_and_limits.py
new file mode 100644
index 000000000..6145cebf7
--- /dev/null
+++ b/tests/test_file_tree_ignore_and_limits.py
@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import os
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+import pytest
+
+from python.helpers.files import (
+ OUTPUT_MODE_FLAT,
+ OUTPUT_MODE_STRING,
+ SORT_ASC,
+ SORT_BY_NAME,
+ create_dir,
+ delete_dir,
+ file_tree,
+ get_abs_path,
+ write_file,
+)
+
+
+@contextmanager
+def _project_directory(relative_path: str):
+ delete_dir(relative_path)
+ try:
+ create_dir(relative_path)
+ yield Path(get_abs_path(relative_path))
+ finally:
+ delete_dir(relative_path)
+
+
+def _materialize_structure(base_rel: str, structure: dict[str, object]) -> None:
+ for name, value in structure.items():
+ rel = os.path.join(base_rel, name)
+ if isinstance(value, dict):
+ create_dir(rel)
+ _materialize_structure(rel, value)
+ else:
+ write_file(rel, "" if value is None else str(value))
+
+
+def test_file_tree_ignore_file_reference_variants() -> None:
+ base_rel = "tmp/tests/file_tree/ignore_file_variants"
+ absolute_ignore = Path(get_abs_path(base_rel)) / "absolute.ignore"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "app": {
+ "build.tmp": "",
+ "main.py": "",
+ "README.md": "",
+ },
+ },
+ )
+ root_ignore = Path(get_abs_path(base_rel)) / ".treeignore"
+ root_ignore.write_text("*.tmp\n", encoding="utf-8")
+ absolute_ignore.write_text("README.md\n", encoding="utf-8")
+
+ inline_result = file_tree(
+ base_rel,
+ ignore="file:.treeignore",
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ abs_result = file_tree(
+ base_rel,
+ ignore=f"file:{absolute_ignore}",
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ url_result = file_tree(
+ base_rel,
+ ignore="file://.treeignore",
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ inline_patterns = file_tree(
+ base_rel,
+ ignore="*.tmp\n!build.tmp",
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+
+ inline_names = {item["name"] for item in inline_result}
+ abs_names = {item["name"] for item in abs_result}
+ url_names = {item["name"] for item in url_result}
+ inline_pattern_names = {item["name"] for item in inline_patterns}
+
+ assert "build.tmp" not in inline_names
+ assert "README.md" in inline_names
+ assert "README.md" not in abs_names
+ assert inline_names == url_names
+ assert "build.tmp" in inline_pattern_names
+
+
+def test_file_tree_limits_emit_summary_comments() -> None:
+ base_rel = "tmp/tests/file_tree/limits_summary"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "pkg": {
+ "a.py": "",
+ "b.py": "",
+ "c.py": "",
+ "d.py": "",
+ "e.py": "",
+ "dir1": {},
+ "dir2": {},
+ "dir3": {},
+ "dir4": {},
+ }
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ max_folders=2,
+ max_files=2,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ lines = result.splitlines()
+ assert any("# 2 more folders" in line for line in lines)
+ assert any("# 3 more files" in line for line in lines)
+
+
+def test_file_tree_global_max_lines() -> None:
+ base_rel = "tmp/tests/file_tree/global_max_lines"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dirA": {"a.txt": "", "b.txt": ""},
+ "dirB": {"c.txt": "", "d.txt": ""},
+ "x.txt": "",
+ "y.txt": "",
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ max_lines=5,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+ flat = file_tree(
+ base_rel,
+ max_lines=5,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+
+ lines = result.splitlines()
+ flat_levels = [item["level"] for item in flat]
+ assert all(level <= 2 for level in flat_levels)
+ top_level_names = {item["name"] for item in flat if item["level"] == 1}
+ assert top_level_names == {"dirA", "dirB", "x.txt", "y.txt"}
+ assert not any("│ " in line for line in lines)
+
+
+def test_file_tree_limits_exact_counts_no_comment() -> None:
+ base_rel = "tmp/tests/file_tree/limits_exact"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "pkg": {
+ "a.py": "",
+ "b.py": "",
+ "dir1": {},
+ "dir2": {},
+ }
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=True,
+ max_folders=2,
+ max_files=2,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ assert "# " not in result
+
+
+def test_file_tree_limits_single_overflow_flat_mode() -> None:
+ base_rel = "tmp/tests/file_tree/limits_single_flat"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "pkg": {
+ "dir_a": {},
+ "dir_b": {},
+ }
+ },
+ )
+
+ flat = file_tree(
+ base_rel,
+ folders_first=True,
+ max_folders=1,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+
+ assert all(item["type"] != "comment" for item in flat)
+ folder_names = [item["name"] for item in flat if item["type"] == "folder"]
+ assert folder_names == ["pkg", "dir_a", "dir_b"]
+
+
+def test_file_tree_performance_guard_large_directory() -> None:
+ base_rel = "tmp/tests/file_tree/performance_guard"
+ with _project_directory(base_rel):
+ structure = {f"dir{i}": {} for i in range(50)}
+ files = {f"file{i}.txt": "" for i in range(4900)}
+ structure.update(files)
+ _materialize_structure(base_rel, structure)
+
+ start = time.perf_counter()
+ file_tree(
+ base_rel,
+ max_lines=200,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+ duration = time.perf_counter() - start
+
+ assert duration < 2.0
diff --git a/tests/test_file_tree_invalid.py b/tests/test_file_tree_invalid.py
new file mode 100644
index 000000000..8022b0a52
--- /dev/null
+++ b/tests/test_file_tree_invalid.py
@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+
+import pytest
+
+from python.helpers.files import (
+ OUTPUT_MODE_STRING,
+ SORT_ASC,
+ SORT_BY_NAME,
+ create_dir,
+ delete_dir,
+ file_tree,
+ get_abs_path,
+ write_file,
+)
+
+
+@contextmanager
+def _project_directory(relative_path: str):
+ delete_dir(relative_path)
+ try:
+ create_dir(relative_path)
+ yield Path(get_abs_path(relative_path))
+ finally:
+ delete_dir(relative_path)
+
+
+def _materialize_structure(base_rel: str) -> None:
+ write_file(os.path.join(base_rel, "file.txt"), "content")
+
+
+def test_file_tree_invalid_sort_key() -> None:
+ base_rel = "tmp/tests/file_tree/invalid_sort_key"
+ with _project_directory(base_rel):
+ _materialize_structure(base_rel)
+ with pytest.raises(ValueError):
+ file_tree(
+ base_rel,
+ sort=("unsupported", SORT_ASC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+
+def test_file_tree_invalid_sort_direction() -> None:
+ base_rel = "tmp/tests/file_tree/invalid_sort_direction"
+ with _project_directory(base_rel):
+ _materialize_structure(base_rel)
+ with pytest.raises(ValueError):
+ file_tree(
+ base_rel,
+ sort=(SORT_BY_NAME, "ascending"),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+
+def test_file_tree_invalid_output_mode() -> None:
+ base_rel = "tmp/tests/file_tree/invalid_output_mode"
+ with _project_directory(base_rel):
+ _materialize_structure(base_rel)
+ with pytest.raises(ValueError):
+ file_tree(base_rel, output_mode="yaml")
+
+
+def test_file_tree_negative_depth_and_lines() -> None:
+ base_rel = "tmp/tests/file_tree/invalid_depth_lines"
+ with _project_directory(base_rel):
+ _materialize_structure(base_rel)
+ with pytest.raises(ValueError):
+ file_tree(base_rel, max_depth=-1)
+ with pytest.raises(ValueError):
+ file_tree(base_rel, max_lines=-5)
+
+
+def test_file_tree_missing_ignore_file() -> None:
+ base_rel = "tmp/tests/file_tree/missing_ignore"
+ with _project_directory(base_rel):
+ _materialize_structure(base_rel)
+ with pytest.raises(FileNotFoundError):
+ file_tree(
+ base_rel,
+ ignore="file:missing.ignore",
+ output_mode=OUTPUT_MODE_STRING,
+ )
diff --git a/tests/test_file_tree_string.py b/tests/test_file_tree_string.py
new file mode 100644
index 000000000..0d5fe0626
--- /dev/null
+++ b/tests/test_file_tree_string.py
@@ -0,0 +1,493 @@
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+import time
+
+import pytest
+
+from python.helpers.files import (
+ OUTPUT_MODE_FLAT,
+ OUTPUT_MODE_STRING,
+ SORT_ASC,
+ SORT_BY_CREATED,
+ SORT_BY_MODIFIED,
+ SORT_BY_NAME,
+ SORT_DESC,
+ create_dir,
+ delete_dir,
+ file_tree,
+ get_abs_path,
+ write_file,
+)
+
+
+FIXTURES_DIR = Path(__file__).resolve().parent / "fixtures" / "file_tree"
+
+
+def _load_fixture(name: str) -> str:
+ return (FIXTURES_DIR / name).read_text(encoding="utf-8").rstrip("\n")
+
+
+@contextmanager
+def _project_directory(relative_path: str):
+ delete_dir(relative_path)
+ try:
+ create_dir(relative_path)
+ yield Path(get_abs_path(relative_path))
+ finally:
+ delete_dir(relative_path)
+
+
+def _materialize_structure(base_rel: str, structure: dict[str, object]) -> None:
+ for entry, value in structure.items():
+ rel = os.path.join(base_rel, entry)
+ if isinstance(value, dict):
+ create_dir(rel)
+ _materialize_structure(rel, value)
+ else:
+ content = "" if value is None else str(value)
+ write_file(rel, content)
+
+
+def _set_entry_times(relative_path: str, timestamp: float) -> None:
+ abs_path = get_abs_path(relative_path)
+ os.utime(abs_path, (timestamp, timestamp))
+ time.sleep(0.01)
+
+
+def _extract_tree_labels(result: str) -> list[str]:
+ labels: list[str] = []
+ for line in result.splitlines()[1:]:
+ if "── " in line:
+ labels.append(line.split("── ", 1)[1])
+ return labels
+
+
+def test_file_tree_string_breadth_first_snapshot() -> None:
+ base_rel = "tmp/tests/file_tree/string_breadth_first"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "alpha": {
+ "alpha_file.txt": "alpha",
+ "nested": {"inner.txt": "inner"},
+ },
+ "beta": {
+ "beta_file.txt": "beta",
+ },
+ "zeta": {},
+ "a.txt": "A",
+ "b.txt": "B",
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ assert result == _load_fixture("string_breadth_first.txt")
+
+
+def test_file_tree_string_ignore_and_limits() -> None:
+ base_rel = "tmp/tests/file_tree/string_ignore_limits"
+ ignore_file_rel = os.path.join(base_rel, ".treeignore")
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "src": {
+ "main.py": "print('hello')",
+ "utils.py": "pass",
+ "tmp.tmp": "",
+ "cache": {
+ "cached.txt": "",
+ "keep.txt": "",
+ },
+ "modules": {
+ "a.py": "",
+ "b.py": "",
+ "c.py": "",
+ },
+ },
+ "logs": {
+ "2024.log": "",
+ "2025.log": "",
+ },
+ "notes.md": "",
+ "build.tmp": "",
+ },
+ )
+
+ write_file(
+ ignore_file_rel,
+ "\n".join(
+ [
+ "*.tmp",
+ "cache/",
+ "!src/cache/keep.txt",
+ "logs/",
+ "!logs/2025.log",
+ ]
+ ),
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=False,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ ignore="file:.treeignore",
+ max_folders=1,
+ max_files=2,
+ max_lines=12,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ assert result == _load_fixture("string_ignore_limits.txt")
+
+
+def test_file_tree_string_single_overflow_promotes_entry() -> None:
+ base_rel = "tmp/tests/file_tree/string_single_overflow"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "first_dir": {},
+ "second_dir": {},
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=True,
+ max_folders=1,
+ sort=(SORT_BY_NAME, SORT_DESC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ assert "# 1 more folder" not in result
+ lines = result.splitlines()
+ assert any(line.endswith("first_dir/") for line in lines)
+ assert any(line.endswith("second_dir/") for line in lines)
+
+
+def test_file_tree_string_summary_comment_after_children() -> None:
+ base_rel = "tmp/tests/file_tree/string_comment_order"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "logs": {
+ "2025.log": "",
+ },
+ "alpha": {},
+ "beta": {},
+ "gamma": {},
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=True,
+ max_folders=1,
+ sort=(SORT_BY_NAME, SORT_DESC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ lines = result.splitlines()
+ comment_index = next(i for i, line in enumerate(lines) if "# 3 more folders" in line)
+ logs_index = next(i for i, line in enumerate(lines) if line.endswith("logs/"))
+ child_index = next(i for i, line in enumerate(lines) if line.strip().endswith("2025.log"))
+ assert logs_index < child_index < comment_index
+
+
+def test_file_tree_string_sort_all_keys() -> None:
+ base_rel = "tmp/tests/file_tree/string_sort_all_keys"
+ with _project_directory(base_rel) as base_abs:
+ _materialize_structure(
+ base_rel,
+ {
+ "folder_alpha": {},
+ "folder_beta": {},
+ "file_first.txt": "",
+ "file_second.txt": "",
+ "file_third.txt": "",
+ },
+ )
+ base_timestamp = time.time()
+ for offset, name in enumerate(
+ [
+ "folder_alpha",
+ "folder_beta",
+ "file_first.txt",
+ "file_second.txt",
+ "file_third.txt",
+ ],
+ start=1,
+ ):
+ _set_entry_times(os.path.join(base_rel, name), base_timestamp + offset)
+
+ stats: dict[str, dict[str, object]] = {}
+ for name in sorted(os.listdir(base_abs)):
+ abs_entry = base_abs / name
+ stat = os.stat(abs_entry, follow_symlinks=False)
+ stats[name] = {
+ "is_dir": abs_entry.is_dir(),
+ "created": stat.st_ctime,
+ "modified": stat.st_mtime,
+ }
+
+ sort_variants = [
+ (SORT_BY_NAME, SORT_ASC),
+ (SORT_BY_NAME, SORT_DESC),
+ (SORT_BY_CREATED, SORT_ASC),
+ (SORT_BY_CREATED, SORT_DESC),
+ (SORT_BY_MODIFIED, SORT_ASC),
+ (SORT_BY_MODIFIED, SORT_DESC),
+ ]
+
+ results = {
+ variant: file_tree(
+ base_rel,
+ folders_first=True,
+ sort=variant,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+ for variant in sort_variants
+ }
+
+ def expected_labels(key: str, direction: str) -> list[str]:
+ reverse = direction == SORT_DESC
+ folders = [(name, stats[name]) for name in stats if stats[name]["is_dir"]]
+ files = [(name, stats[name]) for name in stats if not stats[name]["is_dir"]]
+
+ def sort_key(item):
+ name, meta = item
+ if key == SORT_BY_NAME:
+ return name.casefold()
+ if key == SORT_BY_CREATED:
+ return meta["created"]
+ return meta["modified"]
+
+ folders_sorted = sorted(folders, key=sort_key, reverse=reverse)
+ files_sorted = sorted(files, key=sort_key, reverse=reverse)
+ labels = [f"{name}/" for name, _ in folders_sorted]
+ labels.extend(name for name, _ in files_sorted)
+ return labels
+
+ for key, direction in sort_variants:
+ labels = _extract_tree_labels(results[(key, direction)])
+ assert labels == expected_labels(key, direction)
+
+
+def test_file_tree_string_missing_path() -> None:
+ with pytest.raises(FileNotFoundError):
+ file_tree(
+ "tmp/tests/file_tree/does_not_exist",
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+
+def test_file_tree_string_empty_directory() -> None:
+ base_rel = "tmp/tests/file_tree/string_empty"
+ with _project_directory(base_rel):
+ result = file_tree(base_rel, output_mode=OUTPUT_MODE_STRING)
+ assert result == "tmp/tests/file_tree/string_empty/"
+
+
+def test_file_tree_string_folders_first_disabled() -> None:
+ base_rel = "tmp/tests/file_tree/string_folders_first"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "folder": {"child.txt": ""},
+ "alpha.txt": "",
+ },
+ )
+ result = file_tree(
+ base_rel,
+ folders_first=False,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_STRING,
+ )
+ lines = result.splitlines()
+ assert lines[1] == "├── alpha.txt" # file precedes folder when folders_first=False
+
+
+def test_file_tree_string_max_depth_levels() -> None:
+ base_rel = "tmp/tests/file_tree/string_max_depth"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "level1": {
+ "level2": {
+ "level3.txt": "",
+ },
+ },
+ },
+ )
+ depth_one = file_tree(
+ base_rel,
+ max_depth=1,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+ depth_two = file_tree(
+ base_rel,
+ max_depth=2,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+ assert depth_one.splitlines() == ["tmp/tests/file_tree/string_max_depth/", "└── level1/"]
+ assert "level2/" in depth_two
+
+
+def test_file_tree_string_bfs_regression_flat_levels() -> None:
+ base_rel = "tmp/tests/file_tree/string_bfs_regression"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dirA": {"a1.txt": "", "a2.txt": ""},
+ "dirB": {"b1.txt": ""},
+ "root.txt": "",
+ },
+ )
+ flat = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ levels = [item["level"] for item in flat]
+ assert levels[0] == 1
+ for current, nxt in zip(levels, levels[1:]):
+ assert nxt <= current + 1, "level jumps exceed single depth step"
+
+
+def test_file_tree_string_deep_structure_limits() -> None:
+ base_rel = "tmp/tests/file_tree/string_deep_limits"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "layer1_a": {
+ "layer2_a": {
+ "layer3_a": {
+ "layer4_a": {
+ "layer5_a.txt": "",
+ }
+ }
+ }
+ },
+ "layer1_b": {
+ "layer2_b": {
+ "layer3_b": {
+ "layer4_b": {
+ "layer5_b.txt": "",
+ }
+ }
+ }
+ },
+ "root_file.txt": "",
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ max_lines=6,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ lines = result.splitlines()
+ deep_names = {"layer4_a/", "layer5_a.txt", "layer4_b/", "layer5_b.txt"}
+ combined = "\n".join(lines)
+ for name in deep_names:
+ assert name not in combined
+ assert lines[1:] == [
+ "├── layer1_b/",
+ "│ └── layer2_b/",
+ "│ └── layer3_b/",
+ "├── layer1_a/",
+ "│ └── layer2_a/",
+ "│ └── layer3_a/",
+ "└── root_file.txt",
+ ]
+
+
+def test_file_tree_string_files_first_max_lines_modified() -> None:
+ base_rel = "tmp/tests/file_tree/string_files_first_modified"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dir": {
+ "inner_a.txt": "",
+ "inner_b.txt": "",
+ },
+ "alpha.txt": "",
+ "beta.txt": "",
+ "gamma.txt": "",
+ },
+ )
+ base_ts = time.time()
+ for offset, rel_path in enumerate(
+ [
+ "dir",
+ os.path.join("dir", "inner_a.txt"),
+ os.path.join("dir", "inner_b.txt"),
+ "alpha.txt",
+ "beta.txt",
+ "gamma.txt",
+ ],
+ start=1,
+ ):
+ _set_entry_times(os.path.join(base_rel, rel_path), base_ts + offset)
+
+ result = file_tree(
+ base_rel,
+ folders_first=False,
+ sort=(SORT_BY_MODIFIED, SORT_DESC),
+ max_lines=4,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ lines = result.splitlines()
+ assert len(lines) == 5 # root + 4 entries
+ assert lines[1].endswith("gamma.txt")
+ assert "inner_b.txt" not in result
+
+
+def test_file_tree_string_zero_file_limit_unlimited() -> None:
+ base_rel = "tmp/tests/file_tree/string_zero_limit"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "folder1": {},
+ "folder2": {},
+ "folder3": {},
+ "a.py": "",
+ "b.py": "",
+ "c.py": "",
+ },
+ )
+
+ result = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ max_folders=1,
+ max_files=0,
+ output_mode=OUTPUT_MODE_STRING,
+ )
+
+ lines = result.splitlines()
+ assert any("# 2 more folders" in line for line in lines)
+ assert all("more files" not in line for line in lines)
+ assert "a.py" in result and "c.py" in result
diff --git a/tests/test_file_tree_structured.py b/tests/test_file_tree_structured.py
new file mode 100644
index 000000000..3fd589d01
--- /dev/null
+++ b/tests/test_file_tree_structured.py
@@ -0,0 +1,578 @@
+from __future__ import annotations
+
+import os
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pytest
+
+from python.helpers.files import (
+ OUTPUT_MODE_FLAT,
+ OUTPUT_MODE_NESTED,
+ SORT_ASC,
+ SORT_BY_CREATED,
+ SORT_BY_MODIFIED,
+ SORT_BY_NAME,
+ SORT_DESC,
+ create_dir,
+ delete_dir,
+ file_tree,
+ get_abs_path,
+ write_file,
+)
+
+
+@contextmanager
+def _project_directory(relative_path: str):
+ delete_dir(relative_path)
+ try:
+ create_dir(relative_path)
+ yield Path(get_abs_path(relative_path))
+ finally:
+ delete_dir(relative_path)
+
+
+def _materialize_structure(base_rel: str, structure: dict[str, object]) -> None:
+ for name, value in structure.items():
+ rel = os.path.join(base_rel, name)
+ if isinstance(value, dict):
+ create_dir(rel)
+ _materialize_structure(rel, value)
+ else:
+ write_file(rel, "" if value is None else str(value))
+
+
+def _set_entry_times(relative_path: str, timestamp: float) -> None:
+ abs_path = get_abs_path(relative_path)
+ os.utime(abs_path, (timestamp, timestamp))
+ time.sleep(0.01)
+
+
+def _collect_expected_stats(base_abs: Path) -> dict[str, tuple[datetime, datetime]]:
+ results: dict[str, tuple[datetime, datetime]] = {}
+ for current_path, dirnames, filenames in os.walk(base_abs):
+ for name in dirnames + filenames:
+ path = os.path.join(current_path, name)
+ stat = os.stat(path, follow_symlinks=False)
+ created = datetime.fromtimestamp(stat.st_ctime, tz=timezone.utc)
+ modified = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
+ results[name] = (created, modified)
+ return results
+
+
+def _flatten_nested(items: list[dict]) -> list[dict]:
+ result: list[dict] = []
+ for item in items:
+ result.append(item)
+ if item.get("items"):
+ result.extend(_flatten_nested(item["items"]))
+ return result
+
+
+def _assert_datetime_order(values: list[datetime], direction: str) -> None:
+ expected = sorted(values, reverse=direction == SORT_DESC)
+ assert values == expected
+
+
+def test_file_tree_flat_metadata_and_levels() -> None:
+ base_rel = "tmp/tests/file_tree/flat_metadata"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dirA": {
+ "file1.txt": "",
+ "file2.txt": "",
+ },
+ "dirB": {
+ "sub": {
+ "inner.txt": "",
+ },
+ },
+ "root.txt": "",
+ },
+ )
+
+ flat = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ flat_files_first = file_tree(
+ base_rel,
+ folders_first=False,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+
+ assert all("items" in item for item in flat)
+ assert all(item["type"] in {"file", "folder", "comment"} for item in flat)
+
+ # Ensure datetime fields are timezone-aware UTC
+ for item in flat:
+ assert item["created"].tzinfo is not None
+ assert item["modified"].tzinfo is not None
+
+ # Level ordering: first three entries should be level 1 (dirA, dirB, root.txt)
+ levels = [item["level"] for item in flat]
+ level_one_names = [item["name"] for item in flat if item["level"] == 1]
+ assert level_one_names == ["dirA", "dirB", "root.txt"]
+ assert flat[0]["type"] == "folder"
+ assert flat_files_first[0]["type"] == "file"
+
+
+def test_file_tree_flat_sort_all_keys() -> None:
+ base_rel = "tmp/tests/file_tree/flat_sort_all_keys"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dir_first": {},
+ "dir_second": {},
+ "file_alpha.txt": "",
+ "file_beta.txt": "",
+ "file_gamma.txt": "",
+ },
+ )
+ base_timestamp = time.time()
+ for offset, name in enumerate(
+ ["dir_first", "dir_second", "file_alpha.txt", "file_beta.txt", "file_gamma.txt"],
+ start=1,
+ ):
+ _set_entry_times(os.path.join(base_rel, name), base_timestamp + offset)
+
+ flat_results = {
+ (key, direction): file_tree(
+ base_rel,
+ folders_first=False,
+ sort=(key, direction),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ for key in (SORT_BY_NAME, SORT_BY_CREATED, SORT_BY_MODIFIED)
+ for direction in (SORT_ASC, SORT_DESC)
+ }
+
+ for (key, direction), items in flat_results.items():
+ filtered = [item for item in items if item["type"] != "comment"]
+ folders = [item for item in filtered if item["type"] == "folder"]
+ files = [item for item in filtered if item["type"] == "file"]
+
+ if key == SORT_BY_NAME:
+ file_names = [item["name"] for item in files]
+ folder_names = [item["name"] for item in folders]
+ assert file_names == sorted(file_names, reverse=direction == SORT_DESC)
+ assert folder_names == sorted(folder_names, reverse=direction == SORT_DESC)
+ elif key == SORT_BY_CREATED:
+ file_created = [item["created"] for item in files]
+ folder_created = [item["created"] for item in folders]
+ _assert_datetime_order(file_created, direction)
+ _assert_datetime_order(folder_created, direction)
+ else:
+ file_modified = [item["modified"] for item in files]
+ folder_modified = [item["modified"] for item in folders]
+ _assert_datetime_order(file_modified, direction)
+ _assert_datetime_order(folder_modified, direction)
+
+
+def test_file_tree_nested_structure_and_ignore() -> None:
+ base_rel = "tmp/tests/file_tree/nested_structure"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "src": {
+ "a.py": "",
+ "b.py": "",
+ "cache": {
+ "ignored.py": "",
+ "keep.py": "",
+ },
+ },
+ "README.md": "",
+ },
+ )
+
+ nested = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ ignore="cache/\n!src/cache/keep.py",
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ assert isinstance(nested, list)
+ src_node = next(node for node in nested if node["name"] == "src")
+ src_children = {child["name"] for child in src_node["items"]}
+ assert "cache" in src_children # cache appears to host keep.py
+
+ cache_node = next(child for child in src_node["items"] if child["name"] == "cache")
+ cache_children = {child["name"] for child in cache_node["items"]}
+ assert "keep.py" in cache_children
+ assert "ignored.py" not in cache_children
+ assert [child["name"] for child in src_node["items"]] == ["cache", "a.py", "b.py"]
+
+
+def test_file_tree_nested_sort_all_keys() -> None:
+ base_rel = "tmp/tests/file_tree/nested_sort_all_keys"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dir_first": {
+ "inner_a.txt": "",
+ "inner_b.txt": "",
+ },
+ "dir_second": {
+ "nested_dir": {
+ "deep_file.txt": "",
+ },
+ },
+ "file_alpha.txt": "",
+ },
+ )
+ base_timestamp = time.time()
+ for offset, rel_path in enumerate(
+ [
+ "dir_first",
+ os.path.join("dir_first", "inner_a.txt"),
+ os.path.join("dir_first", "inner_b.txt"),
+ "dir_second",
+ os.path.join("dir_second", "nested_dir"),
+ os.path.join("dir_second", "nested_dir", "deep_file.txt"),
+ "file_alpha.txt",
+ ],
+ start=1,
+ ):
+ _set_entry_times(os.path.join(base_rel, rel_path), base_timestamp + offset)
+
+ nested_results = {
+ (key, direction): file_tree(
+ base_rel,
+ folders_first=False,
+ sort=(key, direction),
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+ for key in (SORT_BY_NAME, SORT_BY_CREATED, SORT_BY_MODIFIED)
+ for direction in (SORT_ASC, SORT_DESC)
+ }
+
+ def assert_nested_sorted(items: list[dict], key: str, direction: str) -> None:
+ filtered = [item for item in items if item["type"] != "comment"]
+ if not filtered:
+ return
+ folders = [item for item in filtered if item["type"] == "folder"]
+ files = [item for item in filtered if item["type"] == "file"]
+
+ def assert_group(group: list[dict], attr: str) -> None:
+ values = [entry[attr] for entry in group]
+ if attr == "name":
+ assert values == sorted(values, reverse=direction == SORT_DESC)
+ else:
+ _assert_datetime_order(values, direction)
+
+ if key == SORT_BY_NAME:
+ assert_group(files, "name")
+ assert_group(folders, "name")
+ elif key == SORT_BY_CREATED:
+ assert_group(files, "created")
+ assert_group(folders, "created")
+ else:
+ assert_group(files, "modified")
+ assert_group(folders, "modified")
+
+ for child in folders + files:
+ if child.get("items"):
+ assert_nested_sorted(child["items"], key, direction)
+
+ for (key, direction), items in nested_results.items():
+ assert_nested_sorted(items, key, direction)
+
+
+def test_file_tree_nested_respects_max_depth() -> None:
+ base_rel = "tmp/tests/file_tree/nested_max_depth"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "top": {
+ "branch": {
+ "leaf.txt": "",
+ },
+ },
+ },
+ )
+
+ nested = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ max_depth=1,
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ top_node = nested[0]
+ assert top_node["items"] == [] # depth limited, children omitted
+
+
+def test_file_tree_flat_and_nested_timestamps_match_filesystem() -> None:
+ base_rel = "tmp/tests/file_tree/timestamp_accuracy"
+ with _project_directory(base_rel) as base_abs:
+ _materialize_structure(
+ base_rel,
+ {
+ "folder_root": {
+ "folder_branch": {
+ "leaf_unique.txt": "",
+ },
+ "leaf_second.txt": "",
+ },
+ "file_standalone.txt": "",
+ },
+ )
+
+ expected_stats = _collect_expected_stats(base_abs)
+ flat = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+ nested = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ def assert_matches(item: dict) -> None:
+ if item["type"] == "comment":
+ return
+ created, modified = expected_stats[item["name"]]
+ assert item["created"] == created
+ assert item["modified"] == modified
+
+ for entry in flat:
+ assert_matches(entry)
+
+ for entry in _flatten_nested(nested):
+ assert_matches(entry)
+
+
+def test_file_tree_nested_summary_comments() -> None:
+ base_rel = "tmp/tests/file_tree/nested_summary_comments"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "folder_root": {
+ "keep_me.txt": "",
+ "omit_me.txt": "",
+ "omit_me_too.txt": "",
+ }
+ },
+ )
+ base_timestamp = time.time()
+ _set_entry_times(os.path.join(base_rel, "folder_root/keep_me.txt"), base_timestamp + 3)
+ _set_entry_times(os.path.join(base_rel, "folder_root/omit_me.txt"), base_timestamp + 1)
+ _set_entry_times(os.path.join(base_rel, "folder_root/omit_me_too.txt"), base_timestamp + 2)
+
+ nested = file_tree(
+ base_rel,
+ folders_first=True,
+ max_files=1,
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ folder_node = nested[0]
+ assert folder_node["name"] == "folder_root"
+ child_items = folder_node["items"]
+ assert child_items is not None
+ comment_nodes = [item for item in child_items if item["type"] == "comment"]
+ assert comment_nodes, "Expected summary comment for truncated children"
+ comment_label = comment_nodes[0]["text"].split("── ", 1)[-1]
+ assert comment_label.startswith("# ")
+ file_names = [item["name"] for item in child_items if item["type"] == "file"]
+ assert file_names == ["keep_me.txt"]
+ assert comment_nodes[0] is child_items[-1]
+ assert comment_nodes[0]["items"] is None
+
+
+def test_file_tree_flat_files_first_limits() -> None:
+ base_rel = "tmp/tests/file_tree/flat_files_first_limits"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dir1": {},
+ "dir2": {},
+ "dir3": {},
+ "dir4": {},
+ "a.txt": "",
+ "b.txt": "",
+ "c.txt": "",
+ },
+ )
+
+ flat = file_tree(
+ base_rel,
+ folders_first=False,
+ max_folders=1,
+ max_files=1,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+
+ comment_nodes = [item for item in flat if item["type"] == "comment"]
+ assert {node["name"] for node in comment_nodes} == {"3 more folders", "2 more files"}
+ assert flat[0]["type"] == "file" # files come first when folders_first=False
+
+
+def test_file_tree_flat_sort_created_max_lines() -> None:
+ base_rel = "tmp/tests/file_tree/flat_sort_created_max_lines"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dirA": {"inner.txt": ""},
+ "file1.txt": "",
+ "file2.txt": "",
+ "file3.txt": "",
+ },
+ )
+ base_ts = time.time()
+ for offset, rel_path in enumerate(
+ [
+ "dirA",
+ os.path.join("dirA", "inner.txt"),
+ "file1.txt",
+ "file2.txt",
+ "file3.txt",
+ ],
+ start=1,
+ ):
+ _set_entry_times(os.path.join(base_rel, rel_path), base_ts + offset)
+
+ flat = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_CREATED, SORT_DESC),
+ max_lines=4,
+ output_mode=OUTPUT_MODE_FLAT,
+ )
+
+ assert len(flat) == 4
+ assert flat[0]["name"] == "dirA"
+ file_names = [item["name"] for item in flat if item["type"] == "file"]
+ assert file_names == ["file3.txt", "file2.txt", "file1.txt"]
+
+
+def test_file_tree_nested_files_first_limits() -> None:
+ base_rel = "tmp/tests/file_tree/nested_files_first_limits"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dir": {
+ "a.py": "",
+ "b.py": "",
+ "c.py": "",
+ },
+ "folder_a": {"inner.txt": ""},
+ "folder_b": {},
+ "folder_c": {},
+ },
+ )
+
+ nested = file_tree(
+ base_rel,
+ folders_first=False,
+ max_folders=1,
+ max_files=1,
+ sort=(SORT_BY_NAME, SORT_ASC),
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ root = nested
+ comment_nodes = [item for item in root if item["type"] == "comment"]
+ assert comment_nodes
+ assert any("more folders" in node["text"] for node in comment_nodes)
+ all_nodes = _flatten_nested(root)
+ file_comment_nodes = [item for item in all_nodes if item["type"] == "comment" and "more files" in item["text"]]
+ assert file_comment_nodes, "Expected file summary comment within nested structure"
+
+
+def test_file_tree_nested_max_depth_with_sort() -> None:
+ base_rel = "tmp/tests/file_tree/nested_max_depth_sort"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "root": {
+ "branch": {
+ "leaf_a.txt": "",
+ "leaf_b.txt": "",
+ },
+ },
+ "alpha.txt": "",
+ },
+ )
+ base_ts = time.time()
+ for offset, rel_path in enumerate(
+ [
+ "root",
+ os.path.join("root", "branch"),
+ os.path.join("root", "branch", "leaf_a.txt"),
+ os.path.join("root", "branch", "leaf_b.txt"),
+ "alpha.txt",
+ ],
+ start=1,
+ ):
+ _set_entry_times(os.path.join(base_rel, rel_path), base_ts + offset)
+
+ nested = file_tree(
+ base_rel,
+ folders_first=True,
+ sort=(SORT_BY_CREATED, SORT_ASC),
+ max_depth=2,
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ root_node = next(item for item in nested if item["name"] == "root")
+ assert root_node["items"] is not None
+ branch_node = next(child for child in root_node["items"] if child["name"] == "branch")
+ assert branch_node["items"] == []
+
+
+def test_file_tree_nested_global_max_lines_prunes_depth() -> None:
+ base_rel = "tmp/tests/file_tree/nested_max_lines"
+ with _project_directory(base_rel):
+ _materialize_structure(
+ base_rel,
+ {
+ "dirA": {
+ "a1.txt": "",
+ "a2.txt": "",
+ },
+ "dirB": {
+ "b1.txt": "",
+ "b2.txt": "",
+ },
+ "root_file.txt": "",
+ },
+ )
+
+ nested = file_tree(
+ base_rel,
+ folders_first=True,
+ max_lines=4,
+ output_mode=OUTPUT_MODE_NESTED,
+ )
+
+ flattened = _flatten_nested(nested)
+ levels = [item["level"] for item in flattened]
+ assert all(level <= 2 for level in levels)
+ top_level = [item for item in flattened if item["level"] == 1]
+ assert {item["name"] for item in top_level} == {"dirA", "dirB", "root_file.txt"}
diff --git a/tests/test_file_tree_visualize.py b/tests/test_file_tree_visualize.py
new file mode 100644
index 000000000..d025e4855
--- /dev/null
+++ b/tests/test_file_tree_visualize.py
@@ -0,0 +1,680 @@
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Iterable
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+import sys
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+try:
+ import pytest # type: ignore
+except ImportError: # pragma: no cover
+ pytest = None
+
+if pytest is not None:
+ pytestmark = pytest.mark.skip(reason="Visualization utility; excluded from automated test runs.")
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(REPO_ROOT))
+
+from python.helpers.files import (
+ OUTPUT_MODE_FLAT,
+ OUTPUT_MODE_NESTED,
+ OUTPUT_MODE_STRING,
+ SORT_ASC,
+ SORT_BY_CREATED,
+ SORT_BY_MODIFIED,
+ SORT_BY_NAME,
+ SORT_DESC,
+ create_dir,
+ delete_dir,
+ file_tree,
+ get_abs_path,
+ write_file,
+)
+
+
+BASE_TEMP_ROOT = "tmp/tests/file_tree/visualize"
+
+
+@dataclass(slots=True)
+class Config:
+ label: str
+ params: Dict[str, Any]
+
+
+SetupHook = Optional[Callable[[str], None]]
+
+
+@dataclass(slots=True)
+class Scenario:
+ name: str
+ description: str
+ structure: Dict[str, Any]
+ configs: List[Config] = field(default_factory=list)
+ ignore_content: Optional[str] = None
+ setup: SetupHook = None
+
+
+def materialize_structure(base_rel: str, structure: Dict[str, Any]) -> None:
+ for entry, value in structure.items():
+ rel = os.path.join(base_rel, entry)
+ if isinstance(value, dict):
+ create_dir(rel)
+ materialize_structure(rel, value)
+ else:
+ write_file(rel, "" if value is None else str(value))
+
+
+def ensure_ignore_file(base_rel: str, content: str) -> None:
+ write_file(os.path.join(base_rel, ".treeignore"), content.strip() + "\n")
+
+
+def print_header(title: str, char: str = "=") -> None:
+ print(char * 80)
+ print(title)
+ print(char * 80)
+
+
+def print_flat(items: List[Dict[str, Any]]) -> None:
+ print("level type name text")
+ print("-" * 80)
+ for item in items:
+ level = item["level"]
+ item_type = item["type"]
+ name = item["name"]
+ text = item["text"]
+ print(f"{level:<5} {item_type:<7} {name:<20} {text}")
+
+
+def print_nested(items: List[Dict[str, Any]], root_label: str) -> None:
+ print(root_label)
+ for item in items:
+ text = item["text"]
+ print(f"{text} [{item['type']}]")
+
+
+@contextmanager
+def scenario_directory(name: str) -> Iterable[str]:
+ rel_path = os.path.join(BASE_TEMP_ROOT, name)
+ delete_dir(rel_path)
+ create_dir(rel_path)
+ try:
+ yield rel_path
+ finally:
+ delete_dir(rel_path)
+
+
+def _set_entry_times(relative_path: str, timestamp: float) -> None:
+ abs_path = get_abs_path(relative_path)
+ os.utime(abs_path, (timestamp, timestamp))
+ time.sleep(0.01)
+
+
+def _apply_timestamps(base_rel: str, paths: List[str], base_ts: Optional[float] = None) -> None:
+ if base_ts is None:
+ base_ts = time.time()
+ for offset, rel in enumerate(paths, start=1):
+ _set_entry_times(os.path.join(base_rel, rel), base_ts + offset)
+
+
+def list_scenarios(scenarios: List[Scenario]) -> None:
+ print("Available scenarios:")
+ for scenario in scenarios:
+ print(f" - {scenario.name}: {scenario.description}")
+
+
+def run_scenarios(selected: List[Scenario]) -> None:
+ create_dir(BASE_TEMP_ROOT)
+ for scenario in selected:
+ print_header(f"Scenario: {scenario.name} — {scenario.description}")
+ with scenario_directory(scenario.name) as base_rel:
+ materialize_structure(base_rel, scenario.structure)
+
+ if scenario.ignore_content:
+ ensure_ignore_file(base_rel, scenario.ignore_content)
+
+ if scenario.setup:
+ scenario.setup(base_rel)
+
+ for config in scenario.configs:
+ print_header(f"Configuration: {config.label}", "-")
+ params = {
+ "relative_path": base_rel,
+ "max_depth": 0,
+ "max_lines": 0,
+ "folders_first": True,
+ "max_folders": None,
+ "max_files": None,
+ "sort": (SORT_BY_MODIFIED, SORT_DESC),
+ **config.params,
+ }
+ output_mode = params.setdefault("output_mode", OUTPUT_MODE_STRING)
+ print("Parameters:")
+ print(f" output_mode : {output_mode}")
+ print(f" folders_first : {params['folders_first']}")
+ sort_key, sort_dir = params["sort"]
+ print(f" sort : key={sort_key}, direction={sort_dir}")
+ print(f" max_depth : {params['max_depth']}")
+ print(f" max_lines : {params['max_lines']}")
+ print(f" max_folders : {params['max_folders']}")
+ print(f" max_files : {params['max_files']}")
+ print(f" ignore : {params.get('ignore')}")
+ print()
+ result = file_tree(**params)
+
+ if output_mode == OUTPUT_MODE_STRING:
+ print(result)
+ elif output_mode == OUTPUT_MODE_FLAT:
+ print_flat(result) # type: ignore[arg-type]
+ elif output_mode == OUTPUT_MODE_NESTED:
+ print_nested(result, f"{scenario.name}/")
+ else:
+ print(f"(Unhandled output mode {output_mode!r})")
+
+ print()
+
+
+def build_scenarios() -> List[Scenario]:
+ scenarios: List[Scenario] = []
+
+ scenarios.append(
+ Scenario(
+ name="basic_breadth_first",
+ description="Default breadth-first traversal with mixed folders/files",
+ structure={
+ "alpha": {"alpha_file.txt": "alpha", "nested": {"inner.txt": "inner"}},
+ "beta": {"beta_file.txt": "beta"},
+ "zeta": {},
+ "a.txt": "A",
+ "b.txt": "B",
+ },
+ configs=[
+ Config(
+ "string • folders-first (name asc)",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ Config(
+ "string • folders-first disabled",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": False,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ Config(
+ "flat • folders-first",
+ {
+ "output_mode": OUTPUT_MODE_FLAT,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ Config(
+ "nested • folders-first",
+ {
+ "output_mode": OUTPUT_MODE_NESTED,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ ],
+ )
+ )
+
+ def setup_sorting(base_rel: str) -> None:
+ entries = [
+ "folder_alpha",
+ "folder_beta",
+ "file_first.txt",
+ "file_second.txt",
+ "file_third.txt",
+ ]
+ for index, entry in enumerate(entries, start=1):
+ abs_path = get_abs_path(os.path.join(base_rel, entry))
+ timestamp = 200_000_0000 + index
+ os.utime(abs_path, (timestamp, timestamp))
+
+ scenarios.append(
+ Scenario(
+ name="sorting_variants",
+ description="Demonstrate sorting by name and timestamp with folders/files",
+ structure={
+ "folder_alpha": {},
+ "folder_beta": {},
+ "file_first.txt": "",
+ "file_second.txt": "",
+ "file_third.txt": "",
+ },
+ configs=[
+ Config(
+ "string • sort by name asc",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ Config(
+ "string • sort by created desc",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": True,
+ "sort": (SORT_BY_CREATED, SORT_DESC),
+ },
+ ),
+ Config(
+ "flat • sort by modified asc",
+ {
+ "output_mode": OUTPUT_MODE_FLAT,
+ "folders_first": True,
+ "sort": (SORT_BY_MODIFIED, SORT_ASC),
+ },
+ ),
+ ],
+ setup=setup_sorting,
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="ignore_and_limits",
+ description="Ignore file semantics with max_folders/max_files summaries",
+ structure={
+ "src": {
+ "main.py": "print('hello')",
+ "utils.py": "pass",
+ "tmp.tmp": "",
+ "cache": {"cached.txt": "", "keep.txt": ""},
+ "modules": {"a.py": "", "b.py": "", "c.py": ""},
+ "pkg": {"alpha.py": "", "beta.py": "", "gamma.py": ""},
+ },
+ "logs": {"2024.log": "", "2025.log": ""},
+ "notes.md": "",
+ "guide.md": "",
+ "todo.md": "",
+ "build.tmp": "",
+ "archive": {},
+ "assets": {},
+ "sandbox": {},
+ "vendor": {},
+ },
+ ignore_content="\n".join(
+ ["*.tmp", "cache/", "!src/cache/keep.txt", "logs/", "!logs/2025.log"]
+ ),
+ configs=[
+ Config(
+ "string • folders-first with summaries",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": False,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 1,
+ "max_files": 2,
+ "max_lines": 12,
+ "ignore": "file:.treeignore",
+ },
+ ),
+ Config(
+ "nested • inspect truncated branches & comments",
+ {
+ "output_mode": OUTPUT_MODE_NESTED,
+ "folders_first": False,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 1,
+ "max_files": 2,
+ "max_lines": 12,
+ "ignore": "file:.treeignore",
+ },
+ ),
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="limits_exact_match",
+ description="Per-directory limits exactly met (no summary comments)",
+ structure={
+ "pkg": {
+ "a.py": "",
+ "b.py": "",
+ "dir1": {},
+ "dir2": {},
+ }
+ },
+ configs=[
+ Config(
+ "string • exact matches (no summaries)",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 2,
+ "max_files": 2,
+ },
+ ),
+ Config(
+ "flat • exact matches (no summaries)",
+ {
+ "output_mode": OUTPUT_MODE_FLAT,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 2,
+ "max_files": 2,
+ },
+ ),
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="single_overflow",
+ description="Single overflow entries promoted instead of summary comment",
+ structure={
+ "pkg": {
+ "dir_a": {},
+ "dir_b": {},
+ "file_a.txt": "",
+ }
+ },
+ configs=[
+ Config(
+ "string • single folder overflow",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 1,
+ },
+ ),
+ Config(
+ "string • single file overflow",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": False,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_files": 1,
+ },
+ ),
+ Config(
+ "flat • folders-first",
+ {
+ "output_mode": OUTPUT_MODE_FLAT,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 1,
+ },
+ ),
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="global_max_lines",
+ description="Global max_lines finishing current depth before truncation",
+ structure={
+ "layer1_a": {
+ "layer2_a": {
+ "layer3_a": {
+ "layer4_a": {"layer5_a.txt": ""},
+ }
+ }
+ },
+ "layer1_b": {
+ "layer2_b": {
+ "layer3_b": {
+ "layer4_b": {"layer5_b.txt": ""},
+ }
+ }
+ },
+ "root_file.txt": "",
+ },
+ configs=[
+ Config(
+ "string • max_lines=6",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "max_lines": 6,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ Config(
+ "nested • max_lines=6",
+ {
+ "output_mode": OUTPUT_MODE_NESTED,
+ "max_lines": 6,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ },
+ ),
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="flat_files_first_limits",
+ description="Flat output with files-first ordering and per-directory summaries",
+ structure={
+ "dir1": {},
+ "dir2": {},
+ "dir3": {},
+ "dir4": {},
+ "a.txt": "",
+ "b.txt": "",
+ "c.txt": "",
+ },
+ configs=[
+ Config(
+ "flat • files-first with limits",
+ {
+ "output_mode": OUTPUT_MODE_FLAT,
+ "folders_first": False,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 1,
+ "max_files": 1,
+ },
+ )
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="flat_sort_created_max_lines",
+ description="Flat output sorted by created time with global max_lines",
+ structure={
+ "dirA": {"inner.txt": ""},
+ "file1.txt": "",
+ "file2.txt": "",
+ "file3.txt": "",
+ },
+ setup=lambda base_rel: _apply_timestamps(
+ base_rel,
+ [
+ "dirA",
+ os.path.join("dirA", "inner.txt"),
+ "file1.txt",
+ "file2.txt",
+ "file3.txt",
+ ],
+ base_ts=2_000_001_000,
+ ),
+ configs=[
+ Config(
+ "flat • sort by created desc, max_lines=4",
+ {
+ "output_mode": OUTPUT_MODE_FLAT,
+ "folders_first": True,
+ "sort": (SORT_BY_CREATED, SORT_DESC),
+ "max_lines": 4,
+ },
+ )
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="nested_files_first_limits",
+ description="Nested output with files-first ordering and per-directory summaries",
+ structure={
+ "dir": {"a.py": "", "b.py": "", "c.py": ""},
+ "folder_a": {"inner.txt": ""},
+ "folder_b": {},
+ "folder_c": {},
+ },
+ configs=[
+ Config(
+ "nested • files-first with limits",
+ {
+ "output_mode": OUTPUT_MODE_NESTED,
+ "folders_first": False,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 1,
+ "max_files": 1,
+ },
+ )
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="nested_max_depth_sort",
+ description="Nested output with created-time ordering and depth pruning",
+ structure={
+ "root": {
+ "branch": {
+ "leaf_a.txt": "",
+ "leaf_b.txt": "",
+ }
+ },
+ "alpha.txt": "",
+ },
+ setup=lambda base_rel: _apply_timestamps(
+ base_rel,
+ [
+ "root",
+ os.path.join("root", "branch"),
+ os.path.join("root", "branch", "leaf_a.txt"),
+ os.path.join("root", "branch", "leaf_b.txt"),
+ "alpha.txt",
+ ],
+ base_ts=2_000_010_000,
+ ),
+ configs=[
+ Config(
+ "nested • sort by created asc, max_depth=2",
+ {
+ "output_mode": OUTPUT_MODE_NESTED,
+ "folders_first": True,
+ "sort": (SORT_BY_CREATED, SORT_ASC),
+ "max_depth": 2,
+ },
+ )
+ ],
+ )
+ )
+
+ scenarios.append(
+ Scenario(
+ name="string_additional_limits",
+ description="String output exercising files-first+max_lines and zero-limit semantics",
+ structure={
+ "dir": {"inner_a.txt": "", "inner_b.txt": ""},
+ "alpha.txt": "",
+ "beta.txt": "",
+ "gamma.txt": "",
+ },
+ setup=lambda base_rel: _apply_timestamps(
+ base_rel,
+ [
+ "dir",
+ os.path.join("dir", "inner_a.txt"),
+ os.path.join("dir", "inner_b.txt"),
+ "alpha.txt",
+ "beta.txt",
+ "gamma.txt",
+ ],
+ base_ts=2_000_020_000,
+ ),
+ configs=[
+ Config(
+ "string • files-first, sort=modified desc, max_lines=4",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": False,
+ "sort": (SORT_BY_MODIFIED, SORT_DESC),
+ "max_lines": 4,
+ },
+ ),
+ Config(
+ "string • zero file limit acts unlimited",
+ {
+ "output_mode": OUTPUT_MODE_STRING,
+ "folders_first": True,
+ "sort": (SORT_BY_NAME, SORT_ASC),
+ "max_folders": 2,
+ "max_files": 0,
+ },
+ ),
+ ],
+ )
+ )
+
+ return scenarios
+
+
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(
+ description="Visualize file_tree() outputs across configurations."
+ )
+ parser.add_argument(
+ "--scenario",
+ action="append",
+ dest="scenarios",
+ help="Scenario name to run (repeat for multiple). Default: run all.",
+ )
+ parser.add_argument(
+ "--list",
+ action="store_true",
+ help="List available scenarios and exit.",
+ )
+ return parser.parse_args()
+
+
+def main() -> None:
+ scenarios = build_scenarios()
+ args = parse_args()
+
+ if args.list:
+ list_scenarios(scenarios)
+ return
+
+ if args.scenarios:
+ name_map = {scenario.name: scenario for scenario in scenarios}
+ unknown = [name for name in args.scenarios if name not in name_map]
+ if unknown:
+ raise SystemExit(f"Unknown scenario(s): {', '.join(unknown)}")
+ selected = [name_map[name] for name in args.scenarios]
+ else:
+ selected = scenarios
+
+ run_scenarios(selected)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_file_tree_visualize.short.png b/tests/test_file_tree_visualize.short.png
new file mode 100644
index 000000000..4cb0e1f01
Binary files /dev/null and b/tests/test_file_tree_visualize.short.png differ
diff --git a/tests/test_file_tree_visualize.short.txt b/tests/test_file_tree_visualize.short.txt
new file mode 100644
index 000000000..486770c41
--- /dev/null
+++ b/tests/test_file_tree_visualize.short.txt
@@ -0,0 +1,341 @@
+================================================================================
+Scenario: basic_breadth_first — Default breadth-first traversal with mixed folders/files
+================================================================================
+--------------------------------------------------------------------------------
+Configuration: string • folders-first (name asc)
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+tmp/tests/file_tree/visualize/basic_breadth_first/
+├── alpha/
+│ ├── nested/
+│ │ └── inner.txt
+│ └── alpha_file.txt
+├── beta/
+│ └── beta_file.txt
+├── zeta/
+├── a.txt
+└── b.txt
+--------------------------------------------------------------------------------
+Configuration: string • folders-first disabled
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : False
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+tmp/tests/file_tree/visualize/basic_breadth_first/
+├── a.txt
+├── b.txt
+├── alpha/
+│ ├── alpha_file.txt
+│ └── nested/
+│ └── inner.txt
+├── beta/
+│ └── beta_file.txt
+└── zeta/
+--------------------------------------------------------------------------------
+Configuration: flat • folders-first
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : flat
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+level type name text
+--------------------------------------------------------------------------------
+1 folder alpha ├── alpha/
+2 folder nested │ ├── nested/
+3 file inner.txt │ │ └── inner.txt
+2 file alpha_file.txt │ └── alpha_file.txt
+1 folder beta ├── beta/
+2 file beta_file.txt │ └── beta_file.txt
+1 folder zeta ├── zeta/
+1 file a.txt ├── a.txt
+1 file b.txt └── b.txt
+--------------------------------------------------------------------------------
+Configuration: nested • folders-first
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : nested
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+basic_breadth_first/
+├── alpha/ [folder]
+├── beta/ [folder]
+├── zeta/ [folder]
+├── a.txt [file]
+└── b.txt [file]
+
+================================================================================
+Scenario: sorting_variants — Demonstrate sorting by name and timestamp with folders/files
+================================================================================
+--------------------------------------------------------------------------------
+Configuration: string • sort by name asc
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+tmp/tests/file_tree/visualize/sorting_variants/
+├── folder_alpha/
+├── folder_beta/
+├── file_first.txt
+├── file_second.txt
+└── file_third.txt
+--------------------------------------------------------------------------------
+Configuration: string • sort by created desc
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : True
+ sort : key=created, direction=desc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+tmp/tests/file_tree/visualize/sorting_variants/
+├── folder_alpha/
+├── folder_beta/
+├── file_third.txt
+├── file_first.txt
+└── file_second.txt
+--------------------------------------------------------------------------------
+Configuration: flat • sort by modified asc
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : flat
+ folders_first : True
+ sort : key=modified, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : None
+ ignore : None
+
+level type name text
+--------------------------------------------------------------------------------
+1 folder folder_alpha ├── folder_alpha/
+1 folder folder_beta ├── folder_beta/
+1 file file_first.txt ├── file_first.txt
+1 file file_second.txt ├── file_second.txt
+1 file file_third.txt └── file_third.txt
+
+================================================================================
+Scenario: ignore_and_limits — Ignore file semantics with max_folders/max_files summaries
+================================================================================
+--------------------------------------------------------------------------------
+Configuration: string • folders-first with summaries
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : False
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 12
+ max_folders : 1
+ max_files : 2
+ ignore : file:.treeignore
+
+tmp/tests/file_tree/visualize/ignore_and_limits/
+├── .treeignore
+├── guide.md
+├── # 2 more files
+├── archive/
+└── # 5 more folders
+--------------------------------------------------------------------------------
+Configuration: nested • inspect truncated branches & comments
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : nested
+ folders_first : False
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 12
+ max_folders : 1
+ max_files : 2
+ ignore : file:.treeignore
+
+ignore_and_limits/
+├── .treeignore [file]
+├── guide.md [file]
+├── # 2 more files [comment]
+├── archive/ [folder]
+└── # 5 more folders [comment]
+
+================================================================================
+Scenario: limits_exact_match — Per-directory limits exactly met (no summary comments)
+================================================================================
+--------------------------------------------------------------------------------
+Configuration: string • exact matches (no summaries)
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : 2
+ max_files : 2
+ ignore : None
+
+tmp/tests/file_tree/visualize/limits_exact_match/
+└── pkg/
+ ├── dir1/
+ ├── dir2/
+ ├── a.py
+ └── b.py
+--------------------------------------------------------------------------------
+Configuration: flat • exact matches (no summaries)
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : flat
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : 2
+ max_files : 2
+ ignore : None
+
+level type name text
+--------------------------------------------------------------------------------
+1 folder pkg └── pkg/
+2 folder dir1 ├── dir1/
+2 folder dir2 ├── dir2/
+2 file a.py ├── a.py
+2 file b.py └── b.py
+
+================================================================================
+Scenario: single_overflow — Single overflow entries promoted instead of summary comment
+================================================================================
+--------------------------------------------------------------------------------
+Configuration: string • single folder overflow
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : 1
+ max_files : None
+ ignore : None
+
+tmp/tests/file_tree/visualize/single_overflow/
+└── pkg/
+ ├── dir_a/
+ ├── dir_b/
+ └── file_a.txt
+--------------------------------------------------------------------------------
+Configuration: string • single file overflow
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : False
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : None
+ max_files : 1
+ ignore : None
+
+tmp/tests/file_tree/visualize/single_overflow/
+└── pkg/
+ ├── file_a.txt
+ ├── dir_a/
+ └── dir_b/
+--------------------------------------------------------------------------------
+Configuration: flat • folders-first
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : flat
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 0
+ max_folders : 1
+ max_files : None
+ ignore : None
+
+level type name text
+--------------------------------------------------------------------------------
+1 folder pkg └── pkg/
+2 folder dir_a ├── dir_a/
+2 folder dir_b ├── dir_b/
+2 file file_a.txt └── file_a.txt
+
+================================================================================
+Scenario: global_max_lines — Global max_lines finishing current depth before truncation
+================================================================================
+--------------------------------------------------------------------------------
+Configuration: string • max_lines=6
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : string
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 6
+ max_folders : None
+ max_files : None
+ ignore : None
+
+tmp/tests/file_tree/visualize/global_max_lines/
+├── layer1_a/
+│ └── layer2_a/
+│ └── layer3_a/
+├── layer1_b/
+│ └── layer2_b/
+│ └── layer3_b/
+└── root_file.txt
+--------------------------------------------------------------------------------
+Configuration: nested • max_lines=6
+--------------------------------------------------------------------------------
+Parameters:
+ output_mode : nested
+ folders_first : True
+ sort : key=name, direction=asc
+ max_depth : 0
+ max_lines : 6
+ max_folders : None
+ max_files : None
+ ignore : None
+
+global_max_lines/
+├── layer1_a/ [folder]
+├── layer1_b/ [folder]
+└── root_file.txt [file]
+