// -----------------------------------------------------------------------------
// BoundaryExtractionContext.cs
// Sprint: SPRINT_3800_0002_0001_boundary_richgraph
// Description: Context for boundary extraction with environment hints.
// -----------------------------------------------------------------------------


using StellaOps.Scanner.Reachability.Gates;
using System;
using System.Collections.Generic;

namespace StellaOps.Scanner.Reachability.Boundary;

/// <summary>
/// Context for boundary extraction, providing environment hints and detected gates.
/// </summary>
public sealed record BoundaryExtractionContext
{
    /// <summary>
    /// Empty context for simple extractions.
    /// </summary>
    /// <remarks>Uses system time. For deterministic timestamps, use <see cref="CreateEmpty"/>.</remarks>
    [Obsolete("Use CreateEmpty(TimeProvider) for deterministic timestamps")]
    public static BoundaryExtractionContext Empty => CreateEmpty();

    /// <summary>
    /// Creates an empty context for simple extractions.
    /// </summary>
    /// <param name="timeProvider">Optional time provider for deterministic timestamps.</param>
    /// <returns>An empty boundary extraction context.</returns>
    public static BoundaryExtractionContext CreateEmpty(TimeProvider? timeProvider = null) => 
        new() { Timestamp = (timeProvider ?? TimeProvider.System).GetUtcNow() };

    /// <summary>
    /// Environment identifier (e.g., "production", "staging").
    /// </summary>
    public string? EnvironmentId { get; init; }

    /// <summary>
    /// Deployment namespace or context (e.g., "default", "kube-system").
    /// </summary>
    public string? Namespace { get; init; }

    /// <summary>
    /// Additional annotations from deployment metadata.
    /// </summary>
    public IReadOnlyDictionary<string, string> Annotations { get; init; } = 
        new Dictionary<string, string>();

    /// <summary>
    /// Gates detected by gate detection analysis.
    /// </summary>
    public IReadOnlyList<DetectedGate> DetectedGates { get; init; } = 
        Array.Empty<DetectedGate>();

    /// <summary>
    /// Whether the service is known to be internet-facing.
    /// </summary>
    public bool? IsInternetFacing { get; init; }

    /// <summary>
    /// Network zone (e.g., "dmz", "internal", "trusted").
    /// </summary>
    public string? NetworkZone { get; init; }

    /// <summary>
    /// Known port bindings (port to protocol).
    /// </summary>
    public IReadOnlyDictionary<int, string> PortBindings { get; init; } =
        new Dictionary<int, string>();

    /// <summary>
    /// Timestamp for the context (for cache invalidation).
    /// </summary>
    public required DateTimeOffset Timestamp { get; init; }

    /// <summary>
    /// Source of this context (e.g., "k8s", "iac", "runtime").
    /// </summary>
    public string? Source { get; init; }

    /// <summary>
    /// Creates a context from detected gates.
    /// </summary>
    /// <param name="gates">The detected gates.</param>
    /// <param name="timeProvider">Optional time provider for deterministic timestamps.</param>
    public static BoundaryExtractionContext FromGates(IReadOnlyList<DetectedGate> gates, TimeProvider? timeProvider = null) =>
        new() { DetectedGates = gates, Timestamp = (timeProvider ?? TimeProvider.System).GetUtcNow() };

    /// <summary>
    /// Creates a context with environment hints.
    /// </summary>
    /// <param name="environmentId">The environment identifier.</param>
    /// <param name="isInternetFacing">Whether the service is internet-facing.</param>
    /// <param name="networkZone">The network zone.</param>
    /// <param name="timeProvider">Optional time provider for deterministic timestamps.</param>
    public static BoundaryExtractionContext ForEnvironment(
        string environmentId,
        bool? isInternetFacing = null,
        string? networkZone = null,
        TimeProvider? timeProvider = null) =>
        new()
        {
            EnvironmentId = environmentId,
            IsInternetFacing = isInternetFacing,
            NetworkZone = networkZone,
            Timestamp = (timeProvider ?? TimeProvider.System).GetUtcNow()
        };
}