Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/index.js

@@ -2,43 +2,62 @@
  * @typedef {import('vfile').VFile} VFile
  * @typedef {import('vfile-message').VFileMessage} VFileMessage
  * @typedef {import('vfile-statistics').Statistics} Statistics
- *
+ */
+
+/**
  * @typedef Options
  *   Configuration (optional).
- * @property {boolean} [color]
+ * @property {boolean | null | undefined} [color]
  *   Use ANSI colors in report (default: depends).
  *   The default behavior in Node.js is the check if color is supported.
- * @property {boolean} [verbose=false]
+ * @property {boolean | null | undefined} [verbose=false]
  *   Show message `note`s.
  *   Notes are optional, additional, long descriptions.
- * @property {boolean} [quiet=false]
+ * @property {boolean | null | undefined} [quiet=false]
  *   Do not show files without messages.
- * @property {boolean} [silent=false]
+ * @property {boolean | null | undefined} [silent=false]
  *   Show errors only.
  *   This does not show info and warning messages.
  *   Also sets `quiet` to `true`.
- * @property {string} [defaultName='<stdin>']
+ * @property {string | null | undefined} [defaultName='<stdin>']
  *   Label to use for files without file path.
  *   If one file and no `defaultName` is given, no name will show up in the report.
  *
- * @typedef Row
+ * @typedef MessageRow
+ *   Message.
  * @property {string} place
+ *   Serialized positional info.
  * @property {string} label
+ *   Kind of message.
  * @property {string} reason
+ *   Reason.
  * @property {string} ruleId
+ *   Rule.
  * @property {string} source
+ *   Source.
+ *
+ * @typedef {keyof MessageRow} MessageColumn
  *
  * @typedef FileRow
+ *   File header row.
  * @property {'file'} type
+ *   Kind.
  * @property {VFile} file
+ *   Virtual file.
  * @property {Statistics} stats
+ *   Statistics.
  *
- * @typedef {Record<string, number>} Sizes
+ * @typedef {Record<MessageColumn, number>} Sizes
+ *   Sizes for message columns.
  *
  * @typedef Info
- * @property {Array<FileRow|Row>} rows
+ *   Result.
+ * @property {Array<FileRow | MessageRow>} rows
+ *   Rows.
  * @property {Statistics} stats
+ *   Total statistics.
  * @property {Sizes} sizes
+ *   Sizes for message columns.
  */
 
 import width from 'string-width'
@@ -65,17 +84,14 @@ const labels = {
 /**
  * Create a report from an error, one file, or multiple files.
  *
- * @param {Error|VFile|Array<VFile>} [files]
+ * @param {Error | VFile | Array<VFile> | null | undefined} [files]
  *   File(s) or error to report.
- * @param {Options} [options]
+ * @param {Options | null | undefined} [options]
  *   Configuration.
  * @returns {string}
  *   Report.
  */
-export function reporter(files, options = {}) {
-  /** @type {boolean|undefined} */
-  let one
-
+export function reporter(files, options) {
   if (!files) {
     return ''
   }
@@ -85,33 +101,39 @@ export function reporter(files, options = {}) {
     return String(files.stack || files)
   }
 
+  const options_ = options || {}
+
   // One file.
-  if (!Array.isArray(files)) {
-    one = true
-    files = [files]
+  if (Array.isArray(files)) {
+    return format(transform(files, options_), false, options_)
   }
 
-  return format(transform(files, options), one, options)
+  return format(transform([files], options_), true, options_)
 }
 
 /**
+ * Parse a list of messages.
+ *
  * @param {Array<VFile>} files
+ *   List of files.
  * @param {Options} options
+ *   Options.
  * @returns {Info}
+ *   Rows.
  */
 function transform(files, options) {
-  /** @type {Array<FileRow|Row>} */
+  /** @type {Array<FileRow | MessageRow>} */
   const rows = []
   /** @type {Array<VFileMessage>} */
   const all = []
   /** @type {Sizes} */
-  const sizes = {}
+  const sizes = {place: 0, label: 0, reason: 0, ruleId: 0, source: 0}
   let index = -1
 
   while (++index < files.length) {
     // @ts-expect-error it works fine.
     const messages = sort({messages: [...files[index].messages]}).messages
-    /** @type {Array<Row>} */
+    /** @type {Array<MessageRow>} */
     const messageRows = []
     let offset = -1
 
@@ -137,7 +159,7 @@ function transform(files, options) {
           source: message.source || ''
         }
 
-        /** @type {keyof row} */
+        /** @type {MessageColumn} */
         let key
 
         for (key in row) {
@@ -164,8 +186,13 @@ function transform(files, options) {
 
 /**
  * @param {Info} map
- * @param {boolean|undefined} one
+ *   Rows.
+ * @param {boolean} one
+ *   Whether the input was explicitly one file (not an array).
  * @param {Options} options
+ *   Configuration.
+ * @returns {string}
+ *   Report.
  */
 // eslint-disable-next-line complexity
 function format(map, one, options) {
@@ -298,10 +325,12 @@ function format(map, one, options) {
 }
 
 /**
- * Get the length of `value`, ignoring ANSI sequences.
+ * Get the length of the first line of `value`, ignoring ANSI sequences.
  *
  * @param {string} value
+ *   Message.
  * @returns {number}
+ *   Width.
  */
 function size(value) {
   const match = /\r?\n|\r/.exec(value)

package.json

@@ -47,6 +47,8 @@
     "string-width": "^5.0.0",
     "supports-color": "^9.0.0",
     "unist-util-stringify-position": "^3.0.0",
+    "vfile": "^5.0.0",
+    "vfile-message": "^3.0.0",
     "vfile-sort": "^3.0.0",
     "vfile-statistics": "^2.0.0"
   },
@@ -61,7 +63,6 @@
     "tape": "^5.0.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
-    "vfile": "^5.0.0",
     "xo": "^0.53.0"
   },
   "scripts": {