feat: todo annotation for parameters (#793)

* feat(gui): allow adding todo annotations to parameters

* test(backend): failing codegen tests

* feat(backend): codegen for todo comments of parameters

* feat(backend): process todo annotations on parameters

Author: lars-reimann

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

@@ -147,7 +147,7 @@ fun PythonClass.toPythonCode() = buildString {
 }
 
 fun PythonConstructor.toPythonCode() = buildString {
-    val todoComment = todoComment(todo)
+    val todoComments = listOf(todoComment(todo)) + parameters.map { todoComment(it.todo, "param:${it.name}") }
     val parametersString = parameters.toPythonCode()
     val boundariesString = parameters
         .mapNotNull { it.boundary?.toPythonCode(it.name) }
@@ -160,8 +160,10 @@ fun PythonConstructor.toPythonCode() = buildString {
         ?.let { "self.instance = ${it.toPythonCode()}" }
         ?: ""
 
-    if (todoComment.isNotBlank()) {
-        appendLine(todoComment)
+    todoComments.forEach {
+        if (it.isNotBlank()) {
+            appendLine(it)
+        }
     }
     appendLine("def __init__($parametersString):")
     if (boundariesString.isNotBlank()) {
@@ -210,7 +212,7 @@ fun PythonEnumInstance.toPythonCode(enumName: String): String {
 }
 
 fun PythonFunction.toPythonCode() = buildString {
-    val todoComment = todoComment(todo)
+    val todoComments = listOf(todoComment(todo)) + parameters.map { todoComment(it.todo, "param:${it.name}") }
     val parametersString = parameters.toPythonCode()
     val docstring = docstring()
     val boundariesString = parameters
@@ -220,8 +222,10 @@ fun PythonFunction.toPythonCode() = buildString {
         ?.let { "return ${it.toPythonCode()}" }
         ?: ""
 
-    if (todoComment.isNotBlank()) {
-        appendLine(todoComment)
+    todoComments.forEach {
+        if (it.isNotBlank()) {
+            appendLine(it)
+        }
     }
     if (isStaticMethod()) {
         appendLine("@staticmethod")
@@ -328,6 +332,7 @@ fun PythonType?.toPythonCodeOrNull(): String? {
                 else -> null
             }
         }
+
         null -> null
     }
 }
@@ -370,7 +375,7 @@ fun Boundary.toPythonCode(parameterName: String) = buildString {
     }
 }
 
-fun todoComment(message: String) = buildString {
+fun todoComment(message: String, scope: String = "") = buildString {
     if (message.isBlank()) {
         return ""
     }
@@ -379,7 +384,12 @@ fun todoComment(message: String) = buildString {
     val firstLine = lines.first()
     val remainingLines = lines.drop(1)
 
-    appendLine("# TODO: ${firstLine.trim()}")
+    append("# TODO")
+    if (scope.isNotBlank()) {
+        append("($scope)")
+    }
+    appendLine(": ${firstLine.trim()}")
+
     remainingLines.forEachIndexed { index, line ->
         val indentedLine = "#       $line"
         append(indentedLine.trim())

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

@@ -188,6 +188,7 @@ class PythonParameter(
     defaultValue: PythonExpression? = null,
     var assignedBy: PythonParameterAssignment = PythonParameterAssignment.POSITION_OR_NAME,
     var description: String = "",
+    var todo: String = "",
     var boundary: Boundary? = null,
     override val annotations: MutableList<EditorAnnotation> = mutableListOf(),
 ) : PythonDeclaration() {

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

@@ -5,6 +5,7 @@ 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.api_editor.mutable_model.PythonParameter
 import com.larsreimann.modeling.descendants
 
 /**
@@ -23,6 +24,7 @@ private fun PythonDeclaration.processTodoAnnotations() {
             when (this) {
                 is PythonClass -> this.todo = it.message
                 is PythonFunction -> this.todo = it.message
+                is PythonParameter -> this.todo = it.message
                 else -> {
                     // Do nothing
                 }

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

@@ -462,15 +462,29 @@ class PythonCodeGeneratorTest {
         @Test
         fun `should store todo if it is not blank`() {
             val testConstructor = PythonConstructor(
-                todo = "    Lorem ipsum\n\n    Dolor sit\namet\n"
+                todo = "    Lorem ipsum\n\n    Dolor sit\namet\n",
+                parameters = listOf(
+                    PythonParameter(
+                        name = "self",
+                        assignedBy = PythonParameterAssignment.IMPLICIT
+                    ),
+                    PythonParameter(
+                        name = "unfinished",
+                        todo = "    Lorem ipsum\n\n    Dolor sit\namet\n",
+                    ),
+                )
             )
 
             testConstructor.toPythonCode() shouldBe """
                     |# TODO: Lorem ipsum
                     |#
                     |#           Dolor sit
                     |#       amet
-                    |def __init__():
+                    |# TODO(param:unfinished): Lorem ipsum
+                    |#
+                    |#           Dolor sit
+                    |#       amet
+                    |def __init__(self, unfinished):
                     |    pass
             """.trimMargin()
         }
@@ -725,23 +739,32 @@ class PythonCodeGeneratorTest {
         fun `should store todo if it is not blank`() {
             val testFunction = PythonFunction(
                 name = "testFunction",
-                todo = "    Lorem ipsum\n\n    Dolor sit\namet\n"
+                todo = "    Lorem ipsum\n\n    Dolor sit\namet\n",
+                parameters = listOf(
+                    PythonParameter(
+                        name = "unfinished",
+                        todo = "    Lorem ipsum\n\n    Dolor sit\namet\n",
+                    ),
+                )
             )
 
             testFunction.toPythonCode() shouldBe """
                     |# TODO: Lorem ipsum
                     |#
                     |#           Dolor sit
                     |#       amet
-                    |def testFunction():
+                    |# TODO(param:unfinished): Lorem ipsum
+                    |#
+                    |#           Dolor sit
+                    |#       amet
+                    |def testFunction(unfinished):
                     |    pass
             """.trimMargin()
         }
     }
 
     @Nested
     inner class ModuleToPythonCode {
-
         private lateinit var testModule: PythonModule
         private lateinit var testClasses: List<PythonClass>
         private lateinit var testFunctions: List<PythonFunction>

api-editor/gui/src/features/packageData/selectionView/ParameterNode.tsx

@@ -44,6 +44,7 @@ export const ParameterNode: React.FC<ParameterNodeProps> = function ({ isTitle,
                         showOptional
                         showRename
                         showRequired
+                        showTodo
                     />
                 )}
                 <CompleteButton target={id} />