@waoooo/claude-skills 1.0.0

package/skills/roadmap-docs-generate/scripts/json-to-mdx.ts

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+/**
+ * Convert JSON planning files to MDX documentation format
+ * 
+ * This script converts:
+ * - roadmap.json → ROADMAP.mdx
+ * - global-todo.json → TODO.mdx
+ * 
+ * Uses template files from assets/templates/ with {{variable}} placeholders
+ * 
+ * Usage:
+ *   npx tsx json-to-mdx.ts \
+ *     --roadmap <roadmap.json> \
+ *     --todo <global-todo.json> \
+ *     --output <output-dir>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Load project config
+const projectRoot = path.resolve(__dirname, '../../../..');
+const projectConfigPath = path.join(projectRoot, 'project.config.json');
+const projectConfig = JSON.parse(fs.readFileSync(projectConfigPath, 'utf-8'));
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface RoadmapData {
+  version: string;
+  generatedAt: string;
+  summary: {
+    totalTasks: number;
+    completedTasks: number;
+    inProgressTasks: number;
+    pendingTasks: number;
+    totalEstimatedHours: number;
+    completedHours: number;
+    remainingHours: number;
+  };
+  jobs: Array<{
+    jobId: string;
+    name: string;
+    status: string;
+    createdAt: string;
+    progress: {
+      totalTasks: number;
+      completed: number;
+      inProgress: number;
+      pending: number;
+      percentage: number;
+    };
+    estimatedHours: number;
+    remainingHours: number;
+  }>;
+  timeline: Array<{
+    date: string;
+    jobs: string[];
+    tasksCompleted: number;
+    hoursSpent: number;
+  }>;
+  milestones: Array<{
+    name: string;
+    targetDate: string;
+    description?: string;
+    completed?: boolean;
+  }>;
+}
+
+interface TodoData {
+  version: string;
+  generatedAt: string;
+  summary: {
+    totalTasks: number;
+    highPriority: number;
+    mediumPriority: number;
+    lowPriority: number;
+  };
+  tasks: Array<{
+    taskId: string;
+    jobId: string;
+    jobName: string;
+    title: string;
+    priority: string;
+    status: string;
+    estimatedHours: number;
+    dependencies: string[];
+    blockedBy: string[];
+    canStartNow: boolean;
+  }>;
+  readyToStart: string[];
+  blocked: string[];
+}
+
+// ============================================================================
+// CLI Arguments
+// ============================================================================
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result: any = {};
+
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i].replace('--', '');
+    const value = args[i + 1];
+    result[key] = value;
+  }
+
+  return {
+    roadmapPath: result.roadmap || 'exports/generated/roadmap.json',
+    todoPath: result.todo || 'exports/generated/global-todo.json',
+    outputDir: result.output || path.join(projectConfig.defaults.docsPath, 'planning'),
+  };
+}
+
+// ============================================================================
+// Template Loading
+// ============================================================================
+
+function loadTemplate(templateName: string): string {
+  const templatePath = path.join(__dirname, '../assets/templates', templateName);
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template not found: ${templatePath}`);
+  }
+  return fs.readFileSync(templatePath, 'utf-8');
+}
+
+// ============================================================================
+// Variable Replacement
+// ============================================================================
+
+function replaceVariables(template: string, variables: Record<string, string>): string {
+  let result = template;
+  for (const [key, value] of Object.entries(variables)) {
+    const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+    result = result.replace(regex, value);
+  }
+  return result;
+}
+
+// ============================================================================
+// ROADMAP Generation
+// ============================================================================
+
+function generateJobCards(jobs: RoadmapData['jobs']): string {
+  const statusEmoji: Record<string, string> = {
+    pending: '⏳',
+    in_progress: '🔄',
+    completed: '✅',
+    failed: '❌'
+  };
+
+  return jobs.map(job => {
+    return `  <Card title="${job.name}" icon="briefcase" href="/planning/${job.name}">
+    ${statusEmoji[job.status] || '⏳'} **状态**: ${job.status}
+    
+    **进度**: ${job.progress.percentage}% (${job.progress.completed}/${job.progress.totalTasks} 任务完成)
+    **预计工时**: ${job.estimatedHours}h
+    **剩余工时**: ${job.remainingHours}h
+    **创建时间**: ${job.createdAt.slice(0, 10)}
+  </Card>`;
+  }).join('\n\n');
+}
+
+function generateTimeline(timeline: RoadmapData['timeline']): string {
+  if (!timeline || timeline.length === 0) {
+    return '暂无时间线数据';
+  }
+
+  return timeline.map(item => {
+    return `### ${item.date}
+
+- **任务完成**: ${item.tasksCompleted} 个
+- **工时消耗**: ${item.hoursSpent}h
+- **相关 Job**: ${item.jobs.join(', ')}`;
+  }).join('\n\n');
+}
+
+function generateMilestones(milestones: RoadmapData['milestones']): string {
+  if (!milestones || milestones.length === 0) {
+    return '暂无里程碑数据';
+  }
+
+  return milestones.map(milestone => {
+    const status = milestone.completed ? '✅' : '⏳';
+    return `### ${status} ${milestone.name}
+
+- **目标日期**: ${milestone.targetDate}
+${milestone.description ? `- **说明**: ${milestone.description}` : ''}`;
+  }).join('\n\n');
+}
+
+function generateRoadmapMdx(roadmapData: RoadmapData): string {
+  const template = loadTemplate('ROADMAP.mdx');
+
+  const { summary } = roadmapData;
+  const completionRate = summary.totalTasks > 0
+    ? Math.floor((summary.completedTasks / summary.totalTasks) * 100)
+    : 0;
+
+  const remainingDays = Math.ceil(summary.remainingHours / 8);
+
+  const variables = {
+    lastUpdated: new Date().toISOString().slice(0, 10),
+    version: roadmapData.version,
+    totalTasks: summary.totalTasks.toString(),
+    completedTasks: summary.completedTasks.toString(),
+    inProgressTasks: summary.inProgressTasks.toString(),
+    pendingTasks: summary.pendingTasks.toString(),
+    completionRate: completionRate.toString(),
+    totalEstimatedHours: summary.totalEstimatedHours.toString(),
+    completedHours: summary.completedHours.toString(),
+    remainingHours: summary.remainingHours.toString(),
+    remainingDays: remainingDays.toString(),
+    timeline: generateTimeline(roadmapData.timeline),
+    milestones: generateMilestones(roadmapData.milestones),
+    generatedAt: new Date().toISOString().slice(0, 10),
+    sourceGeneratedAt: roadmapData.generatedAt,
+  };
+
+  return replaceVariables(template, variables);
+}
+
+// ============================================================================
+// TODO Generation
+// ============================================================================
+
+function generateTaskSection(tasks: TodoData['tasks'], priority: string): string {
+  const filtered = tasks.filter(t => t.priority === priority);
+  
+  if (filtered.length === 0) {
+    return '';
+  }
+
+  const priorityEmoji: Record<string, string> = {
+    high: '🔴',
+    medium: '🟡',
+    low: '🟢'
+  };
+
+  const priorityName: Record<string, string> = {
+    high: '高优先级',
+    medium: '中优先级',
+    low: '低优先级'
+  };
+
+  const taskList = filtered.map(task => {
+    const blockedText = task.blockedBy.length > 0 
+      ? ` 🚫 **被阻塞**: ${task.blockedBy.join(', ')}`
+      : '';
+    
+    return `### ${task.title}
+
+- **Job**: ${task.jobName}
+- **预计工时**: ${task.estimatedHours}h
+- **状态**: ${task.status}${blockedText}`;
+  }).join('\n\n');
+
+  return `## ${priorityEmoji[priority]} ${priorityName[priority]} (${filtered.length} 个任务)
+
+${taskList}`;
+}
+
+function generateReadyToStartSection(tasks: TodoData['tasks'], readyIds: string[]): string {
+  const readyTasks = tasks.filter(t => readyIds.includes(t.taskId));
+  
+  if (readyTasks.length === 0) {
+    return '## ✅ 可立即开始的任务\n\n暂无可立即开始的任务';
+  }
+
+  const taskList = readyTasks.map(task => {
+    return `### ${task.title}
+
+- **Job**: ${task.jobName}
+- **优先级**: ${task.priority}
+- **预计工时**: ${task.estimatedHours}h`;
+  }).join('\n\n');
+
+  return `## ✅ 可立即开始的任务 (${readyTasks.length} 个)
+
+${taskList}`;
+}
+
+function generateBlockedSection(tasks: TodoData['tasks'], blockedIds: string[]): string {
+  const blockedTasks = tasks.filter(t => blockedIds.includes(t.taskId));
+  
+  if (blockedTasks.length === 0) {
+    return '## 🚫 被阻塞的任务\n\n暂无被阻塞的任务';
+  }
+
+  const taskList = blockedTasks.map(task => {
+    return `### ${task.title}
+
+- **Job**: ${task.jobName}
+- **优先级**: ${task.priority}
+- **被阻塞原因**: ${task.blockedBy.join(', ')}`;
+  }).join('\n\n');
+
+  return `## 🚫 被阻塞的任务 (${blockedTasks.length} 个)
+
+${taskList}`;
+}
+
+function generateTodoMdx(todoData: TodoData): string {
+  const template = loadTemplate('TODO.mdx');
+
+  const { summary, tasks } = todoData;
+
+  // Group tasks by Job
+  const tasksByJob: Record<string, TodoData['tasks']> = {};
+  for (const task of tasks) {
+    if (!tasksByJob[task.jobName]) {
+      tasksByJob[task.jobName] = [];
+    }
+    tasksByJob[task.jobName].push(task);
+  }
+
+  // Generate Job sections
+  const jobSections = Object.entries(tasksByJob).map(([jobName, jobTasks]) => {
+    // Group by priority
+    const highPriority = jobTasks.filter(t => t.priority === 'high');
+    const mediumPriority = jobTasks.filter(t => t.priority === 'medium');
+    const lowPriority = jobTasks.filter(t => t.priority === 'low');
+
+    const generateTaskList = (tasks: TodoData['tasks']) => {
+      return tasks.map(task => {
+        const checkbox = task.status === 'completed' ? '[x]' : '[ ]';
+        const blockedText = task.blockedBy.length > 0 ? ' 🚫 被阻塞' : '';
+        return `- ${checkbox} ${task.title} (${task.estimatedHours}h)${blockedText}`;
+      }).join('\n');
+    };
+
+    let sections = [];
+
+    if (highPriority.length > 0) {
+      sections.push(`### 🔴 高优先级\n\n${generateTaskList(highPriority)}`);
+    }
+
+    if (mediumPriority.length > 0) {
+      sections.push(`### 🟡 中优先级\n\n${generateTaskList(mediumPriority)}`);
+    }
+
+    if (lowPriority.length > 0) {
+      sections.push(`### 🟢 低优先级\n\n${generateTaskList(lowPriority)}`);
+    }
+
+    return `## 📋 ${jobName}\n\n${sections.join('\n\n---\n\n')}`;
+  }).join('\n\n---\n\n');
+
+  const variables = {
+    lastUpdated: new Date().toISOString().slice(0, 10),
+    version: todoData.version,
+    totalTasks: summary.totalTasks.toString(),
+    highPriority: summary.highPriority.toString(),
+    mediumPriority: summary.mediumPriority.toString(),
+    lowPriority: summary.lowPriority.toString(),
+    jobSections: jobSections,
+    generatedAt: new Date().toISOString().slice(0, 10),
+    sourceGeneratedAt: todoData.generatedAt,
+  };
+
+  return replaceVariables(template, variables);
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('🚀 Converting JSON to MDX...\n');
+
+  const { roadmapPath, todoPath, outputDir } = parseArgs();
+
+  // Step 1: Load JSON files
+  console.log('📥 Step 1/3: Loading JSON files...');
+  
+  let roadmapData: RoadmapData | null = null;
+  let todoData: TodoData | null = null;
+
+  if (fs.existsSync(roadmapPath)) {
+    roadmapData = JSON.parse(fs.readFileSync(roadmapPath, 'utf-8'));
+    console.log(`  ✅ Loaded: ${roadmapPath}`);
+  } else {
+    console.log(`  ⚠️  Not found: ${roadmapPath}`);
+  }
+
+  if (fs.existsSync(todoPath)) {
+    todoData = JSON.parse(fs.readFileSync(todoPath, 'utf-8'));
+    console.log(`  ✅ Loaded: ${todoPath}`);
+  } else {
+    console.log(`  ⚠️  Not found: ${todoPath}`);
+  }
+
+  console.log('');
+
+  // Step 2: Generate MDX
+  console.log('📝 Step 2/3: Generating MDX...');
+
+  const outputs: Array<{ path: string; content: string }> = [];
+
+  if (roadmapData) {
+    const roadmapMdx = generateRoadmapMdx(roadmapData);
+    outputs.push({
+      path: path.join(outputDir, 'ROADMAP.mdx'),
+      content: roadmapMdx,
+    });
+    console.log('  ✅ Generated ROADMAP.mdx');
+  }
+
+  if (todoData) {
+    const todoMdx = generateTodoMdx(todoData);
+    outputs.push({
+      path: path.join(outputDir, 'TODO.mdx'),
+      content: todoMdx,
+    });
+    console.log('  ✅ Generated TODO.mdx');
+  }
+
+  console.log('');
+
+  // Step 3: Write files
+  console.log('💾 Step 3/3: Writing files...');
+
+  for (const output of outputs) {
+    // outputDir is relative to project root
+    const absolutePath = path.resolve(projectRoot, output.path);
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+    fs.writeFileSync(absolutePath, output.content, 'utf-8');
+    console.log(`  ✅ Written: ${absolutePath}`);
+  }
+
+  console.log('');
+  console.log('🎉 Done!');
+  console.log(`\n📂 Output directory: ${path.resolve(projectRoot, outputDir)}`);
+}
+
+main().catch(error => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});