type RunnerStates = 'afterAll' | 'beforeAll' | 'beginUrl' | 'urlResults';

export type RunnerState = {
  state: RunnerStates;
  url: string;
};

export type Runner = {
  /**
   * Get the current state (state, url).
   *
   * @instance
   * @returns The current runner state.
   * @public
   */
  getCurrentState(): RunnerState;

  /**
   * Get the next state (state, url).
   *
   * @instance
   * @returns The next runner state.
   * @public
   */
  getNextState(): RunnerState;

  /**
   * Resets the runner and reporter to the initial states.
   *
   * @instance
   * @async
   * @public
   */
  reset(): void;

  /**
   * Executes the entire Pa11y CI sequence, calling all reporter functions.
   *
   * @instance
   * @async
   * @public
   */
  runAll(): void;

  /**
   * Executes the next event in the Pa11y CI sequence, calling the
   * appropriate reporter function.
   *
   * @instance
   * @async
   * @public
   */
  runNext(): void;

  /**
   * Executes the entire Pa11y CI sequence, calling all reporter functions,
   * until the specified current state and optional URL are reached. If a URL is not
   * specified, the run completes on the first occurrence of the target state.
   *
   * @instance
   * @param targetState The target state to run to.
   * @param targetUrl The target URL to run to.
   * @async
   * @public
   */
  runUntil(state: RunnerStates, url?: string): void;

  /**
   * Executes the entire Pa11y CI sequence, calling all reporter functions,
   * until the specified next state and optional URL are reached. If a URL is not
   * specified, the run completes on the first occurrence of the target state.
   *
   * @instance
   * @param targetState The target state to run to.
   * @param targetUrl The target URL to run to.
   * @async
   * @public
   */
  runUntilNext(state: RunnerStates, url?: string): void;
};

/**
 * Factory to create a pa11y-ci reporter runner that can execute
 * a reporter with the specified pa11y-ci JSON results file.
 *
 * @param   resultsFileName Pa11y CI JSON results file.
 * @param   reporterName    Name of the reporter to execute (module or path).
 * @param   options         The reporter options.
 * @param   config          The Pa11y CI configuration.
 * @returns                 A Pa11y CI reporter runner.
 * @static
 * @public
 */
export function createRunner(
  resultsFileName: string,
  reporterName: string,
  options?: object,
  config?: object
): Runner;