eslint/Makefile.js

   1 /**
   2  * @fileoverview Build file
   3  * @author nzakas
   4  */
   5
   6 /* global target */
   7 /* eslint no-use-before-define: "off", no-console: "off" */
   8 "use strict";
   9
  10 //------------------------------------------------------------------------------
  11 // Requirements
  12 //------------------------------------------------------------------------------
  13
  14 require("shelljs/make");
  15
  16 const lodash = require("lodash"),
  17     checker = require("npm-license"),
  18     ReleaseOps = require("eslint-release"),
  19     dateformat = require("dateformat"),
  20     fs = require("fs"),
  21     glob = require("glob"),
  22     markdownlint = require("markdownlint"),
  23     os = require("os"),
  24     path = require("path"),
  25     semver = require("semver"),
  26     ejs = require("ejs"),
  27     loadPerf = require("load-perf"),
  28     yaml = require("js-yaml"),
  29     { CLIEngine } = require("./lib/cli-engine"),
  30     builtinRules = require("./lib/rules/index");
  31
  32 const { cat, cd, cp, echo, exec, exit, find, ls, mkdir, pwd, rm, test } = require("shelljs");
  33
  34 //------------------------------------------------------------------------------
  35 // Settings
  36 //------------------------------------------------------------------------------
  37
  38 /*
  39  * A little bit fuzzy. My computer has a first CPU speed of 3392 and the perf test
  40  * always completes in < 3800ms. However, Travis is less predictable due to
  41  * multiple different VM types. So I'm fudging this for now in the hopes that it
  42  * at least provides some sort of useful signal.
  43  */
  44 const PERF_MULTIPLIER = 13e6;
  45
  46 const OPEN_SOURCE_LICENSES = [
  47     /MIT/u, /BSD/u, /Apache/u, /ISC/u, /WTF/u, /Public Domain/u, /LGPL/u
  48 ];
  49
  50 //------------------------------------------------------------------------------
  51 // Data
  52 //------------------------------------------------------------------------------
  53
  54 const NODE = "node ", // intentional extra space
  55     NODE_MODULES = "./node_modules/",
  56     TEMP_DIR = "./tmp/",
  57     DEBUG_DIR = "./debug/",
  58     BUILD_DIR = "build",
  59     DOCS_DIR = "../website/docs",
  60     SITE_DIR = "../website/",
  61     PERF_TMP_DIR = path.join(TEMP_DIR, "eslint", "performance"),
  62
  63     // Utilities - intentional extra space at the end of each string
  64     MOCHA = `${NODE_MODULES}mocha/bin/_mocha `,
  65     ESLINT = `${NODE} bin/eslint.js --report-unused-disable-directives `,
  66
  67     // Files
  68     RULE_FILES = glob.sync("lib/rules/*.js").filter(filePath => path.basename(filePath) !== "index.js"),
  69     JSON_FILES = find("conf/").filter(fileType("json")),
  70     MARKDOWN_FILES_ARRAY = find("docs/").concat(ls(".")).filter(fileType("md")),
  71     TEST_FILES = "\"tests/{bin,lib,tools}/**/*.js\"",
  72     PERF_ESLINTRC = path.join(PERF_TMP_DIR, "eslintrc.yml"),
  73     PERF_MULTIFILES_TARGET_DIR = path.join(PERF_TMP_DIR, "eslint"),
  74     PERF_MULTIFILES_TARGETS = `"${PERF_MULTIFILES_TARGET_DIR + path.sep}{lib,tests${path.sep}lib}${path.sep}**${path.sep}*.js"`,
  75
  76     // Settings
  77     MOCHA_TIMEOUT = 10000;
  78
  79 //------------------------------------------------------------------------------
  80 // Helpers
  81 //------------------------------------------------------------------------------
  82
  83 /**
  84  * Simple JSON file validation that relies on ES JSON parser.
  85  * @param {string} filePath Path to JSON.
  86  * @throws Error If file contents is invalid JSON.
  87  * @returns {undefined}
  88  */
  89 function validateJsonFile(filePath) {
  90     const contents = fs.readFileSync(filePath, "utf8");
  91
  92     JSON.parse(contents);
  93 }
  94
  95 /**
  96  * Generates a function that matches files with a particular extension.
  97  * @param {string} extension The file extension (i.e. "js")
  98  * @returns {Function} The function to pass into a filter method.
  99  * @private
 100  */
 101 function fileType(extension) {
 102     return function(filename) {
 103         return filename.slice(filename.lastIndexOf(".") + 1) === extension;
 104     };
 105 }
 106
 107 /**
 108  * Executes a command and returns the output instead of printing it to stdout.
 109  * @param {string} cmd The command string to execute.
 110  * @returns {string} The result of the executed command.
 111  */
 112 function execSilent(cmd) {
 113     return exec(cmd, { silent: true }).stdout;
 114 }
 115
 116 /**
 117  * Generates a release blog post for eslint.org
 118  * @param {Object} releaseInfo The release metadata.
 119  * @param {string} [prereleaseMajorVersion] If this is a prerelease, the next major version after this prerelease
 120  * @returns {void}
 121  * @private
 122  */
 123 function generateBlogPost(releaseInfo, prereleaseMajorVersion) {
 124     const ruleList = RULE_FILES
 125
 126         // Strip the .js extension
 127         .map(ruleFileName => path.basename(ruleFileName, ".js"))
 128
 129         /*
 130          * Sort by length descending. This ensures that rule names which are substrings of other rule names are not
 131          * matched incorrectly. For example, the string "no-undefined" should get matched with the `no-undefined` rule,
 132          * instead of getting matched with the `no-undef` rule followed by the string "ined".
 133          */
 134         .sort((ruleA, ruleB) => ruleB.length - ruleA.length);
 135
 136     const renderContext = Object.assign({ prereleaseMajorVersion, ruleList }, releaseInfo);
 137
 138     const output = ejs.render(cat("./templates/blogpost.md.ejs"), renderContext),
 139         now = new Date(),
 140         month = now.getMonth() + 1,
 141         day = now.getDate(),
 142         filename = `../website/_posts/${now.getFullYear()}-${
 143             month < 10 ? `0${month}` : month}-${
 144             day < 10 ? `0${day}` : day}-eslint-v${
 145             releaseInfo.version}-released.md`;
 146
 147     output.to(filename);
 148 }
 149
 150 /**
 151  * Generates a doc page with formatter result examples
 152  * @param  {Object} formatterInfo Linting results from each formatter
 153  * @param  {string} [prereleaseVersion] The version used for a prerelease. This
 154  *      changes where the output is stored.
 155  * @returns {void}
 156  */
 157 function generateFormatterExamples(formatterInfo, prereleaseVersion) {
 158     const output = ejs.render(cat("./templates/formatter-examples.md.ejs"), formatterInfo);
 159     let filename = "../website/docs/user-guide/formatters/index.md",
 160         htmlFilename = "../website/docs/user-guide/formatters/html-formatter-example.html";
 161
 162     if (prereleaseVersion) {
 163         filename = filename.replace("/docs", `/docs/${prereleaseVersion}`);
 164         htmlFilename = htmlFilename.replace("/docs", `/docs/${prereleaseVersion}`);
 165         if (!test("-d", path.dirname(filename))) {
 166             mkdir(path.dirname(filename));
 167         }
 168     }
 169
 170     output.to(filename);
 171     formatterInfo.formatterResults.html.result.to(htmlFilename);
 172 }
 173
 174 /**
 175  * Generate a doc page that lists all of the rules and links to them
 176  * @returns {void}
 177  */
 178 function generateRuleIndexPage() {
 179     const outputFile = "../website/_data/rules.yml",
 180         categoryList = "conf/category-list.json",
 181         categoriesData = JSON.parse(cat(path.resolve(categoryList)));
 182
 183     RULE_FILES
 184         .map(filename => [filename, path.basename(filename, ".js")])
 185         .sort((a, b) => a[1].localeCompare(b[1]))
 186         .forEach(pair => {
 187             const filename = pair[0];
 188             const basename = pair[1];
 189             const rule = require(path.resolve(filename));
 190
 191             if (rule.meta.deprecated) {
 192                 categoriesData.deprecated.rules.push({
 193                     name: basename,
 194                     replacedBy: rule.meta.replacedBy || []
 195                 });
 196             } else {
 197                 const output = {
 198                         name: basename,
 199                         description: rule.meta.docs.description,
 200                         recommended: rule.meta.docs.recommended || false,
 201                         fixable: !!rule.meta.fixable
 202                     },
 203                     category = lodash.find(categoriesData.categories, { name: rule.meta.docs.category });
 204
 205                 if (!category.rules) {
 206                     category.rules = [];
 207                 }
 208
 209                 category.rules.push(output);
 210             }
 211         });
 212
 213     const output = yaml.safeDump(categoriesData, { sortKeys: true });
 214
 215     output.to(outputFile);
 216 }
 217
 218 /**
 219  * Creates a git commit and tag in an adjacent `website` repository, without pushing it to
 220  * the remote. This assumes that the repository has already been modified somehow (e.g. by adding a blogpost).
 221  * @param {string} [tag] The string to tag the commit with
 222  * @returns {void}
 223  */
 224 function commitSiteToGit(tag) {
 225     const currentDir = pwd();
 226
 227     cd(SITE_DIR);
 228     exec("git add -A .");
 229     exec(`git commit -m "Autogenerated new docs and demo at ${dateformat(new Date())}"`);
 230
 231     if (tag) {
 232         exec(`git tag ${tag}`);
 233     }
 234
 235     exec("git fetch origin && git rebase origin/master");
 236     cd(currentDir);
 237 }
 238
 239 /**
 240  * Publishes the changes in an adjacent `website` repository to the remote. The
 241  * site should already have local commits (e.g. from running `commitSiteToGit`).
 242  * @returns {void}
 243  */
 244 function publishSite() {
 245     const currentDir = pwd();
 246
 247     cd(SITE_DIR);
 248     exec("git push origin master --tags");
 249     cd(currentDir);
 250 }
 251
 252 /**
 253  * Updates the changelog, bumps the version number in package.json, creates a local git commit and tag,
 254  * and generates the site in an adjacent `website` folder.
 255  * @returns {void}
 256  */
 257 function generateRelease() {
 258     ReleaseOps.generateRelease();
 259     const releaseInfo = JSON.parse(cat(".eslint-release-info.json"));
 260
 261     echo("Generating site");
 262     target.gensite();
 263     generateBlogPost(releaseInfo);
 264     commitSiteToGit(`v${releaseInfo.version}`);
 265 }
 266
 267 /**
 268  * Updates the changelog, bumps the version number in package.json, creates a local git commit and tag,
 269  * and generates the site in an adjacent `website` folder.
 270  * @param {string} prereleaseId The prerelease identifier (alpha, beta, etc.)
 271  * @returns {void}
 272  */
 273 function generatePrerelease(prereleaseId) {
 274     ReleaseOps.generateRelease(prereleaseId);
 275     const releaseInfo = JSON.parse(cat(".eslint-release-info.json"));
 276     const nextMajor = semver.inc(releaseInfo.version, "major");
 277
 278     echo("Generating site");
 279
 280     // always write docs into the next major directory (so 2.0.0-alpha.0 writes to 2.0.0)
 281     target.gensite(nextMajor);
 282
 283     /*
 284      * Premajor release should have identical "next major version".
 285      * Preminor and prepatch release will not.
 286      * 5.0.0-alpha.0 --> next major = 5, current major = 5
 287      * 4.4.0-alpha.0 --> next major = 5, current major = 4
 288      * 4.0.1-alpha.0 --> next major = 5, current major = 4
 289      */
 290     if (semver.major(releaseInfo.version) === semver.major(nextMajor)) {
 291
 292         /*
 293          * This prerelease is for a major release (not preminor/prepatch).
 294          * Blog post generation logic needs to be aware of this (as well as
 295          * know what the next major version is actually supposed to be).
 296          */
 297         generateBlogPost(releaseInfo, nextMajor);
 298     } else {
 299         generateBlogPost(releaseInfo);
 300     }
 301
 302     commitSiteToGit(`v${releaseInfo.version}`);
 303 }
 304
 305 /**
 306  * Publishes a generated release to npm and GitHub, and pushes changes to the adjacent `website` repo
 307  * to remote repo.
 308  * @returns {void}
 309  */
 310 function publishRelease() {
 311     ReleaseOps.publishRelease();
 312     publishSite();
 313 }
 314
 315 /**
 316  * Splits a command result to separate lines.
 317  * @param {string} result The command result string.
 318  * @returns {Array} The separated lines.
 319  */
 320 function splitCommandResultToLines(result) {
 321     return result.trim().split("\n");
 322 }
 323
 324 /**
 325  * Gets the first commit sha of the given file.
 326  * @param {string} filePath The file path which should be checked.
 327  * @returns {string} The commit sha.
 328  */
 329 function getFirstCommitOfFile(filePath) {
 330     let commits = execSilent(`git rev-list HEAD -- ${filePath}`);
 331
 332     commits = splitCommandResultToLines(commits);
 333     return commits[commits.length - 1].trim();
 334 }
 335
 336 /**
 337  * Gets the tag name where a given file was introduced first.
 338  * @param {string} filePath The file path to check.
 339  * @returns {string} The tag name.
 340  */
 341 function getFirstVersionOfFile(filePath) {
 342     const firstCommit = getFirstCommitOfFile(filePath);
 343     let tags = execSilent(`git tag --contains ${firstCommit}`);
 344
 345     tags = splitCommandResultToLines(tags);
 346     return tags.reduce((list, version) => {
 347         const validatedVersion = semver.valid(version.trim());
 348
 349         if (validatedVersion) {
 350             list.push(validatedVersion);
 351         }
 352         return list;
 353     }, []).sort(semver.compare)[0];
 354 }
 355
 356 /**
 357  * Gets the commit that deleted a file.
 358  * @param {string} filePath The path to the deleted file.
 359  * @returns {string} The commit sha.
 360  */
 361 function getCommitDeletingFile(filePath) {
 362     const commits = execSilent(`git rev-list HEAD -- ${filePath}`);
 363
 364     return splitCommandResultToLines(commits)[0];
 365 }
 366
 367 /**
 368  * Gets the first version number where a given file is no longer present.
 369  * @param {string} filePath The path to the deleted file.
 370  * @returns {string} The version number.
 371  */
 372 function getFirstVersionOfDeletion(filePath) {
 373     const deletionCommit = getCommitDeletingFile(filePath),
 374         tags = execSilent(`git tag --contains ${deletionCommit}`);
 375
 376     return splitCommandResultToLines(tags)
 377         .map(version => semver.valid(version.trim()))
 378         .filter(version => version)
 379         .sort(semver.compare)[0];
 380 }
 381
 382 /**
 383  * Lints Markdown files.
 384  * @param {Array} files Array of file names to lint.
 385  * @returns {Object} exec-style exit code object.
 386  * @private
 387  */
 388 function lintMarkdown(files) {
 389     const config = yaml.safeLoad(fs.readFileSync(path.join(__dirname, "./.markdownlint.yml"), "utf8")),
 390         result = markdownlint.sync({
 391             files,
 392             config,
 393             resultVersion: 1
 394         }),
 395         resultString = result.toString(),
 396         returnCode = resultString ? 1 : 0;
 397
 398     if (resultString) {
 399         console.error(resultString);
 400     }
 401     return { code: returnCode };
 402 }
 403
 404 /**
 405  * Gets linting results from every formatter, based on a hard-coded snippet and config
 406  * @returns {Object} Output from each formatter
 407  */
 408 function getFormatterResults() {
 409     const stripAnsi = require("strip-ansi");
 410
 411     const formatterFiles = fs.readdirSync("./lib/cli-engine/formatters/"),
 412         rules = {
 413             "no-else-return": "warn",
 414             indent: ["warn", 4],
 415             "space-unary-ops": "error",
 416             semi: ["warn", "always"],
 417             "consistent-return": "error"
 418         },
 419         cli = new CLIEngine({
 420             useEslintrc: false,
 421             baseConfig: { extends: "eslint:recommended" },
 422             rules
 423         }),
 424         codeString = [
 425             "function addOne(i) {",
 426             "    if (i != NaN) {",
 427             "        return i ++",
 428             "    } else {",
 429             "      return",
 430             "    }",
 431             "};"
 432         ].join("\n"),
 433         rawMessages = cli.executeOnText(codeString, "fullOfProblems.js", true),
 434         rulesMap = cli.getRules(),
 435         rulesMeta = {};
 436
 437     Object.keys(rules).forEach(ruleId => {
 438         rulesMeta[ruleId] = rulesMap.get(ruleId).meta;
 439     });
 440
 441     return formatterFiles.reduce((data, filename) => {
 442         const fileExt = path.extname(filename),
 443             name = path.basename(filename, fileExt);
 444
 445         if (fileExt === ".js") {
 446             const formattedOutput = cli.getFormatter(name)(
 447                 rawMessages.results,
 448                 { rulesMeta }
 449             );
 450
 451             data.formatterResults[name] = {
 452                 result: stripAnsi(formattedOutput)
 453             };
 454         }
 455         return data;
 456     }, { formatterResults: {} });
 457 }
 458
 459 /**
 460  * Gets a path to an executable in node_modules/.bin
 461  * @param {string} command The executable name
 462  * @returns {string} The executable path
 463  */
 464 function getBinFile(command) {
 465     return path.join("node_modules", ".bin", command);
 466 }
 467
 468 //------------------------------------------------------------------------------
 469 // Tasks
 470 //------------------------------------------------------------------------------
 471
 472 target.all = function() {
 473     target.test();
 474 };
 475
 476 target.lint = function([fix = false] = []) {
 477     let errors = 0,
 478         lastReturn;
 479
 480     echo("Validating JavaScript files");
 481     lastReturn = exec(`${ESLINT}${fix ? "--fix" : ""} .`);
 482     if (lastReturn.code !== 0) {
 483         errors++;
 484     }
 485
 486     echo("Validating JSON Files");
 487     lodash.forEach(JSON_FILES, validateJsonFile);
 488
 489     echo("Validating Markdown Files");
 490     lastReturn = lintMarkdown(MARKDOWN_FILES_ARRAY);
 491     if (lastReturn.code !== 0) {
 492         errors++;
 493     }
 494
 495     if (errors) {
 496         exit(1);
 497     }
 498 };
 499
 500 target.fuzz = function({ amount = 1000, fuzzBrokenAutofixes = false } = {}) {
 501     const fuzzerRunner = require("./tools/fuzzer-runner");
 502     const fuzzResults = fuzzerRunner.run({ amount, fuzzBrokenAutofixes });
 503
 504     if (fuzzResults.length) {
 505
 506         const uniqueStackTraceCount = new Set(fuzzResults.map(result => result.error)).size;
 507
 508         echo(`The fuzzer reported ${fuzzResults.length} error${fuzzResults.length === 1 ? "" : "s"} with a total of ${uniqueStackTraceCount} unique stack trace${uniqueStackTraceCount === 1 ? "" : "s"}.`);
 509
 510         const formattedResults = JSON.stringify({ results: fuzzResults }, null, 4);
 511
 512         if (process.env.CI) {
 513             echo("More details can be found below.");
 514             echo(formattedResults);
 515         } else {
 516             if (!test("-d", DEBUG_DIR)) {
 517                 mkdir(DEBUG_DIR);
 518             }
 519
 520             let fuzzLogPath;
 521             let fileSuffix = 0;
 522
 523             // To avoid overwriting any existing fuzzer log files, append a numeric suffix to the end of the filename.
 524             do {
 525                 fuzzLogPath = path.join(DEBUG_DIR, `fuzzer-log-${fileSuffix}.json`);
 526                 fileSuffix++;
 527             } while (test("-f", fuzzLogPath));
 528
 529             formattedResults.to(fuzzLogPath);
 530
 531             // TODO: (not-an-aardvark) Create a better way to isolate and test individual fuzzer errors from the log file
 532             echo(`More details can be found in ${fuzzLogPath}.`);
 533         }
 534
 535         exit(1);
 536     }
 537 };
 538
 539 target.mocha = () => {
 540     let errors = 0,
 541         lastReturn;
 542
 543     echo("Running unit tests");
 544
 545     lastReturn = exec(`${getBinFile("nyc")} -- ${MOCHA} -R progress -t ${MOCHA_TIMEOUT} -c ${TEST_FILES}`);
 546     if (lastReturn.code !== 0) {
 547         errors++;
 548     }
 549
 550     lastReturn = exec(`${getBinFile("nyc")} check-coverage --statement 99 --branch 98 --function 99 --lines 99`);
 551     if (lastReturn.code !== 0) {
 552         errors++;
 553     }
 554
 555     if (errors) {
 556         exit(1);
 557     }
 558 };
 559
 560 target.karma = () => {
 561     echo("Running unit tests on browsers");
 562
 563     target.webpack("production");
 564
 565     const lastReturn = exec(`${getBinFile("karma")} start karma.conf.js`);
 566
 567     if (lastReturn.code !== 0) {
 568         exit(1);
 569     }
 570 };
 571
 572 target.test = function() {
 573     target.lint();
 574     target.checkRuleFiles();
 575     target.mocha();
 576     target.karma();
 577     target.fuzz({ amount: 150, fuzzBrokenAutofixes: false });
 578     target.checkLicenses();
 579 };
 580
 581 target.docs = function() {
 582     echo("Generating documentation");
 583     exec(`${getBinFile("jsdoc")} -d jsdoc lib`);
 584     echo("Documentation has been output to /jsdoc");
 585 };
 586
 587 target.gensite = function(prereleaseVersion) {
 588     echo("Generating eslint.org");
 589
 590     let docFiles = [
 591         "/rules/",
 592         "/user-guide/",
 593         "/maintainer-guide/",
 594         "/developer-guide/",
 595         "/about/"
 596     ];
 597
 598     // append version
 599     if (prereleaseVersion) {
 600         docFiles = docFiles.map(docFile => `/${prereleaseVersion}${docFile}`);
 601     }
 602
 603     // 1. create temp and build directory
 604     echo("> Creating a temporary directory (Step 1)");
 605     if (!test("-d", TEMP_DIR)) {
 606         mkdir(TEMP_DIR);
 607     }
 608
 609     // 2. remove old files from the site
 610     echo("> Removing old files (Step 2)");
 611     docFiles.forEach(filePath => {
 612         const fullPath = path.join(DOCS_DIR, filePath),
 613             htmlFullPath = fullPath.replace(".md", ".html");
 614
 615         if (test("-f", fullPath)) {
 616
 617             rm("-rf", fullPath);
 618
 619             if (filePath.indexOf(".md") >= 0 && test("-f", htmlFullPath)) {
 620                 rm("-rf", htmlFullPath);
 621             }
 622         }
 623     });
 624
 625     // 3. Copy docs folder to a temporary directory
 626     echo("> Copying the docs folder (Step 3)");
 627     cp("-rf", "docs/*", TEMP_DIR);
 628
 629     let versions = test("-f", "./versions.json") ? JSON.parse(cat("./versions.json")) : {};
 630
 631     if (!versions.added) {
 632         versions = {
 633             added: versions,
 634             removed: {}
 635         };
 636     }
 637
 638     const rules = require(".").linter.getRules();
 639
 640     const RECOMMENDED_TEXT = "\n\n(recommended) The `\"extends\": \"eslint:recommended\"` property in a configuration file enables this rule.";
 641     const FIXABLE_TEXT = "\n\n(fixable) The `--fix` option on the [command line](../user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.";
 642
 643     // 4. Loop through all files in temporary directory
 644     process.stdout.write("> Updating files (Steps 4-9): 0/... - ...\r");
 645     const tempFiles = find(TEMP_DIR);
 646     const length = tempFiles.length;
 647
 648     tempFiles.forEach((filename, i) => {
 649         if (test("-f", filename) && path.extname(filename) === ".md") {
 650
 651             const rulesUrl = "https://github.com/eslint/eslint/tree/master/lib/rules/",
 652                 docsUrl = "https://github.com/eslint/eslint/tree/master/docs/rules/",
 653                 baseName = path.basename(filename),
 654                 sourceBaseName = `${path.basename(filename, ".md")}.js`,
 655                 sourcePath = path.join("lib/rules", sourceBaseName),
 656                 ruleName = path.basename(filename, ".md"),
 657                 filePath = path.join("docs", path.relative("tmp", filename));
 658             let text = cat(filename),
 659                 ruleType = "",
 660                 title;
 661
 662             process.stdout.write(`> Updating files (Steps 4-9): ${i}/${length} - ${filePath + " ".repeat(30)}\r`);
 663
 664             // 5. Prepend page title and layout variables at the top of rules
 665             if (path.dirname(filename).indexOf("rules") >= 0) {
 666
 667                 // Find out if the rule requires a special docs portion (e.g. if it is recommended and/or fixable)
 668                 const rule = rules.get(ruleName);
 669                 const isRecommended = rule && rule.meta.docs.recommended;
 670                 const isFixable = rule && rule.meta.fixable;
 671
 672                 // Incorporate the special portion into the documentation content
 673                 const textSplit = text.split("\n");
 674                 const ruleHeading = textSplit[0];
 675                 const ruleDocsContent = textSplit.slice(1).join("\n");
 676
 677                 text = `${ruleHeading}${isRecommended ? RECOMMENDED_TEXT : ""}${isFixable ? FIXABLE_TEXT : ""}\n${ruleDocsContent}`;
 678                 title = `${ruleName} - Rules`;
 679
 680                 if (rule && rule.meta) {
 681                     ruleType = `rule_type: ${rule.meta.type}`;
 682                 }
 683             } else {
 684
 685                 // extract the title from the file itself
 686                 title = text.match(/#([^#].+)\n/u);
 687                 if (title) {
 688                     title = title[1].trim();
 689                 } else {
 690                     title = "Documentation";
 691                 }
 692             }
 693
 694             text = [
 695                 "---",
 696                 `title: ${title}`,
 697                 "layout: doc",
 698                 `edit_link: https://github.com/eslint/eslint/edit/master/${filePath}`,
 699                 ruleType,
 700                 "---",
 701                 "<!-- Note: No pull requests accepted for this file. See README.md in the root directory for details. -->",
 702                 "",
 703                 text
 704             ].join("\n");
 705
 706             // 6. Remove .md extension for relative links and change README to empty string
 707             text = text.replace(/\((?!https?:\/\/)([^)]*?)\.md(.*?)\)/gu, "($1$2)").replace("README.html", "");
 708
 709             // 7. Check if there's a trailing white line at the end of the file, if there isn't one, add it
 710             if (!/\n$/u.test(text)) {
 711                 text = `${text}\n`;
 712             }
 713
 714             // 8. Append first version of ESLint rule was added at.
 715             if (filename.indexOf("rules/") !== -1) {
 716                 if (!versions.added[baseName]) {
 717                     versions.added[baseName] = getFirstVersionOfFile(sourcePath);
 718                 }
 719                 const added = versions.added[baseName];
 720
 721                 if (!versions.removed[baseName] && !test("-f", sourcePath)) {
 722                     versions.removed[baseName] = getFirstVersionOfDeletion(sourcePath);
 723                 }
 724                 const removed = versions.removed[baseName];
 725
 726                 text += "\n## Version\n\n";
 727                 text += removed
 728                     ? `This rule was introduced in ESLint ${added} and removed in ${removed}.\n`
 729                     : `This rule was introduced in ESLint ${added}.\n`;
 730
 731                 text += "\n## Resources\n\n";
 732                 if (!removed) {
 733                     text += `* [Rule source](${rulesUrl}${sourceBaseName})\n`;
 734                 }
 735                 text += `* [Documentation source](${docsUrl}${baseName})\n`;
 736             }
 737
 738             // 9. Update content of the file with changes
 739             text.to(filename.replace("README.md", "index.md"));
 740         }
 741     });
 742     JSON.stringify(versions).to("./versions.json");
 743     echo(`> Updating files (Steps 4-9)${" ".repeat(50)}`);
 744
 745     // 10. Copy temporary directory to site's docs folder
 746     echo("> Copying the temporary directory the site (Step 10)");
 747     let outputDir = DOCS_DIR;
 748
 749     if (prereleaseVersion) {
 750         outputDir += `/${prereleaseVersion}`;
 751         if (!test("-d", outputDir)) {
 752             mkdir(outputDir);
 753         }
 754     }
 755     cp("-rf", `${TEMP_DIR}*`, outputDir);
 756
 757     // 11. Generate rule listing page
 758     echo("> Generating the rule listing (Step 11)");
 759     generateRuleIndexPage();
 760
 761     // 12. Delete temporary directory
 762     echo("> Removing the temporary directory (Step 12)");
 763     rm("-rf", TEMP_DIR);
 764
 765     // 13. Create Example Formatter Output Page
 766     echo("> Creating the formatter examples (Step 14)");
 767     generateFormatterExamples(getFormatterResults(), prereleaseVersion);
 768
 769     echo("Done generating eslint.org");
 770 };
 771
 772 target.webpack = function(mode = "none") {
 773     exec(`${getBinFile("webpack")} --mode=${mode} --output-path=${BUILD_DIR}`);
 774 };
 775
 776 target.checkRuleFiles = function() {
 777
 778     echo("Validating rules");
 779
 780     const ruleTypes = require("./tools/rule-types.json");
 781     let errors = 0;
 782
 783     RULE_FILES.forEach(filename => {
 784         const basename = path.basename(filename, ".js");
 785         const docFilename = `docs/rules/${basename}.md`;
 786
 787         /**
 788          * Check if basename is present in rule-types.json file.
 789          * @returns {boolean} true if present
 790          * @private
 791          */
 792         function isInRuleTypes() {
 793             return Object.prototype.hasOwnProperty.call(ruleTypes, basename);
 794         }
 795
 796         /**
 797          * Check if id is present in title
 798          * @param {string} id id to check for
 799          * @returns {boolean} true if present
 800          * @private
 801          */
 802         function hasIdInTitle(id) {
 803             const docText = cat(docFilename);
 804             const idOldAtEndOfTitleRegExp = new RegExp(`^# (.*?) \\(${id}\\)`, "u"); // original format
 805             const idNewAtBeginningOfTitleRegExp = new RegExp(`^# ${id}: `, "u"); // new format is same as rules index
 806             /*
 807              * 1. Added support for new format.
 808              * 2. Will remove support for old format after all docs files have new format.
 809              * 3. Will remove this check when the main heading is automatically generated from rule metadata.
 810              */
 811
 812             return idNewAtBeginningOfTitleRegExp.test(docText) || idOldAtEndOfTitleRegExp.test(docText);
 813         }
 814
 815         // check for docs
 816         if (!test("-f", docFilename)) {
 817             console.error("Missing documentation for rule %s", basename);
 818             errors++;
 819         } else {
 820
 821             // check for proper doc format
 822             if (!hasIdInTitle(basename)) {
 823                 console.error("Missing id in the doc page's title of rule %s", basename);
 824                 errors++;
 825             }
 826         }
 827
 828         // check for recommended configuration
 829         if (!isInRuleTypes()) {
 830             console.error("Missing setting for %s in tools/rule-types.json", basename);
 831             errors++;
 832         }
 833
 834         // check parity between rules index file and rules directory
 835         const ruleIdsInIndex = require("./lib/rules/index");
 836         const ruleDef = ruleIdsInIndex.get(basename);
 837
 838         if (!ruleDef) {
 839             console.error(`Missing rule from index (./lib/rules/index.js): ${basename}. If you just added a new rule then add an entry for it in this file.`);
 840             errors++;
 841         }
 842
 843         // check eslint:recommended
 844         const recommended = require("./conf/eslint-recommended");
 845
 846         if (ruleDef) {
 847             if (ruleDef.meta.docs.recommended) {
 848                 if (recommended.rules[basename] !== "error") {
 849                     console.error(`Missing rule from eslint:recommended (./conf/eslint-recommended.js): ${basename}. If you just made a rule recommended then add an entry for it in this file.`);
 850                     errors++;
 851                 }
 852             } else {
 853                 if (basename in recommended.rules) {
 854                     console.error(`Extra rule in eslint:recommended (./conf/eslint-recommended.js): ${basename}. If you just added a rule then don't add an entry for it in this file.`);
 855                     errors++;
 856                 }
 857             }
 858         }
 859
 860         // check for tests
 861         if (!test("-f", `tests/lib/rules/${basename}.js`)) {
 862             console.error("Missing tests for rule %s", basename);
 863             errors++;
 864         }
 865
 866     });
 867
 868     if (errors) {
 869         exit(1);
 870     }
 871
 872 };
 873
 874 target.checkLicenses = function() {
 875
 876     /**
 877      * Check if a dependency is eligible to be used by us
 878      * @param {Object} dependency dependency to check
 879      * @returns {boolean} true if we have permission
 880      * @private
 881      */
 882     function isPermissible(dependency) {
 883         const licenses = dependency.licenses;
 884
 885         if (Array.isArray(licenses)) {
 886             return licenses.some(license => isPermissible({
 887                 name: dependency.name,
 888                 licenses: license
 889             }));
 890         }
 891
 892         return OPEN_SOURCE_LICENSES.some(license => license.test(licenses));
 893     }
 894
 895     echo("Validating licenses");
 896
 897     checker.init({
 898         start: __dirname
 899     }, deps => {
 900         const impermissible = Object.keys(deps).map(dependency => ({
 901             name: dependency,
 902             licenses: deps[dependency].licenses
 903         })).filter(dependency => !isPermissible(dependency));
 904
 905         if (impermissible.length) {
 906             impermissible.forEach(dependency => {
 907                 console.error(
 908                     "%s license for %s is impermissible.",
 909                     dependency.licenses,
 910                     dependency.name
 911                 );
 912             });
 913             exit(1);
 914         }
 915     });
 916 };
 917
 918 /**
 919  * Downloads a repository which has many js files to test performance with multi files.
 920  * Here, it's eslint@1.10.3 (450 files)
 921  * @param {Function} cb A callback function.
 922  * @returns {void}
 923  */
 924 function downloadMultifilesTestTarget(cb) {
 925     if (test("-d", PERF_MULTIFILES_TARGET_DIR)) {
 926         process.nextTick(cb);
 927     } else {
 928         mkdir("-p", PERF_MULTIFILES_TARGET_DIR);
 929         echo("Downloading the repository of multi-files performance test target.");
 930         exec(`git clone -b v1.10.3 --depth 1 https://github.com/eslint/eslint.git "${PERF_MULTIFILES_TARGET_DIR}"`, { silent: true }, cb);
 931     }
 932 }
 933
 934 /**
 935  * Creates a config file to use performance tests.
 936  * This config is turning all core rules on.
 937  * @returns {void}
 938  */
 939 function createConfigForPerformanceTest() {
 940     const content = [
 941         "root: true",
 942         "env:",
 943         "    node: true",
 944         "    es6: true",
 945         "rules:"
 946     ];
 947
 948     for (const [ruleId] of builtinRules) {
 949         content.push(`    ${ruleId}: 1`);
 950     }
 951
 952     content.join("\n").to(PERF_ESLINTRC);
 953 }
 954
 955 /**
 956  * Calculates the time for each run for performance
 957  * @param {string} cmd cmd
 958  * @param {int} runs Total number of runs to do
 959  * @param {int} runNumber Current run number
 960  * @param {int[]} results Collection results from each run
 961  * @param {Function} cb Function to call when everything is done
 962  * @returns {int[]} calls the cb with all the results
 963  * @private
 964  */
 965 function time(cmd, runs, runNumber, results, cb) {
 966     const start = process.hrtime();
 967
 968     exec(cmd, { maxBuffer: 64 * 1024 * 1024, silent: true }, (code, stdout, stderr) => {
 969         const diff = process.hrtime(start),
 970             actual = (diff[0] * 1e3 + diff[1] / 1e6); // ms
 971
 972         if (code) {
 973             echo(`  Performance Run #${runNumber} failed.`);
 974             if (stdout) {
 975                 echo(`STDOUT:\n${stdout}\n\n`);
 976             }
 977
 978             if (stderr) {
 979                 echo(`STDERR:\n${stderr}\n\n`);
 980             }
 981             return cb(null);
 982         }
 983
 984         results.push(actual);
 985         echo(`  Performance Run #${runNumber}:  %dms`, actual);
 986         if (runs > 1) {
 987             return time(cmd, runs - 1, runNumber + 1, results, cb);
 988         }
 989         return cb(results);
 990
 991     });
 992
 993 }
 994
 995 /**
 996  * Run a performance test.
 997  * @param {string} title A title.
 998  * @param {string} targets Test targets.
 999  * @param {number} multiplier A multiplier for limitation.
1000  * @param {Function} cb A callback function.
1001  * @returns {void}
1002  */
1003 function runPerformanceTest(title, targets, multiplier, cb) {
1004     const cpuSpeed = os.cpus()[0].speed,
1005         max = multiplier / cpuSpeed,
1006         cmd = `${ESLINT}--config "${PERF_ESLINTRC}" --no-eslintrc --no-ignore ${targets}`;
1007
1008     echo("");
1009     echo(title);
1010     echo("  CPU Speed is %d with multiplier %d", cpuSpeed, multiplier);
1011
1012     time(cmd, 5, 1, [], results => {
1013         if (!results || results.length === 0) { // No results? Something is wrong.
1014             throw new Error("Performance test failed.");
1015         }
1016
1017         results.sort((a, b) => a - b);
1018
1019         const median = results[~~(results.length / 2)];
1020
1021         echo("");
1022         if (median > max) {
1023             echo("  Performance budget exceeded: %dms (limit: %dms)", median, max);
1024         } else {
1025             echo("  Performance budget ok:  %dms (limit: %dms)", median, max);
1026         }
1027         echo("");
1028         cb();
1029     });
1030 }
1031
1032 /**
1033  * Run the load performance for eslint
1034  * @returns {void}
1035  * @private
1036  */
1037 function loadPerformance() {
1038     echo("");
1039     echo("Loading:");
1040
1041     const results = [];
1042
1043     for (let cnt = 0; cnt < 5; cnt++) {
1044         const loadPerfData = loadPerf({
1045             checkDependencies: false
1046         });
1047
1048         echo(`  Load performance Run #${cnt + 1}:  %dms`, loadPerfData.loadTime);
1049         results.push(loadPerfData.loadTime);
1050     }
1051
1052     results.sort((a, b) => a - b);
1053     const median = results[~~(results.length / 2)];
1054
1055     echo("");
1056     echo("  Load Performance median:  %dms", median);
1057     echo("");
1058 }
1059
1060 target.perf = function() {
1061     downloadMultifilesTestTarget(() => {
1062         createConfigForPerformanceTest();
1063
1064         loadPerformance();
1065
1066         runPerformanceTest(
1067             "Single File:",
1068             "tests/performance/jshint.js",
1069             PERF_MULTIPLIER,
1070             () => {
1071
1072                 // Count test target files.
1073                 const count = glob.sync(
1074                     process.platform === "win32"
1075                         ? PERF_MULTIFILES_TARGETS.slice(2).replace(/\\/gu, "/")
1076                         : PERF_MULTIFILES_TARGETS
1077                 ).length;
1078
1079                 runPerformanceTest(
1080                     `Multi Files (${count} files):`,
1081                     PERF_MULTIFILES_TARGETS,
1082                     3 * PERF_MULTIPLIER,
1083                     () => {}
1084                 );
1085             }
1086         );
1087     });
1088 };
1089
1090 target.generateRelease = generateRelease;
1091 target.generatePrerelease = ([prereleaseType]) => generatePrerelease(prereleaseType);
1092 target.publishRelease = publishRelease;