@neurolint/cli/README.md

Professional React/Next.js modernization platform with CLI, VS Code, and Web App integrations

# NeuroLint CLI

[![npm version](https://img.shields.io/npm/v/@neurolint/cli.svg)](https://www.npmjs.com/package/@neurolint/cli)
[![npm downloads](https://img.shields.io/npm/dm/@neurolint/cli.svg)](https://www.npmjs.com/package/@neurolint/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)


> **The Problem**: Modern React/Next.js development is plagued with repetitive code issues - missing accessibility attributes, hydration errors, outdated patterns, and inconsistent configurations. Manual fixes are time-consuming and error-prone.

> **The Solution**: NeuroLint CLI automatically detects and fixes 50+ common issues across 7 intelligent layers, transforming your codebase from legacy patterns to modern best practices in minutes.

## Quick Demo

**Before** (Legacy React component):
```tsx
// Button.tsx - Common issues
function Button({ children, onClick }) {
  return (
    <button onClick={onClick}>
      {children}
    </button>
  );
}
```

**After** (Modern, accessible component):
```tsx
// Button.tsx - Fixed automatically
'use client';

import React from 'react';

interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}

function Button({ 
  children, 
  onClick, 
  variant = 'primary',
  disabled = false 
}: ButtonProps) {
  return (
    <button 
      onClick={onClick}
      disabled={disabled}
      className={`btn btn-${variant}`}
      aria-label={typeof children === 'string' ? children : undefined}
    >
      {children}
    </button>
  );
}

export default Button;
```

## What NeuroLint Fixes

### Next.js 15.5 Migration (New!)
**Problem**: Upgrading to Next.js 15.5 requires manual updates across your codebase
```bash
# Migrate your entire project to Next.js 15.5 compatibility
neurolint migrate . --all-layers --dry-run --verbose

# Apply changes with automatic rollback
neurolint migrate . --all-layers --backup --verbose

# Migrate specific layers for Next.js 15.5
neurolint migrate . --layers=1,2,5 --dry-run --verbose
```

**Features**:
- **Server Actions Enhancement**: Automatic error handling and validation
- **Metadata API Modernization**: Stricter TypeScript typing for `generateMetadata`
- **Deprecation Detection**: Warns about `legacyBehavior`, `next lint`, and old patterns
- **Caching Optimization**: Smart suggestions for `cache: 'force-cache'`
- **Turbopack Integration**: Automatic configuration for Next.js 15+
- **Layer 5 Next.js Fixes**: App Router optimization and directives

### Layer 1: Configuration Modernization
**Problem**: Outdated TypeScript and Next.js configs causing build issues
```json
// Before
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"]
  }
}

// After  
{
  "compilerOptions": {
    "target": "es2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}
```

### Layer 2: Pattern Standardization
**Problem**: Inconsistent patterns and deprecated syntax
```tsx
// Before
const Component = () => {
  console.log('debug info');
  return <div>&quot;Hello&quot;</div>;
}

// After
const Component = () => {
  return <div>"Hello"</div>;
}
```

### Layer 3: Accessibility & Components
**Problem**: Missing accessibility attributes and component best practices
```tsx
// Before
<img src="/logo.png" />
<button onClick={handleClick}>Submit</button>

// After
<img src="/logo.png" alt="Company logo" />
<button 
  onClick={handleClick}
  aria-label="Submit form"
  type="submit"
>
  Submit
</button>
```

### Layer 4: SSR/Hydration Safety
**Problem**: Client-side APIs causing hydration errors
```tsx
// Before
const Component = () => {
  const [theme, setTheme] = useState(localStorage.getItem('theme'));
  return <div>{window.innerWidth}px</div>;
}

// After
const Component = () => {
  const [theme, setTheme] = useState<string | null>(null);
  
  useEffect(() => {
    setTheme(localStorage.getItem('theme'));
  }, []);

  const [width, setWidth] = useState<number>(0);
  
  useEffect(() => {
    setWidth(window.innerWidth);
  }, []);

  return <div>{width}px</div>;
}
```

### Layer 5: Next.js App Router Optimization
**Problem**: Missing directives and inefficient imports
```tsx
// Before
import React from 'react';
import { useState } from 'react';

function ClientComponent() {
  return <div>Client content</div>;
}

// After
'use client';

import { useState } from 'react';

function ClientComponent() {
  return <div>Client content</div>;
}
```

### Layer 6: Testing & Error Handling
**Problem**: Missing error boundaries and test infrastructure
```tsx
// Before
function App() {
  return <MainComponent />;
}

// After
import { ErrorBoundary } from './utils/errorBoundary';

function App() {
  return (
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <MainComponent />
    </ErrorBoundary>
  );
}
```

### Layer 7: Adaptive Pattern Learning
**Problem**: Custom patterns that need intelligent detection
```tsx
// Before (Custom pattern detected by Layer 7)
const useCustomHook = () => {
  const [state, setState] = useState();
  // Missing cleanup
  return [state, setState];
}

// After (Automatically learned and fixed)
const useCustomHook = () => {
  const [state, setState] = useState();
  
  useEffect(() => {
    return () => {
      // Cleanup logic
    };
  }, []);
  
  return [state, setState];
}
```

## Installation

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

```bash
neurolint --help
```

## Usage Examples

### Basic Codebase Modernization
```bash
# Analyze your entire project
neurolint analyze src/

# Fix all issues automatically
neurolint fix src/ --all-layers

# Preview changes first
neurolint fix src/ --dry-run --verbose
```

### Targeted Fixes
```bash
# Fix only accessibility issues
neurolint fix src/ --layers 3

# Fix configuration and patterns
neurolint fix src/ --layers 1,2

# Fix SSR/hydration issues
neurolint fix src/ --layers 4,5
```

### Next.js 15.5 Migration
```bash
# Preview migration changes
neurolint migrate . --all-layers --dry-run --verbose

# Apply migration with rollback safety
neurolint migrate . --all-layers --backup --verbose

# Migrate specific layers for Next.js 15.5
neurolint migrate . --layers=1,2,5 --dry-run --verbose

# Migrate specific directory
neurolint migrate src/ --all-layers --dry-run
```

### Integration Examples
```bash
# Pre-commit hook
neurolint fix src/ --layers 2,3 --dry-run || exit 1

# CI/CD pipeline
neurolint analyze src/ --format=json --output=analysis.json
neurolint fix src/ --layers 1,2,5

# Team collaboration
neurolint rules --export=team-rules.json
neurolint rules --import=team-rules.json

# Next.js 15.5 migration in CI/CD
neurolint migrate . --layers=1,2,5 --dry-run --format=json --output=migration-report.json
```

## Real-World Use Cases

### 1. Legacy React Migration
**Scenario**: Upgrading from React 16 to React 18 with Next.js 13
```bash
# Fix all compatibility issues
neurolint fix src/ --layers 1,2,4,5
```
**Result**: 200+ files updated, 0 breaking changes, 100% compatibility

### 2. Accessibility Compliance
**Scenario**: Meeting WCAG 2.1 AA standards
```bash
# Add missing accessibility attributes
neurolint fix src/ --layers 3
```
**Result**: 150+ accessibility issues fixed automatically

### 3. Performance Optimization
**Scenario**: Reducing bundle size and improving Core Web Vitals
```bash
# Optimize imports and configurations
neurolint fix src/ --layers 1,5
```
**Result**: 30% bundle size reduction, improved LCP scores

### 4. Next.js 15.5 Migration
**Scenario**: Upgrading from Next.js 13 to Next.js 15.5
```bash
# Migrate entire project to Next.js 15.5
neurolint migrate . --all-layers --backup --verbose
```
**Result**: 396 files processed, 31 files updated, 0 breaking changes, full Next.js 15.5 compatibility

### 4. Team Code Standardization
**Scenario**: Enforcing consistent patterns across 10+ developers
```bash
# Apply learned patterns from previous projects
neurolint rules --import=company-standards.json
neurolint fix src/ --layers 7
```
**Result**: Consistent codebase, reduced code review time by 60%

## Troubleshooting

### Common Command Issues

**Issue**: `neurolint migrate-nextjs-15.5` command not found
**Solution**: Use the correct migration command:
```bash
# Instead of: neurolint migrate-nextjs-15.5 . --dry-run
# Use: neurolint migrate . --all-layers --dry-run --verbose

# For Next.js 15.5 specific fixes:
neurolint migrate . --layers=1,2,5 --dry-run --verbose
```

**Issue**: Authentication required for migration
**Solution**: Login first with your API key:
```bash
neurolint login <your-api-key>
neurolint status  # Verify authentication
```

**Issue**: Layer access denied
**Solution**: Check your plan and available layers:
```bash
neurolint status  # Shows available layers
```

### Getting Help
```bash
neurolint --help              # Show all commands
neurolint layers --verbose    # Show layer details
neurolint status              # Check authentication and plan
```

## Commands Reference

### Core Commands
- `neurolint analyze [path]` - Scan for issues and recommend fixes
- `neurolint fix [path]` - Apply automatic fixes
- `neurolint validate [path]` - Validate code without changes
- `neurolint layers` - List all available transformation layers

### Migration Commands
- `neurolint migrate [path]` - One-time migration service (enterprise)
- `neurolint migrate-biome [path]` - Migrate from ESLint to Biome

### Authentication Commands
- `neurolint login <api-key>` - Authenticate with your API key
- `neurolint logout` - Remove authentication
- `neurolint status` - Show authentication and usage status

### Layer Commands
- `neurolint config scan|fix` - Layer 1: Configuration fixes
- `neurolint patterns scan|fix` - Layer 2: Pattern fixes
- `neurolint components scan|fix` - Layer 3: Component fixes
- `neurolint hydration scan|fix` - Layer 4: Hydration fixes
- `neurolint nextjs scan|fix` - Layer 5: Next.js fixes
- `neurolint testing scan|fix` - Layer 6: Testing fixes
- `neurolint adaptive scan|fix` - Layer 7: Adaptive pattern learning

### Advanced Commands
- `neurolint rules` - Manage learned patterns and rules
- `neurolint stats` - Get project statistics and insights
- `neurolint clean` - Clean up old backup and state files
- `neurolint backups` - Manage centralized backups
- `neurolint init-config` - Generate or display configuration
- `neurolint init-tests [path]` - Generate test files for components
- `neurolint health` - Run a health check to verify configuration