feat: todo annotation

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/codegen/PythonCodeGenerator.kt

@@ -117,10 +117,14 @@ fun PythonAttribute.toPythonCode() = buildString {
 }
 
 fun PythonClass.toPythonCode() = buildString {
+    val todoComment = todoComment(todo)
     val docstring = docstring()
     val constructorString = constructor?.toPythonCode() ?: ""
     val methodsString = methods.joinToString("\n\n") { it.toPythonCode() }
 
+    if (todoComment.isNotBlank()) {
+        appendLine(todoComment)
+    }
     appendLine("class $name:")
     if (docstring.isNotBlank()) {
         appendIndented("\"\"\"\n")
@@ -143,6 +147,7 @@ fun PythonClass.toPythonCode() = buildString {
 }
 
 fun PythonConstructor.toPythonCode() = buildString {
+    val todoComment = todoComment(todo)
     val parametersString = parameters.toPythonCode()
     val boundariesString = parameters
         .mapNotNull { it.boundary?.toPythonCode(it.name) }
@@ -155,6 +160,9 @@ fun PythonConstructor.toPythonCode() = buildString {
         ?.let { "self.instance = ${it.toPythonCode()}" }
         ?: ""
 
+    if (todoComment.isNotBlank()) {
+        appendLine(todoComment)
+    }
     appendLine("def __init__($parametersString):")
     if (boundariesString.isNotBlank()) {
         appendIndented(boundariesString)
@@ -202,6 +210,7 @@ fun PythonEnumInstance.toPythonCode(enumName: String): String {
 }
 
 fun PythonFunction.toPythonCode() = buildString {
+    val todoComment = todoComment(todo)
     val parametersString = parameters.toPythonCode()
     val docstring = docstring()
     val boundariesString = parameters
@@ -211,6 +220,9 @@ fun PythonFunction.toPythonCode() = buildString {
         ?.let { "return ${it.toPythonCode()}" }
         ?: ""
 
+    if (todoComment.isNotBlank()) {
+        appendLine(todoComment)
+    }
     if (isStaticMethod()) {
         appendLine("@staticmethod")
     }
@@ -357,3 +369,18 @@ fun Boundary.toPythonCode(parameterName: String) = buildString {
         appendIndented("raise ValueError(f'Valid values of $parameterName must be less than or equal to $upperIntervalLimit, but {$parameterName} was assigned.')")
     }
 }
+
+fun todoComment(message: String) = buildString {
+    if (message.isBlank()) {
+        return ""
+    }
+
+    val lines = message.lines()
+    val firstLine = lines.first()
+    val remainingLines = lines.drop(1)
+
+    appendLine("# TODO: $firstLine")
+    remainingLines.forEach {
+        appendIndented(it, indent = " ".repeat(8))
+    }
+}

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/codegen/Util.kt

@@ -11,13 +11,7 @@ internal fun String.prependIndentUnlessBlank(indent: String = "    "): String {
         .joinToString("\n")
 }
 
-internal fun StringBuilder.appendIndented(init: StringBuilder.() -> Unit): StringBuilder {
-    val stringToIndent = StringBuilder().apply(init).toString()
-    append(stringToIndent.prependIndentUnlessBlank())
-    return this
-}
-
-internal fun StringBuilder.appendIndented(value: String): StringBuilder {
-    append(value.prependIndentUnlessBlank())
+internal fun StringBuilder.appendIndented(value: String, indent: String = "    "): StringBuilder {
+    append(value.prependIndentUnlessBlank(indent))
     return this
 }

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/model/editorAnnotations.kt

@@ -128,6 +128,12 @@ object RequiredAnnotation : EditorAnnotation() {
     override val validTargets = PARAMETERS
 }
 
+@Serializable
+data class TodoAnnotation(val message: String) : EditorAnnotation() {
+    @Transient
+    override val validTargets = ANY_DECLARATION
+}
+
 @Serializable
 sealed class DefaultValue
 
@@ -179,7 +185,6 @@ val ANY_DECLARATION = setOf(
     FUNCTION_PARAMETER
 )
 val GLOBAL_DECLARATIONS = setOf(CLASS, GLOBAL_FUNCTION)
-val CLASSES = setOf(CLASS)
 val FUNCTIONS = setOf(GLOBAL_FUNCTION, METHOD)
 val PARAMETERS = setOf(
     CONSTRUCTOR_PARAMETER,

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/mutable_model/PythonAst.kt

@@ -62,6 +62,7 @@ class PythonClass(
     methods: List<PythonFunction> = emptyList(),
     var isPublic: Boolean = true,
     var description: String = "",
+    var todo: String = "",
     override val annotations: MutableList<EditorAnnotation> = mutableListOf(),
     var originalClass: OriginalPythonClass? = null
 ) : PythonDeclaration() {
@@ -81,7 +82,8 @@ class PythonClass(
 
 class PythonConstructor(
     parameters: List<PythonParameter> = emptyList(),
-    val callToOriginalAPI: PythonCall? = null
+    val callToOriginalAPI: PythonCall? = null,
+    var todo: String = ""
 ) : PythonAstNode() {
 
     val parameters = MutableContainmentList(parameters)
@@ -126,6 +128,7 @@ class PythonFunction(
     results: List<PythonResult> = emptyList(),
     var isPublic: Boolean = true,
     var description: String = "",
+    var todo: String = "",
     var isPure: Boolean = false,
     override val annotations: MutableList<EditorAnnotation> = mutableListOf(),
     var callToOriginalAPI: PythonCall? = null

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/transformation/TodoAnnotationProcessor.kt

@@ -0,0 +1,32 @@
+package com.larsreimann.api_editor.transformation
+
+import com.larsreimann.api_editor.model.TodoAnnotation
+import com.larsreimann.api_editor.mutable_model.PythonClass
+import com.larsreimann.api_editor.mutable_model.PythonDeclaration
+import com.larsreimann.api_editor.mutable_model.PythonFunction
+import com.larsreimann.api_editor.mutable_model.PythonPackage
+import com.larsreimann.modeling.descendants
+
+/**
+ * Processes and removes `@todo` annotations.
+ */
+fun PythonPackage.processTodoAnnotations() {
+    this.descendants()
+        .filterIsInstance<PythonDeclaration>()
+        .forEach { it.processTodoAnnotations() }
+}
+
+private fun PythonDeclaration.processTodoAnnotations() {
+    this.annotations
+        .filterIsInstance<TodoAnnotation>()
+        .forEach {
+            when (this) {
+                is PythonClass -> this.todo = it.message
+                is PythonFunction -> this.todo = it.message
+                else -> {
+                    // Do nothing
+                }
+            }
+            this.annotations.remove(it)
+        }
+}

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/transformation/TransformationPlan.kt

@@ -29,6 +29,7 @@ private fun PythonPackage.preprocess(newPackageName: String) {
 private fun PythonPackage.processAnnotations() {
     processRemoveAnnotations()
     processDescriptionAnnotations()
+    processTodoAnnotations()
     processRenameAnnotations()
     processMoveAnnotations()
     processBoundaryAnnotations()

api-editor/backend/src/main/kotlin/com/larsreimann/api_editor/validation/AnnotationValidator.kt

@@ -181,8 +181,8 @@ class AnnotationValidator(private val annotatedPythonPackage: SerializablePython
 
     companion object {
         private var possibleCombinations = buildMap<String, Set<String>> {
-            this["Attribute"] = mutableSetOf("Description", "Rename")
-            this["Boundary"] = mutableSetOf("Description", "Group", "Optional", "Rename", "Required")
+            this["Attribute"] = mutableSetOf("Description", "Rename", "Todo")
+            this["Boundary"] = mutableSetOf("Description", "Group", "Optional", "Rename", "Required", "Todo")
             this["CalledAfter"] = mutableSetOf("CalledAfter", "Description", "Group", "Move", "Pure", "Rename")
             this["Constant"] = mutableSetOf()
             this["Description"] = mutableSetOf(
@@ -195,9 +195,10 @@ class AnnotationValidator(private val annotatedPythonPackage: SerializablePython
                 "Optional",
                 "Pure",
                 "Rename",
-                "Required"
+                "Required",
+                "Todo"
             )
-            this["Enum"] = mutableSetOf("Description", "Group", "Rename", "Required")
+            this["Enum"] = mutableSetOf("Description", "Group", "Rename", "Required", "Todo")
             this["Group"] =
                 mutableSetOf(
                     "Boundary",
@@ -209,10 +210,11 @@ class AnnotationValidator(private val annotatedPythonPackage: SerializablePython
                     "Optional",
                     "Pure",
                     "Rename",
-                    "Required"
+                    "Required",
+                    "Todo"
                 )
             this["Move"] = mutableSetOf("CalledAfter", "Description", "Group", "Pure", "Rename")
-            this["Optional"] = mutableSetOf("Boundary", "Description", "Group", "Rename")
+            this["Optional"] = mutableSetOf("Boundary", "Description", "Group", "Rename", "Todo")
             this["Pure"] = mutableSetOf("CalledAfter", "Description", "Group", "Move", "Rename")
             this["Remove"] = mutableSetOf()
             this["Rename"] = mutableSetOf(
@@ -225,9 +227,19 @@ class AnnotationValidator(private val annotatedPythonPackage: SerializablePython
                 "Move",
                 "Optional",
                 "Pure",
+                "Required", "Todo"
+            )
+            this["Required"] = mutableSetOf("Boundary", "Description", "Enum", "Group", "Rename", "Todo")
+            this["Todo"] = mutableSetOf(
+                "Attribute",
+                "Boundary",
+                "Description",
+                "Enum",
+                "Group",
+                "Optional",
+                "Rename",
                 "Required"
             )
-            this["Required"] = mutableSetOf("Boundary", "Description", "Enum", "Group", "Rename")
         }
     }
 }

api-editor/backend/src/test/kotlin/com/larsreimann/api_editor/codegen/PythonCodeGeneratorTest.kt

@@ -238,6 +238,21 @@ class PythonCodeGeneratorTest {
                     |        self.testAttribute2: int = 2
             """.trimMargin()
         }
+
+        @Test
+        fun `should store todo if it is not blank`() {
+            val testClass = PythonClass(
+                name = "TestClass",
+                todo = "Lorem ipsum\n\nDolor sit amet"
+            )
+
+            testClass.toPythonCode() shouldBe """
+                    |# TODO: Lorem ipsum
+                    |        Dolor sit amet
+                    |class TestClass:
+                    |    pass
+            """.trimMargin()
+        }
     }
 
     @Nested
@@ -441,6 +456,20 @@ class PythonCodeGeneratorTest {
                 |    self.instance = OriginalClass()
             """.trimMargin()
         }
+
+        @Test
+        fun `should store todo if it is not blank`() {
+            val testConstructor = PythonConstructor(
+                todo = "Lorem ipsum\n\nDolor sit amet"
+            )
+
+            testConstructor.toPythonCode() shouldBe """
+                    |# TODO: Lorem ipsum
+                    |        Dolor sit amet
+                    |def __init__():
+                    |    pass
+            """.trimMargin()
+        }
     }
 
     @Nested
@@ -687,6 +716,21 @@ class PythonCodeGeneratorTest {
                     |    pass
             """.trimMargin()
         }
+
+        @Test
+        fun `should store todo if it is not blank`() {
+            val testFunction = PythonFunction(
+                name = "testFunction",
+                todo = "Lorem ipsum\n\nDolor sit amet"
+            )
+
+            testFunction.toPythonCode() shouldBe """
+                    |# TODO: Lorem ipsum
+                    |        Dolor sit amet
+                    |def testFunction():
+                    |    pass
+            """.trimMargin()
+        }
     }
 
     @Nested

api-editor/backend/src/test/kotlin/com/larsreimann/api_editor/transformation/TodoAnnotationProcessorTest.kt

@@ -0,0 +1,73 @@
+package com.larsreimann.api_editor.transformation
+
+import com.larsreimann.api_editor.model.TodoAnnotation
+import com.larsreimann.api_editor.mutable_model.PythonClass
+import com.larsreimann.api_editor.mutable_model.PythonFunction
+import com.larsreimann.api_editor.mutable_model.PythonModule
+import com.larsreimann.api_editor.mutable_model.PythonPackage
+import io.kotest.matchers.collections.shouldBeEmpty
+import io.kotest.matchers.shouldBe
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+
+class TodoAnnotationProcessorTest {
+    private lateinit var testClass: PythonClass
+    private lateinit var testFunction: PythonFunction
+    private lateinit var testPackage: PythonPackage
+
+    @BeforeEach
+    fun reset() {
+        testClass = PythonClass(
+            name = "TestClass",
+            annotations = mutableListOf(TodoAnnotation("Refactor class"))
+        )
+        testFunction = PythonFunction(
+            name = "testFunction",
+            annotations = mutableListOf(TodoAnnotation("Refactor function"))
+        )
+        testPackage = PythonPackage(
+            distribution = "testPackage",
+            name = "testPackage",
+            version = "1.0.0",
+            modules = listOf(
+                PythonModule(
+                    name = "testModule",
+                    classes = listOf(testClass),
+                    functions = listOf(testFunction)
+                )
+            )
+        )
+    }
+
+    @Test
+    fun `should process TodoAnnotation of classes`() {
+        testPackage.processTodoAnnotations()
+
+        testClass.todo shouldBe "Refactor class"
+    }
+
+    @Test
+    fun `should remove TodoAnnotation of classes`() {
+        testPackage.processTodoAnnotations()
+
+        testClass.annotations
+            .filterIsInstance<TodoAnnotation>()
+            .shouldBeEmpty()
+    }
+
+    @Test
+    fun `should process TodoAnnotation of functions`() {
+        testPackage.processTodoAnnotations()
+
+        testFunction.todo shouldBe "Refactor function"
+    }
+
+    @Test
+    fun `should remove TodoAnnotation of functions`() {
+        testPackage.processTodoAnnotations()
+
+        testFunction.annotations
+            .filterIsInstance<TodoAnnotation>()
+            .shouldBeEmpty()
+    }
+}

api-editor/desktop/src/main/kotlin/com/larsreimann/python_api_editor/AnnotationDropdown.kt

@@ -29,6 +29,7 @@ fun AnnotationDropdown(
     showRemove: Boolean = false,
     showRename: Boolean = false,
     showRequired: Boolean = false,
+    showTodo: Boolean = false,
 ) {
     var expanded by remember { mutableStateOf(false) }
 
@@ -102,6 +103,11 @@ fun AnnotationDropdown(
                     Text(labels.getString("AnnotationDropdown.Option.Required"))
                 }
             }
+            if (showTodo) {
+                DropdownMenuItem(onClick = {}) {
+                    Text(labels.getString("AnnotationDropdown.Option.Todo"))
+                }
+            }
         }
     }
 }

api-editor/desktop/src/main/resources/i18n/labels.properties

@@ -37,3 +37,4 @@ AnnotationDropdown.Option.Pure=@pure
 AnnotationDropdown.Option.Remove=@remove
 AnnotationDropdown.Option.Rename=@rename
 AnnotationDropdown.Option.Required=@required
+AnnotationDropdown.Option.Todo=@todo