Skip to content

Agent Zero AI framework

File Tree: remove excessive testing code and the specifiction documents after finished impl

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