ctrlshiftleft/docs/INTEGRATION.md

AI-powered toolkit for embedding QA and security testing into development workflows

# ctrl.shift.left Integration Guide

This guide explains how the ctrl.shift.left toolkit integrates into development workflows to embed QA and security testing directly into the early stages of development.

## Integration Overview

The ctrl.shift.left toolkit is designed to be embedded at multiple points in the development workflow:

1. **Local Development**: CLI and IDE integration for real-time feedback
2. **Code Review**: Pre-commit hooks and automated PR checks
3. **CI/CD Pipeline**: Automated scanning, testing, and reporting
4. **Documentation**: Auto-generated security and QA documentation

## Development Workflow Integration

### Local Development

Developers can integrate ctrl.shift.left directly into their coding workflow:

```bash
# Start a watch process for security scanning
./bin/ctrlshiftleft watch src --type security

# Generate tests before implementing a feature (TDD approach)
./bin/ctrlshiftleft gen src/components/NewFeature.tsx

# Run a complete scan after implementation
./bin/ctrlshiftleft secure src/components/NewFeature.tsx
```

### IDE Integration

Our VS Code extension (in development) provides direct access to ctrl.shift.left capabilities:

1. Security issues highlighted directly in the editor
2. Quick actions to generate tests and checklists
3. Status bar indicator showing security status
4. One-click remediation suggestions

Until the full extension is ready, you can use the standalone tools and tasks integration.

### Recommended VS Code Tasks

Add these tasks to your `.vscode/tasks.json`:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Analyze Current File",
      "type": "shell",
      "command": "${workspaceFolder}/bin/ctrlshiftleft analyze ${file}",
      "problemMatcher": []
    },
    {
      "label": "Generate Tests for Current File",
      "type": "shell",
      "command": "${workspaceFolder}/bin/ctrlshiftleft gen ${file}",
      "problemMatcher": []
    },
    {
      "label": "Generate Checklist for Current File",
      "type": "shell",
      "command": "${workspaceFolder}/bin/ctrlshiftleft checklist ${file}",
      "problemMatcher": []
    },
    {
      "label": "Full Scan of Current File",
      "type": "shell",
      "command": "${workspaceFolder}/bin/ctrlshiftleft secure ${file}",
      "problemMatcher": []
    }
  ]
}
```

## Code Review Integration

### Pre-commit Hooks

Add ctrl.shift.left to your pre-commit hooks using Husky:

```json
// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "./bin/ctrlshiftleft analyze src --staged-only"
    }
  }
}
```

### Pull Request Automation

The GitHub workflow automatically runs on pull requests and:

1. Scans changed files for security issues
2. Generates tests for new components
3. Creates checklists for review
4. Comments on the PR with findings

## CI/CD Pipeline Integration

Our GitHub Actions workflow (`security-qa.yml`) provides:

1. **Security Scanning**: Automated vulnerability detection
2. **Test Generation & Execution**: Creating and running tests
3. **Checklist Creation**: Documentation of key areas for review
4. **Artifact Collection**: Preserving reports for audit purposes

### Example Jenkins Integration

```groovy
pipeline {
  agent any
  stages {
    stage('Security & QA') {
      steps {
        sh './bin/ctrlshiftleft analyze src'
        sh './bin/ctrlshiftleft gen src'
        sh './bin/ctrlshiftleft checklist src'
      }
      post {
        always {
          archiveArtifacts artifacts: 'vscode-ext-test/*.md', allowEmptyArchive: true
        }
      }
    }
  }
}
```

## Documentation Integration

The toolkit auto-generates documentation that can be integrated with your project:

1. **Security Reports**: Detailed analysis of potential vulnerabilities
2. **QA Checklists**: Comprehensive quality reviews
3. **Test Documentation**: Generated test cases and their purposes

This documentation can be included in code reviews, shared with security teams, and used for compliance purposes.

## Real-world Example: PaymentForm

We've demonstrated the toolkit's capabilities by securing a payment form component:

1. **Initial Analysis**: Security scanning found critical issues
2. **Remediation**: Implemented fixes following best practices
3. **Verification**: Generated tests confirmed the improvements
4. **Documentation**: Created comprehensive reports for review
5. **CI Integration**: Automated ongoing verification

This end-to-end example shows how ctrl.shift.left helps "shift left" security and QA concerns to earlier stages of development, significantly reducing risks and costs.

## Next Steps

To further integrate ctrl.shift.left into your development workflow:

1. Complete the VS Code extension implementation for seamless IDE integration
2. Enhance the CI/CD pipeline integration with more detailed reporting
3. Create team-specific security and QA rules
4. Develop custom checklist templates for your application domain
5. Train developers on security best practices identified by the toolkit