address claude code review points

Author: kantord

docs/mocks.md

@@ -98,7 +98,7 @@ interface AutoAPIMockInstance<T> {
   scenario(name: string, fn: (instance: AutoAPIMockInstance<T>) => AutoAPIMockInstance<T>): this;
 
   // Activate a named scenario for the current test
-  useScenario(name: string): this;
+  activateScenario(name: string): this;
 
   // Reset to default behavior (called automatically before each test)
   reset(): this;
@@ -229,14 +229,14 @@ import { mockedGetRegistryV01Servers } from "@mocks/fixtures/registry_v0_1_serve
 
 describe("getServers", () => {
   it("returns empty array when API returns no servers", async () => {
-    mockedGetRegistryV01Servers.useScenario(MockScenarios.EmptyServers);
+    mockedGetRegistryV01Servers.activateScenario(MockScenarios.EmptyServers);
 
     const servers = await getServers();
     expect(servers).toEqual([]);
   });
 
   it("throws on 500 server error", async () => {
-    mockedGetRegistryV01Servers.useScenario(MockScenarios.ServerError);
+    mockedGetRegistryV01Servers.activateScenario(MockScenarios.ServerError);
 
     await expect(getServers()).rejects.toBeDefined();
   });

src/app/catalog/actions.test.ts

@@ -26,18 +26,18 @@ describe("getServers", () => {
     expect(servers[0].name).toBe("awslabs/aws-nova-canvas");
   });
 
-  // Demo: using .useScenario() for reusable test scenarios
+  // Demo: using .activateScenario() for reusable test scenarios
   it("returns empty array when using empty-servers scenario", async () => {
-    mockedGetRegistryV01Servers.useScenario("empty-servers");
+    mockedGetRegistryV01Servers.activateScenario("empty-servers");
 
     const servers = await getServers();
 
     expect(servers).toEqual([]);
   });
 
-  // Demo: using .useScenario() for error scenarios
+  // Demo: using .activateScenario() for error scenarios
   it("throws on server error scenario", async () => {
-    mockedGetRegistryV01Servers.useScenario("server-error");
+    mockedGetRegistryV01Servers.activateScenario("server-error");
 
     await expect(getServers()).rejects.toBeDefined();
   });

src/mocks/autoAPIMock.ts

@@ -12,24 +12,37 @@ type ScenarioFn<T> = (
   instance: AutoAPIMockInstance<T>,
 ) => AutoAPIMockInstance<T>;
 
-export interface UseScenarioOptions {
+export interface ActivateScenarioOptions {
   /** If true, silently falls back to default when scenario doesn't exist. Default: false (throws) */
   fallbackToDefault?: boolean;
 }
 
 export interface AutoAPIMockInstance<T> {
+  /** Internal MSW handler - don't call directly */
   generatedHandler: HttpResponseResolver;
+
+  /** Override response data with type safety. Preferred for simple data changes. */
   override: (fn: OverrideFn<T>) => AutoAPIMockInstance<T>;
+
+  /** Override the full handler. Use for errors, network failures, or invalid data. */
   overrideHandler: (fn: OverrideHandlerFn<T>) => AutoAPIMockInstance<T>;
+
+  /** Define a reusable named scenario for this mock. */
   scenario: (
     name: MockScenarioName,
     fn: ScenarioFn<T>,
   ) => AutoAPIMockInstance<T>;
-  useScenario: (
+
+  /** Activate a named scenario for the current test. */
+  activateScenario: (
     name: MockScenarioName,
-    options?: UseScenarioOptions,
+    options?: ActivateScenarioOptions,
   ) => AutoAPIMockInstance<T>;
+
+  /** Reset to default behavior. Called automatically before each test. */
   reset: () => AutoAPIMockInstance<T>;
+
+  /** The default fixture data. */
   defaultValue: T;
 }
 
@@ -83,7 +96,10 @@ export function AutoAPIMock<T>(defaultValue: T): AutoAPIMockInstance<T> {
       return instance;
     },
 
-    useScenario(name: MockScenarioName, options?: UseScenarioOptions) {
+    activateScenario(
+      name: MockScenarioName,
+      options?: ActivateScenarioOptions,
+    ) {
       const scenarioFn = scenarios.get(name);
       if (!scenarioFn) {
         if (options?.fallbackToDefault) {
@@ -119,7 +135,6 @@ export function resetAllAutoAPIMocks(): void {
  */
 export function activateMockScenario(name: MockScenarioName): void {
   for (const instance of registry) {
-    // biome-ignore lint/correctness/useHookAtTopLevel: useScenario is not a React hook
-    instance.useScenario(name, { fallbackToDefault: true });
+    instance.activateScenario(name, { fallbackToDefault: true });
   }
 }

src/mocks/index.ts

@@ -1,4 +1,7 @@
-export type { AutoAPIMockInstance, UseScenarioOptions } from "./autoAPIMock";
+export type {
+  ActivateScenarioOptions,
+  AutoAPIMockInstance,
+} from "./autoAPIMock";
 export {
   AutoAPIMock,
   activateMockScenario,