Pemeriksaan Tipe pada CI

Pemeriksaan yang hanya dijalankan bila teringat akan cepat terlupakan, sehingga proyek dengan konsumen nyata membutuhkan gerbang yang berjalan sendiri pada setiap push. Topik ini memasang tiga gerbang pada pustaka-waktu, yaitu lint, typecheck, dan pengujian, melalui skrip package.json dan satu berkas workflow CI. Susunan gerbang ditata dari yang paling murah ke yang paling mahal, dan seluruh gerbangnya disimulasikan di sandbox dengan perintah yang sama seperti yang dijalankan CI. Setelah topik ini selesai, setiap perubahan yang mematahkan kontrak tertolak sebelum sempat digabungkan.

Skrip gerbang pada package.json#

Gerbang diberi nama sebagai skrip pada package.json agar perintahnya tertulis di satu tempat. Skrip typecheck memanggil tsc atas proyek, skrip test menjalankan program uji dengan node, dan skrip lint memanggil eslint atas folder src. Nama skrip inilah yang dipanggil ulang oleh CI, sehingga keketatan yang dilihat CI identik dengan yang dilihat mesin pengembang. Folder pustaka-waktu memuat tsconfig.json beserta src/tipe-publik.ts, src/konversi.ts, src/format.ts, dan uji.ts, sehingga seluruh berkas yang diperiksa gerbang sudah ada pada tempatnya.

{
  "name": "pustaka-waktu",
  "version": "0.1.0",
  "description": "Pustaka utilitas konversi dan pemformatan durasi tanpa dependensi.",
  "scripts": {
    "typecheck": "tsc --project . --pretty false",
    "test": "node --no-warnings uji.ts",
    "lint": "eslint src"
  },
  "devDependencies": {
    "typescript": "^7.0.2",
    "eslint": "^9.0.0",
    "typescript-eslint": "^8.0.0"
  }
}

Skrip lint menuntut pemasangan eslint beserta konfigurasinya, sehingga pengerjaan konfigurasi lint tidak termasuk lingkup topik ini dan hanya skripnya yang ditampilkan. Perintah-perintahnya dijalankan melalui npm setelah dependensi pengembangan terpasang.

# tidak-dijalankan
# memasang dependensi pengembangan persis seperti yang tercatat pada lockfile
npm ci
# menjalankan tiga gerbang secara berurutan
npm run lint
npm run typecheck
npm test

Perintah-perintah di atas tidak dieksekusi di sandbox karena memerlukan pemasangan paket dari jaringan. Simulasinya menggunakan perintah yang sama secara langsung, yaitu tsc dan node, pada bagian akhir topik ini. Nilai devDependencies mencatat perkakas yang dipasang pada tahap dependensi pengembangan, dan lockfile menjaga pemasangan itu tetap sama di mesin mana pun.

Workflow CI pada GitHub Actions#

Berkas workflow berisi langkah otomatisasi yang dibaca GitHub Actions, dan tempatnya wajib berada pada .github/workflows. Pemicunya berupa setiap push pada branch main dan setiap pull_request, sehingga tidak ada perubahan yang masuk tanpa melewati gerbang. Satu job bernama gerbang menjalankan seluruh langkah pada mesin virtual yang dibangun baru setiap kali pemicunya terpicu.

name: ci

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  gerbang:
    runs-on: ubuntu-latest
    steps:
      - name: Mengambil kode
        uses: actions/checkout@v4
      - name: Menyiapkan Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Memasang dependensi pengembangan
        run: npm ci
      - name: Gerbang lint
        run: npm run lint
      - name: Gerbang typecheck
        run: npm run typecheck
      - name: Gerbang pengujian
        run: npm test

Setiap langkah bertanggung jawab atas satu kebutuhan. actions/checkout mengambil kode, actions/setup-node menyiapkan Node.js versi 24, dan npm ci memasang dependensi persis mengikuti lockfile agar mesin CI menghasilkan pemasangan yang sama setiap kali berjalan. Tiga langkah terakhir memanggil skrip gerbang secara berurutan, dan job berhenti pada langkah pertama yang gagal. Keberhasilan seluruh langkah menandai commit sebagai lolos, sedangkan kegagalan salah satunya menandainya merah beserta log langkah yang gagal.

Urutan gerbang murah ke mahal#

Urutan gerbang ditata dari yang paling murah ke yang paling mahal agar kegagalan tertangkap sebelum biaya besar dibayar. Lint paling murah karena hanya membaca teks sumber tanpa memahami tipe, typecheck lebih mahal karena memeriksa seluruh program hingga level tipe, dan pengujian paling mahal karena benar-benar mengeksekusi kode. Tabel berikut merangkum perbandingannya.

Urutan ini berlaku dua arah. Pada CI, kegagalan lint menghentikan job sebelum typecheck dan pengujian sempat berjalan, sehingga waktu mesin tidak terbuang untuk push yang sudah jelas salah. Pada mesin pengembang, urutan yang sama menjadi kebiasaan sebelum push, dan latihannya murah karena setiap gerbang dapat dipanggil dengan satu perintah npm. Penghematan itu makin terasa ketika pengujiannya menyiapkan data dan menjalankan banyak kasus. Kegagalan yang tertangkap lebih awal juga mempersempit lokasi pencariannya, karena push yang lolos lint pasti bebas dari kesalahan yang dilaporkan lint.

Menjalankan gerbang di sandbox#

Simulasi dimulai dari gerbang typecheck atas proyek yang sehat. Perintahnya identik dengan isi skrip typecheck, dan berakhirnya tanpa pesan berarti seluruh berkas pada include lolos pemeriksaan.

# gerbang typecheck atas proyek yang sehat
tsc --project pustaka-waktu --pretty false

Gerbang pengujian dijalankan berikutnya dengan node langsung sebagai pengganti perintah npm test tanpa memasang paket apa pun.

# gerbang pengujian atas program uji pustaka
node --no-warnings pustaka-waktu/uji.ts

1 jam 30 menit
1.50 jam
90
2.25
membaca 70
90
ditolak: masukan harus berupa angka durasi berhingga dan tak negatif
ditolak: durasi tidak boleh NaN atau negatif

Kedua gerbang lolos, dan berikutnya push yang salah disimulasikan. Berkas berikut mengirim teks “90” ke fungsi yang menuntut number, seolah-olah seorang pengembang menulis kode tanpa menjalankan pemeriksaan terlebih dahulu. Karena mengimpor modul lokal, eksekusinya ditunjukkan melalui perintah compiler di bawahnya.

// tidak-dijalankan
import { keMenit } from "./src/konversi.ts";

console.log(keMenit("90", "menit"));

# menggambarkan gerbang typecheck yang menolak push berisi kode salah
tsc --noEmit --pretty false --allowImportingTsExtensions --strict pustaka-waktu/uji-gagal.ts

pustaka-waktu/uji-gagal.ts(4,21): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Pesan TS2345 tersebut menunjuk posisi argumen yang salah, dan pada CI error semacam ini membuat job berhenti serta menandai push sebagai gagal. Perbaikannya berupa mengirim number, menjalankan ulang gerbang, dan baru mendorong perubahan. Dengan gerbang yang bekerja demikian, kontrak tipe pustaka terjaga tanpa bergantung pada ketelitian siapa pun.

Kesalahan umum#

• Menjadikan CI satu-satunya tempat menjalankan pemeriksaan. Push yang gagal berulang membuat riwayat branch kotor, dan menunggu umpan balik dari mesin CI paling lambat. Umpan balik tercepat sebenarnya sudah tersedia, yaitu compiler pada mesin pengembang. Perbaikannya berupa menjalankan skrip yang sama secara lokal sebelum setiap push.
• Menata urutan gerbang dari yang paling mahal. Pengujian yang panjang dieksekusi padahal lint saja sudah mampu menolak push tersebut. Waktu mesin yang terbuang menumpuk seiring bertambahnya push yang gagal pada titik yang sama. Perbaikannya berupa mengurutkan lint, typecheck, lalu pengujian seperti pada workflow.
• Menonaktifkan gerbang yang sering gagal agar push lekas hijau. Gerbang yang mati mengubah CI menjadi jalur perizinan yang tidak memeriksa apa pun. Perbaikannya berupa memperbaiki penyebab kegagalan tersebut, dan bila laporan gerbang keliru, perbaiki aturannya alih-alih mematikan gerbang.

Ringkasan#

• Tiga gerbang diberi nama sebagai skrip package.json berupa lint, typecheck, dan test, sehingga mesin pengembang dan CI menjalankan perintah yang sama.
• Berkas .github/workflows/ci.yml memicu job gerbang pada setiap push main dan pull_request, dan job berhenti pada langkah pertama yang gagal.
• Urutan lint, typecheck, lalu pengujian menata pemeriksaan dari yang paling murah ke yang paling mahal.
• Simulasi di sandbox memperlihatkan typecheck yang lolos senyap dan push berisi kode salah yang ditolak dengan pesan TS2345.

Referensi#

• About workflows — GitHub Docs — Dokumentasi GitHub Actions tentang berkas workflow, pemicunya, dan jobs-nya.
• package.json — npm Docs — Dokumentasi berkas package.json beserta skema scripts dan devDependencies yang dipakai pada topik ini.