iraqi-dialect-bad-words 1.3.0 → 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,6 +95,7 @@ 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'] });
@@ -76,6 +108,8 @@ new IraqiBadWordsFilter(['word1', 'word2']);             // same as customWords
 | `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. |
 
@@ -128,7 +162,7 @@ filter.inspect('روح للكواد!');
 | `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`). 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'` or `'custom'`. A word on more than one list keeps the first: built-in, then insults, then custom. |
+| `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. |
@@ -145,17 +179,22 @@ filter.inspect('وبعيرك', { includeSuppressed: true });
 
 | 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`) |
+| `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.
 
@@ -171,6 +210,22 @@ Adds safe stems to this filter, like the `safeWords` option.
 
 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:
@@ -184,18 +239,26 @@ Matching is done per whole word, after normalizing both the text and the word li
 | 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
@@ -207,9 +270,9 @@ The word list is the heart of this package, and native speakers are the best jud
   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
 
@@ -218,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

@@ -2,7 +2,7 @@
  * 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 = "diacritics" | "invisible" | "spelling" | "keyboard" | "arabic-digits" | "stretched" | "glued-digits" | "arabizi" | "gaf-as-qaf" | "gaf-as-kaf" | "prefix" | "suffix" | "mosul";
+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. Can be your own JSON
@@ -22,6 +22,17 @@ interface IraqiBadWordsFilterOptions {
      * 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
@@ -38,7 +49,7 @@ interface IraqiBadWordsFilterOptions {
 /** 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
@@ -48,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.
@@ -63,7 +74,7 @@ interface ProfanityMatch {
      */
     normalized: string;
     /**
-     * The dictionary entry it matched, spelled as in its list. For a Mosul form
+     * 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;
@@ -86,6 +97,10 @@ declare class IraqiBadWordsFilter {
     private safeStems;
     private stripSuffixes;
     private mosul;
+    private entryStarts;
+    private longest;
+    private normalized;
+    private phrases;
     constructor(options?: string[] | IraqiBadWordsFilterOptions);
     /**
      * Normalizes a word or token for comparison: removes diacritics, tatweel and
@@ -118,11 +133,30 @@ declare class IraqiBadWordsFilter {
      * 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;
     /**
@@ -139,12 +173,58 @@ declare class IraqiBadWordsFilter {
     /** Matches one normalized reading of a word. */
     private matchReading;
     /**
-     * Finds every match in the text, including ones cleared by a safe stem.
+     * 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.
      */
@@ -170,6 +250,15 @@ declare class IraqiBadWordsFilter {
      * 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 Dialect, type InspectOptions, IraqiBadWordsFilter, type IraqiBadWordsFilterOptions, type MatchRule, type ProfanityMatch, type WordSource, IraqiBadWordsFilter as default };

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * 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 = "diacritics" | "invisible" | "spelling" | "keyboard" | "arabic-digits" | "stretched" | "glued-digits" | "arabizi" | "gaf-as-qaf" | "gaf-as-kaf" | "prefix" | "suffix" | "mosul";
+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. Can be your own JSON
@@ -22,6 +22,17 @@ interface IraqiBadWordsFilterOptions {
      * 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
@@ -38,7 +49,7 @@ interface IraqiBadWordsFilterOptions {
 /** 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
@@ -48,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.
@@ -63,7 +74,7 @@ interface ProfanityMatch {
      */
     normalized: string;
     /**
-     * The dictionary entry it matched, spelled as in its list. For a Mosul form
+     * 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;
@@ -86,6 +97,10 @@ declare class IraqiBadWordsFilter {
     private safeStems;
     private stripSuffixes;
     private mosul;
+    private entryStarts;
+    private longest;
+    private normalized;
+    private phrases;
     constructor(options?: string[] | IraqiBadWordsFilterOptions);
     /**
      * Normalizes a word or token for comparison: removes diacritics, tatweel and
@@ -118,11 +133,30 @@ declare class IraqiBadWordsFilter {
      * 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;
     /**
@@ -139,12 +173,58 @@ declare class IraqiBadWordsFilter {
     /** Matches one normalized reading of a word. */
     private matchReading;
     /**
-     * Finds every match in the text, including ones cleared by a safe stem.
+     * 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.
      */
@@ -170,6 +250,15 @@ declare class IraqiBadWordsFilter {
      * 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 Dialect, type InspectOptions, IraqiBadWordsFilter, type IraqiBadWordsFilterOptions, type MatchRule, type ProfanityMatch, type WordSource, IraqiBadWordsFilter as default };