prpm-dbp 0.13.2 → 0.15.0

package/README.md

@@ -132,7 +132,9 @@ Pengguna kemudian menarik versi baharu dengan `npx skills update`.
 | `banding <kata...>` | silang semak PRPM lawan KamusDBP |
 | `cache` | status cache, `--buang <kata>` untuk padam satu |
 
-Pilihan: `--refresh`, `--had <n>`, `--delay <ms>`, `--json`, `--cepat`, `--pedoman`.
+Pilihan: `--refresh`, `--had <n>`, `--delay <ms>`, `--json`, `--cepat`, `--pedoman`, `--luar-talian`, `--homograf`, `--konteks`.
+
+Merumikan ialah keputusan peringkat ayat, bukan peringkat perkataan. `مڠيکوت` ialah ejaan sah bagi `mengikut` dan `mengekot` sekali gus, kedua-duanya entri PRPM sebenar. Gunakan `--konteks` supaya ayat dan makna setiap calon dipaparkan bersama, berserta bilangan rujukan korpus DBP yang mengisih calon lazim ke hadapan.
 
 `--luar-talian` tidak pernah menyentuh rangkaian. Wajib untuk laluan permintaan aplikasi: dokumen penuh dari cache mengambil 0.19 saat, manakala satu perkataan baharu daripada PRPM mengambil beberapa saat.
 

package/SKILL.md

@@ -13,6 +13,23 @@ Model boleh hasilkan Jawi yang nampak betul tetapi salah, dan pembaca tidak dapa
 
 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.
+
+0d. **Merumikan ialah keputusan peringkat AYAT, bukan peringkat perkataan.** Jangan tukar token demi token dan anggap ia selesai. Ejaan Jawi menggunakan empat huruf vokal berbanding enam dalam Rumi, jadi satu ejaan kerap membawa lebih daripada satu bacaan sah. `مڠيکوت` ialah `mengikut` **dan** `mengekot`, dua-duanya entri PRPM sebenar dengan sebutan sendiri. Kamus mengesahkan kedua-duanya wujud; hanya ayat menentukan yang mana dimaksudkan.
+
+   Gunakan `--konteks` supaya ayat dan makna setiap calon dipaparkan bersama:
+
+   ```
+   مڠيکوت  ->  mengikut  atau  mengekot
+     ayat: itu mengikut|mengekot sukatan pelajaran.
+       mengikut    2439 rujukan  pergi bersama-sama dgn, menurut, mengiring
+       mengekot       6 rujukan  merapatkan paha dan tangan ke badan
+   ```
+
+   Bilangan rujukan itu datang daripada panel korpus DBP sendiri, bukan anggaran. Ia **mengisih** calon supaya yang lazim dilihat dahulu; ia **tidak memilih**. Perkataan jarang tetap betul apabila ayat menghendakinya.
+
 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).
@@ -308,6 +325,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

@@ -37,6 +37,7 @@ Pilihan: --refresh  --had <n>  --delay <ms>  --json  --cepat
          --pedoman       jana imbuhan ikut peraturan DBP (88-98% tepat, hasil ditanda)
          --luar-talian   jangan sentuh rangkaian langsung (wajib untuk laluan permintaan app)
          --homograf      tandakan perkataan yang ejaan Jawinya dikongsi perkataan lain
+         --konteks       papar ayat dan makna setiap calon bagi kekaburan (rumi)
 
 Cache: ${CACHE_PATH}
 `
@@ -53,6 +54,7 @@ function huraiArgs(argv) {
     else if (a === '--pedoman') pilihan.pedoman = true
     else if (a === '--luar-talian') pilihan.luarTalian = true
     else if (a === '--homograf') pilihan.homograf = true
+    else if (a === '--konteks') pilihan.konteks = true
     else if (a === '--jenis') pilihan.jenis = argv[++i]
     else if (a === '--had') pilihan.had = Number(argv[++i])
     else if (a === '--delay') pilihan.delay = Number(argv[++i])
@@ -186,6 +188,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}): ` +
@@ -219,6 +227,28 @@ async function main() {
       if (h.tidakDikenali.length) {
         console.error(`tidak dikenali (${h.tidakDikenali.length}): ${h.tidakDikenali.join(', ')}`)
       }
+      if (pilihan.konteks && h.kabur.length) {
+        // Kekaburan hanya boleh diselesaikan oleh ayat, bukan oleh kamus.
+        // Papar ayat penuh berserta makna setiap calon supaya keputusan
+        // itu boleh dibuat tanpa membuka PRPM satu per satu.
+        const ayat = h.teks.split(/(?<=[.!?])\s+/)
+        console.error('\n--- konteks untuk kekaburan ---')
+        for (const k of h.kabur) {
+          const pilihanTeks = k.calon.join('|')
+          const induk = ayat.find((a) => a.includes(pilihanTeks)) ?? ''
+          console.error(`\n${k.jawi}  ->  ${k.calon.join('  atau  ')}`)
+          if (induk) console.error(`  ayat: ${induk.trim()}`)
+          for (const c of k.calon) {
+            const rec = cache[c]
+            const def = (rec?.entri?.[0]?.definisi ?? '').slice(0, 70)
+            const kerap = rec?.rujukanKorpus
+            console.error(
+              `    ${c.padEnd(12)} ${kerap != null ? String(kerap).padStart(5) + ' rujukan' : '     kekerapan tidak diketahui'}` +
+                (def ? `  ${def}` : ''),
+            )
+          }
+        }
+      }
       if (h.arab.length) console.error(`teks Arab dibiarkan (${h.arab.length}): ${h.arab.join(' ')}`)
       for (const k of h.kabur) console.error(`kabur: ${k.jawi} -> ${k.calon.join(', ')}`)
       break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prpm-dbp",
-  "version": "0.13.2",
+  "version": "0.15.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

@@ -34,6 +34,15 @@ const DEFINISI = /<b>Definisi\s*:\s*<\/b>([\s\S]*?)(?=<b>\(|$)/
 const SUMBER = /<b>\(([^)]+)\)<\/b>/
 const TIADA_TESAURUS = /Tiada maklumat tesaurus untuk kata/
 
+// Panel "Juga ditemukan dalam" menyenaraikan bilangan rujukan perkataan itu
+// dalam setiap korpus DBP. Jumlahnya ialah isyarat kekerapan yang BERSUMBER,
+// bukan tekaan: mengikut 2439 rujukan berbanding mengekot 6.
+//
+// Digunakan untuk MENGISIH calon yang kabur, bukan untuk memilih. Perkataan
+// jarang tetap betul apabila ayat menghendakinya.
+const PANEL_KORPUS = /Juga ditemukan dalam:([\s\S]*?)Perkhidmatan/
+const KIRAAN_KORPUS = /<i>\((\d+)\)<\/i>/g
+
 const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', '#39': "'", nbsp: ' ' }
 
 export function stripTags(raw) {
@@ -65,11 +74,17 @@ export function parse(kata, page) {
     })
   }
 
+  const panel = page.match(PANEL_KORPUS)
+  const rujukanKorpus = panel
+    ? [...panel[1].matchAll(KIRAAN_KORPUS)].reduce((jum, m) => jum + Number(m[1]), 0)
+    : null
+
   const semuaJawi = entri.map((e) => e.jawi).filter(Boolean)
   const unik = [...new Set(semuaJawi)]
   return {
     kata,
     dijumpai: entri.length > 0,
+    rujukanKorpus,
     jawi: unik[0] ?? null,
     jawiVarian: unik.slice(1),
     entri,
@@ -252,18 +267,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,
@@ -225,10 +226,21 @@ export function petaSongsang(cache, dataset = null) {
  * Apabila tiada calon lapisan 1, calon yang belum diketahui digunakan dan
  * sumbernya dilabel, tidak dipulangkan secara senyap.
  */
-export function pilihCalon(masuk) {
+export function pilihCalon(masuk, cache = null) {
   if (!masuk) return null
   if (Array.isArray(masuk)) return { calon: masuk, sumber: 'campur' }
-  if (masuk.layak?.length) return { calon: masuk.layak, sumber: 'dbp' }
+
+  // Isih ikut kekerapan korpus DBP apabila diketahui: calon yang lebih
+  // lazim didahulukan supaya pembaca melihatnya dahulu. Ini MENGISIH,
+  // bukan memilih; semua calon tetap dipulangkan.
+  const isih = (senarai) => {
+    if (!cache || senarai.length < 2) return senarai
+    return [...senarai].sort(
+      (a, b) => (cache[b]?.rujukanKorpus ?? 0) - (cache[a]?.rujukanKorpus ?? 0),
+    )
+  }
+
+  if (masuk.layak?.length) return { calon: isih(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
@@ -256,6 +268,7 @@ export async function keJawi(teks, cache, opts = {}) {
   const kataUlang = []
   const dijanaPedoman = []
   const akronim = []
+  const mencurigakan = []
   const bahagian = teks.split(PECAH_RUMI)
   const keluar = []
 
@@ -263,7 +276,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
@@ -387,6 +408,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,
@@ -441,7 +463,7 @@ export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null
       }
       if (!bolehGabung) continue
       const frasa = bahagian.slice(i, akhir + 1).join(' ').replace(/\s+/g, ' ')
-      const jumpa = pilihCalon(peta.get(normalisasiJawi(frasa)))
+      const jumpa = pilihCalon(peta.get(normalisasiJawi(frasa)), cache)
       if (jumpa) { padanan = jumpa.calon; hujung = akhir; break }
     }