devtools/cmd/evaldoc/main.go - pkgsite - Git at Google

 // Copyright 2026 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // The evaldoc command is an HTTP server that takes a module_path@version or a local directory path,
 // loads the module, and serves:
 //   - Root (/): A list of all import paths in the module with counts of symbols that have and need
 //     documentation.
 //   - /<importPath>: A list of files in that package directory with counts of symbols that have
 //     and need documentation.
 //   - /<importPath>/<filename>: The contents of that file with symbol documentation highlighting.
 //
 // It can be used to better understand the "documentation coverage" score
 // on a package's evaluations page (pkg.go.dev/IMPORT/PATH?tab=evals).
 // Run it on your module to get a list of symbols which need documentation,
 // and whether they have documentation.
 package main

 import (
 	"cmp"
 	"context"
 	"errors"
 	"flag"
 	"fmt"
 	"go/ast"
 	"go/parser"
 	"go/token"
 	"html/template"
 	"io/fs"
 	"log"
 	"math"
 	"net"
 	"net/http"
 	"os"
 	"path"
 	"path/filepath"
 	"slices"
 	"strings"

 	"golang.org/x/mod/modfile"
 	"golang.org/x/pkgsite/internal/frontend"
 	"golang.org/x/pkgsite/internal/proxy"
 )

 var (
 	httpAddr = flag.String("http", ":0", "address to listen on")
 	proxyURL = flag.String("proxy", "", "module proxy URL (defaults to GOPROXY or https://proxy.golang.org)")
 )

 // highlight is a byte range [start, end) in a source file corresponding to a symbol
 // identifier, and whether that symbol has documentation.
 type highlight struct {
 	start int
 	end   int
 	has   bool
 }

 // importPathItem contains documentation coverage statistics for a package import
 // path.
 // Fields are exported because this struct appears in a template argument.
 type importPathItem struct {
 	ImportPath       string
 	NumHave, NumNeed int // number of symbols that have/need doc
 	NeedPct          int // percentage of symbols that need doc
 }

 // fileItem contains documentation coverage statistics for an individual source file.
 // Fields are exported because this struct appears in a template argument.
 type fileItem struct {
 	Filename         string
 	NumHave, NumNeed int // number of symbols that have/need doc
 	NeedPct          int // percentage of symbols that need doc
 }

 // server holds state and pre-rendered HTML data for serving the evaldoc web UI.
 type server struct {
 	modulePath      string
 	resolvedVersion string
 	importPaths     []importPathItem
 	dirFiles        map[string][]fileItem    // importPath -> list of file items
 	fileHTML        map[string]template.HTML // importPath + "/" + filename -> HTML content
 }

 func main() {
 	flag.Usage = func() {
 		fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [flags] (module_path@version | local_dir_path)\n", os.Args[0])
 		fmt.Fprintln(flag.CommandLine.Output(), "local_dir_path must start with one of: / . ~")
 		flag.PrintDefaults()
 	}
 	flag.Parse()

 	if flag.NArg() == 0 {
 		flag.Usage()
 		os.Exit(1)
 	}

 	arg := flag.Arg(0)
 	modulePath, resolvedVersion, contentDir, err := getContentDir(arg)
 	if err != nil {
 		log.Fatal(err)
 	}

 	s, err := newServer(modulePath, resolvedVersion, contentDir)
 	if err != nil {
 		log.Fatalf("newServer: %v", err)
 	}

 	addr := *httpAddr
 	if addr == "" {
 		addr = ":0"
 	}
 	ln, err := net.Listen("tcp", addr)
 	if err != nil {
 		log.Fatal(err)
 	}

 	log.Printf("Serving %s@%s on %s", modulePath, resolvedVersion, ln.Addr())
 	if err := http.Serve(ln, s); err != nil {
 		log.Fatal(err)
 	}
 }

 // resolveLocalPath expands a leading "~" to the user's home directory and returns
 // the absolute path of arg.
 func resolveLocalPath(arg string) (string, error) {
 	if strings.HasPrefix(arg, "~") {
 		home, err := os.UserHomeDir()
 		if err != nil {
 			return "", fmt.Errorf("arg is local path, but cannot get home directory: %v", err)
 		}
 		arg = filepath.Join(home, arg[1:])
 	}
 	return filepath.Abs(arg)
 }

 // getContentDir uses arg to find a module, and returns an fs.FS whose root is the
 // content directory of that module (the directory containing the go.mod file).
 // It also returns the module path and the version, with "latest" resolved to a specific version.
 func getContentDir(arg string) (modulePath, resolvedVersion string, contentDir fs.FS, err error) {
 	if len(arg) == 0 {
 		return "", "", nil, errors.New("empty argument")
 	}
 	if arg[0] == '/' || arg[0] == '.' || arg[0] == '~' {
 		localPath, err := resolveLocalPath(arg)
 		if err != nil {
 			return "", "", nil, fmt.Errorf("failed to resolve path %s: %w", arg, err)
 		}
 		fi, err := os.Stat(localPath)
 		if err != nil || !fi.IsDir() {
 			return "", "", nil, fmt.Errorf("%s is not a directory", localPath)
 		}
 		modBytes, err := os.ReadFile(filepath.Join(localPath, "go.mod"))
 		if err != nil {
 			return "", "", nil, fmt.Errorf("failed to read go.mod in %s: %w", localPath, err)
 		}
 		modulePath = modfile.ModulePath(modBytes)
 		if modulePath == "" {
 			return "", "", nil, fmt.Errorf("go.mod in %s contains no module path", localPath)
 		}
 		return modulePath, "local", os.DirFS(localPath), nil
 	}

 	var reqVer string
 	var found bool
 	modulePath, reqVer, found = strings.Cut(arg, "@")
 	if !found || reqVer == "" {
 		reqVer = "latest"
 	}

 	pURL := *proxyURL
 	if pURL == "" {
 		pURL = os.Getenv("GOPROXY")
 	}
 	if pURL == "off" {
 		return "", "", nil, errors.New("GOPROXY is off")
 	}
 	if pURL == "" {
 		pURL = "https://proxy.golang.org"
 	}
 	// Take the first URL from the GOPROXY list.
 	if idx := strings.IndexAny(pURL, ",|"); idx != -1 {
 		pURL = pURL[:idx]
 	}

 	ctx := context.Background()
 	proxyClient, err := proxy.New(pURL, http.DefaultTransport)
 	if err != nil {
 		return "", "", nil, fmt.Errorf("proxy.New(%q): %w", pURL, err)
 	}
 	proxyClient = proxyClient.WithFetchDisabled()

 	verInfo, err := proxyClient.Info(ctx, modulePath, reqVer)
 	if err != nil {
 		return "", "", nil, fmt.Errorf("proxyClient.Info(%q, %q): %w", modulePath, reqVer, err)
 	}
 	resolvedVersion = verInfo.Version

 	zipReader, err := proxyClient.Zip(ctx, modulePath, resolvedVersion)
 	if err != nil {
 		return "", "", nil, fmt.Errorf("proxyClient.Zip(%q, %q): %w", modulePath, resolvedVersion, err)
 	}

 	contentDir, err = fs.Sub(zipReader, modulePath+"@"+resolvedVersion)
 	if err != nil {
 		return "", "", nil, fmt.Errorf("fs.Sub: %w", err)
 	}

 	return modulePath, resolvedVersion, contentDir, nil
 }

 // packageDirs walks contentDir to find directories corresponding to valid import paths,
 // and returns their relative paths.
 func packageDirs(contentDir fs.FS) ([]string, error) {
 	var dirs []string
 	err := fs.WalkDir(contentDir, ".", func(p string, d fs.DirEntry, err error) error {
 		if err != nil {
 			return err
 		}
 		if !d.IsDir() {
 			return nil
 		}
 		// Skip directory trees under internal, vendor and testdata.
 		name := d.Name()
 		if name == "internal" || name == "vendor" || name == "testdata" {
 			return fs.SkipDir
 		}
 		// Skip directory trees if the name starts with a ".", other than "." itself.
 		if len(name) >= 2 && name[0] == '.' {
 			return fs.SkipDir
 		}
 		dirs = append(dirs, p)
 		return nil
 	})
 	if err != nil {
 		return nil, err
 	}
 	return dirs, nil
 }

 // newServer parses and analyzes all non-internal Go package files in contentDir,
 // calculates symbol documentation statistics, pre-renders HTML views, and returns
 // a server for modulePath and resolvedVersion.
 func newServer(modulePath, resolvedVersion string, contentDir fs.FS) (*server, error) {
 	// Phase 1: Walk contentDir to get the set of valid package directories.
 	dirs, err := packageDirs(contentDir)
 	if err != nil {
 		return nil, err
 	}

 	// Phase 2: For each package directory, parse its files and collect symbols.
 	dirFiles := make(map[string][]fileItem)
 	fileHTML := make(map[string]template.HTML)
 	dirHaveCounts := make(map[string]int)
 	dirNeedCounts := make(map[string]int)
 	var rawImportPaths []string

 	for _, relDir := range dirs {
 		importPath := modulePath
 		if relDir != "." && relDir != "" {
 			importPath = path.Join(modulePath, relDir)
 		}
 		entries, err := fs.ReadDir(contentDir, relDir)
 		if err != nil {
 			return nil, err
 		}

 		var fileNames []string
 		fset := token.NewFileSet()
 		var astFiles []*ast.File
 		fileSrcs := make(map[string][]byte)

 		for _, entry := range entries {
 			if entry.IsDir() {
 				continue
 			}
 			fname := entry.Name()
 			// Ignore test files and files that aren't go.
 			if !strings.HasSuffix(fname, ".go") || strings.HasSuffix(fname, "_test.go") {
 				continue
 			}
 			fileNames = append(fileNames, fname)

 			fp := path.Join(relDir, fname)
 			content, err := fs.ReadFile(contentDir, fp)
 			if err != nil {
 				fmt.Fprintf(os.Stderr, "%s: reading: %v\n", fp, err)
 				continue
 			}
 			fileSrcs[fname] = content

 			f, err := parser.ParseFile(fset, fname, content, parser.ParseComments)
 			if err == nil {
 				astFiles = append(astFiles, f)
 			} else {
 				fmt.Fprintf(os.Stderr, "%s: parsing: %v\n", fp, err)
 			}
 		}

 		if len(astFiles) == 0 {
 			continue
 		}

 		rawImportPaths = append(rawImportPaths, importPath)

 		fileHighlights := make(map[string][]highlight)
 		fileNumHave := make(map[string]int)
 		fileNumNeed := make(map[string]int)
 		pkgNumHave := 0
 		pkgNumNeed := 0

 		// Call the same function used by the evals page to summarize documentation.
 		frontend.CollectSymbols(astFiles, func(id *ast.Ident, has bool) {
 			pos := fset.Position(id.Pos())
 			end := fset.Position(id.End())

 			fileHighlights[pos.Filename] = append(fileHighlights[pos.Filename], highlight{
 				start: pos.Offset,
 				end:   end.Offset,
 				has:   has,
 			})
 			if has {
 				fileNumHave[pos.Filename]++
 				pkgNumHave++
 			} else {
 				fileNumNeed[pos.Filename]++
 				pkgNumNeed++
 			}
 		})

 		var fileItems []fileItem
 		for _, fname := range fileNames {
 			src := fileSrcs[fname]
 			key := importPath + "/" + fname
 			fileHTML[key] = formatHighlightedFile(src, fileHighlights[fname])

 			g := fileNumHave[fname]
 			r := fileNumNeed[fname]
 			fileItems = append(fileItems, fileItem{
 				Filename: fname,
 				NumHave:  g,
 				NumNeed:  r,
 				NeedPct:  percent(g, r),
 			})
 		}
 		slices.SortFunc(fileItems, func(a, b fileItem) int {
 			if c := cmp.Compare(b.NumNeed, a.NumNeed); c != 0 {
 				return c
 			}
 			return cmp.Compare(a.Filename, b.Filename)
 		})
 		dirFiles[importPath] = fileItems
 		dirHaveCounts[importPath] = pkgNumHave
 		dirNeedCounts[importPath] = pkgNumNeed
 	}

 	var importPathItems []importPathItem
 	for _, ip := range rawImportPaths {
 		g := dirHaveCounts[ip]
 		r := dirNeedCounts[ip]
 		importPathItems = append(importPathItems, importPathItem{
 			ImportPath: ip,
 			NumHave:    g,
 			NumNeed:    r,
 			NeedPct:    percent(g, r),
 		})
 	}

 	slices.SortFunc(importPathItems, func(a, b importPathItem) int {
 		if c := cmp.Compare(b.NumNeed, a.NumNeed); c != 0 {
 			return c
 		}
 		return cmp.Compare(a.ImportPath, b.ImportPath)
 	})

 	return &server{
 		modulePath:      modulePath,
 		resolvedVersion: resolvedVersion,
 		importPaths:     importPathItems,
 		dirFiles:        dirFiles,
 		fileHTML:        fileHTML,
 	}, nil
 }

 // percent returns the percentage of m/ (n + m), rounded to the nearest integer.
 // It returns 0 if n + m is 0.
 func percent(n, m int) int {
 	total := n + m
 	if total == 0 {
 		return 0
 	}
 	return int(math.Round(float64(m) * 100 / float64(total)))
 }

 func formatHighlightedFile(src []byte, highlights []highlight) template.HTML {
 	slices.SortFunc(highlights, func(a, b highlight) int {
 		return cmp.Compare(a.start, b.start)
 	})

 	var buf strings.Builder
 	last := 0
 	for _, h := range highlights {
 		if h.start < last || h.start > len(src) || h.end > len(src) {
 			continue
 		}
 		buf.WriteString(template.HTMLEscapeString(string(src[last:h.start])))
 		if h.has {
 			buf.WriteString(`<span class="has-doc">`)
 		} else {
 			buf.WriteString(`<span class="need-doc">`)
 		}
 		buf.WriteString(template.HTMLEscapeString(string(src[h.start:h.end])))
 		buf.WriteString(`</span>`)
 		last = h.end
 	}
 	if last < len(src) {
 		buf.WriteString(template.HTMLEscapeString(string(src[last:])))
 	}

 	return template.HTML(buf.String())
 }

 func (s *server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.URL.Path == "/" {
 		s.handleRoot(w)
 		return
 	}
 	if r.URL.Path == "/styles.css" {
 		w.Header().Set("Content-Type", "text/css; charset=utf-8")
 		fmt.Fprint(w, stylesCSS)
 		return
 	}

 	p := strings.TrimPrefix(r.URL.Path, "/")
 	if files, ok := s.dirFiles[p]; ok {
 		s.handleDir(w, p, files)
 		return
 	}

 	if contentHTML, ok := s.fileHTML[p]; ok {
 		s.handleFile(w, p, contentHTML)
 		return
 	}

 	http.NotFound(w, r)
 }

 const stylesCSS = `
 	body { font-family: sans-serif; margin: 20px; }
 	.has-doc { color: #1a7f37; font-weight: bold; margin-left: 4px; }
 	.need-doc { color: #cf222e; font-weight: bold; margin-left: 4px; }
 	.need-pct { color: #000; font-weight: bold; margin-left: 4px; }
 	pre {
 		font-family: monospace; background-color: #f6f8fa;
 	    padding: 16px; border-radius: 6px; overflow: auto;
 	}
 	.legend { font-family: sans-serif; margin-bottom: 1em; }
 	pre .has-doc, .legend .has-doc {
 		background-color: #dafbe1; padding: 0 2px; border-radius: 2px; margin-left: 0;
 	}
 	pre .need-doc, .legend .need-doc {
 		background-color: #ffebe9; padding: 0 2px; border-radius: 2px; margin-left: 0;
 	}
 `

 var rootTmpl = template.Must(template.New("root").Parse(`<!DOCTYPE html>
 <html>
 <head>
 	<meta charset="utf-8">
 	<title>Module {{.ModulePath}}@{{.Version}}</title>
 	<link rel="stylesheet" href="/styles.css">
 </head>
 <body>
 	<h1>Module {{.ModulePath}}@{{.Version}}
 	    <span class="has-doc">{{.NumHave}}</span>
 	    <span class="need-doc">{{.NumNeed}}</span>
 	    <span class="need-pct">{{.NeedPct}}%</span>
 	</h1>
 	<h2>Packages</h2>
 	<ul>
 		{{range .ImportPaths}}
 			<li>
 				<a href="/{{.ImportPath}}">{{.ImportPath}}</a>
 				<span class="has-doc">{{.NumHave}}</span>
 				<span class="need-doc">{{.NumNeed}}</span>
 				<span class="need-pct">{{.NeedPct}}%</span>
 			</li>
 		{{end}}
 	</ul>
 </body>
 </html>`))

 func (s *server) handleRoot(w http.ResponseWriter) {
 	w.Header().Set("Content-Type", "text/html; charset=utf-8")
 	var have, need int
 	for _, item := range s.importPaths {
 		have += item.NumHave
 		need += item.NumNeed
 	}
 	data := struct {
 		ModulePath       string
 		Version          string
 		NumHave, NumNeed int
 		NeedPct          int
 		ImportPaths      []importPathItem
 	}{
 		ModulePath:  s.modulePath,
 		Version:     s.resolvedVersion,
 		NumHave:     have,
 		NumNeed:     need,
 		NeedPct:     percent(have, need),
 		ImportPaths: s.importPaths,
 	}
 	rootTmpl.Execute(w, data)
 }

 var dirTmpl = template.Must(template.New("dir").Parse(`<!DOCTYPE html>
 <html>
 <head>
 	<meta charset="utf-8">
 	<title>Files in {{.ImportPath}}</title>
 	<link rel="stylesheet" href="/styles.css">
 </head>
 <body>
 	<p><a href="/">
 	     Back to Packages</a></p>
 	<h1>Files in {{.ImportPath}}</h1>
 	<ul>
 		{{range .Files}}
 			<li>
 				<a href="/{{$.ImportPath}}/{{.Filename}}">{{.Filename}}</a>
 				<span class="has-doc">{{.NumHave}}</span>
 				<span class="need-doc">{{.NumNeed}}</span>
 				<span class="need-pct">{{.NeedPct}}%</span>
 			</li>
 		{{end}}
 	</ul>
 </body>
 </html>`))

 func (s *server) handleDir(w http.ResponseWriter, importPath string, files []fileItem) {
 	w.Header().Set("Content-Type", "text/html; charset=utf-8")
 	data := struct {
 		ImportPath string
 		Files      []fileItem
 	}{
 		ImportPath: importPath,
 		Files:      files,
 	}
 	dirTmpl.Execute(w, data)
 }

 var fileTmpl = template.Must(template.New("file").Parse(`<!DOCTYPE html>
 <html>
 <head>
 	<meta charset="utf-8">
 	<title>{{.Filename}} - {{.ImportPath}}</title>
 	<link rel="stylesheet" href="/styles.css">
 </head>
 <body>
 	<p><a href="/{{.ImportPath}}">← Back to {{.ImportPath}}</a></p>
 	<div class="legend">
 		Symbol status:
 		<span class="has-doc">Documented (Green)</span> |
 		<span class="need-doc">Undocumented (Red)</span>
 	</div>
 	<h1>{{.Filename}}</h1>
 	<pre><code>{{.Contents}}</code></pre>
 </body>
 </html>`))

 func (s *server) handleFile(w http.ResponseWriter, key string, contentHTML template.HTML) {
 	var importPath, filename string
 	for ip := range s.dirFiles {
 		if after, ok := strings.CutPrefix(key, ip+"/"); ok {
 			if len(ip) > len(importPath) {
 				importPath = ip
 				filename = after
 			}
 		}
 	}

 	w.Header().Set("Content-Type", "text/html; charset=utf-8")
 	fileData := struct {
 		ImportPath string
 		Filename   string
 		Contents   template.HTML
 	}{
 		ImportPath: importPath,
 		Filename:   filename,
 		Contents:   contentHTML,
 	}
 	fileTmpl.Execute(w, fileData)
 }
	// Copyright 2026 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// The evaldoc command is an HTTP server that takes a module_path@version or a local directory path,
	// loads the module, and serves:
	// - Root (/): A list of all import paths in the module with counts of symbols that have and need
	// documentation.
	// - /<importPath>: A list of files in that package directory with counts of symbols that have
	// and need documentation.
	// - /<importPath>/<filename>: The contents of that file with symbol documentation highlighting.
	//
	// It can be used to better understand the "documentation coverage" score
	// on a package's evaluations page (pkg.go.dev/IMPORT/PATH?tab=evals).
	// Run it on your module to get a list of symbols which need documentation,
	// and whether they have documentation.
	package main

	import (
	"cmp"
	"context"
	"errors"
	"flag"
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
	"html/template"
	"io/fs"
	"log"
	"math"
	"net"
	"net/http"
	"os"
	"path"
	"path/filepath"
	"slices"
	"strings"

	"golang.org/x/mod/modfile"
	"golang.org/x/pkgsite/internal/frontend"
	"golang.org/x/pkgsite/internal/proxy"
	)

	var (
	httpAddr = flag.String("http", ":0", "address to listen on")
	proxyURL = flag.String("proxy", "", "module proxy URL (defaults to GOPROXY or https://proxy.golang.org)")
	)

	// highlight is a byte range [start, end) in a source file corresponding to a symbol
	// identifier, and whether that symbol has documentation.
	type highlight struct {
	start int
	end int
	has bool
	}

	// importPathItem contains documentation coverage statistics for a package import
	// path.
	// Fields are exported because this struct appears in a template argument.
	type importPathItem struct {
	ImportPath string
	NumHave, NumNeed int // number of symbols that have/need doc
	NeedPct int // percentage of symbols that need doc
	}

	// fileItem contains documentation coverage statistics for an individual source file.
	// Fields are exported because this struct appears in a template argument.
	type fileItem struct {
	Filename string
	NumHave, NumNeed int // number of symbols that have/need doc
	NeedPct int // percentage of symbols that need doc
	}

	// server holds state and pre-rendered HTML data for serving the evaldoc web UI.
	type server struct {
	modulePath string
	resolvedVersion string
	importPaths []importPathItem
	dirFiles map[string][]fileItem // importPath -> list of file items
	fileHTML map[string]template.HTML // importPath + "/" + filename -> HTML content
	}

	func main() {
	flag.Usage = func() {
	fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [flags] (module_path@version \| local_dir_path)\n", os.Args[0])
	fmt.Fprintln(flag.CommandLine.Output(), "local_dir_path must start with one of: / . ~")
	flag.PrintDefaults()
	}
	flag.Parse()

	if flag.NArg() == 0 {
	flag.Usage()
	os.Exit(1)
	}

	arg := flag.Arg(0)
	modulePath, resolvedVersion, contentDir, err := getContentDir(arg)
	if err != nil {
	log.Fatal(err)
	}

	s, err := newServer(modulePath, resolvedVersion, contentDir)
	if err != nil {
	log.Fatalf("newServer: %v", err)
	}

	addr := *httpAddr
	if addr == "" {
	addr = ":0"
	}
	ln, err := net.Listen("tcp", addr)
	if err != nil {
	log.Fatal(err)
	}

	log.Printf("Serving %s@%s on %s", modulePath, resolvedVersion, ln.Addr())
	if err := http.Serve(ln, s); err != nil {
	log.Fatal(err)
	}
	}

	// resolveLocalPath expands a leading "~" to the user's home directory and returns
	// the absolute path of arg.
	func resolveLocalPath(arg string) (string, error) {
	if strings.HasPrefix(arg, "~") {
	home, err := os.UserHomeDir()
	if err != nil {
	return "", fmt.Errorf("arg is local path, but cannot get home directory: %v", err)
	}
	arg = filepath.Join(home, arg[1:])
	}
	return filepath.Abs(arg)
	}

	// getContentDir uses arg to find a module, and returns an fs.FS whose root is the
	// content directory of that module (the directory containing the go.mod file).
	// It also returns the module path and the version, with "latest" resolved to a specific version.
	func getContentDir(arg string) (modulePath, resolvedVersion string, contentDir fs.FS, err error) {
	if len(arg) == 0 {
	return "", "", nil, errors.New("empty argument")
	}
	if arg[0] == '/' \|\| arg[0] == '.' \|\| arg[0] == '~' {
	localPath, err := resolveLocalPath(arg)
	if err != nil {
	return "", "", nil, fmt.Errorf("failed to resolve path %s: %w", arg, err)
	}
	fi, err := os.Stat(localPath)
	if err != nil \|\| !fi.IsDir() {
	return "", "", nil, fmt.Errorf("%s is not a directory", localPath)
	}
	modBytes, err := os.ReadFile(filepath.Join(localPath, "go.mod"))
	if err != nil {
	return "", "", nil, fmt.Errorf("failed to read go.mod in %s: %w", localPath, err)
	}
	modulePath = modfile.ModulePath(modBytes)
	if modulePath == "" {
	return "", "", nil, fmt.Errorf("go.mod in %s contains no module path", localPath)
	}
	return modulePath, "local", os.DirFS(localPath), nil
	}

	var reqVer string
	var found bool
	modulePath, reqVer, found = strings.Cut(arg, "@")
	if !found \|\| reqVer == "" {
	reqVer = "latest"
	}

	pURL := *proxyURL
	if pURL == "" {
	pURL = os.Getenv("GOPROXY")
	}
	if pURL == "off" {
	return "", "", nil, errors.New("GOPROXY is off")
	}
	if pURL == "" {
	pURL = "https://proxy.golang.org"
	}
	// Take the first URL from the GOPROXY list.
	if idx := strings.IndexAny(pURL, ",\|"); idx != -1 {
	pURL = pURL[:idx]
	}

	ctx := context.Background()
	proxyClient, err := proxy.New(pURL, http.DefaultTransport)
	if err != nil {
	return "", "", nil, fmt.Errorf("proxy.New(%q): %w", pURL, err)
	}
	proxyClient = proxyClient.WithFetchDisabled()

	verInfo, err := proxyClient.Info(ctx, modulePath, reqVer)
	if err != nil {
	return "", "", nil, fmt.Errorf("proxyClient.Info(%q, %q): %w", modulePath, reqVer, err)
	}
	resolvedVersion = verInfo.Version

	zipReader, err := proxyClient.Zip(ctx, modulePath, resolvedVersion)
	if err != nil {
	return "", "", nil, fmt.Errorf("proxyClient.Zip(%q, %q): %w", modulePath, resolvedVersion, err)
	}

	contentDir, err = fs.Sub(zipReader, modulePath+"@"+resolvedVersion)
	if err != nil {
	return "", "", nil, fmt.Errorf("fs.Sub: %w", err)
	}

	return modulePath, resolvedVersion, contentDir, nil
	}

	// packageDirs walks contentDir to find directories corresponding to valid import paths,
	// and returns their relative paths.
	func packageDirs(contentDir fs.FS) ([]string, error) {
	var dirs []string
	err := fs.WalkDir(contentDir, ".", func(p string, d fs.DirEntry, err error) error {
	if err != nil {
	return err
	}
	if !d.IsDir() {
	return nil
	}
	// Skip directory trees under internal, vendor and testdata.
	name := d.Name()
	if name == "internal" \|\| name == "vendor" \|\| name == "testdata" {
	return fs.SkipDir
	}
	// Skip directory trees if the name starts with a ".", other than "." itself.
	if len(name) >= 2 && name[0] == '.' {
	return fs.SkipDir
	}
	dirs = append(dirs, p)
	return nil
	})
	if err != nil {
	return nil, err
	}
	return dirs, nil
	}

	// newServer parses and analyzes all non-internal Go package files in contentDir,
	// calculates symbol documentation statistics, pre-renders HTML views, and returns
	// a server for modulePath and resolvedVersion.
	func newServer(modulePath, resolvedVersion string, contentDir fs.FS) (*server, error) {
	// Phase 1: Walk contentDir to get the set of valid package directories.
	dirs, err := packageDirs(contentDir)
	if err != nil {
	return nil, err
	}

	// Phase 2: For each package directory, parse its files and collect symbols.
	dirFiles := make(map[string][]fileItem)
	fileHTML := make(map[string]template.HTML)
	dirHaveCounts := make(map[string]int)
	dirNeedCounts := make(map[string]int)
	var rawImportPaths []string

	for _, relDir := range dirs {
	importPath := modulePath
	if relDir != "." && relDir != "" {
	importPath = path.Join(modulePath, relDir)
	}
	entries, err := fs.ReadDir(contentDir, relDir)
	if err != nil {
	return nil, err
	}

	var fileNames []string
	fset := token.NewFileSet()
	var astFiles []*ast.File
	fileSrcs := make(map[string][]byte)

	for _, entry := range entries {
	if entry.IsDir() {
	continue
	}
	fname := entry.Name()
	// Ignore test files and files that aren't go.
	if !strings.HasSuffix(fname, ".go") \|\| strings.HasSuffix(fname, "_test.go") {
	continue
	}
	fileNames = append(fileNames, fname)

	fp := path.Join(relDir, fname)
	content, err := fs.ReadFile(contentDir, fp)
	if err != nil {
	fmt.Fprintf(os.Stderr, "%s: reading: %v\n", fp, err)
	continue
	}
	fileSrcs[fname] = content

	f, err := parser.ParseFile(fset, fname, content, parser.ParseComments)
	if err == nil {
	astFiles = append(astFiles, f)
	} else {
	fmt.Fprintf(os.Stderr, "%s: parsing: %v\n", fp, err)
	}
	}

	if len(astFiles) == 0 {
	continue
	}

	rawImportPaths = append(rawImportPaths, importPath)

	fileHighlights := make(map[string][]highlight)
	fileNumHave := make(map[string]int)
	fileNumNeed := make(map[string]int)
	pkgNumHave := 0
	pkgNumNeed := 0

	// Call the same function used by the evals page to summarize documentation.
	frontend.CollectSymbols(astFiles, func(id *ast.Ident, has bool) {
	pos := fset.Position(id.Pos())
	end := fset.Position(id.End())

	fileHighlights[pos.Filename] = append(fileHighlights[pos.Filename], highlight{
	start: pos.Offset,
	end: end.Offset,
	has: has,
	})
	if has {
	fileNumHave[pos.Filename]++
	pkgNumHave++
	} else {
	fileNumNeed[pos.Filename]++
	pkgNumNeed++
	}
	})

	var fileItems []fileItem
	for _, fname := range fileNames {
	src := fileSrcs[fname]
	key := importPath + "/" + fname
	fileHTML[key] = formatHighlightedFile(src, fileHighlights[fname])

	g := fileNumHave[fname]
	r := fileNumNeed[fname]
	fileItems = append(fileItems, fileItem{
	Filename: fname,
	NumHave: g,
	NumNeed: r,
	NeedPct: percent(g, r),
	})
	}
	slices.SortFunc(fileItems, func(a, b fileItem) int {
	if c := cmp.Compare(b.NumNeed, a.NumNeed); c != 0 {
	return c
	}
	return cmp.Compare(a.Filename, b.Filename)
	})
	dirFiles[importPath] = fileItems
	dirHaveCounts[importPath] = pkgNumHave
	dirNeedCounts[importPath] = pkgNumNeed
	}

	var importPathItems []importPathItem
	for _, ip := range rawImportPaths {
	g := dirHaveCounts[ip]
	r := dirNeedCounts[ip]
	importPathItems = append(importPathItems, importPathItem{
	ImportPath: ip,
	NumHave: g,
	NumNeed: r,
	NeedPct: percent(g, r),
	})
	}

	slices.SortFunc(importPathItems, func(a, b importPathItem) int {
	if c := cmp.Compare(b.NumNeed, a.NumNeed); c != 0 {
	return c
	}
	return cmp.Compare(a.ImportPath, b.ImportPath)
	})

	return &server{
	modulePath: modulePath,
	resolvedVersion: resolvedVersion,
	importPaths: importPathItems,
	dirFiles: dirFiles,
	fileHTML: fileHTML,
	}, nil
	}

	// percent returns the percentage of m/ (n + m), rounded to the nearest integer.
	// It returns 0 if n + m is 0.
	func percent(n, m int) int {
	total := n + m
	if total == 0 {
	return 0
	}
	return int(math.Round(float64(m) * 100 / float64(total)))
	}

	func formatHighlightedFile(src []byte, highlights []highlight) template.HTML {
	slices.SortFunc(highlights, func(a, b highlight) int {
	return cmp.Compare(a.start, b.start)
	})

	var buf strings.Builder
	last := 0
	for _, h := range highlights {
	if h.start < last \|\| h.start > len(src) \|\| h.end > len(src) {
	continue
	}
	buf.WriteString(template.HTMLEscapeString(string(src[last:h.start])))
	if h.has {
	buf.WriteString(`<span class="has-doc">`)
	} else {
	buf.WriteString(`<span class="need-doc">`)
	}
	buf.WriteString(template.HTMLEscapeString(string(src[h.start:h.end])))
	buf.WriteString(`</span>`)
	last = h.end
	}
	if last < len(src) {
	buf.WriteString(template.HTMLEscapeString(string(src[last:])))
	}

	return template.HTML(buf.String())
	}

	func (s server) ServeHTTP(w http.ResponseWriter, r http.Request) {
	if r.URL.Path == "/" {
	s.handleRoot(w)
	return
	}
	if r.URL.Path == "/styles.css" {
	w.Header().Set("Content-Type", "text/css; charset=utf-8")
	fmt.Fprint(w, stylesCSS)
	return
	}

	p := strings.TrimPrefix(r.URL.Path, "/")
	if files, ok := s.dirFiles[p]; ok {
	s.handleDir(w, p, files)
	return
	}

	if contentHTML, ok := s.fileHTML[p]; ok {
	s.handleFile(w, p, contentHTML)
	return
	}

	http.NotFound(w, r)
	}

	const stylesCSS = `
	body { font-family: sans-serif; margin: 20px; }
	.has-doc { color: #1a7f37; font-weight: bold; margin-left: 4px; }
	.need-doc { color: #cf222e; font-weight: bold; margin-left: 4px; }
	.need-pct { color: #000; font-weight: bold; margin-left: 4px; }
	pre {
	font-family: monospace; background-color: #f6f8fa;
	padding: 16px; border-radius: 6px; overflow: auto;
	}
	.legend { font-family: sans-serif; margin-bottom: 1em; }
	pre .has-doc, .legend .has-doc {
	background-color: #dafbe1; padding: 0 2px; border-radius: 2px; margin-left: 0;
	}
	pre .need-doc, .legend .need-doc {
	background-color: #ffebe9; padding: 0 2px; border-radius: 2px; margin-left: 0;
	}
	`

	var rootTmpl = template.Must(template.New("root").Parse(`<!DOCTYPE html>
	<html>
	<head>
	<meta charset="utf-8">
	<title>Module {{.ModulePath}}@{{.Version}}</title>
	<link rel="stylesheet" href="/styles.css">
	</head>
	<body>
	<h1>Module {{.ModulePath}}@{{.Version}}
	<span class="has-doc">{{.NumHave}}</span>
	<span class="need-doc">{{.NumNeed}}</span>
	<span class="need-pct">{{.NeedPct}}%</span>
	</h1>
	<h2>Packages</h2>
	<ul>
	{{range .ImportPaths}}
	<li>
	<a href="/{{.ImportPath}}">{{.ImportPath}}</a>
	<span class="has-doc">{{.NumHave}}</span>
	<span class="need-doc">{{.NumNeed}}</span>
	<span class="need-pct">{{.NeedPct}}%</span>
	</li>
	{{end}}
	</ul>
	</body>
	</html>`))

	func (s *server) handleRoot(w http.ResponseWriter) {
	w.Header().Set("Content-Type", "text/html; charset=utf-8")
	var have, need int
	for _, item := range s.importPaths {
	have += item.NumHave
	need += item.NumNeed
	}
	data := struct {
	ModulePath string
	Version string
	NumHave, NumNeed int
	NeedPct int
	ImportPaths []importPathItem
	}{
	ModulePath: s.modulePath,
	Version: s.resolvedVersion,
	NumHave: have,
	NumNeed: need,
	NeedPct: percent(have, need),
	ImportPaths: s.importPaths,
	}
	rootTmpl.Execute(w, data)
	}

	var dirTmpl = template.Must(template.New("dir").Parse(`<!DOCTYPE html>
	<html>
	<head>
	<meta charset="utf-8">
	<title>Files in {{.ImportPath}}</title>
	<link rel="stylesheet" href="/styles.css">
	</head>
	<body>
	<p><a href="/">
	Back to Packages</a></p>
	<h1>Files in {{.ImportPath}}</h1>
	<ul>
	{{range .Files}}
	<li>
	<a href="/{{$.ImportPath}}/{{.Filename}}">{{.Filename}}</a>
	<span class="has-doc">{{.NumHave}}</span>
	<span class="need-doc">{{.NumNeed}}</span>
	<span class="need-pct">{{.NeedPct}}%</span>
	</li>
	{{end}}
	</ul>
	</body>
	</html>`))

	func (s *server) handleDir(w http.ResponseWriter, importPath string, files []fileItem) {
	w.Header().Set("Content-Type", "text/html; charset=utf-8")
	data := struct {
	ImportPath string
	Files []fileItem
	}{
	ImportPath: importPath,
	Files: files,
	}
	dirTmpl.Execute(w, data)
	}

	var fileTmpl = template.Must(template.New("file").Parse(`<!DOCTYPE html>
	<html>
	<head>
	<meta charset="utf-8">
	<title>{{.Filename}} - {{.ImportPath}}</title>
	<link rel="stylesheet" href="/styles.css">
	</head>
	<body>
	<p><a href="/{{.ImportPath}}">← Back to {{.ImportPath}}</a></p>
	<div class="legend">
	Symbol status:
	<span class="has-doc">Documented (Green)</span> \|
	<span class="need-doc">Undocumented (Red)</span>
	</div>
	<h1>{{.Filename}}</h1>
	<pre><code>{{.Contents}}</code></pre>
	</body>
	</html>`))

	func (s *server) handleFile(w http.ResponseWriter, key string, contentHTML template.HTML) {
	var importPath, filename string
	for ip := range s.dirFiles {
	if after, ok := strings.CutPrefix(key, ip+"/"); ok {
	if len(ip) > len(importPath) {
	importPath = ip
	filename = after
	}
	}
	}

	w.Header().Set("Content-Type", "text/html; charset=utf-8")
	fileData := struct {
	ImportPath string
	Filename string
	Contents template.HTML
	}{
	ImportPath: importPath,
	Filename: filename,
	Contents: contentHTML,
	}
	fileTmpl.Execute(w, fileData)
	}