@amritk/mjst 0.8.0 → 0.10.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>
 
@@ -21,6 +21,8 @@
 
 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).
+
 ---
 
 ## Installation
@@ -71,15 +73,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
 
@@ -92,6 +118,45 @@ npx mjst --config ./mjst.config.json
 
 ---
 
+## Linting
+
+`mjst lint` lints JSON/YAML documents against a ruleset — JSON Schema validation and custom style rules, with exact `line:column` findings. It has its own flags (and its own `--help`), independent of the generation flags above.
+
+```bash
+# Lint files against an explicit ruleset
+npx mjst lint "**/*.{yaml,json}" -r .lint.yaml
+
+# Auto-discover a .lint.* ruleset by walking up from each file
+npx mjst lint config/
+
+# Lint piped input
+cat service.yaml | npx mjst lint --stdin-filepath service.yaml
+```
+
+Findings are printed as a compact, editor-clickable report:
+
+```
+config/service.yaml:2:7  error  config-schema  /port must be integer
+
+✖ 1 problem(s) (1 error(s), 0 warning(s))
+```
+
+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.
+
+| Flag | Description |
+| --- | --- |
+| `<documents..>` | Files or globs to lint (positional). |
+| `-r`, `--ruleset` | Path to a ruleset file. Defaults to `.lint.*` discovery. |
+| `-F`, `--fail-severity` | Minimum severity that fails the run: `error` (default), `warn`, `info`, `hint`. |
+| `-D`, `--display-only-failures` | Only show findings at or above `--fail-severity`. |
+| `--stdin-filepath` | Path to associate with piped input (labels findings and enables ruleset discovery). |
+| `--concurrency` | Max documents linted in parallel (default `8`). |
+| `-q`, `--quiet` | Suppress the findings report (the exit code still reflects findings). |
+
+The exit code is `0` when no finding reaches `--fail-severity`, `1` when one does, and `2` on a usage error. Run `mjst lint --help` for the full list.
+
+---
+
 ## Configuration reference
 
 <!-- config-table-start -->
@@ -220,7 +285,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>
@@ -235,10 +300,19 @@ npx mjst --config ./mjst.config.json
 <td>🔗 <code>importExt</code></td>
 <td><code>--import-ext &lt;ext&gt;</code></td>
 <td><code>string</code></td>
-<td align="center"><code>"js"</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">Extension emitted on every relative import specifier in the generated output (cross-file $ref imports, the index barrel, and embedded-helper imports). 'js' (default) is the standard TS NodeNext form ('./x.js' resolving to a sibling x.ts), accepted by tsc, Bun, and bundlers, and required by 'build'. 'ts' emits the literal on-disk paths so the generated .ts sources run directly under Node's type stripping (Node 22.6+ with --experimental-strip-types, on by default from Node 23). Incompatible with 'build' — tsc refuses to emit from .ts specifiers.<br><strong>Allowed:</strong> <code>"js"</code>, <code>"ts"</code></td>
+<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>
@@ -247,7 +321,7 @@ npx mjst --config ./mjst.config.json
 <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, importExt). 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

@@ -93,13 +93,22 @@ export type CliConfig = {
      * Extension emitted on every relative import specifier in the generated
      * output (cross-file `$ref` imports, the index barrel, and embedded-helper
      * imports).
-     * - `'js'` (default): the standard TS NodeNext form (`./x.js` resolving to a
-     *   sibling `x.ts`), accepted by tsc, Bun, and bundlers, and required by
-     *   `build`.
-     * - `'ts'`: the literal on-disk paths, so the generated `.ts` sources run
-     *   directly under Node's type stripping (Node 22.6+ with
-     *   `--experimental-strip-types`, default from Node 23). Incompatible with
-     *   `build` — tsc refuses to emit from `.ts` specifiers.
+     * - `'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, config.importExt);
+    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, config.importExt);
+    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, config.importExt);
+        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);
@@ -230,10 +249,28 @@ const runRecursive = async (config, schemaDir, outputDir) => {
 const run = async () => {
     // Skip the first two args (node executable and script path)
     const args = process.argv.slice(2);
+    // `mjst lint <files>` delegates to the linter, which owns its own flag parsing
+    // and `--help` (yargs) — so this must run before the shared version/help checks,
+    // otherwise `mjst lint --help` would print the codegen help instead.
+    if (args[0] === 'lint') {
+        const { run: lintRun } = await import('./lint/run.js');
+        const result = await lintRun(args.slice(1));
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        process.exit(result.code);
+    }
     if (isVersionRequest(args)) {
         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 +280,12 @@ 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.

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/lint/ruleset-loader.d.ts

@@ -0,0 +1,5 @@
+import { type RulesetDefinition } from '@amritk/lint';
+/** Loads a ruleset definition from a YAML, JSON, or JS/MJS file. */
+export declare const loadRuleset: (path: string) => Promise<RulesetDefinition>;
+/** Walks up from a directory looking for a `.lint.*` ruleset file. */
+export declare const discoverRuleset: (startDir: string) => string | undefined;

package/dist/lint/ruleset-loader.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseWithPointers } from '@amritk/lint';
+const RULESET_FILENAMES = ['.lint.yaml', '.lint.yml', '.lint.json', '.lint.js', '.lint.mjs'];
+/** Loads a ruleset definition from a YAML, JSON, or JS/MJS file. */
+export const loadRuleset = async (path) => {
+    const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+    if (/\.(c|m)?js$/.test(absolute)) {
+        const module = await import(pathToFileURL(absolute).href);
+        return (module.default ?? module);
+    }
+    const content = await readFile(absolute, 'utf8');
+    return parseWithPointers(content).data;
+};
+/** Walks up from a directory looking for a `.lint.*` ruleset file. */
+export const discoverRuleset = (startDir) => {
+    let dir = resolve(startDir);
+    while (true) {
+        for (const name of RULESET_FILENAMES) {
+            const candidate = join(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+};

package/dist/lint/run.d.ts

@@ -0,0 +1,15 @@
+/** The outcome of a {@link run}: exit code plus the text it would print. */
+export type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Runs the linter over `argv`, returning the exit code and the text it would
+ * print (rather than writing to the process streams) so it can be driven
+ * in-process by tests. `stdin` supplies the piped document when there are no file
+ * targets; when omitted it is read from `process.stdin`.
+ */
+export declare const run: (argv: string[], options?: {
+    stdin?: string;
+}) => Promise<RunResult>;

package/dist/lint/run.js

@@ -0,0 +1,176 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { DiagnosticSeverity, lintDocument, validateRuleset, } from '@amritk/lint';
+import fg from 'fast-glob';
+import yargs from 'yargs';
+import { discoverRuleset, loadRuleset } from './ruleset-loader.js';
+const SEVERITY_BY_NAME = {
+    error: DiagnosticSeverity.Error,
+    warn: DiagnosticSeverity.Warning,
+    info: DiagnosticSeverity.Information,
+    hint: DiagnosticSeverity.Hint,
+};
+const SEVERITY_LABEL = ['error', 'warning', 'info', 'hint'];
+/**
+ * Renders findings as a compact, dependency-free report — one `file:line:col`
+ * line per finding (1-based, editor-clickable), then a count summary. Structured
+ * output (JSON, SARIF, …) is a consumer concern: use the `@amritk/lint` library's
+ * `lintDocument`, which returns `IDiagnostic[]`.
+ */
+const formatReport = (findings) => {
+    if (findings.length === 0)
+        return 'No problems found\n';
+    const lines = findings.map((d) => {
+        const loc = `${d.source ?? '<stdin>'}:${d.range.start.line + 1}:${d.range.start.character + 1}`;
+        return `${loc}  ${SEVERITY_LABEL[d.severity] ?? 'error'}  ${d.code}  ${d.message}`;
+    });
+    const errors = findings.filter((d) => d.severity === DiagnosticSeverity.Error).length;
+    const warnings = findings.filter((d) => d.severity === DiagnosticSeverity.Warning).length;
+    lines.push('', `✖ ${findings.length} problem(s) (${errors} error(s), ${warnings} warning(s))`);
+    return `${lines.join('\n')}\n`;
+};
+const readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+};
+const filterBySeverity = (results, failSeverity) => results.filter((result) => result.severity <= failSeverity);
+/**
+ * Maps `items` through `worker` with at most `limit` running at once, preserving
+ * input order in the result. Lets the CLI lint a directory of documents
+ * concurrently instead of strictly one at a time, without unbounded parallelism.
+ */
+const mapWithConcurrency = async (items, limit, worker) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = new Array(Math.max(1, Math.min(limit, items.length))).fill(0).map(async () => {
+        while (true) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index]);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+};
+/**
+ * Runs the linter over `argv`, returning the exit code and the text it would
+ * print (rather than writing to the process streams) so it can be driven
+ * in-process by tests. `stdin` supplies the piped document when there are no file
+ * targets; when omitted it is read from `process.stdin`.
+ */
+export const run = async (argv, options = {}) => {
+    const out = [];
+    const err = [];
+    const parsed = (await yargs(argv)
+        .scriptName('lint')
+        .parserConfiguration({ 'greedy-arrays': false })
+        .usage('$0 [documents..]', 'Lint JSON/YAML documents against a ruleset')
+        .positional('documents', { describe: 'Documents or globs to lint', type: 'string', array: true })
+        .option('ruleset', { alias: 'r', type: 'string', describe: 'Path to a ruleset file' })
+        .option('encoding', { type: 'string', default: 'utf8', describe: 'Input encoding' })
+        .option('fail-severity', { alias: 'F', type: 'string', default: 'error', choices: Object.keys(SEVERITY_BY_NAME) })
+        .option('display-only-failures', { alias: 'D', type: 'boolean', default: false })
+        .option('verbose', { type: 'boolean', default: false })
+        .option('quiet', { alias: 'q', type: 'boolean', default: false })
+        .option('stdin-filepath', {
+        type: 'string',
+        describe: 'Path to associate with stdin input (labels findings and enables ruleset discovery)',
+    })
+        .option('concurrency', {
+        type: 'number',
+        default: 8,
+        describe: 'Maximum number of documents to lint in parallel',
+    })
+        .help()
+        .alias('help', 'h')
+        .parse());
+    const failSeverity = SEVERITY_BY_NAME[parsed.failSeverity] ?? DiagnosticSeverity.Error;
+    const reportRulesetProblems = (definition, label) => {
+        if (parsed.quiet)
+            return;
+        for (const problem of validateRuleset(definition)) {
+            const at = problem.path.length > 0 ? ` (at ${problem.path.join('.')})` : '';
+            err.push(`warning: ruleset ${label}: ${problem.message}${at}\n`);
+        }
+    };
+    const discoverAndLoad = async (dir) => {
+        const discovered = discoverRuleset(dir);
+        if (!discovered)
+            return undefined;
+        const definition = await loadRuleset(discovered);
+        reportRulesetProblems(definition, discovered);
+        return { definition, basePath: dirname(discovered) };
+    };
+    let rulesetDefinition;
+    let rulesetBasePath;
+    if (parsed.ruleset) {
+        rulesetDefinition = await loadRuleset(parsed.ruleset);
+        rulesetBasePath = dirname(isAbsolute(parsed.ruleset) ? parsed.ruleset : resolve(process.cwd(), parsed.ruleset));
+        reportRulesetProblems(rulesetDefinition, parsed.ruleset);
+    }
+    const targets = await fg(parsed.documents ?? [], { dot: true, onlyFiles: true });
+    const allResults = [];
+    if (targets.length === 0) {
+        if (options.stdin === undefined && process.stdin.isTTY) {
+            return { code: 2, stdout: '', stderr: 'No documents provided.\n' };
+        }
+        const content = options.stdin ?? (await readStdin());
+        // With --stdin-filepath, label findings with that path and discover a
+        // `.lint.*` ruleset by walking up from its directory.
+        const stdinPath = parsed.stdinFilepath;
+        let definition = rulesetDefinition;
+        let basePath = rulesetBasePath;
+        if (!definition && !parsed.ruleset && stdinPath) {
+            const discovered = await discoverAndLoad(dirname(stdinPath));
+            if (discovered)
+                ({ definition, basePath } = discovered);
+        }
+        const opts = {
+            ...(definition ? { ruleset: definition } : {}),
+            ...(basePath !== undefined ? { rulesetBasePath: basePath } : {}),
+            source: stdinPath ?? '<stdin>',
+        };
+        allResults.push(...(await lintDocument(content, opts)));
+    }
+    else {
+        // Cache discovered/loaded rulesets by directory so a directory of documents
+        // that share a `.lint.*` file parses it once, not once per file.
+        const rulesetCache = new Map();
+        const perFile = await mapWithConcurrency(targets, parsed.concurrency, async (file) => {
+            const content = await readFile(file, parsed.encoding);
+            let definition = rulesetDefinition;
+            let basePath = rulesetBasePath;
+            if (!definition && !parsed.ruleset) {
+                const dir = dirname(file);
+                let discovered = rulesetCache.get(dir);
+                if (!rulesetCache.has(dir)) {
+                    discovered = await discoverAndLoad(dir);
+                    rulesetCache.set(dir, discovered);
+                }
+                if (discovered)
+                    ({ definition, basePath } = discovered);
+            }
+            const opts = definition
+                ? {
+                    ruleset: definition,
+                    ...(basePath !== undefined ? { rulesetBasePath: basePath } : {}),
+                    source: file,
+                }
+                : { source: file };
+            return lintDocument(content, opts);
+        });
+        for (const remaining of perFile)
+            allResults.push(...remaining);
+    }
+    const displayed = parsed.displayOnlyFailures ? filterBySeverity(allResults, failSeverity) : allResults;
+    if (!parsed.quiet)
+        out.push(formatReport(displayed));
+    return {
+        code: filterBySeverity(allResults, failSeverity).length > 0 ? 1 : 0,
+        stdout: out.join(''),
+        stderr: err.join(''),
+    };
+};

package/dist/load-config.js

@@ -31,6 +31,7 @@ export const loadConfig = async (configPath) => {
         ...(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

@@ -19,6 +19,7 @@ const VALUE_KEYS = new Set([
     '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
@@ -59,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) {

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.8.0",
+  "version": "0.10.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -41,12 +41,16 @@
     "generate-readme": "bun run ./scripts/generate-readme.ts"
   },
   "dependencies": {
-    "@amritk/adapters": "0.2.15",
-    "@amritk/generate-parsers": "0.14.0",
+    "@amritk/adapters": "0.2.16",
+    "@amritk/generate-parsers": "0.15.0",
     "@amritk/generate-markdown": "0.4.1",
-    "@amritk/helpers": "0.11.0"
+    "@amritk/helpers": "0.12.0",
+    "@amritk/lint": "0.1.0",
+    "fast-glob": "^3.3.2",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "json-schema-typed": "^8.0.1"
+    "json-schema-typed": "^8.0.1",
+    "@types/yargs": "^17.0.33"
   }
 }