@playcraft/devkit 1.0.1-8.beta.1

package/core/utils/generateInMobiHtmlWebpackPluginConfig.js

@@ -0,0 +1,36 @@
+"use strict";const fs=require("fs");const path=require("path");/**
+ * InMobi 追踪宏定义
+ * 文档: https://support.inmobi.com/dsp/in/inmobi-dsp-india/creative-specifications-and-guidelines/
+ * 
+ * InMobi 要求:
+ * 1. 单个 index.html 文件（所有资源内联）或 ZIP 包
+ * 2. 必须包含 INMOBI_DSPMACROS 追踪变量
+ * 3. 引用外部 mraid.js（由 InMobi 平台提供）
+ * 4. 支持 MRAID 3.0 标准
+ */const InMobiPlaceholders=`<script>
+  var INMOBI_DSPMACROS = {
+    "Ad_Load_Start": ["$P_AD_LOAD_START"],
+    "Ad_Viewable": ["$P_AD_READY"],
+    "First_Engagement": ["$P_FIRST_ENGAGEMENT"],
+    "Gameplay_Complete": ["$P_GAMEPLAY_DONE"],
+    "DSP_Click": ["$HTML_ESC_CLICK_URL"],
+    "LandingPage_URL": [/android/i.test(navigator.userAgent) ? "{GOOGLE_PLAY_URL}" : "{APP_STORE_URL}"],
+    "Spent_5_Seconds": ["$P_TIMESPENT_5"],
+    "Spent_10_Seconds": ["$P_TIMESPENT_10"],
+    "Spent_15_Seconds": ["$P_TIMESPENT_15"],
+    "Spent_20_Seconds": ["$P_TIMESPENT_20"],
+    "Spent_25_Seconds": ["$P_TIMESPENT_25"],
+    "Spent_30_Seconds": ["$P_TIMESPENT_30"]
+  };
+</script>
+<script src="mraid.js"></script>`;/**
+ * 生成 InMobi 平台所需的 HTML 配置
+ * 
+ * 策略: 
+ * 1. 使用标准的 HtmlWebpackPlugin 配置（不是 templateContent）
+ * 2. JS 会通过 HtmlInlineScriptPlugin 自动内联到 HTML 中
+ * 3. 通过修改 template 文件注入 InMobi 追踪脚本
+ */exports.generateInMobiHtmlWebpackPluginConfig=function generateInMobiHtmlWebpackPluginConfig(originalHtmlContentPath,buildOptions){originalHtmlContentPath=originalHtmlContentPath||"src/index.html";const placeholder=InMobiPlaceholders.replaceAll("{GOOGLE_PLAY_URL}",buildOptions.googlePlayUrl).replaceAll("{APP_STORE_URL}",buildOptions.appStoreUrl);// 读取原始 HTML 模板
+let htmlContent="";try{htmlContent=fs.readFileSync(path.resolve(originalHtmlContentPath),"utf8")}catch(e){console.warn("[InMobi] Could not read HTML template:",e.message)}// 在 </head> 之前注入 InMobi 追踪脚本
+htmlContent=htmlContent.replace("</head>",`${placeholder}\n</head>`);return{filename:"index.html",inject:"head",// webpack 会自动注入 JS，然后 HtmlInlineScriptPlugin 内联
+minify:false,templateContent:htmlContent,meta:{charset:"UTF-8",viewport:"width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no"}}};

package/core/utils/injectSDKPlugins.js

@@ -0,0 +1,19 @@
+"use strict";/**
+ * 根据 AD_NETWORK 和 AD_PROTOCOL 注入对应的渠道 SDK 脚本插件
+ * 此函数被 webpack.dev.js 和 webpack.build.js 共用
+ */const{ExitAPIInjectorPlugin}=require("../plugins/ExitAPIInjectorPlugin.js");const{DAPIInjectorPlugin}=require("../plugins/DAPIInjectorPlugin.js");const{PangleInjectorPlugin}=require("../plugins/PangleInjectorPlugin.js");const{TikTokInjectorPlugin}=require("../plugins/TikTokInjectorPlugin.js");const{MintegralInjectorPlugin}=require("../plugins/MintegralInjectorPlugin.js");const{MRAIDInjectorPlugin}=require("../plugins/MRAIDInjectorPlugin.js");const{BigoAdsInjectorPlugin}=require("../plugins/BigoAdsInjectorPlugin.js");const{LiftoffInjectorPlugin}=require("../plugins/LiftoffInjectorPlugin.js");const{SnapchatInjectorPlugin}=require("../plugins/SnapchatInjectorPlugin.js");const{AdikteevInjectorPlugin}=require("../plugins/AdikteevInjectorPlugin.js");const{UnityInjectorPlugin}=require("../plugins/UnityInjectorPlugin.js");/**
+ * 注入渠道 SDK 插件到 webpack 配置中
+ * @param {import('webpack').Configuration} webpackConfig - webpack 配置对象
+ * @param {Object} options - 配置选项
+ * @param {AD_NETWORK} options.network - 广告网络
+ * @param {AD_PROTOCOL} options.protocol - 广告协议
+ * @param {string} [options.orientation] - 屏幕方向（google 渠道需要）
+ */function injectSDKPlugins(webpackConfig,options){const{network:adNetwork,protocol:adProtocol,orientation}=options;// 协议层注入
+if("dapi"===adProtocol){webpackConfig.plugins.push(new DAPIInjectorPlugin)}else if("mraid"===adProtocol){// 只有 ironsource 才注入 MRAIDInjectorPlugin
+// Unity 使用专门的 UnityInjectorPlugin（在渠道特定注入中处理）
+if(adNetwork==="ironsource"){webpackConfig.plugins.push(new MRAIDInjectorPlugin)}}// 渠道特定注入
+if(adNetwork==="google"){webpackConfig.plugins.push(new ExitAPIInjectorPlugin(orientation))}else if(adNetwork==="unity"){// Unity Ads 使用专门的 UnityInjectorPlugin
+webpackConfig.plugins.push(new UnityInjectorPlugin)}else if(adNetwork==="pangle"){webpackConfig.plugins.push(new PangleInjectorPlugin)}else if(adNetwork==="tiktok"){webpackConfig.plugins.push(new TikTokInjectorPlugin)}else if(adNetwork==="mintegral"){webpackConfig.plugins.push(new MintegralInjectorPlugin)}else if(adNetwork==="bigoads"){// BigoAds 在 dev 模式下注入模拟配置
+webpackConfig.plugins.push(new BigoAdsInjectorPlugin)}else if(adNetwork==="liftoff"){webpackConfig.plugins.push(new LiftoffInjectorPlugin)}else if(adNetwork==="snapchat"){// Snapchat 注入 ScPlayableAd SDK
+webpackConfig.plugins.push(new SnapchatInjectorPlugin)}else if(adNetwork==="adikteev"){// Adikteev 注入 MRAID mock 和占位符变量
+webpackConfig.plugins.push(new AdikteevInjectorPlugin)}}exports.injectSDKPlugins=injectSDKPlugins;

package/core/utils/logOptions.js

@@ -0,0 +1,5 @@
+"use strict";var prettyjson=require("prettyjson");/**
+ * Log provided options into console output
+ */exports.logOptions=function logOptions(options){let logOptions={mode:process.env.NODE_ENV,...options};let isProduction=false;if(process.env.NODE_ENV==="production"){isProduction=true;delete logOptions.port;delete logOptions.open}else if(process.env.NODE_ENV==="development"){delete logOptions.outDir}if(Object.keys(logOptions.compilation).length===0||!isProduction)delete logOptions.compilation;if(Object.keys(logOptions.adNetworkNames).length===0||!isProduction)delete logOptions.adNetworkNames;if(Object.keys(logOptions.defines).length===0)delete logOptions.defines;if(logOptions.zip===false||!isProduction)delete logOptions.zip;if(logOptions.tsConfig==="tsconfig.json")delete logOptions.tsConfig;if(logOptions.jsConfig==="jsconfig.json")delete logOptions.jsConfig;if(logOptions.buildConfig==="build.json")delete logOptions.buildConfig;if(logOptions.language==="en")delete logOptions.language;if(logOptions.orientation==="both")delete logOptions.orientation;// 在 dev 模式下，如果 network 为默认值 preview 则不显示
+if(!isProduction&&logOptions.network==="preview")delete logOptions.network;// 在 dev 模式下，如果 protocol 为默认值 none 则不显示
+if(!isProduction&&logOptions.protocol==="none")delete logOptions.protocol;delete logOptions.filename;delete logOptions.app;delete logOptions.name;delete logOptions.googlePlayUrl;delete logOptions.appStoreUrl;if(logOptions.obfuscateLevel===2)delete logOptions.obfuscateLevel;console.log(prettyjson.render(logOptions,{},2))};

package/core/utils/mergeOptions.js

@@ -0,0 +1,6 @@
+"use strict";/**
+ * Merges two option objects with deep merge for 'defines' and 'build' properties
+ * @param {import('../index').CLIOptions} options1 - First options object
+ * @param {Partial<import('../index').CLIOptions>} [options2] - Second options object
+ * @returns {import('../index').CLIOptions} Merged options object with combined defines and build properties
+ */exports.mergeOptions=function mergeOptions(options1,options2){if(!options1)return{};if(!options2)return options1;const defines=Object.assign({},options1.defines,options2.defines);const build=Object.assign({},options1.build,options2.build);const compilation=Object.assign({},options1.compilation,options2.compilation);const adNetworkNames=Object.assign({},options1.adNetworkNames,options2.adNetworkNames);const options=Object.assign({},options1,options2);options.defines=defines;options.compilation=compilation;options.adNetworkNames=adNetworkNames;options.build=build;return options};

package/core/utils/parseArgvOptions.js

@@ -0,0 +1,8 @@
+"use strict";/** @type {string[]} List of supported advertising networks */const allowedAdNetworks=["preview","applovin","unity","google","ironsource","facebook","moloco","adcolony","mintegral","vungle","tapjoy","snapchat","tiktok","appreciate","chartboost","pangle","mytarget","liftoff","smadex","adikteev","bigabid","inmobi","bigoads"];/** @type {AD_PROTOCOL[]} List of supported advertising protocols */const allowedAdProtocols=["none","mraid","dapi"];/** @type {AD_NETWORK[]} List of advertising partners that support MRAID protocol */const mraidPartners=["ironsource","applovin","unity","appreciate","chartboost","mytarget","liftoff","adcolony","adikteev","bigabid","inmobi"];/** @type {LANGUAGE[]} */const allowedLanguages=["auto","en","es","zh","hi","ar","fr","de","ja","pt"];/** @type {ORIENTATION[]} */const allowedOrientations=["both","portrait","landscape","square"];/**
+ * Parses command line arguments based on provided options configuration
+ * @param {import('../index').CLIOptionConfig[]} posiibleOptions - Array of possible options to parse
+ * @returns {Record<string, any>} Parsed options object with values from command line arguments
+ */exports.parseArgvOptions=function parseArgvOptions(posiibleOptions){const argvOptions={};// Track which options were explicitly set via CLI args
+const cliExplicitKeys=new Set;for(let possibleOption of posiibleOptions){if(possibleOption.defaultValue!==undefined)argvOptions[possibleOption.alias||possibleOption.name]=possibleOption.defaultValue}let adNetwork=null;for(let i=2;i<process.argv.length;i++){let key=process.argv[i];let inlineValue=null;// 支持 --key=value 格式
+if(key.includes("=")){const eqIndex=key.indexOf("=");inlineValue=key.slice(eqIndex+1);key=key.slice(0,eqIndex)}const allowedOption=posiibleOptions.find(e=>"--"+e.name===key);if(allowedOption){let value=true;if(allowedOption.hasValue){// 优先使用内联值（--key=value），否则使用下一个参数
+value=inlineValue!==null?inlineValue:process.argv[++i];if(allowedOption.parser)value=allowedOption.parser(value)}const optionKey=allowedOption.alias||allowedOption.name;argvOptions[optionKey]=value;cliExplicitKeys.add(optionKey)}else if(!adNetwork)adNetwork=key}if(posiibleOptions.find(e=>e.name==="network")){if(adNetwork&&allowedAdNetworks.includes(adNetwork)){argvOptions["network"]=adNetwork}if(posiibleOptions.find(e=>e.name==="protocol")){if(mraidPartners.includes(argvOptions["network"])&&argvOptions["protocol"]==="none"){argvOptions["protocol"]="mraid"}}}argvOptions._cliExplicitKeys=cliExplicitKeys;return argvOptions};exports.allowedAdNetworks=allowedAdNetworks;exports.allowedAdProtocols=allowedAdProtocols;exports.mraidPartners=mraidPartners;exports.allowedLanguages=allowedLanguages;exports.allowedOrientations=allowedOrientations;

package/core/utils/resolveChannelFold2Zip.js

@@ -0,0 +1,14 @@
+"use strict";/**
+ * 解析 isChannelFold2Zip 相关标志
+ *
+ * isChannelFold2Zip：所有渠道（排除 preview）输出 dist/渠道名称.zip
+ * - ZIP 渠道（google/tiktok 等）：正常 ZIP 流程，输出路径改为 dist/渠道名称.zip
+ * - 非 ZIP 渠道（facebook 默认等）：强制将 HTML 打包成 zip，输出 dist/渠道名称.zip
+ *
+ * @param {object} params
+ * @param {boolean} params.isChannelFold2ZipOption - buildOptions.isChannelFold2Zip 的值
+ * @param {string} params.adNetwork - 当前渠道名称
+ * @param {boolean} params.isZipOutput - 当前渠道是否本身就走 ZIP 输出流程
+ * @returns {{ isChannelFold2Zip: boolean, isZipOutputFinal: boolean }}
+ */function resolveChannelFold2Zip({isChannelFold2ZipOption,adNetwork,isZipOutput}){const isChannelFold2Zip=!!(isChannelFold2ZipOption&&adNetwork!=="preview");// 非 ZIP 渠道启用 isChannelFold2Zip 时，需要强制走 ZIP 输出流程
+const isZipOutputFinal=isZipOutput||isChannelFold2Zip;if(isChannelFold2Zip){console.log(`✅ isChannelFold2Zip enabled: output will be dist/${adNetwork}.zip`)}return{isChannelFold2Zip,isZipOutputFinal}}exports.resolveChannelFold2Zip=resolveChannelFold2Zip;

package/core/utils/validateThemeData.js

@@ -0,0 +1,97 @@
+"use strict";const fs=require("fs");const path=require("path");const JSON5=require("json5");const Ajv=require("ajv");const SCHEMA_BACKUP_SUFFIX=".backup";const SCHEMA_BACKUP_COMMENT="// [\u81EA\u52A8\u751F\u6210\u7684\u5907\u4EFD] \u6B64\u6587\u4EF6\u7531\u6253\u5305\u6D41\u7A0B\u521B\u5EFA\u3002\n"+"// \u5982\u679C\u6253\u5305\u4E2D\u65AD\uFF0C\u53EF\u4EE5\u79FB\u9664 \".backup\" \u540E\u7F00\uFF0C\n"+"// \u5E76\u7528\u6B64\u6587\u4EF6\u66FF\u6362\u539F\u59CB\u7684 \"theme.schema.json5\" \u6765\u6062\u590D\u3002\n";/**
+ * 递归提取 JSON Schema 定义中的 `default` 值。
+ *
+ * - 对于 "object" 类型：递归遍历 `properties` 并构建嵌套对象。
+ * - 对于基本类型：如果存在 `default` 值则返回。
+ *
+ * @param {object} schema - JSON Schema（或子 schema）对象
+ * @returns {*} 提取的默认值树，如果没有则返回 undefined
+ */function extractDefaultsFromSchema(schema){if(!schema||typeof schema!=="object")return undefined;if(schema.type==="object"&&schema.properties){const result={};for(const[key,propSchema]of Object.entries(schema.properties)){const val=extractDefaultsFromSchema(propSchema);if(val!==undefined){result[key]=val}}return Object.keys(result).length>0?result:undefined}// 基本类型或数组类型，带有默认值
+if("default"in schema){return schema.default}return undefined}/**
+ * Check whether the parsed content of theme.schema.json5 is a real JSON Schema
+ * (has "type" and "properties" fields) or has already been overwritten with
+ * plain merged data (e.g. due to a previous interrupted build).
+ *
+ * @param {object} obj - Parsed content of theme.schema.json5
+ * @returns {boolean} true if it looks like a valid JSON Schema definition
+ */function isJsonSchema(obj){return obj&&typeof obj==="object"&&obj.type==="object"&&typeof obj.properties==="object"}/**
+ * 根据 schema 校验指定主题的主题数据。
+ *
+ * 项目中预期的文件结构：
+ *   src/theme/theme.schema.json5              – JSON Schema（JSON5 格式）
+ *   src/theme/{themeName}/theme.data.json5    – 各主题的数据
+ *
+ * 通过 extractDefaultsFromSchema 从 schema 的 `default` 字段提取默认值，
+ * 然后与主题数据深度合并（主题数据优先）后再进行校验。
+ *
+ * 保险机制：如果 theme.schema.json5 已经是纯 JSON 数据（非 schema 格式），
+ * 说明上次构建中断后未能恢复，此时直接使用该数据，跳过校验。
+ *
+ * @param {string} themeName   - 主题目录名称
+ * @param {string} projectRoot - 项目根目录的绝对路径
+ * @param {object} [themeConfig] - 可选的主题配置（builds.config.js 中的 themes 部分）
+ * @returns {{ defaultData: object, mergedData: object, isPlainData: boolean, errors: string[] | null }}
+ *   defaultData  – 从 schema 提取的默认值
+ *   mergedData   – schema 默认值与主题数据合并后的完整数据
+ *   isPlainData  – 如果 schema 文件已经是纯数据（非 schema 格式）则为 true
+ *   errors       – 校验通过为 null，否则为错误信息数组
+ */function validateThemeData(themeName,projectRoot,themeConfig){const sourceDir=themeConfig&&themeConfig.sourceDir||"src/theme";const themeBaseDir=path.join(projectRoot,sourceDir);// --- 解析文件路径 ---
+const schemaPath=path.join(themeBaseDir,"theme.schema.json5");const dataPath=path.join(themeBaseDir,themeName,"theme.data.json5");// --- 读取并解析文件 ---
+if(!fs.existsSync(schemaPath)){return{defaultData:null,mergedData:null,isPlainData:false,errors:[`未找到 Schema 文件: ${schemaPath}`]}}const schemaContent=JSON5.parse(fs.readFileSync(schemaPath,"utf8"));// Safety check: if the file is already plain data (not a JSON Schema),
+// it was likely left over from a previous interrupted build.
+// Use it directly without validation or overwriting.
+if(!isJsonSchema(schemaContent)){return{defaultData:schemaContent,mergedData:schemaContent,isPlainData:true,errors:null}}// 从 schema 提取默认值
+const defaultData=extractDefaultsFromSchema(schemaContent)||{};let themeData={};if(fs.existsSync(dataPath)){themeData=JSON5.parse(fs.readFileSync(dataPath,"utf8"))}// 深度合并（主题数据覆盖 schema 默认值），然后校验
+const merged=deepMerge(defaultData,themeData);// --- 根据 schema 校验合并后的数据 ---
+const ajv=new Ajv({allErrors:true,strict:false});const validate=ajv.compile(schemaContent);const valid=validate(merged);if(!valid){const errors=validate.errors.map(err=>{const field=err.instancePath||"(root)";return`${field} ${err.message}`});return{defaultData,mergedData:merged,isPlainData:false,errors}}return{defaultData,mergedData:merged,isPlainData:false,errors:null}}/**
+ * 深度合并两个普通对象。`override` 中的值优先。
+ * 数组会被整体替换（不会拼接）。
+ *
+ * @param {object} base
+ * @param {object} override
+ * @returns {object}
+ */function deepMerge(base,override){const result={...base};for(const key of Object.keys(override)){const baseVal=base[key];const overVal=override[key];if(overVal!==null&&typeof overVal==="object"&&!Array.isArray(overVal)&&baseVal!==null&&typeof baseVal==="object"&&!Array.isArray(baseVal)){result[key]=deepMerge(baseVal,overVal)}else{result[key]=overVal}}return result}/**
+ * 备份原始的 theme.schema.json5 文件。
+ * 备份文件包含注释头，说明如何手动恢复。
+ *
+ * @param {string} schemaPath - theme.schema.json5 的绝对路径
+ * @returns {string} 备份文件路径
+ */function backupSchema(schemaPath){const backupPath=schemaPath+SCHEMA_BACKUP_SUFFIX;const originalContent=fs.readFileSync(schemaPath,"utf8");fs.writeFileSync(backupPath,SCHEMA_BACKUP_COMMENT+originalContent,"utf8");return backupPath}/**
+ * 从备份文件恢复 theme.schema.json5 并删除备份。
+ *
+ * @param {string} schemaPath - theme.schema.json5 的绝对路径
+ */function restoreSchema(schemaPath){const backupPath=schemaPath+SCHEMA_BACKUP_SUFFIX;if(!fs.existsSync(backupPath))return;const backupContent=fs.readFileSync(backupPath,"utf8");// 去除自动生成的注释头（以 "//" 开头的行）
+const lines=backupContent.split("\n");const contentStart=lines.findIndex(line=>!line.startsWith("//"));const originalContent=lines.slice(contentStart>=0?contentStart:0).join("\n");fs.writeFileSync(schemaPath,originalContent,"utf8");fs.unlinkSync(backupPath)}/**
+ * 用合并后的数据（schema 默认值 + 主题覆盖值）覆写 theme.schema.json5，
+ * 以便打包工具在构建时可以直接使用。
+ *
+ * @param {string} schemaPath - theme.schema.json5 的绝对路径
+ * @param {object} mergedData - 要写入的合并后的主题数据
+ */function overwriteSchemaWithMerged(schemaPath,mergedData){const content=JSON.stringify(mergedData,null,2);fs.writeFileSync(schemaPath,content,"utf8")}/**
+ * 执行主题校验并输出标准日志。
+ * 单次构建（build.js）和批量构建（batch-build.js）共用此函数。
+ *
+ * 流程：
+ *   1. 根据 theme.schema.json5 校验 theme.data.json5
+ *   2. 备份 theme.schema.json5（包含恢复说明）
+ *   3. 通过 extractDefaultsFromSchema 从 schema 提取默认值
+ *   4. 用默认数据覆写 theme.schema.json5 以供构建使用
+ *
+ * 构建完成后（无论成功或失败），调用 restoreSchema() 恢复原始文件。
+ *
+ * @param {string} themeName   - 主题目录名称
+ * @param {string} projectRoot - 项目根目录的绝对路径
+ * @param {object} [themeConfig] - 可选的主题配置（builds.config.js 中的 themes 部分）
+ * @param {object} [options]
+ * @param {function} [options.log] - 自定义日志函数(message, level)。默认使用 console.log。
+ * @returns {{ valid: boolean, errors: string[]|null, schemaPath: string|null }}
+ *   valid      – schema 文件不存在（跳过）或校验通过时为 true
+ *   errors     – 校验通过为 null，否则为错误信息数组
+ *   schemaPath – theme.schema.json5 的绝对路径（用于 restoreSchema 调用），或 null
+ */function runThemeValidation(themeName,projectRoot,themeConfig,options){const sourceDir=themeConfig&&themeConfig.sourceDir||"src/theme";const themeBaseDir=path.join(projectRoot,sourceDir);const schemaPath=path.join(themeBaseDir,"theme.schema.json5");// 没有 schema 文件 → 完全跳过校验
+if(!fs.existsSync(schemaPath)){return{valid:true,errors:null,schemaPath:null}}const logFn=options&&options.log||function defaultLog(msg,level){const colors={info:"\x1B[36m",success:"\x1B[32m",error:"\x1B[31m",warn:"\x1B[33m"};const reset="\x1B[0m";const color=colors[level]||"";console.log(`${color}${msg}${reset}`)};logFn(`校验主题数据: ${themeName}`,"info");const{defaultData,mergedData,isPlainData,errors}=validateThemeData(themeName,projectRoot,themeConfig);// Safety: schema file is already plain data (previous build was interrupted)
+// Use it directly, no need to backup/overwrite
+if(isPlainData){logFn(`⚠️  theme.schema.json5 已经是纯数据格式（可能上次构建中断未恢复），直接使用`,"warn");// schemaPath is returned as null so that restoreSchema won't be called
+// (there's nothing to restore — the file is already data, not a schema)
+return{valid:true,errors:null,schemaPath:null}}if(errors){logFn(`主题 "${themeName}" 数据校验失败:`,"error");errors.forEach(e=>logFn(`  - ${e}`,"error"));return{valid:false,errors,schemaPath}}logFn(`主题 "${themeName}" 数据校验通过`,"success");// 备份原始 schema，然后用合并后的数据覆写以供构建使用
+backupSchema(schemaPath);overwriteSchemaWithMerged(schemaPath,mergedData);logFn(`已备份 schema 并写入合并后的主题数据`,"info");return{valid:true,errors:null,schemaPath}}module.exports={validateThemeData,deepMerge,extractDefaultsFromSchema,isJsonSchema,runThemeValidation,backupSchema,restoreSchema,overwriteSchemaWithMerged};

package/core/validators/index.d.ts

@@ -0,0 +1,242 @@
+// ============================================================
+// 埋点验证器类型定义
+// ============================================================
+
+/**
+ * 埋点方法配置
+ */
+export interface TrackingMethod {
+  /** 方法名 */
+  name: string;
+  /** 是否必须调用 */
+  required: boolean;
+  /** 方法描述 */
+  description: string;
+  /** 对应的渠道埋点 */
+  channels: string[];
+}
+
+/**
+ * 验证结果
+ */
+export interface ValidationResult {
+  /** 验证是否通过 */
+  success: boolean;
+  /** 集成类型 */
+  integrationType: 'sdk' | 'tracking' | 'none';
+  /** 方法检测结果 */
+  methods: Array<{
+    method: string;
+    found: boolean;
+    required: boolean;
+    description: string;
+  }>;
+  /** 错误信息列表 */
+  errors: string[];
+  /** 警告信息列表 */
+  warnings: string[];
+  /** 统计信息 */
+  stats: {
+    totalFiles: number;
+    scannedFiles: number;
+    hasTrackingImport: boolean;
+    hasSDKImport: boolean;
+  };
+}
+
+/**
+ * 验证选项
+ */
+export interface ValidationOptions {
+  /** 文件扩展名列表 */
+  extensions?: string[];
+  /** 排除的目录列表 */
+  excludeDirs?: string[];
+  /** 是否输出详细信息 */
+  verbose?: boolean;
+}
+
+/**
+ * 验证项目中的埋点调用
+ * @param projectRoot - 项目根目录
+ * @param options - 验证选项
+ */
+export declare function validateTracking(
+  projectRoot: string,
+  options?: ValidationOptions
+): ValidationResult;
+
+/**
+ * 格式化验证结果并输出到控制台
+ * @param result - 验证结果
+ * @param showDetails - 是否显示详细信息
+ */
+export declare function printValidationResult(
+  result: ValidationResult,
+  showDetails?: boolean
+): void;
+
+/**
+ * 扫描目录获取所有源码文件
+ * @param dir - 目录路径
+ * @param extensions - 文件扩展名列表
+ * @param excludeDirs - 排除的目录名列表
+ */
+export declare function scanSourceFiles(
+  dir: string,
+  extensions?: string[],
+  excludeDirs?: string[]
+): string[];
+
+/**
+ * 检测代码中是否包含 tracking 方法的直接调用
+ * @param content - 文件内容
+ * @param methodName - 方法名
+ */
+export declare function detectDirectTrackingCall(
+  content: string,
+  methodName: string
+): boolean;
+
+/**
+ * 检测代码中是否包含 SDK 方法调用
+ * @param content - 文件内容
+ * @param sdkMethod - SDK 方法名
+ */
+export declare function detectSDKCall(
+  content: string,
+  sdkMethod: string
+): boolean;
+
+/**
+ * 检测是否导入了 @playcraft/ads-tracking
+ * @param content - 文件内容
+ */
+export declare function hasTrackingImport(content: string): boolean;
+
+/**
+ * 检测是否导入了 @playcraft/adsdk
+ * @param content - 文件内容
+ */
+export declare function hasSDKImport(content: string): boolean;
+
+/**
+ * 所有埋点方法配置
+ */
+export declare const TRACKING_METHODS: TrackingMethod[];
+
+/**
+ * SDK 静态方法映射到 tracking 方法
+ */
+export declare const SDK_TO_TRACKING_MAP: Record<string, string>;
+
+// ============================================================
+// 编译前检查器类型定义
+// ============================================================
+
+/**
+ * 检查结果
+ */
+export interface CheckResult {
+  /** 是否通过 */
+  success: boolean;
+  /** 结果消息 */
+  message: string;
+  /** 额外数据 */
+  data?: any;
+  /** 错误对象（如果检查出错） */
+  error?: Error;
+}
+
+/**
+ * 检查器定义
+ */
+export interface Checker {
+  /** 检查器名称 */
+  name: string;
+  /** 检查器描述 */
+  description: string;
+  /** 是否启用 */
+  enabled: boolean;
+  /** 验证函数 */
+  validator: (projectRoot: string, options: any) => Promise<CheckResult> | CheckResult;
+}
+
+/**
+ * 编译前检查选项
+ */
+export interface PreBuildCheckOptions {
+  /** 只执行指定的检查器 ID */
+  only?: string[];
+  /** 跳过指定的检查器 ID */
+  skip?: string[];
+  /** 详细输出 */
+  verbose?: boolean;
+  /** 显示详细报告 */
+  showDetails?: boolean;
+  /** 遇到错误立即停止 */
+  failFast?: boolean;
+  /** 文件扩展名（传递给检查器） */
+  extensions?: string[];
+  /** 排除的目录（传递给检查器） */
+  excludeDirs?: string[];
+}
+
+/**
+ * 编译前检查结果
+ */
+export interface PreBuildCheckResult {
+  /** 是否全部通过 */
+  success: boolean;
+  /** 各检查器的结果 */
+  results: Map<string, CheckResult>;
+}
+
+/**
+ * 执行所有已启用的编译前检查器
+ * @param projectRoot - 项目根目录
+ * @param options - 选项
+ */
+export declare function runPreBuildChecks(
+  projectRoot: string,
+  options?: PreBuildCheckOptions
+): Promise<PreBuildCheckResult>;
+
+/**
+ * 单独运行埋点验证（快捷方法）
+ * @param projectRoot - 项目根目录
+ * @param options - 选项
+ */
+export declare function runTrackingCheck(
+  projectRoot: string,
+  options?: ValidationOptions
+): Promise<CheckResult>;
+
+/**
+ * 注册自定义检查器
+ * @param id - 检查器 ID
+ * @param checker - 检查器配置
+ */
+export declare function registerChecker(id: string, checker: Checker): void;
+
+/**
+ * 启用/禁用检查器
+ * @param id - 检查器 ID
+ * @param enabled - 是否启用
+ */
+export declare function toggleChecker(id: string, enabled: boolean): void;
+
+/**
+ * 获取所有检查器列表
+ */
+export declare function listCheckers(): Array<{
+  id: string;
+  name: string;
+  description: string;
+  enabled: boolean;
+}>;
+
+/**
+ * 内部检查器注册表（高级用户使用）
+ */
+export declare const checkers: Map<string, Checker>;

package/core/validators/pre-build-checker.js

@@ -0,0 +1,89 @@
+"use strict";const{validateTracking,printValidationResult}=require("./tracking-validator.js");// ============================================================
+// 检查器注册表
+// ============================================================
+/**
+ * 检查器定义
+ * @typedef {Object} Checker
+ * @property {string} name - 检查器名称
+ * @property {string} description - 检查器描述
+ * @property {boolean} enabled - 是否启用
+ * @property {(projectRoot: string, options: any) => Promise<CheckResult>|CheckResult} validator - 验证函数
+ *//**
+ * 检查结果
+ * @typedef {Object} CheckResult
+ * @property {boolean} success - 是否通过
+ * @property {string} message - 结果消息
+ * @property {any} [data] - 额外数据
+ *//**
+ * 所有注册的检查器
+ * @type {Map<string, Checker>}
+ */const checkers=new Map;// ============================================================
+// 内置检查器
+// ============================================================
+/**
+ * 埋点验证检查器
+ */checkers.set("tracking",{name:"\u57CB\u70B9\u9A8C\u8BC1",description:"\u9A8C\u8BC1\u9879\u76EE\u4E2D\u662F\u5426\u6B63\u786E\u8C03\u7528\u4E86\u6240\u6709\u5FC5\u987B\u7684\u57CB\u70B9\u65B9\u6CD5",enabled:true,validator:(projectRoot,options={})=>{const result=validateTracking(projectRoot,{verbose:options.verbose||false,extensions:options.extensions,excludeDirs:options.excludeDirs});return{success:result.success,message:result.success?"\u2705 \u57CB\u70B9\u9A8C\u8BC1\u901A\u8FC7":`❌ 埋点验证失败：缺少 ${result.errors.length} 个必须的埋点方法`,data:result}}});// 预留：未来可添加更多检查器
+// checkers.set('assets', {
+//   name: '资源检查',
+//   description: '验证项目资源文件的完整性和规范性',
+//   enabled: false,
+//   validator: (projectRoot, options) => {
+//     // TODO: 实现资源检查逻辑
+//     return { success: true, message: '资源检查通过' };
+//   }
+// });
+// checkers.set('config', {
+//   name: '配置检查',
+//   description: '验证项目配置文件的正确性',
+//   enabled: false,
+//   validator: (projectRoot, options) => {
+//     // TODO: 实现配置检查逻辑
+//     return { success: true, message: '配置检查通过' };
+//   }
+// });
+// ============================================================
+// 检查器管理
+// ============================================================
+/**
+ * 注册自定义检查器
+ * @param {string} id - 检查器 ID
+ * @param {Checker} checker - 检查器配置
+ */function registerChecker(id,checker){if(checkers.has(id)){console.warn(`[警告] 检查器 "${id}" 已存在，将被覆盖`)}checkers.set(id,checker)}/**
+ * 启用/禁用检查器
+ * @param {string} id - 检查器 ID
+ * @param {boolean} enabled - 是否启用
+ */function toggleChecker(id,enabled){const checker=checkers.get(id);if(checker){checker.enabled=enabled}else{console.warn(`[警告] 未找到检查器: ${id}`)}}/**
+ * 获取所有检查器列表
+ * @returns {Array<{id: string, name: string, description: string, enabled: boolean}>}
+ */function listCheckers(){return Array.from(checkers.entries()).map(([id,checker])=>({id,name:checker.name,description:checker.description,enabled:checker.enabled}))}// ============================================================
+// 执行检查
+// ============================================================
+/**
+ * 执行所有已启用的检查器
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} [options] - 选项
+ * @param {string[]} [options.only] - 只执行指定的检查器 ID
+ * @param {string[]} [options.skip] - 跳过指定的检查器 ID
+ * @param {boolean} [options.verbose] - 详细输出
+ * @param {boolean} [options.showDetails] - 显示详细报告
+ * @param {boolean} [options.failFast] - 遇到错误立即停止
+ * @returns {Promise<{success: boolean, results: Map<string, CheckResult>}>}
+ */async function runPreBuildChecks(projectRoot,options={}){const{only=[],skip=[],verbose=false,showDetails=true,failFast=false}=options;const results=new Map;let allSuccess=true;console.log("\n"+"\u2550".repeat(70));console.log("\uD83D\uDD0D \u7F16\u8BD1\u524D\u68C0\u67E5");console.log("\u2550".repeat(70));// 确定要执行的检查器
+let checkersToRun=Array.from(checkers.entries()).filter(([id,checker])=>{// 如果指定了 only，只运行指定的
+if(only.length>0&&!only.includes(id))return false;// 跳过 skip 列表中的
+if(skip.includes(id))return false;// 只运行启用的
+return checker.enabled});if(checkersToRun.length===0){console.log("\n\u26A0\uFE0F  \u6CA1\u6709\u542F\u7528\u7684\u68C0\u67E5\u5668");console.log("\u2550".repeat(70)+"\n");return{success:true,results}}if(verbose){console.log(`\n📋 将执行 ${checkersToRun.length} 个检查器:`);checkersToRun.forEach(([id,checker])=>{console.log(`  - ${checker.name} (${id})`)});console.log("")}// 执行检查器
+for(const[id,checker]of checkersToRun){try{console.log(`\n▶️  执行检查: ${checker.name}`);console.log("-".repeat(70));const result=await Promise.resolve(checker.validator(projectRoot,options));results.set(id,result);console.log(result.message);// 详细输出（针对埋点验证）
+if(showDetails&&id==="tracking"&&result.data){printValidationResult(result.data,showDetails)}if(!result.success){allSuccess=false;if(failFast){console.log("\n\u26A0\uFE0F  failFast \u6A21\u5F0F\uFF1A\u68C0\u6D4B\u5230\u5931\u8D25\uFF0C\u7EC8\u6B62\u540E\u7EED\u68C0\u67E5");break}}}catch(error){console.error(`\n❌ 检查器 "${checker.name}" 执行失败:`,error.message);results.set(id,{success:false,message:`执行出错: ${error.message}`,error});allSuccess=false;if(failFast)break}}// 总结
+console.log("\n"+"\u2550".repeat(70));console.log("\uD83D\uDCCA \u68C0\u67E5\u603B\u7ED3");console.log("\u2550".repeat(70));const successCount=Array.from(results.values()).filter(r=>r.success).length;const totalCount=results.size;console.log(`\n通过: ${successCount}/${totalCount}`);if(allSuccess){console.log("\n\u2705 \u6240\u6709\u68C0\u67E5\u901A\u8FC7\uFF0C\u53EF\u4EE5\u7EE7\u7EED\u7F16\u8BD1\uFF01")}else{console.log("\n\u274C \u90E8\u5206\u68C0\u67E5\u5931\u8D25\uFF0C\u8BF7\u4FEE\u590D\u540E\u518D\u7F16\u8BD1\u3002")}console.log("\u2550".repeat(70)+"\n");return{success:allSuccess,results}}/**
+ * 单独运行埋点验证（快捷方法）
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} [options] - 选项
+ * @returns {Promise<CheckResult>}
+ */async function runTrackingCheck(projectRoot,options={}){const checker=checkers.get("tracking");if(!checker){throw new Error("\u57CB\u70B9\u68C0\u67E5\u5668\u672A\u6CE8\u518C")}return await Promise.resolve(checker.validator(projectRoot,options))}// ============================================================
+// 导出
+// ============================================================
+module.exports={// 主要函数
+runPreBuildChecks,runTrackingCheck,// 检查器管理
+registerChecker,toggleChecker,listCheckers,// 内部访问（供高级用户）
+checkers};