feat: add success and fail notification plugins

- Allow `publish` plugins to return an `Object` with information related to the releases - Add the `success` plugin hook, called when all `publish` are successful, receiving a list of release - Add the `fail` plugin hook, called when an error happens at any point, receiving a list of errors - Add detailed message for each error
2018-02-11 19:53:41 -05:00
parent 9b2f6bfed2
commit 49f5e704ba
29 changed files with 917 additions and 408 deletions
@@ -0,0 +1,118 @@
+const url = require('url');
+const {inspect} = require('util');
+const {toLower, isString} = require('lodash');
+const pkg = require('../../package.json');
+const RELEASE_TYPE = require('./release-types');
+
+const homepage = url.format({...url.parse(pkg.homepage), ...{hash: null}});
+const stringify = obj => (isString(obj) ? obj : inspect(obj, {breakLength: Infinity, depth: 2, maxArrayLength: 5}));
+const linkify = file => `${homepage}/blob/caribou/${file}`;
+
+module.exports = {
+  ENOGITREPO: () => ({
+    message: 'Not running from a git repository.',
+    details: `The \`semantic-release\` command must be executed from a Git repository.
+
+The current working directory is \`${process.cwd()}\`.
+
+Please verify your CI configuration to make sure the \`semantic-release\` command is executed from the root of the cloned repository.`,
+  }),
+  ENOREPOURL: () => ({
+    message: 'The `repositoryUrl` option is required.',
+    details: `The [repositoryUrl option](${linkify(
+      'docs/usage/configuration.md#repositoryurl'
+    )}) cannot be determined from the semantic-release configuration, the \`package.json\` nor the [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes).
+
+Please make sure to add the \`repositoryUrl\` to the [semantic-release configuration] (${linkify(
+      'docs/usage/configuration.md'
+    )}).`,
+  }),
+  EGITNOPERMISSION: ({options}) => ({
+    message: 'The push permission to the Git repository is required.',
+    details: `**semantic-release** cannot push the version tag to the branch \`${
+      options.branch
+    }\` on remote Git repository.
+
+Please refer to the [authentication configuration documentation](${linkify(
+      'docs/usage/ci-configuration.md#authentication'
+    )}) to configure the Git credentials on your CI environment.`,
+  }),
+  EINVALIDTAGFORMAT: ({tagFormat}) => ({
+    message: 'Invalid `tagFormat` option.',
+    details: `The [tagFormat](${linkify(
+      'docs/usage/configuration.md#tagformat'
+    )}) must compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description).
+
+Your configuration for the \`tagFormat\` option is \`${stringify(tagFormat)}\`.`,
+  }),
+  ETAGNOVERSION: ({tagFormat}) => ({
+    message: 'Invalid `tagFormat` option.',
+    details: `The [tagFormat](${linkify(
+      'docs/usage/configuration.md#tagformat'
+    )}) option must contain the variable \`version\` exactly once.
+
+Your configuration for the \`tagFormat\` option is \`${stringify(tagFormat)}\`.`,
+  }),
+  EPLUGINCONF: ({pluginName, pluginConf}) => ({
+    message: `The \`${pluginName}\` plugin configuration is invalid.`,
+    details: `The [${pluginName} plugin configuration](${linkify(
+      `docs/usage/plugins.md#${toLower(pluginName)}-plugin`
+    )}) if defined, must be a single or an array of plugins definition. A plugin definition is either a string or an object with a \`path\` property.
+
+    Your configuration for the \`${pluginName}\` plugin is \`${stringify(pluginConf)}\`.`,
+  }),
+  EPLUGIN: ({pluginName, pluginType}) => ({
+    message: `A plugin configured in the step ${pluginType} is not a valid semantic-release plugin.`,
+    details: `A valid \`${pluginType}\` **semantic-release** plugin must be a function or an object with a function in the property \`${pluginType}\`.
+
+The plugin \`${pluginName}\` doesn't have the property \`${pluginType}\` and cannot be used for the \`${pluginType}\` step.
+
+Please refer to the \`${pluginName}\` and [semantic-release plugins configuration](${linkify(
+      'docs/usage/plugins.md'
+    )}) documentation for more details.`,
+  }),
+  EANALYZEOUTPUT: ({result, pluginName}) => ({
+    message: 'The `analyzeCommits` plugin returned an invalid value. It must return a valid semver release type.',
+    details: `The \`analyzeCommits\` plugin must return a valid [semver](https://semver.org) release type. The valid values are: ${RELEASE_TYPE.map(
+      type => `\`${type}\``
+    ).join(', ')}.
+
+The \`analyzeCommits\` function of the \`${pluginName}\` returned \`${stringify(result)}\` instead.
+
+We recommend to report the issue to the \`${pluginName}\` authors, providing the following informations:
+- The **semantic-release** version: \`${pkg.version}\`
+- The **semantic-release** logs from your CI job
+- The value returned by the plugin: \`${stringify(result)}\`
+- A link to the **semantic-release** plugin developer guide: [${linkify('docs/developer-guide/plugin.md')}](${linkify(
+      'docs/developer-guide/plugin.md'
+    )})`,
+  }),
+  ERELEASENOTESOUTPUT: ({result, pluginName}) => ({
+    message: 'The `generateNotes` plugin returned an invalid value. It must return a `String`.',
+    details: `The \`generateNotes\` plugin must return a \`String\`.
+
+The \`generateNotes\` function of the \`${pluginName}\` returned \`${stringify(result)}\` instead.
+
+We recommend to report the issue to the \`${pluginName}\` authors, providing the following informations:
+- The **semantic-release** version: \`${pkg.version}\`
+- The **semantic-release** logs from your CI job
+- The value returned by the plugin: \`${stringify(result)}\`
+- A link to the **semantic-release** plugin developer guide: [${linkify('docs/developer-guide/plugin.md')}](${linkify(
+      'docs/developer-guide/plugin.md'
+    )})`,
+  }),
+  EPUBLISHOUTPUT: ({result, pluginName}) => ({
+    message: 'A `publish` plugin returned an invalid value. It must return an `Object`.',
+    details: `The \`publish\` plugins must return an \`Object\`.
+
+The \`publish\` function of the \`${pluginName}\` returned \`${stringify(result)}\` instead.
+
+We recommend to report the issue to the \`${pluginName}\` authors, providing the following informations:
+- The **semantic-release** version: \`${pkg.version}\`
+- The **semantic-release** logs from your CI job
+- The value returned by the plugin: \`${stringify(result)}\`
+- A link to the **semantic-release** plugin developer guide: [${linkify('docs/developer-guide/plugin.md')}](${linkify(
+      'docs/developer-guide/plugin.md'
+    )})`,
+  }),
+};
@@ -0,0 +1,61 @@
+const {isString, isFunction, isArray, isPlainObject} = require('lodash');
+const RELEASE_TYPE = require('./release-types');
+
+const validatePluginConfig = conf => isString(conf) || isString(conf.path) || isFunction(conf);
+
+module.exports = {
+  verifyConditions: {
+    default: ['@semantic-release/npm', '@semantic-release/github'],
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+  analyzeCommits: {
+    default: '@semantic-release/commit-analyzer',
+    config: {
+      validator: conf => Boolean(conf) && validatePluginConfig(conf),
+    },
+    output: {
+      validator: output => !output || RELEASE_TYPE.includes(output),
+      error: 'EANALYZEOUTPUT',
+    },
+  },
+  verifyRelease: {
+    default: false,
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+  generateNotes: {
+    default: '@semantic-release/release-notes-generator',
+    config: {
+      validator: conf => !conf || validatePluginConfig(conf),
+    },
+    output: {
+      validator: output => !output || isString(output),
+      error: 'ERELEASENOTESOUTPUT',
+    },
+  },
+  publish: {
+    default: ['@semantic-release/npm', '@semantic-release/github'],
+    config: {
+      validator: conf => Boolean(conf) && (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+    output: {
+      validator: output => !output || isPlainObject(output),
+      error: 'EPUBLISHOUTPUT',
+    },
+  },
+  success: {
+    default: ['@semantic-release/github'],
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+  fail: {
+    default: ['@semantic-release/github'],
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+};
@@ -0,0 +1 @@
+module.exports = ['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease'];
@@ -4,7 +4,7 @@ const cosmiconfig = require('cosmiconfig');
 const resolveFrom = require('resolve-from');
 const debug = require('debug')('semantic-release:config');
 const {repoUrl} = require('./git');
-const PLUGINS_DEFINITION = require('./plugins/definitions');
+const PLUGINS_DEFINITIONS = require('./definitions/plugins');
 const plugins = require('./plugins');
 const getGitAuthUrl = require('./get-git-auth-url');

@@ -25,7 +25,7 @@ module.exports = async (opts, logger) => {
        // For each plugin defined in a shareable config, save in `pluginsPath` the extendable config path,
        // so those plugin will be loaded relatively to the config file
        Object.keys(extendsOpts).reduce((pluginsPath, option) => {
-          if (PLUGINS_DEFINITION[option]) {
+          if (PLUGINS_DEFINITIONS[option]) {
            castArray(extendsOpts[option])
              .filter(plugin => isString(plugin) || (isPlainObject(plugin) && isString(plugin.path)))
              .map(plugin => (isString(plugin) ? plugin : plugin.path))
@@ -0,0 +1,7 @@
+const SemanticReleaseError = require('@semantic-release/error');
+const ERROR_DEFINITIONS = require('./definitions/errors');
+
+module.exports = (code, ctx = {}) => {
+  const {message, details} = ERROR_DEFINITIONS[code](ctx);
+  return new SemanticReleaseError(message, code, details);
+};
@@ -120,7 +120,6 @@ async function push(origin, branch) {
 *
 * @param {String} origin The remote repository URL.
 * @param {String} tagName The tag name to delete.
- * @throws {SemanticReleaseError} if the remote tag exists and references a commit that is not the local head commit.
 */
 async function deleteTag(origin, tagName) {
  // Delete the local tag
@@ -1,55 +0,0 @@
-const {isString, isFunction, isArray} = require('lodash');
-
-const RELEASE_TYPE = ['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease'];
-const validatePluginConfig = conf => isString(conf) || isString(conf.path) || isFunction(conf);
-
-module.exports = {
-  verifyConditions: {
-    default: ['@semantic-release/npm', '@semantic-release/github'],
-    config: {
-      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
-      message:
-        'The "verifyConditions" plugin, if defined, must be a single or an array of plugins definition. A plugin definition is either a string or an object with a path property.',
-    },
-  },
-  analyzeCommits: {
-    default: '@semantic-release/commit-analyzer',
-    config: {
-      validator: conf => Boolean(conf) && validatePluginConfig(conf),
-      message:
-        'The "analyzeCommits" plugin is mandatory, and must be a single plugin definition. A plugin definition is either a string or an object with a path property.',
-    },
-    output: {
-      validator: output => !output || RELEASE_TYPE.includes(output),
-      message: 'The "analyzeCommits" plugin output, if defined, must be a valid semver release type.',
-    },
-  },
-  verifyRelease: {
-    default: false,
-    config: {
-      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
-      message:
-        'The "verifyRelease" plugin, if defined, must be a single or an array of plugins definition. A plugin definition is either a string or an object with a path property.',
-    },
-  },
-  generateNotes: {
-    default: '@semantic-release/release-notes-generator',
-    config: {
-      validator: conf => !conf || validatePluginConfig(conf),
-      message:
-        'The "generateNotes" plugin, if defined, must be a single plugin definition. A plugin definition is either a string or an object with a path property.',
-    },
-    output: {
-      validator: output => !output || isString(output),
-      message: 'The "generateNotes" plugin output, if defined, must be a string.',
-    },
-  },
-  publish: {
-    default: ['@semantic-release/npm', '@semantic-release/github'],
-    config: {
-      validator: conf => Boolean(conf) && (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
-      message:
-        'The "publish" plugin is mandatory, and must be a single or an array of plugins definition. A plugin definition is either a string or an object with a path property.',
-    },
-  },
-};
@@ -1,34 +1,35 @@
-const {isArray, isObject, omit} = require('lodash');
+const {isArray, isObject, omit, castArray, isUndefined} = require('lodash');
 const AggregateError = require('aggregate-error');
-const SemanticReleaseError = require('@semantic-release/error');
-const PLUGINS_DEFINITION = require('./definitions');
+const getError = require('../get-error');
+const PLUGINS_DEFINITIONS = require('../definitions/plugins');
 const pipeline = require('./pipeline');
 const normalize = require('./normalize');

 module.exports = (options, pluginsPath, logger) => {
  const errors = [];
-  const plugins = Object.keys(PLUGINS_DEFINITION).reduce((plugins, pluginType) => {
-    const {config, output, default: def} = PLUGINS_DEFINITION[pluginType];
+  const plugins = Object.keys(PLUGINS_DEFINITIONS).reduce((plugins, pluginType) => {
+    const {config, default: def} = PLUGINS_DEFINITIONS[pluginType];
    let pluginConfs;
-    if (options[pluginType]) {
+
+    if (isUndefined(options[pluginType])) {
+      pluginConfs = def;
+    } else {
      // If an object is passed and the path is missing, set the default one for single plugins
      if (isObject(options[pluginType]) && !options[pluginType].path && !isArray(def)) {
        options[pluginType].path = def;
      }
      if (config && !config.validator(options[pluginType])) {
-        errors.push(new SemanticReleaseError(config.message, 'EPLUGINCONF'));
+        errors.push(getError('EPLUGINCONF', {pluginType, pluginConf: options[pluginType]}));
        return plugins;
      }
      pluginConfs = options[pluginType];
-    } else {
-      pluginConfs = def;
    }

-    const globalOpts = omit(options, Object.keys(PLUGINS_DEFINITION));
+    const globalOpts = omit(options, Object.keys(PLUGINS_DEFINITIONS));

-    plugins[pluginType] = isArray(pluginConfs)
-      ? pipeline(pluginConfs.map(conf => normalize(pluginType, pluginsPath, globalOpts, conf, logger, output)))
-      : normalize(pluginType, pluginsPath, globalOpts, pluginConfs, logger, output);
+    plugins[pluginType] = pipeline(
+      castArray(pluginConfs).map(conf => normalize(pluginType, pluginsPath, globalOpts, conf, logger))
+    );

    return plugins;
  }, {});
@@ -1,15 +1,18 @@
 const {dirname} = require('path');
-const {inspect} = require('util');
-const SemanticReleaseError = require('@semantic-release/error');
-const {isString, isObject, isFunction, noop, cloneDeep} = require('lodash');
+const {isString, isPlainObject, isFunction, noop, cloneDeep} = require('lodash');
 const resolveFrom = require('resolve-from');
+const getError = require('../get-error');
+const {extractErrors} = require('../utils');
+const PLUGINS_DEFINITIONS = require('../definitions/plugins');

-module.exports = (pluginType, pluginsPath, globalOpts, pluginOpts, logger, validator) => {
+module.exports = (pluginType, pluginsPath, globalOpts, pluginOpts, logger) => {
  if (!pluginOpts) {
    return noop;
  }

  const {path, ...config} = isString(pluginOpts) || isFunction(pluginOpts) ? {path: pluginOpts} : pluginOpts;
+  const pluginName = isFunction(path) ? `[Function: ${path.name}]` : path;
+
  if (!isFunction(pluginOpts)) {
    if (pluginsPath[path]) {
      logger.log('Load plugin %s from %s in shareable config %s', pluginType, path, pluginsPath[path]);
@@ -28,21 +31,27 @@ module.exports = (pluginType, pluginsPath, globalOpts, pluginOpts, logger, valid
  let func;
  if (isFunction(plugin)) {
    func = plugin.bind(null, cloneDeep({...globalOpts, ...config}));
-  } else if (isObject(plugin) && plugin[pluginType] && isFunction(plugin[pluginType])) {
+  } else if (isPlainObject(plugin) && plugin[pluginType] && isFunction(plugin[pluginType])) {
    func = plugin[pluginType].bind(null, cloneDeep({...globalOpts, ...config}));
  } else {
-    throw new SemanticReleaseError(
-      `The ${pluginType} plugin must be a function, or an object with a function in the property ${pluginType}.`,
-      'EPLUGINCONF'
-    );
+    throw getError('EPLUGIN', {pluginType, pluginName});
  }

-  return async input => {
-    const result = await func(cloneDeep(input));
-
-    if (validator && !validator.validator(result)) {
-      throw new Error(`${validator.message} Received: ${inspect(result)}`);
-    }
-    return result;
-  };
+  return Object.defineProperty(
+    async input => {
+      const definition = PLUGINS_DEFINITIONS[pluginType];
+      try {
+        const result = await func(cloneDeep(input));
+        if (definition && definition.output && !definition.output.validator(result)) {
+          throw getError(PLUGINS_DEFINITIONS[pluginType].output.error, {result, pluginName});
+        }
+        return result;
+      } catch (err) {
+        extractErrors(err).forEach(err => Object.assign(err, {pluginName}));
+        throw err;
+      }
+    },
+    'pluginName',
+    {value: pluginName, writable: false, enumerable: true}
+  );
 };
@@ -1,37 +1,55 @@
-const {identity, isFunction} = require('lodash');
-const pReflect = require('p-reflect');
+const {identity} = require('lodash');
 const pReduce = require('p-reduce');
 const AggregateError = require('aggregate-error');
+const {extractErrors} = require('../utils');

-module.exports = steps => async (input, settleAll = false, getNextInput = identity) => {
+/**
+ * A Function that execute a list of function sequencially. If at least one Function ins the pipeline throw an Error or rejects, the pipeline function rejects as well.
+ *
+ * @typedef {Function} Pipeline
+ * @param {Any} input Argument to pass to the first step in the pipeline.
+ * @param {Object} options Pipeline options.
+ * @param {Boolean} [options.settleAll=false] If `true` all the steps in the pipeline are executed, even if one rejects, if `false` the execution stops after a steps rejects.
+ * @param {Function} [options.getNextInput=identity] Function called after each step is executed, with the last and current step results; the returned value will be used as the argument of the next step.
+ * @param {Function} [options.transform=identity] Function called after each step is executed, with the current step result and the step function; the returned value will be saved in the pipeline results.
+ *
+ * @return {Array<*>|*} An Array with the result of each step in the pipeline; if there is only 1 step in the pipeline, the result of this step is returned directly.
+ *
+ * @throws {AggregateError|Error} An AggregateError with the errors of each step in the pipeline that rejected; if there is only 1 step in the pipeline, the error of this step is thrown directly.
+ */
+
+/**
+ * Create a Pipeline with a list of Functions.
+ *
+ * @param {Array<Function>} steps The list of Function to execute.
+ * @return {Pipeline} A Function that execute the `steps` sequencially
+ */
+module.exports = steps => async (input, {settleAll = false, getNextInput = identity, transform = identity} = {}) => {
  const results = [];
  const errors = [];
  await pReduce(
    steps,
-    async (prevResult, nextStep) => {
+    async (lastResult, step) => {
      let result;
-
-      // Call the next step with the input computed at the end of the previous iteration and save intermediary result
-      if (settleAll) {
-        const {isFulfilled, value, reason} = await pReflect(nextStep(prevResult));
-        result = isFulfilled ? value : reason;
-        if (isFulfilled) {
-          results.push(result);
-        } else {
-          errors.push(...(result && isFunction(result[Symbol.iterator]) ? result : [result]));
-        }
-      } else {
-        result = await nextStep(prevResult);
+      try {
+        // Call the step with the input computed at the end of the previous iteration and save intermediary result
+        result = await transform(await step(lastResult), step);
        results.push(result);
+      } catch (err) {
+        if (settleAll) {
+          errors.push(...extractErrors(err));
+          result = err;
+        } else {
+          throw err;
+        }
      }
-
-      // Prepare input for next step, passing the result of the previous iteration and the current one
-      return getNextInput(prevResult, result);
+      // Prepare input for the next step, passing the result of the last iteration (or initial parameter for the first iteration) and the current one
+      return getNextInput(lastResult, result);
    },
    input
  );
  if (errors.length > 0) {
-    throw new AggregateError(errors);
+    throw errors.length === 1 ? errors[0] : new AggregateError(errors);
  }
-  return results;
+  return results.length <= 1 ? results[0] : results;
 };
@@ -0,0 +1,7 @@
+const {isFunction} = require('lodash');
+
+function extractErrors(err) {
+  return err && isFunction(err[Symbol.iterator]) ? [...err] : [err];
+}
+
+module.exports = {extractErrors};
@@ -1,44 +1,29 @@
 const {template} = require('lodash');
-const SemanticReleaseError = require('@semantic-release/error');
 const AggregateError = require('aggregate-error');
 const {isGitRepo, verifyAuth, verifyTagName} = require('./git');
+const getError = require('./get-error');

 module.exports = async (options, branch, logger) => {
  const errors = [];

  if (!await isGitRepo()) {
-    logger.error('Semantic-release must run from a git repository.');
-    return false;
-  }
-
-  if (!options.repositoryUrl) {
-    errors.push(new SemanticReleaseError('The repositoryUrl option is required', 'ENOREPOURL'));
+    errors.push(getError('ENOGITREPO'));
+  } else if (!options.repositoryUrl) {
+    errors.push(getError('ENOREPOURL'));
  } else if (!await verifyAuth(options.repositoryUrl, options.branch)) {
-    errors.push(
-      new SemanticReleaseError(
-        `The git credentials doesn't allow to push on the branch ${options.branch}.`,
-        'EGITNOPERMISSION'
-      )
-    );
+    errors.push(getError('EGITNOPERMISSION', {options}));
  }

  // Verify that compiling the `tagFormat` produce a valid Git tag
  if (!await verifyTagName(template(options.tagFormat)({version: '0.0.0'}))) {
-    errors.push(
-      new SemanticReleaseError('The tagFormat template must compile to a valid Git tag format', 'EINVALIDTAGFORMAT')
-    );
+    errors.push(getError('EINVALIDTAGFORMAT', {tagFormat: options.tagFormat}));
  }

  // Verify the `tagFormat` contains the variable `version` by compiling the `tagFormat` template
  // with a space as the `version` value and verify the result contains the space.
  // The space is used as it's an invalid tag character, so it's guaranteed to no be present in the `tagFormat`.
  if ((template(options.tagFormat)({version: ' '}).match(/ /g) || []).length !== 1) {
-    errors.push(
-      new SemanticReleaseError(
-        `The tagFormat template must contain the variable "\${version}" exactly once`,
-        'ETAGNOVERSION'
-      )
-    );
+    errors.push(getError('ETAGNOVERSION', {tagFormat: options.tagFormat}));
  }

  if (errors.length > 0) {
				`@@ -0,0 +1 @@`
				`module.exports = ['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease'];`