namespace StellaOps.Scanner.ChangeTrace.Integration;

/// <summary>
/// Simplified client interface for ReachGraph operations.
/// This is an adapter interface to decouple ChangeTrace from ReachGraph internals.
/// </summary>
public interface IReachGraphClient
{
    /// <summary>
    /// Get reachability information for a package in an image.
    /// </summary>
    /// <param name="imageDigest">Image digest (sha256:...).</param>
    /// <param name="purl">Package URL.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Reachability result.</returns>
    Task<ReachabilityResult> GetReachabilityAsync(
        string imageDigest,
        string purl,
        CancellationToken ct = default);

    /// <summary>
    /// Get call paths to a vulnerable function.
    /// </summary>
    /// <param name="imageDigest">Image digest.</param>
    /// <param name="functionName">Function name.</param>
    /// <param name="maxPaths">Maximum number of paths to return.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Call path result.</returns>
    Task<CallPathResult> GetCallPathsAsync(
        string imageDigest,
        string functionName,
        int maxPaths = 5,
        CancellationToken ct = default);
}

/// <summary>
/// Reachability result for a package.
/// </summary>
public sealed record ReachabilityResult
{
    /// <summary>
    /// Whether the package is reachable from entrypoints.
    /// </summary>
    public required bool IsReachable { get; init; }

    /// <summary>
    /// Number of reachable call paths.
    /// </summary>
    public required int ReachableCallPaths { get; init; }

    /// <summary>
    /// Total number of exported symbols.
    /// </summary>
    public int TotalSymbols { get; init; }

    /// <summary>
    /// Number of reachable symbols.
    /// </summary>
    public int ReachableSymbols { get; init; }

    /// <summary>
    /// Fraction of package that is unreachable (0.0 to 1.0).
    /// </summary>
    public double UnreachableFraction { get; init; }

    /// <summary>
    /// Entrypoints that reach this package.
    /// </summary>
    public IReadOnlyList<string>? ReachingEntrypoints { get; init; }
}

/// <summary>
/// Call path result for a function.
/// </summary>
public sealed record CallPathResult
{
    /// <summary>
    /// Number of call paths found.
    /// </summary>
    public required int PathCount { get; init; }

    /// <summary>
    /// Individual call paths.
    /// </summary>
    public IReadOnlyList<CallPath>? Paths { get; init; }

    /// <summary>
    /// Shortest path depth.
    /// </summary>
    public int? ShortestPathDepth { get; init; }
}

/// <summary>
/// A single call path from entrypoint to target.
/// </summary>
public sealed record CallPath
{
    /// <summary>
    /// Entrypoint function name.
    /// </summary>
    public required string Entrypoint { get; init; }

    /// <summary>
    /// Target function name.
    /// </summary>
    public required string Target { get; init; }

    /// <summary>
    /// Call chain (function names).
    /// </summary>
    public required IReadOnlyList<string> Chain { get; init; }

    /// <summary>
    /// Path depth (number of calls).
    /// </summary>
    public int Depth => Chain.Count;
}