AST Utilities

/**
 * Simple AST traversal utility with visitor pattern support
 * @param startingNode - ESTree node to start traversal from
 * @param options - Visitor configuration with enter function or specific visitors
 * @param setParentPointers - Whether to set parent pointers during traversal
 */
function simpleTraverse(
  startingNode: TSESTree.Node,
  options: SimpleTraverseOptions,
  setParentPointers?: boolean
): void;

/**
 * Configuration for simple traversal with enter function
 */
interface SimpleTraverseEnterOptions {
  enter: (node: TSESTree.Node, parent: TSESTree.Node | undefined) => void;
  visitorKeys?: Readonly<VisitorKeys>;
}

/**
 * Configuration for simple traversal with specific node visitors
 */
interface SimpleTraverseVisitorOptions {
  visitors: Record<string, (node: TSESTree.Node, parent: TSESTree.Node | undefined) => void>;
  visitorKeys?: Readonly<VisitorKeys>;
}

type SimpleTraverseOptions = SimpleTraverseEnterOptions | SimpleTraverseVisitorOptions;

import { simpleTraverse, parse } from "@typescript-eslint/typescript-estree";

const ast = parse('const x = 42; function foo() { return x; }');

// Traverse with enter function
simpleTraverse(ast, {
  enter(node, parent) {
    console.log(`Visiting ${node.type}`);
    if (node.type === 'Identifier') {
      console.log(`  Identifier: ${node.name}`);
    }
  }
});

// Traverse with specific visitors
simpleTraverse(ast, {
  visitors: {
    VariableDeclaration(node) {
      console.log('Found variable declaration');
    },
    FunctionDeclaration(node) {
      console.log(`Found function: ${node.id?.name}`);
    }
  }
});

/**
 * Gets TypeScript modifiers from a node with version compatibility
 * @param node - TypeScript node to inspect
 * @param includeIllegalModifiers - Whether to include illegal modifiers
 * @returns Array of modifier nodes or undefined
 */
function getModifiers(
  node: ts.Node | null | undefined,
  includeIllegalModifiers?: boolean
): ts.Modifier[] | undefined;

/**
 * Gets TypeScript decorators from a node with version compatibility
 * @param node - TypeScript node to inspect
 * @param includeIllegalDecorators - Whether to include illegal decorators
 * @returns Array of decorator nodes or undefined
 */
function getDecorators(
  node: ts.Node | null | undefined,
  includeIllegalDecorators?: boolean
): ts.Decorator[] | undefined;

/**
 * Checks if a TypeScript node has a specific modifier
 * @param modifierKind - TypeScript modifier kind to check for
 * @param node - TypeScript node to inspect
 * @returns True if modifier is present
 */
function hasModifier(modifierKind: ts.KeywordSyntaxKind, node: ts.Node): boolean;

/**
 * Gets the last modifier from a TypeScript node
 * @param node - TypeScript node to inspect
 * @returns Last modifier or null if none
 */
function getLastModifier(node: ts.Node): ts.Modifier | null;

import { getModifiers, getDecorators, hasModifier } from "@typescript-eslint/typescript-estree";

// Inspect TypeScript nodes (typically used with parser services)
const result = parseAndGenerateServices(code, { project: './tsconfig.json' });
const tsNode = result.services.esTreeNodeToTSNodeMap.get(someESTreeNode);

if (tsNode) {
  // Get modifiers
  const modifiers = getModifiers(tsNode);
  console.log('Modifiers:', modifiers?.map(m => ts.SyntaxKind[m.kind]));
  
  // Check for specific modifiers
  const isPublic = hasModifier(ts.SyntaxKind.PublicKeyword, tsNode);
  const isStatic = hasModifier(ts.SyntaxKind.StaticKeyword, tsNode);
  
  // Get decorators
  const decorators = getDecorators(tsNode);
  console.log('Decorators:', decorators?.length);
}

/**
 * Gets the string representation of a TypeScript token kind
 * @param kind - TypeScript SyntaxKind
 * @returns String representation of the token
 */
function getTextForTokenKind<T extends ts.SyntaxKind>(kind: T): string | undefined;

/**
 * Determines if a TypeScript token is a logical operator
 * @param operator - Binary operator token
 * @returns True if logical operator (&&, ||, ??)
 */
function isLogicalOperator(operator: ts.BinaryOperatorToken): boolean;

/**
 * Determines if a TypeScript token is an ESTree binary operator
 * @param operator - Binary operator token  
 * @returns True if valid ESTree binary operator
 */
function isESTreeBinaryOperator(operator: ts.BinaryOperatorToken): boolean;

/**
 * Gets the binary expression type and operator for a TypeScript token
 * @param operator - Binary operator token
 * @returns Object with expression type and operator string
 */
function getBinaryExpressionType(operator: ts.BinaryOperatorToken): {
  type: AST_NODE_TYPES.AssignmentExpression | AST_NODE_TYPES.BinaryExpression | AST_NODE_TYPES.LogicalExpression;
  operator: string;
};

import { 
  getTextForTokenKind,
  isLogicalOperator,
  getBinaryExpressionType
} from "@typescript-eslint/typescript-estree";

// Get token text
const plusText = getTextForTokenKind(ts.SyntaxKind.PlusToken); // "+"
const equalsText = getTextForTokenKind(ts.SyntaxKind.EqualsToken); // "="

// Check operator types (used internally during AST conversion)
// These would typically be used with TypeScript's AST nodes

/**
 * Gets line and character information for a position in source file
 * @param pos - Character position in source
 * @param ast - TypeScript source file
 * @returns Position object with line and column (1-based line)
 */
function getLineAndCharacterFor(pos: number, ast: ts.SourceFile): TSESTree.Position;

/**
 * Gets source location information for a range
 * @param range - Start and end positions
 * @param ast - TypeScript source file
 * @returns Source location with start and end positions
 */
function getLocFor(range: TSESTree.Range, ast: ts.SourceFile): TSESTree.SourceLocation;

/**
 * Gets the range (start and end positions) for a TypeScript node
 * @param node - TypeScript node with getStart and getEnd methods
 * @param ast - TypeScript source file
 * @returns Tuple of start and end positions
 */
function getRange(node: Pick<ts.Node, 'getStart' | 'getEnd'>, ast: ts.SourceFile): [number, number];

/**
 * Determines if a TypeScript node is a valid ESTree class member
 * @param node - TypeScript node to check
 * @returns True if valid class member (not semicolon element)
 */
function isESTreeClassMember(node: ts.Node): boolean;

/**
 * Determines if a TypeScript node is a comment
 * @param node - TypeScript node to check
 * @returns True if single-line or multi-line comment
 */
function isComment(node: ts.Node): boolean;

/**
 * Determines if a TypeScript node is a JSX token
 * @param node - TypeScript node to check
 * @returns True if JSX-related token
 */
function isJSXToken(node: ts.Node): boolean;

/**
 * Determines if a TypeScript node is a computed property name
 * @param node - TypeScript node to check
 * @returns True if computed property name
 */
function isComputedProperty(node: ts.Node): boolean;

/**
 * Determines if a node is optional (has question token)
 * @param node - Node with optional question token
 * @returns True if has question token
 */
function isOptional(node: { questionToken?: ts.QuestionToken }): boolean;

/**
 * Object containing boolean flags for TypeScript version compatibility
 * Versions: 4.7, 4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4
 */
const typescriptVersionIsAtLeast: Record<
  '4.7' | '4.8' | '4.9' | '5.0' | '5.1' | '5.2' | '5.3' | '5.4',
  boolean
>;

import { typescriptVersionIsAtLeast } from "@typescript-eslint/typescript-estree";

// Check TypeScript version compatibility
if (typescriptVersionIsAtLeast['4.8']) {
  // Use TypeScript 4.8+ features
  console.log('TypeScript 4.8+ features available');
}

if (typescriptVersionIsAtLeast['5.3']) {
  // Use JSDoc parsing mode features
  console.log('JSDoc parsing mode available');
}

/**
 * Custom error class for TypeScript parsing errors with location information
 */
class TSError extends Error {
  constructor(
    message: string,
    public readonly fileName: string,
    public readonly location: {
      start: { line: number; column: number; offset: number };
      end: { line: number; column: number; offset: number };
    }
  );
  
  /** Legacy ESLint compatibility property */
  get index(): number;
  /** Legacy ESLint compatibility property */  
  get lineNumber(): number;
  /** Legacy ESLint compatibility property */
  get column(): number;
}

/**
 * Creates a TSError with location information
 * @param message - Error message
 * @param ast - Source file for location calculation
 * @param startIndex - Start position of error
 * @param endIndex - End position of error (defaults to startIndex)
 * @returns TSError instance with location information
 */
function createError(
  message: string,
  ast: ts.SourceFile,
  startIndex: number,
  endIndex?: number
): TSError;

// Position and location types
interface Position {
  line: number;
  column: number;
}

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

type Range = [number, number];

// Visitor keys for traversal
interface VisitorKeys {
  [nodeType: string]: readonly string[];
}

// Token and node classification types
type LogicalOperatorKind = 
  | ts.SyntaxKind.AmpersandAmpersandToken
  | ts.SyntaxKind.BarBarToken
  | ts.SyntaxKind.QuestionQuestionToken;

type BinaryOperatorKind = keyof TSESTree.BinaryOperatorToText;
type AssignmentOperatorKind = keyof TSESTree.AssignmentOperatorToText;