Sanitize generated comments (#39)

connectrpc · Apr 26, 2023 · c6b9ba1 · c6b9ba1
1 parent 7e61ceb
commit c6b9ba1
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 12 deletions.
diff --git a/protoc-gen-connect-kotlin/proto/buf/evilcomments/v1/evilcomments.proto b/protoc-gen-connect-kotlin/proto/buf/evilcomments/v1/evilcomments.proto
@@ -0,0 +1,29 @@
+// Copyright 2022-2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package buf.evilcomments.v1;
+
+message EvilCommentsRequest {}
+
+message EvilCommentsResponse {}
+
+service EvilCommentsService {
+    // This comment contains characters that should be escaped.
+    // @ is valid in KDoc, but not in proto.
+    // Comments in KDoc use C-style block comments, so */ and /* should be escaped.
+    // [ and ] characters should also be escaped.
+    rpc EvilComments(EvilCommentsRequest) returns (EvilCommentsResponse) {}
+}
diff --git a/protoc-gen-connect-kotlin/src/main/kotlin/build/buf/protocgen/connect/Generator.kt b/protoc-gen-connect-kotlin/src/main/kotlin/build/buf/protocgen/connect/Generator.kt
@@ -126,7 +126,7 @@ class Generator : CodeGenerator {
         val interfaceBuilder = TypeSpec.interfaceBuilder(serviceClientInterfaceClassName(packageName, service))
         val functionSpecs = interfaceMethods(service.methods, sourceInfo)
         return interfaceBuilder
-            .addKdoc(sourceInfo.comment())
+            .addKdoc(sourceInfo.comment().sanitizeKdoc())
             .addFunctions(functionSpecs)
             .build()
     }
@@ -144,7 +144,7 @@ class Generator : CodeGenerator {
             val outputClassName = classNameFromType(method.outputType)
             if (method.isClientStreaming && method.isServerStreaming) {
                 val streamingBuilder = FunSpec.builder(method.name.lowerCamelCase())
-                    .addKdoc(sourceInfo.comment())
+                    .addKdoc(sourceInfo.comment().sanitizeKdoc())
                     .addModifiers(KModifier.ABSTRACT)
                     .addModifiers(KModifier.SUSPEND)
                     .addParameter(headerParameterSpec)
@@ -155,7 +155,7 @@ class Generator : CodeGenerator {
                 functions.add(streamingBuilder.build())
             } else if (method.isServerStreaming) {
                 val serverStreamingFunction = FunSpec.builder(method.name.lowerCamelCase())
-                    .addKdoc(sourceInfo.comment())
+                    .addKdoc(sourceInfo.comment().sanitizeKdoc())
                     .addModifiers(KModifier.ABSTRACT)
                     .addModifiers(KModifier.SUSPEND)
                     .addParameter(headerParameterSpec)
@@ -166,7 +166,7 @@ class Generator : CodeGenerator {
                 functions.add(serverStreamingFunction)
             } else if (method.isClientStreaming) {
                 val clientStreamingFunction = FunSpec.builder(method.name.lowerCamelCase())
-                    .addKdoc(sourceInfo.comment())
+                    .addKdoc(sourceInfo.comment().sanitizeKdoc())
                     .addModifiers(KModifier.ABSTRACT)
                     .addModifiers(KModifier.SUSPEND)
                     .addParameter(headerParameterSpec)
@@ -178,7 +178,7 @@ class Generator : CodeGenerator {
             } else {
                 if (configuration.generateCoroutineMethods) {
                     val unarySuspendFunction = FunSpec.builder(method.name.lowerCamelCase())
-                        .addKdoc(sourceInfo.comment())
+                        .addKdoc(sourceInfo.comment().sanitizeKdoc())
                         .addModifiers(KModifier.ABSTRACT)
                         .addModifiers(KModifier.SUSPEND)
                         .addParameter("request", inputClassName)
@@ -194,7 +194,7 @@ class Generator : CodeGenerator {
                         returnType = Unit::class.java.asTypeName()
                     )
                     val unaryCallbackFunction = FunSpec.builder(method.name.lowerCamelCase())
-                        .addKdoc(sourceInfo.comment())
+                        .addKdoc(sourceInfo.comment().sanitizeKdoc())
                         .addModifiers(KModifier.ABSTRACT)
                         .addParameter("request", inputClassName)
                         .addParameter(headerParameterSpec)
@@ -228,7 +228,7 @@ class Generator : CodeGenerator {
             )
         val functionSpecs = implementationMethods(service.methods, sourceInfo)
         return classBuilder
-            .addKdoc(sourceInfo.comment())
+            .addKdoc(sourceInfo.comment().sanitizeKdoc())
             .addFunctions(functionSpecs)
             .build()
     }
@@ -252,7 +252,7 @@ class Generator : CodeGenerator {
                 .build()
             if (method.isClientStreaming && method.isServerStreaming) {
                 val streamingFunction = FunSpec.builder(method.name.lowerCamelCase())
-                    .addKdoc(sourceInfo.comment())
+                    .addKdoc(sourceInfo.comment().sanitizeKdoc())
                     .addModifiers(KModifier.OVERRIDE)
                     .addModifiers(KModifier.SUSPEND)
                     .addParameter("headers", HEADERS_CLASS_NAME)
@@ -278,7 +278,7 @@ class Generator : CodeGenerator {
                 functions.add(streamingFunction)
             } else if (method.isServerStreaming) {
                 val serverStreamingFunction = FunSpec.builder(method.name.lowerCamelCase())
-                    .addKdoc(sourceInfo.comment())
+                    .addKdoc(sourceInfo.comment().sanitizeKdoc())
                     .addModifiers(KModifier.OVERRIDE)
                     .addModifiers(KModifier.SUSPEND)
                     .addParameter("headers", HEADERS_CLASS_NAME)
@@ -300,7 +300,7 @@ class Generator : CodeGenerator {
                 functions.add(serverStreamingFunction)
             } else if (method.isClientStreaming) {
                 val clientStreamingFunction = FunSpec.builder(method.name.lowerCamelCase())
-                    .addKdoc(sourceInfo.comment())
+                    .addKdoc(sourceInfo.comment().sanitizeKdoc())
                     .addModifiers(KModifier.OVERRIDE)
                     .addModifiers(KModifier.SUSPEND)
                     .addParameter("headers", HEADERS_CLASS_NAME)
@@ -323,7 +323,7 @@ class Generator : CodeGenerator {
             } else {
                 if (configuration.generateCoroutineMethods) {
                     val unarySuspendFunction = FunSpec.builder(method.name.lowerCamelCase())
-                        .addKdoc(sourceInfo.comment())
+                        .addKdoc(sourceInfo.comment().sanitizeKdoc())
                         .addModifiers(KModifier.SUSPEND)
                         .addModifiers(KModifier.OVERRIDE)
                         .addParameter("request", inputClassName)
@@ -350,7 +350,7 @@ class Generator : CodeGenerator {
                         returnType = Unit::class.java.asTypeName()
                     )
                     val unaryCallbackFunction = FunSpec.builder(method.name.lowerCamelCase())
-                        .addKdoc(sourceInfo.comment())
+                        .addKdoc(sourceInfo.comment().sanitizeKdoc())
                         .addModifiers(KModifier.OVERRIDE)
                         .addParameter("request", inputClassName)
                         .addParameter("headers", HEADERS_CLASS_NAME)
@@ -396,6 +396,18 @@ class Generator : CodeGenerator {
         }
         return ClassName(packageName, names.first())
     }
+
+    internal fun String.sanitizeKdoc(): String {
+        return this
+            // Remove trailing whitespace on each line.
+            .replace("[^\\S\n]+\n".toRegex(), "\n")
+            .replace("\\s+$".toRegex(), "")
+            .replace("\\*/".toRegex(), "&#42;/")
+            .replace("/\\*".toRegex(), "/&#42;")
+            .replace("""[""", "&#91;")
+            .replace("""]""", "&#93;")
+            .replace("@", "&#64;")
+    }
 }
 
 private fun serviceClientInterfaceClassName(packageName: String, service: Descriptors.ServiceDescriptor): ClassName {

diff --git a/protoc-gen-connect-kotlin/src/test/kotlin/PluginGenerationTest.kt b/protoc-gen-connect-kotlin/src/test/kotlin/PluginGenerationTest.kt
@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import buf.evilcomments.v1.EvilCommentsServiceClient
 import buf.javamultiplefiles.disabled.v1.DisabledEmptyOuterClass
 import buf.javamultiplefiles.disabled.v1.DisabledEmptyServiceClient
 import buf.javamultiplefiles.disabled.v1.DisabledInnerMessageServiceClient
@@ -107,4 +108,9 @@ class PluginGenerationTest {
             }
         }
     }
+
+    @Test
+    fun evilCommentsCompiles() {
+        val client = EvilCommentsServiceClient(mock { })
+    }
 }