Address new TypeScript warnings in core files, improve type definitions.

Author: DavidAnson

eslint.config.mjs

@@ -54,6 +54,7 @@ export default [
       "multiline-comment-style": [ "error", "separate-lines" ],
       "no-empty-function": "off",
       "no-implicit-coercion": "off",
+      "no-inline-comments": [ "error", { "ignorePattern": " @type \\{.+\\} " } ],
       "no-magic-numbers": "off",
       "no-param-reassign": "off",
       "no-plusplus": "off",

example/typescript/type-check.ts

@@ -30,7 +30,7 @@ function assertLintResults(results: LintResults) {
   assert.equal(results["string"][0].lineNumber, 1);
   assert.deepEqual(results["string"][0].ruleNames, [ "MD047", "single-trailing-newline" ]);
   assert.equal(results["string"][0].ruleDescription, "Files should end with a single newline character");
-  assert.equal(results["string"][0].ruleInformation.replace(/v\d+\.\d+\.\d+/, "v0.0.0"), "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md047.md");
+  assert.equal(results["string"][0].ruleInformation?.replace(/v\d+\.\d+\.\d+/, "v0.0.0"), "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md047.md");
   assert.equal(results["string"][0].errorDetail, null);
   assert.equal(results["string"][0].errorContext, null);
   assert.deepEqual(results["string"][0].errorRange, [ 9, 1 ]);

helpers/helpers.cjs

@@ -111,10 +111,11 @@ module.exports.cloneIfArray = cloneIfArray;
 /**
  * Clones the input if it is a URL.
  *
- * @param {Object} url Object of unknown type.
+ * @param {Object | undefined} url Object of unknown type.
  * @returns {Object} Clone of obj iff obj is a URL.
  */
 function cloneIfUrl(url) {
+  // @ts-ignore
   return isUrl(url) ? new URL(url) : url;
 }
 module.exports.cloneIfUrl = cloneIfUrl;
@@ -139,7 +140,7 @@ module.exports.getHtmlAttributeRe = function getHtmlAttributeRe(name) {
 function isBlankLine(line) {
   const startComment = "<!--";
   const endComment = "-->";
-  const removeComments = (s) => {
+  const removeComments = (/** @type {string} */ s) => {
     while (true) {
       const start = s.indexOf(startComment);
       const end = s.indexOf(endComment);
@@ -177,8 +178,8 @@ const startsWithPipeRe = /^ *\|/;
 const notCrLfRe = /[^\r\n]/g;
 const notSpaceCrLfRe = /[^ \r\n]/g;
 const trailingSpaceRe = / +[\r\n]/g;
-const replaceTrailingSpace = (s) => s.replace(notCrLfRe, safeCommentCharacter);
-module.exports.clearHtmlCommentText = function clearHtmlCommentText(text) {
+const replaceTrailingSpace = (/** @type {string} */ s) => s.replace(notCrLfRe, safeCommentCharacter);
+module.exports.clearHtmlCommentText = function clearHtmlCommentText(/** @type {string} */ text) {
   let i = 0;
   while ((i = text.indexOf(htmlCommentBegin, i)) !== -1) {
     const j = text.indexOf(htmlCommentEnd, i + 2);
@@ -220,7 +221,7 @@ module.exports.clearHtmlCommentText = function clearHtmlCommentText(text) {
 };
 
 // Escapes a string for use in a RegExp
-module.exports.escapeForRegExp = function escapeForRegExp(str) {
+module.exports.escapeForRegExp = function escapeForRegExp(/** @type {string} */ str) {
   return str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
 };
 
@@ -355,7 +356,7 @@ module.exports.hasOverlap = function hasOverlap(rangeA, rangeB) {
 
 // Determines if the front matter includes a title
 module.exports.frontMatterHasTitle =
-  function frontMatterHasTitle(frontMatterLines, frontMatterTitlePattern) {
+  function frontMatterHasTitle(/** @type {readonly string[]} */ frontMatterLines, /** @type {string} */ frontMatterTitlePattern) {
     const ignoreFrontMatter =
       (frontMatterTitlePattern !== undefined) && !frontMatterTitlePattern;
     const frontMatterTitleRe =
@@ -367,18 +368,31 @@ module.exports.frontMatterHasTitle =
       frontMatterLines.some((line) => frontMatterTitleRe.test(line));
   };
 
+/**
+ * Result object for getReferenceLinkImageData.
+ *
+ * @typedef {Object} GetReferenceLinkImageDataResult
+ * @property {Map<string, number[][]>} references References.
+ * @property {Map<string, number[][]>} shortcuts Shortcuts.
+ * @property {Map<string, [number, string]>} definitions Definitions.
+ * @property {[string, number][]} duplicateDefinitions Duplicate definitions.
+ * @property {number[]} definitionLineIndices Definition line indices.
+ */
+
 /**
  * Returns an object with information about reference links and images.
  *
  * @param {MicromarkToken[]} tokens Micromark tokens.
- * @returns {Object} Reference link/image data.
+ * @returns {GetReferenceLinkImageDataResult} Reference link/image data.
  */
 function getReferenceLinkImageData(tokens) {
-  const normalizeReference = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
-  const getText = (t) => t?.children.filter((c) => c.type !== "blockQuotePrefix").map((c) => c.text).join("");
+  const normalizeReference = (/** @type {string} */ s) => s.toLowerCase().trim().replace(/\s+/g, " ");
+  const getText = (/** @type {MicromarkToken} */ t) => t?.children.filter((c) => c.type !== "blockQuotePrefix").map((c) => c.text).join("");
+  /** @type {Map<string, number[][]>} */
   const references = new Map();
+  /** @type {Map<string, number[][]>} */
   const shortcuts = new Map();
-  const addReferenceToDictionary = (token, label, isShortcut) => {
+  const addReferenceToDictionary = (/** @type {MicromarkToken} */ token, /** @type {string} */ label, /** @type {boolean} */ isShortcut) => {
     const referenceDatum = [
       token.startLine - 1,
       token.startColumn - 1,
@@ -390,8 +404,11 @@ function getReferenceLinkImageData(tokens) {
     referenceData.push(referenceDatum);
     dictionary.set(reference, referenceData);
   };
+  /** @type {Map<string, [number, string]>} */
   const definitions = new Map();
+  /** @type {number[]} */
   const definitionLineIndices = [];
+  /** @type {[string, number][]} */
   const duplicateDefinitions = [];
   const filteredTokens =
     micromark.filterByTypes(
@@ -433,7 +450,7 @@ function getReferenceLinkImageData(tokens) {
               micromark.getDescendantsByType(parent, [ "definitionDestination", "definitionDestinationRaw", "definitionDestinationString" ])[0]?.text;
             definitions.set(
               reference,
-              [ token.startLine - 1, destinationString ]
+              [ token.startLine - 1, destinationString || "" ]
             );
           }
         }
@@ -490,7 +507,7 @@ module.exports.getReferenceLinkImageData = getReferenceLinkImageData;
  * Gets the most common line ending, falling back to the platform default.
  *
  * @param {string} input Markdown content to analyze.
- * @param {Object} [os] Node.js "os" module.
+ * @param {{EOL: string}} [os] Node.js "os" module.
  * @returns {string} Preferred line ending.
  */
 function getPreferredLineEnding(input, os) {
@@ -530,7 +547,7 @@ module.exports.getPreferredLineEnding = getPreferredLineEnding;
  * Expands a path with a tilde to an absolute path.
  *
  * @param {string} file Path that may begin with a tilde.
- * @param {Object} os Node.js "os" module.
+ * @param {{homedir: () => string}} os Node.js "os" module.
  * @returns {string} Absolute path (or original path).
  */
 function expandTildePath(file, os) {
@@ -591,6 +608,7 @@ function convertLintErrorsVersion2To1(errors) {
  * @returns {LintErrors} Lint errors (v0).
  */
 function convertLintErrorsVersion2To0(errors) {
+  /** @type {Object.<string, number[]>} */
   const dictionary = {};
   for (const error of errors) {
     const ruleName = error.ruleNames[0];
@@ -606,10 +624,11 @@ function convertLintErrorsVersion2To0(errors) {
  * Copies and transforms lint results from resultVersion 3 to ?.
  *
  * @param {LintResults} results Lint results (v3).
- * @param {(LintErrors) => LintErrors} transform Lint errors (v?).
+ * @param {(errors: LintErrors) => LintErrors} transform Lint errors (v?).
  * @returns {LintResults} Lint results (v?).
  */
 function copyAndTransformResults(results, transform) {
+  /** @type {Object.<string, LintErrors>} */
   const newResults = {};
   Object.defineProperty(newResults, "toString", { "value": results.toString });
   for (const key of Object.keys(results)) {

helpers/micromark-helpers.cjs

@@ -17,6 +17,7 @@ const { flatTokensSymbol, htmlFlowSymbol, newLineRe } = require("./shared.cjs");
  * @returns {boolean} True iff the token is within an htmlFlow type.
  */
 function inHtmlFlow(token) {
+  // @ts-ignore
   return Boolean(token[htmlFlowSymbol]);
 }
 
@@ -126,8 +127,11 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  * @returns {Token[]} Filtered tokens.
  */
 function filterByTypes(tokens, types, htmlFlow) {
-  const predicate = (token) => types.includes(token.type) && (htmlFlow || !inHtmlFlow(token));
-  const flatTokens = tokens[flatTokensSymbol];
+  const predicate = (/** @type {Token} */ token) => types.includes(token.type) && (htmlFlow || !inHtmlFlow(token));
+  /** @type {Token[]} */
+  const flatTokens =
+    // @ts-ignore
+    tokens[flatTokensSymbol];
   if (flatTokens) {
     return flatTokens.filter(predicate);
   }
@@ -163,7 +167,7 @@ function getBlockQuotePrefixText(tokens, lineNumber, count = 1) {
 function getDescendantsByType(parent, typePath) {
   let tokens = Array.isArray(parent) ? parent : [ parent ];
   for (const type of typePath) {
-    const predicate = (token) => Array.isArray(type) ? type.includes(token.type) : (type === token.type);
+    const predicate = (/** @type {Token} */ token) => Array.isArray(type) ? type.includes(token.type) : (type === token.type);
     tokens = tokens.flatMap((t) => t.children.filter(predicate));
   }
   return tokens;

lib/cache.mjs

@@ -6,6 +6,7 @@ import { filterByTypes } from "../helpers/micromark-helpers.cjs";
 /** @typedef {import("markdownlint").RuleParams} RuleParams */
 /** @typedef {import("markdownlint").MicromarkToken} MicromarkToken */
 /** @typedef {import("markdownlint").MicromarkTokenType} MicromarkTokenType */
+/** @typedef {import("../helpers/helpers.cjs").GetReferenceLinkImageDataResult} GetReferenceLinkImageDataResult */
 
 /** @type {Map<string, object>} */
 const map = new Map();
@@ -68,9 +69,10 @@ export function filterByTypesCached(types, htmlFlow) {
 /**
  * Gets a reference link and image data object.
  *
- * @returns {Object} Reference link and image data object.
+ * @returns {GetReferenceLinkImageDataResult} Reference link and image data object.
  */
 export function getReferenceLinkImageData() {
+  // @ts-ignore
   return getCached(
     getReferenceLinkImageData.name,
     () => helpersGetReferenceLinkImageData(micromarkTokens())

lib/constants.mjs

@@ -1,5 +1,6 @@
 // @ts-check
 
+/** @type {string[]} */
 export const deprecatedRuleNames = [];
 export const fixableRuleNames = [
   "MD004", "MD005", "MD007", "MD009", "MD010", "MD011",

lib/markdownit.cjs

@@ -127,6 +127,7 @@ function annotateAndFreezeTokens(tokens, lines) {
     }
     // Annotate children with lineNumber
     if (token.children) {
+      /** @type {number[]} */
       const codeSpanExtraLines = [];
       if (token.children.some((child) => child.type === "code_inline")) {
         forEachInlineCodeSpan(token.content, (code) => {
@@ -140,7 +141,7 @@ function annotateAndFreezeTokens(tokens, lines) {
         if ((child.type === "softbreak") || (child.type === "hardbreak")) {
           lineNumber++;
         } else if (child.type === "code_inline") {
-          lineNumber += codeSpanExtraLines.shift();
+          lineNumber += codeSpanExtraLines.shift() || 0;
         }
       }
     }

lib/markdownlint.d.mts

@@ -26,39 +26,38 @@ export function lintSync(options: Options | null): LintResults;
  * @param {Configuration} config Configuration object.
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[] | undefined} parsers Parsing function(s).
- * @param {Object} fs File system implementation.
+ * @param {FsLike} fs File system implementation.
  * @returns {Promise<Configuration>} Configuration object.
  */
-export function extendConfigPromise(config: Configuration, file: string, parsers: ConfigurationParser[] | undefined, fs: any): Promise<Configuration>;
+export function extendConfigPromise(config: Configuration, file: string, parsers: ConfigurationParser[] | undefined, fs: FsLike): Promise<Configuration>;
 /**
  * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
- * @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing
- * function(s).
- * @param {Object} [fs] File system implementation.
+ * @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s).
+ * @param {FsLike | ReadConfigCallback} [fs] File system implementation.
  * @param {ReadConfigCallback} [callback] Callback (err, result) function.
  * @returns {void}
  */
-export function readConfigAsync(file: string, parsers?: ConfigurationParser[] | ReadConfigCallback, fs?: any, callback?: ReadConfigCallback): void;
+export function readConfigAsync(file: string, parsers?: ConfigurationParser[] | ReadConfigCallback, fs?: FsLike | ReadConfigCallback, callback?: ReadConfigCallback): void;
 /**
  * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
- * @param {Object} [fs] File system implementation.
+ * @param {FsLike} [fs] File system implementation.
  * @returns {Promise<Configuration>} Configuration object.
  */
-export function readConfigPromise(file: string, parsers?: ConfigurationParser[], fs?: any): Promise<Configuration>;
+export function readConfigPromise(file: string, parsers?: ConfigurationParser[], fs?: FsLike): Promise<Configuration>;
 /**
  * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
- * @param {Object} [fs] File system implementation.
+ * @param {FsLike} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
  */
-export function readConfigSync(file: string, parsers?: ConfigurationParser[], fs?: any): Configuration;
+export function readConfigSync(file: string, parsers?: ConfigurationParser[], fs?: FsLike): Configuration;
 /**
  * Applies the specified fix to a Markdown content line.
  *
@@ -82,6 +81,19 @@ export function applyFixes(input: string, errors: LintError[]): string;
  * @returns {string} SemVer string.
  */
 export function getVersion(): string;
+/**
+ * Result object for removeFrontMatter.
+ */
+export type RemoveFrontMatterResult = {
+    /**
+     * Markdown content.
+     */
+    content: string;
+    /**
+     * Front matter lines.
+     */
+    frontMatterLines: string[];
+};
 /**
  * Result object for getEffectiveConfig.
  */
@@ -120,6 +132,27 @@ export type EnabledRulesPerLineNumberResult = {
      */
     rulesSeverity: Map<string, "error" | "warning">;
 };
+/**
+ * Node fs instance (or compatible object).
+ */
+export type FsLike = {
+    /**
+     * access method.
+     */
+    access: (path: string, callback: (err: Error) => void) => void;
+    /**
+     * accessSync method.
+     */
+    accessSync: (path: string) => void;
+    /**
+     * readFile method.
+     */
+    readFile: (path: string, encoding: string, callback: (err: Error, data: string) => void) => void;
+    /**
+     * readFileSync method.
+     */
+    readFileSync: (path: string, encoding: string) => string;
+};
 /**
  * Function to implement rule logic.
  */
@@ -418,7 +451,7 @@ export type Options = {
     /**
      * File system implementation.
      */
-    fs?: any;
+    fs?: FsLike;
     /**
      * True to catch exceptions.
      */
@@ -467,15 +500,15 @@ export type LintError = {
     /**
      * Link to more information.
      */
-    ruleInformation: string;
+    ruleInformation: string | null;
     /**
      * Detail about the error.
      */
-    errorDetail: string;
+    errorDetail: string | null;
     /**
      * Context for the error.
      */
-    errorContext: string;
+    errorContext: string | null;
     /**
      * Column number (1-based) and length.
      */