Merge branch 'main' into copilot/pass-openapi-document-to-context

Author: pmcelhaney

.changeset/strongly-typed-load-context.md

@@ -0,0 +1,5 @@
+---
+"counterfact": minor
+---
+
+Export `ContextArgs` type from generated `types/_.context.ts` so that `_.context.ts` files can strongly type the `loadContext` and `readJson` parameters received in the Context constructor. The default `_.context.ts` template now imports and uses `ContextArgs`.

docs/features/repl.md

@@ -76,7 +76,7 @@ A scenario function receives a single argument with `{ context, loadContext, rou
 
 ```ts
 // scenarios/index.ts
-import type { Scenario } from "../types/scenario-context.js";
+import type { Scenario } from "../types/_.context.js";
 
 export const soldPets: Scenario = ($) => {
   // Mutate context directly — same as typing in the REPL
@@ -98,7 +98,7 @@ After the command runs you can immediately use anything stored in `$.routes`:
 ⬣> routes.findSold.send()
 ```
 
-The `Scenario` type and `ApplyContext` interface are generated automatically into `types/scenario-context.ts` when you run Counterfact with type generation enabled.
+The `Scenario` type and `Scenario$` interface are generated automatically into `types/_.context.ts` when you run Counterfact with type generation enabled.
 
 ## See also
 

src/server/context-registry.ts

@@ -107,7 +107,7 @@ export class ContextRegistry extends EventTarget {
 
   /**
    * Removes the context entry for the given path and dispatches a
-   * "context-changed" event so that listeners (e.g. the scenario-context type
+   * "context-changed" event so that listeners (e.g. the _.context type
    * generator) can regenerate type files in response to the removal.
    *
    * @param path - The route path whose context entry should be deleted

src/typescript-generator/generate.ts

@@ -271,29 +271,41 @@ function buildApplyContextContent(contextFiles: ContextFileInfo[]): string {
     "// This file is generated by Counterfact. Do not edit manually.",
     ...importLines,
     "",
-    "export interface ApplyContext {",
-    '  /** Root context, same as loadContext("/") */',
-    `  context: ${contextType};`,
-    "  /** Load a context object for a specific path */",
+    "interface LoadContextDefinitions {",
+    "  /* code generator adds additional signatures here */",
     ...overloadLines,
     "  loadContext(path: string): Record<string, unknown>;",
+    "}",
+    "",
+    "export interface Scenario$ {",
+    '  /** Root context, same as loadContext("/") */',
+    `  readonly context: ${contextType};`,
+    '  readonly loadContext: LoadContextDefinitions["loadContext"];',
     "  /** Named route builders stored in the REPL execution context */",
-    "  routes: Record<string, unknown>;",
+    "  readonly routes: Record<string, unknown>;",
     "  /** Create a new route builder for a given path */",
-    "  route: (path: string) => unknown;",
+    "  readonly route: (path: string) => unknown;",
     "}",
     "",
     "/** A scenario function that receives the live REPL environment */",
-    "export type Scenario = ($: ApplyContext) => Promise<void> | void;",
+    "export type Scenario = ($: Scenario$) => Promise<void> | void;",
+    "",
+    "/** Interface for Context objects defined in _.context.ts files */",
+    "export interface Context$ {",
+    "  /** Load a context object for a specific path */",
+    '  readonly loadContext: LoadContextDefinitions["loadContext"];',
+    "  /** Load a JSON file relative to this file's path */",
+    "  readonly readJson: (relativePath: string) => Promise<unknown>;",
+    "}",
     "",
   ];
 
   return parts.join("\n");
 }
 
 /**
- * Writes the `types/scenario-context.ts` file, which exports the
- * `ApplyContext` interface used to type scenario functions.
+ * Writes the `types/_.context.ts` file, which exports the
+ * `Scenario$` interface used to type scenario functions.
  *
  * The interface is generated from all `_.context.ts` files found under the
  * `routes/` directory, providing strongly typed `loadContext()` overloads for
@@ -305,7 +317,7 @@ export async function writeApplyContextType(
   destination: string,
 ): Promise<void> {
   const typesDir = nodePath.join(destination, "types");
-  const filePath = nodePath.join(typesDir, "scenario-context.ts");
+  const filePath = nodePath.join(typesDir, "_.context.ts");
 
   const contextFiles = await collectContextFiles(destination);
   const content = buildApplyContextContent(contextFiles);
@@ -314,7 +326,7 @@ export async function writeApplyContextType(
   await fs.writeFile(filePath, content, "utf8");
 }
 
-const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/scenario-context.js";
+const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/_.context.js";
 
 /**
  * Scenario scripts are plain TypeScript functions that receive the live REPL

src/typescript-generator/repository.ts

@@ -189,18 +189,23 @@ export class Repository {
 
     await fs.writeFile(
       contextFilePath,
-      `/**
-* This is the default context for Counterfact.
-*
-* It defines the context object in the REPL 
-* and the $.context object in the code.
-*
-* Add properties and methods to suit your needs.
-* 
-* See https://counterfact.dev/docs/usage.html#working-with-state-the-codecontextcode-object-and-codecontexttscode
-*/
-export class Context {
+      `import type { Context$ } from "../types/_.context.js";
 
+/**
+ * This is the default context for Counterfact.
+ *
+ * It defines the context object in the REPL
+ * and the $.context object in the code.
+ *
+ * Add properties and methods to suit your needs.
+ *
+ * See https://github.com/counterfact/api-simulator/blob/main/docs/features/state.md
+ */
+
+export class Context {
+  constructor($: Context$) {
+    void $;
+  }
 }
 `,
     );

test/typescript-generator/generate.test.ts

@@ -59,8 +59,8 @@ describe("end-to-end test", () => {
   });
 });
 
-describe("scenario-context type generation", () => {
-  it("generates a fallback scenario-context.ts when no routes directory exists", async () => {
+describe("_.context type generation", () => {
+  it("generates a fallback _.context.ts when no routes directory exists", async () => {
     await usingTemporaryFiles(async ($) => {
       const basePath = $.path("");
       const repository = new Repository();
@@ -71,14 +71,21 @@ describe("scenario-context type generation", () => {
 
       await generate("./petstore.yaml", basePath, { types: true }, repository);
 
-      const content = await $.read("types/scenario-context.ts");
-      expect(content).toContain("context: Record<string, unknown>");
+      const content = await $.read("types/_.context.ts");
+      expect(content).toContain("readonly context: Record<string, unknown>");
       expect(content).toContain(
         "loadContext(path: string): Record<string, unknown>;",
       );
       expect(content).not.toContain("import type");
       expect(content).toContain(
-        "export type Scenario = ($: ApplyContext) => Promise<void> | void;",
+        "export type Scenario = ($: Scenario$) => Promise<void> | void;",
+      );
+      expect(content).toContain("export interface Context$ {");
+      expect(content).toContain(
+        '  readonly loadContext: LoadContextDefinitions["loadContext"];',
+      );
+      expect(content).toContain(
+        "  readonly readJson: (relativePath: string) => Promise<unknown>;",
       );
     });
   });
@@ -96,11 +103,11 @@ describe("scenario-context type generation", () => {
 
       await generate("./petstore.yaml", basePath, { types: true }, repository);
 
-      const content = await $.read("types/scenario-context.ts");
+      const content = await $.read("types/_.context.ts");
       expect(content).toContain(
         'import type { Context } from "../routes/_.context";',
       );
-      expect(content).toContain("context: Context;");
+      expect(content).toContain("readonly context: Context;");
       expect(content).toContain(
         'loadContext(path: "/" | `/${string}`): Context;',
       );
@@ -124,7 +131,7 @@ describe("scenario-context type generation", () => {
 
       await generate("./petstore.yaml", basePath, { types: true }, repository);
 
-      const content = await $.read("types/scenario-context.ts");
+      const content = await $.read("types/_.context.ts");
       expect(content).toContain(
         'import type { Context } from "../routes/_.context";',
       );
@@ -161,7 +168,7 @@ describe("scenario-context type generation", () => {
 
       await generate("./petstore.yaml", basePath, { types: true }, repository);
 
-      const content = await $.read("types/scenario-context.ts");
+      const content = await $.read("types/_.context.ts");
       expect(content).toContain(
         'import type { Context as PetsPetIdContext } from "../routes/pets/{petId}/_.context";',
       );