@neurolint/cli/README.md

NeuroLint CLI for React/Next.js modernization with advanced 6-layer orchestration and intelligent AST transformations

# NeuroLint CLI

Professional React/Next.js modernization tool with advanced AST transformations and intelligent code analysis.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Features](#features)
- [Commands](#commands)
- [Layer System](#layer-system)
- [Examples](#examples)
- [Configuration](#configuration)
- [CI/CD Integration](#cicd-integration)
- [Troubleshooting](#troubleshooting)
- [API Reference](#api-reference)
- [Support](#support)

## Installation

### Global Installation (Recommended)

```bash
npm install -g @neurolint/cli
```

### Local Project Installation

```bash
npm install --save-dev @neurolint/cli
npx neurolint --version
```

### Verify Installation

```bash
neurolint --version  # Should output: 1.2.0
neurolint --help     # Show available commands
```

## Quick Start

### 1. Analyze Your Project (Always Free)

```bash
# Analyze entire project - completely free
neurolint analyze

# Analyze specific directory - always free
neurolint analyze src/

# Get detailed analysis - free unlimited
neurolint analyze --verbose
```

### 2. Apply Fixes Based on Your Tier

```bash
# Free Tier: Layers 1-2 fixes (unlimited)
neurolint fix --layers 1,2

# Basic Tier ($9/mo): Layers 1-4 fixes  
neurolint fix --layers 1,2,3,4

# Professional+ ($29/mo): All layers
neurolint fix --all-layers
```

## Features

- **6-Layer Modernization System**: Comprehensive React/Next.js upgrade path
- **Advanced AST Transformations**: Babel-powered precise code modifications
- **Smart Analysis**: Intelligent pattern detection and dependency analysis
- **Freemium Model**: Free unlimited scans, premium fixes
- **TypeScript Support**: Full TypeScript analysis and type-aware transformations
- **Next.js 14+ Ready**: App Router migration and optimization
- **CI/CD Integration**: JSON/HTML reporting for automated workflows
- **Backup Protection**: Automatic backup creation before applying fixes
- **Incremental Processing**: Apply fixes layer by layer with validation

## Commands

### Global Commands

#### `neurolint analyze [path]`
Analyze files for modernization opportunities.

**Options:**
- `--include <patterns>` - File patterns to include (default: `**/*.{ts,tsx,js,jsx}`)
- `--exclude <patterns>` - File patterns to exclude (default: `**/node_modules/**,**/dist/**,**/.next/**`)
- `--format <type>` - Output format: `console`, `json`, `html` (default: `console`)
- `--output <file>` - Save analysis to file
- `--layers <list>` - Specific layers to analyze: `1,2,3,4,5,6` or `all` (default: `all`)
- `--verbose` - Detailed output with execution information

**Examples:**
```bash
neurolint analyze src/components --verbose
neurolint analyze --format=json --output=analysis.json
neurolint analyze --layers=3,4 --include="**/*.tsx"
```

#### `neurolint fix [path]`
Apply modernization fixes (Premium feature).

**Options:**
- `--api-key <key>` - NeuroLint Professional API key
- `--dry-run` - Preview changes without applying them
- `--backup` - Create backup before applying fixes (default: `true`)
- `--layers <list>` - Specific layers to apply
- All analyze options also apply

**Examples:**
```bash
neurolint fix --dry-run --verbose
neurolint fix src/ --layers=1,2,3 --backup
neurolint fix --api-key=your_key --exclude="**/test/**"
```

#### `neurolint layers`
Show detailed information about all modernization layers.

#### `neurolint init-config [options]`
Generate NeuroLint configuration file.

**Options:**
- `--init` - Create `.neurolintrc.json` file
- `--show` - Show current configuration

### Layer-Specific Commands

Each layer can be executed individually for targeted fixes:

#### `neurolint <layer> scan|fix [path]`

**Available layers:**
- `config` - Configuration modernization
- `content` - Content standardization
- `components` - Component intelligence
- `hydration` - SSR/Hydration safety
- `approuter` - Next.js App Router optimization
- `quality` - Testing & validation

**Examples:**
```bash
neurolint config scan --verbose
neurolint components fix src/components/
neurolint hydration scan --include="**/pages/**"
neurolint approuter fix app/ --backup
```

## Layer System

### Layer 1: Configuration Modernization

**What it does:**
- Updates `tsconfig.json` to modern TypeScript settings
- Modernizes `next.config.js` configuration
- Optimizes `package.json` scripts and dependencies

**Before:**
```json
{
  "compilerOptions": {
    "target": "es5",
    "strict": false
  }
}
```

**After:**
```json
{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "downlevelIteration": true,
    "skipLibCheck": true
  }
}
```

### Layer 2: Content Standardization

**What it does:**
- Converts HTML entities to proper characters
- Modernizes variable declarations (`var` → `const`/`let`)
- Standardizes console output and debugging patterns
- Cleans up content formatting

**Before:**
```javascript
var message = &quot;Hello World&quot;;
console.log("Debug info");
```

**After:**
```javascript
const message = "Hello World";
console.debug("Debug info");
```

### Layer 3: Component Intelligence

**What it does:**
- Adds missing `key` props in React lists
- Fixes missing accessibility attributes
- Enhances component prop types
- Optimizes component structure

**Before:**
```jsx
{users.map(user => (
  <div>{user.name}</div>
))}
<img src="/avatar.jpg" />
```

**After:**
```jsx
{users.map(user => (
  <div key={user.id}>{user.name}</div>
))}
<img src="/avatar.jpg" alt="User avatar" />
```

### Layer 4: SSR/Hydration Safety

**What it does:**
- Guards client-side API usage with SSR checks
- Protects `localStorage`, `sessionStorage`, `window` access
- Adds hydration-safe patterns for theme providers
- Prevents server-client mismatches

**Before:**
```javascript
const theme = localStorage.getItem('theme');
const width = window.innerWidth;
```

**After:**
```javascript
const theme = typeof window !== 'undefined' ? localStorage.getItem('theme') : null;
const width = typeof window !== 'undefined' ? window.innerWidth : 0;
```

### Layer 5: Next.js App Router Optimization

**What it does:**
- Adds `'use client'` directives for interactive components
- Adds `'use server'` directives for server components
- Optimizes App Router file structure
- Enhances server component patterns

**Before:**
```jsx
// Missing directive
function InteractiveButton() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

**After:**
```jsx
'use client';

function InteractiveButton() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

### Layer 6: Testing & Validation

**What it does:**
- Suggests error boundary implementations
- Optimizes performance patterns
- Enhances accessibility compliance
- Adds validation frameworks

## Examples

### Complete Project Modernization

```bash
# 1. Initial analysis
neurolint analyze --format=html --output=before-analysis.html

# 2. Layer-by-layer fixes (recommended approach)
neurolint config fix --verbose          # Update configurations
neurolint content fix --backup          # Clean up content
neurolint components fix               # Fix React patterns
neurolint hydration fix               # Add SSR safety
neurolint approuter fix app/          # Next.js optimizations

# 3. Final validation
neurolint analyze --format=html --output=after-analysis.html
```

### CI/CD Integration

```bash
# Generate machine-readable report
neurolint analyze --format=json --output=analysis.json

# Check if fixes are needed (exit code indicates issues found)
neurolint analyze --format=json | jq '.issues | length'

# Apply fixes in CI environment
NEUROLINT_API_KEY=$API_KEY neurolint fix --dry-run --format=json
```

### Selective Modernization

```bash
# Only TypeScript and React patterns
neurolint fix --layers=1,3 src/

# Only SSR safety for specific files
neurolint hydration fix src/pages/ --include="**/*.tsx"

# Configuration only (safe for any project)
neurolint config fix --verbose
```

### Large Codebase Processing

```bash
# Process in smaller chunks
neurolint analyze src/components/ --verbose
neurolint analyze src/pages/ --verbose
neurolint analyze src/utils/ --verbose

# Apply fixes incrementally
neurolint fix src/components/ --layers=3,4 --backup
neurolint fix src/pages/ --layers=4,5 --backup
```

## Configuration

### Configuration File

Create `.neurolintrc.json` in your project root:

```bash
neurolint init-config --init
```

### Example Configuration

```json
{
  "enabledLayers": [1, 2, 3, 4, 5, 6],
  "include": [
    "**/*.{ts,tsx,js,jsx}",
    "*.config.js",
    "tsconfig.json"
  ],
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.next/**",
    "**/coverage/**",
    "**/build/**"
  ],
  "verbose": false,
  "backup": true,
  "format": "console",
  "apiUrl": "https://app.neurolint.dev/api",
  "timeout": 30000
}
```

### Environment Variables

```bash
# API Authentication
NEUROLINT_API_KEY=your_api_key_here

# Alternative API endpoint
NEUROLINT_API_URL=https://custom-api.example.com

# Debug mode
NEUROLINT_VERBOSE=true
NEUROLINT_DEBUG=true
```

## CI/CD Integration

### GitHub Actions

```yaml
name: NeuroLint Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install NeuroLint CLI
        run: npm install -g @neurolint/cli
      
      - name: Run Analysis
        run: |
          neurolint analyze --format=json --output=analysis.json
          neurolint analyze --format=html --output=analysis.html
      
      - name: Upload Reports
        uses: actions/upload-artifact@v3
        with:
          name: neurolint-reports
          path: |
            analysis.json
            analysis.html
```

### Jenkins Pipeline

```groovy
pipeline {
    agent any
    stages {
        stage('NeuroLint Analysis') {
            steps {
                sh 'npm install -g @neurolint/cli'
                sh 'neurolint analyze --format=json --output=analysis.json'
                publishHTML([
                    allowMissing: false,
                    alwaysLinkToLastBuild: true,
                    keepAll: true,
                    reportDir: '.',
                    reportFiles: 'analysis.html',
                    reportName: 'NeuroLint Report'
                ])
            }
        }
    }
}
```

## Pricing Tiers

| Tier | Price | What You Get |
|------|-------|-------------|
| **Free** | $0 | Unlimited scans + Layers 1-2 fixes |
| **Basic** | $9/month | Layers 1-4 fixes + Components |
| **Professional** | $29/month | All layers + API + CI/CD |
| **Business** | $79/month | Enhanced API + Team features |
| **Enterprise** | $149/month | Custom rules + Priority support |

### Free Tier Features
- **Unlimited Analysis**: Scan any project, any size
- **Layer 1 Fixes**: Configuration modernization (tsconfig, next.config)
- **Layer 2 Fixes**: Content standardization (HTML entities, patterns)
- **No Signup Required**: CLI works immediately
- **All Platforms**: Works with web app and VS Code extension

### Getting Your API Key

1. Visit [neurolint.dev/pricing](https://neurolint.dev/pricing)
2. Choose your plan and complete payment
3. Access your dashboard at [app.neurolint.dev](https://app.neurolint.dev)
4. Copy your API key from the settings page
5. Set the environment variable: `export NEUROLINT_API_KEY=your_key`

## Troubleshooting

### Common Issues

#### Command Not Found

```bash
# Error: neurolint: command not found
# Solution: Install globally or use npx
npm install -g @neurolint/cli
# OR
npx @neurolint/cli --version
```

#### API Authentication Failed

```bash
# Error: Authentication failed
# Solution: Verify API key
echo $NEUROLINT_API_KEY  # Should show your key
neurolint fix --api-key your_actual_key
```

#### No Files Found to Analyze

```bash
# Error: No files found to analyze
# Solution: Check include/exclude patterns
neurolint analyze --include="**/*.{ts,tsx}" --verbose
neurolint analyze src/ --exclude="**/node_modules/**"
```

#### Layer Execution Failed

```bash
# Error: Layer X execution failed
# Solution: Run with verbose mode and check logs
neurolint fix --verbose --dry-run
neurolint components scan --verbose  # Test specific layer
```

#### Permission Denied

```bash
# Error: EACCES: permission denied
# Solution: Check file permissions or use sudo
sudo chown -R $USER:$USER .
# OR
npm install -g @neurolint/cli --unsafe-perm
```

### Debug Mode

Enable detailed logging:

```bash
# Environment variable
export NEUROLINT_DEBUG=true
neurolint analyze

# Command line option
neurolint analyze --verbose

# Check configuration
neurolint init-config --show
```

### Performance Issues

```bash
# Large codebase optimization
neurolint analyze --exclude="**/node_modules/**" --exclude="**/dist/**"

# Process specific file types only
neurolint analyze --include="**/*.tsx" --include="**/*.ts"

# Reduce layer scope
neurolint fix --layers=1,2 --verbose
```

## API Reference

### Exit Codes

- `0` - Success, no issues found
- `1` - Issues found (analysis mode) or general error
- `2` - Invalid command line arguments
- `3` - Configuration error
- `4` - API authentication error
- `5` - File system error

### Output Formats

#### JSON Format

```json
{
  "summary": {
    "filesAnalyzed": 45,
    "issuesFound": 12,
    "layersProcessed": [1, 2, 3, 4]
  },
  "issues": [
    {
      "file": "src/components/Button.tsx",
      "layer": 3,
      "type": "missing-key",
      "line": 15,
      "severity": "warning",
      "description": "Missing key prop in mapped element"
    }
  ]
}
```

#### HTML Format

Interactive HTML report with:
- Executive summary
- File-by-file breakdown
- Layer-specific issues
- Fix recommendations
- Visual charts and graphs

### Configuration Schema

```typescript
interface NeuroLintConfig {
  enabledLayers: number[];
  include: string[];
  exclude: string[];
  verbose: boolean;
  backup: boolean;
  format: 'console' | 'json' | 'html';
  apiUrl: string;
  timeout: number;
}
```

## Performance

### Benchmarks

- **Small project** (< 100 files): ~5-10 seconds
- **Medium project** (100-500 files): ~30-60 seconds  
- **Large project** (500+ files): ~2-5 minutes
- **Memory usage**: ~50-100MB for typical projects

### Optimization Tips

1. **Use specific layers** instead of processing all layers
2. **Exclude unnecessary directories** like `node_modules`, `dist`
3. **Process incrementally** for very large codebases
4. **Use file patterns** to target specific file types

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
git clone https://github.com/neurolint/cli
cd cli
npm install
npm test
```

## Support

### Documentation
- **Official Docs**: [neurolint.dev/docs](https://app.neurolint.dev/docs)
- **API Reference**: [neurolint.dev/api](https://app.neurolint.dev/api)
- **Migration Guides**: [neurolint.dev/guides](https://app.neurolint.dev/guides)


### Professional Support
- **Email**: support@neurolint.dev
- **Priority Support**: Available with Business+ plans
- **Custom Solutions**: enterprise@neurolint.dev

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Professional React/Next.js modernization made simple.**

*Transform your legacy codebase with confidence using NeuroLint's intelligent analysis and AST-powered fixes.*