ng-form-foundry-transformers 0.4.1 → 0.5.0

package/README.md

@@ -16,7 +16,7 @@ or a CLI just as easily.
 | `yang` | YANG model (via an engine) | RFC 7951 instance data | available |
 | `yaml` | YAML config (optionally a JSON Schema) | YAML (comments preserved) | available |
 | `json` | JSON config (optionally a JSON Schema) | JSON (indent preserved) | available |
-| `libconfig` | libconfig document (optionally a JSON Schema) | libconfig (comments **and scalar types** preserved) | **beta** — warns on first use |
+| `libconfig` | libconfig document (optionally a JSON Schema) | libconfig (comments **and scalar types** preserved) | available |
 
 The YAML and JSON transformers share the same format-agnostic form builders in
 `core` (`inferNodeGroup`, `jsonSchemaToNodeGroup`) — a JSON Schema is an *option*
@@ -169,12 +169,10 @@ const { schema, binding, initialValue } = jsonTransformer.toSchema(configText);
 const out = jsonTransformer.toSource({ ...initialValue, replicas: 5 }, binding);
 ```
 
-## libconfig transformer (beta)
+## libconfig transformer
 
 Edit a **libconfig document** — the `.cfg`/`.conf` format of srsRAN, OAI, and
 other C/C++ software using [libconfig](https://hyperrealm.github.io/libconfig/).
-**Beta**: it logs a one-time warning on first use; diff `toSource` output
-against the original before deploying a write-back.
 
 ```ts
 import { libconfigTransformer } from 'ng-form-foundry-transformers';
@@ -294,6 +292,14 @@ npm test        # node:test on the compiled output (no Python needed)
 
 ## Status
 
+`0.5.0` — the **libconfig transformer is stable**: the one-time beta warning
+is gone (and with it the `resetLibconfigBetaWarning` helper), and the format's
+guarantees and known limitations are documented in the transformers guide.
+Non-decimal integer literals (`0x`, `0b`, `0o`/`0q`) now set a `radix` display
+hint on the generated schema — the paired `ng-form-foundry` release renders
+those fields as hex/octal/binary editors, and the YAML transformer does the
+same for its hex and octal literals.
+
 `0.4.1` — libconfig hardening after a conformance battle test against the C
 library's own scanner, test corpus, and real srsRAN/OAI configs: `0q`/`0Q`
 octal, verbatim radix-prefix preservation on edits, sign accepted on decimal

package/dist/core/schema.d.ts

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

package/dist/index.d.ts

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

package/dist/index.js

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

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

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

package/dist/transformers/libconfig/index.js

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

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

@@ -1,5 +1,5 @@
 /**
- * A libconfig {@link Transformer} (BETA): turn a libconfig document
+ * A libconfig {@link Transformer}: turn a libconfig document
  * (srsRAN/OAI-style `.cfg`/`.conf`) into a form and write the edited value
  * back with comments, formatting, and — critically — scalar *types*
  * preserved (libconfig is statically typed; see {@link import('./revert')}).
@@ -47,8 +47,6 @@ 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>;

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

@@ -1,28 +1,14 @@
 "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)
@@ -32,7 +18,6 @@ exports.libconfigTransformer = {
         return { schema: labeled, binding: { source, root }, initialValue };
     },
     toSource(value, binding) {
-        warnBeta();
         return (0, revert_1.applyValueToSource)(binding.source, binding.root, value);
     },
 };

package/dist/transformers/libconfig/schema.js

@@ -80,14 +80,21 @@ function scalarLeaf(name, scalar) {
         case 'float':
             return { kind: 'leaf', name, type: 'number' };
         case 'int':
-            return { kind: 'leaf', name, type: 'number', integer: true };
+            return withRadix({ kind: 'leaf', name, type: 'number', integer: true }, scalar);
         case 'int64':
             // Beyond 2^53 the value rides as an exact decimal string.
             return typeof scalar.value === 'string'
-                ? { kind: 'leaf', name, type: 'string', pattern: INTEGER_STRING_PATTERN }
-                : { kind: 'leaf', name, type: 'number', integer: true };
+                ? withRadix({ kind: 'leaf', name, type: 'string', pattern: INTEGER_STRING_PATTERN }, scalar)
+                : withRadix({ kind: 'leaf', name, type: 'number', integer: true }, scalar);
     }
 }
+/** Carry a non-decimal literal's base onto the leaf as its display radix. */
+function withRadix(leaf, scalar) {
+    const radix = scalar.int?.radix;
+    if (radix && radix !== 10)
+        leaf.radix = radix;
+    return leaf;
+}
 /**
  * A homogeneous scalar collection → leafList. One int64 element beyond 2^53
  * degrades the whole list to string carry: a leafList holds one scalar type,
@@ -97,10 +104,23 @@ function listLeaf(name, elements) {
     if (elements.length === 0)
         return rawLeaf(name, 'empty collection');
     const f = (0, parser_1.family)(elements[0].type);
+    const radix = f === 'integer' ? sharedRadix(elements) : undefined;
     if (f === 'integer' && elements.some((e) => typeof e.value === 'string')) {
-        return { kind: 'leafList', name, type: 'string' };
+        return { kind: 'leafList', name, type: 'string', ...(radix && { radix }) };
     }
-    return { kind: 'leafList', name, type: f === 'integer' || f === 'float' ? 'number' : f === 'bool' ? 'boolean' : 'string' };
+    return {
+        kind: 'leafList',
+        name,
+        type: f === 'integer' || f === 'float' ? 'number' : f === 'bool' ? 'boolean' : 'string',
+        ...(radix && { radix }),
+    };
+}
+/** The display radix shared by every element, when uniform and non-decimal. */
+function sharedRadix(elements) {
+    const first = elements[0]?.int?.radix ?? 10;
+    if (first === 10)
+        return undefined;
+    return elements.every((e) => (e.int?.radix ?? 10) === first) ? first : undefined;
 }
 function arrayValue(elements) {
     const stringCarry = elements.length > 0 &&

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

@@ -30,6 +30,8 @@ exports.yamlTransformer = {
         const schema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
             : (0, infer_1.inferNodeGroup)(data, options?.rootName);
+        if (!options?.schema && doc.contents)
+            annotateRadix(doc.contents, schema);
         const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
         return { schema: labeled, binding: doc, initialValue: data };
     },
@@ -41,6 +43,67 @@ exports.yamlTransformer = {
     // `satisfies` verifies conformance to the catalog contract while keeping the
     // concrete sync return types, so direct callers need no `await`.
 };
+const RADIX_BY_FORMAT = { BIN: 2, OCT: 8, HEX: 16 };
+/**
+ * Copy non-decimal integer presentation (`0x`/`0o`/`0b` literals) from the
+ * parsed document onto the inferred schema as leaf/leafList `radix` display
+ * hints — the plain-data inference cannot see them, because `toJS()` drops the
+ * scalar format. The revert needs nothing: scalars are mutated in place, so an
+ * edited value re-emits in its literal's own base. Across group-list items the
+ * first non-decimal occurrence wins — one shared item schema cannot vary the
+ * display per item. Schema-driven mode is untouched (JSON Schema has no radix
+ * vocabulary).
+ */
+function annotateRadix(node, schema) {
+    switch (schema.kind) {
+        case 'leaf': {
+            const radix = scalarRadix(node);
+            if (radix && !schema.radix)
+                schema.radix = radix;
+            return;
+        }
+        case 'leafList': {
+            if (!(0, yaml_1.isSeq)(node) || schema.radix)
+                return;
+            const radixes = node.items.map(scalarRadix);
+            if (radixes[0] && radixes.every((r) => r === radixes[0]))
+                schema.radix = radixes[0];
+            return;
+        }
+        case 'nodeGroup': {
+            if (!(0, yaml_1.isMap)(node))
+                return;
+            for (const pair of node.items) {
+                const child = schema.children[pairKey(pair.key)];
+                if (child)
+                    annotateRadix(pair.value, child);
+            }
+            return;
+        }
+        case 'nodeGroupList': {
+            if (!(0, yaml_1.isSeq)(node))
+                return;
+            for (const item of node.items)
+                annotateRadix(item, schema.type);
+            return;
+        }
+        default:
+            return; // choice/map never come out of plain-data inference
+    }
+}
+/** The display radix of a non-decimal integer scalar node, else undefined. */
+function scalarRadix(node) {
+    if (!(0, yaml_1.isScalar)(node))
+        return undefined;
+    if (typeof node.value !== 'number' && typeof node.value !== 'bigint')
+        return undefined;
+    return RADIX_BY_FORMAT[node.format ?? ''];
+}
+/** The string a key node takes as a JS object key, matching `doc.toJS()`. */
+function pairKey(key) {
+    const v = (0, yaml_1.isScalar)(key) ? key.value : key;
+    return v == null ? '' : String(v);
+}
 /**
  * Replace every BigInt from an `intAsBigInt` parse with a form-value scalar: a
  * plain `number` when it fits the safe range, otherwise its decimal string (so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-form-foundry-transformers",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",