linter

type Category int

type Context struct {
	// Path is the path of the file being linted, for reporting only: it is spelled however the
	// caller named the file, so a rule must not read anything into its shape. Use [Dir] for the
	// containing directory.
	Path string
	// Type is the kind of configuration file being linted.
	Type FileType
	// Root is the HuJSON syntax tree of the file. It preserves comments and byte offsets into the
	// original source.
	Root *hujson.Value
	// Dir describes the directory containing the file being linted.
	Dir Dir
}

type Dir struct {
	// FS gives read access to the directory's contents, confined to the lint root. It is nil when
	// the caller has no backing filesystem, e.g. an in-memory document.
	FS fs.FS
	// Name is the directory's own name, taken from where the directory actually is rather than from
	// [Context.Path]. It is empty when the caller has no directory to name.
	Name string
}

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

type Example struct {
	// Bad is configuration the rule reports.
	Bad Snippet
	// Good is configuration the rule does not report, typically Bad with the problem fixed.
	Good Snippet
	// Note is Markdown prose shown after Good, for context Bad and Good alone don't convey (e.g. why
	// Good is scoped the way it is). It is optional.
	Note string
}

type ExampleFile struct {
	// Path is the file's path, relative to the directory the example is linted in (e.g.
	// "devcontainer.json" or ".devcontainer/devcontainer.json").
	Path string
	// Content is the file's content.
	Content string
	// Mode is the file's permission bits. The zero value means a regular file at the default mode;
	// set it for a rule that inspects permissions (e.g. whether install.sh is executable).
	Mode fs.FileMode
}

type FileType string

type Finding struct {
	// Message describes the problem in a human-readable way.
	Message string
	// Offset is the byte offset into the original source where the problem is located, typically the
	// StartOffset of the offending value.
	Offset int
}

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"`
}

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

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
	// Arg is the "docker run" flag occurrence the value was reached as, set only on a node the
	// "runArgs" traversal produced (see [Rule.Paths]) and nil on every other node. Value is then the
	// element the flag's value is written in, which is the flag's own element or the one after it.
	Arg *dockerargs.Arg
}

type Platform int

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
	// LongDescription explains why the rule exists: what goes wrong in the configuration it
	// reports, and what to do instead. It is Markdown, and is shown wherever the rule is
	// documented rather than merely named.
	LongDescription string
	// References are URLs to the specification, documentation, or implementation that justify the
	// rule, most authoritative first.
	References []string
	// Category is the [Category] this rule reports; every rule must declare exactly one.
	Category Category
	// FileTypes are the kinds of configuration files this rule applies to.
	FileTypes []FileType
	// Platforms are the target platforms this rule applies to. A nil or empty value means the rule
	// applies to every platform, 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.
	//
	// A devcontainer.json's "runArgs" is traversed as the "docker run" argv it becomes, so its
	// elements are addressed by flag rather than by index: "/runArgs/--volume" matches once per
	// occurrence of that flag, whichever spelling the argv uses, and [Node.Arg] carries the value the
	// occurrence gives it. Nothing else is addressed under it, so a pattern matching there always
	// arrives with [Node.Arg] set. Only a devcontainer.json has a "runArgs" at all: in a Feature or a
	// Template the same pattern matches whatever that name holds, an ordinary member merely spelled
	// like the flag included, with [Node.Arg] nil.
	//
	// A rule reporting a flag's absence cannot be driven by any of that, since a flag that is not
	// there is never matched; it inspects the document root instead.
	Paths []string
	// Example shows the rule firing and not firing on realistic configuration. Tests lint both: Bad
	// must report the rule, Good must not.
	Example Example
	// Check inspects one value matching Paths and returns any findings. It is called once for a given
	// value, even if several patterns match it — except for a "runArgs" element naming several flags,
	// which it is called for once per flag, with [Node.Arg] telling the occurrences apart. Check must
	// be safe for concurrent use, since it may be called for multiple files.
	Check func(ctx *Context, node *Node) []Finding
}

type Severity int

type Snippet struct {
	// Files are the snippet's files. Exactly one must have the path a rule's first FileType is
	// named at (e.g. "devcontainer.json" for [Devcontainer]); that is the file linted, and it is
	// also the one shown first. The rest are context a rule reads from the directory, e.g. a
	// devcontainer-template.json a devcontainer.json's ${templateOption:...} reference is checked
	// against.
	Files []ExampleFile
	// DirName is the directory's own name, for a rule that reads [Dir.Name] (e.g. a Feature's or
	// Template's id must match the directory containing it). It is empty when no rule needs it.
	DirName string
}