@amritk/generate-parsers 0.2.1 → 0.3.1

package/src/generators/generate-validation-expression.ts

@@ -0,0 +1,286 @@
+import { resolveRef } from '@amritk/helpers/resolve-ref'
+import { safeAccessor } from '@amritk/helpers/safe-accessor'
+import {
+  hasAdditionalProperties,
+  hasAllOf,
+  hasAnyOf,
+  hasConst,
+  hasEnum,
+  hasExclusiveMaximum,
+  hasExclusiveMinimum,
+  hasMaxItems,
+  hasMaximum,
+  hasMaxLength,
+  hasMaxProperties,
+  hasMinItems,
+  hasMinimum,
+  hasMinLength,
+  hasMinProperties,
+  hasMultipleOf,
+  hasOneOf,
+  hasPattern,
+  hasProperties,
+  hasRef,
+  hasRequired,
+  hasType,
+  hasUniqueItems,
+  isSchemaObject,
+} from '@amritk/helpers/schema-guards'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import { findDiscriminator } from '#helpers/find-discriminator'
+
+import { generateDiscriminatedUnionValidation } from './generate-discriminated-union-validation'
+import { generateEnumCheck } from './generate-enum-check'
+import { generateNonDiscriminatedUnionValidation } from './generate-non-discriminated-union-validation'
+import { generateSchemaChecks } from './generate-schema-checks'
+
+/**
+ * Generates a type coercion expression for converting a value to the expected type.
+ */
+const getTypeCoercion = (accessor: string, schema: JSONSchema, defaultValue: string): string | null => {
+  if (!hasType(schema)) {
+    return null
+  }
+
+  switch (schema.type) {
+    case 'string':
+      return `String(${accessor})`
+    case 'number':
+    case 'integer': {
+      // Number() of a non-numeric string produces NaN, which silently poisons
+      // arithmetic. Guard with Number.isFinite and fall back to the default.
+      const n = `Number(${accessor})`
+      return `(Number.isFinite(${n}) ? ${n} : ${defaultValue})`
+    }
+    case 'boolean':
+      return `Boolean(${accessor})`
+    case 'array':
+      return `[]`
+    case 'object':
+      return `typeof ${accessor} === "object" && ${accessor} !== null ? ${accessor} : {}`
+    default:
+      return null
+  }
+}
+
+/**
+ * Generates a validation expression that checks if a value matches the expected type.
+ * Returns the value if valid, coerces to the correct type if invalid, or uses default if required and missing.
+ * Supports type checking, pattern validation, enum validation, union types, and $ref resolution.
+ */
+export const generateValidationExpression = (
+  key: string,
+  schema: JSONSchema,
+  defaultValue: string,
+  isRequired: boolean,
+  rootSchema?: Record<string, unknown>,
+  visitedRefs?: Set<string>,
+  accessorOverride?: string,
+  knownNotUndefined?: boolean,
+): string => {
+  const accessor = accessorOverride ?? safeAccessor('input?', key)
+  const checks: string[] = []
+
+  if (!isSchemaObject(schema)) {
+    return isRequired ? `${accessor} ?? ${defaultValue}` : accessor
+  }
+
+  // Handle $ref - resolve and validate against the referenced schema
+  if (hasRef(schema) && rootSchema) {
+    const ref = schema.$ref
+
+    // If we have already visited this ref, we have a circular reference - return accessor to break cycle
+    if (visitedRefs?.has(ref)) {
+      return isRequired ? `${accessor} ?? ${defaultValue}` : accessor
+    }
+
+    const resolvedSchema = resolveRef(ref, rootSchema)
+    if (resolvedSchema) {
+      const visited = new Set(visitedRefs)
+      visited.add(ref)
+
+      return generateValidationExpression(key, resolvedSchema, defaultValue, isRequired, rootSchema, visited)
+    }
+  }
+
+  // Handle union types (oneOf, anyOf)
+  if (hasOneOf(schema) && schema.oneOf.length > 0) {
+    const discriminator = findDiscriminator(schema.oneOf)
+    if (discriminator) {
+      return generateDiscriminatedUnionValidation(accessor, schema.oneOf, discriminator, defaultValue, isRequired)
+    }
+    return generateNonDiscriminatedUnionValidation(accessor, schema.oneOf, defaultValue, isRequired)
+  }
+
+  if (hasAnyOf(schema) && schema.anyOf.length > 0) {
+    const discriminator = findDiscriminator(schema.anyOf)
+    if (discriminator) {
+      return generateDiscriminatedUnionValidation(accessor, schema.anyOf, discriminator, defaultValue, isRequired)
+    }
+    return generateNonDiscriminatedUnionValidation(accessor, schema.anyOf, defaultValue, isRequired)
+  }
+
+  // Handle allOf (intersection - all schemas must match)
+  if (hasAllOf(schema) && schema.allOf.length > 0) {
+    const allChecks: string[] = []
+    for (const subSchema of schema.allOf) {
+      const subChecks = generateSchemaChecks(accessor, subSchema)
+      allChecks.push(...subChecks)
+    }
+
+    if (allChecks.length > 0) {
+      let combinedCheck = allChecks[0]
+      for (let i = 1; i < allChecks.length; i++) {
+        combinedCheck += ' && ' + allChecks[i]
+      }
+      return `${combinedCheck} ? ${accessor} : ${defaultValue}`
+    }
+    return `${accessor} ?? ${defaultValue}`
+  }
+
+  // Handle not (negation - value must NOT match this schema)
+  if ('not' in schema && schema.not) {
+    const notChecks = generateSchemaChecks(accessor, schema.not)
+    if (notChecks.length > 0) {
+      let combinedNotCheck = notChecks[0]
+      for (let i = 1; i < notChecks.length; i++) {
+        combinedNotCheck += ' && ' + notChecks[i]
+      }
+      return `!(${combinedNotCheck}) ? ${accessor} : ${defaultValue}`
+    }
+  }
+
+  // Handle const — single exact value that must match
+  if (hasConst(schema)) {
+    const constLiteral = JSON.stringify(schema.const)
+    return isRequired
+      ? `${accessor} === ${constLiteral} ? ${accessor} : ${constLiteral}`
+      : `${accessor} === ${constLiteral} ? ${accessor} : (${accessor} !== undefined ? ${constLiteral} : undefined)`
+  }
+
+  if (!hasType(schema) && !hasEnum(schema)) {
+    return `${accessor} ?? ${defaultValue}`
+  }
+
+  // Build type-specific checks
+  if (hasType(schema)) {
+    switch (schema.type) {
+      case 'string': {
+        checks.push(`typeof ${accessor} === "string"`)
+        if (hasPattern(schema)) {
+          checks.push(`/${schema.pattern.replace(/\//g, '\\/')}/.test(${accessor})`)
+        }
+        if (hasMinLength(schema)) {
+          checks.push(`${accessor}.length >= ${schema.minLength}`)
+        }
+        if (hasMaxLength(schema)) {
+          checks.push(`${accessor}.length <= ${schema.maxLength}`)
+        }
+        break
+      }
+      case 'number':
+      case 'integer': {
+        checks.push(`typeof ${accessor} === "number"`)
+        if (hasMinimum(schema)) {
+          checks.push(`${accessor} >= ${schema.minimum}`)
+        }
+        if (hasMaximum(schema)) {
+          checks.push(`${accessor} <= ${schema.maximum}`)
+        }
+        if (hasExclusiveMinimum(schema)) {
+          checks.push(`${accessor} > ${schema.exclusiveMinimum}`)
+        }
+        if (hasExclusiveMaximum(schema)) {
+          checks.push(`${accessor} < ${schema.exclusiveMaximum}`)
+        }
+        if (hasMultipleOf(schema)) {
+          checks.push(`${accessor} % ${schema.multipleOf} === 0`)
+        }
+        break
+      }
+      case 'boolean':
+        checks.push(`typeof ${accessor} === "boolean"`)
+        break
+      case 'array': {
+        checks.push(`Array.isArray(${accessor})`)
+        if (hasMinItems(schema)) {
+          checks.push(`${accessor}.length >= ${schema.minItems}`)
+        }
+        if (hasMaxItems(schema)) {
+          checks.push(`${accessor}.length <= ${schema.maxItems}`)
+        }
+        if (hasUniqueItems(schema) && schema.uniqueItems === true) {
+          checks.push(`new Set(${accessor}).size === ${accessor}.length`)
+        }
+        break
+      }
+      case 'object': {
+        checks.push(`isObject(${accessor})`)
+        // Check required properties exist
+        if (hasRequired(schema) && schema.required.length > 0) {
+          for (const requiredKey of schema.required) {
+            checks.push(`"${requiredKey}" in ${accessor}`)
+          }
+        }
+        // Check minProperties
+        if (hasMinProperties(schema)) {
+          checks.push(`Object.keys(${accessor}).length >= ${schema.minProperties}`)
+        }
+        // Check maxProperties
+        if (hasMaxProperties(schema)) {
+          checks.push(`Object.keys(${accessor}).length <= ${schema.maxProperties}`)
+        }
+        // Check additionalProperties
+        if (hasAdditionalProperties(schema) && schema.additionalProperties === false && hasProperties(schema)) {
+          const allowedKeys = Object.keys(schema.properties)
+          const allowedKeysStr = JSON.stringify(allowedKeys)
+          checks.push(`Object.keys(${accessor}).every(k => ${allowedKeysStr}.includes(k))`)
+        }
+        break
+      }
+    }
+  }
+
+  // Add enum check if present
+  if (hasEnum(schema) && schema.enum.length > 0) {
+    checks.push(generateEnumCheck(accessor, schema.enum))
+  }
+
+  // Combine all checks
+  if (checks.length === 0) {
+    return isRequired ? `${accessor} ?? ${defaultValue}` : accessor
+  }
+
+  let combinedCheck = checks[0]
+  for (let i = 1; i < checks.length; i++) {
+    combinedCheck += ' && ' + checks[i]
+  }
+
+  // Generate the fallback value
+  // If the value exists but fails validation, try to coerce it
+  // If the value is missing and required, use the default
+  const typeCoercion = getTypeCoercion(accessor, schema, defaultValue)
+
+  if (isRequired) {
+    // For required fields: valid ? use_value : (exists ? coerce : default)
+    if (typeCoercion) {
+      // If we know the value is not undefined (e.g., we're inside an undefined check),
+      // we can skip the redundant undefined check
+      if (knownNotUndefined) {
+        return `${combinedCheck} ? ${accessor} : ${typeCoercion}`
+      }
+      return `${combinedCheck} ? ${accessor} : (${accessor} !== undefined ? ${typeCoercion} : ${defaultValue})`
+    }
+    return `${combinedCheck} ? ${accessor} : ${defaultValue}`
+  } else {
+    // For optional fields: valid ? use_value : (exists ? coerce : undefined)
+    if (typeCoercion) {
+      // If we know the value is not undefined, we can skip the check and just coerce
+      if (knownNotUndefined) {
+        return `${combinedCheck} ? ${accessor} : ${typeCoercion}`
+      }
+      return `${combinedCheck} ? ${accessor} : (${accessor} !== undefined ? ${typeCoercion} : undefined)`
+    }
+    return `${combinedCheck} ? ${accessor} : undefined`
+  }
+}

package/src/helpers/apply-schema-extensions.test.ts

@@ -0,0 +1,194 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import { describe, expect, it } from 'vitest'
+
+import { applySchemaExtensions } from './apply-schema-extensions'
+
+describe('apply-schema-extensions', () => {
+  it('merges extension properties into schema properties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+      required: ['name'],
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {
+      parameter: {
+        'x-enabled': { type: 'boolean' },
+      },
+    })
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        'x-enabled': { type: 'boolean' },
+      },
+      required: ['name'],
+    })
+  })
+
+  it('returns original schema when no extensions match the definition name', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {
+      operation: {
+        'x-codegen': { type: 'string' },
+      },
+    })
+
+    expect(result).toBe(schema)
+  })
+
+  it('returns original schema when extensions record is empty', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {})
+
+    expect(result).toBe(schema)
+  })
+
+  it('returns original schema when matching extensions have no properties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {
+      parameter: {},
+    })
+
+    expect(result).toBe(schema)
+  })
+
+  it('returns boolean schema unchanged', () => {
+    const result = applySchemaExtensions(true, 'parameter', {
+      parameter: {
+        'x-enabled': { type: 'boolean' },
+      },
+    })
+
+    expect(result).toBe(true)
+  })
+
+  it('adds properties to a schema that has no existing properties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {
+      parameter: {
+        'x-enabled': { type: 'boolean' },
+      },
+    })
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        'x-enabled': { type: 'boolean' },
+      },
+    })
+  })
+
+  it('merges multiple extension properties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {
+      parameter: {
+        'x-enabled': { type: 'boolean' },
+        'x-internal': { type: 'boolean', default: false },
+        'x-display-name': { type: 'string' },
+      },
+    })
+
+    const properties = (result as Record<string, unknown>)['properties'] as Record<string, unknown>
+    expect(Object.keys(properties)).toEqual(['name', 'x-enabled', 'x-internal', 'x-display-name'])
+  })
+
+  it('does not modify the required array', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+      required: ['name'],
+    }
+
+    const result = applySchemaExtensions(schema, 'parameter', {
+      parameter: {
+        'x-enabled': { type: 'boolean' },
+      },
+    })
+
+    expect((result as Record<string, unknown>)['required']).toEqual(['name'])
+  })
+
+  it('handles complex extension schemas', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    }
+
+    const result = applySchemaExtensions(schema, 'operation', {
+      operation: {
+        'x-codegen': {
+          type: 'object',
+          properties: {
+            methodName: { type: 'string' },
+            deprecated: { type: 'boolean' },
+          },
+          required: ['methodName'],
+        },
+      },
+    })
+
+    const properties = (result as Record<string, unknown>)['properties'] as Record<string, JSONSchema>
+    expect(properties['x-codegen']).toEqual({
+      type: 'object',
+      properties: {
+        methodName: { type: 'string' },
+        deprecated: { type: 'boolean' },
+      },
+      required: ['methodName'],
+    })
+  })
+
+  it('does not mutate the original schema', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    }
+
+    const originalProperties = { ...((schema as Record<string, unknown>)['properties'] as Record<string, unknown>) }
+
+    applySchemaExtensions(schema, 'parameter', {
+      parameter: {
+        'x-enabled': { type: 'boolean' },
+      },
+    })
+
+    expect((schema as Record<string, unknown>)['properties']).toEqual(originalProperties)
+  })
+})

package/src/helpers/apply-schema-extensions.ts

@@ -0,0 +1,63 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import type { SchemaExtensions } from '#types/schema-extensions'
+
+/**
+ * Merges custom extension properties into a schema's properties based on the
+ * definition name. Extension properties are added as optional (not included
+ * in the required array) since they are custom additions that may not always
+ * be present.
+ *
+ * If the schema is not an object, has no matching extensions, or the
+ * extensions record is empty, the original schema is returned unchanged.
+ *
+ * @param schema - The JSON Schema to extend
+ * @param definitionName - The name of the definition (e.g., "parameter")
+ * @param extensions - The extensions configuration mapping definition names to properties
+ * @returns A new schema with extension properties merged in, or the original if unchanged
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   properties: { name: { type: 'string' } },
+ *   required: ['name'],
+ * }
+ *
+ * const extensions = {
+ *   parameter: {
+ *     'x-enabled': { type: 'boolean' },
+ *   },
+ * }
+ *
+ * const extended = applySchemaExtensions(schema, 'parameter', extensions)
+ * // extended.properties now includes 'x-enabled' alongside 'name'
+ * ```
+ */
+export const applySchemaExtensions = (
+  schema: JSONSchema,
+  definitionName: string,
+  extensions: SchemaExtensions,
+): JSONSchema => {
+  const extensionProperties = extensions[definitionName]
+
+  if (!extensionProperties || Object.keys(extensionProperties).length === 0) {
+    return schema
+  }
+
+  if (typeof schema !== 'object' || schema === null) {
+    return schema
+  }
+
+  const existingProperties =
+    'properties' in schema && typeof schema.properties === 'object' && schema.properties !== null
+      ? (schema.properties as Record<string, JSONSchema>)
+      : {}
+
+  return {
+    ...schema,
+    properties: {
+      ...existingProperties,
+      ...extensionProperties,
+    },
+  }
+}

package/src/helpers/collect-helpers.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+
+import { collectHelpers } from './collect-helpers'
+
+describe('collect-helpers', () => {
+  describe('package mode', () => {
+    it('returns validateArray import when parser contains validateArray', () => {
+      const result = collectHelpers('const items = validateArray(input, parseItem)', 'package')
+      expect(result.imports).toEqual(["import { validateArray } from '@amritk/helpers/validate-array';"])
+      expect(result.used).toEqual(new Set(['validate-array']))
+    })
+
+    it('returns validateRecord import (and transitively flags is-object) for embedded shipping', () => {
+      const result = collectHelpers('const record = validateRecord(input, parseValue)', 'package')
+      expect(result.imports).toEqual(["import { validateRecord } from '@amritk/helpers/validate-record';"])
+      expect(result.used).toEqual(new Set(['validate-record', 'is-object']))
+    })
+
+    it('returns isObject import when parser contains isObject', () => {
+      const result = collectHelpers('if (isObject(input)) {', 'package')
+      expect(result.imports).toEqual(["import { isObject } from '@amritk/helpers/is-object';"])
+      expect(result.used).toEqual(new Set(['is-object']))
+    })
+
+    it('returns hasRef import from schema-guards when parser contains hasRef(', () => {
+      const result = collectHelpers('if (hasRef(s)) { return parseFoo(input) }', 'package')
+      expect(result.imports).toEqual(["import { hasRef } from '@amritk/helpers/schema-guards';"])
+      expect(result.used).toEqual(new Set(['has-ref']))
+    })
+
+    it('returns all imports when parser uses every helper', () => {
+      const parser = `
+        const arr = validateArray(input.items, parseItem)
+        const rec = validateRecord(input.map, parseValue)
+        if (isObject(input)) { return input }
+        if (hasRef(schema)) { /* */ }
+      `
+      const result = collectHelpers(parser, 'package')
+      expect(result.imports).toHaveLength(4)
+      expect(result.imports).toContain("import { validateArray } from '@amritk/helpers/validate-array';")
+      expect(result.imports).toContain("import { validateRecord } from '@amritk/helpers/validate-record';")
+      expect(result.imports).toContain("import { isObject } from '@amritk/helpers/is-object';")
+      expect(result.imports).toContain("import { hasRef } from '@amritk/helpers/schema-guards';")
+      expect(result.used).toEqual(new Set(['validate-array', 'validate-record', 'is-object', 'has-ref']))
+    })
+
+    it('returns empty result when parser uses no helpers', () => {
+      const result = collectHelpers('const x = input.name ?? ""', 'package')
+      expect(result.imports).toEqual([])
+      expect(result.used.size).toBe(0)
+    })
+
+    it('handles empty parser string', () => {
+      const result = collectHelpers('', 'package')
+      expect(result.imports).toEqual([])
+      expect(result.used.size).toBe(0)
+    })
+
+    it('matches helpers as substrings in longer identifiers (existing .includes() behaviour)', () => {
+      const result = collectHelpers('const validateArrayItems = true', 'package')
+      expect(result.imports).toHaveLength(1)
+      expect(result.used.has('validate-array')).toBe(true)
+    })
+  })
+
+  describe('embedded mode', () => {
+    it('emits relative imports targeting ./_helpers/', () => {
+      const parser = `
+        const arr = validateArray(input.items, parseItem)
+        const rec = validateRecord(input.map, parseValue)
+        if (isObject(input)) { return input }
+        if (hasRef(schema)) { /* */ }
+      `
+      const result = collectHelpers(parser, 'embedded')
+      expect(result.imports).toContain("import { validateArray } from './_helpers/validate-array';")
+      expect(result.imports).toContain("import { validateRecord } from './_helpers/validate-record';")
+      expect(result.imports).toContain("import { isObject } from './_helpers/is-object';")
+      expect(result.imports).toContain("import { hasRef } from './_helpers/has-ref';")
+    })
+
+    it('marks is-object as used when validateRecord is referenced (transitive dep)', () => {
+      // validate-record.ts imports isObject, so the embedded build must ship is-object too,
+      // even if the generated parser body itself never mentions isObject directly.
+      const result = collectHelpers('const record = validateRecord(input, parseValue)', 'embedded')
+      expect(result.used.has('validate-record')).toBe(true)
+      expect(result.used.has('is-object')).toBe(true)
+    })
+
+    it('does not duplicate the isObject import line when only validateRecord is referenced', () => {
+      const result = collectHelpers('const record = validateRecord(input, parseValue)', 'embedded')
+      expect(result.imports).toEqual(["import { validateRecord } from './_helpers/validate-record';"])
+    })
+
+    it('emits both validateRecord and isObject import lines when both names appear', () => {
+      const result = collectHelpers(
+        'if (!isObject(input)) return {}; const r = validateRecord(input, parse)',
+        'embedded',
+      )
+      expect(result.imports).toContain("import { validateRecord } from './_helpers/validate-record';")
+      expect(result.imports).toContain("import { isObject } from './_helpers/is-object';")
+    })
+  })
+})