prpm-dbp 0.4.0 → 0.5.1

package/SKILL.md

@@ -116,6 +116,40 @@ 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 `کوالا لومڤور`.
 
+## 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.
+
+**§14.1 — kata sendi `di` dan `ke` ditulis sebagai satu kata dengan kata yang mengikutinya.**
+
+```
+di Mekah   ->  دمکة      bukan  د مکة
+ke sekolah ->  کسکوله    bukan  ک سکوله
+```
+
+Nota seksyen yang sama: jika kata berikutnya bermula dengan alif, hamzah dibubuh di atas alif itu. `di Asrama` menjadi `دأسراما`, bukan `داسراما`.
+
+Kodpoint hamzah (U+0623) disahkan secara empirik daripada dataset, bukan diandaikan: `abai` bermula `ا` U+0627, `diabaikan` bermula `د` + `أ` U+0623. Corak sama pada `diambil`, `diajar`, `diurus`.
+
+Bentuk bercantum tidak wujud sebagai entri kamus, jadi pembacaan songsang memisahkannya semula dan memulihkan hamzah kepada alif. Peraturan ini simetri.
+
+Kata sendi **tidak** dicantum apabila kata berikutnya belum disahkan, kerana hasilnya akan menjadi Jawi bercantum dengan teks Rumi bertanda.
+
+**§11 — kata serapan Arab, dua peringkat:**
+
+| Seksyen | Jenis | Cara eja | Contoh |
+|---|---|---|---|
+| §11.1 | istilah khusus | ikut ejaan asal Arab | `wuduk`, `Qur'an`, `sunah`, `hadis`, `tayamum` |
+| §11.2 | kata umum yang sudah terserap | ikut kaedah kata jati Melayu | `sabun` |
+
+Pakej tidak perlu memilih antara dua ini. DBP sudah memilih, dan pilihan itu terkandung dalam ejaan yang dipulangkan PRPM. Ia didokumenkan supaya tiada siapa "membetulkan" `صلاة` kepada ejaan fonetik Melayu kemudian hari.
+
+**§11.6 — alif maqsurah dikekalkan.** `takwa` تقوى, `fatwa` فتوى, `Musa`, `Isa`. Ia diganti dengan alif hanya apabila dibentuk kata terbitan: `ketakwaan`, `memfatwakan`, `pendakwaan`. Perbezaan itu membawa maklumat, jadi `ى` **tidak pernah dilipat** semasa perbandingan. Melipatnya akan membuat `تقوي` yang salah dibandingkan sama dengan `تقوى` yang betul.
+
+**§10 — enam belas perkataan dikecualikan daripada aturan pola:** `ada`, `apa`, `beta`, `bin`, `binti`, `dari`, `daripada`, `ini`, `itu`, `jika`, `kepada`, `kita`, `lima`, `maka`, `pada`, `demikian`. Ejaannya mesti datang daripada kamus dan tidak boleh dibetulkan oleh mana-mana peraturan pola.
+
+**§17.1 — kata ulang penuh menggunakan angka dua Arab `٢`**, bukan sempang: `rama-rama` menjadi `رام٢`. Sempang digunakan hanya apabila bahagian yang diulang berubah bentuk (§17.2).
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/package.json

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

package/src/kamus.js

@@ -187,8 +187,7 @@ export async function cariKamus(kata, { timeout = 25000 } = {}) {
 const LIPATAN = new Map([
   ['ك', 'ک'], // ك Arabic Kaf   -> ک Keheh
   ['ڪ', 'ک'], // ڪ Swash Kaf    -> ک Keheh
-  ['ی', 'ي'], // ی Farsi Yeh    -> ي Arabic Yeh
-  ['ى', 'ي'], // ى Alef Maksura -> ي Arabic Yeh
+  ['ی', 'ي'], // ی Farsi Yeh    -> ي Arabic Yeh (varian bentuk semata-mata)
   ['ڬ', 'ݢ'], // ڬ Gaf varian   -> ݢ Gaf Jawi Melayu
   ['ە', 'ه'], // ە Ae           -> ه Ha
   ['ہ', 'ه'], // ہ Heh Goal     -> ه Ha
@@ -204,6 +203,14 @@ export function normalisasiJawi(teks) {
     .trim()
 }
 
+// SENGAJA TIDAK DILIPAT: ى (U+0649, alif maqsurah) kepada ي (U+064A).
+// Pedoman DBP §11.6: alif maqsurah dalam ejaan asal Arab DIKEKALKAN dalam
+// ejaan Jawi — takwa تقوى, fatwa فتوى, Musa, Isa. Melipatnya akan membuat
+// تقوي (salah) dibandingkan sama dengan تقوى (betul), lalu menyembunyikan
+// kesilapan sebenar. §11.6 juga menyatakan huruf itu diganti dengan alif
+// apabila dibentuk kata terbitan (ketakwaan, memfatwakan), jadi perbezaan
+// itu memang membawa maklumat.
+
 // SENGAJA TIDAK DILIPAT: پ (U+067E, pe Parsi) kepada ڽ (U+06BD, nya).
 // Sesetengah enjin transliterasi negeri mengeluarkan پ di tempat ڽ, tetapi
 // itu huruf yang SALAH, bukan varian bentuk. Melipatnya akan menyembunyikan

package/src/pedoman.js

@@ -0,0 +1,112 @@
+/**
+ * Peraturan daripada Pedoman Umum Ejaan Jawi Bahasa Melayu (DBP).
+ *
+ * Ini satu-satunya tempat dalam pakej yang MENJANA ejaan dan bukan sekadar
+ * mencarinya. Ia dibenarkan kerana setiap peraturan di sini datang daripada
+ * dokumen rasmi DBP dan dirujuk pada seksyennya, bukan direka.
+ *
+ * Sumber: Pedoman Umum Ejaan Jawi Bahasa Melayu, Dewan Bahasa dan Pustaka.
+ * Berasaskan Pedoman Ejaan Jawi yang Disempurnakan (1986, ed. 3 1993),
+ * hasil Konvensyen Tulisan Jawi Peringkat Kebangsaan 1984, diselaraskan
+ * 1991 dan 1993, disahkan Jawatankuasa Teknikal Ejaan Jawi 1993-1994.
+ */
+
+const ALIF = 'ا' // ا
+const ALIF_HAMZAH = 'أ' // أ
+
+/**
+ * §14.1 — Kata sendi nama `di` dan `ke` ditulis sebagai SATU KATA dengan
+ * kata yang mengikutinya.
+ *
+ * Nota §14.1: jika kata yang mengikutinya bermula dengan huruf alif, huruf
+ * hamzah dibubuh di atas alif itu.
+ *
+ * Kodpoint hamzah disahkan secara empirik daripada dataset, bukan diandaikan:
+ *   abai      ا U+0627 ...
+ *   diabaikan د + أ U+0623 ...
+ * Corak sama pada diambil, diajar, diurus.
+ */
+export const KATA_SENDI = new Map([
+  ['di', 'د'], // د
+  ['ke', 'ک'], // ک
+])
+
+export function bolehCantumSendi(kata) {
+  return KATA_SENDI.has(String(kata).toLowerCase())
+}
+
+/**
+ * Cantumkan kata sendi dengan ejaan Jawi kata yang mengikutinya.
+ * Pulangkan null jika kata itu bukan kata sendi yang dicakupi.
+ */
+export function cantumSendi(kataSendi, jawiSelepas) {
+  const awalan = KATA_SENDI.get(String(kataSendi).toLowerCase())
+  if (!awalan || !jawiSelepas) return null
+
+  const selepas = jawiSelepas.startsWith(ALIF)
+    ? ALIF_HAMZAH + jawiSelepas.slice(ALIF.length)
+    : jawiSelepas
+
+  return { jawi: awalan + selepas, rujukan: 'Pedoman DBP §14.1' }
+}
+
+/**
+ * §11 — Kata serapan Arab dieja dalam dua cara berbeza:
+ *   §11.1 istilah khusus  -> ikut ejaan asal bahasa Arab (wuduk, Qur'an,
+ *                            sunah, hadis, tayamum, wuquf, reda)
+ *   §11.2 kata umum yang  -> ikut cara mengeja kata jati Melayu (sabun)
+ *         sudah terserap
+ *
+ * Pakej ini tidak perlu memilih antara dua ini: DBP sudah memilih, dan
+ * pilihan itu terkandung dalam ejaan yang dipulangkan PRPM. Peraturan ini
+ * didokumenkan di sini supaya tiada siapa "membetulkan" صلاة kepada ejaan
+ * fonetik Melayu kemudian hari.
+ */
+export const NOTA_SERAPAN_ARAB = 'Pedoman DBP §11.1 dan §11.2'
+
+/**
+ * Songsangan §14.1: pisahkan kata sendi yang bercantum.
+ *
+ * Bentuk bercantum seperti دمکة tidak wujud sebagai entri kamus, jadi
+ * pembacaan songsang mesti mencubanya sendiri. Hamzah dipulihkan kepada
+ * alif kerana hamzah itu ditambah oleh peraturan, bukan sebahagian ejaan
+ * kata dasar.
+ */
+export function pisahSendi(jawi) {
+  const calon = []
+  for (const [rumi, awalan] of KATA_SENDI) {
+    if (!jawi.startsWith(awalan) || jawi.length <= awalan.length) continue
+    let baki = jawi.slice(awalan.length)
+    if (baki.startsWith(ALIF_HAMZAH)) baki = ALIF + baki.slice(ALIF_HAMZAH.length)
+    calon.push({ sendi: rumi, baki, rujukan: 'Pedoman DBP §14.1' })
+  }
+  return calon
+}
+
+/**
+ * §10 — Senarai perkataan yang dikecualikan daripada beberapa aturan
+ * pengejaan biasa. Ejaannya tidak menurut pola suku kata, jadi ia mesti
+ * datang daripada kamus dan tidak boleh "dibetulkan" oleh mana-mana
+ * peraturan pola.
+ */
+export const KECUALI_POLA = new Set([
+  'ada', 'apa', 'beta', 'bin', 'binti', 'dari', 'daripada', 'ini', 'itu',
+  'jika', 'kepada', 'kita', 'lima', 'maka', 'pada', 'demikian',
+])
+
+/**
+ * §17.1 — Kata ulang penuh ditulis dengan tanda angka dua Arab (٢),
+ * bukan dengan sempang seperti dalam Rumi.
+ *   rama-rama -> رام٢
+ * §17.2 — Apabila bahagian yang diulang berubah bentuk (kata ulang
+ * berimbuhan atau berentak), tanda sempang digunakan.
+ */
+export const ANGKA_DUA = '\u0662'
+
+/**
+ * §11.6 — Alif maqsurah dalam ejaan asal Arab dikekalkan (takwa تقوى,
+ * fatwa فتوى, Musa, Isa), TETAPI diganti dengan alif apabila dibentuk kata
+ * terbitan dengan akhiran atau partikel (ketakwaan, memfatwakan,
+ * pendakwaan). Kerana itu ia tidak boleh dilipat semasa perbandingan.
+ */
+export const NOTA_MAQSURAH = 'Pedoman DBP §11.6'

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, mungkinNamaKhas } from './nama.js'
+import { bolehCantumSendi, cantumSendi, pisahSendi } from './pedoman.js'
 
 // Baris tanda vokal Arab (fathah, kasrah, dammah, sukun, syaddah, tanwin,
 // alef superscript). Jawi Melayu TIDAK menggunakannya; teks al-Quran dan
@@ -185,8 +186,27 @@ export async function keJawi(teks, cache, opts = {}) {
     keluar.push(penanda[0] + cebis + penanda[1])
   }
 
+  // Pedoman DBP §14.1: kata sendi di dan ke bercantum dengan kata berikutnya.
+  // Dibuat sebagai lulusan kedua supaya logik carian di atas kekal mudah.
+  const sendiDicantum = []
+  for (let k = 1; k < keluar.length - 2; k += 2) {
+    const asal = bahagian[k]
+    if (!bolehCantumSendi(asal)) continue
+    if (!/^\s+$/.test(keluar[k + 1])) continue
+    const seterusnya = keluar[k + 2]
+    // Hanya cantum bila kata berikutnya benar-benar bertukar, bukan ditanda.
+    if (!seterusnya || seterusnya.startsWith(penanda[0])) continue
+    const gabung = cantumSendi(asal, seterusnya)
+    if (!gabung) continue
+    sendiDicantum.push({ sendi: asal, jawi: gabung.jawi, rujukan: gabung.rujukan })
+    keluar[k] = gabung.jawi
+    keluar[k + 1] = ''
+    keluar[k + 2] = ''
+  }
+
   return {
     teks: keluar.join(''),
+    sendiDicantum,
     disahkanDbp: dbp.length,
     dariDataset,
     dariNama,
@@ -212,6 +232,7 @@ export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null
   const tidakDikenali = []
   const kabur = []
   const arab = []
+  const sendiDipisah = []
   const bahagian = teksJawi.split(PECAH_JAWI)
   const keluar = []
 
@@ -249,6 +270,15 @@ export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null
     }
 
     if (!padanan) {
+      // Pedoman DBP §14.1 songsang: bentuk bercantum seperti دمکة tiada
+      // dalam kamus, jadi cuba pisahkan kata sendi di hadapan.
+      let dipisah = null
+      for (const calon of pisahSendi(bahagian[i])) {
+        const jumpa = peta.get(normalisasiJawi(calon.baki))
+        if (jumpa?.length === 1) { dipisah = calon.sendi + ' ' + jumpa[0]; break }
+      }
+      if (dipisah) { keluar.push(dipisah); sendiDipisah.push(bahagian[i]); continue }
+
       tidakDikenali.push(bahagian[i])
       keluar.push(penanda[0] + bahagian[i] + penanda[1])
       continue
@@ -267,6 +297,7 @@ export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null
     tidakDikenali: [...new Set(tidakDikenali)],
     kabur,
     arab: [...new Set(arab)],
+    sendiDipisah,
     saizPeta: peta.size,
     lengkap: tidakDikenali.length === 0,
   }