builtins

type BuiltinMeta struct {
	Name    string
	NumArgs int
	IsPure  bool

	// GoCodegen holds the Go code generation specification for this builtin.
	// M-CODEGEN-SUSTAINABILITY: When set, the Go codegen can emit this builtin
	// without hardcoded mapping tables. Each builtin registers BOTH its interpreter
	// implementation (in the eval package) and its codegen equivalent (here).
	GoCodegen *GoCodegenSpec
}

type BuiltinMetadata struct {

	// Description is a one-line summary of what the builtin does
	// Example: "Make an HTTP request with custom headers and body"
	Description string

	// LongDesc is a detailed multi-line description (optional)
	// Can include usage notes, caveats, performance characteristics
	LongDesc string

	// Params documents each parameter (optional but recommended)
	Params []ParamDoc

	// Returns documents the return value (optional but recommended)
	// Example: "Result[HttpResponse, NetError] where HttpResponse contains status, headers, and body"
	Returns string

	// Examples provides usage examples (optional)
	// Highly recommended for complex builtins
	Examples []Example

	// SeeAlso lists related builtins (optional)
	// Example: []string{"_net_httpGet", "_net_httpPost"}
	SeeAlso []string

	// Since indicates when the builtin was added (optional)
	// Example: "v0.2.0"
	Since string

	// Deprecated contains a deprecation message if this builtin is being phased out (optional)
	// Should explain what to use instead
	// Example: "Use _net_httpRequest instead, which supports custom headers"
	Deprecated string

	// Stability indicates API stability guarantees (optional, defaults to Stable for old builtins)
	Stability Stability

	// Tags are searchable keywords (optional)
	// Example: []string{"http", "network", "request", "api"}
	Tags []string

	// Category is a high-level grouping (optional)
	// Examples: "network", "string", "math", "io"
	Category string
}

type BuiltinSpec struct {
	// === Core Metadata (v0.3.10 - Required) ===
	Module  string            // Module path (e.g., "std/net", "std/io")
	Name    string            // Builtin name with _ prefix (e.g., "_net_httpRequest")
	NumArgs int               // Number of arguments (for arity checking)
	IsPure  bool              // true = no side effects, false = has effects
	Effect  string            // "" for pure functions, "Net"/"IO"/"FS" for effects
	Type    func() types.Type // Type signature constructor (must return non-nil)
	Impl    EffectImpl        // Implementation function

	// === Enhanced Metadata (v0.3.15+ - Optional) ===
	// All fields in Metadata are optional for backward compatibility.
	// See internal/builtins/metadata.go for field documentation.
	Metadata *BuiltinMetadata // Enhanced documentation and versioning info
}

type EffectImpl func(*effects.EffContext, []eval.Value) (eval.Value, error)

type Example struct {
	Code        string // AILANG code demonstrating the builtin
	Description string // What the example demonstrates
}

type GameClockState struct {
	DeltaTime  float64 // Time since last frame in seconds (e.g., 0.016 for 60fps)
	TotalTime  float64 // Total game time in seconds since start
	FrameCount int     // Current frame number (starts at 0)
}

type GoCodegenSpec struct {
	// Inline is a Go expression template for simple builtins.
	// Use {{arg0}}, {{arg1}}, etc. as placeholders for arguments.
	// Example: "strings.TrimSpace({{arg0}}.(string))"
	// When set, the codegen substitutes arguments and emits the expression inline.
	Inline string

	// Helper defines a runtime helper function for complex builtins.
	// The function is emitted once in runtime.go and called by name.
	// Use this for builtins that need control flow (loops, conditionals).
	Helper *GoHelperSpec

	// Imports lists Go packages needed by Inline or Helper.
	// These are added to the generated file's import block.
	// Example: []string{"strings", "strconv"}
	Imports []string

	// StdlibName is the AILANG stdlib function name that wraps this builtin.
	// Example: "_str_trim" has StdlibName "trim" (from std/string.trim).
	// Used by the codegen to resolve VarGlobal references from stdlib imports.
	StdlibName string

	// RequiresADT specifies which ADT must be registered for this helper to be emitted.
	// Values: "Json", "Option", "Result", or "" (always emit).
	// Helpers with RequiresADT are eagerly emitted when their ADT is registered,
	// ensuring inter-dependent helpers (e.g., GetString depends on JsonGet, IsNone)
	// are always available as a group.
	RequiresADT string
}

type GoHelperSpec struct {
	// FuncName is the Go function name (PascalCase).
	// Example: "Map", "Filter", "Trim"
	FuncName string

	// Signature is the full Go function signature.
	// Example: "func Map(f, xs interface{}) interface{}"
	Signature string

	// Body is the Go function body (without enclosing braces).
	// Example: "return strings.TrimSpace(s.(string))"
	Body string
}

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

type LegacyBuiltinLocation struct {
	FilePath    string   // Path to the file
	Description string   // What used to be there
	Patterns    []string // Code patterns to search for
}

type LegacyLocationReport struct {
	Location      LegacyBuiltinLocation
	FileExists    bool
	FoundBuiltins []string
	Notes         string
}

type MigrationReport struct {
	LegacyLocations      []LegacyLocationReport
	CurrentRegistryCount int
	OrphanedBuiltins     []OrphanedBuiltin
	Warnings             []string
	IsClean              bool
}

type OrphanedBuiltin struct {
	Name     string
	Location string
	Hint     string
}

type ParamDoc struct {
	Name        string // Parameter name (e.g., "url", "method")
	Description string // What the parameter does and any constraints
}

type RegistryStats struct {
	Total    int            // Total builtins registered
	Pure     int            // Pure functions (no side effects)
	Effect   int            // Functions with effects
	ByModule map[string]int // Count by module
	ByEffect map[string]int // Count by effect type
}

type Stability int

type ValidationError struct {
	Builtin  string // Builtin name
	Message  string // Error description
	Fix      string // Suggested fix with example code
	Location string // File where fix should be applied
	Severity string // "error" or "warning"
}