Introduce type declaration file for project after updating typescript dependency to 3.7.2.

lib/markdownlint.js

@@ -615,8 +615,8 @@ function lintInput(options, synchronous, callback) {
 /**
  * Lint specified Markdown files.
  *
- * @param {Object} options Configuration options.
- * @param {Function} callback Callback (err, result) function.
+ * @param {Options} options Configuration options.
+ * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function markdownlint(options, callback) {
@@ -626,8 +626,8 @@ function markdownlint(options, callback) {
 /**
  * Lint specified Markdown files synchronously.
  *
- * @param {Object} options Configuration options.
- * @returns {Object} Result object.
+ * @param {Options} options Configuration options.
+ * @returns {LintResults} Results object.
  */
 function markdownlintSync(options) {
   let results = null;
@@ -668,9 +668,9 @@ function parseConfiguration(name, content, parsers) {
 /**
  * Read specified configuration file.
  *
- * @param {String} file Configuration file name/path.
- * @param {Array} [parsers] Optional parsing function(s).
- * @param {Function} callback Callback (err, result) function.
+ * @param {string} file Configuration file name.
+ * @param {ConfigurationParser[] | null} parsers Parsing function(s).
+ * @param {ReadConfigCallback} callback Callback (err, result) function.
  * @returns {void}
  */
 function readConfig(file, parsers, callback) {
@@ -711,9 +711,9 @@ function readConfig(file, parsers, callback) {
 /**
  * Read specified configuration file synchronously.
  *
- * @param {String} file Configuration file name/path.
- * @param {Array} [parsers] Optional parsing function(s).
- * @returns {Object} Configuration object.
+ * @param {string} file Configuration file name.
+ * @param {ConfigurationParser[]} [parsers] Parsing function(s).
+ * @returns {Configuration} Configuration object.
  */
 function readConfigSync(file, parsers) {
   // Read file
@@ -743,3 +743,185 @@ markdownlint.sync = markdownlintSync;
 markdownlint.readConfig = readConfig;
 markdownlint.readConfigSync = readConfigSync;
 module.exports = markdownlint;
+
+// Type declarations
+
+/**
+ * Function to implement rule logic.
+ *
+ * @callback RuleFunction
+ * @param {RuleParams} params Rule parameters.
+ * @param {RuleOnError} onError Error-reporting callback.
+ * @returns {void}
+ */
+
+/**
+ * Rule parameters.
+ *
+ * @typedef {Object} RuleParams
+ * @property {string} name File/string name.
+ * @property {MarkdownItToken[]} tokens markdown-it token objects.
+ * @property {string[]} lines File/string lines.
+ * @property {string[]} frontMatterLines Front matter lines.
+ * @property {RuleConfiguration} config Rule configuration.
+ */
+
+/**
+ * Markdown-It token.
+ *
+ * @typedef {Object} MarkdownItToken
+ * @property {string[][]} attrs HTML attributes.
+ * @property {boolean} block Block-level token.
+ * @property {MarkdownItToken[]} children Child nodes.
+ * @property {string} content Tag contents.
+ * @property {boolean} hidden Ignore element.
+ * @property {string} info Fence info.
+ * @property {number} level Nesting level.
+ * @property {number[]} map Beginning/ending line numbers.
+ * @property {string} markup Markup text.
+ * @property {Object} meta Arbitrary data.
+ * @property {number} nesting Level change.
+ * @property {string} tag HTML tag name.
+ * @property {string} type Token type.
+ */
+
+/**
+ * Error-reporting callback.
+ *
+ * @callback RuleOnError
+ * @param {RuleOnErrorInfo} onErrorInfo Error information.
+ * @returns {void}
+ */
+
+/**
+ * Fix information for RuleOnError callback.
+ *
+ * @typedef {Object} RuleOnErrorInfo
+ * @property {number} lineNumber Line number (1-based).
+ * @property {string} [details] Details about the error.
+ * @property {string} [context] Context for the error.
+ * @property {number[]} [range] Column number (1-based) and length.
+ * @property {RuleOnErrorFixInfo} [fixInfo] Fix information.
+ */
+
+/**
+ * Fix information for RuleOnErrorInfo.
+ *
+ * @typedef {Object} RuleOnErrorFixInfo
+ * @property {number} [lineNumber] Line number (1-based).
+ * @property {number} [editColumn] Column of the fix (1-based).
+ * @property {number} [deleteCount] Count of characters to delete.
+ * @property {string} [insertText] Text to insert (after deleting).
+ */
+
+/**
+ * Rule definition.
+ *
+ * @typedef {Object} Rule
+ * @property {string[]} names Rule name(s).
+ * @property {string} description Rule description.
+ * @property {URL} [information] Link to more information.
+ * @property {string[]} tags Rule tag(s).
+ * @property {RuleFunction} function Rule implementation.
+ */
+
+/**
+ * Configuration options.
+ *
+ * @typedef {Object} Options
+ * @property {string[] | string} [files] Files to lint.
+ * @property {Object.<string, string>} [strings] Strings to lint.
+ * @property {Configuration} [config] Configuration object.
+ * @property {Rule[] | Rule} [customRules] Custom rules.
+ * @property {RegExp} [frontMatter] Front matter pattern.
+ * @property {boolean} [handleRuleFailures] True to catch exceptions.
+ * @property {boolean} [noInlineConfig] True to ignore HTML directives.
+ * @property {number} [resultVersion] Results object version.
+ * @property {Plugin[]} [markdownItPlugins] Additional plugins.
+ */
+
+/**
+ * markdown-it plugin.
+ *
+ * @typedef {Array} Plugin
+ */
+
+/**
+ * Function to pretty-print lint results.
+ *
+ * @callback ToStringCallback
+ * @param {boolean} [ruleAliases] True to use rule aliases.
+ * @returns {string}
+ */
+
+/**
+ * Lint results (for resultVersion 3).
+ *
+ * @typedef {Object.<string, LintError[]>} LintResults
+ */
+// The following should be part of the LintResults typedef, but that causes
+// TypeScript to "forget" about the string map.
+// * @property {ToStringCallback} toString String representation.
+// https://github.com/microsoft/TypeScript/issues/34911
+
+/**
+ * Lint error.
+ *
+ * @typedef {Object} LintError
+ * @property {number} lineNumber Line number (1-based).
+ * @property {string[]} ruleNames Rule name(s).
+ * @property {string} ruleDescription Rule description.
+ * @property {string} ruleInformation Link to more information.
+ * @property {string} errorDetail Detail about the error.
+ * @property {string} errorContext Context for the error.
+ * @property {number[]} errorRange Column number (1-based) and length.
+ * @property {FixInfo} fixInfo Fix information.
+ */
+
+/**
+ * Fix information.
+ *
+ * @typedef {Object} FixInfo
+ * @property {number} [editColumn] Column of the fix (1-based).
+ * @property {number} [deleteCount] Count of characters to delete.
+ * @property {string} [insertText] Text to insert (after deleting).
+ */
+
+/**
+ * Called with the result of the lint operation.
+ *
+ * @callback LintCallback
+ * @param {Error | null} err Error object or null.
+ * @param {LintResults} [results] Lint results.
+ * @returns {void}
+ */
+
+/**
+ * Configuration object for linting rules. For a detailed schema, see
+ * {@link ../schema/markdownlint-config-schema.json}.
+ *
+ * @typedef {Object.<string, RuleConfiguration>} Configuration
+ */
+
+/**
+ * Rule configuration object.
+ *
+ * @typedef {boolean | Object} RuleConfiguration Rule configuration.
+ */
+
+/**
+ * Parses a configuration string and returns a configuration object.
+ *
+ * @callback ConfigurationParser
+ * @param {string} text Configuration string.
+ * @returns {Configuration}
+ */
+
+/**
+ * Called with the result of the readConfig operation.
+ *
+ * @callback ReadConfigCallback
+ * @param {Error | null} err Error object or null.
+ * @param {Configuration} [config] Configuration object.
+ * @returns {void}
+ */