super-dev 2.0.0__py3-none-any.whl

super_dev/reviewers/quality_gate.py

@@ -0,0 +1,964 @@
+"""
+质量门禁检查器 - 确保交付物达到质量标准
+
+开发：Excellent（11964948@qq.com）
+功能：多维度质量评分和门禁检查
+作用：按场景阈值（或自定义阈值）评估是否通过质量门禁
+创建时间：2025-12-30
+"""
+
+import json
+import shutil
+import subprocess  # nosec B404
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from defusedxml import ElementTree
+
+from .redteam import RedTeamReport
+
+
+class CheckStatus(Enum):
+    """检查状态"""
+    PASSED = "passed"
+    FAILED = "failed"
+    WARNING = "warning"
+
+
+@dataclass
+class QualityCheck:
+    """质量检查项"""
+    name: str
+    category: str  # documentation, security, performance, testing, code_quality
+    description: str
+    status: CheckStatus
+    score: int  # 0-100
+    weight: float = 1.0  # 权重，用于计算加权总分
+    details: str = ""
+
+
+@dataclass
+class QualityGateResult:
+    """质量门禁结果"""
+    passed: bool
+    total_score: int
+    weighted_score: float
+    checks: list[QualityCheck] = field(default_factory=list)
+    critical_failures: list[str] = field(default_factory=list)
+    recommendations: list[str] = field(default_factory=list)
+    scenario: str = "1-N+1"  # 场景类型: "0-1" 或 "1-N+1"
+
+    @property
+    def passed_checks(self) -> list[QualityCheck]:
+        return [c for c in self.checks if c.status == CheckStatus.PASSED]
+
+    @property
+    def failed_checks(self) -> list[QualityCheck]:
+        return [c for c in self.checks if c.status == CheckStatus.FAILED]
+
+    @property
+    def warning_checks(self) -> list[QualityCheck]:
+        return [c for c in self.checks if c.status == CheckStatus.WARNING]
+
+    def to_markdown(self) -> str:
+        """生成 Markdown 报告"""
+        status_icon = "通过" if self.passed else "未通过"
+        status_color = "green" if self.passed else "red"
+
+        lines = [
+            "# 质量门禁报告",
+            "",
+            f"**场景**: {self.scenario} ({'0-1 新建项目' if self.scenario == '0-1' else '1-N+1 增量开发'})",
+            f"**状态**: <span style='color:{status_color}'>{status_icon}</span>",
+            f"**总分**: {self.total_score}/100",
+            f"**加权分**: {self.weighted_score:.1f}/100",
+            "",
+            "---",
+            "",
+            "## 检查结果摘要",
+            "",
+            f"- 通过: {len(self.passed_checks)} 项",
+            f"- 警告: {len(self.warning_checks)} 项",
+            f"- 失败: {len(self.failed_checks)} 项",
+            "",
+        ]
+
+        if self.critical_failures:
+            lines.extend([
+                "## 关键失败项",
+                "",
+            ])
+            for failure in self.critical_failures:
+                lines.append(f"- {failure}")
+            lines.append("")
+
+        # 按类别分组展示
+        categories: dict[str, list[QualityCheck]] = {}
+        for check in self.checks:
+            if check.category not in categories:
+                categories[check.category] = []
+            categories[check.category].append(check)
+
+        lines.extend([
+            "## 详细检查结果",
+            "",
+        ])
+
+        for category, checks in categories.items():
+            lines.extend([
+                f"### {category}",
+                "",
+                "| 检查项 | 状态 | 得分 | 说明 |",
+                "|:---|:---:|:---:|:---|",
+            ])
+
+            for check in checks:
+                status_icon = "✓" if check.status == CheckStatus.PASSED else "⚠" if check.status == CheckStatus.WARNING else "✗"
+                lines.append(
+                    f"| {check.name} | {status_icon} | {check.score}/100 | {check.description} |"
+                )
+
+            lines.append("")
+
+        # 改进建议
+        if self.recommendations:
+            lines.extend([
+                "## 改进建议",
+                "",
+            ])
+            for idx, rec in enumerate(self.recommendations, 1):
+                lines.append(f"{idx}. {rec}")
+            lines.append("")
+
+        # 下一步行动
+        lines.extend([
+            "---",
+            "",
+            "## 下一步行动",
+            "",
+        ])
+
+        if self.passed:
+            lines.extend([
+                "[通过] 质量门禁已通过，可以继续下一步：",
+                "",
+                "1. 开始编码实现",
+                "2. 设置 CI/CD 流水线",
+                "3. 部署到测试环境",
+                "",
+            ])
+        else:
+            lines.extend([
+                "[未通过] 质量门禁未通过，请完成以下操作后重新检查：",
+                "",
+            ])
+
+            failed_items = [f"- {c.description}" for c in self.failed_checks]
+            lines.extend(failed_items)
+            lines.extend([
+                "",
+                "修复后运行: `super-dev quality --type all`",
+                "",
+            ])
+
+        return "\n".join(lines)
+
+
+class QualityGateChecker:
+    """质量门禁检查器"""
+
+    # 质量门禁阈值
+    PASS_THRESHOLD = 80
+    WARNING_THRESHOLD = 60
+    # 0-1 场景与增量场景统一使用 80+ 标准
+    PASS_THRESHOLD_ZERO_TO_ONE = 80
+
+    # 检查项配置
+    CHECKS_CONFIG = {
+        "documentation": {
+            "weight": 1.0,
+            "required": True,
+        },
+        "security": {
+            "weight": 1.5,  # 安全更重要
+            "required": True,
+        },
+        "performance": {
+            "weight": 1.2,
+            "required": True,
+        },
+        "testing": {
+            "weight": 1.3,
+            "required": True,
+        },
+        "code_quality": {
+            "weight": 1.0,
+            "required": False,
+        },
+    }
+
+    def __init__(
+        self,
+        project_dir: Path,
+        name: str,
+        tech_stack: dict,
+        scenario_override: str | None = None,
+        threshold_override: int | None = None,
+    ):
+        self.project_dir = Path(project_dir).resolve()
+        self.name = name
+        self.tech_stack = tech_stack
+        self.threshold_override = threshold_override
+        if scenario_override in {"0-1", "1-N+1"}:
+            self.is_zero_to_one = scenario_override == "0-1"
+        else:
+            self.is_zero_to_one = self._detect_zero_to_one_scenario()
+
+    def _detect_zero_to_one_scenario(self) -> bool:
+        """
+        检测是否为 0-1 场景（空项目/新建项目）
+
+        0-1 场景特征：
+        - 没有源代码目录（src/, lib/, app/, server/, client/ 等）
+        - 没有配置文件（package.json, requirements.txt, go.mod 等）
+        - 只有 output/ 目录（刚生成的文档）
+
+        Returns:
+            bool: True 表示 0-1 场景，False 表示 1-N+1 场景
+        """
+        # 检查常见的源代码目录
+        source_dirs = [
+            "src", "lib", "app", "server", "client",
+            "backend", "frontend", "api", "handlers",
+            "models", "views", "controllers", "services"
+        ]
+
+        has_source_code = any(
+            (self.project_dir / d).exists()
+            for d in source_dirs
+        )
+
+        # 检查是否有项目配置文件（表明这不是空项目）
+        config_files = [
+            "package.json", "requirements.txt", "go.mod",
+            "Cargo.toml", "pom.xml", "build.gradle"
+        ]
+
+        has_project_config = any(
+            (self.project_dir / f).exists()
+            for f in config_files
+        )
+
+        # 如果有源代码或有项目配置，说明不是 0-1 场景
+        return not (has_source_code or has_project_config)
+
+    def check(self, redteam_report: Optional["RedTeamReport"] = None) -> QualityGateResult:
+        """执行质量门禁检查"""
+        checks: list[QualityCheck] = []
+
+        # 1. 文档质量检查
+        checks.extend(self._check_documentation())
+
+        # 2. 安全检查 (基于红队报告)
+        checks.extend(self._check_security(redteam_report))
+
+        # 3. 性能检查 (基于红队报告)
+        checks.extend(self._check_performance(redteam_report))
+
+        # 4. 测试检查
+        checks.extend(self._check_testing())
+
+        # 5. 代码质量检查
+        checks.extend(self._check_code_quality())
+
+        # 计算总分和加权分
+        total_score = self._calculate_total_score(checks)
+        weighted_score = self._calculate_weighted_score(checks)
+
+        # 根据场景选择阈值
+        threshold = (
+            self.threshold_override
+            if self.threshold_override is not None
+            else (self.PASS_THRESHOLD_ZERO_TO_ONE if self.is_zero_to_one else self.PASS_THRESHOLD)
+        )
+
+        # 收集关键失败项
+        critical_failures = []
+        for check in checks:
+            config = self.CHECKS_CONFIG.get(check.category, {})
+            if config.get("required", False) and check.status == CheckStatus.FAILED:
+                critical_failures.append(f"[{check.category}] {check.description}")
+
+        # 检查是否通过：必须达到阈值，且必检项不能失败
+        passed = total_score >= threshold and not critical_failures
+
+        # 生成改进建议
+        recommendations = self._generate_recommendations(checks)
+
+        # 确定场景类型
+        scenario = "0-1" if self.is_zero_to_one else "1-N+1"
+
+        return QualityGateResult(
+            passed=passed,
+            total_score=total_score,
+            weighted_score=weighted_score,
+            checks=checks,
+            critical_failures=critical_failures,
+            recommendations=recommendations,
+            scenario=scenario,
+        )
+
+    def _check_documentation(self) -> list[QualityCheck]:
+        """检查文档质量"""
+        checks = []
+
+        # 检查 PRD 是否存在
+        prd_path = self.project_dir / "output" / f"{self.name}-prd.md"
+        if prd_path.exists():
+            content = prd_path.read_text(encoding="utf-8")
+            # 简单检查文档完整性
+            has_vision = "产品愿景" in content or "vision" in content.lower()
+            has_features = "功能需求" in content or "features" in content.lower()
+            has_acceptance = "验收标准" in content or "acceptance" in content.lower()
+
+            score = 100 if has_vision and has_features and has_acceptance else 70
+            status = CheckStatus.PASSED if score >= 80 else CheckStatus.WARNING
+
+            checks.append(QualityCheck(
+                name="PRD 文档",
+                category="documentation",
+                description="产品需求文档完整性",
+                status=status,
+                score=score,
+                weight=self.CHECKS_CONFIG["documentation"]["weight"],
+                details="包含产品愿景、功能需求和验收标准" if status == CheckStatus.PASSED else "文档内容不完整",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="PRD 文档",
+                category="documentation",
+                description="产品需求文档存在性",
+                status=CheckStatus.FAILED,
+                score=0,
+                weight=self.CHECKS_CONFIG["documentation"]["weight"],
+                details="PRD 文档不存在",
+            ))
+
+        # 检查架构文档是否存在
+        arch_path = self.project_dir / "output" / f"{self.name}-architecture.md"
+        if arch_path.exists():
+            content = arch_path.read_text(encoding="utf-8")
+            has_tech_stack = "技术栈" in content or "tech stack" in content.lower()
+            has_database = "数据库" in content or "database" in content.lower()
+            has_api = "API" in content
+
+            score = 100 if has_tech_stack and has_database and has_api else 70
+            status = CheckStatus.PASSED if score >= 80 else CheckStatus.WARNING
+
+            checks.append(QualityCheck(
+                name="架构文档",
+                category="documentation",
+                description="架构设计文档完整性",
+                status=status,
+                score=score,
+                weight=self.CHECKS_CONFIG["documentation"]["weight"],
+                details="包含技术栈、数据库设计和 API 设计" if status == CheckStatus.PASSED else "文档内容不完整",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="架构文档",
+                category="documentation",
+                description="架构设计文档存在性",
+                status=CheckStatus.FAILED,
+                score=0,
+                weight=self.CHECKS_CONFIG["documentation"]["weight"],
+                details="架构文档不存在",
+            ))
+
+        # 检查 UI/UX 文档是否存在
+        uiux_path = self.project_dir / "output" / f"{self.name}-uiux.md"
+        if uiux_path.exists():
+            checks.append(QualityCheck(
+                name="UI/UX 文档",
+                category="documentation",
+                description="UI/UX 设计文档存在性",
+                status=CheckStatus.PASSED,
+                score=100,
+                weight=self.CHECKS_CONFIG["documentation"]["weight"],
+                details="UI/UX 文档已创建",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="UI/UX 文档",
+                category="documentation",
+                description="UI/UX 设计文档存在性",
+                status=CheckStatus.WARNING,
+                score=50,
+                weight=self.CHECKS_CONFIG["documentation"]["weight"],
+                details="UI/UX 文档不存在（可选）",
+            ))
+
+        return checks
+
+    def _check_security(self, redteam_report: RedTeamReport | None) -> list[QualityCheck]:
+        """检查安全性"""
+        checks: list[QualityCheck] = []
+
+        if redteam_report:
+            critical_count = sum(1 for i in redteam_report.security_issues if i.severity == "critical")
+            high_count = sum(1 for i in redteam_report.security_issues if i.severity == "high")
+
+            if critical_count > 0:
+                score = max(0, 100 - critical_count * 30)
+                status = CheckStatus.FAILED
+            elif high_count > 2:
+                score = max(0, 100 - high_count * 15)
+                status = CheckStatus.WARNING
+            else:
+                score = 100
+                status = CheckStatus.PASSED
+
+            checks.append(QualityCheck(
+                name="安全审查",
+                category="security",
+                description=f"安全检查 ({critical_count} critical, {high_count} high)",
+                status=status,
+                score=score,
+                weight=self.CHECKS_CONFIG["security"]["weight"],
+                details=f"发现 {critical_count} 个严重问题和 {high_count} 个高危问题" if critical_count + high_count > 0 else "未发现严重安全问题",
+            ))
+        else:
+            # 未进行红队审查，给警告
+            checks.append(QualityCheck(
+                name="安全审查",
+                category="security",
+                description="安全检查状态",
+                status=CheckStatus.WARNING,
+                score=50,
+                weight=self.CHECKS_CONFIG["security"]["weight"],
+                details="未进行红队安全审查",
+            ))
+
+        return checks
+
+    def _check_performance(self, redteam_report: RedTeamReport | None) -> list[QualityCheck]:
+        """检查性能"""
+        checks: list[QualityCheck] = []
+
+        if redteam_report:
+            critical_count = sum(1 for i in redteam_report.performance_issues if i.severity == "critical")
+            high_count = sum(1 for i in redteam_report.performance_issues if i.severity == "high")
+
+            if critical_count > 0:
+                score = max(0, 100 - critical_count * 25)
+                status = CheckStatus.FAILED
+            elif high_count > 2:
+                score = max(0, 100 - high_count * 10)
+                status = CheckStatus.WARNING
+            else:
+                score = 100
+                status = CheckStatus.PASSED
+
+            checks.append(QualityCheck(
+                name="性能审查",
+                category="performance",
+                description=f"性能检查 ({critical_count} critical, {high_count} high)",
+                status=status,
+                score=score,
+                weight=self.CHECKS_CONFIG["performance"]["weight"],
+                details=f"发现 {critical_count} 个严重问题和 {high_count} 个高危问题" if critical_count + high_count > 0 else "未发现严重性能问题",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="性能审查",
+                category="performance",
+                description="性能检查状态",
+                status=CheckStatus.WARNING,
+                score=50,
+                weight=self.CHECKS_CONFIG["performance"]["weight"],
+                details="未进行红队性能审查",
+            ))
+
+        return checks
+
+    def _check_testing(self) -> list[QualityCheck]:
+        """检查测试策略"""
+        checks: list[QualityCheck] = []
+
+        # 检查是否有测试配置
+        has_jest = self._has_js_test_script()
+        has_pytest = self._has_pytest_config()
+
+        if has_jest or has_pytest:
+            checks.append(QualityCheck(
+                name="测试框架",
+                category="testing",
+                description="测试框架配置",
+                status=CheckStatus.PASSED,
+                score=100,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details="测试框架已配置",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="测试框架",
+                category="testing",
+                description="测试框架配置",
+                status=CheckStatus.WARNING,
+                score=50,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details="测试框架未配置",
+            ))
+
+        python_tests = self._discover_python_tests()
+        js_test_targets = self._discover_js_test_targets()
+
+        # 真实测试执行检查（优先 Python）
+        if python_tests:
+            pytest_executable = shutil.which("pytest")
+            if pytest_executable:
+                result = self._run_command(
+                    [pytest_executable, "-q", "--maxfail=1"],
+                    timeout=180,
+                )
+                if result["timed_out"]:
+                    checks.append(QualityCheck(
+                        name="测试执行",
+                        category="testing",
+                        description="自动化测试执行结果",
+                        status=CheckStatus.WARNING,
+                        score=40,
+                        weight=self.CHECKS_CONFIG["testing"]["weight"],
+                        details="pytest 执行超时，建议拆分测试或优化测试速度",
+                    ))
+                elif result["returncode"] == 0:
+                    summary = self._extract_test_summary(str(result["stdout"]))
+                    checks.append(QualityCheck(
+                        name="测试执行",
+                        category="testing",
+                        description="自动化测试执行结果",
+                        status=CheckStatus.PASSED,
+                        score=100,
+                        weight=self.CHECKS_CONFIG["testing"]["weight"],
+                        details=summary or "pytest 执行通过",
+                    ))
+                else:
+                    summary = self._extract_test_summary(str(result["stdout"] or result["stderr"]))
+                    checks.append(QualityCheck(
+                        name="测试执行",
+                        category="testing",
+                        description="自动化测试执行结果",
+                        status=CheckStatus.FAILED,
+                        score=20,
+                        weight=self.CHECKS_CONFIG["testing"]["weight"],
+                        details=summary or "pytest 执行失败",
+                    ))
+            else:
+                checks.append(QualityCheck(
+                    name="测试执行",
+                    category="testing",
+                    description="自动化测试执行结果",
+                    status=CheckStatus.WARNING,
+                    score=40,
+                    weight=self.CHECKS_CONFIG["testing"]["weight"],
+                    details="检测到 Python 测试，但未找到 pytest 可执行文件",
+                ))
+        elif js_test_targets:
+            npm_executable = shutil.which("npm")
+            if not npm_executable:
+                checks.append(QualityCheck(
+                    name="测试执行",
+                    category="testing",
+                    description="自动化测试执行结果",
+                    status=CheckStatus.WARNING,
+                    score=40,
+                    weight=self.CHECKS_CONFIG["testing"]["weight"],
+                    details="检测到 JS 测试脚本，但未找到 npm 可执行文件",
+                ))
+            else:
+                timed_out_targets: list[str] = []
+                failed_targets: list[str] = []
+                passed_targets: list[str] = []
+                for target in js_test_targets:
+                    rel = "."
+                    if target != self.project_dir:
+                        rel = str(target.relative_to(self.project_dir))
+                    result = self._run_command(
+                        [
+                            npm_executable,
+                            "--prefix",
+                            str(target),
+                            "run",
+                            "test",
+                            "--if-present",
+                        ],
+                        timeout=240,
+                    )
+                    if result["timed_out"]:
+                        timed_out_targets.append(rel)
+                    elif result["returncode"] == 0:
+                        passed_targets.append(rel)
+                    else:
+                        failed_targets.append(rel)
+
+                if failed_targets:
+                    checks.append(QualityCheck(
+                        name="测试执行",
+                        category="testing",
+                        description="自动化测试执行结果",
+                        status=CheckStatus.FAILED,
+                        score=20,
+                        weight=self.CHECKS_CONFIG["testing"]["weight"],
+                        details=f"JS 测试失败: {', '.join(failed_targets)}",
+                    ))
+                elif timed_out_targets:
+                    checks.append(QualityCheck(
+                        name="测试执行",
+                        category="testing",
+                        description="自动化测试执行结果",
+                        status=CheckStatus.WARNING,
+                        score=40,
+                        weight=self.CHECKS_CONFIG["testing"]["weight"],
+                        details=f"JS 测试超时: {', '.join(timed_out_targets)}",
+                    ))
+                else:
+                    checks.append(QualityCheck(
+                        name="测试执行",
+                        category="testing",
+                        description="自动化测试执行结果",
+                        status=CheckStatus.PASSED,
+                        score=100,
+                        weight=self.CHECKS_CONFIG["testing"]["weight"],
+                        details=f"JS 测试通过: {', '.join(passed_targets)}",
+                    ))
+        else:
+            warning_score = 70 if self.is_zero_to_one else 40
+            checks.append(QualityCheck(
+                name="测试执行",
+                category="testing",
+                description="自动化测试执行结果",
+                status=CheckStatus.WARNING,
+                score=warning_score,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details="未检测到可执行测试用例",
+            ))
+
+        coverage_percent = self._read_coverage_percent()
+        if coverage_percent is None:
+            warning_score = 70 if self.is_zero_to_one else 50
+            checks.append(QualityCheck(
+                name="测试覆盖率",
+                category="testing",
+                description="覆盖率报告",
+                status=CheckStatus.WARNING,
+                score=warning_score,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details="未检测到 coverage.xml 报告",
+            ))
+        elif coverage_percent >= 80:
+            checks.append(QualityCheck(
+                name="测试覆盖率",
+                category="testing",
+                description="覆盖率报告",
+                status=CheckStatus.PASSED,
+                score=coverage_percent,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details=f"覆盖率 {coverage_percent}%",
+            ))
+        elif coverage_percent >= 60:
+            checks.append(QualityCheck(
+                name="测试覆盖率",
+                category="testing",
+                description="覆盖率报告",
+                status=CheckStatus.WARNING,
+                score=coverage_percent,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details=f"覆盖率 {coverage_percent}%（建议提升到 80%+）",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="测试覆盖率",
+                category="testing",
+                description="覆盖率报告",
+                status=CheckStatus.FAILED,
+                score=coverage_percent,
+                weight=self.CHECKS_CONFIG["testing"]["weight"],
+                details=f"覆盖率 {coverage_percent}%（低于最低建议）",
+            ))
+
+        return checks
+
+    def _check_code_quality(self) -> list[QualityCheck]:
+        """检查代码质量工具"""
+        checks: list[QualityCheck] = []
+
+        # 检查 Linter
+        has_eslint = (self.project_dir / ".eslintrc.js").exists() or (
+            self.project_dir / ".eslintrc.json"
+        ).exists()
+        has_pylint = (self.project_dir / "pylint.ini").exists()
+        has_black = (self.project_dir / "pyproject.toml").exists() and "black" in (
+            self.project_dir / "pyproject.toml"
+        ).read_text(encoding='utf-8')
+
+        if has_eslint or has_pylint or has_black:
+            checks.append(QualityCheck(
+                name="Linter",
+                category="code_quality",
+                description="代码静态检查工具",
+                status=CheckStatus.PASSED,
+                score=100,
+                weight=self.CHECKS_CONFIG["code_quality"]["weight"],
+                details="Linter 已配置",
+            ))
+        else:
+            checks.append(QualityCheck(
+                name="Linter",
+                category="code_quality",
+                description="代码静态检查工具",
+                status=CheckStatus.WARNING,
+                score=50,
+                weight=self.CHECKS_CONFIG["code_quality"]["weight"],
+                details="Linter 未配置",
+            ))
+
+        python_roots = self._discover_python_source_roots()
+        if python_roots:
+            python_exec = shutil.which("python3") or shutil.which("python")
+            if python_exec:
+                cmd = [python_exec, "-m", "compileall", "-q", *[str(p) for p in python_roots]]
+                result = self._run_command(cmd, timeout=120)
+                if result["timed_out"]:
+                    checks.append(QualityCheck(
+                        name="Python 语法检查",
+                        category="code_quality",
+                        description="compileall 语法检查",
+                        status=CheckStatus.WARNING,
+                        score=50,
+                        weight=self.CHECKS_CONFIG["code_quality"]["weight"],
+                        details="compileall 执行超时",
+                    ))
+                elif result["returncode"] == 0:
+                    checks.append(QualityCheck(
+                        name="Python 语法检查",
+                        category="code_quality",
+                        description="compileall 语法检查",
+                        status=CheckStatus.PASSED,
+                        score=100,
+                        weight=self.CHECKS_CONFIG["code_quality"]["weight"],
+                        details="Python 语法检查通过",
+                    ))
+                else:
+                    checks.append(QualityCheck(
+                        name="Python 语法检查",
+                        category="code_quality",
+                        description="compileall 语法检查",
+                        status=CheckStatus.FAILED,
+                        score=20,
+                        weight=self.CHECKS_CONFIG["code_quality"]["weight"],
+                        details="Python 语法检查失败",
+                    ))
+            else:
+                checks.append(QualityCheck(
+                    name="Python 语法检查",
+                    category="code_quality",
+                    description="compileall 语法检查",
+                    status=CheckStatus.WARNING,
+                    score=50,
+                    weight=self.CHECKS_CONFIG["code_quality"]["weight"],
+                    details="未找到 python 解释器，跳过语法检查",
+                ))
+
+        return checks
+
+    def _calculate_total_score(self, checks: list[QualityCheck]) -> int:
+        """计算总分"""
+        if not checks:
+            return 0
+
+        return sum(c.score for c in checks) // len(checks)
+
+    def _calculate_weighted_score(self, checks: list[QualityCheck]) -> float:
+        """计算加权分"""
+        if not checks:
+            return 0.0
+
+        total_weight = sum(c.weight for c in checks)
+        if total_weight == 0:
+            return 0.0
+
+        weighted_sum = sum(c.score * c.weight for c in checks)
+        return weighted_sum / total_weight
+
+    def _generate_recommendations(self, checks: list[QualityCheck]) -> list[str]:
+        """生成改进建议"""
+        recommendations: list[str] = []
+
+        for check in checks:
+            if check.status == CheckStatus.FAILED:
+                recommendations.append(f"修复: {check.description}")
+            elif check.status == CheckStatus.WARNING:
+                recommendations.append(f"建议: {check.description}")
+
+        return recommendations
+
+    def _discover_python_tests(self) -> list[Path]:
+        roots = [self.project_dir / "tests", self.project_dir / "backend" / "tests"]
+        files: list[Path] = []
+        for tests_dir in roots:
+            if not tests_dir.exists():
+                continue
+            files.extend(list(tests_dir.rglob("test_*.py")))
+            files.extend(list(tests_dir.rglob("*_test.py")))
+        return files
+
+    def _has_pytest_config(self) -> bool:
+        if (self.project_dir / "pytest.ini").exists():
+            return True
+
+        setup_cfg = self.project_dir / "setup.cfg"
+        if setup_cfg.exists():
+            content = setup_cfg.read_text(encoding="utf-8", errors="ignore")
+            if "[tool:pytest]" in content:
+                return True
+
+        tox_ini = self.project_dir / "tox.ini"
+        if tox_ini.exists():
+            content = tox_ini.read_text(encoding="utf-8", errors="ignore")
+            if "[pytest]" in content:
+                return True
+
+        pyproject = self.project_dir / "pyproject.toml"
+        if pyproject.exists():
+            content = pyproject.read_text(encoding="utf-8", errors="ignore")
+            if "pytest.ini_options" in content:
+                return True
+
+        backend_pyproject = self.project_dir / "backend" / "pyproject.toml"
+        if backend_pyproject.exists():
+            content = backend_pyproject.read_text(encoding="utf-8", errors="ignore")
+            if "pytest.ini_options" in content:
+                return True
+
+        return False
+
+    def _discover_python_source_roots(self) -> list[Path]:
+        roots: list[Path] = []
+        candidates = [
+            "super_dev", "src", "app", "backend", "server", "api", "services", "lib"
+        ]
+        for name in candidates:
+            path = self.project_dir / name
+            if path.exists() and path.is_dir():
+                roots.append(path)
+
+        top_level_py = list(self.project_dir.glob("*.py"))
+        roots.extend(top_level_py)
+
+        # 去重并限制数量，避免无界扫描
+        unique: list[Path] = []
+        seen = set()
+        for path in roots:
+            key = str(path.resolve())
+            if key in seen:
+                continue
+            seen.add(key)
+            unique.append(path)
+        return unique[:8]
+
+    def _discover_js_test_targets(self) -> list[Path]:
+        targets: list[Path] = []
+        for root in (self.project_dir, self.project_dir / "frontend", self.project_dir / "backend"):
+            package_json = root / "package.json"
+            if not package_json.exists():
+                continue
+            try:
+                data = json.loads(package_json.read_text(encoding="utf-8"))
+            except Exception:
+                continue
+            scripts = data.get("scripts", {})
+            test_script = str(scripts.get("test", "")).strip()
+            if not test_script:
+                continue
+            if test_script == 'echo "Error: no test specified" && exit 1':
+                continue
+            targets.append(root)
+        return targets
+
+    def _has_js_test_script(self) -> bool:
+        return bool(self._discover_js_test_targets())
+
+    def _extract_test_summary(self, output: str) -> str:
+        if not output:
+            return ""
+        lines = [line.strip() for line in output.splitlines() if line.strip()]
+        for line in reversed(lines):
+            if "passed" in line or "failed" in line or "error" in line:
+                return line[:240]
+        return lines[-1][:240] if lines else ""
+
+    def _read_coverage_percent(self) -> int | None:
+        coverage_candidates = [
+            self.project_dir / "coverage.xml",
+            self.project_dir / "backend" / "coverage.xml",
+            self.project_dir / "frontend" / "coverage.xml",
+            self.project_dir / "coverage" / "cobertura-coverage.xml",
+            self.project_dir / "frontend" / "coverage" / "cobertura-coverage.xml",
+            self.project_dir / "backend" / "coverage" / "cobertura-coverage.xml",
+        ]
+
+        parsed_values: list[int] = []
+        for coverage_xml in coverage_candidates:
+            if not coverage_xml.exists():
+                continue
+            try:
+                root = ElementTree.fromstring(coverage_xml.read_text(encoding="utf-8"))
+                line_rate = root.attrib.get("line-rate")
+                if line_rate is not None:
+                    parsed_values.append(max(0, min(100, int(round(float(line_rate) * 100)))))
+                    continue
+
+                lines_covered = root.attrib.get("lines-covered")
+                lines_valid = root.attrib.get("lines-valid")
+                if lines_covered and lines_valid and float(lines_valid) > 0:
+                    percent = (float(lines_covered) / float(lines_valid)) * 100
+                    parsed_values.append(max(0, min(100, int(round(percent)))))
+            except Exception:
+                continue
+
+        if not parsed_values:
+            return None
+        return max(parsed_values)
+
+    def _run_command(self, cmd: list[str], timeout: int = 120) -> dict[str, object]:
+        try:
+            completed = subprocess.run(
+                cmd,
+                cwd=str(self.project_dir),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )  # nosec B603
+            return {
+                "returncode": completed.returncode,
+                "stdout": completed.stdout or "",
+                "stderr": completed.stderr or "",
+                "timed_out": False,
+            }
+        except subprocess.TimeoutExpired as e:
+            return {
+                "returncode": -1,
+                "stdout": (e.stdout or ""),
+                "stderr": (e.stderr or ""),
+                "timed_out": True,
+            }
+        except Exception as e:
+            return {
+                "returncode": -1,
+                "stdout": "",
+                "stderr": str(e),
+                "timed_out": False,
+            }