插件开发基础：实例剖析插件基本形态与架构逻辑

class MyPlugin {
  apply(compiler) {
    // 在这里注册 Hook 回调
  }
}

// 使用方式
module.exports = {
  plugins: [new MyPlugin()]
}

const pluginName = 'MyPlugin';

class MyPlugin {
  constructor(options = {}) {
    this.options = options;
  }

  apply(compiler) {
    // 使用 compiler.hooks 访问钩子
    compiler.hooks.thisCompilation.tap(pluginName, (compilation) => {
      // 在这里操作 compilation 对象
    });
  }
}

module.exports = MyPlugin;

// 方式一：tap - 同步注册（适用于 SyncHook 和部分 AsyncHook）
compiler.hooks.compile.tap('MyPlugin', (params) => {
  console.log('同步执行');
});

// 方式二：tapAsync - 异步回调注册
compiler.hooks.emit.tapAsync('MyPlugin', (compilation, callback) => {
  setTimeout(() => {
    console.log('异步完成');
    callback();
  }, 100);
});

// 方式三：tapPromise - Promise 注册（推荐）
compiler.hooks.emit.tapPromise('MyPlugin', async (compilation) => {
  await doSomethingAsync();
  console.log('Promise 完成');
});

class Compiler {
  // === 生命周期控制 ===
  run(callback) {}                    // 启动单次编译
  watch(watchOptions, handler) {}     // 启动监听模式
  close(callback) {}                  // 关闭编译器

  // === 编译管理 ===
  createCompilation(params) {}        // 创建新 compilation
  createChildCompiler(              // 创建子编译器（多配置场景）
    compilation,
    compilerName,
    compilerIndex
  ) {}

  // === 缓存与日志 ===
  getCache() {}                       // 获取缓存实例（v5 持久化缓存）
  getInfrastructureLogger(name) {}   // 获取基础设施日志器

  // === 文件系统 ===
  inputFileSystem                     // 输入文件系统
  outputFileSystem                    // 输出文件系统
  watchFileSystem                     // 监听文件系统
}

class Compilation {
  // === 模块管理 ===
  addModule(module)                   // 添加模块到构建队列
  getModule(moduleIdentifier)         // 根据 ID 获取模块
  waitForFinished()                  // 等待所有模块构建完成

  // === 入口管理 ===
  addEntry(context, entry, name, options) {}  // 动态添加入口

  // === 产物管理 ===
  emitAsset(file, source, assetInfo) {}       // 发射产物文件
  updateAsset(file, newSource, assetInfo) {}  // 更新产物内容
  deleteAsset(file)                           // 删除产物文件
  getAsset(name)                              // 获取产物对象

  // === 错误与警告 ===
  errors: Array<Error>            // 错误列表（会导致构建失败）
  warnings: Array<Error>          // 警告列表（不会阻断构建）

  // === 依赖查询 ===
  getDependencyReference(module, dependency) {}  // 获取依赖引用

  // === 上下文访问 ===
  compiler: Compiler              // 关联的 compiler 实例
  options: Object                 // 当前编译配置
}

const { sources } = require('webpack-sources');

class MiniCssExtractPlugin {
  constructor(options = {}) {
    this.options = {
      filename: '[name].css',
      chunkFilename: '[id].css',
      ...options
    };
  }

  apply(compiler) {
    // ========== 模式要点1：监听 processAssets 钩子 ==========
    compiler.hooks.thisCompilation.tap(
      'MiniCssExtractPlugin',
      (compilation) => {
        // v5 推荐：使用 processAssets 替代旧的 emit 钩子
        compilation.hooks.processAssets.tap(
          {
            name: 'MiniCssExtractPlugin',
            stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE  // 优化阶段
          },
          (assets) => {
            this.extractCSS(compilation);
          }
        );
      }
    );

    // ========== 模式要点2：监听渲染钩子注入 runtime ==========
    compiler.hooks.thisCompilation.tap(
      'MiniCssExtractPlugin',
      (compilation) => {
        compilation.hooks.renderManifest.tap(
          'MiniCssExtractPlugin',
          (result, { chunk }) => {
            // 为每个 chunk 生成对应的 CSS 文件
            const cssFilename = this.options.filename.replace(
              '[name]',
              chunk.name
            );

            result.push({
              render: () => new sources.RawSource(this.getCSSContentForChunk(chunk)),
              filename: cssFilename,
              info: { development: true },
              additionalAssets: []
            });
          }
        );
      }
    );
  }

  extractCSS(compilation) {
    // ========== 模式要点3：遍历并提取 CSS ==========
    for (const [filename, asset] of Object.entries(compilation.assets)) {
      if (this.isCSSModule(filename)) {
        const source = asset.source();

        // 从 JS 中提取 CSS 内容
        const extractedCSS = this.extractCSSFromJS(source);

        if (extractedCSS) {
          // 生成新的 CSS 文件
          const cssFilename = filename.replace('.js', '.css');
          compilation.emitAsset(
            cssFilename,
            new sources.RawSource(extractedCSS)
          );

          // 可选：从原文件移除 CSS（已提取）
          // delete compilation.assets[filename];
        }
      }
    }
  }

  isCSSModule(filename) {
    return filename.endsWith('.css.js') || filename.includes('.css');
  }

  extractCSSFromJS(source) {
    // 简化的 CSS 提取逻辑
    const cssMatch = source.match(/\/\*__CSS_CONTENT__\*\/([\s\S]*?)\/\*__END_CSS__\*\//);
    return cssMatch ? cssMatch[1] : null;
  }

  getCSSContentForChunk(chunk) {
    let css = '';
    for (const module of chunk.modulesIterable) {
      if (module.type === 'css/mini-extract') {
        css += module.originalSource()?.source() || '';
      }
    }
    return css;
  }
}

module.exports = MiniCssExtractPlugin;

// ✅ 产物拦截器模式通用模板
class AssetInterceptorPlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap(pluginName, (compilation) => {
      // 方案A：使用 processAssets（v5 推荐）
      compilation.hooks.processAssets.tap(
        { name: pluginName, stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE },
        (assets) => {
          // 1. 遍历 assets
          for (const [file, asset] of Object.entries(compilation.assets)) {
            // 2. 读取内容
            const content = asset.source();

            // 3. 处理内容
            const processed = this.process(content);

            // 4. 更新/新增/删除
            compilation.updateAsset(file, new RawSource(processed));
            // 或: compilation.emitAsset(newFile, new RawSource(data));
            // 或: compilation.deleteAsset(file);
          }
        }
      );

      // 方案B：使用 emit（兼容旧版）
      // compiler.hooks.emit.tapAsync(pluginName, (compilation, cb) => { ... });
    });
  }
}

const ConstDependency = require('webpack/lib/dependencies/ConstDependency');

class DefinePlugin {
  constructor(definitions) {
    this.definitions = definitions;
  }

  apply(compiler) {
    // ========== 模式要点1：获取 Parser 实例 ==========
    compiler.hooks.compilation.tap(
      'DefinePlugin',
      (compilation, { normalModuleFactory }) => {

        // ========== 模式要点2：为不同模块类型注册处理器 ==========
        const handler = (parser) => {
          // 递归处理定义的对象
          this.walkDefinitions(parser, this.definitions, '');
        };

        // 支持多种 JavaScript 模块类型
        for (const type of ['javascript/auto', 'javascript/dynamic', 'javascript/esm']) {
          normalModuleFactory.hooks.parser
            .for(type)
            .tap('DefinePlugin', handler);
        }
      }
    );
  }

  walkDefinitions(parser, definitions, prefix) {
    for (const key of Object.keys(definitions)) {
      const code = definitions[key];

      if (typeof code === 'object' && code && !Array.isArray(code)) {
        // 递归处理嵌套对象
        this.walkDefinitions(parser, code, prefix + key + '.');
        this.applyObjectDefine(parser, prefix + key, code);
      } else {
        // 处理基本类型值
        this.applyDefineKey(parser, prefix, key);
        this.applyDefine(parser, prefix + key, code);
      }
    }
  }

  applyDefine(parser, expressionName, code) {
    // ========== 模式要点3：注册表达式替换回调 ==========
    parser.hooks.expression
      .for(expressionName)
      .tap('DefinePlugin', (expr) => {
        // 与真实 DefinePlugin 一致：字符串值视为代码片段原样注入，
        // 其余类型经 JSON 序列化为字面量（如 true -> true、"abc" -> "abc"）
        const replacement = typeof code === 'string' ? code : JSON.stringify(code);

        // ========== 模式要点4：创建 ConstDependency ==========
        const dep = new ConstDependency(
          replacement,             // 替换后的代码
          expr.range               // 要替换的位置范围
        );
        dep.loc = expr.loc;        // 保留位置信息（用于 sourcemap）

        // 将依赖添加到当前模块
        parser.state.module.addPresentationalDependency(dep);

        return true;               // 告诉 Parser 已处理该节点
      });

    // 处理 typeof 场景：typeof PROD -> typeof (true)
    parser.hooks.typeof
      .for(expressionName)
      .tap('DefinePlugin', (expr) => {
        const replacement = typeof code === 'string' ? code : JSON.stringify(code);
        const dep = new ConstDependency(
          `typeof (${replacement})`,
          expr.range
        );
        dep.loc = expr.loc;
        parser.state.module.addPresentationalDependency(dep);
        return true;
      });
  }

  applyObjectDefine(parser, expressionName, obj) {
    // 处理对象类型：{ KEY: { subKey: value } } -> KEY.subKey = value
    parser.hooks.expression
      .for(expressionName)
      .tap('DefinePlugin', (expr) => {
        const dep = new ConstDependency(
          `(${JSON.stringify(obj)})`,
          expr.range
        );
        dep.loc = expr.loc;
        parser.state.module.addPresentationalDependency(dep);
        return true;
      });
  }
}

module.exports = DefinePlugin;

// ✅ AST 操作者模式通用模板
class ASTManipulatorPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(pluginName, (compilation, params) => {
      const { normalModuleFactory } = params;

      const handler = (parser) => {
        // 1. 注册表达式级别 Hook
        parser.hooks.expression.for('TARGET_VAR').tap(pluginName, (expr) => {
          const dep = new ConstReplacement(
            replacementCode,  // 替换内容
            expr.range        // 替换位置
          );
          parser.state.module.addPresentationalDependency(dep);
          return true;
        });

        // 2. 注册语句级别 Hook（可选）
        parser.hooks.statementIf.tap(pluginName, (statement) => {
          // 处理 if 语句等
        });

        // 3. 注册其他 Parser Hook
        // parser.hooks.call.for('xxx').tap(...)
        // parser.hooks.evaluateTypeof.for('xxx').tap(...)
        // parser.hooks.canRename.for('xxx').tap(...)
      };

      // 支持多种模块类型
      ['javascript/auto', 'javascript/dynamic', 'javascript/esm'].forEach(type => {
        normalModuleFactory.hooks.parser.for(type).tap(pluginName, handler);
      });
    });
  }
}

class ESLintWebpackPlugin {
  constructor(options = {}) {
    this.options = {
      extensions: ['js', 'jsx'],
      exclude: /node_modules/,
      failOnError: false,
      failOnWarning: false,
      threads: true,
      ...options
    };
    this.key = 'ESLintWebpackPlugin';
  }

  apply(compiler) {
    // ========== 模式要点1：多层 Hook 协调 ==========
    // 第一层：编译启动时初始化
    compiler.hooks.run.tapPromise(this.key, (compiler) =>
      this.initializeLinting(compiler)
    );

    // 第二层：每次 compilation 创建时设置
    compiler.hooks.compilation.tap(this.key, (compilation) => {
      this.setupCompilationHooks(compilation);
    });
  }

  async initializeLinting(compiler) {
    // 初始化 ESLint 实例、线程池等
    this.linter = await this.createLinter();
  }

  setupCompilationHooks(compilation) {
    const filesToLint = [];

    // ========== 模式要点2：模块级 Hook - 逐个检查 ==========
    compilation.hooks.succeedModule.tap(this.key, (module) => {
      const file = module.resource;

      // 过滤不符合条件的文件
      if (!file || !this.shouldLint(file)) return;

      // 非阻塞地提交检查任务
      filesToLint.push(file);

      if (this.linter) {
        this.linter.lint(file);  // 异步执行，不阻塞构建
      }
    });

    // ========== 模式要点3：批量处理 Hook - 收集结果 ==========
    compilation.hooks.finishModules.tapAsync(this.key, (modules, callback) => {
      // 所有模块处理完毕，可以批量处理剩余文件
      if (filesToLint.length > 0 && !this.options.threads) {
        this.linter.lint(filesToLint);
      }
      callback();
    });

    // ========== 模式要点4：结果处理 Hook - 报告问题 ==========
    compilation.hooks.additionalAssets.tapPromise(this.key, async () => {
      await this.reportResults(compilation);
    });
  }

  shouldLint(filepath) {
    const ext = filepath.split('.').pop();
    const hasValidExtension = this.options.extensions.includes(ext);
    const isNotExcluded = !this.options.exclude.test(filepath);
    return hasValidExtension && isNotExcluded;
  }

  async reportResults(compilation) {
    // 等待所有 lint 任务完成
    const { errors, warnings } = await this.linter.getResults();

    // ========== 模式要点5：通过 compilation API 提交问题 ==========
    if (warnings?.length > 0) {
      if (this.options.failOnWarning) {
        compilation.errors.push(...warnings);
      } else {
        compilation.warnings.push(...warnings);
      }
    }

    if (errors?.length > 0) {
      if (this.options.failOnError) {
        compilation.errors.push(...errors);
      } else {
        compilation.warnings.push(...errors);
      }
    }
  }

  async createLinter() {
    // 创建 ESLint 实例（简化版）
    return {
      lint(files) {
        console.log(`[ESLint] Linting: ${files}`);
      },
      async getResults() {
        return { errors: [], warnings: [] };
      }
    };
  }
}

module.exports = ESLintWebpackPlugin;

// ✅ 流程控制器模式通用模板
class FlowControllerPlugin {
  apply(compiler) {
    // 1. 初始化阶段
    compiler.hooks.run.tapPromise(pluginName, async (compiler) => {
      await this.init();
    });

    // 2. 每次编译设置
    compiler.hooks.compilation.tap(pluginName, (compilation) => {
      // 2a. 模块级处理（高频触发）
      compilation.hooks.succeedModule.tap(pluginName, (module) => {
        this.processModule(module);  // 快速、非阻塞
      });

      // 2b. 批量处理（低频触发）
      compilation.hooks.finishModules.tap(pluginName, (modules) => {
        this.batchProcess(modules);
      });

      // 2c. 结果汇总
      compilation.hooks.additionalAssets.tapPromise(pluginName, async () => {
        await this.collectResults(compilation);
      });
    });
  }

  async init() {}
  processModule(module) {}
  batchProcess(modules) {}
  async collectResults(compilation) {
    // 使用 compilation.errors/warnings 提交问题
  }
}

/**
 * @fileoverview 你的插件名称和简要描述
 * @version 1.0.0
 * @author Your Name
 */

'use strict';

const PLUGIN_NAME = 'YourPluginName';

class YourPluginName {
  /**
   * @param {Object} [options={}] - 插件配置选项
   * @param {boolean} [options.debug=false] - 调试模式
   * @param {RegExp} [options.test=/\.js$/] - 匹配规则
   */
  constructor(options = {}) {
    this.options = {
      debug: false,
      test: /\.js$/,
      ...options
    };

    this._validateOptions();
  }

  _validateOptions() {
    // 参数校验逻辑
    if (this.options.test && !(this.options.test instanceof RegExp)) {
      throw new Error(`${PLUGIN_NAME}: "test" option must be a RegExp`);
    }
  }

  /**
   * Webpack 插件入口方法
   * @param {import('webpack').Compiler} compiler - 编译器实例
   */
  apply(compiler) {
    // 获取 webpack 实例（兼容性处理）
    const webpack = compiler.webpack || require('webpack');

    // 日志工具
    const logger = compiler.getInfrastructureLogger(PLUGIN_NAME);

    // ========== Hook 注册区 ==========

    // 1. 编译初始化阶段
    compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
      logger.debug('compilation created:', compilation.name);

      // 2. 资源处理阶段（v5 推荐）
      compilation.hooks.processAssets.tap(
        {
          name: PLUGIN_NAME,
          stage: webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE
        },
        (assets) => {
          this.processAssets(compilation, assets, logger);
        }
      );
    });

    // 3. （可选）使用 emit 钩子（兼容旧版）
    // compiler.hooks.emit.tapAsync(PLUGIN_NAME, (compilation, callback) => {
    //   this.handleEmit(compilation, logger);
    //   callback();
    // });

    // 4. （可选）编译完成阶段
    compiler.hooks.done.tap(PLUGIN_NAME, (stats) => {
      if (this.options.debug) {
        logger.info('Build completed:', {
          time: stats.endTime - stats.startTime,
          hasErrors: stats.hasErrors(),
          hasWarnings: stats.hasWarnings()
        });
      }
    });
  }

  /**
   * 处理资源文件
   * @param {import('webpack').Compilation} compilation
   * @param {Object} assets
   * @param {Object} logger
   */
  processAssets(compilation, assets, logger) {
    const { sources } = require('webpack-sources');

    for (const [filename, asset] of Object.entries(compilation.assets)) {
      if (!this.options.test.test(filename)) continue;

      try {
        const source = asset.source();
        const processed = this.transformSource(source, filename);

        if (processed !== null) {
          compilation.updateAsset(
            filename,
            new sources.RawSource(processed),
            { [PLUGIN_NAME]: true }  // assetInfo 元数据
          );

          logger.info(`Processed: ${filename}`);
        }
      } catch (error) {
        compilation.errors.push(
          new Error(`${PLUGIN_NAME}: Error processing ${filename}: ${error.message}`)
        );
      }
    }
  }

  /**
   * 转换源码（自定义逻辑）
   * @param {string} source - 原始源码
   * @param {string} filename - 文件名
   * @returns {string|null} 转换后的源码，返回 null 表示不处理
   */
  transformSource(source, filename) {
    // TODO: 实现你的转换逻辑
    // 示例：添加注释头
    return `/* Generated by ${PLUGIN_NAME} */\n${source}`;
  }
}

module.exports = YourPluginName;

// webpack.config.js
const path = require('path');
const YourPluginName = require('./your-plugin-name');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js'
  },
  plugins: [
    new YourPluginName({
      debug: true,
      test: /\.(js|css)$/,
      // 其他自定义选项...
    })
  ]
};

import type { Compiler, Compilation, Asset } from 'webpack';
import type { Sources } from 'webpack-sources';

interface PluginOptions {
  debug?: boolean;
  test?: RegExp;
  [key: string]: any;
}

const PLUGIN_NAME = 'YourPluginName';

export default class YourPluginName {
  private readonly options: Required<PluginOptions>;

  constructor(options: PluginOptions = {}) {
    this.options = {
      debug: false,
      test: /\.js$/,
      ...options
    };
  }

  apply(compiler: Compiler): void {
    const webpack = compiler.webpack || require('webpack') as typeof import('webpack');
    const logger = compiler.getInfrastructureLogger(PLUGIN_NAME);

    compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation: Compilation) => {
      compilation.hooks.processAssets.tap(
        {
          name: PLUGIN_NAME,
          stage: webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE
        },
        (assets: Record<string, Asset>) => {
          this.processAssets(compilation, assets, logger);
        }
      );
    });
  }

  private processAssets(
    compilation: Compilation,
    assets: Record<string, Asset>,
    logger: ReturnType<Compiler['getInfrastructureLogger']>
  ): void {
    const { RawSource } = require('webpack-sources') as typeof import('webpack-sources');

    for (const [filename, asset] of Object.entries(compilation.assets)) {
      if (!this.options.test.test(filename)) continue;

      const source = asset.source();
      const processed = this.transformSource(source, filename);

      if (processed !== null) {
        compilation.updateAsset(
          filename,
          new RawSource(processed),
          { [PLUGIN_NAME]: true }
        );
      }
    }
  }

  private transformSource(source: string, filename: string): string | null {
    return `/* Generated by ${PLUGIN_NAME} */\n${source}`;
  }
}

class DebugHelperPlugin {
  apply(compiler) {
    const logger = compiler.getInfrastructureLogger('DebugHelper');

    // 监听 emit 钩子（异步 Hook 需用 tap 注册，webpack 内部通过 callAsync 触发）
    compiler.hooks.emit.tap('DebugHelper', (compilation) => {
      logger.warn('=== EMIT HOOK TRIGGERED ===');
      logger.warn('compilation.assets keys:', Object.keys(compilation.assets));
    });

    // 打印 compilation 创建信息
    compiler.hooks.thisCompilation.tap('DebugHelper', (compilation) => {
      logger.info('New compilation created:', {
        name: compilation.name,
        compiler: compilation.compiler.name
      });
    });
  }
}

class ValidationPlugin {
  constructor(options = {}) {
    this.options = options;
  }

  apply(compiler) {
    // v5.106+ 新增；低版本不存在该钩子，先做特性检测
    if (compiler.hooks.validate) {
      compiler.hooks.validate.tap('ValidationPlugin', () => {
        // 通过 compiler.validate() 走 webpack 统一的 schema 校验与错误报告
        compiler.validate(
          () => require('./validation-plugin.schema.json'),
          this.options,
          { name: 'Validation Plugin', baseDataPath: 'options' },
          (options) => require('./validation-plugin.schema.check')(options)
        );
      });
    }
  }
}

class EmptyAssetCheckPlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap('EmptyAssetCheckPlugin', (compilation) => {
      compilation.hooks.processAssets.tap(
        { name: 'EmptyAssetCheckPlugin', stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_ANALYSE },
        () => {
          // 示例：确保没有空文件
          for (const [filename, asset] of Object.entries(compilation.assets)) {
            if (asset.size() === 0) {
              compilation.warnings.push(new Error(`Empty asset detected: ${filename}`));
            }
          }
        }
      );
    });
  }
}