ng-form-foundry-transformers 0.2.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mathias Santos de Brito
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,186 @@
+# ng-form-foundry-transformers
+
+A catalog of **source-format transformers** for
+[ng-form-foundry](https://ng-form-foundry.readthedocs.io): turn a model or config
+into a schema your Angular app can render, then revert the edited form value back
+to the source format.
+
+Framework-agnostic **Node + TypeScript** — no framework imports. NestJS is the
+likely host, but the library assumes only Node; wire it into Express, a worker,
+or a CLI just as easily.
+
+## Transformers
+
+| id | Source | Reverts to | Status |
+| --- | --- | --- | --- |
+| `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 |
+
+The YAML and JSON transformers share the same format-agnostic form builders in
+`core` (`inferNodeGroup`, `jsonSchemaToNodeGroup`) — a JSON Schema is an *option*
+to either, not a transformer of its own.
+
+## The contract
+
+Every format implements one `Transformer`, so a single catalog can turn any of
+them into a form and write the edited value back. Look one up by `id` through a
+`TransformerRegistry`, or import the one you need directly (tree-shakeable).
+
+```ts
+interface Transformer<TSource, TData = TSource, TBinding = BindingMap, TOptions = void> {
+  readonly id: string;
+  // source → form schema (+ revert context, and any initial value)
+  toSchema(source: TSource, options?: TOptions): MaybePromise<{
+    schema: NodeGroup; binding: TBinding; initialValue?: FormValue;
+  }>;
+  // edited form value → source data, using the binding from toSchema
+  toSource(value: FormValue, binding: TBinding): MaybePromise<TData>;
+}
+```
+
+For config formats (YAML, JSON) the thing you load and save is the same document
+type, so `TData` defaults to `TSource`. Schema formats differ: YANG's `toSchema`
+consumes a model source but its `toSource` reverts to RFC 7951 *data*.
+
+## YAML transformer
+
+Edit a **YAML config file**: turn it into a form, then write the edited value
+back to YAML with comments, key order, and formatting preserved. Pass a JSON
+Schema to drive types/required/enums, or omit it to infer the form from the data.
+
+```ts
+import { yamlTransformer } from 'ng-form-foundry-transformers';
+
+const yaml = `# upstream API
+host: localhost   # dev only
+port: 8080
+`;
+
+// forward: infer a form schema (+ initial value) from the config
+const { schema, binding, initialValue } = yamlTransformer.toSchema(yaml);
+//   schema      → NodeGroup the Angular app renders with buildFormFromSchema
+//   initialValue → { host: 'localhost', port: 8080 }
+
+// reverse: write the edited value back — comments survive
+const out = yamlTransformer.toSource({ ...initialValue, port: 9090 }, binding);
+//   # upstream API
+//   host: localhost   # dev only
+//   port: 9090
+```
+
+With a JSON Schema: `yamlTransformer.toSchema(yaml, { schema })` — `object` →
+nodeGroup, `array` of objects → nodeGroupList, scalar `enum` → enum leaf,
+`required`/`title`/`default` carried onto the leaves.
+
+## JSON transformer
+
+Same as YAML, for **JSON config files** — `jsonTransformer.toSchema(json, { schema? })`
+and `toSource(value, binding)`. Revert re-serializes with the source's indent width
+and trailing newline preserved. Standard JSON has no comments; for JSON **with**
+comments (JSONC), use the YAML transformer instead (`JSON.parse` rejects comments).
+
+```ts
+import { jsonTransformer } from 'ng-form-foundry-transformers';
+
+const { schema, binding, initialValue } = jsonTransformer.toSchema(configText);
+const out = jsonTransformer.toSource({ ...initialValue, replicas: 5 }, binding);
+```
+
+## YANG transformer
+
+Turn a **YANG** model into an ng-form-foundry schema, then revert the edited form
+value back to **RFC 7951** instance data for write-back to a NETCONF/RESTCONF
+datastore. Use the fuller `YangFormAdapter` when you want caching by `modelId`,
+engine-side validation, and RFC 7951 → form-value conversion:
+
+```ts
+import { YangFormAdapter, SubprocessEngine } from 'ng-form-foundry-transformers';
+
+const adapter = new YangFormAdapter(new SubprocessEngine());
+
+// resolve a device model once (cached by modelId)
+await adapter.compile({
+  modelId: 'acme-router@2026-01-01',
+  entryModule: 'ietf-interfaces',
+  source: { kind: 'dir', path: './yang' },
+});
+
+// forward: hand the Angular app a NodeGroup it renders with buildFormFromSchema
+const schema = await adapter.getFormSchema('acme-router@2026-01-01');
+
+// load the device's current config into a plain form value
+const value = await adapter.toFormValue(deviceGetResponse, 'acme-router@2026-01-01');
+
+// reverse: the edited form value → RFC 7951 JSON, ready for a RESTCONF PUT
+const rfc7951 = await adapter.toYangData(editedValue, 'acme-router@2026-01-01');
+```
+
+Or use the catalog-conformant `createYangTransformer(engine)` for the plain
+`Transformer` view (no caching/validation).
+
+### What it does
+
+- **Forward** — maps a resolved YANG tree to an ng-form-foundry `NodeGroup`
+  (`container` → nodeGroup, `list` → nodeGroupList, `leaf`/`leaf-list` → leaf/leafList).
+- **Reverse** — reconstructs RFC 7951 JSON from a plain form value, restoring
+  module-namespaced member names, list keys, and — critically —
+  `int64`/`uint64`/`decimal64` as **strings** so precision survives. `config false`
+  state is shown for context but dropped from write-back.
+- **Binding stays server-side** — the frontend only ever sees the `NodeGroup`
+  schema and returns a plain value; the resolved YANG model (the "binding") never
+  leaves the adapter.
+
+### Engines
+
+The only part that touches YANG semantics or the environment is the injected
+`YangEngine`:
+
+- **`SubprocessEngine`** (recommended) shells out to the bundled Python helper,
+  which wraps **pyang** to resolve `uses`/`augment`/`typedef` and emit a
+  normalized effective tree. Requires Python + `pip install pyang` on the host.
+- **`FakeEngine`** serves pre-resolved models — used in tests and local dev, no
+  Python required.
+
+Caching is pluggable (`ArtifactCache`; an `InMemoryCache` ships by default).
+
+### Leaf and structural type coverage
+
+| YANG type | Form control | Notes |
+| --- | --- | --- |
+| `string`, `boolean`, int/uint 8–32 | text / checkbox / number | direct |
+| `int64`, `uint64`, `decimal64` | text | kept as strings (precision-safe) |
+| `enumeration`, `identityref` | enum (dropdown) | identityref re-qualified across modules |
+| `empty` | checkbox | `[null]` when set, omitted when not |
+| `bits` | group of checkboxes | reverts to the space-separated set |
+| `binary`, `instance-identifier`, `leafref`, `union` | text | member types / leafref path kept in the binding |
+
+Plain `container` → nodeGroup; **presence** `container` → nodeGroup flagged
+`presence: true` (on/off toggle; present-but-empty round-trips as `{}`, absent is
+omitted). **`choice`/`case`** → a `Choice` node: the form value carries
+`{ __case, ...fields }` and the adapter flattens it to the inline YANG encoding on
+write-back. `must`/`when` cross-field validity is left to server-side validation.
+
+### Using it from NestJS
+
+The core is a plain class, so a NestJS provider is a thin wrapper — see
+[`examples/nestjs-provider.ts`](examples/nestjs-provider.ts).
+
+## Develop
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm test        # node:test on the compiled output (no Python needed)
+```
+
+## Status
+
+`0.2.1` — first release under this name (formerly `yang-form-foundry`),
+restructured into a transformer catalog. YANG, YAML, and JSON transformers are
+complete; YAML and JSON share the format-agnostic form builders in `core` and are
+JSON-Schema-driven or inferred.
+
+## License
+
+Apache-2.0 © Mathias Santos de Brito

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Format-agnostic core of the transformer catalog: the {@link Transformer}
+ * contract every format implements, the {@link TransformerRegistry} for runtime
+ * lookup, the ng-form-foundry schema types that are the shared target of all
+ * transformers, and the shared schema builders (infer a form from plain data, or
+ * map a JSON Schema) that any data-oriented transformer reuses.
+ */
+export type { Transformer, TransformResult, BindingMap } from './transformer';
+export { TransformerRegistry } from './registry';
+export { inferNodeGroup } from './infer';
+export { jsonSchemaToNodeGroup } from './json-schema';
+export type { JsonSchema } from './json-schema';
+export type { NodeGroup, NodeType, Leaf, LeafList, NodeGroupList, Choice, LeafType, FormValue, } from './schema';
+export { CASE_KEY } from './schema';

package/dist/core/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Format-agnostic core of the transformer catalog: the {@link Transformer}
+ * contract every format implements, the {@link TransformerRegistry} for runtime
+ * lookup, the ng-form-foundry schema types that are the shared target of all
+ * transformers, and the shared schema builders (infer a form from plain data, or
+ * map a JSON Schema) that any data-oriented transformer reuses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CASE_KEY = exports.jsonSchemaToNodeGroup = exports.inferNodeGroup = exports.TransformerRegistry = void 0;
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "TransformerRegistry", { enumerable: true, get: function () { return registry_1.TransformerRegistry; } });
+// Shared schema builders — used by the YAML and JSON transformers alike.
+var infer_1 = require("./infer");
+Object.defineProperty(exports, "inferNodeGroup", { enumerable: true, get: function () { return infer_1.inferNodeGroup; } });
+var json_schema_1 = require("./json-schema");
+Object.defineProperty(exports, "jsonSchemaToNodeGroup", { enumerable: true, get: function () { return json_schema_1.jsonSchemaToNodeGroup; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "CASE_KEY", { enumerable: true, get: function () { return schema_1.CASE_KEY; } });

package/dist/core/infer.d.ts

@@ -0,0 +1,15 @@
+import type { NodeGroup } from './schema';
+/**
+ * Infer a root {@link NodeGroup} from a parsed data object when no schema is
+ * given. Structure and types come from the values themselves:
+ *
+ *   - object            → nodeGroup (recursed)
+ *   - array of objects  → nodeGroupList (item schema = union of the items' keys)
+ *   - array of scalars  → leafList (element type from the first element)
+ *   - scalar            → typed leaf (string / number / boolean)
+ *
+ * `null` and empty/mixed arrays fall back to `string`, since a value alone can't
+ * declare an enum, a constraint, or an empty array's element type. Pass a JSON
+ * Schema to {@link import('./json-schema').jsonSchemaToNodeGroup} for richer output.
+ */
+export declare function inferNodeGroup(data: Record<string, unknown>, name?: string): NodeGroup;

package/dist/core/infer.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferNodeGroup = inferNodeGroup;
+const ROOT = '__root__';
+/**
+ * Infer a root {@link NodeGroup} from a parsed data object when no schema is
+ * given. Structure and types come from the values themselves:
+ *
+ *   - object            → nodeGroup (recursed)
+ *   - array of objects  → nodeGroupList (item schema = union of the items' keys)
+ *   - array of scalars  → leafList (element type from the first element)
+ *   - scalar            → typed leaf (string / number / boolean)
+ *
+ * `null` and empty/mixed arrays fall back to `string`, since a value alone can't
+ * declare an enum, a constraint, or an empty array's element type. Pass a JSON
+ * Schema to {@link import('./json-schema').jsonSchemaToNodeGroup} for richer output.
+ */
+function inferNodeGroup(data, name = ROOT) {
+    const group = objectToNodeGroup(data, name);
+    group.root = true;
+    return group;
+}
+function objectToNodeGroup(data, name) {
+    const children = {};
+    for (const [key, value] of Object.entries(data)) {
+        children[key] = inferNode(key, value);
+    }
+    return { kind: 'nodeGroup', name, children };
+}
+function inferNode(name, value) {
+    if (Array.isArray(value))
+        return inferArray(name, value);
+    if (isPlainObject(value))
+        return objectToNodeGroup(value, name);
+    return { kind: 'leaf', name, type: scalarType(value) };
+}
+function inferArray(name, items) {
+    const objects = items.filter(isPlainObject);
+    if (objects.length && objects.length === items.length) {
+        return { kind: 'nodeGroupList', name, type: objectToNodeGroup(unionKeys(objects), name) };
+    }
+    // array of scalars (or empty / mixed → string fallback)
+    const first = items.find((v) => !isPlainObject(v) && !Array.isArray(v));
+    return { kind: 'leafList', name, type: scalarType(first) };
+}
+/** A representative object with every key seen across `items`, each mapped to the first non-null sample. */
+function unionKeys(items) {
+    const merged = {};
+    for (const item of items) {
+        for (const [key, value] of Object.entries(item)) {
+            if (!(key in merged) || (merged[key] == null && value != null))
+                merged[key] = value;
+        }
+    }
+    return merged;
+}
+/** Infer a form {@link LeafType} from a scalar value (default `string`). */
+function scalarType(value) {
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'number')
+        return 'number';
+    return 'string';
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

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

@@ -0,0 +1,26 @@
+import type { NodeGroup } from './schema';
+/**
+ * The subset of JSON Schema (draft-07 style) this transformer maps to a form.
+ * Only the keywords that shape a form are read; anything else is ignored. No
+ * validation is performed — the schema drives *structure and types*, not
+ * constraint checking (that stays server-side).
+ */
+export interface JsonSchema {
+    type?: JsonSchemaType | JsonSchemaType[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    title?: string;
+    default?: unknown;
+}
+type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+/**
+ * Map a JSON Schema whose top level is an object into a root {@link NodeGroup}.
+ * `object` → nodeGroup, `array` of objects → nodeGroupList, `array` of scalars →
+ * leafList, a scalar with `enum` → enum leaf, other scalars → typed leaf.
+ * `required` marks child leaves, `title` becomes the label, `default` carries a
+ * scalar default.
+ */
+export declare function jsonSchemaToNodeGroup(schema: JsonSchema, name?: string): NodeGroup;
+export {};

package/dist/core/json-schema.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonSchemaToNodeGroup = jsonSchemaToNodeGroup;
+const ROOT = '__root__';
+/**
+ * Map a JSON Schema whose top level is an object into a root {@link NodeGroup}.
+ * `object` → nodeGroup, `array` of objects → nodeGroupList, `array` of scalars →
+ * leafList, a scalar with `enum` → enum leaf, other scalars → typed leaf.
+ * `required` marks child leaves, `title` becomes the label, `default` carries a
+ * scalar default.
+ */
+function jsonSchemaToNodeGroup(schema, name = ROOT) {
+    const group = objectToNodeGroup(schema, name, schema.title);
+    group.root = true;
+    return group;
+}
+function objectToNodeGroup(schema, name, 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));
+    }
+    const group = { kind: 'nodeGroup', name, children };
+    if (label)
+        group.label = label;
+    return group;
+}
+function schemaToNode(name, schema, required) {
+    const type = primaryType(schema);
+    if (type === 'object') {
+        return objectToNodeGroup(schema, name, schema.title);
+    }
+    if (type === 'array') {
+        const items = schema.items ?? {};
+        if (primaryType(items) === 'object') {
+            const node = {
+                kind: 'nodeGroupList',
+                name,
+                type: objectToNodeGroup(items, name, items.title),
+            };
+            if (schema.title)
+                node.label = schema.title;
+            return node;
+        }
+        const list = { kind: 'leafList', name, type: scalarType(items) };
+        if (schema.title)
+            list.label = schema.title;
+        return list;
+    }
+    // scalar leaf (possibly an enum)
+    const leaf = { kind: 'leaf', name, type: scalarType(schema) };
+    if (schema.enum && schema.enum.length) {
+        leaf.type = 'enum';
+        leaf.enum = schema.enum.filter((v) => typeof v === 'string' || typeof v === 'number');
+    }
+    if (required)
+        leaf.required = true;
+    if (isScalar(schema.default))
+        leaf.default = schema.default;
+    if (schema.title)
+        leaf.label = schema.title;
+    return leaf;
+}
+/** The first declared type, ignoring a `null` companion in a `[T, 'null']` union. */
+function primaryType(schema) {
+    const t = schema.type;
+    if (Array.isArray(t))
+        return t.find((x) => x !== 'null');
+    return t;
+}
+/** Map a JSON Schema scalar type to a form {@link LeafType} (default `string`). */
+function scalarType(schema) {
+    if (schema.enum && schema.enum.length)
+        return 'enum';
+    switch (primaryType(schema)) {
+        case 'boolean':
+            return 'boolean';
+        case 'number':
+        case 'integer':
+            return 'number';
+        default:
+            return 'string';
+    }
+}
+function isScalar(v) {
+    return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
+}

package/dist/core/registry.d.ts

@@ -0,0 +1,18 @@
+import type { Transformer } from './transformer';
+/**
+ * A lookup of {@link Transformer}s by their `id`. Lets a consumer pick a format
+ * at runtime (`registry.get('yaml')`) instead of importing each transformer
+ * directly. Direct imports remain available and tree-shakeable for consumers
+ * that only need one format.
+ */
+export declare class TransformerRegistry {
+    private readonly byId;
+    /** Register a transformer under its `id`. Throws if the `id` is already taken. */
+    register(transformer: Transformer<any, any, any, any>): this;
+    /** Get a transformer by `id`, or `undefined` if none is registered. */
+    get(id: string): Transformer<any, any, any, any> | undefined;
+    /** Get a transformer by `id`, throwing a listing of known ids if absent. */
+    require(id: string): Transformer<any, any, any, any>;
+    /** The ids of all registered transformers. */
+    ids(): string[];
+}