ng-form-foundry-transformers 0.2.1

package/dist/transformers/yang/revert.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toFormValue = toFormValue;
+exports.toYangData = toYangData;
+const schema_1 = require("../../core/schema");
+const rfc7951_1 = require("./rfc7951");
+/**
+ * The round-trip between a plain form value and RFC 7951 instance data, driven
+ * entirely by the resolved {@link EffectiveModel} (the server-side binding).
+ *
+ * `toFormValue` strips module qualification and decodes each leaf to the shape
+ * the form renders; `toYangData` re-encodes, keeps list keys as ordinary
+ * members, and drops `config false` state. Neither coerces plain scalar values,
+ * so int64/uint64/decimal64 (carried as strings) keep full precision.
+ *
+ * Per-type wire handling (RFC 7951 §6): `empty` is present as `[null]` /
+ * absent; `bits` is a space-separated flag string modeled as a boolean group;
+ * `identityref` is `module:identity` qualified only across module boundaries.
+ * A `choice` (§7.9) has no wrapper on the wire — the active case's fields are
+ * inline; in the form value it becomes `{ __case, ...fields }`, which this
+ * module flattens on encode and reconstructs on decode.
+ *
+ * Counterpart of the forward `mapToSchema` in `mapper.ts`.
+ */
+/** Sentinel returned by the encoder to mean "omit this member entirely". */
+const OMIT = Symbol('omit');
+/** RFC 7951 JSON instance data → a plain form value keyed by bare names. */
+function toFormValue(rfc7951, model) {
+    return decodeObject(model.roots, asObject(rfc7951), null);
+}
+/** A plain form value → RFC 7951 JSON instance data ready for write-back. */
+function toYangData(value, model) {
+    return encodeObject(model.roots, value, null);
+}
+// --- decode (RFC 7951 -> form) ------------------------------------------------
+function decodeObject(children, raw, parentModule) {
+    const out = {};
+    for (const child of children) {
+        if (child.kind === 'choice') {
+            const decoded = decodeChoice(child, raw, parentModule);
+            if (decoded !== undefined)
+                out[child.name] = decoded;
+        }
+        else {
+            const rawChild = readMember(raw, child, parentModule);
+            if (rawChild !== undefined)
+                out[child.name] = decodeNode(child, rawChild);
+        }
+    }
+    return out;
+}
+function decodeChoice(choice, raw, parentModule) {
+    for (const c of choice.cases) {
+        const fields = c.children.filter((f) => f.kind !== 'choice');
+        if (!fields.some((f) => readMember(raw, f, parentModule) !== undefined))
+            continue;
+        const caseValue = { [schema_1.CASE_KEY]: c.name };
+        for (const f of fields) {
+            const rawF = readMember(raw, f, parentModule);
+            if (rawF !== undefined)
+                caseValue[f.name] = decodeNode(f, rawF);
+        }
+        return caseValue;
+    }
+    return choice.default !== undefined ? { [schema_1.CASE_KEY]: choice.default } : undefined;
+}
+function decodeNode(node, raw) {
+    switch (node.kind) {
+        case 'leaf':
+            return decodeLeaf(node, raw);
+        case 'leaf-list':
+            return Array.isArray(raw) ? [...raw] : raw;
+        case 'container':
+            return decodeObject(node.children, asObject(raw), node.module);
+        case 'list':
+            return (Array.isArray(raw) ? raw : []).map((entry) => decodeObject(node.children, asObject(entry), node.module));
+    }
+}
+function decodeLeaf(node, raw) {
+    switch (node.type.base) {
+        case 'empty':
+            return true;
+        case 'bits': {
+            const set = new Set(typeof raw === 'string' ? raw.split(/\s+/).filter(Boolean) : []);
+            const group = {};
+            for (const bit of node.type.bits ?? [])
+                group[bit] = set.has(bit);
+            return group;
+        }
+        case 'identityref':
+            return typeof raw === 'string' ? (0, rfc7951_1.bareIdentity)(raw) : raw;
+        default:
+            return raw;
+    }
+}
+// --- encode (form -> RFC 7951) ------------------------------------------------
+function encodeObject(children, value, parentModule) {
+    const out = {};
+    for (const child of children) {
+        if (child.kind === 'choice') {
+            encodeChoice(child, value[child.name], parentModule, out);
+            continue;
+        }
+        if (isExcluded(child))
+            continue;
+        const v = value[child.name];
+        if (v === undefined)
+            continue;
+        const encoded = encodeNode(child, v);
+        if (encoded !== OMIT)
+            out[(0, rfc7951_1.qualifiedName)(child.name, child.module, parentModule)] = encoded;
+    }
+    return out;
+}
+function encodeChoice(choice, choiceValue, parentModule, out) {
+    if (!choiceValue || typeof choiceValue !== 'object')
+        return;
+    const caseName = choiceValue[schema_1.CASE_KEY];
+    const active = choice.cases.find((c) => c.name === caseName);
+    if (!active)
+        return;
+    // The active case's fields serialize inline at the choice's location.
+    for (const f of active.children) {
+        if (f.kind === 'choice' || isExcluded(f))
+            continue;
+        const v = choiceValue[f.name];
+        if (v === undefined)
+            continue;
+        const encoded = encodeNode(f, v);
+        if (encoded !== OMIT)
+            out[(0, rfc7951_1.qualifiedName)(f.name, f.module, parentModule)] = encoded;
+    }
+}
+function encodeNode(node, value) {
+    switch (node.kind) {
+        case 'leaf':
+            return encodeLeaf(node, value);
+        case 'leaf-list':
+            return Array.isArray(value) ? [...value] : value;
+        case 'container':
+            return encodeObject(node.children, asObject(value), node.module);
+        case 'list':
+            return (Array.isArray(value) ? value : []).map((entry) => encodeObject(node.children, asObject(entry), node.module));
+    }
+}
+function encodeLeaf(node, value) {
+    switch (node.type.base) {
+        case 'empty':
+            return value ? [null] : OMIT;
+        case 'bits': {
+            const group = asObject(value);
+            return (node.type.bits ?? []).filter((bit) => group[bit]).join(' ');
+        }
+        case 'identityref':
+            return typeof value === 'string' ? (0, rfc7951_1.qualifyIdentity)(value, node.module, node.type) : value;
+        default:
+            return value;
+    }
+}
+// --- helpers ------------------------------------------------------------------
+/** Read a node's value from an RFC 7951 object, tolerating a missing module prefix. */
+function readMember(obj, node, parentModule) {
+    const qualified = (0, rfc7951_1.qualifiedName)(node.name, node.module, parentModule);
+    if (qualified in obj)
+        return obj[qualified];
+    return node.name in obj ? obj[node.name] : undefined;
+}
+function isExcluded(node) {
+    return 'config' in node && node.config === false;
+}
+function asObject(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}

package/dist/transformers/yang/rfc7951.d.ts

@@ -0,0 +1,38 @@
+import { LeafType } from '../../core/schema';
+import { YangBase, YangType } from './model';
+/** Whether a leaf of this base must keep a string form to preserve precision. */
+export declare function isStringEncoded(base: YangBase): boolean;
+/**
+ * Map a resolved YANG type to the form model's four leaf value types.
+ *
+ * - `boolean` and `empty` → boolean (empty is a present/absent checkbox).
+ * - `enumeration` and `identityref` → enum (a dropdown of names).
+ * - the fixed-width integers (int/uint 8..32) → number.
+ * - everything else — string, binary, leafref, instance-identifier, union, and
+ *   the string-encoded int64/uint64/decimal64 — renders as text.
+ *
+ * 64-bit integers and decimal64 map to `'string'` deliberately: a JS `number`
+ * cannot hold them without loss, so they stay strings end to end. `bits` has no
+ * leaf equivalent and is mapped to a group of boolean checkboxes by the mapper,
+ * so it never reaches this function.
+ */
+export declare function toFormLeafType(t: YangType): LeafType;
+/**
+ * RFC 7951 identityref value (§6.8): `module:identity` when the identity is
+ * defined in a different module than the referencing leaf, otherwise the bare
+ * identity name.
+ */
+export declare function qualifyIdentity(name: string, leafModule: string, t: YangType): string;
+/** The local identity name, dropping any `module:` prefix. */
+export declare function bareIdentity(value: string): string;
+/**
+ * RFC 7951 member name for a node (§4). A name is qualified `module:name` when
+ * the node is at the top level (no parent module) or its module differs from its
+ * parent's; otherwise the bare name is used.
+ */
+export declare function qualifiedName(name: string, module: string, parentModule: string | null): string;
+/** Split an RFC 7951 member name into its optional module prefix and local name. */
+export declare function splitQualified(member: string): {
+    module?: string;
+    name: string;
+};

package/dist/transformers/yang/rfc7951.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStringEncoded = isStringEncoded;
+exports.toFormLeafType = toFormLeafType;
+exports.qualifyIdentity = qualifyIdentity;
+exports.bareIdentity = bareIdentity;
+exports.qualifiedName = qualifiedName;
+exports.splitQualified = splitQualified;
+/**
+ * RFC 7951 (JSON Encoding of YANG Data) helpers.
+ *
+ * The two round-trip hazards this module owns: member-name namespace
+ * qualification (§4) and the value encodings that differ from a naive JS mapping
+ * (§6) — notably that int64/uint64/decimal64 are JSON *strings* to avoid IEEE-754
+ * precision loss.
+ */
+/** Base types whose RFC 7951 value is a JSON string, not a number (§6.1). */
+const STRING_ENCODED = new Set([
+    'int64',
+    'uint64',
+    'decimal64',
+]);
+const NUMBER_BASES = new Set([
+    'int8', 'int16', 'int32',
+    'uint8', 'uint16', 'uint32',
+]);
+/** Whether a leaf of this base must keep a string form to preserve precision. */
+function isStringEncoded(base) {
+    return STRING_ENCODED.has(base);
+}
+/**
+ * Map a resolved YANG type to the form model's four leaf value types.
+ *
+ * - `boolean` and `empty` → boolean (empty is a present/absent checkbox).
+ * - `enumeration` and `identityref` → enum (a dropdown of names).
+ * - the fixed-width integers (int/uint 8..32) → number.
+ * - everything else — string, binary, leafref, instance-identifier, union, and
+ *   the string-encoded int64/uint64/decimal64 — renders as text.
+ *
+ * 64-bit integers and decimal64 map to `'string'` deliberately: a JS `number`
+ * cannot hold them without loss, so they stay strings end to end. `bits` has no
+ * leaf equivalent and is mapped to a group of boolean checkboxes by the mapper,
+ * so it never reaches this function.
+ */
+function toFormLeafType(t) {
+    if (t.base === 'boolean' || t.base === 'empty')
+        return 'boolean';
+    if (t.base === 'enumeration' || t.base === 'identityref')
+        return 'enum';
+    if (NUMBER_BASES.has(t.base))
+        return 'number';
+    return 'string';
+}
+/**
+ * RFC 7951 identityref value (§6.8): `module:identity` when the identity is
+ * defined in a different module than the referencing leaf, otherwise the bare
+ * identity name.
+ */
+function qualifyIdentity(name, leafModule, t) {
+    const id = t.identities?.find((i) => i.name === name);
+    return id && id.module !== leafModule ? `${id.module}:${name}` : name;
+}
+/** The local identity name, dropping any `module:` prefix. */
+function bareIdentity(value) {
+    const i = value.indexOf(':');
+    return i === -1 ? value : value.slice(i + 1);
+}
+/**
+ * RFC 7951 member name for a node (§4). A name is qualified `module:name` when
+ * the node is at the top level (no parent module) or its module differs from its
+ * parent's; otherwise the bare name is used.
+ */
+function qualifiedName(name, module, parentModule) {
+    return parentModule === null || module !== parentModule ? `${module}:${name}` : name;
+}
+/** Split an RFC 7951 member name into its optional module prefix and local name. */
+function splitQualified(member) {
+    const i = member.indexOf(':');
+    return i === -1 ? { name: member } : { module: member.slice(0, i), name: member.slice(i + 1) };
+}

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

@@ -0,0 +1,16 @@
+import type { Transformer } from '../../core/transformer';
+import type { YangEngine, CompileRequest } from './engine';
+import type { EffectiveModel } from './model';
+/**
+ * A YANG {@link Transformer} for the catalog: resolves a YANG source through an
+ * engine into a form schema, and reverts the edited value to RFC 7951 data.
+ *
+ * This is the stateless, catalog-conformant view. For caching by `modelId`,
+ * engine-side validation on write-back, and RFC 7951 → form-value conversion,
+ * use the fuller {@link import('./adapter').YangFormAdapter} instead — both sit
+ * on the same engine, {@link mapToSchema}, and {@link toYangData}.
+ *
+ * The `binding` it round-trips is the resolved {@link EffectiveModel}, which the
+ * server keeps and never sends to the form UI.
+ */
+export declare function createYangTransformer(engine: YangEngine): Transformer<CompileRequest, Record<string, unknown>, EffectiveModel, void>;

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

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createYangTransformer = createYangTransformer;
+const mapper_1 = require("./mapper");
+const revert_1 = require("./revert");
+/**
+ * A YANG {@link Transformer} for the catalog: resolves a YANG source through an
+ * engine into a form schema, and reverts the edited value to RFC 7951 data.
+ *
+ * This is the stateless, catalog-conformant view. For caching by `modelId`,
+ * engine-side validation on write-back, and RFC 7951 → form-value conversion,
+ * use the fuller {@link import('./adapter').YangFormAdapter} instead — both sit
+ * on the same engine, {@link mapToSchema}, and {@link toYangData}.
+ *
+ * The `binding` it round-trips is the resolved {@link EffectiveModel}, which the
+ * server keeps and never sends to the form UI.
+ */
+function createYangTransformer(engine) {
+    return {
+        id: 'yang',
+        async toSchema(source) {
+            const binding = await engine.resolve(source);
+            return { schema: (0, mapper_1.mapToSchema)(binding), binding };
+        },
+        toSource(value, binding) {
+            return (0, revert_1.toYangData)(value, binding);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "ng-form-foundry-transformers",
+  "version": "0.2.1",
+  "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",
+    "form",
+    "transformer",
+    "yang",
+    "netconf",
+    "restconf",
+    "rfc7950",
+    "rfc7951",
+    "json-schema",
+    "yaml",
+    "json",
+    "network-management",
+    "typescript"
+  ],
+  "author": "Mathias Santos de Brito",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mathiasbrito/ng-form-foundry.git",
+    "directory": "packages/ng-form-foundry-transformers"
+  },
+  "homepage": "https://ng-form-foundry.readthedocs.io",
+  "bugs": {
+    "url": "https://github.com/mathiasbrito/ng-form-foundry/issues"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "python"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "tsc -p tsconfig.json",
+    "test": "node --test out-tsc/test/*.test.js",
+    "clean": "rm -rf dist out-tsc"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "~5.8.2"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}

package/python/emit_effective_tree.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""Resolve a YANG module with pyang and emit the effective model as JSON.
+
+This is the integration counterpart of the TypeScript ``SubprocessEngine``. It
+uses pyang to parse and validate a module (resolving uses/augment/typedef/
+groupings), then walks pyang's resolved child tree (``i_children``) and prints an
+``EffectiveModel`` matching ``src/model.ts`` to stdout.
+
+Requires pyang on the host: ``pip install pyang``. The JS unit tests do not run
+this — they use ``FakeEngine``. It emits container/list/leaf/leaf-list, choice
+and the built-in types, with keys, config, default, mandatory, and the type
+metadata (enum names, bits, union members, identities, leafref path).
+
+Usage:
+    emit_effective_tree.py --entry <module> --source <dir> [--path <dir> ...] \\
+        [--datastore config|operational]
+"""
+import argparse
+import json
+import sys
+
+from pyang import repository, context, statements
+
+
+def resolved_base(type_stmt):
+    """Follow typedefs to a built-in base type name."""
+    spec = getattr(type_stmt, "i_type_spec", None)
+    if spec is not None and getattr(spec, "name", None):
+        return spec.name
+    # Fall back to walking i_typedef chains, else the literal type argument.
+    td = getattr(type_stmt, "i_typedef", None)
+    while td is not None:
+        inner = td.search_one("type")
+        if inner is None:
+            break
+        nxt = getattr(inner, "i_typedef", None)
+        if nxt is None:
+            return inner.arg
+        td = nxt
+    return type_stmt.arg
+
+
+def build_type(stmt):
+    type_stmt = stmt.search_one("type")
+    if type_stmt is None:
+        return {"base": "string"}
+    return type_info(type_stmt)
+
+
+def type_info(type_stmt):
+    base = resolved_base(type_stmt)
+    out = {"base": base}
+    if base == "enumeration":
+        out["enums"] = [e.arg for e in type_stmt.search("enum")]
+    elif base == "bits":
+        out["bits"] = [b.arg for b in type_stmt.search("bit")]
+    elif base == "union":
+        out["members"] = [type_info(t) for t in type_stmt.search("type")]
+    elif base == "identityref":
+        out["identities"] = collect_identities(type_stmt)
+    elif base == "decimal64":
+        fd = type_stmt.search_one("fraction-digits")
+        if fd is not None:
+            out["fractionDigits"] = int(fd.arg)
+    elif base == "leafref":
+        path = type_stmt.search_one("path")
+        if path is not None:
+            out["leafrefPath"] = path.arg
+    return out
+
+
+def collect_identities(type_stmt):
+    """Derived identities for an identityref, each tagged with its module.
+
+    Best-effort against pyang internals (``i_identity.i_derived``).
+    """
+    result = []
+    base = type_stmt.search_one("base")
+    identity = getattr(base, "i_identity", None) if base is not None else None
+    derived = getattr(identity, "i_derived", None) if identity is not None else None
+    for ident in derived or []:
+        result.append({"name": ident.arg, "module": ident.i_module.i_modulename})
+    return result
+
+
+def module_name(stmt):
+    mod = getattr(stmt, "i_module", None)
+    return mod.i_modulename if mod is not None else stmt.main_module().arg
+
+
+def is_config(stmt):
+    # pyang sets i_config on data nodes after validation.
+    val = getattr(stmt, "i_config", None)
+    return True if val is None else bool(val)
+
+
+def walk(stmt):
+    kw = stmt.keyword
+    common = {"name": stmt.arg, "module": module_name(stmt), "config": is_config(stmt)}
+
+    if kw == "leaf":
+        node = {"kind": "leaf", **common, "type": build_type(stmt)}
+        if stmt.search_one("mandatory", "true") is not None:
+            node["mandatory"] = True
+        default = stmt.search_one("default")
+        if default is not None:
+            node["default"] = default.arg
+        return node
+
+    if kw == "leaf-list":
+        node = {"kind": "leaf-list", **common, "type": build_type(stmt)}
+        return node
+
+    if kw == "container":
+        node = {"kind": "container", **common, "children": walk_children(stmt)}
+        if stmt.search_one("presence") is not None:
+            node["presence"] = True
+        return node
+
+    if kw == "list":
+        key = stmt.search_one("key")
+        node = {
+            "kind": "list",
+            **common,
+            "keys": key.arg.split() if key is not None else [],
+            "children": walk_children(stmt),
+        }
+        return node
+
+    if kw == "choice":
+        cases = []
+        for case in getattr(stmt, "i_children", []):
+            if case.keyword == "case":
+                cases.append({"name": case.arg, "children": walk_children(case)})
+            else:
+                # shorthand case: a single data node directly under the choice
+                child = walk(case)
+                if child is not None:
+                    cases.append({"name": case.arg, "children": [child]})
+        node = {"kind": "choice", "name": stmt.arg, "module": module_name(stmt), "cases": cases}
+        default = stmt.search_one("default")
+        if default is not None:
+            node["default"] = default.arg
+        if stmt.search_one("mandatory", "true") is not None:
+            node["mandatory"] = True
+        return node
+
+    return None  # anydata/anyxml are not emitted
+
+
+def walk_children(stmt):
+    out = []
+    for child in getattr(stmt, "i_children", []):
+        node = walk(child)
+        if node is not None:
+            out.append(node)
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--entry", required=True)
+    ap.add_argument("--source", required=True)
+    ap.add_argument("--path", action="append", default=[])
+    ap.add_argument("--datastore", default="config", choices=["config", "operational"])
+    args = ap.parse_args()
+
+    repo = repository.FileRepository(":".join([args.source, *args.path]))
+    ctx = context.Context(repo)
+    module = ctx.search_module(0, args.entry)
+    if module is None:
+        with open_module(ctx, args.entry, args.source) as text:
+            module = ctx.add_module(args.entry, text)
+    statements.validate_module(ctx, module)
+    if ctx.errors:
+        for _pos, tag, arg in ctx.errors:
+            print(f"pyang: {tag} {arg}", file=sys.stderr)
+        sys.exit(1)
+
+    roots = walk_children(module)
+    if args.datastore == "config":
+        roots = strip_state(roots)
+
+    model = {
+        "modules": [{"name": module.i_modulename, "namespace": namespace(module)}],
+        "roots": roots,
+    }
+    json.dump(model, sys.stdout)
+
+
+def strip_state(nodes):
+    kept = []
+    for n in nodes:
+        if n.get("config") is False:
+            continue
+        if "children" in n:
+            n["children"] = strip_state(n["children"])
+        for case in n.get("cases", []):
+            case["children"] = strip_state(case["children"])
+        kept.append(n)
+    return kept
+
+
+def namespace(module):
+    ns = module.search_one("namespace")
+    return ns.arg if ns is not None else ""
+
+
+def open_module(ctx, name, source):
+    import glob
+    import os
+    from contextlib import contextmanager
+
+    @contextmanager
+    def _open():
+        matches = glob.glob(os.path.join(source, f"{name}*.yang"))
+        if not matches:
+            print(f"module '{name}' not found in {source}", file=sys.stderr)
+            sys.exit(1)
+        with open(matches[0], "r", encoding="utf-8") as fh:
+            yield fh.read()
+
+    return _open()
+
+
+if __name__ == "__main__":
+    main()