Help us shape the future of Go! Take the 2026 Go Developer Survey

walker

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package walker handles directory traversal and file processing

Package walker handles directory traversal and file processing

Package walker handles directory traversal and file processing

Package walker handles directory traversal and file processing

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsBinaryFile

func IsBinaryFile(path string) bool

IsBinaryFile checks whether path points to a binary file. 1. Fast-path: Known source/text extensions return false (0 disk I/O). 2. Fast-path: Known binary extensions return true (0 disk I/O). 3. Fallback: Magic-number sniffing via gabriel-vasile/mimetype.

func WalkMeta

func WalkMeta(rootDir string, matcher *ignore.IgnoreMatcher, opts ...Option) ([]FileMeta, []SkippedItem, error)

WalkMeta enumerates a directory tree and returns file metadata only: no full file read. It applies the same ignore, extension, heavy-dir, path, size, and binary filters as Walk, making it the cheap structure pass for progressive UIs. Binary detection may sniff a small bounded prefix of unknown-extension files; nothing is read in full.

Types

type FileMeta

type FileMeta struct {
	Path       string
	Size       int64
	IsDir      bool
	ModTime    time.Time
	Hidden     bool
	GitIgnored bool
}

FileMeta describes a file without its content, backing the picker's structure-first skeleton so the TUI can open before any reads happen.

type Option

type Option func(*WalkOptions)

Option is a functional option for configuring WalkOptions

func WithConcurrency

func WithConcurrency(enabled bool) Option

WithConcurrency enables or disables concurrent file processing

func WithContext

func WithContext(ctx context.Context) Option

WithContext sets the context for cancellation

func WithExtensionMap

func WithExtensionMap(extMap map[string]struct{}) Option

WithExtensionMap sets the file extensions to include from a map (without the dot)

func WithExtensions

func WithExtensions(extensions []string) Option

WithExtensions sets the file extensions to include (without the dot)

func WithIncludeBinary

func WithIncludeBinary(include bool) Option

WithIncludeBinary controls whether binary files are included in the output. By default binary files are skipped.

func WithLogger

func WithLogger(logger utils.Logger) Option

WithLogger sets a custom logger for the walker

func WithMaxFileSize

func WithMaxFileSize(maxBytes int64) Option

WithMaxFileSize sets the maximum file size to read in bytes

func WithMaxWorkers

func WithMaxWorkers(workers int) Option

WithMaxWorkers sets the maximum number of concurrent workers

func WithPathFilter

func WithPathFilter(fn func(relativePath string) bool) Option

WithPathFilter sets a predicate deciding whether a relative path is processed. It runs after all other skip rules (ignore, extension) but before any file is read, so excluded paths never hit the disk.

func WithPreReadFilter

func WithPreReadFilter(fn func(relativePath string) bool) Option

WithPreReadFilter excludes paths before stat/binary detection and content reads. It is intended for cheap name-only rules such as lockfiles and generated bundles.

func WithProgress

func WithProgress(fn ProgressCallback) Option

WithProgress adds a progress callback function

func WithStats

func WithStats(fn StatsCallback) Option

WithStats receives one aggregate snapshot after a walk completes.

type ProgressCallback

type ProgressCallback func(stats ProgressStats)

ProgressCallback is a function that receives progress updates

type ProgressStats

type ProgressStats struct {
	TotalFiles      int64  // Total files seen
	ProcessedFiles  int64  // Files that passed all filters and were processed
	SkippedFiles    int64  // Files that were skipped for any reason
	TotalDirs       int64  // Total directories seen
	SkippedDirs     int64  // Directories that were skipped
	CurrentFilePath string // Path of the current file being processed (relative)
}

ProgressStats holds statistics about the walk progress

type SkippedItem

type SkippedItem struct {
	Path   string        `json:"path"`
	Reason SkippedReason `json:"reason"`
	IsDir  bool          `json:"is_dir"`
}

SkippedItem holds information about a skipped path.

func Walk

func Walk(rootDir string, matcher *ignore.IgnoreMatcher, walkFn WalkFunc, opts ...Option) ([]SkippedItem, error)

Walk traverses the directory tree starting from rootDir. It returns a list of skipped items and any critical error that occurred.

type SkippedReason

type SkippedReason string

SkippedReason clarifies why a file/directory was not processed.

const (
	ReasonIgnoredRule       SkippedReason = "Ignored (Gitignore/Custom Rule)"
	ReasonFilteredExtension SkippedReason = "Filtered (Extension Mismatch)"
	ReasonFilteredPath      SkippedReason = "Filtered (Path Rule)"
	ReasonSkippedSizeLimit  SkippedReason = "Skipped (Size Limit Exceeded)"
	ReasonSkippedNotRegular SkippedReason = "Skipped (Not a Regular File)"
	ReasonSkippedPermError  SkippedReason = "Skipped (Permission Error)"
	ReasonSkippedWalkError  SkippedReason = "Skipped (Walk Error)"
	ReasonSkippedReadError  SkippedReason = "Skipped (Read Error)"
	ReasonSkippedBinary     SkippedReason = "Skipped (Binary File)"
	ReasonSkippedInfoError  SkippedReason = "Skipped (File Info Error)"
	ReasonSkippedPathError  SkippedReason = "Skipped (Path Calculation Error)"
	ReasonSkippedSmart      SkippedReason = "Skipped (Smart Filter)"
)

type SkippedTracker

type SkippedTracker struct {
	// contains filtered or unexported fields
}

SkippedTracker is a struct to track skipped items

func NewSkippedTracker

func NewSkippedTracker(capacity int) *SkippedTracker

NewSkippedTracker creates a new SkippedTracker

func (*SkippedTracker) Dropped added in v1.2.0

func (st *SkippedTracker) Dropped() int

Dropped reports how many skip events were not recorded because the retention cap was reached, so callers can know the skip list was truncated.

func (*SkippedTracker) Items

func (st *SkippedTracker) Items() []SkippedItem

Items returns a copy of the tracked skipped items.

func (*SkippedTracker) Track

func (st *SkippedTracker) Track(path string, reason SkippedReason, isDir bool)

Track adds a skipped item to the tracker, up to the retention cap. Beyond that the item is dropped and counted so callers can detect overflow.

type StatsCallback

type StatsCallback func(WalkStats)

StatsCallback receives aggregate walk metrics after traversal and workers have finished.

type WalkFunc

type WalkFunc func(relativePath string, content []byte, err error) error

WalkFunc is the callback function type used by Walk

type WalkOptions

type WalkOptions struct {
	Logger        utils.Logger
	Concurrent    bool
	MaxWorkers    int
	MaxFileSize   int64
	ExtensionMap  map[string]struct{}
	IncludeBinary bool
	Context       context.Context
	ProgressFn    ProgressCallback // Add progress callback function
	PreReadFilter func(relativePath string) bool
	StatsFn       StatsCallback
	// PathFilter, when set, is consulted before a file is read. Returning
	// false excludes the file from processing, so filtered paths never cost
	// I/O or token work.
	PathFilter func(relativePath string) bool
}

WalkOptions configures the behavior of the Walk function

type WalkStats

type WalkStats struct {
	TotalFiles     int64
	ProcessedFiles int64
	SkippedFiles   int64
	TotalDirs      int64
	SkippedDirs    int64
	BytesRead      int64
	BinarySkipped  int64
	SizeSkipped    int64
	SmartSkipped   int64
	Duration       time.Duration
}

WalkStats summarizes the work performed by a directory walk.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL