skyview/internal/squawk/squawk.go

// Package squawk provides transponder code lookup and interpretation functionality.
//
// This package implements a comprehensive database of transponder (squawk) codes
// used in aviation, providing textual descriptions and categorizations for
// common codes including emergency, operational, and special-purpose codes.
//
// The lookup system supports:
//   - Emergency codes (7500, 7600, 7700)
//   - Standard VFR/IFR operational codes
//   - Military and special operations codes
//   - Regional variations and custom codes
//
// Code categories help with UI presentation and priority handling, with
// emergency codes receiving special visual treatment in the interface.
package squawk

import (
	"fmt"
	"strconv"
)

// CodeType represents the category of a transponder code for UI presentation
type CodeType int

const (
	// Unknown represents codes not in the lookup database
	Unknown CodeType = iota
	// Emergency represents emergency situation codes (7500, 7600, 7700)
	Emergency
	// Standard represents common operational codes (1200, 7000, etc.)
	Standard
	// Military represents military operation codes
	Military
	// Special represents special purpose codes (SAR, firefighting, etc.)
	Special
)

// String returns the string representation of a CodeType
func (ct CodeType) String() string {
	switch ct {
	case Emergency:
		return "Emergency"
	case Standard:
		return "Standard"
	case Military:
		return "Military"
	case Special:
		return "Special"
	default:
		return "Unknown"
	}
}

// CodeInfo contains detailed information about a transponder code
type CodeInfo struct {
	Code        string   `json:"code"`        // The transponder code (e.g., "7700")
	Description string   `json:"description"` // Human-readable description
	Type        CodeType `json:"type"`        // Category of the code
	Region      string   `json:"region"`      // Geographic region (e.g., "Global", "ICAO", "US", "EU")
	Priority    int      `json:"priority"`    // Display priority (higher = more important)
	Notes       string   `json:"notes"`       // Additional context or usage notes
}

// Database contains the transponder code lookup database
type Database struct {
	codes map[string]*CodeInfo // Map of code -> CodeInfo
}

// NewDatabase creates and initializes a new transponder code database
// with comprehensive coverage of common aviation transponder codes
func NewDatabase() *Database {
	db := &Database{
		codes: make(map[string]*CodeInfo),
	}
	
	// Initialize with standard transponder codes
	db.loadStandardCodes()
	
	return db
}

// loadStandardCodes populates the database with standard transponder codes
func (db *Database) loadStandardCodes() {
	codes := []*CodeInfo{
		// Emergency Codes (Highest Priority)
		{
			Code:        "7500",
			Description: "Hijacking/Unlawful Interference",
			Type:        Emergency,
			Region:      "Global",
			Priority:    100,
			Notes:       "Aircraft under unlawful interference or hijacking",
		},
		{
			Code:        "7600",
			Description: "Radio Failure",
			Type:        Emergency,
			Region:      "Global",
			Priority:    95,
			Notes:       "Loss of radio communication capability",
		},
		{
			Code:        "7700",
			Description: "General Emergency",
			Type:        Emergency,
			Region:      "Global",
			Priority:    90,
			Notes:       "General emergency situation requiring immediate attention",
		},
		
		// Standard VFR/IFR Codes
		{
			Code:        "1200",
			Description: "VFR - Visual Flight Rules",
			Type:        Standard,
			Region:      "US/Canada",
			Priority:    10,
			Notes:       "Standard VFR code for uncontrolled airspace in North America",
		},
		{
			Code:        "7000",
			Description: "VFR - Visual Flight Rules",
			Type:        Standard,
			Region:      "ICAO/Europe",
			Priority:    10,
			Notes:       "Standard VFR code for most ICAO regions",
		},
		{
			Code:        "2000",
			Description: "Uncontrolled Airspace",
			Type:        Standard,
			Region:      "Various",
			Priority:    8,
			Notes:       "Used in some regions for uncontrolled airspace operations",
		},
		{
			Code:        "0000",
			Description: "No Transponder/Military",
			Type:        Military,
			Region:      "Global",
			Priority:    5,
			Notes:       "No transponder assigned or military operations",
		},
		{
			Code:        "1000",
			Description: "Mode A/C Not Assigned",
			Type:        Standard,
			Region:      "Global",
			Priority:    5,
			Notes:       "Transponder operating but no specific code assigned",
		},
		
		// Special Purpose Codes
		{
			Code:        "1255",
			Description: "Fire Fighting Aircraft",
			Type:        Special,
			Region:      "US",
			Priority:    25,
			Notes:       "Aircraft engaged in firefighting operations",
		},
		{
			Code:        "1277",
			Description: "Search and Rescue",
			Type:        Special,
			Region:      "US",
			Priority:    30,
			Notes:       "Search and rescue operations",
		},
		{
			Code:        "7777",
			Description: "Military Interceptor",
			Type:        Military,
			Region:      "US",
			Priority:    35,
			Notes:       "Military interceptor aircraft",
		},
		
		// Military Ranges
		{
			Code:        "4000",
			Description: "Military Low Altitude",
			Type:        Military,
			Region:      "US",
			Priority:    15,
			Notes:       "Military operations at low altitude (4000-4777 range)",
		},
		{
			Code:        "0100",
			Description: "Military Operations",
			Type:        Military,
			Region:      "Various",
			Priority:    12,
			Notes:       "Military interceptor operations (0100-0777 range)",
		},
		
		// Additional Common Codes
		{
			Code:        "1201",
			Description: "VFR - High Altitude",
			Type:        Standard,
			Region:      "US",
			Priority:    8,
			Notes:       "VFR operations above 12,500 feet MSL",
		},
		{
			Code:        "4401",
			Description: "Glider Operations",
			Type:        Special,
			Region:      "US",
			Priority:    8,
			Notes:       "Glider and soaring aircraft operations",
		},
		{
			Code:        "1202",
			Description: "VFR - Above 12,500ft",
			Type:        Standard,
			Region:      "US",
			Priority:    8,
			Notes:       "VFR flight above 12,500 feet requiring transponder",
		},
		
		// European Specific
		{
			Code:        "7001",
			Description: "Conspicuity Code A",
			Type:        Standard,
			Region:      "Europe",
			Priority:    10,
			Notes:       "Enhanced visibility in European airspace",
		},
		{
			Code:        "7004",
			Description: "Aerobatic Flight",
			Type:        Special,
			Region:      "Europe",
			Priority:    12,
			Notes:       "Aircraft engaged in aerobatic maneuvers",
		},
		{
			Code:        "7010",
			Description: "GAT in OAT Area",
			Type:        Special,
			Region:      "Europe",
			Priority:    8,
			Notes:       "General Air Traffic operating in Other Air Traffic area",
		},
	}
	
	// Add all codes to the database
	for _, code := range codes {
		db.codes[code.Code] = code
	}
}

// Lookup returns information about a given transponder code
// 
// The method accepts both 4-digit strings and integers, automatically
// formatting them as needed. Returns nil if the code is not found in the database.
//
// Parameters:
//   - code: Transponder code as string (e.g., "7700") or can be called with fmt.Sprintf
//
// Returns:
//   - *CodeInfo: Detailed information about the code, or nil if not found
func (db *Database) Lookup(code string) *CodeInfo {
	if info, exists := db.codes[code]; exists {
		return info
	}
	return nil
}

// LookupInt is a convenience method for looking up codes as integers
//
// Parameters:
//   - code: Transponder code as integer (e.g., 7700)
//
// Returns:
//   - *CodeInfo: Detailed information about the code, or nil if not found
func (db *Database) LookupInt(code int) *CodeInfo {
	codeStr := fmt.Sprintf("%04d", code)
	return db.Lookup(codeStr)
}

// LookupHex is a convenience method for looking up codes from hex strings
//
// Transponder codes are sometimes transmitted in hex format. This method
// converts hex to decimal before lookup.
//
// Parameters:
//   - hexCode: Transponder code as hex string (e.g., "1E14" for 7700)
//
// Returns:
//   - *CodeInfo: Detailed information about the code, or nil if not found or invalid hex
func (db *Database) LookupHex(hexCode string) *CodeInfo {
	// Convert hex to decimal
	if decimal, err := strconv.ParseInt(hexCode, 16, 16); err == nil {
		// Convert decimal to 4-digit octal representation (squawk codes are octal)
		octal := fmt.Sprintf("%04o", decimal)
		return db.Lookup(octal)
	}
	return nil
}

// GetEmergencyCodes returns all emergency codes in the database
//
// Returns:
//   - []*CodeInfo: Slice of all emergency codes, sorted by priority (highest first)
func (db *Database) GetEmergencyCodes() []*CodeInfo {
	var emergencyCodes []*CodeInfo
	
	for _, info := range db.codes {
		if info.Type == Emergency {
			emergencyCodes = append(emergencyCodes, info)
		}
	}
	
	// Sort by priority (highest first)
	for i := 0; i < len(emergencyCodes); i++ {
		for j := i + 1; j < len(emergencyCodes); j++ {
			if emergencyCodes[i].Priority < emergencyCodes[j].Priority {
				emergencyCodes[i], emergencyCodes[j] = emergencyCodes[j], emergencyCodes[i]
			}
		}
	}
	
	return emergencyCodes
}

// IsEmergencyCode returns true if the given code represents an emergency situation
//
// Parameters:
//   - code: Transponder code as string (e.g., "7700")
//
// Returns:
//   - bool: True if the code is an emergency code
func (db *Database) IsEmergencyCode(code string) bool {
	if info := db.Lookup(code); info != nil {
		return info.Type == Emergency
	}
	return false
}

// GetAllCodes returns all codes in the database
//
// Returns:
//   - []*CodeInfo: Slice of all codes in the database
func (db *Database) GetAllCodes() []*CodeInfo {
	codes := make([]*CodeInfo, 0, len(db.codes))
	for _, info := range db.codes {
		codes = append(codes, info)
	}
	return codes
}

// AddCustomCode allows adding custom transponder codes to the database
//
// This is useful for regional codes or organization-specific codes not
// included in the standard database.
//
// Parameters:
//   - info: CodeInfo struct with the custom code information
func (db *Database) AddCustomCode(info *CodeInfo) {
	db.codes[info.Code] = info
}

// FormatSquawkWithDescription returns a formatted string combining code and description
//
// Formats transponder codes for display with appropriate emergency indicators.
// Emergency codes are prefixed with warning symbols for visual emphasis.
//
// Parameters:
//   - code: Transponder code as string (e.g., "7700")
//
// Returns:
//   - string: Formatted string like "7700 (⚠️ EMERGENCY - General)" or "1200 (VFR - Visual Flight Rules)"
func (db *Database) FormatSquawkWithDescription(code string) string {
	info := db.Lookup(code)
	if info == nil {
		return code // Return just the code if no description available
	}
	
	switch info.Type {
	case Emergency:
		return fmt.Sprintf("%s (⚠️ EMERGENCY - %s)", code, info.Description)
	case Special:
		return fmt.Sprintf("%s (🔸 %s)", code, info.Description)
	case Military:
		return fmt.Sprintf("%s (🔰 %s)", code, info.Description)
	default:
		return fmt.Sprintf("%s (%s)", code, info.Description)
	}
}