feat: support specifying packages as real-external dependencies

.vscode/json-schemas/definition.json

@@ -8,16 +8,6 @@
 			"title": "是否启用当前小工具 / Enable the current gadget or not",
 			"default": true
 		},
-		"excludeSites": {
-			"type": "array",
-			"title": "在给定站点上禁用当前小工具 / Disable the current gadget on given sites",
-			"default": [],
-			"items": {
-				"type": "string",
-				"minLength": 1
-			},
-			"minItems": 1
-		},
 		"description": {
 			"type": "string",
 			"title": "“MediaWiki:Gadget-小工具名”页面中的文本，默认为当前小工具名 / The content in the page 'MediaWiki:Gadget-${gadgetName}' (default: the current gadget name)"
@@ -29,6 +19,26 @@
 			"examples": ["appear", "browser", "compatibility", "edit", "sysop"],
 			"minLength": 1
 		},
+		"excludeSites": {
+			"type": "array",
+			"title": "在给定站点上禁用当前小工具 / Disable the current gadget on given sites",
+			"default": [],
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"minItems": 1
+		},
+		"externalPackages": {
+			"type": "array",
+			"title": "除 dependencies 属性中的包之外，额外指定 esbuild 的 external 编译选项 / Specify additional esbuild external compilation options",
+			"default": [],
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"minItems": 1
+		},
 		"actions": {
 			"type": "array",
 			"default": [],

scripts/constant.ts

@@ -35,9 +35,10 @@ const HEADER = `/**
  */
 const DEFAULT_DEFINITION = {
 	enable: true,
-	excludeSites: [],
 	description: '', // 回落值为小工具名称 / Fallback value: the name of the current gadget
 	section: '', // 回落值为 appear / Fallback value: appear
+	excludeSites: [],
+	externalPackages: [],
 	actions: [],
 	contentModels: [],
 	default: false,

scripts/modules/build.ts

@@ -39,9 +39,11 @@ const build = async (): Promise<void> => {
 				continue;
 			}
 
+			const {dependencies, externalPackages} = definition;
 			const builtScriptFileNames: string[] = await buildFiles(gadgetName, 'script', {
+				dependencies,
+				externalPackages,
 				licenseText,
-				dependencies: definition.dependencies,
 				files: generateFileArray(script, scripts),
 			});
 			const scriptFileNames: string = generateFileNames(gadgetName, builtScriptFileNames);

scripts/modules/formatJSON.ts

@@ -96,13 +96,15 @@ const formatJSON = async (paths: string[]): Promise<void> => {
 					break;
 				}
 
-				const {enable, excludeSites, description, section} = object as unknown as DefaultDefinition;
+				const {enable, description, section, excludeSites, externalPackages} =
+					object as unknown as DefaultDefinition;
 
 				let definitionSorted: Partial<DefaultDefinition> = {
 					enable,
-					excludeSites,
 					description,
 					section,
+					excludeSites,
+					externalPackages,
 				};
 				definitionSorted = {
 					...definitionSorted,

scripts/modules/types.d.ts

@@ -35,9 +35,10 @@ type Credentials = CredentialsOnlyOAuth | CredentialsOnlyOAuth2 | CredentialsOnl
 
 interface DefaultDefinition {
 	enable: boolean;
-	excludeSites: string[];
 	description: string;
 	section: string;
+	excludeSites: string[];
+	externalPackages: string[];
 	actions: string[];
 	contentModels: string[];
 	default: boolean;
@@ -54,8 +55,6 @@ interface DefaultSectionMap {
 	[key: DefaultDefinition['section']]: string;
 }
 
-type Dependencies = DefaultDefinition['dependencies'];
-
 type DeploymentDirectTargets = [string, string][];
 
 interface DeploymentTargets {
@@ -95,7 +94,6 @@ export type {
 	CredentialsOnlyPassword,
 	DefaultDefinition,
 	DefaultSectionMap,
-	Dependencies,
 	DeploymentDirectTargets,
 	DeploymentTargets,
 	GlobalSourceFiles,

scripts/modules/utils/build-util.ts

@@ -2,10 +2,11 @@ import * as PACKAGE from '../../../package.json';
 import {BANNER, GLOBAL_REQUIRES_ES6, SOURCE_MAP} from '../../constant';
 import {type BabelFileResult, type TransformOptions, transformAsync} from '@babel/core';
 import {type BuildResult, type OutputFile, build as esbuild} from 'esbuild';
-import type {BuiltFiles, Dependencies, SourceFiles} from '../types';
+import type {BuiltFiles, DefaultDefinition, SourceFiles} from '../types';
 import {type Path, globSync} from 'glob';
 import {
 	__rootDir,
+	generateArray,
 	generateBannerAndFooter,
 	generateDefinition,
 	readFileContent,
@@ -38,17 +39,22 @@ const writeFile = (outputFilePath: string, sourceCode: string): void => {
  * @private
  * @param {string} inputFilePath
  * @param {string} outputFilePath
- * @param {Dependencies} [dependencies]
+ * @param {Object} object
+ * @param {DefaultDefinition['dependencies']|undefined} [object.dependencies]
+ * @param {DefaultDefinition['externalPackages']|undefined} [object.externalPackages]
+ * @param {string} object.licenseText
  * @return {Promise<BuiltFiles>}
  */
 const build = async (
 	inputFilePath: string,
 	outputFilePath: string,
 	{
 		dependencies,
+		externalPackages,
 		licenseText,
 	}: {
-		dependencies?: Dependencies | undefined;
+		dependencies?: DefaultDefinition['dependencies'] | undefined;
+		externalPackages?: DefaultDefinition['externalPackages'] | undefined;
 		licenseText: string | undefined;
 	}
 ): Promise<BuiltFiles> => {
@@ -60,7 +66,7 @@ const build = async (
 			licenseText,
 			isProcessJs: false,
 		}),
-		external: dependencies ?? [],
+		external: generateArray(dependencies, externalPackages),
 		entryPoints: [inputFilePath],
 		outfile: outputFilePath,
 	});
@@ -87,17 +93,22 @@ const build = async (
  * @private
  * @param {string} outputFilePath
  * @param {string} sourceCode
- * @param {Dependencies} dependencies
+ * @param {Object} object
+ * @param {DefaultDefinition['dependencies']|undefined} object.dependencies
+ * @param {DefaultDefinition['externalPackages']|undefined} object.externalPackages
+ * @param {string} object.licenseText
  * @return {Promise<string>}
  */
 const bundle = async (
 	outputFilePath: string,
 	sourceCode: string,
 	{
 		dependencies,
+		externalPackages,
 		licenseText,
 	}: {
-		dependencies: Dependencies | undefined;
+		dependencies: DefaultDefinition['dependencies'] | undefined;
+		externalPackages: DefaultDefinition['externalPackages'] | undefined;
 		licenseText: string | undefined;
 	}
 ): Promise<string> => {
@@ -106,7 +117,7 @@ const bundle = async (
 		...generateBannerAndFooter({
 			licenseText,
 		}),
-		external: dependencies ?? [],
+		external: generateArray(dependencies, externalPackages),
 		stdin: {
 			contents: sourceCode,
 			resolveDir: __rootDir,
@@ -220,17 +231,22 @@ const transform = async (inputFilePath: string, sourceCode: string): Promise<str
  * @private
  * @param {string} gadgetName
  * @param {string} scriptFileName
- * @param {{dependencies:Dependencies; licenseText:string|undefined}} object
+ * @param {Object} object
+ * @param {DefaultDefinition['dependencies']|undefined} object.dependencies
+ * @param {DefaultDefinition['externalPackages']|undefined} object.externalPackages
+ * @param {string} object.licenseText
  * @return {Promise<string[]>}
  */
 const buildScript = async (
 	gadgetName: string,
 	scriptFileName: string,
 	{
 		dependencies,
+		externalPackages,
 		licenseText,
 	}: {
-		dependencies: Dependencies | undefined;
+		dependencies: DefaultDefinition['dependencies'] | undefined;
+		externalPackages: DefaultDefinition['externalPackages'] | undefined;
 		licenseText: string | undefined;
 	}
 ): Promise<string[]> => {
@@ -244,6 +260,7 @@ const buildScript = async (
 
 	const builtFiles: BuiltFiles = await build(inputFilePath, outputFilePath, {
 		dependencies,
+		externalPackages,
 		licenseText,
 	});
 	for (const builtFile of builtFiles) {
@@ -261,6 +278,7 @@ const buildScript = async (
 				const transformOutput: string = await transform(inputFilePath, text);
 				const bundleOutput: string = await bundle(outputFilePath, transformOutput, {
 					dependencies,
+					externalPackages,
 					licenseText,
 				});
 				if (!bundleOutput) {
@@ -306,18 +324,24 @@ const buildStyle = async (
 /**
  * @param {string} gadgetName The gadget name
  * @param {'script'|'style'} type The type of target files
- * @param {{dependencies?:Dependencies; files:string[]; licenseText:string|undefined}} object The dependencies of this gadget, the array of file name for this gadget and the license file content of this gadget
+ * @param {Object} object
+ * @param {DefaultDefinition['dependencies']} [object.dependencies]
+ * @param {DefaultDefinition['externalPackages']} [object.externalPackages]
+ * @param {string[]} object.files
+ * @param {string} object.licenseText
  * @return {Promise<string[]>} The array of built file names
  */
 async function buildFiles(
 	gadgetName: string,
 	type: 'script',
 	{
 		dependencies,
+		externalPackages,
 		files,
 		licenseText,
 	}: {
-		dependencies: Dependencies;
+		dependencies: DefaultDefinition['dependencies'];
+		externalPackages: DefaultDefinition['externalPackages'];
 		files: string[];
 		licenseText: string | undefined;
 	}
@@ -339,10 +363,12 @@ async function buildFiles(
 	type: 'script' | 'style',
 	{
 		dependencies,
+		externalPackages,
 		files,
 		licenseText,
 	}: {
-		dependencies?: Dependencies;
+		dependencies?: DefaultDefinition['dependencies'];
+		externalPackages?: DefaultDefinition['externalPackages'];
 		files: string[];
 		licenseText: string | undefined;
 	}
@@ -355,6 +381,7 @@ async function buildFiles(
 				outputFileNames.push(
 					...(await buildScript(gadgetName, fileName, {
 						dependencies,
+						externalPackages,
 						licenseText,
 					}))
 				);
@@ -400,20 +427,25 @@ const fallbackDefinition = (sourceFiles: SourceFiles): void => {
  * @param {SourceFiles} sourceFiles
  */
 const filterOutInvalidDependencies = (sourceFiles: SourceFiles): void => {
-	for (const gadgetFiles of Object.values(sourceFiles)) {
-		const {
-			definition: {dependencies},
-		} = gadgetFiles;
-
-		gadgetFiles.definition.dependencies = dependencies
-			.filter((dependency: string): boolean => {
-				return typeof dependency === 'string' && !!dependency.trim();
+	const filter = (array: string[]): string[] => {
+		return array
+			.filter((item: string): boolean => {
+				return typeof item === 'string' && !!item.trim();
 			})
-			.map((dependency: string): string => {
-				return trim(dependency, {
+			.map((item: string): string => {
+				return trim(item, {
 					addNewline: false,
 				});
 			});
+	};
+
+	for (const gadgetFiles of Object.values(sourceFiles)) {
+		const {
+			definition: {dependencies, externalPackages},
+		} = gadgetFiles;
+
+		gadgetFiles.definition.dependencies = filter(dependencies);
+		gadgetFiles.definition.externalPackages = filter(externalPackages);
 	}
 };
 
@@ -600,9 +632,10 @@ const generateDefinitionItem = (
 			[
 				// Keys for internal use
 				'enable',
-				'excludeSites',
 				'description',
 				'section',
+				'excludeSites',
+				'externalPackages',
 				// Keys that no need to be specified
 				'package',
 				'targets',
@@ -666,7 +699,7 @@ const generateDefinitionItem = (
  * @return {string[]} The generated file name array
  */
 const generateFileArray = (file: string | undefined, files: string[] | undefined): string[] => {
-	return file ? [file] : files ?? [];
+	return file ? generateArray(file) : generateArray(files);
 };
 
 /**

scripts/modules/utils/general-util.ts

@@ -66,6 +66,31 @@ const writeFileContent = (filePath: number | string, fileContent: string): void
 	closeSync(fileDescriptor);
 };
 
+/**
+ * Generate an array and filter out null and undefined values
+ *
+ * @param {T} args The given arguments
+ * @return {NonNullable<T>[]} The generated array
+ */
+function generateArray<T extends []>(...args: (T | T[])[]): NonNullable<T>[];
+function generateArray<T = unknown>(...args: (T | T[])[]): NonNullable<T>[];
+// eslint-disable-next-line func-style
+function generateArray<T>(...args: (T | T[])[]): T[] {
+	return args.flatMap((arg) => {
+		if (arg === null || arg === undefined) {
+			return [];
+		}
+
+		if (Array.isArray(arg)) {
+			return arg.filter((item): boolean => {
+				return item !== null && item !== undefined;
+			});
+		}
+
+		return [arg];
+	});
+}
+
 /**
  * Sort an object
  *
@@ -299,6 +324,7 @@ export {
 	exec,
 	readFileContent,
 	writeFileContent,
+	generateArray,
 	sortObject,
 	trim,
 	prompt,