@sideid/id-profanity-filter 0.1.0

package/src/core/filter.ts

@@ -0,0 +1,129 @@
+import { FilterOptions, FilterResult, ProfanityWord } from '../types';
+import { findProfanity, findProfanityWithMetadata } from './matcher';
+
+/**
+ * Menyensor kata kotor dalam teks
+ *
+ * @param text Teks yang akan disensor
+ * @param options Opsi untuk filter
+ * @returns FilterResult dengan hasil filter
+ */
+export function filter(
+  text: string,
+  options: FilterOptions = {},
+): FilterResult {
+  const {
+    replaceWith = '*',
+    fullWordCensor = true,
+    detectLeetSpeak = true,
+    whitelist = [],
+    checkSubstring = false,
+  } = options;
+
+  const matches = findProfanity(text, {
+    ...options,
+    detectLeetSpeak,
+    whitelist,
+    checkSubstring,
+  });
+
+  const matchDetails = findProfanityWithMetadata(text, options);
+
+  if (matches.length === 0) {
+    return {
+      filtered: text,
+      censored: 0,
+      replacements: [],
+    };
+  }
+
+  let filteredText = text;
+
+  const replacements: Array<{
+    original: string;
+    censored: string;
+    metadata?: ProfanityWord;
+  }> = [];
+
+  matches.forEach((word) => {
+    const metadata = matchDetails.find(
+      (m) =>
+        m.word.toLowerCase() === word.toLowerCase() ||
+        (m.aliases &&
+          m.aliases.some(
+            (alias) => alias.toLowerCase() === word.toLowerCase(),
+          )),
+    );
+
+    const regex = new RegExp(`\\b${escapeRegExp(word)}\\b`, 'gi');
+
+    let match;
+    while ((match = regex.exec(filteredText)) !== null) {
+      const originalWord = match[0];
+
+      if (whitelist.includes(originalWord.toLowerCase())) continue;
+
+      const censoredWord = fullWordCensor
+        ? replaceWith.repeat(originalWord.length)
+        : censorPartialWord(originalWord, replaceWith);
+
+      replacements.push({
+        original: originalWord,
+        censored: censoredWord,
+        metadata,
+      });
+
+      const replaceRegex = new RegExp(
+        `\\b${escapeRegExp(originalWord)}\\b`,
+        'g',
+      );
+      filteredText = filteredText.replace(replaceRegex, censoredWord);
+    }
+  });
+
+  // if (detectLeetSpeak) {
+  // }
+
+  return {
+    filtered: filteredText,
+    censored: replacements.length,
+    replacements,
+  };
+}
+
+/**
+ * Memeriksa apakah teks mengandung kata kotor
+ *
+ * @param text Teks yang akan diperiksa
+ * @param options Opsi untuk pemeriksaan
+ * @returns Boolean apakah teks mengandung kata kotor
+ */
+export function isProfane(text: string, options: FilterOptions = {}): boolean {
+  const matches = findProfanity(text, options);
+  return matches.length > 0;
+}
+
+/**
+ * Escape karakter khusus regex
+ *
+ * @param string String untuk di-escape
+ * @returns String yang telah di-escape
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Menyensor sebagian kata
+ * @param word Kata yang akan disensor
+ * @param replaceChar Karakter pengganti
+ * @returns Kata yang sudah disensor sebagian
+ */
+function censorPartialWord(word: string, replaceChar: string): string {
+  if (word.length <= 2) {
+    return replaceChar.repeat(word.length);
+  }
+
+  // Simpan huruf pertama dan terakhir, sensor yang lain
+  return word[0] + replaceChar.repeat(word.length - 2) + word[word.length - 1];
+}

package/src/core/matcher.ts

@@ -0,0 +1,267 @@
+import {
+  ProfanityWord,
+  ProfanityCategory,
+  Region,
+  FilterOptions,
+} from '../types';
+
+import { wordObjects, getWordsByFilter } from '../constants/wordList';
+
+export function findProfanity(
+  text: string,
+  options: FilterOptions = {},
+): string[] {
+  const {
+    wordList = [],
+    detectLeetSpeak = true,
+    checkSubstring = false,
+    whitelist = [],
+    categories,
+    regions,
+    severityThreshold = 0,
+  } = options;
+
+  const normalizedText = normalizeText(text);
+
+  let wordsToCheck: string[] = wordList;
+
+  if (wordsToCheck.length === 0) {
+    if (categories || regions || severityThreshold > 0) {
+      wordsToCheck = wordObjects
+        .filter((word) => {
+          const matchCategory = categories
+            ? categories.includes(word.category)
+            : true;
+          const matchRegion = regions ? regions.includes(word.region) : true;
+          const matchSeverity = word.severity >= severityThreshold;
+          return matchCategory && matchRegion && matchSeverity;
+        })
+        .map((word) => word.word);
+    } else {
+      wordsToCheck = wordObjects.map((word) => word.word);
+    }
+  }
+
+  wordsToCheck = wordsToCheck.filter(
+    (word) => !whitelist.includes(word.toLocaleLowerCase()),
+  );
+
+  if (wordsToCheck.length === 0) {
+    return [];
+  }
+
+  const matches = new Set<string>();
+
+  wordsToCheck.forEach((word) => {
+    const pattern = checkSubstring ? word : `\\b${escapeRegExp(word)}\\b`;
+
+    const regex = new RegExp(pattern, 'gi');
+
+    let match;
+    while ((match = regex.exec(normalizedText)) !== null) {
+      matches.add(match[0].toLowerCase());
+    }
+  });
+
+  // jika detectLeetSpeak diaktifkan, cari variasi leet speak
+  if (detectLeetSpeak) {
+    wordsToCheck.forEach((word) => {
+      // Cek leet speak
+      const leetPattern = createLeetSpeakPattern(word);
+      const leetRegex = new RegExp(
+        checkSubstring ? leetPattern : `\\b${leetPattern}\\b`,
+        'gi',
+      );
+
+      let match;
+      while ((match = leetRegex.exec(text)) !== null) {
+        matches.add(word.toLowerCase());
+      }
+
+      // cek karakter yang dipisah
+      const evasionPattern = createEvasionPattern(word);
+      const evasionRegex = new RegExp(evasionPattern, 'gi');
+      while ((match = evasionRegex.exec(text)) !== null) {
+        matches.add(word.toLowerCase());
+      }
+    });
+  }
+
+  return Array.from(matches);
+}
+
+/**
+ * Menormalisasi teks untuk perbandingan
+ *
+ * @param text Teks untuk dinormalisasi
+ * @returns Teks yang dinormalisasi
+ */
+function normalizeText(text: string): string {
+  return text
+    .toLowerCase()
+    .normalize('NFD') // Normalisasi Unicode
+    .replace(/[\u0300-\u036f]/g, '') // Hapus diacritic marks
+    .trim();
+}
+
+/**
+ * Escape karakter khusus dalam regex
+ *
+ * @param string String untuk di-escape
+ * @returns String yang sudah di-escape
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Pattern untuk leet speak
+ *
+ * @param word Kata untuk dibuat pattern leet speak
+ * @return Pattern regex untuk leet speak
+ */
+function createLeetSpeakPattern(word: string): string {
+  const leetMap: Record<string, string[]> = {
+    a: ['a', '4', '@'],
+    b: ['b', '8', '6'],
+    c: ['c', '<', '(', '{'],
+    e: ['e', '3'],
+    g: ['g', '9'],
+    i: ['i', '1', '!'],
+    l: ['l', '1', '|'],
+    o: ['o', '0'],
+    s: ['s', '5', '$'],
+    t: ['t', '7', '+'],
+    z: ['z', '2'],
+  };
+
+  return word
+    .split('')
+    .map((char) => {
+      const lowerChar = char.toLowerCase();
+      const replacements = leetMap[lowerChar];
+
+      if (replacements && replacements.length > 0) {
+        return `[${replacements.join('')}]`;
+      } else {
+        return escapeRegExp(char);
+      }
+    })
+    .join('');
+}
+
+/**
+ * Pattern untuk deteksi upaya menghindari filter
+ *
+ * @param word Kata untuk dibuat pattern evasion
+ * @return Pattern regex untuk evasion
+ */
+function createEvasionPattern(word: string): string {
+  return word
+    .split('')
+    .map((char) => escapeRegExp(char))
+    .join('[\\s\\-._*+]?');
+}
+
+/**
+ * Mencari kata kotor lengkap dengan metadata
+ *
+ * @param text Teks yang akan diperika
+ * @param options Opsi utnuk pencarian kata kotor
+ * @return Array dari objek kata kotor yang ditemukan
+ */
+export function findProfanityWithMetadata(
+  text: string,
+  options: FilterOptions = {},
+): ProfanityWord[] {
+  const matches = findProfanity(text, options);
+  if (matches.length === 0) {
+    return [];
+  }
+
+  return matches
+    .map((word) => {
+      const wordObject = wordObjects.find(
+        (obj) =>
+          obj.word.toLowerCase() === word.toLowerCase() ||
+          (obj.aliases &&
+            obj.aliases.some(
+              (alias) => alias.toLowerCase() === word.toLowerCase(),
+            )),
+      );
+
+      return wordObject;
+    })
+    .filter((word): word is ProfanityWord => word !== undefined);
+}
+
+/**
+ * Mencari kategory kata kotor yang ada dalam teks
+ *
+ * @param text matchDetails Hasil pencarian dari fingProfanityWithMetadata()
+ * @param options Opsi untuk pencarian kategori
+ */
+export function findCategories(
+  matchDetails: ProfanityWord[],
+): ProfanityCategory[] {
+  const categories = new Set<ProfanityCategory>();
+
+  matchDetails.forEach((word) => {
+    categories.add(word.category);
+  });
+
+  return Array.from(categories);
+}
+
+/**
+ * Mencari region kata kotor yang ada dalam teks
+ *
+ * @param text matchDetails Hasil pencarian dari fingProfanityWithMetadata()
+ * @param options Opsi untuk pencarian region
+ */
+export function findRegions(matchDetails: ProfanityWord[]): Region[] {
+  const regions = new Set<Region>();
+
+  matchDetails.forEach((word) => {
+    regions.add(word.region);
+  });
+
+  return Array.from(regions);
+}
+
+/**
+ * Menghitung tingkat keparahan kata kotor yang ditemukan
+ *
+ * @param matchDetails Hasil pencarian dari findProfanityWithMetadata()
+ * @return Skor keparahan dari 0-1
+ */
+export function calculateSeverity(matchDetails: ProfanityWord[]): number {
+  if (matchDetails.length === 0) {
+    return 0;
+  }
+
+  const countFactor = Math.min(matchDetails.length / 10, 1); // Maksimal 10 kata
+
+  const categoryWeights: Record<ProfanityCategory, number> = {
+    sexual: 0.9,
+    blasphemy: 0.9,
+    slur: 0.8,
+    profanity: 0.7,
+    insult: 0.6,
+    drugs: 0.5,
+    disgusting: 0.5,
+  };
+
+  let severitySum = 0;
+  matchDetails.forEach((word) => {
+    const categoryWeight = categoryWeights[word.category] || 0.5;
+    const wordSeverity = word.severity * categoryWeight;
+    severitySum += wordSeverity;
+  });
+
+  const severityAvg = severitySum / matchDetails.length;
+
+  // Gabungkan jumlah kata dan keparahan rata-rata
+  // 70% keparahan kata + 30% faktor jumlah
+  return 0.7 * severityAvg + 0.3 * countFactor;
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+export * from './types';
+export * from './core/matcher';
+export * from './core/filter';
+export * from './core/analyzer';
+
+import { filter, isProfane } from './core/filter';
+import {
+  analyze,
+  batchAnalyze,
+  analyzeBySentence,
+  analyzeWithContext,
+} from './core/analyzer';
+import { FilterOptions, FilterResult, AnalysisResult } from './types';
+
+export class IDProfanityFilter {
+  private options: FilterOptions;
+
+  /**
+   * Membuat instance filter baru
+   * @param options Opsi untuk filter
+   */
+  constructor(options: FilterOptions = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Menyensor teks yang diberikan
+   * @param text Teks yang akan disensor
+   * @returns Hasil filter
+   */
+  filter(text: string): FilterResult {
+    return filter(text, this.options);
+  }
+
+  /**
+   * Memeriksa apakah teks mengandung kata kotor
+   * @param text Teks yang akan diperiksa
+   * @returns Boolean apakah teks mengandung kata kotor
+   */
+  isProfane(text: string): boolean {
+    return isProfane(text, this.options);
+  }
+
+  /**
+   * Menganalisis teks untuk kata kotor
+   * @param text Teks yang akan dianalisis
+   * @returns Hasil analisis
+   */
+  analyze(text: string): AnalysisResult {
+    return analyze(text, this.options);
+  }
+
+  /**
+   * Menganalisis batch teks untuk kata kotor
+   * @param texts Array dari teks yang akan dianalisis
+   * @returns Hasil analisis batch
+   */
+  batchAnalyze(texts: string[]) {
+    return batchAnalyze(texts, this.options);
+  }
+
+  /**
+   * Menganalisis teks per-kalimat
+   * @param text Teks yang akan dianalisis
+   * @returns Array hasil analisis per-kalimat
+   */
+  analyzeBySentence(text: string) {
+    return analyzeBySentence(text, this.options);
+  }
+
+  /**
+   * Menganalisis teks dengan konteks di sekitar kata kotor
+   * @param text Teks yang akan dianalisis
+   * @param contextWindowSize Jumlah kata konteks
+   * @returns Konteks di dekat kata kotor
+   */
+  analyzeWithContext(text: string, contextWindowSize: number = 5) {
+    return analyzeWithContext(text, contextWindowSize, this.options);
+  }
+
+  /**
+   * Mengubah opsi filter
+   * @param options Opsi baru untuk filter
+   */
+  setOptions(options: Partial<FilterOptions>) {
+    this.options = {
+      ...this.options,
+      ...options,
+    };
+  }
+
+  /**
+   * Menetapkan daftar kata kustom
+   * @param wordList Daftar kata untuk digunakan
+   */
+  setWordList(wordList: string[]) {
+    this.options.wordList = wordList;
+  }
+
+  /**
+   * Menambahkan kata ke whitelist
+   * @param word Kata yang akan diabaikan
+   */
+  addToWhitelist(word: string) {
+    this.options.whitelist = [
+      ...(this.options.whitelist || []),
+      word.toLowerCase(),
+    ];
+  }
+
+  /**
+   * Menghapus kata dari whitelist
+   * @param word Kata yang akan dihapus dari whitelist
+   */
+  removeFromWhitelist(word: string) {
+    if (!this.options.whitelist) return;
+
+    this.options.whitelist = this.options.whitelist.filter(
+      (w) => w.toLowerCase() !== word.toLowerCase(),
+    );
+  }
+}
+
+export default IDProfanityFilter;
+
+export const idFilter = {
+  filter: (text: string, options?: FilterOptions) => filter(text, options),
+  isProfane: (text: string, options?: FilterOptions) =>
+    isProfane(text, options),
+  analyze: (text: string, options?: FilterOptions) => analyze(text, options),
+  batchAnalyze: (texts: string[], options?: FilterOptions) =>
+    batchAnalyze(texts, options),
+};

package/src/types/index.ts

@@ -0,0 +1,115 @@
+export type ProfanityCategory =
+  | 'sexual' // Kata-kata berbau seksual
+  | 'insult' // Kata-kata penghinaan
+  | 'profanity' // Umpatan umum
+  | 'slur' // Perkataan merendahkan berdasarkan identitas
+  | 'drugs' // Terkait narkoba
+  | 'disgusting' // Kata-kata menjijikkan
+  | 'blasphemy'; // Penistaan agama
+
+
+export type Region =
+  | 'general' // Umum di Indonesia
+  | 'jawa' 
+  | 'sunda' 
+  | 'betawi' 
+  | 'batak' 
+  | 'minang' 
+  | 'bali' 
+  | 'madura' 
+  | 'bugis' 
+  | 'aceh' 
+  | 'ambon' 
+  | 'papua' 
+  | 'manado' 
+  | 'banjar' 
+  | 'palembang' 
+  | 'lampung' 
+  | 'ntt' 
+  | 'ntb'; 
+
+/**
+ * Definisi kata kotor
+ */
+export interface ProfanityWord {
+  word: string; // Kata kotor
+  category: ProfanityCategory; // Kategori kata
+  region: Region; // Daerah asal kata
+  severity: number; // Tingkat keparahan (0-1)
+  aliases?: string[]; // Variasi kata atau alias
+  description?: string; // Deskripsi atau makna kata
+  context?: string; // Konteks penggunaan kata
+}
+
+/**
+ * Opsi untuk konfigurasi filter
+ */
+export interface FilterOptions {
+  /** List kata yang ingin difilter */
+  wordList?: string[];
+
+  /** Karakter pengganti untuk kata yang disensor */
+  replaceWith?: string;
+
+  /** Apakah harus menyensor seluruh kata atau hanya sebagian */
+  fullWordCensor?: boolean;
+
+  /** Apakah harus mendeteksi kata dengan variasi penulisan */
+  detectLeetSpeak?: boolean;
+
+  /** Mengabaikan kata-kata dalam konteks tertentu (misalnya nama) */
+  whitelist?: string[];
+
+  /** Apakah harus memeriksa substring (lebih ketat) */
+  checkSubstring?: boolean;
+
+  /** Kategori kata yang ingin difilter */
+  categories?: ProfanityCategory[];
+
+  /** Daerah yang ingin difilter katanya */
+  regions?: Region[];
+
+  /** Tingkat keparahan minimum yang akan difilter (0-1) */
+  severityThreshold?: number;
+}
+
+/**
+ * Hasil analisis dari teks
+ */
+export interface AnalysisResult {
+  /** Apakah teks mengandung kata kotor */
+  hasProfanity: boolean;
+
+  /** Daftar kata kotor yang ditemukan */
+  matches: string[];
+
+  /** Daftar kata kotor lengkap dengan metadata */
+  matchDetails: ProfanityWord[];
+
+  /** Daftar kategori kata kotor yang ditemukan */
+  categories: ProfanityCategory[];
+
+  /** Daftar daerah asal kata kotor yang ditemukan */
+  regions: Region[];
+
+  /** Tingkat keparahan (0-1) berdasarkan jumlah dan jenis kata */
+  severityScore: number;
+}
+
+/**
+ * Hasil filter dari teks
+ */
+export interface FilterResult {
+  /** Teks hasil filter */
+  filtered: string;
+
+  /** Jumlah kata yang disensor */
+  censored: number;
+
+  /** Kata asli yang disensor dan penggantinya */
+  replacements: Array<{
+    original: string;
+    censored: string;
+    metadata?: ProfanityWord;
+  }>;
+}