language

type EcosystemUtils interface {
	NormalizeName(name string) string
	CompareVersions(a, b string) (int, error)
}

type Language interface {
	FetchPackageFromRegistry(ctx context.Context, pkg models.PackageInfo) (*RegistryResponse, error)
	ExtractPackageMetadata(ctx context.Context, pkg models.PackageInfo, registryData any) (*models.PackageMetadata, *string, *string, error)
	ExtractVersionHistory(ctx context.Context, pkg models.PackageInfo, registryData any) (*models.VersionMetadata, error)

	// NormalizeName normalizes a package name according to ecosystem-specific rules.
	// For npm: case-sensitive (trim whitespace only)
	// For pypi: PEP 503 normalization (lowercase, [-_.] -> -)
	NormalizeName(name string) string

	// Metadata returns the static metadata for this language ecosystem
	Metadata() *metadata.Metadata

	DependencyFilePatterns() []string

	CompareVersions(a, b string) (int, error)
	ExtractPackageArchive(artifactPath, destDir string) error
	ExtractInstallScriptsFromFiles(files map[string]string) ([]string, error)
}

type RegistryResponse struct {
	// Data is the parsed response from the registry API (e.g., NPMPackageData, PyPIPackageResponse).
	Data any `json:"data,omitempty"`

	// ReleaseData holds release/version history from the full package endpoint.
	// For PyPI with a version query, Data comes from /pypi/{name}/{version}/json
	// while ReleaseData comes from /pypi/{name}/json.
	// Nil when the full endpoint already provides both (npm, pypi without version).
	ReleaseData any `json:"release_data,omitempty"`

	// StatusCode is the HTTP status code from the registry API.
	StatusCode int `json:"status_code"`

	// Headers contains selected HTTP response headers.
	Headers map[string]string `json:"headers,omitempty"`

	// ProjectStatus is the registry's lifecycle status for the project when it exists but is
	// not normally installable — e.g. "quarantined" (frozen by the registry pending a
	// malware/abuse review). Currently only populated for PyPI via the PEP 792 project-status
	// marker; empty for ecosystems that expose no such signal.
	ProjectStatus string `json:"project_status,omitempty"`
}