Menjalankan Proyek di Lokal

Repository ini tidak punya tahap kompilasi. Berkas TypeScript di src/ dijalankan langsung oleh Bun, dan seluruh perintah masuk lewat scripts di package.json:36-42¹. Pemasangan dependensi cukup sekali dengan bun install, lalu setiap tugas dijalankan sebagai script terpisah.

Peta perintah ke efeknya

Diagram berikut memetakan empat perintah utama ke berkas yang dieksekusi dan ke efek sampingnya. Perintah bun start dan bun start --rewrite berbagi entry point yang sama, src/build.ts, lalu bercabang pada pembacaan argumen.

graph TD
  install["bun install"] --> prepare["prepare: husky install"]
  install --> runtime["Bun menjalankan .ts langsung, noEmit"]
  start["bun start"] --> buildts["src/build.ts"]
  rw["bun start --rewrite"] --> buildts
  rw --> flag["argumen --rewrite terdeteksi"]
  flag --> net["fetch documentationUrl, timeout 10_000"]
  net --> prune["entri nonaktif dan NSFW dibuang"]
  buildts --> write["Bun.write berkas JSON kategori"]
  write --> md["susun ulang README dan TOC"]
  md --> fmt["Bun.spawn memanggil bun format"]
  check["bun check"] --> checkts["src/check.ts"]
  checkts --> dup["duplikat documentationUrl"]
  checkts --> nsfw["isBlacklisted"]
  dup --> exit1["process.exit 1"]
  nsfw --> exit1
  style install fill:#2d7d46,color:#fff
  style start fill:#2d7d46,color:#fff
  style buildts fill:#f59e0b,color:#000
  style checkts fill:#f59e0b,color:#000
  style rw fill:#f59e0b,color:#000
  style check fill:#f59e0b,color:#000
  style net fill:#8b5cf6,color:#fff
  style write fill:#8b5cf6,color:#fff
  style md fill:#8b5cf6,color:#fff
  style fmt fill:#8b5cf6,color:#fff
  style exit1 fill:#dc2626,color:#fff
  style prune fill:#dc2626,color:#fff
%% fig: Peta perintah lokal ke berkas dan efeknya
%% desc: Empat perintah Bun bercabang ke build.ts atau check.ts, lalu berujung pada penulisan berkas, pemanggilan prettier, atau process.exit 1.

Pemasangan dependensi

devDependencies memuat bun-types, commitizen, cz-conventional-changelog, husky, node-fetch, dan prettier, sedangkan typescript diletakkan di peerDependencies package.json:9-19². Field module menunjuk src/builder.ts, padahal entry yang benar-benar dijalankan script start adalah src/build.ts, sehingga field itu tidak dipakai saat menjalankan proyek package.json:8³.

tsconfig.json disetel untuk dijalankan tanpa emit: noEmit bernilai true, allowImportingTsExtensions bernilai true, moduleResolution bernilai bundler, strict bernilai true, dan types dibatasi ke bun-types tsconfig.json:2-18⁴. Karena itu global seperti Bun, Bun.file, dan Bun.write dikenali tanpa import, dan tidak ada direktori hasil build yang perlu dibersihkan.

Menjalankan bun start

Tanpa argumen, src/build.ts mengumpulkan berkas JSON kategori lewat getFiles(), yang menelusuri direktori data secara rekursif dan hanya mengambil berkas berekstensi .json src/utils/index.ts:13-33⁵. Setiap berkas ditulis kembali dengan indentasi 2 spasi, lalu blok <!-- API START --> dan <!-- TOC START --> pada README diganti isi baru untuk tiap bahasa src/build.ts:87-105⁶. Langkah terakhir menjalankan Bun.spawn(['bun', 'format']), jadi satu kali bun start sudah sekaligus merapikan format berkas src/build.ts:108-109⁷. Rincian penyusunan markdown ada di Pipeline Build Markdown.

Menjalankan bun start --rewrite

Mode rewrite aktif saat Bun.argv[2] sama dengan --rewrite src/build.ts:20⁸. Untuk setiap API, skrip mengambil api.documentationUrl dengan Accept-Encoding: zlib, gzip, redirect: 'follow', dan AbortSignal.timeout(10_000) src/build.ts:39-49⁹. Hasilnya dipakai untuk memperbarui api.status, dan entri dihapus dari array bila URL masuk daftar blacklist atau bila status sekarang dan sebelumnya sama-sama false src/build.ts:64-77¹⁰.

⚠️ bun start --rewrite menulis ulang berkas JSON kategori di data/ dan dapat menghapus entri secara permanen. Jalankan di branch bersih dan tinjau git diff sebelum membuat commit. Perilaku status ini dijelaskan lebih jauh di Mode Rewrite dan Status API.

Menjalankan bun check

src/check.ts adalah gate sebelum membuat pull request. Ia menolak dua documentationUrl identik di dalam satu berkas kategori, membandingkan URL setelah fragmen #anchor dibuang, lalu berhenti dengan Duplikat documentationUrl di <file>: <url> dan process.exit(1) src/check.ts:12-25¹¹. Pemeriksaan kedua mengambil isi halaman dan menjalankan isBlacklisted; bila cocok, skrip mencetak Sorry, the NSFW API is not allowed here :) lalu keluar dengan kode 1 src/check.ts:43-55¹². Kesalahan jaringan diabaikan oleh blok catch kosong, jadi bun check hanya gagal pada pelanggaran data. Aturan validasinya dibahas di Validator Data lewat check.ts, dan urutan langkah kontribusinya di Alur Kontribusi API Baru.

Hook husky dan prettier

Dua hook dideklarasikan di field husky package.json:20-25¹³. Hook pre-commit menjalankan bun format && git add --all, sehingga hasil format otomatis ikut masuk ke commit. Hook prepare-commit-msg menjalankan npx cz --hook dengan exec < /dev/tty, dan pesan commit mengikuti cz-conventional-changelog yang dikonfigurasi di field config.commitizen package.json:3-7¹⁴.

Opsi prettier disimpan di package.json:26-35¹⁵ dan berlaku untuk seluruh repository, termasuk berkas markdown hasil build.

Menyamakan dengan CI

Workflow di .github/workflows/ memberi urutan acuan: bun install lalu bun start --rewrite pada pengecekan status bulanan .github/workflows/update-status.yml:22-26¹⁶, dan bun install lalu bun start setelah pull request di-merge .github/workflows/build-merge.yml:22-26¹⁷. Keduanya memakai Bun versi 0.8.0. Menjalankan dua perintah yang sama secara lokal membuat hasil build sesuai dengan hasil CI. Susunan workflow lengkapnya ada di Otomasi GitHub Actions.

Panduan kontribusi juga menetapkan urutan yang sama untuk kontributor: bun check lebih dulu, baru bun start untuk memastikan perubahan berjalan CONTRIBUTING.md:25-27¹⁸.