@yarn-tool/static-file 3.0.4 → 3.0.5

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.0.5](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/static-file@3.0.4...@yarn-tool/static-file@3.0.5) (2026-03-02)
+
+
+### BREAKING CHANGES
+
+* **static-file:** 重新組織 const.ts 中的檔案映射
+
+
+
+### 🐛　Bug Fixes
+
+* **config:** 更新 npmrc/pnpm-workspace.yaml 工作區設定 ([c127220](https://github.com/bluelovers/ws-yarn-workspaces/commit/c127220ce308de9409a1bc3b72b5bcf2e01432ce))
+* **static-file:** 補齊 gitignore 規則並修正 jest 配置註解 ([d2e7101](https://github.com/bluelovers/ws-yarn-workspaces/commit/d2e710116f3a3a3632a21839cd9629edaee66a8a))
+
+
+### ✨　Features
+
+* **yarn-tool:** 簡化靜態檔案複製配置並新增測試路徑常數 ([8f7660c](https://github.com/bluelovers/ws-yarn-workspaces/commit/8f7660c6df39b7cfd2c69a019f02a5f840193092))
+
+
+### 📦　Code Refactoring
+
+* **jest-config:** 更改模組載入機制並完善文件註解 ([8c1efb9](https://github.com/bluelovers/ws-yarn-workspaces/commit/8c1efb94efc6ca5e6f2a8eec20c428a6449fc5e7))
+* **static-file:** 重構 tsconfig 靜態檔案映射並更新 gitignore ([e79863e](https://github.com/bluelovers/ws-yarn-workspaces/commit/e79863ef29cb41a28d7fa53082a676907c149368))
+
+
+### 📚　Documentation
+
+* **@yarn-tool/ws-find-up-paths:** 新增雙語 JSDoc 註解並更新 README 文件 ([514a876](https://github.com/bluelovers/ws-yarn-workspaces/commit/514a876771481be67af4a41853582776dc444bb9))
+* **setup-module-env:** 為 tsdx 設定模組添加完整的 JSDoc 文檔註釋 ([5def98a](https://github.com/bluelovers/ws-yarn-workspaces/commit/5def98ab905bb3dc50d2d00e5f3f3d4da5d23cf3))
+
+
+### 🛠　Build System
+
+* update build ([51d49ad](https://github.com/bluelovers/ws-yarn-workspaces/commit/51d49adaa1f1fbfac4a299007dbf406d7ee7a4c7))
+
+
+### ♻️　Chores
+
+* Add test config and global types for tsdx ([88a8df6](https://github.com/bluelovers/ws-yarn-workspaces/commit/88a8df6eef5dc59d9e0d9268b21706dceb5ab2a1))
+* update README installation commands and add JSDoc comments ([2caaee5](https://github.com/bluelovers/ws-yarn-workspaces/commit/2caaee5185b452ec82768faacc27422aec8104b1))
+* add __root.ts test utility to workspace packages ([a771727](https://github.com/bluelovers/ws-yarn-workspaces/commit/a7717278883c86d9ed8ab89f42070d3385c173a7))
+* **deps:** 升級路徑與檔案系統相關依賴版本 ([78d395b](https://github.com/bluelovers/ws-yarn-workspaces/commit/78d395b5469feecc85f250ca2d8b4977161e7618))
+* **deps:** 升級多項依賴套件版本 ([1382602](https://github.com/bluelovers/ws-yarn-workspaces/commit/1382602ca94ff236b251fd1481b6332468de4621))
+* **static-file:** 重新組織 const.ts 中的檔案映射 ([43b04e0](https://github.com/bluelovers/ws-yarn-workspaces/commit/43b04e0884b4dcf1ecd39267a68893291136788c))
+
+
+
 ## [3.0.4](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/static-file@3.0.3...@yarn-tool/static-file@3.0.4) (2025-09-07)
 
 

package/README.md

@@ -1,12 +1,17 @@
 # README.md
 
-    <%= description %>
+    
 
 ## install
 
 ```bash
-yarn add <%= name %>
-yarn-tool add <%= name %>
-yt add <%= name %>
+yarn add @yarn-tool/static-file
+
+yarn-tool add @yarn-tool/static-file
+yt add @yarn-tool/static-file
+
+pnpm add @yarn-tool/static-file
+
+npm install @yarn-tool/static-file
 ```
 

package/__root.d.ts

@@ -1 +1,29 @@
+/**
+ * Static files root directory constant / 靜態檔案根目錄常量
+ *
+ * This module exports the root directory path where static files are located.
+ * 此模組匯出靜態檔案所在的根目錄路徑。
+ *
+ * The `__STATIC_ROOT` constant is used internally to locate the static files
+ * that will be copied to target directories.
+ * `__STATIC_ROOT` 常量在內部用於定位將被複製到目標目錄的靜態檔案。
+ *
+ * @module __root
+ *
+ * @example
+ * ```typescript
+ * import { __STATIC_ROOT } from '@yarn-tool/static-file/__root';
+ *
+ * console.log(__STATIC_ROOT);
+ * // Outputs the path to the static files directory
+ * // 輸出靜態檔案目錄的路徑
+ * ```
+ */
+/**
+ * The root directory path of the static files / 靜態檔案的根目錄路徑
+ *
+ * This is the directory where the `file/` folder containing all static
+ * configuration templates is located.
+ * 這是包含所有靜態配置模板的 `file/` 資料夾所在的目錄。
+ */
 export declare const __STATIC_ROOT: string;

package/__root.js

@@ -1,5 +1,33 @@
 "use strict";
+/**
+ * Static files root directory constant / 靜態檔案根目錄常量
+ *
+ * This module exports the root directory path where static files are located.
+ * 此模組匯出靜態檔案所在的根目錄路徑。
+ *
+ * The `__STATIC_ROOT` constant is used internally to locate the static files
+ * that will be copied to target directories.
+ * `__STATIC_ROOT` 常量在內部用於定位將被複製到目標目錄的靜態檔案。
+ *
+ * @module __root
+ *
+ * @example
+ * ```typescript
+ * import { __STATIC_ROOT } from '@yarn-tool/static-file/__root';
+ *
+ * console.log(__STATIC_ROOT);
+ * // Outputs the path to the static files directory
+ * // 輸出靜態檔案目錄的路徑
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.__STATIC_ROOT = void 0;
+/**
+ * The root directory path of the static files / 靜態檔案的根目錄路徑
+ *
+ * This is the directory where the `file/` folder containing all static
+ * configuration templates is located.
+ * 這是包含所有靜態配置模板的 `file/` 資料夾所在的目錄。
+ */
 exports.__STATIC_ROOT = __dirname;
 //# sourceMappingURL=__root.js.map

package/__root.js.map

@@ -1 +1 @@
-{"version":3,"file":"__root.js","sourceRoot":"","sources":["__root.ts"],"names":[],"mappings":";;;AAAa,QAAA,aAAa,GAAG,SAAS,CAAC","sourcesContent":["export const __STATIC_ROOT = __dirname;\n"]}
+{"version":3,"file":"__root.js","sourceRoot":"","sources":["__root.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH;;;;;;GAMG;AACU,QAAA,aAAa,GAAG,SAAS,CAAC","sourcesContent":["/**\n * Static files root directory constant / 靜態檔案根目錄常量\n *\n * This module exports the root directory path where static files are located.\n * 此模組匯出靜態檔案所在的根目錄路徑。\n *\n * The `__STATIC_ROOT` constant is used internally to locate the static files\n * that will be copied to target directories.\n * `__STATIC_ROOT` 常量在內部用於定位將被複製到目標目錄的靜態檔案。\n *\n * @module __root\n *\n * @example\n * ```typescript\n * import { __STATIC_ROOT } from '@yarn-tool/static-file/__root';\n *\n * console.log(__STATIC_ROOT);\n * // Outputs the path to the static files directory\n * // 輸出靜態檔案目錄的路徑\n * ```\n */\n\n/**\n * The root directory path of the static files / 靜態檔案的根目錄路徑\n *\n * This is the directory where the `file/` folder containing all static\n * configuration templates is located.\n * 這是包含所有靜態配置模板的 `file/` 資料夾所在的目錄。\n */\nexport const __STATIC_ROOT = __dirname;\n"]}

package/file/.gitignore

@@ -0,0 +1,10 @@
+__root_ws.js
+__root_ws.d.ts
+__root.js
+__root.d.ts
+temp.js
+temp.d.ts
+index.cjs
+index.d.cts
+index.mjs
+index.d.mts

package/file/README.md

@@ -2,11 +2,21 @@
 
     <%= description %>
 
-## install
+## 安裝 (Installation)
 
 ```bash
+# 使用 yarn / Using yarn
 yarn add <%= name %>
+
+# 使用 yarn-tool / Using yarn-tool
 yarn-tool add <%= name %>
+# yt 是 yarn-tool 的別名 / yt is an alias for yarn-tool
 yt add <%= name %>
+
+# 使用 pnpm / Using pnpm
+pnpm add <%= name %>
+
+# 使用 npm / Using npm
+npm install <%= name %>
 ```
 

package/file/gitignore

@@ -132,6 +132,7 @@ bin/**/*.d.cts
 *.tgz
 /tsconfig.json.tpl
 /.eslintrc.json.tpl
+!test/tsconfig.json
 !tsconfig.json
 !.eslintrc.json
 yarn-error.log
@@ -168,7 +169,11 @@ coverage
 tsconfig.esm.json.tpl
 
 .browserslistrc
+
 .nvmrc
+.node-version
+!/.nvmrc
+!/.node-version
 
 /.eslintignore
 /package.d.ts
@@ -226,3 +231,13 @@ dist/*.umd.*.*s
 !/.storybook/
 
 test/fixtures/.gitkeep
+
+!.clinerules
+!.kilocode
+!.cline
+!.junie
+!.gemini
+!.copilot
+!.claude
+!.agents
+!.aiassistant

package/file/jest.config.auto.js

@@ -1,18 +1,59 @@
 // @ts-check
 
+/**
+ * Jest 自動配置模組
+ * Jest Auto Configuration Module
+ *
+ * 此模組自動偵測並配置 Jest 測試環境，支援多層級配置解析
+ * This module automatically detects and configures Jest test environment with multi-level configuration resolution
+ */
+
 const { basename, extname, dirname } = require('path');
 
 /**
- * // @type { import('@jest/types').Config.InitialOptions }
- * @type { import('ts-jest').InitialOptionsTsJest }
+ * Jest 配置物件
+ * Jest configuration object
+ *
+ * @type { import('ts-jest').JestConfigWithTsJest }
  */
 let jestConfig = {
 
 }
 
 /**
- * @param {string} name
- * @returns {string}
+ * 嘗試使用 `@yarn-tool/require-resolve` 載入模組的工具函數
+ * Utility function for lazy loading modules
+ *
+ * @param {string} name - 模組名稱 Module name
+ * @param {string[]} [paths] - 搜尋路徑 Search paths
+ * @private
+ */
+function _lazyRequire(name, paths)
+{
+	let m;
+	try
+	{
+		// 嘗試使用 require-resolve 工具載入模組
+		// Try to load module using require-resolve tool
+		m = require('@yarn-tool/require-resolve').requireExtra(name, {
+			includeCurrentDirectory: true,
+			includeGlobal: true,
+			paths,
+		});
+	}
+	catch (e) {}
+
+	// 如果失敗則使用標準 require
+	// If failed, use standard require
+	return typeof m === 'undefined' ? require(name) : m;
+}
+
+/**
+ * 嘗試使用 `@yarn-tool/require-resolve` 解析模組路徑的工具函數
+ * Utility function for resolving module paths
+ *
+ * @param {string} name - 模組名稱 Module name
+ * @returns {string} - 解析後的路徑 Resolved path
  * @private
  */
 function _requireResolve(name)
@@ -21,9 +62,11 @@ function _requireResolve(name)
 
 	try
 	{
-		// @ts-ignore
-		const { requireResolveExtra, requireResolveCore } = require('@yarn-tool/require-resolve');
+		/** @type {import('@yarn-tool/require-resolve')} */
+		const { requireResolveExtra, requireResolveCore } = _lazyRequire('@yarn-tool/require-resolve');
 
+		// 嘗試從多個路徑解析 TSDX 相關模組
+		// Try to resolve TSDX related modules from multiple paths
 		const paths = [
 			requireResolveExtra('@bluelovers/tsdx').result,
 			requireResolveExtra('tsdx').result,
@@ -40,6 +83,8 @@ function _requireResolve(name)
 
 	}
 
+	// 如果都失敗，使用標準 resolve
+	// If all failed, use standard resolve
 	result = result || require.resolve(name);
 
 	console.info('[require.resolve]', name, '=>', result)
@@ -47,19 +92,27 @@ function _requireResolve(name)
 	return result
 }
 
-let _ok = true;
+// 配置解析狀態標誌
+// Configuration resolution status flag
+let _isNeedConfig = true;
 
 try
 {
+	// 第一層：搜尋工作區中的配置檔案
+	// First level: Search for configuration files in workspace
 	if (!jestConfig.preset)
 	{
+		/** @type {import('@yarn-tool/ws-find-up-paths')} */
+		const { findUpPathsWorkspaces } = _lazyRequire('@yarn-tool/ws-find-up-paths');
 
-		let result = require('@yarn-tool/ws-find-up-paths').findUpPathsWorkspaces([
+		// 向上搜尋 jest-preset.js 和 jest.config.js
+		// Search upwards for jest-preset.js and jest.config.js
+		let result = findUpPathsWorkspaces([
 			'jest-preset.js',
 			'jest.config.js',
 		], {
-			ignoreCurrentPackage: true,
-			onlyFiles: true,
+			ignoreCurrentPackage: true,  // 忽略當前套件
+			onlyFiles: true,             // 只搜尋檔案
 		}).result;
 
 		if (result)
@@ -69,9 +122,14 @@ try
 			switch (name)
 			{
 				case 'jest-preset':
+					// 如果是 jest-preset.js，使用其目錄作為 preset
+					// If it's jest-preset.js, use its directory as preset
+					// @ts-ignore
 					jestConfig.preset = dirname(result);
 					break;
 				default:
+					// 其他情況，載入配置檔案內容
+					// Otherwise, load the configuration file content
 					jestConfig = {
 						...require(result),
 						jestConfig,
@@ -79,7 +137,7 @@ try
 					break;
 			}
 
-			_ok = false;
+			_isNeedConfig = false;
 		}
 	}
 }
@@ -90,13 +148,16 @@ catch (e)
 
 try
 {
-	if (_ok && !jestConfig.preset)
+	// 第二層：嘗試解析 @bluelovers/jest-config
+	// Second level: Try to resolve @bluelovers/jest-config
+	if (_isNeedConfig && !jestConfig.preset)
 	{
 		let result = _requireResolve('@bluelovers/jest-config/package.json');
 		if (result)
 		{
+			// @ts-ignore
 			jestConfig.preset = dirname(result);
-			_ok = false;
+			_isNeedConfig = false;
 		}
 	}
 }
@@ -105,12 +166,17 @@ catch (e)
 
 }
 
-if (_ok && !jestConfig.preset)
+if (_isNeedConfig && !jestConfig.preset)
 {
+	// 第三層：使用預設的 @bluelovers/jest-config
+	// Third level: Use default @bluelovers/jest-config
+	// @ts-ignore
 	jestConfig.preset = '@bluelovers/jest-config';
-	_ok = false;
+	_isNeedConfig = false;
 }
 
+// 輸出最終的 preset 設定
+// Output the final preset configuration
 console.info(`jest.config.preset: ${jestConfig.preset}`);
 
 module.exports = jestConfig

package/file/jest.config.js

@@ -1,6 +1,8 @@
 // @ts-check
+// @deprecated replace by jest.config.auto.js
 
 const { join, dirname } = require('path');
+// @ts-ignore
 const { tryRealpath } = require('jest-util');
 const { tmpdir } = require('os');
 
@@ -76,7 +78,7 @@ const testExt = [
 const cacheDirectory = getCacheDirectory();
 
 /**
- * // @type { import('@jest/types').Config.InitialOptions }
+ * @_type { import('@jest/types').Config.InitialOptions }
  * @type { import('ts-jest').InitialOptionsTsJest }
  */
 const jestConfig = {

package/file/npmrc

@@ -1,4 +1,5 @@
 registry=https://registry.npmjs.org/
 color=always
 package-manager-strict=false
-public-hoist-pattern[]=@types/*
+link-workspace-packages=true
+save-workspace-protocol=false

package/file/nvmrc

@@ -1 +1 @@
-node
+lts/*

package/file/pnpm-workspace.yaml

@@ -3,3 +3,22 @@ packages:
   - 'packages/*'
   # exclude packages that are inside test/ directories
   - '!**/test/**'
+
+publicHoistPattern:
+  - "ts-type"
+  - "@bluelovers/tsconfig"
+  - "@bluelovers/jest-config"
+  - "@types/node"
+  - "@types/jest"
+  - "jest"
+  - "ts-jest"
+  - "ts-node"
+  - "tsx"
+  - "tslib"
+
+linkWorkspacePackages: true
+saveWorkspaceProtocol: false
+# ignoreWorkspaceRootCheck: true
+
+# onlyBuiltDependencies: []
+# ignoredBuiltDependencies: []

package/file/test/__root.ts

@@ -3,3 +3,6 @@ import { join } from "path";
 export const __ROOT = join(__dirname, '..');
 
 export const isWin = process.platform === "win32";
+
+export const __TEST_ROOT = join(__ROOT, 'test');
+export const __TEST_FIXTURES = join(__TEST_ROOT, 'fixtures');

package/file/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "noEmit": true
+  }
+}

package/file/tsdx/tsconfig.json.tpl

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "noEmit": true
+  }
+}

package/file/ws-root/jest-preset.js

@@ -1,8 +1,37 @@
-const { mixinJestConfig } = require('@bluelovers/jest-config');
+/**
+ * 嘗試使用 `@yarn-tool/require-resolve` 載入模組的工具函數
+ * Utility function for lazy loading modules
+ *
+ * @param {string} name - 模組名稱 Module name
+ * @param {string[]} [paths] - 搜尋路徑 Search paths
+ * @private
+ */
+function _lazyRequire(name, paths)
+{
+	let m;
+	try
+	{
+		// 嘗試使用 require-resolve 工具載入模組
+		// Try to load module using require-resolve tool
+		m = require('@yarn-tool/require-resolve').requireExtra(name, {
+			includeCurrentDirectory: true,
+			includeGlobal: true,
+			paths,
+		});
+	}
+	catch (e) {}
+
+	// 如果失敗則使用標準 require
+	// If failed, use standard require
+	return typeof m === 'undefined' ? require(name) : m;
+}
+
+/** @type {import('@bluelovers/jest-config')} */
+const { mixinJestConfig } = _lazyRequire('@bluelovers/jest-config');
 
 /**
- * // @type { import('@jest/types').Config.InitialOptions }
- * // @type { import('ts-jest').InitialOptionsTsJest }
+ * @_type { import('@jest/types').Config.InitialOptions }
+ * @_type { import('ts-jest').InitialOptionsTsJest }
  * @type { import('ts-jest').JestConfigWithTsJest }
  */
 const jestConfig = mixinJestConfig({}, true, {

package/file/ws-root/jest.config.js

@@ -2,8 +2,9 @@
 const { resolve } = require('path');
 
 /**
- * // @type { import('@jest/types').Config.InitialOptions }
- * @type { import('ts-jest').InitialOptionsTsJest }
+ * @_type { import('@jest/types').Config.InitialOptions }
+ * @_type { import('ts-jest').InitialOptionsTsJest }
+ * @type { import('ts-jest').JestConfigWithTsJest }
  */
 const jestConfig = {
 	preset: __dirname,

package/index.d.ts

@@ -1,3 +1,28 @@
+/**
+ * @yarn-tool/static-file
+ *
+ * A utility for copying static configuration files to yarn workspace projects.
+ * 用於將靜態配置檔案複製到 yarn 工作區專案的工具。
+ *
+ * This package provides functionality to copy predefined static files
+ * (such as .gitignore, tsconfig.json, etc.) to target directories.
+ * 此套件提供將預定義的靜態檔案（如 .gitignore、tsconfig.json 等）
+ * 複製到目標目錄的功能。
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { copyStaticFiles } from '@yarn-tool/static-file';
+ *
+ * // Copy default static files to current directory
+ * // 將預設靜態檔案複製到當前目錄
+ * copyStaticFiles({
+ *   cwd: process.cwd(),
+ *   overwrite: true
+ * });
+ * ```
+ */
 import { copyStaticFiles } from './lib/copyStaticFiles';
 export { copyStaticFiles };
 export default copyStaticFiles;

package/index.js

@@ -1,6 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.copyStaticFiles = void 0;
+/**
+ * @yarn-tool/static-file
+ *
+ * A utility for copying static configuration files to yarn workspace projects.
+ * 用於將靜態配置檔案複製到 yarn 工作區專案的工具。
+ *
+ * This package provides functionality to copy predefined static files
+ * (such as .gitignore, tsconfig.json, etc.) to target directories.
+ * 此套件提供將預定義的靜態檔案（如 .gitignore、tsconfig.json 等）
+ * 複製到目標目錄的功能。
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { copyStaticFiles } from '@yarn-tool/static-file';
+ *
+ * // Copy default static files to current directory
+ * // 將預設靜態檔案複製到當前目錄
+ * copyStaticFiles({
+ *   cwd: process.cwd(),
+ *   overwrite: true
+ * });
+ * ```
+ */
 const copyStaticFiles_1 = require("./lib/copyStaticFiles");
 Object.defineProperty(exports, "copyStaticFiles", { enumerable: true, get: function () { return copyStaticFiles_1.copyStaticFiles; } });
 exports.default = copyStaticFiles_1.copyStaticFiles;

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,2DAAwD;AAE/C,gGAFA,iCAAe,OAEA;AAExB,kBAAe,iCAAe,CAAC","sourcesContent":["import { copyStaticFiles } from './lib/copyStaticFiles';\n\nexport { copyStaticFiles }\n\nexport default copyStaticFiles;\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,2DAAwD;AAE/C,gGAFA,iCAAe,OAEA;AAExB,kBAAe,iCAAe,CAAC","sourcesContent":["/**\n * @yarn-tool/static-file\n *\n * A utility for copying static configuration files to yarn workspace projects.\n * 用於將靜態配置檔案複製到 yarn 工作區專案的工具。\n *\n * This package provides functionality to copy predefined static files\n * (such as .gitignore, tsconfig.json, etc.) to target directories.\n * 此套件提供將預定義的靜態檔案（如 .gitignore、tsconfig.json 等）\n * 複製到目標目錄的功能。\n *\n * @packageDocumentation\n *\n * @example\n * ```typescript\n * import { copyStaticFiles } from '@yarn-tool/static-file';\n *\n * // Copy default static files to current directory\n * // 將預設靜態檔案複製到當前目錄\n * copyStaticFiles({\n *   cwd: process.cwd(),\n *   overwrite: true\n * });\n * ```\n */\nimport { copyStaticFiles } from './lib/copyStaticFiles';\n\nexport { copyStaticFiles }\n\nexport default copyStaticFiles;\n"]}