Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,15 +1,46 @@
 var push = [].push
 
+/**
+ * @typedef {import('estree').BaseNode} EstreeNode
+ * @typedef {import('estree').Comment} EstreeComment
+ *
+ * @typedef State
+ * @property {EstreeComment[]} comments
+ * @property {number} index
+ *
+ * @typedef Fields
+ * @property {boolean} leading
+ * @property {boolean} trailing
+ */
+
+/**
+ * Attach semistandard estree comment nodes to the tree.
+ *
+ * @param {EstreeNode} tree
+ * @param {EstreeComment[]} [comments]
+ */
 export function attachComments(tree, comments) {
-  walk(tree, {comments: comments.concat().sort(compare), index: 0})
+  var list = (comments || []).concat().sort(compare)
+  if (list.length) walk(tree, {comments: list, index: 0})
   return tree
 }
 
+/**
+ * Attach semistandard estree comment nodes to the tree.
+ *
+ * @param {EstreeNode} node
+ * @param {State} state
+ */
 function walk(node, state) {
+  /** @type {EstreeNode[]} */
   var children = []
+  /** @type {EstreeComment[]} */
   var comments = []
+  /** @type {string} */
   var key
+  /** @type {EstreeNode|EstreeNode[]} */
   var value
+  /** @type {number} */
   var index
 
   // Done, we can quit.
@@ -23,16 +54,16 @@ function walk(node, state) {
 
     // Ignore comments.
     if (value && typeof value === 'object' && key !== 'comments') {
-      if (typeof value.type === 'string') {
-        children.push(value)
-      } else if (Array.isArray(value)) {
+      if (Array.isArray(value)) {
         index = -1
 
         while (++index < value.length) {
           if (value[index] && typeof value[index].type === 'string') {
             children.push(value[index])
           }
         }
+      } else if (typeof value.type === 'string') {
+        children.push(value)
       }
     }
   }
@@ -62,11 +93,19 @@ function walk(node, state) {
   )
 
   if (comments.length) {
+    // @ts-ignore, yes, because they’re nonstandard.
     node.comments = comments
   }
 }
 
+/**
+ * @param {State} state
+ * @param {EstreeNode} node
+ * @param {boolean} compareEnd
+ * @param {Fields} fields
+ */
 function slice(state, node, compareEnd, fields) {
+  /** @type {EstreeComment[]} */
   var result = []
 
   while (
@@ -79,6 +118,12 @@ function slice(state, node, compareEnd, fields) {
   return result
 }
 
+/**
+ * @param {EstreeNode|EstreeComment} left
+ * @param {EstreeNode|EstreeComment} right
+ * @param {boolean} [compareEnd]
+ * @returns {number}
+ */
 function compare(left, right, compareEnd) {
   var field = compareEnd ? 'end' : 'start'
 
@@ -98,6 +143,7 @@ function compare(left, right, compareEnd) {
   // Just `start` (and `end`) on nodes.
   // Default in most parsers.
   if ('start' in left && field in right) {
+    // @ts-ignore Added by Acorn
     return left.start - right[field]
   }
 

package.json

@@ -27,25 +27,34 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "devDependencies": {
+    "@types/acorn": "^4.0.5",
+    "@types/tape": "^4.0.0",
     "acorn": "^8.0.0",
     "c8": "^7.0.0",
-    "estree-walker": "^2.0.0",
+    "estree-walker": "^3.0.0",
     "prettier": "^2.0.0",
     "recast": "^0.20.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.38.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -70,5 +79,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -4,6 +4,12 @@ import recast from 'recast'
 import {walk} from 'estree-walker'
 import {attachComments} from './index.js'
 
+/**
+ * @typedef {import('estree').BaseNode} EstreeNode
+ * @typedef {import('estree').Program} EstreeProgram
+ * @typedef {import('estree').Comment} EstreeComment
+ */
+
 test('estree-attach-comments (recast)', function (t) {
   t.equal(
     recast.print(attachComments(...parse(''))).code,
@@ -72,9 +78,13 @@ test('estree-attach-comments (recast)', function (t) {
     'should support a bunch of line comments'
   )
 
+  /** @type {EstreeComment[]} */
   var comments = []
+  /** @type {EstreeProgram} */
+  // @ts-ignore
   var tree = acornParse('/* 1 */ a /* 2 */ + /* 3 */ 1', {
     ecmaVersion: 2020,
+    // @ts-ignore
     onComment: comments
   })
 
@@ -87,8 +97,25 @@ test('estree-attach-comments (recast)', function (t) {
   )
 
   comments = []
+  // @ts-ignore
+  tree = acornParse('1 + 1', {
+    ecmaVersion: 2020,
+    // @ts-ignore
+    onComment: comments
+  })
+
+  t.equal(
+    recast.print(attachComments(tree)).code,
+    '1 + 1;',
+    'should not fail w/o comments'
+  )
+
+  comments = []
+  /** @type {EstreeProgram} */
+  // @ts-ignore
   tree = acornParse('/* 1 */ a /* 2 */ + /* 3 */ 1', {
     ecmaVersion: 2020,
+    // @ts-ignore
     onComment: comments
   })
 
@@ -101,9 +128,11 @@ test('estree-attach-comments (recast)', function (t) {
   )
 
   comments = []
+  // @ts-ignore
   tree = acornParse('/* 1 */ a /* 2 */ + /* 3 */ 1', {
     ecmaVersion: 2020,
     ranges: true,
+    // @ts-ignore
     onComment: comments
   })
 
@@ -116,9 +145,11 @@ test('estree-attach-comments (recast)', function (t) {
   )
 
   comments = []
+  // @ts-ignore
   tree = acornParse('/* 1 */ a /* 2 */ + /* 3 */ 1', {
     ecmaVersion: 2020,
     locations: true,
+    // @ts-ignore
     onComment: comments
   })
 
@@ -133,16 +164,30 @@ test('estree-attach-comments (recast)', function (t) {
   t.end()
 })
 
+/**
+ * @param {string} doc
+ * @returns {[EstreeProgram, EstreeComment[]]}
+ */
 function parse(doc) {
+  /** @type {EstreeComment[]} */
   var comments = []
+  /** @type {EstreeProgram} */
+  // @ts-ignore
   var tree = acornParse(doc, {ecmaVersion: 2020, onComment: comments})
   return [tree, comments]
 }
 
+/**
+ * @param {EstreeNode|EstreeComment|EstreeNode[]|EstreeComment[]} value
+ * @returns {void}
+ */
 function removePositions(value) {
+  // @ts-ignore
   walk(value, {
     enter(node) {
+      // @ts-ignore they most certainly exist.
       delete node.start
+      // @ts-ignore they most certainly exist.
       delete node.end
     }
   })

tsconfig.json

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