From d7a62f1da1fc405d6968f23e0034aaae0f693403 Mon Sep 17 00:00:00 2001 From: kennytm Date: Tue, 3 Nov 2026 16:22:12 +0800 Subject: [PATCH 1/4] errdoc-gen: validate input arguments --- errdoc-gen/README.md | 16 ++- errdoc-gen/main.go | 70 +++++++++--- errdoc-gen/main_test.go | 247 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 312 insertions(+), 21 deletions(-) create mode 100644 errdoc-gen/main_test.go diff --git a/errdoc-gen/README.md b/errdoc-gen/README.md index 8f98afcc..c65c183a 100644 --- a/errdoc-gen/README.md +++ b/errdoc-gen/README.md @@ -1,6 +1,10 @@ -## Usage - -```shell script -# eg: ./errdoc-gen --source devel/pingap/tidb --module github.com/pingcap/tidb --output devel/pingap/tidb/errors.toml -./errdoc-gen --source /path/to/source/code --module ${module-name} --output /path/to/errors.toml -``` \ No newline at end of file +## Usage + +```shell script +# eg: ./errdoc-gen --source devel/pingap/tidb --module github.com/pingcap/tidb --output devel/pingap/tidb/errors.toml +./errdoc-gen --source /path/to/source/code --module ${module-name} --output /path/to/errors.toml +``` + +Only run errdoc-gen on trusted source trees. It compiles and runs a generated Go program that imports the scanned packages, executing their variable initializers and `init()` functions, including those of their dependencies. Input validation does not sandbox this execution. + +`--module` and package import paths must match `[A-Za-z0-9_]+([.-][A-Za-z0-9_]+)*(/[A-Za-z0-9_]+([.-][A-Za-z0-9_]+)*)*`. This accepts domains, hyphenated names, and version numbers while rejecting empty components and traversal. `--ignore` accepts comma-separated paths using the same pattern, with an optional `./` prefix and trailing `/`, relative to `--source`; surrounding whitespace and blank entries are ignored. Parse failures, invalid paths, and scans with no error declarations or no normalized errors fail without overwriting the output. diff --git a/errdoc-gen/main.go b/errdoc-gen/main.go index a5e4df33..ef59c8f3 100644 --- a/errdoc-gen/main.go +++ b/errdoc-gen/main.go @@ -22,6 +22,7 @@ import ( "os" "os/exec" "path/filepath" + "regexp" "slices" "strings" "text/template" @@ -55,6 +56,13 @@ func fatal(format string, args ...any) { const autoDirectoryName = "_errdoc-generator" const entryFileName = "main.go" +const pathElementPattern = `[A-Za-z0-9_]+([.-][A-Za-z0-9_]+)*` + +var ( + importPathRegexp = regexp.MustCompile(`^` + pathElementPattern + `(/` + pathElementPattern + `)*$`) + ignoreDirectoryRegexp = regexp.MustCompile(`^(\./)?` + pathElementPattern + `(/` + pathElementPattern + `)*/?$`) +) + func main() { flag.Parse() if opt.source == "" { @@ -68,8 +76,8 @@ func main() { opt.source = source _, err = os.Stat(filepath.Join(opt.source, "go.mod")) - if os.IsNotExist(err) { - fatal("The source directory is not the root path of codebase(go.mod not found)") + if err != nil { + fatal("Cannot access go.mod in the source directory: %v", err) } if opt.output == "" { @@ -79,7 +87,7 @@ func main() { errNames, err := errdoc(opt.source, opt.module) if err != nil { - log("Extract the error documentation failed: %+v", err) + fatal("Extract the error documentation failed: %+v", err) } targetDir := filepath.Join(opt.source, autoDirectoryName) @@ -107,7 +115,7 @@ import ( "github.com/BurntSushi/toml" "github.com/pingcap/errors" {{- range $decl := .}} - {{$decl.PackageName}} "{{- $decl.ImportPath}}" + {{$decl.PackageName}} {{printf "%q" $decl.ImportPath}} {{- end}} ) @@ -163,6 +171,10 @@ func main() { dedup[codeText.String()] = s } } + if len(dedup) == 0 { + println("No normalized errors found; refusing to overwrite the output") + os.Exit(1) + } var sorted []spec for _, item := range dedup { @@ -238,6 +250,9 @@ type errDecl struct { } func errdoc(source, module string) ([]*errDecl, error) { + if err := validateImportPath(module); err != nil { + return nil, fmt.Errorf("invalid --module: %w", err) + } source, err := filepath.Abs(source) if err != nil { return nil, err @@ -245,9 +260,16 @@ func errdoc(source, module string) ([]*errDecl, error) { dedup := map[string]*errDecl{} - ignored := strings.Split(opt.ignore, ",") - for i := range ignored { - ignored[i] = filepath.Join(source, ignored[i]) + ignored := []string{filepath.Join(source, autoDirectoryName)} + for _, dir := range strings.Split(opt.ignore, ",") { + dir = strings.TrimSpace(dir) + if dir == "" { + continue + } + if !ignoreDirectoryRegexp.MatchString(dir) { + return nil, fmt.Errorf("invalid --ignore directory %q: must be a subdirectory of the source", dir) + } + ignored = append(ignored, filepath.Join(source, dir)) } err = filepath.Walk(source, func(path string, info os.FileInfo, err error) error { if err != nil { @@ -265,8 +287,7 @@ func errdoc(source, module string) ([]*errDecl, error) { fset := token.NewFileSet() file, err := parser.ParseFile(fset, path, nil, parser.ParseComments) if err != nil { - // Ignore invalid source file - return nil + return fmt.Errorf("parse %s: %w", path, err) } errNames := export(file) if len(errNames) < 1 { @@ -277,26 +298,45 @@ func errdoc(source, module string) ([]*errDecl, error) { if err != nil { return err } - packageName := strings.ReplaceAll(subPath, "/", "_") - if decl, found := dedup[packageName]; found { + importPath := module + if subPath != "." { + importPath += "/" + filepath.ToSlash(subPath) + } + if err := validateImportPath(importPath); err != nil { + return fmt.Errorf("invalid package directory %q: %w", dirPath, err) + } + if decl, found := dedup[importPath]; found { decl.ErrNames = append(decl.ErrNames, errNames...) } else { decl := &errDecl{ - ImportPath: filepath.Join(module, subPath), - PackageName: packageName, + ImportPath: importPath, + PackageName: fmt.Sprintf("errpkg%d", len(dedup)), ErrNames: errNames, } - dedup[packageName] = decl + dedup[importPath] = decl } return nil }) + if err != nil { + return nil, err + } + if len(dedup) == 0 { + return nil, fmt.Errorf("no error declarations found; refusing to overwrite the output") + } var errDecls []*errDecl for _, decl := range dedup { errDecls = append(errDecls, decl) } - return errDecls, err + return errDecls, nil +} + +func validateImportPath(importPath string) error { + if !importPathRegexp.MatchString(importPath) { + return fmt.Errorf("invalid import path %q", importPath) + } + return nil } func export(f *ast.File) []string { diff --git a/errdoc-gen/main_test.go b/errdoc-gen/main_test.go new file mode 100644 index 00000000..a0673838 --- /dev/null +++ b/errdoc-gen/main_test.go @@ -0,0 +1,247 @@ +// Copyright 2026 PingCAP, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package main + +import ( + "flag" + "go/token" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/stretchr/testify/require" +) + +func writeSource(t *testing.T, source, name, content string) { + t.Helper() + filename := filepath.Join(source, name) + require.NoError(t, os.MkdirAll(filepath.Dir(filename), 0755)) + require.NoError(t, os.WriteFile(filename, []byte(content), 0644)) +} + +func TestErrdocIgnore(t *testing.T) { + source := t.TempDir() + writeSource(t, source, "errors.go", "package example; var ErrRoot = new(error)") + writeSource(t, source, "skip/errors.go", "package example; var ErrSkipped = new(error)") + writeSource(t, source, "skip/nested/errors.go", "package example; var ErrNested = new(error)") + writeSource(t, source, autoDirectoryName+"/main.go", "invalid retained generator") + previousIgnore := opt.ignore + t.Cleanup(func() { opt.ignore = previousIgnore }) + for _, test := range []struct { + ignore string + count int + }{ + {"", 3}, + {", ,", 3}, + {"skip", 1}, + {"./skip", 1}, + {"./skip/", 1}, + {"skip/,skip/nested", 1}, + {" , skip, , ", 1}, + } { + t.Run(test.ignore, func(t *testing.T) { + opt.ignore = test.ignore + decls, err := errdoc(source, "example.com/project") + require.NoError(t, err) + require.Len(t, decls, test.count) + }) + } +} + +func TestErrdocScriptArguments(t *testing.T) { + previousIgnore := opt.ignore + t.Cleanup(func() { opt.ignore = previousIgnore }) + for _, test := range []struct { + module string + ignore string + }{ + {"github.com/pingcap/tidb", "pkg/parser,pkg/tidb-binlog"}, + {"github.com/pingcap/tiflow", "proto,dm,deployments,engine,cdc/scheduler/internal"}, + {"github.com/tikv/pd", "./client/errs,./tools"}, + } { + t.Run(test.module, func(t *testing.T) { + source := t.TempDir() + writeSource(t, source, "errors.go", "package example; var ErrRoot = new(error)") + for _, dir := range strings.Split(test.ignore, ",") { + writeSource(t, source, filepath.Join(dir, "invalid.go"), "invalid Go") + } + opt.ignore = test.ignore + decls, err := errdoc(source, test.module) + require.NoError(t, err) + require.Len(t, decls, 1) + require.Equal(t, test.module, decls[0].ImportPath) + }) + } +} + +func TestErrdocInvalidIgnore(t *testing.T) { + source := t.TempDir() + writeSource(t, source, "errors.go", "package example; var ErrRoot = new(error)") + previousIgnore := opt.ignore + t.Cleanup(func() { opt.ignore = previousIgnore }) + for _, ignore := range []string{ + ".", "./", "..", "../outside", "skip/../outside", "skip/./nested", "skip//nested", + "/absolute", "C:\\absolute", "skip\\nested", "with space", "with\nnewline", "with\"quote", + "with`backtick", "with;semicolon", "skip/..hidden", + } { + t.Run(ignore, func(t *testing.T) { + opt.ignore = "valid," + ignore + decls, err := errdoc(source, "example.com/project") + require.ErrorContains(t, err, "invalid --ignore directory") + require.Nil(t, decls) + }) + } +} + +func TestErrdocPackageAliases(t *testing.T) { + source := t.TempDir() + directories := []string{".", "a/b", "a_b", "a-b", "v1.2", "123", "fmt", "for"} + for _, dir := range directories { + writeSource(t, source, filepath.Join(dir, "errors.go"), "package example; var ErrExample = new(error)") + } + writeSource(t, source, "more.go", "package example; var ErrAnother = new(error)") + decls, err := errdoc(source, "example.com/project") + require.NoError(t, err) + require.Len(t, decls, len(directories)) + aliases := make(map[string]bool) + imports := make(map[string][]string) + for _, decl := range decls { + require.True(t, token.IsIdentifier(decl.PackageName), decl.PackageName) + require.False(t, aliases[decl.PackageName], "duplicate alias %s", decl.PackageName) + aliases[decl.PackageName] = true + imports[decl.ImportPath] = decl.ErrNames + } + require.ElementsMatch(t, []string{"ErrExample", "ErrAnother"}, imports["example.com/project"]) + for _, dir := range directories[1:] { + require.Equal(t, []string{"ErrExample"}, imports["example.com/project/"+dir]) + } +} + +func TestErrdocInvalidModule(t *testing.T) { + source := t.TempDir() + writeSource(t, source, "errors.go", "package example; var ErrExample = new(error)") + for _, module := range []string{ + "", "example.com/project\"\n)\nfunc init() {}\n//", "example.com/with space", + "example.com/with`backtick", "example.com/with\\backslash", "/absolute", "../relative", + "example.com/../escape", "example.com//empty", "example.com/trailing/", "-example.com/project", + "example..com/project", "example.com/a..b", "example.com/.hidden", + "example.com/a~b", "example.com/a+b", + } { + t.Run(module, func(t *testing.T) { + decls, err := errdoc(source, module) + require.ErrorContains(t, err, "invalid --module") + require.Nil(t, decls) + }) + } +} + +func TestErrdocInvalidDirectory(t *testing.T) { + for _, dir := range []string{"with space", "with\"quote", "with\nnewline", "with`backtick", "with;semicolon", "a..b", ".hidden", "a+b", "a~b"} { + t.Run(dir, func(t *testing.T) { + if runtime.GOOS == "windows" && strings.ContainsAny(dir, "\"\n") { + t.Skip("directory name cannot be created on Windows") + } + source := t.TempDir() + writeSource(t, source, filepath.Join(dir, "errors.go"), "package example; var ErrExample = new(error)") + decls, err := errdoc(source, "example.com/project") + require.ErrorContains(t, err, "invalid package directory") + require.Nil(t, decls) + }) + } +} + +func TestErrdocCLIProcess(t *testing.T) { + if os.Getenv("ERRDOC_GEN_TEST_PROCESS") != "1" { + return + } + os.Args = append(os.Args[:1], flag.Args()...) + main() + os.Exit(0) +} + +func TestErrdocCLIPreservesOutputOnFailure(t *testing.T) { + for _, test := range []struct { + name string + files map[string]string + args []string + message string + }{ + { + name: "empty scan", + message: "no error declarations found", + }, + { + name: "parse error after valid declaration", + files: map[string]string{"errors.go": "package example; var ErrExample = new(error)", "z.go": "invalid Go"}, + message: "parse ", + }, + { + name: "all packages ignored", + files: map[string]string{"skip/errors.go": "package example; var ErrExample = new(error)"}, + args: []string{"--ignore", "skip"}, + message: "no error declarations found", + }, + { + name: "module injection", + files: map[string]string{"errors.go": "package example; var ErrExample = new(error)"}, + args: []string{"--module", "example.com/project\"\n)\nfunc init() {}\n//"}, + message: "invalid --module", + }, + { + name: "directory injection", + files: map[string]string{"bad;dir/errors.go": "package example; var ErrExample = new(error)"}, + message: "invalid package directory", + }, + { + name: "ignore source root", + args: []string{"--ignore", "."}, + message: "invalid --ignore directory", + }, + { + name: "ignore outside source", + args: []string{"--ignore", "../outside"}, + message: "invalid --ignore directory", + }, + { + name: "ignore absolute path", + args: []string{"--ignore", filepath.Join(t.TempDir(), "outside")}, + message: "invalid --ignore directory", + }, + } { + t.Run(test.name, func(t *testing.T) { + source := t.TempDir() + writeSource(t, source, "go.mod", "module example.com/project\n") + const previous = "# Existing documentation\n[\"example:existing\"]\nerror = 'existing'\ndescription = 'keep me'\n" + writeSource(t, source, "errors.toml", previous) + for name, content := range test.files { + writeSource(t, source, name, content) + } + args := []string{"-test.run=^TestErrdocCLIProcess$", "--", "--source", source, "--module", "example.com/project"} + cmd := exec.Command(os.Args[0], append(args, test.args...)...) + cmd.Env = append(os.Environ(), "ERRDOC_GEN_TEST_PROCESS=1") + output, err := cmd.CombinedOutput() + require.Error(t, err, "%s", output) + require.Contains(t, string(output), test.message) + require.NotContains(t, string(output), "Generate successfully") + content, err := os.ReadFile(filepath.Join(source, "errors.toml")) + require.NoError(t, err) + require.Equal(t, previous, string(content)) + require.NoDirExists(t, filepath.Join(source, autoDirectoryName)) + }) + } +} From 8620497a0fa346cba0352339e7daba0751f4b2f3 Mon Sep 17 00:00:00 2001 From: kennytm Date: Tue, 3 Nov 2026 16:34:02 +0800 Subject: [PATCH 2/4] errdoc-gen: address comments --- errdoc-gen/main.go | 4 ++++ errdoc-gen/main_test.go | 41 +++++++++++++++++++++++++++++++++++++++++ go.mod | 1 + go.sum | 2 ++ 4 files changed, 48 insertions(+) diff --git a/errdoc-gen/main.go b/errdoc-gen/main.go index ef59c8f3..932e5eeb 100644 --- a/errdoc-gen/main.go +++ b/errdoc-gen/main.go @@ -237,6 +237,10 @@ func main() { cmd.Dir = opt.source data, err := cmd.CombinedOutput() if err != nil { + if !opt.retainCode { + out.Close() + os.RemoveAll(targetDir) + } fatal("Generate %s failed: %v, output:\n%s", opt.output, err, string(data)) } diff --git a/errdoc-gen/main_test.go b/errdoc-gen/main_test.go index a0673838..5cdc72ad 100644 --- a/errdoc-gen/main_test.go +++ b/errdoc-gen/main_test.go @@ -21,9 +21,11 @@ import ( "os/exec" "path/filepath" "runtime" + "strconv" "strings" "testing" + "github.com/BurntSushi/toml" "github.com/stretchr/testify/require" ) @@ -174,6 +176,45 @@ func TestErrdocCLIProcess(t *testing.T) { os.Exit(0) } +func TestErrdocCLIRejectsNonNormalizedErrors(t *testing.T) { + repo, err := filepath.Abs("..") + require.NoError(t, err) + module, err := os.ReadFile(filepath.Join(repo, "go.mod")) + require.NoError(t, err) + sums, err := os.ReadFile(filepath.Join(repo, "go.sum")) + require.NoError(t, err) + fixtureModule := strings.Replace(string(module), "module github.com/pingcap/errors", "module example.com/project", 1) + + "\nrequire github.com/pingcap/errors v0.0.0\nreplace github.com/pingcap/errors => " + strconv.Quote(repo) + "\n" + for _, retain := range []bool{false, true} { + t.Run("retain-code="+strconv.FormatBool(retain), func(t *testing.T) { + source := t.TempDir() + writeSource(t, source, "go.mod", fixtureModule) + writeSource(t, source, "go.sum", string(sums)) + writeSource(t, source, "errors.go", "package example\nimport \"errors\"\nvar ErrExample = errors.New(\"ordinary error\")\n") + const previous = "[\"example:existing\"]\nerror = 'existing'\ndescription = 'keep me'\n" + writeSource(t, source, "errors.toml", previous) + cmd := exec.Command(os.Args[0], "-test.run=^TestErrdocCLIProcess$", "--", "--source", source, + "--module", "example.com/project", "--retain-code="+strconv.FormatBool(retain)) + cmd.Env = append(os.Environ(), "ERRDOC_GEN_TEST_PROCESS=1", "GOPROXY=off", "GOFLAGS=-mod=readonly") + output, err := cmd.CombinedOutput() + require.Error(t, err, "%s", output) + require.Contains(t, string(output), "No normalized errors found") + require.NotContains(t, string(output), "Generate successfully") + content, err := os.ReadFile(filepath.Join(source, "errors.toml")) + require.NoError(t, err) + require.Equal(t, previous, string(content)) + var definitions map[string]map[string]string + require.NoError(t, toml.Unmarshal(content, &definitions)) + require.Equal(t, "keep me", definitions["example:existing"]["description"]) + if retain { + require.FileExists(t, filepath.Join(source, autoDirectoryName, entryFileName)) + } else { + require.NoDirExists(t, filepath.Join(source, autoDirectoryName)) + } + }) + } +} + func TestErrdocCLIPreservesOutputOnFailure(t *testing.T) { for _, test := range []struct { name string diff --git a/go.mod b/go.mod index 8423b18f..e7db9714 100644 --- a/go.mod +++ b/go.mod @@ -3,6 +3,7 @@ module github.com/pingcap/errors go 1.25 require ( + github.com/BurntSushi/toml v1.6.0 github.com/stretchr/testify v1.11.1 go.uber.org/atomic v1.11.0 ) diff --git a/go.sum b/go.sum index 8d2f3332..0fcda426 100644 --- a/go.sum +++ b/go.sum @@ -1,3 +1,5 @@ +github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk= +github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From 47a666d770aa8a125ea25e01dc951781771f23c5 Mon Sep 17 00:00:00 2001 From: kennytm Date: Tue, 3 Nov 2026 16:40:22 +0800 Subject: [PATCH 3/4] Add pingcap/errors dependency for tests Add import for pingcap/errors for offline test dependencies. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- errdoc-gen/main_test.go | 1 + 1 file changed, 1 insertion(+) diff --git a/errdoc-gen/main_test.go b/errdoc-gen/main_test.go index 5cdc72ad..a756425a 100644 --- a/errdoc-gen/main_test.go +++ b/errdoc-gen/main_test.go @@ -26,6 +26,7 @@ import ( "testing" "github.com/BurntSushi/toml" + _ "github.com/pingcap/errors" // Load dependencies needed by the offline generated-program test. "github.com/stretchr/testify/require" ) From 720c5c6a4de5708dd4741d571ede427529dabecc Mon Sep 17 00:00:00 2001 From: kennytm Date: Thu, 12 Nov 2026 13:59:40 +0800 Subject: [PATCH 4/4] .github: increase coverage to 80% --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 41833837..f591edd1 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -21,7 +21,7 @@ jobs: - run: go test -cover -coverprofile=coverage.out ./... - name: Check coverage # TODO: increase minimum after adding more tests run: | - awk -v minimum=0 ' + awk -v minimum=80 ' NR > 1 { total += $2 if ($3 > 0) covered += $2