@ordojs/dev-tools/README.md

Advanced developer tools for OrdoJS with component inspector, AST explorer, and performance profiling

# @ordojs/dev-tools

Advanced developer tools for OrdoJS with component inspector, AST explorer, performance profiling,
and enhanced development experience.

## Features

### Component Inspector

- Real-time component inspection and debugging
- Component tree visualization
- Props and state inspection
- Performance metrics tracking
- Component dependency analysis

### Performance Profiler

- Application performance profiling
- Custom performance measurements
- Performance profile management
- Real-time performance monitoring
- Performance optimization suggestions

### AST Explorer

- Abstract Syntax Tree visualization
- Code structure analysis
- Node search and filtering
- AST statistics and metrics
- Code transformation tracking

### Bundle Analyzer

- Bundle size analysis
- Dependency analysis
- Code splitting optimization
- Bundle comparison tools
- Optimization suggestions

### Error Overlay

- Real-time error display
- Error categorization
- Helpful error suggestions
- Error statistics
- Error tracking and reporting

### Enhanced HMR

- Improved hot module replacement
- State preservation during updates
- Update tracking and statistics
- Fast refresh capabilities
- Update debugging tools

### Development Server

- Enhanced development server
- Dev tools integration
- API endpoints for all tools
- Real-time communication
- Configuration management

## Installation

```bash
pnpm add @ordojs/dev-tools
```

## Usage

### Basic Setup

```typescript
import { DevToolsManager } from '@ordojs/dev-tools';

const devTools = new DevToolsManager({
  inspector: true,
  profiler: true,
  astExplorer: true,
  bundleAnalyzer: true,
  errorOverlay: true,
  enhancedHMR: true,
  devServer: {
    port: 3000,
    host: 'localhost',
    hmr: true,
    https: false,
    compression: true,
    cors: true,
    staticDir: 'dist',
  },
});

// Start all dev tools
await devTools.start();

// Stop all dev tools
await devTools.stop();
```

### Component Inspector

```typescript
import { ComponentInspector } from '@ordojs/dev-tools/inspector';

const inspector = new ComponentInspector();

// Register a component for inspection
inspector.registerComponent({
  name: 'MyComponent',
  filePath: '/src/components/MyComponent.ordo',
  props: { title: 'Hello' },
  state: { count: 0 },
  children: [],
  renderCount: 1,
  mountTime: Date.now(),
  lastUpdateTime: Date.now(),
  performance: {
    renderTime: 5,
    memoryUsage: 1024,
    reRenderCount: 0,
    averageRenderTime: 5,
    peakMemoryUsage: 1024,
  },
});

// Get component statistics
const stats = inspector.getStats();
console.log(stats);
```

### Performance Profiler

```typescript
import { PerformanceProfiler } from '@ordojs/dev-tools/profiler';

const profiler = new PerformanceProfiler();

// Start a performance profile
const profile = profiler.startProfile('app-render', {
  component: 'App',
  userAgent: navigator.userAgent,
});

// Add measurements
const measurement = profiler.addMeasurement('app-render', 'component-mount', 'rendering');

// End measurement
profiler.endMeasurement('app-render', 'component-mount');

// Stop profile
const completedProfile = profiler.stopProfile('app-render');
```

### AST Explorer

```typescript
import { ASTExplorer } from '@ordojs/dev-tools/ast-explorer';

const astExplorer = new ASTExplorer();

// Parse source code
const ast = astExplorer.parseSourceCode(sourceCode, 'MyComponent.ordo');

// Find nodes by type
const elements = astExplorer.findNodesByType('MyComponent.ordo', 'Element');

// Get AST statistics
const stats = astExplorer.getASTStats('MyComponent.ordo');
```

### Bundle Analyzer

```typescript
import { BundleAnalyzer } from '@ordojs/dev-tools/bundle-analyzer';

const bundleAnalyzer = new BundleAnalyzer();

// Analyze a bundle
const analysis = await bundleAnalyzer.analyzeBundle('dist/bundle.js', 'main-bundle');

// Get optimization suggestions
const suggestions = bundleAnalyzer.getOptimizationSuggestions('main-bundle');

// Compare bundles
const comparison = bundleAnalyzer.compareBundles('v1-bundle', 'v2-bundle');
```

### Error Overlay

```typescript
import { ErrorOverlay } from '@ordojs/dev-tools/error-overlay';

const errorOverlay = new ErrorOverlay();

// Add an error
errorOverlay.addError('error-1', {
  message: 'Cannot find module "react"',
  stack: 'Error: Cannot find module "react"...',
  filePath: '/src/components/App.ordo',
  lineNumber: 1,
  columnNumber: 1,
  codeFrame: 'import React from "react";',
  suggestions: ['Check if react is installed', 'Verify the import path'],
});

// Generate suggestions for an error
const suggestions = errorOverlay.generateSuggestions('error-1');
```

### Enhanced HMR

```typescript
import { EnhancedHMR } from '@ordojs/dev-tools/hmr';

const hmr = new EnhancedHMR();

// Send an HMR update
hmr.sendUpdate({
  type: 'component',
  filePath: '/src/components/MyComponent.ordo',
  timestamp: Date.now(),
  data: { componentName: 'MyComponent' },
  affectedComponents: ['MyComponent'],
});

// Enable state preservation
hmr.enableStatePreservation();
```

## Configuration

### Dev Tools Configuration

```typescript
interface DevToolsConfig {
  inspector: boolean;
  profiler: boolean;
  astExplorer: boolean;
  bundleAnalyzer: boolean;
  errorOverlay: boolean;
  enhancedHMR: boolean;
  devServer: DevServerConfig;
}
```

### Development Server Configuration

```typescript
interface DevServerConfig {
  port: number;
  host: string;
  hmr: boolean;
  https: boolean;
  compression: boolean;
  cors: boolean;
  staticDir: string;
  proxy?: Record<string, string>;
}
```

## API Endpoints

The development server provides the following API endpoints:

- `GET /api/dev-tools/health` - Health check
- `GET /api/dev-tools/inspector` - Component inspector data
- `GET /api/dev-tools/profiler` - Performance profiler data
- `GET /api/dev-tools/ast-explorer` - AST explorer data
- `GET /api/dev-tools/bundle-analyzer` - Bundle analyzer data
- `GET /api/dev-tools/error-overlay` - Error overlay data
- `GET /api/dev-tools/hmr` - HMR data

## Browser Extension

The dev tools work with a browser extension that provides:

- Component inspector UI
- Performance profiler interface
- AST explorer visualization
- Bundle analyzer charts
- Error overlay display
- HMR status monitoring

## Integration with OrdoJS CLI

The dev tools integrate seamlessly with the OrdoJS CLI:

```bash
# Start development server with all dev tools
ordojs dev --dev-tools

# Start with specific tools
ordojs dev --inspector --profiler --ast-explorer

# Configure dev tools
ordojs dev --dev-tools-config .ordojs-dev-tools.json
```

## Development

### Building

```bash
pnpm build
```

### Testing

```bash
pnpm test
```

### Development Mode

```bash
pnpm dev
```

## License

MIT