@amritk/mjst 0.26.2 → 0.27.0

package/README.md

@@ -134,6 +134,16 @@ alongside it:
 
 ### Running the generated output
 
+> [!IMPORTANT]
+> **Type-checking the output as part of your own project?** Pass `--import-ext js`. The `.ts`
+> default is for running the sources directly, and without `allowImportingTsExtensions` in your
+> `tsconfig.json`, tsc rejects every one of those imports with `TS5097`. The output itself
+> compiles under `strict`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess` and
+> `noPropertyAccessFromIndexSignature`. If your project turns on something it does not satisfy,
+> `--banner "// @ts-nocheck"` writes the directive at the top of every generated file outside
+> `_helpers/` (text made only of `//` lines is emitted as written, not wrapped in a JSDoc block, which TypeScript
+> would not read a directive from).
+
 By default mjst emits relative imports with the literal `.ts` extension (e.g.
 `import { parseUser } from './user.ts'`), so the generated sources run **as-is** — no build
 step — under:
@@ -462,7 +472,7 @@ usage error. Run `mjst markdown --help` for details.
 <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, deliberately, since null usually means not set — so every scalar this coerces, Ajv coerces to the same value, and the rest become errors rather than silent repairs. Coercion reaches through $ref, allOf, if/then/else and unions. At a union a value that already matches a branch as written is left alone; otherwise each branch coerces it its own way, and the result is taken only when every branch that then accepts it agrees on it. So the answer does not depend on the order the union was written in, and a const false branch keeps false where Ajv turns it into the string false through an earlier string branch. A valid document comes back as the very same object. Where the caller cannot let Ajv mutate its input, so Ajv has to clone it first, coerceX runs 5–36× faster on valid input and 1.4–2.1× faster on input that needs coercing; where the caller lets Ajv coerce its document in place there is no clone to save, and on a large document Ajv can come out modestly ahead. Requires validators.</td>
+<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, deliberately, since null usually means not set — so every scalar this coerces, Ajv coerces to the same value, and the rest become errors rather than silent repairs. Moving off Ajv, check how your callers treat a rejected value: a caller that reads rejection as absence silently drops any block holding a null that Ajv used to coerce, so surface the errors or allow null in the schema. Coercion reaches through $ref, allOf, if/then/else and unions. At a union a value that already matches a branch as written is left alone; otherwise each branch coerces it its own way, and the result is taken only when every branch that then accepts it agrees on it. So the answer does not depend on the order the union was written in, and a const false branch keeps false where Ajv turns it into the string false through an earlier string branch. A valid document comes back as the very same object. Where the caller cannot let Ajv mutate its input, so Ajv has to clone it first, coerceX runs 5–36× faster on valid input and 1.4–2.1× faster on input that needs coercing; where the caller lets Ajv coerce its document in place there is no clone to save, and on a large document Ajv can come out modestly ahead. Requires validators.</td>
 </tr>
 <tr>
 <td>🔧 <code>repair</code></td>
@@ -480,7 +490,7 @@ usage error. Run `mjst markdown --help` for details.
 <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, a combinator that passes costs what it costs with the option off, since its branches are tested by the same functions; only an anyOf/oneOf that has already failed asks its branches again for what each one complained about, so the price is paid on invalid input alone. Requires validators.</td>
+<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 every branch rejected the value's kind, the kinds they accept are named instead ("must be object or boolean"); otherwise, 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, a combinator that passes costs what it costs with the option off, since its branches are tested by the same functions; only an anyOf/oneOf that has already failed asks its branches again for what each one complained about, so the price is paid on invalid input alone. Requires validators.</td>
 </tr>
 <tr>
 <td>🎲 <code>examples</code></td>
@@ -615,7 +625,7 @@ usage error. Run `mjst markdown --help` for details.
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="4">Prepend a comment header to every generated file (excluding _helpers/). true uses the default message ('This file was auto-generated by @amritk/mjst…'); a string uses that text as the message body, wrapped in a JSDoc block; false or omitted emits no header. On the CLI, --banner alone enables the default message and --banner &lt;text&gt; sets a custom one.</td>
+<td colspan="4">Prepend a comment header to every generated file (excluding _helpers/). true uses the default message ('This file was auto-generated by @amritk/mjst…'); a string uses that text as the message body, wrapped in a JSDoc block, unless every line of it is a // comment — then it is emitted as written, which is how to add a directive such as // @ts-nocheck that TypeScript only honors as a line comment; false or omitted emits no header. On the CLI, --banner alone enables the default message and --banner &lt;text&gt; sets a custom one.</td>
 </tr>
 <tr>
 <td>🔗 <code>importExt</code></td>

package/dist/cli.js

@@ -14,6 +14,7 @@ import { loadConfig } from "./load-config.js";
 import { parseCliArgs } from "./parse-cli-args.js";
 import { parseMetaRequest } from "./parse-meta-request.js";
 import { readVersion } from "./read-version.js";
+import { resolveBanner } from "./resolve-banner.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(/\.[^.]+$/, "");
@@ -41,17 +42,6 @@ const extractConfigPath = (args) => {
   }
   return void 0;
 };
-const DEFAULT_BANNER_TEXT = "This file was auto-generated by @amritk/mjst.\n * Do not edit it manually \u2014 your changes will be overwritten on the next generation.";
-const resolveBanner = (banner) => {
-  if (!banner)
-    return "";
-  const text = banner === true ? DEFAULT_BANNER_TEXT : banner;
-  return `/**
- * ${text}
- */
-
-`;
-};
 const commitOrDiscard = async (writer, stageAll) => {
   try {
     await stageAll();

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 types, validators and parsers 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  --validators-only     Emit the validator half and no parser: the type, isX, validateX and\n                        whichever of checkX/coerceX/repairX were asked for (implies\n                        --validators; the mirror of --types-only)\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";
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript types, validators and parsers 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  --validators-only     Emit the validator half and no parser: the type, isX, validateX and\n                        whichever of checkX/coerceX/repairX were asked for (implies\n                        --validators; the mirror of --types-only)\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 (text made of\n                        // lines is emitted as written, e.g. \"// @ts-nocheck\")\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

@@ -44,7 +44,8 @@ Output:
   --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)
   --root-type <name>    Root type name for a single --schema run (default: schema title or filename)
   --type-suffix <s>     Suffix appended to every $ref-derived type name
-  --banner [text]       Prepend a header comment to every generated file
+  --banner [text]       Prepend a header comment to every generated file (text made of
+                        // lines is emitted as written, e.g. "// @ts-nocheck")
   --readonly            Emit deeply readonly type definitions
 
 Validation:

package/dist/resolve-banner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Turns the `banner` option into the header prepended to each generated file.
+ *
+ * A message is wrapped in a JSDoc block, which reads well and is what most
+ * headers want. Text made only of `//` lines is emitted as written,
+ * because some headers are directives rather than prose, and only the
+ * line-comment form counts as one: TypeScript ignores a `@ts-nocheck` inside
+ * a block comment, so `--banner "// @ts-nocheck"` was the one header a strict
+ * project needed and the one the wrapping made impossible.
+ */
+export declare const resolveBanner: (banner: boolean | string | undefined) => string;

package/dist/resolve-banner.js

@@ -0,0 +1,22 @@
+const DEFAULT_BANNER_TEXT = "This file was auto-generated by @amritk/mjst.\n * Do not edit it manually \u2014 your changes will be overwritten on the next generation.";
+const isLineComments = (text) => {
+  const lines = text.split("\n").filter((line) => line.trim() !== "");
+  return lines.length > 0 && lines.every((line) => line.trimStart().startsWith("//"));
+};
+const resolveBanner = (banner) => {
+  if (!banner)
+    return "";
+  const text = banner === true ? DEFAULT_BANNER_TEXT : banner;
+  if (isLineComments(text))
+    return `${text.trim()}
+
+`;
+  return `/**
+ * ${text}
+ */
+
+`;
+};
+export {
+  resolveBanner
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,14 +49,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.8",
-    "@amritk/api": "^0.16.6",
-    "@amritk/asyncapi": "^0.3.6",
-    "@amritk/generate-examples": "^0.8.10",
+    "@amritk/adapters": "^0.6.9",
+    "@amritk/api": "^0.16.7",
+    "@amritk/asyncapi": "^0.3.7",
+    "@amritk/generate-examples": "^0.8.11",
     "@amritk/generate-markdown": "^0.12.0",
-    "@amritk/helpers": "^0.24.0",
-    "@amritk/lint": "^0.7.0",
-    "@amritk/validation": "^0.4.1",
+    "@amritk/helpers": "^0.25.0",
+    "@amritk/lint": "^0.7.1",
+    "@amritk/validation": "^0.5.0",
     "@amritk/resolve-refs": "^0.9.0",
     "@amritk/yaml": "^0.8.0",
     "fast-glob": "^3.3.2",