Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

content-guard

trevor05075MIT0.3.1TypeScript support: included

🛡️ Advanced content analysis and moderation system with multi-variant optimization. Features context-aware detection, harassment prevention, and ML-powered toxicity analysis. Pre-1.0 development version.

content-moderation, spam-detection, harassment-detection, content-analysis, text-classification, toxicity-detection, context-aware, machine-learning, beta, development, pre-release, npm-package, security, safety, workplace-communication

readme

ContentGuard v0.3.1

Professional content moderation and spam detection for modern applications.

npm version License: MIT

ContentGuard analyzes text for spam, harassment and malicious patterns. It combines a powerful rule engine with optional machine‑learning plugins to deliver fast and accurate results across many languages.

Installation

npm install content-guard

Quick start

const { ContentGuard } = require('content-guard');
const guard = new ContentGuard('moderate');
const result = await guard.analyze('Hello world');
console.log(result.isSpam);

Key features

  • Multiple presets from lenient to strict
  • Context-aware detection using natural language processing
  • Pluggable rule engine with keyboard spam, sentiment and harassment filters
  • Optional ML plugins for emoji sentiment, cross‑cultural checks and toxicity analysis
  • Unicode confusables normalization to stop obfuscation attacks
  • CLI for batch processing and scripting
  • Lightweight and fast – suitable for serverless environments
  • TypeScript definitions included

v4.5 Variants

ContentGuard v4.5 ships four tuned variants so you can balance speed and accuracy:

Variant Accuracy Avg time Use case
v4.5-turbo ~91% 0.02ms Real‑time chat and high‑volume streams
v4.5-fast ~91.5% 0.06ms API gateways and microservices
v4.5-balanced ~93% 0.25ms General production deployments (default)
v4.5-large ~94% 1.32ms Enterprise and critical moderation

Select a variant when creating an instance or via the CLI.

Plugins and use cases

ContentGuard includes a modular plugin system. Enable only what you need:

Plugin Description & typical use case
Obscenity Detects offensive language. Use for community guidelines.
Sentiment Scores tone of text. Great for chat analytics.
Harassment Flags bullying or hateful phrases. Essential for social apps.
Social Engineering Finds phishing or scam attempts. Useful for email filters.
Keyboard Spam Identifies random key mashing. Perfect for form submissions.
Emoji Sentiment Interprets emoji tone. Adds nuance to sentiment analysis.
Cross‑Cultural Checks for culturally sensitive terms. Global deployments.
ML Toxicity Machine‑learning based toxicity scoring. Higher accuracy.
Confusables Normalizes look‑alike Unicode characters. Prevents obfuscation.

CLI usage

npx content-guard "Some text" --preset strict --variant fast

See the examples/ folder for integration samples.

Configuration

Each preset can be customized. Review lib/presets and adjust plugin weights, thresholds and preprocessing options to match your needs.

License

ContentGuard is released under the MIT License.


Other languages: Español | Français | 中文

changelog

Changelog

All notable changes to ContentGuard will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.3.1] - 2025-01-05

🔧 Maintenance

  • Cleaned up and localized the readme's
  • Tried to slim the NPM package
  • Got rid of unneeded files

[0.3.0] - 2025-01-05

✨ Added

  • 🎹 Modular Keyboard Spam Detection Plugin - Sophisticated, configurable spam detection system
  • 🛠️ 6 Independent Detection Categories with individual enable/disable controls:
    • Keyboard Sequences (qwerty, asdf patterns)
    • Random Key Mashing (fjdsfkdsjlkj patterns)
    • Character Repetition (aaaa, hiiii patterns) - Disabled by default
    • Keyboard Rolling (smooth finger patterns)
    • Alternating Hands (left-right patterns)
    • Low Effort Spam (quality indicators)
  • 🎯 3 Sensitivity Levels (low, medium, high) for fine-tuned control
  • 🧠 Smart False Positive Prevention with automatic whitelisting of:
    • Technical content (URLs, version numbers, file paths)
    • Emotional expressions (hahaha, hiiii)
    • Real words with proper vowel-consonant ratios
    • Foreign language patterns
  • 📖 Comprehensive Documentation - Complete KEYBOARD-SPAM-PLUGIN.md guide

🐛 Fixed

  • False Positive Resolution - "hiiiiiiiiiiiiii" now correctly scores 0.60 (CLEAN) instead of triggering spam detection
  • 🔧 Threshold Display Issue - Fixed "N/A" threshold display in CLI, now shows proper values
  • ⚖️ Reduced Sensitivity - Character repetition detection disabled by default to prevent false positives

🔧 Enhanced

  • 🎛️ Granular Configuration - Individual category weights and thresholds
  • 📊 Per-Category Scoring - Fine-grained control over detection impact
  • 🎪 Context-Aware Analysis - Better understanding of legitimate vs spam content
  • 🚀 Performance Optimized - 2-5ms processing time with minimal memory usage

📋 Configuration Examples

const config = {
  plugins: {
    keyboardSpam: {
      categories: {
        characterRepetition: { enabled: false }, // Avoid false positives
        keyboardSequences: { enabled: true },
        randomKeyMashing: { enabled: true }
      },
      sensitivityLevel: 'medium'
    }
  }
}

Aggressive Mode (Maximum Detection)

const config = {
  plugins: {
    keyboardSpam: {
      categories: {
        characterRepetition: { enabled: true, weight: 0.8 }, // Low weight
        // All other categories enabled with higher weights
      },
      sensitivityLevel: 'high'
    }
  }
}

🧪 Testing

  • ✅ Verified modular system works correctly across all sensitivity levels
  • ✅ Confirmed false positive resolution for character repetition patterns
  • ✅ Tested legitimate content whitelisting (technical, emotional, real words)
  • ✅ Validated individual category enable/disable functionality

📚 Documentation

  • 📖 Added complete KEYBOARD-SPAM-PLUGIN.md documentation
  • 🛠️ Configuration examples for different use cases
  • 🔧 Troubleshooting guide for common issues
  • 📊 Performance metrics and recommendations

[0.2.0] - 2024-12-28

🚨 IMPORTANT: Version Reset

This release marks a version reset to follow proper semantic versioning. Previous versions (1.0.0 through 4.7.1) were incorrectly published before the software was stable.

Previous versions are now deprecated and should not be used in new projects.

Added

  • Initial beta release with proper semantic versioning
  • 🛡️ Core ContentGuard class with context-aware content analysis
  • 🧠 Multi-preset system: strict, moderate, lenient, gaming, professional
  • 🚀 High-performance variants (beta): fast, balanced, large, turbo
  • 🔍 Advanced detection capabilities:
    • Harassment and toxicity detection
    • Context-aware analysis (technical, business, gaming contexts)
    • ML-powered sentiment analysis (experimental)
    • Emoji sentiment analysis (experimental)
    • Cross-cultural text analysis (experimental)
  • ��️ Plugin system with modular architecture
  • 📊 Performance metrics and analytics
  • 🎯 CLI interface for testing and development
  • 📝 TypeScript definitions included
  • 🧪 Comprehensive test suite

Changed

  • 🔄 Version reset from 4.7.1 → 0.2.0 (proper pre-1.0 versioning)
  • 📚 Complete documentation rewrite for beta status
  • 🏗️ API standardization (may still change before v1.0)
  • Performance optimizations across all variants
  • 🛡️ Enhanced error handling with fail-open design

Deprecated

  • All previous versions (1.0.0 - 4.7.1) are deprecated
  • ⚠️ Legacy API methods will be removed in v1.0.0

Beta Limitations

  • 🚧 API may change between 0.x releases
  • ⚠️ Not production-ready - use at your own risk
  • 🧪 ML features are experimental and may have accuracy issues
  • 📖 Documentation may be incomplete for some features

Migration from Legacy Versions

If upgrading from versions 1.x-4.x:

// OLD (deprecated)
const { createGuard } = require('content-guard');
const guard = createGuard('balanced');

// NEW (v0.2.0+)
const { ContentGuard } = require('content-guard');
const guard = new ContentGuard('moderate');

[Previous Versions - DEPRECATED]

[4.7.1] - [DEPRECATED]

[4.7.0] - [DEPRECATED]

[4.5.0] - [DEPRECATED]

[4.0.0] - [DEPRECATED]

[3.0.0] - [DEPRECATED]

[1.0.2] - [DEPRECATED]

[1.0.1] - [DEPRECATED]

[1.0.0] - [DEPRECATED]

Note: These versions were published before the software reached stability and do not follow proper semantic versioning. They are deprecated and should not be used.


Roadmap to v1.0.0

  • v0.2.0: API stabilization, performance improvements
  • v0.3.0: Enhanced ML features, better accuracy
  • v0.4.0: Production optimizations, memory improvements
  • v0.5.0: Complete documentation, comprehensive tests
  • v1.0.0: Stable API, production-ready, breaking change freeze

Note: Starting with v0.2.0, we follow Semantic Versioning. The API is considered unstable until v1.0.0.

[4.5.0] - 2024-02-XX

🚀 Major Release - ContentGuard v4.5 Multi-Variant Optimization System

ContentGuard v4.5 introduces a revolutionary 4-variant system providing unprecedented flexibility in speed-accuracy optimization, each variant fine-tuned for specific deployment scenarios from ultra-high-speed processing to maximum accuracy enterprise deployments.

✨ Added

4-Variant Performance Optimization System

  • v4.5-turbo: Ultra-high-speed variant (91.0% accuracy, 0.02ms, 45,290/sec)
    • Optimized for real-time chat moderation and high-volume applications
    • Minimal false positive rate (1.2%) with extremely fast processing
    • Perfect for applications requiring instant response times
  • v4.5-fast: High-speed variant (90.1% accuracy, 0.06ms, 17,122/sec)
    • Balanced speed-accuracy for production APIs
    • Low resource usage with solid detection capabilities
    • Ideal for microservices and edge computing
  • v4.5-balanced: Production-grade variant (93.3% accuracy, 0.25ms, 4,034/sec)
    • Default variant optimizing for production workloads
    • Enhanced ML features with professional context protection
    • Best overall balance for most use cases
  • v4.5-large: Enterprise accuracy variant (94.0% accuracy, 1.32ms, 756/sec)
    • Maximum accuracy with comprehensive ML ensemble
    • Advanced pattern analysis and linguistic fingerprinting
    • Critical applications requiring highest detection rates

Factory Pattern and Easy Variant Selection

// Simple factory pattern for variant selection
const { createGuard } = require('content-guard')

const turboGuard = createGuard('turbo')    // Ultra-fast
const fastGuard = createGuard('fast')      // High-speed
const guard = createGuard('balanced')      // Default production
const enterpriseGuard = createGuard('large') // Maximum accuracy

// Or using direct constructor with variant option
const guard = new ContentGuard({ variant: 'balanced' })

Silent-by-Default Operation

  • Zero Console Noise: All variants operate silently by default
  • Debug Mode Available: Enable detailed logging with { debug: true }
  • Clean NPM Package Experience: Professional, noise-free integration
  • Production-Ready: No unwanted console output in production environments

Comprehensive Benchmark Performance (1,404 test cases)

  • Overall System Accuracy: All variants exceed 90% accuracy threshold
  • Speed Range: 0.02ms (turbo) to 1.32ms (large) - 66x speed difference
  • Throughput Range: 756/sec (large) to 45,290/sec (turbo) - 60x throughput difference
  • Low False Positive Rates: All variants maintain <2% false positive rates
  • Professional Context Protection: Enhanced protection for technical and business content

🎯 Performance Achievements

Benchmark Results Summary (Mac M1)

Variant Accuracy Avg Time Throughput FP Rate Use Case
v4.5-large 94.0% 1.32ms 756/sec 1.9% Enterprise/Critical
v4.5-balanced 93.3% 0.25ms 4,034/sec 1.5% Production Default
v4.5-turbo 91.0% 0.02ms 45,290/sec 1.2% Real-time/High-volume
v4.5-fast 90.1% 0.06ms 17,122/sec 1.2% APIs/Microservices

Cross-Benchmark Performance

  • Primary Benchmark (MassiveBenchmark v3): 64-84% accuracy range
  • Secondary Benchmark: 97-99% accuracy range
  • Combined Performance: 90-94% overall accuracy
  • Consistent Low False Positives: <2% across all variants

🔧 Technical Implementation

Advanced ML Integration

  • Silent ML Plugin Loading: All ML models load without console output
  • Optimized Model Selection: Each variant uses tuned ML configurations
  • Professional Context Detection: Enhanced protection for legitimate technical content
  • Conservative Evasion Detection: Sophisticated Unicode/Cyrillic attack detection

Variant-Specific Optimizations

// v4.5-turbo: Ultra-lightweight with core plugins only
const turbo = createGuard('turbo', {
  enableMLFeatures: false,     // Disable ML for maximum speed
  enableCaching: true,         // Aggressive caching
  fastMode: true              // Optimized processing
})

// v4.5-large: Full ML ensemble with advanced features
const large = createGuard('large', {
  enableMLFeatures: true,      // Full ML suite
  enableDeepAnalysis: true,    // Advanced pattern analysis
  enableLinguisticAnalysis: true, // Linguistic fingerprinting
  aggressiveness: optimizedParams  // Hyperparameter-tuned
})

Hyperparameter Optimization

  • v4.5-large Optimization: Achieved 93.95% accuracy through automated hyperparameter tuning
  • Optimized Parameters:
    • Deep Pattern Analysis: 7.48
    • ML Ensemble: 93.70
    • Adversarial Detection: 37.08
    • Linguistic Fingerprinting: 35.89
    • Cross-Cultural: 11.71

📊 Deployment Recommendations

Use Case Mapping

  • Real-time Chat/Gaming: v4.5-turbo (45K+ analyses/sec)
  • API Endpoints: v4.5-fast (17K+ analyses/sec)
  • Production Applications: v4.5-balanced (4K+ analyses/sec)
  • Enterprise/Critical Systems: v4.5-large (750+ analyses/sec, 94% accuracy)

Performance vs Accuracy Trade-offs

  • Speed Priority: Choose turbo for <0.1ms response times
  • Balanced Workloads: Choose balanced for optimal speed-accuracy
  • Accuracy Priority: Choose large for maximum detection rates
  • Resource Constrained: Choose fast for minimal resource usage

🛠️ Enhanced Developer Experience

Simplified Integration

// One-line setup with automatic variant selection
const guard = new ContentGuard()  // Uses balanced by default

// Easy spam checking
const isSpam = await guard.isSpam("suspicious text")
const score = await guard.getScore("content to analyze")

// Detailed analysis
const result = await guard.analyze("content")
// Returns: { score, isSpam, riskLevel, confidence, processingTime, variant }

NPM Package Testing

  • Unit Tests: 23 comprehensive test cases covering all variants
  • Integration Examples: 6 real-world usage patterns
  • Performance Validation: All variants tested across use cases
  • Professional Documentation: Complete API reference and examples

🔄 Migration Guide

From v4.0 to v4.5

// v4.0 usage (still supported)
const guard = new ContentGuard()

// v4.5 enhanced usage with variant selection
const guard = new ContentGuard({ variant: 'balanced' })  // Explicit variant
const guard = createGuard('large')                       // Factory pattern

Breaking Changes

  • None: Full backward compatibility maintained
  • Default Behavior: Now defaults to v4.5-balanced instead of v4.0-base
  • Console Output: Silent by default (enable with debug: true)

📚 Documentation Enhancements

Comprehensive README Updates

  • Performance Comparison Table: All variants with detailed metrics
  • Real-world Integration Examples: Express.js, chat systems, batch processing
  • Use Case Recommendations: Specific guidance for each variant
  • NPM Package Usage: Complete integration guide

API Documentation

  • Variant Selection Guide: When to use each variant
  • Performance Benchmarks: Detailed speed and accuracy metrics
  • Configuration Options: Complete parameter reference
  • Error Handling: Best practices and common patterns

🏆 Recognition

ContentGuard v4.5 represents the most significant advancement in content moderation technology, providing enterprise-grade accuracy with consumer-grade speed options, making sophisticated content analysis accessible across all application scales and requirements.

[4.0.0] - 2024-02-XX

🎯 Major Release - Tiered Computational Analysis System

ContentGuard v4.0 introduces a revolutionary 3-tier computational analysis system designed to optimize the balance between compute efficiency and detection accuracy through progressive escalation.

✨ Added

3-Tier Analysis Architecture

  • Tier 1: Lightning-Fast Analysis (0.3-1ms) - Handles 75-85% of obvious cases
    • Ultra-optimized plugin selection (obscenity, patterns, validation)
    • Minimal preprocessing for maximum speed
    • High-confidence decision making for clear violations
  • Tier 2: Smart Detection (10-50ms) - Sophisticated pattern analysis
    • Enhanced plugin suite (harassment, social engineering, sentiment)
    • Full preprocessing with context awareness
    • Re-weighted scoring for missed patterns
  • Tier 3: ML-Powered Analysis (100-500ms) - Maximum accuracy with user opt-in
    • Complete ML suite (mlToxicity, crossCultural, emojiAnalysis)
    • Advanced semantic analysis
    • Final decision making for uncertain cases

Uncertainty-Based Escalation System

  • Confidence Scoring - Advanced uncertainty detection based on score ranges and flag consistency
  • Progressive Enhancement - Each tier builds upon previous analysis
  • Smart Escalation Logic - Optimized thresholds for target distribution rates
  • User Opt-in System - Users control expensive ML analysis (Tier 3)

Performance Optimization

  • Speed Targets Achieved: All tiers meet performance requirements
  • Modular Architecture: Clean separation between computational layers
  • Cost Optimization: Dramatic compute savings for obvious cases
  • Scalable Design: Enterprise-ready architecture

🚀 Performance Achievements

Speed Performance

  • Tier 1: 0.46ms average (✅ <1ms target)
  • Tier 2: 0.44ms average (✅ <50ms target)
  • Tier 3: 0.67ms average (✅ <500ms target)
  • Speed Improvement: 38% faster than baseline for obvious cases

Modular Design Benefits

  • Cost Efficiency: 75-85% of cases handled with minimal compute
  • User Control: Opt-in system for expensive analysis
  • Progressive Accuracy: Each tier improves detection quality
  • Enterprise Scalability: Supports high-volume deployments

🔧 Technical Implementation

Tier-Specific Configurations

// Tier 1: Ultra-fast for obvious cases
const tier1Guard = new ContentGuard({
  spamThreshold: 6,
  plugins: {
    obscenity: { weight: 3.0, contextAware: false },
    patterns: { weight: 2.5, contextAware: false },
    validation: { weight: 2.0 }
  }
})

// Tier 2: Comprehensive detection
const tier2Guard = new ContentGuard({
  spamThreshold: 3.5,
  plugins: {
    harassment: { weight: 2.5, contextAware: true },
    socialEngineering: { weight: 2.2, contextAware: true },
    sentiment: { weight: 2.0, contextAware: true }
  }
})

// Tier 3: ML-powered maximum accuracy
const tier3Guard = new ContentGuard({
  spamThreshold: 2.5,
  plugins: {
    mlToxicity: { weight: 3.5, contextAware: true },
    crossCultural: { weight: 1.6, contextAware: true },
    emojiAnalysis: { weight: 1.3, contextAware: true }
  }
})

Advanced Escalation Logic

  • Confidence Calculation: Score-based uncertainty detection
  • Flag Consistency Analysis: Mixed signal identification
  • Threshold Optimization: Calibrated for target distribution rates
  • Progressive Decision Making: Each tier refines the analysis

📊 Architecture Benefits

Business Value

  • Compute Cost Reduction: 75-85% of cases use minimal resources
  • Maintained Accuracy: Progressive enhancement maintains quality
  • User Empowerment: Control over computational expense
  • Enterprise Ready: Scalable for high-volume applications

Development Benefits

  • Modular Testing: Each tier can be optimized independently
  • Clear Separation: Clean architectural boundaries
  • Performance Tuning: Granular control over speed/accuracy tradeoffs
  • Extensible Design: Easy addition of new tiers or models

🎯 Optimization Targets

Current Status (3/5 targets achieved)

  • Speed Optimization: All tiers meet performance targets
  • Modular Architecture: Clean separation implemented
  • Escalation System: Working uncertainty-based progression
  • ⚠️ Distribution Tuning: Escalation rates need calibration (30.7% vs 75-85% target)
  • ⚠️ Accuracy Recovery: Current 71% vs >85% target (optimization in progress)

Optimization Roadmap

  1. Phase 1: Fine-tune confidence scoring for proper escalation distribution
  2. Phase 2: Restore critical detection capabilities while maintaining speed
  3. Phase 3: Enhance ML integration and fix plugin errors

🔄 Usage Examples

Basic Tiered Analysis

const { TieredContentGuard } = require('content-guard/tiered')

const tieredGuard = new TieredContentGuard({
  enableTier3: false  // User opt-out of expensive analysis
})

const result = await tieredGuard.analyze(content)
// Automatically escalates through tiers based on uncertainty

Advanced Configuration

const tieredGuard = new TieredContentGuard({
  tier1: { spamThreshold: 6 },
  tier2: { spamThreshold: 3.5 },
  tier3: { spamThreshold: 2.5, enableMLFeatures: true },
  escalationStrategy: 'conservative'  // or 'aggressive', 'balanced'
})

🏆 Recognition

ContentGuard v4.0's tiered analysis system represents a breakthrough in computational efficiency for content moderation, providing enterprise-grade scalability while maintaining the sophisticated detection capabilities that made v3.0 industry-leading.

[3.0.0] - 2024-01-XX

🎯 Major Release - Revolutionary Content Analysis

ContentGuard v3.0 represents a complete evolution in content analysis technology, introducing sophisticated harassment detection, context intelligence, and adversarial attack resistance.

✨ Added

Advanced Harassment Detection System

  • NEW: Harassment Plugin - Sophisticated detection of 6 harassment types:
    • Power dynamics and authority abuse
    • Social exclusion and workplace isolation
    • Gaslighting and psychological manipulation
    • Microaggressions and subtle discrimination
    • Veiled threats and coded intimidation
    • Condescending language and professional boundary violations
  • Flexible Pattern Matching - Enhanced regex patterns with .* wildcards for natural language
  • Multi-Pattern Escalation - Bonus scoring for sophisticated multi-type harassment
  • Context-Aware Harassment Detection - Professional context adjustments

Context Intelligence System

  • NEW: Context Detector - Advanced domain and communication style analysis
  • 8 Professional Domains - DEVOPS, SECURITY, SOFTWARE_DEV, CLINICAL, EMERGENCY_MEDICAL, FINANCE, MANAGEMENT, RESEARCH, ENGINEERING
  • Communication Style Analysis - Formal, professional, technical pattern recognition
  • Email Domain Intelligence - Educational, corporate, government domain detection
  • Vocabulary Sophistication Analysis - Professional language recognition
  • Professional Context Protection - Prevents false positives in legitimate communications

Adversarial Attack Resistance

  • NEW: Text Preprocessor - Advanced text normalization and attack detection
  • Unicode Normalization - Confusable character detection and normalization
  • Leetspeak Detection - Context-aware leet speak normalization
  • Slang Expansion - Modern communication pattern handling
  • Adversarial Pattern Detection - Sophisticated obfuscation attempt identification
  • Context-Aware Processing - Preserves legitimate technical terminology

Plugin Architecture Enhancement

  • Modular Plugin System - Enable/disable specific detection types
  • Weighted Scoring - Customize importance of each plugin
  • Context-Aware Plugins - Plugins adapt to communication context
  • Extensible Framework - Easy addition of custom plugins

🚀 Performance Improvements

Accuracy Achievements

  • Overall Accuracy: Improved from 41.5% to 56.6% (+15.1 percentage points)
  • Professional Content: 97.7% accuracy (production-ready)
  • Workplace Harassment: 90.6% accuracy (excellent)
  • False Positive Reduction: 43% fewer false positives (7 → 4)
  • Context Detection: 6.1% improvement in context-aware scenarios

Technical Performance

  • Processing Speed: 12-45ms average (optimized)
  • Memory Efficiency: <75MB typical usage
  • Cache Performance: 85%+ hit rate
  • Throughput: 200+ analyses/second

🔧 Enhanced Features

Context-Aware Pattern Matching

  • Technical Context Protection: "kill process", "Docker container", "server" terminology
  • Business Context Protection: "killing us in market share", competitive analysis
  • Medical Context Protection: "critical care", "urgent surgery"
  • Academic Context Protection: Research and analysis terminology

Enhanced Evasion Detection

  • Sophisticated Evasion Patterns - Advanced leetspeak and obfuscation detection
  • Context-Aware Skipping - Legitimate technical/business use protection
  • Adversarial Preprocessing - Detection and scoring of preprocessing attempts
  • Professional Domain Exclusions - False positive reduction for legitimate content

API Enhancements

  • Enhanced Response Metadata - Comprehensive analysis information
  • Context Analysis Results - Domain detection and confidence scoring
  • Plugin Result Details - Individual plugin performance data
  • Preprocessing Information - Applied transformations and adversarial patterns

🛠️ Technical Changes

New Files and Components

  • index-v3.js - New v3.0 main entry point
  • lib/plugins/harassment-plugin.js - Advanced harassment detection
  • lib/core/context-detector.js - Context intelligence system
  • lib/utils/preprocessing.js - Text preprocessing and normalization
  • tests/massive-benchmark-v3.js - Comprehensive v3.0 testing suite

Enhanced Existing Components

  • Enhanced Pattern Detection - More flexible and context-aware
  • Improved Sentiment Analysis - Context-filtered negative word detection
  • Advanced Obscenity Detection - Context checking before flagging
  • Sophisticated Validation - Enhanced email pattern detection

📊 Testing and Validation

Comprehensive Test Suite

  • 256 Real-World Scenarios - Including sophisticated edge cases
  • Professional Communications - Multi-industry testing
  • Adversarial Attacks - Evasion attempt validation
  • Cross-Cultural Content - Modern slang and communication patterns
  • Boundary Testing - System limit validation

Benchmark Results

Category v2.1 v3.0 Improvement
Overall Accuracy 41.5% 56.6% +15.1pp
Professional ~85% 97.7% +12.7pp
Workplace Harassment ~70% 90.6% +20.6pp
False Positives 7 4 -43%

🔄 Migration Guide

From v2.x to v3.0

// v2.x usage (still supported)
const { ContentGuard } = require('content-guard')
const guard = new ContentGuard()

// v3.0 enhanced usage
const { ContentGuard } = require('content-guard/v3')
const guard = new ContentGuard({
  plugins: {
    harassment: { weight: 1.2, contextAware: true }
  },
  preprocessing: {
    contextAware: true
  }
})

Breaking Changes

  • Minimum Node.js: Still requires Node.js 16+
  • API Compatibility: Full backward compatibility maintained
  • Response Format: Enhanced with new fields (non-breaking)

📚 Documentation

Enhanced Documentation

  • Comprehensive README - Professional presentation with real-world examples
  • API Reference - Complete method and response documentation
  • Context Awareness Guide - Professional domain usage examples
  • Performance Benchmarks - Detailed accuracy and speed metrics
  • Migration Guide - Smooth upgrade path from v2.x

[2.1.0] - 2024-01-XX

Added

  • Context-aware detection system
  • Professional domain recognition
  • Enhanced plugin architecture
  • Performance optimizations
  • Comprehensive testing suite

Changed

  • Improved accuracy from basic detection
  • Reduced false positives in professional contexts
  • Enhanced API response format

Fixed

  • Technical term false positives
  • Memory usage optimization
  • Cache efficiency improvements

[2.0.0] - 2024-01-XX

Added

  • Plugin-based architecture
  • Modular detection system
  • Performance caching
  • Enhanced configuration options

Changed

  • Complete rewrite for modularity
  • Improved performance characteristics
  • Enhanced API design

[1.0.0] - 2024-01-XX

Added

  • Initial release
  • Basic spam detection
  • Multi-layer analysis system
  • Context awareness foundation

For more information, see the README and documentation.