coding_tools/cli/
ct_tree.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 Jonathan Shook
3
4//! The `ct-tree` command grammar (see [`crate::cli`]); the `ct-tree` bin is a
5//! thin parse-and-dispatch wrapper over this `Cli`.
6
7use std::path::PathBuf;
8
9use clap::Parser;
10
11use crate::explain::Format;
12use crate::pattern;
13use crate::pulse::HeartbeatOpts;
14
15#[derive(Parser, Debug)]
16#[command(
17    name = "ct-tree",
18    version,
19    about = "Report a file tree with per-file line/word/char counts, filtered, sorted, and summarised.",
20    long_about = "ct-tree walks a directory for chosen file types and reports the effective tree with \
21                  per-file line, word, and character counts (also reachable as `ct tree`). Filter by \
22                  metric predicates (--min-lines etc.) and per-folder counts, sort by any column, and \
23                  choose a summarisation level (--tree, --flat, --summary). See `ct-tree --explain` \
24                  for agent-oriented documentation."
25)]
26#[command(group = clap::ArgGroup::new("output_mode")
27    .args(["tree", "flat", "summary"])
28    .multiple(false))]
29pub struct Cli {
30    /// Root to walk (relative or absolute), independent of the current directory.
31    #[arg(long, default_value = ".")]
32    pub base: PathBuf,
33
34    /// File-name pattern; '|'-separated alternatives, each substring->glob->regex promoted and anchored.
35    #[arg(long)]
36    pub name: Option<String>,
37
38    /// Pin how --name/--ext patterns are interpreted (promotion off): literal, glob, or regex.
39    #[arg(long, value_enum)]
40    pub mode: Option<pattern::Mode>,
41
42    /// Restrict to these extensions (comma-separated, no dots), e.g. --ext rs,toml. Combined with --name as alternatives.
43    #[arg(long, value_delimiter = ',')]
44    pub ext: Vec<String>,
45
46    /// Include dot-entries (names starting with '.'); default skips them.
47    #[arg(long)]
48    pub hidden: bool,
49
50    /// Follow symlinks while traversing.
51    #[arg(long)]
52    pub follow: bool,
53
54    /// Only include files with at least N lines.
55    #[arg(long)]
56    pub min_lines: Option<u64>,
57    /// Only include files with at most N lines.
58    #[arg(long)]
59    pub max_lines: Option<u64>,
60    /// Only include files with at least N words.
61    #[arg(long)]
62    pub min_words: Option<u64>,
63    /// Only include files with at most N words.
64    #[arg(long)]
65    pub max_words: Option<u64>,
66    /// Only include files with at least N characters.
67    #[arg(long)]
68    pub min_chars: Option<u64>,
69    /// Only include files with at most N characters.
70    #[arg(long)]
71    pub max_chars: Option<u64>,
72
73    /// Only include folders that directly contain at least N matching files.
74    #[arg(long)]
75    pub min_files_per_folder: Option<usize>,
76    /// Only include folders that directly contain at most N matching files.
77    #[arg(long)]
78    pub max_files_per_folder: Option<usize>,
79
80    /// Sort key: path, name, lines, words, chars, or ext.
81    #[arg(long, value_enum, default_value_t = SortKey::Path)]
82    pub sort: SortKey,
83    /// Sort descending instead of ascending.
84    #[arg(long)]
85    pub desc: bool,
86
87    /// Output mode: an indented file tree with per-file and per-folder counts (default).
88    #[arg(long)]
89    pub tree: bool,
90    /// Output mode: one matching file per line with its counts.
91    #[arg(long)]
92    pub flat: bool,
93    /// Output mode: aggregate counts only, grouped by --group.
94    #[arg(long)]
95    pub summary: bool,
96
97    /// Grouping for --summary: ext, dir, or none (grand total only).
98    #[arg(long, value_enum, default_value_t = GroupBy::Ext)]
99    pub group: GroupBy,
100
101    /// Emit a structured JSON result instead of text.
102    #[arg(long)]
103    pub json: bool,
104
105    /// Abort with exit 2 if the report exceeds SECS seconds (fractional allowed).
106    #[arg(long, value_name = "SECS")]
107    pub timeout: Option<f64>,
108
109    #[command(flatten)]
110    pub heartbeat: HeartbeatOpts,
111
112    /// Print agent usage docs (md or json) and exit.
113    #[arg(long, value_enum, num_args = 0..=1, default_missing_value = "md")]
114    pub explain: Option<Format>,
115}
116
117#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
118pub enum SortKey {
119    Path,
120    Name,
121    Lines,
122    Words,
123    Chars,
124    Ext,
125}
126
127#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
128pub enum GroupBy {
129    Ext,
130    Dir,
131    None,
132}
coding_tools/cli/ct_tree.rs

coding_tools/cli/
ct_tree.rs
