ng-form-foundry-transformers 0.3.3 → 0.3.4

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*
@@ -82,8 +83,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 +106,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 +231,14 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`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/json-schema.js

@@ -110,6 +110,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,13 @@ 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;
     children: Record<string, NodeType>;
 }
 export interface NodeGroupList {

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/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,49 @@
+/**
+ * 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 } 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';
+}
+/** 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,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.libconfigTransformer = void 0;
+exports.resetLibconfigBetaWarning = resetLibconfigBetaWarning;
+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 initialValue = (0, schema_1.extractValue)(root, source, options?.schema != null);
+        return { schema, binding: { source, root }, initialValue };
+    },
+    toSource(value, binding) {
+        warnBeta();
+        return (0, revert_1.applyValueToSource)(binding.source, binding.root, value);
+    },
+};

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

@@ -0,0 +1,90 @@
+/**
+ * A lossless libconfig parser: source text → positioned AST.
+ *
+ * Every node carries its `[start, end)` span into the original text, and every
+ * scalar carries the emission metadata (`radix`, `L` suffix, float-ness, raw
+ * lexeme) that {@link import('./revert')} needs to write an edited value back
+ * without re-typing the setting for the consuming C program — libconfig is
+ * statically typed, so `20` and `20.0` are different types to
+ * `config_lookup_*`. Comments and formatting are not modeled: the revert
+ * splices only edited value spans, so every unedited byte survives verbatim.
+ *
+ * Implemented independently from the libconfig manual
+ * (https://hyperrealm.github.io/libconfig/libconfig_manual.html); the grammar
+ * covers: groups `{}`, arrays `[]` (homogeneous scalars), lists `()`
+ * (heterogeneous), settings `name = value;` / `name : value` with an optional
+ * `;`/`,` terminator, int (decimal/hex/binary/octal), int64 (`L`/`LL`
+ * suffix), float, bool (case-insensitive), strings with escapes and adjacent
+ * literal concatenation, `#`/`//`/`/* *​/` comments, and `@include` lines.
+ */
+/** Half-open source range of a node, in code-unit offsets. */
+export interface Span {
+    start: number;
+    end: number;
+}
+/** How an integer literal was written, so an edit re-emits the same style. */
+export interface IntMeta {
+    radix: 2 | 8 | 10 | 16;
+    /** `L`/`LL` suffix, verbatim, or empty. */
+    suffix: string;
+    /** Hex/binary/octal digit count of the literal, for width-preserving edits. */
+    digits: number;
+}
+export type CfgValue = CfgScalar | CfgGroup | CfgArray | CfgList;
+export interface CfgScalar {
+    kind: 'scalar';
+    span: Span;
+    /**
+     * `int` and `float` hold a JS number; `int64` holds the exact decimal digits
+     * as a string when the value is outside the safe integer range, a number
+     * otherwise (the string carry mirrors `core/bigint.ts`).
+     */
+    type: 'int' | 'int64' | 'float' | 'bool' | 'string';
+    value: number | string | boolean;
+    int?: IntMeta;
+}
+export interface CfgSetting {
+    name: string;
+    /** The whole setting: name through terminator (exclusive of trailing comment). */
+    span: Span;
+    value: CfgValue;
+}
+export interface CfgGroup {
+    kind: 'group';
+    span: Span;
+    /** Between the braces (the whole file for the root) — the insertion window. */
+    innerSpan: Span;
+    settings: CfgSetting[];
+}
+export interface CfgArray {
+    kind: 'array';
+    span: Span;
+    innerSpan: Span;
+    elements: CfgScalar[];
+}
+export interface CfgList {
+    kind: 'list';
+    span: Span;
+    innerSpan: Span;
+    elements: CfgValue[];
+}
+/** Options observed by the parser (a subset of the transformer's options). */
+export interface ParseOptions {
+    /**
+     * `'reject'` (default) errors on an `@include` line — the parsed form would
+     * silently show less than the C reader sees. `'opaque'` skips the directive:
+     * the line survives verbatim in the source and the included settings stay
+     * invisible to the form.
+     */
+    includes?: 'reject' | 'opaque';
+}
+/** A parse failure, pointing at the offending line and column. */
+export declare class LibconfigParseError extends Error {
+    readonly line: number;
+    readonly column: number;
+    constructor(message: string, line: number, column: number);
+}
+/** Parse a libconfig document into its root group (spans index into `source`). */
+export declare function parseLibconfig(source: string, options?: ParseOptions): CfgGroup;
+/** Scalar type family for array homogeneity: int and int64 mix, float does not. */
+export declare function family(type: CfgScalar['type']): 'integer' | 'float' | 'bool' | 'string';

package/dist/transformers/libconfig/parser.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * A lossless libconfig parser: source text → positioned AST.
+ *
+ * Every node carries its `[start, end)` span into the original text, and every
+ * scalar carries the emission metadata (`radix`, `L` suffix, float-ness, raw
+ * lexeme) that {@link import('./revert')} needs to write an edited value back
+ * without re-typing the setting for the consuming C program — libconfig is
+ * statically typed, so `20` and `20.0` are different types to
+ * `config_lookup_*`. Comments and formatting are not modeled: the revert
+ * splices only edited value spans, so every unedited byte survives verbatim.
+ *
+ * Implemented independently from the libconfig manual
+ * (https://hyperrealm.github.io/libconfig/libconfig_manual.html); the grammar
+ * covers: groups `{}`, arrays `[]` (homogeneous scalars), lists `()`
+ * (heterogeneous), settings `name = value;` / `name : value` with an optional
+ * `;`/`,` terminator, int (decimal/hex/binary/octal), int64 (`L`/`LL`
+ * suffix), float, bool (case-insensitive), strings with escapes and adjacent
+ * literal concatenation, `#`/`//`/`/* *​/` comments, and `@include` lines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LibconfigParseError = void 0;
+exports.parseLibconfig = parseLibconfig;
+exports.family = family;
+/** A parse failure, pointing at the offending line and column. */
+class LibconfigParseError extends Error {
+    constructor(message, line, column) {
+        super(`libconfig parse error at ${line}:${column} — ${message}`);
+        this.line = line;
+        this.column = column;
+        this.name = 'LibconfigParseError';
+    }
+}
+exports.LibconfigParseError = LibconfigParseError;
+const NAME_RE = /^[A-Za-z*][-A-Za-z0-9_*.]*/;
+const INT_RE = /^[-+]?(0[xX][0-9A-Fa-f]+|0[bB][01]+|0[oO][0-7]+|[0-9]+)(LL?)?/;
+const FLOAT_RE = /^[-+]?(([0-9]*\.[0-9]+|[0-9]+\.[0-9]*)([eE][-+]?[0-9]+)?|[0-9]+[eE][-+]?[0-9]+)/;
+const BOOL_RE = /^(true|false)(?![-A-Za-z0-9_*.])/i;
+/** Parse a libconfig document into its root group (spans index into `source`). */
+function parseLibconfig(source, options) {
+    return new Parser(source, options?.includes ?? 'reject').parseRoot();
+}
+class Parser {
+    constructor(src, includes) {
+        this.src = src;
+        this.includes = includes;
+        this.pos = 0;
+    }
+    parseRoot() {
+        const settings = this.parseSettings(undefined);
+        return {
+            kind: 'group',
+            span: { start: 0, end: this.src.length },
+            innerSpan: { start: 0, end: this.src.length },
+            settings,
+        };
+    }
+    /** Settings until `closer` (or EOF for the root). */
+    parseSettings(closer) {
+        const settings = [];
+        for (;;) {
+            this.skipTrivia();
+            if (this.pos >= this.src.length) {
+                if (closer)
+                    this.fail(`expected '${closer}'`);
+                return settings;
+            }
+            if (closer && this.src[this.pos] === closer)
+                return settings;
+            if (this.src[this.pos] === '@') {
+                this.handleInclude();
+                continue;
+            }
+            settings.push(this.parseSetting(settings));
+        }
+    }
+    parseSetting(siblings) {
+        const start = this.pos;
+        const name = this.match(NAME_RE) ?? this.fail('expected a setting name');
+        if (siblings.some((s) => s.name === name)) {
+            this.fail(`duplicate setting name '${name}' in the same group`);
+        }
+        this.skipTrivia();
+        if (this.src[this.pos] !== '=' && this.src[this.pos] !== ':') {
+            this.fail(`expected '=' or ':' after '${name}'`);
+        }
+        this.pos++;
+        this.skipTrivia();
+        const value = this.parseValue();
+        this.skipTrivia();
+        // Terminator is optional in the grammar: `;`, `,`, or nothing.
+        if (this.src[this.pos] === ';' || this.src[this.pos] === ',')
+            this.pos++;
+        return { name, span: { start, end: this.pos }, value };
+    }
+    parseValue() {
+        const c = this.src[this.pos];
+        if (c === '{')
+            return this.parseGroup();
+        if (c === '[')
+            return this.parseCollection('[', ']', 'array');
+        if (c === '(')
+            return this.parseCollection('(', ')', 'list');
+        return this.parseScalar();
+    }
+    parseGroup() {
+        const start = this.pos++;
+        const innerStart = this.pos;
+        const settings = this.parseSettings('}');
+        const innerEnd = this.pos;
+        this.pos++; // consume '}'
+        return {
+            kind: 'group',
+            span: { start, end: this.pos },
+            innerSpan: { start: innerStart, end: innerEnd },
+            settings,
+        };
+    }
+    parseCollection(open, close, kind) {
+        const start = this.pos++;
+        const innerStart = this.pos;
+        const elements = [];
+        for (;;) {
+            this.skipTrivia();
+            if (this.pos >= this.src.length)
+                this.fail(`expected '${close}'`);
+            if (this.src[this.pos] === close)
+                break;
+            const element = kind === 'array' ? this.parseScalar() : this.parseValue();
+            elements.push(element);
+            this.skipTrivia();
+            if (this.src[this.pos] === ',')
+                this.pos++;
+            else if (this.src[this.pos] !== close)
+                this.fail(`expected ',' or '${close}'`);
+        }
+        const innerEnd = this.pos;
+        this.pos++; // consume closer
+        if (kind === 'array') {
+            const nonScalar = elements.find((e) => e.kind !== 'scalar');
+            if (nonScalar)
+                this.fail('arrays hold scalars only (use a list for groups)');
+            const types = new Set(elements.map((e) => family(e.type)));
+            if (types.size > 1)
+                this.fail('array elements must share one scalar type');
+            return {
+                kind: 'array',
+                span: { start, end: this.pos },
+                innerSpan: { start: innerStart, end: innerEnd },
+                elements: elements,
+            };
+        }
+        return {
+            kind: 'list',
+            span: { start, end: this.pos },
+            innerSpan: { start: innerStart, end: innerEnd },
+            elements,
+        };
+    }
+    parseScalar() {
+        const start = this.pos;
+        const rest = this.src.slice(this.pos);
+        const bool = BOOL_RE.exec(rest);
+        if (bool) {
+            this.pos += bool[0].length;
+            return { kind: 'scalar', span: { start, end: this.pos }, type: 'bool', value: bool[0].toLowerCase() === 'true' };
+        }
+        if (rest[0] === '"')
+            return this.parseString();
+        // Float before int: `1.5` must not lex as int `1` + junk.
+        const float = FLOAT_RE.exec(rest);
+        if (float) {
+            this.pos += float[0].length;
+            return { kind: 'scalar', span: { start, end: this.pos }, type: 'float', value: Number(float[0]) };
+        }
+        const int = INT_RE.exec(rest);
+        if (int) {
+            this.pos += int[0].length;
+            return this.intScalar(int[0], { start, end: this.pos });
+        }
+        return this.fail('expected a value');
+    }
+    intScalar(lexeme, span) {
+        const sign = lexeme[0] === '-' ? '-' : '';
+        const unsigned = lexeme.replace(/^[-+]/, '');
+        const suffix = /LL?$/i.exec(unsigned)?.[0] ?? '';
+        const body = suffix ? unsigned.slice(0, -suffix.length) : unsigned;
+        const prefix = body.slice(0, 2).toLowerCase();
+        const radix = prefix === '0x' ? 16 : prefix === '0b' ? 2 : prefix === '0o' ? 8 : 10;
+        const digits = radix === 10 ? body : body.slice(2);
+        const big = BigInt(sign + (radix === 10 ? digits : body.slice(0, 2) + digits));
+        const meta = { radix, suffix, digits: digits.length };
+        // Values past 2^53 ride as exact decimal strings (the core bigint strategy);
+        // the suffix and radix stay in the metadata for the write-back.
+        const safe = big >= BigInt(Number.MIN_SAFE_INTEGER) && big <= BigInt(Number.MAX_SAFE_INTEGER);
+        const type = suffix || !safe ? 'int64' : 'int';
+        return {
+            kind: 'scalar',
+            span,
+            type,
+            value: safe ? Number(big) : big.toString(),
+            int: meta,
+        };
+    }
+    parseString() {
+        const start = this.pos;
+        let value = '';
+        // Adjacent literals concatenate: `"a" "b"` (possibly across lines) is "ab".
+        for (;;) {
+            value += this.parseStringLiteral();
+            const resume = this.pos;
+            this.skipTrivia();
+            if (this.src[this.pos] !== '"') {
+                this.pos = resume; // trivia after the last literal belongs to the caller
+                break;
+            }
+        }
+        return { kind: 'scalar', span: { start, end: this.pos }, type: 'string', value };
+    }
+    parseStringLiteral() {
+        this.pos++; // opening quote
+        let out = '';
+        while (this.pos < this.src.length) {
+            const c = this.src[this.pos];
+            if (c === '"') {
+                this.pos++;
+                return out;
+            }
+            if (c === '\\') {
+                const esc = this.src[this.pos + 1];
+                if (esc === 'x') {
+                    out += String.fromCharCode(parseInt(this.src.slice(this.pos + 2, this.pos + 4), 16));
+                    this.pos += 4;
+                    continue;
+                }
+                const simple = { n: '\n', r: '\r', t: '\t', f: '\f', v: '\v', '\\': '\\', '"': '"' };
+                out += (esc !== undefined && simple[esc]) || esc || '';
+                this.pos += 2;
+                continue;
+            }
+            if (c === '\n')
+                this.fail('unterminated string');
+            out += c;
+            this.pos++;
+        }
+        return this.fail('unterminated string');
+    }
+    handleInclude() {
+        const lineEnd = this.src.indexOf('\n', this.pos);
+        if (this.includes === 'reject') {
+            this.fail("'@include' is not supported: the form would show less than the C reader sees. " +
+                "Pass includes: 'opaque' to keep the directive verbatim and edit only this file's own settings");
+        }
+        this.pos = lineEnd === -1 ? this.src.length : lineEnd + 1;
+    }
+    /** Skip whitespace and all three comment forms. */
+    skipTrivia() {
+        for (;;) {
+            const c = this.src[this.pos];
+            if (c === ' ' || c === '\t' || c === '\r' || c === '\n') {
+                this.pos++;
+                continue;
+            }
+            if (c === '#' || (c === '/' && this.src[this.pos + 1] === '/')) {
+                const nl = this.src.indexOf('\n', this.pos);
+                this.pos = nl === -1 ? this.src.length : nl;
+                continue;
+            }
+            if (c === '/' && this.src[this.pos + 1] === '*') {
+                const end = this.src.indexOf('*/', this.pos + 2);
+                if (end === -1)
+                    this.fail('unterminated block comment');
+                this.pos = end + 2;
+                continue;
+            }
+            return;
+        }
+    }
+    match(re) {
+        const m = re.exec(this.src.slice(this.pos));
+        if (!m)
+            return undefined;
+        this.pos += m[0].length;
+        return m[0];
+    }
+    fail(message) {
+        const upto = this.src.slice(0, this.pos);
+        const line = upto.split('\n').length;
+        const column = this.pos - upto.lastIndexOf('\n');
+        throw new LibconfigParseError(message, line, column);
+    }
+}
+/** Scalar type family for array homogeneity: int and int64 mix, float does not. */
+function family(type) {
+    return type === 'int' || type === 'int64' ? 'integer' : type;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Write an edited form value back onto libconfig source by span splicing.
+ *
+ * Counterpart of the AST/extraction in {@link import('./parser')} and
+ * {@link import('./schema')}. Instead of regenerating text from the AST, the
+ * edited value is compared against the AST node by node and only the spans
+ * that actually changed are replaced in the original text — every unedited
+ * byte (comments, indentation, `=` vs `:`, terminators, delimiter style)
+ * survives verbatim.
+ *
+ * Emission is type-preserving, because the consuming C program reads settings
+ * through typed lookups: a float stays a float (`21` edits to `21.0`), a hex
+ * 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 { 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;

package/dist/transformers/libconfig/revert.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyValueToSource = applyValueToSource;
+const schema_1 = require("./schema");
+/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
+function applyValueToSource(source, root, value) {
+    const edits = [];
+    patchGroup(source, root, value, edits);
+    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) {
+    for (const setting of group.settings) {
+        if (!value || !(setting.name in value)) {
+            edits.push(deleteSetting(src, setting));
+            continue;
+        }
+        patchValue(src, setting.value, value[setting.name], edits);
+    }
+    const known = new Set(group.settings.map((s) => s.name));
+    const added = Object.keys(value ?? {}).filter((k) => !known.has(k));
+    if (added.length) {
+        edits.push(insertionEdit(src, group, added.map((k) => `${k} = ${serialize(value[k], '')};`)));
+    }
+}
+function patchValue(src, node, value, edits) {
+    switch (node.kind) {
+        case 'scalar': {
+            if (node.value === value)
+                return;
+            edits.push({ ...node.span, text: emitScalar(value, node) });
+            return;
+        }
+        case 'group': {
+            if (isRecord(value))
+                return patchGroup(src, node, value, edits);
+            edits.push({ ...node.span, text: serialize(value, '') }); // shape change: regenerate
+            return;
+        }
+        case 'array': {
+            if (Array.isArray(value))
+                return patchElements(src, node.elements, node, value, edits);
+            // The read-only raw carry of an untyped empty array: leave verbatim.
+            if (typeof value === 'string' && value === (0, schema_1.raw)(node, src))
+                return;
+            edits.push({ ...node.span, text: serialize(value, '') });
+            return;
+        }
+        case 'list': {
+            const shape = (0, schema_1.listShape)(node);
+            if (shape === 'groups' && Array.isArray(value)) {
+                return patchElements(src, node.elements, node, value, edits);
+            }
+            if (shape === 'scalars' && Array.isArray(value)) {
+                return patchElements(src, node.elements, node, value, edits);
+            }
+            if (shape === 'empty' && Array.isArray(value)) {
+                // Editable only under a JSON Schema; entries splice inside the delimiters.
+                if (value.length) {
+                    edits.push({ start: node.innerSpan.start, end: node.innerSpan.start, text: value.map((v) => serialize(v, '')).join(', ') });
+                }
+                return;
+            }
+            // Heterogeneous (read-only raw carry) or unchanged empty: only replace on
+            // a genuine mismatch with a non-raw value shape — otherwise leave verbatim.
+            if (typeof value === 'string' && value === (0, schema_1.raw)(node, src))
+                return;
+            if (value !== undefined && typeof value !== 'string') {
+                edits.push({ ...node.span, text: serialize(value, '') });
+            }
+            return;
+        }
+    }
+}
+/** Element-wise patch of an array/list: edit in place, then grow or shrink. */
+function patchElements(src, elements, collection, value, edits) {
+    const shared = Math.min(elements.length, value.length);
+    for (let i = 0; i < shared; i++)
+        patchValue(src, elements[i], value[i], edits);
+    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;
+        edits.push({ start: at, end: at, text: (elements.length ? ', ' : '') + items.join(', ') });
+    }
+    else if (value.length < elements.length) {
+        const start = value.length ? elements[value.length - 1].span.end : collection.innerSpan.start;
+        edits.push({ start, end: elements[elements.length - 1].span.end, text: '' });
+    }
+}
+/**
+ * Deletion takes the whole setting line when nothing else lives on it: the
+ * leading indent, the setting, trailing spaces, a trailing `#`/`//` comment,
+ * and the newline. A setting sharing its line only gives up its own span.
+ */
+function deleteSetting(src, setting) {
+    let start = setting.span.start;
+    while (start > 0 && (src[start - 1] === ' ' || src[start - 1] === '\t'))
+        start--;
+    const atLineStart = start === 0 || src[start - 1] === '\n';
+    let end = setting.span.end;
+    while (end < src.length && (src[end] === ' ' || src[end] === '\t'))
+        end++;
+    if (src[end] === '#' || (src[end] === '/' && src[end + 1] === '/')) {
+        const nl = src.indexOf('\n', end);
+        end = nl === -1 ? src.length : nl;
+    }
+    if (atLineStart && src[end] === '\n')
+        return { start, end: end + 1, text: '' };
+    return { start: setting.span.start, end, text: '' };
+}
+/** Indent of the group's first setting, for inserted lines (2 spaces fallback). */
+function settingIndent(src, group) {
+    const first = group.settings[0];
+    if (!first)
+        return '  ';
+    const lineStart = src.lastIndexOf('\n', first.span.start - 1) + 1;
+    const lead = src.slice(lineStart, first.span.start);
+    return /^[ \t]*$/.test(lead) ? lead : '  ';
+}
+/**
+ * Where new settings go: on fresh lines after the last setting's own line (so
+ * a trailing inline comment keeps its setting), else at the start of an empty
+ * braced group, else appended at the end of an empty root document.
+ */
+function insertionEdit(src, group, settings) {
+    const isRoot = group.span.start === 0 && group.span.end === src.length;
+    const limit = isRoot ? src.length : group.innerSpan.end;
+    const last = group.settings[group.settings.length - 1];
+    if (last) {
+        const indent = settingIndent(src, group);
+        const nl = src.indexOf('\n', last.span.end);
+        if (nl !== -1 && nl <= limit) {
+            return { start: nl, end: nl, text: settings.map((s) => `\n${indent}${s}`).join('') };
+        }
+        return { start: limit, end: limit, text: settings.map((s) => ` ${s}`).join('') };
+    }
+    const at = isRoot ? limit : group.innerSpan.start;
+    const text = settings.map((s) => `${isRoot ? '' : ' '}${s}`).join(' ');
+    return { start: at, end: at, text: isRoot ? text + '\n' : text + ' ' };
+}
+/** Format an edited scalar in the style its AST node was written in. */
+function emitScalar(value, node) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string') {
+        // The int64 string carry: exact digits back, with the original suffix.
+        if (node.type === 'int64' && typeof node.value === 'string') {
+            if (!/^[-+]?[0-9]+$/.test(value)) {
+                throw new Error(`'${value}' is not an integer: this setting carries a 64-bit integer as a string`);
+            }
+            return value + (node.int?.suffix ?? '');
+        }
+        return quote(value);
+    }
+    if (typeof value === 'number') {
+        if (node.type === 'float')
+            return floatLiteral(value);
+        if ((node.type === 'int' || node.type === 'int64') && Number.isInteger(value)) {
+            return intLiteral(value, node.int);
+        }
+        return floatLiteral(value); // a fractional edit into an int slot: emit honestly
+    }
+    return serialize(value, '');
+}
+/** Integer in the source's radix and width, suffix preserved. */
+function intLiteral(value, meta) {
+    if (!meta || meta.radix === 10)
+        return String(value) + (meta?.suffix ?? '');
+    const prefix = meta.radix === 16 ? '0x' : meta.radix === 2 ? '0b' : '0o';
+    const digits = Math.abs(value).toString(meta.radix).toUpperCase().padStart(meta.digits, '0');
+    return (value < 0 ? '-' : '') + prefix + digits + meta.suffix;
+}
+/** A float literal that stays a float: integral values gain `.0`. */
+function floatLiteral(value) {
+    const s = String(value);
+    return Number.isInteger(value) && !/[.eE]/.test(s) ? `${s}.0` : s;
+}
+function quote(value) {
+    let out = '"';
+    for (const ch of value) {
+        const code = ch.codePointAt(0);
+        if (ch === '"')
+            out += '\\"';
+        else if (ch === '\\')
+            out += '\\\\';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (ch === '\f')
+            out += '\\f';
+        else if (code < 0x20)
+            out += '\\x' + code.toString(16).padStart(2, '0');
+        else
+            out += ch;
+    }
+    return out + '"';
+}
+/**
+ * Serialize a brand-new value with no AST counterpart (an added setting, a
+ * grown collection). Typing is value-driven here: integral numbers emit as
+ * ints, fractional as floats — a host that needs a float-typed `21.0` for a
+ * fresh setting should send `21.0`-producing edits through an existing float
+ * slot or accept the int typing (documented beta limitation).
+ */
+function serialize(value, indent) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'string')
+        return /^[-+]?[0-9]+$/.test(value) && isBigIntString(value) ? value + 'L' : quote(value);
+    if (Array.isArray(value)) {
+        const inner = value.map((v) => serialize(v, indent)).join(', ');
+        const grouped = value.some((v) => isRecord(v) || Array.isArray(v));
+        return grouped ? `( ${inner} )` : `[ ${inner} ]`;
+    }
+    if (isRecord(value)) {
+        const body = Object.keys(value)
+            .map((k) => `${k} = ${serialize(value[k], indent)};`)
+            .join(' ');
+        return `{ ${body} }`;
+    }
+    return 'true'; // null/undefined have no libconfig literal; unreachable via typed forms
+}
+/** An integer string that exceeds the double-safe range (the bigint carry). */
+function isBigIntString(value) {
+    try {
+        const big = BigInt(value);
+        return big > BigInt(Number.MAX_SAFE_INTEGER) || big < BigInt(Number.MIN_SAFE_INTEGER);
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * libconfig AST → form schema and initial value.
+ *
+ * Inference works from the AST, not from plain data, because libconfig
+ * literals are statically typed: `20`, `20.0`, `true`, and `"x"` are four
+ * different types to the consuming C program, and the schema must reflect
+ * that. Rules the plain-data inference in `core/infer.ts` cannot express:
+ *
+ * - int leaves get `integer: true`; int64 values beyond 2^53 become string
+ *   leaves constrained to integer digits (the `core/bigint.ts` carry).
+ * - A list of groups becomes a nodeGroupList whose item type is the union of
+ *   the keys observed across entries; keys absent from at least one entry are
+ *   marked `presence: true`, so building an entry that lacks them does not
+ *   materialize null settings into the write-back.
+ * - Empty arrays/lists and heterogeneous lists have no honest element type,
+ *   so they map to read-only string leaves carrying the raw source span —
+ *   verbatim round-trip, no mistyping. A user-supplied JSON Schema (see the
+ *   transformer options) replaces this inference entirely and makes typed
+ *   empty collections editable.
+ */
+import type { NodeGroup } from '../../core/schema';
+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;
+/**
+ * The plain form value mirroring {@link libconfigToNodeGroup}'s schema.
+ *
+ * `emptyAsArrays` selects the empty-collection carry: the inferred schema
+ * renders an empty `[]`/`()` as a read-only verbatim string (no honest element
+ * type exists), while a user-supplied JSON Schema types it — so schema-driven
+ * extraction hands the form a real empty array instead.
+ */
+export declare function extractValue(value: CfgValue, source: string, emptyAsArrays?: boolean): unknown;
+type ListShape = 'groups' | 'scalars' | 'empty' | 'heterogeneous';
+/** Classify a `( )` list: all groups, all same-family scalars, empty, or mixed. */
+export declare function listShape(list: CfgList): ListShape;
+/** The verbatim source slice of a node. */
+export declare function raw(value: CfgValue, source: string): string;
+export {};

package/dist/transformers/libconfig/schema.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.libconfigToNodeGroup = libconfigToNodeGroup;
+exports.extractValue = extractValue;
+exports.listShape = listShape;
+exports.raw = raw;
+const parser_1 = require("./parser");
+/** Digits only — the constraint for int64 values carried as strings. */
+const INTEGER_STRING_PATTERN = '^[-+]?[0-9]+$';
+/** Infer the root NodeGroup for a parsed document. */
+function libconfigToNodeGroup(root, source, name) {
+    const group = groupToNode(root, source, name);
+    group.root = true;
+    return group;
+}
+/**
+ * The plain form value mirroring {@link libconfigToNodeGroup}'s schema.
+ *
+ * `emptyAsArrays` selects the empty-collection carry: the inferred schema
+ * renders an empty `[]`/`()` as a read-only verbatim string (no honest element
+ * type exists), while a user-supplied JSON Schema types it — so schema-driven
+ * extraction hands the form a real empty array instead.
+ */
+function extractValue(value, source, emptyAsArrays = false) {
+    switch (value.kind) {
+        case 'scalar':
+            return value.value;
+        case 'group': {
+            const out = Object.create(null);
+            for (const s of value.settings)
+                out[s.name] = extractValue(s.value, source, emptyAsArrays);
+            return out;
+        }
+        case 'array':
+            if (value.elements.length === 0 && !emptyAsArrays)
+                return raw(value, source);
+            return arrayValue(value.elements);
+        case 'list': {
+            const shape = listShape(value);
+            if (shape === 'groups')
+                return value.elements.map((e) => extractValue(e, source, emptyAsArrays));
+            if (shape === 'scalars')
+                return arrayValue(value.elements);
+            if (shape === 'empty' && emptyAsArrays)
+                return [];
+            return raw(value, source); // empty or heterogeneous: the verbatim span
+        }
+    }
+}
+function nodeFor(name, value, source) {
+    switch (value.kind) {
+        case 'scalar':
+            return scalarLeaf(name, value);
+        case 'group':
+            return groupToNode(value, source, name);
+        case 'array':
+            return listLeaf(name, value.elements);
+        case 'list': {
+            const shape = listShape(value);
+            if (shape === 'groups')
+                return groupListNode(name, value, source);
+            if (shape === 'scalars')
+                return listLeaf(name, value.elements);
+            return rawLeaf(name, shape === 'empty' ? 'empty collection' : 'heterogeneous list');
+        }
+    }
+}
+function groupToNode(group, source, name) {
+    const children = Object.create(null);
+    for (const s of group.settings)
+        children[s.name] = nodeFor(s.name, s.value, source);
+    return { kind: 'nodeGroup', name, children };
+}
+function scalarLeaf(name, scalar) {
+    switch (scalar.type) {
+        case 'bool':
+            return { kind: 'leaf', name, type: 'boolean' };
+        case 'string':
+            return { kind: 'leaf', name, type: 'string' };
+        case 'float':
+            return { kind: 'leaf', name, type: 'number' };
+        case 'int':
+            return { kind: 'leaf', name, type: 'number', integer: true };
+        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 };
+    }
+}
+/**
+ * A homogeneous scalar collection → leafList. One int64 element beyond 2^53
+ * degrades the whole list to string carry: a leafList holds one scalar type,
+ * so consistency beats convenience (see {@link arrayValue}, which matches).
+ */
+function listLeaf(name, elements) {
+    if (elements.length === 0)
+        return rawLeaf(name, 'empty collection');
+    const f = (0, parser_1.family)(elements[0].type);
+    if (f === 'integer' && elements.some((e) => typeof e.value === 'string')) {
+        return { kind: 'leafList', name, type: 'string' };
+    }
+    return { kind: 'leafList', name, type: f === 'integer' || f === 'float' ? 'number' : f === 'bool' ? 'boolean' : 'string' };
+}
+function arrayValue(elements) {
+    const stringCarry = elements.length > 0 &&
+        (0, parser_1.family)(elements[0].type) === 'integer' &&
+        elements.some((e) => typeof e.value === 'string');
+    return elements.map((e) => (stringCarry ? String(e.value) : e.value));
+}
+/**
+ * A list of groups → nodeGroupList typed as the union of keys across entries;
+ * keys missing from at least one entry become presence fields, so entries
+ * lacking them build without the key instead of materializing nulls.
+ */
+function groupListNode(name, list, source) {
+    const groups = list.elements;
+    const children = Object.create(null);
+    const seenIn = Object.create(null);
+    for (const g of groups) {
+        for (const s of g.settings) {
+            if (!(s.name in children))
+                children[s.name] = nodeFor(s.name, s.value, source);
+            seenIn[s.name] = (seenIn[s.name] ?? 0) + 1;
+        }
+    }
+    for (const key of Object.keys(children)) {
+        if ((seenIn[key] ?? 0) < groups.length) {
+            const child = children[key];
+            if (child.kind === 'leaf' || child.kind === 'nodeGroup' || child.kind === 'map' || child.kind === 'choice') {
+                child.presence = true;
+            }
+        }
+    }
+    return { kind: 'nodeGroupList', name, type: { kind: 'nodeGroup', name, children } };
+}
+/** Classify a `( )` list: all groups, all same-family scalars, empty, or mixed. */
+function listShape(list) {
+    if (list.elements.length === 0)
+        return 'empty';
+    if (list.elements.every((e) => e.kind === 'group'))
+        return 'groups';
+    if (list.elements.every((e) => e.kind === 'scalar')) {
+        const families = new Set(list.elements.map((e) => (0, parser_1.family)(e.type)));
+        if (families.size === 1)
+            return 'scalars';
+    }
+    return 'heterogeneous';
+}
+/** Read-only leaf carrying the collection's verbatim source text. */
+function rawLeaf(name, why) {
+    return {
+        kind: 'leaf',
+        name,
+        type: 'string',
+        readOnly: true,
+        description: `Shown verbatim (${why}): libconfig gives no element type to edit by. Provide a JSON Schema to make it editable.`,
+    };
+}
+/** The verbatim source slice of a node. */
+function raw(value, source) {
+    return source.slice(value.span.start, value.span.end);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry-transformers",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Framework-agnostic Node + TypeScript catalog of source-format transformers: turn a YANG model (and more) into an ng-form-foundry schema and revert the edited form value back to the source format.",
   "keywords": [
     "ng-form-foundry",