[must] add must.True assertion

Also:
- Improve documentation
- Better tests

Change-Id: Ibbac5427bbb745ac6822adf1e7dc8d62332c1fca

Author: xobotyi

must/doc.go

@@ -0,0 +1,40 @@
+// Package must provides assertion functions that panic on failure.
+//
+// # When to Use
+//
+// Use must functions when you are certain that operations should not fail
+// and want to eliminate error handling boilerplate in situations where
+// errors indicate programming bugs rather than runtime conditions.
+//
+// Common scenarios:
+//   - Parsing static/hardcoded data (URLs, JSON, regex patterns)
+//   - Operations that should always succeed in your specific context
+//   - Configuration parsing where failure means misconfiguration
+//
+// # When NOT to Use
+//
+// Avoid must functions for:
+//   - User input validation
+//   - Network operations
+//   - File I/O operations
+//   - Any operation that can legitimately fail at runtime
+//
+// # Functions
+//
+//   - must.OK[T](value T, err error) T - returns value if err is nil, panics otherwise
+//   - must.True[T](value T, condition bool) T - returns value if condition is true, panics otherwise
+//   - must.NoErr(err error) - panics if err is not nil
+//
+// # Examples
+//
+//	// Static data parsing
+//	baseURL := must.OK(url.Parse("https://api.example.com"))
+//	pattern := must.OK(regexp.Compile(`^[a-z]+$`))
+//
+//	// Configuration validation
+//	config := must.True(loadConfig(), config.IsValid())
+//
+//	// JSON unmarshaling of known-good data
+//	var data Config
+//	must.NoErr(json.Unmarshal(embeddedConfig, &data))
+package must

must/no-err.go

@@ -4,19 +4,11 @@ import (
 	"dev.gaijin.team/go/golib/e"
 )
 
-// NoErr is a wrapper function to simplify code, in situations where developer is sure
-// that the function being called cannot return an error. E.g.
+// NoErr panics if error is not nil.
 //
-//	err := json.Unmarshal([]byte(`["totally", "valid", "data"]`), &data)
-//	if err != nil {
-//	    panic(err)
-//	}
-//
-// developer doesn't expect error here because the parsed data is static and correct
-//
-//	must.OK(json.Unmarshal([]byte(`["totally", "valid", "data"]`), &data))
+//	must.NoErr(json.Unmarshal(staticJSON, &data))
 func NoErr(err error) {
 	if err != nil {
-		panic(e.NewFrom("NoErr assurance failed", err))
+		panic(e.NewFrom("must.NoErr assertion failed", err))
 	}
 }

must/no-error_test.go

@@ -6,32 +6,25 @@ import (
 
 	"github.com/stretchr/testify/assert"
 
+	"dev.gaijin.team/go/golib/e"
 	"dev.gaijin.team/go/golib/must"
 )
 
 func TestNoErr(t *testing.T) {
 	t.Parallel()
 
 	assert.NotPanics(t, func() {
-		var v []string
+		var data []string
 
-		must.NoErr(json.Unmarshal([]byte(`["foo"]`), &v))
+		must.NoErr(json.Unmarshal([]byte(`["valid", "json"]`), &data))
+		assert.Equal(t, []string{"valid", "json"}, data)
 	})
 
-	assert.Panics(t, func() {
-		var v []string
+	imminentError := func() error { return e.New("imminent error") }
 
-		must.NoErr(json.Unmarshal([]byte(`["foo]`), &v))
+	err := catchPanicError(t, func() {
+		must.NoErr(imminentError())
 	})
 
-	err := catchPanic(t, func() {
-		must.NoErr(errorFn1())
-	})
-
-	assert.ErrorIs(t, err, errTestError)
-	assert.Equal(t, "NoErr assurance failed: test error", err.Error())
-}
-
-func errorFn1() error {
-	return errTestError
+	assert.ErrorContains(t, err, "must.NoErr assertion failed: imminent error")
 }

must/ok.go

@@ -4,20 +4,12 @@ import (
 	"dev.gaijin.team/go/golib/e"
 )
 
-// OK is a wrapper function to simplify code, in situations where developer is sure
-// that the function being called cannot return an error. E.g.
+// OK returns the value if error is nil, otherwise panics.
 //
-//	u, err := url.Parse("example.com")
-//	if err != nil {
-//	    panic(err)
-//	}
-//
-// developer doesn't expect error here because the parsed path is a static and correct
-//
-//	u = must.OK(url.Parse("example.com"))
+//	u := must.OK(url.Parse("https://example.com"))
 func OK[T any](v T, err error) T { //nolint:ireturn
 	if err != nil {
-		panic(e.NewFrom("OK assurance failed", err))
+		panic(e.NewFrom("must.OK assertion failed", err))
 	}
 
 	return v

must/ok_test.go

@@ -1,48 +1,47 @@
 package must_test
 
 import (
-	"errors"
-	"regexp"
+	"net/url"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 
+	"dev.gaijin.team/go/golib/e"
 	"dev.gaijin.team/go/golib/must"
 )
 
 func TestOK(t *testing.T) {
 	t.Parallel()
 
 	assert.NotPanics(t, func() {
-		_ = must.OK(regexp.Compile("[a-z]")) //nolint:gocritic
+		uri := must.OK(url.Parse("https://example.com"))
+		assert.Equal(t, "https://example.com", uri.String())
 	})
 
-	assert.Panics(t, func() {
-		_ = must.OK(regexp.Compile("[a-z")) //nolint:staticcheck,gocritic
-	})
+	imminentError := func() (bool, error) { return false, e.New("imminent error") }
 
-	err := catchPanic(t, func() {
-		_ = must.OK(errorFn())
+	err := catchPanicError(t, func() {
+		_ = must.OK(imminentError())
 	})
 
-	assert.ErrorIs(t, err, errTestError)
-	assert.Equal(t, "OK assurance failed: test error", err.Error())
-}
-
-var errTestError = errors.New("test error")
-
-func errorFn() (bool, error) {
-	return false, errTestError
+	assert.ErrorContains(t, err, "must.OK assertion failed: imminent error")
 }
 
-func catchPanic(t *testing.T, panickingFn func()) (err error) {
+func catchPanicError(t *testing.T, fn func()) (err error) {
 	t.Helper()
 
 	defer func() {
-		err = recover().(error) //nolint:forcetypeassert
+		if rv := recover(); rv != nil {
+			re, ok := rv.(error)
+			if !ok {
+				t.Fatal("recovered panic value is not an error")
+			}
+
+			err = re
+		}
 	}()
 
-	panickingFn()
+	fn()
 
 	return nil
 }

must/true.go

@@ -0,0 +1,16 @@
+package must
+
+import (
+	"dev.gaijin.team/go/golib/e"
+)
+
+// True returns the value if condition is true, otherwise panics.
+//
+//	result := must.True(logger.FromCtx(ctx))
+func True[T any](v T, condition bool) T { //nolint:ireturn
+	if !condition {
+		panic(e.New("must.True assertion failed"))
+	}
+
+	return v
+}

must/true_test.go

@@ -0,0 +1,27 @@
+package must_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"dev.gaijin.team/go/golib/logger"
+	"dev.gaijin.team/go/golib/must"
+)
+
+func TestTrue(t *testing.T) {
+	t.Parallel()
+
+	assert.NotPanics(t, func() {
+		lgr := logger.NewNop()
+
+		result := must.True(logger.FromCtx(logger.ToCtx(t.Context(), lgr)))
+		assert.Equal(t, lgr, result)
+	})
+
+	err := catchPanicError(t, func() {
+		_ = must.True(logger.FromCtx(t.Context()))
+	})
+
+	assert.ErrorContains(t, err, "must.True assertion failed")
+}