feat: add no-missing-link-fragments rule

README.md

@@ -82,6 +82,7 @@ export default defineConfig([
 | [`no-html`](./docs/rules/no-html.md) | Disallow HTML tags | no |
 | [`no-invalid-label-refs`](./docs/rules/no-invalid-label-refs.md) | Disallow invalid label references | yes |
 | [`no-missing-label-refs`](./docs/rules/no-missing-label-refs.md) | Disallow missing label references | yes |
+| [`no-missing-link-fragments`](./docs/rules/no-missing-link-fragments.md) | Disallow link fragments that don't exist in the document | yes |
 | [`require-alt-text`](./docs/rules/require-alt-text.md) | Require alternative text for images | yes |
 <!-- Rule Table End -->
 

docs/rules/no-missing-link-fragments.md

@@ -0,0 +1,83 @@
+# no-missing-link-fragments
+
+Ensures that link fragments (URLs that start with `#`) reference valid headings or anchors in the document. This rule helps prevent broken internal links.
+
+## Rule Details
+
+This rule is triggered when a link fragment does not match any of the fragments that are automatically generated for headings in a document or explicitly defined via HTML anchors or custom heading IDs.
+
+Examples of **incorrect** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-missing-link-fragments: "error" -->
+
+[Invalid Link](#non-existent-heading)
+
+# Some Heading
+[Case Mismatch](#SOME-HEADING) <!-- Default: case-sensitive -->
+```
+
+### Correct Code Examples
+
+```markdown
+<!-- eslint markdown/no-missing-link-fragments: "error" -->
+
+# Introduction
+[Valid Link](#introduction)
+
+# Another Section {#custom-id}
+[Link to custom ID](#custom-id)
+
+<p id="html-anchor">HTML Anchor</p>
+[Link to HTML anchor](#html-anchor)
+
+<a name="named-anchor">Named Anchor</a>
+[Link to named anchor](#named-anchor)
+
+[Link to top of page](#top)
+
+<!-- With ignoreCase: true -->
+<!-- eslint markdown/no-missing-link-fragments: ["error", { "ignoreCase": true }] -->
+# Case Test
+[Valid Link with different case](#CASE-TEST)
+
+<!-- With allowPattern: "^figure-" -->
+<!-- eslint markdown/no-missing-link-fragments: ["error", { "allowPattern": "^figure-" }] -->
+[Ignored Link](#figure-123)
+```
+
+## Options
+
+This rule supports the following options:
+
+* `ignoreCase` (boolean, default: `false`):
+    When `true`, link fragments are compared with heading and anchor IDs in a case-insensitive manner.
+
+    ```json
+    {
+      "ignoreCase": true
+    }
+    ```
+
+* `allowPattern` (string, default: `""`):
+    A regular expression string. If a link fragment matches this pattern, it will be ignored by the rule. This is useful for fragments that are dynamically generated or handled by other tools.
+
+    ```json
+    {
+      "allowPattern": "^figure-"
+    }
+    ```
+
+    Example: If `allowPattern` is `"^temp-"`, links like `[Link](#temp-section)` will not be checked.
+
+## When Not To Use It
+
+You might consider disabling this rule if:
+
+* You are using a Markdown processor or static site generator that has a significantly different algorithm for generating heading IDs, and this rule produces too many false positives.
+* You have many dynamically generated links or fragments that cannot be easily covered by the `allowPattern` option.
+
+## Further Reading
+
+* [GitHub's heading anchor links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links)
+* [CommonMark Specification](https://spec.commonmark.org/)

package.json

@@ -89,6 +89,7 @@
   "dependencies": {
     "@eslint/core": "^0.14.0",
     "@eslint/plugin-kit": "^0.3.1",
+    "github-slugger": "^2.0.0",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-frontmatter": "^2.0.1",
     "mdast-util-gfm": "^3.0.0",

src/rules/no-missing-link-fragments.js

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview Rule to ensure link fragments (URLs that start with #) reference valid headings
+ * @author Sweta Tanwar (@SwetaTanwar)
+ */
+
+import GithubSlugger from "github-slugger";
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{
+ *   RuleOptions: [{
+ *     ignoreCase?: boolean;
+ *     allowPattern?: string;
+ *   }];
+ * }>} NoMissingLinkFragmentsRuleDefinition
+ */
+
+/**
+ * @typedef {import("mdast").Node & {
+ *   children?: Array<import("mdast").Node>;
+ *   value?: string;
+ * }} NodeWithChildren
+ */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+const githubLineReferencePattern = /^L\d+(?:C\d+)?(?:-L\d+(?:C\d+)?)?$/u;
+const customHeadingIdPattern = /\{#([a-z0-9_-]+)\}\s*$/u;
+const markdownInlineFormattingPattern = /[*_~`]/gu;
+const htmlIdNamePattern = /<(?:[^>]+)\s+(?:id|name)="([^"]+)"/gu;
+const headingPrefixPattern = /^#+\s*/u;
+
+/**
+ * Checks if the fragment is a valid GitHub line reference
+ * @param {string} fragment The fragment to check
+ * @returns {boolean} Whether the fragment is a valid GitHub line reference
+ */
+function isGitHubLineReference(fragment) {
+	return githubLineReferencePattern.test(fragment);
+}
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+/** @type {NoMissingLinkFragmentsRuleDefinition} */
+export default {
+	meta: {
+		type: "problem",
+
+		docs: {
+			recommended: true,
+			description:
+				"Disallow link fragments that do not reference valid headings",
+			url: "https://github.com/eslint/markdown/blob/main/docs/rules/no-missing-link-fragments.md",
+		},
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					ignoreCase: {
+						type: "boolean",
+						default: false,
+					},
+					allowPattern: {
+						type: "string",
+						default: "",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+
+		messages: {
+			invalidFragment:
+				"Link fragment '{{fragment}}' does not reference a valid heading or anchor.",
+		},
+	},
+
+	create(context) {
+		const options = context.options[0] || {};
+		const ignoreCase = options.ignoreCase || false;
+		const allowPattern = options.allowPattern
+			? new RegExp(options.allowPattern, "u")
+			: null;
+
+		const slugger = new GithubSlugger();
+		const fragmentIds = new Set();
+
+		fragmentIds.add("top");
+
+		/**
+		 * Generates a heading ID using the shared slugger instance.
+		 * Handles custom IDs and plain text slugging.
+		 * @param {string} headingText The heading text.
+		 * @returns {string} The normalized heading ID.
+		 */
+		function getHeadingId(headingText) {
+			const customIdMatch = headingText.match(customHeadingIdPattern);
+			if (customIdMatch) {
+				return customIdMatch[1];
+			}
+			const plainText = headingText
+				.replace(markdownInlineFormattingPattern, "")
+				.trim();
+			return slugger.slug(plainText);
+		}
+
+		return {
+			heading(node) {
+				const headingText = context.sourceCode
+					.getText(node)
+					.replace(headingPrefixPattern, "")
+					.trim();
+				const id = getHeadingId(headingText);
+				fragmentIds.add(ignoreCase ? id.toLowerCase() : id);
+			},
+
+			html(node) {
+				if (node.value) {
+					const htmlText = node.value.trim();
+					if (
+						htmlText.startsWith("<!--") &&
+						htmlText.endsWith("-->")
+					) {
+						return;
+					}
+
+					const idMatches = htmlText.matchAll(htmlIdNamePattern);
+					for (const match of idMatches) {
+						const extractedId = match[1];
+						fragmentIds.add(
+							ignoreCase
+								? extractedId.toLowerCase()
+								: extractedId,
+						);
+					}
+				}
+			},
+
+			link(node) {
+				const url = node.url;
+				if (!url || !url.startsWith("#")) {
+					return;
+				}
+
+				const fragment = url.slice(1);
+				if (!fragment) {
+					return;
+				}
+
+				if (allowPattern && allowPattern.test(fragment)) {
+					return;
+				}
+
+				if (isGitHubLineReference(fragment)) {
+					return;
+				}
+
+				const normalizedFragment = ignoreCase
+					? fragment.toLowerCase()
+					: fragment;
+
+				if (!fragmentIds.has(normalizedFragment)) {
+					context.report({
+						loc: node.position,
+						messageId: "invalidFragment",
+						data: { fragment },
+					});
+				}
+			},
+		};
+	},
+};