logwise 0.3.0

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

logwise is an opinionated logging library for Rust that provides structured, context-aware logging with privacy considerations. Unlike traditional logging crates that use generic levels (error, warn, info, debug, trace), logwise provides specific log levels for defined use cases.

## Key Architecture

### Core Trait System

The [`Logger`](src/logger.rs) trait is the fundamental abstraction for all logging backends:
- Must be `Send + Sync + Debug` for thread safety
- Provides sync (`finish_log_record`) and async (`finish_log_record_async`) methods
- Includes `prepare_to_die()` for graceful shutdown

### Log Levels and Build Configuration

| Level | Use Case | Build Type | Thread Control |
|-------|----------|------------|----------------|
| `trace` | Detailed debugging | debug only | Must enable per-thread via `Context::begin_trace()` |
| `debuginternal` | Print-style debugging | debug only | On by default in current crate, per-thread in downstream |
| `info` | Supporting downstream crates | debug only | On by default |
| `perfwarn` | Performance problems with analysis | all builds | Always on |
| `warning` | Suspicious conditions | all builds | Always on |
| `error` | Logging errors in Results | all builds | Always on |
| `panic` | Programmer errors | all builds | Always on |

### Privacy System

The [`Loggable`](src/privacy.rs) trait enables dual logging representations:
- `log_redacting_private_info()`: Safe for remote servers
- `log_all()`: Full details for private logging

Key privacy wrappers:
- `LogIt<T>`: For complex types requiring explicit privacy handling
- `IPromiseItsNotPrivate<T>`: Explicit marker for non-private data

### Context Management

Thread-local context system in [`src/context.rs`](src/context.rs):
- **Task**: Logical unit of work with automatic lifecycle logging
- **Context**: Hierarchical parent-child structure for nested tasks
- **ApplyContext**: Future wrapper preserving context across async boundaries
- Performance intervals automatically tracked per task

### Procedural Macro Architecture

The `logwise_proc` crate generates logging macros following this pattern:
1. `*_pre()` functions create [`LogRecord`](src/log_record.rs) with metadata
2. `PrivateFormatter` handles structured formatting with privacy
3. `*_post()` functions dispatch to global loggers

Each level has sync (`*_sync!`) and async (`*!`) variants.

## Development Commands

### Build and Test
```bash
# Standard build
cargo build
cargo build --release

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run doc tests
cargo test --doc

# WASM testing (requires wasm-pack)
wasm-pack test --node
```

### Code Quality
```bash
# Type checking
cargo check

# Linting
cargo clippy

# Generate documentation
cargo doc
cargo doc --open
```

## Usage Patterns

### Basic Logging with Privacy
```rust
// Simple logging with structured data
logwise::info_sync!("User logged in", user_id=42);

// Complex types require privacy wrapper
logwise::warn_sync!("Failed operation", 
    details=logwise::privacy::LogIt(&complex_struct));

// Explicit non-private marker
logwise::debuginternal_sync!("Processing {item}", 
    item=IPromiseItsNotPrivate(username));
```

### Context and Task Management
```rust
// Create task with parent context
let ctx = Context::new_task(Some(Context::current()), "data_processing");
ctx.clone().set_current();

// Enable tracing for detailed debugging
Context::begin_trace();

// Async context preservation
let future = ApplyContext::new(ctx, async_operation());
```

### Performance Tracking
```rust
// Automatic interval tracking in current task
logwise::perfwarn!("slow_operation", {
    // Code to measure
    expensive_computation();
});
// Duration logged when task drops
```

## Module Organization

- **Core API**: `src/lib.rs` - Main exports and macro re-exports
- **Logging Implementation**: `src/macros.rs` - Core `*_pre`/`*_post` functions
- **Logger Implementations**:
  - `src/stderror_logger.rs` - Default stderr output
  - `src/global_logger.rs` - Global logger registry
  - `src/local_logger.rs` - Thread-local performance optimization
  - `src/inmemory_logger.rs` - Testing logger
- **Context System**: `src/context.rs` - Task and context management
- **Privacy**: `src/privacy.rs` - Loggable trait and wrappers
- **Performance**: `src/interval.rs` - Interval tracking and statistics

## WASM Support

The library includes WASM-specific implementations:
- Uses `web-time` for time operations
- Console output via `web-sys`
- `PeriodicDrainToConsole` for batched logging
- Thread support via `wasm_thread`

## Testing Considerations

- Tests use `#[cfg(test)]` modules inline with implementation
- `InMemoryLogger` available for test assertions
- Context system requires `Context::reset()` for test isolation
- Performance tests should account for interval collection overhead