fix: cleaner code + better error messages

src/index.js

@@ -5,22 +5,27 @@ const fs = require("node:fs")
 
 const {
   filterTokens,
-  addError,
   convertHeadingToHTMLFragment,
   getMarkdownHeadings,
 } = require("./utils.js")
 
+/** @typedef {import('markdownlint').Rule} MarkdownLintRule */
+
+/**
+ * @type {MarkdownLintRule}
+ */
 const customRule = {
   names: ["relative-links"],
   description: "Relative links should be valid",
   tags: ["links"],
   function: (params, onError) => {
     filterTokens(params, "inline", (token) => {
-      for (const child of token.children) {
-        const { lineNumber, type, attrs } = child
+      const children = token.children ?? []
+      for (const child of children) {
+        const { type, attrs, lineNumber } = child
 
-        /** @type {string | null} */
-        let hrefSrc = null
+        /** @type {string | undefined} */
+        let hrefSrc
 
         if (type === "link_open") {
           for (const attr of attrs) {
@@ -45,14 +50,13 @@ const customRule = {
           const isRelative =
             url.protocol === "file:" && !hrefSrc.startsWith("/")
           if (isRelative) {
-            const detail = `Link "${hrefSrc}"`
+            const detail = `"${hrefSrc}"`
 
             if (!fs.existsSync(url)) {
-              addError(
-                onError,
+              onError({
                 lineNumber,
-                `${detail} should exist in the file system`,
-              )
+                detail: `${detail} should exist in the file system`,
+              })
               continue
             }
 
@@ -74,11 +78,10 @@ const customRule = {
               })
 
               if (!headingsHTMLFragments.includes(url.hash)) {
-                addError(
-                  onError,
+                onError({
                   lineNumber,
-                  `${detail} should have a valid fragment`,
-                )
+                  detail: `${detail} should have a valid fragment identifier`,
+                })
               }
             }
           }

src/utils.js

@@ -1,11 +1,14 @@
 const MarkdownIt = require("markdown-it")
 
+/** @typedef {import('markdownlint').RuleParams} MarkdownLintRuleParams */
+/** @typedef {import('markdownlint').MarkdownItToken} MarkdownItToken */
+
 /**
  * Calls the provided function for each matching token.
  *
- * @param {object} params RuleParams instance.
+ * @param {MarkdownLintRuleParams} params RuleParams instance.
  * @param {string} type Token type identifier.
- * @param {Function} handler Callback function.
+ * @param {(token: MarkdownItToken) => void} handler Callback function.
  * @returns {void}
  */
 const filterTokens = (params, type, handler) => {
@@ -16,27 +19,6 @@ const filterTokens = (params, type, handler) => {
   }
 }
 
-/**
- * Adds a generic error object via the onError callback.
- *
- * @param {object} onError RuleOnError instance.
- * @param {number} lineNumber Line number.
- * @param {string} [detail] Error details.
- * @param {string} [context] Error context.
- * @param {number[]} [range] Column and length of error.
- * @param {object} [fixInfo] RuleOnErrorFixInfo instance.
- * @returns {void}
- */
-const addError = (onError, lineNumber, detail, context, range, fixInfo) => {
-  onError({
-    lineNumber,
-    detail,
-    context,
-    range,
-    fixInfo,
-  })
-}
-
 /**
  * Converts a Markdown heading into an HTML fragment according to the rules
  * used by GitHub.
@@ -98,8 +80,10 @@ const getMarkdownHeadings = (content) => {
       continue
     }
 
+    const children = token.children ?? []
+
     headings.push(
-      `${token.children
+      `${children
         .map((token) => {
           return token.content
         })
@@ -112,7 +96,6 @@ const getMarkdownHeadings = (content) => {
 
 module.exports = {
   filterTokens,
-  addError,
   convertHeadingToHTMLFragment,
   getMarkdownHeadings,
 }