// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
 
#nullable disable
 
using System.Collections.Generic;
using System.Collections.Immutable;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.CodeAnalysis.Text;
 
namespace Microsoft.CodeAnalysis.Host
{
    /// <summary>
    /// Map spans in a document to other spans even in other document
    ///
    /// this will be used by various features if provided to convert span in one document to other spans.
    /// 
    /// for example, it is used to show spans users expect in a razor file rather than spans in 
    /// auto generated file that is implementation detail or navigate to the right place rather 
    /// than the generated file and etc.
    /// </summary>
    internal interface ISpanMappingService : IDocumentService
    {
        /// <summary>
        /// Whether this span mapping service can handle mapping import directives added to a document.
        /// </summary>
        bool SupportsMappingImportDirectives { get; }
 
        Task<ImmutableArray<(string mappedFilePath, TextChange mappedTextChange)>> GetMappedTextChangesAsync(
            Document oldDocument,
            Document newDocument,
            CancellationToken cancellationToken);
 
        /// <summary>
        /// Map spans in the document to more appropriate locations
        /// 
        /// in current design, this can NOT map a span to a span that is not backed by a file.
        /// for example, roslyn supports someone to have a document that is not backed by a file. and current design doesn't allow
        /// such document to be returned from this API
        /// for example, span on razor secondary buffer document in roslyn solution mapped to a span on razor cshtml file is possible but
        /// a span on razor cshtml file to a span on secondary buffer document is not possible since secondary buffer document is not backed by a file
        /// </summary>
        /// <param name="document">Document given spans belong to</param>
        /// <param name="spans">Spans in the document</param>
        /// <param name="cancellationToken">Cancellation token</param>
        /// <returns>Return mapped span. order of result should be same as the given span</returns>
        Task<ImmutableArray<MappedSpanResult>> MapSpansAsync(Document document, IEnumerable<TextSpan> spans, CancellationToken cancellationToken);
    }
 
    /// <summary>
    /// Result of span mapping
    /// </summary>
    internal readonly struct MappedSpanResult
    {
        /// <summary>
        /// Path to mapped file
        /// </summary>
        public readonly string FilePath;
 
        /// <summary>
        /// LinePosition representation of the Span
        /// </summary>
        public readonly LinePositionSpan LinePositionSpan;
 
        /// <summary>
        /// Mapped span
        /// </summary>
        public readonly TextSpan Span;
 
        public MappedSpanResult(string filePath, LinePositionSpan linePositionSpan, TextSpan span)
        {
            if (string.IsNullOrEmpty(filePath))
            {
                throw new System.ArgumentException(nameof(filePath));
            }
 
            FilePath = filePath;
            LinePositionSpan = linePositionSpan;
            Span = span;
        }
 
        public bool IsDefault => FilePath == null;
    }
}