prpm-dbp 0.10.0 → 0.11.0

package/README.md

@@ -134,6 +134,8 @@ Pengguna kemudian menarik versi baharu dengan `npx skills update`.
 
 Pilihan: `--refresh`, `--had <n>`, `--delay <ms>`, `--json`, `--cepat`, `--pedoman`.
 
+`--luar-talian` tidak pernah menyentuh rangkaian. Wajib untuk laluan permintaan aplikasi: dokumen penuh dari cache mengambil 0.19 saat, manakala satu perkataan baharu daripada PRPM mengambil beberapa saat.
+
 `--pedoman` membenarkan penjanaan imbuhan menurut peraturan DBP apabila kamus tiada jawapan. Ketepatannya diukur 88-98% terhadap 66,000 perkataan sebenar, jadi ia mati secara lalai dan hasilnya sentiasa ditanda.
 
 ## Guna sebagai library

package/SKILL.md

@@ -69,6 +69,10 @@ Contoh kedua: `dipelajari` ialah terbitan sah daripada `ajar`. Alat ini **tidak*
 
 **Bila `rumi` jumpa kekaburan**, satu ejaan Jawi memetakan kepada beberapa perkataan Rumi. Semua calon dipaparkan dipisah `|`. Pilih ikut konteks ayat, jangan ambil yang pertama secara membuta.
 
+Sebahagian kekaburan itu palsu dan diselesaikan sendiri. DBP menandakan bentuk varian dengan **rujukan silang**: definisi `kalkalah` ialah `®qalqalah.`, bukan definisi sebenar. Varian begitu dinyahutamakan, jadi `قلقله` dibaca `qalqalah` terus.
+
+Isyaratnya mestilah tanda `®` itu, **bukan** kehadiran ejaan Jawi. `pada` tiada ejaan Jawi dalam PRPM manakala `pad` (pinjaman Inggeris) ada. Mengutamakan "yang ada Jawi" akan menukar setiap `pada` menjadi `pad`.
+
 Jawi Melayu menulis vokal dengan alif, wau dan ya, tidak seperti Arab. Kerana itu kekaburan jarang berlaku, tetapi ia tetap wujud.
 
 `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.
@@ -215,12 +219,12 @@ Diuji terhadap 406 perkataan pelajaran Pendidikan Islam Tingkatan 4 sebenar, dit
 
 ```
 token asal 336  ->  token pusing balik 336
-padan tepat        309 (92%)
-padan antara calon  27 (8%)
+padan tepat        314 (93%)
+padan antara calon  22 (7%)
 TIDAK padan          0 (0%)
 ```
 
-Dua puluh tujuh kes kabur itu sah: `قلقله` boleh dibaca `qalqalah` atau `kalkalah`, dua ejaan Rumi yang sama-sama betul bagi istilah Arab yang sama. Alat melaporkan kedua-duanya dan tidak memilih.
+Dua puluh dua kes kabur yang tinggal itu sah: `قلقله` boleh dibaca `qalqalah` atau `kalkalah`, dua ejaan Rumi yang sama-sama betul bagi istilah Arab yang sama. Alat melaporkan kedua-duanya dan tidak memilih.
 
 **Sifar perkataan hilang atau rosak.**
 
@@ -233,6 +237,26 @@ Dua puluh tujuh kes kabur itu sah: `قلقله` boleh dibaca `qalqalah` atau `ka
 | §12 serapan Inggeris | Kamus sudah meliputinya; tiada penjanaan diperlukan. |
 | §16.2, §18 | Tidak memerlukan kod: perbezaannya sudah dikodkan dalam jarak teks Rumi. Ada ujian yang mengunci tingkah laku ini. |
 
+## Menyambung ke aplikasi
+
+Kelajuan diukur pada 406 perkataan:
+
+| Keadaan | Masa |
+|---|---|
+| Semua dari cache | **0.19 saat** |
+| Dua perkataan baharu (perlu rangkaian) | **30.7 saat** |
+
+Perbezaan itu menentukan cara ia disambung. **Dalam laluan permintaan aplikasi, gunakan `--luar-talian` sentiasa.** Mod itu tidak pernah menyentuh rangkaian: perkataan yang tiada dalam cache dilaporkan belum disahkan, bukan diambil secara segerak sambil pengguna menunggu.
+
+Urutan yang disyorkan:
+
+1. **Panaskan cache di luar talian** daripada kosa kata projek anda: `npx prpm-dbp warm senarai.txt`
+2. **Hantar cache itu bersama aplikasi** (salin `~/.cache/prpm-dbp/cache.json`, atau tetapkan `PRPM_CACHE`)
+3. **Jalankan dengan `--luar-talian`** dalam laluan permintaan
+4. **Kumpul medan `belumDisahkan`** dan panaskan cache secara berkala di luar talian
+
+Dengan cara ini pengguna tidak pernah menunggu PRPM, dan PRPM tidak pernah menerima trafik daripada aplikasi anda.
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/bin/cli.js

@@ -34,7 +34,8 @@ const BANTUAN = `prpm-dbp — semak Bahasa Melayu dan Jawi terhadap PRPM DBP
   npx prpm-dbp install [--link]          pasang sebagai Claude Code skill
 
 Pilihan: --refresh  --had <n>  --delay <ms>  --json  --cepat
-         --pedoman  jana imbuhan ikut peraturan DBP (88-98% tepat, hasil ditanda)
+         --pedoman       jana imbuhan ikut peraturan DBP (88-98% tepat, hasil ditanda)
+         --luar-talian   jangan sentuh rangkaian langsung (wajib untuk laluan permintaan app)
 
 Cache: ${CACHE_PATH}
 `
@@ -49,6 +50,7 @@ function huraiArgs(argv) {
     else if (a === '--link') pilihan.link = true
     else if (a === '--cepat') pilihan.cepat = true
     else if (a === '--pedoman') pilihan.pedoman = true
+    else if (a === '--luar-talian') pilihan.luarTalian = 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])
@@ -79,7 +81,12 @@ async function main() {
   }
 
   const cache = await loadCache()
-  const opts = { refresh: pilihan.refresh, delay: pilihan.delay, onProgress: progres }
+  const opts = {
+    refresh: pilihan.refresh,
+    delay: pilihan.delay,
+    onProgress: progres,
+    luarTalian: pilihan.luarTalian,
+  }
 
   switch (perintah) {
     case 'lookup': {

package/package.json

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

@@ -130,11 +130,25 @@ export async function fetchPage(kata, { timeout = 20000 } = {}) {
 
 const tidur = (ms) => new Promise((r) => setTimeout(r, ms))
 
-export async function lookup(kata, cache, { refresh = false, delay = 400, perluPenuh = false } = {}) {
+export async function lookup(
+  kata,
+  cache,
+  { refresh = false, delay = 400, perluPenuh = false, luarTalian = false } = {},
+) {
   const key = String(kata).trim().toLowerCase()
   if (!key) return null
 
   const simpanan = cache[key]
+
+  // Mod luar talian TIDAK PERNAH menyentuh rangkaian. Ini wajib untuk
+  // laluan permintaan aplikasi: satu perkataan yang belum dicache mengambil
+  // beberapa saat, manakala keseluruhan dokumen dari cache mengambil 0.2
+  // saat. Perkataan yang tiada dalam cache dilaporkan belum disahkan,
+  // bukan diambil secara segerak sambil pengguna menunggu.
+  if (luarTalian) {
+    if (simpanan) return { ...simpanan, dariCache: true }
+    return { kata: key, dijumpai: false, jawi: null, jawiVarian: [], entri: [], nota: 'tiada dalam cache (mod luar talian)', url: `${BASE_URL}?keyword=${encodeURIComponent(key)}` }
+  }
   // Rekod benih membawa ejaan sahaja, tanpa definisi, supaya pakej kekal
   // kecil. Bila pemanggil betul-betul perlukan definisi, ambil semula.
   const cukup = simpanan && !(perluPenuh && simpanan.ringkas)

package/src/tukar.js

@@ -159,13 +159,28 @@ export function petaSongsang(cache, dataset = null) {
   const peta = new Map()
   let maxKata = 1
 
-  const tambah = (jawi, rumi) => {
+  // DBP menandakan bentuk varian dengan rujukan silang: definisi `kalkalah`
+  // ialah "®qalqalah.", bukan definisi sebenar. Varian begitu dinyahutamakan
+  // supaya قلقله dibaca qalqalah dan bukan dilaporkan kabur.
+  //
+  // Isyaratnya mestilah tanda ® itu, BUKAN kehadiran ejaan Jawi. `pada`
+  // tiada Jawi dalam PRPM manakala `pad` (pinjaman Inggeris) ada, jadi
+  // mengutamakan "yang ada Jawi" akan menukar setiap `pada` menjadi `pad`.
+  const rujukanSilang = new Set()
+  for (const [kata, rec] of Object.entries(cache)) {
+    const def = rec?.entri?.[0]?.definisi ?? ''
+    if (/^®/.test(def.trim())) rujukanSilang.add(kata)
+  }
+
+  const tambah = (jawi, rumi, sumber) => {
     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(rumi)) peta.get(kunci).push(rumi)
+    if (!peta.has(kunci)) peta.set(kunci, { utama: [], rujukan: [] })
+    const jenis = rujukanSilang.has(rumi) ? 'rujukan' : 'utama'
+    const slot = peta.get(kunci)[jenis]
+    if (!slot.includes(rumi)) slot.push(rumi)
   }
 
   for (const rec of Object.values(cache)) {
@@ -179,6 +194,19 @@ export function petaSongsang(cache, dataset = null) {
   return peta
 }
 
+/**
+ * Pilih calon songsang. Bentuk yang DBP sendiri tandakan sebagai rujukan
+ * silang (®) hanya digunakan apabila tiada bentuk utama. Selain itu semua
+ * calon dilayan sama rata, dan kekaburan sebenar dilaporkan sepenuhnya.
+ */
+export function pilihCalon(masuk) {
+  if (!masuk) return null
+  if (Array.isArray(masuk)) return { calon: masuk, sumber: 'campur' }
+  if (masuk.utama.length) return { calon: masuk.utama, sumber: 'utama' }
+  if (masuk.rujukan.length) return { calon: masuk.rujukan, sumber: 'rujukan' }
+  return null
+}
+
 /**
  * Rumi -> Jawi. Pemisah, tanda baca dan baris baru dikekalkan.
  * Perkataan yang tidak disahkan dibalut penanda, tidak pernah direka.
@@ -360,17 +388,17 @@ export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null
       }
       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 jumpa = pilihCalon(peta.get(normalisasiJawi(frasa)))
+      if (jumpa) { padanan = jumpa.calon; hujung = akhir; break }
     }
 
     if (!padanan) {
       // Pedoman DBP §17.1 songsang: kata dasar + ٢ menjadi kata berulang.
       const dasarUlang = pisahUlangJawi(bahagian[i])
       if (dasarUlang) {
-        const jumpaUlang = peta.get(normalisasiJawi(dasarUlang))
-        if (jumpaUlang?.length === 1) {
-          keluar.push(jumpaUlang[0] + '-' + jumpaUlang[0])
+        const jumpaUlang = pilihCalon(peta.get(normalisasiJawi(dasarUlang)))
+        if (jumpaUlang?.calon.length === 1) {
+          keluar.push(jumpaUlang.calon[0] + '-' + jumpaUlang.calon[0])
           continue
         }
       }
@@ -379,8 +407,8 @@ export function keRumi(teksJawi, cache, { penanda = ['«', '»'], dataset = null
       // 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 }
+        const jumpa = pilihCalon(peta.get(normalisasiJawi(calon.baki)))
+        if (jumpa?.calon.length === 1) { dipisah = calon.sendi + ' ' + jumpa.calon[0]; break }
       }
       if (dipisah) { keluar.push(dipisah); sendiDipisah.push(bahagian[i]); continue }