@playcraft/devkit 1.0.31-beta.1 → 1.0.31-beta.11

package/core/validators/tracking-validator.js

@@ -1,6 +1,10 @@
-"use strict";const fs=require("fs");const path=require("path");// ============================================================
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================
 // 埋点方法配置
 // ============================================================
+
 /**
  * 埋点方法配置
  * @typedef {Object} TrackingMethod
@@ -8,30 +12,212 @@
  * @property {boolean} required - 是否必须调用
  * @property {string} description - 方法描述
  * @property {string[]} channels - 对应的渠道埋点
- *//**
+ */
+
+/**
  * 所有埋点方法配置
  * @type {TrackingMethod[]}
- */const TRACKING_METHODS=[{name:"onPlaycraftTrackingInit",required:true,description:"SDK \u521D\u59CB\u5316\u5F00\u59CB",channels:["Bigabid:mraid_viewable","InMobi:Ad_Load_Start","AppLovin:LOADING"]},{name:"onPlaycraftTrackingLoading",required:true,description:"\u6E38\u620F\u8D44\u6E90\u52A0\u8F7D\u4E2D",channels:["Bigabid:game_viewable","InMobi:Ad_Viewable","AppLovin:LOADED"]},{name:"onPlaycraftTrackingLoaded",required:true,description:"\u4E3B\u573A\u666F\u5C31\u7EEA\uFF0C\u7528\u6237\u53EF\u4EA4\u4E92",channels:["AppLovin:DISPLAYED"]},{name:"onPlaycraftChallengeStart",required:true,description:"\u6311\u6218\u5F00\u59CB\uFF08\u9996\u6B21\u7528\u6237\u4EA4\u4E92\uFF09",channels:["Bigabid:engagement","InMobi:First_Engagement","AppLovin:CHALLENGE_STARTED"]},{name:"onPlaycraftChallengeProgress",required:false,description:"\u8FDB\u5EA6\u767E\u5206\u6BD4\u8FFD\u8E2A\uFF08\u53EF\u9009\uFF09",channels:["AppLovin:CHALLENGE_PASS_*"]},{name:"onPlaycraftChallengeSuccess",required:true,description:"\u6E38\u620F\u6311\u6218\u6210\u529F",channels:["AppLovin:CHALLENGE_SOLVED","Bigabid:complete","InMobi:Gameplay_Complete"]},{name:"onPlaycraftChallengeFinish",required:false,description:"\u6E38\u620F\u7ED3\u675F\uFF08\u53EF\u9009\uFF09",channels:["Bigabid:complete","InMobi:Gameplay_Complete","AppLovin:ENDCARD_SHOWN"]},{name:"onPlaycraftInstall",required:true,description:"\u70B9\u51FB\u5B89\u88C5",channels:["Bigabid:click","InMobi:DSP_Click","AppLovin:CTA_CLICKED"]},{name:"onPlaycraftRetry",required:false,description:"\u91CD\u8BD5\u6E38\u620F\uFF08\u53EF\u9009\uFF09",channels:["AppLovin:CHALLENGE_RETRY"]},{name:"onPlaycraftChallengeFailed",required:true,description:"\u6E38\u620F\u6311\u6218\u5931\u8D25",channels:["AppLovin:CHALLENGE_FAILED"]}];/**
+ */
+const TRACKING_METHODS = [
+  {
+    name: 'onPlaycraftTrackingInit',
+    required: true,
+    description: 'SDK 初始化开始',
+    channels: ['Bigabid:mraid_viewable', 'InMobi:Ad_Load_Start', 'AppLovin:LOADING']
+  },
+  {
+    name: 'onPlaycraftTrackingLoading',
+    required: true,
+    description: '游戏资源加载中',
+    channels: ['Bigabid:game_viewable', 'InMobi:Ad_Viewable', 'AppLovin:LOADED']
+  },
+  {
+    name: 'onPlaycraftTrackingLoaded',
+    required: true,
+    description: '主场景就绪，用户可交互',
+    channels: ['AppLovin:DISPLAYED']
+  },
+  {
+    name: 'onPlaycraftChallengeStart',
+    required: true,
+    description: '挑战开始（首次用户交互）',
+    channels: ['Bigabid:engagement', 'InMobi:First_Engagement', 'AppLovin:CHALLENGE_STARTED']
+  },
+  {
+    name: 'onPlaycraftChallengeProgress',
+    required: false,
+    description: '进度百分比追踪（可选）',
+    channels: ['AppLovin:CHALLENGE_PASS_*']
+  },
+  {
+    name: 'onPlaycraftChallengeSuccess',
+    required: true,
+    description: '游戏挑战成功',
+    channels: ['AppLovin:CHALLENGE_SOLVED', 'Bigabid:complete', 'InMobi:Gameplay_Complete']
+  },
+  {
+    name: 'onPlaycraftChallengeFinish',
+    required: false,
+    description: '游戏结束（可选）',
+    channels: ['Bigabid:complete', 'InMobi:Gameplay_Complete', 'AppLovin:ENDCARD_SHOWN']
+  },
+  {
+    name: 'onPlaycraftInstall',
+    required: true,
+    description: '点击安装',
+    channels: ['Bigabid:click', 'InMobi:DSP_Click', 'AppLovin:CTA_CLICKED']
+  },
+  {
+    name: 'onPlaycraftRetry',
+    required: false,
+    description: '重试游戏（可选）',
+    channels: ['AppLovin:CHALLENGE_RETRY']
+  },
+  {
+    name: 'onPlaycraftChallengeFailed',
+    required: true,
+    description: '游戏挑战失败',
+    channels: ['AppLovin:CHALLENGE_FAILED']
+  }
+];
+
+/**
  * SDK 静态方法映射到 tracking 方法
  * 这些 SDK 方法内部会调用对应的 tracking 方法
- */const SDK_TO_TRACKING_MAP={"playcraftInit":"onPlaycraftTrackingInit","playcraftStart":"onPlaycraftTrackingLoading","playcraftInteractive":"onPlaycraftTrackingLoaded","playcraftChallengeStart":"onPlaycraftChallengeStart","recordPlaycraftChallengeProgress":"onPlaycraftChallengeProgress","playcraftRecordSuccess":"onPlaycraftChallengeSuccess","playcraftFinish":"onPlaycraftChallengeFinish","playcraftInstall":"onPlaycraftInstall","playcraftRetry":"onPlaycraftRetry","playcraftRecordFailed":"onPlaycraftChallengeFailed"};// ============================================================
+ */
+const SDK_TO_TRACKING_MAP = {
+  'playcraftInit': 'onPlaycraftTrackingInit',
+  'playcraftStart': 'onPlaycraftTrackingLoading',
+  'playcraftInteractive': 'onPlaycraftTrackingLoaded',
+  'playcraftChallengeStart': 'onPlaycraftChallengeStart',
+  'recordPlaycraftChallengeProgress': 'onPlaycraftChallengeProgress',
+  'playcraftRecordSuccess': 'onPlaycraftChallengeSuccess',
+  'playcraftFinish': 'onPlaycraftChallengeFinish',
+  'playcraftInstall': 'onPlaycraftInstall',
+  'playcraftRetry': 'onPlaycraftRetry',
+  'playcraftRecordFailed': 'onPlaycraftChallengeFailed'
+};
+
+/** Phaser / Three 游戏逻辑在 src；Cocos 在 assets/scripts。不要扫 library/temp。 */
+const ENGINE_SCAN_ROOTS = {
+  cocos: ['assets/scripts'],
+  phaser: ['src'],
+  threejs: ['src'],
+};
+
+const DEFAULT_EXCLUDE_DIRS = [
+  'node_modules', 'dist', 'build', '.git', '.claude',
+  'library', 'temp', 'profiles', 'native', 'local', 'dist-all',
+];
+
+function detectProjectEngine(projectRoot, explicit) {
+  if (explicit) return String(explicit).toLowerCase();
+  try {
+    const configPath = path.join(projectRoot, 'builds.config.js');
+    if (fs.existsSync(configPath)) {
+      delete require.cache[require.resolve(configPath)];
+      const cfg = require(configPath);
+      if (cfg && cfg.engine) return String(cfg.engine).toLowerCase();
+    }
+  } catch {
+    // ignore invalid builds.config.js
+  }
+  if (fs.existsSync(path.join(projectRoot, 'settings/cocos.config.json'))) return 'cocos';
+  if (
+    fs.existsSync(path.join(projectRoot, 'assets/scripts')) &&
+    fs.existsSync(path.join(projectRoot, 'assets/scenes'))
+  ) {
+    return 'cocos';
+  }
+  return '';
+}
+
+function resolveScanRoots(projectRoot, engine) {
+  const rels = ENGINE_SCAN_ROOTS[engine] || ENGINE_SCAN_ROOTS.phaser;
+  const roots = rels
+    .map((rel) => path.join(projectRoot, rel))
+    .filter((dir) => fs.existsSync(dir));
+  return roots.length ? roots : [projectRoot];
+}
+
+function toRelScanRoots(projectRoot, roots) {
+  return roots.map((dir) => {
+    const rel = path.relative(projectRoot, dir);
+    return rel || '.';
+  });
+}
+
+// ============================================================
 // 文件扫描工具
 // ============================================================
+
 /**
  * 递归扫描目录获取所有源码文件
  * @param {string} dir - 目录路径
  * @param {string[]} extensions - 文件扩展名列表
  * @param {string[]} excludeDirs - 排除的目录名列表
  * @returns {string[]} 文件路径列表
- */function scanSourceFiles(dir,extensions=[".ts",".tsx",".js",".jsx"],excludeDirs=["node_modules","dist","build",".git",".claude"]){const files=[];function scan(currentDir){if(!fs.existsSync(currentDir))return;const entries=fs.readdirSync(currentDir,{withFileTypes:true});for(const entry of entries){const fullPath=path.join(currentDir,entry.name);if(entry.isDirectory()){// 跳过排除的目录
-if(excludeDirs.includes(entry.name))continue;scan(fullPath)}else if(entry.isFile()){// 检查文件扩展名
-const ext=path.extname(entry.name);if(extensions.includes(ext)){files.push(fullPath)}}}}scan(dir);return files}/**
+ */
+function scanSourceFiles(dir, extensions = ['.ts', '.tsx', '.js', '.jsx'], excludeDirs = DEFAULT_EXCLUDE_DIRS) {
+  const files = [];
+
+  function scan(currentDir) {
+    if (!fs.existsSync(currentDir)) return;
+
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        // 跳过排除的目录
+        if (excludeDirs.includes(entry.name)) continue;
+        scan(fullPath);
+      } else if (entry.isFile()) {
+        // 检查文件扩展名
+        const ext = path.extname(entry.name);
+        if (extensions.includes(ext)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  }
+
+  scan(dir);
+  return files;
+}
+
+function scanSourceFilesFromRoots(roots, extensions, excludeDirs) {
+  const files = [];
+  const seen = new Set();
+  for (const root of roots) {
+    for (const file of scanSourceFiles(root, extensions, excludeDirs)) {
+      if (seen.has(file)) continue;
+      seen.add(file);
+      files.push(file);
+    }
+  }
+  return files;
+}
+
+/**
  * 读取文件内容（带错误处理）
  * @param {string} filePath - 文件路径
  * @returns {string|null} 文件内容或 null
- */function readFileContent(filePath){try{return fs.readFileSync(filePath,"utf-8")}catch(err){console.warn(`[警告] 无法读取文件: ${filePath}`,err.message);return null}}// ============================================================
+ */
+function readFileContent(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    console.warn(`[警告] 无法读取文件: ${filePath}`, err.message);
+    return null;
+  }
+}
+
+// ============================================================
 // 方法调用检测
 // ============================================================
+
 /**
  * 检测代码中是否包含 tracking 方法的直接调用
  * @param {string} content - 文件内容
@@ -40,10 +226,21 @@ const ext=path.extname(entry.name);if(extensions.includes(ext)){files.push(fullP
  * 
  * 注意：不依赖对象名称，只检测方法调用模式
  * 匹配：xxx.onPlaycraftXxx( 或 xxx['onPlaycraftXxx']( 或 xxx["onPlaycraftXxx"](
- */function detectDirectTrackingCall(content,methodName){const patterns=[// 匹配 .方法名(
-new RegExp(`\\.${methodName}\\s*\\(`),// 匹配 ['方法名'](
-new RegExp(`\\['${methodName}'\\]\\s*\\(`),// 匹配 ["方法名"](
-new RegExp(`\\["${methodName}"\\]\\s*\\(`)];return patterns.some(pattern=>pattern.test(content))}/**
+ */
+function detectDirectTrackingCall(content, methodName) {
+  const patterns = [
+    // 匹配 .方法名(
+    new RegExp(`\\.${methodName}\\s*\\(`),
+    // 匹配 ['方法名'](
+    new RegExp(`\\['${methodName}'\\]\\s*\\(`),
+    // 匹配 ["方法名"](
+    new RegExp(`\\["${methodName}"\\]\\s*\\(`)
+  ];
+
+  return patterns.some(pattern => pattern.test(content));
+}
+
+/**
  * 检测代码中是否包含 SDK 方法调用（会间接触发 tracking）
  * @param {string} content - 文件内容
  * @param {string} sdkMethod - SDK 方法名
@@ -51,20 +248,48 @@ new RegExp(`\\["${methodName}"\\]\\s*\\(`)];return patterns.some(pattern=>patter
  * 
  * 注意：不依赖对象名称，只检测方法调用模式
  * 匹配：xxx.playcraftXxx( 或 xxx['playcraftXxx']( 或 xxx["playcraftXxx"](
- */function detectSDKCall(content,sdkMethod){const patterns=[// 匹配 .方法名(
-new RegExp(`\\.${sdkMethod}\\s*\\(`),// 匹配 ['方法名'](
-new RegExp(`\\['${sdkMethod}'\\]\\s*\\(`),// 匹配 ["方法名"](
-new RegExp(`\\["${sdkMethod}"\\]\\s*\\(`)];return patterns.some(pattern=>pattern.test(content))}/**
+ */
+function detectSDKCall(content, sdkMethod) {
+  const patterns = [
+    // 匹配 .方法名(
+    new RegExp(`\\.${sdkMethod}\\s*\\(`),
+    // 匹配 ['方法名'](
+    new RegExp(`\\['${sdkMethod}'\\]\\s*\\(`),
+    // 匹配 ["方法名"](
+    new RegExp(`\\["${sdkMethod}"\\]\\s*\\(`)
+  ];
+
+  return patterns.some(pattern => pattern.test(content));
+}
+
+/**
  * 检测是否导入了 @playcraft/ads-tracking
  * @param {string} content - 文件内容
  * @returns {boolean} 是否导入了 tracking
- */function hasTrackingImport(content){return /from\s+['"]@playcraft\/ads-tracking['"]/.test(content)||/require\s*\(\s*['"]@playcraft\/ads-tracking['"]\s*\)/.test(content)}/**
- * 检测是否导入了 @playcraft/adsdk
- * @param {string} content - 文件内容
- * @returns {boolean} 是否导入了 SDK
- */function hasSDKImport(content){return /from\s+['"]@playcraft\/adsdk['"]/.test(content)||/require\s*\(\s*['"]@playcraft\/adsdk['"]\s*\)/.test(content)}// ============================================================
+ */
+function hasTrackingImport(content) {
+  return /from\s+['"]@playcraft\/ads-tracking(?:\/[^'"]*)?['"]/.test(content) ||
+         /require\s*\(\s*['"]@playcraft\/ads-tracking(?:\/[^'"]*)?['"]\s*\)/.test(content);
+}
+
+/**
+ * 检测是否导入了 @playcraft/adsdk（含 /cjs 等子路径，以及项目内 playcraft-adsdk 封装）
+ */
+function hasSDKImport(content) {
+  return /from\s+['"]@playcraft\/adsdk(?:\/[^'"]*)?['"]/.test(content) ||
+         /require\s*\(\s*['"]@playcraft\/adsdk(?:\/[^'"]*)?['"]\s*\)/.test(content) ||
+         /from\s+['"][^'"]*playcraft-adsdk['"]/.test(content) ||
+         /require\s*\(\s*['"][^'"]*playcraft-adsdk['"]\s*\)/.test(content);
+}
+
+function hasAnySdkTrackingCall(content) {
+  return Object.keys(SDK_TO_TRACKING_MAP).some((sdkMethod) => detectSDKCall(content, sdkMethod));
+}
+
+// ============================================================
 // 验证核心逻辑
 // ============================================================
+
 /**
  * 验证结果
  * @typedef {Object} ValidationResult
@@ -74,40 +299,216 @@ new RegExp(`\\["${sdkMethod}"\\]\\s*\\(`)];return patterns.some(pattern=>pattern
  * @property {string[]} errors - 错误信息列表
  * @property {string[]} warnings - 警告信息列表
  * @property {Object} stats - 统计信息
- *//**
+ */
+
+/**
  * 验证项目中的埋点调用
  * @param {string} projectRoot - 项目根目录
  * @param {Object} [options] - 验证选项
  * @param {string[]} [options.extensions] - 文件扩展名
  * @param {string[]} [options.excludeDirs] - 排除的目录
+ * @param {string} [options.engine] - 引擎：cocos / phaser / threejs
+ * @param {string[]} [options.scanDirs] - 覆盖默认扫描目录（相对项目根）
  * @param {boolean} [options.verbose] - 是否输出详细信息
  * @returns {ValidationResult} 验证结果
- */function validateTracking(projectRoot,options={}){const{extensions=[".ts",".tsx",".js",".jsx"],excludeDirs=["node_modules","dist","build",".git"],verbose=false}=options;const result={success:false,integrationType:"none",methods:[],errors:[],warnings:[],stats:{totalFiles:0,scannedFiles:0,hasTrackingImport:false,hasSDKImport:false}};// 1. 扫描所有源码文件
-if(verbose)console.log(`\n[扫描] 开始扫描项目: ${projectRoot}`);const files=scanSourceFiles(projectRoot,extensions,excludeDirs);result.stats.totalFiles=files.length;if(files.length===0){result.errors.push("\u672A\u627E\u5230\u4EFB\u4F55\u6E90\u7801\u6587\u4EF6");return result}if(verbose)console.log(`[扫描] 找到 ${files.length} 个源码文件\n`);// 2. 读取所有文件内容并合并（用于全局检测）
-let allContent="";for(const file of files){const content=readFileContent(file);if(content){allContent+=content+"\n";result.stats.scannedFiles++}}// 3. 判断集成类型
-result.stats.hasTrackingImport=hasTrackingImport(allContent);result.stats.hasSDKImport=hasSDKImport(allContent);if(result.stats.hasTrackingImport&&result.stats.hasSDKImport){result.integrationType="sdk";// SDK 优先
-}else if(result.stats.hasSDKImport){result.integrationType="sdk"}else if(result.stats.hasTrackingImport){result.integrationType="tracking"}else{result.errors.push("\u672A\u68C0\u6D4B\u5230 @playcraft/adsdk \u6216 @playcraft/ads-tracking \u7684\u5BFC\u5165");return result}if(verbose){console.log(`[集成类型] ${result.integrationType==="sdk"?"SDK \u96C6\u6210\uFF08\u901A\u8FC7 sdk \u9759\u6001\u65B9\u6CD5\u8C03\u7528\uFF09":"\u76F4\u63A5 tracking \u96C6\u6210"}`);console.log(`[导入检测] SDK: ${result.stats.hasSDKImport?"\u2713":"\u2717"} | Tracking: ${result.stats.hasTrackingImport?"\u2713":"\u2717"}\n`)}// 4. 检测每个埋点方法
-for(const method of TRACKING_METHODS){let found=false;if(result.integrationType==="sdk"){// SDK 集成：检测 SDK 方法调用
-const sdkMethod=Object.keys(SDK_TO_TRACKING_MAP).find(key=>SDK_TO_TRACKING_MAP[key]===method.name);if(sdkMethod){found=detectSDKCall(allContent,sdkMethod)}}else if(result.integrationType==="tracking"){// 直接 tracking 集成：检测 tracking 方法调用
-found=detectDirectTrackingCall(allContent,method.name)}result.methods.push({method:method.name,found,required:method.required,description:method.description});// 必须方法未找到 -> 错误
-if(method.required&&!found){result.errors.push(`❌ 缺少必须的埋点方法: ${method.name} (${method.description})`)}// 可选方法未找到 -> 警告
-if(!method.required&&!found){result.warnings.push(`⚠️  未找到可选埋点方法: ${method.name} (${method.description})`)}}// 5. 判断验证结果
-result.success=result.errors.length===0;return result}// ============================================================
+ */
+function validateTracking(projectRoot, options = {}) {
+  const {
+    extensions = ['.ts', '.tsx', '.js', '.jsx'],
+    excludeDirs = DEFAULT_EXCLUDE_DIRS,
+    verbose = false
+  } = options;
+  const engine = detectProjectEngine(projectRoot, options.engine);
+  const scanRoots = Array.isArray(options.scanDirs) && options.scanDirs.length
+    ? options.scanDirs.map((dir) => path.resolve(projectRoot, dir)).filter((dir) => fs.existsSync(dir))
+    : resolveScanRoots(projectRoot, engine);
+
+  const result = {
+    success: false,
+    integrationType: 'none',
+    methods: [],
+    errors: [],
+    warnings: [],
+    stats: {
+      totalFiles: 0,
+      scannedFiles: 0,
+      hasTrackingImport: false,
+      hasSDKImport: false,
+      engine,
+      scanRoots: toRelScanRoots(projectRoot, scanRoots),
+    }
+  };
+
+  // 1. 按引擎扫描源码目录，避免 Cocos library/temp 把检测带偏
+  if (verbose) {
+    console.log(`\n[扫描] 项目: ${projectRoot}`);
+    console.log(`[扫描] 引擎: ${engine || '(default/src)'}`);
+    console.log(`[扫描] 目录: ${result.stats.scanRoots.join(', ')}`);
+  }
+  const files = scanSourceFilesFromRoots(scanRoots, extensions, excludeDirs);
+  result.stats.totalFiles = files.length;
+
+  if (files.length === 0) {
+    result.errors.push('未找到任何源码文件');
+    return result;
+  }
+
+  if (verbose) console.log(`[扫描] 找到 ${files.length} 个源码文件\n`);
+
+  // 2. 读取所有文件内容并合并（用于全局检测）
+  let allContent = '';
+  for (const file of files) {
+    const content = readFileContent(file);
+    if (content) {
+      allContent += content + '\n';
+      result.stats.scannedFiles++;
+    }
+  }
+
+  // 3. 判断集成类型
+  result.stats.hasTrackingImport = hasTrackingImport(allContent);
+  result.stats.hasSDKImport = hasSDKImport(allContent);
+
+  if (result.stats.hasSDKImport || hasAnySdkTrackingCall(allContent)) {
+    result.integrationType = 'sdk';
+  } else if (result.stats.hasTrackingImport) {
+    result.integrationType = 'tracking';
+  } else {
+    result.errors.push('未检测到 @playcraft/adsdk 或 @playcraft/ads-tracking 的导入');
+    return result;
+  }
+
+  if (verbose) {
+    console.log(`[集成类型] ${result.integrationType === 'sdk' ? 'SDK 集成（通过 sdk 静态方法调用）' : '直接 tracking 集成'}`);
+    console.log(`[导入检测] SDK: ${result.stats.hasSDKImport ? '✓' : '✗'} | Tracking: ${result.stats.hasTrackingImport ? '✓' : '✗'}\n`);
+  }
+
+  // 4. 检测每个埋点方法
+  for (const method of TRACKING_METHODS) {
+    let found = false;
+
+    if (result.integrationType === 'sdk') {
+      // SDK 集成：检测 SDK 方法调用
+      const sdkMethod = Object.keys(SDK_TO_TRACKING_MAP).find(
+        key => SDK_TO_TRACKING_MAP[key] === method.name
+      );
+      if (sdkMethod) {
+        found = detectSDKCall(allContent, sdkMethod);
+      }
+    } else if (result.integrationType === 'tracking') {
+      // 直接 tracking 集成：检测 tracking 方法调用
+      found = detectDirectTrackingCall(allContent, method.name);
+    }
+
+    result.methods.push({
+      method: method.name,
+      found,
+      required: method.required,
+      description: method.description
+    });
+
+    // 必须方法未找到 -> 错误
+    if (method.required && !found) {
+      result.errors.push(`❌ 缺少必须的埋点方法: ${method.name} (${method.description})`);
+    }
+
+    // 可选方法未找到 -> 警告
+    if (!method.required && !found) {
+      result.warnings.push(`⚠️  未找到可选埋点方法: ${method.name} (${method.description})`);
+    }
+  }
+
+  // 5. 判断验证结果
+  result.success = result.errors.length === 0;
+
+  return result;
+}
+
+// ============================================================
 // 格式化输出
 // ============================================================
+
 /**
  * 格式化验证结果并输出到控制台
  * @param {ValidationResult} result - 验证结果
  * @param {boolean} [showDetails=true] - 是否显示详细信息
- */function printValidationResult(result,showDetails=true){console.log("\n"+"=".repeat(60));console.log("\uD83D\uDCCA \u57CB\u70B9\u9A8C\u8BC1\u62A5\u544A");console.log("=".repeat(60));// 统计信息
-console.log(`\n📁 文件统计: 扫描 ${result.stats.scannedFiles}/${result.stats.totalFiles} 个文件`);console.log(`🔗 集成类型: ${result.integrationType==="sdk"?"SDK \u96C6\u6210":result.integrationType==="tracking"?"Tracking \u76F4\u63A5\u96C6\u6210":"\u672A\u68C0\u6D4B\u5230"}`);// 方法检测结果
-if(showDetails){console.log("\n\uD83D\uDCCB \u65B9\u6CD5\u68C0\u6D4B\u660E\u7EC6:");console.log("-".repeat(60));const requiredMethods=result.methods.filter(m=>m.required);const optionalMethods=result.methods.filter(m=>!m.required);console.log("\n\u5FC5\u987B\u65B9\u6CD5:");for(const m of requiredMethods){const status=m.found?"\u2705":"\u274C";console.log(`  ${status} ${m.method.padEnd(35)} ${m.found?"\u5DF2\u8C03\u7528":"\u672A\u8C03\u7528"}`)}console.log("\n\u53EF\u9009\u65B9\u6CD5:");for(const m of optionalMethods){const status=m.found?"\u2705":"\u26A0\uFE0F ";console.log(`  ${status} ${m.method.padEnd(35)} ${m.found?"\u5DF2\u8C03\u7528":"\u672A\u8C03\u7528"}`)}}// 错误信息
-if(result.errors.length>0){console.log("\n\u274C \u9519\u8BEF:");result.errors.forEach(err=>console.log(`  ${err}`))}// 警告信息
-if(result.warnings.length>0){console.log("\n\u26A0\uFE0F  \u8B66\u544A:");result.warnings.forEach(warn=>console.log(`  ${warn}`))}// 最终结果
-console.log("\n"+"=".repeat(60));if(result.success){console.log("\u2705 \u9A8C\u8BC1\u901A\u8FC7\uFF01\u6240\u6709\u5FC5\u987B\u7684\u57CB\u70B9\u65B9\u6CD5\u90FD\u5DF2\u6B63\u786E\u8C03\u7528\u3002")}else{console.log("\u274C \u9A8C\u8BC1\u5931\u8D25\uFF01\u5B58\u5728\u7F3A\u5931\u7684\u5FC5\u987B\u57CB\u70B9\u65B9\u6CD5\uFF0C\u8BF7\u68C0\u67E5\u4EE3\u7801\u3002")}console.log("=".repeat(60)+"\n")}// ============================================================
+ */
+function printValidationResult(result, showDetails = true) {
+  console.log('\n' + '='.repeat(60));
+  console.log('📊 埋点验证报告');
+  console.log('='.repeat(60));
+
+  // 统计信息
+  console.log(`\n📁 文件统计: 扫描 ${result.stats.scannedFiles}/${result.stats.totalFiles} 个文件`);
+  if (result.stats.engine || (result.stats.scanRoots && result.stats.scanRoots.length)) {
+    console.log(`🧭 引擎: ${result.stats.engine || 'default'} | 目录: ${(result.stats.scanRoots || []).join(', ') || '.'}`);
+  }
+  console.log(`🔗 集成类型: ${result.integrationType === 'sdk' ? 'SDK 集成' : result.integrationType === 'tracking' ? 'Tracking 直接集成' : '未检测到'}`);
+
+  // 方法检测结果
+  if (showDetails) {
+    console.log('\n📋 方法检测明细:');
+    console.log('-'.repeat(60));
+    
+    const requiredMethods = result.methods.filter(m => m.required);
+    const optionalMethods = result.methods.filter(m => !m.required);
+
+    console.log('\n必须方法:');
+    for (const m of requiredMethods) {
+      const status = m.found ? '✅' : '❌';
+      console.log(`  ${status} ${m.method.padEnd(35)} ${m.found ? '已调用' : '未调用'}`);
+    }
+
+    console.log('\n可选方法:');
+    for (const m of optionalMethods) {
+      const status = m.found ? '✅' : '⚠️ ';
+      console.log(`  ${status} ${m.method.padEnd(35)} ${m.found ? '已调用' : '未调用'}`);
+    }
+  }
+
+  // 错误信息
+  if (result.errors.length > 0) {
+    console.log('\n❌ 错误:');
+    result.errors.forEach(err => console.log(`  ${err}`));
+  }
+
+  // 警告信息
+  if (result.warnings.length > 0) {
+    console.log('\n⚠️  警告:');
+    result.warnings.forEach(warn => console.log(`  ${warn}`));
+  }
+
+  // 最终结果
+  console.log('\n' + '='.repeat(60));
+  if (result.success) {
+    console.log('✅ 验证通过！所有必须的埋点方法都已正确调用。');
+  } else {
+    console.log('❌ 验证失败！存在缺失的必须埋点方法，请检查代码。');
+  }
+  console.log('='.repeat(60) + '\n');
+}
+
+// ============================================================
 // 导出
 // ============================================================
-module.exports={// 核心验证函数
-validateTracking,printValidationResult,// 配置数据（供外部使用）
-TRACKING_METHODS,SDK_TO_TRACKING_MAP,// 工具函数（供外部使用）
-scanSourceFiles,detectDirectTrackingCall,detectSDKCall,hasTrackingImport,hasSDKImport};
+
+module.exports = {
+  // 核心验证函数
+  validateTracking,
+  printValidationResult,
+
+  // 配置数据（供外部使用）
+  TRACKING_METHODS,
+  SDK_TO_TRACKING_MAP,
+  ENGINE_SCAN_ROOTS,
+  DEFAULT_EXCLUDE_DIRS,
+
+  // 工具函数（供外部使用）
+  detectProjectEngine,
+  resolveScanRoots,
+  scanSourceFiles,
+  detectDirectTrackingCall,
+  detectSDKCall,
+  hasTrackingImport,
+  hasSDKImport
+};

package/core/validators/tracking-validator.test.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  validateTracking,
+  detectProjectEngine,
+  resolveScanRoots,
+  hasSDKImport,
+} = require('./tracking-validator.js');
+
+const SDK_SOURCE = `
+import { sdk } from '@playcraft/adsdk/cjs';
+sdk.playcraftInit(() => {});
+sdk.playcraftStart();
+sdk.playcraftInteractive();
+sdk.playcraftChallengeStart();
+sdk.playcraftRecordSuccess();
+sdk.playcraftRecordFailed();
+sdk.playcraftInstall();
+`;
+
+describe('tracking validator engine scan roots', () => {
+  let root;
+
+  before(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'tracking-scan-'));
+    fs.mkdirSync(path.join(root, 'assets/scripts/game'), { recursive: true });
+    fs.mkdirSync(path.join(root, 'assets/scenes'), { recursive: true });
+    fs.mkdirSync(path.join(root, 'library/import'), { recursive: true });
+    fs.mkdirSync(path.join(root, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'builds.config.js'), "module.exports = { engine: 'cocos' };\n");
+    fs.writeFileSync(path.join(root, 'assets/scripts/game/GameRoot.ts'), SDK_SOURCE);
+    fs.writeFileSync(
+      path.join(root, 'library/import/noise.js'),
+      "import { tracking } from '@playcraft/ads-tracking';\ntracking.onPlaycraftTrackingInit();\n",
+    );
+    fs.writeFileSync(path.join(root, 'src/index.ts'), 'export const unused = 1;\n');
+  });
+
+  after(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('treats @playcraft/adsdk/cjs as an SDK import', () => {
+    assert.equal(hasSDKImport("import * as adsdk from '@playcraft/adsdk/cjs';"), true);
+    assert.equal(hasSDKImport("import { sdk } from '@playcraft/adsdk';"), true);
+  });
+
+  it('detects cocos from builds.config.js and scans assets/scripts only', () => {
+    assert.equal(detectProjectEngine(root), 'cocos');
+    const roots = resolveScanRoots(root, 'cocos').map((dir) => path.relative(root, dir));
+    assert.deepEqual(roots, ['assets/scripts']);
+  });
+
+  it('passes required tracking checks for a cocos SDK wrapper project', () => {
+    const result = validateTracking(root, { engine: 'cocos' });
+    assert.equal(result.stats.engine, 'cocos');
+    assert.deepEqual(result.stats.scanRoots, ['assets/scripts']);
+    assert.equal(result.integrationType, 'sdk');
+    assert.equal(result.success, true, result.errors.join('\n'));
+    assert.equal(result.stats.hasSDKImport, true);
+  });
+
+  it('does not let library ads-tracking imports flip the integration type', () => {
+    const result = validateTracking(root, { engine: 'cocos' });
+    assert.equal(result.stats.hasTrackingImport, false);
+    assert.ok(result.stats.scannedFiles < 10);
+  });
+
+  it('scans src for phaser', () => {
+    const phaserRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'tracking-phaser-'));
+    fs.mkdirSync(path.join(phaserRoot, 'src'), { recursive: true });
+    fs.mkdirSync(path.join(phaserRoot, 'library'), { recursive: true });
+    fs.writeFileSync(path.join(phaserRoot, 'src/main.ts'), SDK_SOURCE.replace('/cjs', ''));
+    fs.writeFileSync(
+      path.join(phaserRoot, 'library/noise.js'),
+      "import { tracking } from '@playcraft/ads-tracking';\n",
+    );
+    try {
+      const result = validateTracking(phaserRoot, { engine: 'phaser' });
+      assert.deepEqual(result.stats.scanRoots, ['src']);
+      assert.equal(result.integrationType, 'sdk');
+      assert.equal(result.success, true, result.errors.join('\n'));
+    } finally {
+      fs.rmSync(phaserRoot, { recursive: true, force: true });
+    }
+  });
+});

package/core/vite.dev.js

@@ -1 +1 @@
-"use strict";module.exports=require("./engines/web/vite.dev.js");
+module.exports = require('./engines/web/vite.dev.js');

package/core/webpack.build.js

@@ -1 +1 @@
-"use strict";module.exports=require("./engines/web/webpack.build.js");
+module.exports = require('./engines/web/webpack.build.js');

package/core/webpack.common.js

@@ -1 +1 @@
-"use strict";module.exports=require("./engines/web/webpack.common.js");
+module.exports = require('./engines/web/webpack.common.js');

package/core/webpack.dev.js

@@ -1 +1 @@
-"use strict";module.exports=require("./engines/web/webpack.dev.js");
+module.exports = require('./engines/web/webpack.dev.js');