|
| 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