bump-cli 2.8.4 → 2.9.1

package/dist/definition.js

@@ -0,0 +1,240 @@
+import { default as $RefParser, getJsonSchemaRefParserDefaultOptions } from '@apidevtools/json-schema-ref-parser';
+import asyncapi from '@asyncapi/specs';
+import { CLIError } from '@oclif/core/errors';
+import { safeStringify } from '@stoplight/yaml';
+import debug from 'debug';
+import { createRequire } from 'node:module';
+import { default as nodePath } from 'node:path';
+// Used to require JSON files
+const require = createRequire(import.meta.url);
+import { Overlay } from './core/overlay.js';
+class SupportedFormat {
+    static asyncapi = {
+        '2.0': asyncapi.schemas['2.0.0'],
+        '2.1': asyncapi.schemas['2.1.0'],
+        '2.2': asyncapi.schemas['2.2.0'],
+        '2.3': asyncapi.schemas['2.3.0'],
+        '2.4': asyncapi.schemas['2.4.0'],
+        '2.5': asyncapi.schemas['2.5.0'],
+        '2.6': asyncapi.schemas['2.6.0'],
+    };
+    static openapi = {
+        '2.0': require('oas-schemas/schemas/v2.0/schema.json'),
+        '3.0': require('oas-schemas/schemas/v3.0/schema.json'),
+        '3.1': require('oas-schemas/schemas/v3.1/schema.json'),
+    };
+}
+class UnsupportedFormat extends CLIError {
+    constructor(message = '') {
+        const compatOpenAPI = Object.keys(SupportedFormat.openapi).join(', ');
+        const compatAsyncAPI = Object.keys(SupportedFormat.asyncapi).join(', ');
+        const errorMsgs = [
+            `Unsupported API specification (${message})`,
+            `Please try again with an OpenAPI ${compatOpenAPI} or AsyncAPI ${compatAsyncAPI} file.`,
+        ];
+        super(errorMsgs.join('\n'));
+    }
+}
+class API {
+    definition;
+    location;
+    overlayedDefinition;
+    rawDefinition;
+    references;
+    spec;
+    specName;
+    version;
+    constructor(location, values) {
+        this.location = location;
+        this.references = [];
+        const [raw, parsed] = this.resolveContent(values);
+        this.rawDefinition = raw;
+        this.definition = parsed;
+        this.specName = this.getSpecName(parsed);
+        this.version = this.getVersion(parsed);
+        this.spec = this.getSpec(parsed);
+        if (this.spec === undefined) {
+            throw new UnsupportedFormat(`${this.specName} ${this.version}`);
+        }
+    }
+    static isAsyncAPI(definition) {
+        return 'asyncapi' in definition;
+    }
+    static isOpenAPI(definition) {
+        return typeof definition.openapi === 'string' || typeof definition.swagger === 'string';
+    }
+    static isOpenAPIOverlay(definition) {
+        return 'overlay' in definition;
+    }
+    static async load(path) {
+        const { json, text, yaml } = getJsonSchemaRefParserDefaultOptions().parse;
+        // Not sure why the lib types the parser as potentially
+        // “undefined”, hence the forced typing in the following consts.
+        const TextParser = text;
+        const JSONParser = json;
+        const YAMLParser = yaml;
+        // We override the default parsers from $RefParser to be able
+        // to keep the raw content of the files parsed
+        const withRawTextParser = (parser) => ({
+            ...parser,
+            async parse(file) {
+                if (typeof parser.parse === 'function' && typeof TextParser.parse === 'function') {
+                    const parsed = (await parser.parse(file));
+                    return { parsed, raw: TextParser.parse(file) };
+                }
+                // Not sure why the lib states that Plugin.parse can be a
+                // scalar number | string (on not only a callable function)
+                return {};
+            },
+        });
+        return $RefParser
+            .resolve(path, {
+            dereference: { circular: false },
+            parse: {
+                json: withRawTextParser(JSONParser),
+                text: {
+                    ...TextParser,
+                    canParse: ['.md', '.markdown'],
+                    encoding: 'utf8',
+                    async parse(file) {
+                        if (typeof TextParser.parse === 'function') {
+                            const parsed = (await TextParser.parse(file));
+                            return { parsed, raw: parsed };
+                        }
+                        // Not sure why the lib states that Plugin.parse can be a
+                        // scalar number | string (on not only a callable function)
+                        return {};
+                    },
+                },
+                yaml: withRawTextParser(YAMLParser),
+            },
+        })
+            .then(($refs) => {
+            const values = $refs.values();
+            return new API(path, values);
+        })
+            .catch((error) => {
+            throw new CLIError(error);
+        });
+    }
+    async applyOverlay(overlayPath) {
+        const overlay = await API.load(overlayPath);
+        const overlayDefinition = overlay.definition;
+        if (!API.isOpenAPIOverlay(overlayDefinition)) {
+            throw new Error(`${overlayPath} does not look like an OpenAPI overlay`);
+        }
+        this.overlayedDefinition = await new Overlay().run(this.definition, overlayDefinition);
+    }
+    extractDefinition(outputPath) {
+        const references = [];
+        for (let i = 0; i < this.references.length; i++) {
+            const reference = this.references[i];
+            references.push({
+                content: reference.content,
+                location: reference.location,
+            });
+        }
+        return [this.serializeDefinition(outputPath), references];
+    }
+    getSpec(definition) {
+        if (API.isAsyncAPI(definition)) {
+            return SupportedFormat.asyncapi[this.versionWithoutPatch()];
+        }
+        if (API.isOpenAPIOverlay(definition)) {
+            return { overlay: { type: 'string' } };
+        }
+        return SupportedFormat.openapi[this.versionWithoutPatch()];
+    }
+    getSpecName(definition) {
+        if (API.isAsyncAPI(definition)) {
+            return 'AsyncAPI';
+        }
+        return 'OpenAPI';
+    }
+    getVersion(definition) {
+        if (API.isAsyncAPI(definition)) {
+            return definition.asyncapi;
+        }
+        return (definition.openapi || definition.swagger);
+    }
+    guessFormat(output) {
+        return (output || this.location).endsWith('.json') ? 'json' : 'yaml';
+    }
+    isMainRefPath(path) {
+        // $refs from json-schema-ref-parser lib returns posix style
+        // paths. We need to make sure we compare all paths in posix style
+        // independently of the platform runtime.
+        const resolvedAbsLocation = nodePath
+            .resolve(this.location)
+            .split(nodePath?.win32?.sep)
+            .join(nodePath?.posix?.sep ?? '/');
+        return path === this.location || path === resolvedAbsLocation;
+    }
+    resolveContent(values) {
+        let mainReference = { parsed: {}, raw: '' };
+        for (const [absPath, reference] of Object.entries(values)) {
+            if (this.isMainRefPath(absPath)) {
+                // $refs.values is not properly typed so we need to force it
+                // with the resulting type of our custom defined parser
+                mainReference = reference;
+            }
+            else {
+                // $refs.values is not properly typed so we need to force it
+                // with the resulting type of our custom defined parser
+                const { raw } = reference;
+                if (!raw) {
+                    throw new UnsupportedFormat(`Reference ${absPath} is empty`);
+                }
+                this.references.push({
+                    content: raw,
+                    location: this.resolveRelativeLocation(absPath),
+                });
+            }
+        }
+        const { parsed, raw } = mainReference;
+        if (!parsed || !raw || !(parsed instanceof Object) || !('info' in parsed)) {
+            debug('bump-cli:definition')(`Main location (${this.location}) not found or empty (within ${JSON.stringify(Object.keys(values))})`);
+            throw new UnsupportedFormat("Definition needs to be an object with at least an 'info' key");
+        }
+        if (!API.isOpenAPI(parsed) && !API.isAsyncAPI(parsed) && !API.isOpenAPIOverlay(parsed)) {
+            throw new UnsupportedFormat();
+        }
+        return [raw, parsed];
+    }
+    /* Resolve reference absolute paths to the main api location when possible */
+    resolveRelativeLocation(absPath) {
+        const definitionUrl = this.url();
+        const refUrl = this.url(absPath);
+        if ((refUrl.hostname === '' && // filesystem path
+            (/^\//.test(absPath) || // Unix style
+                /^[A-Za-z]+:[/\\]/.test(absPath))) || // Windows style
+            (/^https?:\/\//.test(absPath) && definitionUrl.hostname === refUrl.hostname) // Same domain URLs
+        ) {
+            const relativeLocation = nodePath.relative(nodePath.dirname(this.location), absPath);
+            debug('bump-cli:definition')(`Resolved relative $ref location: ${relativeLocation}`);
+            return relativeLocation;
+        }
+        return absPath;
+    }
+    serializeDefinition(outputPath) {
+        if (this.overlayedDefinition) {
+            return this.guessFormat(outputPath) === 'json'
+                ? JSON.stringify(this.overlayedDefinition)
+                : safeStringify(this.overlayedDefinition);
+        }
+        return this.rawDefinition;
+    }
+    versionWithoutPatch() {
+        const [major, minor] = this.version.split('.', 3);
+        return `${major}.${minor}`;
+    }
+    url(location = this.location) {
+        try {
+            return new URL(location);
+        }
+        catch {
+            return { hostname: '' };
+        }
+    }
+}
+export { API, SupportedFormat };

package/dist/flags.d.ts

@@ -0,0 +1,48 @@
+import { Interfaces } from '@oclif/core';
+declare const doc: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+declare const docName: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+declare const hub: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+declare const filenamePattern: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+declare const branch: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+declare const token: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+declare const autoCreate: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
+declare const interactive: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
+declare const dryRun: (opts?: Partial<Interfaces.BooleanFlag<boolean>>) => Interfaces.BooleanFlag<boolean>;
+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 format: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+declare const expires: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+declare const out: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+declare const overlay: Interfaces.FlagDefinition<string, Interfaces.CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+export { autoCreate, branch, doc, docName, dryRun, expires, failOnBreaking, filenamePattern, format, hub, interactive, live, open, out, overlay, token, };

package/dist/flags.js

@@ -0,0 +1,120 @@
+import { Flags } from '@oclif/core';
+// import * as Parser from '@oclif/parser';
+// Re-export oclif flags https://oclif.io/docs/flags
+// export * from '@oclif/command/lib/flags';
+// Custom flags for bump-cli
+const doc = Flags.custom({
+    char: 'd',
+    async default() {
+        const envDoc = process.env.BUMP_ID;
+        if (envDoc)
+            return envDoc;
+        // Search doc id in .bump/config.json file?
+    },
+    description: 'Documentation public id or slug. Can be provided via BUMP_ID environment variable',
+});
+const docName = Flags.custom({
+    char: 'n',
+    dependsOn: ['auto-create'],
+    description: 'Documentation name. Used with --auto-create flag.',
+});
+const hub = Flags.custom({
+    char: 'b',
+    async default() {
+        const envHub = process.env.BUMP_HUB_ID;
+        if (envHub)
+            return envHub;
+        // Search hub id in .bump/config.json file?
+    },
+    description: 'Hub id or slug. Can be provided via BUMP_HUB_ID environment variable',
+});
+const filenamePattern = Flags.custom({
+    default: '{slug}-api',
+    description: `Pattern to extract the documentation slug from filenames when deploying a DIRECTORY. Pattern uses only '*' and '{slug}' as special characters to extract the slug from a filename without extension. Used with --hub flag only.`,
+});
+const branch = Flags.custom({
+    char: 'B',
+    async default() {
+        const envBranch = process.env.BUMP_BRANCH_NAME;
+        if (envBranch)
+            return envBranch;
+    },
+    description: 'Branch name. Can be provided via BUMP_BRANCH_NAME environment variable',
+});
+const token = Flags.custom({
+    char: 't',
+    async default() {
+        const envToken = process.env.BUMP_TOKEN;
+        if (envToken)
+            return envToken;
+    },
+    description: 'Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable',
+    required: true,
+});
+const autoCreate = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        dependsOn: ['hub'],
+        description: 'Automatically create the documentation if needed (only available with a --hub flag). Documentation name can be provided with --doc-name flag. Default: false',
+    });
+};
+const interactive = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        dependsOn: ['hub'],
+        description: "Interactively create a configuration file to deploy a Hub (only available with a --hub flag). This will start an interactive process if you don't have a CLI configuration file. Default: false",
+    });
+};
+const dryRun = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        description: 'Validate a new documentation version. Does everything a normal deploy would do except publishing the new version. Useful in automated environments such as test platforms or continuous integration. Default: false',
+    });
+};
+const open = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        char: 'o',
+        default: false,
+    });
+};
+const failOnBreaking = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        char: 'F',
+        async default() {
+            const envCi = process.env.CI;
+            if (envCi) {
+                return true;
+            }
+            return false;
+        },
+        description: 'Fail when diff contains a breaking change',
+    });
+};
+const live = (opts = {}) => {
+    return Flags.boolean({
+        ...opts,
+        char: 'l',
+        default: false,
+    });
+};
+const format = Flags.custom({
+    char: 'f',
+    default: 'text',
+    description: 'Format in which to provide the diff result',
+    options: ['text', 'markdown', 'json', 'html'],
+});
+const expires = Flags.custom({
+    char: 'e',
+    description: "Specify a longer expiration date for public diffs (defaults to 1 day). Use iso8601 format to provide a date, or you can use `--expires 'never'` to keep the result live indefinitely.",
+});
+const out = Flags.custom({
+    char: 'o',
+    description: 'Output file path',
+});
+const overlay = Flags.custom({
+    char: 'o',
+    description: 'Path or URL of an overlay file to apply before deploying',
+});
+export { autoCreate, branch, doc, docName, dryRun, expires, failOnBreaking, filenamePattern, format, hub, interactive, live, open, out, overlay, token, };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import Deploy from './commands/deploy.js';
+import Diff from './commands/diff.js';
+import Overlay from './commands/overlay.js';
+import Preview from './commands/preview.js';
+export declare const COMMANDS: {
+    deploy: typeof Deploy;
+    diff: typeof Diff;
+    overlay: typeof Overlay;
+    preview: typeof Preview;
+};
+export { DiffResponse, PreviewResponse, VersionResponse, WithDiff } from './api/models.js';
+export { default as Deploy } from './commands/deploy.js';
+export { default as Preview } from './commands/preview.js';
+export * as Diff from './core/diff.js';
+export * as Overlay from './core/overlay.js';
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1,15 @@
+import Deploy from './commands/deploy.js';
+import Diff from './commands/diff.js';
+import Overlay from './commands/overlay.js';
+import Preview from './commands/preview.js';
+export const COMMANDS = {
+    deploy: Deploy,
+    diff: Diff,
+    overlay: Overlay,
+    preview: Preview,
+};
+export { default as Deploy } from './commands/deploy.js';
+export { default as Preview } from './commands/preview.js';
+export * as Diff from './core/diff.js';
+export * as Overlay from './core/overlay.js';
+export { run } from '@oclif/core';