Added Nullability support (#25)

Author: smaillet

Invoke-Tests.ps1

@@ -38,7 +38,6 @@ try
     Push-Location $BuildInfo['SrcRootPath']
     try
     {
-        dir (Join-Path $BuildInfo['BuildOutputPath'] 'bin' 'Ubiquity.NET.CommandLine.SrcGen.UT' "$Configuration" 'net10.0' 'Ubiquity.NET.CommandLine.*')
         Invoke-External dotnet test Ubiquity.NET.Utils.slnx '-c' $Configuration '-tl:off' '--logger:trx' '--no-build' '-s' '.\.runsettings'
     }
     finally

src/DemoCommandLineSrcGen/Program.cs

@@ -31,6 +31,11 @@ public static async Task<int> Main( string[] args )
                                     .ParseAndInvokeResultAsync( reporter, cts.Token, args );
         }
 
+        /// <summary>Asynchronous main entry point</summary>
+        /// <param name="options">Parsed command line options</param>
+        /// <param name="reporter">Reporter to use for reporting diagnostics for this app</param>
+        /// <param name="ct">Cancellation token to indicate cancellation of the entire app</param>
+        /// <returns>Exit code for the app; 0=NOERROR; any other value MAY indicate an error (App defined)</returns>
         private static async Task<int> AppMainAsync(
                 TestOptions options,
                 ColoredConsoleReporter reporter,
@@ -43,13 +48,17 @@ CancellationToken ct
                 reporter = new ColoredConsoleReporter( options.Verbosity );
             }
 
-            reporter.Verbose( "AppMainAsync" );
-
-            // Core application code here...
-
             // Use the cancellation token to indicate cancellation
             // This is set when CTRL-C is pressed in Main() above.
             ct.ThrowIfCancellationRequested();
+
+            // For demo, Report the full parsed args to the "Verbose" channel
+            // in a normal app this isn't done or would use some sort of logging
+            // and not a UX reporter, but it is useful for validation scripts
+            reporter.Verbose( $"TestOptions:\n{options}" );
+
+            // Core application code here...
+            // app should use/test ct for cancellation of long operations.
             return 0;
         }
     }

src/DemoCommandLineSrcGen/ReadMe.md

@@ -0,0 +1,41 @@
+# Demo/Test command line source generator
+This project demonstrates use of the command line source generator AND also tests the final
+NuGet Packaging. It lists the command line library package. This package should also bring
+in the analyzer and generator.
+
+>[!IMPORTANT]
+> To test/leverage the final package it MUST be built already AND can only reference the
+> dependent packages that also exist. (Including the correct versions). This is normally not
+> plausible from an IDE build. The version number for such builds is based on the timestamp
+> of the build and is determined for each project independently. However, the command line
+> will build ALL of the projects with the same version number.
+> `Build-Source.ps1 -FullInit -ForceClean` will ensure the same version is built into all of
+> the packages. It will then build this project. This breaks the dependency cycles and
+> eliminates the problem of expressing the dependency on a set of generated packages but NOT
+> the projects that create them. (Sadly, this turns out to be a more complex problem than
+> one would think)
+
+To support the dependency and testing this is NOT part of the same solution as the other
+components. Within this repository, it does depend on those being built first.
+
+## Purpose
+Aside from serving as a general demo for use in documentation etc... this project serves to
+validate the proper packaging of the generator with the library it is generating source for.
+The formal tests will validate the behavior of the generator/analyzer itself but don't use
+NuGet packaging (They use project references). The meta package that includes a reference to
+both the library and the generator is built independent of those assemblies. This is done to
+break the dependency problem where the meta package references but does not need them to
+build. Thus, this package validates the NuGet Packaging is functioning as intended. It will
+fail to build if there is a problem. So it is built after all the other projects as part of
+the `Build-Source.ps1` script. As long as it builds without error it worked for what is
+tested. (The formal tests validate the behavior more directly)
+
+## Differences from Real world use
+The only thing that is different from this demo and real world use is the `VersionOverride`
+attribute on the `PackageReference` for `Ubiquity.NET.CommandLine`. This is simply present
+for the use in this repo as the [Nuget.Config](../../NuGet.Config) uses source mapping to
+constrain resolving packages generated by this rep to this repo. This constrains NuGet to
+resolve these dependencies to what was built in this repository only. This ensures that what
+is consumed and tested is what is built. This is a necessity of building or testing this
+repository. This specific demo project, only has the `VersionOverride` to fit into the repo
+build and verify the package built before accepting/releasing it.

src/DemoCommandLineSrcGen/TestOptions.cs

@@ -11,6 +11,10 @@
 
 namespace TestNamespace
 {
+    // It is important to understand how "required" is handled in the underlying command line handler
+    // in System.CommandLine. The semantics are:
+    //     When the command is invoked, the value may not be null.
+    // That is, it is NOT evaluated during parse, ONLY during invocation.
     [RootCommand( Description = "Root command for tests" )]
     internal partial class TestOptions
     {
@@ -25,14 +29,26 @@ internal partial class TestOptions
         [FolderValidation( FolderValidation.ExistingOnly )]
         public required DirectoryInfo SomeExistingPath { get; init; }
 
-        [Option( "--thing1", Aliases = [ "-t" ], Required = true, Description = "Test Thing1", HelpName = "Help name for thing1" )]
-        public bool Thing1 { get; init; }
+        [Option( "--thing1", Aliases = [ "-t" ], Description = "Test Thing1", HelpName = "Help name for thing1" )]
+        public bool? Thing1 { get; init; }
 
         // This should be ignored by generator
         public string? NotAnOption { get; set; }
 
         [Option( "-a", Hidden = true, Required = false, ArityMin = 0, ArityMax = 3, Description = "Test SomeOtherPath" )]
         [FileValidation( FileValidation.ExistingOnly )]
         public required FileInfo SomeOtherPath { get; init; }
+
+        public override string ToString( )
+        {
+            return $"""
+                SomePath = '{SomePath?.FullName ?? "<null>"}'
+                Verbosity = {Verbosity}
+                SomeExistingPath = '{SomeExistingPath?.FullName ?? "<null>"}'
+                Thing1 = {Thing1}
+                NotAnOption = {NotAnOption ?? "<null>"}
+                SomeOtherPath = '{SomeOtherPath?.FullName ?? "<null>"}'
+            """;
+        }
     }
 }

src/Ubiquity.NET.CodeAnalysis.Utils/AttributeDataExtensions.cs

@@ -18,14 +18,12 @@ public static bool IsFullNameMatch( this AttributeData self, NamespaceQualifiedN
                                       .SequenceEqual( fullName.NamespaceNames );
         }
 
-        /// <summary>Gets the <see cref="NamespaceQualifiedName"/> for the attribute</summary>
+        /// <summary>Gets the <see cref="NamespaceQualifiedTypeName"/> for the attribute</summary>
         /// <param name="self">self</param>
-        /// <returns><see cref="NamespaceQualifiedName"/> for the attribute</returns>
-        public static NamespaceQualifiedName GetNamespaceQualifiedName( this AttributeData self )
+        /// <returns><see cref="NamespaceQualifiedTypeName"/> for the attribute</returns>
+        public static NamespaceQualifiedTypeName GetNamespaceQualifiedName( this AttributeData self )
         {
-            return self.AttributeClass is null
-                 ? new( [], string.Empty )
-                 : self.AttributeClass.GetNamespaceQualifiedName();
+            return self.AttributeClass?.GetNamespaceQualifiedName() ?? new();
         }
 
         /// <summary>Gets the location from the <see cref="AttributeData.ApplicationSyntaxReference"/> if available</summary>

src/Ubiquity.NET.CodeAnalysis.Utils/EquatableAttributeData.cs

@@ -33,8 +33,8 @@ public EquatableAttributeData( AttributeData data )
             NamedArguments = namedArgs.ToImmutableDictionary();
         }
 
-        /// <summary>Gets the full namespace qualified name for this attribute</summary>
-        public NamespaceQualifiedName Name { get; }
+        /// <summary>Gets the full namespace qualified name for the type of this attribute</summary>
+        public NamespaceQualifiedTypeName Name { get; }
 
         /// <summary>Gets the unnamed constructor arguments for this attribute</summary>
         public ImmutableArray<StructurallyEquatableTypedConstant> ConstructorArguments { get; }

src/Ubiquity.NET.CodeAnalysis.Utils/NamespaceQualifiedName.cs

@@ -19,17 +19,23 @@ public class NamespaceQualifiedName
         , IEquatable<Type>
         , IFormattable
     {
+        /// <summary>Initializes a new instance of the <see cref="NamespaceQualifiedName"/> class.</summary>
+        public NamespaceQualifiedName()
+        {
+            NamespaceNames = [];
+            SimpleName = string.Empty;
+        }
+
         /// <summary>Initializes a new instance of the <see cref="NamespaceQualifiedName"/> class.</summary>
         /// <param name="namespaceNames">sequence of namespace names (outermost to innermost)</param>
         /// <param name="simpleName">Unqualified name of the symbol</param>
-        public NamespaceQualifiedName(IEnumerable<string> namespaceNames, string simpleName )
+        public NamespaceQualifiedName( IEnumerable<string> namespaceNames, string simpleName )
         {
             PolyFillExceptionValidators.ThrowIfNull(namespaceNames);
             PolyFillExceptionValidators.ThrowIfNullOrWhiteSpace(simpleName);
 
             SimpleName = simpleName;
             NamespaceNames = [ .. namespaceNames.Select( s => ValidateNamespacePart(s) ) ];
-
             static string ValidateNamespacePart( string s, [CallerArgumentExpression(nameof(s))] string? exp = null )
             {
                 PolyFillExceptionValidators.ThrowIfNullOrWhiteSpace( s, exp );
@@ -69,6 +75,8 @@ public IEnumerable<string> FullNameParts
             }
         }
 
+        #region Equality
+
         /// <inheritdoc/>
         public bool Equals( NamespaceQualifiedName other )
         {
@@ -124,6 +132,7 @@ public bool Equals( Type other )
         {
             return ToString() == other.FullName;
         }
+        #endregion
 
         /// <summary>Gets the string representation of the full namespace using '.' as the delimiter</summary>
         /// <returns>Full namespace qualified name as a string (with a global prefix or an alias if available)</returns>
@@ -155,7 +164,7 @@ public override string ToString( )
         /// </remarks>
         /// <exception cref="NotSupportedException"><paramref name="format"/> is not supported</exception>
         [SuppressMessage( "Style", "IDE0046:Convert to conditional expression", Justification = "Result is anything but simpler" )]
-        public string ToString( string format, IFormatProvider? formatProvider )
+        public virtual string ToString( string format, IFormatProvider? formatProvider )
         {
             // default to the C# formatter unless specified.
             formatProvider ??= NamespaceQualifiedNameFormatter.CSharp;

src/Ubiquity.NET.CodeAnalysis.Utils/NamespaceQualifiedNameFormatter.cs

@@ -3,18 +3,19 @@
 
 namespace Ubiquity.NET.CodeAnalysis.Utils
 {
-    /// <summary>Custom formatter for <see cref="NamespaceQualifiedName"/></summary>
+    /// <summary>Custom formatter for <see cref="NamespaceQualifiedName"/> and <see cref="NamespaceQualifiedTypeName"/></summary>
     public class NamespaceQualifiedNameFormatter
         : IFormatProvider
         , ICustomFormatter<NamespaceQualifiedName>
+        , ICustomFormatter<NamespaceQualifiedTypeName>
     {
         /// <summary>Initializes a new instance of the <see cref="NamespaceQualifiedNameFormatter"/> class.</summary>
         /// <param name="globalPrefix">Global prefix for the language this formatter will produce</param>
         /// <param name="aliasMap">Map of aliases for the language (Key is the full namespace name of a type, the values are the alias)</param>
         public NamespaceQualifiedNameFormatter( string globalPrefix, IReadOnlyDictionary<string, string> aliasMap )
         {
             GlobalPrefix = globalPrefix ?? string.Empty;
-            AliasMap = aliasMap ?? throw new ArgumentNullException(nameof(aliasMap));
+            AliasMap = aliasMap ?? throw new ArgumentNullException( nameof( aliasMap ) );
         }
 
         /// <summary>Gets the global prefix for the language formatting (example: "global::")</summary>
@@ -30,12 +31,24 @@ public NamespaceQualifiedNameFormatter( string globalPrefix, IReadOnlyDictionary
         /// <inheritdoc/>
         public string Format( string format, object arg, IFormatProvider? formatProvider )
         {
-            return arg is not NamespaceQualifiedName self
-                 ? string.Empty
-                 : Format(format, self, formatProvider);
+            if(arg is NamespaceQualifiedName name)
+            {
+                return Format( format, name, formatProvider );
+            }
+
+            if(arg is NamespaceQualifiedTypeName typeName)
+            {
+                return Format( format, typeName, formatProvider );
+            }
+
+            // Not a type supported; use the type to do it, if it's formattable itself use that
+            // otherwise fall back to simple Object.ToString().
+            return arg is IFormattable formattable
+                 ? formattable.ToString( format, formatProvider )
+                 : arg.ToString();
         }
 
-        /// <summary>Formats this instance according to the args</summary>
+        /// <summary>Formats <paramref name="arg"/> according to <paramref name="format"/></summary>
         /// <param name="format">Format string for this instance (see remarks)</param>
         /// <param name="arg">The value to format</param>
         /// <param name="formatProvider">[ignored]</param>
@@ -76,10 +89,39 @@ public string Format( string format, NamespaceQualifiedName arg, IFormatProvider
                  : rawName;
         }
 
+        /// <summary>Formats <paramref name="arg"/> according to <paramref name="format"/></summary>
+        /// <param name="format">Format string for this instance (see remarks)</param>
+        /// <param name="arg">The value to format</param>
+        /// <param name="formatProvider">[ignored]</param>
+        /// <returns>Formatted string representation of this instance</returns>
+        /// <remarks>
+        /// The supported values for <paramref name="format"/> are:
+        /// <list type="table">
+        /// <listheader><term>Value</term><description>Description</description></listheader>
+        /// <item><term>A</term><description>Format as a language specific alias if possible</description></item>
+        /// <item><term>G</term><description>Format with a language specific global prefix.</description></item>
+        /// <item><term>AG</term><description>Format with a language specific alias if possible, otherwise include a global prefix.</description></item>
+        /// <item><term>R</term><description>The raw full name without any qualifications</description></item>
+        /// </list>
+        /// <note type="important">
+        /// This will always append a <c>?</c> to the end of the formatted value IF the <see cref="NamespaceQualifiedTypeName.NullableAnnotation"/>
+        /// indicates the value is nullable.
+        /// </note>
+        /// </remarks>
+        /// <exception cref="NotSupportedException"><paramref name="format"/> is not supported</exception>
+        public string Format( string format, NamespaceQualifiedTypeName arg, IFormatProvider? formatProvider )
+        {
+            string formattedString = Format(format, (NamespaceQualifiedName)arg, formatProvider);
+            return arg.NullableAnnotation == NullableAnnotation.Annotated
+                 ? $"{formattedString}?"
+                 : formattedString;
+        }
+
         /// <inheritdoc/>
         public object? GetFormat( Type formatType )
         {
             return formatType == typeof( ICustomFormatter<NamespaceQualifiedName> )
+                || formatType == typeof( ICustomFormatter<NamespaceQualifiedTypeName> )
                   ? this
                   : null;
         }