feat: add no-bare-urls rule (#418)

* feat: add no-bare-urls rule

* docs: add more examples

* code review

Author: xbinaryx

README.md

@@ -89,6 +89,7 @@ export default defineConfig([
 | :- | :- | :-: |
 | [`fenced-code-language`](./docs/rules/fenced-code-language.md) | Require languages for fenced code blocks | yes |
 | [`heading-increment`](./docs/rules/heading-increment.md) | Enforce heading levels increment by one | yes |
+| [`no-bare-urls`](./docs/rules/no-bare-urls.md) | Disallow bare URLs | no |
 | [`no-duplicate-definitions`](./docs/rules/no-duplicate-definitions.md) | Disallow duplicate definitions | yes |
 | [`no-duplicate-headings`](./docs/rules/no-duplicate-headings.md) | Disallow duplicate headings in the same document | no |
 | [`no-empty-definitions`](./docs/rules/no-empty-definitions.md) | Disallow empty definitions | yes |

docs/rules/no-bare-urls.md

@@ -0,0 +1,67 @@
+# no-bare-urls
+
+Disallow bare URLs.
+
+## Background
+
+In Markdown, URLs are typically formatted in two ways:
+
+1. Autolinks: URLs wrapped in angle brackets, such as `<https://example.com/>`
+2. Links: URLs with descriptive text, such as `[Visit our website](https://example.com/)`
+
+A bare URL appears without angle brackets (`<>`), such as `https://example.com/`. While GitHub Flavored Markdown (GFM) allows bare URLs to be recognized as clickable links, this feature is not supported in all Markdown processors. To ensure compatibility across different processors, use autolinks or links instead.
+
+## Rule Details
+
+> [!IMPORTANT] <!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+>
+> This rule requires `language: "markdown/gfm"`.
+
+This rule flags bare URLs that should be formatted as autolinks or links.
+
+Examples of **incorrect** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-bare-urls: "error" -->
+
+For more info, visit https://www.example.com/
+
+Contact us at [email protected]
+
+# https://www.example.com/
+
+[Read the [docs]](https://www.example.com/)
+
+[docs]: https://www.example.com/docs
+```
+
+Examples of **correct** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-bare-urls: "error" -->
+
+For more info, visit <https://www.example.com/>
+
+For more info, visit [Example Website](https://www.example.com/)
+
+Contact us at <[email protected]>
+
+Contact us at [[email protected]](mailto:[email protected])
+
+# <https://www.example.com/>
+
+Not a clickable link: `https://www.example.com/`
+
+[https://www.example.com/]
+
+[Read the \[docs\]](https://www.example.com/)
+```
+
+## When Not to Use It
+
+If you're working in an environment where GFM autolink literals are fully supported and you prefer their simplicity, you can safely disable this rule.
+
+## Prior Art
+
+* [remark-lint-no-literal-urls](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls)
+* [MD034 - Bare URL used](https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md)

src/rules/no-bare-urls.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Rule to prevent bare URLs in Markdown.
+ * @author xbinaryx
+ */
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/** @typedef {import("mdast").Node} Node */
+/** @typedef {import("mdast").Paragraph} ParagraphNode */
+/** @typedef {import("mdast").Heading} HeadingNode */
+/** @typedef {import("mdast").TableCell} TableCellNode */
+/** @typedef {import("mdast").Link} LinkNode */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * NoBareUrlsRuleDefinition
+ */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+const htmlTagNamePattern = /^<([^!>][^/\s>]*)/u;
+
+/**
+ * Parses an HTML tag to extract its name and closing status
+ * @param {string} tagText The HTML tag text to parse
+ * @returns {{ name: string; isClosing: boolean; } | null} Object containing tag name and closing status, or null if not a valid tag
+ */
+function parseHtmlTag(tagText) {
+	const match = tagText.match(htmlTagNamePattern);
+	if (match) {
+		const tagName = match[1].toLowerCase();
+		const isClosing = tagName.startsWith("/");
+
+		return {
+			name: isClosing ? tagName.slice(1) : tagName,
+			isClosing,
+		};
+	}
+
+	return null;
+}
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+/** @type {NoBareUrlsRuleDefinition} */
+export default {
+	meta: {
+		type: "problem",
+
+		docs: {
+			description: "Disallow bare URLs",
+			url: "https://github.com/eslint/markdown/blob/main/docs/rules/no-bare-urls.md",
+		},
+
+		fixable: "code",
+
+		messages: {
+			bareUrl:
+				"Unexpected bare URL. Use autolink (<URL>) or link ([text](URL)) instead.",
+		},
+	},
+
+	create(context) {
+		const { sourceCode } = context;
+		/** @type {Array<LinkNode>} */
+		const bareUrls = [];
+
+		/**
+		 * Finds bare URLs in markdown nodes while handling HTML tags.
+		 * When an HTML tag is found, it looks for its closing tag and skips all nodes
+		 * between them to prevent checking for bare URLs inside HTML content.
+		 * @param {ParagraphNode|HeadingNode|TableCellNode} node The node to process
+		 * @returns {void}
+		 */
+		function findBareUrls(node) {
+			/**
+			 * Recursively traverses the AST to find bare URLs, skipping over HTML blocks.
+			 * @param {Node} currentNode The current AST node being traversed.
+			 * @returns {void}
+			 */
+			function traverse(currentNode) {
+				if (
+					"children" in currentNode &&
+					Array.isArray(currentNode.children)
+				) {
+					for (let i = 0; i < currentNode.children.length; i++) {
+						const child = currentNode.children[i];
+
+						if (child.type === "html") {
+							const tagInfo = parseHtmlTag(
+								sourceCode.getText(child),
+							);
+
+							if (tagInfo && !tagInfo.isClosing) {
+								for (
+									let j = i + 1;
+									j < currentNode.children.length;
+									j++
+								) {
+									const nextChild = currentNode.children[j];
+									if (nextChild.type === "html") {
+										const closingTagInfo = parseHtmlTag(
+											sourceCode.getText(nextChild),
+										);
+										if (
+											closingTagInfo?.name ===
+												tagInfo.name &&
+											closingTagInfo?.isClosing
+										) {
+											i = j;
+											break;
+										}
+									}
+								}
+								continue;
+							}
+						}
+
+						if (child.type === "link") {
+							const text = sourceCode.getText(child);
+							const { url } = child;
+
+							if (
+								text === url ||
+								url === `http://${text}` ||
+								url === `mailto:${text}`
+							) {
+								bareUrls.push(child);
+							}
+						}
+
+						traverse(child);
+					}
+				}
+			}
+
+			traverse(node);
+		}
+
+		return {
+			"root:exit"() {
+				for (const bareUrl of bareUrls) {
+					context.report({
+						node: bareUrl,
+						messageId: "bareUrl",
+						fix(fixer) {
+							const text = sourceCode.getText(bareUrl);
+							return fixer.replaceText(bareUrl, `<${text}>`);
+						},
+					});
+				}
+			},
+
+			paragraph(node) {
+				findBareUrls(node);
+			},
+
+			heading(node) {
+				findBareUrls(node);
+			},
+
+			tableCell(node) {
+				findBareUrls(node);
+			},
+		};
+	},
+};