@drzl/validation-core 3.20.0 → 3.22.0

package/dist/index.d.ts

@@ -95,6 +95,79 @@ declare function resolveBranding(opt: BrandingOption | undefined): ResolvedBrand
  */
 declare function buildBrandPlan(tables: Table$1[], opt: BrandingOption | undefined): BrandPlan | undefined;
 
+/**
+ * Where a generator's files go, so that "write it" and "tell me what you would write" are the same
+ * code path (plan items 68, 80, 81).
+ *
+ * Three requests turn out to be one mechanism. `--dry-run` needs to know what would be written
+ * without writing it, `generate` needs to say which files it created and which it changed rather
+ * than only how many it wrote, and `--check` needs to show a diff of the difference. All three are
+ * the same question asked per file: what content is about to land here, and what is here now. The
+ * only thing a generator has to give up for that is deciding, itself, that the answer goes to disk.
+ *
+ * ## Why an option and not an interception
+ *
+ * The tempting version is to leave every generator alone and patch `node:fs/promises` for the
+ * duration of the run, since each one reaches it through `await import('node:fs/promises')`. That
+ * was measured and rejected. Patching the CommonJS exports object is visible through a later
+ * dynamic import, but a module namespace that already exists is a snapshot and never changes:
+ *
+ *   const ns = await import('node:fs/promises');       // namespace built here
+ *   require('node:fs/promises').writeFile = spy;       // patch applied after
+ *   ns.writeFile === spy                               // false, measured on Node 22.22
+ *
+ * The CLI links `chokidar`, which imports `node:fs/promises` at module scope, so by the time any
+ * command body runs the namespace usually exists and the patch is invisible. A dry run built on
+ * that would write real files whenever an unrelated dependency happened to import first, which is
+ * the worst possible failure for this feature: silent, environmental, and destructive. An explicit
+ * option cannot fail that way, because a generator that never received a sink is a generator whose
+ * call site can be read.
+ *
+ * ## Shape
+ *
+ * `fileWriter` returns an object with the two methods every generator already calls on the
+ * `node:fs/promises` namespace, with the same signatures, so adopting it is one line per generator
+ * and no write site changes at all:
+ *
+ *   const fs = await import('node:fs/promises');   ->   const fs = fileWriter(opts.fileSink);
+ *
+ * That matters more than it looks. Fourteen generators write files, between one and six times
+ * each, and a change that touched every one of those sites would be fourteen chances to miss one
+ * and ship a dry run that writes.
+ */
+/**
+ * Somewhere for a generator's output to go that is not the filesystem.
+ *
+ * `mkdir` is part of it because a dry run that creates directories is not a dry run: run in an
+ * empty project, the honest answer leaves the directory empty, and `fs.mkdir(out, { recursive:
+ * true })` is the first thing every generator does.
+ */
+interface FileSink {
+    mkdir(dir: string): void | Promise<void>;
+    writeFile(file: string, contents: string): void | Promise<void>;
+}
+/**
+ * The `node:fs/promises` subset generators use, narrowed to the two calls they actually make.
+ *
+ * Declared structurally rather than imported from `node:fs` so that the real namespace satisfies
+ * it without a cast and a sink can too. The `options` and `encoding` parameters are accepted and
+ * ignored by a sink: every call site in this repository passes `{ recursive: true }` and `'utf8'`,
+ * and a sink that took different arguments would make the swap a rewrite rather than a rename.
+ */
+interface GeneratorFs {
+    mkdir(dir: string, options?: {
+        recursive?: boolean;
+    }): Promise<unknown>;
+    writeFile(file: string, contents: string, encoding?: BufferEncoding): Promise<void>;
+}
+/**
+ * The filesystem, or whatever was passed instead of it.
+ *
+ * Without a sink this is `node:fs/promises` itself, so a run with no sink performs the same calls
+ * in the same order as before this existed.
+ */
+declare function fileWriter(sink?: FileSink): GeneratorFs;
+
 /**
  * One place that decides what a generated module is called, on disk and in an import.
  *
@@ -253,6 +326,22 @@ declare function resolveAffix(opts?: {
 declare function schemaName(mode: NameMode, tsName: string, affix: ResolvedAffix): string;
 /** Name of the exported type alias, e.g. `InsertusersInput`. */
 declare function typeName(mode: NameMode, tsName: string, affix: ResolvedAffix): string;
+/**
+ * The same two rules, as JSON Schema `pattern` strings, for `drzl.config.schema.json`.
+ *
+ * `z.toJSONSchema` drops refinements without saying so, and the affix rules live in
+ * `ConfigSchema`'s only `.superRefine`. A generated schema would therefore have told an editor
+ * that `suffix: 'my-schema'` was fine, and the CLI would then have refused to generate from it.
+ * Re-encoding the character half here keeps one definition of the rule rather than a regex in
+ * this file and a hand-copied pattern in the schema builder.
+ *
+ * The body is optional because `checkOne` returns early for the empty string: an empty affix
+ * means "none" and is always legal. Equivalence with `validateAffix` is not argued from that
+ * sentence, it is fuzzed over every printable ASCII position in
+ * packages/cli/test/config-json-schema.spec.ts.
+ */
+declare const AFFIX_PREFIX_PATTERN = "^(?:[A-Za-z_$][A-Za-z0-9_$]*)?$";
+declare const AFFIX_SUFFIX_PATTERN = "^(?:[A-Za-z0-9_$]+)?$";
 /**
  * Reject affixes that cannot produce a compilable file, before anything is written:
  *  - characters that are not legal in a TypeScript identifier
@@ -288,6 +377,11 @@ declare function validateAffix(affix?: AffixOptions, schemaSuffix?: string): Aff
  *    base expression rather than on the whole field.
  * 2. **A multi-column check cannot live on a field.** `start_date < end_date` is a statement
  *    about the row, so it is not returned here at all.
+ * 3. **A conjunction splits and a disjunction does not.** Every part of an `AND` has to hold on
+ *    its own, so a list of checks says exactly what it says. An `OR` is *weaker* than either
+ *    branch: a schema enforcing one branch turns away every row that satisfied the other. So a
+ *    disjunction is read only where the whole of it collapses to one statement, and refused
+ *    whole otherwise. See `parseDisjunction`.
  */
 /** A comparison of one column against one literal, which is the case worth translating. */
 interface ColumnCheck {
@@ -326,7 +420,8 @@ interface RowCheck {
     name?: string;
 }
 /**
- * A constraint on a column's *character* count, from `CHECK (length(name) > 3)`.
+ * A constraint on a count derived from a column's value, from `CHECK (length(name) > 3)` and
+ * `CHECK (octet_length(blob) <= 5)`.
  *
  * Kept apart from `ColumnCheck` because it is not a comparison of the value: it compares a count
  * derived from it, and the count Postgres takes is code points rather than UTF-16 units. See
@@ -337,8 +432,88 @@ interface LengthCheck {
     operator: ColumnCheck['operator'];
     /** Decimal, as text, matching how the other bounds are carried. */
     value: string;
+    /**
+     * Which count the expression asked for.
+     *
+     * Absent on a pre-1.x parse, where every count was a character count, so a consumer reading this
+     * treats `undefined` as `'characters'`. `lengthMeasure` is the one place that decision is made.
+     *
+     * This is *not* the whole answer, because the same function means different things on different
+     * column types. Measured on PostgreSQL 17.5 through PGlite, on a `text` holding three emoji and
+     * a `bytea` holding six bytes:
+     *
+     *   | expression        | text | bytea          |
+     *   | ----------------- | ---- | -------------- |
+     *   | `octet_length(x)` | 12   | 6              |
+     *   | `length(x)`       | 3    | 6              |
+     *   | `char_length(x)`  | 3    | does not exist |
+     *
+     * So the unit says what the *expression* asked for and `lengthMeasure` says how to answer it for
+     * a given column.
+     */
+    unit?: 'characters' | 'bytes';
     name?: string;
 }
+/**
+ * How a `LengthCheck` is answered in JavaScript, once the column it names is known.
+ *
+ * Three answers, and no two of them agree on the same value:
+ *
+ *   `codePoints`   `[...v].length`                              a character count
+ *   `utf8Bytes`    `new TextEncoder().encode(v).length`         a byte count of a string
+ *   `byteLength`   `v.length`, on a Uint8Array                  a byte count of a binary payload
+ *
+ * `v.length` on a *string* is none of them: it counts UTF-16 units, which is 6 for the three emoji
+ * whose character count is 3 and whose byte count is 12.
+ */
+type LengthMeasure = 'codePoints' | 'utf8Bytes' | 'byteLength';
+/**
+ * How to answer a count on this column, or nothing where no expression answers it.
+ *
+ * The one place the column type and the expression meet, held here rather than in each generator so
+ * the emitted predicate and the constraint ledger cannot disagree about what is enforced.
+ *
+ * Three refusals, each because the count would be a different measurement than the database took:
+ *
+ * - **An array.** Postgres has no `length(anyarray)`; `cardinality` is the array's own count and is
+ *   carried separately.
+ * - **A byte-string column**, MySQL's `binary(n)`/`varbinary(n)`. It arrives as a string produced by
+ *   a lossy decode, so neither its code points nor their UTF-8 re-encoding is the server's byte
+ *   count: `<ff ff ff>` from a `varbinary(3)` comes back as 3 code points that re-encode to 9
+ *   bytes. See `ColumnShape`.
+ * - **Anything that is not a string or a binary payload.** `length` is defined for text, bytea and
+ *   bit strings, so a count on a number column cannot come from a schema the database accepted, and
+ *   spreading a number with `[...v]` would throw rather than fail.
+ *
+ * A `bytea` answers both functions with the same number, which is why the unit is not consulted
+ * there. `char_length(bytea)` is the one spelling that would break that, and Postgres does not have
+ * it: `function char_length(bytea) does not exist`, measured.
+ */
+declare function lengthMeasure(column: {
+    tsType?: string;
+    arrayDimensions?: number;
+    shape?: {
+        kind: string;
+    };
+}, check: LengthCheck): LengthMeasure | undefined;
+/**
+ * The JavaScript expression that takes one of the three measurements, over a named variable.
+ *
+ * A function of the variable name rather than a constant, because the five validation generators
+ * put the count in three different places: zod and valibot pipe the value itself, while ArkType and
+ * TypeBox reach it off the row object as `o["blob"]`. `CODEPOINT_LENGTH` is the fixed-variable
+ * spelling of the first arm and stays for the call sites that already use it.
+ */
+declare function measureExpression(measure: LengthMeasure, variable: string): string;
+/**
+ * A count constraint as the sentence every emitted schema attaches and the ledger keys on.
+ *
+ * Held here rather than spelled out in each generator, because the constraint error map matches an
+ * issue's message against this string exactly: the two drifting by one character is a map that
+ * silently answers nothing. `char_length` is normalised to `length`, as it always has been, since
+ * the two are the same function in Postgres.
+ */
+declare function lengthCheckLabel(check: LengthCheck): string;
 /**
  * A constraint on an array column's element count, from `CHECK (cardinality(tags) > 0)`.
  *
@@ -351,6 +526,24 @@ interface CardinalityCheck {
     value: string;
     name?: string;
 }
+/**
+ * A test of whether a column holds NULL, from `CHECK (col IS NOT NULL)`.
+ *
+ * Not a comparison: SQL's comparison operators all yield NULL against a NULL operand, and these
+ * two are the operators that answer TRUE or FALSE instead. That is why they are a kind of their
+ * own rather than another `operator` on `ColumnCheck`, whose whole placement rule is that a check
+ * sits *inside* the nullable wrapper because NULL never reaches it.
+ *
+ * `notNull` is the only direction any emitted schema states, and it states it by not being
+ * nullable rather than by carrying a predicate. `IS NULL` is carried so the constraint can be
+ * reported precisely rather than as "not understood", and is enforced nowhere.
+ */
+interface NullCheck {
+    column: string;
+    /** `true` for `IS NOT NULL`, `false` for `IS NULL`. */
+    notNull: boolean;
+    name?: string;
+}
 /** A check that was understood, or the reason it was not. */
 type ParsedCheck = {
     ok: true;
@@ -359,6 +552,7 @@ type ParsedCheck = {
     rows?: RowCheck[];
     lengths?: LengthCheck[];
     cardinalities?: CardinalityCheck[];
+    nulls?: NullCheck[];
 } | {
     ok: false;
     reason: string;
@@ -369,8 +563,36 @@ type ParsedCheck = {
  * Deliberately narrow. `BETWEEN` is included because it is common and means exactly two
  * inclusive bounds; `AND` of arbitrary predicates is not, because getting its scope wrong would
  * silently change what is enforced.
+ *
+ * **The order below is load bearing, in both directions.** `BETWEEN` is matched before the `AND`
+ * split because it *holds* an `AND`; splitting first turned every `BETWEEN` into an unparseable
+ * pair and dropped a constraint that had been enforced. The unary `IS` predicates are matched
+ * *after* the splits for the mirror-image reason: none of them holds an `AND` or an `OR`, and
+ * their trailing operand is greedy, so matching first would let `a IS DISTINCT FROM 5 AND b > 0`
+ * swallow the second predicate. `OR` is split before `AND` because SQL binds `AND` tighter, and
+ * no SQL operator spells an `OR` inside itself the way `BETWEEN` spells an `AND`.
  */
 declare function parseCheck(expression: string | undefined, name?: string): ParsedCheck;
+/**
+ * A number-kind literal, spelled for the wire type of the column it constrains.
+ *
+ * `CHECK (big IN (1, 2))` on a `bigint({ mode: 'bigint' })` column pins a set of *bigints*: the
+ * driver returns `1n` there, and `1n === 1` is false in JavaScript, so a number literal in the
+ * emitted schema rejects every row the database returns. The literal has to be spelled `1n` on
+ * that wire, and stay `1` where a number really arrives, which is what `bigint({ mode: 'number' })`
+ * does. The wire type is `tsType`, which the analyzer sets per mode from what the driver hands
+ * back (see the `PgBigInt53`/`PgBigInt64` arms and `test/decimal-modes.spec.ts` in the analyzer),
+ * so the decision keys on the value's real type rather than on the SQL type name.
+ *
+ * The integer test is load bearing rather than defensive: `1.5n` is a syntax error, so an emitted
+ * module carrying it throws at import. A non-integer literal also has nothing to gain from the
+ * suffix, because no stored bigint ever equals 1.5; it keeps its number spelling, which no bigint
+ * satisfies either, so the schema and the database agree about every value on the wire while the
+ * module keeps parsing.
+ */
+declare function wireNumberLiteral(column: {
+    tsType?: string;
+}, value: string): string;
 /**
  * A human-readable rendering of a set constraint, for an error message.
  *
@@ -378,6 +600,343 @@ declare function parseCheck(expression: string | undefined, name?: string): Pars
  * schema rather than like its JavaScript translation.
  */
 declare function describeSet(set: ColumnSet): string;
+/**
+ * How the database compares a CHECK literal against this column, and so how an emitted schema
+ * must state the comparison. `wireNumberLiteral` above decides a literal's *spelling*; this
+ * decides which comparison that spelling takes part in, which is the other half of the same
+ * rule: the literal's kind and the column's wire are reconciled by the database's semantics,
+ * never by whether the schema happened to quote the literal.
+ *
+ *   `number`          the driver hands back a JS number; literals compare with `===`/ranges.
+ *   `bigint`          a JS bigint; same, spelled with the `n` suffix.
+ *   `numeric-string`  the driver hands back *decimal text* and the database compares it as a
+ *                     number: `numeric`/`decimal` in string mode on every dialect, and v1's
+ *                     `bigint({ mode: 'string' })`. Measured on PostgreSQL 17.5 and MySQL
+ *                     8.4.11: `1 = 1.00` is true and a `numeric(10,2)` returns '1.00' for a
+ *                     stored 1, so neither a number literal nor the literal's own text can be
+ *                     compared to what arrives; only a canonical decimal spelling can.
+ *   `text`            ordinary strings, compared as strings.
+ *   `opaque`          everything else: dates, booleans, arrays, shaped columns. No literal
+ *                     policy applies and the existing arms keep their behaviour.
+ *
+ * Keyed on `tsType` plus `dbType` rather than on the SQL type name, for the reason
+ * `wireNumberLiteral` records: `tsType` is the analyzer's measured wire, and `dbType` is the
+ * coarse kind label both majors agree on (`NUMERIC` for every decimal family, `BIGINT` for the
+ * one string-mode integer wire).
+ */
+type ComparisonWire = 'number' | 'bigint' | 'numeric-string' | 'text' | 'opaque';
+declare function comparisonWire(c: {
+    tsType?: string;
+    dbType?: string;
+    shape?: {
+        kind: string;
+    };
+    arrayDimensions?: number;
+}): ComparisonWire;
+/**
+ * The canonical spelling of plain decimal text, or nothing for anything else.
+ *
+ * The one name under which '1', '1.00', '01', '+1', '1.' and ' 1 ' are the same value, which is
+ * exactly the equality the database applies on a numeric wire: measured through PGlite, a bare
+ * `numeric` returns '1.000000' for an inserted 1.000000 and admits it into `CHECK (n IN (1, 2))`,
+ * and a `numeric(10,2)` returns '1.00' for a stored 1. Sign is normalised (`numeric` has no
+ * negative zero: '-0.00' comes back '0.00'), leading integer zeros and trailing fraction zeros
+ * are stripped, and a bare trailing dot is dropped.
+ *
+ * String arithmetic deliberately: `Number()` is not usable here. A numeric column carries more
+ * digits than a double holds, and Number('99999999999999999999') and
+ * Number('99999999999999999998') are the same double, so rounding through one would merge
+ * members the database keeps distinct.
+ *
+ * Everything outside plain decimal answers nothing, exponent forms included. Postgres does
+ * accept `'1e3'` as numeric *input*, and `CHECK (n IN ('1e3', 2))` is valid DDL that admits
+ * 1000, but its output spelling is always plain ('1000' came back, measured), and a member this
+ * function cannot name makes the whole constraint unenforceable rather than approximated: see
+ * `wireLiteralFit`.
+ */
+declare function canonicalNumericText(text: string): string | undefined;
+/** The canonical forms of a member list, deduplicated, members outside the domain dropped. */
+declare function canonicalMembers(values: string[]): string[];
+/** Name of the canonical helper emitted into a module that compares on a numeric string wire. */
+declare const NUMERIC_CANON_NAME = "DrzlNumericCanon";
+/**
+ * The helper itself, emitted once per file that needs it, in every generator from this one
+ * string so six copies cannot drift. `test/numeric-wire-literals.spec.ts` evaluates it beside
+ * `canonicalNumericText` over the probe corpus to hold the two to one answer.
+ */
+declare const NUMERIC_CANON_SOURCE = "/**\n * The canonical spelling of the plain decimal text a numeric wire carries, or null for anything\n * else. The driver spells one value many ways by declared scale ('1', '1.00', '1.0000000000',\n * measured) and the database compares them as numbers, so equality is decided on this form:\n * sign normalised, leading integer zeros and trailing fraction zeros stripped, a bare trailing\n * dot dropped. String arithmetic on purpose: Number() is not usable here, because a numeric\n * column carries more digits than a double holds and rounding would merge values the database\n * keeps distinct.\n */\nconst DrzlNumericCanon = (s: string): string | null => {\n  const m = /^([+-]?)(\\d*)(?:\\.(\\d*))?$/.exec(s.trim());\n  if (!m || (!m[2] && !m[3])) return null;\n  const int = (m[2] ?? '').replace(/^0+/, '');\n  const frac = (m[3] ?? '').replace(/0+$/, '');\n  if (!int && !frac) return '0';\n  return (m[1] === '-' ? '-' : '') + (int || '0') + (frac ? '.' + frac : '');\n};\n";
+/** What `wireLiteralFit` is asked about: one literal list, one comparison class. */
+interface WireLiteralQuestion {
+    kind: 'number' | 'string';
+    values: string[];
+    /** `=`, `<>` and `IN` are `equality`; the four ordering operators are `range`. */
+    comparison: 'equality' | 'range';
+}
+/**
+ * Whether these literals can be enforced against this column, and in what form.
+ *
+ *   `keep`        the spelling already follows the wire: nothing changes.
+ *   `respell`     quoted plain decimal on a number or bigint wire. The database coerces the
+ *                 text and compares numerically (`bigint CHECK (big IN ('1','2'))` admitted 1
+ *                 and refused 3, measured), so the literal becomes its canonical number-kind
+ *                 self and every existing number arm applies. Canonical rather than verbatim,
+ *                 because `018` and `018n` are syntax errors in an emitted module.
+ *   `canonical`   any equality on a numeric string wire: the emitted schema compares canonical
+ *                 decimal spellings through `NUMERIC_CANON_NAME`. A range there is `respell`:
+ *                 it is emitted as a coerced numeric compare instead, since ordering needs no
+ *                 exact spelling, only a monotonic one.
+ *   `unenforced`  no exact statement exists. Three shapes land here, each measured: a number
+ *                 literal against a text column (Postgres refuses the DDL outright, MySQL
+ *                 compares through double coercion that admits '1.00' and '2.0'), quoted text
+ *                 that is not plain decimal on a number or bigint wire, and a member outside
+ *                 the canonical domain on a numeric string wire (`'1e3'` is valid DDL whose
+ *                 rows come back '1000'). Enforcing a guess would reject rows the database
+ *                 admits, which is the defect class this policy exists to remove, so these are
+ *                 left to the base schema and reported.
+ */
+type WireLiteralFit = {
+    fit: 'keep';
+} | {
+    fit: 'respell';
+    values: string[];
+} | {
+    fit: 'canonical';
+    canon: string[];
+} | {
+    fit: 'unenforced';
+    reason: string;
+};
+declare function wireLiteralFit(c: {
+    name?: string;
+    tsType?: string;
+    dbType?: string;
+    shape?: {
+        kind: string;
+    };
+    arrayDimensions?: number;
+}, q: WireLiteralQuestion): WireLiteralFit;
+/** A clause the wire policy left unenforced, with the reason the ledger reports. */
+interface UnenforcedLiteral {
+    column: string;
+    reason: string;
+    check?: ColumnCheck;
+    set?: ColumnSet;
+}
+/**
+ * The wire policy over a whole table's parsed checks, for the generators.
+ *
+ * Respelled literals come back as the number-kind twins every existing arm already handles,
+ * unenforceable clauses are dropped from the lists and returned beside them, and the
+ * numeric-string clauses pass through untouched for the canonical vehicles to state. The
+ * constraint ledger applies `wireLiteralFit` itself so its texts and reasons cannot drift from
+ * what is emitted here.
+ */
+declare function applyWirePolicy(columns: Array<{
+    name: string;
+    tsType?: string;
+    dbType?: string;
+    shape?: {
+        kind: string;
+    };
+    arrayDimensions?: number;
+}>, checks: ColumnCheck[], sets: ColumnSet[]): {
+    checks: ColumnCheck[];
+    sets: ColumnSet[];
+    unenforced: UnenforcedLiteral[];
+};
+/**
+ * Whether any column of this table needs `NUMERIC_CANON_SOURCE` emitted beside it.
+ *
+ * One condition shared by every generator's preamble and its field emitter, for the reason the
+ * TypeBox generator records on `tbNeedsCapKind`: two copies of one condition drift, and what a
+ * drifted copy emits is a reference to a helper the file never defined.
+ */
+declare function needsNumericCanon(columns: Array<{
+    name: string;
+    tsType?: string;
+    dbType?: string;
+    shape?: {
+        kind: string;
+    };
+    arrayDimensions?: number;
+}>, checks: ColumnCheck[], sets: ColumnSet[]): boolean;
+
+/**
+ * Every constraint on a table, as data a consumer can read without holding a validator.
+ *
+ * `meta` already carries most of these facts, and this is deliberately not a second copy of it.
+ * Three differences, each of which is why both exist.
+ *
+ *   **shape**       `meta` renders a CHECK as prose: `"age_adult: age >= 18"`. That is the right
+ *                   form for its destination, which is `z.toJSONSchema` and then an OpenAPI
+ *                   viewer, and the wrong form for a form builder, which wants the bound as a
+ *                   number and would otherwise have to parse SQL back out of a sentence. Here the
+ *                   operand is data and the sentence is beside it.
+ *
+ *   **content**     `meta` has no foreign keys at all, and its `unique` is a list of column groups
+ *                   with the constraint names dropped. A form cannot render a picker without the
+ *                   first, and, more sharply, nothing can be mapped back to a constraint that has
+ *                   no name, which is what makes the second load bearing rather than cosmetic.
+ *
+ *   **addressing**  `meta` is reachable only by holding the emitted schema object and asking each
+ *                   field, per mode. This is a plain record keyed by table, so the answer to "what
+ *                   constrains this table" costs one property read and no validator import.
+ *
+ * What is *not* here is anything `meta` states about a column rather than a constraint: the SQL
+ * type, whether the database defaults the value, the numeric range of the column's own type. Those
+ * are facts about a field, `meta` carries them, and restating them here would be exactly the
+ * duplication the paragraph above is arguing against.
+ *
+ * Both halves are built from `classifyTableChecks` below, which `meta` also uses, so the two can
+ * disagree about what is enforced only by both being wrong at once.
+ */
+
+/** Where one part of a parsed CHECK lands. */
+type CheckPartPlace = 'column' | 'row' | 'none';
+/**
+ * One clause of one CHECK, classified by what the generated schemas do with it.
+ *
+ * A single `CHECK` declaration can split into several of these: `BETWEEN` is two bounds, and a
+ * conjunction is one part per operand. They are kept apart here because enforcement is decided
+ * per clause, and rejoined into one constraint by `tableConstraints`, because a database has one
+ * constraint there and quotes one name back.
+ */
+interface CheckPart {
+    /** The clause as text. Also the message the emitted schema attaches, when it attaches one. */
+    text: string;
+    /** The columns the clause is about, in the order the expression names them. */
+    columns: string[];
+    place: CheckPartPlace;
+    /** Why nothing enforces it, when nothing does. */
+    reason?: string;
+    /** Present when the clause was folded into the column's range instead of a predicate. */
+    bound?: {
+        column: string;
+        operator: ColumnCheck['operator'];
+        value: string;
+    };
+    /** Present when the clause was folded into a set of literals instead of a predicate. */
+    set?: {
+        column: string;
+        values: string[];
+        kind: 'number' | 'string';
+    };
+    /**
+     * Present when the clause is enforced by the field's shape rather than by a predicate.
+     *
+     * The third fold, after a bound and a set, and the one that leaves *nothing* to match on:
+     * `CHECK (col IS NOT NULL)` is enforced by the field not being nullable, and the failure it
+     * produces is the library's own "expected string, received null". Marked so `tableConstraints`
+     * does not offer the clause text as a message, which would have the error map keying on a
+     * string no emitted module writes.
+     */
+    shape?: 'notNull';
+}
+/** One declared CHECK, with each of its clauses placed. */
+interface ClassifiedCheck {
+    name?: string;
+    /** The expression as declared, trimmed. */
+    expression: string;
+    parts: CheckPart[];
+}
+/**
+ * Every CHECK on a table, split into clauses and placed.
+ *
+ * The single reading of `parseCheck` plus the shape guards, shared by `meta` and by the constraint
+ * ledger so that "the database also checks this and we do not" is one answer rather than two.
+ */
+declare function classifyTableChecks(table: Table$1): ClassifiedCheck[];
+/** What a constraint is. */
+type ConstraintKind = 'primaryKey' | 'unique' | 'foreignKey' | 'check' | 'maxLength' | 'maxBytes';
+/** One clause of a constraint that nothing in the generated schemas checks. */
+interface UnenforcedPart {
+    part: string;
+    reason: string;
+}
+/** One constraint on one table. */
+interface ConstraintFacts {
+    /**
+     * Stable identifier, unique within the table.
+     *
+     * The SQL constraint name where the declaration has one, and a derived name where it does not.
+     * This is what an error map keys on and what a caller stores against its own copy for a
+     * message, so it has to exist even for the constraints SQL leaves anonymous.
+     */
+    id: string;
+    /** The SQL constraint name, absent where the declaration did not give one. */
+    name?: string;
+    kind: ConstraintKind;
+    /** The columns the constraint is about, in declaration order. */
+    columns: string[];
+    /** The rule as a sentence, for a form with nothing better to show. */
+    rule: string;
+    /** Whether a generated schema can reject a row for this constraint. */
+    enforced: boolean;
+    /** The clauses nothing enforces, and why. Absent when there are none. */
+    unenforced?: UnenforcedPart[];
+    /**
+     * The exact messages a generated schema attaches for this constraint.
+     *
+     * Absent where the schema states the constraint in the validator's own vocabulary instead, which
+     * is where the constraint name is lost and the error map has to key on something else.
+     */
+    messages?: string[];
+    /** Bounds folded into a column's range. What a bound-carrying issue is matched against. */
+    bounds?: {
+        column: string;
+        operator: string;
+        value: string;
+    }[];
+    /** A set of literals folded into an enum. */
+    values?: {
+        column: string;
+        values: string[];
+        kind: 'number' | 'string';
+    };
+    /** Where a foreign key points. */
+    references?: {
+        table: string;
+        schema?: string;
+        columns: string[];
+        onDelete?: string;
+        onUpdate?: string;
+    };
+}
+/** Every constraint on one table. */
+interface TableConstraints {
+    /** The SQL table name, which is not the Drizzle export name. */
+    table: string;
+    /** The SQL schema, present only when the table names one. */
+    schema?: string;
+    constraints: ConstraintFacts[];
+}
+/** Every constraint on a table, as data. */
+declare function tableConstraints(table: Table$1): TableConstraints;
+interface ConstraintsModuleOptions {
+    /** Also emit `constraintForIssue`, which is the half that maps a failure back. */
+    errorMap?: boolean;
+}
+/** What `constraints` is asking for, once the boolean shorthand is expanded. */
+type ConstraintsOption = boolean | {
+    enabled?: boolean;
+    errorMap?: boolean;
+};
+declare function resolveConstraints(opt: ConstraintsOption | undefined): ConstraintsModuleOptions | undefined;
+/** The file every generator writes the ledger to. Fixed, like the barrel's own name. */
+declare const CONSTRAINTS_MODULE = "constraints.ts";
+/**
+ * The `constraints.ts` module, as source.
+ *
+ * Plain objects and, optionally, one function. Nothing here imports a validator or any part of
+ * DRZL, so a consumer can read the ledger from a script, a form builder or a server route without
+ * pulling a schema in. The matcher is a separate export for the same reason a separate option
+ * turns it off: a consumer who only renders forms should not carry the code that maps failures.
+ *
+ * `JSON.stringify` rather than a hand-rolled literal, because every string here comes from a
+ * schema the user wrote: a table named `it's` or a CHECK holding a quote has to survive into valid
+ * TypeScript. The formatter unquotes the keys that do not need quoting.
+ */
+declare function renderConstraintsModule(tables: Table$1[], opts?: ConstraintsModuleOptions): string;
 
 /**
  * The facts a generated schema can carry beside itself.
@@ -647,7 +1206,7 @@ declare function nestedNodeColumns<T extends {
  */
 
 /**
- * `findDuplicate<Table>s` for a table with unique constraints, or nothing.
+ * `findDuplicate<Table>s` for a table with a primary key or unique constraints, or nothing.
  *
  * `rowType` is the name of the insert type, which is what a caller has in hand before an insert.
  * Passed in rather than derived, because each generator names its types differently.
@@ -661,6 +1220,16 @@ interface Table {
     primaryKey?: {
         columns: string[];
     };
+    /**
+     * The declared CHECK constraints, because one of them decides whether a column is nullable.
+     *
+     * Structurally the analyzer's `Check[]`, and here rather than only there because the three
+     * column selectors below have to read it and this is the shape they are declared against.
+     */
+    checks?: {
+        name?: string;
+        expression?: string;
+    }[];
 }
 type ValidationLibrary = 'zod' | 'valibot' | 'arktype' | 'typebox' | 'effect';
 interface FormatOptions {
@@ -796,6 +1365,15 @@ interface ValidationGenerateOptions {
         insert?: boolean;
         update?: boolean;
     };
+    /**
+     * Where the generated files go, when that is not the filesystem.
+     *
+     * Omitted, they go to disk exactly as before. Passed, every write and every `mkdir` is handed to
+     * the sink instead, which is what `drzl generate --dry-run` and `drzl generate --check` are
+     * built on: both need the content a run would produce without the run producing it. See
+     * `emit.ts` for why this is an option rather than an interception of `node:fs/promises`.
+     */
+    fileSink?: FileSink;
 }
 interface ValidationRenderer<TOptions extends ValidationGenerateOptions = ValidationGenerateOptions> {
     readonly library: ValidationLibrary;
@@ -841,7 +1419,7 @@ declare function isGeneratedColumn(c: Column, _primaryKeyColumns?: string[]): bo
  * the real hazard is over-rejection. A check that turns away something Postgres accepts breaks
  * working code, which is worse than the bare `string` it replaces.
  *
- * That is why there is exactly one entry. Candidates for `date`, `timestamp`, `time`, `interval`,
+ * The list is short for that reason. Candidates for `date`, `timestamp`, `time`, `interval`,
  * `inet`, `cidr` and `macaddr` were all built and all rejected, each by a value Postgres accepts
  * and the pattern did not:
  *
@@ -850,6 +1428,11 @@ declare function isGeneratedColumn(c: Column, _primaryKeyColumns?: string[]): bo
  *   macaddr   `2020-01-01`, which Postgres pads into `20:20:00:01:00:01`
  *   inet      `10.1/16`, `::ffff:1.2.3.4`
  *   cidr      parses as `inet` and then demands zero host bits, which no regex can state
+ *
+ * **One key per dialect where the servers disagree.** `numeric` is Postgres's alone, and the
+ * analyzer withholds it from SQLite for that reason. The two `bigint` entries are the case where
+ * withholding is not enough, because both dialects have a real answer and the answers contradict
+ * each other in both directions. See them below.
  */
 declare const COLUMN_FORMATS: Record<string, string>;
 /**
@@ -987,6 +1570,34 @@ declare function nonFiniteAccepted(c: Column): {
     nan: boolean;
     infinity: boolean;
 };
+/**
+ * The non-finite doubles the emitted schema must *refuse*, as the analyzer stated them.
+ *
+ * The other reading of the same two flags, and not the negation of `nonFiniteAccepted`. Three
+ * states, because a column that was measured and refused the value is a different thing from a
+ * column nobody measured: `true` is stored and returned, `false` is offered and refused, absent is
+ * unstated. `nonFiniteAccepted` reads `=== true` and this reads `=== false`, so an unstated column
+ * answers no to both and every generator leaves it exactly as its library renders it.
+ *
+ * The distinction is load-bearing rather than tidy. MySQL and SQLite both leave a `real` unbounded,
+ * and MySQL answers `ER_WARN_DATA_OUT_OF_RANGE` for an infinity where SQLite stores it and hands it
+ * back. Reading "not accepted" as "refuse it" would have made one schema right and the other wrong
+ * from the same reading, and the SQLite half is filed separately because that engine also turns
+ * `NaN` into NULL and a column needs both halves of that answer or none.
+ *
+ * Guarded on `tsType` exactly as its sibling is, so a stale analysis carrying the flags on a string
+ * or a shaped column cannot put a numeric predicate beside a `z.string()`.
+ *
+ * What each generator does with a yes is its own: `z.number()` and `Type.Number()` already refuse
+ * every non-finite number with no bound at all, measured, so they emit nothing and read this only
+ * through the tests that pin that. `v.number()` and ArkType's `number` take both infinities, so
+ * those two add a finite predicate wherever no bound already holds one back. Effect builds on
+ * `Schema.Finite` unconditionally and needs nothing either.
+ */
+declare function nonFiniteRefused(c: Column): {
+    nan: boolean;
+    infinity: boolean;
+};
 declare function insertColumns(table: Table): Column[];
 /**
  * Which columns belong in an update schema.
@@ -1003,6 +1614,33 @@ declare function insertColumns(table: Table): Column[];
  */
 declare function updateColumns(table: Table): Column[];
 declare function selectColumns(table: Table): Column[];
+/**
+ * Whether a resolved manifest path belongs to a project's installed dependencies.
+ *
+ * Resolving a package is normally the same question as having it installed, and on Node and Deno
+ * it is: their resolvers walk `node_modules` and answer a missing package with MODULE_NOT_FOUND.
+ * Bun's does not. When nothing is found it auto-installs the package from npm and resolves into
+ * its own global cache, so `require.resolve('@biomejs/biome/package.json')` succeeds under Bun
+ * against a project whose package.json has never mentioned Biome. Measured under Bun 1.3.14:
+ *
+ *   node   -> MODULE_NOT_FOUND
+ *   deno   -> MODULE_NOT_FOUND
+ *   bun    -> /home/<user>/.bun/install/cache/@biomejs/biome@2.5.7@@@1/package.json
+ *
+ * That made `drzl generate` emit Biome-formatted files under Bun and unformatted files under Node
+ * from the same schema and the same config, so `generate --check` under Node called every file
+ * out of date; and it fetched a package, plus a multi-megabyte native binary, from the network in
+ * the middle of codegen. It was not stable within Bun either, since whether the auto-install fired
+ * depended on the state of a cache outside the project.
+ *
+ * A `node_modules` path segment is the discriminator, and it is exact rather than a heuristic:
+ * npm, pnpm's `.pnpm` store and Yarn PnP's zip and unplugged paths all reach a package through
+ * one, and Bun's auto-install cache is the one shape that does not, because it is not a project
+ * install. Under Node and Deno this can never fire, since their resolvers have no other kind of
+ * path to return, so it costs those runtimes nothing. A Bun project that really does install
+ * Biome resolves through its `node_modules` like everyone else and still formats.
+ */
+declare function isProjectInstallPath(manifestPath: string): boolean;
 /**
  * Pretty-print emitted code with whatever formatter the consumer already has.
  *
@@ -1030,4 +1668,4 @@ declare function selectColumns(table: Table): Column[];
  */
 declare function formatCode(code: string, filePath: string, fmt?: FormatOptions): Promise<any>;
 
-export { AFFIX_PROBE_TABLE, type AffixIssue, type AffixOptions, type AffixValue, type BrandAlias, type BrandPlan, type BrandingOption, type BrandingOptions, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, type CardinalityCheck, type ColumnCheck, type ColumnMetaFacts, type ColumnSet, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_NESTED_DEPTH, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FormatOptions, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, MAX_NESTED_DEPTH, type MetaFactOptions, NAME_MODES, NESTED_PREFIX, type NameMode, type NestedArm, type NestedMode, type NestedNode, type ParsedCheck, type ResolvedAffix, type ResolvedBranding, type RowCheck, type Table, type TableCase, type TableMetaFacts, type TableMetaOptions, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, applyTableCase, buildBrandPlan, buildNestedPlan, columnMetaFacts, describeSet, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, moduleFileName, moduleSpecifier, nestedArmNotes, nestedNodeColumns, nestedSchemaName, nestedTypeName, nonFiniteAccepted, parseCheck, parsesToADate, pascalCase, renderDuplicateFinder, resolveAffix, resolveBranding, resolveConfiguredImport, resolveNestedDepth, schemaName, selectColumns, tableMetaFacts, typeName, updateColumns, validateAffix };
+export { AFFIX_PREFIX_PATTERN, AFFIX_PROBE_TABLE, AFFIX_SUFFIX_PATTERN, type AffixIssue, type AffixOptions, type AffixValue, type BrandAlias, type BrandPlan, type BrandingOption, type BrandingOptions, CODEPOINT_LENGTH, COERCIBLE_DATE_STRING, COLUMN_FORMATS, CONSTRAINTS_MODULE, type CardinalityCheck, type CheckPart, type CheckPartPlace, type ClassifiedCheck, type ColumnCheck, type ColumnMetaFacts, type ColumnSet, type ComparisonWire, type ConstraintFacts, type ConstraintKind, type ConstraintsModuleOptions, type ConstraintsOption, DEFAULT_IMPORT_EXTENSION, DEFAULT_MODE_PREFIX, DEFAULT_NESTED_DEPTH, DEFAULT_SCHEMA_SUFFIX, DEFAULT_TYPE_SUFFIX, type FileSink, type FormatOptions, type GeneratorFs, IMPORT_EXTENSIONS, type ImportExtension, type LengthCheck, type LengthMeasure, MAX_NESTED_DEPTH, type MetaFactOptions, NAME_MODES, NESTED_PREFIX, NUMERIC_CANON_NAME, NUMERIC_CANON_SOURCE, type NameMode, type NestedArm, type NestedMode, type NestedNode, type NullCheck, type ParsedCheck, type ResolvedAffix, type ResolvedBranding, type RowCheck, type Table, type TableCase, type TableConstraints, type TableMetaFacts, type TableMetaOptions, type UnenforcedLiteral, type UnenforcedPart, type ValidationGenerateOptions, type ValidationLibrary, type ValidationRenderer, type WireLiteralFit, type WireLiteralQuestion, applyTableCase, applyWirePolicy, buildBrandPlan, buildNestedPlan, canonicalMembers, canonicalNumericText, classifyTableChecks, columnMetaFacts, comparisonWire, describeSet, fileWriter, formatCode, importSpecifier, insertColumns, isGeneratedColumn, isIntegerColumn, isProjectInstallPath, lengthCheckLabel, lengthMeasure, measureExpression, moduleFileName, moduleSpecifier, needsNumericCanon, nestedArmNotes, nestedNodeColumns, nestedSchemaName, nestedTypeName, nonFiniteAccepted, nonFiniteRefused, parseCheck, parsesToADate, pascalCase, renderConstraintsModule, renderDuplicateFinder, resolveAffix, resolveBranding, resolveConfiguredImport, resolveConstraints, resolveNestedDepth, schemaName, selectColumns, tableConstraints, tableMetaFacts, typeName, updateColumns, validateAffix, wireLiteralFit, wireNumberLiteral };