chore(toolkit): cleanup public interfaces (#105)

Clean-up public interface and docs generation in preparation of the
release.

This mostly moves some previously public interfaces to be private,
renames interface and removes unused options.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: mrgrain

.projenrc.ts

@@ -1,11 +1,11 @@
 import { yarn, CdkCliIntegTestsWorkflow } from 'cdklabs-projen-project-types';
 import * as pj from 'projen';
 import { Stability } from 'projen/lib/cdk';
+import { AdcPublishing } from './projenrc/adc-publishing';
 import { BundleCli } from './projenrc/bundle';
+import { CodeCovWorkflow } from './projenrc/codecov';
 import { ESLINT_RULES } from './projenrc/eslint';
 import { JsiiBuild } from './projenrc/jsii';
-import { CodeCovWorkflow } from './projenrc/codecov';
-import { AdcPublishing } from './projenrc/adc-publishing';
 
 // 5.7 sometimes gives a weird error in `ts-jest` in `@aws-cdk/cli-lib-alpha`
 // https://github.com/microsoft/TypeScript/issues/60159
@@ -1148,13 +1148,16 @@ toolkitLib.postCompileTask.exec('node ./lib/api/aws-cdk.js >/dev/null 2>/dev/nul
 
 // Do include all .ts files inside init-templates
 toolkitLib.npmignore?.addPatterns(
+  'build-tools',
+  'docs',
+  'typedoc.json',
+  '*.d.ts.map',
   // Explicitly allow all required files
   '!build-info.json',
   '!db.json.gz',
   '!lib/api/bootstrap/bootstrap-template.yaml',
-  '*.d.ts',
-  '*.d.ts.map',
   '!lib/*.js',
+  '!lib/*.d.ts',
   '!LICENSE',
   '!NOTICE',
   '!THIRD_PARTY_LICENSES',
@@ -1179,7 +1182,7 @@ for (const tsconfig of [toolkitLib.tsconfigDev]) {
 }
 
 toolkitLib.addTask('docs', {
-  exec: 'typedoc lib/index.ts --excludeExternals --excludePrivate --excludeProtected --excludeInternal',
+  exec: 'typedoc lib/index.ts',
 });
 toolkitLib.addTask('publish-local', {
   exec: './build-tools/package.sh',

packages/@aws-cdk/toolkit-lib/.npmignore

@@ -1,5 +1,5 @@
-import { StackActivityProgress } from '../../api/aws-cdk';
-import type { StackSelector } from '../../api/cloud-assembly';
+import type { BaseDeployOptions } from './private/deploy-options';
+import type { StackActivityProgress, Tag } from '../../api/aws-cdk';
 
 export type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
 
@@ -48,14 +48,18 @@ export enum AssetBuildTime {
   JUST_IN_TIME = 'just-in-time',
 }
 
-export interface Tag {
-  readonly Key: string;
-  readonly Value: string;
-}
-
 export enum RequireApproval {
+  /**
+   * Never require any security approvals
+   */
   NEVER = 'never',
+  /**
+   * Any security changes require an approval
+   */
   ANY_CHANGE = 'any-change',
+  /**
+   * Require approval only for changes that are access broadening
+   */
   BROADENING = 'broadening',
 }
 
@@ -107,84 +111,18 @@ export class StackParameters {
   }
 }
 
-export interface BaseDeployOptions {
-  /**
-   * Criteria for selecting stacks to deploy
-   *
-   * @default - all stacks
-   */
-  readonly stacks?: StackSelector;
-
-  /**
-   * Role to pass to CloudFormation for deployment
-   */
-  readonly roleArn?: string;
-
-  /**
-   * @TODO can this be part of `DeploymentMethod`
-   *
-   * Always deploy, even if templates are identical.
-   *
-   * @default false
-   * @deprecated
-   */
-  readonly force?: boolean;
-
-  /**
-   * Deployment method
-   */
-  readonly deploymentMethod?: DeploymentMethod;
-
-  /**
-   * @TODO can this be part of `DeploymentMethod`
-   *
-   * Whether to perform a 'hotswap' deployment.
-   * A 'hotswap' deployment will attempt to short-circuit CloudFormation
-   * and update the affected resources like Lambda functions directly.
-   *
-   * @default - no hotswap
-   */
-  readonly hotswap?: HotswapMode;
-
-  /**
-   * Rollback failed deployments
-   *
-   * @default true
-   */
-  readonly rollback?: boolean;
-
-  /**
-   * Reuse the assets with the given asset IDs
-   */
-  readonly reuseAssets?: string[];
-
-  /**
-   * Maximum number of simultaneous deployments (dependency permitting) to execute.
-   * The default is '1', which executes all deployments serially.
-   *
-   * @default 1
-   */
-  readonly concurrency?: number;
-
-  /**
-   * Whether to send logs from all CloudWatch log groups in the template
-   * to the IoHost
-   *
-   * @default - false
-   */
-  readonly traceLogs?: boolean;
-}
-
 export interface DeployOptions extends BaseDeployOptions {
   /**
    * ARNs of SNS topics that CloudFormation will notify with stack related events
    */
   readonly notificationArns?: string[];
 
   /**
-   * What kind of security changes require approval
+   * Require a confirmation for security relevant changes before continuing with the deployment
    *
    * @default RequireApproval.NEVER
+   * @deprecated in future a message containing the full diff will be emitted and a response requested.
+   * Approval workflows should be implemented in the `IIoHost`.
    */
   readonly requireApproval?: RequireApproval;
 

packages/@aws-cdk/toolkit-lib/.projen/tasks.json

@@ -0,0 +1,89 @@
+import { DeploymentMethod, DeployOptions, HotswapMode } from '..';
+import type { CloudWatchLogEventMonitor } from '../../../api/aws-cdk';
+import type { StackSelector } from '../../../api/cloud-assembly';
+
+export interface BaseDeployOptions {
+  /**
+   * Criteria for selecting stacks to deploy
+   *
+   * @default - all stacks
+   */
+  readonly stacks?: StackSelector;
+
+  /**
+   * Role to pass to CloudFormation for deployment
+   */
+  readonly roleArn?: string;
+
+  /**
+   * Always deploy, even if templates are identical.
+   *
+   * @default false
+   * @deprecated the options currently covers multiple different functionalities and will be split out in future
+   */
+  readonly force?: boolean;
+
+  /**
+   * Deployment method
+   */
+  readonly deploymentMethod?: DeploymentMethod;
+
+  /**
+   * Whether to perform a 'hotswap' deployment.
+   * A 'hotswap' deployment will attempt to short-circuit CloudFormation
+   * and update the affected resources like Lambda functions directly.
+   *
+   * @default - no hotswap
+   */
+  readonly hotswap?: HotswapMode;
+
+  /**
+   * Rollback failed deployments
+   *
+   * @default true
+   */
+  readonly rollback?: boolean;
+
+  /**
+   * Reuse the assets with the given asset IDs
+   */
+  readonly reuseAssets?: string[];
+
+  /**
+   * Maximum number of simultaneous deployments (dependency permitting) to execute.
+   * The default is '1', which executes all deployments serially.
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
+
+  /**
+   * Whether to send logs from all CloudWatch log groups in the template
+   * to the IoHost
+   *
+   * @default - false
+   */
+  readonly traceLogs?: boolean;
+}
+
+/**
+ * Deploy options needed by the watch command.
+ * Intentionally not exported because these options are not
+ * meant to be public facing.
+ */
+export interface ExtendedDeployOptions extends DeployOptions {
+  /**
+   * The extra string to append to the User-Agent header when performing AWS SDK calls.
+   *
+   * @default - nothing extra is appended to the User-Agent header
+   */
+  readonly extraUserAgent?: string;
+
+  /**
+   * Allows adding CloudWatch log groups to the log monitor via
+   * cloudWatchLogMonitor.setLogGroups();
+   *
+   * @default - not monitoring CloudWatch logs
+   */
+  readonly cloudWatchLogMonitor?: CloudWatchLogEventMonitor;
+}

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/index.ts

@@ -1,26 +1,3 @@
-import { DeployOptions } from '..';
-import { CloudWatchLogEventMonitor } from '../../../api/aws-cdk';
-
+export * from './deploy-options';
 export * from './helpers';
 
-/**
- * Deploy options needed by the watch command.
- * Intentionally not exported because these options are not
- * meant to be public facing.
- */
-export interface ExtendedDeployOptions extends DeployOptions {
-  /**
-   * The extra string to append to the User-Agent header when performing AWS SDK calls.
-   *
-   * @default - nothing extra is appended to the User-Agent header
-   */
-  readonly extraUserAgent?: string;
-
-  /**
-   * Allows adding CloudWatch log groups to the log monitor via
-   * cloudWatchLogMonitor.setLogGroups();
-   *
-   * @default - not monitoring CloudWatch logs
-   */
-  readonly cloudWatchLogMonitor?: CloudWatchLogEventMonitor;
-}

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/private/deploy-options.ts

@@ -1,4 +1,4 @@
-import type { BaseDeployOptions } from '../deploy';
+import type { BaseDeployOptions } from '../deploy/private';
 
 export interface ImportOptions extends Omit<BaseDeployOptions, 'reuseAssets' | 'hotswap'> {
   /**

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/private/index.ts

@@ -1,7 +1,6 @@
 export * from './deploy';
 export * from './destroy';
-export * from './diff';
-export * from './import';
 export * from './list';
+export * from './rollback';
 export * from './synth';
 export * from './watch';

packages/@aws-cdk/toolkit-lib/lib/actions/import/index.ts

@@ -1,4 +1,4 @@
-import type { BaseDeployOptions, HotswapMode } from '../deploy';
+import type { BaseDeployOptions } from '../deploy/private';
 
 export interface WatchOptions extends BaseDeployOptions {
   /**
@@ -37,23 +37,4 @@ export interface WatchOptions extends BaseDeployOptions {
    * @default 'cdk.out'
    */
   readonly outdir?: string;
-
-  /**
-   * @TODO can this be part of `DeploymentMethod`
-   *
-   * Whether to perform a 'hotswap' deployment.
-   * A 'hotswap' deployment will attempt to short-circuit CloudFormation
-   * and update the affected resources like Lambda functions directly.
-   *
-   * @default HotswapMode.HOTSWAP_ONLY
-   */
-  readonly hotswap?: HotswapMode;
-}
-
-export function patternsArrayForWatch(
-  patterns: string | string[] | undefined,
-  options: { rootDir: string; returnRootDirIfEmpty: boolean },
-): string[] {
-  const patternsArray: string[] = patterns !== undefined ? (Array.isArray(patterns) ? patterns : [patterns]) : [];
-  return patternsArray.length > 0 ? patternsArray : options.returnRootDirIfEmpty ? [options.rootDir] : [];
 }

packages/@aws-cdk/toolkit-lib/lib/actions/index.ts

@@ -0,0 +1,7 @@
+export function patternsArrayForWatch(
+  patterns: string | string[] | undefined,
+  options: { rootDir: string; returnRootDirIfEmpty: boolean },
+): string[] {
+  const patternsArray: string[] = patterns !== undefined ? (Array.isArray(patterns) ? patterns : [patterns]) : [];
+  return patternsArray.length > 0 ? patternsArray : options.returnRootDirIfEmpty ? [options.rootDir] : [];
+}