@yarn-tool/static-file 3.0.19 → 3.0.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +110 -3
  3. package/file/npmignore +31 -0
  4. package/file/test/__root-core.cjs +1 -1
  5. package/file/test/__root-core.mjs +1 -1
  6. package/file/test/__root.js.map +1 -0
  7. package/file/test/__root.ts +9 -2
  8. package/file/test/temp.js.map +1 -0
  9. package/file/test/tsconfig.json.tpl +7 -0
  10. package/file/tsconfig.esm.json.tpl +9 -1
  11. package/file/tsconfig.json.tpl +9 -1
  12. package/file/tsconfig.tsdx.json.tpl +4 -0
  13. package/file/tsdx/index.cjs.map +1 -0
  14. package/file/ws-root/__root_ws.js.map +1 -0
  15. package/lib/const.js +120 -27
  16. package/lib/const.js.map +1 -1
  17. package/lib/copyStaticFiles.d.ts +62 -2
  18. package/lib/copyStaticFiles.js +156 -9
  19. package/lib/copyStaticFiles.js.map +1 -1
  20. package/lib/copyStaticFilesEntry.d.ts +72 -25
  21. package/lib/copyStaticFilesEntry.js +133 -34
  22. package/lib/copyStaticFilesEntry.js.map +1 -1
  23. package/lib/mergeIgnoreFiles.d.ts +52 -0
  24. package/lib/mergeIgnoreFiles.js +146 -0
  25. package/lib/mergeIgnoreFiles.js.map +1 -0
  26. package/lib/parseStaticMap.js +16 -3
  27. package/lib/parseStaticMap.js.map +1 -1
  28. package/lib/reMapStaticFilesMapArray.js +26 -5
  29. package/lib/reMapStaticFilesMapArray.js.map +1 -1
  30. package/lib/root/getRootCopyStaticFiles.js +17 -2
  31. package/lib/root/getRootCopyStaticFiles.js.map +1 -1
  32. package/lib/types.d.ts +71 -0
  33. package/lib/types.js.map +1 -1
  34. package/package.json +22 -5
  35. package/test/__root-core.cjs +1 -0
  36. package/test/__root-core.d.cts +1 -0
  37. package/test/__root-core.d.mts +1 -0
  38. package/test/__root-core.d.ts +1 -0
  39. package/test/__root-core.mjs +8 -0
  40. package/test/__root.d.ts +32 -0
  41. package/test/__root.js +54 -0
  42. package/test/__root.js.map +1 -0
  43. package/test/copyStaticFiles.test.js.map +1 -0
  44. package/test/copyStaticFiles.test.ts.snapshot +439 -0
  45. package/test/fixtures/out/gitignore +242 -0
  46. package/test/fixtures/out/npmignore +216 -0
  47. package/test/fixtures/split/git/00-header.txt +2 -0
  48. package/test/fixtures/split/git/10-project.txt +24 -0
  49. package/test/fixtures/split/git/20-test.txt +9 -0
  50. package/test/fixtures/split/git/40-env.txt +10 -0
  51. package/test/fixtures/split/git/90-misc.txt +6 -0
  52. package/test/fixtures/split/git/99-whitelist.txt +40 -0
  53. package/test/fixtures/split/npm/01-hidden.txt +2 -0
  54. package/test/fixtures/split/npm/05-source.txt +7 -0
  55. package/test/fixtures/split/npm/10-project.txt +31 -0
  56. package/test/fixtures/split/npm/20-test.txt +20 -0
  57. package/test/fixtures/split/npm/30-ide.txt +2 -0
  58. package/test/fixtures/split/npm/40-env.txt +2 -0
  59. package/test/fixtures/split/npm/90-misc.txt +4 -0
  60. package/test/fixtures/split/other/90-duplicates.txt +33 -0
  61. package/test/fixtures/split/shared/10-project.txt +38 -0
  62. package/test/fixtures/split/shared/20-test.txt +7 -0
  63. package/test/fixtures/split/shared/30-ide.txt +8 -0
  64. package/test/fixtures/split/shared/40-env.txt +6 -0
  65. package/test/fixtures/split/shared/90-misc.txt +10 -0
  66. package/test/scripts/compose-split-ignore-files.d.ts +1 -0
  67. package/test/scripts/compose-split-ignore-files.js +80 -0
  68. package/test/scripts/compose-split-ignore-files.js.map +1 -0
  69. package/test/scripts/lib/ignore-split.d.ts +205 -0
  70. package/test/scripts/lib/ignore-split.js +286 -0
  71. package/test/scripts/lib/ignore-split.js.map +1 -0
  72. package/test/scripts/split-ignore-files.d.ts +1 -0
  73. package/test/scripts/split-ignore-files.js +454 -0
  74. package/test/scripts/split-ignore-files.js.map +1 -0
  75. package/test/scripts/update-npmignore-static-files.d.ts +1 -0
  76. package/test/scripts/update-npmignore-static-files.js +121 -0
  77. package/test/scripts/update-npmignore-static-files.js.map +1 -0
  78. package/test/temp.d.ts +3 -0
  79. package/test/temp.js +5 -0
  80. package/test/temp.js.map +1 -0
  81. package/test/tsconfig.json.tpl +13 -0
@@ -6,7 +6,7 @@
6
6
  *
7
7
  * @module copyStaticFiles
8
8
  */
9
- import { ICopyStaticFilesOptions, IStaticFilesMapArrayEntry } from './types';
9
+ import { ICopyStaticFilesOptions, ICopyStaticFilesOptionsRuntime, IStaticFilesMapArray, IStaticFilesMapArrayEntry } from './types';
10
10
  /**
11
11
  * Copy static files to a target directory / 將靜態檔案複製到目標目錄
12
12
  *
@@ -20,6 +20,7 @@ import { ICopyStaticFilesOptions, IStaticFilesMapArrayEntry } from './types';
20
20
  * @param options.staticRoot - Root directory of static files (defaults to package root) / 靜態檔案根目錄(預設為套件根目錄)
21
21
  * @param options.overwrite - Whether to overwrite existing files / 是否覆蓋已存在的檔案
22
22
  * @param options.file_map - Custom file mapping configuration / 自訂檔案映射配置
23
+ * @param options.ignoreFilesSnapshot - Snapshot of existing ignore files; enables auto-merge when given / reset 前建立的既有 ignore 檔快照;提供時啟用自動合併
23
24
  *
24
25
  * @returns Array of entries that were successfully copied / 成功複製的條目陣列
25
26
  *
@@ -27,6 +28,8 @@ import { ICopyStaticFilesOptions, IStaticFilesMapArrayEntry } from './types';
27
28
  * @throws {TypeError} When options.cwd directory does not exist / 當 options.cwd 目錄不存在時
28
29
  * @throws {TypeError} When file_map is invalid / 當 file_map 無效時
29
30
  *
31
+ * @see mergeIgnoreFiles
32
+ *
30
33
  * @example
31
34
  * ```typescript
32
35
  * import { copyStaticFiles } from '@yarn-tool/static-file';
@@ -49,4 +52,61 @@ import { ICopyStaticFilesOptions, IStaticFilesMapArrayEntry } from './types';
49
52
  * });
50
53
  * ```
51
54
  */
52
- export declare function copyStaticFiles<K extends string>(options: ICopyStaticFilesOptions<K>): IStaticFilesMapArrayEntry<string | K>[];
55
+ export declare function copyStaticFiles<K extends string>(options: ICopyStaticFilesOptions<K>): IStaticFilesMapArray<K>;
56
+ /**
57
+ * 驗證並補齊複製選項 / Validate and fill in copy options
58
+ *
59
+ * 回傳的選項保證 cwd 為已存在的字串、file_map 已解析成陣列、staticRoot 已有明確值。
60
+ * The returned options guarantee an existing string cwd, an array-form file_map, and a resolved staticRoot.
61
+ *
62
+ * @template K - 目標檔案路徑類型 / Target file path type
63
+ *
64
+ * @param options - 呼叫端傳入的原始選項 / Raw options passed by the caller
65
+ * @returns 補齊預設值後的選項 / Options with defaults resolved
66
+ *
67
+ * @throws {TypeError} 當 cwd 不是字串或目錄不存在、或 file_map 解析結果為空時 / When cwd is not a string or does not exist, or the parsed file map is empty
68
+ *
69
+ * @example
70
+ * ```typescript
71
+ * import { _handleCopyStaticFilesOptions } from '@yarn-tool/static-file/lib/copyStaticFiles';
72
+ *
73
+ * // 只需傳入必填的 cwd,其餘取預設值 / Only the required cwd is passed; the rest use defaults
74
+ * const options = _handleCopyStaticFilesOptions({ cwd: '/path/to/project' });
75
+ *
76
+ * console.log(options.staticRoot); // 本套件的 file/ 目錄 / this package's file/ directory
77
+ * console.log(options.file_map); // 預設靜態檔案清單 / default static file list
78
+ * ```
79
+ */
80
+ export declare function _handleCopyStaticFilesOptions<K extends string>(options: ICopyStaticFilesOptions<K>): ICopyStaticFilesOptionsRuntime<K>;
81
+ /**
82
+ * 逐項產出可複製的靜態檔案 / Yield each static file ready to be copied
83
+ *
84
+ * 只負責驗證、解析與過濾,本身不寫入任何檔案;是否複製由呼叫端決定(執行 yield 出來的 copy())。
85
+ * Only validates, resolves and filters — it never writes files; the caller decides whether to run the yielded copy().
86
+ *
87
+ * @template K - 目標檔案路徑類型 / Target file path type
88
+ *
89
+ * @param options - 複製選項 / Copy options
90
+ * @yields 解析完成的條目、其複製資訊與複製動作 / The resolved entry, its copy info, and the copy action
91
+ *
92
+ * @throws {TypeError} 當選項驗證失敗時 / When option validation fails
93
+ * @throws {Error} 當來源靜態檔案不存在時 / When the source static file does not exist
94
+ *
95
+ * @example
96
+ * ```typescript
97
+ * import { _copyStaticFilesCoreListGenerator } from '@yarn-tool/static-file/lib/copyStaticFiles';
98
+ *
99
+ * for (const { entry, runtime, copy } of _copyStaticFilesCoreListGenerator({ cwd: '/path/to/project' }))
100
+ * {
101
+ * console.log(entry[0], '=>', runtime.targetFileFull);
102
+ *
103
+ * // 決定權交給呼叫端;不呼叫 copy() 就不會寫入任何檔案 / The caller decides; without copy() nothing is written
104
+ * copy();
105
+ * }
106
+ * ```
107
+ */
108
+ export declare function _copyStaticFilesCoreListGenerator<K extends string>(options: ICopyStaticFilesOptions<K>): Generator<{
109
+ entry: IStaticFilesMapArrayEntry<K>;
110
+ runtime: import("./types").IStaticFilesEntryRuntime<K>;
111
+ copy(): void;
112
+ }, void, unknown>;
@@ -1,10 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.copyStaticFiles = copyStaticFiles;
4
+ exports._handleCopyStaticFilesOptions = _handleCopyStaticFilesOptions;
5
+ exports._copyStaticFilesCoreListGenerator = _copyStaticFilesCoreListGenerator;
4
6
  const fs_extra_1 = require("fs-extra");
5
7
  const const_1 = require("./const");
6
8
  const parseStaticMap_1 = require("./parseStaticMap");
7
9
  const copyStaticFilesEntry_1 = require("./copyStaticFilesEntry");
10
+ const mergeIgnoreFiles_1 = require("./mergeIgnoreFiles");
8
11
  const __root_1 = require("../__root");
9
12
  /**
10
13
  * Copy static files to a target directory / 將靜態檔案複製到目標目錄
@@ -19,6 +22,7 @@ const __root_1 = require("../__root");
19
22
  * @param options.staticRoot - Root directory of static files (defaults to package root) / 靜態檔案根目錄(預設為套件根目錄)
20
23
  * @param options.overwrite - Whether to overwrite existing files / 是否覆蓋已存在的檔案
21
24
  * @param options.file_map - Custom file mapping configuration / 自訂檔案映射配置
25
+ * @param options.ignoreFilesSnapshot - Snapshot of existing ignore files; enables auto-merge when given / reset 前建立的既有 ignore 檔快照;提供時啟用自動合併
22
26
  *
23
27
  * @returns Array of entries that were successfully copied / 成功複製的條目陣列
24
28
  *
@@ -26,6 +30,8 @@ const __root_1 = require("../__root");
26
30
  * @throws {TypeError} When options.cwd directory does not exist / 當 options.cwd 目錄不存在時
27
31
  * @throws {TypeError} When file_map is invalid / 當 file_map 無效時
28
32
  *
33
+ * @see mergeIgnoreFiles
34
+ *
29
35
  * @example
30
36
  * ```typescript
31
37
  * import { copyStaticFiles } from '@yarn-tool/static-file';
@@ -49,27 +55,168 @@ const __root_1 = require("../__root");
49
55
  * ```
50
56
  */
51
57
  function copyStaticFiles(options) {
58
+ const opts = _handleCopyStaticFilesOptions(options);
59
+ /**
60
+ * 已實際複製的條目,作為回傳值交給呼叫端 / Entries actually copied, collected as the return value
61
+ */
62
+ const copied = [];
63
+ /**
64
+ * 逐項複製並收集實際產出的條目
65
+ * Copy each yielded entry and collect the results
66
+ *
67
+ * 被 detectFile 跳過的條目不會被產出,因此也不會出現在回傳值中
68
+ * Entries skipped by detectFile are never yielded, so they are absent from the result
69
+ */
70
+ for (const result of _copyStaticFilesCoreListGenerator(opts)) {
71
+ result.copy();
72
+ copied.push(result.entry);
73
+ }
74
+ /**
75
+ * 合併既有 ignore 檔內容 / Merge existing ignore file content
76
+ *
77
+ * resetStaticFiles 會先刪除正式 ignore 檔再重新複製樣板,
78
+ * 呼叫端在 reset 前建立的快照在此併回複製後的檔案,使既有規則不因 reset 遺失。
79
+ * resetStaticFiles deletes the real ignore files before copying the templates back;
80
+ * the snapshot taken by the caller before the reset is folded into the post-copy files here,
81
+ * so existing rules survive the reset.
82
+ *
83
+ * 未提供快照時 mergeIgnoreFiles 直接返回,不做任何寫入。
84
+ * mergeIgnoreFiles returns immediately when no snapshot is given, so nothing is written.
85
+ *
86
+ * @see mergeIgnoreFiles
87
+ */
88
+ (0, mergeIgnoreFiles_1.mergeIgnoreFiles)(opts.cwd, opts.file_map, opts.ignoreFilesSnapshot);
89
+ return copied;
90
+ }
91
+ /**
92
+ * 驗證並補齊複製選項 / Validate and fill in copy options
93
+ *
94
+ * 回傳的選項保證 cwd 為已存在的字串、file_map 已解析成陣列、staticRoot 已有明確值。
95
+ * The returned options guarantee an existing string cwd, an array-form file_map, and a resolved staticRoot.
96
+ *
97
+ * @template K - 目標檔案路徑類型 / Target file path type
98
+ *
99
+ * @param options - 呼叫端傳入的原始選項 / Raw options passed by the caller
100
+ * @returns 補齊預設值後的選項 / Options with defaults resolved
101
+ *
102
+ * @throws {TypeError} 當 cwd 不是字串或目錄不存在、或 file_map 解析結果為空時 / When cwd is not a string or does not exist, or the parsed file map is empty
103
+ *
104
+ * @example
105
+ * ```typescript
106
+ * import { _handleCopyStaticFilesOptions } from '@yarn-tool/static-file/lib/copyStaticFiles';
107
+ *
108
+ * // 只需傳入必填的 cwd,其餘取預設值 / Only the required cwd is passed; the rest use defaults
109
+ * const options = _handleCopyStaticFilesOptions({ cwd: '/path/to/project' });
110
+ *
111
+ * console.log(options.staticRoot); // 本套件的 file/ 目錄 / this package's file/ directory
112
+ * console.log(options.file_map); // 預設靜態檔案清單 / default static file list
113
+ * ```
114
+ */
115
+ function _handleCopyStaticFilesOptions(options) {
52
116
  var _a, _b;
53
- // Validate cwd parameter / 驗證 cwd 參數
117
+ /**
118
+ * 驗證 cwd 參數
119
+ * Validate cwd parameter
120
+ *
121
+ * 空字串與 undefined 都會在後續 resolve 時產生錯誤的根路徑,故先行攔截
122
+ * Empty string and undefined would produce a wrong base path during resolve, so intercept early
123
+ */
54
124
  if (typeof options.cwd !== 'string' || !((_a = options.cwd) === null || _a === void 0 ? void 0 : _a.length) || !options.cwd) {
55
125
  throw new TypeError(`options.cwd must is string`);
56
126
  }
57
- // Check if cwd directory exists / 檢查 cwd 目錄是否存在
127
+ /**
128
+ * 檢查 cwd 目錄是否存在
129
+ * Check if cwd directory exists
130
+ *
131
+ * 目標目錄不存在時直接失敗,避免複製到非預期位置
132
+ * Fail early when the target directory is absent, to avoid copying into an unintended location
133
+ */
58
134
  if (!(0, fs_extra_1.pathExistsSync)(options.cwd)) {
59
135
  throw new TypeError(`options.cwd not exists`);
60
136
  }
61
- // Parse the file map / 解析檔案映射
137
+ /**
138
+ * 解析檔案映射
139
+ * Parse the file map
140
+ *
141
+ * 未提供 file_map 時退回預設清單,讓一般呼叫只需傳入 cwd
142
+ * Fall back to the default list when file_map is omitted, so a plain call only needs cwd
143
+ */
62
144
  let ls = (0, parseStaticMap_1.parseStaticMap)((_b = options.file_map) !== null && _b !== void 0 ? _b : const_1.defaultCopyStaticFiles);
63
- // Validate parsed file map / 驗證解析後的檔案映射
145
+ /**
146
+ * 驗證解析後的檔案映射
147
+ * Validate parsed file map
148
+ *
149
+ * 解析結果為空代表映射格式錯誤,若不攔截會安靜地複製零個檔案
150
+ * An empty result means a malformed map; without this guard the copy would silently do nothing
151
+ */
64
152
  if (!ls.length) {
65
153
  throw new TypeError(`Invalid file map: ${options.file_map}`);
66
154
  }
67
- // Determine static root directory / 確定靜態檔案根目錄
155
+ /**
156
+ * 確定靜態檔案根目錄
157
+ * Determine static root directory
158
+ *
159
+ * 允許呼叫端覆寫靜態樣板來源;預設指向本套件的 file/ 目錄
160
+ * Allows overriding the template source; defaults to this package's file/ directory
161
+ */
68
162
  const staticRoot = options.staticRoot || __root_1.__STATIC_ROOT;
69
163
  const { cwd, overwrite } = options;
70
- // Filter and copy files / 過濾並複製檔案
71
- return ls.filter((entry) => {
72
- return (0, copyStaticFilesEntry_1.copyStaticFilesEntry)(entry, cwd, staticRoot, overwrite);
73
- });
164
+ /**
165
+ * 展開原始選項並以解析後的值覆寫,確保 file_map 固定回傳陣列型別,呼叫端無需再判斷格式
166
+ * Spread the raw options and overwrite with resolved values so file_map is always an array and callers need no format check
167
+ */
168
+ return {
169
+ ...options,
170
+ staticRoot,
171
+ cwd,
172
+ overwrite,
173
+ file_map: ls,
174
+ };
175
+ }
176
+ /**
177
+ * 逐項產出可複製的靜態檔案 / Yield each static file ready to be copied
178
+ *
179
+ * 只負責驗證、解析與過濾,本身不寫入任何檔案;是否複製由呼叫端決定(執行 yield 出來的 copy())。
180
+ * Only validates, resolves and filters — it never writes files; the caller decides whether to run the yielded copy().
181
+ *
182
+ * @template K - 目標檔案路徑類型 / Target file path type
183
+ *
184
+ * @param options - 複製選項 / Copy options
185
+ * @yields 解析完成的條目、其複製資訊與複製動作 / The resolved entry, its copy info, and the copy action
186
+ *
187
+ * @throws {TypeError} 當選項驗證失敗時 / When option validation fails
188
+ * @throws {Error} 當來源靜態檔案不存在時 / When the source static file does not exist
189
+ *
190
+ * @example
191
+ * ```typescript
192
+ * import { _copyStaticFilesCoreListGenerator } from '@yarn-tool/static-file/lib/copyStaticFiles';
193
+ *
194
+ * for (const { entry, runtime, copy } of _copyStaticFilesCoreListGenerator({ cwd: '/path/to/project' }))
195
+ * {
196
+ * console.log(entry[0], '=>', runtime.targetFileFull);
197
+ *
198
+ * // 決定權交給呼叫端;不呼叫 copy() 就不會寫入任何檔案 / The caller decides; without copy() nothing is written
199
+ * copy();
200
+ * }
201
+ * ```
202
+ */
203
+ function* _copyStaticFilesCoreListGenerator(options) {
204
+ const opts = _handleCopyStaticFilesOptions(options);
205
+ for (const entry of opts.file_map) {
206
+ const runtime = (0, copyStaticFilesEntry_1._copyStaticFilesEntryCore)(entry, opts.cwd, opts.staticRoot, opts.overwrite);
207
+ /**
208
+ * 被 detectFile 跳過的條目解析結果為 undefined,直接略過不產出
209
+ * An entry skipped by detectFile resolves to undefined and is therefore not yielded
210
+ */
211
+ if (runtime) {
212
+ yield {
213
+ entry,
214
+ runtime,
215
+ copy() {
216
+ return (0, copyStaticFilesEntry_1._copyStaticFilesEntryCoreCopy)(runtime);
217
+ },
218
+ };
219
+ }
220
+ }
74
221
  }
75
222
  //# sourceMappingURL=copyStaticFiles.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"copyStaticFiles.js","sourceRoot":"","sources":["copyStaticFiles.ts"],"names":[],"mappings":";;AA0DA,0CAiCC;AAlFD,uCAAgG;AAEhG,mCAAiD;AACjD,qDAAkD;AAClD,iEAA8D;AAC9D,sCAA0C;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,SAAgB,eAAe,CAAmB,OAAmC;;IAEpF,qCAAqC;IACrC,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAA,MAAA,OAAO,CAAC,GAAG,0CAAE,MAAM,CAAA,IAAI,CAAC,OAAO,CAAC,GAAG,EAC3E,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAA;IAClD,CAAC;IAED,gDAAgD;IAChD,IAAI,CAAC,IAAA,yBAAc,EAAC,OAAO,CAAC,GAAG,CAAC,EAChC,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAA;IAC9C,CAAC;IAED,8BAA8B;IAC9B,IAAI,EAAE,GAAG,IAAA,+BAAc,EAAI,MAAA,OAAO,CAAC,QAAQ,mCAAI,8BAAiD,CAAC,CAAC;IAElG,wCAAwC;IACxC,IAAI,CAAC,EAAE,CAAC,MAAM,EACd,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,qBAAqB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED,8CAA8C;IAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,sBAAa,CAAC;IACvD,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEnC,kCAAkC;IAClC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAEzB,OAAO,IAAA,2CAAoB,EAAC,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,CAAC,CAAA;IAC/D,CAAC,CAAC,CACD;AACH,CAAC","sourcesContent":["/**\n * Copy static files main function / 複製靜態檔案主函數\n *\n * This module provides the main function for copying static files to a target directory.\n * 此模組提供將靜態檔案複製到目標目錄的主函數。\n *\n * @module copyStaticFiles\n */\nimport { ICopyStaticFilesOptions, IStaticFilesMapArray, IStaticFilesMapArrayEntry } from './types';\nimport { CopyOptionsSync, copySync, ensureDirSync, existsSync, pathExistsSync } from 'fs-extra';\nimport { dirname, resolve } from 'path';\nimport { defaultCopyStaticFiles } from './const';\nimport { parseStaticMap } from './parseStaticMap';\nimport { copyStaticFilesEntry } from './copyStaticFilesEntry';\nimport { __STATIC_ROOT } from '../__root';\n\n/**\n * Copy static files to a target directory / 將靜態檔案複製到目標目錄\n *\n * Copies static files based on the provided file map configuration.\n * 根據提供的檔案映射配置複製靜態檔案。\n *\n * @template K - The target file path type / 目標檔案路徑類型\n *\n * @param options - Copy options / 複製選項\n * @param options.cwd - Current working directory (required) / 當前工作目錄(必填)\n * @param options.staticRoot - Root directory of static files (defaults to package root) / 靜態檔案根目錄(預設為套件根目錄)\n * @param options.overwrite - Whether to overwrite existing files / 是否覆蓋已存在的檔案\n * @param options.file_map - Custom file mapping configuration / 自訂檔案映射配置\n *\n * @returns Array of entries that were successfully copied / 成功複製的條目陣列\n *\n * @throws {TypeError} When options.cwd is not a valid string / 當 options.cwd 不是有效的字串時\n * @throws {TypeError} When options.cwd directory does not exist / 當 options.cwd 目錄不存在時\n * @throws {TypeError} When file_map is invalid / 當 file_map 無效時\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 * // Copy with custom file map\n * // 使用自訂檔案映射複製\n * copyStaticFiles({\n * cwd: '/path/to/project',\n * file_map: [\n * ['.gitignore', 'file/gitignore'],\n * ['README.md', 'file/README.md']\n * ]\n * });\n * ```\n */\nexport function copyStaticFiles<K extends string>(options: ICopyStaticFilesOptions<K>)\n{\n\t// Validate cwd parameter / 驗證 cwd 參數\n\tif (typeof options.cwd !== 'string' || !options.cwd?.length || !options.cwd)\n\t{\n\t\tthrow new TypeError(`options.cwd must is string`)\n\t}\n\n\t// Check if cwd directory exists / 檢查 cwd 目錄是否存在\n\tif (!pathExistsSync(options.cwd))\n\t{\n\t\tthrow new TypeError(`options.cwd not exists`)\n\t}\n\n\t// Parse the file map / 解析檔案映射\n\tlet ls = parseStaticMap<K>(options.file_map ?? defaultCopyStaticFiles as IStaticFilesMapArray<K>);\n\n\t// Validate parsed file map / 驗證解析後的檔案映射\n\tif (!ls.length)\n\t{\n\t\tthrow new TypeError(`Invalid file map: ${options.file_map}`)\n\t}\n\n\t// Determine static root directory / 確定靜態檔案根目錄\n\tconst staticRoot = options.staticRoot || __STATIC_ROOT;\n\tconst { cwd, overwrite } = options;\n\n\t// Filter and copy files / 過濾並複製檔案\n\treturn ls.filter((entry) =>\n\t\t{\n\t\t\treturn copyStaticFilesEntry(entry, cwd, staticRoot, overwrite)\n\t\t})\n\t\t;\n}\n"]}
1
+ {"version":3,"file":"copyStaticFiles.js","sourceRoot":"","sources":["copyStaticFiles.ts"],"names":[],"mappings":";;AA8DA,0CAwCC;AA0BD,sEAqEC;AA6BD,8EAwBC;AAjPD,uCAAgG;AAEhG,mCAAiD;AACjD,qDAAkD;AAClD,iEAAwH;AACxH,yDAAsD;AACtD,sCAA0C;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,SAAgB,eAAe,CAAmB,OAAmC;IAEpF,MAAM,IAAI,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;IAEpD;;OAEG;IACH,MAAM,MAAM,GAAG,EAA6B,CAAC;IAE7C;;;;;;OAMG;IACH,KAAK,MAAM,MAAM,IAAI,iCAAiC,CAAC,IAAI,CAAC,EAC5D,CAAC;QACA,MAAM,CAAC,IAAI,EAAE,CAAC;QAEd,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAA,mCAAgB,EAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAEpE,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,6BAA6B,CAAmB,OAAmC;;IAElG;;;;;;OAMG;IACH,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAA,MAAA,OAAO,CAAC,GAAG,0CAAE,MAAM,CAAA,IAAI,CAAC,OAAO,CAAC,GAAG,EAC3E,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAA;IAClD,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,IAAA,yBAAc,EAAC,OAAO,CAAC,GAAG,CAAC,EAChC,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAA;IAC9C,CAAC;IAED;;;;;;OAMG;IACH,IAAI,EAAE,GAAG,IAAA,+BAAc,EAAI,MAAA,OAAO,CAAC,QAAQ,mCAAI,8BAAiD,CAAC,CAAC;IAElG;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CAAC,MAAM,EACd,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,qBAAqB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,sBAAa,CAAC;IACvD,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEnC;;;OAGG;IACH,OAAO;QACN,GAAG,OAAO;QACV,UAAU;QACV,GAAG;QACH,SAAS;QAET,QAAQ,EAAE,EAA6B;KACvC,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,QAAe,CAAC,CAAC,iCAAiC,CAAmB,OAAmC;IAEvG,MAAM,IAAI,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;IAEpD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EACjC,CAAC;QACA,MAAM,OAAO,GAAG,IAAA,gDAAyB,EAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAE5F;;;WAGG;QACH,IAAI,OAAO,EACX,CAAC;YACA,MAAM;gBACL,KAAK;gBACL,OAAO;gBACP,IAAI;oBAEH,OAAO,IAAA,oDAA6B,EAAC,OAAO,CAAC,CAAC;gBAC/C,CAAC;aACD,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC","sourcesContent":["/**\n * Copy static files main function / 複製靜態檔案主函數\n *\n * This module provides the main function for copying static files to a target directory.\n * 此模組提供將靜態檔案複製到目標目錄的主函數。\n *\n * @module copyStaticFiles\n */\nimport { ICopyStaticFilesOptions, ICopyStaticFilesOptionsRuntime, IStaticFilesMapArray, IStaticFilesMapArrayEntry } from './types';\nimport { CopyOptionsSync, copySync, ensureDirSync, existsSync, pathExistsSync } from 'fs-extra';\nimport { dirname, resolve } from 'path';\nimport { defaultCopyStaticFiles } from './const';\nimport { parseStaticMap } from './parseStaticMap';\nimport { _copyStaticFilesEntryCore, _copyStaticFilesEntryCoreCopy, copyStaticFilesEntry } from './copyStaticFilesEntry';\nimport { mergeIgnoreFiles } from './mergeIgnoreFiles';\nimport { __STATIC_ROOT } from '../__root';\n\n/**\n * Copy static files to a target directory / 將靜態檔案複製到目標目錄\n *\n * Copies static files based on the provided file map configuration.\n * 根據提供的檔案映射配置複製靜態檔案。\n *\n * @template K - The target file path type / 目標檔案路徑類型\n *\n * @param options - Copy options / 複製選項\n * @param options.cwd - Current working directory (required) / 當前工作目錄(必填)\n * @param options.staticRoot - Root directory of static files (defaults to package root) / 靜態檔案根目錄(預設為套件根目錄)\n * @param options.overwrite - Whether to overwrite existing files / 是否覆蓋已存在的檔案\n * @param options.file_map - Custom file mapping configuration / 自訂檔案映射配置\n * @param options.ignoreFilesSnapshot - Snapshot of existing ignore files; enables auto-merge when given / reset 前建立的既有 ignore 檔快照;提供時啟用自動合併\n *\n * @returns Array of entries that were successfully copied / 成功複製的條目陣列\n *\n * @throws {TypeError} When options.cwd is not a valid string / 當 options.cwd 不是有效的字串時\n * @throws {TypeError} When options.cwd directory does not exist / 當 options.cwd 目錄不存在時\n * @throws {TypeError} When file_map is invalid / 當 file_map 無效時\n *\n * @see mergeIgnoreFiles\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 * // Copy with custom file map\n * // 使用自訂檔案映射複製\n * copyStaticFiles({\n * cwd: '/path/to/project',\n * file_map: [\n * ['.gitignore', 'file/gitignore'],\n * ['README.md', 'file/README.md']\n * ]\n * });\n * ```\n */\nexport function copyStaticFiles<K extends string>(options: ICopyStaticFilesOptions<K>)\n{\n\tconst opts = _handleCopyStaticFilesOptions(options);\n\n\t/**\n\t * 已實際複製的條目,作為回傳值交給呼叫端 / Entries actually copied, collected as the return value\n\t */\n\tconst copied = [] as IStaticFilesMapArray<K>;\n\n\t/**\n\t * 逐項複製並收集實際產出的條目\n\t * Copy each yielded entry and collect the results\n\t *\n\t * 被 detectFile 跳過的條目不會被產出,因此也不會出現在回傳值中\n\t * Entries skipped by detectFile are never yielded, so they are absent from the result\n\t */\n\tfor (const result of _copyStaticFilesCoreListGenerator(opts))\n\t{\n\t\tresult.copy();\n\n\t\tcopied.push(result.entry);\n\t}\n\n\t/**\n\t * 合併既有 ignore 檔內容 / Merge existing ignore file content\n\t *\n\t * resetStaticFiles 會先刪除正式 ignore 檔再重新複製樣板,\n\t * 呼叫端在 reset 前建立的快照在此併回複製後的檔案,使既有規則不因 reset 遺失。\n\t * resetStaticFiles deletes the real ignore files before copying the templates back;\n\t * the snapshot taken by the caller before the reset is folded into the post-copy files here,\n\t * so existing rules survive the reset.\n\t *\n\t * 未提供快照時 mergeIgnoreFiles 直接返回,不做任何寫入。\n\t * mergeIgnoreFiles returns immediately when no snapshot is given, so nothing is written.\n\t *\n\t * @see mergeIgnoreFiles\n\t */\n\tmergeIgnoreFiles(opts.cwd, opts.file_map, opts.ignoreFilesSnapshot);\n\n\treturn copied;\n}\n\n/**\n * 驗證並補齊複製選項 / Validate and fill in copy options\n *\n * 回傳的選項保證 cwd 為已存在的字串、file_map 已解析成陣列、staticRoot 已有明確值。\n * The returned options guarantee an existing string cwd, an array-form file_map, and a resolved staticRoot.\n *\n * @template K - 目標檔案路徑類型 / Target file path type\n *\n * @param options - 呼叫端傳入的原始選項 / Raw options passed by the caller\n * @returns 補齊預設值後的選項 / Options with defaults resolved\n *\n * @throws {TypeError} 當 cwd 不是字串或目錄不存在、或 file_map 解析結果為空時 / When cwd is not a string or does not exist, or the parsed file map is empty\n *\n * @example\n * ```typescript\n * import { _handleCopyStaticFilesOptions } from '@yarn-tool/static-file/lib/copyStaticFiles';\n *\n * // 只需傳入必填的 cwd,其餘取預設值 / Only the required cwd is passed; the rest use defaults\n * const options = _handleCopyStaticFilesOptions({ cwd: '/path/to/project' });\n *\n * console.log(options.staticRoot); // 本套件的 file/ 目錄 / this package's file/ directory\n * console.log(options.file_map); // 預設靜態檔案清單 / default static file list\n * ```\n */\nexport function _handleCopyStaticFilesOptions<K extends string>(options: ICopyStaticFilesOptions<K>): ICopyStaticFilesOptionsRuntime<K>\n{\n\t/**\n\t * 驗證 cwd 參數\n\t * Validate cwd parameter\n\t*\n\t * 空字串與 undefined 都會在後續 resolve 時產生錯誤的根路徑,故先行攔截\n\t * Empty string and undefined would produce a wrong base path during resolve, so intercept early\n\t */\n\tif (typeof options.cwd !== 'string' || !options.cwd?.length || !options.cwd)\n\t{\n\t\tthrow new TypeError(`options.cwd must is string`)\n\t}\n\n\t/**\n\t * 檢查 cwd 目錄是否存在\n\t * Check if cwd directory exists\n\t *\n\t * 目標目錄不存在時直接失敗,避免複製到非預期位置\n\t * Fail early when the target directory is absent, to avoid copying into an unintended location\n\t */\n\tif (!pathExistsSync(options.cwd))\n\t{\n\t\tthrow new TypeError(`options.cwd not exists`)\n\t}\n\n\t/**\n\t * 解析檔案映射\n\t * Parse the file map\n\t *\n\t * 未提供 file_map 時退回預設清單,讓一般呼叫只需傳入 cwd\n\t * Fall back to the default list when file_map is omitted, so a plain call only needs cwd\n\t */\n\tlet ls = parseStaticMap<K>(options.file_map ?? defaultCopyStaticFiles as IStaticFilesMapArray<K>);\n\n\t/**\n\t * 驗證解析後的檔案映射\n\t * Validate parsed file map\n\t *\n\t * 解析結果為空代表映射格式錯誤,若不攔截會安靜地複製零個檔案\n\t * An empty result means a malformed map; without this guard the copy would silently do nothing\n\t */\n\tif (!ls.length)\n\t{\n\t\tthrow new TypeError(`Invalid file map: ${options.file_map}`)\n\t}\n\n\t/**\n\t * 確定靜態檔案根目錄\n\t * Determine static root directory\n\t *\n\t * 允許呼叫端覆寫靜態樣板來源;預設指向本套件的 file/ 目錄\n\t * Allows overriding the template source; defaults to this package's file/ directory\n\t */\n\tconst staticRoot = options.staticRoot || __STATIC_ROOT;\n\tconst { cwd, overwrite } = options;\n\n\t/**\n\t * 展開原始選項並以解析後的值覆寫,確保 file_map 固定回傳陣列型別,呼叫端無需再判斷格式\n\t * Spread the raw options and overwrite with resolved values so file_map is always an array and callers need no format check\n\t */\n\treturn {\n\t\t...options,\n\t\tstaticRoot,\n\t\tcwd,\n\t\toverwrite,\n\n\t\tfile_map: ls as IStaticFilesMapArray<K>,\n\t}\n}\n\n/**\n * 逐項產出可複製的靜態檔案 / Yield each static file ready to be copied\n*\n * 只負責驗證、解析與過濾,本身不寫入任何檔案;是否複製由呼叫端決定(執行 yield 出來的 copy())。\n * Only validates, resolves and filters — it never writes files; the caller decides whether to run the yielded copy().\n *\n * @template K - 目標檔案路徑類型 / Target file path type\n *\n * @param options - 複製選項 / Copy options\n * @yields 解析完成的條目、其複製資訊與複製動作 / The resolved entry, its copy info, and the copy action\n *\n * @throws {TypeError} 當選項驗證失敗時 / When option validation fails\n * @throws {Error} 當來源靜態檔案不存在時 / When the source static file does not exist\n *\n * @example\n * ```typescript\n * import { _copyStaticFilesCoreListGenerator } from '@yarn-tool/static-file/lib/copyStaticFiles';\n *\n * for (const { entry, runtime, copy } of _copyStaticFilesCoreListGenerator({ cwd: '/path/to/project' }))\n * {\n * console.log(entry[0], '=>', runtime.targetFileFull);\n *\n * // 決定權交給呼叫端;不呼叫 copy() 就不會寫入任何檔案 / The caller decides; without copy() nothing is written\n * copy();\n * }\n * ```\n */\nexport function* _copyStaticFilesCoreListGenerator<K extends string>(options: ICopyStaticFilesOptions<K>)\n{\n\tconst opts = _handleCopyStaticFilesOptions(options);\n\n\tfor (const entry of opts.file_map)\n\t{\n\t\tconst runtime = _copyStaticFilesEntryCore(entry, opts.cwd, opts.staticRoot, opts.overwrite);\n\n\t\t/**\n\t\t * 被 detectFile 跳過的條目解析結果為 undefined,直接略過不產出\n\t\t * An entry skipped by detectFile resolves to undefined and is therefore not yielded\n\t\t */\n\t\tif (runtime)\n\t\t{\n\t\t\tyield {\n\t\t\t\tentry,\n\t\t\t\truntime,\n\t\t\t\tcopy()\n\t\t\t\t{\n\t\t\t\t\treturn _copyStaticFilesEntryCoreCopy(runtime);\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\t}\n}\n\n"]}
@@ -6,47 +6,94 @@
6
6
  *
7
7
  * @module copyStaticFilesEntry
8
8
  */
9
- import { IStaticFilesMapArrayEntry } from './types';
9
+ import { IStaticFilesEntryRuntime, IStaticFilesMapArrayEntry } from './types';
10
10
  /**
11
- * Copy a single static file entry / 複製單個靜態檔案條目
11
+ * 解析單個靜態檔案條目的複製資訊 / Resolve copy info for a single static file entry
12
12
  *
13
- * Copies a single static file from the static root to the target directory.
14
- * 從靜態根目錄複製單個靜態檔案到目標目錄。
13
+ * 只做路徑解析與存在性檢查,不寫入任何檔案;真正的複製交給 _copyStaticFilesEntryCoreCopy。
14
+ * Only resolves paths and checks existence — nothing is written; the actual copy is done by _copyStaticFilesEntryCoreCopy.
15
15
  *
16
- * @param entry - The static file entry / 靜態檔案條目
17
- * @param entry.0 - targetFile: Target file path / 目標檔案路徑
18
- * @param entry.1 - staticFile: Source static file path / 來源靜態檔案路徑
19
- * @param entry.2 - detectFile: Optional file to check for existence / 可選的檢測檔案
16
+ * @param entry - 靜態檔案條目 / Static file entry
17
+ * @param entry.0 - targetFile:目標檔案路徑 / Target file path
18
+ * @param entry.1 - staticFile:來源靜態檔案路徑 / Source static file path
19
+ * @param entry.2 - detectFile:可選的檢測檔案 / Optional file to check for existence
20
20
  *
21
- * @param cwd - Current working directory / 當前工作目錄
22
- * @param staticRoot - Root directory of static files (defaults to package root) / 靜態檔案根目錄(預設為套件根目錄)
23
- * @param overwrite - Whether to overwrite existing files (defaults to false) / 是否覆蓋已存在的檔案(預設為 false)
21
+ * @param cwd - 當前工作目錄 / Current working directory
22
+ * @param staticRoot - 靜態檔案根目錄(預設為套件根目錄)/ Root directory of static files (defaults to package root)
23
+ * @param overwrite - 是否覆蓋已存在的檔案(預設為 false)/ Whether to overwrite existing files (defaults to false)
24
24
  *
25
- * @returns true if file was copied, undefined if skipped (detect file exists) / 如果檔案已複製則返回 true,如果跳過(檢測檔案存在)則返回 undefined
25
+ * @returns 解析後的複製資訊;被 detectFile 跳過時回傳 undefined / Resolved copy info, or undefined when skipped by detectFile
26
+ * @throws {Error} 當來源靜態檔案不存在時 / When the source static file does not exist
26
27
  *
27
- * @throws {Error} When the source static file does not exist / 當來源靜態檔案不存在時
28
+ * @example
29
+ * ```typescript
30
+ * import { _copyStaticFilesEntryCore, _copyStaticFilesEntryCoreCopy } from '@yarn-tool/static-file/lib/copyStaticFilesEntry';
31
+ *
32
+ * // 複製單個檔案 / Copy a single file
33
+ * const runtime = _copyStaticFilesEntryCore(
34
+ * ['.gitignore', 'file/gitignore'],
35
+ * '/path/to/project',
36
+ * '/path/to/static/root',
37
+ * false,
38
+ * );
39
+ *
40
+ * if (runtime)
41
+ * {
42
+ * _copyStaticFilesEntryCoreCopy(runtime);
43
+ * }
44
+ *
45
+ * // 使用檢測檔案:正式設定檔已存在時跳過 / With detect file: skip when the real config already exists
46
+ * _copyStaticFilesEntryCore(
47
+ * ['tsconfig.json', 'file/tsconfig.json.tpl', 'tsconfig.json'],
48
+ * '/path/to/project',
49
+ * );
50
+ * // 專案已有 tsconfig.json 時回傳 undefined / Returns undefined when tsconfig.json already exists
51
+ * ```
52
+ */
53
+ export declare function _copyStaticFilesEntryCore<K extends string>(entry: IStaticFilesMapArrayEntry<K>, cwd: string, staticRoot?: string, overwrite?: boolean): IStaticFilesEntryRuntime<K>;
54
+ /**
55
+ * 執行單個靜態檔案的實際複製 / Perform the actual copy of a single static file entry
56
+ *
57
+ * @param runtime - _copyStaticFilesEntryCore 解析出的複製資訊 / Copy info resolved by _copyStaticFilesEntryCore
58
+ * @throws {TypeError} 當 runtime 為 undefined 時(detectFile 命中)/ When runtime is undefined (detectFile matched)
59
+ */
60
+ export declare function _copyStaticFilesEntryCoreCopy<K extends string>(runtime: IStaticFilesEntryRuntime<K>): void;
61
+ /**
62
+ * 複製單個靜態檔案到目標目錄 / Copy a single static file into the target directory
63
+ *
64
+ * 先解析再複製;被 detectFile 跳過時不會寫入任何檔案。
65
+ * Resolves first, then copies; nothing is written when detectFile skips the entry.
66
+ *
67
+ * @param entry - 靜態檔案條目 / Static file entry
68
+ * @param entry.0 - targetFile:目標檔案路徑 / Target file path
69
+ * @param entry.1 - staticFile:來源靜態檔案路徑 / Source static file path
70
+ * @param entry.2 - detectFile:可選的檢測檔案 / Optional file to check for existence
71
+ *
72
+ * @param cwd - 當前工作目錄 / Current working directory
73
+ * @param staticRoot - 靜態檔案根目錄(預設為套件根目錄)/ Root directory of static files (defaults to package root)
74
+ * @param overwrite - 是否覆蓋已存在的檔案(預設為 false)/ Whether to overwrite existing files (defaults to false)
75
+ *
76
+ * @returns 已複製時回傳 true;被 detectFile 跳過時回傳 undefined / Returns true when copied, undefined when skipped by detectFile
77
+ * @throws {Error} 當來源靜態檔案不存在時 / When the source static file does not exist
28
78
  *
29
79
  * @example
30
80
  * ```typescript
31
- * import { copyStaticFilesEntry } from '@yarn-tool/static-file';
81
+ * import { copyStaticFilesEntry } from '@yarn-tool/static-file/lib/copyStaticFilesEntry';
32
82
  *
33
- * // Copy a single file
34
- * // 複製單個檔案
35
- * const result = copyStaticFilesEntry(
83
+ * // 複製單個檔案 / Copy a single file
84
+ * const copied = copyStaticFilesEntry(
36
85
  * ['.gitignore', 'file/gitignore'],
37
86
  * '/path/to/project',
38
87
  * '/path/to/static/root',
39
- * false
88
+ * false,
40
89
  * );
41
90
  *
42
- * // With detect file - skips if detect file exists
43
- * // 使用檢測檔案 - 如果檢測檔案存在則跳過
44
- * const result = copyStaticFilesEntry(
91
+ * // 使用檢測檔案:已存在則跳過 / With detect file: skip when it already exists
92
+ * const skipped = copyStaticFilesEntry(
45
93
  * ['tsconfig.json', 'file/tsconfig.json.tpl', 'tsconfig.json'],
46
- * '/path/to/project'
94
+ * '/path/to/project',
47
95
  * );
48
- * // Skips copy if tsconfig.json already exists in the project
49
- * // 如果 tsconfig.json 已存在於專案中則跳過複製
96
+ * // 專案已有 tsconfig.json 時 skipped 為 undefined / skipped is undefined when tsconfig.json already exists
50
97
  * ```
51
98
  */
52
- export declare function copyStaticFilesEntry(entry: IStaticFilesMapArrayEntry<string>, cwd: string, staticRoot?: string, overwrite?: boolean): boolean;
99
+ export declare function copyStaticFilesEntry<K extends string>(entry: IStaticFilesMapArrayEntry<K>, cwd: string, staticRoot?: string, overwrite?: boolean): boolean;