feat: create no-unused-definitions rule

README.md

@@ -102,6 +102,7 @@ export default defineConfig([
 | [`no-missing-link-fragments`](./docs/rules/no-missing-link-fragments.md) | Disallow link fragments that do not reference valid headings | yes |
 | [`no-multiple-h1`](./docs/rules/no-multiple-h1.md) | Disallow multiple H1 headings in the same document | yes |
 | [`no-reversed-media-syntax`](./docs/rules/no-reversed-media-syntax.md) | Disallow reversed link and image syntax | yes |
+| [`no-unused-definitions`](./docs/rules/no-unused-definitions.md) | Disallow unused definitions | yes |
 | [`require-alt-text`](./docs/rules/require-alt-text.md) | Require alternative text for images | yes |
 | [`table-column-count`](./docs/rules/table-column-count.md) | Disallow data rows in a GitHub Flavored Markdown table from having more cells than the header row | yes |
 <!-- Rule Table End -->

docs/rules/no-unused-definitions.md

@@ -0,0 +1,102 @@
+# no-unused-definitions
+
+Disallow unused definitions.
+
+## Background
+
+In Markdown, you can define reference-style links, images, and footnotes using definitions that appear elsewhere in the document. These definitions consist of an identifier followed by a URL, image source, or footnote content. However, when definitions are created but never referenced in the document, they become unused and potentially confusing.
+
+Unused definitions can cause several issues:
+
+- They add unnecessary clutter to the document.
+- They might indicate broken references or content that was intended to be included.
+- They can mislead readers who might assume the definitions are purposefully being used somewhere.
+
+Cleaning up unused definitions helps maintain a more organized and intentional document structure.
+
+## Rule Details
+
+> [!IMPORTANT] <!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+>
+> The footnotes are only supported when using `language` mode [`markdown/gfm`](/README.md#languages).
+
+This rule warns about unused reference definitions in Markdown documents. It detects definition entries (e.g., `[reference-id]: http://example.com`) that aren't used by any links, images, or footnotes in the document, and reports them as violations. Please note that this rule doesn't report definition-style comments (e.g., `[//]: # (This is a comment)`) by default.
+
+Examples of **incorrect** code:
+
+```markdown
+<!-- eslint markdown/no-unused-definitions: "error" -->
+
+<!-- definition -->
+
+[mercury]: https://example.com/mercury/
+
+[venus]: https://example.com/venus.jpg
+
+<!-- footnote definition -->
+
+[^mercury]: Hello, Mercury!
+```
+
+Examples of **correct** code:
+
+```markdown
+<!-- eslint markdown/no-unused-definitions: "error" -->
+
+<!-- definition -->
+
+[Mercury][mercury]
+
+[mercury]: https://example.com/mercury/
+
+![Venus Image][venus]
+
+[venus]: https://example.com/venus.jpg
+
+<!-- footnote definition -->
+
+Mercury[^mercury]
+
+[^mercury]: Hello, Mercury!
+
+<!-- definition-style comment -->
+
+[//]: # (This is a comment 1)
+[//]: <> (This is a comment 2)
+```
+
+## Options
+
+- `allowDefinitions: Array<string>` - when specified, unused definitions are allowed if they match one of the identifiers in this array. This is useful for ignoring definitions that are intentionally unused. (default: `["//"]`)
+
+    Examples of **correct** code when configured as `"no-unused-definitions": ["error", { allowDefinitions: ["mercury"] }]`:
+
+    ```markdown
+    <!-- eslint markdown/no-unused-definitions: ["error", { allowDefinitions: ["mercury"] }] -->
+
+    [mercury]: https://example.com/mercury/
+    [mercury]: https://example.com/venus/
+    ```
+
+- `allowFootnoteDefinitions: Array<string>` - when specified, unused footnote definitions are allowed if they match one of the identifiers in this array. This is useful for ignoring footnote definitions that are intentionally unused. (default: `[]`)
+
+    Examples of **correct** code when configured as `"no-unused-definitions": ["error", { allowFootnoteDefinitions: ["mercury"] }]`:
+
+    ```markdown
+    <!-- eslint markdown/no-unused-definitions: ["error", { allowFootnoteDefinitions: ["mercury"] }] -->
+
+    [^mercury]: Hello, Mercury!
+    [^mercury]: Hello, Venus!
+    ```
+
+## When Not to Use It
+
+You might want to disable this rule if:
+
+- You're maintaining a document with intentionally defined but temporarily unused references.
+- You're using reference definitions as a form of comment or placeholder for future content.
+
+## Prior Art
+
+- [MD053 - Link and image reference definitions should be needed](https://github.com/DavidAnson/markdownlint/blob/main/doc/md053.md#md053---link-and-image-reference-definitions-should-be-needed)
+- [remark-lint-no-unused-definitions](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions#remark-lint-no-unused-definitions)

src/rules/no-unused-definitions.js

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Rule to prevent unused definitions in Markdown.
+ * @author 루밀LuMir(lumirlumir)
+ */
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/**
+ * @import { Definition, FootnoteDefinition } from "mdast";
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"unusedDefinition" | "unusedFootnoteDefinition"} NoUnusedDefinitionsMessageIds
+ * @typedef {[{ allowDefinitions?: string[], allowFootnoteDefinitions?: string[] }]} NoUnusedDefinitionsOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoUnusedDefinitionsOptions, MessageIds: NoUnusedDefinitionsMessageIds }>} NoUnusedDefinitionsRuleDefinition
+ */
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+/** @type {NoUnusedDefinitionsRuleDefinition} */
+export default {
+	meta: {
+		type: "problem",
+
+		docs: {
+			recommended: true,
+			description: "Disallow unused definitions",
+			url: "https://github.com/eslint/markdown/blob/main/docs/rules/no-unused-definitions.md",
+		},
+
+		messages: {
+			unusedDefinition:
+				"Unexpected unused definition `{{ identifier }}` found.",
+			unusedFootnoteDefinition:
+				"Unexpected unused footnote definition `{{ identifier }}` found.",
+		},
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					allowDefinitions: {
+						type: "array",
+						items: {
+							type: "string",
+						},
+						uniqueItems: true,
+					},
+					allowFootnoteDefinitions: {
+						type: "array",
+						items: {
+							type: "string",
+						},
+						uniqueItems: true,
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+
+		defaultOptions: [
+			{
+				allowDefinitions: ["//"],
+				allowFootnoteDefinitions: [],
+			},
+		],
+	},
+
+	create(context) {
+		const allowDefinitions = new Set(context.options[0]?.allowDefinitions);
+		const allowFootnoteDefinitions = new Set(
+			context.options[0]?.allowFootnoteDefinitions,
+		);
+
+		/** @type {Set<string>} Set to track used identifiers */
+		const usedIdentifiers = new Set();
+		/** @type {Set<string>} Set to track used footnote identifiers */
+		const usedFootnoteIdentifiers = new Set();
+		/** @type {Set<Definition>} */
+		const definitions = new Set();
+		/** @type {Set<FootnoteDefinition>} */
+		const footnoteDefinitions = new Set();
+
+		return {
+			imageReference(node) {
+				usedIdentifiers.add(node.identifier);
+			},
+
+			linkReference(node) {
+				usedIdentifiers.add(node.identifier);
+			},
+
+			footnoteReference(node) {
+				usedFootnoteIdentifiers.add(node.identifier);
+			},
+
+			definition(node) {
+				if (allowDefinitions.has(node.identifier)) {
+					return;
+				}
+
+				definitions.add(node);
+			},
+
+			footnoteDefinition(node) {
+				if (allowFootnoteDefinitions.has(node.identifier)) {
+					return;
+				}
+
+				footnoteDefinitions.add(node);
+			},
+
+			"root:exit"() {
+				for (const definition of definitions) {
+					if (!usedIdentifiers.has(definition.identifier)) {
+						context.report({
+							node: definition,
+							messageId: "unusedDefinition",
+							data: { identifier: definition.identifier },
+						});
+					}
+				}
+
+				for (const footnoteDefinition of footnoteDefinitions) {
+					if (
+						!usedFootnoteIdentifiers.has(
+							footnoteDefinition.identifier,
+						)
+					) {
+						context.report({
+							node: footnoteDefinition,
+							messageId: "unusedFootnoteDefinition",
+							data: { identifier: footnoteDefinition.identifier },
+						});
+					}
+				}
+			},
+		};
+	},
+};