test(utils): remove unused items, add docs remove export for internal…

… items, deprecate `test` function

test/utils.ts

@@ -7,7 +7,6 @@ import type {
 import type { TSESTree } from '@typescript-eslint/utils'
 import type { RuleModule } from '@typescript-eslint/utils/ts-eslint'
 import type { RuleTester } from 'eslint'
-import eslintPkg from 'eslint/package.json'
 import semver from 'semver'
 import typescriptPkg from 'typescript/package.json'
 
@@ -46,30 +45,16 @@ export function getNonDefaultParsers() {
 
 export const TEST_FILENAME = testFilePath()
 
-export function eslintVersionSatisfies(specifier: string) {
-  return semver.satisfies(eslintPkg.version, specifier)
-}
-
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- simplify testing
 export type ValidTestCase = TSESLintValidTestCase<any> & {
   errors?: readonly InvalidTestCaseError[] | number
   parser?: never
   parserOptions?: never
 }
 
-export type InvalidTestCase = // eslint-disable-next-line @typescript-eslint/no-explicit-any -- simplify testing
+type InvalidTestCase = // eslint-disable-next-line @typescript-eslint/no-explicit-any -- simplify testing
   TSESLintInvalidTestCase<any, any>
 
-export function testVersion<T extends ValidTestCase>(
-  specifier: string,
-  t: () => T,
-): T extends { errors: readonly InvalidTestCaseError[] }
-  ? InvalidTestCase[]
-  : ValidTestCase[] {
-  // @ts-expect-error -- simplify testing
-  return eslintVersionSatisfies(specifier) ? [test(t())] : []
-}
-
 /** @warning DO NOT EXPORT THIS. use {@link createRuleTestCaseFunction} or {@link test} instead */
 function createRuleTestCase<TTestCase extends TSESLintValidTestCase<unknown[]>>(
   t: TTestCase,
@@ -95,6 +80,7 @@ export type InvalidTestCaseError =
       type?: `${TSESTree.AST_NODE_TYPES}`
     })
 
+/** @deprecated use {@link createRuleTestCaseFunction} */
 // eslint-disable-next-line eslint-plugin/require-meta-docs-description, eslint-plugin/require-meta-type, eslint-plugin/prefer-message-ids, eslint-plugin/prefer-object-rule, eslint-plugin/require-meta-schema
 export function test<T extends ValidTestCase>(
   t: T,
@@ -105,17 +91,42 @@ export function test<T extends ValidTestCase>(
   return createRuleTestCase(t)
 }
 
-type GetRuleType<TRule> =
+type GetRuleModuleTypes<TRule> =
   TRule extends RuleModule<infer MessageIds, infer Options>
     ? {
         messageIds: MessageIds
         options: Options
       }
     : never
 
+/**
+ * Create a function that can be used to create both valid and invalid test case
+ * to be provided to {@link TSESLintRuleTester}.
+ * This function accepts one type parameter that should extend a {@link RuleModule}
+ * to be able to provide a function with typed `MessageIds` and `Options` properties
+ *
+ * @example
+ * ```ts
+ * import { createRuleTestCaseFunction } from '../utils'
+ *
+ * const test = createRuleTestCaseFunction<typeof rule>()
+ *
+ * const ruleTester = new TSESLintRuleTester()
+ *
+ * ruleTester.run(`no-useless-path-segments (${resolver})`, rule, {
+ *  valid: [
+ *    test({
+ *      code: '...',
+ *    }),
+ *  ]
+ * })
+ * ```
+ *
+ * If the `TRule` parameter is omitted default types are used.
+ */
 export function createRuleTestCaseFunction<
   TRule extends RuleModule<string, unknown[]>,
-  TData extends GetRuleType<TRule> = GetRuleType<TRule>,
+  TData extends GetRuleModuleTypes<TRule> = GetRuleModuleTypes<TRule>,
   TTestCase extends
     | TSESLintValidTestCase<TData['options']>
     | TSESLintInvalidTestCase<TData['messageIds'], TData['options']> =
@@ -206,6 +217,6 @@ export const SYNTAX_CASES = [
   }),
 ]
 
-export const testCompiled = process.env.TEST_COMPILED === '1'
+const testCompiled = process.env.TEST_COMPILED === '1'
 
 export const srcDir = testCompiled ? 'lib' : 'src'