diff --git a/required_direction_test.go b/required_direction_test.go new file mode 100644 index 00000000..2f33de5a --- /dev/null +++ b/required_direction_test.go @@ -0,0 +1,44 @@ +// Copyright 2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package libopenapi + +import ( + "fmt" + "testing" + + "github.com/pb33f/testify/assert" + "github.com/pb33f/testify/require" +) + +func TestCompareDocumentsRequiredDirection(t *testing.T) { + const request = `"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},"responses":{"204":{"description":"ok"}}` + const response = `"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}}}` + const both = `"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Widget"}}}},` + response + const spec = `{"openapi":"3.1.0","info":{"title":"Direction","version":"1.0.0"},` + + `"paths":{"/widgets":{"post":{%s}}},` + + `"components":{"schemas":{"Widget":{"type":"object","required":[%s],"properties":{"name":{"type":"string"},"id":{"type":"string"}}}}}}` + for _, tc := range []struct { + name, operation, old, next string + breaking bool + }{ + {"response schema gains a required entry", response, `"name"`, `"name","id"`, false}, + {"response schema loses a required entry", response, `"name","id"`, `"name"`, true}, + {"request schema gains a required entry", request, `"name"`, `"name","id"`, true}, + {"request schema loses a required entry", request, `"name","id"`, `"name"`, false}, + {"shared schema gains a required entry", both, `"name"`, `"name","id"`, true}, + {"shared schema loses a required entry", both, `"name","id"`, `"name"`, true}, + } { + t.Run(tc.name, func(t *testing.T) { + left, err := NewDocument([]byte(fmt.Sprintf(spec, tc.operation, tc.old))) + require.NoError(t, err) + right, err := NewDocument([]byte(fmt.Sprintf(spec, tc.operation, tc.next))) + require.NoError(t, err) + changes, err := CompareDocuments(left, right) + require.NoError(t, err) + require.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalChanges()) + assert.Equal(t, tc.breaking, changes.TotalBreakingChanges() > 0) + }) + } +} diff --git a/what-changed/model/document.go b/what-changed/model/document.go index 5c9263c1..eb311aa7 100644 --- a/what-changed/model/document.go +++ b/what-changed/model/document.go @@ -235,6 +235,10 @@ func CompareDocuments(l, r any) *DocumentChanges { lDoc := l.(*v3.Document) rDoc := r.(*v3.Document) + // record which schemas requests and responses use, so that schema changes + // whose effect depends on direction can be classified. + defer trackSchemaUsage(lDoc.Index, rDoc.Index)() + // version addPropertyCheck(&props, lDoc.Version.ValueNode, rDoc.Version.ValueNode, lDoc.Version.Value, rDoc.Version.Value, &changes, v3.OpenAPILabel, diff --git a/what-changed/model/schema.go b/what-changed/model/schema.go index 1f5cea0a..8d8801a0 100644 --- a/what-changed/model/schema.go +++ b/what-changed/model/schema.go @@ -1166,10 +1166,11 @@ func (c *schemaComparison) checkSchemaPropertyChanges( k[rSchema.Required.Value[i].Value] = i } } + requiredAddedBreaking, requiredRemovedBreaking := requiredChangeBreaking(lProxy, rProxy) for g := range k { if _, ok := j[g]; !ok { CreateChange(changes, PropertyAdded, v3.RequiredLabel, - nil, rSchema.Required.Value[k[g]].GetValueNode(), BreakingAdded(CompSchema, PropRequired), nil, + nil, rSchema.Required.Value[k[g]].GetValueNode(), requiredAddedBreaking, nil, rSchema.Required.Value[k[g]].GetValue) checkLocation((*changes)[len(*changes)-1].Context, rSchema.ParentProxy.Schema()) } @@ -1177,7 +1178,7 @@ func (c *schemaComparison) checkSchemaPropertyChanges( for g := range j { if _, ok := k[g]; !ok { CreateChange(changes, PropertyRemoved, v3.RequiredLabel, - lSchema.Required.Value[j[g]].GetValueNode(), nil, BreakingRemoved(CompSchema, PropRequired), lSchema.Required.Value[j[g]].GetValue, + lSchema.Required.Value[j[g]].GetValueNode(), nil, requiredRemovedBreaking, lSchema.Required.Value[j[g]].GetValue, nil) checkLocation((*changes)[len(*changes)-1].Context, lSchema.ParentProxy.Schema()) } diff --git a/what-changed/model/schema_usage.go b/what-changed/model/schema_usage.go new file mode 100644 index 00000000..e9f0f3c2 --- /dev/null +++ b/what-changed/model/schema_usage.go @@ -0,0 +1,350 @@ +// Copyright 2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package model + +import ( + "net/url" + "strconv" + "strings" + "sync" + + "github.com/pb33f/go-yaml" + "github.com/pb33f/libopenapi/datamodel/low/base" + "github.com/pb33f/libopenapi/index" +) + +// schemaDirection records which side of an exchange can carry a schema. +// A request schema describes data that a client sends. A response schema +// describes data that a server returns. +type schemaDirection uint8 + +const ( + directionRequest schemaDirection = 1 << iota + directionResponse + directionBoth = directionRequest | directionResponse +) + +// schemaUsage maps the nodes of one OpenAPI 3 document to the directions that +// can reach them from its operations and webhooks. +type schemaUsage struct { + nodes map[*yaml.Node]schemaDirection +} + +// schemaUsageByIndex holds the usage of each document while CompareDocuments +// runs. A schema finds the usage of its document through its index. A schema +// whose index is not here has no known direction. Comparisons that run at the +// same time can share a document, so each record counts its comparisons. +var ( + schemaUsageMu sync.RWMutex + schemaUsageByIndex = make(map[*index.SpecIndex]*trackedSchemaUsage) +) + +type trackedSchemaUsage struct { + usage *schemaUsage + refs int +} + +// trackSchemaUsage records the usage of each document index for one comparison +// and returns a function that releases it again. +func trackSchemaUsage(indexes ...*index.SpecIndex) func() { + schemaUsageMu.Lock() + defer schemaUsageMu.Unlock() + var tracked []*index.SpecIndex + for _, idx := range indexes { + if idx == nil { + continue + } + entry, ok := schemaUsageByIndex[idx] + if !ok { + usage := buildSchemaUsage(idx.GetRootNode()) + if usage == nil { + continue + } + entry = &trackedSchemaUsage{usage: usage} + schemaUsageByIndex[idx] = entry + } + entry.refs++ + tracked = append(tracked, idx) + } + return func() { + schemaUsageMu.Lock() + defer schemaUsageMu.Unlock() + for _, idx := range tracked { + if entry := schemaUsageByIndex[idx]; entry.refs > 1 { + entry.refs-- + } else { + delete(schemaUsageByIndex, idx) + } + } + } +} + +// schemaPairDirection returns the union of the directions that reach the left +// and right schemas. known is false when either side has no usage record, so +// callers keep their direction-free result. +func schemaPairDirection(l, r *base.SchemaProxy) (direction schemaDirection, known bool) { + if l == nil && r == nil { + return 0, false + } + for _, proxy := range []*base.SchemaProxy{l, r} { + if proxy == nil { + continue + } + d, ok := proxyDirection(proxy) + if !ok { + return 0, false + } + direction |= d + } + return direction, true +} + +func proxyDirection(proxy *base.SchemaProxy) (schemaDirection, bool) { + node := proxy.GetValueNode() + if node == nil { + return 0, false + } + schemaUsageMu.RLock() + entry, ok := schemaUsageByIndex[proxy.GetIndex()] + schemaUsageMu.RUnlock() + if !ok { + return 0, false + } + return entry.usage.nodes[node], true +} + +// buildSchemaUsage walks every operation and webhook of an OpenAPI 3 document. +// Request bodies and parameters mark their subtrees as request data. Responses +// mark their subtrees as response data. Callbacks, webhooks, and any other +// operation field mark both, because their direction is not the direction of +// the API's own operations. Each local $ref passes the direction to its target. +// +// The walk gives up, and returns nil, when it cannot see every place that a +// schema is used: an external or unresolvable $ref, a $dynamicRef, or a +// discriminator mapping that it cannot resolve. +func buildSchemaUsage(root *yaml.Node) *schemaUsage { + if root != nil && root.Kind == yaml.DocumentNode && len(root.Content) > 0 { + root = root.Content[0] + } + if root == nil || root.Kind != yaml.MappingNode { + return nil + } + w := &usageWalker{ + root: root, + nodes: make(map[*yaml.Node]schemaDirection), + visited: make(map[*yaml.Node]struct{}), + } + for i := 0; i+1 < len(root.Content); i += 2 { + switch root.Content[i].Value { + case "paths": + w.eachValue(root.Content[i+1], w.pathItem) + case "webhooks": + w.eachValue(root.Content[i+1], func(n *yaml.Node) { w.walk(n, directionBoth) }) + } + } + if w.unsure { + return nil + } + return &schemaUsage{nodes: w.nodes} +} + +type usageWalker struct { + root *yaml.Node + nodes map[*yaml.Node]schemaDirection + // visited holds the path items and operations already read, so that + // $ref cycles between them end. + visited map[*yaml.Node]struct{} + unsure bool +} + +// first reports whether node is a path item or operation not read before. +func (w *usageWalker) first(node *yaml.Node) bool { + if _, done := w.visited[node]; done { + return false + } + w.visited[node] = struct{}{} + return true +} + +var operationKeys = map[string]bool{ + "get": true, "put": true, "post": true, "delete": true, "options": true, + "head": true, "patch": true, "trace": true, "query": true, +} + +func (w *usageWalker) eachValue(node *yaml.Node, visit func(*yaml.Node)) { + if node == nil || node.Kind != yaml.MappingNode { + return + } + for i := 1; i < len(node.Content); i += 2 { + visit(node.Content[i]) + } +} + +func (w *usageWalker) pathItem(node *yaml.Node) { + if node.Kind != yaml.MappingNode || !w.first(node) { + return + } + for i := 0; i+1 < len(node.Content); i += 2 { + key, value := node.Content[i].Value, node.Content[i+1] + switch { + case key == "$ref": + if target := w.resolveOrGiveUp(value.Value); target != nil { + w.pathItem(target) + } + case key == "parameters": + w.walk(value, directionRequest) + case operationKeys[key]: + w.operation(value) + case key == "additionalOperations": + w.eachValue(value, w.operation) + default: + w.walk(value, directionBoth) + } + } +} + +func (w *usageWalker) operation(node *yaml.Node) { + if node.Kind != yaml.MappingNode || !w.first(node) { + return + } + for i := 0; i+1 < len(node.Content); i += 2 { + value := node.Content[i+1] + switch node.Content[i].Value { + case "$ref": + // libopenapi also reads an operation from a $ref. + if target := w.resolveOrGiveUp(value.Value); target != nil { + w.operation(target) + } + case "parameters", "requestBody": + w.walk(value, directionRequest) + case "responses": + w.walk(value, directionResponse) + default: + w.walk(value, directionBoth) + } + } +} + +func (w *usageWalker) walk(node *yaml.Node, direction schemaDirection) { + if node == nil || node.Kind == yaml.ScalarNode || w.unsure { + return + } + // a node already reached in this direction needs no second visit. + if w.nodes[node]&direction == direction { + return + } + w.nodes[node] |= direction + switch node.Kind { + case yaml.AliasNode: + w.walk(node.Alias, direction) + case yaml.SequenceNode: + for _, item := range node.Content { + w.walk(item, direction) + } + case yaml.MappingNode: + for i := 0; i+1 < len(node.Content); i += 2 { + key, value := node.Content[i].Value, node.Content[i+1] + switch key { + case "$ref": + w.walk(w.resolveOrGiveUp(value.Value), direction) + case "$dynamicRef": + w.unsure = true + return + case "discriminator": + w.discriminatorMapping(value, direction) + } + w.walk(value, direction) + } + } +} + +func (w *usageWalker) discriminatorMapping(node *yaml.Node, direction schemaDirection) { + if node.Kind != yaml.MappingNode { + return + } + for i := 0; i+1 < len(node.Content); i += 2 { + if node.Content[i].Value != "mapping" { + continue + } + w.eachValue(node.Content[i+1], func(target *yaml.Node) { + ref := target.Value + if !strings.HasPrefix(ref, "#") { + ref = "#/components/schemas/" + ref + } + w.walk(w.resolveOrGiveUp(ref), direction) + }) + } +} + +func (w *usageWalker) resolveOrGiveUp(ref string) *yaml.Node { + target := w.resolve(ref) + if target == nil { + w.unsure = true + } + return target +} + +// resolve follows a local JSON pointer such as #/components/schemas/Widget. +// It returns nil for any other reference. +func (w *usageWalker) resolve(ref string) *yaml.Node { + if !strings.HasPrefix(ref, "#/") { + return nil + } + node := w.root + for _, token := range strings.Split(ref[2:], "/") { + token, err := url.PathUnescape(token) + if err != nil { + return nil + } + token = strings.ReplaceAll(strings.ReplaceAll(token, "~1", "/"), "~0", "~") + node = pointerChild(node, token) + if node == nil { + return nil + } + } + return node +} + +func pointerChild(node *yaml.Node, token string) *yaml.Node { + for node.Kind == yaml.AliasNode { + node = node.Alias + } + switch node.Kind { + case yaml.MappingNode: + for i := 0; i+1 < len(node.Content); i += 2 { + if node.Content[i].Value == token { + return node.Content[i+1] + } + } + case yaml.SequenceNode: + if i, err := strconv.Atoi(token); err == nil && i >= 0 && i < len(node.Content) { + return node.Content[i] + } + } + return nil +} + +// requiredChangeBreaking returns the breaking classification of an added and a +// removed required entry. A new required entry only narrows what a server may +// return, so it does not break a schema that only responses use. A removed +// required entry only relaxes what a client must send, so it does not break a +// schema that only requests use. Every other case keeps the configured rule. +func requiredChangeBreaking(l, r *base.SchemaProxy) (added, removed bool) { + added = BreakingAdded(CompSchema, PropRequired) + removed = BreakingRemoved(CompSchema, PropRequired) + if !added && !removed { + return added, removed + } + direction, known := schemaPairDirection(l, r) + if !known { + return added, removed + } + if direction == directionResponse { + added = false + } + if direction == directionRequest { + removed = false + } + return added, removed +} diff --git a/what-changed/model/schema_usage_test.go b/what-changed/model/schema_usage_test.go new file mode 100644 index 00000000..01fcf695 --- /dev/null +++ b/what-changed/model/schema_usage_test.go @@ -0,0 +1,478 @@ +// Copyright 2026 Princess B33f Heavy Industries / Dave Shanley +// SPDX-License-Identifier: MIT + +package model + +import ( + "strings" + "testing" + + "github.com/pb33f/go-yaml" + "github.com/pb33f/libopenapi/datamodel" + "github.com/pb33f/libopenapi/datamodel/low" + "github.com/pb33f/libopenapi/datamodel/low/base" + v3 "github.com/pb33f/libopenapi/datamodel/low/v3" + "github.com/pb33f/libopenapi/index" + "github.com/pb33f/testify/assert" + "github.com/pb33f/testify/require" +) + +// usageSpec builds a document whose operation and components are given as YAML +// fragments indented for their place in the document. +func usageSpec(operation, schemas string) string { + return `openapi: 3.1.0 +info: {title: Direction, version: 1.0.0} +paths: + /widgets: + post: +` + operation + ` +components: + schemas: +` + schemas +} + +const ( + usageRequestOnly = ` requestBody: + content: + application/json: + schema: {$ref: '#/components/schemas/Widget'} + responses: + '204': {description: ok}` + usageResponseOnly = ` responses: + '200': + description: ok + content: + application/json: + schema: {$ref: '#/components/schemas/Widget'}` + usageShared = ` requestBody: + content: + application/json: + schema: {$ref: '#/components/schemas/Widget'} + responses: + '200': + description: ok + content: + application/json: + schema: {$ref: '#/components/schemas/Widget'}` + usageCallback = ` responses: + '204': {description: ok} + callbacks: + done: + '{$request.body#/url}': + post: + requestBody: + content: + application/json: + schema: {$ref: '#/components/schemas/Widget'} + responses: + '204': {description: ok}` + usageUnused = ` responses: + '204': {description: ok}` +) + +func usageWidget(required string) string { + return ` Widget: + type: object + required: [` + required + `] + properties: + name: {type: string} + id: {type: string}` +} + +func compareUsageDocuments(t *testing.T, left, right string) *DocumentChanges { + t.Helper() + lInfo, err := datamodel.ExtractSpecInfo([]byte(left)) + require.NoError(t, err) + rInfo, err := datamodel.ExtractSpecInfo([]byte(right)) + require.NoError(t, err) + lDoc, err := v3.CreateDocumentFromConfig(lInfo, datamodel.NewDocumentConfiguration()) + require.NoError(t, err) + rDoc, err := v3.CreateDocumentFromConfig(rInfo, datamodel.NewDocumentConfiguration()) + require.NoError(t, err) + return CompareDocuments(lDoc, rDoc) +} + +func TestCompareDocuments_SchemaRequiredDirection(t *testing.T) { + cases := []struct { + name, operation string + old, next string + breaking bool + }{ + {"added in response schema", usageResponseOnly, "name", "name, id", false}, + {"removed in response schema", usageResponseOnly, "name, id", "name", true}, + {"added in request schema", usageRequestOnly, "name", "name, id", true}, + {"removed in request schema", usageRequestOnly, "name, id", "name", false}, + {"added in shared schema", usageShared, "name", "name, id", true}, + {"removed in shared schema", usageShared, "name, id", "name", true}, + {"added in callback schema", usageCallback, "name", "name, id", true}, + {"added in unused schema", usageUnused, "name", "name, id", true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + changes := compareUsageDocuments(t, + usageSpec(tc.operation, usageWidget(tc.old)), + usageSpec(tc.operation, usageWidget(tc.next))) + require.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalChanges()) + assert.Equal(t, tc.breaking, changes.TotalBreakingChanges() > 0) + }) + } +} + +func TestCompareDocuments_SchemaRequiredDirectionUnionOfDocuments(t *testing.T) { + // The old document also sends Widget in a request, so the new required entry + // can still break a client of the old contract. + changes := compareUsageDocuments(t, + usageSpec(usageShared, usageWidget("name")), + usageSpec(usageResponseOnly, usageWidget("name, id"))) + require.NotNil(t, changes) + assert.Positive(t, changes.TotalBreakingChanges()) +} + +func TestCompareDocuments_SchemaRequiredDirectionInlineAndNested(t *testing.T) { + const operation = ` parameters: + - name: filter + in: query + schema: {$ref: '#/components/schemas/Filter'} + requestBody: + $ref: '#/components/requestBodies/WidgetInput' + responses: + '200': + $ref: '#/components/responses/WidgetOutput' + '201': + description: ok + headers: + X-Page: {schema: {$ref: '#/components/schemas/Page'}} + content: + application/json: + schema: + type: object + required: [%s] + properties: + name: {type: string} + id: {type: string}` + const schemas = ` Filter: {type: object, required: [%s], properties: {name: {type: string}, id: {type: string}}} + Page: {type: object, required: [%s], properties: {name: {type: string}, id: {type: string}}} + Input: {type: object, properties: {part: {$ref: '#/components/schemas/Part'}}} + Output: {type: object, properties: {part: {$ref: '#/components/schemas/Part'}, detail: {$ref: '#/components/schemas/Detail'}}} + Part: {type: object, required: [%s], properties: {name: {type: string}, id: {type: string}}} + Detail: + type: object + required: [%s] + properties: {name: {type: string}, id: {type: string}} + requestBodies: + WidgetInput: + content: + application/json: + schema: {$ref: '#/components/schemas/Input'} + responses: + WidgetOutput: + description: ok + content: + application/json: + schema: {$ref: '#/components/schemas/Output'}` + build := func(inline, filter, page, part, detail string) string { + return usageSpec(fillRequired(operation, inline), fillRequired(schemas, filter, page, part, detail)) + } + cases := []struct { + name string + old, next [5]string + breakingCount int + }{ + {"inline response schema", [5]string{"name", "name", "name", "name", "name"}, [5]string{"name, id", "name", "name", "name", "name"}, 0}, + {"parameter schema", [5]string{"name", "name", "name", "name", "name"}, [5]string{"name", "name, id", "name", "name", "name"}, 1}, + {"response header schema", [5]string{"name", "name", "name", "name", "name"}, [5]string{"name", "name", "name, id", "name", "name"}, 0}, + {"schema reached from request and response", [5]string{"name", "name", "name", "name", "name"}, [5]string{"name", "name", "name", "name, id", "name"}, 1}, + {"schema reached through a response component", [5]string{"name", "name", "name", "name", "name"}, [5]string{"name", "name", "name", "name", "name, id"}, 0}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + changes := compareUsageDocuments(t, + build(tc.old[0], tc.old[1], tc.old[2], tc.old[3], tc.old[4]), + build(tc.next[0], tc.next[1], tc.next[2], tc.next[3], tc.next[4])) + require.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalChanges()) + assert.Equal(t, tc.breakingCount, changes.TotalBreakingChanges()) + }) + } +} + +// fillRequired places each value in the next %s of the template, in order. +func fillRequired(template string, values ...string) string { + for _, v := range values { + template = strings.Replace(template, "%s", v, 1) + } + return template +} + +func TestCompareDocuments_SchemaRequiredDirectionUnknownUsage(t *testing.T) { + // A $dynamicRef hides where schemas are used, so the configured rule applies. + const operation = usageResponseOnly + ` + x-meta: {$dynamicRef: '#meta'}` + changes := compareUsageDocuments(t, + usageSpec(operation, usageWidget("name")), + usageSpec(operation, usageWidget("name, id"))) + require.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalBreakingChanges()) +} + +func TestCompareDocuments_SchemaRequiredDirectionForgetsUsage(t *testing.T) { + compareUsageDocuments(t, + usageSpec(usageResponseOnly, usageWidget("name")), + usageSpec(usageResponseOnly, usageWidget("name, id"))) + schemaUsageMu.RLock() + defer schemaUsageMu.RUnlock() + assert.Empty(t, schemaUsageByIndex) +} + +func TestCompareSchemas_RequiredWithoutDocumentUsage(t *testing.T) { + // CompareSchemas on its own has no document, so it keeps the configured rule. + l := buildSchemaProxyFromYAML(t, "type: object\nrequired: [name]") + r := buildSchemaProxyFromYAML(t, "type: object\nrequired: [name, id]") + changes := CompareSchemas(l, r) + require.NotNil(t, changes) + assert.Equal(t, 1, changes.TotalBreakingChanges()) +} + +func TestRequiredChangeBreaking_RespectsConfiguredRule(t *testing.T) { + defer ResetActiveBreakingRulesConfig() + SetActiveBreakingRulesConfig(&BreakingRulesConfig{ + Schema: &SchemaRules{Required: rule(false, false, false)}, + }) + added, removed := requiredChangeBreaking(nil, nil) + assert.False(t, added) + assert.False(t, removed) + + SetActiveBreakingRulesConfig(&BreakingRulesConfig{ + Schema: &SchemaRules{Required: rule(true, false, true)}, + }) + added, removed = requiredChangeBreaking(nil, nil) + assert.True(t, added) + assert.True(t, removed) +} + +func usageRoot(t *testing.T, raw string) *yaml.Node { + t.Helper() + var node yaml.Node + require.NoError(t, yaml.Unmarshal([]byte(raw), &node)) + return &node +} + +func usageAt(t *testing.T, usage *schemaUsage, root *yaml.Node, ref string) schemaDirection { + t.Helper() + require.NotNil(t, usage) + w := &usageWalker{root: root.Content[0]} + target := w.resolve(ref) + require.NotNil(t, target, ref) + return usage.nodes[target] +} + +func TestBuildSchemaUsage_Directions(t *testing.T) { + root := usageRoot(t, `openapi: 3.2.0 +paths: + /a: + $ref: '#/components/pathItems/Shared' + /b: + parameters: + - {name: id, in: path, schema: {$ref: '#/components/schemas/PathParam'}} + summary: path level fields do not change the result + get: + responses: + '200': {content: {application/json: {schema: {$ref: '#/components/schemas/Out'}}}} + x-extra: {schema: {$ref: '#/components/schemas/Extra'}} + additionalOperations: + COPY: + requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/In'}}}} + servers: ~ + /c: not a path item + /d: + get: not an operation + /e: + get: {$ref: '#/x-operations/read'} + put: {$ref: '#/paths/~1e/put'} + post: {$ref: '#/x-operations/ping'} +x-operations: + ping: {$ref: '#/x-operations/pong'} + pong: {$ref: '#/x-operations/ping'} + read: + responses: + '200': {content: {application/json: {schema: {$ref: '#/components/schemas/ByOperationRef'}}}} +webhooks: + ping: + post: + requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Hook'}}}} +components: + pathItems: + Shared: + $ref: '#/components/pathItems/Loop' + Loop: + $ref: '#/components/pathItems/Shared' + put: + requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Shared%7EIn'}}}} + schemas: + PathParam: {type: string} + Out: + type: object + properties: + pet: {$ref: '#/components/schemas/Pet'} + tags: {type: array, items: [{$ref: '#/components/schemas/Out/properties/pet'}]} + Pet: + discriminator: + propertyName: kind + mapping: {cat: Cat, dog: '#/components/schemas/Dog'} + x-alias: &anchor {type: object} + x-again: *anchor + Cat: {type: object} + Dog: {type: object} + In: {type: object} + Shared~In: {type: object} + Extra: {type: object} + Hook: {type: object} + Unused: {type: object} + ByOperationRef: {type: object} +`) + usage := buildSchemaUsage(root) + assert.Equal(t, directionRequest, usageAt(t, usage, root, "#/components/schemas/PathParam")) + assert.Equal(t, directionResponse, usageAt(t, usage, root, "#/components/schemas/Out")) + assert.Equal(t, directionResponse, usageAt(t, usage, root, "#/components/schemas/Cat")) + assert.Equal(t, directionResponse, usageAt(t, usage, root, "#/components/schemas/Dog")) + assert.Equal(t, directionRequest, usageAt(t, usage, root, "#/components/schemas/In")) + assert.Equal(t, directionRequest, usageAt(t, usage, root, "#/components/schemas/Shared~0In")) + assert.Equal(t, directionBoth, usageAt(t, usage, root, "#/components/schemas/Extra")) + assert.Equal(t, directionBoth, usageAt(t, usage, root, "#/components/schemas/Hook")) + assert.Equal(t, schemaDirection(0), usageAt(t, usage, root, "#/components/schemas/Unused")) + assert.Equal(t, directionResponse, usageAt(t, usage, root, "#/components/schemas/ByOperationRef")) + assert.Equal(t, directionResponse, usageAt(t, usage, root, "#/components/schemas/Out/properties/tags/items/0")) +} + +func TestBuildSchemaUsage_GivesUp(t *testing.T) { + const spec = `openapi: 3.1.0 +paths: + /a: + get: + responses: + '200': {content: {application/json: {schema: %s}}} +components: + schemas: + Widget: {type: object} + Base: + discriminator: {propertyName: kind, mapping: {gone: Missing}} +` + for name, schema := range map[string]string{ + "external reference": `{$ref: 'other.yaml#/Widget'}`, + "missing reference": `{$ref: '#/components/schemas/Missing'}`, + "bad escape": `{$ref: '#/components/schemas/%zz'}`, + "bad array index": `{$ref: '#/components/schemas/Widget/allOf/x'}`, + "array index out of range": `{allOf: [{$ref: '#/paths/~1a/get/responses/200/content/application~1json/schema/allOf/9'}]}`, + "dynamic reference": `{$dynamicRef: '#node'}`, + "unresolved mapping": `{$ref: '#/components/schemas/Base'}`, + } { + t.Run(name, func(t *testing.T) { + assert.Nil(t, buildSchemaUsage(usageRoot(t, strings.Replace(spec, "%s", schema, 1)))) + }) + } + t.Run("external operation reference", func(t *testing.T) { + assert.Nil(t, buildSchemaUsage(usageRoot(t, "paths:\n /a:\n get: {$ref: 'operations/read.yaml'}\n"))) + }) + t.Run("missing path item reference", func(t *testing.T) { + assert.Nil(t, buildSchemaUsage(usageRoot(t, "paths:\n /a: {$ref: '#/components/pathItems/Missing'}\n"))) + }) +} + +func TestBuildSchemaUsage_DocumentShapes(t *testing.T) { + assert.Nil(t, buildSchemaUsage(nil)) + assert.Nil(t, buildSchemaUsage(usageRoot(t, "just a string"))) + assert.Nil(t, buildSchemaUsage(&yaml.Node{Kind: yaml.DocumentNode})) + + usage := buildSchemaUsage(usageRoot(t, "openapi: 3.1.0\npaths: not a map\nwebhooks: [nope]\n")) + require.NotNil(t, usage) + assert.Empty(t, usage.nodes) + + // discriminator values that are not mappings, and mappings with no mapping key, change nothing. + usage = buildSchemaUsage(usageRoot(t, `paths: + /a: + get: + responses: + '200': {content: {application/json: {schema: {discriminator: kind, x: {discriminator: {propertyName: kind}}}}}} +`)) + require.NotNil(t, usage) + assert.NotEmpty(t, usage.nodes) + + // a pointer through an alias resolves to the aliased node. + root := usageRoot(t, "a: &shared {b: {type: object}}\nc: *shared\n") + w := &usageWalker{root: root.Content[0]} + assert.NotNil(t, w.resolve("#/c/b")) + assert.Nil(t, w.resolve("#/a/b/type/x")) + assert.Nil(t, w.resolve("#")) +} + +func TestSchemaPairDirection(t *testing.T) { + direction, known := schemaPairDirection(nil, nil) + assert.False(t, known) + assert.Zero(t, direction) + + _, known = schemaPairDirection(&base.SchemaProxy{}, nil) + assert.False(t, known, "a proxy with no node has no usage") + + unregistered := buildSchemaProxyFromYAML(t, "type: object") + _, known = schemaPairDirection(nil, unregistered) + assert.False(t, known, "a proxy whose index has no usage record has no known direction") + + // Build a document, register its usage, and look up its schemas directly. + raw := usageSpec(usageResponseOnly, usageWidget("name")) + info, err := datamodel.ExtractSpecInfo([]byte(raw)) + require.NoError(t, err) + doc, err := v3.CreateDocumentFromConfig(info, datamodel.NewDocumentConfiguration()) + require.NoError(t, err) + forget := trackSchemaUsage(nil, doc.Index) + defer forget() + widget := doc.Components.Value.FindSchema("Widget").Value + direction, known = schemaPairDirection(widget, nil) + assert.True(t, known) + assert.Equal(t, directionResponse, direction) + direction, known = schemaPairDirection(widget, unregistered) + assert.False(t, known) + assert.Zero(t, direction) +} + +func TestTrackSchemaUsage_SkipsUnknownDocuments(t *testing.T) { + idx := index.NewSpecIndexWithConfig(usageRoot(t, "paths:\n /a: {$ref: 'other.yaml'}\n"), index.CreateClosedAPIIndexConfig()) + forget := trackSchemaUsage(idx) + schemaUsageMu.RLock() + _, stored := schemaUsageByIndex[idx] + schemaUsageMu.RUnlock() + assert.False(t, stored) + forget() +} + +func TestRequiredChangeBreaking_DirectionFromProxies(t *testing.T) { + low.ClearHashCache() + raw := usageSpec(usageRequestOnly, usageWidget("name")) + info, err := datamodel.ExtractSpecInfo([]byte(raw)) + require.NoError(t, err) + doc, err := v3.CreateDocumentFromConfig(info, datamodel.NewDocumentConfiguration()) + require.NoError(t, err) + defer trackSchemaUsage(doc.Index)() + widget := doc.Components.Value.FindSchema("Widget").Value + added, removed := requiredChangeBreaking(widget, widget) + assert.True(t, added) + assert.False(t, removed) +} + +func TestTrackSchemaUsage_SharedDocument(t *testing.T) { + // Two comparisons that share a document keep its usage until both finish. + info, err := datamodel.ExtractSpecInfo([]byte(usageSpec(usageResponseOnly, usageWidget("name")))) + require.NoError(t, err) + doc, err := v3.CreateDocumentFromConfig(info, datamodel.NewDocumentConfiguration()) + require.NoError(t, err) + widget := doc.Components.Value.FindSchema("Widget").Value + + first := trackSchemaUsage(doc.Index) + second := trackSchemaUsage(doc.Index, doc.Index) + first() + _, known := schemaPairDirection(widget, nil) + assert.True(t, known) + second() + _, known = schemaPairDirection(widget, nil) + assert.False(t, known) +}