@squiz/dx-json-schema-lib 1.87.0 → 1.89.0

package/src/utils/jsonBreakDetector/checks/findStringConstraintNarrowing.ts

@@ -0,0 +1,139 @@
+import { BREAK_MESSAGES, JsonBreak, pushBreak } from '../types';
+import { JSONSchema } from '@squiz/json-schema-library';
+
+/** Recursively detects narrowed string constraints at each schema level, accumulating dotted paths. */
+export function findStringConstraintNarrowing(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  const beforeProperties = beforeSchema.properties ?? {};
+  const afterProperties = afterSchema.properties ?? {};
+
+  // Recurse into latest nested object properties.
+  for (const [key, afterPropertySchema] of Object.entries(afterProperties)) {
+    // Skip if the property is not an object.
+    if (!afterPropertySchema || typeof afterPropertySchema !== 'object') {
+      continue;
+    }
+
+    const beforePropertySchema = beforeProperties[key];
+    const childPath = path ? `${path}.${key}` : key;
+
+    // Only compare string constraints on fields that existed in the before schema. New fields are skipped.
+    if (beforePropertySchema && typeof beforePropertySchema === 'object') {
+      checkStringConstraintNarrowing(beforePropertySchema, afterPropertySchema, childPath, breaks);
+      findStringConstraintNarrowing(beforePropertySchema, afterPropertySchema, childPath, breaks);
+    }
+  }
+
+  const beforeItems = beforeSchema.items;
+  const afterItems = afterSchema.items;
+
+  // Recurse into latest nested array items.
+  if (afterItems && typeof afterItems === 'object' && !Array.isArray(afterItems)) {
+    const itemsPath = path ? `${path}[]` : '[]';
+    const beforeItemSchema =
+      beforeItems && typeof beforeItems === 'object' && !Array.isArray(beforeItems) ? beforeItems : undefined;
+
+    // Only compare string constraints on items that existed in the before schema. New items are skipped.
+    if (beforeItemSchema) {
+      checkStringConstraintNarrowing(beforeItemSchema, afterItems, itemsPath, breaks);
+      findStringConstraintNarrowing(beforeItemSchema, afterItems, itemsPath, breaks);
+    }
+  }
+}
+
+/** Returns true when a schema represents a string field. */
+function isStringFieldSchema(schema: JSONSchema): boolean {
+  const type = schema.type;
+  if (type === 'string') {
+    return true;
+  }
+
+  // Type can be defined as a union of strings e.g. ['string', 'number'], so check if 'string' is included.
+  if (Array.isArray(type) && type.includes('string')) {
+    return true;
+  }
+
+  return (
+    schema.minLength !== undefined ||
+    schema.maxLength !== undefined ||
+    schema.format !== undefined ||
+    schema.pattern !== undefined
+  );
+}
+
+/** Returns true when afterSchema requires a longer string than beforeSchema. */
+function hasMinLengthIncreased(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const beforeMinLength = beforeSchema.minLength ?? 0;
+  const afterMinLength = afterSchema.minLength ?? 0;
+  return afterMinLength > beforeMinLength;
+}
+
+/** Returns true when afterSchema allows a shorter string than beforeSchema. */
+function hasMaxLengthLowered(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const beforeMaxLength = beforeSchema.maxLength;
+  const afterMaxLength = afterSchema.maxLength;
+
+  if (afterMaxLength === undefined) {
+    return false;
+  }
+
+  if (beforeMaxLength === undefined) {
+    return true;
+  }
+
+  return afterMaxLength < beforeMaxLength;
+}
+
+/** Returns true when afterSchema adds or changes a format constraint. */
+function hasFormatChanged(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const afterFormat = afterSchema.format;
+
+  if (afterFormat === undefined) {
+    return false;
+  }
+
+  return beforeSchema.format !== afterFormat;
+}
+
+/** Returns true when afterSchema adds or changes a pattern constraint. */
+function hasPatternChanged(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const afterPattern = afterSchema.pattern;
+
+  if (afterPattern === undefined) {
+    return false;
+  }
+
+  return beforeSchema.pattern !== afterPattern;
+}
+
+/** Checks string constraint keywords on a single schema for narrowing changes. */
+export function checkStringConstraintNarrowing(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  if (!isStringFieldSchema(beforeSchema) && !isStringFieldSchema(afterSchema)) {
+    return;
+  }
+
+  if (hasMinLengthIncreased(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.minLength);
+  }
+
+  if (hasMaxLengthLowered(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.maxLength);
+  }
+
+  if (hasFormatChanged(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.format);
+  }
+
+  if (hasPatternChanged(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.pattern);
+  }
+}

package/src/utils/jsonBreakDetector/compareSubschemas.ts

@@ -0,0 +1,67 @@
+import type { JSONSchema } from '@squiz/json-schema-library';
+
+import { findArrayConstraintNarrowing, checkArrayConstraintNarrowing } from './checks/findArrayConstraintNarrowing';
+import { findConstChanges, checkConstNarrowingAtNode } from './checks/findConstChanges';
+import { findFieldTypeChanges, hasTypeChange } from './checks/findFieldTypeChanges';
+import { findNewRequiredFields } from './checks/findNewRequiredFields';
+import {
+  checkNumericConstraintNarrowing,
+  findNumericConstraintNarrowing,
+} from './checks/findNumericConstraintNarrowing';
+import { findEnumNarrowing, checkEnumNarrowingAtNode } from './checks/findEnumNarrowing';
+import { checkStringConstraintNarrowing, findStringConstraintNarrowing } from './checks/findStringConstraintNarrowing';
+import { BREAK_MESSAGES, JsonBreak, pushBreak } from './types';
+
+/**
+ * Compares two schemas at the same path using every jsonBreakDetector check,
+ * including leaf-level constraints on the current node.
+ */
+export function compareSubschemas(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  // Only applicable to nested schemas (from `contains` subschemas), not the root schema.
+  if (path !== '') {
+    if (hasTypeChange(beforeSchema, afterSchema)) {
+      pushBreak(breaks, path, BREAK_MESSAGES.type);
+    }
+
+    checkEnumNarrowingAtNode(beforeSchema, afterSchema, path, breaks);
+    checkConstNarrowingAtNode(beforeSchema, afterSchema, path, breaks);
+  }
+
+  checkArrayConstraintNarrowing(beforeSchema, afterSchema, path, breaks);
+  checkNumericConstraintNarrowing(beforeSchema, afterSchema, path, breaks);
+  checkStringConstraintNarrowing(beforeSchema, afterSchema, path, breaks);
+
+  // Find breaking changes at children properties and items
+  findNewRequiredFields(beforeSchema, afterSchema, path, breaks);
+  findFieldTypeChanges(beforeSchema, afterSchema, path, breaks);
+  findEnumNarrowing(beforeSchema, afterSchema, path, breaks);
+  findConstChanges(beforeSchema, afterSchema, path, breaks);
+  findArrayConstraintNarrowing(beforeSchema, afterSchema, path, breaks);
+  findNumericConstraintNarrowing(beforeSchema, afterSchema, path, breaks);
+  findStringConstraintNarrowing(beforeSchema, afterSchema, path, breaks);
+}
+
+/** Compares array `contains` subschemas using the full jsonBreakDetector check suite. */
+export function compareContainsSubschemas(
+  beforeArraySchema: JSONSchema,
+  afterArraySchema: JSONSchema,
+  arrayPath: string,
+  breaks: JsonBreak[],
+): void {
+  const afterContains = afterArraySchema.contains;
+
+  if (!afterContains || typeof afterContains !== 'object') {
+    return;
+  }
+
+  const beforeContains = beforeArraySchema.contains;
+  const containsPath = arrayPath ? `${arrayPath}.{contains}` : '{contains}';
+  const beforeSubschema = beforeContains && typeof beforeContains === 'object' ? (beforeContains as JSONSchema) : {};
+
+  compareSubschemas(beforeSubschema, afterContains as JSONSchema, containsPath, breaks);
+}

package/src/utils/jsonBreakDetector/dereference/dereference.spec.ts

@@ -0,0 +1,245 @@
+import { dereferenceLocal } from './dereference';
+
+describe('dereferenceLocal', () => {
+  describe('JSON Schema Draft 7', () => {
+    it('dereferences a top-level $ref to a definition', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $ref: '#/definitions/Person',
+        definitions: {
+          Person: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+            },
+            required: ['name'],
+          },
+        },
+      };
+
+      expect(dereferenceLocal(schema)).toEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        definitions: {
+          Person: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+            },
+            required: ['name'],
+          },
+        },
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+        },
+        required: ['name'],
+      });
+    });
+
+    it('dereferences nested $refs in properties', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        type: 'object',
+        properties: {
+          address: { $ref: '#/definitions/Address' },
+        },
+        definitions: {
+          Address: {
+            type: 'object',
+            properties: {
+              city: { $ref: '#/definitions/City' },
+            },
+          },
+          City: {
+            type: 'string',
+            minLength: 1,
+          },
+        },
+      };
+
+      expect(dereferenceLocal(schema)).toEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        type: 'object',
+        properties: {
+          address: {
+            type: 'object',
+            properties: {
+              city: {
+                type: 'string',
+                minLength: 1,
+              },
+            },
+          },
+        },
+        definitions: {
+          Address: {
+            type: 'object',
+            properties: {
+              city: { $ref: '#/definitions/City' },
+            },
+          },
+          City: {
+            type: 'string',
+            minLength: 1,
+          },
+        },
+      });
+    });
+
+    it('dereferences $refs inside combinators', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        oneOf: [{ $ref: '#/definitions/StringValue' }, { $ref: '#/definitions/NumberValue' }],
+        definitions: {
+          StringValue: { type: 'string' },
+          NumberValue: { type: 'number' },
+        },
+      };
+
+      expect(dereferenceLocal(schema)).toEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        oneOf: [{ type: 'string' }, { type: 'number' }],
+        definitions: {
+          StringValue: { type: 'string' },
+          NumberValue: { type: 'number' },
+        },
+      });
+    });
+
+    it('dereferences chained $refs', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $ref: '#/definitions/Outer',
+        definitions: {
+          Outer: { $ref: '#/definitions/Inner' },
+          Inner: {
+            type: 'boolean',
+          },
+        },
+      };
+
+      expect(dereferenceLocal(schema)).toEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        definitions: {
+          Outer: { $ref: '#/definitions/Inner' },
+          Inner: {
+            type: 'boolean',
+          },
+        },
+        type: 'boolean',
+      });
+    });
+
+    it('merges sibling properties alongside a $ref', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        properties: {
+          title: {
+            $ref: '#/definitions/NonEmptyString',
+            description: 'A human-readable title',
+          },
+        },
+        definitions: {
+          NonEmptyString: {
+            type: 'string',
+            minLength: 1,
+          },
+        },
+      };
+
+      expect(dereferenceLocal(schema)).toEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        properties: {
+          title: {
+            type: 'string',
+            minLength: 1,
+            description: 'A human-readable title',
+          },
+        },
+        definitions: {
+          NonEmptyString: {
+            type: 'string',
+            minLength: 1,
+          },
+        },
+      });
+    });
+
+    it('resolves JSON pointer escaped property names', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        properties: {
+          'foo/bar': { $ref: '#/definitions/foo~1bar' },
+        },
+        definitions: {
+          'foo/bar': {
+            type: 'string',
+          },
+        },
+      };
+
+      expect(dereferenceLocal(schema)).toEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        properties: {
+          'foo/bar': {
+            type: 'string',
+          },
+        },
+        definitions: {
+          'foo/bar': {
+            type: 'string',
+          },
+        },
+      });
+    });
+
+    it('does not infinitely recurse on circular definitions', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $ref: '#/definitions/Node',
+        definitions: {
+          Node: {
+            type: 'object',
+            properties: {
+              child: { $ref: '#/definitions/Node' },
+            },
+          },
+        },
+      };
+
+      const result = dereferenceLocal(schema) as Record<string, unknown>;
+
+      expect(result.type).toBe('object');
+      expect((result.properties as Record<string, unknown>).child).toEqual({
+        type: 'object',
+        properties: {
+          child: { $ref: '#/definitions/Node' },
+        },
+      });
+    });
+
+    it('throws when a reference is not internal', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $ref: 'https://example.com/schema.json',
+      };
+
+      expect(() => dereferenceLocal(schema)).toThrow(
+        'Only internal references starting with "#/" are supported. Received: "https://example.com/schema.json"',
+      );
+    });
+
+    it('throws when a JSON pointer cannot be resolved', () => {
+      const schema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        properties: {
+          missing: { $ref: '#/definitions/DoesNotExist' },
+        },
+      };
+
+      expect(() => dereferenceLocal(schema)).toThrow(
+        'Could not resolve JSON pointer reference: "#/definitions/DoesNotExist" at segment "definitions"',
+      );
+    });
+  });
+});

package/src/utils/jsonBreakDetector/dereference/dereference.ts

@@ -0,0 +1,65 @@
+import type { JSONSchema } from '@squiz/json-schema-library';
+
+export type GenericSchema = Record<string, any>;
+
+/**
+ * Synchronously dereferences internal ($ref: "#/...") JSON schema references.
+ */
+export function dereferenceLocal<T extends GenericSchema = JSONSchema>(schema: T): T {
+  function resolvePointer(root: Record<string, any>, pointer: string): any {
+    if (!pointer.startsWith('#/')) {
+      throw new Error(`Only internal references starting with "#/" are supported. Received: "${pointer}"`);
+    }
+
+    const pathSegments = pointer.replace(/^#\//, '').split('/');
+
+    return pathSegments.reduce((acc, key) => {
+      // Decode RFC 6901 JSON Pointer escaped sequences (~1 -> /, ~0 -> ~)
+      const unescapedKey = key.replace(/~1/g, '/').replace(/~0/g, '~');
+
+      if (acc && typeof acc === 'object' && unescapedKey in acc) {
+        return acc[unescapedKey];
+      }
+
+      throw new Error(`Could not resolve JSON pointer reference: "${pointer}" at segment "${key}"`);
+    }, root);
+  }
+
+  function walk(node: any, root: Record<string, any>, seen = new WeakSet<object>()): any {
+    if (node === null || typeof node !== 'object') {
+      return node;
+    }
+
+    // Prevent infinite loops on circular references
+    if (seen.has(node)) {
+      return node;
+    }
+    seen.add(node);
+
+    if (Array.isArray(node)) {
+      return node.map((item) => walk(item, root, seen));
+    }
+
+    // Check if current object contains a string $ref property
+    if (typeof node.$ref === 'string') {
+      const resolvedTarget = resolvePointer(root, node.$ref);
+
+      // Separate $ref from rest of keys (JSON Schema draft 2019-09+ allows sibling properties)
+      const { $ref: _ref, ...rest } = node;
+
+      return {
+        ...walk(resolvedTarget, root, seen),
+        ...walk(rest, root, seen),
+      };
+    }
+
+    const result: Record<string, any> = {};
+    for (const [key, value] of Object.entries(node)) {
+      result[key] = walk(value, root, seen);
+    }
+
+    return result;
+  }
+
+  return walk(schema, schema) as T;
+}