specshield 3.5.0 → 3.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +55 -0
- package/README.md +95 -2
- package/package.json +1 -1
- package/src/cli.js +4 -0
- package/src/commands/gate.js +13 -0
- package/src/commands/prove.js +149 -0
- package/src/commands/replay.js +195 -0
- package/src/core/configLoader.js +5 -2
- package/src/core/gate/runGate.js +10 -1
- package/src/core/prove/contract.js +241 -0
- package/src/core/prove/execute.js +135 -0
- package/src/core/prove/http.js +104 -0
- package/src/core/prove/index.js +84 -0
- package/src/core/prove/instance.js +400 -0
- package/src/core/prove/relate.js +23 -0
- package/src/core/prove/render.js +169 -0
- package/src/core/prove/repair.js +109 -0
- package/src/core/prove/schema.js +261 -0
- package/src/core/prove/subschema.js +257 -0
- package/src/core/prove/witness.js +702 -0
- package/src/core/replay/runReplay.js +169 -0
- package/src/core/replay/shape.js +100 -0
- package/src/core/replay/traffic.js +168 -0
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Isolation: make an instance satisfy two schemas at once everywhere except
|
|
5
|
+
* one protected location.
|
|
6
|
+
*
|
|
7
|
+
* A spec change rarely comes alone — the same body may gain a required field,
|
|
8
|
+
* change a type and drop another field in one release. A witness built for one
|
|
9
|
+
* of those changes would trip over the others, and "it fails" would prove
|
|
10
|
+
* nothing about the change it is meant to show. So before a witness is judged,
|
|
11
|
+
* every other part of it is repaired until both the old and the new schema
|
|
12
|
+
* accept it; only the protected location is left alone. A repair that the
|
|
13
|
+
* accepting schema rejects is undone, so the witness stays valid on its side.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const S = require('./schema');
|
|
17
|
+
const { generate } = require('./instance');
|
|
18
|
+
const { relatesTo } = require('./relate');
|
|
19
|
+
|
|
20
|
+
const VALUE_KEYWORDS = new Set([
|
|
21
|
+
'type', 'enum', 'const', 'format', 'pattern', 'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum',
|
|
22
|
+
'multipleOf', 'minLength', 'maxLength', 'minItems', 'maxItems', 'uniqueItems', 'oneOf', 'anyOf', 'minProperties',
|
|
23
|
+
]);
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* @param value the instance (from the accepting side, A)
|
|
27
|
+
* @param a { doc, schema } — must keep accepting the result
|
|
28
|
+
* @param b { doc, schema } — repaired towards
|
|
29
|
+
* @param protect diff-engine steps of the location to leave alone, or null
|
|
30
|
+
* @param side 'request' | 'response'
|
|
31
|
+
* @returns the repaired instance (unchanged when nothing could be repaired)
|
|
32
|
+
*/
|
|
33
|
+
function coSatisfy(value, { a, b, protect = null, side = 'request', cfg = {} }) {
|
|
34
|
+
if (value === undefined || !b || !b.schema) return value;
|
|
35
|
+
const at = protect ? S.instancePath(protect) : null;
|
|
36
|
+
const isProtected = (e) => Boolean(protect) && relatesTo([e], protect);
|
|
37
|
+
const validA = S.validator(a.doc, a.schema, { side });
|
|
38
|
+
const validB = S.validator(b.doc, b.schema, { side });
|
|
39
|
+
let x = clone(value);
|
|
40
|
+
for (let pass = 0; pass < 6; pass++) {
|
|
41
|
+
const rb = validB(x);
|
|
42
|
+
if (rb.ok) return x;
|
|
43
|
+
let changed = false;
|
|
44
|
+
for (const e of rb.errors) {
|
|
45
|
+
if (isProtected(e)) continue;
|
|
46
|
+
const fix = proposal(e, b, side, cfg);
|
|
47
|
+
if (!fix || (at !== null && overlaps(fix.pointer, at))) continue;
|
|
48
|
+
const y = apply(x, fix);
|
|
49
|
+
if (y === undefined || same(x, y)) continue;
|
|
50
|
+
if (!validA(y).ok) continue;
|
|
51
|
+
x = y;
|
|
52
|
+
changed = true;
|
|
53
|
+
}
|
|
54
|
+
if (!changed) break;
|
|
55
|
+
}
|
|
56
|
+
return x;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function proposal(e, b, side, cfg) {
|
|
60
|
+
if (e.keyword === 'required' && e.params.missingProperty !== undefined) {
|
|
61
|
+
const pointer = `${e.path}/${esc(e.params.missingProperty)}`;
|
|
62
|
+
const node = S.nodeAtPointer(b.doc, b.schema, pointer);
|
|
63
|
+
return { op: 'set', pointer, value: node ? generate(b.doc, node, { side, ...cfg }) : 'abc' };
|
|
64
|
+
}
|
|
65
|
+
if (e.keyword === 'additionalProperties' && e.params.additionalProperty !== undefined) {
|
|
66
|
+
return { op: 'delete', pointer: `${e.path}/${esc(e.params.additionalProperty)}` };
|
|
67
|
+
}
|
|
68
|
+
if (VALUE_KEYWORDS.has(e.keyword)) {
|
|
69
|
+
const node = S.nodeAtPointer(b.doc, b.schema, e.path);
|
|
70
|
+
if (!node) return null;
|
|
71
|
+
return { op: 'set', pointer: e.path, value: generate(b.doc, node, { side, ...cfg }) };
|
|
72
|
+
}
|
|
73
|
+
return null;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** A fix may not replace the protected value, anything containing it, or anything inside it. */
|
|
77
|
+
function overlaps(pointer, at) {
|
|
78
|
+
return pointer === at || at.startsWith(pointer + '/') || pointer === '' || pointer.startsWith(at + '/');
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function apply(x, { op, pointer, value }) {
|
|
82
|
+
if (pointer === '') return op === 'set' ? clone(value) : undefined;
|
|
83
|
+
const root = clone(x);
|
|
84
|
+
const parts = pointer.split('/').slice(1).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
|
|
85
|
+
let cur = root;
|
|
86
|
+
for (const k of parts.slice(0, -1)) {
|
|
87
|
+
if (cur === null || typeof cur !== 'object' || !(k in cur)) return undefined;
|
|
88
|
+
cur = cur[k];
|
|
89
|
+
}
|
|
90
|
+
if (cur === null || typeof cur !== 'object') return undefined;
|
|
91
|
+
const last = parts[parts.length - 1];
|
|
92
|
+
if (op === 'delete') delete cur[last];
|
|
93
|
+
else cur[last] = clone(value);
|
|
94
|
+
return root;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function esc(s) {
|
|
98
|
+
return String(s).replace(/~/g, '~0').replace(/\//g, '~1');
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function clone(v) {
|
|
102
|
+
return v === undefined || v === null || typeof v !== 'object' ? v : JSON.parse(JSON.stringify(v));
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function same(a, b) {
|
|
106
|
+
return JSON.stringify(a) === JSON.stringify(b);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
module.exports = { coSatisfy };
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Schema plumbing for witnesses: following $refs inside a raw (un-normalized)
|
|
5
|
+
* spec document, flattening allOf, walking the diff engine's field steps, and
|
|
6
|
+
* validating instances with ajv against the document's own schemas.
|
|
7
|
+
*
|
|
8
|
+
* Validation runs against the spec as written — $refs stay $refs, resolved by
|
|
9
|
+
* ajv against the document's components — so a witness is checked against the
|
|
10
|
+
* real contract, not a simplified copy of it.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const Ajv = require('ajv').default;
|
|
14
|
+
const addFormats = require('ajv-formats');
|
|
15
|
+
const L = require('../fix/locate');
|
|
16
|
+
|
|
17
|
+
// inlineRefs: false compiles each referenced component once, as its own
|
|
18
|
+
// function, instead of inlining it into every schema that mentions it — on a
|
|
19
|
+
// spec like Stripe's (thousands of mutually-referencing schemas) the difference
|
|
20
|
+
// between seconds and hours.
|
|
21
|
+
const OPTIONS = { strict: false, allErrors: true, validateFormats: true, logger: false, inlineRefs: false };
|
|
22
|
+
const bodyAjv = addFormats(new Ajv({ ...OPTIONS, coerceTypes: false }));
|
|
23
|
+
// Parameters arrive as strings ("?limit=10"); servers parse them into the
|
|
24
|
+
// declared type, so a parameter validates the way a server would read it.
|
|
25
|
+
const paramAjv = addFormats(new Ajv({ ...OPTIONS, coerceTypes: 'array' }));
|
|
26
|
+
|
|
27
|
+
const ANNOTATIONS = new Set(['example', 'examples', 'xml', 'discriminator', 'readOnly', 'writeOnly', 'deprecated', 'externalDocs', 'nullable', '$schema', '$id', 'x-nullable']);
|
|
28
|
+
|
|
29
|
+
function deref(doc, node, depth = 0) {
|
|
30
|
+
let cur = node;
|
|
31
|
+
for (let i = 0; cur && typeof cur === 'object' && typeof cur.$ref === 'string' && i < 20; i++) {
|
|
32
|
+
const ptr = L.refToPtr(cur.$ref);
|
|
33
|
+
if (!ptr) return null; // external ref
|
|
34
|
+
cur = L.get(doc, ptr);
|
|
35
|
+
}
|
|
36
|
+
return cur && typeof cur === 'object' ? cur : null;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The schema with $refs followed and allOf merged into one node — the shape a
|
|
41
|
+
* generator or a reader cares about. Constraints of every part are kept (the
|
|
42
|
+
* last part wins on a conflict, which ajv's own check then catches).
|
|
43
|
+
*/
|
|
44
|
+
function effective(doc, node, depth = 0) {
|
|
45
|
+
const s = deref(doc, node);
|
|
46
|
+
if (!s || depth > 12) return s;
|
|
47
|
+
if (!Array.isArray(s.allOf)) return s;
|
|
48
|
+
const out = { ...s, properties: { ...(s.properties || {}) }, required: [...(s.required || [])] };
|
|
49
|
+
delete out.allOf;
|
|
50
|
+
for (const part of s.allOf) {
|
|
51
|
+
const p = effective(doc, part, depth + 1);
|
|
52
|
+
if (!p) continue;
|
|
53
|
+
for (const [k, v] of Object.entries(p)) {
|
|
54
|
+
if (k === 'properties') Object.assign(out.properties, v);
|
|
55
|
+
else if (k === 'required') out.required.push(...v);
|
|
56
|
+
else if (!(k in out) || k === 'type') out[k] = v;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
if (Object.keys(out.properties).length === 0) delete out.properties;
|
|
60
|
+
if (out.required.length === 0) delete out.required;
|
|
61
|
+
return out;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** The type a schema declares, ignoring "null" (OpenAPI 3.1 nullable). */
|
|
65
|
+
function typeOf(s) {
|
|
66
|
+
if (!s) return null;
|
|
67
|
+
if (Array.isArray(s.type)) return s.type.find((t) => t !== 'null') || null;
|
|
68
|
+
if (s.type) return s.type;
|
|
69
|
+
if (s.properties || s.additionalProperties) return 'object';
|
|
70
|
+
if (s.items) return 'array';
|
|
71
|
+
return null;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function nullable(s) {
|
|
75
|
+
return Boolean(s && (s.nullable === true || s['x-nullable'] === true || (Array.isArray(s.type) && s.type.includes('null'))));
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Walks diff-engine steps ({prop}, {items}, {map}, {variant, index}) from a
|
|
80
|
+
* schema node. Returns the (un-dereferenced) node at the end, or null.
|
|
81
|
+
*/
|
|
82
|
+
function nodeAt(doc, node, steps) {
|
|
83
|
+
let cur = node;
|
|
84
|
+
for (const step of steps) {
|
|
85
|
+
const s = effective(doc, cur);
|
|
86
|
+
if (!s) return null;
|
|
87
|
+
if (step.prop !== undefined) cur = s.properties && s.properties[step.prop];
|
|
88
|
+
else if (step.items) cur = s.items;
|
|
89
|
+
else if (step.map) cur = s.additionalProperties && typeof s.additionalProperties === 'object' ? s.additionalProperties : null;
|
|
90
|
+
else cur = Array.isArray(s[step.variant]) ? s[step.variant][step.index] : null;
|
|
91
|
+
if (!cur) return null;
|
|
92
|
+
}
|
|
93
|
+
return cur;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* The schema node that governs the value at a JSON pointer of an instance
|
|
98
|
+
* ("/items/0/tag"), or null. Array indexes go to `items`, unknown keys to
|
|
99
|
+
* additionalProperties, and a oneOf/anyOf branch that declares the key wins.
|
|
100
|
+
*/
|
|
101
|
+
function nodeAtPointer(doc, root, pointer) {
|
|
102
|
+
let cur = root;
|
|
103
|
+
for (const raw of pointer.split('/').slice(1)) {
|
|
104
|
+
const seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
|
|
105
|
+
const s = effective(doc, cur);
|
|
106
|
+
if (!s) return null;
|
|
107
|
+
if (s.properties && s.properties[seg]) { cur = s.properties[seg]; continue; }
|
|
108
|
+
if (/^\d+$/.test(seg) && s.items) { cur = s.items; continue; }
|
|
109
|
+
if (s.additionalProperties && typeof s.additionalProperties === 'object') { cur = s.additionalProperties; continue; }
|
|
110
|
+
const branch = (s.oneOf || s.anyOf || []).map((v) => effective(doc, v)).find((v) => v && v.properties && v.properties[seg]);
|
|
111
|
+
if (!branch) return null;
|
|
112
|
+
cur = branch.properties[seg];
|
|
113
|
+
}
|
|
114
|
+
return cur;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Steps → the JSON pointer of the value they name in an instance ("/items/0/tag"). */
|
|
118
|
+
function instancePath(steps) {
|
|
119
|
+
let p = '';
|
|
120
|
+
for (const s of steps) {
|
|
121
|
+
if (s.prop !== undefined) p += '/' + String(s.prop).replace(/~/g, '~0').replace(/\//g, '~1');
|
|
122
|
+
else if (s.items) p += '/0';
|
|
123
|
+
else if (s.map) p += '/key';
|
|
124
|
+
}
|
|
125
|
+
return p;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
// ─── OpenAPI → JSON Schema ──────────────────────────────────────────────────
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Rewrites OpenAPI-isms so ajv validates what the spec means:
|
|
132
|
+
* nullable / x-nullable → type also allows null
|
|
133
|
+
* exclusiveMinimum: true (3.0) → JSON Schema's numeric form
|
|
134
|
+
* readOnly properties → not required in a request
|
|
135
|
+
* writeOnly properties → not required in a response
|
|
136
|
+
* annotations, $schema, $id → dropped
|
|
137
|
+
*/
|
|
138
|
+
function convert(doc, node, side, depth = 0, base = '') {
|
|
139
|
+
if (node === null || typeof node !== 'object' || depth > 200) return node;
|
|
140
|
+
if (Array.isArray(node)) return node.map((n) => convert(doc, n, side, depth + 1, base));
|
|
141
|
+
|
|
142
|
+
const out = {};
|
|
143
|
+
for (const [k, v] of Object.entries(node)) {
|
|
144
|
+
if (ANNOTATIONS.has(k) || k.startsWith('x-')) continue;
|
|
145
|
+
if (k === 'properties' && v && typeof v === 'object') {
|
|
146
|
+
out.properties = {};
|
|
147
|
+
for (const [name, p] of Object.entries(v)) out.properties[name] = convert(doc, p, side, depth + 1, base);
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
if (k === 'type' && v === 'file') continue; // Swagger 2.0 upload
|
|
151
|
+
if (k === '$ref' && typeof v === 'string' && base && v.startsWith('#/')) { out.$ref = base + v; continue; }
|
|
152
|
+
out[k] = convert(doc, v, side, depth + 1, base);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
if (nullable(node) && out.type && !Array.isArray(out.type)) out.type = [out.type, 'null'];
|
|
156
|
+
if (nullable(node) && Array.isArray(out.enum) && !out.enum.includes(null)) out.enum = [...out.enum, null];
|
|
157
|
+
for (const [ex, bound] of [['exclusiveMinimum', 'minimum'], ['exclusiveMaximum', 'maximum']]) {
|
|
158
|
+
if (out[ex] === true && typeof out[bound] === 'number') { out[ex] = out[bound]; delete out[bound]; } else if (typeof out[ex] === 'boolean') delete out[ex];
|
|
159
|
+
}
|
|
160
|
+
if (Array.isArray(node.required) && node.properties) {
|
|
161
|
+
const skip = side === 'request' ? 'readOnly' : 'writeOnly';
|
|
162
|
+
out.required = node.required.filter((name) => {
|
|
163
|
+
const p = deref(doc, node.properties[name]);
|
|
164
|
+
return !(p && p[skip] === true);
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
return out;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// Each document's reusable schemas are registered once per ajv instance and
|
|
171
|
+
// side, under an id of their own; a validator's $refs point there.
|
|
172
|
+
let docSeq = 0;
|
|
173
|
+
const docIds = new WeakMap();
|
|
174
|
+
const registered = new WeakMap();
|
|
175
|
+
|
|
176
|
+
function docBase(ajv, doc, side) {
|
|
177
|
+
let id = docIds.get(doc);
|
|
178
|
+
if (!id) { id = `specshield://doc/${++docSeq}`; docIds.set(doc, id); }
|
|
179
|
+
const uri = `${id}/${side}`;
|
|
180
|
+
let set = registered.get(ajv);
|
|
181
|
+
if (!set) { set = new Set(); registered.set(ajv, set); }
|
|
182
|
+
if (!set.has(uri)) {
|
|
183
|
+
ajv.addSchema({
|
|
184
|
+
$id: uri,
|
|
185
|
+
components: { schemas: convert(doc, (doc.components && doc.components.schemas) || {}, side) },
|
|
186
|
+
definitions: convert(doc, doc.definitions || {}, side),
|
|
187
|
+
});
|
|
188
|
+
set.add(uri);
|
|
189
|
+
}
|
|
190
|
+
return uri;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
const compiled = { body: new WeakMap(), param: new WeakMap() };
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* A validator for `schema` (a node of `doc`). `kind` 'param' parses string
|
|
197
|
+
* values the way a server reads a query/path/header parameter.
|
|
198
|
+
* Returns (value) → { ok, errors: [{ path, keyword, message, params }] }.
|
|
199
|
+
*/
|
|
200
|
+
function validator(doc, schema, { side = 'request', kind = 'body' } = {}) {
|
|
201
|
+
if (!schema || typeof schema !== 'object') return () => ({ ok: true, errors: [] });
|
|
202
|
+
const cache = compiled[kind];
|
|
203
|
+
let bySide = cache.get(schema);
|
|
204
|
+
if (!bySide) { bySide = {}; cache.set(schema, bySide); }
|
|
205
|
+
if (!bySide[side]) {
|
|
206
|
+
let fn;
|
|
207
|
+
try {
|
|
208
|
+
const ajv = kind === 'param' ? paramAjv : bodyAjv;
|
|
209
|
+
fn = ajv.compile(convert(doc, schema, side, 0, docBase(ajv, doc, side)));
|
|
210
|
+
} catch (err) {
|
|
211
|
+
const message = `the spec's schema can't be compiled: ${err.message}`;
|
|
212
|
+
fn = null;
|
|
213
|
+
bySide[side] = () => ({ ok: false, invalidSchema: true, errors: [{ path: '', keyword: 'schema', message, params: {} }] });
|
|
214
|
+
}
|
|
215
|
+
if (fn) {
|
|
216
|
+
bySide[side] = (value) => {
|
|
217
|
+
const copy = value === undefined ? undefined : JSON.parse(JSON.stringify(value));
|
|
218
|
+
if (fn(copy)) return { ok: true, errors: [] };
|
|
219
|
+
return { ok: false, errors: dedupe((fn.errors || []).map((e) => ({ path: e.instancePath || '', keyword: e.keyword, message: e.message, params: e.params || {}, schemaPath: e.schemaPath || '' }))) };
|
|
220
|
+
};
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
return bySide[side];
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* ajv reports every failed branch of a oneOf/anyOf next to the union's own
|
|
228
|
+
* error. Keep the union's error and drop its branches' at the same place; keep
|
|
229
|
+
* each remaining distinct message once.
|
|
230
|
+
*/
|
|
231
|
+
function dedupe(errors) {
|
|
232
|
+
// ajv's schemaPath restarts inside a $ref'd branch, so match by instance
|
|
233
|
+
// location: anything at or below a failed union is that union's detail.
|
|
234
|
+
const unions = errors.filter((e) => e.keyword === 'oneOf' || e.keyword === 'anyOf');
|
|
235
|
+
const inBranch = (e) => unions.some((u) => e.path === u.path || e.path.startsWith(`${u.path}/`));
|
|
236
|
+
const seen = new Set();
|
|
237
|
+
const out = [];
|
|
238
|
+
for (const e of errors) {
|
|
239
|
+
if (e.keyword === 'allOf' || e.keyword === 'if') continue;
|
|
240
|
+
if (e.keyword !== 'oneOf' && e.keyword !== 'anyOf' && inBranch(e)) continue;
|
|
241
|
+
const key = `${e.path}|${e.keyword}|${e.message}`;
|
|
242
|
+
if (!seen.has(key)) { seen.add(key); out.push(e); }
|
|
243
|
+
}
|
|
244
|
+
return out;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** "/items/0/tag must be integer" — an ajv error the way a person reads it. */
|
|
248
|
+
function describeError(e, root = 'body') {
|
|
249
|
+
const where = e.path ? `${root}${e.path.replace(/\/(\d+)(?=\/|$)/g, '[$1]').replace(/\//g, '.')}` : root;
|
|
250
|
+
if (e.keyword === 'required') return `${where} is missing required field "${e.params.missingProperty}"`;
|
|
251
|
+
if (e.keyword === 'enum') return `${where} must be one of ${JSON.stringify(e.params.allowedValues)}`;
|
|
252
|
+
if (e.keyword === 'additionalProperties') return `${where} has a field the spec doesn't allow: "${e.params.additionalProperty}"`;
|
|
253
|
+
if (e.keyword === 'type') return `${where} must be ${e.params.type}`;
|
|
254
|
+
if (e.keyword === 'oneOf' || e.keyword === 'anyOf') {
|
|
255
|
+
return e.params && Array.isArray(e.params.passingSchemas) ? `${where} matches more than one allowed form` : `${where} matches none of the allowed forms`;
|
|
256
|
+
}
|
|
257
|
+
if (e.keyword === 'schema') return e.message;
|
|
258
|
+
return `${where} ${e.message}`;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
module.exports = { deref, effective, typeOf, nullable, nodeAt, nodeAtPointer, instancePath, convert, validator, describeError };
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A sound, incomplete subschema check: `widens(from, to)` returns true only
|
|
5
|
+
* when every instance `from` accepts is also accepted by `to`. When it can't
|
|
6
|
+
* tell — composition it doesn't model, a keyword it doesn't know — it answers
|
|
7
|
+
* false. So "true" is a proof of compatibility; "false" proves nothing.
|
|
8
|
+
*
|
|
9
|
+
* Deciding inclusion between JSON Schemas in general is hard (Habib et al.,
|
|
10
|
+
* "Finding Data Compatibility Bugs with JSON Subschema Checking", ISSTA 2021);
|
|
11
|
+
* this covers the shapes API changes are made of: properties added or made
|
|
12
|
+
* optional, enums extended, bounds relaxed, types widened, a union gaining a
|
|
13
|
+
* branch, branches reordered.
|
|
14
|
+
*
|
|
15
|
+
* Schemas are compared where they live — $refs followed on demand, each pair
|
|
16
|
+
* of nodes visited once. Recursive schemas are handled coinductively: a pair
|
|
17
|
+
* already being compared is assumed to widen, the standard sound rule for
|
|
18
|
+
* recursive types (it proves inclusion for every instance, finite or not).
|
|
19
|
+
*
|
|
20
|
+
* One assumption, the one every API-compatibility check makes: a closed world.
|
|
21
|
+
* An instance carries only the properties its schema declares — a client
|
|
22
|
+
* doesn't send fields the old spec never mentioned. Without it, declaring any
|
|
23
|
+
* new optional property would count as narrowing (an undeclared field could
|
|
24
|
+
* have held anything). Pass { closedWorld: false } to drop the assumption.
|
|
25
|
+
*
|
|
26
|
+
* A side is { doc, node }: a schema node and the document its $refs resolve in.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
const S = require('./schema');
|
|
30
|
+
|
|
31
|
+
const ANNOTATION = /^(description|title|example|examples|externalDocs|deprecated|readOnly|writeOnly|xml|discriminator|default|\$schema|\$id|x-.*)$/;
|
|
32
|
+
// Numeric formats as ranges: float/double add nothing to a JSON number, int64
|
|
33
|
+
// covers every integer JSON carries exactly; int32 is the only real bound.
|
|
34
|
+
const NUMERIC_WIDTH = { int32: 1, int64: 2, float: 3, double: 3 };
|
|
35
|
+
|
|
36
|
+
let seq = 0;
|
|
37
|
+
const ids = new WeakMap();
|
|
38
|
+
const effCache = new WeakMap();
|
|
39
|
+
|
|
40
|
+
function id(o) {
|
|
41
|
+
let n = ids.get(o);
|
|
42
|
+
if (!n) { n = ++seq; ids.set(o, n); }
|
|
43
|
+
return n;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** $refs followed and allOf merged, with a stable identity per node. */
|
|
47
|
+
function eff(doc, node) {
|
|
48
|
+
if (node === true || node === false) return node;
|
|
49
|
+
if (!node || typeof node !== 'object') return null;
|
|
50
|
+
let byDoc = effCache.get(node);
|
|
51
|
+
if (!byDoc) { byDoc = new WeakMap(); effCache.set(node, byDoc); }
|
|
52
|
+
if (!byDoc.has(doc)) byDoc.set(doc, S.effective(doc, node));
|
|
53
|
+
return byDoc.get(doc);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function widens(from, to, opts = { closedWorld: true }) {
|
|
57
|
+
return check(from.doc, from.node, to.doc, to.node, { closedWorld: opts.closedWorld !== false, memo: new Map() });
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function check(fd, fn, td, tn, ctx) {
|
|
61
|
+
const f = eff(fd, fn);
|
|
62
|
+
const t = eff(td, tn);
|
|
63
|
+
if (t === true || (isObj(t) && meaningful(t).length === 0)) return true; // {} accepts everything
|
|
64
|
+
if (f === false) return true;
|
|
65
|
+
if (!isObj(f) || !isObj(t)) return false;
|
|
66
|
+
const key = `${id(f)}|${id(t)}`;
|
|
67
|
+
if (ctx.memo.has(key)) return ctx.memo.get(key);
|
|
68
|
+
ctx.memo.set(key, true); // coinductive assumption
|
|
69
|
+
const r = compare(fd, f, td, t, ctx);
|
|
70
|
+
ctx.memo.set(key, r);
|
|
71
|
+
return r;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function compare(fd, f, td, t, ctx) {
|
|
75
|
+
const fu = union(f);
|
|
76
|
+
const tu = union(t);
|
|
77
|
+
|
|
78
|
+
// A union on the accepting side: enough that one branch takes all of `from`.
|
|
79
|
+
if (tu && onlyKeys(t, tu.kind) && !fu) {
|
|
80
|
+
if (tu.kind === 'oneOf' && !disjointTypes(td, tu.branches)) return false;
|
|
81
|
+
return tu.branches.some((b) => check(fd, f, td, b, ctx));
|
|
82
|
+
}
|
|
83
|
+
// Unions on both sides: every branch of `from` must land in a branch of `to`.
|
|
84
|
+
if (fu && tu && onlyKeys(f, fu.kind) && onlyKeys(t, tu.kind)) {
|
|
85
|
+
if (tu.kind === 'oneOf' && !disjointTypes(td, tu.branches)) return false;
|
|
86
|
+
return fu.branches.every((fb) => tu.branches.some((tb) => check(fd, fb, td, tb, ctx)));
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
const keys = new Set([...meaningful(f), ...meaningful(t)]);
|
|
90
|
+
for (const k of keys) {
|
|
91
|
+
const a = f[k];
|
|
92
|
+
const b = t[k];
|
|
93
|
+
switch (k) {
|
|
94
|
+
case 'type':
|
|
95
|
+
if (!typeWidens(a, b, f)) return false;
|
|
96
|
+
break;
|
|
97
|
+
case 'nullable':
|
|
98
|
+
if (a === true && b !== true) return false;
|
|
99
|
+
break;
|
|
100
|
+
case 'format':
|
|
101
|
+
if (!formatWidens(a, b, f)) return false;
|
|
102
|
+
break;
|
|
103
|
+
case 'pattern': case 'const': case 'multipleOf': case 'uniqueItems':
|
|
104
|
+
if (b !== undefined && !same(a, b)) return false;
|
|
105
|
+
break;
|
|
106
|
+
case 'enum':
|
|
107
|
+
if (b !== undefined && (!Array.isArray(a) || !a.every((v) => b.some((x) => same(x, v))))) return false;
|
|
108
|
+
break;
|
|
109
|
+
case 'minimum': case 'minLength': case 'minItems': case 'minProperties': case 'exclusiveMinimum':
|
|
110
|
+
if (b !== undefined && !(typeof a === typeof b && a >= b)) return false;
|
|
111
|
+
break;
|
|
112
|
+
case 'maximum': case 'maxLength': case 'maxItems': case 'maxProperties': case 'exclusiveMaximum':
|
|
113
|
+
if (b !== undefined && !(typeof a === typeof b && a <= b)) return false;
|
|
114
|
+
break;
|
|
115
|
+
case 'required':
|
|
116
|
+
if (b !== undefined && !b.every((name) => (a || []).includes(name))) return false;
|
|
117
|
+
break;
|
|
118
|
+
case 'items':
|
|
119
|
+
if (b !== undefined && !(a !== undefined && check(fd, a, td, b, ctx))) return false;
|
|
120
|
+
break;
|
|
121
|
+
case 'properties':
|
|
122
|
+
if (!propertiesWiden(fd, f, td, t, ctx)) return false;
|
|
123
|
+
break;
|
|
124
|
+
case 'additionalProperties':
|
|
125
|
+
if (!additionalWidens(fd, f, td, t, ctx)) return false;
|
|
126
|
+
break;
|
|
127
|
+
case 'oneOf': case 'anyOf':
|
|
128
|
+
// A union next to other keywords: only when the two unions match branch for branch.
|
|
129
|
+
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.every((x, i) => check(fd, x, td, b[i], ctx))) return false;
|
|
130
|
+
break;
|
|
131
|
+
default:
|
|
132
|
+
// anything else (not, if/then, patternProperties, …): only when identical
|
|
133
|
+
if (!same(a, b)) return false;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return true;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function union(s) {
|
|
140
|
+
if (Array.isArray(s.anyOf)) return { kind: 'anyOf', branches: s.anyOf };
|
|
141
|
+
if (Array.isArray(s.oneOf)) return { kind: 'oneOf', branches: s.oneOf };
|
|
142
|
+
return null;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
function typeWidens(a, b, f) {
|
|
146
|
+
if (b === undefined) return true;
|
|
147
|
+
const fs = a === undefined ? (f.properties ? ['object'] : null) : [].concat(a);
|
|
148
|
+
if (!fs) return false;
|
|
149
|
+
const ts = [].concat(b);
|
|
150
|
+
return fs.every((x) => ts.includes(x) || (x === 'integer' && ts.includes('number')));
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function formatWidens(a, b, f) {
|
|
154
|
+
if (b === undefined || a === b) return true;
|
|
155
|
+
const types = [].concat(f.type || []);
|
|
156
|
+
const numeric = types.length > 0 && types.every((x) => x === 'integer' || x === 'number' || x === 'null');
|
|
157
|
+
if (!numeric || !(b in NUMERIC_WIDTH) || (a !== undefined && !(a in NUMERIC_WIDTH))) return false;
|
|
158
|
+
return b !== 'int32' || a === 'int32';
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** Every property `from` allows must be allowed by `to`, at least as loosely. */
|
|
162
|
+
function propertiesWiden(fd, f, td, t, ctx) {
|
|
163
|
+
const fp = f.properties || {};
|
|
164
|
+
const tp = t.properties || {};
|
|
165
|
+
for (const [name, a] of Object.entries(fp)) {
|
|
166
|
+
if (tp[name] !== undefined) {
|
|
167
|
+
if (!check(fd, a, td, tp[name], ctx)) return false;
|
|
168
|
+
} else if (t.additionalProperties === false) {
|
|
169
|
+
return false;
|
|
170
|
+
} else if (isObj(t.additionalProperties) && !check(fd, a, td, t.additionalProperties, ctx)) {
|
|
171
|
+
return false;
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
// Properties only `to` declares: in a closed world `from`'s instances never
|
|
175
|
+
// carry them; otherwise `from` must not have let arbitrary values through.
|
|
176
|
+
if (ctx.closedWorld) return true;
|
|
177
|
+
for (const [name, b] of Object.entries(tp)) {
|
|
178
|
+
if (fp[name] !== undefined || f.additionalProperties === false) continue;
|
|
179
|
+
if (isObj(f.additionalProperties) ? !check(fd, f.additionalProperties, td, b, ctx) : !acceptsAll(eff(td, b))) return false;
|
|
180
|
+
}
|
|
181
|
+
return true;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
function additionalWidens(fd, f, td, t, ctx) {
|
|
185
|
+
const a = f.additionalProperties;
|
|
186
|
+
const b = t.additionalProperties;
|
|
187
|
+
if (b === undefined || b === true || (isObj(b) && meaningful(b).length === 0)) return true;
|
|
188
|
+
if (a === false) return true;
|
|
189
|
+
if (b === false) return ctx.closedWorld; // closed world: nothing undeclared is sent
|
|
190
|
+
return isObj(a) && check(fd, a, td, b, ctx);
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function acceptsAll(s) {
|
|
194
|
+
return s === true || (isObj(s) && meaningful(s).length === 0);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/** Branches a oneOf can't both match: distinct JSON types. */
|
|
198
|
+
function disjointTypes(doc, branches) {
|
|
199
|
+
const seen = new Set();
|
|
200
|
+
for (const b of branches) {
|
|
201
|
+
const s = eff(doc, b);
|
|
202
|
+
if (!isObj(s) || s.type === undefined || Array.isArray(s.type)) return false;
|
|
203
|
+
const t = s.type === 'integer' ? 'number' : s.type;
|
|
204
|
+
if (seen.has(t)) return false;
|
|
205
|
+
seen.add(t);
|
|
206
|
+
}
|
|
207
|
+
return true;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Can an instance of `branch` (which pins a required property to one value)
|
|
212
|
+
* also match another branch of a oneOf? Not when every other branch requires
|
|
213
|
+
* that property with values that leave it out — the usual discriminated union.
|
|
214
|
+
*/
|
|
215
|
+
function exclusiveIn(doc, branch, others) {
|
|
216
|
+
const b = eff(doc, branch);
|
|
217
|
+
if (!isObj(b)) return false;
|
|
218
|
+
const req = new Set(b.required || []);
|
|
219
|
+
for (const [prop, raw] of Object.entries(b.properties || {})) {
|
|
220
|
+
const ps = eff(doc, raw);
|
|
221
|
+
if (!req.has(prop) || !isObj(ps)) continue;
|
|
222
|
+
const pinned = ps.const !== undefined ? ps.const : Array.isArray(ps.enum) && ps.enum.length === 1 ? ps.enum[0] : undefined;
|
|
223
|
+
if (pinned === undefined) continue;
|
|
224
|
+
const excluded = others.every((o) => {
|
|
225
|
+
const os = eff(doc, o);
|
|
226
|
+
const op = isObj(os) && os.properties && eff(doc, os.properties[prop]);
|
|
227
|
+
if (!isObj(op) || !(os.required || []).includes(prop)) return false;
|
|
228
|
+
const vals = op.const !== undefined ? [op.const] : op.enum;
|
|
229
|
+
return Array.isArray(vals) && !vals.some((v) => same(v, pinned));
|
|
230
|
+
});
|
|
231
|
+
if (excluded) return true;
|
|
232
|
+
}
|
|
233
|
+
return false;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/** Same meaning both ways — "unchanged" for reporting. */
|
|
237
|
+
function equivalent(a, b) {
|
|
238
|
+
return widens(a, b) && widens(b, a);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function meaningful(s) {
|
|
242
|
+
return Object.keys(s).filter((k) => !ANNOTATION.test(k));
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
function onlyKeys(s, key) {
|
|
246
|
+
return meaningful(s).every((k) => k === key);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
function isObj(v) {
|
|
250
|
+
return v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
function same(a, b) {
|
|
254
|
+
return JSON.stringify(a) === JSON.stringify(b);
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
module.exports = { widens, equivalent, exclusiveIn };
|