npm package: @rayburst/cli
Description: Rayburst - Automatic code analysis for TypeScript/JavaScript projects via Vite plugin
Latest version: 0.4.22

# Rayburst

Automatic code analysis for TypeScript/JavaScript projects. Rayburst runs in the background during development and generates dependency graphs that you can visualize in the Rayburst web application.

## Features

- **Automatic Analysis**: Runs automatically when you start your dev server - no manual commands needed
- **Real-time Updates**: Watches for file changes and updates analysis instantly
- **TypeScript/JavaScript Support**: Full analysis of TS, TSX, JS, and JSX files
- **React Components**: Detects React components and their dependencies
- **Function Tracking**: Maps function calls and relationships
- **Git Integration**: Tracks branches, commits, and changes
- **Zero Configuration**: Works out of the box with sensible defaults

## Installation

```bash
npm install --save-dev @rayburst/cli
```

## Usage

### Vite Projects

Add the Rayburst plugin to your `vite.config.ts`:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { rayburstPlugin } from '@rayburst/cli/vite'

export default defineConfig({
  plugins: [
    rayburstPlugin(),  // Add this line
    react(),
  ],
})
```

That's it! Now when you run `npm run dev`, Rayburst will automatically:
1. Run initial code analysis
2. Generate `.rayburst/analysis.json`
3. Watch for file changes
4. Update analysis in real-time

### Configuration Options

```typescript
rayburstPlugin({
  // Disable the plugin (e.g., for testing)
  enabled: true,

  // Debounce delay for file changes (ms)
  debounceMs: 1500,

  // Custom output path
  outputPath: '.rayburst/analysis.json',
})
```

## Output

The plugin generates a `.rayburst/` directory in your project root:

```
my-project/
├── .rayburst/
│   └── analysis.json    # Analysis data (nodes, edges, dependencies)
├── .gitignore           # Auto-updated to ignore .rayburst/
├── src/
├── vite.config.ts
└── package.json
```

The `.rayburst/` directory is automatically added to your `.gitignore`.

## Analysis Data

The generated `analysis.json` contains:

- **Nodes**: Components, functions, state declarations
- **Edges**: Dependencies between nodes
- **Branches**: Git branch information
- **Files**: Modification timestamps

## Viewing Your Analysis

Once analysis is complete, open the [Rayburst web application](https://rayburst.app) in Chrome or Edge:

1. Click "Add Project" button
2. Select your project folder
3. The app will load `.rayburst/analysis.json` automatically
4. Explore your codebase visually with interactive dependency graphs

The web app uses the File System Access API (Chrome/Edge only) to read your local analysis data.

## Example Output

```typescript
// src/App.tsx
import { Button } from './components/Button'

export function App() {
  return <Button onClick={() => alert('Hello')} />
}
```

Rayburst detects:
- `App` component (node)
- `Button` component usage (edge: App → Button)
- JSX relationships
- File structure

## Console Output

```bash
$ npm run dev

[Rayburst] Starting code analysis...
[Rayburst] Initial analysis complete: 42 nodes, 68 edges

# When you edit a file:
[Rayburst] File changed: src/App.tsx
[Rayburst] Analysis updated:
  Added: 1 nodes, 2 edges
  Modified: 1 nodes
```

## How It Works

Rayburst uses a Vite plugin that:

1. **Hooks into Vite's lifecycle**: Runs when dev server starts
2. **Uses ts-morph**: Analyzes TypeScript/JavaScript AST
3. **Watches files**: Leverages Vite's built-in file watcher
4. **Incremental updates**: Only re-analyzes changed files
5. **Generates graphs**: Produces node/edge data structures

## Requirements

- **Vite**: 4.x, 5.x, 6.x, or 7.x
- **TypeScript**: Project must have `tsconfig.json`
- **package.json**: Required for project metadata

## Browser Compatibility

The analysis data can be viewed in the Rayburst web app, which requires:
- Chrome 86+ or Edge 86+ (for File System Access API)

## Advanced Usage

### Programmatic API

You can also use Rayburst programmatically:

```typescript
import { analyzeProject, writeLocalAnalysis } from '@rayburst/cli'

// Analyze a project
const analysis = await analyzeProject('/path/to/project')

// Write results
await writeLocalAnalysis('/path/to/project', analysis)
```

### Custom Integration

```typescript
import {
  analyzeProject,
  ensureRayburstDir,
  writeLocalAnalysis
} from '@rayburst/cli'

async function customAnalysis() {
  const projectPath = process.cwd()

  // Ensure .rayburst directory exists
  await ensureRayburstDir(projectPath)

  // Run analysis
  const result = await analyzeProject(projectPath)

  // Save results
  await writeLocalAnalysis(projectPath, result)

  console.log(`Analyzed ${result.planData.nodes.length} nodes`)
}
```

## Troubleshooting

### Plugin Not Running

Make sure:
1. Plugin is added to `vite.config.ts`
2. You're running in dev mode (`npm run dev`, not `npm run build`)
3. Project has `tsconfig.json`

### No Analysis Generated

Check:
1. `.rayburst/` directory exists
2. Console for error messages
3. Project has TypeScript/JavaScript files

### Analysis Fails

Common causes:
- Invalid `tsconfig.json`
- TypeScript compilation errors
- Missing `package.json`

Enable verbose logging:
```typescript
rayburstPlugin({
  enabled: process.env.DEBUG === 'true'
})
```

## CI/CD

The plugin is automatically disabled in CI environments (when `CI=true`). To force enable:

```typescript
rayburstPlugin({
  enabled: true  // Always enabled
})
```

## Migration from Old Versions

If you were using `rayburst watch` command:

**Before:**
```bash
# Terminal 1
npm run dev

# Terminal 2
rayburst watch
```

**After:**
```typescript
// vite.config.ts
export default defineConfig({
  plugins: [rayburstPlugin(), react()],
})
```

```bash
# Just one terminal
npm run dev  # Rayburst runs automatically!
```

## Contributing

Contributions welcome! Please read our contributing guidelines.

## License

MIT

## Links

- [Documentation](https://rayburst.app/docs)
- [GitHub Repository](https://github.com/your-org/rayburst)
- [Issue Tracker](https://github.com/your-org/rayburst/issues)