// 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;
 
namespace Microsoft.CodeAnalysis;
 
/// <summary>
/// The <see cref="EventArgs"/> describing any kind of workspace change.
/// </summary>
/// <remarks>
/// When linked files are edited, one document change event is fired per linked file. All of
/// these events contain the same <see cref="OldSolution"/>, and they all contain the same
/// <see cref="NewSolution"/>. This is so that we can trigger document change events on all
/// affected documents without reporting intermediate states in which the linked file contents
/// do not match.
/// </remarks>
public class WorkspaceChangeEventArgs : EventArgs
{
    public WorkspaceChangeKind Kind { get; }
 
    /// <remarks>
    /// If linked documents are being changed, there may be multiple events with the same <see cref="OldSolution"/>
    /// and <see cref="NewSolution"/>.  Note that the workspace starts with its solution set to an empty solution.
    /// <see cref="WorkspaceChangeKind.SolutionAdded"/> replaces the previous solution, which might be the empty
    /// one.
    /// </remarks>
    public Solution OldSolution { get; }
 
    /// <remarks>
    /// If linked documents are being changed, there may be multiple events with the same <see cref="OldSolution"/>
    /// and <see cref="NewSolution"/>. Note <see cref="WorkspaceChangeKind.SolutionRemoved"/> replaces the previous
    /// solution with the empty one.
    /// </remarks>
    public Solution NewSolution { get; }
 
    /// <summary>
    /// The id of the affected <see cref="Project"/>.  Can be <see langword="null"/> if this is an change unrelated
    /// to a project (for example <see cref="WorkspaceChangeKind.SolutionReloaded"/>.  Should be non-<see
    /// langword="null"/> for:
    /// <list type="bullet">
    /// <item><see cref="WorkspaceChangeKind.ProjectAdded"/></item>
    /// <item><see cref="WorkspaceChangeKind.ProjectChanged"/></item>
    /// <item><see cref="WorkspaceChangeKind.ProjectReloaded"/></item>
    /// <item><see cref="WorkspaceChangeKind.ProjectRemoved"/></item>
    /// </list>
    /// </summary>
    public ProjectId? ProjectId { get; }
 
    /// <summary>
    /// The id of the affected <see cref="Document"/>.  Can be <see langword="null"/> if this is an change unrelated
    /// to a document (for example <see cref="WorkspaceChangeKind.ProjectAdded"/>. Should be non-<see
    /// langword="null"/> for:
    /// <list type="bullet">
    /// <item><see cref="WorkspaceChangeKind.DocumentAdded"/></item>
    /// <item><see cref="WorkspaceChangeKind.DocumentChanged"/></item>
    /// <item><see cref="WorkspaceChangeKind.DocumentInfoChanged"/></item>
    /// <item><see cref="WorkspaceChangeKind.DocumentReloaded"/></item>
    /// <item><see cref="WorkspaceChangeKind.DocumentRemoved"/></item>
    /// </list>
    /// </summary>
    public DocumentId? DocumentId { get; }
 
    public WorkspaceChangeEventArgs(WorkspaceChangeKind kind, Solution oldSolution, Solution newSolution, ProjectId? projectId = null, DocumentId? documentId = null)
    {
        if (!kind.IsValid())
            throw new ArgumentOutOfRangeException(nameof(kind));
 
        this.Kind = kind;
        this.OldSolution = oldSolution ?? throw new ArgumentNullException(nameof(oldSolution));
        this.NewSolution = newSolution ?? throw new ArgumentNullException(nameof(newSolution));
        this.ProjectId = projectId;
        this.DocumentId = documentId;
    }
}