Fix README and test for throws on branch not found.

Closes #6.

Implements branch support by _only extending_ the existing functionality. Note that the existing functionality DOES NOT implement a `parent` pointer for commits, and as a result branches are also implemented differently to how git implements them.

git branches are simply a named pointer to a commit object (which then has a pointer to its parent commit), here branches store the entire sequence of pointers to commit objects.

### Why different to git?
I made a mistake in the initial implementation by using a `TreeSet` instead of manually implementing a tree for commits. This allowed the ability to insert commits in-between other commits, which isn't normally possible in `git` _without rebasing which changes commits' hashes_.

The specification for this feature stated:
> All functionality that is implemented already should be preserved.

And so since I cannot remove this functionality any more, I have to build on top of it.

Reviewed-on: #7

.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

@@ -1,9 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
+  <component name="GradleMigrationSettings" migrationVersion="1" />
   <component name="GradleSettings">
     <option name="linkedExternalProjectsSettings">
       <GradleProjectSettings>
         <option name="externalProjectPath" value="$PROJECT_DIR$" />
+        <option name="gradleJvm" value="corretto-19" />
         <option name="modules">
           <set>
             <option value="$PROJECT_DIR$" />

.idea/misc.xml

@@ -4,7 +4,11 @@
   <component name="FrameworkDetectionExcludesConfiguration">
     <file type="web" url="file://$PROJECT_DIR$" />
   </component>
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" project-jdk-name="corretto-19" project-jdk-type="JavaSDK">
+  <component name="PWA">
+    <option name="enabled" value="true" />
+    <option name="wasEnabledAtLeastOnce" value="true" />
+  </component>
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_17" project-jdk-name="openjdk-21" project-jdk-type="JavaSDK">
     <output url="file://$PROJECT_DIR$/out" />
   </component>
 </project>

README.md

@@ -3,11 +3,33 @@
 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".
 
+The package is named `tinyvm` for 'tiny version manager'.
+
 ## Assumptions
 
 Since this is an internship application project, I have assumed that a minimal usage of external libraries is preferred,
 so that a greater technical understanding can be demonstrated.
 
+## Usage
+
+### Gradle
+```kotlin
+repositories {
+    // other repositories
+    maven { url "https://git.koval.net/api/packages/cyclane/maven" }
+}
+
+dependencies {
+    // other dependencies
+    implementation("net.koval.teamcity-gitea-test-task:tinyvm:0.1.1")
+}
+```
+
+### Documentation
+Use autocompletion and hover menus in your IDE, or download the
+generated HTML documentation
+from the [latest release](https://git.koval.net/cyclane/teamcity-gitea-test-task/releases).
+
 ## Instructions
 
 Create a library that implements simple Git functionality. You need to implement at least three entities:

build.gradle.kts

@@ -1,9 +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()
@@ -18,5 +21,48 @@ tasks.test {
 }
 
 kotlin {
-    jvmToolchain(8)
+    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

@@ -0,0 +1,25 @@
+package tinyvm
+
+import java.time.Instant
+
+/**
+ * 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,
+) : Object("commit") {
+    override val data: String
+        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,
+) {
+    override fun toString(): String = "$name <$email>"
+}

src/main/kotlin/tinyvm/Object.kt

@@ -0,0 +1,17 @@
+package tinyvm
+
+import java.security.MessageDigest
+import java.util.HexFormat
+
+/**
+ * Represents an arbitrary version manager object.
+ */
+abstract class Object(val type: String) {
+    abstract val data: String
+
+    fun hash(): String =
+        HexFormat.of().formatHex(
+            MessageDigest.getInstance("SHA-1")
+                .digest("$type ${data.length}\u0000$data".toByteArray()),
+        )
+}

src/main/kotlin/tinyvm/Repository.kt

@@ -0,0 +1,131 @@
+package tinyvm
+
+import java.util.TreeSet
+
+class HashCollisionException(hash: String) : Exception("Different object types with identical hash '$hash'")
+
+private class CommitTimeComparator : Comparator<Commit> {
+    override fun compare(
+        o1: Commit,
+        o2: Commit,
+    ): Int = (o1.timestamp.epochSecond - o2.timestamp.epochSecond).toInt()
+}
+
+private val commitTimeComparator = CommitTimeComparator()
+
+private class Branch(val name: String, val commits: TreeSet<Commit>)
+
+class Repository(initialBranch: String = "master") {
+    private var head = Branch(initialBranch, sortedSetOf(commitTimeComparator))
+    private val commits = mutableMapOf(initialBranch to head)
+
+    val branch: String
+        get() = head.name
+
+    val branches: Set<String>
+        get() = commits.keys
+
+    // Store all objects in one map like git does. This would simplify the data persistence implementation (if there was
+    // one) and allows for other objects to be added in the future without modifying the data persistence implementation
+    // at all.
+    private val objects = mutableMapOf<String, Object>()
+
+    /**
+     * Create a new branch as a copy of the current branch.
+     * @param name New branch name.
+     * @param use Whether to switch to this branch.
+     */
+    fun createBranch(
+        name: String,
+        use: Boolean = true,
+    ) {
+        commits[name] =
+            Branch(
+                name,
+                head.commits.clone() as? TreeSet<Commit> ?: throw Exception("TreeSet.clone() unexpected result"),
+            )
+        if (use) useBranch(name)
+    }
+
+    /**
+     * Use (switch to) a branch.
+     */
+    fun useBranch(name: String) {
+        head = commits[name] ?: throw BranchNotFoundException(name)
+    }
+
+    /**
+     * (Deep) get or put a commit object into the repository.
+     * This will also get or put all child trees and blobs.
+     */
+    fun commit(commit: Commit): Commit {
+        val hash = commit.hash()
+        val obj = findObject<Commit>(hash)
+        if (obj != null) return obj
+        val newCommit =
+            Commit(
+                tree = addTree(commit.tree),
+                author = commit.author,
+                message = commit.message,
+                timestamp = commit.timestamp,
+            )
+        objects[hash] = newCommit
+        head.commits.add(newCommit)
+        return newCommit
+    }
+
+    /**
+     * Get a commit by its hash.
+     */
+    fun getCommit(hash: String): Commit? = findObject<Commit>(hash)
+
+    /**
+     * List all commits.
+     */
+    fun listCommits(): List<Commit> = head.commits.toList()
+
+    /**
+     * Find commit.
+     */
+    fun findCommit(predicate: (Commit) -> Boolean): Commit? = head.commits.find(predicate)
+
+    /**
+     * Dump repository objects
+     */
+    fun dumpObjects(): Map<String, Object> = objects
+
+    /**
+     * (Deep) get or put a tree object into the repository.
+     * This will also get or put all child trees and blobs.
+     */
+    private fun addTree(tree: Tree): Tree {
+        val hash = tree.hash()
+        val obj = findObject<Tree>(hash)
+        if (obj != null) return obj
+        val newTree =
+            Tree(
+                tree.nodes.map { (name, node) ->
+                    when (node) {
+                        is Tree -> name to addTree(node)
+                        is Blob -> name to addObject(node)
+                    }
+                }.toMap(),
+            )
+        objects[hash] = newTree
+        return tree
+    }
+
+    /**
+     * (Shallow) get or put an object into the repository.
+     */
+    private inline fun <reified T : Object> addObject(obj: T): T =
+        objects.getOrPut(obj.hash()) { obj } as? T ?: throw HashCollisionException(obj.hash())
+
+    /**
+     * Find an object in the repository by its hash.
+     */
+    private inline fun <reified T : Object> findObject(hash: String): T? =
+        objects[hash]?.let { it as? T ?: throw HashCollisionException(hash) }
+}
+
+class BranchNotFoundException(name: String) : Exception("Branch '$name' does not exist")

src/main/kotlin/tinyvm/Tree.kt

@@ -0,0 +1,36 @@
+package tinyvm
+
+/**
+ * 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) ->
+                "${node.type} $name\u0000${node.hash()}"
+            }.sorted().joinToString()
+
+    override fun toString(): String =
+        "tree ${hash()}\n" +
+            nodes.map { (name, node) ->
+                when (node) {
+                    is Tree -> "+$name/\n"
+                    is Blob -> "+$name\n"
+                } + node.toString().insertLeftMargin()
+            }.sorted().joinToString("\n")
+}
+
+/**
+ * A blob is a data container.
+ */
+class Blob(override val data: String) : Node("blob") {
+    override fun toString(): String = "blob ${hash()}\n${data.insertLeftMargin()}"
+}
+
+private fun String.insertLeftMargin(): String = split('\n').joinToString("\n") { "| $it" }

src/test/kotlin/tinyvm/RepositoryTest.kt

@@ -0,0 +1,192 @@
+package tinyvm
+
+import org.junit.jupiter.api.assertThrows
+import java.time.Instant
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+internal class RepositoryTest {
+    private val repository = Repository()
+    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(
+                            "dir2" to
+                                Tree(
+                                    mapOf(
+                                        "test1.txt" to Blob("This is a second file"),
+                                    ),
+                                ),
+                            "dir1" to
+                                Tree(
+                                    mapOf(
+                                        "test1.txt" to Blob("Hello World!"),
+                                    ),
+                                ),
+                        ),
+                    ),
+                author = Author("Gleb Koval", "gleb@koval.net"),
+                message = "Move test1.txt to dir1 and add dir2/test1.txt",
+                timestamp = Instant.ofEpochSecond(50),
+            ),
+            Commit(
+                tree =
+                    Tree(
+                        mapOf(
+                            "dir1" to
+                                Tree(
+                                    mapOf(
+                                        "test1.txt" to Blob("Hello World!"),
+                                    ),
+                                ),
+                            "dir2" to
+                                Tree(
+                                    mapOf(
+                                        "test1.txt" to Blob("This is a second file"),
+                                    ),
+                                ),
+                            "README.md" to Blob("# This is a test repo!"),
+                        ),
+                    ),
+                author = Author("Gleb Koval", "gleb@koval.net"),
+                message = "Add README.md",
+                timestamp = Instant.ofEpochSecond(100),
+            ),
+        )
+
+    @Test
+    fun `can commit`() {
+        val committed = repository.commit(commits[0])
+        assertEquals(commits[0].hash(), committed.hash())
+        assertEquals(1, repository.listCommits().size)
+        assertEquals(3, repository.dumpObjects().size)
+    }
+
+    @Test
+    fun `can deduplicate commit`() {
+        repository.commit(commits[0])
+        assertEquals(1, repository.listCommits().size)
+        val committed = repository.commit(commits[0])
+        assertEquals(1, repository.listCommits().size)
+        assertEquals(3, repository.dumpObjects().size)
+        assertEquals(commits[0].hash(), committed.hash())
+    }
+
+    @Test
+    fun `can commit twice and deduplicate objects`() {
+        repository.commit(commits[0])
+        val committed = repository.commit(commits[1])
+        assertEquals(2, repository.listCommits().size)
+        assertEquals(7, repository.dumpObjects().size)
+        assertEquals(commits[1].hash(), committed.hash())
+        assertEquals(commits.take(2).map { it.hash() }, repository.listCommits().map { it.hash() })
+    }
+
+    @Test
+    fun `can commit in-between existing commits`() {
+        repository.commit(commits[0])
+        repository.commit(commits[2])
+        val committed = repository.commit(commits[1])
+        assertEquals(3, repository.listCommits().size)
+        assertEquals(10, repository.dumpObjects().size)
+        assertEquals(commits[1].hash(), committed.hash())
+        assertEquals(commits.map { it.hash() }, repository.listCommits().map { it.hash() })
+    }
+
+    @Test
+    fun `can get commit by hash`() {
+        repository.commit(commits[0])
+        val committed = repository.commit(commits[1])
+        repository.commit(commits[2])
+        assertEquals(committed, repository.getCommit(commits[1].hash()))
+        assertEquals(null, repository.getCommit("00000000000000000000"))
+    }
+
+    @Test
+    fun `can find commit by predicate`() {
+        repository.commit(commits[0])
+        val committed = repository.commit(commits[1])
+        repository.commit(commits[2])
+        assertEquals(committed, repository.findCommit { it.message.matches("Move.*".toRegex()) })
+        assertEquals(null, repository.getCommit("00000000000000000000"))
+    }
+
+    @Test
+    fun `can create and use branch`() {
+        repository.commit(commits[0])
+        repository.commit(commits[1])
+        repository.commit(commits[2])
+        repository.createBranch("test-branch", use = false)
+        assertEquals("master", repository.branch)
+        repository.createBranch("test-branch-2")
+        assertEquals("test-branch-2", repository.branch)
+        assertEquals(setOf("master", "test-branch", "test-branch-2"), repository.branches)
+        assertEquals(commits.map { it.hash() }, repository.listCommits().map { it.hash() })
+        assertEquals(10, repository.dumpObjects().size)
+    }
+
+    @Test
+    fun `cannot use non-existent branch`() {
+        assertThrows<BranchNotFoundException> {
+            repository.useBranch("test-branch")
+        }
+    }
+
+    @Test
+    fun `can commit to branch`() {
+        repository.commit(commits[0])
+        repository.createBranch("test-branch")
+        repository.commit(commits[1])
+        repository.createBranch("test-branch-2")
+        repository.commit(commits[2])
+
+        assertEquals(commits.map { it.hash() }, repository.listCommits().map { it.hash() })
+        repository.useBranch("test-branch")
+        assertEquals(commits.take(2).map { it.hash() }, repository.listCommits().map { it.hash() })
+        repository.useBranch("master")
+        assertEquals(commits.take(1).map { it.hash() }, repository.listCommits().map { it.hash() })
+    }
+
+    @Test
+    fun `can display commit`() {
+        assertEquals(
+            """
+            commit 804c6f0c66da0ea0eab8ac29f23a627e03a962b2
+            tree aaebbb258bce30749fc302cbd161b78462252a32
+            author Gleb Koval <gleb@koval.net>
+            timestamp 0
+            
+            Add test1.txt
+            """.trimIndent(),
+            commits[0].toString(),
+        )
+    }
+
+    @Test
+    fun `can display tree`() {
+        assertEquals(
+            """
+            tree 048b8e267dd7a6c5d4849d59f6ff82e6ae948f13
+            +dir1/
+            | tree aaebbb258bce30749fc302cbd161b78462252a32
+            | +test1.txt
+            | | blob c57eff55ebc0c54973903af5f72bac72762cf4f4
+            | | | Hello World!
+            +dir2/
+            | tree 0e14cbdba02924cd63a58c2492fc3dd05dc682bd
+            | +test1.txt
+            | | blob da3fcc31cbc16fcbb7526d68771f77e7e7f02fb1
+            | | | This is a second file
+            """.trimIndent(),
+            commits[1].tree.toString(),
+        )
+    }
+}