Component Docs Batcher

/**
 * 组件分析器
 * 分析组件源代码，提取Props、类型、导入等信息
 */

import * as fs from 'fs';
import * as path from 'path';

interface PropInfo {
  name: string;
  type: string;
  description?: string;
  defaultValue?: string;
  required?: boolean;
}

interface TypeInfo {
  name: string;
  properties: PropInfo[];
  description?: string;
}

interface ComponentAnalysis {
  name: string;
  type: 'component' | 'hook' | 'util' | 'type';
  description?: string;
  imports: string[];
  props: PropInfo[];
  types: TypeInfo[];
  examples: string[];
  dependencies: string[];
}

/**
 * 判断组件类型
 */
function detectComponentType(filePath: string, content: string): ComponentAnalysis['type'] {
  const fileName = path.basename(filePath);

  // Hook检测
  if (/^use[A-Z]/.test(fileName) || content.includes('use') && content.includes('useState')) {
    return 'hook';
  }

  // 工具函数检测
  if (content.includes('export function') && !content.includes('React')) {
    return 'util';
  }

  // 类型定义检测
  if (fileName.includes('.d.ts') || content.includes('export interface') || content.includes('export type')) {
    return 'type';
  }

  // 默认为组件
  return 'component';
}

/**
 * 提取导入语句
 */
function extractImports(content: string): string[] {
  const importRegex = /import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"]([^'"]+)['"]/g;
  const imports: string[] = [];
  let match;

  while ((match = importRegex.exec(content)) !== null) {
    if (!imports.includes(match[1])) {
      imports.push(match[1]);
    }
  }

  return imports;
}

/**
 * 提取Props接口
 */
function extractPropsInterface(content: string): PropInfo[] {
  const props: PropInfo[] = [];

  // 查找Props接口定义
  const interfaceRegex = /(?:interface|type)\s+(\w*Props?\w*)\s*(?:extends\s+(\w+))?\s*\{([^}]+)\}/g;
  let match;

  while ((match = interfaceRegex.exec(content)) !== null) {
    const interfaceName = match[1];
    const interfaceBody = match[3];

    // 提取接口属性
    const propertyRegex = /(\w+)\s*(\?)?:\s*([^;,=\n]+)(?:\s*=\s*([^;,]+))?(?:[;,])/g;
    let propMatch;

    while ((propMatch = propertyRegex.exec(interfaceBody)) !== null) {
      props.push({
        name: propMatch[1],
        type: propMatch[3].trim(),
        required: !propMatch[2], // 有?表示可选
        defaultValue: propMatch[4]?.trim()
      });
    }
  }

  return props;
}

/**
 * 提取类型定义
 */
function extractTypes(content: string): TypeInfo[] {
  const types: TypeInfo[] = [];

  // 查找所有接口和类型定义
  const typeRegex = /(?:export\s+)?(?:interface|type)\s+(\w+)\s*(?:extends\s+(\w+))?\s*\{([^}]+)\}/g;
  let match;

  while ((match = typeRegex.exec(content)) !== null) {
    const typeName = match[1];
    const typeBody = match[3];

    // 跳过Props类型（已在props中处理）
    if (typeName.toLowerCase().includes('props')) {
      continue;
    }

    const properties: PropInfo[] = [];
    const propertyRegex = /(\w+)\s*(\?)?:\s*([^;,=\n]+)(?:\s*=\s*([^;,]+))?(?:[;,])/g;
    let propMatch;

    while ((propMatch = propertyRegex.exec(typeBody)) !== null) {
      properties.push({
        name: propMatch[1],
        type: propMatch[3].trim(),
        required: !propMatch[2]
      });
    }

    types.push({
      name: typeName,
      properties
    });
  }

  return types;
}

/**
 * 提取代码示例（从注释中）
 */
function extractExamples(content: string): string[] {
  const examples: string[] = [];

  // 查找 @example 注释
  const exampleRegex = /@example\s+([\s\S]*?)(?=@\w+|\*\/)/g;
  let match;

  while ((match = exampleRegex.exec(content)) !== null) {
    examples.push(match[1].trim());
  }

  return examples;
}

/**
 * 提取组件描述（从注释中）
 */
function extractDescription(content: string): string | undefined {
  // 查找文件顶部的描述注释
  const descRegex = /\/\*\*[\s\S]*?\* @(?:description|brief)\s+([^\n]+)[\s\S]*?\*\//;
  const match = descRegex.exec(content);
  return match?.[1]?.trim();
}

/**
 * 分析组件文件
 */
function analyzeComponent(filePath: string): ComponentAnalysis {
  const content = fs.readFileSync(filePath, 'utf-8');
  const fileName = path.basename(filePath, path.extname(filePath));

  const componentType = detectComponentType(filePath, content);
  const imports = extractImports(content);
  const props = extractPropsInterface(content);
  const types = extractTypes(content);
  const examples = extractExamples(content);
  const description = extractDescription(content);

  // 提取外部依赖（从import中过滤相对路径）
  const dependencies = imports.filter(imp => !imp.startsWith('.'));

  return {
    name: fileName,
    type: componentType,
    description,
    imports,
    props,
    types,
    examples,
    dependencies
  };
}

/**
 * 打印分析结果
 */
function printAnalysis(analysis: ComponentAnalysis): void {
  console.log(`\n📦 组件分析结果:`);
  console.log(`   名称: ${analysis.name}`);
  console.log(`   类型: ${analysis.type}`);
  if (analysis.description) {
    console.log(`   描述: ${analysis.description}`);
  }

  console.log(`\n📥 导入依赖 (${analysis.imports.length}):`);
  analysis.imports.forEach(imp => console.log(`   - ${imp}`));

  console.log(`\n📋 Props (${analysis.props.length}):`);
  analysis.props.forEach(prop => {
    console.log(`   - ${prop.name}${prop.required ? '' : '?'}: ${prop.type}`);
    if (prop.defaultValue) {
      console.log(`     默认值: ${prop.defaultValue}`);
    }
  });

  if (analysis.types.length > 0) {
    console.log(`\n📝 类型定义 (${analysis.types.length}):`);
    analysis.types.forEach(type => {
      console.log(`   - ${type.name} (${type.properties.length} 个属性)`);
    });
  }

  if (analysis.examples.length > 0) {
    console.log(`\n💡 示例代码:`);
    analysis.examples.forEach((ex, i) => {
      console.log(`   示例 ${i + 1}:`);
      console.log(`   ${ex.split('\n').join('\n   ')}`);
    });
  }
}

// CLI 接口
if (require.main === module) {
  const args = process.argv.slice(2);
  const filePath = args[0];

  if (!filePath) {
    console.error('❌ 请提供组件文件路径');
    console.log('用法: npx ts-node analyze-component.ts <component-file-path>');
    process.exit(1);
  }

  if (!fs.existsSync(filePath)) {
    console.error(`❌ 文件不存在: ${filePath}`);
    process.exit(1);
  }

  try {
    console.log(`🔍 分析组件: ${filePath}\n`);
    const analysis = analyzeComponent(filePath);
    printAnalysis(analysis);

    // 输出JSON格式
    if (args.includes('--json')) {
      console.log('\n📄 JSON 输出:');
      console.log(JSON.stringify(analysis, null, 2));
    }
  } catch (error) {
    console.error('❌ 分析失败:', error);
    process.exit(1);
  }
}

export { analyzeComponent, ComponentAnalysis, PropInfo, TypeInfo };

/**
 * TODO生成器
 * 根据组件扫描结果生成todos.md任务清单
 */

import * as fs from 'fs';
import * as path from 'path';
import { scanComponents, ComponentInfo } from './scan-components';

interface TodoItem {
  number: number;
  componentPath: string;
  docPath: string;
  status: 'missing' | 'outdated';
  completed: boolean;
}

/**
 * 生成todos.md内容
 */
function generateTodosMarkdown(components: ComponentInfo[]): string {
  const date = new Date().toLocaleDateString('zh-CN', {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit'
  });

  const missing = components.filter(c => c.status === 'missing');
  const outdated = components.filter(c => c.status === 'outdated');

  let markdown = `# 组件文档更新任务清单

> 生成时间: ${date}
> 总计: ${components.length} 个任务（${missing.length} 个新增，${outdated.length} 个更新）
> 使用git提交历史进行时间对比

---

## 📋 统计信息

- **需要新增文档**: ${missing.length} 个组件
- **需要更新文档**: ${outdated.length} 个组件
- **总任务数**: ${components.length} 个

---

## ✅ 任务列表

`;

  // 生成任务列表
  components.forEach((comp, index) => {
    const number = index + 1;
    const isMissing = comp.status === 'missing';
    const statusIcon = isMissing ? '🆕' : '🔄';
    const statusText = isMissing ? '新增文档' : '更新文档';
    const relativePath = path.relative(process.cwd(), comp.componentPath);

    markdown += `### ${number}. ${statusIcon} ${statusText}: ${path.basename(comp.componentPath)}

\`\`\`
组件路径: ${relativePath}
文档路径: ${path.relative(process.cwd(), comp.docPath)}
状态: ${isMissing ? '文档缺失' : '文档过时'}
组件git提交时间: ${comp.componentMtime.toLocaleString('zh-CN')}
${isMissing ? '' : `文档git提交时间: ${comp.docMtime?.toLocaleString('zh-CN')}`}
\`\`\`

#### 操作步骤

1. [ ] 读取组件源码: \`${relativePath}\`
2. [ ] 分析组件结构（Props、类型、依赖等）
3. [ ] ${isMissing ? '创建新文档' : '更新现有文档'}: \`${path.relative(process.cwd(), comp.docPath)}\`
4. [ ] 验证文档格式是否符合规范
5. [ ] 检查文档完整性（API、类型、示例等）

---

`;
  });

  // 添加使用说明
  markdown += `## 📝 使用说明

1. 按照任务列表顺序处理每个组件
2. 完成一个任务后，在对应的 [ ] 中添加 x 标记为已完成
3. 所有任务完成后，删除此文件

## 📚 文档规范参考

所有组件文档必须遵循以下格式规范：

- **引用方式**: import 方式
- **功能类型**: 工具/组件
- **功能名称**: 组件/工具名称
- **功能描述**: 详细描述和适用场景
- **何时使用**: 使用场景说明
- **使用示例**: 代码示例
- **API**: 完整的API表格（属性名、类型、说明、默认值）
- **类型描述**: TypeScript类型定义表格
- **主题变量**: CSS主题变量（如有）

`;

  return markdown;
}

/**
 * 写入todos.md文件
 */
function writeTodosFile(content: string, outputPath: string = 'todos.md'): void {
  fs.writeFileSync(outputPath, content, 'utf-8');
  console.log(`✅ 已生成任务清单: ${outputPath}`);
}

// CLI 接口
if (require.main === module) {
  const args = process.argv.slice(2);
  const rootDir = args[0] || process.cwd();
  const outputPath = args[1] || path.join(rootDir, 'todos.md');

  console.log(`🔍 扫描组件中...`);

  try {
    const components = scanComponents({ rootDir });

    if (components.length === 0) {
      console.log(`✅ 所有组件文档都是最新的，无需更新！`);
      process.exit(0);
    }

    console.log(`📝 生成任务清单中...\n`);
    const content = generateTodosMarkdown(components);
    writeTodosFile(content, outputPath);

    console.log(`\n🎉 任务清单生成完成！`);
    console.log(`   - 文件位置: ${outputPath}`);
    console.log(`   - 任务数量: ${components.length}`);
    console.log(`\n💡 下一步: 打开 todos.md 查看详细任务列表\n`);

  } catch (error) {
    console.error('❌ 生成失败:', error);
    process.exit(1);
  }
}

export { generateTodosMarkdown, writeTodosFile, TodoItem };

/**
 * 组件文档扫描器
 * 扫描项目中的组件文件，对比文档更新时间，识别需要更新或新增文档的组件
 * 使用git提交历史获取准确的文件修改时间
 */

import * as fs from 'fs';
import * as path from 'path';
import { execSync } from 'child_process';

interface ComponentInfo {
  componentPath: string;
  docPath: string;
  componentMtime: Date;
  docMtime: Date | null;
  status: 'missing' | 'outdated' | 'current';
}

interface ScanOptions {
  rootDir: string;
  extensions?: string[];
  docFileName?: string; // 文档文件名（默认为 index.zh-CN.md）
  excludeDirs?: string[];
  excludeFiles?: string[]; // 排除的文件模式
}

/**
 * 判断文件是否应该被排除
 */
function shouldExcludeFile(fileName: string, excludePatterns: string[]): boolean {
  return excludePatterns.some(pattern => {
    // 支持简单的通配符匹配
    const regex = new RegExp(pattern.replace('*', '.*'));
    return regex.test(fileName);
  });
}

/**
 * 获取文件的git最后提交时间
 * @param filePath 文件路径
 * @returns 最后提交时间的Date对象，如果文件不在git历史中则返回null
 */
function getGitLastModifiedTime(filePath: string): Date | null {
  try {
    // 从文件所在目录开始向上查找git仓库根目录
    let currentDir = path.dirname(filePath);
    let gitRoot: string | null = null;

    // 向上查找.git目录，最多查找10层
    for (let i = 0; i < 10; i++) {
      const gitDir = path.join(currentDir, '.git');
      if (fs.existsSync(gitDir)) {
        gitRoot = currentDir;
        break;
      }

      const parentDir = path.dirname(currentDir);
      if (parentDir === currentDir) {
        // 已到达根目录
        break;
      }
      currentDir = parentDir;
    }

    if (!gitRoot) {
      // 文件不在git仓库中
      return null;
    }

    const gitDirPath = path.join(gitRoot, '.git');

    // 检查文件是否被git跟踪（使用绝对路径）
    try {
      execSync(
        `git --git-dir="${gitDirPath}" --work-tree="${gitRoot}" ls-files --error-unmatch "${filePath}"`,
        {
          encoding: 'utf-8',
          stdio: ['pipe', 'pipe', 'ignore']
        }
      );
    } catch {
      // 文件不在git跟踪中（可能是新文件）
      return null;
    }

    // 获取文件的最后提交时间戳（Unix时间戳，秒）
    const timestamp = execSync(
      `git --git-dir="${gitDirPath}" --work-tree="${gitRoot}" log -1 --format=%ct -- "${filePath}"`,
      {
        encoding: 'utf-8',
        stdio: ['pipe', 'pipe', 'ignore']
      }
    ).trim();

    if (!timestamp) {
      return null;
    }

    // 转换为Date对象（秒转毫秒）
    return new Date(parseInt(timestamp) * 1000);
  } catch (error) {
    // 获取git时间失败，返回null
    return null;
  }
}

/**
 * 扫描目录下的组件文件
 */
function scanComponents(options: ScanOptions): ComponentInfo[] {
  const {
    rootDir,
    extensions = ['.tsx', '.jsx'], // 默认只扫描组件文件，不包括 .ts/.js
    docFileName = 'index.zh-CN.md',
    excludeDirs = ['node_modules', 'dist', 'build', '.git', 'styles'],
    excludeFiles = ['index.ts', 'index.tsx', 'index.js', 'index.jsx', '*.store.ts', '*.store.js', 'use*.ts', 'use*.js']
  } = options;

  const components: ComponentInfo[] = [];

  /**
   * 扫描组件目录（一级子目录）
   */
  function scanComponentDirs(rootDir: string) {
    const entries = fs.readdirSync(rootDir, { withFileTypes: true });

    for (const entry of entries) {
      const componentDir = path.join(rootDir, entry.name);

      // 只处理一级子目录
      if (!entry.isDirectory()) {
        continue;
      }

      // 跳过排除的目录
      if (excludeDirs.includes(entry.name)) {
        continue;
      }

      // 在组件目录中查找主要的组件文件
      const files = fs.readdirSync(componentDir);
      const mainComponentFile = files.find(file => {
        // 匹配与目录名同名的 .tsx 或 .jsx 文件
        const baseName = path.basename(file, path.extname(file));
        const ext = path.extname(file);
        const isMainComponent = baseName.toLowerCase() === entry.name.toLowerCase() && extensions.includes(ext);
        const notExcluded = !shouldExcludeFile(file, excludeFiles);
        return isMainComponent && notExcluded;
      });

      if (mainComponentFile) {
        const componentPath = path.join(componentDir, mainComponentFile);
        const docPath = path.join(componentDir, docFileName);

        // 使用git获取组件文件修改时间
        const componentMtime = getGitLastModifiedTime(componentPath);

        // 如果组件文件没有git历史（新文件），使用文件系统时间作为备选
        const componentTime = componentMtime || fs.statSync(componentPath).mtime;

        // 检查文档是否存在
        let docMtime: Date | null = null;
        let status: ComponentInfo['status'] = 'missing';

        if (fs.existsSync(docPath)) {
          // 使用git获取文档修改时间
          const gitDocTime = getGitLastModifiedTime(docPath);

          // 如果文档没有git历史（新文件），使用文件系统时间作为备选
          docMtime = gitDocTime || fs.statSync(docPath).mtime;

          // 比较时间：组件比文档新则需要更新
          if (componentTime > docMtime) {
            status = 'outdated';
          } else {
            status = 'current';
          }
        }

        // 只记录需要更新或新增的组件
        if (status !== 'current') {
          components.push({
            componentPath,
            docPath,
            componentMtime: componentTime,
            docMtime,
            status
          });
        }
      }
    }
  }

  scanComponentDirs(rootDir);
  return components;
}

/**
 * 打印扫描结果
 */
function printResults(components: ComponentInfo[]) {
  const missing = components.filter(c => c.status === 'missing').length;
  const outdated = components.filter(c => c.status === 'outdated').length;

  console.log(`\n📊 扫描结果:`);
  console.log(`   - 需要新增文档: ${missing} 个组件`);
  console.log(`   - 需要更新文档: ${outdated} 个组件`);
  console.log(`   - 总计: ${components.length} 个组件`);
  console.log(`   ℹ️  使用git提交历史进行时间对比\n`);

  if (components.length > 0) {
    console.log(`📝 组件列表:`);
    components.forEach((comp, index) => {
      const statusIcon = comp.status === 'missing' ? '❌' : '⚠️';
      const statusText = comp.status === 'missing' ? '缺失' : '过时';
      const componentName = path.basename(path.dirname(comp.componentPath));
      console.log(`   ${index + 1}. ${statusIcon} ${componentName}`);
      console.log(`      组件文件: ${path.basename(comp.componentPath)}`);
      console.log(`      状态: ${statusText}`);
      console.log(`      组件git提交时间: ${comp.componentMtime.toLocaleString('zh-CN')}`);
      if (comp.docMtime) {
        console.log(`      文档git提交时间: ${comp.docMtime.toLocaleString('zh-CN')}`);
      }
      console.log('');
    });
  }
}

// CLI 接口
if (require.main === module) {
  const args = process.argv.slice(2);
  const rootDir = args[0] || process.cwd();

  console.log(`🔍 开始扫描组件...`);
  console.log(`   根目录: ${rootDir}\n`);

  try {
    const components = scanComponents({ rootDir });
    printResults(components);

    // 输出JSON格式供后续处理
    if (args.includes('--json')) {
      console.log('\n📄 JSON 输出:');
      console.log(JSON.stringify(components, null, 2));
    }
  } catch (error) {
    console.error('❌ 扫描失败:', error);
    process.exit(1);
  }
}

export { scanComponents, ComponentInfo, ScanOptions };