Plugin System

import type {
  Plugin,
  PluginModule,
  PluginConfig,
  PluginOptions,
  PluginContentLoadedActions,
  PluginVersionInformation,
  InitializedPlugin,
  LoadedPlugin,
  PluginIdentifier,
  ConfigureWebpackUtils,
  ConfigureWebpackResult,
  AllContent,
  RouteBuildMetadata,
  PostCssOptions,
  HtmlTagObject,
  HtmlTags,
  ValidationSchema,
  Validate,
  OptionValidationContext,
  ThemeConfigValidationContext,
  Preset,
  PresetModule,
  PresetConfig,
  PresetConfigDefined
} from "@docusaurus/types";
import type { HelmetServerState } from "react-helmet-async";
import type { CommanderStatic } from "commander";
import type { Configuration as WebpackConfiguration, RuleSetRule } from "webpack";
import type { CustomizeRuleString } from "webpack-merge";
import type Joi from "joi";

/**
 * Core plugin interface with all lifecycle hooks
 */
interface Plugin<Content = unknown> {
  /** Plugin identifier name */
  name: string;
  
  /** Load content during build phase */
  loadContent?: () => Promise<Content> | Content;
  
  /** Process loaded content and register routes/data */
  contentLoaded?: (args: {
    content: Content;
    actions: PluginContentLoadedActions;
  }) => Promise<void> | void;
  
  /** Process all content from all plugins */
  allContentLoaded?: (args: {
    allContent: AllContent;
    actions: PluginContentLoadedActions;
  }) => Promise<void> | void;
  
  /** Post-build hook with access to generated routes and metadata */
  postBuild?: (
    props: Props & {
      content: Content;
      head: {[location: string]: HelmetServerState};
      routesBuildMetadata: {[location: string]: RouteBuildMetadata};
    },
  ) => Promise<void> | void;
  
  /** Configure webpack for this plugin */
  configureWebpack?: (
    config: WebpackConfiguration,
    isServer: boolean,
    configureWebpackUtils: ConfigureWebpackUtils,
    content: Content,
  ) => ConfigureWebpackResult | void;
  
  /** Configure PostCSS options */
  configurePostCss?: (options: PostCssOptions) => PostCssOptions;
  
  /** Get theme directory path */
  getThemePath?: () => string;
  
  /** Get TypeScript theme directory path */
  getTypeScriptThemePath?: () => string;
  
  /** Get paths to watch for changes during development */
  getPathsToWatch?: () => string[];
  
  /** Get client modules to load */
  getClientModules?: () => string[];
  
  /** Extend CLI with custom commands */
  extendCli?: (cli: CommanderStatic) => void;
  
  /** Inject HTML tags into pages */
  injectHtmlTags?: (args: {content: Content}) => {
    headTags?: HtmlTags;
    preBodyTags?: HtmlTags;
    postBodyTags?: HtmlTags;
  };
  
  /** Get translation files for i18n */
  getTranslationFiles?: (args: {
    content: Content;
  }) => Promise<TranslationFile[]> | TranslationFile[];
  
  /** Get default code translation messages */
  getDefaultCodeTranslationMessages?: () =>
    | Promise<{[id: string]: string}>
    | {[id: string]: string};
  
  /** Translate plugin content */
  translateContent?: (args: {
    content: Content;
    translationFiles: TranslationFile[];
  }) => Content;
  
  /** Translate theme configuration */
  translateThemeConfig?: (args: {
    themeConfig: ThemeConfig;
    translationFiles: TranslationFile[];
  }) => ThemeConfig;
}

/**
 * Actions available during plugin content loading
 */
interface PluginContentLoadedActions {
  /** Add a route to the site */
  addRoute: (config: RouteConfig) => void;
  /** Create a data file and return its path */
  createData: (name: string, data: string | object) => Promise<string>;
  /** Set global data for this plugin instance */
  setGlobalData: (data: unknown) => void;
}

/**
 * Plugin configuration options
 */
interface PluginOptions {
  id?: string;
  [key: string]: unknown;
}

/**
 * Flexible plugin configuration - supports multiple formats
 */
type PluginConfig<Content = unknown> =
  | string                              // Plugin name only
  | [string, PluginOptions]            // Plugin name with options
  | [PluginModule<Content>, PluginOptions] // Plugin module with options
  | PluginModule<Content>              // Plugin module only
  | false                              // Disabled
  | null;                              // Disabled

/**
 * Plugin module factory function
 */
interface PluginModule<Content = unknown> {
  /** Create plugin instance with context and options */
  (context: LoadContext, options: unknown):
    | Plugin<Content>
    | null
    | Promise<Plugin<Content> | null>;

  /** Validate plugin options */
  validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
  
  /** Validate theme configuration */
  validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;

  /** Get list of swizzleable components (deprecated) */
  getSwizzleComponentList?: () => string[] | undefined;
  
  /** Get swizzle configuration */
  getSwizzleConfig?: () => SwizzleConfig | undefined;
}

/**
 * Plugin identifier for unique identification
 */
interface PluginIdentifier {
  readonly name: string;
  readonly id: string;
}

/**
 * Plugin after initialization with resolved options and metadata
 */
interface InitializedPlugin extends Plugin {
  readonly options: Required<PluginOptions>;
  readonly version: PluginVersionInformation;
  readonly path: string;
}

/**
 * Plugin after content loading with content and routes
 */
interface LoadedPlugin extends InitializedPlugin {
  readonly content: unknown;
  readonly globalData: unknown;
  readonly routes: RouteConfig[];
  readonly defaultCodeTranslations: CodeTranslations;
}

/**
 * Plugin version and source information
 */
type PluginVersionInformation =
  | {
      readonly type: 'package';
      readonly name?: string;
      readonly version?: string;
    }
  | {readonly type: 'project'}
  | {readonly type: 'local'}
  | {readonly type: 'synthetic'};

/**
 * Utilities for configuring webpack in plugins
 */
interface ConfigureWebpackUtils {
  /** Current bundler information (webpack or rspack) */
  currentBundler: CurrentBundler;
  
  /** Get CSS loaders with proper configuration */
  getStyleLoaders: (
    isServer: boolean,
    cssOptions: {[key: string]: unknown},
  ) => RuleSetRule[];
  
  /** Get JavaScript loader configuration */
  getJSLoader: (options: {
    isServer: boolean;
    babelOptions?: string | {[key: string]: unknown};
  }) => RuleSetRule;
}

/**
 * Webpack configuration result with optional merge strategy
 */
interface ConfigureWebpackResult extends WebpackConfiguration {
  mergeStrategy?: {
    [key: string]: CustomizeRuleString;
  };
}

/**
 * Joi validation schema type
 */
type ValidationSchema<T> = Joi.ObjectSchema<T>;

/**
 * Validation function type
 */
type Validate<In, Out> = (
  validationSchema: ValidationSchema<Out>,
  options: In,
) => Out;

/**
 * Context for plugin option validation
 */
interface OptionValidationContext<In, Out> {
  validate: Validate<In, Out>;
  options: In;
}

/**
 * Context for theme configuration validation
 */
interface ThemeConfigValidationContext<In, Out = In> {
  validate: Validate<In, Out>;
  themeConfig: In;
}

/**
 * HTML tag object specification
 */
interface HtmlTagObject {
  /** HTML tag attributes */
  attributes?: Partial<{[key: string]: string | boolean}>;
  /** HTML tag name (e.g., 'div', 'script', 'link', 'meta') */
  tagName: string;
  /** Inner HTML content */
  innerHTML?: string;
}

/**
 * HTML tags can be strings, objects, or arrays
 */
type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];

/**
 * All content from all plugins
 */
interface AllContent {
  [pluginName: string]: {
    [pluginID: string]: unknown;
  };
}

/**
 * Route build metadata for post-build processing
 */
interface RouteBuildMetadata {
  /** Whether this route should be excluded from indexing */
  noIndex: boolean;
}

/**
 * PostCSS configuration options
 */
interface PostCssOptions {
  plugins: unknown[];
  [key: string]: unknown;
}

/**
 * Preset configuration containing plugins and themes
 */
interface Preset {
  plugins?: PluginConfig[];
  themes?: PluginConfig[];
}

/**
 * Preset module factory function
 */
interface PresetModule {
  (context: LoadContext, presetOptions: unknown): Preset;
}

/**
 * Defined preset configuration
 */
type PresetConfigDefined = string | [string, {[key: string]: unknown}];

/**
 * Preset configuration with disable options
 */
type PresetConfig = PresetConfigDefined | false | null;