@amritk/mjst 0.21.0 → 0.22.0

package/AI.md

@@ -8,7 +8,7 @@ reference is [README.md](./README.md); config options are in
 
 > Pre-alpha: generated output and flags change without notice pre-1.0. This
 > package ships **only a `mjst` binary** — there are no JS exports. For the
-> programmatic API import `@amritk/generate-parsers` etc. instead.
+> programmatic API import `@amritk/parsers` etc. instead.
 
 ## The four commands
 

package/README.md

@@ -95,19 +95,35 @@ JSON-Pointer error paths — and an `isX(input)` boolean type guard:
 npx mjst --schema ./schema.json --out-dir ./generated --validators
 ```
 
-The validators carry the same schema-derived filenames as the parsers, so they land in a
-`validators/` subdirectory to avoid colliding:
+Both halves land in one directory, over a single declaration of each type. The type and the
+validators share the file named after the schema; the parser moves next to them under a
+`.parse` suffix and imports the type from there:
 
 ```
 generated/
-  schema.ts, index.ts            ← parsers + types
-  validators/
-    schema.ts, index.ts          ← validateX / isX
-    validation-result.ts         ← ValidationResult / ValidationError contract
+  schema.ts                      ← export type X, plus isX / validateX
+  schema.parse.ts                ← parseX, importing the type from ./schema
+  validation-result.ts           ← ValidationResult / ValidationError contract
+  index.ts                       ← a barrel over all of it
 ```
 
-This works with `--schema-dir` too (the `validators/` tree mirrors the parser layout) and with
-`--build`. It cannot be combined with `--types-only` or `--out-file`, which emit no runtime code.
+So there is exactly one `export type X` in the output, and the guard, the validator and the
+parser are all talking about it.
+
+This works with `--schema-dir` and `--input asyncapi` too — each schema's own subdirectory
+carries both halves — and with `--build`. It cannot be combined with `--types-only` or
+`--out-file`, which emit no runtime code.
+
+Ask for no validators and there is nothing to collide with, so the parser keeps `schema.ts` and
+its own type, and no `validation-result.ts` is emitted at all.
+
+Three flags shape the validators, and each needs `--validators` alongside it:
+
+- `--check` adds `checkX`, the same `ValidationResult` as `validateX` but stopped at the first
+  violation, so it costs one error object rather than however many the document earns.
+- `--coerce` adds `coerceX`, which moves scalars toward the declared type and then validates.
+- `--repair` adds `repairX`, which coerces, validates, and then repairs each rejected position
+  to a value the schema supplies.
 
 ### Running the generated output
 
@@ -389,7 +405,43 @@ Under `--table` only the content between `<!-- config-table-start -->
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="4">Also emit validation functions alongside the parsers. For every generated type X the CLI writes a validateX (returning a rich ValidationResult with JSON-Pointer error paths) and an isX boolean type guard. The files land in a validators/ subdirectory of the output so they never collide with the parser files, which share the same schema-derived names. Works with both schema and schemaDir. Incompatible with typesOnly and outFile, which produce no runtime code.</td>
+<td colspan="4">Also emit validation functions alongside the parsers. For every generated type X the CLI writes a validateX (returning a rich ValidationResult with JSON-Pointer error paths) and an isX boolean type guard. They share one directory and one declaration of X with the parser: the type and the validators land in x.ts, and the parser moves to x.parse.ts beside them, importing the type from there. Works with both schema and schemaDir. Incompatible with typesOnly and outFile, which produce no runtime code.</td>
+</tr>
+<tr>
+<td>🔎 <code>check</code></td>
+<td><code>--check</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit a checkX alongside each validateX. It is the same ValidationResult, carrying the one error that stopped it: where validateX walks the whole document to collect every violation, checkX gives up at the first and costs a single error object. Reach for it when a failure has to be reported but only the first thing wrong matters — a service refusing to boot on a bad config does not need the other nine. When nothing has to be reported at all, isX is cheaper still, since it builds no error object. validateX and isX are unchanged either way. Requires validators.</td>
+</tr>
+<tr>
+<td>🧪 <code>coerce</code></td>
+<td><code>--coerce</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit a coerceX alongside each validateX. It moves scalars toward the type the schema declares and then runs the very same validateX over the result, so a config value written the YAML way reads the same whether it came from a config file or an extension. The input is never modified and nothing is substituted: a value that cannot be coerced into a valid one reaches the validator untouched, so the error names what the caller actually wrote, with the keyword and params that rejected it. The table is Ajv's coerceTypes minus the cells where Ajv guesses — no whitespace-to-zero, no hex or Infinity strings, and nothing coerced to or from null — so every value this coerces, Ajv coerces to the same value, and the rest become errors rather than silent repairs. At a union it coerces only when exactly one of the offered types can take the value, and leaves a value that is already one of them alone, so the answer does not depend on the order the union was written in. Requires validators.</td>
+</tr>
+<tr>
+<td>🔧 <code>repair</code></td>
+<td><code>--repair</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit a repairX alongside each validateX. It coerces, runs the very same validateX, and then repairs each position the validator rejected to a value the schema itself supplies — a default, a const, the first enum member, or a fallback built to satisfy that position's own bounds — re-validating until the document is accepted or nothing further can be repaired. The repairs it reports are the validator's own errors, the ones a repair was found for, so a caller logs the same path, keyword and params it would have been rejected with and the two can never drift apart. A document needing nothing comes back valid with an empty repairs list; one fully repaired comes back valid with a non-empty one, leaving the caller to decide whether that is acceptable; one that could not be fully repaired comes back invalid carrying both the repairs applied and the errors still outstanding. The input is never modified and everything the repair did not touch is shared. Implies coerce, so a value merely written in the wrong type is right before the validator sees it and never counts as a repair. Requires validators.</td>
+</tr>
+<tr>
+<td>🌿 <code>branchErrors</code></td>
+<td><code>--branch-errors</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Explain a failing anyOf/oneOf with the errors of the branch it meant, instead of the bare "must match a schema in anyOf" that names no field and no reason. The branch that rejected the value's kind is dropped first, so a string-or-object union is left with the one branch that was talking about this value; where several remain, a discriminator breaks the tie; where none stands out, nothing extra is reported. Off by default and off costs nothing — the generated code is exactly what it would be without the option. On, each branch keeps what it complained about: a push per failing branch and one lazily-created array per combinator that had one. Requires validators.</td>
 </tr>
 <tr>
 <td>🎲 <code>examples</code></td>
@@ -686,7 +738,7 @@ usage error. Run `mjst markdown --help` for details.
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="4">Also emit validation functions alongside the parsers. For every generated type X the CLI writes a validateX (returning a rich ValidationResult with JSON-Pointer error paths) and an isX boolean type guard. The files land in a validators/ subdirectory of the output so they never collide with the parser files, which share the same schema-derived names. Works with both schema and schemaDir. Incompatible with typesOnly and outFile, which produce no runtime code.</td>
+<td colspan="4">Also emit validation functions alongside the parsers. For every generated type X the CLI writes a validateX (returning a rich ValidationResult with JSON-Pointer error paths) and an isX boolean type guard. They share one directory and one declaration of X with the parser: the type and the validators land in x.ts, and the parser moves to x.parse.ts beside them, importing the type from there. Works with both schema and schemaDir. Incompatible with typesOnly and outFile, which produce no runtime code.</td>
 </tr>
 <tr>
 <td>🎲 <code>examples</code></td>

package/dist/cli-config.d.ts

@@ -45,12 +45,91 @@ export type CliConfig = {
      * When true, also emit validation functions alongside the parsers. For every
      * generated type `X` the CLI writes a `validateX` (returning a rich
      * `ValidationResult` with JSON-Pointer error paths) and an `isX` boolean type
-     * guard. The files land in a `validators/` subdirectory of the output so they
-     * never collide with the parser files, which share the same schema-derived
-     * names. Works with both `schema` and `schemaDir`. Incompatible with
-     * `typesOnly` and `outFile`, which produce no runtime code.
+     * guard.
+     *
+     * They share one directory and one declaration of `X` with the parser: the
+     * type and the validators land in `x.ts`, and the parser moves to `x.parse.ts`
+     * beside them, importing the type from there. Both halves are then talking
+     * about the same type, which two side-by-side trees could only promise.
+     *
+     * Works with both `schema` and `schemaDir`. Incompatible with `typesOnly` and
+     * `outFile`, which produce no runtime code.
      */
     readonly validators?: boolean;
+    /**
+     * When true, generated validators also get a `checkX`: the same
+     * `ValidationResult` `validateX` returns, carrying the one error that stopped
+     * it. It gives up at the first violation instead of walking on to collect the
+     * rest, so it costs a single error object where `validateX` costs however many
+     * the document earns.
+     *
+     * Reach for it when a failure has to be reported but only the first thing
+     * wrong matters — a service refusing to boot on a bad config does not need the
+     * other nine. When nothing has to be reported at all, `isX` is cheaper still:
+     * it builds no error object.
+     *
+     * Requires `validators`. `validateX` and `isX` are unchanged either way.
+     */
+    readonly check?: boolean;
+    /**
+     * When true, generated validators also get a `coerceX`: it moves scalars
+     * toward what the schema asks for and then runs the very same `validateX` over
+     * the result, so a config value written the YAML way reads the same however it
+     * arrived.
+     *
+     * The input is never modified, and nothing is ever substituted: where a value
+     * cannot be coerced into a valid one it is handed to the validator untouched,
+     * so the error names what the caller actually wrote, with the keyword and
+     * params that rejected it. That is the difference from a coercing *parser*,
+     * which repairs toward a default and leaves nothing to report.
+     *
+     * The table is Ajv's `coerceTypes` minus the cells where Ajv guesses — no
+     * whitespace-to-zero, no `0x`/`Infinity` strings, and nothing coerced to or
+     * from `null`. Every value this coerces, Ajv coerces to the same value, so
+     * moving off Ajv never changes a value; it turns some of Ajv's silent repairs
+     * into errors instead. At a union it coerces only when exactly one of the
+     * offered types can take the value, and leaves a value that is already one of
+     * them alone — so the answer does not depend on the order the union is
+     * written in, which under Ajv it does.
+     *
+     * Requires `validators`. `validateX` and `isX` are unchanged either way.
+     */
+    readonly coerce?: boolean;
+    /**
+     * When true, generated validators also get a `repairX`: it coerces, validates,
+     * and then repairs each position the validator rejected to a value the schema
+     * itself supplies — a `default`, a `const`, the first `enum` member, or a
+     * fallback built to satisfy the position's own bounds. The result carries the
+     * repaired value together with `repairs`, which *are* the errors `validateX`
+     * produced for the positions that were repaired, so a caller logs the same
+     * path, keyword and params it would have been rejected with.
+     *
+     * A document needing no repair comes back valid with an empty `repairs`; one
+     * fully repaired comes back valid with a non-empty one, leaving the caller to
+     * decide whether that is acceptable; one that could not be fully repaired
+     * comes back invalid carrying both the repairs applied and the errors still
+     * outstanding.
+     *
+     * Implies `coerce` — repairing runs after coercion, so a value merely written
+     * in the wrong type is right before the validator sees it and never counts as
+     * a repair. Requires `validators`.
+     */
+    readonly repair?: boolean;
+    /**
+     * When true, a failing `anyOf` / `oneOf` in a generated validator also reports
+     * the errors of the branch it meant, instead of the bare "must match a schema
+     * in anyOf" that names no field and no reason.
+     *
+     * Off by default, and off costs nothing — the generated code is exactly what
+     * it would be without the option. On, each branch keeps what it complained
+     * about, which is a push per *failing* branch and one lazily-created array per
+     * combinator that had one. A valid instance fails no branch and allocates
+     * nothing, but the branches are still handed a collector, so measure before
+     * turning it on in a hot path.
+     *
+     * Requires `validators`.
+     */
+    readonly branchErrors?: boolean;
     /**
      * When true, also emit test-data files for every schema: a `fast-check`
      * arbitrary (`FooArbitrary`) that produces schema-valid values and a concrete

package/dist/cli.js

@@ -4,8 +4,6 @@ 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";
 const execFileAsync = promisify(execFile);
 import { combineGeneratedFiles } from "./combine-files.js";
@@ -14,6 +12,7 @@ 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 { generateFiles } from "./generate-files.js";
 import { HELP_TEXT } from "./help-text.js";
 import { isDependencyDeclared } from "./is-dependency-declared.js";
 import { loadAsyncApiDocument } from "./load-asyncapi-document.js";
@@ -22,7 +21,6 @@ import { loadSchema } from "./load-schema.js";
 import { parseCliArgs } from "./parse-cli-args.js";
 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(/\.[^.]+$/, "");
@@ -138,24 +136,13 @@ const findJsonSchemas = async (dir) => {
   }
   return results;
 };
-const runValidators = async (config, schema, rootTypeName, writer, validatorsSubDir) => {
-  const files = await buildValidatorSchema(schema, rootTypeName, config.typeSuffix, void 0, config.unknownKeys, config.formats);
-  const staged = [];
-  for (const file of files) {
-    const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
-    const relFilename = join(validatorsSubDir, file.filename);
-    await writer.stage(relFilename, content);
-    staged.push(relFilename);
-  }
-  return staged;
-};
 const runSingle = async (config, schemaPath, outputDir) => {
   const schema = await loadSchema(config, schemaPath);
   await ensureOutputDir(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, void 0, config.unknownKeys);
+  const files = await generateFiles(config, schema, rootTypeName, { mode: helpersMode });
   const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     for (const file of files) {
@@ -163,8 +150,6 @@ const runSingle = async (config, schemaPath, outputDir) => {
       const content = config.banner && !isHelper ? resolveBanner(config.banner) + file.content : file.content;
       await writer.stage(file.filename, content);
     }
-    if (config.validators)
-      await runValidators(config, schema, rootTypeName, writer, "validators");
   });
   for (const filename of written)
     console.log(`Generated: ${filename}`);
@@ -184,7 +169,9 @@ 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, void 0, config.unknownKeys);
+  const files = await generateFiles(config, schema, rootTypeName, {
+    mode: config.helpers ?? "package"
+  });
   const combined = combineGeneratedFiles(files);
   const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
@@ -226,7 +213,10 @@ 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, void 0, config.unknownKeys);
+      const files = await generateFiles(config, schema, rootTypeName, {
+        mode: helpersMode,
+        importPrefix: helpersImportPrefix
+      });
       for (const file of files) {
         if (file.filename.startsWith("_helpers/")) {
           sharedHelpers.set(file.filename, file.content);
@@ -235,9 +225,6 @@ ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
         const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
         await writer.stage(join(relNoExt, file.filename), content);
       }
-      if (config.validators) {
-        await runValidators(config, schema, rootTypeName, writer, join("validators", relNoExt));
-      }
       if (config.examples)
         exampleTasks.push({ schema, rootTypeName, subDir: relNoExt });
     }
@@ -291,7 +278,10 @@ const runAsyncApi = async (config, documentPath, outputDir) => {
       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);
+      const files = await generateFiles(config, schema, rootTypeName, {
+        mode: helpersMode,
+        importPrefix: helpersImportPrefix
+      });
       for (const file of files) {
         if (file.filename.startsWith("_helpers/")) {
           sharedHelpers.set(file.filename, file.content);
@@ -300,9 +290,6 @@ ${subDir}/ (root type: ${rootTypeName})`);
         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 });
     }
@@ -390,13 +377,26 @@ const run = async () => {
   const fileConfig = configPath ? await loadConfig(configPath) : {};
   const cliConfig = parseCliArgs(args);
   const config = { ...fileConfig, ...cliConfig };
+  if (config.coerce && !config.validators) {
+    console.error("Error: --coerce shapes the generated validators, so it needs --validators too.");
+    process.exit(1);
+  }
+  if (config.repair && !config.validators) {
+    console.error("Error: --repair shapes the generated validators, so it needs --validators too.");
+    process.exit(1);
+  }
+  if (config.check && !config.validators) {
+    console.error("Error: --check shapes the generated validators, so it needs --validators too.");
+    process.exit(1);
+  }
+  if (config.branchErrors && !config.validators) {
+    console.error("Error: --branch-errors shapes the generated validators, so it needs --validators too.");
+    process.exit(1);
+  }
   if (config.outDir && config.outFile) {
     console.error("Error: provide only one of --out-dir or --out-file, not both.");
     process.exit(1);
   }
-  if (config.force) {
-    console.warn("Warning: --force is deprecated and does nothing; generated files always replace what is at their path.");
-  }
   if (config.rootType !== void 0 && !ROOT_TYPE_PATTERN.test(config.rootType)) {
     console.error(`Error: invalid --root-type "${config.rootType}". Expected a TypeScript identifier (letters, digits, _ or $, not starting with a digit).`);
     process.exit(1);

package/dist/combine-files.d.ts

@@ -1,4 +1,4 @@
-import type { GeneratedFile } from '@amritk/generate-parsers';
+import type { GeneratedFile } from '@amritk/parsers';
 /**
  * Merges the per-schema {@link GeneratedFile}s into a single self-contained
  * TypeScript module. Each generated file imports its sibling definitions via

package/dist/generate-files.d.ts

@@ -0,0 +1,24 @@
+import { type GeneratedFile } from '@amritk/parsers';
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { CliConfig } from './cli-config.js';
+/** Where one schema's generated files reach their runtime helpers from. */
+export type HelpersPlacement = {
+    /** The published package, or helper sources emitted into the output tree. */
+    readonly mode: 'package' | 'embedded';
+    /**
+     * Relative path from this schema's output subdirectory back to the shared
+     * `_helpers/` at the output root. The recursive flows nest a schema's files a
+     * directory or more down, so `./` is only right at the top.
+     */
+    readonly importPrefix?: string;
+};
+/**
+ * Generates one schema's files, translating the CLI's flags into the single
+ * options object `@amritk/parsers` takes.
+ *
+ * All four generation flows come through here so none of them can quietly hold a
+ * different opinion about what a flag means — which is exactly what happened
+ * while the CLI drove the two generators directly and positionally: the AsyncAPI
+ * flow passed `--unknown-keys` to the validators and forgot it for the parsers.
+ */
+export declare const generateFiles: (config: Partial<CliConfig>, schema: JSONSchema, rootTypeName: string, helpers: HelpersPlacement) => Promise<GeneratedFile[]>;

package/dist/generate-files.js

@@ -0,0 +1,24 @@
+import { generate } from "@amritk/parsers";
+import { resolveImportExt } from "./resolve-import-ext.js";
+import { resolveModes } from "./resolve-modes.js";
+const generateFiles = async (config, schema, rootTypeName, helpers) => generate(schema, rootTypeName, {
+  modes: resolveModes(config),
+  typeSuffix: config.typeSuffix ?? "",
+  branchErrors: config.branchErrors === true,
+  stripUnknown: config.stripUnknown === true,
+  readonly: config.readonly === true,
+  caseInsensitive: config.caseInsensitive === true,
+  helpersMode: helpers.mode,
+  helpersImportPrefix: helpers.importPrefix ?? "./",
+  importExt: resolveImportExt(config),
+  logWarnings: config.logWarnings === true,
+  // Spread rather than passed as `undefined`: under
+  // `exactOptionalPropertyTypes` an absent option and one set to `undefined`
+  // are different things, and only the first falls back to the generator's own
+  // default.
+  ...config.unknownKeys !== void 0 ? { unknownKeys: config.unknownKeys } : {},
+  ...config.formats !== void 0 ? { formats: config.formats } : {}
+});
+export {
+  generateFiles
+};

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  mjst markdown <schema> --out-dir <dir>  Generate markdown documentation from a JSON Schema\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               Deprecated; ignored (generated files always overwrite)\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  --formats <f>         String formats the generated validators enforce: \"all\", or a\n                        comma-separated list (e.g. uuid,date-time,email). Off by default,\n                        which leaves \"format\" an annotation as JSON Schema reads it.\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  mjst markdown <schema> --out-dir <dir>  Generate markdown documentation from a JSON Schema\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 beside the parsers, over one\n                        shared declaration of each generated type\n  --check               Also emit checkX, the same result as validateX but stopped at the\n                        first violation (requires --validators)\n  --coerce              Also emit coerceX, which coerces scalars the way Ajv's coerceTypes\n                        does and then validates (requires --validators)\n  --repair              Also emit repairX, which coerces, validates, then repairs each\n                        rejected position to a schema-supplied value and reports the\n                        errors it repaired (implies --coerce; requires --validators)\n  --branch-errors       Explain a failing anyOf/oneOf with the errors of the branch it\n                        meant (requires --validators; costs a little on unions)\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               Deprecated; ignored (generated files always overwrite)\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  --formats <f>         String formats the generated validators enforce: \"all\", or a\n                        comma-separated list (e.g. uuid,date-time,email). Off by default,\n                        which leaves \"format\" an annotation as JSON Schema reads it.\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

@@ -21,7 +21,17 @@ Output:
   --out-dir <dir>       Output directory for the generated files
   --out-file <file>     Single-file output instead of a directory (requires --types-only)
   --types-only          Generate type definitions only, without parser functions
-  --validators          Also emit validateX/isX validators into a validators/ subdir
+  --validators          Also emit validateX/isX validators beside the parsers, over one
+                        shared declaration of each generated type
+  --check               Also emit checkX, the same result as validateX but stopped at the
+                        first violation (requires --validators)
+  --coerce              Also emit coerceX, which coerces scalars the way Ajv's coerceTypes
+                        does and then validates (requires --validators)
+  --repair              Also emit repairX, which coerces, validates, then repairs each
+                        rejected position to a schema-supplied value and reports the
+                        errors it repaired (implies --coerce; requires --validators)
+  --branch-errors       Explain a failing anyOf/oneOf with the errors of the branch it
+                        meant (requires --validators; costs a little on unions)
   --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)

package/dist/load-config.js

@@ -34,6 +34,8 @@ const loadConfig = async (configPath) => {
     ...typeof obj["messageContracts"] === "boolean" && { messageContracts: obj["messageContracts"] },
     ...typeof obj["discriminator"] === "string" && { discriminator: obj["discriminator"] },
     ...typeof obj["build"] === "boolean" && { build: obj["build"] },
+    ...typeof obj["coerce"] === "boolean" && { coerce: obj["coerce"] },
+    ...typeof obj["branchErrors"] === "boolean" && { branchErrors: obj["branchErrors"] },
     ...typeof obj["force"] === "boolean" && { force: obj["force"] },
     ...typeof obj["logWarnings"] === "boolean" && { logWarnings: obj["logWarnings"] },
     ...typeof obj["strict"] === "boolean" && { strict: obj["strict"] },

package/dist/parse-cli-args.js

@@ -4,6 +4,10 @@ const LIST_KEYS = /* @__PURE__ */ new Set(["allowedHosts", "allowedRoots"]);
 const BOOLEAN_KEYS = /* @__PURE__ */ new Set([
   "typesOnly",
   "validators",
+  "check",
+  "coerce",
+  "repair",
+  "branchErrors",
   "examples",
   "messageContracts",
   "build",
@@ -127,6 +131,18 @@ const assignBoolean = (config, key, value) => {
     case "validators":
       config.validators = value;
       return true;
+    case "check":
+      config.check = value;
+      return true;
+    case "coerce":
+      config.coerce = value;
+      return true;
+    case "repair":
+      config.repair = value;
+      return true;
+    case "branchErrors":
+      config.branchErrors = value;
+      return true;
     case "examples":
       config.examples = value;
       return true;

package/dist/resolve-modes.d.ts

@@ -0,0 +1,17 @@
+import type { Mode } from '@amritk/parsers';
+import type { CliConfig } from './cli-config.js';
+/**
+ * Turns the flags a run was given into the list of entry points `generate()`
+ * should emit.
+ *
+ * The CLI predates the mode list: its flags grew one at a time, each one meaning
+ * "also emit this function", so the mapping is additive rather than a choice.
+ * Keeping it in one place means the four generation flows cannot drift on what
+ * `--strict --validators --repair` is supposed to produce.
+ *
+ * `--types-only` is the one run with nothing to execute, so it stops at `types`
+ * — asking for a parser there would emit runtime code the flag exists to avoid.
+ * Everything else always carries a parser, because emitting one is what the CLI
+ * does when you do not tell it otherwise.
+ */
+export declare const resolveModes: (config: Partial<CliConfig>) => Mode[];

package/dist/resolve-modes.js

@@ -0,0 +1,19 @@
+const resolveModes = (config) => {
+  if (config.typesOnly === true)
+    return ["types"];
+  const modes = ["types"];
+  if (config.validators === true) {
+    modes.push("guard", "validate");
+    if (config.check === true)
+      modes.push("check");
+    if (config.coerce === true)
+      modes.push("coerce");
+    if (config.repair === true)
+      modes.push("repair");
+  }
+  modes.push(config.strict === true ? "parseStrict" : "parse");
+  return modes;
+};
+export {
+  resolveModes
+};

package/dist/validate-config.js

@@ -9,6 +9,10 @@ const CONFIG_KEYS = {
   outFile: { type: "string" },
   typesOnly: { type: "boolean" },
   validators: { type: "boolean" },
+  check: { type: "boolean" },
+  coerce: { type: "boolean" },
+  repair: { type: "boolean" },
+  branchErrors: { type: "boolean" },
   examples: { type: "boolean" },
   messageContracts: { type: "boolean" },
   discriminator: { type: "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,15 +49,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.2",
-    "@amritk/api": "^0.16.4",
-    "@amritk/asyncapi": "^0.3.0",
-    "@amritk/generate-examples": "^0.8.4",
+    "@amritk/adapters": "^0.6.4",
+    "@amritk/api": "^0.16.5",
+    "@amritk/asyncapi": "^0.3.2",
+    "@amritk/generate-examples": "^0.8.6",
     "@amritk/generate-markdown": "^0.8.0",
-    "@amritk/generate-parsers": "^0.23.0",
-    "@amritk/generate-validators": "^0.17.0",
-    "@amritk/helpers": "^0.21.0",
-    "@amritk/lint": "^0.6.0",
+    "@amritk/helpers": "^0.23.0",
+    "@amritk/lint": "^0.6.1",
+    "@amritk/parsers": "^0.2.0",
     "@amritk/resolve-refs": "^0.7.1",
     "@amritk/yaml": "^0.7.2",
     "fast-glob": "^3.3.2",