@johnhenry/graceholder 0.0.0-stage → 0.1.0

package/src/rng.js

@@ -0,0 +1,89 @@
+// SplitMix64 and the frozen draw helpers (docs/design.md 2.3).
+// A Stream is local to ONE key: it is consumed only by that value's generator.
+
+const M = 0xffffffffffffffffn;
+const GAMMA = 0x9e3779b97f4a7c15n;
+const TWO64 = 1n << 64n;
+
+/**
+ * One SplitMix64 step.
+ * @param {bigint} state
+ * @returns {[bigint, bigint]} [output, nextState]
+ */
+export function splitmix64Next(state) {
+  const s = (state + GAMMA) & M;
+  let z = s;
+  z = ((z ^ (z >> 30n)) * 0xbf58476d1ce4e5b9n) & M;
+  z = ((z ^ (z >> 27n)) * 0x94d049bb133111ebn) & M;
+  return [z ^ (z >> 31n), s];
+}
+
+export class SplitMix64 {
+  /** @param {bigint} state */
+  constructor(state) {
+    this.state = state & M;
+  }
+
+  /** @returns {bigint} next unsigned 64-bit output */
+  next() {
+    const [out, s] = splitmix64Next(this.state);
+    this.state = s;
+    return out;
+  }
+}
+
+/**
+ * Unbiased integer in [lo, hi] using rejection sampling over u64 draws:
+ * a draw is accepted only when it is below the largest multiple of the range
+ * that fits in 2^64. At least one draw is always consumed.
+ * @param {() => bigint} next
+ */
+export function intFrom(next, lo, hi) {
+  if (!Number.isSafeInteger(lo) || !Number.isSafeInteger(hi) || hi < lo) {
+    throw new RangeError(`int(${lo}, ${hi}): need safe integers with lo <= hi`);
+  }
+  const range = BigInt(hi) - BigInt(lo) + 1n;
+  if (range > 1n << 53n) throw new RangeError(`int(${lo}, ${hi}): range exceeds 2^53`);
+  const limit = TWO64 - (TWO64 % range);
+  for (;;) {
+    const u = next();
+    if (u < limit) return Number(BigInt(lo) + (u % range));
+  }
+}
+
+export class Stream extends SplitMix64 {
+  /** @returns {number} in [0, 1) with 53 bits of precision */
+  float() {
+    return Number(this.next() >> 11n) / 2 ** 53;
+  }
+
+  /** @returns {number} integer in [lo, hi], inclusive, unbiased */
+  int(lo, hi) {
+    return intFrom(() => this.next(), lo, hi);
+  }
+
+  /** @template T @param {readonly T[]} arr @returns {T} */
+  pick(arr) {
+    if (arr.length === 0) throw new RangeError("pick() of an empty array");
+    return arr[this.int(0, arr.length - 1)];
+  }
+
+  /** @template T @param {ReadonlyArray<readonly [T, number]>} pairs @returns {T} */
+  weighted(pairs) {
+    let total = 0;
+    for (const [, w] of pairs) total += w;
+    if (!(total > 0)) throw new RangeError("weighted() needs a positive total weight");
+    const x = this.float() * total;
+    let acc = 0;
+    for (const [v, w] of pairs) {
+      acc += w;
+      if (x < acc) return v;
+    }
+    return pairs[pairs.length - 1][0];
+  }
+
+  /** @returns {boolean} true with probability p */
+  bool(p) {
+    return this.float() < p;
+  }
+}

package/src/rules.js

@@ -0,0 +1,228 @@
+// Inference rules: list-vs-one (L) and scalar type/generator by name (T). FROZEN at 1.0.0.
+import { tokenize, singularize, personaKind } from "./naming.js";
+
+
+const IRREGULAR_PLURALS = new Set(["people", "children", "men", "women", "mice"]);
+/** Plural-looking words that are singular count-like scalars (T8) or mass nouns. */
+const SINGULAR_PLURALS = new Set(["views", "likes", "votes", "dislikes", "news", "series", "species"]);
+const L4_NAMES = new Set(["list"]);
+
+function pluralLast(word) {
+  if (SINGULAR_PLURALS.has(word)) return false;
+  if (IRREGULAR_PLURALS.has(word)) return true;
+  if (word === "data") return false;
+  return word.endsWith("s") && !/(ss|us|is)$/.test(word);
+}
+
+/**
+ * L2-L6. L1 (directive/spec) arrives with M4.
+ * @param {string} fieldName
+ * @param {{ paging: boolean, idsArg: boolean, listLiteralArg: boolean, realistic?: boolean, object?: boolean }} ctx
+ * @returns {{ list: boolean, rule: string }}
+ */
+export function listRule(fieldName, ctx) {
+  const tokens = tokenize(fieldName);
+  const last = tokens[tokens.length - 1] ?? "";
+  if (ctx.paging) return { list: true, rule: "L2" };
+  // realistic mode: `salesHistory { date value }` is a time series, which is a list
+  if (ctx.realistic && ctx.object && SERIES_TYPE_WORDS.has(last)) return { list: true, rule: "L7" };
+  // realistic mode: a scalar `followers` or `sales` is a number, not a list of words
+  if (ctx.realistic && !ctx.object && Object.hasOwn(POPULARITY, last)) return { list: false, rule: "L6" };
+  if (pluralLast(last)) return { list: true, rule: "L3" };
+  if (L4_NAMES.has(fieldName.toLowerCase()) || L4_NAMES.has(last) || (tokens[0] === "all" && tokens.length > 1)) {
+    return { list: true, rule: "L4" };
+  }
+  if (ctx.idsArg || ctx.listLiteralArg) return { list: true, rule: "L5" };
+  return { list: false, rule: "L6" };
+}
+
+// --- scalar type by name ------------------------------------------------------
+
+const IMAGE_WORDS = new Set(["avatar", "image", "photo", "thumbnail", "picture", "logo"]);
+const IMAGE_SUFFIX = new Set(["url", "uri", "link", "src"]);
+const URL_WORDS = new Set(["url", "uri", "link", "website", "homepage"]);
+const PHONE_WORDS = new Set(["phone", "mobile", "tel", "telephone"]);
+const BOOL_PREFIX = new Set(["is", "has", "can", "should", "was", "did", "allow", "allows", "allowed"]);
+const BOOL_SUFFIX = new Set(["enabled", "active", "verified", "public", "deleted", "archived", "flag"]);
+
+/** T8: last word -> inclusive integer range. */
+const INT_RANGES = {
+  count: [0, 500], total: [0, 1000], qty: [1, 10], quantity: [1, 10], num: [1, 100], age: [18, 90],
+  year: [1990, 2024], index: [0, 99], position: [1, 20], rank: [1, 100], level: [1, 50], size: [1, 100],
+  length: [1, 100], views: [0, 100000], likes: [0, 5000], votes: [0, 1000],
+};
+
+/** T9: last word -> [generator, min, max]. */
+const FLOAT_RANGES = {
+  price: ["money", 1, 500], cost: ["money", 1, 500], amount: ["money", 1, 1000], total: ["money", 1, 1000],
+  subtotal: ["money", 1, 1000], tax: ["money", 0, 100], fee: ["money", 0, 100], balance: ["money", 0, 10000],
+  salary: ["money", 30000, 200000], revenue: ["money", 1000, 1000000], rate: ["float", 0, 100],
+  ratio: ["float", 0, 1], score: ["float", 0, 100], rating: ["float", 1, 5], weight: ["float", 1, 200],
+  height: ["float", 1, 250], lat: ["float", -90, 90], lng: ["float", -180, 180], latitude: ["float", -90, 90],
+  longitude: ["float", -180, 180], percent: ["float", 0, 100],
+};
+
+/**
+ * Realistic mode only (options.distributions: "realistic"): popularity-like counts are heavy-tailed.
+ * word -> [distribution, min, max]
+ */
+const POPULARITY = {
+  views: ["lognormal", 0, 1000000], view: ["lognormal", 0, 1000000], impressions: ["lognormal", 0, 5000000],
+  plays: ["lognormal", 0, 1000000], reads: ["lognormal", 0, 500000], clicks: ["lognormal", 0, 100000],
+  likes: ["lognormal", 0, 50000], like: ["lognormal", 0, 50000], shares: ["lognormal", 0, 10000],
+  followers: ["powerlaw", 0, 1000000], follower: ["powerlaw", 0, 1000000], subscribers: ["powerlaw", 0, 1000000],
+  stars: ["powerlaw", 0, 100000], downloads: ["powerlaw", 0, 10000000], sales: ["zipf", 0, 100000],
+};
+const SERIES_TYPE_WORDS = new Set(["history", "series", "timeline", "trend"]);
+const SERIES_DATE_WORDS = new Set(["date", "day", "at", "time", "timestamp", "month", "week", "period", "ts", "x"]);
+const SERIES_VALUE_WORDS = new Set([
+  "value", "amount", "count", "total", "price", "y", "balance", "close", "volume", "sales", "revenue", "views",
+  "visits", "users", "score", "rate", "temperature", "level", "reading",
+]);
+
+/** Realistic mode: is this the element type of a time series (`SalesHistory`, `PriceSeries`)? */
+export const isSeriesType = (typeName) => SERIES_TYPE_WORDS.has(tokenize(typeName).at(-1) ?? "");
+
+const COHERENT_DATES = { created: "time.created", updated: "time.updated", published: "time.published" };
+const DATE_WORDS = new Set(["at", "date", "time", "timestamp"]);
+const BIRTH_WORDS = new Set(["birthday", "dob"]);
+
+const ORG_TYPE_KINDS = new Set(["org"]);
+
+const r = (sdl, gen, rule, args = {}, extra = {}) => ({ sdl, gen, args, rule, ...extra });
+
+/**
+ * `<x>Count`, `<x>sCount` and `total<X>s` count a sibling collection (docs/design.md 6.2).
+ * @returns {string[]|null} the words naming the counted collection, last word singular
+ */
+export function countOf(fieldName) {
+  const tokens = tokenize(fieldName);
+  let words = null;
+  if (tokens.length >= 2 && tokens[tokens.length - 1] === "count") words = tokens.slice(0, -1);
+  else if (tokens.length >= 2 && tokens[0] === "total" && /s$/.test(tokens[tokens.length - 1]) && !SINGULAR_PLURALS.has(tokens[tokens.length - 1])) words = tokens.slice(1);
+  if (!words || (words.length === 1 && words[0] === "total")) return null;
+  const out = [...words];
+  out[out.length - 1] = singularize(out[out.length - 1]);
+  return out;
+}
+
+/**
+ * Pick the SDL scalar type and generator for a scalar field. First matching row wins (T1-T13).
+ * @param {string} fieldName
+ * @param {{ typeName: string, list: boolean, packs?: any[], realistic?: boolean }} ctx
+ * @returns {{ sdl: string, gen: string, args: Record<string, any>, rule: string, nullable?: boolean, pack?: string }}
+ */
+export function classifyScalar(fieldName, ctx) {
+  if (fieldName === "__typename") return r("String", "typename", "T2");
+  const tokens = tokenize(fieldName);
+  if (tokens.length === 0) return r("String", "words", "T13", { n: 2 });
+  if (ctx.list) tokens[tokens.length - 1] = singularize(tokens[tokens.length - 1]);
+  const last = tokens[tokens.length - 1];
+  const first = tokens[0];
+  const has = (w) => tokens.includes(w);
+  const kind = personaKind(ctx.typeName);
+
+  // T1
+  if (last === "id") {
+    if (tokens.length === 1 && !ctx.list) return r("ID", "id.key", "T1");
+    return r("ID", "id.int", "T1", { min: 1, max: 100, string: true });
+  }
+  // realistic mode: fields of a time-series element type (`salesHistory { date value }`)
+  if (ctx.realistic && isSeriesType(ctx.typeName)) {
+    if (tokens.length === 1 && SERIES_DATE_WORDS.has(last)) return r("DateTime", "series.date", "T14");
+    if (tokens.length === 1 && SERIES_VALUE_WORDS.has(last)) return r("Float", "series.value", "T14");
+  }
+  // packs, in order: the first pack that recognises the name wins (rule P1)
+  for (const pack of ctx.packs ?? []) {
+    const hit = pack.rules?.({ tokens, first, last, kind, typeName: ctx.typeName, list: ctx.list });
+    if (hit) return r(hit.sdl, hit.gen, "P1", hit.args ?? {}, { pack: pack.name, ...(hit.nullable ? { nullable: true } : {}) });
+  }
+  // T3
+  if (last === "email" || last === "mail" || (last === "address" && has("email"))) return r("String", "person.email", "T3");
+  // T5 before T4: `avatarUrl` is an image, not a plain url
+  if (IMAGE_WORDS.has(last) || (tokens.some((t) => IMAGE_WORDS.has(t)) && IMAGE_SUFFIX.has(last))) {
+    return r("String", "imageUrl", "T5");
+  }
+  // T4
+  if (URL_WORDS.has(last) || has("url")) return r("String", "url", "T4");
+  // T6
+  if (PHONE_WORDS.has(last)) return r("String", "person.phone", "T6");
+  // T7
+  if (BOOL_PREFIX.has(first) || BOOL_SUFFIX.has(last)) return r("Boolean", "bool", "T7");
+  // T8, realistic mode: heavy-tailed popularity counts (`views`, `likeCount`, `followers`, `sales`)
+  if (ctx.realistic) {
+    const word = Object.hasOwn(POPULARITY, last) ? last : (last === "count" || last === "total") && tokens.length > 1 ? tokens[tokens.length - 2] : undefined;
+    const pop = word !== undefined && Object.hasOwn(POPULARITY, word) ? POPULARITY[word] : undefined;
+    if (pop) return r("Int", "int", "T8", { min: pop[1], max: pop[2], dist: pop[0] });
+  }
+  // T8 (a type context overrides `total`, see T9)
+  const numberOf = first === "number" && tokens[1] === "of";
+  const orderTotal = last === "total" && kind === "order";
+  if ((last in INT_RANGES && !orderTotal) || numberOf) {
+    const [min, max] = numberOf ? INT_RANGES.count : INT_RANGES[last];
+    if (last === "age" && kind === "person" && tokens.length === 1) return r("Int", "person.age", "T8", { min, max });
+    return r("Int", "int", "T8", { min, max });
+  }
+  // T9
+  if (kind === "order" && tokens.length === 1 && (last === "subtotal" || last === "total" || last === "tax")) {
+    const [, min, max] = FLOAT_RANGES[last];
+    return r("Float", `order.${last}`, "T9", { min, max });
+  }
+  if (last in FLOAT_RANGES) {
+    const [gen, min, max] = FLOAT_RANGES[last];
+    return r("Float", gen, "T9", { min, max });
+  }
+  // T10
+  if (DATE_WORDS.has(last) || BIRTH_WORDS.has(last)) {
+    if (BIRTH_WORDS.has(last)) return r("DateTime", "time.birthday", "T10");
+    if (tokens.length === 2 && last === "at" && first === "deleted") return r("DateTime", "time.deleted", "T10", {}, { nullable: true });
+    if (tokens.length === 2 && last === "at" && first in COHERENT_DATES) return r("DateTime", COHERENT_DATES[first], "T10");
+    return r("DateTime", "datetime", "T10", { minDaysAgo: 30, maxDaysAgo: 1500 });
+  }
+  // T11
+  const named = namedString(tokens, first, last, has, kind, ctx.typeName);
+  if (named) return r("String", named.gen, "T11", named.args ?? {});
+  // T13
+  return r("String", "words", "T13", { n: 2 });
+}
+
+function namedString(tokens, first, last, has, kind, typeName) {
+  const prev = tokens[tokens.length - 2];
+  if (last === "name") {
+    if (prev === "first" || prev === "given") return { gen: "person.first" };
+    if (prev === "last" || prev === "family" || prev === "sur") return { gen: "person.last" };
+    if (prev === "full") return { gen: "person.full" };
+    if (kind === "product") return { gen: "product.name" };
+    if (ORG_TYPE_KINDS.has(kind)) return { gen: "company.name" };
+    return { gen: "person.full" };
+  }
+  if (last === "username" || last === "handle" || last === "nickname") return { gen: "person.username" };
+  if (last === "title") {
+    if (first === "job" && tokens.length === 2) return { gen: "person.jobTitle" };
+    if (kind === "person") return { gen: "person.jobTitle" };
+    return { gen: "title" };
+  }
+  if (last === "company" || last === "organization") return { gen: "company.name" };
+  if (last === "city") return { gen: "place.city" };
+  if (last === "state") return { gen: "place.state" };
+  if (last === "country") return { gen: "place.country" };
+  if (has("zip") || has("zipcode") || first === "postal") return { gen: "place.zip" };
+  if (last === "street") return { gen: "place.street" };
+  if (last === "address") return { gen: "place.address" };
+  if (last === "bio") return { gen: "person.bio" };
+  if (last === "description" || last === "summary" || last === "text" || last === "comment" || last === "message") return { gen: "sentence" };
+  if (last === "body" || last === "content") return { gen: "paragraph" };
+  if (last === "slug") return { gen: "slug" };
+  if (last === "status") return { gen: "oneOf", args: { vocab: "status" } };
+  if (last === "role") return { gen: "oneOf", args: { vocab: "role" } };
+  if (last === "color" || last === "colour") return { gen: "color" };
+  if (last === "currency") return { gen: "oneOf", args: { vocab: "currency" } };
+  if (last === "locale") return { gen: "oneOf", args: { vocab: "locale" } };
+  if (last === "language") return { gen: "oneOf", args: { vocab: "language" } };
+  if (last === "uuid") return { gen: "id.uuid" };
+  if (last === "ip") return { gen: "ip" };
+  if (last === "sku") return { gen: "pattern", args: { p: "AAA-#####" } };
+  if (last === "token") return { gen: "hex", args: { length: 32 } };
+  void typeName;
+  return null;
+}

package/src/scenario.js

@@ -0,0 +1,120 @@
+// Scenarios: repeatable edge-case modes (docs/design.md section 16, Scenarios).
+// A scenario never changes how a value is generated; it replaces what a field returns.
+// Every choice is a pure function of a key, so scenario output is as repeatable as the rest.
+import { GraceholderError } from "./errors.js";
+
+/** Canonical order; a scenario set is always normalised to this order. */
+export const SCENARIOS = Object.freeze(["empty", "huge", "nulls", "unicode", "boundary", "errors"]);
+
+/**
+ * Normalise a scenario value: a name, an array of names, or "none" / [] (no scenario).
+ * Returns undefined when nothing was given, [] for an explicit "none".
+ * @param {unknown} value
+ * @param {(msg: string) => Error} fail
+ * @returns {string[]|undefined}
+ */
+export function normalizeScenarios(value, fail) {
+  if (value === undefined || value === null) return undefined;
+  const list = Array.isArray(value) ? value : [value];
+  const names = new Set();
+  for (const s of list) {
+    if (s === "none") continue;
+    if (typeof s !== "string" || !SCENARIOS.includes(s)) {
+      throw fail(`unknown scenario ${JSON.stringify(s)} (known: ${SCENARIOS.join(", ")}, or "none")`);
+    }
+    names.add(s);
+  }
+  return SCENARIOS.filter((s) => names.has(s));
+}
+
+export const globalScenarios = (value) => normalizeScenarios(value, (m) => new GraceholderError("bad-options", `scenario: ${m}`)) ?? [];
+
+/** Default share of eligible fields that fail under the errors scenario. */
+export const DEFAULT_ERROR_RATE = 0.25;
+
+export function errorRateOf(options) {
+  const r = options?.errorRate;
+  if (r === undefined) return DEFAULT_ERROR_RATE;
+  if (typeof r !== "number" || !(r >= 0 && r <= 1)) throw new GraceholderError("bad-options", `scenarioOptions.errorRate must be a number between 0 and 1, got ${JSON.stringify(r)}`);
+  return r;
+}
+
+/** List sizes under `huge`, by how many lists enclose the field (a flat 500 would explode when nested). */
+const HUGE_BY_DEPTH = [100, 15, 6, 3];
+export const hugeSize = (depth) => HUGE_BY_DEPTH[Math.min(depth, HUGE_BY_DEPTH.length - 1)];
+/** Total of an endless collection (connection, paged list) under `huge`. */
+export const HUGE_TOTAL = 100000;
+
+/** Generators whose output is free text (the only strings the unicode scenario replaces). */
+const TEXT_GENS = new Set([
+  "words", "sentence", "paragraph", "title",
+  "person.first", "person.last", "person.full", "person.bio", "person.jobTitle",
+  "company.name", "product.name",
+  "place.address", "place.city", "place.country", "place.state", "place.street",
+]);
+export const isTextGen = (gen) => TEXT_GENS.has(gen);
+
+const LONG_UNIT = "The quick brown fox jumps over the lazy dog \u{1F98A} ";
+
+/** Strings that break layouts and encoders, kept as escapes so the file is plain ASCII. */
+const UNICODE = Object.freeze([
+  // right-to-left
+  "مرحبا بالعالم",
+  "שלום עולם",
+  "abc مرحبا 123 שלום def",
+  "‮evil‬ bidi override",
+  // emoji, ZWJ sequences, flags, skin tones
+  "\u{1F600}\u{1F680}\u{1F389}",
+  "\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466} family",
+  "\u{1F1EF}\u{1F1F5}\u{1F1FA}\u{1F1F8} flags \u{1F44D}\u{1F3FD}",
+  // combining marks
+  "Z͖͓͡à͔l͒͆g̕o҉",
+  "é vs é, ñ vs ñ",
+  // wide, CJK, zero-width, astral
+  "日本語のテキストと漢字",
+  "zero​width‌joiners⁠here",
+  "\u{1D4D0}\u{1D4D1}\u{1D4D2} \u{20BB7}\u{20BB8}",
+  // whitespace and markup that UIs mishandle
+  "  leading and trailing  ",
+  "line one\nline two\ttabbed",
+  "<b>bold</b> & \"quoted\" 'text' </script>",
+]);
+
+/** One string from the corpus; the last choice is a very long one. */
+export function unicodeValue(stream) {
+  const i = stream.int(0, UNICODE.length); // UNICODE.length is the very long string
+  if (i < UNICODE.length) return UNICODE[i];
+  return LONG_UNIT.repeat(60); // about 2800 UTF-16 units, multi-code-unit emoji included
+}
+
+const INT_EDGES = Object.freeze([0, 1, -1, 2147483647, -2147483648]);
+const FLOAT_EDGES = Object.freeze([0, 1, -1, Number.MAX_VALUE, -Number.MAX_VALUE, Number.MIN_VALUE, Number.EPSILON, Number.MAX_SAFE_INTEGER, Number.MIN_SAFE_INTEGER]);
+const DATE_EDGES = Object.freeze(["1970-01-01T00:00:00.000Z", "9999-12-31T23:59:59.999Z", "0001-01-01T00:00:00.000Z", "2038-01-19T03:14:07.000Z"]);
+
+/** A boundary value for an SDL scalar type, or undefined when the type has no boundary here. */
+export function boundaryValue(sdl, stream) {
+  switch (sdl) {
+    case "Int": return stream.pick(INT_EDGES);
+    case "Float": return stream.pick(FLOAT_EDGES);
+    case "DateTime": return stream.pick(DATE_EDGES);
+    case "String": return stream.bool(0.5) ? "" : "x";
+    default: return undefined;
+  }
+}
+
+const FAILURES = Object.freeze([
+  ["Simulated resolver failure", "INTERNAL_SERVER_ERROR"],
+  ["Upstream service unavailable", "SERVICE_UNAVAILABLE"],
+  ["Not authorized to read this field", "FORBIDDEN"],
+  ["The request timed out", "TIMEOUT"],
+]);
+
+/** The error a field fails with; graphql-js adds the path and locations. */
+export class ScenarioError extends Error {
+  constructor(stream) {
+    const [message, code] = stream.pick(FAILURES);
+    super(message);
+    this.name = "ScenarioError";
+    this.extensions = { code, scenario: "errors" };
+  }
+}

package/src/schema.js

@@ -0,0 +1,148 @@
+// Schema mode (docs/design.md section 17): load a schema given as SDL, an introspection
+// result or a graphql-js schema, and map its scalars onto generators.
+import {
+  buildSchema,
+  buildASTSchema,
+  buildClientSchema,
+  isSchema,
+  validateSchema,
+  Kind,
+  isNonNullType,
+  isListType,
+  isEnumType,
+  isScalarType,
+  isObjectType,
+  isInterfaceType,
+  isUnionType,
+  getNamedType,
+} from "graphql";
+import { GraceholderError } from "./errors.js";
+
+const cache = new WeakMap();
+const textCache = new Map();
+const TEXT_CACHE_MAX = 16;
+
+const bad = (msg, extra) => new GraceholderError("bad-schema", msg, extra);
+
+function build(input) {
+  if (isSchema(input)) return input;
+  if (typeof input === "string") return buildSchema(input);
+  if (input && typeof input === "object") {
+    if (input.kind === Kind.DOCUMENT) return buildASTSchema(input);
+    const introspection = input.__schema ? input : input.data?.__schema ? input.data : null;
+    if (introspection) return buildClientSchema(introspection);
+  }
+  throw bad("schema must be SDL text, a parsed SDL document, an introspection result ({ __schema } or { data: { __schema } }) or a GraphQLSchema");
+}
+
+/**
+ * Load and validate a schema. Results are cached by identity (objects) or text (strings).
+ * @param {unknown} input
+ * @returns {import("graphql").GraphQLSchema}
+ */
+export function loadSchema(input) {
+  const isText = typeof input === "string";
+  if (isText && textCache.has(input)) return textCache.get(input);
+  if (!isText && input && typeof input === "object" && cache.has(input)) return cache.get(input);
+  let schema;
+  try {
+    schema = build(input);
+  } catch (e) {
+    if (e instanceof GraceholderError) throw e;
+    throw bad(`could not read the schema: ${/** @type {Error} */ (e).message}`, { cause: e });
+  }
+  const problems = validateSchema(schema);
+  if (problems.length) throw bad(`the schema is not valid: ${problems[0].message}`, { cause: problems[0], hint: problems.slice(1, 4).map((p) => p.message).join("; ") || undefined });
+  if (!schema.getQueryType()) throw bad("the schema has no query root type");
+  if (isText) {
+    if (textCache.size >= TEXT_CACHE_MAX) textCache.delete(textCache.keys().next().value);
+    textCache.set(input, schema);
+  } else if (input && typeof input === "object") {
+    cache.set(input, schema);
+  }
+  return schema;
+}
+
+/**
+ * Decompose a field type.
+ * @param {import("graphql").GraphQLOutputType} type
+ * @returns {{ named: import("graphql").GraphQLNamedOutputType, list: boolean, nonNull: boolean, itemNonNull: boolean }}
+ */
+export function shapeOf(type) {
+  /** @type {any} */
+  let t = type;
+  const nonNull = isNonNullType(t);
+  if (nonNull) t = t.ofType;
+  let list = false;
+  let itemNonNull = false;
+  if (isListType(t)) {
+    list = true;
+    t = t.ofType;
+    if (isNonNullType(t)) {
+      itemNonNull = true;
+      t = t.ofType;
+    }
+    if (isListType(t)) {
+      throw new GraceholderError("unsupported", `nested list type ${String(type)} is not supported`, { hint: "use a list of objects, or override the field with a spec" });
+    }
+  }
+  return { named: getNamedType(type), list, nonNull, itemNonNull };
+}
+
+/** Concrete object types a (possibly abstract) type can be at run time, in schema order. */
+export function concreteTypes(schema, type) {
+  if (isObjectType(type)) return [type];
+  if (isInterfaceType(type) || isUnionType(type)) return [...schema.getPossibleTypes(type)];
+  return [];
+}
+
+// --- scalars -> generators ---------------------------------------------------------------------
+
+const DATE_TIME = { gen: "datetime", args: { minDaysAgo: 30, maxDaysAgo: 1500 } };
+
+/** Custom scalar name (lower case, `_`/`-` removed) -> generator. First hit wins; otherwise the field name decides. */
+/** @type {any[]} */
+const CUSTOM_ENTRIES = [
+  ...["datetime", "timestamp", "isodatetime", "instant", "utcdatetime", "localdatetime", "datetimeiso", "zoneddatetime", "offsetdatetime"].map((n) => [n, DATE_TIME]),
+  ...["date", "isodate", "calendardate", "localdate", "plaindate"].map((n) => [n, { gen: "datetime", args: { minDaysAgo: 30, maxDaysAgo: 1500, format: "date" } }]),
+  ...["url", "uri", "href", "weburl"].map((n) => [n, { gen: "url", args: {} }]),
+  ...["email", "emailaddress"].map((n) => [n, { gen: "person.email", args: {} }]),
+  ...["uuid", "guid"].map((n) => [n, { gen: "id.uuid", args: {} }]),
+  ...["phone", "phonenumber", "tel"].map((n) => [n, { gen: "person.phone", args: {} }]),
+  ...["ip", "ipv4", "ipaddress", "ipv4address"].map((n) => [n, { gen: "ip", args: {} }]),
+  ...["color", "colour", "hexcolor", "hexcolorcode"].map((n) => [n, { gen: "color", args: {} }]),
+  ...["slug"].map((n) => [n, { gen: "slug", args: {} }]),
+  ...["bigint", "long", "int64", "safeint", "nonnegativeint", "positiveint", "unsignedint", "uint", "integer"].map((n) => [n, { gen: "int", args: { min: 0, max: 100000 } }]),
+  ...["decimal", "bigdecimal", "float64", "double", "nonnegativefloat", "positivefloat", "money"].map((n) => [n, { gen: "float", args: { min: 0, max: 1000, decimals: 2 } }]),
+  ...["json", "jsonobject", "any", "object", "unknown", "void"].map((n) => [n, { gen: "words", args: { n: 2 } }]),
+];
+const CUSTOM_SCALARS = new Map(CUSTOM_ENTRIES);
+
+/** Look up the generator for a custom scalar by its own name. */
+export function customScalarGen(scalarName) {
+  return CUSTOM_SCALARS.get(scalarName.toLowerCase().replace(/[_-]/g, "")) ?? null;
+}
+
+/** May a heuristic generator whose SDL type is `heur` fill a built-in scalar `declared`? */
+export function compatible(heur, declared) {
+  switch (declared) {
+    case "Int": return heur === "Int" || heur === "ID";
+    case "Float": return heur === "Int" || heur === "Float";
+    case "Boolean": return heur === "Boolean";
+    case "String": return heur === "String" || heur === "DateTime" || heur === "ID";
+    case "ID": return heur === "ID" || heur === "String" || heur === "Int";
+    default: return false;
+  }
+}
+
+/** The generator used for a built-in scalar when no name heuristic fits its type. */
+export const BUILTIN_FALLBACK = {
+  Int: { gen: "int", args: { min: 0, max: 100 } },
+  Float: { gen: "float", args: { min: 0, max: 100, decimals: 2 } },
+  Boolean: { gen: "bool", args: {} },
+  String: { gen: "words", args: { n: 2 } },
+  ID: { gen: "id.key", args: {} },
+};
+
+/** A graphql type guard used by the walker. */
+export const isLeaf = (type) => isScalarType(type) || isEnumType(type);