Contributing Guidelines

// ✅ Good: Explicit types
interface Episode {
  id: string
  episodeNumber: number
  title: string
}

function getEpisode(id: string): Promise<Episode> {
  // ...
}

// ❌ Bad: Using 'any'
function getEpisode(id: any): Promise<any> {
  // ...
}

// ✅ Good: Type guards
function isEpisode(data: unknown): data is Episode {
  return typeof data === 'object' && data !== null && 'episodeNumber' in data
}

// ❌ Bad: Unsafe assertion
const episode = data as Episode

// ✅ Good: Typed props with interface
interface EpisodeCardProps {
  episode: Episode
  onClick?: (id: string) => void
}

export function EpisodeCard({ episode, onClick }: EpisodeCardProps) {
  return (
    <div onClick={() => onClick?.(episode.id)}>
      <h3>{episode.title}</h3>
    </div>
  )
}

// ✅ Good: Custom hooks with proper types
function useEpisode(id: string) {
  const [episode, setEpisode] = useState<Episode | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<Error | null>(null)
  
  // ... fetch logic
  
  return { episode, loading, error }
}

src/
├── components/
│   ├── ui/              # Reusable UI components
│   │   ├── Button.tsx
│   │   └── Card.tsx
│   ├── editor/          # TipTap editor components
│   └── layout/          # Layout components
├── routes/              # Page components
│   ├── index.tsx
│   └── episode/
├── services/            # API clients
│   ├── sanity.ts
│   └── kieai.ts
├── hooks/               # Custom React hooks
├── utils/               # Utility functions
└── types/               # TypeScript type definitions

// 1. External dependencies
import { useState, useEffect } from 'react'
import { useQuery } from '@tanstack/react-query'

// 2. Internal modules
import { Button } from '@/components/ui/Button'
import { useEpisode } from '@/hooks/useEpisode'

// 3. Types
import type { Episode } from '@/types'

// 4. Styles
import './styles.css'

// src/utils/formatDate.test.ts
import { describe, it, expect } from 'vitest'
import { formatDate } from './formatDate'

describe('formatDate', () => {
  it('formats date correctly', () => {
    const date = new Date('2024-03-15')
    expect(formatDate(date)).toBe('March 15, 2024')
  })

  it('handles null', () => {
    expect(formatDate(null)).toBe('Invalid date')
  })

  it('handles invalid dates', () => {
    expect(formatDate(new Date('invalid'))).toBe('Invalid date')
  })
})

# Run all tests
npm run test:run

# Type check
npm run typecheck

# Lint
npm run lint

<type>(<scope>): <description>

[optional body]

[optional footer]

# Feature
feat(editor): add table support to TipTap editor

# Bug fix
fix(api): prevent duplicate episode creation

# Documentation
docs(readme): update installation instructions

# Refactoring
refactor(services): simplify Sanity client API

# Test
test(episodes): add tests for episode CRUD operations

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] Type checking passes

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings