@yannick-z/modulo 0.2.0 → 0.3.0

package/src/packer/prepare.ts

@@ -2,75 +2,81 @@ import picocolors from "picocolors";
 import type { ModuloArgs_Pack } from "../args/index.ts";
 import { collect_modules } from "./collect-modules.ts";
 import { omit_root_path_for_entries } from "../tools/omit-root-path.ts";
-import { get_externals_importmaps } from "./get-externals-and-tags.ts";
+import { getExternalsAndImportMap } from "./get-externals-and-tags.ts";
 import type { GLOBAL_CONFIG } from "../config/type.ts";
 
 let printed = false;
 
 export function prepare_config(
-  args: ModuloArgs_Pack,
-  kind: "page" | "module",
-  config: GLOBAL_CONFIG
+	args: ModuloArgs_Pack,
+	kind: "page" | "module",
+	config: GLOBAL_CONFIG,
 ) {
-  const { externals, importmaps } = get_externals_importmaps(
-    args,
-    config.externals
-  );
+	console.log(picocolors.blueBright(`\n**** 开始构建 【${kind}】 ****`));
+	const entries = collect_modules(args, kind, config);
 
-  !printed &&
-    console.log(
-      `${picocolors.blue("\nexternals:")}\n${JSON.stringify(
-        externals,
-        null,
-        2
-      )}\n`
-    );
+	if (!entries) {
+		console.log(picocolors.red(`\n没有要构建的${kind}，跳过\n`));
+	} else {
+		console.log(
+			`${picocolors.blue(`\n${kind} entries:`)}\n${JSON.stringify(
+				omit_root_path_for_entries(entries),
+				null,
+				2,
+			)}\n`,
+		);
+	}
 
-  if (kind === "page") {
-    console.log(
-      `${picocolors.blue("html_tags:")}\n${JSON.stringify(
-        config.html.tags,
-        null,
-        2
-      )}\n`
-    );
-  }
+	const { externals, importMap } = getExternalsAndImportMap(
+		args,
+		config.externals,
+		config.externalsType,
+	);
 
-  const importmaps_tag = {
-    append: false,
-    head: true,
-    tag: "script",
-    attrs: { type: args.pack.esm ? "importmap" : "systemjs-importmap" },
-    children: `{
-         "imports": ${JSON.stringify(importmaps, null, 2)}
-      }`,
-  };
+	!printed &&
+		console.log(
+			`${picocolors.blue("\nexternals:")}\n${JSON.stringify(
+				externals,
+				null,
+				2,
+			)}\n`,
+		);
 
-  !printed &&
-    console.log(
-      `${picocolors.blue("\nimportmaps:")}\n${JSON.stringify(
-        importmaps,
-        null,
-        2
-      )}\n`
-    );
+	let importMapsTag: any;
 
-  printed = true;
+	if (config.externalsType === "script") {
+		// script 注入模式，生成多个 script 标签
+		importMapsTag = Object.values(importMap).map((url) => ({
+			tag: "script",
+			attrs: { src: url },
+			append: false,
+			head: true,
+		}));
+	} else {
+		// importmap 模式
+		importMapsTag = [
+			{
+				append: false,
+				head: true,
+				tag: "script",
+				attrs: { type: "importmap" },
+				children: `{
+            "imports": ${JSON.stringify(importMap, null, 2)}
+        }`,
+			},
+		];
+	}
 
-  console.log(picocolors.blueBright(`\n**** 开始构建 【${kind}】 ****`));
-  const entries = collect_modules(args, kind);
+	!printed &&
+		console.log(
+			`${picocolors.blue("\nimportmaps/scripts:")}\n${JSON.stringify(
+				importMap,
+				null,
+				2,
+			)}\n`,
+		);
 
-  if (!entries) {
-    console.log(picocolors.red(`\n没有要构建的${kind}，跳过\n`));
-  } else {
-    console.log(
-      `${picocolors.blue(`\n${kind} entries:`)}\n${JSON.stringify(
-        omit_root_path_for_entries(entries),
-        null,
-        2
-      )}\n`
-    );
-  }
+	printed = true;
 
-  return { entries, externals, importmaps_tag };
+	return { entries, externals, importMapsTag };
 }

package/src/tools/cli.ts

@@ -0,0 +1,21 @@
+import readline from "node:readline";
+import picocolors from "picocolors";
+
+/**
+ * CLI 交互式确认
+ * @param message 提示信息
+ * @returns Promise<boolean> 用户是否确认 (Y/y 为 true)
+ */
+export async function confirm(message: string): Promise<boolean> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+
+	return new Promise((resolve) => {
+		rl.question(`${picocolors.yellow(message)} (Y/n) `, (answer) => {
+			rl.close();
+			resolve(answer.toLowerCase() === "y" || answer === "");
+		});
+	});
+}

package/src/tools/file.ts

@@ -1,19 +1,89 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import picocolors from 'picocolors';
-import { debug_log } from './debug-log.ts';
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { resolve, join } from "node:path";
+import picocolors from "picocolors";
+import { debug_log } from "./log.ts";
 
-export function read_file(path: string, error_msg?: string) {
-  try {
-    return readFileSync(path, 'utf8');
-  } catch {
-    console.log(picocolors.red(error_msg || `文件无法访问或者不存在: ${path}`));
-    return '';
-  }
+/**
+ * 读取文件内容
+ * @param path 文件绝对路径
+ * @param error_msg 自定义错误消息（可选）
+ * @param throwError 是否抛出错误（默认 false）
+ * @returns 文件内容字符串，如果失败则返回空字符串（除非 throwError 为 true）
+ */
+export function read_file(
+	path: string,
+	error_msg?: string,
+	throwError = false,
+) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		const msg = error_msg || `文件无法访问或者不存在: ${path}`;
+		debug_log("read_file error", msg, error);
+		if (throwError) {
+			throw new Error(msg);
+		}
+		console.log(picocolors.red(msg));
+		return "";
+	}
 }
 
+/**
+ * 解析路径并读取文件
+ */
 export function resolve_and_read(root: string, name: string) {
-  const fullpath = resolve(root, name);
-  debug_log(`resolve file: ${name}`, 'result is:', fullpath);
-  return read_file(fullpath);
+	const fullpath = resolve(root, name);
+	debug_log(`resolve file: ${name}`, "result is:", fullpath);
+	return read_file(fullpath);
+}
+
+/**
+ * 获取指定目录下的所有子目录名称
+ * @param path 目标目录路径
+ * @returns 子目录名称列表
+ */
+export function get_directories(path: string): string[] {
+	try {
+		if (!existsSync(path)) return [];
+		return readdirSync(path).filter((file) => {
+			const fullPath = join(path, file);
+			return statSync(fullPath).isDirectory();
+		});
+	} catch (error) {
+		debug_log("get_directories error", path, error);
+		return [];
+	}
+}
+
+/**
+ * 在目录中查找入口文件
+ * @param dir 目标目录
+ * @param candidates 候选文件名（不含扩展名）列表，优先级按顺序
+ * @param extensions 支持的扩展名列表，优先级按顺序
+ * @returns 找到的入口文件绝对路径，如果未找到返回 undefined
+ */
+export function find_entry_file(
+	dir: string,
+	candidates: string[],
+	extensions: string[] = [".ts", ".tsx", ".js", ".jsx", ".vue"],
+): string | undefined {
+	for (const name of candidates) {
+		for (const ext of extensions) {
+			const filename = `${name}${ext}`;
+			const filepath = join(dir, filename);
+			if (existsSync(filepath) && statSync(filepath).isFile()) {
+				return filepath;
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * 检查文件是否存在
+ */
+export function exists(path: string): boolean {
+	const isExist = existsSync(path);
+	debug_log(`check exists: ${path}`, isExist);
+	return isExist;
 }

package/src/tools/find-path-root.ts

@@ -1,29 +1,56 @@
-import fs from 'node:fs';
-import path, { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { debug_log } from './debug-log.ts';
+import fs from "node:fs";
+import path, { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { debug_log } from "./log.ts";
 
-let packageRoot = '';
+let packageRoot = "";
 
 export function get_package_root() {
-  if (!packageRoot) {
-    const __filename = fileURLToPath(import.meta.url); // get the resolved path to the file
-    const __dirname = dirname(__filename); // get the name of the directory
-
-    let currentDir = path.resolve(__dirname);
-    const root = path.parse(currentDir).root;
-
-    while (currentDir !== root) {
-      const potentialPkgJson = path.join(currentDir, 'package.json');
-      if (fs.existsSync(potentialPkgJson)) {
-        break;
-      }
-      currentDir = path.dirname(currentDir);
-    }
-
-    debug_log('packageRoot', currentDir);
-    packageRoot = currentDir;
-  }
-
-  return packageRoot;
+	if (!packageRoot) {
+		const __filename = fileURLToPath(import.meta.url); // get the resolved path to the file
+		const __dirname = dirname(__filename); // get the name of the directory
+
+		let currentDir = path.resolve(__dirname);
+		const root = path.parse(currentDir).root;
+
+		while (currentDir !== root) {
+			const potentialPkgJson = path.join(currentDir, "package.json");
+			if (fs.existsSync(potentialPkgJson)) {
+				break;
+			}
+			currentDir = path.dirname(currentDir);
+		}
+
+		debug_log("packageRoot", currentDir);
+		packageRoot = currentDir;
+	}
+
+	return packageRoot;
+}
+
+export function find_workspace_root(cwd: string) {
+	let currentDir = path.resolve(cwd);
+	const root = path.parse(currentDir).root;
+
+	while (currentDir !== root) {
+		const pnpmWorkspace = path.join(currentDir, "pnpm-workspace.yaml");
+		const packageJsonPath = path.join(currentDir, "package.json");
+
+		if (fs.existsSync(pnpmWorkspace)) {
+			return currentDir;
+		}
+
+		if (fs.existsSync(packageJsonPath)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+				if (pkg.workspaces) {
+					return currentDir;
+				}
+			} catch {}
+		}
+
+		currentDir = path.dirname(currentDir);
+	}
+
+	return undefined;
 }

package/src/tools/get-framework-name.ts

@@ -2,13 +2,13 @@ import { get_packagejson } from "../config/index.ts";
 import { PANIC_IF } from "./panic.ts";
 
 export function get_framework_name() {
-  const { dependencies } = get_packagejson();
+	const { dependencies } = get_packagejson();
 
-  PANIC_IF(
-    !("vue" in dependencies || "react" in dependencies),
-    "package.json中未识别到支持的ui库信息, 当前只支持vue和react"
-  );
+	PANIC_IF(
+		!("vue" in dependencies || "react" in dependencies),
+		"package.json中未识别到支持的ui库信息, 当前只支持vue和react",
+	);
 
-  // 该项目是vue还是react项目
-  return "vue" in dependencies ? "vue" : "react";
+	// 该项目是vue还是react项目
+	return "vue" in dependencies ? "vue" : "react";
 }

package/src/tools/get-ui-plugin.ts

@@ -1,23 +1,37 @@
 import { type PluginReactOptions, pluginReact } from "@rsbuild/plugin-react";
 import { type PluginVueOptions, pluginVue2 } from "@rsbuild/plugin-vue2";
-import { get_global_config, get_packagejson } from "../config/index.ts";
+import { get_packagejson } from "../config/index.ts";
+import type { GLOBAL_CONFIG } from "../config/type.ts";
 import { get_framework_name } from "./get-framework-name.ts";
 import { PANIC_IF } from "./panic.ts";
 import type { ModuloArgs_Pack } from "../args/index.ts";
+import semver from "semver";
 
 export function framework_plugin(
-  args: ModuloArgs_Pack,
-  options?: PluginVueOptions | PluginReactOptions
+	global_config: GLOBAL_CONFIG,
+	options?: PluginVueOptions | PluginReactOptions,
 ) {
-  const { dependencies } = get_packagejson();
-  const framework_name = get_framework_name();
+	const { dependencies } = get_packagejson();
+	const framework_name = get_framework_name();
 
-  // 必须使用指定版本号的ui库，以优化代码产出
-  const version = dependencies[framework_name];
-  const global_config = get_global_config(args);
-  PANIC_IF(
-    global_config.ui_lib[framework_name] !== version,
-    "package.json中只允许使用固定版本号, 并且只支持vue-2.7.16和react-17.0.2"
-  );
-  return framework_name === "vue" ? pluginVue2(options) : pluginReact(options);
+	// 必须使用指定版本号的ui库，以优化代码产出
+	const version = dependencies[framework_name];
+
+	const allowed_versions = [
+		global_config.ui_lib.vue2,
+		global_config.ui_lib.react19,
+	];
+
+	const is_valid = allowed_versions.some((allowed) => {
+		const min_version = semver.minVersion(version);
+		return min_version && semver.satisfies(min_version, `^${allowed}`);
+	});
+
+	PANIC_IF(
+		!is_valid,
+		`package.json中只允许使用固定版本号, 并且只支持vue-2.7.16, react-19.2.4 (当前版本: ${version})`,
+	);
+	return framework_name === "vue"
+		? pluginVue2(options as any)
+		: pluginReact(options as any);
 }

package/src/tools/json.ts

@@ -1,11 +1,65 @@
-import picocolors from 'picocolors';
+import picocolors from "picocolors";
+import { readFileSync, writeFileSync } from "node:fs";
 
-export function jsonparse<T>(input: string) {
-  try {
-    if (input) {
-      return JSON.parse(input) as T;
-    }
-  } catch (e) {
-    console.error(picocolors.red(`JSON.parse failed\n${e}`));
-  }
+/**
+ * 解析 JSON 字符串
+ * @param input JSON 字符串
+ * @param defaultValue 解析失败或输入为空时的默认值（可选）
+ * @returns 解析后的对象或默认值
+ */
+export function jsonparse<T>(input: string, defaultValue?: T): T | undefined {
+	try {
+		if (input) {
+			return JSON.parse(input) as T;
+		}
+		return defaultValue;
+	} catch (e) {
+		console.error(picocolors.red(`JSON.parse failed\n${e}`));
+		return defaultValue;
+	}
+}
+
+/**
+ * 更新 JSON 文件
+ * @param path 文件路径
+ * @param updater 更新函数，接收当前数据并返回新数据
+ * @param createIfNotExist 如果文件不存在是否创建（默认 false）
+ * @returns 是否更新成功
+ */
+export function update_json_file<T = any>(
+	path: string,
+	updater: (data: T) => T,
+	createIfNotExist = false,
+): boolean {
+	try {
+		let data: T;
+		try {
+			const content = readFileSync(path, "utf-8");
+			const parsed = jsonparse<T>(content);
+			if (!parsed) {
+				if (createIfNotExist) {
+					data = {} as T;
+				} else {
+					console.error(picocolors.red(`Failed to parse JSON file: ${path}`));
+					return false;
+				}
+			} else {
+				data = parsed;
+			}
+		} catch (error: any) {
+			if (error.code === "ENOENT" && createIfNotExist) {
+				data = {} as T;
+			} else {
+				console.error(picocolors.red(`Failed to read file: ${path}`));
+				return false;
+			}
+		}
+
+		const newData = updater(data);
+		writeFileSync(path, JSON.stringify(newData, null, 2) + "\n");
+		return true;
+	} catch (e) {
+		console.error(picocolors.red(`Failed to update JSON file: ${path}\n${e}`));
+		return false;
+	}
 }

package/src/tools/log.ts

@@ -0,0 +1,58 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import picocolors from "picocolors";
+
+const logFile = path.join(process.cwd(), "modulo.debug.log");
+let index = 0;
+
+/**
+ * 调试日志函数
+ *
+ * 仅在 process.env.DEBUG 开启或 CLI 参数包含 --debug/--verbose 时输出。
+ * - --verbose: 直接输出到控制台
+ * - --debug: 输出日志文件到当前目录的 modulo.debug.log，并在控制台打印序号
+ *
+ * @param hint 日志标题或提示信息
+ * @param params 日志内容（可以是任意对象）
+ */
+export function debug_log(hint: string, ...params: unknown[]) {
+	const argv_debug = process.env.DEBUG || process.argv.includes("--debug");
+	const argv_verbose =
+		process.argv.includes("--verbose") || process.argv.includes("-v");
+
+	if (!argv_debug && !argv_verbose) {
+		return;
+	}
+
+	const timestamp = new Date().toISOString();
+	const sn = String(index++).padStart(3, "0");
+	const logEntry = `--------------\n${sn} [${timestamp}] ${hint}\n${params
+		.map((p: unknown) =>
+			typeof p === "object" ? JSON.stringify(p, null, 2) : String(p),
+		)
+		.join("\n")}\n---------------\n\n`;
+
+	if (argv_verbose) {
+		console.log(logEntry);
+	}
+
+	if (argv_debug) {
+		// 打印序列号方便debug
+		console.log(picocolors.blue(`\ndebug log ${sn}`));
+
+		fs.appendFileSync(logFile, logEntry);
+	}
+}
+
+// Logger utility
+export const logger = {
+	info: (msg: string) => console.log(picocolors.cyan(msg)),
+	success: (msg: string) => console.log(picocolors.green(msg)),
+	warn: (msg: string) => console.log(picocolors.yellow(msg)),
+	error: (msg: string) => console.log(picocolors.red(msg)),
+	debug: (msg: string) => {
+		if (process.env.DEBUG) {
+			console.log(picocolors.gray(`[DEBUG] ${msg}`));
+		}
+	},
+};

package/src/tools/merge-user-config.ts

@@ -1,21 +1,21 @@
 import { PANIC_IF } from "./panic.ts";
 
 export function merge_user_config(target: any, input: any) {
-  for (const key in input) {
-    const from = input[key];
-    const to = target[key];
-    if (typeof from !== typeof to || !(key in target)) {
-      target[key] = from;
-      continue;
-    } else {
-      if (Array.isArray(to)) {
-        PANIC_IF(!Array.isArray(from));
-        target[key] = [...to, ...from];
-      } else if (typeof to === "object") {
-        merge_user_config(to, from);
-      } else {
-        target[key] = from;
-      }
-    }
-  }
+	for (const key in input) {
+		const from = input[key];
+		const to = target[key];
+		if (typeof from !== typeof to || !(key in target)) {
+			target[key] = from;
+			continue;
+		} else {
+			if (Array.isArray(to)) {
+				PANIC_IF(!Array.isArray(from));
+				target[key] = [...to, ...from];
+			} else if (typeof to === "object") {
+				merge_user_config(to, from);
+			} else {
+				target[key] = from;
+			}
+		}
+	}
 }

package/src/tools/omit-root-path.ts

@@ -1,11 +1,21 @@
-const root_path = process.cwd();
-export function omit_root_path(path: string) {
-  // return relative path
-  return path.replace(root_path, "");
+import { relative } from "node:path";
+
+/**
+ * 获取相对于根目录的路径
+ * @param path 绝对路径
+ * @returns 相对路径（以 / 开头）
+ */
+export function omit_root_path(path: string): string {
+	const rel = relative(process.cwd(), path);
+	// 保持输出格式一致，添加前导 /
+	return rel.startsWith("/") ? rel : `/${rel}`;
 }
 
+/**
+ * 批量处理入口文件路径
+ */
 export function omit_root_path_for_entries(entries: Record<string, string>) {
-  return Object.fromEntries(
-    Object.entries(entries).map(([key, value]) => [key, omit_root_path(value)])
-  );
+	return Object.fromEntries(
+		Object.entries(entries).map(([key, value]) => [key, omit_root_path(value)]),
+	);
 }

package/src/tools/panic.ts

@@ -1,11 +1,15 @@
-import { exit } from 'node:process';
-import pc from 'picocolors';
+import { exit } from "node:process";
+import pc from "picocolors";
 
-const alert = '! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !';
+const alert = "! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !";
 
-export function PANIC_IF(status = false, msg = `SOMETHING'S WRONG`, halt = true): asserts status is false {
-  if (status) {
-    console.log(pc.bgRed(pc.white(`\n${alert}\n\n${msg}\n\n${alert}`)), '\n');
-    halt && exit(1);
-  }
+export function PANIC_IF(
+	status = false,
+	msg = `SOMETHING'S WRONG`,
+	halt = true,
+): asserts status is false {
+	if (status) {
+		console.log(pc.bgRed(pc.white(`\n${alert}\n\n${msg}\n\n${alert}`)), "\n");
+		halt && exit(1);
+	}
 }

package/src/tools/string.ts

@@ -1,3 +1,14 @@
-export function first_letter_upper(str: string) {
-  return `${str[0].toUpperCase()}${str.slice(1).toLowerCase()}`;
+/**
+ * 首字母大写，其余小写
+ * @param str 输入字符串
+ * @returns 格式化后的字符串
+ */
+export function capitalize(str: string): string {
+	if (!str) return "";
+	return `${str.charAt(0).toUpperCase()}${str.slice(1).toLowerCase()}`;
 }
+
+/**
+ * @deprecated Use capitalize instead
+ */
+export const first_letter_upper = capitalize;