@ttmg/cli 0.4.1 → 0.4.3

package/dist/scripts/docs/render.js

@@ -1,5 +1,7 @@
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+const childProcess = require('child_process');
 const { pathToFileURL } = require('url');
 
 function parseArgs(argv) {
@@ -16,36 +18,239 @@ function parseArgs(argv) {
 async function loadRecipes(recipesPath) {
   const module = await import(pathToFileURL(recipesPath).href);
   return {
+    schemaVersion: module.schemaVersion || 1,
     recipes: module.recipes || module.default || [],
     locales: module.locales || ['zh-CN', 'en-US'],
     guideTitle: module.guideTitle || 'TikTok 小游戏调试工具使用指南',
+    guideSource: module.guideSource || null,
     guideSections: module.guideSections || {},
     guideFaqs: module.guideFaqs || {},
+    docVersion: module.docVersion || {},
+    documentationContract: module.documentationContract || {},
+    guideReleaseChecks: module.guideReleaseChecks || [],
+    screenshotInventory: module.screenshotInventory || [],
   };
 }
 
-function buildManifest({ recipes, locales, outputDir, guideTitle, guideSections, guideFaqs }) {
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeExec(command, cwd) {
+  try {
+    return childProcess.execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function dropUndefined(value) {
+  if (Array.isArray(value)) {
+    return value.map(dropUndefined);
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, nestedValue]) => nestedValue !== undefined)
+      .map(([key, nestedValue]) => [key, dropUndefined(nestedValue)]),
+  );
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (!value || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(',')}}`;
+}
+
+function createScenarioFingerprint({ schemaVersion, locales, guideTitle, guideSource, recipes }) {
+  return crypto
+    .createHash('sha256')
+    .update(stableStringify({ schemaVersion, locales, guideTitle, guideSource, recipes }))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function screenshotPath(recipe, locale) {
+  return `assets/${recipe.id}.${locale}.png`;
+}
+
+function buildScreenshotIndex({ recipes, locales, outputDir, guideTitle, guideSource, scenarioFingerprint, screenshotInventory }) {
   return {
+    schemaVersion: 1,
     title: guideTitle,
+    guideSource,
+    scenarioFingerprint,
+    generatedAt: new Date().toISOString(),
+    outputDir,
+    screenshotInventory,
+    screenshots: recipes.flatMap(recipe =>
+      locales.map(locale => dropUndefined({
+        id: `${recipe.id}.${locale}`,
+        recipeId: recipe.id,
+        locale,
+        route: recipe.route,
+        page: recipe.page,
+        productArea: recipe.productArea,
+        fixture: recipe.fixture,
+        capture: recipe.capture,
+        doc: recipe.doc,
+        path: screenshotPath(recipe, locale),
+      })),
+    ),
+  };
+}
+
+function buildManifest({
+  schemaVersion,
+  recipes,
+  locales,
+  outputDir,
+  guideTitle,
+  guideSource,
+  guideSections,
+  guideFaqs,
+  scenarioFingerprint,
+  docVersion,
+  documentationContract,
+  guideReleaseChecks,
+  screenshotInventory,
+}) {
+  return {
+    schemaVersion,
+    title: guideTitle,
+    guideSource,
+    docVersion,
+    documentationContract,
+    guideReleaseChecks,
+    screenshotInventory,
+    scenarioFingerprint,
     generatedAt: new Date().toISOString(),
     outputDir,
     locales,
     guideSections,
     guideFaqs,
-    pages: recipes.map(recipe => ({
+    pages: recipes.map(recipe => dropUndefined({
       id: recipe.id,
+      title: recipe.title,
       route: recipe.route,
+      page: recipe.page,
+      productArea: recipe.productArea,
+      fixture: recipe.fixture,
+      capture: recipe.capture,
       captureMode: recipe.captureMode,
       waitFor: recipe.waitFor,
+      doc: recipe.doc,
+      privacy: recipe.privacy,
+      acceptance: recipe.acceptance,
+      updatePolicy: recipe.updatePolicy,
       notes: recipe.notes,
       screenshots: locales.map(locale => ({
         locale,
-        path: `assets/${recipe.id}.${locale}.png`,
+        path: screenshotPath(recipe, locale),
       })),
     })),
   };
 }
 
+function buildDocVersion({
+  repoRoot,
+  outputDir,
+  guideTitle,
+  guideSource,
+  schemaVersion,
+  locales,
+  scenarioFingerprint,
+  docVersion,
+  documentationContract,
+  guideReleaseChecks,
+  screenshotInventory,
+}) {
+  const rootPackage = readJsonIfExists(path.join(repoRoot, 'package.json')) || {};
+  const cliPackage = readJsonIfExists(path.join(repoRoot, 'packages/libs/dev-tools/cli/package.json')) || {};
+  const gitCommit = safeExec('git rev-parse --short HEAD', repoRoot);
+  const gitStatus = safeExec('git status --short', repoRoot);
+
+  return dropUndefined({
+    schemaVersion: 1,
+    id: docVersion.id,
+    status: docVersion.status,
+    title: guideTitle,
+    generatedAt: new Date().toISOString(),
+    outputDir,
+    guideSource,
+    sourceOfTruth: docVersion.sourceOfTruth,
+    publishTiming: docVersion.publishTiming,
+    ownerReviewRequired: docVersion.ownerReviewRequired,
+    scenario: {
+      schemaVersion,
+      scenarioFingerprint,
+      locales,
+      screenshotCount: screenshotInventory.length,
+      screenshotIds: screenshotInventory.map(item => item.id),
+    },
+    packages: {
+      workspace: rootPackage.version,
+      cli: cliPackage.version,
+      ttmgPack: cliPackage.dependencies?.['ttmg-pack'],
+    },
+    git: {
+      commit: gitCommit || undefined,
+      dirty: gitStatus ? true : undefined,
+    },
+    qualityGate: {
+      documentationContract,
+      checks: guideReleaseChecks,
+    },
+    artifacts: {
+      manifest: 'manifest.json',
+      screenshotIndex: 'screenshot-index.json',
+      qualityGate: 'quality-gate.json',
+      guideDraft: 'index.md',
+      screenshotsDir: 'assets/',
+    },
+  });
+}
+
+function buildQualityGate({
+  guideTitle,
+  guideSource,
+  scenarioFingerprint,
+  documentationContract,
+  guideReleaseChecks,
+  screenshotInventory,
+}) {
+  return {
+    schemaVersion: 1,
+    title: guideTitle,
+    guideSource,
+    scenarioFingerprint,
+    generatedAt: new Date().toISOString(),
+    documentationContract,
+    guideReleaseChecks,
+    screenshotInventory,
+  };
+}
+
 function renderRecipeBlock(locale, recipe, headingLevel = 3) {
   const note = recipe.notes[locale];
   const purposeLabel = locale === 'zh-CN' ? '用途' : 'Purpose';
@@ -89,6 +294,7 @@ function renderCommand({ title, description, command }, headingLevel = 3) {
 }
 
 const zhSectionNumbers = ['一', '二', '三', '四', '五', '六', '七', '八', '九', '十'];
+const enSectionNumbers = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X'];
 
 function formatSectionTitle(locale, index, title) {
   if (!index) {
@@ -97,7 +303,7 @@ function formatSectionTitle(locale, index, title) {
   if (locale === 'zh-CN') {
     return `${zhSectionNumbers[index - 1] || index}、${title}`;
   }
-  return `${index}. ${title}`;
+  return `${enSectionNumbers[index - 1] || index}. ${title}`;
 }
 
 function renderGettingStarted(locale, sectionIndex) {
@@ -170,6 +376,7 @@ function renderIntro(locale, sectionIndex) {
       '- 如果你只是想把项目跑起来，先看“开始之前”和“开始调试”。',
       '- 如果你要确认项目配置是否完整，看“项目概览”。',
       '- 如果你要接入登录、分享、广告、内购、直玩卡等平台能力，看“接入助手”。',
+      '- 如果你要优化 Unity Wasm 或了解待开放的非 Unity 子包收集，看“性能优化”。',
       '- 如果你准备提交预览版本，看“上传发布”。',
       '',
     ].join('\n');
@@ -183,6 +390,7 @@ function renderIntro(locale, sectionIndex) {
     '- To get the project running, start with “Before You Start” and “Start Debugging”.',
     '- To verify project setup, read “Project Overview”.',
     '- To integrate login, sharing, ads, IAP, direct-play cards, or other platform capabilities, read “Integration Assistant”.',
+    '- To optimize Unity Wasm or preview the coming-soon non-Unity subpackage flow, read “Performance Optimization”.',
     '- To prepare a preview build, read “Upload & Publish”.',
     '',
   ].join('\n');
@@ -269,6 +477,39 @@ function renderIntegrationAssistantSection({ recipes, locale, sectionIndex }) {
   ].join('\n');
 }
 
+function renderPerformanceOptimizationSection({ recipes, locale, sectionIndex }) {
+  const subpackage = getRecipeById(recipes, 'subpackage-collect');
+  const wasm = getRecipeById(recipes, 'wasm-split');
+
+  if (locale === 'zh-CN') {
+    return [
+      `## ${formatSectionTitle(locale, sectionIndex, '性能优化')}`,
+      '',
+      '### 如何选择',
+      '',
+      '- 非 Unity 小游戏可先了解“子包收集（待开放）”，并阅读[子包收集使用指南](https://bytedance.my.larkoffice.com/docx/MIyMdmzb0oOQAKxNHGNmR5hDyAh)。正式开放后，DevTool 会按真实启动路径采集预下载子包，并生成预加载配置。',
+      '- Unity 小游戏继续使用“Wasm 分包”，将 Wasm 代码拆分为按需加载的子包。',
+      '- 两条链路面向不同运行时，不能混用。当前子包收集仅展示入口和边界，不代表能力已经正式开放。',
+      '',
+      subpackage ? renderRecipeBlock(locale, subpackage, 3) : '',
+      wasm ? renderRecipeBlock(locale, wasm, 3) : '',
+    ].join('\n');
+  }
+
+  return [
+    `## ${formatSectionTitle(locale, sectionIndex, 'Performance Optimization')}`,
+    '',
+    '### Choose the Right Flow',
+    '',
+    '- Non-Unity mini games can preview Subpackage Collection (Coming Soon) and read the [Subpackage Collection Guide](https://bytedance.my.larkoffice.com/docx/MIyMdmzb0oOQAKxNHGNmR5hDyAh). After release, DevTool will capture subpackages downloaded along the real startup path and generate preload configuration.',
+    '- Unity mini games should continue to use Wasm Split to move Wasm code into on-demand subpackages.',
+    '- These flows target different runtimes and are not interchangeable. The current Subpackage Collection page previews the entry and boundaries; it does not mean the feature is generally available.',
+    '',
+    subpackage ? renderRecipeBlock(locale, subpackage, 3) : '',
+    wasm ? renderRecipeBlock(locale, wasm, 3) : '',
+  ].join('\n');
+}
+
 function renderUploadPublishSection({ recipes, locale, sectionIndex }) {
   const upload = getRecipeById(recipes, 'upload-publish');
   const restricted = getRecipeById(recipes, 'upload-game-restricted');
@@ -371,7 +612,8 @@ function renderSidebarModules({ recipes, locale }) {
         recipes: [byId('project-detail')].filter(Boolean),
       }),
       renderIntegrationAssistantSection({ recipes, locale, sectionIndex: 5 }),
-      renderUploadPublishSection({ recipes, locale, sectionIndex: 6 }),
+      renderPerformanceOptimizationSection({ recipes, locale, sectionIndex: 6 }),
+      renderUploadPublishSection({ recipes, locale, sectionIndex: 7 }),
     ].join('\n');
   }
 
@@ -397,7 +639,8 @@ function renderSidebarModules({ recipes, locale }) {
       recipes: [byId('project-detail')].filter(Boolean),
     }),
     renderIntegrationAssistantSection({ recipes, locale, sectionIndex: 5 }),
-    renderUploadPublishSection({ recipes, locale, sectionIndex: 6 }),
+    renderPerformanceOptimizationSection({ recipes, locale, sectionIndex: 6 }),
+    renderUploadPublishSection({ recipes, locale, sectionIndex: 7 }),
   ].join('\n');
 }
 
@@ -414,26 +657,71 @@ function renderFaqSection(title, items = []) {
   ].join('\n');
 }
 
+function renderReferencesSection(locale, sectionIndex) {
+  if (locale === 'zh-CN') {
+    return [
+      `## ${formatSectionTitle(locale, sectionIndex, '更多参考')}`,
+      '',
+      '- [子包收集使用指南](https://bytedance.my.larkoffice.com/docx/MIyMdmzb0oOQAKxNHGNmR5hDyAh)',
+      '- [Unity Wasm 分包指南](https://bytedance.larkoffice.com/wiki/DZDzwzYdDiJpBSkrhcTcWailnuh)',
+      '- [Unity 插件更新说明](https://bytedance.larkoffice.com/wiki/OyGMwHVW9iSeneknlOcc2qb6nUh)',
+      '- [小游戏运行时与 JSAPI 参考](https://bytedance.larkoffice.com/wiki/GQscwDOQSiPxyjkbzyfckh2pnDg)',
+      '',
+    ].join('\n');
+  }
+
+  return [
+    `## ${formatSectionTitle(locale, sectionIndex, 'More References')}`,
+    '',
+    '- [Subpackage Collection Guide](https://bytedance.my.larkoffice.com/docx/MIyMdmzb0oOQAKxNHGNmR5hDyAh)',
+    '- [Unity Wasm Split Guide](https://bytedance.larkoffice.com/wiki/DZDzwzYdDiJpBSkrhcTcWailnuh)',
+    '- [Unity Plugin Update Guide](https://bytedance.larkoffice.com/wiki/OyGMwHVW9iSeneknlOcc2qb6nUh)',
+    '- [Mini-game Runtime and JSAPI Reference](https://bytedance.larkoffice.com/wiki/GQscwDOQSiPxyjkbzyfckh2pnDg)',
+    '',
+  ].join('\n');
+}
+
+function renderNavigation(guideSections = {}) {
+  const zh = ['导读', ...(guideSections['zh-CN'] || []), '常见问题', '更多参考'];
+  const en = ['Overview', ...(guideSections['en-US'] || []), 'FAQ', 'More References'];
+
+  return [
+    '## 选择语言和模块 / Choose Language and Section',
+    '',
+    '- 中文',
+    ...zh.map((item, index) => `  - ${formatSectionTitle('zh-CN', index + 1, item)}`),
+    '- English',
+    ...en.map((item, index) => `  - ${formatSectionTitle('en-US', index + 1, item)}`),
+    '',
+  ].join('\n');
+}
+
 function renderMarkdown({ recipes, guideTitle, guideSections, guideFaqs = {} }) {
-  const zhFaqSection = renderFaqSection(formatSectionTitle('zh-CN', 7, '常见问题'), guideFaqs['zh-CN']);
-  const enFaqSection = renderFaqSection(formatSectionTitle('en-US', 7, 'FAQ'), guideFaqs['en-US']);
+  const zhFaqSection = renderFaqSection(formatSectionTitle('zh-CN', 8, '常见问题'), guideFaqs['zh-CN']);
+  const enFaqSection = renderFaqSection(formatSectionTitle('en-US', 8, 'FAQ'), guideFaqs['en-US']);
 
   return [
     `# ${guideTitle}`,
     '',
+    renderNavigation(guideSections),
+    '# 中文',
+    '',
     renderIntro('zh-CN', 1),
     renderGettingStarted('zh-CN', 2),
     renderSidebarModules({ recipes, locale: 'zh-CN' }),
     '',
     zhFaqSection,
     '',
-    '# TikTok Mini Game Debugging Tool Guide',
+    renderReferencesSection('zh-CN', 9),
+    '# English',
     '',
     renderIntro('en-US', 1),
     renderGettingStarted('en-US', 2),
     renderSidebarModules({ recipes, locale: 'en-US' }),
     '',
     enFaqSection,
+    '',
+    renderReferencesSection('en-US', 9),
   ].join('\n');
 }
 
@@ -449,10 +737,67 @@ async function main() {
     throw new Error('Missing required argument: --output-dir');
   }
 
-  const { recipes, locales, guideTitle, guideSections, guideFaqs } = await loadRecipes(recipesPath);
+  const {
+    schemaVersion,
+    recipes,
+    locales,
+    guideTitle,
+    guideSource,
+    guideSections,
+    guideFaqs,
+    docVersion,
+    documentationContract,
+    guideReleaseChecks,
+    screenshotInventory,
+  } = await loadRecipes(recipesPath);
   fs.mkdirSync(outputDir, { recursive: true });
 
-  const manifest = buildManifest({ recipes, locales, outputDir, guideTitle, guideSections, guideFaqs });
+  const scenarioFingerprint = createScenarioFingerprint({ schemaVersion, recipes, locales, guideTitle, guideSource });
+  const manifest = buildManifest({
+    schemaVersion,
+    recipes,
+    locales,
+    outputDir,
+    guideTitle,
+    guideSource,
+    guideSections,
+    guideFaqs,
+    scenarioFingerprint,
+    docVersion,
+    documentationContract,
+    guideReleaseChecks,
+    screenshotInventory,
+  });
+  const screenshotIndex = buildScreenshotIndex({
+    recipes,
+    locales,
+    outputDir,
+    guideTitle,
+    guideSource,
+    scenarioFingerprint,
+    screenshotInventory,
+  });
+  const docVersionSnapshot = buildDocVersion({
+    repoRoot: process.cwd(),
+    outputDir,
+    guideTitle,
+    guideSource,
+    schemaVersion,
+    locales,
+    scenarioFingerprint,
+    docVersion,
+    documentationContract,
+    guideReleaseChecks,
+    screenshotInventory,
+  });
+  const qualityGate = buildQualityGate({
+    guideTitle,
+    guideSource,
+    scenarioFingerprint,
+    documentationContract,
+    guideReleaseChecks,
+    screenshotInventory,
+  });
   const markdown = renderMarkdown({ recipes, locales, guideTitle, guideSections, guideFaqs });
 
   fs.writeFileSync(
@@ -460,9 +805,24 @@ async function main() {
     `${JSON.stringify(manifest, null, 2)}\n`,
     'utf8',
   );
+  fs.writeFileSync(
+    path.join(outputDir, 'screenshot-index.json'),
+    `${JSON.stringify(screenshotIndex, null, 2)}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(outputDir, 'doc-version.json'),
+    `${JSON.stringify(docVersionSnapshot, null, 2)}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(outputDir, 'quality-gate.json'),
+    `${JSON.stringify(qualityGate, null, 2)}\n`,
+    'utf8',
+  );
   fs.writeFileSync(path.join(outputDir, 'index.md'), `${markdown}\n`, 'utf8');
 
-  console.log(`[ttmg-docs] rendered manifest and markdown into ${outputDir}`);
+  console.log(`[ttmg-docs] rendered manifest, screenshot index, version snapshot, quality gate and markdown into ${outputDir}`);
 }
 
 main().catch(error => {