@amritk/mjst 0.7.16 → 0.9.0

package/README.md

@@ -9,7 +9,7 @@
 ![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square) 
 ![JSON Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-f97316?style=flat-square) 
 ![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white) 
-![vibe coded](https://img.shields.io/badge/vibe%20coded-24%25-a855f7?style=flat-square)
+![vibe coded](https://img.shields.io/badge/vibe-coded-a855f7?style=flat-square)
 
 </div>
 
@@ -71,15 +71,39 @@ npx mjst --schema-dir ./schemas --out-dir ./generated
 ```
 schemas/                  generated/
   user.json        ─▶       user/
-  api/                        document.ts, index.ts
+  api/                        user.ts, index.ts
     order.json     ─▶       api/order/
-                              document.ts, index.ts
+                              order.ts, index.ts
                             _helpers/        ← shared runtime helpers (embedded mode)
 ```
 
 Each schema lands in its own subdirectory so generated files never collide, and in embedded
 mode the runtime helpers are emitted **once** into `outDir/_helpers/` — every nested parser
-imports from that single shared location. `--build` compiles the whole tree in place.
+imports from that single shared location. `--build` compiles the whole tree in place. Each
+schema's root type is named after the schema (its `title`, else its filename in PascalCase),
+so `user.json` yields `User` / `parseUser` and `api/order.json` yields `Order` / `parseOrder`.
+
+### Running the generated output
+
+By default mjst emits relative imports with the literal `.ts` extension (e.g.
+`import { parseUser } from './user.ts'`), so the generated sources run **as-is** — no build
+step — under:
+
+- **Bun** (`bun run generated/index.ts`)
+- **Node ≥ 22.6** type stripping (`node generated/index.ts`; unflagged from 22.18/23, else pass
+  `--experimental-strip-types`)
+- **tsc**, provided your `tsconfig.json` sets `"allowImportingTsExtensions": true`
+
+If you'd rather compile the output first, pass `--build` (mjst switches the imports to the
+NodeNext `./user.js` form and runs `tsc` for you), or generate with `--import-ext js` to emit
+the compile-ready form without building. `--import-ext ts` together with `--build` is rejected,
+since tsc cannot emit from `.ts` specifiers.
+
+> [!NOTE]
+> **Breaking change (0.9.0):** the root type is no longer always named `Document`. It is derived
+> from the schema `title`, falling back to the schema filename (`spec-plan.json` → `SpecPlan`,
+> giving `parseSpecPlan` / `validateSpecPlanShape`). Pass `--root-type <Name>` to override it for
+> a single `--schema` run. Update any imports that referenced `Document` / `parseDocument`.
 
 ### Config file
 
@@ -220,7 +244,7 @@ npx mjst --config ./mjst.config.json
 <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' if @amritk/helpers resolves from outDir, otherwise 'embedded'.<br><strong>Allowed:</strong> <code>"package"</code>, <code>"embedded"</code></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' 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>
@@ -232,13 +256,31 @@ npx mjst --config ./mjst.config.json
 <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>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 / validateProgramShape). When omitted, the name is derived from the schema's title, falling back to the schema filename in PascalCase (spec-plan.json → SpecPlan) and then to 'Document'. Not supported with --schema-dir, where each schema derives its own root type from its filename.<br><strong>Examples:</strong> <code>"Program"</code></td>
+</tr>
+<tr>
 <td>⚙️ <code>config</code></td>
 <td><code>--config &lt;path&gt;</code></td>
 <td><code>string</code></td>
 <td align="center"></td>
 </tr>
 <tr>
-<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, outDir, outFile, typesOnly, build, logWarnings, strict, readonly, helpers, typeSuffix). CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
+<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, outDir, outFile, typesOnly, build, logWarnings, strict, readonly, helpers, typeSuffix, importExt, rootType). CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
 </tr>
 </tbody>
 </table>

package/dist/cli-config.d.ts

@@ -89,4 +89,26 @@ export type CliConfig = {
      * - `false` / omitted — no header.
      */
     readonly banner?: boolean | string;
+    /**
+     * Extension emitted on every relative import specifier in the generated
+     * output (cross-file `$ref` imports, the index barrel, and embedded-helper
+     * imports).
+     * - `'ts'` (default): the literal on-disk paths, so the generated `.ts`
+     *   sources load under Bun, Node's type stripping (Node 22.6+ with
+     *   `--experimental-strip-types`, unflagged from 22.18/23), and tsc with
+     *   `allowImportingTsExtensions`. Incompatible with `build` — tsc refuses
+     *   to emit from `.ts` specifiers.
+     * - `'js'`: the standard TS NodeNext form (`./x.js` resolving to a sibling
+     *   `x.ts`), for output that will be compiled. Used automatically when
+     *   `build` is set and no extension was chosen explicitly.
+     */
+    readonly importExt?: 'js' | 'ts';
+    /**
+     * Name for the root type of a single-`schema` run (e.g. `'Program'` yields
+     * `parseProgram` / `validateProgramShape`). When omitted, the name is
+     * derived from the schema's `title`, falling back to the schema filename in
+     * PascalCase (`spec-plan.json` → `SpecPlan`) and then to `'Document'`.
+     * Not supported with `schemaDir`, where each schema names its own root.
+     */
+    readonly rootType?: string;
 };

package/dist/cli.js

@@ -9,12 +9,33 @@ import { deriveRootTypeName } from '@amritk/helpers/derive-root-type-name';
 const execFileAsync = promisify(execFile);
 import { combineGeneratedFiles } from './combine-files.js';
 import { detectHelpersMode } from './detect-helpers-mode.js';
+import { HELP_TEXT } from './help-text.js';
 import { loadConfig } from './load-config.js';
 import { loadSchemaModule } from './load-schema-module.js';
 import { parseCliArgs } from './parse-cli-args.js';
 import { readVersion } from './read-version.js';
+import { resolveImportExt } from './resolve-import-ext.js';
 /** True when the args request the CLI version (`version`, `--version`, or `-v`). */
 const isVersionRequest = (args) => args[0] === 'version' || args.includes('--version') || args.includes('-v');
+/** True when the args request usage help (`help`, `--help`, or `-h`). */
+const isHelpRequest = (args) => args[0] === 'help' || args.includes('--help') || args.includes('-h');
+/** The schema's base filename without extension, used to derive the root type name. */
+const schemaBaseName = (schemaPath) => basename(schemaPath).replace(/\.[^.]+$/, '');
+/**
+ * Resolves and reports the helpers mode. An explicit `--helpers` wins; otherwise
+ * it is auto-detected from the nearest package.json. When detection falls back to
+ * embedded, nudge the user toward declaring `@amritk/helpers` so multiple
+ * generated trees can share a single runtime helper copy.
+ */
+const resolveHelpersMode = (config, outputDir) => {
+    const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
+    console.log(`Helpers mode: ${helpersMode}${config.helpers ? ' (explicit)' : ' (auto-detected)'}`);
+    if (!config.helpers && helpersMode === 'embedded') {
+        console.log('Tip: add @amritk/helpers as a dependency to share one runtime helper copy across generated trees ' +
+            '(or pass --helpers embedded to silence this).');
+    }
+    return helpersMode;
+};
 /**
  * Extracts the --config flag value from process args before full parsing.
  * We need this early so we can load the config file first, then overlay CLI flags.
@@ -128,11 +149,10 @@ const findJsonSchemas = async (dir) => {
 const runSingle = async (config, schemaPath, outputDir) => {
     const schema = await loadSchema(config, schemaPath);
     await mkdir(outputDir, { recursive: true });
-    const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
-    console.log(`Helpers mode: ${helpersMode}${config.helpers ? ' (explicit)' : ' (auto-detected)'}`);
-    const rootTypeName = deriveRootTypeName(schema);
+    const helpersMode = resolveHelpersMode(config, outputDir);
+    const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
     console.log(`Root type: ${rootTypeName}`);
-    const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode, undefined, config.readonly, config.stripUnknown, config.typeSuffix);
+    const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode, undefined, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config));
     for (const file of files) {
         const isHelper = file.filename.startsWith('_helpers/');
         const content = config.banner && !isHelper ? resolveBanner(config.banner) + file.content : file.content;
@@ -155,9 +175,9 @@ const runSingleFile = async (config, schemaPath, outFilePath) => {
     const schema = await loadSchema(config, schemaPath);
     const outputDir = dirname(outFilePath);
     await mkdir(outputDir, { recursive: true });
-    const rootTypeName = deriveRootTypeName(schema);
+    const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
     console.log(`Root type: ${rootTypeName}`);
-    const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, config.helpers ?? 'package', undefined, config.readonly, config.stripUnknown, config.typeSuffix);
+    const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, config.helpers ?? 'package', undefined, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config));
     const combined = combineGeneratedFiles(files);
     await writeFile(outFilePath, config.banner ? resolveBanner(config.banner) + combined : combined, 'utf-8');
     console.log(`Generated: ${relative(process.cwd(), outFilePath)}`);
@@ -185,8 +205,7 @@ const runRecursive = async (config, schemaDir, outputDir) => {
         process.exit(1);
     }
     await mkdir(outputDir, { recursive: true });
-    const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
-    console.log(`Helpers mode: ${helpersMode}${config.helpers ? ' (explicit)' : ' (auto-detected)'}`);
+    const helpersMode = resolveHelpersMode(config, outputDir);
     // Helper sources are identical across schemas, so collect them by filename and
     // write the deduplicated set once at the output root.
     const sharedHelpers = new Map();
@@ -200,9 +219,9 @@ const runRecursive = async (config, schemaDir, outputDir) => {
         const depth = relNoExt.split(sep).filter(Boolean).length;
         const helpersImportPrefix = '../'.repeat(depth);
         const schema = await loadSchema(config, schemaFile);
-        const rootTypeName = deriveRootTypeName(schema);
+        const rootTypeName = deriveRootTypeName(schema, schemaBaseName(schemaFile));
         console.log(`\n${relPath} → ${relNoExt}/ (root type: ${rootTypeName})`);
-        const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix);
+        const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config));
         for (const file of files) {
             if (file.filename.startsWith('_helpers/')) {
                 sharedHelpers.set(file.filename, file.content);
@@ -234,6 +253,12 @@ const run = async () => {
         console.log(await readVersion());
         return;
     }
+    // Bare `mjst` and `mjst --help` both print usage rather than erroring on a
+    // missing --out-dir — a first-run user needs to see the flags, not a failure.
+    if (args.length === 0 || isHelpRequest(args)) {
+        console.log(HELP_TEXT);
+        return;
+    }
     const configPath = extractConfigPath(args);
     // Start with config file values if provided, then overlay CLI flags on top
     const fileConfig = configPath ? await loadConfig(configPath) : {};
@@ -243,6 +268,19 @@ const run = async () => {
         console.error('Error: provide only one of --out-dir or --out-file, not both.');
         process.exit(1);
     }
+    // --root-type names a single root; under --schema-dir each schema derives its
+    // own root name, so a single override would be ambiguous.
+    if (config.rootType && config.schemaDir) {
+        console.error('Error: --root-type cannot be combined with --schema-dir; each schema derives its own root type.');
+        process.exit(1);
+    }
+    // tsc cannot emit from `.ts` import specifiers (allowImportingTsExtensions
+    // requires noEmit), so compiled output and stripping-ready sources are
+    // mutually exclusive.
+    if (config.build && config.importExt === 'ts') {
+        console.error('Error: --import-ext ts cannot be combined with --build. Drop --build to keep runnable .ts sources.');
+        process.exit(1);
+    }
     // Single-file output is the alternative to a directory of files.
     if (config.outFile) {
         if (!config.typesOnly) {

package/dist/detect-helpers-mode.d.ts

@@ -1,10 +1,15 @@
 /**
- * Detects whether `@amritk/helpers` is resolvable from the consumer's output
- * directory using standard Node module resolution (walks up `node_modules`).
+ * Detects whether generated parsers should import `@amritk/helpers` from the
+ * package (`'package'`) or ship the helper sources alongside them (`'embedded'`).
  *
- * Returns `'package'` when generated parsers can safely
- * `import { ... } from '@amritk/helpers/...'` at runtime, or `'embedded'`
- * when the helper sources need to be shipped alongside the generated files
- * for the output to be self-contained.
+ * We select `'package'` only when `@amritk/helpers` is a *declared* dependency
+ * (dependencies / devDependencies / peer / optional) of the target project's
+ * nearest `package.json` above `outputDir`. Merely being *resolvable* is not
+ * enough: under npm/bun's hoisted layouts `@amritk/helpers` can sit in
+ * `node_modules` purely as a transitive dependency of `@amritk/mjst`, which
+ * makes `import '@amritk/helpers/...'` work locally but break under
+ * pnpm/isolated installs where undeclared packages are not reachable. Requiring
+ * a declaration keeps auto-detected `'package'` output portable across install
+ * layouts; everything else falls back to the self-contained `'embedded'` mode.
  */
 export declare const detectHelpersMode: (outputDir: string) => 'package' | 'embedded';

package/dist/detect-helpers-mode.js

@@ -1,21 +1,45 @@
-import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { dirname, join, parse as parsePath, resolve } from 'node:path';
+/** Reads a package.json's declared dependency names, or `undefined` if unreadable. */
+const readDeclaredDeps = (packageJsonPath) => {
+    try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        return new Set([
+            ...Object.keys(pkg.dependencies ?? {}),
+            ...Object.keys(pkg.devDependencies ?? {}),
+            ...Object.keys(pkg.peerDependencies ?? {}),
+            ...Object.keys(pkg.optionalDependencies ?? {}),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
- * Detects whether `@amritk/helpers` is resolvable from the consumer's output
- * directory using standard Node module resolution (walks up `node_modules`).
+ * Detects whether generated parsers should import `@amritk/helpers` from the
+ * package (`'package'`) or ship the helper sources alongside them (`'embedded'`).
  *
- * Returns `'package'` when generated parsers can safely
- * `import { ... } from '@amritk/helpers/...'` at runtime, or `'embedded'`
- * when the helper sources need to be shipped alongside the generated files
- * for the output to be self-contained.
+ * We select `'package'` only when `@amritk/helpers` is a *declared* dependency
+ * (dependencies / devDependencies / peer / optional) of the target project's
+ * nearest `package.json` above `outputDir`. Merely being *resolvable* is not
+ * enough: under npm/bun's hoisted layouts `@amritk/helpers` can sit in
+ * `node_modules` purely as a transitive dependency of `@amritk/mjst`, which
+ * makes `import '@amritk/helpers/...'` work locally but break under
+ * pnpm/isolated installs where undeclared packages are not reachable. Requiring
+ * a declaration keeps auto-detected `'package'` output portable across install
+ * layouts; everything else falls back to the self-contained `'embedded'` mode.
  */
 export const detectHelpersMode = (outputDir) => {
-    const req = createRequire(resolve(outputDir, 'noop.js'));
-    try {
-        req.resolve('@amritk/helpers/is-object');
-        return 'package';
-    }
-    catch {
-        return 'embedded';
+    let dir = resolve(outputDir);
+    const { root } = parsePath(dir);
+    while (true) {
+        const declared = readDeclaredDeps(join(dir, 'package.json'));
+        if (declared) {
+            return declared.has('@amritk/helpers') ? 'package' : 'embedded';
+        }
+        if (dir === root)
+            break;
+        dir = dirname(dir);
     }
+    return 'embedded';
 };

package/dist/help-text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Usage text printed for `--help`/`-h` and when the CLI is invoked with no
+ * arguments. Kept as a hand-written constant because the config schema that
+ * documents these flags (config.schema.json) is not shipped in the published
+ * package; the help-text test cross-checks that every flag is listed.
+ */
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect\n  --export <name>       Which export of the schema module to use when --input is not json\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --log-warnings        console.warn on input keys not declared in the schema\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";

package/dist/help-text.js

@@ -0,0 +1,43 @@
+/**
+ * Usage text printed for `--help`/`-h` and when the CLI is invoked with no
+ * arguments. Kept as a hand-written constant because the config schema that
+ * 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 const HELP_TEXT = `mjst — generate TypeScript parsers and type definitions from JSON Schemas
+
+Usage:
+  mjst --schema <path> --out-dir <dir> [options]
+  mjst --schema-dir <dir> --out-dir <dir> [options]
+  mjst --schema <path> --out-file <file> --types-only [options]
+
+Input:
+  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set
+  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)
+  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect
+  --export <name>       Which export of the schema module to use when --input is not json
+
+Output:
+  --out-dir <dir>       Output directory for the generated files
+  --out-file <file>     Single-file output instead of a directory (requires --types-only)
+  --types-only          Generate type definitions only, without parser functions
+  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)
+  --import-ext <ext>    Extension on generated relative imports: ts (default) or js
+  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)
+  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)
+  --type-suffix <s>     Suffix appended to every $ref-derived type name
+  --banner [text]       Prepend a header comment to every generated file
+  --readonly            Emit deeply readonly type definitions
+
+Validation:
+  --strict              Throw on type/shape mismatches instead of coercing to defaults
+  --strip-unknown       Silently drop undeclared input keys at every nesting level
+  --log-warnings        console.warn on input keys not declared in the schema
+
+Misc:
+  --config <path>       JSON config file with the same keys; CLI flags take precedence
+  --version, -v         Print the CLI version
+  --help, -h            Print this help
+
+Docs: https://github.com/amritk/mjst/tree/main/packages/cli#readme
+`;

package/dist/load-config.js

@@ -3,6 +3,7 @@ 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';
+const isImportExt = (value) => value === 'js' || value === 'ts';
 /**
  * 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).
@@ -29,6 +30,8 @@ export const loadConfig = async (configPath) => {
         ...(typeof obj['stripUnknown'] === 'boolean' && { stripUnknown: obj['stripUnknown'] }),
         ...(typeof obj['readonly'] === 'boolean' && { readonly: obj['readonly'] }),
         ...(isHelpersMode(obj['helpers']) && { helpers: obj['helpers'] }),
+        ...(isImportExt(obj['importExt']) && { importExt: obj['importExt'] }),
+        ...(typeof obj['rootType'] === 'string' && { rootType: obj['rootType'] }),
         ...(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

@@ -18,6 +18,8 @@ const VALUE_KEYS = new Set([
     'export',
     'helpers',
     'typeSuffix',
+    'importExt',
+    'rootType',
 ]);
 // Recognized flags that don't map into CliConfig because they're consumed
 // earlier in the pipeline (e.g. `--config` is read by `extractConfigPath` to
@@ -31,6 +33,11 @@ const parseHelpersValue = (value) => {
         return value;
     return undefined;
 };
+const parseImportExtValue = (value) => {
+    if (value === 'js' || value === 'ts')
+        return value;
+    return undefined;
+};
 const parseInputValue = (value) => SOURCE_FORMATS.includes(value) ? value : undefined;
 /** Assigns a value-flag onto the config. Returns false for unknown keys. */
 const assignValue = (config, key, value) => {
@@ -53,6 +60,9 @@ const assignValue = (config, key, value) => {
         case 'typeSuffix':
             config.typeSuffix = value;
             return true;
+        case 'rootType':
+            config.rootType = value;
+            return true;
         case 'input': {
             const parsed = parseInputValue(value);
             if (!parsed) {
@@ -69,6 +79,14 @@ const assignValue = (config, key, value) => {
             config.helpers = parsed;
             return true;
         }
+        case 'importExt': {
+            const parsed = parseImportExtValue(value);
+            if (!parsed) {
+                throw new Error(`Invalid --import-ext value "${value}". Expected one of: js, ts.`);
+            }
+            config.importExt = parsed;
+            return true;
+        }
         default:
             return false;
     }

package/dist/resolve-import-ext.d.ts

@@ -0,0 +1,10 @@
+import type { CliConfig } from './cli-config.js';
+/**
+ * Resolves the effective extension for relative import specifiers in the
+ * generated output. An explicit `importExt` (flag or config file) always wins.
+ * Otherwise the default is `'ts'` — the literal on-disk paths, loadable by
+ * Bun, Node's type stripping, and tsc with `allowImportingTsExtensions` —
+ * except under `build`, where tsc must compile the sources and can only emit
+ * from `'js'` specifiers.
+ */
+export declare const resolveImportExt: (config: Partial<CliConfig>) => 'js' | 'ts';

package/dist/resolve-import-ext.js

@@ -0,0 +1,9 @@
+/**
+ * Resolves the effective extension for relative import specifiers in the
+ * generated output. An explicit `importExt` (flag or config file) always wins.
+ * Otherwise the default is `'ts'` — the literal on-disk paths, loadable by
+ * Bun, Node's type stripping, and tsc with `allowImportingTsExtensions` —
+ * except under `build`, where tsc must compile the sources and can only emit
+ * from `'js'` specifiers.
+ */
+export const resolveImportExt = (config) => config.importExt ?? (config.build ? 'js' : 'ts');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.7.16",
+  "version": "0.9.0",
   "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.14",
-    "@amritk/generate-parsers": "0.13.0",
+    "@amritk/adapters": "0.2.16",
+    "@amritk/generate-parsers": "0.15.0",
     "@amritk/generate-markdown": "0.4.1",
-    "@amritk/helpers": "0.10.3"
+    "@amritk/helpers": "0.12.0"
   },
   "devDependencies": {
     "json-schema-typed": "^8.0.1"