@amritk/mjst 0.16.1 → 0.18.0

package/AI.md

@@ -41,13 +41,25 @@ mjst compile-api ./routes.ts --out ./dist/handler.ts
    point `--schema` at a JS/TS **module**; `avro` points it at a `.avsc` JSON
    document, which is read as data (no `import()`, so `--export` does not
    apply).
+6. **`--input asyncapi`** reads an AsyncAPI 2.x/3.0 document (JSON or YAML) and
+   generates from every message payload/headers schema, one subtree per message.
+   It rejects `--schema-dir`, `--out-file`, `--root-type`, and `--export`.
+7. **`--message-contracts`** (AsyncAPI only) additionally writes
+   `contracts/<channel>.ts` — a `defineMessages({ ... })` per channel, plus a
+   barrel. Those files import **`@amritk/api`**, which the *consuming* project
+   installs; the CLI does not put it there, and `--build` leaves the contracts
+   as `.ts` for that reason. Incompatible with `--types-only`. Use
+   `--discriminator <prop>` when the document tags frames with something other
+   than `type`; a channel carrying `x-mjst: { discriminator }` keeps its own.
 
 ## Common flags
 
 `--schema` / `--schema-dir`, `--out-dir` / `--out-file`, `--input`,
-`--validators`, `--examples`, `--types-only`, `--build`, `--strict`,
-`--strip-unknown`, `--readonly`, `--import-ext ts|js`, `--config <path>`,
-`--resolve-remote` / `--allowed-hosts` (SSRF-guarded remote `$ref`s).
+`--validators`, `--examples`, `--message-contracts`, `--discriminator`,
+`--types-only`, `--build`, `--strict`, `--strip-unknown`,
+`--unknown-keys count-keys|count-enumerable`, `--readonly`,
+`--import-ext ts|js`, `--config <path>`, `--resolve-remote` /
+`--allowed-hosts` (SSRF-guarded remote `$ref`s).
 
 ## Lint gotchas
 

package/README.md

@@ -37,7 +37,7 @@ yarn add -D @amritk/mjst
 bun add -d @amritk/mjst
 ```
 
-The package ships a `mjst` bin that runs under Node ≥ 20 (or Bun), so you can invoke it via `npx mjst`, `pnpm dlx mjst`, `yarn dlx mjst`, `bunx mjst`, or as a script in `package.json`.
+The package ships a `mjst` bin that runs under Node ≥ 20 (or Bun), so you can invoke it via `npx mjst`, `pnpm exec mjst`, `yarn mjst`, `bunx mjst`, or as a script in `package.json`.
 
 ---
 
@@ -64,7 +64,7 @@ npx mjst --schema ./schema.json --out-file ./generated/schema.ts --types-only
 ### Recursive — a whole folder of schemas
 
 Point `--schema-dir` at a directory of JSON Schemas and mjst generates parsers for every
-`*.json` file it finds, mirroring the directory layout under `--out-dir`:
+`*.json` file it finds (skipping `node_modules/` and dot-directories), mirroring the directory layout under `--out-dir`:
 
 ```bash
 npx mjst --schema-dir ./schemas --out-dir ./generated
@@ -188,7 +188,7 @@ npx mjst --config ./mjst.config.json
 ```
 
 > [!NOTE]
-> Validate your config against the bundled JSON Schema: [`config.schema.json`](./config.schema.json)
+> Validate your config against the repository's JSON Schema: [`config.schema.json`](./config.schema.json) (not included in the npm package)
 
 ---
 
@@ -220,7 +220,7 @@ With no `-r`, mjst discovers a `.lint.{yaml,yml,json,js,mjs}` ruleset by walking
 | Flag | Description |
 | --- | --- |
 | `<documents..>` | Files or globs to lint (positional). |
-| `-r`, `--ruleset` | Path to a ruleset file. Defaults to `.lint.*` discovery. |
+| `-r`, `--ruleset` | Path to a ruleset file, or a built-in preset (`oas`, `asyncapi`). Defaults to `.lint.*` discovery. |
 | `-F`, `--fail-severity` | Minimum severity that fails the run: `error` (default), `warn`, `info`, `hint`. |
 | `-D`, `--display-only-failures` | Only show findings at or above `--fail-severity`. |
 | `--stdin-filepath` | Path to associate with piped input (labels findings and enables ruleset discovery). |
@@ -230,6 +230,7 @@ With no `-r`, mjst discovers a `.lint.{yaml,yml,json,js,mjs}` ruleset by walking
 | `--allowed-hosts` | Restrict remote `$ref` fetches to these hosts (implies `--resolve-remote`). |
 | `--allow-private-hosts` | Permit remote `$ref`s to private/loopback hosts (SSRF guard, off by default). |
 | `--allowed-roots` | Extra directories a local `$ref` may resolve into, on top of the document's own (repeat the flag). |
+| `--encoding` | Input encoding for the linted files (default `utf8`). |
 | `-q`, `--quiet` | Suppress the findings report (the exit code still reflects findings). |
 
 By default `mjst lint` dereferences `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor` before running rules, so rules with `resolved: true` (the ruleset default) see through references. Internal and local cross-file refs resolve from disk — a finding on a cross-file node reports that file's own `line:column` — as long as they stay inside the linted document's own directory; use `--allowed-roots` to let a document reach a shared sibling folder. Remote refs are only fetched when you opt in with `--resolve-remote` or `--allowed-hosts`.
@@ -250,7 +251,7 @@ npx mjst compile-api src/routes.ts --out dist/handler.js
 npx mjst compile-api src/routes.ts --out dist/handler.js --options compile-options.json
 ```
 
-Every export of the routes module that looks like a route contract (`method`, `path`, `responses`) is compiled; the generated module imports those contracts back through `--routes-import` (default: the relative path from the out file to the routes module). The routes module is imported at build time, so it must be loadable by the runtime running mjst — run via `bunx` for TypeScript sources, or under Node install a loader such as `tsx` (`node --import tsx`).
+Every *named* export of the routes module that looks like a route contract (`method`, `path`, `responses`) is compiled (a `default` export is ignored, because the generated module imports each contract by name); the generated module imports those contracts back through `--routes-import` (default: the relative path from the out file to the routes module). The routes module is imported at build time, so it must be loadable by the runtime running mjst — run via `bunx` for TypeScript sources, or under Node install a loader such as `tsx` (`node --import tsx`).
 
 | Flag | Description |
 | --- | --- |
@@ -303,7 +304,7 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td align="center"><code>"json"</code></td>
 </tr>
 <tr>
-<td colspan="4">Source format of the schema. 'json' (default) reads a JSON Schema file directly. 'avro' reads an Apache Avro '.avsc' JSON document and converts it, needing no extra library. Any other format loads 'schema' as a module and converts it to JSON Schema with the matching adapter. Supported: 'typebox', 'zod' (zod v4+), 'valibot' (with @valibot/to-json-schema), and 'effect' — each requires the corresponding library installed in your project.<br><strong>Allowed:</strong> <code>"json"</code>, <code>"typebox"</code>, <code>"zod"</code>, <code>"valibot"</code>, <code>"effect"</code>, <code>"avro"</code></td>
+<td colspan="4">Source format of the schema. 'json' (default) reads a JSON Schema file directly. 'avro' reads an Apache Avro '.avsc' JSON document and converts it, needing no extra library. 'asyncapi' reads an AsyncAPI 2.x/3.0 document (JSON or YAML) and generates from every message payload/headers schema it declares. Any other format loads 'schema' as a module and converts it to JSON Schema with the matching adapter. Supported: 'typebox', 'zod' (zod v4+), 'valibot' (with @valibot/to-json-schema), and 'effect' — each requires the corresponding library installed in your project.<br><strong>Allowed:</strong> <code>"json"</code>, <code>"typebox"</code>, <code>"zod"</code>, <code>"valibot"</code>, <code>"effect"</code>, <code>"avro"</code>, <code>"asyncapi"</code></td>
 </tr>
 <tr>
 <td>📦 <code>export</code></td>
@@ -312,7 +313,7 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td align="center"></td>
 </tr>
 <tr>
-<td colspan="4">Which export of the schema module to use when 'input' names a module format (anything but 'json' and 'avro', which are read as data). Defaults to the default export, or the sole named export when the module has exactly one.</td>
+<td colspan="4">Which export of the schema module to use when 'input' names a module format (anything but 'json', 'avro', and 'asyncapi', which are read as data). Defaults to the default export, or the sole named export when the module has exactly one.</td>
 </tr>
 <tr>
 <td>📁 <code>outDir</code></td>
@@ -360,6 +361,24 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td colspan="4">Also emit test-data files for every schema into an examples/ subdirectory of the output destination: a fast-check arbitrary (FooArbitrary) that produces schema-valid values and a concrete fooExample value. Under schemaDir the examples mirror the schema layout so they never collide with the parser output. The generated arbitraries import fast-check, which consumers must install as a (dev) dependency; the static example values have no runtime dependencies.</td>
 </tr>
 <tr>
+<td>🔌 <code>messageContracts</code></td>
+<td><code>--message-contracts</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit a @amritk/api channel contract per AsyncAPI channel into a contracts/ subdirectory: one defineMessages({ ... }) module naming every message that channel carries — keyed by the value its discriminator property carries on the wire, with that property stripped out of each payload because the runtime removes it before validating — plus a barrel re-exporting them. Requires input 'asyncapi', which is the only input that has channels and operations to project from. Incompatible with typesOnly: a contract is a runtime value, not a type. The generated modules import @amritk/api, which the consuming project must install; it is not a dependency of the generated parsers.</td>
+</tr>
+<tr>
+<td>🏷️ <code>discriminator</code></td>
+<td><code>--discriminator &lt;prop&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"type"</code></td>
+</tr>
+<tr>
+<td colspan="4">Property name that says which message a frame is, for the contracts messageContracts emits. Defaults to 'type', matching @amritk/api. A channel that declares its own with 'x-mjst': { 'discriminator': '...' } keeps it — one flag covers a whole run, and a run may span channels that disagree. Only meaningful together with messageContracts.<br><strong>Examples:</strong> <code>"event"</code></td>
+</tr>
+<tr>
 <td>🔨 <code>build</code></td>
 <td><code>--build</code></td>
 <td><code>boolean</code></td>
@@ -423,6 +442,15 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td colspan="4">Emit every property, array, and record in the generated type definitions as readonly, producing deeply immutable types. Affects type definitions only; the generated parsers still build and return plain objects.</td>
 </tr>
 <tr>
+<td>🔢 <code>unknownKeys</code></td>
+<td><code>--unknown-keys &lt;strategy&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"count-keys"</code></td>
+</tr>
+<tr>
+<td colspan="4">How generated fast paths (parsers and validators alike) prove a closed object — additionalProperties: false, or a stripUnknown build — carries no undeclared key. 'count-keys' compares Object.keys(obj).length and is the faster form on JavaScriptCore (Bun), where a for…in over a non-extensible object takes the engine's slow path and halves strict-parse throughput. 'count-enumerable' counts with for…in and allocates nothing; it was the faster form on Node 22, but on Node 26 'count-keys' ties or wins there too. Keep the default unless you are pinned to an older V8 and have measured your own shapes; the generated code never detects its runtime.<br><strong>Allowed:</strong> <code>"count-enumerable"</code>, <code>"count-keys"</code></td>
+</tr>
+<tr>
 <td>🧰 <code>helpers</code></td>
 <td><code>--helpers &lt;mode&gt;</code></td>
 <td><code>string</code></td>
@@ -510,7 +538,7 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td align="center"></td>
 </tr>
 <tr>
-<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, input, export, outDir, outFile, typesOnly, validators, examples, build, force, logWarnings, strict, stripUnknown, caseInsensitive, readonly, helpers, typeSuffix, banner, importExt, rootType, resolveRemote, allowedHosts, allowPrivateHosts, allowedRoots) and are validated: an unknown key or a wrong value type fails the run instead of being ignored. CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
+<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, input, export, outDir, outFile, typesOnly, validators, examples, build, force, logWarnings, strict, stripUnknown, caseInsensitive, readonly, unknownKeys, helpers, typeSuffix, banner, importExt, rootType, resolveRemote, allowedHosts, allowPrivateHosts, allowedRoots) and are validated: an unknown key or a wrong value type fails the run instead of being ignored. CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
 </tr>
 </tbody>
 </table>
@@ -559,6 +587,16 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 }
 ```
 
+**Strict — throw on invalid input**
+
+```json
+{
+  "schema": "./schema.json",
+  "outDir": "./generated",
+  "strict": true
+}
+```
+
 ---
 
 ## Scripts

package/dist/cli-config.d.ts

@@ -1,4 +1,5 @@
 import type { SourceFormat } from '@amritk/adapters/source-format';
+import type { UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
 /**
  * Configuration for the CLI tool.
  * These properties map 1:1 with CLI flags and config file keys.
@@ -59,6 +60,25 @@ export type CliConfig = {
      * `fast-check`, which consumers must install as a (dev) dependency.
      */
     readonly examples?: boolean;
+    /**
+     * When true, also emit a `@amritk/api` channel contract per AsyncAPI channel
+     * into a `contracts/` subdirectory: one `defineMessages({ ... })` module
+     * naming every message that channel carries, keyed by its wire discriminator
+     * value, plus a barrel. Requires `input: 'asyncapi'` — the contracts are
+     * projected from the document's channels and operations, which no other input
+     * format has. Incompatible with `typesOnly`: a contract is a runtime value.
+     *
+     * The generated modules import `@amritk/api`, which the *consuming* project
+     * must have installed; it is not a dependency of the generated parsers.
+     */
+    readonly messageContracts?: boolean;
+    /**
+     * Property name that says which message a frame is, for the contracts
+     * `messageContracts` emits. Defaults to `'type'`, matching `@amritk/api`.
+     * A channel that declares its own via `x-mjst: { discriminator }` keeps it —
+     * one flag covers a whole run, and a run may span channels that disagree.
+     */
+    readonly discriminator?: string;
     /**
      * When true, compile the generated TypeScript files to .js and .d.ts output.
      * The .ts source files are removed after compilation.
@@ -105,6 +125,14 @@ export type CliConfig = {
      * path is unaffected.
      */
     readonly caseInsensitive?: boolean;
+    /**
+     * How generated fast paths prove a closed object (`additionalProperties:
+     * false`) carries no undeclared key. `'count-keys'` (the default) compares
+     * `Object.keys(obj).length` and is the faster form on JavaScriptCore (Bun);
+     * `'count-enumerable'` counts with `for…in` and is the faster form on V8
+     * (Node). Applies to parsers and validators alike.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
     /**
      * Controls how generated parsers reference their runtime helpers.
      * - `'package'`: emit `import ... from '@amritk/helpers/...'`.

package/dist/cli.js

@@ -3,6 +3,7 @@ import { execFile } from "node:child_process";
 import { readdir, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
+import { extractAsyncApi, listMessageSchemas } from "@amritk/asyncapi";
 import { buildSchema } from "@amritk/generate-parsers";
 import { buildValidatorSchema } from "@amritk/generate-validators";
 import { deriveRootTypeName } from "@amritk/helpers/derive-root-type-name";
@@ -11,8 +12,11 @@ import { combineGeneratedFiles } from "./combine-files.js";
 import { createOutputWriter } from "./create-output-writer.js";
 import { detectHelpersMode } from "./detect-helpers-mode.js";
 import { emitExamples } from "./emit-examples.js";
+import { CONTRACTS_DIR, CONTRACTS_PEER, emitMessageContracts } from "./emit-message-contracts.js";
 import { ensureOutputDir } from "./ensure-output-dir.js";
 import { HELP_TEXT } from "./help-text.js";
+import { isDependencyDeclared } from "./is-dependency-declared.js";
+import { loadAsyncApiDocument } from "./load-asyncapi-document.js";
 import { loadConfig } from "./load-config.js";
 import { loadSchema } from "./load-schema.js";
 import { parseCliArgs } from "./parse-cli-args.js";
@@ -20,6 +24,7 @@ import { parseMetaRequest } from "./parse-meta-request.js";
 import { readVersion } from "./read-version.js";
 import { resolveImportExt } from "./resolve-import-ext.js";
 const ROOT_TYPE_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const DISCRIMINATOR_PATTERN = /^[A-Za-z_$][\w$-]*$/;
 const schemaBaseName = (schemaPath) => basename(schemaPath).replace(/\.[^.]+$/, "");
 const resolveHelpersMode = (config, outputDir) => {
   const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
@@ -134,7 +139,7 @@ const findJsonSchemas = async (dir) => {
   return results;
 };
 const runValidators = async (config, schema, rootTypeName, writer, validatorsSubDir) => {
-  const files = await buildValidatorSchema(schema, rootTypeName, config.typeSuffix);
+  const files = await buildValidatorSchema(schema, rootTypeName, config.typeSuffix, void 0, config.unknownKeys);
   const staged = [];
   for (const file of files) {
     const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
@@ -150,7 +155,7 @@ const runSingle = async (config, schemaPath, outputDir) => {
   const helpersMode = resolveHelpersMode(config, outputDir);
   const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
   console.log(`Root type: ${rootTypeName}`);
-  const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
+  const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive, void 0, config.unknownKeys);
   const writer = await createOutputWriter(outputDir, config.force);
   const written = await commitOrDiscard(writer, async () => {
     for (const file of files) {
@@ -179,7 +184,7 @@ const runSingleFile = async (config, schemaPath, outFilePath) => {
   await ensureOutputDir(outputDir);
   const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
   console.log(`Root type: ${rootTypeName}`);
-  const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, config.helpers ?? "package", void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
+  const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, config.helpers ?? "package", void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive, void 0, config.unknownKeys);
   const combined = combineGeneratedFiles(files);
   const writer = await createOutputWriter(outputDir, config.force);
   const written = await commitOrDiscard(writer, async () => {
@@ -221,7 +226,7 @@ const runRecursive = async (config, schemaDir, outputDir) => {
       const rootTypeName = deriveRootTypeName(schema, schemaBaseName(schemaFile));
       console.log(`
 ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
-      const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
+      const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive, void 0, config.unknownKeys);
       for (const file of files) {
         if (file.filename.startsWith("_helpers/")) {
           sharedHelpers.set(file.filename, file.content);
@@ -253,6 +258,96 @@ ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
 Total files generated: ${writtenTsFiles.length}`);
   }
 };
+const reportContractsPeer = (outputDir) => {
+  if (isDependencyDeclared(outputDir, CONTRACTS_PEER))
+    return;
+  console.log(`Tip: the generated contracts import ${CONTRACTS_PEER}, which is not a declared dependency of the project at ${outputDir}. Install it there (it is a peer of the generated code, not of the mjst CLI).`);
+};
+const runAsyncApi = async (config, documentPath, outputDir) => {
+  const document = await loadAsyncApiDocument(config, documentPath);
+  const model = extractAsyncApi(document);
+  const schemas = listMessageSchemas(model);
+  for (const issue of model.issues) {
+    console.warn(`Warning: ${issue.path}: ${issue.message}`);
+  }
+  const contractsPossible = config.messageContracts === true && model.channels.some((c) => c.messages.length > 0);
+  if (schemas.length === 0 && !contractsPossible) {
+    console.error(`Error: no generatable message schemas found in ${documentPath}. Every message either declares no payload/headers or uses a non-JSON-Schema schemaFormat (see warnings above).`);
+    process.exit(1);
+  }
+  console.log(`AsyncAPI ${model.version}: ${model.channels.length} channel(s), ${schemas.length} schema(s) to generate`);
+  await ensureOutputDir(outputDir);
+  const helpersMode = resolveHelpersMode(config, outputDir);
+  const sharedHelpers = /* @__PURE__ */ new Map();
+  const writer = await createOutputWriter(outputDir, config.force);
+  const exampleTasks = [];
+  const contractIssues = [];
+  let contractMessageCount = 0;
+  let contractChannelCount = 0;
+  const stageAll = async () => {
+    for (const extracted of schemas) {
+      const { subDir, rootTypeName, schema } = extracted;
+      const depth = subDir.split("/").filter(Boolean).length;
+      const helpersImportPrefix = "../".repeat(depth);
+      console.log(`
+${subDir}/ (root type: ${rootTypeName})`);
+      const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
+      for (const file of files) {
+        if (file.filename.startsWith("_helpers/")) {
+          sharedHelpers.set(file.filename, file.content);
+          continue;
+        }
+        const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
+        await writer.stage(join(subDir, file.filename), content);
+      }
+      if (config.validators) {
+        await runValidators(config, schema, rootTypeName, writer, join("validators", subDir));
+      }
+      if (config.examples)
+        exampleTasks.push({ schema, rootTypeName, subDir });
+    }
+    for (const [filename, content] of sharedHelpers) {
+      await writer.stage(filename, content);
+    }
+    if (config.messageContracts) {
+      const contracts = await emitMessageContracts({
+        model,
+        writer,
+        bannerPrefix: config.banner ? resolveBanner(config.banner) : "",
+        ...config.discriminator !== void 0 ? { discriminator: config.discriminator } : {}
+      });
+      contractIssues.push(...contracts.issues);
+      contractMessageCount = contracts.messageCount;
+      contractChannelCount = contracts.channelCount;
+    }
+  };
+  const writtenTsFiles = await commitOrDiscard(writer, stageAll);
+  for (const filename of writtenTsFiles)
+    console.log(`Generated: ${filename}`);
+  if (config.messageContracts) {
+    for (const issue of contractIssues) {
+      console.warn(`Warning: ${issue.path}: ${issue.message}`);
+    }
+  }
+  if (writtenTsFiles.length === 0) {
+    console.error(`Error: nothing was generated from ${documentPath}. No message declares a payload the generators can use, and no channel projected onto a contract (see the warnings above).`);
+    process.exit(1);
+  }
+  if (config.messageContracts) {
+    console.log(`
+Message contracts: ${contractMessageCount} message(s) across ${contractChannelCount} channel(s)`);
+    reportContractsPeer(outputDir);
+  }
+  if (exampleTasks.length > 0) {
+    await runExamples(config, outputDir, exampleTasks);
+  }
+  if (config.build) {
+    await buildOutput(outputDir, writtenTsFiles.filter((file) => !file.startsWith(`${CONTRACTS_DIR}/`)), config.typesOnly);
+  } else {
+    console.log(`
+Total files generated: ${writtenTsFiles.length}`);
+  }
+};
 const run = async () => {
   const args = process.argv.slice(2);
   if (args[0] === "lint") {
@@ -310,6 +405,41 @@ const run = async () => {
     console.error("Error: --validators cannot be combined with --out-file. Use --out-dir to emit validator files.");
     process.exit(1);
   }
+  if (config.input === "asyncapi") {
+    if (config.schemaDir) {
+      console.error("Error: --input asyncapi reads a single document via --schema; it cannot be combined with --schema-dir.");
+      process.exit(1);
+    }
+    if (config.outFile) {
+      console.error("Error: --input asyncapi generates a directory of files per message; use --out-dir, not --out-file.");
+      process.exit(1);
+    }
+    if (config.rootType) {
+      console.error("Error: --root-type cannot be combined with --input asyncapi; each message derives its own root type.");
+      process.exit(1);
+    }
+    if (config.export) {
+      console.error("Error: --export applies to module inputs (typebox, zod, ...); an AsyncAPI document has no exports.");
+      process.exit(1);
+    }
+  } else if (config.messageContracts) {
+    console.error("Error: --message-contracts requires --input asyncapi; there are no channels to project otherwise.");
+    process.exit(1);
+  }
+  if (config.messageContracts && config.typesOnly) {
+    console.error("Error: --message-contracts cannot be combined with --types-only, which emits no runtime code.");
+    process.exit(1);
+  }
+  if (config.discriminator !== void 0) {
+    if (!config.messageContracts) {
+      console.error("Error: --discriminator only applies to --message-contracts. Add --message-contracts, or drop it.");
+      process.exit(1);
+    }
+    if (!DISCRIMINATOR_PATTERN.test(config.discriminator)) {
+      console.error(`Error: invalid --discriminator "${config.discriminator}". Expected a property name of letters, digits, _, $ or -, not starting with a digit.`);
+      process.exit(1);
+    }
+  }
   if (config.outFile) {
     if (!config.typesOnly) {
       console.error("Error: --out-file currently supports only --types-only output. Add --types-only or use --out-dir.");
@@ -331,6 +461,14 @@ const run = async () => {
     process.exit(1);
   }
   const outputDir = resolve(config.outDir);
+  if (config.input === "asyncapi") {
+    if (!config.schema) {
+      console.error("Error: --schema is required. Provide a path to an AsyncAPI document (JSON or YAML).");
+      process.exit(1);
+    }
+    await runAsyncApi(config, resolve(config.schema), outputDir);
+    return;
+  }
   if (config.schemaDir) {
     await runRecursive(config, resolve(config.schemaDir), outputDir);
     return;

package/dist/detect-helpers-mode.d.ts

@@ -3,13 +3,8 @@
  * package (`'package'`) or ship the helper sources alongside them (`'embedded'`).
  *
  * We select `'package'` only when `@amritk/helpers` is a *declared* dependency
- * (dependencies / devDependencies / peer / optional) of the target project's
- * nearest `package.json` above `outputDir`. Merely being *resolvable* is not
- * enough: under npm/bun's hoisted layouts `@amritk/helpers` can sit in
- * `node_modules` purely as a transitive dependency of `@amritk/mjst`, which
- * makes `import '@amritk/helpers/...'` work locally but break under
- * pnpm/isolated installs where undeclared packages are not reachable. Requiring
- * a declaration keeps auto-detected `'package'` output portable across install
- * layouts; everything else falls back to the self-contained `'embedded'` mode.
+ * of the target project's nearest `package.json` above `outputDir` — see
+ * {@link isDependencyDeclared} for why merely being resolvable is not enough.
+ * Everything else falls back to the self-contained `'embedded'` mode.
  */
 export declare const detectHelpersMode: (outputDir: string) => 'package' | 'embedded';

package/dist/detect-helpers-mode.js

@@ -1,32 +1,5 @@
-import { readFileSync } from "node:fs";
-import { dirname, join, parse as parsePath, resolve } from "node:path";
-const readDeclaredDeps = (packageJsonPath) => {
-  try {
-    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-    return /* @__PURE__ */ new Set([
-      ...Object.keys(pkg.dependencies ?? {}),
-      ...Object.keys(pkg.devDependencies ?? {}),
-      ...Object.keys(pkg.peerDependencies ?? {}),
-      ...Object.keys(pkg.optionalDependencies ?? {})
-    ]);
-  } catch {
-    return void 0;
-  }
-};
-const detectHelpersMode = (outputDir) => {
-  let dir = resolve(outputDir);
-  const { root } = parsePath(dir);
-  while (true) {
-    const declared = readDeclaredDeps(join(dir, "package.json"));
-    if (declared) {
-      return declared.has("@amritk/helpers") ? "package" : "embedded";
-    }
-    if (dir === root)
-      break;
-    dir = dirname(dir);
-  }
-  return "embedded";
-};
+import { isDependencyDeclared } from "./is-dependency-declared.js";
+const detectHelpersMode = (outputDir) => isDependencyDeclared(outputDir, "@amritk/helpers") ? "package" : "embedded";
 export {
   detectHelpersMode
 };

package/dist/emit-message-contracts.d.ts

@@ -0,0 +1,47 @@
+import type { AsyncApiModel, ExtractionIssue } from '@amritk/asyncapi';
+import type { OutputWriter } from './create-output-writer.js';
+/** Subdirectory of the output root the contract modules land in. */
+export declare const CONTRACTS_DIR = "contracts";
+/** The package the generated modules import `defineMessages` from. */
+export declare const CONTRACTS_PEER = "@amritk/api";
+export type EmitMessageContractsOptions = {
+    readonly model: AsyncApiModel;
+    readonly writer: OutputWriter;
+    /** Fallback discriminator for channels that do not declare one (`--discriminator`). */
+    readonly discriminator?: string;
+    /** Header comment prepended to each file, when `--banner` asked for one. */
+    readonly bannerPrefix?: string;
+};
+export type EmitMessageContractsResult = {
+    /** Paths staged on the writer, relative to its root, in the order they were staged. */
+    readonly files: readonly string[];
+    /** Everything a channel could not project, for the caller to warn about. */
+    readonly issues: readonly ExtractionIssue[];
+    /** How many messages made it into a contract, across every channel. */
+    readonly messageCount: number;
+    /** How many channels got a contract module (the barrel is not one of them). */
+    readonly channelCount: number;
+};
+/**
+ * Projects every channel of an AsyncAPI document onto a `defineMessages`
+ * contract and stages one module per channel under `contracts/`, plus a barrel.
+ *
+ * These are *runtime values*, not types — which is why the flag that asks for
+ * them refuses `--types-only`, and why the generated files import
+ * `@amritk/api`. That import is the consumer's dependency to satisfy: the CLI
+ * needs the package to have been written, not to be installed where the output
+ * lands, and pinning it as a hard dependency of generated code would drag a
+ * server framework into projects that only wanted the schemas.
+ *
+ * A channel that projects to nothing (every message skipped, or a channel with
+ * no messages at all) is not written: an exported contract with no messages
+ * accepts no frame in either direction, which is a trap rather than a document.
+ * The reasons come back in {@link EmitMessageContractsResult.issues}.
+ *
+ * The barrel's specifiers are always `.ts`, ignoring `--import-ext`: these
+ * modules are the one part of the output `--build` leaves uncompiled (they
+ * import the `@amritk/api` peer, and handing tsc an import the output's project
+ * has not installed would fail the parsers' compilation too). A `.js` specifier
+ * would then name a file this run never wrote.
+ */
+export declare const emitMessageContracts: (options: EmitMessageContractsOptions) => Promise<EmitMessageContractsResult>;

package/dist/emit-message-contracts.js

@@ -0,0 +1,97 @@
+import { buildChannelContract, sanitizeToken } from "@amritk/asyncapi";
+const CONTRACTS_DIR = "contracts";
+const CONTRACTS_PEER = "@amritk/api";
+const renderDirection = (name, direction, indent) => {
+  const entries = Object.entries(direction).map(([messageName, schema]) => {
+    const literal = JSON.stringify(schema, null, 2).replaceAll("\n", `
+${indent}  `);
+    return `${indent}  ${JSON.stringify(messageName)}: ${literal} as const,`;
+  });
+  return `${indent}${name}: {
+${entries.join("\n")}
+${indent}},`;
+};
+const renderChannelModule = (contract, channel) => {
+  const directions = [
+    Object.keys(contract.clientToServer).length > 0 ? renderDirection("clientToServer", contract.clientToServer, "  ") : void 0,
+    Object.keys(contract.serverToClient).length > 0 ? renderDirection("serverToClient", contract.serverToClient, "  ") : void 0
+  ].filter((entry) => entry !== void 0);
+  const address = channel.address !== void 0 && channel.address !== channel.key ? ` (${channel.address})` : "";
+  return [
+    "/**",
+    ` * Message contract for the AsyncAPI channel \`${channel.key}\`${address}.`,
+    " *",
+    ` * Requires \`${CONTRACTS_PEER}\` at runtime \u2014 it is a peer dependency of this`,
+    " * generated code, not of the mjst CLI that wrote it. Install it in the project",
+    " * that imports this file.",
+    " *",
+    " * Message keys are the wire discriminator values: a frame",
+    ` * \`{ "${contract.discriminator}": "<key>", ... }\` selects its schema by that key, and the`,
+    " * tag is removed before the payload below is validated \u2014 which is why no",
+    " * payload here declares it.",
+    " */",
+    `import { defineMessages } from '${CONTRACTS_PEER}'`,
+    "",
+    `export const ${contract.exportName} = defineMessages({`,
+    `  discriminator: '${contract.discriminator}',`,
+    ...directions,
+    "})",
+    ""
+  ].join("\n");
+};
+const emitMessageContracts = async (options) => {
+  const { model, writer, bannerPrefix = "" } = options;
+  const issues = [];
+  const files = [];
+  const barrel = [];
+  const takenTokens = /* @__PURE__ */ new Set();
+  const takenExports = /* @__PURE__ */ new Set();
+  let messageCount = 0;
+  for (const channel of model.channels) {
+    const contract = buildChannelContract(channel, {
+      ...options.discriminator !== void 0 ? { discriminator: options.discriminator } : {}
+    });
+    issues.push(...contract.issues);
+    const count = Object.keys(contract.clientToServer).length + Object.keys(contract.serverToClient).length;
+    if (count === 0) {
+      issues.push({
+        path: `#/channels/${channel.key}`,
+        message: "no message projected onto a contract; no contract module written for this channel"
+      });
+      continue;
+    }
+    messageCount += count;
+    const token = claim(sanitizeToken(channel.key, "channel"), takenTokens, "-");
+    const exportName = claim(contract.exportName, takenExports, "");
+    if (exportName !== contract.exportName) {
+      issues.push({
+        path: `#/channels/${channel.key}`,
+        message: `contract export name "${contract.exportName}" already claimed; using "${exportName}"`
+      });
+    }
+    const filename = `${CONTRACTS_DIR}/${token}.ts`;
+    await writer.stage(filename, bannerPrefix + renderChannelModule({ ...contract, exportName }, channel));
+    files.push(filename);
+    barrel.push(`export { ${exportName} } from './${token}.ts'`);
+  }
+  if (barrel.length > 0) {
+    const filename = `${CONTRACTS_DIR}/index.ts`;
+    await writer.stage(filename, `${bannerPrefix + barrel.join("\n")}
+`);
+    files.push(filename);
+  }
+  return { files, issues, messageCount, channelCount: barrel.length };
+};
+const claim = (base, taken, separator) => {
+  let candidate = base;
+  for (let n = 2; taken.has(candidate); n++) {
+    candidate = `${base}${separator}${n}`;
+  }
+  taken.add(candidate);
+  return candidate;
+};
+export {
+  CONTRACTS_DIR,
+  CONTRACTS_PEER,
+  emitMessageContracts
+};

package/dist/help-text.d.ts

@@ -4,4 +4,4 @@
  * documents these flags (config.schema.json) is not shipped in the published
  * package; the help-text test cross-checks that every flag is listed.
  */
-export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               Overwrite pre-existing files in the output destination\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,\n                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)\n  --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               Overwrite pre-existing files in the output destination\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n  --unknown-keys <s>    How closed objects are proven free of undeclared keys:\n                        count-keys (default, fastest on Bun) or count-enumerable (fastest on Node)\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";

package/dist/help-text.js

@@ -12,7 +12,8 @@ Subcommands (each with its own flags and --help):
 Input:
   --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set
   --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)
-  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro
+  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,
+                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)
   --export <name>       Which export of the schema module to use when --input names a module format
 
 Output:
@@ -21,6 +22,8 @@ Output:
   --types-only          Generate type definitions only, without parser functions
   --validators          Also emit validateX/isX validators into a validators/ subdir
   --examples            Also emit fast-check arbitraries + example values under examples/
+  --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)
+  --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)
   --build               Compile the generated files to .js/.d.ts (implies --import-ext js)
   --force               Overwrite pre-existing files in the output destination
   --import-ext <ext>    Extension on generated relative imports: ts (default) or js
@@ -35,6 +38,8 @@ Validation:
   --strip-unknown       Silently drop undeclared input keys at every nesting level
   --case-insensitive    Normalize mis-cased enum/const strings to their exact casing
   --log-warnings        console.warn on input keys not declared in the schema
+  --unknown-keys <s>    How closed objects are proven free of undeclared keys:
+                        count-keys (default, fastest on Bun) or count-enumerable (fastest on Node)
 
 Reference resolution:
   --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)

package/dist/is-dependency-declared.d.ts

@@ -0,0 +1,17 @@
+/**
+ * True when `packageName` is a *declared* dependency (dependencies /
+ * devDependencies / peer / optional) of the nearest readable `package.json` at
+ * or above `fromDir`.
+ *
+ * Declared, not merely resolvable: under npm/bun's hoisted layouts a package can
+ * sit in `node_modules` purely as a transitive dependency of `@amritk/mjst`,
+ * which makes importing it work locally but break under pnpm/isolated installs
+ * where undeclared packages are not reachable. Generated code has to survive
+ * both, so the question worth asking is whether the *project* asked for the
+ * package, not whether this machine happens to have it.
+ *
+ * Only the nearest package.json is consulted. A workspace root above it may well
+ * declare the package, but a nested package that does not declare it cannot rely
+ * on the hoist — which is exactly the case this is meant to catch.
+ */
+export declare const isDependencyDeclared: (fromDir: string, packageName: string) => boolean;

package/dist/is-dependency-declared.js

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { dirname, join, parse as parsePath, resolve } from "node:path";
+const readDeclaredDeps = (packageJsonPath) => {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return /* @__PURE__ */ new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+      ...Object.keys(pkg.peerDependencies ?? {}),
+      ...Object.keys(pkg.optionalDependencies ?? {})
+    ]);
+  } catch {
+    return void 0;
+  }
+};
+const isDependencyDeclared = (fromDir, packageName) => {
+  let dir = resolve(fromDir);
+  const { root } = parsePath(dir);
+  while (true) {
+    const declared = readDeclaredDeps(join(dir, "package.json"));
+    if (declared)
+      return declared.has(packageName);
+    if (dir === root)
+      break;
+    dir = dirname(dir);
+  }
+  return false;
+};
+export {
+  isDependencyDeclared
+};

package/dist/lint/run.js

@@ -13,6 +13,16 @@ const SEVERITY_BY_NAME = {
   hint: DiagnosticSeverity.Hint
 };
 const SEVERITY_LABEL = ["error", "warning", "info", "hint"];
+const buildAsyncApiPreset = async () => (await import("@amritk/lint/rules/asyncapi")).createAsyncApiRuleset();
+const buildOpenApiPreset = async () => (await import("@amritk/lint/rules/openapi")).createOpenApiRuleset();
+const PRESET_RULESETS = /* @__PURE__ */ new Map([
+  ["asyncapi", buildAsyncApiPreset],
+  ["loupe:asyncapi", buildAsyncApiPreset],
+  ["spectral:asyncapi", buildAsyncApiPreset],
+  ["oas", buildOpenApiPreset],
+  ["loupe:oas", buildOpenApiPreset],
+  ["spectral:oas", buildOpenApiPreset]
+]);
 const formatReport = (findings) => {
   if (findings.length === 0)
     return "No problems found\n";
@@ -51,7 +61,11 @@ const parseArgs = async (argv) => {
   try {
     const parsed = await yargs(argv).scriptName("lint").parserConfiguration({ "greedy-arrays": false }).strict().exitProcess(false).fail((message, error) => {
       throw error ?? new Error(message);
-    }).usage("$0 [documents..]", "Lint JSON/YAML documents against a ruleset").positional("documents", { describe: "Documents or globs to lint", type: "string", array: true }).option("ruleset", { alias: "r", type: "string", describe: "Path to a ruleset file" }).option("encoding", { type: "string", default: "utf8", describe: "Input encoding" }).option("fail-severity", { alias: "F", type: "string", default: "error", choices: Object.keys(SEVERITY_BY_NAME) }).option("display-only-failures", { alias: "D", type: "boolean", default: false }).option("verbose", { type: "boolean", default: false }).option("quiet", { alias: "q", type: "boolean", default: false }).option("stdin-filepath", {
+    }).usage("$0 [documents..]", "Lint JSON/YAML documents against a ruleset").positional("documents", { describe: "Documents or globs to lint", type: "string", array: true }).option("ruleset", {
+      alias: "r",
+      type: "string",
+      describe: "Path to a ruleset file, or a built-in preset: asyncapi, oas"
+    }).option("encoding", { type: "string", default: "utf8", describe: "Input encoding" }).option("fail-severity", { alias: "F", type: "string", default: "error", choices: Object.keys(SEVERITY_BY_NAME) }).option("display-only-failures", { alias: "D", type: "boolean", default: false }).option("verbose", { type: "boolean", default: false }).option("quiet", { alias: "q", type: "boolean", default: false }).option("stdin-filepath", {
       type: "string",
       describe: "Path to associate with stdin input (labels findings and enables ruleset discovery)"
     }).option("concurrency", {
@@ -127,9 +141,15 @@ Run \`mjst lint --help\` for the supported flags.
   let rulesetDefinition;
   let rulesetBasePath;
   if (parsed.ruleset) {
-    rulesetDefinition = await loadRuleset(parsed.ruleset);
-    rulesetBasePath = dirname(isAbsolute(parsed.ruleset) ? parsed.ruleset : resolve(process.cwd(), parsed.ruleset));
-    reportRulesetProblems(rulesetDefinition, parsed.ruleset);
+    const preset = PRESET_RULESETS.get(parsed.ruleset);
+    if (preset) {
+      rulesetDefinition = await preset();
+    } else {
+      const definition = await loadRuleset(parsed.ruleset);
+      rulesetDefinition = definition;
+      rulesetBasePath = dirname(isAbsolute(parsed.ruleset) ? parsed.ruleset : resolve(process.cwd(), parsed.ruleset));
+      reportRulesetProblems(definition, parsed.ruleset);
+    }
   }
   const documents = parsed.documents ?? [];
   const targets = await fg(documents, { dot: true, onlyFiles: true });

package/dist/load-asyncapi-document.d.ts

@@ -0,0 +1,12 @@
+import type { CliConfig } from './cli-config.js';
+/**
+ * Reads and parses an AsyncAPI document (JSON or YAML) off disk. When the
+ * document carries cross-file or remote `$ref`s, the whole document is
+ * dereferenced with `@amritk/resolve-refs` under the same policy flags as JSON
+ * Schema input — offline by default, SSRF-guarded, confined to the document's
+ * directory. A document with only same-document `#/...` references (the common
+ * case) skips that pass entirely: the extractor follows them itself, and keeps
+ * `#/components/schemas/...` pointers *as names* so the generators emit one
+ * type per component instead of an inlined blob.
+ */
+export declare const loadAsyncApiDocument: (config: Partial<CliConfig>, documentPath: string) => Promise<unknown>;

package/dist/load-asyncapi-document.js

@@ -0,0 +1,91 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { assignKey } from "@amritk/helpers/assign-key";
+import { readKey } from "@amritk/helpers/read-key";
+import { resolveRefsFromFile } from "@amritk/resolve-refs";
+import { parseDocument } from "@amritk/yaml";
+import { hasExternalRefs } from "./has-external-refs.js";
+import { buildResolveOptions, formatResolveErrors } from "./resolve-policy.js";
+const parseDocumentText = (content, location) => {
+  const text = content.charCodeAt(0) === 65279 ? content.slice(1) : content;
+  if (/\.json$/i.test(location))
+    return JSON.parse(text);
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0) {
+    const details = doc.errors.slice(0, 5).map((error) => `  - ${error.message}`).join("\n");
+    throw new Error(`Failed to parse ${location} as YAML:
+${details}`);
+  }
+  if (doc.warnings.some((warning) => warning.code === "MULTIPLE_DOCUMENTS")) {
+    throw new Error(`${location} contains multiple YAML documents; an AsyncAPI document must be a single-document file.`);
+  }
+  return doc.toJS();
+};
+const nodeAt = (root, pointer) => {
+  let node = root;
+  for (const segment of pointer) {
+    if (Array.isArray(node)) {
+      node = node[typeof segment === "number" ? segment : Number(segment)];
+    } else if (typeof node === "object" && node !== null) {
+      node = readKey(node, String(segment));
+    } else {
+      return void 0;
+    }
+  }
+  return node;
+};
+const canonicalizeAliases = (resolved, origins, rootLocation) => {
+  const canonical = /* @__PURE__ */ new Map();
+  for (const [copy, origin] of origins) {
+    if (origin.location !== rootLocation)
+      continue;
+    const target = nodeAt(resolved, origin.pointer);
+    if (typeof target === "object" && target !== null && target !== copy)
+      canonical.set(copy, target);
+  }
+  if (canonical.size === 0)
+    return;
+  const seen = /* @__PURE__ */ new Set();
+  const rewrite = (node) => {
+    if (typeof node !== "object" || node === null || seen.has(node))
+      return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (let index = 0; index < node.length; index++) {
+        const value = node[index];
+        const replacement = typeof value === "object" && value !== null ? canonical.get(value) : void 0;
+        if (replacement !== void 0)
+          node[index] = replacement;
+        else
+          rewrite(value);
+      }
+      return;
+    }
+    for (const [key, value] of Object.entries(node)) {
+      const replacement = typeof value === "object" && value !== null ? canonical.get(value) : void 0;
+      if (replacement !== void 0)
+        assignKey(node, key, replacement);
+      else
+        rewrite(value);
+    }
+  };
+  rewrite(resolved);
+};
+const loadAsyncApiDocument = async (config, documentPath) => {
+  const document = parseDocumentText(await readFile(documentPath, "utf-8"), documentPath);
+  if (!hasExternalRefs(document))
+    return document;
+  const { resolved, errors, origins } = await resolveRefsFromFile(documentPath, {
+    ...buildResolveOptions(config, documentPath),
+    parse: parseDocumentText,
+    trackOrigins: true
+  });
+  if (errors.length > 0)
+    throw new Error(formatResolveErrors(documentPath, errors));
+  if (origins !== void 0)
+    canonicalizeAliases(resolved, origins, resolve(documentPath));
+  return resolved;
+};
+export {
+  loadAsyncApiDocument
+};

package/dist/load-config.js

@@ -1,7 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { isUnknownKeysStrategy } from "@amritk/helpers/unknown-keys-strategy";
 import { validateConfig } from "./validate-config.js";
-const SOURCE_FORMATS = ["json", "typebox", "zod", "valibot", "effect", "avro"];
+const SOURCE_FORMATS = ["json", "typebox", "zod", "valibot", "effect", "avro", "asyncapi"];
 const isSourceFormat = (value) => typeof value === "string" && SOURCE_FORMATS.includes(value);
 const isHelpersMode = (value) => value === "package" || value === "embedded";
 const isImportExt = (value) => value === "js" || value === "ts";
@@ -29,6 +30,8 @@ const loadConfig = async (configPath) => {
     ...typeof obj["validators"] === "boolean" && { validators: obj["validators"] },
     ...typeof obj["typesOnly"] === "boolean" && { typesOnly: obj["typesOnly"] },
     ...typeof obj["examples"] === "boolean" && { examples: obj["examples"] },
+    ...typeof obj["messageContracts"] === "boolean" && { messageContracts: obj["messageContracts"] },
+    ...typeof obj["discriminator"] === "string" && { discriminator: obj["discriminator"] },
     ...typeof obj["build"] === "boolean" && { build: obj["build"] },
     ...typeof obj["force"] === "boolean" && { force: obj["force"] },
     ...typeof obj["logWarnings"] === "boolean" && { logWarnings: obj["logWarnings"] },
@@ -36,6 +39,7 @@ const loadConfig = async (configPath) => {
     ...typeof obj["stripUnknown"] === "boolean" && { stripUnknown: obj["stripUnknown"] },
     ...typeof obj["caseInsensitive"] === "boolean" && { caseInsensitive: obj["caseInsensitive"] },
     ...typeof obj["readonly"] === "boolean" && { readonly: obj["readonly"] },
+    ...isUnknownKeysStrategy(obj["unknownKeys"]) && { unknownKeys: obj["unknownKeys"] },
     ...isHelpersMode(obj["helpers"]) && { helpers: obj["helpers"] },
     ...isImportExt(obj["importExt"]) && { importExt: obj["importExt"] },
     ...typeof obj["rootType"] === "string" && { rootType: obj["rootType"] },

package/dist/load-schema.js

@@ -1,25 +1,9 @@
 import { readFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
 import { getAdapter } from "@amritk/adapters/get-adapter";
 import { resolveRefsFromFile } from "@amritk/resolve-refs";
-import { withAllowedRootsHint } from "./allowed-roots-hint.js";
 import { hasExternalRefs } from "./has-external-refs.js";
 import { loadSchemaModule } from "./load-schema-module.js";
-const buildResolveOptions = (config, schemaPath) => {
-  const remote = (config.resolveRemote ?? false) || (config.allowedHosts?.length ?? 0) > 0;
-  const extraRoots = (config.allowedRoots ?? []).map((root) => resolve(root));
-  return {
-    remote,
-    ...extraRoots.length > 0 ? { allowedRoots: [dirname(resolve(schemaPath)), ...extraRoots] } : {},
-    ...config.allowedHosts ? { allowedHosts: [...config.allowedHosts] } : {},
-    ...config.allowPrivateHosts ? { allowPrivateHosts: config.allowPrivateHosts } : {}
-  };
-};
-const formatResolveErrors = (schemaPath, errors) => {
-  const details = errors.map((error) => `  - ${withAllowedRootsHint(error.message)}`).join("\n");
-  return `Failed to resolve $refs in ${schemaPath}:
-${details}`;
-};
+import { buildResolveOptions, formatResolveErrors } from "./resolve-policy.js";
 const loadSchema = async (config, schemaPath) => {
   const inputFormat = config.input ?? "json";
   if (inputFormat === "json") {

package/dist/parse-cli-args.js

@@ -1,9 +1,11 @@
-const SOURCE_FORMATS = ["json", "typebox", "zod", "valibot", "effect", "avro"];
+import { isUnknownKeysStrategy, UNKNOWN_KEYS_STRATEGIES } from "@amritk/helpers/unknown-keys-strategy";
+const SOURCE_FORMATS = ["json", "typebox", "zod", "valibot", "effect", "avro", "asyncapi"];
 const LIST_KEYS = /* @__PURE__ */ new Set(["allowedHosts", "allowedRoots"]);
 const BOOLEAN_KEYS = /* @__PURE__ */ new Set([
   "typesOnly",
   "validators",
   "examples",
+  "messageContracts",
   "build",
   "force",
   "logWarnings",
@@ -21,10 +23,12 @@ const VALUE_KEYS = /* @__PURE__ */ new Set([
   "outFile",
   "input",
   "export",
+  "discriminator",
   "helpers",
   "typeSuffix",
   "importExt",
-  "rootType"
+  "rootType",
+  "unknownKeys"
 ]);
 const EXTERNAL_VALUE_KEYS = /* @__PURE__ */ new Set(["config"]);
 const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -72,6 +76,9 @@ const assignValue = (config, key, value) => {
     case "rootType":
       config.rootType = value;
       return true;
+    case "discriminator":
+      config.discriminator = value;
+      return true;
     case "input": {
       const parsed = parseInputValue(value);
       if (!parsed) {
@@ -96,6 +103,13 @@ const assignValue = (config, key, value) => {
       config.importExt = parsed;
       return true;
     }
+    case "unknownKeys": {
+      if (!isUnknownKeysStrategy(value)) {
+        throw new Error(`Invalid --unknown-keys value "${value}". Expected one of: ${UNKNOWN_KEYS_STRATEGIES.join(", ")}.`);
+      }
+      config.unknownKeys = value;
+      return true;
+    }
     default:
       return false;
   }
@@ -111,6 +125,9 @@ const assignBoolean = (config, key, value) => {
     case "examples":
       config.examples = value;
       return true;
+    case "messageContracts":
+      config.messageContracts = value;
+      return true;
     case "build":
       config.build = value;
       return true;

package/dist/resolve-policy.d.ts

@@ -0,0 +1,33 @@
+import type { ResolveError } from '@amritk/resolve-refs';
+import type { CliConfig } from './cli-config.js';
+/**
+ * Builds the `@amritk/resolve-refs` options from the CLI config, mirroring the
+ * safety posture of `mjst lint`: remote (`http(s)`) `$ref`s are refused unless
+ * opted into, a non-empty `allowedHosts` implies remote fetching, private/
+ * loopback hosts stay blocked as an SSRF guard unless explicitly permitted, and
+ * a local `$ref` may not leave the document's own directory unless
+ * `allowedRoots` names somewhere else.
+ *
+ * `allowedRoots` is passed only when the user asked for it, and it *adds* to the
+ * document's own directory rather than replacing it. The library option replaces
+ * the default outright, which would make `--allowed-roots ../common` quietly
+ * revoke the folder the document itself lives in — the one directory a user
+ * would never think to list. Entries are resolved against the process cwd (both
+ * from the flag and from a config file), matching how `schema` and `outDir` are
+ * treated in `cli.ts`.
+ *
+ * Shared by every document loader (plain JSON Schema, AsyncAPI) so one flag set
+ * means one policy.
+ */
+export declare const buildResolveOptions: (config: Partial<CliConfig>, documentPath: string) => {
+    remote: boolean;
+    allowedRoots?: string[];
+    allowedHosts?: string[];
+    allowPrivateHosts?: true;
+};
+/**
+ * Renders resolver failures into a single CLI error message. A confinement
+ * refusal is rewritten to name `--allowed-roots`, because the raw library text
+ * tells the user to set an option the CLI does not otherwise expose.
+ */
+export declare const formatResolveErrors: (documentPath: string, errors: readonly ResolveError[]) => string;

package/dist/resolve-policy.js

@@ -0,0 +1,21 @@
+import { dirname, resolve } from "node:path";
+import { withAllowedRootsHint } from "./allowed-roots-hint.js";
+const buildResolveOptions = (config, documentPath) => {
+  const remote = (config.resolveRemote ?? false) || (config.allowedHosts?.length ?? 0) > 0;
+  const extraRoots = (config.allowedRoots ?? []).map((root) => resolve(root));
+  return {
+    remote,
+    ...extraRoots.length > 0 ? { allowedRoots: [dirname(resolve(documentPath)), ...extraRoots] } : {},
+    ...config.allowedHosts ? { allowedHosts: [...config.allowedHosts] } : {},
+    ...config.allowPrivateHosts ? { allowPrivateHosts: config.allowPrivateHosts } : {}
+  };
+};
+const formatResolveErrors = (documentPath, errors) => {
+  const details = errors.map((error) => `  - ${withAllowedRootsHint(error.message)}`).join("\n");
+  return `Failed to resolve $refs in ${documentPath}:
+${details}`;
+};
+export {
+  buildResolveOptions,
+  formatResolveErrors
+};

package/dist/validate-config.js

@@ -1,14 +1,17 @@
 import { readKey } from "@amritk/helpers/read-key";
+import { UNKNOWN_KEYS_STRATEGIES } from "@amritk/helpers/unknown-keys-strategy";
 const CONFIG_KEYS = {
   schema: { type: "string" },
   schemaDir: { type: "string" },
-  input: { type: "string", enum: ["json", "typebox", "zod", "valibot", "effect", "avro"] },
+  input: { type: "string", enum: ["json", "typebox", "zod", "valibot", "effect", "avro", "asyncapi"] },
   export: { type: "string" },
   outDir: { type: "string" },
   outFile: { type: "string" },
   typesOnly: { type: "boolean" },
   validators: { type: "boolean" },
   examples: { type: "boolean" },
+  messageContracts: { type: "boolean" },
+  discriminator: { type: "string" },
   build: { type: "boolean" },
   force: { type: "boolean" },
   logWarnings: { type: "boolean" },
@@ -16,6 +19,7 @@ const CONFIG_KEYS = {
   stripUnknown: { type: "boolean" },
   caseInsensitive: { type: "boolean" },
   readonly: { type: "boolean" },
+  unknownKeys: { type: "string", enum: [...UNKNOWN_KEYS_STRATEGIES] },
   helpers: { type: "string", enum: ["package", "embedded"] },
   typeSuffix: { type: "string" },
   banner: { type: "boolean|string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,13 +49,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.5.2",
-    "@amritk/api": "^0.16.2",
-    "@amritk/generate-examples": "^0.8.1",
-    "@amritk/generate-parsers": "^0.20.1",
-    "@amritk/generate-validators": "^0.15.1",
-    "@amritk/helpers": "^0.18.0",
-    "@amritk/lint": "^0.5.2",
+    "@amritk/adapters": "^0.6.1",
+    "@amritk/api": "^0.16.3",
+    "@amritk/asyncapi": "^0.2.0",
+    "@amritk/generate-examples": "^0.8.3",
+    "@amritk/generate-parsers": "^0.21.1",
+    "@amritk/generate-validators": "^0.16.1",
+    "@amritk/helpers": "^0.20.0",
+    "@amritk/lint": "^0.5.3",
     "@amritk/resolve-refs": "^0.7.1",
     "@amritk/yaml": "^0.7.2",
     "fast-glob": "^3.3.2",
@@ -63,7 +64,7 @@
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@amritk/generate-markdown": "^0.5.0",
+    "@amritk/generate-markdown": "^0.6.0",
     "@types/yargs": "^17.0.33"
   }
 }