@amritk/generate-examples 0.6.3 → 0.7.0

package/AI.md

@@ -47,6 +47,25 @@ const files = await buildExampleSchema(schema, 'User') // → user.ts, index.ts
 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.
+6. **`fooExample` is sometimes emitted as `… as Foo`.** A schema can require a
+   key the generated type never declares (`required` naming something absent from
+   `properties`, a `dependentRequired`/`dependentSchemas` dependency, a
+   `minProperties` filler on an object with no index signature). The value keeps
+   the key — dropping it would ship a fixture missing what its schema demands —
+   so the assertion is what lets the file compile. Do not "clean it up" into a
+   bare literal; TypeScript rejects the excess property, and `satisfies` runs the
+   very same check.
+7. **Derived values are capped at 10,000** characters / elements / keys, so a
+   schema with an enormous `minLength`/`minItems`/`minProperties` gets a
+   short value plus a `console.warn` rather than a file nobody can open.
+   `FooArbitrary` still honours the real bound — reach for it when the exact size
+   matters.
+
+8. **A `default`/`examples` hint that contradicts its own schema is ignored.**
+   The generated type follows the schema, so emitting the hint verbatim produced
+   a file that would not compile (`const fooExample: string = 42`). `const` is
+   always honoured — the type is its literal type. Do not "restore" a mismatched
+   hint; fix the schema instead.
 
 Exports: `buildExampleSchema`, `generateArbitrary`, `generateExampleConst`,
 `deriveExample`, `serializeValue`, `GeneratedFile`. Only the `.` entry.

package/README.md

@@ -163,7 +163,7 @@ compiles — but the generator prints a `console.warn` naming the type. Reach fo
 `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 value falls short for three reasons:
 
 - **The schema has no instance.** `{ pattern: '^ab$', minLength: 5 }`,
   `uniqueItems` over booleans with `minItems: 3`, a `required` key that
@@ -173,6 +173,61 @@ The value falls short for two reasons:
 - **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.
+- **The bound is larger than any fixture should be.** A derived string, array, or
+  object stops growing at 10,000 characters / elements / keys, so a document
+  asking for `minLength: 50000000` yields a capped value and a warning rather than
+  a 50 MB literal. `FooArbitrary` still honours the real bound.
+
+Two more shapes worth knowing about, both of which keep the generated file
+compiling rather than making it correct:
+
+- A schema can require a key its **generated type never declares** — `required`
+  naming something absent from `properties`, a `dependentRequired` /
+  `dependentSchemas` dependency, or a `minProperties` filler on an object with no
+  index signature. The example keeps the key (a fixture missing what its schema
+  demands is broken data) and is emitted as `… as Foo`, since a bare object
+  literal with an excess property fails to compile.
+- An authored `default` or `examples[0]` is used **only when it satisfies its own
+  schema**. A hint that does not (`{ type: 'string', default: 42 }` — common in
+  documents whose field types changed after the hint was written) is ignored in
+  favour of a structurally derived value, because the generated type follows the
+  schema and would reject the hint outright. `const` is always honoured: the type
+  is the const's own literal type, so the two cannot disagree.
+- An **unsatisfiable range** (`minLength: 10, maxLength: 2`) collapses onto its
+  upper bound in the arbitrary. Every bounded `fc.*` combinator asserts
+  `min <= max` and throws at *import*, which would take down every other export in
+  the file alongside it. Integer bounds are also confined to fast-check's own
+  32-bit range, and length/count bounds to non-negative integers.
+- A **recursive definition's** example has to stop somewhere and stops with
+  `null`, which the non-nullable type does not admit — so it is emitted as
+  `… as unknown as Node`. `NodeArbitrary` ties the recursion properly through
+  `fc.letrec` and needs no such escape.
+- A `pattern` that is **not a valid JavaScript regex**, or that uses a lookahead
+  or lookbehind, falls back to a plain `fc.string()`. `fc.stringMatching` compiles
+  the pattern at module scope and cannot generate from an assertion, so honouring
+  it would throw where the whole file becomes unusable rather than just that one
+  arbitrary being loose.
+- **Nesting deeper than 400 levels** is refused with an error naming the limit.
+  Building an arbitrary costs several stack frames per schema level, so a deeper
+  document exhausts the stack — the cap turns that into a message that says what
+  is wrong.
+
+Two shapes stay impossible to generate from, and the arbitrary will retry
+forever if you sample it. Both are schemas with no instance, and the example
+warns:
+
+- A `pattern` no string of the required length can match
+  (`{ pattern: '^[a-z]{2}$', minLength: 5 }`). A satisfiable-but-narrow pairing
+  (`{ pattern: '^[a-f0-9]+$', minLength: 32, maxLength: 32 }`) is slow for the
+  same reason — `fc.stringMatching` rarely lands on the exact length.
+- A `minLength`/`minItems` so large that no value of that size can be built.
+
+One more gap is not this package's to close: a `$ref` that resolves nowhere in
+the document is typed by its name (`Nope`) but never imported, because it was
+never generated as a file. The arbitrary degrades to `fc.anything()`, but the
+type still names it, so the file does not compile. Same for `{ "type": [] }`,
+which types as `export type Foo = ;`. Both come from
+`@amritk/helpers/generate-type-definition`.
 
 > [!TIP]
 > The example for a `$ref` is inlined by value, so a definition graph with wide

package/dist/generators/assert-generator-depth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How deep a schema may nest before the two generator recursions give up.
+ *
+ * Lower than `@amritk/helpers`' `MAX_SCHEMA_DEPTH` of 2000, and deliberately so.
+ * That cap suits the helpers' walkers, which spend roughly two stack frames per
+ * schema level. Building an arbitrary or deriving a value costs far more —
+ * `derive` → `deriveBase` → `deriveForType` → `deriveObject` → `derive` is five
+ * frames before the next level even starts, plus whatever `needsValidationFilter`
+ * adds — so the real stack runs out first: measured, the arbitrary generator dies
+ * somewhere between 500 and 1000 levels and the deriver between 1000 and 1500,
+ * both well under 2000. A cap the stack beats to the punch is no cap at all.
+ *
+ * 400 sits inside the range both were measured to handle, with room for a
+ * shallower stack than this one, and it is still an order of magnitude past
+ * anything a real document nests — hand-written schemas rarely pass ten levels,
+ * and generated ones rarely pass fifty.
+ */
+export declare const MAX_GENERATOR_DEPTH = 400;
+/**
+ * Throws a message naming the nesting limit once a generator recursion passes it.
+ *
+ * Call this at the top of each recursive step with the *current* depth. Without
+ * it a pathologically nested document — a fuzz case, or a document that lost a
+ * closing brace — died with a bare `RangeError: Maximum call stack size exceeded`
+ * pointing at whichever helper happened to be deepest, which says nothing about
+ * the input that caused it.
+ */
+export declare const assertGeneratorDepth: (depth: number, generator: string) => void;

package/dist/generators/assert-generator-depth.js

@@ -0,0 +1,10 @@
+const MAX_GENERATOR_DEPTH = 400;
+const assertGeneratorDepth = (depth, generator) => {
+  if (depth > MAX_GENERATOR_DEPTH) {
+    throw new Error(`Schema nesting exceeds ${MAX_GENERATOR_DEPTH} levels while running ${generator}. Flatten the document (or split the deepest subschema into a $defs entry and $ref it) and try again.`);
+  }
+};
+export {
+  MAX_GENERATOR_DEPTH,
+  assertGeneratorDepth
+};

package/dist/generators/closed-value-set.d.ts

@@ -0,0 +1,14 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * The complete set of values an item schema admits, when that set is finite and
+ * small enough to enumerate: `const`, `enum`, `boolean`, `null`. `uniqueItems`
+ * needs distinct elements, and for these schemas perturbing one value would step
+ * straight out of the schema, so the deriver walks this set instead of nudging.
+ * `undefined` means the value space is open and perturbing is fine.
+ *
+ * The arbitrary generator asks the same question for a different reason: a set
+ * of N values cannot fill a `uniqueArray` of more than N slots, and fast-check
+ * retries forever rather than admitting it — so `{ items: { type: 'boolean' },
+ * minItems: 5, uniqueItems: true }` produced an arbitrary that hung when sampled.
+ */
+export declare const closedValueSet: (schema: JSONSchema | undefined) => unknown[] | undefined;

package/dist/generators/closed-value-set.js

@@ -0,0 +1,20 @@
+import { hasConst, hasEnum, hasType, isSchemaObject } from "@amritk/helpers/schema-guards";
+import { satisfiesScalarConstraints } from "./satisfies-scalar-constraints.js";
+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;
+};
+export {
+  closedValueSet
+};

package/dist/generators/collect-example-imports.js

@@ -1,20 +1,22 @@
 import { refToFilename } from "@amritk/helpers/ref-to-filename";
 import { refToName } from "@amritk/helpers/ref-to-name";
 import { resolveRef } from "@amritk/helpers/resolve-ref";
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasOneOf, hasProperties, hasRef, isSchemaObject } from "@amritk/helpers/schema-guards";
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasContains, hasDependentSchemas, hasOneOf, hasProperties, hasRef, isSchemaObject } from "@amritk/helpers/schema-guards";
+import { assertGeneratorDepth } from "./assert-generator-depth.js";
 const buildImport = (ref, suffix) => {
   const filename = refToFilename(ref);
   const typeName = refToName(ref, suffix);
   return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
 };
-const collectRefs = (schema) => {
+const collectRefs = (schema, depth = 0) => {
+  assertGeneratorDepth(depth, "collectExampleImports");
   if (!isSchemaObject(schema))
     return [];
   if (hasRef(schema))
     return [schema.$ref];
   const refs = [];
   const visit = (sub) => {
-    refs.push(...collectRefs(sub));
+    refs.push(...collectRefs(sub, depth + 1));
   };
   if (hasOneOf(schema))
     schema.oneOf.forEach(visit);
@@ -32,6 +34,8 @@ const collectRefs = (schema) => {
   if (hasAdditionalProperties(schema) && isSchemaObject(schema.additionalProperties)) {
     visit(schema.additionalProperties);
   }
+  if (hasDependentSchemas(schema))
+    Object.values(schema.dependentSchemas).forEach(visit);
   const prefixItems = raw["prefixItems"];
   if (Array.isArray(prefixItems))
     prefixItems.forEach(visit);
@@ -40,6 +44,8 @@ const collectRefs = (schema) => {
     items.forEach(visit);
   else if (isSchemaObject(items))
     visit(items);
+  if (hasContains(schema) && isSchemaObject(schema.contains))
+    visit(schema.contains);
   return refs;
 };
 const collectExampleImports = (schema, options) => {