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

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

@@ -0,0 +1,124 @@
+import { BREAK_MESSAGES, JsonBreak, pushBreak } from '../types';
+import { JSONSchema } from '@squiz/json-schema-library';
+
+/** Recursively detects enum narrowing at each schema level, accumulating dotted paths. */
+export function findEnumNarrowing(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  const beforeProperties = beforeSchema.properties ?? {};
+  const afterProperties = afterSchema.properties ?? {};
+
+  // Recurse into nested object properties.
+  for (const [key, afterPropertySchema] of Object.entries(afterProperties)) {
+    if (!afterPropertySchema || typeof afterPropertySchema !== 'object') {
+      continue;
+    }
+
+    const beforePropertySchema = beforeProperties[key];
+    const childPath = path ? `${path}.${key}` : key;
+
+    if (beforePropertySchema && typeof beforePropertySchema === 'object') {
+      // Only compare enum on fields that existed in the before schema.
+      reportEnumNarrowingAtNode(beforePropertySchema, afterPropertySchema, childPath, breaks);
+
+      // Compare `enum` on this property, then recurse into nested schemas for child fields.
+      findEnumNarrowing(beforePropertySchema, afterPropertySchema, childPath, breaks);
+    }
+    // New properties in afterSchema are skipped; adding a field is not an enum change.
+  }
+
+  const beforeItems = beforeSchema.items;
+  const afterItems = afterSchema.items;
+
+  // Recurse into array item schemas.
+  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 enum on items that existed in the before schema. New items are skipped.
+    if (beforeItemSchema) {
+      reportEnumNarrowingAtNode(beforeItemSchema, afterItems, itemsPath, breaks);
+      findEnumNarrowing(beforeItemSchema, afterItems, itemsPath, breaks);
+    }
+  }
+}
+
+/** Reports enum narrowing on a single schema node. */
+function reportEnumNarrowingAtNode(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  // Removing an options could leave old default value that matched that invalid, so report as breaking.
+  if (hasRemovedEnumOptions(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.enum);
+  }
+
+  // Adding an enum constraint could leave old values that dont match invalid, so report as breaking.
+  if (hasAddedEnum(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.enumAdded);
+  }
+}
+
+/** Reports enum narrowing on a single schema node. */
+export function checkEnumNarrowingAtNode(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  reportEnumNarrowingAtNode(beforeSchema, afterSchema, path, breaks);
+}
+
+/** Returns true when afterSchema adds an enum where the before schema had none. */
+function hasAddedEnum(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const afterEnum = afterSchema.enum;
+  // No enum constraint is not breaking.
+  if (!afterEnum || afterEnum.length === 0) {
+    return false;
+  }
+
+  const beforeEnum = beforeSchema.enum;
+  if (beforeEnum && beforeEnum.length > 0) {
+    return false;
+  }
+
+  // Check if a before const has been converted to an enum. e.g. const: 'published' -> enum: ['draft', 'published'].
+  if (beforeSchema.const !== undefined) {
+    return !afterEnum.some((value: unknown) => JSON.stringify(value) === JSON.stringify(beforeSchema.const));
+  }
+
+  return true;
+}
+
+/** Returns true when afterSchema.enum no longer allows every value from beforeSchema.enum. */
+function hasRemovedEnumOptions(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const beforeEnum = beforeSchema.enum;
+  if (!beforeEnum || beforeEnum.length === 0) {
+    return false;
+  }
+
+  const afterEnum = afterSchema.enum;
+  const afterConst = afterSchema.const;
+
+  // Enum removed entirely is a relaxation, not a breaking change.
+  if (!afterEnum) {
+    if (afterConst === undefined) {
+      return false;
+    }
+
+    // True when any former enum value is not matched by the new `const`.
+    return beforeEnum.some((beforeValue: unknown) => JSON.stringify(beforeValue) !== JSON.stringify(afterConst));
+  }
+
+  // True when any former enum value is missing from the after `enum` list.
+  return beforeEnum.some(
+    (beforeValue: unknown) =>
+      !afterEnum.some((afterValue: unknown) => JSON.stringify(beforeValue) === JSON.stringify(afterValue)),
+  );
+}

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

@@ -0,0 +1,105 @@
+import { BREAK_MESSAGES, JsonBreak, pushBreak } from '../types';
+import { JSONSchema } from '@squiz/json-schema-library';
+
+/**
+ * Recursively function to compare field type values at each schema level, accumulating dotted paths.
+ * */
+export function findFieldTypeChanges(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  typeChanges: JsonBreak[],
+): void {
+  // Get the current schema level child properties
+  const beforeProperties = beforeSchema.properties ?? {};
+  const afterProperties = afterSchema.properties ?? {};
+
+  // Recurse into latest nested object properties.
+  for (const [key, afterPropertySchema] of Object.entries(afterProperties)) {
+    // Only objects have types
+    if (!afterPropertySchema || typeof afterPropertySchema !== 'object') {
+      continue;
+    }
+
+    const beforePropertySchema = beforeProperties[key];
+    const childPath = path ? `${path}.${key}` : key;
+
+    // Only compare type on fields that existed in the before schema. New fields are skipped.
+    if (beforePropertySchema && typeof beforePropertySchema === 'object') {
+      // Only compare type on fields that existed in the before schema.
+      if (hasTypeChange(beforePropertySchema, afterPropertySchema)) {
+        pushBreak(typeChanges, childPath, BREAK_MESSAGES.type);
+      }
+
+      // Compare `type` on this property, then recurse into its nested schema so child fields are checked too.
+      findFieldTypeChanges(beforePropertySchema, afterPropertySchema, childPath, typeChanges);
+    }
+  }
+
+  // If instead the current schema level is an array, get the items schema
+  const beforeItems = beforeSchema.items;
+  const afterItems = afterSchema.items;
+
+  // Recurse into latest array item schemas.
+  if (afterItems && typeof afterItems === 'object' && !Array.isArray(afterItems)) {
+    const itemsPath = path ? `${path}[]` : '[]';
+    const beforeItemSchema =
+      beforeItems && typeof beforeItems === 'object' && !Array.isArray(beforeItems) ? beforeItems : undefined;
+
+    // Compare the `items` schema `type` for array fields, e.g. `tags[]` when
+    // `items: { type: 'string' }` becomes `items: { type: 'number' }`.
+    if (beforeItemSchema) {
+      if (hasTypeChange(beforeItemSchema, afterItems)) {
+        pushBreak(typeChanges, itemsPath, BREAK_MESSAGES.type);
+      }
+      findFieldTypeChanges(beforeItemSchema, afterItems, itemsPath, typeChanges);
+    }
+  }
+}
+
+function toTypeArray(type: string | string[]): string[] {
+  return Array.isArray(type) ? type : [type];
+}
+
+/**
+ * Returns true when every type allowed by `beforeType` is still allowed by `afterType`.
+ * In JSON Schema, integer is a subset of number, so relaxing integer to number is not breaking.
+ */
+function isBeforeTypeCoveredByAfterType(beforeType: string | string[], afterType: string | string[]): boolean {
+  const afterTypes = new Set(toTypeArray(afterType));
+
+  for (const type of toTypeArray(beforeType)) {
+    // Integer is a subset of number, so relaxing integer to number is not breaking.
+    if (type === 'integer') {
+      if (afterTypes.has('integer') || afterTypes.has('number')) {
+        continue;
+      }
+
+      return false;
+    }
+
+    if (!afterTypes.has(type)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** Returns true when the JSON Schema `type` keyword narrows between two schemas. */
+export function hasTypeChange(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const beforeType = beforeSchema.type;
+  const afterType = afterSchema.type;
+
+  // If both types are undefined, there is no change.
+  if (beforeType === undefined && afterType === undefined) {
+    return false;
+  }
+
+  // If one type is undefined, there is a change.
+  if (beforeType === undefined || afterType === undefined) {
+    return true;
+  }
+
+  return !isBeforeTypeCoveredByAfterType(beforeType, afterType);
+}

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

@@ -0,0 +1,97 @@
+import { JSONSchema } from '@squiz/json-schema-library';
+import { JsonBreak, BREAK_MESSAGES, pushBreak } from '../types';
+
+type DependentRequiredMap = Record<string, string[]>;
+
+function getDependentRequired(schema: JSONSchema): DependentRequiredMap {
+  const dependentRequired = (schema as JSONSchema & { dependentRequired?: DependentRequiredMap }).dependentRequired;
+  return dependentRequired ?? {};
+}
+
+function findNewDependentRequiredFields(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  newRequiredFields: JsonBreak[],
+): void {
+  const beforeDependentRequired = getDependentRequired(beforeSchema);
+  const afterDependentRequired = getDependentRequired(afterSchema);
+  const beforeProperties = beforeSchema.properties ?? {};
+
+  for (const [triggerField, afterDependentFields] of Object.entries(afterDependentRequired)) {
+    if (!Array.isArray(afterDependentFields)) {
+      continue;
+    }
+
+    // Adding dependentRequired for a newly added trigger field is not a breaking change.
+    if (!(triggerField in beforeProperties)) {
+      continue;
+    }
+
+    const beforeDependentFields = beforeDependentRequired[triggerField] ?? [];
+
+    for (const field of afterDependentFields) {
+      if (!beforeDependentFields.includes(field)) {
+        pushBreak(newRequiredFields, path ? `${path}.${field}` : field, BREAK_MESSAGES.dependentRequired);
+      }
+    }
+  }
+}
+
+/**
+ * Recursively compares required and dependentRequired fields at each schema level, accumulating dotted paths.
+ */
+export function findNewRequiredFields(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  newRequiredFields: JsonBreak[],
+): void {
+  // Get whats required at the current schema level
+  const beforeRequired = beforeSchema.required ?? [];
+  const afterRequired = afterSchema.required ?? [];
+
+  // Collect fields present in afterSchema.required but not in beforeSchema.required.
+  for (const field of afterRequired) {
+    if (!beforeRequired.includes(field)) {
+      pushBreak(newRequiredFields, path ? `${path}.${field}` : field, BREAK_MESSAGES.required);
+    }
+  }
+
+  findNewDependentRequiredFields(beforeSchema, afterSchema, path, newRequiredFields);
+
+  // Get the current schema level child properties
+  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;
+    // Missing before property is treated as an empty schema with no required fields.
+    findNewRequiredFields(
+      beforePropertySchema && typeof beforePropertySchema === 'object' ? beforePropertySchema : {},
+      afterPropertySchema,
+      childPath,
+      newRequiredFields,
+    );
+  }
+
+  // If instead the current schema level is an array, get the items schema
+  const beforeItems = beforeSchema.items;
+  const afterItems = afterSchema.items;
+  // Recurse into array item schemas (tuple items are not supported).
+  if (afterItems && typeof afterItems === 'object' && !Array.isArray(afterItems)) {
+    const itemsPath = path ? `${path}[]` : '[]';
+    findNewRequiredFields(
+      beforeItems && typeof beforeItems === 'object' && !Array.isArray(beforeItems) ? beforeItems : {},
+      afterItems,
+      itemsPath,
+      newRequiredFields,
+    );
+  }
+}

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

@@ -0,0 +1,243 @@
+import { BREAK_MESSAGES, JsonBreak, pushBreak } from '../types';
+import { JSONSchema } from '@squiz/json-schema-library';
+
+/** Recursively detects narrowed numeric constraints at each schema level, accumulating dotted paths. */
+export function findNumericConstraintNarrowing(
+  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)) {
+    if (!afterPropertySchema || typeof afterPropertySchema !== 'object') {
+      continue;
+    }
+
+    const beforePropertySchema = beforeProperties[key];
+    const childPath = path ? `${path}.${key}` : key;
+
+    // Only compare numeric constraints on fields that existed in the before schema. New fields are skipped.
+    if (beforePropertySchema && typeof beforePropertySchema === 'object') {
+      checkNumericConstraintNarrowing(beforePropertySchema, afterPropertySchema, childPath, breaks);
+      findNumericConstraintNarrowing(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 numeric constraints on items that existed in the before schema. New items are skipped.
+    if (beforeItemSchema) {
+      checkNumericConstraintNarrowing(beforeItemSchema, afterItems, itemsPath, breaks);
+      findNumericConstraintNarrowing(beforeItemSchema, afterItems, itemsPath, breaks);
+    }
+  }
+}
+
+/** Returns true when a schema represents a numeric field. */
+function isNumericFieldSchema(schema: JSONSchema): boolean {
+  const type = schema.type;
+  if (type === 'number' || type === 'integer') {
+    return true;
+  }
+
+  // Type can be defined as a union of strings e.g. ['number', 'integer'], so check if 'number' or 'integer' is included.
+  if (Array.isArray(type) && (type.includes('number') || type.includes('integer'))) {
+    return true;
+  }
+
+  return (
+    schema.minimum !== undefined ||
+    schema.exclusiveMinimum !== undefined ||
+    schema.maximum !== undefined ||
+    schema.exclusiveMaximum !== undefined ||
+    schema.multipleOf !== undefined
+  );
+}
+
+type LowerBoundKeyword = 'minimum' | 'exclusiveMinimum';
+type UpperBoundKeyword = 'maximum' | 'exclusiveMaximum';
+
+/** Represents the effective bound contributed by a single numeric constraint keyword. */
+type NumericBound<K extends string = string> = {
+  value: number;
+  keyword: K;
+};
+
+/** Returns the strictest lower bound from `minimum` and `exclusiveMinimum`, which may both be set. */
+function getEffectiveLowerBound(schema: JSONSchema): NumericBound<LowerBoundKeyword> | undefined {
+  const minimum = schema.minimum;
+  const exclusiveMinimum = schema.exclusiveMinimum;
+
+  // Both are defined, need to figure out which is lower
+  if (minimum !== undefined && exclusiveMinimum !== undefined) {
+    // min 5 is same as exclusiveMinimum 6 (x >= minimum and x > exclusiveMinimum)
+    // so if they are the same exclusiveMinimum is the effective lower bound
+    if (minimum > exclusiveMinimum) {
+      return { value: minimum, keyword: 'minimum' };
+    }
+
+    return { value: exclusiveMinimum, keyword: 'exclusiveMinimum' };
+  }
+
+  if (minimum !== undefined) {
+    return { value: minimum, keyword: 'minimum' };
+  }
+
+  if (exclusiveMinimum !== undefined) {
+    return { value: exclusiveMinimum, keyword: 'exclusiveMinimum' };
+  }
+
+  return undefined;
+}
+
+/** Returns the strictest upper bound from `maximum` and `exclusiveMaximum`, which may both be set. */
+function getEffectiveUpperBound(schema: JSONSchema): NumericBound<UpperBoundKeyword> | undefined {
+  const maximum = schema.maximum;
+  const exclusiveMaximum = schema.exclusiveMaximum;
+
+  if (maximum !== undefined && exclusiveMaximum !== undefined) {
+    // max 4 is same as exclusiveMaximum 5 (x <= maximum and x < exclusiveMaximum)
+    // so if they are the same exclusiveMaximum is the effective upper bound
+    if (maximum < exclusiveMaximum) {
+      return { value: maximum, keyword: 'maximum' };
+    }
+
+    return { value: exclusiveMaximum, keyword: 'exclusiveMaximum' };
+  }
+
+  if (maximum !== undefined) {
+    return { value: maximum, keyword: 'maximum' };
+  }
+
+  if (exclusiveMaximum !== undefined) {
+    return { value: exclusiveMaximum, keyword: 'exclusiveMaximum' };
+  }
+
+  return undefined;
+}
+
+/** Returns true when afterSchema requires a stricter lower bound than beforeSchema. */
+function hasLowerBoundIncreased(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const beforeBound = getEffectiveLowerBound(beforeSchema);
+  const afterBound = getEffectiveLowerBound(afterSchema);
+
+  if (afterBound === undefined) {
+    return false;
+  }
+
+  if (beforeBound === undefined) {
+    return true;
+  }
+
+  if (afterBound.value > beforeBound.value) {
+    return true;
+  }
+
+  if (afterBound.value < beforeBound.value) {
+    return false;
+  }
+
+  // Same effective value, but inclusive vs exclusive still differs (e.g. minimum: 5 allows 5, exclusiveMinimum: 5 does not).
+  return afterBound.keyword === 'exclusiveMinimum' && beforeBound.keyword === 'minimum';
+}
+
+/** Returns true when afterSchema allows a stricter upper bound than beforeSchema. */
+function hasUpperBoundLowered(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const beforeBound = getEffectiveUpperBound(beforeSchema);
+  const afterBound = getEffectiveUpperBound(afterSchema);
+
+  if (afterBound === undefined) {
+    return false;
+  }
+
+  if (beforeBound === undefined) {
+    return true;
+  }
+
+  if (afterBound.value < beforeBound.value) {
+    return true;
+  }
+
+  if (afterBound.value > beforeBound.value) {
+    return false;
+  }
+
+  // Same effective value, but inclusive vs exclusive still differs (e.g. maximum: 10 allows 10, exclusiveMaximum: 10 does not).
+  return afterBound.keyword === 'exclusiveMaximum' && beforeBound.keyword === 'maximum';
+}
+
+/** Picks the break message for the keyword that supplies the effective lower bound in the after schema. */
+function getLowerBoundBreakMessage(_beforeSchema: JSONSchema, afterSchema: JSONSchema): string {
+  const afterBound = getEffectiveLowerBound(afterSchema);
+
+  return afterBound?.keyword === 'exclusiveMinimum' ? BREAK_MESSAGES.exclusiveMinimum : BREAK_MESSAGES.minimum;
+}
+
+/** Picks the break message for the keyword that supplies the effective upper bound in the after schema. */
+function getUpperBoundBreakMessage(_beforeSchema: JSONSchema, afterSchema: JSONSchema): string {
+  const afterBound = getEffectiveUpperBound(afterSchema);
+
+  return afterBound?.keyword === 'exclusiveMaximum' ? BREAK_MESSAGES.exclusiveMaximum : BREAK_MESSAGES.maximum;
+}
+
+/**
+ * Returns true when afterSchema narrows the set of allowed multiples.
+ * A value valid under the before `multipleOf` may be invalid under the after `multipleOf`
+ * unless the before factor is itself a multiple of the after factor.
+ */
+function hasMultipleOfNarrowed(beforeSchema: JSONSchema, afterSchema: JSONSchema): boolean {
+  const afterMultipleOf = afterSchema.multipleOf;
+  const beforeMultipleOf = beforeSchema.multipleOf;
+
+  if (afterMultipleOf === undefined) {
+    return false;
+  }
+
+  if (beforeMultipleOf === undefined) {
+    return true;
+  }
+
+  if (beforeMultipleOf === afterMultipleOf) {
+    return false;
+  }
+
+  // Check if the constraint is strictly narrowed
+  // e.g. from 4 to 2 is ok as previous valid entries will still be valid
+  // but from 4 to 3 is not
+  return beforeMultipleOf % afterMultipleOf !== 0;
+}
+
+/** Checks numeric constraint keywords on a single schema for narrowing changes. */
+export function checkNumericConstraintNarrowing(
+  beforeSchema: JSONSchema,
+  afterSchema: JSONSchema,
+  path: string,
+  breaks: JsonBreak[],
+): void {
+  if (!isNumericFieldSchema(beforeSchema) && !isNumericFieldSchema(afterSchema)) {
+    return;
+  }
+
+  if (hasLowerBoundIncreased(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, getLowerBoundBreakMessage(beforeSchema, afterSchema));
+  }
+
+  if (hasUpperBoundLowered(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, getUpperBoundBreakMessage(beforeSchema, afterSchema));
+  }
+
+  if (hasMultipleOfNarrowed(beforeSchema, afterSchema)) {
+    pushBreak(breaks, path, BREAK_MESSAGES.multipleOf);
+  }
+}