Coding Guidelines

# Format all files
yarn lint:fix

# Format specific files
yarn prettier --write path/to/file.ts

# Run linter
yarn lint

# Auto-fix issues
yarn lint:eslint:fix

// Good
function greet(name: string): string {
  return `Hello, ${name}`;
}

interface User {
  id: string;
  name: string;
  email: string;
}

// Bad
function greet(name) {
  return `Hello, ${name}`;
}

const user: any = { id: '123' };

// Good: Type is inferred
const name = 'John';
const age = 30;
const user = { name, age };

// Bad: Unnecessary annotation
const name: string = 'John';
const age: number = 30;

// Good
function getUserName(user: User | null): string {
  return user?.name ?? 'Anonymous';
}

// Bad
function getUserName(user: User): string {
  return user.name; // May crash if user is null
}

// Good
function getById<T>(items: T[], id: string): T | undefined {
  return items.find(item => item.id === id);
}

// Bad
function getById(items: any[], id: string): any {
  return items.find(item => item.id === id);
}

import { type ReactNode } from 'react';

interface ButtonProps {
  children: ReactNode;
  onClick?: () => void;
  disabled?: boolean;
  variant?: 'primary' | 'secondary';
}

export function Button({
  children,
  onClick,
  disabled = false,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={variant}
    >
      {children}
    </button>
  );
}

// Good
function useWorkspace(id: string) {
  const [workspace, setWorkspace] = useState<Workspace | null>(null);
  
  useEffect(() => {
    fetchWorkspace(id).then(setWorkspace);
  }, [id]);
  
  return workspace;
}

// Bad: Conditional hooks
function useWorkspace(id: string | null) {
  if (!id) return null; // Don't call hooks conditionally
  const [workspace, setWorkspace] = useState<Workspace | null>(null);
  return workspace;
}

import { atom, useAtom } from 'jotai';

const userAtom = atom<User | null>(null);

export function useUser() {
  return useAtom(userAtom);
}

// Usage
function Profile() {
  const [user, setUser] = useUser();
  return <div>{user?.name}</div>;
}

// camelCase for variables and functions
const userName = 'John';
function getUserById(id: string) {}

// PascalCase for classes and components
class UserService {}
function UserProfile() {}

// SCREAMING_SNAKE_CASE for constants
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';

// kebab-case for files and folders
user-service.ts
workspace-list.tsx
api/auth/login.ts

// PascalCase for component files
UserProfile.tsx
WorkspaceList.tsx

// Good
const isLoading = true;
const hasPermission = false;
const canEdit = true;

// Bad
const loading = true;
const permission = false;
const edit = true;

// Good: Explain WHY, not WHAT
function calculateScore(attempts: number): number {
  // Penalize excessive retries to prevent brute force
  return Math.max(0, 100 - attempts * 10);
}

// Bad: Comment explains obvious code
function add(a: number, b: number): number {
  // Add a and b
  return a + b;
}

/**
 * Fetches a workspace by ID.
 * 
 * @param id - The workspace ID
 * @returns The workspace object, or null if not found
 * @throws {NetworkError} If the request fails
 * 
 * @example
 * const workspace = await fetchWorkspace('abc123');
 */
export async function fetchWorkspace(id: string): Promise<Workspace | null> {
  // Implementation
}

// Good
function divide(a: number, b: number): number {
  if (b === 0) {
    throw new Error('Division by zero is not allowed');
  }
  return a / b;
}

// Bad
function divide(a: number, b: number): number {
  return a / b; // May return Infinity or NaN
}

// Good
async function saveWorkspace(data: Workspace) {
  try {
    await api.save(data);
  } catch (error) {
    if (error instanceof NetworkError) {
      toast.error('Network error. Please try again.');
    } else {
      toast.error('Failed to save workspace.');
      logger.error('Save failed', error);
    }
  }
}

// Bad
async function saveWorkspace(data: Workspace) {
  await api.save(data); // Errors crash the app
}

import { memo, useCallback, useMemo } from 'react';

// Memoize expensive components
export const WorkspaceList = memo(function WorkspaceList({ workspaces }: Props) {
  return <div>{/* ... */}</div>;
});

// Memoize callbacks
function Parent() {
  const handleClick = useCallback(() => {
    console.log('clicked');
  }, []);
  
  return <Child onClick={handleClick} />;
}

// Memoize expensive computations
function Stats({ data }: Props) {
  const stats = useMemo(() => {
    return calculateStats(data); // Heavy computation
  }, [data]);
  
  return <div>{stats}</div>;
}

import { lazy, Suspense } from 'react';

const Settings = lazy(() => import('./Settings'));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Settings />
    </Suspense>
  );
}

import DOMPurify from 'dompurify';

// Good: Sanitize HTML
function RenderHTML({ html }: Props) {
  const clean = DOMPurify.sanitize(html);
  return <div dangerouslySetInnerHTML={{ __html: clean }} />;
}

// Bad: XSS vulnerability
function RenderHTML({ html }: Props) {
  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

import { z } from 'zod';

const userSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().min(0).max(150)
});

function createUser(data: unknown) {
  const validated = userSchema.parse(data);
  // Safe to use validated data
}

// Good: Don't log sensitive data
logger.info('User logged in', { userId: user.id });

// Bad: Logs password
logger.info('User logged in', { user });

feat: add workspace sharing
fix: resolve sync conflict
docs: update API documentation
style: format code with prettier
refactor: simplify auth logic
test: add workspace tests
chore: update dependencies

feat/workspace-sharing
fix/sync-conflict
docs/api-documentation
refactor/auth-logic

## Description
Adds workspace sharing functionality allowing users to invite collaborators.

## Changes
- Added share dialog component
- Implemented invite API endpoint
- Added permission checks

## Testing
- [x] Unit tests added
- [x] E2E tests added
- [x] Manually tested

Fixes #123

/**
 * Service for managing workspaces.
 * 
 * Handles workspace creation, updates, deletion,
 * and permission management.
 */
export class WorkspaceService {
  /**
   * Creates a new workspace.
   * 
   * @param name - The workspace name
   * @param ownerId - The owner's user ID
   * @returns The created workspace
   */
  async createWorkspace(name: string, ownerId: string): Promise<Workspace> {
    // Implementation
  }
}

# Package Name

Brief description of the package.

## Installation

How to install and use the package.

## Usage

Code examples showing common use cases.

## API

List of main exports and their purpose.