@amritk/mjst 0.7.14 → 0.7.16

package/README.md

@@ -101,7 +101,6 @@ npx mjst --config ./mjst.config.json
 <th>Property</th>
 <th>CLI Flag</th>
 <th>Type</th>
-<th align="center">Required</th>
 <th align="center">Default</th>
 </tr>
 </thead>
@@ -110,151 +109,136 @@ npx mjst --config ./mjst.config.json
 <td>📄 <code>schema</code></td>
 <td><code>--schema &lt;path&gt;</code></td>
 <td><code>string</code></td>
-<td align="center">—</td>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">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.</td>
+<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>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">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.</td>
+<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">—</td>
 <td align="center"><code>"json"</code></td>
 </tr>
 <tr>
-<td colspan="5">Source format of the schema. 'json' (default) reads a JSON Schema file directly. 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.</td>
+<td colspan="4">Source format of the schema. 'json' (default) reads a JSON Schema file directly. 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></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>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">Which export of the schema module to use when 'input' is not 'json'. Defaults to the default export, or the sole named export when the module has exactly one.</td>
+<td colspan="4">Which export of the schema module to use when 'input' is not 'json'. 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>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">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'.</td>
+<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>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">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'.</td>
+<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">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">Generate only TypeScript type definitions without parser functions. Useful when you only need the type shapes and do not need runtime validation.</td>
+<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>build</code></td>
 <td><code>--build</code></td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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>logWarnings</code></td>
 <td><code>--log-warnings</code></td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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>readonly</code></td>
 <td><code>--readonly</code></td>
 <td><code>boolean</code></td>
-<td align="center">—</td>
 <td align="center"><code>false</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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>helpers</code></td>
 <td><code>--helpers &lt;mode&gt;</code></td>
 <td><code>string</code></td>
-<td align="center">—</td>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">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' if @amritk/helpers resolves from outDir, otherwise 'embedded'.</td>
+<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' if @amritk/helpers resolves from outDir, otherwise 'embedded'.<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">—</td>
 <td align="center"><code>""</code></td>
 </tr>
 <tr>
-<td colspan="5">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>
+<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>config</code></td>
 <td><code>--config &lt;path&gt;</code></td>
 <td><code>string</code></td>
-<td align="center">—</td>
-<td align="center">—</td>
+<td align="center"></td>
 </tr>
 <tr>
-<td colspan="5">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, outDir, outFile, typesOnly, build, logWarnings, strict, readonly, helpers, typeSuffix). CLI flags take precedence over config file values.</td>
+<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, outDir, outFile, typesOnly, build, logWarnings, strict, readonly, helpers, typeSuffix). CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
 </tr>
 </tbody>
 </table>

package/dist/cli.js

@@ -80,9 +80,16 @@ const buildOutput = async (outputDir, tsFiles, typesOnly) => {
         await execFileAsync('npx', ['tsc', '--project', tsconfigPath]);
     }
     catch (error) {
-        // tsc reports the actual errors on stdout; surface them so the user sees
-        // *what* failed instead of a bare "compilation failed".
         const details = error;
+        // A spawn failure (ENOENT) means the *tool* is missing, not that the code is
+        // wrong — pointing the user at "the generated files" would send them hunting
+        // for a compile error that doesn't exist. Report the missing executable.
+        if (details.code === 'ENOENT') {
+            throw new Error('Could not run `npx tsc` to compile the generated files: `npx` (or `tsc`) was not found. ' +
+                'Install TypeScript (e.g. `npm install -D typescript`) or drop --build to skip compilation.');
+        }
+        // Otherwise tsc ran and reported real errors on stdout; surface them so the
+        // user sees *what* failed instead of a bare "compilation failed".
         const output = [details.stdout, details.stderr].filter(Boolean).join('\n').trim();
         throw new Error(`TypeScript compilation failed. Check the generated files for errors.${output ? `\n\n${output}` : ''}`);
     }
@@ -104,6 +111,11 @@ const findJsonSchemas = async (dir) => {
     for (const entry of entries) {
         const full = join(dir, entry.name);
         if (entry.isDirectory()) {
+            // `node_modules` holds dependency schemas that aren't the user's, and
+            // dot-directories (`.git`, `.cache`, ...) hold tooling state — descending
+            // into either pulls in `.json` files the user never meant to generate from.
+            if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                continue;
             results.push(...(await findJsonSchemas(full)));
         }
         else if (entry.isFile() && entry.name.endsWith('.json')) {

package/dist/load-config.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 const SOURCE_FORMATS = ['json', 'typebox', 'zod', 'valibot', 'effect'];
 const isSourceFormat = (value) => typeof value === 'string' && SOURCE_FORMATS.includes(value);
+const isHelpersMode = (value) => value === 'package' || value === 'embedded';
 /**
  * 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).
@@ -27,5 +28,9 @@ export const loadConfig = async (configPath) => {
         ...(typeof obj['strict'] === 'boolean' && { strict: obj['strict'] }),
         ...(typeof obj['stripUnknown'] === 'boolean' && { stripUnknown: obj['stripUnknown'] }),
         ...(typeof obj['readonly'] === 'boolean' && { readonly: obj['readonly'] }),
+        ...(isHelpersMode(obj['helpers']) && { helpers: obj['helpers'] }),
+        ...(typeof obj['typeSuffix'] === 'string' && { typeSuffix: obj['typeSuffix'] }),
+        // `banner` is a boolean toggle or a custom header string, mirroring the CLI flag.
+        ...((typeof obj['banner'] === 'boolean' || typeof obj['banner'] === 'string') && { banner: obj['banner'] }),
     };
 };

package/dist/parse-cli-args.js

@@ -19,6 +19,11 @@ const VALUE_KEYS = new Set([
     'helpers',
     'typeSuffix',
 ]);
+// Recognized flags that don't map into CliConfig because they're consumed
+// earlier in the pipeline (e.g. `--config` is read by `extractConfigPath` to
+// load the config file before flags are overlaid). They still take a value, so
+// list them here to keep the unknown-flag guard from rejecting them.
+const EXTERNAL_VALUE_KEYS = new Set(['config']);
 /** Normalizes a CLI flag name to its camelCase config key so both `--out-dir` and `--outDir` map to `outDir`. */
 const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 const parseHelpersValue = (value) => {
@@ -119,12 +124,19 @@ export const parseCliArgs = (args) => {
             else if (BOOLEAN_KEYS.has(key)) {
                 assignBoolean(config, key, value !== 'false');
             }
-            else {
+            else if (VALUE_KEYS.has(key)) {
                 assignValue(config, key, value);
             }
+            else if (!EXTERNAL_VALUE_KEYS.has(key)) {
+                // An unrecognized flag is almost always a typo (e.g. `--strcit`). Silently
+                // dropping it means the user gets non-strict output while believing they
+                // asked for strict — fail loudly instead of guessing intent.
+                throw new Error(`Unknown flag "--${arg.slice(2, equalsIndex)}".`);
+            }
             continue;
         }
         const key = toCamelCase(arg.slice(2));
+        const flagName = arg.slice(2);
         // --banner: presence alone enables the default message; an immediately
         // following non-flag argument is treated as a custom message string.
         if (key === 'banner') {
@@ -143,14 +155,26 @@ export const parseCliArgs = (args) => {
             assignBoolean(config, key, true);
             continue;
         }
-        // Value flag: consume the next argument when it is not another flag
+        // Value flag: consume the next argument. It must be present and must not be
+        // another flag — `--schema --out-dir dist` means `--schema` lost its value,
+        // which would otherwise silently fall back to a default.
         if (VALUE_KEYS.has(key)) {
             const value = args[i + 1];
-            if (value && !value.startsWith('--')) {
-                assignValue(config, key, value);
-                i++;
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error(`Flag "--${flagName}" expects a value.`);
             }
+            assignValue(config, key, value);
+            i++;
+            continue;
+        }
+        // A flag consumed elsewhere (e.g. `--config`) still swallows its value here.
+        if (EXTERNAL_VALUE_KEYS.has(key)) {
+            const value = args[i + 1];
+            if (value !== undefined && !value.startsWith('--'))
+                i++;
+            continue;
         }
+        throw new Error(`Unknown flag "--${flagName}".`);
     }
     return config;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -41,10 +41,10 @@
     "generate-readme": "bun run ./scripts/generate-readme.ts"
   },
   "dependencies": {
-    "@amritk/adapters": "0.2.12",
-    "@amritk/generate-parsers": "0.12.2",
-    "@amritk/generate-markdown": "0.4.0",
-    "@amritk/helpers": "0.10.1"
+    "@amritk/adapters": "0.2.14",
+    "@amritk/generate-parsers": "0.13.0",
+    "@amritk/generate-markdown": "0.4.1",
+    "@amritk/helpers": "0.10.3"
   },
   "devDependencies": {
     "json-schema-typed": "^8.0.1"