@amritk/generate-parsers 0.24.0 → 0.25.1

package/AI.md

@@ -1,52 +0,0 @@
-# @amritk/generate-parsers — notes for AI coding agents
-
-Programmatic API: turn a JSON Schema (Draft 2020-12) into TypeScript type
-definitions plus optional runtime parser functions. Full reference is
-[README.md](./README.md). (Most users want the [`mjst` CLI](../cli) instead.)
-
-> Pre-alpha: APIs and generated output change pre-1.0.
-
-## Minimal example
-
-```ts
-import { buildSchema } from '@amritk/generate-parsers'
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
-
-const schema: JSONSchema = { type: 'object', properties: { title: { type: 'string' } } }
-
-const files = await buildSchema(schema, 'Document')
-// files → [{ filename: 'document.ts', content: '…' }, { filename: 'index.ts', content: '…' }, …]
-```
-
-## Gotchas — where agents fail
-
-1. **`buildSchema` is `async` and takes POSITIONAL args, no options object.** The
-   full signature is
-   `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?, helpersMode?, helpersImportPrefix?, readonly?, stripUnknown?, typeSuffix?, importExt?, caseInsensitive?, schemas?, unknownKeys?)`.
-   To set a later flag you must pass every intervening positional. (The README's
-   short form omits the trailing seven.) `unknownKeys` (`'count-keys'` by default,
-   `'count-enumerable'` for Node-only output) picks how a closed object's fast
-   path counts keys; nothing in the generated code detects its runtime.
-2. **It returns files in memory — it does NOT write to disk.** You write the
-   `GeneratedFile[]` (`{ filename, content }`) yourself. `rootTypeName` becomes
-   that filename (lowercased) as well as the `export type` name, so it must be a
-   TypeScript identifier — `buildSchema` throws otherwise rather than hand you a
-   path that escapes your output directory. Derive it with `@amritk/helpers`'
-   `deriveRootTypeName`, which always produces one.
-3. **Output is more than one file per `$def`:** always an `index.ts` barrel, and
-   (unless `typesOnly`) runtime helper files.
-4. **Default parsers COERCE invalid input to defaults** rather than throwing;
-   pass `strict: true` (the 6th positional) to make them throw.
-5. **Strict mode enforces the whole Draft 2020-12 assertion vocabulary** —
-   including `unevaluatedProperties` / `unevaluatedItems`, `contains` bounds,
-   `propertyNames`, `dependent*`, `patternProperties`, tuple `prefixItems`, and a
-   `$ref`'s 2020-12 siblings — and is held against Ajv by differential fuzz. It
-   deliberately differs on three points (`format` is an annotation, `multipleOf`
-   uses a scaled tolerance, a type-less `properties` schema still requires an
-   object); see the README.
-6. **Strict generation FAILS LOUDLY on anything it cannot enforce** (e.g. a
-   recursive `$ref` it would have to inline when ref imports are off). Catch the
-   error and fall back to a coercing parser if that is not what you want.
-
-Only the `.` entry (`buildSchema`, `GeneratedFile`, `ImportExtension`).
-Install: `bun add @amritk/generate-parsers`.

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

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

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

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

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

@@ -1,111 +0,0 @@
-import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
-import type { HelpersMode } from '../helpers/collect-helpers.js';
-import type { ImportExtension } from '../helpers/collect-imports.js';
-import type { SchemaExtensions } from '../types/schema-extensions.js';
-/**
- * Represents a generated file with its filename and content.
- */
-export type GeneratedFile = {
-    filename: string;
-    content: string;
-};
-/**
- * Builds all TypeScript files from a JSON Schema by traversing its entire
- * `$ref` / `$dynamicRef` graph (via the shared `@amritk/helpers/walk-ref-graph`
- * walker, which also seeds `$dynamicAnchor` definitions and rewrites
- * `$dynamicRef` to `$ref`).
- *
- * For the root schema and each reachable definition this function generates a
- * TypeScript file, then emits an `index.ts` barrel re-exporting them all.
- *
- * @param rootSchema - The root JSON Schema to build from
- * @param rootTypeName - The name for the root type (e.g., "Document"). Must be a TypeScript
- *   identifier: it is emitted verbatim as `export type <name>` and, lowercased, becomes the
- *   output filename, so a name derived from an untrusted document is refused rather than
- *   written outside the output directory.
- * @param extensions - Optional map of custom extension properties to add to specific definitions.
- *   Keys are definition names (matching $defs keys), values are records of extension property
- *   names to their JSON Schema definitions. Extensions are merged as optional properties before
- *   type and parser generation.
- * @param typesOnly - When true, only generate TypeScript type definitions without parser functions.
- * @param logWarnings - When true, the generated parsers emit a console.warn for every input key
- *   that is not declared in the schema's properties.
- * @param strict - When true, the generated parsers throw on type/shape mismatches
- *   (wrong type, missing required property, enum/pattern/min/max violations) instead
- *   of coercing invalid input to default values.
- * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
- *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
- *   as additional `GeneratedFile` entries so the output directory is self-contained.
- * @param helpersImportPrefix - Relative path prefix to the `_helpers/` directory in
- *   embedded mode. Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
- *   `'../../'`, etc. so nested parsers can import from a single shared `_helpers/`
- *   directory while the helper sources are emitted once at the output root.
- * @param readonly - When true, every property, array, and record in the generated type
- *   definitions is emitted as `readonly`.
- * @param stripUnknown - When true, the generated parsers build their result from declared
- *   properties only, silently dropping undeclared input keys at every nesting level (zod's
- *   `.strip()`) without treating extras as a validation error. Composes with `strict` and
- *   yields to `additionalProperties: false` (which rejects rather than strips in strict mode).
- * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
- *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
- *   is used verbatim and is not affected by this suffix.
- * @param importExt - Extension used on every relative import specifier in the generated
- *   output (cross-file `$ref` imports, the index barrel, and embedded-helper imports).
- *   `'js'` (this function's default) is the standard TS NodeNext form; `'ts'` emits the
- *   literal on-disk paths so the generated sources run directly under Node's type
- *   stripping. Note the `mjst` CLI defaults this to `'ts'` (falling back to `'js'` only
- *   under `--build`, where tsc must compile the sources) so generated output runs under
- *   Node without a build step; direct callers of `buildSchema` opt in explicitly.
- * @param caseInsensitive - When true, the generated coercing parsers normalize a mis-cased
- *   string to the exact casing of a declared `enum`/`const` member it matches
- *   case-insensitively (e.g. `hElLo` → `hello`) instead of coercing to the default. Coerce
- *   mode only — strict parsers still reject a casing mismatch. The normalization lives on
- *   the coercion failure branch, so correctly-cased input keeps the exact-match fast path
- *   and the hot path is unaffected.
- * @param schemas - Other schema documents you have **already loaded**, keyed by the absolute
- *   URI a `$ref` names them by. Supplying them makes those URIs resolvable, so the schema can
- *   reference a document that is not itself — each one becomes a resource of the generated
- *   document, with its own `$id`, anchors and nested resources all resolvable, and a `$ref`
- *   from one registered document into another resolving too. Nothing is fetched here: loading
- *   is yours to do (or `@amritk/resolve-refs`'), and a `$ref` to a URI nobody registered still
- *   stops generation. Only the documents actually referenced get files, so registering more
- *   than the schema uses costs nothing in the output.
- * @param unknownKeys - How the generated fast paths prove a closed object
- *   (`additionalProperties: false`, or a `stripUnknown` build) carries no undeclared key:
- *   `'count-keys'` (the default) compares `Object.keys(input).length` behind a plain-prototype
- *   guard, `'count-enumerable'` counts with `for…in`. The first is the faster form on
- *   JavaScriptCore (Bun), the second on V8 (Node) — see the README for the measurements.
- * @returns An array of generated TypeScript files
- *
- * @example
- * ```typescript
- * const schema = {
- *   type: "object",
- *   properties: {
- *     info: { $ref: "#/$defs/info" }
- *   },
- *   $defs: {
- *     info: {
- *       type: "object",
- *       properties: {
- *         title: { type: "string" }
- *       }
- *     }
- *   }
- * };
- *
- * const files = buildSchema(schema, "Document");
- *
- * // Types-only mode — no parser functions or runtime helpers included:
- * const typesFiles = buildSchema(schema, "Document", undefined, true);
- *
- * // With extensions:
- * const filesWithExtensions = buildSchema(schema, "Document", {
- *   info: {
- *     'x-internal': { type: 'boolean' },
- *   },
- * });
- * ```
- */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension, caseInsensitive?: boolean, schemas?: Readonly<Record<string, unknown>>, unknownKeys?: UnknownKeysStrategy) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -1,74 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { dirname, resolve as resolvePath } from "node:path";
-import { foldNullable } from "@amritk/helpers/fold-nullable";
-import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
-import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
-import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
-import { applySchemaExtensions } from "../helpers/apply-schema-extensions.js";
-import { generateFile } from "./generate-files.js";
-const readHelperSource = async (helper, importExt) => {
-  const require2 = createRequire(import.meta.url);
-  const helpersRoot = dirname(require2.resolve("@amritk/helpers/package.json"));
-  try {
-    const source = await readFile(resolvePath(helpersRoot, "src", `${helper}.ts`), "utf-8");
-    return { ext: "ts", content: source.replace(/\bfrom '(\.\/[^'".]+)'/g, `from '$1.${importExt}'`) };
-  } catch {
-    const compiled = await readFile(resolvePath(helpersRoot, "dist", `${helper}.js`), "utf-8");
-    if (importExt === "ts") {
-      return { ext: "ts", content: compiled.replace(/\bfrom '(\.\/[^'"]+)\.js'/g, "from '$1.ts'") };
-    }
-    return { ext: "js", content: compiled };
-  }
-};
-const ROOT_TYPE_NAME = /^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u;
-const assertRootTypeName = (rootTypeName) => {
-  if (ROOT_TYPE_NAME.test(rootTypeName))
-    return;
-  throw new Error(`Invalid root type name ${JSON.stringify(rootTypeName)}: expected a TypeScript identifier. The name is emitted as \`export type <name>\` and, lowercased, used as the output filename, so anything else either fails to compile or escapes the output directory. Derive it with @amritk/helpers' \`deriveRootTypeName\`, which always produces one.`);
-};
-const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false, schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
-  assertRootTypeName(rootTypeName);
-  const files = [];
-  const usedHelpers = /* @__PURE__ */ new Set();
-  const foldedSchema = foldNullable(rootSchema);
-  walkRefGraph(foldedSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
-    if (node.filename === "index")
-      return;
-    const extended = extensions ? applySchemaExtensions(node.schema, node.filename, extensions) : node.schema;
-    const result = generateFile(extended, node.typeName, {
-      selfFilename: node.filename,
-      typesOnly: typesOnly ?? false,
-      rootSchema: node.rootSchema,
-      helpersMode,
-      helpersImportPrefix,
-      readonly,
-      typeSuffix,
-      importExt,
-      isRoot: node.isRoot,
-      ...node.ref !== void 0 ? { selfRef: node.ref } : {},
-      ...logWarnings !== void 0 ? { logWarnings } : {},
-      ...strict !== void 0 ? { strict } : {},
-      ...stripUnknown ? { stripUnknown } : {},
-      ...caseInsensitive ? { caseInsensitive } : {},
-      unknownKeys
-    });
-    files.push({ filename: `${node.filename}.ts`, content: result.content });
-    for (const helper of result.usedHelpers)
-      usedHelpers.add(helper);
-  });
-  if (helpersMode === "embedded" && !typesOnly) {
-    for (const helper of usedHelpers) {
-      const { ext, content } = await readHelperSource(helper, importExt);
-      files.push({ filename: `_helpers/${helper}.${ext}`, content });
-    }
-  }
-  files.push({
-    filename: "index.ts",
-    content: generateIndexBarrel(files, { typesOnly: typesOnly ?? false, importExt })
-  });
-  return files;
-};
-export {
-  buildSchema
-};

package/dist/generators/generate-deep-equal-check.d.ts

@@ -1,24 +0,0 @@
-/**
- * Builds a boolean expression that is TRUE when `accessor` is structurally equal
- * to `value` — a literal known at generation time (an `enum` member, a `const`).
- *
- * Why not `===` / `.includes` / `JSON.stringify`, the three forms this replaced:
- *
- * - `.includes(x)` is SameValueZero, i.e. *reference* equality for objects and
- *   arrays. `{ enum: [{ a: 1 }] }` could therefore never match a freshly parsed
- *   `{ a: 1 }`, so the strict parser threw on a document Ajv accepts and the fast
- *   path never fired.
- * - `JSON.stringify(x) !== '{"a":1,"b":2}'` is key-order sensitive, so a
- *   reordered-but-equal `{ b: 2, a: 1 }` was rejected — and it serialized the
- *   whole value on every call just to answer a yes/no question.
- *
- * Because the literal is known up front the comparison is unrolled into a flat
- * chain of `typeof` / `===` tests against its shape: no serialization, no
- * allocation, and key order cannot matter because keys are compared by name. The
- * `Object.keys(...).length === n` term is what makes it an equality rather than a
- * "has at least these fields" check.
- *
- * @param accessor - Expression yielding the runtime value (may be `unknown`).
- * @param value - The literal to compare against.
- */
-export declare const generateDeepEqualCheck: (accessor: string, value: unknown) => string;

package/dist/generators/generate-deep-equal-check.js

@@ -1,35 +0,0 @@
-import { safeAccessor } from "@amritk/helpers/safe-accessor";
-const generateDeepEqualCheck = (accessor, value) => {
-  if (value === null || typeof value !== "object") {
-    if (typeof value === "number" && Number.isNaN(value))
-      return `Number.isNaN(${accessor})`;
-    return `${accessor} === ${JSON.stringify(value)}`;
-  }
-  if (Array.isArray(value)) {
-    const elements = `(${accessor} as unknown[])`;
-    const parts2 = [`Array.isArray(${accessor})`, `${elements}.length === ${value.length}`];
-    for (let i = 0; i < value.length; i++) {
-      parts2.push(generateDeepEqualCheck(`${elements}[${i}]`, value[i]));
-    }
-    return parts2.join(" && ");
-  }
-  const entries = Object.entries(value);
-  const record = `(${accessor} as Record<string, unknown>)`;
-  const parts = [
-    `typeof ${accessor} === "object"`,
-    `${accessor} !== null`,
-    `!Array.isArray(${accessor})`,
-    // Pins the key count, so an object carrying extra keys is not "equal" to one
-    // that only has the declared ones. Combined with the per-key value checks
-    // below (an absent key reads as `undefined`, which no JSON literal equals)
-    // this is exact structural equality.
-    `Object.keys(${accessor} as object).length === ${entries.length}`
-  ];
-  for (const [key, sub] of entries) {
-    parts.push(generateDeepEqualCheck(safeAccessor(record, key), sub));
-  }
-  return parts.join(" && ");
-};
-export {
-  generateDeepEqualCheck
-};

package/dist/generators/generate-default-from-pattern.d.ts

@@ -1,26 +0,0 @@
-/**
- * Builds a default string for a `pattern`-constrained schema — a value a
- * coercing parser can fall back to when the input cannot be repaired.
- *
- * The one invariant: **a returned default always matches the pattern it was
- * built from** (and any length bounds handed in alongside it). Every candidate,
- * synthesized or recognized, is tested against the real `RegExp` before it is
- * returned, and anything that fails is discarded. That check is the whole point.
- * Without it this returned a value the schema rejects — `'^\\+?\\d{3}\\d{4}$'`
- * was answered with `"+1234567890"`, which has three digits too many — so a
- * coercing parser "repaired" input into a document still invalid against its own
- * schema, and the array or object built around it was invalid for the same
- * reason.
- *
- * Two sources of candidates, in order:
- *
- *  1. {@link synthesize}, which reads the pattern and constructs a matching
- *     string from it. This covers the ordinary shapes real schemas use — slugs,
- *     identifiers, fixed-width codes — that no fixed list can anticipate.
- *  2. A short list of well-known shapes (email, UUID, URL, semver, ISO date),
- *     which read better than a synthesized `"aaa"` when they happen to fit.
- *
- * Returns `null` when nothing verifies, which callers already treat as "no
- * usable default" — the safe answer, and far better than a confident wrong one.
- */
-export declare const generateDefaultFromPattern: (pattern: string, minLength?: number, maxLength?: number) => string | null;

package/dist/generators/generate-default-from-pattern.js

@@ -1,223 +0,0 @@
-const RECOGNIZED_DEFAULTS = [
-  "user@example.com",
-  "00000000-0000-0000-0000-000000000000",
-  "https://example.com",
-  "1.0.0",
-  "2000-01-01",
-  "+1234567890"
-];
-const UNSUPPORTED = /\(\?[=!<]|\\[1-9]|\\b|\\B/;
-const PREFERRED = "abcdefghijklmnopqrstuvwxyz0123456789";
-const escapedChar = (sequence) => {
-  switch (sequence) {
-    case "d":
-      return "0";
-    case "w":
-      return "a";
-    case "s":
-      return " ";
-    case "D":
-    case "S":
-      return "a";
-    case "W":
-      return "-";
-    case "n":
-      return "\n";
-    case "t":
-      return "	";
-    case "r":
-      return "\r";
-    default:
-      return null;
-  }
-};
-const ONCE = { min: 1, max: 1 };
-const pickFromClass = (body) => {
-  const negated = body.startsWith("^");
-  const source = negated ? body.slice(1) : body;
-  const members = [];
-  for (let i = 0; i < source.length; i++) {
-    const char = source[i];
-    if (char === "\\") {
-      const next = source[++i];
-      if (next === void 0)
-        return null;
-      members.push(escapedChar(next) ?? next);
-      continue;
-    }
-    if (source[i + 1] === "-" && i + 2 < source.length && source[i + 2] !== "]") {
-      const low = char;
-      const high = source[i + 2];
-      const preferred = [...PREFERRED].find((candidate) => candidate >= low && candidate <= high);
-      members.push(preferred ?? low);
-      i += 2;
-      continue;
-    }
-    members.push(char);
-  }
-  if (!negated) {
-    return [...PREFERRED].find((candidate) => members.includes(candidate)) ?? members[0] ?? null;
-  }
-  return [...PREFERRED].find((candidate) => !members.includes(candidate)) ?? null;
-};
-const readQuantifier = (pattern, start) => {
-  const char = pattern[start];
-  let quantifier = ONCE;
-  let next = start;
-  if (char === "*") {
-    quantifier = { min: 0, max: Number.POSITIVE_INFINITY };
-    next = start + 1;
-  } else if (char === "+") {
-    quantifier = { min: 1, max: Number.POSITIVE_INFINITY };
-    next = start + 1;
-  } else if (char === "?") {
-    quantifier = { min: 0, max: 1 };
-    next = start + 1;
-  } else if (char === "{") {
-    const close = pattern.indexOf("}", start);
-    const body = close === -1 ? null : pattern.slice(start + 1, close);
-    const match = body === null ? null : /^(\d+)(,(\d*)?)?$/.exec(body);
-    if (match && close !== -1) {
-      const min = Number(match[1]);
-      const max = match[2] === void 0 ? min : match[3] ? Number(match[3]) : Number.POSITIVE_INFINITY;
-      quantifier = { min, max };
-      next = close + 1;
-    }
-  }
-  if (quantifier !== ONCE && (pattern[next] === "?" || pattern[next] === "+"))
-    next += 1;
-  return { quantifier, next };
-};
-const parseAlternatives = (pattern, start, stop) => {
-  const alternatives = [];
-  let current = [];
-  let i = start;
-  while (i < stop) {
-    const char = pattern[i];
-    if (char === ")")
-      break;
-    if (char === "|") {
-      alternatives.push(current);
-      current = [];
-      i += 1;
-      continue;
-    }
-    let node = null;
-    if (char === "(") {
-      let bodyStart = i + 1;
-      if (pattern.startsWith("(?:", i))
-        bodyStart = i + 3;
-      else if (pattern.startsWith("(?<", i)) {
-        const close = pattern.indexOf(">", i);
-        if (close === -1)
-          return { alternatives: [], next: stop };
-        bodyStart = close + 1;
-      }
-      const inner = parseAlternatives(pattern, bodyStart, stop);
-      if (pattern[inner.next] !== ")")
-        return { alternatives: [], next: stop };
-      const { quantifier, next } = readQuantifier(pattern, inner.next + 1);
-      node = { kind: "group", alternatives: inner.alternatives, quantifier };
-      i = next;
-    } else if (char === "[") {
-      let end = i + 1;
-      if (pattern[end] === "^")
-        end += 1;
-      if (pattern[end] === "]")
-        end += 1;
-      while (end < stop && pattern[end] !== "]")
-        end += pattern[end] === "\\" ? 2 : 1;
-      if (end >= stop)
-        return { alternatives: [], next: stop };
-      const picked = pickFromClass(pattern.slice(i + 1, end));
-      if (picked === null)
-        return { alternatives: [], next: stop };
-      const { quantifier, next } = readQuantifier(pattern, end + 1);
-      node = { kind: "class", value: picked, quantifier };
-      i = next;
-    } else if (char === "\\") {
-      const sequence = pattern[i + 1];
-      if (sequence === void 0)
-        return { alternatives: [], next: stop };
-      const { quantifier, next } = readQuantifier(pattern, i + 2);
-      node = { kind: "literal", value: escapedChar(sequence) ?? sequence, quantifier };
-      i = next;
-    } else if (char === ".") {
-      const { quantifier, next } = readQuantifier(pattern, i + 1);
-      node = { kind: "class", value: "a", quantifier };
-      i = next;
-    } else if (char === "^" || char === "$") {
-      i += 1;
-      continue;
-    } else {
-      const { quantifier, next } = readQuantifier(pattern, i + 1);
-      node = { kind: "literal", value: char, quantifier };
-      i = next;
-    }
-    current.push(node);
-  }
-  alternatives.push(current);
-  return { alternatives, next: i };
-};
-const render = (nodes, budget) => {
-  let out = "";
-  for (const node of nodes) {
-    const { min, max } = node.quantifier;
-    const count = Math.min(min + (max > min ? budget : 0), max);
-    const unit = node.kind === "group" ? render(node.alternatives[0] ?? [], budget) : node.value;
-    out += unit.repeat(count);
-  }
-  return out;
-};
-const synthesize = (pattern) => {
-  if (UNSUPPORTED.test(pattern))
-    return [];
-  const { alternatives } = parseAlternatives(pattern, 0, pattern.length);
-  const candidates = [];
-  for (const alternative of alternatives) {
-    for (let budget = 0; budget <= 64; budget++) {
-      const rendered = render(alternative, budget);
-      candidates.push(rendered);
-      if (rendered.length > 512)
-        break;
-    }
-  }
-  return candidates;
-};
-const compile = (pattern) => {
-  try {
-    return new RegExp(pattern, "u");
-  } catch {
-    try {
-      return new RegExp(pattern);
-    } catch {
-      return null;
-    }
-  }
-};
-const generateDefaultFromPattern = (pattern, minLength, maxLength) => {
-  if (pattern === "")
-    return null;
-  const regex = compile(pattern);
-  if (regex === null)
-    return null;
-  const low = typeof minLength === "number" && minLength > 0 ? minLength : 0;
-  const high = typeof maxLength === "number" && maxLength >= 0 ? maxLength : Number.POSITIVE_INFINITY;
-  const fits = (candidate) => {
-    if (candidate.length < low || candidate.length > high)
-      return false;
-    return regex.test(candidate);
-  };
-  for (const candidate of RECOGNIZED_DEFAULTS) {
-    if (fits(candidate))
-      return JSON.stringify(candidate);
-  }
-  for (const candidate of synthesize(pattern)) {
-    if (fits(candidate))
-      return JSON.stringify(candidate);
-  }
-  return null;
-};
-export {
-  generateDefaultFromPattern
-};