@pikku/openapi-parser 0.12.19 → 0.12.21

package/src/index.ts

@@ -1,26 +0,0 @@
-export {
-  parseOpenAPISpec,
-  computeContractHash,
-  type ParsedSpec,
-} from './parse-openapi.js'
-
-export { generateAddonFromOpenAPI } from './codegen.js'
-
-export {
-  loadAuthConfig,
-  type AuthConfig,
-  type DelegatedLoginConfig,
-} from './auth-config.js'
-
-export {
-  type NamedOperation,
-} from './naming.js'
-
-export {
-  type OpenAPISchema,
-  type ZodCodegenContext,
-  createContext,
-  schemaToZod,
-  schemaVarName,
-  sanitizeTypeName,
-} from './openapi-to-zod-schema.js'

package/src/naming.test.ts

@@ -1,260 +0,0 @@
-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

@@ -1,369 +0,0 @@
-/**
- * Derives function/method names from HTTP method + path.
- * Uses operationId when available, otherwise generates from path segments.
- */
-
-/**
- * Words that are illegal as a `const`/binding identifier in a strict-mode module
- * (generated code is always ESM). Contextual keywords that are only special in a
- * specific position — `get`/`set` (getters), `type`/`as`/`from`/`of` (type & import
- * syntax), `any`/`number`/`object`/`string`/`symbol`/`declare`/`module`/`require`
- * (type positions), and the legacy ES3 future-reserved words (`byte`, `char`, `int`,
- * `long`, `short`, `float`, `double`, `boolean`, `goto`, `native`, `synchronized`,
- * `transient`, `volatile`, `abstract`, `final`) — are all valid binding names and
- * deliberately excluded, so `sheets.spreadsheets.get` stays `get`, not `_get`.
- */
-const JS_RESERVED_WORDS = new Set([
-  'arguments',
-  'await',
-  'break',
-  'case',
-  'catch',
-  'class',
-  'const',
-  'continue',
-  'debugger',
-  'default',
-  'delete',
-  'do',
-  'else',
-  'enum',
-  'eval',
-  'export',
-  'extends',
-  'false',
-  'finally',
-  'for',
-  'function',
-  'if',
-  'implements',
-  'import',
-  'in',
-  'instanceof',
-  'interface',
-  'let',
-  'new',
-  'null',
-  'package',
-  'private',
-  'protected',
-  'public',
-  'return',
-  'static',
-  'super',
-  'switch',
-  'this',
-  'throw',
-  'throws',
-  'true',
-  'try',
-  'typeof',
-  'undefined',
-  'var',
-  'void',
-  'while',
-  'with',
-  'yield',
-])
-
-/**
- * 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',
-  indices: 'index',
-  analyses: 'analysis',
-  quizzes: 'quiz',
-  matrices: 'matrix',
-  vertices: 'vertex',
-  aliases: 'alias',
-  buses: 'bus',
-}
-
-export function singularize(word: string): string {
-  const lower = word.toLowerCase()
-  if (IRREGULAR_PLURALS[lower]) {
-    const singular = IRREGULAR_PLURALS[lower]
-    return word[0] === word[0].toUpperCase()
-      ? singular.charAt(0).toUpperCase() + singular.slice(1)
-      : singular
-  }
-  if (lower.endsWith('ies') && lower.length > 4) {
-    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')
-  ) {
-    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
-  ) {
-    return word.slice(0, -1)
-  }
-  return word
-}
-
-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())
-}
-
-export function toPascalCase(str: string): string {
-  const camel = toCamelCase(str)
-  return camel.charAt(0).toUpperCase() + camel.slice(1)
-}
-
-/**
- * Strip common API prefix from paths (e.g. /api/v2/).
- * Uses majority voting — a prefix shared by >75% of paths is stripped,
- * so a few outlier paths (e.g. /oauth/...) don't break detection.
- */
-export function detectCommonPrefix(paths: string[]): string {
-  if (paths.length === 0) return ''
-
-  const segments = paths.map((p) => p.replace(/^\//, '').split('/'))
-  const threshold = Math.ceil(paths.length * 0.75)
-
-  // Find the longest prefix shared by at least `threshold` paths
-  let prefixLen = 0
-  for (let i = 0; i < 10; i++) {
-    // Count how many paths have the same segment at position i as the first path
-    const candidateSeg = segments[0][i]
-    if (!candidateSeg || candidateSeg.startsWith('{')) break
-
-    const count = segments.filter(
-      (s) => s.length > i + 1 && s[i] === candidateSeg
-    ).length
-
-    if (count >= threshold) {
-      prefixLen = i + 1
-    } else {
-      break
-    }
-  }
-
-  if (prefixLen === 0) return ''
-  return '/' + segments[0].slice(0, prefixLen).join('/') + '/'
-}
-
-/** Convert operationId to camelCase function name */
-function fromOperationId(operationId: string): string {
-  // operationId might be snake_case, camelCase, PascalCase, or kebab-case
-  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> = {
-  get: 'get',
-  post: 'create',
-  put: 'update',
-  patch: 'update',
-  delete: 'delete',
-}
-
-interface OperationForNaming {
-  method: string
-  path: string
-  operationId?: string
-}
-
-/**
- * Find the longest shared leading run of dot-separated operationId segments,
- * always leaving at least one trailing segment on every operation. Only applies
- * when every operation has a dotted operationId (e.g. Google's
- * `sheets.spreadsheets.values.get`), so specs whose ids are camelCase or absent
- * are left untouched. The shared prefix is redundant with the addon namespace,
- * so stripping it turns `sheetsSpreadsheetsValuesGet` into `valuesGet`.
- */
-function commonOperationIdPrefix(operations: OperationForNaming[]): string[] {
-  if (operations.length < 2) {
-    return []
-  }
-  if (
-    !operations.every((op) => op.operationId && op.operationId.includes('.'))
-  ) {
-    return []
-  }
-  const segmented = operations.map((op) => op.operationId!.split('.'))
-  const minLen = Math.min(...segmented.map((s) => s.length))
-  const prefix: string[] = []
-  for (let i = 0; i < minLen - 1; i++) {
-    const seg = segmented[0][i]
-    if (segmented.every((s) => s[i] === seg)) {
-      prefix.push(seg)
-    } else {
-      break
-    }
-  }
-  return prefix
-}
-
-export interface NamedOperation {
-  method: string
-  path: string
-  functionName: string
-  methodName: string
-}
-
-/**
- * Generate function names for a list of operations.
- * Handles collision detection and auto-deduplication.
- */
-export function generateOperationNames(
-  operations: OperationForNaming[],
-  commonPrefix: string
-): 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>()
-
-  const opIdPrefix = commonOperationIdPrefix(operations)
-
-  for (const op of operations) {
-    let name: string
-
-    if (op.operationId) {
-      const opId = opIdPrefix.length
-        ? op.operationId.split('.').slice(opIdPrefix.length).join('.')
-        : op.operationId
-      name = fromOperationId(opId)
-    } else {
-      name = deriveNameFromPath(op.method, op.path, commonPrefix)
-    }
-
-    // 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,
-      path: op.path,
-      functionName: name,
-      methodName: name,
-    })
-  }
-
-  return results
-}
-
-function deriveNameFromPath(
-  method: string,
-  path: string,
-  commonPrefix: string
-): string {
-  // Strip common prefix
-  let cleanPath = path
-  if (commonPrefix && cleanPath.startsWith(commonPrefix)) {
-    cleanPath = '/' + cleanPath.slice(commonPrefix.length)
-  }
-
-  const segments = cleanPath.replace(/^\//, '').split('/').filter(Boolean)
-
-  const methodLower = method.toLowerCase()
-  const prefix = METHOD_PREFIXES[methodLower] || methodLower
-
-  // Separate param and non-param segments
-  const nonParams: string[] = []
-  let hasTrailingParam = false
-
-  for (let i = 0; i < segments.length; i++) {
-    if (segments[i].startsWith('{')) {
-      if (i === segments.length - 1) {
-        hasTrailingParam = true
-      }
-    } else {
-      nonParams.push(segments[i])
-    }
-  }
-
-  if (nonParams.length === 0) {
-    return prefix
-  }
-
-  // For GET with trailing param: singularize the last non-param segment
-  // For GET without trailing param: keep plural (list)
-  // For POST without trailing param: use prefix (create)
-  const parts = nonParams.map((seg, i) => {
-    const isLast = i === nonParams.length - 1
-    let word = seg
-
-    if (isLast && hasTrailingParam) {
-      word = singularize(word)
-    }
-
-    // For GET on collection (no trailing param), use "list" prefix instead of "get"
-    return toPascalCase(word)
-  })
-
-  // For GET on collection, use "list" instead of "get"
-  let finalPrefix = prefix
-  if (methodLower === 'get' && !hasTrailingParam) {
-    finalPrefix = 'list'
-  }
-
-  return finalPrefix + parts.join('')
-}