ctrlshiftleft/docs/V1_4_0_FEATURES.md

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

# ctrl.shift.left v1.4.0 New Features

This document describes the new features and improvements introduced in version 1.4.0 of the ctrl.shift.left toolkit.

## 1. Enhanced Security Analysis

### 1.1 Framework-Specific Security Patterns

The security analyzer now includes specialized pattern detection for:

- **React-specific vulnerabilities**: Detects React anti-patterns and security issues like unsafe HTML injection, component lifecycle issues, and props handling.
- **API Route vulnerabilities**: Enhanced detection for Express.js, Next.js API routes, and other server-side frameworks.
- **Configuration-based scanning**: Load custom patterns and disable built-in patterns using the configuration file.

### 1.2 Customizable Security Rules

Users can now customize security scanning via the configuration file:

```javascript
// .ctrlshiftleft/config.js
module.exports = {
  security: {
    // Add custom security patterns
    customPatterns: [
      {
        id: 'custom-auth-check',
        pattern: /function\s+auth\s*\(\s*\)\s*{[^}]*return\s+true/,
        severity: 'CRITICAL',
        title: 'Authentication Bypass',
        description: 'Function always returns true, bypassing authentication',
        remediation: 'Implement proper authentication checks',
        category: 'authentication'
      }
    ],
    
    // Disable specific built-in patterns
    disabledPatterns: ['react-keys'],
    
    // Framework-specific settings
    frameworks: {
      react: { enabled: true },
      nextjs: { enabled: true },
      express: { enabled: true }
    }
  }
};
```

## 2. Performance Metrics

### 2.1 Performance Tracking

The toolkit now includes built-in performance tracking for all operations, providing insights into:

- Generation speed for tests, checklists, and security reports
- Execution time for tests and analysis operations
- Success rates and performance comparisons

### 2.2 Performance Reports

Generate detailed performance reports in multiple formats:

```bash
# Enable performance tracking for any command
ctrlshiftleft gen MyComponent.jsx --perf

# Generate a performance report in markdown format
ctrlshiftleft gen MyComponent.jsx --perf --perf-report markdown

# Run a dedicated performance analysis
ctrlshiftleft perf MyComponent.jsx --format json
```

Sample performance report:

```
# Performance Report

## Metadata
- Project: MyProject
- Version: 1.4.0
- Timestamp: 2025-04-26T18:30:00Z
- Platform: darwin (arm64)
- Node.js: v18.15.0

## Summary
- Total Operations: 3
- Total Duration: 4500.00ms
- Average Duration: 1500.00ms
- Success Rate: 100.00%

## Operations by Type
| Type | Count | Total Duration | Average Duration | Success Rate |
| ---- | ----- | -------------- | ---------------- | ------------ |
| generation | 2 | 2000.00ms | 1000.00ms | 100.00% |
| execution | 1 | 2500.00ms | 2500.00ms | 100.00% |
```

## 3. Cross-Platform Compatibility

### 3.1 Platform-Agnostic Path Handling

The toolkit now ensures consistent behavior across Windows, macOS, and Linux by:

- Normalizing file paths for the target platform
- Handling line ending differences (CRLF vs LF)
- Providing platform-specific command mappings

### 3.2 Cross-Platform Testing

Test your ctrl.shift.left workflow on multiple platforms:

```bash
# Test compatibility across all platforms
ctrlshiftleft test:cross-platform

# Test specific platforms
ctrlshiftleft test:cross-platform --platforms windows,linux
```

## 4. Error Recovery Mechanisms

### 4.1 Enhanced Error Handling

Improved error handling with:

- Standardized error categorization
- Detailed recovery steps for each error type
- Automatic error logging and documentation references

### 4.2 Automatic Recovery Strategies

The toolkit now attempts to recover from common errors:

- Creates missing directories automatically
- Provides fallback templates when generation fails
- Implements retry mechanisms for network failures
- Gracefully degrades functionality when features are unavailable

Error handling example:

```
❌ Error: Could not find input file: Component.jsx
Error code: FS-123-4567 (filesystem)

Recovery steps:
1. Check if the file or directory exists
2. Ensure you have permission to access the location
3. Try specifying an absolute path instead of a relative path
4. Create any missing directories manually

For more information: https://github.com/johngaspar/ctrlshiftleft/docs/troubleshooting#filesystem-fs-123-4567
```

## 5. Configuration System

### 5.1 Global Configuration

A new configuration system allows customization of all aspects of the toolkit:

```javascript
// .ctrlshiftleft/config.js
module.exports = {
  // Security analyzer configuration
  security: { /* ... */ },
  
  // Test generation configuration
  testing: {
    // Performance tracking settings
    performance: {
      enabled: true,
      reportDir: './performance-reports'
    },
    // Test generation settings
    generation: {
      framework: 'playwright',
      outputDir: './tests'
    }
  },
  
  // Global settings
  global: {
    lineEndings: 'auto',  // 'auto', 'lf', or 'crlf'
    createDirs: true      // Automatically create directories
  }
};
```

### 5.2 CLI Flexibility

New command-line options for fine-grained control:

```bash
# Specify line endings format
ctrlshiftleft gen Component.jsx --line-endings lf

# Enable performance tracking for a single command
ctrlshiftleft analyze Component.jsx --perf

# Generate performance report in specific format
ctrlshiftleft secure Component.jsx --perf --perf-report markdown
```

## Getting Started with v1.4.0

To take advantage of these new features:

1. Update to v1.4.0:
   ```bash
   npm install -g ctrlshiftleft@1.4.0
   ```

2. Create a configuration file (optional):
   ```bash
   mkdir -p .ctrlshiftleft
   touch .ctrlshiftleft/config.js
   ```

3. Run with performance tracking:
   ```bash
   ctrlshiftleft secure MyComponent.jsx --perf --perf-report markdown
   ```

4. Test cross-platform compatibility:
   ```bash
   ctrlshiftleft test:cross-platform
   ```

For more information, see the [full documentation](https://github.com/johngaspar/ctrlshiftleft/docs).