@ir-kit/kit 0.0.0-stage → 1.0.0

package/docs/sdk-swift.md

@@ -0,0 +1,263 @@
+# @ir-kit/kit/sdk/swift
+
+Generate idiomatic iOS Swift client SDKs from an OpenAPI 3.x spec — `Codable` structs, `String`-raw enums, per-tag protocols with `async throws` requirements, and a default `URLSession`-backed impl class. Per-call `RequestOptions`, composable interceptors, typed `APIError`, multipart + form-urlencoded wire encoding, multi-2xx sum-type returns, and per-op security auto-wiring all included.
+
+Built on the [`@hey-api`](https://github.com/hey-api/openapi-ts) toolchain (`@hey-api/json-schema-ref-parser` for spec loading, `@hey-api/shared` IR for normalization). 2.0 / 3.0 / 3.1 inputs all produce the same output.
+
+Sibling package to [`@ir-kit/kit/sdk/kotlin`](../openapi-kotlin). Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). Companion to the [`petstore` example](../../../examples/petstore).
+
+## Install
+
+```bash
+pnpm add @ir-kit/kit @hey-api/shared @hey-api/spec-types
+```
+
+## Usage
+
+```ts
+import { generate } from "@ir-kit/kit/sdk/swift";
+
+await generate({
+  input: "https://api.example.com/openapi.json",
+  output: "./sdk-swift",
+});
+```
+
+Reads any of: a filesystem path, an http(s) URL, or a pre-parsed object. YAML and JSON are both supported. External `$ref`s are bundled inline.
+
+## Output
+
+### Schemas → `Codable` structs / enums / typealiases
+
+```swift
+public struct Pet: Codable {
+    public let id: Int64?
+    public let name: String
+    public let category: Category?
+    public let photoUrls: [String]
+    public let tags: [Tag]?
+    public let status: PetStatus?
+
+    public init(
+        id: Int64? = nil,
+        name: String,
+        category: Category? = nil,
+        photoUrls: [String],
+        tags: [Tag]? = nil,
+        status: PetStatus? = nil
+    ) { /* … */ }
+}
+
+public enum PetStatus: String, Codable {
+    case available = "available"
+    case pending = "pending"
+    case sold = "sold"
+}
+```
+
+Every public struct ships an explicit `public init` so consumers from another module (mode-2 SwiftPM library) can construct values for tests and mocks — Swift's synthesized memberwise init is internal-only.
+
+### Operations → protocols + impls
+
+For each tag the generator emits:
+
+- `protocol <Tag>API` with `async throws` requirements
+- `extension <Tag>API` with no-options convenience overloads (forward to the with-options form using `RequestOptions()` defaults)
+- `final class URLSession<Tag>API: <Tag>API` with the wire impl, holding a single `client: APIClient`
+
+```swift
+public protocol PetAPI {
+    /// GET /pet/{petId}
+    func getPetById(petId: Int64, options: RequestOptions) async throws -> Pet
+    func getPetByIdWithResponse(petId: Int64, options: RequestOptions) async throws -> (Pet, HTTPURLResponse)
+    // …
+}
+
+public extension PetAPI {
+    func getPetById(petId: Int64) async throws -> Pet {
+        try await getPetById(petId: petId, options: RequestOptions())
+    }
+    func getPetByIdWithResponse(petId: Int64) async throws -> (Pet, HTTPURLResponse) {
+        try await getPetByIdWithResponse(petId: petId, options: RequestOptions())
+    }
+}
+
+public final class URLSessionPetAPI: PetAPI {
+    let client: APIClient
+    public init(client: APIClient) { self.client = client }
+    // …
+}
+```
+
+Every operation also emits a sibling `*WithResponse` overload that returns `(T, HTTPURLResponse)` — for callers that need response headers (pagination cursors, `ETag`, rate limits). Void-returning operations get `*WithResponse() -> HTTPURLResponse` instead.
+
+### Per-call control via `RequestOptions`
+
+```swift
+public struct RequestOptions {
+    public var client: APIClient? = nil
+    public var baseURL: URL? = nil
+    public var timeout: TimeInterval? = nil
+    public var headers: [String: String] = [:]
+    public var requestInterceptors: [(URLRequest) async throws -> URLRequest] = []
+    public var responseValidator: ((Data, HTTPURLResponse) async throws -> Void)? = nil
+    public var responseTransformer: ((Data) async throws -> Data)? = nil
+    public init(/* … all defaulted … */) { /* … */ }
+}
+```
+
+```swift
+try await pets.getPetById(petId: 1)                                              // defaults
+try await pets.getPetById(petId: 1, options: .init(client: customClient))        // swap transport
+try await pets.getPetById(petId: 1, options: .init(headers: ["X-Trace": id]))    // extra headers
+try await pets.getPetById(petId: 1, options: .init(baseURL: stagingURL))         // hit staging
+try await pets.getPetById(petId: 1, options: .init(timeout: 60))                 // long-poll override
+```
+
+### Composable interceptors + auth
+
+The runtime `APIClient` carries an `interceptors.request` array that runs against every outgoing request. Interceptors compose — auth, logging, tracing all coexist:
+
+```swift
+let client = APIClient(baseURL: URL(string: "https://api.example.com/")!)
+client.interceptors.request.append { request in
+    var request = request
+    request.setValue("Bearer \(await TokenStore.access())", forHTTPHeaderField: "Authorization")
+    return request
+}
+```
+
+When the spec declares any `securitySchemes`, the generator additionally emits an `Auth` enum (with `bearer`, `apiKey`, `basic` cases — `apiKey` carries an `APIKeyLocation` of `header` / `query` / `cookie`) and the client gains a `var auth: [String: Auth]` bag keyed by scheme name. Operations with `security:` requirements walk the bag and apply the matching scheme automatically:
+
+```swift
+client.auth["bearerAuth"] = .bearer(token: token)
+client.auth["xApiKey"] = .apiKey(name: "X-API-Key", value: key, in: .header)
+```
+
+### Body media-type dispatch
+
+| Input media type | Generated parameter shape | Wire encoding |
+|---|---|---|
+| `application/json` (and `+json`) | `body: T` | `JSONEncoder.encode` |
+| `multipart/form-data` (object schema) | one param per property; binary fields → `Data` | emitted `MultipartFormBody` helper |
+| `application/x-www-form-urlencoded` (object schema) | one param per property | `URLComponents.percentEncodedQuery` |
+| `application/octet-stream`, image, etc. | `body: Data` | raw bytes |
+| `oneOf` / unresolvable JSON | `body: Data` | raw bytes (caller pre-encodes) |
+
+### Typed errors
+
+Every non-2xx response funnels into `APIError`:
+
+```swift
+public enum APIError: Error {
+    case clientError(statusCode: Int, body: Data)        // 4XX
+    case serverError(statusCode: Int, body: Data)        // 5XX
+    case unexpectedStatus(statusCode: Int, body: Data)   // 1XX/3XX/etc.
+    case decodingFailed(Error)                           // JSONDecoder threw on a 2XX body
+    case transport(Error)                                // URLSession / network layer
+}
+```
+
+### Multi-2xx → sum-type return
+
+When an operation declares more than one 2xx response code with distinct schemas, the generator emits a sum-type enum and the impl dispatches on `httpResponse.statusCode`:
+
+```swift
+public enum SubmitJobResponse {
+    case status200(JobResult)
+    case status202(Pending)
+    case status204
+}
+```
+
+## Generator options
+
+Every option is optional. Pass them to `generate({ ... })`:
+
+| Option | Purpose |
+|---|---|
+| `input` / `output` | Spec source (path / URL / object) and SDK output dir. |
+| `clean` | Wipe `output` before writing. Default `true`. Refuses to wipe cwd or filesystem root. |
+| `package` | Emit `Package.swift` for SwiftPM-library mode. `true` → defaults from output dir basename. Object → custom `name`, `platforms`, `toolsVersion`, `sources`. Omit → mode 1 (raw `API/` + `Models/` files only). |
+| `defaultTag` | Tag to use when an op has none. Default `"Default"`. |
+| `protocolName` | `(tag) => string`. Default `(tag) => `${PascalCase(tag)}API``. |
+| `clientClassName` | `(protocolName) => string`. Default `(p) => `URLSession${p}``. |
+| `protocolOnly` | Skip impl class emission. Default `false`. |
+| `openImpl` | Emit impl class as `open` instead of `final` so consumers can subclass. Default `false`. |
+| `layout` | `"split"` (default — `API/` + `Models/`) or `"flat"`. |
+| `fileLocation` | `(decl) => { dir }` — full per-decl override. Rejects `..` traversal and absolute paths. |
+
+```ts
+generate({
+    input,
+    output,
+    package: { name: "PetstoreSDK" },
+    openImpl: true,
+    layout: "flat",
+});
+```
+
+## Two consumption modes
+
+| Mode | Setup | When |
+|---|---|---|
+| **Drop into an Xcode target** | Paste `API/` + `Models/` into your app's target sources. Same module, no `import` needed. | Adding the SDK directly to one app. |
+| **Standalone SwiftPM library** | Pass `package: { name: "YourSDK" }` to `generate()`; `Package.swift` is emitted alongside the source. Consumers reach for it via `.package(path: …)` or a git URL and `import YourSDK`. | Sharing across multiple apps, publishing privately, or wanting a clean module boundary. |
+
+## Output layout
+
+```text
+sdk-swift/
+├── API/
+│   ├── PetAPI.swift                # protocol
+│   ├── PetAPI+Defaults.swift       # convenience overloads (no-options)
+│   ├── URLSessionPetAPI.swift      # impl class
+│   ├── APIClient.swift             # runtime helper (transport, dispatch, decode)
+│   ├── APIInterceptors.swift       # interceptor pipeline
+│   ├── APIError.swift              # typed errors
+│   ├── Auth.swift                  # (when spec has securitySchemes)
+│   ├── APIKeyLocation.swift        # (when spec has securitySchemes)
+│   ├── MultipartFormBody.swift     # (when any op uses multipart/form-data)
+│   ├── URLEncoding.swift           # (when any op has query params)
+│   ├── QueryStyle.swift            # (when any op has query params)
+│   └── RequestOptions.swift
+└── Models/
+    ├── Pet.swift                   # Codable structs
+    ├── PetStatus.swift            # enums
+    └── …
+```
+
+## Requirements
+
+The generated code uses Swift Concurrency, so:
+
+- **Swift** 5.5 or newer
+- **iOS** 13.0+ (with the back-deployment library) / **iOS 15+** native, **macOS** 12+, **tvOS** 15+, **watchOS** 8+
+
+Zero runtime dependencies — the SDK only imports `Foundation`.
+
+## API surface
+
+| Export | Purpose |
+|---|---|
+| `generate(opts)` | High-level entry: load → IR → decls → files on disk. |
+| `schemasToDecls(schemas)` | `IR.Model.components.schemas` → `SwDecl[]`. |
+| `operationsToDecls(paths, opts?)` | `IR.PathsObject` → `SwDecl[]` (protocols + impls grouped by tag). |
+| `buildSwiftProject(decls, opts?)` | `SwDecl[]` → `{ path, content }[]` with `import Foundation` per file. |
+| `packageSwiftFile(opts)` | Build a `Package.swift` for a SwiftPM-library wrapping the SDK. |
+| `securityKey(path, method)` | Key into `OperationsOptions.securitySchemeNames`. |
+| `printFile(file)` / `sw*` builders | Lower-level Swift AST + printer. |
+
+```text
+src/ast/                      sw* builders returning ir-kit nodes; SwDecl
+src/sw-compiler/              printFile / printDecl via ir-kit
+src/ir/
+├── type/                     Schema → SwType
+├── operation/                IR.OperationObject → signature shared by protocol + impl
+├── impl/                     URLSession body builders (url, request, headers, body, decode)
+├── runtime/                  Top-level helper decls (APIClient, APIError, RequestOptions, Auth, …)
+├── schema.ts                 schemasToDecls
+└── operations.ts             paths → protocols + impl classes (orchestrator)
+```
+
+Everything — per-method bodies and runtime helpers — is built as `@ir-kit/kit/codegen` nodes; no string templating.

package/docs/sdk-typescript.md

@@ -0,0 +1,74 @@
+# @ir-kit/kit/sdk/typescript
+
+Thin programmatic wrapper around [`@hey-api/openapi-ts`](https://www.npmjs.com/package/@hey-api/openapi-ts) that exposes the same `generate()` shape as [`@ir-kit/openapi-{go,kotlin,swift}`](https://github.com/ahmedrowaihi/ir-kit). This is what the `typescript` target in `ir.config.ts` runs, next to the native ones.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). **No new codegen** — the entire TypeScript pipeline (types, sdk, schemas, transformers, validators, query hooks, ...) is hey-api's; this package only normalises the calling convention and the result shape.
+
+## Install
+
+```bash
+pnpm add -D @ir-kit/kit @hey-api/openapi-ts
+```
+
+`@hey-api/openapi-ts` is a peer dep so you can pin its version (and the plugins it ships) without depending on what we happen to bundle.
+
+## Usage
+
+```ts
+import { generate } from "@ir-kit/kit/sdk/typescript";
+
+await generate({
+  input: "openapi.yaml",
+  output: "src/client",
+});
+```
+
+The default plugin set is `["@hey-api/client-fetch", "@hey-api/typescript", "@hey-api/sdk"]` — types + SDK functions + a `fetch`-based runtime adapter. Override `plugins` for any other shape:
+
+```ts
+// types-only
+await generate({ input, output, plugins: ["@hey-api/typescript"] });
+
+// SDK + zod validators + tanstack-query hooks
+await generate({
+  input,
+  output,
+  plugins: [
+    "@hey-api/client-fetch",
+    "@hey-api/typescript",
+    "@hey-api/sdk",
+    "@hey-api/schemas",
+    "zod",
+    "@tanstack/react-query",
+  ],
+});
+```
+
+Anything else hey-api's `UserConfig` accepts (custom client config, parser transforms, dryRun, etc.) goes into `heyApi:`:
+
+```ts
+await generate({
+  input,
+  output,
+  heyApi: { dryRun: true, parser: { transforms: { enums: "javascript" } } },
+});
+```
+
+## Result shape
+
+```ts
+interface GenerateResult {
+  output: string;                  // absolute path
+  files: { path: string }[];       // relative paths under output
+}
+```
+
+Matches the result shape of `@ir-kit/kit/sdk/go` / `-kotlin` / `-swift`, so `ir generate` and your own scripts can iterate the four packages uniformly.
+
+## Why a wrapper
+
+We don't ship our own TypeScript codegen — hey-api already does it well, and a competing TS gen would mean rebuilding their `ts-dsl` from scratch. But `ir generate` assumes a `generate({ input, output })` shape across all targets, and hey-api's `createClient(userConfig)` is shaped slightly differently and returns `Context[]` rather than `{ files, output }`. The wrapper closes that gap in ~30 lines of code.
+
+## Limitations
+
+- **Result `files`** is collected by walking the output dir post-run. So if hey-api writes outside `output` (e.g. via custom plugin paths), those files won't be reported. The default plugins all write under `output`, so this is only a concern for advanced setups.

package/docs/spec-asyncapi.md

@@ -0,0 +1,32 @@
+# `@ir-kit/kit/spec/asyncapi`
+
+Load and validate an AsyncAPI 3.x document from a file path, URL, string, or pre-parsed `AsyncAPIDocumentInterface`. Wraps `@ir-kit/kit/asyncapi`'s `parseSpec` for unified input dispatch.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). For multi-format input (OpenAPI + AsyncAPI + TypeSpec under one API), reach for [`@ir-kit/kit/spec`](../../shared/spec-loader) instead.
+
+## Install
+
+```sh
+npm install @ir-kit/kit
+```
+
+## Usage
+
+```ts
+import { loadAsyncAPI } from "@ir-kit/kit/spec/asyncapi";
+
+const doc = await loadAsyncAPI({
+  input: "./events.yaml", // path, URL, or pre-parsed AsyncAPIDocumentInterface
+});
+
+doc.channels().all();
+```
+
+If the input is already an `AsyncAPIDocumentInterface`, it passes through unchanged. String inputs are resolved relative to `opts.cwd` (defaulting to `process.cwd()`).
+
+## API
+
+| Export                                 | Description                                                       |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `loadAsyncAPI(opts)`                   | Resolve + parse + validate, return an `AsyncAPIDocumentInterface` |
+| `AsyncAPIInput`, `LoadAsyncAPIOptions` | Public types                                                      |

package/docs/spec-convert.md

@@ -0,0 +1,85 @@
+# `@ir-kit/kit/spec`
+
+Convert between API specification formats — OpenAPI 3, AsyncAPI 3, TypeSpec, Protobuf, Postman, JSON Schema. Graph-routed dispatcher: registered `(from → to)` converters compose automatically, so any new edge unlocks every other format combinatorially.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/kit
+```
+
+## Usage
+
+```ts
+import { convertSpec } from "@ir-kit/kit/spec";
+
+const result = await convertSpec({
+  input: "./petstore.yaml",
+  to: "postman",
+});
+
+if (result.output.kind === "document") {
+  console.log(result.output.document);
+}
+```
+
+`convertSpec` auto-detects the source format from the file extension and content (override with `from`). When no direct `(from → to)` converter is registered, the dispatcher BFS-routes through intermediate formats — e.g. `proto → openapi3 → postman` works out of the box.
+
+## Registered converters
+
+| From     | →   | To                                    |
+| -------- | --- | ------------------------------------- |
+| openapi3 | →   | json-schema, postman, proto, typespec |
+| postman  | →   | openapi3                              |
+| proto    | →   | openapi3                              |
+| typespec | →   | openapi3, json-schema, proto          |
+
+Any combination not in this table is resolved automatically by chaining edges through the graph — e.g. `postman → typespec` runs `postman → openapi3 → typespec`.
+
+## OpenAPI → proto
+
+`openapi3 → proto` writes one proto3 file. Pass `upstream: { package: "acme.v1" }` to set the package; it defaults to the snake_cased `info.title`.
+
+| OpenAPI                                         | Protobuf                                                                      |
+| ----------------------------------------------- | ----------------------------------------------------------------------------- |
+| component object schema                         | `message`; non-required scalar and enum fields are `optional`                 |
+| `allOf` of objects                              | one `message` with the merged properties                                      |
+| `oneOf` / `anyOf`                               | `message` with a `oneof variant`                                              |
+| string `enum`                                   | `enum` with a `<NAME>_UNSPECIFIED = 0` value first                            |
+| integer `enum`                                  | `int32` / `int64`                                                             |
+| `array` / `additionalProperties`                | `repeated` / `map<string, T>`; nested ones are boxed in a single-field message |
+| `string` + `date-time`, `binary`/`byte`         | `google.protobuf.Timestamp`, `bytes`                                          |
+| untyped schema, mixed enum                      | `google.protobuf.Value`                                                       |
+| `$ref` to an array, map or scalar component     | the referenced type, inlined (proto has no aliases)                           |
+| operation                                       | `rpc` in a `<FirstTag>Service`, commented with its summary and `METHOD /path` |
+| parameters + request body                       | `<Rpc>Request` with one field per parameter plus `body`                       |
+| 2xx response                                    | the referenced message, or `<Rpc>Response`; several 2xx become a `oneof`     |
+| no parameters / no response body                | `google.protobuf.Empty`                                                       |
+
+Property names become snake_case fields with `json_name` set to the original key. HTTP bindings (`google.api.http`), security schemes and error responses are not emitted. The proto JSON mapping of enums and `oneof`s differs from the OpenAPI JSON for the same data. The output uses proto3 `optional`, which needs protoc 3.15+.
+
+## API
+
+| Export                                             | Description                                                   |
+| -------------------------------------------------- | ------------------------------------------------------------- |
+| `convertSpec(opts)`                                | Detect format, dispatch (or chain), return the converted spec |
+| `listConverters()`                                 | Inspect every registered direct edge                          |
+| `SpecFormat`, `ConvertOutput`, `ConvertSpecResult` | Public types                                                  |
+
+`ConvertOutput` is a discriminated union over `{ kind: "document" \| "source" \| "files" }` — a parsed JS object for OpenAPI-family targets, a source string for TypeSpec / Protobuf, or a `{ path → content }` map for emitters that produce multi-file output.
+
+## CLI
+
+```sh
+ir spec convert ./input.yaml --to openapi3
+ir spec convert ./api.proto --to postman
+```
+
+See [`@ir-kit/kit/cli`](../../cli) for full flags.
+
+## Limitations
+
+- `typespec → proto` only accepts TypeSpec written for `@typespec/protobuf`, so no route passes through it; `openapi3 → proto` uses its own converter.
+- AsyncAPI 3 outputs are not yet registered — `asyncapi3` works as a load target via `@ir-kit/kit/spec`, but not yet as a convert target.

package/docs/spec-diff.md

@@ -0,0 +1,46 @@
+# `@ir-kit/kit/spec`
+
+Cross-family API spec diff. Normalizes both inputs to OpenAPI 3 via `@ir-kit/kit/spec`, then delegates classification to [`api-smart-diff`](https://github.com/udamir/api-smart-diff) — community-standard breaking / non-breaking / annotation / unclassified / deprecated buckets.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/kit
+```
+
+## Usage
+
+```ts
+import { diffSpecs } from "@ir-kit/kit/spec";
+
+const result = await diffSpecs({
+  before: "./prod.yaml",
+  after: "./staging.proto", // mix any two supported formats
+});
+
+console.log(result.summary);
+// { total: 12, breaking: 3, nonBreaking: 4, annotation: 5, unclassified: 0, deprecated: 0 }
+
+for (const diff of result.diffs.filter((d) => d.type === "breaking")) {
+  console.log(diff.action, diff.path.join("/"), diff.description);
+}
+```
+
+## API
+
+| Export                                                           | Description                                                                            |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `diffSpecs(opts)`                                                | Run a cross-family diff, return diffs + summary + the two normalized OpenAPI documents |
+| `DiffSummary`, `DiffSpecsOptions`, `DiffSpecsResult`, `DiffType` | Public types                                                                           |
+| `Diff` (re-export from `api-smart-diff`)                         | Single change record — `{ action, path, type, description?, before?, after? }`         |
+
+## CLI
+
+```sh
+ir spec diff ./before.yaml --after ./after.proto
+ir spec diff ./prod.yaml --after ./staging.yaml --failOnBreaking --out report.json
+```
+
+`--failOnBreaking` exits non-zero when any `breaking` diff is found — drop into CI to gate merges on contract stability.

package/docs/spec-docs.md

@@ -0,0 +1,43 @@
+# `@ir-kit/kit/spec`
+
+Render any supported API spec as a standalone HTML documentation page via [Scalar API Reference](https://github.com/scalar/scalar). Converts the input to OpenAPI 3 first (using `@ir-kit/kit/spec`), then delegates HTML emission to `@scalar/core`'s `getHtmlDocument` — the same renderer the official Express / Hono / Fastify integrations use.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/kit
+```
+
+## Usage
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { renderDocs } from "@ir-kit/kit/spec";
+
+const { html } = await renderDocs({
+  input: "./api.yaml", // postman / proto / typespec / openapi3 / asyncapi3
+  theme: "moon", // optional Scalar theme
+});
+
+await writeFile("docs.html", html);
+```
+
+The output is a self-contained HTML page that loads Scalar from CDN — no bundler required, ready to drop on any static host.
+
+## API
+
+| Export                                               | Description                                                           |
+| ---------------------------------------------------- | --------------------------------------------------------------------- |
+| `renderDocs(opts)`                                   | Convert spec to OpenAPI 3 if needed, return `{ html, openapi, from }` |
+| `RenderDocsOptions`, `RenderDocsResult`, `DocsTheme` | Public types                                                          |
+
+Any input format supported by [`@ir-kit/kit/spec`](../spec-convert) works (currently: openapi3, postman, proto, typespec, asyncapi3, json-schema).
+
+## CLI
+
+```sh
+ir docs ./api.yaml --out docs.html
+ir docs ./collection.postman_collection.json --theme moon --out docs.html
+```

package/docs/spec-load.md

@@ -0,0 +1,38 @@
+# `@ir-kit/kit/spec`
+
+Universal spec loader for OpenAPI, AsyncAPI, and TypeSpec. Detects format by extension + content sniff and dispatches to the matching per-format loader, returning a discriminated `{ kind, document }` result.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit).
+
+## Install
+
+```sh
+npm install @ir-kit/kit
+```
+
+## Usage
+
+```ts
+import { loadSpec } from "@ir-kit/kit/spec";
+
+const result = await loadSpec({ input: "./api.yaml" });
+//   result.kind:     "openapi" | "asyncapi"
+//   result.document: parsed OpenAPI object or AsyncAPIDocumentInterface
+```
+
+TypeSpec input (`.tsp`) compiles to OpenAPI 3 in-memory and returns as `{ kind: "openapi" }`. Pre-parsed objects pass through and are classified by their top-level `asyncapi` / `openapi` / `swagger` key.
+
+## API
+
+| Export                                                       | Description                                     |
+| ------------------------------------------------------------ | ----------------------------------------------- |
+| `loadSpec(opts)`                                             | Detect + dispatch + return `{ kind, document }` |
+| `loadOpenAPI`, `loadAsyncAPI`, `compileTypespec`             | Re-exports from each per-format loader          |
+| `resolveOpenAPIInput`, `isTypespecPath`                      | Utility helpers                                 |
+| `SpecKind`, `SpecInput`, `LoadSpecOptions`, `LoadSpecResult` | Public types                                    |
+
+Per-format loaders ship as separate packages — `@ir-kit/kit/spec/openapi`, `@ir-kit/kit/spec/asyncapi`, `@ir-kit/kit/spec/typespec` — if you want a smaller dependency footprint and only need one format.
+
+## Why a wrapper
+
+Every consumer in ir-kit (codegen, docs, diff, recon) needs the same input-handling logic: paths vs URLs vs pre-parsed objects, format detection, `$ref` bundling. Centralizing it here removes that boilerplate from every downstream package.

package/docs/spec-openapi.md

@@ -0,0 +1,32 @@
+# `@ir-kit/kit/spec/openapi`
+
+Load an OpenAPI 3.x spec from a file path, URL, or pre-parsed object. Bundles `$ref`s via `@hey-api/json-schema-ref-parser` and runs optional hey-api-aware normalization.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). For multi-format input (OpenAPI + AsyncAPI + TypeSpec under one API), reach for [`@ir-kit/kit/spec`](../../shared/spec-loader) instead.
+
+## Install
+
+```sh
+npm install @ir-kit/kit
+```
+
+## Usage
+
+```ts
+import { loadOpenAPI } from "@ir-kit/kit/spec/openapi";
+
+const spec = await loadOpenAPI({
+  input: "./petstore.yaml", // path, URL, or pre-parsed object
+  normalize: true, // optional hey-api normalization
+});
+```
+
+## API
+
+| Export                               | Description                                                  |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `loadOpenAPI(opts)`                  | Bundle `$ref`s, optionally normalize, return the spec        |
+| `resolveOpenAPIInput(input, cwd?)`   | Resolve a string input to an absolute path / URL passthrough |
+| `OpenAPIInput`, `LoadOpenAPIOptions` | Public types                                                 |
+
+`normalize: true` applies the safe preset (`SAFE_NORMALIZE` from `@ir-kit/kit/openapi`). Pass a `NormalizeOptions` object to customize.