@yannick-z/modulo 0.2.0 → 0.3.1

package/src/packer/auto-external-plugin.ts

@@ -0,0 +1,205 @@
+import { createRequire } from 'node:module';
+import type { Compiler, Compilation } from "@rspack/core";
+const require = createRequire(import.meta.url);
+import type { ModuloArgs_Pack } from "../args/index.ts";
+import type { GLOBAL_CONFIG } from "../config/type.ts";
+import { getExternalsAndImportMap } from "./get-externals-and-tags.ts";
+
+/**
+ * 自动 External 插件
+ *
+ * 1. 扫描编译过程中使用到的 node_modules 依赖
+ * 2. 如果这些依赖在 config.externals 中定义了，则标记为已使用
+ * 3. 在 HTML 生成阶段，仅注入已使用的依赖的 importmap 或 script 标签
+ */
+export class AutoExternalPlugin {
+	private externalLibNames: string[];
+	private usedExternals: Set<string>;
+	private args: ModuloArgs_Pack;
+	private config: GLOBAL_CONFIG;
+
+	constructor(args: ModuloArgs_Pack, config: GLOBAL_CONFIG) {
+		this.args = args;
+		this.config = config;
+		this.externalLibNames = Object.keys(config.externals);
+		this.usedExternals = new Set<string>();
+	}
+
+	apply(compiler: Compiler) {
+		compiler.hooks.compilation.tap(
+			"AutoExternalPlugin",
+			(compilation: Compilation) => {
+				// 1. 扫描模块依赖
+				compilation.hooks.finishModules.tap("AutoExternalPlugin", (modules) => {
+					// ... (省略模块扫描逻辑，这里没有问题) ...
+					for (const module of modules) {
+						// @ts-ignore
+						const constructorName = module.constructor.name;
+						// @ts-ignore
+						const request = module.request;
+						// @ts-ignore
+						const userRequest = module.userRequest;
+						// @ts-ignore
+						const resource = module.resource;
+						// @ts-ignore
+						const externalType = module.externalType;
+
+						// 策略 A: 检查 ExternalModule
+						// Rspack 中 ExternalModule 的 userRequest 通常是 import 的路径 (例如 'vue')
+						if (constructorName === 'ExternalModule' || externalType) {
+							const libName = request || userRequest; // 通常 request 是 'vue'
+							if (libName && this.externalLibNames.includes(libName)) {
+								this.usedExternals.add(libName);
+								continue;
+							}
+						}
+
+						// 策略 B: 检查 module.resource 是否包含 node_modules (针对未被 external 但我们想知道是否被引用的情况 - 但这通常意味着它被打包了)
+						// 之前的逻辑保留，作为兜底，或者针对未正确 external 的情况
+						if (resource && resource.includes("node_modules")) {
+							for (const libName of this.externalLibNames) {
+								if (
+									resource.includes(`/node_modules/${libName}/`) ||
+									resource.includes(`\\node_modules\\${libName}\\`)
+								) {
+									this.usedExternals.add(libName);
+								}
+							}
+						} else if (resource && resource.includes("/node_modules/.pnpm/")) {
+							// 兼容 pnpm
+							for (const libName of this.externalLibNames) {
+								if (
+									resource.includes(`/node_modules/.pnpm/${libName}@`) ||
+									resource.includes(`/node_modules/.pnpm/${libName}+`) ||
+									// 某些情况下 pnpm 可能会直接链接
+									resource.includes(`/node_modules/${libName}/`)
+								) {
+									this.usedExternals.add(libName);
+								}
+							}
+						}
+					}
+				});
+
+				// 尝试通过 compilation.hooks 访问 HtmlWebpackPlugin hooks
+				// Rsbuild 可能通过 mixin 或者其他方式将 hooks 注入到了 compilation 上
+				// 或者我们可以尝试直接使用 tapAsync 到 HtmlWebpackPlugin 的实例上，如果我们能找到它
+
+				// 终极 Hook 调试: 使用 compiler.hooks.emit 来检查 assets，看是否包含 index.html，以及内容
+				compiler.hooks.emit.tapAsync("AutoExternalPlugin", (compilation, cb) => {
+					if (process.env.DEBUG) console.log('[AutoExternalPlugin] emit hook triggered');
+					// 检查 compilation.assets
+					const assetNames = Object.keys(compilation.assets);
+					if (process.env.DEBUG) console.log('[AutoExternalPlugin] Assets:', assetNames);
+					cb();
+				});
+
+				// 2. 注入 HTML
+				let HtmlWebpackPlugin: any;
+
+				// 优先从 compiler.options.plugins 中查找实例并获取其构造函数
+				// 这是最稳妥的方式，确保我们获取的是同一个类的构造函数
+				const htmlPluginInstance = compiler.options.plugins.find(
+					(p: any) => p && (p.constructor.name === "HtmlWebpackPlugin" || p.constructor.name === "HtmlRspackPlugin")
+				);
+
+				if (htmlPluginInstance) {
+					HtmlWebpackPlugin = htmlPluginInstance.constructor;
+				}
+
+				// Fallback: 如果没找到实例（可能被封装了），尝试从 compiler.webpack 中获取
+				if (!HtmlWebpackPlugin) {
+					HtmlWebpackPlugin =
+						compiler.webpack.HtmlRspackPlugin ||
+						(compiler.webpack as any).HtmlWebpackPlugin;
+				}
+
+				if (!HtmlWebpackPlugin) {
+					// Try to import from @rspack/plugin-html
+					try {
+						HtmlWebpackPlugin = require('@rspack/plugin-html').HtmlRspackPlugin;
+					} catch (e) {
+						// ignore
+					}
+				}
+
+				if (!HtmlWebpackPlugin) {
+					return;
+				}
+
+				// 确保我们拿到的确实是 HtmlWebpackPlugin 构造函数，并且它有 getHooks 方法
+				if (typeof (HtmlWebpackPlugin as any).getHooks !== 'function') {
+					return;
+				}
+
+				const hooks = (HtmlWebpackPlugin as any).getHooks(compilation);
+
+				hooks.alterAssetTags.tapAsync("AutoExternalPlugin", (data: any, cb: any) => {
+					if (data.assetTags && data.assetTags.scripts) {
+						this.processTags(data, 'assetTags.scripts');
+					}
+					cb(null, data);
+				});
+			},
+		);
+	}
+
+	private processTags(data: any, targetProp: string) {
+		if (!this.config.autoExternal) {
+			return data;
+		}
+
+		// 重新计算 importmaps
+		const { importMap } = getExternalsAndImportMap(
+			this.args,
+			this.config.externals,
+			this.config.externalsType,
+		);
+
+		// 过滤未使用的依赖
+		const filteredImportMap = Object.fromEntries(
+			Object.entries(importMap).filter(([key]) =>
+				this.usedExternals.has(key),
+			),
+		);
+
+		if (Object.keys(filteredImportMap).length === 0) {
+			return data;
+		}
+
+		let tags: any[] = [];
+		if (this.config.externalsType === "script") {
+			tags = Object.values(filteredImportMap).map((url) => ({
+				tagName: "script",
+				voidTag: false,
+				attributes: {
+					src: url,
+				},
+			}));
+		} else {
+			tags = [
+				{
+					tagName: "script",
+					voidTag: false,
+					attributes: { type: "importmap" },
+					innerHTML: JSON.stringify(
+						{ imports: filteredImportMap },
+						null,
+						2,
+					),
+				},
+			];
+		}
+
+		// 插入到 head 的最前面
+		if (targetProp === 'headTags') {
+			data.headTags.unshift(...tags);
+		} else if (targetProp === 'assetTags.scripts') {
+			data.assetTags.scripts.unshift(...tags);
+		} else if (targetProp === 'head') {
+			data.head.unshift(...tags);
+		}
+
+		return data;
+	}
+}

package/src/packer/collect-modules.ts

@@ -1,77 +1,66 @@
-import { existsSync, readdirSync } from "node:fs";
 import { resolve } from "node:path";
 import picocolors from "picocolors";
-import { get_global_config } from "../config/index.ts";
-import { debug_log } from "../tools/debug-log.ts";
+import { debug_log } from "../tools/log.ts";
 import { get_framework_name } from "../tools/get-framework-name.ts";
+import { get_directories, find_entry_file, exists } from "../tools/file.ts";
 import type { ModuloArgs_Pack } from "../args/index.ts";
+import type { GLOBAL_CONFIG } from "../config/type.ts";
 
+/**
+ * 收集模块入口文件
+ * 扫描指定目录下的子目录，查找符合规则的入口文件（index/main/同名文件）
+ *
+ * @param args CLI 参数
+ * @param kind 模块类型（page 或 module）
+ * @returns 模块名到入口文件路径的映射对象，如果未找到任何模块则返回 undefined
+ */
 export function collect_modules(
-  args: ModuloArgs_Pack,
-  kind: "page" | "module"
-) {
-  const global_config = get_global_config(args);
-  const framework_name = get_framework_name();
-  const module_path = global_config.input[`${kind}s`];
-  const exist = existsSync(module_path);
-  debug_log(
-    picocolors.blue("check module_path"),
-    module_path,
-    exist ? "exists" : "NOT exists"
-  );
-  // 解析目录下的所有模块
-  const module_entries = !exist
-    ? []
-    : readdirSync(module_path, { withFileTypes: true })
-        .filter((item) => {
-          debug_log(
-            "checking module is directory",
-            item.name,
-            item.isDirectory()
-          );
-          return item.isDirectory();
-        })
-        // 每个模块都要求以index或者main或者文件夹同名命名
-        .map((dirent) => {
-          const dir_path = resolve(module_path, dirent.name);
-          const entry_file_path = [
-            resolve(dir_path, "index.ts"),
-            resolve(dir_path, "index.tsx"),
-            resolve(dir_path, "index.js"),
-            resolve(dir_path, "index.jsx"),
-            resolve(dir_path, "main.ts"),
-            resolve(dir_path, "main.tsx"),
-            resolve(dir_path, "main.js"),
-            resolve(dir_path, "main.jsx"),
-            // vue组件常常用vue文件作为入口，因此优先级高于同名ts和tsx文件
-            ...(framework_name === "vue"
-              ? [
-                  resolve(dir_path, "index.vue"),
-                  resolve(dir_path, "main.vue"),
-                  resolve(dir_path, `${dirent.name}.vue`),
-                ]
-              : []),
-            resolve(dir_path, `${dirent.name}.ts`),
-            resolve(dir_path, `${dirent.name}.tsx`),
-            resolve(dir_path, `${dirent.name}.js`),
-            resolve(dir_path, `${dirent.name}.jsx`),
-          ].find((path) => {
-            const exists = existsSync(path);
-            debug_log(
-              "checking entry candidate",
-              `${path} ${picocolors[exists ? "green" : "red"](
-                `exists - ${exists}`
-              )}`
-            );
-            return exists;
-          });
-          debug_log("found entry", entry_file_path);
-          return [dirent.name, entry_file_path];
-        })
-        // 没有找到入口的就不管
-        .filter((entry): entry is [string, string] => !!entry[1]);
+	args: ModuloArgs_Pack,
+	kind: "page" | "module",
+	global_config: GLOBAL_CONFIG,
+): Record<string, string> | undefined {
+	const framework_name = get_framework_name();
+	const module_path = global_config.input[`${kind}s`];
+	const isExist = exists(module_path);
 
-  return module_entries.length > 0
-    ? Object.fromEntries(module_entries)
-    : undefined;
+	debug_log(
+		picocolors.blue("check module_path"),
+		module_path,
+		isExist ? "exists" : "NOT exists",
+	);
+
+	if (!isExist) {
+		return undefined;
+	}
+
+	// 基础候选文件名
+	const baseCandidates = ["index", "main"];
+	// 扩展名列表
+	const extensions = [".ts", ".tsx", ".js", ".jsx"];
+	// Vue 特有扩展名
+	if (framework_name === "vue") {
+		extensions.unshift(".vue");
+	}
+
+	// 解析目录下的所有模块
+	const module_entries = get_directories(module_path)
+		.map((dirName) => {
+			const dir_path = resolve(module_path, dirName);
+
+			// 构建候选文件名列表，包含目录名
+			const candidates = [...baseCandidates, dirName];
+
+			// 查找入口文件
+			const entry_file_path = find_entry_file(dir_path, candidates, extensions);
+
+			debug_log("found entry", dirName, entry_file_path || "NOT FOUND");
+
+			return [dirName, entry_file_path];
+		})
+		// 没有找到入口的就不管
+		.filter((entry): entry is [string, string] => !!entry[1]);
+
+	return module_entries.length > 0
+		? Object.fromEntries(module_entries)
+		: undefined;
 }

package/src/packer/get-externals-and-tags.ts

@@ -1,65 +1,92 @@
 import type { ModuloArgs_Pack } from "../args/index.ts";
 import {
-  is_env_external,
-  type ExternalLibs,
-  type ImportExternal,
-  is_module_typed_external_url,
-  type ModuleTypedExternalUrl,
-  type ConfigExternalUrl,
-} from "../config/externals.ts";
-import type { Tag } from "../config/preset/html.ts";
-import { is_string } from "../type/guard.ts";
+	type ExternalLibs,
+	type ConfigExternalUrl,
+	type ImportExternal,
+} from "../config/type.ts";
+import {
+	is_env_external,
+	is_string,
+	is_import_external,
+} from "../type/guard.ts";
 
-function get_external_url(args: ModuloArgs_Pack, url: ConfigExternalUrl) {
-  let _url = url;
-  while (!is_string(_url)) {
-    if (is_env_external(_url)) {
-      _url = _url[args.pack.env];
-    } else {
-      const mode = args.pack.esm ? "esm" : "umd";
-      _url = mode in _url ? (_url as any)[mode] : undefined;
-    }
-  }
-  return _url;
+function getExternalUrl(args: ModuloArgs_Pack, url: ConfigExternalUrl) {
+	let resolvedUrl = url;
+	while (!is_string(resolvedUrl)) {
+		if (is_env_external(resolvedUrl)) {
+			resolvedUrl = resolvedUrl[args.pack.env];
+		} else {
+			// 理论上不会走到这里，因为现在只有 string 和 EnvExternalUrl
+			// 但为了类型安全，还是保留一个 else 分支或者抛出错误
+			return undefined;
+		}
+	}
+	return resolvedUrl;
 }
 
-export function get_externals_importmaps(
-  args: ModuloArgs_Pack,
-  external_list: ExternalLibs
+/**
+ * 解析 External 配置，生成 externals 对象和 importMap
+ * @param args CLI 参数
+ * @param externalLibs 外部依赖配置
+ * @param externalsType External 类型（importmap 或 script）
+ * @returns externals 和 importMap
+ */
+export function getExternalsAndImportMap(
+	args: ModuloArgs_Pack,
+	externalLibs: ExternalLibs,
+	externalsType: "importmap" | "script" = "importmap",
 ) {
-  return Object.entries(external_list).reduce(
-    ({ externals, importmaps }, [lib_name, data]) => {
-      // 归一化为GlobalExternal或者ImportExternal
-      // 此处类型推导有问题，因此手动断言
-      const _data = is_env_external(data) ? data[args.pack.env] : data;
-      const external_lib =
-        typeof _data === "string"
-          ? { url: { esm: _data, umd: _data } }
-          : is_module_typed_external_url(_data)
-          ? { url: _data }
-          : _data;
+	return Object.entries(externalLibs).reduce(
+		({ externals, importMap }, [libName, data]) => {
+			// 归一化为GlobalExternal或者ImportExternal
+			// 1. data 是 string -> { url: data }
+			// 2. data 是 EnvExternalUrl (dev/prd) -> { url: data }
+			// 3. data 是 ImportExternal -> data
+			
+			let externalLib: ImportExternal;
+			
+			if (is_string(data)) {
+				externalLib = { url: data };
+			} else if (is_env_external(data)) {
+				externalLib = { url: data };
+			} else {
+				externalLib = data as ImportExternal;
+			}
+			
+			// 解析 url (处理 EnvExternalUrl)
+			const url = getExternalUrl(args, externalLib.url);
+
+			if (externalsType === "script") {
+				// Script 模式：external 映射为全局变量
+				const globalVar = externalLib.global || libName;
+				const importName = externalLib.importName || libName;
+				(Array.isArray(importName) ? importName : [importName]).forEach(
+					(name) => (externals[name] = globalVar),
+				);
 
-      // 合并externals，以剔除打包内容
-      const _importName = external_lib.importName || lib_name;
-      (Array.isArray(_importName) ? _importName : [_importName]).forEach(
-        (name) => (externals[name] = lib_name)
-      );
+				if (url) {
+					importMap[libName] = url; // 复用 importMap 存储 URL，但在 prepare 中会生成 script 标签
+				}
+			} else {
+				// Importmap 模式：external 映射为包名（由 importmap 解析）
+				const importName = externalLib.importName || libName;
+				(Array.isArray(importName) ? importName : [importName]).forEach(
+					(name) => (externals[name] = libName),
+				);
 
-      const url = get_external_url(args, external_lib.url);
-      // 如果有external的url
-      if (url) {
-        // 如果是import的，加入到importmaps
-        importmaps[lib_name] = url;
-      }
+				if (url) {
+					importMap[libName] = url;
+				}
+			}
 
-      return {
-        externals,
-        importmaps,
-      };
-    },
-    {
-      externals: {} as Record<string, string>,
-      importmaps: {} as Record<string, string>,
-    }
-  );
+			return {
+				externals,
+				importMap,
+			};
+		},
+		{
+			externals: {} as Record<string, string>,
+			importMap: {} as Record<string, string>,
+		},
+	);
 }

package/src/packer/lib.ts

@@ -1,84 +1,92 @@
 import { pluginLess } from "@rsbuild/plugin-less";
-import { build, defineConfig } from "@rslib/core";
+import * as rslib from "@rslib/core";
 import picocolors from "picocolors";
 import type { ModuloArgs_Pack } from "../args/index.ts";
 import { get_global_config, get_packagejson } from "../config/index.ts";
 import { framework_plugin } from "../tools/get-ui-plugin.ts";
 import { prepare_config } from "./prepare.ts";
 
+/**
+ * 执行库（module）打包
+ *
+ * 使用 Rslib 将模块目录下的代码打包为 ESM 和 UMD 格式。
+ *
+ * @param args CLI 参数
+ */
 export async function lib_pack(args: ModuloArgs_Pack) {
-  const config = get_global_config(args);
-  const packagejson = get_packagejson();
+	const config = await get_global_config(args);
+	const packagejson = get_packagejson();
 
-  const { entries, externals } = prepare_config(args, "module", config);
+	const { entries, externals } = prepare_config(args, "module", config);
 
-  if (!entries) {
-    return;
-  }
+	if (!entries) {
+		return;
+	}
 
-  const rslibConfig = defineConfig({
-    source: {
-      define: config.define,
-      entry: entries,
-    },
-    plugins: [framework_plugin(args), pluginLess()],
-    resolve: {
-      alias: config.alias,
-    },
-    lib: [
-      {
-        format: "esm",
-        syntax: "esnext",
-        dts: false,
-        output: {
-          assetPrefix: `${config.url.base}/modules`,
-          externals,
-          distPath: {
-            root: config.output.modules,
-            js: "esm",
-            jsAsync: "esm",
-            css: "esm",
-          },
-          minify: config.minify,
-        },
-      },
-      {
-        format: "umd",
-        output: {
-          assetPrefix: `${config.url.base}/modules`,
-          externals,
-          distPath: {
-            root: config.output.modules,
-            js: "umd",
-            jsAsync: "umd",
-            css: "umd",
-          },
-          minify: config.minify,
-        },
-        syntax: "es6",
-        umdName: `${packagejson.name}-modules-[name]`,
-      },
-    ],
-    output: {
-      legalComments: "none",
-      target: "web",
-    },
-    performance: {
-      bundleAnalyze: config.analyze
-        ? {
-            analyzerMode: "disabled",
-            generateStatsFile: true,
-          }
-        : undefined,
-      chunkSplit: {
-        strategy: "all-in-one",
-      },
-    },
-  });
+	const rslibConfig = rslib.defineConfig({
+		source: {
+			define: config.define,
+			entry: entries,
+		},
+		plugins: [framework_plugin(config), pluginLess()],
+		resolve: {
+			alias: config.alias,
+		},
+		lib: [
+			{
+				format: "esm",
+				syntax: "esnext",
+				dts: false,
+				output: {
+					assetPrefix: `${config.url.base}/modules`,
+					externals,
+					distPath: {
+						root: config.output.modules,
+						js: "esm",
+						jsAsync: "esm",
+						css: "esm",
+					},
+					minify: config.minify,
+				},
+			},
+			{
+				format: "umd",
+				output: {
+					assetPrefix: `${config.url.base}/modules`,
+					externals,
+					distPath: {
+						root: config.output.modules,
+						js: "umd",
+						jsAsync: "umd",
+						css: "umd",
+					},
+					minify: config.minify,
+				},
+				syntax: "es6",
+				umdName: `${packagejson.name}-modules-[name]`,
+			},
+		],
+		output: {
+			legalComments: "none",
+			target: "web",
+		},
+		performance: {
+			bundleAnalyze: config.analyze
+				? {
+					analyzerMode: "disabled",
+					generateStatsFile: true,
+				}
+				: undefined,
+			chunkSplit: {
+				strategy: "all-in-one",
+			},
+		},
+	});
 
-  await build(rslibConfig, { watch: args.cmd === "build" && args.pack.watch });
+	const { build } = await rslib.createRslib({ config: rslibConfig });
+	await build({ watch: args.cmd === "build" && args.pack.watch });
 
-  if (args.cmd === "build") {
-    console.log(picocolors.green("\n**** 构建【module】完成 ****\n"));
-  }
+	if (args.cmd === "build") {
+		console.log(picocolors.green("\n**** 构建【module】完成 ****\n"));
+	}
 }