api

type Aggregate struct {
	// Collect is invoked for each matching node. The rule accumulates
	// state internally via this callback (typically via a closure over
	// fields in its adapter).
	Collect func(ctx *Context)
	// Finalize is invoked after the walk completes for a file. It
	// should report findings via ctx.Emit / ctx.EmitAt.
	Finalize func(ctx *Context)
	// Reset clears any per-file state. Called before Collect for the
	// next file.
	Reset func()
}

type BoolOptionSpec[R any] struct {
	Name        string
	Aliases     []string
	Default     bool
	Description string
	Apply       func(*R, bool)
}

type Capabilities uint32

type ConfigOption struct {
	// Name is the primary YAML key for this option.
	Name string

	// Aliases are alternate YAML keys accepted for back-compat (e.g.
	// "threshold" aliasing allowedLines). Checked in order after Name.
	Aliases []string

	// Type declares how the ConfigSource should read the value.
	Type OptionType

	// Default is the value used when no override is present. Retained
	// for schema generation; the runtime does not re-apply the default
	// (the rule struct literal already carries the default).
	Default interface{}

	// Description is the schema-level documentation for this option.
	Description string

	// Apply is invoked with the target rule and the parsed value when a
	// config override is present. The closure downcasts target to the
	// rule's concrete struct type and assigns the field. For OptRegex
	// the value is *regexp.Regexp (compiled via CompileAnchoredPattern);
	// for all other types the value matches Type's Go representation.
	Apply func(target interface{}, value interface{})
}

type ConfigSource interface {
	// GetInt reads an int override. If the key is not set, def is returned.
	GetInt(ruleSet, rule, key string, def int) int
	// GetBool reads a bool override. If the key is not set, def is returned.
	GetBool(ruleSet, rule, key string, def bool) bool
	// GetString reads a string override. If the key is not set, def is returned.
	GetString(ruleSet, rule, key, def string) string
	// GetStringList reads a []string override. Returns nil when not set.
	GetStringList(ruleSet, rule, key string) []string
	// HasKey reports whether the given key is present in the config.
	HasKey(ruleSet, rule, key string) bool
	// IsRuleActive returns the explicit active override for a rule, or nil when
	// the config does not override. Non-nil true enables a default-inactive rule;
	// non-nil false disables a default-active rule.
	IsRuleActive(ruleSet, rule string) *bool
	// IsRuleSetActive returns the explicit active override for a ruleset, or nil
	// when the config does not override. Non-nil false disables every rule in the
	// set regardless of rule-level overrides.
	IsRuleSetActive(ruleSet string) *bool
}

type Context struct {
	// Always available for per-file rules:
	File *scanner.File
	Node *scanner.FlatNode // nil for line-pass rules
	Idx  uint32            // flat tree index of Node (0 for line-pass rules)

	// Rule is the rule whose Check is currently executing. Populated by
	// the dispatcher before invoking Check so Emit can stamp
	// Rule/RuleSet/Severity/Confidence defaults without the rule body
	// having to know them.
	Rule *Rule

	// DefaultConfidence is the family-level fallback confidence applied
	// to findings emitted through Emit when the rule doesn't set its own
	// Confidence. Set by the dispatcher (0.95 node-dispatch, 0.75 line).
	DefaultConfidence float64

	// Collector receives findings written via Emit/EmitAt in columnar form.
	// Must be set before Check is called.
	Collector *scanner.FindingCollector

	// Populated only when the rule declares NeedsResolver:
	Resolver typeinfer.TypeResolver

	// Populated only when the rule declares NeedsModuleIndex:
	ModuleIndex *module.PerModuleIndex

	// Populated only when the rule declares NeedsCrossFile:
	CodeIndex *scanner.CodeIndex

	// Populated only when the rule declares NeedsParsedFiles:
	ParsedFiles []*scanner.File

	// Populated only when the rule declares NeedsManifest. Now strongly
	// typed: the rule-facing manifest model lives in the leaf
	// internal/manifest package, so v2 can import it without creating a
	// cycle through internal/rules.
	Manifest *manifest.Manifest

	// Populated only when the rule declares NeedsResources:
	ResourceIndex *android.ResourceIndex

	// Populated only when the rule declares AndroidDepIcons:
	IconIndex *android.IconIndex

	// Populated only when the rule declares NeedsGradle:
	GradlePath    string
	GradleContent string
	GradleConfig  *android.BuildConfig

	// Populated for Java source files with cheap source-level facts
	// derived from the parsed Java file. JavaSourceIndex is populated
	// when the dispatcher has a project/source file set; single-file
	// dispatch receives a one-file index.
	JavaFacts       *javafacts.JavaFileFacts
	JavaSourceIndex *javafacts.SourceIndex
	// Populated when at least one enabled Java rule requested optional
	// javac-backed semantic facts and the helper was available.
	JavaSemanticFacts *javafacts.Facts

	// Project-wide library and platform facts derived from Gradle where
	// available. Rules should use this instead of baking library-version
	// assumptions directly into AST heuristics.
	LibraryFacts *librarymodel.Facts

	// Facts is the per-run shared cache of derived per-file facts
	// (imports, references, declaration summaries). Always non-nil for
	// contexts produced by the dispatcher; helpers that build their own
	// mini-contexts may leave it nil — filefacts accessors are nil-safe
	// and recompute without caching in that case.
	Facts *filefacts.Cache
}

type Deprecation struct {
	// Since is the krit version in which this rule was deprecated.
	// Empty string means the deprecation predates version tracking.
	Since string

	// ReplacedBy is the canonical ID of the rule users should migrate
	// to. Empty string means the rule was retired without a direct
	// replacement (the user should remove their suppression entirely).
	ReplacedBy string

	// Reason is a one-line explanation surfaced to users alongside the
	// deprecation. Keep terse — not a full migration guide.
	Reason string
}

type ExpressionFactSink interface {
	SetExpressionFact(filePath string, line, col int, t *typeinfer.ResolvedType)
}

type ExpressionPosition struct {
	Line int
	Col  int
}

type ExpressionPositionSelector func(file *scanner.File) []uint32

type ExpressionTypeResolver interface {
	Resolve(positions map[string][]ExpressionPosition) (map[string]map[ExpressionPosition]*typeinfer.ResolvedType, error)
}

type FakeConfigSource struct {
	// Values stores the configured overrides, keyed as
	// Values[ruleSet][rule][key]. Nil is safe to read from but not
	// safe to write to; use Set to populate.
	Values map[string]map[string]map[string]interface{}

	// RuleActive stores explicit rule-level active overrides.
	// Presence of the key indicates an override; the bool is the
	// override value. Absence means "no override".
	RuleActive map[string]bool

	// RuleSetActive stores explicit ruleset-level active overrides.
	// Same presence semantics as RuleActive.
	RuleSetActive map[string]bool
}

type FakeOption func(*Rule)

type FixLevel int

type IntOptionSpec[R any] struct {
	Name        string
	Aliases     []string
	Default     int
	Description string
	Apply       func(*R, int)
}

type JavaFactProfile struct {
	ReceiverTypesForCallees []string
	ReturnTypesForCallees   []string
	ClassSupertypes         []string
	Annotations             []string
	DeclarationNames        []string
}

type LanguageSupport struct {
	Status   LanguageSupportStatus `json:"status" yaml:"status"`
	Reason   string                `json:"reason,omitempty" yaml:"reason,omitempty"`
	Issue    int                   `json:"issue,omitempty" yaml:"issue,omitempty"`
	Evidence []string              `json:"evidence,omitempty" yaml:"evidence,omitempty"`
	Fixtures []string              `json:"fixtures,omitempty" yaml:"fixtures,omitempty"`
}

type LanguageSupportStatus string

type Maturity uint8

type MetaProvider interface {
	Meta() RuleDescriptor
}

type OptionType int

type OracleCallTargetFilter struct {
	AllCalls bool
	// DiscardedOnly means the rule only needs call targets for calls whose
	// result is used as a standalone statement.
	DiscardedOnly bool
	// TargetFQNs are fully-qualified callable targets the rule may query.
	// The Go bridge derives their simple names for the JVM-side lexical
	// callee filter.
	TargetFQNs []string
	// CalleeNames are lexical callee names the rule may query directly.
	CalleeNames []string
	// LexicalHintsByCallee optionally adds cheap file-level evidence that
	// must be present before the JVM resolves broad call names. Absence keeps
	// name-only behavior for that callee.
	LexicalHintsByCallee map[string][]string
	// LexicalSkipByCallee optionally declares cheap receiver evidence where
	// the Go rule can classify the call structurally and does not need a JVM
	// call target for that site.
	LexicalSkipByCallee map[string][]string
	// AnnotatedIdentifiers asks the bridge to derive CalleeNames from
	// source declarations annotated with these annotation identifiers.
	// This is for rules that call LookupCallTarget only so they can call
	// LookupAnnotations on annotated symbols; it avoids resolving every
	// call expression when the annotated declaration names are knowable
	// from raw source.
	AnnotatedIdentifiers []string
}

type OracleDeclarationProfile struct {
	ClassShell              bool
	Supertypes              bool
	ClassAnnotations        bool
	Members                 bool
	MemberSignatures        bool
	MemberAnnotations       bool
	SourceDependencyClosure bool
}

type OracleFilter struct {
	Identifiers []string
	AllFiles    bool
}

type RegexOptionSpec[R any] struct {
	Name        string
	Aliases     []string
	Default     string
	Description string
	Apply       func(*R, *regexp.Regexp)
}

type Rule struct {
	// Identity
	ID          string
	Category    string
	Description string
	Sev         Severity

	// Aliases are legacy or alternate IDs for this rule. They do NOT
	// appear in the registry as separate rules; they only affect
	// suppression: @Suppress("<alias>") (and inline `// krit:ignore[<alias>]`)
	// silences findings emitted under the canonical ID. Use when
	// renaming a rule so existing user suppressions keep working.
	Aliases []string

	// EnabledByDefaultSince records the krit version in which this rule
	// became default-active (DefaultActive transitioned from false to
	// true). Empty string means the rule has been default-active since
	// inception, or the version was not recorded. Used by docs and
	// release-note generation; the runtime does not key behavior on it.
	EnabledByDefaultSince string

	// Deprecated, when non-nil, marks the rule as scheduled for removal.
	// Consumers (docs, output formatters, CI gates) read this to surface
	// migration guidance. The dispatcher does NOT skip deprecated rules
	// — they continue to fire so existing baselines stay valid until the
	// user migrates.
	Deprecated *Deprecation

	// Dispatch routing.
	//
	// Scope, when set, declares the rule's primary dispatcher bucket
	// directly. When ScopeUnset (the zero value), the dispatcher
	// derives the scope from the bits Needs carries plus the shape of
	// NodeTypes. Aspects (NeedsResolver, NeedsOracle, NeedsConcurrent)
	// remain on Needs and layer on top of any scope.
	Scope     Scope
	NodeTypes []string     // nil + no NeedsLinePass means every AST node; nil + NeedsLinePass means line rule
	Needs     Capabilities // zero → no extra deps

	// LexicalCalleeNames narrows call_expression dispatch to calls whose
	// syntactic callee name matches one of these names. It is intentionally
	// lexical and AST-only; semantic call-target filtering for the Kotlin
	// oracle remains in OracleCallTargets below.
	LexicalCalleeNames []string

	// Languages declares which source languages this rule applies to.
	// When nil the effective default is computed from Needs:
	//   NeedsManifest   → [LangXML]
	//   NeedsResources  → [LangXML]
	//   NeedsGradle     → [LangGradle]
	//   otherwise       → [LangKotlin]
	// The dispatcher uses RuleLanguages() to skip rules whose language
	// list does not include the current file's Language.
	Languages []scanner.Language

	// Maturity is the rule's lifecycle stage. The zero value is
	// MaturityStable. Experimental and deprecated rules are
	// default-inactive; see the Maturity type docs for the full contract.
	Maturity Maturity

	// RunAfter declares rule IDs that must run before this rule within
	// the dispatcher. The dispatcher topologically sorts active rules by
	// these constraints once at construction; rules that name a non-active
	// dependency are unconstrained (the missing dependency is silently
	// ignored). Cycles among active rules are a programmer error and
	// cause NewDispatcher to panic with the offending rule IDs.
	//
	// Use cases:
	//   - A fixable rule whose autofix output another rule reads.
	//   - Two rules emitting findings on the same node where downstream
	//     tooling expects a stable ordering.
	//
	// Most rules do not need RunAfter and should leave it nil.
	RunAfter []string

	// Fix metadata
	Fix FixLevel // FixNone → not fixable

	// Confidence tier (0 = use family default)
	Confidence float64

	// Oracle filtering (nil = conservative AllFiles default)
	Oracle *OracleFilter

	// OracleCallTargets optionally narrows JVM call-target resolution to
	// lexical callees this rule can consume. Broad consumers set
	// AllCalls=true, which disables the optimization for the active rule set.
	OracleCallTargets *OracleCallTargetFilter

	// OracleDeclarationNeeds, when non-nil, declares which declaration
	// fields this rule reads from the JVM oracle. The pipeline unions these
	// across all active rules to compute the --declaration-profile flag
	// passed to krit-types. A nil value means the rule has not opted in to
	// narrowing (conservative: treated as needing all fields for the union).
	// Rules that only use expression-level APIs (LookupCallTarget,
	// LookupExpression) and never touch the declarations map should set
	// &OracleDeclarationProfile{} (empty, no fields needed).
	OracleDeclarationNeeds *OracleDeclarationProfile

	// TypeInfo carries per-rule routing hints for type-information
	// lookups. Zero value (PreferAny, Required=false) is backwards
	// compatible — the dispatcher wires the composite resolver just
	// as it did before the hint existed. See TypeInfoHint.
	TypeInfo TypeInfoHint

	// JavaFacts optionally requests javac-backed facts for Java files.
	// This does not make javac mandatory; unavailable facts are a warning
	// and rules must fall back to source AST/index evidence.
	JavaFacts *JavaFactProfile

	// NeedsLibraryFacts declares that the rule reads Context.LibraryFacts
	// and should receive project-derived library facts instead of the
	// conservative defaults when Gradle metadata is available.
	NeedsLibraryFacts bool

	// Check is the rule's analysis function. It receives a Context
	// populated according to the rule's Needs bitfield. Rules report
	// findings by calling ctx.Emit or ctx.EmitAt.
	Check func(*Context)

	// AndroidDeps carries the AndroidDataDependency bitfield (stored as
	// uint32 to avoid an import cycle with the rules package) for Android
	// project-data rules. Zero means "not an Android data rule".
	AndroidDeps uint32

	// Implementation stores the concrete rule instance captured by this v2
	// registration. Config descriptors apply option overrides to this value,
	// and tests may type-assert it to inspect configured fields.
	//
	// Typed as any because the registry is heterogeneous: every rule has a
	// different concrete struct type, but they all share the same Rule
	// metadata shape. Consumers that need a typed pointer assert through
	// the Implementation field (e.g. r.Implementation.(*MyRule)).
	Implementation any

	// Aggregate carries the collect/finalize/reset lifecycle hooks
	// for rules declared with NeedsAggregate. Non-aggregate rules
	// leave this nil.
	Aggregate *Aggregate

	// ExprPositions optionally returns FlatNode indices whose oracle
	// expression types this rule wants resolved before dispatch runs.
	// Used by the targeted-resolution pre-pass under --depth=thorough:
	// the pipeline walks every file once, accumulates the union of
	// requested positions across rules, sends them to krit-types in a
	// single batched RPC, then injects the resulting types into the
	// oracle's expression map. Rules then query ctx.Resolver normally
	// during dispatch and find the precomputed facts via
	// CompositeResolver.ResolveByNameFlat.
	//
	// Selectors must be cheap (AST-only, no resolver calls) — they are
	// invoked for every file regardless of whether any positions match.
	// Returning nil or an empty slice skips the file. A nil ExprPositions
	// means the rule does not participate in targeted resolution.
	ExprPositions ExpressionPositionSelector

	// DefaultActive reports whether the rule runs by default. Rules with
	// DefaultActive == false are opt-in (must be enabled via config or
	// --all-rules).
	DefaultActive bool

	// Options are the configurable fields the rule exposes via YAML.
	Options []ConfigOption

	// CustomApply is an optional escape hatch for rules whose config cannot
	// be expressed as a list of Options. See RuleDescriptor.CustomApply for
	// the contract.
	CustomApply func(target interface{}, cfg ConfigSource)

	// LanguageSupport records per-source-language support status for a rule.
	// See RuleDescriptor.LanguageSupport.
	LanguageSupport map[string]LanguageSupport
}

type RuleDescriptor struct {
	// ID is the stable rule identifier (matches the rule's Name()).
	ID string

	// Aliases are legacy or alternate IDs honored by suppression. See
	// Rule.Aliases for the full contract; the descriptor field exists so
	// rules implementing MetaProvider can publish aliases the same way
	// they publish other metadata.
	Aliases []string

	// EnabledByDefaultSince mirrors Rule.EnabledByDefaultSince — the
	// krit version in which this rule became default-active. Empty
	// string means inception or unrecorded.
	EnabledByDefaultSince string

	// Deprecated mirrors Rule.Deprecated. Non-nil means the rule is
	// scheduled for removal; consumers should surface migration
	// guidance via ReplacedBy / Reason.
	Deprecated *Deprecation

	// RuleSet is the configuration group this rule belongs to
	// (e.g. "complexity", "naming", "performance").
	RuleSet string

	// Severity is "error", "warning", or "info".
	Severity string

	// Description is the human-readable rule summary.
	Description string

	// DefaultActive reports whether the rule runs by default. Rules with
	// DefaultActive == false are opt-in (must be enabled via config or
	// --all-rules).
	DefaultActive bool

	// FixLevel is "", "cosmetic", "idiomatic", or "semantic".
	// Empty string means the rule does not provide an auto-fix.
	FixLevel string

	// Confidence is the base confidence tier (0 = use family default).
	Confidence float64

	// LanguageSupport records per-source-language support status for a rule.
	// It is product/support metadata rather than dispatcher routing: Languages
	// on Rule controls where a rule runs, while LanguageSupport explains whether
	// that behavior counts as full, partial, pending, or inapplicable support.
	LanguageSupport map[string]LanguageSupport

	// Options are the configurable fields the rule exposes via YAML.
	Options []ConfigOption

	// CustomApply is an optional escape hatch for rules whose config cannot
	// be expressed as a list of Options. It runs AFTER the Options loop, so
	// it can override option-applied fields if needed. Rules that can be
	// fully expressed via Options leave this nil.
	//
	// A common use case is a rule that needs to read the whole config tree
	// (e.g. LayerDependencyViolationRule.LayerConfig) rather than a single
	// scalar key. Such hooks typically assert on a concrete ConfigSource
	// implementation (e.g. the real ConfigAdapter) and no-op on the fake
	// sources used by unit tests.
	CustomApply func(target interface{}, cfg ConfigSource)
}

type Scope int8

type Severity string

type StringListOptionSpec[R any] struct {
	Name        string
	Aliases     []string
	Default     []string
	Description string
	Apply       func(*R, []string)
}

type StringOptionSpec[R any] struct {
	Name        string
	Aliases     []string
	Default     string
	Description string
	Apply       func(*R, string)
}

type TypeInfoBackend uint8

type TypeInfoHint struct {
	// PreferBackend names the backend the rule would rather use when
	// the dispatcher has both wired.
	PreferBackend TypeInfoBackend
	// Required controls what happens when PreferBackend is set but
	// the preferred backend is NOT available:
	//
	//   false (default): skip the rule silently — the rule author
	//     asserts that running against the non-preferred backend
	//     would produce wrong or misleading findings.
	//   true           : fall through to whatever backend IS wired;
	//     the preference was a perf hint, not a correctness lever.
	//
	// PreferAny ignores Required — any wired backend satisfies the
	// rule.
	Required bool
}