bump-cli 2.9.4 → 2.9.6

package/README.md

@@ -88,7 +88,7 @@ $ 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.3 linux-x64 node-v20.18.1
+  bump-cli/2.9.5 linux-x64 node-v20.18.1
 
 USAGE
   $ bump [COMMAND]
@@ -178,7 +178,7 @@ Please check `bump deploy --help` for more usage details.
 ### The `diff` command
 
 Using the `diff` command can help to spot differences between the local API
-document and the latest deployed version. 
+document and the latest deployed version.
 
 #### Public API diffs
 
@@ -196,7 +196,7 @@ Modified: GET /consommations
 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. 
+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
@@ -230,6 +230,14 @@ bump diff path/to/your/file.yml path/to/your/next-file.yml --doc my-documentatio
 
 Please check `bump diff --help` for full usage details.
 
+#### Diffs with overlayed source files
+
+The `bump diff` command also supports [overlays](#the-overlay-command). This means you can pass the `--overlay my-overlay-file.yml` flag to the command and it will apply the overlay on both files **before** running the diff. E.g.:
+
+```shell
+bump diff --overlay my-overlay.yml path/to/your/file.yml path/to/your/next-file.yml
+```
+
 ### The `preview` command
 
 When writing documentation, you might want to preview how it renders on Bump.sh.

package/dist/api/models.d.ts

@@ -29,6 +29,7 @@ export interface VersionRequest {
     hub?: string;
     previous_version_id?: string;
     references?: Reference[];
+    temporary?: boolean;
     unpublished?: boolean;
 }
 export interface VersionResponse {

package/dist/commands/deploy.d.ts

@@ -16,9 +16,10 @@ export default class Deploy extends BaseCommand<typeof Deploy> {
         hub: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         interactive: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         overlay: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        preview: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         token: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     protected deployDirectory(dir: string, dryRun: boolean, token: string, hub: string, autoCreate: boolean, interactive: boolean, filenamePattern: string, documentationName: string | undefined, branch: string | undefined): Promise<void>;
-    protected deploySingleFile(api: API, dryRun: boolean, documentation: string, token: string, hub: string | undefined, autoCreate: boolean, documentationName: string | undefined, branch: string | undefined, overlay?: string[] | undefined): Promise<void>;
+    protected deploySingleFile(api: API, dryRun: boolean, documentation: string, token: string, hub: string | undefined, autoCreate: boolean, documentationName: string | undefined, branch: string | undefined, overlay?: string[] | undefined, temporary?: boolean | undefined): Promise<void>;
     run(): Promise<void>;
 }

package/dist/commands/deploy.js

@@ -58,6 +58,7 @@ ${chalk.dim('$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_tok
         hub: flagsBuilder.hub(),
         interactive: flagsBuilder.interactive(),
         overlay: flagsBuilder.overlay(),
+        preview: flagsBuilder.preview(),
         token: flagsBuilder.token(),
     };
     async deployDirectory(dir, dryRun, token, hub, autoCreate, interactive, filenamePattern, documentationName, branch) {
@@ -98,15 +99,15 @@ ${chalk.dim('$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_tok
             throw new CLIError(`No documentation found in ${dir} with the pattern '${filenamePattern}'.\nYou should check with the ${chalk.dim('--filename-pattern')} flag to select your files from your naming convention.\nIf you don't have a naming convention we can help naming your API definition files:\nTry the ${chalk.dim('--interactive')} flag for that.`);
         }
     }
-    async deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay) {
+    async deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay, temporary) {
         ux.action.status = `...a new version to your ${documentation} documentation`;
-        const response = await new CoreDeploy(this.bump).run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay);
+        const response = await new CoreDeploy(this.bump).run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay, temporary);
         if (dryRun) {
             ux.stdout(ux.colorize('green', 'Definition is valid'));
         }
         else if (response) {
             process.stdout.write(ux.colorize('green', `Your ${documentation} documentation...`));
-            ux.stdout(ux.colorize('green', `has received a new deployment which will soon be ready at:`));
+            ux.stdout(ux.colorize('green', `has received a new ${temporary ? 'preview' : 'deployment'} which will soon be ready at:`));
             ux.stdout(ux.colorize('underline', response.doc_public_url));
         }
         else {
@@ -121,7 +122,7 @@ ${chalk.dim('$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_tok
     */
     async run() {
         const { args, flags } = await this.parse(Deploy);
-        const [dryRun, documentation, token, hub, autoCreate, interactive, filenamePattern, documentationName, branch, overlay,] = [
+        const [dryRun, documentation, token, hub, autoCreate, interactive, filenamePattern, documentationName, branch, overlay, temporary,] = [
             flags['dry-run'],
             flags.doc,
             flags.token,
@@ -134,8 +135,10 @@ ${chalk.dim('$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_tok
             flags['doc-name'],
             flags.branch,
             flags.overlay,
+            /* when --preview is provided, generate temporary version */
+            flags.preview,
         ];
-        const action = dryRun ? 'validate' : 'deploy';
+        const action = dryRun ? 'validate' : temporary ? 'preview' : 'deploy';
         ux.action.start(`Let's ${action} on Bump.sh`);
         if (isDir(args.file)) {
             if (hub) {
@@ -148,7 +151,7 @@ ${chalk.dim('$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_tok
         else if (documentation) {
             const api = await API.load(args.file);
             this.d(`${args.file} looks like an ${api.specName} spec version ${api.version}`);
-            await this.deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay);
+            await this.deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay, temporary);
         }
         else {
             throw new CLIError('Missing required flag --doc=<slug>');

package/dist/commands/diff.d.ts

@@ -14,6 +14,7 @@ export default class Diff extends BaseCommand<typeof Diff> {
         'fail-on-breaking': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         hub: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        overlay: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     displayCompareResult(result: DiffResponse, format: string, failOnBreaking: boolean): Promise<void>;

package/dist/commands/diff.js

@@ -48,6 +48,7 @@ export default class Diff extends BaseCommand {
         'fail-on-breaking': flagsBuilder.failOnBreaking({ allowNo: true }),
         format: flagsBuilder.format(),
         hub: flagsBuilder.hub(),
+        overlay: flagsBuilder.overlay(),
         token: flagsBuilder.token({ required: false }),
     };
     async displayCompareResult(result, format, failOnBreaking) {
@@ -78,13 +79,14 @@ export default class Diff extends BaseCommand {
     */
     async run() {
         const { args, flags } = await this.parse(Diff);
-        const [documentation, hub, branch, token, format, expires] = [
+        const [documentation, hub, branch, token, format, expires, overlays] = [
             flags.doc,
             flags.hub,
             flags.branch,
             flags.token,
             flags.format,
             flags.expires,
+            flags.overlay,
         ];
         if (format === 'text') {
             if (args.otherFile) {
@@ -98,7 +100,7 @@ export default class Diff extends BaseCommand {
             throw new CLIError('Please provide a second file argument or login with an existing token');
         }
         ux.action.status = '...diff on Bump.sh in progress';
-        const diff = await new CoreDiff(this.config).run(args.file, args.otherFile, documentation, hub, branch, token, format, expires);
+        const diff = await new CoreDiff(this.config).run(args.file, args.otherFile, documentation, hub, branch, token, format, expires, overlays);
         ux.action.stop();
         if (diff) {
             await this.displayCompareResult(diff, format, flags['fail-on-breaking']);

package/dist/commands/overlay.js

@@ -29,12 +29,12 @@ ${chalk.dim('$ bump overlay DEFINITION_FILE OVERLAY_FILE > destination/file.json
     async run() {
         const { args, flags } = await this.parse(Overlay);
         const outputPath = flags.out;
+        const { file, overlay } = args;
         ux.action.start("* Let's apply the overlay to the main definition");
         ux.action.status = '...loading definition file';
-        const api = await API.load(args.file);
+        const api = await API.load(file);
         ux.action.status = '...applying overlay';
-        await api.applyOverlay(args.overlay);
-        const [overlayedDefinition] = api.extractDefinition(outputPath);
+        const [overlayedDefinition] = await api.extractDefinition(outputPath, [overlay]);
         ux.action.stop();
         if (outputPath) {
             await mkdir(dirname(outputPath), { recursive: true });

package/dist/commands/preview.js

@@ -37,7 +37,7 @@ export default class Preview extends BaseCommand {
     }
     async preview(file, open = false, currentPreview = undefined) {
         const api = await API.load(file);
-        const [definition, references] = api.extractDefinition();
+        const [definition, references] = await api.extractDefinition();
         this.d(`${file} looks like an ${api.specName} spec version ${api.version}`);
         const request = {
             definition,

package/dist/core/deploy.d.ts

@@ -6,6 +6,6 @@ export declare class Deploy {
     constructor(bumpClient: BumpApi);
     protected createVersion(request: VersionRequest, token: string): Promise<VersionResponse | undefined>;
     d(formatter: any, ...args: any[]): void;
-    run(api: API, dryRun: boolean, documentation: string, token: string, hub: string | undefined, autoCreate: boolean, documentationName: string | undefined, branch: string | undefined, overlay?: string[] | undefined): Promise<VersionResponse | undefined>;
+    run(api: API, dryRun: boolean, documentation: string, token: string, hub: string | undefined, autoCreate: boolean, documentationName: string | undefined, branch: string | undefined, overlay?: string[] | undefined, temporary?: boolean | false): Promise<VersionResponse | undefined>;
     validateVersion(version: VersionRequest, token: string): Promise<undefined>;
 }

package/dist/core/deploy.js

@@ -26,18 +26,9 @@ export class Deploy {
     d(formatter, ...args) {
         return debug(`bump-cli:core:deploy`)(formatter, ...args);
     }
-    async run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay) {
+    async run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay, temporary) {
         let version;
-        if (overlay) {
-            /* eslint-disable no-await-in-loop */
-            // Alternatively we can apply all overlays in parallel
-            // https://stackoverflow.com/questions/48957022/unexpected-await-inside-a-loop-no-await-in-loop
-            for (const overlayFile of overlay) {
-                await api.applyOverlay(overlayFile);
-            }
-            /* eslint-enable no-await-in-loop */
-        }
-        const [definition, references] = api.extractDefinition();
+        const [definition, references] = await api.extractDefinition(undefined, overlay);
         const request = {
             auto_create_documentation: autoCreate && !dryRun,
             branch_name: branch,
@@ -46,6 +37,7 @@ export class Deploy {
             documentation_name: documentationName,
             hub,
             references,
+            temporary,
         };
         if (dryRun) {
             await this.validateVersion(request, token);

package/dist/core/diff.d.ts

@@ -8,14 +8,14 @@ export declare class Diff {
     constructor(config?: Config);
     get bumpClient(): BumpApi;
     get pollingPeriod(): number;
-    createDiff(file1: string, file2: string, expires: string | undefined): Promise<DiffResponse | undefined>;
-    createVersion(file: string, documentation: string, token: string, hub: string | undefined, branch_name: string | undefined, previous_version_id?: string | undefined): Promise<VersionResponse | undefined>;
+    createDiff(file1: string, file2: string, expires: string | undefined, overlays?: string[] | undefined): Promise<DiffResponse | undefined>;
+    createVersion(file: string, documentation: string, token: string, hub: string | undefined, branch_name: string | undefined, previous_version_id?: string | undefined, overlays?: string[] | undefined): Promise<VersionResponse | undefined>;
     d(formatter: any, ...args: any[]): void;
     extractDiff(versionWithDiff: VersionResponse & WithDiff): DiffResponse;
     isVersion(result: DiffResponse | VersionResponse): result is VersionResponse;
     isVersionWithDiff(result: DiffResponse | (VersionResponse & WithDiff)): result is VersionResponse & WithDiff;
     pollingDelay(): Promise<void>;
-    run(file1: string, file2: string | undefined, documentation: string | undefined, hub: string | undefined, branch: string | undefined, token: string | undefined, format: string, expires: string | undefined): Promise<DiffResponse | undefined>;
+    run(file1: string, file2: string | undefined, documentation: string | undefined, hub: string | undefined, branch: string | undefined, token: string | undefined, format: string, expires: string | undefined, overlays: string[] | undefined): Promise<DiffResponse | undefined>;
     waitResult(result: DiffResponse | VersionResponse, token: string | undefined, opts: {
         format: string;
         timeout: number;

package/dist/core/diff.js

@@ -22,11 +22,11 @@ export class Diff {
     get pollingPeriod() {
         return process.env.BUMP_POLLING_PERIOD ? Number(process.env.BUMP_POLLING_PERIOD) : 1000;
     }
-    async createDiff(file1, file2, expires) {
+    async createDiff(file1, file2, expires, overlays) {
         const api = await API.load(file1);
-        const [previous_definition, previous_references] = api.extractDefinition();
+        const [previous_definition, previous_references] = await api.extractDefinition(undefined, overlays);
         const api2 = await API.load(file2);
-        const [definition, references] = api2.extractDefinition();
+        const [definition, references] = await api2.extractDefinition(undefined, overlays);
         const request = {
             definition,
             expires_at: expires,
@@ -47,9 +47,9 @@ export class Diff {
             }
         }
     }
-    async createVersion(file, documentation, token, hub, branch_name, previous_version_id = undefined) {
+    async createVersion(file, documentation, token, hub, branch_name, previous_version_id = undefined, overlays) {
         const api = await API.load(file);
-        const [definition, references] = api.extractDefinition();
+        const [definition, references] = await api.extractDefinition(undefined, overlays);
         const request = {
             branch_name,
             definition,
@@ -98,12 +98,12 @@ export class Diff {
     async pollingDelay() {
         await this.delay(this.pollingPeriod);
     }
-    async run(file1, file2, documentation, hub, branch, token, format, expires) {
+    async run(file1, file2, documentation, hub, branch, token, format, expires, overlays) {
         if (!this._config)
             this._config = await Config.load(resolve(import.meta.dirname, './../../'));
         let diffVersion;
         if (file2 && (!documentation || !token)) {
-            diffVersion = await this.createDiff(file1, file2, expires);
+            diffVersion = await this.createDiff(file1, file2, expires, overlays);
         }
         else {
             if (!documentation || !token) {

package/dist/core/overlay.js

@@ -36,6 +36,23 @@ export class Overlay {
                     process.stderr.write(`WARNING: Action target '${target}' has no matching elements\n`);
                     continue;
                 }
+                // When we execute a 'remove' action we need to be careful if
+                // the targets are elements of an array. Because the list of
+                // paths contains an index of each element.
+                //
+                // E.g.
+                // ["servers"][0]
+                // ["servers"][1]
+                // ["servers"][2]
+                //
+                // And if we remove elements starting from the 0, the array
+                // will be reindexed and thus the '2' index won't be valid
+                // anymore.
+                //
+                // Thus, in that case we revers the list of paths
+                if (action.remove) {
+                    paths.reverse();
+                }
                 for (const path of paths) {
                     // The 'executeAction' will mutate the passed spec object in
                     // place.
@@ -71,9 +88,11 @@ export class Overlay {
         // Do the overlay action
         // Is it a remove?
         if (Object.hasOwn(action, 'remove')) {
+            this.d(`Executing 'remove' on target path: ${path}`);
             this.remove(parent, thingToActUpon);
         }
         else if (Object.hasOwn(action, 'update')) {
+            this.d(`Executing 'update' on target path: ${path}`);
             spec = this.update(spec, parent, action.update, thingToActUpon);
         }
         else {

package/dist/definition.d.ts

@@ -19,7 +19,7 @@ declare class API {
     static isOpenAPIOverlay(definition: JSONSchema4Object | JSONSchema6Object): definition is OpenAPIOverlay;
     static load(path: string): Promise<API>;
     applyOverlay(overlayPath: string): Promise<void>;
-    extractDefinition(outputPath?: string): [string, APIReference[]];
+    extractDefinition(outputPath?: string, overlays?: string[] | undefined): Promise<[string, APIReference[]]>;
     getSpec(definition: APIDefinition): SpecSchema;
     getSpecName(definition: APIDefinition): string;
     getVersion(definition: APIDefinition): string;

package/dist/definition.js

@@ -124,9 +124,24 @@ class API {
         if (!API.isOpenAPIOverlay(overlayDefinition)) {
             throw new Error(`${overlayPath} does not look like an OpenAPI overlay`);
         }
+        for (const reference of overlay.references) {
+            // Keep overlay reference data only if there's no existing refs with the same location
+            if (this.references.every((existing) => existing.location !== reference.location)) {
+                this.references.push(reference);
+            }
+        }
         this.overlayedDefinition = await new Overlay().run(currentDefinition, overlayDefinition);
     }
-    extractDefinition(outputPath) {
+    async extractDefinition(outputPath, overlays) {
+        if (overlays) {
+            /* eslint-disable no-await-in-loop */
+            // Alternatively we can apply all overlays in parallel
+            // https://stackoverflow.com/questions/48957022/unexpected-await-inside-a-loop-no-await-in-loop
+            for (const overlayFile of overlays) {
+                await this.applyOverlay(overlayFile);
+            }
+            /* eslint-enable no-await-in-loop */
+        }
         const references = [];
         for (let i = 0; i < this.references.length; i++) {
             const reference = this.references[i];
@@ -220,7 +235,7 @@ class API {
     serializeDefinition(outputPath) {
         if (this.overlayedDefinition) {
             const { comments } = parseWithPointers(this.rawDefinition, { attachComments: true });
-            const dumpOptions = { comments, lineWidth: Number.POSITIVE_INFINITY };
+            const dumpOptions = { comments, lineWidth: Number.POSITIVE_INFINITY, noRefs: true };
             return this.guessFormat(outputPath) === 'json'
                 ? JSON.stringify(this.overlayedDefinition)
                 : safeStringify(this.overlayedDefinition, dumpOptions);

package/dist/flags.d.ts

@@ -29,6 +29,7 @@ declare const dryRun: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Inter
 declare const open: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
 declare const failOnBreaking: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
 declare const live: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
+declare const preview: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
 declare const format: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
     multiple: false;
     requiredOrDefaulted: true;
@@ -45,4 +46,4 @@ declare const overlay: Interfaces.FlagDefinition<string[], Interfaces.CustomOpti
     multiple: true;
     requiredOrDefaulted: false;
 }>;
-export { autoCreate, branch, doc, docName, dryRun, expires, failOnBreaking, filenamePattern, format, hub, interactive, live, open, out, overlay, token, };
+export { autoCreate, branch, doc, docName, dryRun, expires, failOnBreaking, filenamePattern, format, hub, interactive, live, open, out, overlay, preview, token, };

package/dist/flags.js

@@ -96,6 +96,14 @@ const live = (opts = {}) => {
         default: false,
     });
 };
+const preview = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        char: 'p',
+        default: false,
+        description: 'Generate a preview in your API context. The resulting version is temporary and not visible by your documentation viewers.',
+    });
+};
 const format = Flags.custom({
     char: 'f',
     default: 'text',
@@ -115,4 +123,4 @@ const overlay = Flags.custom({
     description: 'Path or URL of overlay file(s) to apply before deploying',
     multiple: true,
 });
-export { autoCreate, branch, doc, docName, dryRun, expires, failOnBreaking, filenamePattern, format, hub, interactive, live, open, out, overlay, token, };
+export { autoCreate, branch, doc, docName, dryRun, expires, failOnBreaking, filenamePattern, format, hub, interactive, live, open, out, overlay, preview, token, };

package/oclif.manifest.json

@@ -92,12 +92,18 @@
           "multiple": true,
           "type": "option"
         },
+        "preview": {
+          "char": "p",
+          "description": "Generate a preview in your API context. The resulting version is temporary and not visible by your documentation viewers.",
+          "name": "preview",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "token": {
           "char": "t",
           "description": "Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable",
           "name": "token",
           "required": true,
-          "default": "99f52837852249b328c0a00249f846a3",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -186,12 +192,19 @@
           "multiple": false,
           "type": "option"
         },
+        "overlay": {
+          "char": "o",
+          "description": "Path or URL of overlay file(s) to apply before deploying",
+          "name": "overlay",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
         "token": {
           "char": "t",
           "description": "Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable",
           "name": "token",
           "required": false,
-          "default": "99f52837852249b328c0a00249f846a3",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -279,5 +292,5 @@
       "strict": true
     }
   },
-  "version": "2.9.4"
+  "version": "2.9.6"
 }

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.4",
+  "version": "2.9.6",
   "author": "Paul Bonaud <paulr@bump.sh>",
   "bin": {
     "bump": "./bin/run.js"
@@ -29,7 +29,7 @@
     "np": "^10.1.0",
     "nyc": "^17.1.0",
     "oclif": "^4",
-    "shx": "^0.3.3",
+    "shx": "^0.4.0",
     "sinon": "^19.0.2",
     "ts-node": "^10",
     "typescript": "^5"