prpm-dbp 0.13.1 → 0.14.0

package/SKILL.md

@@ -11,6 +11,12 @@ 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.
+
+0b. **Dua langkah untuk menentukan sesuatu perkataan betul.** Pertama, pastikan ia **ada dalam PRPM**. Kedua, semak **konteks ayat**. Langkah kedua tidak boleh dilangkau: ejaan Jawi menggunakan empat huruf vokal berbanding enam dalam Rumi, jadi `مڠيکوت` ialah ejaan sah bagi `mengikut` dan `mengekot` sekali gus. Kamus boleh mengesahkan perkataan itu wujud; hanya ayat boleh menentukan yang mana satu dimaksudkan.
+
+0c. **PRPM sendiri boleh tersilap.** Entri `menyebuk` membawa sebutan dan definisi yang betul tetapi ejaan Jawi `مڽبوت`, iaitu ejaan `menyebut`. Pakej menandakannya dalam medan `mencurigakan` apabila huruf akhir Jawi tidak sepadan dengan hujung Rumi. Tandaan itu bermakna semak sendiri di PRPM, bukan buang.
+
 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 +73,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.
@@ -302,6 +312,21 @@ $ npx prpm-dbp jawi nota.txt --homograf
 homograf, ejaan Jawi dikongsi (3): اݢام=agama/igama, ساتو=satu/sato, بوروڠ=burung/borong
 ```
 
+## Laporan check-glosari
+
+Empat kelas berasingan, kerana menggabungkannya menenggelamkan yang penting:
+
+| Medan | Maksud |
+|---|---|
+| `bercanggah` | ejaan benar-benar berbeza daripada PRPM |
+| `ejaanLama` | berbeza **hanya** pada pasangan ortografi lama/baharu yang boleh dipetakan: `ف`→`ڤ`, `ج`→`چ`, `ة`→`ه`, `ك`→`ک` |
+| `homograf` | dua kata Rumi dalam glosari berkongsi ejaan Jawi yang sama |
+| `mencurigakan` | glosari sepadan dengan PRPM, tetapi huruf akhir PRPM sendiri tidak munasabah |
+
+`homograf` ialah satu-satunya kelas yang lolos senyap daripada semakan pasangan biasa: glosari boleh sepadan dengan PRPM dan **tetap salah** kerana ejaan itu dikongsi. `اية` sepadan dengan `ayah` dalam DBP, tetapi dalam teks al-Quran ia `آية` bermaksud `ayat`. Menerima DBP membuta di situ menghasilkan "menyatakan takrif **ayah** 1-5 Surah Al-Baqarah".
+
+Penambahan huruf vokal **tidak** dikira ejaan lama. Kalau kehadiran `ي` diabaikan, `بينا` (bina) dan `بنا` (bena) akan kelihatan sama, sedangkan itu dua perkataan berlainan.
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/bin/cli.js

@@ -186,6 +186,12 @@ async function main() {
             h.dijanaPedoman.map((x) => `${x.kata}=${x.jawi} [${x.rujukan}]`).join(', '),
         )
       }
+      if (h.mencurigakan?.length) {
+        console.error(
+          `ejaan PRPM mencurigakan (${h.mencurigakan.length}): ` +
+            h.mencurigakan.map((x) => `${x.kata}=${x.jawi} (hujung ${x.hujungRumi} vs ${x.hujungJawi})`).join(', '),
+        )
+      }
       if (h.homograf?.length) {
         console.error(
           `homograf, ejaan Jawi dikongsi (${h.homograf.length}): ` +

package/package.json

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

package/src/prpm.js

@@ -252,18 +252,52 @@ export async function auditJawi(jawiTeks, rumiTeks, cache, opts = {}) {
 
 /** Bandingkan glosari rumi->jawi sedia ada dengan ejaan rasmi PRPM. */
 export async function semakGlosari(glosari, cache, opts = {}) {
+  const { ejaanLamaSahaja, semakHurufAkhir } = await import('./semak.js')
   const bercanggah = []
+  const ejaanLama = []
+  const mencurigakan = []
   const tiadaDalamPrpm = []
   let sepadan = 0
   const senarai = Object.entries(glosari)
 
+  // Homograf ialah satu-satunya kelas ralat yang lolos senyap daripada
+  // semakan pasangan: glosari boleh sepadan dengan PRPM dan tetap salah
+  // kerana ejaan itu dikongsi perkataan lain. اية sepadan dengan `ayah`
+  // dalam DBP, tetapi dalam teks al-Quran ia آية bermaksud `ayat`.
+  const ikutJawi = new Map()
+  for (const [rumi, jawi] of senarai) {
+    if (!ikutJawi.has(jawi)) ikutJawi.set(jawi, [])
+    ikutJawi.get(jawi).push(rumi)
+  }
+
   for (const [i, [rumi, jawi]] of senarai.entries()) {
     const rec = await lookup(rumi, cache, opts)
     if (!rec.jawi) tiadaDalamPrpm.push(rumi)
-    else if (rec.jawi === jawi || (rec.jawiVarian ?? []).includes(jawi)) sepadan++
-    else bercanggah.push({ rumi, dalamGlosari: jawi, prpm: rec.jawi, url: rec.url })
+    else if (rec.jawi === jawi || (rec.jawiVarian ?? []).includes(jawi)) {
+      sepadan++
+      const curiga = semakHurufAkhir(rumi, rec.jawi)
+      if (curiga) mencurigakan.push(curiga)
+    } else if (ejaanLamaSahaja(jawi, rec.jawi)) {
+      // Ejaan lama boleh dipetakan kepada ejaan baharu. Bukan salah,
+      // cuma ortografi yang berbeza zaman.
+      ejaanLama.push({ rumi, dalamGlosari: jawi, prpm: rec.jawi, url: rec.url })
+    } else {
+      bercanggah.push({ rumi, dalamGlosari: jawi, prpm: rec.jawi, url: rec.url })
+    }
     opts.onProgress?.(i + 1, senarai.length)
   }
 
-  return { jumlah: senarai.length, sepadan, bercanggah, tiadaDalamPrpm }
+  const homograf = [...ikutJawi]
+    .filter(([, kata]) => kata.length > 1)
+    .map(([jawi, kata]) => ({ jawi, dikongsi: kata }))
+
+  return {
+    jumlah: senarai.length,
+    sepadan,
+    bercanggah,
+    ejaanLama,
+    homograf,
+    mencurigakan,
+    tiadaDalamPrpm,
+  }
 }

package/src/semak.js

@@ -0,0 +1,104 @@
+/**
+ * Semakan kewarasan ejaan: adakah huruf akhir Jawi sepadan dengan hujung Rumi?
+ *
+ * Diperlukan kerana PRPM sendiri kadangkala menyimpan ejaan yang salah pada
+ * kata kepala. Contoh sebenar: entri `menyebuk` membawa sebutan [me.nye.buʔ]
+ * dan definisi "masuk mencelah" yang betul, tetapi ejaan Jawi مڽبوت, iaitu
+ * ejaan `menyebut`. Huruf akhir ت bermaksud "t", sedangkan menyebuk berakhir
+ * dengan "k". Ekstraksi kita setia; sumbernya yang rosak.
+ *
+ * Diukur terhadap 37,801 pasangan sebenar: 99.6% sepadan. Yang tidak sepadan
+ * hampir kesemuanya kata serapan Arab yang mengekalkan ortografi asal
+ * (bahas بحث, asah اصح), jadi huruf Arab disenaraikan sebagai padanan sah.
+ *
+ * Ini menandakan, bukan menolak. Ejaan yang mencurigakan tetap dipulangkan
+ * supaya pengguna melihatnya dan boleh menyemak sendiri di PRPM.
+ */
+
+// Padanan huruf akhir Rumi kepada huruf akhir Jawi yang boleh diterima.
+// Varian Arab disertakan kerana §11.1 mengekalkan ejaan asal bagi istilah
+// khusus: bahas بحث guna ث untuk s, asah اصح guna ح untuk h.
+const PADANAN_AKHIR = new Map([
+  ['t', ['ت', 'ة', 'ط']],
+  ['n', ['ن']],
+  ['m', ['م']],
+  ['h', ['ه', 'ة', 'ح']],
+  ['r', ['ر']],
+  ['l', ['ل']],
+  ['s', ['س', 'ص', 'ث']],
+  ['p', ['ڤ', 'ف']],
+  ['g', ['ݢ', 'ڬ']],
+  ['k', ['ق', 'ک', 'ك', 'ء']],
+  ['d', ['د', 'ض']],
+  ['b', ['ب']],
+  ['f', ['ف']],
+  ['z', ['ز', 'ظ', 'ذ']],
+])
+
+/**
+ * Pulangkan null jika waras atau tidak dapat disemak; pulangkan butiran
+ * jika huruf akhir tidak sepadan.
+ */
+export function semakHurufAkhir(rumi, jawi) {
+  if (!rumi || !jawi) return null
+  const kata = String(rumi).trim().toLowerCase()
+  const ejaan = String(jawi).trim()
+  if (kata.includes('-') || kata.length < 3) return null
+
+  // -ng dan -ny ialah digraf; huruf akhirnya bukan penunjuk yang sah.
+  if (kata.endsWith('ng') || kata.endsWith('ny')) return null
+
+  const jangkaan = PADANAN_AKHIR.get(kata.slice(-1))
+  if (!jangkaan) return null
+
+  const akhirJawi = ejaan.slice(-1)
+  if (jangkaan.includes(akhirJawi)) return null
+
+  return {
+    kata,
+    jawi: ejaan,
+    hujungRumi: kata.slice(-1),
+    hujungJawi: akhirJawi,
+    dijangka: jangkaan,
+    sebab: 'huruf akhir Jawi tidak sepadan dengan hujung Rumi',
+  }
+}
+
+/**
+ * Bezakan ejaan Jawi LAMA daripada ejaan yang benar-benar salah.
+ *
+ * Dokumen kurikulum kerap menggunakan ortografi lama. Perbezaannya boleh
+ * dipetakan dan tidak bermakna ejaannya salah:
+ *   ف -> ڤ   (fa Arab digunakan untuk bunyi p sebelum ڤ digubal)
+ *   ج -> چ   (jim digunakan untuk bunyi c sebelum چ digubal)
+ *   ة -> ه   (ta marbutah ditukar ha pada sesetengah kata terserap)
+ *   ك -> ک   (kaf Arab lawan kaf Jawi)
+ *   ي -> ى   (ya lawan alif maqsurah)
+ *
+ * Melaporkannya sebagai "bercanggah" bersama ejaan yang betul-betul salah
+ * menenggelamkan yang penting. Ia kelas berasingan.
+ */
+const PASANGAN_LAMA = [
+  ['ف', 'ڤ'],
+  ['ج', 'چ'],
+  ['ة', 'ه'],
+  ['ك', 'ک'],
+  ['ي', 'ى'],
+  ['ݢ', 'ڬ'],
+]
+
+function samakanLama(teks) {
+  let keluar = teks
+  for (const [lama, baharu] of PASANGAN_LAMA) {
+    keluar = keluar.split(lama).join(baharu)
+  }
+  return keluar
+}
+
+/**
+ * Adakah dua ejaan berbeza HANYA pada pasangan lama/baharu yang diketahui?
+ */
+export function ejaanLamaSahaja(a, b) {
+  if (!a || !b || a === b) return false
+  return samakanLama(a) === samakanLama(b)
+}

package/src/tukar.js

@@ -12,6 +12,7 @@ import { lookup } from './prpm.js'
 import { normalisasiJawi } from './kamus.js'
 import { cariDataset, muatDataset } from './dataset.js'
 import { cariNama, mungkinAkronim, mungkinNamaKhas } from './nama.js'
+import { semakHurufAkhir } from './semak.js'
 import {
   imbuhAkhiranAn,
   imbuhAkhiranKan,
@@ -172,10 +173,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 +200,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 +217,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
 }
 
@@ -235,6 +257,7 @@ export async function keJawi(teks, cache, opts = {}) {
   const kataUlang = []
   const dijanaPedoman = []
   const akronim = []
+  const mencurigakan = []
   const bahagian = teks.split(PECAH_RUMI)
   const keluar = []
 
@@ -242,7 +265,15 @@ export async function keJawi(teks, cache, opts = {}) {
     if (i % 2 === 0) { keluar.push(cebis); continue }
 
     const rec = await lookup(cebis.toLowerCase(), cache, opts)
-    if (rec?.jawi) { keluar.push(rec.jawi); dbp.push(cebis); continue }
+    if (rec?.jawi) {
+      // PRPM sendiri kadangkala menyimpan ejaan salah pada kata kepala.
+      // Ditandakan, bukan ditolak: pengguna perlu melihatnya.
+      const curiga = semakHurufAkhir(cebis, rec.jawi)
+      if (curiga) mencurigakan.push(curiga)
+      keluar.push(rec.jawi)
+      dbp.push(cebis)
+      continue
+    }
 
     // Keadaan berbeza daripada tiada entri: DBP mengiktiraf perkataan ini
     // sebagai Melayu, cuma tidak menyimpan ejaan Jawinya. Lazim bagi nama
@@ -366,6 +397,7 @@ export async function keJawi(teks, cache, opts = {}) {
     dijanaPedoman,
     namaKhas: [...new Set(namaKhas)],
     akronim: [...new Set(akronim)],
+    mencurigakan,
     adaEntriTanpaJawi: [...new Set(adaEntriTanpaJawi)],
     belumDisahkan: [...new Set(belumDisahkan)],
     terbitanSah,