Plugin System

/**
 * Base plugin configuration provided to all plugins
 */
interface PluginOptions {
  /** Input file system */
  inputFS: FileSystem;
  /** Output file system */
  outputFS: FileSystem;
  /** Build cache */
  cache: Cache;
  /** Plugin logger */
  logger: PluginLogger;
  /** Package manager */
  packageManager: PackageManager;
  /** Worker farm for parallel processing */
  workerFarm: WorkerFarm;
  /** Performance tracer */
  tracer: PluginTracer;
  /** Build mode */
  mode: BuildMode;
  /** Environment variables */
  env: EnvMap;
  /** Feature flags */
  featureFlags: FeatureFlags;
  /** Hot module replacement port */
  hmrPort?: number;
  /** Whether HMR is enabled */
  hmrOptions?: HMROptions;
  /** Development server options */
  serveOptions?: ServerOptions;
}

/**
 * Plugin logger interface
 */
interface PluginLogger {
  /** Log verbose information */
  verbose(message: string): void;
  /** Log informational message */
  info(message: string): void;
  /** Log general message */
  log(message: string): void;
  /** Log warning message */
  warn(message: string): void;
  /** Log error message */
  error(message: string): void;
}

/**
 * Performance tracing interface
 */
interface PluginTracer {
  /** Create a performance measurement */
  createMeasurement(name: string, category?: string): TraceMeasurement;
}

/**
 * Performance measurement interface
 */
interface TraceMeasurement {
  /** End the measurement */
  end(): void;
}

/**
 * Transformer plugin interface
 */
interface Transformer<ConfigType = any> {
  /** Load configuration for this transformer */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Check if AST can be reused from previous transformation */
  canReuseAST?(opts: {
    ast: AST;
    options: PluginOptions;
  }): boolean;
  
  /** Parse source code into AST */
  parse?(opts: {
    asset: MutableAsset;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<AST> | AST;
  
  /** Transform the asset */
  transform(opts: {
    asset: MutableAsset;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<Array<TransformerResult>> | Array<TransformerResult>;
  
  /** Post-process after all transformations */
  postProcess?(opts: {
    assets: Array<MutableAsset>;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<Array<TransformerResult>> | Array<TransformerResult>;
  
  /** Generate final code from AST */
  generate?(opts: {
    asset: Asset;
    ast: AST;
    options: PluginOptions;
  }): Promise<GenerateOutput> | GenerateOutput;
}

/**
 * Transformer result type
 */
type TransformerResult = MutableAsset | Asset;

/**
 * Code generation output
 */
interface GenerateOutput {
  /** Generated code */
  content: string;
  /** Source map */
  map?: SourceMap;
}

/**
 * Resolver plugin interface
 */
interface Resolver<ConfigType = any> {
  /** Load configuration for this resolver */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Resolve a dependency to a file path */
  resolve(opts: {
    dependency: Dependency;
    options: PluginOptions;
    config: ConfigType;
    specifier: DependencySpecifier;
    pipeline: ?string;
  }): Promise<?ResolveResult> | ?ResolveResult;
}

/**
 * Resolution result
 */
interface ResolveResult {
  /** Resolved file path */
  filePath?: FilePath;
  /** Asset pipeline to use */
  pipeline?: string;
  /** Invalidation dependencies */
  invalidateOnFileChange?: Array<FilePath>;
  /** Invalidation on file creation */
  invalidateOnFileCreate?: Array<FileCreateInvalidation>;
  /** Environment variable invalidations */
  invalidateOnEnvChange?: Array<string>;
  /** Side effects information */
  sideEffects?: boolean;
  /** Code information */
  code?: string;
  /** Query string */
  query?: URLSearchParams;
  /** Asset priority */
  priority?: DependencyPriority;
}

/**
 * Bundler plugin interface
 */
interface Bundler<ConfigType = any> {
  /** Load configuration for this bundler */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Create bundles from the asset graph */
  bundle(opts: {
    bundleGraph: MutableBundleGraph;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<void> | void;
  
  /** Optimize bundles after creation */
  optimize?(opts: {
    bundleGraph: MutableBundleGraph;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<void> | void;
}

/**
 * Namer plugin interface
 */
interface Namer<ConfigType = any> {
  /** Load configuration for this namer */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Generate name for a bundle */
  name(opts: {
    bundle: Bundle;
    bundleGraph: BundleGraph<NamedBundle>;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<?string> | ?string;
}

/**
 * Runtime plugin interface
 */
interface Runtime<ConfigType = any> {
  /** Load configuration for this runtime */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Apply runtime modifications to bundle */
  apply(opts: {
    bundle: NamedBundle;
    bundleGraph: BundleGraph<NamedBundle>;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<void | RuntimeAsset> | void | RuntimeAsset;
}

/**
 * Runtime asset for injection
 */
interface RuntimeAsset {
  /** Runtime code */
  code: string;
  /** Asset type */
  filePath: FilePath;
  /** Environment */
  env?: Environment;
  /** Dependencies */
  dependency?: Dependency;
}

/**
 * Packager plugin interface
 */
interface Packager<ConfigType = any, BundleConfigType = any> {
  /** Load configuration for this packager */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Load bundle-specific configuration */
  loadBundleConfig?(opts: {
    bundle: NamedBundle;
    bundleGraph: BundleGraph<NamedBundle>;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<BundleConfigType> | BundleConfigType;
  
  /** Package the bundle */
  package(opts: {
    bundle: NamedBundle;
    bundleGraph: BundleGraph<NamedBundle>;
    getInlineBundleContents: (bundle: Bundle, bundleGraph: BundleGraph<NamedBundle>) => Promise<{contents: Blob}>;
    getSourceMapReference: (map: ?SourceMap) => Promise<?string>;
    config: ConfigType;
    bundleConfig: BundleConfigType;
    options: PluginOptions;
  }): Promise<BundleResult> | BundleResult;
}

/**
 * Bundle packaging result
 */
interface BundleResult {
  /** Bundle contents */
  contents: Blob;
  /** Source map */
  map?: SourceMap;
}

/**
 * Optimizer plugin interface
 */
interface Optimizer<ConfigType = any, BundleConfigType = any> {
  /** Load configuration for this optimizer */
  loadConfig?(opts: {
    config: Config;
    options: PluginOptions;
  }): Promise<ConfigType> | ConfigType;
  
  /** Load bundle-specific configuration */
  loadBundleConfig?(opts: {
    bundle: NamedBundle;
    bundleGraph: BundleGraph<NamedBundle>;
    config: ConfigType;
    options: PluginOptions;
  }): Promise<BundleConfigType> | BundleConfigType;
  
  /** Optimize the bundle */
  optimize(opts: {
    bundle: NamedBundle;
    bundleGraph: BundleGraph<NamedBundle>;
    contents: Blob;
    map?: SourceMap;
    config: ConfigType;
    bundleConfig: BundleConfigType;
    options: PluginOptions;
  }): Promise<BundleResult> | BundleResult;
}

/**
 * Compressor plugin interface
 */
interface Compressor {
  /** Compress bundle contents */
  compress(opts: {
    stream: Readable;
    options: PluginOptions;
  }): Promise<Readable> | Readable;
}

/**
 * Single-threaded validator plugin
 */
interface DedicatedThreadValidator {
  /** Validate an asset */
  validate(opts: {
    asset: Asset;
    options: PluginOptions;
    config: any;
  }): Promise<ValidateResult> | ValidateResult;
}

/**
 * Multi-threaded validator plugin
 */
interface MultiThreadValidator {
  /** Validate multiple assets */
  validateAll(opts: {
    assets: Array<Asset>;
    options: PluginOptions;
    config: any;
  }): Promise<Array<ValidateResult>> | Array<ValidateResult>;
}

/**
 * Validator result
 */
interface ValidateResult {
  /** Validation warnings */
  warnings: Array<Diagnostic>;
  /** Validation errors */
  errors: Array<Diagnostic>;
}

/**
 * Reporter plugin interface
 */
interface Reporter {
  /** Report a build event */
  report(opts: {
    event: ReporterEvent;
    options: PluginOptions;
  }): Promise<void> | void;
}

/**
 * Reporter event types
 */
type ReporterEvent = 
  | BuildStartEvent
  | BuildProgressEvent  
  | BuildSuccessEvent
  | BuildFailureEvent
  | WatchStartEvent
  | WatchEndEvent
  | LogEvent
  | ValidationEvent
  | CacheEvent
  | TraceEvent;

import type { Transformer, PluginOptions, MutableAsset } from '@parcel/types';

// Implement a custom transformer
class MyTransformer implements Transformer {
  async transform({ asset, options }: {
    asset: MutableAsset;
    options: PluginOptions;
  }) {
    const code = await asset.getCode();
    
    // Transform the code
    const transformedCode = `// Transformed by MyTransformer\n${code}`;
    asset.setCode(transformedCode);
    
    // Log transformation
    options.logger.info(`Transformed ${asset.filePath}`);
    
    return [asset];
  }
}

// Implement a custom resolver
class MyResolver implements Resolver {
  async resolve({ dependency, options }) {
    if (dependency.specifier.startsWith('virtual:')) {
      // Handle virtual modules
      return {
        filePath: `/virtual/${dependency.specifier.slice(8)}.js`,
        code: `export default "Virtual module: ${dependency.specifier}";`
      };
    }
    
    return null; // Let other resolvers handle it
  }
}

// Implement a custom reporter
class MyReporter implements Reporter {
  async report({ event, options }) {
    if (event.type === 'buildSuccess') {
      options.logger.info(`Build completed with ${event.bundleGraph.getBundles().length} bundles`);
    }
  }
}