feat: Throw if anything under /seam is not undocumented (#265)

* Throw if anything under /seam is not undocumented

* Update @seamapi/types

* ci: Generate code

---------

Co-authored-by: Seam Bot <seambot@getseam.com>

Author: razor-x

package-lock.json

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

package.json

@@ -500,18 +500,83 @@ export const createBlueprint = async (
     routes,
     context,
   )
+  const events = await createEvents(openapiSchemas, routes, context)
+
+  assertSeamPathsAreUndocumented({
+    routes,
+    namespaces,
+    resources,
+    events,
+    actionAttempts,
+  })
 
   return {
     title: openapi.info.title,
     routes,
     namespaces,
     resources,
     pagination: createPagination(pagination, openapiSchemas),
-    events: await createEvents(openapiSchemas, routes, context),
+    events,
     actionAttempts,
   }
 }
 
+const isSeamPath = (path: string): boolean =>
+  path === '/seam' || path.startsWith('/seam/')
+
+const assertSeamPathsAreUndocumented = ({
+  routes,
+  namespaces,
+  resources,
+  events,
+  actionAttempts,
+}: Pick<
+  Blueprint,
+  'routes' | 'namespaces' | 'resources' | 'events' | 'actionAttempts'
+>): void => {
+  const offenders = [
+    ...routes.flatMap((route) => {
+      const routeOffenders =
+        isSeamPath(route.path) && !route.isUndocumented
+          ? [`route ${route.path}`]
+          : []
+      const endpointOffenders = route.endpoints.flatMap((endpoint) =>
+        isSeamPath(endpoint.path) && !endpoint.isUndocumented
+          ? [`endpoint ${endpoint.path}`]
+          : [],
+      )
+
+      return [...routeOffenders, ...endpointOffenders]
+    }),
+    ...namespaces.flatMap((namespace) =>
+      isSeamPath(namespace.path) && !namespace.isUndocumented
+        ? [`namespace ${namespace.path}`]
+        : [],
+    ),
+    ...resources.flatMap((resource) =>
+      isSeamPath(resource.routePath) && !resource.isUndocumented
+        ? [`resource ${resource.routePath}`]
+        : [],
+    ),
+    ...events.flatMap((event) =>
+      isSeamPath(event.routePath) && !event.isUndocumented
+        ? [`event ${event.routePath}`]
+        : [],
+    ),
+    ...actionAttempts.flatMap((actionAttempt) =>
+      isSeamPath(actionAttempt.routePath) && !actionAttempt.isUndocumented
+        ? [`action_attempt ${actionAttempt.routePath}`]
+        : [],
+    ),
+  ]
+
+  if (offenders.length > 0) {
+    throw new Error(
+      `All /seam entries must be marked undocumented. Found: ${offenders.join(', ')}`,
+    )
+  }
+}
+
 const extractValidActionAttemptTypes = (
   schemas: Openapi['components']['schemas'],
 ): string[] => {
@@ -1946,9 +2011,9 @@ const createActionAttempts = async (
         const allPropertyKeys = new Set<string>()
         for (const schema of actionAttemptSchemas) {
           if (schema.properties != null) {
-            Object.keys(schema.properties).forEach((key) =>
-              allPropertyKeys.add(key),
-            )
+            Object.keys(schema.properties).forEach((key) => {
+              allPropertyKeys.add(key)
+            })
           }
         }
 

src/lib/blueprint.ts

@@ -16,3 +16,40 @@ test('createBlueprint: with formatCode', async (t) => {
   })
   t.snapshot(blueprint, 'blueprint')
 })
+
+test('createBlueprint: throws when a /seam entry is documented', async (t) => {
+  const typesModule = TypesModuleSchema.parse(types)
+  const openapi = structuredClone(typesModule.openapi)
+
+  openapi.paths['/seam/widgets/get'] = {
+    post: {
+      operationId: 'seamWidgetsGetPost',
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: {
+                properties: {
+                  ok: { type: 'boolean' },
+                },
+                required: ['ok'],
+                type: 'object',
+              },
+            },
+          },
+          description: 'OK',
+        },
+      },
+      security: [],
+      summary: '/seam/widgets/get',
+      tags: ['/seam/widgets'],
+      'x-response-key': null,
+      'x-title': 'Get seam widgets',
+    },
+  }
+
+  await t.throwsAsync(() => createBlueprint({ ...typesModule, openapi }), {
+    message:
+      /All \/seam entries must be marked undocumented\. Found: .*\/seam\/widgets\/get/,
+  })
+})