✨ [Logs/annotations] add structured CI annotation loggers for GitHub, Azure DevOps, and TeamCity, with adapters for logs.Loggers.

Author: acabarbaye

changes/202607161700.feature

@@ -0,0 +1 @@
+:sparkles: `[Logs/annotations]` add structured CI annotation loggers for GitHub, Azure DevOps, and TeamCity, with adapters for logs.Loggers.

utils/logs/annotations/annotation.go

@@ -0,0 +1,68 @@
+package annotations
+
+import (
+	"github.com/ARM-software/golang-utils/utils/collection"
+	"github.com/ARM-software/golang-utils/utils/field"
+)
+
+// Severity identifies the severity of an annotation.
+type Severity int
+
+//go:generate go tool enumer -type=Severity -text -json -yaml
+
+const (
+	SeverityError Severity = iota
+	SeverityWarning
+	SeverityNotice
+)
+
+// Annotation describes a structured annotation message.
+type Annotation struct {
+	// Severity identifies whether the annotation is an error, warning, or notice.
+	Severity Severity
+	// Message is the human-readable annotation text.
+	Message string
+	// File is the file path associated with the annotation, if any.
+	File string
+	// Line is the 1-based line number associated with the annotation, if any.
+	Line *int
+	// Column is the 1-based column number associated with the annotation, if any.
+	Column *int
+}
+
+// AnnotationOption configures an annotation.
+type AnnotationOption func(*Annotation) *Annotation
+
+// WithFile sets the file path associated with an annotation.
+func WithFile(path string) AnnotationOption {
+	return func(annotation *Annotation) *Annotation {
+		annotation.File = path
+		return annotation
+	}
+}
+
+// WithLine sets the line associated with an annotation.
+func WithLine(line int) AnnotationOption {
+	return func(annotation *Annotation) *Annotation {
+		annotation.Line = field.ToOptionalInt(line)
+		return annotation
+	}
+}
+
+// WithColumn sets the column associated with an annotation.
+func WithColumn(column int) AnnotationOption {
+	return func(annotation *Annotation) *Annotation {
+		annotation.Column = field.ToOptionalInt(column)
+		return annotation
+	}
+}
+
+func newAnnotation(severity Severity, message string, options ...AnnotationOption) Annotation {
+	annotation := Annotation{Severity: severity, Message: message}
+	collection.ForEach(options, func(option AnnotationOption) {
+		if option != nil {
+			annotation = *option(&annotation)
+		}
+	})
+	return annotation
+}

utils/logs/annotations/azure.go

@@ -0,0 +1,63 @@
+package annotations
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/ARM-software/golang-utils/utils/collection"
+	baselogs "github.com/ARM-software/golang-utils/utils/logs"
+	"github.com/ARM-software/golang-utils/utils/reflection"
+)
+
+// AzureDevOpsFormatter formats annotations as Azure DevOps logging commands.
+//
+// Reference:
+//   - https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands
+type AzureDevOpsFormatter struct{}
+
+// NewAzureDevOpsLogger creates an Azure DevOps-formatted annotation logger backed by baseLogger.
+func NewAzureDevOpsLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error) {
+	return NewLogger(baseLogger, AzureDevOpsFormatter{})
+}
+
+func (AzureDevOpsFormatter) Format(annotation *Annotation) string {
+	if annotation == nil {
+		return ""
+	}
+	typeName := strings.ToLower(strings.TrimPrefix(annotation.Severity.String(), "Severity"))
+	if annotation.Severity == SeverityNotice {
+		typeName = "warning"
+	}
+	properties := collection.Filter([]string{
+		fmt.Sprintf("type=%s", typeName),
+		func() string {
+			if reflection.IsEmpty(annotation.File) {
+				return ""
+			}
+			return fmt.Sprintf("sourcepath=%s", escapeAzureProperty(annotation.File))
+		}(),
+		func() string {
+			if annotation.Line == nil {
+				return ""
+			}
+			return fmt.Sprintf("linenumber=%d", *annotation.Line)
+		}(),
+		func() string {
+			if annotation.Column == nil {
+				return ""
+			}
+			return fmt.Sprintf("columnnumber=%d", *annotation.Column)
+		}(),
+	}, func(value string) bool {
+		return reflection.IsNotEmpty(value)
+	})
+	return fmt.Sprintf("##vso[task.logissue %s]%s", strings.Join(properties, ";"), escapeAzureMessage(annotation.Message))
+}
+
+func escapeAzureMessage(value string) string {
+	return strings.NewReplacer("%", "%25", "\r", "%0D", "\n", "%0A").Replace(value)
+}
+
+func escapeAzureProperty(value string) string {
+	return strings.NewReplacer("%", "%25", "\r", "%0D", "\n", "%0A", ";", "%3B", "]", "%5D").Replace(value)
+}

utils/logs/annotations/azure_test.go

@@ -0,0 +1,17 @@
+package annotations
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestAzureDevOpsFormatter(t *testing.T) {
+	formatter := AzureDevOpsFormatter{}
+	line := 8
+	annotation := &Annotation{Severity: SeverityWarning, Message: "problem", File: "pkg/file.go", Line: &line}
+	assert.Equal(t,
+		"##vso[task.logissue type=warning;sourcepath=pkg/file.go;linenumber=8]problem",
+		formatter.Format(annotation),
+	)
+}

utils/logs/annotations/base.go

@@ -0,0 +1,76 @@
+package annotations
+
+import (
+
+	"github.com/ARM-software/golang-utils/utils/commonerrors"
+	baselogs "github.com/ARM-software/golang-utils/utils/logs"
+	"github.com/ARM-software/golang-utils/utils/reflection"
+)
+
+// AnnotationLogger formats annotations and emits them through an underlying
+// logger.
+//
+// The logger delegates final emission to an existing [logs.Loggers]
+// implementation and is therefore suitable for any sink already supported by
+// the logs package.
+type AnnotationLogger struct {
+	baselogs.Loggers
+	formatter IFormatter
+}
+
+// NewLogger creates an annotation logger backed by baseLogger.
+func NewLogger(baseLogger baselogs.Loggers, formatter IFormatter) (*AnnotationLogger, error) {
+	logger := &AnnotationLogger{Loggers: baseLogger, formatter: formatter}
+	if err := logger.Check(); err != nil {
+		return nil, err
+	}
+	return logger, nil
+}
+
+func (l *AnnotationLogger) Check() error {
+	if reflection.IsEmpty(l.Loggers) {
+		return commonerrors.ErrNoLogger
+	}
+	if l.formatter == nil {
+		return commonerrors.UndefinedVariable("annotation formatter")
+	}
+	return l.Loggers.Check()
+}
+
+// WriteAnnotation writes annotation using the configured formatter.
+func (l *AnnotationLogger) WriteAnnotation(annotation *Annotation) error {
+	if err := l.Check(); err != nil {
+		return err
+	}
+	if reflection.IsEmpty(annotation) {
+		return commonerrors.UndefinedVariable("annotation")
+	}
+	line := l.formatter.Format(annotation)
+	switch annotation.Severity {
+	case SeverityError:
+		l.Loggers.LogError(line)
+	default:
+		l.Loggers.Log(line)
+	}
+	return nil
+}
+
+// WriteError writes an error-level annotation.
+func (l *AnnotationLogger) WriteError(message string, options ...AnnotationOption) error {
+	annotation := newAnnotation(SeverityError, message, options...)
+	return l.WriteAnnotation(&annotation)
+}
+
+// WriteWarning writes a warning-level annotation.
+func (l *AnnotationLogger) WriteWarning(message string, options ...AnnotationOption) error {
+	annotation := newAnnotation(SeverityWarning, message, options...)
+	return l.WriteAnnotation(&annotation)
+}
+
+// WriteNotice writes a notice-level annotation.
+func (l *AnnotationLogger) WriteNotice(message string, options ...AnnotationOption) error {
+	annotation := newAnnotation(SeverityNotice, message, options...)
+	return l.WriteAnnotation(&annotation)
+}
+
+var _ IAnnotationLogger = (*AnnotationLogger)(nil)

utils/logs/annotations/base_test.go

@@ -0,0 +1,27 @@
+package annotations
+
+import (
+	"testing"
+
+	baselogs "github.com/ARM-software/golang-utils/utils/logs"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAnnotationLoggerFromLoggers(t *testing.T) {
+	base, err := baselogs.NewPlainStringLogger()
+	require.NoError(t, err)
+
+	logger, err := NewGitHubLogger(base)
+	require.NoError(t, err)
+	line := 3
+	annotation := newAnnotation(SeverityError, "broken", WithFile("pkg/file.go"), WithLine(line))
+	require.NoError(t, logger.WriteAnnotation(&annotation))
+	require.NoError(t, logger.WriteWarning("warn"))
+	require.NoError(t, logger.WriteNotice("note"))
+
+	assert.Equal(t,
+		"::error file=pkg/file.go,line=3::broken\n::warning::warn\n::notice::note\n",
+		base.GetLogContent(),
+	)
+}

utils/logs/annotations/doc.go

@@ -0,0 +1,20 @@
+// Package annotations provides loggers for emitting structured build and CI
+// annotations such as errors, warnings, and notices.
+//
+// Unlike ordinary log lines, annotations are intended for systems that can
+// highlight issues in a richer way, for example by attaching messages to files
+// and line numbers or surfacing build problems prominently in the UI.
+//
+// The package provides a generic annotation model plus platform-specific
+// formatters for common CI systems. Annotation loggers are built on top of the
+// repository's [logs.Loggers] abstraction so they can reuse existing logging
+// sinks.
+//
+// References:
+//   - GitHub Actions workflow commands:
+//     https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
+//   - Azure DevOps logging commands:
+//     https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands
+//   - TeamCity service messages:
+//     https://www.jetbrains.com/help/teamcity/service-messages.html
+package annotations

utils/logs/annotations/github.go

@@ -0,0 +1,63 @@
+package annotations
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/ARM-software/golang-utils/utils/collection"
+	baselogs "github.com/ARM-software/golang-utils/utils/logs"
+	"github.com/ARM-software/golang-utils/utils/reflection"
+)
+
+// GitHubFormatter formats annotations as GitHub Actions annotation commands.
+//
+// Reference:
+//   - https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
+type GitHubFormatter struct{}
+
+// NewGitHubLogger creates a GitHub-formatted annotation logger backed by baseLogger.
+func NewGitHubLogger(baseLogger baselogs.Loggers) (*AnnotationLogger, error) {
+	return NewLogger(baseLogger, GitHubFormatter{})
+}
+
+func (GitHubFormatter) Format(annotation *Annotation) string {
+	if annotation == nil {
+		return ""
+	}
+	command := strings.ToLower(strings.TrimPrefix(annotation.Severity.String(), "Severity"))
+	properties := collection.Filter([]string{
+		func() string {
+			if reflection.IsEmpty(annotation.File) {
+				return ""
+			}
+			return fmt.Sprintf("file=%s", escapeGitHubProperty(annotation.File))
+		}(),
+		func() string {
+			if annotation.Line == nil {
+				return ""
+			}
+			return fmt.Sprintf("line=%d", *annotation.Line)
+		}(),
+		func() string {
+			if annotation.Column == nil {
+				return ""
+			}
+			return fmt.Sprintf("col=%d", *annotation.Column)
+		}(),
+	}, func(value string) bool {
+		return reflection.IsNotEmpty(value)
+	})
+	propertyBlock := ""
+	if len(properties) > 0 {
+		propertyBlock = " " + strings.Join(properties, ",")
+	}
+	return fmt.Sprintf("::%s%s::%s", command, propertyBlock, escapeGitHubMessage(annotation.Message))
+}
+
+func escapeGitHubMessage(value string) string {
+	return strings.NewReplacer("%", "%25", "\r", "%0D", "\n", "%0A").Replace(value)
+}
+
+func escapeGitHubProperty(value string) string {
+	return strings.NewReplacer("%", "%25", "\r", "%0D", "\n", "%0A", ":", "%3A", ",", "%2C").Replace(value)
+}

utils/logs/annotations/github_test.go

@@ -0,0 +1,18 @@
+package annotations
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGitHubFormatter(t *testing.T) {
+	formatter := GitHubFormatter{}
+	line := 12
+	column := 4
+	annotation := &Annotation{Severity: SeverityError, Message: "bad\nmessage", File: "pkg/file.go", Line: &line, Column: &column}
+	assert.Equal(t,
+		"::error file=pkg/file.go,line=12,col=4::bad%0Amessage",
+		formatter.Format(annotation),
+	)
+}