@amritk/generate-parsers 0.7.1 → 0.8.0

package/src/helpers/collect-helpers.ts

@@ -1,79 +0,0 @@
-/** 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_NAMED_EXPORTS: Record<RuntimeHelperName, string> = {
-  'is-object': 'isObject',
-  'validate-array': 'validateArray',
-  'validate-record': 'validateRecord',
-  'has-ref': 'hasRef',
-}
-
-const embeddedImport = (helper: RuntimeHelperName, prefix: string): string =>
-  `import { ${EMBEDDED_NAMED_EXPORTS[helper]} } from '${prefix}_helpers/${helper}';`
-
-/**
- * Detects which runtime helpers a generated parser body references.
- *
- * @param helpersImportPrefix - Relative path prefix to the shared `_helpers/`
- *   directory in embedded mode. Defaults to `'./'`. The recursive multi-schema
- *   build passes `'../'`, `'../../'`, etc. so nested parsers can reach a single
- *   `_helpers/` directory at the output root.
- */
-export const collectHelpers = (
-  parserFunction: string,
-  mode: HelpersMode,
-  helpersImportPrefix = './',
-): CollectedHelpers => {
-  const imports: string[] = []
-  const used = new Set<RuntimeHelperName>()
-  const importFor = (helper: RuntimeHelperName): string =>
-    mode === 'embedded' ? embeddedImport(helper, helpersImportPrefix) : PACKAGE_IMPORTS[helper]
-
-  if (parserFunction.includes('validateArray')) {
-    imports.push(importFor('validate-array'))
-    used.add('validate-array')
-  }
-
-  if (parserFunction.includes('validateRecord')) {
-    imports.push(importFor('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(importFor('is-object'))
-    used.add('is-object')
-  }
-
-  if (parserFunction.includes('hasRef(')) {
-    imports.push(importFor('has-ref'))
-    used.add('has-ref')
-  }
-
-  return { imports, used }
-}

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

@@ -1,547 +0,0 @@
-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 Contact, parseContact, validateContactShape } from './contact';",
-      "import { type Server, parseServer, validateServerShape } 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 Server, parseServer, validateServerShape } 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 PathItem, parsePathItem, validatePathItemShape } 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 PathItem, parsePathItem, validatePathItemShape } 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 PathItem, parsePathItem, validatePathItemShape } 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 Reference, parseReference, validateReferenceShape } from './reference';",
-      "import { type Response, parseResponse, validateResponseShape } 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 NumberValue, parseNumberValue, validateNumberValueShape } from './number-value';",
-      "import { type StringValue, parseStringValue, validateStringValueShape } 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 Base, parseBase, validateBaseShape } from './base';",
-      "import { type Extension, parseExtension, validateExtensionShape } 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 Contact, parseContact, validateContactShape } 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 Response, parseResponse, validateResponseShape } 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 Callback, parseCallback, validateCallbackShape } from './callback';",
-      "import { type Server, parseServer, validateServerShape } 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 PathItem, parsePathItem, validatePathItemShape } from './path-item';"])
-  })
-
-  it('imports Schema 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 Schema, parseSchema, validateSchemaShape } 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 TypeApikey, parseTypeApikey, validateTypeApikeyShape } from './type-apikey';",
-      "import { type TypeHttp, parseTypeHttp, validateTypeHttpShape } 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 BaseSchema, parseBaseSchema, validateBaseSchemaShape } from './base-schema';",
-      "import { type StylesForForm, parseStylesForForm, validateStylesForFormShape } 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 { Contact } from './contact';", "import type { Server } 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 { Contact } from './contact';"])
-    expect(result[0]).not.toContain('parseContact')
-  })
-
-  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 { Response } 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 { Server } 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 { PathItem } 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 { NumberValue } from './number-value';",
-      "import type { StringValue } 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 { Base } from './base';", "import type { Extension } 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 { Contact } 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 Server, parseServer, validateServerShape } 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 { Parameter } 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 Contact, parseContact, validateContactShape } from './contact';")
-    expect(result).toContain("import { type Server, parseServer, validateServerShape } 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 Contact, parseContact, validateContactShape } from './contact';")
-    expect(result).toContain("import { type Server, parseServer, validateServerShape } 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 Contact, parseContact, validateContactShape } 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 Server, parseServer, validateServerShape } 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 Contact, parseContact, validateContactShape } 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 Header, parseHeader, validateHeaderShape } 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 { Header } from './header';")
-  })
-})