Documentation
¶
Overview ¶
Package linter implements the decolint engine: it determines what kind of devcontainer directory a path is (a dev container definition, a Feature, or a Template), locates the configuration files it contains, parses them as HuJSON (JSONC), runs lint rules against the syntax tree, and filters findings suppressed by ignore comments.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConfigFile ¶
ConfigFile is a configuration file detected in a directory.
func FindConfigs ¶
func FindConfigs(dir string) []ConfigFile
FindConfigs determines the kind of devcontainer directory dir is and returns the configuration files it contains:
- a Feature (dir contains devcontainer-feature.json): that file;
- a Template (dir contains devcontainer-template.json): that file, plus the dev container configuration the template ships;
- otherwise, a dev container definition: the configuration files at the locations defined by the devcontainer specification: .devcontainer/devcontainer.json, .devcontainer.json, and .devcontainer/<folder>/devcontainer.json (one level deep).
An empty result means dir contains no devcontainer configuration.
type Context ¶
type Context struct {
// Path is the path of the file being linted.
Path string
// Type is the kind of configuration file being linted.
Type FileType
// Src is the raw content of the file.
Src []byte
// Root is the HuJSON syntax tree parsed from Src. It preserves comments and byte offsets into Src.
Root *hujson.Value
}
Context carries everything a rule needs to inspect a single configuration file.
type FileType ¶
type FileType string
FileType identifies the kind of configuration file being linted.
type Finding ¶
type Finding struct {
// Message describes the problem in a human-readable way.
Message string
// Offset is the byte offset into Context.Src where the problem is located, typically the
// StartOffset of the offending value.
Offset int
}
Finding is a single problem reported by a rule.
type Issue ¶
type Issue struct {
Path string `json:"path"`
Line int `json:"line"` // 1-based
Col int `json:"col"` // 1-based, in bytes
RuleID string `json:"ruleId"`
Message string `json:"message"`
Severity Severity `json:"severity"`
}
Issue is a rule finding resolved to a file position.
type Linter ¶
type Linter struct {
// contains filtered or unexported fields
}
Linter runs a set of rules against devcontainer configuration files.
func (*Linter) Lint ¶
func (l *Linter) Lint(ctx context.Context, path string, src []byte, fileType FileType) ([]Issue, error)
Lint lints src, which is the content of a configuration file of the given type. path is used only for reporting.
func (*Linter) LintDir ¶
LintDir determines the kind of devcontainer directory dir is (a dev container definition, a Feature, or a Template), and lints every configuration file it contains. It is an error if dir is not a directory or contains no configuration.
func (*Linter) RegisterRule ¶
RegisterRule adds r to the linter, to run at the given severity.
type Node ¶
type Node struct {
// Pointer is the JSON Pointer (RFC 6901) of the value, e.g. "/image" or "/mounts/0". It is "" for
// the document root.
Pointer string
// Value is the HuJSON value at Pointer.
Value *hujson.Value
}
Node is a single value reached by the engine's traversal.
type Platform ¶
type Platform int
Platform identifies a target platform a rule is scoped to.
func ParsePlatform ¶
ParsePlatform parses a platform name, matched case-insensitively, into a Platform. It returns an error if name does not name a known platform.
type Rule ¶
type Rule struct {
// ID is the unique identifier of the rule, used in output and in ignore directives (e.g.
// "no-image-latest").
ID string
// Description is a short human-readable description of what the rule checks.
Description string
// FileTypes are the kinds of configuration files this rule applies to. The rule is only run
// against files of these types.
FileTypes []FileType
// Platforms are the target platforms this rule applies to. A nil or empty value means the rule
// applies to every platform and always runs, regardless of which platforms are selected when the
// linter is configured.
Platforms []Platform
// Paths are the JSON Pointer patterns of the values this rule wants to inspect. A "*" segment
// matches any object member name or array index (e.g. "/mounts/*"); the empty string matches the
// document root.
Paths []string
// Check inspects one value matching Paths and returns any findings. It is called at most once per
// rule for a given value, even if several patterns match it. Check must be safe for concurrent
// use, since it may be called for multiple files.
Check func(ctx *Context, node *Node) []Finding
}
Rule is a single lint rule.
A rule declares the kinds of configuration files it applies to via FileTypes and the JSON Pointer paths it is interested in via Paths. The lint engine traverses the HuJSON syntax tree of each matching file exactly once and calls Check for every value matching one of its paths. The syntax tree preserves comments and byte offsets, so findings can point at the exact location of the offending value.
type Severity ¶
type Severity int
Severity indicates how a finding should be treated: whether it's reported as an error or a warning, or not reported at all. It is specified when a rule is registered on a Linter. Severities are ordered from least to most severe, so they can be compared directly (e.g. to rank findings or apply a fail threshold).
func ParseSeverity ¶
ParseSeverity parses a severity name, matched case-insensitively, into a Severity. It returns an error if name does not name a known severity.
func (Severity) MarshalJSONTo ¶
MarshalJSONTo encodes the severity as its name (see String), for use with encoding/json/v2.
Source Files