Merge pull request #430 from CoreMedia/check-plugin-version

added @RequiresPlugin annotation to enforce plugin installation

Author: daspilker

CONTRIBUTING.md

@@ -56,6 +56,15 @@ job {
 ```
 
 * Use private or protected access modifiers for context and helper methods that should not be exposed to DSL users.
+* Add the `@RequiresPlugin` annotation if the feature needs a specific plugin to be installed in Jenkins.
+
+```groovy
+@RequiresPlugin(id = 'foo', minimumVersion = '1.2')
+void foo(String fooOption) {
+    // your implementation goes here
+}
+```
+
 * Use enum values where appropriate, e.g. when the UI displays a chooser. The enum should be an inner class of the
 context which uses the enum. Use conventions for constants for naming enum values. Add the enum to the implicit imports
 in `DslScriptLoader.createCompilerConfiguration`.
@@ -64,7 +73,7 @@ in `DslScriptLoader.createCompilerConfiguration`.
 class FooContext {
     FooOptions option = FooOptions.FIRST
 
-    def option(FooOptions option) {
+    void option(FooOptions option) {
         this.option = option
     }
 
@@ -82,7 +91,7 @@ of `enableSomeOption(true)`.
 class FooContext {
     boolean foo
 
-    def foo(boolean foo = true) {
+    void foo(boolean foo = true) {
         this.foo = foo
     }
 }
@@ -95,19 +104,19 @@ class FooContext {
     Map<String, String> jvmOptions = [:]
     List<String> args = []
 
-    def jvmOption(String key, String value) {
+    void jvmOption(String key, String value) {
         jvmOptions[key] = value
     }
 
-    def jvmOptions(Map<String, String> options) {
+    void jvmOptions(Map<String, String> options) {
         jvmOptions.putAll(options)
     }
 
-    def arg(String arg) {
+    void arg(String arg) {
         args << arg
     }
 
-    def args(String... args) {
+    void args(String... args) {
         this.args.addAll(args)
     }
 }

job-dsl-core/src/ast/groovy/javaposse/jobdsl/dsl/transform/PluginASTTransformation.groovy

@@ -0,0 +1,71 @@
+package javaposse.jobdsl.dsl.transform
+
+import org.codehaus.groovy.ast.ASTNode
+import org.codehaus.groovy.ast.AnnotationNode
+import org.codehaus.groovy.ast.ClassHelper
+import org.codehaus.groovy.ast.ClassNode
+import org.codehaus.groovy.ast.MethodNode
+import org.codehaus.groovy.ast.expr.ArgumentListExpression
+import org.codehaus.groovy.ast.expr.ConstantExpression
+import org.codehaus.groovy.ast.expr.MethodCallExpression
+import org.codehaus.groovy.ast.expr.VariableExpression
+import org.codehaus.groovy.ast.stmt.BlockStatement
+import org.codehaus.groovy.ast.stmt.ExpressionStatement
+import org.codehaus.groovy.control.CompilePhase
+import org.codehaus.groovy.control.SourceUnit
+import org.codehaus.groovy.syntax.Token
+import org.codehaus.groovy.transform.ASTTransformation
+import org.codehaus.groovy.transform.GroovyASTTransformation
+
+/**
+ * Global AST transformation for checking plugin requirements.
+ *
+ * Each method annotated by <code>@javaposse.jobdsl.dsl.RequiresPlugin</code> is supplemented with a method call to
+ * <code>jobManagement.requireMinimumPluginVersion()</code> or <code>jobManagement.requirePlugin()</code>. The method
+ * must have access to a <code>jobManagement</code> field.
+ */
+@GroovyASTTransformation(phase = CompilePhase.SEMANTIC_ANALYSIS)
+class PluginASTTransformation implements ASTTransformation {
+    private static final ClassNode REQUIRES_PLUGIN_ANNOTATION = ClassHelper.make('javaposse.jobdsl.dsl.RequiresPlugin')
+
+    @Override
+    void visit(ASTNode[] nodes, SourceUnit sourceUnit) {
+        sourceUnit.AST?.classes*.methods.flatten().each { MethodNode method ->
+            method.getAnnotations(REQUIRES_PLUGIN_ANNOTATION).each { AnnotationNode requiresPluginAnnotation ->
+                if (!method.declaringClass.getField('jobManagement')) {
+                    sourceUnit.errorCollector.addError(
+                            "no jobManagement field in $method.declaringClass",
+                            Token.newString(
+                                    requiresPluginAnnotation.text,
+                                    requiresPluginAnnotation.lineNumber,
+                                    requiresPluginAnnotation.columnNumber
+                            ),
+                            sourceUnit
+                    )
+                }
+
+                MethodCallExpression pluginCheckStatement
+                if (requiresPluginAnnotation.members.minimumVersion) {
+                    pluginCheckStatement = new MethodCallExpression(
+                            new VariableExpression('jobManagement'),
+                            new ConstantExpression('requireMinimumPluginVersion'),
+                            new ArgumentListExpression(
+                                    requiresPluginAnnotation.members.id,
+                                    requiresPluginAnnotation.members.minimumVersion,
+                            )
+                    )
+                } else {
+                    pluginCheckStatement = new MethodCallExpression(
+                            new VariableExpression('jobManagement'),
+                            new ConstantExpression('requirePlugin'),
+                            new ArgumentListExpression(
+                                    requiresPluginAnnotation.members.id,
+                            )
+                    )
+                }
+
+                ((BlockStatement) method.code).statements.add(0, new ExpressionStatement(pluginCheckStatement))
+            }
+        }
+    }
+}

job-dsl-core/src/ast/resources/META-INF/services/org.codehaus.groovy.transform.ASTTransformation

@@ -1 +1,2 @@
 javaposse.jobdsl.dsl.transform.ContextASTTransformation
+javaposse.jobdsl.dsl.transform.PluginASTTransformation

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/FileJobManagement.groovy

@@ -74,6 +74,10 @@ class FileJobManagement extends AbstractJobManagement {
         new File(root, filePath).text
     }
 
+    @Override
+    void requirePlugin(String pluginShortName) {
+    }
+
     @Override
     void requireMinimumPluginVersion(String pluginShortName, String version) {
     }

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/JobManagement.groovy

@@ -102,7 +102,12 @@ interface JobManagement {
      */
     void logDeprecationWarning(String subject, String scriptName, int lineNumber)
 
-        /**
+    /**
+     * Logs a warning and sets the build status to unstable if given plugin is not installed.
+     */
+    void requirePlugin(String pluginShortName)
+
+    /**
      * Logs a warning and sets the build status to unstable if the installed version of the given plugin is older than
      * the given version.
      */

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/MemoryJobManagement.groovy

@@ -77,6 +77,10 @@ class MemoryJobManagement extends AbstractJobManagement {
         body
     }
 
+    @Override
+    void requirePlugin(String pluginShortName) {
+    }
+
     @Override
     void requireMinimumPluginVersion(String pluginShortName, String version) {
     }

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/RequiresPlugin.groovy

@@ -0,0 +1,23 @@
+package javaposse.jobdsl.dsl
+
+import java.lang.annotation.Documented
+import java.lang.annotation.ElementType
+import java.lang.annotation.Target
+
+/**
+ * Indicates that a plugin must be installed to use the features provided by the annotated DSL method. A minimum
+ * version can be specified as a lower bound for the version of the required plugin.
+ */
+@Target([ElementType.METHOD])
+@Documented
+@interface RequiresPlugin {
+    /**
+     * The Plugin ID or short name of the required plugin.
+     */
+    String id()
+
+    /**
+     * The least acceptable version of the required plugin. Optional, any version will be accepted if none is given.
+     */
+    String minimumVersion() default ''
+}

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/publisher/GitPublisherContext.groovy

@@ -4,6 +4,7 @@ import javaposse.jobdsl.dsl.Context
 import javaposse.jobdsl.dsl.ContextHelper
 import javaposse.jobdsl.dsl.DslContext
 import javaposse.jobdsl.dsl.JobManagement
+import javaposse.jobdsl.dsl.RequiresPlugin
 
 import static com.google.common.base.Preconditions.checkArgument
 import static com.google.common.base.Strings.isNullOrEmpty
@@ -28,8 +29,8 @@ class GitPublisherContext implements Context {
         this.pushMerge = pushMerge
     }
 
+    @RequiresPlugin(id = 'git', minimumVersion = '2.2.6')
     void forcePush(boolean forcePush = true) {
-        jobManagement.requireMinimumPluginVersion('git', '2.2.6')
         this.forcePush = forcePush
     }
 

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/publisher/HtmlReportTargetContext.groovy

@@ -2,6 +2,7 @@ package javaposse.jobdsl.dsl.helpers.publisher
 
 import javaposse.jobdsl.dsl.Context
 import javaposse.jobdsl.dsl.JobManagement
+import javaposse.jobdsl.dsl.RequiresPlugin
 
 class HtmlReportTargetContext implements Context {
     private final JobManagement jobManagement
@@ -29,9 +30,8 @@ class HtmlReportTargetContext implements Context {
         this.keepAll = keepAll
     }
 
+    @RequiresPlugin(id = 'htmlpublisher', minimumVersion = '1.3')
     void allowMissing(boolean allowMissing = true) {
-        jobManagement.requireMinimumPluginVersion('htmlpublisher', '1.3')
-
         this.allowMissing = allowMissing
     }
 }

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/publisher/PublisherContext.groovy

@@ -8,6 +8,7 @@ import javaposse.jobdsl.dsl.Context
 import javaposse.jobdsl.dsl.ContextHelper
 import javaposse.jobdsl.dsl.DslContext
 import javaposse.jobdsl.dsl.JobManagement
+import javaposse.jobdsl.dsl.RequiresPlugin
 import javaposse.jobdsl.dsl.WithXmlAction
 import javaposse.jobdsl.dsl.helpers.common.BuildPipelineContext
 import javaposse.jobdsl.dsl.helpers.common.DownstreamContext
@@ -66,6 +67,7 @@ class PublisherContext implements Context {
         extendedEmail(recipients, subjectTemplate, null, emailClosure)
     }
 
+    @RequiresPlugin(id = 'email-ext')
     void extendedEmail(String recipients, String subjectTemplate, String contentTemplate,
                        @DslContext(EmailContext) Closure emailClosure = null) {
         EmailContext emailContext = new EmailContext()
@@ -352,9 +354,8 @@ class PublisherContext implements Context {
      *     </plots>
      * </hudson.plugins.plot.PlotPublisher>
      */
+    @RequiresPlugin(id = 'plot', minimumVersion = '1.9')
     void plotBuildData(@DslContext(PlotsContext) Closure plotsClosure) {
-        jobManagement.requireMinimumPluginVersion('plot', '1.9')
-
         PlotsContext plotsContext = new PlotsContext()
         ContextHelper.executeInContext(plotsClosure, plotsContext)
 
@@ -1686,9 +1687,9 @@ class PublisherContext implements Context {
      * }
      * </pre>
      */
+    @RequiresPlugin(id = 'warnings', minimumVersion = '4.0')
     void warnings(List consoleParsers, Map parserConfigurations = [:],
                   @DslContext(WarningsContext) Closure warningsClosure = null) {
-        jobManagement.requireMinimumPluginVersion('warnings', '4.0')
         WarningsContext warningsContext = new WarningsContext()
         ContextHelper.executeInContext(warningsClosure,  warningsContext)