feat: Throw if documented endpoints reference undocumented resources

package.json

@@ -74,7 +74,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@seamapi/types": "^1.768.0",
+    "@seamapi/types": "^1.804.0",
     "@swc/core": "^1.11.29",
     "@types/node": "^24.10.9",
     "ava": "^6.0.1",

src/lib/blueprint.ts

@@ -510,6 +510,11 @@ export const createBlueprint = async (
     actionAttempts,
   })
 
+  assertDocumentedEndpointsDontReferenceUndocumentedResources({
+    routes,
+    resources,
+  })
+
   return {
     title: openapi.info.title,
     routes,
@@ -577,6 +582,38 @@ const assertSeamPathsAreUndocumented = ({
   }
 }
 
+const assertDocumentedEndpointsDontReferenceUndocumentedResources = ({
+  routes,
+  resources,
+}: Pick<Blueprint, 'routes' | 'resources'>): void => {
+  const undocumentedResourceTypes = new Set(
+    resources.filter((r) => r.isUndocumented).map((r) => r.resourceType),
+  )
+
+  const offenders: string[] = []
+
+  for (const route of routes) {
+    for (const endpoint of route.endpoints) {
+      if (endpoint.isUndocumented) continue
+      if (endpoint.response.responseType === 'void') continue
+      if (!('resourceType' in endpoint.response)) continue
+
+      const { resourceType } = endpoint.response
+      if (undocumentedResourceTypes.has(resourceType)) {
+        offenders.push(
+          `${endpoint.path} references undocumented resource '${resourceType}'`,
+        )
+      }
+    }
+  }
+
+  if (offenders.length > 0) {
+    throw new Error(
+      `Documented endpoints must not reference undocumented resources. Found:\n${offenders.join('\n')}`,
+    )
+  }
+}
+
 const extractValidActionAttemptTypes = (
   schemas: Openapi['components']['schemas'],
 ): string[] => {

test/blueprint.test.ts

@@ -53,3 +53,55 @@ test('createBlueprint: throws when a /seam entry is documented', async (t) => {
       /All \/seam entries must be marked undocumented\. Found: .*\/seam\/widgets\/get/,
   })
 })
+
+test('createBlueprint: throws when a documented endpoint references an undocumented resource', async (t) => {
+  const typesModule = TypesModuleSchema.parse(types)
+  const openapi = structuredClone(typesModule.openapi)
+
+  // Add an undocumented resource
+  openapi.components.schemas['secret_widget'] = {
+    type: 'object',
+    properties: {
+      secret_widget_id: { type: 'string', format: 'uuid' },
+    },
+    required: ['secret_widget_id'],
+    'x-undocumented': 'This resource is not yet public.',
+    'x-route-path': '/foos',
+  }
+
+  // Add a documented endpoint that returns the undocumented resource
+  openapi.paths['/widgets/get'] = {
+    post: {
+      operationId: 'widgetsGetPost',
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: {
+                properties: {
+                  ok: { type: 'boolean' },
+                  secret_widget: {
+                    $ref: '#/components/schemas/secret_widget',
+                  },
+                },
+                required: ['ok', 'secret_widget'],
+                type: 'object',
+              },
+            },
+          },
+          description: 'OK',
+        },
+      },
+      security: [],
+      summary: '/widgets/get',
+      tags: ['/widgets'],
+      'x-response-key': 'secret_widget',
+      'x-title': 'Get a widget',
+    },
+  }
+
+  await t.throwsAsync(() => createBlueprint({ ...typesModule, openapi }), {
+    message:
+      /Documented endpoints must not reference undocumented resources\. Found:\n.*\/widgets\/get.*secret_widget/,
+  })
+})