@meng-xi/vite-plugin 0.1.7 → 0.1.9

package/README-en.md

@@ -15,10 +15,10 @@
 
 ## Features
 
-- **Ready to Use** - 12 practical plugins covering auto-import, build progress, bundle analysis & compression, file copying, environment variable validation, route generation, version management, HTML injection, favicon
-  management, global Loading, and more
+- **Ready to Use** - 14 practical plugins covering auto-import, build progress, bundle analysis & compression, file copying, environment variable validation, route generation, version management, HTML injection, favicon
+  management, global Loading, image optimization, and more
 - **Plugin Development Framework** - Exports core components like BasePlugin, Logger, and Validator to quickly build custom Vite plugins
-- **Common Utility Library** - Built-in 7 Common utility modules supporting on-demand sub-path imports
+- **Common Utility Library** - Built-in 8 Common utility modules supporting on-demand sub-path imports
 - **Type Safe** - Complete TypeScript type definitions with configuration validators
 - **On-demand Import** - Supports sub-path exports to reduce bundle size
 
@@ -41,10 +41,26 @@ pnpm add @meng-xi/vite-plugin -D
 
 ```typescript
 import { defineConfig } from 'vite'
-import { autoImport, buildProgress, bundleAnalyzer, compressAssets, copyFile, envGuard, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
+import {
+	assetManifest,
+	autoImport,
+	buildProgress,
+	bundleAnalyzer,
+	compressAssets,
+	copyFile,
+	envGuard,
+	generateRouter,
+	generateVersion,
+	versionUpdateChecker,
+	htmlInject,
+	faviconManager,
+	loadingManager,
+	imageOptimizer
+} from '@meng-xi/vite-plugin'
 
 export default defineConfig({
 	plugins: [
+		assetManifest({ outputFormat: 'vite', groupByEntry: true }),
 		autoImport({ imports: { vue: ['ref', 'reactive', 'computed'] }, dts: 'src/auto-imports.d.ts' }),
 		buildProgress(),
 		bundleAnalyzer({ outputFormat: 'both' }),
@@ -56,7 +72,8 @@ export default defineConfig({
 		versionUpdateChecker(),
 		htmlInject({ rules: [{ id: 'meta', content: '<meta name="description" content="My App">', position: 'head-end' }] }),
 		faviconManager('/assets'),
-		loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
+		loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' }),
+		imageOptimizer({ quality: { jpeg: 80, webp: 75 }, convertToWebp: { png: true } })
 	]
 })
 ```
@@ -65,6 +82,7 @@ export default defineConfig({
 
 | Plugin                                                                                                     | Description                                                                                                                           |
 | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| [assetManifest](https://mengxi-studio.github.io/vite-plugin/en/plugins/asset-manifest.html)                | Build artifact manifest generation with multiple output formats, entry grouping, and runtime injection                                |
 | [autoImport](https://mengxi-studio.github.io/vite-plugin/en/plugins/auto-import.html)                      | Auto-inject import statements with preset mappings, directory scanning, and Vue template auto-import                                  |
 | [buildProgress](https://mengxi-studio.github.io/vite-plugin/en/plugins/build-progress.html)                | Real-time terminal build progress bar, supports bar / spinner / minimal                                                               |
 | [bundleAnalyzer](https://mengxi-studio.github.io/vite-plugin/en/plugins/bundle-analyzer.html)              | Bundle volume analysis with JSON/HTML reports, gzip calculation, threshold alerts, and build diff                                     |
@@ -77,6 +95,7 @@ export default defineConfig({
 | [htmlInject](https://mengxi-studio.github.io/vite-plugin/en/plugins/html-inject.html)                      | HTML content injection with multiple positions, selector targeting, conditional injection, template variables, and security filtering |
 | [loadingManager](https://mengxi-studio.github.io/vite-plugin/en/plugins/loading-manager.html)              | Global Loading state management with request interception, debounce, transition animations, and white-screen Loading                  |
 | [versionUpdateChecker](https://mengxi-studio.github.io/vite-plugin/en/plugins/version-update-checker.html) | Runtime version update checking with multiple prompt styles and custom callbacks                                                      |
+| [imageOptimizer](https://mengxi-studio.github.io/vite-plugin/en/plugins/image-optimizer.html)              | Image optimization & format conversion, supports JPEG/PNG/WebP/AVIF/GIF/TIFF/SVG, concurrent processing and statistics report         |
 
 ## Plugin Development Framework
 
@@ -132,10 +151,13 @@ export const myPlugin = createPluginFactory(MyPlugin)
 Built-in general-purpose utility function library, organized by functional modules, supporting on-demand sub-path imports.
 
 ```typescript
-// Formatting: date params, template variable replacement, file size, date formatting
-import { getDateFormatParams, parseTemplate, formatDate, formatFileSize } from '@meng-xi/vite-plugin/common/format'
+// Formatting: date params, template variable replacement, file size, date formatting, compression ratio
+import { getDateFormatParams, parseTemplate, formatDate, formatFileSize, calcRatio } from '@meng-xi/vite-plugin/common/format'
 
-// File system: file copy, directory scan, safe write, change detection
+// Concurrency: batch execution with concurrency limit
+import { runWithConcurrency } from '@meng-xi/vite-plugin/common/concurrency'
+
+// File system: file copy, directory scan, safe write, change detection, report path resolution
 import { copySourceToTarget, scanDirectory, writeFileSyncSafely, shouldUpdateFileContent } from '@meng-xi/vite-plugin/common/fs'
 
 // HTML: tag injection, content sanitization, attribute escaping
@@ -154,15 +176,16 @@ import { Validator, validateGlobalName, validateNoScriptInTemplate } from '@meng
 import { normalizePath, isExtensionIncluded, isPathExcluded, isPreCompressed } from '@meng-xi/vite-plugin/common/path'
 ```
 
-| Sub-path                                                                                     | Description                                                                                         |
-| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| [`common/format`](https://mengxi-studio.github.io/vite-plugin/en/common/format.html)         | Date param extraction, template variable replacement `{{key}}`, date formatting `{YYYY}`, file size |
-| [`common/fs`](https://mengxi-studio.github.io/vite-plugin/en/common/fs.html)                 | File/directory copy, directory scan, sync safe write, file change detection                         |
-| [`common/html`](https://mengxi-studio.github.io/vite-plugin/en/common/html.html)             | HTML tag injection, dual-zone injection, content sanitization, HTML attribute value escaping        |
-| [`common/script`](https://mengxi-studio.github.io/vite-plugin/en/common/script.html)         | Callback body wrapping into safe function expressions (with try-catch)                              |
-| [`common/ui`](https://mengxi-studio.github.io/vite-plugin/en/common/ui.html)                 | Terminal ANSI color code constants                                                                  |
-| [`common/validation`](https://mengxi-studio.github.io/vite-plugin/en/common/validation.html) | Chain-style config validator, global name validation, script detection, callback field validation   |
-| [`common/path`](https://mengxi-studio.github.io/vite-plugin/en/common/path.html)             | Path normalization, extension filtering, path exclusion matching, pre-compression format detection  |
+| Sub-path                                                                                       | Description                                                                                                            |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| [`common/format`](https://mengxi-studio.github.io/vite-plugin/en/common/format.html)           | Date param extraction, template variable replacement `{{key}}`, date formatting `{YYYY}`, file size, compression ratio |
+| [`common/concurrency`](https://mengxi-studio.github.io/vite-plugin/en/common/concurrency.html) | Batch async execution with concurrency limit                                                                           |
+| [`common/fs`](https://mengxi-studio.github.io/vite-plugin/en/common/fs.html)                   | File/directory copy, directory scan, sync safe write, file change detection                                            |
+| [`common/html`](https://mengxi-studio.github.io/vite-plugin/en/common/html.html)               | HTML tag injection, dual-zone injection, content sanitization, HTML attribute value escaping                           |
+| [`common/script`](https://mengxi-studio.github.io/vite-plugin/en/common/script.html)           | Callback body wrapping into safe function expressions (with try-catch)                                                 |
+| [`common/ui`](https://mengxi-studio.github.io/vite-plugin/en/common/ui.html)                   | Terminal ANSI color code constants                                                                                     |
+| [`common/validation`](https://mengxi-studio.github.io/vite-plugin/en/common/validation.html)   | Chain-style config validator, global name validation, script detection, callback field validation                      |
+| [`common/path`](https://mengxi-studio.github.io/vite-plugin/en/common/path.html)               | Path normalization, extension filtering, path exclusion matching, pre-compression format detection                     |
 
 ## Sub-path Exports
 
@@ -174,6 +197,8 @@ import { normalizePath, isExtensionIncluded, isPathExcluded, isPreCompressed } f
 | `@meng-xi/vite-plugin/plugins`                        | All plugins                          |
 | `@meng-xi/vite-plugin/common`                         | All utility functions                |
 | `@meng-xi/vite-plugin/common/*`                       | Utility sub-modules                  |
+| `@meng-xi/vite-plugin/common/concurrency`             | Concurrency control utilities        |
+| `@meng-xi/vite-plugin/plugins/asset-manifest`         | assetManifest plugin                 |
 | `@meng-xi/vite-plugin/plugins/auto-import`            | autoImport plugin                    |
 | `@meng-xi/vite-plugin/plugins/build-progress`         | buildProgress plugin                 |
 | `@meng-xi/vite-plugin/plugins/bundle-analyzer`        | bundleAnalyzer plugin                |
@@ -186,6 +211,7 @@ import { normalizePath, isExtensionIncluded, isPathExcluded, isPreCompressed } f
 | `@meng-xi/vite-plugin/plugins/html-inject`            | htmlInject plugin                    |
 | `@meng-xi/vite-plugin/plugins/loading-manager`        | loadingManager plugin                |
 | `@meng-xi/vite-plugin/plugins/version-update-checker` | versionUpdateChecker plugin          |
+| `@meng-xi/vite-plugin/plugins/image-optimizer`        | imageOptimizer plugin                |
 
 ## License
 

package/README.md

@@ -15,9 +15,9 @@
 
 ## 特性
 
-- **开箱即用** - 12 个实用插件，覆盖自动导入、构建进度、产物分析与压缩、文件复制、环境变量校验、路由生成、版本管理、HTML 注入、图标管理、全局 Loading 等场景
+- **开箱即用** - 14 个实用插件，覆盖自动导入、构建进度、产物分析与压缩、文件复制、环境变量校验、路由生成、版本管理、HTML 注入、图标管理、全局 Loading、图片优化 等场景
 - **插件开发框架** - 导出 BasePlugin、Logger、Validator 等核心组件，快速构建自定义 Vite 插件
-- **通用工具库** - 内置 7 大 Common 工具模块，支持按需子路径导入
+- **通用工具库** - 内置 8 大 Common 工具模块，支持按需子路径导入
 - **类型安全** - 完整 TypeScript 类型定义与配置验证器
 - **按需导入** - 支持子路径导出，减少打包体积
 
@@ -40,10 +40,26 @@ pnpm add @meng-xi/vite-plugin -D
 
 ```typescript
 import { defineConfig } from 'vite'
-import { autoImport, buildProgress, bundleAnalyzer, compressAssets, copyFile, envGuard, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
+import {
+	assetManifest,
+	autoImport,
+	buildProgress,
+	bundleAnalyzer,
+	compressAssets,
+	copyFile,
+	envGuard,
+	generateRouter,
+	generateVersion,
+	versionUpdateChecker,
+	htmlInject,
+	faviconManager,
+	loadingManager,
+	imageOptimizer
+} from '@meng-xi/vite-plugin'
 
 export default defineConfig({
 	plugins: [
+		assetManifest({ outputFormat: 'vite', groupByEntry: true }),
 		autoImport({ imports: { vue: ['ref', 'reactive', 'computed'] }, dts: 'src/auto-imports.d.ts' }),
 		buildProgress(),
 		bundleAnalyzer({ outputFormat: 'both' }),
@@ -55,27 +71,30 @@ export default defineConfig({
 		versionUpdateChecker(),
 		htmlInject({ rules: [{ id: 'meta', content: '<meta name="description" content="My App">', position: 'head-end' }] }),
 		faviconManager('/assets'),
-		loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
+		loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' }),
+		imageOptimizer({ quality: { jpeg: 80, webp: 75 }, convertToWebp: { png: true } })
 	]
 })
 ```
 
 ## 内置插件
 
-| 插件                                                                                                    | 说明                                                                  |
-| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [autoImport](https://mengxi-studio.github.io/vite-plugin/plugins/auto-import.html)                      | 自动注入 import 语句，支持预设映射、目录扫描和 Vue 模板自动导入       |
-| [buildProgress](https://mengxi-studio.github.io/vite-plugin/plugins/build-progress.html)                | 终端实时构建进度条，支持 bar / spinner / minimal                      |
-| [bundleAnalyzer](https://mengxi-studio.github.io/vite-plugin/plugins/bundle-analyzer.html)              | 构建产物体积分析，支持 JSON/HTML 报告、gzip 计算、阈值告警和构建对比  |
-| [compressAssets](https://mengxi-studio.github.io/vite-plugin/plugins/compress-assets.html)              | 构建产物压缩，支持 gzip / brotli / both，并发压缩和统计报告           |
-| [copyFile](https://mengxi-studio.github.io/vite-plugin/plugins/copy-file.html)                          | 构建完成后复制文件或目录，支持增量复制                                |
-| [envGuard](https://mengxi-studio.github.io/vite-plugin/plugins/env-guard.html)                          | 环境变量校验，支持类型检查、范围验证、自定义规则和运行时守卫          |
-| [faviconManager](https://mengxi-studio.github.io/vite-plugin/plugins/favicon-manager.html)              | 管理网站图标链接注入和文件复制，支持字符串简写配置                    |
-| [generateRouter](https://mengxi-studio.github.io/vite-plugin/plugins/generate-router.html)              | 根据 pages.json 自动生成路由配置与类型声明（uni-app）                 |
-| [generateVersion](https://mengxi-studio.github.io/vite-plugin/plugins/generate-version.html)            | 自动生成版本号，支持文件输出和全局变量注入                            |
-| [htmlInject](https://mengxi-studio.github.io/vite-plugin/plugins/html-inject.html)                      | HTML 内容注入，支持多种位置、选择器定位、条件注入、模板变量和安全过滤 |
-| [loadingManager](https://mengxi-studio.github.io/vite-plugin/plugins/loading-manager.html)              | 全局 Loading 状态管理，支持请求拦截、防抖、过渡动画和白屏 Loading     |
-| [versionUpdateChecker](https://mengxi-studio.github.io/vite-plugin/plugins/version-update-checker.html) | 运行时版本更新检查，支持多种提示样式和自定义回调                      |
+| 插件                                                                                                    | 说明                                                                             |
+| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| [assetManifest](https://mengxi-studio.github.io/vite-plugin/plugins/asset-manifest.html)                | 构建产物资源清单生成，支持多种输出格式、按入口分组和运行时注入                   |
+| [autoImport](https://mengxi-studio.github.io/vite-plugin/plugins/auto-import.html)                      | 自动注入 import 语句，支持预设映射、目录扫描和 Vue 模板自动导入                  |
+| [buildProgress](https://mengxi-studio.github.io/vite-plugin/plugins/build-progress.html)                | 终端实时构建进度条，支持 bar / spinner / minimal                                 |
+| [bundleAnalyzer](https://mengxi-studio.github.io/vite-plugin/plugins/bundle-analyzer.html)              | 构建产物体积分析，支持 JSON/HTML 报告、gzip 计算、阈值告警和构建对比             |
+| [compressAssets](https://mengxi-studio.github.io/vite-plugin/plugins/compress-assets.html)              | 构建产物压缩，支持 gzip / brotli / both，并发压缩和统计报告                      |
+| [copyFile](https://mengxi-studio.github.io/vite-plugin/plugins/copy-file.html)                          | 构建完成后复制文件或目录，支持增量复制                                           |
+| [envGuard](https://mengxi-studio.github.io/vite-plugin/plugins/env-guard.html)                          | 环境变量校验，支持类型检查、范围验证、自定义规则和运行时守卫                     |
+| [faviconManager](https://mengxi-studio.github.io/vite-plugin/plugins/favicon-manager.html)              | 管理网站图标链接注入和文件复制，支持字符串简写配置                               |
+| [generateRouter](https://mengxi-studio.github.io/vite-plugin/plugins/generate-router.html)              | 根据 pages.json 自动生成路由配置与类型声明（uni-app）                            |
+| [generateVersion](https://mengxi-studio.github.io/vite-plugin/plugins/generate-version.html)            | 自动生成版本号，支持文件输出和全局变量注入                                       |
+| [htmlInject](https://mengxi-studio.github.io/vite-plugin/plugins/html-inject.html)                      | HTML 内容注入，支持多种位置、选择器定位、条件注入、模板变量和安全过滤            |
+| [loadingManager](https://mengxi-studio.github.io/vite-plugin/plugins/loading-manager.html)              | 全局 Loading 状态管理，支持请求拦截、防抖、过渡动画和白屏 Loading                |
+| [versionUpdateChecker](https://mengxi-studio.github.io/vite-plugin/plugins/version-update-checker.html) | 运行时版本更新检查，支持多种提示样式和自定义回调                                 |
+| [imageOptimizer](https://mengxi-studio.github.io/vite-plugin/plugins/image-optimizer.html)              | 图片优化压缩与格式转换，支持 JPEG/PNG/WebP/AVIF/GIF/TIFF/SVG，并发处理和统计报告 |
 
 ## 插件开发框架
 
@@ -131,10 +150,13 @@ export const myPlugin = createPluginFactory(MyPlugin)
 内置通用工具函数库，按功能模块组织，支持子路径按需导入。
 
 ```typescript
-// 格式化：日期参数、模板变量替换、文件大小、日期格式化
-import { getDateFormatParams, parseTemplate, formatDate, formatFileSize } from '@meng-xi/vite-plugin/common/format'
+// 格式化：日期参数、模板变量替换、文件大小、日期格式化、压缩率计算
+import { getDateFormatParams, parseTemplate, formatDate, formatFileSize, calcRatio } from '@meng-xi/vite-plugin/common/format'
 
-// 文件系统：文件复制、目录扫描、安全写入、变更检测
+// 并发控制：带并发限制的批量执行
+import { runWithConcurrency } from '@meng-xi/vite-plugin/common/concurrency'
+
+// 文件系统：文件复制、目录扫描、安全写入、变更检测、报告路径解析
 import { copySourceToTarget, scanDirectory, writeFileSyncSafely, shouldUpdateFileContent } from '@meng-xi/vite-plugin/common/fs'
 
 // HTML：标签注入、内容消毒、属性转义
@@ -153,15 +175,16 @@ import { Validator, validateGlobalName, validateNoScriptInTemplate } from '@meng
 import { normalizePath, isExtensionIncluded, isPathExcluded, isPreCompressed } from '@meng-xi/vite-plugin/common/path'
 ```
 
-| 子路径                                                                                    | 描述                                                                      |
-| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| [`common/format`](https://mengxi-studio.github.io/vite-plugin/common/format.html)         | 日期参数提取、模板变量替换 `{{key}}`、日期格式化 `{YYYY}`、文件大小格式化 |
-| [`common/fs`](https://mengxi-studio.github.io/vite-plugin/common/fs.html)                 | 文件/目录复制、目录扫描、同步安全写入、文件变更检测                       |
-| [`common/html`](https://mengxi-studio.github.io/vite-plugin/common/html.html)             | HTML 标签注入、双区域注入、内容安全消毒、HTML 属性值转义                  |
-| [`common/script`](https://mengxi-studio.github.io/vite-plugin/common/script.html)         | 回调函数体包装为安全的函数表达式（含 try-catch）                          |
-| [`common/ui`](https://mengxi-studio.github.io/vite-plugin/common/ui.html)                 | 终端 ANSI 颜色码常量                                                      |
-| [`common/validation`](https://mengxi-studio.github.io/vite-plugin/common/validation.html) | 链式配置验证器、全局名称校验、脚本检测、回调字段校验                      |
-| [`common/path`](https://mengxi-studio.github.io/vite-plugin/common/path.html)             | 路径规范化、扩展名过滤、路径排除匹配、预压缩格式检测                      |
+| 子路径                                                                                      | 描述                                                                                  |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`common/format`](https://mengxi-studio.github.io/vite-plugin/common/format.html)           | 日期参数提取、模板变量替换 `{{key}}`、日期格式化 `{YYYY}`、文件大小格式化、压缩率计算 |
+| [`common/concurrency`](https://mengxi-studio.github.io/vite-plugin/common/concurrency.html) | 带并发限制的批量异步执行                                                              |
+| [`common/fs`](https://mengxi-studio.github.io/vite-plugin/common/fs.html)                   | 文件/目录复制、目录扫描、同步安全写入、文件变更检测                                   |
+| [`common/html`](https://mengxi-studio.github.io/vite-plugin/common/html.html)               | HTML 标签注入、双区域注入、内容安全消毒、HTML 属性值转义                              |
+| [`common/script`](https://mengxi-studio.github.io/vite-plugin/common/script.html)           | 回调函数体包装为安全的函数表达式（含 try-catch）                                      |
+| [`common/ui`](https://mengxi-studio.github.io/vite-plugin/common/ui.html)                   | 终端 ANSI 颜色码常量                                                                  |
+| [`common/validation`](https://mengxi-studio.github.io/vite-plugin/common/validation.html)   | 链式配置验证器、全局名称校验、脚本检测、回调字段校验                                  |
+| [`common/path`](https://mengxi-studio.github.io/vite-plugin/common/path.html)               | 路径规范化、扩展名过滤、路径排除匹配、预压缩格式检测                                  |
 
 ## 子路径导出
 
@@ -173,6 +196,8 @@ import { normalizePath, isExtensionIncluded, isPathExcluded, isPreCompressed } f
 | `@meng-xi/vite-plugin/plugins`                        | 所有插件                  |
 | `@meng-xi/vite-plugin/common`                         | 所有工具函数              |
 | `@meng-xi/vite-plugin/common/*`                       | 各工具子模块              |
+| `@meng-xi/vite-plugin/common/concurrency`             | 并发控制工具              |
+| `@meng-xi/vite-plugin/plugins/asset-manifest`         | assetManifest 插件        |
 | `@meng-xi/vite-plugin/plugins/auto-import`            | autoImport 插件           |
 | `@meng-xi/vite-plugin/plugins/build-progress`         | buildProgress 插件        |
 | `@meng-xi/vite-plugin/plugins/bundle-analyzer`        | bundleAnalyzer 插件       |
@@ -185,6 +210,7 @@ import { normalizePath, isExtensionIncluded, isPathExcluded, isPreCompressed } f
 | `@meng-xi/vite-plugin/plugins/html-inject`            | htmlInject 插件           |
 | `@meng-xi/vite-plugin/plugins/loading-manager`        | loadingManager 插件       |
 | `@meng-xi/vite-plugin/plugins/version-update-checker` | versionUpdateChecker 插件 |
+| `@meng-xi/vite-plugin/plugins/image-optimizer`        | imageOptimizer 插件       |
 
 ## License
 

package/dist/common/concurrency/index.cjs

@@ -0,0 +1 @@
+"use strict";async function runWithConcurrency(n,a,e){const t=[];let r=0;async function i(){for(;r<n.length;){const c=r++,o=await a(n[c]);t[c]=o}}const l=Array(Math.min(e,n.length)).fill(null).map(()=>i());return await Promise.all(l),t}exports.runWithConcurrency=runWithConcurrency;

package/dist/common/concurrency/index.d.cts

@@ -0,0 +1,26 @@
+/**
+ * 带并发限制的批量执行
+ *
+ * @template T - 输入项类型
+ * @template R - 返回结果类型
+ * @param {T[]} items - 待处理项列表
+ * @param {(item: T) => Promise<R>} handler - 处理函数
+ * @param {number} concurrency - 最大并发数
+ * @returns {Promise<R[]>} 处理结果数组，顺序与输入项对应
+ *
+ * @description 使用工作池模式并发执行异步任务，结果顺序与输入项对应。
+ * 当并发数大于等于项数时，所有项同时执行；否则按并发数分批执行。
+ *
+ * @example
+ * ```typescript
+ * const results = await runWithConcurrency(
+ *   [1, 2, 3, 4, 5],
+ *   async (n) => { await delay(100); return n * 2 },
+ *   2
+ * )
+ * // [2, 4, 6, 8, 10]
+ * ```
+ */
+declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
+
+export { runWithConcurrency };

package/dist/common/concurrency/index.d.mts

@@ -0,0 +1,26 @@
+/**
+ * 带并发限制的批量执行
+ *
+ * @template T - 输入项类型
+ * @template R - 返回结果类型
+ * @param {T[]} items - 待处理项列表
+ * @param {(item: T) => Promise<R>} handler - 处理函数
+ * @param {number} concurrency - 最大并发数
+ * @returns {Promise<R[]>} 处理结果数组，顺序与输入项对应
+ *
+ * @description 使用工作池模式并发执行异步任务，结果顺序与输入项对应。
+ * 当并发数大于等于项数时，所有项同时执行；否则按并发数分批执行。
+ *
+ * @example
+ * ```typescript
+ * const results = await runWithConcurrency(
+ *   [1, 2, 3, 4, 5],
+ *   async (n) => { await delay(100); return n * 2 },
+ *   2
+ * )
+ * // [2, 4, 6, 8, 10]
+ * ```
+ */
+declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
+
+export { runWithConcurrency };

package/dist/common/concurrency/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 带并发限制的批量执行
+ *
+ * @template T - 输入项类型
+ * @template R - 返回结果类型
+ * @param {T[]} items - 待处理项列表
+ * @param {(item: T) => Promise<R>} handler - 处理函数
+ * @param {number} concurrency - 最大并发数
+ * @returns {Promise<R[]>} 处理结果数组，顺序与输入项对应
+ *
+ * @description 使用工作池模式并发执行异步任务，结果顺序与输入项对应。
+ * 当并发数大于等于项数时，所有项同时执行；否则按并发数分批执行。
+ *
+ * @example
+ * ```typescript
+ * const results = await runWithConcurrency(
+ *   [1, 2, 3, 4, 5],
+ *   async (n) => { await delay(100); return n * 2 },
+ *   2
+ * )
+ * // [2, 4, 6, 8, 10]
+ * ```
+ */
+declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
+
+export { runWithConcurrency };

package/dist/common/concurrency/index.mjs

@@ -0,0 +1 @@
+async function s(n,c,l){const t=[];let r=0;async function o(){for(;r<n.length;){const a=r++,i=await c(n[a]);t[a]=i}}const e=Array(Math.min(l,n.length)).fill(null).map(()=>o());return await Promise.all(e),t}export{s as runWithConcurrency};

package/dist/common/format/index.cjs

@@ -1 +1 @@
-"use strict";function t(e,r=2){return e.toString().padStart(r,"0")}function getDateFormatParams(e=new Date){return{YYYY:e.getFullYear().toString(),YY:e.getFullYear().toString().slice(-2),MM:t(e.getMonth()+1),DD:t(e.getDate()),HH:t(e.getHours()),mm:t(e.getMinutes()),ss:t(e.getSeconds()),SSS:t(e.getMilliseconds(),3),timestamp:e.getTime().toString()}}function parseTemplate(e,r){let o=e;for(const[n,a]of Object.entries(r)){const s=n.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),i=a.replace(/\$/g,"$$$$");o=o.replace(new RegExp(`\\{\\{${s}\\}\\}`,"g"),i)}return o}function formatDate(e,r){const o=getDateFormatParams(e);let n=r;for(const[a,s]of Object.entries(o))n=n.replace(new RegExp(`\\{${a}\\}`,"g"),s);return n}function formatFileSize(e){return e<1024?`${e}B`:e<1024*1024?`${(e/1024).toFixed(1)}KB`:`${(e/(1024*1024)).toFixed(2)}MB`}exports.formatDate=formatDate,exports.formatFileSize=formatFileSize,exports.getDateFormatParams=getDateFormatParams,exports.parseTemplate=parseTemplate;
+"use strict";function r(t,e=2){return t.toString().padStart(e,"0")}function getDateFormatParams(t=new Date){return{YYYY:t.getFullYear().toString(),YY:t.getFullYear().toString().slice(-2),MM:r(t.getMonth()+1),DD:r(t.getDate()),HH:r(t.getHours()),mm:r(t.getMinutes()),ss:r(t.getSeconds()),SSS:r(t.getMilliseconds(),3),timestamp:t.getTime().toString()}}function parseTemplate(t,e){let o=t;for(const[n,a]of Object.entries(e)){const i=n.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),s=a.replace(/\$/g,"$$$$");o=o.replace(new RegExp(`\\{\\{${i}\\}\\}`,"g"),s)}return o}function formatDate(t,e){const o=getDateFormatParams(t);let n=e;for(const[a,i]of Object.entries(o))n=n.replace(new RegExp(`\\{${a}\\}`,"g"),i);return n}function formatFileSize(t){return t<1024?`${t}B`:t<1024*1024?`${(t/1024).toFixed(1)}KB`:`${(t/(1024*1024)).toFixed(2)}MB`}function calcRatio(t,e){return t>0?Number(((1-e/t)*100).toFixed(1)):0}exports.calcRatio=calcRatio,exports.formatDate=formatDate,exports.formatFileSize=formatFileSize,exports.getDateFormatParams=getDateFormatParams,exports.parseTemplate=parseTemplate;

package/dist/common/format/index.d.cts

@@ -88,6 +88,24 @@ declare function formatDate(date: Date, format: string): string;
  * ```
  */
 declare function formatFileSize(bytes: number): string;
+/**
+ * 计算压缩率百分比
+ *
+ * @param {number} originalSize - 原始大小（字节）
+ * @param {number} compressedSize - 压缩后大小（字节）
+ * @returns {number} 压缩率百分比（0-100），如 65.2 表示体积减少 65.2%
+ *
+ * @description 计算公式: (1 - compressedSize / originalSize) * 100，保留一位小数。
+ * 当 originalSize 为 0 时返回 0，避免除零错误。
+ *
+ * @example
+ * ```typescript
+ * calcRatio(10000, 6000)  // 40.0
+ * calcRatio(10000, 10000) // 0
+ * calcRatio(0, 0)         // 0
+ * ```
+ */
+declare function calcRatio(originalSize: number, compressedSize: number): number;
 
-export { formatDate, formatFileSize, getDateFormatParams, parseTemplate };
+export { calcRatio, formatDate, formatFileSize, getDateFormatParams, parseTemplate };
 export type { DateFormatOptions };

package/dist/common/format/index.d.mts

@@ -88,6 +88,24 @@ declare function formatDate(date: Date, format: string): string;
  * ```
  */
 declare function formatFileSize(bytes: number): string;
+/**
+ * 计算压缩率百分比
+ *
+ * @param {number} originalSize - 原始大小（字节）
+ * @param {number} compressedSize - 压缩后大小（字节）
+ * @returns {number} 压缩率百分比（0-100），如 65.2 表示体积减少 65.2%
+ *
+ * @description 计算公式: (1 - compressedSize / originalSize) * 100，保留一位小数。
+ * 当 originalSize 为 0 时返回 0，避免除零错误。
+ *
+ * @example
+ * ```typescript
+ * calcRatio(10000, 6000)  // 40.0
+ * calcRatio(10000, 10000) // 0
+ * calcRatio(0, 0)         // 0
+ * ```
+ */
+declare function calcRatio(originalSize: number, compressedSize: number): number;
 
-export { formatDate, formatFileSize, getDateFormatParams, parseTemplate };
+export { calcRatio, formatDate, formatFileSize, getDateFormatParams, parseTemplate };
 export type { DateFormatOptions };

package/dist/common/format/index.d.ts

@@ -88,6 +88,24 @@ declare function formatDate(date: Date, format: string): string;
  * ```
  */
 declare function formatFileSize(bytes: number): string;
+/**
+ * 计算压缩率百分比
+ *
+ * @param {number} originalSize - 原始大小（字节）
+ * @param {number} compressedSize - 压缩后大小（字节）
+ * @returns {number} 压缩率百分比（0-100），如 65.2 表示体积减少 65.2%
+ *
+ * @description 计算公式: (1 - compressedSize / originalSize) * 100，保留一位小数。
+ * 当 originalSize 为 0 时返回 0，避免除零错误。
+ *
+ * @example
+ * ```typescript
+ * calcRatio(10000, 6000)  // 40.0
+ * calcRatio(10000, 10000) // 0
+ * calcRatio(0, 0)         // 0
+ * ```
+ */
+declare function calcRatio(originalSize: number, compressedSize: number): number;
 
-export { formatDate, formatFileSize, getDateFormatParams, parseTemplate };
+export { calcRatio, formatDate, formatFileSize, getDateFormatParams, parseTemplate };
 export type { DateFormatOptions };

package/dist/common/format/index.mjs

@@ -1 +1 @@
-function e(t,n=2){return t.toString().padStart(n,"0")}function g(t=new Date){return{YYYY:t.getFullYear().toString(),YY:t.getFullYear().toString().slice(-2),MM:e(t.getMonth()+1),DD:e(t.getDate()),HH:e(t.getHours()),mm:e(t.getMinutes()),ss:e(t.getSeconds()),SSS:e(t.getMilliseconds(),3),timestamp:t.getTime().toString()}}function c(t,n){let r=t;for(const[o,i]of Object.entries(n)){const a=o.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),s=i.replace(/\$/g,"$$$$");r=r.replace(new RegExp(`\\{\\{${a}\\}\\}`,"g"),s)}return r}function l(t,n){const r=g(t);let o=n;for(const[i,a]of Object.entries(r))o=o.replace(new RegExp(`\\{${i}\\}`,"g"),a);return o}function u(t){return t<1024?`${t}B`:t<1024*1024?`${(t/1024).toFixed(1)}KB`:`${(t/(1024*1024)).toFixed(2)}MB`}export{l as formatDate,u as formatFileSize,g as getDateFormatParams,c as parseTemplate};
+function n(t,e=2){return t.toString().padStart(e,"0")}function c(t=new Date){return{YYYY:t.getFullYear().toString(),YY:t.getFullYear().toString().slice(-2),MM:n(t.getMonth()+1),DD:n(t.getDate()),HH:n(t.getHours()),mm:n(t.getMinutes()),ss:n(t.getSeconds()),SSS:n(t.getMilliseconds(),3),timestamp:t.getTime().toString()}}function u(t,e){let r=t;for(const[o,i]of Object.entries(e)){const a=o.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),g=i.replace(/\$/g,"$$$$");r=r.replace(new RegExp(`\\{\\{${a}\\}\\}`,"g"),g)}return r}function s(t,e){const r=c(t);let o=e;for(const[i,a]of Object.entries(r))o=o.replace(new RegExp(`\\{${i}\\}`,"g"),a);return o}function l(t){return t<1024?`${t}B`:t<1024*1024?`${(t/1024).toFixed(1)}KB`:`${(t/(1024*1024)).toFixed(2)}MB`}function f(t,e){return t>0?Number(((1-e/t)*100).toFixed(1)):0}export{f as calcRatio,s as formatDate,l as formatFileSize,c as getDateFormatParams,u as parseTemplate};

package/dist/common/fs/index.cjs

@@ -1 +1 @@
-"use strict";const s=require("fs"),u=require("path");function _interopDefaultCompat(t){return t&&typeof t=="object"&&"default"in t?t.default:t}const s__default=_interopDefaultCompat(s),u__default=_interopDefaultCompat(u),R=10;async function checkSourceExists(t){try{await s__default.promises.access(t,s__default.constants.F_OK)}catch(e){const i=e;throw i.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${t}`):i.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${i.message}`)}}async function g(t){try{await s__default.promises.mkdir(t,{recursive:!0})}catch(e){const i=e;throw i.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${i.message}`)}}async function h(t,e){const i=await s__default.promises.readdir(t,{withFileTypes:!0}),r=[];for(const o of i){const c=u__default.join(t,o.name),l=o.isFile(),F=o.isDirectory();if(r.push({path:c,isFile:l,isDirectory:F}),F&&e){const p=await h(c,e);r.push(...p)}}return r}async function C(t,e){try{const[i,r]=await Promise.all([s__default.promises.stat(t),s__default.promises.stat(e)]);return i.mtimeMs>r.mtimeMs||i.size!==r.size}catch{return!0}}async function D(t){try{return await s__default.promises.access(t,s__default.constants.F_OK),!0}catch{return!1}}async function T(t,e,i){const r=[];let o=0;async function c(){for(;o<t.length;){const F=o++,p=await e(t[F]);r[F]=p}}const l=Array(Math.min(i,t.length)).fill(null).map(()=>c());return await Promise.all(l),r}async function copySourceToTarget(t,e,i){const r=Date.now(),{recursive:o,overwrite:c,incremental:l=!1,parallelLimit:F=R}=i;let p=0,w=0,f=0;if((await s__default.promises.stat(t)).isDirectory()){await g(e);const a=await h(t,o),E=a.filter(n=>n.isFile);f=a.filter(n=>n.isDirectory).length;const S=new Set;for(const n of E){const A=u__default.relative(t,n.path),d=u__default.dirname(u__default.join(e,A));S.add(d)}await Promise.all([...S].map(n=>g(n)));const x=await T(E,async n=>{const A=u__default.relative(t,n.path),d=u__default.join(e,A);let m=c;return m||(m=!await D(d)),l&&m&&(m=await C(n.path,d)),m?(await s__default.promises.copyFile(n.path,d),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},F);for(const n of x)n.copied&&p++,n.skipped&&w++}else{await g(u__default.dirname(e));let a=c;a||(a=!await D(e)),l&&a&&(a=await C(t,e)),a?(await s__default.promises.copyFile(t,e),p++):w++}const y=Date.now()-r;return{copiedFiles:p,skippedFiles:w,copiedDirs:f,executionTime:y}}async function writeFileContent(t,e){try{await s__default.promises.writeFile(t,e,"utf-8")}catch(i){const r=i;throw r.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${t}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function scanDirectory(t,e={}){const{includeExtensions:i=[],excludePatterns:r=[],filter:o}=e,c=[];async function l(F){const p=await s__default.promises.readdir(F,{withFileTypes:!0});for(const w of p){const f=u__default.join(F,w.name);if(w.isDirectory()){await l(f);continue}if(!w.isFile()||r.some(E=>E.startsWith("*")?f.endsWith(E.slice(1)):f.includes(E)))continue;const y=u__default.extname(w.name).toLowerCase();if(i.length>0&&!i.includes(y))continue;const a=await s__default.promises.stat(f);o&&!o(f,y,a.size)||c.push({filePath:f,size:a.size,extension:y})}}return await l(t),c}async function writeJsonReport(t,e,i=2){await writeFileContent(t,JSON.stringify(e,null,i))}function writeFileSyncSafely(t,e){const i=u__default.dirname(t);s__default.existsSync(i)||s__default.mkdirSync(i,{recursive:!0}),s__default.writeFileSync(t,e,"utf-8")}function shouldUpdateFileContent(t,e){if(!s__default.existsSync(t))return!0;try{return s__default.readFileSync(t,"utf-8")!==e}catch{return!0}}exports.checkSourceExists=checkSourceExists,exports.copySourceToTarget=copySourceToTarget,exports.scanDirectory=scanDirectory,exports.shouldUpdateFileContent=shouldUpdateFileContent,exports.writeFileContent=writeFileContent,exports.writeFileSyncSafely=writeFileSyncSafely,exports.writeJsonReport=writeJsonReport;
+"use strict";const s=require("fs"),o=require("path"),common_concurrency_index=require("../concurrency/index.cjs");function _interopDefaultCompat(t){return t&&typeof t=="object"&&"default"in t?t.default:t}const s__default=_interopDefaultCompat(s),o__default=_interopDefaultCompat(o),R=10;async function checkSourceExists(t){try{await s__default.promises.access(t,s__default.constants.F_OK)}catch(e){const u=e;throw u.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${t}`):u.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${u.message}`)}}async function g(t){try{await s__default.promises.mkdir(t,{recursive:!0})}catch(e){const u=e;throw u.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${u.message}`)}}async function C(t,e){const u=await s__default.promises.readdir(t,{withFileTypes:!0}),n=[];for(const a of u){const F=o__default.join(t,a.name),p=a.isFile(),f=a.isDirectory();if(n.push({path:F,isFile:p,isDirectory:f}),f&&e){const w=await C(F,e);n.push(...w)}}return n}async function h(t,e){try{const[u,n]=await Promise.all([s__default.promises.stat(t),s__default.promises.stat(e)]);return u.mtimeMs>n.mtimeMs||u.size!==n.size}catch{return!0}}async function D(t){try{return await s__default.promises.access(t,s__default.constants.F_OK),!0}catch{return!1}}async function copySourceToTarget(t,e,u){const n=Date.now(),{recursive:a,overwrite:F,incremental:p=!1,parallelLimit:f=R}=u;let w=0,l=0,c=0;if((await s__default.promises.stat(t)).isDirectory()){await g(e);const i=await C(t,a),E=i.filter(r=>r.isFile);c=i.filter(r=>r.isDirectory).length;const x=new Set;for(const r of E){const A=o__default.relative(t,r.path),d=o__default.dirname(o__default.join(e,A));x.add(d)}await Promise.all([...x].map(r=>g(r)));const S=await common_concurrency_index.runWithConcurrency(E,async r=>{const A=o__default.relative(t,r.path),d=o__default.join(e,A);let m=F;return m||(m=!await D(d)),p&&m&&(m=await h(r.path,d)),m?(await s__default.promises.copyFile(r.path,d),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},f);for(const r of S)r.copied&&w++,r.skipped&&l++}else{await g(o__default.dirname(e));let i=F;i||(i=!await D(e)),p&&i&&(i=await h(t,e)),i?(await s__default.promises.copyFile(t,e),w++):l++}const y=Date.now()-n;return{copiedFiles:w,skippedFiles:l,copiedDirs:c,executionTime:y}}async function writeFileContent(t,e){try{await s__default.promises.writeFile(t,e,"utf-8")}catch(u){const n=u;throw n.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${t}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${n.message}`)}}async function scanDirectory(t,e={}){const{includeExtensions:u=[],excludePatterns:n=[],filter:a}=e,F=[];async function p(f){const w=await s__default.promises.readdir(f,{withFileTypes:!0});for(const l of w){const c=o__default.join(f,l.name);if(l.isDirectory()){await p(c);continue}if(!l.isFile()||n.some(E=>E.startsWith("*")?c.endsWith(E.slice(1)):c.includes(E)))continue;const y=o__default.extname(l.name).toLowerCase();if(u.length>0&&!u.includes(y))continue;const i=await s__default.promises.stat(c);a&&!a(c,y,i.size)||F.push({filePath:c,size:i.size,extension:y})}}return await p(t),F}async function writeJsonReport(t,e,u=2){await writeFileContent(t,JSON.stringify(e,null,u))}function writeFileSyncSafely(t,e){const u=o__default.dirname(t);s__default.existsSync(u)||s__default.mkdirSync(u,{recursive:!0}),s__default.writeFileSync(t,e,"utf-8")}function shouldUpdateFileContent(t,e){if(!s__default.existsSync(t))return!0;try{return s__default.readFileSync(t,"utf-8")!==e}catch{return!0}}function resolveReportPath(t,e){return e?o__default.isAbsolute(e)?e:o__default.join(t,e):null}exports.checkSourceExists=checkSourceExists,exports.copySourceToTarget=copySourceToTarget,exports.resolveReportPath=resolveReportPath,exports.scanDirectory=scanDirectory,exports.shouldUpdateFileContent=shouldUpdateFileContent,exports.writeFileContent=writeFileContent,exports.writeFileSyncSafely=writeFileSyncSafely,exports.writeJsonReport=writeJsonReport;

package/dist/common/fs/index.d.cts

@@ -160,6 +160,24 @@ declare function writeFileSyncSafely(filePath: string, content: string): void;
  * ```
  */
 declare function shouldUpdateFileContent(filePath: string, newContent: string): boolean;
+/**
+ * 解析报告输出路径
+ *
+ * @param {string} outDir - 构建输出目录路径
+ * @param {string | false} reportPath - 报告文件路径，为 false 时返回 null
+ * @returns {string | null} 解析后的绝对路径，reportPath 为 false 时返回 null
+ *
+ * @description 当 reportPath 为相对路径时，相对于 outDir 解析；
+ * 为绝对路径时直接使用；为 false 时返回 null。
+ *
+ * @example
+ * ```typescript
+ * resolveReportPath('dist', 'report.json')   // 'dist/report.json'
+ * resolveReportPath('dist', '/tmp/r.json')    // '/tmp/r.json'
+ * resolveReportPath('dist', false)            // null
+ * ```
+ */
+declare function resolveReportPath(outDir: string, reportPath: string | false): string | null;
 
-export { checkSourceExists, copySourceToTarget, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
+export { checkSourceExists, copySourceToTarget, resolveReportPath, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
 export type { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile };

package/dist/common/fs/index.d.mts

@@ -160,6 +160,24 @@ declare function writeFileSyncSafely(filePath: string, content: string): void;
  * ```
  */
 declare function shouldUpdateFileContent(filePath: string, newContent: string): boolean;
+/**
+ * 解析报告输出路径
+ *
+ * @param {string} outDir - 构建输出目录路径
+ * @param {string | false} reportPath - 报告文件路径，为 false 时返回 null
+ * @returns {string | null} 解析后的绝对路径，reportPath 为 false 时返回 null
+ *
+ * @description 当 reportPath 为相对路径时，相对于 outDir 解析；
+ * 为绝对路径时直接使用；为 false 时返回 null。
+ *
+ * @example
+ * ```typescript
+ * resolveReportPath('dist', 'report.json')   // 'dist/report.json'
+ * resolveReportPath('dist', '/tmp/r.json')    // '/tmp/r.json'
+ * resolveReportPath('dist', false)            // null
+ * ```
+ */
+declare function resolveReportPath(outDir: string, reportPath: string | false): string | null;
 
-export { checkSourceExists, copySourceToTarget, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
+export { checkSourceExists, copySourceToTarget, resolveReportPath, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
 export type { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile };

package/dist/common/fs/index.d.ts

@@ -160,6 +160,24 @@ declare function writeFileSyncSafely(filePath: string, content: string): void;
  * ```
  */
 declare function shouldUpdateFileContent(filePath: string, newContent: string): boolean;
+/**
+ * 解析报告输出路径
+ *
+ * @param {string} outDir - 构建输出目录路径
+ * @param {string | false} reportPath - 报告文件路径，为 false 时返回 null
+ * @returns {string | null} 解析后的绝对路径，reportPath 为 false 时返回 null
+ *
+ * @description 当 reportPath 为相对路径时，相对于 outDir 解析；
+ * 为绝对路径时直接使用；为 false 时返回 null。
+ *
+ * @example
+ * ```typescript
+ * resolveReportPath('dist', 'report.json')   // 'dist/report.json'
+ * resolveReportPath('dist', '/tmp/r.json')    // '/tmp/r.json'
+ * resolveReportPath('dist', false)            // null
+ * ```
+ */
+declare function resolveReportPath(outDir: string, reportPath: string | false): string | null;
 
-export { checkSourceExists, copySourceToTarget, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
+export { checkSourceExists, copySourceToTarget, resolveReportPath, scanDirectory, shouldUpdateFileContent, writeFileContent, writeFileSyncSafely, writeJsonReport };
 export type { CopyOptions, CopyResult, ScanDirectoryOptions, ScannedFile };

package/dist/common/fs/index.mjs

@@ -1 +1 @@
-import e from"fs";import F from"path";const B=10;async function k(t){try{await e.promises.access(t,e.constants.F_OK)}catch(u){const i=u;throw i.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${t}`):i.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${i.message}`)}}async function D(t){try{await e.promises.mkdir(t,{recursive:!0})}catch(u){const i=u;throw i.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${i.message}`)}}async function C(t,u){const i=await e.promises.readdir(t,{withFileTypes:!0}),r=[];for(const n of i){const a=F.join(t,n.name),l=n.isFile(),c=n.isDirectory();if(r.push({path:a,isFile:l,isDirectory:c}),c&&u){const p=await C(a,u);r.push(...p)}}return r}async function S(t,u){try{const[i,r]=await Promise.all([e.promises.stat(t),e.promises.stat(u)]);return i.mtimeMs>r.mtimeMs||i.size!==r.size}catch{return!0}}async function x(t){try{return await e.promises.access(t,e.constants.F_OK),!0}catch{return!1}}async function v(t,u,i){const r=[];let n=0;async function a(){for(;n<t.length;){const c=n++,p=await u(t[c]);r[c]=p}}const l=Array(Math.min(i,t.length)).fill(null).map(()=>a());return await Promise.all(l),r}async function T(t,u,i){const r=Date.now(),{recursive:n,overwrite:a,incremental:l=!1,parallelLimit:c=B}=i;let p=0,E=0,w=0;if((await e.promises.stat(t)).isDirectory()){await D(u);const o=await C(t,n),f=o.filter(s=>s.isFile);w=o.filter(s=>s.isDirectory).length;const A=new Set;for(const s of f){const h=F.relative(t,s.path),y=F.dirname(F.join(u,h));A.add(y)}await Promise.all([...A].map(s=>D(s)));const $=await v(f,async s=>{const h=F.relative(t,s.path),y=F.join(u,h);let d=a;return d||(d=!await x(y)),l&&d&&(d=await S(s.path,y)),d?(await e.promises.copyFile(s.path,y),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},c);for(const s of $)s.copied&&p++,s.skipped&&E++}else{await D(F.dirname(u));let o=a;o||(o=!await x(u)),l&&o&&(o=await S(t,u)),o?(await e.promises.copyFile(t,u),p++):E++}const m=Date.now()-r;return{copiedFiles:p,skippedFiles:E,copiedDirs:w,executionTime:m}}async function g(t,u){try{await e.promises.writeFile(t,u,"utf-8")}catch(i){const r=i;throw r.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${t}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function z(t,u={}){const{includeExtensions:i=[],excludePatterns:r=[],filter:n}=u,a=[];async function l(c){const p=await e.promises.readdir(c,{withFileTypes:!0});for(const E of p){const w=F.join(c,E.name);if(E.isDirectory()){await l(w);continue}if(!E.isFile()||r.some(f=>f.startsWith("*")?w.endsWith(f.slice(1)):w.includes(f)))continue;const m=F.extname(E.name).toLowerCase();if(i.length>0&&!i.includes(m))continue;const o=await e.promises.stat(w);n&&!n(w,m,o.size)||a.push({filePath:w,size:o.size,extension:m})}}return await l(t),a}async function P(t,u,i=2){await g(t,JSON.stringify(u,null,i))}function j(t,u){const i=F.dirname(t);e.existsSync(i)||e.mkdirSync(i,{recursive:!0}),e.writeFileSync(t,u,"utf-8")}function O(t,u){if(!e.existsSync(t))return!0;try{return e.readFileSync(t,"utf-8")!==u}catch{return!0}}export{k as checkSourceExists,T as copySourceToTarget,z as scanDirectory,O as shouldUpdateFileContent,g as writeFileContent,j as writeFileSyncSafely,P as writeJsonReport};
+import i from"fs";import s from"path";import{runWithConcurrency as v}from"../concurrency/index.mjs";const B=10;async function k(t){try{await i.promises.access(t,i.constants.F_OK)}catch(u){const e=u;throw e.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${t}`):e.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}async function D(t){try{await i.promises.mkdir(t,{recursive:!0})}catch(u){const e=u;throw e.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${t}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}async function C(t,u){const e=await i.promises.readdir(t,{withFileTypes:!0}),r=[];for(const c of e){const F=s.join(t,c.name),E=c.isFile(),p=c.isDirectory();if(r.push({path:F,isFile:E,isDirectory:p}),p&&u){const w=await C(F,u);r.push(...w)}}return r}async function S(t,u){try{const[e,r]=await Promise.all([i.promises.stat(t),i.promises.stat(u)]);return e.mtimeMs>r.mtimeMs||e.size!==r.size}catch{return!0}}async function x(t){try{return await i.promises.access(t,i.constants.F_OK),!0}catch{return!1}}async function T(t,u,e){const r=Date.now(),{recursive:c,overwrite:F,incremental:E=!1,parallelLimit:p=B}=e;let w=0,l=0,a=0;if((await i.promises.stat(t)).isDirectory()){await D(u);const o=await C(t,c),f=o.filter(n=>n.isFile);a=o.filter(n=>n.isDirectory).length;const A=new Set;for(const n of f){const h=s.relative(t,n.path),y=s.dirname(s.join(u,h));A.add(y)}await Promise.all([...A].map(n=>D(n)));const g=await v(f,async n=>{const h=s.relative(t,n.path),y=s.join(u,h);let d=F;return d||(d=!await x(y)),E&&d&&(d=await S(n.path,y)),d?(await i.promises.copyFile(n.path,y),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},p);for(const n of g)n.copied&&w++,n.skipped&&l++}else{await D(s.dirname(u));let o=F;o||(o=!await x(u)),E&&o&&(o=await S(t,u)),o?(await i.promises.copyFile(t,u),w++):l++}const m=Date.now()-r;return{copiedFiles:w,skippedFiles:l,copiedDirs:a,executionTime:m}}async function $(t,u){try{await i.promises.writeFile(t,u,"utf-8")}catch(e){const r=e;throw r.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${t}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${t}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function j(t,u={}){const{includeExtensions:e=[],excludePatterns:r=[],filter:c}=u,F=[];async function E(p){const w=await i.promises.readdir(p,{withFileTypes:!0});for(const l of w){const a=s.join(p,l.name);if(l.isDirectory()){await E(a);continue}if(!l.isFile()||r.some(f=>f.startsWith("*")?a.endsWith(f.slice(1)):a.includes(f)))continue;const m=s.extname(l.name).toLowerCase();if(e.length>0&&!e.includes(m))continue;const o=await i.promises.stat(a);c&&!c(a,m,o.size)||F.push({filePath:a,size:o.size,extension:m})}}return await E(t),F}async function z(t,u,e=2){await $(t,JSON.stringify(u,null,e))}function P(t,u){const e=s.dirname(t);i.existsSync(e)||i.mkdirSync(e,{recursive:!0}),i.writeFileSync(t,u,"utf-8")}function O(t,u){if(!i.existsSync(t))return!0;try{return i.readFileSync(t,"utf-8")!==u}catch{return!0}}function N(t,u){return u?s.isAbsolute(u)?u:s.join(t,u):null}export{k as checkSourceExists,T as copySourceToTarget,N as resolveReportPath,j as scanDirectory,O as shouldUpdateFileContent,$ as writeFileContent,P as writeFileSyncSafely,z as writeJsonReport};