Pass additional context to annotation providers

This allows more powerful dynamic resolution of annotation values

Author: mhutch

src/System.CommandLine.Subsystems.Tests/AlternateSubsystems.cs

@@ -30,7 +30,7 @@ public VersionThatUsesHelpData(CliSymbol symbol)
 
             public override void Execute(PipelineResult pipelineResult)
             {
-                pipelineResult.Pipeline.Annotations.TryGet(Symbol, HelpAnnotations.Description, out string? description);
+                pipelineResult.Annotations.TryGet(Symbol, HelpAnnotations.Description, out string? description);
                 pipelineResult.ConsoleHack.WriteLine(description);
                 pipelineResult.AlreadyHandled = true;
                 pipelineResult.SetSuccess();

src/System.CommandLine.Subsystems/Pipeline.cs

@@ -75,7 +75,6 @@ private Pipeline(IEnumerable<IAnnotationProvider>? annotationProviders = null)
         this.annotationProviders = annotationProviders is not null
             ? [..annotationProviders]
             : [];
-        Annotations = new(this.annotationProviders);
     }
 
     /// <summary>
@@ -194,11 +193,6 @@ public ErrorReportingSubsystem? ErrorReporting
     /// </summary>
     public ResponseSubsystem Response { get; }
 
-    /// <summary>
-    /// Gets the annotation resolver
-    /// </summary>
-    public AnnotationResolver Annotations { get; }
-
     /// <summary>
     /// Gets the list of annotation providers registered with the pipeline
     /// </summary>

src/System.CommandLine.Subsystems/PipelineResult.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System.CommandLine.Parsing;
+using System.CommandLine.Subsystems.Annotations;
 
 namespace System.CommandLine;
 
@@ -18,6 +19,7 @@ public PipelineResult(ParseResult parseResult, string rawInput, Pipeline? pipeli
         Pipeline = pipeline ?? Pipeline.CreateEmpty();
         ConsoleHack = consoleHack ?? new ConsoleHack();
         valueProvider = new ValueProvider(this);
+        Annotations = new AnnotationResolver(this);
     }
 
     public ParseResult ParseResult { get; }
@@ -27,6 +29,8 @@ public PipelineResult(ParseResult parseResult, string rawInput, Pipeline? pipeli
     public Pipeline Pipeline { get; }
     public ConsoleHack ConsoleHack { get; }
 
+    public AnnotationResolver Annotations { get; }
+
     public bool AlreadyHandled { get; set; }
     public int ExitCode { get; set; }
 

src/System.CommandLine.Subsystems/Subsystems/Annotations/AnnotationResolveContext.cs

@@ -0,0 +1,36 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System.CommandLine.Parsing;
+
+namespace System.CommandLine.Subsystems.Annotations;
+
+/// <summary>
+/// Additional context that is passed to <see cref="IAnnotationProvider"/>.
+/// </summary>
+/// <remarks>
+/// This class exists so that additional context properties can be added without
+/// breaking existing <see cref="IAnnotationProvider"/> implementations.
+/// <para>
+/// This is intended to be usable independently of the pipeline. For example, a method could be
+/// implemented that takes a <see cref="CommandLine.ParseResult"/> and prints help output based on the help
+/// annotations in the <see cref="CliSymbol"/> tree, which would then be usable by developers who
+/// are using the <see cref="CliParser"/> API directly.
+/// </para>
+/// </remarks>
+public class AnnotationResolveContext(ParseResult parseResult)
+{
+    public AnnotationResolveContext(PipelineResult pipelineResult)
+    : this(pipelineResult.ParseResult)
+    {
+    }
+
+    /// <summary>
+    /// The <see cref="ParseResult"/> for which annotations are being resolved.
+    /// </summary>
+    /// <remarks>
+    /// This may be used to resolve different values for an annotation based on the parents of the symbol,
+    /// or based on values of other symbols in the parse result.
+    /// </remarks>
+    public ParseResult ParseResult { get; } = parseResult;
+}

src/System.CommandLine.Subsystems/Subsystems/Annotations/AnnotationResolver.cs

@@ -10,13 +10,18 @@ namespace System.CommandLine.Subsystems.Annotations;
 /// taking into account both the values stored directly on the symbol via extension methods
 /// and any values from <see cref="IAnnotationProvider"/> providers.
 /// </summary>
+/// <param name="providers">The providers from which annotation values will be resolved</param>
+/// <param name="context">The context for resolving annotation values</param>
 /// <remarks>
 /// The <paramref name="providers"/> will be enumerated each time an annotation value is requested.
 /// It may be modified after the resolver is created.
 /// </remarks>
-public class AnnotationResolver(ICollection<IAnnotationProvider> providers)
+public class AnnotationResolver(IEnumerable<IAnnotationProvider> providers, AnnotationResolveContext context)
 {
-    private readonly IEnumerable<IAnnotationProvider> providers = providers ?? throw new ArgumentNullException(nameof(providers));
+    public AnnotationResolver(PipelineResult pipelineResult)
+        : this(pipelineResult.Pipeline.AnnotationProviders, new AnnotationResolveContext(pipelineResult))
+    {
+    }
 
     /// <summary>
     /// Attempt to retrieve the <paramref name="symbol"/>'s value for the annotation <paramref name="id"/>. This will check any
@@ -48,7 +53,7 @@ public bool TryGet<TValue>(CliSymbol symbol, AnnotationId annotationId, [NotNull
     {
         foreach (var provider in providers)
         {
-            if (provider.TryGet(symbol, annotationId, out object? rawValue))
+            if (provider.TryGet(symbol, annotationId, context, out object? rawValue))
             {
                 if (rawValue is TValue expectedTypeValue)
                 {
@@ -87,7 +92,7 @@ public bool TryGet(CliSymbol symbol, AnnotationId annotationId, [NotNullWhen(tru
     {
         foreach (var provider in providers)
         {
-            if (provider.TryGet(symbol, annotationId, out value))
+            if (provider.TryGet(symbol, annotationId, context, out value))
             {
                 return true;
             }

src/System.CommandLine.Subsystems/Subsystems/Annotations/IAnnotationProvider.cs

@@ -0,0 +1,22 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace System.CommandLine.Subsystems.Annotations;
+
+/// <summary>
+/// Alternative storage of annotations, enabling lazy loading and dynamic annotations.
+/// </summary>
+public interface IAnnotationProvider
+{
+    /// <summary>
+    /// Try to get the value of the annotation with the given <paramref name="id"/> for the <paramref name="symbol"/>.
+    /// </summary>
+    /// <param name="context">Additional context that may be used when resolving the annotation value.</param>
+    /// <param name="symbol">The symbol</param>
+    /// <param name="annotationId">The annotation identifier</param>
+    /// <param name="value">The annotation value</param>
+    /// <returns><see langword="true"> if the  symbol was resolved, otherwise <see langword="false"></returns>
+    bool TryGet(CliSymbol symbol, AnnotationId annotationId, AnnotationResolveContext context, [NotNullWhen(true)] out object? value);
+}