Agent Zero AI framework
File Tree: Main implementation of helper + tests
Rafael Uzarowskic2b772875eda
diff --git a/python/helpers/files.py b/python/helpers/files.pyindex 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, timezonefrom fnmatch import fnmatchimport json-from ntpath import isabsimport os-import sysimport reimport base64import shutilimport tempfile-from typing import Any+from typing import Any, Callable, Iterable, Literal, Optional, Sequence, Type, castimport zipfile-import importlib-import importlib.util-import inspectimport globimport 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 = VariablesPluginclasses = 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 permissionsshutil.rmtree(abs_path, ignore_errors=True)- except:+ except Exception:# suppress all errors - we're ensuring no errors propagatepass@@ -530,3 +537,557 @@ def read_text_files_in_dir(except Exception:continuereturn 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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: PASSdiff --git a/specs/001-file-tree-utility/quickstart.md b/specs/001-file-tree-utility/quickstart.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.txtnew file mode 100644index 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.txtdiff --git a/tests/fixtures/file_tree/string_ignore_limits.txt b/tests/fixtures/file_tree/string_ignore_limits.txtnew file mode 100644index 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.pydiff --git a/tests/test_file_tree_ignore_and_limits.py b/tests/test_file_tree_ignore_and_limits.pynew file mode 100644index 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.0diff --git a/tests/test_file_tree_invalid.py b/tests/test_file_tree_invalid.pynew file mode 100644index 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.pynew file mode 100644index 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 resultdiff --git a/tests/test_file_tree_structured.py b/tests/test_file_tree_structured.pynew file mode 100644index 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.pynew file mode 100644index 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.pngnew file mode 100644index 000000000..4cb0e1f01Binary files /dev/null and b/tests/test_file_tree_visualize.short.png differdiff --git a/tests/test_file_tree_visualize.short.txt b/tests/test_file_tree_visualize.short.txtnew file mode 100644index 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]+