prpm-dbp 0.13.0 → 0.13.2

package/SKILL.md

@@ -11,6 +11,8 @@ Model boleh hasilkan Jawi yang nampak betul tetapi salah, dan pembaca tidak dapa
 
 ## Peraturan
 
+0. **Semak ejaan ikut DBP, bukan ikut ingatan.** Ini peraturan pertama kerana ia yang paling kerap dilanggar. Perkataan yang anda "tahu" ejaannya masih perlu disemak. Contoh sebenar daripada penggunaan: `sunah` ialah `سنة` tetapi `sunat` ialah `سونت`; `bena` langsung tiada ejaan Jawi dalam PRPM walaupun ia perkataan yang sah; `salat` hanyalah rujukan silang kepada `solat`. Tiada satu pun daripada perbezaan ini boleh diteka daripada bentuk Rumi. Jalankan `lookup` atau `jawi`, jangan tulis daripada ingatan.
+
 1. **Jangan hantar Jawi yang belum disemak.** Setiap perkataan Jawi dalam output mesti datang dari PRPM atau ditanda belum disahkan.
 2. **Tanda, jangan sekat.** Kalau satu perkataan tiada dalam PRPM, hantar kerja itu dan senaraikan perkataan berkenaan di hujung. Jangan tahan seluruh dokumen sebab satu nama khas.
 3. **Sebut sumber.** PRPM ada beberapa kamus. Bila petik definisi, sebut kamus mana (Kamus Dewan Edisi Keempat, Kamus Pelajar Edisi Kedua, dan lain-lain).
@@ -67,6 +69,10 @@ Tanda baca, baris baru dan jarak dikekalkan, jadi susun atur dokumen tidak rosak
 
 Contoh kedua: `dipelajari` ialah terbitan sah daripada `ajar`. Alat ini **tidak** akan menulis Jawi bagi `ajar` di tempatnya. Itu perkataan lain, dan ejaannya berbeza.
 
+**Calon pembacaan songsang diisih ikut rantai kepercayaan.** Perkataan hanya layak menjadi pembacaan bagi sesuatu ejaan Jawi jika PRPM memberikannya ejaan Jawi **sendiri**. Kata yang PRPM catatkan tanpa ejaan Jawi (`bena`), atau yang definisinya rujukan silang (`salat` → `® solat`), dibuang daripada senarai calon walaupun dataset komuniti memetakannya kepada ejaan yang sama.
+
+Perkataan yang **belum diketahui** statusnya, iaitu tiada dalam cache, tidak pernah dibuang. Ketiadaan bukan bukti kegagalan. Ia kekal sebagai calon dan sumbernya dilabel `dataset`. Kerana itu memanaskan cache mengurangkan kekaburan: bukan kerana peraturan berubah, tetapi kerana bukti bertambah.
+
 **Bila `rumi` jumpa kekaburan**, satu ejaan Jawi memetakan kepada beberapa perkataan Rumi. Semua calon dipaparkan dipisah `|`. Pilih ikut konteks ayat, jangan ambil yang pertama secara membuta.
 
 Sebahagian kekaburan itu palsu dan diselesaikan sendiri. DBP menandakan bentuk varian dengan **rujukan silang**: definisi `kalkalah` ialah `®qalqalah.`, bukan definisi sebenar. Varian begitu dinyahutamakan, jadi `قلقله` dibaca `qalqalah` terus.
@@ -288,7 +294,11 @@ Panduan DBP membahagikannya kepada dua:
 
 Jenis kedua ialah Pedoman §8.17 (juga Klinik Jawi Siri ke-35): alif melambangkan [a] di suku kata tertutup untuk membezakannya daripada pepet yang tidak dilambangkan. **Ejaan DBP sudah mengandungi peraturan ini**, jadi pakej tidak perlu menjananya. Sembilan pasangan rujukan diuji, kesemuanya dibezakan dengan betul.
 
-Jenis pertama pula tidak boleh diselesaikan oleh mana-mana peraturan. Itulah sebab `rumi` melaporkan semua calon dan enggan memilih: bagi homograf hakiki, DBP sendiri menyatakan kekaburan itu dibenarkan dan hanya konteks ayat boleh menyelesaikannya.
+**Istilah "hakiki" dan "tidak hakiki" tidak digunakan dalam pakej ini.** Sumber pengajaran bercanggah tentang mana satu bermaksud apa: satu panduan menyatakan hakiki bermaksud tidak dibezakan dan dibenarkan kekal, satu lagi menyatakan hakiki bermaksud boleh diselesaikan dengan huruf saksi. Pakej melaporkan fakta yang boleh diperhatikan, iaitu ejaan Jawi ini dikongsi oleh perkataan-perkataan berikut, dan membiarkan pengelasan itu kepada guru.
+
+Sebahagian homograf ejaan lama telah diselesaikan oleh ejaan baharu dengan menambah huruf vokal: `tulang` تولڠ dan `tolong` تولوڠ, `tujuh` توجوه dan `tujah` توجه. Pembezaan itu ada dalam ejaan yang kita ambil dan dikunci dengan ujian.
+
+Jenis yang tinggal pula tidak boleh diselesaikan oleh mana-mana peraturan. Itulah sebab `rumi` melaporkan semua calon dan enggan memilih: bagi homograf hakiki, DBP sendiri menyatakan kekaburan itu dibenarkan dan hanya konteks ayat boleh menyelesaikannya.
 
 `--homograf` menandakan perkataan yang ejaan Jawinya dikongsi, supaya penulis tahu sebelum menghantar bahawa pembaca akan bergantung pada konteks:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prpm-dbp",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Semak ejaan Bahasa Melayu dan Jawi terhadap PRPM Dewan Bahasa dan Pustaka. CLI dan skill untuk AI agent.",
   "keywords": [
     "bahasa-melayu",

package/src/tukar.js

@@ -172,10 +172,26 @@ export function petaSongsang(cache, dataset = null) {
   // Isyaratnya mestilah tanda ® itu, BUKAN kehadiran ejaan Jawi. `pada`
   // tiada Jawi dalam PRPM manakala `pad` (pinjaman Inggeris) ada, jadi
   // mengutamakan "yang ada Jawi" akan menukar setiap `pada` menjadi `pad`.
-  const rujukanSilang = new Set()
-  for (const [kata, rec] of Object.entries(cache)) {
-    const def = rec?.entri?.[0]?.definisi ?? ''
-    if (/^®/.test(def.trim())) rujukanSilang.add(kata)
+  // Calon dikelaskan kepada TIGA peringkat, bukan dua.
+  //
+  //   layak  : PRPM ada entri DAN ada ejaan Jawi sendiri. Ini lapisan 1.
+  //   tolak  : PRPM ada entri tetapi TIADA ejaan Jawi, atau definisinya
+  //            rujukan silang (®). Kata begini tidak boleh menjadi
+  //            pembacaan bagi mana-mana ejaan Jawi.
+  //   entah  : tiada dalam cache langsung. Ketiadaan BUKAN bukti kegagalan,
+  //            jadi ia tidak boleh dibuang. Ia kekal sebagai calon lapisan 3.
+  //
+  // Perbezaan antara `tolak` dan `entah` itulah pembetulannya. Versi lama
+  // hanya memeriksa rujukan silang, dan hanya bagi calon yang datang dari
+  // cache, jadi calon dataset seperti salat dan bena lolos sepenuhnya.
+  const darjat = (rumi) => {
+    const rec = cache[rumi]
+    if (!rec) return 'entah'
+    const def = (rec.entri?.[0]?.definisi ?? '').trim()
+    if (/^®/.test(def)) return 'tolak'
+    if (rec.dijumpai && !rec.jawi) return 'tolak'
+    if (rec.jawi) return 'layak'
+    return 'entah'
   }
 
   const tambah = (jawi, rumi, sumber) => {
@@ -183,9 +199,8 @@ export function petaSongsang(cache, dataset = null) {
     if (!kunci) return
     const bilangan = kunci.split(/\s+/).length
     if (bilangan > maxKata) maxKata = bilangan
-    if (!peta.has(kunci)) peta.set(kunci, { utama: [], rujukan: [] })
-    const jenis = rujukanSilang.has(rumi) ? 'rujukan' : 'utama'
-    const slot = peta.get(kunci)[jenis]
+    if (!peta.has(kunci)) peta.set(kunci, { layak: [], entah: [], tolak: [] })
+    const slot = peta.get(kunci)[darjat(rumi)]
     if (!slot.includes(rumi)) slot.push(rumi)
   }
 
@@ -201,15 +216,21 @@ export function petaSongsang(cache, dataset = null) {
 }
 
 /**
- * Pilih calon songsang. Bentuk yang DBP sendiri tandakan sebagai rujukan
- * silang (®) hanya digunakan apabila tiada bentuk utama. Selain itu semua
- * calon dilayan sama rata, dan kekaburan sebenar dilaporkan sepenuhnya.
+ * Pilih calon songsang mengikut rantai kepercayaan.
+ *
+ * Calon lapisan 1 (ada entri PRPM dengan ejaan Jawi sendiri) menang mutlak.
+ * Kekaburan dilaporkan HANYA apabila dua calon lapisan 1 berkongsi ejaan,
+ * iaitu homograf tulen seperti sunah dan sanat yang kedua-duanya سنة.
+ *
+ * Apabila tiada calon lapisan 1, calon yang belum diketahui digunakan dan
+ * sumbernya dilabel, tidak dipulangkan secara senyap.
  */
 export function pilihCalon(masuk) {
   if (!masuk) return null
   if (Array.isArray(masuk)) return { calon: masuk, sumber: 'campur' }
-  if (masuk.utama.length) return { calon: masuk.utama, sumber: 'utama' }
-  if (masuk.rujukan.length) return { calon: masuk.rujukan, sumber: 'rujukan' }
+  if (masuk.layak?.length) return { calon: masuk.layak, sumber: 'dbp' }
+  if (masuk.entah?.length) return { calon: masuk.entah, sumber: 'dataset' }
+  if (masuk.tolak?.length) return { calon: masuk.tolak, sumber: 'rujukan' }
   return null
 }