@bluelovers/jest-config 1.1.11 → 1.1.13

package/src/defaults.ts

@@ -1,28 +1,48 @@
-import { IOptions, requireResolveExtra } from '@yarn-tool/require-resolve';
+/**
+ * 預設配置模組 - 提供 Jest 各項預設設定值
+ * Default Configuration Module - Provides default settings for Jest
+ */
+
 import { ITSToWriteableArray } from 'ts-type/lib/helper/array/readonly';
-import { ITSWriteable } from 'ts-type/lib/helper/readonly';
-import { _handleFileExtensions, _requireResolve } from './helper';
-import { InitialOptionsTsJest } from 'ts-jest';
-import { defaultTsJestTransformerOptions } from './plugin/ts-jest';
-import { IRuntime } from './types';
 
+/**
+ * 取得預設的測試檔案副檔名列表
+ * Get default test file extensions list
+ *
+ * 定義哪些副檔名的檔案會被視為測試檔案
+ * Defines which file extensions are recognized as test files
+ *
+ * @returns {string[]} 測試檔案副檔名陣列 / Array of test file extensions
+ */
 export function defaultTestFileExtensions()
 {
 	const value = [
+		// TypeScript 相關副檔名 / TypeScript related extensions
+
 		'ts',
 		'tsx',
 		'mts',
 		'cts',
-//	'js',
-//	'jsx',
-//	'mjs',
-//	'cjs',
+
+		// JavaScript 相關副檔名（目前註解掉） / JavaScript related extensions (currently commented)
+
+		//'js',
+		//'jsx',
+		//'mjs',
+		//'cjs',
 	] as const;
 	return value as ITSToWriteableArray<typeof value>;
 }
 
 /**
+ * 取得預設的模組檔案副檔名列表
+ * Get default module file extensions list
+ *
+ * 定義模組解析時搜尋的副檔名順序
+ * Defines the order of extensions to search during module resolution
+ *
  * @see https://jestjs.io/docs/configuration#options
+ * @returns {string[]} 模組檔案副檔名陣列 / Array of module file extensions
  */
 export function defaultModuleFileExtensions()
 {
@@ -41,6 +61,15 @@ export function defaultModuleFileExtensions()
 	return value as ITSToWriteableArray<typeof value>;
 }
 
+/**
+ * 取得預設的覆蓋率檔案副檔名列表
+ * Get default coverage file extensions list
+ *
+ * 定義哪些副檔名的檔案會被納入覆蓋率統計
+ * Defines which file extensions are included in coverage statistics
+ *
+ * @returns {string[]} 覆蓋率檔案副檔名陣列 / Array of coverage file extensions
+ */
 export function defaultCoverageFileExtensions()
 {
 	const value = [
@@ -58,6 +87,15 @@ export function defaultCoverageFileExtensions()
 	return value as ITSToWriteableArray<typeof value>;
 }
 
+/**
+ * 取得預設的轉換器檔案副檔名列表
+ * Get default transformer file extensions list
+ *
+ * 定義哪些副檔名的檔案需要經過 ts-jest 轉換
+ * Defines which file extensions need to be transformed by ts-jest
+ *
+ * @returns {string[]} 轉換器檔案副檔名陣列 / Array of transformer file extensions
+ */
 export function defaultTransformFileExtensions()
 {
 	const value = [
@@ -69,6 +107,15 @@ export function defaultTransformFileExtensions()
 	return value as ITSToWriteableArray<typeof value>;
 }
 
+/**
+ * 取得預設的覆蓋率忽略路徑模式
+ * Get default coverage path ignore patterns
+ *
+ * 定義哪些路徑的檔案不納入覆蓋率統計
+ * Defines which paths are excluded from coverage statistics
+ *
+ * @returns {string[]} 覆蓋率忽略路徑模式陣列 / Array of coverage ignore patterns
+ */
 export function defaultCoveragePathIgnorePatterns()
 {
 	const value = [
@@ -88,6 +135,15 @@ export function defaultCoveragePathIgnorePatterns()
 	return value as ITSToWriteableArray<typeof value>;
 }
 
+/**
+ * 取得預設的測試路徑忽略模式
+ * Get default test path ignore patterns
+ *
+ * 定義哪些路徑的檔案不會被視為測試檔案
+ * Defines which paths are excluded from test file recognition
+ *
+ * @returns {string[]} 測試路徑忽略模式陣列 / Array of test path ignore patterns
+ */
 export function defaultTestPathIgnorePatterns()
 {
 	const value = [
@@ -103,47 +159,3 @@ export function defaultTestPathIgnorePatterns()
 	return value as ITSToWriteableArray<typeof value>;
 }
 
-export function defaultTransform(runtime: IRuntime)
-{
-	const paths: string[] = [
-		requireResolveExtra('@bluelovers/jest-config').result,
-	].filter(Boolean);
-
-	const opts: IOptions = {
-		includeGlobal: true,
-		includeCurrentDirectory: true,
-		paths,
-	};
-
-	let ts_transform: InitialOptionsTsJest["transform"][string] = _requireResolve('ts-jest') as 'ts-jest';
-
-	ts_transform = [ts_transform, defaultTsJestTransformerOptions(runtime)];
-
-	const { result: tsd } = requireResolveExtra('jest-tsd-transform', opts);
-
-	if (tsd?.length)
-	{
-		const { result: chain } = requireResolveExtra('jest-chain-transform', opts);
-
-		if (chain?.length)
-		{
-			ts_transform = [
-				chain as 'jest-chain-transform', {
-					transformers: [
-						tsd as 'jest-tsd-transform',
-						// @ts-ignore
-						ts_transform as 'ts-jest',
-					],
-				},
-			] satisfies [
-				string,
-				Record<string, unknown>
-			]
-		}
-	}
-
-	const value = {
-		[`.(${_handleFileExtensions(defaultTransformFileExtensions(), '|')})$`]: ts_transform,
-	} as const
-	return value as ITSWriteable<typeof value>;
-}

package/src/helper.ts

@@ -1,36 +1,87 @@
+/**
+ * 輔助函數模組 - 提供 Jest 配置處理的通用工具函數
+ * Helper Functions Module - Provides utility functions for Jest configuration processing
+ */
+
 import { requireResolveCore, requireResolveExtra } from '@yarn-tool/require-resolve';
-import { InitialOptionsTsJest } from 'ts-jest';
 import { ITSValueOrArrayMaybeReadonly } from 'ts-type/lib/type/base';
 import { console } from 'debug-color2';
 import { IJestConfig } from './types';
 import { defaultTestFileExtensions } from './defaults';
 import { array_unique } from 'array-hyper-unique';
 
+/**
+ * 解析模組路徑的內部輔助函數
+ * Internal helper function for resolving module paths
+ *
+ * 優先從 @bluelovers/tsdx 或 tsdx 套件路徑中搜尋，若失敗則使用標準 require.resolve
+ * Searches from @bluelovers/tsdx or tsdx package paths first, falls back to standard require.resolve
+ *
+ * @param {string} name - 要解析的模組名稱 / Module name to resolve
+ * @returns {string} 解析後的模組絕對路徑 / Resolved absolute module path
+ */
 export function _requireResolve(name: string)
 {
+	/**
+	 * 搜尋路徑列表，包含 tsdx 相關套件路徑
+	 * Search paths list including tsdx related package paths
+	 */
 	const paths = [
 		requireResolveExtra('@bluelovers/tsdx').result,
 		requireResolveExtra('tsdx').result,
 	].filter(Boolean);
 
+	/**
+	 * 使用增強的解析器進行模組解析
+	 * Use enhanced resolver for module resolution
+	 */
 	const result = requireResolveCore(name, {
 		includeGlobal: true,
 		includeCurrentDirectory: true,
 		paths,
 	});
 
+	// 輸出除錯資訊 / Output debug info
 	console.debug('[require.resolve]', name, '=>', result)
 
 	return result
 }
 
-export function makeTestRegexConfig<T extends string>(testExt: ITSValueOrArrayMaybeReadonly<T>): Pick<InitialOptionsTsJest, 'testMatch' | 'testRegex'>
+export function _requireResolve2(name: string)
+{
+	return requireResolveExtra(name, {
+		includeGlobal: true,
+		includeCurrentDirectory: true,
+	})
+}
+
+/**
+ * 建立測試正則表達式配置
+ * Create test regex configuration
+ *
+ * 根據測試檔案副檔名生成 testMatch 和 testRegex 配置
+ * Generates testMatch and testRegex configs based on test file extensions
+ *
+ * @param {T} testExt - 測試檔案副檔名或陣列 / Test file extension(s)
+ * @returns {object} 包含 testMatch 和 testRegex 的配置物件 / Object containing testMatch and testRegex
+ */
+export function makeTestRegexConfig<T extends string>(testExt: ITSValueOrArrayMaybeReadonly<T>): Pick<IJestConfig, 'testMatch' | 'testRegex'>
 {
+	// 若未提供副檔名則使用預設值 / Use default if no extensions provided
 	testExt ??= defaultTestFileExtensions() as any as T[];
 	const _testExt = _handleFileExtensions(testExt, '|')
 
 	return {
+		/** 不使用 testMatch（使用 testRegex 替代） / Not using testMatch (using testRegex instead) */
 		testMatch: null as undefined,
+		/**
+		 * 測試檔案正則表達式模式陣列
+		 * Test file regex patterns array
+		 *
+		 * 匹配以下模式:
+		 * - *.test.ts, *.spec.ts, *.tests.ts
+		 * - __tests__ 目錄下的測試檔案
+		 */
 		testRegex: [
 			`\\.(tests?|spec)\\.(${_testExt})$`,
 			`__tests__\/\.*\\.(tests?|spec)\\.(${_testExt})$`,
@@ -38,34 +89,80 @@ export function makeTestRegexConfig<T extends string>(testExt: ITSValueOrArrayMa
 	}
 }
 
+/**
+ * 處理檔案副檔名陣列的核心函數
+ * Core function for processing file extension arrays
+ *
+ * 將輸入轉換為唯一的副檔名陣列
+ * Converts input to unique array of extensions
+ *
+ * @param {T} testExt - 輸入的副檔名（可為陣列或單一值） / Input extension(s)
+ * @returns {T[]} 唯一的副檔名陣列 / Unique array of extensions
+ */
 export function _handleFileExtensionsCore<T extends string>(testExt: ITSValueOrArrayMaybeReadonly<T>)
 {
 	return array_unique([testExt].flat()) as T[]
 }
 
+/**
+ * 處理檔案副檔名並以指定分隔符連接
+ * Process file extensions and join with specified separator
+ *
+ * @param {T} testExt - 輸入的副檔名（可為陣列或單一值） / Input extension(s)
+ * @param {string} sep - 分隔符號 / Separator string
+ * @returns {string} 連接後的副檔名字串 / Joined extension string
+ */
 export function _handleFileExtensions<T extends string>(testExt: ITSValueOrArrayMaybeReadonly<T>, sep: string)
 {
 	return _handleFileExtensionsCore(testExt).join(sep)
 }
 
+/**
+ * 修復 Jest 配置中的相容性問題
+ * Fix compatibility issues in Jest configuration
+ *
+ * 處理 testMatch/testRegex 互斥問題以及 testURL 已棄用選項的遷移
+ * Handles testMatch/testRegex mutual exclusivity and testURL deprecated option migration
+ *
+ * @param {T} jestConfig - 原始 Jest 配置 / Original Jest configuration
+ * @returns {T} 修復後的 Jest 配置 / Fixed Jest configuration
+ */
 export function fixJestConfig<T extends IJestConfig>(jestConfig: T): T
 {
+	/**
+	 * testMatch 和 testRegex 是互斥的選項
+	 * testMatch and testRegex are mutually exclusive options
+	 *
+	 * 如果同時設定兩者會造成衝突，因此需要清除其中一個
+	 * Having both set causes conflicts, so we need to clear one
+	 */
 	if (jestConfig.testMatch)
 	{
+		// 如果使用 testMatch，清除 testRegex
+		// If using testMatch, clear testRegex
 		jestConfig.testRegex = null;
 	}
 	else if (jestConfig.testRegex)
 	{
+		// 如果使用 testRegex，清除 testMatch
+		// If using testRegex, clear testMatch
 		jestConfig.testMatch = null;
 	}
 
 	/**
-	 * Option "testURL" was replaced by passing the URL via "testEnvironmentOptions.url".
+	 * testURL 選項已被 testEnvironmentOptions.url 取代
+	 * testURL option has been replaced by testEnvironmentOptions.url
+	 *
+	 * @see https://jestjs.io/docs/configuration#testurl-string
 	 */
 	if (jestConfig.testURL)
 	{
+		// 確保 testEnvironmentOptions 物件存在
+		// Ensure testEnvironmentOptions object exists
 		jestConfig.testEnvironmentOptions ??= {};
 
+		// 將 testURL 遷移到 testEnvironmentOptions.url
+		// Migrate testURL to testEnvironmentOptions.url
 		jestConfig.testURL = (jestConfig.testEnvironmentOptions['url'] ??= jestConfig.testURL) as string
 	}
 

package/src/index.ts

@@ -1,70 +1,127 @@
+/**
+ * 核心入口模組 - 提供 Jest 配置混合功能
+ * Core Entry Module - Provides Jest configuration mixing functionality
+ */
+
 import { _requireResolve, fixJestConfig, makeTestRegexConfig } from './helper';
 import {
 	defaultCoveragePathIgnorePatterns,
 	defaultModuleFileExtensions,
 	defaultTestFileExtensions,
-	defaultTestPathIgnorePatterns, defaultTransform,
+	defaultTestPathIgnorePatterns,
+
 } from './defaults';
 import { IOptionsPrintJestConfigInfo, printJestConfigInfo } from './print';
 import { IJestConfig } from './types';
 import { getJestCacheDirectory } from 'jest-cache-directory';
+import { defaultTransform } from './default-transform';
+import { defaultSetupFiles } from './default-setup-fles';
 
+// 重新匯出輔助函數和類型 / Re-export helper functions and types
 export * from './helper';
 export * from './defaults';
 export * from './print';
+export { defaultTransform } from './default-transform';
+export { defaultSetupFiles } from './default-setup-fles';
 
+/** Jest 快取目錄路徑 / Jest cache directory path */
 const cacheDirectory = getJestCacheDirectory();
 
 export { cacheDirectory }
 
+/**
+ * 混合 Jest 配置函數 - 將預設配置與使用者自定義配置合併
+ * Mix Jest configuration function - Merges default config with user custom config
+ *
+ * 此函數提供了一個完整的 Jest 配置模板，包含 TypeScript 支援、快取管理、覆蓋率收集等功能
+ * This function provides a complete Jest configuration template with TypeScript support,
+ * cache management, coverage collection, and more.
+ *
+ * @param {T} jestConfig - 使用者自定義的 Jest 配置 / User custom Jest configuration
+ * @param {boolean} autoPrint - 是否自動印出配置資訊 / Whether to auto print config info
+ * @param {IOptionsPrintJestConfigInfo} options - 印出配置的選項 / Options for printing config
+ * @returns {T} 合併後的完整 Jest 配置 / Merged complete Jest configuration
+ */
 export function mixinJestConfig<T extends IJestConfig>(jestConfig?: T, autoPrint?: boolean,
 	options?: IOptionsPrintJestConfigInfo)
 {
 	// @ts-ignore
+	// 如果未提供配置則使用空對象 / Use empty object if no config provided
 	jestConfig ??= {};
+
+	/**
+	 * 建立基礎 Jest 配置物件
+	 * Create base Jest configuration object
+	 *
+	 * 包含以下預設設定:
+	 * - 快取目錄管理 / Cache directory management
+	 * - 單一工作執行緒以確保測試穩定性 / Single worker for test stability
+	 * - 自動清除模擬物件 / Auto clear mocks
+	 * - 無測試時仍通過 / Pass with no tests
+	 * - TypeScript 檔案支援 / TypeScript file support
+	 * - 覆蓋率使用 v8 提供者 / Coverage using v8 provider
+	 */
 	const newJestConfig = fixJestConfig({
 		globals: {
+			// ts-jest 全域配置預留位置 / ts-jest global config placeholder
 //			'ts-jest': {
 //				//tsconfig: 'tsconfig.spec.json',
 //			},
 		},
+		/** 快取目錄路徑 / Cache directory path */
 		cacheDirectory,
+		/** 最大工作執行緒數（設為 1 確保測試順序執行） / Max workers (set to 1 for sequential execution) */
 		maxWorkers: 1,
+		/** 每次測試前清除模擬物件 / Clear mocks before each test */
 		clearMocks: true,
+		/** 無測試檔案時仍視為通過 / Pass even when no test files */
 		passWithNoTests: true,
+		/** 模組檔案副檔名列表 / Module file extensions list */
 		moduleFileExtensions: defaultModuleFileExtensions(),
+		// 測試環境設定（預設 node） / Test environment setting
 		//testEnvironment: 'node',
+		// 測試匹配模式 / Test match patterns
 		//testMatch: ['**/*.test.ts', '**/*.spec.ts'],
+		// 合併測試正則配置 / Merge test regex config
 		...makeTestRegexConfig(defaultTestFileExtensions()),
+		/** 測試路徑忽略模式 / Test path ignore patterns */
 		testPathIgnorePatterns: defaultTestPathIgnorePatterns(),
+		// 測試執行器設定 / Test runner setting
 		//testRunner: 'jest-circus/runner',
-		setupFilesAfterEnv: [
-			//"jest-chain",
-			//"jest-extended/all",
-			//"jest-extended-extra",
-			//"jest-num-close-with",
-			/**
-			 * https://medium.com/doctolib/how-to-run-the-same-jest-test-suite-across-several-platforms-jest-os-detection-plugin-included-f8113832482b
-			 * https://github.com/doctolib/jest-os-detection
-			 */
-			//'jest-os-detection',
-		],
+		/** 環境設置後載入的檔案 / Files to load after environment setup */
+		...defaultSetupFiles(),
+		// 轉換器設定（後面單獨處理） / Transform setting (handled separately below)
 		//transform: defaultTransform(),
+		/** 詳細輸出模式 / Verbose output mode */
 		verbose: true,
 		/**
-		 * if didn't set `coverageProvider` to `v8`
-		 * with `collectCoverage` `true`, nodejs debug point maybe will fail
+		 * 覆蓋率提供者設定為 v8
+		 * Coverage provider set to v8
+		 *
+		 * 若使用 collectCoverage: true 時未設為 v8，Node.js 除錯點可能會失效
+		 * If not set to v8 with collectCoverage: true, Node.js debug points may fail
 		 */
 		coverageProvider: 'v8',
+		/** 是否收集覆蓋率 / Whether to collect coverage */
 		collectCoverage: false,
+		/** 覆蓋率忽略路徑模式 / Coverage path ignore patterns */
 		coveragePathIgnorePatterns: defaultCoveragePathIgnorePatterns(),
 		/**
-		 * https://github.com/facebook/jest/issues/9771#issuecomment-872764344
+		 * Jest 模組解析器參考 / Jest module resolver reference
+		 * @see https://github.com/facebook/jest/issues/9771#issuecomment-872764344
 		 */
 		//resolver: 'jest-node-exports-resolver',
+		// 合併使用者自定義配置 / Merge user custom config
 		...jestConfig,
 	});
 
+	/**
+	 * 設定轉換器（如果尚未設定）
+	 * Set up transform (if not already set)
+	 *
+	 * 使用預設的 ts-jest 轉換器，並支援 jest-tsd-transform 和 jest-chain-transform 鏈式轉換
+	 * Uses default ts-jest transformer with support for jest-tsd-transform and jest-chain-transform chaining
+	 */
 	newJestConfig.transform ??= defaultTransform({
 		jestConfig,
 		autoPrint,
@@ -72,9 +129,14 @@ export function mixinJestConfig<T extends IJestConfig>(jestConfig?: T, autoPrint
 		newJestConfig,
 	});
 
+	// 如果啟用自動印出，則顯示配置資訊 / If autoPrint enabled, display config info
 	autoPrint && printJestConfigInfo(newJestConfig, options);
 
 	return newJestConfig
 }
 
+/**
+ * 預設匯出 - mixinJestConfig 函數
+ * Default export - mixinJestConfig function
+ */
 export default mixinJestConfig

package/src/plugin/ts-jest.ts

@@ -1,23 +1,103 @@
+/**
+ * ts-jest 轉換器配置模組 - 提供 ts-jest 的預設選項設定
+ * ts-jest Transformer Configuration Module - Provides default options for ts-jest
+ */
+
 import { TsJestTransformerOptions } from 'ts-jest';
 import { IRuntime } from '../types';
+import { array_unique } from 'array-hyper-unique';
 
+/**
+ * 取得預設的 ts-jest 轉換器選項
+ * Get default ts-jest transformer options
+ *
+ * 此函數會合併使用者自定義的 ts-jest 設定與預設值，確保測試環境的最佳配置
+ * This function merges user custom ts-jest settings with defaults for optimal test environment
+ *
+ * 主要調整項目:
+ * - 禁用輸出檔案（noEmit: true）
+ * - 允許未使用的參數和標籤（用於測試開發）
+ * - 禁用嚴格的型別檢查選項（確保測試能順利執行）
+ *
+ * Key adjustments:
+ * - Disable file output (noEmit: true)
+ * - Allow unused parameters and labels (for test development)
+ * - Disable strict type checking options (ensure tests run smoothly)
+ *
+ * @param runtime - 執行時期配置，包含原始 Jest 配置 / Runtime configuration containing original Jest config
+ * @returns ts-jest 轉換器選項 / ts-jest transformer options
+ */
 export function defaultTsJestTransformerOptions(runtime: IRuntime)
 {
-	const old: TsJestTransformerOptions = runtime.jestConfig.globals?.['ts-jest'] ?? {};
+	/**
+	 * 取得使用者自定義的 ts-jest 設定（如果存在）
+	 * Get user custom ts-jest settings (if exists)
+	 *
+	 * 從 jestConfig.globals['ts-jest'] 中讀取既有設定
+	 * Reads existing settings from jestConfig.globals['ts-jest']
+	 */
+	const old: TsJestTransformerOptions = (runtime.jestConfig.globals?.['ts-jest'] ?? {}) as TsJestTransformerOptions;
 
+	/**
+	 * 處理 tsconfig 設定物件
+	 * Process tsconfig settings object
+	 *
+	 * 如果使用者提供了物件形式的 tsconfig，則使用它；否則建立空物件
+	 * Uses user-provided object tsconfig or creates empty object
+	 */
 	const tsconfig = typeof old.tsconfig === 'object' ? old.tsconfig : {};
 
+	const types = array_unique([...(tsconfig.types ?? []), 'jest']);
+
+	/**
+	 * 回傳合併後的 ts-jest 選項
+	 * Return merged ts-jest options
+	 *
+	 * 預設值優先於使用者設定，但使用者設定可覆蓋預設值
+	 * Defaults take precedence but user settings can override them
+	 */
 	return {
+		// 保留既有設定 / Preserve existing settings
 		...old,
 		tsconfig: {
+			/**
+			 * 不輸出編譯後的檔案（僅用於型別檢查和轉換）
+			 * Don't emit compiled files (only for type checking and transformation)
+			 */
 			noEmit: true,
+			/**
+			 * 不僅輸出宣告檔案（確保完整編譯）
+			 * Don't emit declaration only (ensure full compilation)
+			 */
 			emitDeclarationOnly: false,
+			/**
+			 * 允許未使用的參數（測試中常見佔位符）
+			 * Allow unused parameters (common placeholders in tests)
+			 */
 			noUnusedParameters: false,
+			/**
+			 * 允許未使用的標籤（方便測試標記）
+			 * Allow unused labels (convenient for test marking)
+			 */
 			allowUnusedLabels: true,
+			/**
+			 * 允許未使用的區域變數（測試開發彈性）
+			 * Allow unused locals (flexibility in test development)
+			 */
 			noUnusedLocals: false,
+			/**
+			 * 允許從索引簽名進行屬性存取（簡化測試語法）
+			 * Allow property access from index signature (simpler test syntax)
+			 */
 			noPropertyAccessFromIndexSignature: false,
+			/**
+			 * 允許隱含的 any 型別（減少測試中的型別宣告負擔）
+			 * Allow implicit any type (reduce type declaration overhead in tests)
+			 */
 			noImplicitAny: false,
+			// 合併使用者自定義的 tsconfig 設定 / Merge user custom tsconfig settings
 			...tsconfig,
+			types,
 		},
-	} satisfies TsJestTransformerOptions
+	} as TsJestTransformerOptions
 }