Rename option, refine docs, add tests

Author: krzema12

github-workflows-kt/api/github-workflows-kt.api

@@ -3249,8 +3249,8 @@ public final class io/github/typesafegithub/workflows/yaml/CheckoutActionVersion
 	public final fun getVersion ()Ljava/lang/String;
 }
 
-public final class io/github/typesafegithub/workflows/yaml/CheckoutActionVersionSource$InferredFromClasspath : io/github/typesafegithub/workflows/yaml/CheckoutActionVersionSource {
-	public static final field INSTANCE Lio/github/typesafegithub/workflows/yaml/CheckoutActionVersionSource$InferredFromClasspath;
+public final class io/github/typesafegithub/workflows/yaml/CheckoutActionVersionSource$InferFromClasspath : io/github/typesafegithub/workflows/yaml/CheckoutActionVersionSource {
+	public static final field INSTANCE Lio/github/typesafegithub/workflows/yaml/CheckoutActionVersionSource$InferFromClasspath;
 }
 
 public abstract interface class io/github/typesafegithub/workflows/yaml/ConsistencyCheckJobConfig {

github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/ConsistencyCheckJob.kt

@@ -12,7 +12,6 @@ import io.github.typesafegithub.workflows.internal.relativeToAbsolute
 import java.nio.file.Path
 import kotlin.io.path.invariantSeparatorsPathString
 import kotlin.reflect.KParameter
-import kotlin.reflect.full.memberProperties
 import kotlin.reflect.full.primaryConstructor
 import kotlin.reflect.jvm.isAccessible
 
@@ -46,7 +45,10 @@ internal fun WorkflowBuilder.consistencyCheckJob(
             when (consistencyCheckJobConfig.checkoutActionVersion) {
                 CheckoutActionVersionSource.BundledWithLibrary -> "v4"
                 is CheckoutActionVersionSource.Given -> consistencyCheckJobConfig.checkoutActionVersion.version
-                CheckoutActionVersionSource.InferredFromClasspath -> inferCheckoutActionVersionFromClasspath()
+                CheckoutActionVersionSource.InferFromClasspath ->
+                    inferCheckoutActionVersionFromClasspath(
+                        consistencyCheckJobConfig.checkoutActionClassFQN,
+                    )
             }
 
         uses(
@@ -112,8 +114,17 @@ internal fun WorkflowBuilder.consistencyCheckJob(
     }
 }
 
-private fun inferCheckoutActionVersionFromClasspath(): String {
-    val clazz = Class.forName("io.github.typesafegithub.workflows.actions.actions.Checkout")
+private fun inferCheckoutActionVersionFromClasspath(checkoutActionClassFQN: String): String {
+    val clazz: Class<*> =
+        try {
+            Class.forName(checkoutActionClassFQN)
+        } catch (_: ClassNotFoundException) {
+            error(
+                "actions/checkout is not found in the classpath! " +
+                    "Either add a dependency on it (`@file:DependsOn(\"actions:checkout:<version>\")`), " +
+                    "or don't use CheckoutActionVersionSource.InferFromClasspath",
+            )
+        } as Class<*>
     // It's easier to call the primary constructor, even though it's private, because
     // the public constructor requires named arguments, and I'm not sure how to call
     // it with these.

github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/ConsistencyCheckJobConfig.kt

@@ -8,6 +8,7 @@ public val DEFAULT_CONSISTENCY_CHECK_JOB_CONFIG: ConsistencyCheckJobConfig.Confi
         condition = null,
         env = emptyMap(),
         checkoutActionVersion = CheckoutActionVersionSource.BundledWithLibrary,
+        checkoutActionClassFQN = "io.github.typesafegithub.workflows.actions.actions.Checkout",
         additionalSteps = null,
         useLocalBindingsServerAsFallback = false,
     )
@@ -19,10 +20,15 @@ public sealed interface ConsistencyCheckJobConfig {
         val condition: String?,
         val env: Map<String, String>,
         /**
-         * Configures what version of https://github.com/actions/checkout should be used in the consistency check job.
+         * Configures what version of https://github.com/actions/checkout is used in the consistency check job.
          * Lets the user choose between convenience of automatic updates and more determinism and control if required.
          */
         val checkoutActionVersion: CheckoutActionVersionSource,
+        /**
+         * Specifies the fully qualified name of a binding class for actions/checkout. Can be overridden if a custom
+         * binding class is provided for this action, under a different FQN.
+         */
+        val checkoutActionClassFQN: String,
         val additionalSteps: (JobBuilder<JobOutputs.EMPTY>.() -> Unit)?,
         /**
          * If the script execution step in the consistency check job fails, another attempt to execute is made with a
@@ -35,10 +41,27 @@ public sealed interface ConsistencyCheckJobConfig {
 }
 
 public sealed interface CheckoutActionVersionSource {
+    /**
+     * Every version of github-workflows-kt library comes with a hardcoded version of this action.
+     * Since bumping this version is possible only upon major releases (major version bumps), this
+     * version often lags behind the newest one.
+     *
+     * This is the current default option.
+     */
     public object BundledWithLibrary : CheckoutActionVersionSource
 
-    public object InferredFromClasspath : CheckoutActionVersionSource
+    /**
+     * In the great majority of workflows, the checkout action is used in a preferred version.
+     * We can utilize this fact and use the same version in the consistency check job.
+     * Warning: this option won't work if a dependency on "action:checkout:vN" is not present.
+     *
+     * This is the most convenient option, and a candidate to become the default one.
+     */
+    public object InferFromClasspath : CheckoutActionVersionSource
 
+    /**
+     * Useful if it's desired to specify a concrete version by hand, right in your workflow.
+     */
     public class Given(
         public val version: String,
     ) : CheckoutActionVersionSource

github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/IntegrationTest.kt

@@ -384,7 +384,7 @@ class IntegrationTest :
                 sourceFile = sourceTempFile,
                 consistencyCheckJobConfig =
                     DEFAULT_CONSISTENCY_CHECK_JOB_CONFIG.copy(
-                        checkoutActionVersion = CheckoutActionVersionSource.InferredFromClasspath,
+                        checkoutActionVersion = CheckoutActionVersionSource.InferFromClasspath,
                     ),
             ) {
                 job(
@@ -434,6 +434,36 @@ class IntegrationTest :
                 """.trimIndent()
         }
 
+        test("actions/checkout's version inferred from classpath but binding class is not available") {
+            // when
+            shouldThrow<IllegalStateException> {
+                workflow(
+                    name = "Test workflow",
+                    on = listOf(Push()),
+                    sourceFile = sourceTempFile,
+                    consistencyCheckJobConfig =
+                        DEFAULT_CONSISTENCY_CHECK_JOB_CONFIG.copy(
+                            checkoutActionVersion = CheckoutActionVersionSource.InferFromClasspath,
+                            checkoutActionClassFQN = "does.not.Exist",
+                        ),
+                ) {
+                    job(
+                        id = "test_job",
+                        runsOn = RunnerType.UbuntuLatest,
+                    ) {
+                        run(
+                            name = "Hello world!",
+                            command = "echo 'hello!'",
+                        )
+                    }
+                }
+            }.also {
+                it.message shouldBe "actions/checkout is not found in the classpath! " +
+                    "Either add a dependency on it (`@file:DependsOn(\"actions:checkout:<version>\")`), " +
+                    "or don't use CheckoutActionVersionSource.InferFromClasspath"
+            }
+        }
+
         test("with concurrency, default behavior") {
             // when
             workflow(