lintwarn

package
v0.47.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
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.

View Source
const UnavailableClass = "lint warnings: unavailable (advisory read did not complete)"

UnavailableClass is the one stderr line an unavailable advisory read prints, once per command. It never carries the underlying error.

View Source
const UnavailableText = "unavailable (no conclusion about warnings)"

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

func Line(w Warning, compiled bool) string

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

func PromptSubject(what string, provenanceRevSeq int) string

PromptSubject names the compiled revision the warnings belong to: the one recorded for the served prompt, never the Agent's newest compile.

func ReportUnavailable

func ReportUnavailable(cmd *cobra.Command)

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.

func WriteSection

func WriteSection(out io.Writer, label, subject string, page *Page, compiled bool) error

WriteSection prints "<label>: ..." for a drained page, or the unavailable line for nil. subject says what the warnings are about.

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

func NewBudget(parent context.Context) *Budget

NewBudget starts the budget now, as a child of parent (which carries the caller's principal and session header, if any).

func (*Budget) Allow

func (b *Budget) Allow() bool

Allow counts one request and reports whether it may go out.

func (*Budget) Close

func (b *Budget) Close()

Close releases the budget's timer.

func (*Budget) Ctx

func (b *Budget) Ctx() context.Context

Ctx is the context for lint requests only.

type Fetch

type Fetch func(ctx context.Context, after *string) (*Raw, error)

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 HistFetch

type HistFetch func(ctx context.Context) (total int, items []HistItem, err error)

HistFetch is one history read: the history total and its items.

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

func Drain(ctx context.Context, allow func() bool, fetch Fetch) *Page

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.

func ReadSignatureLint

func ReadSignatureLint(b *Budget, client graphql.Client, workerID string) *Page

ReadSignatureLint drains Worker.signatureLint. The op's worker id must be the worker the command shows; a different id is unavailable, never another worker's warnings. Nil means unavailable.

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: a record is served but the lint could not be read.
	PromptUnavailable PromptState = "unavailable"
)

type Raw

type Raw struct {
	Items      []*Warning
	Total      int
	NextCursor *string
}

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).

Jump to

Keyboard shortcuts

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