ctrlshiftleft/docs/UPGRADING_TO_V1_4.md

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

# Upgrading to ctrl.shift.left v1.4.0

This guide provides instructions for existing users who are upgrading to v1.4.0 from previous versions.

## Prerequisites

- Node.js 14.x or higher
- npm 7.x or higher

## Upgrade Steps

### 1. Update Your Installation

```bash
# For global installation
npm install -g ctrlshiftleft@1.4.0

# For project-level installation
npm install --save-dev ctrlshiftleft@1.4.0
```

### 2. Configuration Updates

The new version uses a configuration file system. Create a `.ctrlshiftleft` directory in your project root if it doesn't already exist:

```bash
mkdir -p .ctrlshiftleft
```

Create a configuration file:

```bash
# This will generate a sample configuration file with defaults
npx ctrlshiftleft --init-config
```

Or create one manually:

```javascript
// .ctrlshiftleft/config.js
module.exports = {
  security: {
    customPatterns: [],
    disabledPatterns: [],
    frameworks: {
      react: { enabled: true },
      nextjs: { enabled: true },
      express: { enabled: true }
    },
    output: {
      format: 'markdown',
      directory: './security-reports'
    }
  },
  testing: {
    performance: {
      enabled: true,
      reportDir: './performance-reports'
    },
    generation: {
      framework: 'playwright',
      outputDir: './tests'
    }
  },
  global: {
    lineEndings: 'auto',
    createDirs: true
  }
};
```

### 3. Update CI/CD Pipeline

If you're using ctrl.shift.left in CI/CD pipelines, update your workflow files:

#### GitHub Actions

```yaml
# .github/workflows/quality.yml
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '16'
      - name: Install dependencies
        run: npm ci
      - name: Install ctrl.shift.left
        run: npm install -g ctrlshiftleft@1.4.0
      - name: Security Analysis
        run: ctrlshiftleft analyze src/ --output reports/security
      - name: Test Generation
        run: ctrlshiftleft gen src/ --output tests/e2e
      - name: Run Tests
        run: ctrlshiftleft run
```

#### GitLab CI

```yaml
# .gitlab-ci.yml
quality:
  image: node:16
  script:
    - npm ci
    - npm install -g ctrlshiftleft@1.4.0
    - ctrlshiftleft analyze src/ --output reports/security
    - ctrlshiftleft gen src/ --output tests/e2e
    - ctrlshiftleft run
  artifacts:
    paths:
      - reports/
      - tests/
```

### 4. Using New Features

#### Performance Tracking

Enable performance tracking for any command:

```bash
ctrlshiftleft secure MyComponent.jsx --perf --perf-report markdown
```

Run dedicated performance analysis:

```bash
ctrlshiftleft perf MyComponent.jsx
```

#### Enhanced Security Analysis

The security analyzer now has enhanced patterns for React and API routes by default:

```bash
# Uses enhanced analyzer automatically
ctrlshiftleft analyze MyComponent.jsx

# Use legacy analyzer if needed
ctrlshiftleft analyze MyComponent.jsx --enhanced false
```

#### Cross-Platform Testing

Test your workflow across platforms:

```bash
ctrlshiftleft test:cross-platform
```

### 5. Breaking Changes

#### Command Behavior Changes

- The `analyze` command now uses the enhanced analyzer by default (with React and API patterns)
- All commands now respect the configuration file settings by default
- Error handling is more verbose by default

#### API Changes

If you've integrated with the ctrl.shift.left JavaScript API:

```javascript
// Legacy v1.3.x
const analyzer = require('ctrlshiftleft/analyze');
analyzer.analyzeFile(filePath);

// New v1.4.0
const { securityAnalyzer } = require('ctrlshiftleft/security');
securityAnalyzer.analyzeFile(filePath, { enhanced: true });
```

## Troubleshooting

### Common Issues

1. **Missing configuration file**
   
   Error: `Could not load configuration from .ctrlshiftleft/config.js`
   
   Solution: Create the configuration file or run with `--reset-config` to use defaults.

2. **Performance report errors**
   
   Error: `Could not create performance report directory`
   
   Solution: Check directory permissions or specify a different output directory with `--output`.

3. **Path compatibility issues**
   
   Error: `Path contains invalid characters`
   
   Solution: Upgrade to v1.4.0 which handles cross-platform path normalization automatically.

### Getting Help

If you encounter issues not covered in this guide:

1. Run the command with `--verbose` to get more detailed error information
2. Check the error log at `.ctrlshiftleft/logs/error.log`
3. Visit the [GitHub issues page](https://github.com/johngaspar/ctrlshiftleft/issues) to report problems

## What's Next

After upgrading to v1.4.0, we recommend:

1. Generate a configuration file tailored to your project
2. Run a complete security analysis with the enhanced patterns
3. Try the performance tracking to benchmark your development workflow
4. Read the [V1_4_0_FEATURES.md](./V1_4_0_FEATURES.md) documentation for full details on new capabilities