CommonSignals

// This Pine Script™ code is subject to the terms of the Mozilla Public License 2.0
// © Yavuz365
// CommonSignals Library - Standardized Signal Generation Utilities

//@version=5
// @description Standardized signal generation library for consistent indicator output.
// Signals are normalized to: BUY=1, NEUTRAL=0, SELL=-1
// Provides signal aggregation, filtering, and confirmation utilities.
library("CommonSignals", overlay=true)

import TimeFrameUtils as TF

// ============================================================================
// SIGNAL DEFINITIONS & STANDARDIZATION
// ============================================================================

// Signal type: 1=Buy, 0=Neutral, -1=Sell
// Used consistently across all indicators for easy aggregation

// @function Generate RSI signal
// @param rsi RSI value
// @param overbought RSI overbought threshold (default: 70)
// @param oversold RSI oversold threshold (default: 30)
// @returns Signal: 1 (buy), 0 (neutral), -1 (sell)
export rsiSignal(series float rsi, simple float overbought = 70, simple float oversold = 30) =>
    if rsi > overbought
        -1  // Sell signal
    else if rsi < oversold
        1   // Buy signal
    else
        0   // Neutral

// @function Generate MACD signal
// @param macdLine MACD line
// @param signalLine MACD signal line
// @param histogram MACD histogram
// @returns Signal: 1 (buy), 0 (neutral), -1 (sell)
export macdSignal(series float macdLine, series float signalLine, series float histogram) =>
    if macdLine > signalLine and histogram > 0
        1   // Buy signal
    else if macdLine < signalLine and histogram < 0
        -1  // Sell signal
    else
        0   // Neutral

// @function Generate Stochastic signal
// @param k Stochastic K line
// @param d Stochastic D line
// @param overbought Overbought threshold (default: 80)
// @param oversold Oversold threshold (default: 20)
// @returns Signal: 1 (buy), 0 (neutral), -1 (sell)
export stochSignal(series float k, series float d, simple float overbought = 80, simple float oversold = 20) =>
    if k < oversold and k > d
        1   // Buy signal (K crosses above D from oversold)
    else if k > overbought and k < d
        -1  // Sell signal (K crosses below D from overbought)
    else if k > overbought
        -1  // Sell signal (overbought)
    else if k < oversold
        1   // Buy signal (oversold)
    else
        0   // Neutral

// @function Generate Moving Average signal
// @param price Current price
// @param fastMA Fast moving average (e.g., EMA10)
// @param slowMA Slow moving average (e.g., EMA20)
// @returns Signal: 1 (buy), 0 (neutral), -1 (sell)
export maSignal(series float price, series float fastMA, series float slowMA) =>
    if fastMA > slowMA and price > fastMA
        1   // Buy signal
    else if fastMA < slowMA and price < fastMA
        -1  // Sell signal
    else
        0   // Neutral

// @function Generate divergence signal
// @param bullishDiv Bullish divergence detected
// @param bearishDiv Bearish divergence detected
// @returns Signal: 1 (buy), 0 (neutral), -1 (sell)
export divergenceSignal(bool bullishDiv, bool bearishDiv) =>
    if bullishDiv
        1   // Buy signal
    else if bearishDiv
        -1  // Sell signal
    else
        0   // Neutral

// ============================================================================
// SIGNAL AGGREGATION & FILTERING
// ============================================================================

// @function Calculate confluence score from signal array
// @param signals Array of signals (1, 0, -1)
// @returns Confluence score: range from -n to +n
export confluenceScore(array<int> signals) =>
    score = 0
    for sig in signals
        score += sig
    score

// @function Get consensus signal from multiple signals
// @param signals Array of signals
// @returns Consensus: 1 (buy), 0 (neutral), -1 (sell)
export consensusSignal(array<int> signals) =>
    if array.size(signals) == 0
        0
    else
        score = confluenceScore(signals)
        if score > 0
            1
        else if score < 0
            -1
        else
            0

// @function Filter signal by confirmation
// @param signal Input signal
// @param confirmationCount Number of consecutive confirming signals needed
// @returns Filtered signal (returns na if not confirmed)
export confirmedSignal(series int signal, simple int confirmationCount = 2) =>
    if barstate.isconfirmed
        signal
    else
        na

// ============================================================================
// SIGNAL STRENGTH & CERTAINTY
// ============================================================================

// @function Calculate signal strength (0-100%)
// @param signals Array of signals
// @returns Strength percentage (0-100)
export signalStrength(array<int> signals) =>
    if array.size(signals) == 0
        0
    else
        score = confluenceScore(signals)
        maxScore = array.size(signals)
        strength = math.abs(score) / maxScore * 100
        strength

// @function Get signal color for visualization
// @param signal Signal value (1, 0, -1)
// @param buyColor Color for buy signal
// @param sellColor Color for sell signal
// @param neutralColor Color for neutral signal
// @returns Color based on signal
export signalColor(int signal, color buyColor = color.new(color.green, 0), color sellColor = color.new(color.red, 0), color neutralColor = color.new(color.gray, 70)) =>
    if signal == 1
        buyColor
    else if signal == -1
        sellColor
    else
        neutralColor

// ============================================================================
// SIGNAL TREND ANALYSIS
// ============================================================================

// @function Check if signal is trending (consecutive matching signals)
// @param signals Array of recent signals
// @param minLength Minimum length for trend confirmation
// @returns True if trending
export isTrendingSignal(array<int> signals, simple int minLength = 3) =>
    if array.size(signals) < minLength
        false
    else
        lastSignal = array.get(signals, array.size(signals) - 1)
        trendCount = 0
        for i = 1 to math.min(minLength, array.size(signals))
            idx = array.size(signals) - i
            if array.get(signals, idx) == lastSignal
                trendCount += 1
        trendCount >= minLength

// @function Get signal momentum (rate of signal change)
// @param currentSignal Current signal
// @param previousSignal Previous signal
// @returns Momentum: positive (strengthening), negative (weakening), 0 (no change)
export signalMomentum(int currentSignal, int previousSignal) =>
    if currentSignal == previousSignal
        0
    else if (currentSignal > previousSignal)
        1   // Signal strengthening (e.g., neutral to buy, or sell to neutral)
    else
        -1  // Signal weakening

// ============================================================================
// SIGNAL ALERT CONDITIONS
// ============================================================================

// @function Check for signal crossover (change from one signal to another)
// @param currentSignal Current bar signal
// @param previousSignal Previous bar signal
// @returns True if signal has changed
export isSignalCrossover(int currentSignal, int previousSignal) =>
    currentSignal != previousSignal

// @function Check for buy signal trigger
// @param signal Current signal
// @returns True if buy signal detected
export isBuySignal(int signal) =>
    signal == 1

// @function Check for sell signal trigger
// @param signal Current signal
// @returns True if sell signal detected
export isSellSignal(int signal) =>
    signal == -1

// @function Generate alert message
// @param signal Signal value
// @param symbol Trading symbol
// @param timeframe Current timeframe
// @returns Alert message string
export alertMessage(int signal, simple string symbol = "", simple string timeframe = "") =>
    signalType = signal == 1 ? "BUY" : signal == -1 ? "SELL" : "NEUTRAL"
    symbolStr = symbol != "" ? " " + symbol : ""
    tfStr = timeframe != "" ? " @ " + timeframe : ""
    "[" + signalType + "]" + symbolStr + tfStr