forked from jsnbuchanan/crowd-funder-for-time-pwa
Add comprehensive migration documentation and testing infrastructure
- Add TODO annotation to MembersList.vue requiring human testing validation - Create migration templates for systematic component migration - Add best practices guide for PlatformServiceMixin usage - Create ESLint rules template for pattern enforcement - Add validation script to track migration progress - Document Phase 1 completion summary with current state Migration Infrastructure: - Component migration checklist template - Automated validation script (validate-migration.sh) - Best practices documentation - ESLint rules for preventing regression Status: MembersList.vue migration complete but requires human testing Next: Select next component for migration when ready to continue
This commit is contained in:
Matthew Raymer
436
docs/migration-templates/best-practices.md
Normal file
436
docs/migration-templates/best-practices.md
Normal file
@@ -0,0 +1,436 @@
|
||||
# PlatformServiceMixin Best Practices Guide
|
||||
|
||||
## Overview
|
||||
This guide establishes best practices for using PlatformServiceMixin in TimeSafari components to ensure consistent, maintainable, and secure code.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. **Single Source of Truth**
|
||||
- Always use PlatformServiceMixin for database operations
|
||||
- Never mix legacy patterns with mixin patterns in the same component
|
||||
- Use mixin caching to avoid redundant database queries
|
||||
|
||||
### 2. **Component Context Awareness**
|
||||
- Always include component name in error logging
|
||||
- Use `this.$options.name` for consistent component identification
|
||||
- Implement proper error boundaries with context
|
||||
|
||||
### 3. **Progressive Enhancement**
|
||||
- Start with basic mixin methods (`$db`, `$exec`, `$one`)
|
||||
- Use specialized methods when available (`$getAllContacts`, `$settings`)
|
||||
- Leverage caching for frequently accessed data
|
||||
|
||||
## Implementation Patterns
|
||||
|
||||
### Database Operations
|
||||
|
||||
#### ✅ **Preferred Pattern: Use Specialized Methods**
|
||||
```typescript
|
||||
// Best: Use high-level specialized methods
|
||||
const contacts = await this.$getAllContacts();
|
||||
const settings = await this.$settings();
|
||||
const userSettings = await this.$accountSettings(did);
|
||||
```
|
||||
|
||||
#### ✅ **Good Pattern: Use Mapped Query Methods**
|
||||
```typescript
|
||||
// Good: Use query methods with automatic mapping
|
||||
const results = await this.$query<Contact>(
|
||||
"SELECT * FROM contacts WHERE registered = ?",
|
||||
[true]
|
||||
);
|
||||
```
|
||||
|
||||
#### ⚠️ **Acceptable Pattern: Use Raw Database Methods**
|
||||
```typescript
|
||||
// Acceptable: Use raw methods when specialized methods don't exist
|
||||
const result = await this.$db("SELECT COUNT(*) as count FROM logs");
|
||||
const count = result?.values?.[0]?.[0] || 0;
|
||||
```
|
||||
|
||||
#### ❌ **Anti-Pattern: Direct Platform Service**
|
||||
```typescript
|
||||
// Anti-pattern: Avoid direct PlatformService usage
|
||||
const platformService = PlatformServiceFactory.getInstance();
|
||||
const result = await platformService.dbQuery(sql, params);
|
||||
```
|
||||
|
||||
### Settings Management
|
||||
|
||||
#### ✅ **Best Practice: Use Mixin Methods**
|
||||
```typescript
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
|
||||
async loadSettings() {
|
||||
// ✅ Use cached settings retrieval
|
||||
const settings = await this.$settings();
|
||||
return settings;
|
||||
}
|
||||
|
||||
async saveUserPreferences(changes: Partial<Settings>) {
|
||||
// ✅ Use specialized save method
|
||||
await this.$saveSettings(changes);
|
||||
await this.$log("User preferences saved");
|
||||
}
|
||||
|
||||
async loadAccountSettings(did: string) {
|
||||
// ✅ Use account-specific settings
|
||||
const accountSettings = await this.$accountSettings(did);
|
||||
return accountSettings;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ❌ **Anti-Pattern: Legacy Settings Access**
|
||||
```typescript
|
||||
// Anti-pattern: Avoid legacy databaseUtil methods
|
||||
import * as databaseUtil from "../db/databaseUtil";
|
||||
|
||||
async loadSettings() {
|
||||
const settings = await databaseUtil.retrieveSettingsForActiveAccount();
|
||||
return settings;
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
#### ✅ **Best Practice: Component-Aware Error Handling**
|
||||
```typescript
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
|
||||
async performOperation() {
|
||||
try {
|
||||
const result = await this.$getAllContacts();
|
||||
await this.$log("Operation completed successfully");
|
||||
return result;
|
||||
} catch (error) {
|
||||
// ✅ Include component context in error logging
|
||||
await this.$logError(`[${this.$options.name}] Operation failed: ${error}`);
|
||||
|
||||
// ✅ Provide user-friendly error handling
|
||||
this.$notify({
|
||||
group: "alert",
|
||||
type: "danger",
|
||||
title: "Operation Failed",
|
||||
text: "Unable to load contacts. Please try again.",
|
||||
});
|
||||
|
||||
throw error; // Re-throw for upstream handling
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ❌ **Anti-Pattern: Generic Error Handling**
|
||||
```typescript
|
||||
// Anti-pattern: Generic error handling without context
|
||||
try {
|
||||
// operation
|
||||
} catch (error) {
|
||||
console.error("Error:", error);
|
||||
throw error;
|
||||
}
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
#### ✅ **Best Practice: Structured Logging**
|
||||
```typescript
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
|
||||
async performDatabaseOperation() {
|
||||
// ✅ Log operation start with context
|
||||
await this.$log(`[${this.$options.name}] Starting database operation`);
|
||||
|
||||
try {
|
||||
const result = await this.$getAllContacts();
|
||||
|
||||
// ✅ Log successful completion
|
||||
await this.$log(`[${this.$options.name}] Database operation completed, found ${result.length} contacts`);
|
||||
|
||||
return result;
|
||||
} catch (error) {
|
||||
// ✅ Log errors with full context
|
||||
await this.$logError(`[${this.$options.name}] Database operation failed: ${error}`);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ Use appropriate log levels
|
||||
async validateInput(input: string) {
|
||||
if (!input) {
|
||||
await this.$log(`[${this.$options.name}] Input validation failed: empty input`, 'warn');
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Caching Strategies
|
||||
|
||||
#### ✅ **Best Practice: Smart Caching Usage**
|
||||
```typescript
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
|
||||
async loadContactsWithCaching() {
|
||||
// ✅ Use cached contacts (automatically managed by mixin)
|
||||
const contacts = await this.$contacts();
|
||||
|
||||
// ✅ Force refresh when needed
|
||||
if (this.needsFreshData) {
|
||||
const freshContacts = await this.$refreshContacts();
|
||||
return freshContacts;
|
||||
}
|
||||
|
||||
return contacts;
|
||||
}
|
||||
|
||||
async updateContactAndRefresh(did: string, changes: Partial<Contact>) {
|
||||
// ✅ Update contact and invalidate cache
|
||||
await this.$updateContact(did, changes);
|
||||
|
||||
// ✅ Clear cache to ensure fresh data on next access
|
||||
this.$clearAllCaches();
|
||||
|
||||
await this.$log(`[${this.$options.name}] Contact updated and cache cleared`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Input Validation
|
||||
|
||||
#### ✅ **Always Validate Database Inputs**
|
||||
```typescript
|
||||
async saveContact(contact: Partial<Contact>) {
|
||||
// ✅ Validate required fields
|
||||
if (!contact.did || !contact.name) {
|
||||
await this.$logError(`[${this.$options.name}] Invalid contact data: missing required fields`);
|
||||
throw new Error('Contact must have DID and name');
|
||||
}
|
||||
|
||||
// ✅ Sanitize inputs
|
||||
const sanitizedContact = {
|
||||
...contact,
|
||||
name: contact.name.trim(),
|
||||
// Remove any potential XSS vectors
|
||||
notes: contact.notes?.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
|
||||
};
|
||||
|
||||
return await this.$insertContact(sanitizedContact);
|
||||
}
|
||||
```
|
||||
|
||||
### Error Information Disclosure
|
||||
|
||||
#### ✅ **Safe Error Handling**
|
||||
```typescript
|
||||
async performSensitiveOperation(did: string) {
|
||||
try {
|
||||
// Sensitive operation
|
||||
const result = await this.$accountSettings(did);
|
||||
return result;
|
||||
} catch (error) {
|
||||
// ✅ Log full error for debugging
|
||||
await this.$logError(`[${this.$options.name}] Sensitive operation failed: ${error}`);
|
||||
|
||||
// ✅ Return generic error to user
|
||||
throw new Error('Unable to complete operation. Please try again.');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SQL Injection Prevention
|
||||
|
||||
#### ✅ **Always Use Parameterized Queries**
|
||||
```typescript
|
||||
// ✅ Safe: Parameterized query
|
||||
async findContactsByName(searchTerm: string) {
|
||||
return await this.$query<Contact>(
|
||||
"SELECT * FROM contacts WHERE name LIKE ?",
|
||||
[`%${searchTerm}%`]
|
||||
);
|
||||
}
|
||||
|
||||
// ❌ Dangerous: String concatenation
|
||||
async findContactsByNameUnsafe(searchTerm: string) {
|
||||
return await this.$query<Contact>(
|
||||
`SELECT * FROM contacts WHERE name LIKE '%${searchTerm}%'`
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Database Query Optimization
|
||||
|
||||
#### ✅ **Efficient Query Patterns**
|
||||
```typescript
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
|
||||
async loadOptimizedData() {
|
||||
// ✅ Use transactions for multiple operations
|
||||
return await this.$withTransaction(async () => {
|
||||
const contacts = await this.$getAllContacts();
|
||||
const settings = await this.$settings();
|
||||
return { contacts, settings };
|
||||
});
|
||||
}
|
||||
|
||||
async loadDataWithPagination(offset: number, limit: number) {
|
||||
// ✅ Use LIMIT and OFFSET for large datasets
|
||||
return await this.$query<Contact>(
|
||||
"SELECT * FROM contacts ORDER BY name LIMIT ? OFFSET ?",
|
||||
[limit, offset]
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Management
|
||||
|
||||
#### ✅ **Proper Cache Management**
|
||||
```typescript
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
|
||||
beforeDestroy() {
|
||||
// ✅ Clear component caches on destroy
|
||||
this.$clearAllCaches();
|
||||
}
|
||||
|
||||
async handleLargeDataset() {
|
||||
try {
|
||||
// Process large dataset
|
||||
const largeResult = await this.$query("SELECT * FROM large_table");
|
||||
|
||||
// ✅ Process in chunks to avoid memory issues
|
||||
const chunkSize = 100;
|
||||
for (let i = 0; i < largeResult.length; i += chunkSize) {
|
||||
const chunk = largeResult.slice(i, i + chunkSize);
|
||||
await this.processChunk(chunk);
|
||||
}
|
||||
} finally {
|
||||
// ✅ Clear caches after processing large datasets
|
||||
this.$clearAllCaches();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Strategies
|
||||
|
||||
### Unit Testing
|
||||
|
||||
#### ✅ **Mock Mixin Methods**
|
||||
```typescript
|
||||
// test/MyComponent.spec.ts
|
||||
import { mount } from '@vue/test-utils';
|
||||
import MyComponent from '@/components/MyComponent.vue';
|
||||
import { PlatformServiceMixin } from '@/utils/PlatformServiceMixin';
|
||||
|
||||
describe('MyComponent', () => {
|
||||
let wrapper;
|
||||
|
||||
beforeEach(() => {
|
||||
// ✅ Mock mixin methods
|
||||
const mockMixin = {
|
||||
...PlatformServiceMixin,
|
||||
methods: {
|
||||
...PlatformServiceMixin.methods,
|
||||
$getAllContacts: jest.fn().mockResolvedValue([]),
|
||||
$settings: jest.fn().mockResolvedValue({}),
|
||||
$log: jest.fn().mockResolvedValue(undefined),
|
||||
$logError: jest.fn().mockResolvedValue(undefined),
|
||||
}
|
||||
};
|
||||
|
||||
wrapper = mount(MyComponent, {
|
||||
mixins: [mockMixin]
|
||||
});
|
||||
});
|
||||
|
||||
it('should load contacts on mount', async () => {
|
||||
await wrapper.vm.loadContacts();
|
||||
expect(wrapper.vm.$getAllContacts).toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
#### ✅ **Test Real Database Operations**
|
||||
```typescript
|
||||
// test/integration/ContactsView.spec.ts
|
||||
import { createLocalVue, mount } from '@vue/test-utils';
|
||||
import ContactsView from '@/views/ContactsView.vue';
|
||||
import { PlatformServiceMixin } from '@/utils/PlatformServiceMixin';
|
||||
|
||||
describe('ContactsView Integration', () => {
|
||||
it('should perform real database operations', async () => {
|
||||
const wrapper = mount(ContactsView, {
|
||||
mixins: [PlatformServiceMixin]
|
||||
});
|
||||
|
||||
// ✅ Test real mixin functionality
|
||||
const contacts = await wrapper.vm.$getAllContacts();
|
||||
expect(Array.isArray(contacts)).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
When migrating components to PlatformServiceMixin:
|
||||
|
||||
### Pre-Migration
|
||||
- [ ] Identify all database operations in the component
|
||||
- [ ] List all logging operations
|
||||
- [ ] Check for error handling patterns
|
||||
- [ ] Note any specialized database queries
|
||||
|
||||
### During Migration
|
||||
- [ ] Add PlatformServiceMixin to mixins array
|
||||
- [ ] Replace all database operations with mixin methods
|
||||
- [ ] Update logging to use mixin logging methods
|
||||
- [ ] Add component context to error messages
|
||||
- [ ] Replace settings operations with mixin methods
|
||||
- [ ] Update error handling to use structured patterns
|
||||
|
||||
### Post-Migration
|
||||
- [ ] Remove all legacy imports (databaseUtil, logConsoleAndDb)
|
||||
- [ ] Test all component functionality
|
||||
- [ ] Verify TypeScript compilation
|
||||
- [ ] Check for any remaining anti-patterns
|
||||
- [ ] Update component tests if needed
|
||||
- [ ] Run migration validation script
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
### Issue: TypeScript errors after migration
|
||||
**Solution**: Ensure proper type definitions and mixin interface implementation
|
||||
|
||||
### Issue: Methods not available on `this`
|
||||
**Solution**: Verify PlatformServiceMixin is properly included in mixins array
|
||||
|
||||
### Issue: Caching not working as expected
|
||||
**Solution**: Check cache TTL settings and clear cache when needed
|
||||
|
||||
### Issue: Database operations failing
|
||||
**Solution**: Verify PlatformService is properly initialized and check error logs
|
||||
|
||||
### Issue: Performance degradation
|
||||
**Solution**: Review query efficiency and cache usage patterns
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** - Initial best practices documentation
|
||||
- **v1.1** - Added security and performance sections
|
||||
- **v1.2** - Enhanced testing strategies and troubleshooting
|
||||
216
docs/migration-templates/component-migration.md
Normal file
216
docs/migration-templates/component-migration.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Component Migration Template
|
||||
|
||||
## Overview
|
||||
This template provides step-by-step instructions for migrating Vue components from legacy patterns to PlatformServiceMixin.
|
||||
|
||||
## Before Migration Checklist
|
||||
|
||||
- [ ] Component uses `import * as databaseUtil`
|
||||
- [ ] Component uses `import { logConsoleAndDb }`
|
||||
- [ ] Component has direct `PlatformServiceFactory.getInstance()` calls
|
||||
- [ ] Component has manual error handling for database operations
|
||||
- [ ] Component has verbose SQL result processing
|
||||
|
||||
## Step-by-Step Migration
|
||||
|
||||
### Step 1: Update Imports
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE - Legacy imports
|
||||
import * as databaseUtil from "../db/databaseUtil";
|
||||
import { logConsoleAndDb } from "../db/databaseUtil";
|
||||
import { PlatformServiceFactory } from "../services/PlatformServiceFactory";
|
||||
|
||||
// ✅ AFTER - Clean imports
|
||||
import { PlatformServiceMixin } from "@/utils/PlatformServiceMixin";
|
||||
import { Contact } from "@/db/tables/contacts";
|
||||
import { Settings } from "@/db/tables/settings";
|
||||
```
|
||||
|
||||
### Step 2: Add Mixin to Component
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE - No mixin
|
||||
@Component({
|
||||
components: { /* ... */ }
|
||||
})
|
||||
export default class MyComponent extends Vue {
|
||||
// ...
|
||||
}
|
||||
|
||||
// ✅ AFTER - With mixin
|
||||
@Component({
|
||||
components: { /* ... */ }
|
||||
})
|
||||
export default class MyComponent extends Vue {
|
||||
mixins: [PlatformServiceMixin],
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Replace Database Operations
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE - Legacy database access
|
||||
async loadContacts() {
|
||||
try {
|
||||
const platformService = PlatformServiceFactory.getInstance();
|
||||
const result = await platformService.dbQuery("SELECT * FROM contacts");
|
||||
const contacts = databaseUtil.mapQueryResultToValues(result);
|
||||
await logConsoleAndDb("Contacts loaded successfully");
|
||||
return contacts;
|
||||
} catch (error) {
|
||||
await logConsoleAndDb("Error loading contacts: " + error, true);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ AFTER - Mixin methods
|
||||
async loadContacts() {
|
||||
try {
|
||||
const contacts = await this.$getAllContacts();
|
||||
await this.$log("Contacts loaded successfully");
|
||||
return contacts;
|
||||
} catch (error) {
|
||||
await this.$logError(`[${this.$options.name}] Error loading contacts: ${error}`);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Replace Settings Operations
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE - Legacy settings access
|
||||
async loadSettings() {
|
||||
const settingsRow = await databaseUtil.retrieveSettingsForActiveAccount();
|
||||
const settings = settingsRow || {};
|
||||
return settings;
|
||||
}
|
||||
|
||||
async saveSettings(changes: Partial<Settings>) {
|
||||
await databaseUtil.updateDefaultSettings(changes);
|
||||
await logConsoleAndDb("Settings saved");
|
||||
}
|
||||
|
||||
// ✅ AFTER - Mixin methods
|
||||
async loadSettings() {
|
||||
return await this.$settings();
|
||||
}
|
||||
|
||||
async saveSettings(changes: Partial<Settings>) {
|
||||
await this.$saveSettings(changes);
|
||||
await this.$log("Settings saved");
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Replace Logging Operations
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE - Legacy logging
|
||||
try {
|
||||
// operation
|
||||
} catch (error) {
|
||||
console.error("Error occurred:", error);
|
||||
await logConsoleAndDb("Error: " + error, true);
|
||||
}
|
||||
|
||||
// ✅ AFTER - Mixin logging
|
||||
try {
|
||||
// operation
|
||||
} catch (error) {
|
||||
await this.$logError(`[${this.$options.name}] Error: ${error}`);
|
||||
}
|
||||
```
|
||||
|
||||
## Common Migration Patterns
|
||||
|
||||
### Pattern 1: Database Query + Result Processing
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE
|
||||
const platformService = PlatformServiceFactory.getInstance();
|
||||
const result = await platformService.dbQuery(sql, params);
|
||||
const processed = databaseUtil.mapQueryResultToValues(result);
|
||||
|
||||
// ✅ AFTER
|
||||
const processed = await this.$query(sql, params);
|
||||
```
|
||||
|
||||
### Pattern 2: Settings Retrieval
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE
|
||||
const settingsRow = await databaseUtil.retrieveSettingsForActiveAccount();
|
||||
const value = settingsRow?.[field] || defaultValue;
|
||||
|
||||
// ✅ AFTER
|
||||
const settings = await this.$settings();
|
||||
const value = settings[field] || defaultValue;
|
||||
```
|
||||
|
||||
### Pattern 3: Contact Operations
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE
|
||||
const platformService = PlatformServiceFactory.getInstance();
|
||||
const contacts = await platformService.dbQuery("SELECT * FROM contacts");
|
||||
const mappedContacts = databaseUtil.mapQueryResultToValues(contacts);
|
||||
|
||||
// ✅ AFTER
|
||||
const contacts = await this.$getAllContacts();
|
||||
```
|
||||
|
||||
### Pattern 4: Error Handling
|
||||
|
||||
```typescript
|
||||
// ❌ BEFORE
|
||||
try {
|
||||
// operation
|
||||
} catch (error) {
|
||||
console.error("[MyComponent] Error:", error);
|
||||
await databaseUtil.logToDb("Error: " + error, "error");
|
||||
}
|
||||
|
||||
// ✅ AFTER
|
||||
try {
|
||||
// operation
|
||||
} catch (error) {
|
||||
await this.$logError(`[${this.$options.name}] Error: ${error}`);
|
||||
}
|
||||
```
|
||||
|
||||
## After Migration Checklist
|
||||
|
||||
- [ ] All `databaseUtil` imports removed
|
||||
- [ ] All `logConsoleAndDb` imports removed
|
||||
- [ ] All direct `PlatformServiceFactory.getInstance()` calls removed
|
||||
- [ ] Component includes `PlatformServiceMixin` in mixins array
|
||||
- [ ] Database operations use mixin methods (`$db`, `$query`, `$getAllContacts`, etc.)
|
||||
- [ ] Settings operations use mixin methods (`$settings`, `$saveSettings`)
|
||||
- [ ] Logging uses mixin methods (`$log`, `$logError`, `$logAndConsole`)
|
||||
- [ ] Error handling includes component name context
|
||||
- [ ] Component compiles without TypeScript errors
|
||||
- [ ] Component functionality works as expected
|
||||
|
||||
## Testing Migration
|
||||
|
||||
1. **Compile Check**: `npm run build` should complete without errors
|
||||
2. **Runtime Check**: Component should load and function normally
|
||||
3. **Logging Check**: Verify logs appear in console and database
|
||||
4. **Error Handling Check**: Verify errors are properly logged and handled
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Missing Mixin Methods**: Ensure component properly extends PlatformServiceMixin
|
||||
2. **TypeScript Errors**: Check that all types are properly imported
|
||||
3. **Runtime Errors**: Verify all async operations are properly awaited
|
||||
4. **Missing Context**: Add component name to error messages for better debugging
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
- Mixin methods include caching for frequently accessed data
|
||||
- Database operations are queued and optimized
|
||||
- Error logging includes proper context and formatting
|
||||
307
docs/migration-templates/eslint-rules.md
Normal file
307
docs/migration-templates/eslint-rules.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# ESLint Rules for PlatformServiceMixin Migration
|
||||
|
||||
## Overview
|
||||
Custom ESLint rules to enforce PlatformServiceMixin patterns and prevent regression to legacy patterns.
|
||||
|
||||
## Rules Configuration
|
||||
|
||||
Add to `.eslintrc.js`:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
// ... existing config
|
||||
rules: {
|
||||
// ... existing rules
|
||||
|
||||
// Custom rules for PlatformServiceMixin migration
|
||||
'timesafari/no-direct-database-util': 'error',
|
||||
'timesafari/no-legacy-logging': 'error',
|
||||
'timesafari/require-mixin-for-database': 'error',
|
||||
'timesafari/no-direct-platform-service': 'warn',
|
||||
'timesafari/prefer-mixin-methods': 'warn',
|
||||
},
|
||||
|
||||
// Custom rules plugin
|
||||
plugins: ['timesafari'],
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Rules Implementation
|
||||
|
||||
Create `eslint-plugin-timesafari/index.js`:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
rules: {
|
||||
'no-direct-database-util': {
|
||||
meta: {
|
||||
type: 'problem',
|
||||
docs: {
|
||||
description: 'Disallow direct imports from databaseUtil',
|
||||
category: 'Migration',
|
||||
recommended: true,
|
||||
},
|
||||
schema: [],
|
||||
},
|
||||
create(context) {
|
||||
return {
|
||||
ImportDeclaration(node) {
|
||||
if (node.source.value.includes('databaseUtil')) {
|
||||
context.report({
|
||||
node,
|
||||
message: 'Direct databaseUtil imports are deprecated. Use PlatformServiceMixin instead.',
|
||||
});
|
||||
}
|
||||
},
|
||||
};
|
||||
},
|
||||
},
|
||||
|
||||
'no-legacy-logging': {
|
||||
meta: {
|
||||
type: 'problem',
|
||||
docs: {
|
||||
description: 'Disallow legacy logging methods',
|
||||
category: 'Migration',
|
||||
recommended: true,
|
||||
},
|
||||
schema: [],
|
||||
},
|
||||
create(context) {
|
||||
return {
|
||||
ImportDeclaration(node) {
|
||||
if (node.specifiers.some(spec => spec.imported?.name === 'logConsoleAndDb')) {
|
||||
context.report({
|
||||
node,
|
||||
message: 'logConsoleAndDb is deprecated. Use PlatformServiceMixin $log methods instead.',
|
||||
});
|
||||
}
|
||||
},
|
||||
CallExpression(node) {
|
||||
if (node.callee.name === 'logConsoleAndDb') {
|
||||
context.report({
|
||||
node,
|
||||
message: 'logConsoleAndDb is deprecated. Use this.$logAndConsole() instead.',
|
||||
});
|
||||
}
|
||||
},
|
||||
};
|
||||
},
|
||||
},
|
||||
|
||||
'require-mixin-for-database': {
|
||||
meta: {
|
||||
type: 'suggestion',
|
||||
docs: {
|
||||
description: 'Require PlatformServiceMixin for components using database operations',
|
||||
category: 'Migration',
|
||||
recommended: true,
|
||||
},
|
||||
schema: [],
|
||||
},
|
||||
create(context) {
|
||||
let hasDbOperations = false;
|
||||
let hasMixin = false;
|
||||
|
||||
return {
|
||||
CallExpression(node) {
|
||||
// Check for database operations
|
||||
if (node.callee.property &&
|
||||
['dbQuery', 'dbExec', 'dbGetOneRow'].includes(node.callee.property.name)) {
|
||||
hasDbOperations = true;
|
||||
}
|
||||
},
|
||||
Property(node) {
|
||||
// Check for mixin usage
|
||||
if (node.key.name === 'mixins' &&
|
||||
node.value.elements?.some(el => el.name === 'PlatformServiceMixin')) {
|
||||
hasMixin = true;
|
||||
}
|
||||
},
|
||||
'Program:exit'() {
|
||||
if (hasDbOperations && !hasMixin) {
|
||||
context.report({
|
||||
node: context.getSourceCode().ast,
|
||||
message: 'Components using database operations should include PlatformServiceMixin.',
|
||||
});
|
||||
}
|
||||
},
|
||||
};
|
||||
},
|
||||
},
|
||||
|
||||
'no-direct-platform-service': {
|
||||
meta: {
|
||||
type: 'suggestion',
|
||||
docs: {
|
||||
description: 'Discourage direct PlatformServiceFactory usage',
|
||||
category: 'Migration',
|
||||
recommended: false,
|
||||
},
|
||||
schema: [],
|
||||
},
|
||||
create(context) {
|
||||
return {
|
||||
CallExpression(node) {
|
||||
if (node.callee.object?.name === 'PlatformServiceFactory' &&
|
||||
node.callee.property?.name === 'getInstance') {
|
||||
context.report({
|
||||
node,
|
||||
message: 'Consider using PlatformServiceMixin methods instead of direct PlatformServiceFactory.',
|
||||
});
|
||||
}
|
||||
},
|
||||
};
|
||||
},
|
||||
},
|
||||
|
||||
'prefer-mixin-methods': {
|
||||
meta: {
|
||||
type: 'suggestion',
|
||||
docs: {
|
||||
description: 'Prefer mixin convenience methods over direct database calls',
|
||||
category: 'Migration',
|
||||
recommended: false,
|
||||
},
|
||||
schema: [],
|
||||
},
|
||||
create(context) {
|
||||
return {
|
||||
CallExpression(node) {
|
||||
// Check for patterns that could use mixin methods
|
||||
if (node.callee.property?.name === 'dbQuery') {
|
||||
const arg = node.arguments[0];
|
||||
if (arg && arg.type === 'Literal') {
|
||||
const sql = arg.value.toLowerCase();
|
||||
if (sql.includes('select * from contacts')) {
|
||||
context.report({
|
||||
node,
|
||||
message: 'Consider using this.$getAllContacts() instead of direct SQL.',
|
||||
});
|
||||
}
|
||||
if (sql.includes('select * from settings')) {
|
||||
context.report({
|
||||
node,
|
||||
message: 'Consider using this.$settings() instead of direct SQL.',
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
};
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Pre-commit Hook
|
||||
|
||||
Create `.pre-commit-config.yaml`:
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- repo: local
|
||||
hooks:
|
||||
- id: eslint-migration-check
|
||||
name: ESLint Migration Check
|
||||
entry: npx eslint --ext .vue --rule 'timesafari/no-direct-database-util: error'
|
||||
language: system
|
||||
files: \.vue$
|
||||
|
||||
- id: no-legacy-logging
|
||||
name: No Legacy Logging
|
||||
entry: bash -c 'if grep -r "logConsoleAndDb" src/ --include="*.vue" --include="*.ts"; then echo "Found legacy logging imports"; exit 1; fi'
|
||||
language: system
|
||||
pass_filenames: false
|
||||
```
|
||||
|
||||
## Migration Validation Script
|
||||
|
||||
Create `scripts/validate-migration.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
echo "🔍 Validating PlatformServiceMixin migration..."
|
||||
|
||||
# Check for legacy patterns
|
||||
echo "Checking for legacy databaseUtil imports..."
|
||||
LEGACY_DB_IMPORTS=$(grep -r "import.*databaseUtil" src/ --include="*.vue" --include="*.ts" | wc -l)
|
||||
echo "Found $LEGACY_DB_IMPORTS legacy databaseUtil imports"
|
||||
|
||||
echo "Checking for legacy logging imports..."
|
||||
LEGACY_LOG_IMPORTS=$(grep -r "logConsoleAndDb" src/ --include="*.vue" --include="*.ts" | wc -l)
|
||||
echo "Found $LEGACY_LOG_IMPORTS legacy logging imports"
|
||||
|
||||
# Check for mixin usage
|
||||
echo "Checking for PlatformServiceMixin usage..."
|
||||
MIXIN_USAGE=$(grep -r "PlatformServiceMixin" src/ --include="*.vue" | wc -l)
|
||||
echo "Found $MIXIN_USAGE files using PlatformServiceMixin"
|
||||
|
||||
# Check for direct PlatformService usage
|
||||
echo "Checking for direct PlatformService usage..."
|
||||
DIRECT_PLATFORM=$(grep -r "PlatformServiceFactory.getInstance" src/ --include="*.vue" --include="*.ts" | wc -l)
|
||||
echo "Found $DIRECT_PLATFORM direct PlatformService usages"
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo "📊 Migration Status Summary:"
|
||||
echo "- Legacy databaseUtil imports: $LEGACY_DB_IMPORTS (should be 0)"
|
||||
echo "- Legacy logging imports: $LEGACY_LOG_IMPORTS (should be 0)"
|
||||
echo "- Mixin usage: $MIXIN_USAGE (should be high)"
|
||||
echo "- Direct PlatformService usage: $DIRECT_PLATFORM (should be low)"
|
||||
|
||||
# Set exit code based on legacy usage
|
||||
if [ $LEGACY_DB_IMPORTS -gt 0 ] || [ $LEGACY_LOG_IMPORTS -gt 0 ]; then
|
||||
echo "❌ Migration validation failed - legacy patterns found"
|
||||
exit 1
|
||||
else
|
||||
echo "✅ Migration validation passed - no legacy patterns found"
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
1. **Install ESLint rules**:
|
||||
```bash
|
||||
npm install --save-dev eslint-plugin-timesafari
|
||||
```
|
||||
|
||||
2. **Run validation**:
|
||||
```bash
|
||||
npm run lint
|
||||
./scripts/validate-migration.sh
|
||||
```
|
||||
|
||||
3. **Fix issues automatically**:
|
||||
```bash
|
||||
npm run lint -- --fix
|
||||
```
|
||||
|
||||
## IDE Integration
|
||||
|
||||
### VS Code Settings
|
||||
|
||||
Add to `.vscode/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"eslint.validate": [
|
||||
"javascript",
|
||||
"typescript",
|
||||
"vue"
|
||||
],
|
||||
"eslint.options": {
|
||||
"extensions": [".js", ".ts", ".vue"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebStorm Settings
|
||||
|
||||
1. Go to Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
|
||||
2. Enable ESLint
|
||||
3. Set configuration file to `.eslintrc.js`
|
||||
4. Add `.vue` to file extensions
|
||||
Reference in New Issue
Block a user