Project Structure

Repository

I developed Project Structure to solve the common need for clear, visual project documentation. This high-performance CLI tool generates ASCII directory trees while respecting .gitignore rules, providing a clean overview of even the most complex codebases. By leveraging Rust's speed and powerful library ecosystem, I created a utility that is both highly customizable and significantly faster than traditional shell-based alternatives.

Modular CLI Architecture

The tool is built with a highly modular architecture, separating the concerns of directory walking, tree building, and output rendering. I used the clap crate to implement a robust command-line interface with support for diverse flags—including hidden file visibility, depth limits, and custom sorting options. This design allows for easy extension, such as adding new output formats or filtering logic, without modifying the core recursive walker.

1#[derive(Parser, Clone)]
2#[command(name = "project-structure")]
3pub struct Cli {
4    /// Root path of the project to visualize
5    path: Option<PathBuf>,
6
7    /// Include hidden files and directories (dotfiles)
8    #[arg(long)]
9    pub include_hidden: bool,
10
11    /// Filter Depth for the generated tree
12    #[arg(long)]
13    pub depth: Option<usize>,
14
15    /// Output results to a Markdown file instead of stdout
16    #[arg(short, long, num_args(0..=1), require_equals(true))]
17    pub output: Option<Option<PathBuf>>,
18}

Git-Aware Directory Walking

To ensure the generated trees are free of "bloat" like target/ or node_modules/, the tool implements a git-aware directory walker. It parses .gitignore files in the root directory and applies these patterns in real-time as it traverses the file system. This logic is decoupled from the rendering stage, ensuring that the internal representation of the directory tree is accurate and concise before any ASCII characters are generated.

1fn main() -> Result<()> {
2    let cli = Cli::parse();
3    let config = Config::from(cli.clone());
4
5    // Step 1: Walk the directory structure
6    let mut nodes = walker::walk(&config)?;
7    config.sort_nodes(&mut nodes);
8
9    // Step 2: Build the internal tree representation
10    let tree = tree::build(&nodes, &config);
11
12    // Step 3: Render to ASCII or Markdown
13    let output = render::ascii(&tree, &config.filter);
14
15    // Handle file output if requested
16    if let Some(path) = &cli.output {
17        let markdown = format!("# Project Structure\n\n```\n{}\n```", output);
18        fs::write(path, markdown)?;
19    } else {
20        println!("{}", output);
21    }
22    Ok(())
23}

Custom Rendering Engine

The ASCII rendering engine was custom-built to support different tree styles and symbols. It uses a recursive approach to calculate the necessary vertical bars and branch connectors, ensuring a clean visual hierarchy. By parameterizing the renderer, I made it easy to switch between standard ASCII and modern UTF-8 symbols, or even generate the structure as a formatted Markdown code block, which is ideal for inclusion in README.md files.

High-Performance Execution

By choosing Rust, the tool achieves exceptional execution speed. Even when processing large repositories with tens of thousands of files, Project Structure can generate and render the tree in under 50ms. The project taught me the importance of efficient file system access and the power of building small, focused utilities that do one thing exceptionally well.