import type { TtscLintRuleSetting } from "../TtscLintRuleSetting";

/**
 * Vitest test source rules from `@vitest/eslint-plugin`.
 *
 * Vitest reuses much of Jest's testing surface but ships its own runner and
 * configuration. These rules mirror the ergonomic subset of
 * `eslint-plugin-jest` adapted for Vitest semantics — focused tests, identical
 * titles, conditional logic, valid `expect` shape.
 *
 * @reference https://github.com/vitest-dev/eslint-plugin-vitest
 *
 * @evidence contracts/common.md#principled-implementation Optional vitest keys represent independent runner policies through severity-only settings, retaining a distinct namespace despite shared Jest-style source syntax.
 * @evidence contracts/common.md#clear-and-simple-design One map groups Vitest test-source concerns and reuses the common severity union without coupling it to the Jest family type.
 * @evidence contracts/common.md#prohibited-implementation-shortcuts The declared Vitest policy names are public configuration entries rather than production branches introduced solely for this repository's tests.
 * @evidence contracts/common.md#meaningful-documentation Native family prose identifies Vitest and member comments explain collection, assertion and callback concerns; paragraph and member separation follow documentation guidance.
 */
export interface ITtscLintVitestRules {
  /**
   * Require every Vitest test body to contain at least one `expect(...)` call.
   * A test with no assertions still passes, giving a false-positive signal.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/expect-expect.md
   */
  "vitest/expect-expect"?: TtscLintRuleSetting;

  /**
   * Reject recognized `expect(...)` calls in conditional or loop syntax inside
   * test callbacks. The native conditional-kind set does not include
   * try/catch.
   *
   * A branch that never runs turns the assertion into a silent no-op rather
   * than a failure.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-conditional-expect.md
   */
  "vitest/no-conditional-expect"?: TtscLintRuleSetting;

  /**
   * Reject `test(...)`/`it(...)` declarations inside loops or `if` branches.
   *
   * Vitest collects tests at module load, so a conditional declaration produces
   * a different suite shape than the file appears to describe.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-conditional-tests.md
   */
  "vitest/no-conditional-tests"?: TtscLintRuleSetting;

  /**
   * Reject `test.skip`, `it.skip`, `describe.skip`, and `.todo` variants.
   *
   * Disabled tests rot in place and quietly drop coverage for the feature they
   * were meant to pin.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-disabled-tests.md
   */
  "vitest/no-disabled-tests"?: TtscLintRuleSetting;

  /**
   * Reject any first callback parameter in recognized Vitest tests and hooks,
   * regardless of whether its name is `done`.
   *
   * The callback style predates async/await and makes failure propagation easy
   * to miss; return a Promise or mark the body `async` instead.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-done-callback.md
   */
  "vitest/no-done-callback"?: TtscLintRuleSetting;

  /**
   * Reject `test.only`, `it.only`, and `describe.only`.
   *
   * A focused suite silently skips the rest of the file, so a stray `.only`
   * left from debugging hides every other test in CI.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-focused-tests.md
   */
  "vitest/no-focused-tests"?: TtscLintRuleSetting;

  /**
   * Reject duplicate Vitest test or `describe` titles within the same suite
   * scope.
   *
   * The runner cannot disambiguate two siblings with identical names in its
   * error output or filter flags.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-identical-title.md
   */
  "vitest/no-identical-title"?: TtscLintRuleSetting;

  /**
   * Reject `expect(...)` calls outside Vitest tests and hooks.
   *
   * Top-level assertions execute at module load before any test starts, so
   * failures never attach to a named case.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-standalone-expect.md
   */
  "vitest/no-standalone-expect"?: TtscLintRuleSetting;

  /**
   * Reject explicit return statements in recognized Vitest test callbacks,
   * including bare returns and returned Promises; return types are not
   * inferred.
   *
   * The rule is an AST source policy and does not execute runner completion.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-test-return-statement.md
   */
  "vitest/no-test-return-statement"?: TtscLintRuleSetting;

  /**
   * Prefer `expect(value).toHaveLength(n)` over asserting on `value.length`
   * with `toBe`.
   *
   * The dedicated matcher reports the actual length on failure instead of a
   * bare number mismatch.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/prefer-to-have-length.md
   */
  "vitest/prefer-to-have-length"?: TtscLintRuleSetting;

  /**
   * Validate the shape of Vitest `describe` callbacks.
   *
   * The native check requires a function callback without an async modifier. It
   * does not validate parameter count or infer returned Promise types.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/valid-describe-callback.md
   */
  "vitest/valid-describe-callback"?: TtscLintRuleSetting;

  /**
   * Require at least one `expect(...)` argument and a terminating matcher call,
   * permitting `not`, `resolves`, and `rejects` property links. The native
   * check does not impose a maximum arity or validate asynchronous handling.
   *
   * Malformed expects either throw at runtime or pass without asserting
   * anything.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/valid-expect.md
   */
  "vitest/valid-expect"?: TtscLintRuleSetting;

  /**
   * Require non-empty static Vitest test and `describe` titles.
   *
   * Empty or dynamically-built titles produce unreadable failure output and
   * break filter-by-name flags.
   *
   * @reference https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/valid-title.md
   */
  "vitest/valid-title"?: TtscLintRuleSetting;
}