eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
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
|