first commit

.grunt/babel-plugin-add-module-to-define.js

@@ -0,0 +1,169 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * This is a babel plugin to add the Moodle module names to the AMD modules
+ * as part of the transpiling process.
+ *
+ * In addition it will also add a return statement for the default export if the
+ * module is using default exports. This is a highly specific Moodle thing because
+ * we're transpiling to AMD and none of the existing Babel 7 plugins work correctly.
+ *
+ * This will fix the issue where an ES6 module using "export default Foo" will be
+ * transpiled into an AMD module that returns {default: Foo}; Instead it will now
+ * just simply return Foo.
+ *
+ * Note: This means all other named exports in that module are ignored and won't be
+ * exported.
+ *
+ * @copyright  2018 Ryan Wyllie <ryan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+"use strict";
+/* eslint-env node */
+
+module.exports = ({template, types}) => {
+    const fs = require('fs');
+    const path = require('path');
+    const cwd = process.cwd();
+    const ComponentList = require(path.join(process.cwd(), '.grunt', 'components.js'));
+
+    /**
+     * Search the list of components that match the given file name
+     * and return the Moodle component for that file, if found.
+     *
+     * Throw an exception if no matching component is found.
+     *
+     * @throws {Error}
+     * @param {string} searchFileName The file name to look for.
+     * @return {string} Moodle component
+     */
+    function getModuleNameFromFileName(searchFileName) {
+        searchFileName = fs.realpathSync(searchFileName);
+        const relativeFileName = searchFileName.replace(`${cwd}${path.sep}`, '').replace(/\\/g, '/');
+        const [componentPath, file] = relativeFileName.split('/amd/src/');
+        const fileName = file.replace('.js', '');
+
+        // Check subsystems first which require an exact match.
+        const componentName = ComponentList.getComponentFromPath(componentPath);
+        if (componentName) {
+            return `${componentName}/${fileName}`;
+        }
+
+        // This matches the previous PHP behaviour that would throw an exception
+        // if it couldn't parse an AMD file.
+        throw new Error(`Unable to find module name for ${searchFileName} (${componentPath}::${file}}`);
+    }
+
+    /**
+     * This is heavily inspired by the babel-plugin-add-module-exports plugin.
+     * See: https://github.com/59naga/babel-plugin-add-module-exports
+     *
+     * This is used when we detect a module using "export default Foo;" to make
+     * sure the transpiled code just returns Foo directly rather than an object
+     * with the default property (i.e. {default: Foo}).
+     *
+     * Note: This means that we can't support modules that combine named exports
+     * with a default export.
+     *
+     * @param {String} path
+     * @param {String} exportObjectName
+     */
+    function addModuleExportsDefaults(path, exportObjectName) {
+        const rootPath = path.findParent(path => {
+            return path.key === 'body' || !path.parentPath;
+        });
+
+        // HACK: `path.node.body.push` instead of path.pushContainer(due doesn't work in Plugin.post).
+        // This is hardcoded to work specifically with AMD.
+        rootPath.node.body.push(template(`return ${exportObjectName}.default`)());
+    }
+
+    return {
+        pre() {
+            this.seenDefine = false;
+            this.addedReturnForDefaultExport = false;
+        },
+        visitor: {
+            // Plugin ordering is only respected if we visit the "Program" node.
+            // See: https://babeljs.io/docs/en/plugins.html#plugin-preset-ordering
+            //
+            // We require this to run after the other AMD module transformation so
+            // let's visit the "Program" node.
+            Program: {
+                exit(path) {
+                    path.traverse({
+                        CallExpression(path) {
+                            // If we find a "define" function call.
+                            if (!this.seenDefine && path.get('callee').isIdentifier({name: 'define'})) {
+                                // We only want to modify the first instance of define that we find.
+                                this.seenDefine = true;
+
+                                // Get the Moodle component for the file being processed.
+                                var moduleName = getModuleNameFromFileName(this.file.opts.filename);
+
+                                // The function signature of `define()` is:
+                                // define = function (name, deps, callback) {...}
+                                // Ensure that if the moduel supplied its own name that it is replaced.
+                                if (path.node.arguments.length > 0) {
+                                    // Ensure that there is only one name.
+                                    if (path.node.arguments[0].type === 'StringLiteral') {
+                                        // eslint-disable-next-line
+                                        console.log(`Replacing module name '${path.node.arguments[0].extra.rawValue}' with ${moduleName}`);
+                                        path.node.arguments.shift();
+                                    }
+                                }
+
+                                // Add the module name as the first argument to the define function.
+                                path.node.arguments.unshift(types.stringLiteral(moduleName));
+                                // Add a space after the define function in the built file so that previous versions
+                                // of Moodle will not try to add the module name to the file when it's being served
+                                // by PHP. This forces the regex in PHP to not match for this file.
+                                path.node.callee.name = 'define ';
+                            }
+
+                            // Check for any Object.defineProperty('exports', 'default') calls.
+                            if (!this.addedReturnForDefaultExport && path.get('callee').matchesPattern('Object.defineProperty')) {
+                                const [identifier, prop] = path.get('arguments');
+                                const objectName = identifier.get('name').node;
+                                const propertyName = prop.get('value').node;
+
+                                if ((objectName === 'exports' || objectName === '_exports') && propertyName === 'default') {
+                                    addModuleExportsDefaults(path, objectName);
+                                    this.addedReturnForDefaultExport = true;
+                                }
+                            }
+                        },
+                        AssignmentExpression(path) {
+                            // Check for an exports.default assignments.
+                            if (
+                                !this.addedReturnForDefaultExport &&
+                                (
+                                    path.get('left').matchesPattern('exports.default') ||
+                                    path.get('left').matchesPattern('_exports.default')
+                                )
+                            ) {
+                                const objectName = path.get('left.object.name').node;
+                                addModuleExportsDefaults(path, objectName);
+                                this.addedReturnForDefaultExport = true;
+                            }
+                        }
+                    }, this);
+                }
+            }
+        }
+    };
+};

.grunt/components.js

@@ -0,0 +1,394 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Helper functions for working with Moodle component names, directories, and sources.
+ *
+ * @copyright  2019 Andrew Nicols <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+"use strict";
+/* eslint-env node */
+
+/** @var {Object} A list of subsystems in Moodle */
+const componentData = {};
+
+/**
+ * Load details of all moodle modules.
+ *
+ * @returns {object}
+ */
+const fetchComponentData = () => {
+    const fs = require('fs');
+    const path = require('path');
+    const glob = require('glob');
+    const gruntFilePath = process.cwd();
+
+    if (!Object.entries(componentData).length) {
+        componentData.subsystems = {};
+        componentData.pathList = [];
+
+        // Fetch the component definiitions from the distributed JSON file.
+        const components = JSON.parse(fs.readFileSync(`${gruntFilePath}/lib/components.json`));
+
+        // Build the list of moodle subsystems.
+        componentData.subsystems.lib = 'core';
+        componentData.pathList.push(process.cwd() + path.sep + 'lib');
+        for (const [component, thisPath] of Object.entries(components.subsystems)) {
+            if (thisPath) {
+                // Prefix "core_" to the front of the subsystems.
+                componentData.subsystems[thisPath] = `core_${component}`;
+                componentData.pathList.push(process.cwd() + path.sep + thisPath);
+            }
+        }
+
+        // The list of components incldues the list of subsystems.
+        componentData.components = componentData.subsystems;
+
+        // Go through each of the plugintypes.
+        Object.entries(components.plugintypes).forEach(([pluginType, pluginTypePath]) => {
+            // We don't allow any code in this place..?
+            glob.sync(`${pluginTypePath}/*/version.php`).forEach(versionPath => {
+                const componentPath = fs.realpathSync(path.dirname(versionPath));
+                const componentName = path.basename(componentPath);
+                const frankenstyleName = `${pluginType}_${componentName}`;
+                componentData.components[`${pluginTypePath}/${componentName}`] = frankenstyleName;
+                componentData.pathList.push(componentPath);
+
+                // Look for any subplugins.
+                const subPluginConfigurationFile = `${componentPath}/db/subplugins.json`;
+                if (fs.existsSync(subPluginConfigurationFile)) {
+                    const subpluginList = JSON.parse(fs.readFileSync(fs.realpathSync(subPluginConfigurationFile)));
+
+                    Object.entries(subpluginList.plugintypes).forEach(([subpluginType, subpluginTypePath]) => {
+                        glob.sync(`${subpluginTypePath}/*/version.php`).forEach(versionPath => {
+                            const componentPath = fs.realpathSync(path.dirname(versionPath));
+                            const componentName = path.basename(componentPath);
+                            const frankenstyleName = `${subpluginType}_${componentName}`;
+
+                            componentData.components[`${subpluginTypePath}/${componentName}`] = frankenstyleName;
+                            componentData.pathList.push(componentPath);
+                        });
+                    });
+                }
+            });
+        });
+
+    }
+
+    return componentData;
+};
+
+/**
+ * Get the list of component paths.
+ *
+ * @param   {string} relativeTo
+ * @returns {array}
+ */
+const getComponentPaths = (relativeTo = '') => fetchComponentData().pathList.map(componentPath => {
+    return componentPath.replace(relativeTo, '');
+});
+
+/**
+ * Get the list of paths to build AMD sources.
+ *
+ * @returns {Array}
+ */
+const getAmdSrcGlobList = () => {
+    const globList = [];
+    fetchComponentData().pathList.forEach(componentPath => {
+        globList.push(`${componentPath}/amd/src/*.js`);
+        globList.push(`${componentPath}/amd/src/**/*.js`);
+    });
+
+    return globList;
+};
+
+/**
+ * Get the list of paths to build YUI sources.
+ *
+ * @param {String} relativeTo
+ * @returns {Array}
+ */
+const getYuiSrcGlobList = relativeTo => {
+    const globList = [];
+    fetchComponentData().pathList.forEach(componentPath => {
+        const relativeComponentPath = componentPath.replace(relativeTo, '');
+        globList.push(`${relativeComponentPath}/yui/src/**/*.js`);
+    });
+
+    return globList;
+};
+
+/**
+ * Get the list of paths to thirdpartylibs.xml.
+ *
+ * @param {String} relativeTo
+ * @returns {Array}
+ */
+const getThirdPartyLibsList = relativeTo => {
+    const fs = require('fs');
+    const path = require('path');
+
+    return fetchComponentData().pathList
+        .map(componentPath => path.relative(relativeTo, componentPath) + '/thirdpartylibs.xml')
+        .map(componentPath => componentPath.replace(/\\/g, '/'))
+        .filter(path => fs.existsSync(path))
+        .sort();
+};
+
+/**
+ * Get the list of thirdparty library paths.
+ *
+ * @returns {array}
+ */
+const getThirdPartyPaths = () => {
+    const DOMParser = require('@xmldom/xmldom').DOMParser;
+    const fs = require('fs');
+    const path = require('path');
+    const xpath = require('xpath');
+
+    const thirdpartyfiles = getThirdPartyLibsList(fs.realpathSync('./'));
+    const libs = ['node_modules/', 'vendor/'];
+
+    const addLibToList = lib => {
+        if (!lib.match('\\*') && fs.statSync(lib).isDirectory()) {
+            // Ensure trailing slash on dirs.
+            lib = lib.replace(/\/?$/, '/');
+        }
+
+        // Look for duplicate paths before adding to array.
+        if (libs.indexOf(lib) === -1) {
+            libs.push(lib);
+        }
+    };
+
+    thirdpartyfiles.forEach(function(file) {
+        const dirname = path.dirname(file);
+
+        const xmlContent = fs.readFileSync(file, 'utf8');
+        const doc = new DOMParser().parseFromString(xmlContent);
+        const nodes = xpath.select("/libraries/library/location/text()", doc);
+
+        nodes.forEach(function(node) {
+            let lib = path.posix.join(dirname, node.toString());
+            addLibToList(lib);
+        });
+    });
+
+    return libs;
+
+};
+
+/**
+ * Find the name of the component matching the specified path.
+ *
+ * @param {String} path
+ * @returns {String|null} Name of matching component.
+ */
+const getComponentFromPath = path => {
+    const componentList = fetchComponentData().components;
+
+    if (componentList.hasOwnProperty(path)) {
+        return componentList[path];
+    }
+
+    return null;
+};
+
+/**
+ * Check whether the supplied path, relative to the Gruntfile.js, is in a known component.
+ *
+ * @param {String} checkPath The path to check. This can be with either Windows, or Linux directory separators.
+ * @returns {String|null}
+ */
+const getOwningComponentDirectory = checkPath => {
+    const path = require('path');
+
+    // Fetch all components into a reverse sorted array.
+    // This ensures that components which are within the directory of another component match first.
+    const pathList = Object.keys(fetchComponentData().components).sort().reverse();
+    for (const componentPath of pathList) {
+        // If the componentPath is the directory being checked, it will be empty.
+        // If the componentPath is a parent of the directory being checked, the relative directory will not start with ..
+        if (!path.relative(componentPath, checkPath).startsWith('..')) {
+            return componentPath;
+        }
+    }
+
+    return null;
+};
+
+/**
+ * Get the latest tag in a remote GitHub repository.
+ *
+ * @param {string} url The remote repository.
+ * @returns {Array}
+ */
+const getRepositoryTags = async(url) => {
+    const gtr = require('git-tags-remote');
+    try {
+        const tags = await gtr.get(url);
+        if (tags !== undefined) {
+            return tags;
+        }
+    } catch (error) {
+        return [];
+    }
+    return [];
+};
+
+/**
+ * Get the list of thirdparty libraries that could be upgraded.
+ *
+ * @returns {Array}
+ */
+const getThirdPartyLibsUpgradable = async() => {
+    const libraries = getThirdPartyLibsData().filter((library) => !!library.repository);
+    const upgradableLibraries = [];
+    const versionCompare = (a, b) => {
+        if (a === b) {
+            return 0;
+        }
+
+        const aParts = a.split('.');
+        const bParts = b.split('.');
+
+        for (let i = 0; i < Math.min(aParts.length, bParts.length); i++) {
+            const aPart = parseInt(aParts[i], 10);
+            const bPart = parseInt(bParts[i], 10);
+            if (aPart > bPart) {
+                // 1.1.0 > 1.0.9
+                return 1;
+            } else if (aPart < bPart) {
+                // 1.0.9 < 1.1.0
+                return -1;
+            } else {
+                // Same version.
+                continue;
+            }
+        }
+
+        if (aParts.length > bParts.length) {
+            // 1.0.1 > 1.0
+            return 1;
+        }
+
+        // 1.0 < 1.0.1
+        return -1;
+    };
+
+    for (let library of libraries) {
+        upgradableLibraries.push(
+            getRepositoryTags(library.repository).then((tagMap) => {
+                library.version = library.version.replace(/^v/, '');
+                const currentVersion = library.version.replace(/moodle-/, '');
+                const currentMajorVersion = library.version.split('.')[0];
+                const tags = [...tagMap]
+                    .map((tagData) => tagData[0])
+                    .filter((tag) => !tag.match(/(alpha|beta|rc)/))
+                    .map((tag) => tag.replace(/^v/, ''))
+                    .sort((a, b) => versionCompare(b, a));
+                if (!tags.length) {
+                    library.warning = "Unable to find any comparable tags.";
+                    return library;
+                }
+
+                library.latestVersion = tags[0];
+                tags.some((tag) => {
+                    if (!tag) {
+                        return false;
+                    }
+
+                    // See if the version part matches.
+                    const majorVersion = tag.split('.')[0];
+                    if (majorVersion === currentMajorVersion) {
+                        library.latestSameMajorVersion = tag;
+                        return true;
+                    }
+                    return false;
+                });
+
+
+                if (versionCompare(currentVersion, library.latestVersion) > 0) {
+                    // Moodle somehow has a newer version than the latest version.
+                    library.warning = `Newer version found: ${currentVersion} > ${library.latestVersion} for ${library.name}`;
+                    return library;
+                }
+
+
+                if (library.version !== library.latestVersion) {
+                    // Delete version and add it again at the end of the array. That way, current and new will stay closer.
+                    delete library.version;
+                    library.version = currentVersion;
+                    return library;
+                }
+                return null;
+            })
+        );
+    }
+
+    return (await Promise.all(upgradableLibraries)).filter((library) => !!library);
+};
+
+/**
+ * Get the list of thirdparty libraries.
+ *
+ * @returns {Array}
+ */
+const getThirdPartyLibsData = () => {
+    const DOMParser = require('@xmldom/xmldom').DOMParser;
+    const fs = require('fs');
+    const xpath = require('xpath');
+    const path = require('path');
+
+    const libraryList = [];
+    const libraryFields = [
+        'location',
+        'name',
+        'version',
+        'repository',
+    ];
+
+    const thirdpartyfiles = getThirdPartyLibsList(fs.realpathSync('./'));
+    thirdpartyfiles.forEach(function(libraryPath) {
+        const xmlContent = fs.readFileSync(libraryPath, 'utf8');
+        const doc = new DOMParser().parseFromString(xmlContent);
+        const libraries = xpath.select("/libraries/library", doc);
+        for (const library of libraries) {
+            const libraryData = [];
+            for (const field of libraryFields) {
+                libraryData[field] = xpath.select(`${field}/text()`, library)?.toString();
+            }
+            libraryData.location = path.join(path.dirname(libraryPath), libraryData.location);
+            libraryList.push(libraryData);
+        }
+    });
+
+    return libraryList.sort((a, b) => a.location.localeCompare(b.location));
+};
+
+module.exports = {
+    fetchComponentData,
+    getAmdSrcGlobList,
+    getComponentFromPath,
+    getComponentPaths,
+    getOwningComponentDirectory,
+    getYuiSrcGlobList,
+    getThirdPartyLibsList,
+    getThirdPartyPaths,
+    getThirdPartyLibsUpgradable,
+};

.grunt/jsdoc/README.md

@@ -0,0 +1,19 @@
+# Moodle JavaScript Documentation
+
+```
+                                 .-..-.
+   _____                         | || |
+  /____/-.---_  .---.  .---.  .-.| || | .---.
+  | |  _   _  |/  _  \/  _  \/  _  || |/  __ \
+  * | | | | | || |_| || |_| || |_| || || |___/
+    |_| |_| |_|\_____/\_____/\_____||_|\_____)
+
+Moodle - the world's open source learning platform
+
+```
+
+## About
+This generated documentation includes API documentation for JavaScript written in the AMD and ES2015 module formats within Moodle.
+
+## Related information
+See [https://moodledev.io](https://moodledev.io) for other related Developer Documentation.

.grunt/jsdoc/jsdoc.conf.js

@@ -0,0 +1,131 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Helper functions for working with Moodle component names, directories, and sources.
+ *
+ * @copyright  2019 Andrew Nicols <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+"use strict";
+/* eslint-env node */
+
+// Do not include any plugins as stanard.
+const plugins = [];
+
+plugins.push('plugins/markdown');
+
+/**
+ * Get the source configuration.
+ *
+ * @return {Object}
+ */
+const getSource = () => {
+    const glob = require('glob');
+    const path = require('path');
+    const ComponentList = require(path.resolve('.grunt/components.js'));
+    const thirdPartyPaths = ComponentList.getThirdPartyPaths();
+
+    const source = {
+        include: [],
+        includePattern: ".+\\.js$",
+    };
+
+    let includeList = [];
+
+    ComponentList.getAmdSrcGlobList().forEach(async pattern => {
+        includeList.push(...glob.sync(pattern));
+    });
+
+    const cwdLength = process.cwd().length + 1;
+    includeList.forEach(path => {
+        if (source.include.indexOf(path) !== -1) {
+            // Ensure no duplicates.
+            return;
+        }
+
+        const relPath = path.substring(cwdLength);
+        if (thirdPartyPaths.indexOf(relPath) !== -1) {
+            return;
+        }
+
+        source.include.push(path);
+    });
+
+    source.include.push('.grunt/jsdoc/README.md');
+    return source;
+};
+
+const tags = {
+    // Allow the use of unknown tags.
+    // We have a lot of legacy uses of these.
+    allowUnknownTags: true,
+
+    // We make use of jsdoc and closure dictionaries as standard.
+    dictionaries: [
+        'jsdoc',
+        'closure',
+    ],
+};
+
+// Template configuraiton.
+const templates = {
+    cleverLinks: false,
+    monospaceLinks: false,
+};
+
+module.exports = {
+    opts: {
+        destination: "./jsdoc/",
+        template: "node_modules/docdash",
+    },
+    plugins,
+    recurseDepth: 10,
+    source: getSource(),
+    sourceType: 'module',
+    tags,
+    templates,
+    docdash: {
+        collapse: true,
+        search: true,
+        sort: true,
+        sectionOrder: [
+            "Namespaces",
+            "Modules",
+            "Events",
+            "Classes",
+            "Externals",
+            "Mixins",
+            "Tutorials",
+            "Interfaces"
+        ],
+        "menu": {
+            "Developer Docs": {
+                href: "https://moodledev.io",
+                target: "_blank",
+                "class": "menu-item",
+                id: "devdocs"
+            },
+            "MDN Docs": {
+                href: "https://developer.mozilla.org/en-US/docs/Web/JavaScript",
+                target: "_blank",
+                "class": "menu-item",
+                id: "mdndocs",
+            },
+        },
+        typedefs: true,
+    },
+};

.grunt/tasks/componentlibrary.js

@@ -0,0 +1,142 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * Component Library build tasks.
+ *
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+
+    /**
+     * Get a child path of the component library.
+     *
+     * @param   {string} path
+     * @returns {string}
+     */
+    const getCLPath = path => `admin/tool/componentlibrary/${path}`;
+
+    /**
+     * Get a spawn handler.
+     *
+     * This is a generic function to write the spawn output, and then to exit if required and mark the async task as
+     * complete.
+     *
+     * @param   {Promise} done
+     * @returns {function}
+     */
+    const getSpawnHandler = done => (error, result, code) => {
+        grunt.log.write(result);
+
+        if (error) {
+            grunt.log.error(result.stdout);
+            process.exit(code);
+        }
+        done();
+    };
+
+    /**
+     * Spawn a function against Node with the provided args.
+     *
+     * @param   {array} args
+     * @returns {object}
+     */
+    const spawnNodeCall = (args) => grunt.util.spawn({
+        cmd: 'node',
+        args,
+    }, getSpawnHandler(grunt.task.current.async()));
+
+    /**
+     * Build the docs using Hugo.
+     *
+     * @returns {Object} Reference to the spawned task
+     */
+    const docsBuild = () => spawnNodeCall([
+        'node_modules/hugo-bin/cli.js',
+        '--config', getCLPath('config.yml'),
+        '--cleanDestinationDir',
+    ]);
+
+    /**
+     * Build the docs index using the hugo-lunr-indexer.
+     *
+     * @returns {Object} Reference to the spawned task
+     */
+    const indexBuild = () => spawnNodeCall([
+        'node_modules/hugo-lunr-indexer/bin/hli.js',
+        '-i', getCLPath('content/**'),
+        '-o', getCLPath('hugo/site/data/my-index.json'),
+        '-l', 'yaml',
+        '-d', '---',
+    ]);
+
+    /**
+     * Build the hugo CSS.
+     *
+     * @returns {Object} Reference to the spawned task
+     */
+    const cssBuild = () => spawnNodeCall([
+        'node_modules/sass/sass.js',
+        '--style', 'expanded',
+        '--source-map',
+        '--embed-sources',
+        '--precision', 6,
+        '--load-path', process.cwd(),
+        getCLPath('hugo/scss/docs.scss'),
+        getCLPath('hugo/dist/css/docs.css'),
+    ]);
+
+    // Register the various component library tasks.
+    grunt.registerTask('componentlibrary:docsBuild', 'Build the component library', docsBuild);
+    grunt.registerTask('componentlibrary:cssBuild', 'Build the component library', cssBuild);
+    grunt.registerTask('componentlibrary:indexBuild', 'Build the component library', indexBuild);
+    grunt.registerTask('componentlibrary', 'Build the component library', [
+        'componentlibrary:docsBuild',
+        'componentlibrary:cssBuild',
+        'componentlibrary:indexBuild',
+    ]);
+
+    grunt.config.merge({
+        watch: {
+            componentLibraryDocs: {
+                files: [
+                    getCLPath('content/**/*.md'),
+                    getCLPath('hugo'),
+                ],
+                tasks: ['componentlibrary:docsBuild', 'componentlibrary:indexBuild'],
+            },
+            componentLibraryCSS: {
+                files: [
+                    getCLPath('hugo/scss/**/*.scss'),
+                    'hugo',
+                ],
+                tasks: ['componentlibrary:cssBuild'],
+            },
+        },
+    });
+
+    // Add the 'componentlibrary' task as a startup task.
+    grunt.moodleEnv.startupTasks.push('componentlibrary');
+
+    return {
+        docsBuild,
+        cssBuild,
+        indexBuild,
+    };
+};

.grunt/tasks/eslint.js

@@ -0,0 +1,64 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+    const files = grunt.moodleEnv.files;
+
+    // Project configuration.
+    grunt.config.merge({
+        eslint: {
+            // Even though warnings dont stop the build we don't display warnings by default because
+            // at this moment we've got too many core warnings.
+            // To display warnings call: grunt eslint --show-lint-warnings
+            // To fail on warnings call: grunt eslint --max-lint-warnings=0
+            // Also --max-lint-warnings=-1 can be used to display warnings but not fail.
+            options: {
+                quiet: (!grunt.option('show-lint-warnings')) && (typeof grunt.option('max-lint-warnings') === 'undefined'),
+                maxWarnings: ((typeof grunt.option('max-lint-warnings') !== 'undefined') ? grunt.option('max-lint-warnings') : -1)
+            },
+
+            // Check AMD src files.
+            amd: {src: files ? files : grunt.moodleEnv.amdSrc},
+
+            // Check YUI module source files.
+            yui: {src: files ? files : grunt.moodleEnv.yuiSrc},
+        },
+    });
+
+    grunt.loadNpmTasks('grunt-eslint');
+
+    // On watch, we dynamically modify config to build only affected files. This
+    // method is slightly complicated to deal with multiple changed files at once (copied
+    // from the grunt-contrib-watch readme).
+    let changedFiles = Object.create(null);
+    const onChange = grunt.util._.debounce(function() {
+        const files = Object.keys(changedFiles);
+        grunt.config('eslint.amd.src', files);
+        grunt.config('eslint.yui.src', files);
+        changedFiles = Object.create(null);
+    }, 200);
+
+    grunt.event.on('watch', (action, filepath) => {
+        changedFiles[filepath] = action;
+        onChange();
+    });
+};

.grunt/tasks/gherkinlint.js

@@ -0,0 +1,92 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+    /**
+     * Get the list of feature files to pass to the gherkin linter.
+     *
+     * @returns {Array}
+     */
+    const getGherkinLintTargets = () => {
+        if (grunt.moodleEnv.files) {
+            // Specific files were requested. Only check these.
+            return grunt.moodleEnv.files;
+        }
+
+        if (grunt.moodleEnv.inComponent) {
+            return [`${grunt.moodleEnv.runDir}/tests/behat/*.feature`];
+        }
+
+        return ['**/tests/behat/*.feature'];
+    };
+
+    const handler = function() {
+        const done = this.async();
+        const options = grunt.config('gherkinlint.options');
+
+        // Grab the gherkin-lint linter and required scaffolding.
+        const linter = require('gherkin-lint/dist/linter.js');
+        const featureFinder = require('gherkin-lint/dist/feature-finder.js');
+        const configParser = require('gherkin-lint/dist/config-parser.js');
+        const formatter = require('gherkin-lint/dist/formatters/stylish.js');
+
+        // Run the linter.
+        return linter.lint(
+            featureFinder.getFeatureFiles(grunt.file.expand(options.files)),
+            configParser.getConfiguration(configParser.defaultConfigFileName)
+        )
+        .then(results => {
+            // Print the results out uncondtionally.
+            formatter.printResults(results);
+
+            return results;
+        })
+        .then(results => {
+            // Report on the results.
+            // The done function takes a bool whereby a falsey statement causes the task to fail.
+            return results.every(result => result.errors.length === 0);
+        })
+        .then(done); // eslint-disable-line promise/no-callback-in-promise
+    };
+
+    grunt.registerTask('gherkinlint', 'Run gherkinlint against the current directory', handler);
+
+    grunt.config.set('gherkinlint', {
+        options: {
+            files: getGherkinLintTargets(),
+        }
+    });
+
+    grunt.config.merge({
+        watch: {
+            gherkinlint: {
+                files: [grunt.moodleEnv.inComponent ? 'tests/behat/*.feature' : '**/tests/behat/*.feature'],
+                tasks: ['gherkinlint'],
+            },
+        },
+    });
+
+    // Add the 'gherkinlint' task as a startup task.
+    grunt.moodleEnv.startupTasks.push('gherkinlint');
+
+    return handler;
+};

.grunt/tasks/ignorefiles.js

@@ -0,0 +1,100 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+
+    /**
+     * Generate the PHPCS configuration.
+     *
+     * @param {Object} thirdPartyPaths
+     */
+    const phpcsIgnore = (thirdPartyPaths) => {
+        const {toXML} = require('jstoxml');
+
+        const config = {
+            _name: 'ruleset',
+            _attrs: {
+                name: "MoodleCore",
+            },
+            _content: [
+                {
+                    rule: {
+                        _attrs: {
+                            ref: './phpcs.xml.dist',
+                        },
+                    },
+                },
+            ],
+        };
+
+        thirdPartyPaths.forEach(library => {
+            config._content.push({
+                'exclude-pattern': library,
+            });
+        });
+
+        grunt.file.write('phpcs.xml', toXML(config, {
+            header: true,
+            indent: '  ',
+        }) + "\n");
+    };
+
+    /**
+     * Generate ignore files (utilising thirdpartylibs.xml data)
+     */
+    const handler = function() {
+        const path = require('path');
+        const ComponentList = require(path.join(process.cwd(), '.grunt', 'components.js'));
+
+        // An array of paths to third party directories.
+        const thirdPartyPaths = ComponentList.getThirdPartyPaths();
+
+        // Generate .eslintignore.
+        const eslintIgnores = [
+            '# Generated by "grunt ignorefiles"',
+            // Do not ignore the .grunt directory.
+            '!/.grunt',
+
+            // Ignore all yui/src meta directories and build directories.
+            '*/**/yui/src/*/meta/',
+            '*/**/build/',
+        ].concat(thirdPartyPaths);
+        grunt.file.write('.eslintignore', eslintIgnores.join('\n') + '\n');
+
+        // Generate .stylelintignore.
+        const stylelintIgnores = [
+            '# Generated by "grunt ignorefiles"',
+            '**/yui/build/*',
+            'theme/boost/style/moodle.css',
+            'theme/classic/style/moodle.css',
+            'jsdoc/styles/*.css',
+            'admin/tool/componentlibrary/hugo/dist/css/docs.css',
+        ].concat(thirdPartyPaths);
+        grunt.file.write('.stylelintignore', stylelintIgnores.join('\n') + '\n');
+
+        phpcsIgnore(thirdPartyPaths);
+    };
+
+    grunt.registerTask('ignorefiles', 'Generate ignore files for linters', handler);
+
+    return handler;
+};

.grunt/tasks/javascript.js

@@ -0,0 +1,215 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Function to generate the destination for the minification task
+ * (e.g. build/file.min.js). This function will be passed to
+ * the rename property of files array when building dynamically:
+ * http://gruntjs.com/configuring-tasks#building-the-files-object-dynamically
+ *
+ * @param {String} destPath the current destination
+ * @param {String} srcPath the  matched src path
+ * @return {String} The rewritten destination path.
+ */
+const babelRename = function(destPath, srcPath) {
+    destPath = srcPath.replace(`amd/src`, `amd/build`);
+    destPath = destPath.replace(/\.js$/, '.min.js');
+    return destPath;
+};
+
+module.exports = grunt => {
+    // Load the Ignorefiles tasks.
+    require('./ignorefiles')(grunt);
+
+    // Load the Shifter tasks.
+    require('./shifter')(grunt);
+
+    // Load ESLint.
+    require('./eslint')(grunt);
+
+    // Load jsconfig.
+    require('./jsconfig')(grunt);
+
+    // Load JSDoc.
+    require('./jsdoc')(grunt);
+
+    const path = require('path');
+
+    // Register JS tasks.
+    grunt.registerTask('yui', ['eslint:yui', 'shifter']);
+    grunt.registerTask('amd', ['ignorefiles', 'eslint:amd', 'rollup']);
+    grunt.registerTask('js', ['amd', 'yui']);
+
+    // Register NPM tasks.
+    grunt.loadNpmTasks('grunt-contrib-watch');
+    grunt.loadNpmTasks('grunt-rollup');
+
+    const babelTransform = require('@babel/core').transform;
+    const babel = (options = {}) => {
+        return {
+            name: 'babel',
+
+            transform: (code, id) => {
+                grunt.log.debug(`Transforming ${id}`);
+                options.filename = id;
+                const transformed = babelTransform(code, options);
+
+                return {
+                    code: transformed.code,
+                    map: transformed.map
+                };
+            }
+        };
+    };
+
+    // Note: We have to use a rate limit plugin here because rollup runs all tasks asynchronously and in parallel.
+    // When we kick off a full run, if we kick off a rollup of every file this will fork-bomb the machine.
+    // To work around this we use a concurrent Promise queue based on the number of available processors.
+    const rateLimit = () => {
+        const queue = [];
+        let queueRunner;
+
+        const startQueue = () => {
+            if (queueRunner) {
+                return;
+            }
+
+            queueRunner = setTimeout(() => {
+                const limit = Math.max(1, require('os').cpus().length / 2);
+                grunt.log.debug(`Starting rollup with queue size of ${limit}`);
+                runQueue(limit);
+            }, 100);
+        };
+
+        // The queue runner will run the next `size` items in the queue.
+        const runQueue = (size = 1) => {
+            queue.splice(0, size).forEach(resolve => {
+                grunt.log.debug(`Item resolved. Kicking off next one.`);
+                resolve();
+            });
+        };
+
+        return {
+            name: 'ratelimit',
+
+            // The options hook is run in parallel.
+            // We can return an unresolved Promise which is queued for later resolution.
+            options: async(options) => {
+                return new Promise(resolve => {
+                    queue.push(resolve);
+                    startQueue();
+                    return options;
+                });
+            },
+
+            // When an item in the queue completes, start the next item in the queue.
+            generateBundle: (options, bundle) => {
+                grunt.log.debug(`Finished output phase for ${Object.keys(bundle).join(', ')}`);
+                runQueue();
+            },
+        };
+    };
+
+    const terser = require('rollup-plugin-terser').terser;
+    grunt.config.merge({
+        rollup: {
+            options: {
+                format: 'esm',
+                dir: 'output',
+                sourcemap: true,
+                treeshake: false,
+                context: 'window',
+                plugins: [
+                    rateLimit(),
+                    babel({
+                        sourceMaps: true,
+                        comments: false,
+                        compact: false,
+                        plugins: [
+                            'transform-es2015-modules-amd-lazy',
+                            'system-import-transformer',
+                            // This plugin modifies the Babel transpiling for "export default"
+                            // so that if it's used then only the exported value is returned
+                            // by the generated AMD module.
+                            //
+                            // It also adds the Moodle plugin name to the AMD module definition
+                            // so that it can be imported as expected in other modules.
+                            path.resolve('.grunt/babel-plugin-add-module-to-define.js')
+                        ],
+                        presets: [
+                            ['@babel/preset-env', {
+                                modules: false,
+                                useBuiltIns: false
+                            }]
+                        ]
+                    }),
+
+                    terser({
+                        // Do not mangle variables.
+                        // Makes debugging easier.
+                        mangle: false,
+                    }),
+                ],
+            },
+            dist: {
+                files: [{
+                    expand: true,
+                    src: grunt.moodleEnv.files ? grunt.moodleEnv.files : grunt.moodleEnv.amdSrc,
+                    rename: babelRename
+                }],
+            },
+        },
+    });
+
+    grunt.config.merge({
+        watch: {
+            amd: {
+                files: grunt.moodleEnv.inComponent
+                    ? ['amd/src/*.js', 'amd/src/**/*.js']
+                    : ['**/amd/src/**/*.js'],
+                tasks: ['amd']
+            },
+        },
+    });
+
+    // Add the 'js' task as a startup task.
+    grunt.moodleEnv.startupTasks.push('js');
+
+    // On watch, we dynamically modify config to build only affected files. This
+    // method is slightly complicated to deal with multiple changed files at once (copied
+    // from the grunt-contrib-watch readme).
+    let changedFiles = Object.create(null);
+    const onChange = grunt.util._.debounce(function() {
+        const files = Object.keys(changedFiles);
+        grunt.config('rollup.dist.files', [{expand: true, src: files, rename: babelRename}]);
+        changedFiles = Object.create(null);
+    }, 200);
+
+    grunt.event.on('watch', function(action, filepath) {
+        changedFiles[filepath] = action;
+        onChange();
+    });
+
+    return {
+        babelRename,
+    };
+};

.grunt/tasks/jsconfig.js

@@ -0,0 +1,53 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2022 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+const configuration = {
+    compilerOptions: {
+        baseUrl: ".",
+        paths: {
+        },
+        target: "es2015",
+        allowSyntheticDefaultImports: false,
+    },
+    exclude: [
+        "node_modules",
+    ],
+    include: [],
+};
+
+module.exports = (grunt) => {
+    const handler = () => {
+        const jsconfigData = Object.assign({}, configuration);
+
+        const path = require('path');
+        const {fetchComponentData} = require(path.join(process.cwd(), '.grunt', 'components.js'));
+
+        const componentData = fetchComponentData().components;
+        for (const [thisPath, component] of Object.entries(componentData)) {
+            jsconfigData.compilerOptions.paths[`${component}/*`] = [`${thisPath}/amd/src/*`];
+            jsconfigData.include.push(`${thisPath}/amd/src/**/*`);
+        }
+
+        grunt.file.write('jsconfig.json', JSON.stringify(jsconfigData, null, "  ") + "\n");
+    };
+    grunt.registerTask('jsconfig', 'Generate a jsconfig configuration compatible with the LSP', handler);
+};

.grunt/tasks/jsdoc.js

@@ -0,0 +1,52 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = (grunt) => {
+    const path = require('path');
+
+    grunt.registerTask('jsdoc', 'Generate JavaScript documentation using jsdoc', function() {
+        const done = this.async();
+        const configuration = path.resolve('.grunt/jsdoc/jsdoc.conf.js');
+
+        grunt.util.spawn({
+            cmd: 'jsdoc',
+            args: [
+                '--configure',
+                configuration,
+            ]
+        }, function(error, result, code) {
+            if (result.stdout) {
+                grunt.log.write(result.stdout);
+            }
+
+            if (result.stderr) {
+                grunt.log.error(result.stderr);
+            }
+            if (error) {
+                grunt.fail.fatal(`JSDoc failed with error code ${code}`);
+            } else {
+                grunt.log.write('JSDoc completed successfully'.green);
+            }
+            done();
+        });
+    });
+};

.grunt/tasks/sass.js

@@ -0,0 +1,40 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+    grunt.loadNpmTasks('grunt-sass');
+
+    grunt.config.merge({
+        sass: {
+            dist: {
+                files: {
+                    "theme/boost/style/moodle.css": "theme/boost/scss/preset/default.scss",
+                    "theme/classic/style/moodle.css": "theme/classic/scss/classicgrunt.scss"
+                }
+            },
+            options: {
+                implementation: require('sass'),
+                includePaths: ["theme/boost/scss/", "theme/classic/scss/"]
+            }
+        },
+    });
+};

.grunt/tasks/shifter.js

@@ -0,0 +1,155 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/* eslint-env node */
+
+module.exports = grunt => {
+    /**
+     * Shifter task. Is configured with a path to a specific file or a directory,
+     * in the case of a specific file it will work out the right module to be built.
+     *
+     * Note that this task runs the invidiaul shifter jobs async (becase it spawns
+     * so be careful to to call done().
+     */
+    const handler = function() {
+        const done = this.async();
+        const options = grunt.config('shifter.options');
+        const async = require('async');
+        const path = require('path');
+
+        // Run the shifter processes one at a time to avoid confusing output.
+        async.eachSeries(options.paths, function(src, filedone) {
+            var args = [];
+            args.push(path.normalize(process.cwd() + '/node_modules/shifter/bin/shifter'));
+
+            // Always ignore the node_modules directory.
+            args.push('--excludes', 'node_modules');
+
+            // Determine the most appropriate options to run with based upon the current location.
+            if (grunt.file.isMatch('**/yui/**/*.js', src)) {
+                // When passed a JS file, build our containing module (this happen with
+                // watch).
+                grunt.log.debug('Shifter passed a specific JS file');
+                src = path.dirname(path.dirname(src));
+                options.recursive = false;
+            } else if (grunt.file.isMatch('**/yui/src', src)) {
+                // When in a src directory --walk all modules.
+                grunt.log.debug('In a src directory');
+                args.push('--walk');
+                options.recursive = false;
+            } else if (grunt.file.isMatch('**/yui/src/*', src)) {
+                // When in module, only build our module.
+                grunt.log.debug('In a module directory');
+                options.recursive = false;
+            } else if (grunt.file.isMatch('**/yui/src/*/js', src)) {
+                // When in module src, only build our module.
+                grunt.log.debug('In a source directory');
+                src = path.dirname(src);
+                options.recursive = false;
+            }
+
+            if (grunt.option('watch')) {
+                grunt.fail.fatal('The --watch option has been removed, please use `grunt watch` instead');
+            }
+
+            // Add the stderr option if appropriate
+            if (grunt.option('verbose')) {
+                args.push('--lint-stderr');
+            }
+
+            if (grunt.option('no-color')) {
+                args.push('--color=false');
+            }
+
+            var execShifter = function() {
+
+                grunt.log.ok("Running shifter on " + src);
+                grunt.util.spawn({
+                    cmd: "node",
+                    args: args,
+                    opts: {cwd: src, stdio: 'inherit', env: process.env}
+                }, function(error, result, code) {
+                    if (code) {
+                        grunt.fail.fatal('Shifter failed with code: ' + code);
+                    } else {
+                        grunt.log.ok('Shifter build complete.');
+                        filedone();
+                    }
+                });
+            };
+
+            // Actually run shifter.
+            if (!options.recursive) {
+                execShifter();
+            } else {
+                // Check that there are yui modules otherwise shifter ends with exit code 1.
+                if (grunt.file.expand({cwd: src}, '**/yui/src/**/*.js').length > 0) {
+                    args.push('--recursive');
+                    execShifter();
+                } else {
+                    grunt.log.ok('No YUI modules to build.');
+                    filedone();
+                }
+            }
+        }, done);
+    };
+
+    // Register the shifter task.
+    grunt.registerTask('shifter', 'Run Shifter against the current directory', handler);
+
+    // Configure it.
+    grunt.config.set('shifter', {
+        options: {
+            recursive: true,
+            // Shifter takes a relative path.
+            paths: grunt.moodleEnv.files ? grunt.moodleEnv.files : [grunt.moodleEnv.runDir]
+        }
+    });
+
+    grunt.config.merge({
+        watch: {
+            yui: {
+                files: grunt.moodleEnv.inComponent
+                    ? ['yui/src/*.json', 'yui/src/**/*.js']
+                    : ['**/yui/src/**/*.js'],
+                tasks: ['yui']
+            },
+        },
+    });
+
+    // On watch, we dynamically modify config to build only affected files. This
+    // method is slightly complicated to deal with multiple changed files at once (copied
+    // from the grunt-contrib-watch readme).
+    let changedFiles = Object.create(null);
+    const onChange = grunt.util._.debounce(function() {
+        const files = Object.keys(changedFiles);
+        grunt.config('shifter.options.paths', files);
+        changedFiles = Object.create(null);
+    }, 200);
+
+    grunt.event.on('watch', (action, filepath) => {
+        changedFiles[filepath] = action;
+        onChange();
+    });
+
+    return handler;
+};

.grunt/tasks/startup.js

@@ -0,0 +1,46 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+    /**
+     * Generate ignore files (utilising thirdpartylibs.xml data)
+     */
+    const handler = function() {
+        const path = require('path');
+
+        // Are we in a YUI directory?
+        if (path.basename(path.resolve(grunt.moodleEnv.cwd, '../../')) == 'yui') {
+            grunt.task.run('yui');
+        // Are we in an AMD directory?
+        } else if (grunt.moodleEnv.inAMD) {
+            grunt.task.run('amd');
+        } else {
+            // Run all of the requested startup tasks.
+            grunt.moodleEnv.startupTasks.forEach(taskName => grunt.task.run(taskName));
+        }
+    };
+
+    // Register the startup task.
+    grunt.registerTask('startup', 'Run the correct tasks for the current directory', handler);
+
+    return handler;
+};

.grunt/tasks/style.js

@@ -0,0 +1,35 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+    // Load the ignorefiles tasks.
+    require('./ignorefiles')(grunt);
+
+    // Load the Style Lint tasks.
+    require('./stylelint')(grunt);
+
+    // Load the SASS tasks.
+    require('./sass')(grunt);
+
+    // Add the 'css' task as a startup task.
+    grunt.moodleEnv.startupTasks.push('css');
+};

.grunt/tasks/stylelint.js

@@ -0,0 +1,187 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2021 Andrew Nicols
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+
+    const getCssConfigForFiles = files => {
+        return {
+            stylelint: {
+                css: {
+                    // Use a fully-qualified path.
+                    src: files,
+                    options: {
+                        quietDeprecationWarnings: true,
+                        configOverrides: {
+                            rules: {
+                                // These rules have to be disabled in .stylelintrc for scss compat.
+                                "at-rule-no-unknown": true,
+                            }
+                        }
+                    }
+                },
+            },
+        };
+    };
+
+    const getScssConfigForFiles = files => {
+        return {
+            stylelint: {
+                scss: {
+                    options: {
+                        quietDeprecationWarnings: true,
+                        customSyntax: 'postcss-scss',
+                    },
+                    src: files,
+                },
+            },
+        };
+    };
+
+    /**
+     * Register any stylelint tasks.
+     *
+     * @param {Object} grunt
+     * @param {Array} files
+     * @param {String} fullRunDir
+     */
+    const registerStyleLintTasks = () => {
+        const glob = require('glob');
+
+        // The stylelinters do not handle the case where a configuration was provided but no files were included.
+        // Keep track of whether any files were found.
+        let hasCss = false;
+        let hasScss = false;
+
+        // The stylelint processors do not take a path argument. They always check all provided values.
+        // As a result we must check through each glob and determine if any files match the current directory.
+        const scssFiles = [];
+        const cssFiles = [];
+
+        const requestedFiles = grunt.moodleEnv.files;
+        if (requestedFiles) {
+            // Grunt was called with a files argument.
+            // Check whether each of the requested files matches either the CSS or SCSS source file list.
+
+            requestedFiles.forEach(changedFilePath => {
+                let matchesGlob;
+
+                // Check whether this watched path matches any watched SCSS file.
+                matchesGlob = grunt.moodleEnv.scssSrc.some(watchedPathGlob => {
+                    return glob.sync(watchedPathGlob).indexOf(changedFilePath) !== -1;
+                });
+                if (matchesGlob) {
+                    scssFiles.push(changedFilePath);
+                    hasScss = true;
+                }
+
+                // Check whether this watched path matches any watched CSS file.
+                matchesGlob = grunt.moodleEnv.cssSrc.some(watchedPathGlob => {
+                    return glob.sync(watchedPathGlob).indexOf(changedFilePath) !== -1;
+                });
+                if (matchesGlob) {
+                    cssFiles.push(changedFilePath);
+                    hasCss = true;
+                }
+            });
+        } else {
+            // Grunt was called without a list of files.
+            // The start directory (runDir) may be a child dir of the project.
+            // Check each scssSrc file to see if it's in the start directory.
+            // This means that we can lint just mod/*/styles.css if started in the mod directory.
+
+            grunt.moodleEnv.scssSrc.forEach(path => {
+                if (path.startsWith(grunt.moodleEnv.runDir)) {
+                    scssFiles.push(path);
+                    hasScss = true;
+                }
+            });
+
+            grunt.moodleEnv.cssSrc.forEach(path => {
+                if (path.startsWith(grunt.moodleEnv.runDir)) {
+                    cssFiles.push(path);
+                    hasCss = true;
+                }
+            });
+        }
+
+        // Register the tasks.
+        const scssTasks = ['sass'];
+        if (hasScss) {
+            grunt.config.merge(getScssConfigForFiles(scssFiles));
+            scssTasks.unshift('stylelint:scss');
+        }
+        scssTasks.unshift('ignorefiles');
+
+        const cssTasks = ['ignorefiles'];
+        if (hasCss) {
+            grunt.config.merge(getCssConfigForFiles(cssFiles));
+            cssTasks.push('stylelint:css');
+        }
+
+        // The tasks must be registered, even if empty to ensure a consistent command list.
+        // They jsut won't run anything.
+        grunt.registerTask('scss', scssTasks);
+        grunt.registerTask('rawcss', cssTasks);
+    };
+
+    // Register CSS tasks.
+    grunt.loadNpmTasks('grunt-stylelint');
+
+    // Register the style lint tasks.
+    registerStyleLintTasks();
+    grunt.registerTask('css', ['scss', 'rawcss']);
+
+    const getCoreThemeMatches = () => {
+        const scssMatch = 'scss/**/*.scss';
+
+        if (grunt.moodleEnv.inTheme) {
+            return [scssMatch];
+        }
+
+        if (grunt.moodleEnv.runDir.startsWith('theme')) {
+            return [`*/${scssMatch}`];
+        }
+
+        return [`theme/*/${scssMatch}`];
+    };
+
+    // Add the watch configuration for rawcss, and scss.
+    grunt.config.merge({
+        watch: {
+            rawcss: {
+                files: [
+                    '**/*.css',
+                ],
+                excludes: [
+                    '**/moodle.css',
+                    '**/editor.css',
+                    'jsdoc/styles/*.css',
+                ],
+                tasks: ['rawcss']
+            },
+            scss: {
+                files: getCoreThemeMatches(),
+                tasks: ['scss']
+            },
+        },
+    });
+};

.grunt/tasks/upgradablelibs.js

@@ -0,0 +1,42 @@
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+/* jshint node: true, browser: false */
+/* eslint-env node */
+
+/**
+ * @copyright  2023 Sara Arjona <sara@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+module.exports = grunt => {
+    /**
+     * Generate upgradable third-party libraries (utilising thirdpartylibs.xml data)
+     */
+    grunt.registerTask('upgradablelibs', 'Generate upgradable third-party libraries', async function() {
+        const done = this.async();
+
+        const path = require('path');
+        const ComponentList = require(path.join(process.cwd(), '.grunt', 'components.js'));
+
+        // An array of third party libraries that have a newer version in their repositories.
+        const thirdPartyLibs = await ComponentList.getThirdPartyLibsUpgradable({progress: true});
+        for (let library of thirdPartyLibs) {
+            grunt.log.ok(JSON.stringify(Object.assign({}, library), null, 4));
+        }
+
+        done();
+    });
+
+};

.grunt/tasks/watch.js

@@ -0,0 +1,272 @@
+/**
+ * This is a wrapper task to handle the grunt watch command. It attempts to use
+ * Watchman to monitor for file changes, if it's installed, because it's much faster.
+ *
+ * If Watchman isn't installed then it falls back to the grunt-contrib-watch file
+ * watcher for backwards compatibility.
+ */
+
+/* eslint-env node */
+
+module.exports = grunt => {
+    /**
+     * This is a wrapper task to handle the grunt watch command. It attempts to use
+     * Watchman to monitor for file changes, if it's installed, because it's much faster.
+     *
+     * If Watchman isn't installed then it falls back to the grunt-contrib-watch file
+     * watcher for backwards compatibility.
+     */
+    const watchHandler = function() {
+        const async = require('async');
+        const watchTaskDone = this.async();
+        let watchInitialised = false;
+        let watchTaskQueue = {};
+        let processingQueue = false;
+
+        const watchman = require('fb-watchman');
+        const watchmanClient = new watchman.Client();
+
+        // Grab the tasks and files that have been queued up and execute them.
+        var processWatchTaskQueue = function() {
+            if (!Object.keys(watchTaskQueue).length || processingQueue) {
+                // If there is nothing in the queue or we're already processing then wait.
+                return;
+            }
+
+            processingQueue = true;
+
+            // Grab all tasks currently in the queue.
+            var queueToProcess = watchTaskQueue;
+            // Reset the queue.
+            watchTaskQueue = {};
+
+            async.forEachSeries(
+                Object.keys(queueToProcess),
+                function(task, next) {
+                    var files = queueToProcess[task];
+                    var filesOption = '--files=' + files.join(',');
+                    grunt.log.ok('Running task ' + task + ' for files ' + filesOption);
+
+                    // Spawn the task in a child process so that it doesn't kill this one
+                    // if it failed.
+                    grunt.util.spawn(
+                        {
+                            // Spawn with the grunt bin.
+                            grunt: true,
+                            // Run from current working dir and inherit stdio from process.
+                            opts: {
+                                cwd: grunt.moodleEnv.fullRunDir,
+                                stdio: 'inherit'
+                            },
+                            args: [task, filesOption]
+                        },
+                        function(err, res, code) {
+                            if (code !== 0) {
+                                // The grunt task failed.
+                                grunt.log.error(err);
+                            }
+
+                            // Move on to the next task.
+                            next();
+                        }
+                    );
+                },
+                function() {
+                    // No longer processing.
+                    processingQueue = false;
+                    // Once all of the tasks are done then recurse just in case more tasks
+                    // were queued while we were processing.
+                    processWatchTaskQueue();
+                }
+            );
+        };
+
+        const originalWatchConfig = grunt.config.get(['watch']);
+        const watchConfig = Object.keys(originalWatchConfig).reduce(function(carry, key) {
+            if (key == 'options') {
+                return carry;
+            }
+
+            const value = originalWatchConfig[key];
+
+            const taskNames = value.tasks;
+            const files = value.files;
+            let excludes = [];
+            if (value.excludes) {
+                excludes = value.excludes;
+            }
+
+            taskNames.forEach(function(taskName) {
+                carry[taskName] = {
+                    files,
+                    excludes,
+                };
+            });
+
+            return carry;
+        }, {});
+
+        watchmanClient.on('error', function(error) {
+            // We have to add an error handler here and parse the error string because the
+            // example way from the docs to check if Watchman is installed doesn't actually work!!
+            // See: https://github.com/facebook/watchman/issues/509
+            if (error.message.match('Watchman was not found')) {
+                // If watchman isn't installed then we should fallback to the other watch task.
+                grunt.log.ok('It is recommended that you install Watchman for better performance using the "watch" command.');
+
+                // Fallback to the old grunt-contrib-watch task.
+                grunt.renameTask('watch-grunt', 'watch');
+                grunt.task.run(['watch']);
+                // This task is finished.
+                watchTaskDone(0);
+            } else {
+                grunt.log.error(error);
+                // Fatal error.
+                watchTaskDone(1);
+            }
+        });
+
+        watchmanClient.on('subscription', function(resp) {
+            if (resp.subscription !== 'grunt-watch') {
+                return;
+            }
+
+            resp.files.forEach(function(file) {
+                grunt.log.ok('File changed: ' + file.name);
+
+                var fullPath = grunt.moodleEnv.fullRunDir + '/' + file.name;
+                Object.keys(watchConfig).forEach(function(task) {
+
+                    const fileGlobs = watchConfig[task].files;
+                    var match = fileGlobs.some(function(fileGlob) {
+                        return grunt.file.isMatch(`**/${fileGlob}`, fullPath);
+                    });
+
+                    if (match) {
+                        // If we are watching a subdirectory then the file.name will be relative
+                        // to that directory. However the grunt tasks  expect the file paths to be
+                        // relative to the Gruntfile.js location so let's normalise them before
+                        // adding them to the queue.
+                        var relativePath = fullPath.replace(grunt.moodleEnv.gruntFilePath + '/', '');
+                        if (task in watchTaskQueue) {
+                            if (!watchTaskQueue[task].includes(relativePath)) {
+                                watchTaskQueue[task] = watchTaskQueue[task].concat(relativePath);
+                            }
+                        } else {
+                            watchTaskQueue[task] = [relativePath];
+                        }
+                    }
+                });
+            });
+
+            processWatchTaskQueue();
+        });
+
+        process.on('SIGINT', function() {
+            // Let the user know that they may need to manually stop the Watchman daemon if they
+            // no longer want it running.
+            if (watchInitialised) {
+                grunt.log.ok('The Watchman daemon may still be running and may need to be stopped manually.');
+            }
+
+            process.exit();
+        });
+
+        // Initiate the watch on the current directory.
+        watchmanClient.command(['watch-project', grunt.moodleEnv.fullRunDir], function(watchError, watchResponse) {
+            if (watchError) {
+                grunt.log.error('Error initiating watch:', watchError);
+                watchTaskDone(1);
+                return;
+            }
+
+            if ('warning' in watchResponse) {
+                grunt.log.error('warning: ', watchResponse.warning);
+            }
+
+            var watch = watchResponse.watch;
+            var relativePath = watchResponse.relative_path;
+            watchInitialised = true;
+
+            watchmanClient.command(['clock', watch], function(clockError, clockResponse) {
+                if (clockError) {
+                    grunt.log.error('Failed to query clock:', clockError);
+                    watchTaskDone(1);
+                    return;
+                }
+
+                // Generate the expression query used by watchman.
+                // Documentation is limited, but see https://facebook.github.io/watchman/docs/expr/allof.html for examples.
+                // We generate an expression to match any value in the files list of all of our tasks, but excluding
+                // all value in the  excludes list of that task.
+                //
+                // [anyof, [
+                //      [allof, [
+                //          [anyof, [
+                //              ['match', validPath, 'wholename'],
+                //              ['match', validPath, 'wholename'],
+                //          ],
+                //          [not,
+                //              [anyof, [
+                //                  ['match', invalidPath, 'wholename'],
+                //                  ['match', invalidPath, 'wholename'],
+                //              ],
+                //          ],
+                //      ],
+                var matchWholeName = fileGlob => ['match', fileGlob, 'wholename'];
+                var matches = Object.keys(watchConfig).map(function(task) {
+                    const matchAll = [];
+                    matchAll.push(['anyof'].concat(watchConfig[task].files.map(matchWholeName)));
+
+                    if (watchConfig[task].excludes.length) {
+                        matchAll.push(['not', ['anyof'].concat(watchConfig[task].excludes.map(matchWholeName))]);
+                    }
+
+                    return ['allof'].concat(matchAll);
+                });
+
+                matches = ['anyof'].concat(matches);
+
+                var sub = {
+                    expression: matches,
+                    // Which fields we're interested in.
+                    fields: ["name", "size", "type"],
+                    // Add our time constraint.
+                    since: clockResponse.clock
+                };
+
+                if (relativePath) {
+                    /* eslint-disable camelcase */
+                    sub.relative_root = relativePath;
+                }
+
+                watchmanClient.command(['subscribe', watch, 'grunt-watch', sub], function(subscribeError) {
+                    if (subscribeError) {
+                        // Probably an error in the subscription criteria.
+                        grunt.log.error('failed to subscribe: ', subscribeError);
+                        watchTaskDone(1);
+                        return;
+                    }
+
+                    grunt.log.ok('Listening for changes to files in ' + grunt.moodleEnv.fullRunDir);
+                });
+            });
+        });
+    };
+
+    // Rename the grunt-contrib-watch "watch" task because we're going to wrap it.
+    grunt.renameTask('watch', 'watch-grunt');
+
+    // Register the new watch handler.
+    grunt.registerTask('watch', 'Run tasks on file changes', watchHandler);
+
+    grunt.config.merge({
+        watch: {
+            options: {
+                nospawn: true // We need not to spawn so config can be changed dynamically.
+            },
+        },
+    });
+
+    return watchHandler;
+};