types: Add declarations for openapi-examples-validator.

Signed-off-by: Anders Kaseorg <anders@zulip.com>

.codespellignore

@@ -30,3 +30,4 @@ assertIn
 thirdparty
 asend
 COO
+statics

web/src/types/openapi-examples-validator/application-error.d.ts

@@ -0,0 +1,60 @@
+export enum ErrorType {
+    jsENOENT = "ENOENT",
+    jsonPathNotFound = "JsonPathNotFound",
+    errorAndErrorsMutuallyExclusive = "ErrorErrorsMutuallyExclusive",
+    parseError = "ParseError",
+    validation = "Validation",
+}
+
+export type ApplicationErrorOptions = {
+    instancePath?: string;
+    examplePath?: string;
+    exampleFilePath?: string;
+    keyword?: string;
+    message?: string;
+    mapFilePath?: string;
+    params?: {
+        path?: string;
+        missingProperty?: string;
+        type?: string;
+    };
+    schemaPath?: string;
+};
+
+/**
+ * Unified application-error
+ */
+export class ApplicationError {
+    /**
+     * Factory-function, which is able to consume validation-errors and
+     * JS-errors. If a validation error is passed, all properties will be
+     * adopted.
+     *
+     * @param err - Javascript-, validation- or custom-error, to create the
+     * application-error from
+     * @returns Unified application-error instance
+     */
+    static create(err: Error): ApplicationError;
+
+    /**
+     * Constructor
+     *
+     * @param type - Type of error (see statics)
+     * @param options - Optional properties
+     */
+    constructor(type: ErrorType, options?: ApplicationErrorOptions);
+
+    type: ErrorType;
+    instancePath?: string;
+    examplePath?: string;
+    exampleFilePath?: string;
+    keyword?: string;
+    message?: string;
+    mapFilePath?: string;
+    params?: {
+        path?: string;
+        missingProperty?: string;
+        type?: string;
+    };
+    schemaPath?: string;
+}

web/src/types/openapi-examples-validator/index.d.ts

@@ -0,0 +1,137 @@
+import type {ApplicationError} from "./application-error.d.ts";
+
+declare namespace OpenApiExamplesValidator {
+    export type ValidationStatistics = {
+        schemasWithExamples: number;
+        examplesTotal: number;
+        examplesWithoutSchema: number;
+        matchingFilePathsMapping?: number | undefined;
+    };
+
+    export type ValidationResponse = {
+        valid: boolean;
+        statistics: ValidationStatistics;
+        errors: ApplicationError[];
+    };
+
+    /**
+     * Validates OpenAPI-spec with embedded examples.
+     *
+     * @param openapiSpec - OpenAPI-spec
+     */
+    export function validateExamples(
+        openapiSpec: object,
+        options?: {
+            /**
+             * Don't allow properties that are not defined in the schema
+             */
+            noAdditionalProperties?: boolean | undefined;
+            /**
+             * Make all properties required
+             */
+            allPropertiesRequired?: boolean | undefined;
+            /**
+             * List of datatype formats that shall be ignored (to prevent
+             * "unsupported format" errors). If an Array with only one string is
+             * provided where the formats are separated with `\n`, the entries will
+             * be expanded to a new array containing all entries.
+             */
+            ignoreFormats?: string[] | undefined;
+        },
+    ): Promise<ValidationResponse>;
+    // eslint-disable-next-line unicorn/no-named-default
+    export {validateExamples as default};
+
+    /**
+     * Validates OpenAPI-spec with embedded examples.
+     *
+     * @param filePath - File-path to the OpenAPI-spec
+     */
+    export function validateFile(
+        filePath: string,
+        options?: {
+            /**
+             * Don't allow properties that are not defined in the schema
+             */
+            noAdditionalProperties?: boolean | undefined;
+            /**
+             * Make all properties required
+             */
+            allPropertiesRequired?: boolean | undefined;
+            /**
+             * List of datatype formats that shall be ignored (to prevent
+             * "unsupported format" errors). If an Array with only one string is
+             * provided where the formats are separated with `\n`, the entries will
+             * be expanded to a new array containing all entries.
+             */
+            ignoreFormats?: string[] | undefined;
+        },
+    ): Promise<ValidationResponse>;
+
+    /**
+     * Validates examples by mapping-files.
+     *
+     * @param filePathSchema - File-path to the OpenAPI-spec
+     * @param globMapExternalExamples - File-path (globs are supported) to the
+     * mapping-file containing JSON-paths to schemas as key and a single file-path
+     * or Array of file-paths to external examples
+     */
+    export function validateExamplesByMap(
+        filePathSchema: string,
+        globMapExternalExamples: string,
+        options?: {
+            /**
+             * Change working directory for resolving the example-paths (relative to
+             * the mapping-file)
+             */
+            cwdToMappingFile?: boolean | undefined;
+            /**
+             * Don't allow properties that are not defined in the schema
+             */
+            noAdditionalProperties?: boolean | undefined;
+            /**
+             * Make all properties required
+             */
+            allPropertiesRequired?: boolean | undefined;
+            /**
+             * List of datatype formats that shall be ignored (to prevent
+             * "unsupported format" errors). If an Array with only one string is
+             * provided where the formats are separated with `\n`, the entries will
+             * be expanded to a new array containing all entries.
+             */
+            ignoreFormats?: string[] | undefined;
+        },
+    ): Promise<ValidationResponse>;
+
+    /**
+     * Validates a single external example.
+     *
+     * @param filePathSchema - File-path to the OpenAPI-spec
+     * @param pathSchema - JSON-path to the schema
+     * @param filePathExample - File-path to the external example-file
+     */
+    export function validateExample(
+        filePathSchema: string,
+        pathSchema: string,
+        filePathExample: string,
+        options?: {
+            /**
+             * Don't allow properties that are not described in the schema
+             */
+            noAdditionalProperties?: boolean | undefined;
+            /**
+             * Make all properties required
+             */
+            allPropertiesRequired?: boolean | undefined;
+            /**
+             * List of datatype formats that shall be ignored (to prevent
+             * "unsupported format" errors). If an Array with only one string is
+             * provided where the formats are separated with `\n`, the entries will
+             * be expanded to a new array containing all entries.
+             */
+            ignoreFormats?: string[] | undefined;
+        },
+    ): Promise<ValidationResponse>;
+}
+
+export default OpenApiExamplesValidator;