fix: fix generated syscall package description (#369)

* fix: validate doc string

* feat: filter build-constraint files

* fix: update tests

Author: x1unix

internal/pkgindex/parser.go

@@ -57,9 +57,15 @@ func ParseImportCompletionItem(ctx context.Context, params PackageParseParams) (
 			continue
 		}
 
-		// Found a doc string, exit.
 		result.Detail = src.Name.String()
-		docComment := strings.TrimSpace(analyzer.FormatDocString(doc.Text()).Value)
+
+		// Package doc should start with "Package xxx", see issue #367.
+		docComment := strings.TrimSpace(doc.Text())
+		if !validatePackageDoc(docComment) {
+			continue
+		}
+
+		docComment = strings.TrimSpace(analyzer.FormatDocString(docComment).Value)
 		docString = docComment + "\n\n" + docString
 		break
 	}
@@ -71,3 +77,8 @@ func ParseImportCompletionItem(ctx context.Context, params PackageParseParams) (
 	})
 	return result, nil
 }
+
+func validatePackageDoc(str string) bool {
+	normalizedStr := strings.ToLower(str)
+	return strings.HasPrefix(normalizedStr, "package ")
+}

internal/pkgindex/parser_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -13,10 +14,13 @@ import (
 
 func TestParseImportCompletionItem(t *testing.T) {
 	cases := map[string]struct {
-		pkgName    string
-		expectErr  string
-		getContext func() context.Context
-		expect     func(importPath string) monaco.CompletionItem
+		pkgName          string
+		customGoRoot     string
+		expectErr        string
+		filterInputFiles bool
+		getContext       func() context.Context
+		expect           func(importPath string) monaco.CompletionItem
+		compareFunc      func(t *testing.T, got monaco.CompletionItem)
 	}{
 		"package with documentation": {
 			pkgName: "foopkg/pkgbar",
@@ -67,6 +71,15 @@ func TestParseImportCompletionItem(t *testing.T) {
 				return ctx
 			},
 		},
+		"367-syscall-invalid-description": {
+			customGoRoot:     mustGetGoRoot(t) + "/src",
+			pkgName:          "syscall",
+			filterInputFiles: true,
+			compareFunc: func(t *testing.T, got monaco.CompletionItem) {
+				expectPfx := "Package syscall contains an interface to the low-level"
+				expectStartWith(t, got.Documentation.Value.Value, expectPfx)
+			},
+		},
 	}
 
 	const rootDir = "testdata"
@@ -77,25 +90,35 @@ func TestParseImportCompletionItem(t *testing.T) {
 				ctx = c.getContext()
 			}
 
+			goRoot := rootDir
+			if c.customGoRoot != "" {
+				goRoot = c.customGoRoot
+			}
+
 			result, err := ParseImportCompletionItem(ctx, PackageParseParams{
-				RootDir:    rootDir,
+				RootDir:    goRoot,
 				ImportPath: c.pkgName,
-				Files:      findDirFiles(t, rootDir, c.pkgName),
+				Files:      findDirFiles(t, goRoot, c.pkgName, c.filterInputFiles),
 			})
 			if c.expectErr != "" {
 				require.Error(t, err)
 				require.Contains(t, err.Error(), c.expectErr)
 				return
 			}
 
-			expect := c.expect(c.pkgName)
 			require.NoError(t, err)
+			if c.compareFunc != nil {
+				c.compareFunc(t, result)
+				return
+			}
+
+			expect := c.expect(c.pkgName)
 			require.Equal(t, expect, result)
 		})
 	}
 }
 
-func findDirFiles(t *testing.T, dir, pkgName string) []string {
+func findDirFiles(t *testing.T, dir, pkgName string, filterFiles bool) []string {
 	t.Helper()
 	entries, err := os.ReadDir(filepath.Join(dir, pkgName))
 	require.NoError(t, err)
@@ -106,8 +129,26 @@ func findDirFiles(t *testing.T, dir, pkgName string) []string {
 			continue
 		}
 
-		files = append(files, entry.Name())
+		name := entry.Name()
+		if filterFiles {
+			if strings.HasSuffix(name, "_test.go") || !strings.HasSuffix(name, ".go") {
+				continue
+			}
+		}
+
+		files = append(files, name)
 	}
 
 	return files
 }
+
+func mustGetGoRoot(t *testing.T) string {
+	t.Helper()
+	v, err := ResolveGoRoot()
+	require.NoError(t, err)
+	return v
+}
+
+func expectStartWith(t *testing.T, str string, pfx string) {
+	require.Truef(t, strings.HasPrefix(str, pfx), "string %q should start with %q", str, pfx)
+}

internal/pkgindex/scanner.go

@@ -10,15 +10,21 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"regexp"
 	"strings"
 
 	"github.com/x1unix/go-playground/pkg/monaco"
 )
 
 const (
-	resultsPreallocSize = 300
+	queueInitSize = 300
+
+	// resultsInitSize value based on a number of packages in Go 1.22
+	resultsInitSize = 180
 )
 
+var buildContraintRegex = regexp.MustCompile(`(?m)^([\S]+)_(freebsd|darwin|plan9|windows|netbsd|arm|386|loong64|mips|ppc|riscv|s390x)`)
+
 type scanResult struct {
 	hasPkg   bool
 	item     monaco.CompletionItem
@@ -60,7 +66,7 @@ func (s *GoRootScanner) start() ([]monaco.CompletionItem, error) {
 		return nil, fmt.Errorf("cannot open Go SDK directory: %w", err)
 	}
 
-	q := newQueue(resultsPreallocSize)
+	q := newQueue(queueInitSize)
 	for _, entry := range entries {
 		if !entry.Type().IsDir() {
 			continue
@@ -75,7 +81,7 @@ func (s *GoRootScanner) start() ([]monaco.CompletionItem, error) {
 		q.add(pkgName)
 	}
 
-	results := make([]monaco.CompletionItem, 0, resultsPreallocSize)
+	results := make([]monaco.CompletionItem, 0, resultsInitSize)
 	for q.occupied() {
 		pkgName, ok := q.pop()
 		if !ok {
@@ -169,5 +175,19 @@ func shouldIgnoreFileName(fname string) bool {
 		return true
 	}
 
+	if isBuildConstraintFile(fname) {
+		return true
+	}
+
 	return strings.HasSuffix(fname, "_test.go")
 }
+
+// isBuildConstraintFile checks whether file name contains Go build constraint.
+//
+// Linux and "_unix.go" files are allowed to align with GoDoc behavior.
+// Wasm-target files are intentionally allowed to support `syscall/js` package.
+//
+// For example: `foo_amd64.go` or `bar_openbsd_ppc64.go`.
+func isBuildConstraintFile(fname string) bool {
+	return buildContraintRegex.MatchString(fname)
+}

internal/pkgindex/scanner_test.go

@@ -0,0 +1,44 @@
+package pkgindex
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestShouldIgnoreFileName(t *testing.T) {
+	ignoredFiles := []string{
+		"internal",
+		"testdata",
+		"foo_test.go",
+		"bar_windows.go",
+		"foo_darwin.go",
+		"foo_openbsd_arm64.go",
+		"foo_netbsd_riscv64.go",
+		"mmap_unix_test.go",
+		"zerrors_linux_mips64.go",
+	}
+
+	allowFiles := []string{
+		"foo.go",
+		"foo_bar.go",
+		"foo_js.go",
+		"foo_wasm.go",
+		"foo_js_wasm.go",
+		"env_unix.go",
+		"exec_linux.go",
+		"zerrors_linux_amd64.go",
+	}
+
+	t.Run("ignore", func(t *testing.T) {
+		for _, n := range ignoredFiles {
+			require.True(t, shouldIgnoreFileName(n), n)
+		}
+	})
+
+	t.Run("allow", func(t *testing.T) {
+		for _, n := range allowFiles {
+			require.False(t, shouldIgnoreFileName(n), n)
+		}
+	})
+}