super-dev 2.0.0__py3-none-any.whl

super_dev/specs/validator.py

@@ -0,0 +1,415 @@
+"""
+Spec-Driven Development 验证器
+
+开发：Excellent（11964948@qq.com）
+功能：验证规格格式和结构
+作用：检查 spec.md 和 change 的格式是否符合 OpenSpec 标准
+创建时间：2025-12-30
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ValidationError:
+    """验证错误"""
+    file: str                  # 文件路径
+    line: int = 0              # 行号
+    column: int = 0            # 列号
+    message: str = ""          # 错误消息
+    severity: str = "error"    # 严重程度: error, warning, info
+
+
+@dataclass
+class ValidationResult:
+    """验证结果"""
+    is_valid: bool
+    errors: list[ValidationError] = field(default_factory=list)
+    warnings: list[ValidationError] = field(default_factory=list)
+    info: list[ValidationError] = field(default_factory=list)
+
+    @property
+    def total_issues(self) -> int:
+        """总问题数"""
+        return len(self.errors) + len(self.warnings)
+
+    def to_summary(self) -> str:
+        """生成摘要报告"""
+        lines = []
+        if self.is_valid:
+            lines.append("[通过] 规格格式验证通过")
+        else:
+            lines.append(f"[失败] 发现 {len(self.errors)} 个错误")
+
+        if self.warnings:
+            lines.append(f"[警告] {len(self.warnings)} 个警告")
+
+        return "\n".join(lines)
+
+
+class SpecValidator:
+    """规格验证器"""
+
+    # 规范需求关键词
+    REQUIREMENT_KEYWORDS = ["SHALL", "MUST", "SHOULD", "MAY"]
+
+    # Delta 类型
+    DELTA_TYPES = ["ADDED", "MODIFIED", "REMOVED"]
+
+    def __init__(self, project_dir: Path | str):
+        """初始化验证器"""
+        self.project_dir = Path(project_dir).resolve()
+        self.specs_dir = self.project_dir / ".super-dev" / "specs"
+        self.changes_dir = self.project_dir / ".super-dev" / "changes"
+
+    def validate_change(self, change_id: str) -> ValidationResult:
+        """验证变更"""
+        errors: list[ValidationError] = []
+        warnings: list[ValidationError] = []
+        info: list[ValidationError] = []
+
+        change_dir = self.changes_dir / change_id
+        if not change_dir.exists():
+            errors.append(ValidationError(
+                file=str(change_dir),
+                message=f"变更目录不存在: {change_id}"
+            ))
+            return ValidationResult(is_valid=False, errors=errors)
+
+        # 验证 proposal.md
+        proposal_file = change_dir / "proposal.md"
+        if proposal_file.exists():
+            result = self._validate_proposal(proposal_file)
+            errors.extend(result.errors)
+            warnings.extend(result.warnings)
+            info.extend(result.info)
+        else:
+            warnings.append(ValidationError(
+                file=str(proposal_file),
+                message="缺少 proposal.md"
+            ))
+
+        # 验证 tasks.md
+        tasks_file = change_dir / "tasks.md"
+        if tasks_file.exists():
+            result = self._validate_tasks(tasks_file)
+            errors.extend(result.errors)
+            warnings.extend(result.warnings)
+            info.extend(result.info)
+        else:
+            warnings.append(ValidationError(
+                file=str(tasks_file),
+                message="缺少 tasks.md"
+            ))
+
+        # 验证 design.md (可选)
+        design_file = change_dir / "design.md"
+        if design_file.exists():
+            result = self._validate_design(design_file)
+            errors.extend(result.errors)
+            warnings.extend(result.warnings)
+
+        # 验证 specs/ 目录
+        specs_dir = change_dir / "specs"
+        if specs_dir.exists():
+            for spec_file in specs_dir.rglob("spec.md"):
+                result = self._validate_spec_delta(spec_file)
+                errors.extend(result.errors)
+                warnings.extend(result.warnings)
+                info.extend(result.info)
+        else:
+            warnings.append(ValidationError(
+                file=str(specs_dir),
+                message="缺少 specs/ 目录"
+            ))
+
+        return ValidationResult(
+            is_valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings,
+            info=info
+        )
+
+    def validate_spec(self, spec_name: str) -> ValidationResult:
+        """验证规范"""
+        errors: list[ValidationError] = []
+        warnings: list[ValidationError] = []
+
+        spec_file = self.specs_dir / spec_name / "spec.md"
+        if not spec_file.exists():
+            errors.append(ValidationError(
+                file=str(spec_file),
+                message=f"规范文件不存在: {spec_name}"
+            ))
+            return ValidationResult(is_valid=False, errors=errors)
+
+        content = spec_file.read_text(encoding="utf-8")
+        lines = content.split("\n")
+
+        # 检查标题
+        has_title = False
+        has_purpose = False
+        has_requirements = False
+        has_req_keyword = False
+
+        for i, line in enumerate(lines, 1):
+            # 检查一级标题
+            if line.startswith("# ") and not has_title:
+                has_title = True
+                if not line[2:].strip():
+                    errors.append(ValidationError(
+                        file=str(spec_file),
+                        line=i,
+                        message="标题不能为空"
+                    ))
+
+            # 检查 Purpose 部分
+            if line.startswith("## Purpose"):
+                has_purpose = True
+
+            # 检查 Requirements 部分
+            if line.startswith("## Requirements"):
+                has_requirements = True
+
+            # 检查需求格式
+            if line.startswith("### Requirement:"):
+                has_req_keyword = True
+                if not line[16:].strip():
+                    errors.append(ValidationError(
+                        file=str(spec_file),
+                        line=i,
+                        message="需求名称不能为空"
+                    ))
+
+            # 检查需求关键词
+            if any(kw in line for kw in self.REQUIREMENT_KEYWORDS):
+                has_req_keyword = True
+
+            # 检查场景格式
+            if line.startswith("#### Scenario:"):
+                if not line[14:].strip():
+                    warnings.append(ValidationError(
+                        file=str(spec_file),
+                        line=i,
+                        severity="warning",
+                        message="场景描述为空"
+                    ))
+
+        # 验证结果
+        if not has_title:
+            errors.append(ValidationError(
+                file=str(spec_file),
+                message="缺少一级标题"
+            ))
+
+        if not has_purpose:
+            warnings.append(ValidationError(
+                file=str(spec_file),
+                severity="warning",
+                message="缺少 Purpose 部分"
+            ))
+
+        if not has_requirements:
+            warnings.append(ValidationError(
+                file=str(spec_file),
+                severity="warning",
+                message="缺少 Requirements 部分"
+            ))
+
+        if not has_req_keyword:
+            warnings.append(ValidationError(
+                file=str(spec_file),
+                severity="info",
+                message="建议使用 SHALL/MUST/SHOULD/MAY 关键词"
+            ))
+
+        return ValidationResult(
+            is_valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings
+        )
+
+    def _validate_proposal(self, proposal_file: Path) -> ValidationResult:
+        """验证提案文件"""
+        errors: list[ValidationError] = []
+        warnings: list[ValidationError] = []
+
+        content = proposal_file.read_text(encoding="utf-8")
+
+        # 检查必需的章节
+        has_title = False
+        has_description = False
+
+        for line in content.split("\n"):
+            if re.match(r"^##\s+", line):
+                if "description" in line.lower():
+                    has_description = True
+                elif "title" in line.lower() or line.startswith("# "):
+                    has_title = True
+
+        if not has_title:
+            warnings.append(ValidationError(
+                file=str(proposal_file),
+                severity="warning",
+                message="提案缺少标题"
+            ))
+
+        if not has_description:
+            warnings.append(ValidationError(
+                file=str(proposal_file),
+                severity="warning",
+                message="提案缺少描述"
+            ))
+
+        return ValidationResult(
+            is_valid=True,
+            errors=errors,
+            warnings=warnings
+        )
+
+    def _validate_tasks(self, tasks_file: Path) -> ValidationResult:
+        """验证任务文件"""
+        errors: list[ValidationError] = []
+        warnings: list[ValidationError] = []
+
+        content = tasks_file.read_text(encoding="utf-8")
+        lines = content.split("\n")
+
+        task_pattern = re.compile(r'^-\s*\[([ x~_])\]\s*\*\*([\d.]+):\s*([^*]+)\*\*')
+
+        task_ids = []
+        for i, line in enumerate(lines, 1):
+            match = task_pattern.match(line)
+            if match:
+                status_char, task_id, title = match.groups()
+                task_ids.append(task_id)
+
+                # 检查任务标题
+                if not title.strip():
+                    errors.append(ValidationError(
+                        file=str(tasks_file),
+                        line=i,
+                        message="任务标题不能为空"
+                    ))
+
+        # 检查任务ID格式
+        for task_id in task_ids:
+            if not re.match(r"^\d+\.\d+$", task_id):
+                warnings.append(ValidationError(
+                    file=str(tasks_file),
+                    severity="warning",
+                    message=f"任务ID格式建议为 '数字.数字' 格式: {task_id}"
+                ))
+
+        if not task_ids:
+            warnings.append(ValidationError(
+                file=str(tasks_file),
+                severity="warning",
+                message="没有找到任何任务"
+            ))
+
+        return ValidationResult(
+            is_valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings
+        )
+
+    def _validate_design(self, design_file: Path) -> ValidationResult:
+        """验证设计文件"""
+        # design.md 是可选的，只做基本检查
+        content = design_file.read_text(encoding="utf-8")
+        if len(content) < 10:
+            return ValidationResult(
+                is_valid=False,
+                errors=[ValidationError(
+                    file=str(design_file),
+                    message="设计文件内容过少"
+                )]
+            )
+        return ValidationResult(is_valid=True)
+
+    def _validate_spec_delta(self, spec_file: Path) -> ValidationResult:
+        """验证规范增量文件"""
+        errors: list[ValidationError] = []
+        warnings: list[ValidationError] = []
+
+        content = spec_file.read_text(encoding="utf-8")
+        lines = content.split("\n")
+
+        has_delta_header = False
+        current_delta_type = None
+        has_requirements = False
+
+        for i, line in enumerate(lines, 1):
+            # 检查 Delta 类型标题
+            if line.startswith("## "):
+                for delta_type in self.DELTA_TYPES:
+                    if delta_type in line.upper():
+                        has_delta_header = True
+                        current_delta_type = delta_type
+                        break
+
+            # 检查需求格式
+            if line.startswith("### Requirement:"):
+                if not current_delta_type:
+                    errors.append(ValidationError(
+                        file=str(spec_file),
+                        line=i,
+                        message="需求必须在 Delta 类型 (ADDED/MODIFIED/REMOVED) 下"
+                    ))
+
+                has_requirements = True
+
+                if not line[16:].strip():
+                    errors.append(ValidationError(
+                        file=str(spec_file),
+                        line=i,
+                        message="需求名称不能为空"
+                    ))
+
+        if not has_delta_header:
+            errors.append(ValidationError(
+                file=str(spec_file),
+                message="缺少 Delta 类型标题 (ADDED/MODIFIED/REMOVED)"
+            ))
+
+        if not has_requirements:
+            warnings.append(ValidationError(
+                file=str(spec_file),
+                severity="warning",
+                message="没有找到任何需求"
+            ))
+
+        return ValidationResult(
+            is_valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings
+        )
+
+    def validate_all(self) -> ValidationResult:
+        """验证所有变更"""
+        all_errors: list[ValidationError] = []
+        all_warnings: list[ValidationError] = []
+
+        if not self.changes_dir.exists():
+            return ValidationResult(
+                is_valid=False,
+                errors=[ValidationError(
+                    file=str(self.changes_dir),
+                    message="changes 目录不存在，请先运行 'super-dev spec init'"
+                )]
+            )
+
+        for change_dir in self.changes_dir.iterdir():
+            if change_dir.is_dir() and not change_dir.name.startswith("."):
+                result = self.validate_change(change_dir.name)
+                all_errors.extend(result.errors)
+                all_warnings.extend(result.warnings)
+
+        return ValidationResult(
+            is_valid=len(all_errors) == 0,
+            errors=all_errors,
+            warnings=all_warnings
+        )

super_dev/utils/__init__.py

@@ -0,0 +1,11 @@
+"""
+开发:Excellent(11964948@qq.com)
+功能:工具模块初始化
+作用:提供通用工具函数和类
+创建时间:2025-01-29
+最后修改:2025-01-29
+"""
+
+from .logger import get_logger, log_with_extra
+
+__all__ = ['get_logger', 'log_with_extra']

super_dev/utils/logger.py

@@ -0,0 +1,133 @@
+"""
+开发:Excellent(11964948@qq.com)
+功能:统一日志系统
+作用:提供结构化、可配置的日志记录功能
+创建时间:2025-01-29
+最后修改:2025-01-29
+"""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+class ColoredFormatter(logging.Formatter):
+    """彩色日志格式化器"""
+
+    # ANSI颜色代码
+    COLORS = {
+        "DEBUG": "\033[36m",  # 青色
+        "INFO": "\033[32m",  # 绿色
+        "WARNING": "\033[33m",  # 黄色
+        "ERROR": "\033[31m",  # 红色
+        "CRITICAL": "\033[35m",  # 紫色
+    }
+    RESET = "\033[0m"
+
+    def format(self, record):
+        # 添加颜色
+        log_color = self.COLORS.get(record.levelname, self.RESET)
+        record.levelname = f"{log_color}{record.levelname}{self.RESET}"
+        return super().format(record)
+
+
+class StructuredFormatter(logging.Formatter):
+    """结构化日志格式化器(JSON风格)"""
+
+    def format(self, record):
+        log_data = {
+            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        # 添加异常信息
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        # 添加额外字段
+        if hasattr(record, "extra_data"):
+            log_data["data"] = record.extra_data
+
+        return str(log_data)
+
+
+def get_logger(
+    name: str,
+    level: str = "INFO",
+    log_file: Path | None = None,
+    use_colors: bool = True,
+    structured: bool = False,
+) -> logging.Logger:
+    """
+    获取配置好的日志记录器
+
+    Args:
+        name: 日志记录器名称
+        level: 日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_file: 日志文件路径(可选)
+        use_colors: 是否使用彩色输出(仅终端)
+        structured: 是否使用结构化格式
+
+    Returns:
+        配置好的日志记录器
+    """
+    logger = logging.getLogger(name)
+
+    # 避免重复添加handler
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(getattr(logging, level.upper(), logging.INFO))
+    logger.propagate = False  # 不传播到父logger
+
+    # 控制台处理器
+    console_handler = logging.StreamHandler(sys.stdout)
+
+    if use_colors and not structured:
+        formatter: logging.Formatter = ColoredFormatter(
+            fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+        )
+    elif structured:
+        formatter = StructuredFormatter()
+    else:
+        formatter = logging.Formatter(
+            fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+        )
+
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    # 文件处理器(如果指定)
+    if log_file:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.setFormatter(
+            logging.Formatter(
+                fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+def log_with_extra(logger: logging.Logger, level: str, message: str, **extra_data):
+    """
+    带额外数据的日志记录
+
+    Args:
+        logger: 日志记录器
+        level: 日志级别
+        message: 日志消息
+        **extra_data: 额外的结构化数据
+    """
+    log_func = getattr(logger, level.lower(), logger.info)
+    extra = {"extra_data": extra_data} if extra_data else {}
+    log_func(message, extra=extra)