/**
 * Plugin discovery for Node.js environments.
 *
 * @remarks
 * This module provides functionality to discover change-detector plugins
 * from node_modules directories. It scans for packages with specific keywords
 * and loads them dynamically.
 *
 * **Note:** This module uses Node.js APIs (fs, path) and will only work in
 * Node.js environments. In browser environments, plugins must be registered
 * manually using the registry.
 */
import type { ChangeDetectorPlugin } from './plugin-types';
/**
 * Options for plugin discovery.
 *
 * @alpha
 */
export interface PluginDiscoveryOptions {
    /**
     * Directories to scan for node_modules.
     * Defaults to current working directory.
     */
    readonly searchPaths?: readonly string[];
    /**
     * Include legacy input-processor-plugin keyword in search.
     * Defaults to true for backward compatibility.
     */
    readonly includeLegacy?: boolean;
    /**
     * Optional filter to include only specific plugin package names.
     * If provided, only packages matching these names will be loaded.
     */
    readonly packageNames?: readonly string[];
    /**
     * Whether to validate plugins after loading.
     * Defaults to true.
     */
    readonly validate?: boolean;
    /**
     * Custom logger for discovery progress and errors.
     * Defaults to console.warn for errors.
     */
    readonly logger?: PluginDiscoveryLogger;
}
/**
 * Logger interface for discovery operations.
 *
 * @alpha
 */
export interface PluginDiscoveryLogger {
    /**
     * Log debug information.
     */
    debug?(message: string): void;
    /**
     * Log warnings (non-fatal issues).
     */
    warn(message: string): void;
    /**
     * Log errors (fatal issues for individual plugins).
     */
    error(message: string): void;
}
/**
 * Information about a discovered plugin package before loading.
 *
 * @alpha
 */
export interface PluginPackageInfo {
    /**
     * Package name from package.json.
     */
    readonly packageName: string;
    /**
     * Package version from package.json.
     */
    readonly packageVersion: string;
    /**
     * Absolute path to the package directory.
     */
    readonly packagePath: string;
    /**
     * Keywords from package.json that matched our search.
     */
    readonly keywords: readonly string[];
    /**
     * Whether this package uses the legacy keyword.
     */
    readonly isLegacy: boolean;
    /**
     * Main entry point from package.json (resolved).
     */
    readonly main?: string;
}
/**
 * Result of loading a discovered plugin.
 *
 * @alpha
 */
export interface LoadedPlugin {
    /**
     * Package information.
     */
    readonly package: PluginPackageInfo;
    /**
     * The loaded and validated plugin instance.
     */
    readonly plugin: ChangeDetectorPlugin;
    /**
     * Whether this was a legacy plugin that was normalized.
     */
    readonly isLegacy: boolean;
}
/**
 * Error that occurred during plugin discovery or loading.
 *
 * @alpha
 */
export interface PluginDiscoveryError {
    /**
     * Package name (if known).
     */
    readonly packageName?: string;
    /**
     * Package path (if known).
     */
    readonly packagePath?: string;
    /**
     * Error message.
     */
    readonly message: string;
    /**
     * Original error (if any).
     */
    readonly cause?: Error;
}
/**
 * Result of plugin discovery operation.
 *
 * @alpha
 */
export interface PluginDiscoveryResult {
    /**
     * Successfully loaded plugins.
     */
    readonly plugins: readonly LoadedPlugin[];
    /**
     * Errors that occurred during discovery (non-fatal).
     */
    readonly errors: readonly PluginDiscoveryError[];
    /**
     * Package info for packages that were found but not loaded.
     */
    readonly skipped: readonly PluginPackageInfo[];
}
/**
 * Discovers and loads change-detector plugins from node_modules.
 *
 * @remarks
 * This function scans node_modules directories for packages with the
 * `change-detector:plugin` or `change-detector:input-processor-plugin` keywords,
 * loads them dynamically, validates them, and returns the results.
 *
 * **Node.js Only:** This function requires Node.js APIs and will throw
 * an error if called in a browser environment.
 *
 * @param options - Discovery options
 * @returns Discovery result with loaded plugins and any errors
 *
 * @example
 * ```typescript
 * import { discoverPlugins } from '@api-extractor-tools/change-detector-core';
 *
 * const result = await discoverPlugins();
 * for (const { plugin, package: pkg } of result.plugins) {
 *   console.log(`Loaded ${pkg.packageName}@${pkg.packageVersion}`);
 *   registry.register(plugin);
 * }
 *
 * if (result.errors.length > 0) {
 *   console.warn('Some plugins failed to load:', result.errors);
 * }
 * ```
 *
 * @alpha
 */
export declare function discoverPlugins(options?: PluginDiscoveryOptions): Promise<PluginDiscoveryResult>;
/**
 * Discovers plugin packages without loading them.
 *
 * @remarks
 * Use this function when you need to list available plugins without
 * actually loading their code. This is faster and useful for displaying
 * available plugins to users.
 *
 * @param options - Discovery options (packageNames and validate are ignored)
 * @returns Array of discovered package info
 *
 * @alpha
 */
export declare function scanForPlugins(options?: Pick<PluginDiscoveryOptions, 'searchPaths' | 'includeLegacy' | 'logger'>): Promise<PluginPackageInfo[]>;
//# sourceMappingURL=plugin-discovery.d.ts.map