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

collector

package
v0.2.5 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package collector produces Git-aware ingestion requests. It has no server or database dependency; CLI and agent hooks use the same collection entrypoint.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnchanged = errors.New("checkout unchanged")

ErrUnchanged means the checkout still matches its acknowledged fingerprint.

Functions

func Collect

func Collect(ctx context.Context, directory string, options Options) (ingestion.Request, error)

func CollectChanged

func CollectChanged(ctx context.Context, directory string, options Options, previousFingerprint string) (result ingestion.Request, fingerprint string, failure error)

CollectChanged checks complete content identity before constructing previews. A nonempty fingerprint is safe to persist only after successful ingestion. Unknown identities always produce a request, even when a prior value exists.

func CollectPatch

func CollectPatch(ctx context.Context, raw, directory string, options Options) (result ingestion.Request, failure error)

CollectPatch records immutable input with its submission directory as provenance.

func Fingerprint

func Fingerprint(request ingestion.Request) string

Fingerprint identifies checkout contents and stable provenance, excluding submission/agent/session/time and filesystem-based snapshot revisions. Empty means full identity cannot be proven; never use it to suppress a sync.

func SourceID

func SourceID() (string, error)

SourceID identifies this installation independently of its hostname/path. Ephemeral environments can provide DIFFX_SOURCE_ID explicitly.

func SourceIdentity

func SourceIdentity(ctx context.Context, root, sourceID, branch, base string) (string, error)

SourceIdentity uses persisted Git identities. Paths and branch labels are location hints, not the source's identity. Branch identifies object-only recovery; an empty branch identifies the live checkout.

func WithObservationFactory added in v0.2.4

func WithObservationFactory(ctx context.Context, factory ObservationFactory) context.Context

func WithObserver added in v0.2.4

func WithObserver(ctx context.Context, observer Observer) context.Context

Types

type Batch added in v0.2.1

type Batch struct {
	Failures    []Failure
	Diagnostics []string
}

Batch is one collection of every checkout discovered under the workspaces.

func CollectWorkspaces added in v0.2.1

func CollectWorkspaces(ctx context.Context, workspaces Workspaces, options Options, publish func(ingestion.Request) error) (Batch, error)

CollectWorkspaces discovers the workspaces again and collects each checkout independently with its own submission ID. A failed checkout never blocks the others or becomes an empty observation. Finding no checkout is an error. publish runs serially as requests finish. Its failure cancels and joins all remaining collection before returning. Four workers and a bounded result buffer limit completed requests waiting to publish.

type Discovery

type Discovery struct {
	Sources     []DiscoverySource
	Diagnostics []string
}

func DiscoverCheckout

func DiscoverCheckout(ctx context.Context, input, sourceID, base string) (Discovery, error)

DiscoverCheckout resolves only the selected live checkout. Non-Git input returns ErrNotRepository; callers decide whether to ignore a hook event.

func DiscoverWorkspaces added in v0.2.1

func DiscoverWorkspaces(ctx context.Context, workspaces Workspaces, sourceID, base string) (Discovery, error)

DiscoverWorkspaces finds every live checkout under the supplied paths. A path inside a repository resolves to its root; otherwise directories are walked up to depth levels, stopping at repositories and skipping hidden, node_modules and vendor directories. With LinkedWorktrees, each repository contributes all registered worktrees, including those outside the paths. It never fetches, switches branches, creates worktrees or follows symbolic links.

type DiscoverySource

type DiscoverySource struct {
	InputPath string
	Path      string
	Branch    string
	Base      string
	Identity  string
}

type Failure added in v0.2.1

type Failure struct {
	Path         string
	Detail       string
	Code         string
	DiagnosticID string
}

Failure names a discovered checkout that could not be collected.

type Observation added in v0.2.4

type Observation struct {
	Stage   string
	Scope   review.DiffMode
	Attempt int
	Files   int
	Commits int
}

Observation describes collection work without exposing captured contents.

type ObservationFactory added in v0.2.4

type ObservationFactory func(context.Context, string) (context.Context, func(error) error)

ObservationFactory creates an independent recorder for each checkout or discovery attempt. Its completion may annotate an error, preserving Unwrap.

type Observer added in v0.2.4

type Observer interface {
	BeginStage(Observation) func(error)
	Workload(Observation)
}

Observer lives beside its consumer. Composition owns recording and storage.

type Options

type Options struct {
	SourceID         string
	Hostname         string
	RunID            string
	Agent            string
	SessionName      string
	Trigger          string
	TriggerRoot      string
	CollectorVersion string
	SubmissionID     string
	Base             string
	Branch           string
	OnSource         func(ingestion.Metadata, diffsource.Comparison)
	// Identity supplies repository, checkout and branch identity instead of
	// enrolling it in Git metadata, for producers that own identity elsewhere.
	Identity *diffsource.StableRepositoryIdentity
}

type Workspaces added in v0.2.2

type Workspaces struct {
	Paths []string
	// Depth bounds the directory levels walked below a path outside a repository.
	Depth int
	// LinkedWorktrees adds every registered worktree of each repository found;
	// otherwise a repository contributes only the checkout containing its path.
	LinkedWorktrees bool
}

Workspaces selects the checkouts a local process collects.

Jump to

Keyboard shortcuts

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