feat: add configurable exclude globs

  - add repeatable --exclude and --no-default-excludes flags
  - implement doublestar aware excluder and normalize paths
  - report skipped paths in verbose mode during discovery
  - expand tests/docs and bump zerolog to 1.35.0

Author: jcouture

README.md

@@ -82,8 +82,10 @@ You should see `ghostscan dev (commit none)` from a plain source build, or a rea
 ghostscan [flags] [path]
 
 Flags:
+      --exclude strings     exclude files or directories matching this glob; repeatable
       --max-file-size int   skip files larger than this many bytes
   -n, --no-color            disable color
+      --no-default-excludes disable built-in exclude globs
       --silent              suppress the startup banner
       --verbose             print detailed structured finding blocks
   -v, --version             print version
@@ -107,6 +109,12 @@ ghostscan --silent --no-color .
 # Show detailed findings
 ghostscan --silent --no-color --verbose ./testdata/mixed/correlated_decoder_near_payload.js
 
+# Add repeatable exclude globs
+ghostscan . --exclude "**/*.min.js" --exclude "vendor/**"
+
+# Disable built-in excludes and use only an explicit glob
+ghostscan . --no-default-excludes --exclude "**/*.gen.js"
+
 # Enforce a smaller max file size
 ghostscan --max-file-size 1048576 .
 ```
@@ -122,6 +130,13 @@ ghostscan --max-file-size 1048576 .
 - rule ID
 - fingerprint
 
+Verbose mode also reports exclusions during traversal:
+
+```text
+SKIP dist/app.min.js (matched exclude: "**/*.min.js")
+SKIP vendor (matched exclude: "vendor/**")
+```
+
 Exit codes:
 
 | Exit code | Description                                                  |
@@ -138,7 +153,10 @@ The current scanner behavior is intentionally narrow and real:
 - Does not follow symlinks.
 - Treats files containing a NUL byte as binary and skips them.
 - Uses a default max file size of `5 MiB`.
-- Skips `.git`, `node_modules`, `vendor`, `dist`, `build`, `target`, `out`, and `coverage`.
+- Matches excludes against the full normalized relative path with `/` separators.
+- Supports repeatable `--exclude` globs with `**` matching zero or more path segments and `filepath.Match` semantics for other segments.
+- Applies built-in excludes by default: `.git/**`, `node_modules/**`, `vendor/**`, `dist/**`, `build/**`, `target/**`, `out/**`, and `coverage/**`.
+- `--no-default-excludes` disables the built-in exclude set completely.
 - Never executes scanned code or fetches network resources.
 
 ## FAQ

cmd/root.go

@@ -61,11 +61,15 @@ func execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 	var verbose bool
 	var silent bool
 	var maxFileSize int64
+	var excludes []string
+	var noDefaultExcludes bool
 	flags.BoolVarP(&noColor, "no-color", "n", false, "disable color")
 	flags.BoolVarP(&version, "version", "v", false, "print version")
 	flags.BoolVar(&verbose, "verbose", false, "print detailed structured finding blocks")
 	flags.BoolVar(&silent, "silent", false, "suppress the startup banner")
 	flags.Int64Var(&maxFileSize, "max-file-size", 0, "skip files larger than this many bytes")
+	flags.StringArrayVar(&excludes, "exclude", nil, "exclude files or directories matching this glob; repeatable")
+	flags.BoolVar(&noDefaultExcludes, "no-default-excludes", false, "disable built-in exclude globs")
 
 	if err := flags.Parse(args); err != nil {
 		if errors.Is(err, pflag.ErrHelp) {
@@ -95,13 +99,15 @@ func execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 	}
 
 	result, err := app.Run(ctx, app.Options{
-		Path:        path,
-		Stdout:      stdout,
-		Color:       !noColor,
-		Verbose:     verbose,
-		Silent:      silent,
-		MaxFileSize: maxFileSize,
-		Version:     Version,
+		Path:               path,
+		Stdout:             stdout,
+		Color:              !noColor,
+		Verbose:            verbose,
+		Silent:             silent,
+		MaxFileSize:        maxFileSize,
+		Excludes:           excludes,
+		UseDefaultExcludes: !noDefaultExcludes,
+		Version:            Version,
 	})
 	if err != nil {
 		_, _ = fmt.Fprintln(stderr, err)

cmd/root_test.go

@@ -96,6 +96,22 @@ func TestExecute(t *testing.T) {
 			wantCode: exitcode.ExecutionError,
 			wantErr:  "--max-file-size must be zero or greater",
 		},
+		{
+			name:     "repeated excludes",
+			args:     []string{"--no-color", "--exclude", "**/*.min.js", "--exclude", "vendor/**", filepath.Join("..", "testdata", "mixed")},
+			wantCode: exitcode.FindingsDetected,
+		},
+		{
+			name:     "invalid exclude glob",
+			args:     []string{"--exclude", "bad["},
+			wantCode: exitcode.ExecutionError,
+			wantErr:  "configure excludes",
+		},
+		{
+			name:     "no default excludes includes vendor fixture",
+			args:     []string{"--no-color", "--no-default-excludes", filepath.Join("..", "testdata", "clean")},
+			wantCode: exitcode.Success,
+		},
 	}
 
 	for _, tt := range tests {
@@ -163,6 +179,8 @@ func TestExecuteHelp(t *testing.T) {
 		"Usage:\n  ghostscan [flags] [path]",
 		"Optional file or directory to scan. Flags must come before the path.",
 		"--verbose",
+		"--exclude",
+		"--no-default-excludes",
 		"--silent",
 		"--max-file-size",
 	} {

go.mod

@@ -4,7 +4,7 @@ go 1.26.1
 
 require github.com/fatih/color v1.19.0
 
-require github.com/rs/zerolog v1.34.0
+require github.com/rs/zerolog v1.35.0
 
 require github.com/spf13/pflag v1.0.10
 

go.sum

@@ -1,22 +1,13 @@
-github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
 github.com/fatih/color v1.19.0 h1:Zp3PiM21/9Ld6FzSKyL5c/BULoe/ONr9KlbYVOfG8+w=
 github.com/fatih/color v1.19.0/go.mod h1:zNk67I0ZUT1bEGsSGyCZYZNrHuTkJJB+r6Q9VuMi0LE=
-github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
-github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
 github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
-github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
-github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
-github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
-github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
-github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/rs/zerolog v1.35.0 h1:VD0ykx7HMiMJytqINBsKcbLS+BJ4WYjz+05us+LRTdI=
+github.com/rs/zerolog v1.35.0/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
-golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
 golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

internal/app/run.go

@@ -36,13 +36,15 @@ import (
 )
 
 type Options struct {
-	Path        string
-	Stdout      io.Writer
-	Color       bool
-	Verbose     bool
-	Silent      bool
-	MaxFileSize int64
-	Version     string
+	Path               string
+	Stdout             io.Writer
+	Color              bool
+	Verbose            bool
+	Silent             bool
+	MaxFileSize        int64
+	Excludes           []string
+	UseDefaultExcludes bool
+	Version            string
 }
 
 type Result struct {
@@ -75,7 +77,28 @@ func Run(ctx context.Context, opts Options) (Result, error) {
 		maxFileSize = filesystem.DefaultMaxFileSize
 	}
 
-	discovery, err := filesystem.Discover(path, maxFileSize)
+	useDefaultExcludes := true
+	if opts.Excludes != nil || !opts.UseDefaultExcludes {
+		useDefaultExcludes = opts.UseDefaultExcludes
+	}
+
+	excluder, err := filesystem.NewExcluder(opts.Excludes, useDefaultExcludes)
+	if err != nil {
+		return Result{}, fmt.Errorf("configure excludes: %w", err)
+	}
+	headerWritten := false
+	if opts.Verbose {
+		if err := report.WriteHeader(opts.Stdout, opts.Version, opts.Silent); err != nil {
+			return Result{}, fmt.Errorf("write report header: %w", err)
+		}
+		headerWritten = true
+	}
+
+	discovery, err := filesystem.Discover(path, filesystem.DiscoverOptions{
+		MaxFileSize: maxFileSize,
+		Excluder:    excluder,
+		OnExclude:   buildExcludeReporter(opts.Stdout, opts.Verbose),
+	})
 	if err != nil {
 		return Result{}, fmt.Errorf("discover files from %q: %w", path, err)
 	}
@@ -96,10 +119,11 @@ func Run(ctx context.Context, opts Options) (Result, error) {
 	finding.Sort(findings)
 
 	if err := report.WriteHuman(opts.Stdout, findings, report.Options{
-		Version: opts.Version,
-		Color:   opts.Color,
-		Verbose: opts.Verbose,
-		Silent:  opts.Silent,
+		Version:       opts.Version,
+		Color:         opts.Color,
+		Verbose:       opts.Verbose,
+		Silent:        opts.Silent,
+		HeaderWritten: headerWritten,
 		Runtime: report.RuntimeStats{
 			WalkDuration:          walkDuration,
 			ScanDuration:          scanDuration,
@@ -121,6 +145,16 @@ func Run(ctx context.Context, opts Options) (Result, error) {
 	}, nil
 }
 
+func buildExcludeReporter(w io.Writer, verbose bool) func(path, pattern string) {
+	if !verbose {
+		return nil
+	}
+
+	return func(path, pattern string) {
+		_, _ = fmt.Fprintf(w, "SKIP %s (matched exclude: %q)\n", path, pattern)
+	}
+}
+
 func scanCandidates(ctx context.Context, engine *scan.Engine, paths []string) ([]fileScanResult, []error) {
 	if len(paths) == 0 {
 		return nil, nil

internal/app/run_test.go

@@ -196,3 +196,33 @@ func TestRunSilentSuppressesBanner(t *testing.T) {
 		t.Fatalf("stdout = %q, want clean report", output)
 	}
 }
+
+func TestRunVerboseReportsExcludedFilesDuringTraversal(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "keep.js"), []byte("const x = 1;\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "app.min.js"), []byte("const y = 1;\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	var stdout bytes.Buffer
+	_, err := Run(context.Background(), Options{
+		Path:               root,
+		Stdout:             &stdout,
+		Verbose:            true,
+		Silent:             true,
+		UseDefaultExcludes: true,
+		Excludes:           []string{"**/*.min.js"},
+	})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+
+	output := stdout.String()
+	if !strings.Contains(output, "SKIP app.min.js (matched exclude: \"**/*.min.js\")") {
+		t.Fatalf("stdout = %q, want skip line", output)
+	}
+}

internal/filesystem/discover_bench_test.go

@@ -23,10 +23,18 @@ func BenchmarkDiscover(b *testing.B) {
 
 	for _, tc := range cases {
 		b.Run(tc.name, func(b *testing.B) {
+			excluder, err := NewExcluder(nil, true)
+			if err != nil {
+				b.Fatal(err)
+			}
+
 			b.ReportAllocs()
 			b.ResetTimer()
 			for i := 0; i < b.N; i++ {
-				benchDiscovery, benchErr = Discover(tc.root, DefaultMaxFileSize)
+				benchDiscovery, benchErr = Discover(tc.root, DiscoverOptions{
+					MaxFileSize: DefaultMaxFileSize,
+					Excluder:    excluder,
+				})
 				if benchErr != nil {
 					b.Fatal(benchErr)
 				}