@amritk/generate-examples 0.5.6 → 0.6.1

package/AI.md

@@ -24,13 +24,29 @@ const files = await buildExampleSchema(schema, 'User') // → user.ts, index.ts
 
 1. **Generated arbitrary files `import * as fc from 'fast-check'`** — `fast-check`
    (`>=3`) is an **optional peer dependency** consumers must install. The static
-   `fooExample` values have no runtime deps.
+   `fooExample` values have no runtime deps. A generated file whose schema uses
+   `if`/`then`/`else`, `not`, `oneOf`, `patternProperties`, `propertyNames`,
+   `dependentRequired`, `dependentSchemas`, `dependencies`, `minProperties`,
+   `maxProperties`, or `contains` **also** imports `@amritk/runtime-validators`
+   for its validating filter. That one is a `dependency` of this package, not a
+   peer — the generator imports it too — so it resolves for the generator but not
+   necessarily from the consumer's own tree, where the generated file lives.
+   Under pnpm-strict or Yarn PnP, install it directly. It cannot be declared a
+   peer as well: Bun rejects a workspace package listed as both, and
+   `--frozen-lockfile` then fails repo-wide.
 2. **`generateArbitrary` / `generateExampleConst` return source-code STRINGS**;
    **`deriveExample` returns an actual runtime VALUE.** Easy to confuse.
-3. **A static example constrained only by `pattern` may not match the pattern** —
-   use the arbitrary when pattern fidelity matters.
+3. **A static example is validated against its own schema before it is emitted.**
+   If it fails, it is written anyway (the module must compile) and the generator
+   `console.warn`s, naming the type. That happens when the schema has no instance
+   at all, or when the constraint is beyond the deriver (a `pattern` with
+   lookarounds/backreferences, an unrecognized `format`). Use `FooArbitrary`
+   there — it carries a runtime validating filter and stays correct.
 4. **Unsupported keywords degrade silently:** `fc.anything()` in arbitraries,
    `null` in static examples — no error thrown.
+5. **`deriveExample` memoizes each `$ref` per root document**, so the returned
+   value can share sub-objects with the value derived for a sibling schema.
+   Treat it as read-only.
 
 Exports: `buildExampleSchema`, `generateArbitrary`, `generateExampleConst`,
 `deriveExample`, `serializeValue`, `GeneratedFile`. Only the `.` entry.

package/README.md

@@ -39,6 +39,15 @@ An `index.ts` barrel re-exports everything.
 > and the presence-gated object keywords) also imports `@amritk/runtime-validators`
 > for a post-generation validating filter; files that need no such filter don't.
 > The static `fooExample` values have no runtime dependencies.
+>
+> `@amritk/runtime-validators` is a `dependency` here rather than a peer, because
+> this generator imports it itself. That resolves it for the generator, but *not*
+> necessarily for the generated file — that file lands in **your** source tree, so
+> under pnpm's strict layout or Yarn PnP it resolves from your project, not from
+> this package's. If your schemas use any of those keywords, install it directly
+> (`npm i @amritk/runtime-validators`). It cannot also be declared a peer: Bun
+> rejects a workspace package listed as both, and `--frozen-lockfile` then fails
+> for the whole repo.
 
 ---
 
@@ -128,8 +137,7 @@ const res = await fetch('/users', { method: 'POST', body: JSON.stringify(userExa
 `type` — including multi-type unions like `['string', 'null']` —
 (string/number/integer/boolean/null/array/object), `properties`,
 `required`, `items`, `minItems`/`maxItems`, `uniqueItems`,
-`minLength`/`maxLength`, `pattern`, `format` (`email`, `uuid`, `uri`/`url`,
-`date`, `date-time`, `time`, `hostname`, `ipv4`, `ipv6`), `minimum`/`maximum`,
+`minLength`/`maxLength`, `pattern`, `format`, `minimum`/`maximum`,
 `exclusiveMinimum`/`exclusiveMaximum`, `multipleOf`, `enum` (filtered by sibling
 constraints), `const`, `minProperties`/`maxProperties`, `patternProperties`,
 `propertyNames`, `dependentRequired`, `dependentSchemas`, `contains`,
@@ -139,9 +147,37 @@ enforced by validating generated candidates against the schema and
 retrying/rejecting. Unsupported constructs degrade to `fc.anything()` in
 arbitraries and `null` in static examples.
 
+Static examples cover every `format` `@amritk/runtime-validators` knows how to
+check: `email`, `idn-email`, `date`, `date-time`, `time`, `duration`, `uuid`,
+`uri`, `iri`, `uri-reference`, `iri-reference`, `uri-template`, `json-pointer`,
+`relative-json-pointer`, `hostname`, `idn-hostname`, `ipv4`, `ipv6`, `regex`,
+plus OpenAPI's `url`. An unrecognized `format` falls back to `"string"`.
+
+---
+
+## Known limits
+
+Every `fooExample` is validated against its own schema before it is written. When
+the value does not satisfy the schema it is still emitted — so the module always
+compiles — but the generator prints a `console.warn` naming the type. Reach for
+`FooArbitrary` in those cases: the arbitrary carries a runtime validating filter
+and stays correct where the static value cannot.
+
+The value falls short for two reasons:
+
+- **The schema has no instance.** `{ pattern: '^ab$', minLength: 5 }`,
+  `uniqueItems` over booleans with `minItems: 3`, a `required` key that
+  `additionalProperties: false` forbids, or a `oneOf` whose branches every value
+  matches twice. Nothing correct exists to emit; the warning is pointing at the
+  schema, not the generator.
+- **The constraint is beyond the deriver.** `pattern` is sampled by a
+  best-effort recursive-descent walk of the regex, so lookarounds and
+  backreferences fall back to `"string"`; an unrecognized `format` does the same.
+
 > [!TIP]
-> A static example constrained only by `pattern` is not guaranteed to match the
-> pattern — reach for the arbitrary when pattern fidelity matters.
+> The example for a `$ref` is inlined by value, so a definition graph with wide
+> fan-out produces a correspondingly large literal. That cost is in the output
+> size, not in generation time — each definition is derived once per document.
 
 ---
 

package/dist/generators/derive-example.d.ts

@@ -4,13 +4,21 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  *
  * Prefers explicit hints in this order: `const`, `examples[0]`, `default`,
  * `enum[0]`; otherwise produces a canonical value for the declared type.
- * `$ref`s are resolved and inlined by value; recursive refs short-circuit to
- * `null` (tracked via `seen`).
+ * `$ref`s are resolved and inlined by value; a recursive ref short-circuits to
+ * `null` where the cycle closes.
  *
- * Note: values constrained only by `pattern` are not guaranteed to match the
- * pattern — use the generated arbitrary when pattern fidelity matters.
+ * Derived values are memoized per `$ref` per root document, so the returned
+ * value may share sub-objects with a value returned for a sibling schema. That
+ * is safe for the generator (it serializes and never mutates), but treat the
+ * result as read-only.
+ *
+ * Some schemas have no derivable instance (an unsatisfiable `pattern` +
+ * `minLength`, a `oneOf` every candidate matches twice); this returns the
+ * closest structural value it built. {@link generateExampleConst} validates the
+ * final value and warns when that happens, rather than letting an invalid
+ * example ship silently.
  */
-export declare const deriveExample: (schema: JSONSchema, rootSchema?: Record<string, unknown>, seen?: ReadonlySet<string>) => unknown;
+export declare const deriveExample: (schema: JSONSchema, rootSchema?: Record<string, unknown>) => unknown;
 export declare const mergeAllOf: (schema: JSONSchema) => JSONSchema;
 /**
  * Serializes a derived value into a TypeScript source expression. Handles the
@@ -21,6 +29,10 @@ export declare const serializeValue: (value: unknown) => string;
 /**
  * Generates an exported const holding a concrete, schema-valid example value.
  *
+ * The derived value is validated against its own schema before being emitted; a
+ * value that fails is still written (so the generated file compiles) but is
+ * reported via `console.warn` rather than shipping as a silently-wrong fixture.
+ *
  * @example
  * ```typescript
  * generateExampleConst({ type: 'object', properties: { name: { type: 'string' } } }, 'Info')

package/dist/generators/derive-example.js

@@ -14,6 +14,13 @@ const charForClass = (inner) => {
   const first = inner.replace(/^\^/, "")[0];
   return first && first !== "\\" ? first : "a";
 };
+const CONTROL_ESCAPES = {
+  n: "\n",
+  r: "\r",
+  t: "	",
+  f: "\f",
+  v: "\v"
+};
 const charForEscape = (esc) => {
   if (esc === "\\d")
     return "5";
@@ -21,7 +28,10 @@ const charForEscape = (esc) => {
     return "a";
   if (esc === "\\s")
     return " ";
-  return esc[1] ?? "a";
+  const char = esc[1];
+  if (char === void 0)
+    return "a";
+  return CONTROL_ESCAPES[char] ?? char;
 };
 const topLevelAlternatives = (s) => {
   const parts = [];
@@ -144,34 +154,40 @@ const sampleFromPattern = (pattern, minLength) => {
   };
   return sampleAlt(body);
 };
+const FORMAT_EXAMPLES = {
+  email: "user@example.com",
+  "idn-email": "user@example.com",
+  uuid: "00000000-0000-0000-0000-000000000000",
+  uri: "https://example.com",
+  iri: "https://example.com",
+  // `url` is not a JSON Schema format, but OpenAPI documents use it constantly.
+  url: "https://example.com",
+  "uri-reference": "https://example.com",
+  "iri-reference": "https://example.com",
+  "uri-template": "https://example.com/{id}",
+  "date-time": "1970-01-01T00:00:00.000Z",
+  date: "1970-01-01",
+  time: "00:00:00.000Z",
+  duration: "P1D",
+  "json-pointer": "/example",
+  "relative-json-pointer": "0/example",
+  hostname: "example.com",
+  "idn-hostname": "example.com",
+  ipv4: "127.0.0.1",
+  ipv6: "::1",
+  // The `regex` format asks for a string that *compiles* as a regular expression.
+  regex: "^example$"
+};
 const exampleString = (schema) => {
   if (hasFormat(schema)) {
-    switch (schema.format) {
-      case "email":
-        return "user@example.com";
-      case "uuid":
-        return "00000000-0000-0000-0000-000000000000";
-      case "uri":
-      case "url":
-        return "https://example.com";
-      case "date-time":
-        return "1970-01-01T00:00:00.000Z";
-      case "date":
-        return "1970-01-01";
-      case "time":
-        return "00:00:00.000Z";
-      case "hostname":
-        return "example.com";
-      case "ipv4":
-        return "127.0.0.1";
-      case "ipv6":
-        return "::1";
-    }
+    const formatted = FORMAT_EXAMPLES[schema.format];
+    if (formatted !== void 0)
+      return formatted;
   }
   const minLength = hasMinLength(schema) ? schema.minLength : 0;
   if (hasPattern(schema)) {
     const sampled = sampleFromPattern(schema.pattern, minLength);
-    if (sampled !== void 0 && new RegExp(schema.pattern).test(sampled)) {
+    if (sampled !== void 0 && sampled.length >= minLength && new RegExp(schema.pattern).test(sampled)) {
       if (!(hasMaxLength(schema) && sampled.length > schema.maxLength))
         return sampled;
     }
@@ -183,13 +199,61 @@ const exampleString = (schema) => {
     value = value.slice(0, schema.maxLength);
   return value;
 };
-const deriveExample = (schema, rootSchema, seen = /* @__PURE__ */ new Set()) => {
+const contexts = /* @__PURE__ */ new WeakMap();
+const newContext = (rootSchema) => ({
+  rootSchema,
+  values: /* @__PURE__ */ new Map(),
+  active: /* @__PURE__ */ new Set(),
+  cycleBroken: false
+});
+const contextFor = (rootSchema) => {
+  if (rootSchema === void 0)
+    return newContext(void 0);
+  const existing = contexts.get(rootSchema);
+  if (existing)
+    return existing;
+  const created = newContext(rootSchema);
+  contexts.set(rootSchema, created);
+  return created;
+};
+const deriveExample = (schema, rootSchema) => {
+  const ctx = contextFor(rootSchema);
+  ctx.active.clear();
+  ctx.cycleBroken = false;
+  return derive(schema, ctx);
+};
+const derive = (schema, ctx) => {
   if (!isSchemaObject(schema))
     return null;
-  const base = deriveBase(schema, rootSchema, seen);
-  return needsValidationFilter(schema) ? refineExample(schema, base, rootSchema, seen) : base;
+  const base = deriveBase(schema, ctx);
+  return needsValidationFilter(schema) ? refineExample(schema, base, ctx) : base;
 };
-const deriveBase = (schema, rootSchema, seen) => {
+const deriveRef = (ref, ctx) => {
+  if (ctx.active.has(ref)) {
+    ctx.cycleBroken = true;
+    return null;
+  }
+  if (ctx.values.has(ref))
+    return ctx.values.get(ref);
+  if (!ctx.rootSchema)
+    return null;
+  const resolved = resolveRef(ref, ctx.rootSchema);
+  if (!resolved)
+    return null;
+  const outerBroken = ctx.cycleBroken;
+  ctx.cycleBroken = false;
+  ctx.active.add(ref);
+  try {
+    const value = derive(resolved, ctx);
+    if (!ctx.cycleBroken)
+      ctx.values.set(ref, value);
+    ctx.cycleBroken = outerBroken || ctx.cycleBroken;
+    return value;
+  } finally {
+    ctx.active.delete(ref);
+  }
+};
+const deriveBase = (schema, ctx) => {
   if (!isSchemaObject(schema))
     return null;
   if (hasConst(schema))
@@ -202,15 +266,8 @@ const deriveBase = (schema, rootSchema, seen) => {
     const fitting = schema.enum.find((value) => satisfiesScalarConstraints(schema, value));
     return fitting !== void 0 ? fitting : schema.enum[0];
   }
-  if (hasRef(schema)) {
-    const ref = schema.$ref;
-    if (seen.has(ref) || !rootSchema)
-      return null;
-    const resolved = resolveRef(ref, rootSchema);
-    if (!resolved)
-      return null;
-    return deriveExample(resolved, rootSchema, /* @__PURE__ */ new Set([...seen, ref]));
-  }
+  if (hasRef(schema))
+    return deriveRef(schema.$ref, ctx);
   const instanceOf = getMjstInstanceOf(schema);
   if (instanceOf === "Date")
     return /* @__PURE__ */ new Date(0);
@@ -218,15 +275,15 @@ const deriveBase = (schema, rootSchema, seen) => {
   if (primitive === "bigint")
     return 0n;
   if (hasAllOf(schema))
-    return deriveExample(mergeAllOf(schema), rootSchema, seen);
+    return derive(mergeAllOf(schema), ctx);
   if (hasOneOf(schema) && schema.oneOf[0] !== void 0)
-    return deriveExample(schema.oneOf[0], rootSchema, seen);
+    return derive(schema.oneOf[0], ctx);
   if (hasAnyOf(schema) && schema.anyOf[0] !== void 0)
-    return deriveExample(schema.anyOf[0], rootSchema, seen);
+    return derive(schema.anyOf[0], ctx);
   if (hasType(schema))
-    return deriveForType(schema.type, schema, rootSchema, seen);
+    return deriveForType(schema.type, schema, ctx);
   if (Array.isArray(schema.type) && schema.type.length > 0) {
-    return deriveForType(schema.type[0], schema, rootSchema, seen);
+    return deriveForType(schema.type[0], schema, ctx);
   }
   return null;
 };
@@ -237,13 +294,28 @@ const structuralOnly = (schema) => {
     delete clone[key];
   return clone;
 };
-const refineExample = (schema, base, rootSchema, seen) => {
-  const check = makeInstanceCheck(schema, rootSchema);
+const perturb = (value) => {
+  if (typeof value === "string")
+    return [`${value}-1`, ""];
+  if (typeof value === "number")
+    return [value + 1, value - 1];
+  if (typeof value === "boolean")
+    return [!value];
+  if (value === null)
+    return ["string", 0];
+  if (Array.isArray(value))
+    return [[], [...value, null]];
+  if (typeof value === "object")
+    return [{}];
+  return [];
+};
+const refineExample = (schema, base, ctx) => {
+  const check = makeInstanceCheck(schema, ctx.rootSchema);
   if (check(base))
     return base;
   const raw = schema;
   const structural = structuralOnly(schema);
-  const combine = (branch) => deriveExample({ allOf: [structural, branch] }, rootSchema, seen);
+  const combine = (branch) => derive({ allOf: [structural, branch] }, ctx);
   const candidates = [];
   if (hasOneOf(schema)) {
     for (const branch of schema.oneOf)
@@ -255,8 +327,10 @@ const refineExample = (schema, base, rootSchema, seen) => {
       candidates.push(combine(raw["then"]));
     if (raw["else"] !== void 0)
       candidates.push(combine(raw["else"]));
-    candidates.push(deriveExample(structural, rootSchema, seen));
+    candidates.push(derive(structural, ctx));
   }
+  if ("not" in raw)
+    candidates.push(...perturb(base));
   for (const candidate of candidates)
     if (check(candidate))
       return candidate;
@@ -282,7 +356,7 @@ const satisfiesScalarConstraints = (schema, value) => {
   }
   return true;
 };
-const deriveForType = (type, schema, rootSchema, seen) => {
+const deriveForType = (type, schema, ctx) => {
   switch (type) {
     case "string":
       return exampleString(schema);
@@ -294,14 +368,21 @@ const deriveForType = (type, schema, rootSchema, seen) => {
     case "null":
       return null;
     case "array":
-      return deriveArray(schema, rootSchema, seen);
+      return deriveArray(schema, ctx);
     case "object":
-      return deriveObject(schema, rootSchema, seen);
+      return deriveObject(schema, ctx);
     default:
       return null;
   }
 };
-const deriveObject = (schema, rootSchema, seen) => {
+const setProperty = (out, key, value) => {
+  if (key === "__proto__") {
+    Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+    return;
+  }
+  out[key] = value;
+};
+const deriveObject = (schema, ctx) => {
   const out = {};
   const patternEntries = hasPatternProperties(schema) ? Object.entries(schema.patternProperties).flatMap(([source, sub]) => {
     try {
@@ -314,7 +395,7 @@ const deriveObject = (schema, rootSchema, seen) => {
   const additionalSchema = isSchemaObject(additional) ? additional : void 0;
   const additionalClosed = hasAdditionalProperties(schema) && schema.additionalProperties === false;
   const extrasAllowed = !additionalClosed || patternEntries.length > 0;
-  const nameCheck = hasPropertyNames(schema) ? makeInstanceCheck(schema.propertyNames, rootSchema) : void 0;
+  const nameCheck = hasPropertyNames(schema) ? makeInstanceCheck(schema.propertyNames, ctx.rootSchema) : void 0;
   const valueSchemaFor = (key) => {
     const matches = patternEntries.filter(([re]) => re.test(key)).map(([, sub]) => sub);
     if (matches.length === 1)
@@ -325,31 +406,33 @@ const deriveObject = (schema, rootSchema, seen) => {
   };
   const addKey = (key) => {
     const sub = valueSchemaFor(key);
-    out[key] = sub !== void 0 ? deriveExample(sub, rootSchema, seen) : null;
+    if (sub === void 0 && additionalClosed)
+      return;
+    setProperty(out, key, sub !== void 0 ? derive(sub, ctx) : null);
   };
   if (hasProperties(schema)) {
     for (const [key, propSchema] of Object.entries(schema.properties)) {
-      out[key] = deriveExample(propSchema, rootSchema, seen);
+      setProperty(out, key, derive(propSchema, ctx));
     }
   }
   if (hasRequired(schema)) {
     for (const key of schema.required)
-      if (!(key in out))
+      if (!Object.hasOwn(out, key))
         addKey(key);
   }
   if (hasDependentRequired(schema)) {
     for (const [trigger, deps] of Object.entries(schema.dependentRequired)) {
-      if (!(trigger in out))
+      if (!Object.hasOwn(out, trigger))
         continue;
       for (const dep of deps)
-        if (!(dep in out))
+        if (!Object.hasOwn(out, dep))
           addKey(dep);
     }
   }
   if (hasDependentSchemas(schema)) {
     for (const [trigger, sub] of Object.entries(schema.dependentSchemas)) {
-      if (trigger in out && isSchemaObject(sub))
-        applyDependentSchema(out, sub, rootSchema, seen);
+      if (Object.hasOwn(out, trigger) && isSchemaObject(sub))
+        applyDependentSchema(out, sub, ctx);
     }
   }
   if (hasMinProperties(schema) && extrasAllowed) {
@@ -357,7 +440,7 @@ const deriveObject = (schema, rootSchema, seen) => {
     let guard = 0;
     while (Object.keys(out).length < schema.minProperties && guard++ < schema.minProperties + 50) {
       const key = synthKey(n++, patternEntries, schema, nameCheck);
-      if (key === void 0 || key in out)
+      if (key === void 0 || Object.hasOwn(out, key))
         continue;
       addKey(key);
     }
@@ -366,20 +449,20 @@ const deriveObject = (schema, rootSchema, seen) => {
     enforceMaxProperties(out, schema, schema.maxProperties);
   return out;
 };
-const applyDependentSchema = (out, sub, rootSchema, seen) => {
+const applyDependentSchema = (out, sub, ctx) => {
   if (hasProperties(sub)) {
     for (const [key, propSchema] of Object.entries(sub.properties)) {
-      if (!(key in out))
-        out[key] = deriveExample(propSchema, rootSchema, seen);
+      if (!Object.hasOwn(out, key))
+        setProperty(out, key, derive(propSchema, ctx));
     }
   }
   if (hasRequired(sub)) {
     const propSchemas = hasProperties(sub) ? sub.properties : {};
     for (const key of sub.required) {
-      if (key in out)
+      if (Object.hasOwn(out, key))
         continue;
       const propSchema = propSchemas[key];
-      out[key] = propSchema !== void 0 ? deriveExample(propSchema, rootSchema, seen) : null;
+      setProperty(out, key, propSchema !== void 0 ? derive(propSchema, ctx) : null);
     }
   }
 };
@@ -410,7 +493,7 @@ const enforceMaxProperties = (out, schema, max) => {
   const protectedKeys = new Set(hasRequired(schema) ? schema.required : []);
   if (hasDependentRequired(schema)) {
     for (const [trigger, deps] of Object.entries(schema.dependentRequired)) {
-      if (trigger in out)
+      if (Object.hasOwn(out, trigger))
         for (const dep of deps)
           protectedKeys.add(dep);
     }
@@ -441,7 +524,7 @@ const deriveNumber = (schema, isInteger) => {
   }
   return (isInteger ? Math.round(value) : value) + 0;
 };
-const deriveArray = (schema, rootSchema, seen) => {
+const deriveArray = (schema, ctx) => {
   const items = hasItems(schema) ? schema.items : void 0;
   const prefixItems = schema["prefixItems"];
   const prefix = Array.isArray(prefixItems) ? prefixItems : Array.isArray(items) ? items : void 0;
@@ -449,11 +532,11 @@ const deriveArray = (schema, rootSchema, seen) => {
   const max = hasMaxItems(schema) ? schema.maxItems : Number.POSITIVE_INFINITY;
   const rest = items !== void 0 && !Array.isArray(items) && isSchemaObject(items) ? items : void 0;
   if (prefix) {
-    const tuple = prefix.map((item) => deriveExample(item, rootSchema, seen));
+    const tuple = prefix.map((item) => derive(item, ctx));
     const itemsClosed = schema["items"] === false;
     while (tuple.length < min && tuple.length < max) {
       if (rest !== void 0)
-        tuple.push(deriveExample(rest, rootSchema, seen));
+        tuple.push(derive(rest, ctx));
       else if (itemsClosed)
         break;
       else
@@ -467,15 +550,36 @@ const deriveArray = (schema, rootSchema, seen) => {
   const minContains = contains !== void 0 ? typeof raw["minContains"] === "number" ? raw["minContains"] : 1 : 0;
   const unique = hasUniqueItems(schema) && schema.uniqueItems === true;
   const elem = rest ?? contains;
-  const count = Math.min(Math.max(min, minContains, max === 0 ? 0 : 1), max);
+  const choices = unique && contains === void 0 ? closedValueSet(elem) : void 0;
+  const wanted = Math.min(Math.max(min, minContains, max === 0 ? 0 : 1), max);
+  const count = choices !== void 0 ? Math.min(wanted, choices.length) : wanted;
   const result = [];
   for (let i = 0; i < count; i++) {
+    if (choices !== void 0) {
+      result.push(choices[i]);
+      continue;
+    }
     const itemSchema = contains !== void 0 && i < minContains ? contains : elem;
-    const base = itemSchema !== void 0 ? deriveExample(itemSchema, rootSchema, seen) : null;
+    const base = itemSchema !== void 0 ? derive(itemSchema, ctx) : null;
     result.push(unique ? distinctify(base, i, itemSchema) : base);
   }
   return result;
 };
+const closedValueSet = (schema) => {
+  if (schema === void 0 || !isSchemaObject(schema))
+    return void 0;
+  if (hasConst(schema))
+    return [schema.const];
+  if (hasEnum(schema)) {
+    const fitting = schema.enum.filter((value) => satisfiesScalarConstraints(schema, value));
+    return fitting.length > 0 ? fitting : [...schema.enum];
+  }
+  if (hasType(schema) && schema.type === "boolean")
+    return [true, false];
+  if (hasType(schema) && schema.type === "null")
+    return [null];
+  return void 0;
+};
 const distinctify = (base, i, itemSchema) => {
   if (i === 0)
     return base;
@@ -542,6 +646,7 @@ const mergeAllOf = (schema) => {
     merged["required"] = [...required];
   return merged;
 };
+const serializeKey = (key) => key === "__proto__" ? '["__proto__"]' : JSON.stringify(key);
 const serializeValue = (value) => {
   if (typeof value === "bigint")
     return `${value}n`;
@@ -550,13 +655,24 @@ const serializeValue = (value) => {
   if (Array.isArray(value))
     return `[${value.map(serializeValue).join(", ")}]`;
   if (value !== null && typeof value === "object") {
-    const entries = Object.entries(value).filter(([, v]) => v !== void 0).map(([key, v]) => `${JSON.stringify(key)}: ${serializeValue(v)}`);
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).map(([key, v]) => `${serializeKey(key)}: ${serializeValue(v)}`);
     return `{ ${entries.join(", ")} }`;
   }
   return JSON.stringify(value);
 };
+const arbitraryName = (typeName) => `${typeName}Arbitrary`;
+const WARNING_VALUE_LIMIT = 240;
+const warnInvalidExample = (schema, typeName, value, rootSchema) => {
+  const check = makeInstanceCheck(schema, rootSchema, { checkFormats: true });
+  if (check(value))
+    return;
+  const serialized = serializeValue(value);
+  const quoted = serialized.length > WARNING_VALUE_LIMIT ? `${serialized.slice(0, WARNING_VALUE_LIMIT)}\u2026` : serialized;
+  console.warn(`Warning: the derived example for ${typeName} does not validate against its own schema \u2014 ${quoted}. It is emitted anyway so the file still compiles, but treat it as a placeholder: either the schema has no instance, or it uses a constraint the deriver cannot satisfy structurally (see the README's "Known limits"). ${arbitraryName(typeName)} is unaffected.`);
+};
 const generateExampleConst = (schema, typeName, rootSchema) => {
   const value = deriveExample(schema, rootSchema);
+  warnInvalidExample(schema, typeName, value, rootSchema);
   return `export const ${exampleName(typeName)}: ${typeName} = ${serializeValue(value)}`;
 };
 export {

package/dist/generators/generate-arbitrary.js

@@ -9,6 +9,7 @@ const VALIDATE_IMPORT_NAME = "__mjstValidate";
 const VALIDATE_IMPORT_STATEMENT = `import { validate as ${VALIDATE_IMPORT_NAME} } from '@amritk/runtime-validators'`;
 const lazyRef = (arbName) => `fc.constant(null).chain(() => ${arbName})`;
 const SELF_KEY = "self";
+const safeLiteralKey = (key) => key === "__proto__" ? '["__proto__"]' : JSON.stringify(key);
 const stringExpr = (schema) => {
   if (hasFormat(schema)) {
     switch (schema.format) {
@@ -220,7 +221,7 @@ const objectExpr = (schema, ctx) => {
     }
     return "fc.object()";
   }
-  const entries = keys.map((key) => `${JSON.stringify(key)}: ${propArbs.get(key)}`);
+  const entries = keys.map((key) => `${safeLiteralKey(key)}: ${propArbs.get(key)}`);
   const model = `{ ${entries.join(", ")} }`;
   const record = keys.every((key) => required.has(key)) ? `fc.record(${model})` : `fc.record(${model}, { requiredKeys: [${[...required].map((key) => JSON.stringify(key)).join(", ")}] })`;
   const needExtras = extrasAllowed && (extraValueArb !== void 0 || minProps !== void 0 && minProps > required.size);
@@ -303,7 +304,8 @@ const arbitraryExpr = (schema, ctx) => {
     const fitting = members.filter((value) => enumMemberFits(schema, value));
     const chosen = fitting.length > 0 ? fitting : members;
     const values = chosen.map((value) => JSON.stringify(value)).join(", ");
-    return `fc.constantFrom(${values})`;
+    const literalSafe = chosen.every((value) => value === null || typeof value !== "object");
+    return literalSafe ? `fc.constantFrom(...([${values}] as const))` : `fc.constantFrom(${values})`;
   }
   const instanceOf = getMjstInstanceOf(schema);
   if (instanceOf === "Date")
@@ -340,7 +342,7 @@ const generateArbitrary = (schema, typeName, suffix = "", lazyRefFilenames = /*
     const validatorName = `${selfArbName}Validator`;
     const embedded = JSON.stringify(withResolvableDefs(schema, rootSchema));
     return `const ${validatorName} = ${VALIDATE_IMPORT_NAME}(${embedded})
-export const ${selfArbName}: fc.Arbitrary<${typeName}> = (${body}).filter((value) => ${validatorName}(value) === true)`;
+export const ${selfArbName}: fc.Arbitrary<${typeName}> = (${body}).filter((value): value is ${typeName} => ${validatorName}(value) === true)`;
   }
   return `export const ${selfArbName}: fc.Arbitrary<${typeName}> = ${body}`;
 };

package/dist/generators/schema-validation.d.ts

@@ -7,14 +7,44 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  */
 export declare const needsValidationFilter: (schema: JSONSchema) => boolean;
 /**
- * Returns `schema` augmented with the root document's `$defs`/`definitions` so its
- * local `$ref`s (`#/$defs/…`) resolve when it is validated in isolation. The
- * schema's own definitions win on collision.
+ * Returns `schema` augmented with the definitions its local `$ref`s need, so it
+ * can be validated (or embedded in generated output) on its own.
+ *
+ * Only the *reachable* definitions come along. Splicing in the root's entire
+ * `$defs` used to make every check quadratic in the size of the document — the
+ * validator screens every `pattern` in whatever it is handed, so a 959-definition
+ * OpenAPI schema paid for all 959 on each of the thousand-odd checks a single
+ * generation run makes — and it also embedded the whole document into every
+ * generated file that carries a validating filter. A ref we cannot pin to one
+ * definition (an `$anchor` name, or any `$dynamicRef`/`$recursiveRef`) still
+ * falls back to the full set, since correctness beats size. The schema's own
+ * definitions win on collision.
  */
 export declare const withResolvableDefs: (schema: JSONSchema, rootSchema?: Record<string, unknown>) => Record<string, unknown>;
 /**
- * Compiles a boolean validator for `schema` (with the root document's definitions
- * spliced in so local `$ref`s resolve). Used at generation time to accept/reject
- * candidate example values for keywords the deriver can't satisfy structurally.
+ * How strictly a check judges a candidate value.
+ *
+ * `format` is off for the checks that *steer* derivation (`refineExample` picks
+ * among candidates; rejecting one over a format it cannot influence would only
+ * discard a better value), and on for the final audit of an emitted example,
+ * where an unsupported `format` falling back to the bare `"string"` is exactly
+ * the kind of quiet wrongness worth reporting.
  */
-export declare const makeInstanceCheck: (schema: JSONSchema, rootSchema?: Record<string, unknown>) => ((value: unknown) => boolean);
+export type InstanceCheckOptions = {
+    readonly checkFormats?: boolean;
+};
+/**
+ * Compiles a boolean validator for `schema` (with the definitions its `$ref`s
+ * need spliced in). Used at generation time to accept/reject candidate example
+ * values for keywords the deriver can't satisfy structurally.
+ *
+ * A schema the interpreter refuses — a `$ref` pointing outside the document
+ * (`#/components/schemas/…` in a bare OpenAPI fragment), or a `pattern` its
+ * ReDoS screen rejects — answers `true` for everything instead of throwing.
+ * This check is an *opinion* about a candidate value; it must never be the
+ * reason a whole generation run dies, and an undecidable schema is not grounds
+ * for discarding an otherwise reasonable example. It does warn on the way past,
+ * though — a filter that turns itself off without saying so is indistinguishable
+ * from one that ran and approved of everything.
+ */
+export declare const makeInstanceCheck: (schema: JSONSchema, rootSchema?: Record<string, unknown>, options?: InstanceCheckOptions) => ((value: unknown) => boolean);

package/dist/generators/schema-validation.js

@@ -1,3 +1,4 @@
+import { extractRefs } from "@amritk/helpers/extract-refs";
 import { isSchemaObject } from "@amritk/helpers/schema-guards";
 import { validateGuard } from "@amritk/runtime-validators";
 const FILTER_KEYWORDS = /* @__PURE__ */ new Set([
@@ -16,6 +17,7 @@ const FILTER_KEYWORDS = /* @__PURE__ */ new Set([
   "contains"
 ]);
 const SKIP_RECURSE = /* @__PURE__ */ new Set(["enum", "const", "examples", "default", "$ref", "required", "$defs", "definitions"]);
+const filterAnswers = /* @__PURE__ */ new WeakMap();
 const needsValidationFilter = (schema) => {
   const walk = (node) => {
     if (Array.isArray(node))
@@ -35,23 +37,148 @@ const needsValidationFilter = (schema) => {
     }
     return false;
   };
-  return walk(schema);
+  if (typeof schema !== "object" || schema === null)
+    return walk(schema);
+  const cached = filterAnswers.get(schema);
+  if (cached !== void 0)
+    return cached;
+  const answer = walk(schema);
+  filterAnswers.set(schema, answer);
+  return answer;
 };
+const defTargetFor = (ref) => {
+  if (ref.startsWith("#")) {
+    const fragment = ref.slice(1);
+    if (fragment === "")
+      return null;
+    if (!fragment.startsWith("/"))
+      return "all";
+    const [container, name] = fragment.slice(1).split("/");
+    if (name === void 0 || container !== "$defs" && container !== "definitions")
+      return null;
+    return { container, name: name.replace(/~1/g, "/").replace(/~0/g, "~") };
+  }
+  const hash = ref.indexOf("#");
+  return { container: "$defs", name: hash === -1 ? ref : ref.slice(0, hash) };
+};
+const DYNAMIC_REF_KEYWORDS = /* @__PURE__ */ new Set(["$dynamicRef", "$recursiveRef"]);
+const dynamicRefAnswers = /* @__PURE__ */ new WeakMap();
+const usesDynamicRef = (node) => {
+  if (node === null || typeof node !== "object")
+    return false;
+  const cached = dynamicRefAnswers.get(node);
+  if (cached !== void 0)
+    return cached;
+  const answer = Array.isArray(node) ? node.some(usesDynamicRef) : Object.entries(node).some(([key, value]) => DYNAMIC_REF_KEYWORDS.has(key) && typeof value === "string" || usesDynamicRef(value));
+  dynamicRefAnswers.set(node, answer);
+  return answer;
+};
+const reachableDefs = (schema, rootSchema) => {
+  if (usesDynamicRef(schema))
+    return "all";
+  const picked = {
+    $defs: /* @__PURE__ */ Object.create(null),
+    definitions: /* @__PURE__ */ Object.create(null)
+  };
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [...extractRefs(schema)];
+  for (let head = 0; head < queue.length; head++) {
+    const ref = queue[head];
+    if (ref === void 0 || seen.has(ref))
+      continue;
+    seen.add(ref);
+    const target = defTargetFor(ref);
+    if (target === "all")
+      return "all";
+    if (target === null)
+      continue;
+    const container = rootSchema[target.container];
+    if (container === null || typeof container !== "object")
+      continue;
+    const definition = container[target.name];
+    if (definition === void 0 || Object.hasOwn(picked[target.container], target.name))
+      continue;
+    if (usesDynamicRef(definition))
+      return "all";
+    picked[target.container][target.name] = definition;
+    for (const nested of extractRefs(definition)) {
+      if (!seen.has(nested))
+        queue.push(nested);
+    }
+  }
+  return picked;
+};
+const resolvableCache = /* @__PURE__ */ new WeakMap();
 const withResolvableDefs = (schema, rootSchema) => {
+  if (!rootSchema || typeof schema !== "object" || schema === null)
+    return spliceDefs(schema, rootSchema);
+  const perRoot = resolvableCache.get(rootSchema) ?? /* @__PURE__ */ new WeakMap();
+  resolvableCache.set(rootSchema, perRoot);
+  const existing = perRoot.get(schema);
+  if (existing)
+    return existing;
+  const spliced = spliceDefs(schema, rootSchema);
+  perRoot.set(schema, spliced);
+  return spliced;
+};
+const spliceDefs = (schema, rootSchema) => {
   const base = isSchemaObject(schema) ? { ...schema } : { const: schema };
   if (!rootSchema)
     return base;
+  const reachable = reachableDefs(schema, rootSchema);
   for (const key of ["$defs", "definitions"]) {
-    const rootDefs = rootSchema[key];
-    if (rootDefs && typeof rootDefs === "object") {
-      base[key] = { ...rootDefs, ...base[key] ?? {} };
-    }
+    const rootDefs = reachable === "all" ? rootSchema[key] : reachable[key];
+    if (!rootDefs || typeof rootDefs !== "object")
+      continue;
+    if (reachable !== "all" && Object.keys(rootDefs).length === 0 && base[key] === void 0)
+      continue;
+    base[key] = { ...rootDefs, ...base[key] ?? {} };
   }
   return base;
 };
-const makeInstanceCheck = (schema, rootSchema) => {
-  const guard = validateGuard(withResolvableDefs(schema, rootSchema));
-  return (value) => guard(value) === true;
+const WARNING_SCHEMA_LIMIT = 240;
+const reportedGuardFailures = /* @__PURE__ */ new Set();
+const describeSchema = (schema) => {
+  const serialized = (() => {
+    try {
+      return JSON.stringify(schema) ?? String(schema);
+    } catch {
+      return String(schema);
+    }
+  })();
+  return serialized.length > WARNING_SCHEMA_LIMIT ? `${serialized.slice(0, WARNING_SCHEMA_LIMIT)}\u2026` : serialized;
+};
+const warnUndecidableSchema = (schema, reason) => {
+  const described = describeSchema(schema);
+  const message = reason instanceof Error ? reason.message : String(reason);
+  const key = `${message}
+${described}`;
+  if (reportedGuardFailures.has(key))
+    return;
+  reportedGuardFailures.add(key);
+  console.warn(`Warning: cannot validate generated values against ${described} \u2014 ${message}. Every candidate value is accepted for this subschema, so constraints only the validator enforces (\`oneOf\`, \`not\`, \`pattern\`, \`if\`/\`then\`, \u2026) go unchecked there and the emitted example may not satisfy its own schema. Generation continues regardless; the usual causes are a \`$ref\` pointing outside this fragment and a \`pattern\` the ReDoS screen rejects.`);
+};
+const tryGuard = (schema, checkFormats) => {
+  try {
+    return checkFormats ? validateGuard(schema, { formats: "all" }) : validateGuard(schema);
+  } catch (error) {
+    warnUndecidableSchema(schema, error);
+    return void 0;
+  }
+};
+const makeInstanceCheck = (schema, rootSchema, options) => {
+  const resolved = withResolvableDefs(schema, rootSchema);
+  const guard = tryGuard(resolved, options?.checkFormats === true);
+  if (guard === void 0)
+    return () => true;
+  return (value) => {
+    try {
+      return guard(value) === true;
+    } catch (error) {
+      warnUndecidableSchema(resolved, error);
+      return true;
+    }
+  };
 };
 export {
   makeInstanceCheck,

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@amritk/generate-examples",
-  "version": "0.5.6",
+  "version": "0.6.1",
   "description": "Generate fast-check arbitraries and example values from JSON Schemas.",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -38,6 +40,7 @@
   },
   "scripts": {
     "build": "tsgo -p tsconfig.build.json && tsc-alias -p tsconfig.build.json -f && node ../../scripts/strip-comments.mjs",
+    "prepublishOnly": "node ../../scripts/check-publishable.mjs",
     "types:check": "tsgo -p . --noEmit",
     "test": "NODE_ENV=production vitest run --root ../.. generate-examples"
   },
@@ -52,8 +55,8 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.14.0",
-    "@amritk/runtime-validators": "0.9.1"
+    "@amritk/helpers": "^0.15.1",
+    "@amritk/runtime-validators": "^0.10.1"
   },
   "devDependencies": {
     "ajv": "^8.17.1"