TypeScript ESLint Types

/**
 * Complete ESLint rule module with TypeScript support
 */
interface RuleModule<
  TMessageIds extends string,
  TOptions extends readonly unknown[],
  TRuleListener extends RuleListener = RuleListener
> {
  /** Rule metadata including messages, schema, and documentation */
  meta: RuleMetaData<TMessageIds>;
  /** Function that creates the rule implementation */
  create(context: RuleContext<TMessageIds, TOptions>): TRuleListener;
  /** Default options for the rule */
  defaultOptions?: TOptions;
}

/**
 * Function signature for creating rule implementations
 */
type RuleCreateFunction<
  TMessageIds extends string,
  TOptions extends readonly unknown[],
  TRuleListener extends RuleListener = RuleListener
> = (context: RuleContext<TMessageIds, TOptions>) => TRuleListener;

/**
 * Rule metadata interface with TypeScript message ID support
 */
interface RuleMetaData<TMessageIds extends string> {
  /** Rule category: 'problem' for bugs, 'suggestion' for improvements, 'layout' for formatting */
  type: 'problem' | 'suggestion' | 'layout';
  /** Message templates keyed by message ID */
  messages: Record<TMessageIds, string>;
  /** Whether the rule can automatically fix issues */
  fixable?: 'code' | 'whitespace';
  /** JSON schema for rule options validation */
  schema: JSONSchema.JSONSchema7 | readonly JSONSchema.JSONSchema7[];
  /** Whether the rule is deprecated */
  deprecated?: boolean;
  /** Rules that replace this deprecated rule */
  replacedBy?: readonly string[];
  /** Documentation metadata */
  docs?: RuleMetaDataDocs;
  /** Whether the rule has suggestions */
  hasSuggestions?: boolean;
}

/**
 * Rule documentation metadata
 */
interface RuleMetaDataDocs {
  /** Description of what the rule does */
  description: string;
  /** Rule category for organization */
  category?: string;
  /** Recommendation level for the rule */
  recommended?: boolean | 'error' | 'warn' | 'strict';
  /** Whether the rule requires TypeScript type checking */
  requiresTypeChecking?: boolean;
  /** Whether this rule extends a base ESLint rule */
  extendsBaseRule?: boolean | string;
  /** URL to rule documentation */
  url?: string;
}

/**
 * Rule recommendation levels
 */
type RuleRecommendation = 'error' | 'strict' | 'warn' | false;

/**
 * Rule execution context with TypeScript support
 */
interface RuleContext<TMessageIds extends string, TOptions extends readonly unknown[]> {
  /** Rule configuration options */
  readonly options: TOptions;
  /** Shared configuration settings */
  readonly settings: Record<string, unknown>;
  /** Source code being analyzed */
  readonly sourceCode: SourceCode;
  /** Physical filename being linted */
  readonly filename: string;
  /** Configured parser options */
  readonly parserOptions: ParserOptions;
  /** Parser path used */
  readonly parserPath: string;
  /** Language options */
  readonly languageOptions?: {
    ecmaVersion?: ParserOptions['ecmaVersion'];
    sourceType?: ParserOptions['sourceType'];
    globals?: Record<string, boolean>;
  };
  
  /**
   * Gets the current ESLint scope
   * @returns Current scope object
   */
  getScope(): Scope.Scope;
  
  /**
   * Gets all ancestor nodes of the current node
   * @returns Array of ancestor nodes from closest to root
   */
  getAncestors(): TSESTree.Node[];
  
  /**
   * Gets variables declared by the given node
   * @param node - AST node to get variables for
   * @returns Array of variables declared by the node
   */
  getDeclaredVariables(node: TSESTree.Node): Scope.Variable[];
  
  /**
   * Gets the source code object for the file being linted
   * @returns SourceCode instance
   */
  getSourceCode(): SourceCode;
  
  /**
   * Gets the filename being linted
   * @returns Physical filename
   */
  getFilename(): string;
  
  /**
   * Marks a variable as used to prevent unused variable warnings
   * @param name - Variable name to mark as used
   * @returns True if variable was found and marked
   */
  markVariableAsUsed(name: string): boolean;
  
  /**
   * Reports a rule violation
   * @param descriptor - Problem description with message and location
   */
  report(descriptor: ReportDescriptor<TMessageIds>): void;
  
  /**
   * Reports a rule violation at a specific node
   * @param node - AST node where the problem occurs
   * @param message - Problem message or message ID
   * @param data - Template data for message interpolation
   */
  report(node: TSESTree.Node, message: string): void;
  report(node: TSESTree.Node, messageId: TMessageIds, data?: Record<string, unknown>): void;
}

/**
 * AST visitor interface with handlers for all node types
 */
interface RuleListener {
  /** Visitor for ArrayExpression nodes */
  ArrayExpression?(node: TSESTree.ArrayExpression): void;
  /** Visitor for ArrayPattern nodes */
  ArrayPattern?(node: TSESTree.ArrayPattern): void;
  /** Visitor for ArrowFunctionExpression nodes */
  ArrowFunctionExpression?(node: TSESTree.ArrowFunctionExpression): void;
  /** Visitor for AssignmentExpression nodes */
  AssignmentExpression?(node: TSESTree.AssignmentExpression): void;
  /** Visitor for AssignmentPattern nodes */
  AssignmentPattern?(node: TSESTree.AssignmentPattern): void;
  /** Visitor for AwaitExpression nodes */
  AwaitExpression?(node: TSESTree.AwaitExpression): void;
  /** Visitor for BinaryExpression nodes */
  BinaryExpression?(node: TSESTree.BinaryExpression): void;
  /** Visitor for BlockStatement nodes */
  BlockStatement?(node: TSESTree.BlockStatement): void;
  /** Visitor for BreakStatement nodes */
  BreakStatement?(node: TSESTree.BreakStatement): void;
  /** Visitor for CallExpression nodes */
  CallExpression?(node: TSESTree.CallExpression): void;
  /** Visitor for CatchClause nodes */
  CatchClause?(node: TSESTree.CatchClause): void;
  /** Visitor for ChainExpression nodes */
  ChainExpression?(node: TSESTree.ChainExpression): void;
  /** Visitor for ClassBody nodes */
  ClassBody?(node: TSESTree.ClassBody): void;
  /** Visitor for ClassDeclaration nodes */
  ClassDeclaration?(node: TSESTree.ClassDeclaration): void;
  /** Visitor for ClassExpression nodes */
  ClassExpression?(node: TSESTree.ClassExpression): void;
  /** Visitor for ConditionalExpression nodes */
  ConditionalExpression?(node: TSESTree.ConditionalExpression): void;
  /** Visitor for ContinueStatement nodes */
  ContinueStatement?(node: TSESTree.ContinueStatement): void;
  /** Visitor for DebuggerStatement nodes */
  DebuggerStatement?(node: TSESTree.DebuggerStatement): void;
  /** Visitor for DoWhileStatement nodes */
  DoWhileStatement?(node: TSESTree.DoWhileStatement): void;
  /** Visitor for EmptyStatement nodes */
  EmptyStatement?(node: TSESTree.EmptyStatement): void;
  /** Visitor for ExpressionStatement nodes */
  ExpressionStatement?(node: TSESTree.ExpressionStatement): void;
  /** Visitor for ForInStatement nodes */
  ForInStatement?(node: TSESTree.ForInStatement): void;
  /** Visitor for ForOfStatement nodes */
  ForOfStatement?(node: TSESTree.ForOfStatement): void;
  /** Visitor for ForStatement nodes */
  ForStatement?(node: TSESTree.ForStatement): void;
  /** Visitor for FunctionDeclaration nodes */
  FunctionDeclaration?(node: TSESTree.FunctionDeclaration): void;
  /** Visitor for FunctionExpression nodes */
  FunctionExpression?(node: TSESTree.FunctionExpression): void;
  /** Visitor for Identifier nodes */
  Identifier?(node: TSESTree.Identifier): void;
  /** Visitor for IfStatement nodes */
  IfStatement?(node: TSESTree.IfStatement): void;
  /** Visitor for ImportDeclaration nodes */
  ImportDeclaration?(node: TSESTree.ImportDeclaration): void;
  /** Visitor for ImportDefaultSpecifier nodes */
  ImportDefaultSpecifier?(node: TSESTree.ImportDefaultSpecifier): void;
  /** Visitor for ImportNamespaceSpecifier nodes */
  ImportNamespaceSpecifier?(node: TSESTree.ImportNamespaceSpecifier): void;
  /** Visitor for ImportSpecifier nodes */
  ImportSpecifier?(node: TSESTree.ImportSpecifier): void;
  /** Visitor for LabeledStatement nodes */
  LabeledStatement?(node: TSESTree.LabeledStatement): void;
  /** Visitor for Literal nodes */
  Literal?(node: TSESTree.Literal): void;
  /** Visitor for LogicalExpression nodes */
  LogicalExpression?(node: TSESTree.LogicalExpression): void;
  /** Visitor for MemberExpression nodes */
  MemberExpression?(node: TSESTree.MemberExpression): void;
  /** Visitor for MetaProperty nodes */
  MetaProperty?(node: TSESTree.MetaProperty): void;
  /** Visitor for MethodDefinition nodes */
  MethodDefinition?(node: TSESTree.MethodDefinition): void;
  /** Visitor for NewExpression nodes */
  NewExpression?(node: TSESTree.NewExpression): void;
  /** Visitor for ObjectExpression nodes */
  ObjectExpression?(node: TSESTree.ObjectExpression): void;
  /** Visitor for ObjectPattern nodes */
  ObjectPattern?(node: TSESTree.ObjectPattern): void;
  /** Visitor for Program nodes */
  Program?(node: TSESTree.Program): void;
  /** Visitor for Property nodes */
  Property?(node: TSESTree.Property): void;
  /** Visitor for RestElement nodes */
  RestElement?(node: TSESTree.RestElement): void;
  /** Visitor for ReturnStatement nodes */
  ReturnStatement?(node: TSESTree.ReturnStatement): void;
  /** Visitor for SequenceExpression nodes */
  SequenceExpression?(node: TSESTree.SequenceExpression): void;
  /** Visitor for SpreadElement nodes */
  SpreadElement?(node: TSESTree.SpreadElement): void;
  /** Visitor for Super nodes */
  Super?(node: TSESTree.Super): void;
  /** Visitor for SwitchCase nodes */
  SwitchCase?(node: TSESTree.SwitchCase): void;
  /** Visitor for SwitchStatement nodes */
  SwitchStatement?(node: TSESTree.SwitchStatement): void;
  /** Visitor for TaggedTemplateExpression nodes */
  TaggedTemplateExpression?(node: TSESTree.TaggedTemplateExpression): void;
  /** Visitor for TemplateElement nodes */
  TemplateElement?(node: TSESTree.TemplateElement): void;
  /** Visitor for TemplateLiteral nodes */
  TemplateLiteral?(node: TSESTree.TemplateLiteral): void;
  /** Visitor for ThisExpression nodes */
  ThisExpression?(node: TSESTree.ThisExpression): void;
  /** Visitor for ThrowStatement nodes */
  ThrowStatement?(node: TSESTree.ThrowStatement): void;
  /** Visitor for TryStatement nodes */
  TryStatement?(node: TSESTree.TryStatement): void;
  /** Visitor for UnaryExpression nodes */
  UnaryExpression?(node: TSESTree.UnaryExpression): void;
  /** Visitor for UpdateExpression nodes */
  UpdateExpression?(node: TSESTree.UpdateExpression): void;
  /** Visitor for VariableDeclaration nodes */
  VariableDeclaration?(node: TSESTree.VariableDeclaration): void;
  /** Visitor for VariableDeclarator nodes */
  VariableDeclarator?(node: TSESTree.VariableDeclarator): void;
  /** Visitor for WhileStatement nodes */
  WhileStatement?(node: TSESTree.WhileStatement): void;
  /** Visitor for WithStatement nodes */
  WithStatement?(node: TSESTree.WithStatement): void;
  /** Visitor for YieldExpression nodes */
  YieldExpression?(node: TSESTree.YieldExpression): void;

  // TypeScript-specific nodes
  /** Visitor for TSAbstractKeyword nodes */
  TSAbstractKeyword?(node: TSESTree.TSAbstractKeyword): void;
  /** Visitor for TSAbstractMethodDefinition nodes */
  TSAbstractMethodDefinition?(node: TSESTree.TSAbstractMethodDefinition): void;
  /** Visitor for TSAbstractPropertyDefinition nodes */
  TSAbstractPropertyDefinition?(node: TSESTree.TSAbstractPropertyDefinition): void;
  /** Visitor for TSAnyKeyword nodes */
  TSAnyKeyword?(node: TSESTree.TSAnyKeyword): void;
  /** Visitor for TSArrayType nodes */
  TSArrayType?(node: TSESTree.TSArrayType): void;
  /** Visitor for TSAsExpression nodes */
  TSAsExpression?(node: TSESTree.TSAsExpression): void;
  /** Visitor for TSBigIntKeyword nodes */
  TSBigIntKeyword?(node: TSESTree.TSBigIntKeyword): void;
  /** Visitor for TSBooleanKeyword nodes */
  TSBooleanKeyword?(node: TSESTree.TSBooleanKeyword): void;
  /** Visitor for TSCallSignatureDeclaration nodes */
  TSCallSignatureDeclaration?(node: TSESTree.TSCallSignatureDeclaration): void;
  /** Visitor for TSConditionalType nodes */
  TSConditionalType?(node: TSESTree.TSConditionalType): void;
  /** Visitor for TSConstructorType nodes */
  TSConstructorType?(node: TSESTree.TSConstructorType): void;
  /** Visitor for TSConstructSignatureDeclaration nodes */
  TSConstructSignatureDeclaration?(node: TSESTree.TSConstructSignatureDeclaration): void;
  /** Visitor for TSDeclareFunction nodes */
  TSDeclareFunction?(node: TSESTree.TSDeclareFunction): void;
  /** Visitor for TSDeclareKeyword nodes */
  TSDeclareKeyword?(node: TSESTree.TSDeclareKeyword): void;
  /** Visitor for TSEmptyBodyFunctionExpression nodes */
  TSEmptyBodyFunctionExpression?(node: TSESTree.TSEmptyBodyFunctionExpression): void;
  /** Visitor for TSEnumDeclaration nodes */
  TSEnumDeclaration?(node: TSESTree.TSEnumDeclaration): void;
  /** Visitor for TSEnumMember nodes */
  TSEnumMember?(node: TSESTree.TSEnumMember): void;
  /** Visitor for TSExportKeyword nodes */
  TSExportKeyword?(node: TSESTree.TSExportKeyword): void;
  /** Visitor for TSExternalModuleReference nodes */
  TSExternalModuleReference?(node: TSESTree.TSExternalModuleReference): void;
  /** Visitor for TSFunctionType nodes */
  TSFunctionType?(node: TSESTree.TSFunctionType): void;
  /** Visitor for TSImportEqualsDeclaration nodes */
  TSImportEqualsDeclaration?(node: TSESTree.TSImportEqualsDeclaration): void;
  /** Visitor for TSImportType nodes */
  TSImportType?(node: TSESTree.TSImportType): void;
  /** Visitor for TSIndexedAccessType nodes */
  TSIndexedAccessType?(node: TSESTree.TSIndexedAccessType): void;
  /** Visitor for TSIndexSignature nodes */
  TSIndexSignature?(node: TSESTree.TSIndexSignature): void;
  /** Visitor for TSInferType nodes */
  TSInferType?(node: TSESTree.TSInferType): void;
  /** Visitor for TSInterfaceBody nodes */
  TSInterfaceBody?(node: TSESTree.TSInterfaceBody): void;
  /** Visitor for TSInterfaceDeclaration nodes */
  TSInterfaceDeclaration?(node: TSESTree.TSInterfaceDeclaration): void;
  /** Visitor for TSInterfaceHeritage nodes */
  TSInterfaceHeritage?(node: TSESTree.TSInterfaceHeritage): void;
  /** Visitor for TSIntersectionType nodes */
  TSIntersectionType?(node: TSESTree.TSIntersectionType): void;
  /** Visitor for TSIntrinsicKeyword nodes */
  TSIntrinsicKeyword?(node: TSESTree.TSIntrinsicKeyword): void;
  /** Visitor for TSLiteralType nodes */
  TSLiteralType?(node: TSESTree.TSLiteralType): void;
  /** Visitor for TSMappedType nodes */
  TSMappedType?(node: TSESTree.TSMappedType): void;
  /** Visitor for TSMethodSignature nodes */
  TSMethodSignature?(node: TSESTree.TSMethodSignature): void;
  /** Visitor for TSModuleBlock nodes */
  TSModuleBlock?(node: TSESTree.TSModuleBlock): void;
  /** Visitor for TSModuleDeclaration nodes */
  TSModuleDeclaration?(node: TSESTree.TSModuleDeclaration): void;
  /** Visitor for TSNamedTupleMember nodes */
  TSNamedTupleMember?(node: TSESTree.TSNamedTupleMember): void;
  /** Visitor for TSNamespaceExportDeclaration nodes */
  TSNamespaceExportDeclaration?(node: TSESTree.TSNamespaceExportDeclaration): void;
  /** Visitor for TSNeverKeyword nodes */
  TSNeverKeyword?(node: TSESTree.TSNeverKeyword): void;
  /** Visitor for TSNonNullExpression nodes */
  TSNonNullExpression?(node: TSESTree.TSNonNullExpression): void;
  /** Visitor for TSNullKeyword nodes */
  TSNullKeyword?(node: TSESTree.TSNullKeyword): void;
  /** Visitor for TSNumberKeyword nodes */
  TSNumberKeyword?(node: TSESTree.TSNumberKeyword): void;
  /** Visitor for TSObjectKeyword nodes */
  TSObjectKeyword?(node: TSESTree.TSObjectKeyword): void;
  /** Visitor for TSOptionalType nodes */
  TSOptionalType?(node: TSESTree.TSOptionalType): void;
  /** Visitor for TSParameterProperty nodes */
  TSParameterProperty?(node: TSESTree.TSParameterProperty): void;
  /** Visitor for TSPrivateKeyword nodes */
  TSPrivateKeyword?(node: TSESTree.TSPrivateKeyword): void;
  /** Visitor for TSPropertySignature nodes */
  TSPropertySignature?(node: TSESTree.TSPropertySignature): void;
  /** Visitor for TSProtectedKeyword nodes */
  TSProtectedKeyword?(node: TSESTree.TSProtectedKeyword): void;
  /** Visitor for TSPublicKeyword nodes */
  TSPublicKeyword?(node: TSESTree.TSPublicKeyword): void;
  /** Visitor for TSQualifiedName nodes */
  TSQualifiedName?(node: TSESTree.TSQualifiedName): void;
  /** Visitor for TSReadonlyKeyword nodes */
  TSReadonlyKeyword?(node: TSESTree.TSReadonlyKeyword): void;
  /** Visitor for TSRestType nodes */
  TSRestType?(node: TSESTree.TSRestType): void;
  /** Visitor for TSStaticKeyword nodes */
  TSStaticKeyword?(node: TSESTree.TSStaticKeyword): void;
  /** Visitor for TSStringKeyword nodes */
  TSStringKeyword?(node: TSESTree.TSStringKeyword): void;
  /** Visitor for TSSymbolKeyword nodes */
  TSSymbolKeyword?(node: TSESTree.TSSymbolKeyword): void;
  /** Visitor for TSTemplateLiteralType nodes */
  TSTemplateLiteralType?(node: TSESTree.TSTemplateLiteralType): void;
  /** Visitor for TSThisType nodes */
  TSThisType?(node: TSESTree.TSThisType): void;
  /** Visitor for TSTupleType nodes */
  TSTupleType?(node: TSESTree.TSTupleType): void;
  /** Visitor for TSTypeAliasDeclaration nodes */
  TSTypeAliasDeclaration?(node: TSESTree.TSTypeAliasDeclaration): void;
  /** Visitor for TSTypeAnnotation nodes */
  TSTypeAnnotation?(node: TSESTree.TSTypeAnnotation): void;
  /** Visitor for TSTypeAssertion nodes */
  TSTypeAssertion?(node: TSESTree.TSTypeAssertion): void;
  /** Visitor for TSTypeLiteral nodes */
  TSTypeLiteral?(node: TSESTree.TSTypeLiteral): void;
  /** Visitor for TSTypeOperator nodes */
  TSTypeOperator?(node: TSESTree.TSTypeOperator): void;
  /** Visitor for TSTypeParameter nodes */
  TSTypeParameter?(node: TSESTree.TSTypeParameter): void;
  /** Visitor for TSTypeParameterDeclaration nodes */
  TSTypeParameterDeclaration?(node: TSESTree.TSTypeParameterDeclaration): void;
  /** Visitor for TSTypeParameterInstantiation nodes */
  TSTypeParameterInstantiation?(node: TSESTree.TSTypeParameterInstantiation): void;
  /** Visitor for TSTypePredicate nodes */
  TSTypePredicate?(node: TSESTree.TSTypePredicate): void;
  /** Visitor for TSTypeQuery nodes */
  TSTypeQuery?(node: TSESTree.TSTypeQuery): void;
  /** Visitor for TSTypeReference nodes */
  TSTypeReference?(node: TSESTree.TSTypeReference): void;
  /** Visitor for TSUndefinedKeyword nodes */
  TSUndefinedKeyword?(node: TSESTree.TSUndefinedKeyword): void;
  /** Visitor for TSUnionType nodes */
  TSUnionType?(node: TSESTree.TSUnionType): void;
  /** Visitor for TSUnknownKeyword nodes */
  TSUnknownKeyword?(node: TSESTree.TSUnknownKeyword): void;
  /** Visitor for TSVoidKeyword nodes */
  TSVoidKeyword?(node: TSESTree.TSVoidKeyword): void;

  // Exit handlers (called when leaving nodes)
  /** Exit handler for ArrayExpression nodes */
  'ArrayExpression:exit'?(node: TSESTree.ArrayExpression): void;
  /** Exit handler for Program nodes (commonly used for cleanup) */
  'Program:exit'?(node: TSESTree.Program): void;
  
  // Add all other exit handlers...
  [key: string]: ((node: TSESTree.Node) => void) | undefined;
}

/**
 * Descriptor for reporting rule violations
 */
interface ReportDescriptor<TMessageIds extends string> {
  /** AST node where the problem occurs */
  node: TSESTree.Node;
  /** Message ID from rule metadata */
  messageId: TMessageIds;
  /** Template data for message interpolation */
  data?: Record<string, unknown>;
  /** Specific source location (overrides node location) */
  loc?: TSESTree.SourceLocation | TSESTree.LineAndColumnData;
  /** Function to generate fix for the problem */
  fix?: ReportFixFunction;
  /** Array of suggested fixes */
  suggest?: SuggestionReportDescriptor<TMessageIds>[];
}

/**
 * Function that generates a fix for a rule violation
 */
type ReportFixFunction = (fixer: RuleFixer) => RuleFix | readonly RuleFix[];

/**
 * Interface for applying code fixes
 */
interface RuleFixer {
  /**
   * Inserts text after the given node or token
   */
  insertTextAfter(nodeOrToken: TSESTree.Node | TSESTree.Token, text: string): RuleFix;
  
  /**
   * Inserts text after the specified range
   */
  insertTextAfterRange(range: readonly [number, number], text: string): RuleFix;
  
  /**
   * Inserts text before the given node or token
   */
  insertTextBefore(nodeOrToken: TSESTree.Node | TSESTree.Token, text: string): RuleFix;
  
  /**
   * Inserts text before the specified range
   */
  insertTextBeforeRange(range: readonly [number, number], text: string): RuleFix;
  
  /**
   * Removes the given node or token
   */
  remove(nodeOrToken: TSESTree.Node | TSESTree.Token): RuleFix;
  
  /**
   * Removes text in the specified range
   */
  removeRange(range: readonly [number, number]): RuleFix;
  
  /**
   * Replaces the given node or token with text
   */
  replaceText(nodeOrToken: TSESTree.Node | TSESTree.Token, text: string): RuleFix;
  
  /**
   * Replaces text in the specified range
   */
  replaceTextRange(range: readonly [number, number], text: string): RuleFix;
}

/**
 * Individual fix operation
 */
interface RuleFix {
  /** Character range to modify */
  range: readonly [number, number];
  /** Text to insert/replace */
  text: string;
}

/**
 * Suggestion descriptor for alternative fixes
 */
interface SuggestionReportDescriptor<TMessageIds extends string> {
  /** Message ID for the suggestion */
  messageId: TMessageIds;
  /** Template data for suggestion message */
  data?: Record<string, unknown>;
  /** Function to generate the suggested fix */
  fix: ReportFixFunction;
  /** Human-readable description */
  desc?: string;
}

/**
 * Source code representation with TypeScript enhancements
 */
declare class SourceCode {
  /** Raw source text */
  readonly text: string;
  /** AST root node */
  readonly ast: TSESTree.Program;
  /** Parsed tokens */
  readonly tokens: TSESTree.Token[];
  /** Comment tokens */
  readonly comments: TSESTree.Comment[];
  /** Token and comment locations */
  readonly tokensAndComments: (TSESTree.Token | TSESTree.Comment)[];
  /** Source location mapping */
  readonly lines: string[];
  /** Scope manager instance */
  readonly scopeManager: Scope.ScopeManager;
  /** AST visitor keys */
  readonly visitorKeys: SourceCode.VisitorKeys;

  /**
   * Creates a new SourceCode instance
   */
  constructor(text: string, ast: SourceCode.Program);
  constructor(config: SourceCode.SourceCodeConfig);

  /**
   * Gets the source text for a node or range
   */
  getText(node?: TSESTree.Node): string;
  getText(node: TSESTree.Node, beforeCount: number, afterCount: number): string;

  /**
   * Gets all tokens in the source
   */
  getTokens(): TSESTree.Token[];
  getTokens(node: TSESTree.Node): TSESTree.Token[];
  getTokens(node: TSESTree.Node, options: SourceCode.CursorWithSkipOptions): TSESTree.Token[];
  getTokens(node: TSESTree.Node, beforeCount: number, afterCount: number): TSESTree.Token[];

  /**
   * Gets the first token of a node
   */
  getFirstToken(node: TSESTree.Node): TSESTree.Token | null;
  getFirstToken(node: TSESTree.Node, options: SourceCode.CursorWithSkipOptions): TSESTree.Token | null;

  /**
   * Gets the last token of a node
   */
  getLastToken(node: TSESTree.Node): TSESTree.Token | null;
  getLastToken(node: TSESTree.Node, options: SourceCode.CursorWithSkipOptions): TSESTree.Token | null;

  /**
   * Gets the token before a node or token
   */
  getTokenBefore(node: TSESTree.Node | TSESTree.Token): TSESTree.Token | null;
  getTokenBefore(node: TSESTree.Node | TSESTree.Token, options: SourceCode.CursorWithSkipOptions): TSESTree.Token | null;

  /**
   * Gets the token after a node or token
   */
  getTokenAfter(node: TSESTree.Node | TSESTree.Token): TSESTree.Token | null;
  getTokenAfter(node: TSESTree.Node | TSESTree.Token, options: SourceCode.CursorWithSkipOptions): TSESTree.Token | null;

  /**
   * Gets tokens between two nodes or tokens
   */
  getTokensBetween(left: TSESTree.Node | TSESTree.Token, right: TSESTree.Node | TSESTree.Token): TSESTree.Token[];
  getTokensBetween(left: TSESTree.Node | TSESTree.Token, right: TSESTree.Node | TSESTree.Token, padding: number): TSESTree.Token[];

  /**
   * Gets all comments
   */
  getAllComments(): TSESTree.Comment[];

  /**
   * Gets comments before a node or token
   */
  getCommentsBefore(node: TSESTree.Node | TSESTree.Token): TSESTree.Comment[];

  /**
   * Gets comments after a node or token
   */
  getCommentsAfter(node: TSESTree.Node | TSESTree.Token): TSESTree.Comment[];

  /**
   * Gets comments inside a node
   */
  getCommentsInside(node: TSESTree.Node): TSESTree.Comment[];

  /**
   * Checks if comments exist between two nodes
   */
  commentsExistBetween(left: TSESTree.Node | TSESTree.Token, right: TSESTree.Node | TSESTree.Token): boolean;

  /**
   * Checks if there's whitespace between two nodes
   */
  isSpaceBetween(left: TSESTree.Node | TSESTree.Token, right: TSESTree.Node | TSESTree.Token): boolean;

  /**
   * Gets the scope for a node
   */
  getScope(node: TSESTree.Node): Scope.Scope;

  /**
   * Marks a variable as used
   */
  markVariableAsUsed(name: string, node: TSESTree.Node): boolean;
}

declare namespace SourceCode {
  interface Program extends TSESTree.Program {
    comments: TSESTree.Comment[];
    tokens: TSESTree.Token[];
  }

  interface SourceCodeConfig {
    text: string;
    ast: Program;
  }

  type VisitorKeys = Record<string, readonly string[]>;

  type FilterPredicate = (token: TSESTree.Token) => boolean;

  interface CursorWithSkipOptions {
    skip?: number;
    includeComments?: boolean;
    filter?: FilterPredicate;
  }

  interface CursorWithCountOptions {
    count?: number;
    includeComments?: boolean;
    filter?: FilterPredicate;
  }
}

/**
 * Parser options for TypeScript files
 */
interface ParserOptions {
  /** ECMAScript version to parse */
  ecmaVersion?: EcmaVersion;
  /** Source type: module or script */
  sourceType?: 'module' | 'script';
  /** ECMAScript features */
  ecmaFeatures?: {
    globalReturn?: boolean;
    impliedStrict?: boolean;
    jsx?: boolean;
  };
  /** Path to TypeScript config file */
  project?: string | string[];
  /** TypeScript config file content */
  tsconfigRootDir?: string;
  /** Programs to use for type checking */
  programs?: unknown[];
  /** Create default program */
  createDefaultProgram?: boolean;
  /** Extra file extensions */
  extraFileExtensions?: string[];
  /** Debug level */
  debugLevel?: DebugLevel;
  /** Error on unknown AST node type */
  errorOnUnknownASTType?: boolean;
  /** Error on type script syntax in .js files */
  errorOnTypeScriptSyntacticAndSemanticIssues?: boolean;
  /** Allow invalid AST */
  allowInvalidAST?: boolean;
  /** Tokens to include */
  tokens?: boolean;
  /** Comments to include */
  comment?: boolean;
  /** Include locations */
  loc?: boolean;
  /** Include ranges */
  range?: boolean;
  /** Attach comments */
  attachComments?: boolean;
}

/**
 * ECMAScript version specification
 */
type EcmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 'latest';

/**
 * Parser debug levels
 */
type DebugLevel = boolean | ('typescript-eslint' | 'eslint' | 'typescript')[];

/**
 * Shared configuration between rules
 */
interface SharedConfigurationSettings {
  [name: string]: unknown;
}

/**
 * Linter environment configuration
 */
interface Environment {
  [name: string]: boolean;
}

namespace Linter {
  interface Environment {
    [name: string]: boolean;
  }

  interface GlobalsConfig {
    [name: string]: boolean | 'readonly' | 'writable' | 'off';
  }

  interface ProcessorConfig {
    [name: string]: unknown;
  }
}

/**
 * AST token representation
 */
namespace AST {
  interface Range extends ReadonlyArray<number> {
    0: number;
    1: number;
  }

  interface SourceLocation {
    start: Position;
    end: Position;
  }

  interface Position {
    /** 1-based line number */
    line: number;
    /** 0-based column number */
    column: number;
  }

  interface Token {
    type: string;
    value: string;
    range: Range;
    loc: SourceLocation;
  }

  type TokenType = 
    | 'Boolean'
    | 'Null' 
    | 'Identifier'
    | 'Keyword'
    | 'Punctuator'
    | 'Numeric'
    | 'String'
    | 'RegularExpression'
    | 'Template'
    | 'JSXIdentifier'
    | 'JSXText'
    | 'Block'
    | 'Line';
}