// 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.
 
using System.Threading;
using System.Threading.Tasks;
using Microsoft.CodeAnalysis.CodeCleanup;
using Microsoft.CodeAnalysis.Host;
using Microsoft.CodeAnalysis.Simplification;
 
namespace Microsoft.CodeAnalysis.ChangeNamespace
{
    internal interface IChangeNamespaceService : ILanguageService
    {
        /// <summary>
        /// Determine whether we can change the namespace for given <paramref name="container"/> in the document.
        /// Linked documents are not supported, except for a regular document in a multi-targeting project, 
        /// where the container node must be consistent among all linked documents.
        /// Here's the additional requirements on <paramref name="container"/> to use this service:
        /// 
        /// - If <paramref name="container"/> is a namespace declaration node:
        ///    1. Doesn't contain or is nested in other namespace declarations
        ///    2. The name of the namespace is valid (i.e. no errors)
        ///    3. No partial type declared in the namespace. Otherwise its multiple declarations will
        ///       end up in different namespace.
        ///
        /// - If <paramref name="container"/> is a compilation unit node:
        ///    1. It must contain no namespace declaration
        ///    2. No partial type declared in the document. Otherwise its multiple declarations will
        ///       end up in different namespace.
        ///       
        /// - Otherwise, an <see cref="System.ArgumentException"/> will be thrown.
        ///   
        /// Returns <see langword="true"/> only when all the requirements above are met.
        /// </summary>
        /// <remarks>
        /// While this service might be used by features that change namespace based on some property of the document
        /// (e.g. Sync namespace refactoring), those logic is implemented by those individual features and isn't part 
        /// of the IChangeNamespaceService service.
        /// </remarks>
        Task<bool> CanChangeNamespaceAsync(Document document, SyntaxNode container, CancellationToken cancellationToken);
 
        /// <summary>
        /// Change namespace for given <paramref name="container"/> to the name specified by <paramref name="targetNamespace"/>.
        /// Everything declared in the <paramref name="container"/> will be moved to the new namespace. 
        /// Change will only be made if <see cref="CanChangeNamespaceAsync"/> returns <see langword="true"/> and <paramref name="targetNamespace"/>
        /// is a valid name for namespace. Use "" for <paramref name="targetNamespace"/> to specify the global namespace.
        /// 
        /// An <see cref="System.ArgumentException"/> will be thrown if:
        /// 1. <paramref name="container"/> is not a namespace declaration or a compilation unit node.
        /// 2. <paramref name="targetNamespace"/> is null or contains an invalid character.
        /// </summary>
        /// <remarks>
        /// If the declared namespace for <paramref name="container"/> is already identical to <paramref name="targetNamespace"/>, then it will be
        /// a no-op and original solution will be returned.
        /// </remarks>
        Task<Solution> ChangeNamespaceAsync(Document document, SyntaxNode container, string targetNamespace, CodeCleanupOptionsProvider fallbackOptions, CancellationToken cancellationToken);
 
        /// <summary>
        /// Using only the top level namespace declarations of a document, change all of them to the target namespace. Will only
        /// use namespace containers considered valid by <see cref="CanChangeNamespaceAsync(Document, SyntaxNode, CancellationToken)"/>
        /// </summary>
        Task<Solution?> TryChangeTopLevelNamespacesAsync(Document document, string targetNamespace, CodeCleanupOptionsProvider fallbackOptions, CancellationToken cancellationToken);
    }
}