lints

package
v0.48.0 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package lints owns the lint registry and the verdict rules every check entry point shares.

The embedded lints.toml is the single authority for every lint selfdoc can emit, keyed by its name: its severity and its one-line description are declared there and nowhere else. LintResult derives its severity from the registry, so a construction site cannot state a severity and cannot emit an unregistered lint -- both are refused rather than discouraged. The lint-name enum in the declared check payload schema is pinned to the registry by a test, and the check guide's lint-rule table is rendered from the registry by the "table-lints" directive rather than repeated by hand. Each lint is also an option (options.go), whose registry is rendered from this one.

selfdoc's check command, the unified check, the post-build lint pass and the posts-only check all decide the same question -- does this run pass? -- and they used to decide it with four copies of the same three conditions. One copy had drifted: it compared documented against total public symbols directly, hardcoding a 100% coverage requirement, so a project that lowered its coverage threshold passed one check and failed the other on identical state. This package owns the rules.

Code generated by strictspec. DO NOT EDIT.

strictspec generator: 0.7.0 schema: selfdoc-lint-registry (format_version 1) regenerate: strictspec gen --manifest strictspec.toml

Released under the MIT license (unencumbered). This file is machine-generated; edit the schema and regenerate, never this file.

Index

Constants

View Source 
const (
	SettingError = "error"
	SettingWarn  = "warn"
	SettingOff   = "off"
)

The values a lint's option ranks. A repository's entry names one of them.

View Source 
const DefaultCoverageThreshold = 1.0

DefaultCoverageThreshold is the fraction of public symbols that must be documented when a project does not say otherwise. It mirrors the historical CLI default.

View Source 
const GENERATED_BY = "0.7.0"

GENERATED_BY is the strictspec release that produced this file. It is INFORMATIONAL: pairing is on GENERATED_CODE_FORMAT below, so a later release of the runtime reads this file unchanged, and no tool may derive a dependency floor from this string.

View Source 
const GENERATED_CODE_FORMAT = 2

GENERATED_CODE_FORMAT is the shape of generated code this file was written to. The runtime pairing guard hard-errors unless this format is one the linked runtime reads; the remedy is regeneration.

View Source 
const OptionsRegistryFormatVersion = 2

OptionsRegistryFormatVersion is the format version of the options registry selfdoc ships: the document's format_version, the one strictspec's built-in options-registry schema reads.

View Source 
const OptionsSubject = "docs"

OptionsSubject is the subject every selfdoc option is filed under, so every entry for one lives in .strictmetadata/options/docs.toml.

View Source 
const OptionsTool = "selfdoc"

OptionsTool is the namespace selfdoc's options live in: an entry names one as selfdoc:<lint name>.

View Source 
const SCHEMA_FORMAT_VERSION = 1

SCHEMA_FORMAT_VERSION is the document format_version this validator accepts.

Variables

This section is empty.

Functions

func BuildOptionsRegistry added in v0.46.0 

func BuildOptionsRegistry(raw []byte) (*strictspec.CheckedOptionsRegistry, error)

BuildOptionsRegistry validates registry-document bytes through strictspec, the shape against the built-in options-registry schema and then the registry rules, and returns the checked registry.

func CheckExitCode 

func CheckExitCode(
	lints []LintResult,
	directiveResults []DirectiveOutcome,
	coverage Coverage,
	config map[string]any,
) int

CheckExitCode computes the process exit code for a check run.

This is the single definition of "did this check pass": a run fails when a directive failed to resolve, when any lint is error-severity, or when documented coverage is under the configured threshold. It returns 1 when the run fails and 0 when it passes.

lints are the diagnostics the run produced, with the repository's lint options already applied (Settings.Apply). directiveResults are the per-directive resolution results, and are nil for a reduced entry point that resolved no directives (the post-build lint pass, the posts-only check). coverage is nil for an entry point that measured no coverage.

func CoverageBelowThreshold 

func CoverageBelowThreshold(coverage Coverage, config map[string]any) bool

CoverageBelowThreshold reports whether documented coverage is under the configured threshold.

config is the project configuration the run was driven by, read for "coverage_threshold"; a nil config means no configuration is in play, which uses DefaultCoverageThreshold. The answer is false whenever there is nothing to measure -- no coverage at all, or a project with no public symbols.

func LintSeverity 

func LintSeverity(name string) (string, error)

LintSeverity returns the registered severity of the named lint, or an UnknownLintNameError.

func OptionID added in v0.46.0 

func OptionID(name string) string

OptionID is the id an entry names a lint's option by.

func OptionsRegistry added in v0.46.0 

func OptionsRegistry() *strictspec.CheckedOptionsRegistry

OptionsRegistry returns selfdoc's shipped options registry, validated on first use. It panics when the embedded document is malformed, as Registered does: this build of selfdoc would not know its own options.

func OptionsRegistryDocument added in v0.46.0 

func OptionsRegistryDocument() []byte

OptionsRegistryDocument returns the shipped options registry exactly as it is embedded: the bytes of options.toml, which `selfdoc options registry` prints. The caller gets a copy, so the embedded document cannot be altered.

func RenderLintTable 

func RenderLintTable() string

RenderLintTable renders the registry as the Markdown table the documentation carries.

func RenderOptionsRegistry added in v0.46.0 

func RenderOptionsRegistry(reg *Registry) string

RenderOptionsRegistry renders the options registry a lint registry implies: one option per lint, in registry order. The shipped options.toml is this rendering of the shipped lint registry, written by `go run ./internal/lints/genoptions`, and a test holds the two together.

Types

type Coverage 

type Coverage interface {
	TotalPublic() int
	Documented() int
}

Coverage is what the verdict rules need from a run's coverage measurement: how many public symbols there are and how many of them are documented.

The concrete coverage type is the check package's, which measures far more than this; declaring the dependency as an interface here keeps this package below check in the import graph, as the Python module it ports was (the former blog package depended on selfdoc-core but not on selfdoc, so a posts-only install must reach the verdict without the check module present).

Pass a nil Coverage for a run that measured no coverage. A non-nil interface holding a nil pointer is not the same thing and will panic.

type DirectiveOutcome 

type DirectiveOutcome interface {
	Status() string
}

DirectiveOutcome is what the verdict rules need from one directive's resolution result: its status, which is "OK" or "FAILED".

As with Coverage, the concrete type is the check package's.

type LintDescriptor 

type LintDescriptor struct {
	Name        string
	Severity    string
	Description string
}

LintDescriptor is the frozen typed binding of the "LintDescriptor" record. Fields are immutable by convention (shallow-plus-generated-immutability); use With* for copy-on-write.

func (*LintDescriptor) WithDescription 

func (x *LintDescriptor) WithDescription(v string) *LintDescriptor

WithDescription returns a copy of LintDescriptor with Description set to the given value.

func (*LintDescriptor) WithName added in v0.46.0 

func (x *LintDescriptor) WithName(v string) *LintDescriptor

WithName returns a copy of LintDescriptor with Name set to the given value.

func (*LintDescriptor) WithSeverity 

func (x *LintDescriptor) WithSeverity(v string) *LintDescriptor

WithSeverity returns a copy of LintDescriptor with Severity set to the given value.

type LintRegistry 

type LintRegistry struct {
	FormatVersion int64
	Lints         []*LintDescriptor
}

LintRegistry is the frozen typed binding of the "LintRegistry" record. Fields are immutable by convention (shallow-plus-generated-immutability); use With* for copy-on-write.

func ValidateBytes 

func ValidateBytes(input []byte, syntax string) (*LintRegistry, []strictspec.Diagnostic)

ValidateBytes is the raw-bytes entry point: lossless parse of input in the given syntax ("json" | "toml" | "jsonl"), then validate. It returns the typed root value (nil when any diagnostic fired) and the ordered diagnostics.

func ValidateBytesWithEvidence 

func ValidateBytesWithEvidence(input []byte, syntax string, evidence map[string][]map[string]any) (*LintRegistry, []strictspec.Diagnostic)

ValidateBytesWithEvidence is ValidateBytes plus cross-document resolver evidence for the constraint vocabulary.

func ValidateValue 

func ValidateValue(v strictspec.Value) (*LintRegistry, []strictspec.Diagnostic)

ValidateValue is the tagged-value entry point: validate an already-parsed tagged document value (from strictspec.LoadValue or a typed constructor).

func (*LintRegistry) WithFormatVersion 

func (x *LintRegistry) WithFormatVersion(v int64) *LintRegistry

WithFormatVersion returns a copy of LintRegistry with FormatVersion set to the given value.

func (*LintRegistry) WithLints 

func (x *LintRegistry) WithLints(v []*LintDescriptor) *LintRegistry

WithLints returns a copy of LintRegistry with Lints set to the given value.

type LintRegistryError 

type LintRegistryError struct {
	Message string
}

LintRegistryError reports a registry document that failed strictspec validation: the lint registry is malformed, so selfdoc cannot know what its own lints are.

func (*LintRegistryError) Error 

func (e *LintRegistryError) Error() string

type LintResult 

type LintResult struct {
	// contains filtered or unexported fields
}

LintResult is a single lint diagnostic.

Its severity is not a construction argument: it is read from the registry for the named lint. That is what keeps severities out of the construction sites scattered across the check modules, and what makes an unregistered lint impossible to emit. Every field is read-only through an accessor, because a diagnostic's severity is the registry's answer for its lint and nothing downstream may rewrite it after the fact.

func MustLintResult 

func MustLintResult(file string, line *int, name, message string) LintResult

MustLintResult is NewLintResult for a call site whose lint name is a literal declared in the registry document, and panics when it is not.

The panic is the point: an unregistered literal is a defect in this repository rather than a condition a run can encounter, and the alternative -- an error return threaded through every emission site -- would make the emission sites decide what to do about a lint that cannot exist.

func NewLintResult 

func NewLintResult(file string, line *int, name, message string) (LintResult, error)

NewLintResult builds a diagnostic of the named lint, deriving its severity from the registry.

line is nil for a diagnostic that belongs to a file rather than to one of its lines. An unregistered name is an UnknownLintNameError.

func (LintResult) File 

func (l LintResult) File() string

File returns the diagnostic's path, relative to the docs directory.

func (LintResult) Line 

func (l LintResult) Line() *int

Line returns the 1-based line the diagnostic sits on, or nil when it belongs to the file as a whole.

func (LintResult) Message 

func (l LintResult) Message() string

Message returns the diagnostic's human-readable message.

func (LintResult) Name added in v0.46.0 

func (l LintResult) Name() string

Name returns the name of the registered lint the diagnostic reports.

func (LintResult) Severity 

func (l LintResult) Severity() string

Severity returns the registry's severity for this diagnostic's lint.

type LintSpec 

type LintSpec struct {
	Name        string
	Severity    string // "error" or "warning"
	Description string
}

LintSpec is the registry entry for a single lint.

type LintTableRow 

type LintTableRow struct {
	Name        string
	Severity    string
	Description string
}

LintTableRow is one row of the rendered lint-rule table.

func LintTableRows 

func LintTableRows() []LintTableRow

LintTableRows returns a row per registered lint, in registry (documentation) order. The documentation's lint-rule table is rendered from this and nothing else.

type OptionsError added in v0.46.0 

type OptionsError struct {
	Message string
}

OptionsError is a repository whose option entries cannot be read: a subject document of the wrong shape, or a selfdoc entry strictspec refuses. The message carries strictspec's catalogued diagnostics, each naming its file.

func (*OptionsError) Error added in v0.46.0 

func (e *OptionsError) Error() string

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry is a loaded, validated lint registry.

It keeps the document's order, which is documentation order: the lint-rule table renders in it, grouping the families rather than sorting the names alphabetically.

func BuildRegistry 

func BuildRegistry(raw []byte) (*Registry, error)

BuildRegistry validates raw registry-document bytes and binds them into a Registry.

strictspec is the boundary validator: the document is checked against its schema by the generated validator, and only a wholly valid document is bound. Any diagnostic is a LintRegistryError.

func Load 

func Load() (*Registry, error)

Load reads, validates and binds the embedded registry document.

This is the error-returning door. Production code reads Registered instead, which loads once.

func Registered 

func Registered() *Registry

Registered returns the shipped lint registry, loading and validating the embedded document on first use.

It panics when the document is malformed, which is the Go counterpart of the Python surface's import-time crash: the document is embedded in the binary, so a diagnostic here means this build of selfdoc does not know what its own lints are. Use Load where an error is wanted.

func (*Registry) Has 

func (r *Registry) Has(name string) bool

Has reports whether the registry carries a lint of that name.

func (*Registry) Len 

func (r *Registry) Len() int

Len returns how many lints the registry carries.

func (*Registry) Names added in v0.46.0 

func (r *Registry) Names() []string

Names returns every registered lint's name in registry (documentation) order.

func (*Registry) Spec 

func (r *Registry) Spec(name string) (LintSpec, bool)

Spec returns the named lint's registry entry, reporting whether the registry carries it.

type Settings added in v0.46.0 

type Settings struct {
	// contains filtered or unexported fields
}

Settings is the value each lint runs at in one repository: the current value of its entry, or its registered severity when the repository has none.

func LoadSettings added in v0.46.0 

func LoadSettings(repoRoot string) (Settings, error)

LoadSettings reads a repository's option entries and returns the value each lint runs at.

Every subject document is shape-validated by strictspec's loader, whichever tool's entries it holds, and a document of the wrong shape is refused. The selfdoc namespace is then judged against selfdoc's registry, and any entry strictspec refuses is refused here with its diagnostic. Another tool's entries are not judged.

func (Settings) Apply added in v0.46.0 

func (s Settings) Apply(results []LintResult) []LintResult

Apply returns the lints a run reports under these settings: a lint whose option is off is dropped, one at warn is reported as a warning, which never blocks, and one at error keeps its registered severity.

It can only lower a diagnostic's severity from the registry's answer: an option ranks no value above the registered severity.

func (Settings) Current added in v0.46.0 

func (s Settings) Current(name string) string

Current returns the value a lint runs at.

type UnknownLintNameError added in v0.46.0 

type UnknownLintNameError struct {
	Message string
}

UnknownLintNameError reports a lint name the registry does not carry.

Every emittable lint is declared in the registry document. An undeclared lint would carry no severity, would be rejected by the JSON output schema, and would be invisible to the documentation table -- so it is refused at the construction site instead.

func (*UnknownLintNameError) Error added in v0.46.0 

func (e *UnknownLintNameError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Command genoptions writes selfdoc's options registry, internal/lints/options.toml, from the lint registry: one option per lint.
 Command genoptions writes selfdoc's options registry, internal/lints/options.toml, from the lint registry: one option per lint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.