feat: fail build if ref can't be resolved

CountRedClaw · CountRedClaw · commit 24a60d092d4c · 2025-03-21T22:20:57.000+05:00
diff --git a/src/apitypes/rest/rest.document.ts b/src/apitypes/rest/rest.document.ts
@@ -53,7 +53,7 @@ const openApiDocumentMeta = (data: OpenAPIV3.Document): RestDocumentInfo => {
 export const buildRestDocument: DocumentBuilder<OpenAPIV3.Document> = async (parsedFile, file, ctx) => {
   const { fileId, slug = '', publish = true, apiKind, ...fileMetadata } = file
 
-  const { data, dependencies } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver)
+  const { data, dependencies } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, !!ctx.config.strictValidation)
 
   let bundledFileData = data
 
diff --git a/src/apitypes/unknown/unknown.document.ts b/src/apitypes/unknown/unknown.document.ts
@@ -33,7 +33,7 @@ export const buildUnknownDocument: DocumentBuilder<string> = async (parsedFile,
       const {
         data,
         dependencies: fileDependencies,
-      } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver)
+      } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, !!ctx.config.strictValidation)
       bundledFileData = data
       dependencies = fileDependencies
     }
diff --git a/src/utils/document.ts b/src/utils/document.ts
@@ -32,6 +32,7 @@ import {
 } from '../types'
 import { bundle, Resolver } from 'api-ref-bundler'
 import { FILE_FORMAT_JSON, FILE_FORMAT_YAML } from '../consts'
+import { takeIf } from './objects'
 
 export const EXPORT_FORMAT_TO_FILE_FORMAT = new Map<OperationsGroupExportFormat, FileFormat>([
   [YAML_EXPORT_GROUP_FORMAT, FILE_FORMAT_YAML],
@@ -120,6 +121,7 @@ export const getDocumentTitle = (fileId: string): string => {
 export const getBundledFileDataWithDependencies = async (
   fileId: FileId,
   parsedFileResolver: _ParsedFileResolver,
+  throwOnBadRef: boolean,
 ): Promise<{ data: any; dependencies: string[] }> => {
   const dependencies: string[] = []
 
@@ -130,6 +132,8 @@ export const getBundledFileDataWithDependencies = async (
       return {}
     }
 
+    // todo: this error has no effect because it is suppressed here: https://github.com/udamir/api-ref-bundler/blob/master/src/resolver.ts#L33
+    // move this throw to bundler hooks or you'll see just "Cannot resolve: filename" message in case of wrong file kind
     if (data.kind !== FILE_KIND.TEXT) {
       throw new Error(`Dependency with path ${filepath} is not a text file`)
     }
@@ -141,7 +145,14 @@ export const getBundledFileDataWithDependencies = async (
     return data.data
   }
 
-  const bundledFileData = await bundle(fileId, resolver)
+  const bundledFileData = await bundle(fileId, resolver, {
+    hooks: {
+      ...takeIf(
+        { onError: (message: string) => { throw new Error(message) } },
+        throwOnBadRef,
+      ),
+    },
+  })
 
   return { data: bundledFileData, dependencies: dependencies }
 }
diff --git a/test/bundle-dependencies.test.ts b/test/bundle-dependencies.test.ts
diff --git a/test/projects/reference-bundling/case1/config.json b/test/projects/reference-bundling/case1/config.json
@@ -1,16 +1,16 @@
 {
-  "packageId": "bundle-dependencies",
+  "packageId": "reference-bundling",
   "apiType": "rest",
   "version": "v1",
   "files": [
     {
-      "fileId": "dependency.yaml",
+      "fileId": "reference.yaml",
       "publish": true,
       "labels": [],
       "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1cd"
     },
     {
-      "fileId": "main.yaml",
+      "fileId": "openapi.yaml",
       "publish": true,
       "labels": [],
       "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1xd"
diff --git a/test/projects/reference-bundling/case1/openapi.yaml b/test/projects/reference-bundling/case1/openapi.yaml
@@ -13,4 +13,4 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: './dependency.yaml#/User'
+                  $ref: './reference.yaml#/User'
diff --git a/test/projects/reference-bundling/case1/reference.yaml b/test/projects/reference-bundling/case1/reference.yaml
@@ -3,5 +3,3 @@ User:
   properties:
     id:
       type: integer
-    name:
-      type: string
diff --git a/test/projects/reference-bundling/case2/config.json b/test/projects/reference-bundling/case2/config.json
@@ -0,0 +1,13 @@
+{
+  "packageId": "reference-bundling",
+  "apiType": "rest",
+  "version": "v1",
+  "files": [
+    {
+      "fileId": "openapi.yaml",
+      "publish": true,
+      "labels": [],
+      "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1xd"
+    }
+  ]
+}
diff --git a/test/projects/reference-bundling/case2/openapi.yaml b/test/projects/reference-bundling/case2/openapi.yaml
@@ -13,4 +13,4 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: './non-existent-dependency.yaml#/User'
+                  $ref: './non-existent-reference.yaml#/User'
diff --git a/test/projects/reference-bundling/case3/config.json b/test/projects/reference-bundling/case3/config.json
@@ -0,0 +1,25 @@
+{
+  "packageId": "reference-bundling",
+  "apiType": "rest",
+  "version": "v1",
+  "files": [
+    {
+      "fileId": "transitive-reference.yaml",
+      "publish": true,
+      "labels": [],
+      "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1cd"
+    },
+    {
+      "fileId": "reference.yaml",
+      "publish": true,
+      "labels": [],
+      "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1cd"
+    },
+    {
+      "fileId": "openapi.yaml",
+      "publish": true,
+      "labels": [],
+      "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1xd"
+    }
+  ]
+}
diff --git a/test/projects/reference-bundling/case3/openapi.yaml b/test/projects/reference-bundling/case3/openapi.yaml
@@ -0,0 +1,7 @@
+openapi: 3.0.1
+info:
+  title: API
+  version: 1.0.0
+paths:
+  /users:
+    $ref: 'reference.yaml'
diff --git a/test/projects/reference-bundling/case3/reference.yaml b/test/projects/reference-bundling/case3/reference.yaml
@@ -0,0 +1,10 @@
+get:
+  responses:
+    '200':
+      description: description
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: './transitive-reference.yaml#/User'
diff --git a/test/projects/reference-bundling/case3/transitive-reference.yaml b/test/projects/reference-bundling/case3/transitive-reference.yaml
@@ -3,5 +3,3 @@ User:
   properties:
     id:
       type: integer
-    name:
-      type: string
diff --git a/test/projects/reference-bundling/case4/config.json b/test/projects/reference-bundling/case4/config.json
@@ -1,16 +1,16 @@
 {
-  "packageId": "bundle-dependencies",
+  "packageId": "reference-bundling",
   "apiType": "rest",
   "version": "v1",
   "files": [
     {
-      "fileId": "dependency.yaml",
+      "fileId": "reference.yaml",
       "publish": true,
       "labels": [],
       "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1cd"
     },
     {
-      "fileId": "main.yaml",
+      "fileId": "openapi.yaml",
       "publish": true,
       "labels": [],
       "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1xd"
diff --git a/test/projects/reference-bundling/case4/openapi.yaml b/test/projects/reference-bundling/case4/openapi.yaml
@@ -0,0 +1,7 @@
+openapi: 3.0.1
+info:
+  title: API
+  version: 1.0.0
+paths:
+  /users:
+    $ref: 'reference.yaml'
diff --git a/test/projects/reference-bundling/case4/reference.yaml b/test/projects/reference-bundling/case4/reference.yaml
@@ -0,0 +1,10 @@
+get:
+  responses:
+    '200':
+      description: description
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: './non-existent-reference.yaml#/User'
diff --git a/test/projects/reference-bundling/case5/config.json b/test/projects/reference-bundling/case5/config.json
@@ -0,0 +1,13 @@
+{
+  "packageId": "reference-bundling",
+  "apiType": "rest",
+  "version": "v1",
+  "files": [
+    {
+      "fileId": "openapi.yaml",
+      "publish": true,
+      "labels": [],
+      "commitId": "6c778b1f44200bd19944a6a8eac10a4e5a21a1xd"
+    }
+  ]
+}
diff --git a/test/projects/reference-bundling/case5/openapi.yaml b/test/projects/reference-bundling/case5/openapi.yaml
@@ -0,0 +1,23 @@
+openapi: 3.0.1
+info:
+  title: API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      responses:
+        '200':
+          description: description
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Userrr'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
diff --git a/test/reference-bundling.test.ts b/test/reference-bundling.test.ts
@@ -0,0 +1,70 @@
+import { LocalRegistry } from './helpers'
+
+describe('Reference bundling test', () => {
+  test('external references should be bundled', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case1')
+    const result = await pkg.publish(pkg.packageId, { packageId: pkg.packageId })
+
+    expect(result.documents.get('openapi.yaml')?.dependencies).toEqual(['reference.yaml'])
+  })
+
+  test('should throw on missing external reference', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case2')
+
+    await expect(pkg.publish(pkg.packageId)).rejects.toThrow(/Cannot resolve/)
+  })
+
+  test('should not throw on missing external reference', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case2')
+    const result = await pkg.publish(pkg.packageId, {
+      packageId: pkg.packageId,
+      strictValidation: false,
+    })
+
+    expect(result.operations.size).toBe(1)
+    expect(result.documents.get('openapi.yaml')?.dependencies.length).toBe(0)
+  })
+
+  test('transitive external references should be bundled', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case3')
+    const result = await pkg.publish(pkg.packageId, { packageId: pkg.packageId })
+
+    expect(result.documents.get('openapi.yaml')?.dependencies).toEqual([
+      'reference.yaml',
+      'transitive-reference.yaml',
+    ])
+  })
+
+  test('should throw on missing transitive external reference', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case4')
+
+    await expect(pkg.publish(pkg.packageId)).rejects.toThrow(/Cannot resolve/)
+  })
+
+  test('should not throw on missing transitive external reference', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case4')
+    const result = await pkg.publish(pkg.packageId, {
+      packageId: pkg.packageId,
+      strictValidation: false,
+    })
+
+    expect(result.operations.size).toBe(1)
+    expect(result.documents.get('openapi.yaml')?.dependencies).toEqual(['reference.yaml'])
+  })
+
+  test('should throw on missing internal reference', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case5')
+
+    await expect(pkg.publish(pkg.packageId)).rejects.toThrow(/\$ref can't be resolved/)
+  })
+
+  test('should not throw on missing internal reference', async () => {
+    const pkg = LocalRegistry.openPackage('reference-bundling/case5')
+    const result = await pkg.publish(pkg.packageId, {
+      packageId: pkg.packageId,
+      strictValidation: false,
+    })
+
+    expect(result.operations.size).toBe(1)
+  })
+})

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ export const buildUnknownDocument: DocumentBuilder<string> = async (parsedFile,`
`33`	`33`	`const {`
`34`	`34`	`data,`
`35`	`35`	`dependencies: fileDependencies,`
`36`		`- } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver)`
	`36`	`+ } = await getBundledFileDataWithDependencies(fileId, ctx.parsedFileResolver, !!ctx.config.strictValidation)`
`37`	`37`	`bundledFileData = data`
`38`	`38`	`dependencies = fileDependencies`
`39`	`39`	`}`