@pikku/openapi-parser 0.12.9 → 0.12.10

package/src/index.ts

@@ -8,9 +8,7 @@ export {
   type SecuritySchemeInfo,
 } from './parse-openapi.js'
 
-export {
-  generateAddonFromOpenAPI,
-} from './codegen.js'
+export { generateAddonFromOpenAPI } from './codegen.js'
 
 export {
   generateOperationNames,
@@ -25,4 +23,5 @@ export {
   schemaToZod,
   schemaVarName,
   sanitizeTypeName,
+  snakeToCamel,
 } from './openapi-to-zod-schema.js'

package/src/naming.test.ts

@@ -0,0 +1,260 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import {
+  sanitizeIdentifier,
+  singularize,
+  toCamelCase,
+  toPascalCase,
+  detectCommonPrefix,
+  generateOperationNames,
+} from './naming.js'
+
+// ---------------------------------------------------------------------------
+// sanitizeIdentifier
+// ---------------------------------------------------------------------------
+describe('sanitizeIdentifier', () => {
+  test('prefixes reserved words with underscore', () => {
+    assert.equal(sanitizeIdentifier('delete'), '_delete')
+    assert.equal(sanitizeIdentifier('package'), '_package')
+    assert.equal(sanitizeIdentifier('class'), '_class')
+    assert.equal(sanitizeIdentifier('import'), '_import')
+    assert.equal(sanitizeIdentifier('export'), '_export')
+    assert.equal(sanitizeIdentifier('return'), '_return')
+    assert.equal(sanitizeIdentifier('function'), '_function')
+    assert.equal(sanitizeIdentifier('yield'), '_yield')
+  })
+
+  test('prefixes names starting with digits with "n"', () => {
+    assert.equal(
+      sanitizeIdentifier('4oDBrowseByDateFeed'),
+      'n4oDBrowseByDateFeed'
+    )
+    assert.equal(sanitizeIdentifier('123abc'), 'n123abc')
+    assert.equal(sanitizeIdentifier('0'), 'n0')
+  })
+
+  test('strips numeric separators (1_000 → 1000)', () => {
+    assert.equal(sanitizeIdentifier('limit1_000'), 'limit1000')
+    assert.equal(sanitizeIdentifier('max1_000_000'), 'max1000000')
+  })
+
+  test('strips curly braces from operationId-like names', () => {
+    // sanitizeIdentifier strips all non-alphanumeric/underscore/$
+    assert.equal(
+      sanitizeIdentifier('createProfiles{extension}'),
+      'createProfilesextension'
+    )
+  })
+
+  test('strips dashes and special characters', () => {
+    assert.equal(sanitizeIdentifier('foo-bar'), 'foobar')
+    assert.equal(sanitizeIdentifier('hello.world'), 'helloworld')
+  })
+
+  test('returns "unnamed" for empty string after sanitization', () => {
+    assert.equal(sanitizeIdentifier('---'), 'unnamed')
+    assert.equal(sanitizeIdentifier(''), 'unnamed')
+  })
+
+  test('does not prefix underscore-only names as digit-leading', () => {
+    assert.equal(sanitizeIdentifier('_foo'), '_foo')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// singularize
+// ---------------------------------------------------------------------------
+describe('singularize', () => {
+  test('regular plurals', () => {
+    assert.equal(singularize('users'), 'user')
+    assert.equal(singularize('products'), 'product')
+  })
+
+  test('ies → y', () => {
+    assert.equal(singularize('categories'), 'category')
+    assert.equal(singularize('entries'), 'entry')
+  })
+
+  test('irregular plurals', () => {
+    assert.equal(singularize('addresses'), 'address')
+    assert.equal(singularize('statuses'), 'status')
+    assert.equal(singularize('indices'), 'index')
+    assert.equal(singularize('aliases'), 'alias')
+  })
+
+  test('shes/ches/xes/zes/sses → drop "es"', () => {
+    assert.equal(singularize('bushes'), 'bush')
+    assert.equal(singularize('churches'), 'church')
+    assert.equal(singularize('boxes'), 'box')
+  })
+
+  test('preserves words ending in ss or us', () => {
+    assert.equal(singularize('class'), 'class')
+    assert.equal(singularize('campus'), 'campus')
+  })
+
+  test('does not singularize short words', () => {
+    assert.equal(singularize('as'), 'as')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// toCamelCase / toPascalCase
+// ---------------------------------------------------------------------------
+describe('toCamelCase', () => {
+  test('converts kebab-case', () => {
+    assert.equal(toCamelCase('foo-bar'), 'fooBar')
+  })
+
+  test('converts snake_case', () => {
+    assert.equal(toCamelCase('foo_bar'), 'fooBar')
+  })
+
+  test('lowers leading capital', () => {
+    assert.equal(toCamelCase('FooBar'), 'fooBar')
+  })
+
+  test('strips trailing non-alphanumeric', () => {
+    assert.equal(toCamelCase('foo-bar-'), 'fooBar')
+  })
+})
+
+describe('toPascalCase', () => {
+  test('uppercases first letter', () => {
+    assert.equal(toPascalCase('foo-bar'), 'FooBar')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// detectCommonPrefix
+// ---------------------------------------------------------------------------
+describe('detectCommonPrefix', () => {
+  test('detects /api/v1/ prefix shared by majority', () => {
+    const paths = [
+      '/api/v1/users',
+      '/api/v1/users/{id}',
+      '/api/v1/products',
+      '/api/v1/orders',
+    ]
+    assert.equal(detectCommonPrefix(paths), '/api/v1/')
+  })
+
+  test('detects prefix even with outliers below 25%', () => {
+    const paths = [
+      '/api/v2/users',
+      '/api/v2/products',
+      '/api/v2/orders',
+      '/api/v2/settings',
+      '/oauth/authorize', // outlier
+    ]
+    // 4 out of 5 share /api/v2/ → 80% > 75% threshold
+    assert.equal(detectCommonPrefix(paths), '/api/v2/')
+  })
+
+  test('returns empty when no common prefix', () => {
+    const paths = ['/users', '/products', '/orders']
+    assert.equal(detectCommonPrefix(paths), '')
+  })
+
+  test('returns empty for empty array', () => {
+    assert.equal(detectCommonPrefix([]), '')
+  })
+
+  test('skips path-parameter segments as prefix candidates', () => {
+    const paths = ['/{version}/users', '/{version}/products']
+    // {version} starts with {, so it should not be considered a prefix
+    assert.equal(detectCommonPrefix(paths), '')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// generateOperationNames
+// ---------------------------------------------------------------------------
+describe('generateOperationNames', () => {
+  test('uses operationId when available', () => {
+    const ops = [{ method: 'get', path: '/users', operationId: 'listUsers' }]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, 'listUsers')
+  })
+
+  test('strips curly braces from operationId', () => {
+    const ops = [
+      {
+        method: 'post',
+        path: '/profiles',
+        operationId: 'createProfiles{extension}',
+      },
+    ]
+    const result = generateOperationNames(ops, '')
+    // {} are stripped, then toCamelCase runs — no separator between "Profiles" and "extension"
+    // so the result is "createProfilesextension"
+    assert.equal(result[0].functionName, 'createProfilesextension')
+  })
+
+  test('strips curly braces with separators from operationId', () => {
+    const ops = [
+      {
+        method: 'post',
+        path: '/profiles',
+        operationId: 'create-profiles-{extension}',
+      },
+    ]
+    const result = generateOperationNames(ops, '')
+    // With dashes as separators, toCamelCase capitalizes after each separator
+    assert.equal(result[0].functionName, 'createProfilesExtension')
+  })
+
+  test('derives name from path when no operationId', () => {
+    const ops = [{ method: 'get', path: '/users/{id}' }]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, 'getUser')
+  })
+
+  test('uses "list" prefix for GET on collection', () => {
+    const ops = [{ method: 'get', path: '/users' }]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, 'listUsers')
+  })
+
+  test('handles collision by appending counter', () => {
+    const ops = [
+      { method: 'get', path: '/users', operationId: 'listUsers' },
+      { method: 'get', path: '/v2/users', operationId: 'listUsers' },
+    ]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, 'listUsers')
+    assert.equal(result[1].functionName, 'listUsers2')
+  })
+
+  test('sanitizes reserved word operationIds', () => {
+    const ops = [
+      { method: 'delete', path: '/items/{id}', operationId: 'delete' },
+    ]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, '_delete')
+  })
+
+  test('sanitizes digit-leading operationIds', () => {
+    const ops = [
+      { method: 'get', path: '/feeds', operationId: '4oDBrowseByDateFeed' },
+    ]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, 'n4oDBrowseByDateFeed')
+  })
+
+  test('strips common prefix from path-derived names', () => {
+    const ops = [
+      { method: 'get', path: '/api/v1/users' },
+      { method: 'get', path: '/api/v1/products' },
+    ]
+    const result = generateOperationNames(ops, '/api/v1/')
+    assert.equal(result[0].functionName, 'listUsers')
+    assert.equal(result[1].functionName, 'listProducts')
+  })
+
+  test('handles dashes and underscores in operationIds', () => {
+    const ops = [{ method: 'get', path: '/x', operationId: 'get-all_items' }]
+    const result = generateOperationNames(ops, '')
+    assert.equal(result[0].functionName, 'getAllItems')
+  })
+})

package/src/naming.ts

@@ -3,6 +3,118 @@
  * Uses operationId when available, otherwise generates from path segments.
  */
 
+/** JavaScript/TypeScript reserved words that cannot be used as identifiers */
+const JS_RESERVED_WORDS = new Set([
+  // ECMAScript reserved words
+  'abstract',
+  'arguments',
+  'await',
+  'boolean',
+  'break',
+  'byte',
+  'case',
+  'catch',
+  'char',
+  'class',
+  'const',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'double',
+  'else',
+  'enum',
+  'eval',
+  'export',
+  'extends',
+  'false',
+  'final',
+  'finally',
+  'float',
+  'for',
+  'function',
+  'goto',
+  'if',
+  'implements',
+  'import',
+  'in',
+  'instanceof',
+  'int',
+  'interface',
+  'let',
+  'long',
+  'native',
+  'new',
+  'null',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'return',
+  'short',
+  'static',
+  'super',
+  'switch',
+  'synchronized',
+  'this',
+  'throw',
+  'throws',
+  'transient',
+  'true',
+  'try',
+  'typeof',
+  'undefined',
+  'var',
+  'void',
+  'volatile',
+  'while',
+  'with',
+  'yield',
+  // TypeScript additional reserved words in strict mode
+  'as',
+  'any',
+  'declare',
+  'get',
+  'module',
+  'require',
+  'number',
+  'object',
+  'set',
+  'string',
+  'symbol',
+  'type',
+  'from',
+  'of',
+])
+
+/**
+ * Ensure a name is a valid JS/TS identifier:
+ * - Not a reserved word
+ * - Does not start with a digit
+ * - Does not contain numeric separator patterns (e.g. 1_000)
+ */
+export function sanitizeIdentifier(name: string): string {
+  // Strip numeric separator patterns like 1_000 → 1000
+  name = name.replace(/(\d)_(\d)/g, '$1$2')
+
+  // Strip any remaining invalid characters
+  name = name.replace(/[^a-zA-Z0-9_$]/g, '')
+
+  // Prefix with 'n' if name starts with a digit (not underscore, since
+  // pikku inspector may strip leading underscores from type names)
+  if (/^[0-9]/.test(name)) {
+    name = 'n' + name
+  }
+
+  // Prefix with underscore if name is a reserved word
+  if (JS_RESERVED_WORDS.has(name)) {
+    name = '_' + name
+  }
+
+  return name || 'unnamed'
+}
+
 const IRREGULAR_PLURALS: Record<string, string> = {
   addresses: 'address',
   statuses: 'status',
@@ -27,11 +139,22 @@ export function singularize(word: string): string {
     return word.slice(0, -3) + 'y'
   }
   // -shes, -ches, -xes, -zes, -sses → drop "es"
-  if (lower.endsWith('shes') || lower.endsWith('ches') || lower.endsWith('xes') || lower.endsWith('zes') || lower.endsWith('sses')) {
+  if (
+    lower.endsWith('shes') ||
+    lower.endsWith('ches') ||
+    lower.endsWith('xes') ||
+    lower.endsWith('zes') ||
+    lower.endsWith('sses')
+  ) {
     return word.slice(0, -2)
   }
   // General: drop trailing "s" (covers courses→course, products→product, etc.)
-  if (lower.endsWith('s') && !lower.endsWith('ss') && !lower.endsWith('us') && lower.length > 2) {
+  if (
+    lower.endsWith('s') &&
+    !lower.endsWith('ss') &&
+    !lower.endsWith('us') &&
+    lower.length > 2
+  ) {
     return word.slice(0, -1)
   }
   return word
@@ -40,6 +163,7 @@ export function singularize(word: string): string {
 export function toCamelCase(str: string): string {
   return str
     .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/[^a-zA-Z0-9]+$/g, '') // strip trailing non-alphanumeric chars
     .replace(/^[A-Z]/, (c) => c.toLowerCase())
 }
 
@@ -84,12 +208,16 @@ export function detectCommonPrefix(paths: string[]): string {
 /** Convert operationId to camelCase function name */
 function fromOperationId(operationId: string): string {
   // operationId might be snake_case, camelCase, PascalCase, or kebab-case
-  return toCamelCase(
-    operationId
-      .replace(/[^a-zA-Z0-9_-]/g, '_')
-      .replace(/_+/g, '_')
-      .replace(/^_|_$/g, '')
-  )
+  let name =
+    toCamelCase(
+      operationId
+        .replace(/[{}]/g, '') // strip curly braces from path parameters
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .replace(/[-_]+/g, '_')
+        .replace(/^_|_$/g, '')
+    ) || 'unnamed'
+
+  return sanitizeIdentifier(name)
 }
 
 const METHOD_PREFIXES: Record<string, string> = {
@@ -123,6 +251,11 @@ export function generateOperationNames(
 ): NamedOperation[] {
   const results: NamedOperation[] = []
   const usedNames = new Map<string, number>()
+  // Track names case-insensitively to prevent file system collisions on
+  // case-insensitive systems (macOS, Windows). Two operationIds that differ
+  // only in casing (e.g. userGetOauth2Application vs userGetOAuth2Application)
+  // would produce files that collide on disk.
+  const usedNamesLower = new Map<string, number>()
 
   for (const op of operations) {
     let name: string
@@ -133,13 +266,24 @@ export function generateOperationNames(
       name = deriveNameFromPath(op.method, op.path, commonPrefix)
     }
 
-    // Handle collisions
-    const existing = usedNames.get(name) ?? 0
+    // Ensure name is a valid JS/TS identifier
+    name = sanitizeIdentifier(name)
+
+    // Handle collisions (case-insensitive to avoid file system conflicts)
+    const nameLower = name.toLowerCase()
+    const existingExact = usedNames.get(name) ?? 0
+    const existingCI = usedNamesLower.get(nameLower) ?? 0
+    const existing = Math.max(existingExact, existingCI)
     if (existing > 0) {
       usedNames.set(name, existing + 1)
+      usedNamesLower.set(nameLower, existing + 1)
       name = `${name}${existing + 1}`
     }
     usedNames.set(name, (usedNames.get(name) ?? 0) || 1)
+    usedNamesLower.set(
+      name.toLowerCase(),
+      (usedNamesLower.get(name.toLowerCase()) ?? 0) || 1
+    )
 
     results.push({
       method: op.method,
@@ -163,10 +307,7 @@ function deriveNameFromPath(
     cleanPath = '/' + cleanPath.slice(commonPrefix.length)
   }
 
-  const segments = cleanPath
-    .replace(/^\//, '')
-    .split('/')
-    .filter(Boolean)
+  const segments = cleanPath.replace(/^\//, '').split('/').filter(Boolean)
 
   const methodLower = method.toLowerCase()
   const prefix = METHOD_PREFIXES[methodLower] || methodLower