feat(MacroError): add MacroError (#25)

Closes #22

.all-contributorsrc

@@ -24,7 +24,9 @@
       "name": "Sunil Pai",
       "avatar_url": "https://avatars1.githubusercontent.com/u/18808?v=3",
       "profile": "https://github.com/threepointone",
-      "contributions": []
+      "contributions": [
+        "ideas"
+      ]
     },
     {
       "login": "suchipi",
@@ -35,6 +37,24 @@
         "question",
         "doc"
       ]
+    },
+    {
+      "login": "dralletje",
+      "name": "Michiel Dral",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/767261?v=4",
+      "profile": "http://twitter.com/dralletje",
+      "contributions": [
+        "ideas"
+      ]
+    },
+    {
+      "login": "tkh44",
+      "name": "Kye Hohenberger",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/662750?v=4",
+      "profile": "https://github.com/tkh44",
+      "contributions": [
+        "ideas"
+      ]
     }
   ]
 }

README.md

@@ -13,7 +13,7 @@ Enables zero-config, importable babel plugins
 [![downloads][downloads-badge]][npmchart]
 [![MIT License][license-badge]][LICENSE]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
 [![Donate][donate-badge]][donate]
 [![Code of Conduct][coc-badge]][coc]
@@ -237,8 +237,8 @@ turned into macros.
 Thanks goes to these people ([emoji key][emojis]):
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-| [<img src="https://avatars.githubusercontent.com/u/1500684?v=3" width="100px;"/><br /><sub>Kent C. Dodds</sub>](https://kentcdodds.com)<br />[💻](https://github.com/kentcdodds/babel-macros/commits?author=kentcdodds "Code") [📖](https://github.com/kentcdodds/babel-macros/commits?author=kentcdodds "Documentation") [🚇](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/kentcdodds/babel-macros/commits?author=kentcdodds "Tests") | [<img src="https://avatars1.githubusercontent.com/u/18808?v=3" width="100px;"/><br /><sub>Sunil Pai</sub>](https://github.com/threepointone)<br /> | [<img src="https://avatars3.githubusercontent.com/u/1341513?v=3" width="100px;"/><br /><sub>Stephen Scott</sub>](http://suchipi.com/)<br />[💬](#question-suchipi "Answering Questions") [📖](https://github.com/kentcdodds/babel-macros/commits?author=suchipi "Documentation") |
-| :---: | :---: | :---: |
+| [<img src="https://avatars.githubusercontent.com/u/1500684?v=3" width="100px;"/><br /><sub>Kent C. Dodds</sub>](https://kentcdodds.com)<br />[💻](https://github.com/kentcdodds/babel-macros/commits?author=kentcdodds "Code") [📖](https://github.com/kentcdodds/babel-macros/commits?author=kentcdodds "Documentation") [🚇](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/kentcdodds/babel-macros/commits?author=kentcdodds "Tests") | [<img src="https://avatars1.githubusercontent.com/u/18808?v=3" width="100px;"/><br /><sub>Sunil Pai</sub>](https://github.com/threepointone)<br />[🤔](#ideas-threepointone "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/1341513?v=3" width="100px;"/><br /><sub>Stephen Scott</sub>](http://suchipi.com/)<br />[💬](#question-suchipi "Answering Questions") [📖](https://github.com/kentcdodds/babel-macros/commits?author=suchipi "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/767261?v=4" width="100px;"/><br /><sub>Michiel Dral</sub>](http://twitter.com/dralletje)<br />[🤔](#ideas-dralletje "Ideas, Planning, & Feedback") | [<img src="https://avatars2.githubusercontent.com/u/662750?v=4" width="100px;"/><br /><sub>Kye Hohenberger</sub>](https://github.com/tkh44)<br />[🤔](#ideas-tkh44 "Ideas, Planning, & Feedback") |
+| :---: | :---: | :---: | :---: | :---: |
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.

__mocks__/error-thrower.macro.js

@@ -0,0 +1,8 @@
+// const printAST = require('ast-pretty-print')
+const {createMacro} = require('../src')
+
+module.exports = createMacro(evalMacro)
+
+function evalMacro() {
+  throw new Error('not helpful')
+}

error.js

@@ -0,0 +1 @@
+module.exports = require('./dist').MacroError

other/docs/author.md

@@ -7,7 +7,7 @@
 A macro is a JavaScript module that exports a function. Here's a simple example:
 
 ```javascript
-const createMacro = require('babel-macros/create')
+const {create: createMacro} = require('babel-macros')
 
 // `createMacros` is simply a function that ensures your macro is only
 // called in the context of a babel transpilation and will throw an
@@ -146,6 +146,32 @@ you're given. For that check out [the babel handbook][babel-handbook].
 > One other thing to note is that after your macro has run, babel-macros will
 > remove the import/require statement for you.
 
+## Throwing Helpful Errors
+
+Debugging stuff that transpiles your code is the worst, especially for
+beginners. That's why it's important that you make assertions, and catch errors
+to throw more meaningful errors with helpful information for the developer to
+know what to do to resolve the issue.
+
+In an effort to make this easier for you, `babel-macros` will wrap the
+invocation of your plugin in a `try/catch` and throw as helpful an error message
+as possible for you.
+
+To make it even better, you can throw your own with more context. For example:
+
+```javascript
+const {create: createMacro, MacroError} = require('babel-macros')
+
+module.exports = createMacro(myMacro)
+
+function myMacro({references, state, babel}) {
+  // something unexpected happens:
+  throw new MacroError(
+    'Some helpful and contextual message. Learn more: ' +
+      'https://github.com/your-org/your-repo/blob/master/docs/errors.md#learn-more-about-eror-title'
+  )
+}
+```
 
 ## Testing your macro
 

package.json

@@ -12,7 +12,7 @@
     "validate": "kcd-scripts validate",
     "precommit": "kcd-scripts precommit"
   },
-  "files": ["dist", "create.js"],
+  "files": ["dist", "create.js", "error.js"],
   "keywords": [
     "babel-plugin",
     "macros",
@@ -26,7 +26,7 @@
   "devDependencies": {
     "ast-pretty-print": "^2.0.0",
     "babel-core": "^6.25.0",
-    "babel-plugin-tester": "^3.2.2",
+    "babel-plugin-tester": "^4.0.0",
     "babylon": "6.17.4",
     "kcd-scripts": "0.3.4"
   },

src/__tests__/__snapshots__/index.js.snap

@@ -1,81 +1,81 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`2. does nothing but remove macros if it is unused 1`] = `
+exports[`Supports named imports 1`] = `
 
-import foo from './some-macros-that-doesnt-even-need-to-exist.macro'
-export default 'something else'
+import {css as CSS, styled as STYLED} from './fixtures/emotion.macro'
+const red = CSS\`
+  background-color: red;
+\`
+
+const Div = STYLED.div\`
+  composes: \${red}
+  color: blue;
+\`
 
       ↓ ↓ ↓ ↓ ↓ ↓
 
-export default 'something else';
+const red = 'background-color: red;';
+
+const Div = STYLED.div\`undefined\`;
 
 `;
 
-exports[`3. works with import 1`] = `
+exports[`Works as a JSXElement 1`] = `
 
-import myEval from './fixtures/eval.macro'
-const x = myEval\`34 + 45\`
+import MyEval from './fixtures/eval.macro'
+const x = <MyEval>34 + 45</MyEval>
 
       ↓ ↓ ↓ ↓ ↓ ↓
 
 const x = 79;
 
 `;
 
-exports[`4. works with require 1`] = `
+exports[`appends the npm URL for errors thrown by node modules 1`] = `
 
-const evaler = require('./fixtures/eval.macro')
-const x = evaler\`34 + 45\`
+import errorThrower from 'error-thrower.macro'
+errorThrower('hi')
 
       ↓ ↓ ↓ ↓ ↓ ↓
 
-const x = 79;
+Error: <PROJECT_ROOT>/src/__tests__/index.js: error-thrower.macro: not helpful Learn more: https://www.npmjs.com/package/error-thrower.macro
 
 `;
 
-exports[`5. works with function calls 1`] = `
+exports[`does nothing but remove macros if it is unused 1`] = `
 
-import myEval from './fixtures/eval.macro'
-const x = myEval('34 + 45')
+import foo from './some-macros-that-doesnt-even-need-to-exist.macro'
+export default 'something else'
 
       ↓ ↓ ↓ ↓ ↓ ↓
 
-const x = 79;
+export default 'something else';
 
 `;
 
-exports[`6. Works as a JSXElement 1`] = `
+exports[`forwards MacroErrors thrown by the macro 1`] = `
 
-import MyEval from './fixtures/eval.macro'
-const x = <MyEval>34 + 45</MyEval>
+import errorThrower from './fixtures/macro-error-thrower.macro'
+errorThrower('hey')
 
       ↓ ↓ ↓ ↓ ↓ ↓
 
-const x = 79;
+MacroError: <PROJECT_ROOT>/src/__tests__/index.js: very helpful
 
 `;
 
-exports[`7. Supports named imports 1`] = `
+exports[`prepends the relative path for errors thrown by the macro 1`] = `
 
-import {css as CSS, styled as STYLED} from './fixtures/emotion.macro'
-const red = CSS\`
-  background-color: red;
-\`
-
-const Div = STYLED.div\`
-  composes: \${red}
-  color: blue;
-\`
+import errorThrower from './fixtures/error-thrower.macro'
+errorThrower('hey')
 
       ↓ ↓ ↓ ↓ ↓ ↓
 
-const red = 'background-color: red;';
-
-const Div = STYLED.div\`undefined\`;
+Error: <PROJECT_ROOT>/src/__tests__/index.js: ./fixtures/error-thrower.macro: very unhelpful
 
 `;
 
-exports[`8. supports macros from node_modules 1`] = `
+exports[`supports macros from node_modules 1`] = `
 
 import fakeMacro from 'fake/macro'
 fakeMacro('hi')
@@ -87,3 +87,36 @@ fakeMacro('hi');
 `;
 
 exports[`throws error if it is not transpiled 1`] = `The macro you imported from "untranspiled.macro" is being executed outside the context of compilation with babel-macros. This indicates that you don't have the babel plugin "babel-macros" configured correctly. Please see the documentation for how to configure babel-macros properly: https://github.com/kentcdodds/babel-macros/blob/master/other/docs/user.md`;
+
+exports[`works with function calls 1`] = `
+
+import myEval from './fixtures/eval.macro'
+const x = myEval('34 + 45')
+
+      ↓ ↓ ↓ ↓ ↓ ↓
+
+const x = 79;
+
+`;
+
+exports[`works with import 1`] = `
+
+import myEval from './fixtures/eval.macro'
+const x = myEval\`34 + 45\`
+
+      ↓ ↓ ↓ ↓ ↓ ↓
+
+const x = 79;
+
+`;
+
+exports[`works with require 1`] = `
+
+const evaler = require('./fixtures/eval.macro')
+const x = evaler\`34 + 45\`
+
+      ↓ ↓ ↓ ↓ ↓ ↓
+
+const x = 79;
+
+`;

src/__tests__/fixtures/error-thrower.macro.js

@@ -0,0 +1,8 @@
+// const printAST = require('ast-pretty-print')
+const {createMacro} = require('../../')
+
+module.exports = createMacro(evalMacro)
+
+function evalMacro() {
+  throw new Error('very unhelpful')
+}

src/__tests__/fixtures/macro-error-thrower.macro.js

@@ -0,0 +1,8 @@
+// const printAST = require('ast-pretty-print')
+const {createMacro, MacroError} = require('../../')
+
+module.exports = createMacro(evalMacro)
+
+function evalMacro() {
+  throw new MacroError('very helpful')
+}

src/__tests__/index.js

@@ -103,6 +103,30 @@ pluginTester({
         expect(fakeMacro.mock.calls[0].babel).toBe(babel)
       },
     },
+    {
+      title: 'forwards MacroErrors thrown by the macro',
+      error: true,
+      code: `
+        import errorThrower from './fixtures/macro-error-thrower.macro'
+        errorThrower('hey')
+      `,
+    },
+    {
+      title: 'prepends the relative path for errors thrown by the macro',
+      error: true,
+      code: `
+        import errorThrower from './fixtures/error-thrower.macro'
+        errorThrower('hey')
+      `,
+    },
+    {
+      title: 'appends the npm URL for errors thrown by node modules',
+      error: true,
+      code: `
+        import errorThrower from 'error-thrower.macro'
+        errorThrower('hi')
+      `,
+    },
   ],
 })