src/tools/tidy/src/style.rs

   1 //! Tidy check to enforce various stylistic guidelines on the Rust codebase.
   2 //!
   3 //! Example checks are:
   4 //!
   5 //! * No lines over 100 characters (in non-Rust files).
   6 //! * No files with over 3000 lines (in non-Rust files).
   7 //! * No tabs.
   8 //! * No trailing whitespace.
   9 //! * No CR characters.
  10 //! * No `TODO` or `XXX` directives.
  11 //! * No unexplained ` ```ignore ` or ` ```rust,ignore ` doc tests.
  12 //!
  13 //! Note that some of these rules are excluded from Rust files because we enforce rustfmt. It is
  14 //! preferable to be formatted rather than tidy-clean.
  15 //!
  16 //! A number of these checks can be opted-out of with various directives of the form:
  17 //! `// ignore-tidy-CHECK-NAME`.
  18
  19 use crate::walk::{filter_dirs, walk};
  20 use regex::Regex;
  21 use std::path::Path;
  22
  23 /// Error code markdown is restricted to 80 columns because they can be
  24 /// displayed on the console with --example.
  25 const ERROR_CODE_COLS: usize = 80;
  26 const COLS: usize = 100;
  27
  28 const LINES: usize = 3000;
  29
  30 const UNEXPLAINED_IGNORE_DOCTEST_INFO: &str = r#"unexplained "```ignore" doctest; try one:
  31
  32 * make the test actually pass, by adding necessary imports and declarations, or
  33 * use "```text", if the code is not Rust code, or
  34 * use "```compile_fail,Ennnn", if the code is expected to fail at compile time, or
  35 * use "```should_panic", if the code is expected to fail at run time, or
  36 * use "```no_run", if the code should type-check but not necessary linkable/runnable, or
  37 * explain it like "```ignore (cannot-test-this-because-xxxx)", if the annotation cannot be avoided.
  38
  39 "#;
  40
  41 const LLVM_UNREACHABLE_INFO: &str = r"\
  42 C++ code used llvm_unreachable, which triggers undefined behavior
  43 when executed when assertions are disabled.
  44 Use llvm::report_fatal_error for increased robustness.";
  45
  46 const ANNOTATIONS_TO_IGNORE: &[&str] = &[
  47     "// @!has",
  48     "// @has",
  49     "// @matches",
  50     "// CHECK",
  51     "// EMIT_MIR",
  52     "// compile-flags",
  53     "// error-pattern",
  54     "// gdb",
  55     "// lldb",
  56     "// cdb",
  57     "// normalize-stderr-test",
  58 ];
  59
  60 // Intentionally written in decimal rather than hex
  61 const PROBLEMATIC_CONSTS: &[u32] = &[
  62     184594741, 2880289470, 2881141438, 2965027518, 2976579765, 3203381950, 3405691582, 3405697037,
  63     3735927486, 4027431614, 4276992702,
  64 ];
  65
  66 /// Parser states for `line_is_url`.
  67 #[derive(Clone, Copy, PartialEq)]
  68 #[allow(non_camel_case_types)]
  69 enum LIUState {
  70     EXP_COMMENT_START,
  71     EXP_LINK_LABEL_OR_URL,
  72     EXP_URL,
  73     EXP_END,
  74 }
  75
  76 /// Returns `true` if `line` appears to be a line comment containing a URL,
  77 /// possibly with a Markdown link label in front, and nothing else.
  78 /// The Markdown link label, if present, may not contain whitespace.
  79 /// Lines of this form are allowed to be overlength, because Markdown
  80 /// offers no way to split a line in the middle of a URL, and the lengths
  81 /// of URLs to external references are beyond our control.
  82 fn line_is_url(is_error_code: bool, columns: usize, line: &str) -> bool {
  83     // more basic check for markdown, to avoid complexity in implementing two state machines
  84     if is_error_code {
  85         return line.starts_with('[') && line.contains("]:") && line.contains("http");
  86     }
  87
  88     use self::LIUState::*;
  89     let mut state: LIUState = EXP_COMMENT_START;
  90     let is_url = |w: &str| w.starts_with("http://") || w.starts_with("https://");
  91
  92     for tok in line.split_whitespace() {
  93         match (state, tok) {
  94             (EXP_COMMENT_START, "//") | (EXP_COMMENT_START, "///") | (EXP_COMMENT_START, "//!") => {
  95                 state = EXP_LINK_LABEL_OR_URL
  96             }
  97
  98             (EXP_LINK_LABEL_OR_URL, w)
  99                 if w.len() >= 4 && w.starts_with('[') && w.ends_with("]:") =>
 100             {
 101                 state = EXP_URL
 102             }
 103
 104             (EXP_LINK_LABEL_OR_URL, w) if is_url(w) => state = EXP_END,
 105
 106             (EXP_URL, w) if is_url(w) || w.starts_with("../") => state = EXP_END,
 107
 108             (_, w) if w.len() > columns && is_url(w) => state = EXP_END,
 109
 110             (_, _) => {}
 111         }
 112     }
 113
 114     state == EXP_END
 115 }
 116
 117 /// Returns `true` if `line` can be ignored. This is the case when it contains
 118 /// an annotation that is explicitly ignored.
 119 fn should_ignore(line: &str) -> bool {
 120     // Matches test annotations like `//~ ERROR text`.
 121     // This mirrors the regex in src/tools/compiletest/src/runtest.rs, please
 122     // update both if either are changed.
 123     let re = Regex::new("\\s*//(\\[.*\\])?~.*").unwrap();
 124     re.is_match(line) || ANNOTATIONS_TO_IGNORE.iter().any(|a| line.contains(a))
 125 }
 126
 127 /// Returns `true` if `line` is allowed to be longer than the normal limit.
 128 fn long_line_is_ok(extension: &str, is_error_code: bool, max_columns: usize, line: &str) -> bool {
 129     match extension {
 130         // fluent files are allowed to be any length
 131         "ftl" => true,
 132         // non-error code markdown is allowed to be any length
 133         "md" if !is_error_code => true,
 134         _ => line_is_url(is_error_code, max_columns, line) || should_ignore(line),
 135     }
 136 }
 137
 138 enum Directive {
 139     /// By default, tidy always warns against style issues.
 140     Deny,
 141
 142     /// `Ignore(false)` means that an `ignore-tidy-*` directive
 143     /// has been provided, but is unnecessary. `Ignore(true)`
 144     /// means that it is necessary (i.e. a warning would be
 145     /// produced if `ignore-tidy-*` was not present).
 146     Ignore(bool),
 147 }
 148
 149 fn contains_ignore_directive(can_contain: bool, contents: &str, check: &str) -> Directive {
 150     if !can_contain {
 151         return Directive::Deny;
 152     }
 153     // Update `can_contain` when changing this
 154     if contents.contains(&format!("// ignore-tidy-{check}"))
 155         || contents.contains(&format!("# ignore-tidy-{check}"))
 156         || contents.contains(&format!("/* ignore-tidy-{check} */"))
 157     {
 158         Directive::Ignore(false)
 159     } else {
 160         Directive::Deny
 161     }
 162 }
 163
 164 macro_rules! suppressible_tidy_err {
 165     ($err:ident, $skip:ident, $msg:expr) => {
 166         if let Directive::Deny = $skip {
 167             $err($msg);
 168         } else {
 169             $skip = Directive::Ignore(true);
 170         }
 171     };
 172 }
 173
 174 pub fn is_in(full_path: &Path, parent_folder_to_find: &str, folder_to_find: &str) -> bool {
 175     if let Some(parent) = full_path.parent() {
 176         if parent.file_name().map_or_else(
 177             || false,
 178             |f| {
 179                 f.to_string_lossy() == folder_to_find
 180                     && parent
 181                         .parent()
 182                         .and_then(|f| f.file_name())
 183                         .map_or_else(|| false, |f| f == parent_folder_to_find)
 184             },
 185         ) {
 186             true
 187         } else {
 188             is_in(parent, parent_folder_to_find, folder_to_find)
 189         }
 190     } else {
 191         false
 192     }
 193 }
 194
 195 fn skip_markdown_path(path: &Path) -> bool {
 196     // These aren't ready for tidy.
 197     const SKIP_MD: &[&str] = &[
 198         "src/doc/edition-guide",
 199         "src/doc/embedded-book",
 200         "src/doc/nomicon",
 201         "src/doc/reference",
 202         "src/doc/rust-by-example",
 203         "src/doc/rustc-dev-guide",
 204     ];
 205     SKIP_MD.iter().any(|p| path.ends_with(p))
 206 }
 207
 208 fn is_unexplained_ignore(extension: &str, line: &str) -> bool {
 209     if !line.ends_with("```ignore") && !line.ends_with("```rust,ignore") {
 210         return false;
 211     }
 212     if extension == "md" && line.trim().starts_with("//") {
 213         // Markdown examples may include doc comments with ignore inside a
 214         // code block.
 215         return false;
 216     }
 217     true
 218 }
 219
 220 pub fn check(path: &Path, bad: &mut bool) {
 221     fn skip(path: &Path) -> bool {
 222         filter_dirs(path) || skip_markdown_path(path)
 223     }
 224     let problematic_consts_strings: Vec<String> = (PROBLEMATIC_CONSTS.iter().map(u32::to_string))
 225         .chain(PROBLEMATIC_CONSTS.iter().map(|v| format!("{:x}", v)))
 226         .chain(PROBLEMATIC_CONSTS.iter().map(|v| format!("{:X}", v)))
 227         .collect();
 228     walk(path, &mut skip, &mut |entry, contents| {
 229         let file = entry.path();
 230         let filename = file.file_name().unwrap().to_string_lossy();
 231         let extensions = [".rs", ".py", ".js", ".sh", ".c", ".cpp", ".h", ".md", ".css", ".ftl"];
 232         if extensions.iter().all(|e| !filename.ends_with(e)) || filename.starts_with(".#") {
 233             return;
 234         }
 235
 236         let is_style_file = filename.ends_with(".css");
 237         let under_rustfmt = filename.ends_with(".rs") &&
 238             // This list should ideally be sourced from rustfmt.toml but we don't want to add a toml
 239             // parser to tidy.
 240             !file.ancestors().any(|a| {
 241                 a.ends_with("src/test") ||
 242                     a.ends_with("src/doc/book")
 243             });
 244
 245         if is_style_file && !is_in(file, "src", "librustdoc") {
 246             // We only check CSS files in rustdoc.
 247             return;
 248         }
 249
 250         if contents.is_empty() {
 251             tidy_error!(bad, "{}: empty file", file.display());
 252         }
 253
 254         let extension = file.extension().unwrap().to_string_lossy();
 255         let is_error_code = extension == "md" && is_in(file, "src", "error_codes");
 256
 257         let max_columns = if is_error_code { ERROR_CODE_COLS } else { COLS };
 258
 259         let can_contain = contents.contains("// ignore-tidy-")
 260             || contents.contains("# ignore-tidy-")
 261             || contents.contains("/* ignore-tidy-");
 262         // Enable testing ICE's that require specific (untidy)
 263         // file formats easily eg. `issue-1234-ignore-tidy.rs`
 264         if filename.contains("ignore-tidy") {
 265             return;
 266         }
 267         let mut skip_cr = contains_ignore_directive(can_contain, &contents, "cr");
 268         let mut skip_undocumented_unsafe =
 269             contains_ignore_directive(can_contain, &contents, "undocumented-unsafe");
 270         let mut skip_tab = contains_ignore_directive(can_contain, &contents, "tab");
 271         let mut skip_line_length = contains_ignore_directive(can_contain, &contents, "linelength");
 272         let mut skip_file_length = contains_ignore_directive(can_contain, &contents, "filelength");
 273         let mut skip_end_whitespace =
 274             contains_ignore_directive(can_contain, &contents, "end-whitespace");
 275         let mut skip_trailing_newlines =
 276             contains_ignore_directive(can_contain, &contents, "trailing-newlines");
 277         let mut skip_leading_newlines =
 278             contains_ignore_directive(can_contain, &contents, "leading-newlines");
 279         let mut skip_copyright = contains_ignore_directive(can_contain, &contents, "copyright");
 280         let mut leading_new_lines = false;
 281         let mut trailing_new_lines = 0;
 282         let mut lines = 0;
 283         let mut last_safety_comment = false;
 284         for (i, line) in contents.split('\n').enumerate() {
 285             let mut err = |msg: &str| {
 286                 tidy_error!(bad, "{}:{}: {}", file.display(), i + 1, msg);
 287             };
 288             if !under_rustfmt
 289                 && line.chars().count() > max_columns
 290                 && !long_line_is_ok(&extension, is_error_code, max_columns, line)
 291             {
 292                 suppressible_tidy_err!(
 293                     err,
 294                     skip_line_length,
 295                     &format!("line longer than {max_columns} chars")
 296                 );
 297             }
 298             if !is_style_file && line.contains('\t') {
 299                 suppressible_tidy_err!(err, skip_tab, "tab character");
 300             }
 301             if line.ends_with(' ') || line.ends_with('\t') {
 302                 suppressible_tidy_err!(err, skip_end_whitespace, "trailing whitespace");
 303             }
 304             if is_style_file && line.starts_with(' ') {
 305                 err("CSS files use tabs for indent");
 306             }
 307             if line.contains('\r') {
 308                 suppressible_tidy_err!(err, skip_cr, "CR character");
 309             }
 310             if filename != "style.rs" {
 311                 if line.contains("TODO") {
 312                     err("TODO is deprecated; use FIXME")
 313                 }
 314                 if line.contains("//") && line.contains(" XXX") {
 315                     err("XXX is deprecated; use FIXME")
 316                 }
 317                 for s in problematic_consts_strings.iter() {
 318                     if line.contains(s) {
 319                         err("Don't use magic numbers that spell things (consider 0x12345678)");
 320                     }
 321                 }
 322             }
 323             let is_test = || file.components().any(|c| c.as_os_str() == "tests");
 324             // for now we just check libcore
 325             if line.contains("unsafe {") && !line.trim().starts_with("//") && !last_safety_comment {
 326                 if file.components().any(|c| c.as_os_str() == "core") && !is_test() {
 327                     suppressible_tidy_err!(err, skip_undocumented_unsafe, "undocumented unsafe");
 328                 }
 329             }
 330             if line.contains("// SAFETY:") {
 331                 last_safety_comment = true;
 332             } else if line.trim().starts_with("//") || line.trim().is_empty() {
 333                 // keep previous value
 334             } else {
 335                 last_safety_comment = false;
 336             }
 337             if (line.starts_with("// Copyright")
 338                 || line.starts_with("# Copyright")
 339                 || line.starts_with("Copyright"))
 340                 && (line.contains("Rust Developers") || line.contains("Rust Project Developers"))
 341             {
 342                 suppressible_tidy_err!(
 343                     err,
 344                     skip_copyright,
 345                     "copyright notices attributed to the Rust Project Developers are deprecated"
 346                 );
 347             }
 348             if is_unexplained_ignore(&extension, line) {
 349                 err(UNEXPLAINED_IGNORE_DOCTEST_INFO);
 350             }
 351             if filename.ends_with(".cpp") && line.contains("llvm_unreachable") {
 352                 err(LLVM_UNREACHABLE_INFO);
 353             }
 354             if line.is_empty() {
 355                 if i == 0 {
 356                     leading_new_lines = true;
 357                 }
 358                 trailing_new_lines += 1;
 359             } else {
 360                 trailing_new_lines = 0;
 361             }
 362
 363             if !line.trim().starts_with("//") {
 364                 lines += 1;
 365             }
 366         }
 367         if leading_new_lines {
 368             let mut err = |_| {
 369                 tidy_error!(bad, "{}: leading newline", file.display());
 370             };
 371             suppressible_tidy_err!(err, skip_leading_newlines, "mising leading newline");
 372         }
 373         let mut err = |msg: &str| {
 374             tidy_error!(bad, "{}: {}", file.display(), msg);
 375         };
 376         match trailing_new_lines {
 377             0 => suppressible_tidy_err!(err, skip_trailing_newlines, "missing trailing newline"),
 378             1 => {}
 379             n => suppressible_tidy_err!(
 380                 err,
 381                 skip_trailing_newlines,
 382                 &format!("too many trailing newlines ({n})")
 383             ),
 384         };
 385         if lines > LINES {
 386             let mut err = |_| {
 387                 tidy_error!(
 388                     bad,
 389                     "{}: too many lines ({}) (add `// \
 390                      ignore-tidy-filelength` to the file to suppress this error)",
 391                     file.display(),
 392                     lines
 393                 );
 394             };
 395             suppressible_tidy_err!(err, skip_file_length, "");
 396         }
 397
 398         if let Directive::Ignore(false) = skip_cr {
 399             tidy_error!(bad, "{}: ignoring CR characters unnecessarily", file.display());
 400         }
 401         if let Directive::Ignore(false) = skip_tab {
 402             tidy_error!(bad, "{}: ignoring tab characters unnecessarily", file.display());
 403         }
 404         if let Directive::Ignore(false) = skip_end_whitespace {
 405             tidy_error!(bad, "{}: ignoring trailing whitespace unnecessarily", file.display());
 406         }
 407         if let Directive::Ignore(false) = skip_trailing_newlines {
 408             tidy_error!(bad, "{}: ignoring trailing newlines unnecessarily", file.display());
 409         }
 410         if let Directive::Ignore(false) = skip_leading_newlines {
 411             tidy_error!(bad, "{}: ignoring leading newlines unnecessarily", file.display());
 412         }
 413         if let Directive::Ignore(false) = skip_copyright {
 414             tidy_error!(bad, "{}: ignoring copyright unnecessarily", file.display());
 415         }
 416         // We deliberately do not warn about these being unnecessary,
 417         // that would just lead to annoying churn.
 418         let _unused = skip_line_length;
 419         let _unused = skip_file_length;
 420     })
 421 }