--- name: app-quality description: High-quality app evaluation framework — 12 dimension quality scoring, code quality, security, performance, accessibility, UX, architecture, testing, deployment readiness, observability, documentation license: MIT compatibility: opencode metadata: audience: developers, code-reviewers, architects domain: general paradigm: quality-first capabilities: - code-quality-scoring - security-audit - performance-benchmarking - accessibility-evaluation - ux-review - architecture-assessment - testing-coverage - deployment-readiness - documentation-quality - typescript-strictness - error-handling-review - observability-check integrates_with: - security-audit - frontend-react - backend-nodejs - database-postgres - database-security - devops-platform-engineering - backend-go - typescript --- # Aplikasi Kualitas Tinggi Standard Evaluasi > Framework komprehensif 12-dimensi untuk menilai apakah suatu aplikasi memenuhi standar kualitas tinggi. > Digunakan oleh @code-reviewer agent untuk evaluasi otomatis dan manual. ``` ┌─────────────────────────────────────────────────────────────┐ │ EVALUATION PIPELINE │ │ │ │ Input: Source Code + Config + Dependencies + Build Output │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ │ │ Static │→ │ Dynamic │→ │ Security│→ │ Report │ │ │ │ Analysis│ │ Analysis│ │ Audit │ │ Generator │ │ │ └─────────┘ └─────────┘ └─────────┘ └──────────────┘ │ │ │ │ │ │ │ │ └────────────┴────────────┴───────────────┘ │ │ │ │ │ ┌─────▼──────┐ │ │ │ 12-DIM │ │ │ │ SCORING │ │ │ └─────┬──────┘ │ │ │ │ │ ┌─────▼──────┐ │ │ │ GRADE + │ │ │ │ REPORT │ │ │ └────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 1. The 12-Dimension Quality Framework Setiap aplikasi dievaluasi dalam 12 dimensi independen. Masing-masing diberi skor 0-10, lalu dikalikan dengan bobot untuk mendapatkan skor akhir. ### Scoring Table | # | Dimensi | Bobot | Fokus Utama | |---|---------|-------|-------------| | 1 | Code Quality & Maintainability | 15% | Readability, DRY, SOLID, complexity | | 2 | Security Posture | 15% | OWASP Top 10, dependency, secrets | | 3 | Performance & Core Web Vitals | 12% | LCP, INP, CLS, bundle, render | | 4 | Accessibility (a11y) | 10% | WCAG AAA, semantic HTML, keyboard | | 5 | Architecture & Design | 10% | Separation of concerns, patterns | | 6 | Testing Maturity | 10% | Coverage, types, quality | | 7 | UX & User Experience | 8% | Consistency, loading, error states | | 8 | TypeScript Strictness | 6% | Strict mode, proper types | | 9 | Error Handling | 5% | Graceful degradation, logging | | 10 | Documentation | 4% | Code comments, README, API docs | | 11 | Observability & Monitoring | 3% | Logs, metrics, traces, alerts | | 12 | Deployment Readiness | 2% | CI/CD, env config, rollback | | | **Total** | **100%** | | ### Scoring Flow ``` ┌──────────────────┐ │ Start Evaluation│ └────────┬─────────┘ │ ▼ ┌──────────────────────────────────────┐ │ For Each Dimension (D1 - D12): │ │ │ │ ┌────────────┐ ┌───────────────┐ │ │ │ Run Checks │→ │ Score 0 - 10 │ │ │ └────────────┘ └───────┬───────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────┐ │ │ │ Weighted Score = Raw × Weight│ │ │ └──────────────────────────────┘ │ └──────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Aggregate: Total = Σ Weighted Scores │ ├──────────────────────────────────────┤ │ Grade: A(90-100) B(75-89) C(60-74) │ │ D(40-59) F(<40) │ ├──────────────────────────────────────┤ │ Generate Report with Findings │ └──────────────────────────────────────┘ ``` --- ## 2. Scoring Rubric Setiap dimensi dinilai dengan skala berikut: | Skor | Level | Deskripsi | |------|-------|-----------| | 10 | Sempurna | Best-in-class, reference implementation | | 9 | Excellent | Production-ready, minor nitpicks only | | 8 | Very Good | Solid, one or two minor improvements | | 7 | Good | Solid with room for improvement | | 6 | Adequate+ | Functional, noticeable issues | | 5 | Adequate | Passable, needs work | | 4 | Poor- | Significant issues in multiple areas | | 3 | Poor | Major shortcomings | | 2 | Critical- | Fundamentally broken | | 1 | Critical | Needs complete rewrite | | 0 | None | Not implemented at all | ### Scoring Rules 1. Start at 10 (perfect), subtract points for each failed check 2. Critical/security issues force max score of 4 regardless of other checks 3. If >50% checks fail, max score is 5 4. If >80% checks fail, max score is 2 5. Score is floored to nearest integer --- ## 3. Dimension 1: Code Quality & Maintainability (Bobot: 15%) ### Area Penilaian #### 3.1 Readability (30% dari dimensi) - [ ] Meaningful variable/function/class names (self-documenting) - [ ] Consistent formatting (enforced by Prettier/dprint) - [ ] No magic numbers — all constants named - [ ] No magic strings — string literals extracted to constants - [ ] Consistent casing convention per language (camelCase, PascalCase, etc.) - [ ] Code reads like prose — clear intent without comments - [ ] No deeply nested ternaries (max 1 level) - [ ] Boolean variables named as predicates (`isLoading`, `hasError`, `canSubmit`) #### 3.2 DRY Principle (20% dari dimensi) - [ ] No duplicated code blocks (>3 lines repeated) - [ ] Proper abstraction for repeated patterns - [ ] Utility functions extracted for shared logic - [ ] No copy-pasted API calls — use service layer - [ ] Shared types/interfaces extracted - [ ] Configuration values centralized (not scattered) #### 3.3 SOLID Principles (20% dari dimensi) - [ ] **Single Responsibility**: each class/function has one reason to change - [ ] **Open/Closed**: open for extension, closed for modification - [ ] **Liskov Substitution**: subtypes behave correctly when substituted - [ ] **Interface Segregation**: small focused interfaces, not god objects - [ ] **Dependency Inversion**: depend on abstractions, not concretions #### 3.4 Complexity Control (15% dari dimensi) - [ ] Cyclomatic complexity < 10 per function - [ ] Nesting depth <= 3 levels - [ ] Function length < 50 lines - [ ] File length < 300 lines (except generated/config files) - [ ] No deeply nested callbacks — use async/await or Promise chain #### 3.5 Imports & Dependencies (10% dari dimensi) - [ ] Imports organized (external → internal, absolute → relative) - [ ] No unused imports (checked by ESLint `no-unused-vars`) - [ ] No circular dependencies (checked by madge/dependency-cruiser) - [ ] No barrel files that cause circular imports - [ ] Dependencies version pinned (no `^` range in production) #### 3.6 Code Smells (5% dari dimensi) - [ ] No `any` type usage (unless documented exception) - [ ] No `// @ts-ignore` or `// @ts-expect-error` (unless documented) - [ ] No commented-out code - [ ] No `console.log` in production code (use proper logger) - [ ] No empty catch blocks - [ ] No `TODO`/`FIXME`/`HACK` without ticket reference - [ ] No mutable global state - [ ] No direct DOM manipulation (in React/Svelte apps) ### Scoring Formula D1 ```text Let pass = number of checks passed Let total = number of applicable checks Let rawScore = (pass / total) * 10 Let finalScore = Math.min(10, Math.floor(rawScore * 10) / 10) ``` --- ## 4. Dimension 2: Security Posture (Bobot: 15%) ### 4.1 OWASP Top 10 (2021) — 40% dari dimensi #### A01 — Broken Access Control - [ ] Proper authorization checks on all protected routes/endpoints - [ ] Role-based access control (RBAC) implemented - [ ] No IDOR vulnerabilities (user A cannot access user B's data) - [ ] API endpoints validate ownership before returning data - [ ] No direct object references without authorization #### A02 — Cryptographic Failures - [ ] Passwords hashed with bcrypt (cost >= 10) or argon2 - [ ] HTTPS enforced (HTTP redirects to HTTPS) - [ ] No weak crypto (MD5, SHA1 for security contexts) - [ ] TLS >= 1.2 configured on server - [ ] Sensitive data encrypted at rest - [ ] API keys/tokens stored securely (not in code) #### A03 — Injection - [ ] All SQL queries parameterized (no string concatenation) - [ ] ORM used with parameterized queries (Prisma, TypeORM, Drizzle) - [ ] No eval/Function constructor with user input - [ ] No dangerouslySetInnerHTML (React) without sanitization - [ ] Input validation on all user inputs (Zod, Valibot, Joi) - [ ] No NoSQL injection vectors (MongoDB sanitization) #### A04 — Insecure Design - [ ] Rate limiting on auth endpoints - [ ] Account lockout after N failed attempts - [ ] CSRF tokens on mutating requests - [ ] Secure password reset flow - [ ] MFA available for sensitive actions #### A05 — Security Misconfiguration - [ ] CORS configured correctly (not `Access-Control-Allow-Origin: *`) - [ ] Security headers set (CSP, X-Frame-Options, HSTS, etc.) - [ ] Error messages don't leak stack traces to users - [ ] Debug mode disabled in production - [ ] Default credentials changed - [ ] Unused routes/endpoints removed #### A06 — Vulnerable Components - [ ] `npm audit` passes with 0 critical vulnerabilities - [ ] Dependencies regularly updated (Dependabot/Renovate configured) - [ ] No known-vulnerable versions in use - [ ] Snyk/CodeQL scanning active - [ ] Lockfile committed (package-lock.json, yarn.lock) #### A07 — Authentication Failures - [ ] JWT with short expiry (< 15 min for access token) - [ ] Refresh token rotation - [ ] Secure cookie flags (httpOnly, secure, sameSite) - [ ] Session invalidation on logout - [ ] Password complexity requirements enforced - [ ] No hardcoded credentials #### A08 — Data Integrity Failures - [ ] Signed data (JWT, HMAC) verified on every request - [ ] No unsafe deserialization - [ ] File upload validation (type, size, scan) - [ ] CSP prevents script injection #### A09 — Logging & Monitoring - [ ] Security-relevant events logged (login, logout, admin actions) - [ ] Failed auth attempts logged - [ ] Audit trail for data changes - [ ] Logs include user ID, timestamp, action - [ ] Alerting on anomalous patterns #### A10 — SSRF - [ ] URL validation on external fetch requests - [ ] Internal network addresses blocked - [ ] Allowlist for outbound connections - [ ] URL parsing done server-side, not user-supplied ### 4.2 Dependency Audit — 20% dari dimensi - [ ] `npm audit` (or equivalent) — 0 critical, 0 high - [ ] No deprecated packages actively in use - [ ] Direct dependencies minimized (no unnecessary deps) - [ ] Dev dependencies separated from production - [ ] Snyk/Dependabot/CodeQL integrated in CI ### 4.3 Secrets Management — 20% dari dimensi - [ ] No secrets in code (API keys, passwords, tokens) - [ ] Environment variables for all secrets - [ ] .env.example committed (with placeholder values) - [ ] .env in .gitignore - [ ] Secret scanning in CI (truffleHog, git-secrets) ### 4.4 HTTP Security — 20% dari dimensi - [ ] Helmet.js (or equivalent) middleware - [ ] Content-Security-Policy header configured - [ ] X-Content-Type-Options: nosniff - [ ] X-Frame-Options: DENY (or SAMEORIGIN) - [ ] Strict-Transport-Security (HSTS) with preload - [ ] Referrer-Policy: strict-origin-when-cross-origin - [ ] Permissions-Policy configured ### Security Violation — Automatic Score Cap ``` IF any critical issue found (hardcoded secret, SQL injection, eval): D2 Score = MIN(D2 Score, 2) Flag as CRITICAL in report ``` --- ## 5. Dimension 3: Performance & Core Web Vitals (Bobot: 12%) ### 5.1 Core Web Vitals — 30% dari dimensi #### Largest Contentful Paint (LCP) — target < 2.5s - [ ] LCP < 2.5s (field data / Lighthouse) - [ ] No render-blocking resources above fold - [ ] Optimized hero images (WebP/AVIF, responsive sizes) - [ ] Preload key resources (fonts, hero image) - [ ] Server-side rendering or static generation for above-fold content #### Interaction to Next Paint (INP) — target < 200ms - [ ] INP < 200ms (field data) - [ ] No long tasks (>50ms) on main thread - [ ] Event handlers not blocking UI - [ ] Debounced/throttled expensive handlers (scroll, resize, input) - [ ] Web Workers for CPU-intensive operations #### Cumulative Layout Shift (CLS) — target < 0.1 - [ ] CLS < 0.1 - [ ] Explicit width/height on images and embeds - [ ] No late-loading content that shifts layout - [ ] Font swap behavior prevents layout shift - [ ] Dynamic content has reserved space ### 5.2 Bundle Optimization — 25% dari dimensi - [ ] Production JS bundle < 200KB (gzipped, initial load) - [ ] Route-level code splitting implemented - [ ] Component-level lazy loading for below-fold content - [ ] No large dependencies without tree-shaking - [ ] Bundle analysis tools used (next/bundle-analyzer, vite-bundle-visualizer) - [ ] Dynamic imports for heavy libraries - [ ] Moment.js avoided (use date-fns, dayjs, or native Intl) - [ ] Lodash imported selectively (`lodash/get` not `lodash`) ### 5.3 Image & Asset Optimization — 15% dari dimensi - [ ] Images in modern format (WebP/AVIF) - [ ] Lazy loading for below-fold images (`loading="lazy"`) - [ ] Responsive image sizes (`srcset` + `sizes`) - [ ] Image CDN or optimization pipeline (next/image, Cloudinary) - [ ] Fonts self-hosted or preloaded with `font-display: swap` - [ ] SVGs optimized (removed unnecessary metadata) - [ ] No oversized images (actual display size matched) ### 5.4 Caching Strategy — 10% dari dimensi - [ ] HTTP caching headers (Cache-Control, ETag) - [ ] CDN configured for static assets - [ ] Service worker for offline capability / faster loads - [ ] API responses cached where appropriate (Stale-While-Revalidate) - [ ] Browser caching for static assets (immutable) ### 5.5 Rendering Optimization — 10% dari dimensi - [ ] Server Components used for static content (Next.js App Router) - [ ] Virtual list for long scrollable lists (TanStack Virtual, react-window) - [ ] Debounced search inputs - [ ] Infinite scroll with proper cleanup - [ ] Memoization for expensive computations (useMemo, useCallback) - [ ] Stable references for child component props ### 5.6 Database Performance — 10% dari dimensi - [ ] N+1 queries detected and resolved - [ ] Indexes on frequently queried columns - [ ] Connection pooling configured - [ ] Query optimization (EXPLAIN ANALYZE) - [ ] Pagination for large result sets (no offset without limit) - [ ] Eager loading for related data (not lazy) ### Performance Budget ```text | Metric | Target | Critical | |----------------------|------------|----------| | LCP | < 2.5s | > 4.0s | | INP | < 200ms | > 500ms | | CLS | < 0.1 | > 0.25 | | TTFB | < 800ms | > 1.8s | | FCP | < 1.8s | > 3.0s | | Total Bundle (gzip) | < 200KB | > 500KB | | TBT (Total Blocking) | < 200ms | > 500ms | | SI (Speed Index) | < 3.4s | > 5.8s | ``` --- ## 6. Dimension 4: Accessibility (a11y) (Bobot: 10%) ### 6.1 WCAG AAA Compliance — 50% dari dimensi #### Perceivable - [ ] All non-text content has text alternatives (alt text on images) - [ ] Captions provided for audio/video content - [ ] Content can be presented without loss of information (responsive) - [ ] Color is not the only means of conveying information - [ ] Contrast ratio >= 7:1 for normal text (< 18px) - [ ] Contrast ratio >= 4.5:1 for large text (>= 18px bold / >= 24px) - [ ] Text can be resized up to 200% without loss of functionality - [ ] Images of text not used (except logo) #### Operable - [ ] All functionality available via keyboard - [ ] No keyboard traps - [ ] Visible focus indicator (focus ring, minimum 2px) - [ ] Focus order matches visual order - [ ] Skip navigation link provided - [ ] No flashing content > 3 times per second - [ ] Time limits adjustable or disabled - [ ] Motion animation triggered by interaction can be disabled #### Understandable - [ ] Language attribute set on `` element - [ ] Unusual words defined (glossary, tooltip) - [ ] Abbreviations explained on first use - [ ] Reading level appropriate for target audience - [ ] Navigation consistent across pages - [ ] Components with same functionality labelled consistently - [ ] Error messages suggest correction (not just "Error") - [ ] Form inputs have associated labels #### Robust - [ ] Semantic HTML elements used (`