Documentation generation (Dokka HTML) (#3)

Generate documentation HTML and `javadoc.jar`.

Reviewed-on: #3

.github/workflows/main.yaml

@@ -1,9 +0,0 @@
-name: Main Workflow
-on:
-  pull_request:
-    branches:
-      - main
-  push:
-    branches:
-      - main
-jobs:

.github/workflows/publish.yaml

@@ -0,0 +1,40 @@
+name: Publish Workflow
+on:
+  push:
+    tags:
+      - v*
+jobs:
+  publish:
+    name: Publish library
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: adopt
+          java-version: 17
+
+      - name: Verify Gradle wrapper
+        uses: gradle/wrapper-validation-action@v1
+
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v2
+
+      - name: Run checks
+        run: ./gradlew check
+
+      - name: Parse parameters
+        id: parse
+        run: |
+          export VERSION="$(echo ${{ github.ref_name }} | cut -c2-)"
+          echo "Parsed version: '$VERSION'"
+          echo "tinyvm_version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Publish to Gitea package repository
+        env:
+          TINYVM_VERSION: ${{ steps.parse.outputs.tinyvm_version }}
+          GITEA_USERNAME: ${{ github.repository_owner }}
+          GITEA_TOKEN: ${{ secrets.deploy_token }}
+        run: ./gradlew publishAllPublicationsToGiteaRepository

.github/workflows/test.yaml

@@ -0,0 +1,29 @@
+name: Test Workflow
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+jobs:
+  lint-and-test:
+    name: Lint and test library
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: adopt
+          java-version: 17
+
+      - name: Verify Gradle wrapper
+        uses: gradle/wrapper-validation-action@v1
+
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v2
+
+      - name: Run checks
+        run: ./gradlew check

.idea/gradle.xml

@@ -5,6 +5,7 @@
     <option name="linkedExternalProjectsSettings">
       <GradleProjectSettings>
         <option name="externalProjectPath" value="$PROJECT_DIR$" />
+        <option name="gradleJvm" value="corretto-19" />
         <option name="modules">
           <set>
             <option value="$PROJECT_DIR$" />

build.gradle.kts

@@ -1,10 +1,12 @@
 plugins {
     kotlin("jvm") version "1.9.21"
     id("org.jmailen.kotlinter") version "4.1.0"
+    id("org.jetbrains.dokka") version "1.9.10"
+    `maven-publish`
 }
 
-group = "net.koval"
-version = "1.0-SNAPSHOT"
+group = "net.koval.teamcity-gitea-test-task"
+version = System.getenv("TINYVM_VERSION")
 
 repositories {
     mavenCentral()
@@ -21,3 +23,46 @@ tasks.test {
 kotlin {
     jvmToolchain(17)
 }
+
+val dokkaHtml by tasks.getting(org.jetbrains.dokka.gradle.DokkaTask::class)
+val javadocJar: TaskProvider<Jar> by tasks.registering(Jar::class) {
+    dependsOn(dokkaHtml)
+    archiveClassifier.set("javadoc")
+    from(dokkaHtml.outputDirectory)
+}
+
+publishing {
+    publications.register<MavenPublication>("gpr") {
+        artifactId = "tinyvm"
+        from(components["java"])
+        artifact(javadocJar)
+        pom {
+            name.set("TeamCity support for Gitea - Test Task - tiny version manager")
+            description.set("This is a small project to implement a subset of git's functionality in Kotlin and was " +
+                "created using the instructions below as part of my application to the JetBrains internship project " +
+                "\"TeamCity support for Gitea\".")
+            url.set("https://git.koval.net/cyclane/teamcity-gitea-test-task")
+            developers {
+                developer {
+                    id.set("cyclane")
+                    name.set("Gleb Koval")
+                    email.set("gleb@koval.net")
+                }
+            }
+            scm {
+                url.set("https://git.koval.net/cyclane/teamcity-gitea-test-task")
+            }
+        }
+    }
+
+    repositories {
+        maven {
+            name = "Gitea"
+            url = uri("https://git.koval.net/api/packages/cyclane/maven")
+            credentials {
+                username = System.getenv("GITEA_USERNAME")
+                password = System.getenv("GITEA_TOKEN")
+            }
+        }
+    }
+}

src/main/kotlin/tinyvm/Commit.kt

@@ -2,32 +2,41 @@ package tinyvm
 
 import java.security.MessageDigest
 import java.time.Instant
+import java.util.HexFormat
 
-abstract class Object(
-    val type: String,
-) {
+/**
+ * Represents an arbitrary version manager object.
+ */
+abstract class Object(val type: String) {
     abstract val data: String
-    fun hash(): String = MessageDigest
+
+    fun hash(): String =
+        HexFormat.of().formatHex(
+            MessageDigest
                 .getInstance("SHA-1")
-        .digest("$type ${data.length}\u0000$data".toByteArray())
-        .toHex()
+                .digest("$type ${data.length}\u0000$data".toByteArray()),
+        )
 }
 
+/**
+ * Commits are a pointer to a 'head' tree with some metadata.
+ */
 class Commit(
     val tree: Tree,
     val author: Author,
     val message: String,
-    val timestamp: Instant
+    val timestamp: Instant,
 ) : Object("commit") {
-    // Use \n\n for end of header in-case additional metadata is implemented in the future.
     override val data: String
+        // Use \n\n for end of header in-case additional metadata is implemented in the future.
         get() = "tree ${tree.hash()}\nauthor $author\ntimestamp ${timestamp.epochSecond}\n\n$message"
+
+    override fun toString(): String = "commit ${hash()}\n$data"
 }
 
 data class Author(
     val name: String,
-    val email: String
+    val email: String,
 ) {
-    override fun toString(): String =
-        "$name <$email>"
+    override fun toString(): String = "$name <$email>"
 }

src/main/kotlin/tinyvm/Extensions.kt

@@ -1,6 +0,0 @@
-package tinyvm
-
-import java.util.HexFormat
-
-fun ByteArray.toHex(): String =
-     HexFormat.of().formatHex(this)

src/main/kotlin/tinyvm/Repository.kt

@@ -2,9 +2,11 @@ package tinyvm
 
 class HashCollisionException(hash: String) : Exception("Different object types with identical hash '$hash'")
 
-class CommitTimeComparator: Comparator<Commit> {
-    override fun compare(o1: Commit, o2: Commit): Int =
-        (o1.timestamp.epochSecond - o2.timestamp.epochSecond).toInt()
+class CommitTimeComparator : Comparator<Commit> {
+    override fun compare(
+        o1: Commit,
+        o2: Commit,
+    ): Int = (o1.timestamp.epochSecond - o2.timestamp.epochSecond).toInt()
 }
 
 class Repository {
@@ -23,11 +25,12 @@ class Repository {
         val hash = commit.hash()
         val obj = findObject<Commit>(hash)
         if (obj != null) return obj
-        val newCommit = Commit(
+        val newCommit =
+            Commit(
                 tree = addTree(commit.tree),
                 author = commit.author,
                 message = commit.message,
-            timestamp = commit.timestamp
+                timestamp = commit.timestamp,
             )
         objects[hash] = newCommit
         commits.add(newCommit)
@@ -47,8 +50,7 @@ class Repository {
     /**
      * Find commit.
      */
-    fun findCommit(predicate: (Commit) -> Boolean): Commit? =
-        commits.find(predicate)
+    fun findCommit(predicate: (Commit) -> Boolean): Commit? = commits.find(predicate)
 
     /**
      * Dump repository objects
@@ -63,13 +65,14 @@ class Repository {
         val hash = tree.hash()
         val obj = findObject<Tree>(hash)
         if (obj != null) return obj
-        val newTree = Tree(
+        val newTree =
+            Tree(
                 tree.nodes.map { (name, node) ->
                     when (node) {
                         is Tree -> name to addTree(node)
                         is Blob -> name to addObject(node)
                     }
-            }.toMap()
+                }.toMap(),
             )
         objects[hash] = newTree
         return tree
@@ -86,5 +89,4 @@ class Repository {
      */
     private inline fun <reified T : Object> findObject(hash: String): T? =
         objects[hash]?.let { it as? T ?: throw HashCollisionException(hash) }
-
 }

src/main/kotlin/tinyvm/Tree.kt

@@ -1,13 +1,23 @@
 package tinyvm
 
-sealed class Node(type: String): Object(type)
+/**
+ * Tree nodes are either trees or blobs, represented by this sealed class.
+ */
+sealed class Node(type: String) : Object(type)
 
+/**
+ * A tree is a set of named nodes.
+ */
 class Tree(val nodes: Map<String, Node>) : Node("tree") {
     // For simplicity just use the hex-formatted hash, not the actual value like git does.
     override val data: String
-        get() = nodes.map { (name, node) ->
+        get() =
+            nodes.map { (name, node) ->
                 "${node.type} $name\u0000${node.hash()}"
             }.sorted().joinToString()
 }
 
+/**
+ * A blob is a data container.
+ */
 class Blob(override val data: String) : Node("blob")

src/test/kotlin/tinyvm/RepositoryTest.kt

@@ -6,50 +6,59 @@ import kotlin.test.assertEquals
 
 internal class RepositoryTest {
     private val repository = Repository()
-    private val commits = listOf(
+    private val commits =
+        listOf(
             Commit(
                 tree = Tree(mapOf("test1.txt" to Blob("Hello World!"))),
                 author = Author("Gleb Koval", "gleb@koval.net"),
                 message = "Add test1.txt",
-            timestamp = Instant.ofEpochSecond(0)
-        ), Commit(
-            tree = Tree(
-                mapOf(
-                    "dir1" to Tree(
-                        mapOf(
-                            "test1.txt" to Blob("Hello World!")
-                        )
+                timestamp = Instant.ofEpochSecond(0),
             ),
-                    "dir2" to Tree(
+            Commit(
+                tree =
+                    Tree(
                         mapOf(
-                            "test2.txt" to Blob("This is a second file")
-                        )
-                    )
-                )
+                            "dir1" to
+                                Tree(
+                                    mapOf(
+                                        "test1.txt" to Blob("Hello World!"),
+                                    ),
+                                ),
+                            "dir2" to
+                                Tree(
+                                    mapOf(
+                                        "test2.txt" to Blob("This is a second file"),
+                                    ),
+                                ),
+                        ),
                     ),
                 author = Author("Gleb Koval", "gleb@koval.net"),
                 message = "Move test1.txt and add dir2/test2.txt",
-            timestamp = Instant.ofEpochSecond(50)
-        ), Commit(
-            tree = Tree(
-                mapOf(
-                    "dir1" to Tree(
-                        mapOf(
-                            "test1.txt" to Blob("Hello World!")
-                        )
+                timestamp = Instant.ofEpochSecond(50),
             ),
-                    "dir2" to Tree(
+            Commit(
+                tree =
+                    Tree(
                         mapOf(
-                            "test2.txt" to Blob("This is a second file")
-                        )
+                            "dir1" to
+                                Tree(
+                                    mapOf(
+                                        "test1.txt" to Blob("Hello World!"),
+                                    ),
+                                ),
+                            "dir2" to
+                                Tree(
+                                    mapOf(
+                                        "test2.txt" to Blob("This is a second file"),
+                                    ),
+                                ),
+                            "README.md" to Blob("# This is a test repo!"),
                         ),
-                    "README.md" to Blob("# This is a test repo!")
-                )
                     ),
                 author = Author("Gleb Koval", "gleb@koval.net"),
                 message = "Add README.md",
-            timestamp = Instant.ofEpochSecond(100)
-        )
+                timestamp = Instant.ofEpochSecond(100),
+            ),
         )
 
     @Test