@amritk/mjst 0.17.0 → 0.18.0

package/AI.md

@@ -41,14 +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`, `--unknown-keys count-keys|count-enumerable`, `--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

@@ -361,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>

package/dist/cli-config.d.ts

@@ -60,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.

package/dist/cli.js

@@ -12,8 +12,10 @@ 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";
@@ -22,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);
@@ -255,6 +258,11 @@ ${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);
@@ -262,7 +270,8 @@ const runAsyncApi = async (config, documentPath, outputDir) => {
   for (const issue of model.issues) {
     console.warn(`Warning: ${issue.path}: ${issue.message}`);
   }
-  if (schemas.length === 0) {
+  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);
   }
@@ -272,6 +281,9 @@ const runAsyncApi = async (config, documentPath, 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;
@@ -297,15 +309,40 @@ ${subDir}/ (root type: ${rootTypeName})`);
     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, config.typesOnly);
+    await buildOutput(outputDir, writtenTsFiles.filter((file) => !file.startsWith(`${CONTRACTS_DIR}/`)), config.typesOnly);
   } else {
     console.log(`
 Total files generated: ${writtenTsFiles.length}`);
@@ -385,6 +422,23 @@ const run = async () => {
       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) {

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                        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  --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";
+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

@@ -22,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

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/load-config.js

@@ -30,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"] },

package/dist/parse-cli-args.js

@@ -5,6 +5,7 @@ const BOOLEAN_KEYS = /* @__PURE__ */ new Set([
   "typesOnly",
   "validators",
   "examples",
+  "messageContracts",
   "build",
   "force",
   "logWarnings",
@@ -22,6 +23,7 @@ const VALUE_KEYS = /* @__PURE__ */ new Set([
   "outFile",
   "input",
   "export",
+  "discriminator",
   "helpers",
   "typeSuffix",
   "importExt",
@@ -74,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) {
@@ -120,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/validate-config.js

@@ -10,6 +10,8 @@ const CONFIG_KEYS = {
   typesOnly: { type: "boolean" },
   validators: { type: "boolean" },
   examples: { type: "boolean" },
+  messageContracts: { type: "boolean" },
+  discriminator: { type: "string" },
   build: { type: "boolean" },
   force: { type: "boolean" },
   logWarnings: { type: "boolean" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,13 +49,13 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.0",
+    "@amritk/adapters": "^0.6.1",
     "@amritk/api": "^0.16.3",
-    "@amritk/asyncapi": "^0.1.0",
-    "@amritk/generate-examples": "^0.8.2",
-    "@amritk/generate-parsers": "^0.21.0",
-    "@amritk/generate-validators": "^0.16.0",
-    "@amritk/helpers": "^0.19.0",
+    "@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",