ng-form-foundry-transformers 0.3.3 → 0.3.5

package/README.md

@@ -16,6 +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 |
 
 The YAML and JSON transformers share the same format-agnostic form builders in
 `core` (`inferNodeGroup`, `jsonSchemaToNodeGroup`) — a JSON Schema is an *option*
@@ -49,6 +50,69 @@ the library's `serializeForm(schema, form)`, which strips the `__case`
 discriminators from `getRawValue()`. The YANG adapter is the exception: its
 `toYangData` consumes the form value and flattens `__case` itself.
 
+## Thesaurus — display metadata for machine schemas
+
+Machine schemas (O-RAN A1 policy types, inferred configs) ship without titles,
+so forms fall back to raw attribute names (`guRanUeId`, `mcc`). Every
+`toSchema` accepts a **thesaurus** — identifier → `{ label, description }` —
+injected into the produced schema, JSON-Schema-driven or inferred alike:
+
+```ts
+const thesaurus = {
+  ueId: { label: 'UE ID', description: 'UE identifier.' },
+  mcc: { label: 'MCC', description: 'Mobile Country Code (3 digits).' },
+};
+yamlTransformer.toSchema(text, { thesaurus });          // also json / libconfig
+jsonSchemaToNodeGroup(schema, 'body', { thesaurus });   // or standalone
+applyThesaurus(nodeGroup, thesaurus);                   // post-process anything
+```
+
+Keys are **plain identifier names**, matched **case-insensitively** against
+each node's property/setting name — one entry covers the identifier wherever
+it appears. Keys are never paths: no separator exists, so a `.` in a key is a
+literal character of the name. The thesaurus fills gaps only — schema-authored
+`title`/`description` always win. Unlabeled choice cases are titled from their
+discriminating required field; when sibling cases collide (identical required
+sets), the library's case selectors disambiguate them by each case's
+distinguishing fields.
+
+When the same identifier means different things at different depths, a key
+maps to a **list of variants scoped by `under`** — an ancestor-**name** suffix
+(an array, so still no separators; each segment is a literal name). The
+longest matching scope wins; an entry without `under` is the fallback:
+
+```ts
+const thesaurus = {
+  id: [
+    { under: ['cell'],  label: 'Cell ID' },   // any `id` directly inside a `cell`
+    { under: ['slice'], label: 'S-NSSAI' },
+    { label: 'ID' },                          // everywhere else
+  ],
+};
+```
+
+Scoping follows the **data hierarchy of names**: list indices, map entry keys,
+and — by default — choice case names are transparent. For a **choice**, case
+fields match both with and without their case-name segment, so one scope can
+cover the whole choice or target a single case:
+
+```ts
+// scope (choice) → cases byUe / byCell, both with a field named `id`
+const thesaurus = {
+  id: [
+    { under: ['scope', 'byUe'],   label: 'UE ID' },    // only inside the byUe case
+    { under: ['scope', 'byCell'], label: 'Cell ID' },  // only inside byCell
+    { under: ['scope'],           label: 'Scope ID' }, // any other case of scope
+  ],
+};
+// → byUe.id: "UE ID", byCell.id: "Cell ID"; the per-case labels also flow
+//   into caseLabels via each case's discriminating field.
+```
+
+Scoping by an auto-generated case name (`under: ['case0']`) works but is
+positional — it shifts when the source schema reorders its branches; prefer
+case-name scopes only for hand-named cases.
+
 ## YAML transformer
 
 Edit a **YAML config file**: turn it into a form, then write the edited value
@@ -82,8 +146,11 @@ leafList, `anyOf`/`oneOf` → choice (or a nullable leaf for `[T, null]`), `$ref
 `$defs`/`definitions` resolved inline (local **or cross-file** via
 `schemaOptions.refDocuments`, matched by `$id`), `const` → a read-only leaf, and the
 string / number constraints (`pattern`, `minLength`, `minimum`, `multipleOf`,
-`format`, …) carried onto the leaves as validators. Non-`required` properties
-become **`presence` nodes** — absent from the form and the serialized value until
+`format`, …) carried onto the leaves as validators, with
+`minProperties`/`maxProperties` becoming present-children bounds on closed
+objects (`minPresent`/`maxPresent`) or entry bounds on open maps.
+Non-`required` properties become **`presence` nodes** — absent from the form
+and the serialized value until
 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`.
@@ -102,6 +169,42 @@ const { schema, binding, initialValue } = jsonTransformer.toSchema(configText);
 const out = jsonTransformer.toSource({ ...initialValue, replicas: 5 }, binding);
 ```
 
+## libconfig transformer (beta)
+
+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';
+
+const { schema, binding, initialValue } = libconfigTransformer.toSchema(cfgText);
+// … build the form, let the user edit …
+const editedCfg = libconfigTransformer.toSource(editedValue, binding);
+```
+
+The revert **splices edited spans into the original text**, so comments, key
+order, `=` vs `:`, terminators, and delimiter style survive verbatim on every
+unedited byte. Emission is **type-preserving** — libconfig is statically typed,
+so a float slot edited to an integral value emits `21.0` not `21`, hex re-emits
+in hex at its original width, an int64 keeps its `L` suffix, and values beyond
+2^53 travel as exact decimal strings (the same bigint strategy as YAML/JSON).
+
+Without a JSON Schema, the form is inferred from the document's own typed
+literals; a list of groups infers the union of entry keys (keys missing from
+some entries become presence toggles). **Empty and heterogeneous collections
+are then shown read-only** — libconfig gives no element type to edit by; pass a
+JSON Schema (`{ schema, schemaOptions? }`) to type them and make them editable.
+`@include` is rejected by default (the form would show less than the C reader
+sees); `{ includes: 'opaque' }` keeps the directive line verbatim and edits only
+the file's own settings. Newly added settings are value-typed (an integral
+number emits as an int) — route float-typed additions through a JSON Schema
+slot that exists in the source, or accept the int typing.
+
+The format, the parser design, and the full round-trip semantics are described
+in [`docs/libconfig.md`](docs/libconfig.md).
+
 ## YANG transformer
 
 Turn a **YANG** model into an ng-form-foundry schema, then revert the edited form
@@ -191,6 +294,21 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.3.5` — the **thesaurus**: every `toSchema` and `jsonSchemaToNodeGroup`
+accept identifier → `{ label, description }` display metadata, with variants
+scoped by ancestor names (`under`) for identifiers that mean different things
+at different depths; choice cases are titled from their labeled discriminating
+field. Adversarially battle-tested (51-agent panel); the paired library
+release guarantees unique case-selector labels.
+
+`0.3.4` — the **libconfig transformer debuts as a beta** (one-time console
+warning on first use; lossless span-splicing round-trip with scalar types
+preserved — see [`docs/libconfig.md`](docs/libconfig.md)), and
+`minProperties`/`maxProperties` on closed objects now map to the library's
+`minPresent`/`maxPresent` present-children bounds, so an emptied
+all-optional object (e.g. an A1 `qosObjectives`) is flagged client-side
+instead of only by the server's validator.
+
 `0.3.3` — schema-valid round-trips for JSON-Schema-driven forms. Non-`required`
 properties now map to `presence` nodes (absent until enabled; opt out with
 `schemaOptions: { optionalPresence: false }`), a required property mapping to a

package/dist/core/index.d.ts

@@ -12,3 +12,5 @@ export { jsonSchemaToNodeGroup } from './json-schema';
 export type { JsonSchema, JsonSchemaOptions } from './json-schema';
 export type { NodeGroup, NodeType, Leaf, LeafList, NodeGroupList, Choice, ChoiceCase, NodeMap, LeafType, FormValue, } from './schema';
 export { CASE_KEY } from './schema';
+export type { Thesaurus, ThesaurusEntry } from './schema';
+export { applyThesaurus } from './thesaurus';

package/dist/core/index.js

@@ -7,7 +7,7 @@
  * map a JSON Schema) that any data-oriented transformer reuses.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CASE_KEY = exports.jsonSchemaToNodeGroup = exports.inferNodeGroup = exports.TransformerRegistry = void 0;
+exports.applyThesaurus = exports.CASE_KEY = exports.jsonSchemaToNodeGroup = exports.inferNodeGroup = exports.TransformerRegistry = void 0;
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "TransformerRegistry", { enumerable: true, get: function () { return registry_1.TransformerRegistry; } });
 // Shared schema builders — used by the YAML and JSON transformers alike.
@@ -17,3 +17,5 @@ var json_schema_1 = require("./json-schema");
 Object.defineProperty(exports, "jsonSchemaToNodeGroup", { enumerable: true, get: function () { return json_schema_1.jsonSchemaToNodeGroup; } });
 var schema_1 = require("./schema");
 Object.defineProperty(exports, "CASE_KEY", { enumerable: true, get: function () { return schema_1.CASE_KEY; } });
+var thesaurus_1 = require("./thesaurus");
+Object.defineProperty(exports, "applyThesaurus", { enumerable: true, get: function () { return thesaurus_1.applyThesaurus; } });

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

@@ -1,4 +1,4 @@
-import type { NodeGroup } from './schema';
+import type { NodeGroup, Thesaurus } from './schema';
 /**
  * The subset of JSON Schema (draft 2020-12, back-compatible with draft-07) this
  * transformer maps to a form. Only the keywords that shape a form are read;
@@ -56,6 +56,12 @@ export interface JsonSchemaOptions {
      * unconditionally.
      */
     optionalPresence?: boolean;
+    /**
+     * Display metadata injected into the produced schema (`label`,
+     * `description`, choice `caseLabels`) — see {@link applyThesaurus}. Fills
+     * gaps only; schema-authored `title`/`description` always win.
+     */
+    thesaurus?: Thesaurus;
 }
 type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
 /**
@@ -71,7 +77,9 @@ type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'bo
  * choice `mandatory`; a property *not* in `required` becomes a `presence` node
  * — absent from the form value until enabled — unless
  * {@link JsonSchemaOptions.optionalPresence} is `false`. `title` becomes the
- * label, `default`/`const` carry a scalar value.
+ * label, `default`/`const` carry a scalar value, and
+ * {@link JsonSchemaOptions.thesaurus} fills labels/descriptions the schema
+ * does not author.
  */
 export declare function jsonSchemaToNodeGroup(schema: JsonSchema, name?: string, options?: JsonSchemaOptions): NodeGroup;
 export {};

package/dist/core/json-schema.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonSchemaToNodeGroup = jsonSchemaToNodeGroup;
+const thesaurus_1 = require("./thesaurus");
 const ROOT = '__root__';
 /**
  * Map a JSON Schema whose top level is an object into a root {@link NodeGroup}.
@@ -15,7 +16,9 @@ const ROOT = '__root__';
  * choice `mandatory`; a property *not* in `required` becomes a `presence` node
  * — absent from the form value until enabled — unless
  * {@link JsonSchemaOptions.optionalPresence} is `false`. `title` becomes the
- * label, `default`/`const` carry a scalar value.
+ * label, `default`/`const` carry a scalar value, and
+ * {@link JsonSchemaOptions.thesaurus} fills labels/descriptions the schema
+ * does not author.
  */
 function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
     const documents = [schema, ...(options?.refDocuments ?? [])];
@@ -24,7 +27,7 @@ function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
     const { schema: root, scope } = resolver.resolve(schema);
     const group = objectToNodeGroup(root, name, scope, ctx, root.title);
     group.root = true;
-    return group;
+    return options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(group, options.thesaurus) : group;
 }
 /**
  * Apply {@link JsonSchemaOptions.optionalPresence} to one *property* node: a
@@ -110,6 +113,12 @@ function objectToNodeGroup(schema, name, resolver, ctx, label) {
     const group = { kind: 'nodeGroup', name, children };
     if (label)
         group.label = label;
+    // On a closed object these bound the count of *present* keys — meaningful
+    // because non-required properties are presence nodes (optionalPresence).
+    if (typeof schema.minProperties === 'number')
+        group.minPresent = schema.minProperties;
+    if (typeof schema.maxProperties === 'number')
+        group.maxPresent = schema.maxProperties;
     return group;
 }
 /** An `object` with open keys — `additionalProperties: <schema>` or `patternProperties`, and no fixed `properties`. */

package/dist/core/schema.d.ts

@@ -59,6 +59,14 @@ export interface NodeGroup {
      * serializes as `{}`, absent is omitted.
      */
     presence?: boolean;
+    /**
+     * Minimum / maximum number of keys present in the group's value (JSON Schema
+     * `minProperties`/`maxProperties` on a closed object with presence-optional
+     * children); the library validates the enabled-children count against them.
+     */
+    minPresent?: number;
+    maxPresent?: number;
+    description?: string;
     children: Record<string, NodeType>;
 }
 export interface NodeGroupList {
@@ -115,3 +123,30 @@ export type NodeType = Leaf | LeafList | NodeGroup | NodeGroupList | Choice | No
 export declare const CASE_KEY = "__case";
 /** A plain, nested value object produced/consumed by a rendered form. */
 export type FormValue = Record<string, unknown>;
+/** Display metadata for one schema identifier (see {@link Thesaurus}). */
+export interface ThesaurusEntry {
+    label?: string;
+    description?: string;
+    /**
+     * Ancestor-name suffix this variant applies under: each segment is a
+     * **literal name** (no separators exist, so any character is literal),
+     * matched case-insensitively against the identifier's ancestor chain.
+     * `['scope', 'cell']` applies to a node whose parent is `cell` inside
+     * `scope`, at any depth. Longest matching `under` wins; an entry without
+     * `under` is the unscoped fallback. Case fields match both with and without
+     * their case-name segment, so `['scope']` covers every case of a choice and
+     * `['scope', 'byUe']` targets one case.
+     */
+    under?: string[];
+}
+/**
+ * Identifier → display metadata, injected into a generated {@link NodeGroup}
+ * by `applyThesaurus`. Keys are **plain identifier names** matched
+ * **case-insensitively** against node record keys — never paths: no separator
+ * exists, so a `.` (or any character) in a key is a literal part of the name.
+ *
+ * A key maps to one entry, or to a list of variants scoped by
+ * {@link ThesaurusEntry.under} when the same identifier carries different
+ * meanings at different depths.
+ */
+export type Thesaurus = Record<string, ThesaurusEntry | ThesaurusEntry[]>;

package/dist/core/thesaurus.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A thesaurus: human-readable metadata for schema identifiers, injected into a
+ * generated {@link NodeGroup} as `label`/`description`/`caseLabels`.
+ *
+ * Machine schemas (O-RAN A1 policy types, inferred configs) ship without
+ * titles, so forms fall back to raw attribute names (`guRanUeId`, `mcc`).
+ * A thesaurus maps those identifiers to display metadata once, and every
+ * transformer entry point applies it to whatever schema it produced —
+ * JSON-Schema-driven or inferred alike.
+ *
+ * Keys are **plain identifier names**, matched **case-insensitively** against
+ * each node's record key (its property/setting name). They are never paths:
+ * no separator exists, so a name containing `.`/`/` or any other character is
+ * matched verbatim — one entry covers the identifier wherever it appears in
+ * the tree. When the same identifier means different things at different
+ * depths, a key maps to a list of variants scoped by
+ * {@link ThesaurusEntry.under} (an ancestor-name suffix); the longest
+ * matching scope wins, and an unscoped variant is the fallback.
+ */
+import type { NodeGroup, Thesaurus } from './schema';
+/**
+ * Return a copy of `schema` with thesaurus metadata filled in. Existing
+ * `label`/`description`/`caseLabels` values are respected, never overwritten —
+ * the thesaurus fills gaps, it does not restyle authored schemas.
+ *
+ * Coverage: every node reachable from the root (group children, list item
+ * fields, map value templates, choice case fields). Scoping follows the
+ * **data hierarchy of names**: fields inside list items scope under the list
+ * name (indices are transparent), map value fields under the map name
+ * (runtime keys are transparent), and choice case fields match both with and
+ * without their case-name segment — `under: ['scope']` covers every case of
+ * the `scope` choice, `under: ['scope', 'byUe']` targets one case (scoping by
+ * an auto-generated `case0`-style name works but is positional and brittle).
+ *
+ * A choice case with no label is titled from its discriminating field — the
+ * first `required` field (else the first field) whose thesaurus match carries
+ * a `label` (description-only entries do not title cases).
+ * Sibling cases may end up with the same label when their required sets
+ * coincide; the library's `caseDisplayLabels` disambiguates colliding labels
+ * in the selectors by each case's distinguishing fields, using the field
+ * labels injected here.
+ */
+export declare function applyThesaurus<G extends NodeGroup>(schema: G, thesaurus: Thesaurus): G;

package/dist/core/thesaurus.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyThesaurus = applyThesaurus;
+/**
+ * Return a copy of `schema` with thesaurus metadata filled in. Existing
+ * `label`/`description`/`caseLabels` values are respected, never overwritten —
+ * the thesaurus fills gaps, it does not restyle authored schemas.
+ *
+ * Coverage: every node reachable from the root (group children, list item
+ * fields, map value templates, choice case fields). Scoping follows the
+ * **data hierarchy of names**: fields inside list items scope under the list
+ * name (indices are transparent), map value fields under the map name
+ * (runtime keys are transparent), and choice case fields match both with and
+ * without their case-name segment — `under: ['scope']` covers every case of
+ * the `scope` choice, `under: ['scope', 'byUe']` targets one case (scoping by
+ * an auto-generated `case0`-style name works but is positional and brittle).
+ *
+ * A choice case with no label is titled from its discriminating field — the
+ * first `required` field (else the first field) whose thesaurus match carries
+ * a `label` (description-only entries do not title cases).
+ * Sibling cases may end up with the same label when their required sets
+ * coincide; the library's `caseDisplayLabels` disambiguates colliding labels
+ * in the selectors by each case's distinguishing fields, using the field
+ * labels injected here.
+ */
+function applyThesaurus(schema, thesaurus) {
+    const lookup = new Map();
+    for (const [key, value] of Object.entries(thesaurus)) {
+        const variants = (Array.isArray(value) ? value : [value]).map((entry, order) => ({
+            under: (entry.under ?? []).map((segment) => segment.toLowerCase()),
+            entry,
+            order,
+        }));
+        lookup.set(key.toLowerCase(), variants);
+    }
+    const out = structuredClone(schema);
+    decorate(out, out.name, [[]], lookup);
+    return out;
+}
+/**
+ * The best-scoped entry for `name` given the node's applicable ancestor
+ * chains: the variant with the longest `under` that is a suffix of any chain
+ * (an entry without `under` always applies); equal lengths keep author order.
+ */
+function resolve(name, chains, lookup) {
+    const variants = lookup.get(name.toLowerCase());
+    if (!variants)
+        return undefined;
+    let best;
+    for (const v of variants) {
+        if (!chains.some((chain) => isSuffix(v.under, chain)))
+            continue;
+        if (!best || v.under.length > best.under.length)
+            best = v;
+    }
+    return best?.entry;
+}
+function isSuffix(under, chain) {
+    if (under.length > chain.length)
+        return false;
+    const tail = chain.slice(chain.length - under.length);
+    return under.every((segment, i) => segment === tail[i]);
+}
+/**
+ * `transparentKey` marks a structural hop that contributes no ancestor
+ * segment: a map's `value` template is not a name in the data — entry fields
+ * scope under the map's own name.
+ */
+function decorate(node, key, chains, lookup, transparentKey = false) {
+    const entry = resolve(key, chains, lookup) ?? (key === node.name ? undefined : resolve(node.name, chains, lookup));
+    if (entry) {
+        if (entry.label !== undefined && node.label === undefined)
+            node.label = entry.label;
+        if (entry.description !== undefined &&
+            (node.kind === 'leaf' || node.kind === 'nodeGroup' || node.kind === 'map') &&
+            node.description === undefined) {
+            node.description = entry.description;
+        }
+    }
+    // Children's ancestor chains gain this node's key. List items and map
+    // entries add no segment of their own — indices and runtime keys are not
+    // names — so their fields scope under the list/map name directly.
+    const childChains = transparentKey ? chains : chains.map((chain) => [...chain, key.toLowerCase()]);
+    switch (node.kind) {
+        case 'nodeGroup':
+            for (const [childKey, child] of Object.entries(node.children))
+                decorate(child, childKey, childChains, lookup);
+            return;
+        case 'nodeGroupList':
+            for (const [childKey, child] of Object.entries(node.type.children))
+                decorate(child, childKey, childChains, lookup);
+            return;
+        case 'map':
+            decorate(node.value, node.value.name, childChains, lookup, true);
+            return;
+        case 'choice': {
+            for (const [caseName, body] of Object.entries(node.cases)) {
+                // Case fields match with and without the case segment: the wire
+                // encoding is inline (case-transparent), while the extra chain lets a
+                // scope target one case of the choice.
+                const caseChains = [...childChains, ...childChains.map((c) => [...c, caseName.toLowerCase()])];
+                const fields = caseFieldRecord(body);
+                for (const [fieldKey, field] of Object.entries(fields))
+                    decorate(field, fieldKey, caseChains, lookup);
+                if (node.caseLabels?.[caseName] !== undefined)
+                    continue;
+                // The discriminant must carry a LABEL — a description-only entry on an
+                // earlier field must not block a labeled sibling from titling the case.
+                const keys = Object.keys(fields);
+                const labelOf = (k) => resolve(k, caseChains, lookup)?.label;
+                const discriminant = keys.find((k) => fields[k].required && labelOf(k) !== undefined) ??
+                    keys.find((k) => labelOf(k) !== undefined);
+                const label = discriminant ? labelOf(discriminant) : undefined;
+                if (label !== undefined)
+                    node.caseLabels = { ...(node.caseLabels ?? {}), [caseName]: label };
+            }
+            return;
+        }
+        default:
+            return; // leaf / leafList: nothing beneath
+    }
+}
+/** A case body as a field record (a leaf-bodied case is a one-field record keyed by its name). */
+function caseFieldRecord(body) {
+    return typeof body.kind === 'string'
+        ? { [body.name]: body }
+        : body;
+}

package/dist/index.d.ts

@@ -12,6 +12,9 @@
  *              driven or inferred from the data, comment-preserving on revert.
  *   - `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.
  *
  * Look transformers up at runtime through {@link TransformerRegistry}, or import
  * the one you need directly.
@@ -20,3 +23,4 @@ export * from './core';
 export * from './transformers/yang';
 export * from './transformers/yaml';
 export * from './transformers/json';
+export * from './transformers/libconfig';

package/dist/index.js

@@ -13,6 +13,9 @@
  *              driven or inferred from the data, comment-preserving on revert.
  *   - `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.
  *
  * Look transformers up at runtime through {@link TransformerRegistry}, or import
  * the one you need directly.
@@ -38,3 +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

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

@@ -1,4 +1,4 @@
-import type { FormValue } from '../../core/schema';
+import type { FormValue, 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`. */
@@ -12,6 +12,13 @@ export interface JsonOptions {
     rootName?: string;
     /** Options forwarded to `jsonSchemaToNodeGroup` (`refDocuments`, `optionalPresence`). */
     schemaOptions?: JsonSchemaOptions;
+    /**
+     * Display metadata (`label`/`description`/choice `caseLabels`) injected into
+     * the produced schema, schema-driven or inferred alike — see
+     * `applyThesaurus`. Keys are plain identifier names, matched
+     * case-insensitively; never paths.
+     */
+    thesaurus?: Thesaurus;
 }
 /** How the source was formatted, so `toSource` re-emits it the same way. */
 export interface JsonFormat {

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonTransformer = void 0;
+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");
@@ -30,12 +31,13 @@ exports.jsonTransformer = {
         const schema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
+        const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
         const binding = {
             indent: detectIndent(source),
             trailingNewline: source.endsWith('\n'),
             bigInts,
         };
-        return { schema, binding, initialValue: data };
+        return { schema: labeled, binding, initialValue: data };
     },
     toSource(value, binding) {
         const paths = new Set(binding.bigInts);

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

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

package/dist/transformers/libconfig/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LibconfigParseError = exports.parseLibconfig = exports.resetLibconfigBetaWarning = 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

@@ -0,0 +1,56 @@
+/**
+ * A libconfig {@link Transformer} (BETA): 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')}).
+ *
+ * The `binding` is the original source plus its positioned AST; `toSource`
+ * splices edited spans into the source, so unedited bytes survive verbatim.
+ *
+ * Without a JSON Schema the form is inferred from the document's own typed
+ * literals ({@link import('./schema')}); empty and heterogeneous collections
+ * 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 { TransformResult } from '../../core/transformer';
+import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
+import { type CfgGroup } from './parser';
+/** Options for {@link libconfigTransformer}'s `toSchema`. */
+export interface LibconfigOptions {
+    /**
+     * A JSON Schema describing the config. When given, the form is built from it
+     * (types, required/presence, enums, empty-collection element types); when
+     * omitted, the form is inferred from the document's typed literals.
+     */
+    schema?: JsonSchema;
+    /** Name for the root node group. Defaults to `__root__`. */
+    rootName?: string;
+    /** Options forwarded to `jsonSchemaToNodeGroup` (`refDocuments`, `optionalPresence`). */
+    schemaOptions?: JsonSchemaOptions;
+    /**
+     * `@include` handling: `'reject'` (default) errors, because the form would
+     * silently show less than the C reader sees; `'opaque'` keeps the directive
+     * line verbatim and edits only this file's own settings.
+     */
+    includes?: 'reject' | 'opaque';
+    /**
+     * Display metadata (`label`/`description`/choice `caseLabels`) injected into
+     * the produced schema, schema-driven or inferred alike — see
+     * `applyThesaurus`. Keys are plain identifier names, matched
+     * case-insensitively; never paths.
+     */
+    thesaurus?: Thesaurus;
+}
+/** The revert context: the original text and its positioned AST. */
+export interface LibconfigBinding {
+    source: string;
+    root: CfgGroup;
+}
+/** 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>;
+    toSource(value: FormValue, binding: LibconfigBinding): string;
+};

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

@@ -0,0 +1,38 @@
+"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 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
+            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
+            : (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 };
+    },
+    toSource(value, binding) {
+        warnBeta();
+        return (0, revert_1.applyValueToSource)(binding.source, binding.root, value);
+    },
+};