@mclawnet/agent 0.6.20 → 0.6.21

package/skills/theone-cocos-standards/references/review/quality-review.md

@@ -0,0 +1,239 @@
+# TypeScript Quality Review
+
+This review focuses on TypeScript code quality issues including access modifiers, strict mode compliance, error handling, and code hygiene.
+
+## TypeScript Strict Mode Violations
+
+```typescript
+// ❌ CRITICAL: Strict mode disabled
+// tsconfig.json
+{
+    "compilerOptions": {
+        "strict": false // Bad!
+    }
+}
+
+// ✅ CORRECT: Enable strict mode
+{
+    "compilerOptions": {
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "strictBindCallApply": true,
+        "strictPropertyInitialization": true
+    }
+}
+
+// Severity: 🔴 Critical
+// Fix: Enable strict mode in tsconfig.json
+```
+
+## Access Modifier Violations
+
+```typescript
+// ❌ CRITICAL: Missing access modifiers
+@ccclass('NoModifiers')
+export class NoModifiers extends Component {
+    playerNode: Node | null = null; // Implicitly public!
+    currentHealth: number = 100;    // Implicitly public!
+
+    updateHealth(value: number) {   // Implicitly public!
+        this.currentHealth = value;
+    }
+}
+
+// ✅ CORRECT: Explicit modifiers
+@ccclass('WithModifiers')
+export class WithModifiers extends Component {
+    @property(Node)
+    private readonly playerNode: Node | null = null;
+
+    private currentHealth: number = 100;
+
+    public updateHealth(value: number): void {
+        this.currentHealth = value;
+    }
+}
+
+// Severity: 🔴 Critical
+// Fix: Add access modifiers (public/private/protected) to all members
+```
+
+## Silent Error Handling
+
+```typescript
+// ❌ CRITICAL: Silent failures
+@ccclass('SilentErrors')
+export class SilentErrors extends Component {
+    public getPlayer(id: string): Player | undefined {
+        const player = this.players.get(id);
+        return player; // Caller doesn't know why it failed
+    }
+}
+
+// ✅ CORRECT: Throw exceptions
+@ccclass('ThrowExceptions')
+export class ThrowExceptions extends Component {
+    public getPlayer(id: string): Player {
+        const player = this.players.get(id);
+        if (!player) {
+            throw new Error(`Player not found: ${id}`);
+        }
+        return player;
+    }
+}
+
+// Severity: 🔴 Critical
+// Fix: Throw exceptions for errors, not silent failures
+```
+
+## console.log in Production
+
+```typescript
+// ❌ CRITICAL: Unconditional console.log
+@ccclass('ConsoleLogBad')
+export class ConsoleLogBad extends Component {
+    protected update(dt: number): void {
+        console.log('Update'); // In production build!
+    }
+}
+
+// ✅ CORRECT: Conditional or removed
+@ccclass('ConsoleLogGood')
+export class ConsoleLogGood extends Component {
+    protected update(dt: number): void {
+        if (CC_DEBUG) {
+            console.log('Update');
+        }
+    }
+}
+
+// Severity: 🔴 Critical (for playables)
+// Impact: Bundle size increase, performance
+// Fix: Wrap in CC_DEBUG or remove entirely
+```
+
+## Inline Comments Instead of Descriptive Names
+
+```typescript
+// ❌ IMPORTANT: Comments explaining unclear code
+@ccclass('InlineCommentsBad')
+export class InlineCommentsBad extends Component {
+    private h: number = 100; // health
+
+    public td(a: number): void { // take damage
+        this.h = this.h - a; // subtract
+        if (this.h <= 0) { // dead
+            this.hd(); // handle death
+        }
+    }
+}
+
+// ✅ CORRECT: Self-explanatory names
+@ccclass('InlineCommentsGood')
+export class InlineCommentsGood extends Component {
+    private currentHealth: number = 100;
+
+    public takeDamage(amount: number): void {
+        this.currentHealth -= amount;
+        if (this.isDead()) {
+            this.handleDeath();
+        }
+    }
+
+    private isDead(): boolean {
+        return this.currentHealth <= 0;
+    }
+
+    private handleDeath(): void {
+        // Implementation
+    }
+}
+
+// Severity: 🟡 Important
+// Fix: Use descriptive names, remove inline comments
+```
+
+## Missing readonly/const
+
+```typescript
+// ❌ IMPORTANT: Mutable when should be immutable
+@ccclass('MissingReadonly')
+export class MissingReadonly extends Component {
+    @property(Node)
+    private targetNode: Node | null = null; // Should be readonly
+
+    private maxHealth: number = 100; // Should be static readonly
+}
+
+// ✅ CORRECT: Use readonly/const
+@ccclass('WithReadonly')
+export class WithReadonly extends Component {
+    @property(Node)
+    private readonly targetNode: Node | null = null;
+
+    private static readonly MAX_HEALTH: number = 100;
+}
+
+// Severity: 🟡 Important
+// Fix: Add readonly to fields not reassigned, use static readonly for constants
+```
+
+## Using `any` Type
+
+```typescript
+// ❌ IMPORTANT: Using any without justification
+@ccclass('UsingAny')
+export class UsingAny extends Component {
+    private data: any = {}; // Type safety lost
+
+    public processData(input: any): any {
+        return input; // No type checking
+    }
+}
+
+// ✅ CORRECT: Use proper types
+interface PlayerData {
+    id: string;
+    name: string;
+    level: number;
+}
+
+@ccclass('WithTypes')
+export class WithTypes extends Component {
+    private data: Map<string, PlayerData> = new Map();
+
+    public processData(input: PlayerData): PlayerData {
+        return input;
+    }
+}
+
+// Severity: 🟡 Important
+// Fix: Define proper types and interfaces, avoid `any`
+```
+
+## Summary: Quality Review Checklist
+
+**🔴 Critical (Must Fix):**
+- [ ] TypeScript strict mode enabled in tsconfig.json
+- [ ] All members have access modifiers (public/private/protected)
+- [ ] Exceptions thrown for errors (no silent failures)
+- [ ] console.log removed or wrapped in CC_DEBUG
+- [ ] No nullable warnings (proper null handling)
+
+**🟡 Important (Should Fix):**
+- [ ] readonly used for non-reassigned fields
+- [ ] const used for constants (not let)
+- [ ] No inline comments (self-explanatory code)
+- [ ] Optional chaining (?.) for safe access
+- [ ] Nullish coalescing (??) for defaults
+- [ ] No `any` types without justification
+
+**🟢 Nice to Have:**
+- [ ] Arrow functions for callbacks
+- [ ] Destructuring for cleaner code
+- [ ] Type guards for type safety
+- [ ] Utility types (Partial, Required, etc.)
+
+**Code quality is the foundation - fix these issues before performance optimization.**