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 std::path::Path;
  20
  21 const ERROR_CODE_COLS: usize = 80;
  22 const COLS: usize = 100;
  23
  24 const LINES: usize = 3000;
  25
  26 const UNEXPLAINED_IGNORE_DOCTEST_INFO: &str = r#"unexplained "```ignore" doctest; try one:
  27
  28 * make the test actually pass, by adding necessary imports and declarations, or
  29 * use "```text", if the code is not Rust code, or
  30 * use "```compile_fail,Ennnn", if the code is expected to fail at compile time, or
  31 * use "```should_panic", if the code is expected to fail at run time, or
  32 * use "```no_run", if the code should type-check but not necessary linkable/runnable, or
  33 * explain it like "```ignore (cannot-test-this-because-xxxx)", if the annotation cannot be avoided.
  34
  35 "#;
  36
  37 const LLVM_UNREACHABLE_INFO: &str = r"\
  38 C++ code used llvm_unreachable, which triggers undefined behavior
  39 when executed when assertions are disabled.
  40 Use llvm::report_fatal_error for increased robustness.";
  41
  42 /// Parser states for `line_is_url`.
  43 #[derive(Clone, Copy, PartialEq)]
  44 #[allow(non_camel_case_types)]
  45 enum LIUState {
  46     EXP_COMMENT_START,
  47     EXP_LINK_LABEL_OR_URL,
  48     EXP_URL,
  49     EXP_END,
  50 }
  51
  52 /// Returns `true` if `line` appears to be a line comment containing an URL,
  53 /// possibly with a Markdown link label in front, and nothing else.
  54 /// The Markdown link label, if present, may not contain whitespace.
  55 /// Lines of this form are allowed to be overlength, because Markdown
  56 /// offers no way to split a line in the middle of a URL, and the lengths
  57 /// of URLs to external references are beyond our control.
  58 fn line_is_url(columns: usize, line: &str) -> bool {
  59     // more basic check for error_codes.rs, to avoid complexity in implementing two state machines
  60     if columns == ERROR_CODE_COLS {
  61         return line.starts_with('[') && line.contains("]:") && line.contains("http");
  62     }
  63
  64     use self::LIUState::*;
  65     let mut state: LIUState = EXP_COMMENT_START;
  66     let is_url = |w: &str| w.starts_with("http://") || w.starts_with("https://");
  67
  68     for tok in line.split_whitespace() {
  69         match (state, tok) {
  70             (EXP_COMMENT_START, "//") | (EXP_COMMENT_START, "///") | (EXP_COMMENT_START, "//!") => {
  71                 state = EXP_LINK_LABEL_OR_URL
  72             }
  73
  74             (EXP_LINK_LABEL_OR_URL, w)
  75                 if w.len() >= 4 && w.starts_with('[') && w.ends_with("]:") =>
  76             {
  77                 state = EXP_URL
  78             }
  79
  80             (EXP_LINK_LABEL_OR_URL, w) if is_url(w) => state = EXP_END,
  81
  82             (EXP_URL, w) if is_url(w) || w.starts_with("../") => state = EXP_END,
  83
  84             (_, w) if w.len() > columns && is_url(w) => state = EXP_END,
  85
  86             (_, _) => {}
  87         }
  88     }
  89
  90     state == EXP_END
  91 }
  92
  93 /// Returns `true` if `line` is allowed to be longer than the normal limit.
  94 /// Currently there is only one exception, for long URLs, but more
  95 /// may be added in the future.
  96 fn long_line_is_ok(max_columns: usize, line: &str) -> bool {
  97     if line_is_url(max_columns, line) {
  98         return true;
  99     }
 100
 101     false
 102 }
 103
 104 enum Directive {
 105     /// By default, tidy always warns against style issues.
 106     Deny,
 107
 108     /// `Ignore(false)` means that an `ignore-tidy-*` directive
 109     /// has been provided, but is unnecessary. `Ignore(true)`
 110     /// means that it is necessary (i.e. a warning would be
 111     /// produced if `ignore-tidy-*` was not present).
 112     Ignore(bool),
 113 }
 114
 115 fn contains_ignore_directive(can_contain: bool, contents: &str, check: &str) -> Directive {
 116     if !can_contain {
 117         return Directive::Deny;
 118     }
 119     // Update `can_contain` when changing this
 120     if contents.contains(&format!("// ignore-tidy-{}", check))
 121         || contents.contains(&format!("# ignore-tidy-{}", check))
 122         || contents.contains(&format!("/* ignore-tidy-{} */", check))
 123     {
 124         Directive::Ignore(false)
 125     } else {
 126         Directive::Deny
 127     }
 128 }
 129
 130 macro_rules! suppressible_tidy_err {
 131     ($err:ident, $skip:ident, $msg:expr) => {
 132         if let Directive::Deny = $skip {
 133             $err($msg);
 134         } else {
 135             $skip = Directive::Ignore(true);
 136         }
 137     };
 138 }
 139
 140 pub fn is_in(full_path: &Path, parent_folder_to_find: &str, folder_to_find: &str) -> bool {
 141     if let Some(parent) = full_path.parent() {
 142         if parent.file_name().map_or_else(
 143             || false,
 144             |f| {
 145                 f.to_string_lossy() == folder_to_find
 146                     && parent
 147                         .parent()
 148                         .and_then(|f| f.file_name())
 149                         .map_or_else(|| false, |f| f == parent_folder_to_find)
 150             },
 151         ) {
 152             true
 153         } else {
 154             is_in(parent, parent_folder_to_find, folder_to_find)
 155         }
 156     } else {
 157         false
 158     }
 159 }
 160
 161 pub fn check(path: &Path, bad: &mut bool) {
 162     super::walk(path, &mut super::filter_dirs, &mut |entry, contents| {
 163         let file = entry.path();
 164         let filename = file.file_name().unwrap().to_string_lossy();
 165         let extensions = [".rs", ".py", ".js", ".sh", ".c", ".cpp", ".h", ".md", ".css"];
 166         if extensions.iter().all(|e| !filename.ends_with(e)) || filename.starts_with(".#") {
 167             return;
 168         }
 169
 170         let is_style_file = filename.ends_with(".css");
 171         let under_rustfmt = filename.ends_with(".rs") &&
 172             // This list should ideally be sourced from rustfmt.toml but we don't want to add a toml
 173             // parser to tidy.
 174             !file.ancestors().any(|a| {
 175                 a.ends_with("src/test") ||
 176                     a.ends_with("library/std/src/sys/cloudabi") ||
 177                     a.ends_with("src/doc/book")
 178             });
 179
 180         if filename.ends_with(".md")
 181             && file.parent().unwrap().file_name().unwrap().to_string_lossy() != "error_codes"
 182         {
 183             // We don't want to check all ".md" files (almost of of them aren't compliant
 184             // currently), just the long error code explanation ones.
 185             return;
 186         }
 187         if is_style_file && !is_in(file, "src", "librustdoc") {
 188             // We only check CSS files in rustdoc.
 189             return;
 190         }
 191
 192         if contents.is_empty() {
 193             tidy_error!(bad, "{}: empty file", file.display());
 194         }
 195
 196         let max_columns = if filename == "error_codes.rs" || filename.ends_with(".md") {
 197             ERROR_CODE_COLS
 198         } else {
 199             COLS
 200         };
 201
 202         let can_contain = contents.contains("// ignore-tidy-")
 203             || contents.contains("# ignore-tidy-")
 204             || contents.contains("/* ignore-tidy-");
 205         // Enable testing ICE's that require specific (untidy)
 206         // file formats easily eg. `issue-1234-ignore-tidy.rs`
 207         if filename.contains("ignore-tidy") {
 208             return;
 209         }
 210         let mut skip_cr = contains_ignore_directive(can_contain, &contents, "cr");
 211         let mut skip_undocumented_unsafe =
 212             contains_ignore_directive(can_contain, &contents, "undocumented-unsafe");
 213         let mut skip_tab = contains_ignore_directive(can_contain, &contents, "tab");
 214         let mut skip_line_length = contains_ignore_directive(can_contain, &contents, "linelength");
 215         let mut skip_file_length = contains_ignore_directive(can_contain, &contents, "filelength");
 216         let mut skip_end_whitespace =
 217             contains_ignore_directive(can_contain, &contents, "end-whitespace");
 218         let mut skip_trailing_newlines =
 219             contains_ignore_directive(can_contain, &contents, "trailing-newlines");
 220         let mut skip_copyright = contains_ignore_directive(can_contain, &contents, "copyright");
 221         let mut leading_new_lines = false;
 222         let mut trailing_new_lines = 0;
 223         let mut lines = 0;
 224         let mut last_safety_comment = false;
 225         for (i, line) in contents.split('\n').enumerate() {
 226             let mut err = |msg: &str| {
 227                 tidy_error!(bad, "{}:{}: {}", file.display(), i + 1, msg);
 228             };
 229             if !under_rustfmt
 230                 && line.chars().count() > max_columns
 231                 && !long_line_is_ok(max_columns, line)
 232             {
 233                 suppressible_tidy_err!(
 234                     err,
 235                     skip_line_length,
 236                     &format!("line longer than {} chars", max_columns)
 237                 );
 238             }
 239             if !is_style_file && line.contains('\t') {
 240                 suppressible_tidy_err!(err, skip_tab, "tab character");
 241             }
 242             if line.ends_with(' ') || line.ends_with('\t') {
 243                 suppressible_tidy_err!(err, skip_end_whitespace, "trailing whitespace");
 244             }
 245             if is_style_file && line.starts_with(' ') {
 246                 err("CSS files use tabs for indent");
 247             }
 248             if line.contains('\r') {
 249                 suppressible_tidy_err!(err, skip_cr, "CR character");
 250             }
 251             if filename != "style.rs" {
 252                 if line.contains("TODO") {
 253                     err("TODO is deprecated; use FIXME")
 254                 }
 255                 if line.contains("//") && line.contains(" XXX") {
 256                     err("XXX is deprecated; use FIXME")
 257                 }
 258             }
 259             let is_test = || file.components().any(|c| c.as_os_str() == "tests");
 260             // for now we just check libcore
 261             if line.contains("unsafe {") && !line.trim().starts_with("//") && !last_safety_comment {
 262                 if file.components().any(|c| c.as_os_str() == "core") && !is_test() {
 263                     suppressible_tidy_err!(err, skip_undocumented_unsafe, "undocumented unsafe");
 264                 }
 265             }
 266             if line.contains("// SAFETY:") || line.contains("// Safety:") {
 267                 last_safety_comment = true;
 268             } else if line.trim().starts_with("//") || line.trim().is_empty() {
 269                 // keep previous value
 270             } else {
 271                 last_safety_comment = false;
 272             }
 273             if (line.starts_with("// Copyright")
 274                 || line.starts_with("# Copyright")
 275                 || line.starts_with("Copyright"))
 276                 && (line.contains("Rust Developers") || line.contains("Rust Project Developers"))
 277             {
 278                 suppressible_tidy_err!(
 279                     err,
 280                     skip_copyright,
 281                     "copyright notices attributed to the Rust Project Developers are deprecated"
 282                 );
 283             }
 284             if line.ends_with("```ignore") || line.ends_with("```rust,ignore") {
 285                 err(UNEXPLAINED_IGNORE_DOCTEST_INFO);
 286             }
 287             if filename.ends_with(".cpp") && line.contains("llvm_unreachable") {
 288                 err(LLVM_UNREACHABLE_INFO);
 289             }
 290             if line.is_empty() {
 291                 if i == 0 {
 292                     leading_new_lines = true;
 293                 }
 294                 trailing_new_lines += 1;
 295             } else {
 296                 trailing_new_lines = 0;
 297             }
 298             lines = i;
 299         }
 300         if leading_new_lines {
 301             tidy_error!(bad, "{}: leading newline", file.display());
 302         }
 303         let mut err = |msg: &str| {
 304             tidy_error!(bad, "{}: {}", file.display(), msg);
 305         };
 306         match trailing_new_lines {
 307             0 => suppressible_tidy_err!(err, skip_trailing_newlines, "missing trailing newline"),
 308             1 => {}
 309             n => suppressible_tidy_err!(
 310                 err,
 311                 skip_trailing_newlines,
 312                 &format!("too many trailing newlines ({})", n)
 313             ),
 314         };
 315         if lines > LINES {
 316             let mut err = |_| {
 317                 tidy_error!(
 318                     bad,
 319                     "{}: too many lines ({}) (add `// \
 320                      ignore-tidy-filelength` to the file to suppress this error)",
 321                     file.display(),
 322                     lines
 323                 );
 324             };
 325             suppressible_tidy_err!(err, skip_file_length, "");
 326         }
 327
 328         if let Directive::Ignore(false) = skip_cr {
 329             tidy_error!(bad, "{}: ignoring CR characters unnecessarily", file.display());
 330         }
 331         if let Directive::Ignore(false) = skip_tab {
 332             tidy_error!(bad, "{}: ignoring tab characters unnecessarily", file.display());
 333         }
 334         if let Directive::Ignore(false) = skip_line_length {
 335             tidy_error!(bad, "{}: ignoring line length unnecessarily", file.display());
 336         }
 337         if let Directive::Ignore(false) = skip_file_length {
 338             tidy_error!(bad, "{}: ignoring file length unnecessarily", file.display());
 339         }
 340         if let Directive::Ignore(false) = skip_end_whitespace {
 341             tidy_error!(bad, "{}: ignoring trailing whitespace unnecessarily", file.display());
 342         }
 343         if let Directive::Ignore(false) = skip_trailing_newlines {
 344             tidy_error!(bad, "{}: ignoring trailing newlines unnecessarily", file.display());
 345         }
 346         if let Directive::Ignore(false) = skip_copyright {
 347             tidy_error!(bad, "{}: ignoring copyright unnecessarily", file.display());
 348         }
 349     })
 350 }