refactor: migrate type declarations to use the @import syntax

src/index.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Enables the processor for Markdown file extensions.
+ * @fileoverview Markdown plugin.
  * @author Brandon Mills
  */
 
@@ -17,16 +17,18 @@ 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 { MarkdownRuleVisitor as MRV, MarkdownRuleDefinition as MRD, MarkdownRuleDefinitionTypeOptions } from "./types.js";
+ * @typedef {Linter.RulesRecord} RulesRecord
+ * @typedef {MarkdownRuleDefinition} RuleModule
+ * @typedef {MRV} MarkdownRuleVisitor
+ */
+
+/**
+ * @typedef {MRD<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);

src/processor.js

@@ -13,15 +13,14 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("./types.ts").Block} Block */
-/** @typedef {import("./types.ts").RangeMap} RangeMap */
-/** @typedef {import("mdast").Node} Node */
-/** @typedef {import("mdast").Parent} ParentNode */
-/** @typedef {import("mdast").Code} CodeNode */
-/** @typedef {import("mdast").Html} HtmlNode */
-/** @typedef {import("eslint").Linter.LintMessage} Message */
-/** @typedef {import("eslint").Rule.Fix} Fix */
-/** @typedef {import("eslint").AST.Range} Range */
+/**
+ * @import { Node, Parent, Code, Html } from "mdast";
+ * @import { Linter, Rule, AST } from "eslint";
+ * @import { Block, RangeMap } from "./types.js";
+ * @typedef {Linter.LintMessage} Message
+ * @typedef {Rule.Fix} Fix
+ * @typedef {AST.Range} Range
+ */
 
 //-----------------------------------------------------------------------------
 // Helpers
@@ -53,7 +52,7 @@ function traverse(node, callbacks) {
 		callbacks["*"]();
 	}
 
-	const parent = /** @type {ParentNode} */ (node);
+	const parent = /** @type {Parent} */ (node);
 
 	if (typeof parent.children !== "undefined") {
 		for (let i = 0; i < parent.children.length; i++) {
@@ -291,7 +290,7 @@ function preprocess(sourceText, filename) {
 
 		/**
 		 * Visit a code node.
-		 * @param {CodeNode} node The visited node.
+		 * @param {Code} node The visited node.
 		 * @returns {void}
 		 */
 		code(node) {
@@ -320,7 +319,7 @@ function preprocess(sourceText, filename) {
 
 		/**
 		 * Visit an HTML node.
-		 * @param {HtmlNode} node The visited node.
+		 * @param {Html} node The visited node.
 		 * @returns {void}
 		 */
 		html(node) {

src/rules/fenced-code-language.js

@@ -8,8 +8,10 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ required?: string[]; }]; }>}
- * FencedCodeLanguageRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"missingLanguage" | "disallowedLanguage"} FencedCodeLanguageMessageIds
+ * @typedef {[{ required?: string[] }]} FencedCodeLanguageOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: FencedCodeLanguageOptions, MessageIds: FencedCodeLanguageMessageIds }>} FencedCodeLanguageRuleDefinition
  */
 
 //-----------------------------------------------------------------------------

src/rules/heading-increment.js

@@ -8,8 +8,10 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
- * HeadingIncrementRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"skippedHeading"} HeadingIncrementMessageIds
+ * @typedef {[]} HeadingIncrementOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: HeadingIncrementOptions, MessageIds: HeadingIncrementMessageIds }>} HeadingIncrementRuleDefinition
  */
 
 //-----------------------------------------------------------------------------

src/rules/no-bare-urls.js

@@ -7,14 +7,12 @@
 // 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
+ * @import { Node, Heading, Paragraph, TableCell, Link } from "mdast";
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"bareUrl"} NoBareUrlsMessageIds
+ * @typedef {[]} NoBareUrlsOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoBareUrlsOptions, MessageIds: NoBareUrlsMessageIds }>} NoBareUrlsRuleDefinition
  */
 
 //-----------------------------------------------------------------------------
@@ -67,14 +65,14 @@ export default {
 
 	create(context) {
 		const { sourceCode } = context;
-		/** @type {Array<LinkNode>} */
+		/** @type {Array<Link>} */
 		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
+		 * @param {Paragraph|Heading|TableCell} node The node to process
 		 * @returns {void}
 		 */
 		function findBareUrls(node) {

src/rules/no-duplicate-definitions.js

@@ -8,8 +8,10 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ allowDefinitions: string[], allowFootnoteDefinitions: string[]; }]; }>}
- * NoDuplicateDefinitionsRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"duplicateDefinition" | "duplicateFootnoteDefinition"} NoDuplicateDefinitionsMessageIds
+ * @typedef {[{ allowDefinitions?: string[], allowFootnoteDefinitions?: string[] }]} NoDuplicateDefinitionsOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoDuplicateDefinitionsOptions, MessageIds: NoDuplicateDefinitionsMessageIds }>} NoDuplicateDefinitionsRuleDefinition
  */
 
 //-----------------------------------------------------------------------------
@@ -70,7 +72,9 @@ export default {
 			context.options[0]?.allowFootnoteDefinitions,
 		);
 
+		/** @type {Set<string>} */
 		const definitions = new Set();
+		/** @type {Set<string>} */
 		const footnoteDefinitions = new Set();
 
 		return {

src/rules/no-duplicate-headings.js

@@ -7,10 +7,12 @@
 // Type Definitions
 //-----------------------------------------------------------------------------
 
-/** @typedef {import("mdast").Heading} HeadingNode */
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ checkSiblingsOnly?: boolean; }]; }>}
- * NoDuplicateHeadingsRuleDefinition
+ * @import { Heading } from "mdast";
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"duplicateHeading"} NoDuplicateHeadingsMessageIds
+ * @typedef {[{ checkSiblingsOnly?: boolean }]} NoDuplicateHeadingsOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoDuplicateHeadingsOptions, MessageIds: NoDuplicateHeadingsMessageIds }>} NoDuplicateHeadingsRuleDefinition
  */
 
 //-----------------------------------------------------------------------------
@@ -65,7 +67,7 @@ export default {
 
 		/**
 		 * Gets the text of a heading node
-		 * @param {HeadingNode} node The heading node
+		 * @param {Heading} node The heading node
 		 * @returns {string} The heading text
 		 */
 		function getHeadingText(node) {

src/rules/no-empty-definitions.js

@@ -8,8 +8,10 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
- * NoEmptyDefinitionsRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"emptyDefinition"} NoEmptyDefinitionsMessageIds
+ * @typedef {[]} NoEmptyDefinitionsOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoEmptyDefinitionsOptions, MessageIds: NoEmptyDefinitionsMessageIds }>} NoEmptyDefinitionsRuleDefinition
  */
 
 //-----------------------------------------------------------------------------

src/rules/no-empty-images.js

@@ -8,8 +8,10 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
- * NoEmptyImagesRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"emptyImage"} NoEmptyImagesMessageIds
+ * @typedef {[]} NoEmptyImagesOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoEmptyImagesOptions, MessageIds: NoEmptyImagesMessageIds }>} NoEmptyImagesRuleDefinition
  */
 
 //-----------------------------------------------------------------------------

src/rules/no-empty-links.js

@@ -7,8 +7,10 @@
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: []; }>}
- * NoEmptyLinksRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"emptyLink"} NoEmptyLinksMessageIds
+ * @typedef {[]} NoEmptyLinksOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoEmptyLinksOptions, MessageIds: NoEmptyLinksMessageIds }>} NoEmptyLinksRuleDefinition
  */
 
 //-----------------------------------------------------------------------------

src/rules/no-html.js

@@ -14,8 +14,10 @@ import { findOffsets } from "../util.js";
 //-----------------------------------------------------------------------------
 
 /**
- * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ allowed?: string[]; }]; }>}
- * NoHtmlRuleDefinition
+ * @import { MarkdownRuleDefinition } from "../types.js";
+ * @typedef {"disallowedElement"} NoHtmlMessageIds
+ * @typedef {[{ allowed?: string[] }]} NoHtmlOptions
+ * @typedef {MarkdownRuleDefinition<{ RuleOptions: NoHtmlOptions, MessageIds: NoHtmlMessageIds }>} NoHtmlRuleDefinition
  */
 
 //-----------------------------------------------------------------------------