feature/dom export flat

.vscode/launch.json

@@ -196,10 +196,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "search",
-        "microsoft"
-      ],
+      "args": ["search", "microsoft"],
       "cwd": "${workspaceFolder}/src/kiota",
       "console": "internalConsole",
       "stopAtEntry": false
@@ -210,10 +207,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "search",
-        "test"
-      ],
+      "args": ["search", "test"],
       "cwd": "${workspaceFolder}/src/kiota",
       "console": "internalConsole",
       "stopAtEntry": false
@@ -255,11 +249,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "info",
-        "-l",
-        "CSharp"
-      ],
+      "args": ["info", "-l", "CSharp"],
       "cwd": "${workspaceFolder}/src/kiota",
       "console": "internalConsole",
       "stopAtEntry": false
@@ -270,11 +260,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "update",
-        "-o",
-        "${workspaceFolder}/samples"
-      ],
+      "args": ["update", "-o", "${workspaceFolder}/samples"],
       "cwd": "${workspaceFolder}/src/kiota",
       "console": "internalConsole",
       "stopAtEntry": false
@@ -285,10 +271,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "workspace",
-        "migrate"
-      ],
+      "args": ["workspace", "migrate"],
       "cwd": "${workspaceFolder}/samples/msgraph-mail/dotnet",
       "console": "internalConsole",
       "stopAtEntry": false,
@@ -302,10 +285,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "client",
-        "generate"
-      ],
+      "args": ["client", "generate"],
       "cwd": "${workspaceFolder}/samples/msgraph-mail/dotnet",
       "console": "internalConsole",
       "stopAtEntry": false,
@@ -369,11 +349,7 @@
       "request": "launch",
       "preLaunchTask": "build",
       "program": "${workspaceFolder}/src/kiota/bin/Debug/net8.0/kiota.dll",
-      "args": [
-        "login",
-        "github",
-        "device"
-      ],
+      "args": ["login", "github", "device"],
       "cwd": "${workspaceFolder}/src/kiota",
       "console": "internalConsole",
       "stopAtEntry": false
@@ -385,4 +361,4 @@
       "processId": "${command:pickProcess}"
     }
   ]
-}
+}

.vscode/tasks.json

@@ -22,7 +22,17 @@
         "/property:GenerateFullPaths=true",
         "/consoleloggerparameters:NoSummary"
       ],
-      "problemMatcher": "$msCompile"
+      "problemMatcher": "$msCompile",
+      "dependsOn": ["checkout:sample:locks"]
+    },
+    {
+      "label": "checkout:sample:locks",
+      "type": "process",
+      "command": "git",
+      "args": ["checkout", "**/kiota-lock.json"],
+      "options": {
+        "cwd": "${workspaceFolder}/samples"
+      }
     },
     {
       "label": "test",

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added the ability to export the CodeDom to a file showing the public APIs to be generated in a given language [#4627](https://github.com/microsoft/kiota/issues/4627)
+
 ### Changed
 
 - Fixed shorthand for refresh option in workspace experience. [#5240](https://github.com/microsoft/kiota/issues/5240)

src/Kiota.Builder/CodeDOM/CodeMethod.cs

@@ -85,7 +85,7 @@ public object Clone()
     }
 }
 
-public class CodeMethod : CodeTerminalWithKind<CodeMethodKind>, ICloneable, IDocumentedElement, IDeprecableElement
+public class CodeMethod : CodeTerminalWithKind<CodeMethodKind>, ICloneable, IDocumentedElement, IDeprecableElement, IAccessibleElement
 {
     public static readonly CodeParameterKind ParameterKindForConvertedIndexers = CodeParameterKind.Custom;
     public static CodeMethod FromIndexer(CodeIndexer originalIndexer, Func<string, string> methodNameCallback, Func<string, string> parameterNameCallback, bool parameterNullable, bool typeSpecificOverload = false)

src/Kiota.Builder/CodeDOM/CodeProperty.cs

@@ -40,7 +40,7 @@ public enum CodePropertyKind
     ErrorMessageOverride
 }
 
-public class CodeProperty : CodeTerminalWithKind<CodePropertyKind>, IDocumentedElement, IAlternativeName, ICloneable, IDeprecableElement
+public class CodeProperty : CodeTerminalWithKind<CodePropertyKind>, IDocumentedElement, IAlternativeName, ICloneable, IDeprecableElement, IAccessibleElement
 {
     public bool ReadOnly
     {

src/Kiota.Builder/CodeDOM/CodeType.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.Collections.ObjectModel;
 using System.Linq;
 
@@ -33,10 +34,22 @@
             TypeDefinition = TypeDefinition, // not cloning the type definition as it's a code element that lives in the tree and we don't want to fork the tree
             IsExternal = IsExternal,
             // Clone the list so that modifications on cloned objects' property are localized
             // e.g. var y = x.Clone(); var z = y.Clone(); y.GenericTypeParameterValues.Add(value);
             // shouldn't modify x.GenericTypeParameterValues or z.GenericTypeParameterValues
-            GenericTypeParameterValues = new(GenericTypeParameterValues.ToList()),
+            genericTypeParameterValues = [.. genericTypeParameterValues],
         }.BaseClone<CodeType>(this, TypeDefinition is null || IsExternal);
     }
-    public Collection<CodeType> GenericTypeParameterValues { get; init; } = new();
+    public IEnumerable<CodeType> GenericTypeParameterValues
+    {
+        get => genericTypeParameterValues;
+        init => AddGenericTypeParameterValue([.. value]);
+    }
+    private Collection<CodeType> genericTypeParameterValues = [];
+    public void AddGenericTypeParameterValue(params CodeType[] types)
+    {
+        if (types is null) return;
+        EnsureElementsAreChildren(types);
+        foreach (var type in types)
+            genericTypeParameterValues.Add(type);
+    }
 }

src/Kiota.Builder/CodeDOM/IAccessibleElement.cs

@@ -0,0 +1,12 @@
+namespace Kiota.Builder.CodeDOM;
+
+/// <summary>
+/// Defines a contract for elements that can have configurable access to them using <see cref="AccessModifier"/> 
+/// </summary>
+public interface IAccessibleElement
+{
+    AccessModifier Access
+    {
+        get; set;
+    }
+}

src/Kiota.Builder/Configuration/GenerationConfiguration.cs

@@ -39,6 +39,10 @@ public ConsumerOperation? Operation
     public string ClientClassName { get; set; } = "ApiClient";
     public string ClientNamespaceName { get; set; } = "ApiSdk";
     public string NamespaceNameSeparator { get; set; } = ".";
+    public bool ExportPublicApi
+    {
+        get; set;
+    }
     internal const string ModelsNamespaceSegmentName = "models";
     public string ModelsNamespaceName
     {
@@ -152,6 +156,7 @@ public object Clone()
             PatternsOverride = new(PatternsOverride ?? Enumerable.Empty<string>(), StringComparer.OrdinalIgnoreCase),
             PluginTypes = new(PluginTypes ?? Enumerable.Empty<PluginType>()),
             DisableSSLValidation = DisableSSLValidation,
+            ExportPublicApi = ExportPublicApi,
         };
     }
     private static readonly StringIEnumerableDeepComparer comparer = new();

src/Kiota.Builder/Export/PublicAPIExportService.cs

@@ -0,0 +1,130 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Kiota.Builder.CodeDOM;
+using Kiota.Builder.Configuration;
+using Kiota.Builder.Writers;
+using Kiota.Builder.Writers.CSharp;
+using Kiota.Builder.Writers.Go;
+using Kiota.Builder.Writers.Java;
+using Kiota.Builder.Writers.Php;
+using Kiota.Builder.Writers.Python;
+using Kiota.Builder.Writers.Ruby;
+using Kiota.Builder.Writers.Swift;
+using Kiota.Builder.Writers.TypeScript;
+
+namespace Kiota.Builder.Export;
+
+internal class PublicApiExportService
+{
+    internal PublicApiExportService(GenerationConfiguration generationConfiguration)
+    {
+        ArgumentNullException.ThrowIfNull(generationConfiguration);
+        _conventionService = GetLanguageConventionServiceFromConfiguration(generationConfiguration);
+    }
+    private readonly ILanguageConventionService _conventionService;
+    internal const string DomExportFileName = "kiota-dom-export.txt";
+    private const string InheritsSymbol = "-->";
+    private const string ImplementsSymbol = "~~>";
+    private const string OptionalSymbol = "?";
+    private const string ParentElementAndChildSeparator = "::";
+
+    internal async Task SerializeDomAsync(Stream outputStream, CodeNamespace rootNamespace, CancellationToken cancellationToken = default)
+    {
+        var streamWriter = new StreamWriter(outputStream, leaveOpen: true);
+        await using (streamWriter.ConfigureAwait(false))
+        {
+            var entries = GetEntriesFromDom(rootNamespace).Order(StringComparer.OrdinalIgnoreCase).ToArray();
+            foreach (var entry in entries)
+            {
+                await streamWriter.WriteLineAsync(entry.AsMemory(), cancellationToken).ConfigureAwait(false);
+            }
+            await streamWriter.FlushAsync(cancellationToken).ConfigureAwait(false);
+        }
+    }
+    private IEnumerable<string> GetEntriesFromDom(CodeElement currentElement)
+    {
+        foreach (var currentElementEntry in GetEntry(currentElement).Where(static x => !string.IsNullOrEmpty(x)))
+            yield return currentElementEntry;
+        foreach (var childElement in currentElement.GetChildElements())
+            foreach (var childElementEntry in GetEntriesFromDom(childElement))
+                yield return childElementEntry;
+    }
+
+    private IEnumerable<string> GetEntry(CodeElement codeElement, bool includeDefinitions = false)
+    {
+        string accessModifierValue = string.Empty;
+        if (codeElement is IAccessibleElement accessibleElement)
+        {
+            if (accessibleElement.Access is AccessModifier.Private)
+                return []; // we are not interested in private props as they are not used externally
+
+            accessModifierValue = $"|{accessibleElement.Access.ToString().ToLowerInvariant()}|";
+        }
+
+        return codeElement switch
+        {
+            CodeProperty property when property.Parent is not null =>
+                [$"{GetEntryPath(property.Parent)}{ParentElementAndChildSeparator}{accessModifierValue}{property.Name}:{GetEntryType(property.Type, property)}"],
+            CodeMethod method when method.Parent is not null =>
+                [$"{GetEntryPath(method.Parent)}{ParentElementAndChildSeparator}{(method.IsStatic ? "|static" : string.Empty)}{accessModifierValue}{method.Name}({GetParameters(method.Parameters)}):{((GetEntryType(method.ReturnType, method) is { } stringValue && !string.IsNullOrEmpty(stringValue)) ? stringValue : method.ReturnType.Name)}"],
+            CodeFunction function when function.Parent is not null =>
+                [$"{GetEntryPath(function.Parent)}{ParentElementAndChildSeparator}{function.Name}({GetParameters(function.OriginalLocalMethod.Parameters)}):{GetEntryType(function.OriginalLocalMethod.ReturnType, function)}"],
+            CodeIndexer codeIndexer when codeIndexer.Parent is not null =>
+                [$"{GetEntryPath(codeIndexer.Parent)}{ParentElementAndChildSeparator}[{GetParameters([codeIndexer.IndexParameter])}]:{GetEntryType(codeIndexer.ReturnType, codeIndexer)}"],
+            CodeEnum codeEnum1 when !includeDefinitions =>
+                codeEnum1.Options.Select((x, y) => $"{GetEntryPath(codeEnum1)}::{y:D4}-{x.Name}"),
+            CodeClass codeClass1 when !includeDefinitions && codeClass1.StartBlock.Inherits is not null =>
+                [$"{GetEntryPath(codeClass1)}{InheritsSymbol}{GetEntryType(codeClass1.StartBlock.Inherits, codeClass1)}"],
+            CodeClass codeClass2 when !includeDefinitions && codeClass2.StartBlock.Implements.Any() =>
+                [$"{GetEntryPath(codeClass2)}{ImplementsSymbol}{string.Join("; ", codeClass2.StartBlock.Implements.Select(x => GetEntryType(x, codeClass2)))}"],
+            CodeInterface codeInterface1 when !includeDefinitions && codeInterface1.StartBlock.Implements.Any() =>
+                [$"{GetEntryPath(codeInterface1)}{ImplementsSymbol}{string.Join("; ", codeInterface1.StartBlock.Implements.Select(x => GetEntryType(x, codeInterface1)))}"],
+            CodeClass codeClass when includeDefinitions => [GetEntryPath(codeClass)],
+            CodeEnum codeEnum when includeDefinitions => [GetEntryPath(codeEnum)],
+            CodeInterface codeInterface when includeDefinitions => [GetEntryPath(codeInterface)],
+            CodeConstant codeConstant => [GetEntryPath(codeConstant)],
+            _ => [],
+        };
+    }
+    private string GetParameters(IEnumerable<CodeParameter> parameters)
+    {
+        return string.Join("; ", parameters.Select(x => $"{x.Name}{(x.Optional ? OptionalSymbol : string.Empty)}:{GetEntryType(x.Type, x)}{(string.IsNullOrEmpty(x.DefaultValue) ? string.Empty : $"={x.DefaultValue}")}"));
+    }
+
+    private string GetEntryType(CodeTypeBase codeElementTypeBase, CodeElement targetElement) => _conventionService.GetTypeString(codeElementTypeBase, targetElement)
+        .Replace(ParentElementAndChildSeparator, ".", StringComparison.OrdinalIgnoreCase);//ensure language specific stuff doesn't break things like global:: in dotnet
+
+    private static string GetEntryPath(CodeElement codeElement)
+    {
+        return codeElement switch
+        {
+            CodeClass x when x.Parent is not null => $"{GetEntryPath(x.Parent)}.{codeElement.Name}",
+            CodeEnum x when x.Parent is not null => $"{GetEntryPath(x.Parent)}.{codeElement.Name}",
+            CodeInterface x when x.Parent is not null => $"{GetEntryPath(x.Parent)}.{codeElement.Name}",
+            CodeConstant x when x.Parent is not null => $"{GetEntryPath(x.Parent)}.{codeElement.Name}",
+            CodeFile x when x.Parent is not null => GetEntryPath(x.Parent),
+            CodeNamespace x => x.Name,
+            _ => string.Empty,
+        };
+    }
+    private static ILanguageConventionService GetLanguageConventionServiceFromConfiguration(GenerationConfiguration generationConfiguration)
+    {
+        return generationConfiguration.Language switch
+        {
+            GenerationLanguage.CSharp => new CSharpConventionService(),
+            GenerationLanguage.Java => new JavaConventionService(),
+            GenerationLanguage.TypeScript => new TypeScriptConventionService(),
+            GenerationLanguage.PHP => new PhpConventionService(),
+            GenerationLanguage.Python => new PythonConventionService(),
+            GenerationLanguage.Go => new GoConventionService(),
+            GenerationLanguage.Swift => new SwiftConventionService(generationConfiguration.ClientNamespaceName),
+            GenerationLanguage.Ruby => new RubyConventionService(),
+            GenerationLanguage.CLI => new CSharpConventionService(),
+            _ => throw new ArgumentOutOfRangeException(nameof(generationConfiguration), generationConfiguration.Language, null)
+        };
+    }
+}

src/Kiota.Builder/KiotaBuilder.cs

@@ -19,6 +19,7 @@
 using Kiota.Builder.Configuration;
 using Kiota.Builder.EqualityComparers;
 using Kiota.Builder.Exceptions;
+using Kiota.Builder.Export;
 using Kiota.Builder.Extensions;
 using Kiota.Builder.Logging;
 using Kiota.Builder.Manifest;
@@ -268,6 +269,18 @@
             await ApplyLanguageRefinement(config, generatedCode, cancellationToken).ConfigureAwait(false);
             StopLogAndReset(sw, $"step {++stepId} - refine by language - took");
 
+            if (config.ExportPublicApi)
+            {
+                // Generate public API export
+                sw.Start();
+                var fileStream = File.Create(Path.Combine(config.OutputPath, PublicApiExportService.DomExportFileName));
+                await using (fileStream.ConfigureAwait(false))
+                {
+                    await new PublicApiExportService(config).SerializeDomAsync(fileStream, generatedCode, cancellationToken).ConfigureAwait(false);
+                }
+                StopLogAndReset(sw, $"step {++stepId} - generated public API export - took");
+            }
+
             // Write language source
             sw.Start();
             await CreateLanguageSourceFilesAsync(config.Language, generatedCode, cancellationToken).ConfigureAwait(false);
@@ -695,7 +708,7 @@
         methodToAdd.AddParameter(new CodeParameter
         {
             Name = "rawUrl",
             Type = new CodeType { Name = "string", IsExternal = true },
             Optional = false,
             Documentation = new()
             {
@@ -809,7 +822,7 @@
             IsAsync = false,
             IsStatic = false,
             Documentation = new(new() {
                                 {"TypeName", new CodeType {
                                     IsExternal = false,
                                     TypeDefinition = currentClass,
                                 }
@@ -1051,7 +1064,7 @@
 
         if (!"string".Equals(parameter.Type.Name, StringComparison.OrdinalIgnoreCase) && config.IncludeBackwardCompatible)
         { // adding a second indexer for the string version of the parameter so we keep backward compatibility
             //TODO remove for v2
             var backCompatibleValue = (CodeIndexer)result[0].Clone();
             backCompatibleValue.Name += "-string";
             backCompatibleValue.IndexParameter.Type = DefaultIndexerParameterType;
@@ -1207,7 +1220,7 @@
             var suffix = $"{operationType}Response";
             var modelType = CreateModelDeclarations(currentNode, schema, operation, parentClass, suffix);
             if (modelType is not null && config.IncludeBackwardCompatible && config.Language is GenerationLanguage.CSharp or GenerationLanguage.Go && modelType.Name.EndsWith(suffix, StringComparison.Ordinal))
             { //TODO remove for v2
                 var obsoleteTypeName = modelType.Name[..^suffix.Length] + "Response";
                 if (modelType is CodeType codeType &&
                     codeType.TypeDefinition is CodeClass codeClass)
@@ -1339,7 +1352,7 @@
             executorMethod.AddParameter(cancellationParam);// Add cancellation token parameter
 
             if (returnTypes.Item2 is not null && config.IncludeBackwardCompatible)
             { //TODO remove for v2
                 var additionalExecutorMethod = (CodeMethod)executorMethod.Clone();
                 additionalExecutorMethod.ReturnType = returnTypes.Item2;
                 additionalExecutorMethod.OriginalMethod = executorMethod;
@@ -2407,7 +2420,7 @@
         if (!parameterClass.ContainsPropertyWithWireName(prop.WireName))
         {
             if (addBackwardCompatibleParameter && config.IncludeBackwardCompatible && config.Language is GenerationLanguage.CSharp or GenerationLanguage.Go)
             { //TODO remove for v2
                 var modernProp = (CodeProperty)prop.Clone();
                 modernProp.Name = $"{prop.Name}As{modernProp.Type.Name.ToFirstCharacterUpperCase()}";
                 modernProp.SerializationName = prop.WireName;

src/Kiota.Builder/Refiners/CliRefiner.cs

@@ -109,7 +109,7 @@
     }
     private static void RemoveBackwardCompatibleIndexers(CodeElement currentElement)
     {
         //TODO remove for v2
         if (currentElement is CodeClass
             {
                 Kind: CodeClassKind.RequestBuilder, Indexer: not null
@@ -327,10 +327,10 @@
             {
                 Name = "Tuple",
                 IsExternal = true,
-                GenericTypeParameterValues = new() {
+                GenericTypeParameterValues = [
                     CreateCommandType(collectionKind),
                     CreateCommandType(collectionKind),
-                }
+                ]
             },
             SimpleName = indexer.Name.CleanupSymbolName()
         };

src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs

@@ -623,9 +623,9 @@
         if (currentElement is CodeIndexer currentIndexer &&
             currentElement.Parent is CodeClass indexerParentClass)
         {
             if (indexerParentClass.ContainsMember(currentElement.Name)) // TODO remove condition for v2 necessary because of the second case of Go block
                 indexerParentClass.RemoveChildElement(currentElement);
             //TODO remove whole block except for last else if body for v2
             if (language == GenerationLanguage.Go)
             {
                 if (currentIndexer.IsLegacyIndexer)
@@ -1411,7 +1411,7 @@
                 };
                 if (addCurrentTypeAsGenericTypeParameter)
                 {
-                    currentClass.StartBlock.Inherits.GenericTypeParameterValues.Add(new CodeType
+                    currentClass.StartBlock.Inherits.AddGenericTypeParameterValue(new CodeType
                     {
                         TypeDefinition = currentClass,
                     });
@@ -1502,7 +1502,7 @@
     private static CodeType GetGenericTypeForRequestConfiguration(CodeType configurationParameterType, CodeType genericTypeParamValue)
     {
         var newType = (CodeType)configurationParameterType.Clone();
-        newType.GenericTypeParameterValues.Add(genericTypeParamValue);
+        newType.AddGenericTypeParameterValue(genericTypeParamValue);
         return newType;
     }