@playcraft/devkit 1.0.26 → 1.0.28

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

@@ -1,6 +1,9 @@
-"use strict";const{validateTracking,printValidationResult}=require("./tracking-validator.js");// ============================================================
+const { validateTracking, printValidationResult } = require('./tracking-validator.js');
+
+// ============================================================
 // 检查器注册表
 // ============================================================
+
 /**
  * 检查器定义
  * @typedef {Object} Checker
@@ -8,21 +11,145 @@
  * @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;// ============================================================
+ */
+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('tracking', {
+  name: '埋点验证',
+  description: '验证项目中是否正确调用了所有必须的埋点方法',
+  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 
+        ? '✅ 埋点验证通过' 
+        : `❌ 埋点验证失败：缺少 ${result.errors.length} 个必须的埋点方法`,
+      data: result
+    };
+  }
+});
+
+/**
+ * 主题名称检查器
+ * 校验本次构建涉及的主题名称长度是否超过限制（不超过 50 个字符）。
+ * 主题名称过长可能导致下游文件名 / 目录名 / COS Key 超出系统或第三方平台限制。
+ *
+ * 分两种情况校验：
+ * 1. 主题名称自身长度（无论是否拼接渠道名都会超限的情况）。
+ * 2. 「主题名_渠道名」组合后的长度（对应批量构建产物的第二级目录名 / zip 文件名）。
+ *    渠道名可能带有锁定 UI 等后缀变体（如 google_L / google_P），
+ *    因此必须以传入的 options.channels 实际渠道列表为准逐一比对，
+ *    而不能只校验主题名称本身。
+ */
+checkers.set('themeName', {
+  name: '主题名称检查',
+  description: '验证主题名称、以及「主题名_渠道名」组合后的长度是否超过限制（不超过 50 个字符）',
+  enabled: true,
+  validator: (projectRoot, options = {}) => {
+    const MAX_LENGTH = 50;
+    const themeNames = Array.isArray(options.themes)
+      ? options.themes.filter(name => typeof name === 'string' && name.length > 0)
+      : [];
+    const channelNames = Array.isArray(options.channels)
+      ? options.channels.filter(name => typeof name === 'string' && name.length > 0)
+      : [];
+
+    if (themeNames.length === 0) {
+      return {
+        success: true,
+        message: 'ℹ️  未提供主题名称，跳过主题名称检查'
+      };
+    }
+
+    // 情况一：主题名称自身已超过限制（拼不拼渠道名都会超）
+    const bareInvalidThemes = themeNames.filter(name => name.length > MAX_LENGTH);
+    const bareInvalidThemeSet = new Set(bareInvalidThemes);
+
+    // 情况二：主题名称自身未超限，但拼接渠道名（含锁定 UI 后缀，如 google_L / google_P）后超限
+    const combinedViolations = [];
+    if (channelNames.length > 0) {
+      themeNames.forEach(theme => {
+        if (bareInvalidThemeSet.has(theme)) return; // 已在情况一中报告，避免重复
+
+        channelNames.forEach(channel => {
+          const combined = `${theme}_${channel}`;
+          if (combined.length > MAX_LENGTH) {
+            combinedViolations.push({
+              theme,
+              channel,
+              combined,
+              length: combined.length,
+              exceededBy: combined.length - MAX_LENGTH
+            });
+          }
+        });
+      });
+    }
+
+    if (bareInvalidThemes.length === 0 && combinedViolations.length === 0) {
+      return {
+        success: true,
+        message: channelNames.length > 0
+          ? `✅ 主题名称检查通过（共 ${themeNames.length} 个主题 × ${channelNames.length} 个渠道，「主题名_渠道名」组合均未超过 ${MAX_LENGTH} 个字符）`
+          : `✅ 主题名称检查通过（共 ${themeNames.length} 个主题，均未超过 ${MAX_LENGTH} 个字符）`
+      };
+    }
+
+    const lines = [];
+
+    if (bareInvalidThemes.length > 0) {
+      lines.push('主题名称自身已超过长度限制：');
+      bareInvalidThemes.forEach(name => {
+        lines.push(`    - "${name}" (${name.length} 个字符，超出 ${name.length - MAX_LENGTH} 个字符)`);
+      });
+    }
+
+    if (combinedViolations.length > 0) {
+      lines.push('主题名称本身未超限，但与渠道名拼接后（第二级输出目录名 / zip 文件名）超过长度限制：');
+      combinedViolations.forEach(v => {
+        lines.push(
+          `    - 主题 "${v.theme}" + 渠道 "${v.channel}" → "${v.combined}" ` +
+          `(${v.length} 个字符，超出 ${v.exceededBy} 个字符)`
+        );
+      });
+      lines.push('    提示：部分渠道可能带有锁定 UI 后缀（如 google_L / google_P），拼接后长度会更长，请一并纳入考量。');
+    }
+
+    return {
+      success: false,
+      message: `❌ 主题名称检查失败：\n${lines.join('\n')}`,
+      data: { bareInvalidThemes, combinedViolations, maxLength: MAX_LENGTH }
+    };
+  }
+});
+
+// 预留：未来可添加更多检查器
 // checkers.set('assets', {
 //   name: '资源检查',
 //   description: '验证项目资源文件的完整性和规范性',
@@ -32,6 +159,7 @@
 //     return { success: true, message: '资源检查通过' };
 //   }
 // });
+
 // checkers.set('config', {
 //   name: '配置检查',
 //   description: '验证项目配置文件的正确性',
@@ -41,23 +169,54 @@
 //     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)}/**
+ */
+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}`)}}/**
+ */
+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}))}// ============================================================
+ */
+function listCheckers() {
+  return Array.from(checkers.entries()).map(([id, checker]) => ({
+    id,
+    name: checker.name,
+    description: checker.description,
+    enabled: checker.enabled
+  }));
+}
+
+// ============================================================
 // 执行检查
 // ============================================================
+
 /**
  * 执行所有已启用的检查器
  * @param {string} projectRoot - 项目根目录
@@ -67,23 +226,140 @@
  * @param {boolean} [options.verbose] - 详细输出
  * @param {boolean} [options.showDetails] - 显示详细报告
  * @param {boolean} [options.failFast] - 遇到错误立即停止
+ * @param {string[]} [options.themes] - 本次构建涉及的主题名称列表（供 themeName 检查器使用）
+ * @param {string[]} [options.channels] - 本次构建涉及的渠道名称列表（供 themeName 检查器校验「主题名_渠道名」组合长度，可包含锁定 UI 后缀如 google_L / google_P）
  * @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}}/**
+ */
+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' + '═'.repeat(70));
+  console.log('🔍 编译前检查');
+  console.log('═'.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⚠️  没有启用的检查器');
+    console.log('═'.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⚠️  failFast 模式：检测到失败，终止后续检查');
+          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' + '═'.repeat(70));
+  console.log('📊 检查总结');
+  console.log('═'.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✅ 所有检查通过，可以继续编译！');
+  } else {
+    console.log('\n❌ 部分检查失败，请修复后再编译。');
+  }
+
+  console.log('═'.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))}// ============================================================
+ */
+async function runTrackingCheck(projectRoot, options = {}) {
+  const checker = checkers.get('tracking');
+  if (!checker) {
+    throw new Error('埋点检查器未注册');
+  }
+
+  return await Promise.resolve(checker.validator(projectRoot, options));
+}
+
+// ============================================================
 // 导出
 // ============================================================
-module.exports={// 主要函数
-runPreBuildChecks,runTrackingCheck,// 检查器管理
-registerChecker,toggleChecker,listCheckers,// 内部访问（供高级用户）
-checkers};
+
+module.exports = {
+  // 主要函数
+  runPreBuildChecks,
+  runTrackingCheck,
+
+  // 检查器管理
+  registerChecker,
+  toggleChecker,
+  listCheckers,
+
+  // 内部访问（供高级用户）
+  checkers
+};