feat: WIP: provide bindings with comment

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env kotlin
 @file:Repository("https://repo.maven.apache.org/maven2/")
-@file:DependsOn("io.github.typesafegithub:github-workflows-kt:3.4.0")
+@file:DependsOn("io.github.typesafegithub:github-workflows-kt:3.6.0")
 @file:DependsOn("io.kotest:kotest-assertions-core:5.9.1")
 
 @file:Repository("http://localhost:8080")
@@ -24,6 +24,9 @@
 // Always untyped action.
 @file:DependsOn("typesafegithub:always-untyped-action-for-tests:v1")
 
+// Action version pinned to a commit.
+@file:DependsOn("actions:setup-python___commit_lenient:v6.0.0__e797f83bcb11b83ae66e0230d6156d7c80228e7c")
+
 import io.github.typesafegithub.workflows.actions.actions.Cache
 import io.github.typesafegithub.workflows.actions.actions.Checkout
 import io.github.typesafegithub.workflows.actions.actions.SetupNode
@@ -41,6 +44,7 @@ println(AlwaysUntypedActionForTests_Untyped(foobar_Untyped = "baz"))
 println(ActionsSetupGradle())
 println(Cache(path = listOf("some-path"), key = "some-key"))
 println(SetupNode())
+println(SetupPython())
 
 ActionsDependencySubmission_Untyped().actionVersion shouldBe "v3"
 ActionsWrapperValidation().actionVersion shouldBe "v4.2"

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

@@ -1,14 +1,16 @@
 public final class io/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords {
-	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 fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/SignificantVersion;Ljava/lang/String;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;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 ()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 final fun component6 ()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;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;Ljava/lang/String;ILjava/lang/Object;)Lio/github/typesafegithub/workflows/actionbindinggenerator/domain/ActionCoords;
 	public fun equals (Ljava/lang/Object;)Z
+	public final fun getComment ()Ljava/lang/String;
 	public final fun getName ()Ljava/lang/String;
 	public final fun getOwner ()Ljava/lang/String;
 	public final fun getPath ()Ljava/lang/String;

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

@@ -15,6 +15,7 @@ public data class ActionCoords(
      */
     val significantVersion: SignificantVersion = FULL,
     val path: String? = null,
+    val comment: String? = null,
 )
 
 /**

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

@@ -463,7 +463,11 @@ private fun TypeSpec.Builder.inheritsFromRegularAction(
                 MINOR -> coords.version.minorVersion
                 FULL -> coords.version
             },
-        )
+        ).also {
+            if (coords.comment != null) {
+                addSuperclassConstructorParameter("%S", coords.comment)
+            }
+        }
 }
 
 private val String.majorVersion get() = substringBefore('.')

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

@@ -0,0 +1,80 @@
+// 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
+import kotlin.collections.toList
+import kotlin.collections.toTypedArray
+
+/**
+ * Action: Action with comment
+ *
+ * Do something cool
+ *
+ * [Action on GitHub](https://github.com/john-smith/action-with-comment)
+ *
+ * @param foo <required> Short description
+ * @param foo_Untyped <required> Short description
+ * @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 ActionWithComment private constructor(
+    /**
+     * <required> Short description
+     */
+    public val foo: String? = null,
+    /**
+     * <required> Short description
+     */
+    public val foo_Untyped: String? = null,
+    /**
+     * 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-comment", _customVersion ?: "v3", "some-comment") {
+    init {
+        require(!((foo != null) && (foo_Untyped != null))) {
+            "Only foo or foo_Untyped must be set, but not both"
+        }
+        require((foo != null) || (foo_Untyped != null)) {
+            "Either foo or foo_Untyped must be set, one of them is required"
+        }
+    }
+
+    public constructor(
+        vararg pleaseUseNamedArguments: Unit,
+        foo: String? = null,
+        foo_Untyped: String? = null,
+        _customInputs: Map<String, String> = mapOf(),
+        _customVersion: String? = null,
+    ) : this(foo = foo, foo_Untyped = foo_Untyped, _customInputs = _customInputs, _customVersion = _customVersion)
+
+    @Suppress("SpreadOperator")
+    override fun toYamlArguments(): LinkedHashMap<String, String> = linkedMapOf(
+        *listOfNotNull(
+            foo?.let { "foo" to it },
+            foo_Untyped?.let { "foo" to it },
+            *_customInputs.toList().toTypedArray(),
+        ).toTypedArray()
+    )
+
+    override fun buildOutputObject(stepId: String): Action.Outputs = Outputs(stepId)
+}

action-binding-generator/src/test/kotlin/io/github/typesafegithub/workflows/actionbindinggenerator/generation/GenerationTest.kt

@@ -582,6 +582,36 @@ class GenerationTest :
                 binding.shouldContainAndMatchFile("ActionWithNoInputsWithMinorVersion_Untyped.kt")
             }
         }
+
+        test("action with comment") {
+            // given
+            val actionManifest =
+                Metadata(
+                    name = "Action with comment",
+                    description = "Do something cool",
+                    inputs =
+                        mapOf(
+                            "foo" to
+                                Input(
+                                    description = "Short description",
+                                    required = true,
+                                    default = null,
+                                ),
+                        ),
+                )
+            val coords = ActionCoords("john-smith", "action-with-comment", "v3", comment = "some-comment")
+
+            // when
+            val binding =
+                coords.generateBinding(
+                    metadataRevision = NewestForVersion,
+                    metadata = actionManifest,
+                    inputTypings = ActionTypings(inputTypings = actionManifest.allInputsAsStrings(), source = ACTION),
+                )
+
+            // then
+            binding.shouldContainAndMatchFile("ActionWithComment.kt")
+        }
     })
 
 private fun Metadata.allInputsAsStrings(): Map<String, Typing> = this.inputs.mapValues { StringTyping }

jit-binding-server/src/main/kotlin/io/github/typesafegithub/workflows/jitbindingserver/ActionCoords.kt

@@ -19,14 +19,37 @@ fun Parameters.extractActionCoords(extractVersion: Boolean): ActionCoords {
                     .entries
                     .find { "$it" == significantVersionString }
             } ?: FULL
+    val pinToCommit =
+        nameAndPathAndSignificantVersionParts
+            .drop(1)
+            .takeIf { it.isNotEmpty() }
+            ?.single() == "commit_lenient"
     val nameAndPathParts = nameAndPath.split("__")
     val name = nameAndPathParts.first()
     val path =
         nameAndPathParts
             .drop(1)
             .joinToString("/")
             .takeUnless { it.isBlank() }
-    val version = if (extractVersion) this["version"]!! else "irrelevant"
+    val version =
+        if (extractVersion) {
+            val versionPart = this["version"]!!
+            if (pinToCommit) {
+                versionPart.split("__")[1]
+            } else {
+                versionPart
+            }
+        } else {
+            "irrelevant"
+        }
+    val comment = if (pinToCommit) this["version"]!!.split("__")[0] else null
 
-    return ActionCoords(owner, name, version, significantVersion, path)
+    return ActionCoords(
+        owner = owner,
+        name = name,
+        version = version,
+        significantVersion = significantVersion,
+        path = path,
+        comment = comment,
+    )
 }

jit-binding-server/src/main/kotlin/io/github/typesafegithub/workflows/jitbindingserver/ArtifactRoutes.kt

@@ -84,6 +84,9 @@ private fun Route.getArtifact(
     refresh: Boolean,
 ) {
     get {
+        // TODO: there'a problem with caching the artifacts under certain keys,
+        //   and parameters.extractActionCoords returning certain (different) ActionCoords.
+        //   Because of this problem, the artifact that uses commit pinning is now not found.
         val bindingArtifacts = call.toBindingArtifacts(refresh, bindingsCache) ?: return@get call.respondNotFound()
 
         if (refresh && !deliverOnRefreshRoute) return@get call.respondText(text = "OK")