github.com/klauspost/cpuid/v2 v2.3.0: cpuid.CPU, cpuid.Detect, cpuid.FeatureID

# klauspost/cpuid/v2 CPU Feature Detection and Query Semantics

## Pinned Release
- `github.com/klauspost/cpuid/v2`: `v2.3.0`

## Observed Behavior and API Contracts

### 1. Command-Line Flag Registration via `cpuid.Flags`
- `cpuid.Flags()` registers CLI flags (`cpu.arm`, `cpu.disable`, and `cpu.features`) into standard `flag.CommandLine`.
- It allows disabling specific CPU features or querying features directly from CLI arguments before execution.

### 2. Global `cpuid.CPU` Singleton Initialization
- `cpuid.CPU` is an exported global `CPUInfo` struct initialized automatically at runtime startup.
- It provides hardware topology and vendor attributes such as `PhysicalCores`, `LogicalCores`, `Family`, `Model`, `Stepping`, `VendorID`, and `VendorString`.
- Core counts are non-negative, and `VendorString` matches the detected `VendorID`.

### 3. Feature Identification and Parsing via `cpuid.FeatureID`
- `cpuid.FeatureID` represents distinct hardware instruction set extensions and features.
- `FeatureID.String()` returns the textual identifier of the feature (e.g. `"CMOV"`, `"AVX2"`).
- `cpuid.ParseFeature` looks up a feature by name, returning `cpuid.UNKNOWN` (`-1`) when given an unrecognized name.

### 4. Hardware Re-detection with `cpuid.Detect`
- Calling `cpuid.Detect()` re-runs hardware CPU feature detection and updates the global `cpuid.CPU` instance.
- This resets any dynamic modifications performed directly on the global `cpuid.CPU` instance via `Enable` or `Disable`.

### 5. Multi-Feature Checks with `Supports` and `AnyOf`
- `cpuid.CPU.Supports(ids ...FeatureID)` verifies conjunction: returns `true` only if all specified features are supported (vacuously `true` when passed zero arguments).
- `cpuid.CPU.AnyOf(ids ...FeatureID)` verifies disjunction: returns `true` if at least one of the specified features is supported (returns `false` when passed zero arguments).

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0
Demonstrate these symbols/APIs:
  - cpuid.CPU
  - cpuid.Detect
  - cpuid.FeatureID
  - cpuid.Flags

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package cpuidcheck

import (
	"flag"
	"testing"

	"github.com/klauspost/cpuid/v2"
)

func TestFlagsRegistration(t *testing.T) {
	// 1. cpuid.Flags registers command line flags for CPU feature inspection and disabling
	cpuid.Flags()
	if flag.Lookup("cpu.disable") == nil {
		t.Fatalf("expected cpu.disable flag to be registered by cpuid.Flags()")
	}
	if flag.Lookup("cpu.features") == nil {
		t.Fatalf("expected cpu.features flag to be registered by cpuid.Flags()")
	}
	if flag.Lookup("cpu.arm") == nil {
		t.Fatalf("expected cpu.arm flag to be registered by cpuid.Flags()")
	}
}

func TestCPUSingletonAndProperties(t *testing.T) {
	// 2. cpuid.CPU global singleton provides CPU vendor and topology details
	if cpuid.CPU.PhysicalCores < 0 || cpuid.CPU.LogicalCores < 0 {
		t.Fatalf("expected non-negative core counts, got physical: %d, logical: %d",
			cpuid.CPU.PhysicalCores, cpuid.CPU.LogicalCores)
	}

	if cpuid.CPU.VendorString == "" && cpuid.CPU.VendorID != cpuid.VendorUnknown {
		t.Fatalf("expected VendorString to match VendorID")
	}
}

func TestFeatureIDAndParsing(t *testing.T) {
	// 3. cpuid.FeatureID string representation and ParseFeature lookup
	featName := cpuid.CMOV.String()
	if featName != "CMOV" {
		t.Fatalf("expected CMOV string representation 'CMOV', got: %s", featName)
	}
	parsedID := cpuid.ParseFeature("CMOV")
	if parsedID != cpuid.CMOV {
		t.Fatalf("expected ParseFeature('CMOV') to return cpuid.CMOV, got: %v", parsedID)
	}
	if cpuid.ParseFeature("NON_EXISTENT_FEATURE_xyz") != cpuid.UNKNOWN {
		t.Fatalf("expected ParseFeature with unknown name to return cpuid.UNKNOWN (-1)")
	}
}

func TestDetectAndMutation(t *testing.T) {
	// 4. cpuid.Detect re-evaluates CPU features and resets mutated global state
	origCPU := cpuid.CPU
	cpuid.CPU.Disable(cpuid.CMOV)
	if cpuid.CPU.Has(cpuid.CMOV) {
		t.Fatalf("expected cpuid.CPU.Has(CMOV) to be false after Disable")
	}

	cpuid.Detect()
	if origCPU.Has(cpuid.CMOV) != cpuid.CPU.Has(cpuid.CMOV) {
		t.Fatalf("expected cpuid.Detect() to restore original detected CMOV state")
	}
}

func TestFeatureQuerySupportsAndAnyOf(t *testing.T) {
	// 5. Supports and AnyOf behavior
	if !cpuid.CPU.Supports() {
		t.Fatalf("cpuid.CPU.Supports() with no arguments must return true")
	}
	if cpuid.CPU.AnyOf() {
		t.Fatalf("cpuid.CPU.AnyOf() with no arguments must return false")
	}

	features := cpuid.CPU.FeatureSet()
	if len(features) > 0 {
		firstID := cpuid.ParseFeature(features[0])
		if firstID != cpuid.UNKNOWN {
			if !cpuid.CPU.Has(firstID) {
				t.Fatalf("expected cpuid.CPU.Has(%s) to be true", features[0])
			}
			if !cpuid.CPU.Supports(firstID) {
				t.Fatalf("expected cpuid.CPU.Supports(%s) to be true", features[0])
			}
			if !cpuid.CPU.AnyOf(firstID) {
				t.Fatalf("expected cpuid.CPU.AnyOf(%s) to be true", features[0])
			}
		}
	}
}

{"case":{"caseId":"case:sha256:988da150faf8aba581b9257d94582304cbd6e9b455b2965bd140355d717d71bb","contract":["cpuid.Flags registers command-line flags including cpu.arm, cpu.disable, and cpu.features for runtime CPU feature configuration.","cpuid.CPU is an exported global CPUInfo struct initialized at startup providing non-negative physical and logical core counts and vendor metadata.","cpuid.FeatureID represents hardware CPU features, providing String representation, ParseFeature lookup, and UNKNOWN for unrecognized strings.","cpuid.Detect re-evaluates hardware CPU features, resetting any dynamically modified flags on the global cpuid.CPU instance.","cpuid.CPU.Supports returns true if all specified feature IDs are supported (vacuously true for zero args), and cpuid.CPU.AnyOf returns true if at least one is supported."],"goal":"verify pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0","kind":"HOW","packages":["pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0"],"schemaVersion":1,"symbols":["cpuid.CPU","cpuid.Detect","cpuid.FeatureID","cpuid.Flags"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","executionContext":"go","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0","symbols":["cpuid.CPU","cpuid.Detect","cpuid.FeatureID","cpuid.Flags"],"verifierAdapter":"golang@1"}

module example.com/cpuidcheck

go 1.26.6

require github.com/klauspost/cpuid/v2 v2.3.0

require golang.org/x/sys v0.41.0 // indirect

github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
github.com/klauspost/cpuid/v2 v2.4.0 h1:S6Hrbc7+ywsr0r+RLapfGBHfyefhCTwEh3A0tV913Dw=
github.com/klauspost/cpuid/v2 v2.4.0/go.mod h1:19jmZ9mjzoF//ddRSUsv0zfBTJWh3QJh9FNxZTMrGxU=
golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/klauspost/cpuid/v2@v2.3.0"
  ],
  "symbols": [
    "cpuid.CPU",
    "cpuid.Detect",
    "cpuid.FeatureID",
    "cpuid.Flags"
  ]
}