forked from jsnbuchanan/crowd-funder-for-time-pwa
refactor(cursor-rules): restructure rules architecture with meta-rule system
- 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
This commit is contained in:
Matthew Raymer
358
.cursor/rules/development/logging_migration.mdc
Normal file
358
.cursor/rules/development/logging_migration.mdc
Normal file
@@ -0,0 +1,358 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user