feat(utils): update types to reflect RuleContext and SourceCode c…

…hanges and deprecations (#7812)

* chore(utils): deprecate `Context#parserServices`

* feat(utils): define new methods on `SourceCode`

* chore(utils): mark `Context` properties and methods as deprecated

* fix(utils): `getAncestors` not `getScope`

* chore: ignore usage of deprecated property for now

* fix(utils): mark new methods as optional

* Update getParserServices.ts

---------

Co-authored-by: Brad Zacher <brad.zacher@gmail.com>

packages/utils/src/eslint-utils/getParserServices.ts

@@ -67,7 +67,9 @@ function getParserServices(
   // This check allows us to handle bad user setups whilst providing a nice user-facing
   // error message explaining the problem.
   if (
+    // eslint-disable-next-line deprecation/deprecation -- TODO - support for ESLint v9 with backwards-compatible support for ESLint v8
     context.parserServices?.esTreeNodeToTSNodeMap == null ||
+    // eslint-disable-next-line deprecation/deprecation -- TODO - support for ESLint v9 with backwards-compatible support for ESLint v8
     context.parserServices.tsNodeToESTreeNodeMap == null
   ) {
     throw new Error(ERROR_MESSAGE);
@@ -76,12 +78,14 @@ function getParserServices(
   // if a rule requires full type information, then hard fail if it doesn't exist
   // this forces the user to supply parserOptions.project
   if (
+    // eslint-disable-next-line deprecation/deprecation -- TODO - support for ESLint v9 with backwards-compatible support for ESLint v8
     context.parserServices.program == null &&
     !allowWithoutFullTypeInformation
   ) {
     throw new Error(ERROR_MESSAGE);
   }
 
+  // eslint-disable-next-line deprecation/deprecation -- TODO - support for ESLint v9 with backwards-compatible support for ESLint v8
   return context.parserServices;
 }
 /* eslint-enable @typescript-eslint/unified-signatures */

packages/utils/src/ts-eslint/Rule.ts

@@ -195,6 +195,8 @@ interface RuleContext<
   parserOptions: Linter.ParserOptions;
   /**
    * An object containing parser-provided services for rules
+   *
+   * @deprecated in favor of `SourceCode#parserServices`
    */
   parserServices?: ParserServices;
   /**
@@ -207,19 +209,24 @@ interface RuleContext<
    * Returns an array of the ancestors of the currently-traversed node, starting at
    * the root of the AST and continuing through the direct parent of the current node.
    * This array does not include the currently-traversed node itself.
+   *
+   * @deprecated in favor of `SourceCode#getAncestors`
    */
   getAncestors(): TSESTree.Node[];
 
   /**
    * Returns a list of variables declared by the given node.
    * This information can be used to track references to variables.
+   *
+   * @deprecated in favor of `SourceCode#getDeclaredVariables`
    */
   getDeclaredVariables(node: TSESTree.Node): readonly Scope.Variable[];
 
   /**
    * Returns the current working directory passed to Linter.
    * It is a path to a directory that should be considered as the current working directory.
    * @since 6.6.0
+   * @deprecated in favor of `RuleContext#cwd`
    */
   getCwd(): string;
 
@@ -232,6 +239,8 @@ interface RuleContext<
 
   /**
    * Returns the filename associated with the source.
+   *
+   * @deprecated in favor of `RuleContext#filename`
    */
   getFilename(): string;
 
@@ -244,6 +253,7 @@ interface RuleContext<
   /**
    * Returns the full path of the file on disk without any code block information (unlike `getFilename()`).
    * @since 7.28.0
+   * @deprecated in favor of `RuleContext#physicalFilename`
    */
   getPhysicalFilename?(): string;
 
@@ -256,12 +266,16 @@ interface RuleContext<
   /**
    * Returns the scope of the currently-traversed node.
    * This information can be used track references to variables.
+   *
+   * @deprecated in favor of `SourceCode#getScope`
    */
   getScope(): Scope.Scope;
 
   /**
    * Returns a SourceCode object that you can use to work with the source that
    * was passed to ESLint.
+   *
+   * @deprecated in favor of `RuleContext#sourceCode`
    */
   getSourceCode(): Readonly<SourceCode>;
 
@@ -275,6 +289,8 @@ interface RuleContext<
   /**
    * Marks a variable with the given name in the current scope as used.
    * This affects the no-unused-vars rule.
+   *
+   * @deprecated in favor of `SourceCode#markVariableAsUsed`
    */
   markVariableAsUsed(name: string): boolean;
 

packages/utils/src/ts-eslint/SourceCode.ts

@@ -299,6 +299,31 @@ declare class SourceCodeBase extends TokenStore {
    * @deprecated in favor of isSpaceBetween
    */
   isSpaceBetweenTokens(first: TSESTree.Token, second: TSESTree.Token): boolean;
+  /**
+   * Returns the scope of the given node.
+   * This information can be used track references to variables.
+   * @since 8.37.0
+   */
+  getScope?(node: TSESTree.Node): Scope.Scope;
+  /**
+   * Returns an array of the ancestors of the given node, starting at
+   * the root of the AST and continuing through the direct parent of the current node.
+   * This array does not include the currently-traversed node itself.
+   * @since 8.38.0
+   */
+  getAncestors?(node: TSESTree.Node): TSESTree.Node[];
+  /**
+   * Returns a list of variables declared by the given node.
+   * This information can be used to track references to variables.
+   * @since 8.38.0
+   */
+  getDeclaredVariables?(node: TSESTree.Node): readonly Scope.Variable[];
+  /**
+   * Marks a variable with the given name in the current scope as used.
+   * This affects the no-unused-vars rule.
+   * @since 8.39.0
+   */
+  markVariableAsUsed?(name: string, node: TSESTree.Node): boolean;
   /**
    * The source code split into lines according to ECMA-262 specification.
    * This is done to avoid each rule needing to do so separately.