> ## Documentation Index
> Fetch the complete documentation index at: https://arclux-os.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gotchas

> Hal-hal yang gampang bikin salah kalau gak tau

## GOTCHA KRITIS — baca ini sebelum debug apapun

1. **`nodeRequire.resolve()` TIDAK BISA DIPERCAYA di runtime webpack
   Next.js** — balikin path relatif ke lokasi bundle, bukan absolute
   filesystem path. Ini udah bikin bug yang sama 2x (sekali asli, sekali
   regresi pas "cleanup"). Kalau butuh resolve path native asset
   (`.wasm`, dll) di server-side Next.js code, JANGAN pakai
   `nodeRequire.resolve()` sama sekali — build path dari `process.cwd()`.
2. **Next.js dev server port suka geser + zombie process numpuk.**
   Kalau curl/test dapet response kosong/aneh, JANGAN asumsi itu bug
   kode — cek dulu `ps aux | grep node` (harus kosong sebelum start
   ulang) dan pastiin port yang dites PERSIS sama dengan yang muncul di
   baris `Local: http://localhost:XXXX`. Ini penyebab kebingungan
   paling sering sepanjang sesi-sesi kemarin.
3. **Selalu `cat` file dulu sebelum patch** — jangan asumsi isi file
   dari draft/issue/percakapan sebelumnya, walau keliatan "pasti sama".
   File bisa udah berubah dari sesi lain / PR lain.
4. Patch pakai python3 heredoc + verifikasi `anchor count == 1` sebelum
   nulis (abort kalau 0 atau >1) — pola aman yang udah terbukti.
   `set +H` dulu di awal sesi biar bash gak makan karakter `!` di
   heredoc.
5. Error yang ketangkep `ArcluxError` di API routes **gak otomatis
   ke-log** ke server console — kalau debug error yang gak keliatan di
   log, cek dulu apa error-handling-nya sengaja skip `console.error`.
6. Testing lewat `tsx` langsung (`analyzeRepository`/`buildIndex`)
   SKIP TOTAL webpack — itu cuma buktiin logic Node-nya bener, BUKAN
   buktiin jalan di runtime Next.js beneran. Dua-duanya harus dites
   terpisah, bug bisa ada di salah satu doang.
7. Komponen yang progress notes-nya bilang "typecheck-only, belum
   diverifikasi visual" — anggap serius kalau ada bug report soal itu,
   walau kodenya "kelihatan" udah bener pas dibaca.
8. `wasmPath` sekarang hardcoded ke struktur pnpm
   (`node_modules/.pnpm/tree-sitter-wasms@VERSION/...`) — bakal patah
   kalau pindah ke npm/yarn.