feat(openapi-ruleset-utilities): add type declaration files (#743)

This allows the package to integrate with TypeScript-developed rulesets
that need to rely on the utilities in this package.

Signed-off-by: Dustin Popp <[email protected]>

Author: dpopp07

.github/pull_request_template.md

@@ -11,7 +11,7 @@ Please make sure that your PR fulfills the following requirements:
 - [ ] Docs have been added / updated (for bug fixes / features)
 - [ ] Dependencies have been updated as needed
 - [ ] `.secrets.baseline` has been updated as needed
-- [ ] `npm run generate-utilities-docs` has been run if any files in `packages/utilities/src` have been updated
+- [ ] `npm run update-utilities` has been run if any files in `packages/utilities/src` have been updated
 
 #### Checklist for adding a new validation rule:
 - [ ] Added new validation rule definition (packages/ruleset/src/rules/*.js, index.js)

package-lock.json

@@ -29,7 +29,9 @@
     "unlink": "npm run unlink --workspace packages/validator",
     "all": "npm run test && npm run lint",
     "format-readme-toc": "npx -y markdown-toc --maxdepth 5 -i README.md",
-    "generate-utilities-docs": "scripts/generate-utilities-docs.js"
+    "generate-utilities-docs": "scripts/generate-utilities-docs.js",
+    "generate-utilities-types": "npm run generate-types -w packages/utilities",
+    "update-utilities": "npm run generate-utilities-docs && npm run generate-utilities-types"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

package.json

@@ -5,6 +5,7 @@
   "license": "Apache-2.0",
   "private": false,
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/IBM/openapi-validator.git",
@@ -17,11 +18,13 @@
     "test-travis": "jest --silent --runInBand --no-colors --testNamePattern='^((?!@skip-ci).)*$' test",
     "lint": "eslint --cache --quiet --ext '.js' src test",
     "fix": "eslint --fix --ext '.js' src test",
+    "generate-types": "tsc",
     "pkg": "echo no executables to build in this package"
   },
   "devDependencies": {
     "@stoplight/spectral-core": "^1.19.4",
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "typescript": "^5.8.3"
   },
   "engines": {
     "node": ">=16.0.0"

packages/utilities/package.json

@@ -0,0 +1,23 @@
+{
+  // Used to auto-generate TS types for this utilities package,
+  // so that it can be imported into other rulesets developed in TS.
+
+  "include": ["src/**/*"],
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files.
+    "allowJs": true,
+    // Generate d.ts files.
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files.
+    "emitDeclarationOnly": true,
+    // Types should go into this directory.
+    // Removing this would place the .d.ts files
+    // next to the .js files.
+    "outDir": "types",
+    // Go to js file when using IDE functions like
+    // "Go to Definition" in VSCode.
+    "declarationMap": true
+  }
+}

packages/utilities/tsconfig.json

@@ -0,0 +1,16 @@
+/**
+ * Copyright 2017 - 2024 IBM Corporation.
+ * SPDX-License-Identifier: Apache2.0
+ */
+export const operations: string[];
+export const requestBodySchemas: string[];
+export const responseSchemas: string[];
+export const unresolvedRequestBodySchemas: string[];
+export const unresolvedResponseSchemas: string[];
+export declare let parameters: string[];
+export declare let patchOperations: string[];
+export declare let paths: string[];
+export declare let schemas: string[];
+export declare let securitySchemes: string[];
+export declare let unresolvedSchemas: string[];
+//# sourceMappingURL=index.d.ts.map

packages/utilities/types/collections/index.d.ts

@@ -0,0 +1,67 @@
+declare const _exports: {
+    collections: {
+        operations: string[];
+        parameters: string[];
+        patchOperations: string[];
+        paths: string[];
+        requestBodySchemas: string[];
+        responseSchemas: string[];
+        schemas: string[];
+        securitySchemes: string[];
+        unresolvedRequestBodySchemas: string[];
+        unresolvedResponseSchemas: string[];
+        unresolvedSchemas: string[];
+    };
+    validateComposedSchemas: typeof import("./utils/validate-composed-schemas");
+    validateNestedSchemas: typeof import("./utils/validate-nested-schemas");
+    validateSubschemas: typeof import("./utils/validate-subschemas");
+    getNodes: typeof import("./utils/spectral-context-utils").getNodes;
+    getResolvedSpec: typeof import("./utils/spectral-context-utils").getResolvedSpec;
+    getUnresolvedSpec: typeof import("./utils/spectral-context-utils").getUnresolvedSpec;
+    isObject: typeof import("./utils/is-object");
+    schemaHasConstraint: typeof import("./utils/schema-has-constraint");
+    schemaHasProperty: typeof import("./utils/schema-has-property");
+    schemaLooselyHasConstraint: typeof import("./utils/schema-loosely-has-constraint");
+    schemaRequiresProperty: typeof import("./utils/schema-requires-property");
+    SchemaType: {
+        ARRAY: symbol;
+        BINARY: symbol;
+        BOOLEAN: symbol;
+        BYTE: symbol;
+        DATE: symbol;
+        DATE_TIME: symbol;
+        DOUBLE: symbol;
+        ENUMERATION: symbol;
+        FLOAT: symbol;
+        INT32: symbol;
+        INT64: symbol;
+        INTEGER: symbol;
+        NUMBER: symbol;
+        OBJECT: symbol;
+        STRING: symbol;
+        UNKNOWN: symbol;
+    };
+    getSchemaType: typeof import("./utils/get-schema-type").getSchemaType;
+    isArraySchema: typeof import("./utils/get-schema-type").isArraySchema;
+    isBinarySchema: typeof import("./utils/get-schema-type").isBinarySchema;
+    isBooleanSchema: typeof import("./utils/get-schema-type").isBooleanSchema;
+    isByteSchema: typeof import("./utils/get-schema-type").isByteSchema;
+    isDateSchema: typeof import("./utils/get-schema-type").isDateSchema;
+    isDateTimeSchema: typeof import("./utils/get-schema-type").isDateTimeSchema;
+    isDoubleSchema: typeof import("./utils/get-schema-type").isDoubleSchema;
+    isEnumerationSchema: typeof import("./utils/get-schema-type").isEnumerationSchema;
+    isFloatSchema: typeof import("./utils/get-schema-type").isFloatSchema;
+    isInt32Schema: typeof import("./utils/get-schema-type").isInt32Schema;
+    isInt64Schema: typeof import("./utils/get-schema-type").isInt64Schema;
+    isIntegerSchema: typeof import("./utils/get-schema-type").isIntegerSchema;
+    isNumberSchema: typeof import("./utils/get-schema-type").isNumberSchema;
+    isObjectSchema: typeof import("./utils/get-schema-type").isObjectSchema;
+    isPrimitiveSchema: typeof import("./utils/get-schema-type").isPrimitiveSchema;
+    isStringSchema: typeof import("./utils/get-schema-type").isStringSchema;
+    schemaIsOfType: typeof import("./utils/get-schema-type").schemaIsOfType;
+    collectFromComposedSchemas: typeof import("./utils/collect-from-composed-schemas");
+    getExamplesForSchema: typeof import("./utils/get-examples-for-schema");
+    getPropertyNamesForSchema: typeof import("./utils/get-property-names-for-schema");
+};
+export = _exports;
+//# sourceMappingURL=index.d.ts.map

packages/utilities/types/collections/index.d.ts.map

@@ -0,0 +1,17 @@
+export = collectFromComposedSchemas;
+/**
+ * Copyright 2024 IBM Corporation.
+ * SPDX-License-Identifier: Apache2.0
+ */
+/**
+ * Returns an array of items collected by the provided `collector(schema) => item[]` function for a
+ * simple or composite schema, and deduplicates primitives in the result. The collector function is
+ * not run for `null` or `undefined` schemas.
+ * @param {object} schema simple or composite OpenAPI 3.x schema object
+ * @param {Function} collector a `(schema) => item[]` function to collect items from each simple schema
+ * @param {boolean} includeSelf collect from the provided schema in addition to its composed schemas (defaults to `true`)
+ * @param {boolean} includeNot collect from schemas composed with `not` (defaults to `false`)
+ * @returns {Array} collected items
+ */
+declare function collectFromComposedSchemas(schema: object, collector: Function, includeSelf?: boolean, includeNot?: boolean): any[];
+//# sourceMappingURL=collect-from-composed-schemas.d.ts.map