@amritk/mjst 0.10.0 → 0.11.0

package/README.md

@@ -151,8 +151,14 @@ With no `-r`, mjst discovers a `.lint.{yaml,yml,json,js,mjs}` ruleset by walking
 | `-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.
 
 ---
@@ -270,6 +276,15 @@ The exit code is `0` when no finding reaches `--fail-severity`, `1` when one doe
 <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);

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/run.js

@@ -3,6 +3,7 @@ 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,
@@ -83,11 +84,40 @@ export const run = async (argv, options = {}) => {
         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;
@@ -131,6 +161,7 @@ export const run = async (argv, options = {}) => {
         const opts = {
             ...(definition ? { ruleset: definition } : {}),
             ...(basePath !== undefined ? { rulesetBasePath: basePath } : {}),
+            ...(resolver && definition ? { resolve: resolver } : {}),
             source: stdinPath ?? '<stdin>',
         };
         allResults.push(...(await lintDocument(content, opts)));
@@ -157,6 +188,7 @@ export const run = async (argv, options = {}) => {
                 ? {
                     ruleset: definition,
                     ...(basePath !== undefined ? { rulesetBasePath: basePath } : {}),
+                    ...(resolver ? { resolve: resolver } : {}),
                     source: file,
                 }
                 : { source: file };

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.10.0",
+  "version": "0.11.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -42,10 +42,12 @@
   },
   "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/lint": "0.1.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"
   },