Gruntfile.js

/*!
 * Copyright 2014 Apereo Foundation (AF) Licensed under the
 * Educational Community License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License. You may
 * obtain a copy of the License at
 *
 *     http://opensource.org/licenses/ECL-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an "AS IS"
 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

const util = require('util');
const vm = require('vm');
const _ = require('underscore');

module.exports = function(grunt) {
  // Project configuration.
  grunt.initConfig({
    pkg: '<json:package.json>',
    meta: {
      banner:
        '/*! <%= pkg.name %> - v<%= pkg.version %> - ' +
        '<%= grunt.template.today("yyyy-mm-dd") %>\n' +
        '<%= pkg.homepage ? "* " + pkg.homepage + "\n" : "" %>' +
        '* Copyright (c) <%= grunt.template.today("yyyy") %> <%= pkg.author.name %>;' +
        ' Licensed <%= _.pluck(pkg.licenses, "type").join(", ") %> */'
    },
    target: process.env.DESTDIR || 'target',
    qunit: {
      files: ['tests/qunit/tests/*.html']
    },
    uglify: {
      my_target: {
        options: {
          mangle: {
            reserved: ['jquery']
          }
        },
        files: [
          {
            expand: true,
            src: [
              '<%= target %>/optimized/**/*.js',
              '!<%= target %>/optimized/**/*.min.js',
              '!<%= target %>/optimized/node_modules/**/*.js',
              '!<%= target %>/optimized/target/**/*.js'
            ],
            dest: '<%= target %>/optimized',
            cwd: '.',
            rename(dst, src) {
              return src;
            }
          }
        ]
      }
    },
    lint: {
      files: [
        'grunt.js',
        'admin/**/*.js',
        'shared/**/*.js',
        'ui/**/*.js',
        'node_modules/oae-*/**/*.js',
        '!node_modules/oae-release-tools/**'
      ]
    },
    watch: {
      files: '<config:lint.files>',
      tasks: 'lint test'
    },
    csslint: {
      options: {
        ids: false // ignore "Don't use IDs in CSS selectors" warning
      },
      files: [
        'admin/**/*.css',
        'shared/oae/**/*.css',
        'ui/**/*.css',
        'node_modules/oae-*/**/*.css',
        '!node_modules/oae-release-tools/**'
      ]
    },
    jshint: {
      options: {
        node: true,
        sub: true,
        indent: 4,
        trailing: true,
        quotmark: 'single',
        curly: true,
        white: false,
        strict: false,
        esversion: 6
      },
      files: [
        'admin/**/*.js',
        'shared/oae/**/*.js',
        'ui/**/*.js',
        'node_modules/oae-*/**/*.js',
        '!node_modules/oae-release-tools/**'
      ]
    },
    clean: {
      folder: '<%= target %>/'
    },
    copy: {
      main: {
        files: [
          {
            expand: true,
            src: [
              '**',
              '!<%= target %>/**',
              '!tests/**',
              '!tools/**',
              '!node_modules/.*/**',
              '!node_modules/grunt*/**',
              '!node_modules/oae-release-tools/**',
              '!node_modules/optimist/**',
              '!node_modules/properties-parser/**',
              '!node_modules/readdirp/**',
              '!node_modules/underscore/**'
            ],
            dest: '<%= target %>/original'
          }
        ]
      }
    },
    requirejs: {
      optimize: {
        options: {
          appDir: './',
          baseUrl: './shared',
          mainConfigFile: './shared/oae/api/oae.bootstrap.js',
          dir: '<%= target %>/optimized',
          normalizeDirDefines: 'all',
          optimize: 'none',
          preserveLicenseComments: false,
          optimizeCss: 'standard',
          // TODO: Replace this with a saner value
          // @see https://github.com/jrburke/r.js/pull/653
          cssImportIgnore:
            '//fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,400,300,600,700&subset=latin,cyrillic-ext,latin-ext,greek-ext',
          inlineText: true,
          useStrict: false,
          pragmas: {},
          skipPragmas: false,
          skipModuleInsertion: false,
          modules: [
            {
              name: 'oae.core',
              exclude: ['jquery']
            }
          ],
          fileExclusionRegExp: /^(\.|<%= target %>|tests|tools|grunt|optimist|properties-parser|readdirp|underscore$|shelljs$|oae-release-tools|benchmark|robots\.txt)/,
          logLevel: 2
        }
      }
    },
    ver: {
      oae: {
        basedir: '<%= target %>/optimized',
        phases: [
          /*!
           * In the first phase, we hash the contents of all the shared bundle and culture
           * folders and rename the foler to contain the hash. All references to the
           * original folder name are replaced with the hashed version in just the shared
           * JS files as those are the only places we have references to them.
           */
          {
            folders: [
              '<%= target %>/optimized/shared/oae/bundles/ui',
              '<%= target %>/optimized/shared/oae/bundles/email',
              '<%= target %>/optimized/shared/vendor/js/l10n/cultures'
            ],
            references: ['<%= target %>/optimized/shared/**/*.js']
          },

          /*!
           * In the second phase, we hash just files that are not going to have
           * references to other hashed files. That's basically everything except
           * JS and CSS files so those file extensions are excluded. Additionally,
           * the following types of files are excluded:
           *
           *  * We do not hash HTML files because they aren't cached
           *  * We do not hash JS and CSS files because they are handled separately in a later phase
           *  * We do not hash the JSON files (e.g., manifest.json) because they are not referenced as assets by the UI, only by the oae-ui Hilary module
           *  * We do not hash the favicon (*.ico) because it is a browser standard file
           *  * We do not hash less files because they are programmatically accessed
           *  * We exclude the directories that have already been hashed (bundles and cultures)
           *
           * TODO: Remove "custom" when there is a proper landing page customization strategy
           */
          {
            files: _hashFiles({
              directories: [
                '<%= target %>/optimized/admin',
                '<%= target %>/optimized/custom',
                '<%= target %>/optimized/docs',
                '<%= target %>/optimized/shared',
                '<%= target %>/optimized/ui'
              ],
              excludeExts: ['css', 'html', 'ico', 'js', 'json', 'less'],
              extra: [
                '!<%= target %>/optimized/shared/oae/bundles/email.*/**',
                '!<%= target %>/optimized/shared/oae/bundles/ui.*/**',
                '!<%= target %>/optimized/shared/vendor/js/l10n/cultures.*/**'
              ]
            }),
            references: _replacementReferences({
              directories: [
                '<%= target %>/optimized/admin',
                '<%= target %>/optimized/custom',
                '<%= target %>/optimized/docs',
                '<%= target %>/optimized/node_modules/oae-*',
                '<%= target %>/optimized/shared',
                '<%= target %>/optimized/ui'
              ],
              includeExts: ['css', 'html', 'js'],
              extra: ['<%= target %>/optimized/shared/oae/macros/*.html']
            })
          },

          /*!
           * In the third phase, we hash the macros and apply any replacements to the JS
           * files in the shared directory.
           */
          {
            files: ['<%= target %>/optimized/shared/oae/macros/*.html'],
            references: ['<%= target %>/optimized/shared/**/*.js']
          },

          /*!
           * In the fourth phase, we hash JavaScript, CSS, HTML (macro) files of the /shared
           * directory and replace all HTML and JS files with them. CSS files don't
           * need replacement because a CSS file will never references another CSS
           * or JavaScript (@import statements are inlined). Here we don't worry about
           * JS-to-JS references because those are aliased inside oae.bootstrap.js
           *
           * TODO: Remove "custom" when there is a proper landing page customization strategy
           */
          {
            files: [
              '<%= target %>/optimized/shared/**/*.js',
              '<%= target %>/optimized/shared/**/*.css',
              '!<%= target %>/optimized/shared/vendor/js/l10n/cultures.*/**'
            ],
            references: _replacementReferences({
              directories: [
                '<%= target %>/optimized/admin',
                '<%= target %>/optimized/custom',
                '<%= target %>/optimized/docs',
                '<%= target %>/optimized/node_modules/oae-*',
                '<%= target %>/optimized/shared',
                '<%= target %>/optimized/ui'
              ],
              includeExts: ['html', 'js'],
              extra: ['<%= target %>/optimized/shared/oae/macros/*.html']
            })
          },

          /*!
           * In the fifth phase, we hash the JS directories of all the actual UIs like
           * /admin, /ui etc... We need to hash the directory because there are JS-to-JS
           * references that can't be reliably processed such that hashes are created
           * after inline replacement of paths have occurred. By hashing the directory we
           * ensure that all JS files are invalidated as a group and so don't wind up with
           * indirect references that don't properly update a hash.
           *
           * We also hash the CSS files and perform the necessary replacements.
           *
           * TODO: Remove "custom" when there is a proper landing page customization strategy
           */
          {
            folders: [
              '<%= target %>/optimized/admin/js',
              '<%= target %>/optimized/custom/js',
              '<%= target %>/optimized/docs/js',
              '<%= target %>/optimized/ui/js'
            ],
            files: [
              '<%= target %>/optimized/admin/**/*.css',
              '<%= target %>/optimized/docs/**/*.css',
              '<%= target %>/optimized/custom/**/*.css',
              '<%= target %>/optimized/ui/**/*.css'
            ],
            references: _replacementReferences({
              directories: [
                '<%= target %>/optimized/admin',
                '<%= target %>/optimized/custom',
                '<%= target %>/optimized/docs',
                '<%= target %>/optimized/node_modules/oae-*',
                '<%= target %>/optimized/ui'
              ],
              includeExts: ['html', 'js'],
              extra: ['<%= target %>/optimized/shared/oae/macros/*.html']
            })
          }
        ],
        version: '<%= target %>/optimized/hashes.json'
      }
    },
    replace: {
      url: 'URL pointing to a CDN that gets set by the cdn task',
      main: {
        src: [
          'target/optimized/ui/*.html',
          'target/optimized/ui/custom/*.html',
          'target/optimized/admin/*.html',
          'target/optimized/shared/oae/api/oae.bootstrap.*.js',
          'target/optimized/shared/oae/api/oae.core.*.js'
        ],
        overwrite: true,
        replacements: [
          {
            from: /(src)="\/(.+?)"/gi,
            to(matchedWord, index, fullText, regexMatches) {
              return _cdnifyStaticAsset(grunt.config('replace').url, matchedWord, index, fullText, regexMatches);
            }
          },
          {
            from: /(data-loadmodule)="\/(.+?)"/gi,
            to(matchedWord, index, fullText, regexMatches) {
              return _cdnifyStaticAsset(grunt.config('replace').url, matchedWord, index, fullText, regexMatches);
            }
          },
          {
            from: /(data-main)="\/(.+?)"/gi,
            to(matchedWord, index, fullText, regexMatches) {
              return _cdnifyStaticAsset(grunt.config('replace').url, matchedWord, index, fullText, regexMatches);
            }
          },
          {
            from: /(<link.*?href)="\/(.+?)"/gi,
            to(matchedWord, index, fullText, regexMatches) {
              return _cdnifyStaticAsset(grunt.config('replace').url, matchedWord, index, fullText, regexMatches);
            }
          },
          {
            // Replace the require base URL
            from: /requirejs\.config\(\{baseUrl:"\/shared\/",/,
            to(matchedWord, index, fullText, regexMatches) {
              // The URL of our CDN
              const cdn = grunt.config('replace').url;

              // Return the attribute with our CDN in it
              return util.format('requirejs.config({baseUrl:"%s/shared/",', cdn);
            }
          },
          {
            // We're loading in a globalize culture dynamically that can
            // be loaded from our CDN
            from: /require\(\["\/shared\/vendor\/js\/l10n\/cultures\./,
            to(matchedWord, index, fullText, regexMatches) {
              // The URL of our CDN
              const cdn = grunt.config('replace').url;

              // Return the attribute with our CDN in it
              return util.format('require(["%s/shared/vendor/js/l10n/cultures.', cdn);
            }
          }
        ]
      },
      'core-widgets': {
        src: ['target/optimized/node_modules/oae-core/**/*.html'],
        overwrite: true,
        replacements: [
          {
            // Replace the CSS paths in the oae-core widgets
            from: /href="css\/([a-z]+?)\.([a-z0-9]+?).css"/,
            to(matchedWord, index, fullText, regexMatches) {
              const cdn = grunt.config('replace').url;
              return util.format(
                'href="%s/node_modules/oae-core/%s/css/%s.%s.css"',
                cdn,
                regexMatches[0],
                regexMatches[0],
                regexMatches[1]
              );
            }
          },
          {
            // Replace the JS paths in the oae-core widgets
            from: /src="js\/([a-z]+?)\.([a-z0-9]+?).js"/,
            to(matchedWord, index, fullText, regexMatches) {
              const cdn = grunt.config('replace').url;
              return util.format(
                'src="%s/node_modules/oae-core/%s/js/%s.%s.js"',
                cdn,
                regexMatches[0],
                regexMatches[0],
                regexMatches[1]
              );
            }
          }
        ]
      },
      'admin-widgets': {
        src: ['target/optimized/node_modules/oae-admin/**/*.html'],
        overwrite: true,
        replacements: [
          ,
          {
            from: /href="css\/([a-z]+?)\.([a-z0-9]+?).css"/,
            to(matchedWord, index, fullText, regexMatches) {
              const cdn = grunt.config('replace').url;
              return util.format(
                'href="%s/node_modules/oae-admin/%s/css/%s.%s.css"',
                cdn,
                regexMatches[0],
                regexMatches[0],
                regexMatches[1]
              );
            }
          },
          {
            from: /src="js\/([a-z]+?)\.([a-z0-9]+?).js"/,
            to(matchedWord, index, fullText, regexMatches) {
              const cdn = grunt.config('replace').url;
              return util.format(
                'src="%s/node_modules/oae-admin/%s/js/%s.%s.js"',
                cdn,
                regexMatches[0],
                regexMatches[0],
                regexMatches[1]
              );
            }
          }
        ]
      }
    },
    'git-describe': {
      oae: {}
    },
    exec: {
      startDependencies: {
        cmd: 'node tests/casperjs/startDependencies.js'
      }
    }
  });

  // Load tasks from npm modules
  grunt.loadNpmTasks('grunt-contrib-clean');
  grunt.loadNpmTasks('grunt-contrib-copy');
  grunt.loadNpmTasks('grunt-contrib-csslint');
  grunt.loadNpmTasks('grunt-contrib-jshint');
  grunt.loadNpmTasks('grunt-contrib-qunit');
  grunt.loadNpmTasks('grunt-contrib-uglify-es');
  grunt.loadNpmTasks('grunt-git-describe');
  grunt.loadNpmTasks('grunt-ver');
  grunt.loadNpmTasks('grunt-contrib-requirejs');
  grunt.loadNpmTasks('grunt-exec');
  grunt.loadNpmTasks('grunt-text-replace');

  // Task to write the version to a file
  grunt.registerTask('writeVersion', function() {
    this.requires('git-describe');
    const json = grunt.template.process('{"oae:ux-version":"<%= meta.version %>"}');
    grunt.file.write(grunt.config('target') + '/optimized/ui/version.json', json);
  });

  // Task to fill out the nginx config template
  grunt.registerTask('configNginx', () => {
    const infile = './nginx/nginx.json';
    if (grunt.file.exists(infile)) {
      const nginxConfig = require(infile);
      const template = grunt.file.read('./nginx/nginx.conf');
      grunt.config.set('nginxConf', nginxConfig);
      const config = grunt.template.process(template);
      const outfile = grunt.config('target') + '/optimized/nginx/nginx.conf';
      grunt.file.write(outfile, config);
      grunt.log.writeln('nginx.conf rendered at '.green + outfile.green);
    } else {
      const msg = 'No ' + infile + ' found, not rendering nginx.conf template';
      grunt.log.writeln(msg.yellow);
    }
  });

  // Task to place an update slug on the oae.bootstrap.js file so that it always gets a new hash in a
  // build. This is needed because we do post-hash updates on the file to update module references and
  // if module reference hashes change, it's possible the oae.bootstrap.js file won't get a new hash
  // as a result
  grunt.registerTask('touchBootstrap', () => {
    // Just place a comment in the file with the current timestamp
    util
      .format('\n// Date Built: %d', Date.now())
      .toEnd(util.format('%s/optimized/shared/oae/api/oae.bootstrap.js', grunt.config('target')));
  });

  // Task to hash files
  grunt.registerTask('hashFiles', function() {
    this.requires('requirejs');
    this.requires('touchBootstrap');

    // Add a new ver task for each module that needs to be optimized
    const oaeModules = grunt.file.expand(
      { filter: 'isDirectory' },
      grunt.config('target') + '/optimized/node_modules/oae-*/*'
    );
    oaeModules.forEach(module => {
      grunt.log.writeln(module);

      const moduleReferences = [
        util.format('%s/**/*.css', module),
        util.format('%s/**/*.html', module),
        util.format('%s/**/*.js', module),
        util.format('%s/**/*.json', module)
      ];

      const phases = [
        /*!
         * First, hash all files that do not have references to other files. That's
         * basically everything except HTML, JS, CSS files. Additionally, we
         * don't hash the following:
         *
         *  * properties files aren't hashed, because the bundles directory itself
         *    is hashed
         *  * JSON files (manifest.json) aren't hashed because it needs to have a
         *    deterministic name
         */
        {
          files: _hashFiles({
            directories: [module],
            excludeExts: ['css', 'html', 'js', 'json', 'properties']
          }),
          references: moduleReferences.slice()
        },

        /*!
         * Second, hash the bundles directories of the widgets
         */
        {
          folders: [util.format('%s/bundles', module)],
          references: moduleReferences.slice()
        },

        /*!
         * Third, hash just the JS files and CSS files so their references can be updated in
         * the HTML files.
         *
         * TODO:
         *
         * Hashing JS files only once in this way is rather unstable. There is an issue such
         * that if one JS file references another, and that other JS file changes, the hash
         * of the JS file that references it will not get updated. Either the hashing cycle
         * needs to happen a safe number of times (e.g., hashing 3 times may secure JS
         * reference chains of depth 3), or there should be a better strategy to catch changes
         * in JS files. Directory hashing on the js/ directory does not work because it
         * results in all strings of "js" to be replaced in the widget files, which catches
         * things like: /shared/vendor/js/... for example, thus breaking those references.
         *
         * In this replacement phase, we are only replacing references in HTML files, since
         * any references to these files by non-HTML files will otherwise result in less
         * obvious issues that can only be caught with meticulous cache-upgrade testing which
         * is difficult to get right and very time consuming.
         *
         * See https://github.com/oaeproject/3akai-ux/issues/3551 for more information.
         */
        {
          files: [util.format('%s/**/*.css', module), util.format('%s/**/*.js', module)],
          references: [util.format('%s/**/*.html', module)]
        },

        /*!
         * Fourth, now that references for all other files have been replaced, finally
         * hash the HTML files of the widget, replacing the reference in the `manifest.json`
         * file, as that is the only place the optimization workflow has accounted for them
         * to be referenced.
         *
         * This optimization phase is intentionally only accounting for the setup that the
         * `manifest.json` file is the only reference to a widget HTML file. If a situation
         * arises that the `manifest.json` is not the only file that references an HTML file
         * (e.g., a JS file referencing an HTML widget macro file), then there are indirect
         * cache invalidation issues that will almost certainly start happeningf if the macro
         * file is updated and gets a new hash, but the JS file is not. By limiting this to
         * the `manifest.json` for now, we can more explicitly visit this issue when it is
         * obvious in testing, rather than it becoming an intermittent production cache issue
         * first.
         */
        {
          files: [util.format('%s/**/*.html', module)],
          references: [util.format('%s/**/*.json', module)]
        }
      ];

      grunt.config.set(util.format('ver.%s.basedir', module), module);
      grunt.config.set(util.format('ver.%s.phases', module), phases);
      grunt.task.run(util.format('ver:%s', module));
    });

    grunt.task.run('ver:oae');
    grunt.task.run('updateBootstrapPaths');
  });

  // Task to update the paths in oae.bootstrap to the hashed versions
  grunt.registerTask('updateBootstrapPaths', function() {
    this.requires('ver:oae');

    const basedir = grunt.config('target') + '/optimized/';
    const hashedPaths = require('./' + grunt.config.get('ver.oae.version'));
    const bootstrapPath = basedir + hashedPaths['/shared/oae/api/oae.bootstrap.js'];
    let bootstrap = grunt.file.read(bootstrapPath);
    const regex = /("|')?paths("|')?: ?\{[^}]*\}/;
    const scriptPaths = 'paths = {' + bootstrap.match(regex)[0] + '}';

    const { paths } = vm.runInThisContext(scriptPaths);

    // Update the bootstrap file with the hashed paths
    Object.keys(paths).forEach(key => {
      const prefix = '/shared/';
      const path = prefix + paths[key] + '.js';
      let hashedPath = '';
      if (hashedPaths[path]) {
        hashedPath = hashedPaths[path];
        // Trim off prefix and .js
        paths[key] = hashedPath.substring(prefix.length, hashedPath.length - 3);
      }
    });
    bootstrap = bootstrap.replace(regex, 'paths:' + JSON.stringify(paths));
    grunt.file.write(bootstrapPath, bootstrap);
    grunt.log.writeln('Boots strapped'.green);
  });

  // Task to update the paths so static assets are pulled from the CDN.
  // The CDN URL can be provided as
  //  - an environment variable: e.g., `CDN_URL="https://cdn.example.com" grunt cdn`
  //  - a grunt parameter: e.g., `grunt cdn:https\://cdn.example.com`
  // If no CDN is provided, this task will do nothing
  grunt.registerTask('cdn', url => {
    url = url || process.env.CDN_URL;
    if (url) {
      // Pass the URL of the CDN to the replacement task
      grunt.config.set('replace.url', url);

      // Start replacing paths
      grunt.task.run('replace:main');
      grunt.task.run('replace:core-widgets');
      grunt.task.run('replace:admin-widgets');
    } else {
      const msg = 'No cdn provided, not performing cdn task';
      grunt.log.writeln(msg.yellow);
    }
  });

  // A task that will copy the release files to a directory of your choosing
  grunt.registerTask('copyReleaseArtifacts', outputDir => {
    if (!outputDir) {
      return grunt.log.writeln('Please provide a path where the release files should be copied to'.red);
    }

    const config = {
      files: [
        {
          expand: true,
          src: ['./<%= grunt.config("target") %>/*', './README.md', './LICENSE', './COMMITTERS.txt'],
          dest: outputDir
        }
      ]
    };
    grunt.config.set('copy.release', config);
    grunt.task.run('copy:release');
  });

  // Release task.
  // This essentially runs the default task and then copies the target directory to the `outputDir`
  //
  // Example:
  //    grunt release:/tmp/release
  //
  // This will run the entire UI build (minification, hashing, nginx config, etc, ..) and create the following folders:
  //    /tmp/release/optimized  -  contains the minified UI sources
  //    /tmp/release/original   -  contains the original UI files
  grunt.registerTask('release', outputDir => {
    if (!outputDir) {
      return grunt.log.writeln('Please provide a path where the release files should be copied to'.red);
    }

    // Run the default task that will minify and hash all the UI files.
    grunt.task.run('default');

    // Copy the minified and original files to the output directory
    // and give them the proper names so no config changes in Hilary need to occur
    grunt.task.run('copyReleaseArtifacts:' + outputDir);
  });

  // Lint tasks (JavaScript only for now, too many errors in css)
  grunt.registerTask('lint', ['jshint' /* , 'csslint' */]);

  // Wrap the QUnit task
  grunt.renameTask('qunit', 'contrib-qunit');
  grunt.registerTask('qunit', host => {
    // Fall back to the `qunit-host` option
    host = host || grunt.option('qunit-host');
    if (!host) {
      return grunt.fail.fatal(
        'Please provide a link to a running OAE instance. e.g. `grunt qunit:tenant1.oae.com` or `grunt qunit --qunit-host tenant1.oae.com`'
      );
    }

    const urls = _.map(grunt.file.expand(grunt.config.get('qunit.files')), file => {
      return 'http://' + host + '/' + file;
    });
    const config = { options: { urls } };
    grunt.config.set('contrib-qunit.all', config);
    grunt.task.run('contrib-qunit');
  });

  // Task to start prerequisites for CasperJS tests
  grunt.registerTask('startDependencies', path => {
    grunt.task.run('exec:startDependencies');
  });

  // Task to run the CasperJS and QUnit tests
  grunt.registerTask('test', ['startDependencies']);

  // Task to run an individual CasperJS test
  grunt.registerTask('test-file', path => {
    path = path || grunt.option('path');

    if (!path) {
      return grunt.fail.fatal(
        'Please provide a path to a CasperJS test file. e.g. `grunt test-file --path=node_modules/oae-core/preferences/tests/preferences.js`'
      );
    }

    grunt.task.run('exec:runCasperTest:' + path);
  });

  // Default task for production build
  grunt.registerTask('default', [
    'clean',
    'copy',
    'git-describe',
    'requirejs',
    'uglify',
    'touchBootstrap',
    'cdn',
    'writeVersion',
    'configNginx'
  ]);
};

/**
 * Generate the standard replacement references for the given resource directories, and also
 * include the provided "extra" replacement files.
 *
 * @param  {Object}     options                 An options object that specifies what files to hash
 * @param  {String[]}   options.directories     A list of directories whose resource paths should be replaced
 * @param  {String[]}   [options.includeExts]   The file extensions that should have replacement performed
 * @param  {String[]}   [options.extra]         Additional replacements to perform
 * @return {String[]}                           The full derived list of all resources that replacement should be performed
 * @api private
 */
var _replacementReferences = function(options) {
  options.includeExts = options.includeExts || [];
  options.extra = options.extra || [];

  const globs = [];
  _.each(options.directories, directory => {
    _.each(options.includeExts, ext => {
      globs.push(util.format('%s/**/*.%s', directory, ext));
    });
  });

  return _.union(globs, options.extra);
};

/**
 * Generate the glob expressions to match all extensions of files in the provided set of
 * directories. Any file with an extension that is found in the `excludeExts` option  will not be
 * hashed
 *
 * @param  {Object}     options                 An options object that specifies what files to hash
 * @param  {String[]}   options.directories     The list of directories whose files to hash
 * @param  {String[]}   [options.excludeExts]   The extensions of files to ignore when hashing files
 * @param  {String[]}   [options.extra]         Extra glob patterns to append, in addition to the ones added for the extensions
 * @return {String[]}                           An array of glob expressions that match the files to hash in the directories
 * @api private
 */
var _hashFiles = function(options) {
  options.excludeExts = options.excludeExts || [];
  options.extra = options.extra || [];

  const globs = [];
  _.each(options.directories, directory => {
    globs.push(util.format('%s/**', directory));
    _.each(options.excludeExts, ext => {
      // Exclude both direct children of the excluded extensions, and all grand-children
      globs.push(util.format('!%s/*.%s', directory, ext));
      globs.push(util.format('!%s/**/*.%s', directory, ext));
    });
  });

  return _.union(globs, options.extra);
};

/**
 * Prepend the CDN url for those static assets that are not delivered by either
 * the OAE APIs or other external hosts
 *
 * @param  {String}         cdn                 The url of the cdn to prepend before static asset urls
 * @param  {String}         matchedWord         The full match. For example, `src="/shared/oae/css/oae.core.123456.css`
 * @param  {Number}         index               The index where the match was found in the `fullText`
 * @param  {String}         fullText            The full original text of the file
 * @param  {String[]}       regexMatches        The matches that were made by the configured regex
 * @return {String}                             The string that will replace `matchedWord`
 * @api private
 */
var _cdnifyStaticAsset = function(cdn, matchedWord, index, fullText, regexMatches) {
  // Get the name of the attribute (e.g., `src`, `data-main`, ...)
  const attr = regexMatches[0];

  // Do not replace anything that already points to an outside source
  // e.g., do not cdnify src="//www.youtube" or href="https://foo.com/asset.jpg"
  if (regexMatches[1].indexOf('/') === 0 || regexMatches[1].indexOf('api') === 0) {
    return matchedWord;
  }

  // Return the attribute with our CDN in it
  return util.format('%s="%s/%s"', attr, cdn, regexMatches[1]);
};