Documentation
¶
Overview ¶
Package directive provides inline suppression directives for linting.
This package implements comment-based suppression compatible with:
- tally: # tally ignore=RULE1,RULE2 or # tally global ignore=...
- hadolint: # hadolint ignore=RULE1,RULE2 (migration compatibility)
- buildx: # check=skip=RULE1,RULE2 (Docker buildx compatibility)
Directives can be:
- Next-line: Affects the next non-comment line only
- Global: Affects the entire file
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Directive ¶
type Directive struct {
// Type indicates whether this is a next-line or global directive.
Type DirectiveType
// Rules contains the rule codes to suppress.
// A single-element slice containing "all" means suppress all rules.
Rules []string
// Line is the 0-based line number where the directive appears.
Line int
// AppliesTo is the range of lines affected by this directive.
AppliesTo LineRange
// Used is set to true when this directive suppresses at least one violation.
// Used for unused directive detection.
Used bool
// RawText is the original comment text (for error messages).
RawText string
// Source indicates which format the directive used.
Source DirectiveSource
// Reason is an optional explanation for why the rule is being suppressed.
// Extracted from `reason=...` in the directive comment.
Reason string
}
Directive represents a parsed inline suppression directive.
func (*Directive) SuppressesLine ¶
SuppressesLine returns true if this directive suppresses violations on the given line. Line is 0-based.
func (*Directive) SuppressesRule ¶
SuppressesRule returns true if this directive suppresses the given rule code. Supports both namespaced (tally/max-lines) and non-namespaced (max-lines) forms.
type DirectiveSource ¶
type DirectiveSource string
DirectiveSource identifies which syntax format was used.
const ( // SourceTally indicates # tally ignore=... syntax. SourceTally DirectiveSource = "tally" // SourceHadolint indicates # hadolint ignore=... syntax. SourceHadolint DirectiveSource = "hadolint" // SourceBuildx indicates # check=skip=... syntax. SourceBuildx DirectiveSource = "buildx" )
type DirectiveType ¶
type DirectiveType int
DirectiveType indicates the scope of a directive.
const ( // TypeNextLine affects only the next non-comment line. TypeNextLine DirectiveType = iota // TypeGlobal affects the entire file. TypeGlobal )
func (DirectiveType) String ¶
func (t DirectiveType) String() string
String returns a human-readable name for the directive type.
type FilterResult ¶
type FilterResult struct {
// Violations that were not suppressed.
Violations []rules.Violation
// Suppressed violations that were filtered out.
Suppressed []rules.Violation
// UnusedDirectives that did not suppress any violations.
UnusedDirectives []Directive
}
FilterResult contains the results of filtering violations through directives.
func Filter ¶
func Filter(violations []rules.Violation, directives []Directive) *FilterResult
Filter applies directives to filter violations. Violations are suppressed if a directive matches both:
- The violation's rule code (or "all")
- The violation's line number
Line number conversion: Violations use 1-based lines; directives use 0-based. We convert violation lines to 0-based for comparison.
Matching precedence: Uses first-match-wins semantics. When multiple directives could suppress the same violation (e.g., a global and a next-line directive), only the first matching directive is marked as Used. This keeps suppression deterministic but may cause subsequent matching directives to appear unused.
type InstructionSpan ¶ added in v0.17.0
InstructionSpan represents the (inclusive) span of a single Dockerfile instruction. Line numbers are 0-based to match SourceMap conventions.
type InstructionSpanIndex ¶ added in v0.17.0
type InstructionSpanIndex struct {
Spans []InstructionSpan // Sorted by StartLine ascending.
}
InstructionSpanIndex enables efficient lookup of the next instruction span after a given line.
func NewInstructionSpanIndexFromAST ¶ added in v0.17.0
func NewInstructionSpanIndexFromAST(ast *parser.Result, sm *sourcemap.SourceMap) *InstructionSpanIndex
NewInstructionSpanIndexFromAST builds an index from a BuildKit parser result.
func NewInstructionSpanIndexFromSource ¶ added in v0.17.0
func NewInstructionSpanIndexFromSource(source []byte, sm *sourcemap.SourceMap) *InstructionSpanIndex
NewInstructionSpanIndexFromSource parses the Dockerfile source and builds a span index. Returns nil if parsing fails.
type LineRange ¶
type LineRange struct {
// Start is the 0-based line number (inclusive).
Start int
// End is the 0-based line number (inclusive).
// For global directives, this is math.MaxInt.
End int
}
LineRange represents a range of lines affected by a directive. Line numbers are 0-based to match SourceMap conventions.
func GlobalRange ¶
func GlobalRange() LineRange
GlobalRange returns a LineRange that covers the entire file.
type ParseError ¶
type ParseError struct {
// Line is the 0-based line number where the error occurred.
Line int
// Message describes what went wrong.
Message string
// RawText is the original comment text.
RawText string
}
ParseError represents an error parsing a directive.
type ParseResult ¶
type ParseResult struct {
// Directives contains successfully parsed ignore directives.
Directives []Directive
// ShellDirectives contains shell override directives.
ShellDirectives []ShellDirective
// Errors contains parse errors for malformed directives.
Errors []ParseError
}
ParseResult contains all directives parsed from a file plus any errors.
func Parse ¶
func Parse(sm *sourcemap.SourceMap, validator RuleValidator, spanIndex *InstructionSpanIndex) *ParseResult
Parse extracts all inline directives from a SourceMap. If validator is non-nil, unknown rule codes generate parse errors.
type RuleValidator ¶
RuleValidator is a function that checks if a rule code is known. Returns true if the rule exists in the registry.
type ShellDirective ¶
type ShellDirective struct {
// Shell is the shell name (e.g., "bash", "sh", "dash", "ash", "zsh").
Shell string
// Line is the 0-based line number where the directive appears.
Line int
// Source indicates which format the directive used.
Source DirectiveSource
// RawText is the original comment text.
RawText string
}
ShellDirective represents a shell override directive. Supported formats:
- # tally shell=bash
- # hadolint shell=dash
Source Files