refactor: Add type references (#18652)

nzakas · mdjermanovic · web-flow · commit 7bcda760369c · 2024-07-05T17:45:24.000+02:00
* refactor: Add type references

* Update lib/languages/js/index.js

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;

---------

Co-authored-by: Milos Djermanovic &lt;milos.djermanovic@gmail.com&gt;
diff --git 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
@@ -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<TraversalStep>}
+     * @type {Array<ITraversalStep>}
      */
     #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
@@ -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
@@ -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
@@ -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
@@ -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",
