Documentation
¶
Overview ¶
Package lintwarn is the shared core of the CLI's advisory lint reads (cor:agt:040:13): the page DTOs, the fixed "unavailable" stderr class, and a fail-closed cursor loop that never returns a partial page as a complete one. Callers own their operation, flag and rendering (cli#1167, cli#2007).
Index ¶
- Constants
- func Line(w Warning, compiled bool) string
- func PromptSubject(what string, provenanceRevSeq int) string
- func ReportUnavailable(cmd *cobra.Command)
- func WriteSection(out io.Writer, label, subject string, page *Page, compiled bool) error
- type Budget
- type Fetch
- type HistFetch
- type HistFetchAt
- type HistItem
- type Page
- func Drain(ctx context.Context, allow func() bool, fetch Fetch) *Page
- func ReadHistoryLint(b *Budget, shownIDs []string, shownOffset, shownTotal int, first HistFetch, ...) []*Page
- func ReadRecordLint(b *Budget, wantID string, fetch RecordFetch) *Page
- func ReadSignatureLint(b *Budget, client graphql.Client, workerID string) *Page
- type PromptLint
- type PromptState
- type Raw
- type RecordFetch
- type Warning
Constants ¶
const ( ReadTimeout = 5 * time.Second MaxRequests = 1000 )
ReadTimeout and MaxRequests bound ALL the advisory reads of one command (cli#2007 §6). The budget starts when the main operation has succeeded and never constrains the main read or write; when it runs out, what is unfinished is unavailable, never wrong.
UnavailableClass is the one stderr line an unavailable advisory read prints, once per command. It never carries the underlying error.
UnavailableText is the one text for a null page: no conclusion is drawn, and it is never "no warnings" or "up to date".
Variables ¶
This section is empty.
Functions ¶
func Line ¶
Line renders one warning as " <KIND> <locator>: <server text>" (cli#2007 §5). The server's sentence is printed as it stands, with nothing added. compiled is true for lint of a compiled revision, where position is an immutable occurrence ordinal, not an offset. WORKER_LINK_MISSING is told apart by its workerField (both fields carry position 0). targetUrn, the pinned and newer revisions and an overridden loc print only when the server returned them.
func PromptSubject ¶
PromptSubject names the compiled revision the warnings belong to: the one recorded for the served prompt, never the Agent's newest compile.
func ReportUnavailable ¶
ReportUnavailable prints UnavailableClass once per command: never expose the provider error or infer why the advisory is unavailable. A diagnostic write failure cannot undo the command's success.
Types ¶
type Budget ¶
type Budget struct {
// contains filtered or unexported fields
}
Budget is the one advisory budget of a command. It is safe for concurrent use.
func NewBudget ¶
NewBudget starts the budget now, as a child of parent (which carries the caller's principal and session header, if any).
type Fetch ¶
Fetch reads one page after the cursor (nil for the first). Return nil, nil for a null page, or an error for any failure or identity mismatch: all of them make the whole read unavailable.
type HistFetchAt ¶
type HistFetchAt func(ctx context.Context, offset int, after *string) (total int, items []HistItem, err error)
HistFetchAt re-reads exactly one record by offset, after a lint cursor.
type HistItem ¶
type HistItem struct {
ID string
Lint *gen.LintWarningPageFields
}
HistItem is one record of a history page with its inline first lint page.
type Page ¶
type Page struct {
Items []Warning `json:"items"`
Total int `json:"total"`
NextCursor *string `json:"nextCursor"`
}
Page is a completed read: every page drained, never partial.
func Drain ¶
Drain follows the cursor to the end and returns nil (unavailable) on any error, null page, nil items, negative or drifting total, empty or repeated cursor, short final page, or when allow reports the request budget spent. allow is asked before every request.
func ReadHistoryLint ¶
func ReadHistoryLint(b *Budget, shownIDs []string, shownOffset, shownTotal int, first HistFetch, at HistFetchAt) []*Page
ReadHistoryLint returns, for each shown record (ids in display order, the page starting at shownOffset of shownTotal), its lint page or nil. Each record is whole or nil, never partial and never another record's: the inline first page counts only if item i has the shown id and the history total is unchanged; a record with more pages is drained one at a time by offset and every page must return that one record with the same lint and history total.
func ReadRecordLint ¶
func ReadRecordLint(b *Budget, wantID string, fetch RecordFetch) *Page
ReadRecordLint drains the lint of the single record the command shows (worker or run served-prompt). Every page must come from record wantID.
type PromptLint ¶
type PromptLint struct {
State PromptState
Page *Page
// ServedID and ProvenanceRevSeq name the record the warnings belong to
// (never the Agent's newest compile).
ServedID string
ProvenanceRevSeq int
}
PromptLint is the outcome of Worker.promptLintWarnings.
func ReadPromptLint ¶
func ReadPromptLint(b *Budget, client graphql.Client, workerID string) PromptLint
ReadPromptLint drains Worker.promptLintWarnings. Nothing-served is told from unavailable by servedPrompt { id } in the same operation, never by hasLiveSession: an idle but open session still has a record and warnings.
type PromptState ¶
type PromptState string
PromptState says why a prompt read has, or has no, page.
const ( // PromptOK: the page answered (it may hold zero warnings). PromptOK PromptState = "ok" // PromptNothingServed: the worker has no served record for an open session. PromptNothingServed PromptState = "nothing-served" PromptUnavailable PromptState = "unavailable" )
type Raw ¶
Raw is one server page, converted by the caller's fetch. A nil Items slice or a nil element means the server broke its contract; the read is then unavailable, never partial.
type RecordFetch ¶
type RecordFetch func(ctx context.Context, after *string) (recordID string, page *gen.LintWarningPageFields, err error)
RecordFetch reads one lint page of ONE served record.
type Warning ¶
type Warning struct {
Kind string `json:"kind"`
Position int `json:"position"`
Text string `json:"text"`
TargetURN *string `json:"targetUrn"`
PinnedRevision *int `json:"pinnedRevision"`
NewerRevision *int `json:"newerRevision"`
OverriddenNodeLoc *string `json:"overriddenNodeLoc"`
WorkerField *string `json:"workerField"`
}
Warning is one lint warning as the CLI prints it (stable --json item shape).