Add goal function to create a new GoalWithFulfillment

[changelog:added]

lib/api/goal/GoalWithFulfillment.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { LogSuppressor } from "../../api-helper/log/logInterpreters";
 import { AbstractSoftwareDeliveryMachine } from "../../api-helper/machine/AbstractSoftwareDeliveryMachine";
 import { InterpretLog } from "../../spi/log/InterpretedLog";
 import { GoalExecutionListener } from "../listener/GoalStatusListener";
@@ -38,6 +39,7 @@ import {
     ExecuteGoal,
     GoalProjectListenerRegistration,
 } from "./GoalInvocation";
+import { DefaultGoalNameGenerator } from "./GoalNameGenerator";
 import { ReportProgress } from "./progress/ReportProgress";
 import {
     GoalEnvironment,
@@ -280,6 +282,36 @@ export class GoalWithFulfillment extends FulfillableGoal {
     }
 }
 
+/**
+ * Creates a new GoalWithFulfillment instance using conventions if overwrites aren't provided
+ * @param details
+ * @param goalExecutor
+ * @param options
+ */
+export function goal(details: FulfillableGoalDetails = {},
+                     goalExecutor?: ExecuteGoal,
+                     options?: {
+                         pushTest?: PushTest,
+                         logInterpreter?: InterpretLog,
+                         progressReporter?: ReportProgress,
+                     }): GoalWithFulfillment {
+    const def = getGoalDefinitionFrom(details, DefaultGoalNameGenerator.generateName(details.displayName || "goal"));
+    const g = new GoalWithFulfillment(def);
+    if (!!goalExecutor) {
+        const optsToUse = {
+            pushTest: AnyPush,
+            logInterpreter: LogSuppressor,
+            ...(!!options ? options : {}),
+        };
+        g.with({
+            name: def.uniqueName,
+            goalExecutor,
+            ...optsToUse,
+        });
+    }
+    return g;
+}
+
 // tslint:disable:cyclomatic-complexity
 export function getGoalDefinitionFrom(goalDetails: FulfillableGoalDetails | string,
                                       uniqueName: string,

test/api/goal/GoalWithFulfillment.test.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright © 2018 Atomist, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as assert from "power-assert";
+import { goal } from "../../../lib/api/goal/GoalWithFulfillment";
+import { IndependentOfEnvironment } from "../../../lib/api/goal/support/environment";
+
+describe("GoalWithFulfillment", () => {
+
+    describe("goal", () => {
+
+        it("should create an empty goal", () => {
+            const g = goal();
+            assert(g.uniqueName.startsWith("goal#goalwithfulfillment.test.ts"));
+            assert.strictEqual(g.uniqueName, g.name);
+            assert.strictEqual(g.environment, IndependentOfEnvironment);
+        });
+
+    });
+
+});