prpm-dbp 0.2.2 → 0.4.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

@@ -73,6 +73,49 @@ Jawi Melayu menulis vokal dengan alif, wau dan ya, tidak seperti Arab. Kerana it
 
 `rumi` bekerja dari cache sahaja dan tidak menyentuh rangkaian. Perkataan yang belum pernah disemak dalam arah Rumi ke Jawi tidak akan dikenali. Jalankan `warm` atau `audit` dahulu pada kosa kata yang berkaitan.
 
+## Istilah Arab
+
+Kebanyakan istilah agama ialah **kata Melayu**, bukan kata asing. Diuji terhadap PRPM: 29 daripada 30 istilah lazim ada entri, termasuk `yasin`, `fatihah`, `baqarah`, `rahman`, `rasulullah`. Jangan andaikan sesuatu itu Arab semata-mata kerana ia berbunyi Arab; tanya DBP dahulu.
+
+Tiga keadaan berbeza, dilaporkan berasingan:
+
+| Keadaan | Contoh | Maksud |
+|---|---|---|
+| Ada entri dan ejaan Jawi | `solat` صلاة, `zakat` زکاة | guna terus |
+| `adaEntriTanpaJawi` | `yasin`, `fatihah`, `baqarah`, `wuduk` | DBP iktiraf sebagai kata Melayu, cuma tiada ejaan Jawi disimpan |
+| `belumDisahkan` | `ahzab` | bukan kata Melayu; nama khas Arab |
+
+Ejaan Jawi bagi pinjaman Arab **mengekalkan ejaan Arab asal**, bukan dieja secara fonetik: `صلاة` bukan `سولت`, `زکاة` bukan `زکات`. Ta marbutah dan alef maksura dikekalkan. Sebab itu ta marbutah tidak pernah dilipat semasa perbandingan.
+
+Sesetengah entri memulangkan **dua perkataan Jawi untuk satu perkataan Rumi**: `rasulullah` → `رسول الله`. Pembacaan songsang memadan jujukan, jadi ia tidak pecah menjadi `rasul allah`.
+
+**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 `کوالا لومڤور`.
+
 ## 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
@@ -154,6 +157,18 @@ async function main() {
       if (h.belumDisahkan.length) {
         console.error(`\nbelum disahkan (${h.belumDisahkan.length}): ${h.belumDisahkan.join(', ')}`)
       }
+      if (h.adaEntriTanpaJawi.length) {
+        console.error(
+          `DBP ada entri tetapi tiada ejaan Jawi (${h.adaEntriTanpaJawi.length}): ` +
+            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}): ` +
@@ -165,17 +180,29 @@ async function main() {
 
     case 'rumi': {
       const teks = await readFile(baki[0], 'utf8')
-      const h = keRumi(teks, cache)
+      const h = keRumi(teks, cache, { dataset: await muatDataset() })
       if (pilihan.json) { keluar(h); break }
       console.log(h.teks)
       console.error(`\npeta songsang: ${h.saizPeta} ejaan`)
       if (h.tidakDikenali.length) {
         console.error(`tidak dikenali (${h.tidakDikenali.length}): ${h.tidakDikenali.join(', ')}`)
       }
+      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
     }
 
+    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.2.2",
+  "version": "0.4.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/tukar.js

@@ -10,7 +10,14 @@
 
 import { lookup } from './prpm.js'
 import { normalisasiJawi } from './kamus.js'
-import { cariDataset } from './dataset.js'
+import { cariDataset, muatDataset } from './dataset.js'
+import { cariNama, mungkinNamaKhas } from './nama.js'
+
+// Baris tanda vokal Arab (fathah, kasrah, dammah, sukun, syaddah, tanwin,
+// alef superscript). Jawi Melayu TIDAK menggunakannya; teks al-Quran dan
+// hadis yang dipetik dalam dokumen Melayu menggunakannya. Kehadirannya
+// bermakna potongan itu bahasa Arab, bukan Jawi, dan tidak boleh ditukar.
+const HARAKAT = /[\u064B-\u0652\u0670\u0653-\u0655]/
 
 const JAWI_JULAT = '؀-ۿݐ-ݿﭐ-﷿ﹰ-'
 // Token dipecah supaya pemisah dikekalkan, jadi tanda baca, baris baru dan
@@ -80,15 +87,36 @@ export async function cariDasar(kata, cache, opts = {}) {
   return null
 }
 
-/** Bina peta Jawi -> Rumi daripada segala yang sudah disahkan dalam cache. */
-export function petaSongsang(cache) {
+/**
+ * Bina peta Jawi -> Rumi. Menggabungkan cache DBP dengan dataset yang
+ * diimport, jika ada: tanpa dataset, apa-apa yang ditukar melalui lapisan
+ * ketiga tidak boleh dipusingkan balik langsung.
+ *
+ * Sesetengah nilai mengandungi RUANG (rasulullah -> رسول الله). Peta menjejaki
+ * bilangan perkataan terpanjang supaya pembacaan songsang boleh memadan
+ * jujukan, bukan token tunggal sahaja.
+ */
+export function petaSongsang(cache, dataset = null) {
   const peta = new Map()
-  for (const rec of Object.values(cache)) {
-    if (!rec?.jawi) continue
-    const kunci = normalisasiJawi(rec.jawi)
+  let maxKata = 1
+
+  const tambah = (jawi, rumi) => {
+    const kunci = normalisasiJawi(jawi)
+    if (!kunci) return
+    const bilangan = kunci.split(/\s+/).length
+    if (bilangan > maxKata) maxKata = bilangan
     if (!peta.has(kunci)) peta.set(kunci, [])
-    if (!peta.get(kunci).includes(rec.kata)) peta.get(kunci).push(rec.kata)
+    if (!peta.get(kunci).includes(rumi)) peta.get(kunci).push(rumi)
   }
+
+  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)
+  }
+
+  peta.maxKata = maxKata
   return peta
 }
 
@@ -102,6 +130,9 @@ export async function keJawi(teks, cache, opts = {}) {
   const terbitanSah = []
   const dariDataset = []
   const dbp = []
+  const adaEntriTanpaJawi = []
+  const dariNama = []
+  const namaKhas = []
   const bahagian = teks.split(PECAH_RUMI)
   const keluar = []
 
@@ -111,6 +142,11 @@ export async function keJawi(teks, cache, opts = {}) {
     const rec = await lookup(cebis.toLowerCase(), cache, opts)
     if (rec?.jawi) { 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
+    // surah dan istilah agama seperti yasin, fatihah, baqarah.
+    if (rec?.dijumpai) adaEntriTanpaJawi.push(cebis)
+
     // Lapisan ketiga: dataset yang diimport pengguna. Berlabel, tidak pernah
     // menyamar sebagai ejaan DBP.
     if (gunaDataset) {
@@ -122,6 +158,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) {
@@ -133,7 +177,11 @@ 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])
   }
 
@@ -141,9 +189,12 @@ export async function keJawi(teks, cache, opts = {}) {
     teks: keluar.join(''),
     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,
   }
@@ -156,32 +207,66 @@ export async function keJawi(teks, cache, opts = {}) {
  * menggugurkannya. Kerana itu perlanggaran jauh lebih jarang daripada yang
  * disangka. Bila ia berlaku, SEMUA calon dilaporkan, bukan dipilih satu.
  */
-export function keRumi(teksJawi, cache, { penanda = ['«', '»'] } = {}) {
-  const peta = petaSongsang(cache)
+export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null } = {}) {
+  const peta = petaSongsang(cache, dataset)
   const tidakDikenali = []
   const kabur = []
+  const arab = []
   const bahagian = teksJawi.split(PECAH_JAWI)
   const keluar = []
 
-  for (const [i, cebis] of bahagian.entries()) {
-    if (i % 2 === 0) { keluar.push(cebis); continue }
+  for (let i = 0; i < bahagian.length; i++) {
+    if (i % 2 === 0) { keluar.push(bahagian[i]); continue }
+
+    // Teks Arab bertanda baris dibiarkan seadanya. Cuba menukarnya akan
+    // merosakkan petikan al-Quran dan hadis dalam dokumen Melayu.
+    if (HARAKAT.test(bahagian[i])) {
+      arab.push(bahagian[i])
+      keluar.push(bahagian[i])
+      continue
+    }
+
+    // Padanan jujukan terpanjang dahulu, supaya رسول الله ditemui sebagai
+    // satu perkataan dan bukan dipecah jadi rasul + allah.
+    let padanan = null
+    let hujung = i
+    // Had atas MESTI integer. Nilai pecahan menyebabkan n melompat 3.5, 2.5,
+    // 1.5 dan tidak pernah menyentuh bilangan perkataan sebenar, lalu hujung
+    // jatuh pada pemisah dan bukan token.
+    const maxN = Math.min(peta.maxKata, Math.floor((bahagian.length - i + 1) / 2))
+    for (let n = maxN; n >= 1; n--) {
+      const akhir = i + (n - 1) * 2
+      if (akhir >= bahagian.length || akhir % 2 === 0) continue
+      // Hanya gabung apabila pemisah antara token benar-benar ruang.
+      let bolehGabung = true
+      for (let k = i + 1; k < akhir; k += 2) {
+        if (!/^\s+$/.test(bahagian[k])) { bolehGabung = false; break }
+      }
+      if (!bolehGabung) continue
+      const frasa = bahagian.slice(i, akhir + 1).join(' ').replace(/\s+/g, ' ')
+      const jumpa = peta.get(normalisasiJawi(frasa))
+      if (jumpa) { padanan = jumpa; hujung = akhir; break }
+    }
 
-    const padanan = peta.get(normalisasiJawi(cebis))
     if (!padanan) {
-      tidakDikenali.push(cebis)
-      keluar.push(penanda[0] + cebis + penanda[1])
-    } else if (padanan.length === 1) {
-      keluar.push(padanan[0])
-    } else {
-      kabur.push({ jawi: cebis, calon: padanan })
+      tidakDikenali.push(bahagian[i])
+      keluar.push(penanda[0] + bahagian[i] + penanda[1])
+      continue
+    }
+
+    if (padanan.length === 1) keluar.push(padanan[0])
+    else {
+      kabur.push({ jawi: bahagian.slice(i, hujung + 1).join(''), calon: padanan })
       keluar.push(padanan.join('|'))
     }
+    i = hujung
   }
 
   return {
     teks: keluar.join(''),
     tidakDikenali: [...new Set(tidakDikenali)],
     kabur,
+    arab: [...new Set(arab)],
     saizPeta: peta.size,
     lengkap: tidakDikenali.length === 0,
   }