@robinmordasiewicz/f5xc-api-mcp 1.0.82-2512312028

package/dist/generator/openapi-parser.js

@@ -0,0 +1,704 @@
+/**
+ * OpenAPI Specification Parser
+ *
+ * Parses F5 Distributed Cloud OpenAPI specifications and extracts
+ * operation metadata for MCP tool generation.
+ */
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join, extname, relative, basename } from "path";
+import YAML from "yaml";
+import { z } from "zod";
+import { transformText, extractDomainFromPath, extractResourceFromPath, methodToOperation, generateToolName, } from "./naming/index.js";
+import { normalizeTitleAcronyms } from "./naming/acronyms.js";
+import { normalizeExamples } from "./transformers/index.js";
+import { logger } from "../utils/logging.js";
+import { extractOperationDependencies, mapResourceToSubscriptions, formatAddonDisplayName, extractTierFromAddon, resolveResourceDomain, } from "./dependency-extractor.js";
+/**
+ * OpenAPI Schema Types
+ */
+const OpenApiParameterSchema = z.object({
+    name: z.string(),
+    in: z.enum(["path", "query", "header", "cookie"]),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+    schema: z.record(z.string(), z.unknown()).optional(),
+    // Rich metadata fields from enriched specs
+    "x-displayname": z.string().optional(),
+    "x-ves-example": z.string().optional(),
+    "x-ves-validation-rules": z.record(z.string(), z.string()).optional(),
+    "x-ves-required": z.boolean().optional(),
+});
+const OpenApiRequestBodySchema = z.object({
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+    content: z
+        .record(z.string(), z.object({
+        schema: z.record(z.string(), z.unknown()).optional(),
+    }))
+        .optional(),
+});
+const OpenApiResponseSchema = z.object({
+    description: z.string().optional(),
+    content: z
+        .record(z.string(), z.object({
+        schema: z.record(z.string(), z.unknown()).optional(),
+    }))
+        .optional(),
+});
+/**
+ * Side effects schema for operations
+ */
+const SideEffectsSchema = z.object({
+    creates: z.array(z.string()).optional(),
+    modifies: z.array(z.string()).optional(),
+    deletes: z.array(z.string()).optional(),
+});
+/**
+ * Operation metadata schema from enriched specs
+ */
+const OperationMetadataSchema = z.object({
+    purpose: z.string().optional(),
+    required_fields: z.array(z.string()).optional(),
+    optional_fields: z.array(z.string()).optional(),
+    field_docs: z.record(z.string(), z.unknown()).optional(),
+    conditions: z
+        .object({
+        prerequisites: z.array(z.string()).optional(),
+        postconditions: z.array(z.string()).optional(),
+    })
+        .optional(),
+    side_effects: SideEffectsSchema.optional(),
+    danger_level: z.enum(["low", "medium", "high"]).optional(),
+    confirmation_required: z.boolean().optional(),
+    common_errors: z
+        .array(z.object({
+        code: z.number(),
+        message: z.string(),
+        solution: z.string().optional(),
+    }))
+        .optional(),
+    performance_impact: z
+        .object({
+        latency: z.string().optional(),
+        resource_usage: z.string().optional(),
+    })
+        .optional(),
+});
+const OpenApiOperationSchema = z.object({
+    operationId: z.string().optional(),
+    summary: z.string().optional(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    parameters: z.array(OpenApiParameterSchema).optional(),
+    requestBody: OpenApiRequestBodySchema.optional(),
+    responses: z.record(z.string(), OpenApiResponseSchema).optional(),
+    security: z.array(z.record(z.string(), z.array(z.string()))).optional(),
+    // Existing x-* field
+    "x-ves-proto-rpc": z.string().optional(),
+    // Rich metadata fields from enriched specs v1.0.63
+    "x-ves-danger-level": z.enum(["low", "medium", "high"]).optional(),
+    "x-ves-side-effects": SideEffectsSchema.optional(),
+    "x-ves-required-fields": z.array(z.string()).optional(),
+    "x-ves-confirmation-required": z.boolean().optional(),
+    "x-ves-operation-metadata": OperationMetadataSchema.optional(),
+});
+const OpenApiPathItemSchema = z.object({
+    get: OpenApiOperationSchema.optional(),
+    post: OpenApiOperationSchema.optional(),
+    put: OpenApiOperationSchema.optional(),
+    delete: OpenApiOperationSchema.optional(),
+    patch: OpenApiOperationSchema.optional(),
+    parameters: z.array(OpenApiParameterSchema).optional(),
+});
+const OpenApiSpecSchema = z.object({
+    openapi: z.string().optional(),
+    swagger: z.string().optional(),
+    info: z.object({
+        title: z.string(),
+        version: z.string(),
+        description: z.string().optional(),
+    }),
+    paths: z.record(z.string(), OpenApiPathItemSchema).optional(),
+    components: z
+        .object({
+        schemas: z.record(z.string(), z.unknown()).optional(),
+        securitySchemes: z.record(z.string(), z.unknown()).optional(),
+    })
+        .optional(),
+});
+/**
+ * Parse a single OpenAPI specification file
+ * @param filePath - Absolute path to the spec file
+ * @param basePath - Optional base path for creating relative sourceFile paths (for deterministic output)
+ * @deprecated Use parseDomainSpecFile() for pre-enriched domain specs from robinmordasiewicz/f5xc-api-enriched
+ */
+export function parseSpecFile(filePath, basePath) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        const ext = extname(filePath).toLowerCase();
+        let rawSpec;
+        if (ext === ".yaml" || ext === ".yml") {
+            rawSpec = YAML.parse(content);
+        }
+        else if (ext === ".json") {
+            rawSpec = JSON.parse(content);
+        }
+        else {
+            logger.warn(`Unsupported file extension: ${ext}`, { file: filePath });
+            return null;
+        }
+        // Validate spec structure
+        const parseResult = OpenApiSpecSchema.safeParse(rawSpec);
+        if (!parseResult.success) {
+            logger.debug(`Invalid OpenAPI spec: ${filePath}`, {
+                errors: parseResult.error.issues,
+            });
+            return null;
+        }
+        const spec = parseResult.data;
+        // Use relative path for sourceFile to ensure deterministic output across environments
+        const sourceFile = basePath ? relative(basePath, filePath) : filePath;
+        const operations = extractOperations(spec, sourceFile);
+        return {
+            filePath,
+            title: transformText(normalizeTitleAcronyms(spec.info.title)),
+            version: spec.info.version,
+            operations,
+            schemas: spec.components?.schemas ?? {},
+        };
+    }
+    catch (error) {
+        logger.error(`Failed to parse spec file: ${filePath}`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Extract curl examples from component schemas
+ * Returns a map of normalized API path to curl example
+ */
+function extractCurlExamplesFromSchemas(schemas) {
+    const curlExamples = new Map();
+    if (!schemas) {
+        return curlExamples;
+    }
+    for (const schema of Object.values(schemas)) {
+        if (!schema || typeof schema !== "object") {
+            continue;
+        }
+        const schemaObj = schema;
+        const minConfig = schemaObj["x-ves-minimum-configuration"];
+        if (!minConfig || typeof minConfig !== "object") {
+            continue;
+        }
+        const config = minConfig;
+        const exampleCurl = config["example_curl"];
+        if (typeof exampleCurl !== "string") {
+            continue;
+        }
+        // Extract the API path from the curl command
+        // Pattern: $F5XC_API_URL/api/...  or "$F5XC_API_URL/api/..."
+        const pathMatch = exampleCurl.match(/\$F5XC_API_URL(\/api\/[^\s"\\]+)/);
+        if (!pathMatch || !pathMatch[1]) {
+            continue;
+        }
+        const apiPath = pathMatch[1];
+        // Normalize the path by replacing concrete namespace/name values with placeholders
+        // /api/config/namespaces/default/app_firewalls -> /api/config/namespaces/{namespace}/app_firewalls
+        const normalizedPath = apiPath
+            .replace(/\/namespaces\/[^/]+\//, "/namespaces/{namespace}/")
+            .replace(/\/system\//, "/{system_namespace}/");
+        // Store if not already present (first match wins)
+        if (!curlExamples.has(normalizedPath)) {
+            curlExamples.set(normalizedPath, exampleCurl);
+        }
+    }
+    return curlExamples;
+}
+/**
+ * Match an operation path to a curl example
+ * Handles path template differences like {metadata.namespace} vs {namespace}
+ */
+function matchCurlExample(operationPath, curlExamples) {
+    // Normalize the operation path similarly
+    const normalizedOpPath = operationPath
+        .replace(/\{metadata\.namespace\}/g, "{namespace}")
+        .replace(/\{metadata\.name\}/g, "{name}")
+        .replace(/\{[^}]+\}/g, (match) => {
+        // Keep just the last part of dotted names
+        const simplified = match.replace(/\{[^.]+\./g, "{");
+        return simplified;
+    });
+    // Try exact match first
+    if (curlExamples.has(normalizedOpPath)) {
+        return curlExamples.get(normalizedOpPath);
+    }
+    // Try matching the base path (without trailing name/id parameter)
+    // e.g., /api/config/namespaces/{namespace}/resources/{name} -> /api/config/namespaces/{namespace}/resources
+    const basePathMatch = normalizedOpPath.match(/^(.+?)(?:\/\{[^}]+\})?$/);
+    if (basePathMatch && basePathMatch[1]) {
+        const basePath = basePathMatch[1];
+        if (curlExamples.has(basePath)) {
+            return curlExamples.get(basePath);
+        }
+    }
+    return null;
+}
+/**
+ * Extract operations from parsed spec
+ */
+function extractOperations(spec, sourceFile, curlExamples) {
+    const operations = [];
+    if (!spec.paths) {
+        return operations;
+    }
+    // Extract curl examples from schemas if not provided
+    const curlMap = curlExamples ??
+        extractCurlExamplesFromSchemas(spec.components?.schemas);
+    const httpMethods = ["get", "post", "put", "delete", "patch"];
+    // Sort paths alphabetically for deterministic output (use < > for locale-independent sorting)
+    const sortedPaths = Object.entries(spec.paths).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const [path, pathItem] of sortedPaths) {
+        // Check if path has a name parameter (indicates single resource operations)
+        const hasNameParam = path.includes("{name}") || path.includes("{id}");
+        // Get path-level parameters
+        const pathLevelParams = pathItem.parameters ?? [];
+        for (const method of httpMethods) {
+            const operation = pathItem[method];
+            if (!operation) {
+                continue;
+            }
+            // Determine operation type and generate tool name
+            const operationType = methodToOperation(method, hasNameParam);
+            const domain = extractDomainFromPath(path);
+            const resource = extractResourceFromPath(path);
+            const toolName = generateToolName(domain, resource, operationType);
+            // Combine path and operation parameters
+            const allParams = [...pathLevelParams, ...(operation.parameters ?? [])];
+            const pathParameters = allParams.filter((p) => p.in === "path");
+            const queryParameters = allParams.filter((p) => p.in === "query");
+            // Extract request body schema
+            let requestBodySchema = null;
+            if (operation.requestBody?.content) {
+                const jsonContent = operation.requestBody.content["application/json"];
+                if (jsonContent?.schema) {
+                    requestBodySchema = jsonContent.schema;
+                }
+            }
+            // Extract response schema (from 200 or first success response)
+            let responseSchema = null;
+            if (operation.responses) {
+                const successResponse = operation.responses["200"] ?? operation.responses["201"];
+                if (successResponse?.content) {
+                    const jsonContent = successResponse.content["application/json"];
+                    if (jsonContent?.schema) {
+                        responseSchema = jsonContent.schema;
+                    }
+                }
+            }
+            // Collect required parameters
+            const requiredParams = [];
+            for (const param of allParams) {
+                if (param.required) {
+                    requiredParams.push(param.name);
+                }
+            }
+            if (operation.requestBody?.required) {
+                requiredParams.push("body");
+            }
+            // Transform text content and normalize examples
+            const summary = transformText(normalizeTitleAcronyms(operation.summary ?? `${operationType} ${resource}`));
+            const description = normalizeExamples(transformText(operation.description ?? ""));
+            // Normalize parameter descriptions
+            const normalizedPathParams = pathParameters.map((p) => ({
+                ...p,
+                description: p.description ? normalizeExamples(p.description) : p.description,
+            }));
+            const normalizedQueryParams = queryParameters.map((p) => ({
+                ...p,
+                description: p.description ? normalizeExamples(p.description) : p.description,
+            }));
+            // Extract rich metadata from x-* fields (if present in older specs)
+            const dangerLevel = operation["x-ves-danger-level"] ?? null;
+            const sideEffects = operation["x-ves-side-effects"] ?? null;
+            const requiredFields = operation["x-ves-required-fields"] ?? [];
+            const confirmationRequired = operation["x-ves-confirmation-required"] ?? false;
+            const operationMetadata = operation["x-ves-operation-metadata"] ?? null;
+            // Extract parameter-level metadata
+            const parameterExamples = {};
+            const validationRules = {};
+            let displayName = null;
+            for (const param of allParams) {
+                if (param["x-ves-example"]) {
+                    parameterExamples[param.name] = param["x-ves-example"];
+                }
+                if (param["x-ves-validation-rules"]) {
+                    validationRules[param.name] = param["x-ves-validation-rules"];
+                }
+            }
+            // Get path-level displayname if available
+            const pathItemAny = pathItem;
+            if (pathItemAny["x-displayname"] && typeof pathItemAny["x-displayname"] === "string") {
+                displayName = pathItemAny["x-displayname"];
+            }
+            // Match curl example for this operation
+            const curlExample = matchCurlExample(path, curlMap);
+            // Extract dependency intelligence (v1.0.67)
+            const componentSchemas = spec.components?.schemas ?? {};
+            const extractedDeps = extractOperationDependencies(requestBodySchema, componentSchemas);
+            // Resolve domain for each reference
+            const dependencies = extractedDeps.references.map((ref) => ({
+                ...ref,
+                domain: ref.domain || resolveResourceDomain(ref.resourceType),
+            }));
+            // Get subscription requirements based on resource and domain
+            const subscriptionIds = mapResourceToSubscriptions(resource, domain);
+            const subscriptionRequirements = subscriptionIds.map((id) => ({
+                addonService: id,
+                displayName: formatAddonDisplayName(id),
+                tier: extractTierFromAddon(id),
+                required: false, // Heuristic mapping, not strictly required
+            }));
+            operations.push({
+                toolName,
+                method: method.toUpperCase(),
+                path,
+                operation: operationType,
+                domain,
+                resource,
+                summary,
+                description,
+                pathParameters: normalizedPathParams,
+                queryParameters: normalizedQueryParams,
+                requestBodySchema,
+                responseSchema,
+                requiredParams,
+                operationId: operation.operationId ?? null,
+                tags: operation.tags ?? [],
+                sourceFile,
+                // Rich metadata (defaults for backward compatibility)
+                displayName,
+                dangerLevel,
+                sideEffects,
+                requiredFields,
+                confirmationRequired,
+                parameterExamples,
+                validationRules,
+                operationMetadata,
+                curlExample,
+                // Dependency intelligence (v1.0.67)
+                dependencies,
+                oneOfGroups: extractedDeps.oneOfGroups,
+                subscriptionRequirements,
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * Parse all spec files in a directory
+ * @deprecated Use parseDomainsDirectory() for pre-enriched domain specs from robinmordasiewicz/f5xc-api-enriched
+ */
+export function parseSpecDirectory(dirPath) {
+    const specs = [];
+    if (!existsSync(dirPath)) {
+        logger.warn(`Spec directory does not exist: ${dirPath}`);
+        return specs;
+    }
+    // Use parent of dirPath as base for relative paths (makes paths like "raw/filename.json")
+    const basePath = join(dirPath, "..");
+    function scanDir(currentDir) {
+        const entries = readdirSync(currentDir, { withFileTypes: true });
+        // Sort entries alphabetically for deterministic output across different filesystems (locale-independent)
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                scanDir(fullPath);
+            }
+            else if (entry.name.endsWith(".json") ||
+                entry.name.endsWith(".yaml") ||
+                entry.name.endsWith(".yml")) {
+                const spec = parseSpecFile(fullPath, basePath);
+                if (spec && spec.operations.length > 0) {
+                    specs.push(spec);
+                }
+            }
+        }
+    }
+    scanDir(dirPath);
+    logger.info(`Parsed ${specs.length} spec files`, {
+        totalOperations: specs.reduce((sum, s) => sum + s.operations.length, 0),
+    });
+    return specs;
+}
+/**
+ * Get all unique operations across all specs
+ */
+export function getAllOperations(specs) {
+    const operationsMap = new Map();
+    for (const spec of specs) {
+        for (const operation of spec.operations) {
+            // Use tool name as unique key to deduplicate
+            if (!operationsMap.has(operation.toolName)) {
+                operationsMap.set(operation.toolName, operation);
+            }
+        }
+    }
+    // Sort by toolName for deterministic output (locale-independent)
+    return Array.from(operationsMap.values()).sort((a, b) => a.toolName < b.toolName ? -1 : a.toolName > b.toolName ? 1 : 0);
+}
+/**
+ * Group operations by domain
+ */
+export function groupOperationsByDomain(operations) {
+    const grouped = new Map();
+    for (const operation of operations) {
+        const domain = operation.domain;
+        if (!grouped.has(domain)) {
+            grouped.set(domain, []);
+        }
+        grouped.get(domain).push(operation);
+    }
+    // Sort operations within each domain by toolName for deterministic output (locale-independent)
+    for (const ops of grouped.values()) {
+        ops.sort((a, b) => (a.toolName < b.toolName ? -1 : a.toolName > b.toolName ? 1 : 0));
+    }
+    // Return a new Map with sorted domain keys for deterministic iteration order
+    const sortedGrouped = new Map();
+    const sortedDomains = Array.from(grouped.keys()).sort();
+    for (const domain of sortedDomains) {
+        sortedGrouped.set(domain, grouped.get(domain));
+    }
+    return sortedGrouped;
+}
+/**
+ * Extract operations from an enriched domain spec (pre-normalized upstream)
+ * This skips transformation since enriched specs are already normalized
+ */
+function extractDomainOperations(spec, domain, sourceFile, curlExamples) {
+    const operations = [];
+    if (!spec.paths) {
+        return operations;
+    }
+    // Extract curl examples from schemas if not provided
+    const curlMap = curlExamples ??
+        extractCurlExamplesFromSchemas(spec.components?.schemas);
+    const httpMethods = ["get", "post", "put", "delete", "patch"];
+    // Sort paths alphabetically for deterministic output
+    const sortedPaths = Object.entries(spec.paths).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const [path, pathItem] of sortedPaths) {
+        // Check if path has a name parameter (indicates single resource operations)
+        const hasNameParam = path.includes("{name}") || path.includes("{id}");
+        // Get path-level parameters
+        const pathLevelParams = pathItem.parameters ?? [];
+        for (const method of httpMethods) {
+            const operation = pathItem[method];
+            if (!operation) {
+                continue;
+            }
+            // Determine operation type and generate tool name
+            const operationType = methodToOperation(method, hasNameParam);
+            const resource = extractResourceFromPath(path);
+            const toolName = generateToolName(domain, resource, operationType);
+            // Combine path and operation parameters
+            const allParams = [...pathLevelParams, ...(operation.parameters ?? [])];
+            const pathParameters = allParams.filter((p) => p.in === "path");
+            const queryParameters = allParams.filter((p) => p.in === "query");
+            // Extract request body schema
+            let requestBodySchema = null;
+            if (operation.requestBody?.content) {
+                const jsonContent = operation.requestBody.content["application/json"];
+                if (jsonContent?.schema) {
+                    requestBodySchema = jsonContent.schema;
+                }
+            }
+            // Extract response schema (from 200 or first success response)
+            let responseSchema = null;
+            if (operation.responses) {
+                const successResponse = operation.responses["200"] ?? operation.responses["201"];
+                if (successResponse?.content) {
+                    const jsonContent = successResponse.content["application/json"];
+                    if (jsonContent?.schema) {
+                        responseSchema = jsonContent.schema;
+                    }
+                }
+            }
+            // Collect required parameters
+            const requiredParams = [];
+            for (const param of allParams) {
+                if (param.required) {
+                    requiredParams.push(param.name);
+                }
+            }
+            if (operation.requestBody?.required) {
+                requiredParams.push("body");
+            }
+            // Use content as-is - enriched specs are already normalized
+            const summary = operation.summary ?? `${operationType} ${resource}`;
+            const description = operation.description ?? "";
+            // Extract rich metadata from x-* fields (v1.0.63 enriched specs)
+            const dangerLevel = operation["x-ves-danger-level"] ?? null;
+            const sideEffects = operation["x-ves-side-effects"] ?? null;
+            const requiredFields = operation["x-ves-required-fields"] ?? [];
+            const confirmationRequired = operation["x-ves-confirmation-required"] ?? false;
+            const operationMetadata = operation["x-ves-operation-metadata"] ?? null;
+            // Extract parameter-level metadata (examples, validation rules, displaynames)
+            const parameterExamples = {};
+            const validationRules = {};
+            let displayName = null;
+            for (const param of allParams) {
+                // Extract parameter examples
+                if (param["x-ves-example"]) {
+                    parameterExamples[param.name] = param["x-ves-example"];
+                }
+                // Extract validation rules
+                if (param["x-ves-validation-rules"]) {
+                    validationRules[param.name] = param["x-ves-validation-rules"];
+                }
+            }
+            // Get path-level displayname if available (from pathItem)
+            const pathItemAny = pathItem;
+            if (pathItemAny["x-displayname"] && typeof pathItemAny["x-displayname"] === "string") {
+                displayName = pathItemAny["x-displayname"];
+            }
+            // Match curl example for this operation
+            const curlExample = matchCurlExample(path, curlMap);
+            // Extract dependency intelligence (v1.0.67)
+            const componentSchemas = spec.components?.schemas ?? {};
+            const extractedDeps = extractOperationDependencies(requestBodySchema, componentSchemas);
+            // Resolve domain for each reference
+            const dependencies = extractedDeps.references.map((ref) => ({
+                ...ref,
+                domain: ref.domain || resolveResourceDomain(ref.resourceType),
+            }));
+            // Get subscription requirements based on resource and domain
+            const subscriptionIds = mapResourceToSubscriptions(resource, domain);
+            const subscriptionRequirements = subscriptionIds.map((id) => ({
+                addonService: id,
+                displayName: formatAddonDisplayName(id),
+                tier: extractTierFromAddon(id),
+                required: false, // Heuristic mapping, not strictly required
+            }));
+            operations.push({
+                toolName,
+                method: method.toUpperCase(),
+                path,
+                operation: operationType,
+                domain,
+                resource,
+                summary,
+                description,
+                pathParameters,
+                queryParameters,
+                requestBodySchema,
+                responseSchema,
+                requiredParams,
+                operationId: operation.operationId ?? null,
+                tags: operation.tags ?? [],
+                sourceFile,
+                // Rich metadata from enriched specs
+                displayName,
+                dangerLevel,
+                sideEffects,
+                requiredFields,
+                confirmationRequired,
+                parameterExamples,
+                validationRules,
+                operationMetadata,
+                curlExample,
+                // Dependency intelligence (v1.0.67)
+                dependencies,
+                oneOfGroups: extractedDeps.oneOfGroups,
+                subscriptionRequirements,
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * Parse a single enriched domain specification file
+ * Domain is derived from the filename (e.g., load_balancer.json → load_balancer)
+ *
+ * @param filePath - Absolute path to the domain spec file
+ * @param basePath - Optional base path for creating relative sourceFile paths
+ */
+export function parseDomainSpecFile(filePath, basePath) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        const ext = extname(filePath).toLowerCase();
+        if (ext !== ".json") {
+            logger.warn(`Domain specs must be JSON: ${ext}`, { file: filePath });
+            return null;
+        }
+        const rawSpec = JSON.parse(content);
+        // Validate spec structure
+        const parseResult = OpenApiSpecSchema.safeParse(rawSpec);
+        if (!parseResult.success) {
+            logger.debug(`Invalid OpenAPI spec: ${filePath}`, {
+                errors: parseResult.error.issues,
+            });
+            return null;
+        }
+        const spec = parseResult.data;
+        // Derive domain from filename (load_balancer.json → load_balancer)
+        const filename = basename(filePath, ext);
+        const domain = filename.replace(/-/g, "_");
+        // Use relative path for sourceFile to ensure deterministic output
+        const sourceFile = basePath ? relative(basePath, filePath) : filePath;
+        // Extract operations using domain-specific function (no transformations)
+        const operations = extractDomainOperations(spec, domain, sourceFile);
+        // Title is already normalized in enriched specs
+        return {
+            filePath,
+            title: spec.info.title,
+            version: spec.info.version,
+            operations,
+            schemas: spec.components?.schemas ?? {},
+        };
+    }
+    catch (error) {
+        logger.error(`Failed to parse domain spec file: ${filePath}`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Parse all enriched domain specs from a directory
+ * This is the primary entry point for the new enriched spec format
+ *
+ * @param dirPath - Path to the domains directory (specs/domains/)
+ */
+export function parseDomainsDirectory(dirPath) {
+    const specs = [];
+    if (!existsSync(dirPath)) {
+        logger.warn(`Domains directory does not exist: ${dirPath}`);
+        return specs;
+    }
+    // Use parent of dirPath as base for relative paths (makes paths like "domains/filename.json")
+    const basePath = join(dirPath, "..");
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    // Sort entries alphabetically for deterministic output
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            continue;
+        }
+        if (!entry.name.endsWith(".json")) {
+            continue;
+        }
+        const fullPath = join(dirPath, entry.name);
+        const spec = parseDomainSpecFile(fullPath, basePath);
+        if (spec && spec.operations.length > 0) {
+            specs.push(spec);
+        }
+    }
+    logger.info(`Parsed ${specs.length} domain spec files`, {
+        totalOperations: specs.reduce((sum, s) => sum + s.operations.length, 0),
+        domains: specs.map((s) => basename(s.filePath, ".json")),
+    });
+    return specs;
+}
+//# sourceMappingURL=openapi-parser.js.map