@zuplo/cli 6.63.4 → 6.63.6

package/dist/open-api/overlay/handler.js

@@ -3,41 +3,26 @@ import path from "node:path";
 import { detectFormatFromExtension, parseFile, serializeContent, } from "../../common/file-format.js";
 import { printDiagnosticsToConsole } from "../../common/output.js";
 import { logger } from "../../common/logger.js";
-import { applyOverlay as applyOverlayEngine, applyAction, deepClone, } from "./overlay-engine.js";
+import { applyOverlay as applyOverlayEngine } from "./overlay-engine.js";
 function applyOverlayWithProgress(openapi, overlay) {
-    printDiagnosticsToConsole(`\nApplying overlay: ${overlay.info?.title || "Unnamed"}`);
-    printDiagnosticsToConsole(`Version: ${overlay.overlay || "unknown"}\n`);
-    const result = deepClone(openapi);
-    const stats = { applied: 0, skipped: 0, totalNodes: 0 };
-    for (const [index, action] of overlay.actions.entries()) {
-        const desc = action.description || `Action ${index + 1}`;
-        process.stdout.write(`  [${index + 1}/${overlay.actions.length}] ${desc}... `);
-        try {
-            const { applied, count } = applyAction(result, action);
-            if (applied) {
-                printDiagnosticsToConsole(`✓ (${count} node${count !== 1 ? "s" : ""})`);
-                stats.applied++;
-                stats.totalNodes += count;
-            }
-            else {
-                printDiagnosticsToConsole("⊘ skipped");
-                stats.skipped++;
-            }
-        }
-        catch (error) {
-            printDiagnosticsToConsole(`✗ failed`);
-            logger.warn(error, `Failed to apply action: ${desc}`);
-            stats.skipped++;
+    let validatedOverlay;
+    try {
+        validatedOverlay = applyOverlayEngine(openapi, overlay);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            printDiagnosticsToConsole(`\n${error.message}`);
         }
+        throw error;
     }
+    const { result, stats } = validatedOverlay;
     printDiagnosticsToConsole(`\n=== Summary ===`);
-    printDiagnosticsToConsole(`Applied: ${stats.applied}/${overlay.actions.length} actions`);
-    printDiagnosticsToConsole(`Modified: ${stats.totalNodes} nodes`);
+    printDiagnosticsToConsole(`Applied: ${stats.applied} action${stats.applied !== 1 ? "s" : ""}`);
+    printDiagnosticsToConsole(`Modified: ${stats.totalNodes} node${stats.totalNodes !== 1 ? "s" : ""}`);
     if (stats.skipped > 0) {
-        printDiagnosticsToConsole(`Skipped: ${stats.skipped} actions`);
+        printDiagnosticsToConsole(`Skipped: ${stats.skipped} action${stats.skipped !== 1 ? "s" : ""}`);
     }
-    const { result: finalResult } = applyOverlayEngine(openapi, overlay);
-    return finalResult;
+    return result;
 }
 export async function applyOverlay(args) {
     const openapiPath = path.resolve(args.input);
@@ -57,10 +42,25 @@ export async function applyOverlay(args) {
     try {
         const openapiContent = fs.readFileSync(openapiPath, "utf-8");
         const overlayContent = fs.readFileSync(overlayPath, "utf-8");
-        const { document: openapi } = parseFile(openapiContent, openapiPath);
-        const { document: overlay } = parseFile(overlayContent, overlayPath);
-        if (!overlay.overlay || !overlay.actions) {
-            throw new Error("Invalid overlay format. Must include 'overlay' version and 'actions' array.");
+        let openapi;
+        let overlay;
+        try {
+            const parsed = parseFile(openapiContent, openapiPath);
+            openapi = parsed.document;
+        }
+        catch (error) {
+            throw new Error(`Failed to parse OpenAPI file '${openapiPath}'`, {
+                cause: error,
+            });
+        }
+        try {
+            const parsed = parseFile(overlayContent, overlayPath);
+            overlay = parsed.document;
+        }
+        catch (error) {
+            throw new Error(`Failed to parse overlay file '${overlayPath}'`, {
+                cause: error,
+            });
         }
         const result = applyOverlayWithProgress(openapi, overlay);
         let outputFormat;

package/dist/open-api/overlay/handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/open-api/overlay/handler.ts"],"names":[],"mappings":"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","sourcesContent":["/** biome-ignore-all lint/suspicious/noConsole: CLI output file */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  detectFormatFromExtension,\n  parseFile,\n  serializeContent,\n  type FileFormat,\n} from \"../../common/file-format.js\";\nimport { printDiagnosticsToConsole } from \"../../common/output.js\";\nimport { logger } from \"../../common/logger.js\";\nimport {\n  applyOverlay as applyOverlayEngine,\n  applyAction,\n  deepClone,\n  type OverlayDocument,\n} from \"./overlay-engine.js\";\n\nexport interface Arguments {\n  overlay: string;\n  input: string;\n  output: string;\n  format?: \"json\" | \"yaml\";\n  json?: boolean;\n  yaml?: boolean;\n}\n\n/**\n * Apply overlay to OpenAPI document with console output\n */\n// biome-ignore lint/suspicious/noExplicitAny: Working with dynamic JSON structures\nfunction applyOverlayWithProgress(openapi: any, overlay: OverlayDocument): any {\n  printDiagnosticsToConsole(\n    `\\nApplying overlay: ${overlay.info?.title || \"Unnamed\"}`\n  );\n  printDiagnosticsToConsole(`Version: ${overlay.overlay || \"unknown\"}\\n`);\n\n  // Clone the document for modification\n  const result = deepClone(openapi);\n  const stats = { applied: 0, skipped: 0, totalNodes: 0 };\n\n  // Apply actions with progress reporting\n  for (const [index, action] of overlay.actions.entries()) {\n    const desc = action.description || `Action ${index + 1}`;\n    process.stdout.write(\n      `  [${index + 1}/${overlay.actions.length}] ${desc}... `\n    );\n\n    try {\n      const { applied, count } = applyAction(result, action);\n\n      if (applied) {\n        printDiagnosticsToConsole(`✓ (${count} node${count !== 1 ? \"s\" : \"\"})`);\n        stats.applied++;\n        stats.totalNodes += count;\n      } else {\n        printDiagnosticsToConsole(\"⊘ skipped\");\n        stats.skipped++;\n      }\n    } catch (error) {\n      printDiagnosticsToConsole(`✗ failed`);\n      logger.warn(error, `Failed to apply action: ${desc}`);\n      stats.skipped++;\n    }\n  }\n\n  printDiagnosticsToConsole(`\\n=== Summary ===`);\n  printDiagnosticsToConsole(\n    `Applied: ${stats.applied}/${overlay.actions.length} actions`\n  );\n  printDiagnosticsToConsole(`Modified: ${stats.totalNodes} nodes`);\n  if (stats.skipped > 0) {\n    printDiagnosticsToConsole(`Skipped: ${stats.skipped} actions`);\n  }\n\n  // Use the engine's reordering functions\n  const { result: finalResult } = applyOverlayEngine(openapi, overlay);\n\n  return finalResult;\n}\n\n/**\n * Main handler function\n */\nexport async function applyOverlay(args: Arguments): Promise<void> {\n  const openapiPath = path.resolve(args.input);\n  const overlayPath = path.resolve(args.overlay);\n  const outputPath = path.resolve(args.output);\n\n  // Validate input files exist\n  if (!fs.existsSync(openapiPath)) {\n    throw new Error(`OpenAPI file not found: ${openapiPath}`);\n  }\n\n  if (!fs.existsSync(overlayPath)) {\n    throw new Error(`Overlay file not found: ${overlayPath}`);\n  }\n\n  printDiagnosticsToConsole(\"OpenAPI Overlay Applicator\");\n  printDiagnosticsToConsole(\"===========================\");\n  printDiagnosticsToConsole(`OpenAPI file: ${openapiPath}`);\n  printDiagnosticsToConsole(`Overlay file: ${overlayPath}`);\n  printDiagnosticsToConsole(`Output file:  ${outputPath}`);\n\n  try {\n    // Load files with flexible parsing\n    const openapiContent = fs.readFileSync(openapiPath, \"utf-8\");\n    const overlayContent = fs.readFileSync(overlayPath, \"utf-8\");\n\n    // Parse with automatic format detection\n    const { document: openapi } = parseFile(openapiContent, openapiPath);\n    const { document: overlay } = parseFile(overlayContent, overlayPath);\n\n    // Validate overlay format\n    if (!overlay.overlay || !overlay.actions) {\n      throw new Error(\n        \"Invalid overlay format. Must include 'overlay' version and 'actions' array.\"\n      );\n    }\n\n    // Apply overlay with progress output\n    const result = applyOverlayWithProgress(\n      openapi,\n      overlay as OverlayDocument\n    );\n\n    // Determine output format\n    let outputFormat: FileFormat;\n    if (args.format) {\n      outputFormat = args.format;\n    } else if (args.json) {\n      outputFormat = \"json\";\n    } else if (args.yaml) {\n      outputFormat = \"yaml\";\n    } else {\n      // Try to detect from output file extension\n      const formatFromExt = detectFormatFromExtension(outputPath);\n      outputFormat = formatFromExt || \"json\"; // Default to JSON if no extension\n    }\n\n    // Serialize output\n    const outputContent = serializeContent(result, outputFormat);\n\n    // Create output directory if it doesn't exist\n    const outputDir = path.dirname(outputPath);\n    if (!fs.existsSync(outputDir)) {\n      fs.mkdirSync(outputDir, { recursive: true });\n    }\n\n    fs.writeFileSync(outputPath, outputContent, \"utf-8\");\n\n    printDiagnosticsToConsole(\n      `\\n✓ Output written to: ${outputPath} (${outputFormat.toUpperCase()})`\n    );\n  } catch (error) {\n    logger.error(error, \"Error applying overlay\");\n    printDiagnosticsToConsole(`Error: ${(error as Error).message}`);\n    throw error;\n  }\n}\n"]}
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/open-api/overlay/handler.ts"],"names":[],"mappings":"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","sourcesContent":["/** biome-ignore-all lint/suspicious/noConsole: CLI output file */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  detectFormatFromExtension,\n  parseFile,\n  serializeContent,\n  type FileFormat,\n} from \"../../common/file-format.js\";\nimport { printDiagnosticsToConsole } from \"../../common/output.js\";\nimport { logger } from \"../../common/logger.js\";\nimport { applyOverlay as applyOverlayEngine } from \"./overlay-engine.js\";\n\nexport interface Arguments {\n  overlay: string;\n  input: string;\n  output: string;\n  format?: \"json\" | \"yaml\";\n  json?: boolean;\n  yaml?: boolean;\n}\n\n/**\n * Apply overlay to OpenAPI document with console output\n * Validates inputs and provides progress feedback\n */\nfunction applyOverlayWithProgress(\n  openapi: unknown,\n  overlay: unknown\n): Record<string, unknown> {\n  // Apply overlay (includes validation)\n  let validatedOverlay: ReturnType<typeof applyOverlayEngine>;\n\n  try {\n    validatedOverlay = applyOverlayEngine(openapi, overlay);\n  } catch (error) {\n    // Re-throw with better context for CLI users\n    if (error instanceof Error) {\n      printDiagnosticsToConsole(`\\n${error.message}`);\n    }\n    throw error;\n  }\n\n  const { result, stats } = validatedOverlay;\n\n  // Show summary\n  printDiagnosticsToConsole(`\\n=== Summary ===`);\n  printDiagnosticsToConsole(\n    `Applied: ${stats.applied} action${stats.applied !== 1 ? \"s\" : \"\"}`\n  );\n  printDiagnosticsToConsole(\n    `Modified: ${stats.totalNodes} node${stats.totalNodes !== 1 ? \"s\" : \"\"}`\n  );\n  if (stats.skipped > 0) {\n    printDiagnosticsToConsole(\n      `Skipped: ${stats.skipped} action${stats.skipped !== 1 ? \"s\" : \"\"}`\n    );\n  }\n\n  return result;\n}\n\n/**\n * Main handler function\n */\nexport async function applyOverlay(args: Arguments): Promise<void> {\n  const openapiPath = path.resolve(args.input);\n  const overlayPath = path.resolve(args.overlay);\n  const outputPath = path.resolve(args.output);\n\n  // Validate input files exist\n  if (!fs.existsSync(openapiPath)) {\n    throw new Error(`OpenAPI file not found: ${openapiPath}`);\n  }\n\n  if (!fs.existsSync(overlayPath)) {\n    throw new Error(`Overlay file not found: ${overlayPath}`);\n  }\n\n  printDiagnosticsToConsole(\"OpenAPI Overlay Applicator\");\n  printDiagnosticsToConsole(\"===========================\");\n  printDiagnosticsToConsole(`OpenAPI file: ${openapiPath}`);\n  printDiagnosticsToConsole(`Overlay file: ${overlayPath}`);\n  printDiagnosticsToConsole(`Output file:  ${outputPath}`);\n\n  try {\n    // Load files with flexible parsing\n    const openapiContent = fs.readFileSync(openapiPath, \"utf-8\");\n    const overlayContent = fs.readFileSync(overlayPath, \"utf-8\");\n\n    // Parse with automatic format detection\n    let openapi: unknown;\n    let overlay: unknown;\n\n    try {\n      const parsed = parseFile(openapiContent, openapiPath);\n      openapi = parsed.document;\n    } catch (error) {\n      throw new Error(`Failed to parse OpenAPI file '${openapiPath}'`, {\n        cause: error,\n      });\n    }\n\n    try {\n      const parsed = parseFile(overlayContent, overlayPath);\n      overlay = parsed.document;\n    } catch (error) {\n      throw new Error(`Failed to parse overlay file '${overlayPath}'`, {\n        cause: error,\n      });\n    }\n\n    // Apply overlay with progress output\n    // Validation happens inside applyOverlayWithProgress\n    const result = applyOverlayWithProgress(openapi, overlay);\n\n    // Determine output format\n    let outputFormat: FileFormat;\n    if (args.format) {\n      outputFormat = args.format;\n    } else if (args.json) {\n      outputFormat = \"json\";\n    } else if (args.yaml) {\n      outputFormat = \"yaml\";\n    } else {\n      // Try to detect from output file extension\n      const formatFromExt = detectFormatFromExtension(outputPath);\n      outputFormat = formatFromExt || \"json\"; // Default to JSON if no extension\n    }\n\n    // Serialize output\n    const outputContent = serializeContent(result, outputFormat);\n\n    // Create output directory if it doesn't exist\n    const outputDir = path.dirname(outputPath);\n    if (!fs.existsSync(outputDir)) {\n      fs.mkdirSync(outputDir, { recursive: true });\n    }\n\n    fs.writeFileSync(outputPath, outputContent, \"utf-8\");\n\n    printDiagnosticsToConsole(\n      `\\n✓ Output written to: ${outputPath} (${outputFormat.toUpperCase()})`\n    );\n  } catch (error) {\n    logger.error(error, \"Error applying overlay\");\n    printDiagnosticsToConsole(`Error: ${(error as Error).message}`);\n    throw error;\n  }\n}\n"]}

package/dist/open-api/overlay/overlay-engine.d.ts

@@ -1,22 +1,8 @@
-export interface OverlayDocument {
-  overlay: string;
-  info: {
-    title: string;
-    version: string;
-  };
-  actions: OverlayAction[];
-  extends?: string;
-}
-export interface OverlayAction {
-  target: string;
-  description?: string;
-  update?: any;
-  remove?: boolean | RemoveCondition;
-}
-export interface RemoveCondition {
-  empty?: boolean;
-  missing?: string;
-}
+import {
+  type OverlayAction,
+  type OverlayDocument,
+  type RemoveCondition,
+} from "../../common/open-api/index.js";
 export interface ApplyResult {
   applied: boolean;
   count: number;
@@ -27,29 +13,33 @@ export interface OverlayStats {
   totalNodes: number;
 }
 export declare function deepClone<T>(obj: T): T;
-export declare function deepMerge(target: any, source: any): any;
+export declare function deepMerge(target: unknown, source: unknown): unknown;
 export declare function checkCondition(
-  value: any,
+  value: unknown,
   condition: RemoveCondition
 ): boolean;
 export declare function setValueAtPath(
-  doc: any,
+  doc: unknown,
   target: string,
-  value: any
+  value: unknown
 ): void;
 export declare function applyAction(
-  doc: any,
+  doc: unknown,
   action: OverlayAction
 ): ApplyResult;
 export declare function extractPathOrder(overlay: OverlayDocument): string[];
-export declare function reorderOperationProperties(operation: any): any;
-export declare function reorderPaths(doc: any, pathOrder: string[]): any;
-export declare function reorderDocumentProperties(doc: any): any;
+export declare function reorderOperationProperties(
+  operation: unknown
+): Record<string, unknown>;
+export declare function reorderPaths<T>(doc: T, pathOrder: string[]): T;
+export declare function reorderDocumentProperties(
+  doc: unknown
+): Record<string, unknown>;
 export declare function applyOverlay(
-  openapi: any,
-  overlay: OverlayDocument
+  openapi: unknown,
+  overlay: unknown
 ): {
-  result: any;
+  result: Record<string, unknown>;
   stats: OverlayStats;
 };
 //# sourceMappingURL=overlay-engine.d.ts.map

package/dist/open-api/overlay/overlay-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay-engine.d.ts","sourceRoot":"","sources":["../../../src/open-api/overlay/overlay-engine.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAKtC;AAMD,wBAAgB,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,CAgDvD;AAKD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,eAAe,GACzB,OAAO,CA2BT;AAyCD,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAuCzE;AAKD,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,CA+ExE;AAMD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAiBnE;AAKD,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,CAmB9D;AAKD,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,GAAG,CAiD/D;AAMD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAmBvD;AAQD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,GAAG,EACZ,OAAO,EAAE,eAAe,GACvB;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CA8BtC"}
+{"version":3,"file":"overlay-engine.d.ts","sourceRoot":"","sources":["../../../src/open-api/overlay/overlay-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,gCAAgC,CAAC;AAExC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAmBD,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAKtC;AAQD,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CA+DnE;AAKD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,eAAe,GACzB,OAAO,CAgCT;AAyCD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAyCN;AAKD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,CA2F5E;AAMD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAiBnE;AAMD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,OAAO,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB;AAMD,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,CAkD9D;AAOD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB;AAmBD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GACf;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CA6B1D"}

package/dist/open-api/overlay/overlay-engine.js

@@ -1,4 +1,11 @@
 import { JSONPath } from "jsonpath-plus";
+import { HTTP_METHODS, validateOpenApiDocument, validateOverlayDocument, } from "../../common/open-api/index.js";
+function toRecord(value, context) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`Expected object at ${context}, but got ${Array.isArray(value) ? "array" : typeof value}`);
+    }
+    return value;
+}
 export function deepClone(obj) {
     if (typeof structuredClone === "function") {
         return structuredClone(obj);
@@ -17,11 +24,22 @@ export function deepMerge(target, source) {
             return deepClone(source);
         }
         if (source.length > 0 &&
-            source[0].name !== undefined &&
-            source[0].in !== undefined) {
+            typeof source[0] === "object" &&
+            source[0] !== null &&
+            "name" in source[0] &&
+            "in" in source[0]) {
             const merged = [...target];
             for (const sourceParam of source) {
-                const existingIndex = merged.findIndex((p) => p.name === sourceParam.name && p.in === sourceParam.in);
+                if (typeof sourceParam !== "object" || sourceParam === null)
+                    continue;
+                const existingIndex = merged.findIndex((p) => typeof p === "object" &&
+                    p !== null &&
+                    "name" in p &&
+                    "in" in p &&
+                    "name" in sourceParam &&
+                    "in" in sourceParam &&
+                    p.name === sourceParam.name &&
+                    p.in === sourceParam.in);
                 if (existingIndex >= 0) {
                     merged[existingIndex] = deepMerge(merged[existingIndex], sourceParam);
                 }
@@ -33,8 +51,10 @@ export function deepMerge(target, source) {
         }
         return [...target, ...deepClone(source)];
     }
-    const result = { ...target };
-    for (const [key, value] of Object.entries(source)) {
+    const targetObj = target;
+    const sourceObj = source;
+    const result = { ...targetObj };
+    for (const [key, value] of Object.entries(sourceObj)) {
         if (key in result) {
             result[key] = deepMerge(result[key], value);
         }
@@ -58,7 +78,10 @@ export function checkCondition(value, condition) {
         const parts = condition.missing.split(".");
         let current = value;
         for (const part of parts) {
-            if (current && typeof current === "object" && part in current) {
+            if (current &&
+                typeof current === "object" &&
+                !Array.isArray(current) &&
+                part in current) {
                 current = current[part];
             }
             else {
@@ -83,7 +106,7 @@ function extractBracketKey(bracketNotation) {
 export function setValueAtPath(doc, target, value) {
     const targetPath = target.replace(/^\$\./, "");
     const parts = targetPath.match(JSONPATH_SEGMENT_PATTERN) || [];
-    let current = doc;
+    let current = toRecord(doc, "setValueAtPath document");
     for (let i = 0; i < parts.length - 1; i++) {
         const part = parts[i];
         if (part.startsWith("[")) {
@@ -91,13 +114,15 @@ export function setValueAtPath(doc, target, value) {
             if (!(key in current)) {
                 current[key] = {};
             }
-            current = current[key];
+            const next = current[key];
+            current = toRecord(next, `setValueAtPath at ${target}[${i}]`);
         }
         else {
             if (!(part in current)) {
                 current[part] = {};
             }
-            current = current[part];
+            const next = current[part];
+            current = toRecord(next, `setValueAtPath at ${target}.${part}`);
         }
     }
     const lastPart = parts[parts.length - 1];
@@ -110,9 +135,10 @@ export function setValueAtPath(doc, target, value) {
     }
 }
 export function applyAction(doc, action) {
+    const docRecord = toRecord(doc, "applyAction document");
     if (action.update) {
         if (action.target === "$") {
-            Object.assign(doc, deepMerge(doc, action.update));
+            Object.assign(docRecord, deepMerge(doc, action.update));
             return { applied: true, count: 1 };
         }
         try {
@@ -125,8 +151,12 @@ export function applyAction(doc, action) {
                 let count = 0;
                 for (const result of results) {
                     const { parent, parentProperty } = result;
-                    if (parent && parentProperty !== undefined) {
-                        parent[parentProperty] = deepMerge(parent[parentProperty], action.update);
+                    if (parent &&
+                        typeof parent === "object" &&
+                        !Array.isArray(parent) &&
+                        parentProperty !== undefined) {
+                        const parentRecord = parent;
+                        parentRecord[parentProperty] = deepMerge(parentRecord[parentProperty], action.update);
                         count++;
                     }
                 }
@@ -135,8 +165,8 @@ export function applyAction(doc, action) {
             setValueAtPath(doc, action.target, action.update);
             return { applied: true, count: 1 };
         }
-        catch (error) {
-            throw new Error(`Failed to apply update: ${error.message}`);
+        catch (cause) {
+            throw new Error("Failed to apply update", { cause });
         }
     }
     else if (action.remove) {
@@ -160,7 +190,7 @@ export function applyAction(doc, action) {
                     if (Array.isArray(parent)) {
                         parent.splice(parentProperty, 1);
                     }
-                    else {
+                    else if (typeof parent === "object" && parent !== null) {
                         delete parent[parentProperty];
                     }
                     count++;
@@ -168,8 +198,8 @@ export function applyAction(doc, action) {
             }
             return { applied: true, count };
         }
-        catch (error) {
-            throw new Error(`Failed to remove: ${error.message}`);
+        catch (cause) {
+            throw new Error("Failed to remove", { cause });
         }
     }
     return { applied: false, count: 0 };
@@ -190,14 +220,15 @@ export function extractPathOrder(overlay) {
     return pathOrder;
 }
 export function reorderOperationProperties(operation) {
+    const operationObj = toRecord(operation, "reorderOperationProperties");
     const priorityKeys = ["summary", "description", "operationId"];
     const reordered = {};
     for (const key of priorityKeys) {
-        if (key in operation) {
-            reordered[key] = operation[key];
+        if (key in operationObj) {
+            reordered[key] = operationObj[key];
         }
     }
-    for (const [key, value] of Object.entries(operation)) {
+    for (const [key, value] of Object.entries(operationObj)) {
         if (!priorityKeys.includes(key)) {
             reordered[key] = value;
         }
@@ -205,10 +236,14 @@ export function reorderOperationProperties(operation) {
     return reordered;
 }
 export function reorderPaths(doc, pathOrder) {
-    if (!doc.paths || pathOrder.length === 0) {
+    if (typeof doc !== "object" ||
+        doc === null ||
+        !("paths" in doc) ||
+        pathOrder.length === 0) {
         return doc;
     }
-    const originalPaths = doc.paths;
+    const docRecord = doc;
+    const originalPaths = toRecord(docRecord.paths, "paths");
     const reorderedPaths = {};
     for (const targetPath of pathOrder) {
         if (targetPath in originalPaths) {
@@ -221,35 +256,30 @@ export function reorderPaths(doc, pathOrder) {
         }
     }
     for (const pathItem of Object.values(reorderedPaths)) {
-        const httpMethods = [
-            "get",
-            "post",
-            "put",
-            "patch",
-            "delete",
-            "options",
-            "head",
-            "trace",
-        ];
-        for (const method of httpMethods) {
-            if (pathItem[method] &&
-                typeof pathItem[method] === "object") {
-                pathItem[method] = reorderOperationProperties(pathItem[method]);
+        if (typeof pathItem !== "object" || pathItem === null)
+            continue;
+        const pathItemRecord = pathItem;
+        for (const method of HTTP_METHODS) {
+            if (method in pathItemRecord &&
+                typeof pathItemRecord[method] === "object" &&
+                pathItemRecord[method] !== null) {
+                pathItemRecord[method] = reorderOperationProperties(pathItemRecord[method]);
             }
         }
     }
-    doc.paths = reorderedPaths;
+    docRecord.paths = reorderedPaths;
     return doc;
 }
 export function reorderDocumentProperties(doc) {
+    const docObj = toRecord(doc, "reorderDocumentProperties");
     const priorityKeys = ["openapi", "info", "tags"];
     const reordered = {};
     for (const key of priorityKeys) {
-        if (key in doc) {
-            reordered[key] = doc[key];
+        if (key in docObj) {
+            reordered[key] = docObj[key];
         }
     }
-    for (const [key, value] of Object.entries(doc)) {
+    for (const [key, value] of Object.entries(docObj)) {
         if (!priorityKeys.includes(key)) {
             reordered[key] = value;
         }
@@ -257,12 +287,11 @@ export function reorderDocumentProperties(doc) {
     return reordered;
 }
 export function applyOverlay(openapi, overlay) {
-    if (!overlay.overlay || !overlay.actions) {
-        throw new Error("Invalid overlay format. Must include 'overlay' version and 'actions' array.");
-    }
-    const result = deepClone(openapi);
+    const validatedOverlay = validateOverlayDocument(overlay);
+    const validatedOpenApi = validateOpenApiDocument(openapi);
+    const result = deepClone(validatedOpenApi);
     const stats = { applied: 0, skipped: 0, totalNodes: 0 };
-    for (const action of overlay.actions) {
+    for (const action of validatedOverlay.actions) {
         const { applied, count } = applyAction(result, action);
         if (applied) {
             stats.applied++;
@@ -272,7 +301,7 @@ export function applyOverlay(openapi, overlay) {
             stats.skipped++;
         }
     }
-    const pathOrder = extractPathOrder(overlay);
+    const pathOrder = extractPathOrder(validatedOverlay);
     reorderPaths(result, pathOrder);
     const reordered = reorderDocumentProperties(result);
     return { result: reordered, stats };

package/dist/open-api/overlay/overlay-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"overlay-engine.js","sourceRoot":"","sources":["../../../src/open-api/overlay/overlay-engine.ts"],"names":[],"mappings":"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","sourcesContent":["/** biome-ignore-all lint/suspicious/noExplicitAny: Complex overlay algorithm working with dynamic JSON structures */\nimport { JSONPath } from \"jsonpath-plus\";\n\nexport interface OverlayDocument {\n  overlay: string;\n  info: {\n    title: string;\n    version: string;\n  };\n  actions: OverlayAction[];\n  extends?: string;\n}\n\nexport interface OverlayAction {\n  target: string;\n  description?: string;\n  update?: any;\n  remove?: boolean | RemoveCondition;\n}\n\nexport interface RemoveCondition {\n  empty?: boolean;\n  missing?: string;\n}\n\nexport interface ApplyResult {\n  applied: boolean;\n  count: number;\n}\n\nexport interface OverlayStats {\n  applied: number;\n  skipped: number;\n  totalNodes: number;\n}\n\n/**\n * Deep clone an object using structuredClone for better performance and correctness\n * Falls back to JSON parse/stringify for environments without structuredClone\n */\nexport function deepClone<T>(obj: T): T {\n  if (typeof structuredClone === \"function\") {\n    return structuredClone(obj);\n  }\n  return JSON.parse(JSON.stringify(obj));\n}\n\n/**\n * Deep merge two objects\n * Special handling for OpenAPI parameters (merge by name+in)\n */\nexport function deepMerge(target: any, source: any): any {\n  if (!source || typeof source !== \"object\") {\n    return source;\n  }\n\n  if (!target || typeof target !== \"object\") {\n    return deepClone(source);\n  }\n\n  if (Array.isArray(source)) {\n    if (!Array.isArray(target)) {\n      return deepClone(source);\n    }\n\n    // Special case for OpenAPI parameters - merge by name+in\n    if (\n      source.length > 0 &&\n      source[0].name !== undefined &&\n      source[0].in !== undefined\n    ) {\n      const merged = [...target];\n      for (const sourceParam of source) {\n        const existingIndex = merged.findIndex(\n          (p) => p.name === sourceParam.name && p.in === sourceParam.in\n        );\n        if (existingIndex >= 0) {\n          merged[existingIndex] = deepMerge(merged[existingIndex], sourceParam);\n        } else {\n          merged.push(deepClone(sourceParam));\n        }\n      }\n      return merged;\n    }\n\n    // For other arrays, concatenate\n    return [...target, ...deepClone(source)];\n  }\n\n  const result = { ...target };\n  for (const [key, value] of Object.entries(source)) {\n    if (key in result) {\n      result[key] = deepMerge(result[key], value);\n    } else {\n      result[key] = deepClone(value);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Check if a condition is met for conditional removal\n */\nexport function checkCondition(\n  value: any,\n  condition: RemoveCondition\n): boolean {\n  // Support \"empty\" condition to check if object has no keys\n  if (condition.empty) {\n    if (typeof value === \"object\" && value !== null && !Array.isArray(value)) {\n      return Object.keys(value).length === 0;\n    }\n    if (Array.isArray(value)) {\n      return value.length === 0;\n    }\n    return false;\n  }\n\n  // Support \"missing\" condition to check if a property doesn't exist\n  if (condition.missing) {\n    const parts = condition.missing.split(\".\");\n    let current = value;\n    for (const part of parts) {\n      if (current && typeof current === \"object\" && part in current) {\n        current = current[part];\n      } else {\n        return true; // Property is missing\n      }\n    }\n    return false; // Property exists\n  }\n\n  return false;\n}\n\n/**\n * Regular expression for parsing JSONPath segments\n * Matches: word, or [quoted], or ['quoted'], or [\"quoted\"], or numeric indices [0]\n */\nconst JSONPATH_SEGMENT_PATTERN = /[^.[]+|\\[[^\\]]+\\]/g;\n\n/**\n * Extract key from bracket notation, handling various formats:\n * - ['key'] -> key\n * - [\"key\"] -> key\n * - [key] -> key\n * - [0] -> 0 (as string for consistency)\n */\nfunction extractBracketKey(bracketNotation: string): string {\n  const inner = bracketNotation.slice(1, -1); // Remove [ and ]\n\n  // Handle single-quoted: ['key'] -> key\n  if (inner.startsWith(\"'\") && inner.endsWith(\"'\")) {\n    return inner.slice(1, -1);\n  }\n\n  // Handle double-quoted: [\"key\"] -> key\n  if (inner.startsWith('\"') && inner.endsWith('\"')) {\n    return inner.slice(1, -1);\n  }\n\n  // Handle unquoted: [key] or [0] -> key or 0\n  return inner;\n}\n\n/**\n * Set a value at a JSONPath, creating parent paths as needed\n * Handles patterns like:\n *   $.paths['/route'].method\n *   $.components.parameters['name']\n *   $.paths[\"/users\"].get\n *   $.paths[users].get\n *   $.items[0].value\n */\nexport function setValueAtPath(doc: any, target: string, value: any): void {\n  // Parse the path manually to handle both bracket and dot notation\n  // Example: $.paths['/route'].post -> [\"paths\", \"['/route']\", \"post\"]\n\n  // Remove leading $.\n  const targetPath = target.replace(/^\\$\\./, \"\");\n\n  // Split by dots, but keep bracket notation together\n  const parts = targetPath.match(JSONPATH_SEGMENT_PATTERN) || [];\n\n  let current = doc;\n\n  for (let i = 0; i < parts.length - 1; i++) {\n    const part = parts[i];\n\n    // Handle bracket notation\n    if (part.startsWith(\"[\")) {\n      const key = extractBracketKey(part);\n      if (!(key in current)) {\n        current[key] = {};\n      }\n      current = current[key];\n    } else {\n      // Handle regular property\n      if (!(part in current)) {\n        current[part] = {};\n      }\n      current = current[part];\n    }\n  }\n\n  // Set the final value\n  const lastPart = parts[parts.length - 1];\n  if (lastPart.startsWith(\"[\")) {\n    const key = extractBracketKey(lastPart);\n    current[key] = value;\n  } else {\n    current[lastPart] = value;\n  }\n}\n\n/**\n * Apply a single overlay action to the document\n */\nexport function applyAction(doc: any, action: OverlayAction): ApplyResult {\n  if (action.update) {\n    // Handle root level updates specially\n    if (action.target === \"$\") {\n      Object.assign(doc, deepMerge(doc, action.update));\n      return { applied: true, count: 1 };\n    }\n\n    try {\n      // Try to find existing nodes\n      const results = JSONPath({\n        path: action.target,\n        json: doc,\n        resultType: \"all\",\n      });\n\n      if (results.length > 0) {\n        // Path exists, merge the update\n        let count = 0;\n        for (const result of results) {\n          const { parent, parentProperty } = result;\n          if (parent && parentProperty !== undefined) {\n            parent[parentProperty] = deepMerge(\n              parent[parentProperty],\n              action.update\n            );\n            count++;\n          }\n        }\n        return { applied: true, count };\n      }\n\n      // Path doesn't exist, create it manually\n      setValueAtPath(doc, action.target, action.update);\n      return { applied: true, count: 1 };\n    } catch (error) {\n      throw new Error(`Failed to apply update: ${(error as Error).message}`);\n    }\n  } else if (action.remove) {\n    try {\n      const results = JSONPath({\n        path: action.target,\n        json: doc,\n        resultType: \"all\",\n      });\n\n      if (results.length === 0) {\n        return { applied: false, count: 0 };\n      }\n\n      let count = 0;\n      // Process in reverse to avoid index issues when removing\n      for (let i = results.length - 1; i >= 0; i--) {\n        const result = results[i];\n        const { parent, parentProperty, value } = result;\n\n        // Check condition if specified\n        const shouldRemove =\n          typeof action.remove === \"object\"\n            ? checkCondition(value, action.remove)\n            : true;\n\n        if (shouldRemove && parent && parentProperty !== undefined) {\n          if (Array.isArray(parent)) {\n            parent.splice(parentProperty as number, 1);\n          } else {\n            delete parent[parentProperty];\n          }\n          count++;\n        }\n      }\n\n      return { applied: true, count };\n    } catch (error) {\n      throw new Error(`Failed to remove: ${(error as Error).message}`);\n    }\n  }\n\n  return { applied: false, count: 0 };\n}\n\n/**\n * Extract path order from overlay actions\n * Returns array of paths in the order they appear in overlay\n */\nexport function extractPathOrder(overlay: OverlayDocument): string[] {\n  const pathOrder: string[] = [];\n  const seenPaths = new Set<string>();\n\n  for (const action of overlay.actions) {\n    // Match patterns like $.paths['/route'].method\n    const match = action.target.match(/^\\$\\.paths\\['([^']+)'\\]/);\n    if (match) {\n      const targetPath = match[1];\n      if (!seenPaths.has(targetPath)) {\n        pathOrder.push(targetPath);\n        seenPaths.add(targetPath);\n      }\n    }\n  }\n\n  return pathOrder;\n}\n\n/**\n * Reorder operation properties so summary, description, operationId come first\n */\nexport function reorderOperationProperties(operation: any): any {\n  const priorityKeys = [\"summary\", \"description\", \"operationId\"];\n  const reordered: any = {};\n\n  // Add priority keys first (in order)\n  for (const key of priorityKeys) {\n    if (key in operation) {\n      reordered[key] = operation[key];\n    }\n  }\n\n  // Add remaining keys\n  for (const [key, value] of Object.entries(operation)) {\n    if (!priorityKeys.includes(key)) {\n      reordered[key] = value;\n    }\n  }\n\n  return reordered;\n}\n\n/**\n * Reorder paths object to match the order from overlay\n */\nexport function reorderPaths(doc: any, pathOrder: string[]): any {\n  if (!doc.paths || pathOrder.length === 0) {\n    return doc;\n  }\n\n  const originalPaths = doc.paths;\n  const reorderedPaths: any = {};\n\n  // First, add paths in the order specified by overlay\n  for (const targetPath of pathOrder) {\n    if (targetPath in originalPaths) {\n      reorderedPaths[targetPath] = originalPaths[targetPath];\n    }\n  }\n\n  // Then add any remaining paths that weren't in the overlay\n  for (const [targetPath, value] of Object.entries(originalPaths)) {\n    if (!(targetPath in reorderedPaths)) {\n      reorderedPaths[targetPath] = value;\n    }\n  }\n\n  // Reorder operation properties within each path\n  for (const pathItem of Object.values(reorderedPaths)) {\n    const httpMethods = [\n      \"get\",\n      \"post\",\n      \"put\",\n      \"patch\",\n      \"delete\",\n      \"options\",\n      \"head\",\n      \"trace\",\n    ];\n\n    for (const method of httpMethods) {\n      if (\n        (pathItem as any)[method] &&\n        typeof (pathItem as any)[method] === \"object\"\n      ) {\n        (pathItem as any)[method] = reorderOperationProperties(\n          (pathItem as any)[method]\n        );\n      }\n    }\n  }\n\n  doc.paths = reorderedPaths;\n  return doc;\n}\n\n/**\n * Reorder top-level document properties to ensure proper ordering\n * OpenAPI spec should have: openapi, info, tags, servers, paths, components, etc.\n */\nexport function reorderDocumentProperties(doc: any): any {\n  const priorityKeys = [\"openapi\", \"info\", \"tags\"];\n  const reordered: any = {};\n\n  // Add priority keys first\n  for (const key of priorityKeys) {\n    if (key in doc) {\n      reordered[key] = doc[key];\n    }\n  }\n\n  // Add remaining keys\n  for (const [key, value] of Object.entries(doc)) {\n    if (!priorityKeys.includes(key)) {\n      reordered[key] = value;\n    }\n  }\n\n  return reordered;\n}\n\n/**\n * Apply overlay to OpenAPI document\n * @param openapi The OpenAPI document to modify\n * @param overlay The overlay document to apply\n * @returns The modified OpenAPI document and statistics\n */\nexport function applyOverlay(\n  openapi: any,\n  overlay: OverlayDocument\n): { result: any; stats: OverlayStats } {\n  // Validate overlay format\n  if (!overlay.overlay || !overlay.actions) {\n    throw new Error(\n      \"Invalid overlay format. Must include 'overlay' version and 'actions' array.\"\n    );\n  }\n\n  const result = deepClone(openapi);\n  const stats: OverlayStats = { applied: 0, skipped: 0, totalNodes: 0 };\n\n  for (const action of overlay.actions) {\n    const { applied, count } = applyAction(result, action);\n\n    if (applied) {\n      stats.applied++;\n      stats.totalNodes += count;\n    } else {\n      stats.skipped++;\n    }\n  }\n\n  // Reorder paths to match overlay order\n  const pathOrder = extractPathOrder(overlay);\n  reorderPaths(result, pathOrder);\n\n  // Reorder top-level document properties\n  const reordered = reorderDocumentProperties(result);\n\n  return { result: reordered, stats };\n}\n"]}
+{"version":3,"file":"overlay-engine.js","sourceRoot":"","sources":["../../../src/open-api/overlay/overlay-engine.ts"],"names":[],"mappings":"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","sourcesContent":["import { JSONPath } from \"jsonpath-plus\";\nimport {\n  HTTP_METHODS,\n  validateOpenApiDocument,\n  validateOverlayDocument,\n  type OverlayAction,\n  type OverlayDocument,\n  type RemoveCondition,\n} from \"../../common/open-api/index.js\";\n\nexport interface ApplyResult {\n  applied: boolean;\n  count: number;\n}\n\nexport interface OverlayStats {\n  applied: number;\n  skipped: number;\n  totalNodes: number;\n}\n\n/**\n * Safely validate and return a generic object\n * Used internally for dynamic JSON manipulation\n */\nfunction toRecord(value: unknown, context: string): Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new Error(\n      `Expected object at ${context}, but got ${Array.isArray(value) ? \"array\" : typeof value}`\n    );\n  }\n  return value as Record<string, unknown>;\n}\n\n/**\n * Deep clone an object using structuredClone for better performance and correctness\n * Falls back to JSON parse/stringify for environments without structuredClone\n */\nexport function deepClone<T>(obj: T): T {\n  if (typeof structuredClone === \"function\") {\n    return structuredClone(obj);\n  }\n  return JSON.parse(JSON.stringify(obj));\n}\n\n/**\n * Deep merge two objects\n * Special handling for OpenAPI parameters (merge by name+in)\n * Returns the merged result, which will have the shape of source if target is not an object,\n * or a merged object/array if both are objects/arrays\n */\nexport function deepMerge(target: unknown, source: unknown): unknown {\n  if (!source || typeof source !== \"object\") {\n    return source;\n  }\n\n  if (!target || typeof target !== \"object\") {\n    return deepClone(source);\n  }\n\n  if (Array.isArray(source)) {\n    if (!Array.isArray(target)) {\n      return deepClone(source);\n    }\n\n    // Special case for OpenAPI parameters - merge by name+in\n    if (\n      source.length > 0 &&\n      typeof source[0] === \"object\" &&\n      source[0] !== null &&\n      \"name\" in source[0] &&\n      \"in\" in source[0]\n    ) {\n      const merged = [...target];\n      for (const sourceParam of source) {\n        if (typeof sourceParam !== \"object\" || sourceParam === null) continue;\n        const existingIndex = merged.findIndex(\n          (p) =>\n            typeof p === \"object\" &&\n            p !== null &&\n            \"name\" in p &&\n            \"in\" in p &&\n            \"name\" in sourceParam &&\n            \"in\" in sourceParam &&\n            p.name === sourceParam.name &&\n            p.in === sourceParam.in\n        );\n        if (existingIndex >= 0) {\n          merged[existingIndex] = deepMerge(merged[existingIndex], sourceParam);\n        } else {\n          merged.push(deepClone(sourceParam));\n        }\n      }\n      return merged;\n    }\n\n    // For other arrays, concatenate\n    return [...target, ...deepClone(source)];\n  }\n\n  // Both are objects at this point (checked above)\n  const targetObj = target as Record<string, unknown>;\n  const sourceObj = source as Record<string, unknown>;\n  const result = { ...targetObj };\n\n  for (const [key, value] of Object.entries(sourceObj)) {\n    if (key in result) {\n      result[key] = deepMerge(result[key], value);\n    } else {\n      result[key] = deepClone(value);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Check if a condition is met for conditional removal\n */\nexport function checkCondition(\n  value: unknown,\n  condition: RemoveCondition\n): boolean {\n  // Support \"empty\" condition to check if object has no keys\n  if (condition.empty) {\n    if (typeof value === \"object\" && value !== null && !Array.isArray(value)) {\n      return Object.keys(value).length === 0;\n    }\n    if (Array.isArray(value)) {\n      return value.length === 0;\n    }\n    return false;\n  }\n\n  // Support \"missing\" condition to check if a property doesn't exist\n  if (condition.missing) {\n    const parts = condition.missing.split(\".\");\n    let current: unknown = value;\n    for (const part of parts) {\n      if (\n        current &&\n        typeof current === \"object\" &&\n        !Array.isArray(current) &&\n        part in current\n      ) {\n        current = (current as Record<string, unknown>)[part];\n      } else {\n        return true; // Property is missing\n      }\n    }\n    return false; // Property exists\n  }\n\n  return false;\n}\n\n/**\n * Regular expression for parsing JSONPath segments\n * Matches: word, or [quoted], or ['quoted'], or [\"quoted\"], or numeric indices [0]\n */\nconst JSONPATH_SEGMENT_PATTERN = /[^.[]+|\\[[^\\]]+\\]/g;\n\n/**\n * Extract key from bracket notation, handling various formats:\n * - ['key'] -> key\n * - [\"key\"] -> key\n * - [key] -> key\n * - [0] -> 0 (as string for consistency)\n */\nfunction extractBracketKey(bracketNotation: string): string {\n  const inner = bracketNotation.slice(1, -1); // Remove [ and ]\n\n  // Handle single-quoted: ['key'] -> key\n  if (inner.startsWith(\"'\") && inner.endsWith(\"'\")) {\n    return inner.slice(1, -1);\n  }\n\n  // Handle double-quoted: [\"key\"] -> key\n  if (inner.startsWith('\"') && inner.endsWith('\"')) {\n    return inner.slice(1, -1);\n  }\n\n  // Handle unquoted: [key] or [0] -> key or 0\n  return inner;\n}\n\n/**\n * Set a value at a JSONPath, creating parent paths as needed\n * Handles patterns like:\n *   $.paths['/route'].method\n *   $.components.parameters['name']\n *   $.paths[\"/users\"].get\n *   $.paths[users].get\n *   $.items[0].value\n */\nexport function setValueAtPath(\n  doc: unknown,\n  target: string,\n  value: unknown\n): void {\n  // Parse the path manually to handle both bracket and dot notation\n  // Example: $.paths['/route'].post -> [\"paths\", \"['/route']\", \"post\"]\n\n  // Remove leading $.\n  const targetPath = target.replace(/^\\$\\./, \"\");\n\n  // Split by dots, but keep bracket notation together\n  const parts = targetPath.match(JSONPATH_SEGMENT_PATTERN) || [];\n\n  let current = toRecord(doc, \"setValueAtPath document\");\n\n  for (let i = 0; i < parts.length - 1; i++) {\n    const part = parts[i];\n\n    // Handle bracket notation\n    if (part.startsWith(\"[\")) {\n      const key = extractBracketKey(part);\n      if (!(key in current)) {\n        current[key] = {};\n      }\n      const next = current[key];\n      current = toRecord(next, `setValueAtPath at ${target}[${i}]`);\n    } else {\n      // Handle regular property\n      if (!(part in current)) {\n        current[part] = {};\n      }\n      const next = current[part];\n      current = toRecord(next, `setValueAtPath at ${target}.${part}`);\n    }\n  }\n\n  // Set the final value\n  const lastPart = parts[parts.length - 1];\n  if (lastPart.startsWith(\"[\")) {\n    const key = extractBracketKey(lastPart);\n    current[key] = value;\n  } else {\n    current[lastPart] = value;\n  }\n}\n\n/**\n * Apply a single overlay action to the document\n */\nexport function applyAction(doc: unknown, action: OverlayAction): ApplyResult {\n  const docRecord = toRecord(doc, \"applyAction document\");\n\n  if (action.update) {\n    // Handle root level updates specially\n    if (action.target === \"$\") {\n      Object.assign(docRecord, deepMerge(doc, action.update));\n      return { applied: true, count: 1 };\n    }\n\n    try {\n      // Try to find existing nodes\n      const results = JSONPath({\n        path: action.target,\n        // biome-ignore lint/suspicious/noExplicitAny: JSONPath library requires loose typing\n        json: doc as any,\n        resultType: \"all\",\n      }) as Array<{ parent: unknown; parentProperty: unknown; value: unknown }>;\n\n      if (results.length > 0) {\n        // Path exists, merge the update\n        let count = 0;\n        for (const result of results) {\n          const { parent, parentProperty } = result;\n          if (\n            parent &&\n            typeof parent === \"object\" &&\n            !Array.isArray(parent) &&\n            parentProperty !== undefined\n          ) {\n            const parentRecord = parent as Record<string, unknown>;\n            parentRecord[parentProperty as string] = deepMerge(\n              parentRecord[parentProperty as string],\n              action.update\n            );\n            count++;\n          }\n        }\n        return { applied: true, count };\n      }\n\n      // Path doesn't exist, create it manually\n      setValueAtPath(doc, action.target, action.update);\n      return { applied: true, count: 1 };\n    } catch (cause) {\n      throw new Error(\"Failed to apply update\", { cause });\n    }\n  } else if (action.remove) {\n    try {\n      const results = JSONPath({\n        path: action.target,\n        // biome-ignore lint/suspicious/noExplicitAny: JSONPath library requires loose typing\n        json: doc as any,\n        resultType: \"all\",\n      }) as Array<{ parent: unknown; parentProperty: unknown; value: unknown }>;\n\n      if (results.length === 0) {\n        return { applied: false, count: 0 };\n      }\n\n      let count = 0;\n      // Process in reverse to avoid index issues when removing\n      for (let i = results.length - 1; i >= 0; i--) {\n        const result = results[i];\n        const { parent, parentProperty, value } = result;\n\n        // Check condition if specified\n        const shouldRemove =\n          typeof action.remove === \"object\"\n            ? checkCondition(value, action.remove)\n            : true;\n\n        if (shouldRemove && parent && parentProperty !== undefined) {\n          if (Array.isArray(parent)) {\n            parent.splice(parentProperty as number, 1);\n          } else if (typeof parent === \"object\" && parent !== null) {\n            delete (parent as Record<string, unknown>)[\n              parentProperty as string\n            ];\n          }\n          count++;\n        }\n      }\n\n      return { applied: true, count };\n    } catch (cause) {\n      throw new Error(\"Failed to remove\", { cause });\n    }\n  }\n\n  return { applied: false, count: 0 };\n}\n\n/**\n * Extract path order from overlay actions\n * Returns array of paths in the order they appear in overlay\n */\nexport function extractPathOrder(overlay: OverlayDocument): string[] {\n  const pathOrder: string[] = [];\n  const seenPaths = new Set<string>();\n\n  for (const action of overlay.actions) {\n    // Match patterns like $.paths['/route'].method\n    const match = action.target.match(/^\\$\\.paths\\['([^']+)'\\]/);\n    if (match) {\n      const targetPath = match[1];\n      if (!seenPaths.has(targetPath)) {\n        pathOrder.push(targetPath);\n        seenPaths.add(targetPath);\n      }\n    }\n  }\n\n  return pathOrder;\n}\n\n/**\n * Reorder operation properties so summary, description, operationId come first\n * Returns a new object with reordered keys\n */\nexport function reorderOperationProperties(\n  operation: unknown\n): Record<string, unknown> {\n  const operationObj = toRecord(operation, \"reorderOperationProperties\");\n  const priorityKeys = [\"summary\", \"description\", \"operationId\"];\n  const reordered: Record<string, unknown> = {};\n\n  // Add priority keys first (in order)\n  for (const key of priorityKeys) {\n    if (key in operationObj) {\n      reordered[key] = operationObj[key];\n    }\n  }\n\n  // Add remaining keys\n  for (const [key, value] of Object.entries(operationObj)) {\n    if (!priorityKeys.includes(key)) {\n      reordered[key] = value;\n    }\n  }\n\n  return reordered;\n}\n\n/**\n * Reorder paths object to match the order from overlay\n * Modifies the document in place and returns it\n */\nexport function reorderPaths<T>(doc: T, pathOrder: string[]): T {\n  // Early return if no paths to reorder\n  if (\n    typeof doc !== \"object\" ||\n    doc === null ||\n    !(\"paths\" in doc) ||\n    pathOrder.length === 0\n  ) {\n    return doc;\n  }\n\n  const docRecord = doc as Record<string, unknown>;\n  const originalPaths = toRecord(docRecord.paths, \"paths\");\n  const reorderedPaths: Record<string, unknown> = {};\n\n  // First, add paths in the order specified by overlay\n  for (const targetPath of pathOrder) {\n    if (targetPath in originalPaths) {\n      reorderedPaths[targetPath] = originalPaths[targetPath];\n    }\n  }\n\n  // Then add any remaining paths that weren't in the overlay\n  for (const [targetPath, value] of Object.entries(originalPaths)) {\n    if (!(targetPath in reorderedPaths)) {\n      reorderedPaths[targetPath] = value;\n    }\n  }\n\n  // Reorder operation properties within each path\n  for (const pathItem of Object.values(reorderedPaths)) {\n    if (typeof pathItem !== \"object\" || pathItem === null) continue;\n\n    const pathItemRecord = pathItem as Record<string, unknown>;\n\n    for (const method of HTTP_METHODS) {\n      if (\n        method in pathItemRecord &&\n        typeof pathItemRecord[method] === \"object\" &&\n        pathItemRecord[method] !== null\n      ) {\n        pathItemRecord[method] = reorderOperationProperties(\n          pathItemRecord[method]\n        );\n      }\n    }\n  }\n\n  docRecord.paths = reorderedPaths;\n  return doc;\n}\n\n/**\n * Reorder top-level document properties to ensure proper ordering\n * OpenAPI spec should have: openapi, info, tags, servers, paths, components, etc.\n * Returns a new object with reordered keys\n */\nexport function reorderDocumentProperties(\n  doc: unknown\n): Record<string, unknown> {\n  const docObj = toRecord(doc, \"reorderDocumentProperties\");\n  const priorityKeys = [\"openapi\", \"info\", \"tags\"];\n  const reordered: Record<string, unknown> = {};\n\n  // Add priority keys first\n  for (const key of priorityKeys) {\n    if (key in docObj) {\n      reordered[key] = docObj[key];\n    }\n  }\n\n  // Add remaining keys\n  for (const [key, value] of Object.entries(docObj)) {\n    if (!priorityKeys.includes(key)) {\n      reordered[key] = value;\n    }\n  }\n\n  return reordered;\n}\n\n/**\n * Apply overlay to OpenAPI document\n *\n * Validates both the OpenAPI document and overlay upfront, then applies\n * all actions defined in the overlay to produce a modified OpenAPI document.\n *\n * @param openapi The OpenAPI document to modify (will be validated)\n * @param overlay The overlay document to apply (will be validated)\n * @returns The modified OpenAPI document and statistics about what was applied\n * @throws {Error} if either document is invalid, with actionable error messages\n *\n * @example\n * ```typescript\n * const result = applyOverlay(openapiDoc, overlayDoc);\n * console.log(`Applied ${result.stats.applied} actions`);\n * ```\n */\nexport function applyOverlay(\n  openapi: unknown,\n  overlay: unknown\n): { result: Record<string, unknown>; stats: OverlayStats } {\n  // Validate inputs upfront with actionable error messages\n  const validatedOverlay = validateOverlayDocument(overlay);\n  const validatedOpenApi = validateOpenApiDocument(openapi);\n\n  // Clone the document for modification\n  const result = deepClone(validatedOpenApi);\n  const stats: OverlayStats = { applied: 0, skipped: 0, totalNodes: 0 };\n\n  // Apply each action\n  for (const action of validatedOverlay.actions) {\n    const { applied, count } = applyAction(result, action);\n\n    if (applied) {\n      stats.applied++;\n      stats.totalNodes += count;\n    } else {\n      stats.skipped++;\n    }\n  }\n\n  // Reorder paths to match overlay order\n  const pathOrder = extractPathOrder(validatedOverlay);\n  reorderPaths(result, pathOrder);\n\n  // Reorder top-level document properties\n  const reordered = reorderDocumentProperties(result);\n\n  return { result: reordered, stats };\n}\n"]}