ng-form-foundry-transformers 0.3.2 → 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*
@@ -80,9 +81,16 @@ covers **draft 2020-12** (back-compatible with draft-07): `object` → nodeGroup
 a `map` for `additionalProperties`/`patternProperties`), `array` → nodeGroupList /
 leafList, `anyOf`/`oneOf` → choice (or a nullable leaf for `[T, null]`), `$ref` →
 `$defs`/`definitions` resolved inline (local **or cross-file** via
-`options.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.
+`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, 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`.
 
 ## JSON transformer
 
@@ -98,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
@@ -187,6 +231,23 @@ 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
+choice is flagged `mandatory`, and the YAML/JSON transformers gained
+`options.schemaOptions` — which also makes `refDocuments` (cross-file `$ref`)
+reachable through them for the first time. Pairs with the library's
+required-aware choice-case inference, empty list seeding, and
+materialized-validity rules.
+
 `0.3.2` — documentation release alongside the library's `serializeForm`: the
 YAML/JSON `toSource` examples now take the wire value (choice `__case`
 discriminators stripped); no transformer code changes.

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

@@ -47,6 +47,15 @@ export interface JsonSchemaOptions {
      * document then resolve against it.
      */
     refDocuments?: JsonSchema[];
+    /**
+     * Map non-required properties to `presence: true` nodes (default `true`):
+     * absent from the form and the serialized value until the user enables them,
+     * which is what `required` + `additionalProperties: false` schemas demand —
+     * an untouched optional materialized as `null` fails validation against the
+     * very schema the form came from. Set `false` to materialize every property
+     * unconditionally.
+     */
+    optionalPresence?: boolean;
 }
 type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
 /**
@@ -58,8 +67,11 @@ type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'bo
  * `additionalProperties`/`patternProperties`); `anyOf`/`oneOf` → a {@link Choice}
  * (or a nullable leaf for the `[T, null]` shape); `array` → nodeGroupList or
  * leafList; a scalar (with `enum`, `const`, `type: [T, 'null']`, and the string /
- * number constraints) → a typed leaf. `required` marks child leaves, `title`
- * becomes the label, `default`/`const` carry a scalar value.
+ * number constraints) → a typed leaf. `required` marks leaves required and a
+ * 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.
  */
 export declare function jsonSchemaToNodeGroup(schema: JsonSchema, name?: string, options?: JsonSchemaOptions): NodeGroup;
 export {};

package/dist/core/json-schema.js

@@ -11,17 +11,37 @@ const ROOT = '__root__';
  * `additionalProperties`/`patternProperties`); `anyOf`/`oneOf` → a {@link Choice}
  * (or a nullable leaf for the `[T, null]` shape); `array` → nodeGroupList or
  * leafList; a scalar (with `enum`, `const`, `type: [T, 'null']`, and the string /
- * number constraints) → a typed leaf. `required` marks child leaves, `title`
- * becomes the label, `default`/`const` carry a scalar value.
+ * number constraints) → a typed leaf. `required` marks leaves required and a
+ * 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.
  */
 function jsonSchemaToNodeGroup(schema, name = ROOT, options) {
     const documents = [schema, ...(options?.refDocuments ?? [])];
     const resolver = new RefResolver(schema, documents);
+    const ctx = { optionalPresence: options?.optionalPresence ?? true };
     const { schema: root, scope } = resolver.resolve(schema);
-    const group = objectToNodeGroup(root, name, scope, root.title);
+    const group = objectToNodeGroup(root, name, scope, ctx, root.title);
     group.root = true;
     return group;
 }
+/**
+ * Apply {@link JsonSchemaOptions.optionalPresence} to one *property* node: a
+ * non-required property becomes a presence node, so it stays absent from the
+ * form value until enabled. Only called at property positions
+ * ({@link objectToNodeGroup} children and {@link branchToCase} fields) — a map's
+ * `value` template, an array's item type, and a leaf-bodied case are not
+ * properties and must never be marked. Lists cannot carry `presence`.
+ */
+function markOptionalProperty(node, required, ctx) {
+    if (!ctx.optionalPresence || required)
+        return node;
+    if (node.kind === 'leaf' || node.kind === 'nodeGroup' || node.kind === 'choice' || node.kind === 'map') {
+        node.presence = true;
+    }
+    return node;
+}
 /**
  * Resolves `$ref` chains, following them across documents. A resolver is bound to
  * one document (for `#/…` local refs); crossing into another document via a
@@ -80,15 +100,22 @@ function resolveFragment(doc, fragment) {
     return node;
 }
 // --- objects / maps -----------------------------------------------------------
-function objectToNodeGroup(schema, name, resolver, label) {
+function objectToNodeGroup(schema, name, resolver, ctx, label) {
     const required = new Set(schema.required ?? []);
     const children = {};
     for (const [key, propSchema] of Object.entries(schema.properties ?? {})) {
-        children[key] = schemaToNode(key, propSchema, required.has(key), resolver);
+        const node = schemaToNode(key, propSchema, required.has(key), resolver, ctx);
+        children[key] = markOptionalProperty(node, required.has(key), ctx);
     }
     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`. */
@@ -100,7 +127,7 @@ function isOpenMap(schema) {
     const hasPattern = !!schema.patternProperties && Object.keys(schema.patternProperties).length > 0;
     return additionalIsSchema || hasPattern;
 }
-function objectToMap(name, schema, resolver) {
+function objectToMap(name, schema, resolver, ctx) {
     let valueSchema = {};
     let keyPattern;
     const pattern = schema.patternProperties && Object.entries(schema.patternProperties)[0];
@@ -110,7 +137,7 @@ function objectToMap(name, schema, resolver) {
     else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
         valueSchema = schema.additionalProperties;
     }
-    const node = { kind: 'map', name, value: schemaToNode('value', valueSchema, false, resolver) };
+    const node = { kind: 'map', name, value: schemaToNode('value', valueSchema, false, resolver, ctx) };
     if (schema.title)
         node.label = schema.title;
     if (keyPattern)
@@ -123,7 +150,7 @@ function objectToMap(name, schema, resolver) {
 }
 // --- anyOf / oneOf → choice ---------------------------------------------------
 /** The `anyOf`/`oneOf` `[T, null]` shape collapses to a nullable leaf; anything else is a choice. */
-function branchesToNode(name, schema, rawBranches, required, resolver) {
+function branchesToNode(name, schema, rawBranches, required, resolver, ctx) {
     const branches = rawBranches.map((b) => resolver.resolve(b));
     const nonNull = branches.filter((b) => b.schema.type !== 'null');
     const sole = nonNull.length === 1 ? nonNull[0] : undefined;
@@ -136,11 +163,13 @@ function branchesToNode(name, schema, rawBranches, required, resolver) {
     const caseLabels = {};
     branches.forEach(({ schema: branch, scope }, index) => {
         const caseName = `case${index}`;
-        cases[caseName] = branchToCase(branch, scope);
+        cases[caseName] = branchToCase(branch, scope, ctx);
         if (branch.title)
             caseLabels[caseName] = branch.title;
     });
     const choice = { kind: 'choice', name, cases };
+    if (required)
+        choice.mandatory = true;
     if (schema.title)
         choice.label = schema.title;
     if (Object.keys(caseLabels).length)
@@ -148,29 +177,30 @@ function branchesToNode(name, schema, rawBranches, required, resolver) {
     return choice;
 }
 /** A resolved branch → a case body: a field record for an object branch, else a single node. */
-function branchToCase(branch, scope) {
+function branchToCase(branch, scope, ctx) {
     if (primaryType(branch) === 'object' && branch.properties) {
         const required = new Set(branch.required ?? []);
         const fields = {};
         for (const [key, propSchema] of Object.entries(branch.properties)) {
-            fields[key] = schemaToNode(key, propSchema, required.has(key), scope);
+            const node = schemaToNode(key, propSchema, required.has(key), scope, ctx);
+            fields[key] = markOptionalProperty(node, required.has(key), ctx);
         }
         return fields;
     }
-    return schemaToNode('value', branch, false, scope);
+    return schemaToNode('value', branch, false, scope, ctx);
 }
 // --- dispatch -----------------------------------------------------------------
-function schemaToNode(name, rawSchema, required, resolver) {
+function schemaToNode(name, rawSchema, required, resolver, ctx) {
     const { schema, scope } = resolver.resolve(rawSchema);
     const branches = schema.anyOf ?? schema.oneOf;
     if (branches && branches.length) {
-        return branchesToNode(name, schema, branches, required, scope);
+        return branchesToNode(name, schema, branches, required, scope, ctx);
     }
     const type = primaryType(schema);
     if (type === 'object' || (type === undefined && (schema.properties || isOpenMap(schema)))) {
         if (isOpenMap(schema))
-            return objectToMap(name, schema, scope);
-        return objectToNodeGroup(schema, name, scope, schema.title);
+            return objectToMap(name, schema, scope, ctx);
+        return objectToNodeGroup(schema, name, scope, ctx, schema.title);
     }
     if (type === 'array') {
         const { schema: items, scope: itemScope } = scope.resolve(schema.items ?? {});
@@ -178,7 +208,7 @@ function schemaToNode(name, rawSchema, required, resolver) {
             const node = {
                 kind: 'nodeGroupList',
                 name,
-                type: objectToNodeGroup(items, name, itemScope, items.title),
+                type: objectToNodeGroup(items, name, itemScope, ctx, items.title),
             };
             if (schema.title)
                 node.label = schema.title;

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 {
@@ -86,7 +93,10 @@ export interface Choice {
     /** Display labels for cases, keyed by case name. */
     caseLabels?: Record<string, string>;
     default?: string;
+    /** A case must be selected for the form to be valid (a required property). */
     mandatory?: boolean;
+    /** Optional choice whose presence is itself data (mirrors {@link NodeGroup.presence}). */
+    presence?: boolean;
 }
 /**
  * An open, arbitrary-keyed record: unlike {@link NodeGroup} (a fixed key set), a

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,6 +1,6 @@
 import type { FormValue } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
-import { type JsonSchema } from '../../core/json-schema';
+import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 /** Options for {@link jsonTransformer}'s `toSchema`. */
 export interface JsonOptions {
     /**
@@ -10,6 +10,8 @@ export interface JsonOptions {
     schema?: JsonSchema;
     /** Name for the root node group. Defaults to `__root__`. */
     rootName?: string;
+    /** Options forwarded to `jsonSchemaToNodeGroup` (`refDocuments`, `optionalPresence`). */
+    schemaOptions?: JsonSchemaOptions;
 }
 /** How the source was formatted, so `toSource` re-emits it the same way. */
 export interface JsonFormat {

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

@@ -28,7 +28,7 @@ exports.jsonTransformer = {
         const parsed = JSON.parse(source, bigIntReviver);
         const data = collectBigInts(parsed ?? {}, [], bigInts);
         const schema = options?.schema
-            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName)
+            ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
         const binding = {
             indent: detectIndent(source),

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';