iraqi-dialect-bad-words 1.2.1 → 1.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 A profanity filter for the Iraqi Arabic dialect. Detects and masks bad words in user-generated text.
 
-Works in **React Native / Expo**, **React** (Vite, Next.js, CRA, …) and **Node.js**, with TypeScript types included. No dependencies.
+Works in **React Native / Expo**, **React** (Vite, Next.js, CRA, …), **Vue** (Vite, Nuxt) and **Node.js**, with TypeScript types included. No dependencies.
 
 ## Install
 
@@ -55,6 +55,37 @@ export function CommentInput() {
 }
 ```
 
+### Vue example
+
+Create the filter once in its own module and import it where you need it. Keep it out of `ref()` and `reactive()`: the filter never changes, and wrapping it in reactive proxies only slows every check down.
+
+```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">Please keep it respectful.</p>
+  <button :disabled="isProfane">Send</button>
+</template>
+```
+
+To highlight bad words, render the text in pieces split at the `start` and `end` of each match from [`inspect()`](#inspecttext-string-options-profanitymatch) rather than with `v-html`, so user text can't inject HTML.
+
+In any framework, check the text on your server too (a Nuxt server route or any Node backend can use the same package): a check in the browser can be skipped by calling your API directly.
+
 ## API
 
 ### `new IraqiBadWordsFilter(options?)`
@@ -64,16 +95,48 @@ Creates a filter with the built-in word list.
 ```ts
 new IraqiBadWordsFilter();                               // profanity only
 new IraqiBadWordsFilter({ includeInsults: true });       // also milder insults
+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({ safeWords: ['word3'] });        // clean words not to flag
 new IraqiBadWordsFilter(['word1', 'word2']);             // same as customWords
 ```
 
 | Option | Default | Description |
 |---|---|---|
-| `customWords` | `[]` | Extra words to filter. |
+| `customWords` | `[]` | Extra words to filter, on top of the built-in list. Can come from your own JSON file (see below). |
+| `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. |
 | `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).
+
+```json
+["زفت", "نذل"]
+```
+
+Import them and pass them as `customWords` and `safeWords`. The built-in lists stay on, and your words are added to them:
+
+```ts
+import IraqiBadWordsFilter from 'iraqi-dialect-bad-words';
+import myWords from './my-words.json'; // TypeScript needs "resolveJsonModule": true
+import mySafeWords from './my-safe-words.json';
+// CommonJS: const myWords = require('./my-words.json');
+
+const filter = new IraqiBadWordsFilter({ customWords: myWords, safeWords: mySafeWords });
+```
+
+Your words go through the same normalization as the built-in lists, so you don't need to list diacritic, ة/ه, stretched or prefixed spellings. Whitespace around a word is trimmed and blank entries are skipped. `inspect()` reports a match from your word file with `source: 'custom'`, and a match cleared by your safe words with `suppressedBy` set to that safe word.
+
+A safe word only clears a match that needed a prefix or suffix stripped, like the built-in safe stems. To stop a listed word itself from being flagged, use `removeWords()`.
+
+React Native, Expo, Vite and Next.js bundle the JSON files into your app, so this works the same in each. The filter doesn't read files at runtime. If your lists come from a server, fetch them and pass the arrays to `addWords()` and `addSafeWords()`.
 
 ### `isProfane(text: string): boolean`
 
@@ -89,38 +152,80 @@ Lists each bad word in the text and explains why it matched. Use it to highlight
 
 ```ts
 filter.inspect('روح للكواد!');
-// [{ token: 'للكواد', start: 4, end: 10, normalized: 'لكواد',
-//    entry: 'كواد', source: 'words', prefix: 'ل' }]
+// [{ token: 'للكواد', start: 4, end: 10, normalized: 'لكواد', entry: 'كواد',
+//    source: 'words', prefix: 'ل', suffix: '', rules: ['stretched', 'prefix'] }]
 ```
 
 | Field | Description |
 |---|---|
 | `token` | The word exactly as written. |
 | `start`, `end` | Offsets in the **original** text, so `text.slice(start, end) === token`. Counted in JavaScript string units (UTF-16); convert them if another platform counts characters differently. |
-| `normalized` | The word after normalization (Arabizi is folded too, so `Qa7ba` shows as `gahba`). |
-| `entry` | The list entry it matched, spelled as in the list. |
-| `source` | `'words'`, `'insults'` or `'custom'`. A word on more than one list keeps the first: built-in, then insults, then custom. |
+| `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. |
 | `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. |
 | `suppressedBy` | Only with `includeSuppressed`: the safe stem that cleared this match. |
 
 Pass `{ includeSuppressed: true }` to also see words that matched but were cleared by a safe stem. They are not profane (`isProfane` and `clean` ignore them), but they show why a word *wasn't* flagged:
 
 ```ts
 filter.inspect('وبعيرك', { includeSuppressed: true });
-// [{ token: 'وبعيرك', …, entry: 'عيرك', prefix: 'وب', suppressedBy: 'بعير' }]
+// [{ token: 'وبعيرك', …, entry: 'عيرك', prefix: 'وب', rules: ['prefix'], suppressedBy: 'بعير' }]
 ```
 
-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 and prefix rule fired.
+`rules` lists only the rules that made a difference between the typed word and the entry, so a report shows straight away why something matched:
+
+| Rule | Example |
+|---|---|
+| `unicode-forms` | `ﻋﻴﺮ`, `ｇａｈｂａ`, `𝐠𝐚𝐡𝐛𝐚` (presentation forms, full-width and mathematical letters) |
+| `diacritics` | `عَارَة`, `عـــارة` |
+| `invisible` | `عا‌رة` (zero-width character inside) |
+| `spelling` | `عاره` (ة/ه, ى/ي, أ/ا) |
+| `keyboard` | `عیر`, `کس` (Persian/Kurdish letters) |
+| `lookalike` | `gаhba` (Cyrillic `а` in a Latin word) |
+| `arabic-digits` | `ga٧ba` |
+| `stretched` | `عاااارة`, `للكواد` |
+| `glued-digits` | `عارة3` |
+| `arabizi` | `qa7ba` → `gahba` |
+| `gaf-as-qaf` / `gaf-as-kaf` | `گحبة` → قحبة, `گسها` → كسها |
+| `prefix` / `suffix` | `بطيزك`, `ياعارة`, `طيزهم` (with `stripSuffixes`) |
+| `mosul` | `شغموطة` → شرموطة (with `dialects: ['mosul']`) |
+| `phrase` | `تعال العب بيه` (with `includePhrases`) |
+| `split` | `ع*ي*ر`, `ع ي ر` (pieces joined again) |
+| `symbols` | `g@hba`, `$harmoota` (@ as a, $ as s) |
+
+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`
 
 Adds words to this filter.
 
+### `addSafeWords(words: string[]): void`
+
+Adds safe stems to this filter, like the `safeWords` option.
+
 ### `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`
+
+Adds phrases to this filter, like the `customPhrases` option, or removes them, including built-in ones.
+
+A phrase is its words separated by spaces. A word can list alternatives separated by `|`, so one entry covers every combination:
+
+```json
+[
+  "قوم|كوم بيه|بينو"
+]
+```
+
+matches `قوم بيه`, `قوم بينو`, `كوم بيه` and `كوم بينو`. A phrase matches when its words appear one after another with only spaces or punctuation between them (`تعال، العب بيه!`). Each word is normalized like any other, so `گوم` matches the `قوم` alternative without listing it. The first word can carry an attached prefix (`وتعال العب بيه`) or the Iraqi progressive `د` (`دقوم بيه`). Other forms aren't stripped or guessed, so list each one you want as an alternative.
+
+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.
+
 ## 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:
@@ -132,19 +237,28 @@ Matching is done per whole word, after normalizing both the text and the word li
 | Tatweel | `عـــارة` |
 | ة / ه, ى / ي, أ / إ / آ / ا | `عاره` |
 | Persian/Kurdish keyboard letters ی ک ە | `عیر`, `کس` |
+| گ read as ق (Iraqi) and as ك (Kurdish typists) | `گحبة` = `قحبة`, `گس` = `كس` |
 | Invisible characters hidden inside a word (zero-width, direction marks, soft hyphen) | `عا‌رة` |
-| Attached prefixes و ف ب ل ك ال | `والعارة`, `للعارة` |
+| 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`) | `طيزهم`, `وطيزكم` |
 | 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` |
+| 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 = ق) |
+| @ and $ standing in for letters in Arabizi | `g@hba`, `$harmoota` |
 
 Because matching is whole-word, a clean word that merely contains a bad word is not flagged.
 
+Split words are found by joining neighbouring pieces when the gap between them is short, on one line, and either has no spaces (`عي*ر`), sits between single letters (`ع ي ر`), or has a symbol between pieces of one or two letters (`عي * ر`). Normal sentences like `انا و انت` or `د. علي` stay apart, and the joined word must match an entry exactly. A split safe stem stays safe: `ب ع ي ر` is بعير (camel).
+
 ## Known limitations
 
-- Phrases (multiple words) can't be list entries; each entry is a single word.
+- 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.
+- 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.
 
 ## Contributing
@@ -154,10 +268,11 @@ The word list is the heart of this package, and native speakers are the best jud
 - **A word is missing:** open a [“Suggest a word” issue](https://github.com/karam-fikre/iraqi-dialect-bad-words/issues/new?template=add-word.yml), or add it to [`src/words.json`](src/words.json) in a pull request.
 - **A clean word is flagged:** open a [“Clean word flagged” issue](https://github.com/karam-fikre/iraqi-dialect-bad-words/issues/new?template=false-positive.yml).
   If it's flagged only because of a prefix (e.g. `بعير` "camel" = `ب` + a bad word), the fix is adding it to [`src/safe-stems.json`](src/safe-stems.json).
+  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` or `stripSuffixes`). Every sentence there runs as a test, so later word-list changes can't silently flip it.
+- **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.
 
-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`.
+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.
 
 ### Development
 
@@ -166,8 +281,11 @@ npm install
 npm test           # run tests
 npm run typecheck  # type-check
 npm run build      # build dist/
+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.
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.d.mts

@@ -1,20 +1,55 @@
+/**
+ * A rule a word needed to match its list entry, reported in ProfanityMatch.rules.
+ * Only rules that made a difference are reported: عارة matching عارة has none.
+ */
+type MatchRule = "unicode-forms" | "diacritics" | "invisible" | "spelling" | "keyboard" | "lookalike" | "arabic-digits" | "stretched" | "glued-digits" | "arabizi" | "gaf-as-qaf" | "gaf-as-kaf" | "prefix" | "suffix" | "mosul" | "split" | "symbols" | "phrase";
 interface IraqiBadWordsFilterOptions {
-    /** Extra words to filter, on top of the built-in list. */
+    /**
+     * Extra words to filter, on top of the built-in list. Can be your own JSON
+     * word file: `customWords: require('./my-words.json')`.
+     */
     customWords?: string[];
+    /**
+     * Extra safe stems, on top of the built-in safe-stems.json: clean words that
+     * would otherwise match once a prefix or suffix is stripped, like the
+     * built-in بعير ("camel" = ب + عير). Their prefixed and suffixed forms are
+     * safe too (وبعيرك).
+     * Can be your own JSON file: `safeWords: require('./my-safe-words.json')`.
+     */
+    safeWords?: string[];
     /**
      * Also filter milder insults (كلب, حمار, قندرة, …). Off by default because
      * many of them are everyday words ("عندي كلب", "جلب لي هدية").
      */
     includeInsults?: boolean;
+    /**
+     * Also filter phrases (phrases.json) whose words are clean on their own but
+     * vulgar together (تعال العب بيه). Off by default because the same words can
+     * be meant literally ("come play with it").
+     */
+    includePhrases?: boolean;
+    /**
+     * Extra phrases to filter, whatever includePhrases is. Can be your own JSON
+     * file: `customPhrases: require('./my-phrases.json')`.
+     */
+    customPhrases?: string[];
     /**
      * Also match words with a pronoun suffix the list doesn't spell out
      * (طيزهم -> طيز). Off by default: it widens matching, so it can flag
      * clean words that happen to end like a bad word plus a suffix.
      */
     stripSuffixes?: boolean;
+    /**
+     * Regional pronunciations to also match. "mosul": ر said as غ, so every entry
+     * and safe stem with ر also matches its غ form (عير -> عيغ, بعير -> بعيغ).
+     * The ر forms keep matching. Off by default.
+     */
+    dialects?: Dialect[];
 }
+/** A regional pronunciation the filter can also match. */
+type Dialect = "mosul";
 /** Which list a dictionary entry came from. */
-type WordSource = "words" | "insults" | "custom";
+type WordSource = "words" | "insults" | "phrases" | "custom";
 interface InspectOptions {
     /**
      * Also return words that matched but were cleared by a safe stem
@@ -24,7 +59,7 @@ interface InspectOptions {
 }
 /** A bad word found by inspect(). */
 interface ProfanityMatch {
-    /** The word exactly as written in the input. */
+    /** The word (or phrase) exactly as written in the input. */
     token: string;
     /**
      * Offset of the word in the input; text.slice(start, end) === token.
@@ -33,9 +68,15 @@ interface ProfanityMatch {
     start: number;
     /** Offset just past the end of the word in the input. */
     end: number;
-    /** The word after normalization (diacritics, stretched letters, … removed). */
+    /**
+     * The word after normalization (diacritics, stretched letters, … removed).
+     * For a word with گ, the reading that matched: گ as ق or as ك.
+     */
     normalized: string;
-    /** The dictionary entry it matched, spelled as in its list. */
+    /**
+     * The dictionary entry (word or phrase) it matched, spelled as in its list. For a Mosul form
+     * (rule "mosul"), the listed ر spelling: الشرموطة for الشغموطة.
+     */
     entry: string;
     /** The list the entry came from. */
     source: WordSource;
@@ -43,8 +84,10 @@ interface ProfanityMatch {
     prefix: string;
     /** The suffix stripped before matching (only with stripSuffixes), or "". */
     suffix: string;
+    /** The rules the word needed to match the entry, e.g. ["prefix", "arabizi"]. */
+    rules: MatchRule[];
     /**
-     * The safe stem that cleared this match, spelled as in safe-stems.json.
+     * The safe stem that cleared this match, spelled as in safe-stems.json or safeWords.
      * Only set on matches returned with `includeSuppressed`; these are not profane.
      */
     suppressedBy?: string;
@@ -53,42 +96,135 @@ declare class IraqiBadWordsFilter {
     private words;
     private safeStems;
     private stripSuffixes;
+    private mosul;
+    private entryStarts;
+    private longest;
+    private normalized;
+    private phrases;
     constructor(options?: string[] | IraqiBadWordsFilterOptions);
     /**
-     * Normalizes Arabic text so spelling variants compare equal:
-     * removes diacritics (Tashkeel), tatweel and invisible characters, unifies
-     * Alef/Teh Marbuta/Alef Maksura forms and the Persian/Kurdish keyboard letters
-     * ی ک ە, turns Arabic-Indic digits into 0-9, and collapses stretched letters
-     * (عاااارة -> عارة).
+     * Normalizes a word or token for comparison: removes diacritics, tatweel and
+     * invisible characters, unifies letter variants (أ/ا, ة/ه, ی/ي, ک/ك, …),
+     * reads Arabic-Indic digits, collapses stretched letters (عاااارة -> عارة),
+     * ignores digits in Arabic words and folds Arabizi. See NORMALIZE_STEPS.
      */
-    private normalizeArabic;
+    private normalize;
     /**
-     * Folds Arabizi (Arabic written in Latin letters and digits) so spelling
-     * variants compare equal: ga7ba / qahba / gahba, kosomak / kusomak,
-     * teezak / tizak. Only words made purely of Latin letters and digits are
-     * folded; expects text already passed through normalizeArabic.
+     * The ways a normalized word can be read. Iraqi Arabic writes ق as گ, but
+     * Kurdish typists sometimes use گ for ك, so a word with گ is tried both ways.
      */
-    private foldArabizi;
-    /** Normalizes a word or token for comparison. */
-    private normalize;
+    private readings;
+    /** A list word plus its regional forms (عير -> عير, عيغ with the Mosul dialect). */
+    private dialectForms;
+    /** The key a list word is stored under. A گ in a list entry means ق. */
+    private entryKey;
+    /**
+     * A word list with surrounding whitespace trimmed and entries that are empty
+     * after normalization skipped. A stray "" in a user's file would otherwise
+     * match a lone tatweel as a word, or clear every match as a safe stem.
+     */
+    private cleanList;
+    /**
+     * Adds safe stems from one list. A safe stem written with گ protects only
+     * words spelled with گ (گلب "heart"), so it isn't read as ق or ك.
+     */
+    private addSafeStems;
     /**
      * Adds words from one list. A word already present keeps its first source.
      */
     private addEntries;
+    /**
+     * Reads a listed phrase: words separated by spaces, each with its alternatives
+     * separated by | (قوم|كوم بيه|بينو). Punctuation in a word is ignored, and
+     * alternatives that are empty after normalization (a lone tatweel) are left
+     * out. With the Mosul dialect, an alternative with ر also has its غ form.
+     * Phrases that match the same text get the same id.
+     */
+    private parsePhrase;
+    /**
+     * Adds phrases from one list, indexed by each alternative of their first word.
+     * A phrase already present keeps its first source.
+     */
+    private addPhraseEntries;
+    /**
+     * The first word of a phrase with attached prefixes removed, and also the
+     * Iraqi progressive د (دقوم بيه, ودقوم بيه).
+     */
+    private phraseCandidates;
     /**
      * Checks a single word, also trying it with attached prefixes removed
      * (والكحبة -> كحبة, بطيزك -> طيزك), and suffixes removed when stripSuffixes is on.
      * Returns the matched entry, or null.
      * A match cleared by a safe stem is returned with `suppressedBy` set.
+     * Pass `spelled` when the token is already normalized.
      */
     private matchWord;
     /**
-     * Finds every match in the text, including ones cleared by a safe stem.
+     * Works out which rules a match needed, by comparing the typed word with the
+     * listed spelling (plus any stripped prefix and suffix). A normalization rule
+     * counts only if leaving it out would keep them apart: عاااارة vs عارة needs
+     * "stretched" but not "spelling", since both have ة.
+     */
+    private explain;
+    /** The word plus each form of it with an attached prefix removed. */
+    private prefixCandidates;
+    /** The first safe stem one of the candidates starts with, as listed. */
+    private findSafe;
+    /** Matches one normalized reading of a word. */
+    private matchReading;
+    /**
+     * Finds every match in the text, including ones cleared by a safe stem: whole
+     * words, phrases, words split into pieces, and Arabizi words with symbols as
+     * letters. Matches from different passes can overlap; inspect() resolves that.
+     */
+    private findMatches;
+    /**
+     * Finds listed phrases: their words one after another, with only spaces or
+     * punctuation between them, each one of its alternatives. Each word is
+     * normalized like any other, and the first can carry an attached prefix
+     * (وتعال العب بيه) or the progressive د (دقوم بيه). The longest phrase wins.
+     */
+    private findPhraseMatches;
+    /**
+     * Matches each word in the text.
      * A token with invisible characters is matched whole first (عا‌رة -> عارة);
      * if that finds nothing profane, each visible piece is tried on its own, so an
      * invisible character between two words can't hide a bad word either.
      */
-    private findMatches;
+    private findWordMatches;
+    /**
+     * Whether two neighbouring pieces can be one split word. The gap between them
+     * must be short and on one line, and either have no spaces (عي*ر, شرم.وطة),
+     * sit between single letters (ع ي ر), or have a symbol between pieces of at
+     * most two letters (عي * ر). Normal sentences (انا و انت, كلمة، كلمة) stay apart.
+     * `size` gives a piece's normalized length, worked out only when needed.
+     */
+    private joinable;
+    /**
+     * Whether a normalized word, or a longer one made by joining more pieces to
+     * it, could still match an entry: it must be the start of a prefix, or a
+     * prefix plus the start of an entry (or of an entry and a suffix). A word
+     * with no letters yet (digits only) always could.
+     */
+    private couldMatch;
+    /**
+     * Finds bad words split into pieces by symbols or spaces (ع*ي*ر, ع ي ر,
+     * g-a-h-b-a) by joining neighbouring pieces again. From each piece, the
+     * longest joined stretch that matches wins, and its span covers the separators.
+     */
+    private findSplitMatches;
+    /**
+     * Finds Arabizi words with @ or $ standing in for a letter (g@hba, $harmoota).
+     * A word glued to other letters, like an Arabic word, is left to the other passes.
+     */
+    private findSymbolMatches;
+    /**
+     * Puts matches in text order and drops overlapping ones, so each span is
+     * reported and masked once. Real matches go before ones cleared by a safe
+     * stem, then earlier and longer before later or shorter: ع*ي*ر is one match,
+     * not also its pieces.
+     */
+    private resolveOverlaps;
     /**
      * Checks if a given text contains profane words.
      */
@@ -106,10 +242,23 @@ declare class IraqiBadWordsFilter {
      * Dynamically add words to the active dictionary.
      */
     addWords(newWords: string[]): void;
+    /**
+     * Add safe stems to this filter, like the safeWords option.
+     */
+    addSafeWords(newWords: string[]): void;
     /**
      * Remove words from the active filter dictionary.
      */
     removeWords(wordsToRemove: string[]): void;
+    /**
+     * Add phrases to this filter, like the customPhrases option.
+     */
+    addPhrases(newPhrases: string[]): void;
+    /**
+     * Remove phrases from this filter, for example a built-in phrase you don't want
+     * flagged. Pass the phrase as listed, alternatives included.
+     */
+    removePhrases(phrasesToRemove: string[]): void;
 }
 
-export { type InspectOptions, IraqiBadWordsFilter, type IraqiBadWordsFilterOptions, type ProfanityMatch, type WordSource, IraqiBadWordsFilter as default };
+export { type Dialect, type InspectOptions, IraqiBadWordsFilter, type IraqiBadWordsFilterOptions, type MatchRule, type ProfanityMatch, type WordSource, IraqiBadWordsFilter as default };