Add JSDoc based types

.gitignore

@@ -1,5 +1,6 @@
 coverage/
 node_modules/
 .DS_Store
+*.d.ts
 *.log
 yarn.lock

index.js

@@ -1,3 +1,42 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('mdast').Paragraph} Paragraph
+ * @typedef {import('mdast').Link} Link
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ * @typedef {import('type-fest').PackageJson} PackageJson
+ *
+ * @typedef Options
+ *   Configuration.
+ * @property {string} [name]
+ *   License holder.
+ *   Detected from the `package.json` closest to the file supporting both
+ *   `object` and `string` format of `author`.
+ *   *Throws when neither given nor detected.*
+ * @property {string} [license]
+ *   SPDX identifier
+ *   Detected from the `license` field in the `package.json` in the current
+ *   working directory.
+ *   Deprecated license objects are not supported.
+ *   *Throws when neither given nor detected.*
+ * @property {string} [file]
+ *   File name of license file
+ *   Detected from the files in the directory of the `package.json` if there is
+ *   one, or the current working directory, in which case the first file
+ *   matching `/^licen[cs]e(?=$|\.)/i` is used.
+ *   If there is no given or found license file, but `options.license` is a
+ *   known SPDX identifier, the URL to the license on `spdx.org` is used.
+ * @property {string} [url]
+ *   URL to license holder
+ *   Detected from the `package.json` in the current working directory,
+ *   supporting both `object` and `string` format of `author`.
+ *   `http://` is prepended if `url` starts without HTTP or HTTPS protocol.
+ * @property {boolean} [ignoreFinalDefinitions=true]
+ *   Ignore final definitions otherwise in the section.
+ * @property {string|RegExp} [heading]
+ *   Heading to look for.
+ *   Default: `/^licen[cs]e$/i`.
+ */
+
 import {promises as fs} from 'fs'
 import path from 'path'
 import parse from 'parse-author'
@@ -11,7 +50,11 @@ const licenseHeadingRegexp = /^licen[cs]e$/i
 const http = 'http://'
 const https = 'https://'
 
-/* Add a license section. */
+/**
+ * Plugin to add a license section.
+ *
+ * @type {import('unified').Plugin<[Options], Root>}
+ */
 export default function remarkLicense(options = {}) {
   const ignoreFinalDefinitions =
     options.ignoreFinalDefinitions === undefined ||
@@ -26,14 +69,19 @@ export default function remarkLicense(options = {}) {
     /* c8 ignore next */
     const base = file.dirname ? path.resolve(file.cwd, file.dirname) : file.cwd
     const packageFile = await findUpOne('package.json', base)
+    /** @type {string|undefined} */
     let defaultName
+    /** @type {string|undefined} */
     let defaultUrl
+    /** @type {string|undefined} */
     let defaultLicense
+    /** @type {string|undefined} */
     let defaultLicenseFile
 
     // Skip package loading if we have all info in `options`.
     if (packageFile && (!options.url || !options.name || !options.license)) {
       await read(packageFile)
+      /** @type {PackageJson} */
       const packageJson = JSON.parse(String(packageFile))
       const author =
         typeof packageJson.author === 'string'
@@ -89,9 +137,12 @@ export default function remarkLicense(options = {}) {
       licenseFile = spdx[license].url
     }
 
-    headingRange(tree, {ignoreFinalDefinitions, test}, (start, nodes, end) => {
+    headingRange(tree, {ignoreFinalDefinitions, test}, (start, _, end) => {
+      /** @type {PhrasingContent[]} */
       const children = []
+      /** @type {Paragraph} */
       const node = {type: 'paragraph', children}
+      /** @type {Paragraph|Link} */
       let parent
 
       if (licenseFile) {
@@ -102,22 +153,19 @@ export default function remarkLicense(options = {}) {
       }
 
       parent.children.push({type: 'text', value: license})
-
       children.push({type: 'text', value: ' © '})
 
       if (url) {
-        let link
-
-        if (
-          url.slice(0, http.length) !== http &&
-          url.slice(0, https.length) !== https
-        ) {
-          link = http + url
-        } else {
-          link = url
+        parent = {
+          type: 'link',
+          title: null,
+          url:
+            url.slice(0, http.length) !== http &&
+            url.slice(0, https.length) !== https
+              ? http + url
+              : url,
+          children: []
         }
-
-        parent = {type: 'link', title: null, url: link, children: []}
         children.push(parent)
       } else {
         parent = node

package.json

@@ -31,31 +31,42 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "mdast-util-heading-range": "^3.0.0",
     "parse-author": "^2.0.0",
     "spdx-license-list": "^6.0.0",
     "to-vfile": "^7.0.0",
-    "vfile-find-up": "^6.0.0"
+    "unified": "^10.0.0",
+    "vfile-find-up": "^6.0.0",
+    "type-fest": "^1.0.0"
   },
   "devDependencies": {
+    "@types/parse-author": "^2.0.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "is-hidden": "^2.0.0",
     "prettier": "^2.0.0",
     "remark": "^14.0.0",
     "remark-cli": "^10.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": {
+    "build": "rimraf \"test/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo --ignore-pattern test/ && prettier . -w --loglevel warn && xo --fix",
     "test-api": "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,
@@ -82,5 +93,11 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

readme.md

@@ -114,8 +114,8 @@ Ignore final definitions otherwise in the section (`boolean`, default: true).
 
 ###### `options.heading`
 
-Heading to look for
-(`string` (case-insensitive) or `RegExp`, default: `/^licen[cs]e$/i`).
+Heading to look for (`string` (case-insensitive) or `RegExp`, default:
+`/^licen[cs]e$/i`).
 
 ## Detection
 

test/index.js

@@ -1,5 +1,10 @@
+/**
+ * @typedef {import('../index.js').Options} Options
+ */
+
 import fs from 'fs'
 import path from 'path'
+import {URL} from 'url'
 import test from 'tape'
 import {remark} from 'remark'
 import {isHidden} from 'is-hidden'
@@ -25,20 +30,26 @@ test('Fixtures', async (t) => {
 
   while (++index < fixtures.length) {
     const name = fixtures[index]
+    /** @type {Options|undefined} */
     let config
+    /** @type {string} */
     let output
 
     if (isHidden(name)) continue
 
     try {
-      config = JSON.parse(fs.readFileSync(path.join(root, name, 'config.json')))
+      config = JSON.parse(
+        String(fs.readFileSync(path.join(root, name, 'config.json')))
+      )
     } catch {
       try {
         config = (
           await import(
-            new URL(
-              path.join('.', 'fixtures', name, 'config.js'),
-              import.meta.url
+            String(
+              new URL(
+                path.join('.', 'fixtures', name, 'config.js'),
+                import.meta.url
+              )
             )
           )
         ).default

tsconfig.json

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