@amritk/mjst 0.9.0 → 0.11.0

package/README.md

@@ -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
@@ -116,6 +118,51 @@ 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`). |
+| `--no-resolve` | Skip `$ref` dereferencing; rules see the raw document. |
+| `--resolve-remote` | Fetch `http(s)` `$ref`s while resolving (off by default; a lint run stays offline). |
+| `--allowed-hosts` | Restrict remote `$ref` fetches to these hosts (implies `--resolve-remote`). |
+| `--allow-private-hosts` | Permit remote `$ref`s to private/loopback hosts (SSRF guard, off by default). |
+| `-q`, `--quiet` | Suppress the findings report (the exit code still reflects findings). |
+
+By default `mjst lint` dereferences `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor` before running rules, so rules with `resolved: true` (the ruleset default) see through references. Internal and local cross-file refs resolve from disk — a finding on a cross-file node reports that file's own `line:column` — while remote refs are only fetched when you opt in with `--resolve-remote` or `--allowed-hosts`.
+
+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 -->
@@ -229,6 +276,15 @@ npx mjst --config ./mjst.config.json
 <td colspan="4">Build each parser's result from the schema's declared properties only, silently dropping undeclared input keys at every nesting level (zod's .strip()). Extras are never a validation error, so this composes with strict (which still throws on wrong types and missing required properties) and yields to additionalProperties: false, which rejects rather than strips in strict mode.</td>
 </tr>
 <tr>
+<td>🔡 <code>caseInsensitive</code></td>
+<td><code>--case-insensitive</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Normalize a mis-cased string to the exact casing of a declared enum/const member it matches case-insensitively (e.g. hElLo → hello) instead of coercing to the default. Coerce mode only — strict parsers still reject a casing mismatch. Correctly-cased input keeps the exact-match fast path, so the hot path is unaffected.</td>
+</tr>
+<tr>
 <td>🔒 <code>readonly</code></td>
 <td><code>--readonly</code></td>
 <td><code>boolean</code></td>

package/dist/cli-config.d.ts

@@ -61,6 +61,15 @@ export type CliConfig = {
      * rather than strips in strict mode.
      */
     readonly stripUnknown?: boolean;
+    /**
+     * When true, the generated coercing parsers normalize a mis-cased string to
+     * the exact casing of a declared `enum`/`const` member it matches
+     * case-insensitively (e.g. `hElLo` → `hello`) instead of coercing to the
+     * default. Coerce mode only — `strict` parsers still reject a casing
+     * mismatch. Correctly-cased input keeps the exact-match fast path, so the hot
+     * path is unaffected.
+     */
+    readonly caseInsensitive?: boolean;
     /**
      * Controls how generated parsers reference their runtime helpers.
      * - `'package'`: emit `import ... from '@amritk/helpers/...'`.

package/dist/cli.js

@@ -152,7 +152,7 @@ const runSingle = async (config, schemaPath, outputDir) => {
     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, resolveImportExt(config));
+    const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode, undefined, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
     for (const file of files) {
         const isHelper = file.filename.startsWith('_helpers/');
         const content = config.banner && !isHelper ? resolveBanner(config.banner) + file.content : file.content;
@@ -177,7 +177,7 @@ const runSingleFile = async (config, schemaPath, outFilePath) => {
     await mkdir(outputDir, { recursive: true });
     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, resolveImportExt(config));
+    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), config.caseInsensitive);
     const combined = combineGeneratedFiles(files);
     await writeFile(outFilePath, config.banner ? resolveBanner(config.banner) + combined : combined, 'utf-8');
     console.log(`Generated: ${relative(process.cwd(), outFilePath)}`);
@@ -221,7 +221,7 @@ const runRecursive = async (config, schemaDir, outputDir) => {
         const schema = await loadSchema(config, schemaFile);
         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, resolveImportExt(config));
+        const files = await buildSchema(schema, rootTypeName, undefined, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
         for (const file of files) {
             if (file.filename.startsWith('_helpers/')) {
                 sharedHelpers.set(file.filename, file.content);
@@ -249,6 +249,18 @@ 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;

package/dist/help-text.d.ts

@@ -4,4 +4,4 @@
  * documents these flags (config.schema.json) is not shipped in the published
  * package; the help-text test cross-checks that every flag is listed.
  */
-export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\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";
+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  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n\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

@@ -32,6 +32,7 @@ Output:
 Validation:
   --strict              Throw on type/shape mismatches instead of coercing to defaults
   --strip-unknown       Silently drop undeclared input keys at every nesting level
+  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing
   --log-warnings        console.warn on input keys not declared in the schema
 
 Misc:

package/dist/lint/resolver.d.ts

@@ -0,0 +1,24 @@
+import { type LintResolver } from '@amritk/lint';
+/** How `mjst lint` dereferences `$ref` (and `$dynamicRef`/`$recursiveRef`). */
+export type ResolverOptions = {
+    /**
+     * Fetch http(s) `$ref`s. Defaults to `false`: a lint run should not make
+     * network calls unless asked. A non-empty `allowedHosts` implies `remote`.
+     */
+    remote?: boolean;
+    /** If set, only these hosts may be fetched (and each bypasses the private-host guard). */
+    allowedHosts?: string[];
+    /** Permit remote refs to private/loopback/link-local hosts (off by default as an SSRF guard). */
+    allowPrivateHosts?: boolean;
+};
+/**
+ * Builds a {@link LintResolver} backed by `@amritk/resolve-refs`, dereferencing
+ * `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor`
+ * so rules with `resolved: true` (the ruleset default) see through references.
+ *
+ * Internal-only documents resolve in memory. A document with cross-file/remote
+ * refs is resolved from disk **only when its source file reads back exactly as
+ * the linted input** — so a piped document (`--stdin-filepath`) never resolves
+ * against a different on-disk file — with remote fetching gated by `options`.
+ */
+export declare const createLintResolver: (options?: ResolverOptions) => LintResolver;

package/dist/lint/resolver.js

@@ -0,0 +1,115 @@
+import { readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { createDocument, resolveSourceOriginFromMap, } from '@amritk/lint';
+import { resolveRefs, resolveRefsFromFile } from '@amritk/resolve-refs';
+import { parse as parseYaml } from '@amritk/yaml';
+const isRemote = (location) => /^https?:\/\//i.test(location);
+/**
+ * Parses a referenced document by extension: YAML for `.yaml`/`.yml`, JSON for
+ * `.json`, and for anything else (extensionless, remote) tries JSON first, then
+ * YAML. YAML is a JSON superset, so this accepts every document the linter does.
+ */
+const parseDoc = (content, location) => {
+    if (/\.ya?ml$/i.test(location))
+        return parseYaml(content);
+    if (/\.json$/i.test(location))
+        return JSON.parse(content);
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return parseYaml(content);
+    }
+};
+/** The reference keywords whose value may point at another document (a non-`#` target). */
+const REF_KEYWORDS = ['$ref', '$dynamicRef', '$recursiveRef'];
+/**
+ * Whether `data` contains a reference into another document (a `$ref` value that
+ * is not a same-document `#...` fragment). Internal-only documents resolve fully
+ * in memory, so we avoid the disk round-trip unless an external target exists.
+ */
+const hasExternalRefs = (data) => {
+    if (data === null || typeof data !== 'object')
+        return false;
+    if (Array.isArray(data))
+        return data.some(hasExternalRefs);
+    const obj = data;
+    for (const keyword of REF_KEYWORDS) {
+        const value = obj[keyword];
+        if (typeof value === 'string' && !value.startsWith('#'))
+            return true;
+    }
+    return Object.values(obj).some(hasExternalRefs);
+};
+/** Whether the file at `absolute` reads back byte-for-byte as `input` (the document we linted). */
+const readsBackAs = (absolute, input) => {
+    try {
+        return readFileSync(absolute, 'utf8') === input;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Builds the {@link ISourceSet} the runner uses to map a finding on a resolved
+ * (dereferenced) node back to the file it came from. Origins from the resolver
+ * attribute each inlined node to its source document + path; `get` lazily parses
+ * each source file (with a position map) so findings on cross-file nodes report
+ * that file's own `line:column`. The root document is already parsed by the
+ * linter, so it is reused directly. Remote documents are not re-fetched here, so
+ * a finding inlined from a URL falls back to the root document's position.
+ */
+const buildSourceSet = (rootDocument, resolved, origins, rootLocation) => {
+    const documents = new Map([[rootLocation, rootDocument]]);
+    const originMap = origins ?? new Map();
+    const load = (location) => {
+        if (documents.has(location))
+            return documents.get(location);
+        let document;
+        if (location !== '' && !isRemote(location)) {
+            try {
+                document = createDocument(readFileSync(location, 'utf8'), { source: location });
+            }
+            catch {
+                document = undefined;
+            }
+        }
+        documents.set(location, document);
+        return document;
+    };
+    return {
+        get: load,
+        origin: (path) => resolveSourceOriginFromMap(resolved, originMap, rootLocation, path),
+    };
+};
+/**
+ * Builds a {@link LintResolver} backed by `@amritk/resolve-refs`, dereferencing
+ * `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor`
+ * so rules with `resolved: true` (the ruleset default) see through references.
+ *
+ * Internal-only documents resolve in memory. A document with cross-file/remote
+ * refs is resolved from disk **only when its source file reads back exactly as
+ * the linted input** — so a piped document (`--stdin-filepath`) never resolves
+ * against a different on-disk file — with remote fetching gated by `options`.
+ */
+export const createLintResolver = (options = {}) => {
+    const fromFileOptions = {
+        remote: options.remote ?? false,
+        ...(options.allowedHosts ? { allowedHosts: options.allowedHosts } : {}),
+        ...(options.allowPrivateHosts ? { allowPrivateHosts: options.allowPrivateHosts } : {}),
+        parse: parseDoc,
+        trackOrigins: true,
+    };
+    return async (document, { input }) => {
+        const { source } = document;
+        if (source && hasExternalRefs(document.data)) {
+            const absolute = resolvePath(source);
+            if (readsBackAs(absolute, input)) {
+                const { resolved, origins } = await resolveRefsFromFile(absolute, fromFileOptions);
+                return { resolved, sources: buildSourceSet(document, resolved, origins, absolute) };
+            }
+        }
+        const { resolved, origins } = resolveRefs(document.data, { trackOrigins: true });
+        return { resolved, sources: buildSourceSet(document, resolved, origins, '') };
+    };
+};

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,208 @@
+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 { createLintResolver } from './resolver.js';
+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',
+    })
+        .option('resolve', {
+        type: 'boolean',
+        default: true,
+        describe: 'Dereference $ref / $dynamicRef / $recursiveRef before linting (use --no-resolve to disable)',
+    })
+        .option('resolve-remote', {
+        type: 'boolean',
+        default: false,
+        describe: 'Allow fetching http(s) $refs while resolving (off by default; a lint run stays offline)',
+    })
+        .option('allowed-hosts', {
+        type: 'string',
+        array: true,
+        describe: 'Restrict remote $ref fetches to these hosts (implies --resolve-remote)',
+    })
+        .option('allow-private-hosts', {
+        type: 'boolean',
+        default: false,
+        describe: 'Permit remote $refs to private/loopback hosts (SSRF guard, off by default)',
+    })
+        .help()
+        .alias('help', 'h')
+        .parse());
+    const failSeverity = SEVERITY_BY_NAME[parsed.failSeverity] ?? DiagnosticSeverity.Error;
+    // A non-empty --allowed-hosts is an explicit opt-in to remote fetching.
+    const allowRemote = parsed.resolveRemote || (parsed.allowedHosts?.length ?? 0) > 0;
+    const resolver = parsed.resolve
+        ? createLintResolver({
+            remote: allowRemote,
+            ...(parsed.allowedHosts ? { allowedHosts: parsed.allowedHosts } : {}),
+            allowPrivateHosts: parsed.allowPrivateHosts,
+        })
+        : undefined;
+    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 } : {}),
+            ...(resolver && definition ? { resolve: resolver } : {}),
+            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 } : {}),
+                    ...(resolver ? { resolve: resolver } : {}),
+                    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

@@ -28,6 +28,7 @@ export const loadConfig = async (configPath) => {
         ...(typeof obj['logWarnings'] === 'boolean' && { logWarnings: obj['logWarnings'] }),
         ...(typeof obj['strict'] === 'boolean' && { strict: obj['strict'] }),
         ...(typeof obj['stripUnknown'] === 'boolean' && { stripUnknown: obj['stripUnknown'] }),
+        ...(typeof obj['caseInsensitive'] === 'boolean' && { caseInsensitive: obj['caseInsensitive'] }),
         ...(typeof obj['readonly'] === 'boolean' && { readonly: obj['readonly'] }),
         ...(isHelpersMode(obj['helpers']) && { helpers: obj['helpers'] }),
         ...(isImportExt(obj['importExt']) && { importExt: obj['importExt'] }),

package/dist/parse-cli-args.js

@@ -6,6 +6,7 @@ const BOOLEAN_KEYS = new Set([
     'logWarnings',
     'strict',
     'stripUnknown',
+    'caseInsensitive',
     'readonly',
 ]);
 // Value flags consume the following argument (or `--flag=value`).
@@ -109,6 +110,9 @@ const assignBoolean = (config, key, value) => {
         case 'stripUnknown':
             config.stripUnknown = value;
             return true;
+        case 'caseInsensitive':
+            config.caseInsensitive = value;
+            return true;
         case 'readonly':
             config.readonly = value;
             return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -42,11 +42,17 @@
   },
   "dependencies": {
     "@amritk/adapters": "0.2.16",
-    "@amritk/generate-parsers": "0.15.0",
+    "@amritk/generate-parsers": "0.16.0",
     "@amritk/generate-markdown": "0.4.1",
-    "@amritk/helpers": "0.12.0"
+    "@amritk/helpers": "0.12.0",
+    "@amritk/lint": "0.2.0",
+    "@amritk/resolve-refs": "0.3.0",
+    "@amritk/yaml": "0.2.3",
+    "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"
   }
 }