prpm-dbp 0.16.0 → 0.17.0

package/SKILL.md

@@ -9,6 +9,30 @@ Sumber kebenaran tunggal untuk ejaan BM dan Jawi ialah PRPM DBP, bukan ingatan m
 
 Model boleh hasilkan Jawi yang nampak betul tetapi salah, dan pembaca tidak dapat kesan. Skill ini tukar tekaan jadi semakan.
 
+## Prosedur wajib
+
+Ikut ini setiap kali, jangan langkau langkah.
+
+**Menulis Jawi daripada Rumi:**
+
+1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
+2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
+3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
+4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
+5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
+
+**Merumikan daripada Jawi:**
+
+1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
+2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
+3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
+4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
+5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
+
+**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
+
+Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
+
 ## 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.
@@ -160,6 +184,30 @@ Ejaan yang disimpan begini ditandakan datang daripada pengguna, bukan daripada D
 
 Bagi nama berasal Arab, ejaan Jawinya memang ejaan Arab asal, jadi ia nampak seperti dikekalkan. Bagi nama bukan Arab ia ditransliterasi penuh: `Kuala Lumpur` menjadi `کوالا لومڤور`.
 
+## Prosedur wajib
+
+Ikut ini setiap kali, jangan langkau langkah.
+
+**Menulis Jawi daripada Rumi:**
+
+1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
+2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
+3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
+4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
+5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
+
+**Merumikan daripada Jawi:**
+
+1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
+2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
+3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
+4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
+5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
+
+**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
+
+Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
+
 ## Peraturan Pedoman DBP
 
 Satu fail sahaja dalam pakej ini **menjana** ejaan dan bukan mencarinya: `src/pedoman.js`. Ia dibenarkan kerana setiap peraturan di dalamnya datang daripada *Pedoman Umum Ejaan Jawi Bahasa Melayu* terbitan DBP, dan dirujuk pada seksyennya.
@@ -271,6 +319,30 @@ Dua puluh dua kes kabur yang tinggal itu sah: `قلقله` boleh dibaca `qalqala
 
 **Sifar perkataan hilang atau rosak.**
 
+## Prosedur wajib
+
+Ikut ini setiap kali, jangan langkau langkah.
+
+**Menulis Jawi daripada Rumi:**
+
+1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
+2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
+3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
+4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
+5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
+
+**Merumikan daripada Jawi:**
+
+1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
+2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
+3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
+4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
+5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
+
+**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
+
+Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
+
 ## Peraturan yang sengaja TIDAK dilaksanakan
 
 | Seksyen | Sebab |
@@ -357,6 +429,34 @@ Empat kelas berasingan, kerana menggabungkannya menenggelamkan yang penting:
 
 Penambahan huruf vokal **tidak** dikira ejaan lama. Kalau kehadiran `ي` diabaikan, `بينا` (bina) dan `بنا` (bena) akan kelihatan sama, sedangkan itu dua perkataan berlainan.
 
+## Ejaan bukan piawai DBP
+
+Dokumen kurikulum Malaysia kerap menggunakan ortografi Jawi yang berbeza daripada piawai DBP. Pasangan yang disahkan daripada DSKP Pendidikan Islam KPM sebenar:
+
+| Rumi | DBP | DSKP | Beza |
+|---|---|---|---|
+| surah | `سورة` | `سوره` | ta marbutah jadi ha |
+| iktibar | `اعتبار` | `اعتبر` | alif digugurkan |
+| bersifat | `برصيفت` | `برصفة` | ya digugurkan, ta marbutah |
+| dalil | `دليل` | `داليل` | alif ditambah |
+| syirik | `شيريک` | `شرك` | ya digugurkan, kaf Arab |
+
+Kesemuanya berbeza hanya pada huruf vokal dan bentuk huruf, bukan pada rangka konsonan. `--rangka` memadan rangka itu:
+
+```
+$ npx prpm-dbp rumi dskp.txt --luar-talian --rangka
+ejaan bukan piawai DBP (209):
+  اعتبر -> iktibar  [DBP eja: اعتبار]
+  سوره  -> surah    [DBP eja: سورة]
+  کتب   -> kitab|katib|kutub  (rangka sama, PILIH ikut konteks)
+```
+
+Diukur pada 168 baris DSKP sebenar: token yang langsung tidak dikenali turun daripada 100 kepada 47.
+
+**Ini lapisan terakhir dan ia LOSSY.** 29% rangka dikongsi lebih daripada satu perkataan, purata 4.1 calon. Ia hanya digunakan selepas padanan tepat gagal, hasilnya sentiasa berlabel `ejaanBukanPiawai` berserta ejaan DBP untuk perbandingan, dan ia **tidak pernah memilih sendiri** apabila calon berbilang.
+
+Kegunaannya bukan menjadikan alat lebih longgar. Ia membezakan **"ini surah, cuma dieja lain"** daripada **"saya tidak kenal benda ini"** — dua keadaan yang dahulu keluar sama sebagai `«...»`.
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/bin/cli.js

@@ -38,6 +38,7 @@ Pilihan: --refresh  --had <n>  --delay <ms>  --json  --cepat
          --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)
+         --rangka        padan ejaan bukan piawai melalui rangka konsonan (berlabel)
          --pilih         pilih calon paling lazim supaya teks boleh terus dibaca;
                          setiap pilihan disenaraikan untuk disemak ikut konteks
 
@@ -58,6 +59,7 @@ function huraiArgs(argv) {
     else if (a === '--homograf') pilihan.homograf = true
     else if (a === '--konteks') pilihan.konteks = true
     else if (a === '--pilih') pilihan.pilih = true
+    else if (a === '--rangka') pilihan.rangka = 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])
@@ -226,6 +228,7 @@ async function main() {
       const h = keRumi(teks, cache, {
         dataset: await muatDataset(),
         pilihLazim: pilihan.pilih,
+        padanRangka: pilihan.rangka,
       })
       if (pilihan.json) { keluar(h); break }
       console.log(h.teks)
@@ -255,6 +258,17 @@ async function main() {
           }
         }
       }
+      if (h.ejaanBukanPiawai?.length) {
+        const tunggal = h.ejaanBukanPiawai.filter((x) => x.calon.length === 1)
+        const banyak = h.ejaanBukanPiawai.filter((x) => x.calon.length > 1)
+        console.error(`\nejaan bukan piawai DBP (${h.ejaanBukanPiawai.length}):`)
+        for (const x of tunggal.slice(0, 20)) {
+          console.error(`  ${x.jawi} -> ${x.calon[0].rumi}  [DBP eja: ${x.calon[0].jawiDbp}]`)
+        }
+        for (const x of banyak.slice(0, 10)) {
+          console.error(`  ${x.jawi} -> ${x.calon.map((c) => c.rumi).join('|')}  (rangka sama, PILIH ikut konteks)`)
+        }
+      }
       if (h.arab.length) console.error(`teks Arab dibiarkan (${h.arab.length}): ${h.arab.join(' ')}`)
       for (const k of h.kabur) {
         console.error(

package/package.json

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

@@ -127,10 +127,43 @@ export async function loadCache() {
   }
 }
 
+/**
+ * Simpan cache dengan MENGGABUNGKAN keadaan di cakera terlebih dahulu.
+ *
+ * Menulis ganti secara membuta memusnahkan kerja proses lain. Dua sesi yang
+ * berjalan serentak akan memuat keadaan yang sama, masing-masing menambah
+ * perkataannya, dan yang menyimpan kemudian memadam tambahan yang awal.
+ * Ia diperhatikan secara langsung: entri yang baru dipanaskan hilang selepas
+ * sesi lain menyimpan.
+ *
+ * Rekod di cakera menang bagi kunci yang sama, kerana ia mungkin lebih baharu.
+ * Rekod benih (`ringkas`) tidak pernah menewaskan rekod penuh.
+ */
 export async function saveCache(cache) {
   await mkdir(dirname(CACHE_PATH), { recursive: true })
+
+  let diCakera = {}
+  try {
+    diCakera = JSON.parse(await readFile(CACHE_PATH, 'utf8'))
+  } catch {
+    diCakera = {}
+  }
+
+  const gabung = { ...cache }
+  for (const [kata, rec] of Object.entries(diCakera)) {
+    const sedia = gabung[kata]
+    // Rekod penuh mengatasi rekod ringkas; selain itu cakera menang.
+    if (sedia && !sedia.ringkas && rec.ringkas) continue
+    gabung[kata] = rec
+  }
+
+  // Rekod benih tidak ditulis ke cache pengguna: ia sudah ada dalam pakej.
+  for (const [kata, rec] of Object.entries(gabung)) {
+    if (rec?.benih) delete gabung[kata]
+  }
+
   const tmp = `${CACHE_PATH}.tmp`
-  await writeFile(tmp, JSON.stringify(cache, null, 1), 'utf8')
+  await writeFile(tmp, JSON.stringify(gabung, null, 1), 'utf8')
   await rename(tmp, CACHE_PATH)
 }
 

package/src/semak.js

@@ -102,3 +102,53 @@ export function ejaanLamaSahaja(a, b) {
   if (!a || !b || a === b) return false
   return samakanLama(a) === samakanLama(b)
 }
+
+/**
+ * Rangka konsonan: buang huruf vokal pilihan dan samakan varian bentuk.
+ *
+ * Dokumen kurikulum Malaysia kerap menggunakan ejaan Jawi yang berbeza
+ * daripada piawai DBP. Corak yang disahkan pada pasangan sebenar DSKP:
+ *
+ *   surah     DBP سورة   DSKP سوره    ta marbutah jadi ha
+ *   iktibar   DBP اعتبار DSKP اعتبر   alif digugurkan
+ *   bersifat  DBP برصيفت DSKP برصفة   ya digugurkan, ta marbutah
+ *   dalil     DBP دليل   DSKP داليل   alif ditambah
+ *   syirik    DBP شيريک  DSKP شرك     ya digugurkan, kaf Arab
+ *
+ * Kesemuanya berbeza hanya pada huruf vokal dan bentuk huruf, bukan pada
+ * rangka konsonan. Membuang vokal menjadikan kedua-dua ejaan sepadan.
+ *
+ * INI LOSSY dan MESTI kekal di bawah lapisan 1 dan 2. Banyak perkataan
+ * berkongsi rangka yang sama, jadi padanan begini adalah inferens, bukan
+ * rekod DBP, dan hasilnya mesti berlabel.
+ */
+const VOKAL_PILIHAN = /[اويى]/g
+
+const SAMA_BENTUK = new Map([
+  ['ة', 'ه'],
+  ['ك', 'ک'],
+  ['ڬ', 'ݢ'],
+  ['ف', 'ڤ'],
+  ['ج', 'چ'],
+  ['أ', 'ا'],
+  ['إ', 'ا'],
+  ['ء', ''],
+])
+
+// Pedoman §6.4: ta marbutah melambangkan [t] ATAU [h] sebagai kelainan
+// sebutan pada kata serapan Arab (akibat/akibah, hidayat/hidayah). Ketiga-tiga
+// huruf itu boleh bertukar di HUJUNG kata sahaja. Di tengah kata ia huruf
+// berlainan dan tidak boleh dilipat.
+const HUJUNG_SETARA = new Set(['ة', 'ه', 'ت'])
+
+export function rangkaKonsonan(jawi) {
+  if (!jawi) return ''
+  let keluar = ''
+  for (const huruf of String(jawi).normalize('NFC')) {
+    const ganti = SAMA_BENTUK.has(huruf) ? SAMA_BENTUK.get(huruf) : huruf
+    keluar += ganti
+  }
+  keluar = keluar.replace(VOKAL_PILIHAN, '').replace(/\s+/g, '')
+  if (keluar && HUJUNG_SETARA.has(keluar.slice(-1))) keluar = keluar.slice(0, -1) + 'ه'
+  return keluar
+}

package/src/tukar.js

@@ -12,7 +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 { rangkaKonsonan, semakHurufAkhir } from './semak.js'
 import {
   imbuhAkhiranAn,
   imbuhAkhiranKan,
@@ -162,6 +162,33 @@ export async function cariDasar(kata, cache, opts = {}) {
  * bilangan perkataan terpanjang supaya pembacaan songsang boleh memadan
  * jujukan, bukan token tunggal sahaja.
  */
+/**
+ * Indeks rangka konsonan, untuk memadan ejaan bukan piawai.
+ *
+ * Dokumen kurikulum Malaysia kerap menggunakan ortografi yang berbeza
+ * daripada DBP: vokal digugur atau ditambah, ta marbutah bertukar ha, bentuk
+ * Arab menggantikan bentuk Jawi Melayu. Indeks ini memadan rangka konsonan
+ * supaya `سوره` masih dikenali sebagai `surah`.
+ *
+ * LOSSY: 29% rangka dikongsi lebih daripada satu perkataan, purata 4.1 calon.
+ * Kerana itu ia hanya digunakan selepas padanan tepat gagal, hasilnya sentiasa
+ * berlabel, dan ia TIDAK PERNAH memilih sendiri apabila calon berbilang.
+ */
+export function petaRangka(cache, dataset = null) {
+  const peta = new Map()
+  const tambah = (jawi, rumi) => {
+    const kunci = rangkaKonsonan(jawi)
+    if (!kunci) return
+    if (!peta.has(kunci)) peta.set(kunci, new Map())
+    if (!peta.get(kunci).has(rumi)) peta.get(kunci).set(rumi, jawi)
+  }
+  for (const rec of Object.values(cache)) if (rec?.jawi) tambah(rec.jawi, rec.kata)
+  for (const [rumi, ejaan] of Object.entries(dataset?.peta ?? {})) {
+    for (const j of ejaan) tambah(j, rumi)
+  }
+  return peta
+}
+
 export function petaSongsang(cache, dataset = null) {
   const peta = new Map()
   let maxKata = 1
@@ -428,13 +455,15 @@ export async function keJawi(teks, cache, opts = {}) {
 export function keRumi(
   teksJawi,
   cache,
-  { penanda = ['«', '»'], dataset = null, pilihLazim = false } = {},
+  { penanda = ['«', '»'], dataset = null, pilihLazim = false, padanRangka = false } = {},
 ) {
   const peta = petaSongsang(cache, dataset)
   const tidakDikenali = []
   const kabur = []
   const arab = []
   const sendiDipisah = []
+  const bukanPiawai = []
+  const rangka = padanRangka ? petaRangka(cache, dataset) : null
   const bahagian = teksJawi.split(PECAH_JAWI)
   const keluar = []
 
@@ -491,6 +520,22 @@ export function keRumi(
       }
       if (dipisah) { keluar.push(dipisah); sendiDipisah.push(bahagian[i]); continue }
 
+      // Lapisan terakhir: ejaan bukan piawai. Berlabel, di bawah lapisan
+      // 1 dan 2, dan tidak pernah memilih sendiri apabila calon berbilang.
+      if (rangka) {
+        const padananRangka = rangka.get(rangkaKonsonan(bahagian[i]))
+        if (padananRangka?.size) {
+          const senarai = [...padananRangka.entries()].map(([rumi, jawiDbp]) => ({ rumi, jawiDbp }))
+          bukanPiawai.push({ jawi: bahagian[i], calon: senarai })
+          if (senarai.length === 1) {
+            keluar.push(senarai[0].rumi)
+            continue
+          }
+          keluar.push(penanda[0] + senarai.map((x) => x.rumi).join('|') + penanda[1])
+          continue
+        }
+      }
+
       tidakDikenali.push(bahagian[i])
       keluar.push(penanda[0] + bahagian[i] + penanda[1])
       continue
@@ -521,6 +566,7 @@ export function keRumi(
     kabur,
     arab: [...new Set(arab)],
     sendiDipisah,
+    ejaanBukanPiawai: bukanPiawai,
     saizPeta: peta.size,
     lengkap: tidakDikenali.length === 0,
   }