feat: Create type definitions for rules (#324)

fasttime · web-flow · commit 5f11a3d07110 · 2025-03-26T10:36:18.000-04:00
* fix: make `RuleModule` language specific

* patch for deprecated `RuleContext` methods

* extend `MarkdownRuleVisitor`

* fix `IMarkdownSourceCode`

* export generic type `MarkdownRuleDefinition`

* remove patch for deprecated `RuleContext` methods

* update ESLint

* remove `MarkdownRuleDefinition` export
diff --git a/package.json b/package.json
@@ -66,7 +66,7 @@
     "c8": "^10.1.2",
     "chai": "^5.1.1",
     "dedent": "^1.5.3",
-    "eslint": "^9.15.0",
+    "eslint": "^9.23.0",
     "eslint-config-eslint": "^11.0.0",
     "eslint-plugin-eslint-plugin": "^6.3.2",
     "globals": "^15.1.0",
diff --git a/src/index.js b/src/index.js
@@ -19,7 +19,8 @@ import rules from "./build/rules.js";
 /** @typedef {import("eslint").Linter.RulesRecord} RulesRecord*/
 /** @typedef {import("eslint").Linter.Config} Config*/
 /** @typedef {import("eslint").ESLint.Plugin} Plugin */
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/** @typedef {import("./types.ts").MarkdownRuleDefinition} RuleModule */
+/** @typedef {import("./types.ts").MarkdownRuleVisitor} MarkdownRuleVisitor */
 /** @typedef {import("@eslint/core").Language} Language */
 
 //-----------------------------------------------------------------------------
diff --git a/src/language/markdown-source-code.js b/src/language/markdown-source-code.js
@@ -32,6 +32,7 @@ import { findOffsets } from "../util.js";
 /** @typedef {import("@eslint/core").SourceRange} SourceRange */
 /** @typedef {import("@eslint/core").FileProblem} FileProblem */
 /** @typedef {import("@eslint/core").DirectiveType} DirectiveType */
+/** @typedef {import("../types.ts").IMarkdownSourceCode} IMarkdownSourceCode */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -135,6 +136,7 @@ function extractInlineConfigCommentsFromHTML(node) {
 
 /**
  * Markdown Source Code Object
+ * @implements {IMarkdownSourceCode}
  */
 export class MarkdownSourceCode extends TextSourceCodeBase {
 	/**
diff --git a/src/rules/fenced-code-language.js b/src/rules/fenced-code-language.js
@@ -7,13 +7,16 @@
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ required?: string[]; }]; }>}
+ * FencedCodeLanguageRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {FencedCodeLanguageRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
diff --git a/src/rules/heading-increment.js b/src/rules/heading-increment.js
@@ -7,13 +7,16 @@
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * HeadingIncrementRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {HeadingIncrementRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
@@ -40,7 +43,7 @@ export default {
 						messageId: "skippedHeading",
 						data: {
 							fromLevel: lastHeadingDepth.toString(),
-							toLevel: node.depth,
+							toLevel: node.depth.toString(),
 						},
 					});
 				}
diff --git a/src/rules/no-duplicate-headings.js b/src/rules/no-duplicate-headings.js
@@ -7,13 +7,16 @@
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * NoDuplicateHeadingsRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {NoDuplicateHeadingsRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
diff --git a/src/rules/no-empty-links.js b/src/rules/no-empty-links.js
@@ -6,13 +6,16 @@
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * NoEmptyLinksRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {NoEmptyLinksRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
diff --git a/src/rules/no-html.js b/src/rules/no-html.js
@@ -13,7 +13,10 @@ import { findOffsets } from "../util.js";
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ allowed?: string[]; }]; }>}
+ * NoHtmlRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -25,7 +28,7 @@ const htmlTagPattern = /<([a-z0-9]+(?:-[a-z0-9]+)*)/giu;
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {NoHtmlRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
diff --git a/src/rules/no-invalid-label-refs.js b/src/rules/no-invalid-label-refs.js
@@ -15,7 +15,10 @@ import { findOffsets, illegalShorthandTailPattern } from "../util.js";
 
 /** @typedef {import("unist").Position} Position */
 /** @typedef {import("mdast").Text} TextNode */
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * NoInvalidLabelRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -120,7 +123,7 @@ function findInvalidLabelReferences(node, docText) {
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {NoInvalidLabelRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
diff --git a/src/rules/no-missing-label-refs.js b/src/rules/no-missing-label-refs.js
@@ -15,7 +15,10 @@ import { findOffsets, illegalShorthandTailPattern } from "../util.js";
 
 /** @typedef {import("unist").Position} Position */
 /** @typedef {import("mdast").Text} TextNode */
-/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
+ * NoMissingLabelRuleDefinition
+ */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -101,7 +104,7 @@ function findMissingReferences(node, nodeText) {
 // Rule Definition
 //-----------------------------------------------------------------------------
 
-/** @type {RuleModule} */
+/** @type {NoMissingLabelRuleDefinition} */
 export default {
 	meta: {
 		type: "problem",
diff --git a/src/types.ts b/src/types.ts
@@ -1,5 +1,39 @@
-import type { Node } from "mdast";
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+
+import type {
+	Code,
+	Heading,
+	Html,
+	Link,
+	Node,
+	Parent,
+	Root,
+	Text,
+} from "mdast";
 import type { Linter } from "eslint";
+import type {
+	RuleDefinition,
+	RuleVisitor,
+	SourceLocation,
+	TextSourceCode,
+} from "@eslint/core";
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+/** Adds matching `:exit` selectors for all properties of a `RuleVisitor`. */
+type WithExit<RuleVisitorType extends RuleVisitor> = {
+	[Key in keyof RuleVisitorType as
+		| Key
+		| `${Key & string}:exit`]: RuleVisitorType[Key];
+};
+
+//------------------------------------------------------------------------------
+// Exports
+//------------------------------------------------------------------------------
 
 export interface RangeMap {
 	indent: number;
@@ -20,3 +54,63 @@ export interface Block extends Node, BlockBase {
 export type Message = Linter.LintMessage;
 
 export type RuleType = "problem" | "suggestion" | "layout";
+
+/**
+ * The `SourceCode` interface for Markdown files.
+ */
+export interface IMarkdownSourceCode
+	extends TextSourceCode<{
+		LangOptions: {};
+		RootNode: Root;
+		SyntaxElementWithLoc: Node;
+		ConfigNode: { value: string; position: SourceLocation };
+	}> {
+	/**
+	 * Gets the entire source text split into an array of lines.
+	 * @returns The source text as an array of lines.
+	 */
+	get lines(): Array<string>;
+
+	/**
+	 * Gets the source code for the given node.
+	 * @param node The AST node to get the text for.
+	 * @param beforeCount The number of characters before the node to retrieve.
+	 * @param afterCount The number of characters after the node to retrieve.
+	 * @returns The text representing the AST node.
+	 */
+	getText(node?: Node, beforeCount?: number, afterCount?: number): string;
+}
+
+export interface MarkdownRuleVisitor
+	extends RuleVisitor,
+		WithExit<{
+			root?(node: Root): void;
+			code?(node: Code, parent?: Parent): void;
+			heading?(node: Heading, parent?: Parent): void;
+			html?(node: Html, parent?: Parent): void;
+			link?(node: Link, parent?: Parent): void;
+			text?(node: Text, parent?: Parent): void;
+		}> {}
+
+export type MarkdownRuleDefinitionTypeOptions = {
+	RuleOptions: unknown[];
+	MessageIds: string;
+	ExtRuleDocs: Record<string, unknown>;
+};
+
+export type MarkdownRuleDefinition<
+	Options extends Partial<MarkdownRuleDefinitionTypeOptions> = {},
+> = RuleDefinition<
+	// Language specific type options (non-configurable)
+	{
+		LangOptions: {};
+		Code: IMarkdownSourceCode;
+		Visitor: MarkdownRuleVisitor;
+		Node: Node;
+	} & Required<
+		// Rule specific type options (custom)
+		Options &
+			// Rule specific type options (defaults)
+			Omit<MarkdownRuleDefinitionTypeOptions, keyof Options>
+	>
+>;
diff --git a/tests/types/types.test.ts b/tests/types/types.test.ts
@@ -1,4 +1,13 @@
-import markdown from "@eslint/markdown";
+import markdown, {
+	IMarkdownSourceCode,
+	MarkdownNode,
+	MarkdownRuleVisitor,
+	ParentNode,
+	RootNode,
+	SourceLocation,
+	TextNode,
+	type RuleModule,
+} from "@eslint/markdown";
 import { ESLint, Linter } from "eslint";
 
 markdown satisfies ESLint.Plugin;
@@ -35,3 +44,41 @@ typeof processorPlugins satisfies {};
 	// Check that all recommended rule names match the names of existing rules in this plugin.
 	null as AssertAllNamesIn<RecommendedRuleName, RuleName>;
 }
+
+(): RuleModule => ({
+	create({ sourceCode }): MarkdownRuleVisitor {
+		sourceCode satisfies IMarkdownSourceCode;
+
+		sourceCode.ast satisfies RootNode;
+		sourceCode.lines satisfies string[];
+
+		return {
+			// Root selector
+			root(node) {
+				node satisfies RootNode;
+			},
+
+			// Known node selector, sourceCode methods used in visitor
+			text(node) {
+				node satisfies TextNode;
+				sourceCode.getText(node) satisfies string;
+				sourceCode.getLoc(node) satisfies SourceLocation;
+			},
+
+			// Known node selector with parent
+			link(node, parent) {
+				node satisfies MarkdownNode;
+				parent satisfies ParentNode | undefined;
+			},
+
+			// Known node selector with ":exit"
+			"html:exit"(node, parent) {
+				node satisfies MarkdownNode;
+				parent satisfies ParentNode | undefined;
+			},
+
+			// Unknown selectors allowed
+			"heading[depth=1]"(node: MarkdownNode, parent?: ParentNode) {},
+		};
+	},
+});
diff --git a/tools/dedupe-types.js b/tools/dedupe-types.js
@@ -39,5 +39,10 @@ files.forEach(filePath => {
 		return true;
 	});
 
-	fs.writeFileSync(filePath, remainingLines.join("\n"), "utf8");
+	// replace references to ../types.ts with ./types.ts
+	const text = remainingLines
+		.join("\n")
+		.replace(/\.\.\/types\.ts/gu, "./types.ts");
+
+	fs.writeFileSync(filePath, text, "utf8");
 });
