Add support for file in options

Related-to: remarkjs/remark#1272.

Author: wooorm

lib/state.js

@@ -11,6 +11,8 @@
  * @typedef {import('mdast').Nodes} MdastNodes
  * @typedef {import('mdast').Parents} MdastParents
  *
+ * @typedef {import('vfile').VFile} VFile
+ *
  * @typedef {import('./footer.js').FootnoteBackContentTemplate} FootnoteBackContentTemplate
  * @typedef {import('./footer.js').FootnoteBackLabelTemplate} FootnoteBackLabelTemplate
  */
@@ -56,6 +58,8 @@
  *   at that place.
  *   It can also break polyfills.
  *   Using a prefix solves these problems.
+ * @property {VFile | null | undefined} [file]
+ *   Corresponding virtual file representing the input document (optional).
  * @property {FootnoteBackContentTemplate | string | null | undefined} [footnoteBackContent]
  *   Content of the backreference back to references (default: `defaultFootnoteBackContent`).
  *

package.json

@@ -40,7 +40,8 @@
     "micromark-util-sanitize-uri": "^2.0.0",
     "trim-lines": "^3.0.0",
     "unist-util-position": "^5.0.0",
-    "unist-util-visit": "^5.0.0"
+    "unist-util-visit": "^5.0.0",
+    "vfile": "^6.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

readme.md

@@ -351,6 +351,8 @@ Configuration (TypeScript type).
 *   `clobberPrefix` (`string`, default: `'user-content-'`)
     — prefix to use before the `id` property on footnotes to prevent them from
     *clobbering*
+*   `file` ([`VFile`][vfile], optional)
+    — corresponding virtual file representing the input document
 *   `footnoteBackContent`
     ([`FootnoteBackContentTemplate`][api-footnote-back-content-template]
     or `string`, default:
@@ -1687,6 +1689,8 @@ abide by its terms.
 
 [remark-rehype]: https://github.com/remarkjs/remark-rehype
 
+[vfile]: https://github.com/vfile/vfile
+
 [clobber-example]: https://github.com/rehypejs/rehype-sanitize#example-headings-dom-clobbering
 
 [github-markdown-css]: https://github.com/sindresorhus/github-markdown-css

test/core.js

@@ -6,7 +6,8 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 import {h} from 'hastscript'
-import {toHast} from 'mdast-util-to-hast'
+import {toHast, defaultHandlers} from 'mdast-util-to-hast'
+import {VFile} from 'vfile'
 
 test('toHast', async function (t) {
   await t.test('should expose the public api', async function () {
@@ -272,16 +273,16 @@ test('toHast', async function (t) {
         {type: 'paragraph', children: [{type: 'text', value: 'alpha'}]},
         {
           handlers: {
-            paragraph(h, /** @type {Paragraph} */ node) {
+            paragraph(state, /** @type {Paragraph} */ node) {
               /** @type {Element} */
               const result = {
                 type: 'element',
                 tagName: 'p',
                 properties: {},
                 children: [{type: 'text', value: 'bravo'}]
               }
-              h.patch(node, result)
-              return h.applyData(node, result)
+              state.patch(node, result)
+              return state.applyData(node, result)
             }
           }
         }
@@ -290,6 +291,29 @@ test('toHast', async function (t) {
     )
   })
 
+  await t.test('should support files', async function () {
+    const file = new VFile('alpha')
+
+    assert.deepEqual(
+      toHast(
+        {type: 'paragraph', children: [{type: 'text', value: 'alpha'}]},
+        {
+          file,
+          handlers: {
+            paragraph(state, /** @type {Paragraph} */ node) {
+              assert(state.options.file)
+              state.options.file.message('Warning!')
+              return defaultHandlers.paragraph(state, node)
+            }
+          }
+        }
+      ),
+      h('p', 'alpha')
+    )
+
+    assert.deepEqual(file.messages.map(String), ['1:1: Warning!'])
+  })
+
   await t.test('should support unknown nodes by default', async function () {
     assert.deepEqual(
       toHast(customMdast),