Add improved error messages

Author: wooorm

Diff for: lib/index.js

@@ -65,9 +65,22 @@ export function fromXml(value) {
       preserveXmlDeclaration: true
     })
   } catch (error_) {
-    const error = /** @type {XmlError} */ (error_)
-    const point = loc.toPoint(error.pos)
-    throw new VFileMessage(error.message, point, 'xast-util-from-xml:error')
+    const cause = /** @type {XmlError} */ (error_)
+    const place = loc.toPoint(cause.pos)
+    const message = new VFileMessage(
+      'Could not parse XML with `@rgrove/parse-xml`',
+      {
+        cause,
+        place,
+        ruleId: 'error',
+        source: 'xast-util-from-xml'
+      }
+    )
+
+    message.fatal = true
+    message.url = 'https://github.com/syntax-tree/xast-util-from-xml#throws'
+
+    throw message
   }
 
   const state = {location: loc}

Diff for: readme.md

@@ -136,13 +136,21 @@ Parse a string of XML to a xast tree.
 
 ##### Parameters
 
-*   `value` (`string` or `Buffer` in UTF-8).
+*   `value` (`Uint8Array` in UTF-8 or `string`).
     — serialized XML
 
 ##### Returns
 
 xast root ([`Root`][root]).
 
+###### Throws
+
+When the XML cannot be parsed with `@rgrove/parse-xml`, a
+[`VFileMessage`][vfile-message] is thrown.
+
+This can for example happen when passing archaic or unsafe XML (such as
+entities), or just otherwise invalid XML such as missnested tags.
+
 ## Types
 
 This package is fully typed with [TypeScript][].
@@ -234,6 +242,8 @@ abide by its terms.
 
 [root]: https://github.com/syntax-tree/xast#root
 
+[vfile-message]: https://github.com/vfile/vfile-message
+
 [parse-xml]: https://github.com/rgrove/parse-xml
 
 [xast-util-to-xml]: https://github.com/syntax-tree/xast-util-to-xml

Diff for: test/index.js

@@ -21,7 +21,7 @@ test('fromXml', async function (t) {
       fromXml('<root unquoted=attribute>')
       assert.fail()
     } catch (error) {
-      assert.match(String(error), /^1:16: Attribute value expected/)
+      assert.match(String(error), /^1:16: Could not parse XML/)
     }
   })
 
@@ -30,7 +30,7 @@ test('fromXml', async function (t) {
       fromXml('<!ENTITY>')
       assert.fail()
     } catch (error) {
-      assert.match(String(error), /^1:1: Root element is missing or invalid/)
+      assert.match(String(error), /^1:1: Could not parse XML/)
     }
   })
 
@@ -39,7 +39,7 @@ test('fromXml', async function (t) {
       fromXml('<root>&foo;</root>')
       assert.fail()
     } catch (error) {
-      assert.match(String(error), /^1:7: Named entity isn't defined/)
+      assert.match(String(error), /^1:7: Could not parse XML/)
     }
   })
 
@@ -48,7 +48,7 @@ test('fromXml', async function (t) {
       fromXml('<root>&copy;</root>')
       assert.fail()
     } catch (error) {
-      assert.match(String(error), /^1:7: Named entity isn't defined/)
+      assert.match(String(error), /^1:7: Could not parse XML/)
     }
   })
 
@@ -57,7 +57,7 @@ test('fromXml', async function (t) {
       fromXml('<root><a><b><c/></a></b></root>')
       assert.fail()
     } catch (error) {
-      assert.match(String(error), /^1:17: Missing end tag for element/)
+      assert.match(String(error), /^1:17: Could not parse XML/)
     }
   })
 })