prpm-dbp 0.19.0 → 0.20.0

package/SKILL.md

@@ -43,6 +43,35 @@ Empat perkara yang ditangkap dalam teks Jawi:
 
 Ruang tersasar itu kes paling berbahaya. Separuh perkataan boleh **berjaya secara palsu**: `ݢول` benar-benar memetakan kepada dua perkataan DBP tulen, `gol` dan `gul`. Penukar yang memilih calon paling kerap akan mengeluarkan "gol" dengan yakin, dan separuh perkataan hilang tanpa sesiapa perasan. Sebab itu percantuman dicuba apabila **salah satu** jiran belum selesai, bukan kedua-duanya.
 
+## Teks Arab dan al-Quran TIDAK PERNAH ditukar
+
+Pedoman §11.1: petikan al-Quran, hadis, nama surah, nama tokoh dan nama tempat **kekal ejaan Arab asalnya**. Ia tidak ditransliterasi ke Rumi dan tidak pernah dicadangkan pembetulan ejaan Melayu.
+
+Ini bukan teori. `الدين` (ad-Din) memetakan kepada dua entri dalam data, jadi penukar lama mengeluarkan `addin|al-din` untuk teks Arab tulen dan pembaca tidak nampak apa-apa salah.
+
+Dua isyarat automatik, kedua-duanya diukur pada 66,323 ejaan Jawi DBP sebenar:
+
+| Isyarat | Padanan palsu | Contoh dilindungi |
+|---|---|---|
+| tanda baris (harakat) | **0** | `إِنَّ ٱللَّهَ مَعَ ٱلصَّٰبِرِينَ` |
+| `أ` atau `آ` di awal | 5 (0.008%) | `أصحاب` |
+| `ال` di awal, tidak dikenali | — | `اليمين`, `المقربون`, `الفاتحة` |
+
+Petikan al-Quran datang bertanda baris dalam amalan biasa, jadi ia dilindungi tanpa apa-apa persediaan.
+
+**Istilah Arab telanjang** — yang tiada tanda baris dan padan sesuatu dalam kamus, seperti `الدين` — diisytihar sekali:
+
+```bash
+npx prpm-dbp nama ad-din الدين --jenis arab
+```
+
+Selepas itu ia tidak disentuh lagi, dalam `rumi` mahupun `gate`.
+
+**Dua perkara yang sengaja TIDAK dibuat**, kedua-duanya diuji dan ditolak:
+
+1. **Rentang Arab tidak merebak kepada jiran.** Kelihatan betul sehingga diuji: satu ejaan Melayu yang salah di sebelah petikan al-Quran tidak dapat dibezakan daripada satu perkataan Arab di sebelah petikan al-Quran, jadi `منجاوهكن` diserap dan kesilapan sebenar hilang. Mendiamkan ralat tulen lebih buruk daripada menandakan satu perkataan Arab yang jarang.
+2. **Jaminan DBP tidak dituntut untuk mengatasi isyarat `ال`.** Ia membekukan 325 daripada 346 perkataan ber-`ال`, termasuk `alah`, `alaf` dan `alabaster`, yang alif-lamnya sebahagian perkataan dan bukan kata sandang. Ortografi sahaja tidak dapat membezakannya.
+
 Nama khas Arab tanpa kata sandang `ال` (`أصحاب`, nama tokoh, nama tempat) tidak dapat disahkan kamus Melayu. Isytiharkannya melalui `npx prpm-dbp nama <rumi> <jawi> --jenis arab`; selepas itu ia berhenti menjadi ralat, tetapi tetap **bukan** lulus DBP.
 
 `gate` keluar dengan kod 1 apabila ada ralat, jadi ia boleh dipasang sebagai hook atau langkah CI. Peraturan yang bergantung pada agen ingat sendiri akan gagal, dan gagal secara senyap.

package/bin/cli.js

@@ -7,6 +7,17 @@ import { banding, cariKamus } from '../src/kamus.js'
 import { keJawi, keRumi, semakJawi } from '../src/tukar.js'
 import { huraiTsv, muatDataset, simpanDataset } from '../src/dataset.js'
 import { NAMA_PATH, muatNama, tambahNama } from '../src/nama.js'
+
+// Istilah Arab yang pengguna sahkan sendiri. Petikan al-Quran datang
+// bertanda baris dalam amalan biasa dan dikenali automatik; istilah
+// telanjang seperti الدين diisytihar sekali di sini dan tidak pernah
+// ditransliterasi lagi, dalam `rumi` mahupun `gate`.
+const arabDiisytiharkan = async () =>
+  new Set(
+    Object.values(await muatNama())
+      .filter((n) => n?.jenis === 'arab' && n.jawi)
+      .map((n) => n.jawi),
+  )
 import { gate, kodKeluar } from '../src/gate.js'
 import {
   CACHE_PATH,
@@ -252,6 +263,7 @@ async function main() {
         pilihLazim: pilihan.pilih,
         padanRangka: pilihan.rangka,
         glosari: pilihan.glosari ? JSON.parse(await readFile(pilihan.glosari, 'utf8')) : null,
+        arabDiisytihar: await arabDiisytiharkan(),
       })
       if (pilihan.json) { keluar(h); break }
       console.log(h.teks)
@@ -330,6 +342,7 @@ async function main() {
               .map((n) => n?.jawi)
               .filter(Boolean),
           ),
+          arabDiisytihar: await arabDiisytiharkan(),
           luarTalian: pilihan.luarTalian !== false,
           abai,
         })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prpm-dbp",
-  "version": "0.19.0",
+  "version": "0.20.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/gate.js

@@ -29,7 +29,7 @@ import { cariDataset } from './dataset.js'
 import { normalisasiJawi } from './kamus.js'
 import { jarakHuruf, petaSongsang } from './tukar.js'
 import { pisahUlangJawi } from './pedoman.js'
-import { rangkaKonsonan } from './semak.js'
+import { isyaratArab, rangkaKonsonan } from './semak.js'
 
 const TOKEN_RUMI = /([A-Za-zÀ-ÿ][A-Za-zÀ-ÿ'-]*)/g
 const TOKEN_JAWI = /([؀-ۿݐ-ݿﭐ-﷿ﹰ-]+)/g
@@ -55,7 +55,7 @@ const HARAKAT = /[ً-ْٰٓ-ٕ]/
  * kerana separuh pertama "berjaya".
  */
 export function gateJawi(teks, cache, opts = {}) {
-  const { dataset = null, abai = new Set(), namaJawi = new Set() } = opts
+  const { dataset = null, abai = new Set(), namaJawi = new Set(), arabDiisytihar = new Set() } = opts
   const peta = petaSongsang(cache, dataset)
 
   // Indeks rangka konsonan, dibina sekali. Ejaan yang tersalah biasanya
@@ -113,21 +113,48 @@ export function gateJawi(teks, cache, opts = {}) {
     return m ? m.layak.length === 1 : false
   }
 
+  // ── Kesan rentang Arab SEBELUM apa-apa dinilai ────────────────────────
+  //
+  // Pedoman §11.1: petikan al-Quran, hadis, nama surah, nama tokoh dan nama
+  // tempat KEKAL ejaan Arab asalnya. Ia tidak boleh disemak dengan kamus
+  // Melayu, dan lebih penting lagi ia tidak boleh DICADANGKAN pembetulan.
+  // Gate hanya melapor, tetapi agen yang membaca "guna اصحاب" akan menyunting
+  // ayat al-Quran. Mencadangkan pembetulan pada teks wahyu lebih teruk
+  // daripada tidak menyemaknya langsung.
+  //
+  // Diukur pada 66,323 ejaan Jawi DBP sebenar:
+  //   harakat      0 padanan  -> isyarat sempurna
+  //   `أ` di awal  4 padanan  -> 0.006%, dan keempat-empatnya larut sendiri
+  //   `إ` di awal  7 padanan  -> termasuk إسلام, jadi BUKAN isyarat
+  //   `ال` di awal 360 padanan -> hanya berguna bersama syarat tidak larut
+  const benihArab = (t) => isyaratArab(t, (x) => Boolean(cari(x)), arabDiisytihar)
+
+  const arab = new Set()
+  for (const tok of token) if (benihArab(tok.teks)) arab.add(tok.i)
+
+  // Rentang Arab SENGAJA TIDAK merebak kepada jiran. Percubaan merebak
+  // melalui ruang kepada token yang tidak larut kelihatan betul sehingga
+  // diuji: satu ejaan Melayu yang salah di sebelah petikan al-Quran tidak
+  // dapat dibezakan daripada satu perkataan Arab di sebelah petikan
+  // al-Quran, jadi منجاوهكن diserap dan kesilapan sebenar hilang.
+  //
+  // Mendiamkan ralat tulen lebih buruk daripada menandakan satu perkataan
+  // Arab yang jarang. Setiap token mesti membawa isyaratnya sendiri.
+  // Petikan al-Quran datang bertanda baris dalam amalan biasa, jadi ia
+  // dilindungi; apa yang tidak, diisytihar melalui `nama` atau `--abai`.
+
   for (const [n, tok] of token.entries()) {
     const t = tok.teks
     if (abai.has(t) || abai.has(normalisasiJawi(t))) continue
 
-    // Petikan Arab tidak selalu bertanda baris. Kata sandang `ال` ialah
-    // penanda paling boleh dipercayai yang tinggal: ia membuka hampir setiap
-    // frasa Arab yang dipetik (اليمين, المقربون, الشمال) dan pada dasarnya
-    // tidak pernah membuka kata Melayu Jawi. Nama khas Arab tanpa kata
-    // sandang (أصحاب) tetap perlu diisytihar melalui simpanan `nama`;
-    // kamus Melayu memang tidak boleh mengesahkannya, dan berpura-pura
-    // boleh adalah jaminan palsu.
-    if (HARAKAT.test(t) || (/^ال/.test(t) && !cari(t))) {
-      // Pedoman §11.1: petikan Arab kekalkan ejaan asal. Ia bukan lulus DBP
-      // kerana kamus Melayu tidak boleh mengesahkannya; ia keadaan ketiga.
-      if (!dilihat.has(t)) { dilihat.add(t); tidakDapatDisahkan.push({ kata: t, sebab: 'teks Arab, dikekalkan (Pedoman §11.1)' }) }
+    if (arab.has(tok.i)) {
+      // Bukan lulus DBP: kamus Melayu tidak mengesahkannya. Bukan ralat:
+      // ejaan Arab asal memang betul. Ia keadaan ketiga, dan TIADA cadangan
+      // pembetulan dikeluarkan untuknya.
+      if (!dilihat.has(t)) {
+        dilihat.add(t)
+        tidakDapatDisahkan.push({ kata: t, sebab: 'teks Arab, kekalkan seadanya (Pedoman §11.1)' })
+      }
       continue
     }
 
@@ -136,7 +163,7 @@ export function gateJawi(teks, cache, opts = {}) {
     // Cuba cantum dengan jiran SEBELUM melaporkan apa-apa, kerana ruang
     // tersasar mencemarkan kedua-dua separuh sekali gus.
     const seterusnya = token[n + 1]
-    if (seterusnya && ruangSahaja(tok.i, seterusnya.i)) {
+    if (seterusnya && !arab.has(seterusnya.i) && ruangSahaja(tok.i, seterusnya.i)) {
       const belumSelesai = !selesai(t) || !selesai(seterusnya.teks)
       if (belumSelesai) {
         const gabung = cari(t + seterusnya.teks)

package/src/semak.js

@@ -152,3 +152,52 @@ export function rangkaKonsonan(jawi) {
   if (keluar && HUJUNG_SETARA.has(keluar.slice(-1))) keluar = keluar.slice(0, -1) + 'ه'
   return keluar
 }
+
+// ── Pengesan teks Arab ────────────────────────────────────────────────────
+//
+// Pedoman DBP §11.1: petikan al-Quran, hadis, nama surah, nama tokoh dan
+// nama tempat KEKAL ejaan Arab asalnya. Ia tidak boleh ditransliterasi ke
+// Rumi dan tidak boleh dicadangkan pembetulan ejaan Melayu.
+//
+// Ini bukan sekadar teori. `الدين` (ad-Din) memetakan kepada dua entri Jawi
+// dalam data DBP, jadi tanpa pemeriksaan ini penukar mengeluarkan
+// "addin|al-din" untuk teks Arab dan pembaca tidak nampak apa-apa salah.
+//
+// Diukur pada 66,323 ejaan Jawi DBP sebenar:
+//   harakat        0 padanan  -> isyarat sempurna
+//   `أ` `آ` awal   5 padanan  -> 0.008%
+//   `ال` awal    360 padanan  -> berguna HANYA bersama syarat tidak larut
+//   `إ` awal       7 padanan  -> termasuk إسلام, jadi BUKAN isyarat
+const HARAKAT = /[ً-ْٰٓ-ٕ]/
+
+/**
+ * @param {string} token  satu perkataan Jawi/Arab
+ * @param {(t: string) => boolean} larut  adakah token ini dikenali sebagai
+ *   kata Melayu langsung
+ * @param {Set<string>} diisytihar  istilah Arab yang pengguna sahkan sendiri
+ *
+ * Menuntut jaminan DBP lapisan 1 untuk mengatasi isyarat `ال` telah diuji
+ * dan DITOLAK: ia membekukan 325 daripada 346 perkataan ber-`ال`, termasuk
+ * alah, alaf dan alabaster, yang alif-lamnya sebahagian perkataan dan bukan
+ * kata sandang. Ortografi sahaja tidak dapat membezakannya.
+ *
+ * Yang tinggal ialah dua isyarat yang benar-benar bersih, ditambah
+ * pengisytiharan pengguna. Petikan al-Quran datang bertanda baris dalam
+ * amalan biasa; istilah Arab telanjang seperti `الدين` diisytihar sekali
+ * melalui simpanan `nama --jenis arab` dan tidak pernah disentuh lagi.
+ *
+ * Isyarat sengaja per-token dan TIDAK merebak kepada jiran. Percubaan
+ * merebak melalui ruang kelihatan betul sehingga diuji: satu ejaan Melayu
+ * yang salah di sebelah petikan al-Quran tidak dapat dibezakan daripada satu
+ * perkataan Arab di sebelah petikan al-Quran, jadi ralat tulen diserap dan
+ * hilang. Mendiamkan kesilapan sebenar lebih buruk daripada menandakan satu
+ * perkataan Arab yang jarang.
+ */
+export function isyaratArab(token, larut = () => false, diisytihar = new Set()) {
+  if (HARAKAT.test(token)) return 'harakat'
+  if (diisytihar.has(token)) return 'diisytihar pengguna'
+  if (larut(token)) return null
+  if (/^[أآ]/.test(token)) return 'hamzah awal'
+  if (/^ال/.test(token)) return 'kata sandang'
+  return null
+}

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 { rangkaKonsonan, semakHurufAkhir } from './semak.js'
+import { isyaratArab, rangkaKonsonan, semakHurufAkhir } from './semak.js'
 import {
   imbuhAkhiranAn,
   imbuhAkhiranKan,
@@ -491,6 +491,7 @@ export function keRumi(
     pilihLazim = false,
     padanRangka = false,
     glosari = null,
+    arabDiisytihar = new Set(),
   } = {},
 ) {
   const peta = petaSongsang(cache, dataset)
@@ -521,9 +522,17 @@ export function keRumi(
       }
     }
 
-    // Teks Arab bertanda baris dibiarkan seadanya. Cuba menukarnya akan
-    // merosakkan petikan al-Quran dan hadis dalam dokumen Melayu.
-    if (HARAKAT.test(bahagian[i])) {
+    // Teks Arab dibiarkan seadanya. Cuba menukarnya akan merosakkan petikan
+    // al-Quran dan hadis dalam dokumen Melayu.
+    //
+    // Tanda baris sahaja TIDAK memadai. Frasa seperti أصحاب اليمين datang
+    // tanpa baris, dan lebih buruk lagi `الدين` memetakan kepada dua entri
+    // Jawi dalam data DBP — jadi penukar mengeluarkan "addin|al-din" untuk
+    // teks Arab tulen dan pembaca tidak nampak apa-apa salah. Perkataan
+    // yang benar-benar larut dalam DBP tidak terjejas: isyarat kata sandang
+    // hanya terpakai apabila perkataan itu bukan kata Melayu.
+    const tandaArab = isyaratArab(bahagian[i], (t) => peta.has(normalisasiJawi(t)), arabDiisytihar)
+    if (tandaArab) {
       arab.push(bahagian[i])
       keluar.push(bahagian[i])
       continue