bump-cli 2.9.2 → 2.9.3

package/README.md

@@ -5,16 +5,17 @@
 </p>
 
 <p align="center">
-  <a href="https://help.bump.sh/">Help</a> |
+  <a href="https://docs.bump.sh/help">Help</a> |
   <a href="https://bump.sh/users/sign_up">Sign up</a>
 </p>
 
-The Bump.sh CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API definition of your choice (from Swagger, OpenAPI or AsyncAPI), it can help you to:
+The Bump.sh CLI is used to interact with API documentation and hubs hosted on Bump.sh from your choice of popular API description formats: OpenAPI, Swagger, or AsyncAPI.
 
-- Validate an API document before publishing it to your documentation
-- Publish an API document to your Bump.sh documentation or hubs
-- Compare two API documents to generate a human-readable diff from your API definitions
+Using [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (v3.x and v2.0) or [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) (2.x), you can do any of the following:
 
+- Validate an API document before publishing to your documentation.
+- Publish an API document to your Bump.sh documentation or hubs.
+- Compare two API documents to generate a human-readable diff from your API definition.
 Under the hood, it uses the API of [developers.bump.sh](https://developers.bump.sh). And is built with the [`oclif`](https://oclif.io) framework in Typescript.
 
 [![Version](https://img.shields.io/npm/v/bump-cli.svg)](https://npmjs.org/package/bump-cli)
@@ -34,43 +35,43 @@ Under the hood, it uses the API of [developers.bump.sh](https://developers.bump.
 
 The Bump.sh CLI is a node package currently distributed via NPM. This means you must have the Node v20+ interpreter installed on your computer or CI servers.
 
-_If you are looking to use Bump.sh in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/api-documentation-on-bump)._
+_If you are looking to use Bump.sh in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/bump-sh-api-documentation-changelog)._
 
 > You can download a standalone package directly from the latest
-> GitHub release assets if you don’t use Node.
+> Github release assets if you don’t use Node.
 {: .info}
 
 ### Global installation
 
-To install it globally, run the following command with NPM
+To install it globally, run the following command with NPM:
 
-```sh-session
+```shell
 npm install -g bump-cli
 ```
 
-Or, with Yarn via
+Or, with Yarn via:
 
-```sh-session
+```shell
 yarn global add bump-cli
 ```
 
 ### Add Bump.sh to your Node project
 
-As our CLI is a node package, you can easily embed it into your project by adding the package to your `package.json` file, either with NPM
+As our CLI is a node package, you can easily embed it to your project by adding the package to your `package.json` file, either with NPM:
 
-```sh-session
+```shell
 npm install --save-dev bump-cli
 ```
 
-Or with Yarn via
+Or with Yarn via:
 
-```sh-session
+```shell
 yarn add --dev bump-cli
 ```
 
-You can then use any Bump.sh commands with `npx` (same as `npm exec`)
+You can then use any Bump.sh commands with `npx` (same as `npm exec`):
 
-```sh-session
+```shell
 npx bump --help
 ```
 
@@ -82,12 +83,12 @@ Unfortunately, at the moment we only support the Node environment. However, you
 
 To list all the available commands, just type `bump` in your command line environment.
 
-```sh-session
+```shell
 $ bump --help
 The Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh
 
 VERSION
-  bump-cli/2.9.1 linux-x64 node-v20.18.1
+  bump-cli/2.9.2 linux-x64 node-v20.18.1
 
 USAGE
   $ bump [COMMAND]
@@ -110,16 +111,16 @@ Head over to your Documentation settings in the “CI deployment” section or y
 
 ## Commands
 
-* [`bump deploy [FILE]`](#bump-deploy-file)
-* [`bump diff [FILE]`](#bump-diff-file)
-* [`bump preview [FILE]`](#bump-preview-file)
-* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#bump-overlay-definition_file-overlay_file)
+* [`bump deploy [FILE]`](#the-deploy-command)
+* [`bump diff [FILE]`](#the-diff-command)
+* [`bump preview [FILE]`](#the-preview-command)
+* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#the-overlay-command)
 
-### `bump deploy [FILE]`
+### The `deploy` command
 
-When you update your API, you also want its documentation to be up to date for your API users. This is what the deploy command is for.
+When an API is updated, the documentation should be updated at the same time. This is what the deploy command is for.
 
-```sh-session
+```shell
 bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN
 ```
 
@@ -128,7 +129,7 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN
 
 You can also deploy a given API document to a different branch of your documentation with the `--branch <branch-name>` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature are available on [this dedicated help page](https://docs.bump.sh/help/branching). E.g. deploy the API document to the `staging` branch of the documentation:
 
-```sh-session
+```shell
 bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging
 ```
 
@@ -136,7 +137,7 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN -
 
 If you already have a hub in your [Bump.sh](https://bump.sh) account, you can automatically create documentation and deploy it into that hub by publishing a whole directory containing multiple API documents in a single command:
 
-```sh-session
+```shell
 bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN
 ```
 
@@ -168,69 +169,81 @@ bump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service'
 
 Simulate your API document's deployment to ensure it is valid by adding the `--dry-run` flag to the `deploy` command. It is handy in a Continuous Integration environment running a test deployment outside your main branch:
 
-```sh-session
+```shell
 bump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $DOC_TOKEN
 ```
 
 Please check `bump deploy --help` for more usage details.
 
-### `bump diff [FILE]`
-
-_If you want to receive automatic `bump diff` results on your Github Pull Requests you might be interested by [our Github Action](https://github.com/marketplace/actions/bump-sh-api-documentation-changelog) which also has a diff command._
+### The `diff` command
 
-Please note that by default the command will always exit with a
-successful return code. If you want to use this command in a CI
-environment and want the command to fail **in case of a breaking
-change**, you will need to add the `--fail-on-breaking` flag to your
-diff command. By default if the environment variable `CI=1` is present
-(in most continuous integration environment), the flag will be
-enabled. In that case you can disable the failures with
-`--no-fail-on-breaking` flag.
+Using the `diff` command can help to spot differences between the local API
+document and the latest deployed version. 
 
 #### Public API diffs
 
-From any two API documents or URLs, you can retrieve a comprehensive changelog of what has changed between them.
+From any two API documents or URLs, you can retrieve a comprehensive changelog
+of what has changed between them.
 
-```sh-session
+```shell
 $ bump diff path/to/your/file.yml path/to/your/second_file.yml
 * Comparing the two given definition files... done
 Modified: GET /consommations
   Response modified: 200
     [Breaking] Body attribute modified: energie
 ```
-> You can create as many diffs as you like without being authenticated. This is a **free and unlimited service** provided as long as you use the service fairly.
-{: .info}
 
-_**Note:** You can also test this feature in our dedicated web application at <https://api-diff.io/>._
+By default the command will always exit with a successful return code. If you
+want to use this command in a CI environment and want the command to fail **in
+case of a breaking change**, you will need to add the `--fail-on-breaking` flag
+to your diff command. 
+
+By default if the environment variable `CI=1` is present (in most continuous
+integration environment), the flag will be enabled. In that case you can disable
+the failures with `--no-fail-on-breaking` flag.
+
+You can also test this feature in our dedicated web application at
+<https://api-diff.io/>.
+
+#### GitHub Integration
+
+If you want to receive automatic `bump diff` results on Github Pull Requests you
+might be interested by [our Github
+Action](https://github.com/marketplace/actions/bump-sh-api-documentation-changelog#deploy-documentation--diff-on-pull-requests)
+which has support for the diff command.
 
 #### Authenticated diffs related to your Bump.sh documentation
 
-From an existing Bump.sh documentation, the `diff` command will retrieve a comparison changelog between your latest published documentation and the given file or URL:
+From an existing Bump.sh documentation, the `diff` command will retrieve a
+comparison changelog between your latest published documentation and the given
+file or URL:
 
-```sh-session
+```shell
 bump diff path/to/your/file.yml --doc my-documentation --token $DOC_TOKEN
 ```
 
 If you want to compare two unpublished versions of your API document, the `diff` command can retrieve a comparison changelog between two given file or URL, “as simple as `git diff`”:
 
-```sh-session
+```shell
 bump diff path/to/your/file.yml path/to/your/next-file.yml --doc my-documentation --token $DOC_TOKEN
 ```
 
 Please check `bump diff --help` for full usage details.
 
-### `bump preview [FILE]`
+### The `preview` command
 
+When writing documentation, you might want to preview how it renders on Bump.sh.
+This is precisely the goal of the `preview` command: it will create temporary
+documentation with a unique URL, which will be available for a short period (30
+minutes).
 
-When writing documentation, you might want to preview how it renders on Bump.sh. This is precisely the goal of the `preview` command: it will create temporary documentation with a unique URL, which will be available for a short period (30 minutes).
-
-Usage from a local OpenAPI or AsyncAPI file
+Usage from a local OpenAPI or AsyncAPI document:
 
 ```shell
 bump preview path/to/file.json
 ```
 
-You can also preview a file available from a URL
+You can also preview a document available via a URL:
 
 ```shell
 bump preview https://developers.bump.sh/source.yaml
@@ -243,37 +256,48 @@ By using the `--live` flag you can stay focused on API design (OpenAPI or AsyncA
 - Launch the live preview command in your terminal
 
 ```shell
-bump preview --live --open openapi-definition.json
+bump preview --live --open api-document.yaml
 ```
 
-- Edit your `openapi-definition.json` file in your favorite text editor
+- Edit your `api-document.yaml` file in your favorite text editor.
 - Watch the live preview being updated each time you save your file.
+- The additional `--open` flag helps to automatically open the preview URL in your browser.
 
 > You can create as many previews as you like without being authenticated. This is a **free and unlimited service**.
 {: .info}
 
-_**Note:** the additional `--open` flag helps to automatically open the preview URL in your browser._
-
 Please check `bump preview --help` for more usage details
 
-### `bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`
+### The `overlay` command
 
-> This feature implements the [OpenAPI Overlay specification](https://github.com/OAI/Overlay-Specification). It is possible to apply an Overlay to any kind of document, be it an OpenAPI or AsyncAPI definition file.
+The [Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) from the OpenAPI Initiative makes it possible to modify the content of an API definition by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original definition. 
 
-The Overlay specification of OpenAPI makes it possible to modify the content of an API definition file by adding a layer on top of it. That layer helps add, remove, or change some or all of the content of the original definition.
+The `bump overlay` command takes an original API document, applies the changes from the overlay document, and outputs a modified version. No changes are made directly to the original document.
 
-Technically, the `bump overlay` command will output a modified version of the `[DEFINITION_FILE]` (an OpenAPI or AsyncAPI document) by applying the operations described in the `[OVERLAY_FILE]` Overlay file to the original API document.
+```shell
+bump overlay api-document.yaml overlay.yaml
+```
+
+To redirect the output of the command to a new file you can run:
+
+```shell
+bump overlay api-document.yaml overlay.yaml > modified-api-document.yaml
+```
 
-To redirect the output of the command to a new file you can run the following:
+You can also apply the overlay using the [`deploy` command](#the-deploy-command) with the `--overlay` flag:
 
 ```shell
-bump overlay api-document.yaml overlay-file.yaml > api-overlayed-document.yaml
+bump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay.yaml
 ```
 
-_Note: you can also apply overlays during the [`bump deploy` command]((#bump-deploy-file)) with the `--overlay` flag (which can be used multiples times):_
+If there are multiple overlays which need to be applied, the `--overlay` can be passed multiple times.
 
 ```shell
-bump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay-file.yaml
+bump deploy api-document.yaml \
+  --doc my-doc \
+  --token my-token \
+  --overlay overlay1.yaml \
+  --overlay overlay2.yaml
 ```
 
 ## Development
@@ -282,55 +306,44 @@ Make sure to have Node.js (At least v20) installed on your machine.
 
 - Install node dependencies with
 
-  ```sh-session
+  ```shell
   npm install
   ```
 
 - Compile the Typescript code
 
-  ```sh-session
+
+  ```shell
   npm run build
-  npm run clean # to remove build artifacts
+  npm run clean # Remove build artifacts
   ```
 
 - Format the codebase to comply with the linter rules
 
-  ```sh-session
+  ```shell
   npm run fmt
   ```
 
 - Run the test suites
-
-  ```sh-session
+  
+  ```shell
   npm run test
   npm run test-coverage # Run tests with coverage
   ```
 
-## Compatible specification types
+## License
 
-We currently support [OpenAPI](https://github.com/OAI/OpenAPI-Specification) from 2.0 (called Swagger) to 3.1 and [AsyncAPI 2.x](https://www.asyncapi.com/docs/reference/specification/latest) specification file types. Both YAML and JSON file formats are accepted file inputs to the CLI.
+The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/bump-sh/cli>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-## Thanks
-
-- [Lorna Mitchel](https://github.com/lornajane/) for [openapi-overlay-js](https://github.com/lornajane/openapi-overlays-js)
-
-## License
-
-The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).
-
 ## Code of Conduct
 
 Everyone interacting in the Bump-CLI project codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/bump-sh/.github/blob/main/CODE_OF_CONDUCT.md).
 
-## Versioning
-
-This npm package starts at v2.0.0 for two main reasons:
-
-- Our [first version](https://github.com/bump-sh/bump-cli) of the Bump CLI was written in Ruby, starting at v2.0.0, which makes it clear we are working on our second version of the Bump CLI
+## Thanks
 
-- The `bump-cli` package used to be [owned by Rico](https://github.com/rstacruz) which already published v1.x packages. If you are looking for the old npm package please head to [`@rstacruz/bump-cli` package](https://www.npmjs.com/package/@rstacruz/bump-cli). _A big thanks to Rico for transferring the ownership of the `bump-cli` package name!_
-w
+- [Lorna Mitchel](https://github.com/lornajane/) for [openapi-overlay-js](https://github.com/lornajane/openapi-overlays-js).
+- [Rico](https://github.com/rstacruz) for transferring the ownership of the `bump-cli` package name.

package/dist/core/overlay.d.ts

@@ -2,4 +2,8 @@ import { APIDefinition, OpenAPIOverlay } from '../definition.js';
 export declare class Overlay {
     d(formatter: any, ...args: any[]): void;
     run(spec: APIDefinition, overlay: OpenAPIOverlay): APIDefinition;
+    private executeAction;
+    private humanName;
+    private remove;
+    private update;
 }

package/dist/core/overlay.js

@@ -1,6 +1,5 @@
 import debug from 'debug';
-/* eslint-disable-next-line import/default */
-import jsonpath from 'jsonpath';
+import * as jsonpath from 'jsonpathly';
 import { mergician } from 'mergician';
 export class Overlay {
     // WIP @github.com/lornajane/openapi-overlays-js
@@ -19,63 +18,104 @@ export class Overlay {
     // If you make any changes here, PLEASE ALSO MAKE THEM UPSTREAM.
     run(spec, overlay) {
         // 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;
                 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;
-                // 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, 1);
-                            }
-                            else {
-                                delete parent[thingToRemove];
-                            }
-                        }
-                    }
+                // 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;
                 }
-                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);
-                                }
-                                return action.update;
-                            });
-                        }
-                    }
-                    catch (error) {
-                        process.stderr.write(`Error applying overlay: ${error.message}\n`);
-                        // return chunk
-                    }
+                for (const path of paths) {
+                    // The 'executeAction' will mutate the passed spec object in
+                    // place.
+                    this.executeAction(spec, action, path);
                 }
             }
+        }
+        else {
+            process.stderr.write('WARNING: No actions found in your overlay\n');
+        }
         return spec;
     }
+    /* Mutates the given 'spec' object with the 'action' given and
+     * targeting a unique 'pat ' within the spec object. We don't check
+     * if the path is valid in the object as this is the role of the
+     * jsonpathly lib which we used previously to extract the target
+     * paths. */
+    executeAction(spec, action, path) {
+        const explodedPath = path.split(/(?:]\[|\$\[)+/);
+        // Remove root
+        explodedPath.shift();
+        // Take last element from path (which is the thing to act
+        // upon)
+        let thingToActUpon = 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)));
+        // Reconstruct the stringified path expression targeting the parent
+        const parentPath = explodedPath.join('][');
+        const parent = parentPath.length > 0 ? jsonpath.query(spec, `$[${parentPath}]`) : 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`);
+        }
+    }
+    humanName(action) {
+        return action.description ? `Action '${action.description}'` : 'Action';
+    }
+    remove(parent, property_or_index) {
+        if (Array.isArray(parent)) {
+            parent.splice(property_or_index, 1);
+        }
+        else {
+            delete parent[property_or_index];
+        }
+    }
+    update(spec, parent, update, property_or_index) {
+        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 jsonpathly 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.message}\n`);
+        }
+    }
 }

package/oclif.manifest.json

@@ -277,5 +277,5 @@
       "strict": true
     }
   },
-  "version": "2.9.2"
+  "version": "2.9.3"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bump-cli",
   "description": "The Bump CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh",
-  "version": "2.9.2",
+  "version": "2.9.3",
   "author": "Paul Bonaud <paulr@bump.sh>",
   "bin": {
     "bump": "./bin/run.js"
@@ -73,7 +73,6 @@
   },
   "repository": "bump-sh/cli",
   "scripts": {
-    "prepare": "npm run build",
     "build": "shx rm -rf dist && tsc -b",
     "clean": "rm -rf dist/ oclif.manifest.json",
     "lint": "eslint . --ext .ts",
@@ -93,7 +92,7 @@
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.7.2",
     "@asyncapi/specs": "^6.8.0",
-    "@clack/prompts": "^0.7.0",
+    "@clack/prompts": "^0.10.0",
     "@oclif/core": "^4",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-warn-if-update-available": "^3.1.20",
@@ -102,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"