refactor: pecah lib/api.ts dan constants/Styles.ts per domain
- lib/api.ts (879 baris) → 13 file di lib/api/ per domain - constants/Styles.ts (1.275 baris) → 10 file di constants/styles/ per domain - tambah docs/FILE-HEALTH.md dan referensinya ke CLAUDE.md - kedua file lama tetap sebagai re-export — zero breaking changes
This commit is contained in:
134
docs/FILE-HEALTH.md
Normal file
134
docs/FILE-HEALTH.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# FILE-HEALTH — Aturan Ukuran & Struktur File
|
||||
|
||||
Aturan ini berlaku untuk semua file dalam project ini.
|
||||
Tujuan: menjaga file tetap kecil, kohesif, dan mudah diproses oleh AI maupun manusia.
|
||||
|
||||
---
|
||||
|
||||
## Batas Ukuran File
|
||||
|
||||
| Tipe File | Maks Baris | Maks Karakter | Keterangan |
|
||||
|-----------|-----------|---------------|------------|
|
||||
| Route handler | 150 | 6.000 | Satu file = satu resource |
|
||||
| Service / use-case | 300 | 12.000 | Satu file = satu domain logic |
|
||||
| Repository / query | 250 | 10.000 | Pisah per entity |
|
||||
| Schema / validation | 200 | 8.000 | Pisah per domain |
|
||||
| Types / interfaces | 300 | 10.000 | Boleh agregat, tapi per modul |
|
||||
| Utility / helper | 200 | 8.000 | Satu concern per file |
|
||||
| Config | 100 | 4.000 | Tidak ada logic bisnis |
|
||||
| Test file | 400 | 16.000 | Satu file test per satu unit |
|
||||
|
||||
> **Hard limit global:** Tidak ada file yang boleh melebihi **500 baris** atau **20.000 karakter**,
|
||||
> kecuali file yang di-generate otomatis (migration, seed, generated types).
|
||||
|
||||
---
|
||||
|
||||
## Aturan Wajib
|
||||
|
||||
### 1. Satu File, Satu Tanggung Jawab
|
||||
- Setiap file harus bisa dijelaskan dalam satu kalimat pendek.
|
||||
- Jika penjelasannya butuh kata "dan" lebih dari sekali → **pecah file-nya**.
|
||||
|
||||
### 2. Tidak Ada "God File"
|
||||
- Dilarang menaruh lebih dari satu route group dalam satu file handler.
|
||||
- Dilarang mencampur business logic dengan transport layer (HTTP, WS, queue).
|
||||
- Dilarang mencampur type definition dengan implementation dalam satu file yang panjang.
|
||||
|
||||
### 3. Penamaan File Harus Eksplisit
|
||||
- Nama file harus mencerminkan isi secara tepat.
|
||||
- Hindari nama generik: `utils.ts`, `helpers.ts`, `common.ts`, `misc.ts`.
|
||||
- Gunakan pola: `[domain].[layer].ts` → contoh: `user.service.ts`, `payment.repository.ts`.
|
||||
|
||||
### 4. Index File Hanya Untuk Re-export
|
||||
- File `index.ts` hanya boleh berisi re-export, **bukan** implementasi.
|
||||
- Maksimal 50 baris untuk file index.
|
||||
|
||||
### 5. Tidak Ada Barrel Import yang Dalam
|
||||
- Hindari barrel yang mengimpor dari barrel lain lebih dari 2 level.
|
||||
- Ini membuat AI sulit trace dependency dengan akurat.
|
||||
|
||||
---
|
||||
|
||||
## Kapan Harus Pecah File
|
||||
|
||||
Pecah file segera jika salah satu kondisi ini terpenuhi:
|
||||
|
||||
- [ ] File melebihi batas karakter/baris di tabel di atas
|
||||
- [ ] Ada dua fungsi/class yang tidak saling bergantung dalam satu file
|
||||
- [ ] File mengandung lebih dari 3 exported symbol utama
|
||||
- [ ] File sulit diberi nama yang spesifik tanpa kata "dan"
|
||||
- [ ] Edit di satu bagian file sering menyebabkan konflik di bagian lain
|
||||
|
||||
---
|
||||
|
||||
## Pola Pemecahan File yang Dianjurkan
|
||||
|
||||
### Service yang Terlalu Besar
|
||||
```
|
||||
// SEBELUM: user.service.ts (600 baris)
|
||||
|
||||
// SESUDAH:
|
||||
user.service.ts // orchestration, max 150 baris
|
||||
user.query.service.ts // read operations
|
||||
user.command.service.ts // write operations
|
||||
user.notification.service.ts // side effects
|
||||
```
|
||||
|
||||
### Handler yang Terlalu Besar
|
||||
```
|
||||
// SEBELUM: user.route.ts (400 baris)
|
||||
|
||||
// SESUDAH:
|
||||
user.route.ts // route registration only
|
||||
user.handler.ts // handler functions
|
||||
user.middleware.ts // route-specific middleware
|
||||
```
|
||||
|
||||
### Types yang Terlalu Besar
|
||||
```
|
||||
// SEBELUM: types.ts (500 baris)
|
||||
|
||||
// SESUDAH:
|
||||
types/user.types.ts
|
||||
types/payment.types.ts
|
||||
types/shared.types.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Instruksi Khusus untuk AI
|
||||
|
||||
Ketika bekerja dalam project ini, **Claude wajib**:
|
||||
|
||||
1. **Menolak menambah kode** ke file yang sudah mendekati atau melebihi batas,
|
||||
kecuali penambahannya memang sangat kecil (< 10 baris) dan kohesif.
|
||||
|
||||
2. **Proaktif menyarankan refactor** saat mendeteksi file yang tumbuh tidak sehat,
|
||||
sebelum menambahkan fitur baru ke file tersebut.
|
||||
|
||||
3. **Tidak membuat "helper dump"** — setiap helper harus punya file sendiri
|
||||
yang namanya spesifik, bukan ditumpuk ke file utils yang ada.
|
||||
|
||||
4. **Selalu buat file baru** jika implementasi baru tidak secara alami masuk
|
||||
ke salah satu file yang sudah ada.
|
||||
|
||||
5. **Periksa ukuran file saat ini** sebelum mengedit — jika sudah > 80% dari
|
||||
batas, sarankan pecah terlebih dahulu.
|
||||
|
||||
---
|
||||
|
||||
## Pengecualian
|
||||
|
||||
File berikut **dikecualikan** dari aturan batas ukuran:
|
||||
|
||||
- `*.generated.ts` — file hasil code generation (Prisma, tRPC, dll)
|
||||
- `*.migration.ts` / `*_migration.sql` — file migrasi database
|
||||
- `*.seed.ts` — file seeding data
|
||||
- File di folder `__fixtures__/` atau `__mocks__/`
|
||||
|
||||
Pengecualian **tidak berlaku** untuk file konfigurasi runtime seperti
|
||||
`elysia.config.ts`, `app.ts`, atau `server.ts` — file ini tetap harus ringkas.
|
||||
|
||||
---
|
||||
|
||||
*Letakkan file ini di root project atau sertakan referensinya di `CLAUDE.md`.*
|
||||
Reference in New Issue
Block a user