ng-form-foundry-transformers 0.4.1 → 0.5.1

package/README.md

@@ -16,7 +16,7 @@ or a CLI just as easily.
 | `yang` | YANG model (via an engine) | RFC 7951 instance data | available |
 | `yaml` | YAML config (optionally a JSON Schema) | YAML (comments preserved) | available |
 | `json` | JSON config (optionally a JSON Schema) | JSON (indent preserved) | available |
-| `libconfig` | libconfig document (optionally a JSON Schema) | libconfig (comments **and scalar types** preserved) | **beta** — warns on first use |
+| `libconfig` | libconfig document (optionally a JSON Schema) | libconfig (comments **and scalar types** preserved) | available |
 
 The YAML and JSON transformers share the same format-agnostic form builders in
 `core` (`inferNodeGroup`, `jsonSchemaToNodeGroup`) — a JSON Schema is an *option*
@@ -155,6 +155,15 @@ enabled, so the output validates against the source schema (opt out with
 `schemaOptions: { optionalPresence: false }`); a required property mapping to a
 choice is marked `mandatory`.
 
+**The schema may cover any slice of the document.** Keys it does not mention
+are governed by `unknownKeys` (YAML, JSON, and libconfig alike):
+`'preserve'` (default) keeps them verbatim on save — a partial schema edits
+its fields without erasing the rest of a real-world config; `'drop'` deletes
+them — for an intentionally complete schema (sanitizing, template
+enforcement); `'edit'` surfaces them as editable fields typed by the
+document's own values, merged under the JSON Schema in document order, so
+nothing in the file is invisible.
+
 ## JSON transformer
 
 Same as YAML, for **JSON config files** — `jsonTransformer.toSchema(json, { schema? })`
@@ -169,12 +178,10 @@ const { schema, binding, initialValue } = jsonTransformer.toSchema(configText);
 const out = jsonTransformer.toSource({ ...initialValue, replicas: 5 }, binding);
 ```
 
-## libconfig transformer (beta)
+## libconfig transformer
 
 Edit a **libconfig document** — the `.cfg`/`.conf` format of srsRAN, OAI, and
 other C/C++ software using [libconfig](https://hyperrealm.github.io/libconfig/).
-**Beta**: it logs a one-time warning on first use; diff `toSource` output
-against the original before deploying a write-back.
 
 ```ts
 import { libconfigTransformer } from 'ng-form-foundry-transformers';
@@ -294,6 +301,22 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.5.1` — **partial JSON Schemas edit safely**: the new `unknownKeys` option
+(YAML, JSON, libconfig) governs keys the schema does not cover — `'preserve'`
+(default) keeps them verbatim on save, `'drop'` deletes them for
+intentionally complete schemas, `'edit'` surfaces them as editable fields
+typed by the document's own values. The YAML binding is now
+`YamlBinding { doc, schema? }` instead of the bare parsed document (bindings
+are opaque; code that hands them straight back to `toSource` is unaffected).
+
+`0.5.0` — the **libconfig transformer is stable**: the one-time beta warning
+is gone (and with it the `resetLibconfigBetaWarning` helper), and the format's
+guarantees and known limitations are documented in the transformers guide.
+Non-decimal integer literals (`0x`, `0b`, `0o`/`0q`) now set a `radix` display
+hint on the generated schema — the paired `ng-form-foundry` release renders
+those fields as hex/octal/binary editors, and the YAML transformer does the
+same for its hex and octal literals.
+
 `0.4.1` — libconfig hardening after a conformance battle test against the C
 library's own scanner, test corpus, and real srsRAN/OAI configs: `0q`/`0Q`
 octal, verbatim radix-prefix preservation on edits, sign accepted on decimal

package/dist/core/infer.d.ts

@@ -1,7 +1,8 @@
 import type { NodeGroup } from './schema';
 /**
- * Infer a root {@link NodeGroup} from a parsed data object when no schema is
- * given. Structure and types come from the values themselves:
+ * Infer a root {@link NodeGroup} from a parsed data object — the whole form
+ * when no JSON Schema is given, and the layer `mergeInferred` overlays under
+ * `unknownKeys: 'edit'`. Structure and types come from the values themselves:
  *
  *   - object            → nodeGroup (recursed)
  *   - array of objects  → nodeGroupList (item schema = union of the items' keys)

package/dist/core/infer.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.inferNodeGroup = inferNodeGroup;
 const ROOT = '__root__';
 /**
- * Infer a root {@link NodeGroup} from a parsed data object when no schema is
- * given. Structure and types come from the values themselves:
+ * Infer a root {@link NodeGroup} from a parsed data object — the whole form
+ * when no JSON Schema is given, and the layer `mergeInferred` overlays under
+ * `unknownKeys: 'edit'`. Structure and types come from the values themselves:
  *
  *   - object            → nodeGroup (recursed)
  *   - array of objects  → nodeGroupList (item schema = union of the items' keys)
@@ -21,7 +22,9 @@ function inferNodeGroup(data, name = ROOT) {
     return group;
 }
 function objectToNodeGroup(data, name) {
-    const children = {};
+    // Null prototype: data keys are arbitrary, and assigning a `__proto__` key
+    // onto a plain object would silently set the record's prototype instead.
+    const children = Object.create(null);
     for (const [key, value] of Object.entries(data)) {
         children[key] = inferNode(key, value);
     }
@@ -45,7 +48,7 @@ function inferArray(name, items) {
 }
 /** A representative object with every key seen across `items`, each mapped to the first non-null sample. */
 function unionKeys(items) {
-    const merged = {};
+    const merged = Object.create(null);
     for (const item of items) {
         for (const [key, value] of Object.entries(item)) {
             if (!(key in merged) || (merged[key] == null && value != null))

package/dist/core/merge-inferred.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema union for `unknownKeys: 'edit'`: overlay a user-supplied JSON
+ * Schema's {@link NodeGroup} onto the schema *inferred from the document
+ * itself*, so covered keys keep their typed, validated, labeled nodes while
+ * every key the JSON Schema does not mention still renders — editable, typed
+ * by inference (see `core/infer.ts` and the per-format inference in the
+ * transformers). Counterpart of `core/schema-keys.ts`, which handles the
+ * *preserve-invisibly* answer to the same question.
+ */
+import type { NodeGroup } from './schema';
+/**
+ * Merge per key, recursively. Document order wins for placement: the
+ * inferred children mirror the source document, so present keys render in
+ * file order with schema-only keys (e.g. presence-able additions) appended
+ * after, in schema order. Where both sides describe a key, the schema wins —
+ * except that groups and group-lists merge structurally, so a partially
+ * covered subtree keeps its uncovered fields at any depth. Group metadata
+ * (name, label, presence, bounds) comes from the schema side.
+ */
+export declare function mergeInferred(schema: NodeGroup, inferred: NodeGroup): NodeGroup;

package/dist/core/merge-inferred.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeInferred = mergeInferred;
+/**
+ * Merge per key, recursively. Document order wins for placement: the
+ * inferred children mirror the source document, so present keys render in
+ * file order with schema-only keys (e.g. presence-able additions) appended
+ * after, in schema order. Where both sides describe a key, the schema wins —
+ * except that groups and group-lists merge structurally, so a partially
+ * covered subtree keeps its uncovered fields at any depth. Group metadata
+ * (name, label, presence, bounds) comes from the schema side.
+ */
+function mergeInferred(schema, inferred) {
+    const children = Object.create(null);
+    for (const [name, inferredChild] of Object.entries(inferred.children)) {
+        const schemaChild = schema.children[name];
+        children[name] = schemaChild ? mergeNode(schemaChild, inferredChild) : inferredChild;
+    }
+    for (const [name, schemaChild] of Object.entries(schema.children)) {
+        if (!(name in children))
+            children[name] = schemaChild;
+    }
+    return { ...schema, children };
+}
+/**
+ * One key described by both sides: groups and group-lists merge recursively;
+ * everything else — leaves, choices, maps, and shape disagreements — takes
+ * the schema node, which is authoritative wherever it speaks. One inferred
+ * fact does carry over: a leaf's `radix` display hint, which only the
+ * document knows (JSON Schema has no radix vocabulary).
+ */
+function mergeNode(schema, inferred) {
+    if (schema.kind === 'nodeGroup' && inferred.kind === 'nodeGroup') {
+        return mergeInferred(schema, inferred);
+    }
+    if (schema.kind === 'nodeGroupList' && inferred.kind === 'nodeGroupList') {
+        return { ...schema, type: mergeInferred(schema.type, inferred.type) };
+    }
+    if ((schema.kind === 'leaf' || schema.kind === 'leafList') &&
+        schema.kind === inferred.kind &&
+        inferred.radix &&
+        !schema.radix) {
+        return { ...schema, radix: inferred.radix };
+    }
+    return schema;
+}

package/dist/core/schema-keys.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Schema-born key resolution for partial-schema reverts.
+ *
+ * A transformer given a JSON Schema builds its form from the produced
+ * {@link NodeGroup} — so `serializeForm` can only ever emit keys that schema
+ * describes. When the edited value is written back onto the original
+ * document, the value is authoritative for those **schema-born** paths only;
+ * every other key was never carried by the form and must be preserved.
+ * These helpers answer "which keys can the value legitimately speak for?" at
+ * each document level, mirroring the wire encoding of
+ * ng-form-foundry's `serializeForm`/`toWireValue`.
+ */
+import type { NodeGroup, NodeType } from './schema';
+/**
+ * The schema-born key set of one document level, as `name → child schema`
+ * for recursion. `undefined` means "no schema in play": every key is
+ * value-authoritative. A key absent from a defined map is not schema-born
+ * and must be preserved verbatim.
+ */
+export type SchemaKeys = Map<string, NodeType | undefined> | undefined;
+/**
+ * The keys `serializeForm` can emit for a schema node standing at a document
+ * object/group, with each key's schema for recursion. A nodeGroup
+ * contributes its children by key — a choice child included, since the wire
+ * value keeps a choice at its own key (`toWireValue` strips only the case
+ * discriminator). Standing at a choice, the keys are the union of every
+ * case's fields: the form only emits the active case, so the other cases'
+ * keys behave like any non-emitted schema key. A map is open-keyed — every
+ * key is schema-born and entries recurse with the map's value schema.
+ */
+export declare function childrenOf(node: NodeType): SchemaKeys;
+/** The per-item schema when `node` describes a list of groups, else undefined. */
+export declare function itemSchemaOf(node: NodeType | undefined): NodeGroup | undefined;

package/dist/core/schema-keys.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.childrenOf = childrenOf;
+exports.itemSchemaOf = itemSchemaOf;
+/**
+ * The keys `serializeForm` can emit for a schema node standing at a document
+ * object/group, with each key's schema for recursion. A nodeGroup
+ * contributes its children by key — a choice child included, since the wire
+ * value keeps a choice at its own key (`toWireValue` strips only the case
+ * discriminator). Standing at a choice, the keys are the union of every
+ * case's fields: the form only emits the active case, so the other cases'
+ * keys behave like any non-emitted schema key. A map is open-keyed — every
+ * key is schema-born and entries recurse with the map's value schema.
+ */
+function childrenOf(node) {
+    switch (node.kind) {
+        case 'nodeGroup':
+            return new Map(Object.entries(node.children));
+        case 'choice': {
+            const out = new Map();
+            for (const [name, field] of caseEntries(node))
+                out.set(name, field);
+            return out;
+        }
+        case 'map':
+            return new OpenKeys(node.value);
+        default:
+            return undefined; // leaf/leafList/list shapes carry no key semantics
+    }
+}
+/** The per-item schema when `node` describes a list of groups, else undefined. */
+function itemSchemaOf(node) {
+    return node?.kind === 'nodeGroupList' ? node.type : undefined;
+}
+/** Field name → schema across every case of a choice (leaf-bodied cases too). */
+function* caseEntries(choice) {
+    for (const body of Object.values(choice.cases)) {
+        if ('kind' in body)
+            yield [body.name, body];
+        else
+            for (const [name, field] of Object.entries(body))
+                yield [name, field];
+    }
+}
+/** A `SchemaKeys` map matching every key — a map node's open dictionary. */
+class OpenKeys extends Map {
+    constructor(valueSchema) {
+        super();
+        this.valueSchema = valueSchema;
+    }
+    has(_key) {
+        return true;
+    }
+    get(_key) {
+        return this.valueSchema;
+    }
+}

package/dist/core/schema.d.ts

@@ -32,6 +32,13 @@ export interface Leaf {
     min?: number;
     max?: number;
     multipleOf?: number;
+    /**
+     * Present the value in this base (16 hex, 8 octal, 2 binary) instead of
+     * decimal — set when the source document wrote the literal that way. Purely
+     * a display hint: the value itself stays a plain number (or, on a string
+     * leaf, the exact decimal-digit carry of an integer beyond ±2^53).
+     */
+    radix?: 2 | 8 | 16;
     /** The value may be `null` (JSON Schema `type: [T, 'null']`). */
     nullable?: boolean;
     /** Optional scalar whose presence is itself data (on/off toggle). */
@@ -47,6 +54,8 @@ export interface LeafList {
     label?: string;
     minItems?: number;
     maxItems?: number;
+    /** Present every item in this base — see {@link Leaf.radix}. */
+    radix?: 2 | 8 | 16;
 }
 export interface NodeGroup {
     kind: 'nodeGroup';

package/dist/index.d.ts

@@ -13,8 +13,8 @@
  *   - `json` — JSON config → form → JSON ({@link jsonTransformer}); same builders
  *              as `yaml`, indent preserved.
  *   - `libconfig` — libconfig document (srsRAN/OAI-style `.cfg`/`.conf`) → form →
- *              libconfig ({@link libconfigTransformer}); **BETA**, warns once on
- *              first use; comment- and type-preserving span splicing on revert.
+ *              libconfig ({@link libconfigTransformer}); comment- and
+ *              type-preserving span splicing on revert.
  *
  * Look transformers up at runtime through {@link TransformerRegistry}, or import
  * the one you need directly.

package/dist/index.js

@@ -14,8 +14,8 @@
  *   - `json` — JSON config → form → JSON ({@link jsonTransformer}); same builders
  *              as `yaml`, indent preserved.
  *   - `libconfig` — libconfig document (srsRAN/OAI-style `.cfg`/`.conf`) → form →
- *              libconfig ({@link libconfigTransformer}); **BETA**, warns once on
- *              first use; comment- and type-preserving span splicing on revert.
+ *              libconfig ({@link libconfigTransformer}); comment- and
+ *              type-preserving span splicing on revert.
  *
  * Look transformers up at runtime through {@link TransformerRegistry}, or import
  * the one you need directly.
@@ -41,4 +41,4 @@ __exportStar(require("./core"), exports);
 __exportStar(require("./transformers/yang"), exports);
 __exportStar(require("./transformers/yaml"), exports);
 __exportStar(require("./transformers/json"), exports);
-__exportStar(require("./transformers/libconfig"), exports); // BETA — warns once on first use
+__exportStar(require("./transformers/libconfig"), exports);

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

@@ -1,4 +1,4 @@
-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 jsonTransformer}'s `toSchema`. */
@@ -19,6 +19,18 @@ export interface JsonOptions {
      * case-insensitively; never paths.
      */
     thesaurus?: Thesaurus;
+    /**
+     * Schema-driven mode only: what happens to keys the JSON Schema does not
+     * cover. `'preserve'` (default) keeps them — 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';
 }
 /** How the source was formatted, so `toSource` re-emits it the same way. */
 export interface JsonFormat {
@@ -32,6 +44,19 @@ export interface JsonFormat {
      * them back as unquoted numbers so precision survives the round-trip.
      */
     bigInts: string[];
+    /**
+     * Present in schema-driven mode with `unknownKeys: 'preserve'` (the
+     * default) or `'edit'`: the original parsed data and the NodeGroup the
+     * form was built from (the JSON Schema's own under `'preserve'`, the
+     * inferred-merged one under `'edit'`). `toSource` then treats the value as
+     * authoritative for schema-born paths only and merges it over the
+     * original, so uncovered keys survive in their original key order — under
+     * `'edit'` that protection is left covering only the keys no form field
+     * can carry (e.g. a key inside a covered choice's object that no case
+     * names).
+     */
+    original?: FormValue;
+    schema?: NodeGroup;
 }
 /**
  * A JSON {@link Transformer}: turn a JSON config document into a form and write
@@ -39,12 +64,15 @@ export interface JsonFormat {
  * `core` builders the YAML transformer uses — only parsing (`JSON.parse`) and
  * serialization (`JSON.stringify`) are JSON-specific.
  *
- * Standard JSON has no comments, so revert re-serializes the edited value,
- * preserving the source's indent width and trailing newline. Key order follows
- * the form value (which follows the schema, derived from the original), so it is
- * preserved for untouched keys. For JSON **with comments** (JSONC), parse and
- * edit it as YAML with {@link import('../yaml/yaml-transformer').yamlTransformer}
- * instead — `JSON.parse` rejects comments.
+ * Standard JSON has no comments, so revert re-serializes, preserving the
+ * source's indent width and trailing newline. In schema-driven mode with
+ * `unknownKeys: 'preserve'` or `'edit'` the value is merged over the original
+ * data at schema-born paths ({@link mergeSchemaBorn}), so uncovered keys and
+ * the original key order survive; otherwise the edited value is serialized
+ * as-is, key order following the form value. For JSON **with comments**
+ * (JSONC), parse and edit it as YAML with
+ * {@link import('../yaml/yaml-transformer').yamlTransformer} instead —
+ * `JSON.parse` rejects comments.
  *
  * Integers beyond 2^53 can't survive a `number` round-trip, so they are carried
  * as strings in the form value and re-emitted verbatim as unquoted numbers (the

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

@@ -5,18 +5,23 @@ const thesaurus_1 = require("../../core/thesaurus");
 const infer_1 = require("../../core/infer");
 const json_schema_1 = require("../../core/json-schema");
 const bigint_1 = require("../../core/bigint");
+const schema_keys_1 = require("../../core/schema-keys");
+const merge_inferred_1 = require("../../core/merge-inferred");
 /**
  * A JSON {@link Transformer}: turn a JSON config document into a form and write
  * the edited value back to JSON. The form is built by the same format-agnostic
  * `core` builders the YAML transformer uses — only parsing (`JSON.parse`) and
  * serialization (`JSON.stringify`) are JSON-specific.
  *
- * Standard JSON has no comments, so revert re-serializes the edited value,
- * preserving the source's indent width and trailing newline. Key order follows
- * the form value (which follows the schema, derived from the original), so it is
- * preserved for untouched keys. For JSON **with comments** (JSONC), parse and
- * edit it as YAML with {@link import('../yaml/yaml-transformer').yamlTransformer}
- * instead — `JSON.parse` rejects comments.
+ * Standard JSON has no comments, so revert re-serializes, preserving the
+ * source's indent width and trailing newline. In schema-driven mode with
+ * `unknownKeys: 'preserve'` or `'edit'` the value is merged over the original
+ * data at schema-born paths ({@link mergeSchemaBorn}), so uncovered keys and
+ * the original key order survive; otherwise the edited value is serialized
+ * as-is, key order following the form value. For JSON **with comments**
+ * (JSONC), parse and edit it as YAML with
+ * {@link import('../yaml/yaml-transformer').yamlTransformer} instead —
+ * `JSON.parse` rejects comments.
  *
  * Integers beyond 2^53 can't survive a `number` round-trip, so they are carried
  * as strings in the form value and re-emitted verbatim as unquoted numbers (the
@@ -28,26 +33,80 @@ exports.jsonTransformer = {
         const bigInts = [];
         const parsed = JSON.parse(source, bigIntReviver);
         const data = collectBigInts(parsed ?? {}, [], bigInts);
-        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, infer_1.inferNodeGroup)(data, options?.rootName);
+            : undefined;
+        const schema = fromJsonSchema && unknownKeys === 'edit'
+            ? (0, merge_inferred_1.mergeInferred)(fromJsonSchema, (0, infer_1.inferNodeGroup)(data, options?.rootName))
+            : fromJsonSchema ?? (0, infer_1.inferNodeGroup)(data, options?.rootName);
         const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
+        // 'preserve' gates the revert on the JSON Schema's NodeGroup; 'edit' on
+        // the merged one (schema-born ≈ everything, but keys no form field can
+        // carry stay protected); 'drop' and inferred mode leave the value
+        // authoritative for the whole document.
+        const preserveUnknown = fromJsonSchema != null && unknownKeys !== 'drop';
         const binding = {
             indent: detectIndent(source),
             trailingNewline: source.endsWith('\n'),
             bigInts,
+            original: preserveUnknown ? data : undefined,
+            schema: preserveUnknown ? schema : undefined,
         };
         return { schema: labeled, binding, initialValue: data };
     },
     toSource(value, binding) {
+        const merged = binding.schema && binding.original !== undefined
+            ? mergeSchemaBorn(binding.original, value, (0, schema_keys_1.childrenOf)(binding.schema))
+            : value;
         const paths = new Set(binding.bigInts);
-        const prepared = paths.size ? markBigInts(value, [], paths) : value;
+        const prepared = paths.size ? markBigInts(merged, [], paths) : merged;
         let text = JSON.stringify(prepared, null, binding.indent);
         if (paths.size)
             text = text.replace(BIGINT_MARK_RE, '$1');
         return binding.trailingNewline ? text + '\n' : text;
     },
 };
+/**
+ * Merge the edited value over the original data, value-authoritative for
+ * schema-born keys only: an uncovered key keeps its original value and its
+ * position in the key order; a covered key takes the edited value (recursing
+ * where both sides are objects, and per index into arrays of groups); a
+ * covered key absent from the value is omitted (a presence toggle off);
+ * covered keys new to the document append after the originals.
+ */
+function mergeSchemaBorn(original, value, schema) {
+    if (!isPlainObject(original) || !isPlainObject(value) || !schema)
+        return value;
+    // Null-prototype output and own-key checks: document keys are arbitrary, so
+    // `__proto__` must stay a data key and `toString`/`constructor` must not
+    // resolve through the prototype chain (which would drop or fabricate keys).
+    const out = Object.create(null);
+    for (const key of Object.keys(original)) {
+        if (!schema.has(key)) {
+            out[key] = original[key]; // not schema-born: verbatim, in place
+        }
+        else if (hasOwn(value, key)) {
+            out[key] = mergeChild(original[key], value[key], schema.get(key));
+        } // covered + absent: deleted
+    }
+    for (const key of Object.keys(value)) {
+        if (!(key in out) && !hasOwn(original, key) && schema.has(key))
+            out[key] = value[key];
+    }
+    return out;
+}
+/** Per-key recursion: objects merge by their child schema, group arrays per index. */
+function mergeChild(original, value, schema) {
+    if (schema && isPlainObject(original) && isPlainObject(value)) {
+        return mergeSchemaBorn(original, value, (0, schema_keys_1.childrenOf)(schema));
+    }
+    const itemSchema = (0, schema_keys_1.itemSchemaOf)(schema);
+    if (itemSchema && Array.isArray(original) && Array.isArray(value)) {
+        return value.map((item, i) => i < original.length ? mergeChild(original[i], item, itemSchema) : item);
+    }
+    return value;
+}
 /** Indent width (in spaces) of the first indented line, or 2 if none/tabs. */
 function detectIndent(source) {
     const match = source.match(/\n( +)\S/);
@@ -102,7 +161,8 @@ function collectBigInts(node, path, out) {
     if (Array.isArray(node))
         return node.map((v, i) => collectBigInts(v, [...path, i], out));
     if (isPlainObject(node)) {
-        const res = {};
+        // Null prototype: a `__proto__` document key must stay a data key.
+        const res = Object.create(null);
         for (const key of Object.keys(node))
             res[key] = collectBigInts(node[key], [...path, key], out);
         return res;
@@ -121,7 +181,7 @@ function markBigInts(node, path, paths) {
     if (Array.isArray(node))
         return node.map((v, i) => markBigInts(v, [...path, i], paths));
     if (isPlainObject(node)) {
-        const res = {};
+        const res = Object.create(null);
         for (const key of Object.keys(node))
             res[key] = markBigInts(node[key], [...path, key], paths);
         return res;
@@ -131,3 +191,7 @@ function markBigInts(node, path, paths) {
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/** Own-key membership, immune to `Object.prototype` members and null-prototype objects. */
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}

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

@@ -1,2 +1,2 @@
-export { libconfigTransformer, resetLibconfigBetaWarning, type LibconfigBinding, type LibconfigOptions, } from './libconfig-transformer';
+export { libconfigTransformer, type LibconfigBinding, type LibconfigOptions, } from './libconfig-transformer';
 export { parseLibconfig, LibconfigParseError } from './parser';

package/dist/transformers/libconfig/index.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LibconfigParseError = exports.parseLibconfig = exports.resetLibconfigBetaWarning = exports.libconfigTransformer = void 0;
+exports.LibconfigParseError = exports.parseLibconfig = exports.libconfigTransformer = void 0;
 var libconfig_transformer_1 = require("./libconfig-transformer");
 Object.defineProperty(exports, "libconfigTransformer", { enumerable: true, get: function () { return libconfig_transformer_1.libconfigTransformer; } });
-Object.defineProperty(exports, "resetLibconfigBetaWarning", { enumerable: true, get: function () { return libconfig_transformer_1.resetLibconfigBetaWarning; } });
 var parser_1 = require("./parser");
 Object.defineProperty(exports, "parseLibconfig", { enumerable: true, get: function () { return parser_1.parseLibconfig; } });
 Object.defineProperty(exports, "LibconfigParseError", { enumerable: true, get: function () { return parser_1.LibconfigParseError; } });

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

@@ -1,5 +1,5 @@
 /**
- * A libconfig {@link Transformer} (BETA): turn a libconfig document
+ * A libconfig {@link Transformer}: turn a libconfig document
  * (srsRAN/OAI-style `.cfg`/`.conf`) into a form and write the edited value
  * back with comments, formatting, and — critically — scalar *types*
  * preserved (libconfig is statically typed; see {@link import('./revert')}).
@@ -12,7 +12,7 @@
  * are then shown read-only. A JSON Schema in the options unlocks typed empty
  * collections, presence toggles for optional settings, enums, and ranges.
  */
-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';
 import { type CfgGroup } from './parser';
@@ -34,6 +34,20 @@ export interface LibconfigOptions {
      * line verbatim and edits only this file's own settings.
      */
     includes?: 'reject' | 'opaque';
+    /**
+     * Schema-driven mode only: what happens to settings the JSON Schema does
+     * not cover. `'preserve'` (default) keeps them byte-verbatim in place —
+     * 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 settings — for consumers whose schema
+     * is intentionally complete (sanitizing a config, enforcing a strict
+     * template). `'edit'` surfaces them instead: uncovered settings render as
+     * editable fields typed by the document's own literals (the inferred
+     * schema merged under the JSON Schema — see `mergeInferred`), so nothing
+     * is invisible and the value covers the whole document. Ignored without a
+     * `schema`, where the inferred value covers every setting anyway.
+     */
+    unknownKeys?: 'preserve' | 'drop' | 'edit';
     /**
      * Display metadata (`label`/`description`/choice `caseLabels`) injected into
      * the produced schema, schema-driven or inferred alike — see
@@ -42,13 +56,23 @@ export interface LibconfigOptions {
      */
     thesaurus?: Thesaurus;
 }
-/** The revert context: the original text and its positioned AST. */
+/**
+ * The revert context: the original text, its positioned AST, 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` knows
+ * which paths are schema-born. Settings outside those paths were never
+ * carried by the form and survive verbatim; under `'edit'` that is only the
+ * keys no form field can carry (e.g. a key inside a covered choice's group
+ * that no case names). Absent `schema` (inferred mode, or
+ * `unknownKeys: 'drop'`), the value covers the whole document and is
+ * authoritative everywhere.
+ */
 export interface LibconfigBinding {
     source: string;
     root: CfgGroup;
+    schema?: NodeGroup;
 }
-/** Test seam: makes the one-time beta warning observable per test. */
-export declare function resetLibconfigBetaWarning(): void;
 export declare const libconfigTransformer: {
     id: string;
     toSchema(source: string, options?: LibconfigOptions): TransformResult<LibconfigBinding>;