screeps-gruntfile

gruntfile.js

/**
 * @file gruntfile.js
 *
 * @summary Configurable gruntfile for the game Screeps.
 * @description
 *      Gruntfile to upload code to an arbitrary Screeps server and generating
 *      a documentation of the player code using `jsdoc`. The parameters of the
 *      grunt tasks are configurable using the custom configuration file.
 *
 * @author krnd
 * @version 1.0
 *
 * @see http://gruntjs.com/configuring-tasks
 * @see http://gist.github.com/krnd
 */

// other potential script extensions
//  http://github.com/gruntjs/grunt-contrib-copy
//  http://github.com/wecodemore/grunt-githooks

// user configuration file
const userConfigPath = 'grunt.json'


// ------------------------------------ Default User Configuration -------------

// default upload target name
const defaultUploadTarget = 'default'
const defaultConfig = {
  // common folders and files
  sourceFolder: 'screeps',
  uploadFolder: 'screeps',
  docFolder: 'doc',
  entryFile: 'main.js',

  // credentials file
  credentials: 'screeps.json',

  // jsdoc configuration file
  jsdocFile: 'jsdoc.json',

  // timestamping
  uploadTimestamp: true,
  timestampFile: /* defaults to `entryFile` */ null,
  timestampVariable: 'UPLOAD',

  // upload configuration
  uploadBranch: 'default',
  upload: { [defaultUploadTarget]: { /* branch defaults to `uploadBranch` */ } },
}


// ------------------------------------ Helper Functions -----------------------

/**
 * Resolve user configuration upload targets shortcuts.
 *
 * @param {object} uploadTargets - Upload targets to resolve.
 *
 * @returns {object} Returns the resolved upload targets object.
 */
function resolveUploadTargets(uploadTargets) {
  // resolve single-target branch shorthand
  if (typeof uploadTargets === 'string')
    uploadTargets = { [defaultUploadTarget]: { branch: uploadTargets } }

  // resolve multi-target shorthands
  for (const target in uploadTargets) {
    const targetInfo = uploadTargets[target]
    // resolve branch shorthand
    if (typeof targetInfo === 'string')
      uploadTargets[target] = { branch: targetInfo }
  }

  return uploadTargets
}


// ------------------------------------ Plugin Configurations ------------------

/**
 * Configures the plugin identified by the objects key.
 * @func configurePlugin
 *
 * @param {object} grunt - Default Grunt parameter.
 * @param {object} gruntConfig - Grunt tasks configuration.
 * @param {UserConfig} userConfig - Grunt script user configuration.
 */
const configurePlugin = {
  // @see http://github.com/gruntjs/grunt-contrib-clean
  'contrib-clean': function (grunt, gruntConfig, userConfig) {
    // load plugin tasks
    grunt.loadNpmTasks('grunt-contrib-clean')

    // default user configurations
    const docFolder = userConfig.docFolder || defaultConfig.docFolder

    // create grunt task config
    const gtcfg = gruntConfig.clean = {}

    // add documentation cleanup target to grunt config
    gtcfg.doc = { src: docFolder }
  },

  // @see http://github.com/edejin/grunt-file-append
  'file-append': function (grunt, gruntConfig, userConfig) {
    // load plugin tasks
    grunt.loadNpmTasks('grunt-file-append')

    // default user configurations
    const uploadFolder = userConfig.uploadFolder || defaultConfig.uploadFolder
    const timestampFile = (userConfig.timestampFile || userConfig.timestampFile) ||
      (defaultConfig.timestampFile || defaultConfig.timestampFile)
    const timestampVariable = userConfig.timestampVariable || defaultConfig.timestampVariable

    // create grunt task config
    const gtcfg = gruntConfig.file_append = {}                                    // eslint-disable-line camelcase

    // add timestamp target to grunt config
    const uploadTime = new Date()
    gtcfg.timestamp = {
      files: [{
        input: `${uploadFolder}/${timestampFile}`,
        prepend: `// ${uploadTime}\nglobal.${timestampVariable} = ${uploadTime.getTime()}\n\n`
      }]
    }
  },

  // @see http://github.com/krampstudio/grunt-jsdoc
  'jsdoc': function (grunt, gruntConfig, userConfig) {                          // eslint-disable-line quote-props
    // load plugin tasks
    grunt.loadNpmTasks('grunt-jsdoc')

    // default user configurations
    const sourceFolder = userConfig.sourceFolder || defaultConfig.sourceFolder
    const docFolder = userConfig.docFolder || defaultConfig.docFolder
    const jsdocFile = userConfig.jsdocFile || defaultConfig.jsdocFile

    // create grunt task config
    const gtcfg = gruntConfig.jsdoc = {}

    // add default documentation generation target to grunt config
    gtcfg['default'] = {
      options: {
        configure: jsdocFile,
        destination: docFolder,
      },
      src: [`${sourceFolder}/*.js`, `${sourceFolder}/*.jsdoc`],
    }
  },

  // @see http://github.com/screeps/grunt-screeps
  'screeps': function (grunt, gruntConfig, userConfig) {                        // eslint-disable-line quote-props
    // load plugin tasks
    grunt.loadNpmTasks('grunt-screeps')

    // default user configurations
    const credentialsFile = userConfig.credentials || defaultConfig.credentials
    const uploadFolder = userConfig.uploadFolder || defaultConfig.uploadFolder
    let uploadTargets = userConfig.upload || defaultConfig.upload
    const uploadBranch = userConfig.uploadBranch || defaultConfig.uploadBranch

    // load user credentials
    const userCreds = require(credentialsFile)                                  // eslint-disable-line global-require
    // resolve upload target shorthands
    uploadTargets = resolveUploadTargets(uploadTargets)

    // create grunt task config
    const gtcfg = gruntConfig.screeps = {
      // default target options
      options: {
        email: userCreds.email,
        password: userCreds.password,
      }
    }

    // add upload targets to grunt config
    for (const target in uploadTargets) {
      const targetInfo = uploadTargets[target]
      gtcfg[target] = {
        options: targetInfo || {},
        src: `${uploadFolder}/*.js`,
      }
      if (!targetInfo.branch)
        gtcfg[target].options.branch = { branch: uploadBranch }
    }
  },
}


// ------------------------------------ Grunt Main -----------------------------

export default
function (grunt) {
  // load grunt user configuration
  const userConfig = require(userConfigPath)                                    // eslint-disable-line global-require

  // default user configurations
  let uploadTargets = userConfig.upload || defaultConfig.upload

  // resolve upload target shorthands
  uploadTargets = resolveUploadTargets(uploadTargets)

  // configure grunt tasks
  const gruntConfig = {}
  for (const plugin in configurePlugin.keys())
    configurePlugin[plugin](grunt, gruntConfig, userConfig)

  // prepare upload prepended tasks
  const preUploadTasks = []
  if (userConfig.uploadTimestamp || defaultConfig.uploadTimestamp)
    preUploadTasks.push('file_append:timestamp')
  // register upload tasks
  for (const target of uploadTargets) {
    grunt.registerTask(
        `upload-${target}`,
        `Upload player code. (${target})`,
        [...preUploadTasks, `screeps:${target}`])
  }

  // register documentation generation task
  grunt.registerTask(
      'doc',
      'Generate code documentation.',
      ['clean:doc', 'jsdoc:default'])
}