overlay: replace jsonpath by the more recent (and typed) jsonpathly

The currently used `jsonpath` lib is pretty old and unmaintained (last
commits 4 years ago), and even more problematic it causes issues to
[upgrade our github action](bump-sh/github-action#508) as that lib has an inconsistant use of
'require' and doesn't seem to work well with the packaging
step (rollup) of the github action.

Hopefully this upgrade (and change of lib) should let us a clean
upgrade of the GH action to an ESM version 🤞

Author: paulRbr

package-lock.json

@@ -101,7 +101,7 @@
     "axios": "^1.7.7",
     "chalk": "^5.3.0",
     "debug": "^4.3.7",
-    "jsonpath": "^1.1.1",
+    "jsonpathly": "^2.0.2",
     "mergician": "^2.0.2",
     "oas-schemas": "git+https://git@github.com/OAI/OpenAPI-Specification.git#882d1caedb0bff825a1fd10728e7e3dc43912d37",
     "open": "^10.1.0"

package.json

@@ -1,7 +1,6 @@
 import debug from 'debug'
-import {JSONSchema4Object} from 'json-schema'
-/* eslint-disable-next-line import/default */
-import jsonpath from 'jsonpath'
+import {JSONSchema4Object, JSONSchema4Type} from 'json-schema'
+import * as jsonpath from 'jsonpathly'
 import {mergician} from 'mergician'
 
 import {APIDefinition, OpenAPIOverlay} from '../definition.js'
@@ -24,64 +23,107 @@ export class Overlay {
   // If you make any changes here, PLEASE ALSO MAKE THEM UPSTREAM.
   public run(spec: APIDefinition, overlay: OpenAPIOverlay): APIDefinition {
     // Use jsonpath.apply to do the changes
-    if (overlay.actions && overlay.actions.length > 0)
+    if (overlay.actions && overlay.actions.length > 0) {
       for (const a of overlay.actions) {
         const action = a as JSONSchema4Object
         if (!action.target) {
-          process.stderr.write('Action with a missing target\n')
+          process.stderr.write(`WARNING: ${this.humanName(action)} has an empty target\n`)
           continue
         }
 
         const target = action.target as string
-        // Is it a remove?
-        if (Object.hasOwn(action, 'remove')) {
-          /* eslint-disable-next-line no-constant-condition */
-          while (true) {
-            const path = jsonpath.paths(spec, target)
-            if (path.length === 0) {
-              break
-            }
-
-            const parent = jsonpath.parent(spec, target)
-            const thingToRemove = path[0].at(-1)
-            if (thingToRemove !== undefined) {
-              if (Array.isArray(parent)) {
-                parent.splice(thingToRemove as number, 1)
-              } else {
-                delete parent[thingToRemove]
-              }
-            }
-          }
-        } else {
-          try {
-            // It must be an update
-            // Deep merge objects using a module (built-in spread operator is only shallow)
-            const merger = mergician({appendArrays: true})
-            if (target === '$') {
-              // You can't actually merge an update on a root object
-              // target with the jsonpath lib, this is just us merging
-              // the given update with the whole spec.
-              spec = merger(spec, action.update)
-            } else {
-              jsonpath.apply(spec, target, (chunk) => {
-                if (typeof chunk === 'object' && typeof action.update === 'object') {
-                  if (Array.isArray(chunk) && Array.isArray(action.update)) {
-                    return [...chunk, ...action.update]
-                  }
-
-                  return merger(chunk, action.update)
-                }
+        // jsonpathly's paths are strings. They represent a “Path
+        // expression” which represents the absolute path in the objet
+        // tree reached by our `target`.
+        //
+        // E.g. '$["store"]["book"][0]["price"]'
+        const paths = jsonpath.paths(spec, target)
+        if (paths.length === 0) {
+          process.stderr.write(`WARNING: Action target '${target}' has no matching elements\n`)
+          continue
+        }
 
-                return action.update
-              })
-            }
-          } catch (error) {
-            process.stderr.write(`Error applying overlay: ${(error as Error).message}\n`)
-            // return chunk
-          }
+        for (const path of paths) {
+          this.executeAction(spec, action, path)
         }
       }
+    } else {
+      process.stderr.write('WARNING: No actions found in your overlay\n')
+    }
 
     return spec
   }
+
+  private executeAction(spec: APIDefinition, action: JSONSchema4Object, path: string): void {
+    const explodedPath: string[] = path.split(/(?:]\[|\$\[)+/)
+    // Remove root
+    explodedPath.shift()
+
+    // Take last element from path (which is the thing to act
+    // upon)
+    let thingToActUpon: number | string | undefined = explodedPath.pop()
+    // The last element (e.g. '"price"]' or '0]') contains a final ']'
+    // so we need to remove it AND we need to parse the element to
+    // transform the string in either a string or a number
+    thingToActUpon =
+      thingToActUpon === undefined ? '$' : (thingToActUpon = JSON.parse(thingToActUpon.slice(0, -1)) as number | string)
+
+    // Reconstruct the stringified path expression targeting the parent
+    const parentPath: string = explodedPath.join('][')
+    const parent: JSONSchema4Object =
+      parentPath.length > 0 ? (jsonpath.query(spec, `$[${parentPath}]`) as JSONSchema4Object) : spec
+
+    // Do the overlay action
+    // Is it a remove?
+    if (Object.hasOwn(action, 'remove')) {
+      this.remove(parent, thingToActUpon)
+    } else if (Object.hasOwn(action, 'update')) {
+      this.update(spec, parent, action.update, thingToActUpon)
+    } else {
+      process.stderr.write(`WARNING: ${this.humanName(action)} needs either a 'remove' or an 'update' property\n`)
+    }
+  }
+
+  private humanName(action: JSONSchema4Object): string {
+    return action.description ? `Action '${action.description}'` : 'Action'
+  }
+
+  private remove(parent: JSONSchema4Object, property_or_index: number | string): void {
+    if (Array.isArray(parent)) {
+      parent.splice(property_or_index as number, 1)
+    } else {
+      delete parent[property_or_index]
+    }
+  }
+
+  private update(
+    spec: APIDefinition,
+    parent: JSONSchema4Object,
+    update: JSONSchema4Type,
+    property_or_index: number | string,
+  ): void {
+    try {
+      // Deep merge objects using a module (built-in spread operator is only shallow)
+      const merger = mergician({appendArrays: true})
+      if (property_or_index === '$') {
+        // You can't actually merge an update on a root object
+        // target with the jsonpath lib, this is just us merging
+        // the given update with the whole spec.
+        spec = merger(spec, update)
+      } else if (property_or_index) {
+        const targetObject = parent[property_or_index]
+
+        if (typeof targetObject === 'object' && typeof update === 'object') {
+          parent[property_or_index] =
+            Array.isArray(targetObject) && Array.isArray(update)
+              ? [...targetObject, ...update]
+              : merger(targetObject, update)
+        } else {
+          parent[property_or_index] = update
+        }
+      }
+    } catch (error) {
+      process.stderr.write(`Error applying overlay: ${(error as Error).message}\n`)
+    }
+  }
 }