Move shared methods to common Action* classes

Feedback and GitMirror actions are the same and share most of
the code. Finish hooks are also similar, the only difference
is that we don't allow to return an error/noop, since they are
kind of "auxiliary" tasks we do to the migration and we don't
want to mask a migration error with a hook error. Also a hook
error shouldn't block migrations.

Change-Id: I5e2304936b8897e221572af153ef94879b060be2

Author: mikelalcon

docs/reference.md

@@ -24,6 +24,7 @@
     - [console.verbose](#console.verbose)
     - [console.warn](#console.warn)
   - [core](#core)
+    - [core.action](#core.action)
     - [core.copy](#core.copy)
     - [core.dynamic_feedback](#core.dynamic_feedback)
     - [core.dynamic_transform](#core.dynamic_transform)
@@ -58,7 +59,10 @@
     - [feedback.context.record_effect](#feedback.context.record_effect)
     - [feedback.context.success](#feedback.context.success)
   - [feedback.finish_hook_context](#feedback.finish_hook_context)
+    - [feedback.finish_hook_context.error](#feedback.finish_hook_context.error)
+    - [feedback.finish_hook_context.noop](#feedback.finish_hook_context.noop)
     - [feedback.finish_hook_context.record_effect](#feedback.finish_hook_context.record_effect)
+    - [feedback.finish_hook_context.success](#feedback.finish_hook_context.success)
   - [feedback.revision_context](#feedback.revision_context)
   - [filter_replace](#filter_replace)
   - [folder](#folder)
@@ -585,6 +589,21 @@ Name | Type | Description
 <span style="white-space: nowrap;">`--validate-starlark`</span> | *string* | Starlark should be validated prior to execution, but this might break legacy configs. Options are LOOSE, STRICT
 <span style="white-space: nowrap;">`-v, --verbose`</span> | *boolean* | Verbose output.
 
+<a id="core.action" aria-hidden="true"></a>
+### core.action
+
+Create a dynamic Skylark action. This should only be used by libraries developers. Actions are Starlark functions that receive a context, perform some side effect and return a result (success, error or noop).
+
+`dynamic.action core.action(impl, params={})`
+
+
+#### Parameters:
+
+Parameter | Description
+--------- | -----------
+impl | `callable`<br><p>The Skylark function to call</p>
+params | `dict`<br><p>The parameters to the function. Will be available under ctx.params</p>
+
 <a id="core.copy" aria-hidden="true"></a>
 ### core.copy
 
@@ -1453,7 +1472,7 @@ console | Get an instance of the console to report errors or warnings
 destination | An object representing the destination. Can be used to query or modify the destination state
 feedback_name | The name of the Feedback migration calling this action.
 origin | An object representing the origin. Can be used to query about the ref or modifying the origin state
-params | Parameters for the function if created with core.dynamic_feedback
+params | Parameters for the function if created with core.action
 refs | A list containing string representations of the entities that triggered the event
 
 <a id="feedback.context.error" aria-hidden="true"></a>
@@ -1526,9 +1545,37 @@ console | Get an instance of the console to report errors or warnings
 destination | An object representing the destination. Can be used to query or modify the destination state
 effects | The list of effects that happened in the destination
 origin | An object representing the origin. Can be used to query about the ref or modifying the origin state
-params | Parameters for the function if created with core.dynamic_feedback
+params | Parameters for the function if created with core.action
 revision | Get the requested/resolved revision
 
+<a id="feedback.finish_hook_context.error" aria-hidden="true"></a>
+### feedback.finish_hook_context.error
+
+Returns an error action result.
+
+`dynamic.action_result feedback.finish_hook_context.error(msg)`
+
+
+#### Parameters:
+
+Parameter | Description
+--------- | -----------
+msg | `string`<br><p>The error message</p>
+
+<a id="feedback.finish_hook_context.noop" aria-hidden="true"></a>
+### feedback.finish_hook_context.noop
+
+Returns a no op action result with an optional message.
+
+`dynamic.action_result feedback.finish_hook_context.noop(msg=None)`
+
+
+#### Parameters:
+
+Parameter | Description
+--------- | -----------
+msg | `string` or `NoneType`<br><p>The no op message</p>
+
 <a id="feedback.finish_hook_context.record_effect" aria-hidden="true"></a>
 ### feedback.finish_hook_context.record_effect
 
@@ -1547,6 +1594,13 @@ destination_ref | `destination_ref`<br><p>The destination ref</p>
 errors | `sequence of string`<br><p>An optional list of errors</p>
 type | `string`<br><p>The type of migration effect:<br><ul><li><b>'CREATED'</b>: A new review or change was created.</li><li><b>'UPDATED'</b>: An existing review or change was updated.</li><li><b>'NOOP'</b>: The change was a noop.</li><li><b>'INSUFFICIENT_APPROVALS'</b>: The effect couldn't happen because the change doesn't have enough approvals.</li><li><b>'ERROR'</b>: A user attributable error happened that prevented the destination from creating/updating the change. <li><b>'STARTED'</b>: The initial effect of a migration that depends on a previous one. This allows to have 'dependant' migrations defined by users.<br>An example of this: a workflow migrates code from a Gerrit review to a GitHub PR, and a feedback migration migrates the test results from a CI in GitHub back to the Gerrit change.<br>This effect would be created on the former one.</li></ul></p>
 
+<a id="feedback.finish_hook_context.success" aria-hidden="true"></a>
+### feedback.finish_hook_context.success
+
+Returns a successful action result.
+
+`dynamic.action_result feedback.finish_hook_context.success()`
+
 
 
 ## feedback.revision_context

java/com/google/copybara/Core.java

@@ -1467,6 +1467,7 @@ public Transformation dynamic_transform(
         impl, Dict.<Object, Object>copyOf(thread.mutability(), params), printHandler);
   }
 
+  // TODO(malcon): Deprecate this method once all references moved to core.action
   @SuppressWarnings("unused")
   @StarlarkMethod(
       name = "dynamic_feedback",
@@ -1490,6 +1491,29 @@ public Action dynamicFeedback(StarlarkCallable impl, Dict<?, ?> params, Starlark
         impl, Dict.<Object, Object>copyOf(thread.mutability(), params), printHandler);
   }
 
+  @SuppressWarnings("unused")
+  @StarlarkMethod(
+      name = "action",
+      doc = "Create a dynamic Skylark action. This should only be used by libraries"
+              + " developers. Actions are Starlark functions that receive a context, perform"
+              + " some side effect and return a result (success, error or noop).",
+      parameters = {
+        @Param(
+            name = "impl",
+            named = true,
+            doc = "The Skylark function to call"),
+        @Param(
+            name = "params",
+            named = true,
+            doc = "The parameters to the function. Will be available under ctx.params",
+            defaultValue = "{}"),
+      },
+      useStarlarkThread = true)
+  public Action action(StarlarkCallable impl, Dict<?, ?> params, StarlarkThread thread) {
+    return new StarlarkAction(
+        impl, Dict.<Object, Object>copyOf(thread.mutability(), params), printHandler);
+  }
+
   @SuppressWarnings("unused")
   @StarlarkMethod(
       name = "fail_with_noop",

java/com/google/copybara/SkylarkContext.java

@@ -28,5 +28,5 @@ public interface SkylarkContext<T> {
   T withParams(Dict<?, ?> params);
 
   /** Performs tasks after Starlark code finishes. */
-  void onFinish(Object result, SkylarkContext<?> context) throws ValidationException;
+  void onFinish(Object result, SkylarkContext<T> context) throws ValidationException;
 }

java/com/google/copybara/TransformWork.java

@@ -754,7 +754,8 @@ private void setDateForCurrentRev(Map<String, ImmutableList<String>> labels) {
   }
 
   @Override
-  public void onFinish(Object result, SkylarkContext<?> context) throws ValidationException {
+  public void onFinish(Object result, SkylarkContext<TransformWork> context)
+      throws ValidationException {
     checkCondition(
         result == null || result.equals(Starlark.NONE),
         "Transform work cannot return any result but returned: %s",

java/com/google/copybara/Workflow.java

@@ -50,6 +50,7 @@
 import com.google.copybara.util.Glob;
 import com.google.copybara.util.Identity;
 import com.google.copybara.util.console.Console;
+
 import java.io.IOException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
@@ -62,6 +63,7 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import java.util.stream.Collectors;
+
 import javax.annotation.Nullable;
 
 /**

java/com/google/copybara/action/Action.java

@@ -17,9 +17,9 @@
 package com.google.copybara.action;
 
 import com.google.common.collect.ImmutableSetMultimap;
-import com.google.copybara.SkylarkContext;
 import com.google.copybara.exception.RepoException;
 import com.google.copybara.exception.ValidationException;
+
 import net.starlark.java.annot.StarlarkBuiltin;
 import net.starlark.java.eval.StarlarkValue;
 
@@ -34,7 +34,7 @@
     documented = false)
 public interface Action extends StarlarkValue {
 
-  void run(SkylarkContext<?> context) throws ValidationException, RepoException;
+  void run(ActionContext context) throws ValidationException, RepoException;
 
   String getName();