Surface a schema assertion on bodies for rule runner (#2672)

Author: niclim

projects/openapi-utilities/src/openapi3/implementations/openapi3/__tests__/__snapshots__/openapi-traverser.test.ts.snap

@@ -26,6 +26,7 @@ import invariant from 'ts-invariant';
 import { jsonPointerHelpers as jsonPointer } from '@useoptic/json-pointer-helpers';
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { OAS3 } from '../../traverser';
+import { SchemaLocation } from '../../sdk/types/location';
 
 export function normalizeOpenApiPath(path: string): string {
   return path
@@ -53,7 +54,7 @@ const isObject = (value: any) => {
 };
 
 // TODO deprecate this usage of facts
-// This is currently used by the rule runner, openapi-cli and changelogv1
+// This is currently used by the rule runner
 export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
   format = 'openapi3';
 
@@ -472,6 +473,13 @@ export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
           )}, found ${schema}`
         );
       } else if (isNotReferenceObject(schema)) {
+        yield this.onSchema(schema, jsonPath, conceptualPath, {
+          ...location,
+          jsonSchemaTrail: [],
+          context: {
+            type: 'body',
+          },
+        });
         yield this.onContentForBody(
           schema,
           contentType,
@@ -540,6 +548,14 @@ export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
     location: FieldLocation
   ): IterableIterator<IFact> {
     this.checkJsonTrail(jsonPath, schema);
+    yield this.onSchema(schema, jsonPath, conceptualPath, {
+      ...location,
+      context: {
+        type: 'field',
+        key,
+        required,
+      },
+    });
     yield this.onField(
       key,
       schema,
@@ -551,7 +567,6 @@ export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
     yield* this.traverseSchema(schema, jsonPath, conceptualPath, location);
   }
 
-  // TODO discriminate between ArraySchemaObject | NonArraySchemaObject
   *traverseSchema(
     schema: OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject,
     jsonPath: string,
@@ -592,6 +607,10 @@ export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
             )}, found ${branchSchema}`
           );
         } else if (isNotReferenceObject(branchSchema)) {
+          yield this.onSchema(branchSchema, newJsonPath, newConceptualPath, {
+            ...location,
+            context: { type: branchType as any },
+          });
           yield* this.traverseSchema(
             branchSchema,
             newJsonPath,
@@ -647,14 +666,20 @@ export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
           )}, found ${arrayItems}`
         );
       } else if (isNotReferenceObject(arrayItems)) {
+        const nextConceptualPath = [...conceptualPath, 'items'];
+        const nextLocation = {
+          ...location,
+          jsonSchemaTrail: [...(location.jsonSchemaTrail || []), 'items'],
+        };
+        yield this.onSchema(arrayItems, nextJsonPath, nextConceptualPath, {
+          ...nextLocation,
+          context: { type: 'array' },
+        });
         yield* this.traverseSchema(
           arrayItems,
           nextJsonPath,
-          [...conceptualPath, 'items'],
-          {
-            ...location,
-            jsonSchemaTrail: [...(location.jsonSchemaTrail || []), 'items'],
-          }
+          nextConceptualPath,
+          nextLocation
         );
       } else {
         this.warnings.push(
@@ -797,6 +822,27 @@ export class OpenAPITraverser implements Traverse<OpenAPIV3.Document> {
     };
   }
 
+  onSchema(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject,
+    jsonPath: string,
+    conceptualPath: IPathComponent[],
+    location: SchemaLocation
+  ): FactVariant<OpenApiKind.Schema> {
+    const flatSchema = this.getSchemaFact(schema);
+
+    return {
+      value: {
+        flatSchema,
+      },
+      location: {
+        jsonPath,
+        conceptualPath,
+        conceptualLocation: location,
+        kind: OpenApiKind.Schema,
+      },
+    };
+  }
+
   onBodyExample(
     example: OpenAPIV3.ExampleObject | OpenAPIV3_1.ExampleObject,
     contentType: string,

projects/openapi-utilities/src/openapi3/implementations/openapi3/openapi-traverser.ts

@@ -48,7 +48,8 @@ export type OpenApiFact =
   | OpenApiBodyExampleFact
   | OpenApiFieldFact
   | OpenApiSpecificationFact
-  | OpenApiComponentSchemaExampleFact;
+  | OpenApiComponentSchemaExampleFact
+  | OpenApiSchemaFact;
 
 export interface OpenApiSpecificationFact
   extends Omit<OpenAPIV3.Document, 'paths' | 'components'> {}
@@ -72,6 +73,10 @@ export interface OpenApiBodyFact {
   flatSchema: OpenApi3SchemaFact;
 }
 
+export interface OpenApiSchemaFact {
+  flatSchema: OpenApi3SchemaFact;
+}
+
 export interface OpenApiBodyExampleFact extends OpenAPIV3.ExampleObject {
   contentType: string;
   name?: string;
@@ -120,6 +125,7 @@ export type OpenApiKindToFact = {
   [OpenApiKind.BodyExample]: OpenApiBodyExampleFact;
   [OpenApiKind.Field]: OpenApiFieldFact;
   [OpenApiKind.ComponentSchemaExample]: OpenApiComponentSchemaExampleFact;
+  [OpenApiKind.Schema]: OpenApiSchemaFact;
 };
 
 export interface FactVariant<FactKind extends OpenApiKind> {
@@ -175,7 +181,8 @@ export type IFact =
   | FactVariant<OpenApiKind.Body>
   | FactVariant<OpenApiKind.BodyExample>
   | FactVariant<OpenApiKind.Field>
-  | FactVariant<OpenApiKind.ComponentSchemaExample>;
+  | FactVariant<OpenApiKind.ComponentSchemaExample>
+  | FactVariant<OpenApiKind.Schema>;
 
 export type IChange =
   | ChangeVariant<OpenApiKind.Specification>
@@ -190,4 +197,5 @@ export type IChange =
   | ChangeVariant<OpenApiKind.Body>
   | ChangeVariant<OpenApiKind.BodyExample>
   | ChangeVariant<OpenApiKind.Field>
-  | ChangeVariant<OpenApiKind.ComponentSchemaExample>;
+  | ChangeVariant<OpenApiKind.ComponentSchemaExample>
+  | ChangeVariant<OpenApiKind.Schema>;

projects/openapi-utilities/src/openapi3/sdk/types/index.ts

@@ -96,6 +96,46 @@ export type FieldLocation = OperationLocation &
       }
   );
 
+type SchemaContext =
+  | {
+      type: 'polymorphic';
+      key: 'oneOf' | 'anyOf' | 'allOf';
+    }
+  | {
+      type: 'field';
+      key: string;
+      required: boolean;
+    }
+  | {
+      type: 'array';
+    }
+  | {
+      type: 'body';
+    };
+
+export type SchemaLocation = OperationLocation &
+  (
+    | {
+        inRequest: {
+          body: {
+            contentType: string;
+          };
+        };
+        jsonSchemaTrail: string[];
+        context: SchemaContext;
+      }
+    | {
+        inResponse: {
+          body: {
+            contentType: string;
+          };
+          statusCode: string;
+        };
+        jsonSchemaTrail: string[];
+        context: SchemaContext;
+      }
+  );
+
 export type ComponentSchemaLocation = {
   inComponentSchema: {
     schemaName: string;
@@ -141,6 +181,7 @@ export type ILocation = {
   | { conceptualLocation: BodyLocation; kind: OpenApiKind.Body }
   | { conceptualLocation: BodyExampleLocation; kind: OpenApiKind.BodyExample }
   | { conceptualLocation: FieldLocation; kind: OpenApiKind.Field }
+  | { conceptualLocation: SchemaLocation; kind: OpenApiKind.Schema }
   | {
       conceptualLocation: ComponentSchemaLocation;
       kind: OpenApiKind.ComponentSchemaExample;

projects/openapi-utilities/src/openapi3/sdk/types/location.ts

@@ -11,6 +11,7 @@ export enum OpenApiKind {
   Body = 'body',
   BodyExample = 'body-example',
   Field = 'field',
+  Schema = 'schema',
   ComponentSchemaExample = 'component-schema-example',
 }
 

projects/openapi-utilities/src/openapi3/sdk/types/openApiKinds.ts

@@ -6046,6 +6046,34 @@ exports[`groupChangesAndRules diffs and groups changes between two open api file
         },
       },
     },
+    "GET-~_~-/store/inventory" => {
+      "change": null,
+      "cookieParameters": {
+        "changes": Map {},
+        "hasRules": false,
+      },
+      "hasRules": false,
+      "headers": {
+        "changes": Map {},
+        "hasRules": false,
+      },
+      "method": "get",
+      "path": "/store/inventory",
+      "pathParameters": {
+        "changes": Map {},
+        "hasRules": false,
+      },
+      "queryParameters": {
+        "changes": Map {},
+        "hasRules": false,
+      },
+      "request": {
+        "bodyChanges": Map {},
+        "change": null,
+        "hasRules": false,
+      },
+      "responses": Map {},
+    },
     "POST-~_~-/store/order" => {
       "change": null,
       "cookieParameters": {

projects/openapi-utilities/src/utilities/__tests__/__snapshots__/group-changes.test.ts.snap

@@ -12,18 +12,6 @@ export type { SpecFileOperation } from './files';
 
 // patches and operations
 export { SpecFileOperations, SpecFiles, SpecFilesAsync } from './streams/files';
-export {
-  SpecFacts,
-  SpecFactsIterable,
-  BodyExampleFacts,
-  ComponentSchemaExampleFacts,
-  OperationFacts,
-} from './streams/facts';
-export type {
-  BodyExampleFact,
-  ComponentSchemaExampleFact,
-  OperationFact,
-} from './streams/facts';
 
 // templates
 export { SpecTemplate } from './templates';