Improve tests & validate FSEntry names (#4)

Contributes to #2 .

- Add some additional tests to existing functionality.
- Cleanup code to use more of `kotlin.io.*` instead of `java.nio.*`.
- Validate FSEntry names on object construction (and tests).
- Validate folders do not contain entries with duplicate names on `FSCreator.create()` (and tests).

Reviewed-on: #4

.editorconfig

@@ -10,4 +10,7 @@ max_line_length = 120
 tab_width = 4
 
 [{*.yaml,*.yml}]
-indent_size = 2
+indent_size = 2
+
+[{*.kt,*.kts}]
+ij_kotlin_packages_to_use_import_on_demand = org.junit.jupiter.api

.github/workflows/publish.yaml

@@ -30,11 +30,11 @@ jobs:
         run: |
           export VERSION="$(echo ${{ github.ref_name }} | cut -c2-)"
           echo "Parsed version: '$VERSION'"
-          echo "tinyvm_version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "filesystem_version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Publish to Gitea package repository
         env:
-          TINYVM_VERSION: ${{ steps.parse.outputs.tinyvm_version }}
+          FILESYSTEM_VERSION: ${{ steps.parse.outputs.filesystem_version }}
           GITEA_USERNAME: ${{ github.repository_owner }}
           GITEA_TOKEN: ${{ secrets.deploy_token }}
         run: ./gradlew publishAllPublicationsToGiteaRepository

README.md

@@ -3,6 +3,28 @@
 This is a small project to make a very basic filesystem library in Kotlin and was created using the instructions below
 as part of my application to the JetBrains internship project "TeamCity Kotlin Script build step extension library".
 
+The package is (very creatively) named `filesystem`.
+
+## Usage
+
+### Gradle
+```kotlin
+repositories {
+    // other repositories
+    maven { url "https://git.koval.net/api/packages/cyclane/maven" }
+}
+
+dependencies {
+    // other dependencies
+    implementation("net.koval.teamcity-build-step-extension-test-task:filesystem:0.1.0")
+}
+```
+
+### Documentation
+Use autocompletion and hover menus in your IDE, or download the
+[generated HTML documentation](https://git.koval.net/cyclane/teamcity-build-step-extension-test-task/releases/download/v0.1.0/filesystem-0.1.0-javadoc.zip)
+from the [latest release](https://git.koval.net/cyclane/teamcity-build-step-extension-test-task/releases).
+
 ## Instructions
 
 Create a library implementing four classes:

src/main/kotlin/filesystem/FSCreator.kt

@@ -1,30 +1,57 @@
 package filesystem
 
 import java.nio.file.FileAlreadyExistsException
-import java.nio.file.FileSystemException
-import java.nio.file.Files
-import java.nio.file.Path
+import kotlin.io.path.Path
+import kotlin.io.path.createDirectory
+import kotlin.io.path.createFile
+import kotlin.io.path.writeText
 
 class FSCreator {
-    // Create entry, leaving existing folders' contents, but overwriting existing files.
-    @Throws(FileSystemException::class)
-    fun create(entryToCreate: FSEntry, destination: String) {
-        val queue = ArrayDeque<Pair<FSEntry, Path>>()
-        queue.add(entryToCreate to Path.of(destination))
+    /**
+     * Create entry, leaving existing folders' contents, but overwriting existing files.
+     * @throws CyclicFolderException Cyclic folders cannot be created.
+     * @throws DuplicateEntryNameException A folder or sub-folder contains entries with duplicate names.
+     */
+    @Throws(CyclicFolderException::class, DuplicateEntryNameException::class)
+    fun create(
+        entryToCreate: FSEntry,
+        destination: String,
+    ) {
+        // No point in running anything if we know the input is invalid.
+        if (entryToCreate is FSFolder) {
+            if (entryToCreate.isCyclic()) {
+                throw CyclicFolderException()
+            }
+            if (entryToCreate.deepHasDuplicateNames()) {
+                throw DuplicateEntryNameException()
+            }
+        }
+
+        val queue =
+            ArrayDeque(
+                listOf(
+                    entryToCreate to Path(destination),
+                ),
+            )
 
         while (queue.isNotEmpty()) {
             val (entry, dest) = queue.removeFirst()
             val path = dest.resolve(entry.name)
             try {
                 when (entry) {
-                    is FSFile -> Files.createFile(path)
-                    is FSFolder -> Files.createDirectory(path)
+                    is FSFile -> path.createFile()
+                    is FSFolder -> path.createDirectory()
                 }
-            } catch (_: FileAlreadyExistsException) {} // Allow files/folders to already exist.
+            } catch (_: FileAlreadyExistsException) {
+            } // Allow files/folders to already exist.
             when (entry) {
-                is FSFile -> Files.write(path, entry.content.toByteArray())
+                is FSFile -> path.writeText(entry.content)
                 is FSFolder -> queue.addAll(entry.entries.map { it to path })
             }
         }
     }
-}
+}
+
+class CyclicFolderException : Exception("Cyclic FSFolders are not supported")
+
+class DuplicateEntryNameException : Exception("Folder contains entries with duplicate names")

src/main/kotlin/filesystem/FSEntry.kt

@@ -1,9 +1,59 @@
 package filesystem
 
+import kotlin.io.path.Path
+
 // Note sealed allows for simpler logic in FSCreator by guaranteeing FSFile and FSFolder are the only possible FSEntries
-// (as we expect), and it also makes the class abstract as required.
-sealed class FSEntry(val name: String)
+// (as we expect), and it also implicitly makes the class abstract as required.
+sealed class FSEntry(val name: String) {
+    init {
+        val p = Path(name)
+        // Only allow single filenames (no paths or relative references (e.g. ".."))
+        if (p.toList().size != 1 || p.fileName != p.toFile().canonicalFile.toPath().fileName) {
+            throw InvalidEntryNameException(name)
+        }
+    }
+}
 
-class FSFile(name: String, val content: String): FSEntry(name)
+class FSFile(name: String, val content: String) : FSEntry(name)
 
-class FSFolder(name: String, val entries: List<FSEntry>): FSEntry(name)
+class FSFolder(name: String, val entries: List<FSEntry>) : FSEntry(name) {
+    /**
+     * Check whether a folder is cyclic.
+     */
+    fun isCyclic(): Boolean {
+        val seen = listOf(this).toHashSet<FSEntry>()
+        val queue = ArrayDeque(entries)
+        while (queue.isNotEmpty()) {
+            val entry = queue.removeFirst()
+            if (!seen.add(entry)) {
+                return true
+            }
+            if (entry is FSFolder) {
+                queue.addAll(entry.entries)
+            }
+        }
+        return false
+    }
+
+    /**
+     * Check whether a folder contains multiple entries with the same name.
+     */
+    fun hasDuplicateNames(): Boolean {
+        val seen = HashSet<String>()
+        return entries.any { !seen.add(it.name) }
+    }
+
+    internal fun deepHasDuplicateNames(): Boolean {
+        val queue = ArrayDeque(listOf(this))
+        while (queue.isNotEmpty()) {
+            val entry = queue.removeFirst()
+            if (entry.hasDuplicateNames()) {
+                return true
+            }
+            queue.addAll(entry.entries.mapNotNull { it as? FSFolder })
+        }
+        return false
+    }
+}
+
+class InvalidEntryNameException(name: String) : Exception("Invalid FSEntry name: '$name'")

src/test/kotlin/filesystem/FSCreatorTest.kt

@@ -1,10 +1,10 @@
 package filesystem
 
 import org.junit.jupiter.api.*
-import java.nio.file.FileSystemException
-import java.nio.file.Files
-import java.nio.file.Path
+import java.io.File
 import java.util.concurrent.TimeUnit
+import kotlin.io.path.Path
+import kotlin.io.path.createDirectory
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
@@ -14,90 +14,173 @@ class FSCreatorTest {
     @BeforeEach
     fun `before each`() {
         assertDoesNotThrow("should create _tmp directory") {
-            Files.createDirectory(Path.of("_tmp"))
+            Path("_tmp").createDirectory()
         }
     }
 
     @AfterEach
     fun `after each`() {
         assertDoesNotThrow("should delete _tmp directory") {
-            deleteRecursive(Path.of("_tmp"))
+            File("_tmp").deleteRecursively()
         }
     }
 
+    @Test
+    fun `create file`() {
+        val file = FSFile("test.txt", "This is a file")
+        assertDoesNotThrow("should create file") {
+            creator.create(file, "_tmp")
+        }
+        assertEquals(file.content, File("_tmp/", file.name).readText())
+    }
+
     @Test
     fun `create entries`() {
         val readme = FSFile("README", "Hello World!")
         val gomod = FSFile("go.mod", "module example.com/hello-world\n\ngo1.21.5")
-        val maingo = FSFile("main.go", "package main\n\nimport \"example.com/hello-world/utils\"\n\n" +
-            "func main() {\n\tprintln(\"Hello World!\")\n}")
-        val helloworldgo = FSFile("hello-world.go", "package utils\n\nfunc PrintHelloWorld() {\n" +
-            "\tprintln(\"Hello World!\")\n}")
+        val maingo =
+            FSFile(
+                "main.go",
+                "package main\n\nimport \"example.com/hello-world/utils\"\n\n" +
+                    "func main() {\n\tprintln(\"Hello World!\")\n}",
+            )
+        val helloworldgo =
+            FSFile(
+                "hello-world.go",
+                "package utils\n\nfunc PrintHelloWorld() {\n" +
+                    "\tprintln(\"Hello World!\")\n}",
+            )
         assertDoesNotThrow("should create entries") {
-            creator.create(FSFolder("folder", listOf(
-                readme,
-                gomod,
-                maingo,
-                FSFolder("utils", listOf(
-                    helloworldgo
-                ))
-            )), "_tmp")
+            creator.create(
+                FSFolder(
+                    "folder",
+                    listOf(
+                        readme,
+                        gomod,
+                        maingo,
+                        FSFolder(
+                            "utils",
+                            listOf(
+                                helloworldgo,
+                            ),
+                        ),
+                    ),
+                ),
+                "_tmp",
+            )
         }
         // If objects don't exist, these functions will throw anyway, so don't explicitly check for existence.
         // Similarly, don't explicitly check if an object is a directory.
-        assertEquals(readme.content, Files.readString(Path.of("_tmp/folder", readme.name)))
-        assertEquals(gomod.content, Files.readString(Path.of("_tmp/folder", gomod.name)))
-        assertEquals(maingo.content, Files.readString(Path.of("_tmp/folder", maingo.name)))
-        assertEquals(helloworldgo.content, Files.readString(Path.of("_tmp/folder/utils", helloworldgo.name)))
+        assertEquals(readme.content, File("_tmp/folder", readme.name).readText())
+        assertEquals(gomod.content, File("_tmp/folder", gomod.name).readText())
+        assertEquals(maingo.content, File("_tmp/folder", maingo.name).readText())
+        assertEquals(helloworldgo.content, File("_tmp/folder/utils", helloworldgo.name).readText())
     }
 
     @Test
     fun `create existing entries`() {
         assertDoesNotThrow("creation one") {
-            creator.create(FSFolder("folder", listOf(
-                FSFolder("sub-folder", listOf(
-                    FSFile("hi", "hi")
-                )),
-                FSFolder("another-folder", listOf()),
-                FSFile("1.txt", "One!"),
-                FSFile("2.txt", "Two!")
-            )), "_tmp")
+            creator.create(
+                FSFolder(
+                    "folder",
+                    listOf(
+                        FSFolder(
+                            "sub-folder",
+                            listOf(
+                                FSFile("hi", "hi"),
+                            ),
+                        ),
+                        FSFolder("folder", listOf()),
+                        FSFile("1.txt", "One!"),
+                        FSFile("2.txt", "Two!"),
+                    ),
+                ),
+                "_tmp",
+            )
         }
         assertDoesNotThrow("creation two") {
-            creator.create(FSFolder("folder", listOf(
-                FSFolder("another-folder", listOf(
-                    FSFolder("secrets", listOf(
-                        FSFile("secret", "P4ssW0rd")
-                    ))
-                )),
-                FSFile("1.txt", "One is a good number"),
-                FSFile("3.txt", "Three!")
-            )), "_tmp")
+            creator.create(
+                FSFolder(
+                    "folder",
+                    listOf(
+                        FSFolder(
+                            // Repeated name should be fine here (not throw)
+                            "folder",
+                            listOf(
+                                FSFolder(
+                                    "secrets",
+                                    listOf(
+                                        FSFile("secret", "P4ssW0rd"),
+                                    ),
+                                ),
+                            ),
+                        ),
+                        FSFile("1.txt", "One is a good number"),
+                        FSFile("3.txt", "Three!"),
+                    ),
+                ),
+                "_tmp",
+            )
         }
-        assertEquals("hi", Files.readString(Path.of("_tmp/folder/sub-folder/hi")))
-        assertEquals("P4ssW0rd", Files.readString(Path.of("_tmp/folder/another-folder/secrets/secret")))
-        assertEquals("One is a good number", Files.readString(Path.of("_tmp/folder/1.txt")))
-        assertEquals("Two!", Files.readString(Path.of("_tmp/folder/2.txt")))
-        assertEquals("Three!", Files.readString(Path.of("_tmp/folder/3.txt")))
+        assertEquals("hi", File("_tmp/folder/sub-folder/hi").readText())
+        assertEquals("P4ssW0rd", File("_tmp/folder/folder/secrets/secret").readText())
+        assertEquals("One is a good number", File("_tmp/folder/1.txt").readText())
+        assertEquals("Two!", File("_tmp/folder/2.txt").readText())
+        assertEquals("Three!", File("_tmp/folder/3.txt").readText())
     }
 
     @Test
-    @Timeout(500, unit = TimeUnit.MILLISECONDS) // in case implementation starts trying to handle recursion
-    fun `create throws on recursive folder`() {
+    @Timeout(500, unit = TimeUnit.MILLISECONDS) // in case implementation starts trying to handle cyclic folders
+    fun `create throws on cyclic folder`() {
         val files = mutableListOf<FSEntry>()
         val folder = FSFolder("folder", files)
         files.add(folder)
-        assertThrows<FileSystemException> {
+        assertThrows<CyclicFolderException> {
             creator.create(folder, "_tmp")
         }
     }
-}
 
-fun deleteRecursive(path: Path) {
-    if (Files.isDirectory(path)) {
-        for (child in Files.list(path)) {
-            deleteRecursive(child)
+    @Test
+    @Timeout(500, unit = TimeUnit.MILLISECONDS)
+    fun `create throws on long cyclic folder`() {
+        val files = mutableListOf<FSEntry>()
+        val folder1 = FSFolder("folder", files)
+        val folder2 = FSFolder("folder2", listOf(folder1))
+        val folder3 = FSFolder("folder3", listOf(folder2))
+        val folder4 = FSFolder("folder4", listOf(folder3))
+        files.add(folder4)
+        assertThrows<CyclicFolderException> {
+            creator.create(folder4, "_tmp")
+        }
+    }
+
+    @Test
+    fun `create throws on folder with duplicate names`() {
+        val folder =
+            FSFolder(
+                "folder",
+                listOf(
+                    FSFile("README.md", "# Test File"),
+                    FSFile("hello-world.txt", "Hello World!"),
+                    FSFolder(
+                        "src",
+                        listOf(
+                            FSFile("README.md", "# Source files"),
+                            FSFolder(
+                                "solution",
+                                listOf(
+                                    FSFile("solution.py", "print('1 + 1 = 1')"),
+                                    FSFile("tmp", "A temporary file"),
+                                    FSFolder("tmp", listOf()),
+                                ),
+                            ),
+                        ),
+                    ),
+                    FSFolder("tmp", listOf()),
+                ),
+            )
+        assertThrows<DuplicateEntryNameException> {
+            creator.create(folder, "_tmp")
         }
     }
-    Files.delete(path)
 }

src/test/kotlin/filesystem/FSEntryTest.kt

@@ -0,0 +1,136 @@
+package filesystem
+
+import org.junit.jupiter.api.*
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class FSEntryTest {
+    @Test
+    fun `valid name entries`() {
+        assertDoesNotThrow("should construct FSFile and FSFolder without throwing") {
+            FSFile("A file with a name.tar.xz", "Contents")
+            FSFolder(".a folder with a name", listOf())
+        }
+    }
+
+    @Test
+    fun `invalid name entries`() {
+        assertThrows<InvalidEntryNameException> {
+            FSFile("File/here", "Contents")
+        }
+        assertThrows<InvalidEntryNameException> {
+            FSFolder("Folder/here", listOf())
+        }
+        assertThrows<InvalidEntryNameException> {
+            FSFolder(".", listOf())
+        }
+        assertThrows<InvalidEntryNameException> {
+            FSFolder("/", listOf())
+        }
+    }
+
+    @Test
+    fun `non-cyclic folder`() {
+        val folder =
+            FSFolder(
+                "folder",
+                listOf(
+                    FSFolder("folder", listOf()),
+                    FSFile("text.txt", "Hello!"),
+                ),
+            )
+        assertFalse(folder.isCyclic())
+    }
+
+    @Test
+    fun `cyclic folder`() {
+        val files = mutableListOf<FSEntry>()
+        val folder = FSFolder("folder", files)
+        files.add(folder)
+        assertTrue(folder.isCyclic())
+    }
+
+    @Test
+    fun `long cyclic folder`() {
+        val files = mutableListOf<FSEntry>()
+        val folder1 = FSFolder("folder", files)
+        val folder2 = FSFolder("folder2", listOf(folder1))
+        val folder3 = FSFolder("folder3", listOf(folder2))
+        val folder4 = FSFolder("folder4", listOf(folder3))
+        files.add(folder4)
+        assertTrue(folder1.isCyclic())
+        assertTrue(folder2.isCyclic())
+        assertTrue(folder3.isCyclic())
+        assertTrue(folder4.isCyclic())
+    }
+
+    @Test
+    fun `no duplicate names folder`() {
+        val folder =
+            FSFolder(
+                "folder",
+                listOf(
+                    FSFile("README.md", "# Test File"),
+                    FSFile("hello-world.txt", "Hello World!"),
+                    FSFolder(
+                        "src",
+                        listOf(
+                            FSFile("README.md", "# Source files"),
+                            FSFile("solution-1.py", "print('1 + 1 = 1')"),
+                            FSFile("solution-2.py", "print('1 + 1 = 1')"),
+                        ),
+                    ),
+                    FSFolder("tmp", listOf()),
+                ),
+            )
+        assertFalse(folder.hasDuplicateNames())
+        assertFalse(folder.deepHasDuplicateNames())
+    }
+
+    @Test
+    fun `shallow duplicate names folder`() {
+        val folder =
+            FSFolder(
+                "folder",
+                listOf(
+                    FSFile("README.md", "# Test File"),
+                    FSFile("hello-world.txt", "Hello World!"),
+                    FSFolder(
+                        "src",
+                        listOf(
+                            FSFile("README.md", "# Source files"),
+                            FSFile("solution-1.py", "print('1 + 1 = 1')"),
+                            FSFile("solution-2.py", "print('1 + 1 = 1')"),
+                        ),
+                    ),
+                    FSFolder("tmp", listOf()),
+                    FSFile("tmp", "A temporary file"),
+                ),
+            )
+        assertTrue(folder.hasDuplicateNames())
+        assertTrue(folder.deepHasDuplicateNames())
+    }
+
+    @Test
+    fun `deep duplicate names folder`() {
+        val folder =
+            FSFolder(
+                "folder",
+                listOf(
+                    FSFile("README.md", "# Test File"),
+                    FSFile("hello-world.txt", "Hello World!"),
+                    FSFolder(
+                        "src",
+                        listOf(
+                            FSFile("README.md", "# Source files"),
+                            FSFile("solution-1.py", "print('1 + 1 = 1')"),
+                            FSFile("solution-1.py", "print('1 + 1 = 1')"),
+                        ),
+                    ),
+                    FSFolder("tmp", listOf()),
+                ),
+            )
+        assertFalse(folder.hasDuplicateNames())
+        assertTrue(folder.deepHasDuplicateNames())
+    }
+}