Merge branch 'main' into frontmatterTitle

Author: xbinaryx

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -35,7 +35,7 @@ body:
       attributes:
           label: What did you do?
           description: |
-              Please include a *minimal* reproduction case.
+              Please include a *minimal* reproduction case. Use this [StackBlitz template](https://stackblitz.com/edit/stackblitz-starters-jqcrssas?file=eslint.config.js) as a starting point.
           value: |
               <details>
               <summary>Configuration</summary>

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 -->
@@ -257,7 +258,7 @@ to get your logo on our READMEs and [website](https://eslint.org/sponsors).
 <p><a href="https://automattic.com"><img src="https://images.opencollective.com/automattic/d0ef3e1/logo.png" alt="Automattic" height="128"></a> <a href="https://www.airbnb.com/"><img src="https://images.opencollective.com/airbnb/d327d66/logo.png" alt="Airbnb" height="128"></a></p><h3>Gold Sponsors</h3>
 <p><a href="https://qlty.sh/"><img src="https://images.opencollective.com/qltysh/33d157d/logo.png" alt="Qlty Software" height="96"></a> <a href="https://trunk.io/"><img src="https://images.opencollective.com/trunkio/fb92d60/avatar.png" alt="trunk.io" height="96"></a> <a href="https://shopify.engineering/"><img src="https://avatars.githubusercontent.com/u/8085" alt="Shopify" height="96"></a></p><h3>Silver Sponsors</h3>
 <p><a href="https://vite.dev/"><img src="https://images.opencollective.com/vite/e6d15e1/logo.png" alt="Vite" height="64"></a> <a href="https://liftoff.io/"><img src="https://images.opencollective.com/liftoff/5c4fa84/logo.png" alt="Liftoff" height="64"></a> <a href="https://americanexpress.io"><img src="https://avatars.githubusercontent.com/u/3853301" alt="American Express" height="64"></a> <a href="https://stackblitz.com"><img src="https://avatars.githubusercontent.com/u/28635252" alt="StackBlitz" height="64"></a></p><h3>Bronze Sponsors</h3>
-<p><a href="https://sentry.io"><img src="https://github.com/getsentry.png" alt="Sentry" height="32"></a> <a href="https://syntax.fm"><img src="https://github.com/syntaxfm.png" alt="Syntax" height="32"></a> <a href="https://cybozu.co.jp/"><img src="https://images.opencollective.com/cybozu/933e46d/logo.png" alt="Cybozu" height="32"></a> <a href="https://www.crosswordsolver.org/anagram-solver/"><img src="https://images.opencollective.com/anagram-solver/2666271/logo.png" alt="Anagram Solver" height="32"></a> <a href="https://icons8.com/"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://www.gitbook.com"><img src="https://avatars.githubusercontent.com/u/7111340" alt="GitBook" height="32"></a> <a href="https://nolebase.ayaka.io"><img src="https://avatars.githubusercontent.com/u/11081491" alt="Neko" height="32"></a> <a href="https://nx.dev"><img src="https://avatars.githubusercontent.com/u/23692104" alt="Nx" height="32"></a> <a href="https://opensource.mercedes-benz.com/"><img src="https://avatars.githubusercontent.com/u/34240465" alt="Mercedes-Benz Group" height="32"></a> <a href="https://herocoders.com"><img src="https://avatars.githubusercontent.com/u/37549774" alt="HeroCoders" height="32"></a> <a href="https://www.lambdatest.com"><img src="https://avatars.githubusercontent.com/u/171592363" alt="LambdaTest" height="32"></a></p>
+<p><a href="https://cybozu.co.jp/"><img src="https://images.opencollective.com/cybozu/933e46d/logo.png" alt="Cybozu" height="32"></a> <a href="https://icons8.com/"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://www.gitbook.com"><img src="https://avatars.githubusercontent.com/u/7111340" alt="GitBook" height="32"></a> <a href="https://nx.dev"><img src="https://avatars.githubusercontent.com/u/23692104" alt="Nx" height="32"></a> <a href="https://opensource.mercedes-benz.com/"><img src="https://avatars.githubusercontent.com/u/34240465" alt="Mercedes-Benz Group" height="32"></a> <a href="https://herocoders.com"><img src="https://avatars.githubusercontent.com/u/37549774" alt="HeroCoders" height="32"></a> <a href="https://www.lambdatest.com"><img src="https://avatars.githubusercontent.com/u/171592363" alt="LambdaTest" height="32"></a></p>
 <h3>Technology Sponsors</h3>
 Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.
 <p><a href="https://netlify.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/netlify-icon.svg" alt="Netlify" height="32"></a> <a href="https://algolia.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/algolia-icon.svg" alt="Algolia" height="32"></a> <a href="https://1password.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/1password-icon.svg" alt="1Password" height="32"></a></p>

docs/rules/no-empty-definitions.md

@@ -4,19 +4,27 @@ Disallow empty definitions.
 
 ## Background
 
-Markdown allows you to specify a label as a placeholder for a URL in both links and images using square brackets, such as:
+Markdown allows you to specify a label as a placeholder for a URL in both links and images, or as a footnote reference, using square brackets. For example:
 
 ```markdown
 [ESLint][eslint]
 
 [eslint]: https://eslint.org
+
+[ESLint][^eslint]
+
+[^eslint]: Find and fix problmes in your JavaScript code
 ```
 
-If the definition's URL is empty or only contains an empty fragment (`#`), then it's not providing any useful information and could be a mistake.
+Definitions with an empty URL or only an empty fragment (`#`), as well as footnote definitions with no content, are usually mistakes and do not provide useful information.
 
 ## Rule Details
 
-This rule warns when it finds definitions where the URL is either not specified or contains only an empty fragment (`#`).
+> [!IMPORTANT] <!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+>
+> Footnotes are only supported when using `language` mode [`markdown/gfm`](/README.md#languages).
+
+This rule warns when it finds definitions where the URL is either not specified or contains only an empty fragment (`#`). It also warns for empty footnote definitions by default.
 
 Examples of **incorrect** code for this rule:
 
@@ -25,15 +33,31 @@ Examples of **incorrect** code for this rule:
 
 [earth]: <>
 [moon]: #
+[^note]:
 ```
 
-Examples of correct code:
+Examples of **correct** code for this rule:
 
 ```markdown
 <!-- eslint markdown/no-empty-definitions: "error" -->
 
 [earth]: https://example.com/earth/
 [moon]: #section
+[^note]: This is a footnote.
+```
+
+## Options
+
+The following options are available on this rule:
+
+* `checkFootnoteDefinitions: boolean` - When set to `false`, the rule will not report empty footnote definitions. (default: `true`).
+
+Examples of **correct** code for this rule with `checkFootnoteDefinitions: false`:
+
+```markdown
+<!-- eslint markdown/no-empty-definitions: ["error", { checkFootnoteDefinitions: false }] -->
+
+[^note]:
 ```
 
 ## When Not to Use It

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

@@ -55,6 +55,10 @@ Examples of **correct** code for this rule:
 
 [Link](#L2)
 
+# café
+
+[Link to café](#caf%C3%A9)
+
 # <span class="icon-star"></span> Starred Projects
 
 [Link to starred projects](#-starred-projects)

docs/rules/no-unused-definitions.md

@@ -0,0 +1,103 @@
+# 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 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/index.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Enables the processor for Markdown file extensions.
+ * @fileoverview Markdown plugin.
  * @author Brandon Mills
  */
 
@@ -17,16 +17,19 @@ import rules from "./build/rules.js";
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("eslint").Linter.RulesRecord} RulesRecord*/
-/** @typedef {import("eslint").Linter.Config} Config*/
-/** @typedef {import("eslint").ESLint.Plugin} Plugin */
 /**
- * @typedef {import("./types.ts").MarkdownRuleDefinition<Options>} MarkdownRuleDefinition<Options>
- * @template {Partial<import("./types.ts").MarkdownRuleDefinitionTypeOptions>} [Options={}]
+ * @import { Linter } from "eslint";
+ * @import * as Types from "./types.js";
+ * @typedef {Linter.RulesRecord} RulesRecord
+ * @typedef {Types.MarkdownRuleDefinition} RuleModule
+ * @typedef {Types.MarkdownRuleVisitor} MarkdownRuleVisitor
+ * @typedef {Types.MarkdownRuleDefinitionTypeOptions} MarkdownRuleDefinitionTypeOptions
+ */
+
+/**
+ * @typedef {Types.MarkdownRuleDefinition<Options>} MarkdownRuleDefinition<Options>
+ * @template {Partial<MarkdownRuleDefinitionTypeOptions>} [Options={}]
  */
-/** @typedef {MarkdownRuleDefinition} RuleModule */
-/** @typedef {import("./types.ts").MarkdownRuleVisitor} MarkdownRuleVisitor */
-/** @typedef {import("@eslint/core").Language} Language */
 
 //-----------------------------------------------------------------------------
 // Exports

src/language/markdown-language.js

@@ -20,16 +20,15 @@ import { gfm } from "micromark-extension-gfm";
 // Types
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("mdast").Root} RootNode */
-/** @typedef {import("mdast-util-from-markdown").Options['extensions']} Extensions */
-/** @typedef {import("mdast-util-from-markdown").Options['mdastExtensions']} MdastExtensions */
-/** @typedef {import("@eslint/core").Language} Language */
-/** @typedef {import("@eslint/core").File} File */
-/** @typedef {import("@eslint/core").ParseResult<RootNode>} ParseResult */
-/** @typedef {import("@eslint/core").OkParseResult<RootNode>} OkParseResult */
-/** @typedef {import("../types.ts").MarkdownLanguageOptions} MarkdownLanguageOptions */
-/** @typedef {import("../types.ts").MarkdownLanguageContext} MarkdownLanguageContext */
-/** @typedef {"commonmark"|"gfm"} ParserMode */
+/**
+ * @import { Language, File, ParseResult, OkParseResult } from "@eslint/core";
+ * @import { Root } from "mdast";
+ * @import { Options } from "mdast-util-from-markdown";
+ * @import { MarkdownLanguageOptions, MarkdownLanguageContext } from "../types.js";
+ * @typedef {Options['extensions']} Extensions
+ * @typedef {Options['mdastExtensions']} MdastExtensions
+ * @typedef {"commonmark"|"gfm"} ParserMode
+ */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -182,7 +181,7 @@ export class MarkdownLanguage {
 	 * Parses the given file into an AST.
 	 * @param {File} file The virtual file to parse.
 	 * @param {MarkdownLanguageContext} context The options to use for parsing.
-	 * @returns {ParseResult} The result of parsing.
+	 * @returns {ParseResult<Root>} The result of parsing.
 	 */
 	parse(file, context) {
 		// Note: BOM already removed
@@ -216,7 +215,7 @@ export class MarkdownLanguage {
 	/**
 	 * Creates a new `MarkdownSourceCode` object from the given information.
 	 * @param {File} file The virtual file to create a `MarkdownSourceCode` object from.
-	 * @param {OkParseResult} parseResult The result returned from `parse()`.
+	 * @param {OkParseResult<Root>} parseResult The result returned from `parse()`.
 	 * @returns {MarkdownSourceCode} The new `MarkdownSourceCode` object.
 	 */
 	createSourceCode(file, parseResult) {

src/language/markdown-source-code.js

@@ -19,20 +19,11 @@ import { findOffsets } from "../util.js";
 // Types
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("mdast").Root} RootNode */
-/** @typedef {import("mdast").Node} MarkdownNode */
-/** @typedef {import("mdast").Html} HTMLNode */
-/** @typedef {import("@eslint/core").Language} Language */
-/** @typedef {import("@eslint/core").File} File */
-/** @typedef {import("@eslint/core").TraversalStep} TraversalStep */
-/** @typedef {import("@eslint/core").VisitTraversalStep} VisitTraversalStep */
-/** @typedef {import("@eslint/core").ParseResult<RootNode>} ParseResult */
-/** @typedef {import("@eslint/core").SourceLocation} SourceLocation */
-/** @typedef {import("@eslint/core").SourceRange} SourceRange */
-/** @typedef {import("@eslint/core").FileProblem} FileProblem */
-/** @typedef {import("@eslint/core").DirectiveType} DirectiveType */
-/** @typedef {import("@eslint/core").RulesConfig} RulesConfig */
-/** @typedef {import("../types.ts").MarkdownLanguageOptions} MarkdownLanguageOptions */
+/**
+ * @import { Root, Node, Html } from "mdast";
+ * @import { TraversalStep, SourceLocation, FileProblem, DirectiveType, RulesConfig } from "@eslint/core";
+ * @import { MarkdownLanguageOptions } from "../types.js";
+ */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -73,7 +64,7 @@ class InlineConfigComment {
 
 /**
  * Extracts inline configuration comments from an HTML node.
- * @param {HTMLNode} node The HTML node to extract comments from.
+ * @param {Html} node The HTML node to extract comments from.
  * @returns {Array<InlineConfigComment>} The inline configuration comments found in the node.
  */
 function extractInlineConfigCommentsFromHTML(node) {
@@ -136,7 +127,7 @@ function extractInlineConfigCommentsFromHTML(node) {
 
 /**
  * Markdown Source Code Object
- * @extends {TextSourceCodeBase<{LangOptions: MarkdownLanguageOptions, RootNode: RootNode, SyntaxElementWithLoc: MarkdownNode, ConfigNode: { value: string; position: SourceLocation }}>}
+ * @extends {TextSourceCodeBase<{LangOptions: MarkdownLanguageOptions, RootNode: Root, SyntaxElementWithLoc: Node, ConfigNode: { value: string; position: SourceLocation }}>}
  */
 export class MarkdownSourceCode extends TextSourceCodeBase {
 	/**
@@ -147,13 +138,13 @@ export class MarkdownSourceCode extends TextSourceCodeBase {
 
 	/**
 	 * Cache of parent nodes.
-	 * @type {WeakMap<MarkdownNode, MarkdownNode>}
+	 * @type {WeakMap<Node, Node>}
 	 */
 	#parents = new WeakMap();
 
 	/**
 	 * Collection of HTML nodes. Used to find directive comments.
-	 * @type {Array<HTMLNode>}
+	 * @type {Array<Html>}
 	 */
 	#htmlNodes = [];
 
@@ -165,15 +156,15 @@ export class MarkdownSourceCode extends TextSourceCodeBase {
 
 	/**
 	 * The AST of the source code.
-	 * @type {RootNode}
+	 * @type {Root}
 	 */
 	ast = undefined;
 
 	/**
 	 * Creates a new instance.
 	 * @param {Object} options The options for the instance.
 	 * @param {string} options.text The source code text.
-	 * @param {RootNode} options.ast The root AST node.
+	 * @param {Root} options.ast The root AST node.
 	 */
 	constructor({ text, ast }) {
 		super({ ast, text });
@@ -185,8 +176,8 @@ export class MarkdownSourceCode extends TextSourceCodeBase {
 
 	/**
 	 * Returns the parent of the given node.
-	 * @param {MarkdownNode} node The node to get the parent of.
-	 * @returns {MarkdownNode|undefined} The parent of the node.
+	 * @param {Node} node The node to get the parent of.
+	 * @returns {Node|undefined} The parent of the node.
 	 */
 	getParent(node) {
 		return this.#parents.get(node);