@amritk/mjst 0.11.0 → 0.12.0

package/README.md

@@ -85,6 +85,30 @@ imports from that single shared location. `--build` compiles the whole tree in p
 schema's root type is named after the schema (its `title`, else its filename in PascalCase),
 so `user.json` yields `User` / `parseUser` and `api/order.json` yields `Order` / `parseOrder`.
 
+### Validators
+
+Pass `--validators` to also emit runtime validation functions beside the parsers. For every
+generated type `X` you get a `validateX(input)` — returning a rich `ValidationResult` with
+JSON-Pointer error paths — and an `isX(input)` boolean type guard:
+
+```bash
+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:
+
+```
+generated/
+  schema.ts, index.ts            ← parsers + types
+  validators/
+    schema.ts, index.ts          ← validateX / isX
+    validation-result.ts         ← ValidationResult / ValidationError contract
+```
+
+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.
+
 ### Running the generated output
 
 By default mjst emits relative imports with the literal `.ts` extension (e.g.
@@ -107,6 +131,38 @@ since tsc cannot emit from `.ts` specifiers.
 > giving `parseSpecPlan` / `validateSpecPlanShape`). Pass `--root-type <Name>` to override it for
 > a single `--schema` run. Update any imports that referenced `Document` / `parseDocument`.
 
+### External and remote `$ref`s
+
+A schema can split its definitions across files. When a schema references another
+document — `{ "$ref": "./address.json" }` or `{ "$ref": "./common.json#/$defs/id" }` —
+mjst dereferences those cross-file targets before generating, inlining them into a
+single schema so the generated parsers cover the whole shape:
+
+```bash
+npx mjst --schema ./order.json --out-dir ./generated
+```
+
+Same-document refs (`#/$defs/...`) are left untouched — the generator resolves those
+itself into named type files, so nothing changes for schemas that only reference
+themselves. Local cross-file refs resolve from disk with no extra flags. Remote
+(`http(s)`) refs stay **offline by default**: a schema with a remote `$ref` fails
+rather than making a network call unless you opt in.
+
+```bash
+# Allow remote $ref fetches
+npx mjst --schema ./order.json --out-dir ./generated --resolve-remote
+
+# …restricted to specific hosts (implies --resolve-remote)
+npx mjst --schema ./order.json --out-dir ./generated --allowed-hosts schemas.example.com
+
+# …permitting private/loopback hosts (off by default as an SSRF guard)
+npx mjst --schema ./order.json --out-dir ./generated --resolve-remote --allow-private-hosts
+```
+
+Unresolvable references (a missing file, a refused host, a bad URL) fail the run with
+the underlying reason rather than emitting a half-resolved schema. This works with
+`--schema-dir` too — each schema resolves its own external references.
+
 ### Config file
 
 ```bash
@@ -240,6 +296,24 @@ The exit code is `0` when no finding reaches `--fail-severity`, `1` when one doe
 <td colspan="4">Generate only TypeScript type definitions without parser functions. Useful when you only need the type shapes and do not need runtime validation.</td>
 </tr>
 <tr>
+<td>✅ <code>validators</code></td>
+<td><code>--validators</code></td>
+<td><code>boolean</code></td>
+<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>
+</tr>
+<tr>
+<td>🎲 <code>examples</code></td>
+<td><code>--examples</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit test-data files for every schema into an examples/ subdirectory of the output destination: a fast-check arbitrary (FooArbitrary) that produces schema-valid values and a concrete fooExample value. Under schemaDir the examples mirror the schema layout so they never collide with the parser output. The generated arbitraries import fast-check, which consumers must install as a (dev) dependency; the static example values have no runtime dependencies.</td>
+</tr>
+<tr>
 <td>🔨 <code>build</code></td>
 <td><code>--build</code></td>
 <td><code>boolean</code></td>
@@ -312,6 +386,15 @@ The exit code is `0` when no finding reaches `--fail-severity`, `1` when one doe
 <td colspan="4">Suffix appended to every generated type name derived from a $ref (e.g. 'Object' turns Contact into ContactObject). Defaults to no suffix. The root type name is used verbatim and is unaffected.</td>
 </tr>
 <tr>
+<td>🪧 <code>banner</code></td>
+<td><code>--banner [text]</code></td>
+<td><code>boolean | string</code></td>
+<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>
+</tr>
+<tr>
 <td>🔗 <code>importExt</code></td>
 <td><code>--import-ext &lt;ext&gt;</code></td>
 <td><code>string</code></td>
@@ -330,13 +413,40 @@ The exit code is `0` when no finding reaches `--fail-severity`, `1` when one doe
 <td colspan="4">Name for the root type of a single --schema run (e.g. 'Program' yields parseProgram / validateProgramShape). When omitted, the name is derived from the schema's title, falling back to the schema filename in PascalCase (spec-plan.json → SpecPlan) and then to 'Document'. Not supported with --schema-dir, where each schema derives its own root type from its filename.<br><strong>Examples:</strong> <code>"Program"</code></td>
 </tr>
 <tr>
+<td>🌐 <code>resolveRemote</code></td>
+<td><code>--resolve-remote</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Allow fetching http(s) $refs while dereferencing a schema that contains cross-file or remote references. Off by default, so generation stays offline unless asked: a schema with a remote $ref fails rather than making a network call. Local cross-file $refs are always resolved and do not need this flag. A non-empty allowedHosts implies this.</td>
+</tr>
+<tr>
+<td>🛡️ <code>allowedHosts</code></td>
+<td><code>--allowed-hosts &lt;hosts&gt;</code></td>
+<td><code>array</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Restrict remote $ref fetches to these hosts (e.g. api.example.com). Accepts a comma-separated list or the flag repeated. Providing an allow-list is itself an opt-in to remote fetching (it implies resolveRemote), and each listed host bypasses the private-host guard.<br><strong>Examples:</strong> <code>["schemas.example.com"]</code></td>
+</tr>
+<tr>
+<td>🔓 <code>allowPrivateHosts</code></td>
+<td><code>--allow-private-hosts</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Permit remote $refs to private, loopback, and link-local hosts. Off by default: such targets are refused as a best-effort SSRF guard (notably the 169.254.169.254 cloud-metadata endpoint). An explicit allowedHosts entry always bypasses this guard.</td>
+</tr>
+<tr>
 <td>⚙️ <code>config</code></td>
 <td><code>--config &lt;path&gt;</code></td>
 <td><code>string</code></td>
 <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, outDir, outFile, typesOnly, build, logWarnings, strict, readonly, helpers, typeSuffix, importExt, rootType). 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, logWarnings, strict, stripUnknown, caseInsensitive, readonly, helpers, typeSuffix, banner, importExt, rootType, resolveRemote, allowedHosts, allowPrivateHosts). CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
 </tr>
 </tbody>
 </table>

package/dist/cli-config.d.ts

@@ -36,6 +36,25 @@ export type CliConfig = {
      * Useful when you only need the type shapes and do not need runtime validation.
      */
     readonly typesOnly?: boolean;
+    /**
+     * 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.
+     */
+    readonly validators?: boolean;
+    /**
+     * When true, also emit test-data files for every schema: a `fast-check`
+     * arbitrary (`FooArbitrary`) that produces schema-valid values and a concrete
+     * `fooExample` value. The files are written into an `examples/` subdirectory of
+     * the output destination (mirroring the schema layout under `--schema-dir`) so
+     * they never collide with the parser output. The generated arbitraries import
+     * `fast-check`, which consumers must install as a (dev) dependency.
+     */
+    readonly examples?: boolean;
     /**
      * When true, compile the generated TypeScript files to .js and .d.ts output.
      * The .ts source files are removed after compilation.
@@ -120,4 +139,25 @@ export type CliConfig = {
      * Not supported with `schemaDir`, where each schema names its own root.
      */
     readonly rootType?: string;
+    /**
+     * Allow fetching `http(s)` `$ref`s while dereferencing a schema that contains
+     * cross-file or remote references. Defaults to `false`: generation stays
+     * offline unless asked, so a schema with a remote `$ref` fails rather than
+     * making a network call. A non-empty `allowedHosts` implies this.
+     */
+    readonly resolveRemote?: boolean;
+    /**
+     * If set, only these hosts (e.g. `api.example.com`) may be fetched for remote
+     * `$ref`s. Restricting to an allow-list is itself an opt-in to remote fetching
+     * (it implies `resolveRemote`), and each listed host bypasses the private-host
+     * guard.
+     */
+    readonly allowedHosts?: readonly string[];
+    /**
+     * Permit remote `$ref`s to private, loopback, and link-local hosts. Defaults
+     * to `false`: such targets are refused as a best-effort SSRF guard (notably the
+     * `169.254.169.254` cloud-metadata endpoint). An explicit `allowedHosts` entry
+     * always bypasses this guard.
+     */
+    readonly allowPrivateHosts?: boolean;
 };

package/dist/cli.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, unlink, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
-import { getAdapter } from '@amritk/adapters/get-adapter';
 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';
 import { detectHelpersMode } from './detect-helpers-mode.js';
+import { emitExamples } from './emit-examples.js';
 import { HELP_TEXT } from './help-text.js';
 import { loadConfig } from './load-config.js';
-import { loadSchemaModule } from './load-schema-module.js';
+import { loadSchema } from './load-schema.js';
 import { parseCliArgs } from './parse-cli-args.js';
 import { readVersion } from './read-version.js';
 import { resolveImportExt } from './resolve-import-ext.js';
@@ -52,16 +53,6 @@ const extractConfigPath = (args) => {
     }
     return undefined;
 };
-/** Reads a JSON Schema off disk, or loads a module and converts it via its adapter. */
-const loadSchema = async (config, schemaPath) => {
-    const inputFormat = config.input ?? 'json';
-    if (inputFormat === 'json') {
-        return JSON.parse(await readFile(schemaPath, 'utf-8'));
-    }
-    console.log(`Input format: ${inputFormat}`);
-    const source = await loadSchemaModule(schemaPath, config.export);
-    return getAdapter(inputFormat).toJSONSchema(source);
-};
 const DEFAULT_BANNER_TEXT = 'This file was auto-generated by @amritk/mjst.\n * Do not edit it manually — your changes will be overwritten on the next generation.';
 const resolveBanner = (banner) => {
     if (!banner)
@@ -75,6 +66,30 @@ const writeGeneratedFile = async (baseDir, filename, content) => {
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, content, 'utf-8');
 };
+/**
+ * Emits fast-check arbitrary + example files for one schema (delegating to
+ * {@link emitExamples}) and logs each written path. The files land in an
+ * `examples/` subdirectory of `outputDir` so they never collide with the parser
+ * files, which share the same `<name>.ts` / `index.ts` names. `subDir` mirrors a
+ * schema's nested location under `--schema-dir`. The example sources are left out
+ * of `--build`: they import the `fast-check` peer dependency and are meant to be
+ * consumed by tests, not compiled alongside the runtime parsers.
+ */
+const runExamples = async (config, schema, rootTypeName, outputDir, subDir = '') => {
+    const written = await emitExamples({
+        schema: schema,
+        rootTypeName,
+        outputDir,
+        subDir,
+        bannerPrefix: config.banner ? resolveBanner(config.banner) : '',
+        // Spread conditionally: `exactOptionalPropertyTypes` rejects an explicit
+        // `undefined` for the optional `typeSuffix`.
+        ...(config.typeSuffix !== undefined ? { typeSuffix: config.typeSuffix } : {}),
+    });
+    for (const path of written) {
+        console.log(`Generated example: ${path}`);
+    }
+};
 /**
  * Compiles the generated `.ts` files to `.js`/`.d.ts` with a temporary tsconfig,
  * then removes the intermediate sources. `tsFiles` are paths relative to `outputDir`.
@@ -145,6 +160,25 @@ const findJsonSchemas = async (dir) => {
     }
     return results;
 };
+/**
+ * Emits validator files (`validateX` / `isX`) for one schema into `validatorsSubDir`
+ * (a path relative to `outputDir`). The validators carry the same schema-derived
+ * filenames as the parsers, so they live in their own subdirectory to avoid
+ * colliding. Returns the written `.ts` paths relative to `outputDir` so the caller
+ * can fold them into a `--build` compilation.
+ */
+const runValidators = async (config, schema, rootTypeName, outputDir, validatorsSubDir) => {
+    const files = await buildValidatorSchema(schema, rootTypeName, config.typeSuffix);
+    const written = [];
+    for (const file of files) {
+        const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
+        const relFilename = join(validatorsSubDir, file.filename);
+        await writeGeneratedFile(outputDir, relFilename, content);
+        written.push(relFilename);
+        console.log(`Generated: ${relFilename}`);
+    }
+    return written;
+};
 /** Generates parsers for a single schema (the original one-schema-in, one-outDir-out flow). */
 const runSingle = async (config, schemaPath, outputDir) => {
     const schema = await loadSchema(config, schemaPath);
@@ -159,11 +193,17 @@ const runSingle = async (config, schemaPath, outputDir) => {
         await writeGeneratedFile(outputDir, file.filename, content);
         console.log(`Generated: ${file.filename}`);
     }
+    const validatorFiles = config.validators
+        ? await runValidators(config, schema, rootTypeName, outputDir, 'validators')
+        : [];
+    if (config.examples) {
+        await runExamples(config, schema, rootTypeName, outputDir);
+    }
     if (config.build) {
-        await buildOutput(outputDir, files.map((f) => f.filename), config.typesOnly);
+        await buildOutput(outputDir, [...files.map((f) => f.filename), ...validatorFiles], config.typesOnly);
     }
     else {
-        console.log(`\nTotal files generated: ${files.length}`);
+        console.log(`\nTotal files generated: ${files.length + validatorFiles.length}`);
     }
 };
 /**
@@ -181,6 +221,9 @@ const runSingleFile = async (config, schemaPath, outFilePath) => {
     const combined = combineGeneratedFiles(files);
     await writeFile(outFilePath, config.banner ? resolveBanner(config.banner) + combined : combined, 'utf-8');
     console.log(`Generated: ${relative(process.cwd(), outFilePath)}`);
+    if (config.examples) {
+        await runExamples(config, schema, rootTypeName, outputDir);
+    }
     if (config.build) {
         await buildOutput(outputDir, [basename(outFilePath)], config.typesOnly);
     }
@@ -233,6 +276,16 @@ const runRecursive = async (config, schemaDir, outputDir) => {
             writtenTsFiles.push(relativeFilename);
             console.log(`Generated: ${relativeFilename}`);
         }
+        if (config.validators) {
+            // Mirror the parser layout under a top-level `validators/` tree so each
+            // schema's validators sit beside their parser counterparts without sharing
+            // a filename.
+            const validatorFiles = await runValidators(config, schema, rootTypeName, outputDir, join('validators', relNoExt));
+            writtenTsFiles.push(...validatorFiles);
+        }
+        if (config.examples) {
+            await runExamples(config, schema, rootTypeName, outputDir, relNoExt);
+        }
     }
     for (const [filename, content] of sharedHelpers) {
         await writeGeneratedFile(outputDir, filename, content);
@@ -293,6 +346,16 @@ const run = async () => {
         console.error('Error: --import-ext ts cannot be combined with --build. Drop --build to keep runnable .ts sources.');
         process.exit(1);
     }
+    // Validators are runtime code (validateX / isX), so they have nothing to emit
+    // in the type-only flows.
+    if (config.validators && config.typesOnly) {
+        console.error('Error: --validators cannot be combined with --types-only, which emits no runtime code.');
+        process.exit(1);
+    }
+    if (config.validators && config.outFile) {
+        console.error('Error: --validators cannot be combined with --out-file. Use --out-dir to emit validator files.');
+        process.exit(1);
+    }
     // Single-file output is the alternative to a directory of files.
     if (config.outFile) {
         if (!config.typesOnly) {

package/dist/emit-examples.d.ts

@@ -0,0 +1,36 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Inputs for {@link emitExamples}. The schema and its root type name are the same
+ * ones handed to the parser generator, so the arbitraries/examples line up with
+ * the parsers that consume them.
+ */
+export type EmitExamplesOptions = {
+    readonly schema: JSONSchema;
+    readonly rootTypeName: string;
+    /** Output root; example files always land under `<outputDir>/examples/`. */
+    readonly outputDir: string;
+    /**
+     * Nested location of the schema relative to `--schema-dir` (e.g. `api/order`),
+     * mirrored beneath `examples/` so each schema's test data sits beside where its
+     * parsers were emitted. Defaults to `''` (single-schema output at the root).
+     */
+    readonly subDir?: string;
+    /** Suffix appended to every `$ref`-derived type/arbitrary name. Defaults to `''`. */
+    readonly typeSuffix?: string;
+    /** Header comment (already wrapped in a JSDoc block) prepended to each file, or `''`. */
+    readonly bannerPrefix?: string;
+};
+/**
+ * Emits fast-check arbitrary + concrete example files for one schema into an
+ * `examples/` subdirectory of `outputDir`.
+ *
+ * The dedicated subdirectory keeps the test-data output from colliding with the
+ * parser files, which otherwise share the same `<name>.ts` / `index.ts` names.
+ * Each generated file exports a `FooArbitrary` (a `fast-check` arbitrary that
+ * produces schema-valid values) and a static `fooExample` value; an `index.ts`
+ * barrel re-exports them. The arbitraries import `fast-check`, which consumers
+ * must install as a (dev) dependency.
+ *
+ * @returns The written file paths, relative to `outputDir`.
+ */
+export declare const emitExamples: (options: EmitExamplesOptions) => Promise<string[]>;

package/dist/emit-examples.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { buildExampleSchema } from '@amritk/generate-examples';
+/**
+ * Emits fast-check arbitrary + concrete example files for one schema into an
+ * `examples/` subdirectory of `outputDir`.
+ *
+ * The dedicated subdirectory keeps the test-data output from colliding with the
+ * parser files, which otherwise share the same `<name>.ts` / `index.ts` names.
+ * Each generated file exports a `FooArbitrary` (a `fast-check` arbitrary that
+ * produces schema-valid values) and a static `fooExample` value; an `index.ts`
+ * barrel re-exports them. The arbitraries import `fast-check`, which consumers
+ * must install as a (dev) dependency.
+ *
+ * @returns The written file paths, relative to `outputDir`.
+ */
+export const emitExamples = async (options) => {
+    const { schema, rootTypeName, outputDir, subDir = '', typeSuffix, bannerPrefix = '' } = options;
+    const files = await buildExampleSchema(schema, rootTypeName, typeSuffix);
+    const exampleDir = join(outputDir, 'examples', subDir);
+    const written = [];
+    for (const file of files) {
+        const filePath = join(exampleDir, file.filename);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, bannerPrefix + file.content, 'utf-8');
+        written.push(relative(outputDir, filePath));
+    }
+    return written;
+};

package/dist/has-external-refs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether `data` contains a reference into another document (a `$ref` value that
+ * is not a same-document `#...` fragment). Same-document references resolve
+ * without a disk round-trip, so callers can skip the file-backed resolver — and
+ * preserve behavior that depends on those internal refs — unless an external
+ * (cross-file or remote) target exists.
+ */
+export declare const hasExternalRefs: (data: unknown) => boolean;

package/dist/has-external-refs.js

@@ -0,0 +1,22 @@
+/** The reference keywords whose value may point at another document (a non-`#` target). */
+const REF_KEYWORDS = ['$ref', '$dynamicRef', '$recursiveRef'];
+/**
+ * Whether `data` contains a reference into another document (a `$ref` value that
+ * is not a same-document `#...` fragment). Same-document references resolve
+ * without a disk round-trip, so callers can skip the file-backed resolver — and
+ * preserve behavior that depends on those internal refs — unless an external
+ * (cross-file or remote) target exists.
+ */
+export const hasExternalRefs = (data) => {
+    if (data === null || typeof data !== 'object')
+        return false;
+    if (Array.isArray(data))
+        return data.some(hasExternalRefs);
+    const obj = data;
+    for (const keyword of REF_KEYWORDS) {
+        const value = obj[keyword];
+        if (typeof value === 'string' && !value.startsWith('#'))
+            return true;
+    }
+    return Object.values(obj).some(hasExternalRefs);
+};

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\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\n  --export <name>       Which export of the schema module to use when --input is not json\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  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\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\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\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\n  --export <name>       Which export of the schema module to use when --input is not json\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  --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\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,6 +21,8 @@ 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
+  --examples            Also emit fast-check arbitraries + example values under examples/
   --build               Compile the generated files to .js/.d.ts (implies --import-ext js)
   --import-ext <ext>    Extension on generated relative imports: ts (default) or js
   --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)
@@ -35,6 +37,11 @@ Validation:
   --case-insensitive    Normalize mis-cased enum/const strings to their exact casing
   --log-warnings        console.warn on input keys not declared in the schema
 
+Reference resolution:
+  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)
+  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)
+  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)
+
 Misc:
   --config <path>       JSON config file with the same keys; CLI flags take precedence
   --version, -v         Print the CLI version

package/dist/lint/resolver.js

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
-import { createDocument, resolveSourceOriginFromMap, } from '@amritk/lint';
+import { createDocument, DiagnosticSeverity, resolveSourceOriginFromMap, } from '@amritk/lint';
 import { resolveRefs, resolveRefsFromFile } from '@amritk/resolve-refs';
 import { parse as parseYaml } from '@amritk/yaml';
+import { hasExternalRefs } from '../has-external-refs.js';
 const isRemote = (location) => /^https?:\/\//i.test(location);
 /**
  * Parses a referenced document by extension: YAML for `.yaml`/`.yml`, JSON for
@@ -21,26 +22,6 @@ const parseDoc = (content, location) => {
         return parseYaml(content);
     }
 };
-/** The reference keywords whose value may point at another document (a non-`#` target). */
-const REF_KEYWORDS = ['$ref', '$dynamicRef', '$recursiveRef'];
-/**
- * Whether `data` contains a reference into another document (a `$ref` value that
- * is not a same-document `#...` fragment). Internal-only documents resolve fully
- * in memory, so we avoid the disk round-trip unless an external target exists.
- */
-const hasExternalRefs = (data) => {
-    if (data === null || typeof data !== 'object')
-        return false;
-    if (Array.isArray(data))
-        return data.some(hasExternalRefs);
-    const obj = data;
-    for (const keyword of REF_KEYWORDS) {
-        const value = obj[keyword];
-        if (typeof value === 'string' && !value.startsWith('#'))
-            return true;
-    }
-    return Object.values(obj).some(hasExternalRefs);
-};
 /** Whether the file at `absolute` reads back byte-for-byte as `input` (the document we linted). */
 const readsBackAs = (absolute, input) => {
     try {
@@ -82,6 +63,28 @@ const buildSourceSet = (rootDocument, resolved, origins, rootLocation) => {
         origin: (path) => resolveSourceOriginFromMap(resolved, originMap, rootLocation, path),
     };
 };
+/** A zero-width range at the document start, for resolve errors with no recoverable position. */
+const DOCUMENT_START = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
+/**
+ * Maps resolver failures ({@link ResolveError}) into lint findings so an
+ * unresolvable `$ref` — a typo'd pointer, a missing file, a refused/failed
+ * remote fetch — surfaces as a diagnostic instead of being silently dropped. An
+ * error carrying a JSON path is anchored to that node's position in the root
+ * document (best effort, `closest`); otherwise the finding is document-level.
+ */
+const toFindings = (errors, root) => errors.map((error) => {
+    const location = error.path.length > 0 ? root.getLocationForJsonPath(error.path, true) : undefined;
+    const finding = {
+        code: 'unresolved-ref',
+        message: error.message,
+        path: error.path,
+        severity: DiagnosticSeverity.Error,
+        range: location?.range ?? DOCUMENT_START,
+    };
+    if (root.source !== undefined)
+        finding.source = root.source;
+    return finding;
+});
 /**
  * Builds a {@link LintResolver} backed by `@amritk/resolve-refs`, dereferencing
  * `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor`
@@ -105,11 +108,19 @@ export const createLintResolver = (options = {}) => {
         if (source && hasExternalRefs(document.data)) {
             const absolute = resolvePath(source);
             if (readsBackAs(absolute, input)) {
-                const { resolved, origins } = await resolveRefsFromFile(absolute, fromFileOptions);
-                return { resolved, sources: buildSourceSet(document, resolved, origins, absolute) };
+                const { resolved, origins, errors } = await resolveRefsFromFile(absolute, fromFileOptions);
+                return {
+                    resolved,
+                    sources: buildSourceSet(document, resolved, origins, absolute),
+                    ...(errors.length > 0 ? { diagnostics: toFindings(errors, document) } : {}),
+                };
             }
         }
-        const { resolved, origins } = resolveRefs(document.data, { trackOrigins: true });
-        return { resolved, sources: buildSourceSet(document, resolved, origins, '') };
+        const { resolved, origins, errors } = resolveRefs(document.data, { trackOrigins: true });
+        return {
+            resolved,
+            sources: buildSourceSet(document, resolved, origins, ''),
+            ...(errors.length > 0 ? { diagnostics: toFindings(errors, document) } : {}),
+        };
     };
 };

package/dist/load-config.js

@@ -4,6 +4,7 @@ const SOURCE_FORMATS = ['json', 'typebox', 'zod', 'valibot', 'effect'];
 const isSourceFormat = (value) => typeof value === 'string' && SOURCE_FORMATS.includes(value);
 const isHelpersMode = (value) => value === 'package' || value === 'embedded';
 const isImportExt = (value) => value === 'js' || value === 'ts';
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string');
 /**
  * Loads a JSON config file and returns the relevant CLI config properties.
  * The config file should have the same keys as the CLI flags (schema, outDir).
@@ -24,6 +25,7 @@ export const loadConfig = async (configPath) => {
         ...(isSourceFormat(obj['input']) && { input: obj['input'] }),
         ...(typeof obj['export'] === 'string' && { export: obj['export'] }),
         ...(typeof obj['typesOnly'] === 'boolean' && { typesOnly: obj['typesOnly'] }),
+        ...(typeof obj['examples'] === 'boolean' && { examples: obj['examples'] }),
         ...(typeof obj['build'] === 'boolean' && { build: obj['build'] }),
         ...(typeof obj['logWarnings'] === 'boolean' && { logWarnings: obj['logWarnings'] }),
         ...(typeof obj['strict'] === 'boolean' && { strict: obj['strict'] }),
@@ -36,5 +38,8 @@ export const loadConfig = async (configPath) => {
         ...(typeof obj['typeSuffix'] === 'string' && { typeSuffix: obj['typeSuffix'] }),
         // `banner` is a boolean toggle or a custom header string, mirroring the CLI flag.
         ...((typeof obj['banner'] === 'boolean' || typeof obj['banner'] === 'string') && { banner: obj['banner'] }),
+        ...(typeof obj['resolveRemote'] === 'boolean' && { resolveRemote: obj['resolveRemote'] }),
+        ...(isStringArray(obj['allowedHosts']) && { allowedHosts: obj['allowedHosts'] }),
+        ...(typeof obj['allowPrivateHosts'] === 'boolean' && { allowPrivateHosts: obj['allowPrivateHosts'] }),
     };
 };

package/dist/load-schema.d.ts

@@ -0,0 +1,14 @@
+import type { CliConfig } from './cli-config.js';
+/**
+ * Reads a JSON Schema off disk, or loads a module and converts it via its adapter.
+ *
+ * For JSON input, a schema whose only references are same-document `#/...`
+ * pointers is parsed as-is — the generator resolves those internal `$ref`s
+ * itself into named type files, so inlining them here would collapse that
+ * structure. When a cross-file or remote `$ref` is present (which the generator
+ * cannot follow on its own), the schema is dereferenced with
+ * `@amritk/resolve-refs`, inlining every external target into a single document.
+ * Any resolve failures are surfaced as a CLI error rather than silently yielding
+ * a half-resolved schema.
+ */
+export declare const loadSchema: (config: Partial<CliConfig>, schemaPath: string) => Promise<unknown>;

package/dist/load-schema.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { getAdapter } from '@amritk/adapters/get-adapter';
+import { resolveRefsFromFile } from '@amritk/resolve-refs';
+import { hasExternalRefs } from './has-external-refs.js';
+import { loadSchemaModule } from './load-schema-module.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, and private/
+ * loopback hosts stay blocked as an SSRF guard unless explicitly permitted.
+ */
+const buildResolveOptions = (config) => {
+    // A non-empty allow-list is itself an opt-in to remote fetching.
+    const remote = (config.resolveRemote ?? false) || (config.allowedHosts?.length ?? 0) > 0;
+    return {
+        remote,
+        ...(config.allowedHosts ? { allowedHosts: [...config.allowedHosts] } : {}),
+        ...(config.allowPrivateHosts ? { allowPrivateHosts: config.allowPrivateHosts } : {}),
+    };
+};
+/** Renders resolver failures into a single CLI error message. */
+const formatResolveErrors = (schemaPath, errors) => {
+    const details = errors.map((error) => `  - ${error.message}`).join('\n');
+    return `Failed to resolve $refs in ${schemaPath}:\n${details}`;
+};
+/**
+ * Reads a JSON Schema off disk, or loads a module and converts it via its adapter.
+ *
+ * For JSON input, a schema whose only references are same-document `#/...`
+ * pointers is parsed as-is — the generator resolves those internal `$ref`s
+ * itself into named type files, so inlining them here would collapse that
+ * structure. When a cross-file or remote `$ref` is present (which the generator
+ * cannot follow on its own), the schema is dereferenced with
+ * `@amritk/resolve-refs`, inlining every external target into a single document.
+ * Any resolve failures are surfaced as a CLI error rather than silently yielding
+ * a half-resolved schema.
+ */
+export const loadSchema = async (config, schemaPath) => {
+    const inputFormat = config.input ?? 'json';
+    if (inputFormat === 'json') {
+        const data = JSON.parse(await readFile(schemaPath, 'utf-8'));
+        if (!hasExternalRefs(data))
+            return data;
+        const { resolved, errors } = await resolveRefsFromFile(schemaPath, buildResolveOptions(config));
+        if (errors.length > 0)
+            throw new Error(formatResolveErrors(schemaPath, errors));
+        return resolved;
+    }
+    console.log(`Input format: ${inputFormat}`);
+    const source = await loadSchemaModule(schemaPath, config.export);
+    return getAdapter(inputFormat).toJSONSchema(source);
+};

package/dist/parse-cli-args.js

@@ -2,12 +2,16 @@ const SOURCE_FORMATS = ['json', 'typebox', 'zod', 'valibot', 'effect'];
 // Boolean flags toggle on by presence and accept `--flag=false` to opt out.
 const BOOLEAN_KEYS = new Set([
     'typesOnly',
+    'validators',
+    'examples',
     'build',
     'logWarnings',
     'strict',
     'stripUnknown',
     'caseInsensitive',
     'readonly',
+    'resolveRemote',
+    'allowPrivateHosts',
 ]);
 // Value flags consume the following argument (or `--flag=value`).
 const VALUE_KEYS = new Set([
@@ -40,6 +44,20 @@ const parseImportExtValue = (value) => {
     return undefined;
 };
 const parseInputValue = (value) => SOURCE_FORMATS.includes(value) ? value : undefined;
+/**
+ * Appends the hosts in `value` (comma-separated) onto `allowedHosts`. Repeating
+ * `--allowed-hosts` accumulates, so `--allowed-hosts a.com --allowed-hosts b.com`
+ * and `--allowed-hosts a.com,b.com` are equivalent. Blank entries are dropped.
+ */
+const appendAllowedHosts = (config, value) => {
+    const hosts = value
+        .split(',')
+        .map((host) => host.trim())
+        .filter((host) => host.length > 0);
+    if (hosts.length === 0)
+        return;
+    config.allowedHosts = [...(config.allowedHosts ?? []), ...hosts];
+};
 /** Assigns a value-flag onto the config. Returns false for unknown keys. */
 const assignValue = (config, key, value) => {
     switch (key) {
@@ -98,6 +116,12 @@ const assignBoolean = (config, key, value) => {
         case 'typesOnly':
             config.typesOnly = value;
             return true;
+        case 'validators':
+            config.validators = value;
+            return true;
+        case 'examples':
+            config.examples = value;
+            return true;
         case 'build':
             config.build = value;
             return true;
@@ -116,6 +140,12 @@ const assignBoolean = (config, key, value) => {
         case 'readonly':
             config.readonly = value;
             return true;
+        case 'resolveRemote':
+            config.resolveRemote = value;
+            return true;
+        case 'allowPrivateHosts':
+            config.allowPrivateHosts = value;
+            return true;
         default:
             return false;
     }
@@ -143,6 +173,9 @@ export const parseCliArgs = (args) => {
                 // --banner=false → false, --banner=true → true, --banner=<text> → custom string
                 config.banner = value === 'false' ? false : value === 'true' ? true : value;
             }
+            else if (key === 'allowedHosts') {
+                appendAllowedHosts(config, value);
+            }
             else if (BOOLEAN_KEYS.has(key)) {
                 assignBoolean(config, key, value !== 'false');
             }
@@ -172,6 +205,16 @@ export const parseCliArgs = (args) => {
             }
             continue;
         }
+        // --allowed-hosts takes a value (comma-separated) and accumulates when repeated.
+        if (key === 'allowedHosts') {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`Flag "--${flagName}" expects a value.`);
+            }
+            appendAllowedHosts(config, value);
+            i++;
+            continue;
+        }
         // Boolean flag: presence alone enables it, no value needed
         if (BOOLEAN_KEYS.has(key)) {
             assignBoolean(config, key, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -41,13 +41,15 @@
     "generate-readme": "bun run ./scripts/generate-readme.ts"
   },
   "dependencies": {
-    "@amritk/adapters": "0.2.16",
-    "@amritk/generate-parsers": "0.16.0",
+    "@amritk/adapters": "0.3.0",
+    "@amritk/generate-examples": "0.5.0",
+    "@amritk/generate-parsers": "0.16.1",
+    "@amritk/generate-validators": "0.11.6",
     "@amritk/generate-markdown": "0.4.1",
-    "@amritk/helpers": "0.12.0",
-    "@amritk/lint": "0.2.0",
-    "@amritk/resolve-refs": "0.3.0",
-    "@amritk/yaml": "0.2.3",
+    "@amritk/helpers": "0.13.0",
+    "@amritk/lint": "0.3.0",
+    "@amritk/resolve-refs": "0.4.0",
+    "@amritk/yaml": "0.3.0",
     "fast-glob": "^3.3.2",
     "yargs": "^17.7.2"
   },