fix: address code review feedback - safer array access, clearer naming

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/e45b6211-c18d-4a86-8bf3-8bef0d04957b

Author: Copilot

src/app.ts

@@ -254,11 +254,15 @@ function buildMultiSpecMiddleware(
   return async function multiSpecMiddleware(ctx, next) {
     for (const { prefix, middleware } of specMiddlewares) {
       if (ctx.request.path.startsWith(prefix)) {
-        let passedThrough = false;
+        // The per-spec koaMiddleware calls `next` only when the path does NOT
+        // match its routePrefix, which means we should move on to the next spec.
+        // When it handles the request it does NOT call next, so `calledNext`
+        // stays false and we return immediately.
+        let calledNext = false;
         await middleware(ctx, async () => {
-          passedThrough = true;
+          calledNext = true;
         });
-        if (!passedThrough) return;
+        if (!calledNext) return;
       }
     }
     await next();
@@ -307,19 +311,22 @@ export async function counterfact(config: Config) {
       ),
     );
 
+    // Guaranteed non-empty: we checked `config.specs.length > 0` above and
+    // `specBundles` has the same length as `config.specs`.
+    const primaryBundle = specBundles[0] as SpecBundle;
+    const primarySpec = config.specs[0] as (typeof config.specs)[number];
+
     const compositeMiddleware = buildMultiSpecMiddleware(specBundles, config);
 
     // Use the first spec's registry for the Koa admin/OpenAPI UI (best effort).
-    const primaryRegistry = specBundles[0]!.registry;
+    const primaryRegistry = primaryBundle.registry;
 
     const koaApp = createKoaApp(
       primaryRegistry,
       compositeMiddleware,
       {
         ...config,
-        openApiPath: specBundles[0]!.openApiDocument
-          ? config.specs[0]!.source
-          : "_",
+        openApiPath: primaryBundle.openApiDocument ? primarySpec.source : "_",
       },
       contextRegistry,
     );
@@ -359,7 +366,7 @@ export async function counterfact(config: Config) {
           scenarioRegistry,
           contextRegistry,
           config,
-          specBundles[0]!.openApiDocument,
+          primaryBundle.openApiDocument,
         );
 
         const server = koaApp.listen({ port: config.port });
@@ -401,7 +408,7 @@ export async function counterfact(config: Config) {
           primaryRegistry,
           config,
           undefined,
-          specBundles[0]!.openApiDocument,
+          primaryBundle.openApiDocument,
           scenarioRegistry,
         ),
     };

test/app.test.ts

@@ -255,32 +255,48 @@ describe("counterfact multi-spec mode", () => {
 
     // Simulate a Koa context for /alpha/...
     const alphaCtx = {
-      request: { path: "/alpha/hello/world", method: "GET", body: undefined, headers: {}, query: {} },
+      request: {
+        path: "/alpha/hello/world",
+        method: "GET",
+        body: undefined,
+        headers: {},
+        query: {},
+      },
       req: {},
       status: 200,
       set: () => {},
       body: undefined,
     } as any;
 
     let alphaCalledNext = false;
-    await result.koaMiddleware(alphaCtx, async () => { alphaCalledNext = true; });
+    await result.koaMiddleware(alphaCtx, async () => {
+      alphaCalledNext = true;
+    });
 
-    // The request should have been handled (next was NOT called or it was passed through normally)
-    // Since /alpha/hello/world may not exist in the registry, it returns a 404-like response
-    // but the middleware should NOT propagate to next() unless the prefix doesn't match.
+    // /alpha matches the "alpha" spec prefix. The per-spec middleware handles
+    // any request under that prefix (even if the route doesn't exist) and does
+    // NOT call next(), so alphaCalledNext should remain false.
     expect(alphaCalledNext).toBe(false);
 
     // Simulate a Koa context for an unknown prefix /gamma/...
     const unknownCtx = {
-      request: { path: "/gamma/something", method: "GET", body: undefined, headers: {}, query: {} },
+      request: {
+        path: "/gamma/something",
+        method: "GET",
+        body: undefined,
+        headers: {},
+        query: {},
+      },
       req: {},
       status: 200,
       set: () => {},
       body: undefined,
     } as any;
 
     let unknownCalledNext = false;
-    await result.koaMiddleware(unknownCtx, async () => { unknownCalledNext = true; });
+    await result.koaMiddleware(unknownCtx, async () => {
+      unknownCalledNext = true;
+    });
 
     // No spec matches /gamma, so next should be called
     expect(unknownCalledNext).toBe(true);