generation-info.ts

export type Namespace = string;

import { FernIr as DynamicFernIr } from "@fern-api/dynamic-ir-sdk";
import { FernIr } from "@fern-fern/ir-sdk";

type IntermediateRepresentation = FernIr.IntermediateRepresentation;
type TypeId = FernIr.TypeId;
type FernFilepath = FernIr.FernFilepath;

/**
 * Browser-compatible path join for C# project paths.
 * Joins path segments with "/" separator, filtering empty segments.
 */
function join(...segments: string[]): string {
    return segments.filter(Boolean).join("/");
}

import * as ast from "../ast/index.js";
import { ClassReference } from "../ast/types/ClassReference.js";
import { Type } from "../ast/types/IType.js";
import { Collection, Primitive, Value } from "../ast/types/Type.js";
import { CSharp } from "../csharp.js";
import { type CsharpConfigSchema } from "../custom-config/index.js";
import { is, text } from "../index.js";
import { lazy } from "../utils/lazy.js";
import { camelCase, upperFirst } from "../utils/text.js";

import { MinimalGeneratorConfig, Support, TAbsoluteFilePath, TRelativeFilePath } from "./common.js";
import { Extern } from "./extern.js";
import { ModelNavigator } from "./model-navigator.js";
import { NameRegistry } from "./name-registry.js";

/**
 * Central configuration and code generation context for C# SDK generation.
 *
 * This class serves as the single source of truth for all code generation decisions,
 * consolidating names, namespaces, types, and settings into a unified graph. It eliminates
 * duplication between dynamic and regular generators by providing consistent access to
 * generation metadata.
 *
 * ## Key Responsibilities:
 * - Manages namespace organization for generated C# code
 * - Provides standardized naming conventions for classes, types, and identifiers
 * - Lazily initializes and caches type references and configuration values
 * - Serves as a navigation hub for the IR (Intermediate Representation) model
 * - Coordinates between code generation utilities (CSharp, NameRegistry, etc.)
 *
 * ## Lazy Initialization:
 * All returned values use lazy initialization for performance:
 * - Parameterless functions: Evaluated once and cached on first access
 * - Parameterized functions: Remain as functions, evaluated on each call
 *
 * ## Usage Pattern:
 * ```typescript
 * const generation = new Generation(ir, apiName, config, generatorConfig);
 * const namespace = generation.namespaces.root; // Lazy-evaluated and cached
 * const pager = generation.types.Pager(itemType); // Function, evaluated each call
 * ```
 *
 * This object is safe to pass throughout the code generation pipeline and should be
 * the primary source for all naming and type reference decisions.
 */
export class Generation {
    /**
     * Creates a new Generation context for C# code generation.
     *
     * @param intermediateRepresentation - The Fern IR containing the API definition,
     *                                     supports both static and dynamic IR formats
     * @param apiName - The name of the API being generated (used for namespace/class naming)
     * @param customConfig - User-provided custom configuration overrides for the generator
     * @param generatorConfig - Core generator configuration including organization and workspace info
     */
    constructor(
        public readonly intermediateRepresentation:
            | IntermediateRepresentation
            | DynamicFernIr.dynamic.DynamicIntermediateRepresentation,
        private readonly apiName: string,
        private readonly customConfig: CsharpConfigSchema,
        private readonly generatorConfig: MinimalGeneratorConfig,
        private readonly support: Support = {
            makeRelativeFilePath: (path) => path as TRelativeFilePath,
            makeAbsoluteFilePath: (path: string) => path as TAbsoluteFilePath,
            getNamespaceForTypeId: (typeId: TypeId) => "",
            getDirectoryForTypeId: (typeId: TypeId) => "",
            getCoreAsIsFiles: () => [],
            getCoreTestAsIsFiles: () => [],
            getPublicCoreAsIsFiles: () => [],
            getAsyncCoreAsIsFiles: () => [],
            getChildNamespaceSegments: (fernFilepath: FernFilepath) => []
        }
    ) {
        // Initialize the model navigator to traverse and query the IR
        this.model = new ModelNavigator(intermediateRepresentation, this);

        this.ir = is.IR.IntermediateRepresentation(intermediateRepresentation)
            ? intermediateRepresentation
            : ({} as IntermediateRepresentation);
        this.dir = is.DynamicIR.DynamicIntermediateRepresentation(intermediateRepresentation)
            ? intermediateRepresentation
            : ({} as DynamicFernIr.dynamic.DynamicIntermediateRepresentation);
    }

    public readonly ir: IntermediateRepresentation;
    public readonly dir: DynamicFernIr.dynamic.DynamicIntermediateRepresentation;

    /**
     * Utility for generating C# AST nodes and type references.
     * Provides methods for creating class references, type declarations, and other C# constructs.
     */
    public readonly csharp = new CSharp(this);

    /**
     * Registry for tracking and managing generated names to prevent collisions.
     * Ensures unique naming across namespaces, classes, properties, and other identifiers.
     */
    public readonly registry = new NameRegistry(this);

    /**
     * Navigator for traversing the IR model and querying type information.
     * Provides access to types, endpoints, errors, and other IR elements.
     */
    public readonly model: ModelNavigator;

    /**
     * Manager for external dependencies and imports.
     * Tracks which external packages and types are needed by the generated code.
     */
    public readonly extern = new Extern(this);

    /**
     * Lazily-initialized configuration settings for C# code generation.
     *
     * These settings control various aspects of the generated code including:
     * - Namespace configuration
     * - Feature flags (websockets, forward-compatible enums, etc.)
     * - Type generation options (discriminated unions, additional properties)
     * - Naming customization (client class names, exception classes)
     * - Testing options (mock server tests)
     * - Access modifiers and visibility settings
     *
     * All settings are derived from the custom configuration with sensible defaults.
     * Each property is lazily evaluated and cached on first access.
     */
    public readonly settings = lazy({
        /** The root namespace for all generated C# code (e.g., "Acme.MyApi"). Defaults to Organization_ApiName in camelCase. */
        namespace: () =>
            this.customConfig.namespace ??
            upperFirst(camelCase(`${this.generatorConfig.organization}_${this.apiName}`)),
        /** List of types that should use ReadOnlyMemory<byte> instead of byte[] for binary data. Default: []. */
        readOnlyMemoryTypes: () => this.customConfig["read-only-memory-types"] ?? [],
        /** When true, simplifies object dictionaries in generated code for better type safety. Default: false. */
        simplifyObjectDictionaries: () => this.customConfig["simplify-object-dictionaries"] ?? false,
        /** When true, uses fully-qualified namespaces in generated code to avoid naming conflicts. Default: false. */
        useFullyQualifiedNamespaces: () => this.customConfig["experimental-fully-qualified-namespaces"] ?? false,
        /** When true, runs dotnet format on generated code for consistent formatting. Default: false. */
        useDotnetFormat: () => this.customConfig["experimental-dotnet-format"] ?? false,
        /** When true, enables WebSocket support in the generated SDK. Default: false. */
        enableWebsockets: () => this.customConfig["experimental-enable-websockets"] ?? false,
        /** @deprecated Use `generateLiterals` instead. When true, generates readonly constants instead of static properties. Default: false. */
        enableReadonlyConstants: () => this.customConfig["experimental-readonly-constants"] ?? false,
        /** When true, generates literal struct types for literal properties. If `experimental-readonly-constants` is also set, this takes precedence. Default: false. */
        generateLiterals: () =>
            this.customConfig["generate-literals"] ?? this.customConfig["experimental-readonly-constants"] ?? false,
        /** When true, uses explicit nullable/optional attributes and Optional<T?> wrapper for better null handling. Default: false. */
        enableExplicitNullableOptional: () => this.customConfig["experimental-explicit-nullable-optional"] ?? false,
        /** When true, generates Defaults nested class and WithDefaults() method for request records with default values. Default: false. */
        useDefaultRequestParameterValues: () => this.customConfig["use-default-request-parameter-values"] ?? false,
        /** When true, redacts the response body in deserialization error exceptions and adds a custom ToString override to the base API exception. Default: false. */
        redactResponseBodyOnError: () => this.customConfig["redact-response-body-on-error"] ?? false,
        /** Temporary mapping of websocket environment configurations. Default: {}. */
        temporaryWebsocketEnvironments: () => this.customConfig["temporary-websocket-environments"] ?? {},
        /** Custom name for the base API exception class. Default: "" (auto-generated). */
        baseApiExceptionClassName: () => this.customConfig["base-api-exception-class-name"] ?? "",
        /** Custom name for the base exception class. Default: "" (auto-generated). */
        baseExceptionClassName: () => this.customConfig["base-exception-class-name"] ?? "",
        /** When true, generates discriminated unions with type discriminators. Default: true. */
        shouldGeneratedDiscriminatedUnions: () => this.customConfig["use-discriminated-unions"] ?? true,
        /** When true, generates undiscriminated unions with runtime type detection. Default: false. */
        shouldGenerateUndiscriminatedUnions: () => this.customConfig["use-undiscriminated-unions"] ?? false,
        /** Custom name for the exported public client class. Default: "" (uses clientClassName or computed name). */
        exportedClientClassName: () => this.customConfig["exported-client-class-name"] ?? "",
        /** Custom name for the internal client class. Default: "" (auto-generated from organization/workspace). */
        clientClassName: () => this.customConfig["client-class-name"] ?? "",
        /** When true, places core classes in the root namespace instead of {root}.Core. Default: true. */
        rootNamespaceForCoreClasses: () => this.customConfig["root-namespace-for-core-classes"] ?? true,
        /** Custom NuGet package identifier. Default: "" (uses root namespace). */
        packageId: () => this.customConfig["package-id"] ?? "",
        /** When true, generates enums that can handle unknown/future values gracefully. Default: true. */
        isForwardCompatibleEnumsEnabled: () =>
            this.customConfig["enable-forward-compatible-enums"] ??
            this.customConfig["experimental-enable-forward-compatible-enums"] ??
            true,
        /** Mapping of websocket environment configurations. Default: {}. */
        websocketEnvironments: () => this.customConfig["temporary-websocket-environments"] ?? {},
        /** Custom name for the pagination class. Default: "" (auto-generated). */
        customPagerName: () => this.customConfig["custom-pager-name"] ?? "",
        /** Custom name for the environment configuration class. Default: "" (auto-generated). */
        environmentClassName: () => this.customConfig["environment-class-name"] ?? "",
        /** When true, generates dedicated error type classes for API errors. Default: true. */
        generateErrorTypes: () => this.customConfig["generate-error-types"] ?? true,
        /** When true, inlines path parameters in method signatures instead of using a request object. Default: true. */
        shouldInlinePathParameters: () => this.customConfig["inline-path-parameters"] ?? true,
        /** When true, includes exception handler infrastructure for custom error handling. Default: false. */
        includeExceptionHandler: () => this.customConfig["include-exception-handler"] ?? false,
        /** Custom name for the exception interceptor class. Default: {PackageName}ExceptionInterceptor. */
        exceptionInterceptorClassName: () => this.customConfig["exception-interceptor-class-name"] ?? "",
        /** When true, generates mock server tests for the SDK. Default: true. Also accepts enable-wire-tests as an alias. */
        shouldGenerateMockServerTests: () =>
            this.customConfig["generate-mock-server-tests"] ?? this.customConfig["enable-wire-tests"] ?? true,
        /** Access modifier for the root client class (Public or Internal). Default: Public. */
        rootClientAccess: () =>
            this.customConfig["root-client-class-access"] == "internal" ? ast.Access.Internal : ast.Access.Public,
        /** Additional NuGet package dependencies to include in the generated project. Default: {}. */
        extraDependencies: () => this.customConfig["extra-dependencies"] ?? {},
        /** When true, omits Fern platform headers (X-Fern-Language, SDK name/version, User-Agent) from generated SDK requests. Default: false. */
        omitFernHeaders: () => this.customConfig["omit-fern-headers"] ?? false,
        /** When true, uses PascalCase for environment names (e.g., "Production" instead of "production"). Default: true. */
        pascalCaseEnvironments: () => this.customConfig["pascal-case-environments"] ?? true,
        /** Solution file format: "sln" generates both .sln and .slnx, "slnx" (default) generates only .slnx. */
        slnFormat: () => this.customConfig["sln-format"] ?? "slnx",
        /** When true, requires explicit namespace declarations instead of using file-scoped namespaces. Default: false. */
        explicitNamespaces: () => this.customConfig["explicit-namespaces"] === true,
        /**
         * Output path configuration for generated files.
         * Returns normalized paths for library, test, solution, and other files.
         */
        outputPath: () => {
            const config = this.customConfig["output-path"];
            if (config == null) {
                // Default: all files go to "src" for library/test, "." for solution/other
                return {
                    library: "src",
                    test: "src",
                    solution: ".",
                    other: "."
                };
            }
            if (typeof config === "string") {
                // Simple string: library and test go to that path, solution/other go to "."
                return {
                    library: config,
                    test: config,
                    solution: ".",
                    other: "."
                };
            }
            // Object: use specified paths with defaults
            return {
                library: config.library ?? "src",
                test: config.test ?? "src",
                solution: config.solution ?? ".",
                other: config.other ?? "."
            };
        }
    });

    public readonly constants = {
        folders: lazy({
            mockServerTests: () => this.support.makeRelativeFilePath("Unit/MockServer"),
            types: () => "Types",
            exceptions: () => "Exceptions",
            src: () => "src",
            protobuf: () => "proto",
            serializationTests: () => this.support.makeRelativeFilePath("Unit/Serialization"),
            project: () =>
                this.support.makeRelativeFilePath(
                    join(
                        this.constants.folders.sourceFiles,
                        this.support.makeRelativeFilePath(this.names.files.project)
                    )
                ),
            sourceFiles: () => this.support.makeRelativeFilePath(this.constants.folders.src),
            coreFiles: () =>
                this.support.makeRelativeFilePath(
                    join(
                        this.constants.folders.project,
                        this.support.makeRelativeFilePath(this.constants.defaults.core)
                    )
                ),
            publicCoreFiles: () =>
                this.support.makeRelativeFilePath(
                    join(
                        this.constants.folders.project,
                        this.support.makeRelativeFilePath(this.constants.defaults.core),
                        this.support.makeRelativeFilePath(this.constants.defaults.publicCore)
                    )
                ),
            testFiles: () =>
                this.support.makeRelativeFilePath(
                    join(
                        this.constants.folders.sourceFiles,
                        this.support.makeRelativeFilePath(this.names.files.testProject)
                    )
                )
        }),

        formatting: lazy({
            indent: () => "    "
        }),

        defaults: lazy({
            core: () => "Core",
            publicCore: () => "Public",
            version: () => "0.0.0"
        })
    };

    /**
     * Lazily-initialized namespace paths for organizing generated C# code.
     *
     * This object defines the namespace hierarchy used throughout the generated SDK:
     * - `root`: The top-level namespace for all generated code
     * - `core`: Internal implementation details and utilities (e.g., {root}.Core)
     * - `test`: Testing utilities and fixtures
     * - `testUtils`: Helper methods for tests
     * - `mockServerTest`: Mock server testing infrastructure
     * - `publicCore`: Public core utilities exposed to SDK users
     * - `webSocketsCore`: WebSocket API utilities
     * - `publicCoreTest`: Tests for public core functionality
     * - `asIsTestUtils`: Test utilities that preserve original casing
     * - `publicCoreClasses`: Location for core classes based on rootNamespaceForCoreClasses setting
     *
     * Namespaces are canonicalized through the NameRegistry to avoid conflicts with generated types.
     * All namespace paths are lazy-evaluated and cached on first access.
     */
    public readonly namespaces = lazy({
        /** The top-level root namespace for all generated SDK code (e.g., "Acme.MyApi"). */
        root: (): string => this.settings.namespace,
        /** Internal Core namespace for SDK implementation details and utilities ({root}.Core). */
        core: (): string => `${this.namespaces.root}.Core`,
        /** Pre-qualified root namespace with global:: prefix when the root segment has a type-namespace conflict. */
        qualifiedRoot: (): string => this.qualifyNamespace(this.namespaces.root),
        /** Pre-qualified Core namespace with global:: prefix when the root segment has a type-namespace conflict. */
        qualifiedCore: (): string => this.qualifyNamespace(this.namespaces.core),
        /** Test namespace for all test-related code, canonicalized to avoid conflicts ({root}.Test). */
        test: (): string => this.registry.canonicalizeNamespace(`${this.namespaces.root}.Test`),
        /** Test utilities namespace for helper methods and fixtures ({root}.Test.Utils). */
        testUtils: (): string => `${this.namespaces.test}.Utils`,
        /** Mock server test namespace for mock server testing infrastructure ({root}.Test.Unit.MockServer). */
        mockServerTest: (): string => `${this.namespaces.test}.Unit.MockServer`,
        /** Public Core namespace, same as root for publicly exposed core utilities. */
        publicCore: (): string => this.namespaces.root,
        /** WebSockets Core namespace for WebSocket APIs ({root}.Core.WebSockets). */
        webSocketsCore: (): string => `${this.namespaces.core}.WebSockets`,
        /** Public Core test namespace for testing public core functionality ({root}.Test.PublicCore). */
        publicCoreTest: (): string => `${this.namespaces.root}.Test.PublicCore`,
        /** Test utilities namespace that preserves original casing ({root}.Test.Utils). */
        asIsTestUtils: (): string => `${this.namespaces.root}.Test.Utils`,
        /** Namespace for public core classes; either root or core based on rootNamespaceForCoreClasses setting. */
        publicCoreClasses: (): string =>
            this.settings.rootNamespaceForCoreClasses ? this.namespaces.root : this.namespaces.core,
        /** Implicit namespaces are namespaces that are assumed to be automatically imported into the generated code. */
        implicit: (): Set<string> =>
            new Set([
                "System",
                "System.Collections.Generic",
                "System.IO",
                "System.Linq",
                "System.Threading",
                "System.Threading.Tasks",
                "System.Net.Http"
            ])
    });

    /**
     * Lazily-initialized names for key generated classes and identifiers.
  
     *
     * Names are computed using naming conventions (camelCase, upperFirst) and can be
     * overridden via custom configuration. All names are lazy-evaluated and cached.
     */
    public readonly names = {
        classes: lazy({
            /** The name of the base API exception class (e.g., "AcmeWidgetsApiException"). */
            baseApiException: (): string =>
                this.settings.baseApiExceptionClassName || `${this.names.project.clientPrefix}ApiException`,
            /** The name of the base exception class for all SDK exceptions (e.g., "AcmeWidgetsException"). */
            baseException: (): string =>
                this.settings.baseExceptionClassName || `${this.names.project.clientPrefix}Exception`,
            /** The name of the main internal SDK client class (e.g., "AcmeWidgetsClient"). */
            rootClient: (): string => this.settings.clientClassName || `${this.names.project.clientPrefix}Client`,
            /** The name of the client class used in documentation snippets and examples. */
            rootClientForSnippets: (): string => this.settings.exportedClientClassName || this.names.classes.rootClient,
            /** The name for custom pagination classes (e.g., "AcmeWidgetsPager"), alphanumeric only. */
            customPager: (): string =>
                this.settings.customPagerName || `${this.names.project.packageId.replace(/[^a-zA-Z0-9]/g, "")}Pager`,
            /** The name for the environment configuration class (e.g., "AcmeWidgetsEnvironment"). */
            environment: (): string =>
                this.settings.environmentClassName || `${this.names.project.clientPrefix}Environment`,
            /** The name for the custom exception interceptor class (e.g., "AcmeWidgetsExceptionInterceptor"). */
            exceptionInterceptor: (): string =>
                this.settings.exceptionInterceptorClassName ||
                `${this.names.project.packageId.replace(/[^a-zA-Z0-9]/g, "")}ExceptionInterceptor`
        }),
        project: lazy({
            /** The computed client name derived from organization and workspace in camelCase (e.g., "AcmeWidgets"). */
            client: () =>
                upperFirst(camelCase(`${this.generatorConfig.organization}_${this.generatorConfig.workspaceName}`)),
            /** The prefix used for client-related classes, customizable via config or defaults to clientName. */
            clientPrefix: () =>
                this.settings.exportedClientClassName || this.settings.clientClassName || this.names.project.client,
            /** The NuGet package identifier for the generated SDK, defaults to root namespace if not specified. */
            packageId: () => this.settings.packageId || this.namespaces.root
        }),
        files: lazy({
            /* the name of the project */
            project: () => this.namespaces.root,
            /* the name of the test project */
            testProject: () => `${this.namespaces.root}.Test`
        }),
        methods: lazy({
            mockOauth: () => "MockOAuthEndpoint",
            mockInferredAuth: () => "MockInferredAuthEndpoint",
            getAccessTokenAsync: () => "GetAccessTokenAsync",
            getAuthHeadersAsync: () => "GetAuthHeadersAsync"
        }),
        variables: lazy({
            client: () => "client",
            response: () => "response",
            httpRequest: () => "httpRequest",
            sendRequest: () => "sendRequest",
            responseBody: () => "responseBody",
            query: () => "_query",
            headers: () => "_headers"
        }),
        parameters: lazy({
            cancellationToken: () => "cancellationToken",
            requestOptions: () => "options",
            idempotentOptions: () => "options"
        })
    };

    /**
     * Lazily-initialized C# type references for core SDK classes and utilities.
     *
     * This object provides type references for all core infrastructure classes used in the
     * generated SDK. These references are used throughout code generation to ensure consistent
     * type usage and proper namespace imports.
     *
     * ## Categories of Types:
     *
     * ### Request/Response Handling:
     * - `FormRequest`, `JsonRequest`: Request builders for different content types
     * - `ClientOptions`, `RequestOptions`: Configuration objects for API calls
     * - `RawClient`, `RawGrpcClient`: Low-level HTTP/gRPC clients
     * - `Headers`: HTTP header management
     *
     * ### Client Infrastructure:
     * - `RootClient`, `RootClientForSnippets`: Main SDK client classes
     * - `TestClient`: Testing infrastructure
     * - `WebSocketClient`: WebSocket client for managing connections
     *
     * ### Error Handling:
     * - `BaseException`, `BaseApiException`: Exception hierarchy
     * - `ExceptionInterceptor`, `ExceptionHandler`: Exception processing
     *
     * ### Serialization:
     * - `EnumSerializer`, `StringEnumSerializer`: Enum serialization
     * - `DateTimeSerializer`: DateTime handling
     * - `JsonUtils`: JSON utilities
     * - `OneOfSerializer`: Union type serialization
     * - `CollectionItemSerializer`: Collection element serialization
     * - `ProtoConverter`, `ProtoAnyMapper`: Protocol buffer conversion
     *
     * ### Pagination:
     * - `Pager`: Base pagination interface
     * - `CustomPagerClass`: Custom pagination implementation
     * - `OffsetPager`: Offset-based pagination
     * - `CursorPager`: Cursor-based pagination
     * - `CustomPagerFactory`, `CustomPagerContext`: Pagination utilities
     *
     * ### Additional Properties:
     * - `AdditionalProperties`: Mutable additional properties
     * - `ReadOnlyAdditionalProperties`: Immutable additional properties
     *
     * ### Other Utilities:
     * - `Version`: SDK version information
     * - `ValueConvert`: Value conversion utilities
     * - `FileParameter`: File upload support
     * - `Constants`: SDK constants
     * - `Environments`: Environment configuration
     * - `Extensions`: Extension methods
     * - `OAuthTokenProvider`: OAuth authentication
     * - `QueryBuilder`: Query string building
     * - `IStringEnum`, `StringEnum`: String-based enum support
     *
     * ## Usage Patterns:
     *
     * ### Non-Generic Types (cached):
     * ```typescript
     * const clientType = generation.Types.RootClient; // Returns cached ClassReference
     * ```
     *
     * ### Generic Types (evaluated per call):
     * ```typescript
     * const pager = generation.Types.Pager(itemType); // Returns new ClassReference each time
     * const webSocketClient = generation.Types.WebSocketClient();
     * ```
     *
     * All type references include proper namespace information and are registered with
     * the NameRegistry to ensure correct imports in generated code.
     */
    public readonly Types = lazy({
        Arbitrary: (name: string) => new Primitive.ArbitraryType(name, this),
        HttpMethodExtensions: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("HttpMethodExtensions")
            }),
        /** Core infrastructure type for building multipart/form-data requests */
        FormRequest: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("FormRequest")
            }),
        /** Optional<T> wrapper type for explicit undefined/null semantics */
        Optional: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("Optional")
            }),
        /** Configuration options for the SDK client (base URL, headers, timeout, etc.) */
        ClientOptions: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("ClientOptions"),
                namespace: this.namespaces.publicCoreClasses
            }),
        /** Low-level HTTP client wrapper for making raw API calls */
        RawClient: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("RawClient")
            }),
        /** Per-request configuration options (headers, timeout overrides, etc.) */
        RequestOptions: () =>
            this.csharp.classReference({
                namespace: this.namespaces.publicCoreClasses,
                origin: this.model.staticExplicit("RequestOptions")
            }),
        /** Interface for per-request configuration options */
        RequestOptionsInterface: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("IRequestOptions")
            }),
        /** Core infrastructure type for building JSON requests */
        JsonRequest: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("JsonRequest")
            }),
        /** SDK version metadata class */
        Version: () =>
            this.csharp.classReference({
                namespace: this.namespaces.publicCore,
                origin: this.model.staticExplicit("Version")
            }),
        /** Utility for converting values between different representations */
        ValueConvert: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("ValueConvert")
            }),
        /** Wrapper for file upload parameters in multipart requests */
        FileParameter: () =>
            this.csharp.classReference({
                namespace: this.namespaces.publicCore,
                origin: this.model.staticExplicit("FileParameter"),
                multipartMethodName: "AddFileParameterPart",
                multipartMethodNameForCollection: "AddFileParameterParts",
                isReferenceType: true
            }),
        /** HTTP header management utilities */
        Headers: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("Headers")
            }),
        /** HTTP header value management utilities */
        HeaderValue: () =>
            this.csharp.classReference({
                namespace: this.namespaces.core,
                origin: this.model.staticExplicit("HeaderValue")
            }),
        /** The main SDK client class (for code generation) */
        RootClient: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.rootClient),
                namespace: this.namespaces.root
            }),
        /** The main SDK client class (for documentation snippets) */
        RootClientForSnippets: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.rootClientForSnippets),
                namespace: this.namespaces.root
            }),
        /** Base exception class for API errors (HTTP 4xx/5xx responses) */
        BaseApiException: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.baseApiException),
                namespace: this.namespaces.publicCoreClasses
            }),
        /** Base exception class for all SDK exceptions */
        BaseException: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.baseException),
                namespace: this.namespaces.publicCoreClasses
            }),
        /** Interface for intercepting and processing exceptions */
        ExceptionInterceptor: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("IExceptionInterceptor"),
                namespace: this.namespaces.core
            }),
        /** Utility for handling and transforming exceptions */
        ExceptionHandler: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("ExceptionHandler"),
                namespace: this.namespaces.core
            }),
        /** Custom exception interceptor class for SDK authors to implement */
        CustomExceptionInterceptor: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.exceptionInterceptor),
                namespace: this.namespaces.core
            }),
        /** Utility for mapping Protocol Buffer Any types */
        ProtoAnyMapper: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("ProtoAnyMapper"),
                namespace: this.namespaces.core
            }),
        /** SDK-wide constants */
        Constants: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("Constants"),
                namespace: this.namespaces.core
            }),
        /** JSON serializer for enum types */
        EnumSerializer: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("EnumSerializer"),
                namespace: this.namespaces.core
            }),
        /** JSON serializer for DateTime types */
        DateTimeSerializer: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("DateTimeSerializer"),
                namespace: this.namespaces.core
            }),
        /** Utility methods for JSON serialization/deserialization */
        JsonUtils: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("JsonUtils"),
                namespace: this.namespaces.core
            }),
        /** Test assertion helper for JSON comparison */
        JsonAssert: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("JsonAssert"),
                namespace: this.namespaces.testUtils
            }),
        /** Factory for creating custom pagination instances */
        CustomPagerFactory: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(`${this.names.classes.customPager}Factory`),
                namespace: this.namespaces.core
            }),
        /** Context object for custom pagination state */
        CustomPagerContext: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(`${this.names.classes.customPager}Context`),
                namespace: this.namespaces.core
            }),
        /** Environment configuration class (base URLs for different environments) */
        Environments: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.environment),
                namespace: this.namespaces.publicCoreClasses
            }),
        /** Test client for testing infrastructure */
        TestClient: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("TestClient"),
                namespace: this.namespaces.test
            }),
        /** Base class for mock server tests */
        BaseMockServerTest: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("BaseMockServerTest"),
                namespace: this.namespaces.mockServerTest
            }),
        /** Request options with idempotency key support */
        IdempotentRequestOptions: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("IdempotentRequestOptions"),
                namespace: this.namespaces.publicCoreClasses
            }),
        /** Interface for idempotent request options */
        IdempotentRequestOptionsInterface: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("IIdempotentRequestOptions"),
                namespace: this.namespaces.core
            }),
        /** Interface for string-based enum types */
        IStringEnum: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("IStringEnum"),
                namespace: this.namespaces.core
            }),
        /** WebSocket client for managing WebSocket connections */
        WebSocketClient: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("WebSocketClient"),
                namespace: this.namespaces.webSocketsCore
            }),
        /** Query string builder utility for WebSocket URLs (legacy) */
        QueryBuilder: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("Query"),
                namespace: this.namespaces.webSocketsCore
            }),
        /** High-performance query string builder with fluent API */
        QueryStringBuilder: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("QueryStringBuilder"),
                namespace: this.namespaces.core
            }),
        /** Fluent builder for constructing query strings */
        QueryStringBuilderBuilder: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("QueryStringBuilder.Builder"),
                namespace: this.namespaces.core
            }),
        /** OAuth token provider for authentication */
        OAuthTokenProvider: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("OAuthTokenProvider"),
                namespace: this.namespaces.core
            }),
        /** Inferred auth token provider for authentication */
        InferredAuthTokenProvider: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("InferredAuthTokenProvider"),
                namespace: this.namespaces.core
            }),
        /** Converter for Protocol Buffer types */
        ProtoConverter: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("ProtoConverter"),
                namespace: this.namespaces.core
            }),
        /** Low-level gRPC client wrapper */
        RawGrpcClient: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("RawGrpcClient"),
                namespace: this.namespaces.core
            }),
        /** Extension methods for common operations */
        Extensions: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("Extensions"),
                namespace: this.namespaces.core
            }),
        /** Request options for gRPC calls */
        GrpcRequestOptions: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("GrpcRequestOptions"),
                namespace: this.namespaces.root
            }),
        /** Configuration options for gRPC channels */
        GrpcChannelOptions: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("GrpcChannelOptions"),
                namespace: "Grpc.Net.Client"
            }),
        /**
         * Generic string-based enum wrapper type.
         * @param genericType - The specific enum type to wrap (optional)
         */
        StringEnum: (genericType?: ast.Type | ast.ClassReference) =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("StringEnum"),
                namespace: this.namespaces.core,
                generics: genericType ? [genericType] : undefined
            }),
        /**
         * Generic event wrapper for WebSocket APIs.
         * @param genericType - The event payload type
         */
        WebSocketEvent: (genericType: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("Event"),
                namespace: this.namespaces.webSocketsCore,
                generics: [genericType]
            });
        },
        /** Connection status enum for WebSocket connections */
        ConnectionStatus: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("ConnectionStatus"),
                namespace: this.namespaces.webSocketsCore
            }),
        /** Connected event for WebSocket connections */
        WebSocketConnected: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("Connected"),
                namespace: this.namespaces.webSocketsCore
            }),
        /** Closed event for WebSocket connections */
        WebSocketClosed: () =>
            this.csharp.classReference({
                origin: this.model.staticExplicit("Closed"),
                namespace: this.namespaces.webSocketsCore
            }),
        /**
         * JSON serializer for string-based enum types.
         * @param enumClassReference - The enum type to serialize
         */
        StringEnumSerializer: (enumClassReference: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("StringEnumSerializer"),
                namespace: this.namespaces.core,
                generics: [enumClassReference]
            });
        },
        /**
         * Custom pagination class for iterating over paged results.
         * @param itemType - The type of items in each page
         */
        CustomPagerClass: (itemType: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit(this.names.classes.customPager),
                namespace: this.namespaces.core,
                generics: [itemType]
            });
        },
        /**
         * Generic pager interface for pagination support.
         * @param itemType - The type of items being paginated
         */
        Pager: (itemType: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("Pager"),
                namespace: this.namespaces.core,
                generics: [itemType]
            });
        },
        /**
         * Offset-based pagination implementation.
         * Supports paginating through results using numeric offsets.
         *
         * @param requestType - The type of the pagination request
         * @param requestOptionsType - The type of request options
         * @param responseType - The type of the pagination response
         * @param offsetType - The type of the offset (usually int or long)
         * @param stepType - The type of the step/page size (usually int)
         * @param itemType - The type of items in the paginated results
         */
        OffsetPager: ({
            requestType,
            requestOptionsType,
            responseType,
            offsetType,
            stepType,
            itemType
        }: {
            requestType: ast.Type;
            requestOptionsType: ast.Type;
            responseType: ast.Type;
            offsetType: ast.Type;
            stepType: ast.Type;
            itemType: ast.Type;
        }): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("OffsetPager"),
                namespace: this.namespaces.core,
                generics: [requestType, requestOptionsType, responseType, offsetType, stepType, itemType]
            });
        },
        /**
         * Cursor-based pagination implementation.
         * Supports paginating through results using opaque cursor tokens.
         *
         * @param requestType - The type of the pagination request
         * @param requestOptionsType - The type of request options
         * @param responseType - The type of the pagination response
         * @param cursorType - The type of the cursor token (usually string)
         * @param itemType - The type of items in the paginated results
         */
        CursorPager: ({
            requestType,
            requestOptionsType,
            responseType,
            cursorType,
            itemType
        }: {
            requestType: ast.Type;
            requestOptionsType: ast.Type;
            responseType: ast.Type;
            cursorType: ast.Type;
            itemType: ast.Type;
        }): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("CursorPager"),
                namespace: this.namespaces.core,
                generics: [requestType, requestOptionsType, responseType, cursorType, itemType]
            });
        },
        /**
         * Custom JSON serializer for collection items.
         * Wraps items in a collection with a specific serializer implementation.
         *
         * @param itemType - The type of items in the collection
         * @param serializer - The serializer class to use for each item
         * @returns A ClassReference for CollectionItemSerializer<TItem, TSerializer>
         */
        CollectionItemSerializer: (
            itemType: ast.ClassReference,
            serializer: ast.ClassReference
        ): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("CollectionItemSerializer"),
                namespace: this.namespaces.core,
                generics: [itemType, serializer]
            });
        },
        /**
         * JSON serializer for union/OneOf types.
         * Handles discriminated and undiscriminated union serialization.
         *
         * @param oneof - The union type to serialize
         * @returns A ClassReference for OneOfSerializer<TOneOf>
         */
        OneOfSerializer: (oneof: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("OneOfSerializer"),
                namespace: this.namespaces.core,
                generics: [oneof]
            });
        },
        /**
         * Mutable dictionary for additional/extra properties on objects.
         * Allows setting arbitrary key-value pairs beyond defined properties.
         *
         * @param genericType - The value type for additional properties (defaults to object if not specified)
         * @returns A ClassReference for AdditionalProperties or AdditionalProperties<T>
         */
        AdditionalProperties: (genericType?: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("AdditionalProperties"),
                namespace: this.namespaces.publicCore,
                generics: genericType ? [genericType] : undefined
            });
        },
        /**
         * Immutable read-only dictionary for additional/extra properties on objects.
         * Provides read-only access to arbitrary key-value pairs beyond defined properties.
         *
         * @param genericType - The value type for additional properties (defaults to object if not specified)
         * @returns A ClassReference for ReadOnlyAdditionalProperties or ReadOnlyAdditionalProperties<T>
         */
        ReadOnlyAdditionalProperties: (genericType?: ast.Type | ast.ClassReference): ast.ClassReference => {
            return this.csharp.classReference({
                origin: this.model.staticExplicit("ReadOnlyAdditionalProperties"),
                namespace: this.namespaces.publicCore,
                generics: genericType ? [genericType] : undefined
            });
        }
    });
    public Primitive = lazy({
        /**
         * Creates a string type.
         *
         * @returns A Type object representing the C# string type
         */
        string: () => {
            return new Primitive.String(this);
        },
        /**
         * Creates a boolean type.
         *
         * @returns A Type object representing the C# bool type
         */
        boolean: () => {
            return new Primitive.Boolean(this);
        },
        /**
         * Creates an integer type.
         *
         * @returns A Type object representing the C# int type
         */
        integer: () => {
            return new Primitive.Integer(this);
        },
        /**
         * Creates a long type.
         *
         * @returns A Type object representing the C# long type
         */
        long: () => {
            return new Primitive.Long(this);
        },
        /**
         * Creates an unsigned integer type.
         *
         * @returns A Type object representing the C# uint type
         */
        uint: () => {
            return new Primitive.Uint(this);
        },
        /**
         * Creates an unsigned long type.
         *
         * @returns A Type object representing the C# ulong type
         */
        ulong: () => {
            return new Primitive.ULong(this);
        },
        /**
         * Creates a float type.
         *
         * @returns A Type object representing the C# float type
         */
        float: () => {
            return new Primitive.Float(this);
        },
        /**
         * Creates a double type.
         *
         * @returns A Type object representing the C# double type
         */
        double: () => {
            return new Primitive.Double(this);
        },
        /**
         * Creates an object type.
         *
         * @returns A Type object representing the C# object type
         */
        object: () => {
            return new Primitive.Object(this);
        }
    });
    public Value = lazy({
        /**
         * Creates a string type.
         *
         * @returns A Type object representing the C# string type
         */
        binary: () => {
            return new Value.Binary(this);
        },
        /**
         * Creates a DateOnly type.
         *
         * @returns A Type object representing the C# DateOnly type
         */
        dateOnly: () => {
            return new Value.DateOnly(this);
        },
        /**
         * Creates a DateTime type.
         *
         * @returns A Type object representing the C# DateTime type
         */
        dateTime: () => {
            return new Value.DateTime(this);
        },
        /**
         * Creates a Guid type.
         *
         * @returns A Type object representing the C# Guid type
         */
        uuid: () => {
            return new Value.Uuid(this);
        },
        /**
         * Creates a string enum type.
         *
         * @param value - The class reference for the string enum
         * @returns A Type object representing the string enum type
         */
        stringEnum: (value: ClassReference) => {
            return new Value.StringEnum(value, this);
        }
    });
    public Collection = lazy({
        /**
         * Creates an array type.
         *
         * @param value - The element type of the array
         * @returns A Type object representing the C# array type
         */
        array: (value: Type) => {
            return new Collection.Array(value, this);
        },
        /**
         * Creates a list type.
         *
         * @param value - The element type of the list
         * @returns A Type object representing the C# List<T> type
         */
        listType: (value: Type) => {
            return new Collection.ListType(value, this);
        },
        /**
         * Creates a generic list type.
         *
         * @param value - The element type of the list
         * @returns A Type object representing the C# List<T> type
         */
        list: (value: Type) => {
            return new Collection.List(value, this);
        },
        /**
         * Creates a set type.
         *
         * @param value - The element type of the set
         * @returns A Type object representing the C# HashSet<T> type
         */
        set: (value: Type) => {
            return new Collection.Set(value, this);
        },
        /**
         * Creates a map/dictionary type.
         *
         * @param keyType - The key type of the map
         * @param valueType - The value type of the map
         * @param options - Optional configuration for the map
         * @returns A Type object representing the C# Dictionary<TKey, TValue> type
         */
        map: (keyType: Type, valueType: Type, options?: { dontSimplify?: boolean }) => {
            return new Collection.Map(keyType, valueType, this, options);
        },
        /**
         * Creates an IDictionary type.
         *
         * @param keyType - The key type of the dictionary
         * @param valueType - The value type of the dictionary
         * @param options - Optional configuration for the dictionary
         * @returns A Type object representing the C# IDictionary<TKey, TValue> type
         */
        idictionary: (keyType: Type, valueType: Type, options?: { dontSimplify?: boolean }) => {
            return new Collection.IDictionary(keyType, valueType, this, options);
        },
        /**
         * Creates a KeyValuePair type.
         *
         * @param keyType - The key type of the pair
         * @param valueType - The value type of the pair
         * @returns A Type object representing the C# KeyValuePair<TKey, TValue> type
         */
        keyValuePair: (keyType: Type, valueType: Type) => {
            return new Collection.KeyValuePair(keyType, valueType, this);
        }
    });

    public readonly format = lazy({
        private: (name: string) => `_${text.camelCase(name)}`
    });

    /** This is called (once) before any generator actually starts to generate code.
     * It offers a last-chance to validate or modify the generation before certain things are fixed in place.
     * If this returns false, the generation should be aborted.
     */
    public initialize(): boolean {
        return this.initializers.implicitNamespaces;
    }

    /** One-time initializers that are called before any generator actually starts to generate code. */
    public readonly initializers = lazy({
        implicitNamespaces: () => {
            // add all the implicit namespaces
            for (const namespace of this.namespaces.implicit) {
                this.registry.addImplicitNamespace(namespace);
            }
            return true;
        }
    });

    /** Provides access to .NET System namespace types and utilities */
    public get System() {
        return this.extern.System;
    }

    /** Provides access to NUnit testing framework types */
    public get NUnit() {
        return this.extern.NUnit;
    }

    /** Provides access to OneOf discriminated union library types */
    public get OneOf() {
        return this.extern.OneOf;
    }

    /** Provides access to Google protocol buffer types */
    public get Google() {
        return this.extern.Google;
    }
    public get Grpc() {
        return this.extern.Grpc;
    }
    /** Provides access to WireMock.Net testing/mocking library types */
    public get WireMock() {
        return this.extern.WireMock;
    }

    /**
     * Returns a namespace string with a `global::` prefix if the first segment
     * has a type-namespace conflict (e.g., class "Candid" shadowing namespace "Candid.Net").
     * Use this when writing raw namespace strings in string interpolations to avoid CS0426.
     */
    public qualifyNamespace(ns: string): string {
        const firstSegment = ns.split(".")[0];
        if (firstSegment && this.registry.hasTypeNamespaceConflict(firstSegment)) {
            return `global::${ns}`;
        }
        return ns;
    }
}