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 ¶
- Variables
- func Collect(ctx context.Context, directory string, options Options) (ingestion.Request, error)
- func CollectChanged(ctx context.Context, directory string, options Options, ...) (result ingestion.Request, fingerprint string, failure error)
- func CollectPatch(ctx context.Context, raw, directory string, options Options) (result ingestion.Request, failure error)
- func Fingerprint(request ingestion.Request) string
- func SourceID() (string, error)
- func SourceIdentity(ctx context.Context, root, sourceID, branch, base string) (string, error)
- func WithObservationFactory(ctx context.Context, factory ObservationFactory) context.Context
- func WithObserver(ctx context.Context, observer Observer) context.Context
- type Batch
- type Discovery
- type DiscoverySource
- type Failure
- type Observation
- type ObservationFactory
- type Observer
- type Options
- type Workspaces
Constants ¶
This section is empty.
Variables ¶
var ErrUnchanged = errors.New("checkout unchanged")
ErrUnchanged means the checkout still matches its acknowledged fingerprint.
Functions ¶
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 ¶
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 ¶
SourceID identifies this installation independently of its hostname/path. Ephemeral environments can provide DIFFX_SOURCE_ID explicitly.
func SourceIdentity ¶
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
Types ¶
type Batch ¶ added in v0.2.1
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 ¶
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 Observation ¶ added in v0.2.4
Observation describes collection work without exposing captured contents.
type ObservationFactory ¶ added in v0.2.4
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.