Ctrl.shift.left

A CLI and IDE-integrated toolkit that empowers developers to embed QA and security into early development by auto-generating, executing, and verifying end-to-end tests and QA checklists as code is authored. Now featuring AI-enhanced security analysis, Next.js framework support, and self-diagnostic capabilities!

What's New in v1.3.1

• Improved Path Resolution: Enhanced module path handling with a new .ctrlshiftleft directory structure
• Better Output Path Handling: Fixed output path handling for security reports and test generation
• Enhanced Next.js Support: Specialized setup for Next.js projects with better framework detection
• Improved Error Handling: Better diagnostics and error recovery for common integration issues

Security & QA Status

Security and QA metrics automatically generated by ctrl.shift.left

Overview

Ctrl.shift.left helps developers shift quality assurance and security testing left in the development process by:

1. Automatically generating end-to-end tests from source code
2. Creating structured QA and security checklists
3. Providing verification tools to execute tests and compare against checklists
4. Integrating seamlessly with development workflows via CLI, IDE, and CI
5. NEW: Delivering AI-powered security analysis with sophisticated remediation suggestions
6. NEW: Providing a programmable API for integration with other tools
7. NEW: Offering an enhanced real-time watcher with AI capabilities
8. NEW: Providing first-class Next.js framework support and optimizations
9. NEW: Featuring self-diagnostic and repair utilities for seamless integration
10. NEW: Including QA validation middleware for API routes

Installation

From NPM (Recommended)

# Install from NPM
npm install -g ctrlshiftleft

# Verify installation
ctrlshiftleft --version

# For Next.js projects, run the specialized setup
ctrlshiftleft-setup --nextjs

From Source

# Clone the repository
git clone <repository-url>
cd ctrlshiftleft

# Install dependencies
npm install

# Build the project
npm run build

# Create a symlink for global usage
npm link

Configuration

Create a .env file in the root directory with the following variables:

# OpenAI API Key for AI-enhanced security analysis and LLM features
OPENAI_API_KEY=your_openai_api_key_here

# OpenAI model to use (optional, defaults to gpt-4)
OPENAI_MODEL=gpt-4

# Enable AI security analysis by default (optional)
CTRLSHIFTLEFT_AI_ANALYSIS=true

Usage

Self-Diagnostics & Repair

If you're experiencing issues with your installation, use the repair tool:

ctrlshiftleft-repair

Options:

• --fix: Automatically fix detected issues
• --verbose: Show detailed diagnostic information
• --next: Specifically check Next.js compatibility

Framework-Specific Setup

For Next.js projects, use the specialized setup tool:

ctrlshiftleft-setup --nextjs

This creates necessary configuration files and updates your project for optimal compatibility with Next.js App Router or Pages Router.

See NEXTJS.md for framework-specific details.

AI-Enhanced Security Analysis

Perform advanced security analysis with AI-powered insights:

ctrlshiftleft-ai analyze --ai <source-path>

Options:

• --ai: Enable AI-powered analysis (requires OPENAI_API_KEY)
• --output=<file>: Output file for the security report

AI-Enhanced Full Scan

Run a complete workflow with AI security analysis, test generation, and checklist creation:

ctrlshiftleft-ai secure --ai <source-path>

Options:

• --ai: Enable AI-powered analysis (requires OPENAI_API_KEY)

Generate Tests

Generate end-to-end tests from source code:

ctrlshiftleft gen <source-path> [options]

Options:

• -o, --output <directory>: Output directory for generated tests (default: ./tests)
• -f, --format <format>: Test format (playwright or selenium) (default: playwright)
• -t, --timeout <timeout>: Timeout for test generation in seconds (default: 60)

Run Tests

Execute generated end-to-end tests:

ctrlshiftleft run [test-path] [options]

Options:

• [test-path]: Path to test file or directory (default: ./tests)
• -b, --browser <browser>: Browser to run tests in (default: chromium)
• -h, --headless: Run browser in headless mode (default: true)
• -t, --timeout <timeout>: Test timeout in seconds (default: 30)
• -r, --reporter <reporter>: Test reporter format (default: list)

Watch Mode

Watch source files and auto-generate tests on changes:

ctrlshiftleft watch <source-path> [options]

Options:

• -o, --output <directory>: Output directory for generated tests (default: ./tests)
• -i, --ignore <patterns>: Comma-separated glob patterns to ignore (default: node_modules,dist,build,*.test.*)
• -d, --delay <ms>: Debounce delay in milliseconds (default: 1000)

AI-Enhanced Watch (NEW)

Watch files with real-time AI-powered security analysis, test generation, and checklist creation:

ctrlshiftleft watch-ai <directory> [options]

# Or use the npm script
npm run ai:watch

Options:

• -t, --tests: Generate tests on file changes (default: true)
• -s, --security: Perform security analysis on file changes (default: true)
• -c, --checklists: Generate QA checklists on file changes (default: true)
• -a, --ai: Use AI-enhanced security analysis (requires OpenAI API key)
• --test-output <dir>: Output directory for tests (default: ./tests)
• --security-output <dir>: Directory for security reports (default: ./security-reports)
• --checklist-output <dir>: Directory for checklists (default: ./checklists)
• --include <patterns...>: Glob patterns to include
• --exclude <patterns...>: Glob patterns to exclude

Cursor AI Integration (NEW)

Get real-time feedback during development with Cursor AI and VS Code integration:

# Start real-time feedback in your editor
ctrlshiftleft-cursor --dir=./src

# Output in editor-friendly diagnostics format
ctrlshiftleft-cursor --output=diagnostics

# Or use npm scripts
npm run cursor:watch
npm run cursor:integrate

Options:

• --dir, -d <path>: Directory to watch (default: ./src)
• --output, -o <format>: Output format: console, diagnostics, json (default: console)
• --ai <boolean>: Use AI-enhanced analysis (default: true)
• --notify, -n <boolean>: Show notifications in editor (default: true)
• --extensions, -e <exts...>: File extensions to watch (default: js,jsx,ts,tsx)

See CURSOR_INTEGRATION.md for VS Code tasks.json setup and more details.

• --concurrent <n>: Maximum concurrent tasks (default: 3)
• --silent: Run in silent mode (no progress reporting)

This enhanced watcher is optimized for integration with AI code generation tools like Cursor AI, providing immediate feedback as code is created.

Generate Checklists

Generate QA and security checklists from source code:

ctrlshiftleft checklist <source-path> [options]

Options:

• -o, --output <file>: Output JSON file for generated checklist (default: ./checklist.json)
• -t, --type <type>: Type of checklist to generate (qa, security, all) (default: all)
• --format <format>: Output format (json, markdown) (default: json)

Programmable API (NEW)

Use ctrl.shift.left programmatically in your Node.js applications:

// Import the API
const ctrlShiftLeft = require('ctrlshiftleft');

// Generate end-to-end tests
const testResults = await ctrlShiftLeft.generateTests('./src/components/LoginForm.jsx', {
  outputDir: './generated-tests',
  format: 'playwright'
});
console.log(`Generated ${testResults.testCount} tests`);

// Use the AI-enhanced watcher
const { EnhancedWatcher } = ctrlShiftLeft;
const watcher = new EnhancedWatcher({
  useAIAnalysis: true,  // Requires OpenAI API key
  maxConcurrentTasks: 2
});

// Listen for events
watcher.on('analysis:complete', (result) => {
  if (result.success) {
    console.log(`Analysis completed for ${result.filePath}`);
  }
});

// Start watching
watcher.watch('./src');

For complete API documentation, see API.md.

CI/CD Integration

GitHub Action

Ctrl.shift.left provides an official GitHub Action that you can add to your workflow:

name: Security & QA Check

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-security-qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up OpenAI API Key
        run: echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }}" >> $GITHUB_ENV
      
      - name: Run ctrl.shift.left Analysis
        uses: ctrlshiftleft/action@v1
        with:
          source-path: './src'  # Path to your source code
          fail-on-security-issues: true  # Fail the build if security issues found
          framework: 'nextjs'  # Specify framework for specialized handling

Configuration Options

| Input | Description | Default | |-------|-------------|--------| | source-path | Path to source code to analyze | ./src | | test-output-path | Output directory for generated tests | ./tests/generated | | checklist-output-path | Output directory for generated checklists | ./checklists | | browser | Browser to use for tests (chromium, firefox, webkit) | chromium | | headless | Run tests in headless mode | true | | fail-on-security-issues | Fail build on security issues | true | | framework | Target framework (nextjs, react, vue, etc.) | auto |

Action Outputs

| Output | Description | |--------|-------------| | has-security-issues | Boolean indicating whether security issues were found |

For more information, see the GitHub Action README.

Manual Integration

Alternatively, you can manually integrate ctrl.shift.left into your CI/CD pipeline:

- name: Generate and run tests
  run: |
    npm install -g ctrlshiftleft
    ctrlshiftleft gen ./src -o ./tests
    ctrlshiftleft run ./tests

Middleware Integration

Include security and QA validation in your API routes:

// Express example
const express = require('express');
const { createValidationMiddleware } = require('ctrlshiftleft/middleware/qa-validation');

const app = express();

// Create a middleware with validation rules
const validateUser = createValidationMiddleware({
  requiredFields: ['username', 'email'],
  fieldValidations: {
    email: { type: 'email' },
    password: { type: 'password', minStrength: 'medium' },
    websiteUrl: { type: 'url', optional: true }
  }
});

// Apply the middleware to routes
app.post('/api/users', validateUser, (req, res) => {
  // If validation passes, handle the request
  // The validated data is available in req.validatedData
  res.json({ success: true });
});

Troubleshooting

If you encounter any issues, refer to our comprehensive Troubleshooting Guide.

License

MIT