ctrlshiftleft/docs/TOOLKIT.md

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

# ctrl.shift.left Developer Toolkit

This document provides detailed information about the ctrl.shift.left toolkit components that help developers embed QA and security testing directly into their development workflow.

## Core Tools

The toolkit consists of three main components that work together to shift security and QA testing "left" in the development process:

### 1. Security Analyzer

The Security Analyzer scans your code for potential security vulnerabilities and provides actionable remediation steps.

```bash
# Run security analysis on a component
./bin/ctrlshiftleft analyze demo/src/components/PaymentForm.tsx

# Analyze multiple files
./bin/ctrlshiftleft analyze "src/**/*.tsx"
```

Key features:
- Detects common security vulnerabilities like XSS, injection risks, and insecure data storage
- Provides severity classifications (Critical, High, Medium, Low, Info)
- Generates detailed Markdown reports with remediation suggestions
- Integrates with CI/CD pipelines for automated security scanning

### 2. Test Generator

The Test Generator automatically creates Playwright end-to-end tests for your components, focusing on both functionality and security aspects.

```bash
# Generate tests for a component
./bin/ctrlshiftleft gen demo/src/components/PaymentForm.tsx

# Specify output directory
./bin/ctrlshiftleft gen demo/src/components/PaymentForm.tsx -o tests/e2e
```

Key features:
- Creates comprehensive test suites covering rendering, validation, submission, and security
- Includes security-focused tests for XSS prevention, CSRF protection, and sensitive data handling
- Generates accessibility tests to ensure keyboard navigation works
- Follows best practices for test structure and organization

### 3. QA & Security Checklist Generator

The Checklist Generator creates comprehensive QA and security checklists for your components, helping you identify and address issues early.

```bash
# Generate a checklist for a component
./bin/ctrlshiftleft checklist demo/src/components/PaymentForm.tsx

# Specify output file
./bin/ctrlshiftleft checklist demo/src/components/PaymentForm.tsx -o reports/payment-checklist.json
```

Key features:
- Covers multiple categories: Functionality, Security, Accessibility, Performance, and Testing
- Provides actionable items with PASS/FAIL/REVIEW status
- Generates both JSON data (for programmatic use) and Markdown reports (for human review)
- Prioritizes critical issues that need immediate attention

## Unified Workflow

The toolkit provides a unified workflow to streamline security and QA testing:

```bash
# Run the complete workflow on a component
./bin/ctrlshiftleft secure demo/src/components/PaymentForm.tsx
```

This command runs all three tools in sequence, providing a comprehensive analysis of your component.

## Continuous Integration

The toolkit includes GitHub Actions workflows for automated security and QA testing:

```yaml
# .github/workflows/security-qa.yml
name: Ctrl+Shift+Left Security & QA

on:
  push:
    branches: [ main, master, develop ]
  pull_request:
    branches: [ main, master, develop ]
```

This workflow automates:
- Security scanning of all components
- Test generation and execution
- QA checklist creation
- Artifact collection for review

## Standalone Tools

For developers who prefer direct access to individual tools:

```bash
# Run security analysis directly
node vscode-ext-test/analyze-security.js <file-path>

# Generate tests directly
node vscode-ext-test/generate-tests.js <file-path> [output-dir]

# Generate checklist directly
node vscode-ext-test/generate-checklist.js <file-path> [output-file]
```

## Real-time Development Integration

For real-time feedback during development:

```bash
# Watch for changes and run security analysis
./bin/ctrlshiftleft watch src --type security

# Watch for changes and run all tools
./bin/ctrlshiftleft watch src --type all
```

## Case Study: Securing PaymentForm

The toolkit has been used to secure the `PaymentForm` component, demonstrating the value of shifting security and QA testing left:

1. **Initial Analysis**: Security scan found several critical issues including improper storage of sensitive data and lack of input sanitization
2. **Remediation**: Implemented fixes following security best practices for payment handling
3. **Verification**: Generated tests confirmed the security improvements and ensured functionality remained intact
4. **Continuous Protection**: CI workflow now automatically checks for any regression in security posture

By embedding these tools into the development workflow, the team was able to identify and fix security issues before they reached production, significantly reducing risk.