@workos/oagen-emitters 0.2.1 → 0.4.0

package/test/python/models.test.ts

@@ -0,0 +1,716 @@
+import { describe, it, expect } from 'vitest';
+import { generateModels } from '../../src/python/models.js';
+import type { EmitterContext, ApiSpec, Model, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+
+const emptySpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: '',
+  services: [],
+  models: [],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec: emptySpec,
+};
+
+describe('generateModels', () => {
+  it('returns empty for no models', () => {
+    expect(generateModels([], ctx)).toEqual([]);
+  });
+
+  it('generates a dataclass for a model', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [
+            {
+              name: 'id',
+              type: { kind: 'primitive', type: 'string' },
+              required: true,
+            },
+          ],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'created_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+          },
+          {
+            name: 'external_id',
+            type: {
+              kind: 'nullable',
+              inner: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    // Model file + barrel __init__.py (parent __init__.py is generated by generateServiceInits)
+    expect(files.length).toBe(2);
+
+    const modelFile = files.find((f) => f.path === 'src/workos/organizations/models/organization.py')!;
+    expect(modelFile).toBeDefined();
+
+    // Has dataclass decorator
+    expect(modelFile.content).toContain('@dataclass(slots=True)');
+    expect(modelFile.content).toContain('class Organization:');
+
+    // Required fields
+    expect(modelFile.content).toContain('    id: str');
+    expect(modelFile.content).toContain('    name: str');
+    expect(modelFile.content).toContain('from datetime import datetime');
+    expect(modelFile.content).toContain('    created_at: datetime');
+
+    // Optional/nullable field
+    expect(modelFile.content).toContain('    external_id: Optional[str] = None');
+
+    // from_dict method
+    expect(modelFile.content).toContain('def from_dict(cls, data: Dict[str, Any])');
+    expect(modelFile.content).toContain('_parse_datetime(data["created_at"])');
+    expect(modelFile.content).toContain('_raise_deserialize_error("Organization", e)');
+    expect(modelFile.content).toContain('from workos._types import _raise_deserialize_error');
+
+    // to_dict method
+    expect(modelFile.content).toContain('def to_dict(self) -> Dict[str, Any]:');
+    expect(modelFile.content).toContain('result["created_at"] = _format_datetime(self.created_at)');
+    expect(modelFile.content).toContain('from workos._types import _format_datetime, _parse_datetime');
+    expect(modelFile.content).toContain('result["external_id"] = None');
+  });
+
+  it('handles array fields with model refs', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'domains',
+            type: {
+              kind: 'array',
+              items: { kind: 'model', name: 'OrganizationDomain' },
+            },
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'OrganizationDomain',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'domain',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    // 2 model files + 1 barrel __init__.py (parent __init__.py is generated by generateServiceInits)
+    expect(files.length).toBe(3);
+
+    const orgFile = files.find((f) => f.path.includes('organization.py') && !f.path.includes('organization_domain'));
+    expect(orgFile).toBeDefined();
+    expect(orgFile!.content).toContain('domains: List["OrganizationDomain"]');
+    expect(orgFile!.content).toContain('OrganizationDomain.from_dict(cast(Dict[str, Any], item))');
+    expect(orgFile!.content).not.toContain('or []');
+  });
+
+  it('omits optional non-nullable fields and preserves required nullable fields in to_dict', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          {
+            name: 'nickname',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+          },
+          {
+            name: 'external_id',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const files = generateModels(models, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    });
+    const modelFile = files.find((f) => f.path === 'src/workos/organizations/models/organization.py')!;
+    expect(modelFile.content).toContain('if self.nickname is not None:');
+    expect(modelFile.content).not.toContain('result["nickname"] = None');
+    expect(modelFile.content).toContain('result["external_id"] = None');
+  });
+
+  it('skips list wrapper and list metadata models', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'listOrganizations',
+          httpMethod: 'get',
+          path: '/organizations',
+          pathParams: [],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'OrganizationList' },
+          errors: [],
+          injectIdempotencyKey: false,
+          pagination: {
+            strategy: 'cursor',
+            param: 'after',
+            dataPath: 'data',
+            itemType: { kind: 'model', name: 'Organization' },
+          },
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'OrganizationList',
+        fields: [
+          {
+            name: 'data',
+            type: { kind: 'array', items: { kind: 'model', name: 'Organization' } },
+            required: true,
+          },
+          {
+            name: 'list_metadata',
+            type: { kind: 'model', name: 'ListMetadata' },
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'ListMetadata',
+        fields: [
+          { name: 'before', type: { kind: 'primitive', type: 'string' }, required: false },
+          { name: 'after', type: { kind: 'primitive', type: 'string' }, required: false },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    const filePaths = files.map((f) => f.path);
+
+    // Should generate Organization but NOT OrganizationList or ListMetadata
+    expect(filePaths.some((p) => p.includes('organization.py'))).toBe(true);
+    expect(filePaths.some((p) => p.includes('organization_list.py'))).toBe(false);
+    expect(filePaths.some((p) => p.includes('list_metadata.py'))).toBe(false);
+
+    // Barrel should not export the skipped models
+    const barrel = files.find((f) => f.path.endsWith('__init__.py') && f.path.includes('models/'));
+    expect(barrel).toBeDefined();
+    expect(barrel!.content).not.toContain('OrganizationList');
+    expect(barrel!.content).not.toContain('ListMetadata');
+  });
+
+  it('generates type alias for structurally identical models', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'OrganizationDomain' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'OrganizationDomain',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'domain', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+      {
+        name: 'OrganizationDomainStandAlone',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'domain', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+
+    // Canonical model should have a full dataclass
+    const canonicalFile = files.find(
+      (f) => f.path.includes('organization_domain.py') && !f.path.includes('stand_alone'),
+    )!;
+    expect(canonicalFile).toBeDefined();
+    expect(canonicalFile.content).toContain('@dataclass');
+    expect(canonicalFile.content).toContain('class OrganizationDomain:');
+
+    // Alias model should be a type alias
+    const aliasFile = files.find((f) => f.path.includes('organization_domain_stand_alone.py'))!;
+    expect(aliasFile).toBeDefined();
+    expect(aliasFile.content).toContain('OrganizationDomainStandAlone: TypeAlias = OrganizationDomain');
+    expect(aliasFile.content).not.toContain('@dataclass');
+  });
+
+  it('does not alias response models to request-only dto models', () => {
+    const service: Service = {
+      name: 'Pipes',
+      operations: [
+        {
+          name: 'getUserlandUserToken',
+          httpMethod: 'post',
+          path: '/data-integrations/{slug}/token',
+          pathParams: [{ name: 'slug', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          requestBody: { kind: 'model', name: 'CreateApplicationSecret' },
+          response: { kind: 'model', name: 'DataIntegrationAccessTokenResponse' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'CreateApplicationSecret',
+        fields: [{ name: 'access_token', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'DataIntegrationAccessTokenResponse',
+        fields: [{ name: 'access_token', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+    ];
+
+    const files = generateModels(models, { ...ctx, spec: { ...emptySpec, services: [service], models } });
+    const responseFile = files.find((f) => f.path.includes('data_integration_access_token_response.py'))!;
+    expect(responseFile.content).toContain('@dataclass(slots=True)');
+    expect(responseFile.content).not.toContain('= CreateApplicationSecret');
+    // Dto stripping now happens at IR level (schemaNameTransform in oagen.config.ts),
+    // so model names arrive at the emitter already stripped
+    const dtoFile = files.find((f) => f.path.includes('create_application_secret.py'));
+    expect(dtoFile).toBeDefined();
+    expect(dtoFile!.content).toContain('class CreateApplicationSecret:');
+    expect(files.every((f) => !f.path.includes('_dto'))).toBe(true);
+  });
+
+  it('treats deprecated or baseline-optional fields as optional', () => {
+    const service: Service = {
+      name: 'Events',
+      operations: [
+        {
+          name: 'getOrganizationEvent',
+          httpMethod: 'get',
+          path: '/events/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'OrganizationEvent' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'OrganizationEvent',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          {
+            name: 'allow_profiles_outside_organization',
+            type: { kind: 'primitive', type: 'boolean' },
+            required: true,
+            deprecated: true,
+          },
+        ],
+      },
+    ];
+
+    const files = generateModels(models, { ...ctx, spec: { ...emptySpec, services: [service], models } });
+    const eventFile = files.find((f) => f.path.includes('organization_event.py'))!;
+    expect(eventFile.content).toContain('allow_profiles_outside_organization: Optional[bool] = None');
+    expect(eventFile.content).toContain('data.get("allow_profiles_outside_organization")');
+  });
+
+  it('handles union fields with identical model variants in from_dict', () => {
+    const service: Service = {
+      name: 'Auth',
+      operations: [
+        {
+          name: 'getFactor',
+          httpMethod: 'get',
+          path: '/auth/factors/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'AuthenticationFactor' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'AuthenticationFactor',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          {
+            name: 'totp',
+            type: {
+              kind: 'union',
+              variants: [
+                { kind: 'model', name: 'AuthenticationFactorTotp' },
+                { kind: 'model', name: 'AuthenticationFactorTotp' },
+              ],
+            },
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'AuthenticationFactorTotp',
+        fields: [
+          { name: 'issuer', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'user', type: { kind: 'primitive', type: 'string' }, required: true },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    const factorFile = files.find((f) => f.path.includes('authentication_factor.py') && !f.path.includes('totp'))!;
+    expect(factorFile).toBeDefined();
+
+    // Union of identical model refs should collapse in from_dict
+    expect(factorFile.content).toContain('AuthenticationFactorTotp.from_dict');
+    // Type annotation should be collapsed (no Union[Foo, Foo])
+    expect(factorFile.content).toContain('Optional["AuthenticationFactorTotp"]');
+    expect(factorFile.content).not.toContain('Union["AuthenticationFactorTotp", "AuthenticationFactorTotp"]');
+  });
+
+  it('handles map fields', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+          {
+            name: 'metadata',
+            type: {
+              kind: 'map',
+              valueType: { kind: 'primitive', type: 'string' },
+            },
+            required: false,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    // 1 model file + 1 barrel __init__.py (parent __init__.py is generated by generateServiceInits)
+    expect(files.length).toBe(2);
+    const modelFile = files.find((f) => f.path.endsWith('organization.py'))!;
+    expect(modelFile.content).toContain('metadata: Optional[Dict[str, str]] = None');
+  });
+
+  it('adds .. deprecated:: docstring for deprecated fields', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          {
+            name: 'old_field',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            deprecated: true,
+            description: 'Legacy field',
+          },
+          {
+            name: 'old_no_desc',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+            deprecated: true,
+          },
+        ],
+      },
+    ];
+
+    const files = generateModels(models, {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    });
+    const modelFile = files.find((f) => f.path.includes('organization.py'))!;
+
+    // Deprecated required field with description gets both description and .. deprecated::
+    expect(modelFile.content).toContain('"""Legacy field\n\n    .. deprecated:: This field is deprecated."""');
+
+    // Deprecated optional field without description gets just .. deprecated::
+    expect(modelFile.content).toContain('""".. deprecated:: This field is deprecated."""');
+  });
+
+  it('deduplicates models with recursively identical sub-model references', () => {
+    const service: Service = {
+      name: 'Events',
+      operations: [
+        {
+          name: 'listEvents',
+          httpMethod: 'get',
+          path: '/events',
+          pathParams: [],
+          queryParams: [],
+          headerParams: [],
+          response: {
+            kind: 'union',
+            variants: [
+              { kind: 'model', name: 'EventA' },
+              { kind: 'model', name: 'EventB' },
+            ],
+          },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'EventA',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'event', type: { kind: 'literal', value: 'event_a' }, required: true },
+          { name: 'context', type: { kind: 'model', name: 'EventAContext' }, required: false },
+        ],
+      },
+      {
+        name: 'EventAContext',
+        fields: [
+          { name: 'actor_id', type: { kind: 'primitive', type: 'string' }, required: false },
+          { name: 'detail', type: { kind: 'model', name: 'EventAContextDetail' }, required: false },
+        ],
+      },
+      {
+        name: 'EventAContextDetail',
+        fields: [{ name: 'ip', type: { kind: 'primitive', type: 'string' }, required: false }],
+      },
+      {
+        name: 'EventB',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'event', type: { kind: 'literal', value: 'event_b' }, required: true },
+          { name: 'context', type: { kind: 'model', name: 'EventBContext' }, required: false },
+        ],
+      },
+      {
+        name: 'EventBContext',
+        fields: [
+          { name: 'actor_id', type: { kind: 'primitive', type: 'string' }, required: false },
+          { name: 'detail', type: { kind: 'model', name: 'EventBContextDetail' }, required: false },
+        ],
+      },
+      {
+        name: 'EventBContextDetail',
+        fields: [{ name: 'ip', type: { kind: 'primitive', type: 'string' }, required: false }],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+
+    // Top-level events differ (different literal values) → both get full dataclasses
+    const eventAFile = files.find((f) => f.path.includes('/event_a.py'))!;
+    expect(eventAFile).toBeDefined();
+    expect(eventAFile.content).toContain('@dataclass');
+    expect(eventAFile.content).toContain('class EventA:');
+
+    const eventBFile = files.find((f) => f.path.includes('/event_b.py'))!;
+    expect(eventBFile).toBeDefined();
+    expect(eventBFile.content).toContain('@dataclass');
+    expect(eventBFile.content).toContain('class EventB:');
+
+    // Leaf models are structurally identical → one canonical, one alias
+    const detailAFile = files.find((f) => f.path.includes('event_a_context_detail.py'))!;
+    expect(detailAFile).toBeDefined();
+    expect(detailAFile.content).toContain('@dataclass');
+
+    const detailBFile = files.find((f) => f.path.includes('event_b_context_detail.py'))!;
+    expect(detailBFile).toBeDefined();
+    expect(detailBFile.content).toContain('TypeAlias');
+    expect(detailBFile.content).not.toContain('@dataclass');
+
+    // Context models reference recursively-identical sub-models → also deduplicated
+    const contextAFile = files.find((f) => f.path.includes('/event_a_context.py'))!;
+    expect(contextAFile).toBeDefined();
+    expect(contextAFile.content).toContain('@dataclass');
+
+    const contextBFile = files.find((f) => f.path.includes('/event_b_context.py'))!;
+    expect(contextBFile).toBeDefined();
+    expect(contextBFile.content).toContain('TypeAlias');
+    expect(contextBFile.content).not.toContain('@dataclass');
+  });
+});