feat(reflect): add KindUintptr + TypeFor/NewValue/MakeSlice/MakeMap/CopyValue/MakeFunc + StructField

Phase 2 v0.10.4 gap-fill — genuine reflect gaps consumers reach for that
reflect.go wrapped no equivalent of:

- KindUintptr — missing sibling Kind constant (consumers used reflect.Uintptr 16x)
- StructField type alias — field descriptor from Type.Field
- TypeFor[T] — type-safe replacement for TypeOf((*T)(nil)).Elem() (10 uses)
- NewValue (reflect.New, renamed — core.New is the constructor) — 69 uses
- MakeSlice/MakeMap/MakeMapWithSize — reflective make() (31+7+4 uses)
- CopyValue (reflect.Copy, renamed — core.Copy is io.Copy) — 9 uses
- MakeFunc — runtime func synthesis (4 uses)

Additive only. Good/Bad/Ugly per symbol, runnable godoc examples,
ReportAllocs benchmarks for the allocating constructors.

Deliberately NOT wrapped (subtle/unsafe per AX reflect caution):
reflect.NewAt (unsafe.Pointer arg). reflect.Ptr (deprecated Kind alias,
consumers should use KindPointer = non-compliance). All bare Kind consts
(reflect.Func/Slice/Map/String/Int*/etc.) already wrapped as Kind* =
non-compliance noise, not gaps.

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

reflect.go

@@ -61,9 +61,18 @@ const (
 	KindSlice         = reflect.Slice
 	KindString        = reflect.String
 	KindStruct        = reflect.Struct
+	KindUintptr       = reflect.Uintptr
 	KindUnsafePointer = reflect.UnsafePointer
 )
 
+// StructField is an alias for reflect.StructField — one field's
+// descriptor (Name, Type, Tag, offset) returned by Type.Field during
+// struct introspection.
+//
+//	f := core.TypeOf(opts).Field(0)
+//	tag := f.Tag.Get("json")
+type StructField = reflect.StructField
+
 // TypeOf returns the runtime type of v. Returns nil if v is a nil
 // interface value.
 //
@@ -100,3 +109,68 @@ func DeepEqual(x, y any) bool {
 func Zero(t Type) Value {
 	return reflect.Zero(t)
 }
+
+// TypeFor returns the Type for the compile-time type T. The type-safe
+// replacement for TypeOf((*T)(nil)).Elem() — no nil-pointer dance, no
+// runtime value needed.
+//
+//	t := core.TypeFor[MyStruct]()
+//	if t.Kind() == core.KindStruct { ... }
+func TypeFor[T any]() Type {
+	return reflect.TypeFor[T]()
+}
+
+// NewValue returns a Value representing a pointer to a new zero value
+// of type t — the reflective equivalent of new(T). Named NewValue (not
+// New) because core.New is the framework constructor.
+//
+//	ptr := core.NewValue(core.TypeFor[Config]())  // *Config, zeroed
+//	cfg := ptr.Elem().Interface().(Config)
+func NewValue(t Type) Value {
+	return reflect.New(t)
+}
+
+// MakeSlice returns a Value representing a new slice of element type's
+// slice t with the given length and capacity. t must have Kind Slice;
+// callers control that, so this stays infallible (panics on a non-slice
+// type, matching the stdlib contract).
+//
+//	s := core.MakeSlice(core.TypeFor[[]int](), 0, 8)
+func MakeSlice(t Type, len, cap int) Value {
+	return reflect.MakeSlice(t, len, cap)
+}
+
+// MakeMap returns a Value representing a new empty map of map type t.
+//
+//	m := core.MakeMap(core.TypeFor[map[string]int]())
+func MakeMap(t Type) Value {
+	return reflect.MakeMap(t)
+}
+
+// MakeMapWithSize returns a new empty map of type t pre-sized for about
+// n entries — the reflective make(map, n) hint.
+//
+//	m := core.MakeMapWithSize(core.TypeFor[map[string]int](), 64)
+func MakeMapWithSize(t Type, n int) Value {
+	return reflect.MakeMapWithSize(t, n)
+}
+
+// CopyValue copies the contents of src into dst until dst is full or
+// src is exhausted, returning the number of elements copied. Both must
+// be slices (or dst an array) with assignable element types. Named
+// CopyValue (not Copy) because core.Copy is the io stream copier.
+//
+//	n := core.CopyValue(dstVal, srcVal)
+func CopyValue(dst, src Value) int {
+	return reflect.Copy(dst, src)
+}
+
+// MakeFunc returns a new function Value of type t whose body calls fn
+// with the in-arguments and returns fn's results. Used to synthesise
+// functions (proxies, generic adapters) at runtime — reach for it only
+// when a closure over a concrete signature genuinely cannot.
+//
+//	fn := core.MakeFunc(t, func(args []core.Value) []core.Value { ... })
+func MakeFunc(t Type, fn func(args []Value) (results []Value)) Value {
+	return reflect.MakeFunc(t, fn)
+}

reflect_bench_test.go

@@ -20,6 +20,7 @@ var (
 	reflectSinkValue Value
 	reflectSinkBool  bool
 	reflectSinkKind  Kind
+	reflectSinkInt   int
 )
 
 // Fixtures
@@ -122,3 +123,45 @@ func BenchmarkReflect_Zero_Struct(b *B) {
 		reflectSinkValue = Zero(t)
 	}
 }
+
+// --- TypeFor / NewValue / MakeSlice / MakeMap / CopyValue ---
+
+func BenchmarkReflect_TypeFor_Struct(b *B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		reflectSinkType = TypeFor[reflectStruct]()
+	}
+}
+
+func BenchmarkReflect_NewValue_Struct(b *B) {
+	t := TypeFor[reflectStruct]()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		reflectSinkValue = NewValue(t)
+	}
+}
+
+func BenchmarkReflect_MakeSlice_Int(b *B) {
+	t := TypeFor[[]int]()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		reflectSinkValue = MakeSlice(t, 0, 8)
+	}
+}
+
+func BenchmarkReflect_MakeMap_StringInt(b *B) {
+	t := TypeFor[map[string]int]()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		reflectSinkValue = MakeMap(t)
+	}
+}
+
+func BenchmarkReflect_CopyValue_Int(b *B) {
+	src := ValueOf(reflectFixSlice)
+	dst := MakeSlice(TypeFor[[]int](), len(reflectFixSlice), len(reflectFixSlice))
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		reflectSinkInt = CopyValue(dst, src)
+	}
+}

reflect_example_test.go

@@ -34,3 +34,20 @@ func ExampleKind() {
 	Println(k == KindString)
 	// Output: true
 }
+
+// ExampleTypeFor names a type at compile time through `TypeFor`, with no
+// nil-pointer dance. Reflection stays behind a narrow core surface for
+// rare inspection code.
+func ExampleTypeFor() {
+	Println(TypeFor[string]().Kind())
+	// Output: string
+}
+
+// ExampleNewValue allocates a zeroed value of a reflected type through
+// `NewValue` — the reflective new(T).
+func ExampleNewValue() {
+	ptr := NewValue(TypeFor[int]())
+	ptr.Elem().SetInt(7)
+	Println(ptr.Elem().Int())
+	// Output: 7
+}

reflect_test.go

@@ -62,3 +62,160 @@ func TestReflect_Zero_Ugly(t *T) {
 	AssertEqual(t, KindPointer, z.Kind())
 	AssertTrue(t, z.IsNil())
 }
+
+func TestReflect_KindUintptr_Good(t *T) {
+	var p uintptr
+	AssertEqual(t, KindUintptr, TypeOf(p).Kind())
+}
+
+func TestReflect_KindUintptr_Bad(t *T) {
+	AssertNotEqual(t, KindUintptr, TypeOf(42).Kind())
+}
+
+func TestReflect_KindUintptr_Ugly(t *T) {
+	// UnsafePointer is a distinct kind, not Uintptr.
+	AssertNotEqual(t, KindUintptr, KindUnsafePointer)
+}
+
+type reflectTagged struct {
+	Name string `json:"name"`
+}
+
+func TestReflect_StructField_Good(t *T) {
+	var f StructField = TypeFor[reflectTagged]().Field(0)
+	AssertEqual(t, "Name", f.Name)
+	AssertEqual(t, "name", f.Tag.Get("json"))
+}
+
+func TestReflect_StructField_Bad(t *T) {
+	// Indexing past the field count panics.
+	AssertPanics(t, func() { _ = TypeFor[reflectTagged]().Field(5) })
+}
+
+func TestReflect_StructField_Ugly(t *T) {
+	AssertEqual(t, KindString, TypeFor[reflectTagged]().Field(0).Type.Kind())
+}
+
+func TestReflect_TypeFor_Good(t *T) {
+	AssertEqual(t, KindString, TypeFor[string]().Kind())
+}
+
+func TestReflect_TypeFor_Bad(t *T) {
+	AssertNotEqual(t, TypeFor[int](), TypeFor[string]())
+}
+
+func TestReflect_TypeFor_Ugly(t *T) {
+	// TypeFor[any] yields a nil-interface element type.
+	AssertEqual(t, KindInterface, TypeFor[any]().Kind())
+}
+
+func TestReflect_NewValue_Good(t *T) {
+	ptr := NewValue(TypeFor[int]())
+	AssertEqual(t, KindPointer, ptr.Kind())
+	AssertEqual(t, int64(0), ptr.Elem().Int())
+}
+
+func TestReflect_NewValue_Bad(t *T) {
+	AssertPanics(t, func() { _ = NewValue(nil) })
+}
+
+func TestReflect_NewValue_Ugly(t *T) {
+	// The new value is addressable and settable through its pointer.
+	ptr := NewValue(TypeFor[int]())
+	ptr.Elem().SetInt(7)
+	AssertEqual(t, int64(7), ptr.Elem().Int())
+}
+
+func TestReflect_MakeSlice_Good(t *T) {
+	s := MakeSlice(TypeFor[[]int](), 0, 4)
+	AssertEqual(t, 0, s.Len())
+	AssertEqual(t, 4, s.Cap())
+}
+
+func TestReflect_MakeSlice_Bad(t *T) {
+	// A non-slice type panics.
+	AssertPanics(t, func() { _ = MakeSlice(TypeFor[int](), 0, 0) })
+}
+
+func TestReflect_MakeSlice_Ugly(t *T) {
+	s := MakeSlice(TypeFor[[]int](), 2, 2)
+	AssertEqual(t, 2, s.Len())
+	AssertEqual(t, int64(0), s.Index(0).Int())
+}
+
+func TestReflect_MakeMap_Good(t *T) {
+	m := MakeMap(TypeFor[map[string]int]())
+	AssertEqual(t, KindMap, m.Kind())
+	AssertEqual(t, 0, m.Len())
+}
+
+func TestReflect_MakeMap_Bad(t *T) {
+	AssertPanics(t, func() { _ = MakeMap(TypeFor[int]()) })
+}
+
+func TestReflect_MakeMap_Ugly(t *T) {
+	m := MakeMap(TypeFor[map[string]int]())
+	m.SetMapIndex(ValueOf("k"), ValueOf(9))
+	AssertEqual(t, 1, m.Len())
+}
+
+func TestReflect_MakeMapWithSize_Good(t *T) {
+	m := MakeMapWithSize(TypeFor[map[string]int](), 16)
+	AssertEqual(t, 0, m.Len())
+}
+
+func TestReflect_MakeMapWithSize_Bad(t *T) {
+	AssertPanics(t, func() { _ = MakeMapWithSize(TypeFor[int](), 4) })
+}
+
+func TestReflect_MakeMapWithSize_Ugly(t *T) {
+	// A zero size hint is valid; the map is still usable.
+	m := MakeMapWithSize(TypeFor[map[string]int](), 0)
+	m.SetMapIndex(ValueOf("k"), ValueOf(1))
+	AssertEqual(t, 1, m.Len())
+}
+
+func TestReflect_CopyValue_Good(t *T) {
+	src := ValueOf([]int{1, 2, 3})
+	dst := MakeSlice(TypeFor[[]int](), 3, 3)
+	n := CopyValue(dst, src)
+	AssertEqual(t, 3, n)
+	AssertEqual(t, int64(2), dst.Index(1).Int())
+}
+
+func TestReflect_CopyValue_Bad(t *T) {
+	// Copying into a zero-length destination copies nothing.
+	src := ValueOf([]int{1, 2, 3})
+	dst := MakeSlice(TypeFor[[]int](), 0, 0)
+	AssertEqual(t, 0, CopyValue(dst, src))
+}
+
+func TestReflect_CopyValue_Ugly(t *T) {
+	// Copy stops at the shorter length (dst here).
+	src := ValueOf([]int{1, 2, 3, 4})
+	dst := MakeSlice(TypeFor[[]int](), 2, 2)
+	AssertEqual(t, 2, CopyValue(dst, src))
+}
+
+func TestReflect_MakeFunc_Good(t *T) {
+	// Synthesise func(int) int that doubles its argument.
+	doubler := MakeFunc(TypeFor[func(int) int](), func(args []Value) []Value {
+		return []Value{ValueOf(int(args[0].Int()) * 2)}
+	})
+	fn := doubler.Interface().(func(int) int)
+	AssertEqual(t, 10, fn(5))
+}
+
+func TestReflect_MakeFunc_Bad(t *T) {
+	// A non-func type panics.
+	AssertPanics(t, func() {
+		_ = MakeFunc(TypeFor[int](), func(args []Value) []Value { return nil })
+	})
+}
+
+func TestReflect_MakeFunc_Ugly(t *T) {
+	// A no-arg, no-result func is valid and callable.
+	noop := MakeFunc(TypeFor[func()](), func(args []Value) []Value { return nil })
+	fn := noop.Interface().(func())
+	AssertNotPanics(t, fn)
+}