Add improved error messages

Author: wooorm

lib/index.js

@@ -96,18 +96,22 @@ export function fromJs(value, options) {
       onComment: comments
     })
   } catch (error) {
-    const exception = /** @type {AcornError} */ (error)
-    exception.message = exception.message.replace(/ \((\d+):(\d+)\)$/, '')
+    const cause = /** @type {AcornError} */ (error)
 
-    throw new VFileMessage(
-      exception,
-      {
-        line: exception.loc.line,
-        column: exception.loc.column + 1,
-        offset: exception.pos
+    const message = new VFileMessage('Could not parse JavaScript with Acorn', {
+      cause,
+      place: {
+        line: cause.loc.line,
+        column: cause.loc.column + 1,
+        offset: cause.pos
       },
-      'esast-util-from-js:acorn'
-    )
+      ruleId: 'acorn',
+      source: 'esast-util-from-js'
+    })
+
+    message.url = 'https://github.com/syntax-tree/esast-util-from-js#throws'
+
+    throw message
   }
 
   tree.comments = comments

package.json

@@ -39,7 +39,7 @@
     "@types/estree-jsx": "^1.0.0",
     "acorn": "^8.0.0",
     "esast-util-from-estree": "^1.0.0",
-    "vfile-message": "^3.0.0"
+    "vfile-message": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

readme.md

@@ -135,6 +135,15 @@ Parse JavaScript to an esast.
 
 Tree ([`Node`][node]).
 
+###### Throws
+
+When the JavaScript cannot be parsed with `acorn`, a
+[`VFileMessage`][vfile-message] is thrown.
+
+This can for example happen when passing modern syntax (you could maybe use a
+newer `version`, or it might be that the syntax is not yet supported), or just
+otherwise invalid JavaScript (you might need a plugin).
+
 ### `Options`
 
 Configuration (TypeScript type).
@@ -309,6 +318,8 @@ abide by its terms.
 
 [estree-util-to-js]: https://github.com/syntax-tree/estree-util-to-js
 
+[vfile-message]: https://github.com/vfile/vfile-message
+
 [fromjs]: #fromjsvalue-options
 
 [options]: #options

test/index.js

@@ -69,7 +69,7 @@ test('fromJs', () => {
     function () {
       fromJs('import "a"')
     },
-    /'import' and 'export' may appear only with 'sourceType: module'/,
+    /Could not parse JavaScript with Acorn/,
     'should fail on an import w/o `module: true`'
   )