SuperClaude/.github/workflows/readme-quality-check.yml

name: README Quality Check

on:
  pull_request:
    paths: 
      - 'README*.md'
      - 'Docs/**/*.md'
  push:
    branches: [main, master, develop]
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  readme-quality-check:
    name: Multi-language README Quality Assessment
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'
        
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install requests beautifulsoup4 pyyaml
        
    - name: Create quality checker script
      run: |
        cat > readme_checker.py << 'EOF'
        #!/usr/bin/env python3
        # -*- coding: utf-8 -*-
        """
        SuperClaude多语言README质量检查器
        检查版本同步、链接有效性、结构一致性
        """
        
        import os
        import re
        import requests
        import json
        from pathlib import Path
        from urllib.parse import urljoin
        
        class READMEQualityChecker:
            def __init__(self):
                self.readme_files = ['README.md', 'README-zh.md', 'README-ja.md']
                self.results = {
                    'structure_consistency': [],
                    'link_validation': [],
                    'translation_sync': [],
                    'overall_score': 0
                }
                
            def check_structure_consistency(self):
                """检查结构一致性"""
                print("🔍 检查结构一致性...")
                
                structures = {}
                for file in self.readme_files:
                    if os.path.exists(file):
                        with open(file, 'r', encoding='utf-8') as f:
                            content = f.read()
                            # 提取标题结构
                            headers = re.findall(r'^#{1,6}\s+(.+)$', content, re.MULTILINE)
                            structures[file] = len(headers)
                            
                # 比较结构差异
                line_counts = [structures.get(f, 0) for f in self.readme_files if f in structures]
                if line_counts:
                    max_diff = max(line_counts) - min(line_counts)
                    consistency_score = max(0, 100 - (max_diff * 5))
                    
                    self.results['structure_consistency'] = {
                        'score': consistency_score,
                        'details': structures,
                        'status': 'PASS' if consistency_score >= 90 else 'WARN'
                    }
                    
                    print(f"✅ 结构一致性: {consistency_score}/100")
                    for file, count in structures.items():
                        print(f"   {file}: {count} headers")
                        
            def check_link_validation(self):
                """检查链接有效性"""
                print("🔗 检查链接有效性...")
                
                all_links = {}
                broken_links = []
                
                for file in self.readme_files:
                    if os.path.exists(file):
                        with open(file, 'r', encoding='utf-8') as f:
                            content = f.read()
                            
                        # 提取所有链接
                        links = re.findall(r'\[([^\]]+)\]\(([^)]+)\)', content)
                        all_links[file] = []
                        
                        for text, url in links:
                            link_info = {'text': text, 'url': url, 'status': 'unknown'}
                            
                            # 检查本地文件链接
                            if not url.startswith(('http://', 'https://', '#')):
                                if os.path.exists(url):
                                    link_info['status'] = 'valid'
                                else:
                                    link_info['status'] = 'broken'
                                    broken_links.append(f"{file}: {url}")
                            
                            # HTTP链接检查（简化版）
                            elif url.startswith(('http://', 'https://')):
                                try:
                                    # 只检查几个关键链接，避免过多请求
                                    if any(domain in url for domain in ['github.com', 'pypi.org', 'npmjs.com']):
                                        response = requests.head(url, timeout=10, allow_redirects=True)
                                        link_info['status'] = 'valid' if response.status_code < 400 else 'broken'
                                    else:
                                        link_info['status'] = 'skipped'
                                except:
                                    link_info['status'] = 'error'
                            else:
                                link_info['status'] = 'anchor'
                                
                            all_links[file].append(link_info)
                
                # 计算链接健康度
                total_links = sum(len(links) for links in all_links.values())
                broken_count = len(broken_links)
                link_score = max(0, 100 - (broken_count * 10)) if total_links > 0 else 100
                
                self.results['link_validation'] = {
                    'score': link_score,
                    'total_links': total_links,
                    'broken_links': broken_count,
                    'broken_list': broken_links[:10],  # 最多显示10个
                    'status': 'PASS' if link_score >= 80 else 'FAIL'
                }
                
                print(f"✅ 链接有效性: {link_score}/100")
                print(f"   总链接数: {total_links}")
                print(f"   损坏链接: {broken_count}")
                
            def check_translation_sync(self):
                """检查翻译同步性"""
                print("🌍 检查翻译同步性...")
                
                if not all(os.path.exists(f) for f in self.readme_files):
                    print("⚠️  缺少某些README文件")
                    self.results['translation_sync'] = {
                        'score': 60,
                        'status': 'WARN',
                        'message': '缺少某些README文件'
                    }
                    return
                
                # 检查文件修改时间
                mod_times = {}
                for file in self.readme_files:
                    mod_times[file] = os.path.getmtime(file)
                    
                # 计算时间差异（秒）
                times = list(mod_times.values())
                time_diff = max(times) - min(times)
                
                # 根据时间差评分（7天内修改认为是同步的）
                sync_score = max(0, 100 - (time_diff / (7 * 24 * 3600) * 20))
                
                self.results['translation_sync'] = {
                    'score': int(sync_score),
                    'time_diff_days': round(time_diff / (24 * 3600), 2),
                    'status': 'PASS' if sync_score >= 80 else 'WARN',
                    'mod_times': {f: f"{os.path.getmtime(f):.0f}" for f in self.readme_files}
                }
                
                print(f"✅ 翻译同步性: {int(sync_score)}/100")
                print(f"   最大时间差: {round(time_diff / (24 * 3600), 1)} 天")
                
            def generate_report(self):
                """生成质量报告"""
                print("\n📊 生成质量报告...")
                
                # 计算总分
                scores = [
                    self.results['structure_consistency'].get('score', 0),
                    self.results['link_validation'].get('score', 0),
                    self.results['translation_sync'].get('score', 0)
                ]
                overall_score = sum(scores) // len(scores)
                self.results['overall_score'] = overall_score
                
                # 生成GitHub Actions摘要
                pipe = "|"
                table_header = f"{pipe} 检查项目 {pipe} 分数 {pipe} 状态 {pipe} 详情 {pipe}"
                table_separator = f"{pipe}----------|------|------|------|"
                table_row1 = f"{pipe} 📐 结构一致性 {pipe} {self.results['structure_consistency'].get('score', 0)}/100 {pipe} {self.results['structure_consistency'].get('status', 'N/A')} {pipe} {len(self.results['structure_consistency'].get('details', {}))} 个文件 {pipe}"
                table_row2 = f"{pipe} 🔗 链接有效性 {pipe} {self.results['link_validation'].get('score', 0)}/100 {pipe} {self.results['link_validation'].get('status', 'N/A')} {pipe} {self.results['link_validation'].get('broken_links', 0)} 个损坏链接 {pipe}"
                table_row3 = f"{pipe} 🌍 翻译同步性 {pipe} {self.results['translation_sync'].get('score', 0)}/100 {pipe} {self.results['translation_sync'].get('status', 'N/A')} {pipe} {self.results['translation_sync'].get('time_diff_days', 0)} 天差异 {pipe}"
                
                summary_parts = [
                    "## 📊 README质量检查报告",
                    "",
                    f"### 🏆 总体评分: {overall_score}/100",
                    "",
                    table_header,
                    table_separator,
                    table_row1,
                    table_row2,
                    table_row3,
                    "",
                    "### 📋 详细信息",
                    "",
                    "**结构一致性详情:**"
                ]
                summary = "\n".join(summary_parts)
                
                for file, count in self.results['structure_consistency'].get('details', {}).items():
                    summary += f"\n- `{file}`: {count} 个标题"
                
                if self.results['link_validation'].get('broken_links'):
                    summary += f"\n\n**损坏链接列表:**\n"
                    for link in self.results['link_validation']['broken_list']:
                        summary += f"\n- ❌ {link}"
                
                summary += f"\n\n### 🎯 建议\n"
                
                if overall_score >= 90:
                    summary += "✅ 质量优秀！继续保持。"
                elif overall_score >= 70:
                    summary += "⚠️ 质量良好，有改进空间。"
                else:
                    summary += "🚨 需要改进！请检查上述问题。"
                
                # 写入GitHub Actions摘要
                github_step_summary = os.environ.get('GITHUB_STEP_SUMMARY')
                if github_step_summary:
                    with open(github_step_summary, 'w', encoding='utf-8') as f:
                        f.write(summary)
                
                # 保存详细结果
                with open('readme-quality-report.json', 'w', encoding='utf-8') as f:
                    json.dump(self.results, f, indent=2, ensure_ascii=False)
                
                print("✅ 报告已生成")
                
                # 根据分数决定退出码
                return 0 if overall_score >= 70 else 1
                
            def run_all_checks(self):
                """运行所有检查"""
                print("🚀 开始README质量检查...\n")
                
                self.check_structure_consistency()
                self.check_link_validation() 
                self.check_translation_sync()
                
                exit_code = self.generate_report()
                
                print(f"\n🎯 检查完成！总分: {self.results['overall_score']}/100")
                return exit_code

        if __name__ == "__main__":
            checker = READMEQualityChecker()
            exit_code = checker.run_all_checks()
            exit(exit_code)
        EOF
        
    - name: Run README quality check
      run: python readme_checker.py
      
    - name: Upload quality report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: readme-quality-report
        path: readme-quality-report.json
        retention-days: 30
        
    - name: Comment PR (if applicable)
      if: github.event_name == 'pull_request' && always() && github.event.pull_request.head.repo.full_name == github.repository
      uses: actions/github-script@v7
      with:
        script: |
          const fs = require('fs');
          
          if (fs.existsSync('readme-quality-report.json')) {
            const report = JSON.parse(fs.readFileSync('readme-quality-report.json', 'utf8'));
            
            const score = report.overall_score;
            const emoji = score >= 90 ? '🏆' : score >= 70 ? '✅' : '⚠️';
            
            const comment = `${emoji} **README质量检查结果: ${score}/100**\n\n` +
              `📐 结构一致性: ${report.structure_consistency?.score || 0}/100\n` +
              `🔗 链接有效性: ${report.link_validation?.score || 0}/100\n` +
              `🌍 翻译同步性: ${report.translation_sync?.score || 0}/100\n\n` +
              `查看详细报告请点击 Actions 标签页。`;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });
          }