1 // This file is part of Moodle - http://moodle.org/
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.
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.
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 */
19 * @copyright 2014 Andrew Nicols
20 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
28 module
.exports
= function(grunt
) {
29 var path
= require('path'),
31 cwd
= process
.env
.PWD
|| process
.cwd(),
32 async
= require('async'),
33 DOMParser
= require('xmldom').DOMParser
,
34 xpath
= require('xpath'),
35 semver
= require('semver'),
36 watchman
= require('fb-watchman'),
37 watchmanClient
= new watchman
.Client(),
38 gruntFilePath
= process
.cwd();
40 // Verify the node version is new enough.
41 var expected
= semver
.validRange(grunt
.file
.readJSON('package.json').engines
.node
);
42 var actual
= semver
.valid(process
.version
);
43 if (!semver
.satisfies(actual
, expected
)) {
44 grunt
.fail
.fatal('Node version not satisfied. Require ' + expected
+ ', version installed: ' + actual
);
47 // Windows users can't run grunt in a subdirectory, so allow them to set
48 // the root by passing --root=path/to
/dir
.
49 if (grunt
.option('root')) {
50 var root
= grunt
.option('root');
51 if (grunt
.file
.exists(__dirname
, root
)) {
52 cwd
= path
.join(__dirname
, root
);
53 grunt
.log
.ok('Setting root to ' + cwd
);
55 grunt
.fail
.fatal('Setting root to ' + root
+ ' failed - path does not exist');
60 if (grunt
.option('files')) {
61 // Accept a comma separated list of files to process.
62 files
= grunt
.option('files').split(',');
65 var inAMD
= path
.basename(cwd
) == 'amd';
67 // Globbing pattern for matching all AMD JS source files.
70 amdSrc
.push(cwd
+ "/src/*.js");
71 amdSrc
.push(cwd
+ "/src/**/*.js");
73 amdSrc
.push("**/amd/src/*.js");
74 amdSrc
.push("**/amd/src/**/*.js");
78 * Function to generate the destination for the uglify task
79 * (e.g. build/file.min.js). This function will be passed to
80 * the rename property of files array when building dynamically:
81 * http://gruntjs.com/configuring-tasks#building-the-files-object-dynamically
83 * @param {String} destPath the current destination
84 * @param {String} srcPath the matched src path
85 * @return {String} The rewritten destination path.
87 var babelRename
= function(destPath
, srcPath
) {
88 destPath
= srcPath
.replace('src', 'build');
89 destPath
= destPath
.replace('.js', '.min.js');
94 * Find thirdpartylibs.xml and generate an array of paths contained within
95 * them (used to generate ignore files and so on).
97 * @return {array} The list of thirdparty paths.
99 var getThirdPartyPathsFromXML
= function() {
100 var thirdpartyfiles
= grunt
.file
.expand('*/**/thirdpartylibs.xml');
101 var libs
= ['node_modules/', 'vendor/'];
103 thirdpartyfiles
.forEach(function(file
) {
104 var dirname
= path
.dirname(file
);
106 var doc
= new DOMParser().parseFromString(grunt
.file
.read(file
));
107 var nodes
= xpath
.select("/libraries/library/location/text()", doc
);
109 nodes
.forEach(function(node
) {
110 var lib
= path
.join(dirname
, node
.toString());
111 if (grunt
.file
.isDir(lib
)) {
112 // Ensure trailing slash on dirs.
113 lib
= lib
.replace(/\/?$/, '/');
116 // Look for duplicate paths before adding to array.
117 if (libs.indexOf(lib) === -1) {
125 // Project configuration.
128 // Even though warnings dont stop the build we don't display warnings by
default because
129 // at this moment we've got too many core warnings.
130 options
: {quiet
: !grunt
.option('show-lint-warnings')},
131 amd
: {src
: files
? files
: amdSrc
},
132 // Check YUI module source files.
133 yui
: {src
: files
? files
: ['**/yui/src/**/*.js', '!*/**/yui/src/*/meta/*.js']}
140 'transform-es2015-modules-amd-lazy',
141 'system-import-transformer',
142 // This plugin modifies the Babel transpiling for "export default"
143 // so that if it's used then only the exported value is returned
144 // by the generated AMD module.
146 // It also adds the Moodle plugin name to the AMD module definition
147 // so that it can be imported as expected in other modules.
148 path
.resolve('babel-plugin-add-module-to-define.js'),
149 '@babel/plugin-syntax-dynamic-import',
150 '@babel/plugin-syntax-import-meta',
151 ['@babel/plugin-proposal-class-properties', {'loose': false}],
152 '@babel/plugin-proposal-json-strings'
156 // This minification plugin needs to be disabled because it breaks the
157 // source map generation and causes invalid source maps to be output.
161 ['@babel/preset-env', {
180 src
: files
? files
: amdSrc
,
188 "theme/boost/style/moodle.css": "theme/boost/scss/preset/default.scss",
189 "theme/classic/style/moodle.css": "theme/classic/scss/classicgrunt.scss"
193 includePaths
: ["theme/boost/scss/", "theme/classic/scss/"]
198 nospawn
: true // We need not to spawn so config can be changed dynamically.
201 files
: ['**/amd/src/**/*.js'],
205 files
: ['**/theme/boost/scss/**/*.scss'],
209 files
: ['**/*.css', '**/theme/**/!(moodle.css|editor.css)'],
213 files
: ['**/yui/src/**/*.js'],
217 files
: ['**/tests/behat/*.feature'],
218 tasks
: ['gherkinlint']
224 paths
: files
? files
: [cwd
]
229 files
: files
? files
: ['**/tests/behat/*.feature'],
234 options
: {syntax
: 'scss'},
235 src
: files
? files
: ['*/**/*.scss']
238 src
: files
? files
: ['*/**/*.css'],
242 // These rules have to be disabled in .stylelintrc for scss compat.
243 "at-rule-no-unknown": true,
252 * Generate ignore files (utilising thirdpartylibs.xml data)
254 tasks
.ignorefiles
= function() {
255 // An array of paths to third party directories.
256 var thirdPartyPaths
= getThirdPartyPathsFromXML();
257 // Generate .eslintignore.
258 var eslintIgnores
= ['# Generated by "grunt ignorefiles"', '*/**/yui/src/*/meta/', '*/**/build/'].concat(thirdPartyPaths
);
259 grunt
.file
.write('.eslintignore', eslintIgnores
.join('\n'));
260 // Generate .stylelintignore.
261 var stylelintIgnores
= [
262 '# Generated by "grunt ignorefiles"',
264 'theme/boost/style/moodle.css',
265 'theme/classic/style/moodle.css',
266 ].concat(thirdPartyPaths
);
267 grunt
.file
.write('.stylelintignore', stylelintIgnores
.join('\n'));
271 * Shifter task. Is configured with a path to a specific file or a directory,
272 * in the case of a specific file it will work out the right module to be built.
274 * Note that this task runs the invidiaul shifter jobs async (becase it spawns
275 * so be careful to to call done().
277 tasks
.shifter
= function() {
278 var done
= this.async(),
279 options
= grunt
.config('shifter.options');
281 // Run the shifter processes one at a time to avoid confusing output.
282 async
.eachSeries(options
.paths
, function(src
, filedone
) {
284 args
.push(path
.normalize(__dirname
+ '/node_modules/shifter/bin/shifter'));
286 // Always ignore the node_modules directory.
287 args
.push('--excludes', 'node_modules');
289 // Determine the most appropriate options to run with based upon the current location.
290 if (grunt
.file
.isMatch('**/yui/**/*.js', src
)) {
291 // When passed a JS file, build our containing module (this happen with
293 grunt
.log
.debug('Shifter passed a specific JS file');
294 src
= path
.dirname(path
.dirname(src
));
295 options
.recursive
= false;
296 } else if (grunt
.file
.isMatch('**/yui/src', src
)) {
297 // When in a src directory --walk all modules.
298 grunt
.log
.debug('In a src directory');
300 options
.recursive
= false;
301 } else if (grunt
.file
.isMatch('**/yui/src/*', src
)) {
302 // When in module, only build our module.
303 grunt
.log
.debug('In a module directory');
304 options
.recursive
= false;
305 } else if (grunt
.file
.isMatch('**/yui/src/*/js', src
)) {
306 // When in module src, only build our module.
307 grunt
.log
.debug('In a source directory');
308 src
= path
.dirname(src
);
309 options
.recursive
= false;
312 if (grunt
.option('watch')) {
313 grunt
.fail
.fatal('The --watch option has been removed, please use `grunt watch` instead');
316 // Add the stderr option if appropriate
317 if (grunt
.option('verbose')) {
318 args
.push('--lint-stderr');
321 if (grunt
.option('no-color')) {
322 args
.push('--color=false');
325 var execShifter
= function() {
327 grunt
.log
.ok("Running shifter on " + src
);
331 opts
: {cwd
: src
, stdio
: 'inherit', env
: process
.env
}
332 }, function(error
, result
, code
) {
334 grunt
.fail
.fatal('Shifter failed with code: ' + code
);
336 grunt
.log
.ok('Shifter build complete.');
342 // Actually run shifter.
343 if (!options
.recursive
) {
346 // Check that there are yui modules otherwise shifter ends with exit code 1.
347 if (grunt
.file
.expand({cwd
: src
}, '**/yui/src/**/*.js').length
> 0) {
348 args
.push('--recursive');
351 grunt
.log
.ok('No YUI modules to build.');
358 tasks
.gherkinlint
= function() {
359 var done
= this.async(),
360 options
= grunt
.config('gherkinlint.options');
362 var args
= grunt
.file
.expand(options
.files
);
363 args
.unshift(path
.normalize(__dirname
+ '/node_modules/.bin/gherkin-lint'));
367 opts
: {stdio
: 'inherit', env
: process
.env
}
368 }, function(error
, result
, code
) {
369 // Propagate the exit code.
374 tasks
.startup
= function() {
375 // Are we in a YUI directory?
376 if (path
.basename(path
.resolve(cwd
, '../../')) == 'yui') {
377 grunt
.task
.run('yui');
378 // Are we in an AMD directory?
380 grunt
.task
.run('amd');
383 grunt
.task
.run('css');
384 grunt
.task
.run('js');
385 grunt
.task
.run('gherkinlint');
390 * This is a wrapper task to handle the grunt watch command. It attempts to use
391 * Watchman to monitor for file changes, if it's installed, because it's much faster.
393 * If Watchman isn't installed then it falls back to the grunt-contrib-watch file
394 * watcher for backwards compatibility.
396 tasks
.watch
= function() {
397 var watchTaskDone
= this.async();
398 var watchInitialised
= false;
399 var watchTaskQueue
= {};
400 var processingQueue
= false;
402 // Grab the tasks and files that have been queued up and execute them.
403 var processWatchTaskQueue
= function() {
404 if (!Object
.keys(watchTaskQueue
).length
|| processingQueue
) {
405 // If there is nothing in the queue or we're already processing then wait.
409 processingQueue
= true;
411 // Grab all tasks currently in the queue.
412 var queueToProcess
= watchTaskQueue
;
417 Object
.keys(queueToProcess
),
418 function(task
, next
) {
419 var files
= queueToProcess
[task
];
420 var filesOption
= '--files=' + files
.join(',');
421 grunt
.log
.ok('Running task ' + task
+ ' for files ' + filesOption
);
423 // Spawn the task in a child process so that it doesn't kill this one
427 // Spawn with the grunt bin.
429 // Run from current working dir and inherit stdio from process.
434 args
: [task
, filesOption
]
436 function(err
, res
, code
) {
438 // The grunt task failed.
439 grunt
.log
.error(err
);
442 // Move on to the next task.
448 // No longer processing.
449 processingQueue
= false;
450 // Once all of the tasks are done then recurse just in case more tasks
451 // were queued while we were processing.
452 processWatchTaskQueue();
457 var watchConfig
= grunt
.config
.get(['watch']);
458 watchConfig
= Object
.keys(watchConfig
).reduce(function(carry
, key
) {
459 if (key
== 'options') {
463 var value
= watchConfig
[key
];
464 var fileGlobs
= value
.files
;
465 var taskNames
= value
.tasks
;
467 taskNames
.forEach(function(taskName
) {
468 carry
[taskName
] = fileGlobs
;
474 watchmanClient
.on('error', function(error
) {
475 // We have to add an error handler here and parse the error string because the
476 // example way from the docs to check if Watchman is installed doesn't actually work!!
477 // See: https://github.com/facebook
/watchman/issues/509
478 if (error
.message
.match('Watchman was not found')) {
479 // If watchman isn't installed then we should fallback to the other watch task.
480 grunt
.log
.ok('It is recommended that you install Watchman for better performance using the "watch" command.');
482 // Fallback to the old grunt-contrib-watch task.
483 grunt
.renameTask('watch-grunt', 'watch');
484 grunt
.task
.run(['watch']);
485 // This task is finished.
488 grunt
.log
.error(error
);
494 watchmanClient
.on('subscription', function(resp
) {
495 if (resp
.subscription
!== 'grunt-watch') {
499 resp
.files
.forEach(function(file
) {
500 grunt
.log
.ok('File changed: ' + file
.name
);
502 var fullPath
= cwd
+ '/' + file
.name
;
503 Object
.keys(watchConfig
).forEach(function(task
) {
504 var fileGlobs
= watchConfig
[task
];
505 var match
= fileGlobs
.every(function(fileGlob
) {
506 return grunt
.file
.isMatch(fileGlob
, fullPath
);
509 // If we are watching a subdirectory then the file.name will be relative
510 // to that directory. However the grunt tasks expect the file paths to be
511 // relative to the Gruntfile.js location so let's normalise them before
512 // adding them to the queue.
513 var relativePath
= fullPath
.replace(gruntFilePath
+ '/', '');
514 if (task
in watchTaskQueue
) {
515 if (!watchTaskQueue
[task
].includes(relativePath
)) {
516 watchTaskQueue
[task
] = watchTaskQueue
[task
].concat(relativePath
);
519 watchTaskQueue
[task
] = [relativePath
];
525 processWatchTaskQueue();
528 process
.on('SIGINT', function() {
529 // Let the user know that they may need to manually stop the Watchman daemon if they
530 // no longer want it running.
531 if (watchInitialised
) {
532 grunt
.log
.ok('The Watchman daemon may still be running and may need to be stopped manually.');
538 // Initiate the watch on the current directory.
539 watchmanClient
.command(['watch-project', cwd
], function(watchError
, watchResponse
) {
541 grunt
.log
.error('Error initiating watch:', watchError
);
546 if ('warning' in watchResponse
) {
547 grunt
.log
.error('warning: ', watchResponse
.warning
);
550 var watch
= watchResponse
.watch
;
551 var relativePath
= watchResponse
.relative_path
;
552 watchInitialised
= true;
554 watchmanClient
.command(['clock', watch
], function(clockError
, clockResponse
) {
556 grunt
.log
.error('Failed to query clock:', clockError
);
561 // Use the matching patterns specified in the watch config.
562 var matches
= Object
.keys(watchConfig
).map(function(task
) {
563 var fileGlobs
= watchConfig
[task
];
564 var fileGlobMatches
= fileGlobs
.map(function(fileGlob
) {
565 return ['match', fileGlob
, 'wholename'];
568 return ['allof'].concat(fileGlobMatches
);
572 expression
: ["anyof"].concat(matches
),
573 // Which fields we're interested in.
574 fields
: ["name", "size", "type"],
575 // Add our time constraint.
576 since
: clockResponse
.clock
580 /* eslint-disable camelcase */
581 sub
.relative_root
= relativePath
;
584 watchmanClient
.command(['subscribe', watch
, 'grunt-watch', sub
], function(subscribeError
) {
585 if (subscribeError
) {
586 // Probably an error in the subscription criteria.
587 grunt
.log
.error('failed to subscribe: ', subscribeError
);
592 grunt
.log
.ok('Listening for changes to files in ' + cwd
);
598 // On watch, we dynamically modify config to build only affected files. This
599 // method is slightly complicated to deal with multiple changed files at once (copied
600 // from the grunt-contrib-watch readme).
601 var changedFiles
= Object
.create(null);
602 var onChange
= grunt
.util
._
.debounce(function() {
603 var files
= Object
.keys(changedFiles
);
604 grunt
.config('eslint.amd.src', files
);
605 grunt
.config('eslint.yui.src', files
);
606 grunt
.config('shifter.options.paths', files
);
607 grunt
.config('gherkinlint.options.files', files
);
608 grunt
.config('babel.dist.files', [{expand
: true, src
: files
, rename
: babelRename
}]);
609 changedFiles
= Object
.create(null);
612 grunt
.event
.on('watch', function(action
, filepath
) {
613 changedFiles
[filepath
] = action
;
617 // Register NPM tasks.
618 grunt
.loadNpmTasks('grunt-contrib-uglify');
619 grunt
.loadNpmTasks('grunt-contrib-watch');
620 grunt
.loadNpmTasks('grunt-sass');
621 grunt
.loadNpmTasks('grunt-eslint');
622 grunt
.loadNpmTasks('grunt-stylelint');
623 grunt
.loadNpmTasks('grunt-babel');
625 // Rename the grunt-contrib-watch "watch" task because we're going to wrap it.
626 grunt
.renameTask('watch', 'watch-grunt');
628 // Register JS tasks.
629 grunt
.registerTask('shifter', 'Run Shifter against the current directory', tasks
.shifter
);
630 grunt
.registerTask('gherkinlint', 'Run gherkinlint against the current directory', tasks
.gherkinlint
);
631 grunt
.registerTask('ignorefiles', 'Generate ignore files for linters', tasks
.ignorefiles
);
632 grunt
.registerTask('watch', 'Run tasks on file changes', tasks
.watch
);
633 grunt
.registerTask('yui', ['eslint:yui', 'shifter']);
634 grunt
.registerTask('amd', ['eslint:amd', 'babel']);
635 grunt
.registerTask('js', ['amd', 'yui']);
637 // Register CSS taks.
638 grunt
.registerTask('css', ['stylelint:scss', 'sass', 'stylelint:css']);
639 grunt
.registerTask('scss', ['stylelint:scss', 'sass']);
640 grunt
.registerTask('rawcss', ['stylelint:css']);
642 // Register the startup task.
643 grunt
.registerTask('startup', 'Run the correct tasks for the current directory', tasks
.startup
);
645 // Register the default task.
646 grunt
.registerTask('default', ['startup']);