@ir-kit/kit 0.0.1 → 1.0.0

package/docs/compilers-go.md

@@ -0,0 +1,16 @@
+# ir-kit
+
+Typed Go AST and printer. Build Go source through a TypeScript-compiler-style `factory`, then print it. Zero runtime dependencies.
+
+The printer's snapshot suite is gated by the canonical Go formatter (`scripts/lint-go.sh`), so printed output is formatter-clean by construction.
+
+Originally developed in [typescript-compilers](https://github.com/ahmedrowaihi/typescript-compilers) (Hey API); imported with full history.
+
+## Usage
+
+```ts
+import { go } from "@ir-kit/kit";
+
+const file = go.factory.createSourceFile(/* ... */);
+const source = go.createPrinter().printFile(file);
+```

package/docs/compilers-java.md

@@ -0,0 +1,16 @@
+# ir-kit
+
+Typed Java AST and printer. Build Java source through a TypeScript-compiler-style `factory`, then print it. Zero runtime dependencies.
+
+The printer's snapshot suite is gated by the canonical Java formatter (`scripts/lint-java.sh`), so printed output is formatter-clean by construction.
+
+Originally developed in [typescript-compilers](https://github.com/ahmedrowaihi/typescript-compilers) (Hey API); imported with full history.
+
+## Usage
+
+```ts
+import { java } from "@ir-kit/kit";
+
+const file = java.factory.createSourceFile(/* ... */);
+const source = java.createPrinter().printFile(file);
+```

package/docs/compilers-kotlin.md

@@ -0,0 +1,16 @@
+# ir-kit
+
+Typed Kotlin AST and printer. Build Kotlin source through a TypeScript-compiler-style `factory`, then print it. Zero runtime dependencies.
+
+The printer's snapshot suite is gated by the canonical Kotlin formatter (`scripts/lint-kotlin.sh`), so printed output is formatter-clean by construction.
+
+Originally developed in [typescript-compilers](https://github.com/ahmedrowaihi/typescript-compilers) (Hey API); imported with full history.
+
+## Usage
+
+```ts
+import { kotlin } from "@ir-kit/kit";
+
+const file = kotlin.factory.createSourceFile(/* ... */);
+const source = kotlin.createPrinter().printFile(file);
+```

package/docs/compilers-swift.md

@@ -0,0 +1,16 @@
+# ir-kit
+
+Typed Swift AST and printer. Build Swift source through a TypeScript-compiler-style `factory`, then print it. Zero runtime dependencies.
+
+The printer's snapshot suite is gated by the canonical Swift formatter (`scripts/lint-swift.sh`), so printed output is formatter-clean by construction.
+
+Originally developed in [typescript-compilers](https://github.com/ahmedrowaihi/typescript-compilers) (Hey API); imported with full history.
+
+## Usage
+
+```ts
+import { swift } from "@ir-kit/kit";
+
+const file = swift.factory.createSourceFile(/* ... */);
+const source = swift.createPrinter().printFile(file);
+```

package/docs/fn-schema-core.md

@@ -0,0 +1,114 @@
+# @ir-kit/kit/fn-schema
+
+Language-agnostic IR + emitters for fn-schema. Defines the `Extractor` contract that language-specific packages implement, and ships the orchestration + output paths every extractor shares.
+
+## When to use this directly
+
+Most users don't import `core` — they use the [`cli`](../cli/README.md) or `@ir-kit/kit/fn-schema/typescript` (which re-exports a pre-wired `extract`). Reach for `core` when you want to:
+
+- register multiple extractors in the same run (e.g. TS + Python, when Python lands)
+- keep a long-lived `Project` warm across many `extract()` calls
+- build your own emitter on top of the orchestrator
+
+## Quick start
+
+```ts
+import { createProject } from "@ir-kit/kit/fn-schema"
+import { typescript } from "@ir-kit/kit/fn-schema/typescript"
+
+const project = createProject({
+  cwd: process.cwd(),
+  tsConfigPath: "./tsconfig.json",
+  extractors: [typescript()],
+})
+
+const result = await project.extract({
+  files: ["src/api/handlers.ts"],
+  schema: { identity: "x-fn-schema-ts", transport: "x-fn-schema-transport" },
+})
+
+project.dispose()
+```
+
+### Discovery without schemas
+
+`Project.discover()` walks the same files but stops at function detection — no schema generation. Use it when you only need names, locations, JSDoc tags, and the like.
+
+```ts
+const { signatures, stats } = await project.discover({
+  files: ["src/**/*.ts"],
+  include: { jsDocTag: "schema" },
+})
+for (const fn of signatures) console.log(fn.name, fn.file, fn.location)
+```
+
+## Emitters
+
+```ts
+import { emit } from "@ir-kit/kit/fn-schema"
+
+emit.toFiles(result, { dir: "generated", format: "json-pretty" })
+emit.toBundle(result, { pretty: true })
+emit.toBundleTypesModule(result, { jsonImport: "./schemas.json" })
+emit.toOpenAPI(result, { title: "my-api" })
+```
+
+- `toFiles` — one JSON per signature
+- `toBundle` — single JSON with all signatures + shared definitions
+- `toBundleTypesModule` — TS wrapper exporting the bundle under literal-typed signature ids and definition names (pair with [`loader`](../loader/README.md))
+- `toOpenAPI` — components-only OpenAPI 3.1 doc; tuples use `prefixItems`
+
+## Schema knobs
+
+```ts
+schema: {
+  dialect: "draft-07" | "draft-2020-12" | "openapi-3.1",
+  expose: "all" | "export" | "none",
+  topRef: false,
+  additionalProperties: false,
+
+  // user overrides built-in mappings (Date, File, Buffer, …)
+  typeMappers: { MyType: { type: "string", format: "uuid" } },
+
+  // off-by-default vendor extensions
+  identity: "x-fn-schema-ts",            // attach originating TS type name
+  transport: "x-fn-schema-transport",    // attach multipart/base64 hint
+  sourceLocations: "x-fn-schema-source", // attach file:line:col
+}
+```
+
+## Diagnostics
+
+Every mapping decision is observable:
+
+| Code | Severity | When |
+|---|---|---|
+| `TYPE_MAPPED` | info | Well-known TS type rewritten to canonical JSON Schema |
+| `LOSSY_MAPPING` | warning | Mapping lost information (e.g. `bigint` → `integer`) |
+| `NOT_REPRESENTABLE` | error | Type can't be represented in JSON Schema (e.g. `symbol`) |
+| `GENERIC_SKIPPED` | warning | Generic function skipped (set `signature.generics: "erase"` to override) |
+| `DUPLICATE_ID` | warning | Definition emitted with conflicting shapes from two functions |
+| `EXTRACTOR_FAILURE` | error | Extractor threw on a function |
+| `EMPTY_RESULT` | info | No signatures matched the filter |
+| `NO_EXTRACTOR` | warning | A file's extension isn't claimed by any registered extractor |
+
+Subscribe via `extract({ onDiagnostic: (d) => ... })` or read `result.diagnostics` after.
+
+## Extractor contract
+
+Other languages plug in by implementing:
+
+```ts
+interface Extractor {
+  readonly extensions: readonly string[]
+  readonly language: string
+  init(opts: ExtractorInitOptions): Promise<ExtractorInstance>
+}
+
+interface ExtractorInstance {
+  discover(files: readonly string[], filter: ResolvedFilter): Promise<FunctionInfo[]>
+  toSchemas(fn: FunctionInfo, opts: ResolvedSignatureOptions & ResolvedSchemaOptions): Promise<SignaturePair>
+  refresh(files: readonly string[]): void
+  dispose(): void
+}
+```

package/docs/fn-schema-loader.md

@@ -0,0 +1,112 @@
+# @ir-kit/kit/fn-schema/loader
+
+Type-safe reader over a fn-schema bundle. Generic over the bundle type so signature ids and definition names land as literal-typed unions.
+
+Zero runtime dependencies — works in any JS runtime that can read JSON.
+
+## When to use it
+
+You have a fn-schema bundle (produced by the CLI or programmatically — doesn't matter which) and want ergonomic access from your app:
+
+- server endpoints looking up schemas by id
+- frontend form builders resolving `$ref` pointers
+- canvas tools matching types nominally via `findByIdentity`
+
+If you're loading the JSON in one place and reading it once, the helper is overkill — just `JSON.parse` it.
+
+## Install
+
+```bash
+pnpm add @ir-kit/kit
+```
+
+## Producing a bundle
+
+Pick whichever fits your build chain — both produce the same JSON:
+
+### Programmatically
+
+```ts
+import { extract } from "@ir-kit/kit/fn-schema/typescript";
+import { emit } from "@ir-kit/kit/fn-schema";
+import { writeFile } from "node:fs/promises";
+
+const result = await extract({
+  files: ["src/api/**/*.ts"],
+  schema: { identity: "x-fn-schema-ts" },
+});
+await writeFile(
+  "generated/schemas.json",
+  emit.toBundle(result, { pretty: true }),
+);
+await writeFile(
+  "generated/schemas.ts",
+  emit.toBundleTypesModule(result, { jsonImport: "./schemas.json" }),
+);
+```
+
+### Via CLI
+
+```bash
+npx fn-schema extract 'src/api/**/*.ts' --bundle generated/schemas.json --bundle-types --pretty
+```
+
+The `.ts` wrapper next to `schemas.json` is what unlocks literal-typed lookups in the reader.
+
+## Reading
+
+```ts
+import { createReader } from "@ir-kit/kit/fn-schema/loader";
+import schemas from "./generated/schemas"; // the typed wrapper
+
+const reader = createReader(schemas);
+
+reader.get("createUser"); // ✅ typed
+reader.get("createUserx"); // ❌ TS error
+reader.has("listUsers"); // type predicate
+
+reader.inputOf("createUser"); // resolved (top-level $ref chased)
+reader.outputOf("createUser");
+reader.resolveRef("#/definitions/User");
+
+// canvas-style nominal-type matching (only when bundle was extracted with `identity`)
+reader.findByIdentity("User", "x-fn-schema-ts");
+// → [{ signatureId: "createUser", position: "output", schema: {...} }, ...]
+```
+
+## API
+
+```ts
+interface Reader<T extends Bundle> {
+  readonly bundle: T;
+  get<K extends SignatureId<T>>(id: K): T["signatures"][K] | undefined;
+  has<K extends string>(id: K): id is K & SignatureId<T>;
+  resolve<K extends DefinitionName<T>>(
+    name: K,
+  ): T["definitions"][K] | undefined;
+  resolveRef(ref: string): Record<string, unknown> | undefined;
+  inputOf<K extends SignatureId<T>>(id: K): unknown;
+  outputOf<K extends SignatureId<T>>(id: K): unknown;
+  findByIdentity(name: string, identityKey?: string): Match[];
+  listSignatures(): SignatureId<T>[];
+  listDefinitions(): DefinitionName<T>[];
+}
+```
+
+`identityKey` defaults to `"x-fn-schema-ts"`.
+
+## Without the typed wrapper
+
+Works on any plain object too — you just lose autocomplete:
+
+```ts
+import { readFileSync } from "node:fs";
+import { createReader, type Bundle } from "@ir-kit/kit/fn-schema/loader";
+
+const raw = JSON.parse(readFileSync("./schemas.json", "utf-8")) as Bundle;
+const reader = createReader(raw);
+```
+
+## $ref resolution
+
+`inputOf` / `outputOf` chase a single top-level `$ref`. Nested `$ref`s inside the schema body are left intact — call `resolveRef` yourself if you need to chase further. Keeps the helper predictable; no cycle handling.

package/docs/fn-schema-transformer.md

@@ -0,0 +1,123 @@
+# @ir-kit/kit/fn-schema/transformer
+
+TypeScript compiler-API transformer that **inlines fn-schema results into emitted JS at compile time**. Replaces every `schemaOf(fn)` call with a literal JSON Schema object pulled from a pre-extracted bundle.
+
+## When to use this — and when not to
+
+Use it when you want zero runtime cost: no `JSON.parse` on cold start, no `schemas.json` artifact at runtime, no ts-morph dep in your shipped bundle.
+
+For 95% of users the [`loader`](../loader/README.md) is the right answer — simpler to set up and works in every TS toolchain. Only reach for the transformer when you've measured a real cost (cold-start latency, bundle size) or your deployment target forbids JSON files.
+
+|                          | loader                    | transformer                        |
+| ------------------------ | ------------------------- | ---------------------------------- |
+| setup                    | `import`                  | `ts-patch` + tsconfig plugin entry |
+| runtime cost             | one `JSON.parse`          | none                               |
+| live updates             | yes (re-extract + import) | no (rebuild required)              |
+| works with vanilla `tsc` | yes                       | no (needs `tspc`)                  |
+
+## Install
+
+```bash
+pnpm add -D @ir-kit/kit ts-patch
+```
+
+## Setup
+
+### 1. Produce a bundle
+
+Either path works — the transformer just needs a `schemas.json` on disk before tsc runs.
+
+**Programmatic** (in a build script):
+
+```ts
+import { extract } from "@ir-kit/kit/fn-schema/typescript";
+import { emit } from "@ir-kit/kit/fn-schema";
+import { writeFile, mkdir } from "node:fs/promises";
+
+const result = await extract({ files: ["src/api/**/*.ts"] });
+await mkdir("generated", { recursive: true });
+await writeFile("generated/schemas.json", emit.toBundle(result));
+```
+
+**CLI**:
+
+```bash
+npx fn-schema extract 'src/api/**/*.ts' --bundle generated/schemas.json --pretty
+```
+
+### 2. Configure ts-patch
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "@ir-kit/kit/fn-schema/transformer",
+        "bundlePath": "./generated/schemas.json",
+      },
+    ],
+  },
+}
+```
+
+```jsonc
+// package.json — bundle must exist before tspc runs
+{
+  "scripts": {
+    "build:schemas": "node scripts/extract.mjs",
+    "build:ts": "tspc",
+    "build": "pnpm build:schemas && pnpm build:ts",
+  },
+}
+```
+
+`tspc` is `ts-patch`'s patched compiler (replaces `tsc`).
+
+### 3. Use the runtime markers
+
+```ts
+import {
+  schemaOf,
+  inputSchemaOf,
+  outputSchemaOf,
+} from "@ir-kit/kit/fn-schema/transformer/runtime";
+import { createUser } from "./api/handlers";
+
+const meta = schemaOf(createUser);
+const inputSchema = inputSchemaOf(createUser);
+const outputSchema = outputSchemaOf(createUser);
+```
+
+After transformation, the emitted JS has:
+
+```js
+const meta = { input: { type: "object", properties: { ... } }, output: { ... } }
+const inputSchema = { type: "object", properties: { ... } }
+const outputSchema = { ... }
+```
+
+The runtime stubs return `undefined` if the transformer is NOT applied, so dev tooling that doesn't run the transformer (`tsx`, `vitest`, etc.) doesn't break — calls just return `undefined`.
+
+## What gets replaced
+
+Direct calls only:
+
+```ts
+schemaOf(myFunction); // ✅ inlined
+inputSchemaOf(myFunction); // ✅
+outputSchemaOf(myFunction); // ✅
+
+const fn = myFunction;
+schemaOf(fn); // ❌ not inlined (argument is a binding, not the original identifier)
+
+schemaOf(makeFn()); // ❌ not inlined (call expression)
+```
+
+Lookup is by the argument identifier's name. If `myFunction` isn't in the bundle, the call is left alone — no error, but you get `undefined` at runtime via the stub.
+
+## Limitations
+
+- TS transformers are **synchronous**. The bundle must exist on disk before tsc runs — wire your build chain so extraction completes first.
+- Doesn't work with vanilla `tsc` — needs [`ts-patch`](https://github.com/nonara/ts-patch)'s `tspc` (or another tool supporting custom transformers).
+- Source-map fidelity is best-effort.

package/docs/fn-schema-typescript.md

@@ -0,0 +1,85 @@
+# @ir-kit/kit/fn-schema/typescript
+
+TypeScript extractor for fn-schema. The default TS implementation of the `Extractor` contract from `core`.
+
+Most users don't import this directly — they use the [`cli`](../cli/README.md). Reach for the programmatic API when you're building tooling on top of fn-schema.
+
+## Install
+
+```bash
+pnpm add @ir-kit/kit
+```
+
+## Quick start
+
+```ts
+import { extract } from "@ir-kit/kit/fn-schema/typescript"
+
+const result = await extract({
+  files: ["src/api/handlers.ts"],
+  tsConfigPath: "./tsconfig.json",
+})
+
+for (const sig of result.signatures) {
+  console.log(sig.id, sig.input, sig.output)
+}
+```
+
+`extract` is a one-shot helper. For repeat calls (server endpoints, dev mode, watch), use [`createProject`](../core/README.md) from `core` directly with `typescript()` as the extractor — it keeps the ts-morph project warm.
+
+## What it discovers
+
+- `function foo() {}` declarations
+- `const foo = () => {}` and `const foo = function() {}`
+- Class methods (instance + static, exported classes)
+- Object-literal members: `export const api = { create() {}, tag: () => {} }`
+- Default-export arrows: `export default (input) => {}`
+- Function and method overloads (configurable via `signature.overloads`)
+- `this` parameter is auto-skipped
+
+## What it extracts
+
+- Multi-parameter functions — `signature.parameters` controls layout (`array` / `first-only` / `object`)
+- Async returns — `Promise<T>` auto-unwrapped (toggle via `signature.unwrapPromise`)
+- Generic functions — skipped by default (set `signature.generics: "erase"` to coerce to `unknown`)
+- Branded types (`type X = string & { __brand: "X" }`) — phantom stripped, identity preserved when the keyword is on
+- Well-known types canonicalized: `Date`, `URL`, `RegExp`, `File`, `Blob`, `Buffer`, `Uint8Array`, `ArrayBuffer`, `bigint`
+- `symbol` and function-as-input → `NOT_REPRESENTABLE` diagnostic
+
+## Filters
+
+```ts
+extract({
+  files: ["src/api/**/*.ts"],
+  include: {
+    exported: true,
+    name: /^create/,
+    jsDocTag: "schema",
+    kind: ["function", "method"],
+  },
+  exclude: { name: /^_/, jsDocTag: "internal" },
+  filter: (fn) => fn.async,
+})
+```
+
+## How the type resolution works
+
+For each function we synthesize a virtual TS file alongside it:
+
+```ts
+// src/__fn_schema_virtual__/handlers_createUser.virtual.ts
+import type { CreateUserInput, User } from "../handlers"
+
+type __FnSchemaMap_Date = { readonly __fn_schema_marker: "Date" }
+
+export type __In_0 = CreateUserInput
+export type __Out__ = Awaited<Promise<User>>
+```
+
+ts-json-schema-generator processes this like any other source file. Sentinel object types (`__FnSchemaMap_Date`, etc.) survive union flattening because they're structurally distinct from primitives. After generation, a post-process pass swaps each sentinel for its canonical schema and (optionally) attaches identity/transport/source-location keywords.
+
+This indirection is what lets fn-schema reuse ts-json-schema-generator without forking it — we work around its inability to resolve `Parameters<typeof X>` and `import("path").Y` by emitting bare type identifiers and resolving cross-file imports ourselves.
+
+## Diagnostics
+
+Subscribe via `extract({ onDiagnostic: (d) => ... })` or read `result.diagnostics`. Codes are documented in [`core/README.md`](../core/README.md#diagnostics).

package/docs/fn-schema-unplugin.md

@@ -0,0 +1,76 @@
+# @ir-kit/kit/fn-schema/unplugin
+
+Bundler plugin for fn-schema. Resolves a virtual module to the extracted bundle, with HMR on source change in Vite. Built on [unplugin](https://github.com/unjs/unplugin) — same package powers Vite, webpack, Rollup, esbuild, Rspack, Rolldown, and Farm.
+
+## When to use it
+
+You have a Vite/Next/webpack app and want fn-schema results available via a regular import — without running the [`cli`](../cli/README.md) as a separate process. The plugin keeps a warm `Project` instance during dev and triggers a reload when source files change.
+
+## Install
+
+```bash
+pnpm add -D @ir-kit/kit
+```
+
+## Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite"
+import fnSchema from "@ir-kit/kit/fn-schema/unplugin/vite"
+
+export default defineConfig({
+  plugins: [
+    fnSchema({
+      files: "src/api/**/*.ts",
+      schema: { identity: "x-fn-schema-ts", transport: "x-fn-schema-transport" },
+    }),
+  ],
+})
+```
+
+```ts
+// app code
+import schemas from "virtual:fn-schema/bundle"
+import { createReader } from "@ir-kit/kit/fn-schema/loader"
+
+const reader = createReader(schemas)
+```
+
+## Other bundlers
+
+```ts
+// webpack
+const fnSchema = require("@ir-kit/kit/fn-schema/unplugin/webpack").default
+
+// rollup
+import fnSchema from "@ir-kit/kit/fn-schema/unplugin/rollup"
+
+// esbuild
+import fnSchema from "@ir-kit/kit/fn-schema/unplugin/esbuild"
+```
+
+Subpath exports also exist for `/rspack`, `/rolldown`, `/farm`.
+
+## Options
+
+```ts
+interface FnSchemaPluginOptions {
+  files: string | string[]            // required
+  cwd?: string                         // default: process.cwd()
+  tsConfigPath?: string
+  virtualModuleId?: string             // default: "virtual:fn-schema/bundle"
+  // …all extract options (include, exclude, signature, schema, naming, hooks)
+}
+```
+
+## CLI vs unplugin
+
+| | CLI | unplugin |
+|---|---|---|
+| extra dev process | yes | no |
+| HMR on schema change | manual (your watcher) | built-in (Vite) |
+| works outside a bundler | yes | no |
+| produces disk artifact (`schemas.json`) | yes | no (in-memory) |
+
+Use the CLI when you want a checked-in `schemas.json` — for backend Node servers, deployment validation, or sharing across services. Use unplugin when fn-schema is a per-app dev concern.

package/docs/generate.md

@@ -0,0 +1,61 @@
+# `ir generate`
+
+List the spec and everything you want from it in one `ir.config.ts`, then run one command.
+
+```ts
+// ir.config.ts
+import { defineConfig } from "@ir-kit/kit";
+
+export default defineConfig({
+  input: "api/openapi.yaml",
+  targets: {
+    go: { output: "sdk/go", gomod: "github.com/me/api-go" },
+    kotlin: { output: "sdk/kotlin", gradle: true },
+    typescript: { output: "sdk/ts" },
+    k6: { output: "loadtest/client" },
+    docs: { output: "docs/index.html" },
+  },
+});
+```
+
+```sh
+npx @ir-kit/kit init       # write a starter ir.config.ts
+npx ir generate       # write every target
+npx ir generate --check   # write nothing; fail if any target is out of date
+npx ir watch          # regenerate when the spec or config changes
+```
+
+`ir init` writes `ir.config.mts` instead when `package.json` isn't `"type": "module"`, so Node loads it as an ES module either way. `ir.config.{ts,mts,js,mjs}` are all found. `--targets go,docs` runs only some targets. `--config path/to/ir.config.ts` picks another file. Relative paths in the config start at the config file's directory.
+
+## Targets
+
+| Target | Options besides `output` and `input` |
+| --- | --- |
+| `go` | `packageName`, `gomod`, `clean`, `normalize`, `defaultTag` |
+| `kotlin`, `java` | `packageName`, `gradle`, `clean`, `normalize`, `defaultTag` |
+| `swift` | `swiftPackage`, `clean`, `normalize`, `defaultTag` |
+| `typescript` | `plugins` (Hey API plugins), `heyApi` (any other Hey API option), `normalize` |
+| `k6` | `scaffold`, `defaultBaseUrl`, `normalize` |
+| `docs` | `theme`, `from`; `output` is an HTML file |
+| `asyncapi` | `plugins` (`typescript`, `events`, `event-map`, `dispatch`, `amqplib`, `index`; default all) |
+
+Each target can set its own `input`, for example an AsyncAPI file for `asyncapi` next to an OpenAPI file for the rest. Given an AsyncAPI file, the `go`, `kotlin`, `swift`, `java` and `typescript` targets write one model type per message payload and named component schema. A top-level `normalize: true` applies to every target that supports it. Unknown targets and options are errors.
+
+The options are the same ones `ir sdk <target>` takes as flags.
+
+## In CI
+
+`--check` generates into a temporary directory and compares it with what is committed. It lists each file that changed, is missing, or (for targets that clear their output) should no longer be there. Loadtest stubs written by `k6` with `scaffold` belong to you after the first run, so they are never compared.
+
+```yaml
+- run: npx ir generate --check
+```
+
+## From code
+
+```ts
+import { generate, loadIrConfig, watch } from "@ir-kit/kit/generate";
+
+const { config, cwd } = await loadIrConfig();
+const results = await generate(config, { cwd, check: true });
+```

package/docs/ir.md

@@ -0,0 +1,23 @@
+# @ir-kit/kit/ir
+
+ir-kit's own model of an HTTP API. The Go, Kotlin, Swift, Java and k6 generators read it, so they don't depend on any parser's internal types.
+
+```ts
+import { type IR, parseOpenAPI } from "@ir-kit/kit/ir";
+
+const model: IR.Model = parseOpenAPI(openApiDocument);
+for (const [path, item] of Object.entries(model.paths ?? {})) {
+  for (const op of Object.values(item)) {
+    console.log(op.method, path, op.securitySchemes);
+  }
+}
+```
+
+| Export | Description |
+| --- | --- |
+| `parseOpenAPI(doc)` | Read an OpenAPI 2.0, 3.0 or 3.1 document (refs already bundled) into `IR.Model`. Each operation lists the security schemes it accepts in `securitySchemes`, taken from its own `security` or the document's. |
+| `asyncapiSchemas(doc, messageSuffix?)` | An AsyncAPI document's component schemas plus one schema per message payload, as OpenAPI 3.1 schemas. |
+| `asyncapiToOpenAPI(doc)` | The same schemas wrapped in an OpenAPI 3.1 document with no paths. This is how the SDK targets write models from an AsyncAPI file. |
+| `IR` | The model types: `Model`, `Operation`, `Parameter`, `Body`, `Response`, `Schema` and so on. `IR.Schema` is JSON Schema 2020-12, the same type as `@ir-kit/kit/schema`'s `Schema`. |
+
+`parseOpenAPI` uses Hey API's OpenAPI parser to read the document, then converts its schemas to JSON Schema.