@amritk/validation 0.2.0

package/AI.md

@@ -0,0 +1,92 @@
+# @amritk/validation — notes for AI coding agents
+
+One generator surface over mjst's types, guards, validators, coercers, repairers
+and parsers. It owns both generator engines: the validator/coercer/repairer one
+and the parser/type one, which used to ship as `@amritk/generate-validators` and
+`@amritk/generate-parsers` and are now internal modules here.
+
+> Pre-alpha: APIs and generated output change pre-1.0.
+
+## Minimal example
+
+```ts
+import { generate } from '@amritk/validation'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+const schema: JSONSchema = {
+  type: 'object',
+  properties: { title: { type: 'string' } },
+  required: ['title'],
+}
+
+const files = await generate(schema, 'Document', { modes: ['types', 'guard', 'validate', 'repair'] })
+// → document.ts, validation-result.ts, index.ts
+```
+
+## The modes
+
+| mode | emits | value back | tells you | stops at |
+|:---|:---|:---|:---|:---|
+| `types` | `X` | — | — | — |
+| `guard` | `isX` | — | a boolean | first problem |
+| `validate` | `validateX` | — | every error | the end |
+| `check` | `checkX` | — | the first error | first problem |
+| `coerce` | `coerceX` | coerced | every error | the end |
+| `repair` | `repairX` | repaired | repairs **and** errors | the end |
+| `parse` | `parseX` | repaired | nothing (total) | never |
+| `parseStrict` | `parseX` | as given | throws the first | first problem |
+
+## The same modes from the CLI
+
+Every mode is reachable from `mjst` without dropping to the programmatic API:
+
+| mode | flags |
+|:---|:---|
+| `types` | `--types-only` (alone), otherwise always emitted |
+| `guard`, `validate` | `--validators`, or `--validators-only` for no parser |
+| `check` | `--check` |
+| `coerce` | `--coerce` |
+| `repair` | `--repair` (emits `coerceX` too) |
+| `parse` | the default on any run that is not `--types-only`/`--validators-only` |
+| `parseStrict` | `--strict` |
+
+`--validators-only` is this package's own default (`['types', 'guard', 'validate']`)
+spelled as a flag: everything that judges a document, nothing that builds one.
+
+## Gotchas — where agents fail
+
+1. **Options object, not positional booleans.** `generate(schema, typeName, options)`.
+   The two engines underneath take long positional argument lists; this is the
+   only entry point, and they are not reachable from outside the package.
+2. **The default is `['types', 'guard', 'validate']`** — read-only. Anything that
+   rewrites a document (`coerce`, `repair`, `parse`) is opt-in.
+3. **`parse` and `parseStrict` are mutually exclusive** and `generate` throws if
+   you ask for both: they are one function name under two contracts.
+4. **One type, two files.** The type is declared once, in `x.ts`, alongside the
+   validator half. The parser half lands in `x.parse.ts` and imports the type. Do
+   not expect `parseX` in `x.ts`, and do not expect a second `export type X`
+   anywhere — there is exactly one.
+5. **`repairX` reports `valid: true` for a *fully repaired* document**, with a
+   non-empty `repairs`. `result.valid` alone does not mean the input was clean;
+   check `repairs.length` when that matters.
+6. **`guard` is the fail-fast mode and it is much cheaper on bad input** — it
+   short-circuits and builds no error object. It is also, counter-intuitively,
+   *not* faster than `validateX` on input that is valid, where both must check
+   everything. Pick `guard` when the answer is a branch, `validate` when someone
+   has to be told what to fix.
+7. **`check` is the middle of those two, and it returns `validateX`'s type.**
+   `checkX` hands back the same `true | { valid: false, errors }`, with exactly
+   one error in it — the one `validateX` would have reported first, same `path`,
+   `keyword` and `params` — so error-handling code is shared between the two.
+   Pick it when a failure has to be reported but only the first thing wrong
+   matters. Do not build it by hand out of the other two: `isX(v) ? true :
+   validateX(v)` pays for both passes and is no faster than `validateX`.
+
+8. **It emits each engine's exact bytes.** A single-mode build is byte-identical
+   to what that engine emitted when it was its own package, so there is no runtime
+   difference to reason about and no speedup to claim — do not tell a user this is
+   faster. What it changes is that the whole matrix comes out as one type instead
+   of two, and that a build asking for no validator mode ships no
+   `validation-result.ts`.
+
+Only the `.` entry. Install: `bun add @amritk/validation`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amritk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+<div align="center">
+
+# @amritk/validation
+
+**One generator surface over mjst's types, guards, validators, coercers, repairers and parsers.**
+
+</div>
+
+---
+
+## Overview
+
+`@amritk/validation` is the front door. Given a JSON Schema (Draft 2020-12) it emits
+one coherent set of TypeScript files carrying whichever runtime entry points you
+ask for — from a bare type, through a boolean guard and a full error report, to a
+coercer, a repairer and a total parser.
+
+Underneath it are **two** generator engines, not one: a validator, coercer and
+repairer engine, and a parser and type engine. They shipped separately as
+`@amritk/generate-validators` and `@amritk/generate-parsers` until this package
+absorbed them, and keeping both is deliberate. They emit genuinely different
+code for the value-producing modes: a parser fuses building the output with
+checking it, and is several times faster for it; a validator keeps the passes
+apart, and can therefore report what was wrong. Collapsing them into one emitter
+would mean giving up one of those properties.
+
+What makes one output directory possible is that both derive the TypeScript type
+from the same `@amritk/helpers/generate-type-definition`, so the type is declared
+**once** and every function in the output is talking about it.
+
+---
+
+## Installation
+
+```bash
+bun add @amritk/validation
+```
+
+---
+
+## Usage
+
+```typescript
+import { generate } from '@amritk/validation'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+const schema: JSONSchema = {
+  type: 'object',
+  properties: {
+    retries: { type: 'integer', minimum: 0, maximum: 10, default: 3 },
+    name: { type: 'string', minLength: 3 },
+  },
+  required: ['retries', 'name'],
+}
+
+const files = await generate(schema, 'Config', {
+  modes: ['types', 'guard', 'validate', 'coerce', 'repair', 'parse'],
+})
+
+for (const file of files) await Bun.write(`./generated/${file.filename}`, file.content)
+```
+
+---
+
+## The modes
+
+Each mode is a different answer to *how much may this do to my document, and what
+do I get told*. They compose: ask for several and you get several functions over
+one type, and every one that judges a value judges it with the same `validateX`,
+so no two can disagree about whether a document is valid.
+
+| mode | function | value back | tells you | stops at |
+|:---|:---|:---|:---|:---|
+| `types` | — | — | — | — |
+| `guard` | `isX(input): input is X` | — | a boolean | the first problem |
+| `validate` | `validateX(input)` | — | every error | the end |
+| `coerce` | `coerceX(input)` | coerced | every error | the end |
+| `repair` | `repairX(input)` | repaired | repairs **and** errors | the end |
+| `parse` | `parseX(input)` | repaired | nothing | never fails |
+| `parseStrict` | `parseX(input)` | as given | throws the first | the first problem |
+
+**Validate only, fail fast or find every error.** `guard` is the fail-fast half:
+it stops at the first thing wrong and builds no error object, which on invalid
+input is dramatically cheaper than reporting. `validate` is the other half: every
+error, each with a JSON Pointer, the keyword that rejected the value, and that
+keyword's own values. Reach for `guard` when the answer is a branch and
+`validate` when a human or an API client has to be told what to fix.
+
+**Coerce and repair, with or without the errors.** `coerceX` and `repairX` hand
+back the value *and* the diagnostics; `parseX` hands back only the value and
+never fails. Coercion moves a value that is already right but written in the
+wrong type; repair also substitutes a value the schema supplies for one that
+cannot be coerced, and reports the validator's own errors as the repairs.
+
+`parse` and `parseStrict` are the same function name under two contracts, so
+asking for both is an error rather than a silent choice.
+
+---
+
+## API
+
+### `generate(rootSchema, rootTypeName, options?)`
+
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `rootSchema` | `JSONSchema` | — | The root schema. `$ref` and `$dynamicRef` are resolved recursively. |
+| `rootTypeName` | `string` | — | Name for the root type (e.g. `"Config"`). |
+| `options.modes` | `Mode[]` | `['types', 'guard', 'validate']` | Which entry points to emit. The default is read-only; anything that rewrites a document is opt-in. |
+| `options.typeSuffix` | `string` | `''` | Suffix on every `$ref`-derived type name. The root name is untouched. |
+| `options.schemas` | `Record<string, unknown>` | — | Documents you have already loaded, keyed by the URI a `$ref` names them by. |
+| `options.unknownKeys` | `'count-keys' \| 'count-enumerable'` | `'count-keys'` | How a closed object's fast path proves it carries no undeclared key. |
+| `options.formats` | `'all' \| string[]` | — | String `format`s the validators enforce. Unset leaves `format` an annotation. |
+| `options.branchErrors` | `boolean` | `false` | Explain a failing `anyOf` / `oneOf` with the branch it plainly meant. |
+| `options.stripUnknown` | `boolean` | `false` | Build each parsed result from the declared properties only. |
+| `options.readonly` | `boolean` | `false` | Emit `readonly` type members. |
+| `options.caseInsensitive` | `boolean` | `false` | Normalize a mis-cased string onto an `enum` member it matches. |
+| `options.helpersMode` | `'package' \| 'embedded'` | `'package'` | Where the parser half gets its runtime helpers. |
+| `options.extensions` | `SchemaExtensions` | — | Schema extensions, passed through to the parser half. |
+
+Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
+
+---
+
+## Output layout
+
+```
+config.ts         the type, plus isX / validateX / coerceX / repairX
+config.parse.ts   parseX, importing the type from ./config.js
+validation-result.ts   the shared error and result types, and the runtime helpers
+index.ts          a barrel over all of it
+```
+
+The type lives in `config.ts` because that is where a reader looks for it. The
+parser half moves to `config.parse.ts` because both generators name their file
+after the schema and one of them has to give way. There is exactly one
+`export type Config` in the output, whatever combination of modes you asked for
+— which the test suite asserts, over a corpus of schema shapes, by compiling the
+result under this repo's own flags.
+
+Ask for no validator mode and there is nothing to collide with, so the parser
+keeps both its own filename and the type it already authored, and no
+`validation-result.ts` is emitted at all — a parse-only build has nothing that
+could import its 17 KiB of error types and runtime helpers.
+
+---
+
+## Is it faster?
+
+No, and it should not be. Ask this package for one mode and it emits **the exact
+bytes** the engine that owns that mode emits — which the test suite pins per
+mode, by fingerprint, not by reading the output. Identical code cannot
+run at a different speed, so there is no runtime claim to make here and none is
+made. `bun run bench` measures it anyway, and the deltas wander either side of
+zero between runs, which is what process-level variance looks like when there is
+no underlying difference.
+
+What does change is the cold side, and only in the direction you would hope:
+
+| | before (both engines directly) | after |
+|:---|:---|:---|
+| codegen for the whole matrix | 2.9 ms | 2.7 ms |
+| emitted bytes | 46.0 KiB | 45.8 KiB |
+| files | 7 | 6 |
+| declarations of `Order` | **2** | **1** |
+| per-mode codegen | — | equal or slightly lower |
+| per-mode bytes | — | identical |
+
+The one that matters is the last row of the middle block. Reaching every mode
+used to mean running both generators yourself and shipping two trees for one
+schema, including two declarations of the same type — structurally
+interchangeable, but two things to keep in step. Now there is one.
+
+---
+
+## Related packages
+
+- [`@amritk/helpers`](../helpers) — the shared type definition and fallback tables both engines read
+- [`@amritk/mjst`](../cli) — the command-line interface
+
+---
+
+## License
+
+MIT

package/dist/generate.d.ts

@@ -0,0 +1,135 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { buildSchema } from './parsers/index.js';
+/** The extension emitted on relative import specifiers. */
+export type ImportExtension = 'js' | 'ts';
+/** A generated TypeScript file, as every mjst generator hands one back. */
+export type GeneratedFile = {
+    filename: string;
+    content: string;
+};
+/**
+ * One runtime entry point the generated output can carry. Each is a different
+ * answer to "how much may this do to my document, and what do I get told".
+ *
+ * They compose rather than compete: asking for several emits several functions
+ * over one shared type, and the ones that judge a value all judge it with the
+ * same `validateX`, so no two can disagree about whether a document is valid.
+ */
+export type Mode = 
+/** `X` — the TypeScript type, and nothing that runs. Always emitted. */
+'types'
+/**
+ * `isX(input): input is X` — a type guard. Stops at the first thing wrong and
+ * builds no error object, which on invalid input is dramatically cheaper than
+ * any mode that reports: the check that fails is usually the first one tried.
+ * Use it when the answer is a branch, not a message.
+ */
+ | 'guard'
+/**
+ * `validateX(input): ValidationResult` — every error, each with a JSON Pointer,
+ * the keyword that rejected the value and that keyword's own values. Use it
+ * when a human or an API client has to be told what to fix.
+ */
+ | 'validate'
+/**
+ * `checkX(input): ValidationResult` — the same result `validateX` returns, with
+ * the one error that stopped it. Use it when a failure has to be reported but
+ * only the first thing wrong matters: it costs a single error object and walks
+ * no further, where `validateX` keeps going to collect the rest.
+ */
+ | 'check'
+/**
+ * `coerceX(input): CoercionResult<X>` — move a scalar toward the declared type
+ * where the schema leaves no choice, then validate. Substitutes nothing, so a
+ * value it cannot coerce is rejected as written.
+ */
+ | 'coerce'
+/**
+ * `repairX(input): RepairResult<X>` — coerce, validate, then repair each
+ * rejected position to a value the schema supplies, reporting the validator's
+ * own errors as the repairs. Tolerant, and never silently so.
+ */
+ | 'repair'
+/**
+ * `parseX(input): X` — a total function. Repairs whatever it is given and
+ * always returns a valid instance, reporting nothing. The fastest way to get a
+ * usable value when you do not care what was wrong with the input.
+ */
+ | 'parse'
+/**
+ * `parseX(input): X` that throws on the first violation instead of repairing.
+ * Mutually exclusive with `'parse'` — they are the same function under two
+ * contracts.
+ */
+ | 'parseStrict';
+/** Every mode, for a caller who wants the lot. */
+export declare const ALL_MODES: readonly Mode[];
+export type GenerateOptions = {
+    /**
+     * Which entry points to emit. Defaults to `['types', 'guard', 'validate']` —
+     * the modes that only ever read the document. Anything that rewrites a value
+     * is opt-in, because a generator that quietly starts repairing documents is
+     * not one you can trust by default.
+     */
+    readonly modes?: readonly Mode[];
+    /** Suffix appended to every `$ref`-derived type name. The root name is untouched. */
+    readonly typeSuffix?: string;
+    /** Documents already loaded, keyed by the absolute URI a `$ref` names them by. */
+    readonly schemas?: Readonly<Record<string, unknown>>;
+    /** How a closed object's fast path proves it carries no undeclared key. */
+    readonly unknownKeys?: UnknownKeysStrategy;
+    /** String `format`s the generated validators enforce. Unset leaves `format` an annotation. */
+    readonly formats?: 'all' | readonly string[];
+    /** Explain a failing `anyOf` / `oneOf` with the errors of the branch it plainly meant. */
+    readonly branchErrors?: boolean;
+    /** Build each parsed result from the declared properties only, dropping undeclared keys. */
+    readonly stripUnknown?: boolean;
+    /** Emit `readonly` type members. */
+    readonly readonly?: boolean;
+    /** Normalize a mis-cased string onto an `enum` member it matches case-insensitively. */
+    readonly caseInsensitive?: boolean;
+    /** Where the parser half gets its runtime helpers: the published package, or emitted sources. */
+    readonly helpersMode?: 'package' | 'embedded';
+    /** Prefix on emitted-helper import specifiers, when `helpersMode` is `'embedded'`. */
+    readonly helpersImportPrefix?: string;
+    /** Schema extensions, keyed by definition name, passed through to the parser half. */
+    readonly extensions?: Parameters<typeof buildSchema>[2];
+    /**
+     * Extension on every emitted relative import specifier. `'js'` (the default) is
+     * the standard NodeNext form a compiled consumer needs; `'ts'` emits the literal
+     * on-disk paths, so the output runs directly under Node's type stripping with no
+     * build step.
+     *
+     * It reaches both halves, which is not a detail: they share one directory here,
+     * and a set where the parser files say `.ts` and the validator files say `.js`
+     * is one that resolves under neither runtime.
+     */
+    readonly importExt?: ImportExtension;
+    /**
+     * Print warnings the parser generator raises about the schema — a keyword it
+     * cannot enforce, a construct it had to widen. Off by default because this is a
+     * library call, and a library that writes to stdout is a nuisance in anything
+     * that embeds it.
+     */
+    readonly logWarnings?: boolean;
+};
+/**
+ * Generates one coherent set of files for a schema, carrying whichever entry
+ * points were asked for.
+ *
+ * This composes the two generator engines that live beside it, `./parsers` and
+ * `./validators`, rather than reimplementing either. That is deliberate: the two
+ * emit genuinely different code for the value-producing modes — a parser fuses
+ * building the output with checking it and is several times faster for it, while
+ * a validator keeps the passes apart and can therefore report — and collapsing
+ * them into one emitter would mean giving up one of those properties. Composing
+ * keeps both and spends the cost on reconciling their output instead, which is
+ * bounded and testable.
+ *
+ * What makes the reconciliation honest is that both generators derive the type
+ * from the same `@amritk/helpers/generate-type-definition`, so the type is
+ * emitted once and the parser half imports it. There is exactly one `X` in the
+ * output, and every function in it is talking about the same type.
+ */
+export declare const generate: (rootSchema: JSONSchema, rootTypeName: string, options?: GenerateOptions) => Promise<GeneratedFile[]>;

package/dist/generate.js

@@ -0,0 +1,74 @@
+import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
+import { buildSchema } from "./parsers/index.js";
+import { buildValidatorSchema } from "./validators/index.js";
+import { rehomeParserFile } from "./rehome-parser-file.js";
+const ALL_MODES = ["types", "guard", "validate", "check", "coerce", "repair", "parse"];
+const VALIDATOR_MODES = /* @__PURE__ */ new Set(["guard", "validate", "check", "coerce", "repair"]);
+const PARSER_MODES = /* @__PURE__ */ new Set(["parse", "parseStrict"]);
+const PARSER_SUFFIX = ".parse";
+const wants = (modes, group) => modes.some((mode) => group.has(mode));
+const generate = async (rootSchema, rootTypeName, options = {}) => {
+  const modes = options.modes ?? ["types", "guard", "validate"];
+  if (modes.includes("parse") && modes.includes("parseStrict")) {
+    throw new Error("modes 'parse' and 'parseStrict' are the same function under two contracts \u2014 one repairs and always returns a value, the other throws on the first violation. Ask for one.");
+  }
+  const typeSuffix = options.typeSuffix ?? "";
+  const unknownKeys = options.unknownKeys ?? DEFAULT_UNKNOWN_KEYS;
+  const importExt = options.importExt ?? "js";
+  const needsValidator = wants(modes, VALIDATOR_MODES);
+  const needsParser = wants(modes, PARSER_MODES);
+  const files = [];
+  const parserFiles = async () => buildSchema(
+    rootSchema,
+    rootTypeName,
+    options.extensions,
+    !needsParser,
+    // typesOnly — when the parser is only here to author the type
+    options.logWarnings === true,
+    modes.includes("parseStrict"),
+    options.helpersMode ?? "package",
+    options.helpersImportPrefix ?? "./",
+    options.readonly === true,
+    options.stripUnknown === true,
+    typeSuffix,
+    importExt,
+    options.caseInsensitive === true,
+    options.schemas,
+    unknownKeys
+  );
+  if (!needsValidator) {
+    for (const file of await parserFiles()) {
+      if (file.filename !== "index.ts")
+        files.push(file);
+    }
+    files.push({ filename: "index.ts", content: generateIndexBarrel(files, { importExt }) });
+    return files;
+  }
+  const validatorFiles = await buildValidatorSchema(rootSchema, rootTypeName, typeSuffix, options.schemas, unknownKeys, options.formats, modes.includes("coerce") || modes.includes("repair"), options.branchErrors === true, modes.includes("repair"), importExt, modes.includes("check"));
+  for (const file of validatorFiles) {
+    if (file.filename !== "index.ts")
+      files.push(file);
+  }
+  if (needsParser) {
+    for (const file of await parserFiles()) {
+      if (file.filename === "index.ts")
+        continue;
+      if (file.filename.includes("/")) {
+        files.push(file);
+        continue;
+      }
+      const moduleName = file.filename.replace(/\.ts$/, "");
+      files.push({
+        filename: `${moduleName}${PARSER_SUFFIX}.ts`,
+        content: rehomeParserFile(file.content, moduleName, PARSER_SUFFIX, importExt)
+      });
+    }
+  }
+  files.push({ filename: "index.ts", content: generateIndexBarrel(files, { importExt }) });
+  return files;
+};
+export {
+  ALL_MODES,
+  generate
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { ALL_MODES, type GeneratedFile, type GenerateOptions, generate, type ImportExtension, type Mode, } from './generate.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+import { ALL_MODES, generate } from "./generate.js";
+export {
+  ALL_MODES,
+  generate
+};

package/dist/parsers/generators/assert-supported-keywords.d.ts

@@ -0,0 +1,30 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { type StrictAssertionContext } from './generate-strict-assertion.js';
+/**
+ * Throws when a schema (anywhere in its subtree) uses a keyword the *strict*
+ * parser generator cannot enforce but which narrows the set of valid documents.
+ * Mirrors the validator engine's `assertNoUnsupportedKeywords`: failing loudly at
+ * generation time is strictly better than silently emitting a parser that
+ * accepts input the schema forbids — a strict parser promises to "throw on
+ * violations".
+ *
+ * Two families are rejected:
+ *
+ *  - `contains`, `not`, `propertyNames`, or `dependentSchemas` whose subschema
+ *    uses a form {@link canMatchSubschema} cannot prove inline (a cyclic `$ref`,
+ *    an unknown keyword). The parser enforces these keywords only for subschemas
+ *    it can match exactly; anything else would be silently ignored.
+ *
+ *  - A node whose enforcement rests on the whole-schema backstop (see
+ *    {@link backstopReason} — `unevaluatedProperties` / `unevaluatedItems`, a
+ *    `$ref` nothing delegates, a type-less constraint) when the matcher cannot
+ *    build that backstop.
+ *
+ * Everything the matcher *can* prove is enforced rather than refused, which is
+ * why `unevaluated*` and `$ref`-carrying subschemas no longer fail outright.
+ *
+ * This runs for strict generation only — coercing parsers are documented to be
+ * permissive (they repair rather than reject), so ignoring these keywords there
+ * is the contract, not a lie.
+ */
+export declare const assertNoUnsupportedKeywords: (schema: JSONSchema, typeName: string, context?: StrictAssertionContext) => void;

package/dist/parsers/generators/assert-supported-keywords.js

@@ -0,0 +1,87 @@
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { backstopReason, backstopSchema } from "./generate-strict-assertion.js";
+import { canMatchSubschema } from "./subschema-match.js";
+const SUBSCHEMA_KEYS = [
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "contains",
+  "additionalProperties",
+  "propertyNames",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "not",
+  "if",
+  "then",
+  "else",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "contentSchema"
+];
+const SUBSCHEMA_MAP_KEYS = [
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions"
+];
+const assertNoUnsupportedKeywords = (schema, typeName, context = {}) => {
+  const rootSchema = context.rootSchema ?? (isSchemaObject(schema) ? schema : void 0);
+  const provable = (sub) => canMatchSubschema(sub, rootSchema);
+  const fail = (keyword, detail) => {
+    throw new Error(`[${typeName}] unsupported keyword "${keyword}": the strict parser generator ${detail}, and would silently accept documents the schema rejects. Generate a coercing (non-strict) parser, validate this schema with a validate mode instead of parseStrict, or remove the keyword.`);
+  };
+  const visit = (node) => {
+    if (typeof node !== "object" || node === null || Array.isArray(node))
+      return;
+    const record = node;
+    if ("contains" in record && !provable(record["contains"])) {
+      fail("contains", "cannot prove its subschema inline");
+    }
+    if ("not" in record && !provable(record["not"])) {
+      fail("not", "cannot prove its subschema inline");
+    }
+    if ("propertyNames" in record && isSchemaObject(record["propertyNames"])) {
+      if (!provable(record["propertyNames"])) {
+        fail("propertyNames", "cannot prove its subschema inline");
+      }
+    }
+    const dependentSchemas = record["dependentSchemas"];
+    if (typeof dependentSchemas === "object" && dependentSchemas !== null && !Array.isArray(dependentSchemas)) {
+      for (const sub of Object.values(dependentSchemas)) {
+        if (typeof sub === "boolean")
+          continue;
+        if (!provable(sub)) {
+          fail("dependentSchemas", "cannot prove one of its subschemas inline");
+        }
+      }
+    }
+    const reason = backstopReason(node, context);
+    if (reason !== null && !provable(backstopSchema(node, reason))) {
+      fail(reason, "cannot prove the schema it appears in inline");
+    }
+    for (const keyword of SUBSCHEMA_KEYS) {
+      const value = record[keyword];
+      if (value === void 0)
+        continue;
+      if (Array.isArray(value)) {
+        for (const item of value)
+          visit(item);
+      } else {
+        visit(value);
+      }
+    }
+    for (const keyword of SUBSCHEMA_MAP_KEYS) {
+      const value = record[keyword];
+      if (typeof value !== "object" || value === null || Array.isArray(value))
+        continue;
+      for (const sub of Object.values(value))
+        visit(sub);
+    }
+  };
+  visit(schema);
+};
+export {
+  assertNoUnsupportedKeywords
+};