ng-form-foundry-transformers 0.2.1

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

@@ -0,0 +1,18 @@
+import { CompiledModel } from './model';
+/**
+ * Pluggable store for compiled models, keyed by a caller-chosen id (typically a
+ * hash of the yang-library so the cache invalidates when the device's module
+ * set changes). Swap the in-memory default for Redis or similar in production.
+ */
+export interface ArtifactCache {
+    get(key: string): Promise<CompiledModel | undefined>;
+    set(key: string, model: CompiledModel): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** A process-local {@link ArtifactCache}. Fine for a single instance; not shared across replicas. */
+export declare class InMemoryCache implements ArtifactCache {
+    private readonly store;
+    get(key: string): Promise<CompiledModel | undefined>;
+    set(key: string, model: CompiledModel): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/transformers/yang/cache.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryCache = void 0;
+/** A process-local {@link ArtifactCache}. Fine for a single instance; not shared across replicas. */
+class InMemoryCache {
+    constructor() {
+        this.store = new Map();
+    }
+    async get(key) {
+        return this.store.get(key);
+    }
+    async set(key, model) {
+        this.store.set(key, model);
+    }
+    async delete(key) {
+        this.store.delete(key);
+    }
+}
+exports.InMemoryCache = InMemoryCache;

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

@@ -0,0 +1,41 @@
+import { EffectiveModel } from './model';
+/**
+ * A request to resolve a YANG module set into an {@link EffectiveModel}.
+ *
+ * `source` locates the raw `.yang` files (a directory, or an in-memory map of
+ * module name → text). `yangLibrary` pins exactly which modules, revisions,
+ * features, and deviations are in effect (RFC 8525 ietf-yang-library), so the
+ * resolved model matches the target datastore. `datastore` selects whether
+ * `config false` state nodes are included.
+ */
+export interface CompileRequest {
+    entryModule: string;
+    source: YangSource;
+    yangLibrary?: unknown;
+    datastore?: 'config' | 'operational';
+}
+export type YangSource = {
+    kind: 'dir';
+    path: string;
+} | {
+    kind: 'inline';
+    modules: Record<string, string>;
+};
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * The pluggable YANG engine — the only part of the adapter that touches YANG
+ * semantics or the environment.
+ *
+ * Implementations resolve a module set into an {@link EffectiveModel} and
+ * validate RFC 7951 instance data against it. The recommended implementation
+ * shells out to pyang/yangson (`SubprocessEngine`); tests use `FakeEngine`.
+ * Keeping this an interface is what lets the adapter stay framework- and
+ * tooling-agnostic.
+ */
+export interface YangEngine {
+    resolve(req: CompileRequest): Promise<EffectiveModel>;
+    validate(data: unknown, model: EffectiveModel): Promise<ValidationResult>;
+}

package/dist/transformers/yang/engine.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/transformers/yang/engines/fake-engine.d.ts

@@ -0,0 +1,15 @@
+import { CompileRequest, ValidationResult, YangEngine } from '../engine';
+import { EffectiveModel } from '../model';
+/**
+ * A {@link YangEngine} backed by pre-resolved effective models, keyed by entry
+ * module name. Used in tests and for local development so the adapter runs
+ * without a Python toolchain. An optional `validator` lets a test assert the
+ * validation branch; by default validation always passes.
+ */
+export declare class FakeEngine implements YangEngine {
+    private readonly models;
+    private readonly validator?;
+    constructor(models: Record<string, EffectiveModel>, validator?: ((data: unknown, model: EffectiveModel) => ValidationResult) | undefined);
+    resolve(req: CompileRequest): Promise<EffectiveModel>;
+    validate(data: unknown, model: EffectiveModel): Promise<ValidationResult>;
+}

package/dist/transformers/yang/engines/fake-engine.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeEngine = void 0;
+/**
+ * A {@link YangEngine} backed by pre-resolved effective models, keyed by entry
+ * module name. Used in tests and for local development so the adapter runs
+ * without a Python toolchain. An optional `validator` lets a test assert the
+ * validation branch; by default validation always passes.
+ */
+class FakeEngine {
+    constructor(models, validator) {
+        this.models = models;
+        this.validator = validator;
+    }
+    async resolve(req) {
+        const model = this.models[req.entryModule];
+        if (!model) {
+            throw new Error(`FakeEngine has no effective model for entry module '${req.entryModule}'`);
+        }
+        return model;
+    }
+    async validate(data, model) {
+        return this.validator ? this.validator(data, model) : { valid: true, errors: [] };
+    }
+}
+exports.FakeEngine = FakeEngine;

package/dist/transformers/yang/engines/subprocess-engine.d.ts

@@ -0,0 +1,30 @@
+import { CompileRequest, ValidationResult, YangEngine } from '../engine';
+import { EffectiveModel } from '../model';
+export interface SubprocessEngineOptions {
+    /** Python interpreter. Defaults to `python3`. */
+    python?: string;
+    /** Directory holding the bundled helper scripts. Defaults to the packaged `python/`. */
+    scriptDir?: string;
+    /** Extra `--path` entries passed to the resolver for imported modules. */
+    yangPath?: string[];
+}
+/**
+ * A {@link YangEngine} that resolves and validates by shelling out to the
+ * bundled Python helpers, which wrap pyang/yangson (the maintained YANG
+ * toolchain). Requires Python plus `pyang` and `yangson` on the host — ship them
+ * in the deployment image, or run this behind a sidecar.
+ *
+ * `resolve` runs `emit_effective_tree.py` and parses its JSON as an
+ * {@link EffectiveModel}. `validate` is currently a no-op — full RFC 7951
+ * validation with yangson needs the target's yang-library.
+ * Counterpart of `FakeEngine`, which serves canned models for tests.
+ */
+export declare class SubprocessEngine implements YangEngine {
+    private readonly python;
+    private readonly scriptDir;
+    private readonly yangPath;
+    constructor(opts?: SubprocessEngineOptions);
+    resolve(req: CompileRequest): Promise<EffectiveModel>;
+    validate(_data: unknown, _model: EffectiveModel): Promise<ValidationResult>;
+    private run;
+}

package/dist/transformers/yang/engines/subprocess-engine.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubprocessEngine = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+/**
+ * A {@link YangEngine} that resolves and validates by shelling out to the
+ * bundled Python helpers, which wrap pyang/yangson (the maintained YANG
+ * toolchain). Requires Python plus `pyang` and `yangson` on the host — ship them
+ * in the deployment image, or run this behind a sidecar.
+ *
+ * `resolve` runs `emit_effective_tree.py` and parses its JSON as an
+ * {@link EffectiveModel}. `validate` is currently a no-op — full RFC 7951
+ * validation with yangson needs the target's yang-library.
+ * Counterpart of `FakeEngine`, which serves canned models for tests.
+ */
+class SubprocessEngine {
+    constructor(opts = {}) {
+        this.python = opts.python ?? 'python3';
+        // Compiled to dist/transformers/yang/engines/; the bundled python/ sits at
+        // the package root, four levels up.
+        this.scriptDir = opts.scriptDir ?? (0, node_path_1.join)(__dirname, '..', '..', '..', '..', 'python');
+        this.yangPath = opts.yangPath ?? [];
+    }
+    async resolve(req) {
+        if (req.source.kind !== 'dir') {
+            throw new Error('SubprocessEngine currently supports only { kind: "dir" } sources');
+        }
+        const args = [
+            (0, node_path_1.join)(this.scriptDir, 'emit_effective_tree.py'),
+            '--entry', req.entryModule,
+            '--source', req.source.path,
+            '--datastore', req.datastore ?? 'config',
+            ...this.yangPath.flatMap((p) => ['--path', p]),
+        ];
+        const stdout = await this.run(args);
+        return JSON.parse(stdout);
+    }
+    async validate(_data, _model) {
+        // No-op: RFC 7951 validation via yangson requires the target's yang-library.
+        return { valid: true, errors: [] };
+    }
+    run(args, stdin) {
+        return new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)(this.python, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+            let out = '';
+            let err = '';
+            child.stdout.on('data', (d) => (out += d));
+            child.stderr.on('data', (d) => (err += d));
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve(out);
+                else
+                    reject(new Error(`${this.python} exited ${code}: ${err.trim()}`));
+            });
+            if (stdin !== undefined)
+                child.stdin.end(stdin);
+            else
+                child.stdin.end();
+        });
+    }
+}
+exports.SubprocessEngine = SubprocessEngine;

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

@@ -0,0 +1,20 @@
+/**
+ * YANG transformer — turn a YANG model into an ng-form-foundry schema and revert
+ * the edited form value back to RFC 7951 instance data.
+ *
+ * {@link createYangTransformer} is the catalog-conformant entry point;
+ * {@link YangFormAdapter} is the fuller stateful orchestrator (caching,
+ * engine-side validation, RFC 7951 → form-value conversion).
+ */
+export { createYangTransformer } from './yang-transformer';
+export { YangFormAdapter, YangValidationError } from './adapter';
+export type { CompileOptions } from './adapter';
+export type { YangEngine, CompileRequest, YangSource, ValidationResult } from './engine';
+export { SubprocessEngine } from './engines/subprocess-engine';
+export type { SubprocessEngineOptions } from './engines/subprocess-engine';
+export { FakeEngine } from './engines/fake-engine';
+export { InMemoryCache } from './cache';
+export type { ArtifactCache } from './cache';
+export { mapToSchema } from './mapper';
+export { toFormValue, toYangData } from './revert';
+export type { EffectiveModel, CompiledModel, EffNode, EffLeaf, EffLeafList, EffContainer, EffList, YangType, YangBase, ModuleInfo, } from './model';

package/dist/transformers/yang/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * YANG transformer — turn a YANG model into an ng-form-foundry schema and revert
+ * the edited form value back to RFC 7951 instance data.
+ *
+ * {@link createYangTransformer} is the catalog-conformant entry point;
+ * {@link YangFormAdapter} is the fuller stateful orchestrator (caching,
+ * engine-side validation, RFC 7951 → form-value conversion).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toYangData = exports.toFormValue = exports.mapToSchema = exports.InMemoryCache = exports.FakeEngine = exports.SubprocessEngine = exports.YangValidationError = exports.YangFormAdapter = exports.createYangTransformer = void 0;
+var yang_transformer_1 = require("./yang-transformer");
+Object.defineProperty(exports, "createYangTransformer", { enumerable: true, get: function () { return yang_transformer_1.createYangTransformer; } });
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "YangFormAdapter", { enumerable: true, get: function () { return adapter_1.YangFormAdapter; } });
+Object.defineProperty(exports, "YangValidationError", { enumerable: true, get: function () { return adapter_1.YangValidationError; } });
+var subprocess_engine_1 = require("./engines/subprocess-engine");
+Object.defineProperty(exports, "SubprocessEngine", { enumerable: true, get: function () { return subprocess_engine_1.SubprocessEngine; } });
+var fake_engine_1 = require("./engines/fake-engine");
+Object.defineProperty(exports, "FakeEngine", { enumerable: true, get: function () { return fake_engine_1.FakeEngine; } });
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "InMemoryCache", { enumerable: true, get: function () { return cache_1.InMemoryCache; } });
+var mapper_1 = require("./mapper");
+Object.defineProperty(exports, "mapToSchema", { enumerable: true, get: function () { return mapper_1.mapToSchema; } });
+var revert_1 = require("./revert");
+Object.defineProperty(exports, "toFormValue", { enumerable: true, get: function () { return revert_1.toFormValue; } });
+Object.defineProperty(exports, "toYangData", { enumerable: true, get: function () { return revert_1.toYangData; } });

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

@@ -0,0 +1,14 @@
+import { EffectiveModel } from './model';
+import { NodeGroup } from '../../core/schema';
+/**
+ * Derive the frontend `NodeGroup` schema from a resolved {@link EffectiveModel}.
+ *
+ * container → nodeGroup (presence containers flagged `presence`), list →
+ * nodeGroupList, leaf-list → leafList, choice → a `Choice` node, and leaf → leaf
+ * (with `bits` becoming a group of boolean checkboxes and identityref/enum
+ * carrying their options). Wire-encoding concerns stay in the binding (the
+ * effective model); this output is the pure render contract handed to the app.
+ *
+ * Counterpart of the revert in `revert.ts`, which walks the same effective model.
+ */
+export declare function mapToSchema(model: EffectiveModel): NodeGroup;

package/dist/transformers/yang/mapper.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapToSchema = mapToSchema;
+const rfc7951_1 = require("./rfc7951");
+/**
+ * Derive the frontend `NodeGroup` schema from a resolved {@link EffectiveModel}.
+ *
+ * container → nodeGroup (presence containers flagged `presence`), list →
+ * nodeGroupList, leaf-list → leafList, choice → a `Choice` node, and leaf → leaf
+ * (with `bits` becoming a group of boolean checkboxes and identityref/enum
+ * carrying their options). Wire-encoding concerns stay in the binding (the
+ * effective model); this output is the pure render contract handed to the app.
+ *
+ * Counterpart of the revert in `revert.ts`, which walks the same effective model.
+ */
+function mapToSchema(model) {
+    return {
+        kind: 'nodeGroup',
+        name: '__root__',
+        root: true,
+        children: mapChildren(model.roots),
+    };
+}
+function mapChildren(nodes) {
+    const children = {};
+    for (const node of nodes) {
+        children[node.name] = mapNode(node);
+    }
+    return children;
+}
+function mapNode(node) {
+    switch (node.kind) {
+        case 'leaf': {
+            // `bits` has no scalar form control; render it as a group of checkboxes,
+            // one boolean per flag. The revert collapses the group back to the wire
+            // string.
+            if (node.type.base === 'bits' && node.type.bits) {
+                return bitsGroup(node, node.type.bits);
+            }
+            const leaf = { kind: 'leaf', name: node.name, type: (0, rfc7951_1.toFormLeafType)(node.type) };
+            if (node.mandatory)
+                leaf.required = true;
+            if (node.default !== undefined)
+                leaf.default = node.default;
+            const options = node.type.enums ?? node.type.identities?.map((i) => i.name);
+            if (options)
+                leaf.enum = [...options];
+            return leaf;
+        }
+        case 'leaf-list': {
+            const list = { kind: 'leafList', name: node.name, type: (0, rfc7951_1.toFormLeafType)(node.type) };
+            if (node.minElements !== undefined)
+                list.minItems = node.minElements;
+            if (node.maxElements !== undefined)
+                list.maxItems = node.maxElements;
+            return list;
+        }
+        case 'container': {
+            const group = { kind: 'nodeGroup', name: node.name, children: mapChildren(node.children) };
+            if (node.presence)
+                group.presence = true;
+            return group;
+        }
+        case 'list': {
+            const groupList = {
+                kind: 'nodeGroupList',
+                name: node.name,
+                type: { kind: 'nodeGroup', name: node.name, children: mapChildren(node.children) },
+            };
+            if (node.minElements !== undefined)
+                groupList.minItems = node.minElements;
+            if (node.maxElements !== undefined)
+                groupList.maxItems = node.maxElements;
+            return groupList;
+        }
+        case 'choice': {
+            const cases = {};
+            for (const c of node.cases) {
+                cases[c.name] = mapChildren(c.children);
+            }
+            const choice = { kind: 'choice', name: node.name, cases };
+            if (node.default)
+                choice.default = node.default;
+            if (node.mandatory)
+                choice.mandatory = true;
+            return choice;
+        }
+    }
+}
+function bitsGroup(node, bits) {
+    const children = {};
+    for (const bit of bits) {
+        children[bit] = { kind: 'leaf', name: bit, type: 'boolean' };
+    }
+    return { kind: 'nodeGroup', name: node.name, children };
+}

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

@@ -0,0 +1,111 @@
+/**
+ * The resolved YANG schema — the effective model the engine emits and the
+ * "binding" the adapter keeps server-side.
+ *
+ * A `YangEngine` resolves a raw YANG module set (with `uses`/`augment`/`typedef`
+ * already collapsed) into this normalized tree. It carries everything the plain
+ * form value drops but the RFC 7951 round-trip needs: the resolved base type,
+ * the owning module (for name qualification), list keys, and the config/state
+ * flag. `mapToSchema` derives the frontend `NodeGroup` from it; the revert walks
+ * it directly. Kept in the adapter, never sent to the client.
+ */
+/** YANG built-in base types this version recognizes (RFC 7950 §9). */
+export type YangBase = 'string' | 'boolean' | 'int8' | 'int16' | 'int32' | 'int64' | 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'decimal64' | 'enumeration' | 'binary' | 'identityref' | 'leafref' | 'empty' | 'instance-identifier' | 'union' | 'bits';
+export interface YangType {
+    base: YangBase;
+    /** Allowed names for `enumeration`. */
+    enums?: string[];
+    /** Digit count for `decimal64`. */
+    fractionDigits?: number;
+    /** Derived identities for `identityref`, each tagged with its defining module. */
+    identities?: {
+        name: string;
+        module: string;
+    }[];
+    /** Named flags for `bits`, in schema order. */
+    bits?: string[];
+    /** Member types for `union` (ordered; RFC 7950 §9.12). */
+    members?: YangType[];
+    /** Schema-node path a `leafref` points at (RFC 7950 §9.9). */
+    leafrefPath?: string;
+}
+export interface EffLeaf {
+    kind: 'leaf';
+    name: string;
+    module: string;
+    type: YangType;
+    default?: string | number | boolean;
+    mandatory?: boolean;
+    /** `false` = read-only operational state; excluded from write-back. Defaults to config (true). */
+    config?: boolean;
+    description?: string;
+}
+export interface EffLeafList {
+    kind: 'leaf-list';
+    name: string;
+    module: string;
+    type: YangType;
+    minElements?: number;
+    maxElements?: number;
+    orderedByUser?: boolean;
+    config?: boolean;
+    description?: string;
+}
+export interface EffContainer {
+    kind: 'container';
+    name: string;
+    module: string;
+    presence?: boolean;
+    config?: boolean;
+    children: EffNode[];
+    description?: string;
+}
+export interface EffList {
+    kind: 'list';
+    name: string;
+    module: string;
+    keys: string[];
+    minElements?: number;
+    maxElements?: number;
+    orderedByUser?: boolean;
+    config?: boolean;
+    children: EffNode[];
+    description?: string;
+}
+export interface EffCase {
+    name: string;
+    children: EffNode[];
+}
+/**
+ * A YANG choice (RFC 7950 §7.9): mutually-exclusive cases. The choice itself has
+ * no instance data — the selected case's children serialize *inline* at the
+ * choice's location, with no choice/case wrapper.
+ */
+export interface EffChoice {
+    kind: 'choice';
+    name: string;
+    module: string;
+    cases: EffCase[];
+    default?: string;
+    mandatory?: boolean;
+    description?: string;
+}
+export type EffNode = EffLeaf | EffLeafList | EffContainer | EffList | EffChoice;
+export interface ModuleInfo {
+    name: string;
+    namespace: string;
+    revision?: string;
+}
+/**
+ * A fully-resolved YANG model: the top-level data nodes plus module metadata.
+ * This is the value stored as a compiled model's `binding`.
+ */
+export interface EffectiveModel {
+    modules: ModuleInfo[];
+    roots: EffNode[];
+}
+/** The compiled artifact: the frontend schema plus the server-side binding. */
+export interface CompiledModel {
+    schema: import('../../core/schema').NodeGroup;
+    binding: EffectiveModel;
+}

package/dist/transformers/yang/model.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * The resolved YANG schema — the effective model the engine emits and the
+ * "binding" the adapter keeps server-side.
+ *
+ * A `YangEngine` resolves a raw YANG module set (with `uses`/`augment`/`typedef`
+ * already collapsed) into this normalized tree. It carries everything the plain
+ * form value drops but the RFC 7951 round-trip needs: the resolved base type,
+ * the owning module (for name qualification), list keys, and the config/state
+ * flag. `mapToSchema` derives the frontend `NodeGroup` from it; the revert walks
+ * it directly. Kept in the adapter, never sent to the client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,6 @@
+import { EffectiveModel } from './model';
+import { FormValue } from '../../core/schema';
+/** RFC 7951 JSON instance data → a plain form value keyed by bare names. */
+export declare function toFormValue(rfc7951: unknown, model: EffectiveModel): FormValue;
+/** A plain form value → RFC 7951 JSON instance data ready for write-back. */
+export declare function toYangData(value: FormValue, model: EffectiveModel): Record<string, unknown>;