fix(open-api): hoist composite parameter schemas to components.schemas

FastAPI / Pydantic v2 encode `Optional[T]` parameters as inline composite
schemas on the parameter (e.g.
`{anyOf: [{type: string}, {type: null}], title: 'X-Client'}`).  The
hoisting pass walked request/response JSON schemas but not parameter
schemas, so hey-api-openapi synthesised an anonymous composite named
from the title (`XClient`, `Session`, …) without emitting a
declaration, and every generated FastAPI client failed to compile:

    types.gen.ts: Cannot find name 'XClient'
    pyright:      '"Session" is not defined'

Extends the existing hoist to also move composite parameter schemas
into `components.schemas` under `<OpId>Request<In><Name>`.

Author: nx-plugin-for-aws

packages/nx-plugin/src/open-api/ts-client/generator.fast-api.spec.ts

@@ -975,4 +975,94 @@ describe('openApiTsClientGenerator - FastAPI', () => {
       ],
     });
   });
+
+  it('should hoist inline composite parameter schemas so FastAPI `Optional[T]` params compile', async () => {
+    // Regression: FastAPI / Pydantic v2 encode `Optional[T]` params as
+    // `{anyOf: [T, {type: 'null'}], title: '<name>'}` inline on the
+    // parameter.  hey-api used to derive a type name from the title
+    // (e.g. `XClient`, `Session`, `Tag`) but no declaration was emitted,
+    // so the generated client failed to compile with:
+    //
+    //   types.gen.ts: Cannot find name 'XClient'
+    //   client.gen.ts: Property 'XClient' does not exist on type '$IO'
+    //
+    // Existing parameter tests covered primitive schemas (`{type: string}`)
+    // and the composite tests covered `components.schemas.*` — both of
+    // which were hoisted.  Composite parameter-level schemas were the
+    // uncovered gap.
+    const spec: Spec = {
+      openapi: '3.1.0',
+      info: { title, version: '1.0.0' },
+      paths: {
+        '/pets/{petId}': {
+          get: {
+            operationId: 'getPet',
+            parameters: [
+              {
+                name: 'petId',
+                in: 'path',
+                required: true,
+                schema: { type: 'integer' },
+              },
+              {
+                name: 'X-Client',
+                in: 'header',
+                schema: {
+                  anyOf: [{ type: 'string' }, { type: 'null' }],
+                  title: 'X-Client',
+                } as any,
+              },
+              {
+                name: 'session',
+                in: 'cookie',
+                schema: {
+                  anyOf: [{ type: 'string' }, { type: 'null' }],
+                  title: 'Session',
+                } as any,
+              },
+              {
+                name: 'tag',
+                in: 'query',
+                schema: {
+                  anyOf: [
+                    { type: 'array', items: { type: 'string' } },
+                    { type: 'null' },
+                  ],
+                  title: 'Tag',
+                } as any,
+              },
+            ],
+            responses: {
+              '200': {
+                description: 'ok',
+                content: {
+                  'application/json': { schema: { type: 'string' } },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    tree.write('openapi.json', JSON.stringify(spec));
+    await openApiTsClientGenerator(tree, {
+      openApiSpecPath: 'openapi.json',
+      outputPath: 'src/generated',
+    });
+
+    // Must actually compile (the phantom composites used to break tsc).
+    validateTypeScript([
+      'src/generated/client.gen.ts',
+      'src/generated/types.gen.ts',
+    ]);
+
+    const types = tree.read('src/generated/types.gen.ts', 'utf-8')!;
+    // The hoisted composite schemas get operation-scoped names.
+    expect(types).toMatch(/GetPetRequestHeaderXClient\s*=\s*string \| null/);
+    expect(types).toMatch(/GetPetRequestCookieSession\s*=\s*string \| null/);
+    expect(types).toMatch(/GetPetRequestQueryTag\s*=\s*Array<string> \| null/);
+    expect(types).toContain('xClient?: GetPetRequestHeaderXClient');
+    expect(types).toContain('session?: GetPetRequestCookieSession');
+    expect(types).toContain('tag?: GetPetRequestQueryTag');
+  });
 });

packages/nx-plugin/src/open-api/utils/normalise.ts

@@ -389,6 +389,21 @@ export const normaliseOpenApiSpecForCodeGen = (inSpec: Spec): Spec => {
             };
           }
         }
+
+        // Hoist parameter schemas
+        (operation.parameters ?? []).forEach((p) => {
+          const param = resolveIfRef(spec, p);
+          const paramSchema = param?.schema;
+          if (
+            paramSchema &&
+            !isRef(paramSchema) &&
+            isCompositeSchema(paramSchema as OpenAPIV3.SchemaObject)
+          ) {
+            const schemaName = `${upperFirst(deduplicatedOpId)}Request${upperFirst(param.in)}${upperFirst(camelCase(param.name))}`;
+            spec.components!.schemas![schemaName] = paramSchema;
+            param.schema = { $ref: `#/components/schemas/${schemaName}` };
+          }
+        });
       }
     }),
   );