@siliconst/metaui 1.4.51 → 2.0.0

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

@@ -1,88 +1,101 @@
-/**
- * @file OpenApiBuilder.ts
- * @description Facade orchestration for translating Swagger/OpenAPI JSON into native MetaUI ISchema.
- * Strict Single Responsibility architecture delegates mapping logic to dedicated utilities and factories.
- */
-
-import { ISchema } from "../interfaces/ISchema";
-import { ISchemaBuilderPlugin } from "../interfaces/ISchemaBuilderPlugin";
-import { Logger } from "../utils/Logger";
-import { OpenApiParserFactory } from "./OpenApiParserFactory";
-import { OpenApiHeuristicEngine } from "./heuristics/OpenApiHeuristicEngine";
-
-/**
- * Facade orchestration for translating Swagger/OpenAPI JSON into native MetaUI ISchema.
- * Strict Single Responsibility architecture delegates mapping logic to dedicated utilities and factories.
- * 
- * @public
- */
-export class OpenApiBuilder implements ISchemaBuilderPlugin {
-
-    /**
-     * Determines if the provided JSON payload is a Swagger or OpenAPI document.
-     * 
-     * @param {unknown} rawSchema The raw JSON schema to test.
-     * @returns {boolean} True if the document contains 'openapi' or 'swagger' root keys.
-     */
-    public canHandle(rawSchema: unknown): boolean {
-        const schema = rawSchema as Record<string, unknown>;
-        return !!(schema && (schema.openapi || schema.swagger));
-    }
-
-    /**
-     * Builds a strict MetaUI ISchema from the provided OpenAPI payload.
-     * 
-     * @param {unknown} rawSchema The OpenAPI root document.
-     * @param {string} [targetDefinition] Optional target root definition.
-     * @returns {ISchema} The translated MetaUI schema.
-     */
-    public build(rawSchema: unknown, targetDefinition?: string): ISchema {
-        return OpenApiBuilder.build(rawSchema, targetDefinition);
-    }
-
-    /**
-     * Asynchronously fetches a remote OpenAPI document and compiles it into a MetaUI ISchema.
-     * 
-     * @param {string} url The URL to fetch the JSON payload from.
-     * @param {string} [targetDefinition] Optional. The specific entity schema to extract.
-     * @returns {Promise<ISchema>} A Promise resolving to the compiled ISchema.
-     */
-    public static async fetchAndBuild(url: string, targetDefinition?: string): Promise<ISchema> {
-        try {
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`HTTP error! status: ${response.status}`);
-            }
-            const openApiRoot = await response.json();
-            return this.build(openApiRoot, targetDefinition);
-        } catch (error) {
-            const msg = "Failed to fetch Swagger JSON from URL: " + (error as Error).message;
-            Logger.error("[MetaUI OpenApiBuilder]", msg);
-            throw new Error(msg);
-        }
-    }
-
-    /**
-     * Synchronously builds a MetaUI ISchema from a provided OpenAPI root document.
-     * Delegates to HeuristicEngine and OpenApiParserFactory.
-     * 
-     * @public
-     * @param {unknown} openApiRoot The raw OpenAPI root JSON document.
-     * @param {string} [targetDefinition] Optional target definition key to extract.
-     * @returns {ISchema} The synthesized MetaUI schema.
-     * @throws {Error} If the root object is invalid.
-     */
-    public static build(openApiRoot: unknown, targetDefinition?: string): ISchema {
-        if (!openApiRoot || typeof openApiRoot !== "object") {
-            throw new Error("[MetaUI OpenApiBuilder] Invalid Swagger root object provided.");
-        }
-
-        // 1. Run Heuristics to mutate AST (e.g., simulating oneOf)
-        const heuristicEngine = new OpenApiHeuristicEngine();
-        heuristicEngine.run(openApiRoot);
-
-        // 2. Delegate to correct parser version
-        const parser = OpenApiParserFactory.getParser(openApiRoot);
-        return parser.parse(openApiRoot, targetDefinition);
-    }
-}
+/**
+ * @file OpenApiBuilder.ts
+ * @description Facade orchestration for translating Swagger/OpenAPI JSON into native MetaUI ISchema.
+ * Strict Single Responsibility architecture delegates mapping logic to dedicated utilities and factories.
+ */
+
+import { ISchema } from "../interfaces/ISchema";
+import { ISchemaBuilderPlugin } from "../interfaces/ISchemaBuilderPlugin";
+import { Logger } from "../utils/Logger";
+import { isRecord, deepClone } from "../utils/TypeGuards";
+import { UrlValidator } from "../utils/UrlValidator";
+import { OpenApiParserFactory } from "./OpenApiParserFactory";
+import { OpenApiHeuristicEngine } from "./heuristics/OpenApiHeuristicEngine";
+
+/**
+ * Facade orchestration for translating Swagger/OpenAPI JSON into native MetaUI ISchema.
+ * Strict Single Responsibility architecture delegates mapping logic to dedicated utilities and factories.
+ *
+ * @internal
+ */
+export class OpenApiBuilder implements ISchemaBuilderPlugin {
+
+    /**
+     * Determines if the provided JSON payload is a Swagger or OpenAPI document.
+     *
+     * @param {unknown} rawSchema The raw JSON schema to test.
+     * @returns {boolean} True if the document contains 'openapi' or 'swagger' root keys.
+     */
+    public canHandle(rawSchema: unknown): boolean {
+        return isRecord(rawSchema) && Boolean(rawSchema.openapi || rawSchema.swagger);
+    }
+
+    /**
+     * Builds a strict MetaUI ISchema from the provided OpenAPI payload.
+     *
+     * @param {unknown} rawSchema The OpenAPI root document.
+     * @param {string} [targetDefinition] Optional target root definition.
+     * @returns {ISchema} The translated MetaUI schema.
+     */
+    public build(rawSchema: unknown, targetDefinition?: string): ISchema {
+        return OpenApiBuilder.build(rawSchema, targetDefinition);
+    }
+
+    /**
+     * Asynchronously fetches a remote OpenAPI document and compiles it into a MetaUI ISchema.
+     *
+     * The endpoint passes through the same scheme and origin policy as every other outbound request
+     * MetaUI makes, so an application that narrows {@link UrlValidator.setDataSourceOriginPolicy} is
+     * not left with an unguarded side door on this sibling of `SchemaProvider.resolve`.
+     *
+     * @param {string} url The URL to fetch the JSON payload from.
+     * @param {string} [targetDefinition] Optional. The specific entity schema to extract.
+     * @returns {Promise<ISchema>} A Promise resolving to the compiled ISchema.
+     * @throws {Error} If the URL is blocked by the data source URL policy, or the fetch or parse fails.
+     */
+    public static async fetchAndBuild(url: string, targetDefinition?: string): Promise<ISchema> {
+        if (!UrlValidator.isSafeDataSourceUrl(url)) {
+            const refusal = `Refused OpenAPI URL '${url}': blocked by the data source URL policy.`;
+            Logger.warn(refusal, undefined, "OpenApiBuilder");
+            throw new Error(refusal);
+        }
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const openApiRoot = await response.json();
+            return this.build(openApiRoot, targetDefinition);
+        } catch (error) {
+            const msg = "Failed to fetch Swagger JSON from URL: " + (error as Error).message;
+            Logger.error(msg, undefined, "OpenApiBuilder");
+            throw new Error(msg);
+        }
+    }
+
+    /**
+     * Synchronously builds a MetaUI ISchema from a provided OpenAPI root document.
+     * Clones the input document so heuristic AST transformations never mutate caller-owned objects.
+     *
+     * @public
+     * @param {unknown} openApiRoot The raw OpenAPI root JSON document.
+     * @param {string} [targetDefinition] Optional target definition key to extract.
+     * @returns {ISchema} The synthesized MetaUI schema.
+     * @throws {Error} If the root object is invalid.
+     */
+    public static build(openApiRoot: unknown, targetDefinition?: string): ISchema {
+        if (!isRecord(openApiRoot)) {
+            throw new Error("[MetaUI OpenApiBuilder] Invalid Swagger root object provided.");
+        }
+
+        const workingRoot = deepClone(openApiRoot);
+
+        // 1. Run Heuristics to mutate working AST copy (e.g., simulating oneOf)
+        const heuristicEngine = new OpenApiHeuristicEngine();
+        heuristicEngine.run(workingRoot);
+
+        // 2. Delegate to correct parser version
+        const parser = OpenApiParserFactory.getParser(workingRoot);
+        return parser.parse(workingRoot, targetDefinition);
+    }
+}

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

@@ -1,44 +1,70 @@
-/**
- * @file OpenApiParserFactory.ts
- * @description Factory class to determine and instantiate the correct Swagger parser version.
- */
-
-import { IOpenApiParserPlugin } from "./interfaces/IOpenApiParserPlugin";
-import { OpenApi2Parser } from "./parsers/OpenApi2Parser";
-import { OpenApi3Parser } from "./parsers/OpenApi3Parser";
-import { Logger } from "../utils/Logger";
-
-/**
- * Factory class responsible for analyzing a raw OpenAPI document's metadata to dynamically 
- * instantiate the correct, version-specific parser plugin. This isolates structural version 
- * differences from the primary Engine orchestration layer.
- * 
- * @public
- */
-export class OpenApiParserFactory {
-    /**
-     * Inspects the root level structural signatures of an OpenAPI document (e.g., `swagger: "2.0"` 
-     * vs `openapi: "3.x"`) to instantiate the appropriate parsing engine.
-     * 
-     * @param {any} rawSchema The raw, unparsed OpenAPI root JSON structure.
-     * @returns {IOpenApiParserPlugin} An initialized instance of the correct concrete parser plugin.
-     */
-    public static getParser(rawSchema: unknown): IOpenApiParserPlugin {
-        if (!rawSchema || typeof rawSchema !== "object") {
-            Logger.error("[MetaUI OpenApiParserFactory] Invalid OpenAPI document provided.");
-            return new OpenApi3Parser(); // Fallback
-        }
-
-        const schema = rawSchema as Record<string, unknown>;
-        if (schema.swagger === "2.0") {
-            return new OpenApi2Parser();
-        }
-
-        if (schema.openapi && typeof schema.openapi === "string" && schema.openapi.startsWith("3")) {
-            return new OpenApi3Parser();
-        }
-
-        Logger.warn("[MetaUI OpenApiParserFactory] Unable to strictly determine OpenAPI version. Defaulting to OpenAPI 3.0 Parser.");
-        return new OpenApi3Parser();
-    }
-}
+/**
+ * @file OpenApiParserFactory.ts
+ * @description Factory class to determine and instantiate the correct Swagger parser version.
+ */
+
+import { IOpenApiParserPlugin } from "./interfaces/IOpenApiParserPlugin";
+import { OpenApi2Parser } from "./parsers/OpenApi2Parser";
+import { OpenApi3Parser } from "./parsers/OpenApi3Parser";
+import { Logger } from "../utils/Logger";
+import { isRecord } from "../utils/TypeGuards";
+
+/**
+ * Factory class responsible for analyzing a raw OpenAPI document's metadata to dynamically
+ * instantiate the correct, version-specific parser plugin. This isolates structural version
+ * differences from the primary Engine orchestration layer.
+ *
+ * @internal
+ */
+export class OpenApiParserFactory {
+    /**
+     * Detects the canonical OpenAPI specification family (`"2.0"` or `"3.0"`) from a raw root document,
+     * tolerating `"2.0"`, `"2.0.0"`, numeric `2.0` (`2`), `"3.0.x"`, and `"3.1.x"`.
+     *
+     * @param rawSchema The raw OpenAPI root document.
+     * @returns {"2.0" | "3.0" | undefined} The detected specification family, or `undefined` if unrecognized.
+     */
+    public static detectSpecVersion(rawSchema: unknown): "2.0" | "3.0" | undefined {
+        if (!isRecord(rawSchema)) {
+            return undefined;
+        }
+        if (rawSchema.swagger !== undefined && rawSchema.swagger !== null) {
+            const swaggerStr = String(rawSchema.swagger).trim();
+            if (swaggerStr === "2" || swaggerStr.startsWith("2.")) {
+                return "2.0";
+            }
+        }
+        if (rawSchema.openapi !== undefined && rawSchema.openapi !== null) {
+            const openapiStr = String(rawSchema.openapi).trim();
+            if (openapiStr === "3" || openapiStr.startsWith("3.")) {
+                return "3.0";
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Inspects the root level structural signatures of an OpenAPI document (e.g., `swagger: "2.0"`
+     * vs `openapi: "3.x"`) to instantiate the appropriate parsing engine.
+     *
+     * @param rawSchema The raw, unparsed OpenAPI root JSON structure.
+     * @returns {IOpenApiParserPlugin} An initialized instance of the correct concrete parser plugin.
+     */
+    public static getParser(rawSchema: unknown): IOpenApiParserPlugin {
+        if (!isRecord(rawSchema)) {
+            Logger.error("[MetaUI OpenApiParserFactory] Invalid OpenAPI document provided.");
+            return new OpenApi3Parser();
+        }
+
+        const version = this.detectSpecVersion(rawSchema);
+        if (version === "2.0") {
+            return new OpenApi2Parser();
+        }
+        if (version === "3.0") {
+            return new OpenApi3Parser();
+        }
+
+        Logger.warn("[MetaUI OpenApiParserFactory] Unable to strictly determine OpenAPI version. Defaulting to OpenAPI 3.0 Parser.");
+        return new OpenApi3Parser();
+    }
+}

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

@@ -1,61 +1,166 @@
-/**
- * @file OpenApiRefResolver.ts
- * @description Utility class for resolving local $ref pointers within an OpenAPI document.
- */
-import { Logger } from "../utils/Logger";
-
-/**
- * Utility class for resolving local $ref pointers within an OpenAPI document.
- * 
- * @public
- */
-export class OpenApiRefResolver {
-    /**
-     * Recursively traverses a local JSON Pointer $ref path (e.g., '#/components/schemas/Pet')
-     * and extracts the target object from the Swagger root document.
-     * External URLs or invalid references are safely ignored.
-     * 
-     * @param {string} refUrl The $ref string path.
-     * @param {any} openApiRoot The root OpenAPI document to query against.
-     * @param {number} depth The current recursive depth count, used to prevent infinite loops.
-     * @returns {any} The resolved schema object, or null if unresolvable.
-     */
-    public static resolve(refUrl: string, openApiRoot: unknown, depth: number = 0): unknown {
-        if (!refUrl || !refUrl.startsWith("#/")) {
-            Logger.debug(`[MetaUI OpenApiBuilder] Ignoring non-local or empty $ref: ${refUrl}`, "OpenApiBuilder");
-            return null; // Ignore external URLs per architectural rules
-        }
-
-        // Circular Reference Limit:
-        // A hard limit is enforced to prevent stack overflow exceptions caused by infinitely 
-        // recursive structures (e.g., a Tree node that references another Tree node).
-        if (depth > 10) {
-            Logger.error(`[MetaUI OpenApiBuilder] Circular or overly deep $ref detected: ${refUrl}`, null, "OpenApiBuilder");
-            return null;
-        }
-
-        // Path Segment Parsing:
-        // The '#/' prefix is stripped, and the remaining path is split by '/'.
-        // We incrementally descend into the swagger root using these segments.
-        const pathSegments = refUrl.substring(2).split("/");
-        let current = openApiRoot;
-
-        for (const segment of pathSegments) {
-            if (current && typeof current === "object" && segment in current) {
-                current = (current as Record<string, unknown>)[segment];
-            } else {
-                Logger.error(`[MetaUI OpenApiBuilder] Failed to resolve local $ref: ${refUrl}`, null, "OpenApiBuilder");
-                return null;
-            }
-        }
-
-        // Deep Resolution Recursion:
-        // If the resolved target is itself a reference pointer, recursively resolve again
-        // until we reach a terminal structure or hit the recursion depth limit.
-        if (current && typeof current === "object" && (current as Record<string, unknown>).$ref) {
-            return this.resolve((current as Record<string, unknown>).$ref as string, openApiRoot, depth + 1);
-        }
-
-        return current;
-    }
-}
+/**
+ * @file OpenApiRefResolver.ts
+ * @description Pure utility class for resolving RFC 6901 local $ref pointers within an OpenAPI document.
+ */
+
+import { OPENAPI_PREFIX, MAX_SCHEMA_DEPTH } from "../constants/MetaUIConstants";
+import { Logger } from "../utils/Logger";
+import { isRecord, readRecord, readString } from "../utils/TypeGuards";
+
+/**
+ * Resolves local JSON Pointer `$ref` paths (e.g., `'#/components/schemas/Pet'` or `'#/paths/~1v1~1orders/post'`)
+ * against an OpenAPI root document with circular-reference protection and RFC 6901 unescaping.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.openapi
+ * @internal
+ */
+export class OpenApiRefResolver {
+
+    /**
+     * Unescapes a single RFC 6901 JSON Pointer reference token (`decodeURIComponent`, then `~1` -> `/`, then `~0` -> `~`).
+     *
+     * @param segment The raw pointer reference token.
+     * @returns {string} The unescaped token string.
+     */
+    public static unescapePointerSegment(segment: string): string {
+        const decoded =
+            segment.includes("%") && !/%(?![0-9A-Fa-f]{2})/.test(segment)
+                ? decodeURIComponent(segment)
+                : segment;
+        return decoded.replace(/~1/g, "/").replace(/~0/g, "~");
+    }
+
+    /**
+     * Escapes a single string segment for inclusion in an RFC 6901 JSON Pointer (`~` -> `~0`, `/` -> `~1`,
+     * then `%` -> `%25`).
+     *
+     * The exact inverse of {@link OpenApiRefResolver.unescapePointerSegment}. That method percent-decodes
+     * first (RFC 6901 §6 URI-fragment form), so a literal `%` in a key — an OpenAPI path such as
+     * `/a%20b/{id}` is the common case — must be percent-encoded here or the round trip silently yields a
+     * different key, and the pointer resolves to an unrelated schema.
+     *
+     * @param segment The unescaped key or path string.
+     * @returns {string} The RFC 6901 escaped pointer token.
+     */
+    public static escapePointerSegment(segment: string): string {
+        return segment.replace(/~/g, "~0").replace(/\//g, "~1").replace(/%/g, "%25");
+    }
+
+    /**
+     * Extracts the clean definition name from a local `$ref` pointer (`#/components/schemas/...`,
+     * `#/definitions/...`, or `#/$defs/...`) and unescapes RFC 6901 tokens (`~1` -> `/`, `~0` -> `~`).
+     *
+     * @param refPath The raw `$ref` pointer string.
+     * @returns {string} The unescaped definition name.
+     */
+    public static extractRefName(refPath: string): string {
+        if (!refPath) return "";
+        let key = refPath;
+        if (key.startsWith(OPENAPI_PREFIX.COMPONENTS_SCHEMAS)) {
+            key = key.substring(OPENAPI_PREFIX.COMPONENTS_SCHEMAS.length);
+        } else if (key.startsWith(OPENAPI_PREFIX.DEFINITIONS)) {
+            key = key.substring(OPENAPI_PREFIX.DEFINITIONS.length);
+        } else if (key.startsWith(OPENAPI_PREFIX.DEFS)) {
+            key = key.substring(OPENAPI_PREFIX.DEFS.length);
+        } else if (key.startsWith("#/")) {
+            const parts = key.substring(2).split("/");
+            key = parts[parts.length - 1] || key;
+        }
+        return this.unescapePointerSegment(key);
+    }
+
+    /**
+     * Iteratively traverses a local JSON Pointer `$ref` path (and any chained `$ref` targets) and extracts the target node.
+     * External URLs or invalid references are safely ignored and return `null`.
+     *
+     * @param refUrl The `$ref` string path starting with `'#/'`.
+     * @param openApiRoot The root OpenAPI or normalized ISchema document to query against.
+     * @param depth Starting hop count, capped by `MAX_SCHEMA_DEPTH` to prevent circular reference loops.
+     * @param activeRefs Set of currently active `$ref` pointers on the call chain.
+     * @returns {unknown} The resolved schema or operation object, or `null` if unresolvable.
+     */
+    public static resolve(
+        refUrl: string,
+        openApiRoot: unknown,
+        depth: number = 0,
+        activeRefs: Set<string> = new Set()
+    ): unknown {
+        let currentRefUrl = refUrl;
+        let currentDepth = depth;
+        const seenRefs = new Set(activeRefs);
+
+        while (true) {
+            if (!currentRefUrl || !currentRefUrl.startsWith("#/")) {
+                // Warning, not debug: multi-file specs are the norm in enterprise OpenAPI, and
+                // dropping an external $ref silently renders a form missing its fields with no
+                // indication why - the plausible-looking empty result AGENTS.md rule 2 forbids.
+                Logger.warn(
+                    `[MetaUI OpenApiBuilder] Unsupported $ref dropped, so any fields it declares are missing from the form: `
+                    + `${currentRefUrl || "(empty)"}. Only local pointers of the form '#/...' are resolved; `
+                    + `pre-flatten the specification or inline the definition.`,
+                    "OpenApiBuilder"
+                );
+                return null;
+            }
+
+            if (currentDepth > MAX_SCHEMA_DEPTH || seenRefs.has(currentRefUrl)) {
+                Logger.error(
+                    `[MetaUI OpenApiBuilder] Circular or overly deep $ref detected: ${currentRefUrl}`,
+                    undefined,
+                    "OpenApiBuilder"
+                );
+                return null;
+            }
+
+            const pathSegments = currentRefUrl
+                .substring(2)
+                .split("/")
+                .map((segment) => this.unescapePointerSegment(segment));
+
+            let current: unknown = openApiRoot;
+            let found = true;
+            for (const segment of pathSegments) {
+                if (Array.isArray(current)) {
+                    const idx = Number(segment);
+                    if (segment !== "" && Number.isInteger(idx) && idx >= 0 && idx < current.length) {
+                        current = current[idx];
+                    } else {
+                        found = false;
+                        break;
+                    }
+                } else if (isRecord(current) && segment in current) {
+                    current = current[segment];
+                } else {
+                    found = false;
+                    break;
+                }
+            }
+
+            if (!found && isRecord(openApiRoot)) {
+                const refName = this.extractRefName(currentRefUrl);
+                const fallbackDefs = readRecord(openApiRoot, "definitions") || readRecord(openApiRoot, "$defs");
+                if (fallbackDefs && refName in fallbackDefs) {
+                    current = fallbackDefs[refName];
+                    found = true;
+                }
+            }
+
+            if (!found) {
+                Logger.error(
+                    `[MetaUI OpenApiBuilder] Failed to resolve local $ref: ${currentRefUrl}`,
+                    undefined,
+                    "OpenApiBuilder"
+                );
+                return null;
+            }
+
+            const nestedRef = isRecord(current) ? readString(current, "$ref") : undefined;
+            if (!nestedRef) {
+                return current;
+            }
+            seenRefs.add(currentRefUrl);
+            currentRefUrl = nestedRef;
+            currentDepth++;
+        }
+    }
+}

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

@@ -1,36 +1,41 @@
-/**
- * @file OpenApiTypeMapper.ts
- * @description Utility class for mapping OpenAPI primitive types to MetaUI FieldTypes.
- */
-import { FieldType } from "../interfaces/ISchema";
-
-/**
- * Acts as the translation boundary between raw OpenAPI types and the internal MetaUI FieldType enumerations.
- * This ensures that the core layout engine never has to parse or understand Swagger-specific semantics.
- * 
- * @public
- */
-export class OpenApiTypeMapper {
-    /**
-     * Maps an OpenAPI primitive type string to the closest MetaUI FieldType.
-     * If the type is omitted (common for objects) or unknown, it defaults to "object"
-     * to trigger a safe nested-form fallback behavior.
-     * 
-     * @param {string} openApiType The raw OpenAPI type (e.g., 'string', 'integer').
-     * @returns {FieldType} The mapped MetaUI FieldType strictly understood by the core engine.
-     */
-    public static mapType(openApiType: string): FieldType {
-        const typeMap: Record<string, FieldType> = {
-            "string": "string",
-            "number": "number",
-            "integer": "integer",
-            "boolean": "boolean",
-            "array": "array",
-            "object": "object",
-            "date": "date"
-        };
-        
-        // Default to "object" if the type is unknown or omitted by the API specification.
-        return typeMap[openApiType] || "object";
-    }
-}
+/**
+ * @file OpenApiTypeMapper.ts
+ * @description Utility class for mapping OpenAPI primitive types to MetaUI FieldTypes.
+ */
+import { FieldType } from "../interfaces/ISchema";
+
+/**
+ * Acts as the translation boundary between raw OpenAPI types and the internal MetaUI FieldType enumerations.
+ * This ensures that the core layout engine never has to parse or understand Swagger-specific semantics.
+ *
+ * @internal
+ */
+export class OpenApiTypeMapper {
+    /**
+     * Maps an OpenAPI primitive type string to the closest MetaUI FieldType.
+     * If the type is omitted or unknown, it defaults to `"string"` (aligned with
+     * `SchemaNormalizer` / `SchemaDirectiveNormalizer.resolveSchemaType`, which handles
+     * structural object/array inference from `properties`/`items` before falling back to `"string"`).
+     *
+     * @param {string} openApiType The raw OpenAPI type (e.g., 'string', 'integer').
+     * @returns {FieldType} The mapped MetaUI FieldType strictly understood by the core engine.
+     */
+    public static mapType(openApiType: string): FieldType {
+        // A Map, not an object literal: the spec being mapped is untrusted input, and a plain
+        // object resolves "toString", "constructor" and every other Object.prototype member to an
+        // inherited function, which is truthy and would be returned in place of a FieldType.
+        const typeMap = new Map<string, FieldType>([
+            ["string", "string"],
+            ["file", "string"],
+            ["number", "number"],
+            ["integer", "integer"],
+            ["boolean", "boolean"],
+            ["array", "array"],
+            ["object", "object"],
+            ["date", "date"]
+        ]);
+
+        // Default to "string" if the type is unknown or omitted by the API specification (aligned with SchemaNormalizer).
+        return typeMap.get(openApiType) ?? "string";
+    }
+}