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

treestamp

package module
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 30 Imported by: 0

README

Treestamp

Go Reference

Native Go library for walking a tree. You can then select files, hash what you selected, explain why a path was kept or dropped, and verify the next tree. Same scanner from a CLI when you are not writing Go.

What Where Open this
Library this repository root pkg.go.dev/github.com/sergii-ziborov/treestamp
CLI cmd/treestamp cmd/treestamp/README.md
Driver cmd/treestamp-driver cmd/treestamp-driver/README.md — fixture protocol only, not the product

Published tags: library v0.1.4, CLI cmd/treestamp/v0.1.4. This checkout’s Version is 0.1.5 (untagged). go install still uses the published CLI module (@v0.1.4) until cmd/treestamp/v0.1.5. Those published tags stay immutable. This tree is not a retag.

Install

Requires Go 1.21 or newer. CGO_ENABLED=0.

Library
go get github.com/sergii-ziborov/treestamp@v0.1.4

Import github.com/sergii-ziborov/treestamp. Docs and examples: pkg.go.dev/github.com/sergii-ziborov/treestamp. The runtime module requires golang.org/x/sys only. It does not require fastwalk, godirwalk, gocodewalker, or fsnotify.

CLI
go install github.com/sergii-ziborov/treestamp/cmd/treestamp@v0.1.4

Without Go, download a treestamp-* binary from the CLI v0.1.4 release and check SHA256SUMS.txt. That release is the user command treestamp. It is not treestamp-driver.

treestamp
treestamp scan --help

A bare treestamp prints help. It does not hash the current directory.

Not the CLI

cmd/treestamp-driver speaks a JSON fixture protocol for parity tests. Do not go install it. Do not ship it as Treestamp.

Walk

package main

import (
	"fmt"
	"io/fs"
	"log"

	"github.com/sergii-ziborov/treestamp"
)

func main() {
	err := treestamp.WalkWithConfig(".", treestamp.Config{NumWorkers: 4},
		func(path string, d fs.DirEntry, err error) error {
			if err != nil || d.IsDir() {
				return err
			}
			fmt.Println(path)
			return nil
		})
	if err != nil {
		log.Fatal(err)
	}
}

Walk is serial. NumWorkers != 0 is the parallel opt-in. Config.Sort is legacy serial global DFS; SortMode is local and may stay parallel. Saved callback entries keep their names. Switch a fastwalk import to compat/fastwalk — worked example: consumer/. Runnable iterator: examples/walk.

This is not a claimed speed win over charlievieth/fastwalk v1.0.14.

New in this tree

Capability rows, not a ranking over fastwalk v1.0.14.

  • Walk / WalkDirs keep persistable listing entries. WalkDirs holds one []Entry; a saved callback keeps its name.
  • Parallel unsorted walk streams those entries and uses listing FileInfo. A Linux lazy dent is not Stated for that cache.
  • Workers start only when more than one directory remains. An explicit NumWorkers is not clipped to the native default cap of 8.
  • ReadDirnames calls Readdirnames(-1) (no ReadDir plus a name copy).
  • SortMode includes SortDirsFirst (directory, regular file, other). Serial Walk honors SortMode.
  • Ordered pull reserves a ready slot before listing, then adds bytes. ParallelWalkIter.Err is the constructor error from IntoIterOrderedBounded.
  • Options.IgnoreRules and FileWalker.CustomIgnorePatterns ignore; they do not invert. OverrideRules is the include list. Empty IgnoreRules keep the oracle descriptor v2 hash.
  • compat/fastwalk keeps a relative root relative. FollowOutside is always on so ErrTraverseLink can leave the root; Follow still decides auto-follow of every directory symlink.

Proven receipts

Official B01–B14 first-campaign rows are MEASURED on a 1000-file tree, TREESTAMP_OFFICIAL=1. Receipt: compat/results/official-benches.json (host Windows/AMD64, go1.26.5, 2026-09-17). Policy: BENCHMARKS.md.

set CGO_ENABLED=0
python tools/run_official_benches.py

These nanoseconds are host-local. They are not a 10k/100k/1M ranking and not Rust oracle percentages. The informal table below is a 20 September 2026 remasurement after persistable WalkDirs, Readdirnames, listing FileInfo, ordered ready reserve, and compat FollowOutside. Official B01–B14 stay the 17 September first campaign.

Pinned sources used with those receipts:

Pin Value
weavatrix-scan 0.5.2, commit 29c003a6ad541c9a10faf30505235375fa78b9d8
fastwalk (bench only) v1.0.14
gocodewalker (bench only) v1.5.1
godirwalk (bench only) v1.17.0
Informal listing table 20 September 2026 remasure (0.1.5 tree), INFORMAL_RUN.json

Do not follow live main of a competitor as the oracle. Do not rewrite official-benches.json or INFORMAL_RUN.json without a new host run.

Informal benches

Windows/amd64, Intel Core Ultra 7 255U, 20 September 2026 remasure. Go 1.26.5 (go env GOVERSION), module line 1.21.0, CGO_ENABLED=0, GOTOOLCHAIN=local. Comparators in bench/go-compat: fastwalk v1.0.14, gocodewalker v1.5.1, godirwalk v1.17.0. Medians of three runs on a ~400-file temp tree. Not a 15–25% release claim. Same-day earlier tables on this host swung hundreds of microseconds.

Case Treestamp Comparator
Raw serial walk 571 µs, 158 KiB, 1248 allocs fastwalk v1.0.14: 327 µs / 143 KiB; godirwalk v1.17.0: 489 µs / 208 KiB
Raw parallel walk 395 µs, 153 KiB, 1637 allocs fastwalk v1.0.14: 327 µs / 143 KiB
Regex ScanPaths 5.60 ms, 99 KiB, 1338 allocs gocodewalker v1.5.1: 8.18 ms / 134 KiB
Cached Stat 424 µs, 164 KiB, 1252 allocs fastwalk v1.0.14: 409 µs / 139 KiB; os.Stat 24.5 ms
DirScanner 2.01 ms, 647 KiB, 8152 allocs godirwalk v1.17.0: 1.86 ms / 564 KiB / 12008 allocs
Scratch ReadDirents 2.95 ms, 736 KiB, 8021 allocs godirwalk v1.17.0: 3.80 ms / 956 KiB / 12023 allocs
ReadDirnames 1.93 ms, 298 KiB, 4020 allocs godirwalk v1.17.0: 1.81 ms / 801 KiB / 8022 allocs

WalkFS is fs.WalkDir (same 2678 allocs). Compiled test-binary peak working set 55.0 MiB, process CPU 145 s on -test.count=1. Per-op memory is B/op, not that RSS. ReadDirnames drops about 4000 allocs versus godirwalk on this host because it no longer copies ReadDir entries. Raw walk still uses more B/op than fastwalk, and this remasure’s wall times are not a claimed speed win.

set CGO_ENABLED=0
set GOTOOLCHAIN=local
python tools/run_informal_benches.py

Receipt: bench/go-compat/INFORMAL_RUN.json. WalkDirs and listing methods vs godirwalk v1.17.0 (same remasure) are bench/go-compat/WALKDIRS_G05.md; they do not replace the table above.

Scan and explain

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/sergii-ziborov/treestamp"
)

func main() {
	ctx := context.Background()
	report, err := treestamp.ScanWith(ctx, ".", treestamp.WithExtensions("go"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(report.Summary())
	why, err := treestamp.Explain(".", "generated/model.go")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(why.Outcome, why.Source, why.Line, why.Pattern)
}

A nil error means selected work finished under the chosen policy. Runnable copy: examples/docquickstart. API pick: docs/choose-an-api.md.

Scan(ctx, root) and ScanPaths(ctx, root) keep two-argument signatures. Options{} is not DefaultOptions(). Explain is selection only. TreeSnapshot is an in-memory persistent structure, not a disk index. ContentProvider.Open returns loaded bytes, not an io.Reader.

CLI example

Same scanner as the library. Use it from CI or a shell. Do not use it as find, a watcher, or a hashdeep replacement.

# Pin the CLI package, not the whole checkout
treestamp scan ./cmd/treestamp --ext go --json --output ./baselines/cli.tstamp.json
treestamp verify ./baselines/cli.tstamp.json --root ./cmd/treestamp

# Why generated code is absent from that baseline
treestamp explain testdata/generated/model.go --root .

# Names only; paths does not apply binary or size checks
treestamp paths . --ext go --null | xargs -0 gofmt -l

--output cannot sit inside the scan root. verify re-applies the saved policy; it does not take the root from the file.

treestamp scan ./examples/docquickstart --ext go

treestamp scan

More commands: cmd/treestamp/README.md. Guide: docs/guides/cli.md.

Tasks

Task Start here
Choose an API docs/choose-an-api.md
Walk a tree docs/recipes/walk-fastwalk.md
List paths docs/recipes/scan-paths.md
Manifest / EachFile / Explain docs/index.md
Scan an fs.FS docs/choose-an-api.md
Replace godirwalk docs/recipes/walk-dirs.md
Replace fastwalk MIGRATING.md
Why a file was skipped docs/recipes/explain.md
Cache, snapshot, tree2 docs/guides/snapshots.md
Symptom → check docs/troubleshooting.md
Walker migration MIGRATING.md
CLI install and flags cmd/treestamp/README.md

The library is a native Go port of pinned Weavatrix Scan 0.5.2, plus Go-side additions (ScanFS, a growing-file read budget, MultiScanReport.Revision, WalkDirs / compat/godirwalk, compat/fastwalk, IgnoreRules). It is not a parser, search engine, graph, embedder, secret scanner, MCP server, web service, or daemon. Search, when ported, stays a consumer of this module.

Authorship and license

Personal public repository of Sergii Ziborov. Module: github.com/sergii-ziborov/treestamp. Not a Weavatrix or EdgeHawk organization repository. Oracle pin: weavatrix-scan 0.5.2, commit 29c003a6ad541c9a10faf30505235375fa78b9d8.

.treestampignore is not a default ignore file. Optional watch/ uses fsnotify and is never a main-module require.

MIT. Copyright (c) 2026 Sergii Ziborov.

Also: AGENTS.md, ARCHITECTURE.md, CONFORMANCE.md, THREAT_MODEL.md, RELEASE.md.

Documentation

Overview

Package treestamp is a native Go library for deterministic repository scanning.

It selects files under ignore and filter rules, hashes selected content, and explains why a path was kept or dropped. Start with ScanWith, ScanPathsWith, EachFile, or Compile. Explain is selection only; it does not re-read file bytes.

Requires Go 1.21 or newer. The command-line app is the nested module github.com/sergii-ziborov/treestamp/cmd/treestamp.

Index

Constants

View Source 
const (
	ScanDescriptorVersion  = scan.DescriptorVersion
	ScanCacheFormatVersion = scan.CacheFormatVersion
)
View Source 
const (
	IgnoreGitGlobal  = ignore.SourceGitGlobal
	IgnoreGitExclude = ignore.SourceGitExclude
	IgnoreGitIgnore  = ignore.SourceGitIgnore
	IgnoreDotIgnore  = ignore.SourceDotIgnore
	IgnoreCustom     = ignore.SourceCustom
	IgnoreExplicit   = ignore.SourceExplicit
	IgnoreOverride   = ignore.SourceOverride
	IgnoreGitModules = ignore.SourceGitModules
)
View Source 
const (
	SkipNone                   = selection.SkipNone
	SkipBinary                 = selection.SkipBinary
	SkipFileSystemBoundary     = selection.SkipFileSystemBoundary
	SkipExtension              = selection.SkipExtension
	SkipIgnored                = selection.SkipIgnored
	SkipIOError                = selection.SkipIOError
	SkipMaxDepth               = selection.SkipMaxDepth
	SkipOversized              = selection.SkipOversized
	SkipPathEscape             = selection.SkipPathEscape
	SkipStandardDirectory      = selection.SkipStandardDirectory
	SkipHidden                 = selection.SkipHidden
	SkipOverride               = selection.SkipOverride
	SkipSymlink                = selection.SkipSymlink
	SkipSymlinkLoop            = selection.SkipSymlinkLoop
	SkipScanLimit              = selection.SkipScanLimit
	SkipConcurrentModification = selection.SkipConcurrentModification
)
View Source 
const (
	ErrorContinue              = walk.ErrorContinue
	ErrorAbort                 = walk.ErrorAbort
	RootFollow                 = walk.RootFollow
	RootReject                 = walk.RootReject
	DefaultMaxOpen             = walk.DefaultMaxOpen
	OpCanonicalize             = walk.OpCanonicalize
	OpReadDirectory            = walk.OpReadDirectory
	OpReadEntry                = walk.OpReadEntry
	OpReadMetadata             = walk.OpReadMetadata
	OpScheduleWorker           = walk.OpScheduleWorker
	WalkSkipNone               = walk.SkipNone
	WalkSkipMaxDepth           = walk.SkipMaxDepth
	WalkSkipFileSystemBoundary = walk.SkipFileSystemBoundary
	WalkSkipPathEscape         = walk.SkipPathEscape
	WalkSkipSymlinkLoop        = walk.SkipSymlinkLoop
	WalkContinue               = walk.WalkContinue
	WalkSkip                   = walk.WalkSkip
	WalkQuit                   = walk.WalkQuit
	WalkTraverseLink           = walk.WalkTraverseLink
	SortNone                   = 0
	SortLexical                = 1
	SortFilesFirst             = 2
	SortDirsFirst              = 3
	SelectedFile               = selection.SelectedFile
	TraverseDirectory          = selection.TraverseDirectory
	Unselected                 = selection.Unselected
	RepoMatchNone              = ignore.MatchNone
	RepoMatchIgnore            = ignore.MatchIgnore
	RepoMatchInclude           = ignore.MatchInclude
	RepoOverrideIgnore         = ignore.MatchOverrideIgnore
	RepoOverrideInclude        = ignore.MatchOverrideInclude
	RepoMatchHidden            = ignore.MatchHidden
)
View Source 
const Version = "0.1.5"

Version is the library module version published with this tree.

Variables

View Source 
var (
	ErrPartial = dx.ErrPartial
	ErrStop    = dx.ErrStop
)

ErrPartial means selected work was incomplete. ErrStop is a deliberate EachFile halt.

View Source 
var (
	SkipDir         = fs.SkipDir
	SkipAll         = fs.SkipAll
	SkipThis        = walk.ErrSkipThis
	ErrSkipFiles    = walk.ErrSkipFiles
	ErrAdmitTimeout = runtime.ErrAdmitTimeout
	// ErrTraverseLink requests traversal of the callback's directory symlink.
	ErrTraverseLink = walk.ErrTraverseLink
)
View Source 
var ErrTerminateWalk = errors.New("treestamp terminated")

ErrTerminateWalk is returned when FileWalker.Terminate stops a walk.

Functions

func CollapsePathPrefixes 

func CollapsePathPrefixes(prefixes []string) []string

func DirEntryDepth 

func DirEntryDepth(entry fs.DirEntry) int

DirEntryDepth returns callback depth or -1 for another DirEntry type.

func FindRepositoryRoot 

func FindRepositoryRoot(start string) string

FindRepositoryRoot walks up from start looking for .git or .hg. If none is found it returns the absolute start directory.

func IsNotImplemented 

func IsNotImplemented(err error) bool

func IsSameOrDescendant 

func IsSameOrDescendant(path, prefix string) bool

func MinimumScratchBufferSize 

func MinimumScratchBufferSize() int

MinimumScratchBufferSize is the reusable getdents buffer floor. It is the page size on Unix and 0 on Windows.

func NameSort 

func NameSort(a, b os.DirEntry) int

func NewParallelMultiWalker 

func NewParallelMultiWalker(root string) *parallelMulti

func NewScratchBuffer 

func NewScratchBuffer() []byte

NewScratchBuffer allocates a reusable directory-read buffer.

func NewStatefulWalkBuilder 

func NewStatefulWalkBuilder[R, E any](root string, rootState R) *walk.StatefulWalkBuilder[R, E]

func PathCoveredByPrefixes 

func PathCoveredByPrefixes(path string, prefixes []string) bool

func ReadDirents 

func ReadDirents(dirname string) ([]os.DirEntry, error)

ReadDirents lists one directory. Prefer ReadDirentsScratch in a loop.

func ReadDirentsScratch 

func ReadDirentsScratch(dirname string, scratch []byte) ([]os.DirEntry, error)

ReadDirentsScratch lists one directory using an optional scratch buffer.

func ReadDirnames 

func ReadDirnames(dirname string, scratch []byte) ([]string, error)

ReadDirnames lists child names using an optional scratch buffer.

func SafeCause 

func SafeCause(err error) string

func ScanPaths 

func ScanPaths(ctx context.Context, root string) ([]string, error)

func ScanPathsFS added in v0.1.5 

func ScanPathsFS(ctx context.Context, fsys fs.FS, root string, opts ...Option) ([]string, error)

ScanPathsFS is ScanPathsWith over an fs.FS. Content options are rejected.

func ScanPathsWith 

func ScanPathsWith(ctx context.Context, root string, opts ...Option) ([]string, error)

func StatDirEntry 

func StatDirEntry(path string, entry fs.DirEntry) (fs.FileInfo, error)

StatDirEntry returns cached os.Stat metadata when entry supports it.

func Walk 

func Walk(root string, fn WalkDirFunc) error

func WalkDefault 

func WalkDefault(root string, fn WalkDirFunc) error

func WalkDirs 

func WalkDirs(root string, opts DirWalkOptions) error

func WalkFS 

func WalkFS(fsys fs.FS, root string, fn fs.WalkDirFunc) error

WalkFS walks an arbitrary fs.FS with fs.WalkDir-compatible callback control.

func WalkParallel 

func WalkParallel(root string, workers int, fn walk.WalkFunc) error

func WalkUnsorted 

func WalkUnsorted(root string, fn WalkDirFunc) error

func WalkWithConfig 

func WalkWithConfig(root string, cfg Config, fn WalkDirFunc) error

WalkWithConfig uses serial traversal when deterministic sorting is requested. Sort (bool) is the legacy global-order switch and is not SortMode. A callback may return ErrTraverseLink to select one directory symlink.

Types

type ByteLimit 

type ByteLimit = dx.ByteLimit

func LimitBytes 

func LimitBytes(n uint64) ByteLimit

func UnlimitedBytes 

func UnlimitedBytes() ByteLimit

func ZeroBytes 

func ZeroBytes() ByteLimit

type CacheValidationPolicy 

type CacheValidationPolicy int
const (
	CacheValidationFast CacheValidationPolicy = iota
	CacheValidationStrict
)

type CancellationToken 

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

func NewCancellationToken 

func NewCancellationToken() *CancellationToken

func (*CancellationToken) Cancel 

func (t *CancellationToken) Cancel()

func (*CancellationToken) IsCancelled 

func (t *CancellationToken) IsCancelled() bool

type ChangedContentVisitOutcome 

type ChangedContentVisitOutcome struct {
	Visited            *ChangedContentVisitReport
	FullRescanRequired bool
}

type ChangedContentVisitReport 

type ChangedContentVisitReport struct {
	Content ContentVisitReport
	Removed []string
}

type CompactContentEvidence 

type CompactContentEvidence struct {
	ContentHash        string      `json:"content_hash,omitempty"`
	ContentFingerprint string      `json:"content_fingerprint,omitempty"`
	Version            FileVersion `json:"version"`
	BinaryChecked      bool        `json:"binary_checked"`
}

type CompactScanReport 

type CompactScanReport struct {
	Root          string                 `json:"root"`
	Files         []CompactScannedFile   `json:"files"`
	Skipped       []SkippedEntry         `json:"skipped"`
	Warnings      []ScanWarning          `json:"warnings"`
	IgnoreSources []IgnoreSourceEvidence `json:"ignore_sources"`
	Revision      string                 `json:"revision"`
	Descriptor    ScanDescriptor         `json:"descriptor"`
	Complete      bool                   `json:"complete"`
	Termination   ScanTermination        `json:"termination,omitempty"`
	Portable      bool                   `json:"portable"`
	Cache         ScanCacheStats         `json:"cache"`
}

func ScanCompact 

func ScanCompact(ctx context.Context, root string) (*CompactScanReport, error)

func (CompactScanReport) AbsolutePath 

func (r CompactScanReport) AbsolutePath(file CompactScannedFile) string

func (CompactScanReport) IntoScanReport 

func (r CompactScanReport) IntoScanReport() ScanReport

func (*CompactScanReport) Summary 

func (r *CompactScanReport) Summary() ScanSummary

func (*CompactScanReport) ToCache 

func (r *CompactScanReport) ToCache() ScanCache

type CompactScannedFile 

type CompactScannedFile struct {
	Relative    string                  `json:"relative"`
	Bytes       uint64                  `json:"bytes"`
	ContentHash string                  `json:"content_hash,omitempty"`
	Content     *CompactContentEvidence `json:"content,omitempty"`
}

type Config 

type Config struct {
	Follow, Sort, ToSlash, ContentsFirst, DirsFirst bool
	FollowOutside, KeepSkipAll                      bool
	NumWorkers, MaxDepth                            int
	SortMode                                        SortMode
}

type ContentDiscoveryMode 

type ContentDiscoveryMode int
const (
	ContentDiscoveryStreaming ContentDiscoveryMode = iota
	ContentDiscoveryBufferedParallel
)

type ContentFile 

type ContentFile struct {
	RootIndex                uint
	Sequence                 uint64
	Root, Absolute, Relative string
	Bytes                    uint64
}

type ContentFileStatus 

type ContentFileStatus int
const (
	ContentFileSelected ContentFileStatus = iota
	ContentFileBinary
	ContentFileChanged
)

type ContentValidationPolicy 

type ContentValidationPolicy int
const (
	ContentValidationFast ContentValidationPolicy = iota
	ContentValidationStrict
)

type ContentVisitControl 

type ContentVisitControl int
const (
	ContentVisitContinue ContentVisitControl = iota
	ContentVisitSkipFile
	ContentVisitQuit
)

type ContentVisitEvent 

type ContentVisitEvent struct {
	FileStart, Chunk, FileEnd bool
	WorkerIndex               int
	File                      ContentFile
	Offset                    uint64
	Bytes                     []byte
	Status                    ContentFileStatus
	BytesRead                 uint64
	ContentHash               string
	ConsumerSkipped           bool
}

type ContentVisitMode 

type ContentVisitMode int
const (
	ContentVisitRevision ContentVisitMode = iota
	ContentVisitStreaming
)

type ContentVisitReport 

type ContentVisitReport struct {
	Mode                                                                            ContentVisitMode
	Root                                                                            string
	Discovered, Completed, Opened, Chunks, BytesRead, BytesEmitted, ConsumerSkipped uint64
	Stopped                                                                         bool
	Skipped                                                                         []SkippedEntry
	Warnings                                                                        []ScanWarning
	IgnoreSources                                                                   []IgnoreSourceEvidence
	Revision                                                                        string
	Complete                                                                        bool
	Termination                                                                     ScanTermination
	Portable                                                                        bool
	Cache                                                                           ScanCacheStats
}

type ContentVisitor 

type ContentVisitor func(ContentVisitEvent) ContentVisitControl

type DeltaQuality 

type DeltaQuality int
const (
	DeltaContentHash DeltaQuality = iota
	DeltaMetadata
	DeltaPartial
)

type DirEntry 

type DirEntry = walk.DirEntry

type DirScanner 

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

DirScanner yields one child at a time from a single directory. It is not the repository Scanner.

func NewDirScanner 

func NewDirScanner(dirname string) (*DirScanner, error)

NewDirScanner opens a lazy single-directory scanner.

func NewDirScannerScratch 

func NewDirScannerScratch(dirname string, scratch []byte) (*DirScanner, error)

NewDirScannerScratch opens a lazy scanner with a reusable scratch buffer.

func (*DirScanner) Close 

func (s *DirScanner) Close() error

func (*DirScanner) Dirent 

func (s *DirScanner) Dirent() (os.DirEntry, error)

func (*DirScanner) Err 

func (s *DirScanner) Err() error

func (*DirScanner) Name 

func (s *DirScanner) Name() string

func (*DirScanner) Scan 

func (s *DirScanner) Scan() bool

type DirWalkOptions 

type DirWalkOptions struct {
	Callback             WalkDirFunc
	PostChildrenCallback WalkDirFunc
	ErrorCallback        func(path string, err error) error
	Unsorted             bool
	FollowSymbolicLinks  bool
	ContentsFirst        bool
	DirsFirst            bool
	AllowNonDirectory    bool
	NumWorkers           int
	ToSlash              bool
	ScratchBuffer        []byte
	MaxOpen              int
	Context              context.Context
}

DirWalkOptions is the godirwalk-shaped callback surface.

type EntryFilter added in v0.1.5 

type EntryFilter = walkcfg.EntryFilter

func NewEntryFilter added in v0.1.5 

func NewEntryFilter() *EntryFilter

type Error 

type Error struct {
	Code ErrorCode
	Op   string
	Path string
	Err  error
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorCode 

type ErrorCode string
const (
	CodeNotImplemented ErrorCode = "not_implemented"
	CodeInvalid        ErrorCode = "invalid"
	CodeWalk           ErrorCode = "walk"
	CodeCancelled      ErrorCode = "cancelled"
	CodeTimeout        ErrorCode = "timeout"
	CodeStale          ErrorCode = "stale_snapshot"
	CodePartial        ErrorCode = "partial"
	CodePermission     ErrorCode = "permission"
	CodeUnavailable    ErrorCode = "unavailable"
	CodeChanged        ErrorCode = "changed"
	CodeLimit          ErrorCode = "limit"
	CodeAdmission      ErrorCode = "admission"
	CodeUnsupported    ErrorCode = "unsupported"
	CodeCallback       ErrorCode = "callback"
	CodeCache          ErrorCode = "cache_corrupt"
)

type ErrorPolicy 

type ErrorPolicy = walk.ErrorPolicy

type EvidenceMode 

type EvidenceMode int
const (
	EvidenceComplete EvidenceMode = iota
	EvidenceSelectedFiles
)

type FSEntry 

type FSEntry = walkfs.Entry

type FSWalker 

type FSWalker = walkfs.Walker

func NewFSWalker 

func NewFSWalker(fsys fs.FS, root string) (*FSWalker, error)

NewFSWalker constructs a deterministic pull walker over an arbitrary fs.FS.

type File 

type File struct {
	Location string
	Filename string
}

func (*File) Path 

func (f *File) Path() string

type FileIdentity 

type FileIdentity = platform.Identity

type FileVersion 

type FileVersion = walk.FileVersion

type FileWalker 

type FileWalker struct {
	LocationExcludePattern []string
	IncludeDirectory       []string
	ExcludeDirectory       []string
	IncludeFilename        []string
	ExcludeFilename        []string
	IncludeDirectoryRegex  []*regexp.Regexp
	ExcludeDirectoryRegex  []*regexp.Regexp
	IncludeFilenameRegex   []*regexp.Regexp
	ExcludeFilenameRegex   []*regexp.Regexp
	ExcludeListExtensions  []string
	CustomIgnore           []string
	CustomIgnorePatterns   []string
	// contains filtered or unexported fields
}

func NewFileWalker 

func NewFileWalker(directory string, queue chan *File) *FileWalker

func NewParallelFileWalker 

func NewParallelFileWalker(directory string, queue chan *File, workers int) *FileWalker

func (*FileWalker) AddRoot 

func (w *FileWalker) AddRoot(directory string) *FileWalker

func (*FileWalker) AllowListExtensions 

func (w *FileWalker) AllowListExtensions(exts ...string) *FileWalker

func (*FileWalker) IgnoreBinaryFiles 

func (w *FileWalker) IgnoreBinaryFiles() *FileWalker

func (*FileWalker) IgnoreGitignore 

func (w *FileWalker) IgnoreGitignore() *FileWalker

func (*FileWalker) IgnoreIgnoreFile 

func (w *FileWalker) IgnoreIgnoreFile() *FileWalker

func (*FileWalker) IncludeHidden 

func (w *FileWalker) IncludeHidden(enabled bool) *FileWalker

func (*FileWalker) RespectGitModules 

func (w *FileWalker) RespectGitModules() *FileWalker

func (*FileWalker) SetConcurrency 

func (w *FileWalker) SetConcurrency(n int) *FileWalker

func (*FileWalker) SetErrorHandler 

func (w *FileWalker) SetErrorHandler(fn func(error) bool) *FileWalker

func (*FileWalker) SetMaxDepth 

func (w *FileWalker) SetMaxDepth(n int) *FileWalker

func (*FileWalker) Start 

func (w *FileWalker) Start() error

func (*FileWalker) Terminate 

func (w *FileWalker) Terminate()

func (*FileWalker) Walking 

func (w *FileWalker) Walking() bool

type Filters 

type Filters = selection.Filters

Filters is the public declarative name/dir/regex filter set.

func CompileFilters 

func CompileFilters(includeNames, excludeNames, includeDirs, excludeDirs []string, includeNameRE, excludeNameRE, includeDirRE, excludeDirRE []string) (Filters, error)

type FullRescanReason 

type FullRescanReason int
const (
	FullRescanPolicyChanged FullRescanReason = iota
	FullRescanIgnoreInputChanged
	FullRescanStructuralChange
	FullRescanIncompletePreviousState
)

type IgnoreFile 

type IgnoreFile struct {
	Kind     IgnoreSourceKind
	Location string
}

type IgnorePolicy 

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

func GitCompatibleIgnorePolicy 

func GitCompatibleIgnorePolicy() IgnorePolicy

func NoneIgnorePolicy 

func NoneIgnorePolicy() IgnorePolicy

func RepositoryIgnorePolicy 

func RepositoryIgnorePolicy() IgnorePolicy

func (IgnorePolicy) WithCustomIgnore 

func (p IgnorePolicy) WithCustomIgnore(enabled bool) IgnorePolicy

func (IgnorePolicy) WithDotIgnore 

func (p IgnorePolicy) WithDotIgnore(enabled bool) IgnorePolicy

func (IgnorePolicy) WithExplicitFile 

func (p IgnorePolicy) WithExplicitFile(path string) IgnorePolicy

func (IgnorePolicy) WithGitExclude 

func (p IgnorePolicy) WithGitExclude(enabled bool) IgnorePolicy

func (IgnorePolicy) WithGitGlobal 

func (p IgnorePolicy) WithGitGlobal(enabled bool) IgnorePolicy

func (IgnorePolicy) WithGitIgnore 

func (p IgnorePolicy) WithGitIgnore(enabled bool) IgnorePolicy

func (IgnorePolicy) WithParentRules 

func (p IgnorePolicy) WithParentRules(enabled bool) IgnorePolicy

func (IgnorePolicy) WithRequireGit 

func (p IgnorePolicy) WithRequireGit(enabled bool) IgnorePolicy

type IgnoreSourceEvidence 

type IgnoreSourceEvidence struct {
	Kind        IgnoreSourceKind `json:"kind"`
	Location    string           `json:"location"`
	ContentHash string           `json:"content_hash"`
}

type IgnoreSourceKind 

type IgnoreSourceKind = ignore.SourceKind

type ModifiedFile 

type ModifiedFile struct{ Previous, Current ScannedFile }

type MultiContentVisitReport 

type MultiContentVisitReport struct{ Reports []ContentVisitReport }

func (MultiContentVisitReport) IsEmpty 

func (r MultiContentVisitReport) IsEmpty() bool

func (MultiContentVisitReport) Len 

func (r MultiContentVisitReport) Len() int

type MultiScanReport 

type MultiScanReport struct{ Reports []*ScanReport }

func (MultiScanReport) IsEmpty 

func (r MultiScanReport) IsEmpty() bool

func (MultiScanReport) Len 

func (r MultiScanReport) Len() int

func (MultiScanReport) Revision added in v0.1.5 

func (r MultiScanReport) Revision() string

Revision is one digest over the ordered roots. It does not merge file lists.

type MultiScanner 

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

func NewMultiScanner 

func NewMultiScanner(root string) *MultiScanner

func (*MultiScanner) AddRoot 

func (m *MultiScanner) AddRoot(root string) *MultiScanner

func (*MultiScanner) Options 

func (m *MultiScanner) Options(options Options) *MultiScanner

func (*MultiScanner) Scan 

func (m *MultiScanner) Scan(ctx context.Context) (*MultiScanReport, error)

func (*MultiScanner) VisitContent 

func (m *MultiScanner) VisitContent(ctx context.Context, factory func(root, worker int) ContentVisitor) (*MultiContentVisitReport, error)

func (*MultiScanner) WithAdmitTimeout 

func (m *MultiScanner) WithAdmitTimeout(d time.Duration) *MultiScanner

func (*MultiScanner) WithRootParallelism 

func (m *MultiScanner) WithRootParallelism(n int) *MultiScanner

type MultiWalker 

type MultiWalker = walk.MultiWalker

type NamedFileTypes 

type NamedFileTypes = filetypes.NamedFileTypes

func DefaultFileTypes 

func DefaultFileTypes() *NamedFileTypes

type Option 

type Option func(*planBuilder) error

Option configures a compiled Plan. Scan and ScanPaths keep two-argument signatures.

func Using 

func Using(opts Options) Option

func WithAdmitTimeout added in v0.1.2 

func WithAdmitTimeout(d time.Duration) Option

func WithDetectBinary 

func WithDetectBinary(on bool) Option

func WithExcludeGlobs 

func WithExcludeGlobs(globs ...string) Option

func WithExtensions 

func WithExtensions(exts ...string) Option

func WithFailFast 

func WithFailFast() Option

func WithFilenameRegex 

func WithFilenameRegex(patterns ...string) Option

func WithHashContents 

func WithHashContents(on bool) Option

func WithLocationExclude 

func WithLocationExclude(globs ...string) Option

func WithLogger 

func WithLogger(logger *slog.Logger) Option

func WithMaxFileBytes 

func WithMaxFileBytes(n uint64) Option

func WithNoIgnore 

func WithNoIgnore() Option

func WithProgress 

func WithProgress(fn func(Progress)) Option

func WithReadLimit 

func WithReadLimit(lim ByteLimit) Option

func WithRequireCache 

func WithRequireCache() Option

func WithScope 

func WithScope(globs ...string) Option

type Options 

type Options struct {
	MaxFileBytes      uint64
	IgnoreFiles       []string
	OverrideRules     []string
	IgnoreRules       []string
	Extensions        []string
	FileTypes         *filetypes.NamedFileTypes
	IgnorePolicy      IgnorePolicy
	IgnoreCase        bool
	SkipHidden        bool
	StandardSkips     bool
	VCSSkips          bool
	GitModules        bool
	Filters           selection.Filters
	HashFileContents  bool
	DetectBinaryFiles bool
	EvidenceComplete  bool
	Evidence          EvidenceMode
	Walk              WalkOptions
	TraversalWorkers  int
	ContentWorkers    int
	Limits            ScanLimits
	Cancellation      *CancellationToken
	CacheValidation   CacheValidationPolicy
	ContentValidation ContentValidationPolicy
	ContentDiscovery  ContentDiscoveryMode
	AdmitTimeout      time.Duration
	// contains filtered or unexported fields
}

func DefaultOptions 

func DefaultOptions() Options

func (Options) MetadataOnly 

func (o Options) MetadataOnly() Options

func (Options) SelectedFilesOnly 

func (o Options) SelectedFilesOnly() Options

func (Options) WithAdmitTimeout added in v0.1.2 

func (o Options) WithAdmitTimeout(d time.Duration) Options

func (Options) WithCacheValidation 

func (o Options) WithCacheValidation(policy CacheValidationPolicy) Options

func (Options) WithCancellation 

func (o Options) WithCancellation(token *CancellationToken) Options

func (Options) WithContentDiscovery 

func (o Options) WithContentDiscovery(mode ContentDiscoveryMode) Options

func (Options) WithContentParallelism 

func (o Options) WithContentParallelism(n int) Options

func (Options) WithContentValidation 

func (o Options) WithContentValidation(policy ContentValidationPolicy) Options

func (Options) WithExcludeDirectories 

func (o Options) WithExcludeDirectories(dirs ...string) Options

func (Options) WithExcludeDirectoryRegex 

func (o Options) WithExcludeDirectoryRegex(patterns ...string) Options

func (Options) WithExcludeFilenameRegex 

func (o Options) WithExcludeFilenameRegex(patterns ...string) Options

func (Options) WithExcludeFilenames 

func (o Options) WithExcludeFilenames(names ...string) Options

func (Options) WithExtensions 

func (o Options) WithExtensions(exts ...string) Options

func (Options) WithFileTypes 

func (o Options) WithFileTypes(types *NamedFileTypes) Options

func (Options) WithFilters 

func (o Options) WithFilters(filters selection.Filters) Options

func (Options) WithGitModules 

func (o Options) WithGitModules(enabled bool) Options

func (Options) WithIgnoreCase 

func (o Options) WithIgnoreCase(enabled bool) Options

func (Options) WithIgnoreFiles 

func (o Options) WithIgnoreFiles(names ...string) Options

func (Options) WithIgnorePolicy 

func (o Options) WithIgnorePolicy(policy IgnorePolicy) Options

func (Options) WithIncludeFilenameRegex 

func (o Options) WithIncludeFilenameRegex(patterns ...string) Options

func (Options) WithIncludeFilenames 

func (o Options) WithIncludeFilenames(names ...string) Options

func (Options) WithMaxEntries 

func (o Options) WithMaxEntries(n uint64) Options

func (Options) WithMaxFileBytes 

func (o Options) WithMaxFileBytes(n uint64) Options

func (Options) WithMaxTotalBytes 

func (o Options) WithMaxTotalBytes(n uint64) Options

func (Options) WithOverrideRules 

func (o Options) WithOverrideRules(rules ...string) Options

func (Options) WithParallelism 

func (o Options) WithParallelism(n int) Options

func (Options) WithSkipHidden 

func (o Options) WithSkipHidden(enabled bool) Options

func (Options) WithStandardSkips 

func (o Options) WithStandardSkips(enabled bool) Options

func (Options) WithTimeout 

func (o Options) WithTimeout(d time.Duration) Options

func (Options) WithTraversalParallelism 

func (o Options) WithTraversalParallelism(n int) Options

func (Options) WithVCSSkips added in v0.1.5 

func (o Options) WithVCSSkips(enabled bool) Options

type ParallelExecutor 

type ParallelExecutor = runtime.Executor

type ParallelJob 

type ParallelJob = runtime.Job

type ParallelMultiVisitReport 

type ParallelMultiVisitReport struct {
	Visited uint64
	Errors  []*WalkError
	Quit    bool
}

type ParallelMultiWalkEvent 

type ParallelMultiWalkEvent struct {
	RootIndex int
	Event     WalkEvent
}

type ParallelMultiWalkReport 

type ParallelMultiWalkReport struct{ Reports []ParallelWalkReport }

type ParallelMultiWalker 

type ParallelMultiWalker = walk.MultiWalker

type ParallelRuntime 

type ParallelRuntime = runtime.Runtime

func DedicatedRuntime 

func DedicatedRuntime(n int) ParallelRuntime

func GlobalRuntime 

func GlobalRuntime() ParallelRuntime

func OwnedRuntime 

func OwnedRuntime(exec ParallelExecutor) ParallelRuntime

type ParallelVisitReport 

type ParallelVisitReport = walk.ParallelVisitReport

type ParallelWalkIter 

type ParallelWalkIter = walk.ParallelWalkIter

type ParallelWalkReport 

type ParallelWalkReport = walk.ParallelWalkReport

type ParallelWalker 

type ParallelWalker = walk.ParallelWalker

func NewParallelWalker 

func NewParallelWalker(root string) *ParallelWalker

type PathExplanation 

type PathExplanation struct {
	Relative, Outcome, Reason, Source, Pattern string
	Line                                       int
}

func Explain 

func Explain(root, relative string, opts ...Option) (PathExplanation, error)

type PathQuery 

type PathQuery = selection.PathQuery

type Plan 

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

Plan is an immutable compiled scan configuration. It does not hold Context.

func Compile 

func Compile(opts ...Option) (*Plan, error)

func (*Plan) Describe 

func (p *Plan) Describe() string

func (*Plan) EachFile 

func (p *Plan) EachFile(ctx context.Context, root string, consume func(ScannedFile, []byte) error) (*ScanSummary, error)

func (*Plan) EachFileFS added in v0.1.5 

func (p *Plan) EachFileFS(ctx context.Context, fsys fs.FS, root string, consume func(ScannedFile, []byte) error) (*ScanSummary, error)

func (*Plan) Explain 

func (p *Plan) Explain(root, relative string) (PathExplanation, error)

func (*Plan) Files 

func (p *Plan) Files(ctx context.Context, root string) func(func(ScannedFile, error) bool)

func (*Plan) Scan 

func (p *Plan) Scan(ctx context.Context, root string) (*ScanReport, error)

func (*Plan) ScanCached 

func (p *Plan) ScanCached(ctx context.Context, root string, cache *ScanCache) (*ScanReport, error)

func (*Plan) ScanFS added in v0.1.5 

func (p *Plan) ScanFS(ctx context.Context, fsys fs.FS, root string) (*ScanReport, error)

func (*Plan) ScanPaths 

func (p *Plan) ScanPaths(ctx context.Context, root string) ([]string, error)

func (*Plan) ScanPathsFS added in v0.1.5 

func (p *Plan) ScanPathsFS(ctx context.Context, fsys fs.FS, root string) ([]string, error)

func (*Plan) WriteDiagnostics 

func (p *Plan) WriteDiagnostics(w io.Writer, sum *ScanSummary) error

type PortableIgnoreSourceEvidence 

type PortableIgnoreSourceEvidence struct {
	Kind               IgnoreSourceKind `json:"kind"`
	RepositoryRelative string           `json:"repository_relative,omitempty"`
	ContentHash        string           `json:"content_hash"`
}

type PortableScanReport 

type PortableScanReport struct {
	Files             []PortableScannedFile          `json:"files"`
	Skipped           []PortableSkippedEntry         `json:"skipped"`
	Warnings          []PortableScanWarning          `json:"warnings"`
	IgnoreSources     []PortableIgnoreSourceEvidence `json:"ignore_sources"`
	Revision          string                         `json:"revision"`
	Descriptor        ScanDescriptor                 `json:"descriptor"`
	Complete          bool                           `json:"complete"`
	Termination       ScanTermination                `json:"termination,omitempty"`
	SelectionPortable bool                           `json:"selection_portable"`
}

type PortableScanWarning 

type PortableScanWarning struct {
	Relative    string `json:"relative,omitempty"`
	MessageHash string `json:"message_hash"`
}

type PortableScannedFile 

type PortableScannedFile struct {
	Relative      string `json:"relative"`
	Bytes         uint64 `json:"bytes"`
	ContentHash   string `json:"content_hash,omitempty"`
	BinaryChecked bool   `json:"binary_checked"`
}

type PortableSkippedEntry 

type PortableSkippedEntry struct {
	Relative   string   `json:"relative"`
	Kind       SkipKind `json:"kind"`
	DetailHash string   `json:"detail_hash,omitempty"`
}

type Progress 

type Progress = dx.Progress

type RenamedFile 

type RenamedFile struct{ Previous, Current ScannedFile }

type RepositoryMatch 

type RepositoryMatch = ignore.Match

type RepositoryMatcher 

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

func NewRepositoryMatcher 

func NewRepositoryMatcher(root string, opts Options) (*RepositoryMatcher, error)

func (*RepositoryMatcher) EnterDir 

func (m *RepositoryMatcher) EnterDir(abs, rel string) []string

func (*RepositoryMatcher) Match 

func (m *RepositoryMatcher) Match(relative string, isDir bool) RepositoryMatch

func (*RepositoryMatcher) Sources 

func (m *RepositoryMatcher) Sources() []IgnoreSourceEvidence

type RootSymlinkPolicy 

type RootSymlinkPolicy = walk.RootSymlinkPolicy

type ScanCache 

type ScanCache struct {
	FormatVersion uint32           `json:"format_version"`
	Root          string           `json:"root"`
	Entries       []ScanCacheEntry `json:"entries"`
}

func (*ScanCache) ApplyWatchPlan 

func (c *ScanCache) ApplyWatchPlan(plan WatchPlan) int

func (*ScanCache) Invalidate 

func (c *ScanCache) Invalidate(relativePaths []string) int

func (ScanCache) IsCompatible 

func (c ScanCache) IsCompatible(root string) bool

type ScanCacheEntry 

type ScanCacheEntry struct {
	Relative           string      `json:"relative"`
	ContentHash        string      `json:"content_hash,omitempty"`
	ContentFingerprint string      `json:"content_fingerprint,omitempty"`
	Bytes              uint64      `json:"bytes"`
	Version            FileVersion `json:"version"`
	BinaryChecked      bool        `json:"binary_checked"`
}

type ScanCacheStats 

type ScanCacheStats struct {
	ReusedHashes     uint64 `json:"reused_hashes"`
	ContentReads     uint64 `json:"content_reads"`
	FingerprintReads uint64 `json:"fingerprint_reads"`
	Rebuilt          bool   `json:"rebuilt,omitempty"`
}

type ScanDelta 

type ScanDelta struct {
	FromRevision, ToRevision                                string
	Added, Removed                                          []ScannedFile
	Modified                                                []ModifiedFile
	Renamed                                                 []RenamedFile
	Unchanged                                               uint64
	SelectionInputsChanged, PolicyChanged, ScanStateChanged bool
	Quality                                                 DeltaQuality
}

func DeltaBetween 

func DeltaBetween(previous, current *ScanReport) ScanDelta

func (ScanDelta) IsEmpty 

func (d ScanDelta) IsEmpty() bool

type ScanDescriptor 

type ScanDescriptor struct {
	Version uint32 `json:"version"`
	Policy  string `json:"policy"`
}

func DescriptorFromOptions 

func DescriptorFromOptions(opts Options) ScanDescriptor

func (ScanDescriptor) Matches 

func (d ScanDescriptor) Matches(opts Options) bool

type ScanLimits 

type ScanLimits struct {
	MaxEntries    *uint64
	MaxTotalBytes *uint64
	Timeout       time.Duration
}

type ScanOptions 

type ScanOptions = Options

type ScanReport 

type ScanReport struct {
	Root          string                 `json:"root"`
	Files         []ScannedFile          `json:"files"`
	Skipped       []SkippedEntry         `json:"skipped"`
	Warnings      []ScanWarning          `json:"warnings"`
	IgnoreSources []IgnoreSourceEvidence `json:"ignore_sources"`
	Revision      string                 `json:"revision"`
	Descriptor    ScanDescriptor         `json:"descriptor"`
	Complete      bool                   `json:"complete"`
	Termination   ScanTermination        `json:"termination,omitempty"`
	Portable      bool                   `json:"portable"`
	Cache         ScanCacheStats         `json:"cache"`
}

func Scan 

func Scan(ctx context.Context, root string) (*ScanReport, error)

func ScanFS added in v0.1.5 

func ScanFS(ctx context.Context, fsys fs.FS, root string, opts ...Option) (*ScanReport, error)

ScanFS is ScanWith over an fs.FS. Walk is lexical and does not follow symlinks. Native identity, ConfineAt, and cache reuse do not apply.

func ScanWith 

func ScanWith(ctx context.Context, root string, opts ...Option) (*ScanReport, error)

func (*ScanReport) ContentProvider 

func (r *ScanReport) ContentProvider() (*SnapshotContentProvider, error)

func (*ScanReport) Delta 

func (r *ScanReport) Delta(current *ScanReport) ScanDelta

func (*ScanReport) PortableFilesPage 

func (r *ScanReport) PortableFilesPage(offset, limit int) []PortableScannedFile

func (*ScanReport) Summary 

func (r *ScanReport) Summary() ScanSummary

func (*ScanReport) ToCache 

func (r *ScanReport) ToCache() ScanCache

func (*ScanReport) ToCompact 

func (r *ScanReport) ToCompact() CompactScanReport

func (*ScanReport) ToPortable 

func (r *ScanReport) ToPortable() PortableScanReport

type ScanSession 

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

func OpenScanSession 

func OpenScanSession(ctx context.Context, root string, opts Options) (*ScanSession, error)

func (*ScanSession) ApplyWatchPlan 

func (s *ScanSession) ApplyWatchPlan(ctx context.Context, plan WatchPlan) (*ScanReport, error)

func (*ScanSession) ApplyWatchPlanWithCancellation 

func (s *ScanSession) ApplyWatchPlanWithCancellation(ctx context.Context, plan WatchPlan, cancel *CancellationToken) (*ScanReport, error)

func (*ScanSession) FilesPage 

func (s *ScanSession) FilesPage(generation uint64, offset, limit int) ([]PortableScannedFile, error)

func (*ScanSession) Generation 

func (s *ScanSession) Generation() uint64

func (*ScanSession) IntoReport 

func (s *ScanSession) IntoReport() *ScanReport

func (*ScanSession) LastUpdateReason 

func (s *ScanSession) LastUpdateReason() (WatchUpdateReason, bool)

func (*ScanSession) Report 

func (s *ScanSession) Report() *ScanReport

func (*ScanSession) Rescan 

func (s *ScanSession) Rescan(ctx context.Context) (*ScanReport, error)

func (*ScanSession) Root 

func (s *ScanSession) Root() string

func (*ScanSession) TreeRevision 

func (s *ScanSession) TreeRevision() string

type ScanSink 

type ScanSink interface {
	OnFile(*ScannedFile) ScanSinkControl
}

type ScanSinkControl 

type ScanSinkControl int
const (
	ScanSinkContinue ScanSinkControl = iota
	ScanSinkStop
)

type ScanSinkFunc 

type ScanSinkFunc func(*ScannedFile) ScanSinkControl

func (ScanSinkFunc) OnFile 

func (f ScanSinkFunc) OnFile(file *ScannedFile) ScanSinkControl

type ScanStreamReport 

type ScanStreamReport struct {
	Root              string
	Selected, Emitted uint64
	Stopped           bool
	Skipped           []SkippedEntry
	Warnings          []ScanWarning
	IgnoreSources     []IgnoreSourceEvidence
	Revision          string
	Complete          bool
	Termination       ScanTermination
	Portable          bool
	Cache             ScanCacheStats
}

func ScanIntoErr 

func ScanIntoErr(ctx context.Context, root string, fn func(*ScannedFile) error, opts ...Option) (*ScanStreamReport, error)

type ScanSummary 

type ScanSummary struct {
	SelectedFiles, HashedFiles, BinaryCheckedFiles, RecordedSkips, Warnings, IgnoreSources int
	SelectedBytes                                                                          uint64
	SkippedByKind                                                                          map[SkipKind]int
	Complete, Stopped                                                                      bool
	Termination                                                                            ScanTermination
	Portable                                                                               bool
	Cache                                                                                  ScanCacheStats
}

func EachFile 

func EachFile(ctx context.Context, root string, consume func(ScannedFile, []byte) error, opts ...Option) (*ScanSummary, error)

func EachFileFS added in v0.1.5 

func EachFileFS(ctx context.Context, fsys fs.FS, root string, consume func(ScannedFile, []byte) error, opts ...Option) (*ScanSummary, error)

EachFileFS is EachFile over an fs.FS. A callback error is not replayed.

func (ScanSummary) LogValue 

func (s ScanSummary) LogValue() slog.Value

func (ScanSummary) String 

func (s ScanSummary) String() string

type ScanTermination 

type ScanTermination int
const (
	TerminationNone ScanTermination = iota
	TerminationMaxEntries
	TerminationMaxTotalBytes
	TerminationTimeout
	TerminationCancelled
)

func (ScanTermination) String 

func (t ScanTermination) String() string

type ScanWarning 

type ScanWarning struct {
	Relative string `json:"relative,omitempty"`
	Message  string `json:"message"`
}

type ScannedFile 

type ScannedFile struct {
	Absolute           string      `json:"absolute"`
	Relative           string      `json:"relative"`
	ContentHash        string      `json:"content_hash,omitempty"`
	ContentFingerprint string      `json:"content_fingerprint,omitempty"`
	Bytes              uint64      `json:"bytes"`
	Version            FileVersion `json:"version"`
	BinaryChecked      bool        `json:"binary_checked"`
	Binary             bool        `json:"binary,omitempty"`
}

func (ScannedFile) AbsolutePath 

func (f ScannedFile) AbsolutePath() string

type Scanner 

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

func NewScanner 

func NewScanner(root string, opts ...ScannerOption) (*Scanner, error)

func (*Scanner) Explain 

func (s *Scanner) Explain(rel string) (PathExplanation, error)

Explain reports the winning selection rule for rel. It does not hash the file or apply binary / max-file-bytes checks.

func (*Scanner) Options 

func (s *Scanner) Options(options Options) *Scanner

func (*Scanner) Scan 

func (s *Scanner) Scan(ctx context.Context) (*ScanReport, error)

func (*Scanner) ScanCached 

func (s *Scanner) ScanCached(ctx context.Context, cache *ScanCache) (*ScanReport, error)

func (*Scanner) ScanCompact 

func (s *Scanner) ScanCompact(ctx context.Context) (*CompactScanReport, error)

func (*Scanner) ScanIncremental 

func (s *Scanner) ScanIncremental(ctx context.Context, previous *ScanReport) (*ScanReport, error)

func (*Scanner) ScanInto 

func (s *Scanner) ScanInto(ctx context.Context, sink ScanSink) (*ScanStreamReport, error)

func (*Scanner) ScanPaths 

func (s *Scanner) ScanPaths(ctx context.Context) ([]string, error)

func (*Scanner) ScanWatchPlan 

func (s *Scanner) ScanWatchPlan(ctx context.Context, previous *ScanReport, plan WatchPlan) (*ScanReport, error)

func (*Scanner) ScanWatchPlanDetailed 

func (s *Scanner) ScanWatchPlanDetailed(ctx context.Context, previous *ScanReport, plan WatchPlan) (*WatchUpdate, error)

func (*Scanner) VisitChangedContent 

func (s *Scanner) VisitChangedContent(ctx context.Context, plan WatchPlan, factory func(worker int) ContentVisitor) (ChangedContentVisitOutcome, error)

func (*Scanner) VisitContent 

func (s *Scanner) VisitContent(ctx context.Context, factory func(worker int) ContentVisitor) (*ContentVisitReport, error)

func (*Scanner) VisitContentManifest 

func (s *Scanner) VisitContentManifest(ctx context.Context, factory func(worker int) ContentVisitor) (*CompactScanReport, error)

func (*Scanner) VisitContentStreaming 

func (s *Scanner) VisitContentStreaming(ctx context.Context, factory func(worker int) ContentVisitor) (*ContentVisitReport, error)

type ScannerOption 

type ScannerOption func(*scannerConfig)

func WithContentWorkers 

func WithContentWorkers(n int) ScannerOption

func WithOptions 

func WithOptions(options Options) ScannerOption

func WithTraversalWorkers 

func WithTraversalWorkers(n int) ScannerOption

type SelectionDecision 

type SelectionDecision = selection.Decision

type SelectionDisposition 

type SelectionDisposition = selection.Disposition

type SelectionMatcher 

type SelectionMatcher = selection.Matcher

func NewSelectionMatcher 

func NewSelectionMatcher(root string, opts Options) (*SelectionMatcher, error)

type SkipKind 

type SkipKind = selection.SkipKind

type SkippedEntry 

type SkippedEntry struct {
	Relative string   `json:"relative"`
	Kind     SkipKind `json:"kind"`
	Detail   string   `json:"detail,omitempty"`
}

type SnapshotContent 

type SnapshotContent struct {
	Relative string
	Bytes    []byte
	Evidence SnapshotEvidence
}

type SnapshotContentProvider 

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

func (*SnapshotContentProvider) Open 

func (p *SnapshotContentProvider) Open(relative string) (*SnapshotContent, error)

Open loads verified bytes for relative. It does not return an io.Reader.

func (*SnapshotContentProvider) Read 

func (p *SnapshotContentProvider) Read(relative string) (*SnapshotContent, error)

func (*SnapshotContentProvider) ReadBounded 

func (p *SnapshotContentProvider) ReadBounded(relative string, maxBytes uint64) (*SnapshotContent, error)

type SnapshotEvidence 

type SnapshotEvidence int
const (
	SnapshotFileVersion SnapshotEvidence = iota
	SnapshotSHA256
)

type SnapshotReadError 

type SnapshotReadError struct {
	Relative        string
	Reason          string
	Bytes, MaxBytes uint64
	Err             error
}

func (*SnapshotReadError) Error 

func (e *SnapshotReadError) Error() string

func (*SnapshotReadError) Unwrap 

func (e *SnapshotReadError) Unwrap() error

type SortMode added in v0.1.5 

type SortMode = int

type StandardSkips 

type StandardSkips int
const (
	StandardSkipsEnabled StandardSkips = iota
	StandardSkipsDisabled
)

type TreeSnapshot 

type TreeSnapshot struct {
	Cover merkle.Coverage
	// contains filtered or unexported fields
}

TreeSnapshot is a persistent keyed Merkle index. It is not LegacyRevision.

func SnapshotFromFiles 

func SnapshotFromFiles(files []ScannedFile) *TreeSnapshot

func (*TreeSnapshot) Apply 

func (s *TreeSnapshot) Apply(upserts, deletes []ScannedFile) *TreeSnapshot

func (*TreeSnapshot) Len 

func (s *TreeSnapshot) Len() int

func (*TreeSnapshot) TreeRevision 

func (s *TreeSnapshot) TreeRevision() string

type WalkBuilder 

type WalkBuilder = walk.Builder

func NewWalkBuilder 

func NewWalkBuilder(root string) *WalkBuilder

type WalkControl 

type WalkControl = walk.WalkControl

type WalkDirFunc 

type WalkDirFunc = fs.WalkDirFunc

func IgnoreDuplicateDirs 

func IgnoreDuplicateDirs(fn WalkDirFunc) WalkDirFunc

func IgnoreDuplicateFiles 

func IgnoreDuplicateFiles(fn WalkDirFunc) WalkDirFunc

func IgnorePermissionErrors added in v0.1.5 

func IgnorePermissionErrors(fn WalkDirFunc) WalkDirFunc

type WalkEntry 

type WalkEntry = walk.WalkEntry

func CollectParallel 

func CollectParallel(root string, workers int, sortPaths bool) ([]*WalkEntry, error)

func CollectWalk 

func CollectWalk(next func() (*WalkEntry, error)) ([]*WalkEntry, error)

type WalkError 

type WalkError = walk.WalkError

type WalkEvent 

type WalkEvent = walk.WalkEvent

type WalkFunc 

type WalkFunc = walk.WalkFunc

type WalkOperation 

type WalkOperation = walk.WalkOperation

type WalkOptions 

type WalkOptions = walk.WalkOptions

func DefaultWalkOptions 

func DefaultWalkOptions() WalkOptions

type WalkSkipReason 

type WalkSkipReason = walk.WalkSkipReason

type Walker 

type Walker = walk.Walker

func NewWalker 

func NewWalker(root string) (*Walker, error)

func NewWalkerWithOptions 

func NewWalkerWithOptions(root string, options WalkOptions) (*Walker, error)

type WatchEvent 

type WatchEvent struct {
	Path string
	Kind WatchEventKind
}

func NewWatchEvent 

func NewWatchEvent(path string, kind WatchEventKind) WatchEvent

type WatchEventKind 

type WatchEventKind int
const (
	WatchCreate WatchEventKind = iota
	WatchModify
	WatchRemove
	WatchRenameFrom
	WatchRenameTo
	WatchDirectory
	WatchRescan
)

type WatchPlan 

type WatchPlan struct {
	Changed, Removed []string
	FullRescan       bool
	RejectedEvents   uint64
}

func (WatchPlan) ExpandRemoved 

func (p WatchPlan) ExpandRemoved(known []string) []string

func (WatchPlan) Invalidated 

func (p WatchPlan) Invalidated() []string

func (WatchPlan) InvalidatesPath 

func (p WatchPlan) InvalidatesPath(relative string) bool

type WatchUpdate 

type WatchUpdate struct {
	Report *ScanReport
	Reason WatchUpdateReason
}

type WatchUpdateReason 

type WatchUpdateReason int
const (
	WatchReasonIncremental WatchUpdateReason = iota
	WatchReasonFullPolicy
	WatchReasonFullIgnore
	WatchReasonFullStructural
	WatchReasonFullIncomplete
)

func (WatchUpdateReason) AsString 

func (r WatchUpdateReason) AsString() string

func (WatchUpdateReason) String 

func (r WatchUpdateReason) String() string

type WatcherEventAdapter 

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

func NewWatcherEventAdapter 

func NewWatcherEventAdapter(root string, ignoreFiles []string) (*WatcherEventAdapter, error)

func NewWatcherEventAdapterWithOptions 

func NewWatcherEventAdapterWithOptions(root string, opts Options) (*WatcherEventAdapter, error)

func (*WatcherEventAdapter) Plan 

func (a *WatcherEventAdapter) Plan(events []WatchEvent) WatchPlan

Source Files

View all Source files

Directories

Path Synopsis
cmd
treestamp-driver command
Command treestamp-driver speaks the Treestamp fixture protocol.
 Command treestamp-driver speaks the Treestamp fixture protocol.
treestamp module
compat
fastwalk
Package fastwalk is a Treestamp-backed compatibility entry for charlievieth/fastwalk v1.0.14.
 Package fastwalk is a Treestamp-backed compatibility entry for charlievieth/fastwalk v1.0.14.
godirwalk
Package godirwalk is a Treestamp-backed compatibility entry for karrick/godirwalk v1.17.0.
 Package godirwalk is a Treestamp-backed compatibility entry for karrick/godirwalk v1.17.0.
examples
docquickstart command
scan command
walk command
internal
dirread
Package dirread lists directory names and types without extra metadata.
 Package dirread lists directory names and types without extra metadata.
dx
fileread
filetypes
hashx
ignore
Package ignore holds nested ignore sources and precedence (P2).
 Package ignore holds nested ignore sources and precedence (P2).
listwalk
Package listwalk is the unsorted callback walk used by Walk / WalkDirs.
 Package listwalk is the unsorted callback walk used by Walk / WalkDirs.
merkle
Package merkle holds a persistent keyed snapshot tree.
 Package merkle holds a persistent keyed snapshot tree.
path
platform
report
runtime
Package runtime holds executors, admission, and bounded queues (P4).
 Package runtime holds executors, admission, and bounded queues (P4).
scan
selection
Package selection holds reusable matchers and named types (P2).
 Package selection holds reusable matchers and named types (P2).
walk
walkcfg
walkfs
Package walkfs traverses arbitrary io/fs filesystems.
 Package walkfs traverses arbitrary io/fs filesystems.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.