feat(output): annotate github-actions failures at spec file:line

Signed-off-by: caesarsage <destinyerhabor6@gmail.com>

Author: Caesarsage

go.mod

@@ -16,6 +16,7 @@ require (
 	golang.org/x/oauth2 v0.36.0
 	golang.org/x/term v0.40.0
 	gopkg.in/yaml.v2 v2.4.0
+	gopkg.in/yaml.v3 v3.0.1
 	microcks.io/testcontainers-go v0.3.3
 )
 
@@ -73,6 +74,5 @@ require (
 	go.opentelemetry.io/otel/trace v1.41.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 	microcks.io/go-client v0.3.1 // indirect
 )

pkg/output/formatter.go

@@ -42,8 +42,23 @@ type Formatter interface {
 	Format(result *connectors.TestResult) (string, error)
 }
 
+// Option configures a Formatter.
+type Option func(*config)
+
+type config struct {
+	artifactPath string
+}
+
+func WithArtifactPath(path string) Option {
+	return func(c *config) { c.artifactPath = path }
+}
+
 // NewFormatter returns the Formatter for the given format.
-func NewFormatter(format OutputFormat) (Formatter, error) {
+func NewFormatter(format OutputFormat, opts ...Option) (Formatter, error) {
+	c := &config{}
+	for _, o := range opts {
+		o(c)
+	}
 	switch format {
 	case FormatText:
 		return &TextFormatter{}, nil
@@ -52,7 +67,7 @@ func NewFormatter(format OutputFormat) (Formatter, error) {
 	case FormatYAML:
 		return &YAMLFormatter{}, nil
 	case FormatGitHubActions:
-		return &GitHubActionsFormatter{}, nil
+		return &GitHubActionsFormatter{artifactPath: c.artifactPath}, nil
 	default:
 		return nil, fmt.Errorf("unsupported output format %q (use: text, json, yaml, github-actions)", format)
 	}

pkg/output/github_actions_formatter.go

@@ -27,7 +27,9 @@ import (
 // a collapsible ::group:: per operation, ::error:: annotations for failures
 // (and ::notice:: for passes when MICROCKS_ACTIONS_VERBOSE is set), plus a
 // markdown table appended to $GITHUB_STEP_SUMMARY.
-type GitHubActionsFormatter struct{}
+type GitHubActionsFormatter struct {
+	artifactPath string
+}
 
 func (f *GitHubActionsFormatter) Format(r *connectors.TestResult) (string, error) {
 	verbose := os.Getenv("MICROCKS_ACTIONS_VERBOSE") != ""
@@ -42,8 +44,8 @@ func (f *GitHubActionsFormatter) Format(r *connectors.TestResult) (string, error
 		for _, s := range tc.TestStepResults {
 			switch {
 			case !s.Success:
-				fmt.Fprintf(&b, "::error title=%s::%s\n",
-					escapeProperty(tc.OperationName), escapeData(stepMessage(s)))
+				fmt.Fprintf(&b, "::error %s::%s\n",
+					f.errorProperties(tc.OperationName), escapeData(stepMessage(s)))
 			case verbose:
 				fmt.Fprintf(&b, "::notice title=%s::%s passed\n",
 					escapeProperty(tc.OperationName), escapeData(s.RequestName))
@@ -67,6 +69,17 @@ func (f *GitHubActionsFormatter) Format(r *connectors.TestResult) (string, error
 	return b.String(), nil
 }
 
+func (f *GitHubActionsFormatter) errorProperties(operationName string) string {
+	props := []string{"title=" + escapeProperty(operationName)}
+	if f.artifactPath != "" {
+		props = append(props, "file="+escapeProperty(f.artifactPath))
+		if line := operationLine(f.artifactPath, operationName); line > 0 {
+			props = append(props, fmt.Sprintf("line=%d", line))
+		}
+	}
+	return strings.Join(props, ",")
+}
+
 // stepMessage returns the failure message, or a sensible default when empty.
 func stepMessage(s connectors.TestStepResult) string {
 	if strings.TrimSpace(s.Message) != "" {

pkg/output/openapi_linemap.go

@@ -0,0 +1,82 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package output
+
+import (
+	"os"
+	"strings"
+
+	yamlv3 "gopkg.in/yaml.v3"
+)
+
+// operationLine returns the 1-based line of an operation (e.g. "GET /products")
+// within an OpenAPI spec file, or 0 if it can't be determined (non-YAML spec,
+// parse error, or operation not found). yaml.v3 nodes carry line numbers, which
+// yaml.v2 does not expose.
+func operationLine(specPath, operationName string) int {
+	method, path, ok := splitOperation(operationName)
+	if !ok {
+		return 0
+	}
+
+	data, err := os.ReadFile(specPath)
+	if err != nil {
+		return 0
+	}
+
+	var doc yamlv3.Node
+	if err := yamlv3.Unmarshal(data, &doc); err != nil {
+		return 0
+	}
+	root := &doc
+	if root.Kind == yamlv3.DocumentNode && len(root.Content) > 0 {
+		root = root.Content[0]
+	}
+
+	_, pathsNode := mappingEntry(root, "paths")
+	if pathsNode == nil {
+		return 0
+	}
+	_, pathNode := mappingEntry(pathsNode, path)
+	if pathNode == nil {
+		return 0
+	}
+	line, _ := mappingEntry(pathNode, method)
+	return line
+}
+
+// splitOperation parses "GET /products" into ("get", "/products", true).
+func splitOperation(operationName string) (method, path string, ok bool) {
+	parts := strings.SplitN(strings.TrimSpace(operationName), " ", 2)
+	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+		return "", "", false
+	}
+	return strings.ToLower(parts[0]), parts[1], true
+}
+
+// mappingEntry looks up key in a mapping node and returns the key node's line
+// (where "key:" appears) and its value node.
+func mappingEntry(node *yamlv3.Node, key string) (int, *yamlv3.Node) {
+	if node == nil || node.Kind != yamlv3.MappingNode {
+		return 0, nil
+	}
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		if node.Content[i].Value == key {
+			return node.Content[i].Line, node.Content[i+1]
+		}
+	}
+	return 0, nil
+}

pkg/output/output_test.go

@@ -153,3 +153,81 @@ func TestEscaping(t *testing.T) {
 		t.Errorf("escapeProperty = %q", got)
 	}
 }
+
+const specFixture = `openapi: 3.0.0
+info:
+  title: X
+  version: 1.0.0
+paths:
+  /products:
+    get:
+      operationId: getProducts
+      responses:
+        "200":
+          description: ok
+  /orders:
+    post:
+      operationId: placeOrder
+      responses:
+        "201":
+          description: created
+`
+
+func writeSpec(t *testing.T) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "spec.yaml")
+	if err := os.WriteFile(p, []byte(specFixture), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+func TestOperationLine(t *testing.T) {
+	spec := writeSpec(t)
+	cases := map[string]int{
+		"GET /products":    7,  // line of "get:" under /products
+		"POST /orders":     13, // line of "post:" under /orders
+		"GET /nonexistent": 0,
+		"weird":            0, // no method/path split
+	}
+	for op, want := range cases {
+		if got := operationLine(spec, op); got != want {
+			t.Errorf("operationLine(%q) = %d, want %d", op, got, want)
+		}
+	}
+	if got := operationLine("/no/such/file.yaml", "GET /products"); got != 0 {
+		t.Errorf("missing file = %d, want 0", got)
+	}
+}
+
+func TestGitHubActionsFileLineAnnotation(t *testing.T) {
+	spec := writeSpec(t)
+	result := &connectors.TestResult{
+		Success: false,
+		TestCaseResults: []connectors.TestCaseResult{
+			{Success: false, OperationName: "GET /products", TestStepResults: []connectors.TestStepResult{
+				{Success: false, RequestName: "r", Message: "boom"},
+			}},
+		},
+	}
+	formatter, err := NewFormatter(FormatGitHubActions, WithArtifactPath(spec))
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := formatter.Format(result)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"title=GET /products", "file=" + spec, "line=7"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("annotation missing %q\n%s", want, out)
+		}
+	}
+
+	// Without an artifact path, no file/line properties.
+	plain, _ := NewFormatter(FormatGitHubActions)
+	out2, _ := plain.Format(result)
+	if strings.Contains(out2, "file=") || strings.Contains(out2, "line=") {
+		t.Errorf("did not expect file/line without artifact path:\n%s", out2)
+	}
+}