Add JSDoc based types

.gitignore

@@ -1,5 +1,13 @@
-node_modules/
 coverage/
+node_modules/
+packages/remark/*.d.ts
+packages/remark-cli/*.d.ts
+packages/remark-parse/lib/*.d.ts
+packages/remark-parse/test.d.ts
+packages/remark-stringify/lib/*.d.ts
+packages/remark-stringify/test.d.ts
+script/**/*.d.ts
+test/**/*.d.ts
 .DS_Store
 *.log
 yarn.lock

package.json

@@ -11,28 +11,32 @@
   },
   "type": "module",
   "devDependencies": {
+    "@types/mdast": "^3.0.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "camelcase": "^6.0.0",
-    "dtslint": "^4.0.0",
     "execa": "^5.0.0",
     "lerna": "^4.0.0",
     "mdast-util-assert": "^4.0.0",
     "mdast-util-gfm": "^1.0.0",
     "micromark-extension-gfm": "^1.0.0",
     "prettier": "^2.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",
     "unified": "^10.0.0",
     "unist-util-remove-position": "^4.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
     "postinstall": "lerna bootstrap --no-ci",
+    "build": "lerna run build && rimraf \"*.d.ts\" \"{test,script}/**/*.d.ts\" && tsc && type-coverage",
     "format": "./packages/remark-cli/cli.js . -qfo && prettier . -w --loglevel warn && xo --fix",
-    "test-api": "node --conditions development test/index.js && lerna run test",
+    "test-api": "lerna run test && node --conditions development test/index.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov npm run test-api",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -43,14 +47,17 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true,
-    "ignores": [
-      "**/types"
-    ]
+    "prettier": true
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

packages/remark-cli/cli.js

@@ -21,6 +21,7 @@ const extensions = [
 ]
 
 args({
+  // @ts-expect-error: fine.
   processor: remark,
   name: proc.name,
   description: cli.description,

packages/remark-cli/package.json

@@ -35,7 +35,14 @@
     "unified-args": "^9.0.0"
   },
   "scripts": {
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "test": "node --conditions development test.js"
   },
-  "xo": false
+  "xo": false,
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
+  }
 }

packages/remark-cli/test.js

@@ -1,12 +1,12 @@
-import url from 'url'
+import {URL, fileURLToPath} from 'url'
 import execa from 'execa'
 import test from 'tape'
 
 test('remark-cli', (t) => {
   t.plan(2)
 
   t.test('should show help on `--help`', (t) => {
-    const bin = url.fileURLToPath(new URL('./cli.js', import.meta.url))
+    const bin = fileURLToPath(new URL('./cli.js', import.meta.url))
 
     t.plan(1)
 
@@ -63,7 +63,7 @@ test('remark-cli', (t) => {
   })
 
   t.test('should show version on `--version`', (t) => {
-    const bin = url.fileURLToPath(new URL('./cli.js', import.meta.url))
+    const bin = fileURLToPath(new URL('./cli.js', import.meta.url))
 
     t.plan(2)
 

packages/remark-cli/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["*.js"]
+}

packages/remark-parse/index.d.ts

@@ -0,0 +1,7 @@
+// This wrapper exists because JS in TS can’t export a `@type` of a function.
+import type {Options} from './lib/index.js'
+import type {Root} from 'mdast'
+import type {Plugin} from 'unified'
+declare const remarkParse: Plugin<[Options?] | void[], string, Root>
+export default remarkParse
+export type {Options}

packages/remark-parse/index.js

@@ -1,16 +1,3 @@
-import {fromMarkdown} from 'mdast-util-from-markdown'
+import remarkParse from './lib/index.js'
 
-export default function remarkParse(options) {
-  this.Parser = (doc) => {
-    return fromMarkdown(
-      doc,
-      Object.assign({}, this.data('settings'), options, {
-        // Note: these options are not in the readme.
-        // The goal is for them to be set by plugins on `data` instead of being
-        // passed by users.
-        extensions: this.data('micromarkExtensions') || [],
-        mdastExtensions: this.data('fromMarkdownExtensions') || []
-      })
-    )
-  }
-}
+export default remarkParse

packages/remark-parse/lib/index.js

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('mdast-util-from-markdown').Options} Options
+ */
+
+import {fromMarkdown} from 'mdast-util-from-markdown'
+
+/** @type {import('unified').Plugin<[Options?] | void[], string, Root>} */
+export default function remarkParse(options) {
+  /** @type {import('unified').ParserFunction<Root>} */
+  const parser = (doc) => {
+    // Assume options.
+    const settings = /** @type {Options} */ (this.data('settings'))
+
+    return fromMarkdown(
+      doc,
+      Object.assign({}, settings, options, {
+        // Note: these options are not in the readme.
+        // The goal is for them to be set by plugins on `data` instead of being
+        // passed by users.
+        extensions: this.data('micromarkExtensions') || [],
+        mdastExtensions: this.data('fromMarkdownExtensions') || []
+      })
+    )
+  }
+
+  Object.assign(this, {Parser: parser})
+}

packages/remark-parse/package.json

@@ -34,14 +34,26 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "lib/",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
-    "mdast-util-from-markdown": "^1.0.0"
+    "@types/mdast": "^3.0.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "unified": "^10.0.0"
   },
   "scripts": {
-    "test": "node --conditions development test.js"
+    "test": "node --conditions development test.js",
+    "build": "rimraf \"test.d.ts\" \"lib/**/*.d.ts\" && tsc && type-coverage"
   },
-  "xo": false
+  "xo": false,
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
+  }
 }

packages/remark-parse/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["lib/**/*.js", "test.js"]
+}

packages/remark-stringify/index.d.ts

@@ -0,0 +1,7 @@
+// This wrapper exists because JS in TS can’t export a `@type` of a function.
+import type {Options} from './lib/index.js'
+import type {Root} from 'mdast'
+import type {Plugin} from 'unified'
+declare const remarkStringify: Plugin<[Options?] | void[], Root, string>
+export default remarkStringify
+export type {Options}

packages/remark-stringify/index.js

@@ -1,15 +1,3 @@
-import {toMarkdown} from 'mdast-util-to-markdown'
+import remarkStringify from './lib/index.js'
 
-export default function remarkStringify(options) {
-  this.Compiler = (tree) => {
-    return toMarkdown(
-      tree,
-      Object.assign({}, this.data('settings'), options, {
-        // Note: this option is not in the readme.
-        // The goal is for it to be set by plugins on `data` instead of being
-        // passed by users.
-        extensions: this.data('toMarkdownExtensions') || []
-      })
-    )
-  }
-}
+export default remarkStringify

packages/remark-stringify/lib/index.js

@@ -0,0 +1,27 @@
+/**
+ * @typedef {import('mdast').Root|import('mdast').Content} Node
+ * @typedef {import('mdast-util-to-markdown').Options} Options
+ */
+
+import {toMarkdown} from 'mdast-util-to-markdown'
+
+/** @type {import('unified').Plugin<[Options]|void[], Node, string>} */
+export default function remarkStringify(options) {
+  /** @type {import('unified').CompilerFunction<Node, string>} */
+  const compiler = (tree) => {
+    // Assume options.
+    const settings = /** @type {Options} */ (this.data('settings'))
+
+    return toMarkdown(
+      tree,
+      Object.assign({}, settings, options, {
+        // Note: this option is not in the readme.
+        // The goal is for it to be set by plugins on `data` instead of being
+        // passed by users.
+        extensions: this.data('toMarkdownExtensions') || []
+      })
+    )
+  }
+
+  Object.assign(this, {Compiler: compiler})
+}

packages/remark-stringify/package.json

@@ -34,14 +34,26 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "lib/",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
-    "mdast-util-to-markdown": "^1.0.0"
+    "@types/mdast": "^3.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
+    "unified": "^10.0.0"
   },
   "scripts": {
-    "test": "node --conditions development test.js"
+    "test": "node --conditions development test.js",
+    "build": "rimraf \"test.d.ts\" \"lib/**/*.d.ts\" && tsc && type-coverage"
   },
-  "xo": false
+  "xo": false,
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
+  }
 }