Workflow Git aman untuk refactor massal perlu menjawab satu masalah utama: bagaimana mengubah banyak file atau banyak commit secara konsisten tanpa merusak repository, tanpa lolos ke branch utama dalam keadaan setengah jadi, dan tanpa mengandalkan script shell yang rapuh. Pendekatan yang paling masuk akal untuk tim biasanya bukan satu tool tunggal, melainkan kombinasi transformer yang deterministik, validasi lokal, dan verifikasi terpusat.

Artikel ini membahas pola praktis: Rust CLI sebagai mesin transformasi kode atau metadata commit, Git hook sebagai guardrail lokal, dan CI pipeline sebagai lapisan verifikasi final. Inspirasinya datang dari gagasan refactor dan rewriting repository secara terprogram, tetapi fokus di sini adalah implementasi tim yang aman, dapat diaudit, dan bisa diulang.

Kapan refactor massal butuh workflow khusus

Tidak semua perubahan memerlukan arsitektur ini. Namun, workflow terstruktur sangat berguna ketika perubahan memiliki sifat berikut:

  • Menyentuh ratusan atau ribuan file.
  • Harus konsisten di seluruh repository, misalnya rename API, migrasi format konfigurasi, atau normalisasi import.
  • Tidak aman jika dilakukan manual karena rawan miss.
  • Perlu dapat diulang saat branch target bergerak.
  • Perlu pembuktian bahwa hasil transformasi tidak mengubah semantik yang seharusnya tetap.

Contoh nyata:

  • Mengganti nama package internal di monorepo.
  • Mengubah pola pemanggilan API lama ke API baru.
  • Menstandarkan header lisensi, namespace, atau naming convention.
  • Memperbarui referensi konfigurasi lintas service.
  • Membersihkan histori commit tertentu sebelum merge ke branch integrasi.

Dalam kasus seperti ini, script shell sederhana sering cepat dibuat, tetapi cepat juga menjadi sumber masalah: parsing teks rapuh, error handling minim, sulit diuji, dan mudah berbeda perilakunya di Linux, macOS, atau CI image yang berbeda.

Arsitektur workflow Git aman untuk refactor massal

Model yang aman biasanya membagi tanggung jawab menjadi tiga lapisan:

  1. Rust CLI melakukan transformasi secara deterministik.
  2. Git hook memblokir kondisi lokal yang jelas bermasalah sebelum commit atau push.
  3. CI pipeline memverifikasi ulang hasil transformasi secara bersih dari awal.

Gambaran alur

Developer branch
  - jalankan Rust CLI dalam mode dry-run
  - review output dan log
  - jalankan transformasi nyata
  - pre-commit / pre-push hook memvalidasi hasil lokal
  - push branch

CI
  - checkout bersih
  - jalankan Rust CLI lagi dalam mode verify atau regenerate
  - cek diff harus kosong atau hanya diff yang diharapkan
  - jalankan test, lint, type-check, build
  - optional: validasi struktur commit / metadata

Merge
  - hanya jika semua guardrail lolos
  - simpan artefak log transformasi untuk audit

Pemisahan ini penting karena tiap lapisan punya tujuan berbeda:

  • CLI fokus pada correctness transformasi.
  • Hook fokus pada fast feedback.
  • CI fokus pada reproducibility dan konsistensi lintas environment.

Mengapa Rust CLI lebih aman daripada script shell biasa

Shell script tetap berguna untuk otomasi kecil, terutama jika tugasnya hanya merangkai command yang memang sudah stabil. Namun untuk refactor massal yang menyentuh struktur file, parsing source code, atau rewrite commit secara selektif, Rust CLI sering lebih aman karena beberapa alasan.

1. Tipe data dan error handling lebih jelas

Di shell, banyak kegagalan muncul sebagai string kosong, exit code yang terlupakan, atau ekspansi path yang tak terduga. Di Rust, Anda bisa memodelkan input, aturan transformasi, dan hasil validasi secara eksplisit. Ini menurunkan risiko transformasi setengah jalan tanpa terdeteksi.

2. Lebih cocok untuk transformasi deterministik

Refactor massal yang aman sebaiknya deterministic: input sama menghasilkan output sama. Rust memudahkan pembuatan pipeline yang jelas: scan file, parse, transform, validate, write.

3. Mudah diberi mode dry-run, logging, dan exit code yang konsisten

Dry-run bukan fitur tambahan; ini guardrail utama. Rust CLI memudahkan pemisahan mode:

  • plan: hitung file yang akan berubah.
  • apply: terapkan perubahan.
  • verify: gagal jika hasil repo tidak sesuai aturan.

4. Lebih mudah diuji

Untuk tool refactor, pengujian sangat penting. Anda bisa membuat fixture repository kecil dan memverifikasi:

  • file apa yang berubah,
  • isi akhir file,
  • kasus parse error,
  • idempotensi saat command dijalankan dua kali.

Kapan shell script masih cukup

Pilih shell jika:

  • perubahannya semata orchestration command yang sudah ada,
  • tidak perlu parsing source code,
  • jumlah file kecil,
  • tidak butuh portability tinggi atau test yang kompleks.

Begitu logika sudah bercabang, perlu rollback yang jelas, atau mulai memproses konten file secara struktural, Rust CLI biasanya lebih tepat.

Merancang Rust CLI untuk transformasi yang aman

Jangan mulai dari fungsi “ubah semua file”. Mulailah dari kontrak perilaku tool-nya. Tool refactor yang aman minimal memiliki kemampuan berikut:

  • Target selection: file mana yang diproses.
  • Preview: apa yang akan berubah.
  • Apply: terapkan perubahan.
  • Verify: pastikan repo sudah sesuai aturan.
  • Logging: catat keputusan dan kegagalan.
  • Exit code: bisa dipakai hook dan CI.

Contoh antarmuka CLI

refactor-cli plan --rule rename-api --path services/
refactor-cli apply --rule rename-api --path services/ --write
refactor-cli verify --rule rename-api --path services/
refactor-cli apply --rule rename-api --path services/ --write --staged-only

Prinsip pentingnya:

  • plan tidak menulis file.
  • apply --write baru benar-benar mengubah file.
  • verify gagal jika masih ada file yang seharusnya berubah.
  • --staged-only berguna di hook agar area validasi tidak terlalu luas.

Contoh struktur program

use std::fs;
use std::path::Path;

#[derive(Debug)]
struct Change {
    path: String,
    before_hash: String,
    after_hash: String,
    summary: String,
}

fn transform_content(input: &str) -> Option<String> {
    let output = input.replace("OldApiClient", "NewApiClient");
    if output == input {
        None
    } else {
        Some(output)
    }
}

fn process_file(path: &Path, write: bool) -> Result<Option<Change>, Box<dyn std::error::Error>> {
    let before = fs::read_to_string(path)?;
    let Some(after) = transform_content(&before) else {
        return Ok(None);
    };

    if write {
        fs::write(path, &after)?;
    }

    Ok(Some(Change {
        path: path.display().to_string(),
        before_hash: format!("{}", md5::compute(&before)),
        after_hash: format!("{}", md5::compute(&after)),
        summary: "rename OldApiClient -> NewApiClient".to_string(),
    }))
}

Contoh di atas sengaja sederhana. Untuk refactor source code yang serius, jangan bergantung pada replace mentah bila konteks sintaks penting. Jika bahasa target memiliki parser atau AST yang layak, gunakan itu. Trade-off-nya memang lebih kompleks, tetapi lebih aman daripada mengganti string membabi buta.

Aturan desain penting

  • Idempotent: menjalankan tool dua kali tidak menghasilkan perubahan tambahan.
  • Atomic per file: file gagal parse jangan ditulis setengah.
  • Explicit failure: jika aturan tak bisa diterapkan, keluar dengan error yang jelas.
  • Machine-readable log: JSON lines atau format serupa memudahkan audit di CI.

Contoh skenario: refactor lintas banyak file dengan guardrail

Misalkan tim backend ingin mengganti pemakaian OldApiClient ke NewApiClient di monorepo. Perubahannya melibatkan:

  • import statement,
  • inisialisasi objek,
  • konfigurasi environment terkait,
  • dokumentasi internal yang harus tetap sinkron.

Langkah 1: buat aturan transformasi yang sempit

Jangan gabungkan banyak perubahan semantik dalam satu rule. Pisahkan misalnya:

  • rule A: ubah import,
  • rule B: ubah konstruktor,
  • rule C: ubah key konfigurasi,
  • rule D: verifikasi tak ada simbol lama tersisa.

Pemisahan rule memudahkan debugging saat CI gagal. Anda langsung tahu tahap mana yang bermasalah.

Langkah 2: jalankan plan lebih dulu

refactor-cli plan --rule rename-api --path services/
refactor-cli plan --rule config-key-migration --path config/

Output plan sebaiknya menjawab:

  • berapa file akan berubah,
  • file mana yang gagal diparse,
  • berapa perubahan per kategori,
  • apakah ada file yang ambigu dan dilewati.

Langkah 3: apply ke branch khusus

git checkout -b chore/refactor-new-api-client
refactor-cli apply --rule rename-api --path services/ --write
refactor-cli apply --rule config-key-migration --path config/ --write

Gunakan branch terpisah, jangan langsung di branch kerja fitur lain. Ini mempermudah review, revert, dan re-run.

Langkah 4: validasi lokal via hook

Hook lokal mencegah developer melakukan commit atau push saat hasil refactor belum lengkap.

Contoh pre-commit sederhana:

#!/usr/bin/env sh
set -eu

if git diff --cached --name-only | grep -E '^(services/|config/)' >/dev/null; then
  echo "[pre-commit] verify refactor rules"
  refactor-cli verify --rule rename-api --path services/
  refactor-cli verify --rule config-key-migration --path config/
fi

Contoh pre-push untuk validasi lebih berat:

#!/usr/bin/env sh
set -eu

echo "[pre-push] run tests related to refactor"
refactor-cli verify --rule rename-api --path services/
make test-changed

Catatan penting: hook lokal mudah dilewati secara sengaja atau tidak sengaja, jadi jangan pernah mengandalkan hook sebagai satu-satunya lapisan proteksi. Hook berguna untuk feedback cepat, bukan sebagai otoritas final.

Pipeline CI untuk verifikasi hasil otomatis

CI harus mengasumsikan environment bersih dan tidak percaya hasil lokal. Peran CI bukan hanya menjalankan test, tetapi juga memastikan transformasi bisa direproduksi dan tidak ada drift.

Pola verifikasi yang aman

  1. Checkout branch.
  2. Install binary refactor-cli.
  3. Jalankan verify atau regenerate perubahan.
  4. Pastikan working tree tetap bersih setelah verifikasi.
  5. Jalankan lint, type-check, test, dan build.

Contoh job CI generik

steps:
  - checkout
  - run: cargo build --release
  - run: ./target/release/refactor-cli verify --rule rename-api --path services/
  - run: ./target/release/refactor-cli verify --rule config-key-migration --path config/
  - run: git diff --exit-code
  - run: make lint
  - run: make test
  - run: make build

Ada dua pola umum di CI:

  • Verify-only: CI gagal jika repository belum sesuai aturan.
  • Regenerate-and-check-diff: CI menjalankan transformasi, lalu gagal jika muncul diff tak terkomit.

Pola kedua sering lebih kuat karena benar-benar membuktikan determinisme tool. Jika output CI berbeda dari hasil lokal, berarti ada masalah pada portability, dependency, atau aturan transformasi.

Guardrail sebelum merge

Sebelum PR diizinkan merge, tetapkan guardrail yang eksplisit:

  • Semua rule verify wajib lolos.
  • git diff --exit-code setelah regenerate harus bersih.
  • Test regresi wajib lolos pada area terdampak.
  • Optional: blok merge jika masih ada simbol lama yang terdeteksi oleh grep atau analyzer khusus.
  • Optional: wajib ada log artefak perubahan untuk audit.

Jika repository besar, pertimbangkan matriks CI berdasarkan direktori atau package agar validasi tetap cepat tanpa mengorbankan cakupan.

Strategi dry-run yang benar

Dry-run bukan sekadar mencetak “akan mengubah 120 file”. Dry-run yang berguna harus cukup informatif untuk membantu reviewer dan operator memahami dampak perubahan sebelum file benar-benar ditulis.

Apa yang sebaiknya ditampilkan dalam dry-run

  • Daftar file yang akan berubah.
  • Jenis rule yang diterapkan pada tiap file.
  • Alasan file dipilih atau dilewati.
  • Ringkasan warning, misalnya parse ambigu atau format tak dikenal.
  • Estimasi kategori perubahan, bukan benchmark performa yang belum diverifikasi.

Contoh output log yang lebih mudah dipakai mesin:

{"level":"info","rule":"rename-api","path":"services/user.rs","action":"modify"}
{"level":"warn","rule":"rename-api","path":"services/legacy.rs","action":"skip","reason":"parse_error"}
{"level":"info","rule":"config-key-migration","path":"config/app.yaml","action":"modify"}

Format seperti ini memudahkan:

  • ditampilkan di CI,
  • disimpan sebagai artefak,
  • diproses lagi untuk laporan coverage transformasi.

Rollback yang realistis untuk refactor massal

Rollback harus dirancang sebelum apply, bukan setelah terjadi masalah. Ada beberapa level rollback yang umum.

1. Rollback via branch isolation

Yang paling sederhana dan sering paling aman: semua refactor dilakukan di branch khusus. Jika hasil buruk, branch dibuang atau commit di-revert. Ini alasan utama mengapa refactor massal sebaiknya tidak dicampur dengan perubahan fitur harian.

2. Rollback via commit checkpoint

Simpan checkpoint jelas sebelum tiap tahap besar:

git commit -m "checkpoint: before rename-api"
refactor-cli apply --rule rename-api --path services/ --write
git commit -am "refactor: rename api client"
refactor-cli apply --rule config-key-migration --path config/ --write
git commit -am "refactor: migrate config keys"

Dengan begitu, rollback bisa selektif per tahap, bukan membatalkan semua sekaligus.

3. Rollback via generated patch

Untuk operasi yang sensitif, simpan patch sebelum dan sesudah transformasi:

git diff > before-refactor.patch
refactor-cli apply --rule rename-api --path services/ --write
git diff > after-refactor.patch

Ini bukan pengganti commit, tetapi berguna untuk audit dan analisis insiden.

4. Rollback histori commit

Jika transformasi juga menyentuh metadata commit atau melakukan rewrite histori, batas risikonya naik. Dalam konteks tim, gunakan pendekatan ini hanya jika benar-benar perlu dan pastikan ada:

  • clone atau mirror cadangan,
  • aturan branch protection,
  • komunikasi jelas bahwa SHA akan berubah,
  • rencana sinkronisasi ulang branch turunan.

Untuk banyak tim, lebih aman membatasi automasi pada working tree dan commit baru, bukan mengubah histori branch yang sudah dibagikan luas.

Logging, audit trail, dan debugging

Refactor massal yang aman harus bisa dijelaskan setelah kejadian. Jika sebuah file salah berubah, tim perlu tahu rule mana yang memprosesnya, kapan, dan mengapa.

Praktik logging yang berguna

  • Gunakan level log: info, warn, error.
  • Catat rule, path file, aksi, dan alasan skip.
  • Simpan ringkasan jumlah file diproses, dimodifikasi, dilewati, dan gagal.
  • Pisahkan log manusia dan log mesin jika perlu.

Checklist debugging saat hasil CI berbeda dari lokal

  • Pastikan input file sama persis, termasuk line ending.
  • Cek apakah CLI memproses file berdasarkan urutan nondeterministik.
  • Pastikan parser atau formatter tidak bergantung pada locale atau environment tertentu.
  • Cek apakah hook hanya memvalidasi file staged, sedangkan CI memvalidasi seluruh path.
  • Pastikan tool idempotent: jalankan dua kali dan cek tidak ada diff baru.

Masalah nondeterministik sering datang dari detail kecil seperti traversal direktori tanpa sort, formatter yang menghasilkan output berbeda karena konfigurasi tidak termuat, atau pemilihan file berdasarkan glob yang berbeda antar shell.

Kesalahan umum saat membangun workflow ini

Mengandalkan grep dan replace mentah untuk perubahan semantik

Jika simbol target bisa muncul di komentar, string literal, atau nama lain yang mirip, pendekatan ini rawan false positive. Gunakan parser atau setidaknya validasi kontekstual.

Menggabungkan terlalu banyak rule dalam satu commit besar

Review menjadi sulit dan rollback menjadi kasar. Pecah tahap transformasi berdasarkan tujuan teknis.

Menaruh seluruh logika di hook

Hook seharusnya ringan dan cepat. Logika transformasi utama tetap di CLI yang dapat diuji dan dapat dijalankan ulang di CI.

Tidak punya mode verify

Tool yang hanya bisa apply sulit dipakai sebagai guardrail. Mode verify penting agar CI bisa menjawab: “apakah repository sudah sesuai aturan?” tanpa mengubah state.

Tidak memikirkan file gagal parse

File yang gagal parse tidak boleh diam-diam dilewati tanpa jejak. Minimal beri warning, exit non-zero jika perlu, dan tampilkan daftar file yang butuh penanganan manual.

Kapan pendekatan ini lebih aman daripada script shell biasa

Pendekatan kombinasi Rust CLI + Git hook + CI lebih aman jika:

  • perubahan harus deterministik dan dapat direproduksi,
  • logika transformasi lebih dari sekadar satu baris sed,
  • perlu audit trail yang jelas,
  • repository besar dan dikerjakan banyak orang,
  • gagal sebagian harus bisa dideteksi dengan baik,
  • dibutuhkan validasi sebelum merge yang konsisten di semua environment.

Sebaliknya, script shell biasa masih rasional jika tugasnya sederhana, jangka pendek, dan cukup aman diperlakukan sebagai glue antar-command standar.

Rekomendasi implementasi untuk tim

  1. Mulai dari satu rule refactor yang sempit dan mudah diverifikasi.
  2. Buat mode plan, apply, dan verify sejak awal.
  3. Pastikan tool idempotent sebelum dipakai tim luas.
  4. Gunakan branch khusus untuk setiap operasi refactor massal.
  5. Pasang hook lokal untuk feedback cepat, tetapi tetap paksa verifikasi ulang di CI.
  6. Simpan log atau artefak perubahan untuk audit.
  7. Pisahkan commit per tahap agar rollback dan review tetap masuk akal.

Intinya, workflow Git aman untuk refactor massal bukan soal memilih tool yang paling canggih, melainkan memastikan perubahan dapat diprediksi, dapat dibuktikan, dan mudah dibatalkan. Rust CLI memberi fondasi yang lebih kuat untuk transformasi deterministik; Git hook memberi umpan balik cepat; dan CI memastikan hasil yang akan di-merge benar-benar sesuai aturan. Kombinasi tiga lapisan inilah yang biasanya membuat refactor besar tetap terkendali di lingkungan tim.