Hacktoberfest [JENKINS-69731] Enhance @Library annotation to load same version (feature branch name) of library as pipeline script from SCM

pom.xml

@@ -203,5 +203,11 @@
             <version>1.10.7</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.jenkins-ci.plugins</groupId>
+            <artifactId>envinject</artifactId>
+            <version>2.4.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 </project>

src/main/java/org/jenkinsci/plugins/workflow/libs/LibraryAdder.java

@@ -126,7 +126,7 @@
                     listener.getLogger().println("Only using first definition of library " + name);
                     continue;
                 }
-                String version = cfg.defaultedVersion(libraryVersions.remove(name));
+                String version = cfg.defaultedVersion(libraryVersions.remove(name), build, listener);
                 Boolean changelog = cfg.defaultedChangelogs(libraryChangelogs.remove(name));
                 String source = kind.getClass().getName();
                 if (cfg instanceof LibraryResolver.ResolvedLibraryConfiguration) {

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/config.jelly

@@ -37,6 +37,18 @@ THE SOFTWARE.
     <f:entry field="allowVersionOverride" title="${%Allow default version to be overridden}">
         <f:checkbox default="true"/>
     </f:entry>
+    <f:entry field="allowVersionEnvvar" title="${%Allow literal use of @Library 'libname@${env.VARNAME}' pattern in pipeline scripts; falls back to default version if such custom VARNAME is not available among environment variables for the build or not found as branch name in SCM}">
+        <f:checkbox default="false"/>
+    </f:entry>
+    <f:entry field="allowBRANCH_NAME" title="${%Allow literal use of @Library 'libname@${BRANCH_NAME}' in pipeline scripts from SCM; falls back to default version if BRANCH_NAME is not available or not found}">
+        <f:checkbox default="false"/>
+    </f:entry>
+    <f:entry field="allowBRANCH_NAME_PR" title="${%If you allow literal use of @Library 'libname@${BRANCH_NAME}' above, you can also allow fallback to CHANGE_BRANCH and/or CHANGE_TARGET for pull request builds}">
+        <f:checkbox default="false"/>
+    </f:entry>
+    <f:entry field="traceDefaultedVersion" title="${%Request tracing of 'libname@${BRANCH_NAME}' resolution into build log}">
+        <f:checkbox default="false"/>
+    </f:entry>
     <f:entry field="includeInChangesets" title="${%Include @Library changes in job recent changes}">
         <f:checkbox default="true"/>
     </f:entry>

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/help-allowBRANCH_NAME.html

@@ -0,0 +1,17 @@
+<div>
+  If checked, scripts may select a custom version of the library
+  by appending literally <code>@${BRANCH_NAME}</code> in the
+  <code>@Library</code> annotation, to use same SCM branch name
+  of the library codebase as that of the pipeline being built.<br/>
+  If such branch name is not resolvable as an environment variable
+  or not present in library storage (SCM, release artifacts...),
+  it would fall back to default version you select here.<br/>
+  Keep in mind that while the markup for such variable version
+  specification is intentionally similar to what you would use
+  in pipeline Groovy code, for simpler use and maintenance, the
+  actual strings are expanded by the plugin as it pre-processes
+  the pipeline script before compilation. Tokens spelled in the
+  <code>@Library</code> annotation are not Groovy variables!
+  The values substituted here are not influenced by run-time
+  interpretation of the pipeline script source text!
+</div>

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/help-allowBRANCH_NAME_PR.html

@@ -0,0 +1,10 @@
+<div>
+  If checked, and if scripts are allowed to select a custom version
+  of the library by appending literally <code>@${BRANCH_NAME}</code>
+  in the <code>@Library</code> annotation, then for pull request
+  builds additional fall-back library branches would include the
+  names used as <code>CHANGE_BRANCH</code> (name of source branch
+  of pipeline pull request) and <code>CHANGE_TARGET</code> (name
+  of target branch of pipeline pull request), if such branch names
+  already exist in the trusted shared library repository.
+</div>

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/help-allowVersionEnvvar.html

@@ -0,0 +1,18 @@
+<div>
+  If checked, scripts may select a custom version of the library
+  by appending literally <code>@${env.VARNAME}</code> pattern in
+  the <code>@Library</code> annotation, to use current value of
+  chosen environment variable named <code>VARNAME</code> if it
+  is defined in job properties or on the build agent.<br/>
+  If such branch name is not resolvable as an environment variable
+  or not present in library storage (SCM, release artifacts...),
+  it would fall back to default version you select here.<br/>
+  Keep in mind that while the markup for such variable version
+  specification is intentionally similar to what you would use
+  in pipeline Groovy code, for simpler use and maintenance, the
+  actual strings are expanded by the plugin as it pre-processes
+  the pipeline script before compilation. Tokens spelled in the
+  <code>@Library</code> annotation are not Groovy variables!
+  The values substituted here are not influenced by run-time
+  interpretation of the pipeline script source text!
+</div>

src/main/resources/org/jenkinsci/plugins/workflow/libs/LibraryConfiguration/help-traceDefaultedVersion.html

@@ -0,0 +1,5 @@
+<div>
+  If checked, the <code>defaultedVersion</code> method would print
+  its progress trying to resolve <code>@${BRANCH_NAME}</code> in the
+  <code>@Library</code> annotation into the build log.
+</div>

src/test/java/org/jenkinsci/plugins/workflow/libs/LibraryConfigurationTest.java

@@ -26,9 +26,11 @@
 
 import java.util.Collections;
 
+import hudson.AbortException;
 import hudson.plugins.git.GitSCM;
 import org.hamcrest.Matchers;
 import org.junit.Test;
+import org.junit.Assert;
 import static org.junit.Assert.*;
 import org.junit.Rule;
 import org.jvnet.hudson.test.Issue;
@@ -92,6 +94,109 @@ public class LibraryConfigurationTest {
         assertNull(cfg.getDefaultVersion());
     }
 
+    @Issue("JENKINS-69731")
+    @Test public void nullPresentDefaultedVersion() {
+        String libraryName = "valid-name";
+        String defaultVersion = "master";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+        cfg.setDefaultVersion(defaultVersion);
+
+        assertEquals("master", cfg.getDefaultVersion());
+        try {
+            assertEquals("master", cfg.defaultedVersion(null));
+        } catch(AbortException ae) {
+            Assert.fail("LibraryConfiguration.defaultedVersion() threw an AbortException when it was not expected: " + ae.getMessage());
+        }
+    }
+
+    @Issue("JENKINS-69731")
+    @Test public void nullAbsentDefaultedVersion() {
+        String libraryName = "valid-name";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+
+        assertEquals(null, cfg.getDefaultVersion());
+        assertThrows(AbortException.class, () -> cfg.defaultedVersion(null));
+    }
+
+    @Issue("JENKINS-69731")
+    @Test public void forbiddenOverrideDefaultedVersion() {
+        String libraryName = "valid-name";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+        cfg.setAllowVersionOverride(false);
+
+        assertEquals(false, cfg.isAllowVersionOverride());
+        assertThrows(AbortException.class, () -> cfg.defaultedVersion("branchname"));
+    }
+
+    @Issue("JENKINS-69731")
+    @Test public void allowedOverrideDefaultedVersion() {
+        String libraryName = "valid-name";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+        cfg.setAllowVersionOverride(true);
+
+        assertEquals(true, cfg.isAllowVersionOverride());
+        try {
+            assertEquals("branchname", cfg.defaultedVersion("branchname"));
+        } catch(AbortException ae) {
+            Assert.fail("LibraryConfiguration.defaultedVersion() threw an AbortException when it was not expected: " + ae.getMessage());
+        }
+    }
+
+    @Issue("JENKINS-69731")
+    @Test public void notAllowedOverrideDefaultedVersionWhenBRANCH_NAME() {
+        String libraryName = "valid-name";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+        cfg.setAllowVersionOverride(true);
+        cfg.setAllowBRANCH_NAME(false);
+        cfg.setTraceDefaultedVersion(true);
+
+        assertEquals(true, cfg.isAllowVersionOverride());
+        assertEquals(false, cfg.isAllowBRANCH_NAME());
+        assertEquals(true, cfg.isTraceDefaultedVersion());
+        assertThrows(AbortException.class, () -> cfg.defaultedVersion("${BRANCH_NAME}"));
+        /* This SHOULD NOT return a version string that literally remains '${BRANCH_NAME}'! */
+    }
+
+    @Issue("JENKINS-69731")
+    @Test public void allowedBRANCH_NAMEnoRunPresentDefaultedVersion() {
+        String libraryName = "valid-name";
+        String defaultVersion = "master";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+        cfg.setDefaultVersion(defaultVersion);
+        cfg.setAllowBRANCH_NAME(true);
+        cfg.setTraceDefaultedVersion(true);
+
+        assertEquals(true, cfg.isAllowBRANCH_NAME());
+        try {
+            assertEquals("master", cfg.defaultedVersion("${BRANCH_NAME}", null, null));
+        } catch(AbortException ae) {
+            Assert.fail("LibraryConfiguration.defaultedVersion() threw an AbortException when it was not expected: " + ae.getMessage());
+        }
+    }
+
+    @Issue("JENKINS-69731")
+    @Test public void allowedBRANCH_NAMEnoRunAbsentDefaultedVersion() {
+        String libraryName = "valid-name";
+
+        LibraryConfiguration cfg = new LibraryConfiguration(libraryName, new SCMRetriever(new GitSCM("https://phony.jenkins.io/bar.git")));
+        cfg.setAllowBRANCH_NAME(true);
+        cfg.setTraceDefaultedVersion(true);
+
+        assertEquals(true, cfg.isAllowBRANCH_NAME());
+        assertThrows(AbortException.class, () -> cfg.defaultedVersion("${BRANCH_NAME}", null, null));
+    }
 
+    /* Note: further tests for JENKINS-69731 behaviors with allowBRANCH_NAME
+     * would rely on having a Run with or without a BRANCH_NAME envvar, and
+     * a TaskListener, and a (mock?) LibraryRetriever that would confirm or
+     * deny existence of a requested "version" (e.g. Git branch) of the lib.
+     * For examples, see e.g. SCMSourceRetrieverTest codebase.
+     */
 
 }