@amritk/generate-examples 0.6.3 → 0.7.0

package/dist/generators/derive-example.js

@@ -1,6 +1,11 @@
 import { getMjstInstanceOf, getMjstPrimitive } from "@amritk/helpers/mjst-extension";
+import { readKey } from "@amritk/helpers/read-key";
 import { resolveRef } from "@amritk/helpers/resolve-ref";
 import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDefault, hasDependentRequired, hasDependentSchemas, hasEnum, hasExamples, hasExclusiveMaximum, hasExclusiveMinimum, hasFormat, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasPatternProperties, hasProperties, hasPropertyNames, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject } from "@amritk/helpers/schema-guards";
+import { assertGeneratorDepth } from "./assert-generator-depth.js";
+import { closedValueSet } from "./closed-value-set.js";
+import { declaresOwnShape, isObjectLike, typesConflict } from "./is-object-like.js";
+import { satisfiesScalarConstraints } from "./satisfies-scalar-constraints.js";
 import { makeInstanceCheck, needsValidationFilter } from "./schema-validation.js";
 const lowerFirst = (name) => name.charAt(0).toLowerCase() + name.slice(1);
 const exampleName = (typeName) => `${lowerFirst(typeName)}Example`;
@@ -67,6 +72,13 @@ const topLevelAlternatives = (s) => {
   parts.push(cur);
   return parts;
 };
+const matchesPattern = (pattern, value) => {
+  try {
+    return new RegExp(pattern).test(value);
+  } catch {
+    return false;
+  }
+};
 const sampleFromPattern = (pattern, minLength) => {
   let body = pattern;
   if (body.startsWith("^"))
@@ -178,16 +190,17 @@ const FORMAT_EXAMPLES = {
   // The `regex` format asks for a string that *compiles* as a regular expression.
   regex: "^example$"
 };
+const MAX_DERIVED_SIZE = 1e4;
 const exampleString = (schema) => {
   if (hasFormat(schema)) {
-    const formatted = FORMAT_EXAMPLES[schema.format];
+    const formatted = readKey(FORMAT_EXAMPLES, schema.format);
     if (formatted !== void 0)
       return formatted;
   }
-  const minLength = hasMinLength(schema) ? schema.minLength : 0;
+  const minLength = Math.min(hasMinLength(schema) ? schema.minLength : 0, MAX_DERIVED_SIZE);
   if (hasPattern(schema)) {
     const sampled = sampleFromPattern(schema.pattern, minLength);
-    if (sampled !== void 0 && sampled.length >= minLength && new RegExp(schema.pattern).test(sampled)) {
+    if (sampled !== void 0 && sampled.length >= minLength && matchesPattern(schema.pattern, sampled)) {
       if (!(hasMaxLength(schema) && sampled.length > schema.maxLength))
         return sampled;
     }
@@ -204,7 +217,9 @@ const newContext = (rootSchema) => ({
   rootSchema,
   values: /* @__PURE__ */ new Map(),
   active: /* @__PURE__ */ new Set(),
-  cycleBroken: false
+  cycleBroken: false,
+  needsAssertion: false,
+  depth: 0
 });
 const contextFor = (rootSchema) => {
   if (rootSchema === void 0)
@@ -216,52 +231,76 @@ const contextFor = (rootSchema) => {
   contexts.set(rootSchema, created);
   return created;
 };
-const deriveExample = (schema, rootSchema) => {
+const deriveExample = (schema, rootSchema) => deriveReported(schema, rootSchema).value;
+const deriveReported = (schema, rootSchema) => {
   const ctx = contextFor(rootSchema);
   ctx.active.clear();
   ctx.cycleBroken = false;
-  return derive(schema, ctx);
+  ctx.needsAssertion = false;
+  ctx.depth = 0;
+  const value = derive(schema, ctx);
+  return { value, needsAssertion: ctx.needsAssertion, cycleBroken: ctx.cycleBroken };
 };
 const derive = (schema, ctx) => {
+  assertGeneratorDepth(ctx.depth, "deriveExample");
   if (!isSchemaObject(schema))
     return null;
-  const base = deriveBase(schema, ctx);
-  return needsValidationFilter(schema) ? refineExample(schema, base, ctx) : base;
+  ctx.depth++;
+  try {
+    const base = deriveBase(schema, ctx);
+    return needsValidationFilter(schema) ? refineExample(schema, base, ctx) : base;
+  } finally {
+    ctx.depth--;
+  }
 };
 const deriveRef = (ref, ctx) => {
   if (ctx.active.has(ref)) {
     ctx.cycleBroken = true;
     return null;
   }
-  if (ctx.values.has(ref))
-    return ctx.values.get(ref);
+  const memoized = ctx.values.get(ref);
+  if (memoized !== void 0) {
+    if (memoized.needsAssertion)
+      ctx.needsAssertion = true;
+    return memoized.value;
+  }
   if (!ctx.rootSchema)
     return null;
   const resolved = resolveRef(ref, ctx.rootSchema);
   if (!resolved)
     return null;
   const outerBroken = ctx.cycleBroken;
+  const outerUndeclared = ctx.needsAssertion;
   ctx.cycleBroken = false;
+  ctx.needsAssertion = false;
   ctx.active.add(ref);
   try {
     const value = derive(resolved, ctx);
     if (!ctx.cycleBroken)
-      ctx.values.set(ref, value);
+      ctx.values.set(ref, { value, needsAssertion: ctx.needsAssertion });
     ctx.cycleBroken = outerBroken || ctx.cycleBroken;
+    ctx.needsAssertion = outerUndeclared || ctx.needsAssertion;
     return value;
   } finally {
     ctx.active.delete(ref);
   }
 };
+const authoredHint = (schema) => {
+  if (hasExamples(schema) && Array.isArray(schema.examples) && schema.examples.length > 0) {
+    return { value: schema.examples[0] };
+  }
+  if (hasDefault(schema))
+    return { value: schema.default };
+  return void 0;
+};
 const deriveBase = (schema, ctx) => {
   if (!isSchemaObject(schema))
     return null;
   if (hasConst(schema))
     return schema.const;
-  if (hasExamples(schema) && Array.isArray(schema.examples) && schema.examples.length > 0)
-    return schema.examples[0];
-  if (hasDefault(schema))
-    return schema.default;
+  const hint = authoredHint(schema);
+  if (hint !== void 0 && makeInstanceCheck(schema, ctx.rootSchema)(hint.value))
+    return hint.value;
   if (hasEnum(schema) && schema.enum.length > 0) {
     const fitting = schema.enum.find((value) => satisfiesScalarConstraints(schema, value));
     return fitting !== void 0 ? fitting : schema.enum[0];
@@ -276,10 +315,16 @@ const deriveBase = (schema, ctx) => {
     return 0n;
   if (hasAllOf(schema))
     return derive(mergeAllOf(schema), ctx);
-  if (hasOneOf(schema) && schema.oneOf[0] !== void 0)
-    return derive(schema.oneOf[0], ctx);
-  if (hasAnyOf(schema) && schema.anyOf[0] !== void 0)
-    return derive(schema.anyOf[0], ctx);
+  const branches = hasOneOf(schema) ? schema.oneOf : hasAnyOf(schema) ? schema.anyOf : void 0;
+  if (branches !== void 0 && branches.length > 0) {
+    const rest = withoutCombinators(schema);
+    if (!declaresOwnShape(rest))
+      return derive(branches[0], ctx);
+    const chosen = branches.find((branch) => !typesConflict(rest, branch)) ?? branches[0];
+    return derive({ allOf: [rest, chosen] }, ctx);
+  }
+  if (isObjectLike(schema))
+    return deriveObject(schema, ctx);
   if (hasType(schema))
     return deriveForType(schema.type, schema, ctx);
   if (Array.isArray(schema.type) && schema.type.length > 0) {
@@ -287,6 +332,12 @@ const deriveBase = (schema, ctx) => {
   }
   return null;
 };
+const withoutCombinators = (schema) => {
+  const rest = { ...schema };
+  delete rest["oneOf"];
+  delete rest["anyOf"];
+  return rest;
+};
 const REFINED_APPLICATORS = ["if", "then", "else", "not", "oneOf"];
 const structuralOnly = (schema) => {
   const clone = { ...schema };
@@ -336,26 +387,6 @@ const refineExample = (schema, base, ctx) => {
       return candidate;
   return base;
 };
-const satisfiesScalarConstraints = (schema, value) => {
-  if (typeof value === "string") {
-    if (hasMinLength(schema) && value.length < schema.minLength)
-      return false;
-    if (hasMaxLength(schema) && value.length > schema.maxLength)
-      return false;
-  } else if (typeof value === "number") {
-    if (hasMinimum(schema) && value < schema.minimum)
-      return false;
-    if (hasMaximum(schema) && value > schema.maximum)
-      return false;
-    if (hasExclusiveMinimum(schema) && value <= schema.exclusiveMinimum)
-      return false;
-    if (hasExclusiveMaximum(schema) && value >= schema.exclusiveMaximum)
-      return false;
-    if (hasMultipleOf(schema) && schema.multipleOf > 0 && value % schema.multipleOf !== 0)
-      return false;
-  }
-  return true;
-};
 const deriveForType = (type, schema, ctx) => {
   switch (type) {
     case "string":
@@ -396,6 +427,15 @@ const deriveObject = (schema, ctx) => {
   const additionalClosed = hasAdditionalProperties(schema) && schema.additionalProperties === false;
   const extrasAllowed = !additionalClosed || patternEntries.length > 0;
   const nameCheck = hasPropertyNames(schema) ? makeInstanceCheck(schema.propertyNames, ctx.rootSchema) : void 0;
+  const declaredKeys = new Set(hasProperties(schema) ? Object.keys(schema.properties) : []);
+  const hasIndexSignature = additionalSchema !== void 0 || hasPatternProperties(schema) && Object.keys(schema.patternProperties).length > 0;
+  const noteKey = (key) => {
+    if (!hasIndexSignature && !declaredKeys.has(key))
+      ctx.needsAssertion = true;
+  };
+  const raw = schema;
+  if (Object.hasOwn(raw, "if") && Object.hasOwn(raw, "then"))
+    ctx.needsAssertion = true;
   const valueSchemaFor = (key) => {
     const matches = patternEntries.filter(([re]) => re.test(key)).map(([, sub]) => sub);
     if (matches.length === 1)
@@ -408,6 +448,7 @@ const deriveObject = (schema, ctx) => {
     const sub = valueSchemaFor(key);
     if (sub === void 0 && additionalClosed)
       return;
+    noteKey(key);
     setProperty(out, key, sub !== void 0 ? derive(sub, ctx) : null);
   };
   if (hasProperties(schema)) {
@@ -416,9 +457,10 @@ const deriveObject = (schema, ctx) => {
     }
   }
   if (hasRequired(schema)) {
-    for (const key of schema.required)
-      if (!Object.hasOwn(out, key))
+    for (const key of schema.required) {
+      if (typeof key === "string" && !Object.hasOwn(out, key))
         addKey(key);
+    }
   }
   if (hasDependentRequired(schema)) {
     for (const [trigger, deps] of Object.entries(schema.dependentRequired)) {
@@ -432,63 +474,78 @@ const deriveObject = (schema, ctx) => {
   if (hasDependentSchemas(schema)) {
     for (const [trigger, sub] of Object.entries(schema.dependentSchemas)) {
       if (Object.hasOwn(out, trigger) && isSchemaObject(sub))
-        applyDependentSchema(out, sub, ctx);
+        applyDependentSchema(out, sub, ctx, noteKey);
     }
   }
   if (hasMinProperties(schema) && extrasAllowed) {
+    const target = Math.min(schema.minProperties, MAX_DERIVED_SIZE);
+    let count = Object.keys(out).length;
     let n = 0;
-    let guard = 0;
-    while (Object.keys(out).length < schema.minProperties && guard++ < schema.minProperties + 50) {
+    let attempts = 0;
+    while (count < target && attempts++ < target + 50) {
       const key = synthKey(n++, patternEntries, schema, nameCheck);
-      if (key === void 0 || Object.hasOwn(out, key))
+      if (key === void 0)
+        break;
+      if (Object.hasOwn(out, key))
         continue;
       addKey(key);
+      if (Object.hasOwn(out, key))
+        count++;
     }
   }
   if (hasMaxProperties(schema))
     enforceMaxProperties(out, schema, schema.maxProperties);
   return out;
 };
-const applyDependentSchema = (out, sub, ctx) => {
+const applyDependentSchema = (out, sub, ctx, noteKey) => {
+  const add = (key, propSchema) => {
+    noteKey(key);
+    setProperty(out, key, propSchema !== void 0 ? derive(propSchema, ctx) : null);
+  };
   if (hasProperties(sub)) {
     for (const [key, propSchema] of Object.entries(sub.properties)) {
       if (!Object.hasOwn(out, key))
-        setProperty(out, key, derive(propSchema, ctx));
+        add(key, propSchema);
     }
   }
   if (hasRequired(sub)) {
     const propSchemas = hasProperties(sub) ? sub.properties : {};
     for (const key of sub.required) {
-      if (Object.hasOwn(out, key))
+      if (typeof key !== "string" || Object.hasOwn(out, key))
         continue;
-      const propSchema = propSchemas[key];
-      setProperty(out, key, propSchema !== void 0 ? derive(propSchema, ctx) : null);
+      add(key, propSchemas[key]);
     }
   }
 };
+const MAX_SYNTH_KEY_LENGTH = 64;
 const synthKey = (i, patternEntries, schema, nameCheck) => {
-  const vary = (seed) => seed.repeat(i + 1);
+  const variants = (seed) => i === 0 ? [seed] : [`${seed}${i}`, seed.repeat(i + 1)].filter((key) => key.length <= MAX_SYNTH_KEY_LENGTH);
   const seeds = [];
   for (const [re] of patternEntries) {
     const sampled = sampleFromPattern(re.source, 0);
-    if (sampled !== void 0 && sampled.length > 0)
-      seeds.push(vary(sampled));
+    if (sampled !== void 0 && sampled.length > 0) {
+      seeds.push({ seed: sampled, matches: (key) => re.test(key) });
+    }
   }
   const propertyNames = isSchemaObject(schema) && hasPropertyNames(schema) ? schema.propertyNames : void 0;
   if (propertyNames !== void 0 && isSchemaObject(propertyNames) && hasPattern(propertyNames)) {
     const sampled = sampleFromPattern(propertyNames.pattern, 0);
     if (sampled !== void 0 && sampled.length > 0)
-      seeds.push(vary(sampled));
+      seeds.push({ seed: sampled, matches: () => true });
   }
-  seeds.push(vary("extra"));
-  for (const seed of seeds) {
-    if (!nameCheck || nameCheck(seed))
-      return seed;
+  seeds.push({ seed: "extra", matches: () => true });
+  for (const { seed, matches } of seeds) {
+    for (const key of variants(seed)) {
+      if (matches(key) && (!nameCheck || nameCheck(key)))
+        return key;
+    }
   }
   return void 0;
 };
 const enforceMaxProperties = (out, schema, max) => {
-  if (Object.keys(out).length <= max)
+  const keys = Object.keys(out);
+  let count = keys.length;
+  if (count <= max)
     return;
   const protectedKeys = new Set(hasRequired(schema) ? schema.required : []);
   if (hasDependentRequired(schema)) {
@@ -498,11 +555,13 @@ const enforceMaxProperties = (out, schema, max) => {
           protectedKeys.add(dep);
     }
   }
-  for (const key of Object.keys(out)) {
-    if (Object.keys(out).length <= max)
+  for (const key of keys) {
+    if (count <= max)
       break;
-    if (!protectedKeys.has(key))
-      delete out[key];
+    if (protectedKeys.has(key))
+      continue;
+    delete out[key];
+    count--;
   }
 };
 const deriveNumber = (schema, isInteger) => {
@@ -516,7 +575,7 @@ const deriveNumber = (schema, isInteger) => {
   let value = Number.isFinite(lo) ? lo : Number.isFinite(hi) ? Math.min(0, hi) : 0;
   if (isInteger)
     value = Math.ceil(value);
-  if (hasMultipleOf(schema) && schema.multipleOf > 0) {
+  if (hasMultipleOf(schema) && Number.isFinite(schema.multipleOf) && schema.multipleOf > 0) {
     const m = schema.multipleOf;
     value = Math.ceil(value / m - 1e-9) * m;
     if (value > hi && Number.isFinite(hi))
@@ -551,35 +610,27 @@ const deriveArray = (schema, ctx) => {
   const unique = hasUniqueItems(schema) && schema.uniqueItems === true;
   const elem = rest ?? contains;
   const choices = unique && contains === void 0 ? closedValueSet(elem) : void 0;
-  const wanted = Math.min(Math.max(min, minContains, max === 0 ? 0 : 1), max);
+  const wanted = Math.min(Math.max(min, minContains, max === 0 ? 0 : 1), max, MAX_DERIVED_SIZE);
   const count = choices !== void 0 ? Math.min(wanted, choices.length) : wanted;
+  const itemsCheck = rest !== void 0 && contains !== void 0 ? makeInstanceCheck(rest, ctx.rootSchema) : void 0;
   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 ? derive(itemSchema, ctx) : null;
-    result.push(unique ? distinctify(base, i, itemSchema) : base);
+    const useContains = contains !== void 0 && i < minContains;
+    const itemSchema = useContains ? contains : elem;
+    let chosen = itemSchema;
+    let base = itemSchema !== void 0 ? derive(itemSchema, ctx) : null;
+    if (useContains && itemsCheck !== void 0 && !itemsCheck(base)) {
+      chosen = rest;
+      base = rest !== void 0 ? derive(rest, ctx) : null;
+    }
+    result.push(unique ? distinctify(base, i, chosen) : 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;
@@ -605,10 +656,20 @@ const TIGHTEST = /* @__PURE__ */ new Map([
   ["maxItems", "min"],
   ["maxProperties", "min"]
 ]);
+const flattenBranches = (nodes, depth = 0) => {
+  assertGeneratorDepth(depth, "mergeAllOf");
+  return nodes.flatMap((node) => {
+    if (!isSchemaObject(node) || !hasAllOf(node))
+      return [node];
+    const own = { ...node };
+    delete own["allOf"];
+    return [...flattenBranches(node.allOf, depth + 1), own];
+  });
+};
 const mergeAllOf = (schema) => {
-  const branches = hasAllOf(schema) ? schema.allOf : [];
-  const merged = {};
-  const properties = {};
+  const branches = hasAllOf(schema) ? flattenBranches(schema.allOf) : [];
+  const merged = /* @__PURE__ */ Object.create(null);
+  const properties = /* @__PURE__ */ Object.create(null);
   const required = /* @__PURE__ */ new Set();
   for (const branch of [...branches, schema]) {
     if (!isSchemaObject(branch))
@@ -636,7 +697,7 @@ const mergeAllOf = (schema) => {
       }
     }
   }
-  const mergedProps = {};
+  const mergedProps = /* @__PURE__ */ Object.create(null);
   for (const [prop, schemas] of Object.entries(properties)) {
     mergedProps[prop] = schemas.length === 1 ? schemas[0] : { allOf: schemas };
   }
@@ -671,9 +732,13 @@ const warnInvalidExample = (schema, typeName, value, rootSchema) => {
   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);
+  const { value, needsAssertion, cycleBroken } = deriveReported(schema, rootSchema);
   warnInvalidExample(schema, typeName, value, rootSchema);
-  return `export const ${exampleName(typeName)}: ${typeName} = ${serializeValue(value)}`;
+  const literal = serializeValue(value);
+  const admitsNothing = schema === false;
+  const assertion = cycleBroken || admitsNothing ? ` as unknown as ${typeName}` : needsAssertion ? ` as ${typeName}` : "";
+  const expression = `${literal}${assertion}`;
+  return `export const ${exampleName(typeName)}: ${typeName} = ${expression}`;
 };
 export {
   deriveExample,