// <copyright file="ITraceAnonymizer.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
// </copyright>
// Sprint: SPRINT_20260105_002_002_TEST_trace_replay_evidence
// Task: TREP-001, TREP-002

using System.Collections.Immutable;

namespace StellaOps.Replay.Anonymization;

/// <summary>
/// Anonymizes production traces for safe use in testing.
/// </summary>
public interface ITraceAnonymizer
{
    /// <summary>
    /// Anonymize a production trace, removing PII and sensitive data.
    /// </summary>
    /// <param name="trace">The production trace to anonymize.</param>
    /// <param name="options">Anonymization options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The anonymized trace.</returns>
    Task<AnonymizedTrace> AnonymizeAsync(
        ProductionTrace trace,
        AnonymizationOptions options,
        CancellationToken ct = default);

    /// <summary>
    /// Validate that a trace is properly anonymized.
    /// </summary>
    /// <param name="trace">The anonymized trace to validate.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Validation result.</returns>
    Task<AnonymizationValidationResult> ValidateAnonymizationAsync(
        AnonymizedTrace trace,
        CancellationToken ct = default);
}

/// <summary>
/// Options controlling trace anonymization behavior.
/// </summary>
/// <param name="RedactImageNames">Whether to redact container image names.</param>
/// <param name="RedactUserIds">Whether to redact user identifiers.</param>
/// <param name="RedactIpAddresses">Whether to redact IP addresses.</param>
/// <param name="RedactFilePaths">Whether to redact file paths.</param>
/// <param name="RedactEnvironmentVariables">Whether to redact environment variables.</param>
/// <param name="PreserveTimingPatterns">Whether to preserve relative timing patterns.</param>
/// <param name="AdditionalPiiPatterns">Additional regex patterns to treat as PII.</param>
/// <param name="AllowlistedValues">Values to preserve without redaction.</param>
public sealed record AnonymizationOptions(
    bool RedactImageNames = true,
    bool RedactUserIds = true,
    bool RedactIpAddresses = true,
    bool RedactFilePaths = true,
    bool RedactEnvironmentVariables = true,
    bool PreserveTimingPatterns = true,
    ImmutableArray<string> AdditionalPiiPatterns = default,
    ImmutableArray<string> AllowlistedValues = default)
{
    /// <summary>
    /// Default anonymization options with all redactions enabled.
    /// </summary>
    public static AnonymizationOptions Default => new();

    /// <summary>
    /// Minimal anonymization that only redacts obvious PII.
    /// </summary>
    public static AnonymizationOptions Minimal => new(
        RedactFilePaths: false,
        RedactEnvironmentVariables: false);
}

/// <summary>
/// Result of anonymization validation.
/// </summary>
/// <param name="IsValid">Whether the trace is properly anonymized.</param>
/// <param name="Violations">Any detected PII violations.</param>
/// <param name="Warnings">Non-critical warnings about the trace.</param>
public sealed record AnonymizationValidationResult(
    bool IsValid,
    ImmutableArray<PiiViolation> Violations,
    ImmutableArray<string> Warnings)
{
    /// <summary>
    /// Creates a successful validation result.
    /// </summary>
    public static AnonymizationValidationResult Success() =>
        new(true, ImmutableArray<PiiViolation>.Empty, ImmutableArray<string>.Empty);

    /// <summary>
    /// Creates a failed validation result with violations.
    /// </summary>
    public static AnonymizationValidationResult Failure(params PiiViolation[] violations) =>
        new(false, [.. violations], ImmutableArray<string>.Empty);
}

/// <summary>
/// A detected PII violation in an anonymized trace.
/// </summary>
/// <param name="SpanId">The span containing the violation.</param>
/// <param name="FieldPath">Path to the field containing PII.</param>
/// <param name="ViolationType">Type of PII detected.</param>
/// <param name="SampleValue">Masked sample of the detected value.</param>
public sealed record PiiViolation(
    string SpanId,
    string FieldPath,
    PiiType ViolationType,
    string SampleValue);

/// <summary>
/// Types of PII that can be detected.
/// </summary>
public enum PiiType
{
    IpAddress,
    Email,
    UserId,
    FilePath,
    ImageName,
    EnvironmentVariable,
    Uuid,
    Custom
}