SAT ETRANS ASM — VS Code Extension

Dukungan bahasa untuk file ASM kustom (.sat.asm) pada platform ETRANS-V5/SAT: syntax highlighting, linting/diagnostics, IntelliSense, navigasi, folding, snippets, dan auto-formatting yang konsisten dengan toolchain SAT ASM Executor.

— Hanya untuk file dengan ekstensi .sat.asm —

Fitur Utama

• Syntax Highlighting untuk instruksi ASM, variabel, label, directives (.KEY_VALUE/.ITEM), dan sebagainya.
• Diagnostics (lint ringan):
  • Instruksi tidak valid, referensi label/fungsi (PUSHF/CALLF/Jxx/JMP) yang belum didefinisikan.
  • Fungsi F_ setelah END wajib ditutup dengan RET (error bila tidak).
  • Hint untuk label/fungsi yang tidak pernah dipakai.
• IntelliSense:
  • Saran keyword instruksi, angka setelah O/S/I/L/D, saran nama fungsi setelah CALL.
  • Generator perintah MOV (range): ketik “MS 0-5” → snippet massal.
  • Integrasi daftar fungsi eksternal: tambahkan path direktori via setting, maka saran CALL akan memuat semua fungsi dari file di direktori tersebut (Pencarian substring, contoh ketik "bu" → muncul fungsi yang mengandung "bu").
  • Warna nama fungsi setelah CALL otomatis berbeda jika fungsi ditemukan di direktori yang diatur (function) vs tidak ditemukan (teks biasa/variable).
• Navigasi:
  • Go to Definition: variabel → asal MOV; PUSHF/CALLF → definisi F*/L*; Jxx/JMP → target label.
  • Definition untuk fungsi eksternal (CALL): jika terindeks dari direktori yang dikonfigurasi, Ctrl+Click akan lompat ke file sumbernya.
  • Document Symbols: daftar F*/L* di Outline (Explorer).
• Folding:
  • Blok F*/L* dan blok data DLOAD…DEND / LLOAD…LEND.
• Formatting (dengan setting):
  • Uppercase untuk instruksi terdaftar, normalisasi spasi, indentasi rapi.
  • Indentasi isi F_ (konfigurabel), RET tidak terindent.
  • Indent directives .KEY_VALUE/.ITEM di dalam DLOAD/LLOAD.
  • Normalisasi baris kosong berurutan (maksimal N).
  • Perbedaan warna opcode per kategori (arithmetic, jump, keyword) melalui semantic tokens.

Cara Pakai Singkat

0. Konfigurasi terlebih dahulu path direktori fungsi eksternal Anda (opsional namun direkomendasikan, agar IntelliSense CALL berfungsi optimal):

   • Buka Settings → cari “SAT ASM”.
   • Isi satAsm.functionSearchPaths dengan direktori berisi file fungsi, misalnya:
     • /Users/stevanuspangau/SAT/Projects/Etrans-v5-ph/etrans-v5-ph-client/etrans_v5_dev/app/functions/lof
   • Jika perlu, sesuaikan satAsm.functionExtensions (default: .py, .ts, .js).
   • Jalankan perintah “SAT: Refresh Function Index” untuk memuat ulang daftar fungsi.

1. Install ekstensi ini dan buka file ASM Anda dengan ekstensi .sat.asm.

2. Mulai menulis ASM. Contoh:

; Deklarasi variabel
MOV S0 "Hello"
MOV I0 1
MOV D0 dict1

; Blok data dictionary
DLOAD D0
  .KEY_VALUE "key1" "value1"
  .KEY_VALUE "key2" 100
DEND

END

; Fungsi (setelah END) wajib diakhiri RET
F_print_hello:
  PRINT S0
RET

3. Format-on-save aktif secara default (bisa dimatikan via setting). Anda juga bisa menjalankan “Format Document” secara manual.

Bahasa & Sintaks

• Instruksi inti: MOV, SET, PUSH, CALL, CALLF, PUSHF, END, RET, PRINT, JMP, CMP, JE, JNE, JG, JGE, JL, JLE, ADD, SUB, MUL, INC, DEC, GLOBAL, GLOBAL_RM, GLOBAL_CLR, DLOAD/DEND, LLOAD/LEND.
• Variabel: Sx (string), Ix (integer), Ox (object), Lx (list), Dx (dict), G* (global).
• Label/Fungsi: L_*: untuk label, F_*: untuk fungsi (RET di akhir fungsi).
• Directives: .KEY_VALUE (untuk DLOAD), .ITEM (untuk LLOAD).

Formatting & Indent

• Indentasi isi fungsi F_ menggunakan spasi sesuai setting satAsm.indentSize (default 2), contoh:

F_fn:
  PRINT "inside function"
RET

• Directives di dalam DLOAD/LLOAD terindent tambahan satu level. Jika berada di dalam fungsi F_, total indent = 2 level.
• Normalisasi baris kosong: jumlah baris kosong berturut-turut dibatasi oleh satAsm.maxConsecutiveBlankLines (default 1).

Diagnostics & Linting

• Instruksi tidak dikenal → error.
• Referensi label/fungsi (PUSHF, CALLF, JE/JNE/JG/JGE/JL/JLE/JMP) yang belum didefinisikan → error di tempat referensi.
• Fungsi F_ setelah END tanpa RET → error pada baris definisi fungsi.
• Label/fungsi tidak pernah direferensikan → hint agar mudah refactor.

IntelliSense & Navigasi

• Go to Definition:
  • Variabel dalam operasi (PUSH/dsb) → baris MOV asal.
  • PUSHF/CALLF → definisi F_...: atau L_...:.
  • JE/JNE/JG/JGE/JL/JLE/JMP → target label.
• Completion:
  • Kata kunci instruksi, angka setelah O/S/I/L/D, saran CALL (daftar statis yang bisa diperluas), generator MOV “MS|MI|MO|ML|MD start-end”.
• Folding & Symbols:
  • Collapse/expand blok F_/L_, DLOAD…DEND, LLOAD…LEND; Outline menampilkan fungsi/label.

Snippets & Commands

• Snippets dasar (trigger): MS/MI/MO/ML/MD → MOV, PS/PI/PO/PL/PD → PUSH, F_/L_ → template label/fungsi.
• Command: “SAT: Masukan nama fungsi” → QuickPick snippet CALL siap pakai.
• Command: “SAT: Generate MOV Commands” → generator perintah MOV (rentang indeks).

Konfigurasi

• satAsm.formatOnSave (boolean, default: true)
  • Format otomatis saat save file .sat.asm.
• satAsm.maxConsecutiveBlankLines (number, default: 1)
  • Maksimal baris kosong berturut-turut saat format.
• satAsm.indentSize (number, default: 2)
  • Jumlah spasi per level indent (isi F_ + directives di DLOAD/LLOAD).
• satAsm.functionSearchPaths (string[], default: [])
  • Daftar direktori (absolute atau workspace-relative) untuk memindai fungsi eksternal. Contoh:
    • /Users/stevanuspangau/SAT/Projects/Etrans-v5-ph/etrans-v5-ph-client/etrans_v5_dev/app/functions/lof
  • Semua file dengan ekstensi yang diizinkan akan dipindai untuk nama fungsi.
• satAsm.functionExtensions (string[], default: [".py", ".ts", ".js"])
  • Ekstensi file yang akan dipindai. Pola default mengenali def name( pada Python dan function name(/export function name( pada TS/JS.

Persyaratan

• VS Code 1.60.0 atau lebih baru.
• File harus berekstensi .sat.asm agar semua fitur aktif.

Build & Publish (Pengembang)

Jika Anda menemui error “Extension entrypoint(s) missing: extension/out/extension.js”, pastikan Anda sudah mengompilasi TypeScript:

1. Masuk ke folder extension/ dan jalankan:
   • npm install
   • npm run compile
2. Perintah vsce package akan mengeksekusi vscode:prepublish sehingga build dilakukan otomatis saat packaging.
3. Pastikan berkas out/extension.js terbentuk dan tidak diabaikan oleh .vscodeignore (sudah disiapkan untuk menyertakan out/**).

Batasan Dikenal

• Daftar saran fungsi setelah CALL membaca indeks direktori yang Anda atur. Jalankan “SAT: Refresh Function Index” setelah mengubah/menambah file fungsi agar indeks terbaru terpakai.
• Indentasi on-enter mengikuti konfigurasi bahasa statis; hasil akhir tetap rapi karena formatter pada save/manual.

Changelog

Lihat file CHANGELOG.md untuk daftar perubahan.

Lisensi

Private/Proprietary. Lihat file LICENSE.