feat: add no-reversed-media-syntax rule (#398)

* feat: add no-reversed-media-syntax rule

* cleanup tests

* code review

* code review

* simplify error message

* code review

* code review

Author: xbinaryx

README.md

@@ -101,6 +101,7 @@ export default defineConfig([
 | [`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 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 |
 | [`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-reversed-media-syntax.md

@@ -0,0 +1,40 @@
+# no-reversed-media-syntax
+
+Disallow reversed link and image syntax in Markdown.
+
+## Background
+
+Markdown syntax for links requires the text to be in square brackets `[]` followed by the URL in parentheses `()`. Similarly, images use `![alt](url)`. It's easy to accidentally reverse these brackets, which results in invalid syntax that won't render correctly.
+
+## Rule Details
+
+This rule is triggered when text that appears to be a link or image is encountered, but the syntax seems to have been reversed (the `[]` and `()` are in the wrong order).
+
+Examples of **incorrect** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-reversed-media-syntax: "error" -->
+
+(ESLint)[https://eslint.org/]
+
+!(A beautiful sunset)[sunset.png]
+```
+
+Examples of **correct** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-reversed-media-syntax: "error" -->
+
+[ESLint](https://eslint.org/)
+
+![A beautiful sunset](sunset.png)
+```
+
+## When Not To Use It
+
+If you don't need to enforce correct link and image syntax, you can safely disable this rule.
+
+## Prior Art
+
+* [MD011 - no-reversed-links](https://github.com/DavidAnson/markdownlint/blob/main/doc/md011.md)
+* [remark-lint-correct-media-syntax](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-correct-media-syntax)

src/rules/no-reversed-media-syntax.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Rule to prevent reversed link and image syntax in Markdown.
+ * @author xbinaryx
+ */
+
+//-----------------------------------------------------------------------------
+// Imports
+//-----------------------------------------------------------------------------
+
+import { findOffsets } from "../util.js";
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/** @typedef {import("mdast").Node} Node */
+/** @typedef {import("mdast").Paragraph} ParagraphNode */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * NoReversedMediaSyntaxRuleDefinition
+ */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+/** Matches reversed link/image syntax like (text)[url], ignoring escaped characters like \(text\)[url]. */
+const reversedPattern =
+	/(?<!\\)\(((?:\\.|[^()\\]|\([\s\S]*\))*)\)\[((?:\\.|[^\]\\\n])*)\](?!\()/gu;
+
+/**
+ * Checks if a match is within any of the code spans
+ * @param {number} matchIndex The index of the match
+ * @param {Array<{startOffset: number, endOffset: number}>} codeSpans Array of code span positions
+ * @returns {boolean} True if the match is within a code span
+ */
+function isInCodeSpan(matchIndex, codeSpans) {
+	return codeSpans.some(
+		span => matchIndex >= span.startOffset && matchIndex < span.endOffset,
+	);
+}
+
+/**
+ * Finds all code spans in the paragraph node by traversing its children
+ * @param {ParagraphNode} node The paragraph node to search
+ * @returns {Array<{startOffset: number, endOffset: number}>} Array of code span positions
+ */
+function findCodeSpans(node) {
+	const codeSpans = [];
+
+	/**
+	 * Recursively traverses the AST to find inline code nodes
+	 * @param {Node} currentNode The current node being traversed
+	 * @returns {void}
+	 */
+	function traverse(currentNode) {
+		if (currentNode.type === "inlineCode") {
+			codeSpans.push({
+				startOffset: currentNode.position.start.offset,
+				endOffset: currentNode.position.end.offset,
+			});
+			return;
+		}
+
+		if ("children" in currentNode && Array.isArray(currentNode.children)) {
+			currentNode.children.forEach(traverse);
+		}
+	}
+
+	traverse(node);
+	return codeSpans;
+}
+
+//-----------------------------------------------------------------------------
+// Rule Definition
+//-----------------------------------------------------------------------------
+
+/** @type {NoReversedMediaSyntaxRuleDefinition} */
+export default {
+	meta: {
+		type: "problem",
+
+		docs: {
+			recommended: true,
+			description: "Disallow reversed link and image syntax",
+			url: "https://github.com/eslint/markdown/blob/main/docs/rules/no-reversed-media-syntax.md",
+		},
+
+		fixable: "code",
+
+		messages: {
+			reversedSyntax:
+				"Unexpected reversed syntax found. Use [label](URL) syntax instead.",
+		},
+	},
+
+	create(context) {
+		return {
+			paragraph(node) {
+				const text = context.sourceCode.getText(node);
+				const codeSpans = findCodeSpans(node);
+				let match;
+
+				while ((match = reversedPattern.exec(text)) !== null) {
+					const [reversedSyntax, label, url] = match;
+					const matchIndex = match.index;
+					const matchLength = reversedSyntax.length;
+
+					if (isInCodeSpan(matchIndex, codeSpans)) {
+						continue;
+					}
+
+					const {
+						lineOffset: startLineOffset,
+						columnOffset: startColumnOffset,
+					} = findOffsets(text, matchIndex);
+					const {
+						lineOffset: endLineOffset,
+						columnOffset: endColumnOffset,
+					} = findOffsets(text, matchIndex + matchLength);
+
+					const baseColumn = 1;
+					const nodeStartLine = node.position.start.line;
+					const nodeStartColumn = node.position.start.column;
+					const startLine = nodeStartLine + startLineOffset;
+					const endLine = nodeStartLine + endLineOffset;
+					const startColumn =
+						(startLine === nodeStartLine
+							? nodeStartColumn
+							: baseColumn) + startColumnOffset;
+					const endColumn =
+						(endLine === nodeStartLine
+							? nodeStartColumn
+							: baseColumn) + endColumnOffset;
+
+					context.report({
+						loc: {
+							start: {
+								line: startLine,
+								column: startColumn,
+							},
+							end: {
+								line: endLine,
+								column: endColumn,
+							},
+						},
+						messageId: "reversedSyntax",
+						fix(fixer) {
+							const startOffset =
+								node.position.start.offset + matchIndex;
+							const endOffset = startOffset + matchLength;
+
+							return fixer.replaceTextRange(
+								[startOffset, endOffset],
+								`[${label}](${url})`,
+							);
+						},
+					});
+				}
+			},
+		};
+	},
+};