Initial commit

2025-11-30 08:38:46 +08:00
commit 6902106648
49 changed files with 11466 additions and 0 deletions
--- a/.claude/commands/clean.md
+++ b/.claude/commands/clean.md
@@ -0,0 +1,758 @@
+---
+description: Remove dead code safely from codebase
+argument-hint: [scope]
+allowed-tools: Read, Write, Edit, Bash, Task, Glob, Grep
+model: claude-haiku-4-5-20251001
+---
+
+# `/lazy cleanup` - Safe Dead Code Removal
+
+You are the **Cleanup Command Handler** for LAZY-DEV-FRAMEWORK. Your role is to identify and safely remove dead code from the codebase while ensuring no regressions are introduced.
+
+## Command Overview
+
+**Purpose**: Remove dead code safely from codebase with comprehensive analysis and safety measures
+
+**Scope Options**:
+- `codebase` - Analyze entire project
+- `current-branch` - Only files changed in current git branch
+- `path/to/directory` - Specific directory or file path
+
+**Safety Modes**:
+- `--safe-mode true` (default) - Create git stash backup before changes
+- `--safe-mode false` - Skip backup (not recommended)
+- `--dry-run` - Preview changes without applying them
+
+## Usage Examples
+
+```bash
+# Analyze and clean entire codebase (with safety backup)
+/lazy cleanup codebase
+
+# Clean specific directory
+/lazy cleanup src/services
+
+# Preview cleanup without applying changes
+/lazy cleanup codebase --dry-run
+
+# Clean current branch only
+/lazy cleanup current-branch
+
+# Clean without backup (use with caution)
+/lazy cleanup src/legacy --safe-mode false
+```
+
+---
+
+## Workflow
+
+### Step 1: Parse Arguments and Validate Scope
+
+**Extract parameters**:
+```python
+# Parse scope argument
+scope = $1  # Required: codebase | current-branch | path/to/directory
+safe_mode = $2 or "true"  # Optional: true | false
+dry_run = $3  # Optional: --dry-run flag
+
+# Validate scope
+if scope == "codebase":
+    target_paths = ["."]  # Entire project
+elif scope == "current-branch":
+    # Get changed files in current branch
+    git diff --name-only main..HEAD
+    target_paths = [list of changed files]
+elif scope is a path:
+    # Verify path exists
+    if not os.path.exists(scope):
+        ERROR: "Path not found: {scope}"
+    target_paths = [scope]
+```
+
+**Display scan scope**:
+```
+🧹 Cleanup Analysis Starting...
+
+Scope: {scope}
+Target Paths: {target_paths}
+Safe Mode: {safe_mode}
+Dry Run: {dry_run}
+
+Scanning for dead code...
+```
+
+---
+
+### Step 2: Scan for Dead Code Patterns
+
+**Use Glob and Grep tools to identify**:
+
+#### A. Unused Imports
+```bash
+# Find imports that are never used
+# Pattern: import statements not referenced in code
+```
+
+#### B. Unused Functions/Methods
+```bash
+# Find functions/methods defined but never called
+# Pattern: def/async def with no references
+```
+
+#### C. Unused Variables
+```bash
+# Find variables assigned but never read
+# Pattern: variable = value, but no subsequent usage
+```
+
+#### D. Unreachable Code
+```bash
+# Find code after return/break/continue statements
+# Pattern: statements after control flow terminators
+```
+
+#### E. Commented-Out Code Blocks
+```bash
+# Find large blocks of commented code (>3 lines)
+# Pattern: consecutive lines starting with #
+```
+
+#### F. Orphaned Files
+```bash
+# Find files with no imports from other modules
+# Pattern: files not in any import statement across codebase
+```
+
+#### G. Deprecated Code
+```bash
+# Find code marked with @deprecated decorator or TODO: remove
+# Pattern: @deprecated, # TODO: remove, # DEPRECATED
+```
+
+---
+
+### Step 3: Invoke Cleanup Agent for Analysis
+
+**Call Cleanup Agent with findings**:
+
+```markdown
+@agent-cleanup
+
+You are the **Cleanup Agent** for LAZY-DEV-FRAMEWORK. Analyze code to identify dead code that can be safely removed.
+
+## Scan Results
+
+### Target Paths
+$paths
+
+### Dead Code Patterns to Identify
+- Unused imports
+- Unused functions/methods
+- Unused variables
+- Unreachable code
+- Commented-out code blocks (>3 lines)
+- Orphaned files (no references)
+- Deprecated code (marked for removal)
+
+### Analysis Mode
+Safe Mode: $safe_mode
+Dry Run: $dry_run
+
+## Your Task
+
+**Phase 1: Comprehensive Analysis**
+
+For each target path, analyze and identify:
+
+1. **Unused Imports**
+   - List import statements not referenced in code
+   - Provide: file, line number, import name
+
+2. **Unused Functions/Methods**
+   - Find functions/methods with zero call sites
+   - Exclude: __init__, __main__, test fixtures, public API methods
+   - Provide: file, line number, function name, reason safe to remove
+
+3. **Unused Variables**
+   - Find variables assigned but never read
+   - Exclude: loop variables, configuration variables
+   - Provide: file, line number, variable name
+
+4. **Unreachable Code**
+   - Find code after return/break/continue/raise
+   - Provide: file, line number range, code snippet
+
+5. **Commented-Out Code**
+   - Find consecutive commented lines (>3 lines) containing code
+   - Exclude: legitimate comments, docstrings
+   - Provide: file, line number range, size (lines)
+
+6. **Orphaned Files**
+   - Find files not imported anywhere in codebase
+   - Exclude: entry points, scripts, tests, __init__.py
+   - Provide: file path, size (lines), last modified date
+
+7. **Deprecated Code**
+   - Find code marked @deprecated or TODO: remove
+   - Provide: file, line number, deprecation reason
+
+**Phase 2: Safety Assessment**
+
+For each identified item, assess:
+- **Risk Level**: LOW | MEDIUM | HIGH
+- **Safe to Remove?**: YES | NO | MAYBE (requires review)
+- **Reason**: Why it's safe (or not safe) to remove
+- **Dependencies**: Any code that depends on this
+
+**Phase 3: Removal Recommendations**
+
+Categorize findings:
+
+✅ **Safe to Remove (Low Risk)**
+- Items with zero dependencies
+- Clearly unused code with no side effects
+
+⚠️ **Review Recommended (Medium Risk)**
+- Items with unclear usage patterns
+- Code that might be used via reflection/dynamic imports
+
+❌ **Do Not Remove (High Risk)**
+- Public API methods (even if unused internally)
+- Code with external dependencies
+- Configuration code
+- Test fixtures
+
+## Output Format
+
+```yaml
+dead_code_analysis:
+  summary:
+    total_items: N
+    safe_to_remove: N
+    review_recommended: N
+    do_not_remove: N
+
+  safe_removals:
+    unused_imports:
+      - file: "path/to/file.py"
+        line: 5
+        import: "from module import unused_function"
+        reason: "No references to unused_function in file"
+
+    unused_functions:
+      - file: "path/to/file.py"
+        line_start: 42
+        line_end: 58
+        function: "old_helper()"
+        reason: "Zero call sites across entire codebase"
+
+    commented_code:
+      - file: "path/to/file.py"
+        line_start: 100
+        line_end: 125
+        size_lines: 25
+        reason: "Block comment contains old implementation"
+
+    orphaned_files:
+      - file: "src/old_utils.py"
+        size_lines: 200
+        reason: "No imports found across codebase"
+
+  review_recommended:
+    - file: "path/to/file.py"
+      line: 78
+      code: "def potentially_used()"
+      reason: "Might be used via dynamic import or reflection"
+
+  total_lines_to_remove: N
+```
+```
+
+**Agent will return structured analysis for next step.**
+
+---
+
+### Step 4: Present Findings for User Approval
+
+**Display findings summary**:
+
+```
+🧹 Cleanup Analysis Complete
+
+Dead Code Found:
+
+✅ SAFE TO REMOVE:
+  ✓ {N} unused imports in {X} files
+  ✓ {N} unused functions ({X} lines)
+  ✓ {N} unused variables
+  ✓ {N} unreachable code blocks ({X} lines)
+  ✓ {N} lines of commented code
+  ✓ {N} orphaned files ({file1.py, file2.py})
+
+⚠️  REVIEW RECOMMENDED:
+  ! {N} items need manual review:
+    - {item1}: {reason}
+    - {item2}: {reason}
+
+📊 Impact:
+  Total lines to remove: {N}
+  Files affected: {X}
+  Estimated time saved: {Y} minutes in future maintenance
+
+🔒 Safety:
+  Safe mode: {enabled/disabled}
+  Dry run: {yes/no}
+  Backup: {will be created/skipped}
+```
+
+**Ask user for approval**:
+
+```
+Apply cleanup?
+
+Options:
+  [y] Yes - Apply all safe removals
+  [n] No - Cancel cleanup
+  [p] Preview - Show detailed preview of each change
+  [s] Selective - Review each item individually
+
+Your choice:
+```
+
+---
+
+### Step 5: Apply Cleanup (If Approved)
+
+#### If user selects "Preview" (p):
+```
+📝 Detailed Preview:
+
+1. UNUSED IMPORT: path/to/file.py:5
+   Remove: from module import unused_function
+   Reason: No references in file
+
+2. UNUSED FUNCTION: path/to/file.py:42-58
+   Remove: def old_helper(): ...
+   Reason: Zero call sites
+   Code preview:
+   ```python
+   def old_helper():
+       # 16 lines
+       ...
+   ```
+
+3. ORPHANED FILE: src/old_utils.py
+   Remove: entire file (200 lines)
+   Reason: No imports found
+   Last modified: 2024-08-15
+
+[Continue preview...]
+
+Apply these changes? (y/n):
+```
+
+#### If user selects "Selective" (s):
+```
+Review each item:
+
+1/15: UNUSED IMPORT: path/to/file.py:5
+      Remove: from module import unused_function
+      Apply? (y/n/q):
+```
+
+#### If user approves (y):
+
+**Create safety backup** (if safe_mode=true):
+```bash
+# Create git stash with timestamp
+git stash push -m "cleanup-backup-$(date +%Y%m%d-%H%M%S)" --include-untracked
+
+# Output:
+💾 Safety backup created: stash@{0}
+   To restore: git stash apply stash@{0}
+```
+
+**Apply removals using Edit tool**:
+```python
+# For each safe removal:
+# 1. Use Edit tool to remove unused imports
+# 2. Use Edit tool to remove unused functions
+# 3. Use Edit tool to remove commented blocks
+# 4. Use Bash tool to remove orphaned files
+
+# Track changes
+changes_applied = []
+```
+
+**Display progress**:
+```
+🧹 Applying cleanup...
+
+✅ Removed unused imports (5 files)
+✅ Removed unused functions (3 files)
+✅ Removed commented code (8 files)
+✅ Removed orphaned files (2 files)
+
+Total: 250 lines removed from 12 files
+```
+
+---
+
+### Step 6: Run Quality Pipeline
+
+**CRITICAL: Must pass quality gates before commit**
+
+```bash
+# Run quality checks
+1. Format: python scripts/format.py {changed_files}
+2. Lint: python scripts/lint.py {changed_files}
+3. Type: python scripts/type_check.py {changed_files}
+4. Test: python scripts/test_runner.py
+
+# If ANY check fails:
+  - Restore from backup: git stash apply
+  - Report error to user
+  - Return: "Cleanup failed quality checks, changes reverted"
+```
+
+**Display quality results**:
+```
+📊 Quality Pipeline: RUNNING...
+
+✅ Format (Black/Ruff): PASS
+✅ Lint (Ruff): PASS
+✅ Type Check (Mypy): PASS
+✅ Tests (Pytest): PASS
+   - 124/124 tests passing
+   - Coverage: 87% (unchanged)
+
+All quality checks passed! ✅
+```
+
+---
+
+### Step 7: Commit Changes
+
+**Create commit** (if quality passes):
+
+```bash
+git add {changed_files}
+
+git commit -m "$(cat <<'EOF'
+chore(cleanup): remove dead code
+
+Cleanup scope: {scope}
+Files affected: {N}
+Lines removed: {M}
+
+Items removed:
+- {N} unused imports
+- {N} unused functions
+- {N} commented code blocks
+- {N} orphaned files
+
+Quality pipeline: PASSED
+All tests passing: ✅
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Step 8: Return Summary
+
+**Final output**:
+
+```
+✅ Cleanup Complete
+
+📊 Summary:
+  Scope: {scope}
+  Files modified: {N}
+  Files deleted: {N}
+  Lines removed: {M}
+
+  Items removed:
+  ✓ {N} unused imports
+  ✓ {N} unused functions
+  ✓ {N} unused variables
+  ✓ {N} unreachable code blocks
+  ✓ {N} lines of commented code
+  ✓ {N} orphaned files
+
+📊 Quality Pipeline: PASS
+  ✅ Format (Black/Ruff)
+  ✅ Lint (Ruff)
+  ✅ Type Check (Mypy)
+  ✅ Tests (Pytest)
+
+💾 Committed: {commit_sha}
+  Message: "chore(cleanup): remove dead code"
+
+💾 Safety Backup: {stash_id}
+  To restore if needed: git stash apply {stash_id}
+
+🎯 Impact:
+  Code reduction: {M} lines
+  Maintainability: Improved
+  Future time saved: ~{X} minutes
+```
+
+---
+
+## Error Handling
+
+### Git Issues
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| **Not a git repository** | No .git directory | Initialize: `git init`, retry |
+| **Dirty working tree** | Uncommitted changes | Commit or stash changes first |
+| **Stash creation failed** | No changes to stash | Disable safe mode, retry |
+
+### Cleanup Issues
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| **No dead code found** | Clean codebase | Return: "No dead code detected" |
+| **Agent timeout** | Large codebase | Reduce scope, retry with specific path |
+| **Path not found** | Invalid scope argument | Verify path exists, retry |
+
+### Quality Pipeline Failures
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| **Format failed** | Syntax errors introduced | Restore from stash: `git stash apply`, report issue |
+| **Lint failed** | Code quality regressions | Restore from stash, report issue |
+| **Type check failed** | Type errors introduced | Restore from stash, report issue |
+| **Tests failed** | Removed code was not actually dead | Restore from stash, mark as unsafe removal |
+
+**Failure recovery pattern**:
+```bash
+# If quality pipeline fails:
+echo "❌ Cleanup failed at: {stage}"
+echo "🔄 Restoring from backup..."
+git stash apply {stash_id}
+echo "✅ Changes reverted"
+echo ""
+echo "Issue: {error_details}"
+echo "Action: Review removals manually or report issue"
+```
+
+---
+
+## Safety Constraints
+
+**DO NOT REMOVE**:
+- Public API methods (even if unused internally)
+- Test fixtures and test utilities
+- Configuration variables
+- __init__.py files
+- __main__.py entry points
+- Code marked with # KEEP or # DO_NOT_REMOVE comments
+- Callbacks registered via decorators
+- Code used via reflection/dynamic imports
+
+**ALWAYS**:
+- Create backup before changes (unless --safe-mode false)
+- Run full quality pipeline before commit
+- Ask for user approval before applying changes
+- Show detailed preview if requested
+- Provide restoration instructions
+
+**NEVER**:
+- Remove code without analysis
+- Skip quality checks
+- Commit failing tests
+- Remove files without verifying zero references
+
+---
+
+## Best Practices
+
+### 1. Conservative Approach
+- When in doubt, mark for review (don't auto-remove)
+- Prefer false negatives (keep code) over false positives (remove needed code)
+
+### 2. Thorough Analysis
+- Check entire codebase for references, not just local file
+- Consider reflection, dynamic imports, getattr() usage
+- Exclude public APIs from unused function detection
+
+### 3. Quality First
+- ALWAYS run quality pipeline
+- NEVER commit with failing tests
+- Verify type checking passes
+
+### 4. User Communication
+- Show clear preview before changes
+- Provide detailed removal reasons
+- Offer selective approval option
+- Display impact metrics
+
+### 5. Safety Nets
+- Default to safe mode (backup)
+- Provide restoration instructions
+- Auto-revert on quality failures
+- Log all removals for audit
+
+---
+
+## Example Execution
+
+### Command
+```bash
+/lazy cleanup src/services
+```
+
+### Output
+```
+🧹 Cleanup Analysis Starting...
+
+Scope: src/services
+Target Paths: ['src/services']
+Safe Mode: enabled
+Dry Run: no
+
+Scanning for dead code...
+
+🔍 Analyzing: src/services/auth.py
+🔍 Analyzing: src/services/payment.py
+🔍 Analyzing: src/services/notification.py
+
+🧹 Cleanup Analysis Complete
+
+Dead Code Found:
+
+✅ SAFE TO REMOVE:
+  ✓ 5 unused imports in 3 files
+  ✓ 2 unused functions (35 lines)
+  ✓ 3 unused variables
+  ✓ 1 unreachable code block (8 lines)
+  ✓ 50 lines of commented code
+  ✓ 1 orphaned file (old_utils.py, 200 lines)
+
+📊 Impact:
+  Total lines to remove: 293
+  Files affected: 4
+  Estimated time saved: 15 minutes in future maintenance
+
+🔒 Safety:
+  Safe mode: enabled
+  Dry run: no
+  Backup: will be created
+
+Apply cleanup? (y/n/p/s): y
+
+💾 Safety backup created: stash@{0}
+   To restore: git stash apply stash@{0}
+
+🧹 Applying cleanup...
+
+✅ Removed unused imports (3 files)
+✅ Removed unused functions (2 files)
+✅ Removed commented code (3 files)
+✅ Removed orphaned file: src/services/old_utils.py
+
+Total: 293 lines removed from 4 files
+
+📊 Quality Pipeline: RUNNING...
+
+✅ Format (Black/Ruff): PASS
+✅ Lint (Ruff): PASS
+✅ Type Check (Mypy): PASS
+✅ Tests (Pytest): PASS
+   - 124/124 tests passing
+   - Coverage: 87% (unchanged)
+
+All quality checks passed! ✅
+
+💾 Committing changes...
+
+✅ Cleanup Complete
+
+📊 Summary:
+  Scope: src/services
+  Files modified: 3
+  Files deleted: 1
+  Lines removed: 293
+
+  Items removed:
+  ✓ 5 unused imports
+  ✓ 2 unused functions
+  ✓ 3 unused variables
+  ✓ 1 unreachable code block
+  ✓ 50 lines of commented code
+  ✓ 1 orphaned file
+
+📊 Quality Pipeline: PASS
+
+💾 Committed: abc123def
+  Message: "chore(cleanup): remove dead code"
+
+💾 Safety Backup: stash@{0}
+  To restore if needed: git stash apply stash@{0}
+
+🎯 Impact:
+  Code reduction: 293 lines
+  Maintainability: Improved
+  Future time saved: ~15 minutes
+```
+
+---
+
+## Session Logging
+
+All cleanup activities logged to `logs/<session-id>/cleanup.json`:
+
+```json
+{
+  "command": "/lazy cleanup",
+  "scope": "src/services",
+  "safe_mode": true,
+  "dry_run": false,
+  "timestamp": "2025-10-26T10:30:00Z",
+  "analysis": {
+    "total_items_found": 15,
+    "safe_to_remove": 12,
+    "review_recommended": 3,
+    "do_not_remove": 0
+  },
+  "removals": {
+    "unused_imports": 5,
+    "unused_functions": 2,
+    "unused_variables": 3,
+    "unreachable_code": 1,
+    "commented_code": 1,
+    "orphaned_files": 1
+  },
+  "impact": {
+    "files_modified": 3,
+    "files_deleted": 1,
+    "lines_removed": 293
+  },
+  "quality_pipeline": {
+    "format": "pass",
+    "lint": "pass",
+    "type_check": "pass",
+    "tests": "pass"
+  },
+  "commit": {
+    "sha": "abc123def",
+    "message": "chore(cleanup): remove dead code"
+  },
+  "backup": {
+    "stash_id": "stash@{0}",
+    "created": true
+  }
+}
+```
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2025-10-26
+**Framework**: LAZY-DEV-FRAMEWORK