Add description to Space when it is created (#53)

* Add description to Space when it is created

* Bump plugin minor version

functional-tests/specs/space_creation.spec

@@ -14,6 +14,7 @@ The `example-user/example-repo` comes from the [dummy Git remote URL config in t
 test framework code][1].  When users run the plugin the Space name will be taken from 
 the Git remote URL of the Git repository that the plugin is executed on.
 
+* Space has description "Gauge (https://gauge.org) specifications from https://github.com/example-user/example-repo, published automatically by the Gauge Confluence plugin tool (https://github.com/agilepathway/gauge-confluence) as living documentation.  Do not edit this Space manually.  You can use Confluence's Include Macro (https://confluence.atlassian.com/doc/include-page-macro-139514.html) to include these specifications in as many of your existing Confluence Spaces as you wish."
 
 ## If the Space does not already exist, the plugin needs to be run by a user with permissions to create it
 Tags: not-cloud

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/Confluence.java

@@ -94,6 +94,12 @@ public void assertSpaceHasName(String name) {
         assertThat(space.getName()).isEqualTo(name);
     }
 
+    @Step("Space has description <description>")
+    public void assertSpaceHasDescription(String description) {
+        Space space = new Space(getScenarioSpaceKey());
+        assertThat(space.getDescription()).isEqualTo(description);
+    }
+
     @Step("Published pages are: <table>")
     public void assertPublishedPages(Table expectedPages) throws Exception {
         int expectedTotal = expectedPages.getTableRows().size();

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/ConfluenceClient.java

@@ -117,7 +117,7 @@ private static HttpRequest getAllPagesRequest(String spaceKey) {
 
     private static HttpRequest getSpaceRequest(String spaceKey) {
         HttpRequest.Builder builder = baseConfluenceRequest();
-        String getSpaceURL = String.format("%1$s/%2$s", baseSpaceAPIURL(), spaceKey);
+        String getSpaceURL = String.format("%1$s/%2$s?expand=description.plain", baseSpaceAPIURL(), spaceKey);
         builder.uri(URI.create(getSpaceURL));
         return builder.build();
     }

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/Space.java

@@ -14,6 +14,10 @@ public String getName() {
         return jsonSpace.getString("name");
     }
 
+    public String getDescription() {
+        return jsonSpace.getJSONObject("description").getJSONObject("plain").getString("value");
+    }
+
     @Override
     public String toString() {
         return jsonSpace.toString(4);

internal/confluence/api/client.go

@@ -94,16 +94,32 @@ func (c *Client) DeletePage(pageID string) (err error) {
 }
 
 // CreateSpace creates a Confluence Space with the given key
-func (c *Client) CreateSpace(key, name string) error {
+func (c *Client) CreateSpace(key, name, description string) error {
+	type Plain struct {
+		Value          string `json:"value"`
+		Representation string `json:"representation"`
+	}
+
+	type Description struct {
+		Plain `json:"plain"`
+	}
+
 	type Data struct {
-		Key  string `json:"key"`
-		Name string `json:"name"`
+		Key         string `json:"key"`
+		Name        string `json:"name"`
+		Description `json:"description"`
 	}
 
 	path := "space"
 	requestBody := Data{
 		key,
 		name,
+		Description{
+			Plain{
+				description,
+				"plain",
+			},
+		},
 	}
 
 	return c.httpClient.PostJSON(path, requestBody)

internal/confluence/space.go

@@ -98,16 +98,21 @@ func (s *space) createIfDoesNotAlreadyExist() (err error) {
 
 	logger.Infof(true, "Space with key %s does not already exist, creating it ...", s.key)
 
-	spaceName, err := s.name()
+	return s.createSpace()
+}
+
+func (s *space) createSpace() error {
+	name, err := s.name()
 	if err != nil {
 		return err
 	}
 
-	return s.createSpace(s.key, spaceName)
-}
+	description, err := s.description()
+	if err != nil {
+		return err
+	}
 
-func (s *space) createSpace(key, name string) error {
-	err := s.apiClient.CreateSpace(key, name)
+	err = s.apiClient.CreateSpace(s.key, name, description)
 
 	if err != nil {
 		e, ok := err.(*http.RequestError)
@@ -132,6 +137,20 @@ func (s *space) name() (string, error) {
 	return fmt.Sprintf("Gauge specs for %s", gitRemoteURLPath), nil
 }
 
+func (s *space) description() (string, error) {
+	gitWebURL, err := git.WebURL()
+	if err != nil {
+		return "", err
+	}
+
+	return fmt.Sprintf("Gauge (https://gauge.org) specifications from %s, "+
+		"published automatically by the Gauge Confluence plugin tool "+
+		"(https://github.com/agilepathway/gauge-confluence) as living documentation.  "+
+		"Do not edit this Space manually.  "+
+		"You can use Confluence's Include Macro (https://confluence.atlassian.com/doc/include-page-macro-139514.html) "+
+		"to include these specifications in as many of your existing Confluence Spaces as you wish.", gitWebURL), nil
+}
+
 func (s *space) exists() (bool, error) {
 	return s.apiClient.DoesSpaceExist(s.key)
 }

internal/git/git_url.go

@@ -10,11 +10,22 @@ import (
 // copied from https://github.com/go-git/go-git/blob/bf3471db54b0255ab5b159005069f37528a151b7/internal/url/url.go#L9
 var scpLikeURIRegExp = regexp.MustCompile(`^(?:(?P<user>[^@]+)@)?(?P<host>[^:\s]+):(?:(?P<port>[0-9]{1,5})(?:\/|:))?(?P<path>[^\\].*\/[^\\].*)$`) //nolint:lll
 
+// WebURL provides the web URL of the remote Git repository.
+func WebURL() (string, error) {
+	remoteGitURL, err := discoverRemoteGitURL()
+
+	if err != nil {
+		return "", err
+	}
+
+	return buildGitWebURL(remoteGitURL)
+}
+
 // RemoteURLPath provides the path part of the remote Git URL.
 // It does not include the slash at the beginning of the path.
 // e.g. user-or-org/project
 func RemoteURLPath() (string, error) {
-	gitWebURL, err := discoverGitWebURL()
+	gitWebURL, err := WebURL()
 	if err != nil {
 		return "", err
 	}
@@ -24,7 +35,7 @@ func RemoteURLPath() (string, error) {
 
 // SpecGitURL gives the remote Git URL (e.g. on GitHub, GitLab, Bitbucket etc) for a spec file
 func SpecGitURL(absoluteSpecPath, projectRoot string) string {
-	gitWebURL, err := discoverGitWebURL()
+	gitWebURL, err := WebURL()
 
 	if err != nil {
 		fmt.Println(err)
@@ -52,16 +63,6 @@ func parseURLPath(s string) (string, error) {
 	return strings.TrimPrefix(u.Path, "/"), nil
 }
 
-func discoverGitWebURL() (string, error) {
-	remoteGitURL, err := discoverRemoteGitURL()
-
-	if err != nil {
-		return "", err
-	}
-
-	return buildGitWebURL(remoteGitURL)
-}
-
 // buildGitWebURL constructs the publicly accessible Git web URL from a Git remote URL.
 func buildGitWebURL(remoteGitURI string) (string, error) {
 	url, err := url.Parse(remoteGitURI)

plugin.json

@@ -1,6 +1,6 @@
 {
     "id": "confluence",
-    "version": "0.14.1",
+    "version": "0.15.0",
     "name": "Confluence",
     "description": "Publishes Gauge specifications to Confluence",
     "install": {