@amritk/asyncapi 0.1.0

package/AI.md

@@ -0,0 +1,35 @@
+# @amritk/asyncapi — notes for AI coding agents
+
+Extract every message payload/headers schema from an AsyncAPI 2.x/3.0 document
+as self-contained JSON Schema 2020-12, ready for the mjst generators. Full
+reference is [README.md](./README.md).
+
+> Pre-alpha: APIs change in **minor** versions.
+
+## Minimal example
+
+```ts
+import { extractAsyncApi, listMessageSchemas } from '@amritk/asyncapi'
+
+const model = extractAsyncApi(parsedDocument) // takes a VALUE, not a path
+const schemas = listMessageSchemas(model)
+// → [{ subDir: 'channels/lighting-measured/light-measured', rootTypeName: 'LightMeasured', schema }, ...]
+```
+
+## Gotchas — where agents fail
+
+1. **It takes an already-parsed document.** No filesystem, no YAML, no network —
+   parse with `@amritk/yaml` / `JSON.parse` and resolve cross-file refs with
+   `@amritk/resolve-refs` *before* calling. External `$ref`s still present are
+   reported as issues, not fetched.
+2. **Problems are collected, not thrown.** Read `model.issues`; only "this is
+   not an AsyncAPI document" throws. An Avro/Protobuf `schemaFormat` skips that
+   one schema with an issue.
+3. **Directions are application-relative.** 2.x `publish` → `receive`,
+   `subscribe` → `send` (the app is the server). Absent when no operation names
+   the message.
+4. **Extracted schemas are copies.** `#/components/schemas/X` refs are rebased
+   to `#/$defs/X` with components copied in per message — mutating one
+   message's schema never affects another.
+5. **Root type names come from message identity**, not schema `title` — two
+   messages titled "Event" stay distinct.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amritk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+<div align="center">
+
+# @amritk/asyncapi
+
+**Extract JSON Schemas from AsyncAPI 2.x/3.0 documents for the mjst generators.**
+
+![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square)&nbsp;
+![version](https://img.shields.io/npm/v/@amritk/asyncapi?style=flat-square&logo=npm&logoColor=white&label=version&color=6366f1)&nbsp;
+![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)&nbsp;
+![AsyncAPI](https://img.shields.io/badge/AsyncAPI-2.x%20%7C%203.0-f97316?style=flat-square)&nbsp;
+![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white)&nbsp;
+![vibe coded](https://img.shields.io/badge/vibe-coded-a855f7?style=flat-square)
+
+</div>
+
+---
+
+## Overview
+
+`@amritk/asyncapi` walks an AsyncAPI document — 2.0 through 2.6, or 3.0 — and pulls every message's payload and headers out as **self-contained JSON Schema 2020-12 documents**, ready for [`@amritk/generate-parsers`](../generate-parsers), [`@amritk/generate-validators`](../generate-validators), [`@amritk/generate-examples`](../generate-examples), or [`@amritk/runtime-validators`](../runtime-validators). It is the extraction layer behind `mjst --input asyncapi`.
+
+What "self-contained" buys: the AsyncAPI default schema dialect (a draft-07 superset) is upgraded to 2020-12 conventions, OpenAPI-format payloads get `nullable` folded into their `type`, and every `$ref` into the document's `#/components/schemas/...` is rebased into a local `$defs` with the referenced components copied in transitively — so each extracted schema stands alone as a generator input.
+
+Both majors normalize into one 3.0-shaped model. Directions are named from the application's point of view (2.x `publish` → `receive`, `subscribe` → `send`), matching [`@amritk/api`](../api)'s message contracts. Non-JSON-Schema payloads (`schemaFormat`: Avro, Protobuf, …) are skipped per message with a recorded issue — one Avro payload never costs the document's other messages.
+
+---
+
+## Installation
+
+```bash
+npm install @amritk/asyncapi
+# or
+pnpm add @amritk/asyncapi
+# or
+yarn add @amritk/asyncapi
+# or
+bun add @amritk/asyncapi
+```
+
+---
+
+## Usage
+
+```ts
+import { extractAsyncApi, listMessageSchemas } from '@amritk/asyncapi'
+
+// Parse the document yourself (JSON.parse, @amritk/yaml, ...) — this package
+// takes the already-parsed value and never touches the filesystem or network.
+const model = extractAsyncApi(document)
+
+for (const issue of model.issues) {
+  console.warn(`${issue.path}: ${issue.message}`)
+}
+
+for (const channel of model.channels) {
+  for (const message of channel.messages) {
+    // message.payload / message.headers are self-contained JSON Schema 2020-12
+    console.log(channel.key, message.name, message.direction)
+  }
+}
+
+// Flatten into generator inputs: one { subDir, rootTypeName, schema } per
+// payload/headers, laid out as channels/<channel>/<message>[-headers].
+const schemas = listMessageSchemas(model)
+```
+
+Cross-file and remote `$ref`s are the loader's job: resolve them first (for example with [`@amritk/resolve-refs`](../resolve-refs)); a still-unresolved external reference is reported as an issue, never fetched.
+
+---
+
+## API
+
+- **`extractAsyncApi(document)`** → `AsyncApiModel` — the normalized document: `version`, `major`, `title?`, `channels` (each with `key`, `address?`, `messages`), and collected `issues`. Throws only when the input is not an AsyncAPI document at all.
+- **`listMessageSchemas(model, issues?)`** → `ExtractedSchema[]` — one `{ subDir, rootTypeName, schema }` per generatable payload/headers, with deterministic collision-suffixed directory tokens; collision issues are appended to `model.issues` (or to the `issues` array you pass).
+- **`detectAsyncApiVersion(document)`** — the `asyncapi` version and its major, or `undefined`.
+- **`classifySchemaFormat(schemaFormat)`** — which JSON Schema dialect a `schemaFormat` names (`'asyncapi' | 'draft-07' | '2020-12' | 'openapi'`), or `'unsupported'`.
+- **`mergeTraits(target, traits, precedence)`** — trait application as an RFC 7386 JSON Merge Patch (recursive, so nested contributions from both sides survive); `precedence` is `'trait'` for 2.x (traits override the target) or `'target'` for 3.0 (the target wins). Applied before `schemaFormat` is read.
+
+---
+
+## License
+
+MIT

package/dist/detect-version.d.ts

@@ -0,0 +1,14 @@
+export type DetectedVersion = {
+    readonly major: 2 | 3;
+    /** The declared version string, verbatim. */
+    readonly version: string;
+};
+/**
+ * Reads the document's `asyncapi` version and classifies its major.
+ *
+ * The major is matched with an anchored `M.` so a hypothetical `20.0.0` is not
+ * mistaken for 2.x — the same guard the lint format detectors carry for minors.
+ * Returns `undefined` for anything that is not an AsyncAPI 2.x/3.x document, so
+ * the caller owns the error message.
+ */
+export declare const detectAsyncApiVersion: (document: unknown) => DetectedVersion | undefined;

package/dist/detect-version.js

@@ -0,0 +1,16 @@
+import { readKey } from "@amritk/helpers/read-key";
+const detectAsyncApiVersion = (document) => {
+  if (typeof document !== "object" || document === null || Array.isArray(document))
+    return void 0;
+  const version = readKey(document, "asyncapi");
+  if (typeof version !== "string")
+    return void 0;
+  if (/^2\.\d/.test(version))
+    return { major: 2, version };
+  if (/^3\.\d/.test(version))
+    return { major: 3, version };
+  return void 0;
+};
+export {
+  detectAsyncApiVersion
+};

package/dist/extract-async-api.d.ts

@@ -0,0 +1,13 @@
+import type { AsyncApiModel } from './types.js';
+/**
+ * Extracts an already-parsed AsyncAPI document (2.x or 3.x) into the
+ * normalized model: channels, their messages, and each message's payload and
+ * headers as self-contained JSON Schema 2020-12 documents.
+ *
+ * Per-message problems — an Avro payload, a dangling `$ref`, a malformed
+ * trait — are collected on `issues` so one bad message never costs the rest of
+ * the document. Only a document that is not AsyncAPI at all throws: there is
+ * nothing to extract, and a silent empty model would read as "no channels"
+ * rather than "wrong file".
+ */
+export declare const extractAsyncApi: (document: unknown) => AsyncApiModel;

package/dist/extract-async-api.js

@@ -0,0 +1,25 @@
+import { readKey } from "@amritk/helpers/read-key";
+import { detectAsyncApiVersion } from "./detect-version.js";
+import { extractChannelsV2 } from "./extract-channels-v2.js";
+import { extractChannelsV3 } from "./extract-channels-v3.js";
+const extractAsyncApi = (document) => {
+  const detected = detectAsyncApiVersion(document);
+  if (!detected) {
+    throw new Error("Not an AsyncAPI document: expected a top-level `asyncapi` field declaring version 2.x or 3.x.");
+  }
+  const record = document;
+  const issues = [];
+  const channels = detected.major === 2 ? extractChannelsV2(record, issues) : extractChannelsV3(record, issues);
+  const info = readKey(record, "info");
+  const title = typeof info === "object" && info !== null ? readKey(info, "title") : void 0;
+  return {
+    version: detected.version,
+    major: detected.major,
+    ...typeof title === "string" ? { title } : {},
+    channels,
+    issues
+  };
+};
+export {
+  extractAsyncApi
+};

package/dist/extract-channels-v2.d.ts

@@ -0,0 +1,16 @@
+import type { ExtractionIssue, NormalizedChannel } from './types.js';
+/**
+ * Walks an AsyncAPI 2.x document's channels into the normalized model.
+ *
+ * Directions are mapped to the application's point of view: `publish` declares
+ * what clients publish — so the application *receives* it — and `subscribe`
+ * declares what it *sends*. A channel's key doubles as its address; 2.x has no
+ * separate `address` field.
+ *
+ * `schemaFormat` is read off the message only *after* trait merging, so a
+ * trait-contributed format gates its payload exactly like an inline one.
+ * Message names follow `name` → `messageId` → positional `message-<n>`, the
+ * `n` counting across both operations of the channel so a `oneOf` list and a
+ * publish/subscribe pair cannot collide.
+ */
+export declare const extractChannelsV2: (document: Record<string, unknown>, issues: ExtractionIssue[]) => NormalizedChannel[];

package/dist/extract-channels-v2.js

@@ -0,0 +1,71 @@
+import { readKey } from "@amritk/helpers/read-key";
+import { mergeTraits } from "./merge-traits.js";
+import { normalizeMessage } from "./normalize-message.js";
+import { resolveNode } from "./resolve-pointer.js";
+const resolveTraits = (document, traits, issues, path) => {
+  if (!Array.isArray(traits))
+    return [];
+  const resolved = [];
+  for (const [index, trait] of traits.entries()) {
+    const node = resolveNode(document, trait, issues, `${path}/traits/${index}`);
+    if (node !== void 0)
+      resolved.push(node);
+  }
+  return resolved;
+};
+const extractChannelsV2 = (document, issues) => {
+  const channelsMap = readKey(document, "channels");
+  if (typeof channelsMap !== "object" || channelsMap === null)
+    return [];
+  const defaultContentType = readKey(document, "defaultContentType");
+  const channels = [];
+  for (const [channelKey, rawChannel] of Object.entries(channelsMap)) {
+    const channelPath = `#/channels/${channelKey}`;
+    const channel = resolveNode(document, rawChannel, issues, channelPath);
+    if (channel === void 0)
+      continue;
+    const messages = [];
+    let positional = 0;
+    for (const operationKey of ["publish", "subscribe"]) {
+      const operation = readKey(channel, operationKey);
+      if (typeof operation !== "object" || operation === null)
+        continue;
+      const direction = operationKey === "publish" ? "receive" : "send";
+      const operationPath = `${channelPath}/${operationKey}`;
+      const rawMessage = readKey(operation, "message");
+      if (rawMessage === void 0)
+        continue;
+      const messageNode = resolveNode(document, rawMessage, issues, `${operationPath}/message`);
+      if (messageNode === void 0)
+        continue;
+      const oneOf = readKey(messageNode, "oneOf");
+      const items = Array.isArray(oneOf) ? oneOf : [messageNode];
+      for (const [index, item] of items.entries()) {
+        const itemPath = Array.isArray(oneOf) ? `${operationPath}/message/oneOf/${index}` : `${operationPath}/message`;
+        const resolved = resolveNode(document, item, issues, itemPath);
+        if (resolved === void 0)
+          continue;
+        const merged = mergeTraits(resolved, resolveTraits(document, readKey(resolved, "traits"), issues, itemPath), "trait");
+        positional++;
+        const declaredName = readKey(merged, "name");
+        const messageId = readKey(merged, "messageId");
+        const name = typeof declaredName === "string" && declaredName !== "" ? declaredName : typeof messageId === "string" && messageId !== "" ? messageId : `message-${positional}`;
+        const contentType = readKey(merged, "contentType") ?? defaultContentType;
+        messages.push(normalizeMessage({
+          name,
+          channelKey,
+          direction,
+          ...typeof contentType === "string" ? { contentType } : {},
+          payloadSchemaFormat: readKey(merged, "schemaFormat"),
+          payload: readKey(merged, "payload"),
+          headers: readKey(merged, "headers")
+        }, document, issues, itemPath));
+      }
+    }
+    channels.push({ key: channelKey, address: channelKey, messages });
+  }
+  return channels;
+};
+export {
+  extractChannelsV2
+};

package/dist/extract-channels-v3.d.ts

@@ -0,0 +1,10 @@
+import type { ExtractionIssue, NormalizedChannel } from './types.js';
+/**
+ * Walks an AsyncAPI 3.0 document's channels into the normalized model.
+ *
+ * Payload and headers values may each be a Multi Format Schema Object — 3.0
+ * moved `schemaFormat` into that wrapper — so both are unwrapped here and the
+ * format travels with the schema it labels. Message names are the channel's
+ * `messages` map keys, which 3.0 makes mandatory and unique per channel.
+ */
+export declare const extractChannelsV3: (document: Record<string, unknown>, issues: ExtractionIssue[]) => NormalizedChannel[];

package/dist/extract-channels-v3.js

@@ -0,0 +1,208 @@
+import { readKey } from "@amritk/helpers/read-key";
+import { mergeTraits } from "./merge-traits.js";
+import { normalizeMessage } from "./normalize-message.js";
+import { resolveNode } from "./resolve-pointer.js";
+import { unwrapMultiFormat } from "./unwrap-multi-format.js";
+const CHANNEL_REF = /^#\/channels\/([^/]+)$/;
+const CHANNEL_MESSAGE_REF = /^#\/channels\/([^/]+)\/messages\/([^/]+)$/;
+const decodeSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
+const memberKey = (map, segment) => {
+  const raw = decodeSegment(segment);
+  if (readKey(map, raw) !== void 0)
+    return raw;
+  if (raw.includes("%")) {
+    try {
+      const decoded = decodeURIComponent(raw);
+      if (readKey(map, decoded) !== void 0)
+        return decoded;
+    } catch {
+    }
+  }
+  return void 0;
+};
+const resolveTraits = (document, traits, issues, path) => {
+  if (!Array.isArray(traits))
+    return [];
+  const resolved = [];
+  for (const [index, trait] of traits.entries()) {
+    const node = resolveNode(document, trait, issues, `${path}/traits/${index}`);
+    if (node !== void 0)
+      resolved.push(node);
+  }
+  return resolved;
+};
+const collectDirections = (document, channelsMap, issues) => {
+  const directions = /* @__PURE__ */ new Map();
+  const operationsMap = readKey(document, "operations");
+  if (typeof operationsMap !== "object" || operationsMap === null)
+    return directions;
+  const channelKeyOf = (channelNode, path) => {
+    if (typeof channelNode === "object" && channelNode !== null) {
+      const ref = readKey(channelNode, "$ref");
+      if (typeof ref === "string") {
+        const match = CHANNEL_REF.exec(ref);
+        if (match) {
+          const key = memberKey(channelsMap, match[1]);
+          if (key !== void 0)
+            return key;
+        }
+      }
+    }
+    const scratch = [];
+    const resolved = resolveNode(document, channelNode, scratch, path);
+    if (resolved !== void 0) {
+      for (const [key, value] of Object.entries(channelsMap)) {
+        if (value === channelNode || value === resolved)
+          return key;
+        if (resolveNode(document, value, scratch, path) === resolved)
+          return key;
+      }
+    }
+    return void 0;
+  };
+  const processOperationLike = (operation, action, operationPath, kind) => {
+    const channelNode = readKey(operation, "channel");
+    let channelKey;
+    let channelMessages;
+    if (channelNode !== void 0 || kind === "operation") {
+      channelKey = channelKeyOf(channelNode, `${operationPath}/channel`);
+      if (channelKey === void 0) {
+        issues.push({
+          path: `${operationPath}/channel`,
+          message: `${kind} channel does not resolve; direction skipped`
+        });
+        return;
+      }
+      const channel = resolveNode(document, readKey(channelsMap, channelKey), issues, `#/channels/${channelKey}`);
+      channelMessages = channel === void 0 ? void 0 : readKey(channel, "messages");
+    }
+    const opMessages = readKey(operation, "messages");
+    const messageTargets = [];
+    if (Array.isArray(opMessages)) {
+      for (const [index, item] of opMessages.entries()) {
+        const ref = typeof item === "object" && item !== null ? readKey(item, "$ref") : void 0;
+        const match = typeof ref === "string" ? CHANNEL_MESSAGE_REF.exec(ref) : null;
+        if (match && channelKey === void 0) {
+          const refChannelKey = memberKey(channelsMap, match[1]);
+          const refChannel = refChannelKey === void 0 ? void 0 : resolveNode(document, readKey(channelsMap, refChannelKey), issues, `#/channels/${refChannelKey}`);
+          const refMessages = refChannel === void 0 ? void 0 : readKey(refChannel, "messages");
+          const messageKey = typeof refMessages === "object" && refMessages !== null ? memberKey(refMessages, match[2]) : void 0;
+          if (refChannelKey !== void 0 && messageKey !== void 0) {
+            messageTargets.push([refChannelKey, messageKey]);
+            continue;
+          }
+        }
+        if (match && channelKey !== void 0 && typeof channelMessages === "object" && channelMessages !== null) {
+          const key = memberKey(channelMessages, match[2]);
+          if (key !== void 0) {
+            messageTargets.push([channelKey, key]);
+            continue;
+          }
+        }
+        let found = false;
+        if (channelKey !== void 0 && typeof channelMessages === "object" && channelMessages !== null) {
+          const scratch = [];
+          const itemPath = `${operationPath}/messages/${index}`;
+          const resolvedItem = resolveNode(document, item, scratch, itemPath);
+          for (const [key, value] of Object.entries(channelMessages)) {
+            const matches = value === item || resolvedItem !== void 0 && (value === resolvedItem || resolveNode(document, value, scratch, itemPath) === resolvedItem);
+            if (matches) {
+              messageTargets.push([channelKey, key]);
+              found = true;
+              break;
+            }
+          }
+        }
+        if (!found) {
+          issues.push({
+            path: `${operationPath}/messages/${index}`,
+            message: `${kind} message reference does not resolve to a channel message; direction skipped`
+          });
+        }
+      }
+    } else if (channelKey !== void 0 && typeof channelMessages === "object" && channelMessages !== null) {
+      for (const key of Object.keys(channelMessages)) {
+        messageTargets.push([channelKey, key]);
+      }
+    }
+    for (const [messageChannelKey, messageKey] of messageTargets) {
+      const key = `${messageChannelKey}\0${messageKey}`;
+      const existing = directions.get(key);
+      if (existing === void 0) {
+        directions.set(key, action);
+      } else if (existing !== action) {
+        issues.push({
+          path: operationPath,
+          message: `message "${messageKey}" on channel "${messageChannelKey}" is both sent and received; keeping "${existing}"`
+        });
+      }
+    }
+  };
+  for (const [operationKey, rawOperation] of Object.entries(operationsMap)) {
+    const operationPath = `#/operations/${operationKey}`;
+    const operation = resolveNode(document, rawOperation, issues, operationPath);
+    if (operation === void 0)
+      continue;
+    const action = readKey(operation, "action");
+    if (action !== "send" && action !== "receive")
+      continue;
+    processOperationLike(operation, action, operationPath, "operation");
+    const rawReply = readKey(operation, "reply");
+    if (rawReply !== void 0) {
+      const reply = resolveNode(document, rawReply, issues, `${operationPath}/reply`);
+      if (reply !== void 0) {
+        processOperationLike(reply, action === "send" ? "receive" : "send", `${operationPath}/reply`, "reply");
+      }
+    }
+  }
+  return directions;
+};
+const extractChannelsV3 = (document, issues) => {
+  const channelsMap = readKey(document, "channels");
+  if (typeof channelsMap !== "object" || channelsMap === null)
+    return [];
+  const defaultContentType = readKey(document, "defaultContentType");
+  const directions = collectDirections(document, channelsMap, issues);
+  const channels = [];
+  for (const [channelKey, rawChannel] of Object.entries(channelsMap)) {
+    const channelPath = `#/channels/${channelKey}`;
+    const channel = resolveNode(document, rawChannel, issues, channelPath);
+    if (channel === void 0)
+      continue;
+    const address = readKey(channel, "address");
+    const messages = [];
+    const messagesMap = readKey(channel, "messages");
+    if (typeof messagesMap === "object" && messagesMap !== null) {
+      for (const [messageKey, rawMessage] of Object.entries(messagesMap)) {
+        const messagePath = `${channelPath}/messages/${messageKey}`;
+        const resolved = resolveNode(document, rawMessage, issues, messagePath);
+        if (resolved === void 0)
+          continue;
+        const merged = mergeTraits(resolved, resolveTraits(document, readKey(resolved, "traits"), issues, messagePath), "target");
+        const payload = unwrapMultiFormat(readKey(merged, "payload"));
+        const headers = unwrapMultiFormat(readKey(merged, "headers"));
+        const contentType = readKey(merged, "contentType") ?? defaultContentType;
+        const direction = directions.get(`${channelKey}\0${messageKey}`);
+        messages.push(normalizeMessage({
+          name: messageKey,
+          channelKey,
+          ...direction !== void 0 ? { direction } : {},
+          ...typeof contentType === "string" ? { contentType } : {},
+          payloadSchemaFormat: payload.schemaFormat,
+          payload: payload.schema,
+          headersSchemaFormat: headers.schemaFormat,
+          headers: headers.schema
+        }, document, issues, messagePath));
+      }
+    }
+    channels.push({
+      key: channelKey,
+      ...typeof address === "string" && address !== "" ? { address } : {},
+      messages
+    });
+  }
+  return channels;
+};
+export {
+  extractChannelsV3
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type DetectedVersion, detectAsyncApiVersion } from './detect-version.js';
+export { extractAsyncApi } from './extract-async-api.js';
+export { mergeTraits } from './merge-traits.js';
+export { listMessageSchemas } from './message-schemas.js';
+export { classifySchemaFormat, type SchemaFormatFamily } from './schema-format.js';
+export type { AsyncApiModel, ExtractedSchema, ExtractionIssue, MessageDirection, NormalizedChannel, NormalizedMessage, } from './types.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+import { detectAsyncApiVersion } from "./detect-version.js";
+import { extractAsyncApi } from "./extract-async-api.js";
+import { mergeTraits } from "./merge-traits.js";
+import { listMessageSchemas } from "./message-schemas.js";
+import { classifySchemaFormat } from "./schema-format.js";
+export {
+  classifySchemaFormat,
+  detectAsyncApiVersion,
+  extractAsyncApi,
+  listMessageSchemas,
+  mergeTraits
+};

package/dist/merge-traits.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which side of a key conflict wins when a trait and its target both set it.
+ * Both majors define trait application via JSON Merge Patch (RFC 7386), but
+ * they disagree on who patches whom — and 3.0 changed the answer on purpose:
+ *
+ * - `'trait'` — AsyncAPI 2.x: traits "MUST be merged into the message object
+ *   using the JSON Merge Patch algorithm in the same order they are defined",
+ *   so each trait is the *patch* and its values override the target's.
+ * - `'target'` — AsyncAPI 3.0: "A property on a trait MUST NOT override the
+ *   same property on the target object" — the target is applied last.
+ */
+export type TraitPrecedence = 'trait' | 'target';
+/**
+ * Applies a message's (or operation's) traits per the requested precedence:
+ * with `'trait'` each trait patches the accumulating target in declaration
+ * order; with `'target'` the traits accumulate first and the target overlays
+ * them, its own values — authored `null`s included — kept verbatim. Merging
+ * happens *before* anything reads `schemaFormat` off the result: a
+ * trait-contributed format is just as binding as an inline one, and reading
+ * it pre-merge is how an Avro payload gets misjudged as JSON Schema.
+ *
+ * The `traits` key itself is dropped from the result — it has been applied,
+ * and a leftover copy would read as still-pending.
+ */
+export declare const mergeTraits: (target: Record<string, unknown>, traits: readonly Record<string, unknown>[], precedence: TraitPrecedence) => Record<string, unknown>;

package/dist/merge-traits.js

@@ -0,0 +1,51 @@
+import { assignKey } from "@amritk/helpers/assign-key";
+import { readKey } from "@amritk/helpers/read-key";
+const applyMergePatch = (target, patch) => {
+  if (typeof patch !== "object" || patch === null || Array.isArray(patch))
+    return patch;
+  const base = typeof target === "object" && target !== null && !Array.isArray(target) ? target : {};
+  const result = {};
+  for (const [key, value] of Object.entries(base))
+    assignKey(result, key, value);
+  for (const key of Object.keys(patch)) {
+    const value = readKey(patch, key);
+    if (value === null) {
+      delete result[key];
+    } else {
+      assignKey(result, key, applyMergePatch(readKey(result, key), value));
+    }
+  }
+  return result;
+};
+const overlayTarget = (base, target) => {
+  if (typeof target !== "object" || target === null || Array.isArray(target))
+    return target;
+  if (typeof base !== "object" || base === null || Array.isArray(base))
+    return structuredClone(target);
+  const result = {};
+  for (const [key, value] of Object.entries(base))
+    assignKey(result, key, value);
+  for (const key of Object.keys(target)) {
+    assignKey(result, key, overlayTarget(readKey(result, key), readKey(target, key)));
+  }
+  return result;
+};
+const mergeTraits = (target, traits, precedence) => {
+  let merged;
+  if (precedence === "trait") {
+    merged = structuredClone(target);
+    for (const trait of traits)
+      merged = applyMergePatch(merged, trait);
+  } else {
+    merged = {};
+    for (const trait of traits)
+      merged = applyMergePatch(merged, trait);
+    merged = overlayTarget(merged, target);
+  }
+  const result = merged;
+  delete result["traits"];
+  return result;
+};
+export {
+  mergeTraits
+};

package/dist/message-schemas.d.ts

@@ -0,0 +1,19 @@
+import type { AsyncApiModel, ExtractedSchema, ExtractionIssue } from './types.js';
+/**
+ * Flattens the model into the list of generatable schemas, each with the
+ * output subdirectory and root type name the CLI hands to `buildSchema` —
+ * `channels/<channel>/<message>/` per payload, with headers in a sibling
+ * `<message>-headers/` tree, mirroring how `--schema-dir` gives every schema
+ * its own directory.
+ *
+ * The root type name comes from the message identity (`LightMeasured`), never
+ * the schema's `title`: two messages titled "Event" are distinct messages, and
+ * the directory layout already says which is which. Messages without a usable
+ * payload or headers schema (skipped formats, absent payloads) contribute
+ * nothing here — their issues already sit on the model.
+ *
+ * Name collisions append to `issues`, which the model shares by reference —
+ * callers reading `model.issues` after this call see them; pass an array to
+ * collect them separately.
+ */
+export declare const listMessageSchemas: (model: AsyncApiModel, issues?: ExtractionIssue[]) => ExtractedSchema[];