test: separate cases, so it's easier to know what fails

.github/workflows/lint.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: "actions/checkout@v4.1.1"
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.0.0"
+        uses: "actions/setup-node@v4.0.1"
         with:
           node-version: "lts/*"
           cache: "npm"
@@ -26,3 +26,4 @@ jobs:
       - run: "npm run lint:markdown"
       - run: "npm run lint:eslint"
       - run: "npm run lint:prettier"
+      - run: "npm run lint:javascript"

.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.0.0"
+        uses: "actions/setup-node@v4.0.1"
         with:
           node-version: "lts/*"
           cache: "npm"

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: "actions/checkout@v4.1.1"
 
       - name: "Setup Node.js"
-        uses: "actions/setup-node@v4.0.0"
+        uses: "actions/setup-node@v4.0.1"
         with:
           node-version: "lts/*"
           cache: "npm"

.husky/pre-commit

@@ -2,4 +2,5 @@
 . "$(dirname "$0")/_/husky.sh"
 
 npm run lint:staged
+npm run lint:javascript
 npm run test

.markdownlint-cli2.jsonc

@@ -6,6 +6,6 @@
     "MD033": false
   },
   "globs": ["**/*.{md,mdx}"],
-  "ignores": ["**/node_modules", "**/test/fixtures"],
+  "ignores": ["**/node_modules", "**/test/fixtures/**"],
   "customRules": ["./src/index.js"]
 }

.vscode/settings.json

@@ -3,6 +3,6 @@
   "prettier.configPath": ".prettierrc.json",
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
-    "source.fixAll": true
+    "source.fixAll": "explicit"
   }
 }

LICENSE

@@ -1,4 +1,4 @@
-MIT License
+# MIT License
 
 Copyright (c) Théo LUDWIG
 

README.md

@@ -43,9 +43,22 @@ With `awesome.md` content:
 Running [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) with `markdownlint-rule-relative-links` will output:
 
 ```sh
-awesome.md:3 relative-links Relative links should be valid [Link "./invalid.txt" should exist in the file system]
+awesome.md:3 relative-links Relative links should be valid ["./invalid.txt" should exist in the file system]
 ```
 
+### Additional features
+
+- Support images (e.g: `![Image](./image.png)`).
+- Support anchors (heading fragment links) (e.g: `[Link](./awesome.md#existing-heading)`).
+- Ignore external links and absolute paths as it only checks relative links (e.g: `https://example.com/` or `/absolute/path.png`).
+
+### Limitations
+
+- Only images and links defined using markdown syntax are supported, html syntax is not supported (e.g: `<a href="./link.txt" />` or `<img src="./image.png" />`).
+- Anchors checking is limited to headings, other elements are not supported (e.g: with a "id", `<div id="anchor" />`).
+
+Contributions are welcome to improve the rule, and to alleviate these limitations. See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
+
 ### Related links
 
 - [DavidAnson/markdownlint#253](https://github.com/DavidAnson/markdownlint/issues/253)

jsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "checkJs": true,
+    "allowJs": true,
+    "noEmit": true,
+    "rootDir": ".",
+    "baseUrl": ".",
+    "strict": true,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package.json

@@ -35,34 +35,37 @@
     "lint:markdown": "markdownlint-cli2",
     "lint:eslint": "eslint . --max-warnings 0 --report-unused-disable-directives --ignore-path .gitignore",
     "lint:prettier": "prettier . --check --ignore-path .gitignore",
+    "lint:javascript": "tsc --project jsconfig.json --noEmit",
     "lint:staged": "lint-staged",
-    "test": "node --test ./test",
+    "test": "node --test --experimental-test-coverage ./test",
     "release": "semantic-release",
     "postinstall": "husky install",
     "prepublishOnly": "pinst --disable",
     "postpublish": "pinst --enable"
   },
   "dependencies": {
-    "markdown-it": "13.0.2"
+    "markdown-it": "14.0.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "18.4.3",
+    "@commitlint/cli": "18.4.4",
-    "@commitlint/config-conventional": "18.4.3",
+    "@commitlint/config-conventional": "18.4.4",
-    "@types/node": "20.9.4",
+    "@types/markdown-it": "13.0.7",
+    "@types/node": "20.10.8",
     "editorconfig-checker": "5.1.2",
-    "eslint": "8.54.0",
+    "eslint": "8.56.0",
-    "eslint-config-conventions": "13.0.0",
+    "eslint-config-conventions": "13.1.0",
-    "eslint-config-prettier": "9.0.0",
+    "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-import": "2.29.0",
+    "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-prettier": "5.0.1",
+    "eslint-plugin-prettier": "5.1.2",
     "eslint-plugin-promise": "6.1.1",
-    "eslint-plugin-unicorn": "49.0.0",
+    "eslint-plugin-unicorn": "50.0.1",
     "husky": "8.0.3",
-    "lint-staged": "15.1.0",
+    "lint-staged": "15.2.0",
-    "markdownlint": "0.32.1",
+    "markdownlint": "0.33.0",
     "markdownlint-cli2": "0.11.0",
     "pinst": "3.0.0",
-    "prettier": "3.1.0",
+    "prettier": "3.1.1",
-    "semantic-release": "22.0.8"
+    "semantic-release": "22.0.12",
+    "typescript": "5.3.3"
   }
 }

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 children = token.children ?? []
-        const { lineNumber, type, attrs } = child
+      for (const child of children) {
+        const { type, attrs, lineNumber } = child
 
-        /** @type {string | null} */
+        /** @type {string | undefined} */
-        let hrefSrc = null
+        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,
 }

test/basic.test.js

@@ -1,46 +0,0 @@
-const test = require("node:test")
-const assert = require("node:assert/strict")
-
-const { markdownlint } = require("markdownlint").promises
-
-const relativeLinks = require("../src/index.js")
-
-test("ensure the rule validate correctly", async () => {
-  const lintResults = await markdownlint({
-    files: ["test/fixtures/Valid.md", "test/fixtures/Invalid.md"],
-    config: {
-      default: false,
-      "relative-links": true,
-    },
-    customRules: [relativeLinks],
-  })
-  assert.equal(lintResults["test/fixtures/Valid.md"].length, 0)
-  assert.equal(lintResults["test/fixtures/Invalid.md"].length, 3)
-
-  assert.equal(
-    lintResults["test/fixtures/Invalid.md"][0]?.ruleDescription,
-    "Relative links should be valid",
-  )
-  assert.equal(
-    lintResults["test/fixtures/Invalid.md"][0]?.errorDetail,
-    'Link "./basic.test.js" should exist in the file system',
-  )
-
-  assert.equal(
-    lintResults["test/fixtures/Invalid.md"][1]?.ruleDescription,
-    "Relative links should be valid",
-  )
-  assert.equal(
-    lintResults["test/fixtures/Invalid.md"][1]?.errorDetail,
-    'Link "../image.png" should exist in the file system',
-  )
-
-  assert.equal(
-    lintResults["test/fixtures/Invalid.md"][2]?.ruleDescription,
-    "Relative links should be valid",
-  )
-  assert.equal(
-    lintResults["test/fixtures/Invalid.md"][2]?.errorDetail,
-    'Link "./Valid.md#not-existing-heading" should have a valid fragment',
-  )
-})

test/fixtures/Invalid.md

@@ -1,19 +0,0 @@
-# Invalid
-
-[basic.js](./basic.test.js)
-
-![Image](../image.png)
-
-[Link fragment](./Valid.md#not-existing-heading)
-
-## Existing Heading
-
-### Repeated Heading
-
-Text
-
-### Repeated Heading
-
-Text
-
-### Repeated Heading

test/fixtures/Valid.md

@@ -1,21 +0,0 @@
-# Valid
-
-[basic.js](../basic.test.js)
-
-![Image](./image.png)
-
-![Absolute Path](/absolute/path.png)
-
-[External https link](https://example.com/)
-
-[External https link 2](https:./external.https)
-
-[External ftp link](ftp:./external.ftp)
-
-[Link fragment](./Invalid.md#existing-heading)
-
-[Link fragment Repeated 0](./Invalid.md#repeated-heading)
-
-[Link fragment Repeated 1](./Invalid.md#repeated-heading-1)
-
-[Link fragment Repeated 2](./Invalid.md#repeated-heading-2)

test/fixtures/invalid/non-existing-file.md

@@ -0,0 +1,3 @@
+# Invalid
+
+[File](./index.test.js)

test/fixtures/invalid/non-existing-heading-fragment/awesome.md

@@ -0,0 +1,3 @@
+# Valid
+
+## Existing Heading

test/fixtures/invalid/non-existing-heading-fragment/non-existing-heading-fragment.md

@@ -0,0 +1,3 @@
+# Invalid
+
+[Link fragment](./awesome.md#non-existing-heading)

test/fixtures/invalid/non-existing-image.md

@@ -0,0 +1,3 @@
+# Invalid
+
+![Image](./image.png)

test/fixtures/valid/existing-file.md

@@ -0,0 +1,3 @@
+# Valid
+
+[File](../../index.test.js)

test/fixtures/valid/existing-heading-fragment/awesome.md

@@ -0,0 +1,13 @@
+# Valid
+
+## Existing Heading
+
+### Repeated Heading
+
+Text
+
+### Repeated Heading
+
+Text
+
+### Repeated Heading

test/fixtures/valid/existing-heading-fragment/existing-heading-fragment.md

@@ -0,0 +1,9 @@
+# Valid
+
+[Link fragment](./awesome.md#existing-heading)
+
+[Link fragment Repeated 0](./awesome.md#repeated-heading)
+
+[Link fragment Repeated 1](./awesome.md#repeated-heading-1)
+
+[Link fragment Repeated 2](./awesome.md#repeated-heading-2)

test/fixtures/valid/existing-image.md

@@ -0,0 +1,3 @@
+# Valid
+
+![Image](./image.png)

test/fixtures/valid/ignore-absolute-paths.md

@@ -0,0 +1,3 @@
+# Valid
+
+![Absolute Path](/absolute/path.png)

test/fixtures/valid/ignore-external-links.md

@@ -0,0 +1,7 @@
+# Valid
+
+[External https link](https://example.com/)
+
+[External https link 2](https:./external.https)
+
+[External ftp link](ftp:./external.ftp)

test/index.test.js

@@ -0,0 +1,112 @@
+const { test } = require("node:test")
+const assert = require("node:assert/strict")
+
+const { markdownlint } = require("markdownlint").promises
+
+const relativeLinksRule = require("../src/index.js")
+
+/**
+ *
+ * @param {string} fixtureFile
+ * @returns
+ */
+const validateMarkdownLint = async (fixtureFile) => {
+  const lintResults = await markdownlint({
+    files: [fixtureFile],
+    config: {
+      default: false,
+      "relative-links": true,
+    },
+    customRules: [relativeLinksRule],
+  })
+  return lintResults[fixtureFile]
+}
+
+test("ensure the rule validates correctly", async (t) => {
+  await t.test("should be valid", async (t) => {
+    await t.test("with an existing heading fragment", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/valid/existing-heading-fragment/existing-heading-fragment.md",
+      )
+      assert.equal(lintResults?.length, 0)
+    })
+
+    await t.test("with an existing file", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/valid/existing-file.md",
+      )
+      assert.equal(lintResults?.length, 0)
+    })
+
+    await t.test("with an existing image", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/valid/existing-image.md",
+      )
+      assert.equal(lintResults?.length, 0)
+    })
+
+    await t.test("should ignore absolute paths", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/valid/ignore-absolute-paths.md",
+      )
+      assert.equal(lintResults?.length, 0)
+    })
+
+    await t.test("should ignore external links", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/valid/ignore-external-links.md",
+      )
+      assert.equal(lintResults?.length, 0)
+    })
+  })
+
+  await t.test("should be invalid", async (t) => {
+    await t.test("with a non-existing heading fragment", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/invalid/non-existing-heading-fragment/non-existing-heading-fragment.md",
+      )
+      assert.equal(lintResults?.length, 1)
+      assert.deepEqual(lintResults?.[0]?.ruleNames, relativeLinksRule.names)
+      assert.equal(
+        lintResults?.[0]?.ruleDescription,
+        relativeLinksRule.description,
+      )
+      assert.equal(
+        lintResults?.[0]?.errorDetail,
+        '"./awesome.md#non-existing-heading" should have a valid fragment identifier',
+      )
+    })
+
+    await t.test("with a non-existing file", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/invalid/non-existing-file.md",
+      )
+      assert.equal(lintResults?.length, 1)
+      assert.deepEqual(lintResults?.[0]?.ruleNames, relativeLinksRule.names)
+      assert.equal(
+        lintResults?.[0]?.ruleDescription,
+        relativeLinksRule.description,
+      )
+      assert.equal(
+        lintResults?.[0]?.errorDetail,
+        '"./index.test.js" should exist in the file system',
+      )
+    })
+
+    await t.test("with a non-existing image", async () => {
+      const lintResults = await validateMarkdownLint(
+        "test/fixtures/invalid/non-existing-image.md",
+      )
+      assert.equal(lintResults?.length, 1)
+      assert.deepEqual(lintResults?.[0]?.ruleNames, relativeLinksRule.names)
+      assert.equal(
+        lintResults?.[0]?.ruleDescription,
+        relativeLinksRule.description,
+      )
+      assert.equal(
+        lintResults?.[0]?.errorDetail,
+        '"./image.png" should exist in the file system',
+      )
+    })
+  })
+})

test/utils.test.js

@@ -1,4 +1,4 @@
-const test = require("node:test")
+const { test } = require("node:test")
 const assert = require("node:assert/strict")
 
 const {