feat: validate relative links fragments

Similar to https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md

Fixes #2

BREAKING CHANGE: Validate links fragments in relative links

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 <!-- Please first discuss the change you wish to make via issue before making a change. It might avoid a waste of your time. -->
 
-## What changes this PR introduce?
+# What changes this PR introduce?
 
 ## List any relevant issue numbers
 

.github/workflows/lint.yml

@@ -10,16 +10,16 @@ jobs:
   lint:
     runs-on: 'ubuntu-latest'
     steps:
-      - uses: 'actions/checkout@v3.5.0'
+      - uses: 'actions/checkout@v3.5.2'
 
-      - name: 'Use Node.js'
+      - name: 'Setup Node.js'
         uses: 'actions/setup-node@v3.6.0'
         with:
           node-version: 'lts/*'
           cache: 'npm'
 
-      - name: 'Install'
+      - name: 'Install dependencies'
-        run: 'npm install'
+        run: 'npm clean-install'
 
       - run: 'npm run lint:commit -- --to "${{ github.sha }}"'
       - run: 'npm run lint:editorconfig'

.github/workflows/release.yml

@@ -7,20 +7,28 @@ on:
 jobs:
   release:
     runs-on: 'ubuntu-latest'
+    permissions:
+      contents: 'write'
+      issues: 'write'
+      pull-requests: 'write'
+      id-token: 'write'
     steps:
-      - uses: 'actions/checkout@v3.5.0'
+      - uses: 'actions/checkout@v3.5.2'
         with:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: 'Use Node.js'
+      - name: 'Setup Node.js'
         uses: 'actions/setup-node@v3.6.0'
         with:
           node-version: 'lts/*'
           cache: 'npm'
 
-      - name: 'Install'
+      - name: 'Install dependencies'
-        run: 'npm install'
+        run: 'npm clean-install'
+
+      - name: 'Verify the integrity of provenance attestations and registry signatures for installed dependencies'
+        run: 'npm audit signatures'
 
       - name: 'Release'
         run: 'npm run release'

.github/workflows/test.yml

@@ -10,16 +10,16 @@ jobs:
   test:
     runs-on: 'ubuntu-latest'
     steps:
-      - uses: 'actions/checkout@v3.5.0'
+      - uses: 'actions/checkout@v3.5.2'
 
-      - name: 'Use Node.js'
+      - name: 'Setup Node.js'
         uses: 'actions/setup-node@v3.6.0'
         with:
           node-version: 'lts/*'
           cache: 'npm'
 
-      - name: 'Install'
+      - name: 'Install dependencies'
-        run: 'npm install'
+        run: 'npm clean-install'
 
       - name: 'Test'
         run: 'npm run test'

.markdownlint-cli2.jsonc

@@ -1,4 +1,10 @@
 {
+  "config": {
+    "extends": "markdownlint/style/prettier",
+    "relative-links": true,
+    "default": true,
+    "MD033": false
+  },
   "globs": ["**/*.{md,mdx}"],
   "ignores": ["**/node_modules", "**/test/fixtures"],
   "customRules": ["./src/index.js"]

.markdownlint.json

@@ -1,8 +0,0 @@
-{
-  "default": true,
-  "relative-links": true,
-  "extends": "markdownlint/style/prettier",
-  "MD024": false,
-  "MD033": false,
-  "MD041": false
-}

.npmrc

@@ -1 +1,2 @@
 save-exact=true
+provenance=true

.taprc

@@ -1,8 +0,0 @@
-ts: false
-jsx: false
-flow: false
-check-coverage: false
-coverage: false
-
-files:
-  - 'test/**/*.test.js'

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-contact@divlo.fr.
+<contact@theoludwig.fr>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

CONTRIBUTING.md

@@ -2,6 +2,14 @@
 
 Thanks a lot for your interest in contributing to **markdownlint-rule-relative-links**! 🎉
 
+## Code of Conduct
+
+**markdownlint-rule-relative-links** adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](./CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
+
+## Open Development
+
+All work on **markdownlint-rule-relative-links** happens directly on this repository. Both core team members and external contributors send pull requests which go through the same review process.
+
 ## Types of contributions
 
 - Reporting a bug.
@@ -11,7 +19,7 @@ Thanks a lot for your interest in contributing to **markdownlint-rule-relative-l
 
 ## Pull Requests
 
-- **Please first discuss** the change you wish to make via [issue](https://github.com/Divlo/markdownlint-rule-relative-links/issues) before making a change. It might avoid a waste of your time.
+- **Please first discuss** the change you wish to make via [issue](https://github.com/theoludwig/markdownlint-rule-relative-links/issues) before making a change. It might avoid a waste of your time.
 
 - Ensure your code respect linting.
 
@@ -21,26 +29,4 @@ If you're adding new features to **markdownlint-rule-relative-links**, please in
 
 ## Commits
 
-The commit message guidelines respect [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) and [Semantic Versioning](https://semver.org/) for releases.
+The commit message guidelines adheres to [Conventional Commits](https://www.conventionalcommits.org/) and [Semantic Versioning](https://semver.org/) for releases.
-
-### Types
-
-Types define which kind of changes you made to the project.
-
-| Types    | Description                                                                                                  |
-| -------- | ------------------------------------------------------------------------------------------------------------ |
-| feat     | A new feature.                                                                                               |
-| fix      | A bug fix.                                                                                                   |
-| docs     | Documentation only changes.                                                                                  |
-| style    | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).      |
-| refactor | A code change that neither fixes a bug nor adds a feature.                                                   |
-| perf     | A code change that improves performance.                                                                     |
-| test     | Adding missing tests or correcting existing tests.                                                           |
-| build    | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).         |
-| ci       | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs). |
-| chore    | Other changes that don't modify src or test files.                                                           |
-| revert   | Reverts a previous commit.                                                                                   |
-
-### Scopes
-
-Scopes define what part of the code changed.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Divlo
+Copyright (c) Théo LUDWIG
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -9,8 +9,8 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/licence-MIT-blue.svg" alt="Licence MIT"/></a>
   <a href="./CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg" alt="Contributor Covenant" /></a>
   <br />
-  <a href="https://github.com/Divlo/markdownlint-rule-relative-links/actions/workflows/lint.yml"><img src="https://github.com/Divlo/markdownlint-rule-relative-links/actions/workflows/lint.yml/badge.svg?branch=develop" /></a>
+  <a href="https://github.com/theoludwig/markdownlint-rule-relative-links/actions/workflows/lint.yml"><img src="https://github.com/theoludwig/markdownlint-rule-relative-links/actions/workflows/lint.yml/badge.svg?branch=develop" /></a>
-  <a href="https://github.com/Divlo/markdownlint-rule-relative-linksactions/workflows/test.yml"><img src="https://github.com/Divlo/markdownlint-rule-relative-links/actions/workflows/test.yml/badge.svg?branch=develop" /></a>
+  <a href="https://github.com/theoludwig/markdownlint-rule-relative-linksactions/workflows/test.yml"><img src="https://github.com/theoludwig/markdownlint-rule-relative-links/actions/workflows/test.yml/badge.svg?branch=develop" /></a>
   <br />
   <a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg" alt="Conventional Commits" /></a>
   <a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="semantic-release" /></a>
@@ -21,7 +21,7 @@
 
 **markdownlint-rule-relative-links** is a [markdownlint](https://github.com/DavidAnson/markdownlint) custom rule to validate relative links.
 
-It ensures that relative links (using `file:` protocol) are working and not "dead" which means that it exists in the file system of the project that uses `markdownlint`.
+It ensures that relative links (using `file:` protocol) are working and not "dead" which means that it exists in the file system of the project that uses [markdownlint](https://github.com/DavidAnson/markdownlint).
 
 ### Example
 
@@ -40,7 +40,7 @@ With `awesome.md` content:
 [Dead link](./dead.txt)
 ```
 
-Running `markdownlint-cli2` with `markdownlint-rule-relative-links` will output:
+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 "./dead.txt" is dead]
@@ -64,9 +64,9 @@ npm install --save-dev markdownlint-rule-relative-links
 
 ## Configuration
 
-There are various ways `markdownlint` can be configured using objects, config files etc. For more information on `markdownlint` configuration refer [options.config](https://github.com/DavidAnson/markdownlint#optionsconfig).
+There are various ways [markdownlint](https://github.com/DavidAnson/markdownlint) can be configured using objects, config files etc. For more information on configuration refer to [options.config](https://github.com/DavidAnson/markdownlint#optionsconfig).
 
-We recommend configuring `markdownlint-cli2` over `markdownlint-cli` for compatibility with the `vscode-markdownlint` plugin.
+We recommend configuring [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) over [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) for compatibility with the [vscode-markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension.
 
 `.markdownlint-cli2.jsonc`
 

package.json

@@ -3,16 +3,16 @@
   "version": "0.0.0-development",
   "public": true,
   "description": "Custom rule for markdownlint to validate relative links.",
-  "author": "Divlo <contact@divlo.fr>",
+  "author": "Théo LUDWIG <contact@theoludwig.fr>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Divlo/markdownlint-rule-relative-links.git"
+    "url": "https://github.com/theoludwig/markdownlint-rule-relative-links.git"
   },
   "bugs": {
-    "url": "https://github.com/Divlo/markdownlint-rule-relative-links/issues"
+    "url": "https://github.com/theoludwig/markdownlint-rule-relative-links/issues"
   },
-  "homepage": "https://github.com/Divlo/markdownlint-rule-relative-links#readme",
+  "homepage": "https://github.com/theoludwig/markdownlint-rule-relative-links#readme",
   "keywords": [
     "markdownlint",
     "markdownlint-rule"
@@ -21,42 +21,48 @@
   "files": [
     "src"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "engines": {
     "node": ">=16.0.0",
-    "npm": ">=8.0.0"
+    "npm": ">=9.0.0"
   },
   "scripts": {
     "lint:commit": "commitlint",
     "lint:editorconfig": "editorconfig-checker",
     "lint:markdown": "markdownlint-cli2",
-    "lint:eslint": "eslint \".\" --ignore-path \".gitignore\"",
+    "lint:eslint": "eslint . --ignore-path .gitignore",
-    "lint:prettier": "prettier \".\" --check --ignore-path \".gitignore\"",
+    "lint:prettier": "prettier . --check --ignore-path .gitignore",
     "lint:staged": "lint-staged",
-    "test": "tap",
+    "test": "node --test ./test",
     "release": "semantic-release",
     "postinstall": "husky install",
     "prepublishOnly": "pinst --disable",
     "postpublish": "pinst --enable"
   },
+  "dependencies": {
+    "markdown-it": "13.0.1"
+  },
   "devDependencies": {
-    "@commitlint/cli": "17.5.1",
+    "@commitlint/cli": "17.6.5",
-    "@commitlint/config-conventional": "17.4.4",
+    "@commitlint/config-conventional": "17.6.5",
-    "@types/tap": "15.0.8",
+    "@types/node": "20.3.1",
     "editorconfig-checker": "5.0.1",
-    "eslint": "8.37.0",
+    "eslint": "8.43.0",
-    "eslint-config-conventions": "8.0.0",
+    "eslint-config-conventions": "9.0.0",
     "eslint-config-prettier": "8.8.0",
     "eslint-plugin-import": "2.27.5",
     "eslint-plugin-prettier": "4.2.1",
     "eslint-plugin-promise": "6.1.1",
-    "eslint-plugin-unicorn": "46.0.0",
+    "eslint-plugin-unicorn": "47.0.0",
     "husky": "8.0.3",
-    "lint-staged": "13.2.0",
+    "lint-staged": "13.2.2",
-    "markdownlint": "0.28.0",
+    "markdownlint": "0.29.0",
-    "markdownlint-cli2": "0.6.0",
+    "markdownlint-cli2": "0.8.1",
     "pinst": "3.0.0",
-    "prettier": "2.8.7",
+    "prettier": "2.8.8",
-    "semantic-release": "21.0.1",
+    "semantic-release": "21.0.5"
-    "tap": "16.3.4"
   }
 }

src/index.js

@@ -3,42 +3,12 @@
 const { pathToFileURL } = require('node:url')
 const fs = require('node:fs')
 
-/**
+const {
- * Calls the provided function for each matching token.
+  filterTokens,
- *
+  addError,
- * @param {Object} params RuleParams instance.
+  convertHeadingToHTMLFragment,
- * @param {string} type Token type identifier.
+  getMarkdownHeadings
- * @param {Function} handler Callback function.
+} = require('./utils.js')
- * @returns {void}
- */
-const filterTokens = (params, type, handler) => {
-  for (const token of params.tokens) {
-    if (token.type === type) {
-      handler(token)
-    }
-  }
-}
-
-/**
- * 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
-  })
-}
 
 const customRule = {
   names: ['relative-links'],
@@ -70,12 +40,37 @@ const customRule = {
 
         if (hrefSrc != null) {
           const url = new URL(hrefSrc, pathToFileURL(params.name))
-          url.hash = ''
           const isRelative =
             url.protocol === 'file:' && !hrefSrc.startsWith('/')
-          if (isRelative && !fs.existsSync(url)) {
+          if (isRelative) {
-            const detail = `Link "${hrefSrc}" is dead`
+            const detail = `Link "${hrefSrc}" is not valid`
+
+            if (!fs.existsSync(url)) {
               addError(onError, lineNumber, detail)
+              return
+            }
+
+            if (type === 'link_open' && url.hash !== '') {
+              const fileContent = fs.readFileSync(url, { encoding: 'utf8' })
+              const headings = getMarkdownHeadings(fileContent)
+
+              /** @type {Map<string, number>} */
+              const fragments = new Map()
+
+              const headingsHTMLFragments = headings.map((heading) => {
+                const fragment = convertHeadingToHTMLFragment(heading)
+                const count = fragments.get(fragment) ?? 0
+                fragments.set(fragment, count + 1)
+                if (count !== 0) {
+                  return `${fragment}-${count}`
+                }
+                return fragment
+              })
+
+              if (!headingsHTMLFragments.includes(url.hash)) {
+                addError(onError, lineNumber, detail)
+              }
+            }
           }
         }
       })

src/utils.js

@@ -0,0 +1,120 @@
+const MarkdownIt = require('markdown-it')
+
+/**
+ * Calls the provided function for each matching token.
+ *
+ * @param {Object} params RuleParams instance.
+ * @param {string} type Token type identifier.
+ * @param {Function} handler Callback function.
+ * @returns {void}
+ */
+const filterTokens = (params, type, handler) => {
+  for (const token of params.tokens) {
+    if (token.type === type) {
+      handler(token)
+    }
+  }
+}
+
+/**
+ * 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.
+ *
+ * Taken from <https://github.com/DavidAnson/markdownlint/blob/d01180ec5a014083ee9d574b693a8d7fbc1e566d/lib/md051.js#L19>
+ *
+ * @param {string} inlineText Inline token for heading.
+ * @returns {string} Fragment string for heading.
+ */
+const convertHeadingToHTMLFragment = (inlineText) => {
+  return (
+    '#' +
+    encodeURIComponent(
+      inlineText
+        .toLowerCase()
+        // RegExp source with Ruby's \p{Word} expanded into its General Categories
+        // eslint-disable-next-line max-len
+        // https://github.com/gjtorikian/html-pipeline/blob/main/lib/html/pipeline/toc_filter.rb
+        // https://ruby-doc.org/core-3.0.2/Regexp.html
+        .replace(
+          /[^\p{Letter}\p{Mark}\p{Number}\p{Connector_Punctuation}\- ]/gu,
+          ''
+        )
+        .replace(/ /gu, '-')
+    )
+  )
+}
+
+const headingTags = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+const ignoredTokens = new Set(['heading_open', 'heading_close'])
+
+/**
+ * Gets the headings from a Markdown string.
+ * @param {string} content
+ * @returns {string[]}
+ */
+const getMarkdownHeadings = (content) => {
+  const markdownIt = new MarkdownIt({ html: true })
+  const tokens = markdownIt.parse(content, {})
+
+  /** @type {string[]} */
+  const headings = []
+
+  /** @type {string | null} */
+  let headingToken = null
+
+  for (const token of tokens) {
+    if (headingTags.has(token.tag)) {
+      if (token.type === 'heading_open') {
+        headingToken = token.markup
+      } else if (token.type === 'heading_close') {
+        headingToken = null
+      }
+    }
+
+    if (ignoredTokens.has(token.type)) {
+      continue
+    }
+
+    if (headingToken === null) {
+      continue
+    }
+
+    headings.push(
+      `${token.children
+        .map((token) => {
+          return token.content
+        })
+        .join('')}`
+    )
+  }
+
+  return headings
+}
+
+module.exports = {
+  filterTokens,
+  addError,
+  convertHeadingToHTMLFragment,
+  getMarkdownHeadings
+}

test/basic.test.js

@@ -1,34 +1,46 @@
-const tap = require('tap')
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
 const { markdownlint } = require('markdownlint').promises
 
 const relativeLinks = require('../src/index.js')
 
-tap.test('ensure we validate correctly', async (t) => {
+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]
   })
-  t.equal(lintResults['test/fixtures/Valid.md'].length, 0)
+  assert.equal(lintResults['test/fixtures/Valid.md'].length, 0)
-  t.equal(lintResults['test/fixtures/Invalid.md'].length, 2)
+  assert.equal(lintResults['test/fixtures/Invalid.md'].length, 3)
 
-  t.equal(
+  assert.equal(
     lintResults['test/fixtures/Invalid.md'][0]?.ruleDescription,
     'Relative links should be valid'
   )
-  t.equal(
+  assert.equal(
     lintResults['test/fixtures/Invalid.md'][0]?.errorDetail,
-    'Link "./basic.test.js" is dead'
+    'Link "./basic.test.js" is not valid'
   )
 
-  t.equal(
+  assert.equal(
     lintResults['test/fixtures/Invalid.md'][1]?.ruleDescription,
     'Relative links should be valid'
   )
-  t.equal(
+  assert.equal(
     lintResults['test/fixtures/Invalid.md'][1]?.errorDetail,
-    'Link "../image.png" is dead'
+    'Link "../image.png" is not valid'
+  )
+
+  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" is not valid'
   )
 })

test/fixtures/Invalid.md

@@ -3,3 +3,17 @@
 [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

@@ -11,3 +11,11 @@
 [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/utils.test.js

@@ -0,0 +1,37 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
+const {
+  convertHeadingToHTMLFragment,
+  getMarkdownHeadings
+} = require('../src/utils.js')
+
+test('utils', async (t) => {
+  await t.test('convertHeadingToHTMLFragment', async () => {
+    assert.strictEqual(
+      convertHeadingToHTMLFragment('Valid Fragments'),
+      '#valid-fragments'
+    )
+    assert.strictEqual(
+      convertHeadingToHTMLFragment('Valid Heading With Underscores _'),
+      '#valid-heading-with-underscores-_'
+    )
+    assert.strictEqual(
+      convertHeadingToHTMLFragment(
+        `Valid Heading With Quotes ' And Double Quotes "`
+      ),
+      '#valid-heading-with-quotes--and-double-quotes-'
+    )
+    assert.strictEqual(
+      convertHeadingToHTMLFragment('🚀 Valid Heading With Emoji'),
+      '#-valid-heading-with-emoji'
+    )
+  })
+
+  await t.test('getMarkdownHeadings', async () => {
+    assert.deepStrictEqual(
+      getMarkdownHeadings('# Hello\n\n## World\n\n## Hello, world!\n'),
+      ['Hello', 'World', 'Hello, world!']
+    )
+  })
+})