@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/openapi/OpenApiUIMapper.ts

@@ -1,93 +1,68 @@
-/**
- * @file OpenApiUIMapper.ts
- * @description Utility class for mapping OpenAPI properties and formats into MetaUI IUIDirectives.
- */
-import { IUIDirective } from "../interfaces/ISchema";
-
-/**
- * Utility class responsible for evaluating OpenAPI metadata and generating the corresponding 
- * MetaUI UI rendering directives. This isolates all visual layout assumptions from the parsing engine.
- * 
- * @public
- */
-export class OpenApiUIMapper {
-    /**
-     * Evaluates an OpenAPI property definition and constructs a MetaUI IUIDirective block.
-     * Extracts labels from title/description, maps readOnly state, and assigns 
-     * specific UI5 Fiori widgets based on the OpenAPI 'format' property.
-     * 
-     * @param {any} swaggerProp The raw OpenAPI property schema chunk.
-     * @param {string} keyName The technical JSON key of the property.
-     * @returns {IUIDirective} The constructed MetaUI UI orchestration directive.
-     */
-    public static build(rawProp: unknown, keyName: string): IUIDirective {
-        const swaggerProp = (rawProp || {}) as Record<string, unknown>;
-        const ui: IUIDirective = {};
-
-        // Label Synthesis
-        if (swaggerProp.title) {
-            ui.label = swaggerProp.title as string;
-        } else {
-            ui.label = this.generateLabel(keyName);
-        }
-
-        // State Mapping
-        if (swaggerProp.readOnly === true) {
-            ui.readOnly = true;
-        }
-
-        // Format to Widget Translation
-        if (swaggerProp.format) {
-            switch (swaggerProp.format) {
-                case "date-time":
-                    ui.widget = "datetime";
-                    break;
-                case "date":
-                    ui.widget = "date";
-                    break;
-                case "password":
-                    ui.widget = "password";
-                    ui.format = "password"; // Kept for schema validation
-                    break;
-                case "email":
-                    ui.widget = "email";
-                    ui.format = "email"; // Kept for schema validation
-                    break;
-                case "uri":
-                    ui.widget = "link";
-                    ui.format = "url"; // Kept for schema validation
-                    break;
-                case "binary":
-                case "byte":
-                    ui.widget = "fileUploader";
-                    break;
-                case "uuid":
-                case "ipv4":
-                case "ipv6":
-                case "hostname":
-                    if (!ui.validators) ui.validators = [];
-                    ui.validators.push(swaggerProp.format as string);
-                    break;
-            }
-        }
-
-        return ui;
-    }
-
-    /**
-     * Synthesizes a human-readable Title Case label from camelCase or snake_case technical keys.
-     * 
-     * @param {string} name The raw technical property key (e.g., 'creationTimestamp').
-     * @returns {string} The formatted human-readable label (e.g., 'Creation Timestamp').
-     * @private
-     */
-    private static generateLabel(name: string): string {
-        if (!name) return "";
-        let spaced = name.replace(/([A-Z])/g, " $1").replace(/_/g, " ");
-        return spaced.split(' ')
-            .filter(w => w.length > 0)
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-            .join(' ')
-            .trim();
-    }
-}
+/**
+ * @file OpenApiUIMapper.ts
+ * @description Pure utility class for mapping OpenAPI properties and formats into MetaUI IUIDirectives.
+ */
+
+import { IUIDirective } from "../interfaces/ISchema";
+import { WIDGET_TYPE } from "../constants/MetaUIConstants";
+import { DataInferenceBuilder } from "../core/DataInferenceBuilder";
+import { SchemaDirectiveNormalizer } from "../core/SchemaDirectiveNormalizer";
+import { isRecord, readString, readBoolean } from "../utils/TypeGuards";
+
+/**
+ * Evaluates OpenAPI property metadata and constructs the corresponding MetaUI `IUIDirective` block.
+ * Isolates all visual widget and format mappings from the OpenAPI structural parsers.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.openapi
+ * @internal
+ */
+export class OpenApiUIMapper {
+    /**
+     * Constructs a MetaUI `IUIDirective` from a raw OpenAPI property definition.
+     * Extracts labels from `title` or synthesizes a human-readable label from `keyName`,
+     * maps `readOnly` state, and assigns Fiori widgets and validation formats from OpenAPI `format`.
+     *
+     * @param rawProp The raw OpenAPI property schema record.
+     * @param keyName The technical JSON key of the property.
+     * @returns {IUIDirective} The constructed MetaUI UI orchestration directive.
+     */
+    public static build(rawProp: unknown, keyName: string): IUIDirective {
+        const swaggerProp = isRecord(rawProp) ? rawProp : {};
+        const ui: IUIDirective = {
+            label: readString(swaggerProp, "title") || DataInferenceBuilder.generateLabel(keyName)
+        };
+
+        if (readBoolean(swaggerProp, "readOnly") === true) {
+            ui.readOnly = true;
+        }
+
+        if (readString(swaggerProp, "type") === "file") {
+            ui.widget = WIDGET_TYPE.FILE_UPLOADER;
+        }
+
+        // Mirrors SchemaDirectiveNormalizer.normalizeUI so a document compiled through OpenApiBuilder
+        // alone carries the same placeholder as the same document run through SchemaNormalizer.
+        const placeholder = SchemaDirectiveNormalizer.exampleAsPlaceholder(swaggerProp.example);
+        if (placeholder !== undefined) {
+            ui.placeholder = placeholder;
+        }
+
+        const format = readString(swaggerProp, "format");
+        const formatMapping = SchemaDirectiveNormalizer.formatToWidget(format);
+        if (formatMapping.widget) {
+            ui.widget = formatMapping.widget;
+        }
+        if (formatMapping.uiFormat) {
+            ui.format = formatMapping.uiFormat;
+        }
+
+        if (isRecord(swaggerProp.ui)) {
+            Object.assign(ui, swaggerProp.ui);
+            if (!ui.label) {
+                ui.label = readString(swaggerProp, "title") || DataInferenceBuilder.generateLabel(keyName);
+            }
+        }
+
+        return ui;
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/openapi/heuristics/OpenApiHeuristicEngine.ts

@@ -1,43 +1,43 @@
-/**
- * @file OpenApiHeuristicEngine.ts
- * @description Orchestrator that registers and executes all IHeuristicPlugin implementations against the raw schema.
- */
-
-import { IHeuristicPlugin } from "./interfaces/IHeuristicPlugin";
-import { ProtobufVariantHeuristic } from "./plugins/ProtobufVariantHeuristic";
-
-/**
- * Orchestration engine that initializes and executes heuristic plugins sequentially.
- * This pipeline mutates the raw OpenAPI document in-place to normalize non-standard constructs
- * (like Protobuf unions) before the primary parsing phase occurs.
- * 
- * @public
- */
-export class OpenApiHeuristicEngine {
-    private plugins: IHeuristicPlugin[] = [];
-
-    /**
-     * Initializes a new instance of the HeuristicEngine and registers default heuristics.
-     */
-    constructor() {
-        // Register default heuristics
-        this.plugins.push(new ProtobufVariantHeuristic());
-    }
-
-    /**
-     * Runs all registered heuristic plugins sequentially against the raw OpenAPI document.
-     * Captures and bubbles plugin-specific execution failures to prevent silent pipeline corruption.
-     * 
-     * @param {any} openApiRoot The entire OpenAPI root document, to be mutated in-place.
-     * @throws {Error} If any heuristic plugin crashes during execution.
-     */
-    public run(openApiRoot: unknown): void {
-        for (const plugin of this.plugins) {
-            try {
-                plugin.apply(openApiRoot);
-            } catch (e: any) {
-                throw new Error(`[MetaUI HeuristicEngine] Plugin execution failed: ${e.message}`);
-            }
-        }
-    }
-}
+/**
+ * @file OpenApiHeuristicEngine.ts
+ * @description Orchestrator that registers and executes all IHeuristicPlugin implementations against the raw schema.
+ */
+
+import { IHeuristicPlugin } from "./interfaces/IHeuristicPlugin";
+import { ProtobufVariantHeuristic } from "./plugins/ProtobufVariantHeuristic";
+
+/**
+ * Orchestration engine that initializes and executes heuristic plugins sequentially.
+ * This pipeline mutates the raw OpenAPI document in-place to normalize non-standard constructs
+ * (like Protobuf unions) before the primary parsing phase occurs.
+ *
+ * @internal
+ */
+export class OpenApiHeuristicEngine {
+    private plugins: IHeuristicPlugin[] = [];
+
+    /**
+     * Initializes a new instance of the HeuristicEngine and registers default heuristics.
+     */
+    constructor() {
+        // Register default heuristics
+        this.plugins.push(new ProtobufVariantHeuristic());
+    }
+
+    /**
+     * Runs all registered heuristic plugins sequentially against the raw OpenAPI document.
+     * Captures and bubbles plugin-specific execution failures to prevent silent pipeline corruption.
+     *
+     * @param {unknown} openApiRoot The entire OpenAPI root document, to be mutated in-place.
+     * @throws {Error} If any heuristic plugin crashes during execution.
+     */
+    public run(openApiRoot: unknown): void {
+        for (const plugin of this.plugins) {
+            try {
+                plugin.apply(openApiRoot);
+            } catch (e: unknown) {
+                throw new Error(`[MetaUI HeuristicEngine] Plugin execution failed: ${(e as Error).message}`);
+            }
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/openapi/heuristics/interfaces/IHeuristicPlugin.ts

@@ -1,21 +1,21 @@
-/**
- * @file IHeuristicPlugin.ts
- * @description Contract for plugins that inspect and mutate the raw OpenAPI AST before translation.
- */
-
-/**
- * Interface defining the operational boundaries for structural heuristic plugins.
- * Implementations are executed synchronously during the pre-processing phase to normalize
- * non-standard schema constructs (like generic object unions) before translation occurs.
- * 
- * @public
- */
-export interface IHeuristicPlugin {
-    /**
-     * Evaluates and mutates the provided OpenAPI AST in-place.
-     * Heuristics are expected to strictly scope their mutations to patterns they explicitly recognize.
-     * 
-     * @param {any} openApiRoot The mutable OpenAPI root document block.
-     */
-    apply(openApiRoot: unknown): void;
-}
+/**
+ * @file IHeuristicPlugin.ts
+ * @description Contract for plugins that inspect and mutate the raw OpenAPI AST before translation.
+ */
+
+/**
+ * Interface defining the operational boundaries for structural heuristic plugins.
+ * Implementations are executed synchronously during the pre-processing phase to normalize
+ * non-standard schema constructs (like generic object unions) before translation occurs.
+ * 
+ * @public
+ */
+export interface IHeuristicPlugin {
+    /**
+     * Evaluates and mutates the provided OpenAPI AST in-place.
+     * Heuristics are expected to strictly scope their mutations to patterns they explicitly recognize.
+     * 
+     * @param {any} openApiRoot The mutable OpenAPI root document block.
+     */
+    apply(openApiRoot: unknown): void;
+}

package/src/nz/co/siliconst/ui5/metaui/openapi/heuristics/plugins/ProtobufVariantHeuristic.ts

@@ -1,117 +1,102 @@
-/**
- * @file ProtobufVariantHeuristic.ts
- * @description Scans OpenAPI 2.0 schemas for implicitly polymorphic structures (e.g., objects containing purely optional, mutually exclusive fields) and explicitly mutates them into `oneOf` structures.
- */
-
-import { IHeuristicPlugin } from "../interfaces/IHeuristicPlugin";
-
-/**
- * Heuristic plugin that detects Protobuf-style Variant representations (objects with exclusively optional *_value fields)
- * and mutates the AST to a proper oneOf polymorphic array before it reaches the parsers.
- * 
- * @public
- */
-export class ProtobufVariantHeuristic implements IHeuristicPlugin {
-    /**
-     * Executes the heuristic logic against the OpenAPI AST.
-     * Initiates a scan of the global definitions block if the document matches the OpenAPI 2.0 specification.
-     * 
-     * @param {any} openApiRoot The entire OpenAPI root document.
-     */
-    public apply(openApiRoot: unknown): void {
-        if (!openApiRoot) return;
-        const root = openApiRoot as Record<string, unknown>;
-        // In OpenAPI 2.0, scan definitions
-        if (root.swagger === "2.0" && root.definitions) {
-            this._scanDefinitions(root.definitions as Record<string, unknown>);
-        }
-    }
-
-    /**
-     * Iterates over all root-level definitions to detect and mutate variant structures.
-     * 
-     * @param {Record<string, any>} definitions The raw OpenAPI 2.0 definitions dictionary.
-     * @private
-     */
-    private _scanDefinitions(definitions: Record<string, unknown>): void {
-        for (const [key, definition] of Object.entries(definitions)) {
-            // Heuristic 1: If the object name ends with "Value" and has multiple optional properties 
-            // that end with "_value" (common Protobuf JSON representation for variants)
-            if (this._isProtobufVariant(key, definition)) {
-                this._mutateToOneOf(definition as Record<string, unknown>);
-            }
-        }
-    }
-
-    /**
-     * Evaluates a schema block against the heuristic signature of a Protobuf Variant.
-     * 
-     * @param {string} key The schema definition name.
-     * @param {any} definition The structural definition block.
-     * @returns {boolean} True if the structure matches a Protobuf variant pattern.
-     * @private
-     */
-    private _isProtobufVariant(key: string, rawDef: unknown): boolean {
-        const definition = rawDef as Record<string, unknown>;
-        if (definition.type !== "object" || !definition.properties) {
-            return false;
-        }
-
-        // Must not have required fields if it's a pure union
-        const requiredFields = definition.required as string[] | undefined;
-        if (requiredFields && requiredFields.length > 0) {
-            return false;
-        }
-
-        const properties = definition.properties as Record<string, unknown>;
-        const propKeys = Object.keys(properties);
-        if (propKeys.length < 2) {
-            return false;
-        }
-
-        // Check if all properties end with "_value" (e.g. bool_value, list_value)
-        const allEndWithValue = propKeys.every(k => k.endsWith("_value"));
-        if (allEndWithValue && (key.endsWith("Value") || key.endsWith("Variant"))) {
-            return true;
-        }
-
-        return false;
-    }
-
-    /**
-     * Mutates the AST in-place by synthesizing a `oneOf` array from the optional properties
-     * and strictly purging the original object layout to force polymorphic evaluation.
-     * 
-     * @param {any} definition The target variant object schema.
-     * @private
-     */
-    private _mutateToOneOf(definition: Record<string, unknown>): void {
-        const properties = definition.properties as Record<string, unknown>;
-        const propKeys = Object.keys(properties);
-        const oneOfArray: unknown[] = [];
-
-        for (const propKey of propKeys) {
-            const variantSchema = properties[propKey] as Record<string, unknown>;
-            
-            // Reconstruct a sub-object for each variant, enforcing strict requirement of the single variant property
-            const syntheticVariant = {
-                type: "object",
-                properties: {
-                    [propKey]: variantSchema
-                },
-                required: [propKey],
-                title: variantSchema.description || propKey
-            };
-            
-            oneOfArray.push(syntheticVariant);
-        }
-
-        // Mutate the original definition to become a oneOf root
-        definition.oneOf = oneOfArray;
-        
-        // CRITICAL DESTRUCTIVE MUTATION:
-        // We delete the original properties block. If this is not done, the core engine's layout
-        // orchestrator will attempt to render both a standard static form AND the polymorphic switcher simultaneously.
-        delete definition.properties;
-    }
-}
+/**
+ * @file ProtobufVariantHeuristic.ts
+ * @description Scans OpenAPI 2.0 schemas for implicitly polymorphic Protobuf variant structures
+ * (objects containing purely optional `*_value` fields) and mutates them into `oneOf` unions.
+ */
+
+import { IHeuristicPlugin } from "../interfaces/IHeuristicPlugin";
+import { OpenApiParserFactory } from "../../OpenApiParserFactory";
+import { JsonRecord, isRecord, readString, readRecord, readStringArray } from "../../../utils/TypeGuards";
+
+/**
+ * Heuristic plugin that detects Protobuf-style Variant representations (objects with exclusively optional `*_value` fields)
+ * and transforms the AST into a standard `oneOf` polymorphic array before it reaches the OpenAPI parsers.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.openapi.heuristics.plugins
+ * @internal
+ */
+export class ProtobufVariantHeuristic implements IHeuristicPlugin {
+    /**
+     * Executes the heuristic scan against the OpenAPI 2.0 `definitions` dictionary.
+     *
+     * @param openApiRoot The OpenAPI root document.
+     */
+    public apply(openApiRoot: unknown): void {
+        if (!isRecord(openApiRoot)) {
+            return;
+        }
+        const definitions = readRecord(openApiRoot, "definitions");
+        if (OpenApiParserFactory.detectSpecVersion(openApiRoot) === "2.0" && definitions) {
+            this.scanDefinitions(definitions);
+        }
+    }
+
+    /**
+     * Iterates over all root-level definitions to detect and mutate variant structures.
+     *
+     * @param definitions The raw OpenAPI 2.0 `definitions` dictionary.
+     */
+    private scanDefinitions(definitions: JsonRecord): void {
+        for (const [key, definition] of Object.entries(definitions)) {
+            if (isRecord(definition) && this.isProtobufVariant(key, definition)) {
+                this.mutateToOneOf(definition);
+            }
+        }
+    }
+
+    /**
+     * Evaluates a schema block against the heuristic signature of a Protobuf Variant.
+     *
+     * @param key The schema definition name.
+     * @param definition The structural definition block.
+     * @returns {boolean} True if the structure matches a Protobuf variant pattern.
+     */
+    private isProtobufVariant(key: string, definition: JsonRecord): boolean {
+        if (Array.isArray(definition.oneOf)) {
+            return false;
+        }
+        const properties = readRecord(definition, "properties");
+        if (readString(definition, "type") !== "object" || !properties) {
+            return false;
+        }
+
+        const requiredFields = readStringArray(definition, "required");
+        if (requiredFields && requiredFields.length > 0) {
+            return false;
+        }
+
+        const propKeys = Object.keys(properties);
+        if (propKeys.length < 2) {
+            return false;
+        }
+
+        const allEndWithValue = propKeys.every((k) => k.endsWith("_value"));
+        return allEndWithValue && (key.endsWith("Value") || key.endsWith("Variant"));
+    }
+
+    /**
+     * Mutates the definition in-place by synthesizing a `oneOf` array from its optional `*_value` properties
+     * and removing the flat `properties` map so polymorphic rendering takes precedence.
+     *
+     * @param definition The target variant object schema.
+     */
+    private mutateToOneOf(definition: JsonRecord): void {
+        const properties = readRecord(definition, "properties") || {};
+        const oneOfArray: JsonRecord[] = [];
+
+        for (const propKey of Object.keys(properties)) {
+            const variantSchema = readRecord(properties, propKey) || {};
+            oneOfArray.push({
+                type: "object",
+                properties: {
+                    [propKey]: variantSchema
+                },
+                required: [propKey],
+                title: readString(variantSchema, "title") || readString(variantSchema, "description") || propKey
+            });
+        }
+
+        definition.oneOf = oneOfArray;
+        delete definition.properties;
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/openapi/interfaces/IOpenApiParserPlugin.ts

@@ -1,25 +1,25 @@
-/**
- * @file IOpenApiParserPlugin.ts
- * @description Contract for OpenAPI schema translation implementations.
- */
-
-import { ISchema } from "../../interfaces/ISchema";
-
-/**
- * Interface defining the boundary for dynamic OpenAPI schema parsing.
- * Any parser plugin must implement this contract to ensure the orchestration engine
- * can seamlessly synthesize MetaUI layouts regardless of the underlying OpenAPI version.
- * 
- * @public
- */
-export interface IOpenApiParserPlugin {
-    /**
-     * Converts a raw OpenAPI schema document into a strictly-typed MetaUI ISchema tree.
-     * Implementations must handle protocol-specific mapping internally.
-     * 
-     * @param {any} rawSchema The raw, unparsed OpenAPI document structure.
-     * @param {string} [targetDefinition] Optional name of a specific definition root to target.
-     * @returns {ISchema} A completely normalized and decoupled MetaUI layout definition.
-     */
-    parse(rawSchema: unknown, targetDefinition?: string): ISchema;
-}
+/**
+ * @file IOpenApiParserPlugin.ts
+ * @description Contract for OpenAPI schema translation implementations.
+ */
+
+import { ISchema } from "../../interfaces/ISchema";
+
+/**
+ * Interface defining the boundary for dynamic OpenAPI schema parsing.
+ * Any parser plugin must implement this contract to ensure the orchestration engine
+ * can seamlessly synthesize MetaUI layouts regardless of the underlying OpenAPI version.
+ * 
+ * @public
+ */
+export interface IOpenApiParserPlugin {
+    /**
+     * Converts a raw OpenAPI schema document into a strictly-typed MetaUI ISchema tree.
+     * Implementations must handle protocol-specific mapping internally.
+     * 
+     * @param {any} rawSchema The raw, unparsed OpenAPI document structure.
+     * @param {string} [targetDefinition] Optional name of a specific definition root to target.
+     * @returns {ISchema} A completely normalized and decoupled MetaUI layout definition.
+     */
+    parse(rawSchema: unknown, targetDefinition?: string): ISchema;
+}