snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

server/public/plugin/checker/check_api.go

@@ -0,0 +1,50 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package main
+
+import (
+	"fmt"
+	"go/ast"
+	"go/token"
+
+	"github.com/mattermost/mattermost/server/public/plugin/checker/internal/asthelpers"
+	"github.com/mattermost/mattermost/server/public/plugin/checker/internal/version"
+)
+
+func checkAPIVersionComments(pkgPath string) (result, error) {
+	pkg, err := asthelpers.GetPackage(pkgPath)
+	if err != nil {
+		return result{}, err
+	}
+
+	apiInterface, err := asthelpers.FindInterface("API", pkg.Syntax)
+	if err != nil {
+		return result{}, err
+	}
+
+	invalidMethods := findInvalidMethods(apiInterface.Methods.List)
+	return result{Errors: renderErrors(pkg.Fset, invalidMethods)}, nil
+}
+
+func findInvalidMethods(methods []*ast.Field) []*ast.Field {
+	var invalid []*ast.Field
+	for _, m := range methods {
+		if !hasValidMinimumVersionComment(m.Doc.Text()) {
+			invalid = append(invalid, m)
+		}
+	}
+	return invalid
+}
+
+func hasValidMinimumVersionComment(s string) bool {
+	return version.ExtractMinimumVersionFromComment(s) != ""
+}
+
+func renderErrors(fset *token.FileSet, methods []*ast.Field) []string {
+	var out []string
+	for _, m := range methods {
+		out = append(out, renderWithFilePosition(fset, m.Pos(), fmt.Sprintf("missing a minimum server version comment on method %s", m.Names[0].Name)))
+	}
+	return out
+}

server/public/plugin/checker/check_api_test.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCheckAPIVersionComments(t *testing.T) {
+	testCases := []struct {
+		name, pkgPath, err string
+		expected           result
+	}{
+		{
+			name:    "valid comments",
+			pkgPath: "github.com/mattermost/mattermost/server/public/plugin/checker/internal/test/valid",
+			err:     "",
+		},
+		{
+			name:    "invalid comments",
+			pkgPath: "github.com/mattermost/mattermost/server/public/plugin/checker/internal/test/invalid",
+			expected: result{
+				Errors: []string{"internal/test/invalid/invalid.go:15:2: missing a minimum server version comment on method InvalidMethod"},
+			},
+		},
+		{
+			name:    "missing API interface",
+			pkgPath: "github.com/mattermost/mattermost/server/public/plugin/checker/internal/test/missing",
+			err:     "could not find API interface",
+		},
+		{
+			name:    "non-existent package path",
+			pkgPath: "github.com/mattermost/mattermost/server/public/plugin/checker/internal/test/does_not_exist",
+			err:     "could not find API interface",
+		},
+	}
+
+	// Enable debug flag to have packagesdriver/sizes.go print stderr of `go list` command.
+	// We want to surface any error text that may exist in stderr of this command.
+	// t.Setenv prevents t.Parallel — env var has no config equivalent
+	t.Setenv("GOPACKAGESPRINTGOLISTERRORS", "true")
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			res, err := checkAPIVersionComments(tc.pkgPath)
+			assert.Equal(t, res, tc.expected)
+
+			if tc.err != "" {
+				assert.EqualError(t, err, tc.err)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}

server/public/plugin/checker/internal/asthelpers/helpers.go

@@ -0,0 +1,127 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package asthelpers
+
+import (
+	"go/ast"
+	"go/types"
+
+	"github.com/pkg/errors"
+	"golang.org/x/tools/go/packages"
+)
+
+func GetPackage(pkgPath string) (*packages.Package, error) {
+	cfg := &packages.Config{
+		Mode: packages.NeedName | packages.NeedTypes | packages.NeedSyntax | packages.NeedTypesInfo,
+	}
+	pkgs, err := packages.Load(cfg, pkgPath)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(pkgs) == 0 {
+		return nil, errors.Errorf("could not find package %s", pkgPath)
+	}
+	return pkgs[0], nil
+}
+
+func FindInterface(name string, files []*ast.File) (*ast.InterfaceType, error) {
+	iface, _, err := FindInterfaceWithIdent(name, files)
+	return iface, err
+}
+
+func FindInterfaceWithIdent(name string, files []*ast.File) (*ast.InterfaceType, *ast.Ident, error) {
+	var (
+		ident *ast.Ident
+		iface *ast.InterfaceType
+	)
+
+	for _, f := range files {
+		ast.Inspect(f, func(n ast.Node) bool {
+			if t, ok := n.(*ast.TypeSpec); ok {
+				if iface != nil {
+					return false
+				}
+
+				if i, ok := t.Type.(*ast.InterfaceType); ok && t.Name.Name == name {
+					ident = t.Name
+					iface = i
+					return false
+				}
+			}
+			return true
+		})
+
+		if iface != nil {
+			return iface, ident, nil
+		}
+	}
+	return nil, nil, errors.Errorf("could not find %s interface", name)
+}
+
+func FindMethodsCalledOnType(info *types.Info, typ types.Type, caller *ast.FuncDecl) []string {
+	var methods []string
+
+	ast.Inspect(caller, func(n ast.Node) bool {
+		if s, ok := n.(*ast.SelectorExpr); ok {
+			var receiver *ast.Ident
+			switch r := s.X.(type) {
+			case *ast.Ident:
+				// Left-hand side of the selector is an identifier, eg:
+				//
+				//   a := p.API
+				//   a.GetTeams()
+				//
+				receiver = r
+			case *ast.SelectorExpr:
+				// Left-hand side of the selector is a selector, eg:
+				//
+				//   p.API.GetTeams()
+				//
+				receiver = r.Sel
+			}
+
+			if receiver != nil {
+				obj := info.ObjectOf(receiver)
+				if obj != nil && types.Identical(obj.Type(), typ) {
+					methods = append(methods, s.Sel.Name)
+				}
+				return false
+			}
+		}
+		return true
+	})
+
+	return methods
+}
+
+func FindReceiverMethods(receiverName string, files []*ast.File) []*ast.FuncDecl {
+	var fns []*ast.FuncDecl
+	for _, f := range files {
+		ast.Inspect(f, func(n ast.Node) bool {
+			if fn, ok := n.(*ast.FuncDecl); ok {
+				r := extractReceiverTypeName(fn)
+				if r == receiverName {
+					fns = append(fns, fn)
+				}
+			}
+			return true
+		})
+	}
+	return fns
+}
+
+func extractReceiverTypeName(fn *ast.FuncDecl) string {
+	if fn.Recv != nil {
+		t := fn.Recv.List[0].Type
+		// Unwrap the pointer type (a star expression)
+		if se, ok := t.(*ast.StarExpr); ok {
+			t = se.X
+		}
+		if id, ok := t.(*ast.Ident); ok {
+			return id.Name
+		}
+	}
+	return ""
+}

server/public/plugin/checker/internal/test/invalid/invalid.go

@@ -0,0 +1,36 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package invalid
+
+type API interface {
+	// ValidMethod is a fake method for testing the
+	// plugin comment checker with a valid comment.
+	//
+	// Minimum server version: 1.2.3
+	ValidMethod()
+
+	// InvalidMethod is a fake method for testing the
+	// plugin comment checker with an invalid comment.
+	InvalidMethod()
+}
+
+type Helpers interface {
+	// Minimum server version: 1.1
+	LowerVersionMethod()
+
+	// Minimum server version: 1.3
+	HigherVersionMethod()
+}
+
+type HelpersImpl struct {
+	api API
+}
+
+func (h *HelpersImpl) LowerVersionMethod() {
+	h.api.ValidMethod()
+}
+
+func (h *HelpersImpl) HigherVersionMethod() {
+	h.api.ValidMethod()
+}

server/public/plugin/checker/internal/test/missing/missing.go

@@ -0,0 +1,7 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package missing
+
+// SomeType is a fake interface for testing the plugin comment checker.
+type SomeType any

server/public/plugin/checker/internal/test/valid/valid.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package valid
+
+type API interface {
+	// ValidMethod is a fake method for testing the
+	// plugin comment checker with a valid comment.
+	//
+	// Minimum server version: 1.2.3
+	ValidMethod()
+
+	// Minimum server version: 1.5
+	NewerValidMethod()
+}
+
+type Helpers interface {
+	// Minimum server version: 1.2.3
+	ValidHelperMethod()
+
+	// Minimum server version: 1.5
+	NewerValidHelperMethod()
+
+	// Minimum server version: 1.5
+	IndirectReferenceMethod()
+}
+
+type HelpersImpl struct {
+	api API
+}
+
+func (h *HelpersImpl) ValidHelperMethod() {
+	h.api.ValidMethod()
+}
+
+func (h *HelpersImpl) NewerValidHelperMethod() {
+	h.api.NewerValidMethod()
+	h.api.ValidMethod()
+}
+
+func (h *HelpersImpl) IndirectReferenceMethod() {
+	a := h.api
+	a.NewerValidMethod()
+}

server/public/plugin/checker/internal/version/comments.go

@@ -0,0 +1,22 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package version
+
+import (
+	"regexp"
+	"strings"
+)
+
+var versionCommentRE = regexp.MustCompile(`^Minimum server version: (\d+\.\d+(?:\.\d+[\w-]*)?)$`)
+
+func ExtractMinimumVersionFromComment(s string) string {
+	lines := strings.Split(strings.TrimSpace(s), "\n")
+	if len(lines) > 0 {
+		lastLine := lines[len(lines)-1]
+		if m := versionCommentRE.FindStringSubmatch(lastLine); len(m) >= 1 {
+			return m[1]
+		}
+	}
+	return ""
+}

server/public/plugin/checker/internal/version/comments_test.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package version
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestExtractVersionFromComment(t *testing.T) {
+	testCases := []struct {
+		input    string
+		expected string
+	}{
+		{
+			input:    "This is a comment.\n\nMinimum server version: 1.2.3-rc1\n",
+			expected: "1.2.3-rc1",
+		},
+		{
+			input:    "This is a comment.\n\nMinimum server version: 1.2.3\n",
+			expected: "1.2.3",
+		},
+		{
+			input:    "This is a comment.\n\nMinimum server version: 1.2\n",
+			expected: "1.2",
+		},
+		{
+			input:    "This is a comment.\n\nMinimum server version: 1\n",
+			expected: "",
+		},
+		{
+			input:    "This is a comment.\n",
+			expected: "",
+		},
+		{
+			input:    "",
+			expected: "",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(fmt.Sprintf("%+v", tc), func(t *testing.T) {
+			assert.Equal(t, tc.expected, ExtractMinimumVersionFromComment(tc.input))
+		})
+	}
+}

server/public/plugin/checker/internal/version/version.go

@@ -0,0 +1,74 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package version
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+type V string
+
+func (v V) GreaterThanOrEqualTo(other V) bool {
+	return !v.LessThan(other)
+}
+
+func (v V) LessThan(other V) bool {
+	leftParts, leftCount := split(v)
+	rightParts, rightCount := split(other)
+
+	length := max(leftCount, rightCount)
+	for i := range length {
+		var left, right string
+
+		if i < leftCount {
+			left = leftParts[i]
+		}
+
+		if i < rightCount {
+			right = rightParts[i]
+		}
+
+		if left == right {
+			continue
+		}
+
+		leftInt := parseInt(left)
+		rightInt := parseInt(right)
+
+		isNumericalComparison := leftInt != nil && rightInt != nil
+
+		if isNumericalComparison {
+			return *leftInt < *rightInt
+		}
+
+		return left < right
+	}
+
+	return false
+}
+
+func split(v V) ([]string, int) {
+	var chunks []string
+
+	for part := range strings.SplitSeq(string(v), ".") {
+		chunks = append(chunks, splitNumericalChunks(part)...)
+	}
+
+	return chunks, len(chunks)
+}
+
+var numericalOrAlphaRE = regexp.MustCompile(`(\d+|\D+)`)
+
+func splitNumericalChunks(s string) []string {
+	return numericalOrAlphaRE.FindAllString(s, -1)
+}
+
+func parseInt(s string) *int64 {
+	if n, err := strconv.ParseInt(s, 10, 64); err == nil {
+		return &n
+	}
+	return nil
+}

server/public/plugin/checker/internal/version/version_test.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package version
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestVersionComparison(t *testing.T) {
+	testCases := []struct {
+		a, b V
+	}{
+		{
+			a: V("1.2"),
+			b: V("1.10"),
+		},
+		{
+			a: V("1.2.1"),
+			b: V("1.2.3"),
+		},
+		{
+			a: V("1.2"),
+			b: V("1.2.3"),
+		},
+		{
+			a: V("1.2.1"),
+			b: V("1.2.3"),
+		},
+		{
+			a: V("1.1"),
+			b: V("1.2.3"),
+		},
+		{
+			a: V("1.2.3"),
+			b: V("1.3"),
+		},
+		{
+			a: V("1.2.1-rc2"),
+			b: V("1.2.1-rc10"),
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(fmt.Sprintf("%+v", tc), func(t *testing.T) {
+			assert.True(t, tc.a.LessThan(tc.b))
+			assert.False(t, tc.b.LessThan(tc.a))
+
+			assert.True(t, tc.b.GreaterThanOrEqualTo(tc.a))
+			assert.False(t, tc.a.GreaterThanOrEqualTo(tc.b))
+		})
+	}
+
+	assert.True(t, V("1.2").GreaterThanOrEqualTo("1.2"))
+}

server/public/plugin/checker/main.go

@@ -0,0 +1,71 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+)
+
+const pluginPackagePath = "github.com/mattermost/mattermost/server/public/plugin"
+
+type result struct {
+	Warnings []string
+	Errors   []string
+}
+
+type checkFn func(pkgPath string) (result, error)
+
+var checks = []checkFn{
+	checkAPIVersionComments,
+}
+
+func main() {
+	var res result
+	for _, check := range checks {
+		res = runCheck(res, check)
+	}
+
+	var msgs []string
+	msgs = append(msgs, res.Errors...)
+	msgs = append(msgs, res.Warnings...)
+	slices.Sort(msgs)
+
+	if len(msgs) > 0 {
+		fmt.Fprintln(os.Stderr, "#", pluginPackagePath)
+		fmt.Fprintln(os.Stderr, strings.Join(msgs, "\n"))
+	}
+
+	if len(res.Errors) > 0 {
+		os.Exit(1)
+	}
+}
+
+func runCheck(prev result, fn checkFn) result {
+	res, err := fn(pluginPackagePath)
+	if err != nil {
+		prev.Errors = append(prev.Errors, err.Error())
+		return prev
+	}
+
+	if len(res.Warnings) > 0 {
+		prev.Warnings = append(prev.Warnings, mapWarnings(res.Warnings)...)
+	}
+
+	if len(res.Errors) > 0 {
+		prev.Errors = append(prev.Errors, res.Errors...)
+	}
+
+	return prev
+}
+
+func mapWarnings(ss []string) []string {
+	var out []string
+	for _, s := range ss {
+		out = append(out, "[warn] "+s)
+	}
+	return out
+}

server/public/plugin/checker/render.go

@@ -0,0 +1,29 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+
+package main
+
+import (
+	"fmt"
+	"go/token"
+	"os"
+	"path/filepath"
+)
+
+func renderWithFilePosition(fset *token.FileSet, pos token.Pos, msg string) string {
+	var cwd string
+	if d, err := os.Getwd(); err == nil {
+		cwd = d
+	}
+
+	fpos := fset.Position(pos)
+
+	filename, err := filepath.Rel(cwd, fpos.Filename)
+	if err != nil {
+		// If deriving a relative path fails for some reason,
+		// we prefer to still print the absolute path to the file.
+		filename = fpos.Filename
+	}
+
+	return fmt.Sprintf("%s:%d:%d: %s", filename, fpos.Line, fpos.Column, msg)
+}