@meng-xi/vite-plugin 0.1.3 → 0.1.4

package/dist/plugins/generateVersion/index.d.ts

@@ -46,6 +46,18 @@ interface VersionInfo {
  * 自动生成版本号插件的配置选项接口
  *
  * @interface GenerateVersionOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * generateVersion({
+ *   format: 'semver',
+ *   semverBase: '2.0.0',
+ *   outputType: 'both',
+ *   prefix: 'v',
+ *   extra: { environment: 'production' }
+ * })
+ * ```
  */
 interface GenerateVersionOptions extends BasePluginOptions {
     /**

package/dist/plugins/htmlInject/index.cjs

@@ -1,7 +1 @@
-"use strict";const factory_index=require("../../factory/index.cjs"),common_script_index=require("../../common/script/index.cjs"),a=require("node:path");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs");function _interopDefaultCompat(e){return e&&typeof e=="object"&&"default"in e?e.default:e}const a__default=_interopDefaultCompat(a),g$1=["script","iframe","object","embed","applet","form","input","textarea","select","button"],b=["onclick","ondblclick","onmouseover","onmouseout","onmousemove","onmousedown","onmouseup","onkeydown","onkeyup","onkeypress","onload","onerror","onfocus","onblur","onsubmit","onchange","oninput","oncontextmenu","ondrag","ondrop","onanimationend","ontransitionend"];function validateRules(e){if(!e.rules||!Array.isArray(e.rules))throw new Error("rules \u5FC5\u987B\u662F\u975E\u7A7A\u6570\u7EC4");if(e.rules.length===0)throw new Error("rules \u4E0D\u80FD\u4E3A\u7A7A\u6570\u7EC4");for(let t=0;t<e.rules.length;t++)m(e.rules[t],t)}function m(e,t){if(!e.content||typeof e.content!="string")throw new Error(`rules[${t}].content \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);if(!e.position||typeof e.position!="string")throw new Error(`rules[${t}].position \u5FC5\u987B\u662F\u6709\u6548\u7684\u6CE8\u5165\u4F4D\u7F6E`);const n=["head-start","head-end","body-start","body-end","before-selector","after-selector","replace-selector"];if(!n.includes(e.position))throw new Error(`rules[${t}].position \u5FC5\u987B\u662F ${n.join(", ")} \u4E4B\u4E00`);if(e.position.includes("selector")&&!e.selector)throw new Error(`rules[${t}].position \u4E3A "${e.position}" \u65F6\uFF0Cselector \u4E3A\u5FC5\u586B\u9879`);if(e.priority!==void 0&&(typeof e.priority!="number"||e.priority<0))throw new Error(`rules[${t}].priority \u5FC5\u987B\u662F\u975E\u8D1F\u6570`);e.condition&&y(e.condition,t)}function y(e,t){if(!e)return;const n=["env","file-contains","custom"];if(!n.includes(e.type))throw new Error(`rules[${t}].condition.type \u5FC5\u987B\u662F ${n.join(", ")} \u4E4B\u4E00`);if(e.type==="custom"&&typeof e.value!="function")throw new Error(`rules[${t}].condition.type \u4E3A "custom" \u65F6\uFF0Cvalue \u5FC5\u987B\u662F\u51FD\u6570`);if(e.type!=="custom"&&typeof e.value!="string")throw new Error(`rules[${t}].condition.type \u4E3A "${e.type}" \u65F6\uFF0Cvalue \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`)}function validateSecurityConfig(e){if(e){if(e.blockedTags&&!Array.isArray(e.blockedTags))throw new Error("security.blockedTags \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4");if(e.allowedTags&&!Array.isArray(e.allowedTags))throw new Error("security.allowedTags \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4");if(e.blockedAttributes&&!Array.isArray(e.blockedAttributes))throw new Error("security.blockedAttributes \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4")}}function validateAll(e){validateRules(e),validateSecurityConfig(e.security)}function sanitizeContent(e,t,n,o){const s=n?.blockDangerousTags!==!1,r=n?.blockDangerousAttributes!==!1,i=n?.blockedTags||g$1,f=n?.allowedTags,l=n?.blockedAttributes||b;let c=e;if(s){const E=f?i.filter(d=>!f.includes(d)):i;if(common_script_index.containsScriptTag(e))if(t.allowScriptInjection)o?.warn(`[\u5B89\u5168\u8B66\u544A] \u89C4\u5219 "${t.id||"unnamed"}" \u5DF2\u542F\u7528\u811A\u672C\u6CE8\u5165(allowScriptInjection=true)\uFF0C\u8BF7\u786E\u4FDD\u6CE8\u5165\u5185\u5BB9\u6765\u6E90\u53EF\u4FE1\u3002\u6CE8\u5165\u811A\u672C\u53EF\u80FD\u5E26\u6765 XSS \u653B\u51FB\u98CE\u9669\u3002`);else throw new Error(`\u89C4\u5219 "${t.id||"unnamed"}" \u7684\u5185\u5BB9\u5305\u542B <script> \u6807\u7B7E\uFF0C\u9ED8\u8BA4\u88AB\u963B\u6B62\u3002\u5982\u9700\u6CE8\u5165\u811A\u672C\uFF0C\u8BF7\u8BBE\u7F6E allowScriptInjection: true`);for(const d of E){if(d==="script")continue;const F=new RegExp(`<${d}\\b[^>]*>[\\s\\S]*?<\\/${d}>`,"gi"),h=new RegExp(`<${d}\\b[^>]*/?>`,"gi");if(F.test(c)||h.test(c))if(t.allowScriptInjection){o?.warn(`[\u5B89\u5168\u8B66\u544A] \u89C4\u5219 "${t.id||"unnamed"}" \u5305\u542B\u88AB\u963B\u6B62\u7684\u6807\u7B7E <${d}>\uFF0C\u5DF2\u901A\u8FC7 allowScriptInjection \u8DF3\u8FC7\u5B89\u5168\u68C0\u67E5\uFF0C\u8BF7\u786E\u4FDD\u5185\u5BB9\u53EF\u4FE1\u3002`);continue}else throw new Error(`\u89C4\u5219 "${t.id||"unnamed"}" \u7684\u5185\u5BB9\u5305\u542B\u88AB\u963B\u6B62\u7684\u6807\u7B7E <${d}>\u3002\u5982\u9700\u6CE8\u5165\u6B64\u6807\u7B7E\uFF0C\u8BF7\u8BBE\u7F6E allowScriptInjection: true \u6216\u5728 security.allowedTags \u4E2D\u6DFB\u52A0 "${d}"`);c=c.replace(F,""),c=c.replace(h,"")}}if(r)for(const E of l){const d=new RegExp(`\\s${E}\\s*=\\s*["'][^"']*["']`,"gi");if(d.test(c))if(t.allowScriptInjection){o?.warn(`[\u5B89\u5168\u8B66\u544A] \u89C4\u5219 "${t.id||"unnamed"}" \u5305\u542B\u5371\u9669\u5C5E\u6027 ${E}\uFF0C\u5DF2\u901A\u8FC7 allowScriptInjection \u8DF3\u8FC7\u5B89\u5168\u68C0\u67E5\uFF0C\u8BF7\u786E\u4FDD\u5185\u5BB9\u53EF\u4FE1\u3002`);continue}else throw new Error(`\u89C4\u5219 "${t.id||"unnamed"}" \u7684\u5185\u5BB9\u5305\u542B\u5371\u9669\u5C5E\u6027 ${E}\u3002\u5982\u9700\u6CE8\u5165\u6B64\u5C5E\u6027\uFF0C\u8BF7\u8BBE\u7F6E allowScriptInjection: true`);c=c.replace(d,"")}return c}function g(e,t,n){if(n==="regex"){try{const s=new RegExp(t),r=e.match(s);if(r&&r.index!==void 0)return{index:r.index,length:r[0].length}}catch{return null}return null}const o=e.indexOf(t);return o===-1?null:{index:o,length:t.length}}function applyTemplateVars(e,t,n){let o=e;const s={...n,...t};for(const[r,i]of Object.entries(s)){const f=r.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),l=i.replace(/\$/g,"$$$$");o=o.replace(new RegExp(`\\{\\{${f}\\}\\}`,"g"),l)}return o}function evaluateCondition(e,t){let n=!1;switch(e.type){case"env":{const o=e.value,s=process.env[o];n=!!s&&s!=="false"&&s!=="0";break}case"file-contains":{const o=e.value;n=t.includes(o);break}case"custom":{const o=e.value;try{n=!!o()}catch{n=!1}break}}return e.negate?!n:n}function sortRulesByPriority(e){return[...e].sort((t,n)=>(t.priority??100)-(n.priority??100))}function injectAtPosition(e,t,n,o,s){switch(n){case"head-start":{const r=e.match(/<head\b[^>]*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 <head> \u6807\u7B7E"};const i=(r.index??0)+r[0].length;return{html:e.slice(0,i)+`
-`+t+e.slice(i),injected:!0}}case"head-end":{const r=e.match(/<\/head\s*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 </head> \u6807\u7B7E"};const i=r.index;return{html:e.slice(0,i)+t+`
-`+e.slice(i),injected:!0}}case"body-start":{const r=e.match(/<body\b[^>]*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 <body> \u6807\u7B7E"};const i=(r.index??0)+r[0].length;return{html:e.slice(0,i)+`
-`+t+e.slice(i),injected:!0}}case"body-end":{const r=e.match(/<\/body\s*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 </body> \u6807\u7B7E"};const i=r.index;return{html:e.slice(0,i)+t+`
-`+e.slice(i),injected:!0}}case"before-selector":{if(!o)return{html:e,injected:!1,reason:"before-selector \u9700\u8981 selector \u53C2\u6570"};const r=g(e,o,s);return r?{html:e.slice(0,r.index)+t+`
-`+e.slice(r.index),injected:!0}:{html:e,injected:!1,reason:`\u672A\u627E\u5230\u9009\u62E9\u5668 "${o}"`}}case"after-selector":{if(!o)return{html:e,injected:!1,reason:"after-selector \u9700\u8981 selector \u53C2\u6570"};const r=g(e,o,s);if(!r)return{html:e,injected:!1,reason:`\u672A\u627E\u5230\u9009\u62E9\u5668 "${o}"`};const i=r.index+r.length;return{html:e.slice(0,i)+`
-`+t+e.slice(i),injected:!0}}case"replace-selector":{if(!o)return{html:e,injected:!1,reason:"replace-selector \u9700\u8981 selector \u53C2\u6570"};const r=g(e,o,s);if(!r)return{html:e,injected:!1,reason:`\u672A\u627E\u5230\u9009\u62E9\u5668 "${o}"`};const i=r.index+r.length;return{html:e.slice(0,r.index)+t+e.slice(i),injected:!0}}default:return{html:e,injected:!1,reason:`\u4E0D\u652F\u6301\u7684\u6CE8\u5165\u4F4D\u7F6E: ${n}`}}}function processRules(e,t,n,o,s){let r=e;const i=[],f=sortRulesByPriority(t);for(const l of f){const c={ruleId:l.id||"unnamed",position:l.position,selector:l.selector,injected:!1,timestamp:Date.now()};if(l.condition&&!evaluateCondition(l.condition,r)){c.injected=!1,c.reason="\u6761\u4EF6\u4E0D\u6EE1\u8DB3\uFF0C\u8DF3\u8FC7\u6CE8\u5165",i.push(c);continue}let E=applyTemplateVars(l.content,l.templateVars,n);try{E=sanitizeContent(E,l,o,s)}catch(F){c.injected=!1,c.reason=F.message,i.push(c),s?.warn(`\u89C4\u5219 "${l.id||"unnamed"}" \u5B89\u5168\u68C0\u67E5\u5931\u8D25: ${F.message}`);continue}const d=injectAtPosition(r,E,l.position,l.selector,l.selectorMatch);r=d.html,c.injected=d.injected,c.reason=d.reason,i.push(c)}return{html:r,logs:i}}class u extends factory_index.BasePlugin{injectionLogs=[];getDefaultOptions(){return{targetFile:"index.html",logInjection:!0,security:{blockDangerousTags:!0,blockDangerousAttributes:!0}}}validateOptions(){this.validator.field("targetFile").string().field("rules").required().field("logInjection").boolean().validate(),validateAll(this.options)}getPluginName(){return"html-inject"}isTargetFile(t,n){if(n==="index.html")return t.endsWith("index.html")||t.endsWith("index.htm");const o=n.replace(/\\/g,"/"),s=t.replace(/\\/g,"/");return s.endsWith(o)?!0:a__default.basename(s)===a__default.basename(o)}addPluginHooks(t){t.transformIndexHtml={order:"post",handler:(n,o)=>{const s=o.filename||"",r=this.options.targetFile||"index.html";if(!this.isTargetFile(s,r))return n;const i={warn:l=>this.logger.warn(l)},f=processRules(n,this.options.rules,this.options.templateVars,this.options.security,i);return this.injectionLogs=f.logs,this.options.logInjection&&this.logInjectionResults(f.logs),f.html}},t.buildEnd=()=>{this.options.logInjection&&this.injectionLogs.length>0&&this.logger.info(`\u6CE8\u5165\u5B8C\u6210\uFF0C\u5171\u5904\u7406 ${this.injectionLogs.length} \u6761\u89C4\u5219`)}}logInjectionResults(t){for(const n of t)n.injected?this.logger.success(`\u89C4\u5219 "${n.ruleId}" \u6CE8\u5165\u6210\u529F (\u4F4D\u7F6E: ${n.position}${n.selector?`, \u9009\u62E9\u5668: ${n.selector}`:""})`):this.logger.warn(`\u89C4\u5219 "${n.ruleId}" \u6CE8\u5165\u5931\u8D25: ${n.reason||"\u672A\u77E5\u539F\u56E0"}`)}getInjectionLogs(){return[...this.injectionLogs]}}const htmlInject=factory_index.createPluginFactory(u);exports.htmlInject=htmlInject;
+"use strict";const factory_index=require("../../factory/index.cjs"),security=require("../../shared/vite-plugin.BrI73DHA.cjs"),a=require("node:path");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs"),require("../../common/script/index.cjs");function _interopDefaultCompat(e){return e&&typeof e=="object"&&"default"in e?e.default:e}const a__default=_interopDefaultCompat(a);function validateRules(e){if(!e.rules||!Array.isArray(e.rules))throw new Error("rules \u5FC5\u987B\u662F\u975E\u7A7A\u6570\u7EC4");if(e.rules.length===0)throw new Error("rules \u4E0D\u80FD\u4E3A\u7A7A\u6570\u7EC4");for(let t=0;t<e.rules.length;t++)s(e.rules[t],t)}function s(e,t){if(!e.content||typeof e.content!="string")throw new Error(`rules[${t}].content \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);if(!e.position||typeof e.position!="string")throw new Error(`rules[${t}].position \u5FC5\u987B\u662F\u6709\u6548\u7684\u6CE8\u5165\u4F4D\u7F6E`);const o=["head-start","head-end","body-start","body-end","before-selector","after-selector","replace-selector"];if(!o.includes(e.position))throw new Error(`rules[${t}].position \u5FC5\u987B\u662F ${o.join(", ")} \u4E4B\u4E00`);if(e.position.includes("selector")&&!e.selector)throw new Error(`rules[${t}].position \u4E3A "${e.position}" \u65F6\uFF0Cselector \u4E3A\u5FC5\u586B\u9879`);if(e.priority!==void 0&&(typeof e.priority!="number"||e.priority<0))throw new Error(`rules[${t}].priority \u5FC5\u987B\u662F\u975E\u8D1F\u6570`);e.condition&&c(e.condition,t)}function c(e,t){if(!e)return;const o=["env","file-contains","custom"];if(!o.includes(e.type))throw new Error(`rules[${t}].condition.type \u5FC5\u987B\u662F ${o.join(", ")} \u4E4B\u4E00`);if(e.type==="custom"&&typeof e.value!="function")throw new Error(`rules[${t}].condition.type \u4E3A "custom" \u65F6\uFF0Cvalue \u5FC5\u987B\u662F\u51FD\u6570`);if(e.type!=="custom"&&typeof e.value!="string")throw new Error(`rules[${t}].condition.type \u4E3A "${e.type}" \u65F6\uFF0Cvalue \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`)}function validateAll(e){validateRules(e),security.validateSecurityConfig(e.security)}function processRules(e,t,o,l,r){let d=e;const p=[],h=security.sortRulesByPriority(t);for(const n of h){const i={ruleId:n.id||"unnamed",position:n.position,selector:n.selector,injected:!1,timestamp:Date.now()};if(n.condition&&!security.evaluateCondition(n.condition,d)){i.injected=!1,i.reason="\u6761\u4EF6\u4E0D\u6EE1\u8DB3\uFF0C\u8DF3\u8FC7\u6CE8\u5165",p.push(i);continue}let g=security.applyTemplateVars(n.content,n.templateVars,o);try{g=security.sanitizeContent(g,n,l,r)}catch(F){i.injected=!1,i.reason=F.message,p.push(i),r?.warn(`\u89C4\u5219 "${n.id||"unnamed"}" \u5B89\u5168\u68C0\u67E5\u5931\u8D25: ${F.message}`);continue}const f=security.injectAtPosition(d,g,n.position,n.selector,n.selectorMatch);d=f.html,i.injected=f.injected,i.reason=f.reason,p.push(i)}return{html:d,logs:p}}class u extends factory_index.BasePlugin{injectionLogs=[];getDefaultOptions(){return{targetFile:"index.html",logInjection:!0,security:{blockDangerousTags:!0,blockDangerousAttributes:!0}}}validateOptions(){this.validator.field("targetFile").string().field("rules").required().field("logInjection").boolean().validate(),validateAll(this.options)}getPluginName(){return"html-inject"}isTargetFile(t,o){if(o==="index.html")return t.endsWith("index.html")||t.endsWith("index.htm");const l=o.replace(/\\/g,"/"),r=t.replace(/\\/g,"/");return r.endsWith(l)?!0:a__default.basename(r)===a__default.basename(l)}addPluginHooks(t){t.transformIndexHtml={order:"post",handler:(o,l)=>{const r=l.filename||"",d=this.options.targetFile||"index.html";if(!this.isTargetFile(r,d))return o;const p={warn:n=>this.logger.warn(n)},h=processRules(o,this.options.rules,this.options.templateVars,this.options.security,p);return this.injectionLogs=h.logs,this.options.logInjection&&this.logInjectionResults(h.logs),h.html}},t.buildEnd=()=>{this.options.logInjection&&this.injectionLogs.length>0&&this.logger.info(`\u6CE8\u5165\u5B8C\u6210\uFF0C\u5171\u5904\u7406 ${this.injectionLogs.length} \u6761\u89C4\u5219`)}}logInjectionResults(t){for(const o of t)o.injected?this.logger.success(`\u89C4\u5219 "${o.ruleId}" \u6CE8\u5165\u6210\u529F (\u4F4D\u7F6E: ${o.position}${o.selector?`, \u9009\u62E9\u5668: ${o.selector}`:""})`):this.logger.warn(`\u89C4\u5219 "${o.ruleId}" \u6CE8\u5165\u5931\u8D25: ${o.reason||"\u672A\u77E5\u539F\u56E0"}`)}getInjectionLogs(){return[...this.injectionLogs]}}const htmlInject=factory_index.createPluginFactory(u);exports.htmlInject=htmlInject;

package/dist/plugins/htmlInject/index.d.cts

@@ -1,239 +1,94 @@
 import { BasePluginOptions, PluginFactory } from '../../factory/index.cjs';
+import { a as InjectPosition, b as SelectorMatch, I as InjectCondition, S as SecurityConfig } from '../../shared/vite-plugin.FfJ-Wwfu.cjs';
 import 'vite';
 import '../../shared/vite-plugin.CLr0ttuO.cjs';
 import '../../shared/vite-plugin.DRRlWY8P.cjs';
 
 /**
- * 选择器匹配模式
- *
- * @description
- * - 'string': 使用字符串精确匹配（默认）
- * - 'regex': 使用正则表达式匹配，支持更灵活的模式
- */
-type SelectorMatch = 'string' | 'regex';
-/**
- * HTML 内容注入位置
- *
- * @description
- * - 'head-start': 注入到 `<head>` 标签开始之后
- * - 'head-end': 注入到 `</head>` 标签之前
- * - 'body-start': 注入到 `<body>` 标签开始之后
- * - 'body-end': 注入到 `</body>` 标签之前
- * - 'before-selector': 注入到指定选择器之前
- * - 'after-selector': 注入到指定选择器之后
- * - 'replace-selector': 替换指定选择器匹配的内容
- */
-type InjectPosition = 'head-start' | 'head-end' | 'body-start' | 'body-end' | 'before-selector' | 'after-selector' | 'replace-selector';
-/**
- * 条件类型
- *
- * @description
- * - 'env': 基于环境变量判断
- * - 'file-contains': 基于 HTML 文件内容判断
- * - 'custom': 基于自定义函数判断
- */
-type ConditionType = 'env' | 'file-contains' | 'custom';
-/**
- * 注入条件接口
- *
- * @interface InjectCondition
- * @description 定义内容注入的触发条件，支持环境变量检测、文件内容检测和自定义函数
- */
-interface InjectCondition {
-    /**
-     * 条件类型
-     */
-    type: ConditionType;
-    /**
-     * 条件值
-     *
-     * @description
-     * - 当 type 为 'env' 时，为环境变量名（字符串）
-     * - 当 type 为 'file-contains' 时，为要搜索的字符串（字符串）
-     * - 当 type 为 'custom' 时，为返回布尔值的判断函数
-     */
-    value: string | ((...args: any[]) => boolean);
-    /**
-     * 是否对条件结果取反
-     *
-     * @default false
-     */
-    negate?: boolean;
-}
-/**
- * 注入规则接口
+ * HTML 注入规则接口
  *
  * @interface InjectRule
- * @description 定义单条 HTML 内容注入规则，包括注入内容、位置、条件、优先级等
+ * @description 定义单条 HTML 内容注入规则，包含注入内容、位置、条件和安全配置。
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'meta-viewport',
+ *   content: '<meta name="viewport" content="width=device-width">',
+ *   position: 'head-end',
+ *   priority: 10
+ * }
+ * ```
  */
 interface InjectRule {
-    /**
-     * 规则唯一标识符，用于日志记录和调试
-     */
+    /** 规则唯一标识，用于日志输出和调试追踪 */
     id?: string;
-    /**
-     * 要注入的 HTML 内容
-     *
-     * @example '<meta name="description" content="My App">'
-     */
+    /** 要注入的 HTML 内容字符串，支持模板变量占位符 `{{varName}}` */
     content: string;
-    /**
-     * 注入位置
-     */
+    /** 注入位置，如 'head-start'、'head-end'、'body-start'、'body-end' 等 */
     position: InjectPosition;
-    /**
-     * 选择器字符串，当 position 为 selector 相关位置时必填
-     *
-     * @description 当 selectorMatch 为 'string' 时，使用字符串精确匹配；
-     * 当 selectorMatch 为 'regex' 时，使用正则表达式匹配
-     *
-     * @example '<div id="app">'
-     */
+    /** CSS 选择器，仅在 position 为 'before-selector' 或 'after-selector' 时需要 */
     selector?: string;
-    /**
-     * 选择器匹配模式
-     *
-     * @default 'string'
-     */
+    /** 选择器匹配模式，仅在指定 selector 时有效 */
     selectorMatch?: SelectorMatch;
-    /**
-     * 规则优先级，数值越小优先级越高，越先执行
-     *
-     * @default 100
-     */
+    /** 规则优先级，数值越大越先执行 */
     priority?: number;
-    /**
-     * 注入条件，满足条件时才执行注入
-     */
+    /** 条件注入配置，满足条件时才执行注入 */
     condition?: InjectCondition;
-    /**
-     * 规则级模板变量，会覆盖全局模板变量
-     *
-     * @description 使用 `{{变量名}}` 语法在 content 中引用变量
-     *
-     * @example { greeting: 'Hello', name: 'World' }
-     */
+    /** 规则级别的模板变量，会与全局 templateVars 合并 */
     templateVars?: Record<string, string>;
-    /**
-     * 是否允许注入脚本等危险内容
-     *
-     * @default false
-     * @remarks 启用此选项将跳过安全检查，请确保注入内容来源可信
-     */
+    /** 是否允许注入 `<script>` 标签，默认为 false 以防止 XSS 攻击 */
     allowScriptInjection?: boolean;
 }
-/**
- * 安全配置接口
- *
- * @interface SecurityConfig
- * @description 控制 HTML 注入内容的安全过滤行为，防止 XSS 攻击
- */
-interface SecurityConfig {
-    /**
-     * 是否阻止危险标签（script、iframe、object 等）
-     *
-     * @default true
-     */
-    blockDangerousTags?: boolean;
-    /**
-     * 是否阻止危险属性（onclick、onload 等事件处理器）
-     *
-     * @default true
-     */
-    blockDangerousAttributes?: boolean;
-    /**
-     * 允许通过的标签白名单，白名单中的标签不会被阻止
-     *
-     * @example ['iframe', 'object']
-     */
-    allowedTags?: string[];
-    /**
-     * 自定义阻止标签列表，覆盖默认阻止列表
-     *
-     * @example ['div', 'span']
-     */
-    blockedTags?: string[];
-    /**
-     * 自定义阻止属性列表，覆盖默认阻止列表
-     *
-     * @example ['data-custom', 'data-track']
-     */
-    blockedAttributes?: string[];
-}
 /**
  * 注入日志条目接口
  *
  * @interface InjectionLogEntry
- * @description 记录单条注入规则的执行结果，用于调试和问题排查
+ * @description 记录单条注入规则的执行结果，用于调试和统计。
  */
 interface InjectionLogEntry {
-    /**
-     * 规则标识符
-     */
+    /** 规则标识 */
     ruleId: string;
-    /**
-     * 注入位置
-     */
+    /** 注入位置 */
     position: InjectPosition;
-    /**
-     * 使用的选择器
-     */
+    /** 使用的 CSS 选择器（如果有） */
     selector?: string;
-    /**
-     * 是否注入成功
-     */
+    /** 是否注入成功 */
     injected: boolean;
-    /**
-     * 注入失败原因
-     */
+    /** 注入失败原因（如果失败） */
     reason?: string;
-    /**
-     * 日志时间戳
-     */
+    /** 日志记录时间戳（毫秒） */
     timestamp: number;
 }
 /**
- * HTML 注入插件的配置选项接口
+ * HTML 内容注入插件的配置选项接口
  *
  * @interface HtmlInjectOptions
  * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * htmlInject({
+ *   targetFile: 'index.html',
+ *   rules: [
+ *     { content: '<meta name="description" content="My App">', position: 'head-end' }
+ *   ],
+ *   security: { blockDangerousTags: true },
+ *   templateVars: { appName: 'My App' },
+ *   logInjection: true
+ * })
+ * ```
  */
 interface HtmlInjectOptions extends BasePluginOptions {
-    /**
-     * 目标 HTML 文件路径或文件名
-     *
-     * @default 'index.html'
-     * @description 支持相对路径和文件名匹配，默认匹配所有 index.html 文件
-     *
-     * @example 'index.html'
-     * @example 'src/views/home.html'
-     */
+    /** 目标 HTML 文件路径或文件名，默认为 'index.html' */
     targetFile?: string;
-    /**
-     * 注入规则数组
-     *
-     * @description 定义要注入的 HTML 内容及其注入位置和条件，规则按 priority 升序执行
-     */
+    /** 注入规则数组，至少包含一条规则 */
     rules: InjectRule[];
-    /**
-     * 安全配置
-     *
-     * @description 控制注入内容的安全过滤行为，防止 XSS 攻击
-     */
+    /** 安全过滤配置，控制危险标签和属性的过滤行为 */
     security?: SecurityConfig;
-    /**
-     * 全局模板变量，可被规则级 templateVars 覆盖
-     *
-     * @description 使用 `{{变量名}}` 语法在 content 中引用变量
-     *
-     * @example { appName: 'My App', version: '1.0.0' }
-     */
+    /** 全局模板变量映射，用于替换内容中的 `{{varName}}` 占位符 */
     templateVars?: Record<string, string>;
-    /**
-     * 是否在控制台输出注入日志
-     *
-     * @default true
-     */
+    /** 是否在控制台输出注入结果日志 */
     logInjection?: boolean;
 }
 
@@ -275,4 +130,4 @@ interface HtmlInjectOptions extends BasePluginOptions {
 declare const htmlInject: PluginFactory<HtmlInjectOptions, HtmlInjectOptions>;
 
 export { htmlInject };
-export type { ConditionType, HtmlInjectOptions, InjectCondition, InjectPosition, InjectRule, InjectionLogEntry, SecurityConfig, SelectorMatch };
+export type { HtmlInjectOptions, InjectRule, InjectionLogEntry };

package/dist/plugins/htmlInject/index.d.mts

@@ -1,239 +1,94 @@
 import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
+import { a as InjectPosition, b as SelectorMatch, I as InjectCondition, S as SecurityConfig } from '../../shared/vite-plugin.FfJ-Wwfu.mjs';
 import 'vite';
 import '../../shared/vite-plugin.CLr0ttuO.mjs';
 import '../../shared/vite-plugin.DRRlWY8P.mjs';
 
 /**
- * 选择器匹配模式
- *
- * @description
- * - 'string': 使用字符串精确匹配（默认）
- * - 'regex': 使用正则表达式匹配，支持更灵活的模式
- */
-type SelectorMatch = 'string' | 'regex';
-/**
- * HTML 内容注入位置
- *
- * @description
- * - 'head-start': 注入到 `<head>` 标签开始之后
- * - 'head-end': 注入到 `</head>` 标签之前
- * - 'body-start': 注入到 `<body>` 标签开始之后
- * - 'body-end': 注入到 `</body>` 标签之前
- * - 'before-selector': 注入到指定选择器之前
- * - 'after-selector': 注入到指定选择器之后
- * - 'replace-selector': 替换指定选择器匹配的内容
- */
-type InjectPosition = 'head-start' | 'head-end' | 'body-start' | 'body-end' | 'before-selector' | 'after-selector' | 'replace-selector';
-/**
- * 条件类型
- *
- * @description
- * - 'env': 基于环境变量判断
- * - 'file-contains': 基于 HTML 文件内容判断
- * - 'custom': 基于自定义函数判断
- */
-type ConditionType = 'env' | 'file-contains' | 'custom';
-/**
- * 注入条件接口
- *
- * @interface InjectCondition
- * @description 定义内容注入的触发条件，支持环境变量检测、文件内容检测和自定义函数
- */
-interface InjectCondition {
-    /**
-     * 条件类型
-     */
-    type: ConditionType;
-    /**
-     * 条件值
-     *
-     * @description
-     * - 当 type 为 'env' 时，为环境变量名（字符串）
-     * - 当 type 为 'file-contains' 时，为要搜索的字符串（字符串）
-     * - 当 type 为 'custom' 时，为返回布尔值的判断函数
-     */
-    value: string | ((...args: any[]) => boolean);
-    /**
-     * 是否对条件结果取反
-     *
-     * @default false
-     */
-    negate?: boolean;
-}
-/**
- * 注入规则接口
+ * HTML 注入规则接口
  *
  * @interface InjectRule
- * @description 定义单条 HTML 内容注入规则，包括注入内容、位置、条件、优先级等
+ * @description 定义单条 HTML 内容注入规则，包含注入内容、位置、条件和安全配置。
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'meta-viewport',
+ *   content: '<meta name="viewport" content="width=device-width">',
+ *   position: 'head-end',
+ *   priority: 10
+ * }
+ * ```
  */
 interface InjectRule {
-    /**
-     * 规则唯一标识符，用于日志记录和调试
-     */
+    /** 规则唯一标识，用于日志输出和调试追踪 */
     id?: string;
-    /**
-     * 要注入的 HTML 内容
-     *
-     * @example '<meta name="description" content="My App">'
-     */
+    /** 要注入的 HTML 内容字符串，支持模板变量占位符 `{{varName}}` */
     content: string;
-    /**
-     * 注入位置
-     */
+    /** 注入位置，如 'head-start'、'head-end'、'body-start'、'body-end' 等 */
     position: InjectPosition;
-    /**
-     * 选择器字符串，当 position 为 selector 相关位置时必填
-     *
-     * @description 当 selectorMatch 为 'string' 时，使用字符串精确匹配；
-     * 当 selectorMatch 为 'regex' 时，使用正则表达式匹配
-     *
-     * @example '<div id="app">'
-     */
+    /** CSS 选择器，仅在 position 为 'before-selector' 或 'after-selector' 时需要 */
     selector?: string;
-    /**
-     * 选择器匹配模式
-     *
-     * @default 'string'
-     */
+    /** 选择器匹配模式，仅在指定 selector 时有效 */
     selectorMatch?: SelectorMatch;
-    /**
-     * 规则优先级，数值越小优先级越高，越先执行
-     *
-     * @default 100
-     */
+    /** 规则优先级，数值越大越先执行 */
     priority?: number;
-    /**
-     * 注入条件，满足条件时才执行注入
-     */
+    /** 条件注入配置，满足条件时才执行注入 */
     condition?: InjectCondition;
-    /**
-     * 规则级模板变量，会覆盖全局模板变量
-     *
-     * @description 使用 `{{变量名}}` 语法在 content 中引用变量
-     *
-     * @example { greeting: 'Hello', name: 'World' }
-     */
+    /** 规则级别的模板变量，会与全局 templateVars 合并 */
     templateVars?: Record<string, string>;
-    /**
-     * 是否允许注入脚本等危险内容
-     *
-     * @default false
-     * @remarks 启用此选项将跳过安全检查，请确保注入内容来源可信
-     */
+    /** 是否允许注入 `<script>` 标签，默认为 false 以防止 XSS 攻击 */
     allowScriptInjection?: boolean;
 }
-/**
- * 安全配置接口
- *
- * @interface SecurityConfig
- * @description 控制 HTML 注入内容的安全过滤行为，防止 XSS 攻击
- */
-interface SecurityConfig {
-    /**
-     * 是否阻止危险标签（script、iframe、object 等）
-     *
-     * @default true
-     */
-    blockDangerousTags?: boolean;
-    /**
-     * 是否阻止危险属性（onclick、onload 等事件处理器）
-     *
-     * @default true
-     */
-    blockDangerousAttributes?: boolean;
-    /**
-     * 允许通过的标签白名单，白名单中的标签不会被阻止
-     *
-     * @example ['iframe', 'object']
-     */
-    allowedTags?: string[];
-    /**
-     * 自定义阻止标签列表，覆盖默认阻止列表
-     *
-     * @example ['div', 'span']
-     */
-    blockedTags?: string[];
-    /**
-     * 自定义阻止属性列表，覆盖默认阻止列表
-     *
-     * @example ['data-custom', 'data-track']
-     */
-    blockedAttributes?: string[];
-}
 /**
  * 注入日志条目接口
  *
  * @interface InjectionLogEntry
- * @description 记录单条注入规则的执行结果，用于调试和问题排查
+ * @description 记录单条注入规则的执行结果，用于调试和统计。
  */
 interface InjectionLogEntry {
-    /**
-     * 规则标识符
-     */
+    /** 规则标识 */
     ruleId: string;
-    /**
-     * 注入位置
-     */
+    /** 注入位置 */
     position: InjectPosition;
-    /**
-     * 使用的选择器
-     */
+    /** 使用的 CSS 选择器（如果有） */
     selector?: string;
-    /**
-     * 是否注入成功
-     */
+    /** 是否注入成功 */
     injected: boolean;
-    /**
-     * 注入失败原因
-     */
+    /** 注入失败原因（如果失败） */
     reason?: string;
-    /**
-     * 日志时间戳
-     */
+    /** 日志记录时间戳（毫秒） */
     timestamp: number;
 }
 /**
- * HTML 注入插件的配置选项接口
+ * HTML 内容注入插件的配置选项接口
  *
  * @interface HtmlInjectOptions
  * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * htmlInject({
+ *   targetFile: 'index.html',
+ *   rules: [
+ *     { content: '<meta name="description" content="My App">', position: 'head-end' }
+ *   ],
+ *   security: { blockDangerousTags: true },
+ *   templateVars: { appName: 'My App' },
+ *   logInjection: true
+ * })
+ * ```
  */
 interface HtmlInjectOptions extends BasePluginOptions {
-    /**
-     * 目标 HTML 文件路径或文件名
-     *
-     * @default 'index.html'
-     * @description 支持相对路径和文件名匹配，默认匹配所有 index.html 文件
-     *
-     * @example 'index.html'
-     * @example 'src/views/home.html'
-     */
+    /** 目标 HTML 文件路径或文件名，默认为 'index.html' */
     targetFile?: string;
-    /**
-     * 注入规则数组
-     *
-     * @description 定义要注入的 HTML 内容及其注入位置和条件，规则按 priority 升序执行
-     */
+    /** 注入规则数组，至少包含一条规则 */
     rules: InjectRule[];
-    /**
-     * 安全配置
-     *
-     * @description 控制注入内容的安全过滤行为，防止 XSS 攻击
-     */
+    /** 安全过滤配置，控制危险标签和属性的过滤行为 */
     security?: SecurityConfig;
-    /**
-     * 全局模板变量，可被规则级 templateVars 覆盖
-     *
-     * @description 使用 `{{变量名}}` 语法在 content 中引用变量
-     *
-     * @example { appName: 'My App', version: '1.0.0' }
-     */
+    /** 全局模板变量映射，用于替换内容中的 `{{varName}}` 占位符 */
     templateVars?: Record<string, string>;
-    /**
-     * 是否在控制台输出注入日志
-     *
-     * @default true
-     */
+    /** 是否在控制台输出注入结果日志 */
     logInjection?: boolean;
 }
 
@@ -275,4 +130,4 @@ interface HtmlInjectOptions extends BasePluginOptions {
 declare const htmlInject: PluginFactory<HtmlInjectOptions, HtmlInjectOptions>;
 
 export { htmlInject };
-export type { ConditionType, HtmlInjectOptions, InjectCondition, InjectPosition, InjectRule, InjectionLogEntry, SecurityConfig, SelectorMatch };
+export type { HtmlInjectOptions, InjectRule, InjectionLogEntry };