iraqi-dialect-bad-words 1.4.0 → 2.0.0

package/README.ar.md

@@ -0,0 +1,352 @@
+# iraqi-dialect-bad-words
+
+[English](README.md) | **العربية**
+
+[![npm version](https://img.shields.io/npm/v/iraqi-dialect-bad-words.svg)](https://www.npmjs.com/package/iraqi-dialect-bad-words)
+[![CI](https://github.com/karam-fikre/iraqi-dialect-bad-words/actions/workflows/ci.yml/badge.svg)](https://github.com/karam-fikre/iraqi-dialect-bad-words/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/iraqi-dialect-bad-words.svg)](LICENSE)
+
+فلتر للكلمات البذيئة في اللهجة العراقية. يكتشف الكلمات البذيئة في النصوص التي يكتبها المستخدمون ويخفيها.
+
+يعمل في **React Native / Expo** و **React** ‏(Vite و Next.js و CRA وغيرها) و **Vue** ‏(Vite و Nuxt) و **Node.js**، ويأتي مع أنواع TypeScript، وبلا أي اعتماديات.
+
+## التثبيت
+
+```bash
+npm install iraqi-dialect-bad-words
+# أو
+yarn add iraqi-dialect-bad-words
+# أو
+npx expo install iraqi-dialect-bad-words
+```
+
+## الاستخدام
+
+```ts
+import IraqiBadWordsFilter from 'iraqi-dialect-bad-words';
+// CommonJS: const { IraqiBadWordsFilter } = require('iraqi-dialect-bad-words');
+
+const filter = new IraqiBadWordsFilter();
+
+filter.isProfane('مرحبا بك');      // false
+filter.isProfane('هذا كلام عارة');  // true
+
+filter.clean('هذا كلام عارة');       // 'هذا كلام ****'
+filter.clean('هذا كلام عارة', '#');  // 'هذا كلام ####'
+filter.clean('هذا كلام عارة', '');       // 'هذا كلام '
+```
+
+### مثال React Native
+
+```tsx
+import { useState } from 'react';
+import { TextInput, Text } from 'react-native';
+import IraqiBadWordsFilter from 'iraqi-dialect-bad-words';
+
+const filter = new IraqiBadWordsFilter(); // أنشئه مرة واحدة، خارج المكوّن
+
+export function CommentInput() {
+  const [text, setText] = useState('');
+
+  return (
+    <>
+      <TextInput value={text} onChangeText={setText} />
+      {filter.isProfane(text) && <Text>يرجى الالتزام بالاحترام.</Text>}
+    </>
+  );
+}
+```
+
+### مثال Vue
+
+أنشئ الفلتر مرة واحدة في ملف خاص به واستورده حيث تحتاجه. لا تضعه داخل `ref()` أو `reactive()`: الفلتر لا يتغير، وتغليفه بكائنات تفاعلية يبطّئ كل فحص فقط.
+
+```ts
+// src/profanity.ts
+import IraqiBadWordsFilter from 'iraqi-dialect-bad-words';
+
+export const filter = new IraqiBadWordsFilter();
+```
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { filter } from '@/profanity';
+
+const text = ref('');
+const isProfane = computed(() => filter.isProfane(text.value));
+</script>
+
+<template>
+  <textarea v-model="text" dir="auto" />
+  <p v-if="isProfane">يرجى الالتزام بالاحترام.</p>
+  <button :disabled="isProfane">إرسال</button>
+</template>
+```
+
+لتمييز الكلمات البذيئة، اعرض النص قطعًا مقسّمة عند `start` و `end` لكل تطابق من [`inspect()`](#inspecttext-string-options-profanitymatch)، وليس باستخدام `v-html`، حتى لا يستطيع نص المستخدم حقن HTML.
+
+في أي إطار عمل، افحص النص على الخادم أيضًا (مسار خادم في Nuxt أو أي خادم Node يستطيع استخدام الحزمة نفسها): الفحص في المتصفح يمكن تجاوزه باستدعاء الـ API مباشرة.
+
+## الواجهة البرمجية (API)
+
+### `new IraqiBadWordsFilter(options?)`
+
+ينشئ فلترًا بقائمة الكلمات المدمجة.
+
+```ts
+new IraqiBadWordsFilter();                               // الكلمات البذيئة فقط
+new IraqiBadWordsFilter({ includeInsults: true });       // والشتائم الأخف أيضًا
+new IraqiBadWordsFilter({ includePhrases: true });       // والعبارات البذيئة أيضًا
+new IraqiBadWordsFilter({ stripSuffixes: true });        // والصيغ بلواحق غير مدرجة أيضًا
+new IraqiBadWordsFilter({ dialects: ['mosul'] });        // وصيغ الموصل ر → غ أيضًا
+new IraqiBadWordsFilter({ customWords: ['word1', 'word2'] });
+new IraqiBadWordsFilter({ customWords: [{ word: 'word1', severity: 'mild' }] });
+new IraqiBadWordsFilter({ useDefaultList: false, customWords: ['word1'] }); // كلماتك فقط
+new IraqiBadWordsFilter({ safeWords: ['word3'] });        // كلمات سليمة لا تُعلَّم
+new IraqiBadWordsFilter(['word1', 'word2']);             // مثل customWords
+```
+
+| الخيار | الافتراضي | الوصف |
+|---|---|---|
+| `customWords` | `[]` | كلمات إضافية للفلترة، فوق القائمة المدمجة. يمكن أن تأتي من ملف JSON خاص بك (انظر أدناه). الكلمة `'strong'` ما لم تُعطَ بصيغة `{ word, severity }` (انظر [درجة الشدة](#درجة-الشدة)). |
+| `useDefaultList` | `true` | القيمة `false` تستبعد [`words.json`](src/words.json) المدمج، فلا تُفلتر إلا كلماتك. يبقى `includeInsults` و `includePhrases` يضيفان قائمتيهما، وتبقى الجذور الآمنة المدمجة. |
+| `safeWords` | `[]` | جذور آمنة إضافية، فوق [`safe-stems.json`](src/safe-stems.json) المدمج: كلمات سليمة كانت ستُطابَق بعد حذف سابقة أو لاحقة، مثل `بعير` المدمجة (`ب` + `عير`). استخدمه للكلمات السليمة التي يعلّمها تطبيقك خطأً، خاصة تلك التي تسببها كلمات `customWords` الخاصة بك. صيغها بالسوابق واللواحق آمنة أيضًا (`وبعيرك`). يمكن أن تأتي من ملف JSON خاص بك (انظر أدناه). |
+| `includeInsults` | `false` | يفلتر أيضًا الشتائم الأخف مثل كلب، حمار، قندرة، نعال. معطّل افتراضيًا لأن كثيرًا منها كلمات يومية، فتفعيله يعلّم جملًا مثل `عندي كلب`. |
+| `includePhrases` | `false` | يفلتر أيضًا العبارات في [`phrases.json`](src/phrases.json): كلمات سليمة تصبح بذيئة معًا، مثل `تعال العب بيه`. معطّل افتراضيًا لأن الكلمات نفسها قد تُقصد بمعناها الحرفي. |
+| `customPhrases` | `[]` | عبارات إضافية للفلترة، سواء كان `includePhrases` مفعّلًا أم لا. يمكن أن تأتي من ملف JSON خاص بك. العبارة `'strong'` ما لم تُعطَ بصيغة `{ phrase, severity }`. |
+| `stripSuffixes` | `false` | يطابق أيضًا الكلمات بلاحقة ضمير (ي ك ج ه ها نا كم هم) غير مكتوبة في القائمة، مثل `طيزهم` ← `طيز`. معطّل افتراضيًا لأنه يوسّع المطابقة: الكلمة السليمة التي تنتهي كأنها كلمة بذيئة مع لاحقة تُعلَّم أيضًا. |
+| `dialects` | `[]` | لهجات محلية تُطابَق أيضًا. `'mosul'`: تُلفظ ر غينًا، فكل مدخل فيه ر يطابق أيضًا صيغته بالغين (`شرموطة` ← `شغموطة`)، وتبقى صيغ الراء تُطابَق. والجذور الآمنة تحصل على صيغة الغين أيضًا. |
+
+#### استخدام ملفات كلماتك الخاصة
+
+احفظ الكلمات الإضافية لتطبيقك، والكلمات السليمة التي لا تريد تعليمها، في ملفات JSON: مصفوفات من كلمات مفردة، بنفس صيغة [`src/safe-stems.json`](src/safe-stems.json). والكلمة التي تحتاج [درجة شدة](#درجة-الشدة) خاصة بها يمكن أن تكون كائنًا:
+
+```json
+["زفت", { "word": "نذل", "severity": "mild" }]
+```
+
+استوردها ومرّرها في `customWords` و `safeWords`. تبقى القوائم المدمجة مفعّلة، وتُضاف كلماتك إليها:
+
+```ts
+import IraqiBadWordsFilter from 'iraqi-dialect-bad-words';
+import myWords from './my-words.json'; // يحتاج TypeScript إلى "resolveJsonModule": true
+import mySafeWords from './my-safe-words.json';
+// CommonJS: const myWords = require('./my-words.json');
+
+const filter = new IraqiBadWordsFilter({ customWords: myWords, safeWords: mySafeWords });
+```
+
+تمر كلماتك بنفس توحيد الكتابة الذي تمر به القوائم المدمجة، فلا تحتاج إلى إدراج الصيغ بالتشكيل أو ة/ه أو الحروف الممطوطة أو السوابق. تُحذف المسافات حول الكلمة وتُتجاهل المدخلات الفارغة. يبلّغ `inspect()` عن التطابق من ملف كلماتك بـ `source: 'custom'`، وعن التطابق الذي ألغته كلماتك الآمنة بـ `suppressedBy` مساويًا لتلك الكلمة الآمنة.
+
+الكلمة الآمنة لا تلغي إلا تطابقًا احتاج إلى حذف سابقة أو لاحقة، مثل الجذور الآمنة المدمجة. لمنع تعليم كلمة مدرجة في القائمة نفسها، استخدم `removeWords()`.
+
+تحزم React Native و Expo و Vite و Next.js ملفات JSON داخل تطبيقك، فيعمل هذا بالطريقة نفسها في كل منها. الفلتر لا يقرأ ملفات أثناء التشغيل. إذا كانت قوائمك تأتي من خادم، فاجلبها ومرّر المصفوفات إلى `addWords()` و `addSafeWords()`.
+
+### `isProfane(text: string): boolean`
+
+يرجع `true` إذا كانت أي كلمة في النص موجودة في القائمة.
+
+### `clean(text: string, placeholder = '*'): string`
+
+يستبدل كل كلمة بذيئة بالرمز البديل، مكررًا بطول الكلمة. تبقى المسافات وعلامات الترقيم كما هي.
+
+يمكن أن يكون البديل دالة أيضًا: تستلم كل تطابق من [`inspect()`](#inspecttext-string-options-profanitymatch) وترجع النص الذي يوضع مكانه. مثلًا، أبقِ الحرف الأول، أو أخفِ الكلمات الأشد فقط:
+
+```ts
+filter.clean('انت عارة', (match) => {
+  const [first, ...rest] = Array.from(match.token);  // يعدّ Array.from الحرف 𝐠 أو الإيموجي حرفًا واحدًا
+  return first + '*'.repeat(rest.length);
+});
+// 'انت ع***'
+
+filter.clean(text, (match) => (match.severity === 'mild' ? match.token : '***'));
+```
+
+### `inspect(text: string, options?): ProfanityMatch[]`
+
+يسرد كل كلمة بذيئة في النص ويشرح سبب مطابقتها. استخدمه لتمييز الكلمات، أو للتعامل مع الكلمات بحسب شدتها (مثلًا حظر `'severe'` والاكتفاء بالتحذير من `'mild'`)، أو ليراجع شخص التطابق قبل أن يحظره تطبيقك.
+
+```ts
+filter.inspect('روح للكواد!');
+// [{ token: 'للكواد', start: 4, end: 10, normalized: 'لكواد', entry: 'كواد',
+//    source: 'words', severity: 'strong', prefix: 'ل', suffix: '', rules: ['stretched', 'prefix'] }]
+```
+
+| الحقل | الوصف |
+|---|---|
+| `token` | الكلمة كما كُتبت تمامًا. |
+| `start`، `end` | المواقع في النص **الأصلي**، بحيث `text.slice(start, end) === token`. تُعدّ بوحدات سلاسل JavaScript ‏(UTF-16)؛ حوّلها إذا كانت منصة أخرى تعدّ الحروف بطريقة مختلفة. |
+| `normalized` | الكلمة بعد توحيد الكتابة (والعربيزي يُوحَّد أيضًا، فتظهر `Qa7ba` بصيغة `gahba`). للكلمة التي فيها گ، القراءة التي طابقت (ق أو ك). |
+| `entry` | المدخل الذي طابقته في القائمة، بالإملاء المكتوب في القائمة. لصيغة موصلية، الإملاء المدرج بالراء. |
+| `source` | `'words'` أو `'insults'` أو `'phrases'` أو `'custom'`. الكلمة الموجودة في أكثر من قائمة تحتفظ بالأولى: المدمجة، ثم الشتائم، ثم الخاصة. |
+| `severity` | `'mild'` أو `'strong'` أو `'severe'` (انظر أدناه). |
+| `prefix` | السابقة الملتصقة التي حُذفت قبل المطابقة (بعد توحيد الكتابة، فتظهر `لل` بصيغة `ل`)، أو `''` للتطابق المباشر. |
+| `suffix` | اللاحقة التي حُذفت قبل المطابقة (مع `stripSuffixes` فقط)، أو `''`. |
+| `rules` | القواعد التي احتاجتها الكلمة لتطابق المدخل (انظر أدناه). فارغة إذا كانت مكتوبة تمامًا مثل المدخل. |
+| `suppressedBy` | مع `includeSuppressed` فقط: الجذر الآمن الذي ألغى هذا التطابق. |
+
+مرّر `{ includeSuppressed: true }` لترى أيضًا الكلمات التي طابقت لكن ألغاها جذر آمن. هذه ليست بذيئة (يتجاهلها `isProfane` و `clean`)، لكنها تبيّن لماذا *لم* تُعلَّم الكلمة:
+
+```ts
+filter.inspect('وبعيرك', { includeSuppressed: true });
+// [{ token: 'وبعيرك', …, entry: 'عيرك', prefix: 'وب', rules: ['prefix'], suppressedBy: 'بعير' }]
+```
+
+يسرد `rules` القواعد التي أحدثت فرقًا بين الكلمة المكتوبة والمدخل فقط، فيبيّن التقرير مباشرة لماذا طابق شيء ما:
+
+| القاعدة | مثال |
+|---|---|
+| `unicode-forms` | `ﻋﻴﺮ`، `ｇａｈｂａ`، `𝐠𝐚𝐡𝐛𝐚` (أشكال العرض، والحروف كاملة العرض والرياضية) |
+| `diacritics` | `عَارَة`، `عـــارة` |
+| `invisible` | `عا‌رة` (حرف بعرض صفري داخلها) |
+| `spelling` | `عاره` (ة/ه، ى/ي، أ/ا) |
+| `keyboard` | `عیر`، `کس`، `پورنو` (حروف فارسية/كردية) |
+| `che-as-kaf` | `چلب` ← كلب |
+| `lookalike` | `gаhba` (حرف `а` سيريلي في كلمة لاتينية) |
+| `arabic-digits` | `ga٧ba` |
+| `stretched` | `عاااارة`، `للكواد` |
+| `glued-digits` | `عارة3` |
+| `arabizi` | `qa7ba` ← `gahba` |
+| `gaf-as-qaf` / `gaf-as-kaf` | `گحبة` ← قحبة، `گسها` ← كسها |
+| `prefix` / `suffix` | `بطيزك`، `ياعارة`، `طيزهم` (مع `stripSuffixes`) |
+| `mosul` | `شغموطة` ← شرموطة (مع `dialects: ['mosul']`) |
+| `phrase` | `تعال العب بيه` (مع `includePhrases`) |
+| `split` | `ع*ي*ر`، `ع ي ر` (القطع تُجمع من جديد) |
+| `repeated` | `عيرعير`، `gahbagahba` (مدخل مكتوب عدة مرات بلا مسافة) |
+| `symbols` | `g@hba`، `$harmoota` (‏@ بمعنى a، و $ بمعنى s) |
+
+#### درجة الشدة
+
+لكل تطابق `severity`، فيستطيع التطبيق أن يحظر بعض الكلمات ويكتفي بالتحذير من غيرها:
+
+| الدرجة | ماذا تشمل | أمثلة |
+|---|---|---|
+| `'mild'` | شتائم لها معنى يومي: كل ما في [`insults.json`](src/insults.json) | `كلب`، `حمار`، `قندرة` |
+| `'strong'` | كلمات بذيئة وشتائم ليس لها معنى سليم | `كواد`، `سرسري`، `يلعن ابوك` |
+| `'severe'` | كلمات جنسية وصريحة | `كس`، `شرموطة`، `تعال العب بيه` |
+
+كلماتك وعباراتك الخاصة `'strong'` ما لم تعطها درجة (`{ word: 'نذل', severity: 'mild' }`). والكلمة الموجودة أصلًا في قائمة مدمجة تحتفظ بدرجة تلك القائمة.
+
+```ts
+const matches = filter.inspect(comment);
+if (matches.some((match) => match.severity === 'severe')) rejectComment();
+else if (matches.length) flagForReview();
+```
+
+إرفاق ناتج `inspect` في [بلاغ “Clean word flagged”](https://github.com/karam-fikre/iraqi-dialect-bad-words/issues/new?template=false-positive.yml) يبيّن بالضبط أي مدخل طابق وأي قواعد احتاج؛ ونموذج البلاغ فيه حقل لذلك.
+
+### `addWords(words: (string | CustomWord)[]): void`
+
+يضيف كلمات إلى هذا الفلتر، مثل خيار `customWords`.
+
+### `addSafeWords(words: string[]): void` / `removeSafeWords(words: string[]): void`
+
+يضيف جذورًا آمنة إلى هذا الفلتر، مثل خيار `safeWords`، أو يحذفها، بما فيها المدمجة (مع صيغها الموصلية عند تفعيل اللهجة).
+
+### `removeWords(words: string[]): void`
+
+يحذف كلمات من هذا الفلتر، مثلًا كلمة مدمجة لا تريد تعليمها في تطبيقك.
+
+### `addPhrases(phrases: (string | CustomPhrase)[]): void` / `removePhrases(phrases: string[]): void`
+
+يضيف عبارات إلى هذا الفلتر، مثل خيار `customPhrases`، أو يحذفها، بما فيها المدمجة.
+
+العبارة هي كلماتها مفصولة بمسافات. ويمكن للكلمة أن تسرد بدائل مفصولة بـ `|`، فيغطي مدخل واحد كل التركيبات:
+
+```json
+[
+  "قوم|كوم بيه|بينو"
+]
+```
+
+يطابق `قوم بيه` و `قوم بينو` و `كوم بيه` و `كوم بينو`. تطابق العبارة عندما تأتي كلماتها واحدة بعد الأخرى وبينها مسافات أو علامات ترقيم فقط (`تعال، العب بيه!`). كل كلمة يُوحَّد إملاؤها مثل أي كلمة أخرى، فتطابق `گوم` البديل `قوم` من دون إدراجها. ويمكن للكلمة الأولى أن تحمل سابقة ملتصقة (`وتعال العب بيه`) أو دال الاستمرار العراقية `د` (`دقوم بيه`). الصيغ الأخرى لا تُحذف ولا تُخمَّن، فأدرج كل صيغة تريدها بديلًا.
+
+تُبلَّغ العبارة كاملة تطابقًا واحدًا بالقاعدة `phrase`، ويكون `entry` هو السطر كما أُدرج، ويخفيها `clean()` كلها. يأخذ `removePhrases()` السطر كما أُدرج؛ ولا يهم ترتيب بدائله.
+
+### قوائم الكلمات: `iraqi-dialect-bad-words/lists`
+
+القوائم المدمجة مُصدَّرة أيضًا وحدها، للأدوات التي لا تستطيع استخدام الفلتر (استعلام قاعدة بيانات، أو خادم بلغة أخرى):
+
+```ts
+import { words, insults, phrases, safeStems } from 'iraqi-dialect-bad-words/lists';
+
+words.severe;  // ['عارة', 'كس', …]
+words.strong;  // ['كواد', 'كواويد', …]
+insults;       // ['كلب', 'حمار', …]
+```
+
+‏`words` و `phrases` مجمّعة بحسب درجة الشدة؛ و `insults` كلها `'mild'`. المدخلات كما أُدرجت، ولا يمكن تعديلها. مطابقتها بمقارنة نصية بسيطة تلتقط أقل بكثير مما يلتقطه الفلتر: فهي لا توحّد الإملاء ولا تحذف السوابق ولا توحّد العربيزي ولا تضيف صيغ الموصل.
+
+## ماذا يلتقط
+
+تتم المطابقة على الكلمة كاملة، بعد توحيد كتابة النص وقائمة الكلمات معًا، فكل هذه تطابق المدخل نفسه:
+
+| الاختلاف | مثال |
+|---|---|
+| التشكيل | `عَارَة` |
+| الحروف الممطوطة | `عاااارة` |
+| التطويل | `عـــارة` |
+| ة / ه، ى / ي، أ / إ / آ / ا | `عاره` |
+| حروف لوحة المفاتيح الفارسية/الكردية ی ک ە پ ڤ | `عیر`، `کس`، `پورنو` |
+| گ تُقرأ ق (عراقيًا) وك (كما يكتبها الكرد) | `گحبة` = `قحبة`، `گس` = `كس` |
+| چ تُقرأ ك، لأن العراقي يلفظ الكاف چ في كلمات كثيرة | `چلب` = `كلب` |
+| حروف غير مرئية مخبأة داخل الكلمة (بعرض صفري، علامات اتجاه، شرطة ناعمة) | `عا‌رة` |
+| حروف مفصولة برموز، أو بمسافات بين حروف مفردة | `ع*ي*ر`، `ع.ي.ر`، `ع ي ر`، `عي * ر`، `شرم.وطة`، `g-a-h-b-a` |
+| أشكال العرض العربية، والحروف كاملة العرض والرياضية | `ﻋﻴﺮ`، `ｇａｈｂａ`، `𝐠𝐚𝐡𝐛𝐚` |
+| حروف يونانية أو سيريلية تشبه اللاتينية داخل كلمة لاتينية | `gаhba` (حرف `а` سيريلي) |
+| السوابق الملتصقة و ف ب ل ك ال، و يا / ويا | `والعارة`، `للعارة`، `ياعارة`، `يالعارة`، `وياعارة` |
+| لواحق الضمائر (مع `stripSuffixes`) | `طيزهم`، `وطيزكم` |
+| الكلمة نفسها مكتوبة عدة مرات بلا مسافة | `عيرعير`، `gahbagahba` |
+| علامات الترقيم الملاصقة للكلمة | `عارة!` `عارة،` |
+| أرقام ملتصقة بالكلمة العربية أو داخلها | `عارة3`، `عا٣رة` |
+| العربيزي (حروف وأرقام لاتينية، غربية أو هندية)، مع اختلافات الإملاء | `ga7ba` = `ga٧ba` = `qahba` = `gahba`، `kosomak` = `kusumak`، `3ayri` = `ayri`، `6eezak` = `teezak` (‏6 = ط)، `9awad` = `8awad` = `gawad` (‏9 و 8 = ق) |
+| ‏@ و $ بدل حروف في العربيزي | `g@hba`، `$harmoota` |
+
+لأن المطابقة على الكلمة كاملة، فالكلمة السليمة التي تحتوي كلمة بذيئة داخلها لا تُعلَّم.
+
+تُكتشف الكلمات المقسّمة بجمع القطع المتجاورة عندما تكون الفجوة بينها قصيرة، وعلى سطر واحد، وإما بلا مسافات (`عي*ر`)، أو بين حروف مفردة (`ع ي ر`)، أو فيها رمز بين قطع من حرف أو حرفين (`عي * ر`). الجمل العادية مثل `انا و انت` أو `د. علي` تبقى منفصلة، والكلمة المجموعة يجب أن تطابق مدخلًا تمامًا. والجذر الآمن المقسّم يبقى آمنًا: `ب ع ي ر` هي بعير.
+
+## القيود المعروفة
+
+- العبارات تطابق كما أُدرجت فقط، كلمة بكلمة: كلمة إضافية بينها (`تعال هنا العب بيه`) أو صيغة غير مدرجة (`بيهم`) لا تُطابَق.
+- الكلمات المختلفة الملتصقة بلا مسافة لا تُكتشف. أما الكلمة نفسها مكتوبة عدة مرات (`عيرعير`) فتُكتشف.
+- الحرف المستبدل برمز (`ع*ر`، `ك*بة`) لا يُكتشف: الرمز قد يعني أي حرف، و `ع*ر` قد تكون عمر.
+- القطع الأطول المفصولة بمسافات حول الرمز (`شرم * وطة`) لا تُجمع، حتى لا تُجمع الجمل العادية أيضًا.
+- لا توجد قائمة كلمات كاملة. استخدم هذه الحزمة طبقة واحدة من طبقات الإشراف على المحتوى، لا الطبقة الوحيدة.
+
+## المساهمة
+
+قائمة الكلمات هي قلب هذه الحزمة، وأهل اللهجة هم أفضل من يحكم عليها.
+
+- **كلمة ناقصة:** افتح [بلاغ “Suggest a word”](https://github.com/karam-fikre/iraqi-dialect-bad-words/issues/new?template=add-word.yml)، أو أضفها إلى [`src/words.json`](src/words.json) في طلب دمج (pull request).
+- **كلمة سليمة تُعلَّم خطأً:** افتح [بلاغ “Clean word flagged”](https://github.com/karam-fikre/iraqi-dialect-bad-words/issues/new?template=false-positive.yml).
+  إذا كانت تُعلَّم بسبب سابقة فقط (مثل `بعير` = `ب` + كلمة بذيئة)، فالحل إضافتها إلى [`src/safe-stems.json`](src/safe-stems.json).
+  الجذر الآمن المكتوب بـ گ يحمي الكلمات المكتوبة بـ گ فقط، فيمكن أن تكون `گلب` (قلب بالإملاء العراقي) آمنة بينما `كلب` ليست كذلك.
+
+- **جملة يُحكم عليها خطأً:** أضفها إلى [`test/fixtures/sentences.json`](test/fixtures/sentences.json) مع الحكم الذي يتوقعه ابن اللهجة (`"profane": true` أو `false`، مع `"options"` إذا احتاجت `includeInsults` أو `includePhrases` أو `stripSuffixes`). كل جملة هناك تعمل اختبارًا، فلا يمكن لتغييرات القائمة لاحقًا أن تقلب حكمها بصمت.
+- **نص سليم يُعلَّم:** أضفه إلى [`test/fixtures/clean-text.txt`](test/fixtures/clean-text.txt)، الذي يجب ألا ينتج أي تطابق أبدًا (مع `stripSuffixes` و `includePhrases` ولهجة الموصل أو من دونها)، ثم أصلح القوائم حتى تنجح الاختبارات من جديد.
+
+في [`src/words.json`](src/words.json)، الكلمات الجنسية والصريحة توضع تحت `"severe"` وباقي الكلمات البذيئة تحت `"strong"`. والكلمات التي لها أيضًا معنى عادي شائع (مثل كلب) مكانها [`src/insults.json`](src/insults.json)، وهي اختيارية وكلها `'mild'`، وليس `words.json`. والعبارات المكونة من كلمات سليمة تصبح بذيئة معًا مكانها [`src/phrases.json`](src/phrases.json)، وهي اختيارية أيضًا.
+
+### التطوير
+
+```bash
+npm install
+npm test           # تشغيل الاختبارات، ومنها فحوص قوائم الكلمات وفحص النص السليم
+npm run typecheck  # فحص الأنواع
+npm run build      # بناء dist/
+npm run size       # التأكد من أن الملفات المبنية ضمن حدود حجمها
+npm run smoke      # تحميل الحزمة المبنية بـ Node فقط، كما يفعل CI على Node 14-18
+npm run check -- article.txt --phrases   # سرد كل تطابق في ملف نصي
+```
+
+يشغّل `npm run check` الفلتر على ملف نصي (أو على stdin، مثل `pbpaste | npm run check`) ويطبع كل تطابق مع سطره وعموده، والمدخل الذي طابقه، ومصدره وقواعده، والنص المحيط به. الخيارات تفعّل الإعدادات: `--insults` و `--phrases` و `--suffixes` و `--mosul`، و `--clean` لطباعة النص بعد الإخفاء أيضًا. تشغيله على مقالات تعرف أنها سليمة هو أسرع طريقة لإيجاد التعليم الخاطئ: كل تطابق إما جذر آمن ناقص، أو كلمة مكانها قائمة اختيارية.
+
+يفحص `npm test` القوائم نفسها أيضًا: لا يجوز لمدخل أن يتوحّد إلى الكلمة نفسها كمدخل آخر (`گحبة` و `قحبة`، `qahba` و `gahba`)، ولا أن يكون مدخلًا يلتقطه الفلتر من دونه (`الكس` هي `ال` + `كس`)، وكل جذر آمن يجب أن يلغي تطابقًا. عندما يفشل مدخل جديد، تذكر الرسالة المدخل الذي يكرّره والقواعد التي تلتقطه أصلًا.
+
+هذا الملف ترجمة لـ [README.md](README.md). عند تغيير أحدهما، غيّر الآخر أيضًا.
+
+## الترخيص
+
+[MIT](LICENSE)

package/README.md

@@ -1,5 +1,7 @@
 # iraqi-dialect-bad-words
 
+**English** | [العربية](README.ar.md)
+
 [![npm version](https://img.shields.io/npm/v/iraqi-dialect-bad-words.svg)](https://www.npmjs.com/package/iraqi-dialect-bad-words)
 [![CI](https://github.com/karam-fikre/iraqi-dialect-bad-words/actions/workflows/ci.yml/badge.svg)](https://github.com/karam-fikre/iraqi-dialect-bad-words/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/iraqi-dialect-bad-words.svg)](LICENSE)
@@ -99,26 +101,29 @@ new IraqiBadWordsFilter({ includePhrases: true });       // also vulgar phrases
 new IraqiBadWordsFilter({ stripSuffixes: true });        // also unlisted suffix forms
 new IraqiBadWordsFilter({ dialects: ['mosul'] });        // also Mosul ر → غ forms
 new IraqiBadWordsFilter({ customWords: ['word1', 'word2'] });
+new IraqiBadWordsFilter({ customWords: [{ word: 'word1', severity: 'mild' }] });
+new IraqiBadWordsFilter({ useDefaultList: false, customWords: ['word1'] }); // your words only
 new IraqiBadWordsFilter({ safeWords: ['word3'] });        // clean words not to flag
 new IraqiBadWordsFilter(['word1', 'word2']);             // same as customWords
 ```
 
 | Option | Default | Description |
 |---|---|---|
-| `customWords` | `[]` | Extra words to filter, on top of the built-in list. Can come from your own JSON file (see below). |
+| `customWords` | `[]` | Extra words to filter, on top of the built-in list. Can come from your own JSON file (see below). A word is `'strong'` unless given as `{ word, severity }` (see [severity](#severity)). |
+| `useDefaultList` | `true` | `false` leaves out the built-in [`words.json`](src/words.json), so only your own words are filtered. `includeInsults` and `includePhrases` still add their lists, and the built-in safe stems stay. |
 | `safeWords` | `[]` | Extra safe stems, on top of the built-in [`safe-stems.json`](src/safe-stems.json): clean words that would otherwise match once a prefix or suffix is stripped, like the built-in `بعير` ("camel" = `ب` + `عير`). Use it for clean words your app sees flagged, especially ones your own `customWords` cause. Their prefixed and suffixed forms are safe too (`وبعيرك`). Can come from your own JSON file (see below). |
 | `includeInsults` | `false` | Also filter milder insults like كلب, حمار, قندرة, نعال. Off by default because many of them are everyday words, so turning it on flags sentences like `عندي كلب` ("I have a dog"). |
 | `includePhrases` | `false` | Also filter the phrases in [`phrases.json`](src/phrases.json): clean words that are vulgar together, like `تعال العب بيه`. Off by default because the same words can be meant literally ("come play with it"). |
-| `customPhrases` | `[]` | Extra phrases to filter, whether or not `includePhrases` is on. Can come from your own JSON file. |
+| `customPhrases` | `[]` | Extra phrases to filter, whether or not `includePhrases` is on. Can come from your own JSON file. A phrase is `'strong'` unless given as `{ phrase, severity }`. |
 | `stripSuffixes` | `false` | Also match words with a pronoun suffix (ي ك ج ه ها نا كم هم) that the list doesn't spell out, e.g. `طيزهم` → `طيز`. Off by default because it widens matching: a clean word that ends like a bad word plus a suffix gets flagged too. |
 | `dialects` | `[]` | Regional pronunciations to also match. `'mosul'`: ر said as غ, so every entry with ر also matches its غ form (`شرموطة` → `شغموطة`); the ر forms keep matching. Safe stems get their غ form too. |
 
 #### Using your own word files
 
-Keep your app's extra words, and clean words you don't want flagged, in JSON files: arrays of single words, the same format as [`src/words.json`](src/words.json) and [`src/safe-stems.json`](src/safe-stems.json).
+Keep your app's extra words, and clean words you don't want flagged, in JSON files: arrays of single words, the same format as [`src/safe-stems.json`](src/safe-stems.json). A word that needs its own [severity](#severity) can be an object instead:
 
 ```json
-["زفت", "نذل"]
+["زفت", { "word": "نذل", "severity": "mild" }]
 ```
 
 Import them and pass them as `customWords` and `safeWords`. The built-in lists stay on, and your words are added to them:
@@ -146,14 +151,26 @@ Returns `true` if any word in the text is on the list.
 
 Replaces each bad word with the placeholder, repeated to the word's length. Spaces and punctuation are kept.
 
+The placeholder can also be a function: it gets each match from [`inspect()`](#inspecttext-string-options-profanitymatch) and returns the text to put in its place. For example, keep the first letter, or mask only the stronger words:
+
+```ts
+filter.clean('انت عارة', (match) => {
+  const [first, ...rest] = Array.from(match.token);  // Array.from counts 𝐠 or an emoji as one letter
+  return first + '*'.repeat(rest.length);
+});
+// 'انت ع***'
+
+filter.clean(text, (match) => (match.severity === 'mild' ? match.token : '***'));
+```
+
 ### `inspect(text: string, options?): ProfanityMatch[]`
 
-Lists each bad word in the text and explains why it matched. Use it to highlight words, to treat lists differently (e.g. block `words` but only warn on `insults`), or to let someone review a match before your app blocks it.
+Lists each bad word in the text and explains why it matched. Use it to highlight words, to treat words differently by severity (e.g. block `'severe'` but only warn on `'mild'`), or to let someone review a match before your app blocks it.
 
 ```ts
 filter.inspect('روح للكواد!');
 // [{ token: 'للكواد', start: 4, end: 10, normalized: 'لكواد', entry: 'كواد',
-//    source: 'words', prefix: 'ل', suffix: '', rules: ['stretched', 'prefix'] }]
+//    source: 'words', severity: 'strong', prefix: 'ل', suffix: '', rules: ['stretched', 'prefix'] }]
 ```
 
 | Field | Description |
@@ -163,6 +180,7 @@ filter.inspect('روح للكواد!');
 | `normalized` | The word after normalization (Arabizi is folded too, so `Qa7ba` shows as `gahba`). For a word with گ, the reading that matched (ق or ك). |
 | `entry` | The list entry it matched, spelled as in the list. For a Mosul form, the listed ر spelling. |
 | `source` | `'words'`, `'insults'`, `'phrases'` or `'custom'`. A word on more than one list keeps the first: built-in, then insults, then custom. |
+| `severity` | `'mild'`, `'strong'` or `'severe'` (see below). |
 | `prefix` | The attached prefix stripped before matching (after normalization, so `لل` shows as `ل`), or `''` for a direct match. |
 | `suffix` | The suffix stripped before matching (only with `stripSuffixes`), or `''`. |
 | `rules` | The rules the word needed to match the entry (see below). Empty when it's spelled exactly like the entry. |
@@ -183,7 +201,8 @@ filter.inspect('وبعيرك', { includeSuppressed: true });
 | `diacritics` | `عَارَة`, `عـــارة` |
 | `invisible` | `عا‌رة` (zero-width character inside) |
 | `spelling` | `عاره` (ة/ه, ى/ي, أ/ا) |
-| `keyboard` | `عیر`, `کس` (Persian/Kurdish letters) |
+| `keyboard` | `عیر`, `کس`, `پورنو` (Persian/Kurdish letters) |
+| `che-as-kaf` | `چلب` → كلب |
 | `lookalike` | `gаhba` (Cyrillic `а` in a Latin word) |
 | `arabic-digits` | `ga٧ba` |
 | `stretched` | `عاااارة`, `للكواد` |
@@ -194,23 +213,42 @@ filter.inspect('وبعيرك', { includeSuppressed: true });
 | `mosul` | `شغموطة` → شرموطة (with `dialects: ['mosul']`) |
 | `phrase` | `تعال العب بيه` (with `includePhrases`) |
 | `split` | `ع*ي*ر`, `ع ي ر` (pieces joined again) |
+| `repeated` | `عيرعير`, `gahbagahba` (an entry typed several times with no space) |
 | `symbols` | `g@hba`, `$harmoota` (@ as a, $ as s) |
 
+#### Severity
+
+Every match has a `severity`, so an app can block some words and only warn on others:
+
+| Severity | What | Examples |
+|---|---|---|
+| `'mild'` | Insults with an everyday meaning: everything in [`insults.json`](src/insults.json) | `كلب`, `حمار`, `قندرة` |
+| `'strong'` | Profanity and insults with no clean meaning | `كواد`, `سرسري`, `يلعن ابوك` |
+| `'severe'` | Sexual and explicit words | `كس`, `شرموطة`, `تعال العب بيه` |
+
+Your own words and phrases are `'strong'` unless you give them a severity (`{ word: 'نذل', severity: 'mild' }`). A word already on a built-in list keeps that list's severity.
+
+```ts
+const matches = filter.inspect(comment);
+if (matches.some((match) => match.severity === 'severe')) rejectComment();
+else if (matches.length) flagForReview();
+```
+
 Including the output of `inspect` in a [“Clean word flagged” issue](https://github.com/karam-fikre/iraqi-dialect-bad-words/issues/new?template=false-positive.yml) shows exactly which entry matched and which rules it needed; the issue form has a field for it.
 
-### `addWords(words: string[]): void`
+### `addWords(words: (string | CustomWord)[]): void`
 
-Adds words to this filter.
+Adds words to this filter, like the `customWords` option.
 
-### `addSafeWords(words: string[]): void`
+### `addSafeWords(words: string[]): void` / `removeSafeWords(words: string[]): void`
 
-Adds safe stems to this filter, like the `safeWords` option.
+Adds safe stems to this filter, like the `safeWords` option, or removes them, including built-in ones (with their Mosul forms when the dialect is on).
 
 ### `removeWords(words: string[]): void`
 
 Removes words from this filter, for example a built-in word you don't want flagged in your app.
 
-### `addPhrases(phrases: string[]): void` / `removePhrases(phrases: string[]): void`
+### `addPhrases(phrases: (string | CustomPhrase)[]): void` / `removePhrases(phrases: string[]): void`
 
 Adds phrases to this filter, like the `customPhrases` option, or removes them, including built-in ones.
 
@@ -226,6 +264,20 @@ matches `قوم بيه`, `قوم بينو`, `كوم بيه` and `كوم بينو
 
 The whole phrase is reported as one match with the rule `phrase`, its `entry` being the line as listed, and `clean()` masks all of it. `removePhrases()` takes a line as listed; the order of its alternatives doesn't matter.
 
+### The word lists: `iraqi-dialect-bad-words/lists`
+
+The built-in lists are also exported on their own, for tools that can't use the filter (a database query, a backend in another language):
+
+```ts
+import { words, insults, phrases, safeStems } from 'iraqi-dialect-bad-words/lists';
+
+words.severe;  // ['عارة', 'كس', …]
+words.strong;  // ['كواد', 'كواويد', …]
+insults;       // ['كلب', 'حمار', …]
+```
+
+`words` and `phrases` are grouped by severity; `insults` are all `'mild'`. The entries are as listed, and they can't be changed. Matching them by plain string comparison catches far less than the filter: it doesn't normalize spelling, strip prefixes, fold Arabizi or add Mosul forms.
+
 ## What it catches
 
 Matching is done per whole word, after normalizing both the text and the word list, so these all match the same entry:
@@ -236,14 +288,16 @@ Matching is done per whole word, after normalizing both the text and the word li
 | Stretched letters | `عاااارة` |
 | Tatweel | `عـــارة` |
 | ة / ه, ى / ي, أ / إ / آ / ا | `عاره` |
-| Persian/Kurdish keyboard letters ی ک ە | `عیر`, `کس` |
+| Persian/Kurdish keyboard letters ی ک ە پ ڤ | `عیر`, `کس`, `پورنو` |
 | گ read as ق (Iraqi) and as ك (Kurdish typists) | `گحبة` = `قحبة`, `گس` = `كس` |
+| چ read as ك, as Iraqi says ك in many words | `چلب` = `كلب` |
 | Invisible characters hidden inside a word (zero-width, direction marks, soft hyphen) | `عا‌رة` |
 | Letters split by symbols, or by spaces between single letters | `ع*ي*ر`, `ع.ي.ر`, `ع ي ر`, `عي * ر`, `شرم.وطة`, `g-a-h-b-a` |
 | Arabic presentation forms, full-width and mathematical letters | `ﻋﻴﺮ`, `ｇａｈｂａ`, `𝐠𝐚𝐡𝐛𝐚` |
 | Greek or Cyrillic look-alike letters in a Latin word | `gаhba` (Cyrillic `а`) |
 | Attached prefixes و ف ب ل ك ال, and يا / ويا | `والعارة`, `للعارة`, `ياعارة`, `يالعارة`, `وياعارة` |
 | Pronoun suffixes (with `stripSuffixes`) | `طيزهم`, `وطيزكم` |
+| The same word typed several times with no space | `عيرعير`, `gahbagahba` |
 | Punctuation next to the word | `عارة!` `عارة،` |
 | Digits glued to or inside an Arabic word | `عارة3`, `عا٣رة` |
 | Arabizi (Latin letters and numbers, Western or Arabic-Indic), including spelling variants | `ga7ba` = `ga٧ba` = `qahba` = `gahba`, `kosomak` = `kusumak`, `3ayri` = `ayri`, `6eezak` = `teezak` (6 = ط), `9awad` = `8awad` = `gawad` (9, 8 = ق) |
@@ -256,7 +310,7 @@ Split words are found by joining neighbouring pieces when the gap between them i
 ## Known limitations
 
 - Phrases match only as listed, word for word: another word in between (`تعال هنا العب بيه`) or an unlisted form (`بيهم`) isn't matched.
-- Words glued together without a space (e.g. the same word typed twice) aren't detected.
+- Different words glued together without a space aren't detected. The same word typed several times (`عيرعير`) is.
 - A letter replaced by a symbol (`ع*ر`, `ك*بة`) isn't detected: the symbol could stand for any letter, and `ع*ر` could just as well be عمر.
 - Longer pieces split with spaces around the symbol (`شرم * وطة`) aren't joined, so normal sentences aren't either.
 - No word list is complete. Use this as one layer of moderation, not the only one.
@@ -271,21 +325,28 @@ The word list is the heart of this package, and native speakers are the best jud
   A safe stem written with گ protects only words spelled with گ, so `گلب` ("heart", Iraqi spelling of قلب) can be safe while `كلب` is not.
 
 - **A sentence is judged wrong:** add it to [`test/fixtures/sentences.json`](test/fixtures/sentences.json) with the verdict a native speaker expects (`"profane": true` or `false`, plus `"options"` if it needs `includeInsults`, `includePhrases` or `stripSuffixes`). Every sentence there runs as a test, so later word-list changes can't silently flip it.
+- **Clean text gets flagged:** add it to [`test/fixtures/clean-text.txt`](test/fixtures/clean-text.txt), which must never produce a match (with or without `stripSuffixes`, `includePhrases` and the Mosul dialect), then fix the lists until the tests pass again.
 
-Words that also have a common, normal meaning (like كلب "dog") belong in [`src/insults.json`](src/insults.json), which is opt-in, not in `words.json`. Phrases of clean words that are vulgar together belong in [`src/phrases.json`](src/phrases.json), also opt-in.
+In [`src/words.json`](src/words.json), sexual and explicit words go under `"severe"` and other profanity under `"strong"`. Words that also have a common, normal meaning (like كلب "dog") belong in [`src/insults.json`](src/insults.json), which is opt-in and all `'mild'`, not in `words.json`. Phrases of clean words that are vulgar together belong in [`src/phrases.json`](src/phrases.json), also opt-in.
 
 ### Development
 
 ```bash
 npm install
-npm test           # run tests
+npm test           # run tests, including the word-list checks and the clean-text check
 npm run typecheck  # type-check
 npm run build      # build dist/
+npm run size       # check the built files are within their size budgets
+npm run smoke      # load the built package with plain Node, as CI does on Node 14-18
 npm run check -- article.txt --phrases   # list every match in a text file
 ```
 
 `npm run check` runs the filter over a text file (or stdin, e.g. `pbpaste | npm run check`) and prints each match with its line and column, the entry it matched, its source and rules, and the text around it. Flags turn on options: `--insults`, `--phrases`, `--suffixes`, `--mosul`, and `--clean` to also print the masked text. Running it on articles you know are clean is the quickest way to find false positives: each match is either a missing safe stem or a word that belongs in an opt-in list.
 
+`npm test` also checks the lists themselves: no entry may normalize to the same word as another (`گحبة` and `قحبة`, `qahba` and `gahba`), no entry may be one the filter already catches without it (`الكس` is `ال` + `كس`), and every safe stem must clear a match. When a new entry fails, the message names the entry it duplicates and the rules that already catch it.
+
+[README.ar.md](README.ar.md) is an Arabic translation of this file. When you change one, change the other too.
+
 ## License
 
 [MIT](LICENSE)