Alternate syntax for cross references (#9116)

* Add support for local vs. remote xrefs

* Add doc for references

* Docs: fix cases not currently supported

* One more doc fix

* Doc: mentions for teams and orgs

* Change !num ref concept, no change in functionality

* Fix test

* Improve table of issue reference types

* Fix paragraph mark

2 files changed, 72 insertions, 35 deletions

diff --git a/modules/references/references.go b/modules/references/references.go
index 17e9ec2c91..dec77b57b2 100644
--- a/modules/references/references.go
+++ b/modules/references/references.go
@@ -29,12 +29,12 @@ var (
 	// mentionPattern matches all mentions in the form of "@user"
 	mentionPattern = regexp.MustCompile(`(?:\s|^|\(|\[)(@[0-9a-zA-Z-_]+|@[0-9a-zA-Z-_][0-9a-zA-Z-_.]+[0-9a-zA-Z-_])(?:\s|[:,;.?!]\s|[:,;.?!]?$|\)|\])`)
 	// issueNumericPattern matches string that references to a numeric issue, e.g. #1287
-	issueNumericPattern = regexp.MustCompile(`(?:\s|^|\(|\[)(#[0-9]+)(?:\s|$|\)|\]|:|\.(\s|$))`)
+	issueNumericPattern = regexp.MustCompile(`(?:\s|^|\(|\[)([#!][0-9]+)(?:\s|$|\)|\]|:|\.(\s|$))`)
 	// issueAlphanumericPattern matches string that references to an alphanumeric issue, e.g. ABC-1234
 	issueAlphanumericPattern = regexp.MustCompile(`(?:\s|^|\(|\[)([A-Z]{1,10}-[1-9][0-9]*)(?:\s|$|\)|\]|:|\.(\s|$))`)
 	// crossReferenceIssueNumericPattern matches string that references a numeric issue in a different repository
 	// e.g. gogits/gogs#12345
-	crossReferenceIssueNumericPattern = regexp.MustCompile(`(?:\s|^|\(|\[)([0-9a-zA-Z-_\.]+/[0-9a-zA-Z-_\.]+#[0-9]+)(?:\s|$|\)|\]|\.(\s|$))`)
+	crossReferenceIssueNumericPattern = regexp.MustCompile(`(?:\s|^|\(|\[)([0-9a-zA-Z-_\.]+/[0-9a-zA-Z-_\.]+[#!][0-9]+)(?:\s|$|\)|\]|\.(\s|$))`)
 
 	issueCloseKeywordsPat, issueReopenKeywordsPat *regexp.Regexp
 	issueKeywordsOnce                             sync.Once
@@ -66,10 +66,14 @@ type IssueReference struct {
 }
 
 // RenderizableReference contains an unverified cross-reference to with rendering information
+// The IsPull member means that a `!num` reference was used instead of `#num`.
+// This kind of reference is used to make pulls available when an external issue tracker
+// is used. Otherwise, `#` and `!` are completely interchangeable.
 type RenderizableReference struct {
 	Issue          string
 	Owner          string
 	Name           string
+	IsPull         bool
 	RefLocation    *RefSpan
 	Action         XRefAction
 	ActionLocation *RefSpan
@@ -79,6 +83,7 @@ type rawReference struct {
 	index          int64
 	owner          string
 	name           string
+	isPull         bool
 	action         XRefAction
 	issue          string
 	refLocation    *RefSpan
@@ -202,14 +207,14 @@ func FindAllIssueReferences(content string) []IssueReference {
 }
 
 // FindRenderizableReferenceNumeric returns the first unvalidated reference found in a string.
-func FindRenderizableReferenceNumeric(content string) (bool, *RenderizableReference) {
+func FindRenderizableReferenceNumeric(content string, prOnly bool) (bool, *RenderizableReference) {
 	match := issueNumericPattern.FindStringSubmatchIndex(content)
 	if match == nil {
 		if match = crossReferenceIssueNumericPattern.FindStringSubmatchIndex(content); match == nil {
 			return false, nil
 		}
 	}
-	r := getCrossReference([]byte(content), match[2], match[3], false)
+	r := getCrossReference([]byte(content), match[2], match[3], false, prOnly)
 	if r == nil {
 		return false, nil
 	}
@@ -218,6 +223,7 @@ func FindRenderizableReferenceNumeric(content string) (bool, *RenderizableRefere
 		Issue:          r.issue,
 		Owner:          r.owner,
 		Name:           r.name,
+		IsPull:         r.isPull,
 		RefLocation:    r.refLocation,
 		Action:         r.action,
 		ActionLocation: r.actionLocation,
@@ -238,6 +244,7 @@ func FindRenderizableReferenceAlphanumeric(content string) (bool, *RenderizableR
 		RefLocation:    &RefSpan{Start: match[2], End: match[3]},
 		Action:         action,
 		ActionLocation: location,
+		IsPull:         false,
 	}
 }
 
@@ -248,14 +255,14 @@ func findAllIssueReferencesBytes(content []byte, links []string) []*rawReference
 
 	matches := issueNumericPattern.FindAllSubmatchIndex(content, -1)
 	for _, match := range matches {
-		if ref := getCrossReference(content, match[2], match[3], false); ref != nil {
+		if ref := getCrossReference(content, match[2], match[3], false, false); ref != nil {
 			ret = append(ret, ref)
 		}
 	}
 
 	matches = crossReferenceIssueNumericPattern.FindAllSubmatchIndex(content, -1)
 	for _, match := range matches {
-		if ref := getCrossReference(content, match[2], match[3], false); ref != nil {
+		if ref := getCrossReference(content, match[2], match[3], false, false); ref != nil {
 			ret = append(ret, ref)
 		}
 	}
@@ -273,12 +280,17 @@ func findAllIssueReferencesBytes(content []byte, links []string) []*rawReference
 			if len(parts) != 5 || parts[0] != "" {
 				continue
 			}
-			if parts[3] != "issues" && parts[3] != "pulls" {
+			var sep string
+			if parts[3] == "issues" {
+				sep = "#"
+			} else if parts[3] == "pulls" {
+				sep = "!"
+			} else {
 				continue
 			}
 			// Note: closing/reopening keywords not supported with URLs
-			bytes := []byte(parts[1] + "/" + parts[2] + "#" + parts[4])
-			if ref := getCrossReference(bytes, 0, len(bytes), true); ref != nil {
+			bytes := []byte(parts[1] + "/" + parts[2] + sep + parts[4])
+			if ref := getCrossReference(bytes, 0, len(bytes), true, false); ref != nil {
 				ref.refLocation = nil
 				ret = append(ret, ref)
 			}
@@ -288,13 +300,18 @@ func findAllIssueReferencesBytes(content []byte, links []string) []*rawReference
 	return ret
 }
 
-func getCrossReference(content []byte, start, end int, fromLink bool) *rawReference {
+func getCrossReference(content []byte, start, end int, fromLink bool, prOnly bool) *rawReference {
 	refid := string(content[start:end])
-	parts := strings.Split(refid, "#")
-	if len(parts) != 2 {
+	sep := strings.IndexAny(refid, "#!")
+	if sep < 0 {
+		return nil
+	}
+	isPull := refid[sep] == '!'
+	if prOnly && !isPull {
 		return nil
 	}
-	repo, issue := parts[0], parts[1]
+	repo := refid[:sep]
+	issue := refid[sep+1:]
 	index, err := strconv.ParseInt(issue, 10, 64)
 	if err != nil {
 		return nil
@@ -309,11 +326,12 @@ func getCrossReference(content []byte, start, end int, fromLink bool) *rawRefere
 			index:          index,
 			action:         action,
 			issue:          issue,
+			isPull:         isPull,
 			refLocation:    &RefSpan{Start: start, End: end},
 			actionLocation: location,
 		}
 	}
-	parts = strings.Split(strings.ToLower(repo), "/")
+	parts := strings.Split(strings.ToLower(repo), "/")
 	if len(parts) != 2 {
 		return nil
 	}
@@ -328,6 +346,7 @@ func getCrossReference(content []byte, start, end int, fromLink bool) *rawRefere
 		name:           name,
 		action:         action,
 		issue:          issue,
+		isPull:         isPull,
 		refLocation:    &RefSpan{Start: start, End: end},
 		actionLocation: location,
 	}
@@ -352,6 +371,10 @@ func findActionKeywords(content []byte, start int) (XRefAction, *RefSpan) {
 }
 
 // IsXrefActionable returns true if the xref action is actionable (i.e. produces a result when resolved)
-func IsXrefActionable(a XRefAction) bool {
-	return a == XRefActionCloses || a == XRefActionReopens
+func IsXrefActionable(ref *RenderizableReference, extTracker bool, alphaNum bool) bool {
+	if extTracker {
+		// External issues cannot be automatically closed
+		return false
+	}
+	return ref.Action == XRefActionCloses || ref.Action == XRefActionReopens
 }
diff --git a/modules/references/references_test.go b/modules/references/references_test.go
index d46c5e85d7..b38ee102ba 100644
--- a/modules/references/references_test.go
+++ b/modules/references/references_test.go
@@ -22,6 +22,7 @@ type testResult struct {
 	Owner          string
 	Name           string
 	Issue          string
+	IsPull         bool
 	Action         XRefAction
 	RefLocation    *RefSpan
 	ActionLocation *RefSpan
@@ -33,7 +34,13 @@ func TestFindAllIssueReferences(t *testing.T) {
 		{
 			"Simply closes: #29 yes",
 			[]testResult{
-				{29, "", "", "29", XRefActionCloses, &RefSpan{Start: 15, End: 18}, &RefSpan{Start: 7, End: 13}},
+				{29, "", "", "29", false, XRefActionCloses, &RefSpan{Start: 15, End: 18}, &RefSpan{Start: 7, End: 13}},
+			},
+		},
+		{
+			"Simply closes: !29 yes",
+			[]testResult{
+				{29, "", "", "29", true, XRefActionCloses, &RefSpan{Start: 15, End: 18}, &RefSpan{Start: 7, End: 13}},
 			},
 		},
 		{
@@ -43,7 +50,7 @@ func TestFindAllIssueReferences(t *testing.T) {
 		{
 			" #124 yes, this is a reference.",
 			[]testResult{
-				{124, "", "", "124", XRefActionNone, &RefSpan{Start: 0, End: 4}, nil},
+				{124, "", "", "124", false, XRefActionNone, &RefSpan{Start: 0, End: 4}, nil},
 			},
 		},
 		{
@@ -57,7 +64,13 @@ func TestFindAllIssueReferences(t *testing.T) {
 		{
 			"This user3/repo4#200 yes.",
 			[]testResult{
-				{200, "user3", "repo4", "200", XRefActionNone, &RefSpan{Start: 5, End: 20}, nil},
+				{200, "user3", "repo4", "200", false, XRefActionNone, &RefSpan{Start: 5, End: 20}, nil},
+			},
+		},
+		{
+			"This user3/repo4!200 yes.",
+			[]testResult{
+				{200, "user3", "repo4", "200", true, XRefActionNone, &RefSpan{Start: 5, End: 20}, nil},
 			},
 		},
 		{
@@ -67,19 +80,19 @@ func TestFindAllIssueReferences(t *testing.T) {
 		{
 			"This [two](/user2/repo1/issues/921) yes.",
 			[]testResult{
-				{921, "user2", "repo1", "921", XRefActionNone, nil, nil},
+				{921, "user2", "repo1", "921", false, XRefActionNone, nil, nil},
 			},
 		},
 		{
 			"This [three](/user2/repo1/pulls/922) yes.",
 			[]testResult{
-				{922, "user2", "repo1", "922", XRefActionNone, nil, nil},
+				{922, "user2", "repo1", "922", true, XRefActionNone, nil, nil},
 			},
 		},
 		{
 			"This [four](http://gitea.com:3000/user3/repo4/issues/203) yes.",
 			[]testResult{
-				{203, "user3", "repo4", "203", XRefActionNone, nil, nil},
+				{203, "user3", "repo4", "203", false, XRefActionNone, nil, nil},
 			},
 		},
 		{
@@ -93,50 +106,50 @@ func TestFindAllIssueReferences(t *testing.T) {
 		{
 			"This http://gitea.com:3000/user4/repo5/pulls/202 yes.",
 			[]testResult{
-				{202, "user4", "repo5", "202", XRefActionNone, nil, nil},
+				{202, "user4", "repo5", "202", true, XRefActionNone, nil, nil},
 			},
 		},
 		{
 			"This http://GiTeA.COM:3000/user4/repo6/pulls/205 yes.",
 			[]testResult{
-				{205, "user4", "repo6", "205", XRefActionNone, nil, nil},
+				{205, "user4", "repo6", "205", true, XRefActionNone, nil, nil},
 			},
 		},
 		{
 			"Reopens #15 yes",
 			[]testResult{
-				{15, "", "", "15", XRefActionReopens, &RefSpan{Start: 8, End: 11}, &RefSpan{Start: 0, End: 7}},
+				{15, "", "", "15", false, XRefActionReopens, &RefSpan{Start: 8, End: 11}, &RefSpan{Start: 0, End: 7}},
 			},
 		},
 		{
 			"This closes #20 for you yes",
 			[]testResult{
-				{20, "", "", "20", XRefActionCloses, &RefSpan{Start: 12, End: 15}, &RefSpan{Start: 5, End: 11}},
+				{20, "", "", "20", false, XRefActionCloses, &RefSpan{Start: 12, End: 15}, &RefSpan{Start: 5, End: 11}},
 			},
 		},
 		{
 			"Do you fix user6/repo6#300 ? yes",
 			[]testResult{
-				{300, "user6", "repo6", "300", XRefActionCloses, &RefSpan{Start: 11, End: 26}, &RefSpan{Start: 7, End: 10}},
+				{300, "user6", "repo6", "300", false, XRefActionCloses, &RefSpan{Start: 11, End: 26}, &RefSpan{Start: 7, End: 10}},
 			},
 		},
 		{
 			"For 999 #1235 no keyword, but yes",
 			[]testResult{
-				{1235, "", "", "1235", XRefActionNone, &RefSpan{Start: 8, End: 13}, nil},
+				{1235, "", "", "1235", false, XRefActionNone, &RefSpan{Start: 8, End: 13}, nil},
 			},
 		},
 		{
 			"Which abc. #9434 same as above",
 			[]testResult{
-				{9434, "", "", "9434", XRefActionNone, &RefSpan{Start: 11, End: 16}, nil},
+				{9434, "", "", "9434", false, XRefActionNone, &RefSpan{Start: 11, End: 16}, nil},
 			},
 		},
 		{
 			"This closes #600 and reopens #599",
 			[]testResult{
-				{600, "", "", "600", XRefActionCloses, &RefSpan{Start: 12, End: 16}, &RefSpan{Start: 5, End: 11}},
-				{599, "", "", "599", XRefActionReopens, &RefSpan{Start: 29, End: 33}, &RefSpan{Start: 21, End: 28}},
+				{600, "", "", "600", false, XRefActionCloses, &RefSpan{Start: 12, End: 16}, &RefSpan{Start: 5, End: 11}},
+				{599, "", "", "599", false, XRefActionReopens, &RefSpan{Start: 29, End: 33}, &RefSpan{Start: 21, End: 28}},
 			},
 		},
 	}
@@ -190,6 +203,7 @@ func testFixtures(t *testing.T, fixtures []testFixture, context string) {
 				index:          e.Index,
 				owner:          e.Owner,
 				name:           e.Name,
+				isPull:         e.IsPull,
 				action:         e.Action,
 				issue:          e.Issue,
 				refLocation:    e.RefLocation,
@@ -329,25 +343,25 @@ func TestCustomizeCloseKeywords(t *testing.T) {
 		{
 			"Simplemente cierra: #29 yes",
 			[]testResult{
-				{29, "", "", "29", XRefActionCloses, &RefSpan{Start: 20, End: 23}, &RefSpan{Start: 12, End: 18}},
+				{29, "", "", "29", false, XRefActionCloses, &RefSpan{Start: 20, End: 23}, &RefSpan{Start: 12, End: 18}},
 			},
 		},
 		{
 			"Closes: #123 no, this English.",
 			[]testResult{
-				{123, "", "", "123", XRefActionNone, &RefSpan{Start: 8, End: 12}, nil},
+				{123, "", "", "123", false, XRefActionNone, &RefSpan{Start: 8, End: 12}, nil},
 			},
 		},
 		{
 			"Cerró user6/repo6#300 yes",
 			[]testResult{
-				{300, "user6", "repo6", "300", XRefActionCloses, &RefSpan{Start: 7, End: 22}, &RefSpan{Start: 0, End: 6}},
+				{300, "user6", "repo6", "300", false, XRefActionCloses, &RefSpan{Start: 7, End: 22}, &RefSpan{Start: 0, End: 6}},
 			},
 		},
 		{
 			"Reabre user3/repo4#200 yes",
 			[]testResult{
-				{200, "user3", "repo4", "200", XRefActionReopens, &RefSpan{Start: 7, End: 22}, &RefSpan{Start: 0, End: 6}},
+				{200, "user3", "repo4", "200", false, XRefActionReopens, &RefSpan{Start: 7, End: 22}, &RefSpan{Start: 0, End: 6}},
 			},
 		},
 	}