Initial commit

2025-11-29 18:00:50 +08:00
commit c5931553a6
106 changed files with 49995 additions and 0 deletions
--- a/skills/fullstack-validation/SKILL.md
+++ b/skills/fullstack-validation/SKILL.md
@@ -0,0 +1,462 @@
+---
+name: fullstack-validation
+description: Comprehensive validation methodology for multi-component applications including backend, frontend, database, and infrastructure
+version: 2.0.0
+---
+
+## Overview
+
+This skill provides systematic approaches for validating full-stack applications with multiple interconnected components. It enables automatic detection of project structure, parallel validation workflows, cross-component verification, and identification of integration issues.
+
+**When to use**: Full-stack projects with backend + frontend, microservices, monorepos, Docker Compose setups, or any multi-technology application.
+
+**Key innovation**: Parallel validation with cross-component awareness - validates each layer independently while ensuring they work together correctly.
+
+## Project Structure Detection
+
+### Detection Patterns
+
+**Monorepo Indicators**:
+- Root `package.json` with workspaces
+- `lerna.json` or `nx.json` present
+- Multiple `package.json` files in subdirectories
+- `pnpm-workspace.yaml` present
+
+**Separate Repos Indicators**:
+- Single technology stack per repository
+- Docker Compose references external services
+- Git submodules present
+
+**Technology Stack Detection**:
+```
+Backend:
+- FastAPI: requirements.txt with 'fastapi', main.py with FastAPI app
+- Django: manage.py, settings.py present
+- Express: package.json with 'express', app.js/index.js
+- Spring Boot: pom.xml or build.gradle with spring-boot
+
+Frontend:
+- React: package.json with 'react', src/App.tsx or src/App.jsx
+- Vue: package.json with 'vue', src/App.vue
+- Angular: package.json with '@angular/core', angular.json
+- Svelte: package.json with 'svelte', src/App.svelte
+
+Database:
+- PostgreSQL: requirements.txt with 'psycopg2', docker-compose.yml with postgres
+- MySQL: package.json with 'mysql2', docker-compose.yml with mysql
+- MongoDB: package.json with 'mongoose', docker-compose.yml with mongo
+- Redis: docker-compose.yml with redis, requirements.txt with 'redis'
+
+Infrastructure:
+- Docker: Dockerfile, docker-compose.yml present
+- Kubernetes: k8s/ or kubernetes/ directory with .yaml files
+- Terraform: .tf files present
+- Nginx: nginx.conf present
+```
+
+## Validation Workflows
+
+### Backend Validation Checklist
+
+**Python/FastAPI Projects**:
+1. Dependency validation
+   - Check requirements.txt exists and is parseable
+   - Verify all imports can be resolved
+   - Check for version conflicts
+   - Validate Python version compatibility
+
+2. Type checking
+   - Run mypy on all source files
+   - Check for missing type hints
+   - Validate Pydantic model definitions
+   - Verify return type annotations
+
+3. Test validation
+   - Run pytest with coverage
+   - Check test isolation (database cleanup)
+   - Validate fixture dependencies
+   - Ensure no test data pollution
+   - Check for views/triggers blocking teardown
+
+4. API schema validation
+   - Extract OpenAPI/Swagger schema
+   - Validate all endpoints have docstrings
+   - Check request/response models
+   - Verify authentication decorators
+
+5. Database migration validation
+   - Check Alembic migrations are sequential
+   - Validate up/down migration pairs
+   - Ensure migrations are reversible
+   - Check for data loss risks
+
+**Node.js/Express Projects**:
+1. Dependency validation (npm/yarn/pnpm)
+2. ESLint validation
+3. Jest/Mocha test execution
+4. API route validation
+5. Database migration validation (Knex/Sequelize)
+
+### Frontend Validation Checklist
+
+**React + TypeScript Projects**:
+1. TypeScript validation
+   - Run tsc --noEmit for type checking
+   - Detect unused imports (auto-fix available)
+   - Check tsconfig.json strictness
+   - Validate path aliases (@/ imports)
+   - Generate missing .d.ts files (vite-env.d.ts, etc.)
+
+2. Dependency validation
+   - Check package.json for peer dependency warnings
+   - Detect version mismatches (React Query vs React)
+   - Validate ESM vs CommonJS consistency
+   - Check for deprecated packages
+
+3. Build validation
+   - Run production build (npm run build / vite build)
+   - Check bundle size (warn if > 1MB per chunk)
+   - Validate environment variables
+   - Check for build warnings
+   - Validate asset optimization
+
+4. Code quality
+   - Run ESLint with auto-fix
+   - Check for console.log statements in production
+   - Validate React hooks usage
+   - Check for deprecated React patterns
+   - Detect old library syntax (React Query v4 → v5)
+
+5. API client validation
+   - Check all API calls have error handling
+   - Validate API base URLs
+   - Ensure loading/error states exist
+   - Check authentication token handling
+
+**Vue/Angular Projects**: Similar checklist adapted to framework specifics
+
+### Database Validation Checklist
+
+1. Schema validation
+   - Check all tables exist
+   - Validate foreign key constraints
+   - Check for orphaned records
+   - Validate indexes on frequently queried columns
+
+2. Test isolation validation
+   - Detect views dependent on test tables
+   - Check for triggers that prevent cleanup
+   - Validate CASCADE deletion works
+   - Ensure test data doesn't leak to other tests
+
+3. Query validation
+   - Check for N+1 query problems
+   - Validate JOIN efficiency
+   - Check for missing indexes
+   - Detect raw SQL strings (SQLAlchemy 2.0 requires text() wrapper)
+
+### Infrastructure Validation Checklist
+
+**Docker Compose Projects**:
+1. Service health checks
+   - Verify all services start successfully
+   - Check healthcheck endpoints respond
+   - Validate depends_on order is correct
+   - Check restart policies
+
+2. Port conflict detection
+   - Ensure no duplicate port mappings
+   - Check host ports are available
+   - Validate internal service communication
+
+3. Volume validation
+   - Check mounted directories exist
+   - Validate volume permissions
+   - Ensure persistent data volumes are defined
+
+4. Environment variable validation
+   - Check .env.example matches required vars
+   - Validate all services receive needed env vars
+   - Check for hardcoded credentials
+   - Ensure secrets are not committed
+
+## Cross-Component Validation
+
+### API Contract Validation
+
+**Process**:
+1. Extract backend API schema
+   - FastAPI: GET /docs → openapi.json
+   - Express: Parse route definitions
+   - Django REST: GET /schema
+
+2. Extract frontend API client calls
+   - Search for axios/fetch calls
+   - Find API client service files
+   - Parse API endpoint strings
+
+3. Cross-validate
+   - Check every frontend call has matching backend endpoint
+   - Validate HTTP methods match (GET/POST/PUT/DELETE)
+   - Check parameter names and types match
+   - Verify response types match frontend expectations
+   - Detect missing error handling
+
+**Auto-fix capabilities**:
+- Generate missing TypeScript types from OpenAPI schema
+- Generate missing API client methods
+- Update deprecated endpoint calls
+- Add missing error handling
+
+### Environment Variable Consistency
+
+**Process**:
+1. Collect all env var references
+   - Backend: os.getenv(), settings.py
+   - Frontend: import.meta.env, process.env
+   - Docker: docker-compose.yml env sections
+
+2. Cross-validate
+   - Check .env.example has all referenced vars
+   - Ensure frontend vars have VITE_ or REACT_APP_ prefix
+   - Validate no secrets in frontend code
+   - Check env vars are documented
+
+### Authentication Flow Validation
+
+**Process**:
+1. Identify auth mechanism (JWT, OAuth, Basic, API Key)
+2. Check backend auth implementation
+   - Token generation/validation
+   - Password hashing
+   - Session management
+3. Check frontend auth implementation
+   - Token storage (localStorage/sessionStorage/cookies)
+   - Auth headers in API calls
+   - Protected route guards
+   - Token refresh logic
+4. Cross-validate
+   - Ensure token format matches backend expectations
+   - Check expiration handling
+   - Validate logout clears all auth data
+
+## Parallel Validation Strategy
+
+### Execution Plan
+
+```
+Phase 1: Detection (Sequential)
+├─ Scan project structure
+├─ Identify all components
+└─ Determine validation workflows
+
+Phase 2: Component Validation (Parallel)
+├─ Backend validation (background)
+├─ Frontend validation (background)
+├─ Database validation (background)
+└─ Infrastructure validation (background)
+
+Phase 3: Cross-Component Validation (Sequential)
+├─ API contract validation (requires Phase 2 complete)
+├─ Environment variable validation
+└─ Authentication flow validation
+
+Phase 4: Reporting (Sequential)
+├─ Aggregate results
+├─ Prioritize issues
+└─ Generate recommendations
+```
+
+### Priority Levels
+
+**Critical (🔴)**: Blocks deployment, requires immediate fix
+- Backend tests failing
+- Frontend build failing
+- API contract mismatches causing runtime errors
+- Database migration failures
+- Security vulnerabilities
+
+**Warning (🟡)**: Should be fixed, doesn't block deployment
+- Low test coverage (< 70%)
+- Bundle size warnings
+- Missing type hints
+- Unused dependencies
+- Performance issues
+
+**Info (🟢)**: Nice to have, improves quality
+- Code style inconsistencies
+- Missing documentation
+- Optimization opportunities
+- Deprecated syntax (still functional)
+
+## Auto-Fix Capabilities
+
+### Automatic Fixes (No confirmation needed)
+
+**TypeScript**:
+- Remove unused imports
+- Add missing semicolons
+- Fix indentation
+- Sort imports
+
+**Python**:
+- Format with Black
+- Sort imports with isort
+- Remove unused variables (prefix with _)
+- Add text() wrapper to raw SQL strings
+
+**Configuration**:
+- Generate missing config files (vite-env.d.ts, tsconfig.json)
+- Fix ESM/CommonJS conflicts
+- Update deprecated config syntax
+
+### Suggested Fixes (Requires confirmation)
+
+**TypeScript**:
+- Generate missing type definitions
+- Update React Query v4 → v5 syntax
+- Add missing error handling
+- Migrate class components to hooks
+
+**Python**:
+- Add missing type hints
+- Migrate to async/await
+- Update deprecated SQLAlchemy patterns
+- Add missing docstrings
+
+**Database**:
+- Add missing indexes
+- Fix N+1 queries with joins
+- Update cascade delete rules
+
+## Pattern Learning Integration
+
+### Patterns to Capture
+
+**Project Structure Patterns**:
+```json
+{
+  "project_type": "fullstack-monorepo",
+  "backend": "fastapi",
+  "frontend": "react-typescript",
+  "database": "postgresql",
+  "infrastructure": "docker-compose",
+  "patterns_detected": {
+    "api_versioning": "/api/v1",
+    "auth_method": "jwt",
+    "orm": "sqlalchemy",
+    "state_management": "react-query"
+  }
+}
+```
+
+**Common Issue Patterns**:
+```json
+{
+  "typescript_unused_imports": {
+    "frequency": 12,
+    "auto_fix_success_rate": 1.0,
+    "common_files": ["src/components/*.tsx"]
+  },
+  "sqlalchemy_raw_sql": {
+    "frequency": 5,
+    "auto_fix_success_rate": 1.0,
+    "pattern": "execute('SELECT ...') → execute(text('SELECT ...'))"
+  },
+  "react_query_v4_syntax": {
+    "frequency": 3,
+    "auto_fix_success_rate": 0.9,
+    "pattern": "useQuery(['key'], fn) → useQuery({queryKey: ['key'], queryFn: fn})"
+  }
+}
+```
+
+**Validation Performance Patterns**:
+```json
+{
+  "backend_validation_time": "15s",
+  "frontend_validation_time": "45s",
+  "bottlenecks": ["TypeScript compilation", "npm install"],
+  "optimization_opportunities": ["Use turbo for builds", "Cache dependencies"]
+}
+```
+
+## When to Apply This Skill
+
+**Automatic triggers**:
+- Project has both backend and frontend directories
+- docker-compose.yml detected with multiple services
+- Multiple package.json or requirements.txt files found
+- User runs `/validate-fullstack` command
+
+**Manual triggers**:
+- User mentions "full-stack", "backend and frontend", "API integration"
+- User reports issues across multiple components
+- Deployment preparation
+- CI/CD pipeline setup
+
+## Integration with Other Skills
+
+**Combines with**:
+- `code-analysis`: For structural analysis of each component
+- `quality-standards`: For quality benchmarks
+- `testing-strategies`: For test coverage validation
+- `pattern-learning`: For capturing project-specific patterns
+- `validation-standards`: For tool usage validation
+
+**Delegates to agents**:
+- `frontend-analyzer`: For detailed TypeScript/React validation
+- `api-contract-validator`: For API synchronization
+- `build-validator`: For build configuration issues
+- `test-engineer`: For test infrastructure fixes
+- `quality-controller`: For comprehensive quality assessment
+
+## Success Metrics
+
+**Validation effectiveness**:
+- Issue detection rate: % of issues found automatically
+- False positive rate: < 5%
+- Auto-fix success rate: > 80%
+- Time savings vs manual validation: > 90%
+
+**Quality improvements**:
+- Issues caught before deployment: Track over time
+- Deployment success rate: Should increase
+- Time to fix issues: Should decrease
+- Pattern reuse rate: Should increase for similar projects
+
+## Example Validation Report
+
+```
+✅ Full-Stack Validation Complete (2m 34s)
+
+📊 Component Status:
+├─ Backend (FastAPI + PostgreSQL)
+│  ├─ ✅ Dependencies: 42 packages, 0 conflicts
+│  ├─ ✅ Type hints: 98% coverage
+│  ├─ ⚠️  Tests: 45 passing, 42% coverage (target: 70%)
+│  └─ ✅ API schema: 23 endpoints documented
+│
+├─ Frontend (React + TypeScript)
+│  ├─ ✅ Type check: 0 errors (auto-fixed 16)
+│  ├─ ✅ Build: 882KB bundle (optimized)
+│  ├─ ✅ Dependencies: 124 packages, 0 peer warnings
+│  └─ ✅ Unused imports: 0 (auto-removed 5)
+│
+└─ Integration
+   ├─ ✅ API contract: 23/23 endpoints matched
+   ├─ ✅ Environment vars: 15/15 documented
+   └─ ✅ Auth flow: JWT tokens validated
+
+🔧 Auto-Fixed Issues (11):
+✓ Removed 5 unused TypeScript imports
+✓ Generated vite-env.d.ts
+✓ Added text() wrapper to 3 SQL queries
+✓ Fixed 2 React Query v5 syntax issues
+
+⚠️  Recommended Actions (2):
+1. Increase test coverage to 70% (currently 42%)
+2. Add indexes to users.email and projects.created_at
+
+🎯 Overall Score: 87/100 (Production Ready)
+```