namespace AvParser.Core.Parsing;

/// <summary>
/// The pluggable unit of the whole application: turns one input into a stream of outcomes.
/// </summary>
/// <remarks>
/// Results are streamed rather than returned as a batch so that the UI can render partial
/// results, report progress and honour cancellation on inputs of arbitrary size.
/// </remarks>
public interface IParser<in TInput, TOutput>
{
    /// <summary>Stable identifier used for persistence and lookup. Never localise this.</summary>
    string Id { get; }

    /// <summary>Human-readable name shown in the UI.</summary>
    string DisplayName { get; }

    /// <summary>One-line explanation of what this parser accepts.</summary>
    string Description { get; }

    /// <summary>Cheap structural check — must not throw and must not do IO.</summary>
    bool CanParse(TInput input);

    /// <summary>
    /// Whether this parser makes network requests and therefore needs a working proxy.
    /// </summary>
    /// <remarks>
    /// A default implementation rather than an abstract member, so adding a parser stays a
    /// one-line change: a parser that works on text the user pasted opts out by saying nothing.
    /// Parsers that fetch anything must set this, or they will run direct even when the user has
    /// asked for proxy-only operation.
    /// </remarks>
    bool RequiresNetwork => false;

    /// <summary>Streams one outcome per logical record.</summary>
    IAsyncEnumerable<ParseOutcome<TOutput>> ParseAsync(
        TInput input,
        IProgress<ParseProgress>? progress,
        CancellationToken cancellationToken
    );
}