@amritk/mjst 0.16.1 → 0.17.0

package/AI.md

@@ -46,7 +46,8 @@ mjst compile-api ./routes.ts --out ./dist/handler.ts
 
 `--schema` / `--schema-dir`, `--out-dir` / `--out-file`, `--input`,
 `--validators`, `--examples`, `--types-only`, `--build`, `--strict`,
-`--strip-unknown`, `--readonly`, `--import-ext ts|js`, `--config <path>`,
+`--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>
@@ -423,6 +424,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 +520,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 +569,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.
@@ -105,6 +106,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";
@@ -13,6 +14,7 @@ import { detectHelpersMode } from "./detect-helpers-mode.js";
 import { emitExamples } from "./emit-examples.js";
 import { ensureOutputDir } from "./ensure-output-dir.js";
 import { HELP_TEXT } from "./help-text.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";
@@ -134,7 +136,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 +152,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 +181,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 +223,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 +255,62 @@ ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
 Total files generated: ${writtenTsFiles.length}`);
   }
 };
+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}`);
+  }
+  if (schemas.length === 0) {
+    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 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);
+    }
+  };
+  const writtenTsFiles = await commitOrDiscard(writer, stageAll);
+  for (const filename of writtenTsFiles)
+    console.log(`Generated: ${filename}`);
+  if (exampleTasks.length > 0) {
+    await runExamples(config, outputDir, exampleTasks);
+  }
+  if (config.build) {
+    await buildOutput(outputDir, writtenTsFiles, 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 +368,24 @@ 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);
+    }
+  }
   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 +407,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/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  --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:
@@ -35,6 +36,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/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";
@@ -36,6 +37,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,4 +1,5 @@
-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",
@@ -24,7 +25,8 @@ const VALUE_KEYS = /* @__PURE__ */ new Set([
   "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());
@@ -96,6 +98,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;
   }

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,8 +1,9 @@
 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" },
@@ -16,6 +17,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.17.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.0",
+    "@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/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"
   }
 }