@amritk/mjst 0.19.0 → 0.21.0

package/AI.md

@@ -1,7 +1,8 @@
 # @amritk/mjst (the `mjst` CLI) — notes for AI coding agents
 
 The command-line entry point to mjst: generate TypeScript parsers, validators,
-and types from JSON Schema, plus `lint` and `compile-api` subcommands. Full
+and types from JSON Schema, plus `lint`, `compile-api`, and `markdown`
+subcommands. Full
 reference is [README.md](./README.md); config options are in
 [config.schema.json](./config.schema.json).
 
@@ -9,7 +10,7 @@ reference is [README.md](./README.md); config options are in
 > package ships **only a `mjst` binary** — there are no JS exports. For the
 > programmatic API import `@amritk/generate-parsers` etc. instead.
 
-## The three commands
+## The four commands
 
 ```bash
 # 1. Codegen (default command)
@@ -20,6 +21,10 @@ mjst lint "**/*.{yaml,json}" -r .lint.yaml
 
 # 3. Compile an @amritk/api routes module to a fused, eval-free handler
 mjst compile-api ./routes.ts --out ./dist/handler.ts
+
+# 4. Render a schema as documentation (pages by default, --table for one table)
+mjst markdown ./config.schema.json --out-dir ./docs
+mjst markdown ./config.schema.json --table --readme ./README.md
 ```
 
 ## Codegen gotchas

package/README.md

@@ -21,7 +21,7 @@
 
 Options can be supplied via CLI flags or a JSON config file. **CLI flags always take precedence over config file values.**
 
-It also carries a `lint` subcommand — `mjst lint <files>` — a format-agnostic JSON/YAML style-guide linter powered by [`@amritk/lint`](../lint) (see [Linting](#linting)), and a `compile-api` subcommand — `mjst compile-api <routes-module> --out <file>` — that compiles [`@amritk/api`](../api) route contracts into a production fetch-handler module (see [Compiling an API](#compiling-an-api)).
+It also carries a `lint` subcommand — `mjst lint <files>` — a format-agnostic JSON/YAML style-guide linter powered by [`@amritk/lint`](../lint) (see [Linting](#linting)), a `compile-api` subcommand — `mjst compile-api <routes-module> --out <file>` — that compiles [`@amritk/api`](../api) route contracts into a production fetch-handler module (see [Compiling an API](#compiling-an-api)), and a `markdown` subcommand — `mjst markdown <schema>` — that renders a schema as documentation with [`@amritk/generate-markdown`](../generate-markdown) (see [Generating markdown docs](#generating-markdown-docs)).
 
 ---
 
@@ -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). |
@@ -266,6 +279,330 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 
 ---
 
+## Generating markdown docs
+
+`mjst markdown` renders a JSON Schema as documentation with
+[`@amritk/generate-markdown`](../generate-markdown), so a config's docs cannot
+drift from the schema that validates it. Like `lint` and `compile-api`, it has
+its own flags (and its own `--help`), independent of the generation flags above.
+
+```bash
+# The prose reference: a heading, a type, the description and an example per
+# property, across as many pages as the schema's x-doc keyword declares
+npx mjst markdown ./config.schema.json --out-dir ./docs
+
+# The other shape: one HTML table, spliced into an existing markdown file
+npx mjst markdown ./config.schema.json --table --readme ./README.md
+```
+
+| Flag | Description |
+| --- | --- |
+| `<schema>` | The JSON Schema to document (positional, required). |
+| `--out-dir` | Directory the prose reference pages are written to (default: the current directory). |
+| `--file` | Output path of the index page (default: the schema's `x-doc.file`, then `index.md`). |
+| `--title` | Page title (default: the schema's `title`). |
+| `--language` | Fence language for derived examples and literals (default: `json`). |
+| `--layout` | Default layout for nested properties: `headings` (default), `table`, or `none`. |
+| `--sort` | Property order: `schema` (default) or `alphabetical`. |
+| `--heading-level` | Heading level of the page title, 1-6 (default: `1`). |
+| `--table` | Render the HTML config table instead of the prose pages. |
+| `--readme` | Markdown file the table is spliced into (default: `README.md`). Requires `--table`. |
+
+Under `--table` only the content between `<!-- config-table-start -->
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>CLI Flag</th>
+<th>Type</th>
+<th align="center">Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>📄 <code>schema</code></td>
+<td><code>--schema &lt;path&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Path to the schema to process. With the default 'json' input this is a JSON Schema file that is read and parsed. With any other input format it is a JS/TS module that exports a schema, which is loaded and converted to JSON Schema via the matching adapter. Either 'schema' or 'schemaDir' is required.<br><strong>Examples:</strong> <code>"./schema.json"</code></td>
+</tr>
+<tr>
+<td>🗂️ <code>schemaDir</code></td>
+<td><code>--schema-dir &lt;dir&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Path to a directory of JSON Schema files. When set, the CLI walks the directory recursively, generates parsers for every '*.json' schema it finds, and mirrors the directory layout under outDir (each schema lands in its own subdirectory). The runtime helpers are emitted once into a shared outDir/_helpers/ that every nested parser imports from. Mutually exclusive with 'schema'; when both are present 'schemaDir' wins. Only JSON Schema input is supported in this mode.<br><strong>Examples:</strong> <code>"./schemas"</code></td>
+</tr>
+<tr>
+<td>🔌 <code>input</code></td>
+<td><code>--input &lt;format&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"json"</code></td>
+</tr>
+<tr>
+<td colspan="4">Source format of the schema. 'json' (default) reads a JSON Schema file directly. 'avro' reads an Apache Avro '.avsc' JSON document and converts it, needing no extra library. 'asyncapi' reads an AsyncAPI 2.x/3.0 document (JSON or YAML) and generates from every message payload/headers schema it declares. Any other format loads 'schema' as a module and converts it to JSON Schema with the matching adapter. Supported: 'typebox', 'zod' (zod v4+), 'valibot' (with @valibot/to-json-schema), and 'effect' — each requires the corresponding library installed in your project.<br><strong>Allowed:</strong> <code>"json"</code>, <code>"typebox"</code>, <code>"zod"</code>, <code>"valibot"</code>, <code>"effect"</code>, <code>"avro"</code>, <code>"asyncapi"</code></td>
+</tr>
+<tr>
+<td>📦 <code>export</code></td>
+<td><code>--export &lt;name&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Which export of the schema module to use when 'input' names a module format (anything but 'json', 'avro', and 'asyncapi', which are read as data). Defaults to the default export, or the sole named export when the module has exactly one.</td>
+</tr>
+<tr>
+<td>📁 <code>outDir</code></td>
+<td><code>--out-dir &lt;dir&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Output directory for generated TypeScript files. The directory is created automatically if it does not exist. Subdirectories are created as needed when a generated file includes a nested path. Mutually exclusive with 'outFile'.<br><strong>Examples:</strong> <code>"./generated"</code></td>
+</tr>
+<tr>
+<td>📄 <code>outFile</code></td>
+<td><code>--out-file &lt;file&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Output everything to a single TypeScript file instead of a directory. Every generated definition is concatenated into one self-contained file and the cross-file imports are dropped. Mutually exclusive with 'outDir'. Currently supported only together with 'typesOnly'.<br><strong>Examples:</strong> <code>"./generated/schema.ts"</code></td>
+</tr>
+<tr>
+<td>🏷️ <code>typesOnly</code></td>
+<td><code>--types-only</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<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>messageContracts</code></td>
+<td><code>--message-contracts</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Also emit a @amritk/api channel contract per AsyncAPI channel into a contracts/ subdirectory: one defineMessages({ ... }) module naming every message that channel carries — keyed by the value its discriminator property carries on the wire, with that property stripped out of each payload because the runtime removes it before validating — plus a barrel re-exporting them. Requires input 'asyncapi', which is the only input that has channels and operations to project from. Incompatible with typesOnly: a contract is a runtime value, not a type. The generated modules import @amritk/api, which the consuming project must install; it is not a dependency of the generated parsers.</td>
+</tr>
+<tr>
+<td>🏷️ <code>discriminator</code></td>
+<td><code>--discriminator &lt;prop&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"type"</code></td>
+</tr>
+<tr>
+<td colspan="4">Property name that says which message a frame is, for the contracts messageContracts emits. Defaults to 'type', matching @amritk/api. A channel that declares its own with 'x-mjst': { 'discriminator': '...' } keeps it — one flag covers a whole run, and a run may span channels that disagree. Only meaningful together with messageContracts.<br><strong>Examples:</strong> <code>"event"</code></td>
+</tr>
+<tr>
+<td>🔨 <code>build</code></td>
+<td><code>--build</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Compile the generated TypeScript files to .js and .d.ts output. A temporary tsconfig is written to the output directory, tsc is invoked, and the intermediate .ts source files are removed when compilation succeeds.</td>
+</tr>
+<tr>
+<td>💥 <code>force</code></td>
+<td><code>--force</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<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>
+<td><code>--log-warnings</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime.</td>
+</tr>
+<tr>
+<td>🚫 <code>strict</code></td>
+<td><code>--strict</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. When a schema sets additionalProperties: false, undeclared keys throw too; otherwise they are still allowed.</td>
+</tr>
+<tr>
+<td>🧹 <code>stripUnknown</code></td>
+<td><code>--strip-unknown</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Build each parser's result from the schema's declared properties only, silently dropping undeclared input keys at every nesting level (zod's .strip()). Extras are never a validation error, so this composes with strict (which still throws on wrong types and missing required properties) and yields to additionalProperties: false, which rejects rather than strips in strict mode.</td>
+</tr>
+<tr>
+<td>🔡 <code>caseInsensitive</code></td>
+<td><code>--case-insensitive</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Normalize a mis-cased string to the exact casing of a declared enum/const member it matches case-insensitively (e.g. hElLo → hello) instead of coercing to the default. Coerce mode only — strict parsers still reject a casing mismatch. Correctly-cased input keeps the exact-match fast path, so the hot path is unaffected.</td>
+</tr>
+<tr>
+<td>🔒 <code>readonly</code></td>
+<td><code>--readonly</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Emit every property, array, and record in the generated type definitions as readonly, producing deeply immutable types. Affects type definitions only; the generated parsers still build and return plain objects.</td>
+</tr>
+<tr>
+<td>🔢 <code>unknownKeys</code></td>
+<td><code>--unknown-keys &lt;strategy&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>"count-keys"</code></td>
+</tr>
+<tr>
+<td colspan="4">How generated fast paths (parsers and validators alike) prove a closed object — additionalProperties: false, or a stripUnknown build — carries no undeclared key. 'count-keys' compares Object.keys(obj).length and is the faster form on JavaScriptCore (Bun), where a for…in over a non-extensible object takes the engine's slow path and halves strict-parse throughput. 'count-enumerable' counts with for…in and allocates nothing; it was the faster form on Node 22, but on Node 26 'count-keys' ties or wins there too. Keep the default unless you are pinned to an older V8 and have measured your own shapes; the generated code never detects its runtime.<br><strong>Allowed:</strong> <code>"count-enumerable"</code>, <code>"count-keys"</code></td>
+</tr>
+<tr>
+<td>🧪 <code>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>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Controls how generated parsers reference their runtime helpers. 'package' emits imports from @amritk/helpers (requires it to be installed in the consumer project). 'embedded' ships the helper source under outDir/_helpers/ so the output is self-contained. When omitted, the CLI auto-detects: it picks 'package' only when @amritk/helpers is a declared dependency (dependencies/devDependencies) of the nearest package.json above outDir, otherwise 'embedded'. Requiring a declaration (rather than mere resolvability) keeps auto-detected 'package' output portable across pnpm/isolated installs, where an undeclared transitive @amritk/helpers is not reachable at runtime.<br><strong>Allowed:</strong> <code>"package"</code>, <code>"embedded"</code></td>
+</tr>
+<tr>
+<td>🏷️ <code>typeSuffix</code></td>
+<td><code>--type-suffix &lt;suffix&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"><code>""</code></td>
+</tr>
+<tr>
+<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>
+<td align="center"><code>"ts"</code></td>
+</tr>
+<tr>
+<td colspan="4">Extension emitted on every relative import specifier in the generated output (cross-file $ref imports, the index barrel, and embedded-helper imports). 'ts' (default) emits the literal on-disk paths so the generated .ts sources load directly under Bun, Node's type stripping (Node 22.6+ with --experimental-strip-types, unflagged from 22.18/23), and tsc when the consumer sets allowImportingTsExtensions — no build step required. 'js' is the standard TS NodeNext form ('./x.js' resolving to a sibling x.ts) for output you compile; it is selected automatically under 'build' since tsc refuses to emit from .ts specifiers. Passing --import-ext ts together with --build is an error.<br><strong>Allowed:</strong> <code>"js"</code>, <code>"ts"</code></td>
+</tr>
+<tr>
+<td>🌱 <code>rootType</code></td>
+<td><code>--root-type &lt;name&gt;</code></td>
+<td><code>string</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Name for the root type of a single --schema run (e.g. 'Program' yields parseProgram / validateProgram). 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>allowedRoots</code></td>
+<td><code>--allowed-roots &lt;dirs&gt;</code></td>
+<td><code>array</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Extra directories a local (cross-file) $ref may resolve into. By default a local $ref is confined to the schema's own directory, so '{"$ref": "../../../secrets.env"}' (or an absolute path) reads nothing. List a root here for the ordinary split-spec layout where v1/api.json refers to a shared common/user.json one level up. The schema's own directory is always allowed, so these roots widen the default rather than replacing it, and a $ref that still lands outside every root is refused. Accepts a comma-separated list or the flag repeated; relative entries resolve against the current working directory, from a config file as well as from the flag.<br><strong>Examples:</strong> <code>["./specs"]</code></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, input, export, outDir, outFile, typesOnly, validators, examples, build, force, logWarnings, strict, stripUnknown, caseInsensitive, readonly, unknownKeys, helpers, typeSuffix, banner, importExt, rootType, resolveRemote, allowedHosts, allowPrivateHosts, allowedRoots) and are validated: an unknown key or a wrong value type fails the run instead of being ignored. CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
+</tr>
+</tbody>
+</table>
+<!-- config-table-end -->` is replaced; a file that exists without both markers
+is left untouched and the run fails, rather than clobbering hand-written prose.
+The prose pages have no such deal — the generator owns them and overwrites them
+wholesale. The table and page flags are mutually exclusive: passing a page flag
+with `--table` is a usage error rather than a silently ignored option.
+
+The exit code is `0` on success, `1` when generation fails (malformed schema, a
+readme without markers, a page declaration the schema contradicts), and `2` on a
+usage error. Run `mjst markdown --help` for details.
+
+---
+
 ## Configuration reference
 
 <!-- config-table-start -->
@@ -451,6 +788,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

@@ -129,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

@@ -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;
@@ -368,6 +368,15 @@ const run = async () => {
       process.stderr.write(result.stderr);
     process.exit(result.code);
   }
+  if (args[0] === "markdown") {
+    const { run: markdownRun } = await import("./markdown/run.js");
+    const result = await markdownRun(args.slice(1));
+    if (result.stdout)
+      process.stdout.write(result.stdout);
+    if (result.stderr)
+      process.stderr.write(result.stderr);
+    process.exit(result.code);
+  }
   const metaRequest = parseMetaRequest(args);
   if (metaRequest === "version") {
     console.log(await readVersion());

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               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\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n  mjst markdown <schema> --out-dir <dir>  Generate markdown documentation from a JSON Schema\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect, avro,\n                        or asyncapi (an AsyncAPI 2.x/3.0 document, JSON or YAML)\n  --export <name>       Which export of the schema module to use when --input names a module format\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators 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

@@ -8,6 +8,7 @@ Usage:
 Subcommands (each with its own flags and --help):
   mjst lint <files>                       Lint JSON/YAML documents against a ruleset
   mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module
+  mjst markdown <schema> --out-dir <dir>  Generate markdown documentation from a JSON Schema
 
 Input:
   --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set
@@ -40,6 +41,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/markdown/help-text.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Usage text for `mjst markdown --help`. Hand-written like the top-level
+ * HELP_TEXT: the flag list is small and stable, and the test cross-checks that
+ * every flag is listed.
+ */
+export declare const MARKDOWN_HELP_TEXT = "mjst markdown \u2014 generate markdown documentation from a JSON Schema\n\nUsage:\n  mjst markdown <schema> --out-dir <dir> [options]\n  mjst markdown <schema> --table --readme <file>\n\nTwo shapes come out of the same schema. By default it writes the prose\nreference \u2014 a heading, a type, the description and an example per property,\nacross as many pages as the schema's x-doc keyword declares. With --table it\nrenders one HTML table instead and splices it into an existing markdown file\nbetween <!-- config-table-start --> and <!-- config-table-end -->, leaving the\nrest of that file alone.\n\nProse reference options:\n  --out-dir <dir>      Directory the pages are written to (default: the current directory)\n  --file <path>        Output path of the index page (default: the schema's x-doc.file, then index.md)\n  --title <text>       Page title (default: the schema's title)\n  --language <lang>    Fence language for derived examples and literals (default: json)\n  --layout <mode>      Default layout for nested properties: headings (default), table, or none\n  --sort <order>       Property order: schema (default) or alphabetical\n  --heading-level <n>  Heading level of the page title, 1-6 (default: 1)\n\nTable options:\n  --table              Render the HTML config table instead of the prose pages\n  --readme <path>      Markdown file the table is spliced into (default: README.md)\n\nMisc:\n  --help, -h           Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";

package/dist/markdown/help-text.js

@@ -0,0 +1,34 @@
+const MARKDOWN_HELP_TEXT = `mjst markdown \u2014 generate markdown documentation from a JSON Schema
+
+Usage:
+  mjst markdown <schema> --out-dir <dir> [options]
+  mjst markdown <schema> --table --readme <file>
+
+Two shapes come out of the same schema. By default it writes the prose
+reference \u2014 a heading, a type, the description and an example per property,
+across as many pages as the schema's x-doc keyword declares. With --table it
+renders one HTML table instead and splices it into an existing markdown file
+between <!-- config-table-start --> and <!-- config-table-end -->, leaving the
+rest of that file alone.
+
+Prose reference options:
+  --out-dir <dir>      Directory the pages are written to (default: the current directory)
+  --file <path>        Output path of the index page (default: the schema's x-doc.file, then index.md)
+  --title <text>       Page title (default: the schema's title)
+  --language <lang>    Fence language for derived examples and literals (default: json)
+  --layout <mode>      Default layout for nested properties: headings (default), table, or none
+  --sort <order>       Property order: schema (default) or alphabetical
+  --heading-level <n>  Heading level of the page title, 1-6 (default: 1)
+
+Table options:
+  --table              Render the HTML config table instead of the prose pages
+  --readme <path>      Markdown file the table is spliced into (default: README.md)
+
+Misc:
+  --help, -h           Print this help
+
+Docs: https://github.com/amritk/mjst/tree/main/packages/cli#readme
+`;
+export {
+  MARKDOWN_HELP_TEXT
+};

package/dist/markdown/parse-markdown-args.d.ts

@@ -0,0 +1,34 @@
+import type { DocLayout, DocSort } from '@amritk/generate-markdown';
+/** The flags and positional the `markdown` subcommand understands. */
+export type MarkdownArgs = {
+    /** Path to the JSON Schema to document (the sole positional). */
+    schema?: string;
+    /** Directory the prose reference pages are written to (`--out-dir`). */
+    outDir?: string;
+    /** Output path of the index page (`--file`). */
+    file?: string;
+    /** Page title override (`--title`). */
+    title?: string;
+    /** Fence language for derived examples (`--language`). */
+    language?: string;
+    /** Default layout for nested properties (`--layout`). */
+    layout?: DocLayout;
+    /** Property order (`--sort`). */
+    sort?: DocSort;
+    /** Heading level of the page title (`--heading-level`). */
+    headingLevel?: number;
+    /** True when `--table` was passed: render the HTML table instead of the pages. */
+    table?: boolean;
+    /** Markdown file the table is spliced into (`--readme`). */
+    readme?: string;
+    /** True when `--help`/`-h` was passed. */
+    help?: boolean;
+};
+/**
+ * Parses the `markdown` argv into a typed args object. Mirrors the other
+ * subcommand parsers: kebab-case and camelCase flag spellings, both
+ * `--flag value` and `--flag=value`, and a loud error on unknown flags so a
+ * typo cannot silently drop an option. Throws on usage errors; the caller turns
+ * that into the exit-code-2 path.
+ */
+export declare const parseMarkdownArgs: (argv: readonly string[]) => MarkdownArgs;

package/dist/markdown/parse-markdown-args.js

@@ -0,0 +1,97 @@
+const VALUE_KEYS = /* @__PURE__ */ new Set(["outDir", "file", "title", "language", "layout", "sort", "headingLevel", "readme"]);
+const BOOLEAN_KEYS = /* @__PURE__ */ new Set(["table"]);
+const LAYOUTS = ["headings", "table", "none"];
+const SORTS = ["schema", "alphabetical"];
+const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const parseChoice = (flag, value, choices) => {
+  const match = choices.find((choice) => choice === value);
+  if (match === void 0) {
+    throw new Error(`Invalid --${flag} value "${value}". Expected one of: ${choices.join(", ")}.`);
+  }
+  return match;
+};
+const parseHeadingLevel = (value) => {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 6) {
+    throw new Error(`Invalid --heading-level value "${value}". Expected an integer from 1 to 6.`);
+  }
+  return parsed;
+};
+const assignValue = (args, key, value) => {
+  switch (key) {
+    case "outDir":
+      args.outDir = value;
+      return;
+    case "file":
+      args.file = value;
+      return;
+    case "title":
+      args.title = value;
+      return;
+    case "language":
+      args.language = value;
+      return;
+    case "layout":
+      args.layout = parseChoice("layout", value, LAYOUTS);
+      return;
+    case "sort":
+      args.sort = parseChoice("sort", value, SORTS);
+      return;
+    case "headingLevel":
+      args.headingLevel = parseHeadingLevel(value);
+      return;
+    case "readme":
+      args.readme = value;
+      return;
+    default:
+      throw new Error(`Unknown flag "--${key}".`);
+  }
+};
+const parseMarkdownArgs = (argv) => {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === void 0)
+      continue;
+    if (arg === "--help" || arg === "-h") {
+      args.help = true;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      if (args.schema !== void 0) {
+        throw new Error(`Unexpected argument "${arg}". markdown takes a single schema path.`);
+      }
+      args.schema = arg;
+      continue;
+    }
+    const equalsIndex = arg.indexOf("=");
+    if (equalsIndex !== -1) {
+      const name = arg.slice(2, equalsIndex);
+      const key2 = toCamelCase(name);
+      if (BOOLEAN_KEYS.has(key2))
+        throw new Error(`Flag "--${name}" is a switch and takes no value.`);
+      if (!VALUE_KEYS.has(key2))
+        throw new Error(`Unknown flag "--${name}".`);
+      assignValue(args, key2, arg.slice(equalsIndex + 1));
+      continue;
+    }
+    const flagName = arg.slice(2);
+    const key = toCamelCase(flagName);
+    if (BOOLEAN_KEYS.has(key)) {
+      args.table = true;
+      continue;
+    }
+    if (!VALUE_KEYS.has(key))
+      throw new Error(`Unknown flag "--${flagName}".`);
+    const value = argv[i + 1];
+    if (value === void 0 || value.startsWith("--")) {
+      throw new Error(`Flag "--${flagName}" expects a value.`);
+    }
+    assignValue(args, key, value);
+    i++;
+  }
+  return args;
+};
+export {
+  parseMarkdownArgs
+};

package/dist/markdown/run.d.ts

@@ -0,0 +1,9 @@
+import type { RunResult } from '../lint/run.js';
+/**
+ * Runs `mjst markdown` over `argv`: renders a JSON Schema as documentation,
+ * either as the prose reference pages (the default) or as the HTML config table
+ * spliced into an existing markdown file (`--table`). Returns the exit code and
+ * the text it would print (rather than writing to the process streams) so tests
+ * can drive it in-process — the same shape as the other subcommands' `run`.
+ */
+export declare const run: (argv: string[]) => Promise<RunResult>;

package/dist/markdown/run.js

@@ -0,0 +1,72 @@
+import { relative, resolve } from "node:path";
+import { generateConfigTable, generateDocs } from "@amritk/generate-markdown";
+import { MARKDOWN_HELP_TEXT } from "./help-text.js";
+import { parseMarkdownArgs } from "./parse-markdown-args.js";
+const usageError = (message) => ({ code: 2, stdout: "", stderr: `Error: ${message}
+` });
+const failure = (message) => ({ code: 1, stdout: "", stderr: `Error: ${message}
+` });
+const PAGE_FLAGS = ["outDir", "file", "title", "language", "layout", "sort", "headingLevel"];
+const run = async (argv) => {
+  let args;
+  try {
+    args = parseMarkdownArgs(argv);
+  } catch (error) {
+    return usageError(error instanceof Error ? error.message : String(error));
+  }
+  if (args.help || argv.length === 0) {
+    return { code: 0, stdout: MARKDOWN_HELP_TEXT, stderr: "" };
+  }
+  if (args.schema === void 0) {
+    return usageError("A schema path is required. Usage: mjst markdown <schema> --out-dir <dir>");
+  }
+  if (args.table) {
+    const stray = PAGE_FLAGS.filter((flag) => args[flag] !== void 0);
+    if (stray.length > 0) {
+      return usageError(`--table renders one table into a single file, so it cannot be combined with ${stray.map((flag) => `--${flag.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`).join(", ")}. Drop --table to generate the prose reference pages.`);
+    }
+  } else if (args.readme !== void 0) {
+    return usageError("--readme names the file the config table is spliced into, so it requires --table.");
+  }
+  const schemaPath = resolve(args.schema);
+  const outDir = resolve(args.outDir ?? ".");
+  if (args.table) {
+    let readmePath;
+    try {
+      readmePath = await generateConfigTable({
+        schemaPath,
+        ...args.readme !== void 0 ? { readmePath: resolve(args.readme) } : {}
+      });
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    return { code: 0, stdout: `Generated config table: ${relative(process.cwd(), readmePath)}
+`, stderr: "" };
+  }
+  const options = {
+    schemaPath,
+    outDir,
+    file: args.file,
+    title: args.title,
+    language: args.language,
+    layout: args.layout,
+    sort: args.sort,
+    headingLevel: args.headingLevel
+  };
+  let files;
+  try {
+    files = await generateDocs(options);
+  } catch (error) {
+    return failure(error instanceof Error ? error.message : String(error));
+  }
+  const stdout = [
+    ...files.map((file) => `Generated: ${relative(process.cwd(), resolve(outDir, file.filename))}`),
+    "",
+    `Total files generated: ${files.length}`,
+    ""
+  ].join("\n");
+  return { code: 0, stdout, stderr: "" };
+};
+export {
+  run
+};

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.19.0",
+  "version": "0.21.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,14 +49,15 @@
     "./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.22.0",
-    "@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-markdown": "^0.8.0",
+    "@amritk/generate-parsers": "^0.23.0",
+    "@amritk/generate-validators": "^0.17.0",
+    "@amritk/helpers": "^0.21.0",
+    "@amritk/lint": "^0.6.0",
     "@amritk/resolve-refs": "^0.7.1",
     "@amritk/yaml": "^0.7.2",
     "fast-glob": "^3.3.2",
@@ -64,7 +65,6 @@
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@amritk/generate-markdown": "^0.6.0",
     "@types/yargs": "^17.0.33"
   }
 }