WireTestGenerator.ts

import { FernGeneratorExec } from "@fern-api/browser-compatible-base-generator";
import { FernIr as DynamicFernIr } from "@fern-api/dynamic-ir-sdk";
import { RelativeFilePath } from "@fern-api/fs-utils";
import { WireMockMapping } from "@fern-api/mock-utils";
import { python } from "@fern-api/python-ast";
import { WriteablePythonFile } from "@fern-api/python-base";
import { DynamicSnippetsGenerator } from "@fern-api/python-dynamic-snippets";
import { FernIr } from "@fern-fern/ir-sdk";
import { SdkGeneratorContext } from "../SdkGeneratorContext.js";
import { WireTestSetupGenerator } from "./WireTestSetupGenerator.js";

/**
 * Local interface for wire test examples.
 * Contains only the fields needed for wire test generation, avoiding coupling to FernIr.dynamic.EndpointExample.
 */
interface WireTestExample {
    name?: string;
    pathParameters: Record<string, unknown>;
    queryParameters: Record<string, unknown>;
    headers: Record<string, unknown>;
    requestBody?: unknown;
}

/**
 * Generates WireMock-based integration tests for Python SDK.
 *
 * This is a skeleton implementation that sets up the infrastructure for wire tests
 * but does not implement the actual Python test code generation.
 */
export class WireTestGenerator {
    private readonly context: SdkGeneratorContext;
    private dynamicIr: FernIr.dynamic.DynamicIntermediateRepresentation;
    private wireMockConfigContent: Record<string, WireMockMapping>;
    private snippetGenerator: DynamicSnippetsGenerator;
    constructor(context: SdkGeneratorContext, ir: FernIr.IntermediateRepresentation) {
        this.context = context;
        const dynamicIr = ir.dynamic;
        if (!dynamicIr) {
            throw new Error("Cannot generate wire tests without dynamic IR");
        }
        this.dynamicIr = dynamicIr;
        this.wireMockConfigContent = this.getWireMockConfigContent();

        // TODO(tjdbdc): Really need a migration framework for FernIr.dynamic IR
        this.snippetGenerator = new DynamicSnippetsGenerator({
            ir: this.dynamicIr,
            config: {
                organization: context.config.organization,
                workspaceName: context.config.workspaceName,
                customConfig: context.customConfig
            } as FernGeneratorExec.GeneratorConfig
        });
    }

    // =============================================================================
    // PUBLIC API
    // =============================================================================

    public async generate(): Promise<void> {
        const endpointsByService = this.groupEndpointsByService();

        this.context.logger.debug(
            `Wire tests: ${endpointsByService.size} services, ${Object.keys(this.dynamicIr.endpoints).length} dynamic endpoints`
        );

        let totalEndpointsWithExamples = 0;

        for (const [serviceName, endpoints] of endpointsByService.entries()) {
            // Filter to endpoints that have static IR examples
            // We MUST use static IR examples to match WireMock mappings (which are generated from static IR)
            const endpointsWithExamples = endpoints.filter((endpoint) => {
                const staticExample = this.getStaticIrExample(endpoint);
                return staticExample !== undefined;
            });

            totalEndpointsWithExamples += endpointsWithExamples.length;

            if (endpointsWithExamples.length === 0) {
                continue;
            }

            const serviceTestFile = await this.generateServiceTestFile(serviceName, endpointsWithExamples);
            if (serviceTestFile) {
                this.context.project.addSourceFiles(serviceTestFile);
            }
        }

        this.context.logger.debug(`Wire tests: ${totalEndpointsWithExamples} endpoints with static IR examples`);

        // Generate docker-compose.test.yml and wiremock-mappings.json for WireMock
        new WireTestSetupGenerator(this.context, this.context.ir).generate();
    }

    /**
     * Gets the first available example from the static IR for an endpoint.
     * Prefers user-specified examples over autogenerated ones.
     */
    private getStaticIrExample(endpoint: FernIr.HttpEndpoint): FernIr.ExampleEndpointCall | undefined {
        // Prefer user-specified OK examples (WireMock mappings are generated from successful examples).
        for (const userExample of endpoint.userSpecifiedExamples) {
            if (userExample.example && userExample.example.response.type === "ok") {
                return userExample.example;
            }
        }
        // Then fall back to any user-specified example
        for (const userExample of endpoint.userSpecifiedExamples) {
            if (userExample.example) {
                return userExample.example;
            }
        }
        // Prefer autogenerated OK examples
        for (const autoExample of endpoint.autogeneratedExamples) {
            if (autoExample.example && autoExample.example.response.type === "ok") {
                return autoExample.example;
            }
        }
        // Then fall back to any autogenerated example
        for (const autoExample of endpoint.autogeneratedExamples) {
            if (autoExample.example) {
                return autoExample.example;
            }
        }
        return undefined;
    }

    /**
     * Checks if an example has an error response (non-2xx status code).
     */
    private isErrorResponse(example: FernIr.ExampleEndpointCall): boolean {
        // WireMock mappings produced by @fern-api/mock-utils currently only include successful
        // responses (e.g. 200/201). Until error stubs are generated as well, wire tests should
        // not assert ApiError behavior.
        void example;
        return false;
    }

    /**
     * Converts a static IR example to a wire test example format.
     */
    private convertStaticExampleToWireTest(
        endpoint: FernIr.HttpEndpoint,
        staticExample: FernIr.ExampleEndpointCall
    ): WireTestExample {
        // Extract path parameters
        const pathParameters: Record<string, unknown> = {};
        for (const param of [
            ...(staticExample.rootPathParameters ?? []),
            ...(staticExample.servicePathParameters ?? []),
            ...(staticExample.endpointPathParameters ?? [])
        ]) {
            pathParameters[param.name.originalName] = param.value.jsonExample;
        }

        // Extract query parameters
        const queryParameters: Record<string, unknown> = {};
        for (const param of staticExample.queryParameters ?? []) {
            queryParameters[param.name.wireValue] = param.value.jsonExample;
        }

        // Extract headers
        const headers: Record<string, unknown> = {};
        for (const header of [...(staticExample.serviceHeaders ?? []), ...(staticExample.endpointHeaders ?? [])]) {
            headers[header.name.wireValue] = header.value.jsonExample;
        }

        // Extract request body
        let requestBody: unknown = undefined;
        if (staticExample.request) {
            if ("jsonExample" in staticExample.request && staticExample.request.jsonExample !== undefined) {
                requestBody = staticExample.request.jsonExample;
            }
        }

        return {
            name: staticExample.name?.originalName,
            pathParameters,
            queryParameters,
            headers,
            requestBody
        };
    }

    // =============================================================================
    // FILE GENERATION
    // =============================================================================

    private async generateServiceTestFile(
        serviceName: string,
        endpoints: FernIr.HttpEndpoint[]
    ): Promise<WriteablePythonFile | null> {
        const endpointTestCases: Array<{
            endpoint: FernIr.HttpEndpoint;
            example: WireTestExample;
            service: FernIr.HttpService;
            exampleIndex: number;
            isErrorResponse: boolean;
        }> = [];

        for (const endpoint of endpoints) {
            // Find the service that owns this endpoint
            const service = Object.values(this.context.ir.services).find((s) =>
                s.endpoints.some((e) => e.id === endpoint.id)
            );
            if (!service) {
                continue;
            }

            // Skip bytes request body endpoints — the IR example system has no
            // ExampleRequestBody variant for bytes, so we can't produce a proper example.
            if (endpoint.requestBody?.type === "bytes") {
                continue;
            }

            // Always use static IR examples to match WireMock mappings
            // WireMock mappings are generated from static IR examples, so we must use the same examples
            const staticExample = this.getStaticIrExample(endpoint);
            if (staticExample) {
                const wireTestExample = this.convertStaticExampleToWireTest(endpoint, staticExample);
                const isErrorResponse = this.isErrorResponse(staticExample);
                endpointTestCases.push({
                    endpoint,
                    example: wireTestExample,
                    service,
                    exampleIndex: 0,
                    isErrorResponse
                });
            }
        }

        if (endpointTestCases.length === 0) {
            return null;
        }

        this.context.logger.info(
            `Generating test file for service ${serviceName} with ${endpointTestCases.length} test cases`
        );

        const pythonFile = this.buildTestFile(serviceName, endpointTestCases);
        if (pythonFile === null) {
            return null;
        }

        return new WriteablePythonFile({
            filename: `test_${serviceName}`,
            directory: RelativeFilePath.of("tests/wire"),
            contents: pythonFile
        });
    }

    // =============================================================================
    // FILE BUILDING
    // =============================================================================

    private buildTestFile(
        serviceName: string,
        testCases: Array<{
            endpoint: FernIr.HttpEndpoint;
            example: WireTestExample;
            service: FernIr.HttpService;
            exampleIndex: number;
            isErrorResponse: boolean;
        }>
    ): python.PythonFile | null {
        const statements: python.AstNode[] = [];

        // Add raw imports for pytest (not supported by AST)
        statements.push(python.codeBlock("import pytest"));

        // Add an import registration statement (for "from X import Y" style imports)
        statements.push(this.createImportRegistration());

        // Add test functions for each endpoint
        let testFunctionCount = 0;
        for (const { endpoint, example, service, exampleIndex, isErrorResponse } of testCases) {
            const testFunction = this.generateEndpointTestFunction(
                serviceName,
                endpoint,
                example,
                service,
                exampleIndex,
                isErrorResponse
            );
            if (testFunction) {
                statements.push(testFunction);
                testFunctionCount++;
            }
        }

        if (testFunctionCount === 0) {
            return null;
        }

        const pathSegments = `tests/wire/test_${serviceName}`.split("/");
        return python.file({
            path: pathSegments,
            statements
        });
    }

    /**
     * Creates a special node that registers imports without rendering anything.
     * This is a workaround for using codeBlock while still getting automatic "from X import Y" imports.
     */
    private createImportRegistration(): python.AstNode {
        // Create an empty code block
        const node = python.codeBlock("");

        // Import get_client and verify_request_count from .conftest (relative import within tests/wire package)
        node.addReference(python.reference({ name: "get_client", modulePath: [".conftest"] }));
        node.addReference(python.reference({ name: "verify_request_count", modulePath: [".conftest"] }));

        // Import ApiError from the SDK's core module for error response tests
        const modulePath = this.context.getModulePath();
        node.addReference(python.reference({ name: "ApiError", modulePath: [modulePath, "core"] }));

        return node;
    }

    // =============================================================================
    // TEST FUNCTION GENERATION
    // =============================================================================

    private generateEndpointTestFunction(
        serviceName: string,
        endpoint: FernIr.HttpEndpoint,
        example: WireTestExample,
        service: FernIr.HttpService,
        exampleIndex: number,
        isErrorResponse: boolean
    ): python.Method | null {
        try {
            const testName = this.getTestFunctionName(serviceName, endpoint);
            const basePath = this.buildBasePath(endpoint);
            const queryParamsCode = this.buildQueryParamsCode(endpoint);

            // Build deterministic test ID based on fully qualified path
            const testId = this.buildDeterministicTestId(service, endpoint, exampleIndex);

            const statements: python.AstNode[] = [];

            // Use deterministic test ID for concurrency safety
            statements.push(python.codeBlock(`test_id = "${testId}"`));

            // Create client using the get_client helper from conftest.py
            // This ensures all required auth parameters are supplied with fake values
            statements.push(python.codeBlock(`client = get_client(test_id)`));

            // Exclusions use definition-level identifiers in the form "<service_path>.<endpoint_name>"
            // or "<service_path>.*" to exclude an entire service.
            const servicePathParts = service.name.fernFilepath.allParts.map((part) => part.snakeCase.safeName);
            const servicePath = servicePathParts.join(".");
            const selector =
                servicePath.length > 0
                    ? `${servicePath}.${endpoint.name.snakeCase.safeName}`
                    : endpoint.name.snakeCase.safeName;
            const excluded = this.context.customConfig.wire_tests?.exclusions ?? [];
            if (
                excluded.includes(selector) ||
                excluded.some((pattern) => pattern.endsWith(".*") && selector.startsWith(pattern.slice(0, -2) + "."))
            ) {
                return null;
            }

            // Generate the API call AST directly
            const apiCallAst = this.generateApiCallAst(endpoint, example);

            // For error responses, wrap in pytest.raises() to expect the exception
            if (isErrorResponse) {
                // For streaming endpoints, we need to consume the iterator inside pytest.raises
                if (this.isStreamingEndpoint(endpoint)) {
                    const block = python.codeBlock(
                        `with pytest.raises(ApiError):\n        for _ in ${apiCallAst.toString()}:\n            pass`
                    );
                    // Preserve import references from the AST that are lost during toString()
                    for (const ref of apiCallAst.getReferences()) {
                        block.addReference(ref);
                    }
                    statements.push(block);
                } else {
                    const block = python.codeBlock(`with pytest.raises(ApiError):\n        ${apiCallAst.toString()}`);
                    for (const ref of apiCallAst.getReferences()) {
                        block.addReference(ref);
                    }
                    statements.push(block);
                }
            } else {
                // For streaming endpoints, wrap the call in a for loop to consume the iterator
                // This is necessary because streaming methods return lazy generators that don't
                // execute the HTTP request until iterated
                if (this.isStreamingEndpoint(endpoint)) {
                    const block = python.codeBlock(`for _ in ${apiCallAst.toString()}:`);
                    // Preserve import references from the AST that are lost during toString()
                    for (const ref of apiCallAst.getReferences()) {
                        block.addReference(ref);
                    }
                    statements.push(block);
                    statements.push(python.codeBlock("    pass"));
                } else {
                    statements.push(apiCallAst);
                }
            }

            // Verify request count using test ID for filtering
            // When testing the auth token endpoint itself, expect 2 requests:
            // 1. The automatic token fetch request (from OAuth/inferred auth)
            // 2. The actual API call being tested
            // For all other endpoints, expect 1 request (the auth token fetch goes to a different endpoint)
            const expectedRequestCount =
                this.isInferredAuthTokenEndpoint(endpoint) || this.isOAuthTokenEndpoint(endpoint) ? 2 : 1;
            statements.push(
                python.codeBlock(
                    `verify_request_count(test_id, "${endpoint.method}", "${basePath}", ${queryParamsCode}, ${expectedRequestCount})`
                )
            );

            const method = python.method({
                name: testName,
                return_: python.Type.none(),
                docstring: `Test ${endpoint.name.originalName} endpoint with WireMock`
            });

            statements.forEach((stmt) => method.addStatement(stmt));
            return method;
        } catch (error) {
            this.context.logger.warn(`Failed to generate test function for endpoint ${endpoint.id}: ${error}`);
            return null;
        }
    }

    /**
     * Checks if the IR has any inferred auth schemes.
     * When inferred auth is present, the client will make an additional request to get a token.
     */
    private hasInferredAuth(): boolean {
        if (!this.context.ir.auth?.schemes) {
            return false;
        }
        return this.context.ir.auth.schemes.some((scheme) => scheme.type === "inferred");
    }

    /**
     * Checks if an endpoint is the inferred auth token endpoint.
     * When testing the auth token endpoint with inferred auth, expect 2 requests:
     * 1. The automatic token fetch request
     * 2. The actual API call being tested
     */
    private isInferredAuthTokenEndpoint(endpoint: FernIr.HttpEndpoint): boolean {
        if (!this.context.ir.auth?.schemes) {
            return false;
        }
        for (const scheme of this.context.ir.auth.schemes) {
            if (scheme.type === "inferred") {
                const tokenEndpointId = scheme.tokenEndpoint.endpoint.endpointId;
                if (endpoint.id === tokenEndpointId) {
                    return true;
                }
            }
        }
        return false;
    }

    /**
     * Checks if an endpoint is the OAuth token endpoint.
     * When testing the token endpoint with OAuth client credentials, expect 2 requests:
     * 1. The automatic token fetch request (from the OAuth token provider)
     * 2. The actual API call being tested
     */
    private isOAuthTokenEndpoint(endpoint: FernIr.HttpEndpoint): boolean {
        if (!this.context.ir.auth?.schemes) {
            return false;
        }
        for (const scheme of this.context.ir.auth.schemes) {
            if (scheme.type === "oauth" && scheme.configuration?.type === "clientCredentials") {
                const tokenEndpointId = scheme.configuration.tokenEndpoint.endpointReference.endpointId;
                if (endpoint.id === tokenEndpointId) {
                    return true;
                }
            }
        }
        return false;
    }

    /**
     * Checks if an endpoint returns a streaming response.
     * Streaming endpoints return Iterator[bytes] or AsyncIterator[bytes] which are lazy generators.
     * This includes:
     * - streaming: SSE or other streaming responses
     * - streamParameter: Responses controlled by a stream parameter
     * - fileDownload: File download responses that return an iterator of bytes
     */
    private isStreamingEndpoint(endpoint: FernIr.HttpEndpoint): boolean {
        const responseBody = endpoint.response?.body;
        if (!responseBody) {
            return false;
        }
        return (
            responseBody.type === "streaming" ||
            responseBody.type === "streamParameter" ||
            responseBody.type === "fileDownload"
        );
    }

    /**
     * Builds a deterministic test ID based on the fully qualified service path.
     * Format: service.sub_service.endpoint_name.example_index
     * This ensures test IDs are unique per test and deterministic across regenerations.
     */
    private buildDeterministicTestId(
        service: FernIr.HttpService,
        endpoint: FernIr.HttpEndpoint,
        exampleIndex: number
    ): string {
        const servicePathParts = service.name.fernFilepath.allParts.map((part) => part.snakeCase.safeName);
        const endpointName = endpoint.name.snakeCase.safeName;

        const segments: string[] = [];
        if (servicePathParts.length > 0) {
            segments.push(servicePathParts.join("."));
        }
        segments.push(endpointName);
        segments.push(String(exampleIndex));

        // Example: "endpoints.primitive.get_and_return_string.0"
        return segments.join(".");
    }

    // =============================================================================
    // API CALL GENERATION
    // =============================================================================

    /**
     * Builds the path template for an endpoint in the format expected by the snippet generator.
     * Example: "/users/{userId}/posts/{postId}"
     */
    private buildPathTemplate(endpoint: FernIr.HttpEndpoint): string {
        let path = endpoint.fullPath.head;
        for (const part of endpoint.fullPath.parts) {
            path += `{${part.pathParameter}}${part.tail}`;
        }
        // Ensure the path starts with a leading slash to match FernIr.dynamic IR format
        if (!path.startsWith("/")) {
            path = "/" + path;
        }
        return path;
    }

    private generateApiCallAst(endpoint: FernIr.HttpEndpoint, example: WireTestExample): python.AstNode {
        try {
            // Build the snippet request
            const snippetRequest: DynamicFernIr.dynamic.EndpointSnippetRequest = {
                endpoint: {
                    method: endpoint.method,
                    path: this.buildPathTemplate(endpoint)
                },
                baseURL: "http://localhost:8080",
                pathParameters: example.pathParameters,
                queryParameters: example.queryParameters,
                headers: example.headers,
                requestBody: example.requestBody
            };

            // If this is a multipart/file-upload endpoint, static examples often omit file content.
            // However, generated Python client methods can require these file parameters. To keep
            // wire tests runnable and generic, synthesize placeholder file values for any required
            // file fields that are missing from the example request body.
            this.addPlaceholderFileUploadFields({ endpoint, snippetRequest });

            // Generate just the method call AST using DynamicSnippetsGenerator
            // Pass endpointId to avoid path collision issues when multiple
            // namespaces have endpoints with the same HTTP method and path pattern
            return this.snippetGenerator.generateMethodCallSnippetAst({
                request: snippetRequest,
                options: { endpointId: endpoint.id }
            });
        } catch (error) {
            // Fallback: log error and generate a placeholder
            this.context.logger.error(
                `Failed to generate API call for endpoint ${endpoint.name.originalName}: ${error}`
            );
            throw error;
        }
    }

    private addPlaceholderFileUploadFields({
        endpoint,
        snippetRequest
    }: {
        endpoint: FernIr.HttpEndpoint;
        snippetRequest: DynamicFernIr.dynamic.EndpointSnippetRequest;
    }): void {
        const requestBody = endpoint.requestBody;
        if (requestBody?.type !== "fileUpload" || !Array.isArray(requestBody.properties)) {
            return;
        }
        const record =
            typeof snippetRequest.requestBody === "object" && snippetRequest.requestBody != null
                ? (snippetRequest.requestBody as Record<string, unknown>)
                : {};
        for (const property of requestBody.properties) {
            if (property.type !== "file") {
                continue;
            }
            const fileValue = property.value;
            const key = fileValue.key;
            if (key.wireValue == null || fileValue.isOptional || record[key.wireValue] != null) {
                continue;
            }
            const placeholder = `example_${key.wireValue}`;
            record[key.wireValue] = fileValue.type === "fileArray" ? [placeholder] : placeholder;
        }
        snippetRequest.requestBody = record;
    }

    /**
     * Escapes a string for use in Python code.
     * Handles newlines, tabs, carriage returns, backslashes, and quotes.
     */
    private escapeStringForPython(value: string): string {
        return value
            .replace(/\\/g, "\\\\") // Escape backslashes first
            .replace(/\n/g, "\\n") // Escape newlines
            .replace(/\r/g, "\\r") // Escape carriage returns
            .replace(/\t/g, "\\t") // Escape tabs
            .replace(/"/g, '\\"'); // Escape double quotes
    }

    // =============================================================================
    // PATH AND QUERY PARAMETER HELPERS
    // =============================================================================

    /**
     * Checks if a query parameter is typed as datetime (DATE_TIME) in the IR.
     * Handles optional/nullable wrappers by unwrapping to the inner type.
     * String-typed parameters that happen to contain datetime-looking values return false.
     */
    private isDatetimeTypedQueryParam(endpoint: FernIr.HttpEndpoint, wireKey: string): boolean {
        const queryParam = endpoint.queryParameters.find((qp) => qp.name.wireValue === wireKey);
        if (!queryParam) {
            return false;
        }
        return this.isDatetimeTypeReference(queryParam.valueType);
    }

    /**
     * Recursively checks if a TypeReference resolves to a datetime primitive.
     * Unwraps optional/nullable containers to check the inner type.
     */
    private isDatetimeTypeReference(typeRef: FernIr.TypeReference): boolean {
        if (typeRef.type === "primitive") {
            return typeRef.primitive.v1 === "DATE_TIME";
        }
        if (typeRef.type === "container") {
            if (typeRef.container.type === "optional") {
                return this.isDatetimeTypeReference(typeRef.container.optional);
            }
            if (typeRef.container.type === "nullable") {
                return this.isDatetimeTypeReference(typeRef.container.nullable);
            }
        }
        return false;
    }

    /**
     * Normalizes a query parameter value for datetime_milliseconds config.
     * When datetime_milliseconds is true AND the parameter is datetime-typed, adds ".000" to
     * datetime values that lack fractional seconds so the test verification matches the SDK's
     * millisecond-precision output from serialize_datetime.
     * String-typed parameters are never normalized because the SDK passes them through as-is.
     */
    private normalizeDatetimeQueryParamValue(value: string, isDatetimeTyped: boolean): string {
        if (this.context.customConfig.datetime_milliseconds && isDatetimeTyped) {
            // Use replace with a capture group to insert ".000" before the timezone suffix.
            // The regex matches the seconds portion followed by the timezone (Z or +/-offset).
            return value.replace(/^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(Z|[+-]\d{2}:\d{2})$/, "$1.000$2");
        }
        return value;
    }

    private buildQueryParamsCode(endpoint: FernIr.HttpEndpoint): string {
        const dynamicEndpoint = this.dynamicIr.endpoints[endpoint.id];
        if (!dynamicEndpoint?.examples?.[0]?.queryParameters) {
            return "None";
        }

        const queryParams = dynamicEndpoint.examples[0].queryParameters;
        const entries: string[] = [];

        for (const [key, value] of Object.entries(queryParams)) {
            if (value != null) {
                const isDatetimeTyped = this.isDatetimeTypedQueryParam(endpoint, key);
                const normalized = this.normalizeDatetimeQueryParamValue(String(value), isDatetimeTyped);
                entries.push(`"${this.escapeStringForPython(key)}": "${this.escapeStringForPython(normalized)}"`);
            }
        }

        if (entries.length === 0) {
            return "None";
        }

        return `{${entries.join(", ")}}`;
    }

    // =============================================================================
    // UTILITY METHODS
    // =============================================================================

    private getTestFunctionName(serviceName: string, endpoint: FernIr.HttpEndpoint): string {
        const endpointName = endpoint.name.snakeCase.safeName;
        return `test_${serviceName}_${endpointName}`;
    }

    private getClientModulePath(): string[] {
        // The client is imported from the root package module
        // e.g., "from seed import SeedExhaustive" -> modulePath is ["seed"]
        return [this.context.getModulePath()];
    }

    private getClientClassName(): string {
        // The client class name follows the pattern: OrganizationWorkspace
        // For seed_exhaustive, it would be SeedExhaustive
        const orgName = this.context.config.organization;
        const workspaceName = this.context.config.workspaceName;

        // Convert to PascalCase
        const toPascalCase = (str: string) => {
            return str
                .split(/[-_]/)
                .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
                .join("");
        };

        return toPascalCase(orgName) + toPascalCase(workspaceName);
    }

    // =============================================================================
    // =============================================================================

    private wiremockMappingKey({
        requestMethod,
        requestUrlPathTemplate
    }: {
        requestMethod: string;
        requestUrlPathTemplate: string;
    }): string {
        return `${requestMethod} - ${requestUrlPathTemplate}`;
    }

    private getWireMockConfigContent(): Record<string, WireMockMapping> {
        const out: Record<string, WireMockMapping> = {};
        const wiremockStubMapping = WireTestSetupGenerator.getWiremockConfigContent(this.context.ir);
        for (const mapping of wiremockStubMapping.mappings) {
            const key = this.wiremockMappingKey({
                requestMethod: mapping.request.method,
                requestUrlPathTemplate: mapping.request.urlPathTemplate
            });
            out[key] = mapping;
        }
        return out;
    }

    // =============================================================================
    // =============================================================================

    private buildBasePath(endpoint: FernIr.HttpEndpoint): string {
        let basePath = endpoint.fullPath.head;
        for (const part of endpoint.fullPath.parts || []) {
            basePath += `{${part.pathParameter}}${part.tail}`;
        }
        if (!basePath.startsWith("/")) {
            basePath = "/" + basePath;
        }

        // Strip URL fragment - fragments are never sent to the server in HTTP requests
        // e.g., "/oauth2/token#refresh" -> "/oauth2/token"
        const fragmentIndex = basePath.indexOf("#");
        if (fragmentIndex !== -1) {
            basePath = basePath.substring(0, fragmentIndex);
        }

        // Substitute path parameters with actual values from WireMock mapping
        // Use the path WITHOUT fragment to look up the mapping, since mock-utils strips fragments
        const mappingKey = this.wiremockMappingKey({
            requestMethod: endpoint.method,
            requestUrlPathTemplate: basePath
        });

        const wiremockMapping = this.wireMockConfigContent[mappingKey];
        if (wiremockMapping && wiremockMapping.request.pathParameters) {
            Object.entries(wiremockMapping.request.pathParameters).forEach(([paramName, paramValue]) => {
                const pathParam = paramValue as { equalTo: string };
                basePath = basePath.replace(`{${paramName}}`, pathParam.equalTo);
            });
        }

        return basePath;
    }

    // =============================================================================
    // =============================================================================

    private groupEndpointsByService(): Map<string, FernIr.HttpEndpoint[]> {
        const endpointsByService = new Map<string, FernIr.HttpEndpoint[]>();

        for (const service of Object.values(this.context.ir.services)) {
            const serviceName = this.getFormattedServiceName(service);
            const endpoints = service.endpoints;

            if (endpoints.length > 0) {
                endpointsByService.set(serviceName, endpoints);
            }
        }

        return endpointsByService;
    }

    private getFormattedServiceName(service: FernIr.HttpService): string {
        return service.name.fernFilepath.allParts.map((part) => part.camelCase.unsafeName).join("_");
    }
}