src/tools/tidy/src/features.rs

   1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Tidy check to ensure that unstable features are all in order
  12 //!
  13 //! This check will ensure properties like:
  14 //!
  15 //! * All stability attributes look reasonably well formed
  16 //! * The set of library features is disjoint from the set of language features
  17 //! * Library features have at most one stability level
  18 //! * Library features have at most one `since` value
  19 //! * All unstable lang features have tests to ensure they are actually unstable
  20
  21 use std::collections::HashMap;
  22 use std::fmt;
  23 use std::fs::File;
  24 use std::io::prelude::*;
  25 use std::path::Path;
  26
  27 #[derive(Debug, PartialEq, Clone)]
  28 pub enum Status {
  29     Stable,
  30     Removed,
  31     Unstable,
  32 }
  33
  34 impl fmt::Display for Status {
  35     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  36         let as_str = match *self {
  37             Status::Stable => "stable",
  38             Status::Unstable => "unstable",
  39             Status::Removed => "removed",
  40         };
  41         fmt::Display::fmt(as_str, f)
  42     }
  43 }
  44
  45 #[derive(Debug, Clone)]
  46 pub struct Feature {
  47     pub level: Status,
  48     pub since: String,
  49     pub has_gate_test: bool,
  50     pub tracking_issue: Option<u32>,
  51 }
  52
  53 impl Feature {
  54     fn check_match(&self, other: &Feature)-> Result<(), Vec<&'static str>> {
  55         let mut mismatches = Vec::new();
  56         if self.level != other.level {
  57             mismatches.push("stability level");
  58         }
  59         if self.level == Status::Stable || other.level == Status::Stable {
  60             // As long as a feature is unstable, the since field tracks
  61             // when the given part of the feature has been implemented.
  62             // Mismatches are tolerable as features evolve and functionality
  63             // gets added.
  64             // Once a feature is stable, the since field tracks the first version
  65             // it was part of the stable distribution, and mismatches are disallowed.
  66             if self.since != other.since {
  67                 mismatches.push("since");
  68             }
  69         }
  70         if self.tracking_issue != other.tracking_issue {
  71             mismatches.push("tracking issue");
  72         }
  73         if mismatches.is_empty() {
  74             Ok(())
  75         } else {
  76             Err(mismatches)
  77         }
  78     }
  79 }
  80
  81 pub type Features = HashMap<String, Feature>;
  82
  83 pub fn check(path: &Path, bad: &mut bool, quiet: bool) {
  84     let mut features = collect_lang_features(path);
  85     assert!(!features.is_empty());
  86
  87     let lib_features = get_and_check_lib_features(path, bad, &features);
  88     assert!(!lib_features.is_empty());
  89
  90     let mut contents = String::new();
  91
  92     super::walk_many(&[&path.join("test/compile-fail"),
  93                        &path.join("test/compile-fail-fulldeps"),
  94                        &path.join("test/parse-fail"),],
  95                      &mut |path| super::filter_dirs(path),
  96                      &mut |file| {
  97         let filename = file.file_name().unwrap().to_string_lossy();
  98         if !filename.ends_with(".rs") || filename == "features.rs" ||
  99            filename == "diagnostic_list.rs" {
 100             return;
 101         }
 102
 103         let filen_underscore = filename.replace("-","_").replace(".rs","");
 104         let filename_is_gate_test = test_filen_gate(&filen_underscore, &mut features);
 105
 106         contents.truncate(0);
 107         t!(t!(File::open(&file), &file).read_to_string(&mut contents));
 108
 109         for (i, line) in contents.lines().enumerate() {
 110             let mut err = |msg: &str| {
 111                 tidy_error!(bad, "{}:{}: {}", file.display(), i + 1, msg);
 112             };
 113
 114             let gate_test_str = "gate-test-";
 115
 116             if !line.contains(gate_test_str) {
 117                 continue;
 118             }
 119
 120             let feature_name = match line.find(gate_test_str) {
 121                 Some(i) => {
 122                     &line[i+gate_test_str.len()..line[i+1..].find(' ').unwrap_or(line.len())]
 123                 },
 124                 None => continue,
 125             };
 126             match features.get_mut(feature_name) {
 127                 Some(f) => {
 128                     if filename_is_gate_test {
 129                         err(&format!("The file is already marked as gate test \
 130                                       through its name, no need for a \
 131                                       'gate-test-{}' comment",
 132                                      feature_name));
 133                     }
 134                     f.has_gate_test = true;
 135                 }
 136                 None => {
 137                     err(&format!("gate-test test found referencing a nonexistent feature '{}'",
 138                                  feature_name));
 139                 }
 140             }
 141         }
 142     });
 143
 144     // Only check the number of lang features.
 145     // Obligatory testing for library features is dumb.
 146     let gate_untested = features.iter()
 147                                 .filter(|&(_, f)| f.level == Status::Unstable)
 148                                 .filter(|&(_, f)| !f.has_gate_test)
 149                                 .collect::<Vec<_>>();
 150
 151     for &(name, _) in gate_untested.iter() {
 152         println!("Expected a gate test for the feature '{}'.", name);
 153         println!("Hint: create a file named 'feature-gate-{}.rs' in the compile-fail\
 154                 \n      test suite, with its failures due to missing usage of\
 155                 \n      #![feature({})].", name, name);
 156         println!("Hint: If you already have such a test and don't want to rename it,\
 157                 \n      you can also add a // gate-test-{} line to the test file.",
 158                  name);
 159     }
 160
 161     if gate_untested.len() > 0 {
 162         tidy_error!(bad, "Found {} features without a gate test.", gate_untested.len());
 163     }
 164
 165     if *bad {
 166         return;
 167     }
 168     if quiet {
 169         println!("* {} features", features.len());
 170         return;
 171     }
 172
 173     let mut lines = Vec::new();
 174     for (name, feature) in features.iter() {
 175         lines.push(format!("{:<32} {:<8} {:<12} {:<8}",
 176                            name,
 177                            "lang",
 178                            feature.level,
 179                            feature.since));
 180     }
 181     for (name, feature) in lib_features {
 182         lines.push(format!("{:<32} {:<8} {:<12} {:<8}",
 183                            name,
 184                            "lib",
 185                            feature.level,
 186                            feature.since));
 187     }
 188
 189     lines.sort();
 190     for line in lines {
 191         println!("* {}", line);
 192     }
 193 }
 194
 195 fn find_attr_val<'a>(line: &'a str, attr: &str) -> Option<&'a str> {
 196     line.find(attr)
 197         .and_then(|i| line[i..].find('"').map(|j| i + j + 1))
 198         .and_then(|i| line[i..].find('"').map(|j| (i, i + j)))
 199         .map(|(i, j)| &line[i..j])
 200 }
 201
 202 fn test_filen_gate(filen_underscore: &str, features: &mut Features) -> bool {
 203     if filen_underscore.starts_with("feature_gate") {
 204         for (n, f) in features.iter_mut() {
 205             if filen_underscore == format!("feature_gate_{}", n) {
 206                 f.has_gate_test = true;
 207                 return true;
 208             }
 209         }
 210     }
 211     return false;
 212 }
 213
 214 pub fn collect_lang_features(base_src_path: &Path) -> Features {
 215     let mut contents = String::new();
 216     let path = base_src_path.join("libsyntax/feature_gate.rs");
 217     t!(t!(File::open(path)).read_to_string(&mut contents));
 218
 219     contents.lines()
 220         .filter_map(|line| {
 221             let mut parts = line.trim().split(",");
 222             let level = match parts.next().map(|l| l.trim().trim_left_matches('(')) {
 223                 Some("active") => Status::Unstable,
 224                 Some("removed") => Status::Removed,
 225                 Some("accepted") => Status::Stable,
 226                 _ => return None,
 227             };
 228             let name = parts.next().unwrap().trim();
 229             let since = parts.next().unwrap().trim().trim_matches('"');
 230             let issue_str = parts.next().unwrap().trim();
 231             let tracking_issue = if issue_str.starts_with("None") {
 232                 None
 233             } else {
 234                 let s = issue_str.split("(").nth(1).unwrap().split(")").nth(0).unwrap();
 235                 Some(s.parse().unwrap())
 236             };
 237             Some((name.to_owned(),
 238                 Feature {
 239                     level,
 240                     since: since.to_owned(),
 241                     has_gate_test: false,
 242                     tracking_issue,
 243                 }))
 244         })
 245         .collect()
 246 }
 247
 248 pub fn collect_lib_features(base_src_path: &Path) -> Features {
 249     let mut lib_features = Features::new();
 250
 251     // This library feature is defined in the `compiler_builtins` crate, which
 252     // has been moved out-of-tree. Now it can no longer be auto-discovered by
 253     // `tidy`, because we need to filter out its (submodule) directory. Manually
 254     // add it to the set of known library features so we can still generate docs.
 255     lib_features.insert("compiler_builtins_lib".to_owned(), Feature {
 256         level: Status::Unstable,
 257         since: "".to_owned(),
 258         has_gate_test: false,
 259         tracking_issue: None,
 260     });
 261
 262     map_lib_features(base_src_path,
 263                      &mut |res, _, _| {
 264         match res {
 265             Ok((name, feature)) => {
 266                 if lib_features.get(name).is_some() {
 267                     return;
 268                 }
 269                 lib_features.insert(name.to_owned(), feature);
 270             },
 271             Err(_) => (),
 272         }
 273     });
 274    lib_features
 275 }
 276
 277 fn get_and_check_lib_features(base_src_path: &Path,
 278                               bad: &mut bool,
 279                               lang_features: &Features) -> Features {
 280     let mut lib_features = Features::new();
 281     map_lib_features(base_src_path,
 282                      &mut |res, file, line| {
 283             match res {
 284                 Ok((name, f)) => {
 285                     let mut check_features = |f: &Feature, list: &Features, display: &str| {
 286                         if let Some(ref s) = list.get(name) {
 287                             if let Err(m) = (&f).check_match(s) {
 288                                 tidy_error!(bad,
 289                                             "{}:{}: mismatches to {} in: {:?}",
 290                                             file.display(),
 291                                             line,
 292                                             display,
 293                                             &m);
 294                             }
 295                         }
 296                     };
 297                     check_features(&f, &lang_features, "corresponding lang feature");
 298                     check_features(&f, &lib_features, "previous");
 299                     lib_features.insert(name.to_owned(), f);
 300                 },
 301                 Err(msg) => {
 302                     tidy_error!(bad, "{}:{}: {}", file.display(), line, msg);
 303                 },
 304             }
 305
 306     });
 307     lib_features
 308 }
 309
 310 fn map_lib_features(base_src_path: &Path,
 311                     mf: &mut FnMut(Result<(&str, Feature), &str>, &Path, usize)) {
 312     let mut contents = String::new();
 313     super::walk(base_src_path,
 314                 &mut |path| super::filter_dirs(path) || path.ends_with("src/test"),
 315                 &mut |file| {
 316         let filename = file.file_name().unwrap().to_string_lossy();
 317         if !filename.ends_with(".rs") || filename == "features.rs" ||
 318            filename == "diagnostic_list.rs" {
 319             return;
 320         }
 321
 322         contents.truncate(0);
 323         t!(t!(File::open(&file), &file).read_to_string(&mut contents));
 324
 325         let mut becoming_feature: Option<(String, Feature)> = None;
 326         for (i, line) in contents.lines().enumerate() {
 327             macro_rules! err {
 328                 ($msg:expr) => {{
 329                     mf(Err($msg), file, i + 1);
 330                     continue;
 331                 }};
 332             };
 333             if let Some((ref name, ref mut f)) = becoming_feature {
 334                 if f.tracking_issue.is_none() {
 335                     f.tracking_issue = find_attr_val(line, "issue")
 336                     .map(|s| s.parse().unwrap());
 337                 }
 338                 if line.ends_with("]") {
 339                     mf(Ok((name, f.clone())), file, i + 1);
 340                 } else if !line.ends_with(",") && !line.ends_with("\\") {
 341                     // We need to bail here because we might have missed the
 342                     // end of a stability attribute above because the "]"
 343                     // might not have been at the end of the line.
 344                     // We could then get into the very unfortunate situation that
 345                     // we continue parsing the file assuming the current stability
 346                     // attribute has not ended, and ignoring possible feature
 347                     // attributes in the process.
 348                     err!("malformed stability attribute");
 349                 } else {
 350                     continue;
 351                 }
 352             }
 353             becoming_feature = None;
 354             if line.contains("rustc_const_unstable(") {
 355                 // const fn features are handled specially
 356                 let feature_name = match find_attr_val(line, "feature") {
 357                     Some(name) => name,
 358                     None => err!("malformed stability attribute"),
 359                 };
 360                 let feature = Feature {
 361                     level: Status::Unstable,
 362                     since: "None".to_owned(),
 363                     has_gate_test: false,
 364                     // Whether there is a common tracking issue
 365                     // for these feature gates remains an open question
 366                     // https://github.com/rust-lang/rust/issues/24111#issuecomment-340283184
 367                     // But we take 24111 otherwise they will be shown as
 368                     // "internal to the compiler" which they are not.
 369                     tracking_issue: Some(24111),
 370                 };
 371                 mf(Ok((feature_name, feature)), file, i + 1);
 372                 continue;
 373             }
 374             let level = if line.contains("[unstable(") {
 375                 Status::Unstable
 376             } else if line.contains("[stable(") {
 377                 Status::Stable
 378             } else {
 379                 continue;
 380             };
 381             let feature_name = match find_attr_val(line, "feature") {
 382                 Some(name) => name,
 383                 None => err!("malformed stability attribute"),
 384             };
 385             let since = match find_attr_val(line, "since") {
 386                 Some(name) => name,
 387                 None if level == Status::Stable => {
 388                     err!("malformed stability attribute");
 389                 }
 390                 None => "None",
 391             };
 392             let tracking_issue = find_attr_val(line, "issue").map(|s| s.parse().unwrap());
 393
 394             let feature = Feature {
 395                 level,
 396                 since: since.to_owned(),
 397                 has_gate_test: false,
 398                 tracking_issue,
 399             };
 400             if line.contains("]") {
 401                 mf(Ok((feature_name, feature)), file, i + 1);
 402             } else {
 403                 becoming_feature = Some((feature_name.to_owned(), feature));
 404             }
 405         }
 406     });
 407 }