Merge pull request #10617 from backstage/freben/bump-commander

Bump commander to version 9.1.0

packages/techdocs-cli/package.json

@@ -68,7 +68,7 @@
     "@backstage/config": "^1.0.0",
     "@backstage/plugin-techdocs-node": "^1.1.0",
     "@types/dockerode": "^3.3.0",
-    "commander": "^6.1.0",
+    "commander": "^9.1.0",
     "dockerode": "^3.3.1",
     "fs-extra": "^10.0.1",
     "http-proxy": "^1.18.1",

packages/techdocs-cli/src/commands/generate/generate.ts

@@ -15,7 +15,7 @@
  */
 
 import { resolve } from 'path';
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 import fs from 'fs-extra';
 import Docker from 'dockerode';
 import {
@@ -30,19 +30,19 @@ import {
 } from '../../lib/utility';
 import { stdout } from 'process';
 
-export default async function generate(cmd: Command) {
+export default async function generate(opts: OptionValues) {
   // Use techdocs-node package to generate docs. Keep consistency between Backstage and CI generating docs.
   // Docs can be prepared using actions/checkout or git clone, or similar paradigms on CI. The TechDocs CI workflow
   // will run on the CI pipeline containing the documentation files.
 
-  const logger = createLogger({ verbose: cmd.verbose });
+  const logger = createLogger({ verbose: opts.verbose });
 
-  const sourceDir = resolve(cmd.sourceDir);
-  const outputDir = resolve(cmd.outputDir);
-  const omitTechdocsCorePlugin = cmd.omitTechdocsCoreMkdocsPlugin;
-  const dockerImage = cmd.dockerImage;
-  const pullImage = cmd.pull;
-  const legacyCopyReadmeMdToIndexMd = cmd.legacyCopyReadmeMdToIndexMd;
+  const sourceDir = resolve(opts.sourceDir);
+  const outputDir = resolve(opts.outputDir);
+  const omitTechdocsCorePlugin = opts.omitTechdocsCoreMkdocsPlugin;
+  const dockerImage = opts.dockerImage;
+  const pullImage = opts.pull;
+  const legacyCopyReadmeMdToIndexMd = opts.legacyCopyReadmeMdToIndexMd;
 
   logger.info(`Using source dir ${sourceDir}`);
   logger.info(`Will output generated files in ${outputDir}`);
@@ -54,7 +54,7 @@ export default async function generate(cmd: Command) {
   const config = new ConfigReader({
     techdocs: {
       generator: {
-        runIn: cmd.docker ? 'docker' : 'local',
+        runIn: opts.docker ? 'docker' : 'local',
         dockerImage,
         pullImage,
         legacyCopyReadmeMdToIndexMd,
@@ -70,10 +70,10 @@ export default async function generate(cmd: Command) {
   const containerRunner = new DockerContainerRunner({ dockerClient });
 
   let parsedLocationAnnotation = {} as ParsedLocationAnnotation;
-  if (cmd.techdocsRef) {
+  if (opts.techdocsRef) {
     try {
       parsedLocationAnnotation = convertTechDocsRefToLocationAnnotation(
-        cmd.techdocsRef,
+        opts.techdocsRef,
       );
     } catch (err) {
       logger.error(err.message);
@@ -91,13 +91,13 @@ export default async function generate(cmd: Command) {
   await techdocsGenerator.run({
     inputDir: sourceDir,
     outputDir,
-    ...(cmd.techdocsRef
+    ...(opts.techdocsRef
       ? {
           parsedLocationAnnotation,
         }
       : {}),
     logger,
-    etag: cmd.etag,
+    etag: opts.etag,
     ...(process.env.LOG_LEVEL === 'debug' ? { logStream: stdout } : {}),
   });
 

packages/techdocs-cli/src/commands/index.ts

@@ -14,12 +14,12 @@
  * limitations under the License.
  */
 
-import { CommanderStatic } from 'commander';
+import { Command } from 'commander';
 import { TechdocsGenerator } from '@backstage/plugin-techdocs-node';
 
 const defaultDockerImage = TechdocsGenerator.defaultDockerImage;
 
-export function registerCommands(program: CommanderStatic) {
+export function registerCommands(program: Command) {
   program
     .command('generate')
     .description('Generate TechDocs documentation site using MkDocs.')

packages/techdocs-cli/src/commands/migrate/migrate.ts

@@ -16,19 +16,19 @@
 
 import { SingleHostDiscovery } from '@backstage/backend-common';
 import { Publisher } from '@backstage/plugin-techdocs-node';
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 import { createLogger } from '../../lib/utility';
 import { PublisherConfig } from '../../lib/PublisherConfig';
 
-export default async function migrate(cmd: Command) {
-  const logger = createLogger({ verbose: cmd.verbose });
+export default async function migrate(opts: OptionValues) {
+  const logger = createLogger({ verbose: opts.verbose });
 
-  const config = PublisherConfig.getValidConfig(cmd);
+  const config = PublisherConfig.getValidConfig(opts);
   const discovery = SingleHostDiscovery.fromConfig(config);
   const publisher = await Publisher.fromConfig(config, { logger, discovery });
 
   if (!publisher.migrateDocsCase) {
-    throw new Error(`Migration not implemented for ${cmd.publisherType}`);
+    throw new Error(`Migration not implemented for ${opts.publisherType}`);
   }
 
   // Check that the publisher's underlying storage is ready and available.
@@ -39,12 +39,12 @@ export default async function migrate(cmd: Command) {
   }
 
   // Validate and parse migration arguments.
-  const removeOriginal = cmd.removeOriginal;
-  const numericConcurrency = parseInt(cmd.concurrency, 10);
+  const removeOriginal = opts.removeOriginal;
+  const numericConcurrency = parseInt(opts.concurrency, 10);
 
   if (!Number.isInteger(numericConcurrency) || numericConcurrency <= 0) {
     throw new Error(
-      `Concurrency must be a number greater than 1. ${cmd.concurrency} provided.`,
+      `Concurrency must be a number greater than 1. ${opts.concurrency} provided.`,
     );
   }
 

packages/techdocs-cli/src/commands/publish/publish.ts

@@ -15,17 +15,17 @@
  */
 
 import { resolve } from 'path';
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 import { createLogger } from '../../lib/utility';
 import { SingleHostDiscovery } from '@backstage/backend-common';
 import { Publisher } from '@backstage/plugin-techdocs-node';
 import { Entity } from '@backstage/catalog-model';
 import { PublisherConfig } from '../../lib/PublisherConfig';
 
-export default async function publish(cmd: Command): Promise<any> {
-  const logger = createLogger({ verbose: cmd.verbose });
+export default async function publish(opts: OptionValues): Promise<any> {
+  const logger = createLogger({ verbose: opts.verbose });
 
-  const config = PublisherConfig.getValidConfig(cmd);
+  const config = PublisherConfig.getValidConfig(opts);
   const discovery = SingleHostDiscovery.fromConfig(config);
   const publisher = await Publisher.fromConfig(config, { logger, discovery });
 
@@ -36,7 +36,7 @@ export default async function publish(cmd: Command): Promise<any> {
     return Promise.reject(new Error(''));
   }
 
-  const [namespace, kind, name] = cmd.entity.split('/');
+  const [namespace, kind, name] = opts.entity.split('/');
   const entity = {
     kind,
     metadata: {
@@ -45,7 +45,7 @@ export default async function publish(cmd: Command): Promise<any> {
     },
   } as Entity;
 
-  const directory = resolve(cmd.directory);
+  const directory = resolve(opts.directory);
   await publisher.publish({ entity, directory });
 
   return true;

packages/techdocs-cli/src/commands/serve/mkdocs.ts

@@ -14,25 +14,25 @@
  * limitations under the License.
  */
 
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 import openBrowser from 'react-dev-utils/openBrowser';
 import { createLogger } from '../../lib/utility';
 import { runMkdocsServer } from '../../lib/mkdocsServer';
 import { LogFunc, waitForSignal } from '../../lib/run';
 
-export default async function serveMkdocs(cmd: Command) {
-  const logger = createLogger({ verbose: cmd.verbose });
+export default async function serveMkdocs(opts: OptionValues) {
+  const logger = createLogger({ verbose: opts.verbose });
 
-  const dockerAddr = `http://0.0.0.0:${cmd.port}`;
-  const localAddr = `http://127.0.0.1:${cmd.port}`;
-  const expectedDevAddr = cmd.docker ? dockerAddr : localAddr;
+  const dockerAddr = `http://0.0.0.0:${opts.port}`;
+  const localAddr = `http://127.0.0.1:${opts.port}`;
+  const expectedDevAddr = opts.docker ? dockerAddr : localAddr;
   // We want to open browser only once based on a log.
   let boolOpenBrowserTriggered = false;
 
   const logFunc: LogFunc = data => {
     // Sometimes the lines contain an unnecessary extra new line in between
     const logLines = data.toString().split('\n');
-    const logPrefix = cmd.docker ? '[docker/mkdocs]' : '[mkdocs]';
+    const logPrefix = opts.docker ? '[docker/mkdocs]' : '[mkdocs]';
     logLines.forEach(line => {
       if (line === '') {
         return;
@@ -59,10 +59,10 @@ export default async function serveMkdocs(cmd: Command) {
 
   // Commander stores --no-docker in cmd.docker variable
   const childProcess = await runMkdocsServer({
-    port: cmd.port,
-    dockerImage: cmd.dockerImage,
-    dockerEntrypoint: cmd.dockerEntrypoint,
-    useDocker: cmd.docker,
+    port: opts.port,
+    dockerImage: opts.dockerImage,
+    dockerEntrypoint: opts.dockerEntrypoint,
+    useDocker: opts.docker,
     stdoutLogFunc: logFunc,
     stderrLogFunc: logFunc,
   });

packages/techdocs-cli/src/commands/serve/serve.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 import path from 'path';
 import openBrowser from 'react-dev-utils/openBrowser';
 import { findPaths } from '@backstage/cli-common';
@@ -42,8 +42,8 @@ function findPreviewBundlePath(): string {
   }
 }
 
-export default async function serve(cmd: Command) {
-  const logger = createLogger({ verbose: cmd.verbose });
+export default async function serve(opts: OptionValues) {
+  const logger = createLogger({ verbose: opts.verbose });
 
   // Determine if we want to run in local dev mode or not
   // This will run the backstage http server on a different port and only used
@@ -58,15 +58,17 @@ export default async function serve(cmd: Command) {
   const backstagePort = 3000;
   const backstageBackendPort = 7007;
 
-  const mkdocsDockerAddr = `http://0.0.0.0:${cmd.mkdocsPort}`;
-  const mkdocsLocalAddr = `http://127.0.0.1:${cmd.mkdocsPort}`;
-  const mkdocsExpectedDevAddr = cmd.docker ? mkdocsDockerAddr : mkdocsLocalAddr;
+  const mkdocsDockerAddr = `http://0.0.0.0:${opts.mkdocsPort}`;
+  const mkdocsLocalAddr = `http://127.0.0.1:${opts.mkdocsPort}`;
+  const mkdocsExpectedDevAddr = opts.docker
+    ? mkdocsDockerAddr
+    : mkdocsLocalAddr;
 
   let mkdocsServerHasStarted = false;
   const mkdocsLogFunc: LogFunc = data => {
     // Sometimes the lines contain an unnecessary extra new line
     const logLines = data.toString().split('\n');
-    const logPrefix = cmd.docker ? '[docker/mkdocs]' : '[mkdocs]';
+    const logPrefix = opts.docker ? '[docker/mkdocs]' : '[mkdocs]';
     logLines.forEach(line => {
       if (line === '') {
         return;
@@ -88,10 +90,10 @@ export default async function serve(cmd: Command) {
   // Had me questioning this whole implementation for half an hour.
   logger.info('Starting mkdocs server.');
   const mkdocsChildProcess = await runMkdocsServer({
-    port: cmd.mkdocsPort,
-    dockerImage: cmd.dockerImage,
-    dockerEntrypoint: cmd.dockerEntrypoint,
-    useDocker: cmd.docker,
+    port: opts.mkdocsPort,
+    dockerImage: opts.dockerImage,
+    dockerEntrypoint: opts.dockerEntrypoint,
+    useDocker: opts.docker,
     stdoutLogFunc: mkdocsLogFunc,
     stderrLogFunc: mkdocsLogFunc,
   });
@@ -116,8 +118,8 @@ export default async function serve(cmd: Command) {
   const httpServer = new HTTPServer(
     findPreviewBundlePath(),
     port,
-    cmd.mkdocsPort,
-    cmd.verbose,
+    opts.mkdocsPort,
+    opts.verbose,
   );
 
   httpServer

packages/techdocs-cli/src/index.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import program from 'commander';
+import { program } from 'commander';
 import { registerCommands } from './commands';
 import { version } from '../package.json';
 

packages/techdocs-cli/src/lib/PublisherConfig.test.ts

@@ -14,14 +14,14 @@
  * limitations under the License.
  */
 
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 import { PublisherConfig } from './PublisherConfig';
 
 describe('getValidPublisherConfig', () => {
   it('should not allow unknown publisher types', () => {
     const invalidConfig = {
       publisherType: 'unknown publisher',
-    } as unknown as Command;
+    } as unknown as OptionValues;
 
     expect(() => PublisherConfig.getValidConfig(invalidConfig)).toThrowError(
       `Unknown publisher type ${invalidConfig.publisherType}`,
@@ -32,7 +32,7 @@ describe('getValidPublisherConfig', () => {
     it('should require --azureAccountName', () => {
       const config = {
         publisherType: 'azureBlobStorage',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       expect(() => PublisherConfig.getValidConfig(config)).toThrowError(
         'azureBlobStorage requires --azureAccountName to be specified',
@@ -44,7 +44,7 @@ describe('getValidPublisherConfig', () => {
         publisherType: 'azureBlobStorage',
         azureAccountName: 'someAccountName',
         storageName: 'someContainer',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       const actualConfig = PublisherConfig.getValidConfig(config);
       expect(actualConfig.getString('techdocs.publisher.type')).toBe(
@@ -69,7 +69,7 @@ describe('getValidPublisherConfig', () => {
         publisherType: 'awsS3',
         storageName: 'someStorageName',
         awsBucketRootPath: 'backstage-data/techdocs',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       const actualConfig = PublisherConfig.getValidConfig(config);
       expect(actualConfig.getString('techdocs.publisher.type')).toBe('awsS3');
@@ -86,7 +86,7 @@ describe('getValidPublisherConfig', () => {
         publisherType: 'awsS3',
         storageName: 'someStorageName',
         awsS3sse: 'aws:kms',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       const actualConfig = PublisherConfig.getValidConfig(config);
       expect(actualConfig.getString('techdocs.publisher.type')).toBe('awsS3');
@@ -102,7 +102,7 @@ describe('getValidPublisherConfig', () => {
         publisherType: 'openStackSwift',
         osCredentialId: 'someCredentialId',
         osSecret: 'someSecret',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       expect(() => PublisherConfig.getValidConfig(config)).toThrowError(
         `openStackSwift requires the following params to be specified: ${[
@@ -120,7 +120,7 @@ describe('getValidPublisherConfig', () => {
         osSecret: 'someSecret',
         osAuthUrl: 'someAuthUrl',
         osSwiftUrl: 'someSwiftUrl',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       const actualConfig = PublisherConfig.getValidConfig(config);
       expect(actualConfig.getString('techdocs.publisher.type')).toBe(
@@ -146,7 +146,7 @@ describe('getValidPublisherConfig', () => {
         publisherType: 'googleGcs',
         storageName: 'someStorageName',
         gcsBucketRootPath: 'backstage-data/techdocs',
-      } as unknown as Command;
+      } as unknown as OptionValues;
 
       const actualConfig = PublisherConfig.getValidConfig(config);
       expect(actualConfig.getString('techdocs.publisher.type')).toBe(

packages/techdocs-cli/src/lib/PublisherConfig.ts

@@ -15,7 +15,7 @@
  */
 
 import { ConfigReader } from '@backstage/config';
-import { Command } from 'commander';
+import { OptionValues } from 'commander';
 
 type Publisher = keyof typeof PublisherConfig['configFactories'];
 type PublisherConfiguration = {
@@ -45,11 +45,11 @@ export class PublisherConfig {
    * Note: This assumes that proper credentials are set in Environment
    * variables for the respective GCS/AWS clients to work.
    */
-  static getValidConfig(cmd: Command): ConfigReader {
-    const publisherType = cmd.publisherType;
+  static getValidConfig(opts: OptionValues): ConfigReader {
+    const publisherType = opts.publisherType;
 
     if (!PublisherConfig.isKnownPublisher(publisherType)) {
-      throw new Error(`Unknown publisher type ${cmd.publisherType}`);
+      throw new Error(`Unknown publisher type ${opts.publisherType}`);
     }
 
     return new ConfigReader({
@@ -61,9 +61,9 @@ export class PublisherConfig {
         },
       },
       techdocs: {
-        publisher: PublisherConfig.configFactories[publisherType](cmd),
+        publisher: PublisherConfig.configFactories[publisherType](opts),
         legacyUseCaseSensitiveTripletPaths:
-          cmd.legacyUseCaseSensitiveTripletPaths,
+          opts.legacyUseCaseSensitiveTripletPaths,
       },
     });
   }
@@ -80,16 +80,20 @@ export class PublisherConfig {
   /**
    * Retrieve valid AWS S3 configuration based on the command.
    */
-  private static getValidAwsS3Config(cmd: Command): PublisherConfiguration {
+  private static getValidAwsS3Config(
+    opts: OptionValues,
+  ): PublisherConfiguration {
     return {
       type: 'awsS3',
       awsS3: {
-        bucketName: cmd.storageName,
-        ...(cmd.awsBucketRootPath && { bucketRootPath: cmd.awsBucketRootPath }),
-        ...(cmd.awsRoleArn && { credentials: { roleArn: cmd.awsRoleArn } }),
-        ...(cmd.awsEndpoint && { endpoint: cmd.awsEndpoint }),
-        ...(cmd.awsS3ForcePathStyle && { s3ForcePathStyle: true }),
-        ...(cmd.awsS3sse && { sse: cmd.awsS3sse }),
+        bucketName: opts.storageName,
+        ...(opts.awsBucketRootPath && {
+          bucketRootPath: opts.awsBucketRootPath,
+        }),
+        ...(opts.awsRoleArn && { credentials: { roleArn: opts.awsRoleArn } }),
+        ...(opts.awsEndpoint && { endpoint: opts.awsEndpoint }),
+        ...(opts.awsS3ForcePathStyle && { s3ForcePathStyle: true }),
+        ...(opts.awsS3sse && { sse: opts.awsS3sse }),
       },
     };
   }
@@ -97,8 +101,10 @@ export class PublisherConfig {
   /**
    * Retrieve valid Azure Blob Storage configuration based on the command.
    */
-  private static getValidAzureConfig(cmd: Command): PublisherConfiguration {
-    if (!cmd.azureAccountName) {
+  private static getValidAzureConfig(
+    opts: OptionValues,
+  ): PublisherConfiguration {
+    if (!opts.azureAccountName) {
       throw new Error(
         `azureBlobStorage requires --azureAccountName to be specified`,
       );
@@ -107,10 +113,10 @@ export class PublisherConfig {
     return {
       type: 'azureBlobStorage',
       azureBlobStorage: {
-        containerName: cmd.storageName,
+        containerName: opts.storageName,
         credentials: {
-          accountName: cmd.azureAccountName,
-          accountKey: cmd.azureAccountKey,
+          accountName: opts.azureAccountName,
+          accountKey: opts.azureAccountKey,
         },
       },
     };
@@ -119,12 +125,16 @@ export class PublisherConfig {
   /**
    * Retrieve valid GCS configuration based on the command.
    */
-  private static getValidGoogleGcsConfig(cmd: Command): PublisherConfiguration {
+  private static getValidGoogleGcsConfig(
+    opts: OptionValues,
+  ): PublisherConfiguration {
     return {
       type: 'googleGcs',
       googleGcs: {
-        bucketName: cmd.storageName,
-        ...(cmd.gcsBucketRootPath && { bucketRootPath: cmd.gcsBucketRootPath }),
+        bucketName: opts.storageName,
+        ...(opts.gcsBucketRootPath && {
+          bucketRootPath: opts.gcsBucketRootPath,
+        }),
       },
     };
   }
@@ -133,14 +143,14 @@ export class PublisherConfig {
    * Retrieves valid OpenStack Swift configuration based on the command.
    */
   private static getValidOpenStackSwiftConfig(
-    cmd: Command,
+    opts: OptionValues,
   ): PublisherConfiguration {
     const missingParams = [
       'osCredentialId',
       'osSecret',
       'osAuthUrl',
       'osSwiftUrl',
-    ].filter((param: string) => !cmd[param]);
+    ].filter((param: string) => !opts[param]);
 
     if (missingParams.length) {
       throw new Error(
@@ -153,13 +163,13 @@ export class PublisherConfig {
     return {
       type: 'openStackSwift',
       openStackSwift: {
-        containerName: cmd.storageName,
+        containerName: opts.storageName,
         credentials: {
-          id: cmd.osCredentialId,
-          secret: cmd.osSecret,
+          id: opts.osCredentialId,
+          secret: opts.osSecret,
         },
-        authUrl: cmd.osAuthUrl,
-        swiftUrl: cmd.osSwiftUrl,
+        authUrl: opts.osAuthUrl,
+        swiftUrl: opts.osSwiftUrl,
       },
     };
   }