critical-rules

name	critical-rules
description	Use always - non-negotiable rules for TypeScript safety, socket events, and React patterns

Critical Rules

MANDATORY rules that must NEVER be violated. These prevent common bugs and ensure code quality.

Checklist

Rule 1: TypeScript Type Safety

• NEVER use any type - no exceptions, including tests
  • ❌ const data: any = response
  • ✅ const data: unknown = response
  • ✅ const data = response as UserData
  • ✅ For test mocks: as unknown as Type

Why: any disables all type checking and hides bugs. Use proper types, unknown, or type assertions instead.

Examples:

// ❌ Bad - loses all type safety
function process(data: any) {
  return data.user.name // No error if user is undefined!
}

// ✅ Good - proper typing
function process(data: unknown) {
  if (isUserData(data)) {
    return data.user.name
  }
  throw new Error('Invalid data')
}

// ✅ Good - type assertion when you know the type
const mockSocket = {
  on: vi.fn(),
  emit: vi.fn()
} as unknown as Socket

Rule 2: Socket Event Handling

• NEVER use socket.on() directly in components
  • ❌ socket.on('event', callback) - Breaks on reconnection
  • ✅ useSocketEvent('event', callback, [callback]) - Reactive and safe

Why: Direct socket.on() doesn't re-subscribe when socket reconnects. Use the useSocketEvent hook which handles reconnection automatically.

Examples:

// ❌ Bad - loses events after reconnection
useEffect(() => {
  const socket = useSocket.getState().socket
  socket?.on(SocketEvents.DOWNLOAD_START, handleDownload)
}, [])

// ✅ Good - handles reconnection automatically
useSocketEvent(SocketEvents.DOWNLOAD_START, handleDownload, [handleDownload])

Rule 3: useEffect Cleanup

• Cleanup functions must be synchronous
  • ❌ return async () => { await cleanup() } - Breaks React
  • ✅ return () => { cleanup().catch(console.error) } - Fire-and-forget

Why: React expects cleanup functions to be synchronous. Async cleanup functions are ignored.

Examples:

// ❌ Bad - async cleanup is ignored
useEffect(() => {
  startService()
  return async () => {
    await stopService() // Never runs!
  }
}, [])

// ✅ Good - synchronous cleanup with fire-and-forget async
useEffect(() => {
  startService()
  return () => {
    stopService().catch(console.error)
  }
}, [])

// ✅ Good - synchronous cleanup only
useEffect(() => {
  const interval = setInterval(poll, 1000)
  return () => clearInterval(interval)
}, [])

Rule 4: Test Behavior, Not Implementation

• Test what the code does, not how it does it
  • ❌ Testing that socket.on was called 3 times
  • ✅ Testing that component responds correctly to events

Why: Implementation details change frequently. Behavior tests remain stable and catch real bugs.

Examples:

// ❌ Bad - tests implementation
it('should call socket.on with download event', () => {
  render(<Component />)
  expect(mockSocket.on).toHaveBeenCalledWith(SocketEvents.DOWNLOAD_START, expect.any(Function))
})

// ✅ Good - tests behavior
it('should show download progress when download starts', () => {
  render(<Component />)

  act(() => {
    handlers[SocketEvents.DOWNLOAD_START]({ id: '123', filename: 'model.bin' })
  })

  expect(screen.getByText('Downloading model.bin')).toBeInTheDocument()
})

Verification

Before committing code, verify these rules are followed:

• Run pnpm run type-check - catches any types
• Search for socket.on - should only appear in useSocketEvent hook
• Review useEffect cleanup - must be synchronous
• Review tests - focus on behavior, not implementation

Consequences

Violating these rules leads to:

• Type safety violations → Runtime errors in production
• Socket event loss → Features stop working after reconnect
• Broken cleanup → Memory leaks and stale subscriptions
• Brittle tests → False failures during refactoring