@ir-kit/openapi-loader 0.2.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Load an OpenAPI 3.x spec from a file path, URL, or pre-parsed object. Bundles `$ref`s via `@hey-api/json-schema-ref-parser` and runs optional hey-api-aware normalization.
 
-Part of [ir-kit](https://github.com/ir-kit/ir-kit). For multi-format input (OpenAPI + AsyncAPI + TypeSpec under one API), reach for [`@ir-kit/spec-loader`](../../shared/spec-loader) instead.
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). For multi-format input (OpenAPI + AsyncAPI + TypeSpec under one API), reach for [`@ir-kit/spec-loader`](../../shared/spec-loader) instead.
 
 ## Install
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { type NormalizeOptions } from "@ir-kit/openapi";
+import { type Type } from "js-yaml";
 export type OpenAPIInput = string | Record<string, unknown>;
 export interface LoadOpenAPIOptions {
     input: OpenAPIInput;
@@ -7,6 +8,19 @@ export interface LoadOpenAPIOptions {
      *  the safe preset; pass an object for custom rules. */
     normalize?: boolean | NormalizeOptions;
 }
+/** Parse a spec file, URL or object into its raw root document without resolving refs. */
+export declare function readSpecDocument(input: OpenAPIInput, cwd?: string): Promise<Record<string, unknown>>;
 export declare function loadOpenAPI(opts: LoadOpenAPIOptions): Promise<Record<string, unknown>>;
+declare module "js-yaml" {
+    const types: {
+        merge: Type;
+    };
+}
+/**
+ * `x-` extensions are opaque to OpenAPI, so an external `$ref` inside one
+ * (Spotify's `x-spotify-policy: { $ref: ../policies.yaml }`) is data, not a
+ * dependency of the spec. Rename it to `x-$ref` so bundling never fetches it.
+ */
+export declare function detachExtensionRefs(node: unknown, inExtension?: boolean): void;
 export declare function resolveOpenAPIInput(input: OpenAPIInput, cwd?: string): OpenAPIInput;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;4DACwD;IACxD,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;CACxC;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAalC;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,GAAG,GAAE,MAAsB,GAC1B,YAAY,CASd"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,gBAAgB,EAGtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAqB,KAAK,IAAI,EAAS,MAAM,SAAS,CAAC;AAE9D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;4DACwD;IACxD,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;CACxC;AAED,0FAA0F;AAC1F,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,YAAY,EACnB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKlC;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0BlC;AAED,OAAO,QAAQ,SAAS,CAAC;IAEvB,MAAM,KAAK,EAAE;QAAE,KAAK,EAAE,IAAI,CAAA;KAAE,CAAC;CAC9B;AA4CD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,UAAQ,GAAG,IAAI,CAuB5E;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,GAAG,GAAE,MAAsB,GAC1B,YAAY,CASd"}

package/dist/index.js

@@ -1,15 +1,105 @@
 import { isAbsolute, resolve } from "node:path";
-import { $RefParser } from "@hey-api/json-schema-ref-parser";
-import { normalizeSpec, SAFE_NORMALIZE, } from "@ir-kit/openapi";
+import { $RefParser, ParserError, } from "@hey-api/json-schema-ref-parser";
+import { hoistForeignSchemaRefs, normalizeSpec, SAFE_NORMALIZE, } from "@ir-kit/openapi";
+import { CORE_SCHEMA, load, types } from "js-yaml";
+/** Parse a spec file, URL or object into its raw root document without resolving refs. */
+export async function readSpecDocument(input, cwd) {
+    const { schema } = await createParser().parse({
+        pathOrUrlOrSchema: resolveOpenAPIInput(input, cwd),
+    });
+    return schema;
+}
 export async function loadOpenAPI(opts) {
-    const bundled = (await new $RefParser().bundle({
-        pathOrUrlOrSchema: resolveOpenAPIInput(opts.input, opts.cwd),
+    const parser = createParser();
+    const input = resolveOpenAPIInput(opts.input, opts.cwd);
+    const { schema } = await parser.parse({ pathOrUrlOrSchema: input });
+    const root = parser.$refs._root$Ref;
+    detachExtensionRefs(schema);
+    const bundled = (await parser.bundle({
+        pathOrUrlOrSchema: input,
+        resolvedInput: {
+            path: root.path ?? "",
+            schema,
+            type: typeof input === "string" ? root.pathType : "json",
+        },
     }));
+    hoistForeignSchemaRefs(bundled);
     if (opts.normalize) {
         normalizeSpec(bundled, opts.normalize === true ? SAFE_NORMALIZE : opts.normalize);
     }
     return bundled;
 }
+// why: js-yaml's default YAML 1.1 schema turns unquoted dates such as
+// Stripe's `api_version` enum (`- 2011-01-01`) into `Date` objects, which
+// codegen then drops; the YAML 1.2 core schema keeps them as strings.
+// `<<` merge keys stay supported, as specs use them to share fields.
+const YAML_SCHEMA = CORE_SCHEMA.extend({ implicit: [types.merge] });
+function createParser() {
+    const parser = new $RefParser();
+    parser.options.parse.yaml.handler = (file) => {
+        const data = Buffer.isBuffer(file.data) ? file.data.toString() : file.data;
+        if (typeof data !== "string")
+            return data;
+        try {
+            return load(data, { schema: YAML_SCHEMA });
+        }
+        catch (error) {
+            throw new ParserError(error.message, file.url);
+        }
+    };
+    return parser;
+}
+/** Keys whose children are user-named entries, never `x-` extensions. */
+const NAMED_ENTRY_MAPS = new Set([
+    "$defs",
+    "callbacks",
+    "content",
+    "definitions",
+    "encoding",
+    "examples",
+    "headers",
+    "links",
+    "mapping",
+    "parameters",
+    "pathItems",
+    "patternProperties",
+    "properties",
+    "requestBodies",
+    "responses",
+    "schemas",
+    "securitySchemes",
+    "variables",
+]);
+/**
+ * `x-` extensions are opaque to OpenAPI, so an external `$ref` inside one
+ * (Spotify's `x-spotify-policy: { $ref: ../policies.yaml }`) is data, not a
+ * dependency of the spec. Rename it to `x-$ref` so bundling never fetches it.
+ */
+export function detachExtensionRefs(node, inExtension = false) {
+    if (!node || typeof node !== "object")
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            detachExtensionRefs(item, inExtension);
+        return;
+    }
+    const obj = node;
+    if (inExtension &&
+        typeof obj.$ref === "string" &&
+        !obj.$ref.startsWith("#")) {
+        obj["x-$ref"] = obj.$ref;
+        delete obj.$ref;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        if (NAMED_ENTRY_MAPS.has(key) && value && typeof value === "object") {
+            for (const entry of Object.values(value))
+                detachExtensionRefs(entry, inExtension);
+        }
+        else {
+            detachExtensionRefs(value, inExtension || key.startsWith("x-"));
+        }
+    }
+}
 export function resolveOpenAPIInput(input, cwd = process.cwd()) {
     if (typeof input !== "string")
         return input;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAEL,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC;AAYzB,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB;IAExB,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC,MAAM,CAAC;QAC7C,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC;KAC7D,CAAC,CAA4B,CAAC;IAE/B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,aAAa,CACX,OAAO,EACP,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAC1D,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,KAAmB,EACnB,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAClD,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ir-kit/openapi-loader",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Load an OpenAPI 3.x spec from a file path, URL, or pre-parsed object. Bundles `$ref`s via `@hey-api/json-schema-ref-parser` and runs optional hey-api-aware normalization.",
   "keywords": [
     "openapi",
@@ -9,9 +9,9 @@
     "spec",
     "ir-kit"
   ],
-  "homepage": "https://github.com/ir-kit/ir-kit/tree/main/packages/openapi/loader",
+  "homepage": "https://github.com/ahmedrowaihi/ir-kit/tree/main/packages/openapi/loader",
   "bugs": {
-    "url": "https://github.com/ir-kit/ir-kit/issues"
+    "url": "https://github.com/ahmedrowaihi/ir-kit/issues"
   },
   "license": "MIT",
   "author": {
@@ -20,7 +20,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ir-kit/ir-kit.git",
+    "url": "git+https://github.com/ahmedrowaihi/ir-kit.git",
     "directory": "packages/openapi/loader"
   },
   "type": "module",
@@ -44,10 +44,12 @@
     "provenance": true
   },
   "dependencies": {
-    "@hey-api/json-schema-ref-parser": "^1.4.1",
-    "@ir-kit/openapi": "0.3.0"
+    "@hey-api/json-schema-ref-parser": "^1.4.4",
+    "js-yaml": "^4.1.0",
+    "@ir-kit/openapi": "0.5.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22",
     "vitest": "^4.0.0",
     "@ir-kit/tsconfig": "0.0.0"