bun-runtime ยท diff

v5.0.0 to v5.0.0

52 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
version: "5.0.0"
scope: ["typescript", "javascript", "json", "toml"]
- description: Bun runtime patterns and best practices
alwaysApply: true
+ description: "Bun runtime patterns and best practices"
lastUpdated: "2025-10-08"
dependencies: ["quality-standards", "process-management"]
---
# Bun Runtime Rules
+
+ ## ๐Ÿ” Code Searchability Patterns
+
+ ### Find Bun Runtime Issues with ast-grep
+
+ ```bash
+ # Find incorrect process spawning (should use processManager)
+ ast-grep --pattern 'Bun.spawn($$$)' src/
+ ast-grep --pattern 'import { spawn } from "bun"' src/
+ ast-grep --pattern 'import { spawn } from "child_process"' src/
+ sg -p 'Bun.spawn' src/
+ sg -p 'from "child_process"' src/
+
+ # Find Node.js fs usage (should use Bun file APIs)
+ ast-grep --pattern 'import fs from "fs"' src/
+ ast-grep --pattern 'import { readFile } from "fs/promises"' src/
+ sg -p 'from "fs"' src/
+ sg -p 'from "fs/promises"' src/
+
+ # Find incorrect test imports (should use bun:test)
+ ast-grep --pattern 'import { describe, test, expect } from "vitest"' tests/
+ ast-grep --pattern 'import { describe, test, expect } from "@jest/globals"' tests/
+ sg -p 'from "vitest"' tests/
+ sg -p 'from "@jest/globals"' tests/
+
+ # Find npm/yarn usage (should use bun)
+ ast-grep --pattern 'npm install' scripts/
+ ast-grep --pattern 'yarn install' scripts/
+ sg -p 'npm install' scripts/
+ sg -p 'yarn install' scripts/
+ ```
+
+ ### Bun Runtime Discovery Commands
+
+ ```bash
+ # Find all Bun-specific patterns
+ sg search 'Bun.' src/
+ sg search 'bun:' src/
+ sg search 'processManager' src/
+
+ # Find Node.js anti-patterns
+ sg search 'from "fs"' src/
+ sg search 'from "child_process"' src/
+ sg search 'npm ' scripts/
+ sg search 'yarn ' scripts/
+
+ # Find Bun native APIs
+ sg search 'Bun.file' src/
+ sg search 'Bun.write' src/
+ sg search 'Bun.password' src/
+ ```
## Process Spawning (CRITICAL)
### Always Use Process Manager
```typescript
// โŒ WRONG - Creates zombie processes
import { spawn } from 'bun';
const proc = Bun.spawn(['command']);
// โŒ WRONG - Old Node.js pattern
import { spawn } from 'child_process';
// โœ… CORRECT - Tracked and cleaned up
import processManager from './tests/utils/process-cleanup';
const proc = processManager.spawn(['command'], options);
```
See [Process Management Rules](mdc:.cursor/rules/process-management.mdc) for details.
## File Operations
**Use Bun APIs, not Node.js fs:**
```typescript
// โœ… CORRECT - Bun file API
const file = Bun.file('path/to/file.txt');
const contents = await file.text();
await Bun.write('output.txt', 'content');
// โŒ WRONG - Node.js fs
import fs from 'fs';
import { readFile } from 'fs/promises';
```
## Test Runner
**Use Bun Test, not Vitest or Jest:**
```typescript
// โœ… CORRECT - Bun Test
import { describe, test, expect } from 'bun:test';
// โŒ WRONG - Vitest/Jest imports
import { describe, test, expect } from 'vitest';
```
## Commands
**Always use Bun commands:**
```bash
โœ… bun install # Install dependencies
โœ… bun run dev # Development server
โœ… bun test # Run tests
โœ… bun run build # Build project
โŒ npm install # WRONG
โŒ yarn install # WRONG
โŒ node script.js # WRONG - use: bun run script.ts
```
## Configuration
### TypeScript Config
```json
{
"compilerOptions": {
"module": "Preserve",
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"verbatimModuleSyntax": true,
"noEmit": true,
"types": ["@types/bun"]
}
}
```
### Bun Config (bunfig.toml)
```toml
[test]
timeout = 10000 # 10 seconds default
root = "."
[install]
# Package manager settings
```
## Native APIs
Bun provides native APIs for:
- Crypto
- Compression
- Encoding
- Streams
- Timers
- Workers
- Cron
- JWT
- Hash maps
- UUID
- Path
- Glob
- Watch
- Subprocess
- HTTP client
- WebSocket
- TLS
**Never install external packages for these features.**
## Key Files
- [Bun Config](mdc:bunfig.toml) - Runtime configuration
- [TypeScript Config](mdc:tsconfig.json) - TypeScript settings
- [Package.json](mdc:package.json) - Scripts and dependencies
- [Process Cleanup](mdc:tests/utils/process-cleanup.ts) - Process management
## Related Rules
- [Process Management](mdc:.cursor/rules/process-management.mdc) - Process spawning patterns
- [Testing Patterns](mdc:.cursor/rules/testing-patterns.mdc) - Bun Test usage
- [Security Patterns](mdc:.cursor/rules/security-patterns.mdc) - Security considerations
## Common Mistakes
### โŒ Wrong Imports
```typescript
// Don't use these
import { spawn } from 'bun'; // Wrong API
import { spawn } from 'child_process'; // Node.js
import fs from 'fs'; // Node.js
```
### โœ… Correct Imports
```typescript
// Use these
import processManager from './tests/utils/process-cleanup';
const file = Bun.file('path');
import { describe, test } from 'bun:test';
```
## Rules Summary
1. โœ… Use [processManager](mdc:tests/utils/process-cleanup.ts) for all process spawning
2. โœ… Use Bun file APIs (not Node.js fs)
3. โœ… Use Bun test runner (not Vitest/Jest)
4. โœ… Use bun commands (not npm/yarn)
5. โœ… Use Bun native APIs when available
6. โŒ Never use `Bun.spawn()` directly
7. โŒ Never use Node.js `child_process`
8. โŒ Never use Node.js `fs` module
9. โŒ Never install packages for Bun-native features
---
## Related Rules
- [Quality Standards](mdc:.cursor/rules/quality-standards.mdc) - Code quality standards โญ **NEW**
- [Process Management](mdc:.cursor/rules/process-management.mdc) - Zombie process prevention
- [Testing Patterns](mdc:.cursor/rules/testing-patterns.mdc) - Bun test patterns
- [Cloudflare Workers](mdc:.cursor/rules/cloudflare-workers.mdc) - Workers with Bun
## Related Documentation
- [docs/QUALITY_STANDARDS.md](mdc:docs/QUALITY_STANDARDS.md) - Complete quality guide โญ **NEW**
- [tests/utils/process-cleanup.ts](mdc:tests/utils/process-cleanup.ts) - Process manager
- [bunfig.toml](mdc:bunfig.toml) - Bun configuration
- [package.json](mdc:package.json) - Project configuration
- [tsconfig.json](mdc:tsconfig.json) - TypeScript configuration
---
**Status:** Bun runtime patterns established
**Last Updated:** 2025-10-08