a224aced85
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
359 lines
8.4 KiB
Plaintext
359 lines
8.4 KiB
Plaintext
---
|
||
alwaysApply: false
|
||
---
|
||
|
||
# Logging Migration — Patterns and Examples
|
||
|
||
> **Agent role**: Reference this file for specific migration patterns and
|
||
examples when converting console.* calls to logger usage.
|
||
|
||
## Migration — Auto‑Rewrites (Apply Every Time)
|
||
|
||
### Exact Transforms
|
||
|
||
- `console.debug(...)` → `logger.debug(...)`
|
||
|
||
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
|
||
|
||
clearly stateful)
|
||
|
||
- `console.info(...)` → `logger.info(...)`
|
||
|
||
- `console.warn(...)` → `logger.warn(...)`
|
||
|
||
- `console.error(...)` → `logger.error(...)`
|
||
|
||
### Multi-arg Handling
|
||
|
||
- First arg becomes `message` (stringify safely if non-string).
|
||
|
||
- Remaining args map 1:1 to `...args`:
|
||
|
||
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
|
||
|
||
### Sole `Error`
|
||
|
||
- `console.error(err)` → `logger.error(err.message, err)`
|
||
|
||
### Object-wrapping Cleanup
|
||
|
||
Replace `{{ userId, meta }}` wrappers with separate args:
|
||
`logger.info('User signed in', userId, meta)`
|
||
|
||
## Level Guidelines with Examples
|
||
|
||
### DEBUG Examples
|
||
|
||
```typescript
|
||
|
||
logger.debug('[HomeView] reloadFeedOnChange() called');
|
||
logger.debug('[HomeView] Current filter settings',
|
||
settings.filterFeedByVisible,
|
||
settings.filterFeedByNearby,
|
||
settings.searchBoxes?.length ?? 0);
|
||
logger.debug('[FeedFilters] Toggling nearby filter',
|
||
this.isNearby, this.settingChanged, this.activeDid);
|
||
|
||
```
|
||
|
||
**Avoid**: Vague messages (`'Processing data'`).
|
||
|
||
### INFO Examples
|
||
|
||
```typescript
|
||
|
||
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
|
||
logger.info('[StartView] User selected new seed generation');
|
||
logger.info('[SearchAreaView] Search box stored',
|
||
searchBox.name, searchBox.bbox);
|
||
logger.info('[ContactQRScanShowView] Contact registration OK',
|
||
contact.did);
|
||
|
||
```
|
||
|
||
**Avoid**: Diagnostic details that belong in `debug`.
|
||
|
||
### WARN Examples
|
||
|
||
```typescript
|
||
|
||
logger.warn('[ContactQRScanShowView] Invalid scan result – no value',
|
||
resultType);
|
||
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
|
||
logger.warn('[ContactQRScanShowView] JWT missing "own" field');
|
||
|
||
```
|
||
|
||
**Avoid**: Hard failures (those are `error`).
|
||
|
||
### ERROR Examples
|
||
|
||
```typescript
|
||
|
||
logger.error('[HomeView Settings] initializeIdentity() failed', err);
|
||
logger.error('[StartView] Failed to load initialization data', error);
|
||
logger.error('[ContactQRScanShowView] Error processing contact QR',
|
||
error, rawValue);
|
||
|
||
```
|
||
|
||
**Avoid**: Expected user cancels (use `info`/`debug`).
|
||
|
||
## Context Hygiene Examples
|
||
|
||
### Component Context
|
||
|
||
```typescript
|
||
|
||
const log = logger.withContext('UserService');
|
||
log.info('User created', userId);
|
||
log.error('Failed to create user', error);
|
||
|
||
```
|
||
|
||
If not using `withContext`, prefix message with `[ComponentName]`.
|
||
|
||
### Emoji Guidelines
|
||
|
||
Recommended set for visual scanning:
|
||
|
||
- Start/finish: 🚀 / ✅
|
||
|
||
- Retry/loop: 🔄
|
||
|
||
- External call: 📡
|
||
|
||
- Data/metrics: 📊
|
||
|
||
- Inspection: 🔍
|
||
|
||
## Quick Before/After
|
||
|
||
### **Before**
|
||
|
||
```typescript
|
||
|
||
console.log('User signed in', user.id, meta);
|
||
console.error('Failed to update profile', err);
|
||
console.info('Filter toggled', this.hasVisibleDid);
|
||
|
||
```
|
||
|
||
### **After**
|
||
|
||
```typescript
|
||
|
||
import { logger } from '@/utils/logger';
|
||
|
||
logger.info('User signed in', user.id, meta);
|
||
logger.error('Failed to update profile', err);
|
||
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
|
||
|
||
```
|
||
|
||
## Checklist (for every PR)
|
||
|
||
- [ ] No `console.*` (or properly pragma'd in the allowed locations)
|
||
|
||
- [ ] Correct import path for `logger`
|
||
|
||
- [ ] Rest-parameter call shape (`message, ...args`)
|
||
|
||
- [ ] Right level chosen (debug/info/warn/error)
|
||
|
||
- [ ] No secrets / oversized payloads / throwaway context objects
|
||
|
||
- [ ] Component context provided (scoped logger or `[Component]` prefix)
|
||
|
||
**See also**:
|
||
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules.
|
||
|
||
# Logging Migration — Patterns and Examples
|
||
|
||
> **Agent role**: Reference this file for specific migration patterns and
|
||
examples when converting console.* calls to logger usage.
|
||
|
||
## Migration — Auto‑Rewrites (Apply Every Time)
|
||
|
||
### Exact Transforms
|
||
|
||
- `console.debug(...)` → `logger.debug(...)`
|
||
|
||
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
|
||
|
||
clearly stateful)
|
||
|
||
- `console.info(...)` → `logger.info(...)`
|
||
|
||
- `console.warn(...)` → `logger.warn(...)`
|
||
|
||
- `console.error(...)` → `logger.error(...)`
|
||
|
||
### Multi-arg Handling
|
||
|
||
- First arg becomes `message` (stringify safely if non-string).
|
||
|
||
- Remaining args map 1:1 to `...args`:
|
||
|
||
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
|
||
|
||
### Sole `Error`
|
||
|
||
- `console.error(err)` → `logger.error(err.message, err)`
|
||
|
||
### Object-wrapping Cleanup
|
||
|
||
Replace `{{ userId, meta }}` wrappers with separate args:
|
||
`logger.info('User signed in', userId, meta)`
|
||
|
||
## Level Guidelines with Examples
|
||
|
||
### DEBUG Examples
|
||
|
||
```typescript
|
||
|
||
logger.debug('[HomeView] reloadFeedOnChange() called');
|
||
logger.debug('[HomeView] Current filter settings',
|
||
settings.filterFeedByVisible,
|
||
settings.filterFeedByNearby,
|
||
settings.searchBoxes?.length ?? 0);
|
||
logger.debug('[FeedFilters] Toggling nearby filter',
|
||
this.isNearby, this.settingChanged, this.activeDid);
|
||
|
||
```
|
||
|
||
**Avoid**: Vague messages (`'Processing data'`).
|
||
|
||
### INFO Examples
|
||
|
||
```typescript
|
||
|
||
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
|
||
logger.info('[StartView] User selected new seed generation');
|
||
logger.info('[SearchAreaView] Search box stored',
|
||
searchBox.name, searchBox.bbox);
|
||
logger.info('[ContactQRScanShowView] Contact registration OK',
|
||
contact.did);
|
||
|
||
```
|
||
|
||
**Avoid**: Diagnostic details that belong in `debug`.
|
||
|
||
### WARN Examples
|
||
|
||
```typescript
|
||
|
||
logger.warn('[ContactQRScanShowView] Invalid scan result – no value',
|
||
resultType);
|
||
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
|
||
logger.warn('[ContactQRScanShowView] JWT missing "own" field');
|
||
|
||
```
|
||
|
||
**Avoid**: Hard failures (those are `error`).
|
||
|
||
### ERROR Examples
|
||
|
||
```typescript
|
||
|
||
logger.error('[HomeView Settings] initializeIdentity() failed', err);
|
||
logger.error('[StartView] Failed to load initialization data', error);
|
||
logger.error('[ContactQRScanShowView] Error processing contact QR',
|
||
error, rawValue);
|
||
|
||
```
|
||
|
||
**Avoid**: Expected user cancels (use `info`/`debug`).
|
||
|
||
## Context Hygiene Examples
|
||
|
||
### Component Context
|
||
|
||
```typescript
|
||
|
||
const log = logger.withContext('UserService');
|
||
log.info('User created', userId);
|
||
log.error('Failed to create user', error);
|
||
|
||
```
|
||
|
||
If not using `withContext`, prefix message with `[ComponentName]`.
|
||
|
||
### Emoji Guidelines
|
||
|
||
Recommended set for visual scanning:
|
||
|
||
- Start/finish: 🚀 / ✅
|
||
|
||
- Retry/loop: 🔄
|
||
|
||
- External call: 📡
|
||
|
||
- Data/metrics: 📊
|
||
|
||
- Inspection: 🔍
|
||
|
||
## Quick Before/After
|
||
|
||
### **Before**
|
||
|
||
```typescript
|
||
|
||
console.log('User signed in', user.id, meta);
|
||
console.error('Failed to update profile', err);
|
||
console.info('Filter toggled', this.hasVisibleDid);
|
||
|
||
```
|
||
|
||
### **After**
|
||
|
||
```typescript
|
||
|
||
import { logger } from '@/utils/logger';
|
||
|
||
logger.info('User signed in', user.id, meta);
|
||
logger.error('Failed to update profile', err);
|
||
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
|
||
|
||
```
|
||
|
||
## Checklist (for every PR)
|
||
|
||
- [ ] No `console.*` (or properly pragma'd in the allowed locations)
|
||
|
||
- [ ] Correct import path for `logger`
|
||
|
||
- [ ] Rest-parameter call shape (`message, ...args`)
|
||
|
||
- [ ] Right level chosen (debug/info/warn/error)
|
||
|
||
- [ ] No secrets / oversized payloads / throwaway context objects
|
||
|
||
- [ ] Component context provided (scoped logger or `[Component]` prefix)
|
||
|
||
**See also**:
|
||
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules.
|
||
|
||
## Model Implementation Checklist
|
||
|
||
### Before Logging Migration
|
||
|
||
- [ ] **Code Review**: Identify all `console.*` calls in the codebase
|
||
- [ ] **Logger Import**: Verify logger utility is available and accessible
|
||
- [ ] **Context Planning**: Plan component context for each logging call
|
||
- [ ] **Level Assessment**: Determine appropriate log levels for each call
|
||
|
||
### During Logging Migration
|
||
|
||
- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls
|
||
- [ ] **Context Addition**: Add component context using scoped logger or prefix
|
||
- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error)
|
||
- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`)
|
||
|
||
### After Logging Migration
|
||
|
||
- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd)
|
||
- [ ] **Context Validation**: Verify all logging calls have proper context
|
||
- [ ] **Level Review**: Confirm log levels are appropriate for each situation
|
||
- [ ] **Testing**: Test logging functionality across all platforms
|