Add x-glean-deprecated to Speakeasy deprecation format transformation

Transform x-glean-deprecated annotations in OpenAPI specs to Speakeasy-
compatible deprecation format. This enables Speakeasy SDK generation to
properly handle deprecated operations, parameters, and schema properties.

The transformation:
- Adds `deprecated: true` to elements with x-glean-deprecated
- Generates `x-speakeasy-deprecation-message` with format:
  "Deprecated on {introduced}, removal scheduled for {removal}: {message}"
- Preserves the original x-glean-deprecated annotation for internal tooling

Author: travis-hoover-glean

src/source-spec-transformer.js

@@ -256,6 +256,46 @@ export function transformEnumDescriptions(spec) {
   return spec;
 }
 
+/**
+ * Transforms x-glean-deprecated annotations to Speakeasy-compatible deprecation format
+ * Adds deprecated: true and x-speakeasy-deprecation-message fields while preserving the original annotation
+ * @param {Object} spec The OpenAPI spec object
+ * @returns {Object} Transformed spec object
+ */
+export function transformGleanDeprecated(spec) {
+  const processObject = (obj) => {
+    if (!obj || typeof obj !== 'object') return;
+
+    // Process arrays
+    if (Array.isArray(obj)) {
+      obj.forEach(processObject);
+      return;
+    }
+
+    // Check if this object has x-glean-deprecated
+    if (obj['x-glean-deprecated']) {
+      const deprecation = obj['x-glean-deprecated'];
+
+      // Add deprecated: true
+      obj.deprecated = true;
+
+      // Build the deprecation message with dates
+      const message = `Deprecated on ${deprecation.introduced}, removal scheduled for ${deprecation.removal}${deprecation.message ? `: ${deprecation.message}` : ''}`;
+      obj['x-speakeasy-deprecation-message'] = message;
+    }
+
+    // Recursively process all properties
+    Object.values(obj).forEach((value) => {
+      if (value && typeof value === 'object') {
+        processObject(value);
+      }
+    });
+  };
+
+  processObject(spec);
+  return spec;
+}
+
 /**
  * Injects the open-api repository commit SHA into the spec info section
  * @param {Object} spec The OpenAPI spec object
@@ -334,6 +374,9 @@ export function transform(content, filename, commitSha) {
   // Apply x-enumDescriptions -> x-speakeasy-enum-descriptions transformation for all files
   transformEnumDescriptions(spec);
 
+  // Apply x-glean-deprecated -> Speakeasy deprecation format transformation for all files
+  transformGleanDeprecated(spec);
+
   // Apply admin duplicate operationId fix
   if (filename === 'admin_rest.yaml') {
     transformActAsBearerTokenToAPIToken(spec);

tests/source-spec-transformer.test.js

@@ -9,6 +9,7 @@ import {
   transformBearerAuthToAPIToken,
   transformServerVariables,
   transformEnumDescriptions,
+  transformGleanDeprecated,
   injectOpenApiCommitSha,
 } from '../src/source-spec-transformer.js';
 
@@ -423,4 +424,193 @@ describe('OpenAPI YAML Transformer', () => {
 
     expect(transformedSpec.info['x-open-api-commit-sha']).toBeUndefined();
   });
+
+  test('transformGleanDeprecated adds Speakeasy deprecation fields to operations', () => {
+    const testSpec = {
+      paths: {
+        '/test': {
+          get: {
+            operationId: 'getTest',
+            'x-glean-deprecated': {
+              id: 'uuid-123',
+              message: 'Use /v2/test instead',
+              introduced: '2024-01-15',
+              removal: '2024-07-15',
+            },
+          },
+        },
+      },
+    };
+
+    const transformedSpec = transformGleanDeprecated(testSpec);
+
+    expect(transformedSpec.paths['/test'].get.deprecated).toBe(true);
+    expect(
+      transformedSpec.paths['/test'].get['x-speakeasy-deprecation-message'],
+    ).toBe(
+      'Deprecated on 2024-01-15, removal scheduled for 2024-07-15: Use /v2/test instead',
+    );
+    // Verify original annotation is preserved
+    expect(
+      transformedSpec.paths['/test'].get['x-glean-deprecated'],
+    ).toBeDefined();
+    expect(transformedSpec.paths['/test'].get['x-glean-deprecated'].id).toBe(
+      'uuid-123',
+    );
+  });
+
+  test('transformGleanDeprecated adds Speakeasy deprecation fields to parameters', () => {
+    const testSpec = {
+      paths: {
+        '/test': {
+          get: {
+            parameters: [
+              {
+                name: 'oldParam',
+                in: 'query',
+                'x-glean-deprecated': {
+                  id: 'param-uuid',
+                  message: 'Use newParam instead',
+                  introduced: '2024-02-01',
+                  removal: '2024-08-01',
+                },
+              },
+            ],
+          },
+        },
+      },
+    };
+
+    const transformedSpec = transformGleanDeprecated(testSpec);
+
+    const param = transformedSpec.paths['/test'].get.parameters[0];
+    expect(param.deprecated).toBe(true);
+    expect(param['x-speakeasy-deprecation-message']).toBe(
+      'Deprecated on 2024-02-01, removal scheduled for 2024-08-01: Use newParam instead',
+    );
+    expect(param['x-glean-deprecated']).toBeDefined();
+  });
+
+  test('transformGleanDeprecated adds Speakeasy deprecation fields to schema properties', () => {
+    const testSpec = {
+      components: {
+        schemas: {
+          TestSchema: {
+            type: 'object',
+            properties: {
+              oldField: {
+                type: 'string',
+                'x-glean-deprecated': {
+                  id: 'schema-uuid',
+                  message: 'Field renamed to newField',
+                  introduced: '2024-03-01',
+                  removal: '2024-09-01',
+                  docs: 'https://docs.example.com/migration',
+                },
+              },
+              newField: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const transformedSpec = transformGleanDeprecated(testSpec);
+
+    const oldField =
+      transformedSpec.components.schemas.TestSchema.properties.oldField;
+    expect(oldField.deprecated).toBe(true);
+    expect(oldField['x-speakeasy-deprecation-message']).toBe(
+      'Deprecated on 2024-03-01, removal scheduled for 2024-09-01: Field renamed to newField',
+    );
+    expect(oldField['x-glean-deprecated']).toBeDefined();
+    expect(oldField['x-glean-deprecated'].docs).toBe(
+      'https://docs.example.com/migration',
+    );
+
+    // Verify non-deprecated field is unchanged
+    const newField =
+      transformedSpec.components.schemas.TestSchema.properties.newField;
+    expect(newField.deprecated).toBeUndefined();
+    expect(newField['x-speakeasy-deprecation-message']).toBeUndefined();
+  });
+
+  test('transformGleanDeprecated handles specs without x-glean-deprecated', () => {
+    const testSpec = {
+      paths: {
+        '/test': {
+          get: {
+            operationId: 'getTest',
+            summary: 'Test endpoint',
+          },
+        },
+      },
+      components: {
+        schemas: {
+          TestSchema: {
+            type: 'object',
+            properties: {
+              field: {
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const transformedSpec = transformGleanDeprecated(testSpec);
+
+    // Verify no deprecated fields were added
+    expect(transformedSpec.paths['/test'].get.deprecated).toBeUndefined();
+    expect(
+      transformedSpec.paths['/test'].get['x-speakeasy-deprecation-message'],
+    ).toBeUndefined();
+    expect(
+      transformedSpec.components.schemas.TestSchema.properties.field.deprecated,
+    ).toBeUndefined();
+  });
+
+  test('transformGleanDeprecated handles nested deprecations', () => {
+    const testSpec = {
+      paths: {
+        '/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: {
+                    properties: {
+                      deprecatedField: {
+                        type: 'string',
+                        'x-glean-deprecated': {
+                          id: 'nested-uuid',
+                          message: 'This field is deprecated',
+                          introduced: '2024-04-01',
+                          removal: '2024-10-01',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const transformedSpec = transformGleanDeprecated(testSpec);
+
+    const deprecatedField =
+      transformedSpec.paths['/test'].post.requestBody.content[
+        'application/json'
+      ].schema.properties.deprecatedField;
+    expect(deprecatedField.deprecated).toBe(true);
+    expect(deprecatedField['x-speakeasy-deprecation-message']).toBe(
+      'Deprecated on 2024-04-01, removal scheduled for 2024-10-01: This field is deprecated',
+    );
+  });
 });