dash-devtools 1.0.0__py3-none-any.whl

dash_devtools/validators/common/security.py

@@ -0,0 +1,270 @@
+"""
+安全性驗證器（通用）
+
+檢查項目：
+1. API Key / Token 外洩
+2. 密碼硬編碼
+3. .env 檔案提交
+4. 敏感資料暴露
+"""
+
+import re
+from fnmatch import fnmatch
+from pathlib import Path
+
+
+class SecurityValidator:
+    """安全性驗證器"""
+
+    name = 'security'
+
+    # 敏感資料正則表達式
+    SENSITIVE_PATTERNS = [
+        (r'(?i)(api[_-]?key|apikey)\s*[=:]\s*["\']?[a-zA-Z0-9_-]{20,}', 'API Key'),
+        (r'(?i)(secret|token)\s*[=:]\s*["\']?[a-zA-Z0-9_-]{20,}', 'Secret/Token'),
+        (r'(?i)password\s*[=:]\s*["\'][^"\']+["\']', '密碼'),
+        (r'sk-[a-zA-Z0-9]{48}', 'OpenAI API Key'),
+        (r'sk_live_[a-zA-Z0-9]{24,}', 'Stripe Live Key'),
+        (r'ghp_[a-zA-Z0-9]{36}', 'GitHub Token'),
+        # Clerk 只檢查 secret key (sk_)，publishable key (pk_) 是公開的
+        (r'CLERK_SECRET_KEY\s*=\s*["\']?sk_[a-zA-Z0-9_-]{20,}', 'Clerk Secret Key'),
+        # Neon Database API Key (napi_開頭，64字元)
+        (r'napi_[a-zA-Z0-9]{60,}', 'Neon API Key'),
+        # PostgreSQL 連線字串 (含密碼)
+        (r'postgres(?:ql)?://[^:<]+:[^@<]+@[^\s"\']+', 'PostgreSQL 連線字串'),
+        # Neon PostgreSQL 專用格式
+        (r'npg_[a-zA-Z0-9]{10,}', 'Neon PostgreSQL 密碼'),
+    ]
+
+    # 敏感檔案
+    SENSITIVE_FILES = [
+        '.env',
+        '.env.local',
+        '.env.production',
+        'credentials.json',
+        'service-account.json',
+        'private.key',
+        '*.pem',
+    ]
+
+    # 忽略目錄
+    IGNORE_DIRS = [
+        'node_modules', '.git', 'dist', 'build', '.next', '__pycache__',
+        '.angular', 'venv', '.venv', '.cache', 'coverage'
+    ]
+
+    def __init__(self, project_path):
+        self.project_path = Path(project_path)
+        self.project_name = self.project_path.name
+        self.scanignore = self._parse_scanignore()
+        self.result = {
+            'name': self.name,
+            'passed': True,
+            'errors': [],
+            'warnings': [],
+            'checks': {}
+        }
+
+    def run(self):
+        """執行所有驗證"""
+        if not self.project_path.exists():
+            self.result['passed'] = False
+            self.result['errors'].append(f'專案路徑不存在: {self.project_path}')
+            return self.result
+
+        self.check_sensitive_files()
+        self.check_hardcoded_secrets()
+        self.check_gitignore()
+
+        return self.result
+
+    def check_sensitive_files(self):
+        """檢查敏感檔案是否被追蹤"""
+        issues = []
+
+        # 找出所有巢狀的 git repo (要跳過)
+        nested_repos = self._get_nested_repos()
+
+        for pattern in self.SENSITIVE_FILES:
+            if '*' in pattern:
+                files = list(self.project_path.rglob(pattern))
+            else:
+                files = [self.project_path / pattern]
+
+            for f in files:
+                if f.exists() and f.is_file():
+                    if self._should_skip(f, nested_repos):
+                        continue
+                    if not self._is_gitignored(f):
+                        issues.append(str(f.relative_to(self.project_path)))
+
+        self.result['checks']['sensitive_files'] = {
+            'count': len(issues),
+            'files': issues
+        }
+
+        if issues:
+            self.result['passed'] = False
+            for f in issues:
+                self.result['errors'].append(f'敏感檔案未忽略: {f}')
+
+    def check_hardcoded_secrets(self):
+        """檢查硬編碼的敏感資料"""
+        issues = []
+
+        for file_path in self._get_source_files():
+            try:
+                content = file_path.read_text(encoding='utf-8')
+                rel_path = str(file_path.relative_to(self.project_path))
+
+                # 全排除檢查
+                if self._is_scanignored(rel_path, None):
+                    continue
+
+                for pattern, desc in self.SENSITIVE_PATTERNS:
+                    # 特定 pattern 排除檢查
+                    if self._is_scanignored(rel_path, desc):
+                        continue
+                    matches = re.findall(pattern, content)
+                    if matches:
+                        issues.append({
+                            'file': rel_path,
+                            'type': desc,
+                            'count': len(matches)
+                        })
+            except Exception:
+                pass
+
+        self.result['checks']['hardcoded_secrets'] = {
+            'count': len(issues),
+            'issues': issues
+        }
+
+        if issues:
+            self.result['passed'] = False
+            for issue in issues:
+                self.result['errors'].append(
+                    f"發現 {issue['type']} 在 {issue['file']}"
+                )
+
+    def check_gitignore(self):
+        """檢查 .gitignore 設定"""
+        gitignore = self.project_path / '.gitignore'
+        required_patterns = ['.env', 'node_modules', '*.log']
+        missing = []
+
+        if gitignore.exists():
+            content = gitignore.read_text(encoding='utf-8')
+            for pattern in required_patterns:
+                if pattern not in content:
+                    missing.append(pattern)
+        else:
+            missing = required_patterns
+
+        self.result['checks']['gitignore'] = {
+            'exists': gitignore.exists(),
+            'missing_patterns': missing
+        }
+
+        if missing:
+            for pattern in missing:
+                self.result['warnings'].append(f'.gitignore 缺少: {pattern}')
+
+    def _get_nested_repos(self):
+        """取得巢狀 git repo 路徑"""
+        nested_repos = []
+        for git_dir in self.project_path.rglob('.git'):
+            if git_dir.parent != self.project_path:
+                nested_repos.append(str(git_dir.parent))
+        return nested_repos
+
+    def _should_skip(self, file_path, nested_repos):
+        """檢查是否應該跳過該檔案"""
+        file_str = str(file_path)
+        # 跳過巢狀 git repo
+        if any(file_str.startswith(repo) for repo in nested_repos):
+            return True
+        # 跳過忽略目錄
+        if any(ignore in file_str for ignore in self.IGNORE_DIRS):
+            return True
+        return False
+
+    def _get_source_files(self):
+        """取得所有原始碼檔案"""
+        extensions = ['*.js', '*.ts', '*.jsx', '*.tsx', '*.py', '*.json', '*.yaml', '*.yml']
+        files = []
+        nested_repos = self._get_nested_repos()
+
+        for ext in extensions:
+            for f in self.project_path.rglob(ext):
+                if not self._should_skip(f, nested_repos):
+                    files.append(f)
+
+        return files
+
+    def _parse_scanignore(self):
+        """解析 .scanignore 檔案"""
+        scanignore_file = self.project_path / '.scanignore'
+        result = {'paths': [], 'pattern_paths': []}
+
+        if not scanignore_file.exists():
+            return result
+
+        try:
+            for line in scanignore_file.read_text(encoding='utf-8').splitlines():
+                line = line.strip()
+                if not line or line.startswith('#'):
+                    continue
+
+                pattern_match = re.match(r'^\[pattern:(.+?)\]\s+(.+)$', line)
+                if pattern_match:
+                    pattern_name = pattern_match.group(1).strip()
+                    path_glob = pattern_match.group(2).strip()
+                    result['pattern_paths'].append((pattern_name, path_glob))
+                else:
+                    result['paths'].append(line)
+        except Exception:
+            pass
+
+        return result
+
+    def _is_scanignored(self, rel_path, pattern_name):
+        """檢查檔案是否在 .scanignore 中"""
+        # 全排除路徑
+        for glob_pattern in self.scanignore['paths']:
+            if glob_pattern.endswith('/'):
+                if rel_path.startswith(glob_pattern) or rel_path.startswith(glob_pattern.rstrip('/')):
+                    return True
+            if fnmatch(rel_path, glob_pattern):
+                return True
+            if rel_path.startswith(glob_pattern.rstrip('/') + '/'):
+                return True
+
+        # 特定 pattern 排除
+        if pattern_name:
+            for p_name, p_glob in self.scanignore['pattern_paths']:
+                if p_name == pattern_name:
+                    if fnmatch(rel_path, p_glob):
+                        return True
+                    if rel_path == p_glob:
+                        return True
+
+        return False
+
+    def _is_gitignored(self, file_path):
+        """檢查檔案是否在 .gitignore 中"""
+        gitignore = self.project_path / '.gitignore'
+        if not gitignore.exists():
+            return False
+
+        content = gitignore.read_text(encoding='utf-8')
+        rel_path = str(file_path.relative_to(self.project_path))
+
+        for line in content.splitlines():
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            if line in rel_path or rel_path.startswith(line):
+                return True
+
+        return False

dash_devtools/validators/common/spec.py

@@ -0,0 +1,273 @@
+"""
+OpenSpec 規格驗證器
+
+檢查項目：
+1. openspec/ 目錄存在性
+2. 規格檔案格式正確 (YAML frontmatter)
+3. 無孤立的提案（超過 7 天未處理）
+4. specs/ 與 changes/ 一致性
+"""
+
+import re
+import time
+from pathlib import Path
+
+
+class SpecValidator:
+    """OpenSpec 規格驗證器"""
+
+    name = 'spec'
+
+    # 忽略目錄
+    IGNORE_DIRS = [
+        'node_modules', '.git', 'dist', 'build', '__pycache__', 'venv'
+    ]
+
+    # 規格檔案必要欄位
+    REQUIRED_FRONTMATTER = ['title', 'status']
+
+    # 變更檔案必要欄位
+    REQUIRED_CHANGE_FIELDS = ['title', 'type']
+
+    def __init__(self, project_path):
+        self.project_path = Path(project_path)
+        self.project_name = self.project_path.name
+        self.openspec_dir = self.project_path / 'openspec'
+        self.result = {
+            'name': self.name,
+            'passed': True,
+            'errors': [],
+            'warnings': [],
+            'checks': {}
+        }
+
+    def run(self):
+        """執行所有驗證"""
+        if not self.project_path.exists():
+            self.result['passed'] = False
+            self.result['errors'].append(f'專案路徑不存在: {self.project_path}')
+            return self.result
+
+        # 如果沒有 openspec 目錄，跳過驗證
+        if not self.openspec_dir.exists():
+            self.result['checks']['initialized'] = {'exists': False}
+            return self.result
+
+        self.check_directory_structure()
+        self.check_specs_format()
+        self.check_changes_format()
+        self.check_stale_changes()
+        self.check_consistency()
+
+        return self.result
+
+    def check_directory_structure(self):
+        """檢查目錄結構"""
+        specs_dir = self.openspec_dir / 'specs'
+        changes_dir = self.openspec_dir / 'changes'
+
+        structure = {
+            'openspec_exists': self.openspec_dir.exists(),
+            'specs_exists': specs_dir.exists(),
+            'changes_exists': changes_dir.exists(),
+        }
+
+        self.result['checks']['directory_structure'] = structure
+
+        # 目錄存在但子目錄缺失是警告
+        if self.openspec_dir.exists():
+            if not specs_dir.exists():
+                self.result['warnings'].append('openspec/specs/ 目錄不存在')
+            if not changes_dir.exists():
+                self.result['warnings'].append('openspec/changes/ 目錄不存在')
+
+    def check_specs_format(self):
+        """檢查規格檔案格式"""
+        specs_dir = self.openspec_dir / 'specs'
+        if not specs_dir.exists():
+            return
+
+        issues = []
+        valid_count = 0
+
+        for spec_file in specs_dir.glob('*.md'):
+            try:
+                content = spec_file.read_text(encoding='utf-8')
+                frontmatter = self._parse_frontmatter(content)
+
+                if frontmatter is None:
+                    issues.append({
+                        'file': spec_file.name,
+                        'error': '缺少 YAML frontmatter'
+                    })
+                    continue
+
+                # 檢查必要欄位
+                missing = [f for f in self.REQUIRED_FRONTMATTER if f not in frontmatter]
+                if missing:
+                    issues.append({
+                        'file': spec_file.name,
+                        'error': f'缺少欄位: {", ".join(missing)}'
+                    })
+                else:
+                    valid_count += 1
+
+            except Exception as e:
+                issues.append({
+                    'file': spec_file.name,
+                    'error': str(e)
+                })
+
+        self.result['checks']['specs_format'] = {
+            'valid_count': valid_count,
+            'issues': issues
+        }
+
+        for issue in issues:
+            self.result['warnings'].append(
+                f"規格格式問題: {issue['file']} - {issue['error']}"
+            )
+
+    def check_changes_format(self):
+        """檢查變更檔案格式"""
+        changes_dir = self.openspec_dir / 'changes'
+        if not changes_dir.exists():
+            return
+
+        issues = []
+        valid_count = 0
+
+        for change_file in changes_dir.glob('*.md'):
+            try:
+                content = change_file.read_text(encoding='utf-8')
+                frontmatter = self._parse_frontmatter(content)
+
+                if frontmatter is None:
+                    issues.append({
+                        'file': change_file.name,
+                        'error': '缺少 YAML frontmatter'
+                    })
+                    continue
+
+                # 檢查必要欄位
+                missing = [f for f in self.REQUIRED_CHANGE_FIELDS if f not in frontmatter]
+                if missing:
+                    issues.append({
+                        'file': change_file.name,
+                        'error': f'缺少欄位: {", ".join(missing)}'
+                    })
+                else:
+                    valid_count += 1
+
+            except Exception as e:
+                issues.append({
+                    'file': change_file.name,
+                    'error': str(e)
+                })
+
+        self.result['checks']['changes_format'] = {
+            'valid_count': valid_count,
+            'issues': issues
+        }
+
+        for issue in issues:
+            self.result['warnings'].append(
+                f"變更格式問題: {issue['file']} - {issue['error']}"
+            )
+
+    def check_stale_changes(self):
+        """檢查過期的變更提案（超過 7 天未處理）"""
+        changes_dir = self.openspec_dir / 'changes'
+        if not changes_dir.exists():
+            return
+
+        stale = []
+        now = time.time()
+        seven_days = 7 * 24 * 60 * 60
+
+        for change_file in changes_dir.glob('*.md'):
+            mtime = change_file.stat().st_mtime
+            age_days = (now - mtime) / (24 * 60 * 60)
+
+            if now - mtime > seven_days:
+                stale.append({
+                    'file': change_file.stem,
+                    'age_days': int(age_days)
+                })
+
+        self.result['checks']['stale_changes'] = {
+            'count': len(stale),
+            'changes': stale
+        }
+
+        for change in stale:
+            self.result['warnings'].append(
+                f"過期變更: {change['file']} (已 {change['age_days']} 天未處理)"
+            )
+
+    def check_consistency(self):
+        """檢查 specs 與 changes 的一致性"""
+        specs_dir = self.openspec_dir / 'specs'
+        changes_dir = self.openspec_dir / 'changes'
+
+        if not specs_dir.exists() or not changes_dir.exists():
+            return
+
+        # 收集 specs 中參照的變更
+        referenced_changes = set()
+        for spec_file in specs_dir.glob('*.md'):
+            try:
+                content = spec_file.read_text(encoding='utf-8')
+                # 簡單解析 changes 參照 (格式: [[change-name]])
+                refs = re.findall(r'\[\[([^\]]+)\]\]', content)
+                referenced_changes.update(refs)
+            except Exception:
+                pass
+
+        # 檢查 changes 目錄中的檔案
+        existing_changes = {f.stem for f in changes_dir.glob('*.md')}
+
+        # 找出孤立的變更（在 changes/ 但沒被任何 spec 參照）
+        orphan_changes = existing_changes - referenced_changes
+
+        self.result['checks']['consistency'] = {
+            'specs_count': len(list(specs_dir.glob('*.md'))),
+            'changes_count': len(existing_changes),
+            'orphan_changes': list(orphan_changes)
+        }
+
+        # 孤立變更只是警告，不是錯誤
+        if orphan_changes:
+            for change in orphan_changes:
+                self.result['warnings'].append(
+                    f"孤立變更: {change} (未被任何規格參照)"
+                )
+
+    def _parse_frontmatter(self, content: str) -> dict | None:
+        """解析 YAML frontmatter
+
+        Args:
+            content: Markdown 檔案內容
+
+        Returns:
+            dict: frontmatter 資料，如果沒有則返回 None
+        """
+        # 檢查是否以 --- 開頭
+        if not content.startswith('---'):
+            return None
+
+        # 找到結束的 ---
+        end_match = re.search(r'\n---\n', content)
+        if not end_match:
+            return None
+
+        frontmatter_text = content[3:end_match.start()]
+
+        # 簡單解析 YAML (只處理 key: value 格式)
+        result = {}
+        for line in frontmatter_text.strip().split('\n'):
+            if ':' in line:
+                key, value = line.split(':', 1)
+                result[key.strip()] = value.strip().strip('"\'')
+
+        return result if result else None