Schema-Drift Detector: Catch Structural and Semantic Contract Changes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204

export type AttributeName = "type" | "required" | "nullable" | "enum" | "unit" | "meaning";
export type Severity = "non_breaking" | "review" | "breaking" | "unknown";
export type Status = "unchanged" | "non_breaking" | "review_required" | "breaking" | "indeterminate";

export interface FieldSchema {
  type: string | null;
  required: boolean | null;
  nullable: boolean | null;
  enum: string[] | null;
  unit: string | null;
  meaning: string | null;
  unknown_attributes?: AttributeName[];
}

export interface SchemaDocument {
  schema_id: string;
  version: string;
  parent_version: string | null;
  completeness: "complete" | "partial" | "unknown";
  fields: Record<string, FieldSchema>;
}

export interface ReleasePolicy {
  name: string;
  direction: string;
  added_field: Severity;
  removed_optional: Severity;
  removed_required: Severity;
  type_changed: Severity;
  optional_to_required: Severity;
  required_to_optional: Severity;
  nonnullable_to_nullable: Severity;
  nullable_to_nonnullable: Severity;
  enum_values_added: Severity;
  enum_values_removed: Severity;
  unit_changed: Severity;
  meaning_changed: Severity;
}

export interface DriftChange {
  field: string;
  kind: string;
  severity: Severity;
  before: unknown;
  after: unknown;
  rationale: string;
}

const ATTRIBUTES: AttributeName[] = ["type", "required", "nullable", "enum", "unit", "meaning"];
const SEVERITY_RANK: Record<Severity, number> = { non_breaking: 0, review: 1, breaking: 2, unknown: -1 };

export const STRICT_EXISTING_CONSUMER_POLICY: ReleasePolicy = {
  name: "strict_existing_consumer_v1",
  direction: "candidate_producer_to_baseline_consumer",
  added_field: "non_breaking",
  removed_optional: "review",
  removed_required: "breaking",
  type_changed: "breaking",
  optional_to_required: "non_breaking",
  required_to_optional: "breaking",
  nonnullable_to_nullable: "breaking",
  nullable_to_nonnullable: "non_breaking",
  enum_values_added: "breaking",
  enum_values_removed: "review",
  unit_changed: "breaking",
  meaning_changed: "breaking",
};

function validateDocument(document: SchemaDocument, label: string): void {
  if (!document || typeof document !== "object") throw new TypeError(`${label} must be an object`);
  for (const key of ["schema_id", "version", "parent_version", "completeness", "fields"] as const) {
    if (!(key in document)) throw new Error(`${label} is missing key: ${key}`);
  }
  if (!["complete", "partial", "unknown"].includes(document.completeness)) {
    throw new Error(`${label}.completeness must be complete, partial, or unknown`);
  }
  if (!document.fields || typeof document.fields !== "object" || Array.isArray(document.fields)) {
    throw new TypeError(`${label}.fields must be an object`);
  }
  for (const [fieldName, field] of Object.entries(document.fields)) {
    if (!fieldName) throw new Error(`${label} field names must be non-empty strings`);
    const unknown = field.unknown_attributes ?? [];
    if (!Array.isArray(unknown) || unknown.some((item) => !ATTRIBUTES.includes(item))) {
      throw new Error(`${label}.${fieldName}.unknown_attributes is invalid`);
    }
    if (document.completeness === "complete" && unknown.length) {
      throw new Error(`${label}.${fieldName} cannot be unknown in a complete document`);
    }
    for (const attribute of ATTRIBUTES) {
      if (!(attribute in field)) throw new Error(`${label}.${fieldName} is missing ${attribute}`);
    }
    if (field.enum !== null) {
      if (!Array.isArray(field.enum) || field.enum.some((value) => typeof value !== "string")) {
        throw new TypeError(`${label}.${fieldName}.enum must be null or a string array`);
      }
      if (new Set(field.enum).size !== field.enum.length) throw new Error(`${label}.${fieldName}.enum contains duplicates`);
    }
  }
}

function change(field: string, kind: string, severity: Severity, before: unknown, after: unknown, rationale: string): DriftChange {
  return { field, kind, severity, before: structuredClone(before), after: structuredClone(after), rationale };
}

export function detectSchemaDrift(
  baseline: SchemaDocument,
  candidate: SchemaDocument,
  policy: ReleasePolicy = STRICT_EXISTING_CONSUMER_POLICY,
) {
  validateDocument(baseline, "baseline");
  validateDocument(candidate, "candidate");
  const active = structuredClone(policy);
  const changes: DriftChange[] = [];

  if (baseline.schema_id !== candidate.schema_id) {
    changes.push(change("$schema", "lineage_mismatch", "unknown", baseline.schema_id, candidate.schema_id, "Different schema identities cannot be compared as one lineage."));
  }
  if (candidate.parent_version !== baseline.version) {
    changes.push(change("$schema", "lineage_mismatch", "unknown", baseline.version, candidate.parent_version, "Candidate parent_version does not identify the supplied baseline."));
  }
  for (const [label, document] of [["baseline", baseline], ["candidate", candidate]] as const) {
    if (document.completeness !== "complete") {
      changes.push(change("$schema", "spec_incomplete", "unknown", null, document.completeness, `The ${label} specification is not declared complete.`));
    }
  }

  const fields = [...new Set([...Object.keys(baseline.fields), ...Object.keys(candidate.fields)])].sort();
  for (const fieldName of fields) {
    const before = baseline.fields[fieldName];
    const after = candidate.fields[fieldName];
    if (!before || !after) {
      const missingDocument = !before ? baseline : candidate;
      if (missingDocument.completeness !== "complete") {
        changes.push(change(fieldName, "field_presence_unknown", "unknown", before ?? null, after ?? null, "An absent field is not evidence of addition or removal in an incomplete specification."));
      } else if (!before) {
        changes.push(change(fieldName, "field_added", active.added_field, null, after, "The strict policy assumes baseline consumers ignore unknown fields."));
      } else {
        const severity = before.required === true ? active.removed_required : active.removed_optional;
        changes.push(change(fieldName, "field_removed", severity, before, null, "Removal is breaking when a baseline consumer requires the field; optional dependencies require review."));
      }
      continue;
    }

    const beforeUnknown = new Set(before.unknown_attributes ?? []);
    const afterUnknown = new Set(after.unknown_attributes ?? []);
    for (const attribute of ATTRIBUTES) {
      if (beforeUnknown.has(attribute) || afterUnknown.has(attribute)) {
        changes.push(change(fieldName, "attribute_unknown", "unknown", before[attribute], after[attribute], `${attribute} is not known in both specification versions.`));
        continue;
      }
      const valuesEqual = attribute === "enum"
        ? (() => {
            const beforeValues = new Set(before.enum ?? []);
            const afterValues = new Set(after.enum ?? []);
            return beforeValues.size === afterValues.size && [...beforeValues].every((value) => afterValues.has(value));
          })()
        : JSON.stringify(before[attribute]) === JSON.stringify(after[attribute]);
      if (valuesEqual) continue;
      if (attribute === "type") {
        changes.push(change(fieldName, "type_changed", active.type_changed, before.type, after.type, "A baseline parser may not accept the candidate representation."));
      } else if (attribute === "required") {
        const severity = after.required ? active.optional_to_required : active.required_to_optional;
        changes.push(change(fieldName, "requiredness_changed", severity, before.required, after.required, "Under this direction, making a baseline-required field optional can create missing values for existing consumers."));
      } else if (attribute === "nullable") {
        const severity = after.nullable ? active.nonnullable_to_nullable : active.nullable_to_nonnullable;
        changes.push(change(fieldName, "nullability_changed", severity, before.nullable, after.nullable, "Existing consumers may fail when null becomes newly valid."));
      } else if (attribute === "enum") {
        const beforeValues = new Set(before.enum ?? []);
        const afterValues = new Set(after.enum ?? []);
        const added = [...afterValues].filter((value) => !beforeValues.has(value)).sort();
        const removed = [...beforeValues].filter((value) => !afterValues.has(value)).sort();
        const severities: Severity[] = [];
        if (added.length) severities.push(active.enum_values_added);
        if (removed.length) severities.push(active.enum_values_removed);
        const severity = severities.sort((a, b) => SEVERITY_RANK[b] - SEVERITY_RANK[a])[0];
        changes.push(change(fieldName, "enum_changed", severity, before.enum, after.enum, `Added values ${added.length ? added.join(", ") : "none"}; removed values ${removed.length ? removed.join(", ") : "none"}. Exhaustive baseline consumers may reject new codes.`));
      } else if (attribute === "unit") {
        changes.push(change(fieldName, "unit_changed", active.unit_changed, before.unit, after.unit, "The representation may still parse while numerical scale or economic unit changes."));
      } else {
        changes.push(change(fieldName, "meaning_changed", active.meaning_changed, before.meaning, after.meaning, "A semantic contract change can alter interpretation without changing the physical type."));
      }
    }
  }

  const hasBreaking = changes.some((item) => item.severity === "breaking");
  const hasUnknown = changes.some((item) => item.severity === "unknown");
  const hasReview = changes.some((item) => item.severity === "review");
  let status: Status;
  if (hasBreaking) status = "breaking";
  else if (hasUnknown) status = "indeterminate";
  else if (hasReview) status = "review_required";
  else if (changes.length) status = "non_breaking";
  else status = "unchanged";

  return {
    baseline_version: baseline.version,
    candidate_version: candidate.version,
    policy: active,
    status,
    coverage_complete: !hasUnknown,
    changes,
  };
}