ng-form-foundry-transformers 0.4.1 → 0.5.1

package/dist/transformers/libconfig/libconfig-transformer.js

@@ -1,38 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.libconfigTransformer = void 0;
-exports.resetLibconfigBetaWarning = resetLibconfigBetaWarning;
 const thesaurus_1 = require("../../core/thesaurus");
 const json_schema_1 = require("../../core/json-schema");
+const merge_inferred_1 = require("../../core/merge-inferred");
+const schema_keys_1 = require("../../core/schema-keys");
 const parser_1 = require("./parser");
 const schema_1 = require("./schema");
 const revert_1 = require("./revert");
-let warnedBeta = false;
-function warnBeta() {
-    if (warnedBeta)
-        return;
-    warnedBeta = true;
-    console.warn('[ng-form-foundry-transformers] The libconfig transformer is a BETA feature. ' +
-        'Verify every write-back (diff toSource output against the original file) before deploying it.');
-}
-/** Test seam: makes the one-time beta warning observable per test. */
-function resetLibconfigBetaWarning() {
-    warnedBeta = false;
-}
 exports.libconfigTransformer = {
     id: 'libconfig',
     toSchema(source, options) {
-        warnBeta();
         const root = (0, parser_1.parseLibconfig)(source, { includes: options?.includes });
-        const schema = options?.schema
+        const unknownKeys = options?.unknownKeys ?? 'preserve';
+        const fromJsonSchema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
-            : (0, schema_1.libconfigToNodeGroup)(root, source, options?.rootName ?? '__root__');
+            : undefined;
+        const schema = fromJsonSchema && unknownKeys === 'edit'
+            ? (0, merge_inferred_1.mergeInferred)(fromJsonSchema, (0, schema_1.libconfigToNodeGroup)(root, source, options?.rootName ?? '__root__'))
+            : fromJsonSchema ?? (0, schema_1.libconfigToNodeGroup)(root, source, options?.rootName ?? '__root__');
         const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
         const initialValue = (0, schema_1.extractValue)(root, source, options?.schema != null);
-        return { schema: labeled, binding: { source, root }, initialValue };
+        if (fromJsonSchema && unknownKeys === 'edit') {
+            // Uncovered empty collections merged as read-only carries: their value
+            // must be the verbatim slice, not the typed [] the extraction produced.
+            (0, schema_1.carryUncoveredEmpties)(root, source, initialValue, (0, schema_keys_1.childrenOf)(fromJsonSchema));
+        }
+        return {
+            schema: labeled,
+            binding: {
+                source,
+                root,
+                // 'preserve' gates the revert on the JSON Schema's NodeGroup; 'edit'
+                // on the merged one (schema-born ≈ everything, but settings no form
+                // field can carry stay protected); 'drop' and inferred mode leave
+                // the value authoritative for the whole document.
+                schema: fromJsonSchema && unknownKeys !== 'drop' ? schema : undefined,
+            },
+            initialValue,
+        };
     },
     toSource(value, binding) {
-        warnBeta();
-        return (0, revert_1.applyValueToSource)(binding.source, binding.root, value);
+        return (0, revert_1.applyValueToSource)(binding.source, binding.root, value, binding.schema);
     },
 };

package/dist/transformers/libconfig/revert.d.ts

@@ -13,6 +13,18 @@
  * literal re-emits in hex at its original digit width, an int64 keeps its
  * `L`/`LL` suffix, and values beyond 2^53 travel as exact decimal strings.
  */
+import type { NodeGroup } from '../../core/schema';
 import type { CfgGroup } from './parser';
-/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
-export declare function applyValueToSource(source: string, root: CfgGroup, value: Record<string, unknown>): string;
+/**
+ * Apply `value` onto the parsed `root` of `source`, returning the new text.
+ *
+ * Without `schema` (inferred mode) the value is authoritative for the whole
+ * document: it was extracted from every setting, so a key it lacks is a
+ * deletion. With `schema` (the NodeGroup the form was built from) the value
+ * is authoritative for **schema-born paths only** — the form never carried
+ * the other settings, so they survive byte-verbatim in their original
+ * positions. A partial schema thus edits its slice of an OAI/srsRAN config
+ * without erasing keys the schema does not enumerate; absence of a
+ * schema-born key still deletes (a presence toggle turned off).
+ */
+export declare function applyValueToSource(source: string, root: CfgGroup, value: Record<string, unknown>, schema?: NodeGroup): string;

package/dist/transformers/libconfig/revert.js

@@ -1,33 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyValueToSource = applyValueToSource;
+const schema_keys_1 = require("../../core/schema-keys");
 const schema_1 = require("./schema");
-/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
-function applyValueToSource(source, root, value) {
+/**
+ * Apply `value` onto the parsed `root` of `source`, returning the new text.
+ *
+ * Without `schema` (inferred mode) the value is authoritative for the whole
+ * document: it was extracted from every setting, so a key it lacks is a
+ * deletion. With `schema` (the NodeGroup the form was built from) the value
+ * is authoritative for **schema-born paths only** — the form never carried
+ * the other settings, so they survive byte-verbatim in their original
+ * positions. A partial schema thus edits its slice of an OAI/srsRAN config
+ * without erasing keys the schema does not enumerate; absence of a
+ * schema-born key still deletes (a presence toggle turned off).
+ */
+function applyValueToSource(source, root, value, schema) {
     const edits = [];
-    patchGroup(source, root, value, edits);
+    patchGroup(source, root, value, edits, schema && (0, schema_keys_1.childrenOf)(schema));
     edits.sort((a, b) => b.start - a.start);
     let out = source;
     for (const e of edits)
         out = out.slice(0, e.start) + e.text + out.slice(e.end);
     return out;
 }
-function patchGroup(src, group, value, edits) {
+function patchGroup(src, group, value, edits, schema) {
     for (const setting of group.settings) {
-        if (!value || !(setting.name in value)) {
+        if (schema && !schema.has(setting.name))
+            continue; // not schema-born: verbatim
+        // Own-key check: `in` would resolve setting names like `toString` through
+        // the prototype chain, making them undeletable (and their "value" a function).
+        if (!value || !Object.prototype.hasOwnProperty.call(value, setting.name)) {
             edits.push(deleteSetting(src, setting));
             continue;
         }
-        patchValue(src, setting.value, value[setting.name], edits);
+        patchValue(src, setting.value, value[setting.name], edits, schema?.get(setting.name));
     }
     const known = new Set(group.settings.map((s) => s.name));
-    // null/undefined means "absent", never a value: such keys are not added.
-    const added = Object.keys(value ?? {}).filter((k) => !known.has(k) && value[k] != null);
+    // null/undefined means "absent", never a value: such keys are not added —
+    // and under a schema, only schema-born keys may be added at all.
+    const added = Object.keys(value ?? {}).filter((k) => !known.has(k) && value[k] != null && (!schema || schema.has(k)));
     if (added.length) {
         edits.push(insertionEdit(src, group, added.map((k) => `${k} = ${serialize(value[k], '')};`)));
     }
 }
-function patchValue(src, node, value, edits) {
+function patchValue(src, node, value, edits, schema) {
     switch (node.kind) {
         case 'scalar': {
             if (node.value === value)
@@ -41,7 +58,7 @@ function patchValue(src, node, value, edits) {
         }
         case 'group': {
             if (isRecord(value))
-                return patchGroup(src, node, value, edits);
+                return patchGroup(src, node, value, edits, schema && (0, schema_keys_1.childrenOf)(schema));
             edits.push({ ...node.span, text: serialize(value, '') }); // shape change: regenerate
             return;
         }
@@ -61,7 +78,7 @@ function patchValue(src, node, value, edits) {
         case 'list': {
             const shape = (0, schema_1.listShape)(node);
             if (shape === 'groups' && Array.isArray(value)) {
-                return patchElements(src, node.elements, node, value, edits);
+                return patchElements(src, node.elements, node, value, edits, (0, schema_keys_1.itemSchemaOf)(schema));
             }
             if (shape === 'scalars' && Array.isArray(value)) {
                 return patchElements(src, node.elements, node, value, edits);
@@ -89,10 +106,10 @@ function patchValue(src, node, value, edits) {
     }
 }
 /** Element-wise patch of an array/list: edit in place, then grow or shrink. */
-function patchElements(src, elements, collection, value, edits) {
+function patchElements(src, elements, collection, value, edits, itemSchema) {
     const shared = Math.min(elements.length, value.length);
     for (let i = 0; i < shared; i++)
-        patchValue(src, elements[i], value[i], edits);
+        patchValue(src, elements[i], value[i], edits, itemSchema);
     if (value.length > elements.length) {
         const items = value.slice(elements.length).map((v) => serialize(v, ''));
         const at = elements.length ? elements[elements.length - 1].span.end : collection.innerSpan.start;

package/dist/transformers/libconfig/schema.d.ts

@@ -19,6 +19,7 @@
  *   empty collections editable.
  */
 import type { NodeGroup } from '../../core/schema';
+import { type SchemaKeys } from '../../core/schema-keys';
 import { type CfgGroup, type CfgList, type CfgValue } from './parser';
 /** Infer the root NodeGroup for a parsed document. */
 export declare function libconfigToNodeGroup(root: CfgGroup, source: string, name: string): NodeGroup;
@@ -36,4 +37,14 @@ type ListShape = 'groups' | 'scalars' | 'empty' | 'heterogeneous';
 export declare function listShape(list: CfgList): ListShape;
 /** The verbatim source slice of a node. */
 export declare function raw(value: CfgValue, source: string): string;
+/**
+ * `unknownKeys: 'edit'` extraction fixup. The whole-document extraction runs
+ * with `emptyAsArrays` (schema-covered empty collections are typed and
+ * editable), but collections the JSON Schema does **not** cover merge as
+ * read-only raw-carry leaves — their value must be the verbatim source
+ * slice, not `[]`. Walks the document alongside the original (pre-merge)
+ * schema coverage and restores the carry on every uncovered empty
+ * collection, at any depth.
+ */
+export declare function carryUncoveredEmpties(group: CfgGroup, source: string, value: unknown, keys: SchemaKeys): void;
 export {};

package/dist/transformers/libconfig/schema.js

@@ -4,6 +4,8 @@ exports.libconfigToNodeGroup = libconfigToNodeGroup;
 exports.extractValue = extractValue;
 exports.listShape = listShape;
 exports.raw = raw;
+exports.carryUncoveredEmpties = carryUncoveredEmpties;
+const schema_keys_1 = require("../../core/schema-keys");
 const parser_1 = require("./parser");
 /** Digits only — the constraint for int64 values carried as strings. */
 const INTEGER_STRING_PATTERN = '^[-+]?[0-9]+$';
@@ -80,14 +82,21 @@ function scalarLeaf(name, scalar) {
         case 'float':
             return { kind: 'leaf', name, type: 'number' };
         case 'int':
-            return { kind: 'leaf', name, type: 'number', integer: true };
+            return withRadix({ kind: 'leaf', name, type: 'number', integer: true }, scalar);
         case 'int64':
             // Beyond 2^53 the value rides as an exact decimal string.
             return typeof scalar.value === 'string'
-                ? { kind: 'leaf', name, type: 'string', pattern: INTEGER_STRING_PATTERN }
-                : { kind: 'leaf', name, type: 'number', integer: true };
+                ? withRadix({ kind: 'leaf', name, type: 'string', pattern: INTEGER_STRING_PATTERN }, scalar)
+                : withRadix({ kind: 'leaf', name, type: 'number', integer: true }, scalar);
     }
 }
+/** Carry a non-decimal literal's base onto the leaf as its display radix. */
+function withRadix(leaf, scalar) {
+    const radix = scalar.int?.radix;
+    if (radix && radix !== 10)
+        leaf.radix = radix;
+    return leaf;
+}
 /**
  * A homogeneous scalar collection → leafList. One int64 element beyond 2^53
  * degrades the whole list to string carry: a leafList holds one scalar type,
@@ -97,10 +106,23 @@ function listLeaf(name, elements) {
     if (elements.length === 0)
         return rawLeaf(name, 'empty collection');
     const f = (0, parser_1.family)(elements[0].type);
+    const radix = f === 'integer' ? sharedRadix(elements) : undefined;
     if (f === 'integer' && elements.some((e) => typeof e.value === 'string')) {
-        return { kind: 'leafList', name, type: 'string' };
+        return { kind: 'leafList', name, type: 'string', ...(radix && { radix }) };
     }
-    return { kind: 'leafList', name, type: f === 'integer' || f === 'float' ? 'number' : f === 'bool' ? 'boolean' : 'string' };
+    return {
+        kind: 'leafList',
+        name,
+        type: f === 'integer' || f === 'float' ? 'number' : f === 'bool' ? 'boolean' : 'string',
+        ...(radix && { radix }),
+    };
+}
+/** The display radix shared by every element, when uniform and non-decimal. */
+function sharedRadix(elements) {
+    const first = elements[0]?.int?.radix ?? 10;
+    if (first === 10)
+        return undefined;
+    return elements.every((e) => (e.int?.radix ?? 10) === first) ? first : undefined;
 }
 function arrayValue(elements) {
     const stringCarry = elements.length > 0 &&
@@ -164,3 +186,61 @@ function rawLeaf(name, why) {
 function raw(value, source) {
     return source.slice(value.span.start, value.span.end);
 }
+/**
+ * `unknownKeys: 'edit'` extraction fixup. The whole-document extraction runs
+ * with `emptyAsArrays` (schema-covered empty collections are typed and
+ * editable), but collections the JSON Schema does **not** cover merge as
+ * read-only raw-carry leaves — their value must be the verbatim source
+ * slice, not `[]`. Walks the document alongside the original (pre-merge)
+ * schema coverage and restores the carry on every uncovered empty
+ * collection, at any depth.
+ */
+function carryUncoveredEmpties(group, source, value, keys) {
+    if (!isRecord(value))
+        return;
+    for (const setting of group.settings) {
+        if (keys && !keys.has(setting.name)) {
+            restoreEmptyCarries(setting.value, source, value, setting.name);
+            continue;
+        }
+        const child = keys?.get(setting.name);
+        const v = value[setting.name];
+        if (setting.value.kind === 'group' && child) {
+            carryUncoveredEmpties(setting.value, source, v, (0, schema_keys_1.childrenOf)(child));
+        }
+        else if (setting.value.kind === 'list' && Array.isArray(v)) {
+            const itemSchema = (0, schema_keys_1.itemSchemaOf)(child);
+            if (!itemSchema)
+                continue;
+            const itemKeys = (0, schema_keys_1.childrenOf)(itemSchema);
+            setting.value.elements.forEach((el, i) => {
+                if (el.kind === 'group')
+                    carryUncoveredEmpties(el, source, v[i], itemKeys);
+            });
+        }
+    }
+}
+/** In a fully uncovered subtree, every empty collection reverts to its carry. */
+function restoreEmptyCarries(node, source, parent, key) {
+    if ((node.kind === 'array' || node.kind === 'list') && node.elements.length === 0) {
+        parent[key] = raw(node, source);
+        return;
+    }
+    if (node.kind === 'group') {
+        const v = parent[key];
+        if (!isRecord(v))
+            return;
+        for (const s of node.settings)
+            restoreEmptyCarries(s.value, source, v, s.name);
+        return;
+    }
+    if (node.kind === 'list') {
+        const v = parent[key];
+        if (!Array.isArray(v))
+            return;
+        node.elements.forEach((el, i) => restoreEmptyCarries(el, source, v, i));
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/transformers/yaml/index.d.ts

@@ -7,5 +7,5 @@
  * `core` — they are format-agnostic and shared with the JSON transformer.
  */
 export { yamlTransformer } from './yaml-transformer';
-export type { YamlOptions } from './yaml-transformer';
+export type { YamlOptions, YamlBinding } from './yaml-transformer';
 export { applyValueToDocument } from './revert';

package/dist/transformers/yaml/revert.d.ts

@@ -1,4 +1,5 @@
 import { type Document } from 'yaml';
+import type { NodeGroup } from '../../core/schema';
 /**
  * Apply an edited form value onto a parsed YAML {@link Document} in place,
  * preserving comments and formatting on every node that survives the edit.
@@ -10,9 +11,15 @@ import { type Document } from 'yaml';
  * {@link import('./json-schema')}. Callers should clone the document first if the
  * original must be preserved.
  *
+ * With `schema` (the NodeGroup the form was built from) the
+ * value is authoritative for **schema-born paths only**: keys the schema does
+ * not cover — at any depth — are preserved verbatim, their comments included.
+ * Without it the value covers the whole document and a key it lacks is a
+ * deletion.
+ *
  * Map keys are matched by the *same string form* `doc.toJS()` produced when the
  * form value was built, so non-string keys (a `80:` port map, a `true:` flag)
  * reconcile against their original typed key nodes instead of being appended as
  * duplicate string-keyed pairs.
  */
-export declare function applyValueToDocument(doc: Document, value: unknown): void;
+export declare function applyValueToDocument(doc: Document, value: unknown, schema?: NodeGroup): void;

package/dist/transformers/yaml/revert.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyValueToDocument = applyValueToDocument;
 const yaml_1 = require("yaml");
 const bigint_1 = require("../../core/bigint");
+const schema_keys_1 = require("../../core/schema-keys");
 /**
  * Apply an edited form value onto a parsed YAML {@link Document} in place,
  * preserving comments and formatting on every node that survives the edit.
@@ -14,17 +15,23 @@ const bigint_1 = require("../../core/bigint");
  * {@link import('./json-schema')}. Callers should clone the document first if the
  * original must be preserved.
  *
+ * With `schema` (the NodeGroup the form was built from) the
+ * value is authoritative for **schema-born paths only**: keys the schema does
+ * not cover — at any depth — are preserved verbatim, their comments included.
+ * Without it the value covers the whole document and a key it lacks is a
+ * deletion.
+ *
  * Map keys are matched by the *same string form* `doc.toJS()` produced when the
  * form value was built, so non-string keys (a `80:` port map, a `true:` flag)
  * reconcile against their original typed key nodes instead of being appended as
  * duplicate string-keyed pairs.
  */
-function applyValueToDocument(doc, value) {
+function applyValueToDocument(doc, value, schema) {
     if (doc.contents == null) {
         doc.contents = doc.createNode(value);
         return;
     }
-    doc.contents = applyToNode(doc, doc.contents, value);
+    doc.contents = applyToNode(doc, doc.contents, value, schema);
 }
 /**
  * Reconcile the parsed `node` at one position with its edited `value`, returning
@@ -32,22 +39,27 @@ function applyValueToDocument(doc, value) {
  * a map/sequence is reconciled child-by-child; a shape change (or a brand-new
  * position) allocates a fresh node.
  */
-function applyToNode(doc, node, value) {
+function applyToNode(doc, node, value, schema) {
     if (isPlainObject(value)) {
         if (!(0, yaml_1.isMap)(node))
             return doc.createNode(value);
-        reconcileMap(doc, node, value);
+        reconcileMap(doc, node, value, schema && (0, schema_keys_1.childrenOf)(schema));
         return node;
     }
     if (Array.isArray(value)) {
         if (!(0, yaml_1.isSeq)(node))
             return doc.createNode(value);
-        reconcileSeq(doc, node, value);
+        reconcileSeq(doc, node, value, (0, schema_keys_1.itemSchemaOf)(schema));
         return node;
     }
     // scalar (string / number / boolean / null)
     if ((0, yaml_1.isScalar)(node)) {
-        node.value = coerceScalarValue(value, node.value);
+        const next = coerceScalarValue(value, node.value);
+        // An unchanged value keeps the node untouched — the parsed BigInt and the
+        // form's number compare by numeric value, so an identity pass never
+        // downgrades a BigInt-held integer to a lossy JS number.
+        if (!sameScalar(node.value, next))
+            node.value = next;
         return node;
     }
     return doc.createNode(value);
@@ -56,13 +68,24 @@ function applyToNode(doc, node, value) {
  * Update a map node against the value object: drop pairs whose key is gone,
  * recurse into the ones that remain (matched by their `toJS` key string, so
  * typed keys line up), and append a fresh pair for each genuinely new key.
+ * Under `schema`, keys that are not schema-born are exempt from all three —
+ * never dropped, never recursed into, never addable.
  */
-function reconcileMap(doc, node, value) {
-    node.items = node.items.filter((pair) => keyString(pair.key) in value);
+function reconcileMap(doc, node, value, schema) {
+    node.items = node.items.filter((pair) => {
+        const key = keyString(pair.key);
+        if (schema && !schema.has(key))
+            return true; // not schema-born: verbatim
+        // Own-key check: `in` would resolve doc keys like `toString` through the
+        // prototype chain and make them undeletable.
+        return Object.prototype.hasOwnProperty.call(value, key);
+    });
     for (const key of Object.keys(value)) {
+        if (schema && !schema.has(key))
+            continue; // not schema-born: never written
         const pair = node.items.find((p) => keyString(p.key) === key);
         if (pair) {
-            pair.value = applyToNode(doc, pair.value, value[key]);
+            pair.value = applyToNode(doc, pair.value, value[key], schema?.get(key));
         }
         else {
             node.items.push(doc.createPair(key, value[key]));
@@ -70,12 +93,12 @@ function reconcileMap(doc, node, value) {
     }
 }
 /** Update a sequence node: shrink/grow to the value's length, recurse per item. */
-function reconcileSeq(doc, node, value) {
+function reconcileSeq(doc, node, value, itemSchema) {
     while (node.items.length > value.length)
         node.items.pop();
     for (let i = 0; i < value.length; i++) {
         if (i < node.items.length) {
-            node.items[i] = applyToNode(doc, node.items[i], value[i]);
+            node.items[i] = applyToNode(doc, node.items[i], value[i], itemSchema);
         }
         else {
             node.items.push(doc.createNode(value[i]));
@@ -96,6 +119,15 @@ function coerceScalarValue(value, current) {
     }
     return value;
 }
+/** Numeric equality across the BigInt/number divide, `===` otherwise. */
+function sameScalar(current, next) {
+    if (current === next)
+        return true;
+    if (typeof current === 'bigint' && typeof next === 'number' && Number.isInteger(next)) {
+        return current === BigInt(next);
+    }
+    return false;
+}
 /**
  * The string a key node takes as a JS object key, matching `doc.toJS()`: the
  * scalar value stringified, with `null`/`undefined` collapsing to `''` (the

package/dist/transformers/yaml/yaml-transformer.d.ts

@@ -1,5 +1,5 @@
 import { type Document } from 'yaml';
-import type { FormValue, Thesaurus } from '../../core/schema';
+import type { FormValue, NodeGroup, Thesaurus } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
 import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 /** Options for {@link yamlTransformer}'s `toSchema`. */
@@ -21,6 +21,32 @@ export interface YamlOptions {
      * case-insensitively; never paths.
      */
     thesaurus?: Thesaurus;
+    /**
+     * Schema-driven mode only: what happens to keys the JSON Schema does not
+     * cover. `'preserve'` (default) keeps them verbatim — the form never
+     * carried them, so a partial schema edits its slice without erasing the
+     * rest. `'drop'` makes the edited value authoritative for the whole
+     * document, deleting uncovered keys — for consumers whose schema is
+     * intentionally complete. `'edit'` surfaces them instead: uncovered keys
+     * render as editable fields typed by the data (the inferred schema merged
+     * under the JSON Schema), so nothing is invisible and the value covers the
+     * whole document. Ignored without a `schema`.
+     */
+    unknownKeys?: 'preserve' | 'drop' | 'edit';
+}
+/**
+ * The revert context: the parsed {@link Document} and — in schema-driven
+ * mode with `unknownKeys: 'preserve'` or `'edit'` — the NodeGroup the form
+ * was built from (the JSON Schema's own under `'preserve'`, the
+ * inferred-merged one under `'edit'`), so `toSource` treats the value as
+ * authoritative for schema-born paths only. Under `'edit'` that is almost
+ * the whole document; the gate still protects the keys no form field can
+ * carry (e.g. a key inside a covered choice's object that no case names).
+ * Treat it as opaque: build it with `toSchema`, hand it back to `toSource`.
+ */
+export interface YamlBinding {
+    doc: Document;
+    schema?: NodeGroup;
 }
 /**
  * A YAML {@link Transformer}: turn a YAML config document into a form and write
@@ -28,14 +54,15 @@ export interface YamlOptions {
  * preserves comments, key order, and formatting by applying edits onto the parsed
  * document (see {@link applyValueToDocument}).
  *
- * The `binding` it round-trips is the parsed {@link Document}; `toSource` clones
- * it before applying, so a single `toSchema` result can serve many edits.
+ * The `binding` it round-trips is a {@link YamlBinding}; `toSource` clones the
+ * document inside it before applying, so a single `toSchema` result can serve
+ * many edits.
  *
  * With a JSON Schema in {@link YamlOptions}, the form is schema-driven; without
  * one it is inferred from the data.
  */
 export declare const yamlTransformer: {
     id: string;
-    toSchema(source: string, options?: YamlOptions): TransformResult<Document>;
-    toSource(value: FormValue, binding: Document): string;
+    toSchema(source: string, options?: YamlOptions): TransformResult<YamlBinding>;
+    toSource(value: FormValue, binding: YamlBinding): string;
 };