[Backport] Always run 'required' generators: (#80058)

- Add a CreateOnlyRequired generation state
- Add a filter that only runs razor when required generators are
requested

Manual backport of #79510

Author: phil-allen-msft

src/VisualStudio/Core/Test.Next/Services/ServiceHubServicesTests.cs

@@ -47,9 +47,9 @@ ValueTask<ImmutableArray<string>> GetContentsAsync(
         Checksum solutionChecksum, ProjectId projectId, ImmutableArray<DocumentId> documentIds, bool withFrozenSourceGeneratedDocuments, CancellationToken cancellationToken);
 
     /// <summary>
-    /// Whether or not the specified analyzer references have source generators or not.
+    /// Whether or not the specified analyzer references have source generators, and which kind of generators they have if they do.
     /// </summary>
-    ValueTask<bool> HasGeneratorsAsync(
+    ValueTask<SourceGeneratorPresence> GetSourceGeneratorPresenceAsync(
         Checksum solutionChecksum, ProjectId projectId, ImmutableArray<Checksum> analyzerReferenceChecksums, string language, CancellationToken cancellationToken);
 
     /// <summary>

src/Workspaces/Core/Portable/SourceGeneration/IRemoteSourceGenerationService.cs

@@ -0,0 +1,44 @@
+// 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.Collections.Immutable;
+using System.Linq;
+
+namespace Microsoft.CodeAnalysis.SourceGeneration;
+
+internal static class SourceGeneratorExtensions
+{
+    /// <summary>
+    /// Determines if this generator is considered required, and should still run when the 
+    /// solution <see cref="SolutionCompilationState.GeneratedDocumentCreationPolicy"/> is set to
+    /// <see cref="SolutionCompilationState.GeneratedDocumentCreationPolicy.CreateOnlyRequired"/>.
+    /// </summary>
+    /// <param name="generator">The generator to test</param>
+    /// <returns><c>True</c> if the generator is considered 'required'</returns>
+    /// <remarks>
+    /// Currently, only Razor is considered to be a required generator.
+    /// </remarks>
+    public static bool IsRequiredGenerator(this ISourceGenerator generator)
+    {
+        // For now, we hard code the required generator list to Razor.
+        // In the future we might want to expand this to e.g. run any generators with open generated files
+        return generator.GetGeneratorType().FullName == "Microsoft.NET.Sdk.Razor.SourceGenerators.RazorSourceGenerator";
+    }
+
+    /// <summary>
+    /// Determines the presence and type of source generators in the specified collection.
+    /// </summary>
+    /// <returns>A value indicating whether the collection contains no source generators, only optional source generators, or at
+    /// least one required source generator.</returns>
+    public static SourceGeneratorPresence GetSourceGeneratorPresence(this ImmutableArray<ISourceGenerator> generators)
+    {
+        if (generators.IsDefaultOrEmpty)
+            return SourceGeneratorPresence.NoSourceGenerators;
+
+        var hasRequiredGenerators = generators.Any(g => g.IsRequiredGenerator());
+        return hasRequiredGenerators
+            ? SourceGeneratorPresence.ContainsRequiredSourceGenerators
+            : SourceGeneratorPresence.OnlyOptionalSourceGenerators;
+    }
+}

src/Workspaces/Core/Portable/SourceGeneration/SourceGeneratorExtensions.cs

@@ -0,0 +1,28 @@
+// 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.
+
+namespace Microsoft.CodeAnalysis.SourceGeneration;
+
+/// <summary>
+/// Indicates the presence and types of source generators in a project.
+/// </summary>
+internal enum SourceGeneratorPresence
+{
+    /// <summary>
+    /// The project contains no source generators.
+    /// </summary>
+    NoSourceGenerators,
+
+    /// <summary>
+    /// The project contains source generators, but none of them are considered "required".
+    /// These generators may be skipped in certain scenarios for performance reasons.
+    /// </summary>
+    OnlyOptionalSourceGenerators,
+
+    /// <summary>
+    /// The project contains at least one required source generator that must always run.
+    /// The project may also contain additional optional generators.
+    /// </summary>
+    ContainsRequiredSourceGenerators
+}

src/Workspaces/Core/Portable/SourceGeneration/SourceGeneratorPresence.cs

@@ -16,6 +16,15 @@ private enum GeneratedDocumentCreationPolicy
         /// </summary>
         Create,
 
+        /// <summary>
+        /// Source generators that are considered required should be run and produce results. Previously
+        /// computed results should be reused for other generators.
+        /// </summary>
+        /// <remarks>
+        /// Today the only required generator is Razor.
+        /// </remarks>
+        CreateOnlyRequired,
+
         /// <summary>
         /// Source generators should not run.  Whatever results were previously computed should be reused.
         /// </summary>

src/Workspaces/Core/Portable/Workspace/Solution/SolutionCompilationState.CreationPolicy.cs

@@ -47,7 +47,7 @@ bool ContainsAssemblyOrModuleOrDynamic(
         ICompilationTracker WithCreateCreationPolicy(bool forceRegeneration);
 
         /// <summary>
-        /// Updates the creation policy for this tracker.  Setting it to <see cref="CreationPolicy.DoNotCreate"/>.
+        /// Updates the creation policy for this tracker. Setting it to <see cref="CreationPolicy.DoNotCreate"/>.
         /// </summary>
         ICompilationTracker WithDoNotCreateCreationPolicy();
 

src/Workspaces/Core/Portable/Workspace/Solution/SolutionCompilationState.ICompilationTracker.cs

@@ -589,21 +589,21 @@ await compilationState.GetCompilationAsync(
                     cancellationToken).ConfigureAwait(false);
 
                 // Our generated documents are up to date if we just created them.  Note: when in balanced mode, we
-                // will then change our creation policy below to DoNotCreate.  This means that any successive forks
-                // will move us to an in-progress-state that is not running generators.  And the next time we get
-                // here and produce a final compilation, this will then be 'false' since we'll be reusing old
-                // generated docs.
+                // will then change our creation policy below to CreateOnlyRequired.  This means that any successive
+                // forks will move us to an in-progress-state that only runs required generators. The next time we get
+                // here and produce a final compilation, this will then be 'false' since we'll only be generating required
+                // docs and combining them with the old docs from other generators.
                 //
                 // This flag can then be used later when we hear about external user events (like save/build) to
                 // decide if we need to do anything.  If the generated documents are up to date, then we don't need
                 // to do anything in that case.
                 var generatedDocumentsUpToDate = creationPolicy.GeneratedDocumentCreationPolicy == GeneratedDocumentCreationPolicy.Create;
 
                 // If the user has the option set to only run generators to something other than 'automatic' then we
-                // want to set ourselves to not run generators again now that generators have run.  That way, any
-                // further *automatic* changes to the solution will not run generators again.  Instead, when one of
-                // those external events happen, we'll grab the workspace's solution, transition all states *out* of
-                // this state and then let the next 'GetCompilationAsync' operation cause generators to run.
+                // want to set ourselves to only run required generators now that all other generators have run.  That way,
+                // any further *automatic* changes to the solution will only run the required generators again.
+                // When one of those external events happen, we'll grab the workspace's solution, transition all states
+                // *out* of this state and then let the next 'GetCompilationAsync' operation cause all generators to run.
                 //
                 // Similarly, we don't want to automatically create skeletons at this point (unless they're missing
                 // entirely).
@@ -612,7 +612,7 @@ await compilationState.GetCompilationAsync(
                 if (workspacePreference != SourceGeneratorExecutionPreference.Automatic)
                 {
                     if (creationPolicy.GeneratedDocumentCreationPolicy == GeneratedDocumentCreationPolicy.Create)
-                        creationPolicy = creationPolicy with { GeneratedDocumentCreationPolicy = GeneratedDocumentCreationPolicy.DoNotCreate };
+                        creationPolicy = creationPolicy with { GeneratedDocumentCreationPolicy = GeneratedDocumentCreationPolicy.CreateOnlyRequired };
 
                     if (creationPolicy.SkeletonReferenceCreationPolicy == SkeletonReferenceCreationPolicy.Create)
                         creationPolicy = creationPolicy with { SkeletonReferenceCreationPolicy = SkeletonReferenceCreationPolicy.CreateIfAbsent };

src/Workspaces/Core/Portable/Workspace/Solution/SolutionCompilationState.RegularCompilationTracker.cs

@@ -36,10 +36,12 @@ private sealed partial class RegularCompilationTracker : ICompilationTracker
             Compilation? compilationWithStaleGeneratedTrees,
             CancellationToken cancellationToken)
         {
-            if (creationPolicy.GeneratedDocumentCreationPolicy is GeneratedDocumentCreationPolicy.DoNotCreate)
+            var canSkipRunningGenerators = await CanSkipRunningGeneratorsAsync(creationPolicy, compilationState, cancellationToken).ConfigureAwait(false);
+            if (canSkipRunningGenerators)
             {
-                // We're frozen.  So we do not want to go through the expensive cost of running generators.  Instead, we
-                // just whatever prior generated docs we have.
+                // We're either frozen, or we only want required generators and know that there aren't any to run, so we
+                // do not want to go through the expensive cost of running generators.  Instead, we just use whatever
+                // prior generated docs we have.
                 var generatedSyntaxTrees = await generatorInfo.Documents.States.Values.SelectAsArrayAsync(
                     static (state, cancellationToken) => state.GetSyntaxTreeAsync(cancellationToken), cancellationToken).ConfigureAwait(false);
 
@@ -69,9 +71,33 @@ private sealed partial class RegularCompilationTracker : ICompilationTracker
                     generatorInfo.Documents,
                     generatorInfo.Driver,
                     compilationWithStaleGeneratedTrees,
+                    creationPolicy.GeneratedDocumentCreationPolicy,
                     cancellationToken).ConfigureAwait(false);
                 return (compilationWithGeneratedFiles, new(nextGeneratedDocuments, nextGeneratorDriver));
             }
+
+            async ValueTask<bool> CanSkipRunningGeneratorsAsync(CreationPolicy creationPolicy, SolutionCompilationState compilationState, CancellationToken cancellationToken)
+            {
+                // if we don't want to create generated documents, we can skip
+                if (creationPolicy.GeneratedDocumentCreationPolicy is GeneratedDocumentCreationPolicy.DoNotCreate)
+                    return true;
+
+                // if we only want required documents, we can skip if we don't have any required generators
+                if (creationPolicy.GeneratedDocumentCreationPolicy is GeneratedDocumentCreationPolicy.CreateOnlyRequired)
+                {
+                    var hasRequiredGenerators = await HasRequiredGeneratorsAsync(compilationState, cancellationToken).ConfigureAwait(false);
+                    return !hasRequiredGenerators;
+                }
+
+                // we need to run generators
+                return false;
+            }
+        }
+
+        private async Task<bool> HasRequiredGeneratorsAsync(SolutionCompilationState compilationState, CancellationToken cancellationToken)
+        {
+            var presence = await compilationState.GetProjectGeneratorPresenceAsync(ProjectState.Id, cancellationToken).ConfigureAwait(false);
+            return presence is SourceGeneratorPresence.ContainsRequiredSourceGenerators;
         }
 
         private async Task<(Compilation compilationWithGeneratedFiles, TextDocumentStates<SourceGeneratedDocumentState> generatedDocuments)?> TryComputeNewGeneratorInfoInRemoteProcessAsync(
@@ -236,12 +262,16 @@ await newGeneratedDocuments.States.Values.SelectAsArrayAsync(
             TextDocumentStates<SourceGeneratedDocumentState> oldGeneratedDocuments,
             GeneratorDriver? generatorDriver,
             Compilation? compilationWithStaleGeneratedTrees,
+            GeneratedDocumentCreationPolicy creationPolicy,
             CancellationToken cancellationToken)
         {
             // If we don't have any source generators.  Trivially bail out.
             if (!await compilationState.HasSourceGeneratorsAsync(this.ProjectState.Id, cancellationToken).ConfigureAwait(false))
                 return (compilationWithoutGeneratedFiles, TextDocumentStates<SourceGeneratedDocumentState>.Empty, generatorDriver);
 
+            // Hold onto the prior results so we can compare when filtering
+            var priorRunResult = generatorDriver?.GetRunResult();
+
             // If we don't already have an existing generator driver, create one from scratch
             generatorDriver ??= CreateGeneratorDriver(this.ProjectState);
 
@@ -268,7 +298,7 @@ await newGeneratedDocuments.States.Values.SelectAsArrayAsync(
             var compilationToRunGeneratorsOn = compilationWithoutGeneratedFiles.RemoveSyntaxTrees(treesToRemove);
             // END HACK HACK HACK HACK.
 
-            generatorDriver = generatorDriver.RunGenerators(compilationToRunGeneratorsOn, cancellationToken);
+            generatorDriver = generatorDriver.RunGenerators(compilationToRunGeneratorsOn, ShouldGeneratorRun, cancellationToken);
 
             Contract.ThrowIfNull(generatorDriver);
 
@@ -425,6 +455,46 @@ static void CheckGeneratorDriver(GeneratorDriver generatorDriver, ProjectState p
 
                 Contract.ThrowIfFalse(additionalTexts.Length == projectState.AdditionalDocumentStates.Count);
             }
+
+            bool ShouldGeneratorRun(GeneratorFilterContext context)
+            {
+                // We should never try and run a generator driver if we're not expecting to do any work
+                Contract.ThrowIfTrue(creationPolicy is GeneratedDocumentCreationPolicy.DoNotCreate);
+
+                // If we're in Create mode, we're always going to run all generators
+                if (creationPolicy is GeneratedDocumentCreationPolicy.Create)
+                    return true;
+
+                // If we get here we expect to be in CreateOnlyRequired. Throw to ensure we catch if someone adds a new state
+                Contract.ThrowIfFalse(creationPolicy is GeneratedDocumentCreationPolicy.CreateOnlyRequired);
+
+                // We want to only run required generators, but it's also possible that there are generators that 
+                // have never been run (for instance, an AddGenerator operation might have occurred between runs).
+                // Our model is that it's acceptable for documents to be slightly out of date, but it is
+                // fundamentally incorrect to have *no* documents for a generator that could be producing them.
+
+                // If there was no prior run result, then we can't have any documents for this generator, so we
+                // need to re-run it.
+                if (priorRunResult is null)
+                    return true;
+
+                // Next we need to check if this particular generator was run as part of the prior driver execution.
+                // Either we have no state for the generator, in which case it can't have run. If we do have state,
+                // the contract from the generator driver is that a generator that hasn't run yet produces a default
+                // ImmutableArray for GeneratedSources. Note that this is different from an empty array, which
+                // indicates that the generator ran, but didn't produce any documents:
+
+                // - GeneratedSources == default ImmutableArray: the generator was not invoked during that run (must run).
+                // - GeneratedSources == non-default empty array: the generator ran but produced no documents (may skip).
+                // - GeneratedSources == non-default non-empty array: the generator ran and produced documents (may skip).
+
+                if (!priorRunResult.Results.Any(r => r.Generator == context.Generator && !r.GeneratedSources.IsDefault))
+                    return true;
+
+                // We have results for this generator, and we're in CreateOnlyRequired, so only run this generator if
+                // we consider it to be required.
+                return context.Generator.IsRequiredGenerator();
+            }
         }
     }
 }