ajsc 5.2.4 → 7.1.0

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to ajsc are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project follows [Semantic Versioning](https://semver.org/).
+
+## [7.0.0] — 2026-04-24
+
+This release adds first-class **Kotlin** and **Swift** language targets, restores the root subpath import that v6 dropped, and ships several behavioral fixes to the TypeScript converter that consumers depending on the older buggy output may need to migrate.
+
+### Added
+
+- **Kotlin converter** (`ajsc/kotlin`, or `emitKotlin` from `ajsc`).
+  - Emits idiomatic `data class` declarations.
+  - Default `serializer: "kotlinx"` adds `@Serializable`, `@SerialName`, `@Contextual`. Pass `serializer: "none"` for plain types.
+  - Discriminated `oneOf`/`anyOf` unions emit as `sealed interface` with `@JsonClassDiscriminator`.
+  - JVM stdlib type mapping for date-time (`java.time.Instant`), uuid (`java.util.UUID`), uri (`java.net.URI`), date / time.
+  - `Pair<A,B>` / `Triple<A,B,C>` for 2- and 3-element tuples.
+  - `packageName` option emits a `package …` line at the top of the output.
+- **Swift converter** (`ajsc/swift`, or `emitSwift` from `ajsc`).
+  - Emits `struct` declarations with `: Codable` conformance by default.
+  - Foundation stdlib mapping (`Date`, `UUID`, `URL`).
+  - Discriminated unions emit as `enum` with associated values, including a hand-written `init(from:)` and `encode(to:)` that dispatch by the schema's discriminator field.
+  - `CodingKeys` blocks generated when JSON keys differ from Swift property names.
+  - Acronym preservation in enum case names: `case US` rather than `case uS = "US"`.
+  - `accessLevel` option (`"public"` default, `"internal"` available).
+- **Top-level emit functions** at the package root: `emitTypescript`, `emitKotlin`, `emitSwift`, plus the shared `EmitResult` type.
+- **`nameRegistry` and `namePrefix` opts** on `BaseConverterOpts`. Pass a shared `Set<string>` across multiple emit calls so types extracted from sibling schemas don't collide when concatenated into a single Kotlin `object` or Swift `enum` namespace. `namePrefix` prepends a per-slot prefix to extracted (nested) type names — `BodyAddress` vs `ResponseAddress` rather than `Address` vs `Address2`. See README "Emitting multiple schemas into one namespace" for the recommended pattern. Most useful for Kotlin and Swift; harmless for TypeScript.
+- **`ajsc/converter` subpath** for downstream extension authors. Exports `BaseConverter`, `Emitter`, `walkIR`, `LanguageProfile`, `BaseConverterContext`, `RefTypeEntry`, and `BaseConverterOpts`.
+- **`rootTypeName` option** on every converter — overrides the schema-derived root name without modifying the schema.
+- **Introspection fields** on every converter: `rootTypeName: string`, `extractedTypeNames: string[]`, `imports: string[]`. Codegen pipelines can reference emitted type names without parsing the `code` string.
+- **Architecture documentation** at `docs/architecture/README.md` — data flow, layered class hierarchy, `LanguageProfile` pattern, per-language module structure, and the steps to add a new language target.
+- **Cross-language fixture corpus** of 18 schemas with 54 golden output files (TS + Kotlin + Swift) under `src/integrations/fixtures/`.
+- **JSON Schema 2020-12 `prefixItems`** treated as equivalent to legacy array-form `items`.
+- **Schema-level `default`** now propagated to Kotlin/Swift property declarations for primitive defaults (`val foo: String = "x"`, `let foo: Int64 = 0`).
+- **Format `int32`** is now honored: emits `Int` (Kotlin) and `Int32` (Swift) where previously these always emitted `Long` / `Int64`.
+- **Root-level enum schemas** (`{ type: "string", enum: [...] }`) now emit as `enum class` (Kotlin) and `public enum: String, Codable` (Swift), instead of empty data classes/structs.
+
+### Changed (breaking — TypeScript output)
+
+- **`$ref: "#"` recursion in TypeScript** now emits direct self-reference. A schema like `{ "title": "Tree", "properties": { "children": { "type": "array", "items": { "$ref": "#" } } } }` now produces:
+  ```ts
+  export type Tree = { children?: Array<Tree>; };
+  ```
+  instead of the previous bifurcated form (`Child` extracted with `Array<any>` recursion). Consumers depending on the old `Child` extracted type by name will need to update.
+- **`anyOf` merge** preserves the parent's `required` flag. A required schema field that gets anyOf-merged is now non-optional in output. Example:
+  ```ts
+  // before:  actor?: Actor
+  // after:   actor: Actor
+  ```
+- **`oneOf` variant naming in TypeScript** uses discriminator-derived names. A schema with two oneOf variants `{ kind: "wrapper" }` / `{ kind: "scalar" }` now emits `WrapperOuter` / `ScalarOuter` rather than collision-suffixed `Outer` / `OuterType`. Kotlin and Swift have always produced discriminator-derived names; this brings TypeScript into alignment.
+
+### Changed (breaking — extension API)
+
+- **`./converter` subpath public surface refactored.** Most consumers won't notice — only authors who subclassed `BaseConverter` to override hook methods.
+  - 9 separate `protected` hook methods (`shouldEraseDiscriminator`, `processOneOfAsDiscriminatedUnion`, `getDiscriminatedVariantParentName`, `shouldPopulateDiscriminatorInfo`, `detectSelfReferenceToRoot`, etc.) consolidated into a single `protected readonly languageProfile: LanguageProfile` field. See `docs/architecture/README.md` for the migration pattern.
+  - `RefTypes` is now `RefTypeEntry[]` (array of named records) instead of a tuple-of-tuples. Access changes from `entry[2].code` → `entry.code`, `[_s, name, { code }]` destructure → `{ name, code }`.
+  - Several previously-protected helper methods (`findDiscriminatorProperty`, `collectUnionPropertyNames`, `stripDiscriminatorField`, `getConstStringValue`, `findAvailableName`) are now public (with `@internal` JSDoc) so they can be referenced by helper-module Context interfaces.
+  - **`BaseConverterContext` interface** introduced as the surface helper modules operate on. `BaseConverter implements BaseConverterContext`. Helper modules in `src/converter/` (`registry.ts`, `naming.ts`, `mergeUnions.ts`, `discriminatedUnions.ts`, `walk.ts`) take a `BaseConverterContext` rather than the abstract class, decoupling helpers from the class hierarchy.
+  - **Per-language `<Lang>ConverterContext` interfaces** (`KotlinConverterContext`, `SwiftConverterContext`) extend `BaseConverterContext` with language-specific state and methods. The Kotlin and Swift converter classes `implements` their respective Context interface; helper modules in `src/kotlin/` and `src/swift/` take the interface. Replaces the prior `_x` accessor wrapper pattern with a single declarative interface.
+
+### Changed (non-breaking)
+
+- **Swift discriminated-enum emission** uses consistent 4-space indentation throughout (previously had 4/8-space mismatches in `init(from:)` / `encode(to:)` blocks).
+- **Kotlin module structure** split into focused files: `typeMapper.ts`, `objectEmitter.ts`, `sealedUnion.ts`, `enums.ts`, `unsupported.ts`, `annotations.ts`. Pure internal refactor; no public API change.
+- **Swift module structure** split into focused files: `typeMapper.ts`, `structEmitter.ts`, `discriminatedEnum.ts`, `enums.ts`, `unsupported.ts`. Pure internal refactor.
+- **`BaseConverter` split** into focused files: `walk.ts`, `naming.ts`, `registry.ts`, `mergeUnions.ts`, `discriminatedUnions.ts`. Pure internal refactor.
+
+### Fixed
+
+- **Kotlin `init` reserved word** — was missing from `KOTLIN_RESERVED`; properties named `init` now correctly emit as `init_`.
+- **Swift acronym case names** — `case US` instead of `case uS = "US"` for all-uppercase enum values.
+- **Schema `default`** is no longer silently dropped in Kotlin and Swift output for primitive defaults.
+
+### Removed
+
+- The `dart` keyword from `package.json` keywords (no Dart converter is available; misleading for npm discoverability).
+
+### Internal
+
+- 90+ commits since v6.0.0. Test count grew from 188 → 473.
+- New regression-net pattern: vitest snapshots of the kitchen-sink schema (`_baseline-snapshot.test.ts.snap`) catch any drift in TS converter output across refactors. Used throughout this release as the gate for the `BaseConverter` refactor.
+- Cross-language golden fixtures (18 schemas × 3 languages = 54 goldens) protect against drift.
+- Cross-call integration tests (`src/__tests__/cross-call-name-registry.test.ts`, `src/__tests__/multi-call-integration.test.ts`) lock in the orchestration pattern for downstream codegen pipelines.
+
+### Known follow-ups (deferred to a future release)
+
+These were surfaced during v7 development but intentionally not implemented to keep the release scope focused. Real, agreed-on next steps:
+
+- **`EmitSession` API**: an emit-session object that bundles `nameRegistry` plus `refTypes` across multiple calls so identical schema shapes (e.g., the same `address` structure in both `body` and `response`) emit as a single declaration referenced from both slots. The current `nameRegistry` fix avoids compile errors but emits structurally-identical types twice (`BodyAddress`, `ResponseAddress`). A session API would dedupe at the structural level.
+- **Smart `namePrefix`**: prefix extracted names only when they would collide, instead of unconditionally. Today, `namePrefix: "Body"` produces `BodyAddress`, `BodyContact`, `BodySettings` even when only `Address` actually collides with another slot. A two-pass approach (collect names, detect overlaps, prefix the conflicting ones) would give more ergonomic output.
+- **Cross-call collision fallback**: when `nameRegistry` is set without `namePrefix`, prefer numeric suffix (`Address2`) over postfix-list (`AddressType`) fallbacks. The postfix list was designed for single-call path-escalation; in cross-call mode, postfix names become semantically misleading.
+- **`additionalItems` support**: tuple-form `items: [...]` plus `additionalItems: { ... }` is currently silently dropped.
+- **Schema `examples` lifting**: currently dropped (no clean target idiom across all three languages).
+- **`@internal` accessor consolidation**: `BaseConverter` exposes several public-with-`@internal` methods (`findDiscriminatorProperty`, `collectUnionPropertyNames`, etc.) for the `BaseConverterContext` interface. They work but the `@internal` JSDoc isn't enforced. A `Symbol`-keyed accessor pattern or a separate "internal" module would prevent downstream code from depending on them.
+
+---
+
+## [6.0.0] — earlier
+
+Reorganized `src` by feature and switched to subpath exports. The previous root barrel (`import { TypescriptConverter } from "ajsc"`) stopped resolving in v6. (v7 restores the root entry; see [Migrating from v6 to v7](./README.md#migrating-from-v6-to-v7).)
+
+## [5.x] — earlier
+
+Earlier releases. See `git log` for detail.

package/README.md

@@ -1,198 +1,357 @@
-# ajsc - Another JSON Schema Parser
+# ajsc — Another JSON Schema Converter
 
-**ajsc** is an npm package that transforms JSON Schema definitions into an intermediate representation (IR) called `IRNode`. This intermediate form is designed to be consumed by language-specific converters—such as the built-in [TypeScript converter](#typescriptconverter)—or by any custom converter you create for languages like Kotlin or Swift. This library streamlines the process of converting API JSON Schema definitions into strong-typed code representations, ensuring consistency between your API contracts and client implementations.
+**ajsc** transforms JSON Schema documents into idiomatic, language-native code for **TypeScript**, **Kotlin**, and **Swift**. It exposes a small function-style API for typical codegen pipelines, plus class-based converters for advanced extension.
 
----
+```bash
+npm install ajsc
+```
 
-## Features
+```ts
+import { emitTypescript, emitKotlin, emitSwift } from "ajsc";
 
-- **Comprehensive Schema Parsing:**  
-  Convert JSON Schema types including strings, numbers, booleans, nulls, literals, enums, unions, intersections, arrays, and objects into a unified IR.
+const schema = {
+  title: "User",
+  type: "object",
+  properties: {
+    id:    { type: "integer" },
+    name:  { type: "string" },
+    email: { type: "string", format: "email" },
+  },
+  required: ["id", "name"],
+};
 
-- **Intermediate Representation (`IRNode`):**  
-  The `IRNode` provides a standard structure that captures type, constraints, and path information. This representation is ideal for further transformation into various target languages.
+const ts = emitTypescript(schema);
+const kt = emitKotlin(schema);
+const sw = emitSwift(schema);
+```
 
-- **Plugin-Based Architecture:**  
-  Use the provided language plugin (currently, a [TypeScript converter](#typescriptconverter)) or write your own converter to support additional languages such as Kotlin or Swift.
+Each emit function returns the same shape:
 
-- **$defs and References Handling:**  
-  Resolve JSON Schema definitions (`$defs`) and references (`$ref`) seamlessly, ensuring reusable schema components are properly processed.
+```ts
+interface EmitResult {
+  code: string;                   // declarations only — no `import` lines
+  rootTypeName: string;           // top-level emitted type ("User")
+  extractedTypeNames: string[];   // additional types emitted (nested objects, enums, variants)
+  imports: string[];              // language-native module/symbol paths to import
+}
+```
 
-- **Unique Signature Tracking:**  
-  For objects and arrays, the library tracks unique signatures to avoid duplicate type definitions when converting to code.
+`code` contains type declarations only. Consumers assemble the final source file by combining `imports` with `code`.
 
 ---
 
-## Installation
+## Output examples
 
-Install **ajsc** via npm:
+### TypeScript
 
-```bash
-npm install ajsc
+```ts
+import { emitTypescript } from "ajsc";
+
+const { code } = emitTypescript({
+  title: "User", type: "object",
+  properties: { id: { type: "integer" }, name: { type: "string" } },
+  required: ["id", "name"],
+});
+
+// code:
+// export type User = { id: number; name: string; };
 ```
 
-## Usage
+### Kotlin (default: kotlinx-serialization)
+
+```ts
+import { emitKotlin } from "ajsc";
+
+const { code, imports } = emitKotlin({
+  title: "User", type: "object",
+  properties: { id: { type: "integer" }, name: { type: "string" } },
+  required: ["id", "name"],
+});
+
+// imports: ["kotlinx.serialization.Serializable"]
+// code:
+// @Serializable
+// data class User(
+//   val id: Long,
+//   val name: String,
+// )
+```
 
-### Basic Conversion to IRNode
+Pass `serializer: "none"` for plain types with no annotations.
 
-The primary function of ajsc is to convert a JSON Schema into an IRNode. Here’s an example of converting a simple JSON Schema that defines a string type:
+### Swift (default: Codable)
 
-```javascript
-import { JSONSchemaConverter } from "ajsc";
+```ts
+import { emitSwift } from "ajsc";
 
-const schema = { type: "string" };
-const converter = new JSONSchemaConverter(schema);
+const { code, imports } = emitSwift({
+  title: "User", type: "object",
+  properties: { id: { type: "integer" }, name: { type: "string" } },
+  required: ["id", "name"],
+});
 
-console.log(converter.irNode);
-// Output:
-// {
-//   type: "string",
-//   constraints: {},
-//   path: "",
+// imports: []
+// code:
+// public struct User: Codable {
+//   public let id: Int64
+//   public let name: String
 // }
 ```
 
-Converting Complex Schemas
-You can also convert more complex schemas including objects, arrays, unions, intersections, and even schemas with $defs:
-
-```javascript
-import { JSONSchemaConverter } from "ajsc";
-
-const complexSchema = {
-  $defs: {
-    Person: {
-      type: "object",
-      properties: {
-        name: { type: "string" },
-        age: { type: "number" },
-      },
-      required: ["name"],
-    },
-  },
-  type: "object",
-  properties: {
-    person: { $ref: "#/$defs/Person" },
-  },
-};
+Pass `serializer: "none"` to drop `Codable` conformance.
 
-const converter = new JSONSchemaConverter(complexSchema);
-console.log(converter.irNode);
+### Assembling a final file
+
+```ts
+const { code, imports } = emitKotlin(schema);
+const file = [...imports.map((i) => `import ${i}`), "", code].join("\n");
 ```
 
-## API Reference
+Swift `imports` are module names (`["Foundation"]`); Kotlin `imports` are fully-qualified symbol paths. TypeScript `imports` is always empty.
 
-### JSONSchemaConverter
+---
 
-- Constructor:
-  `new JSONSchemaConverter(schema: object)`
-- Properties:
-  - irNode: The resulting intermediate representation of the JSON Schema.
-- Supported Schema Types:
-  - Primitive Types: string, number, boolean, null
-  - Literals: Using the const keyword.
-  - Enums: Using the enum property.
-  - Unions: When type is an array (e.g., ["string", "number"]).
-  - Intersections: Using allOf to combine multiple schemas.
-  - Arrays: With type: "array" and an items schema.
-  - Objects: With type: "object" and a properties definition.
-  - $defs and $ref: For defining and referencing reusable schema parts.
+## Package layout
 
-### TypescriptConverter
+| Subpath          | Exports                                                                                                |
+|------------------|--------------------------------------------------------------------------------------------------------|
+| `ajsc`           | `emitTypescript`, `emitKotlin`, `emitSwift`, `EmitResult`, plus the converter classes (re-exported)    |
+| `ajsc/typescript`| `TypescriptConverter`, `TypescriptBaseConverter`, related types                                        |
+| `ajsc/kotlin`    | `KotlinConverter`, `KotlinBaseConverter`, `sanitizeKotlinIdentifier`, `KOTLIN_RESERVED`                |
+| `ajsc/swift`     | `SwiftConverter`, `SwiftBaseConverter`, `sanitizeSwiftIdentifier`, `SWIFT_RESERVED`                    |
+| `ajsc/converter` | `BaseConverter`, `Emitter`, `walkIR`, `LanguageProfile`, `BaseConverterOpts`, `RefTypeEntry`, etc.     |
+| `ajsc/ir`        | `JSONSchemaConverter` (JSON Schema → IRNode tree)                                                      |
+| `ajsc/types`     | `IRNode`, `ILanguageConverter`, signature types                                                        |
+| `ajsc/utils`     | `PathUtils`, `toPascalCase`                                                                            |
+
+The root (`ajsc`) is the typical entry point. Subpaths are for advanced use — extending a converter, accessing the IR layer, building a custom language target.
+
+---
 
-The package includes a TypeScript language plugin that converts the IRNode into TypeScript type definitions.
+## Function-style vs class-style
+
+```ts
+// Function-style — recommended for most consumers.
+import { emitKotlin } from "ajsc";
+const result = emitKotlin(schema, opts);
+
+// Class-style — for subclassing or accessing converter internals.
+import { KotlinConverter } from "ajsc/kotlin";
+const converter = new KotlinConverter(schema, opts);
+console.log(converter.code, converter.imports);
+```
+
+Both produce identical output; the function form just bundles `code`, `rootTypeName`, `extractedTypeNames`, `imports` into a single return value. For codegen pipelines, the function form is usually nicer — it avoids the `new` and gives a stable result shape.
+
+---
 
-- Constructor:
-  `new TypescriptConverter(schema: object, options?: TypescriptConverterOpts)`
-- Properties:
-  - code: A string containing the generated TypeScript code.
+## Options
 
-#### Options
+All three converters accept `BaseConverterOpts` plus language-specific options.
+
+### Shared options (`BaseConverterOpts`)
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `inlineTypes` | `boolean` | `false` | If true, object types are inlined instead of extracted as named type aliases. |
-| `depluralize` | `boolean` | `true` | Singularize array item type names. Handles irregular plurals (e.g. `entries` → `Entry`, `people` → `Person`). |
-| `arrayItemNaming` | `string \| false` | `false` | Controls the postfix for array item type names. `false` = no postfix, `string` = custom postfix (e.g. `"Item"` → `ContactItem`). |
-| `enumStyle` | `"union" \| "enum"` | `"union"` | `"union"` emits `"a" \| "b"`, `"enum"` emits `export enum`. Only applies when `inlineTypes` is false and all values are strings. |
-| `uncountableWords` | `string[]` | `undefined` | Additional words that should not be singularized (built-in: `"data"`, `"metadata"`). |
+| `rootTypeName` | `string` | `schema.title \|\| "Root"` | Override the top-level type name. |
+| `arrayItemNaming` | `string \| false` | `false` | Postfix for array-item type names. `false` = property name, `"Item"` = `ContactsItem`. |
+| `depluralize` | `boolean` | `true` | Singularize array-item path segments (`entries` → `Entry`). |
+| `uncountableWords` | `string[]` | `[]` | Words to skip when singularizing. Built-ins: `data`, `metadata`. |
+| `unsupportedUnions` | `"throw" \| "fallback"` | `"throw"` | What to do with untagged unions: throw with a path-bearing error, or emit a language fallback type (`JsonElement` / `AnyCodable` / `any`). |
 
-#### Usage Examples
+### TypeScript (`TypescriptConverterOpts`)
 
-Default behavior — array item types are automatically singularized:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `inlineTypes` | `boolean` | `false` | If true, nested object types are inlined rather than extracted to named aliases. |
+| `enumStyle` | `"union" \| "enum"` | `"union"` | `"union"` emits `"a" \| "b" \| "c"`; `"enum"` emits `export enum Status { ... }`. |
+| `jsdoc` | `boolean` | `false` | Emit JSDoc comments from JSON Schema `description` and `title`. Requires `inlineTypes: false`. |
 
-```javascript
-import { TypescriptConverter } from "ajsc";
+### Kotlin (`KotlinConverterOpts`)
 
-const schema = {
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    age: { type: "number" },
-    contacts: {
-      type: "array",
-      items: {
-        type: "object",
-        properties: {
-          email: { type: "string" },
-        },
-        required: ["email"],
-      },
-    },
-    profile: {
-      type: "object",
-      properties: {
-        email: { type: "string" },
-      },
-      required: ["email"],
-    },
-  },
-  required: ["name", "age"],
-};
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serializer` | `"kotlinx" \| "none"` | `"kotlinx"` | Emit `@Serializable`/`@SerialName`/`@Contextual` annotations and matching imports. `"none"` emits plain types. |
+| `packageName` | `string` | `undefined` | If set, emit `package <name>` at the top of the output. |
 
-const tsConverter = new TypescriptConverter(schema);
-console.log(tsConverter.code);
+### Swift (`SwiftConverterOpts`)
 
-// Output:
-// export type Contact = { email: string; };
-// export type Profile = { email: string; };
-//
-// export type Root = { name: string; age: number; contacts?: Array<Contact>; profile?: Profile; };
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serializer` | `"codable" \| "none"` | `"codable"` | Emit `: Codable` conformance, `CodingKeys` enums, and discriminated-union `init(from:)`/`encode(to:)` plumbing. `"none"` emits plain types. |
+| `accessLevel` | `"public" \| "internal"` | `"public"` | Access modifier on emitted types and members. |
+
+---
+
+## Type mapping
+
+### TypeScript
+
+JSON Schema → idiomatic TS. `string` → `string`, `integer` → `number`, etc. Discriminated `oneOf`/`anyOf` → tagged union types. `$ref: "#"` → direct self-reference.
+
+### Kotlin (target: JVM)
+
+| JSON Schema | Kotlin | Notes |
+|-------------|--------|-------|
+| `string` | `String` | |
+| `string, format: date-time` | `java.time.Instant` | `@Contextual` under kotlinx |
+| `string, format: date` / `time` | `java.time.LocalDate` / `LocalTime` | `@Contextual` under kotlinx |
+| `string, format: uuid` | `java.util.UUID` | `@Contextual` under kotlinx |
+| `string, format: uri` | `java.net.URI` | `@Contextual` under kotlinx |
+| `string, format: email` / `hostname` / `ipv4` / `ipv6` | `String` + KDoc note | |
+| `integer` | `Long` | `format: int32` → `Int` |
+| `number` | `Double` | |
+| `boolean` | `Boolean` | |
+| `array` | `List<T>` | |
+| `object` | `data class` | `@Serializable` under kotlinx |
+| `enum` (string) | `enum class` | `@Serializable` under kotlinx |
+| `oneOf` w/ discriminator | `sealed interface` | `@JsonClassDiscriminator` under kotlinx |
+| Tuple length 2 / 3 | `Pair<A,B>` / `Triple<A,B,C>` | length > 3 throws |
+
+### Swift
+
+| JSON Schema | Swift | Notes |
+|-------------|-------|-------|
+| `string` | `String` | |
+| `string, format: date-time` | `Foundation.Date` | requires `JSONDecoder.dateDecodingStrategy = .iso8601` |
+| `string, format: uuid` | `Foundation.UUID` | |
+| `string, format: uri` | `Foundation.URL` | |
+| `string, format: email` etc. | `String` + `///` doc note | |
+| `integer` | `Int64` | `format: int32` → `Int32` |
+| `number` | `Double` | |
+| `boolean` | `Bool` | |
+| `array` | `[T]` | |
+| `object` | `struct` | `: Codable` by default |
+| `enum` (string) | `enum: String, Codable` | raw-value enum |
+| `oneOf` w/ discriminator | `enum` w/ associated values | hand-rolled `init(from:)`/`encode(to:)` |
+| Tuple (homogeneous) | `[T]` | |
+| Tuple (heterogeneous, codable) | throws | use `serializer: "none"` for native tuples |
+
+Schema-level `default` values are emitted inline for primitive types in Kotlin/Swift (`val foo: String = "x"`, `let foo: Int64 = 0`).
+
+---
+
+## Emitting multiple schemas into one namespace
+
+Codegen pipelines that emit several sibling schemas into a shared output (e.g., wrapping an endpoint's `pathParams`, `query`, `body`, `response`, and error types under a single Kotlin `object` or Swift `enum`) need to avoid duplicate-name collisions across the emit calls. Each emit call has its own private name-tracking state by default, so two slots with a nested `address: { type: "object" }` would each emit a `data class Address(...)` — a duplicate-class compile error in the merged output.
+
+Pass a shared `nameRegistry: Set<string>` across calls. The converter uses it as its declaration registry and mutates it as new types are emitted. Pair with `namePrefix` for clean per-slot names:
+
+```ts
+import { emitKotlin } from "ajsc";
+
+const registry = new Set<string>();
+
+const body = emitKotlin(bodySchema, {
+  nameRegistry: registry,
+  namePrefix: "Body",
+  rootTypeName: "Body",
+});
+
+const response = emitKotlin(responseSchema, {
+  nameRegistry: registry,
+  namePrefix: "Response",
+  rootTypeName: "Response",
+});
+
+// body.code:     `data class Body(...)` + `data class BodyAddress(...)`
+// response.code: `data class Response(...)` + `data class ResponseAddress(...)`
+// Concatenated under one `object Endpoint { ... }` — no name collisions.
 ```
 
-Inline types (no extracted type aliases):
+### Without `namePrefix`
+
+You can pass `nameRegistry` alone — collisions still resolve correctly via the standard fallback path. But the resulting names are awkward:
 
-```javascript
-const tsConverter = new TypescriptConverter(schema, { inlineTypes: true });
-console.log(tsConverter.code);
+```ts
+const registry = new Set<string>();
+emitKotlin(bodySchema,     { nameRegistry: registry, rootTypeName: "Body" });
+emitKotlin(responseSchema, { nameRegistry: registry, rootTypeName: "Response" });
 
-// Output:
-// { name: string; age: number; contacts?: Array<{ email: string; }>; profile?: { email: string; }; }
+// body emits:     `data class Address(...)`         ← bare name (first-come-first-served)
+// response emits: `data class AddressType(...)`     ← postfix fallback (semantically wrong)
 ```
 
-Enum style:
+`AddressType` is a literal type name in the emitted Kotlin/Swift — but it's not a "type of address," it's just another `Address`. The fallback exists because path-collision escalation was designed for single-call use; in cross-call scenarios where every slot's path looks the same, the fallback fires immediately. **Recommendation: always pair `nameRegistry` with a per-slot `namePrefix`.** That's the pattern shown above and the one the integration tests assert against.
 
-```javascript
-const enumSchema = {
-  type: "object",
-  properties: {
-    status: { type: "string", enum: ["active", "inactive", "pending"] },
-  },
-};
+### Notes
+
+`namePrefix` does **not** affect the root type name (use `rootTypeName` for that). It only applies to extracted nested types, and it's applied unconditionally — every nested type gets the prefix, not just colliding ones. That can produce slightly verbose names for unique types (e.g. `BodyContact` even when no other slot has a `Contact`), but it's predictable and avoids the alternative's two-pass complexity.
+
+Both `nameRegistry` and `namePrefix` work for all three languages. They're most useful for Kotlin and Swift, which require named declarations for non-primitive types. TypeScript supports them too but rarely needs them — most codegen pipelines use `inlineTypes: true` to flatten nested types instead.
+
+---
+
+## Working with the IR directly
 
-const tsConverter = new TypescriptConverter(enumSchema, { enumStyle: "enum" });
-console.log(tsConverter.code);
+If you need the intermediate representation (e.g., to write a custom emitter), use `JSONSchemaConverter`:
 
-// Output:
-// export enum Status { Active = "active", Inactive = "inactive", Pending = "pending" }
-//
-// export type Root = { status?: Status; };
+```ts
+import { JSONSchemaConverter } from "ajsc/ir";
+
+const ir = new JSONSchemaConverter({ type: "string" }).irNode;
+// { type: "string", path: "", constraints: {} }
 ```
 
-Custom uncountable words:
+`IRNode` shape is documented in `ajsc/types`.
 
-```javascript
-const tsConverter = new TypescriptConverter(schema, {
-  uncountableWords: ["criteria", "alumni"],
-});
-// "criteria" array items will produce type "Criteria", not "Criterium"
+## Building a custom language emitter
+
+To target a new language, extend `BaseConverter`:
+
+```ts
+import { BaseConverter, type LanguageProfile } from "ajsc/converter";
+
+class DartConverter extends BaseConverter {
+  protected readonly languageProfile: LanguageProfile = {
+    language: "dart",
+    // ... per-language overrides
+  };
+  // ... implement generateObjectType and the emission orchestration
+}
+```
+
+See `docs/architecture/README.md` for the layered design — `BaseConverter`, the `LanguageProfile` pattern, and the per-language helper module conventions used by Kotlin and Swift.
+
+---
+
+## Migrating from v6 to v7
+
+### Breaking changes
+
+These are output changes for existing consumers. They're behavioral fixes, not regressions, but if you've been depending on the older shapes you'll see diffs:
+
+- **`$ref: "#"` recursion** in TypeScript now emits direct self-reference (`Array<Tree>`) rather than a buggy `Child` extraction with `Array<any>` recursion.
+- **`anyOf` merge** preserves the parent's `required` flag. A required schema field that gets anyOf-merged is now non-optional in output (`actor: Actor` instead of `actor?: Actor`).
+- **`oneOf` variant naming** in TypeScript now uses discriminator-derived names (`WrapperOuter`, `ScalarOuter`) rather than path-collision suffix names (`Outer`, `OuterType`). Kotlin and Swift always used the discriminator-derived form; this brings TS into alignment.
+- **`format: int32`** is now honored: emits `Int` (Kotlin) and `Int32` (Swift) where previously these always emitted `Long`/`Int64`. `format: int64` and unset format both still emit `Long`/`Int64`.
+- **Schema-level `default`** is now emitted in Kotlin and Swift property declarations for primitive defaults (`val foo: String = "x"`). TS output is unchanged.
+- **Swift acronym preservation**: enum case names for all-uppercase tokens (`US`, `URL`, `ID`) are no longer lowerCamelCased (`uS`/`uRL`/`iD`). They're preserved as-is.
+- **`./converter` extension API** has been heavily refactored. If you subclassed `BaseConverter` to override hook methods, see the new `LanguageProfile` pattern in `docs/architecture/README.md`. Most legacy hook overrides should migrate to a single `protected readonly languageProfile` field.
+
+### New features
+
+- **Kotlin and Swift converters.** First-class language targets, not just IR.
+- **Top-level emit functions.** `emitTypescript`, `emitKotlin`, `emitSwift` from `"ajsc"`.
+- **`./converter` subpath** for downstream extension authors.
+- **Root subpath restored.** `import { TypescriptConverter } from "ajsc"` works again (was subpath-only in v6).
+
+### Migrating v5 → v7
+
+If you're still on v5, the v6 → v7 changes apply on top of these:
+
+```diff
+- import { TypescriptConverter, JSONSchemaConverter } from "ajsc";
++ import { TypescriptConverter } from "ajsc";              // root entry restored
++ import { JSONSchemaConverter } from "ajsc/ir";           // moved to subpath in v6
 ```
+
+---
+
+## Architecture
+
+For contributors and downstream extension authors, see [`docs/architecture/README.md`](./docs/architecture/README.md) — the data flow, layered class hierarchy, `LanguageProfile` pattern, per-language module structure, and the steps to add a new language target.
+
+## License
+
+MIT