tree-generator

Tree Generator

Generate clean, annotated directory-tree documentation files into docs/trees/.

Hard Rules

• Depths are fixed: tree-monorepo.md = depth 3; per-component files = depth 4.
• "Major component" is decided by the Component Rule in Step 1 — never by guessing.
• Every written file starts with the auto-generated header template from Step 4.
• Trees are always written in indented tree form; if the find fallback is used, reformat its flat paths into a tree first — never paste a flat path list into a doc.
• Completion is claimed only after the Done gate passes.

Phase 0 — Load Project Context

Read if present, skip silently if absent: CLAUDE.md or AGENTS.md; docs/architecture/*.md that describe layout. Use it to: learn the documented top-level structure and reuse its directory descriptions as annotations.

Process

Step 1 — Detect components

Component Rule — a directory is a major component if EITHER:

1. It contains its own root marker — package.json, go.mod, Cargo.toml, or pyproject.toml — and is not the repo root; OR
2. It is a top-level directory named src, backend, frontend, cmd, or internal.

Detection command:

find . -maxdepth 3 -not -path '*/node_modules/*' -not -path '*/.git/*' \
  \( -name go.mod -o -name package.json -o -name Cargo.toml -o -name pyproject.toml \)

Branches (explicit — no other modes exist):

• 2+ components matched → monorepo mode: write tree-monorepo.md PLUS one tree-{component}.md per component.
• 0–1 components matched (markers only at repo root, or nothing) → single-component mode: write ONLY tree-monorepo.md. This is also the default when detection is ambiguous.

Step 2 — Generate trees (two depth variants)

Overview — always, depth 3, from repo root:

tree -I 'node_modules|.git|__pycache__|vendor|dist|build|.next|.cache|*.pyc|.DS_Store' \
     --dirsfirst -L 3

Per component — monorepo mode only, depth 4:

tree -I 'node_modules|.git|__pycache__|vendor|dist|build|.next|.cache|*.pyc|.DS_Store' \
     --dirsfirst -L 4 <component-dir>