lint

type Diagnostic struct {
	File            string
	Line            int
	Column          int
	RuleID          string
	RuleName        string
	Severity        Severity
	Message         string
	SourceLines     []string // context lines around the diagnostic; empty if unavailable
	SourceStartLine int      // 1-based line number of first entry in SourceLines
	// Explanation, when non-nil, attaches per-leaf provenance for the
	// rule that fired. Populated by the CLI when --explain is on.
	Explanation *Explanation
}

type Explanation struct {
	Rule   string
	Leaves []ExplanationLeaf
}

type ExplanationLeaf struct {
	Path   string
	Value  any
	Source string
}

type File struct {
	Path        string
	Source      []byte
	Lines       [][]byte
	AST         ast.Node
	FS          fs.FS
	RootFS      fs.FS
	RootDir     string
	FrontMatter []byte
	LineOffset  int

	// StripFrontMatter records whether this file was parsed in
	// front-matter-stripping mode. Rules that read other files
	// from the corpus should mirror the same mode so that line
	// numbers in cross-file diagnostics are computed against the
	// same coordinate system as the current file.
	StripFrontMatter bool

	// MaxInputBytes is the maximum file size in bytes that rules
	// should enforce when reading secondary files (includes, schemas,
	// cross-references). Zero or negative means unlimited.
	MaxInputBytes int64

	// GitignoreFunc is a lazy factory for the gitignore matcher.
	// It is called at most once (on first access via GetGitignore)
	// and the result is cached. Rules that do not call GetGitignore
	// never trigger matcher construction.
	GitignoreFunc func() *GitignoreMatcher

	// GeneratedRanges records the content line ranges of generated
	// sections (<?include?> / <?catalog?> bodies). Diagnostics whose
	// line falls within these ranges are suppressed when linting the
	// host file — the source file is responsible for those bytes.
	GeneratedRanges []LineRange
	// contains filtered or unexported fields
}

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

type LineRange struct {
	From int
	To   int
}

type ProcessingInstruction struct {
	ast.BaseBlock
	ClosureLine text.Segment
	Name        string // directive name from <?name
}

type ResolveOpts struct {
	// UseGitignore enables filtering of walked directories by .gitignore
	// rules. When true (the default), files matched by .gitignore patterns
	// are skipped during directory walking. Explicitly named file paths are
	// never filtered by gitignore. Defaults to true when the zero value is
	// used (see DefaultResolveOpts).
	UseGitignore *bool

	// FollowSymlinks opts in to following symbolic links that
	// resolve to regular files. The zero value skips all symlinks,
	// which is the secure default.
	//
	// Symlinks that resolve to anything other than a regular file
	// are always skipped, regardless of this flag: directories
	// (filepath.Walk is Lstat-based and does not descend a symlink
	// root) as well as FIFOs, devices, and sockets (reading them
	// during linting could block or fail unexpectedly).
	FollowSymlinks bool
}

type Severity string