ksp-plugin: mark the API as experimental (closes #13)

nesk · Oct 27, 2023 · dd74c4e · dd74c4e
1 parent b5384b2
commit dd74c4e
Show file tree

Hide file tree

Showing 6 changed files with 38 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### ⚠️ Breaking changes
 
 - The `Configuration` class is now instantiated through a builder DSL ([#13](https://github.com/nesk/akkurate/issues/13))
+- Mark the API of the KSP plugin as experimental ([#13](https://github.com/nesk/akkurate/issues/13))
 - Remove unused `MutablePath` type alias
 
 ### Added

diff --git a/plugin/src/main/kotlin/dev/nesk/akkurate/annotations/ExperimentalAkkurateCompilerApi.kt b/plugin/src/main/kotlin/dev/nesk/akkurate/annotations/ExperimentalAkkurateCompilerApi.kt
@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+package dev.nesk.akkurate.annotations
+
+/**
+ * This annotation marks the compiler API considered experimental.
+ *
+ * The behavior of such API may be changed, or the API may even be removed completely in any further release.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR, message = "This compiler API is not considered stable and might break without warning.")
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS)
+internal annotation class ExperimentalAkkurateCompilerApi
diff --git a/plugin/src/main/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessor.kt b/plugin/src/main/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessor.kt
@@ -27,10 +27,12 @@ import com.squareup.kotlinpoet.ParameterizedTypeName.Companion.parameterizedBy
 import com.squareup.kotlinpoet.ksp.toClassName
 import com.squareup.kotlinpoet.ksp.toTypeName
 import com.squareup.kotlinpoet.ksp.toTypeParameterResolver
+import dev.nesk.akkurate.annotations.ExperimentalAkkurateCompilerApi
 import dev.nesk.akkurate.annotations.Validate
 import java.io.OutputStreamWriter
 import kotlin.reflect.KProperty1
 
+@ExperimentalAkkurateCompilerApi
 public class ValidateAnnotationProcessor(
     private val codeGenerator: CodeGenerator,
     private val logger: KSPLogger,

diff --git a/plugin/src/main/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessorConfig.kt b/plugin/src/main/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessorConfig.kt
@@ -17,6 +17,9 @@
 
 package dev.nesk.akkurate.ksp
 
+import dev.nesk.akkurate.annotations.ExperimentalAkkurateCompilerApi
+
+@ExperimentalAkkurateCompilerApi
 public data class ValidateAnnotationProcessorConfig(
     /**
      * Appends the provided value to the original package of the generated accessor.

diff --git a/plugin/src/main/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessorProvider.kt b/plugin/src/main/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessorProvider.kt
@@ -20,7 +20,9 @@ package dev.nesk.akkurate.ksp
 import com.google.devtools.ksp.processing.SymbolProcessor
 import com.google.devtools.ksp.processing.SymbolProcessorEnvironment
 import com.google.devtools.ksp.processing.SymbolProcessorProvider
+import dev.nesk.akkurate.annotations.ExperimentalAkkurateCompilerApi
 
+@ExperimentalAkkurateCompilerApi
 public class ValidateAnnotationProcessorProvider : SymbolProcessorProvider {
     override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
         val options = environment.options

diff --git a/plugin/src/test/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessorTest.kt b/plugin/src/test/kotlin/dev/nesk/akkurate/ksp/ValidateAnnotationProcessorTest.kt
@@ -19,6 +19,7 @@ package dev.nesk.akkurate.ksp
 
 import com.karumi.kotlinsnapshot.matchWithSnapshot
 import com.tschuchort.compiletesting.*
+import dev.nesk.akkurate.annotations.ExperimentalAkkurateCompilerApi
 import kotlin.io.path.*
 import kotlin.test.Test
 import kotlin.test.assertEquals
@@ -409,6 +410,7 @@ class ValidateAnnotationProcessorTest {
             .matchWithSnapshot("the option 'validatablePackages' processes all the classes of the provided packages (dev.nesk.user)")
     }
 
+    @OptIn(ExperimentalAkkurateCompilerApi::class)
     private fun compile(vararg sources: SourceFile, options: Map<String, String> = emptyMap()): Pair<KotlinCompilation.Result, KotlinCompilation> {
         val compiler = KotlinCompilation().apply {
             inheritClassPath = true