Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

index.js

@@ -1,20 +1,50 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ * @typedef {import('unist-util-visit').Visitor<Node>} Visitor
+ *
+ * @typedef ZoneInfo
+ * @property {number} start
+ * @property {number} end
+ * @property {Parent|null} parent
+ *
+ * @callback Handler
+ * @param {Node|undefined} start
+ * @param {Array.<Node>} between
+ * @param {Node|undefined} end
+ * @param {ZoneInfo} info
+ */
+
 import {commentMarker} from 'mdast-comment-marker'
 import {visit} from 'unist-util-visit'
 
+/**
+ * @param {Node} node
+ * @param {string} name
+ * @param {Handler} callback
+ */
 export function zone(node, name, callback) {
+  /** @type {number} */
   var level
+  /** @type {Node} */
   var marker
+  /** @type {Parent} */
   var scope
 
   visit(node, gather)
 
-  // Gather one dimensional zones.
+  /**
+   * Gather one dimensional zones.
+   * @type {Visitor}
+   */
   function gather(node, index, parent) {
     var info = commentMarker(node)
     var match =
       info && info.name === name && info.attributes.match(/(start|end)\b/)
     var type = match && match[0]
+    /** @type {number} */
     var start
+    /** @type {Array.<Node>} */
     var result
 
     if (type) {

package.json

@@ -29,28 +29,38 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.3",
+    "@types/unist": "^2.0.3",
     "mdast-comment-marker": "^2.0.0",
     "unist-util-visit": "^3.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "is-hidden": "^2.0.0",
     "prettier": "^2.0.0",
     "remark": "^13.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"{test/**,}*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test/index.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test/index.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -63,6 +73,7 @@
   "xo": {
     "prettier": true,
     "rules": {
+      "capitalized-comments": "off",
       "no-var": "off",
       "prefer-arrow-callback": "off"
     }
@@ -71,5 +82,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test/fixtures/mismatched/index.js

@@ -1,4 +1,9 @@
-export default function assertion(t, zone, tree) {
+/**
+ * @param {import('tape').Test} _
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
+export default function assertion(_, zone, tree) {
   zone(tree, 'foo', handle)
 
   function handle() {

test/fixtures/nodes/index.js

@@ -1,3 +1,8 @@
+/**
+ * @param {import('tape').Test} t
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
 export default function assertion(t, zone, tree) {
   var count = 0
 
@@ -6,9 +11,11 @@ export default function assertion(t, zone, tree) {
 
     zone(tree, 'foo', handle)
 
-    function handle(start, nodes) {
+    /** @type {import('../../../index.js').Handler} */
+    function handle(_, nodes) {
       st.equal(nodes.length, 1)
       st.equal(nodes[0].type, 'paragraph')
+      // @ts-ignore hush
       st.equal(nodes[0].children.length, 1)
       st.equal(nodes[0].children[0].type, 'text')
       st.equal(nodes[0].children[0].value, 'Foo.')

test/fixtures/non-marker/index.js

@@ -1,4 +1,9 @@
-export default function assertion(t, zone, tree) {
+/**
+ * @param {import('tape').Test} _
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
+export default function assertion(_, zone, tree) {
   zone(tree, 'foo', handle)
 
   function handle() {

test/fixtures/range-children/index.js

@@ -1,3 +1,8 @@
+/**
+ * @param {import('tape').Test} t
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
 export default function assertion(t, zone, tree) {
   var count = 0
 
@@ -6,7 +11,8 @@ export default function assertion(t, zone, tree) {
 
     zone(tree, 'foo', handle)
 
-    function handle(start, nodes) {
+    /** @type {import('../../../index.js').Handler} */
+    function handle(_, nodes) {
       st.equal(nodes.length, 1)
       st.equal(nodes[0].type, 'blockquote')
       st.equal(++count, 1)

test/fixtures/remove-children/index.js

@@ -1,7 +1,13 @@
-export default function assertion(t, zone, tree) {
+/**
+ * @param {import('tape').Test} _
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
+export default function assertion(_, zone, tree) {
   zone(tree, 'foo', handle)
 
-  function handle(start, nodes, end) {
+  /** @type {import('../../../index.js').Handler} */
+  function handle(start, _, end) {
     return [start, end]
   }
 }

test/fixtures/remove/index.js

@@ -1,4 +1,9 @@
-export default function assertion(t, zone, tree) {
+/**
+ * @param {import('tape').Test} _
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
+export default function assertion(_, zone, tree) {
   zone(tree, 'foo', handle)
 
   function handle() {

test/fixtures/replace-children/index.js

@@ -1,7 +1,13 @@
-export default function assertion(t, zone, tree) {
+/**
+ * @param {import('tape').Test} _
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
+export default function assertion(_, zone, tree) {
   zone(tree, 'foo', handle)
 
-  function handle(start, nodes, end) {
+  /** @type {import('../../../index.js').Handler} */
+  function handle(start, _, end) {
     return [
       start,
       {

test/fixtures/replace/index.js

@@ -1,4 +1,9 @@
-export default function assertion(t, zone, tree) {
+/**
+ * @param {import('tape').Test} _
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
+export default function assertion(_, zone, tree) {
   zone(tree, 'foo', handle)
 
   function handle() {

test/fixtures/simple/index.js

@@ -1,9 +1,15 @@
+/**
+ * @param {import('tape').Test} t
+ * @param {import('../../../index.js').zone} zone
+ * @param {import('unist').Node} tree
+ */
 export default function assertion(t, zone, tree) {
   t.test('range', function (st) {
     st.plan(5)
 
     zone(tree, 'foo', handle)
 
+    /** @type {import('../../../index.js').Handler} */
     function handle(start, nodes, end) {
       st.equal(start.type, 'html')
       st.equal(start.value, '<!--foo start bar="baz"-->')

test/index.js

@@ -1,3 +1,9 @@
+/**
+ * @typedef {import('tape').Test} Test
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('../index.js').zone} Zone
+ */
+
 import fs from 'fs'
 import path from 'path'
 import test from 'tape'
@@ -9,8 +15,11 @@ test('mdast-zone', async function (t) {
   var root = path.join('test', 'fixtures')
   var fixtures = fs.readdirSync(root)
   var index = -1
+  /** @type {string} */
   var output
+  /** @type {string} */
   var name
+  /** @type {(t: Test, zone: Zone, node: Node) => void} */
   var mod
 
   while (++index < fixtures.length) {
@@ -20,13 +29,15 @@ test('mdast-zone', async function (t) {
     if (isHidden(name)) continue
 
     try {
-      output = fs.readFileSync(path.join(root, name, 'output.md'))
+      output = String(fs.readFileSync(path.join(root, name, 'output.md')))
     } catch {}
 
+    /* eslint-disable no-await-in-loop */
     mod =
-      /* eslint-disable-next-line no-await-in-loop */
+      // @ts-ignore hush.
       (await import(new URL('fixtures/' + name + '/index.js', import.meta.url)))
-        .default
+        .default // type-coverage:ignore-line
+    /* eslint-enable no-await-in-loop */
 
     remark()
       .use(() => (tree) => {

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": ["*.js", "test/**/*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}