Documentation
¶
Overview ¶
Package delivery is the shared advisory-delivery transaction of the edit hooks. One edit event from any client runs one sequence: normalize the paths, select the lessons, lease the once-per-context state, emit, commit, and audit. The package owns that order, so a client adapter cannot mark advice delivered before the client has it.
The package does not know a native payload. A client adapter decodes the event before Deliver and encodes the advice inside the emit callback. The package makes no model call and never blocks an edit: every failure leaves the advice eligible for a later event.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Reset ¶
func Reset(req ResetRequest) error
Reset starts a new delivery generation for the receiving context of the event, so its lessons can be emitted once again. An event that names no resettable context resets nothing: a missing identity must not reset an unrelated context. Reset never creates state: it is a no-op until once-per-context delivery has been used.
Types ¶
type Emit ¶
Emit encodes the advisory text for the client and writes it. Deliver calls it at most once, after selection and suppression. An error means the client did not get the advice.
type EmitError ¶
type EmitError struct {
Err error
}
EmitError wraps an error of the emit callback. The caller can tell a failed client reply apart from a failed lesson lookup: the reply error is the hook's own failure, and a lookup error must stay quiet.
type Normalized ¶
type Normalized struct {
// Files lists the workspace files, repository-relative with forward
// slashes, in first-appearance order and without duplicates.
Files []string
// Rejected holds the first maxRejections rejected paths.
Rejected []RejectedPath
// RejectedCount counts every rejected path, kept or not.
RejectedCount int
}
Normalized is the result of NormalizePaths.
func NormalizePaths ¶
func NormalizePaths(root, cwd string, paths []string) Normalized
NormalizePaths turns the native paths of one edit event into repository-relative files. A relative path resolves against cwd, the working directory of the event. An empty cwd means the workspace root, and a relative cwd resolves against the workspace root.
A path does not need to exist: new, deleted, and moved files are still in scope by path. The function follows every link of a path, in the order the operating system follows them. It rejects a path whose real location is outside the workspace, so a link never selects lessons for an unrelated tree. The result names the real location, because lessons follow the real file.
The function reports each rejected path. The caller gets the count of all rejections and the first few rejected paths.
type Outcome ¶
type Outcome struct {
Status Status
// Files lists the normalized files that selection used.
Files []string
// Rejected holds the first rejected native paths, and RejectedCount
// counts all of them. The values are raw client input.
Rejected []RejectedPath
RejectedCount int
// Emitted and Suppressed count lessons. HeldBackPins counts the
// applicable pins that the budget left out of the advice.
Emitted int
Suppressed int
HeldBackPins int
// Generation is the context generation of the lease, or zero
// without a lease.
Generation uint64
// ContextBytes is the exact size of the emitted advisory text.
ContextBytes int
Suppression Suppression
// AuditFailed is true when a firing-log append failed. The delivery
// result does not change: the log is best effort.
AuditFailed bool
}
Outcome describes one delivery for diagnostics and tests. The hook prints none of it: a hook writes only the native reply.
func Deliver ¶
Deliver runs the delivery sequence for one edit event. st must be an open index: Deliver does not index, mine, or create a database.
The error is an *EmitError when the emit callback fails. It is a plain error when the lesson lookup fails or ctx ends. In both cases Deliver marks no lesson delivered and records no injection.
type RejectReason ¶
type RejectReason string
RejectReason says why a native path gives no workspace file.
const ( // RejectMalformed is an empty path or a path with a NUL byte. RejectMalformed RejectReason = "malformed path" // RejectOutside is a path that resolves outside the workspace. RejectOutside RejectReason = "outside the workspace" // RejectUnresolvable is a path whose real location is unknown: the // links form a loop, or a directory on the way is not readable. RejectUnresolvable RejectReason = "real location is not resolvable" )
The reasons NormalizePaths rejects a path.
type RejectedPath ¶
type RejectedPath struct {
Path string
Reason RejectReason
}
RejectedPath is one native path that selection does not use. Path is the raw client value: sanitize it before display.
type Request ¶
type Request struct {
// Root is the canonical workspace root.
Root string
// ClientID is the resolved registry ID of the client. It comes from
// the CLI selection and never from the hook payload, so a payload
// cannot claim the state of another client.
ClientID string
// Mechanism is the adapter's name for the native path of the advice.
// The firing log records it beside the client.
Mechanism string
// Event is the decoded native event. Event.Context is the receiving
// context; nil keeps suppression off.
Event integration.EditEvent
// Config is the lessons configuration of the workspace. Nil means
// the defaults.
Config *reviews.Config
}
Request is one edit event to advise on.
type ResetRequest ¶
type ResetRequest struct {
// Root is the canonical workspace root.
Root string
// ClientID is the resolved registry ID of the client.
ClientID string
// Event is the decoded native reset event.
Event integration.ResetEvent
}
ResetRequest is one context-reset event.
type Status ¶
type Status string
Status is the visible result of one delivery.
const ( // StatusSilent means no lesson applies, so Deliver writes nothing. StatusSilent Status = "silent" // StatusEmitted means the emit callback accepts the advice. StatusEmitted Status = "emitted" // StatusSuppressed means this receiving context already has every // matching lesson, so Deliver writes nothing. StatusSuppressed Status = "suppressed" )
The delivery results.
type Suppression ¶
type Suppression string
Suppression says whether once-per-context suppression applied, and why not when it did not. Every state except SuppressionActive means repeated delivery: the advice is emitted on every matching event.
const ( // SuppressionOff means the configuration asks for repeated delivery. SuppressionOff Suppression = "off" // SuppressionActive means the lease selected the lessons to emit. SuppressionActive Suppression = "active" // SuppressionNoContext means the adapter identified no receiving // context, for example an event without a session id, or a client // whose adapter reads no receiver yet. SuppressionNoContext Suppression = "no-receiving-context" // SuppressionNotResettable means no reset event reaches the context. // Suppressed advice would then stay hidden after a compaction. SuppressionNotResettable Suppression = "context-not-resettable" // an unknown version, or on a platform without file locks. SuppressionStateUnavailable Suppression = "state-unavailable" // SuppressionCommitFailed means the emission succeeds and the state // write fails. A later event emits the same advice again. SuppressionCommitFailed Suppression = "commit-failed" )
The suppression states.
Source Files