@amritk/mjst 0.24.0 → 0.25.1

package/README.md

@@ -304,7 +304,7 @@ 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
+# property, across as many pages as the schema's x-mjst keyword declares
 npx mjst markdown ./config.schema.json --out-dir ./docs
 
 # The other shape: one HTML table, spliced into an existing markdown file
@@ -315,7 +315,7 @@ npx mjst markdown ./config.schema.json --table --readme ./README.md
 | --- | --- |
 | `<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`). |
+| `--file` | Output path of the index page (default: the schema's `x-mjst.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`. |
@@ -324,7 +324,7 @@ npx mjst markdown ./config.schema.json --table --readme ./README.md
 | `--type-label` | Whether every property heading gets its **Type:** line: `auto` (default) or `never`. Under `never` an enum lists its **Allowed values:** instead, since the label was the only other place they appeared. |
 | `--type-column` | When a property table renders its **Type** column: `auto` (default — only when a row fills it with something a reader could act on), `always`, or `never`. |
 | `--default-column` | When a property table renders its **Default** column: `auto` (default), `always`, or `never`. |
-| `--required-style` | How a property table says which properties are required: `marker` (default — `_required_` beside the name) or `column` (a **Required** column). |
+| `--required-style` | How a property table says which properties are required: `column` (default — a **Required** column), or any other text as a suffix right after a required name, as markdown or inline HTML — e.g. `"*"`, `" _required_"` or `"<br><sub><i>required</i></sub>"`. Appended exactly as written, so include a leading space if you want one. |
 | `--required-first` | List the required properties at the top of every table, the rest under them. |
 | `--table` | Render the HTML config table instead of the prose pages. |
 | `--readme` | Markdown file the table is spliced into (default: `README.md`). Requires `--table`. |

package/dist/cli.js

@@ -3,21 +3,14 @@ import { execFile } from "node:child_process";
 import { readdir, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
-import { extractAsyncApi, listMessageSchemas } from "@amritk/asyncapi";
 import { deriveRootTypeName } from "@amritk/helpers/derive-root-type-name";
 const execFileAsync = promisify(execFile);
-import { combineGeneratedFiles } from "./combine-files.js";
 import { createOutputWriter } from "./create-output-writer.js";
 import { detectHelpersMode } from "./detect-helpers-mode.js";
-import { emitExamples } from "./emit-examples.js";
-import { CONTRACTS_DIR, CONTRACTS_PEER, emitMessageContracts } from "./emit-message-contracts.js";
 import { ensureOutputDir } from "./ensure-output-dir.js";
-import { generateFiles } from "./generate-files.js";
 import { HELP_TEXT } from "./help-text.js";
 import { isDependencyDeclared } from "./is-dependency-declared.js";
-import { loadAsyncApiDocument } from "./load-asyncapi-document.js";
 import { loadConfig } from "./load-config.js";
-import { loadSchema } from "./load-schema.js";
 import { parseCliArgs } from "./parse-cli-args.js";
 import { parseMetaRequest } from "./parse-meta-request.js";
 import { readVersion } from "./read-version.js";
@@ -32,6 +25,10 @@ const resolveHelpersMode = (config, outputDir) => {
   }
   return helpersMode;
 };
+const loadGenerationPipeline = async () => {
+  const [{ loadSchema }, { generateFiles }] = await Promise.all([import("./load-schema.js"), import("./generate-files.js")]);
+  return { loadSchema, generateFiles };
+};
 const extractConfigPath = (args) => {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -65,6 +62,7 @@ const commitOrDiscard = async (writer, stageAll) => {
   return writer.commit();
 };
 const runExamples = async (config, outputDir, tasks) => {
+  const { emitExamples } = await import("./emit-examples.js");
   const writer = await createOutputWriter(outputDir);
   const written = await commitOrDiscard(writer, async () => {
     for (const task of tasks) {
@@ -137,6 +135,7 @@ const findJsonSchemas = async (dir) => {
   return results;
 };
 const runSingle = async (config, schemaPath, outputDir) => {
+  const { loadSchema, generateFiles } = await loadGenerationPipeline();
   const schema = await loadSchema(config, schemaPath);
   await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
@@ -164,6 +163,8 @@ Total files generated: ${written.length}`);
   }
 };
 const runSingleFile = async (config, schemaPath, outFilePath) => {
+  const { loadSchema, generateFiles } = await loadGenerationPipeline();
+  const { combineGeneratedFiles } = await import("./combine-files.js");
   const schema = await loadSchema(config, schemaPath);
   const outputDir = dirname(outFilePath);
   await ensureOutputDir(outputDir);
@@ -194,6 +195,7 @@ const runRecursive = async (config, schemaDir, outputDir) => {
     process.exit(1);
   }
   const schemaFiles = await findJsonSchemas(schemaDir);
+  const { loadSchema, generateFiles } = await loadGenerationPipeline();
   if (schemaFiles.length === 0) {
     console.error(`Error: no .json schema files found under ${schemaDir}.`);
     process.exit(1);
@@ -245,12 +247,19 @@ ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
 Total files generated: ${writtenTsFiles.length}`);
   }
 };
-const reportContractsPeer = (outputDir) => {
-  if (isDependencyDeclared(outputDir, CONTRACTS_PEER))
+const reportContractsPeer = (outputDir, peer) => {
+  if (isDependencyDeclared(outputDir, peer))
     return;
-  console.log(`Tip: the generated contracts import ${CONTRACTS_PEER}, which is not a declared dependency of the project at ${outputDir}. Install it there (it is a peer of the generated code, not of the mjst CLI).`);
+  console.log(`Tip: the generated contracts import ${peer}, which is not a declared dependency of the project at ${outputDir}. Install it there (it is a peer of the generated code, not of the mjst CLI).`);
 };
 const runAsyncApi = async (config, documentPath, outputDir) => {
+  const [{ loadAsyncApiDocument }, { extractAsyncApi, listMessageSchemas }, { generateFiles }, contractsModule] = await Promise.all([
+    import("./load-asyncapi-document.js"),
+    import("@amritk/asyncapi"),
+    import("./generate-files.js"),
+    import("./emit-message-contracts.js")
+  ]);
+  const { CONTRACTS_DIR, CONTRACTS_PEER, emitMessageContracts } = contractsModule;
   const document = await loadAsyncApiDocument(config, documentPath);
   const model = extractAsyncApi(document);
   const schemas = listMessageSchemas(model);
@@ -323,7 +332,7 @@ ${subDir}/ (root type: ${rootTypeName})`);
   if (config.messageContracts) {
     console.log(`
 Message contracts: ${contractMessageCount} message(s) across ${contractChannelCount} channel(s)`);
-    reportContractsPeer(outputDir);
+    reportContractsPeer(outputDir, CONTRACTS_PEER);
   }
   if (exampleTasks.length > 0) {
     await runExamples(config, outputDir, exampleTasks);

package/dist/markdown/help-text.d.ts

@@ -3,4 +3,4 @@
  * 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  --type-label <when>  Give every property heading its Type: line: auto (default) or\n                       never (an enum then lists its allowed values instead)\n\nProperty table options (the root x-doc.table, for every table on every page):\n  --type-column <when>     Render the Type column: auto (default), always, or never\n  --default-column <when>  Render the Default column: auto (default), always, or never\n  --required-style <how>   Say which properties are required: marker (default, beside\n                           the name) or column (a Required column)\n  --required-first         List the required properties at the top of every table\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";
+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-mjst 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-mjst.markdown.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  --type-label <when>  Give every property heading its Type: line: auto (default) or\n                       never (an enum then lists its allowed values instead)\n\nProperty table options (the root x-mjst.markdown.table, for every table on every page):\n  --type-column <when>     Render the Type column: auto (default), always, or never\n  --default-column <when>  Render the Default column: auto (default), always, or never\n  --required-style <how>   Say which properties are required: column (default, a\n                           Required column), or any other text as a suffix right\n                           after a required name, as markdown or inline HTML: \"*\",\n                           \" _required_\", \"<br><sub>required</sub>\"\n  --required-first         List the required properties at the top of every table\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

@@ -6,14 +6,14 @@ Usage:
 
 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
+across as many pages as the schema's x-mjst 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)
+  --file <path>        Output path of the index page (default: the schema's x-mjst.markdown.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
@@ -22,11 +22,13 @@ Prose reference options:
   --type-label <when>  Give every property heading its Type: line: auto (default) or
                        never (an enum then lists its allowed values instead)
 
-Property table options (the root x-doc.table, for every table on every page):
+Property table options (the root x-mjst.markdown.table, for every table on every page):
   --type-column <when>     Render the Type column: auto (default), always, or never
   --default-column <when>  Render the Default column: auto (default), always, or never
-  --required-style <how>   Say which properties are required: marker (default, beside
-                           the name) or column (a Required column)
+  --required-style <how>   Say which properties are required: column (default, a
+                           Required column), or any other text as a suffix right
+                           after a required name, as markdown or inline HTML: "*",
+                           " _required_", "<br><sub>required</sub>"
   --required-first         List the required properties at the top of every table
 
 Table options:

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

@@ -23,7 +23,10 @@ export type MarkdownArgs = {
     typeColumn?: DocTableColumn;
     /** When property tables render their Default column (`--default-column`). */
     defaultColumn?: DocTableColumn;
-    /** How property tables say which properties are required (`--required-style`). */
+    /**
+     * How property tables say which properties are required (`--required-style`):
+     * `column`, or any other text as a suffix after a required name.
+     */
     requiredStyle?: DocTableRequired;
     /** True when `--required-first` was passed: required properties head every table. */
     requiredFirst?: boolean;

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

@@ -17,7 +17,6 @@ const LAYOUTS = ["headings", "table", "none"];
 const SORTS = ["schema", "alphabetical"];
 const HEADING_TYPES = ["auto", "never"];
 const TABLE_COLUMNS = ["auto", "always", "never"];
-const REQUIRED_STYLES = ["marker", "column"];
 const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 const parseChoice = (flag, value, choices) => {
   const match = choices.find((choice) => choice === value);
@@ -65,8 +64,10 @@ const assignValue = (args, key, value) => {
     case "defaultColumn":
       args.defaultColumn = parseChoice("default-column", value, TABLE_COLUMNS);
       return;
+    // Free text on purpose: anything but `column` is the suffix itself, so
+    // there is no typo to catch — `*` is as valid as ` _required_`.
     case "requiredStyle":
-      args.requiredStyle = parseChoice("required-style", value, REQUIRED_STYLES);
+      args.requiredStyle = value;
       return;
     case "readme":
       args.readme = value;

package/dist/markdown/run.js

@@ -66,7 +66,7 @@ const run = async (argv) => {
     sort: args.sort,
     headingLevel: args.headingLevel,
     // Always passed: every member is optional, so the schema's own
-    // `x-doc.table` still decides whatever the flags left alone.
+    // `x-mjst.markdown.table` still decides whatever the flags left alone.
     table: {
       type: args.typeColumn,
       default: args.defaultColumn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -49,16 +49,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@amritk/adapters": "^0.6.5",
-    "@amritk/api": "^0.16.5",
-    "@amritk/asyncapi": "^0.3.3",
-    "@amritk/generate-examples": "^0.8.7",
-    "@amritk/generate-markdown": "^0.10.0",
-    "@amritk/helpers": "^0.23.1",
-    "@amritk/lint": "^0.6.1",
-    "@amritk/validation": "^0.3.0",
-    "@amritk/resolve-refs": "^0.7.1",
-    "@amritk/yaml": "^0.7.2",
+    "@amritk/adapters": "^0.6.7",
+    "@amritk/api": "^0.16.6",
+    "@amritk/asyncapi": "^0.3.5",
+    "@amritk/generate-examples": "^0.8.9",
+    "@amritk/generate-markdown": "^0.11.0",
+    "@amritk/helpers": "^0.23.3",
+    "@amritk/lint": "^0.6.2",
+    "@amritk/validation": "^0.3.2",
+    "@amritk/resolve-refs": "^0.8.0",
+    "@amritk/yaml": "^0.7.3",
     "fast-glob": "^3.3.2",
     "json-schema-typed": "^8.0.1",
     "yargs": "^17.7.2"