@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/configuration-review.md

@@ -0,0 +1,425 @@
+# Configuration Review Guide
+
+> Comprehensive guide for reviewing XML, YAML, JSON, TOML, and environment configuration files.
+
+## Table of Contents
+
+- [Configuration File Types](#configuration-file-types)
+- [XML Configuration Review](#xml-configuration-review)
+- [YAML Configuration Review](#yaml-configuration-review)
+- [JSON Configuration Review](#json-configuration-review)
+- [Environment Files Review](#environment-files-review)
+- [Security Checklist](#security-checklist)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+---
+
+## Configuration File Types
+
+| Format | Common Uses | Key Concerns |
+|--------|-------------|--------------|
+| **XML** | Java/Spring, .NET, Maven, Hibernate | Verbosity, schema validation, XXE attacks |
+| **YAML** | Kubernetes, Docker, CI/CD, Ansible | Indentation errors, type coercion |
+| **JSON** | Package managers, APIs, settings | No comments, strict syntax |
+| **TOML** | Rust (Cargo), Python (pyproject) | Section ordering, type clarity |
+| **.env** | Environment variables | Secrets exposure, format errors |
+| **INI** | Legacy apps, Windows | Limited structure |
+| **Properties** | Java applications | Encoding issues |
+
+---
+
+## XML Configuration Review
+
+### Common XML Issues
+
+| Issue | Risk | Example |
+|-------|------|---------|
+| **XXE Vulnerability** | Remote code execution | External entity injection |
+| **Secrets in XML** | Credential exposure | Plaintext passwords |
+| **Invalid Schema** | Runtime errors | Missing required elements |
+| **Encoding Issues** | Character corruption | Wrong encoding declaration |
+
+### XXE Vulnerability Detection
+
+```xml
+<!-- 🔴 VULNERABLE: XXE attack possible -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE foo [
+  <!ENTITY xxe SYSTEM "https://example.invalid/xxe">
+]>
+<data>&xxe;</data>
+
+<!-- Check parser configuration -->
+<!-- Java: Disable external entities -->
+<!-- factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true); -->
+```
+
+### Spring/Java XML Review
+
+```xml
+<!-- 🔴 BUG: Hardcoded credentials -->
+<bean id="dataSource" class="...DataSource">
+    <property name="password" value="supersecret"/>
+</bean>
+
+<!-- ✅ FIX: Use placeholder -->
+<bean id="dataSource" class="...DataSource">
+    <property name="password" value="${db.password}"/>
+</bean>
+
+<!-- 🔴 BUG: Overly permissive CORS -->
+<mvc:cors>
+    <mvc:mapping path="/**" allowed-origins="*"/>
+</mvc:cors>
+
+<!-- ✅ FIX: Specific origins -->
+<mvc:cors>
+    <mvc:mapping path="/api/**" allowed-origins="https://myapp.com"/>
+</mvc:cors>
+```
+
+### Maven pom.xml Review
+
+```xml
+<!-- 🔴 BUG: Dependency without version -->
+<dependency>
+    <groupId>com.example</groupId>
+    <artifactId>library</artifactId>
+</dependency>
+
+<!-- ✅ FIX: Pin version -->
+<dependency>
+    <groupId>com.example</groupId>
+    <artifactId>library</artifactId>
+    <version>1.2.3</version>
+</dependency>
+
+<!-- 🔴 BUG: Known vulnerable dependency -->
+<dependency>
+    <groupId>log4j</groupId>
+    <artifactId>log4j</artifactId>
+    <version>1.2.17</version>  <!-- CVE-2021-44228 -->
+</dependency>
+```
+
+### .NET web.config Review
+
+```xml
+<!-- 🔴 BUG: Debug mode in production -->
+<system.web>
+    <compilation debug="true"/>
+</system.web>
+
+<!-- ✅ FIX: Debug off in production -->
+<system.web>
+    <compilation debug="false"/>
+</system.web>
+
+<!-- 🔴 BUG: Custom errors disabled -->
+<system.web>
+    <customErrors mode="Off"/>
+</system.web>
+
+<!-- ✅ FIX: Show generic errors -->
+<system.web>
+    <customErrors mode="RemoteOnly" defaultRedirect="/Error"/>
+</system.web>
+
+<!-- 🔴 BUG: Plaintext connection string -->
+<connectionStrings>
+    <add name="DB" connectionString="...Password=secret..."/>
+</connectionStrings>
+
+<!-- ✅ FIX: Use encrypted sections or environment -->
+```
+
+---
+
+## YAML Configuration Review
+
+### Common YAML Pitfalls
+
+| Issue | Example | Problem |
+|-------|---------|---------|
+| **Type Coercion** | `version: 1.0` | Parsed as float, not string |
+| **Boolean Confusion** | `on: true`, `yes: 1` | Unexpected boolean conversion |
+| **Indentation** | Mixed tabs/spaces | Parse errors |
+| **Multiline Strings** | Improper folding | Whitespace issues |
+
+### YAML Type Coercion Bugs
+
+```yaml
+# 🔴 BUG: Version parsed as float (becomes 1)
+version: 1.0
+
+# ✅ FIX: Quote to keep as string
+version: "1.0"
+
+# 🔴 BUG: Norway country code parsed as boolean
+countries:
+  - NO  # Parsed as false!
+
+# ✅ FIX: Quote it
+countries:
+  - "NO"
+
+# 🔴 BUG: Timestamp parsed unexpectedly
+date: 2024-01-01  # Parsed as datetime, not string
+
+# ✅ FIX: Quote if string needed
+date: "2024-01-01"
+
+# 🔴 BUG: Octal number confusion
+port: 0755  # May be parsed as octal (493 decimal)
+
+# ✅ FIX: Quote or use explicit decimal
+port: 755
+```
+
+### Kubernetes YAML Issues
+
+```yaml
+# 🔴 BUG: Wrong indentation (spec at wrong level)
+apiVersion: v1
+kind: Pod
+  spec:  # Should not be indented
+    containers: []
+
+# ✅ FIX: Correct indentation
+apiVersion: v1
+kind: Pod
+spec:
+  containers: []
+
+# 🔴 BUG: Multiline string incorrectly formatted
+env:
+  - name: CONFIG
+    value: line1
+      line2  # This is invalid YAML
+
+# ✅ FIX: Use block scalar
+env:
+  - name: CONFIG
+    value: |
+      line1
+      line2
+```
+
+### Ansible YAML Review
+
+```yaml
+# 🔴 BUG: Hardcoded password
+- name: Create user
+  user:
+    name: admin
+    password: supersecret
+
+# ✅ FIX: Use vault-encrypted variable
+- name: Create user
+  user:
+    name: admin
+    password: "{{ vault_admin_password }}"
+
+# 🔴 BUG: No become for privileged operation
+- name: Install package
+  apt:
+    name: nginx
+
+# ✅ FIX: Add become
+- name: Install package
+  apt:
+    name: nginx
+  become: yes
+```
+
+---
+
+## JSON Configuration Review
+
+### Common JSON Issues
+
+| Issue | Problem | Impact |
+|-------|---------|--------|
+| **Trailing Comma** | Invalid JSON | Parse failure |
+| **Comments** | Not allowed in JSON | Parse failure |
+| **Duplicate Keys** | Undefined behavior | Unpredictable |
+| **Large Numbers** | Precision loss | Data corruption |
+
+### package.json Review
+
+```json
+// 🔴 BUG: Range version (non-reproducible)
+{
+  "dependencies": {
+    "lodash": "^4.0.0"
+  }
+}
+
+// ✅ FIX: Use lockfile (package-lock.json) and consider exact versions
+{
+  "dependencies": {
+    "lodash": "4.17.21"
+  }
+}
+
+// 🔴 BUG: Script with inline secret
+{
+  "scripts": {
+    "deploy": "API_KEY=abc123 deploy.sh"
+  }
+}
+
+// ✅ FIX: Use environment variable
+{
+  "scripts": {
+    "deploy": "deploy.sh"
+  }
+}
+```
+
+### tsconfig.json / jsconfig.json
+
+```json
+// 🔴 BUG: Overly permissive TypeScript
+{
+  "compilerOptions": {
+    "strict": false,
+    "any": true
+  }
+}
+
+// ✅ FIX: Enable strict mode
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true
+  }
+}
+```
+
+---
+
+## Environment Files Review
+
+### .env File Security
+
+```bash
+# 🔴 BUG: .env in git
+# Check: git ls-files | grep -E "\.env$"
+
+# 🔴 BUG: Production secrets in .env.example
+# .env.example should have placeholder values only
+DATABASE_URL=postgres://user:CHANGE_ME@localhost/db
+
+# 🔴 BUG: Weak/default secrets
+SECRET_KEY=secret
+API_KEY=test123
+
+# ✅ GOOD: Strong random values
+SECRET_KEY=a1b2c3d4e5f6...  # Generated securely
+```
+
+### Environment Variable Patterns
+
+| Pattern | Risk | Better |
+|---------|------|--------|
+| `PASSWORD=xxx` in code | Exposed in version control | Environment variable |
+| `SECRET=xxx` in CI logs | Visible in build output | Masked secrets |
+| Shared `.env` file | Multiple environments mixed | Separate env files |
+
+### Detection Commands
+
+```bash
+# Find .env files
+find . -name ".env*" -type f 2>/dev/null
+
+# Check if .env is in git
+git ls-files | grep -E "\.env$"
+
+# Find hardcoded secrets in env files
+grep -rn "password=\|secret=\|api_key=" --include="*.env*"
+
+# Validate .env format
+grep -v "^#\|^$\|^[A-Z_]*=" .env  # Should return nothing
+```
+
+---
+
+## Security Checklist
+
+### Configuration Security Review
+
+```markdown
+## Configuration Security Checklist
+
+### Secrets
+- [ ] No plaintext secrets in any config file
+- [ ] Secrets use environment variables or secrets manager
+- [ ] Example files have placeholder values only
+- [ ] .env files are gitignored
+
+### Validation
+- [ ] XML files have schema validation
+- [ ] Required fields are validated
+- [ ] Type coercion issues addressed
+- [ ] Version numbers are quoted strings
+
+### Permissions
+- [ ] Config files have appropriate permissions (not world-readable)
+- [ ] Sensitive configs separated from general configs
+- [ ] Production configs protected
+
+### Environment Separation
+- [ ] Dev/staging/prod configs are separate
+- [ ] No prod secrets in dev configs
+- [ ] Environment-specific overrides work correctly
+```
+
+---
+
+## Common Anti-Patterns
+
+### Configuration Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **God Config** | Single file with everything | Split by concern |
+| **Config Duplication** | Same values in multiple places | Use shared/base configs |
+| **Magic Values** | Unexplained numbers/strings | Add comments or constants |
+| **Environment Coupling** | Code checks environment name | Use feature flags |
+| **Missing Defaults** | Fails if config not set | Provide sensible defaults |
+
+### Environment-Specific Issues
+
+```python
+# 🔴 BAD: Checking environment name
+if os.environ.get("ENV") == "production":
+    enable_feature_x()
+
+# ✅ GOOD: Feature flag
+if os.environ.get("FEATURE_X_ENABLED", "false") == "true":
+    enable_feature_x()
+
+# 🔴 BAD: Default to development behavior
+DEBUG = os.environ.get("DEBUG", True)  # Dangerous default!
+
+# ✅ GOOD: Secure default
+DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
+```
+
+### Configuration Validation Pattern
+
+```python
+# ✅ GOOD: Validate configuration at startup
+def validate_config():
+    required = ["DATABASE_URL", "SECRET_KEY", "API_KEY"]
+    missing = [var for var in required if not os.environ.get(var)]
+    
+    if missing:
+        raise ValueError(f"Missing required config: {', '.join(missing)}")
+    
+    if len(os.environ.get("SECRET_KEY", "")) < 32:
+        raise ValueError("SECRET_KEY must be at least 32 characters")
+```
+

package/.claude/skills/code-review/references/control-flow-completeness.md

@@ -0,0 +1,114 @@
+# Control Flow Completeness (控制流完整性检查)
+
+**核心问题**：代码中的 `break/return/throw` 等早期退出语句，是否有合理的后续处理？
+
+## 🔴 必检场景
+
+### 1. 循环中的 break
+
+**问题模式**：
+```python
+for step in range(max_steps):
+    if some_condition_fails:
+        break  # ❌ 退出后没有任何处理
+    
+    # ... 正常逻辑
+# 循环结束后没有代码处理 break 的情况
+```
+
+**正确模式**：
+```python
+result = None
+for step in range(max_steps):
+    if some_condition_fails:
+        # ✅ 设置回退值或执行降级逻辑
+        result = fallback_result()
+        break
+    
+    result = process_step()
+
+# ✅ 确保 result 有值
+if result is None:
+    result = handle_no_result()
+return result
+```
+
+### 2. 异步生成器/流式输出中的 break
+
+**问题模式**：
+```python
+async def stream_response():
+    for step in range(max_steps):
+        if token_limit_exceeded:
+            break  # ❌ 流直接结束，用户看到空回复
+        
+        async for chunk in llm.stream(messages):
+            yield chunk
+```
+
+**正确模式**：
+```python
+async def stream_response():
+    yielded_any = False
+    for step in range(max_steps):
+        if token_limit_exceeded:
+            if not yielded_any:
+                # ✅ 确保至少有一个回复
+                yield create_fallback_response("由于限制，无法完整处理请求")
+            break
+        
+        async for chunk in llm.stream(messages):
+            yielded_any = True
+            yield chunk
+    
+    # ✅ 循环结束后检查是否有输出
+    if not yielded_any:
+        yield create_error_response("处理失败")
+```
+
+### 3. 条件判断中的 return
+
+**问题模式**：
+```python
+async def process_request(request):
+    if not is_safe:
+        return  # ❌ 静默返回，调用者不知道发生了什么
+    
+    # ... 正常逻辑
+```
+
+**正确模式**：
+```python
+async def process_request(request):
+    if not is_safe:
+        # ✅ 返回有意义的结果或抛出异常
+        return ProcessResult(success=False, reason="Safety check failed")
+    
+    # ... 正常逻辑
+```
+
+## 检查清单
+
+| # | 检查项 | Severity |
+|---|-------|----------|
+| 1 | 每个 `break` 后，循环外是否有代码处理这种情况？ | P0 |
+| 2 | 每个 `return` 是否返回有意义的值（非 None/空）？ | P1 |
+| 3 | 生成器/流式函数中的 `break`，是否确保至少有一个输出？ | P0 |
+| 4 | 异常处理中的 `return`，是否有日志/通知？ | P1 |
+| 5 | 循环结束后，是否处理了"所有迭代都 break 了"的情况？ | P0 |
+
+## 典型 Bug 模式
+
+| 模式 | 问题 | 解决方案 |
+|------|------|---------|
+| Silent Break | break 后没有任何处理 | 添加回退逻辑或状态标记 |
+| Empty Stream | 流式输出提前中断 | 确保至少有一个输出 |
+| Void Return | return 没有返回值 | 返回有意义的结果或抛异常 |
+| Lost Context | break 后丢失上下文 | 在 break 前保存必要状态 |
+
+## 检测方法
+
+1. 搜索所有 `break` 语句：`grep -n "break" file.py`
+2. 检查循环后是否有代码处理 break 情况
+3. 搜索所有 `return` 语句，检查返回值是否有意义
+4. 对于流式函数，确认是否有"确保输出"的逻辑