If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bootandy/dust shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 21+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bootandy/dust repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bootandy/dust.

What it runs against: a local clone of bootandy/dust — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bootandy/dust | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 105 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bootandy/dust. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bootandy/dust.git
#   cd dust
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bootandy/dust and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bootandy/dust(\\.git)?\\b" \\
  && ok "origin remote is bootandy/dust" \\
  || miss "origin remote is not bootandy/dust (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 105 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~75d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bootandy/dust"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Dust is a Rust-based reimplementation of the Unix du command that visualizes disk usage in a hierarchical, terminal-based display with ASCII bars showing percentage allocation. Unlike traditional du, it intelligently recurses down directory trees and displays the largest subdirectories proportionally, with color-coded bars that visually represent how much of a parent directory's space is consumed by each child, making disk usage patterns immediately obvious without needing to pipe through sort or head. Single-binary Rust project with clean module separation: src/cli.rs handles argument parsing via clap derive macros, src/dir_walker.rs implements parallel recursive directory traversal using rayon, src/node.rs models the directory tree structure, src/display.rs and src/display_node.rs handle terminal rendering with ANSI colors, src/filter.rs implements filtering logic, and src/config.rs loads user configuration from config/config.toml. The build.rs generates shell completions at compile time using clap_complete.

System administrators and developers who need to quickly identify large disk space consumers on their systems, particularly those working in monorepo environments (like Rust projects with target/ directories) or anyone frustrated with the unintuitive output of traditional du commands. Users value the minimal cognitive overhead—no flags needed, just run dust and get instant visual insight.

Production-ready and actively maintained. The project has a complete CI/CD pipeline (.github/workflows/CICD.yml), comprehensive shell/PowerShell/Elvish completion scripts, man-page documentation (man-page/dust.1), and official packaging across Homebrew, Snap, Conda, Scoop, and deb distributions. Version 1.2.4 with Apache 2.0 license indicates stability, though the maintainer (bootandy) drives primary development.

Low-to-moderate risk: the dependency footprint is moderate (~14 direct dependencies including clap, rayon, sysinfo) with well-maintained crates, but the project is primarily single-maintainer driven. No breaking changes are evident from the version history (still at 1.x), and the codebase is small enough (~136KB Rust) to audit. Primary risk is maintainer availability, though the tool's narrow scope (disk usage visualization) limits complexity.

The repo appears stable with no indication of active ongoing feature work in the provided structure. Version 1.2.4 is the current release. The presence of recent CI/CD configuration (CICD.yml) and comprehensive cross-platform support (Windows PowerShell, Linux bash, fish, Elvish shells) suggests maintenance focus is on stability and distribution rather than new features.

git clone https://github.com/bootandy/dust.git
cd dust
cargo build --release
./target/release/dust .

Alternatively, cargo install du-dust for immediate system-wide installation.

Daily commands: Development: cargo build (debug binary in target/debug/dust). Release build: cargo build --release with LTO and codegen-unit optimization enabled (see Cargo.toml [profile.release]). Run: ./target/release/dust [path] or just dust if installed. Tests: cargo test (integration tests in tests/tests.rs use assert_cmd and tempfile).

• src/main.rs: Entry point orchestrating CLI parsing, config loading, directory walking, filtering, and display rendering
• src/dir_walker.rs: Core parallel directory traversal using rayon; bottleneck for large directory trees and main I/O performance component
• src/display.rs: Terminal rendering engine using ANSI escape codes to draw proportional bars and handle responsive layout to terminal height
• src/node.rs: Tree data structure representing directories/files with size aggregation and parent-child relationships
• src/cli.rs: Clap-based argument parsing; defines all command-line flags, their defaults, and help text
• src/filter.rs: Filtering logic to hide/include files based on regex patterns, size thresholds, or node aggregation strategy
• src/config.rs: TOML configuration file parsing (config/config.toml) for persistent user preferences
• build.rs: Build script generating shell completions for bash, fish, PowerShell, Elvish at compile time using clap_complete
• tests/tests.rs: Integration tests validating end-to-end behavior against test fixtures in tests/test_dir* directories

CLI changes: edit src/cli.rs (clap derive structs). Display/formatting: src/display.rs (bar rendering) and src/display_node.rs (per-node rendering logic). Filter logic: src/filter.rs and src/filter_type.rs. Directory scanning: src/dir_walker.rs (core traversal, uses rayon for parallelism). New config options: src/config.rs + config/config.toml. Platform-specific behavior: src/platform.rs (Windows filesize handling via winapi-util). Run cargo build && cargo test after changes; integration tests in tests/tests.rs validate against test_dir/ and test_dir2/ fixtures.

Windows filesize behavior: src/platform.rs uses conditional compilation and winapi-util for Windows-specific file size retrieval; test on Windows if modifying. Rayon thread pool: dir_walker.rs uses rayon::scope for parallel traversal—ensure proper Sync/Send trait bounds and no race conditions when adding new fields to Node struct. ANSI terminal assumptions: display.rs relies on terminal_size crate and assumes ANSI escape codes are supported; some edge-case terminals (dumb terminals, redirected output) may not render correctly. Config path resolution: config.rs expects config/config.toml in standard config directories (OS-specific)—test config loading on macOS, Linux, and Windows separately. No built-in caching: each run rescans the filesystem; very large directory trees (100k+ files) may stall noticeably.

• Parallel tree traversal with Rayon work-stealing — src/dir_walker.rs uses rayon::scope to parallelize recursive directory scanning across CPU cores; understanding work-stealing schedulers and Sync/Send trait bounds is essential to avoid bottlenecks in large filesystems
• ANSI escape codes for terminal styling — src/display.rs and src/display_node.rs use nu-ansi-term to emit colored bars and styled text; understanding ANSI SGR (Select Graphic Rendition) codes is required to extend terminal output formatting
• Tree aggregation algorithms (bottom-up size calculation) — src/node.rs accumulates file sizes from leaves to root; the proportional bar display in src/display.rs depends on correct size aggregation—modifying this logic requires careful handling of aggregation semantics
• Terminal responsive layout (terminal_size crate) — src/display.rs queries terminal dimensions via terminal_size and constrains output to terminal height minus 1; understanding how terminals report size (TIOCGWINSZ ioctl on Unix, GetConsoleScreenBufferInfo on Windows) informs display logic
• Clap derive macro CLI parsing — src/cli.rs uses clap 4's derive feature for zero-boilerplate argument parsing; understanding clap's builder pattern and subcommand composition is needed to add new flags or commands
• TOML configuration file deserialization via serde — src/config.rs loads config/config.toml into Rust structs using serde; understanding derive macros and serde's feature flags (e.g., #[serde(default)]) is needed to extend config options
• Platform-conditional compilation (cfg attributes) — src/platform.rs and Cargo.toml use #[cfg(windows)] and target-specific dependencies (winapi-util); maintaining cross-platform code requires testing platform-specific branches and understanding Rust's conditional compilation model

• sharkdp/fd — Another Rust CLI tool with similar UX philosophy (intuitive defaults, fast parallel scanning); shares rayon + clap ecosystem and provides patterns for progress reporting
• ncdu-dev/ncdu — The original ncdu (disk usage analyzer) in C; dust is spiritual successor with Rust performance—studying ncdu's design decisions on tree traversal and rendering informs maintenance
• XAMPPRocky/tokei — Rust CLI tool using similar patterns (rayon parallelism, clap derive macros, cargo-binstall); demonstrates cross-platform packaging best practices dust follows
• BurntSushi/ripgrep — Canonical Rust CLI project with fast parallel searching, ANSI output, and excellent argument parsing; provides UX/performance patterns applicable to large directory scanning
• starship/starship — High-profile Rust CLI with multi-shell completion generation (bash, fish, zsh, PowerShell, Elvish) via clap_complete; dust's build.rs approach mirrors this pattern

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for symlink handling across platforms

The repo has tests/tests_symlinks.rs but it's likely incomplete given the complexity of symlink behavior on Windows vs Unix. With dust being a disk usage tool, proper symlink handling (follow vs skip) is critical. Currently missing comprehensive tests for: symlink loops, broken symlinks, and cross-platform behavior. This would catch regressions and improve Windows compatibility.

• [ ] Review existing tests/tests_symlinks.rs to identify coverage gaps
• [ ] Add test cases in tests/tests_symlinks.rs for circular symlink detection
• [ ] Add test cases for broken/dangling symlinks (should not crash)
• [ ] Add Windows-specific symlink tests using #[cfg(windows)] attributes
• [ ] Run existing test suite to ensure no regressions

Add configuration file schema documentation and validation tests

The repo has config/config.toml and src/config.rs but no schema documentation or validation tests. Users cannot easily understand what config options are valid, what types they accept, or what happens with invalid configs. This would improve UX significantly for advanced users.

• [ ] Create a comprehensive config schema document (e.g., docs/CONFIG.md) with all valid keys and types
• [ ] Add test cases in tests/test_flags.rs or new tests/test_config.rs for valid/invalid config files
• [ ] Test edge cases: missing required fields, type mismatches, unknown keys
• [ ] Add tests for config file precedence (user config vs defaults)
• [ ] Test the config loading logic from src/config.rs against malformed toml files

Add regression tests for Unicode and special filename handling

The repo has test directories for Unicode (tests/test_dir_unicode/) but lacks comprehensive integration tests. With stfu8 dependency and unicode-width in use, there's risk of display bugs with special characters. Current tests/tests.rs likely doesn't fully exercise edge cases with emoji, RTL text, or control characters.

• [ ] Review tests/tests.rs to see current Unicode test coverage
• [ ] Add integration tests for filenames with emoji, CJK characters, and zero-width characters
• [ ] Add tests for very long Unicode filenames (combine with tests/test_dir with long_dir_name_...)
• [ ] Test correct column alignment in output when mixed ASCII/Unicode is present
• [ ] Add tests for RTL text filenames to ensure display doesn't break formatting

• Add unit tests for src/filter.rs filter matching logic—currently only covered by integration tests; add test module validating regex patterns, size thresholds, and aggregation behavior against mock Node trees.
• Implement a --sort-by flag in src/cli.rs to let users sort output by size, name, or modification time; add corresponding sort logic in src/display.rs and integration tests in tests/tests.rs.
• Add a --follow-symlinks flag (currently not present in cli.rs) to control whether symbolic links are followed during dir_walker.rs traversal; requires conditional logic in dir_walker.rs and tests with symlink fixtures in tests/test_dir*.

The 'dust' project demonstrates reasonable security practices with pinned dependencies, release optimizations (LTO, strip), and proper CI/CD integration. However, a critical configuration error exists with an invalid Rust edition that prevents proper compilation and verification. No obvious injection vulnerabilities, hardcoded secrets, or exposed credentials were detected. Key recommendations include: (1) fix the Cargo.toml edition field immediately, (2) implement cargo-audit and cargo-deny in the CI/CD pipeline, (3) review directory traversal and symlink handling logic, (4) add configuration validation, and (5) enhance pre-commit hooks with security checks.

• High · Invalid Rust Edition in Cargo.toml — Cargo.toml (line: edition = "2024"). The Cargo.toml specifies edition = "2024", which is not a valid Rust edition. Valid editions are 2015, 2018, and 2021. This will cause build failures and may mask actual vulnerabilities. This appears to be a configuration error that could prevent the project from being built and verified. Fix: Change edition to a valid value (2021 is recommended for modern Rust projects). Use 'edition = "2021"' in Cargo.toml.
• Medium · Dependency on Unverified External Crates — Cargo.toml (dependencies section). The project relies on multiple external crates including 'config-file' for configuration parsing. While the dependency versions are pinned, there is no evidence of supply chain security measures such as dependency auditing, SBOM generation, or vendor verification. Fix: Implement 'cargo audit' in CI/CD pipeline to detect known vulnerabilities. Consider using 'cargo-deny' for additional supply chain security checks. Add dependency verification to the CICD.yml workflow.
• Low · Potential Path Traversal Risk in Directory Walking — src/dir_walker.rs. The src/dir_walker.rs module walks directory trees. Without reviewing the actual code, there is a potential risk of path traversal vulnerabilities if symbolic links are not properly handled or if user input is not sanitized when constructing file paths. Fix: Review directory walking logic to ensure: (1) Symbolic links are handled safely and cyclical links cannot cause DoS, (2) Canonicalization is used appropriately, (3) Path operations use safe Rust idioms. Add tests for symlink edge cases (note: tests_symlinks.rs exists but should be reviewed).
• Low · Config File Processing Without Validation — src/config.rs. The project uses 'config-file' crate to parse configuration from config/config.toml and potentially user-supplied configs. Without visible validation logic, there could be risks from malformed or malicious configuration files. Fix: Implement strict schema validation for configuration files. Define expected keys, types, and ranges. Reject unknown configuration keys. Log configuration parsing errors securely without exposing sensitive information.
• Low · Missing Security Headers in Pre-commit Configuration — .pre-commit-config.yaml. The .pre-commit-config.yaml exists but typical security hooks (like secret scanning, dependency checking) are not visible in the file structure description. Fix: Add pre-commit hooks for: detecting secrets/credentials, checking for vulnerable dependencies, and enforcing code quality. Consider adding hooks like 'truffleHog' or 'detect-secrets'.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.