ctrlshiftleft/API.md

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

# ctrl.shift.left API Reference

This document provides a comprehensive guide to the ctrl.shift.left programmatic API. The API allows you to integrate QA and security testing directly into your development workflows, CI/CD pipelines, or other tools.

## Installation

```bash
npm install ctrlshiftleft
```

## Basic Usage

```javascript
const { generateTests, generateChecklist } = require('ctrlshiftleft');

// Generate end-to-end tests
const testResults = await generateTests('src/components/Login.jsx', {
  outputDir: './tests',
  format: 'playwright'
});

// Generate QA checklist
const checklistResult = await generateChecklist('src/components/Login.jsx', {
  outputDir: './checklists'
});
```

## API Reference

The ctrl.shift.left API provides the following core functions and classes:

### Test Generation

#### `generateTests(sourcePath, options)`

Generates end-to-end tests for the specified source file or directory.

**Parameters:**
- `sourcePath` (string): Path to the source file or directory
- `options` (object):
  - `outputDir` (string): Output directory for generated tests (default: './tests')
  - `format` (string): Test format - 'playwright' or 'selenium' (default: 'playwright')
  - `timeout` (number): Timeout in seconds (default: 60)
  - `overwrite` (boolean): Whether to overwrite existing tests (default: false)

**Returns:** Promise resolving to:
```typescript
{
  testCount: number;
  files: string[];
}
```

### Test Execution

#### `runTests(testPath, options)`

Runs the specified tests using Playwright or Selenium.

**Parameters:**
- `testPath` (string): Path to the test file or directory
- `options` (object):
  - `browser` (string): Browser to use - 'chromium', 'firefox', or 'webkit' (default: 'chromium')
  - `headless` (boolean): Whether to run in headless mode (default: true)
  - `workers` (number): Number of parallel workers (default: 1)
  - `reporter` (string): Reporter to use - 'list', 'dot', 'line', 'json' (default: 'list')
  - `timeout` (number): Timeout in seconds (default: 60)

**Returns:** Promise resolving to:
```typescript
{
  passed: number;
  failed: number;
  total: number;
  duration: number;
}
```

### Checklist Generation

#### `generateChecklist(sourcePath, options)`

Generates a QA and security checklist for the specified source file or directory.

**Parameters:**
- `sourcePath` (string): Path to the source file or directory
- `options` (object):
  - `outputDir` (string): Output directory for generated checklists (default: './checklists')
  - `format` (string): Output format - 'json', 'markdown', or 'html' (default: 'json')
  - `includeSecurityChecks` (boolean): Whether to include security checks (default: true)
  - `includeQAChecks` (boolean): Whether to include QA checks (default: true)

**Returns:** Promise resolving to:
```typescript
{
  itemCount: number;
  files: string[];
}
```

### File Watching

#### `watch(sourcePath, options)`

Watches the specified source files for changes and automatically generates tests, performs security analysis, and creates QA checklists.

**Parameters:**
- `sourcePath` (string): Path to the source file or directory to watch
- `options` (object):
  - `outputDir` (string): Base output directory (default: './ctrl-shift-left-output')
  - `generateTests` (boolean): Whether to generate tests on file changes (default: true)
  - `runTests` (boolean): Whether to run tests after generation (default: false)
  - `generateChecklists` (boolean): Whether to generate checklists on file changes (default: true)
  - `analyzeSecurity` (boolean): Whether to analyze security on file changes (default: true)

**Returns:** Function to stop watching

## AI-Enhanced Security Analysis

ctrl.shift.left includes AI-powered security analysis capabilities that provide deeper and more context-aware vulnerability detection compared to traditional pattern-based scanning.

### Prerequisites

Set your OpenAI API key as an environment variable:

```bash
export OPENAI_API_KEY="your-api-key"
```

Or in your code:

```javascript
process.env.OPENAI_API_KEY = "your-api-key";
```

### API Functions

#### `analyzeSecurityWithAI(sourcePath, options)`

Analyzes a file for security vulnerabilities using AI-enhanced techniques.

**Parameters:**
- `sourcePath` (string): Path to the source file
- `options` (object):
  - `outputDir` (string): Output directory for security reports (default: './security-reports')
  - `format` (string): Output format - 'json', 'markdown', or 'html' (default: 'markdown')
  - `model` (string): OpenAI model to use (default: 'gpt-4o')

**Returns:** Promise resolving to:
```typescript
{
  issueCount: number;
  reportPath: string;
  issues: Array<{
    id: string;
    title: string;
    description: string;
    severity: string; // 'critical', 'high', 'medium', 'low', or 'info'
    line?: number;
    code?: string;
    remediation?: string;
  }>;
}
```

#### `isAISecurityAvailable()`

Checks if AI-enhanced security analysis is available.

**Returns:** Boolean indicating if AI security analysis is available (requires OPENAI_API_KEY)

#### `setAISecurityApiKey(apiKey)`

Sets the OpenAI API key for AI-enhanced security analysis.

**Parameters:**
- `apiKey` (string): OpenAI API key

## Enhanced Watcher

The `EnhancedWatcher` class provides a more powerful file watching experience with AI integration.

### `new EnhancedWatcher(options)`

Creates a new enhanced watcher instance.

**Parameters:**
- `options` (object):
  - `include` (string[]): Glob patterns to include (default: all common web source files)
  - `exclude` (string[]): Glob patterns to exclude (default: node_modules, dist, etc.)
  - `generateTests` (boolean): Whether to generate tests on file changes (default: true)
  - `analyzeSecurity` (boolean): Whether to analyze security on file changes (default: true)
  - `useAIAnalysis` (boolean): Whether to use AI-enhanced security analysis (default: false)
  - `generateChecklists` (boolean): Whether to generate checklists on file changes (default: true)
  - `testOutputDir` (string): Output directory for generated tests (default: './tests')
  - `securityOutputDir` (string): Output directory for security reports (default: './security-reports')
  - `checklistOutputDir` (string): Output directory for checklists (default: './checklists')
  - `testFormat` (string): Test format - 'playwright' or 'selenium' (default: 'playwright')
  - `openAIApiKey` (string): OpenAI API key for AI-enhanced security analysis
  - `maxConcurrentTasks` (number): Maximum concurrent tasks (default: 3)

### EnhancedWatcher Methods

#### `watch(directoryPath)`

Starts watching the specified directory.

**Parameters:**
- `directoryPath` (string): Path to the directory to watch

**Returns:** Function to stop watching

#### `stop()`

Stops watching and cleans up resources.

**Returns:** Promise that resolves when the watcher has stopped

#### `analyzeFile(filePath, analysisTypes)`

Manually analyzes a file.

**Parameters:**
- `filePath` (string): Path to the file to analyze
- `analysisTypes` (object):
  - `generateTests` (boolean): Whether to generate tests
  - `analyzeSecurity` (boolean): Whether to analyze security
  - `useAI` (boolean): Whether to use AI-enhanced security analysis
  - `generateChecklists` (boolean): Whether to generate checklists

**Returns:** Promise resolving to an array of analysis results

#### `isAIAvailable()`

Checks if AI-enhanced security analysis is available.

**Returns:** Boolean indicating if AI security analysis is available

### EnhancedWatcher Events

The EnhancedWatcher extends EventEmitter and emits the following events:

- `ready`: Emitted when the watcher is ready
- `stopped`: Emitted when the watcher has stopped
- `file:change`: Emitted when a file changes, with change event details
- `analysis:complete`: Emitted when an analysis completes
- `error`: Emitted when an error occurs

## Examples

See the `examples` directory for more detailed usage examples:
- `api-usage.js`: Basic API usage
- `api-usage-with-ai.js`: AI-enhanced API usage

## License

MIT