Logic for propagating suppressions.

Author: tjprescott

src/definitions.ts

@@ -5,10 +5,9 @@ import {
   parseReference,
   ReferenceMetadata,
   toSorted,
+  getRegistryName,
 } from "./util.js";
-import * as fs from "fs";
 import path from "path";
-import { SuppressionRegistry } from "./suppression.js";
 
 /** The registry to look up the name within. */
 export enum RegistryKind {
@@ -33,7 +32,7 @@ class CollectionRegistry {
       if (subdata !== undefined) {
         for (const [name, _] of toSorted(Object.entries(subdata))) {
           const resolvedPath = getResolvedPath(filepath).replace(/\\/g, "/");
-          const pathKey = `${resolvedPath}#/${this.getRegistryName()}/${name}`;
+          const pathKey = `${resolvedPath}#/${getRegistryName(this.kind)}/${name}`;
           // we don't care about unreferenced common-types
           if (!resolvedPath.includes("common-types")) {
             this.unreferenced.add(pathKey);
@@ -43,19 +42,6 @@ class CollectionRegistry {
     }
   }
 
-  getRegistryName(): string {
-    switch (this.kind) {
-      case RegistryKind.Definition:
-        return "definitions";
-      case RegistryKind.Parameter:
-        return "parameters";
-      case RegistryKind.Response:
-        return "responses";
-      case RegistryKind.SecurityDefinition:
-        return "securityDefinitions";
-    }
-  }
-
   /** Add or update an item. */
   add(itemPath: string, name: string, value: any) {
     const resolvedPath = getResolvedPath(itemPath);
@@ -77,7 +63,7 @@ class CollectionRegistry {
   countReference(path: string, name: string, kind: RegistryKind) {
     // convert backslashes to forward slashes
     path = path.replace(/\\/g, "/");
-    const pathKey = `${path}#/${this.getRegistryName()}/${name}`;
+    const pathKey = `${path}#/${getRegistryName(this.kind)}/${name}`;
     this.unreferenced.delete(pathKey);
   }
 

src/diff-client.ts

@@ -24,10 +24,11 @@ export interface DiffClientConfig {
 
 export class DiffClient {
   public args: any;
+  public suppressions?: SuppressionRegistry;
+
   private rules: RuleSignature[];
   private lhsParser?: SwaggerParser;
   private rhsParser?: SwaggerParser;
-  private suppressions?: SuppressionRegistry;
   /** Tracks if shortenKeys has been called to avoid re-running the algorithm needlessly. */
   private keysShortened: boolean = false;
 
@@ -251,7 +252,10 @@ export class DiffClient {
 
     // if a violation is suppressed, keep metadata the same but change it from a
     // flagged or assumed violation to `RuleResult.Suppressed`.
-    const isSuppressed = this.suppressions.has(getUrlEncodedPath(data.path));
+    const urlEncodedPath = getUrlEncodedPath(data.path);
+    const isSuppressed = this.suppressions
+      ? this.suppressions.has(urlEncodedPath)
+      : false;
     const finalRuleResult =
       (Array.isArray(finalResult) ? finalResult[0] : finalResult) ??
       RuleResult.AssumedViolation;

src/parser.ts

@@ -3,6 +3,7 @@ import { OpenAPIV2 } from "openapi-types";
 import { DefinitionRegistry, RegistryKind } from "./definitions.js";
 import {
   forceArray,
+  getUrlEncodedPath,
   isReference,
   loadPaths,
   parseReference,
@@ -27,7 +28,9 @@ export class SwaggerParser {
   private host?: string;
   private result: any = {};
   private defRegistry?: DefinitionRegistry;
+  private client?: DiffClient;
   private swaggerMap?: Map<string, any>;
+  private currentPath?: string[];
 
   /**
    * Creates a new SwaggerParser instance asynchronously.
@@ -44,6 +47,7 @@ export class SwaggerParser {
     const pathMap = await loadPaths(forceArray(paths), rootPath, client.args);
     parser.defRegistry = new DefinitionRegistry(pathMap, client);
     parser.swaggerMap = pathMap;
+    parser.client = client;
     return parser;
   }
 
@@ -55,6 +59,7 @@ export class SwaggerParser {
     if (!this.defRegistry) {
       throw new Error("Definition registry is not initialized.");
     }
+    this.currentPath = [];
     const allPathsUnsorted: any = {};
     for (const [_, data] of this.swaggerMap.entries()) {
       // Retrieve any top-level defaults that need to be normalized later on.
@@ -74,12 +79,15 @@ export class SwaggerParser {
 
       // combine the paths and x-ms-paths objects and merge into overall paths object
       const allPaths = { ...paths, ...xMsPaths };
+      this.currentPath?.push("paths");
       const newPaths = this.#parsePaths(allPaths);
       for (const [path, data] of Object.entries(newPaths)) {
         allPathsUnsorted[path] = data;
       }
+      this.currentPath?.pop();
 
       for (const [key, val] of toSorted(Object.entries(data))) {
+        this.currentPath?.push(key);
         switch (key) {
           case "swagger":
           case "info":
@@ -116,6 +124,7 @@ export class SwaggerParser {
           default:
             throw new Error(`Unhandled root key: ${key}`);
         }
+        this.currentPath?.pop();
       }
     }
     // sort all the paths and add into the result
@@ -194,6 +203,7 @@ export class SwaggerParser {
   #parseResponse(value: any): any {
     let result: any = {};
     for (const [key, val] of toSorted(Object.entries(value))) {
+      this.currentPath?.push(key);
       if (key === "headers") {
         result[key] = {};
         for (const [headerKey, headerVal] of toSorted(
@@ -205,6 +215,7 @@ export class SwaggerParser {
       } else {
         result[key] = this.#parseNode(val);
       }
+      this.currentPath?.pop();
     }
     return result;
   }
@@ -238,6 +249,7 @@ export class SwaggerParser {
   #parseResponses(value: any): any {
     let result: any = {};
     for (const [code, data] of toSorted(Object.entries(value))) {
+      this.currentPath?.push(code);
       if (code === "default") {
         // Don't expand the default response. We will handle this in a special way.
         const errorName = this.#parseErrorName(data);
@@ -252,6 +264,7 @@ export class SwaggerParser {
       } else {
         result[code] = this.#parseResponse(data);
       }
+      this.currentPath?.pop();
     }
     return result;
   }
@@ -262,6 +275,7 @@ export class SwaggerParser {
     value["consumes"] = value["consumes"] ?? this.defaultConsumes;
     value["produces"] = value["produces"] ?? this.defaultProduces;
     for (const [key, val] of toSorted(Object.entries(value))) {
+      this.currentPath?.push(key);
       if (key === "parameters") {
         // mix in any parameters from parameterized host
         const hostParams = this.parameterizedHost?.parameters ?? [];
@@ -301,6 +315,7 @@ export class SwaggerParser {
       } else {
         result[key] = this.#parseNode(value[key]);
       }
+      this.currentPath?.pop();
     }
     return result;
   }
@@ -309,7 +324,9 @@ export class SwaggerParser {
   #parseVerbs(value: any): any {
     let result: any = {};
     for (const [verb, data] of toSorted(Object.entries(value))) {
+      this.currentPath?.push(verb);
       result[verb] = this.#parseOperation(data);
+      this.currentPath?.pop();
     }
     return result;
   }
@@ -320,7 +337,10 @@ export class SwaggerParser {
     for (const [operationPath, pathData] of Object.entries(value)) {
       // normalize the path to coerce the naming convention
       const normalizedPath = this.#normalizePath(operationPath);
+      const urlEncodedPath = getUrlEncodedPath([normalizedPath])!;
+      this.currentPath?.push(urlEncodedPath);
       result[normalizedPath] = this.#parseVerbs(pathData);
+      this.currentPath?.pop();
     }
     return result;
   }
@@ -330,8 +350,10 @@ export class SwaggerParser {
     if (value.length > 0 && typeof value[0] === "object") {
       const values: any[] = [];
       for (let i = 0; i < value.length; i++) {
+        this.currentPath?.push(i.toString());
         const item = value[i];
         values.push(this.#parseNode(item));
+        this.currentPath?.pop();
       }
       return values;
     } else {
@@ -377,12 +399,18 @@ export class SwaggerParser {
           refResult.registry
         );
       }
+      this.client?.suppressions?.propagateSuppression(
+        refResult,
+        this.currentPath
+      );
       return this.#parseObject(resolved);
     }
     const result: any = {};
     // visit each key in the object in sorted order
     for (const [key, val] of toSorted(Object.entries(value))) {
+      this.currentPath?.push(key);
       result[key] = this.#parseNode(val);
+      this.currentPath?.pop();
     }
     return result;
   }

src/suppression.ts

@@ -1,20 +1,21 @@
 import * as fs from "fs";
 import { parse } from "yaml";
+import { getRegistryName, ReferenceMetadata } from "./util.js";
 
 export interface SuppressionMetadata {
   path: string;
   reason: string;
 }
 
 export class SuppressionRegistry {
-  data = new Set<string>();
+  private data = new Set<string>();
 
   constructor(filepath: string) {
     const contents = fs.readFileSync(filepath, "utf8");
-    const data: SuppressionMetadata[] = parse(contents);
+    const data: SuppressionMetadata[] = parse(contents) ?? [];
     for (const item of data) {
       let path = item.path.trim().toLowerCase();
-      this.data.add(path);
+      this.add(path);
     }
   }
 
@@ -24,9 +25,8 @@ export class SuppressionRegistry {
    * @param key the Swagger path which serves as a key
    * @param path the transformed path to add to the suppression list
    */
-  add(key: string, path: string) {
+  add(path: string) {
     path = path.trim().toLowerCase();
-    key = key.toLowerCase();
     this.data.add(path);
   }
 
@@ -37,6 +37,20 @@ export class SuppressionRegistry {
   has(path: string | undefined): boolean {
     if (!path) return false;
     path = path.trim().toLowerCase();
-    return this.data.has(path);
+    const value = this.data.has(path);
+    return value;
+  }
+
+  propagateSuppression(ref: ReferenceMetadata, basePath: string[] | undefined) {
+    if (!basePath) throw new Error("basePath is undefined");
+    const base = basePath.join("/");
+    const target = `${getRegistryName(ref.registry)}/${ref.name}`.toLowerCase();
+    for (const item of this.data) {
+      if (item.startsWith(target)) {
+        // create a new string suppression propagating the suppression onto the base path
+        const newItem = item.replace(target, base);
+        this.add(newItem);
+      }
+    }
   }
 }

src/util.ts

@@ -428,3 +428,19 @@ export function getUrlEncodedPath(
   if (segments === undefined) return undefined;
   return segments.map((x: string) => encodeURIComponent(x)).join("/");
 }
+
+/**
+ * Returns the string key for the `RegistryKind` enum.
+ */
+export function getRegistryName(kind: RegistryKind): string {
+  switch (kind) {
+    case RegistryKind.Definition:
+      return "definitions";
+    case RegistryKind.Parameter:
+      return "parameters";
+    case RegistryKind.Response:
+      return "responses";
+    case RegistryKind.SecurityDefinition:
+      return "securityDefinitions";
+  }
+}

suppression.yaml

@@ -1,4 +1,2 @@
 - path: definitions/Foo/properties/age/format
   reason: Because a really good reason.
-- path: paths/%2F/get/responses/200/schema/properties/age/format
-  reason: This reason is amazing.

test/files/suppressions1a.json

@@ -0,0 +1,57 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "(title)",
+    "version": "0000-00-00",
+    "x-typespec-generated": [
+      {
+        "emitter": "@azure-tools/typespec-autorest"
+      }
+    ]
+  },
+  "schemes": ["https"],
+  "produces": ["application/json"],
+  "consumes": ["application/json"],
+  "tags": [],
+  "paths": {
+    "/": {
+      "put": {
+        "operationId": "CreateFoo",
+        "parameters": [
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/Foo"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "schema": {
+              "$ref": "#/definitions/Foo"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "Foo": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "age": {
+          "type": "integer",
+          "format": "int16"
+        }
+      },
+      "required": ["name", "age"]
+    }
+  },
+  "parameters": {}
+}