Fix/code quality issues

.claude/skills/add-assertion/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: add-assertion
+description: adding a new assertion to the library
+---
+
 # Adding a New Assertion
 
 Step-by-step workflow for adding a new assertion function to testify.

.claude/skills/codegen/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: regenerate-code-and-doc
+description: How to regenerate code and documentation after a maintenance that changes the API
+---
+
 # Code Generation
 
 How the testify code and documentation generator works.

.claude/skills/doc-site/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: documentation-site
+description: How to run and test the hugo doc site locally
+---
+
 # Documentation Site
 
 Hugo-based documentation site for testify, auto-generated from source code.

.claude/skills/testing-generic-functions/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: writing-test-for-generics
+description: How to write tests that cover both generic and reflection-based assertions
+---
+
 # Testing Generic Functions with Table-Driven Tests
 
 ## The Challenge

codegen/internal/generator/doc_generator.go

@@ -143,7 +143,8 @@ func (d *DocGenerator) reorganizeByDomain() (iter.Seq2[string, model.Document],
 				}
 				weight++
 
-				// populate document context in all children
+				// populate document context in all children: at doc generation time,
+				// we need the full context to be available when iterating over functions.
 				doc.Package.Context = &doc
 				for i, fn := range doc.Package.Functions {
 					fn.Context = &doc

codegen/internal/generator/domains/domains.go

@@ -4,6 +4,7 @@
 package domains
 
 import (
+	"fmt"
 	"iter"
 	"path"
 	"slices"
@@ -15,25 +16,30 @@ import (
 const (
 	nodomain   = "common"
 	assertions = "assertions"
+	maxDepth   = 10
 )
 
 // FlattenDocumentation flattens a nested documentation structure into a map of packages.
 func FlattenDocumentation(documentation model.Documentation) map[string]model.Document {
 	index := make(map[string]model.Document, len(documentation.Documents))
 
-	flattenDocuments(index, documentation.Documents)
+	flattenDocuments(index, documentation.Documents, 0)
 
 	return index
 }
 
-func flattenDocuments(index map[string]model.Document, docs []model.Document) {
+func flattenDocuments(index map[string]model.Document, docs []model.Document, depth int) {
+	if depth > maxDepth {
+		panic(fmt.Errorf("dev error: there is no sensible reason why we should recurse more than %d here", maxDepth))
+	}
+
 	for _, doc := range docs {
 		key := doc.Package.Package
 		if _, ok := index[key]; !ok {
 			index[key] = doc
 		}
 
-		flattenDocuments(index, doc.Documents)
+		flattenDocuments(index, doc.Documents, depth+1)
 	}
 }
 

codegen/internal/generator/funcmaps/funcmaps.go

@@ -283,7 +283,8 @@ func relocate(values []model.TestValue, pkg string) string {
 		return strings.Join(parts, ", ")
 	}
 
-	// Relocate each value
+	// Relocate each value: the original "assertions" package moves to the
+	// target package where the value is generated.
 	relocated := make([]string, 0, len(values))
 	for _, tv := range values {
 		// If parse failed, use original (fallback)

codegen/internal/generator/funcmaps/markdown.go

@@ -58,7 +58,8 @@ func markdownLinks(in string) (string, []string) {
 	// Pattern: [text]: url (at start of line or after whitespace)
 	refLinks := make(map[string]string)
 
-	// Extract all reference links
+	// Extract all reference links: godoc-style links need to be reworked as proper markdown.
+	// We extract the detected links (regexp match) before further reprocessing (below).
 	matches := refLinkPattern.FindAllStringSubmatch(in, -1)
 	const expectedGroups = 2
 	for _, match := range matches {
@@ -70,7 +71,7 @@ func markdownLinks(in string) (string, []string) {
 	// Remove reference link definitions from input
 	processed := refLinkPattern.ReplaceAllString(in, "")
 
-	// Convert reference-style links to inline links
+	// Convert reference-style links to inline links.
 	// Replace [text] with [text](url) where we have the reference
 	usedRefs := make(map[string]bool)
 	for refText, refURL := range refLinks {

codegen/internal/scanner/comments-parser/examples.go

@@ -72,7 +72,12 @@ func ParseTestExamples(text string) []model.Test {
 			continue
 		}
 
-		// skip until we find the Examples section
+		// skip until we find the Examples section.
+		//
+		// This assumes that the godoc comment is organized in sections ("# {section}"):
+		// we'll start processing only when we find an "# Example[s]" section.
+		//
+		// In this section, we expect to find example values that fit the documented assertion (both success and fail).
 		if !inExamplesSection {
 			continue
 		}

codegen/internal/scanner/comments-parser/expressions.go

@@ -46,7 +46,11 @@ func ParseTestValues(input string) []model.TestValue {
 		}}
 	}
 
-	// Extract elements from the composite literal
+	// Extract elements from the composite literal.
+	// The godoc comment contains testable values as legit go literals.
+	//
+	// We parse this snippet and produce a documented version of it [model.TestValue]
+	// for proper rendering (either as code or as documentation).
 	compositeLit, ok := expr.(*ast.CompositeLit)
 	if !ok {
 		// Should never happen if parser succeeded
@@ -58,29 +62,11 @@ func ParseTestValues(input string) []model.TestValue {
 	}
 
 	// Convert each element to TestValue
-	result := make([]model.TestValue, 0, len(compositeLit.Elts))
 
 	// We need to extract the original source text for each element
 	// Since we don't have position info for the original input, we'll format the AST
 	fset := token.NewFileSet()
-	for _, elt := range compositeLit.Elts {
-		// Format the expression back to source code
-		var buf strings.Builder
-		if err := format.Node(&buf, fset, elt); err != nil {
-			result = append(result, model.TestValue{
-				Raw:   "<formatting error>",
-				Expr:  elt,
-				Error: fmt.Errorf("failed to format expression: %w", err),
-			})
-			continue
-		}
-
-		result = append(result, model.TestValue{
-			Raw:   buf.String(),
-			Expr:  elt,
-			Error: nil,
-		})
-	}
+	result := formatLiteralExpression(compositeLit, fset)
 
 	return result
 }
@@ -120,6 +106,16 @@ func ParseExprWithFileSet(fset *token.FileSet, filename string, input string) ([
 	}
 
 	// Convert each element to TestValue
+	result := formatLiteralExpression(compositeLit, fset)
+
+	return result, nil
+}
+
+func formatLiteralExpression(compositeLit *ast.CompositeLit, fset *token.FileSet) []model.TestValue {
+	if compositeLit == nil {
+		return nil
+	}
+
 	result := make([]model.TestValue, 0, len(compositeLit.Elts))
 
 	for _, elt := range compositeLit.Elts {
@@ -141,5 +137,5 @@ func ParseExprWithFileSet(fset *token.FileSet, filename string, input string) ([
 		})
 	}
 
-	return result, nil
+	return result
 }

codegen/internal/scanner/examples-parser/parser.go

@@ -289,12 +289,6 @@ func (x TestableExample) Render() string {
 	}
 
 	return x.renderBody()
-
-	// Previous routing: stripped package/imports/main scaffolding.
-	// if x.WholeFile && x.play != nil {
-	// 	return x.renderWholeFile()
-	// }
-	// return x.renderBody()
 }
 
 // renderPlay renders the Play AST as-is:
@@ -323,7 +317,9 @@ func (x TestableExample) renderBody() string {
 		return ""
 	}
 
-	// Print the raw AST node.
+	// Print the raw AST node as valid, formatted go code.
+	// This allows to generate code from the testable values
+	// captured in the godoc of an assertion.
 	var buf bytes.Buffer
 	p := printer.Config{Mode: printer.UseSpaces, Tabwidth: tabWidth}
 	if err := p.Fprint(&buf, x.fset, x.code); err != nil {
@@ -352,36 +348,6 @@ func (x TestableExample) renderBody() string {
 	return extractFuncBody(string(formatted))
 }
 
-/*
-// renderWholeFile renders a whole-file example, stripping the package clause
-// and imports, and renaming "func main()" back to the example function name.
-func (x TestableExample) renderWholeFile() string {
-	// Print the entire Play file.
-	var buf bytes.Buffer
-	p := printer.Config{Mode: printer.UseSpaces, Tabwidth: tabWidth}
-	if err := p.Fprint(&buf, x.fset, x.play); err != nil {
-		return ""
-	}
-
-	raw := buf.String()
-
-	// Remove "// Output:" comments.
-	raw = stripOutputComments(raw)
-
-	// Format with goimports.
-	formatted, err := imports.Process("example.go", []byte(raw), &imports.Options{
-		Fragment:   true,
-		FormatOnly: true,
-	})
-	if err != nil {
-		formatted = []byte(raw)
-	}
-
-	// Strip package clause and imports, rename main -> Example function.
-	return extractWholeFileBody(string(formatted), "Example"+x.Name)
-}
-*/
-
 // extractWholeFileBody strips the package clause and import blocks from a
 // formatted Go file, and renames "func main()" to the given example function name.
 func extractWholeFileBody(src, exampleFuncName string) string {

docs/doc-site/api/number.md

@@ -281,13 +281,15 @@ func main() {
 |--|--|
 | [`assertions.InDeltaMapValues(t T, expected any, actual any, delta float64, msgAndArgs ...any) bool`](https://pkg.go.dev/github.com/go-openapi/testify/v2/internal/assertions#InDeltaMapValues) | internal implementation |
 
-**Source:** [github.com/go-openapi/testify/v2/internal/assertions#InDeltaMapValues](https://github.com/go-openapi/testify/blob/master/internal/assertions/number.go#L367)
+**Source:** [github.com/go-openapi/testify/v2/internal/assertions#InDeltaMapValues](https://github.com/go-openapi/testify/blob/master/internal/assertions/number.go#L375)
 {{% /tab %}}
 {{< /tabs >}}
 
 ### InDeltaSlice{#indeltaslice}
 InDeltaSlice is the same as [InDelta](https://pkg.go.dev/github.com/go-openapi/testify/v2/assert#InDelta), except it compares two slices.
 
+It returns false if the compared slices are not of the same length.
+
 See [InDelta](https://pkg.go.dev/github.com/go-openapi/testify/v2/assert#InDelta).
 
 {{% expand title="Examples" %}}
@@ -394,7 +396,7 @@ func main() {
 |--|--|
 | [`assertions.InDeltaSlice(t T, expected any, actual any, delta float64, msgAndArgs ...any) bool`](https://pkg.go.dev/github.com/go-openapi/testify/v2/internal/assertions#InDeltaSlice) | internal implementation |
 
-**Source:** [github.com/go-openapi/testify/v2/internal/assertions#InDeltaSlice](https://github.com/go-openapi/testify/blob/master/internal/assertions/number.go#L331)
+**Source:** [github.com/go-openapi/testify/v2/internal/assertions#InDeltaSlice](https://github.com/go-openapi/testify/blob/master/internal/assertions/number.go#L333)
 {{% /tab %}}
 {{< /tabs >}}
 
@@ -752,7 +754,7 @@ func main() {
 |--|--|
 | [`assertions.InEpsilonSlice(t T, expected any, actual any, epsilon float64, msgAndArgs ...any) bool`](https://pkg.go.dev/github.com/go-openapi/testify/v2/internal/assertions#InEpsilonSlice) | internal implementation |
 
-**Source:** [github.com/go-openapi/testify/v2/internal/assertions#InEpsilonSlice](https://github.com/go-openapi/testify/blob/master/internal/assertions/number.go#L422)
+**Source:** [github.com/go-openapi/testify/v2/internal/assertions#InEpsilonSlice](https://github.com/go-openapi/testify/blob/master/internal/assertions/number.go#L430)
 {{% /tab %}}
 {{< /tabs >}}
 

internal/assertions/enable/colors/colors.go

@@ -20,18 +20,6 @@ const (
 	brightYellowMark = "\033[0;93m" // aka yellow
 	brightCyanMark   = "\033[0;96m" // aka turquoise
 
-	// color codes for future use.
-
-	// blackMark   = "\033[0;30m"
-	// blueMark    = "\033[0;34m"
-	// magentaMark = "\033[0;35m"
-	// greyMark    = "\033[0;37m".
-
-	// darkGreyMark      = "\033[0;90m"
-	// brightBlueMark    = "\033[0;94m"
-	// brightMagentaMark = "\033[0;95m"
-	// brightWhiteMark   = "\033[0;97m".
-
 	endMark = "\033[0m"
 )
 
@@ -56,13 +44,9 @@ func noopColorizer(s string) string {
 var (
 	greenColorizer = makeColorizer(greenMark)
 	redColorizer   = makeColorizer(redMark)
-	// yellowColorizer = makeColorizer(yellowMark)
-	// cyanColorizer   = makeColorizer(cyanMark).
 
 	brightGreenColorizer = makeColorizer(brightGreenMark)
 	brightRedColorizer   = makeColorizer(brightRedMark)
-	// brightYellowColorizer = makeColorizer(brightYellowMark)
-	// brightCyanColorizer   = makeColorizer(brightCyanMark).
 )
 
 //nolint:gochecknoglobals // internal printer builders may safely be shared at the package-level
@@ -76,12 +60,6 @@ var (
 	brightRedPrinterBuilder    = ansiPrinterBuilder(brightRedMark)
 	brightYellowPrinterBuilder = ansiPrinterBuilder(brightYellowMark)
 	brightCyanPrinterBuilder   = ansiPrinterBuilder(brightCyanMark)
-
-	// magentaPrinterBuilder = ansiPrinterBuilder(magentaMark)
-	// bluePrinterBuilder    = ansiPrinterBuilder(blueMark).
-
-	// brightMagentaPrinterBuilder = ansiPrinterBuilder(brightMagentaMark)
-	// brightBluePrinterBuilder    = ansiPrinterBuilder(brightBlueMark).
 )
 
 func ansiPrinterBuilder(mark string) difflib.PrinterBuilder {