BUG/MINOR: spell out expected tag formats in subject errors

When a commit subject fails the tag check, the error only named the
internal policy sets (e.g. "HAProxy Standard Patch") without saying
which tags and severity levels are valid, nor that a bare severity tag
like MINOR is also accepted. Contributors had no actionable guidance
short of reading the CONTRIBUTING link.

Now the errors list the valid tags and severity levels from the policy
config and show the expected subject prefix forms, including the
bare-scope one.

Author: oktalz

check.go

@@ -161,7 +161,25 @@ func (c CommitPolicyConfig) CheckPatchTypes(tag, severity string, patchTypeName
 	return tagScopeOK
 }
 
-var ErrTagScope = errors.New("invalid tag and or severity")
+// allowedTagSummary describes what a tag alternative accepts, so error
+// messages can show expected tags and severity levels instead of internal
+// set names.
+func (c CommitPolicyConfig) allowedTagSummary(patchTypes []string) string {
+	parts := []string{}
+	for _, pType := range patchTypes {
+		pt := c.PatchTypes[pType]
+		if pt.Scope == "" {
+			parts = append(parts, fmt.Sprintf("bare '<TAG>' in [%s] for %s", strings.Join(pt.Values, ", "), pType))
+			continue
+		}
+		parts = append(parts, fmt.Sprintf("'<TAG>/<SEVERITY>' with TAG in [%s] and SEVERITY in [%s] for %s",
+			strings.Join(pt.Values, ", "), strings.Join(c.PatchScopes[pt.Scope], ", "), pType))
+	}
+
+	return strings.Join(parts, "; ")
+}
+
+var ErrTagScope = errors.New("invalid or missing commit tag")
 
 func (c CommitPolicyConfig) CheckSubject(rawSubject []byte, junitSuite junit.Interface) error {
 	// check for ascii-only before anything else
@@ -191,11 +209,12 @@ func (c CommitPolicyConfig) CheckSubject(rawSubject []byte, junitSuite junit.Int
 		if len(submatch) == 0 { // no match
 			if !tagOK {
 				hint := suggestionHint(c.suggestFromSubject(rawSubject, tagAlternative.PatchTypes))
-				junitSuite.AddMessageFailed("", "invalid or missing tag/severity in commit message"+hint, fmt.Sprintf("subject: %s", rawSubject))
+				summary := c.allowedTagSummary(tagAlternative.PatchTypes)
+				junitSuite.AddMessageFailed("", "missing tag prefix in commit message, subject must start with '<TAG>/<SEVERITY>: ' (e.g. 'BUG/MINOR: ') or a bare tag like 'MINOR: ', expected "+summary+hint, fmt.Sprintf("subject: %s", rawSubject))
 				slog.Error("unable to find tag match in subject", "subject", string(rawSubject))
 
-				return fmt.Errorf("invalid tag or no tag found%s, searched through [%s]: %w",
-					hint, strings.Join(tagAlternative.PatchTypes, ", "), ErrTagScope)
+				return fmt.Errorf("missing tag prefix in subject: subject must start with '<TAG>/<SEVERITY>: ' (e.g. 'BUG/MINOR: ') or a bare tag like 'MINOR: ', expected %s%s: %w",
+					summary, hint, ErrTagScope)
 			}
 			continue
 		}
@@ -218,11 +237,12 @@ func (c CommitPolicyConfig) CheckSubject(rawSubject []byte, junitSuite junit.Int
 
 		if !tagOK {
 			hint := suggestionHint(c.suggestTag(tag, severity, tagAlternative.PatchTypes))
-			junitSuite.AddMessageFailed("", "invalid tag/severity in commit message"+hint, fmt.Sprintf("subject: %s", rawSubject))
+			summary := c.allowedTagSummary(tagAlternative.PatchTypes)
+			junitSuite.AddMessageFailed("", fmt.Sprintf("invalid tag/severity '%s' in commit message, expected %s%s", strings.TrimSuffix(strings.TrimSpace(string(tagPart)), ":"), summary, hint), fmt.Sprintf("subject: %s", rawSubject))
 			slog.Error("unable to find valid tag among candidates", "candidates", candidates)
 
-			return fmt.Errorf("invalid tag or no tag found%s, searched through [%s]: %w",
-				hint, strings.Join(tagAlternative.PatchTypes, ", "), ErrTagScope)
+			return fmt.Errorf("invalid tag/severity '%s' in subject: expected %s%s: %w",
+				strings.TrimSuffix(strings.TrimSpace(string(tagPart)), ":"), summary, hint, ErrTagScope)
 		}
 	}