feat(automation): improve readability of suggesting versions (#1258)

Author: krzema12

automation/code-generator/src/main/kotlin/io/github/typesafegithub/workflows/codegenerator/versions/SuggestVersions.kt

@@ -42,7 +42,7 @@ suspend fun main() {
     for ((coords, existingVersions) in actionsMap) {
         val available = coords.fetchAvailableVersions(githubAuthorization)
         coords.suggestNewerVersion(existingVersions, available)?.let { message ->
-            val outputForAction = "$message for ${coords.prettyPrint}"
+            val outputForAction = "# ${coords.prettyPrint}\n$message"
             println(outputForAction)
             output += "$outputForAction\n"
         }
@@ -93,8 +93,18 @@ fun ActionCoords.suggestNewerVersion(
                 val removedInputs = metadata.inputs.keys - thisMetadata.inputs.keys
                 val addedOutputs = thisMetadata.outputs.keys - metadata.outputs.keys
                 val removedOutputs = metadata.outputs.keys - thisMetadata.outputs.keys
-                "$it (added inputs: $addedInputs, removed inputs: $removedInputs, " +
-                    "added outputs: $addedOutputs, removed outputs: $removedOutputs)"
+                """
+                * $it ([diff](${this.buildGitHubComparisonUrl(maxExisting, it)}))
+                  * added inputs: $addedInputs
+                  * removed inputs: $removedInputs
+                  * added outputs: $addedOutputs
+                  * removed outputs: $removedOutputs
+                """.trimIndent()
             }
-    return "new version(s) available: $newerMajorVersions".takeIf { newerMajorVersions.isNotEmpty() }
+    return newerMajorVersions.joinToString("\n").takeIf { newerMajorVersions.isNotEmpty() }
 }
+
+private fun ActionCoords.buildGitHubComparisonUrl(
+    version1: Version,
+    version2: Version,
+): String = "https://github.com/${this.owner}/${this.name}/compare/$version1...$version2#files_bucket"

automation/code-generator/src/test/kotlin/io/github/typesafegithub/workflows/codegenerator/versions/SuggestVersionsTest.kt

@@ -103,23 +103,45 @@ class SuggestVersionsTest : FunSpec({
                     "v1".versions(),
                     "v1, v1.1.1, v2, v2.0.1, v3, v3.1.1".versions(),
                     fetchMeta = ActionCoords::fetchMeta,
-                ) shouldBe "new version(s) available: [" +
-                    "v2 (added inputs: [new-input-in-v2], removed inputs: [input-will-be-removed-in-v2], " +
-                    "added outputs: [new-input-in-v2], removed outputs: [outputs-will-be-removed-in-v2]), " +
-                    "v3 (added inputs: [new-input-in-v2], removed inputs: [input-will-be-removed-in-v2], " +
-                    "added outputs: [new-input-in-v2], removed outputs: [outputs-will-be-removed-in-v2])]"
+                ) shouldBe
+                    """
+                    * v2 ([diff](https://github.com/test-owner/test-name/compare/v1...v2#files_bucket))
+                      * added inputs: [new-input-in-v2]
+                      * removed inputs: [input-will-be-removed-in-v2]
+                      * added outputs: [new-input-in-v2]
+                      * removed outputs: [outputs-will-be-removed-in-v2]
+                    * v3 ([diff](https://github.com/test-owner/test-name/compare/v1...v3#files_bucket))
+                      * added inputs: [new-input-in-v2]
+                      * removed inputs: [input-will-be-removed-in-v2]
+                      * added outputs: [new-input-in-v2]
+                      * removed outputs: [outputs-will-be-removed-in-v2]
+                    """.trimIndent()
 
                 testCoords.suggestNewerVersion(
                     "v2".versions(),
                     "v1.1.1, v2, v2.0.1, v3, v3.1.1".versions(),
                     fetchMeta = ActionCoords::fetchMeta,
-                ) shouldBe "new version(s) available: [v3 (added inputs: [], removed inputs: [], added outputs: [], removed outputs: [])]"
+                ) shouldBe
+                    """
+                    * v3 ([diff](https://github.com/test-owner/test-name/compare/v2...v3#files_bucket))
+                      * added inputs: []
+                      * removed inputs: []
+                      * added outputs: []
+                      * removed outputs: []
+                    """.trimIndent()
 
                 testCoords.suggestNewerVersion(
                     "v9".versions(),
                     "v12, v12.0.1".versions(),
                     fetchMeta = ActionCoords::fetchMeta,
-                ) shouldBe "new version(s) available: [v12 (added inputs: [], removed inputs: [], added outputs: [], removed outputs: [])]"
+                ) shouldBe
+                    """
+                    * v12 ([diff](https://github.com/test-owner/test-name/compare/v9...v12#files_bucket))
+                      * added inputs: []
+                      * removed inputs: []
+                      * added outputs: []
+                      * removed outputs: []
+                    """.trimIndent()
             }
         }
     }