diff --git a/apps/generator-cli/src/README.md b/apps/generator-cli/src/README.md index 3486db1f6cf..22ea03cd079 100644 --- a/apps/generator-cli/src/README.md +++ b/apps/generator-cli/src/README.md @@ -165,6 +165,38 @@ Further it is also possible to configure generators, for example: If `openapi-generator-cli generate` is called without further arguments, then the configuration is automatically used to generate your code. 🎉 +### Config file location + +By default, `openapi-generator-cli` reads and writes *openapitools.json* in the current working directory. +To use a config file somewhere else (e.g. in a monorepo with a shared configuration), pass a global option +before the command or set an environment variable: + +```sh +# global option (place it before the command) +openapi-generator-cli -c /path/to/openapitools.json generate -i spec.yaml -g ruby + +# the long form works as well and is equivalent to the existing --openapitools option +openapi-generator-cli --config /path/to/openapitools.json version-manager list + +# via environment variable, e.g. in CI +OPENAPI_GENERATOR_CLI_CONFIG=/path/to/openapitools.json openapi-generator-cli generate +``` + +The config file location is resolved in the following order: + +1. the global option `-c, --config ` or `--openapitools ` +2. the `OPENAPI_GENERATOR_CLI_CONFIG` environment variable +3. *./openapitools.json* (default) + +Relative paths are resolved against the current working directory. When an explicit path is given +(via option or environment variable) but the file does not exist, the CLI exits with an error instead +of silently creating a new configuration file. When neither the option nor the environment variable is +set, the default *./openapitools.json* is used (and created on first usage), just like before. + +`-c` and `--config` must be placed **before** the command name — afterwards they belong to the +invoked command itself. For example, the config file in `openapi-generator-cli generate -c generator-config.yaml` +is the generator configuration read by the Java generator, not the *openapitools.json* location. + ##### Available placeholders diff --git a/apps/generator-cli/src/app/app.module.spec.ts b/apps/generator-cli/src/app/app.module.spec.ts index df3a81b6cdd..bcb6f82f937 100644 --- a/apps/generator-cli/src/app/app.module.spec.ts +++ b/apps/generator-cli/src/app/app.module.spec.ts @@ -149,6 +149,10 @@ describe('AppModule', () => { describe.each([ ['the separate option value', ['--openapitools', 'x.json']], ['the inline option value', ['--openapitools=x.json']], + ['the separate -c option value', ['-c', 'x.json']], + ['the separate --config option value', ['--config', 'x.json']], + ['the inline --config option value', ['--config=x.json']], + ['the attached -c option value', ['-cx.json']], ])('version-manager resolve with %s', (_, configArgs) => { beforeEach(async () => { process.argv = [ @@ -191,6 +195,66 @@ describe('AppModule', () => { }); }); + describe('a command is invoked with its own -c/--config option', () => { + beforeEach(async () => { + process.argv = [ + 'foo', + 'baz', + 'generate', + '-i', + 'spec.yaml', + '-c', + 'gen-cfg.yaml', + ]; + programMock.parse.mockImplementation(() => undefined); + versionManagerServiceMock.getSelectedVersion.mockReturnValue('1.2.3'); + await fixture.onApplicationBootstrap(); + }); + + it('hands the command arguments untouched to commander', () => { + expect(programMock.parse).toHaveBeenCalledWith([ + 'foo', + 'baz', + 'generate', + '-i', + 'spec.yaml', + '-c', + 'gen-cfg.yaml', + ]); + }); + }); + + describe.each([ + ['the separate -c option value', ['-c', 'x.json']], + ['the separate --config option value', ['--config', 'x.json']], + ['the inline --config option value', ['--config=x.json']], + ['the attached -c option value', ['-cx.json']], + ])('a global -c/--config option is used as %s before the command', (_, configArgs) => { + beforeEach(async () => { + process.argv = [ + 'foo', + 'baz', + ...configArgs, + 'version-manager', + 'resolve', + 'latest', + ]; + programMock.parse.mockImplementation(() => undefined); + versionManagerServiceMock.getSelectedVersion.mockReturnValue('1.2.3'); + await fixture.onApplicationBootstrap(); + }); + + it('hands commander an argv without the config option, so the command is dispatched', () => { + expect(programMock.parse).toHaveBeenCalledWith([ + 'foo', + 'baz', + 'version-manager', + 'resolve', + 'latest', + ]); + }); + }); + describe('a custom generator is provided', () => { beforeEach(async () => { process.argv = [ diff --git a/apps/generator-cli/src/app/app.module.ts b/apps/generator-cli/src/app/app.module.ts index 3bdd5ee292e..c574aababb1 100644 --- a/apps/generator-cli/src/app/app.module.ts +++ b/apps/generator-cli/src/app/app.module.ts @@ -7,6 +7,9 @@ import { COMMANDER_PROGRAM, LOGGER } from './constants'; import { VersionManagerController } from './controllers/version-manager.controller'; import { ConfigService, + extractGlobalConfigArgs, +} from './services/config.service'; +import { GeneratorService, PassThroughService, UIService, @@ -49,6 +52,21 @@ if (hasHttpsProxyEnvs) { .option( '--openapitools ', 'Use the specified openapi-generator-cli configuration file', + ) + // The global `-c, --config ` option is intentionally NOT + // registered with commander: commander would consume it from the whole + // argv — including after the command name — which would swallow the + // Java generator's own `generate -c, --config ` option. + // Instead, it is only honored BEFORE the command name by ConfigService + // (see extractGlobalConfigArgs) and stripped from the argv handed to + // commander below. It is listed here so it still shows up in the help. + .addHelpText( + 'after', + '\nGlobal config option (must be placed before the command name):\n\n' + + ' -c, --config \n' + + ' Use the specified openapi-generator-cli configuration file (alternative to --openapitools, also available via the ' + + ConfigService.envConfigVariable + + ' environment variable)\n', ), }, { provide: LOGGER, useValue: console }, @@ -86,7 +104,13 @@ export class AppModule implements OnApplicationBootstrap { if (!isVersionManagerResolveCommand) { await this.passThroughService.init(); } - this.program.parse(process.argv); + // Remove the global -c/--config options from the argv handed to commander: + // they are not registered (see above), and an unrecognized option before + // the command name would make commander treat the command itself as an + // unknown argument and skip its dispatch. + this.program.parse( + extractGlobalConfigArgs(process.argv).argvWithoutGlobalConfigArgs, + ); }; private isVersionManagerResolveCommand() { @@ -96,12 +120,20 @@ export class AppModule implements OnApplicationBootstrap { while (commandIndex < args.length) { const arg = args[commandIndex]; - if (arg === '--openapitools') { + if ( + arg === '--openapitools' || + arg === '--config' || + arg === '-c' + ) { commandIndex += 2; continue; } - if (arg.startsWith('--openapitools=')) { + if ( + arg.startsWith('--openapitools=') || + arg.startsWith('--config=') || + (arg.startsWith('-c') && arg.length > 2) + ) { commandIndex += 1; continue; } diff --git a/apps/generator-cli/src/app/services/config.service.spec.ts b/apps/generator-cli/src/app/services/config.service.spec.ts index 9947c2f4f72..5a7fcb428a4 100644 --- a/apps/generator-cli/src/app/services/config.service.spec.ts +++ b/apps/generator-cli/src/app/services/config.service.spec.ts @@ -1,5 +1,6 @@ import { Test } from '@nestjs/testing'; import { Command, createCommand } from 'commander'; +import * as path from 'path'; import { ConfigService } from './config.service'; import { LOGGER, COMMANDER_PROGRAM } from '../constants'; @@ -14,7 +15,19 @@ describe('ConfigService', () => { const log = jest.fn(); const error = jest.fn(); + let originalArgv: string[]; + beforeEach(async () => { + // the config file is resolved from process.argv, pin it to a plain cli + // invocation so the runner's own arguments (e.g. jest's --config) are not + // mistaken for cli options + originalArgv = process.argv; + process.argv = ['node', 'openapi-generator-cli']; + // keep the host environment from leaking into the resolution: an exported + // OPENAPI_GENERATOR_CLI_CONFIG would send every ConfigService construction + // in this suite down the config-not-found path + delete process.env[ConfigService.envConfigVariable]; + program = createCommand(); jest.spyOn(program, 'helpInformation'); @@ -32,6 +45,10 @@ describe('ConfigService', () => { fs.ensureFileSync.mockReset(); }); + afterEach(() => { + process.argv = originalArgv; + }); + describe('API', () => { describe('get()', () => { describe.each([ @@ -194,33 +211,280 @@ describe('ConfigService', () => { }); describe('configFileOrDefault()', () => { + let exitSpy: jest.SpyInstance; + let originalEnv: NodeJS.ProcessEnv; + + const createFixture = async ( + argv: string[] = ['node', 'openapi-generator-cli'], + ): Promise => { + process.argv = argv; + program = createCommand().option( + '--openapitools ', + 'Use the specified openapi-generator-cli configuration file', + ); + + fs.writeJSONSync.mockReset(); + fs.readJSONSync.mockReset(); + fs.ensureFileSync.mockReset(); + + const moduleRef = await Test.createTestingModule({ + providers: [ + ConfigService, + { provide: LOGGER, useValue: { log, error } }, + { provide: COMMANDER_PROGRAM, useValue: program }, + ], + }).compile(); + + return moduleRef.get(ConfigService); + }; + + beforeEach(() => { + fs.existsSync.mockReset(); + error.mockClear(); + exitSpy = jest + .spyOn(process, 'exit') + .mockImplementation((() => undefined) as never); + originalEnv = { ...process.env }; + delete process.env[ConfigService.envConfigVariable]; + }); + + afterEach(() => { + exitSpy.mockRestore(); + process.env = { ...originalEnv }; + process.argv = originalArgv; + }); + describe('--openapitools set', () => { - beforeEach(async () => { - program = createCommand(); - program.opts().openapitools = '/tmp/myopenapitools.json'; - - const moduleRef = await Test.createTestingModule({ - providers: [ - ConfigService, - { provide: LOGGER, useValue: { log } }, - { provide: COMMANDER_PROGRAM, useValue: program }, - ], - }).compile(); - - fixture = moduleRef.get(ConfigService); - fs.writeJSONSync.mockReset(); - fs.readJSONSync.mockReset(); - fs.ensureFileSync.mockReset(); - }); - it('returns path set at cli, if openapitools argument provided', () => { + it('returns path set at cli, if openapitools argument provided', async () => { + fs.existsSync.mockReturnValue(true); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + '--openapitools', + '/tmp/myopenapitools.json', + ]); expect(fixture.configFile).toEqual('/tmp/myopenapitools.json'); }); }); + + describe('-c/--config set before the command', () => { + it.each([ + [ + 'the separate -c option value', + ['-c', '/tmp/my-other-openapitools.json'], + ], + [ + 'the separate --config option value', + ['--config', '/tmp/my-other-openapitools.json'], + ], + [ + 'the inline --config option value', + ['--config=/tmp/my-other-openapitools.json'], + ], + [ + 'the attached -c option value', + ['-c/tmp/my-other-openapitools.json'], + ], + ])( + 'returns the path provided via %s', + async (_, configArgs) => { + fs.existsSync.mockReturnValue(true); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + ...configArgs, + 'version-manager', + 'resolve', + ]); + expect(fixture.configFile).toEqual( + '/tmp/my-other-openapitools.json', + ); + }, + ); + + it('resolves a relative path against the cwd', async () => { + fs.existsSync.mockReturnValue(true); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + '-c', + 'conf/openapi.json', + 'version-manager', + 'resolve', + ]); + expect(fixture.configFile).toEqual( + path.resolve(fixture.cwd, 'conf/openapi.json'), + ); + }); + + it('skips root options with a value, e.g. --custom-generator, before the command', async () => { + fs.existsSync.mockReturnValue(true); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + '--custom-generator', + './my-generator.jar', + '-c', + '/tmp/my-other-openapitools.json', + 'version-manager', + 'resolve', + ]); + expect(fixture.configFile).toEqual( + '/tmp/my-other-openapitools.json', + ); + }); + + it('rejects a trailing -c without a value', async () => { + await expect( + createFixture(['node', 'openapi-generator-cli', '-c']), + ).rejects.toThrow('The -c/--config option requires a value'); + }); + + it('rejects a trailing --config without a value', async () => { + await expect( + createFixture(['node', 'openapi-generator-cli', '--config']), + ).rejects.toThrow('The -c/--config option requires a value'); + }); + }); + + describe('the config options of the invoked command', () => { + it.each([ + ['the separate -c option', ['generate', '-c', 'gen-cfg.yaml']], + [ + 'the separate --config option', + ['generate', '--config', 'gen-cfg.yaml'], + ], + [ + 'the inline --config option', + ['generate', '--config=gen-cfg.yaml'], + ], + ['the attached -c option', ['generate', '-cgen-cfg.yaml']], + [ + 'an option of another command', + ['version-manager', 'list', '-c', 'gen-cfg.yaml'], + ], + ])( + 'is left to the command: %s reaches the command and the default config is used', + async (_, commandArgs) => { + // even a not existing path must not be mistaken for the cli config + fs.existsSync.mockReturnValue(false); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + ...commandArgs, + ]); + expect(fixture.configFile).toEqual( + expect.stringMatching(/[/\\]openapitools\.json$/), + ); + expect(exitSpy).not.toHaveBeenCalled(); + expect(error).not.toHaveBeenCalled(); + }, + ); + }); + + describe(ConfigService.envConfigVariable + ' set', () => { + it('returns the path set via the environment variable', async () => { + fs.existsSync.mockReturnValue(true); + process.env[ConfigService.envConfigVariable] = + '/tmp/env-openapitools.json'; + const fixture = await createFixture(); + expect(fixture.configFile).toEqual('/tmp/env-openapitools.json'); + }); + + it('resolves a relative environment variable path against the cwd', async () => { + fs.existsSync.mockReturnValue(true); + process.env[ConfigService.envConfigVariable] = 'conf/openapi.json'; + const fixture = await createFixture(); + expect(fixture.configFile).toEqual( + path.resolve(fixture.cwd, 'conf/openapi.json'), + ); + }); + }); + + describe('a cli option and the environment variable are set', () => { + it('the cli option takes precedence over the environment variable', async () => { + fs.existsSync.mockReturnValue(true); + process.env[ConfigService.envConfigVariable] = + '/tmp/env-openapitools.json'; + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + '-c', + '/tmp/cli-openapitools.json', + 'version-manager', + 'resolve', + ]); + expect(fixture.configFile).toEqual('/tmp/cli-openapitools.json'); + }); + }); + + describe('--openapitools and -c/--config are both set', () => { + it('--openapitools keeps precedence over -c/--config', async () => { + fs.existsSync.mockReturnValue(true); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + '--openapitools', + '/tmp/openapitools.json', + '-c', + '/tmp/config.json', + 'version-manager', + 'resolve', + ]); + expect(fixture.configFile).toEqual('/tmp/openapitools.json'); + }); + }); + describe('--openapitools not set', () => { - it('returns default path, if openapitools argument not provided', () => { + it('returns default path, if openapitools argument not provided', async () => { + const fixture = await createFixture(); + expect(fixture.configFile).toEqual( + expect.stringMatching(/[/\\]openapitools\.json$/), + ); + }); + }); + + describe('the explicit config file does not exist', () => { + it('logs an error and exits, if the path was set via a cli option', async () => { + fs.existsSync.mockReturnValue(false); + const fixture = await createFixture([ + 'node', + 'openapi-generator-cli', + '-c', + '/tmp/not-existing-openapitools.json', + 'version-manager', + 'resolve', + ]); + expect(fixture.configFile).toEqual('/tmp/not-existing-openapitools.json'); + expect(error).toHaveBeenCalledWith( + expect.stringContaining('/tmp/not-existing-openapitools.json'), + ); + expect(exitSpy).toHaveBeenCalledWith(1); + }); + + it('logs an error and exits, if the path was set via the environment variable', async () => { + fs.existsSync.mockReturnValue(false); + process.env[ConfigService.envConfigVariable] = + '/tmp/not-existing-openapitools.json'; + await createFixture(); + expect(error).toHaveBeenCalledWith( + expect.stringContaining('/tmp/not-existing-openapitools.json'), + ); + expect(error).toHaveBeenCalledWith( + expect.stringContaining(ConfigService.envConfigVariable), + ); + expect(exitSpy).toHaveBeenCalledWith(1); + }); + + it('does not exit, if the default config file does not exist', async () => { + fs.existsSync.mockReturnValue(false); + const errorCallsBefore = error.mock.calls.length; + const fixture = await createFixture(); expect(fixture.configFile).toEqual( expect.stringMatching(/[/\\]openapitools\.json$/), ); + expect(exitSpy).not.toHaveBeenCalled(); + expect(error.mock.calls.length).toBe(errorCallsBefore); }); }); }); diff --git a/apps/generator-cli/src/app/services/config.service.ts b/apps/generator-cli/src/app/services/config.service.ts index e7a68f345c4..2adc070f6e9 100644 --- a/apps/generator-cli/src/app/services/config.service.ts +++ b/apps/generator-cli/src/app/services/config.service.ts @@ -4,21 +4,156 @@ import { COMMANDER_PROGRAM, LOGGER } from '../constants'; import * as fs from 'fs-extra'; import { Command } from 'commander'; +/** + * Result of scanning argv for the global config options. + */ +export interface GlobalConfigArgs { + /** + * The value of the global `-c/--config ` option, if it was used before + * the command name; `undefined` otherwise. + */ + configPath: string | undefined; + /** + * The given argv without the global `-c/--config ` options, so they are + * not seen (and not passed on) by the invoked command. + */ + argvWithoutGlobalConfigArgs: string[]; +} + +/** + * Extracts the global `-c/--config ` occurrences from `argv`. + * + * Only occurrences placed BEFORE the first positional argument (the command + * name) belong to the CLI itself. Afterwards, `-c` and `--config` are options + * of the invoked command — e.g. the Java generator defines its own + * `generate -c, --config ` — so the scan stops there and those + * arguments are returned untouched. + * + * Root options that take their own value are skipped together with the value + * (e.g. `--openapitools`, `--custom-generator`), so a value that looks like a + * positional argument is not mistaken for the command name. + */ +export function extractGlobalConfigArgs(argv: string[]): GlobalConfigArgs { + const args = argv.slice(2); // skip the node executable and the script path + const occurrences: Array<{ index: number; hasSeparateValue: boolean }> = []; + + let index = 0; + while (index < args.length) { + const arg = args[index]; + + if (arg === '--openapitools') { + // global option with a separate value, skip it and its value + index += 2; + continue; + } + if (arg.startsWith('--openapitools=')) { + index += 1; + continue; + } + if (arg === '--custom-generator') { + // root option with a separate value, skip it and its value + index += 2; + continue; + } + if (arg.startsWith('--custom-generator=')) { + index += 1; + continue; + } + if (arg === '-c' || arg === '--config') { + occurrences.push({ index, hasSeparateValue: true }); + index += 2; + continue; + } + if (arg.startsWith('--config=')) { + occurrences.push({ index, hasSeparateValue: false }); + index += 1; + continue; + } + if (arg.startsWith('-c') && arg.length > 2) { + // attached value, e.g. -cfoo.json + occurrences.push({ index, hasSeparateValue: false }); + index += 1; + continue; + } + + // the command name or an option of the invoked command: + // everything from here on belongs to the command + break; + } + + if (occurrences.length === 0) { + return { configPath: undefined, argvWithoutGlobalConfigArgs: argv }; + } + + const configArgs = new Set(); + let configPath: string | undefined; + for (const { index, hasSeparateValue } of occurrences) { + configArgs.add(index); + if (hasSeparateValue) { + if (args[index + 1] === undefined) { + throw new Error( + 'The -c/--config option requires a value (a path to an openapitools.json file)', + ); + } + configArgs.add(index + 1); + configPath = args[index + 1]; + } else if (args[index].startsWith('--config=')) { + configPath = args[index].slice('--config='.length); + } else { + configPath = args[index].slice(2); + } + } + + return { + configPath, + argvWithoutGlobalConfigArgs: [ + ...argv.slice(0, 2), + ...args.filter((_, i) => !configArgs.has(i)), + ], + }; +} + @Injectable() export class ConfigService { + /** + * Environment variable pointing to an openapitools.json outside of the cwd. + * Precedence: cli option (-c/--config or --openapitools) > env var > ./openapitools.json + */ + public static readonly envConfigVariable = 'OPENAPI_GENERATOR_CLI_CONFIG'; + public readonly cwd = process.env.PWD || process.env.INIT_CWD || process.cwd(); public readonly configFile = this.configFileOrDefault(); private configFileOrDefault() { this.program.parseOptions(process.argv); - const conf = this.program.opts().openapitools; - - if (!conf) { + const opts = this.program.opts(); + const globalConfigArgs = extractGlobalConfigArgs(process.argv); + const explicitConfigPath = + opts.openapitools || + globalConfigArgs.configPath || + process.env[ConfigService.envConfigVariable]; + + if (!explicitConfigPath) { return path.resolve(this.cwd, 'openapitools.json'); } - return path.isAbsolute(conf) ? conf : path.resolve(this.cwd, conf); + const configPath = path.isAbsolute(explicitConfigPath) + ? explicitConfigPath + : path.resolve(this.cwd, explicitConfigPath); + + if (!fs.existsSync(configPath)) { + this.logger.error( + `Config file not found at "${configPath}". It was set via ${ + opts.openapitools || globalConfigArgs.configPath + ? 'the -c/--config or --openapitools option' + : `the ${ConfigService.envConfigVariable} environment variable` + }. Please make sure the file exists, or unset it to use the default ./openapitools.json.`, + ); + process.exit(1); + } + + return configPath; } public get useDocker() {