@amritk/asyncapi 0.1.0

package/dist/message-schemas.js

@@ -0,0 +1,62 @@
+import { toKebabCase } from "@amritk/helpers/ref-to-filename";
+import { refToName } from "@amritk/helpers/ref-to-name";
+const sanitizeToken = (value, fallback) => {
+  const token = toKebabCase(value).replace(/[^\p{ID_Continue}.]+/gu, "-").replace(/-{2,}/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  return token === "" ? fallback : token;
+};
+const claimToken = (base, taken, issues, path) => {
+  let token = base;
+  for (let n = 2; taken.has(token); n++) {
+    token = `${base}-${n}`;
+  }
+  if (token !== base) {
+    issues.push({ path, message: `output name "${base}" already claimed; using "${token}"` });
+  }
+  taken.add(token);
+  return token;
+};
+const claimMessageToken = (base, taken, issues, path) => {
+  let token = base;
+  for (let n = 2; taken.has(token) || taken.has(`${token}-headers`); n++) {
+    token = `${base}-${n}`;
+  }
+  if (token !== base) {
+    issues.push({ path, message: `output name "${base}" already claimed; using "${token}"` });
+  }
+  taken.add(token);
+  taken.add(`${token}-headers`);
+  return token;
+};
+const listMessageSchemas = (model, issues) => {
+  const collected = issues ?? model.issues;
+  const schemas = [];
+  const channelTokens = /* @__PURE__ */ new Set();
+  for (const channel of model.channels) {
+    const channelToken = claimToken(sanitizeToken(channel.key, "channel"), channelTokens, collected, `#/channels/${channel.key}`);
+    const messageTokens = /* @__PURE__ */ new Set();
+    for (const message of channel.messages) {
+      if (message.payload === void 0 && message.headers === void 0)
+        continue;
+      const messageToken = claimMessageToken(sanitizeToken(message.name, "message"), messageTokens, collected, `#/channels/${channel.key}/messages/${message.name}`);
+      const rootTypeName = refToName(messageToken);
+      if (message.payload !== void 0) {
+        schemas.push({
+          subDir: `channels/${channelToken}/${messageToken}`,
+          rootTypeName,
+          schema: message.payload
+        });
+      }
+      if (message.headers !== void 0) {
+        schemas.push({
+          subDir: `channels/${channelToken}/${messageToken}-headers`,
+          rootTypeName: `${rootTypeName}Headers`,
+          schema: message.headers
+        });
+      }
+    }
+  }
+  return schemas;
+};
+export {
+  listMessageSchemas
+};

package/dist/normalize-message.d.ts

@@ -0,0 +1,29 @@
+import type { ExtractionIssue, MessageDirection, NormalizedMessage } from './types.js';
+export type RawMessage = {
+    readonly name: string;
+    readonly channelKey: string;
+    readonly direction?: MessageDirection;
+    readonly contentType?: string;
+    /** The message's effective payload `schemaFormat` (post-trait-merge / unwrapped). */
+    readonly payloadSchemaFormat?: unknown;
+    readonly payload?: unknown;
+    /**
+     * The headers' own format: in 2.x headers are always an AsyncAPI Schema
+     * Object whatever the payload declares, while a 3.0 headers value may carry
+     * its own Multi Format wrapper — so the two cannot share one field.
+     */
+    readonly headersSchemaFormat?: unknown;
+    readonly headers?: unknown;
+};
+/**
+ * Turns one raw message (already dereferenced and trait-merged by the version
+ * walkers) into a {@link NormalizedMessage}, normalizing its payload and
+ * headers into self-contained 2020-12 schemas.
+ *
+ * A schema whose format is not a JSON Schema dialect — Avro, Protobuf, a
+ * malformed value — is skipped with an issue naming the format, keeping the
+ * message itself in the model so a consumer can still see it exists. A
+ * non-object schema (AsyncAPI allows boolean schemas; the generators need an
+ * object root) is skipped the same way.
+ */
+export declare const normalizeMessage: (raw: RawMessage, document: unknown, issues: ExtractionIssue[], path: string) => NormalizedMessage;

package/dist/normalize-message.js

@@ -0,0 +1,36 @@
+import { normalizeSchema } from "./normalize-schema.js";
+import { rebaseComponentRefs } from "./rebase-component-refs.js";
+import { classifySchemaFormat } from "./schema-format.js";
+const normalizeMessage = (raw, document, issues, path) => {
+  const normalizeOne = (value, schemaFormat, label) => {
+    if (value === void 0)
+      return void 0;
+    const family = classifySchemaFormat(schemaFormat);
+    if (family === "unsupported") {
+      issues.push({
+        path: `${path}/${label}`,
+        message: `skipped: unsupported schemaFormat ${JSON.stringify(schemaFormat)} (not a JSON Schema dialect)`
+      });
+      return void 0;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      issues.push({ path: `${path}/${label}`, message: `skipped: ${label} is not an object schema` });
+      return void 0;
+    }
+    return rebaseComponentRefs(normalizeSchema(value, family), document, family, issues, `${path}/${label}`);
+  };
+  const payload = normalizeOne(raw.payload, raw.payloadSchemaFormat, "payload");
+  const headers = normalizeOne(raw.headers, raw.headersSchemaFormat, "headers");
+  return {
+    name: raw.name,
+    channelKey: raw.channelKey,
+    ...raw.direction !== void 0 ? { direction: raw.direction } : {},
+    ...raw.contentType !== void 0 ? { contentType: raw.contentType } : {},
+    ...typeof raw.payloadSchemaFormat === "string" ? { schemaFormat: raw.payloadSchemaFormat } : {},
+    ...payload !== void 0 ? { payload } : {},
+    ...headers !== void 0 ? { headers } : {}
+  };
+};
+export {
+  normalizeMessage
+};

package/dist/normalize-schema.d.ts

@@ -0,0 +1,24 @@
+import type { SchemaFormatFamily } from './schema-format.js';
+/**
+ * Normalizes one extracted schema into the 2020-12 conventions the generators
+ * expect, according to the dialect its `schemaFormat` named:
+ *
+ * - `'asyncapi'` / `'draft-07'` — run the draft-07 upgrade (`definitions` →
+ *   `$defs`, refs rewritten, nested defs hoisted). The upgrade only fires on a
+ *   schema that *declares* draft-07, and an AsyncAPI payload almost never
+ *   carries `$schema` at all, so the declaration is stamped on first: the
+ *   dialect was declared at the message level, out of the schema's sight. The
+ *   upgrade strips the stamp again on output.
+ * - `'openapi'` — fold `nullable: true` into the `type` list, the one 3.0-ism
+ *   the generators would otherwise read as "never null".
+ * - `'2020-12'` — pass through.
+ *
+ * Keywords the AsyncAPI dialect adds beyond draft-07 (and draft-07 spellings
+ * the upgrade does not rewrite, like array-form `items`) pass through
+ * unchanged: `@amritk/runtime-validators` implements them directly, and an
+ * unknown keyword is an annotation everywhere else in the pipeline.
+ *
+ * An empty `$defs` left behind by the upgrade is dropped so a schema with no
+ * definitions round-trips without growing keys.
+ */
+export declare const normalizeSchema: (schema: Record<string, unknown>, family: Exclude<SchemaFormatFamily, 'unsupported'>) => Record<string, unknown>;

package/dist/normalize-schema.js

@@ -0,0 +1,18 @@
+import { foldNullable } from "@amritk/helpers/fold-nullable";
+import { upgradeDraft07Schema } from "@amritk/helpers/upgrade-draft07-schema";
+const normalizeSchema = (schema, family) => {
+  if (family === "openapi")
+    return foldNullable(schema);
+  if (family === "2020-12")
+    return schema;
+  const upgraded = upgradeDraft07Schema({ ...schema, $schema: "http://json-schema.org/draft-07/schema" });
+  const defs = upgraded["$defs"];
+  if (typeof defs === "object" && defs !== null && Object.keys(defs).length === 0) {
+    const { $defs: _, ...rest } = upgraded;
+    return rest;
+  }
+  return upgraded;
+};
+export {
+  normalizeSchema
+};

package/dist/rebase-component-refs.d.ts

@@ -0,0 +1,40 @@
+import type { SchemaFormatFamily } from './schema-format.js';
+import type { ExtractionIssue } from './types.js';
+/**
+ * Makes an extracted schema self-contained: every `$ref` into the document's
+ * `#/components/schemas/...` is rewritten to a local `#/$defs/...` entry, and
+ * the referenced components — transitively, since components reference each
+ * other — are copied in beside it, normalized with the same dialect rules as
+ * the root.
+ *
+ * Copying rather than leaving document-relative pointers is what lets each
+ * message's schema stand alone as a generator input; the cost is that a
+ * component used by N messages appears in N output trees, the same trade
+ * `--schema-dir` makes across schema files. Component names keep their exact
+ * spelling as `$defs` keys so the rewritten pointers resolve; a name the root
+ * schema already claims in its own `$defs` (or one needing pointer escapes) is
+ * moved to a `component-` prefixed key instead, consistently across every ref
+ * to it.
+ *
+ * A copied component's own definitions cannot stay nested: normalization
+ * renames a draft-07 `definitions` block to a component-root `$defs` and
+ * rewrites the component's internal refs to `#/$defs/...` — pointers that,
+ * embedded under the message root, would resolve against the *root's* `$defs`
+ * and land on nothing (or on the wrong schema). So each copied component's
+ * definitions — from `$defs` *and* from a `definitions` block a
+ * 2020-12/OpenAPI component keeps verbatim, each block under its own key —
+ * are hoisted to the root under `<component>-<name>` keys, with the
+ * component's internal refs and any external ref whose pointer tail dives
+ * through a block re-aimed at the hoisted entries.
+ *
+ * Two more pointer shapes are handled the same way: a tail through a Multi
+ * Format component's `schema` wrapper key (the copy is unwrapped, so the hop
+ * is stripped), and a document-root `#/$defs/...` reference — which the
+ * cross-file resolver manufactures when it hoists a reference cycle onto the
+ * document root — whose target is copied in beside the components.
+ *
+ * A reference to anything the document does not declare becomes an empty
+ * (`{}`, match-anything) definition plus an issue — one dangling pointer
+ * should cost precision on one branch, not the whole message.
+ */
+export declare const rebaseComponentRefs: (root: Record<string, unknown>, document: unknown, family: Exclude<SchemaFormatFamily, 'unsupported'>, issues: ExtractionIssue[], path: string) => Record<string, unknown>;

package/dist/rebase-component-refs.js

@@ -0,0 +1,349 @@
+import { assignKey } from "@amritk/helpers/assign-key";
+import { entersSchemaMap, isDataPosition } from "@amritk/helpers/build-resource-registry";
+import { assertSchemaDepth } from "@amritk/helpers/max-schema-depth";
+import { readKey } from "@amritk/helpers/read-key";
+import { normalizeSchema } from "./normalize-schema.js";
+import { classifySchemaFormat } from "./schema-format.js";
+import { unwrapMultiFormat } from "./unwrap-multi-format.js";
+const COMPONENT_SCHEMA_REF = /^#\/components\/schemas\/([^/]+)(\/.*)?$/;
+const TAIL_THROUGH_DEFS = /^\/(definitions|\$defs)\/([^/]+)(\/.*)?$/;
+const LOCAL_DEFS_REF = /^#\/(\$defs|definitions)\/([^/]+)(\/.*)?$/;
+const NAME_MAP_KEYWORDS = /* @__PURE__ */ new Set(["properties", "patternProperties", "dependentSchemas", "dependencies"]);
+const decodeSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
+const KEYWORD_SEGMENTS = /* @__PURE__ */ new Set(["definitions", "$defs", "schema", "schemaFormat"]);
+const decodeKeywordSegments = (pointer) => pointer.split("/").map((segment) => {
+  if (!segment.includes("%"))
+    return segment;
+  try {
+    const decoded = decodeURIComponent(segment);
+    return KEYWORD_SEGMENTS.has(decoded) ? decoded : segment;
+  } catch {
+    return segment;
+  }
+}).join("/");
+const divesThroughDefs = (tail) => {
+  let expectName = false;
+  for (const rawSegment of tail.split("/").slice(1)) {
+    const segment = decodeSegment(rawSegment);
+    if (expectName) {
+      expectName = false;
+      continue;
+    }
+    if (segment === "definitions" || segment === "$defs")
+      return true;
+    if (NAME_MAP_KEYWORDS.has(segment))
+      expectName = true;
+  }
+  return false;
+};
+const sanitizeKey = (name) => name.replace(/[~/%]+/g, "-");
+const ROOT_SCOPE = { kind: "root" };
+const DOC_DEF_SCOPE = { kind: "docDef" };
+const rebaseComponentRefs = (root, document, family, issues, path) => {
+  const documentRecord = typeof document === "object" && document !== null && !Array.isArray(document) ? document : void 0;
+  const componentSchemas = documentRecord ? readKey(readKey(documentRecord, "components") ?? {}, "schemas") : void 0;
+  const documentDefs = (() => {
+    const block = documentRecord === void 0 ? void 0 : readKey(documentRecord, "$defs");
+    return typeof block === "object" && block !== null && !Array.isArray(block) ? block : void 0;
+  })();
+  const rootDefs = readKey(root, "$defs");
+  const rootOwnDefNames = new Set(typeof rootDefs === "object" && rootDefs !== null ? Object.keys(rootDefs) : []);
+  const taken = new Set(rootOwnDefNames);
+  const keyByName = /* @__PURE__ */ new Map();
+  const defKeyByName = /* @__PURE__ */ new Map();
+  const defKeyEntries = [];
+  const docDefKeyByName = /* @__PURE__ */ new Map();
+  const unresolvable = [];
+  const componentQueue = [];
+  const docDefQueue = [];
+  const claimKey = (preferred) => {
+    let key = preferred;
+    for (let n = 2; taken.has(key); n++)
+      key = `${preferred}-${n}`;
+    taken.add(key);
+    return key;
+  };
+  const allocateKey = (name) => {
+    const existing = keyByName.get(name);
+    if (existing !== void 0)
+      return existing;
+    const key = taken.has(name) || /[~/%]/.test(name) ? claimKey(`component-${sanitizeKey(name)}`) : claimKey(name);
+    keyByName.set(name, key);
+    componentQueue.push(name);
+    return key;
+  };
+  const canonicalName = (segment) => {
+    const raw = decodeSegment(segment);
+    if (componentSchemas !== void 0 && readKey(componentSchemas, raw) !== void 0)
+      return raw;
+    if (raw.includes("%")) {
+      try {
+        const decoded = decodeURIComponent(raw);
+        if (componentSchemas !== void 0 && readKey(componentSchemas, decoded) !== void 0)
+          return decoded;
+      } catch {
+      }
+    }
+    return raw;
+  };
+  const allocateDefKey = (componentName, block, defName) => {
+    const mapKey = JSON.stringify([componentName, block, defName]);
+    const existing = defKeyByName.get(mapKey);
+    if (existing !== void 0)
+      return existing;
+    const componentKey = allocateKey(componentName);
+    const key = claimKey(`${componentKey}-${sanitizeKey(defName)}`);
+    defKeyByName.set(mapKey, key);
+    defKeyEntries.push({ component: componentName, block, defName, key });
+    return key;
+  };
+  const allocateDocDefKey = (name) => {
+    const existing = docDefKeyByName.get(name);
+    if (existing !== void 0)
+      return existing;
+    const key = /[~/%]/.test(name) ? claimKey(sanitizeKey(name)) : claimKey(name);
+    docDefKeyByName.set(name, key);
+    docDefQueue.push(name);
+    return key;
+  };
+  const isWrappedComponent = (name) => {
+    const raw = componentSchemas === void 0 ? void 0 : readKey(componentSchemas, name);
+    return raw !== void 0 && unwrapMultiFormat(raw).schemaFormat !== void 0;
+  };
+  const componentBlockNames = (name) => {
+    const raw = componentSchemas === void 0 ? void 0 : readKey(componentSchemas, name);
+    if (raw === void 0)
+      return void 0;
+    const { schemaFormat, schema } = unwrapMultiFormat(raw);
+    const componentFamily = schemaFormat === void 0 ? family : classifySchemaFormat(schemaFormat);
+    if (componentFamily === "unsupported" || typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+      return void 0;
+    }
+    const names = { definitions: /* @__PURE__ */ new Set(), $defs: /* @__PURE__ */ new Set() };
+    for (const blockName of ["definitions", "$defs"]) {
+      const block = readKey(schema, blockName);
+      if (typeof block !== "object" || block === null || Array.isArray(block))
+        continue;
+      for (const key of Object.keys(block))
+        names[blockName].add(key);
+    }
+    return names;
+  };
+  const canonicalDefName = (segment, declared) => {
+    const raw = decodeSegment(segment);
+    if (declared(raw))
+      return raw;
+    if (raw.includes("%")) {
+      try {
+        const decoded = decodeURIComponent(raw);
+        if (declared(decoded))
+          return decoded;
+      } catch {
+      }
+    }
+    return raw;
+  };
+  const degrade = (ref, reason) => {
+    const key = claimKey("unsupported-pointer");
+    unresolvable.push({ key, ref, reason });
+    return `#/$defs/${key}`;
+  };
+  const rewriteRef = (ref, scope) => {
+    const component = COMPONENT_SCHEMA_REF.exec(ref);
+    if (component) {
+      const name = canonicalName(component[1]);
+      let tail = decodeKeywordSegments(component[2] ?? "");
+      if (tail !== "" && isWrappedComponent(name)) {
+        const wrapperHop = /^\/schema(\/.*)?$/.exec(tail);
+        if (wrapperHop)
+          tail = wrapperHop[1] ?? "";
+        else if (/^\/schemaFormat(\/|$)/.test(tail))
+          return degrade(ref, "points into a Multi Format wrapper key the unwrapped copy does not keep");
+      }
+      const throughDefs = TAIL_THROUGH_DEFS.exec(tail);
+      if (throughDefs) {
+        const rest = throughDefs[3] ?? "";
+        if (divesThroughDefs(rest))
+          return degrade(ref, "dives through nested definitions, which rebasing does not support");
+        const block = throughDefs[1];
+        const blocks = componentBlockNames(name);
+        const defName = canonicalDefName(throughDefs[2], (candidate) => blocks !== void 0 && (blocks[block].has(candidate) || blocks.$defs.has(candidate)));
+        if (rest !== "") {
+          const declared = blocks !== void 0 && (blocks[block].has(defName) || blocks.$defs.has(defName) || blocks.definitions.has(defName));
+          if (!declared)
+            return degrade(ref, "points below a definition its component does not declare");
+        }
+        return `#/$defs/${allocateDefKey(name, block, defName)}${rest}`;
+      }
+      if (tail !== "" && componentBlockNames(name) === void 0)
+        return degrade(ref, "points into a component that cannot be copied");
+      if (tail !== "" && divesThroughDefs(tail))
+        return degrade(ref, "points through a definitions block in a form rebasing does not support");
+      return `#/$defs/${allocateKey(name)}${tail}`;
+    }
+    const local = LOCAL_DEFS_REF.exec(decodeKeywordSegments(ref));
+    if (local) {
+      const block = local[1];
+      const tail = local[3] ?? "";
+      const nestedTail = tail !== "" && divesThroughDefs(tail);
+      const degradeNestedTail = () => degrade(ref, "dives through nested definitions, which rebasing does not support");
+      if (scope.kind === "component") {
+        const defName = canonicalDefName(local[2], (candidate) => scope.blocks[block].has(candidate) || scope.blocks.$defs.has(candidate));
+        if (scope.blocks[block].has(defName)) {
+          if (nestedTail)
+            return degradeNestedTail();
+          return `#/$defs/${allocateDefKey(scope.component, block, defName)}${tail}`;
+        }
+        if (block === "definitions" && scope.blocks.$defs.has(defName)) {
+          if (nestedTail)
+            return degradeNestedTail();
+          return `#/$defs/${allocateDefKey(scope.component, "$defs", defName)}${tail}`;
+        }
+      }
+      if (block === "$defs") {
+        const defName = canonicalDefName(local[2], (candidate) => scope.kind === "root" && rootOwnDefNames.has(candidate) || documentDefs !== void 0 && readKey(documentDefs, candidate) !== void 0);
+        if (scope.kind === "root" && rootOwnDefNames.has(defName))
+          return ref;
+        if (documentDefs !== void 0 && readKey(documentDefs, defName) !== void 0) {
+          if (nestedTail)
+            return degradeNestedTail();
+          return `#/$defs/${allocateDocDefKey(defName)}${tail}`;
+        }
+      }
+      if (scope.kind === "component" && block === "$defs") {
+        const defName = canonicalDefName(local[2], (candidate) => scope.blocks.definitions.has(candidate));
+        if (scope.blocks.definitions.has(defName)) {
+          if (nestedTail)
+            return degradeNestedTail();
+          return `#/$defs/${allocateDefKey(scope.component, "definitions", defName)}${tail}`;
+        }
+      }
+    }
+    if (scope.kind === "component" && /^#\/(?:definitions|\$defs)$/.test(decodeKeywordSegments(ref)))
+      return degrade(ref, "points at a definitions block the copy does not keep");
+    return ref;
+  };
+  const rewrite = (node, depth, inSchemaMap, scope) => {
+    assertSchemaDepth(depth, "rebaseComponentRefs");
+    if (Array.isArray(node))
+      return node.map((item) => rewrite(item, depth + 1, inSchemaMap, scope));
+    if (typeof node !== "object" || node === null)
+      return node;
+    const record = node;
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (isDataPosition(key, inSchemaMap)) {
+        assignKey(result, key, value);
+      } else if (!inSchemaMap && key === "$ref" && typeof value === "string") {
+        assignKey(result, key, rewriteRef(value, scope));
+      } else {
+        assignKey(result, key, rewrite(value, depth + 1, entersSchemaMap(key, inSchemaMap), scope));
+      }
+    }
+    return result;
+  };
+  const rewrittenRoot = rewrite(root, 0, false, ROOT_SCOPE);
+  const copiedDefs = {};
+  const processedBlocks = /* @__PURE__ */ new Map();
+  const processComponent = (name) => {
+    const defsKey = keyByName.get(name);
+    const raw = componentSchemas === void 0 ? void 0 : readKey(componentSchemas, name);
+    if (raw === void 0) {
+      issues.push({
+        path,
+        message: `$ref to undeclared component "#/components/schemas/${name}"; treated as an unconstrained schema`
+      });
+      assignKey(copiedDefs, defsKey, {});
+      return;
+    }
+    const { schemaFormat, schema } = unwrapMultiFormat(raw);
+    const componentFamily = schemaFormat === void 0 ? family : classifySchemaFormat(schemaFormat);
+    if (componentFamily === "unsupported" || typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+      issues.push({
+        path,
+        message: componentFamily === "unsupported" ? `component "${name}" uses unsupported schemaFormat ${JSON.stringify(schemaFormat)}; treated as an unconstrained schema` : `component "${name}" is not an object schema; treated as an unconstrained schema`
+      });
+      assignKey(copiedDefs, defsKey, {});
+      return;
+    }
+    const normalized = normalizeSchema(schema, componentFamily);
+    const blocks = { definitions: /* @__PURE__ */ new Set(), $defs: /* @__PURE__ */ new Set() };
+    const blockValues = [];
+    for (const blockName of ["definitions", "$defs"]) {
+      const block = readKey(schema, blockName);
+      if (typeof block !== "object" || block === null || Array.isArray(block))
+        continue;
+      for (const [defName, value] of Object.entries(block)) {
+        blocks[blockName].add(defName);
+        blockValues.push({ block: blockName, defName, value });
+      }
+    }
+    processedBlocks.set(name, blocks);
+    const scope = { kind: "component", component: name, blocks };
+    for (const { block, defName, value } of blockValues) {
+      const prepared = typeof value === "object" && value !== null && !Array.isArray(value) ? normalizeSchema(value, componentFamily) : value;
+      assignKey(copiedDefs, allocateDefKey(name, block, defName), rewrite(prepared, 0, false, scope));
+    }
+    const { $defs: _, definitions: __, ...body } = normalized;
+    assignKey(copiedDefs, defsKey, rewrite(body, 0, false, scope));
+  };
+  const processDocDef = (name) => {
+    const key = docDefKeyByName.get(name);
+    const raw = documentDefs === void 0 ? void 0 : readKey(documentDefs, name);
+    if (raw === void 0 || typeof raw !== "object" || Array.isArray(raw)) {
+      issues.push({
+        path,
+        message: `$ref to "#/$defs/${name}" has no target on the document root; treated as an unconstrained schema`
+      });
+      assignKey(copiedDefs, key, {});
+      return;
+    }
+    assignKey(copiedDefs, key, rewrite(normalizeSchema(raw, family), 0, false, DOC_DEF_SCOPE));
+  };
+  let componentIndex = 0;
+  let docDefIndex = 0;
+  while (componentIndex < componentQueue.length || docDefIndex < docDefQueue.length) {
+    if (componentIndex < componentQueue.length) {
+      processComponent(componentQueue[componentIndex++]);
+    } else {
+      processDocDef(docDefQueue[docDefIndex++]);
+    }
+  }
+  for (const { component, block, defName, key } of defKeyEntries) {
+    if (readKey(copiedDefs, key) !== void 0)
+      continue;
+    const declared = processedBlocks.get(component);
+    const aliasBlock = block === "definitions" && declared?.$defs.has(defName) ? "$defs" : block === "$defs" && declared?.definitions.has(defName) ? "definitions" : void 0;
+    if (aliasBlock !== void 0) {
+      const aliasKey = defKeyByName.get(JSON.stringify([component, aliasBlock, defName]));
+      if (aliasKey !== void 0) {
+        assignKey(copiedDefs, key, readKey(copiedDefs, aliasKey));
+        continue;
+      }
+    }
+    issues.push({
+      path,
+      message: `$ref into "#/components/schemas/${component}" names a definition "${defName}" it does not declare; treated as an unconstrained schema`
+    });
+    assignKey(copiedDefs, key, {});
+  }
+  for (const { key, ref, reason } of unresolvable) {
+    issues.push({
+      path,
+      message: `$ref "${ref}" ${reason}; treated as an unconstrained schema`
+    });
+    assignKey(copiedDefs, key, {});
+  }
+  if (Object.keys(copiedDefs).length === 0)
+    return rewrittenRoot;
+  const existingDefs = typeof rewrittenRoot["$defs"] === "object" && rewrittenRoot["$defs"] !== null ? rewrittenRoot["$defs"] : {};
+  const mergedDefs = {};
+  for (const [key, value] of Object.entries(existingDefs))
+    assignKey(mergedDefs, key, value);
+  for (const [key, value] of Object.entries(copiedDefs))
+    assignKey(mergedDefs, key, value);
+  return { ...rewrittenRoot, $defs: mergedDefs };
+};
+export {
+  rebaseComponentRefs
+};

package/dist/resolve-pointer.d.ts

@@ -0,0 +1,21 @@
+import type { ExtractionIssue } from './types.js';
+/**
+ * Follows a same-document JSON Pointer (`#/a/b`) to its target value, or
+ * `undefined` when any segment is missing. Segments are unescaped per RFC 6901
+ * (`~1` → `/`, `~0` → `~`), and each map step reads own properties only — a
+ * pointer segment of `constructor` must find the document's key or nothing,
+ * never `Object.prototype`.
+ */
+export declare const getByPointer: (document: unknown, pointer: string) => unknown;
+/**
+ * Dereferences a document node that may be a Reference Object, following
+ * chained `$ref`s until an object without one (or a failure) is reached.
+ *
+ * Only same-document `#/...` pointers are followed: by the time extraction
+ * runs, cross-file and remote references are the loader's job
+ * (`@amritk/resolve-refs` inlines them), so one still standing here is
+ * reported rather than fetched. Failures — an external ref, a dangling
+ * pointer, a `$ref` cycle, a non-object target — land on `issues` and resolve
+ * to `undefined` so a single broken reference skips one node, not the run.
+ */
+export declare const resolveNode: (document: unknown, node: unknown, issues: ExtractionIssue[], path: string) => Record<string, unknown> | undefined;

package/dist/resolve-pointer.js

@@ -0,0 +1,61 @@
+import { readKey } from "@amritk/helpers/read-key";
+const getByPointer = (document, pointer) => {
+  if (pointer === "#" || pointer === "#/")
+    return document;
+  if (!pointer.startsWith("#/"))
+    return void 0;
+  let current = document;
+  for (const rawSegment of pointer.slice(2).split("/")) {
+    const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (Array.isArray(current)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index) || index < 0 || index >= current.length)
+        return void 0;
+      current = current[index];
+    } else if (typeof current === "object" && current !== null) {
+      const record = current;
+      let next = readKey(record, segment);
+      if (next === void 0 && segment.includes("%")) {
+        try {
+          next = readKey(record, decodeURIComponent(segment));
+        } catch {
+        }
+      }
+      if (next === void 0)
+        return void 0;
+      current = next;
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+};
+const resolveNode = (document, node, issues, path) => {
+  const seen = /* @__PURE__ */ new Set();
+  let current = node;
+  while (typeof current === "object" && current !== null && !Array.isArray(current)) {
+    const ref = readKey(current, "$ref");
+    if (typeof ref !== "string")
+      return current;
+    if (!ref.startsWith("#")) {
+      issues.push({ path, message: `external $ref "${ref}" was not resolved before extraction; node skipped` });
+      return void 0;
+    }
+    if (seen.has(ref)) {
+      issues.push({ path, message: `$ref cycle through "${ref}"; node skipped` });
+      return void 0;
+    }
+    seen.add(ref);
+    current = getByPointer(document, ref);
+    if (current === void 0) {
+      issues.push({ path, message: `$ref "${ref}" does not resolve; node skipped` });
+      return void 0;
+    }
+  }
+  issues.push({ path, message: "expected an object node; node skipped" });
+  return void 0;
+};
+export {
+  getByPointer,
+  resolveNode
+};

package/dist/schema-format.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The JSON Schema dialect a `schemaFormat` names, or `'unsupported'` for
+ * everything the pipeline cannot turn into JSON Schema (Avro, Protobuf, RAML,
+ * unrecognized media types). The four supported families each get their own
+ * normalization: the AsyncAPI default dialect and declared draft-07 go through
+ * the draft-07 upgrade, OpenAPI schema objects get `nullable` folded, and
+ * 2020-12 passes through.
+ */
+export type SchemaFormatFamily = 'asyncapi' | 'draft-07' | '2020-12' | 'openapi' | 'unsupported';
+/**
+ * Classifies a message's effective `schemaFormat`. An absent format means the
+ * AsyncAPI default dialect — the spec's own rule — so `undefined` is
+ * `'asyncapi'`, while a present-but-non-string value is malformed and lands in
+ * `'unsupported'` with everything else the pipeline cannot generate from.
+ */
+export declare const classifySchemaFormat: (schemaFormat: unknown) => SchemaFormatFamily;