| 1 | # file_tree.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the `file_tree.py` helper module. |
| 6 | - This module renders bounded file-tree summaries for prompts and UI surfaces. |
| 7 | - Keep this file-level DOX profile synchronized with `file_tree.py` because this directory is intentionally flat. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - `file_tree.py` owns the runtime implementation. |
| 12 | - `file_tree.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 13 | - Classes: |
| 14 | - `_TreeEntry` (no explicit base class) |
| 15 | - `as_dict(self) -> dict[str, Any]` |
| 16 | - Top-level functions: |
| 17 | - `_from_timestamp(timestamp: float) -> datetime` |
| 18 | - `file_tree(relative_path: str, max_depth: int=..., max_lines: int=..., folders_first: bool=..., max_folders: int=..., max_files: int=..., sort: tuple[Literal['name', 'created', 'modified'], Literal['asc', 'desc']]=..., ignore: str | None=..., output_mode: Literal['string', 'flat', 'nested']=...) -> str | list[dict]`: Render a directory tree relative to the repository base path. |
| 19 | - `_normalize_relative_path(path: str) -> str` |
| 20 | - `_directory_has_visible_entries(directory: str, root_abs_path: str, ignore_spec: PathSpec, cache: dict[str, bool], max_depth_remaining: int) -> bool` |
| 21 | - `_create_summary_comment(parent: _TreeEntry, noun: str, count: int) -> _TreeEntry` |
| 22 | - `_create_global_limit_comment(parent: _TreeEntry, hidden_children: Sequence[_TreeEntry]) -> _TreeEntry` |
| 23 | - `_create_folder_unprocessed_comment(folder_node: _TreeEntry, folder_path: str, abs_root: str, ignore_spec: Optional[PathSpec]) -> Optional[_TreeEntry]` |
| 24 | - `_prune_to_visible(node: _TreeEntry, visible_ids: set[int]) -> None` |
| 25 | - `_mark_last_flags(node: _TreeEntry) -> None` |
| 26 | - `_refresh_render_metadata(node: _TreeEntry) -> None` |
| 27 | - `_resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optional[PathSpec]` |
| 28 | - `_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]]` |
| 29 | - `_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]` |
| 30 | - `_format_line(node: _TreeEntry) -> str` |
| 31 | - `_build_tree_items_flat(items: Sequence[_TreeEntry]) -> list[dict]` |
| 32 | - `_to_nested_structure(items: Sequence[_TreeEntry]) -> list[dict]` |
| 33 | - `_iter_depth_first(items: Sequence[_TreeEntry]) -> Iterable[_TreeEntry]` |
| 34 | - Notable constants/configuration names: `SORT_BY_NAME`, `SORT_BY_CREATED`, `SORT_BY_MODIFIED`, `SORT_ASC`, `SORT_DESC`, `OUTPUT_MODE_STRING`, `OUTPUT_MODE_FLAT`, `OUTPUT_MODE_NESTED`. |
| 35 | |
| 36 | ## Runtime Contracts |
| 37 | |
| 38 | - Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together. |
| 39 | - Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change. |
| 40 | - Observed side-effect areas: filesystem reads, subprocess/runtime control, WebSocket state. |
| 41 | - Imported dependency areas include: `__future__`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathspec`, `typing`. |
| 42 | |
| 43 | ## Key Concepts |
| 44 | |
| 45 | - Important called helpers/classes observed in the source: `dataclass`, `datetime.fromtimestamp`, `files_helper.get_abs_path`, `files_helper.get_abs_path_dockerized`, `_resolve_ignore_patterns`, `os.stat`, `_TreeEntry`, `deque`, `queue.clear`, `_mark_last_flags`, `_refresh_render_metadata`, `path.replace`, `normalized.startswith`, `join`, `_create_global_limit_comment`, `ignore.startswith`, `PathSpec.from_lines`, `segments.reverse`, `os.path.exists`, `FileNotFoundError`. |
| 46 | - Keep request/response, tool, or helper semantics documented here at the same time as source changes. |
| 47 | |
| 48 | ## Work Guidance |
| 49 | |
| 50 | - Preserve public helper APIs used by core code and plugins unless every caller is updated. |
| 51 | - Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded. |
| 52 | - Prefer adding cohesive helper functions here only when behavior is reused across modules. |
| 53 | |
| 54 | ## Verification |
| 55 | |
| 56 | - Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers. |
| 57 | - Related tests observed by source search: |
| 58 | - `tests/test_file_tree_visualize.py` |
| 59 | - `tests/test_skills_runtime.py` |
| 60 | |
| 61 | ## Child DOX Index |
| 62 | |
| 63 | No child DOX files. |