@amritk/mjst 0.18.0 → 0.20.0

package/README.md

@@ -217,6 +217,19 @@ config/service.yaml:2:7  error  config-schema  /port must be integer
 
 With no `-r`, mjst discovers a `.lint.{yaml,yml,json,js,mjs}` ruleset by walking up from each linted file. A ruleset maps a JSONPath (`given`) to a function (`then`) — `schema` (JSON Schema), `casing`, `pattern`, `truthy`, and more, plus your own. The [`@amritk/lint` README](../lint#ruleset-format) documents the ruleset format and built-in functions. For machine-readable output (JSON, SARIF, …), call the [`@amritk/lint`](../lint) library's `lintDocument`, which returns structured findings.
 
+Your own ruleset can build on a preset: `extends: [asyncapi]` (or `[oas]`) layers your rules on top of the preset's, with the preset's custom functions and format detection intact — through `-r <file>` and `.lint.*` discovery alike. Relative `extends` targets and custom `functions` still resolve next to your ruleset file. Extend at most one preset per ruleset: the two bring different formats and functions and neither can resolve the other, so a ruleset naming both is refused up front. Lint AsyncAPI and OpenAPI documents in separate runs.
+
+```yaml
+# .lint.yaml — the AsyncAPI preset plus a house rule
+extends:
+  - asyncapi
+rules:
+  needs-terms-of-service:
+    given: "$.info"
+    severity: error
+    then: { field: termsOfService, function: truthy }
+```
+
 | Flag | Description |
 | --- | --- |
 | `<documents..>` | Files or globs to lint (positional). |
@@ -394,7 +407,7 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="4">Allow generated files to overwrite files that already exist in the output destination. By default a collision with a file mjst did not generate (a hand-written index.ts, say) aborts the run before anything is written, because the generator would otherwise replace it — and, under build, delete it along with the other intermediate sources. Regenerating never needs this flag: each run records what it wrote in a .mjst-manifest.json at the root of the output directory, and anything listed there is replaced freely.</td>
+<td colspan="4">Deprecated and ignored. Generated files always replace whatever is at their path, so this flag no longer does anything; it is still accepted so existing scripts and config files keep running. Reverting an unwanted replacement is version control's job. Compilation under build still only removes the intermediate sources the run itself generated.</td>
 </tr>
 <tr>
 <td>⚠️ <code>logWarnings</code></td>
@@ -451,6 +464,15 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td colspan="4">How generated fast paths (parsers and validators alike) prove a closed object — additionalProperties: false, or a stripUnknown build — carries no undeclared key. 'count-keys' compares Object.keys(obj).length and is the faster form on JavaScriptCore (Bun), where a for…in over a non-extensible object takes the engine's slow path and halves strict-parse throughput. 'count-enumerable' counts with for…in and allocates nothing; it was the faster form on Node 22, but on Node 26 'count-keys' ties or wins there too. Keep the default unless you are pinned to an older V8 and have measured your own shapes; the generated code never detects its runtime.<br><strong>Allowed:</strong> <code>"count-enumerable"</code>, <code>"count-keys"</code></td>
 </tr>
 <tr>
+<td>🧪 <code>formats</code></td>
+<td><code>--formats &lt;list&gt;</code></td>
+<td><code>string | array</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">String formats the generated validators enforce: "all", or a comma-separated list (e.g. uuid,date-time,email). Omitted, format stays an annotation — JSON Schema's own reading, and what @amritk/runtime-validators does when given no formats. Set it to whatever validates the same schemas at runtime (@amritk/lint and createApi({ formats }) run the interpreter with formats on) so the build-time and runtime answers agree. Both validateX and the flat isX check them, against a formats.ts emitted alongside the validators.</td>
+</tr>
+<tr>
 <td>🧰 <code>helpers</code></td>
 <td><code>--helpers &lt;mode&gt;</code></td>
 <td><code>string</code></td>

package/dist/cli-config.d.ts

@@ -85,15 +85,11 @@ export type CliConfig = {
      */
     readonly build?: boolean;
     /**
-     * When true, generated files may overwrite files that already exist in the
-     * output destination. By default a collision with a file mjst did not generate
-     * (a hand-written `index.ts`, say) aborts the run rather than silently
-     * replacing it — and with `build`, deleting it afterwards. Regeneration does
-     * not need this: each run records what it wrote in a `.mjst-manifest.json` at
-     * the root of the output directory, and reclaims those paths freely. With
-     * `outFile` the "output directory" is the directory holding that file, so the
-     * manifest lands beside it — generated examples and the `build` output already
-     * do.
+     * @deprecated No longer has any effect, and is accepted only so existing
+     * scripts and config files keep running. Generated files always replace
+     * whatever is at their path; version control is where an unwanted replacement
+     * shows up and gets reverted. `build` still only ever deletes the intermediate
+     * sources the run itself committed.
      */
     readonly force?: boolean;
     /**
@@ -133,6 +129,15 @@ export type CliConfig = {
      * (Node). Applies to parsers and validators alike.
      */
     readonly unknownKeys?: UnknownKeysStrategy;
+    /**
+     * String `format`s the generated validators enforce — `'all'`, or the names to
+     * check. Left unset, `format` stays an annotation, which is 2020-12's own
+     * reading and what `@amritk/runtime-validators` does when given no formats.
+     *
+     * Set it to whatever the code validating the same schemas at runtime uses, so
+     * the build-time and runtime answers agree.
+     */
+    readonly formats?: 'all' | readonly string[];
     /**
      * Controls how generated parsers reference their runtime helpers.
      * - `'package'`: emit `import ... from '@amritk/helpers/...'`.

package/dist/cli.js

@@ -67,7 +67,7 @@ const commitOrDiscard = async (writer, stageAll) => {
   return writer.commit();
 };
 const runExamples = async (config, outputDir, tasks) => {
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     for (const task of tasks) {
       await emitExamples({
@@ -139,7 +139,7 @@ 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);
+  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;
@@ -156,7 +156,7 @@ const runSingle = async (config, schemaPath, 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 writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     for (const file of files) {
       const isHelper = file.filename.startsWith("_helpers/");
@@ -186,7 +186,7 @@ const runSingleFile = async (config, schemaPath, outFilePath) => {
   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 combined = combineGeneratedFiles(files);
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     await writer.stage(basename(outFilePath), config.banner ? resolveBanner(config.banner) + combined : combined);
   });
@@ -214,7 +214,7 @@ const runRecursive = async (config, schemaDir, outputDir) => {
   await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
   const sharedHelpers = /* @__PURE__ */ new Map();
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const exampleTasks = [];
   const stageAll = async () => {
     for (const schemaFile of schemaFiles) {
@@ -279,7 +279,7 @@ const runAsyncApi = async (config, documentPath, outputDir) => {
   await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
   const sharedHelpers = /* @__PURE__ */ new Map();
-  const writer = await createOutputWriter(outputDir, config.force);
+  const writer = await createOutputWriter(outputDir);
   const exampleTasks = [];
   const contractIssues = [];
   let contractMessageCount = 0;
@@ -385,6 +385,9 @@ const run = async () => {
     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/create-output-writer.d.ts

@@ -3,22 +3,21 @@
  * final location under a temporary name, and only once the whole set is on disk
  * are the temporaries renamed into place.
  *
- * Two failure modes drive the design:
+ * The failure mode it exists for is **partial trees**. Writing straight to the
+ * final paths meant a failure halfway through (a `_helpers` path occupied by a
+ * regular file, a full disk) left some generated files behind and others missing
+ * — a tree that compiles against a schema that no longer exists. Staging first
+ * means the run either lands completely or leaves the destination as it found it.
+ * Renaming is not one atomic operation across the whole set, but every rename
+ * happens after all the risky work (generating, creating directories, writing
+ * bytes) has already succeeded, so it is the cheapest place to get the guarantee.
  *
- * 1. **Partial trees.** Writing straight to the final paths meant a failure
- *    halfway through (a `_helpers` path occupied by a regular file, a full disk)
- *    left some generated files behind and others missing — a tree that compiles
- *    against a schema that no longer exists. Staging first means the run either
- *    lands completely or leaves the destination as it found it. Renaming is not
- *    one atomic operation across the whole set, but every rename happens after
- *    all the risky work (generating, creating directories, writing bytes) has
- *    already succeeded, so it is the cheapest place to get the guarantee.
- * 2. **Clobbering hand-written files.** A generated name can collide with a file
- *    the user wrote (`index.ts` is the common one), which used to be overwritten
- *    without a word — and then, under `--build`, deleted along with the other
- *    intermediate sources. A file is only replaced when a previous run claimed it
- *    (see {@link MANIFEST_FILENAME}) or `--force` says so, and `--build` is only
- *    ever handed the paths this run actually committed.
+ * A generated path that already exists is simply replaced. The writer keeps no
+ * record of what it produced last time: an output directory is generated output,
+ * and version control is where a user sees — and reverts — a replacement they did
+ * not want. What the writer still guarantees is that `--build` only ever deletes
+ * intermediate sources this run committed, so nothing that was already sitting in
+ * the output directory is removed.
  */
 export type OutputWriter = {
     /**
@@ -34,7 +33,10 @@ export type OutputWriter = {
 /**
  * Creates an {@link OutputWriter} rooted at `rootDir`.
  *
+ * Still async with nothing to await: it read the previous run's manifest here
+ * until that was removed, and every call site already awaits it. Keeping the
+ * signature leaves room for setup that does need I/O.
+ *
  * @param rootDir - Output root. Every write must resolve inside it.
- * @param force - Overwrite pre-existing files instead of refusing (`--force`).
  */
-export declare const createOutputWriter: (rootDir: string, force?: boolean) => Promise<OutputWriter>;
+export declare const createOutputWriter: (rootDir: string) => Promise<OutputWriter>;

package/dist/create-output-writer.js

@@ -1,23 +1,8 @@
-import { readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
 import { ensureOutputDir } from "./ensure-output-dir.js";
-const MANIFEST_FILENAME = ".mjst-manifest.json";
-const pathExists = async (path) => stat(path).then(() => true, () => false);
-const readManifest = async (root) => {
-  const raw = await readFile(join(root, MANIFEST_FILENAME), "utf-8").catch(() => void 0);
-  if (raw === void 0)
-    return /* @__PURE__ */ new Set();
-  try {
-    const parsed = JSON.parse(raw);
-    const files = Array.isArray(parsed.files) ? parsed.files : [];
-    return new Set(files.filter((file) => typeof file === "string").map((file) => resolve(root, file)));
-  } catch {
-    return /* @__PURE__ */ new Set();
-  }
-};
-const createOutputWriter = async (rootDir, force = false) => {
+const createOutputWriter = async (rootDir) => {
   const root = resolve(rootDir);
-  const owned = await readManifest(root);
   const staged = [];
   const stamp = `${process.pid}-${Date.now().toString(36)}`;
   const stage = async (relativePath, content) => {
@@ -25,9 +10,6 @@ const createOutputWriter = async (rootDir, force = false) => {
     if (targetPath !== root && !targetPath.startsWith(root + sep)) {
       throw new Error(`Refusing to write "${relativePath}": it resolves outside the output directory ${root}.`);
     }
-    if (!force && !owned.has(targetPath) && await pathExists(targetPath)) {
-      throw new Error(`Refusing to overwrite ${targetPath}: it already exists and was not generated by mjst. Move it aside, choose another output directory, or pass --force to overwrite it.`);
-    }
     const tempPath = `${targetPath}.mjst-${stamp}-${staged.length}.tmp`;
     await ensureOutputDir(dirname(targetPath));
     await writeFile(tempPath, content, "utf-8");
@@ -36,12 +18,6 @@ const createOutputWriter = async (rootDir, force = false) => {
   const commit = async () => {
     for (const file of staged) {
       await rename(file.tempPath, file.targetPath);
-      owned.add(file.targetPath);
-    }
-    if (staged.length > 0) {
-      const files = [...owned].map((path) => relative(root, path)).sort();
-      await writeFile(join(root, MANIFEST_FILENAME), `${JSON.stringify({ version: 1, files }, null, 2)}
-`, "utf-8");
     }
     return staged.map((file) => file.relativePath);
   };

package/dist/emit-examples.d.ts

@@ -11,10 +11,9 @@ export type EmitExamplesOptions = {
     /**
      * The run's writer, rooted at the output destination. Examples used to be
      * written straight to disk with `mkdir` + `writeFile`, which meant the one
-     * output tree mjst emits that skipped the ownership check — a hand-written
-     * `examples/index.ts` was overwritten without a word. Taking the writer instead
-     * of a directory makes that impossible to reintroduce: there is no path here
-     * that does not go through staging, the manifest, and `--force`.
+     * output tree mjst emits that skipped staging entirely — a failure part-way
+     * through left a half-written `examples/` tree behind. Taking the writer
+     * instead of a directory makes that impossible to reintroduce.
      */
     readonly writer: OutputWriter;
     /**

package/dist/emit-message-contracts.d.ts

@@ -38,6 +38,12 @@ export type EmitMessageContractsResult = {
  * accepts no frame in either direction, which is a trap rather than a document.
  * The reasons come back in {@link EmitMessageContractsResult.issues}.
  *
+ * Only payloads are projected. A message's `headers` schema is generated as its
+ * own tree by the parser run, but has no slot in a messages contract — the
+ * contract describes WebSocket frames, and headers are the broker's layer. Each
+ * module says so in its header when the channel declares any, rather than
+ * leaving the omission to be discovered.
+ *
  * The barrel's specifiers are always `.ts`, ignoring `--import-ext`: these
  * modules are the one part of the output `--build` leaves uncompiled (they
  * import the `@amritk/api` peer, and handing tsc an import the output's project

package/dist/emit-message-contracts.js

@@ -11,12 +11,19 @@ ${indent}  `);
 ${entries.join("\n")}
 ${indent}},`;
 };
-const renderChannelModule = (contract, channel) => {
+const renderChannelModule = (contract, channel, headerMessages) => {
   const directions = [
     Object.keys(contract.clientToServer).length > 0 ? renderDirection("clientToServer", contract.clientToServer, "  ") : void 0,
     Object.keys(contract.serverToClient).length > 0 ? renderDirection("serverToClient", contract.serverToClient, "  ") : void 0
   ].filter((entry) => entry !== void 0);
   const address = channel.address !== void 0 && channel.address !== channel.key ? ` (${channel.address})` : "";
+  const headerNote = headerMessages.length === 0 ? [] : [
+    " *",
+    " * Payloads only: a message contract describes WebSocket frames, which carry",
+    " * no headers of their own. These messages declare a headers schema, and its",
+    ` * types were generated alongside the payload's, under \`<message>-headers/\`:`,
+    ` * ${headerMessages.join(", ")}.`
+  ];
   return [
     "/**",
     ` * Message contract for the AsyncAPI channel \`${channel.key}\`${address}.`,
@@ -29,6 +36,7 @@ const renderChannelModule = (contract, channel) => {
     ` * \`{ "${contract.discriminator}": "<key>", ... }\` selects its schema by that key, and the`,
     " * tag is removed before the payload below is validated \u2014 which is why no",
     " * payload here declares it.",
+    ...headerNote,
     " */",
     `import { defineMessages } from '${CONTRACTS_PEER}'`,
     "",
@@ -70,7 +78,8 @@ const emitMessageContracts = async (options) => {
       });
     }
     const filename = `${CONTRACTS_DIR}/${token}.ts`;
-    await writer.stage(filename, bannerPrefix + renderChannelModule({ ...contract, exportName }, channel));
+    const headerMessages = channel.messages.filter((message) => message.headers !== void 0).map(({ name }) => name);
+    await writer.stage(filename, bannerPrefix + renderChannelModule({ ...contract, exportName }, channel, headerMessages));
     files.push(filename);
     barrel.push(`export { ${exportName} } from './${token}.ts'`);
   }

package/dist/help-text.d.ts

@@ -4,4 +4,4 @@
  * documents these flags (config.schema.json) is not shipped in the published
  * package; the help-text test cross-checks that every flag is listed.
  */
-export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,\n                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)\n  --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               Overwrite pre-existing files in the output destination\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n  --unknown-keys <s>    How closed objects are proven free of undeclared keys:\n                        count-keys (default, fastest on Bun) or count-enumerable (fastest on Node)\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,\n                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)\n  --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               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

@@ -25,7 +25,7 @@ Output:
   --message-contracts   Also emit @amritk/api channel contracts under contracts/ (--input asyncapi only)
   --discriminator <p>   Property naming which message a frame is, for --message-contracts (default: type)
   --build               Compile the generated files to .js/.d.ts (implies --import-ext js)
-  --force               Overwrite pre-existing files in the output destination
+  --force               Deprecated; ignored (generated files always overwrite)
   --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)
   --root-type <name>    Root type name for a single --schema run (default: schema title or filename)
@@ -40,6 +40,9 @@ Validation:
   --log-warnings        console.warn on input keys not declared in the schema
   --unknown-keys <s>    How closed objects are proven free of undeclared keys:
                         count-keys (default, fastest on Bun) or count-enumerable (fastest on Node)
+  --formats <f>         String formats the generated validators enforce: "all", or a
+                        comma-separated list (e.g. uuid,date-time,email). Off by default,
+                        which leaves "format" an annotation as JSON Schema reads it.
 
 Reference resolution:
   --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)

package/dist/lint/preset-ruleset.d.ts

@@ -0,0 +1,61 @@
+import type { Ruleset } from '@amritk/lint';
+import type { RulesetDefinition } from '@amritk/lint/types';
+/**
+ * Routing a ruleset to the right builder: which names mean a built-in preset,
+ * whether a ruleset the CLI loaded off disk names one, and how to build with it.
+ * The three live together rather than one per file because they are a single
+ * concern — the name table is the whole question — and because the two entry
+ * points must agree on it: `--ruleset <name>` and a loaded ruleset's `extends`
+ * accept exactly the same preset names.
+ */
+/**
+ * The two built-in presets the CLI can build a ruleset with. They are mutually
+ * exclusive: each preset only knows how to resolve its *own* name inside
+ * `extends`, and each brings a different format registry, so one ruleset cannot
+ * be built with both.
+ */
+export type PresetName = 'asyncapi' | 'oas';
+/**
+ * Every name that resolves to a built-in preset — as `--ruleset <name>` and
+ * inside a ruleset's `extends` — mapped to the preset it names. The aliases
+ * mirror what the presets' own `extends` resolution accepts, including the
+ * legacy Spectral ones.
+ *
+ * A Map, not a record: the key comes straight from user input, and a record
+ * lookup on `constructor` would find `Object.prototype`'s.
+ */
+export declare const PRESET_RULESET_NAMES: ReadonlyMap<string, PresetName>;
+/**
+ * Builds a *runnable* ruleset with a preset's builder. Built rather than handed
+ * to `lintDocument` as data, deliberately: a preset brings its own custom
+ * functions and format detectors, which a definition cannot carry — as data,
+ * every one of its rules would be silently skipped (unknown functions, a
+ * `formats` gate matching nothing).
+ *
+ * With no `definition` this is the bare `--ruleset asyncapi` case: the preset's
+ * recommended rules and nothing else. With one, the caller's ruleset is built by
+ * the preset, whose `extends` resolution knows the preset names and whose
+ * `basePath` keeps the user's relative `extends` and `functions` resolving next
+ * to their own file.
+ *
+ * No `restrictTo` is passed, which matches what the core path does for a
+ * discovered or `--ruleset` file today: the CLI treats a ruleset on the local
+ * disk as trusted configuration. (`--allowed-roots` fences `$ref` resolution in
+ * the *document*, a separate concern.) See the "Trust boundary" section of
+ * `@amritk/lint`'s README.
+ */
+export declare const buildPresetRuleset: (preset: PresetName, definition?: RulesetDefinition, basePath?: string) => Promise<Ruleset>;
+/**
+ * Decides what `lintDocument` should run for a ruleset just loaded off disk —
+ * whether it came from `--ruleset <file>` or `.lint.*` discovery.
+ *
+ * A ruleset that extends a built-in preset has to be built *here*, by that
+ * preset's builder: handed over as a definition, `lintDocument` builds it with
+ * the core `createRuleset`, which knows neither the preset names nor the
+ * functions and format detectors a preset brings. Anything else stays a
+ * definition and takes the core path exactly as it did before.
+ *
+ * @param basePath - The ruleset file's own directory, so its relative `extends` and `functions` still resolve there.
+ * @param label - How to name the ruleset in an error, e.g. its path.
+ */
+export declare const buildLoadedRuleset: (definition: RulesetDefinition, basePath: string, label: string) => Promise<RulesetDefinition | Ruleset>;

package/dist/lint/preset-ruleset.js

@@ -0,0 +1,55 @@
+const PRESET_RULESET_NAMES = /* @__PURE__ */ new Map([
+  ["asyncapi", "asyncapi"],
+  ["loupe:asyncapi", "asyncapi"],
+  ["spectral:asyncapi", "asyncapi"],
+  ["oas", "oas"],
+  ["loupe:oas", "oas"],
+  ["spectral:oas", "oas"]
+]);
+const collectPresets = (definition, into, seen) => {
+  if (typeof definition !== "object" || definition === null)
+    return;
+  if (seen.has(definition))
+    return;
+  seen.add(definition);
+  if (!definition.extends)
+    return;
+  const entries = Array.isArray(definition.extends) ? definition.extends : [definition.extends];
+  for (const entry of entries) {
+    const target = Array.isArray(entry) ? entry[0] : entry;
+    if (typeof target === "string") {
+      const preset = PRESET_RULESET_NAMES.get(target);
+      if (preset && !into.has(preset))
+        into.set(preset, target);
+    } else {
+      collectPresets(target, into, seen);
+    }
+  }
+};
+const findExtendedPreset = (definition, label) => {
+  const found = /* @__PURE__ */ new Map();
+  collectPresets(definition, found, /* @__PURE__ */ new Set());
+  const asyncapi = found.get("asyncapi");
+  const oas = found.get("oas");
+  if (asyncapi && oas) {
+    throw new Error(`Ruleset ${label} extends both built-in presets ("${asyncapi}" and "${oas}"), which cannot be combined: each preset brings its own functions and format detectors, and neither can resolve the other. Extend at most one preset per ruleset, and lint AsyncAPI and OpenAPI documents in separate runs.`);
+  }
+  return asyncapi ? "asyncapi" : oas ? "oas" : void 0;
+};
+const buildPresetRuleset = async (preset, definition, basePath) => {
+  if (preset === "asyncapi") {
+    const { createAsyncApiRuleset } = await import("@amritk/lint/rules/asyncapi");
+    return createAsyncApiRuleset(definition, basePath);
+  }
+  const { createOpenApiRuleset } = await import("@amritk/lint/rules/openapi");
+  return createOpenApiRuleset(definition, basePath);
+};
+const buildLoadedRuleset = async (definition, basePath, label) => {
+  const preset = findExtendedPreset(definition, label);
+  return preset ? await buildPresetRuleset(preset, definition, basePath) : definition;
+};
+export {
+  PRESET_RULESET_NAMES,
+  buildLoadedRuleset,
+  buildPresetRuleset
+};

package/dist/lint/run.js

@@ -4,6 +4,7 @@ import { lintDocument, validateRuleset } from "@amritk/lint";
 import { DiagnosticSeverity } from "@amritk/lint/types";
 import fg from "fast-glob";
 import yargs from "yargs";
+import { buildLoadedRuleset, buildPresetRuleset, PRESET_RULESET_NAMES } from "./preset-ruleset.js";
 import { createLintResolver } from "./resolver.js";
 import { discoverRuleset, loadRuleset } from "./ruleset-loader.js";
 const SEVERITY_BY_NAME = {
@@ -13,16 +14,6 @@ const SEVERITY_BY_NAME = {
   hint: DiagnosticSeverity.Hint
 };
 const SEVERITY_LABEL = ["error", "warning", "info", "hint"];
-const buildAsyncApiPreset = async () => (await import("@amritk/lint/rules/asyncapi")).createAsyncApiRuleset();
-const buildOpenApiPreset = async () => (await import("@amritk/lint/rules/openapi")).createOpenApiRuleset();
-const PRESET_RULESETS = /* @__PURE__ */ new Map([
-  ["asyncapi", buildAsyncApiPreset],
-  ["loupe:asyncapi", buildAsyncApiPreset],
-  ["spectral:asyncapi", buildAsyncApiPreset],
-  ["oas", buildOpenApiPreset],
-  ["loupe:oas", buildOpenApiPreset],
-  ["spectral:oas", buildOpenApiPreset]
-]);
 const formatReport = (findings) => {
   if (findings.length === 0)
     return "No problems found\n";
@@ -136,19 +127,20 @@ Run \`mjst lint --help\` for the supported flags.
       return void 0;
     const definition = await loadRuleset(discovered);
     reportRulesetProblems(definition, discovered);
-    return { definition, basePath: dirname(discovered) };
+    const basePath = dirname(discovered);
+    return { definition: await buildLoadedRuleset(definition, basePath, discovered), basePath };
   };
   let rulesetDefinition;
   let rulesetBasePath;
   if (parsed.ruleset) {
-    const preset = PRESET_RULESETS.get(parsed.ruleset);
+    const preset = PRESET_RULESET_NAMES.get(parsed.ruleset);
     if (preset) {
-      rulesetDefinition = await preset();
+      rulesetDefinition = await buildPresetRuleset(preset);
     } else {
       const definition = await loadRuleset(parsed.ruleset);
-      rulesetDefinition = definition;
       rulesetBasePath = dirname(isAbsolute(parsed.ruleset) ? parsed.ruleset : resolve(process.cwd(), parsed.ruleset));
       reportRulesetProblems(definition, parsed.ruleset);
+      rulesetDefinition = await buildLoadedRuleset(definition, rulesetBasePath, parsed.ruleset);
     }
   }
   const documents = parsed.documents ?? [];

package/dist/load-config.d.ts

@@ -1,10 +1,2 @@
 import type { CliConfig } from './cli-config.js';
-/**
- * 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).
- *
- * Every key is validated up front (see {@link validateConfig}), so the `typeof`
- * guards below are only here to narrow the types for TypeScript — by the time we
- * reach them, nothing can fail them.
- */
 export declare const loadConfig: (configPath: string) => Promise<Partial<CliConfig>>;

package/dist/load-config.js

@@ -7,6 +7,7 @@ const isSourceFormat = (value) => typeof value === "string" && SOURCE_FORMATS.in
 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");
+const isFormatsOption = (value) => value === "all" || Array.isArray(value) && value.every((name) => typeof name === "string");
 const loadConfig = async (configPath) => {
   const absolutePath = resolve(configPath);
   const raw = await readFile(absolutePath, "utf-8").catch((error) => {
@@ -40,6 +41,7 @@ const loadConfig = async (configPath) => {
     ...typeof obj["caseInsensitive"] === "boolean" && { caseInsensitive: obj["caseInsensitive"] },
     ...typeof obj["readonly"] === "boolean" && { readonly: obj["readonly"] },
     ...isUnknownKeysStrategy(obj["unknownKeys"]) && { unknownKeys: obj["unknownKeys"] },
+    ...isFormatsOption(obj["formats"]) && { formats: obj["formats"] },
     ...isHelpersMode(obj["helpers"]) && { helpers: obj["helpers"] },
     ...isImportExt(obj["importExt"]) && { importExt: obj["importExt"] },
     ...typeof obj["rootType"] === "string" && { rootType: obj["rootType"] },

package/dist/parse-cli-args.js

@@ -28,7 +28,8 @@ const VALUE_KEYS = /* @__PURE__ */ new Set([
   "typeSuffix",
   "importExt",
   "rootType",
-  "unknownKeys"
+  "unknownKeys",
+  "formats"
 ]);
 const EXTERNAL_VALUE_KEYS = /* @__PURE__ */ new Set(["config"]);
 const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -103,6 +104,10 @@ const assignValue = (config, key, value) => {
       config.importExt = parsed;
       return true;
     }
+    case "formats": {
+      config.formats = value === "all" ? "all" : value.split(",").map((name) => name.trim()).filter((name) => name !== "");
+      return true;
+    }
     case "unknownKeys": {
       if (!isUnknownKeysStrategy(value)) {
         throw new Error(`Invalid --unknown-keys value "${value}". Expected one of: ${UNKNOWN_KEYS_STRATEGIES.join(", ")}.`);

package/dist/validate-config.d.ts

@@ -1,8 +1,11 @@
 /**
  * The JSON type each config key accepts, mirroring `config.schema.json`.
- * `boolean|string` is `banner`'s `"type": ["boolean", "string"]`.
+ * `boolean|string` is `banner`'s `"type": ["boolean", "string"]`, and
+ * `string|string[]` is `formats`' `"type": ["string", "array"]` — a union the
+ * label spells by its element type rather than by the bare word `array`, since
+ * "expected string|array" tells a reader less than "expected string|string[]".
  */
-type ConfigValueType = 'string' | 'boolean' | 'boolean|string' | 'string[]';
+type ConfigValueType = 'string' | 'boolean' | 'boolean|string' | 'string[]' | 'string|string[]';
 /** One key's contract: its JSON type, plus the closed value set when it has one. */
 type ConfigKeySpec = {
     readonly type: ConfigValueType;

package/dist/validate-config.js

@@ -20,6 +20,7 @@ const CONFIG_KEYS = {
   caseInsensitive: { type: "boolean" },
   readonly: { type: "boolean" },
   unknownKeys: { type: "string", enum: [...UNKNOWN_KEYS_STRATEGIES] },
+  formats: { type: "string|string[]" },
   helpers: { type: "string", enum: ["package", "embedded"] },
   typeSuffix: { type: "string" },
   banner: { type: "boolean|string" },
@@ -48,6 +49,8 @@ const matchesType = (value, type) => {
       return typeof value === "boolean" || typeof value === "string";
     case "string[]":
       return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+    case "string|string[]":
+      return typeof value === "string" || Array.isArray(value) && value.every((e) => typeof e === "string");
   }
 };
 const validateConfig = (parsed, configPath) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.18.0",
+  "version": "0.20.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.1",
-    "@amritk/api": "^0.16.3",
-    "@amritk/asyncapi": "^0.2.0",
-    "@amritk/generate-examples": "^0.8.3",
-    "@amritk/generate-parsers": "^0.21.1",
-    "@amritk/generate-validators": "^0.16.1",
-    "@amritk/helpers": "^0.20.0",
-    "@amritk/lint": "^0.5.3",
+    "@amritk/adapters": "^0.6.2",
+    "@amritk/api": "^0.16.4",
+    "@amritk/asyncapi": "^0.3.0",
+    "@amritk/generate-examples": "^0.8.4",
+    "@amritk/generate-parsers": "^0.23.0",
+    "@amritk/generate-validators": "^0.17.0",
+    "@amritk/helpers": "^0.21.0",
+    "@amritk/lint": "^0.6.0",
     "@amritk/resolve-refs": "^0.7.1",
     "@amritk/yaml": "^0.7.2",
     "fast-glob": "^3.3.2",
@@ -64,7 +64,7 @@
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@amritk/generate-markdown": "^0.6.0",
+    "@amritk/generate-markdown": "^0.7.0",
     "@types/yargs": "^17.0.33"
   }
 }