@ttmg/cli 0.4.1 → 0.4.2

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';
@@ -449,10 +654,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 +722,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 => {