fix(codebuild): API cleanup. (#2745)

Change the names of the source classes to be more consistent with other integrations. Make the abstract Source classes package-private. Add static factory methods to Source.

Change the names of artifacts classes to be more consistent with other integrations. Add static factory methods to Artifacts.

Make CodePipelineSource, CodePipelineArtifacts, NoSource, and NoArtifacts package-private.

Get rid of the SourceType enum.

BREAKING CHANGE:
* codebuild: rename BuildSource to Source, S3BucketSource to S3Source, BuildArtifacts to Artifacts, S3BucketBuildArtifacts to S3Artifacts
* codebuild: the classes CodePipelineBuildSource, CodePipelineBuildArtifacts, NoBuildSource, and NoBuildArtifacts have been removed
* codebuild: rename buildScriptAsset and buildScriptAssetEntrypoint to buildScript and buildScriptEntrypoint, respectively

Author: skinny85

packages/@aws-cdk/aws-codebuild/README.md

@@ -42,15 +42,10 @@ methods and attributes.
 ## Source
 
 Build projects are usually associated with a _source_, which is specified via
-the `source` property which accepts a class that extends the `BuildSource`
-abstract base class. The supported sources are:
-
-### `NoSource`
-
-This is the default and implies that no source is associated with this
-build project.
-
-The `buildSpec` option is required in this case.
+the `source` property which accepts a class that extends the `Source`
+abstract base class.
+The default is to have no source associated with the build project;
+the `buildSpec` option is required in that case.
 
 Here's a CodeBuild project with no source which simply prints `Hello,
 CodeBuild!`:
@@ -67,11 +62,11 @@ import codecommit = require('@aws-cdk/aws-codecommit');
 
 const repository = new codecommit.Repository(this, 'MyRepo', { repositoryName: 'foo' });
 new codebuild.Project(this, 'MyFirstCodeCommitProject', {
-  source: new codebuild.CodeCommitSource({ repository }),
+  source: codebuild.Source.codeCommit({ repository }),
 });
 ```
 
-### `S3BucketSource`
+### `S3Source`
 
 Create a CodeBuild project with an S3 bucket as the source:
 
@@ -81,25 +76,20 @@ import s3 = require('@aws-cdk/aws-s3');
 
 const bucket = new s3.Bucket(this, 'MyBucket');
 new codebuild.Project(this, 'MyProject', {
-  source: new codebuild.S3BucketSource({
+  source: codebuild.Source.s3({
     bucket: bucket,
     path: 'path/to/file.zip',
   }),
 });
 ```
 
-### `CodePipelineSource`
-
-Used as a special source type when a CodeBuild project is used as a
-CodePipeline action.
-
 ### `GitHubSource` and `GitHubEnterpriseSource`
 
 These source types can be used to build code from a GitHub repository.
 Example:
 
 ```typescript
-const gitHubSource = new codebuild.GitHubSource({
+const gitHubSource = codebuild.Source.gitHub({
   owner: 'awslabs',
   repo: 'aws-cdk',
   webhook: true, // optional, default: true if `webhookFilteres` were provided, false otherwise
@@ -121,6 +111,23 @@ aws codebuild import-source-credentials --server-type GITHUB --auth-type PERSONA
 
 This source type can be used to build code from a BitBucket repository.
 
+## CodePipeline
+
+To add a CodeBuild Project as an Action to CodePipeline,
+use the `PipelineProject` class instead of `Project`.
+It's a simple class that doesn't allow you to specify `sources`,
+`secondarySources`, `artifacts` or `secondaryArtifacts`,
+as these are handled by setting input and output CodePipeline `Artifact` instances on the Action,
+instead of setting them on the Project.
+
+```typescript
+const project = new codebuild.PipelineProject(this, 'Project', {
+  // properties as above...
+})
+```
+
+For more details, see the readme of the `@aws-cdk/@aws-codepipeline` package.
+
 ## Caching
 
 You can save time when your project builds by using a cache. A cache can store reusable pieces of your build environment and use them across multiple builds. Your build project can use one of two types of caching: Amazon S3 or local. In general, S3 caching is a good option for small and intermediate build artifacts that are more expensive to build than to download. Local caching is a good option for large intermediate build artifacts because the cache is immediately available on the build host.
@@ -225,13 +232,13 @@ multiple outputs. For example:
 ```ts
 const project = new codebuild.Project(this, 'MyProject', {
   secondarySources: [
-    new codebuild.CodeCommitSource({
+    codebuild.Source.codeCommit({
       identifier: 'source2',
       repository: repo,
     }),
   ],
   secondaryArtifacts: [
-    new codebuild.S3BucketBuildArtifacts({
+    codebuild.Artifacts.s3({
       identifier: 'artifact2',
       bucket: bucket,
       path: 'some/path',
@@ -324,7 +331,7 @@ const securityGroup = new ec2.SecurityGroup(stack, 'SecurityGroup1', {
     vpc: vpc,
 });
 new Project(stack, 'MyProject', {
-    buildScriptAsset: new assets.ZipDirectoryAsset(stack, 'Bundle', { path: 'script_bundle' }),
+    buildScript: new assets.ZipDirectoryAsset(stack, 'Bundle', { path: 'script_bundle' }),
     securityGroups: [securityGroup],
     vpc: vpc
 });

packages/@aws-cdk/aws-codebuild/lib/artifacts.ts

@@ -1,84 +1,83 @@
 import s3 = require('@aws-cdk/aws-s3');
+import { Construct } from '@aws-cdk/cdk';
 import { CfnProject } from './codebuild.generated';
-import { Project } from './project';
+import { IProject } from './project';
 
 /**
- * Properties common to all Artifacts classes.
+ * The type returned from {@link IArtifacts#bind}.
  */
-export interface BuildArtifactsProps {
+export interface ArtifactsConfig {
   /**
-   * The artifact identifier.
-   * This property is required on secondary artifacts.
+   * The low-level CloudFormation artifacts property.
    */
-  readonly identifier?: string;
+  readonly artifactsProperty: CfnProject.ArtifactsProperty;
 }
 
 /**
- * Artifacts definition for a CodeBuild Project.
+ * The abstract interface of a CodeBuild build output.
+ * Implemented by {@link Artifacts}.
  */
-export abstract class BuildArtifacts {
-  public readonly identifier?: string;
-  protected abstract readonly type: string;
-
-  constructor(props: BuildArtifactsProps) {
-    this.identifier = props.identifier;
-  }
-
+export interface IArtifacts {
   /**
-   * @internal
+   * The artifact identifier.
+   * This property is required on secondary artifacts.
    */
-  public _bind(_project: Project) {
-    return;
-  }
+  readonly identifier?: string;
 
-  public toArtifactsJSON(): CfnProject.ArtifactsProperty {
-    const artifactsProp = this.toArtifactsProperty();
-    return {
-      artifactIdentifier: this.identifier,
-      type: this.type,
-      ...artifactsProp,
-    };
-  }
+  /**
+   * The CodeBuild type of this artifact.
+   */
+  readonly type: string;
 
-  protected toArtifactsProperty(): any {
-    return {
-    };
-  }
+  /**
+   * Callback when an Artifacts class is used in a CodeBuild Project.
+   *
+   * @param scope a root Construct that allows creating new Constructs
+   * @param project the Project this Artifacts is used in
+   */
+  bind(scope: Construct, project: IProject): ArtifactsConfig;
 }
 
 /**
- * A `NO_ARTIFACTS` CodeBuild Project Artifact definition.
- * This is the default artifact type,
- * if none was specified when creating the Project
- * (and the source was not specified to be CodePipeline).
- * *Note*: the `NO_ARTIFACTS` type cannot be used as a secondary artifact,
- * and because of that, you're not allowed to specify an identifier for it.
+ * Properties common to all Artifacts classes.
  */
-export class NoBuildArtifacts  extends BuildArtifacts {
-  protected readonly type = 'NO_ARTIFACTS';
-
-  constructor() {
-    super({});
-  }
+export interface ArtifactsProps {
+  /**
+   * The artifact identifier.
+   * This property is required on secondary artifacts.
+   */
+  readonly identifier?: string;
 }
 
 /**
- * CodePipeline Artifact definition for a CodeBuild Project.
- * *Note*: this type cannot be used as a secondary artifact,
- * and because of that, you're not allowed to specify an identifier for it.
+ * Artifacts definition for a CodeBuild Project.
  */
-export class CodePipelineBuildArtifacts extends BuildArtifacts {
-  protected readonly type = 'CODEPIPELINE';
+export abstract class Artifacts implements IArtifacts {
+  public static s3(props: S3ArtifactsProps): Artifacts {
+    return new S3Artifacts(props);
+  }
 
-  constructor() {
-    super({});
+  public readonly identifier?: string;
+  public abstract readonly type: string;
+
+  protected constructor(props: ArtifactsProps) {
+    this.identifier = props.identifier;
+  }
+
+  public bind(_scope: Construct, _project: IProject): ArtifactsConfig {
+    return {
+      artifactsProperty: {
+        artifactIdentifier: this.identifier,
+        type: this.type,
+      },
+    };
   }
 }
 
 /**
- * Construction properties for {@link S3BucketBuildArtifacts}.
+ * Construction properties for {@link S3Artifacts}.
  */
-export interface S3BucketBuildArtifactsProps extends BuildArtifactsProps {
+export interface S3ArtifactsProps extends ArtifactsProps {
   /**
    * The name of the output bucket.
    */
@@ -119,27 +118,25 @@ export interface S3BucketBuildArtifactsProps extends BuildArtifactsProps {
 /**
  * S3 Artifact definition for a CodeBuild Project.
  */
-export class S3BucketBuildArtifacts extends BuildArtifacts {
-  protected readonly type = 'S3';
+class S3Artifacts extends Artifacts {
+  public readonly type = 'S3';
 
-  constructor(private readonly props: S3BucketBuildArtifactsProps) {
+  constructor(private readonly props: S3ArtifactsProps) {
     super(props);
   }
 
-  /**
-   * @internal
-   */
-  public _bind(project: Project) {
+  public bind(_scope: Construct, project: IProject): ArtifactsConfig {
     this.props.bucket.grantReadWrite(project);
-  }
-
-  protected toArtifactsProperty(): any {
+    const superConfig = super.bind(_scope, project);
     return {
-      location: this.props.bucket.bucketName,
-      path: this.props.path,
-      namespaceType: this.props.includeBuildId === false ? 'NONE' : 'BUILD_ID',
-      name: this.props.name,
-      packaging: this.props.packageZip === false ? 'NONE' : 'ZIP',
+      artifactsProperty: {
+        ...superConfig.artifactsProperty,
+        location: this.props.bucket.bucketName,
+        path: this.props.path,
+        namespaceType: this.props.includeBuildId === false ? 'NONE' : 'BUILD_ID',
+        name: this.props.name,
+        packaging: this.props.packageZip === false ? 'NONE' : 'ZIP',
+      }
     };
   }
 }

packages/@aws-cdk/aws-codebuild/lib/codepipeline-artifacts.ts

@@ -0,0 +1,14 @@
+import { Artifacts } from './artifacts';
+
+/**
+ * CodePipeline Artifact definition for a CodeBuild Project.
+ * *Note*: this type cannot be used as a secondary artifact,
+ * and because of that, you're not allowed to specify an identifier for it.
+ */
+export class CodePipelineArtifacts extends Artifacts {
+  public readonly type = 'CODEPIPELINE';
+
+  constructor() {
+    super({});
+  }
+}

packages/@aws-cdk/aws-codebuild/lib/codepipeline-source.ts

@@ -0,0 +1,15 @@
+import { Source } from './source';
+import { CODEPIPELINE_SOURCE_ARTIFACTS_TYPE } from './source-types';
+
+/**
+ * CodePipeline Source definition for a CodeBuild Project.
+ * *Note*: this type cannot be used as a secondary source,
+ * and because of that, you're not allowed to specify an identifier for it.
+ */
+export class CodePipelineSource extends Source {
+  public readonly type = CODEPIPELINE_SOURCE_ARTIFACTS_TYPE;
+
+  constructor() {
+    super({});
+  }
+}

packages/@aws-cdk/aws-codebuild/lib/no-artifacts.ts

@@ -0,0 +1,19 @@
+import { Artifacts } from './artifacts';
+
+/**
+ * A `NO_ARTIFACTS` CodeBuild Project Artifact definition.
+ * This is the default artifact type,
+ * if none was specified when creating the Project
+ * (and the source was not specified to be CodePipeline).
+ * *Note*: the `NO_ARTIFACTS` type cannot be used as a secondary artifact,
+ * and because of that, you're not allowed to specify an identifier for it.
+ *
+ * This class is private to the @aws-codebuild package.
+ */
+export class NoArtifacts extends Artifacts {
+  public readonly type = 'NO_ARTIFACTS';
+
+  constructor() {
+    super({});
+  }
+}

packages/@aws-cdk/aws-codebuild/lib/no-source.ts

@@ -0,0 +1,19 @@
+import { Source } from './source';
+import { NO_SOURCE_TYPE } from './source-types';
+
+/**
+ * A `NO_SOURCE` CodeBuild Project Source definition.
+ * This is the default source type,
+ * if none was specified when creating the Project.
+ * *Note*: the `NO_SOURCE` type cannot be used as a secondary source,
+ * and because of that, you're not allowed to specify an identifier for it.
+ *
+ * This class is private to the aws-codebuild package.
+ */
+export class NoSource extends Source {
+  public readonly type = NO_SOURCE_TYPE;
+
+  constructor() {
+    super({});
+  }
+}

packages/@aws-cdk/aws-codebuild/lib/pipeline-project.ts

@@ -1,7 +1,7 @@
 import cdk = require('@aws-cdk/cdk');
-import { CodePipelineBuildArtifacts } from './artifacts';
+import { CodePipelineArtifacts } from './codepipeline-artifacts';
+import { CodePipelineSource } from './codepipeline-source';
 import { CommonProjectProps, Project } from './project';
-import { CodePipelineSource } from './source';
 
 // tslint:disable-next-line:no-empty-interface
 export interface PipelineProjectProps extends CommonProjectProps {
@@ -14,7 +14,7 @@ export class PipelineProject extends Project {
   constructor(scope: cdk.Construct, id: string, props?: PipelineProjectProps) {
     super(scope, id, {
       source: new CodePipelineSource(),
-      artifacts: new CodePipelineBuildArtifacts(),
+      artifacts: new CodePipelineArtifacts(),
       ...props
     });
   }