using System.Collections.Immutable;

namespace StellaOps.BinaryIndex.GoldenSet;

/// <summary>
/// Service for looking up known sinks and their metadata.
/// </summary>
public interface ISinkRegistry
{
    /// <summary>
    /// Checks if a sink is known in the registry.
    /// </summary>
    /// <param name="sinkName">The sink function name.</param>
    /// <returns>True if the sink is known; otherwise, false.</returns>
    bool IsKnownSink(string sinkName);

    /// <summary>
    /// Gets detailed information about a sink.
    /// </summary>
    /// <param name="sinkName">The sink function name.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Sink information or null if not found.</returns>
    Task<SinkInfo?> GetSinkInfoAsync(string sinkName, CancellationToken ct = default);

    /// <summary>
    /// Gets all sinks in a category.
    /// </summary>
    /// <param name="category">The category to filter by.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>List of sinks in the category.</returns>
    Task<ImmutableArray<SinkInfo>> GetSinksByCategoryAsync(string category, CancellationToken ct = default);

    /// <summary>
    /// Gets all sinks associated with a CWE ID.
    /// </summary>
    /// <param name="cweId">The CWE ID to filter by.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>List of sinks associated with the CWE.</returns>
    Task<ImmutableArray<SinkInfo>> GetSinksByCweAsync(string cweId, CancellationToken ct = default);
}

/// <summary>
/// Information about a known sink function.
/// </summary>
/// <param name="Name">Sink function name.</param>
/// <param name="Category">Category (e.g., "memory", "command_injection").</param>
/// <param name="Description">Human-readable description.</param>
/// <param name="CweIds">Associated CWE IDs.</param>
/// <param name="Severity">Severity level (low, medium, high, critical).</param>
public sealed record SinkInfo(
    string Name,
    string Category,
    string? Description,
    ImmutableArray<string> CweIds,
    string Severity);

/// <summary>
/// Well-known sink categories.
/// </summary>
public static class SinkCategory
{
    /// <summary>Memory corruption sinks (memcpy, strcpy, etc.).</summary>
    public const string Memory = "memory";

    /// <summary>Command injection sinks (system, exec, etc.).</summary>
    public const string CommandInjection = "command_injection";

    /// <summary>Code injection sinks (dlopen, LoadLibrary, etc.).</summary>
    public const string CodeInjection = "code_injection";

    /// <summary>Path traversal sinks (fopen, open, etc.).</summary>
    public const string PathTraversal = "path_traversal";

    /// <summary>Network-related sinks (connect, send, etc.).</summary>
    public const string Network = "network";

    /// <summary>SQL injection sinks.</summary>
    public const string SqlInjection = "sql_injection";

    /// <summary>Cryptographic sinks.</summary>
    public const string Crypto = "crypto";
}