Draft: Introducing Build Position as a Condition - Seeking Guidance and Collaboration

.gitignore

@@ -1,3 +1,4 @@
 /.idea
 **/*.iml
 target/
+.vscode/

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/BuildHistoryManager.java

@@ -54,20 +54,22 @@ public synchronized void perform(Job<?, ?> job) throws IOException, InterruptedE
         }
 
         Run<?, ?> run = job.getLastCompletedBuild();
+        int buildPosition = 0;
         // for each completed build...
         while (run != null) {
-            log(uniquePerformName, "Processing build #" + run.getNumber());
+            buildPosition++;
+            log(uniquePerformName, "Processing build #" + run.getNumber() + " at build position " + buildPosition);
             if (run.isKeepLog()) {
                 log(uniquePerformName, "Build #" + run.getNumber() + " is marked as keep forever -> skip processing");
             } else {
                 for (int i = 0; i < rules.size(); i++) {
                     Rule rule = rules.get(i);
                     log(uniquePerformName, "Processing rule no " + (i + 1));
-                    if (rule.validateConditions(run)) {
+                    if (rule.validateConditions(run, buildPosition)) {
                         log(uniquePerformName, "Processing actions for rule no " + (i + 1));
                         rule.performActions(run);
 
-                        // if other rules should not be proceed, shift to next build
+                        // if other rules should not proceed, shift to next build
                         if (!rule.getContinueAfterMatch()) {
                             break;
                         }

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/descriptors/conditions/BuildPositionConditionDescriptor.java

@@ -0,0 +1,22 @@
+package pl.damianszczepanik.jenkins.buildhistorymanager.descriptors.conditions;
+
+import org.jenkinsci.Symbol;
+
+import hudson.Extension;
+import hudson.model.Descriptor;
+import pl.damianszczepanik.jenkins.buildhistorymanager.model.conditions.BuildPositionCondition;
+import pl.damianszczepanik.jenkins.buildhistorymanager.model.conditions.Condition;
+@Extension
+@Symbol("BuildPosition")
+public class BuildPositionConditionDescriptor extends Descriptor<Condition> {
+
+    public BuildPositionConditionDescriptor() {
+        super(BuildPositionCondition.class);
+    }
+
+    @Override
+    public String getDisplayName() {
+        return "Build Position";
+    }
+
+}

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/Rule.java

@@ -74,9 +74,10 @@ public void initialize(String uniquePerformName) {
      * Checks if passed build matches with all conditions from this rule.
      *
      * @param run build to validate
+     * @param buildPosition The position of the build in the history
      * @return <code>true</code> if all conditions match otherwise <code>false</code>
      */
-    public boolean validateConditions(Run<?, ?> run) {
+    public boolean validateConditions(Run<?, ?> run, int buildPosition) {
         // stop checking if max number of processed builds is reached
         if (matchedTimes == getMatchAtMost()) {
             log(uniquePerformName, String.format("Skipping rule because matched %d times", matchedTimes));
@@ -86,7 +87,7 @@ public boolean validateConditions(Run<?, ?> run) {
         // validateConditions condition one by one...
         for (Condition condition : conditions) {
             log(uniquePerformName, String.format("Processing condition '%s'", condition.getDescriptor().getDisplayName()));
-            boolean conditionMatched = condition.matches(run, configuration);
+            boolean conditionMatched = condition.matches(run, configuration, buildPosition);
             // stop checking rest conditions when at least condition does not match
             if (!conditionMatched) {
                 log(uniquePerformName, String.format("Condition '%s' does not match", condition.getDescriptor().getDisplayName()));

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildAgeRangeCondition.java

@@ -41,7 +41,7 @@ public void setMaxDaysAge(int maxDaysAge) {
     }
 
     @Override
-    public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
 
         Calendar buildTime = Calendar.getInstance();
         buildTime.setTimeInMillis(run.getStartTimeInMillis() + run.getDuration());

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildNumberRangeCondition.java

@@ -39,7 +39,7 @@ public void setMaxBuildNumber(int maxBuildNumber) {
     }
 
     @Override
-    public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
         return run.getNumber() >= minBuildNumber && run.getNumber() <= maxBuildNumber;
     }
 }

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildPositionCondition.java

@@ -0,0 +1,31 @@
+package pl.damianszczepanik.jenkins.buildhistorymanager.model.conditions;
+
+import org.kohsuke.stapler.DataBoundConstructor;
+import org.kohsuke.stapler.DataBoundSetter;
+
+import hudson.model.Run;
+import pl.damianszczepanik.jenkins.buildhistorymanager.model.RuleConfiguration;
+
+public class BuildPositionCondition extends Condition {
+
+    private int maxBuildPosition;
+
+    @DataBoundConstructor
+    public BuildPositionCondition() {
+      // Jenkins stapler requires to have public constructor with @DataBoundConstructor
+    }
+
+    public int getMaxBuildPosition() {
+        return maxBuildPosition;
+    }
+
+    @DataBoundSetter
+    public void setMaxBuildPosition(int maxBuildPosition) {
+        this.maxBuildPosition = maxBuildPosition;
+    }
+
+    @Override
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
+        return buildPosition <= maxBuildPosition;
+    } 
+}

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildResultCondition.java

@@ -70,7 +70,7 @@ public void setMatchNotBuilt(boolean matchNotBuilt) {
     }
 
     @Override
-    public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
         Result result = run.getResult();
         if (matchSuccess && result == Result.SUCCESS) {
             return true;

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/CauseCondition.java

@@ -30,7 +30,7 @@ public void setCauseClass(String causeClass) {
     }
 
     @Override
-    public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
         for (Cause cause : run.getCauses()) {
             // use contains() method to avoid problem with class name
             // for causes which are often inner class and name contains $ character

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/Condition.java

@@ -18,7 +18,8 @@ public abstract class Condition extends AbstractDescribableImpl<Condition> {
      *
      * @param run           build which should be evaluated
      * @param configuration configuration from the role
+     * @param buildPosition the position of the build in the build history
      * @return <code>true</code> if the build matches given criteria, otherwise <code>false</code>
      */
-    public abstract boolean matches(Run<?, ?> run, RuleConfiguration configuration);
+    public abstract boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition);
 }

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/MatchEveryBuildCondition.java

@@ -17,7 +17,7 @@ public MatchEveryBuildCondition() {
     }
 
     @Override
-    public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
         return true;
     }
 }

src/main/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/TokenMacroCondition.java

@@ -47,7 +47,7 @@ public String getValue() {
     }
 
     @Override
-    public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+    public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
 
         try {
             File workspace = run.getRootDir();

src/main/resources/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildPositionCondition/config.jelly

@@ -0,0 +1,7 @@
+<?jelly escape-by-default='true'?>
+<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
+
+    <f:entry title="Max Build Position in Build History" field="maxBuildPosition">
+        <f:number default="0"/>
+    </f:entry>
+</j:jelly>

src/main/resources/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildPositionCondition/help.html

@@ -0,0 +1,8 @@
+<p><b>Description</b></p>
+<p>TODO</p>
+
+<p><b>Use cases</b></p>
+<p>TODO</p>
+
+<p><b>Warning!</b></p>
+<p>TODO</p>

src/test/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/ConditionBuilder.java

@@ -37,7 +37,7 @@ public String getDisplayName() {
     public static class PositiveCondition extends AbstractSampleCondition {
 
         @Override
-        public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+        public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
             matchesTimes++;
             return true;
         }
@@ -46,7 +46,7 @@ public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
     public static class NegativeCondition extends AbstractSampleCondition {
 
         @Override
-        public boolean matches(Run<?, ?> run, RuleConfiguration configuration) {
+        public boolean matches(Run<?, ?> run, RuleConfiguration configuration, int buildPosition) {
             return false;
         }
     }

src/test/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/RuleBuilder.java

@@ -22,7 +22,7 @@ public TestRule(boolean validateResult) {
         }
 
         @Override
-        public boolean validateConditions(Run<?, ?> run) {
+        public boolean validateConditions(Run<?, ?> run, int buildPosition) {
             validateConditionsTimes++;
             return validateResult;
         }

src/test/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/RuleTest.java

@@ -22,6 +22,8 @@
  */
 public class RuleTest {
 
+    public static final int FIRST_BUILD_POSITION = 0;
+
     @Test
     public void getConditions_ReturnsConditions() {
 
@@ -101,7 +103,7 @@ public void validateConditions_MatchesAllConditions() {
         Run<?, ?> run = mock(Run.class);
 
         // when
-        rule.validateConditions(run);
+        rule.validateConditions(run, FIRST_BUILD_POSITION);
 
         // then
         for (Condition condition : rule.getConditions()) {
@@ -117,7 +119,7 @@ public void validateConditions_OnNegativeCondition_DoesNotIncrementMatchedTimes(
         Run<?, ?> run = mock(Run.class);
 
         // when
-        rule.validateConditions(run);
+        rule.validateConditions(run, FIRST_BUILD_POSITION);
 
         // then
         int matchedTimes = Deencapsulation.getField(rule, "matchedTimes");
@@ -149,8 +151,8 @@ public void validateConditions_PerformsNTimes() throws IOException, InterruptedE
         Run<?, ?> run = mock(Run.class);
 
         // when
-        rule.validateConditions(run);
-        rule.validateConditions(run);
+        rule.validateConditions(run, FIRST_BUILD_POSITION);
+        rule.validateConditions(run, FIRST_BUILD_POSITION);
 
         // then
         int matchedTimes = Deencapsulation.getField(rule, "matchedTimes");

src/test/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildAgeRangeConditionTest.java

@@ -54,7 +54,7 @@ public void matches_OnTodayBuild_ReturnsTrue() throws IOException {
         Run<?, ?> run = new RunStub();
 
         // when
-        boolean matches = condition.matches(run, null);
+        boolean matches = condition.matches(run, null, 0);
 
         assertThat(matches).isTrue();
     }
@@ -72,7 +72,7 @@ public void matches_OnBuildTimeBelowMax_ReturnsFalse() throws IOException {
         Run<?, ?> run = new RunStub(1, buildTimeMinus3Days);
 
         // when
-        boolean matches = condition.matches(run, null);
+        boolean matches = condition.matches(run, null, 0);
 
         assertThat(matches).isFalse();
     }
@@ -90,7 +90,7 @@ public void matches_OnBuildTimeAboveMin_ReturnsFalse() throws IOException {
         Run<?, ?> run = new RunStub(1, buildTimeMinus3Days);
 
         // when
-        boolean matches = condition.matches(run, null);
+        boolean matches = condition.matches(run, null,0);
 
         assertThat(matches).isFalse();
     }
@@ -107,7 +107,7 @@ public void matches_OnBuildTimeInRange_ReturnsTrue() throws IOException {
         Run<?, ?> run = new RunStub(1, buildTimeMinus3Days);
 
         // when
-        boolean matches = condition.matches(run, null);
+        boolean matches = condition.matches(run, null, 0);
 
         assertThat(matches).isTrue();
     }
@@ -123,7 +123,7 @@ public void matches_OnInvalidRange_ReturnsFalse() throws IOException {
         Run<?, ?> run = new RunStub();
 
         // when
-        boolean matches = condition.matches(run, null);
+        boolean matches = condition.matches(run, null, 0);
 
         assertThat(matches).isFalse();
     }

src/test/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildNumberRangeConditionTest.java

@@ -54,7 +54,7 @@ public void matches_ForSmallerBuildNumber_ReturnsFalse() {
         condition.setMaxBuildNumber(maxBuildNumberRange);
 
         // when
-        boolean matches = condition.matches(mockRun(minBuildNumberRange - 1), null);
+        boolean matches = condition.matches(mockRun(minBuildNumberRange - 1), null, 0);
 
         // then
         assertThat(matches).isFalse();
@@ -69,7 +69,7 @@ public void matches_ForGreaterBuildNumber_ReturnsFalse() {
         condition.setMaxBuildNumber(maxBuildNumberRange);
 
         // when
-        boolean matches = condition.matches(mockRun(maxBuildNumberRange + 1), null);
+        boolean matches = condition.matches(mockRun(maxBuildNumberRange + 1), null, 0);
 
         // then
         assertThat(matches).isFalse();
@@ -84,7 +84,7 @@ public void matches_ForValidBuildNumber_ReturnsTrue() {
         condition.setMaxBuildNumber(maxBuildNumberRange);
 
         // when
-        boolean matches = condition.matches(mockRun((minBuildNumberRange + maxBuildNumberRange) / 2), null);
+        boolean matches = condition.matches(mockRun((minBuildNumberRange + maxBuildNumberRange) / 2), null, 0);
 
         // then
         assertThat(matches).isTrue();

src/test/java/pl/damianszczepanik/jenkins/buildhistorymanager/model/conditions/BuildPositionConditionIT.java

@@ -0,0 +1,55 @@
+package pl.damianszczepanik.jenkins.buildhistorymanager.model.conditions;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.Objects;
+import java.util.concurrent.ExecutionException;
+
+import org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition;
+import org.jenkinsci.plugins.workflow.job.WorkflowJob;
+import org.jenkinsci.plugins.workflow.job.WorkflowRun;
+import org.junit.Assert;
+import org.junit.Rule;
+import org.junit.Test;
+import org.jvnet.hudson.test.JenkinsRule;
+
+import hudson.util.RunList;
+
+public class BuildPositionConditionIT {
+
+    @Rule
+    public JenkinsRule jenkinsRule = new JenkinsRule();
+
+    private WorkflowJob createPipelineJobFromScriptFile(String fileName) throws IOException {
+        Path pipelineScriptPath = Paths.get("src/test/resources", fileName);
+        String pipelineScript = new String(Files.readAllBytes(pipelineScriptPath));
+
+        CpsFlowDefinition cpsFlowDefinition = new CpsFlowDefinition(pipelineScript, true);
+        WorkflowJob pipelineJob = jenkinsRule.jenkins.createProject(WorkflowJob.class, fileName);
+
+        pipelineJob.setDefinition(cpsFlowDefinition);
+        return pipelineJob;
+    }
+
+    private void executeAndWaitForSuccessfulRun(WorkflowJob pipelineJob) throws InterruptedException, ExecutionException {
+        WorkflowRun run = Objects.requireNonNull(pipelineJob.scheduleBuild2(0)).get();
+        jenkinsRule.waitForCompletion(run);
+    }
+
+    @Test
+    public void queueMultipleRuns() throws Exception {
+        WorkflowJob pipelineJob = createPipelineJobFromScriptFile("buildPositionCondition_KeepLastTenBuildsTest.jf");
+        for (int i = 1; i <= 15; i++ ) {
+            executeAndWaitForSuccessfulRun(pipelineJob);
+        }
+
+        RunList<WorkflowRun> runList = pipelineJob.getBuilds();
+        int numOfRuns = 0;
+        for (WorkflowRun ignored : runList) {
+            numOfRuns++;
+        }        
+        Assert.assertEquals(10, numOfRuns);
+    }
+}