namespace StellaOps.Scanner.Reachability;

/// <summary>
/// Contract for language-specific static lifters that extract callgraph edges
/// and symbol definitions for reachability analysis.
/// </summary>
/// <remarks>
/// Implementers must produce deterministic output: stable ordering, no randomness,
/// and normalized symbol IDs using <see cref="SymbolId"/> helpers.
/// </remarks>
public interface IReachabilityLifter
{
    /// <summary>
    /// Language identifier (e.g., "java", "dotnet", "node").
    /// Must match <see cref="SymbolId.Lang"/> constants.
    /// </summary>
    string Language { get; }

    /// <summary>
    /// Lifts static callgraph information from analyzed artifacts.
    /// </summary>
    /// <param name="context">Analysis context with filesystem access.</param>
    /// <param name="builder">Builder to emit nodes and edges.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Task that completes when lifting is done.</returns>
    ValueTask LiftAsync(ReachabilityLifterContext context, ReachabilityGraphBuilder builder, CancellationToken cancellationToken);
}

/// <summary>
/// Context provided to reachability lifters during analysis.
/// </summary>
public sealed class ReachabilityLifterContext
{
    /// <summary>
    /// Root path of the analysis target (workspace, container layer, etc.).
    /// </summary>
    public required string RootPath { get; init; }

    /// <summary>
    /// Analysis ID for CAS namespacing.
    /// </summary>
    public required string AnalysisId { get; init; }

    /// <summary>
    /// Optional layer digest for container analysis.
    /// </summary>
    public string? LayerDigest { get; init; }

    /// <summary>
    /// Optional entrypoint hint from image config.
    /// </summary>
    public string? Entrypoint { get; init; }

    /// <summary>
    /// Additional options for lifter behavior.
    /// </summary>
    public ReachabilityLifterOptions Options { get; init; } = ReachabilityLifterOptions.Default;
}

/// <summary>
/// Options controlling reachability lifter behavior.
/// </summary>
public sealed class ReachabilityLifterOptions
{
    /// <summary>
    /// Default options for production use.
    /// </summary>
    public static ReachabilityLifterOptions Default { get; } = new();

    /// <summary>
    /// Include edges with low confidence (dynamic/reflection patterns).
    /// </summary>
    public bool IncludeLowConfidenceEdges { get; init; } = true;

    /// <summary>
    /// Include framework/runtime symbols in the graph.
    /// </summary>
    public bool IncludeFrameworkSymbols { get; init; } = true;

    /// <summary>
    /// Maximum depth for transitive edge discovery.
    /// </summary>
    public int MaxTransitiveDepth { get; init; } = 10;
}