/**
 * Primary orchestrator and CLI configuration API for Lupa tests.
 *
 * @packageDocumentation
 * @module @pawel-up/lupa/runner
 */
import type { Config, CLIArgs } from './types.js';
export type * from './types.js';
import type { ProgrammaticReporterContract } from '../types.js';
export { loadLupaConfig } from './config_loader.js';
export type { Config, NormalizedConfig, CLIArgs, JsonSerializable } from './types.js';
/**
 * Define Lupa configuration.
 *
 * This is an identity function that provides TypeScript autocomplete and type-checking
 * for your `lupa.config.ts` file. It does not mutate state or hydrate the configuration.
 *
 * @example
 * ```ts
 * import { defineConfig } from '@pawel-up/lupa/runner'
 *
 * export default defineConfig({
 *   files: ['tests/**\/*.spec.ts'],
 *   testPlugins: ['@pawel-up/lupa/assert']
 * })
 * ```
 *
 * @param config Lupa configuration object
 * @returns Unmodified Lupa configuration object
 */
export declare function defineConfig(config: Config): Config;
/**
 * Configure the Lupa test runner.
 *
 * This function hydrates the provided configuration options and merges them with parsed CLI arguments.
 *
 * **Note:** If you are using the standard `npx lupa test` CLI, you do not need to call this manually.
 * The CLI automatically loads your `lupa.config.ts` and calls `configure()` for you.
 * This function is exposed primarily for advanced users building custom integrations or programmatic runners.
 *
 * You must call this function before calling {@link run}.
 *
 * @category Configuration
 * @useWhen Building a programmatic test runner or custom CLI integration.
 * @avoidWhen You are already inside a running test or suite.
 *
 * @param options - The configuration object. You must provide either a top-level `files` array
 *                  or a `suites` array to define your test files.
 * @param args - Optional CLI arguments to override configuration.
 *
 * @example
 * **Basic Configuration**
 * ```ts
 * import { configure, run } from '@pawel-up/lupa/runner'
 *
 * configure({
 *   files: ['tests/**\/*.spec.ts'],
 *   testPlugins: ['@pawel-up/lupa/assert']
 * })
 *
 * run()
 * ```
 *
 * @example
 * **Using Test Suites**
 * ```ts
 * import { configure, run } from '@pawel-up/lupa/runner'
 *
 * configure({
 *   suites: [
 *     { name: 'components', files: ['tests/components/**\/*.spec.ts'] },
 *     { name: 'e2e', files: ['tests/e2e/**\/*.spec.ts'] }
 *   ],
 *   timeout: 5000,
 * })
 *
 * run()
 * ```
 */
export declare function configure(options: Config, args?: CLIArgs): void;
/**
 * Run the test suite.
 *
 * This is the primary entry point for running your tests. It uses the configuration
 * provided by {@link configure}.
 *
 * @returns A Promise that resolves when the test run is complete,
 *          or rejects if the test run encounters an error (e.g., uncaught exceptions).
 *
 * @category Execution
 * @never NEVER call this inside a test suite or hook. Fix: Call it only once at the end of your execution script.
 * @throws {Error} Throws if configuration is missing or invalid.
 *
 * @example
 * ```ts
 * import { configure, run } from '@pawel-up/lupa/runner'
 *
 * configure({
 *   files: ['tests/**\/*.spec.ts'],
 * })
 *
 * run()
 * ```
 */
export declare function run(): Promise<void>;
/**
 * Run Lupa programmatically and return the typed output of the given programmatic reporter.
 * This execution path does not intercept standard process signals and avoids `process.exit()`.
 *
 * @example
 * ```ts
 * import { runProgrammatic } from '@pawel-up/lupa/runner'
 * import { json } from '@pawel-up/lupa/reporters'
 *
 * const result = await runProgrammatic(json())
 * ```
 */
export declare function runProgrammatic<T>(reporter: ProgrammaticReporterContract<T>, options?: Partial<Config>): Promise<T>;