Skip to content

Commit c5b884e

Browse files
committed
cpp_check: a named file set, and one file per job
Two changes to the tool, both about being usable on a large project. # `--file` and `--files-from` C++'s locality is strong and every file checked pays for its own include closure — measured on neovim, ~0.8 s of render per file, 252 s for the 228 translation units. A hook, an editor mapping "check this buffer", and a person reproducing a report all know which files they mean: ```text $ cpp_check E:\neovim --file src/nvim/cursor.c --file src/nvim/api/vim.c $ cpp_check E:\neovim --files-from changed.txt ``` `--file` is repeatable; `--files-from` reads one path per line, ignores blank lines and `#` comments, and resolves a relative path against the current directory. **`ROOT` is still the project**: its compile database, flags and `.cppls.toml` decide how a named file is read, so a header is still checked the way its build reads it. Either form skips the walk entirely; `--max-files` still caps the set. A list that cannot be read is an error rather than an empty run, because "check these files" answered with "no files" is a silence a hook would believe. Measured: two named files, 31 findings, **4.3 s** — against 4 minutes for the walk. The 31 are the same findings the walk gives for those two files. # One file per job `main.rs` was 859 lines holding the command line, the walk, the pipeline, the report and the tests. Now: ```text main.rs the sequence: parse, resolve the file set, run, merge, report, exit cli.rs the command line, the file-set resolution, and the clock the summary needs walk.rs the workspace walk — which extensions, which directories, `--headers`, `--exclude` rules.rs `--code`/`--skip-code` resolved against DiagnosticCode::ALL run.rs the per-file pipeline (load, catch_up, cook, pump, diagnostics) and its tally report.rs findings as text or JSON, the positions they point at, and the fate of the files tests.rs the arithmetic, the walk's file set, the filter, and the new list resolution ``` No behaviour moved with the code: the same 6 tests pass, the walk and the report are byte-identical on the same input, and `--time` prints the same stages. The new tests cover a list with comments, blanks and a repeated path (checked once), a missing list (an error naming the file), and `--file` overriding the walk while `--max-files` still caps it. Docs: `docs/cpp-check.md` gained the two forms and the measurement behind them.
1 parent 9aaccc4 commit c5b884e

8 files changed

Lines changed: 900 additions & 686 deletions

File tree

‎crates/cpp_check/src/cli.rs‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
//! **What the tool is told to do** — the command line, and the file set it resolves to.
2+
//!
3+
//! Two ways to name the work:
4+
//!
5+
//! ```text
6+
//! cpp_check [ROOT] walk the workspace (translation units, or --headers too)
7+
//! cpp_check ROOT --file a.c --file b.c exactly these files
8+
//! cpp_check ROOT --files-from list.txt exactly the files the list names
9+
//! ```
10+
//!
11+
//! **Why the second form exists.** C++'s locality is strong: a change to four files wants those four files checked, not
12+
//! the 228 translation units of the project, each of which pays for its own include closure (measured on neovim: ~0.8 s
13+
//! of render per file). A pre-commit hook, an editor mapping "check this buffer", and a person reproducing a report
14+
//! all know which files they mean, and telling the tool is cheaper than making it ask again.
15+
//!
16+
//! The project is still `ROOT`: the compile database, the toolchain's include search and `.cppls.toml` all come from
17+
//! there, so a named file is read the way the build reads it.
18+
19+
use std::path::{Path, PathBuf};
20+
use std::time::Instant;
21+
22+
use clap::Parser;
23+
24+
use crate::walk;
25+
26+
#[derive(Parser, Debug)]
27+
#[command(
28+
name = "cpp_check",
29+
version,
30+
about = "Run the analysis's checks over a whole workspace.",
31+
long_about = None
32+
)]
33+
pub struct Args {
34+
/// The workspace the files belong to — its compile database, flags and configuration. Defaults to the current
35+
/// directory.
36+
#[arg(default_value = ".")]
37+
pub root: PathBuf,
38+
39+
/// Check only this file. Repeatable; the project still comes from ROOT.
40+
#[arg(long = "file", value_name = "PATH")]
41+
pub files: Vec<PathBuf>,
42+
43+
/// A file naming the files to check, one path per line. Blank lines and lines starting with `#` are ignored, and
44+
/// a relative path is relative to the current directory.
45+
#[arg(long = "files-from", value_name = "PATH")]
46+
pub files_from: Option<PathBuf>,
47+
48+
/// Report only findings at or above this severity: hint, warning or error.
49+
#[arg(long, value_enum, default_value_t = Level::Warning)]
50+
pub min_severity: Level,
51+
52+
/// Only these codes, by name — `--code=undefined-name,use-after-free`.
53+
#[arg(long, value_delimiter = ',')]
54+
pub code: Vec<String>,
55+
56+
/// Skip these codes, by name.
57+
#[arg(long = "skip-code", value_delimiter = ',')]
58+
pub skip_code: Vec<String>,
59+
60+
/// Also check headers on their own. By default only translation units are checked — a header is checked in the
61+
/// context of the files that include it, which is the only context it compiles in.
62+
#[arg(long)]
63+
pub headers: bool,
64+
65+
/// Stop after this many files. A smoke run, not a check.
66+
#[arg(long)]
67+
pub max_files: Option<usize>,
68+
69+
/// Machine-readable output: one JSON object.
70+
#[arg(long)]
71+
pub json: bool,
72+
73+
/// Print nothing but the findings and the summary — no progress lines.
74+
#[arg(long)]
75+
pub quiet: bool,
76+
77+
/// A path substring to skip, repeatable — `--exclude=third_party`.
78+
#[arg(long)]
79+
pub exclude: Vec<String>,
80+
81+
/// Print where the time went, stage by stage.
82+
#[arg(long)]
83+
pub time: bool,
84+
}
85+
86+
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, clap::ValueEnum)]
87+
pub enum Level {
88+
Hint,
89+
Warning,
90+
Error,
91+
}
92+
93+
impl Level {
94+
pub fn rank(self) -> u8 {
95+
match self {
96+
Level::Hint => 0,
97+
Level::Warning => 1,
98+
Level::Error => 2,
99+
}
100+
}
101+
102+
pub fn of(severity: cpp_code_analysis::sema::check::RuleSeverity) -> Level {
103+
use cpp_code_analysis::sema::check::RuleSeverity;
104+
match severity {
105+
RuleSeverity::Error => Level::Error,
106+
RuleSeverity::Warning => Level::Warning,
107+
RuleSeverity::Hint | RuleSeverity::Information => Level::Hint,
108+
}
109+
}
110+
111+
pub fn text(self) -> &'static str {
112+
match self {
113+
Level::Hint => "hint",
114+
Level::Warning => "warning",
115+
Level::Error => "error",
116+
}
117+
}
118+
}
119+
120+
/// **The files a run checks**, in the order it checks them.
121+
///
122+
/// `--file` and `--files-from` name the set exactly, and the walk is skipped: the point of naming them is that the
123+
/// project is too large to read for four files. Without either, the workspace is walked — and `--max-files` caps the
124+
/// result, which is a smoke run rather than a check.
125+
///
126+
/// A named path is **absolute-ized but not canonicalized**, for the reason `main` documents about `ROOT`: on Windows
127+
/// `canonicalize` answers `\\?\C:\…`, and the analysis keys everything on the spelling a client writes.
128+
pub fn files_to_check(root: &Path, args: &Args) -> Result<Vec<PathBuf>, String> {
129+
let named = args.files.iter().cloned().chain(
130+
args.files_from
131+
.as_deref()
132+
.map(paths_in)
133+
.transpose()?
134+
.unwrap_or_default(),
135+
);
136+
137+
let mut files: Vec<PathBuf> = named
138+
.map(|path| {
139+
std::path::absolute(&path)
140+
.map_err(|error| format!("cannot resolve {}: {error}", path.display()))
141+
})
142+
.collect::<Result<_, _>>()?;
143+
144+
if files.is_empty() {
145+
files = walk::discover(root, args.headers, &args.exclude);
146+
} else {
147+
// **One entry per file.** A list that names a file twice (a hook that appends the changed files to a base
148+
// list) should check it once, and the order is the reader's: sorted, like the walk's.
149+
files.sort();
150+
files.dedup();
151+
}
152+
153+
if let Some(max) = args.max_files {
154+
files.truncate(max);
155+
}
156+
Ok(files)
157+
}
158+
159+
/// The paths a `--files-from` list names, in the order it writes them.
160+
///
161+
/// `#` is a comment because a list in a repository is kept next to a reason; a blank line is a separator. A missing
162+
/// list is an error rather than an empty set, because "check these files" answered with "no files" is the wrong
163+
/// silence.
164+
fn paths_in(list: &Path) -> Result<Vec<PathBuf>, String> {
165+
let text = std::fs::read_to_string(list)
166+
.map_err(|error| format!("cannot read {}: {error}", list.display()))?;
167+
Ok(text
168+
.lines()
169+
.map(str::trim)
170+
.filter(|line| !line.is_empty() && !line.starts_with('#'))
171+
.map(PathBuf::from)
172+
.collect())
173+
}
174+
175+
/// A timer the run's summary needs, kept here so `main` reads as the sequence of steps rather than as bookkeeping.
176+
pub struct Clock(Instant);
177+
178+
impl Clock {
179+
pub fn start() -> Clock {
180+
Clock(Instant::now())
181+
}
182+
183+
pub fn seconds(&self) -> f64 {
184+
self.0.elapsed().as_secs_f64()
185+
}
186+
}
187+
188+
#[cfg(test)]
189+
mod tests {
190+
use super::*;
191+
192+
fn args() -> Args {
193+
Args {
194+
root: PathBuf::from("."),
195+
files: Vec::new(),
196+
files_from: None,
197+
min_severity: Level::Warning,
198+
code: Vec::new(),
199+
skip_code: Vec::new(),
200+
headers: false,
201+
max_files: None,
202+
json: false,
203+
quiet: true,
204+
exclude: Vec::new(),
205+
time: false,
206+
}
207+
}
208+
209+
/// **A list file, as a repository writes one**: paths, comments, blank lines, and a repeated path.
210+
#[test]
211+
fn a_file_list_names_the_files_and_ignores_comments() {
212+
let directory = std::env::temp_dir().join(format!("cpp_check_list_{}", std::process::id()));
213+
let _ = std::fs::remove_dir_all(&directory);
214+
std::fs::create_dir_all(&directory).expect("a temp dir");
215+
let list = directory.join("files.txt");
216+
std::fs::write(
217+
&list,
218+
"# the files this change touches\nsrc/one.c\n\nsrc/two.c \n # indented comment\nsrc/one.c\n",
219+
)
220+
.expect("the list");
221+
222+
let mut args = args();
223+
args.files_from = Some(list);
224+
let files = files_to_check(&directory, &args).expect("the list resolves");
225+
let names: Vec<String> = files
226+
.iter()
227+
.map(|path| path.file_name().unwrap().to_string_lossy().into_owned())
228+
.collect();
229+
assert_eq!(
230+
names,
231+
vec!["one.c", "two.c"],
232+
"two files, sorted, with the repeat and the comments gone"
233+
);
234+
assert!(
235+
files.iter().all(|path| path.is_absolute()),
236+
"a named path is absolute-ized, so the session's keys do not depend on the caller's directory"
237+
);
238+
239+
let _ = std::fs::remove_dir_all(&directory);
240+
}
241+
242+
/// **A list that cannot be read is an error, not an empty check** — "check these files" answered with "nothing"
243+
/// is a silence a hook would believe.
244+
#[test]
245+
fn a_missing_list_is_an_error() {
246+
let mut args = args();
247+
args.files_from = Some(PathBuf::from("no-such-list-anywhere.txt"));
248+
let answer = files_to_check(Path::new("."), &args);
249+
assert!(
250+
answer.expect_err("a missing list").contains("cannot read"),
251+
"the message says which file could not be read"
252+
);
253+
}
254+
255+
/// **`--file` wins over the walk**, and `--max-files` still caps the set.
256+
#[test]
257+
fn a_named_file_is_checked_instead_of_the_walk() {
258+
let directory =
259+
std::env::temp_dir().join(format!("cpp_check_named_{}", std::process::id()));
260+
let _ = std::fs::remove_dir_all(&directory);
261+
std::fs::create_dir_all(&directory).expect("a temp dir");
262+
for name in ["a.c", "b.c", "c.c"] {
263+
std::fs::write(directory.join(name), "int x;\n").expect("a fixture file");
264+
}
265+
266+
let mut args = args();
267+
args.root = directory.clone();
268+
args.files = vec![directory.join("b.c")];
269+
let files = files_to_check(&directory, &args).expect("the named file");
270+
assert_eq!(files.len(), 1, "the walk did not run: {files:?}");
271+
assert_eq!(files[0].file_name().unwrap(), "b.c");
272+
273+
args.files.push(directory.join("a.c"));
274+
args.max_files = Some(1);
275+
let files = files_to_check(&directory, &args).expect("both named files");
276+
assert_eq!(files.len(), 1, "`--max-files` caps a named set too");
277+
278+
let _ = std::fs::remove_dir_all(&directory);
279+
}
280+
}

0 commit comments

Comments
 (0)