feat: add a package comment linter (#2712)

Update `TestExportedSymbolsHaveDocs` to check that each Go package
includes a top-level doc comment.

Fixes #628

Author: JoeWang1127

all_test.go

@@ -205,9 +205,10 @@ func rungo(t *testing.T, args ...string) {
 }
 
 func TestExportedSymbolsHaveDocs(t *testing.T) {
+	packageHasComment := make(map[string]bool)
 	err := filepath.WalkDir(".", func(path string, d os.DirEntry, err error) error {
 		if err != nil || d.IsDir() || !strings.HasSuffix(path, ".go") ||
-			strings.HasSuffix(path, "_test.go") || strings.HasSuffix(path, ".pb.go") {
+			strings.HasSuffix(path, "_test.go") || strings.HasSuffix(path, ".pb.go") || strings.Contains(path, "testdata") {
 			return nil
 		}
 
@@ -218,6 +219,8 @@ func TestExportedSymbolsHaveDocs(t *testing.T) {
 			return nil
 		}
 
+		recordPackageCommentStatus(t, node, packageHasComment)
+
 		// Visit every top-level declaration in the file.
 		for _, decl := range node.Decls {
 			gen, ok := decl.(*ast.GenDecl)
@@ -242,6 +245,12 @@ func TestExportedSymbolsHaveDocs(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
+
+	for name, hasPkgComment := range packageHasComment {
+		if !hasPkgComment {
+			t.Errorf("package %s does not have package comment", name)
+		}
+	}
 }
 
 func checkDoc(t *testing.T, name *ast.Ident, doc *ast.CommentGroup, path string) {
@@ -254,3 +263,13 @@ func checkDoc(t *testing.T, name *ast.Ident, doc *ast.CommentGroup, path string)
 			path, name.Name)
 	}
 }
+
+// recordPackageCommentStatus updates the seen map with the package comment status for a given package, processing each
+// package only once.
+func recordPackageCommentStatus(t *testing.T, file *ast.File, packageHasComment map[string]bool) {
+	t.Helper()
+	pkg := file.Name.String()
+	if !packageHasComment[pkg] {
+		packageHasComment[pkg] = file.Doc != nil
+	}
+}

internal/automation/cli.go

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package automation implements the command-line interface and core logic
+// for Librarian's automated workflows.
 package automation
 
 import (

internal/container/java/bazel/parser.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package bazel provides utilities for parsing BUILD.bazel files.
 package bazel
 
 import (

internal/container/java/execv/execv.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package execv provides a helper function for executing external commands.
 package execv
 
 import (

internal/container/java/pom/pom.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package pom handles the generation of Maven pom.xml files for a Java library.
 package pom
 
 import (

internal/container/java/protoc/protoc.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package protoc provides utilities for constructing protoc command arguments.
 package protoc
 
 import (

internal/librarian/librarian.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package librarian provides the core implementation for the Librarian CLI tool.
 package librarian
 
 import (

internal/semver/semver.go

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package semver provides functionality for parsing, comparing, and manipulating
+// semantic version strings according to the SemVer 2.0.0 spec.
 package semver
 
 import (
@@ -25,7 +27,7 @@ import (
 // Version represents a semantic version.
 type Version struct {
 	Major, Minor, Patch int
-	// Prerelease is the non-numeric part of the pre-release string (e.g., "alpha", "beta").
+	// Prerelease is the non-numeric part of the prerelease string (e.g., "alpha", "beta").
 	Prerelease string
 	// PrereleaseSeparator is the separator between the pre-release string and
 	// its version (e.g., ".").

internal/sidekick/internal/api/apitest/apitest.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package apitest provides helper functions for testing the api package.
 package apitest
 
 import (

internal/sidekick/internal/api/model.go

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package api defines the data model representing a parsed API surface.
 package api
 
 import (