Arsitektur Modul

Repository ini tidak memakai framework web atau runtime server. Seluruh kode program berada di src/ dan dijalankan sebagai dua skrip CLI terpisah: start memanggil bun run src/build.ts, sedangkan check memanggil bun run src/check.ts (package.json:36-42¹). Keduanya duduk di atas satu lapisan helper (src/utils/) dan satu berkas kontrak tipe (src/types.ts), sementara data/ menyimpan isi daftar API yang menjadi sumber kebenaran.

Peta ketergantungan antar modul

Diagram berikut memetakan empat kelompok modul beserta simbol yang benar-benar menyeberang batas modul. Garis putus-putus menandai impor tipe saja, yang hilang saat kompilasi.

graph TD
  build["src/build.ts<br/>pipeline markdown"]
  check["src/check.ts<br/>validator data"]
  files["src/utils/index.ts<br/>getFiles · getLanguage · isBlacklisted · resolve"]
  markdown["src/utils/markdown.ts<br/>translate · markdownBuilder · generateToc"]
  types["src/types.ts<br/>CategoryType · ListType"]
  data["data/<kategori>/id.json · en.json"]
  srcdata["src/data/blacklist.json · vocabularies.json"]

  build -->|"generateToc, markdownBuilder"| markdown
  build -->|"getFiles, getLanguage, isBlacklisted, resolve"| files
  check -->|"getFiles, isBlacklisted"| files
  build -.->|"CategoryType, ListType"| types
  check -.->|"CategoryType"| types
  markdown -.->|"CategoryType"| types
  markdown -->|"vocabularies.json"| srcdata
  files -->|"blacklist.json"| srcdata
  files -->|"readdir rekursif berkas .json"| data
  build -->|"Bun.write per berkas kategori"| data

  style build fill:#2d7d46,color:#fff
  style check fill:#dc2626,color:#fff
  style files fill:#8b5cf6,color:#fff
  style markdown fill:#8b5cf6,color:#fff
  style types fill:#f59e0b,color:#000
  style data fill:#336791,color:#fff
  style srcdata fill:#336791,color:#fff
%% fig: Ketergantungan empat modul utama
%% desc: Dua entry point CLI memakai helper yang sama, membaca data/ lewat getFiles, dan hanya build.ts yang menulis kembali berkas kategori.

Peran tiap modul

Arah impor satu arah

Lapisan helper tidak pernah mengimpor entry point. src/utils/index.ts hanya mengimpor path, fs/promises, dan ../data/blacklist.json (src/utils/index.ts:1-3⁹). src/utils/markdown.ts hanya mengimpor ../types dan ../data/vocabularies.json (src/utils/markdown.ts:1-2¹⁰). Di sisi lain, src/build.ts mengimpor ./utils/markdown dan ./utils (src/build.ts:1-5¹¹), dan src/check.ts mengimpor ./utils saja, tanpa ./utils/markdown (src/check.ts:1-4¹²). Kedua entry point juga tidak saling mengimpor, sehingga keduanya bisa dijalankan sendiri-sendiri lewat bun start atau bun check.

State di level modul

Tidak ada fungsi main. src/build.ts menyimpan state di scope modul: data, crawledx, crawled, dan agent (src/build.ts:7-10¹³), lalu langsung menjalankan loop pembacaan berkas di top level (src/build.ts:13-15¹⁴). src/check.ts memakai pola yang sama dengan crawled dan agent (src/check.ts:6-7¹⁵). Karena itu setiap berkas entry point adalah program utuh: mengimpornya berarti menjalankan efek sampingnya, bukan mengambil fungsi darinya.

data/ sebagai sumber kebenaran

getFiles() menelusuri direktori data/ secara rekursif dan mengumpulkan setiap berkas berakhiran .json (src/utils/index.ts:13-33¹⁶). Setiap kategori berupa satu direktori dengan satu berkas per bahasa: data/general/id.json untuk bahasa Indonesia (data/general/id.json:1-3⁷) dan data/general/en.json untuk bahasa Inggris (data/general/en.json:1-3). Objek yang sama juga dipakai balik sebagai tipe CategoryType saat dibaca dengan Bun.file(file).json() di kedua entry point (src/build.ts:13-15, src/check.ts:9-10). Setelah kategori disusun, src/build.ts menulis kembali berkas itu lewat Bun.write (src/build.ts:77).

Dua helper dengan beban berbeda

markdownBuilder(categories, language) merakit tabel markdown per kategori: baris header dari translate(), baris pemisah | - | - | - | - | - | - |, lalu satu baris per API (src/utils/markdown.ts:8-33²⁰). generateToc(markdown) tidak menyentuh data/ sama sekali; ia memindai string markdown yang sudah jadi lewat regex ^(#{1,6})\s+(.+)$ dan menyusun daftar bersarang (src/utils/markdown.ts:35-57²¹). Pemisahan ini menjelaskan mengapa src/check.ts cukup mengimpor getFiles dan isBlacklisted. Rincian tiap helper ada di Helper Markdown dan Daftar Isi dan Helper Berkas dan Filter Blacklist.

Berkas pendukung di src/data/

blacklist.json dan vocabularies.json bukan bagian dari daftar kategori, karena keduanya tinggal di src/data/, di luar data/. isBlacklisted mencocokkan substring HTML terhadap isi blacklist (src/utils/index.ts:35-37²²), dan berkas itu berisi tiga kata kunci (src/data/blacklist.json:1⁸). translate mengambil label kolom per bahasa dari vocabularies (src/utils/markdown.ts:4-6²³).

Kontrak tipe bersama

src/types.ts mendefinisikan ItemType yang tidak diekspor, lalu mengekspor CategoryType ( categoryName dan apis) serta ListType yang memetakan kode bahasa ke daftar kategori (src/types.ts:1-17⁶). ListType hanya dipakai src/build.ts untuk mengumpulkan hasil per bahasa (src/build.ts:7-10¹³), sedangkan src/check.ts cukup memakai CategoryType (src/check.ts:1-4¹²).

⚠️ package.json masih memuat "module": "src/builder.ts" (package.json:8²⁴), padahal src/ hanya berisi build.ts, check.ts, types.ts, dan dua direktori. Jalur eksekusi yang benar selalu lewat scripts (package.json:36-42¹), bukan field module itu. Jangan menganggap src/builder.ts ada.

Tahap yang dijalankan src/build.ts dibahas di Pipeline Build Markdown dan Mode Rewrite dan Status API. Aturan yang ditegakkan src/check.ts ada di Validator Data lewat check.ts, bentuk berkas di data/ ada di Skema Data Kategori, dan modul mana yang dijalankan CI ada di Otomasi GitHub Actions.