@tamyla/ui-components-react/docs/reports/WORKFLOW_README.md

React-based UI component library with Factory Bridge pattern - integrates seamlessly with @tamyla/ui-components. Enhanced AI agent discoverability with structured component registry, comprehensive Storybook (8 components), and detailed guides.

# Pre-Production Validation Workflow System

A comprehensive, automated workflow system that orchestrates all testing, validation, and quality assurance steps required before committing changes to production. This system consolidates and enhances all existing validation tools into a unified, repeatable process.

## 🎯 Overview

The Pre-Production Workflow System ensures that every change meets production standards by running through multiple validation layers. It leverages all existing tools and scripts while providing a standardized, automated pipeline for both minor and major releases.

## ✨ Key Features

- **🔄 Automated Pipeline**: Orchestrates 11 validation steps in the correct order
- **🏷️ Release-Type Aware**: Different validation levels for patch, minor, and major releases
- **📊 Comprehensive Reporting**: Multiple report formats with detailed execution results
- **🔍 Manual Checkpoints**: Built-in review points for critical changes
- **♻️ Error Recovery**: Graceful handling of failures with detailed diagnostics
- **🔗 CI/CD Integration**: JSON output for automated pipeline integration
- **📈 Dashboard Monitoring**: Real-time status and metrics tracking
- **⚙️ Highly Configurable**: JSON-based configuration for customization

## 🚀 Quick Start

### For Bug Fixes and Patches
```bash
npm run preprod:patch
```

### For New Features
```bash
npm run preprod:minor
```

### For Breaking Changes
```bash
npm run preprod:major
```

### Custom Validation
```bash
npm run preprod:custom
```

## 📋 Workflow Steps

| Step | Description | Patch | Minor | Major | Duration |
|------|-------------|-------|-------|-------|----------|
| **Setup** | Environment validation | ✅ | ✅ | ✅ | ~1m |
| **Code Quality** | TypeScript/ESLint checks | ✅ | ✅ | ✅ | ~2m |
| **Testing** | Unit & integration tests | ✅ | ✅ | ✅ | ~5m |
| **Validation** | Component validation | ❌ | ✅ | ✅ | ~3m |
| **Build** | Production build | ✅ | ✅ | ✅ | ~4m |
| **Integration** | Package compatibility | ✅ | ✅ | ✅ | ~2m |
| **Documentation** | Docs validation | ❌ | ✅ | ✅ | ~1m |
| **Security** | Security scanning | ✅ | ✅ | ✅ | ~3m |
| **Performance** | Bundle analysis | ❌ | ❌ | ✅ | ~2m |
| **Manual Review** | Human verification | ❌ | ❌ | ✅ | ~1h |
| **Final Check** | Production readiness | ✅ | ✅ | ✅ | ~30s |

## 🛠️ Available Scripts

```bash
# Pre-production workflows
npm run preprod:patch     # Bug fixes and patches
npm run preprod:minor     # New features
npm run preprod:major     # Breaking changes
npm run preprod:custom    # Custom validation

# Validation and reporting
npm run preprod:validate  # Dry-run validation
npm run workflow:report   # Generate detailed reports
npm run workflow:dashboard # View workflow status

# Individual validation steps
npm run test              # Unit tests
npm run test:coverage     # Test coverage
npm run lint              # Code linting
npm run type-check        # TypeScript validation
npm run build             # Production build
```

## 📊 Dashboard & Monitoring

Get real-time insights into your workflow health:

```bash
# Quick status overview
npm run workflow:dashboard

# Detailed status with git checks
npm run workflow:dashboard -- --status

# Recent workflow runs
npm run workflow:dashboard -- --recent=5

# JSON output for CI/CD
npm run workflow:dashboard -- --json
```

## 📈 Report Generation

Generate comprehensive reports in multiple formats:

```bash
# Markdown report (default)
npm run workflow:report

# HTML report
npm run workflow:report -- --format=html

# JSON report
npm run workflow:report -- --format=json

# Custom output directory
npm run workflow:report -- --output=my-reports
```

## ⚙️ Configuration

Customize the workflow behavior via `workflow-config.json`:

```json
{
  "releaseTypes": {
    "patch": {
      "skipSteps": ["performance", "manual-review"],
      "requiredTests": ["unit", "integration"],
      "timeout": 300000
    }
  },
  "globalSettings": {
    "continueOnError": false,
    "verbose": true,
    "cleanupOnFailure": true
  }
}
```

## 🔧 Command Line Options

### Workflow Execution Options
```bash
# Dry run mode
npm run preprod:patch -- --dry-run

# Verbose output
npm run preprod:minor -- --verbose

# Skip manual review
npm run preprod:major -- --skip-manual

# Continue on errors
npm run preprod:custom -- --continue-on-error
```

### Report Options
```bash
# Generate latest report
npm run workflow:report -- --latest

# Multiple formats
npm run workflow:report -- --format=html,json

# Custom output
npm run workflow:report -- --output=./reports
```

## 🔗 Integration Examples

### GitHub Actions
```yaml
- name: Pre-Production Validation
  run: npm run preprod:${{ github.event.inputs.releaseType }}

- name: Upload Reports
  uses: actions/upload-artifact@v3
  with:
    name: workflow-reports
    path: reports/
```

### Jenkins Pipeline
```groovy
stage('Validation') {
    steps {
        sh 'npm run preprod:minor'
    }
    post {
        always {
            archiveArtifacts artifacts: 'reports/*.json', allowEmptyArchive: true
        }
    }
}
```

### Custom CI/CD
```bash
# Run workflow and check results
npm run preprod:patch

# Generate and upload reports
npm run workflow:report -- --format=json
curl -X POST -H "Content-Type: application/json" \
  -d @reports/workflow-report-patch-*.json \
  $WEBHOOK_URL
```

## 📁 Generated Files

The workflow creates several output files in the `temp/` directory:

- `preprod-report-[type]-[timestamp].json`: Detailed execution report
- `preprod-summary.json`: Production readiness summary
- `validation-results.json`: Component validation results

Reports are also generated in `reports/` directory:
- `workflow-report-[type]-[timestamp].md`: Markdown report
- `workflow-report-[type]-[timestamp].html`: HTML report
- `workflow-report-[type]-[timestamp].json`: JSON report

## 🧪 Testing the Workflow

### Dry Run Mode
Test the workflow without making changes:
```bash
npm run preprod:validate
```

### Individual Step Testing
```bash
# Test code quality
node scripts/fix-typescript-eslint.js --dry-run

# Test component validation
node scripts/react-component-validation.js --report

# Test build process
npm run build
```

### Mock Data Testing
```bash
# Create mock validation results
echo '{"summary": {"total": 10, "valid": 9, "invalid": 1}}' > temp/validation-results.json

# Test report generation
npm run workflow:report
```

## 🐛 Troubleshooting

### Common Issues

**"Not in project root"**
```bash
# Ensure you're in the correct directory
pwd
ls package.json
```

**"Build artifacts missing"**
```bash
# Check build process
npm run build
ls -la dist/
```

**"Tests failing"**
```bash
# Run tests individually
npm run test
npm run test:coverage
```

**"Permission denied"**
```bash
# Fix script permissions
chmod +x scripts/*.js
```

### Debug Mode
```bash
# Enable verbose logging
npm run preprod:patch -- --verbose

# Dry run to see execution plan
npm run preprod:minor -- --dry-run

# Check workflow status
npm run workflow:dashboard -- --status
```

## 📚 Advanced Usage

### Custom Workflow Steps
Add custom validation steps by extending the workflow:

```javascript
// scripts/custom-workflow-steps/my-custom-step.js
export async function executeCustomValidation() {
  // Your custom validation logic
  return { success: true, data: {} };
}
```

### Parallel Execution
Configure steps to run in parallel for faster execution:

```json
{
  "workflowSteps": {
    "security": {
      "parallel": true,
      "commands": ["npm audit", "npx lockfile-lint"]
    }
  }
}
```

### Conditional Steps
Skip steps based on conditions:

```javascript
if (process.env.CI) {
  // Skip manual review in CI
  config.skipSteps.push('manual-review');
}
```

## 🤝 Contributing

### Adding New Validation Steps
1. Add the step to `WORKFLOW_STEPS` array in `preprod-workflow.js`
2. Implement the `execute[StepName]` function
3. Update `workflow-config.json` with step configuration
4. Add documentation to this README
5. Test the workflow with all release types

### Modifying Existing Steps
1. Update the step implementation in `preprod-workflow.js`
2. Modify configuration in `workflow-config.json`
3. Update documentation
4. Test changes thoroughly

### Configuration Changes
1. Edit `workflow-config.json`
2. Validate JSON syntax
3. Test with dry-run mode
4. Update documentation if needed

## 📝 Best Practices

### Development Workflow
1. **Run Early, Run Often**: Execute workflow after each significant change
2. **Address Failures Immediately**: Don't accumulate failing steps
3. **Review Reports**: Always check generated reports for insights
4. **Use Appropriate Release Types**: Choose the right validation level
5. **Document Customizations**: Keep track of workflow modifications

### CI/CD Integration
1. **Use JSON Output**: Parse results programmatically in CI/CD
2. **Set Appropriate Timeouts**: Configure step timeouts for your environment
3. **Handle Failures Gracefully**: Use `--continue-on-error` for non-critical failures
4. **Archive Reports**: Keep reports for audit and debugging purposes

### Team Collaboration
1. **Standardize Release Types**: Agree on when to use patch/minor/major
2. **Document Manual Steps**: Keep manual review checklists up to date
3. **Share Reports**: Make workflow reports accessible to the team
4. **Regular Reviews**: Periodically review and update the workflow

## 🔄 Version History

### v1.0.0
- Initial release with 11 validation steps
- Support for patch, minor, and major releases
- Multiple report formats
- Dashboard and monitoring capabilities
- CI/CD integration support

## 📞 Support

For issues and questions:
1. Check the troubleshooting section above
2. Review generated workflow reports for error details
3. Run with `--verbose` flag for detailed logging
4. Check the dashboard for system status

## 🎯 Future Enhancements

- [ ] Web-based dashboard interface
- [ ] Slack/Teams notifications
- [ ] GitHub integration for PR validation
- [ ] Performance regression detection
- [ ] Automated rollback capabilities
- [ ] Custom plugin system
- [ ] Multi-environment support

---

**Built with ❤️ for reliable, production-ready releases**