Add JSDoc based types

vfile · May 4, 2021 · eab1324 · eab1324
1 parent 1eb8b98
commit eab1324
Show file tree

Hide file tree

Showing 9 changed files with 151 additions and 186 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

diff --git a/index.js b/index.js
@@ -1,12 +1,30 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Position} Position
+ * @typedef {import('unist').Point} Point
+ */
+
 import {stringifyPosition} from 'unist-util-stringify-position'
 
-// Construct a new VFileMessage.
 export class VFileMessage extends Error {
+  /**
+   * Constructor of a message for `reason` at `position` from `origin`.
+   * When an error is passed in as `reason`, copies the `stack`.
+   *
+   * @param {string|Error} reason Reason for message (`string` or `Error`). Uses the stack and message of the error if given.
+   * @param {Node|Position|Point} [position] Place at which the message occurred in a file (`Node`, `Position`, or `Point`, optional).
+   * @param {string} [origin] Place in code the message originates from (`string`, optional).
+   */
   constructor(reason, position, origin) {
-    var parts = []
+    /** @type {[string?, string?]} */
+    var parts = [null, null]
+    /** @type {Position} */
+    var location = {
+      start: {line: null, column: null},
+      end: {line: null, column: null}
+    }
+    /** @type {number} */
     var index
-    var range
-    var location
 
     super()
 
@@ -26,42 +44,89 @@ export class VFileMessage extends Error {
       }
     }
 
-    range = stringifyPosition(position) || '1:1'
-
-    location = {
-      start: {line: null, column: null},
-      end: {line: null, column: null}
-    }
-
-    // Node.
-    if (position && position.position) {
-      position = position.position
-    }
-
     if (position) {
+      // Node.
+      if ('type' in position || 'position' in position) {
+        location = position.position
+      }
       // Position.
-      if (position.start) {
+      else if ('start' in position) {
+        // @ts-ignore Looks like a position.
         location = position
-        position = position.start
-      } else {
-        // Point.
+      }
+      // Point.
+      else if ('line' in position) {
+        // @ts-ignore Looks like a point.
         location.start = position
       }
     }
 
-    this.name = range
-    this.reason = reason.message || reason
-    this.message = this.reason
-    this.stack = reason.stack || ''
-    this.column = position ? position.column : null
-    this.line = position ? position.line : null
+    // Fields from `Error`
+    this.name = stringifyPosition(position) || '1:1'
+    this.message = typeof reason === 'object' ? reason.message : reason
+    this.stack = typeof reason === 'object' ? reason.stack : ''
+
+    /**
+     * Full range information, when available.
+     * Has start and end properties, both set to an object with line and column, set to number?.
+     * @type {Position?}
+     */
     this.location = location
-    this.source = parts[0] || null
-    this.ruleId = parts[1] || null
+    /**
+     * Reason for message.
+     * @type {string}
+     */
+    this.reason = this.message
+    /**
+     * Starting column of error.
+     * @type {number?}
+     */
+    this.column = location.start.line
+    /**
+     * Starting line of error.
+     * @type {number?}
+     */
+    this.line = location.start.column
+    /**
+     * Namespace of warning.
+     * @type {string?}
+     */
+    this.source = parts[0]
+    /**
+     * Category of message.
+     * @type {string?}
+     */
+    this.ruleId = parts[1]
+
+    // The following fields are “well known”.
+    // Not standard.
+    // Feel free to add other non-standard fields to your messages.
+
+    /* eslint-disable no-unused-expressions */
+    /**
+     * You may add a file property with a path of a file (used throughout the VFile ecosystem).
+     * @type {string?}
+     */
+    this.file
+    /**
+     * If true, marks associated file as no longer processable.
+     * @type {boolean?}
+     */
+    this.fatal
+    /**
+     * You may add a url property with a link to documentation for the message.
+     * @type {string?}
+     */
+    this.url
+    /**
+     * You may add a note property with a long form description of the message (supported by vfile-reporter).
+     * @type {string?}
+     */
+    this.note
+    /* eslint-enable no-unused-expressions */
   }
 }
 
-// Message properties.
 VFileMessage.prototype.file = ''
 VFileMessage.prototype.name = ''
 VFileMessage.prototype.reason = ''
@@ -70,3 +135,6 @@ VFileMessage.prototype.stack = ''
 VFileMessage.prototype.fatal = null
 VFileMessage.prototype.column = null
 VFileMessage.prototype.line = null
+VFileMessage.prototype.source = null
+VFileMessage.prototype.ruleId = null
+VFileMessage.prototype.location = null
diff --git a/package.json b/package.json
@@ -25,28 +25,34 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
-  "types": "types/index.d.ts",
+  "types": "index.d.ts",
   "files": [
-    "types/index.d.ts",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "@types/unist": "^2.0.0",
     "unist-util-stringify-position": "^3.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.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 \"*.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,
@@ -61,14 +67,17 @@
     "rules": {
       "no-var": "off",
       "prefer-arrow-callback": "off"
-    },
-    "ignores": [
-      "types/"
-    ]
+    }
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }
diff --git a/test.js b/test.js
@@ -1,20 +1,31 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Position} Position
+ * @typedef {import('unist').Point} Point
+ */
+
 import path from 'path'
 import test from 'tape'
 import {VFileMessage} from './index.js'
 
 /* eslint-disable no-undef */
+/** @type {Error} */
 var exception
+/** @type {Error} */
 var changedMessage
+/** @type {Error} */
 var multilineException
 
 try {
+  // @ts-ignore
   variable = 1
 } catch (error) {
   error.stack = cleanStack(error.stack, 3)
   exception = error
 }
 
 try {
+  // @ts-ignore
   variable = 1
 } catch (error) {
   error.message = 'foo'
@@ -23,6 +34,7 @@ try {
 }
 
 try {
+  // @ts-ignore
   variable = 1
 } catch (error) {
   error.message = 'foo\nbar\nbaz'
@@ -32,7 +44,9 @@ try {
 /* eslint-enable no-undef */
 
 test('VFileMessage(reason[, position][, origin])', function (t) {
+  /** @type {VFileMessage} */
   var message
+  /** @type {Node|Position|Point} */
   var pos
 
   t.ok(new VFileMessage('') instanceof Error, 'should return an Error')
@@ -98,6 +112,7 @@ test('VFileMessage(reason[, position][, origin])', function (t) {
   )
 
   pos = {
+    type: 'x',
     position: {
       start: {line: 2, column: 3},
       end: {line: 2, column: 5}
@@ -130,11 +145,13 @@ test('VFileMessage(reason[, position][, origin])', function (t) {
   t.equal(String(message), '2:3: test', 'should accept a position')
 
   t.equal(
+    // @ts-ignore runtime supports an overload w/o position.
     new VFileMessage('test', 'charlie').ruleId,
     'charlie',
     'should accept a `ruleId` as `origin`'
   )
 
+  // @ts-ignore runtime supports an overload w/o position.
   message = new VFileMessage('test', 'delta:echo')
 
   t.deepEqual(
@@ -146,6 +163,11 @@ test('VFileMessage(reason[, position][, origin])', function (t) {
   t.end()
 })
 
+/**
+ * @param {string} stack
+ * @param {number} max
+ * @returns {string}
+ */
 function cleanStack(stack, max) {
   return stack
     .replace(new RegExp('\\(.+\\' + path.sep, 'g'), '(')

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