@specferret/core 0.1.3 → 0.2.0

package/src/extractor/upward-classifier.test.ts

@@ -0,0 +1,188 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'bun:test';
+import { classifyUpwardDrift } from './upward-classifier.js';
+
+const FILE = 'src/auth/jwt.ts';
+const SYMBOL = 'JwtPayload';
+const CONTRACT_ID = 'auth.jwt';
+
+// ─── Canonical declared schema ────────────────────────────────────────────────
+
+const DECLARED_SCHEMA = {
+  type: 'object',
+  properties: {
+    sub: { type: 'string' },
+    role: { type: 'string', enum: ['admin', 'user'] },
+    exp: { type: 'number' },
+  },
+  required: ['sub', 'role'],
+};
+
+describe('classifyUpwardDrift — S51: BREAKING cases', () => {
+  it('required field removed from code shape → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+      },
+      required: ['role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /required field\(s\) removed: sub/);
+    assert.equal(result.contractId, CONTRACT_ID);
+    assert.equal(result.sourceFile, FILE);
+    assert.equal(result.sourceSymbol, SYMBOL);
+  });
+
+  it('field type changed in code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'number' }, // was string
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /type changed/);
+  });
+
+  it('required field added in code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+        iat: { type: 'number' },
+      },
+      required: ['sub', 'role', 'iat'], // iat newly required
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /required field\(s\) added: iat/);
+  });
+
+  it('property removed entirely from code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        exp: { type: 'number' },
+        // role removed entirely
+      },
+      required: ['sub'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /property 'role' removed|required field\(s\) removed/);
+  });
+
+  it('enum value removed from code → BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin'] }, // 'user' removed
+        exp: { type: 'number' },
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'BREAKING');
+    assert.match(result.reason, /enum value\(s\) removed/);
+  });
+});
+
+describe('classifyUpwardDrift — S51: NON_BREAKING cases', () => {
+  it('optional field added in code → NON_BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin', 'user'] },
+        exp: { type: 'number' },
+        nbf: { type: 'number' }, // new optional field
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NON_BREAKING');
+    assert.match(result.reason, /optional field\(s\) added/);
+  });
+
+  it('enum value added to code → NON_BREAKING', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        sub: { type: 'string' },
+        role: { type: 'string', enum: ['admin', 'user', 'superuser'] }, // 'superuser' added
+        exp: { type: 'number' },
+      },
+      required: ['sub', 'role'],
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NON_BREAKING');
+    assert.match(result.reason, /enum value\(s\) added/);
+  });
+});
+
+describe('classifyUpwardDrift — S51: NOOP cases', () => {
+  it('identical schemas → NOOP', () => {
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NOOP');
+    assert.match(result.reason, /semantically identical/);
+  });
+
+  it('property order change in code does not produce drift (hash-stable)', () => {
+    const codeSchema = {
+      type: 'object',
+      properties: {
+        // same properties, different key order
+        exp: { type: 'number' },
+        role: { type: 'string', enum: ['admin', 'user'] },
+        sub: { type: 'string' },
+      },
+      required: ['role', 'sub'], // reordered required array
+    };
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, codeSchema, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NOOP');
+  });
+
+  it('empty vs empty schemas → NOOP', () => {
+    const result = classifyUpwardDrift(CONTRACT_ID, {}, {}, FILE, SYMBOL);
+    assert.equal(result.driftClass, 'NOOP');
+  });
+});
+
+describe('classifyUpwardDrift — S51: result shape', () => {
+  it('result always contains all required fields', () => {
+    const result = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    assert.ok('contractId' in result);
+    assert.ok('driftClass' in result);
+    assert.ok('sourceFile' in result);
+    assert.ok('sourceSymbol' in result);
+    assert.ok('reason' in result);
+    assert.equal(typeof result.reason, 'string');
+  });
+
+  it('is a pure function — same inputs produce same output', () => {
+    const r1 = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    const r2 = classifyUpwardDrift(CONTRACT_ID, DECLARED_SCHEMA, DECLARED_SCHEMA, FILE, SYMBOL);
+    assert.deepEqual(r1, r2);
+  });
+
+  it('does not mutate inputs', () => {
+    const declared = { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] };
+    const code = { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] };
+    const declaredBefore = JSON.stringify(declared);
+    const codeBefore = JSON.stringify(code);
+    classifyUpwardDrift(CONTRACT_ID, declared, code, FILE, SYMBOL);
+    assert.equal(JSON.stringify(declared), declaredBefore);
+    assert.equal(JSON.stringify(code), codeBefore);
+  });
+});

package/src/extractor/upward-classifier.ts

@@ -0,0 +1,68 @@
+// Pure function. No I/O. No side effects. Ever.
+// Upward drift classifier — detects when a TypeScript implementation diverges from
+// its declared contract schema (code → spec direction).
+
+import { compareSchemas } from './validator.js';
+
+export type UpwardDriftClass = 'BREAKING' | 'NON_BREAKING' | 'NOOP';
+
+export interface UpwardDriftResult {
+  contractId: string;
+  driftClass: UpwardDriftClass;
+  sourceFile: string;
+  sourceSymbol: string;
+  reason: string;
+}
+
+/**
+ * Classifies the drift between a declared contract schema and the live code-derived schema.
+ *
+ * Input:
+ *   - declaredSchema: the schema declared in the .contract.md frontmatter (the spec)
+ *   - codeSchema:     the schema extracted from the TypeScript source at lint time
+ *
+ * Output:
+ *   - BREAKING:     code change breaks the declared contract (required field removed, type changed, etc.)
+ *   - NON_BREAKING: code change is additive but not declared (optional field added, enum value added)
+ *   - NOOP:         code and declared schema are semantically identical (hash-stable, no action needed)
+ *
+ * Uses the same classification taxonomy as compareSchemas for consistency.
+ * No-op formatting changes (property reorder with stable hash) return NOOP.
+ */
+export function classifyUpwardDrift(
+  contractId: string,
+  declaredSchema: unknown,
+  codeSchema: unknown,
+  sourceFile: string,
+  sourceSymbol: string,
+): UpwardDriftResult {
+  const comparison = compareSchemas(declaredSchema, codeSchema);
+
+  if (comparison.classification === 'no-change') {
+    return {
+      contractId,
+      driftClass: 'NOOP',
+      sourceFile,
+      sourceSymbol,
+      reason: comparison.reason,
+    };
+  }
+
+  if (comparison.classification === 'breaking') {
+    return {
+      contractId,
+      driftClass: 'BREAKING',
+      sourceFile,
+      sourceSymbol,
+      reason: comparison.reason,
+    };
+  }
+
+  return {
+    contractId,
+    driftClass: 'NON_BREAKING',
+    sourceFile,
+    sourceSymbol,
+    reason: comparison.reason,
+  };
+}

package/src/extractor/validator.test.ts

@@ -0,0 +1,228 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'bun:test';
+import { validateFerretSchema, compareSchemas, validateContractType } from './validator.js';
+import { CONTRACT_TYPES } from './contract-types.js';
+
+// ─── validateFerretSchema ────────────────────────────────────────────────────
+
+describe('validateFerretSchema', () => {
+  it('warns on every unsupported keyword when present', () => {
+    const UNSUPPORTED = ['$ref', 'allOf', 'anyOf', 'oneOf', 'not', 'if', 'then', 'else', '$defs', 'definitions', 'patternProperties', 'dependencies'];
+
+    for (const keyword of UNSUPPORTED) {
+      const shape = { type: 'object', [keyword]: {} };
+      const result = validateFerretSchema(shape, 'contracts/test.contract.md');
+      assert.equal(result.warnings.length, 1);
+      assert.match(result.warnings[0], new RegExp(keyword.replace('$', '\\$')));
+      assert.match(result.warnings[0], /contracts\/test\.contract\.md/);
+      assert.equal(result.valid, true);
+    }
+  });
+
+  it('does not warn on valid supported keywords', () => {
+    const shape = {
+      type: 'object',
+      properties: {
+        id: { type: 'string', format: 'uuid' },
+        name: { type: 'string' },
+        score: { type: 'number' },
+        active: { type: 'boolean' },
+        tags: { type: 'array', items: { type: 'string' } },
+        status: { type: 'string', enum: ['pending', 'active', 'cancelled'] },
+      },
+      required: ['id', 'name'],
+      additionalProperties: false,
+    };
+    const result = validateFerretSchema(shape, 'contracts/valid.contract.md');
+    assert.equal(result.warnings.length, 0);
+    assert.equal(result.valid, true);
+  });
+
+  it('warns on multiple unsupported keywords in a single schema', () => {
+    const shape = {
+      type: 'object',
+      allOf: [{}],
+      anyOf: [{}],
+      $ref: '#/definitions/Foo',
+    };
+    const result = validateFerretSchema(shape, 'contracts/complex.contract.md');
+    assert.ok(result.warnings.length >= 3);
+    assert.equal(result.valid, true);
+  });
+
+  it('does not warn on null or primitive shape', () => {
+    assert.equal(validateFerretSchema(null, 'f.md').warnings.length, 0);
+    assert.equal(validateFerretSchema('string shape', 'f.md').warnings.length, 0);
+    assert.equal(validateFerretSchema(42, 'f.md').warnings.length, 0);
+  });
+});
+
+describe('validateContractType', () => {
+  it('accepts all six supported contract types', () => {
+    for (const contractType of CONTRACT_TYPES) {
+      const result = validateContractType(contractType, 'contracts/test.contract.md');
+      assert.equal(result.valid, true);
+      if (result.valid) {
+        assert.equal(result.value, contractType);
+      }
+    }
+  });
+
+  it('rejects unknown contract types and lists allowed values', () => {
+    const result = validateContractType('service', 'contracts/test.contract.md');
+    assert.equal(result.valid, false);
+    assert.match(result.error ?? '', /Invalid contract type 'service'/);
+    assert.match(result.error ?? '', /Allowed types: api, table, type, event, flow, config/);
+  });
+
+  it('keeps shared constants aligned with expected six core types', () => {
+    assert.deepEqual(CONTRACT_TYPES, ['api', 'table', 'type', 'event', 'flow', 'config']);
+  });
+});
+
+// ─── compareSchemas ──────────────────────────────────────────────────────────
+
+describe('compareSchemas — breaking changes', () => {
+  it('required field removed → breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['id', 'email'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /email/);
+  });
+
+  it('field type changed → breaking', () => {
+    const prev = { type: 'object', properties: { count: { type: 'string' } } };
+    const curr = { type: 'object', properties: { count: { type: 'integer' } } };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+  });
+
+  it('required field added → breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id', 'name'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /name/);
+  });
+
+  it('enum value removed → breaking', () => {
+    const prev = { type: 'string', enum: ['pending', 'active', 'cancelled'] };
+    const curr = { type: 'string', enum: ['pending', 'active'] };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /cancelled/);
+  });
+
+  it('response type changed → breaking', () => {
+    const prev = { response: { type: 'array', items: { type: 'string' } } };
+    const curr = { response: { type: 'object', properties: {} } };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+  });
+
+  it('property removed → breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, secret: { type: 'string' } },
+      required: ['id'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /secret/);
+  });
+});
+
+describe('compareSchemas — non-breaking changes', () => {
+  it('optional field added → non-breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, description: { type: 'string' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'non-breaking');
+    assert.match(result.reason, /description/);
+  });
+
+  it('enum value added → non-breaking', () => {
+    const prev = { type: 'string', enum: ['pending', 'active'] };
+    const curr = { type: 'string', enum: ['pending', 'active', 'cancelled'] };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'non-breaking');
+    assert.match(result.reason, /cancelled/);
+  });
+});
+
+describe('compareSchemas — no-change', () => {
+  it('property order changed → no-change', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id', 'name'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { name: { type: 'string' }, id: { type: 'string' } }, // order swapped
+      required: ['id', 'name'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'no-change');
+  });
+
+  it('required array reordered → no-change', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['id', 'email'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['email', 'id'], // same fields, different order
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'no-change');
+  });
+
+  it('identical schemas → no-change', () => {
+    const schema = {
+      type: 'object',
+      properties: { id: { type: 'string', format: 'uuid' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(schema, { ...schema });
+    assert.equal(result.classification, 'no-change');
+  });
+
+  it('empty schemas compared → no-change', () => {
+    const result = compareSchemas({}, {});
+    assert.equal(result.classification, 'no-change');
+  });
+});

package/src/extractor/validator.ts

@@ -0,0 +1,199 @@
+// Pure function. No I/O. No side effects. Ever.
+// Validator layer — validates JSON Schema subset, classifies breaking/non-breaking/no-change.
+
+import { CONTRACT_TYPES, formatAllowedContractTypes, isContractType, type ContractType } from './contract-types.js';
+
+export type ChangeClassification = 'breaking' | 'non-breaking' | 'no-change';
+
+export interface SchemaValidationResult {
+  valid: boolean;
+  warnings: string[];
+}
+
+export interface SchemaComparisonResult {
+  classification: ChangeClassification;
+  reason: string;
+}
+
+export type ContractTypeValidationResult = { valid: true; value: ContractType } | { valid: false; error: string };
+
+export function validateContractType(contractType: unknown, filePath: string): ContractTypeValidationResult {
+  if (isContractType(contractType)) {
+    return { valid: true, value: contractType };
+  }
+
+  return {
+    valid: false,
+    error: `Invalid contract type '${String(contractType)}' in ${filePath}. Allowed types: ${formatAllowedContractTypes()}.`,
+  };
+}
+
+/**
+ * JSON Schema keywords that are explicitly NOT supported by Ferret.
+ * If any appear in a schema, a warning is emitted but the schema is still accepted.
+ * See: spec/CONTRACT-SCHEMA.md — Part 3
+ */
+const UNSUPPORTED_KEYWORDS = [
+  '$ref',
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'not',
+  'if',
+  'then',
+  'else',
+  '$defs',
+  'definitions',
+  'patternProperties',
+  'dependencies',
+];
+
+/**
+ * Validates a schema object against the Ferret JSON Schema subset.
+ * Always returns valid: true — unsupported keywords produce warnings, not errors.
+ */
+export function validateFerretSchema(shape: unknown, filePath: string): SchemaValidationResult {
+  const warnings: string[] = [];
+
+  if (shape === null || typeof shape !== 'object') {
+    return { valid: true, warnings };
+  }
+
+  const serialised = JSON.stringify(shape);
+
+  for (const keyword of UNSUPPORTED_KEYWORDS) {
+    // Match the keyword as a JSON object key (surrounded by quotes)
+    if (serialised.includes(`"${keyword}"`)) {
+      warnings.push(
+        `⚠ Unsupported JSON Schema keyword: ${keyword} in ${filePath}\n` +
+          `  Ferret supports a subset of JSON Schema.\n` +
+          `  See: spec/CONTRACT-SCHEMA.md — Part 3`,
+      );
+    }
+  }
+
+  return { valid: true, warnings };
+}
+
+/**
+ * Compares two schema objects and classifies the change.
+ *
+ * Breaking:     required field removed, field type changed, enum value removed,
+ *               response/array type changed, required field added
+ * Non-breaking: optional field added, enum value added
+ * No-change:    property order changed, whitespace, required array reordered
+ */
+export function compareSchemas(previous: unknown, current: unknown): SchemaComparisonResult {
+  // Normalise: work with plain objects only
+  const prev = (typeof previous === 'object' && previous !== null ? previous : {}) as Record<string, unknown>;
+  const curr = (typeof current === 'object' && current !== null ? current : {}) as Record<string, unknown>;
+
+  // 1. Check type change at this level
+  if (prev.type !== undefined && curr.type !== undefined && prev.type !== curr.type) {
+    return { classification: 'breaking', reason: `type changed from '${prev.type}' to '${curr.type}'` };
+  }
+
+  // 2. Check required fields
+  const prevRequired = normaliseRequired(prev.required);
+  const currRequired = normaliseRequired(curr.required);
+
+  const removedRequired = prevRequired.filter((f) => !currRequired.includes(f));
+  if (removedRequired.length > 0) {
+    return { classification: 'breaking', reason: `required field(s) removed: ${removedRequired.join(', ')}` };
+  }
+
+  const addedRequired = currRequired.filter((f) => !prevRequired.includes(f));
+  if (addedRequired.length > 0) {
+    return { classification: 'breaking', reason: `required field(s) added: ${addedRequired.join(', ')}` };
+  }
+
+  // 3. Check enum changes
+  const prevEnum = normaliseEnum(prev.enum);
+  const currEnum = normaliseEnum(curr.enum);
+
+  if (prevEnum !== null && currEnum !== null) {
+    const removedEnum = prevEnum.filter((v) => !currEnum.includes(v));
+    if (removedEnum.length > 0) {
+      return { classification: 'breaking', reason: `enum value(s) removed: ${removedEnum.join(', ')}` };
+    }
+    const addedEnum = currEnum.filter((v) => !prevEnum.includes(v));
+    if (addedEnum.length > 0) {
+      return { classification: 'non-breaking', reason: `enum value(s) added: ${addedEnum.join(', ')}` };
+    }
+  }
+
+  // 4. Check properties — look for type changes in existing properties, or optional additions
+  const prevProps = (prev.properties ?? {}) as Record<string, unknown>;
+  const currProps = (curr.properties ?? {}) as Record<string, unknown>;
+
+  for (const key of Object.keys(currProps)) {
+    if (!(key in prevProps)) {
+      // New property — only breaking if it's also in required (already caught above)
+      if (currRequired.includes(key)) {
+        return { classification: 'breaking', reason: `required field added: ${key}` };
+      }
+      // Not required — non-breaking addition
+      continue;
+    }
+    // Property exists in both — check for type change recursively
+    const nested = compareSchemas(prevProps[key], currProps[key]);
+    if (nested.classification === 'breaking') {
+      return { classification: 'breaking', reason: `property '${key}': ${nested.reason}` };
+    }
+    if (nested.classification === 'non-breaking') {
+      return { classification: 'non-breaking', reason: `property '${key}': ${nested.reason}` };
+    }
+  }
+
+  // 5. Check for property removals (any removal is breaking — even "optional" fields
+  //    that consumers may depend on)
+  for (const key of Object.keys(prevProps)) {
+    if (!(key in currProps)) {
+      return { classification: 'breaking', reason: `property '${key}' removed` };
+    }
+  }
+
+  // 6. Check request/response top-level wrappers (Ferret API extension)
+  for (const wrapper of ['request', 'response'] as const) {
+    if (prev[wrapper] !== undefined || curr[wrapper] !== undefined) {
+      const nested = compareSchemas(prev[wrapper] ?? {}, curr[wrapper] ?? {});
+      if (nested.classification === 'breaking') {
+        return { classification: 'breaking', reason: `${wrapper}: ${nested.reason}` };
+      }
+      if (nested.classification === 'non-breaking') {
+        return { classification: 'non-breaking', reason: `${wrapper}: ${nested.reason}` };
+      }
+    }
+  }
+
+  // 7. Check array items type change
+  if (prev.items !== undefined && curr.items !== undefined) {
+    const nested = compareSchemas(prev.items, curr.items);
+    if (nested.classification === 'breaking') {
+      return { classification: 'breaking', reason: `array items: ${nested.reason}` };
+    }
+    if (nested.classification === 'non-breaking') {
+      return { classification: 'non-breaking', reason: `array items: ${nested.reason}` };
+    }
+  }
+
+  // 8. Check if a new optional property was added (non-breaking)
+  const newOptionalKeys = Object.keys(currProps).filter((k) => !(k in prevProps) && !currRequired.includes(k));
+  if (newOptionalKeys.length > 0) {
+    return { classification: 'non-breaking', reason: `optional field(s) added: ${newOptionalKeys.join(', ')}` };
+  }
+
+  return { classification: 'no-change', reason: 'schemas are semantically identical' };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function normaliseRequired(required: unknown): string[] {
+  if (!Array.isArray(required)) return [];
+  return required.filter((v): v is string => typeof v === 'string');
+}
+
+function normaliseEnum(enumVal: unknown): string[] | null {
+  if (!Array.isArray(enumVal)) return null;
+  return enumVal.map((v) => String(v));
+}