specshield 3.2.7 → 3.2.9

package/README.md

@@ -17,8 +17,8 @@
 **Commands — local & hosted compare**
 - [Local Compare](#local-compare) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
 
-**Bi-Directional Contract Testing (BDCT)**
-- [BDCT overview & full command reference](#bi-directional-contract-testing-bdct)
+**Contract Compatibility Testing — the `bdct` commands**
+- [Overview & full command reference](#bi-directional-contract-testing-bdct)
 - [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
   - [Step 1 — record a HAR](#step-1--record-a-har-file) · [Step 2 — generate contract](#step-2--turn-the-har-into-a-consumer-contract) · [Step 3 — publish + gate](#step-3--publish--gate) · [Operational concerns](#operational-concerns-read-this-before-going-live)
 - [`bdct verify-provider` — spec-vs-production conformance](#bdct-verify-provider--does-your-live-provider-actually-match-its-spec)
@@ -34,21 +34,23 @@
 
 ---
 
-> **OpenAPI Diff · Breaking-Change Detection · Bi-Directional Contract Testing · `can-i-deploy` Gate · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
+> **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
 
 ---
 
 ## Never ship a breaking change to your API consumers
 
-**SpecShield** is the one CLI that does four things to keep your API safe:
+**SpecShield is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
+
+It's the one CLI that does four things to keep your API safe:
 
 1. **Diff** two OpenAPI specs and fail CI on breaking changes.
-2. **Bi-directional contract testing** with `can-i-deploy` — block a deploy that would break a consumer.
+2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer.
 3. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
 4. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
 
 ```
-OpenAPI diff  +  BDCT  +  HAR → consumer contract  +  spec-vs-production conformance  —  in one CLI.
+OpenAPI diff  +  contract compatibility checks  +  HAR → consumer contract  +  spec-vs-production conformance  —  in one CLI.
 ```
 
 No broker. No Pact DSL. Language-agnostic. Works in 30 seconds. Local mode never uploads your specs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specshield",
-  "version": "3.2.7",
-  "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
+  "version": "3.2.9",
+  "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
   "main": "src/cli.js",
   "bin": {
     "specshield": "./bin/specshield.js"

package/src/core/classifyChanges.js

@@ -21,6 +21,10 @@ const BREAKING_TYPES = new Set([
   'REQUEST_TYPE_CHANGED',
   'RESPONSE_TYPE_CHANGED',
   'SCHEMA_REMOVED',
+  // Dropping a union variant, or changing the discriminator, breaks consumers
+  // that relied on the removed shape / the old discriminator.
+  'SCHEMA_VARIANT_REMOVED',
+  'SCHEMA_DISCRIMINATOR_CHANGED',
   // Constraint tightening: previously-valid values become invalid → breaking.
   'CONSTRAINT_TIGHTENED',
   // Pattern changes are treated as breaking (semantic safety: we can't
@@ -36,6 +40,8 @@ const ADDITION_TYPES = new Set([
   'RESPONSE_FIELD_ADDED',
   'RESPONSE_ADDED',
   'SCHEMA_ADDED',
+  // Adding a union variant is backwards-compatible.
+  'SCHEMA_VARIANT_ADDED',
 ]);
 
 const MODIFICATION_TYPES = new Set([

package/src/core/diffEngine.js

@@ -323,6 +323,70 @@ function diffSchemaNode(path, method, fieldPrefix, base, target, diffs, isReques
       });
     }
   }
+
+  // additionalProperties (free-form map): compare the value schema so a
+  // breaking change inside map values is caught. ".<*>" denotes "any key".
+  if (base.additionalProperties || target.additionalProperties) {
+    const apField = `${fieldPrefix}.<*>`;
+    if (base.additionalProperties && target.additionalProperties) {
+      diffSchemaNode(path, method, apField, base.additionalProperties, target.additionalProperties, diffs, isRequest);
+    } else if (base.additionalProperties && !target.additionalProperties) {
+      diffs.push({
+        type: isRequest ? 'REQUEST_FIELD_REMOVED' : 'RESPONSE_FIELD_REMOVED',
+        path,
+        method,
+        field: apField,
+        description: `Map value schema (additionalProperties) removed from "${fieldPrefix}" in ${method.toUpperCase()} ${path}`,
+      });
+    }
+  }
+
+  // Discriminator rename/removal — breaks consumers keyed on the old name.
+  if (base.discriminator && base.discriminator !== target.discriminator) {
+    diffs.push({
+      type: 'SCHEMA_DISCRIMINATOR_CHANGED',
+      path,
+      method,
+      field: `${fieldPrefix}.discriminator`,
+      oldValue: base.discriminator,
+      newValue: target.discriminator || null,
+      description: `Discriminator at "${fieldPrefix}" changed from "${base.discriminator}" to "${target.discriminator || '(none)'}" in ${method.toUpperCase()} ${path}`,
+    });
+  }
+
+  // oneOf / anyOf variant comparison (positional; field-level changes inside a
+  // matched variant are caught by recursion). Mirrors the backend engine.
+  diffVariants(path, method, `${fieldPrefix}.oneOf`, base.oneOf, target.oneOf, diffs, isRequest);
+  diffVariants(path, method, `${fieldPrefix}.anyOf`, base.anyOf, target.anyOf, diffs, isRequest);
+}
+
+function diffVariants(path, method, fieldPrefix, baseVariants, targetVariants, diffs, isRequest) {
+  const b = Array.isArray(baseVariants) ? baseVariants : [];
+  const t = Array.isArray(targetVariants) ? targetVariants : [];
+  if (b.length === 0 && t.length === 0) return;
+
+  const matched = Math.min(b.length, t.length);
+  for (let i = 0; i < matched; i++) {
+    diffSchemaNode(path, method, `${fieldPrefix}[${i}]`, b[i], t[i], diffs, isRequest);
+  }
+  for (let i = t.length; i < b.length; i++) {
+    diffs.push({
+      type: 'SCHEMA_VARIANT_REMOVED',
+      path,
+      method,
+      field: `${fieldPrefix}[${i}]`,
+      description: `A schema variant was removed from "${fieldPrefix}" in ${method.toUpperCase()} ${path}`,
+    });
+  }
+  for (let i = b.length; i < t.length; i++) {
+    diffs.push({
+      type: 'SCHEMA_VARIANT_ADDED',
+      path,
+      method,
+      field: `${fieldPrefix}[${i}]`,
+      description: `A schema variant was added to "${fieldPrefix}" in ${method.toUpperCase()} ${path}`,
+    });
+  }
 }
 
 // ─── Constraints (min/max, length, pattern) ─────────────────────────────────

package/src/core/normalizeSpec.js

@@ -102,20 +102,30 @@ function resolveSchema(schema, schemas, depth = 0) {
     return resolveSchema(resolved, schemas, depth + 1);
   }
 
-  // Handle allOf / oneOf / anyOf by merging
+  // allOf = composition → merge into one combined object.
   if (schema.allOf) {
     return mergeSchemas(schema.allOf, schemas, depth);
   }
-  if (schema.oneOf || schema.anyOf) {
-    const list = schema.oneOf || schema.anyOf;
-    return mergeSchemas(list, schemas, depth);
+  // oneOf / anyOf are NOT merged — they're kept as separate variants below so
+  // the diff engine can compare variants individually (added/removed variants
+  // + per-variant field changes). This matches the backend's variant-aware
+  // model; merging would lose variant identity and over-mark `required`.
+
+  // OpenAPI 3.1 expresses nullability as a type array: `type: [x, "null"]`.
+  // Normalize that to a single base type + nullable flag so it compares cleanly
+  // against 3.0's `nullable: true` form and doesn't surface a bogus type change.
+  let resolvedType = schema.type;
+  let resolvedNullable = Boolean(schema.nullable);
+  if (Array.isArray(resolvedType)) {
+    if (resolvedType.includes('null')) resolvedNullable = true;
+    resolvedType = resolvedType.find((t) => t !== 'null') || 'object';
   }
 
   const node = {
-    type: schema.type || 'object',
+    type: resolvedType || 'object',
     format: schema.format || null,
     enum: schema.enum || null,
-    nullable: Boolean(schema.nullable),
+    nullable: resolvedNullable,
     required: Array.isArray(schema.required) ? schema.required : [],
     properties: {},
     items: null,
@@ -143,6 +153,23 @@ function resolveSchema(schema, schemas, depth = 0) {
     node.items = resolveSchema(schema.items, schemas, depth + 1);
   }
 
+  // additionalProperties as a schema = a free-form map/dictionary value type
+  // (e.g. Map<String, Metric>). Boolean true/false is not a value schema.
+  if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+    node.additionalProperties = resolveSchema(schema.additionalProperties, schemas, depth + 1);
+  }
+
+  // oneOf / anyOf variants kept separate (variant-aware model).
+  if (Array.isArray(schema.oneOf)) {
+    node.oneOf = schema.oneOf.map((s) => resolveSchema(s, schemas, depth + 1));
+  }
+  if (Array.isArray(schema.anyOf)) {
+    node.anyOf = schema.anyOf.map((s) => resolveSchema(s, schemas, depth + 1));
+  }
+  if (schema.discriminator && schema.discriminator.propertyName) {
+    node.discriminator = schema.discriminator.propertyName;
+  }
+
   return node;
 }