feat: add details to error messages

Author: pvdlg

lib/definitions/errors.js

@@ -0,0 +1,49 @@
+const url = require('url');
+const pkg = require('../../package.json');
+
+const homepage = url.format({...url.parse(pkg.homepage), ...{hash: null}});
+const linkify = file => `${homepage}/blob/master/${file}`;
+
+module.exports = {
+  EINVALIDNPMPUBLISH: ({npmPublish}) => ({
+    message: 'Invalid `npmPublish` option.',
+    details: `The [npmPublish option](${linkify('README.md#npmpublish')}) option, if defined, must be a \`Boolean\`.
+
+Your configuration for the \`npmPublish\` option is \`${npmPublish}\`.`,
+  }),
+  EINVALIDTARBALLDIR: ({tarballDir}) => ({
+    message: 'Invalid `tarballDir` option.',
+    details: `The [tarballDir option](${linkify('README.md#tarballdir')}) option, if defined, must be a \`String\`.
+
+Your configuration for the \`tarballDir\` option is \`${tarballDir}\`.`,
+  }),
+  EINVALIDPKGROOT: ({pkgRoot}) => ({
+    message: 'Invalid `pkgRoot` option.',
+    details: `The [pkgRoot option](${linkify('README.md#pkgroot')}) option, if defined, must be a \`String\`.
+
+Your configuration for the \`pkgRoot\` option is \`${pkgRoot}\`.`,
+  }),
+  EINVALIDNPMTOKEN: ({registry}) => ({
+    message: 'Invalid npm token.',
+    details: `The [npm token](${linkify(
+      'README.md#npm-registry-authentication'
+    )}) configured in the \`NPM_TOKEN\` environment variable must be a valid [token](https://docs.npmjs.com/getting-started/working_with_tokens) allowing to publish to the registry \`${registry}\`.
+
+If you are using Two-Factor Authentication, make configure the \`auth-only\` [level](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported. **semantic-release** cannot publish with the default \`auth-and-writes\` level.
+
+Please make sure to set the \`NPM_TOKEN\` environment variable in your CI with the exact value of the npm token.`,
+  }),
+
+  ENOPKGNAME: () => ({
+    message: 'Missing `name` property in `package.json`.',
+    details: `The \`package.json\`'s [name](https://docs.npmjs.com/files/package.json#name) property is required in order to publish a package to the npm registry.
+
+Please make sure to add a valid \`name\` for your package in your \`package.json\`.`,
+  }),
+  ENOPKG: () => ({
+    message: 'Missing `package.json` file.',
+    details: `A [package.json file](https://docs.npmjs.com/files/package.json) at the root of your project is required to release on npm.
+
+Please follow the [npm guideline](https://docs.npmjs.com/getting-started/creating-node-modules) to create a valid \`pacakge.json\` file.`,
+  }),
+};

lib/get-error.js

@@ -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);
+};

lib/get-pkg.js

@@ -1,6 +1,6 @@
 const readPkg = require('read-pkg');
 const AggregateError = require('aggregate-error');
-const SemanticReleaseError = require('@semantic-release/error');
+const getError = require('./get-error');
 
 module.exports = async pkgRoot => {
   const errors = [];
@@ -10,17 +10,19 @@ module.exports = async pkgRoot => {
     pkg = await readPkg(pkgRoot);
 
     if (!pkg.name) {
-      errors.push(new SemanticReleaseError('No "name" found in package.json.', 'ENOPKGNAME'));
+      errors.push(getError('ENOPKGNAME'));
     }
   } catch (err) {
     if (err.code === 'ENOENT') {
-      errors.push(new SemanticReleaseError('A package.json file is required to release on npm.', 'ENOPKG'));
+      errors.push(getError('ENOPKG'));
     } else {
       errors.push(err);
     }
   }
+
   if (errors.length > 0) {
     throw new AggregateError(errors);
   }
+
   return pkg;
 };

lib/verify-auth.js

@@ -1,7 +1,7 @@
 const execa = require('execa');
 const normalizeUrl = require('normalize-url');
 const AggregateError = require('aggregate-error');
-const SemanticReleaseError = require('@semantic-release/error');
+const getError = require('./get-error');
 const getRegistry = require('./get-registry');
 const setNpmrcAuth = require('./set-npmrc-auth');
 
@@ -20,7 +20,7 @@ module.exports = async (
     try {
       await execa('npm', ['whoami', '--registry', registry]);
     } catch (err) {
-      throw new AggregateError([new SemanticReleaseError('Invalid npm token.', 'EINVALIDNPMTOKEN')]);
+      throw new AggregateError([getError('EINVALIDNPMTOKEN', {registry})]);
     }
   }
 };

lib/verify-config.js

@@ -1,22 +1,19 @@
 const {isString, isUndefined, isBoolean} = require('lodash');
-const SemanticReleaseError = require('@semantic-release/error');
+const getError = require('./get-error');
 
 module.exports = ({npmPublish, tarballDir, pkgRoot}) => {
   const errors = [];
   if (!isUndefined(npmPublish) && !isBoolean(npmPublish)) {
-    errors.push(
-      new SemanticReleaseError('The "npmPublish" options, if defined, must be a Boolean.', 'EINVALIDNPMPUBLISH')
-    );
+    errors.push(getError('EINVALIDNPMPUBLISH', {npmPublish}));
   }
 
   if (!isUndefined(tarballDir) && !isString(tarballDir)) {
-    errors.push(
-      new SemanticReleaseError('The "tarballDir" options, if defined, must be a String.', 'EINVALIDTARBALLDIR')
-    );
+    errors.push(getError('EINVALIDTARBALLDIR', {tarballDir}));
   }
 
   if (!isUndefined(pkgRoot) && !isString(pkgRoot)) {
-    errors.push(new SemanticReleaseError('The "pkgRoot" options, if defined, must be a String.', 'EINVALIDPKGROOT'));
+    errors.push(getError('EINVALIDPKGROOT', {pkgRoot}));
   }
+
   return errors;
 };

package.json

@@ -16,7 +16,7 @@
     "Gregor Martynus (https://twitter.com/gr2m)"
   ],
   "dependencies": {
-    "@semantic-release/error": "^2.1.0",
+    "@semantic-release/error": "^2.2.0",
     "aggregate-error": "^1.0.0",
     "execa": "^0.9.0",
     "fs-extra": "^5.0.0",