@amritk/generate-parsers 0.1.0 → 0.3.0

package/src/helpers/collect-helpers.ts

@@ -0,0 +1,64 @@
+/** Names (without `.ts`) of runtime helpers that can be embedded into generated output. */
+export type RuntimeHelperName = 'is-object' | 'validate-array' | 'validate-record' | 'has-ref'
+
+/** Controls how generated parsers reference their runtime helpers. */
+export type HelpersMode = 'package' | 'embedded'
+
+export type CollectedHelpers = {
+  /** Import lines to splice into the generated file. */
+  readonly imports: string[]
+  /**
+   * Helper names that need to ship alongside the generated file in embedded mode.
+   * Includes transitive deps (e.g. `validate-record` pulls in `is-object`) so the
+   * orchestrator can emit a complete `_helpers/` directory.
+   */
+  readonly used: Set<RuntimeHelperName>
+}
+
+const PACKAGE_IMPORTS: Record<RuntimeHelperName, string> = {
+  'is-object': "import { isObject } from '@amritk/helpers/is-object';",
+  'validate-array': "import { validateArray } from '@amritk/helpers/validate-array';",
+  'validate-record': "import { validateRecord } from '@amritk/helpers/validate-record';",
+  // hasRef has historically lived in the schema-guards subpath; preserve that for package mode.
+  'has-ref': "import { hasRef } from '@amritk/helpers/schema-guards';",
+}
+
+const EMBEDDED_IMPORTS: Record<RuntimeHelperName, string> = {
+  'is-object': "import { isObject } from './_helpers/is-object';",
+  'validate-array': "import { validateArray } from './_helpers/validate-array';",
+  'validate-record': "import { validateRecord } from './_helpers/validate-record';",
+  'has-ref': "import { hasRef } from './_helpers/has-ref';",
+}
+
+/** Detects which runtime helpers a generated parser body references. */
+export const collectHelpers = (parserFunction: string, mode: HelpersMode): CollectedHelpers => {
+  const imports: string[] = []
+  const used = new Set<RuntimeHelperName>()
+  const table = mode === 'embedded' ? EMBEDDED_IMPORTS : PACKAGE_IMPORTS
+
+  if (parserFunction.includes('validateArray')) {
+    imports.push(table['validate-array'])
+    used.add('validate-array')
+  }
+
+  if (parserFunction.includes('validateRecord')) {
+    imports.push(table['validate-record'])
+    used.add('validate-record')
+    // The embedded validate-record.ts imports is-object, so it must be shipped too —
+    // but only the `validate-record` line is needed in the parser file unless the
+    // parser body itself references `isObject` (handled below).
+    used.add('is-object')
+  }
+
+  if (parserFunction.includes('isObject')) {
+    imports.push(table['is-object'])
+    used.add('is-object')
+  }
+
+  if (parserFunction.includes('hasRef(')) {
+    imports.push(table['has-ref'])
+    used.add('has-ref')
+  }
+
+  return { imports, used }
+}

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

@@ -0,0 +1,587 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import { describe, expect, it } from 'vitest'
+
+import { collectImports } from './collect-imports'
+
+describe('collect-imports', () => {
+  it('collects imports from properties with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        contact: { $ref: '#/$defs/contact' },
+        server: { $ref: '#/$defs/server' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    ])
+  })
+
+  it('collects imports from array items with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        servers: {
+          type: 'array',
+          items: { $ref: '#/$defs/server' },
+        },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    ])
+  })
+
+  it('collects imports from additionalProperties with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        webhooks: {
+          type: 'object',
+          additionalProperties: { $ref: '#/$defs/path-item' },
+        },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type PathItemObject, parsePathItemObject, validatePathItemObjectShape } from './path-item';",
+    ])
+  })
+
+  it('collects imports from non-extension patternProperties with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      patternProperties: {
+        '^/': { $ref: '#/$defs/path-item' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type PathItemObject, parsePathItemObject, validatePathItemObjectShape } from './path-item';",
+    ])
+  })
+
+  it('collects imports from patternProperties with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      patternProperties: {
+        '^/': { $ref: '#/$defs/path-item' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type PathItemObject, parsePathItemObject, validatePathItemObjectShape } from './path-item';",
+    ])
+  })
+
+  it('collects imports from oneOf with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        response: {
+          oneOf: [{ $ref: '#/$defs/response' }, { $ref: '#/$defs/reference' }],
+        },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type ReferenceObject, parseReferenceObject, validateReferenceObjectShape } from './reference';",
+      "import { type ResponseObject, parseResponseObject, validateResponseObjectShape } from './response';",
+    ])
+  })
+
+  it('collects imports from anyOf with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        value: {
+          anyOf: [{ $ref: '#/$defs/string-value' }, { $ref: '#/$defs/number-value' }],
+        },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type NumberValueObject, parseNumberValueObject, validateNumberValueObjectShape } from './number-value';",
+      "import { type StringValueObject, parseStringValueObject, validateStringValueObjectShape } from './string-value';",
+    ])
+  })
+
+  it('collects imports from allOf with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        combined: {
+          allOf: [{ $ref: '#/$defs/base' }, { $ref: '#/$defs/extension' }],
+        },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type BaseObject, parseBaseObject, validateBaseObjectShape } from './base';",
+      "import { type ExtensionObject, parseExtensionObject, validateExtensionObjectShape } from './extension';",
+    ])
+  })
+
+  it('deduplicates imports by filename', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        contact1: { $ref: '#/$defs/contact' },
+        contact2: { $ref: '#/$defs/contact' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+    ])
+  })
+
+  it('collects imports from $ref properties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        response: { $ref: '#/$defs/response' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type ResponseObject, parseResponseObject, validateResponseObjectShape } from './response';",
+    ])
+  })
+
+  it('handles nested refs in complex schemas', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        servers: {
+          type: 'array',
+          items: { $ref: '#/$defs/server' },
+        },
+        callbacks: {
+          type: 'object',
+          additionalProperties: { $ref: '#/$defs/callback' },
+        },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type CallbackObject, parseCallbackObject, validateCallbackObjectShape } from './callback';",
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    ])
+  })
+
+  it('collects imports from root-level additionalProperties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      additionalProperties: { $ref: '#/$defs/path-item' },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type PathItemObject, parsePathItemObject, validatePathItemObjectShape } from './path-item';",
+    ])
+  })
+
+  it('imports SchemaObject parser and type from generated schema.ts', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        schema: { $ref: '#/$defs/schema' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type SchemaObject, parseSchemaObject, validateSchemaObjectShape } from './schema';",
+    ])
+  })
+
+  it('handles empty schema', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([])
+  })
+
+  it('handles schema without properties', () => {
+    const schema: JSONSchema = {
+      type: 'string',
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([])
+  })
+
+  it('collects imports from root-level allOf refs', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      allOf: [
+        { $ref: '#/$defs/security-scheme/$defs/type-apikey' },
+        { $ref: '#/$defs/security-scheme/$defs/type-http' },
+      ],
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type TypeApikeyObject, parseTypeApikeyObject, validateTypeApikeyObjectShape } from './type-apikey';",
+      "import { type TypeHttpObject, parseTypeHttpObject, validateTypeHttpObjectShape } from './type-http';",
+    ])
+  })
+
+  it('collects imports from all allOf $ref entries', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        contentType: { type: 'string' },
+      },
+      allOf: [{ $ref: '#/$defs/base-schema' }, { $ref: '#/$defs/styles-for-form' }],
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type BaseSchemaObject, parseBaseSchemaObject, validateBaseSchemaObjectShape } from './base-schema';",
+      "import { type StylesForFormObject, parseStylesForFormObject, validateStylesForFormObjectShape } from './styles-for-form';",
+    ])
+  })
+
+  it('generates type-only imports when typesOnly is true', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        contact: { $ref: '#/$defs/contact' },
+        server: { $ref: '#/$defs/server' },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual([
+      "import type { ContactObject } from './contact';",
+      "import type { ServerObject } from './server';",
+    ])
+  })
+
+  it('does not include parser names in type-only imports', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        contact: { $ref: '#/$defs/contact' },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual(["import type { ContactObject } from './contact';"])
+    expect(result[0]).not.toContain('parseContactObject')
+  })
+
+  it('collects type-only imports from $ref properties in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        response: { $ref: '#/$defs/response' },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual(["import type { ResponseObject } from './response';"])
+  })
+
+  it('generates type-only imports from array items $ref in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        servers: {
+          type: 'array',
+          items: { $ref: '#/$defs/server' },
+        },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual(["import type { ServerObject } from './server';"])
+  })
+
+  it('generates type-only imports from additionalProperties $ref in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      additionalProperties: { $ref: '#/$defs/path-item' },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual(["import type { PathItemObject } from './path-item';"])
+  })
+
+  it('generates type-only imports from anyOf $ref in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        value: {
+          anyOf: [{ $ref: '#/$defs/string-value' }, { $ref: '#/$defs/number-value' }],
+        },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual([
+      "import type { NumberValueObject } from './number-value';",
+      "import type { StringValueObject } from './string-value';",
+    ])
+  })
+
+  it('generates type-only imports from allOf $ref in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      allOf: [{ $ref: '#/$defs/base' }, { $ref: '#/$defs/extension' }],
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual([
+      "import type { BaseObject } from './base';",
+      "import type { ExtensionObject } from './extension';",
+    ])
+  })
+
+  it('deduplicates type-only imports by filename', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        contact1: { $ref: '#/$defs/contact' },
+        contact2: { $ref: '#/$defs/contact' },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual(["import type { ContactObject } from './contact';"])
+  })
+
+  it('returns empty array for schema with no $ref in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual([])
+  })
+
+  it('collects imports from root-level array items with $ref', () => {
+    const schema: JSONSchema = {
+      type: 'array',
+      items: { $ref: '#/$defs/server' },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    ])
+  })
+
+  it('collects imports from root-level array items $ref in typesOnly mode', () => {
+    const schema: JSONSchema = {
+      type: 'array',
+      items: { $ref: '#/$defs/parameter' },
+    }
+
+    const result = collectImports(schema, { typesOnly: true })
+
+    expect(result).toEqual(["import type { ParameterObject } from './parameter';"])
+  })
+
+  it('collects imports from root-level oneOf refs', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      oneOf: [{ $ref: '#/$defs/contact' }, { $ref: '#/$defs/server' }],
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toContain(
+      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+    )
+    expect(result).toContain(
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    )
+  })
+
+  it('collects imports from root-level anyOf refs', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      anyOf: [{ $ref: '#/$defs/contact' }, { $ref: '#/$defs/server' }],
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toContain(
+      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+    )
+    expect(result).toContain(
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    )
+  })
+
+  it('collects imports from root-level if branch', () => {
+    const schema: JSONSchema = {
+      if: { $ref: '#/$defs/contact' },
+      then: { type: 'object' },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toContain(
+      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+    )
+  })
+
+  it('collects imports from root-level then branch', () => {
+    const schema: JSONSchema = {
+      if: { type: 'object' },
+      then: { $ref: '#/$defs/server' },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toContain(
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    )
+  })
+
+  it('collects imports from root-level else branch', () => {
+    const schema: JSONSchema = {
+      if: { type: 'object' },
+      else: { $ref: '#/$defs/contact' },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toContain(
+      "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+    )
+  })
+
+  it('does not generate a self-import when a schema references its own $defs key via a property', () => {
+    // Mirrors the encoding schema: encoding.ts has a property `itemEncoding` that is a direct
+    // $ref back to #/$defs/encoding. Generating `import ... from './encoding'` inside encoding.ts
+    // would be a circular self-import that crashes at runtime.
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        itemEncoding: { $ref: '#/$defs/encoding' },
+        header: { $ref: '#/$defs/header' },
+      },
+    }
+
+    const result = collectImports(schema, { selfRef: '#/$defs/encoding' })
+
+    expect(result).not.toContain("'./encoding'")
+    expect(result).toContain(
+      "import { type HeaderObject, parseHeaderObject, validateHeaderObjectShape } from './header';",
+    )
+  })
+
+  it('does not generate a self-import when a schema references its own $defs key via additionalProperties', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        encoding: {
+          type: 'object',
+          additionalProperties: { $ref: '#/$defs/encoding' },
+        },
+      },
+    }
+
+    const result = collectImports(schema, { selfRef: '#/$defs/encoding' })
+
+    expect(result).not.toContain("'./encoding'")
+  })
+
+  it('does not generate a self-import when a schema references its own $defs key via array items', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        prefixEncoding: {
+          type: 'array',
+          items: { $ref: '#/$defs/encoding' },
+        },
+      },
+    }
+
+    const result = collectImports(schema, { selfRef: '#/$defs/encoding' })
+
+    expect(result).not.toContain("'./encoding'")
+  })
+
+  it('does not collect imports for external $refs', () => {
+    // External refs (e.g. from draft-04 schemas) cannot be resolved locally and have no generated file.
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        maximum: { $ref: 'http://json-schema.org/draft-04/schema#/properties/maximum' },
+        name: { type: 'string' },
+      },
+    }
+
+    const result = collectImports(schema)
+
+    expect(result).toEqual([])
+  })
+
+  it('does not generate a self-import in types-only mode', () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        itemEncoding: { $ref: '#/$defs/encoding' },
+        header: { $ref: '#/$defs/header' },
+      },
+    }
+
+    const result = collectImports(schema, { typesOnly: true, selfRef: '#/$defs/encoding' })
+
+    expect(result).not.toContain("'./encoding'")
+    expect(result).toContain("import type { HeaderObject } from './header';")
+  })
+})