Gruntfile.js

   1 // This file is part of Moodle - http://moodle.org/
   2 //
   3 // Moodle is free software: you can redistribute it and/or modify
   4 // it under the terms of the GNU General Public License as published by
   5 // the Free Software Foundation, either version 3 of the License, or
   6 // (at your option) any later version.
   7 //
   8 // Moodle is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 // GNU General Public License for more details.
  12 //
  13 // You should have received a copy of the GNU General Public License
  14 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  15 /* jshint node: true, browser: false */
  16 /* eslint-env node */
  17
  18 /**
  19  * @copyright  2014 Andrew Nicols
  20  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  21  */
  22
  23 /**
  24  * Grunt configuration
  25  */
  26
  27 module.exports = function(grunt) {
  28     var path = require('path'),
  29         tasks = {},
  30         cwd = process.env.PWD || process.cwd(),
  31         async = require('async'),
  32         DOMParser = require('xmldom').DOMParser,
  33         xpath = require('xpath'),
  34         semver = require('semver'),
  35         watchman = require('fb-watchman'),
  36         watchmanClient = new watchman.Client(),
  37         gruntFilePath = process.cwd();
  38
  39     // Verify the node version is new enough.
  40     var expected = semver.validRange(grunt.file.readJSON('package.json').engines.node);
  41     var actual = semver.valid(process.version);
  42     if (!semver.satisfies(actual, expected)) {
  43         grunt.fail.fatal('Node version not satisfied. Require ' + expected + ', version installed: ' + actual);
  44     }
  45
  46     // Windows users can't run grunt in a subdirectory, so allow them to set
  47     // the root by passing --root=path/to/dir.
  48     if (grunt.option('root')) {
  49         var root = grunt.option('root');
  50         if (grunt.file.exists(__dirname, root)) {
  51             cwd = path.join(__dirname, root);
  52             grunt.log.ok('Setting root to ' + cwd);
  53         } else {
  54             grunt.fail.fatal('Setting root to ' + root + ' failed - path does not exist');
  55         }
  56     }
  57
  58     var files = null;
  59     if (grunt.option('files')) {
  60         // Accept a comma separated list of files to process.
  61         files = grunt.option('files').split(',');
  62     }
  63
  64     var inAMD = path.basename(cwd) == 'amd';
  65
  66     // Globbing pattern for matching all AMD JS source files.
  67     var amdSrc = [];
  68     if (inAMD) {
  69         amdSrc.push(cwd + "/src/*.js");
  70         amdSrc.push(cwd + "/src/**/*.js");
  71     } else {
  72         amdSrc.push("**/amd/src/*.js");
  73         amdSrc.push("**/amd/src/**/*.js");
  74     }
  75
  76     /**
  77      * Function to generate the destination for the uglify task
  78      * (e.g. build/file.min.js). This function will be passed to
  79      * the rename property of files array when building dynamically:
  80      * http://gruntjs.com/configuring-tasks#building-the-files-object-dynamically
  81      *
  82      * @param {String} destPath the current destination
  83      * @param {String} srcPath the  matched src path
  84      * @return {String} The rewritten destination path.
  85      */
  86     var babelRename = function(destPath, srcPath) {
  87         destPath = srcPath.replace('src', 'build');
  88         destPath = destPath.replace('.js', '.min.js');
  89         return destPath;
  90     };
  91
  92     /**
  93      * Find thirdpartylibs.xml and generate an array of paths contained within
  94      * them (used to generate ignore files and so on).
  95      *
  96      * @return {array} The list of thirdparty paths.
  97      */
  98     var getThirdPartyPathsFromXML = function() {
  99         var thirdpartyfiles = grunt.file.expand('*/**/thirdpartylibs.xml');
 100         var libs = ['node_modules/', 'vendor/'];
 101
 102         thirdpartyfiles.forEach(function(file) {
 103           var dirname = path.dirname(file);
 104
 105           var doc = new DOMParser().parseFromString(grunt.file.read(file));
 106           var nodes = xpath.select("/libraries/library/location/text()", doc);
 107
 108           nodes.forEach(function(node) {
 109             var lib = path.join(dirname, node.toString());
 110             if (grunt.file.isDir(lib)) {
 111                 // Ensure trailing slash on dirs.
 112                 lib = lib.replace(/\/?$/, '/');
 113             }
 114
 115             // Look for duplicate paths before adding to array.
 116             if (libs.indexOf(lib) === -1) {
 117                 libs.push(lib);
 118             }
 119           });
 120         });
 121         return libs;
 122     };
 123
 124     // Project configuration.
 125     grunt.initConfig({
 126         eslint: {
 127             // Even though warnings dont stop the build we don't display warnings by default because
 128             // at this moment we've got too many core warnings.
 129             options: {quiet: !grunt.option('show-lint-warnings')},
 130             amd: {src: files ? files : amdSrc},
 131             // Check YUI module source files.
 132             yui: {src: files ? files : ['**/yui/src/**/*.js', '!*/**/yui/src/*/meta/*.js']}
 133         },
 134         babel: {
 135             options: {
 136                 sourceMaps: true,
 137                 comments: false,
 138                 plugins: [
 139                     'transform-es2015-modules-amd-lazy',
 140                     // This plugin modifies the Babel transpiling for "export default"
 141                     // so that if it's used then only the exported value is returned
 142                     // by the generated AMD module.
 143                     //
 144                     // It also adds the Moodle plugin name to the AMD module definition
 145                     // so that it can be imported as expected in other modules.
 146                     path.resolve('babel-plugin-add-module-to-define.js'),
 147                     '@babel/plugin-syntax-dynamic-import',
 148                     '@babel/plugin-syntax-import-meta',
 149                     ['@babel/plugin-proposal-class-properties', {'loose': false}],
 150                     '@babel/plugin-proposal-json-strings'
 151                 ],
 152                 presets: [
 153                     ['minify', {
 154                         // This minification plugin needs to be disabled because it breaks the
 155                         // source map generation and causes invalid source maps to be output.
 156                         simplify: false,
 157                         builtIns: false
 158                     }],
 159                     ['@babel/preset-env', {
 160                         targets: {
 161                             browsers: [
 162                                 ">0.25%",
 163                                 "last 2 versions",
 164                                 "not ie <= 10",
 165                                 "not op_mini all",
 166                                 "not Opera > 0",
 167                                 "not dead"
 168                             ]
 169                         },
 170                         modules: false,
 171                         useBuiltIns: false
 172                     }]
 173                 ]
 174             },
 175             dist: {
 176                 files: [{
 177                     expand: true,
 178                     src: files ? files : amdSrc,
 179                     rename: babelRename
 180                 }]
 181             }
 182         },
 183         sass: {
 184             dist: {
 185                 files: {
 186                     "theme/boost/style/moodle.css": "theme/boost/scss/preset/default.scss",
 187                     "theme/classic/style/moodle.css": "theme/classic/scss/classicgrunt.scss"
 188                 }
 189             },
 190             options: {
 191                 includePaths: ["theme/boost/scss/", "theme/classic/scss/"]
 192             }
 193         },
 194         watch: {
 195             options: {
 196                 nospawn: true // We need not to spawn so config can be changed dynamically.
 197             },
 198             amd: {
 199                 files: ['**/amd/src/**/*.js'],
 200                 tasks: ['amd']
 201             },
 202             boost: {
 203                 files: ['**/theme/boost/scss/**/*.scss'],
 204                 tasks: ['scss']
 205             },
 206             rawcss: {
 207                 files: ['**/*.css', '**/theme/**/!(moodle.css|editor.css)'],
 208                 tasks: ['rawcss']
 209             },
 210             yui: {
 211                 files: ['**/yui/src/**/*.js'],
 212                 tasks: ['yui']
 213             },
 214             gherkinlint: {
 215                 files: ['**/tests/behat/*.feature'],
 216                 tasks: ['gherkinlint']
 217             }
 218         },
 219         shifter: {
 220             options: {
 221                 recursive: true,
 222                 paths: files ? files : [cwd]
 223             }
 224         },
 225         gherkinlint: {
 226             options: {
 227                 files: files ? files : ['**/tests/behat/*.feature'],
 228             }
 229         },
 230         stylelint: {
 231             scss: {
 232                 options: {syntax: 'scss'},
 233                 src: files ? files : ['*/**/*.scss']
 234             },
 235             css: {
 236                 src: files ? files : ['*/**/*.css'],
 237                 options: {
 238                     configOverrides: {
 239                         rules: {
 240                             // These rules have to be disabled in .stylelintrc for scss compat.
 241                             "at-rule-no-unknown": true,
 242                         }
 243                     }
 244                 }
 245             }
 246         }
 247     });
 248
 249     /**
 250      * Generate ignore files (utilising thirdpartylibs.xml data)
 251      */
 252     tasks.ignorefiles = function() {
 253       // An array of paths to third party directories.
 254       var thirdPartyPaths = getThirdPartyPathsFromXML();
 255       // Generate .eslintignore.
 256       var eslintIgnores = ['# Generated by "grunt ignorefiles"', '*/**/yui/src/*/meta/', '*/**/build/'].concat(thirdPartyPaths);
 257       grunt.file.write('.eslintignore', eslintIgnores.join('\n'));
 258       // Generate .stylelintignore.
 259       var stylelintIgnores = [
 260           '# Generated by "grunt ignorefiles"',
 261           '**/yui/build/*',
 262           'theme/boost/style/moodle.css',
 263           'theme/classic/style/moodle.css',
 264       ].concat(thirdPartyPaths);
 265       grunt.file.write('.stylelintignore', stylelintIgnores.join('\n'));
 266     };
 267
 268     /**
 269      * Shifter task. Is configured with a path to a specific file or a directory,
 270      * in the case of a specific file it will work out the right module to be built.
 271      *
 272      * Note that this task runs the invidiaul shifter jobs async (becase it spawns
 273      * so be careful to to call done().
 274      */
 275     tasks.shifter = function() {
 276         var done = this.async(),
 277             options = grunt.config('shifter.options');
 278
 279         // Run the shifter processes one at a time to avoid confusing output.
 280         async.eachSeries(options.paths, function(src, filedone) {
 281             var args = [];
 282             args.push(path.normalize(__dirname + '/node_modules/shifter/bin/shifter'));
 283
 284             // Always ignore the node_modules directory.
 285             args.push('--excludes', 'node_modules');
 286
 287             // Determine the most appropriate options to run with based upon the current location.
 288             if (grunt.file.isMatch('**/yui/**/*.js', src)) {
 289                 // When passed a JS file, build our containing module (this happen with
 290                 // watch).
 291                 grunt.log.debug('Shifter passed a specific JS file');
 292                 src = path.dirname(path.dirname(src));
 293                 options.recursive = false;
 294             } else if (grunt.file.isMatch('**/yui/src', src)) {
 295                 // When in a src directory --walk all modules.
 296                 grunt.log.debug('In a src directory');
 297                 args.push('--walk');
 298                 options.recursive = false;
 299             } else if (grunt.file.isMatch('**/yui/src/*', src)) {
 300                 // When in module, only build our module.
 301                 grunt.log.debug('In a module directory');
 302                 options.recursive = false;
 303             } else if (grunt.file.isMatch('**/yui/src/*/js', src)) {
 304                 // When in module src, only build our module.
 305                 grunt.log.debug('In a source directory');
 306                 src = path.dirname(src);
 307                 options.recursive = false;
 308             }
 309
 310             if (grunt.option('watch')) {
 311                 grunt.fail.fatal('The --watch option has been removed, please use `grunt watch` instead');
 312             }
 313
 314             // Add the stderr option if appropriate
 315             if (grunt.option('verbose')) {
 316                 args.push('--lint-stderr');
 317             }
 318
 319             if (grunt.option('no-color')) {
 320                 args.push('--color=false');
 321             }
 322
 323             var execShifter = function() {
 324
 325                 grunt.log.ok("Running shifter on " + src);
 326                 grunt.util.spawn({
 327                     cmd: "node",
 328                     args: args,
 329                     opts: {cwd: src, stdio: 'inherit', env: process.env}
 330                 }, function(error, result, code) {
 331                     if (code) {
 332                         grunt.fail.fatal('Shifter failed with code: ' + code);
 333                     } else {
 334                         grunt.log.ok('Shifter build complete.');
 335                         filedone();
 336                     }
 337                 });
 338             };
 339
 340             // Actually run shifter.
 341             if (!options.recursive) {
 342                 execShifter();
 343             } else {
 344                 // Check that there are yui modules otherwise shifter ends with exit code 1.
 345                 if (grunt.file.expand({cwd: src}, '**/yui/src/**/*.js').length > 0) {
 346                     args.push('--recursive');
 347                     execShifter();
 348                 } else {
 349                     grunt.log.ok('No YUI modules to build.');
 350                     filedone();
 351                 }
 352             }
 353         }, done);
 354     };
 355
 356     tasks.gherkinlint = function() {
 357         var done = this.async(),
 358             options = grunt.config('gherkinlint.options');
 359
 360         var args = grunt.file.expand(options.files);
 361         args.unshift(path.normalize(__dirname + '/node_modules/.bin/gherkin-lint'));
 362         grunt.util.spawn({
 363             cmd: 'node',
 364             args: args,
 365             opts: {stdio: 'inherit', env: process.env}
 366         }, function(error, result, code) {
 367             // Propagate the exit code.
 368             done(code === 0);
 369         });
 370     };
 371
 372     tasks.startup = function() {
 373         // Are we in a YUI directory?
 374         if (path.basename(path.resolve(cwd, '../../')) == 'yui') {
 375             grunt.task.run('yui');
 376         // Are we in an AMD directory?
 377         } else if (inAMD) {
 378             grunt.task.run('amd');
 379         } else {
 380             // Run them all!.
 381             grunt.task.run('css');
 382             grunt.task.run('js');
 383             grunt.task.run('gherkinlint');
 384         }
 385     };
 386
 387     /**
 388      * This is a wrapper task to handle the grunt watch command. It attempts to use
 389      * Watchman to monitor for file changes, if it's installed, because it's much faster.
 390      *
 391      * If Watchman isn't installed then it falls back to the grunt-contrib-watch file
 392      * watcher for backwards compatibility.
 393      */
 394     tasks.watch = function() {
 395         var watchTaskDone = this.async();
 396         var watchInitialised = false;
 397         var watchTaskQueue = {};
 398         var processingQueue = false;
 399
 400         // Grab the tasks and files that have been queued up and execute them.
 401         var processWatchTaskQueue = function() {
 402             if (!Object.keys(watchTaskQueue).length || processingQueue) {
 403                 // If there is nothing in the queue or we're already processing then wait.
 404                 return;
 405             }
 406
 407             processingQueue = true;
 408
 409             // Grab all tasks currently in the queue.
 410             var queueToProcess = watchTaskQueue;
 411             // Reset the queue.
 412             watchTaskQueue = {};
 413
 414             async.forEachSeries(
 415                 Object.keys(queueToProcess),
 416                 function(task, next) {
 417                     var files = queueToProcess[task];
 418                     var filesOption = '--files=' + files.join(',');
 419                     grunt.log.ok('Running task ' + task + ' for files ' + filesOption);
 420
 421                     // Spawn the task in a child process so that it doesn't kill this one
 422                     // if it failed.
 423                     grunt.util.spawn(
 424                         {
 425                             // Spawn with the grunt bin.
 426                             grunt: true,
 427                             // Run from current working dir and inherit stdio from process.
 428                             opts: {
 429                                 cwd: cwd,
 430                                 stdio: 'inherit'
 431                             },
 432                             args: [task, filesOption]
 433                         },
 434                         function(err, res, code) {
 435                             if (code !== 0) {
 436                                 // The grunt task failed.
 437                                 grunt.log.error(err);
 438                             }
 439
 440                             // Move on to the next task.
 441                             next();
 442                         }
 443                     );
 444                 },
 445                 function() {
 446                     // No longer processing.
 447                     processingQueue = false;
 448                     // Once all of the tasks are done then recurse just in case more tasks
 449                     // were queued while we were processing.
 450                     processWatchTaskQueue();
 451                 }
 452             );
 453         };
 454
 455         var watchConfig = grunt.config.get(['watch']);
 456         watchConfig = Object.keys(watchConfig).reduce(function(carry, key) {
 457             if (key == 'options') {
 458                 return carry;
 459             }
 460
 461             var value = watchConfig[key];
 462             var fileGlobs = value.files;
 463             var taskNames = value.tasks;
 464
 465             taskNames.forEach(function(taskName) {
 466                 carry[taskName] = fileGlobs;
 467             });
 468
 469             return carry;
 470         }, {});
 471
 472         watchmanClient.on('error', function(error) {
 473             // We have to add an error handler here and parse the error string because the
 474             // example way from the docs to check if Watchman is installed doesn't actually work!!
 475             // See: https://github.com/facebook/watchman/issues/509
 476             if (error.message.match('Watchman was not found')) {
 477                 // If watchman isn't installed then we should fallback to the other watch task.
 478                 grunt.log.ok('It is recommended that you install Watchman for better performance using the "watch" command.');
 479
 480                 // Fallback to the old grunt-contrib-watch task.
 481                 grunt.renameTask('watch-grunt', 'watch');
 482                 grunt.task.run(['watch']);
 483                 // This task is finished.
 484                 watchTaskDone(0);
 485             } else {
 486                 grunt.log.error(error);
 487                 // Fatal error.
 488                 watchTaskDone(1);
 489             }
 490         });
 491
 492         watchmanClient.on('subscription', function(resp) {
 493             if (resp.subscription !== 'grunt-watch') {
 494                 return;
 495             }
 496
 497             resp.files.forEach(function(file) {
 498                 grunt.log.ok('File changed: ' + file.name);
 499
 500                 var fullPath = cwd + '/' + file.name;
 501                 Object.keys(watchConfig).forEach(function(task) {
 502                     var fileGlobs = watchConfig[task];
 503                     var match = fileGlobs.every(function(fileGlob) {
 504                         return grunt.file.isMatch(fileGlob, fullPath);
 505                     });
 506                     if (match) {
 507                         // If we are watching a subdirectory then the file.name will be relative
 508                         // to that directory. However the grunt tasks  expect the file paths to be
 509                         // relative to the Gruntfile.js location so let's normalise them before
 510                         // adding them to the queue.
 511                         var relativePath = fullPath.replace(gruntFilePath + '/', '');
 512                         if (task in watchTaskQueue) {
 513                             if (!watchTaskQueue[task].includes(relativePath)) {
 514                                 watchTaskQueue[task] = watchTaskQueue[task].concat(relativePath);
 515                             }
 516                         } else {
 517                             watchTaskQueue[task] = [relativePath];
 518                         }
 519                     }
 520                 });
 521             });
 522
 523             processWatchTaskQueue();
 524         });
 525
 526         process.on('SIGINT', function() {
 527             // Let the user know that they may need to manually stop the Watchman daemon if they
 528             // no longer want it running.
 529             if (watchInitialised) {
 530                 grunt.log.ok('The Watchman daemon may still be running and may need to be stopped manually.');
 531             }
 532
 533             process.exit();
 534         });
 535
 536         // Initiate the watch on the current directory.
 537         watchmanClient.command(['watch-project', cwd], function(watchError, watchResponse) {
 538             if (watchError) {
 539                 grunt.log.error('Error initiating watch:', watchError);
 540                 watchTaskDone(1);
 541                 return;
 542             }
 543
 544             if ('warning' in watchResponse) {
 545                 grunt.log.error('warning: ', watchResponse.warning);
 546             }
 547
 548             var watch = watchResponse.watch;
 549             var relativePath = watchResponse.relative_path;
 550             watchInitialised = true;
 551
 552             watchmanClient.command(['clock', watch], function(clockError, clockResponse) {
 553                 if (clockError) {
 554                     grunt.log.error('Failed to query clock:', clockError);
 555                     watchTaskDone(1);
 556                     return;
 557                 }
 558
 559                 // Use the matching patterns specified in the watch config.
 560                 var matches = Object.keys(watchConfig).map(function(task) {
 561                     var fileGlobs = watchConfig[task];
 562                     var fileGlobMatches = fileGlobs.map(function(fileGlob) {
 563                         return ['match', fileGlob, 'wholename'];
 564                     });
 565
 566                     return ['allof'].concat(fileGlobMatches);
 567                 });
 568
 569                 var sub = {
 570                     expression: ["anyof"].concat(matches),
 571                     // Which fields we're interested in.
 572                     fields: ["name", "size", "type"],
 573                     // Add our time constraint.
 574                     since: clockResponse.clock
 575                 };
 576
 577                 if (relativePath) {
 578                     sub.relative_root = relativePath;
 579                 }
 580
 581                 watchmanClient.command(['subscribe', watch, 'grunt-watch', sub], function(subscribeError) {
 582                     if (subscribeError) {
 583                         // Probably an error in the subscription criteria.
 584                         grunt.log.error('failed to subscribe: ', subscribeError);
 585                         watchTaskDone(1);
 586                         return;
 587                     }
 588
 589                     grunt.log.ok('Listening for changes to files in ' + cwd);
 590                 });
 591             });
 592         });
 593     };
 594
 595     // On watch, we dynamically modify config to build only affected files. This
 596     // method is slightly complicated to deal with multiple changed files at once (copied
 597     // from the grunt-contrib-watch readme).
 598     var changedFiles = Object.create(null);
 599     var onChange = grunt.util._.debounce(function() {
 600         var files = Object.keys(changedFiles);
 601         grunt.config('eslint.amd.src', files);
 602         grunt.config('eslint.yui.src', files);
 603         grunt.config('shifter.options.paths', files);
 604         grunt.config('gherkinlint.options.files', files);
 605         grunt.config('babel.dist.files', [{expand: true, src: files, rename: babelRename}]);
 606         changedFiles = Object.create(null);
 607     }, 200);
 608
 609     grunt.event.on('watch', function(action, filepath) {
 610         changedFiles[filepath] = action;
 611         onChange();
 612     });
 613
 614     // Register NPM tasks.
 615     grunt.loadNpmTasks('grunt-contrib-uglify');
 616     grunt.loadNpmTasks('grunt-contrib-watch');
 617     grunt.loadNpmTasks('grunt-sass');
 618     grunt.loadNpmTasks('grunt-eslint');
 619     grunt.loadNpmTasks('grunt-stylelint');
 620     grunt.loadNpmTasks('grunt-babel');
 621
 622     // Rename the grunt-contrib-watch "watch" task because we're going to wrap it.
 623     grunt.renameTask('watch', 'watch-grunt');
 624
 625     // Register JS tasks.
 626     grunt.registerTask('shifter', 'Run Shifter against the current directory', tasks.shifter);
 627     grunt.registerTask('gherkinlint', 'Run gherkinlint against the current directory', tasks.gherkinlint);
 628     grunt.registerTask('ignorefiles', 'Generate ignore files for linters', tasks.ignorefiles);
 629     grunt.registerTask('watch', 'Run tasks on file changes', tasks.watch);
 630     grunt.registerTask('yui', ['eslint:yui', 'shifter']);
 631     grunt.registerTask('amd', ['eslint:amd', 'babel']);
 632     grunt.registerTask('js', ['amd', 'yui']);
 633
 634     // Register CSS taks.
 635     grunt.registerTask('css', ['stylelint:scss', 'sass', 'stylelint:css']);
 636     grunt.registerTask('scss', ['stylelint:scss', 'sass']);
 637     grunt.registerTask('rawcss', ['stylelint:css']);
 638
 639     // Register the startup task.
 640     grunt.registerTask('startup', 'Run the correct tasks for the current directory', tasks.startup);
 641
 642     // Register the default task.
 643     grunt.registerTask('default', ['startup']);
 644 };