feat: allow using version ranges to cope with stale Maven Local cache (#1611)

With these changes you can for example depend on
`actions:cache__save___major:[v4,v5)"` and get the latest v4 action with
latest v4 typing by resolving to a concrete v4.x.y version but the
output still contains just `v4`.
The same for `actions:cache__save___minor:[v4.0,v4.1)`, to get the
latest v4.0 but in the output just have `v4.0`.

Author: Vampire

.github/workflows/test-script-consuming-jit-bindings.main.do-not-compile.kts

@@ -1,6 +1,7 @@
 #!/usr/bin/env kotlin
 @file:Repository("https://repo.maven.apache.org/maven2/")
 @file:DependsOn("io.github.typesafegithub:github-workflows-kt:1.13.0")
+@file:DependsOn("io.kotest:kotest-assertions-core:5.9.1")
 
 @file:Repository("http://localhost:8080")
 
@@ -13,14 +14,21 @@
 // Using specific version.
 @file:DependsOn("actions:cache:v3.3.3")
 
+// Using version ranges.
+@file:DependsOn("gradle:actions__dependency-submission___major:[v3.3.1,v4-alpha)")
+@file:DependsOn("gradle:actions__wrapper-validation___minor:[v4.2.1,v4.3-alpha)")
+
 // Always untyped action.
 @file:DependsOn("typesafegithub:always-untyped-action-for-tests:v1")
 
 import io.github.typesafegithub.workflows.actions.actions.Cache
 import io.github.typesafegithub.workflows.actions.actions.Checkout
 import io.github.typesafegithub.workflows.actions.actions.Checkout_Untyped
 import io.github.typesafegithub.workflows.actions.gradle.ActionsSetupGradle
+import io.github.typesafegithub.workflows.actions.gradle.ActionsDependencySubmission_Untyped
+import io.github.typesafegithub.workflows.actions.gradle.ActionsWrapperValidation
 import io.github.typesafegithub.workflows.actions.typesafegithub.AlwaysUntypedActionForTests_Untyped
+import io.kotest.matchers.shouldBe
 
 println(Checkout_Untyped(fetchTags_Untyped = "false"))
 println(Checkout(fetchTags = false))
@@ -29,5 +37,8 @@ println(AlwaysUntypedActionForTests_Untyped(foobar_Untyped = "baz"))
 println(ActionsSetupGradle())
 println(Cache(path = listOf("some-path"), key = "some-key"))
 
+ActionsDependencySubmission_Untyped().actionVersion shouldBe "v3"
+ActionsWrapperValidation().actionVersion shouldBe "v4.2"
+
 // Ensure that 'copy(...)' method is exposed.
 Checkout(fetchTags = false).copy(fetchTags = true)

action-binding-generator/api/action-binding-generator.api

@@ -1,16 +1,18 @@
 public final class io/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords {
-	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
-	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Ljava/lang/String;
 	public final fun component3 ()Ljava/lang/String;
-	public final fun component4 ()Ljava/lang/String;
-	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;
-	public static synthetic fun copy$default (Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;
+	public final fun component4 ()Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
+	public final fun component5 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;Ljava/lang/String;)Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;
+	public static synthetic fun copy$default (Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;Ljava/lang/String;ILjava/lang/Object;)Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getName ()Ljava/lang/String;
 	public final fun getOwner ()Ljava/lang/String;
 	public final fun getPath ()Ljava/lang/String;
+	public final fun getSignificantVersion ()Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
 	public final fun getVersion ()Ljava/lang/String;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
@@ -44,6 +46,16 @@ public final class io/github/typesafegithub/workflows/actionbindinggenerator/dom
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class io/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion : java/lang/Enum {
+	public static final field FULL Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
+	public static final field MAJOR Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
+	public static final field MINOR Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public fun toString ()Ljava/lang/String;
+	public static fun valueOf (Ljava/lang/String;)Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
+	public static fun values ()[Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;
+}
+
 public final class io/github/typesafegithub/workflows/actionbindinggenerator/domain/TypingActualSource : java/lang/Enum {
 	public static final field ACTION Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/TypingActualSource;
 	public static final field TYPING_CATALOG Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/TypingActualSource;

action-binding-generator/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords.kt

@@ -1,9 +1,19 @@
 package io.github.typesafegithub.workflows.actionbindinggenerator.domain
 
+import io.github.typesafegithub.workflows.actionbindinggenerator.domain.SignificantVersion.FULL
+
 public data class ActionCoords(
     val owner: String,
     val name: String,
     val version: String,
+    /**
+     * The version part that is significant when generating the YAML output,
+     * i.e. whether to write the full version, only the major version or major and minor version.
+     * This is used to enable usage of Maven ranges without needing to specify a custom version
+     * each time instantiating an action.
+     * The value of this property is part of the Maven coordinates as a suffix for the [name] property.
+     */
+    val significantVersion: SignificantVersion = FULL,
     val path: String? = null,
 )
 
@@ -13,7 +23,9 @@ public data class ActionCoords(
  */
 public val ActionCoords.isTopLevel: Boolean get() = path == null
 
-public val ActionCoords.prettyPrint: String get() = "$owner/$fullName@$version"
+public val ActionCoords.prettyPrint: String get() = "$owner/$fullName${
+    significantVersion.takeUnless { it == FULL }?.let { " with $it version" } ?: ""
+}@$version"
 
 /**
  * For most actions, it's empty.

action-binding-generator/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion.kt

@@ -0,0 +1,26 @@
+package io.github.typesafegithub.workflows.actionbindinggenerator.domain
+
+/**
+ * The version part that is significant when generating the YAML output.
+ * This is used to enable usage of Maven ranges without needing to specify a custom version
+ * each time instantiating an action.
+ */
+public enum class SignificantVersion {
+    /**
+     * Only write the major version to the generated YAML.
+     */
+    MAJOR,
+
+    /**
+     * Only write the major and minor version to the generated YAML.
+     */
+    MINOR,
+
+    /**
+     * Write the full version to the generated YAML.
+     */
+    FULL,
+    ;
+
+    override fun toString(): String = super.toString().lowercase()
+}

action-binding-generator/src/main/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/generation/Generation.kt

@@ -17,6 +17,9 @@ import com.squareup.kotlinpoet.asTypeName
 import com.squareup.kotlinpoet.buildCodeBlock
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.ActionCoords
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.MetadataRevision
+import io.github.typesafegithub.workflows.actionbindinggenerator.domain.SignificantVersion.FULL
+import io.github.typesafegithub.workflows.actionbindinggenerator.domain.SignificantVersion.MAJOR
+import io.github.typesafegithub.workflows.actionbindinggenerator.domain.SignificantVersion.MINOR
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.TypingActualSource
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.fullName
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.isTopLevel
@@ -415,9 +418,19 @@ private fun TypeSpec.Builder.inheritsFromRegularAction(
         .superclass(superclass)
         .addSuperclassConstructorParameter("%S", coords.owner)
         .addSuperclassConstructorParameter("%S", coords.fullName)
-        .addSuperclassConstructorParameter("_customVersion ?: %S", coords.version)
+        .addSuperclassConstructorParameter(
+            "_customVersion ?: %S",
+            when (coords.significantVersion) {
+                MAJOR -> coords.version.majorVersion
+                MINOR -> coords.version.minorVersion
+                FULL -> coords.version
+            },
+        )
 }
 
+private val String.majorVersion get() = substringBefore('.')
+private val String.minorVersion get() = split('.', limit = 3).take(2).joinToString(".")
+
 private fun Metadata.primaryConstructor(
     inputTypings: Map<String, Typing>,
     coords: ActionCoords,

action-binding-generator/src/test/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/bindingsfromunittests/ActionWithNoInputsWithMajorVersion.kt

@@ -0,0 +1,51 @@
+// This file was generated using action-binding-generator. Don't change it by hand, otherwise your
+// changes will be overwritten with the next binding code regeneration.
+// See https://github.com/typesafegithub/github-workflows-kt for more info.
+@file:Suppress(
+    "DataClassPrivateConstructor",
+    "UNUSED_PARAMETER",
+)
+
+package io.github.typesafegithub.workflows.actions.johnsmith
+
+import io.github.typesafegithub.workflows.domain.actions.Action
+import io.github.typesafegithub.workflows.domain.actions.RegularAction
+import java.util.LinkedHashMap
+import kotlin.ExposedCopyVisibility
+import kotlin.String
+import kotlin.Suppress
+import kotlin.Unit
+import kotlin.collections.Map
+
+/**
+ * Action: Action With No Inputs
+ *
+ * Description
+ *
+ * [Action on GitHub](https://github.com/john-smith/action-with-no-inputs-with-major-version)
+ *
+ * @param _customInputs Type-unsafe map where you can put any inputs that are not yet supported by the binding
+ * @param _customVersion Allows overriding action's version, for example to use a specific minor version, or a newer version that the binding doesn't yet know about
+ */
+@ExposedCopyVisibility
+public data class ActionWithNoInputsWithMajorVersion private constructor(
+    /**
+     * Type-unsafe map where you can put any inputs that are not yet supported by the binding
+     */
+    public val _customInputs: Map<String, String> = mapOf(),
+    /**
+     * Allows overriding action's version, for example to use a specific minor version, or a newer version that the binding doesn't yet know about
+     */
+    public val _customVersion: String? = null,
+) : RegularAction<Action.Outputs>("john-smith", "action-with-no-inputs-with-major-version", _customVersion ?: "v3") {
+    public constructor(
+        vararg pleaseUseNamedArguments: Unit,
+        _customInputs: Map<String, String> = mapOf(),
+        _customVersion: String? = null,
+    ) : this(_customInputs = _customInputs, _customVersion = _customVersion)
+
+    @Suppress("SpreadOperator")
+    override fun toYamlArguments(): LinkedHashMap<String, String> = LinkedHashMap(_customInputs)
+
+    override fun buildOutputObject(stepId: String): Action.Outputs = Outputs(stepId)
+}

action-binding-generator/src/test/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/bindingsfromunittests/ActionWithNoInputsWithMajorVersion_Untyped.kt

@@ -0,0 +1,76 @@
+// This file was generated using action-binding-generator. Don't change it by hand, otherwise your
+// changes will be overwritten with the next binding code regeneration.
+// See https://github.com/typesafegithub/github-workflows-kt for more info.
+@file:Suppress(
+    "DataClassPrivateConstructor",
+    "UNUSED_PARAMETER",
+)
+
+package io.github.typesafegithub.workflows.actions.johnsmith
+
+import io.github.typesafegithub.workflows.domain.actions.Action
+import io.github.typesafegithub.workflows.domain.actions.RegularAction
+import java.util.LinkedHashMap
+import kotlin.Deprecated
+import kotlin.ExposedCopyVisibility
+import kotlin.String
+import kotlin.Suppress
+import kotlin.Unit
+import kotlin.collections.Map
+
+/**
+ * ```text
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ * !!!                             WARNING                             !!!
+ * !!!                                                                 !!!
+ * !!! This action binding has no typings provided. All inputs will    !!!
+ * !!! have a default type of String.                                  !!!
+ * !!! To be able to use this action in a type-safe way, ask the       !!!
+ * !!! action's owner to provide the typings using                     !!!
+ * !!!                                                                 !!!
+ * !!! https://github.com/typesafegithub/github-actions-typing         !!!
+ * !!!                                                                 !!!
+ * !!! or if it's impossible, contribute typings to a community-driven !!!
+ * !!!                                                                 !!!
+ * !!! https://github.com/typesafegithub/github-actions-typing-catalog !!!
+ * !!!                                                                 !!!
+ * !!! This '_Untyped' binding will be available even once the typings !!!
+ * !!! are added.                                                      !!!
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ * ```
+ *
+ * Action: Action With No Inputs
+ *
+ * Description
+ *
+ * [Action on GitHub](https://github.com/john-smith/action-with-no-inputs-with-major-version)
+ *
+ * @param _customInputs Type-unsafe map where you can put any inputs that are not yet supported by the binding
+ * @param _customVersion Allows overriding action's version, for example to use a specific minor version, or a newer version that the binding doesn't yet know about
+ */
+@Deprecated(
+    "Use the typed class instead",
+    ReplaceWith("ActionWithNoInputsWithMajorVersion"),
+)
+@ExposedCopyVisibility
+public data class ActionWithNoInputsWithMajorVersion_Untyped private constructor(
+    /**
+     * Type-unsafe map where you can put any inputs that are not yet supported by the binding
+     */
+    public val _customInputs: Map<String, String> = mapOf(),
+    /**
+     * Allows overriding action's version, for example to use a specific minor version, or a newer version that the binding doesn't yet know about
+     */
+    public val _customVersion: String? = null,
+) : RegularAction<Action.Outputs>("john-smith", "action-with-no-inputs-with-major-version", _customVersion ?: "v3") {
+    public constructor(
+        vararg pleaseUseNamedArguments: Unit,
+        _customInputs: Map<String, String> = mapOf(),
+        _customVersion: String? = null,
+    ) : this(_customInputs = _customInputs, _customVersion = _customVersion)
+
+    @Suppress("SpreadOperator")
+    override fun toYamlArguments(): LinkedHashMap<String, String> = LinkedHashMap(_customInputs)
+
+    override fun buildOutputObject(stepId: String): Action.Outputs = Outputs(stepId)
+}

action-binding-generator/src/test/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/bindingsfromunittests/ActionWithNoInputsWithMinorVersion.kt

@@ -0,0 +1,51 @@
+// This file was generated using action-binding-generator. Don't change it by hand, otherwise your
+// changes will be overwritten with the next binding code regeneration.
+// See https://github.com/typesafegithub/github-workflows-kt for more info.
+@file:Suppress(
+    "DataClassPrivateConstructor",
+    "UNUSED_PARAMETER",
+)
+
+package io.github.typesafegithub.workflows.actions.johnsmith
+
+import io.github.typesafegithub.workflows.domain.actions.Action
+import io.github.typesafegithub.workflows.domain.actions.RegularAction
+import java.util.LinkedHashMap
+import kotlin.ExposedCopyVisibility
+import kotlin.String
+import kotlin.Suppress
+import kotlin.Unit
+import kotlin.collections.Map
+
+/**
+ * Action: Action With No Inputs
+ *
+ * Description
+ *
+ * [Action on GitHub](https://github.com/john-smith/action-with-no-inputs-with-minor-version)
+ *
+ * @param _customInputs Type-unsafe map where you can put any inputs that are not yet supported by the binding
+ * @param _customVersion Allows overriding action's version, for example to use a specific minor version, or a newer version that the binding doesn't yet know about
+ */
+@ExposedCopyVisibility
+public data class ActionWithNoInputsWithMinorVersion private constructor(
+    /**
+     * Type-unsafe map where you can put any inputs that are not yet supported by the binding
+     */
+    public val _customInputs: Map<String, String> = mapOf(),
+    /**
+     * Allows overriding action's version, for example to use a specific minor version, or a newer version that the binding doesn't yet know about
+     */
+    public val _customVersion: String? = null,
+) : RegularAction<Action.Outputs>("john-smith", "action-with-no-inputs-with-minor-version", _customVersion ?: "v3.1") {
+    public constructor(
+        vararg pleaseUseNamedArguments: Unit,
+        _customInputs: Map<String, String> = mapOf(),
+        _customVersion: String? = null,
+    ) : this(_customInputs = _customInputs, _customVersion = _customVersion)
+
+    @Suppress("SpreadOperator")
+    override fun toYamlArguments(): LinkedHashMap<String, String> = LinkedHashMap(_customInputs)
+
+    override fun buildOutputObject(stepId: String): Action.Outputs = Outputs(stepId)
+}