# Code Review Checklist

Use this checklist when reviewing code for logging best practices and evlog adoption.

## Quick Scan

Run through these checks first to identify improvement opportunities:

### 1. Console Statement Audit

Search for these patterns:

```typescript
// ❌ Patterns to find and transform
console.log(...)
console.error(...)
console.warn(...)
console.info(...)
console.debug(...)
```

**Questions to ask:**

- Are there multiple console statements in one function?
- Are they logging request/response data?
- Could they be consolidated into a wide event?

### 2. Error Pattern Audit

Search for these patterns:

```typescript
// ❌ Generic errors
throw new Error('...')
throw Error('...')

// ❌ Re-throwing without context
catch (error) {
  throw error
}

// ❌ Logging and throwing
catch (error) {
  console.error(error)
  throw error
}
```

**Questions to ask:**

- Does the error message explain what happened?
- Is there a `why` explaining the root cause?
- Is there a `fix` suggesting a solution?
- Is the original error preserved as `cause`?

### 3. Request Handler Audit

For each API route/handler, check:

```typescript
// ❌ Missing request context
export default defineEventHandler(async (event) => {
  // No logging at all, or scattered console.logs
});
```

**Questions to ask:**

- Is there a request-scoped logger?
- Is context accumulated throughout the request?
- Is there a single emit at the end?

## Detailed Review

### Console.log Transformations

#### Single Debug Log

```typescript
// ❌ Before
console.log("Processing user:", userId);

// ✅ After - if part of a larger operation
log.set({ user: { id: userId } });

// ✅ After - if standalone debug
log.debug("user", `Processing user ${userId}`);
```

#### Multiple Related Logs

```typescript
// ❌ Before
console.log("Starting checkout");
console.log("User:", user.id);
console.log("Cart items:", cart.items.length);
console.log("Total:", cart.total);

// ✅ After
log.info({
  action: "checkout",
  user: { id: user.id },
  cart: { items: cart.items.length, total: cart.total },
});
```

#### Request Lifecycle Logs

```typescript
// server/api/process.post.ts

// ❌ Before
export default defineEventHandler(async (event) => {
  console.log("Request started");
  const user = await getUser(event);
  console.log("User loaded");
  const result = await processData(user);
  console.log("Processing complete");
  return result;
});

// ✅ After (Nuxt - auto-imported, no import needed)
// For Nitro v3: import { useLogger } from 'evlog/nitro/v3'
// For Nitro v2: import { useLogger } from 'evlog/nitro'

export default defineEventHandler(async (event) => {
  const log = useLogger(event);

  const user = await getUser(event);
  log.set({ user: { id: user.id } });

  const result = await processData(user);
  log.set({ result: { id: result.id } });

  return result;
  // emit() called automatically
});
```

### Error Transformations

#### Generic Error

```typescript
// ❌ Before
throw new Error("Failed to create user");

// ✅ After
throw createError({
  message: "Failed to create user",
  why: "Email address already registered",
  fix: "Use a different email or log in to existing account",
  link: "https://your-app.com/docs/registration",
});
```

#### Wrapped Error Without Context

```typescript
// ❌ Before
try {
  await externalApi.call();
} catch (error) {
  throw new Error("API call failed");
}

// ✅ After
try {
  await externalApi.call();
} catch (error) {
  throw createError({
    message: "External API call failed",
    why: `API returned: ${error.message}`,
    fix: "Check API credentials and try again",
    link: "https://api-docs.example.com/errors",
    cause: error,
  });
}
```

#### Log-and-Throw Anti-pattern

```typescript
// ❌ Before
try {
  await riskyOperation();
} catch (error) {
  console.error("Operation failed:", error);
  throw error;
}

// ✅ After
try {
  await riskyOperation();
} catch (error) {
  log.error(error, { step: "riskyOperation" });
  throw createError({
    message: "Operation failed",
    why: error.message,
    fix: "Check input and retry",
    cause: error,
  });
}
```

### Request Handler Transformations

#### No Logging

```typescript
// server/api/orders.post.ts

// ❌ Before
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  const result = await processOrder(body);
  return result;
});

// ✅ After (Nuxt - auto-imported, no import needed)
// For Nitro v3: import { useLogger } from 'evlog/nitro/v3'
// For Nitro v2: import { useLogger } from 'evlog/nitro'
import { createError } from "evlog";

export default defineEventHandler(async (event) => {
  const log = useLogger(event);

  const body = await readBody(event);
  log.set({ order: { items: body.items?.length } });

  try {
    const result = await processOrder(body);
    log.set({ result: { orderId: result.id, status: result.status } });
    return result;
  } catch (error) {
    log.error(error, { step: "processOrder" });
    throw createError({
      message: "Order processing failed",
      why: error.message,
      fix: "Check the order data and try again",
    });
  }
  // emit() called automatically
});
```

## Review Checklist Summary

### Logging

- [ ] No raw `console.log` statements in production code
- [ ] Request handlers use `useLogger(event)` (Nuxt/Nitro) or `createRequestLogger()` (standalone)
- [ ] Context is accumulated with `log.set()` throughout the request
- [ ] `emit()` is automatic with `useLogger()`, manual with `createRequestLogger()`
- [ ] Wide events include: user, business context, outcome

### Errors

- [ ] All errors use `createError()` instead of `new Error()` (import from `evlog`)
- [ ] Every error has a clear `message` and appropriate `status` code
- [ ] Complex errors include `why` explaining root cause
- [ ] Fixable errors include `fix` with actionable steps
- [ ] Documented errors include `link` to docs
- [ ] Wrapped errors preserve `cause`
- [ ] Support-only or sensitive diagnostics use `internal`, not `message` / `why` / `fix`

### Frontend Error Handling

- [ ] API errors are caught and displayed with full context (message, why, fix)
- [ ] Toasts or error components use the structured data from `error.data.data`
- [ ] Links to documentation are actionable (buttons/links in toasts)

### Context

- [ ] User context includes: id, plan/subscription, relevant business data
- [ ] Request context includes: method, path, requestId
- [ ] Business context is domain-specific and useful for debugging
- [ ] No sensitive data in logs (passwords, tokens, full card numbers)

## Anti-Pattern Summary

| Anti-Pattern                           | Fix                                                                         |
| -------------------------------------- | --------------------------------------------------------------------------- |
| Multiple `console.log` in one function | Single wide event with `useLogger(event).set()`                             |
| `throw new Error('...')`               | `throw createError({ message, status, why, fix })`                          |
| `console.error(e); throw e`            | `log.error(e); throw createError(...)`                                      |
| No logging in request handlers         | Add `useLogger(event)` (Nuxt/Nitro) or `createRequestLogger()` (standalone) |
| Flat log data                          | Grouped objects: `{ user: {...}, cart: {...} }`                             |
| Abbreviated field names                | Descriptive names: `userId` not `uid`                                       |

## Suggested Review Comments

Use these when leaving review feedback:

### Console.log Found

> Consider using evlog's wide event pattern here. Instead of multiple console.log statements, use `useLogger(event)` to accumulate context and emit a single comprehensive event.

### Generic Error

> This error would benefit from evlog's structured error pattern. Consider using `import { createError } from 'evlog'` and `createError({ message, status, why, fix })` to provide more debugging context.

### Missing Request Context

> This handler would benefit from request-scoped logging. Add `useLogger(event)` at the start to capture context throughout the request lifecycle.

### Good Logging (Positive Feedback)

> Nice use of wide events here! The context is well-structured and will be very useful for debugging.