perf(validator,fixer,builder,joiner): migrate to pathutil for ref string building (#289)

* perf(validator,fixer,builder): migrate to pathutil for ref string building

Replace fmt.Sprintf and inline string concatenation with centralized
pathutil reference builders across validator, fixer, and builder packages.

Changes:
- validator/refs.go: Replace 14 fmt.Sprintf calls with pathutil functions
- fixer/refs.go: Replace helper functions and inline concatenations with pathutil
- fixer/stub_missing_refs.go: Use pathutil for prefix constants and descriptions
- fixer/generic_names.go: Use pathutil constants in extractSchemaNameFromRefPath
- builder/parameter.go: Replace parameterRefPrefix with pathutil.ParameterRef
- builder/response.go: Replace responseRefPrefix with pathutil.ResponseRef

Benefits:
- Eliminates ~40 fmt.Sprintf/string concat calls
- Removes 2 duplicate helper functions
- Replaces 14+ hardcoded prefix strings with constants
- Centralizes all OAS reference path logic in internal/pathutil

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* perf(joiner): migrate to pathutil for ref string building

- Use pathutil.DefinitionRef/SchemaRef in schemaRefPath()
- Use pathutil constants in extractSchemaName()
- Modernize to strings.CutPrefix for cleaner prefix extraction

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: erraggy

builder/parameter.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"regexp"
 
+	"github.com/erraggy/oastools/internal/pathutil"
 	"github.com/erraggy/oastools/oaserrors"
 	"github.com/erraggy/oastools/parser"
 )
@@ -643,19 +644,10 @@ func hasParamConstraints(cfg *paramConfig) bool {
 		cfg.defaultValue != nil
 }
 
-// parameterRefPrefix returns the appropriate $ref prefix for parameters.
-// OAS 2.0 uses "#/parameters/" while OAS 3.x uses "#/components/parameters/".
-func (b *Builder) parameterRefPrefix() string {
-	if b.version == parser.OASVersion20 {
-		return "#/parameters/"
-	}
-	return "#/components/parameters/"
-}
-
 // ParameterRef returns a reference to a named parameter.
 // This method returns the version-appropriate ref path.
 func (b *Builder) ParameterRef(name string) string {
-	return b.parameterRefPrefix() + name
+	return pathutil.ParameterRef(name, b.version == parser.OASVersion20)
 }
 
 // WithParameterRef adds a parameter reference to the operation.

builder/response.go

@@ -1,6 +1,7 @@
 package builder
 
 import (
+	"github.com/erraggy/oastools/internal/pathutil"
 	"github.com/erraggy/oastools/parser"
 )
 
@@ -96,19 +97,10 @@ func (b *Builder) AddResponse(name string, description string, responseType any,
 	return b
 }
 
-// responseRefPrefix returns the appropriate $ref prefix for responses.
-// OAS 2.0 uses "#/responses/" while OAS 3.x uses "#/components/responses/".
-func (b *Builder) responseRefPrefix() string {
-	if b.version == parser.OASVersion20 {
-		return "#/responses/"
-	}
-	return "#/components/responses/"
-}
-
 // ResponseRef returns a reference to a named response.
 // This method returns the version-appropriate ref path.
 func (b *Builder) ResponseRef(name string) string {
-	return b.responseRefPrefix() + name
+	return pathutil.ResponseRef(name, b.version == parser.OASVersion20)
 }
 
 // buildResponsesFromMap converts a map of status codes to responses into

fixer/generic_names.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"unicode"
 
+	"github.com/erraggy/oastools/internal/pathutil"
 	"github.com/erraggy/oastools/parser"
 	"golang.org/x/text/cases"
 	"golang.org/x/text/language"
@@ -551,11 +552,11 @@ func rewriteSchemaRefsRecursive(schema *parser.Schema, renames map[string]string
 // Returns empty string if not a schema reference.
 func extractSchemaNameFromRefPath(ref string) string {
 	// OAS 3.x style
-	if name, found := strings.CutPrefix(ref, "#/components/schemas/"); found {
+	if name, found := strings.CutPrefix(ref, pathutil.RefPrefixSchemas); found {
 		return name
 	}
 	// OAS 2.0 style
-	if name, found := strings.CutPrefix(ref, "#/definitions/"); found {
+	if name, found := strings.CutPrefix(ref, pathutil.RefPrefixDefinitions); found {
 		return name
 	}
 	return ""

fixer/refs.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/erraggy/oastools/internal/pathutil"
 	"github.com/erraggy/oastools/parser"
 )
 
@@ -812,7 +813,7 @@ func (c *RefCollector) IsResponseReferenced(name string, version parser.OASVersi
 // IsRequestBodyReferenced returns true if a request body with the given name is referenced.
 // This is only applicable for OAS 3.x documents.
 func (c *RefCollector) IsRequestBodyReferenced(name string) bool {
-	ref := "#/components/requestBodies/" + name
+	ref := pathutil.RequestBodyRef(name)
 	return c.isRefReferenced(ref, RefTypeRequestBody)
 }
 
@@ -831,31 +832,31 @@ func (c *RefCollector) IsHeaderReferenced(name string, version parser.OASVersion
 		// OAS 2.0 doesn't have a global headers definition
 		return false
 	}
-	ref = "#/components/headers/" + name
+	ref = pathutil.HeaderRef(name)
 	return c.isRefReferenced(ref, RefTypeHeader)
 }
 
 // IsLinkReferenced returns true if a link with the given name is referenced.
 func (c *RefCollector) IsLinkReferenced(name string) bool {
-	ref := "#/components/links/" + name
+	ref := pathutil.LinkRef(name)
 	return c.isRefReferenced(ref, RefTypeLink)
 }
 
 // IsCallbackReferenced returns true if a callback with the given name is referenced.
 func (c *RefCollector) IsCallbackReferenced(name string) bool {
-	ref := "#/components/callbacks/" + name
+	ref := pathutil.CallbackRef(name)
 	return c.isRefReferenced(ref, RefTypeCallback)
 }
 
 // IsExampleReferenced returns true if an example with the given name is referenced.
 func (c *RefCollector) IsExampleReferenced(name string) bool {
-	ref := "#/components/examples/" + name
+	ref := pathutil.ExampleRef(name)
 	return c.isRefReferenced(ref, RefTypeExample)
 }
 
 // IsPathItemReferenced returns true if a path item with the given name is referenced.
 func (c *RefCollector) IsPathItemReferenced(name string) bool {
-	ref := "#/components/pathItems/" + name
+	ref := pathutil.PathItemRef(name)
 	return c.isRefReferenced(ref, RefTypePathItem)
 }
 
@@ -920,43 +921,34 @@ func (c *RefCollector) getRefsByType(refType RefType) []string {
 // schemaRefPath returns the reference path for a schema name.
 func schemaRefPath(name string, version parser.OASVersion) string {
 	if version == parser.OASVersion20 {
-		return "#/definitions/" + name
+		return pathutil.DefinitionRef(name)
 	}
-	return "#/components/schemas/" + name
+	return pathutil.SchemaRef(name)
 }
 
 // parameterRefPath returns the reference path for a parameter name.
 func parameterRefPath(name string, version parser.OASVersion) string {
-	if version == parser.OASVersion20 {
-		return "#/parameters/" + name
-	}
-	return "#/components/parameters/" + name
+	return pathutil.ParameterRef(name, version == parser.OASVersion20)
 }
 
 // responseRefPath returns the reference path for a response name.
 func responseRefPath(name string, version parser.OASVersion) string {
-	if version == parser.OASVersion20 {
-		return "#/responses/" + name
-	}
-	return "#/components/responses/" + name
+	return pathutil.ResponseRef(name, version == parser.OASVersion20)
 }
 
 // securitySchemeRefPath returns the reference path for a security scheme name.
 func securitySchemeRefPath(name string, version parser.OASVersion) string {
-	if version == parser.OASVersion20 {
-		return "#/securityDefinitions/" + name
-	}
-	return "#/components/securitySchemes/" + name
+	return pathutil.SecuritySchemeRef(name, version == parser.OASVersion20)
 }
 
 // ExtractSchemaNameFromRef extracts the schema name from a reference path.
 // Returns empty string if the reference is not a schema reference.
 func ExtractSchemaNameFromRef(ref string, version parser.OASVersion) string {
 	var prefix string
 	if version == parser.OASVersion20 {
-		prefix = "#/definitions/"
+		prefix = pathutil.RefPrefixDefinitions
 	} else {
-		prefix = "#/components/schemas/"
+		prefix = pathutil.RefPrefixSchemas
 	}
 
 	if name, found := strings.CutPrefix(ref, prefix); found {
@@ -970,24 +962,24 @@ func ExtractSchemaNameFromRef(ref string, version parser.OASVersion) string {
 func ExtractComponentNameFromRef(ref string) (componentType, name string) {
 	// OAS 2.0 patterns
 	oas2Prefixes := map[string]string{
-		"#/definitions/":         "schema",
-		"#/parameters/":          "parameter",
-		"#/responses/":           "response",
-		"#/securityDefinitions/": "securityScheme",
+		pathutil.RefPrefixDefinitions:         "schema",
+		pathutil.RefPrefixParameters:          "parameter",
+		pathutil.RefPrefixResponses:           "response",
+		pathutil.RefPrefixSecurityDefinitions: "securityScheme",
 	}
 
 	// OAS 3.x patterns
 	oas3Prefixes := map[string]string{
-		"#/components/schemas/":         "schema",
-		"#/components/parameters/":      "parameter",
-		"#/components/responses/":       "response",
-		"#/components/requestBodies/":   "requestBody",
-		"#/components/headers/":         "header",
-		"#/components/securitySchemes/": "securityScheme",
-		"#/components/links/":           "link",
-		"#/components/callbacks/":       "callback",
-		"#/components/examples/":        "example",
-		"#/components/pathItems/":       "pathItem",
+		pathutil.RefPrefixSchemas:         "schema",
+		pathutil.RefPrefixParameters3:     "parameter",
+		pathutil.RefPrefixResponses3:      "response",
+		pathutil.RefPrefixRequestBodies:   "requestBody",
+		pathutil.RefPrefixHeaders:         "header",
+		pathutil.RefPrefixSecuritySchemes: "securityScheme",
+		pathutil.RefPrefixLinks:           "link",
+		pathutil.RefPrefixCallbacks:       "callback",
+		pathutil.RefPrefixExamples:        "example",
+		pathutil.RefPrefixPathItems:       "pathItem",
 	}
 
 	// Try OAS 3.x patterns first (more specific)

fixer/stub_missing_refs.go

@@ -9,6 +9,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/erraggy/oastools/internal/pathutil"
 	"github.com/erraggy/oastools/parser"
 )
 
@@ -37,9 +38,9 @@ func isLocalRef(ref string) bool {
 func extractResponseNameFromRef(ref string, version parser.OASVersion) string {
 	var prefix string
 	if version == parser.OASVersion20 {
-		prefix = "#/responses/"
+		prefix = pathutil.RefPrefixResponses
 	} else {
-		prefix = "#/components/responses/"
+		prefix = pathutil.RefPrefixResponses3
 	}
 
 	if name, found := strings.CutPrefix(ref, prefix); found {
@@ -119,7 +120,7 @@ func (f *Fixer) stubSchemaOAS2(doc *parser.OAS2Document, name string, result *Fi
 	fix := Fix{
 		Type:        FixTypeStubMissingRef,
 		Path:        fmt.Sprintf("definitions.%s", name),
-		Description: fmt.Sprintf("Created stub schema for missing reference #/definitions/%s", name),
+		Description: "Created stub schema for missing reference " + pathutil.DefinitionRef(name),
 		Before:      nil,
 		After:       stub,
 	}
@@ -153,7 +154,7 @@ func (f *Fixer) stubResponseOAS2(doc *parser.OAS2Document, name string, result *
 	fix := Fix{
 		Type:        FixTypeStubMissingRef,
 		Path:        fmt.Sprintf("responses.%s", name),
-		Description: fmt.Sprintf("Created stub response for missing reference #/responses/%s", name),
+		Description: "Created stub response for missing reference " + pathutil.ResponseRef(name, true),
 		Before:      nil,
 		After:       stub,
 	}
@@ -238,7 +239,7 @@ func (f *Fixer) stubSchemaOAS3(doc *parser.OAS3Document, name string, result *Fi
 	fix := Fix{
 		Type:        FixTypeStubMissingRef,
 		Path:        fmt.Sprintf("components.schemas.%s", name),
-		Description: fmt.Sprintf("Created stub schema for missing reference #/components/schemas/%s", name),
+		Description: "Created stub schema for missing reference " + pathutil.SchemaRef(name),
 		Before:      nil,
 		After:       stub,
 	}
@@ -277,7 +278,7 @@ func (f *Fixer) stubResponseOAS3(doc *parser.OAS3Document, name string, result *
 	fix := Fix{
 		Type:        FixTypeStubMissingRef,
 		Path:        fmt.Sprintf("components.responses.%s", name),
-		Description: fmt.Sprintf("Created stub response for missing reference #/components/responses/%s", name),
+		Description: "Created stub response for missing reference " + pathutil.ResponseRef(name, false),
 		Before:      nil,
 		After:       stub,
 	}

joiner/rewriter.go

@@ -5,6 +5,7 @@ import (
 	"reflect"
 	"strings"
 
+	"github.com/erraggy/oastools/internal/pathutil"
 	"github.com/erraggy/oastools/parser"
 )
 
@@ -50,9 +51,9 @@ func (r *SchemaRewriter) RewriteDocument(doc any) error {
 // schemaRefPath returns the $ref path for a schema name based on OAS version
 func schemaRefPath(name string, version parser.OASVersion) string {
 	if version == parser.OASVersion20 {
-		return "#/definitions/" + name
+		return pathutil.DefinitionRef(name)
 	}
-	return "#/components/schemas/" + name
+	return pathutil.SchemaRef(name)
 }
 
 // rewriteOAS3Document rewrites all references in an OAS 3.x document
@@ -402,12 +403,12 @@ func (r *SchemaRewriter) rewriteOperation(op *parser.Operation) {
 // extractSchemaName extracts the schema name from a $ref path
 func extractSchemaName(ref string) string {
 	// Handle "#/components/schemas/Name"
-	if strings.HasPrefix(ref, "#/components/schemas/") {
-		return strings.TrimPrefix(ref, "#/components/schemas/")
+	if name, found := strings.CutPrefix(ref, pathutil.RefPrefixSchemas); found {
+		return name
 	}
 	// Handle "#/definitions/Name"
-	if strings.HasPrefix(ref, "#/definitions/") {
-		return strings.TrimPrefix(ref, "#/definitions/")
+	if name, found := strings.CutPrefix(ref, pathutil.RefPrefixDefinitions); found {
+		return name
 	}
 	return ""
 }