From 7bcda760369c44d0f1131fccaaf1ccfed5af85f1 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Fri, 5 Jul 2024 11:45:24 -0400 Subject: [PATCH] refactor: Add type references (#18652) * refactor: Add type references * Update lib/languages/js/index.js Co-authored-by: Milos Djermanovic --------- Co-authored-by: Milos Djermanovic --- lib/languages/js/index.js | 13 +++++++++---- lib/languages/js/source-code/source-code.js | 10 ++++++++-- lib/linter/apply-disable-directives.js | 9 ++++++--- lib/linter/linter.js | 8 ++++++-- lib/linter/vfile.js | 7 +++++++ package.json | 1 + 6 files changed, 37 insertions(+), 11 deletions(-) diff --git a/lib/languages/js/index.js b/lib/languages/js/index.js index 8991ee181059..f8c3ae6c36bc 100644 --- a/lib/languages/js/index.js +++ b/lib/languages/js/index.js @@ -20,7 +20,9 @@ const { validateLanguageOptions } = require("./validate-language-options"); // Type Definitions //----------------------------------------------------------------------------- -/** @typedef {import("../../linter/vfile").VFile} VFile */ +/** @typedef {import("@eslint/core").File} File */ +/** @typedef {import("@eslint/core").Language} Language */ +/** @typedef {import("@eslint/core").OkParseResult} OkParseResult */ //----------------------------------------------------------------------------- // Helpers @@ -56,6 +58,9 @@ function analyzeScope(ast, languageOptions, visitorKeys) { // Exports //----------------------------------------------------------------------------- +/** + * @type {Language} + */ module.exports = { fileType: "text", @@ -143,7 +148,7 @@ module.exports = { /** * Parses the given file into an AST. - * @param {VFile} file The virtual file to parse. + * @param {File} file The virtual file to parse. * @param {Object} options Additional options passed from ESLint. * @param {LanguageOptions} options.languageOptions The language options. * @returns {Object} The result of parsing. @@ -218,8 +223,8 @@ module.exports = { /** * Creates a new `SourceCode` object from the given information. - * @param {VFile} file The virtual file to create a `SourceCode` object from. - * @param {Object} parseResult The result returned from `parse()`. + * @param {File} file The virtual file to create a `SourceCode` object from. + * @param {OkParseResult} parseResult The result returned from `parse()`. * @param {Object} options Additional options passed from ESLint. * @param {LanguageOptions} options.languageOptions The language options. * @returns {SourceCode} The new `SourceCode` object. diff --git a/lib/languages/js/source-code/source-code.js b/lib/languages/js/source-code/source-code.js index 2401dafc522b..7baf2ea26c86 100644 --- a/lib/languages/js/source-code/source-code.js +++ b/lib/languages/js/source-code/source-code.js @@ -29,6 +29,10 @@ const //------------------------------------------------------------------------------ /** @typedef {import("eslint-scope").Variable} Variable */ +/** @typedef {import("eslint-scope").Scope} Scope */ +/** @typedef {import("@eslint/core").SourceCode} ISourceCode */ +/** @typedef {import("@eslint/core").Directive} IDirective */ +/** @typedef {import("@eslint/core").TraversalStep} ITraversalStep */ //------------------------------------------------------------------------------ // Private @@ -373,6 +377,7 @@ class TraversalStep { /** * A class to represent a directive comment. + * @implements {IDirective} */ class Directive { @@ -429,12 +434,13 @@ const caches = Symbol("caches"); /** * Represents parsed source code. + * @implements {ISourceCode} */ class SourceCode extends TokenStore { /** * The cache of steps that were taken while traversing the source code. - * @type {Array} + * @type {Array} */ #steps; @@ -838,7 +844,7 @@ class SourceCode extends TokenStore { /** * Gets the scope for the given node * @param {ASTNode} currentNode The node to get the scope of - * @returns {eslint-scope.Scope} The scope information for this node + * @returns {Scope} The scope information for this node * @throws {TypeError} If the `currentNode` argument is missing. */ getScope(currentNode) { diff --git a/lib/linter/apply-disable-directives.js b/lib/linter/apply-disable-directives.js index beb6e5d8c210..723bcf55015c 100644 --- a/lib/linter/apply-disable-directives.js +++ b/lib/linter/apply-disable-directives.js @@ -10,6 +10,9 @@ //------------------------------------------------------------------------------ /** @typedef {import("../shared/types").LintMessage} LintMessage */ +/** @typedef {import("@eslint/core").Language} Language */ +/** @typedef {import("@eslint/core").Position} Position */ +/** @typedef {import("@eslint/core").RulesConfig} RulesConfig */ //------------------------------------------------------------------------------ // Module Definition @@ -24,8 +27,8 @@ const { /** * Compares the locations of two objects in a source file - * @param {{line: number, column: number}} itemA The first object - * @param {{line: number, column: number}} itemB The second object + * @param {Position} itemA The first object + * @param {Position} itemB The second object * @returns {number} A value less than 1 if itemA appears before itemB in the source file, greater than 1 if * itemA appears after itemB in the source file, or 0 if itemA and itemB have the same location. */ @@ -418,7 +421,7 @@ function applyDirectives(options) { * @param {{ruleId: (string|null), line: number, column: number}[]} options.problems * A list of problems reported by rules, sorted by increasing location in the file, with one-based columns. * @param {"off" | "warn" | "error"} options.reportUnusedDisableDirectives If `"warn"` or `"error"`, adds additional problems for unused directives - * @param {Object} options.configuredRules The rules configuration. + * @param {RulesConfig} options.configuredRules The rules configuration. * @param {Function} options.ruleFilter A predicate function to filter which rules should be executed. * @param {boolean} options.disableFixes If true, it doesn't make `fix` properties. * @returns {{ruleId: (string|null), line: number, column: number, suppressions?: {kind: string, justification: string}}[]} diff --git a/lib/linter/linter.js b/lib/linter/linter.js index 21484b66dcd2..86b51b6488fb 100644 --- a/lib/linter/linter.js +++ b/lib/linter/linter.js @@ -72,6 +72,10 @@ const STEP_KIND_CALL = 2; /** @typedef {import("../shared/types").Processor} Processor */ /** @typedef {import("../shared/types").Rule} Rule */ /** @typedef {import("../shared/types").Times} Times */ +/** @typedef {import("@eslint/core").Language} Language */ +/** @typedef {import("@eslint/core").RuleSeverity} RuleSeverity */ +/** @typedef {import("@eslint/core").RuleConfig} RuleConfig */ + /* eslint-disable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */ /** @@ -276,7 +280,7 @@ function updateLocationInformation({ line, column, endLine, endColumn }, languag * @param {string} [options.ruleId] the ruleId to report * @param {Object} [options.loc] the loc to report * @param {string} [options.message] the error message to report - * @param {string} [options.severity] the error message to report + * @param {RuleSeverity} [options.severity] the error message to report * @param {Language} [options.language] the language to use to adjust the location information * @returns {LintMessage} created problem, returns a missing-rule problem if only provided ruleId. * @private @@ -877,7 +881,7 @@ function storeTime(time, timeOpts, slots) { /** * Get the options for a rule (not including severity), if any - * @param {Array|number} ruleConfig rule configuration + * @param {RuleConfig} ruleConfig rule configuration * @returns {Array} of rule options, empty Array if none */ function getRuleOptions(ruleConfig) { diff --git a/lib/linter/vfile.js b/lib/linter/vfile.js index 904deb39abe3..8528a5197b05 100644 --- a/lib/linter/vfile.js +++ b/lib/linter/vfile.js @@ -5,6 +5,12 @@ "use strict"; +//----------------------------------------------------------------------------- +// Type Definitions +//----------------------------------------------------------------------------- + +/** @typedef {import("@eslint/core").File} File */ + //------------------------------------------------------------------------------ // Helpers //------------------------------------------------------------------------------ @@ -54,6 +60,7 @@ function stripUnicodeBOM(value) { /** * Represents a virtual file inside of ESLint. + * @implements {File} */ class VFile { diff --git a/package.json b/package.json index e0bad93c09c5..941ea8f33fdc 100644 --- a/package.json +++ b/package.json @@ -104,6 +104,7 @@ "devDependencies": { "@babel/core": "^7.4.3", "@babel/preset-env": "^7.4.3", + "@eslint/core": "^0.1.0", "@types/estree": "^1.0.5", "@types/node": "^20.11.5", "@wdio/browser-runner": "^8.38.3",