eslint-plugin-markdown-preferences 0.4.0 → 0.6.0

package/README.md

@@ -92,8 +92,9 @@ The rules with the following star ⭐ are included in the configs.
 |:--------|:------------|:-------:|:-----------:|
 | [markdown-preferences/hard-linebreak-style](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/hard-linebreak-style.html) | enforce consistent hard linebreak style. | 🔧 | ⭐ |
 | [markdown-preferences/no-text-backslash-linebreak](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/no-text-backslash-linebreak.html) | disallow text backslash at the end of a line. |  | ⭐ |
-| [markdown-preferences/no-trailing-spaces](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/no-trailing-spaces.html) | trailing whitespace at the end of lines in Markdown files. | 🔧 |  |
+| [markdown-preferences/no-trailing-spaces](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/no-trailing-spaces.html) | disallow trailing whitespace at the end of lines in Markdown files. | 🔧 |  |
 | [markdown-preferences/prefer-inline-code-words](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-inline-code-words.html) | enforce the use of inline code for specific words. | 🔧 |  |
+| [markdown-preferences/prefer-link-reference-definitions](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-link-reference-definitions.html) | enforce using link reference definitions instead of inline links | 🔧 |  |
 | [markdown-preferences/prefer-linked-words](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-linked-words.html) | enforce the specified word to be a link. | 🔧 |  |
 
 <!--RULES_TABLE_END-->

package/lib/index.d.ts

@@ -3,7 +3,78 @@ import * as _eslint_core0 from "@eslint/core";
 import { RuleDefinition } from "@eslint/core";
 import { ESLint, Linter } from "eslint";
 
-//#region src/configs/recommended.d.ts
+//#region src/rule-types.d.ts
+declare module 'eslint' {
+  namespace Linter {
+    interface RulesRecord extends RuleOptions {}
+  }
+}
+interface RuleOptions {
+  /**
+   * enforce consistent hard linebreak style.
+   * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/hard-linebreak-style.html
+   */
+  'markdown-preferences/hard-linebreak-style'?: Linter.RuleEntry<MarkdownPreferencesHardLinebreakStyle>;
+  /**
+   * disallow text backslash at the end of a line.
+   * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/no-text-backslash-linebreak.html
+   */
+  'markdown-preferences/no-text-backslash-linebreak'?: Linter.RuleEntry<[]>;
+  /**
+   * disallow trailing whitespace at the end of lines in Markdown files.
+   * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/no-trailing-spaces.html
+   */
+  'markdown-preferences/no-trailing-spaces'?: Linter.RuleEntry<MarkdownPreferencesNoTrailingSpaces>;
+  /**
+   * enforce the use of inline code for specific words.
+   * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-inline-code-words.html
+   */
+  'markdown-preferences/prefer-inline-code-words'?: Linter.RuleEntry<MarkdownPreferencesPreferInlineCodeWords>;
+  /**
+   * enforce using link reference definitions instead of inline links
+   * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-link-reference-definitions.html
+   */
+  'markdown-preferences/prefer-link-reference-definitions'?: Linter.RuleEntry<MarkdownPreferencesPreferLinkReferenceDefinitions>;
+  /**
+   * enforce the specified word to be a link.
+   * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-linked-words.html
+   */
+  'markdown-preferences/prefer-linked-words'?: Linter.RuleEntry<MarkdownPreferencesPreferLinkedWords>;
+}
+type MarkdownPreferencesHardLinebreakStyle = [] | [{
+  style?: ("backslash" | "spaces");
+}];
+type MarkdownPreferencesNoTrailingSpaces = [] | [{
+  skipBlankLines?: boolean;
+  ignoreComments?: boolean;
+}];
+type MarkdownPreferencesPreferInlineCodeWords = [] | [{
+  words: string[];
+  ignores?: {
+    words?: (string | string[]);
+    node?: {
+      [k: string]: unknown | undefined;
+    };
+    [k: string]: unknown | undefined;
+  }[];
+  [k: string]: unknown | undefined;
+}];
+type MarkdownPreferencesPreferLinkReferenceDefinitions = [] | [{
+  minLinks?: number;
+}];
+type MarkdownPreferencesPreferLinkedWords = [] | [{
+  words: ({
+    [k: string]: (string | null);
+  } | string[]);
+  ignores?: {
+    words?: (string | string[]);
+    node?: {
+      [k: string]: unknown | undefined;
+    };
+    [k: string]: unknown | undefined;
+  }[];
+  [k: string]: unknown | undefined;
+}];
 declare namespace recommended_d_exports {
   export { files, language, name$1 as name, plugins, rules$1 as rules };
 }
@@ -19,7 +90,7 @@ declare namespace meta_d_exports {
   export { name, version };
 }
 declare const name: "eslint-plugin-markdown-preferences";
-declare const version: "0.4.0";
+declare const version: "0.6.0";
 //#endregion
 //#region src/index.d.ts
 declare const configs: {
@@ -34,4 +105,4 @@ declare const _default: {
   rules: Record<string, RuleDefinition<_eslint_core0.RuleDefinitionTypeOptions>>;
 };
 //#endregion
-export { configs, _default as default, meta_d_exports as meta, rules };
+export { RuleOptions, configs, _default as default, meta_d_exports as meta, rules };

package/lib/index.js

@@ -131,7 +131,7 @@ var no_trailing_spaces_default = createRule("no-trailing-spaces", {
 	meta: {
 		type: "layout",
 		docs: {
-			description: "trailing whitespace at the end of lines in Markdown files.",
+			description: "disallow trailing whitespace at the end of lines in Markdown files.",
 			categories: []
 		},
 		fixable: "whitespace",
@@ -245,13 +245,14 @@ var no_trailing_spaces_default = createRule("no-trailing-spaces", {
 
 //#endregion
 //#region src/utils/search-words.ts
-const RE_BOUNDARY = /^[\s\p{Letter_Number}\p{Modifier_Letter}\p{Modifier_Symbol}\p{Nonspacing_Mark}\p{Other_Letter}\p{Other_Symbol}\p{Script=Han}!"#$%&'(),./:;<=>?\\{|}~\u{2ffc}-\u{303d}\u{30a0}-\u{30fb}\u{3192}-\u{32bf}\u{fe10}-\u{fe1f}\u{fe30}-\u{fe6f}\u{ff00}-\u{ffef}\u{2ebf0}-\u{2ee5d}]*$/u;
+const RE_BOUNDARY = /^[\s\p{Letter_Number}\p{Modifier_Letter}\p{Modifier_Symbol}\p{Nonspacing_Mark}\p{Other_Letter}\p{Other_Symbol}\p{Script=Han}!"#$%&'()*+,./:;<=>?\\{|}~\u{2ffc}-\u{303d}\u{30a0}-\u{30fb}\u{3192}-\u{32bf}\u{fe10}-\u{fe1f}\u{fe30}-\u{fe6f}\u{ff00}-\u{ffef}\u{2ebf0}-\u{2ee5d}]*$/u;
 /**
 * Iterate through words in a text node that match the specified words.
 */
-function* iterateSearchWords(sourceCode, node, words) {
+function* iterateSearchWords({ sourceCode, node, words, ignores }) {
 	const text = sourceCode.getText(node);
 	for (const word of words) {
+		if (ignores.ignore(word)) continue;
 		let startPosition = 0;
 		while (true) {
 			const index = text.indexOf(word, startPosition);
@@ -280,6 +281,57 @@ function* iterateSearchWords(sourceCode, node, words) {
 		}
 	}
 }
+const IGNORES_SCHEMA = {
+	type: "array",
+	items: {
+		type: "object",
+		properties: {
+			words: { anyOf: [{ type: "string" }, {
+				type: "array",
+				items: { type: "string" }
+			}] },
+			node: { type: "object" }
+		},
+		additionalProperties: true
+	}
+};
+/**
+* Create a context for ignoring specific words or nodes.
+*/
+function createSearchWordsIgnoreContext(ignores) {
+	if (!ignores || ignores.length === 0) return {
+		enter: () => void 0,
+		exit: () => void 0,
+		ignore: () => false
+	};
+	const conditions = ignores.map((ignore) => {
+		const isIgnoreWord = ignore.words == null ? () => true : Array.isArray(ignore.words) ? (word) => ignore.words.includes(word) : (word) => ignore.words === word;
+		const node = ignore.node || {};
+		const keys = Object.keys(node);
+		return {
+			isIgnoreWord,
+			isIgnoreNode: (nodeToCheck) => {
+				return keys.every((key) => nodeToCheck[key] === node[key]);
+			}
+		};
+	});
+	const currentIgnores = /* @__PURE__ */ new Set();
+	return {
+		enter(node) {
+			for (const ignore of conditions) if (ignore.isIgnoreNode(node)) currentIgnores.add({
+				node,
+				condition: ignore
+			});
+		},
+		exit(node) {
+			for (const element of [...currentIgnores]) if (element.node === node) currentIgnores.delete(element);
+		},
+		ignore(word) {
+			for (const { condition } of currentIgnores) if (condition.isIgnoreWord(word)) return true;
+			return false;
+		}
+	};
+}
 
 //#endregion
 //#region src/rules/prefer-inline-code-words.ts
@@ -294,19 +346,30 @@ var prefer_inline_code_words_default = createRule("prefer-inline-code-words", {
 		hasSuggestions: false,
 		schema: [{
 			type: "object",
-			properties: { words: {
-				type: "array",
-				items: { type: "string" }
-			} },
-			required: ["words"]
+			properties: {
+				words: {
+					type: "array",
+					items: { type: "string" }
+				},
+				ignores: IGNORES_SCHEMA
+			},
+			required: ["words"],
+			additionalProperties: true
 		}],
 		messages: { requireInlineCode: "The word \"{{name}}\" should be in inline code." }
 	},
 	create(context) {
 		const sourceCode = context.sourceCode;
 		const words = context.options[0]?.words || [];
+		const ignores = createSearchWordsIgnoreContext(context.options[0]?.ignores);
 		let shortcutLinkReference = null;
 		return {
+			"*"(node) {
+				ignores.enter(node);
+			},
+			"*:exit"(node) {
+				ignores.exit(node);
+			},
 			linkReference(node) {
 				if (node.referenceType !== "shortcut") return;
 				if (shortcutLinkReference) return;
@@ -316,7 +379,12 @@ var prefer_inline_code_words_default = createRule("prefer-inline-code-words", {
 				if (shortcutLinkReference === node) shortcutLinkReference = null;
 			},
 			text(node) {
-				for (const { word, loc, range } of iterateSearchWords(sourceCode, node, words)) {
+				for (const { word, loc, range } of iterateSearchWords({
+					sourceCode,
+					node,
+					words,
+					ignores
+				})) {
 					const shortcutLinkReferenceToReport = shortcutLinkReference;
 					context.report({
 						node,
@@ -335,6 +403,140 @@ var prefer_inline_code_words_default = createRule("prefer-inline-code-words", {
 	}
 });
 
+//#endregion
+//#region src/rules/prefer-link-reference-definitions.ts
+var prefer_link_reference_definitions_default = createRule("prefer-link-reference-definitions", {
+	meta: {
+		type: "layout",
+		docs: {
+			description: "enforce using link reference definitions instead of inline links",
+			categories: []
+		},
+		fixable: "code",
+		hasSuggestions: false,
+		schema: [{
+			type: "object",
+			properties: { minLinks: {
+				type: "number",
+				description: "minimum number of links to trigger the rule (default: 2)",
+				default: 2,
+				minimum: 1
+			} },
+			additionalProperties: false
+		}],
+		messages: { useLinkReferenceDefinitions: "Use link reference definitions instead of inline links." }
+	},
+	create(context) {
+		const sourceCode = context.sourceCode;
+		const options = context.options[0] || {};
+		const minLinks = options.minLinks ?? 2;
+		const definitions = [];
+		const links = [];
+		const linkReferences = [];
+		/**
+		* Verify links.
+		*/
+		function verify() {
+			const resourceToNodes = /* @__PURE__ */ new Map();
+			for (const link of links) getResourceNodes(link).links.push(link);
+			for (const linkReference of linkReferences) {
+				const definition = definitions.find((def) => def.identifier === linkReference.identifier);
+				if (definition) getResourceNodes(definition).linkReferences.push(linkReference);
+			}
+			for (const definition of definitions) getResourceNodes(definition).definitions.push(definition);
+			for (const map of resourceToNodes.values()) for (const nodes of map.values()) {
+				if (nodes.links.length === 0 || nodes.links.length + nodes.linkReferences.length < minLinks) continue;
+				for (const link of nodes.links) {
+					const linkInfo = getLinkInfo(link);
+					if (linkInfo.label === "") continue;
+					context.report({
+						node: link,
+						messageId: "useLinkReferenceDefinitions",
+						*fix(fixer) {
+							const definition = nodes.definitions[0];
+							let identifier;
+							if (definition) identifier = definition.label ?? definition.identifier;
+							else identifier = linkInfo.label.replaceAll(/\]/g, "-");
+							yield fixer.replaceText(link, `${sourceCode.text.slice(...linkInfo.labelRange)}${identifier === linkInfo.label ? "" : `[${identifier}]`}`);
+							if (!definition) {
+								const linkRange = sourceCode.getRange(link);
+								const reLineBreaks = /\n#{1,6}\s/gu;
+								reLineBreaks.lastIndex = linkRange[1];
+								const nextSectionMatch = reLineBreaks.exec(sourceCode.text);
+								const insertIndex = !nextSectionMatch ? sourceCode.text.trimEnd().length : nextSectionMatch.index;
+								yield fixer.insertTextAfterRange([insertIndex, insertIndex], `${sourceCode.text[insertIndex - 1] === "\n" ? "" : "\n"}\n[${identifier}]: ${sourceCode.text.slice(linkInfo.urlAndTitleRange[0] + 1, linkInfo.urlAndTitleRange[1] - 1).trim()}${nextSectionMatch ? "\n" : ""}`);
+							}
+						}
+					});
+				}
+			}
+			/**
+			* Get the resource nodes for a link or definition.
+			*/
+			function getResourceNodes(resource) {
+				const url = resource.url;
+				const title = resource.title ?? null;
+				let map = resourceToNodes.get(url);
+				if (!map) {
+					map = /* @__PURE__ */ new Map();
+					resourceToNodes.set(url, map);
+				}
+				let nodes = map.get(title);
+				if (!nodes) {
+					nodes = {
+						links: [],
+						linkReferences: [],
+						definitions: []
+					};
+					map.set(title, nodes);
+				}
+				return nodes;
+			}
+		}
+		return {
+			link(node) {
+				links.push(node);
+			},
+			linkReference(node) {
+				linkReferences.push(node);
+			},
+			definition(node) {
+				definitions.push(node);
+			},
+			"root:exit"() {
+				verify();
+			}
+		};
+		/**
+		* Get the range of the link label.
+		*/
+		function getLinkInfo(link) {
+			const range = sourceCode.getRange(link);
+			const linkLabelRange = getLinkLabelRange();
+			const linkLabelWithBracketsText = sourceCode.text.slice(...linkLabelRange);
+			const linkLabelText = linkLabelWithBracketsText.slice(1, -1).trim();
+			const urlStartIndex = sourceCode.text.indexOf("(", linkLabelRange[1]);
+			return {
+				label: linkLabelText,
+				labelRange: linkLabelRange,
+				urlAndTitleRange: [urlStartIndex, range[1]]
+			};
+			/**
+			* Get the range of the link label.
+			*/
+			function getLinkLabelRange() {
+				if (link.children.length === 0) {
+					const index$1 = sourceCode.text.indexOf("]", range[0] + 1);
+					return [range[0], index$1 + 1];
+				}
+				const lastRange = sourceCode.getRange(link.children[link.children.length - 1]);
+				const index = sourceCode.text.indexOf("]", lastRange[0] + 1);
+				return [range[0], index + 1];
+			}
+		}
+	}
+});
+
 //#endregion
 //#region src/rules/prefer-linked-words.ts
 var prefer_linked_words_default = createRule("prefer-linked-words", {
@@ -348,20 +550,25 @@ var prefer_linked_words_default = createRule("prefer-linked-words", {
 		hasSuggestions: false,
 		schema: [{
 			type: "object",
-			properties: { words: { anyOf: [{
-				type: "object",
-				patternProperties: { "^[\\s\\S]+$": { type: ["string", "null"] } }
-			}, {
-				type: "array",
-				items: { type: "string" }
-			}] } },
-			required: ["words"]
+			properties: {
+				words: { anyOf: [{
+					type: "object",
+					patternProperties: { "^[\\s\\S]+$": { type: ["string", "null"] } }
+				}, {
+					type: "array",
+					items: { type: "string" }
+				}] },
+				ignores: IGNORES_SCHEMA
+			},
+			required: ["words"],
+			additionalProperties: true
 		}],
 		messages: { requireLink: "The word \"{{name}}\" should be a link." }
 	},
 	create(context) {
 		const sourceCode = context.sourceCode;
 		const wordsOption = context.options[0]?.words || {};
+		const ignores = createSearchWordsIgnoreContext(context.options[0]?.ignores);
 		const links = Object.create(null);
 		const words = [];
 		if (Array.isArray(wordsOption)) words.push(...wordsOption);
@@ -373,18 +580,29 @@ var prefer_linked_words_default = createRule("prefer-linked-words", {
 			}
 			words.push(word);
 		}
-		let ignore = null;
+		let linkedNode = null;
 		return {
-			"link, linkReference, heading, footnoteDefinition"(node) {
-				if (ignore) return;
-				ignore = node;
+			"*"(node) {
+				ignores.enter(node);
 			},
-			"link, linkReference, heading, footnoteDefinition:exit"(node) {
-				if (ignore === node) ignore = null;
+			"*:exit"(node) {
+				ignores.exit(node);
+			},
+			"link, linkReference"(node) {
+				if (linkedNode) return;
+				linkedNode = node;
+			},
+			"link, linkReference:exit"(node) {
+				if (linkedNode === node) linkedNode = null;
 			},
 			text(node) {
-				if (ignore) return;
-				for (const { word, loc, range } of iterateSearchWords(sourceCode, node, words)) {
+				if (linkedNode) return;
+				for (const { word, loc, range } of iterateSearchWords({
+					sourceCode,
+					node,
+					words,
+					ignores
+				})) {
 					const link = links[word];
 					context.report({
 						node,
@@ -398,17 +616,20 @@ var prefer_linked_words_default = createRule("prefer-linked-words", {
 				}
 			},
 			inlineCode(node) {
-				if (ignore) return;
-				for (const word of words) if (node.value === word) {
-					const link = links[word];
-					context.report({
-						node,
-						messageId: "requireLink",
-						data: { name: word },
-						fix: link ? (fixer) => {
-							return fixer.replaceText(node, `[\`${word}\`](${link})`);
-						} : null
-					});
+				if (linkedNode) return;
+				for (const word of words) {
+					if (ignores.ignore(word)) continue;
+					if (node.value === word) {
+						const link = links[word];
+						context.report({
+							node,
+							messageId: "requireLink",
+							data: { name: word },
+							fix: link ? (fixer) => {
+								return fixer.replaceText(node, `[\`${word}\`](${link})`);
+							} : null
+						});
+					}
 				}
 			}
 		};
@@ -431,6 +652,7 @@ const rules$1 = [
 	no_text_backslash_linebreak_default,
 	no_trailing_spaces_default,
 	prefer_inline_code_words_default,
+	prefer_link_reference_definitions_default,
 	prefer_linked_words_default
 ];
 
@@ -466,7 +688,7 @@ __export(meta_exports, {
 	version: () => version
 });
 const name = "eslint-plugin-markdown-preferences";
-const version = "0.4.0";
+const version = "0.6.0";
 
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-markdown-preferences",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "ESLint plugin that enforces our markdown preferences",
   "type": "module",
   "exports": {
@@ -71,6 +71,7 @@
     "@types/eslint-utils": "^3.0.5",
     "@types/estree": "^1.0.6",
     "@types/json-schema": "^7.0.15",
+    "@types/mdast": "^4.0.4",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.13.10",
     "@types/semver": "^7.5.8",