rules

type AsyncRule interface {
	Rule
	PlanAsync(input LintInput) []async.CheckRequest
}

type BuildContext interface {
	// IsIgnored checks if a path would be ignored by .dockerignore.
	IsIgnored(path string) (bool, error)

	// FileExists checks if a file exists in the build context.
	FileExists(path string) bool

	// ReadFile reads a regular file from the build context.
	// The path must be relative to the context root.
	ReadFile(path string) ([]byte, error)

	// IsHeredocFile checks if a path is a virtual heredoc file.
	IsHeredocFile(path string) bool

	// HasIgnoreFile returns true if a .dockerignore file exists.
	HasIgnoreFile() bool

	// HasIgnoreExclusions returns true if .dockerignore contains negated patterns.
	// When exclusions exist, static copy-source validation is unreliable.
	HasIgnoreExclusions() bool
}

type ConfigurableRule interface {
	Rule

	// Schema returns the JSON Schema for this rule's configuration options.
	// This follows ESLint's meta.schema pattern where rules define their own schema.
	// The schema is used for:
	//   - Config validation
	//   - Documentation generation
	//   - IDE autocompletion
	//
	// Example return value:
	//
	//	map[string]any{
	//	    "type": "object",
	//	    "properties": map[string]any{
	//	        "max": map[string]any{"type": "integer", "minimum": 0, "default": 50},
	//	    },
	//	    "additionalProperties": false,
	//	}
	Schema() map[string]any

	// DefaultConfig returns the default configuration for this rule.
	// Used when no user config is provided.
	DefaultConfig() any

	// ValidateConfig checks if a configuration is valid for this rule.
	ValidateConfig(config any) error
}

type EpilogueOrderResolveData struct {
	// StageIndex is the 0-based index of the stage that triggered the violation.
	StageIndex int
}

type FixSafety int

type GitRunContext struct {
	Script  string
	Workdir string
	Variant shell.Variant
}

type HeredocFixType int

type HeredocResolveData struct {
	// Type indicates whether this is for consecutive RUNs or chained commands.
	Type HeredocFixType

	// StageIndex is the 0-based index of the stage containing the RUN(s).
	StageIndex int

	// ShellVariant is the shell variant for parsing.
	ShellVariant shell.Variant

	// MinCommands is the minimum number of commands to trigger heredoc conversion.
	MinCommands int

	// PipefailEnabled indicates whether DL4006 (pipefail) is enabled.
	// When true, the heredoc formatter will add "set -o pipefail" inside the
	// heredoc body if any command contains a pipe, avoiding the need for a
	// separate SHELL instruction.
	PipefailEnabled bool
}

type LintInput struct {
	// File is the path to the Dockerfile being linted.
	File string

	// AST is the parsed Dockerfile AST from BuildKit (guaranteed non-nil).
	// Use AST nodes for line information, not raw source counting.
	AST *parser.Result

	// Stages contains the parsed build stages with typed instructions.
	// This is populated by BuildKit's instructions.Parse().
	Stages []instructions.Stage

	// MetaArgs contains ARG instructions that appear before the first FROM.
	// These are global build arguments that affect base image selection.
	MetaArgs []instructions.ArgCommand

	// Source is the raw source content of the Dockerfile.
	// Used for snippet extraction and directive parsing.
	Source []byte

	// Context is optional build context for context-aware rules.
	// Rules should check for nil before using.
	Context BuildContext

	// Semantic is the semantic model for cross-instruction analysis.
	// Provides stage resolution, variable scoping, and COPY --from validation.
	// The lint pipeline and testutil.MakeLintInput populate this for rule execution.
	Semantic *semantic.Model

	// Facts contains cached, derived facts shared across rules for this file.
	// The lint pipeline and testutil.MakeLintInput populate this for rule execution.
	Facts *facts.FileFacts

	// Config is the rule-specific configuration (type depends on rule).
	Config any

	// EnabledRules contains the codes of all rules that are enabled in this run.
	// Rules can check this to coordinate behavior, e.g., DL3003 can skip its fix
	// if prefer-run-heredoc is enabled and would handle the command better.
	// May be nil if not computed (for backward compatibility in tests).
	EnabledRules []string

	// HeredocMinCommands is the configured min-commands for the prefer-run-heredoc rule.
	// Rules that coordinate with heredoc (like DL3003) should use this value.
	// Zero means use the default (HeredocDefaultMinCommands).
	HeredocMinCommands int
}

type Location struct {
	// File is the path to the source file (not in parser.Range).
	File string `json:"file"`
	// Start is the starting position (inclusive, 1-based line numbers).
	Start Position `json:"start"`
	// End is the ending position (exclusive, LSP semantics).
	// Points to the first position after the range.
	// A point location has End.Line < 0 (unset) or End equals Start.
	End Position `json:"end"`
}

type NewlineResolveData struct {
	Mode string
}

type Position struct {
	// Line is the 1-based line number (first line is 1, same as BuildKit).
	Line int `json:"line"`
	// Column is the 0-based column number (same as BuildKit's Character field).
	Column int `json:"column"`
}

type PostFixRevalidator interface {
	Rule

	// RevalidateAfterFix returns true if the violation still holds
	// given the modified file content after fixes were applied.
	// The config parameter is the rule-specific configuration.
	RevalidateAfterFix(violation Violation, modifiedContent []byte, config any) bool
}

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

type Rule interface {
	// Metadata returns static information about the rule.
	Metadata() RuleMetadata

	// Check runs the rule against the given input and returns any violations.
	// The AST and Source fields are guaranteed non-nil. The Context field
	// may be nil in v1.0 (context-aware linting is optional).
	Check(input LintInput) []Violation
}

type RuleMetadata struct {
	// Code is the unique identifier (e.g., "DL3006", "max-lines").
	Code string

	// Name is the human-readable rule name.
	Name string

	// Description explains what the rule checks.
	Description string

	// DocURL links to detailed documentation.
	DocURL string

	// DefaultSeverity is the severity when not overridden.
	DefaultSeverity Severity

	// Category groups related rules (e.g., "security", "performance", "style").
	Category string

	// IsExperimental marks rules that may change or be removed.
	IsExperimental bool

	// FixPriority determines the order in which fixes are applied.
	// Lower values = earlier application (content fixes like DL3027: apt → apt-get).
	// Higher values = later application (structural transforms like prefer-run-heredoc).
	// Default 0 is for content fixes. Use 100+ for structural transformations.
	FixPriority int
}

type Severity int

type SuggestedFix struct {
	// Description explains what this fix does.
	Description string `json:"description"`

	// Edits contains the actual text replacements to apply.
	// May be empty if NeedsResolve is true (populated by resolver).
	Edits []TextEdit `json:"edits,omitempty"`

	// Safety indicates how reliable this fix is.
	// Default (zero value) is FixSafe.
	Safety FixSafety `json:"safety,omitzero"`

	// IsPreferred marks this as the recommended fix when alternatives exist.
	IsPreferred bool `json:"isPreferred,omitzero"`

	// NeedsResolve indicates this fix requires async resolution.
	// When true, Edits is empty and ResolverID specifies which resolver to use.
	// Examples: fetching image digests, computing file checksums.
	NeedsResolve bool `json:"needsResolve,omitzero"`

	// ResolverID identifies which FixResolver should compute the edits.
	// Only used when NeedsResolve is true.
	ResolverID string `json:"resolverId,omitempty"`

	// ResolverData contains opaque data for the resolver.
	// Not serialized to JSON; used internally during fix application.
	ResolverData any `json:"-"`

	// ResolveErr captures resolver failures during fix application.
	// Not serialized to JSON; used internally for diagnostics.
	ResolveErr error `json:"-"`

	// Priority determines application order when multiple fixes exist.
	// Copied from rule's FixPriority. Lower = applied first.
	// Content fixes (priority 0) run before structural transforms (priority 100+).
	Priority int `json:"priority,omitzero"`
}

type TextEdit struct {
	// Location specifies where to apply the edit.
	Location Location `json:"location"`
	// NewText is the text to insert/replace with. Empty string means delete.
	NewText string `json:"newText"`
}

type Violation struct {
	// Location specifies where the violation occurred.
	Location Location `json:"location"`

	// RuleCode is the unique identifier for the rule (e.g., "DL3006", "max-lines").
	RuleCode string `json:"rule"`

	// Message is a human-readable description of the issue.
	Message string `json:"message"`

	// Detail provides additional context (optional).
	Detail string `json:"detail,omitempty"`

	// Severity indicates how critical this violation is.
	Severity Severity `json:"severity"`

	// DocURL links to documentation about this rule (optional).
	DocURL string `json:"docUrl,omitempty"`

	// SourceCode is the source snippet where the violation occurred (optional).
	// Populated by post-processing; rules don't need to set this.
	SourceCode string `json:"sourceCode,omitempty"`

	// SuggestedFix provides a structured fix hint (optional).
	// When SuggestedFixes is populated, this is automatically set to the preferred fix.
	// Supports "auto-fix suggestion" without auto-applying.
	SuggestedFix *SuggestedFix `json:"suggestedFix,omitempty"`

	// SuggestedFixes holds multiple alternative fix options for this violation.
	// Each alternative may have a different description, safety level, and edits.
	// At most one should have IsPreferred=true; that fix is also mirrored in SuggestedFix.
	// Omitted from JSON when there are fewer than two alternatives (the single fix
	// is already available via SuggestedFix).
	SuggestedFixes []*SuggestedFix `json:"suggestedFixes,omitzero"`

	// StageIndex tracks which Dockerfile stage this violation belongs to.
	// Used internally for merging async results; not serialized.
	StageIndex int `json:"-"`
}