introduce SymbolResult.Errors (#2166)

* introduce `SymbolResult.Errors`

This property makes it possible to inspect results of other symbols from within a custom parser.

* update API baseline

Author: jonsequitur

src/System.CommandLine.ApiCompatibility.Tests/ApiCompatibilityApprovalTests.System_CommandLine_api_is_not_changed.approved.txt

@@ -257,6 +257,7 @@ System.CommandLine.Parsing
     public SymbolResult SymbolResult { get; }
     public System.String ToString()
   public abstract class SymbolResult
+    public System.Collections.Generic.IEnumerable<ParseError> Errors { get; }
     public SymbolResult Parent { get; }
     public System.Collections.Generic.IReadOnlyList<Token> Tokens { get; }
     public System.Void AddError(System.String errorMessage)

src/System.CommandLine.Tests/ArgumentTests.cs

@@ -442,6 +442,52 @@ public void Multiple_arguments_can_have_custom_parsers()
                       .Contain("UH UH");
             }
 
+            [Theory]
+            // The two different examples verify that the relative order of the symbols doesn't matter.
+            [InlineData("--option-with-error 123 --depends-on-option-with-error")]
+            [InlineData("--depends-on-option-with-error --option-with-error 123")]
+            public void Custom_parser_can_check_another_option_result_for_custom_errors(string commandLine)
+            {
+                var optionWithError = new CliOption<string>("--option-with-error")
+                {
+                    CustomParser = r =>
+                    {
+                        r.AddError("one");
+                        return r.Tokens[0].Value;
+                    }
+                };
+
+                var optionThatDependsOnOptionWithError = new CliOption<bool>("--depends-on-option-with-error")
+                {
+                    CustomParser = result =>
+                    {
+                        if (result.FindResultFor(optionWithError) is { } optionWithErrorResult)
+                        {
+                            var otherOptionError = optionWithErrorResult.Errors.SingleOrDefault()?.Message;
+
+                            result.AddError(otherOptionError + " " + "two");
+                        }
+
+                        return false;
+                    }
+                };
+
+                var command = new CliCommand("cmd")
+                {
+                    optionWithError,
+                    optionThatDependsOnOptionWithError
+                };
+
+                var parseResult = command.Parse(commandLine);
+
+                parseResult.Errors
+                           .Single(e => e.SymbolResult is OptionResult optResult &&
+                                        optResult.Option == optionThatDependsOnOptionWithError)
+                           .Message
+                           .Should()
+                           .Be("one two");
+            }
+
             [Fact]
             public void When_custom_conversion_fails_then_an_option_does_not_accept_further_arguments()
             {

src/System.CommandLine/Parsing/ArgumentResult.cs

@@ -123,7 +123,7 @@ public void OnlyTake(int numberOfTokens)
         /// <inheritdoc/>
         public override void AddError(string errorMessage)
         {
-            SymbolResultTree.AddError(new ParseError(errorMessage, Parent is OptionResult option ? option : this));
+            SymbolResultTree.AddError(new ParseError(errorMessage, AppliesToPublicSymbolResult));
             _conversionResult = ArgumentConversionResult.Failure(this, errorMessage, ArgumentConversionResultType.Failed);
         }
 
@@ -188,17 +188,29 @@ private ArgumentConversionResult ValidateAndConvert(bool useValidators)
                 return ArgumentConversionResult.Success(this, value);
             }
 
-            return ReportErrorIfNeeded(ArgumentConversionResult.ArgumentConversionCannotParse(this, Argument.ValueType, Tokens[0].Value));
+            return ReportErrorIfNeeded(
+                ArgumentConversionResult.ArgumentConversionCannotParse(
+                    this,
+                    Argument.ValueType,
+                    Tokens.Count > 0 
+                        ? Tokens[0].Value
+                        : ""));
 
             ArgumentConversionResult ReportErrorIfNeeded(ArgumentConversionResult result)
             {
                 if (result.Result >= ArgumentConversionResultType.Failed)
                 {
-                    SymbolResultTree.AddError(new ParseError(result.ErrorMessage!, Parent is OptionResult option ? option : this));
+                    SymbolResultTree.AddError(new ParseError(result.ErrorMessage!, AppliesToPublicSymbolResult));
                 }
 
                 return result;
             }
         }
+
+        /// <summary>
+        /// Since Option.Argument is an internal implementation detail, this ArgumentResult applies to the OptionResult in public API if the parent is an OptionResult.
+        /// </summary>
+        private SymbolResult AppliesToPublicSymbolResult => 
+            Parent is OptionResult optionResult ? optionResult : this;
     }
 }

src/System.CommandLine/Parsing/SymbolResult.cs

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System.Collections.Generic;
-using System.CommandLine.Binding;
+using System.Linq;
 
 namespace System.CommandLine.Parsing
 {
@@ -20,6 +20,31 @@ private protected SymbolResult(SymbolResultTree symbolResultTree, SymbolResult?
             Parent = parent;
         }
 
+        /// <summary>
+        /// The parse errors associated with this symbol result.
+        /// </summary>
+        public IEnumerable<ParseError> Errors
+        {
+            get
+            {
+                var parseErrors = SymbolResultTree.Errors;
+
+                if (parseErrors is null)
+                {
+                    yield break;
+                }
+
+                for (var i = 0; i < parseErrors.Count; i++)
+                {
+                    var parseError = parseErrors[i];
+                    if (parseError.SymbolResult == this)
+                    {
+                        yield return parseError;
+                    }
+                }
+            }
+        }
+
         /// <summary>
         /// The parent symbol result in the parse tree.
         /// </summary>