Merge pull request #223 from abraham/copilot/fix-222

[WIP] Strip complex types from property descriptions

Author: abraham

dist/schema.json

@@ -5120,7 +5120,7 @@
                       "type": "string",
                       "format": "uri"
                     },
-                    "description": "String or Array of Strings. Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter."
+                    "description": "Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter."
                   },
                   "scopes": {
                     "type": "string",

src/__tests__/generators/OpenAPIGenerator.complex.test.ts

@@ -28,8 +28,7 @@ describe('OpenAPIGenerator Complex Parameters', () => {
 
       expect(schema).toEqual({
         type: 'array',
-        description:
-          'Array of String. Include Attachment IDs to be attached as media.',
+        description: 'Include Attachment IDs to be attached as media.',
         items: {
           type: 'string',
         },
@@ -103,7 +102,7 @@ describe('OpenAPIGenerator Complex Parameters', () => {
 
       expect(schema).toEqual({
         type: 'string',
-        description: 'String. The text content of the status.',
+        description: 'The text content of the status.',
         enum: ['public', 'unlisted', 'private'],
       });
     });
@@ -119,7 +118,7 @@ describe('OpenAPIGenerator Complex Parameters', () => {
 
       expect(schema).toEqual({
         type: 'string',
-        description: 'String. ID of the status being replied to.',
+        description: 'ID of the status being replied to.',
       });
     });
   });

src/__tests__/generators/TypeParser.email-format.test.ts

@@ -91,7 +91,7 @@ describe('TypeParser - Email format detection', () => {
       expect(result).toEqual({
         type: 'string',
         format: 'email',
-        description: 'String. The user email address',
+        description: 'The user email address',
       });
     });
 
@@ -107,7 +107,7 @@ describe('TypeParser - Email format detection', () => {
       expect(result).toEqual({
         type: 'string',
         format: 'email',
-        description: 'String. The user e-mail address',
+        description: 'The user e-mail address',
       });
     });
 
@@ -122,7 +122,7 @@ describe('TypeParser - Email format detection', () => {
       const result = typeParser.convertParameterToSchema(param);
       expect(result).toEqual({
         type: 'string',
-        description: 'Boolean. Whether to send a confirmation email',
+        description: 'Whether to send a confirmation email',
       });
       expect(result.format).toBeUndefined();
     });
@@ -138,7 +138,7 @@ describe('TypeParser - Email format detection', () => {
       const result = typeParser.convertParameterToSchema(param);
       expect(result).toEqual({
         type: 'string',
-        description: 'String. The email that will be sent for notifications',
+        description: 'The email that will be sent for notifications',
       });
       expect(result.format).toBeUndefined();
     });
@@ -155,7 +155,7 @@ describe('TypeParser - Email format detection', () => {
       expect(result).toEqual({
         type: 'string',
         format: 'email',
-        description: 'String. The user email for contact',
+        description: 'The user email for contact',
       });
     });
 

src/__tests__/generators/TypeParser.enum-fix.test.ts

@@ -25,7 +25,9 @@ describe('TypeParser Enum Values Fix', () => {
     const schema = typeParser.convertParameterToSchema(parameter);
 
     expect(schema.type).toBe('string');
-    expect(schema.description).toBe(parameter.description);
+    expect(schema.description).toBe(
+      'Sets the visibility of the posted status to `public`, `unlisted`, `private`, `direct`.'
+    );
     expect(schema.enum).toEqual(['public', 'unlisted', 'private', 'direct']);
   });
 
@@ -47,7 +49,7 @@ describe('TypeParser Enum Values Fix', () => {
     const schema = typeParser.convertParameterToSchema(parameter);
 
     expect(schema.type).toBe('array');
-    expect(schema.description).toBe(parameter.description);
+    expect(schema.description).toBe('Array of notification types');
     // Array properties should NOT have enum on the array itself, only on items
     expect(schema.enum).toBeUndefined();
     expect(schema.items).toBeDefined();
@@ -68,7 +70,9 @@ describe('TypeParser Enum Values Fix', () => {
     const schema = typeParser.convertParameterToSchema(parameter);
 
     expect(schema.type).toBe('string');
-    expect(schema.description).toBe(parameter.description);
+    expect(schema.description).toBe(
+      'Sets the visibility of the posted status to `public`, `unlisted`, `private`, `direct`.'
+    );
     expect(schema.enum).toEqual(['public', 'unlisted', 'private', 'direct']);
   });
 
@@ -86,7 +90,7 @@ describe('TypeParser Enum Values Fix', () => {
     const schema = typeParser.convertParameterToSchema(parameter);
 
     expect(schema.type).toBe('string');
-    expect(schema.description).toBe(parameter.description);
+    expect(schema.description).toBe('The text content of the status.');
     expect(schema.enum).toBeUndefined();
   });
 });

src/__tests__/generators/TypeParser.redirect-uris-oneof.test.ts

@@ -23,7 +23,7 @@ describe('TypeParser - redirect_uris oneOf pattern', () => {
 
     expect(schema).toEqual({
       description:
-        'String or Array of Strings. Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter.',
+        'Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter.',
       oneOf: [
         {
           type: 'string',
@@ -50,7 +50,7 @@ describe('TypeParser - redirect_uris oneOf pattern', () => {
     const schema = typeParser.convertParameterToSchema(parameter);
 
     expect(schema).toEqual({
-      description: 'String or Array of String. Test parameter description.',
+      description: 'Test parameter description.',
       oneOf: [
         {
           type: 'string',
@@ -100,7 +100,7 @@ describe('TypeParser - redirect_uris oneOf pattern', () => {
 
     expect(schema).toEqual({
       type: 'string',
-      description: 'String. A name for your application',
+      description: 'A name for your application',
     });
   });
 
@@ -115,7 +115,7 @@ describe('TypeParser - redirect_uris oneOf pattern', () => {
 
     expect(schema).toEqual({
       type: 'string',
-      description: 'Array of String. List of scopes.',
+      description: 'List of scopes.',
     });
   });
 });

src/__tests__/integration/create-app-parameters.test.ts

@@ -91,7 +91,7 @@ describe('Create App Method Parameters', () => {
 
     expect(redirectUrisParam).toBeDefined();
     expect(redirectUrisParam!.description).toContain(
-      'String or Array of Strings'
+      'Where the user should be redirected after authorization'
     );
 
     // Convert parameter to schema using TypeParser

src/__tests__/integration/create-app-redirect-uris-override.test.ts

@@ -42,7 +42,7 @@ describe('CreateApp redirect_uris override', () => {
 
     // Verify the description is preserved
     expect(redirectUrisProperty.description).toContain(
-      'String or Array of Strings'
+      'Where the user should be redirected after authorization'
     );
   });
 });

src/__tests__/parsers/EntityParsingUtils.cleanDescription.test.ts

@@ -186,6 +186,39 @@ describe('EntityParsingUtils.cleanDescription - Type Stripping', () => {
     });
   });
 
+  test('should remove "String or Array of..." type prefixes from descriptions', () => {
+    // Test the specific patterns mentioned in the issue
+    const testCases = [
+      {
+        input:
+          'String or Array of Strings. Where the user should be redirected after authorization.',
+        expected: 'Where the user should be redirected after authorization.',
+      },
+      {
+        input: 'String or Array of String. Test parameter description.',
+        expected: 'Test parameter description.',
+      },
+      {
+        input:
+          'String or Array of String (URLs). Where the user should be redirected.',
+        expected: 'Where the user should be redirected.',
+      },
+      {
+        input: 'string or array of strings. Include attachment IDs.',
+        expected: 'Include attachment IDs.',
+      },
+      {
+        input: 'STRING OR ARRAY OF STRING. List of values.',
+        expected: 'List of values.',
+      },
+    ];
+
+    testCases.forEach(({ input, expected }) => {
+      const result = EntityParsingUtils.cleanDescription(input);
+      expect(result).toBe(expected);
+    });
+  });
+
   test('should not strip complex type words that are not prefixes', () => {
     const testCases = [
       {

src/generators/TypeParser.ts

@@ -1,6 +1,7 @@
 import { ApiParameter } from '../interfaces/ApiParameter';
 import { HashAttribute } from '../interfaces/ApiMethod';
 import { OpenAPIProperty, OpenAPISpec } from '../interfaces/OpenAPISchema';
+import { EntityParsingUtils } from '../parsers/EntityParsingUtils';
 import { UtilityHelpers } from './UtilityHelpers';
 
 /**
@@ -276,12 +277,19 @@ class TypeParser {
    */
   public convertParameterToSchema(param: ApiParameter): OpenAPIProperty {
     // Check for "String or Array of Strings" pattern to generate oneOf schema
+    // Also check for redirect_uris parameter specifically, which often has this pattern
     if (param.description) {
       const stringOrArrayPattern = /string\s+or\s+array\s+of\s+strings?/i.test(
         param.description
       );
 
-      if (stringOrArrayPattern) {
+      // Special case for redirect_uris parameter - it's commonly "String or Array of Strings"
+      // even if the type prefix has been stripped
+      const isRedirectUrisParameter =
+        param.name.toLowerCase() === 'redirect_uris' &&
+        param.description.toLowerCase().includes('redirect');
+
+      if (stringOrArrayPattern || isRedirectUrisParameter) {
         // Detect if URIs are involved for format specification
         const hasUriIndicator =
           param.name.toLowerCase().includes('uri') ||
@@ -302,7 +310,7 @@ class TypeParser {
         }
 
         return {
-          description: param.description,
+          description: EntityParsingUtils.cleanDescription(param.description),
           oneOf: [baseStringSchema, baseArraySchema],
         };
       }
@@ -312,7 +320,9 @@ class TypeParser {
     if (param.schema) {
       const schema: OpenAPIProperty = {
         type: param.schema.type,
-        description: param.description,
+        description: param.description
+          ? EntityParsingUtils.cleanDescription(param.description)
+          : undefined,
       };
 
       // Add enum values if available - for arrays, put enum on items instead of array
@@ -445,7 +455,9 @@ class TypeParser {
     if (hasDateTimePattern) {
       const parsedType = this.parseType(param.description || '');
       const schema: OpenAPIProperty = {
-        description: param.description,
+        description: param.description
+          ? EntityParsingUtils.cleanDescription(param.description)
+          : undefined,
         ...parsedType,
       };
 
@@ -478,7 +490,9 @@ class TypeParser {
       const schema: OpenAPIProperty = {
         type: 'string',
         format: 'email',
-        description: param.description,
+        description: param.description
+          ? EntityParsingUtils.cleanDescription(param.description)
+          : undefined,
       };
 
       // Add enum values if available
@@ -497,7 +511,9 @@ class TypeParser {
     // Default fallback for other parameters
     const schema: OpenAPIProperty = {
       type: 'string',
-      description: param.description,
+      description: param.description
+        ? EntityParsingUtils.cleanDescription(param.description)
+        : undefined,
     };
 
     // Add enum values if available

src/parsers/EntityParsingUtils.ts

@@ -26,9 +26,10 @@ export class EntityParsingUtils {
 
     // Remove redundant type prefixes like "String.", "Boolean.", etc.
     // Also remove complex type prefixes like "Array of String.", "Array of Integer.", etc.
+    // Also remove "String or Array of..." patterns
     // Match case-insensitive type prefix followed by period and space at start of string
     const typePattern =
-      /^(String|Boolean|Integer|Number|Array(\s+of\s+(String|Boolean|Integer|Number|Object|Hash))?|Object|Hash)\.\s*/i;
+      /^(String(\s+or\s+Array\s+of\s+(String|Strings?)(\s+\([^)]+\))?)?|Boolean|Integer|Number|Array(\s+of\s+(String|Boolean|Integer|Number|Object|Hash))?|Object|Hash)\.\s*/i;
     cleaned = cleaned.replace(typePattern, '');
 
     return cleaned.trim();
@@ -40,9 +41,10 @@ export class EntityParsingUtils {
   static stripTypePrefix(description: string): string {
     // Remove redundant type prefixes like "String.", "Boolean.", etc.
     // Also remove complex type prefixes like "Array of String.", "Array of Integer.", etc.
+    // Also remove "String or Array of..." patterns
     // Match case-insensitive type prefix followed by period and space at start of string
     const typePattern =
-      /^(String|Boolean|Integer|Number|Array(\s+of\s+(String|Boolean|Integer|Number|Object|Hash))?|Object|Hash)\.\s*/i;
+      /^(String(\s+or\s+Array\s+of\s+(String|Strings?)(\s+\([^)]+\))?)?|Boolean|Integer|Number|Array(\s+of\s+(String|Boolean|Integer|Number|Object|Hash))?|Object|Hash)\.\s*/i;
     return description.replace(typePattern, '').trim();
   }