prpm-dbp 0.3.0 → 0.5.0

package/README.md

@@ -128,6 +128,7 @@ Pengguna kemudian menarik versi baharu dengan `npx skills update`.
 | `jawi <fail>` | tukar teks Rumi ke Jawi ikut ejaan DBP |
 | `rumi <fail>` | tukar teks Jawi ke Rumi dari cache |
 | `import-tsv <fail>` | import dataset rumi/jawi tambahan |
+| `nama <rumi> <jawi>` | sahkan satu nama khas |
 | `banding <kata...>` | silang semak PRPM lawan KamusDBP |
 | `cache` | status cache, `--buang <kata>` untuk padam satu |
 

package/SKILL.md

@@ -91,6 +91,59 @@ Sesetengah entri memulangkan **dua perkataan Jawi untuk satu perkataan Rumi**: `
 
 **Teks Arab yang dipetik dibiarkan sepenuhnya.** Jawi Melayu tidak menggunakan baris tanda vokal, jadi kehadiran fathah, kasrah, dammah, sukun atau tanwin bermakna potongan itu Arab, bukan Jawi. Ayat al-Quran dan hadis dalam dokumen Melayu lulus tanpa disentuh dan dilaporkan dalam medan `arab`.
 
+## Nama khas
+
+Diuji terhadap PRPM: **nama tokoh dan nama surah tiada sumber berwibawa.** `muhammad`, `ibrahim`, `musa`, `umar`, `aisyah`, `khadijah` semuanya tiada entri. Nama surah seperti `fatihah`, `baqarah`, `yasin` ada entri tetapi tanpa ejaan Jawi. Dataset komuniti meliputi nama tempat (`mekah` مکة, `mesir` مسير, `pahang` ڤاهڠ) tetapi bukan nama orang.
+
+Alat ini **tidak mereka ejaan nama**. Sebaliknya:
+
+- Perkataan berhuruf besar di **tengah** ayat dikira nama khas dan dilaporkan dalam medan `namaKhas`, berasingan daripada `belumDisahkan`. Nama bukan salah eja.
+- Sahkan sekali, guna selamanya:
+
+```bash
+npx prpm-dbp nama Muhammad <ejaan-jawi>
+npx prpm-dbp nama          # senaraikan yang sudah disahkan
+```
+
+Ejaan yang disimpan begini ditandakan datang daripada pengguna, bukan daripada DBP. Sahkan dengan guru atau rujukan bertulis dahulu.
+
+**Jangan keliru antara dua benda:**
+
+| | Layanan |
+|---|---|
+| Petikan bahasa Arab (ayat, doa, hadis) | kekal Arab, tidak disentuh |
+| Nama khas dalam ayat Melayu | **ditulis dalam Jawi**, bukan dikekalkan |
+
+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.
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/bin/cli.js

@@ -6,6 +6,7 @@ import { pasangSkill } from '../src/install.js'
 import { banding, cariKamus } from '../src/kamus.js'
 import { keJawi, keRumi } from '../src/tukar.js'
 import { huraiTsv, muatDataset, simpanDataset } from '../src/dataset.js'
+import { NAMA_PATH, muatNama, tambahNama } from '../src/nama.js'
 import {
   CACHE_PATH,
   auditJawi,
@@ -26,6 +27,8 @@ const BANTUAN = `prpm-dbp — semak Bahasa Melayu dan Jawi terhadap PRPM DBP
   npx prpm-dbp jawi <fail.txt>           tukar teks Rumi ke Jawi ikut ejaan DBP
   npx prpm-dbp rumi <fail.txt>           tukar teks Jawi ke Rumi dari cache
   npx prpm-dbp import-tsv <fail.tsv>     import dataset rumi<TAB>jawi (dilabel bukan DBP)
+  npx prpm-dbp nama <rumi> <jawi>        sahkan satu nama khas (tokoh, surah, tempat)
+  npx prpm-dbp nama                      senaraikan nama khas yang disahkan
   npx prpm-dbp banding <kata...>         silang semak PRPM lawan KamusDBP
   npx prpm-dbp cache [--buang <kata>]    status cache
   npx prpm-dbp install [--link]          pasang sebagai Claude Code skill
@@ -160,6 +163,12 @@ async function main() {
             h.adaEntriTanpaJawi.join(', '),
         )
       }
+      if (h.namaKhas.length) {
+        console.error(
+          `nama khas belum disahkan (${h.namaKhas.length}): ${h.namaKhas.join(', ')}\n` +
+            `  sahkan dengan: npx prpm-dbp nama <rumi> <jawi>`,
+        )
+      }
       if (h.terbitanSah.length) {
         console.error(
           `terbitan sah tanpa ejaan Jawi (${h.terbitanSah.length}): ` +
@@ -183,6 +192,17 @@ async function main() {
       break
     }
 
+    case 'nama': {
+      if (baki.length >= 2) {
+        const rec = await tambahNama(baki[0], baki[1], { jenis: pilihan.jenis ?? null })
+        keluar({ disimpan: rec, fail: NAMA_PATH, nota: 'Ejaan ini datang dari anda, bukan dari DBP.' })
+        break
+      }
+      const peta = await muatNama()
+      keluar({ fail: NAMA_PATH, jumlah: Object.keys(peta).length, nama: peta })
+      break
+    }
+
     case 'import-tsv': {
       if (!baki[0]) throw new Error('perlu fail TSV: rumi<TAB>jawi setiap baris')
       const { peta, dilangkau, jumlah } = huraiTsv(await readFile(baki[0], 'utf8'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prpm-dbp",
-  "version": "0.3.0",
+  "version": "0.5.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/nama.js

@@ -0,0 +1,70 @@
+/**
+ * Simpanan nama khas yang disahkan pengguna.
+ *
+ * Kenapa ini wujud: nama tokoh dan nama surah tiada sumber berwibawa yang
+ * boleh dicapai. Diuji terhadap PRPM, muhammad, ibrahim, musa, umar, aisyah
+ * dan khadijah semuanya TIADA entri. Dataset komuniti pula meliputi nama
+ * tempat (مکة, مسير, ڤاهڠ) tetapi bukan nama orang atau nama surah.
+ *
+ * Alat ini TIDAK mereka ejaan nama. Ia menyimpan apa yang pengguna sahkan
+ * sendiri, dengan sumber dicatat, supaya kerja pengesahan itu dibuat sekali
+ * sahaja dan boleh diaudit kemudian.
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { CACHE_PATH } from './prpm.js'
+
+export const NAMA_PATH = process.env.PRPM_NAMA ?? join(dirname(CACHE_PATH), 'nama-khas.json')
+
+let dimuat = null
+
+export async function muatNama() {
+  if (dimuat !== null) return dimuat
+  try {
+    dimuat = JSON.parse(await readFile(NAMA_PATH, 'utf8'))
+  } catch {
+    dimuat = {}
+  }
+  return dimuat
+}
+
+export async function simpanNama(peta) {
+  await mkdir(dirname(NAMA_PATH), { recursive: true })
+  const tmp = `${NAMA_PATH}.tmp`
+  await writeFile(tmp, JSON.stringify(peta, null, 1), 'utf8')
+  await rename(tmp, NAMA_PATH)
+  dimuat = peta
+  return NAMA_PATH
+}
+
+export async function tambahNama(rumi, jawi, { sumber = 'pengguna', jenis = null } = {}) {
+  const peta = { ...(await muatNama()) }
+  const kunci = String(rumi).trim().toLowerCase()
+  if (!kunci || !jawi) throw new Error('perlu rumi dan jawi')
+  peta[kunci] = { rumi: kunci, jawi: String(jawi).trim(), sumber, jenis }
+  await simpanNama(peta)
+  return peta[kunci]
+}
+
+export async function cariNama(kata) {
+  const peta = await muatNama()
+  const rec = peta[String(kata).trim().toLowerCase()]
+  if (!rec) return null
+  return { ...rec, dijumpai: true, disahkanDbp: false }
+}
+
+/**
+ * Teka sama ada perkataan itu nama khas.
+ *
+ * Huruf besar di TENGAH ayat ialah isyarat yang munasabah dalam teks Melayu.
+ * Ia sengaja tidak digunakan pada perkataan pertama ayat, kerana di situ
+ * huruf besar tidak bermakna apa-apa.
+ */
+export function mungkinNamaKhas(kata, sebelumnya) {
+  if (!/^[A-Z]/.test(kata)) return false
+  // Awal teks, atau selepas noktah, tanda soal, tanda seru, atau baris baru.
+  const awalAyat = !sebelumnya || /[.!?:\n]\s*$/.test(sebelumnya)
+  return !awalAyat
+}

package/src/pedoman.js

@@ -0,0 +1,84 @@
+/**
+ * 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
+}

package/src/tukar.js

@@ -11,6 +11,8 @@
 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
@@ -130,6 +132,8 @@ export async function keJawi(teks, cache, opts = {}) {
   const dariDataset = []
   const dbp = []
   const adaEntriTanpaJawi = []
+  const dariNama = []
+  const namaKhas = []
   const bahagian = teks.split(PECAH_RUMI)
   const keluar = []
 
@@ -155,6 +159,14 @@ export async function keJawi(teks, cache, opts = {}) {
       }
     }
 
+    // Nama khas yang pengguna sudah sahkan sendiri.
+    const nm = await cariNama(cebis)
+    if (nm?.jawi) {
+      dariNama.push({ kata: cebis, jawi: nm.jawi })
+      keluar.push(nm.jawi)
+      continue
+    }
+
     if (cubaDasar) {
       const dasar = await cariDasar(cebis.toLowerCase(), cache, opts)
       if (dasar) {
@@ -166,18 +178,43 @@ export async function keJawi(teks, cache, opts = {}) {
       }
     }
 
-    belumDisahkan.push(cebis)
+    // Nama khas yang belum disahkan bukan salah eja. Ia dilaporkan
+    // berasingan supaya pengguna tahu apa yang perlu disahkan sekali, dan
+    // bukan mengulang menyemak ejaan yang memang betul.
+    if (mungkinNamaKhas(cebis, bahagian[i - 1])) namaKhas.push(cebis)
+    else belumDisahkan.push(cebis)
     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,
+    namaKhas: [...new Set(namaKhas)],
     adaEntriTanpaJawi: [...new Set(adaEntriTanpaJawi)],
     belumDisahkan: [...new Set(belumDisahkan)],
     terbitanSah,
-    lengkap: belumDisahkan.length === 0 && terbitanSah.length === 0,
+    lengkap: belumDisahkan.length === 0 && terbitanSah.length === 0 && namaKhas.length === 0,
     // Sepenuhnya DBP bermakna setiap perkataan datang dari sumber rasmi.
     semuanyaDbp: dariDataset.length === 0 && belumDisahkan.length === 0 && terbitanSah.length === 0,
   }
@@ -195,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 = []
 
@@ -232,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
@@ -250,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,
   }