feat: added a build process for the readme and rules files. There we type errors and bugs in the old mdx examples. Now, with a build process, all the TS examples are now linted, typechecked, tested and code reviewed before being published.

Author: PaulJPhilp

README.md

@@ -260,21 +260,12 @@ How to test Effect code effectively, reliably, and deterministically.
 
 ## AI Coding Rules
 
-This project provides several machine-readable sets of coding rules, tailored for different needs and optimized for AI-powered IDEs and coding agents like Cursor or GitHub Copilot.
+This project provides a machine-readable set of coding rules for AI-powered IDEs and coding agents.
 
-You can find the latest rule files in the [`rules`](./rules/) directory. These are automatically generated from the content in this repository.
+You can find the latest rules files in the [rules directory](./rules/). These files are designed for integration with tools like Cursor, GitHub Copilot, and other AI coding assistants.
 
-### Available Formats
-
--   **Comprehensive Rules (`rules.md`)**: A human-readable markdown file containing all patterns, guidelines, and rationale.
--   **Compact Rules (`rules-compact.md`)**: A condensed version containing only the core rule for each pattern, designed for minimal token usage.
--   **Structured JSON (`rules.json`)**: A machine-readable JSON file containing all rule information for programmatic use.
--   **By Skill Level**: Detailed rules, including examples, split into separate files for each skill level.
-    -   [`beginner.md`](./rules/beginner.md)
-    -   [`intermediate.md`](./rules/intermediate.md)
-    -   [`advanced.md`](./rules/advanced.md)
--   **By Use Case**: Detailed rules, including examples, grouped by practical application areas.
-    -   [View all use cases](./rules/by-use-case/)
+- **rules.md**: Human-readable rules summary
+- **rules.json**: Structured rules for programmatic consumption
 
 ---
 

bun.lock

@@ -23,7 +23,31 @@ This allows your business logic to declaratively state its dependency on a piece
 
 ## Good Example
 
-<Example path="./src/access-config-in-context.ts" />
+```typescript
+import { Config, Effect, Layer } from "effect";
+
+// Define config service
+class AppConfig extends Effect.Service<AppConfig>()(
+  "AppConfig",
+  {
+    sync: () => ({
+      host: "localhost",
+      port: 3000
+    })
+  }
+) {}
+
+// Create program that uses config
+const program = Effect.gen(function* () {
+  const config = yield* AppConfig;
+  yield* Effect.log(`Starting server on http://${config.host}:${config.port}`);
+});
+
+// Run the program with default config
+Effect.runPromise(
+  Effect.provide(program, AppConfig.Default)
+);
+```
 
 **Explanation:**  
 By yielding the config object, you make your dependency explicit and leverage Effect's context system for testability and modularity.

content/access-config-in-context.mdx

@@ -42,7 +42,62 @@ This makes any time-dependent logic pure, deterministic, and easy to test with p
 
 This example shows a function that checks if a token is expired. Its logic depends on `Clock`, making it fully testable.
 
-<Example path="./src/accessing-current-time-with-clock.ts" />
+```typescript
+import { Effect, Clock, Duration } from "effect";
+
+interface Token {
+  readonly value: string;
+  readonly expiresAt: number; // UTC milliseconds
+}
+
+// This function is pure and testable because it depends on Clock
+const isTokenExpired = (token: Token): Effect.Effect<boolean, never, Clock.Clock> =>
+  Clock.currentTimeMillis.pipe(
+    Effect.map((now) => now > token.expiresAt),
+    Effect.tap((expired) => Effect.log(`Token expired? ${expired} (current time: ${new Date().toISOString()})`))
+  );
+
+// Create a test clock service that advances time
+const makeTestClock = (timeMs: number): Clock.Clock => ({
+  currentTimeMillis: Effect.succeed(timeMs),
+  currentTimeNanos: Effect.succeed(BigInt(timeMs * 1_000_000)),
+  sleep: (duration: Duration.Duration) => Effect.succeed(void 0),
+  unsafeCurrentTimeMillis: () => timeMs,
+  unsafeCurrentTimeNanos: () => BigInt(timeMs * 1_000_000),
+  [Clock.ClockTypeId]: Clock.ClockTypeId,
+});
+
+// Create a token that expires in 1 second
+const token = { value: "abc", expiresAt: Date.now() + 1000 };
+
+// Check token expiry with different clocks
+const program = Effect.gen(function* () {
+  // Check with current time
+  yield* Effect.log("Checking with current time...");
+  yield* isTokenExpired(token);
+
+  // Check with past time
+  yield* Effect.log("\nChecking with past time (1 minute ago)...");
+  const pastClock = makeTestClock(Date.now() - 60_000);
+  yield* isTokenExpired(token).pipe(
+    Effect.provideService(Clock.Clock, pastClock)
+  );
+
+  // Check with future time
+  yield* Effect.log("\nChecking with future time (1 hour ahead)...");
+  const futureClock = makeTestClock(Date.now() + 3600_000);
+  yield* isTokenExpired(token).pipe(
+    Effect.provideService(Clock.Clock, futureClock)
+  );
+});
+
+// Run the program with default clock
+Effect.runPromise(
+  program.pipe(
+    Effect.provideService(Clock.Clock, makeTestClock(Date.now()))
+  )
+);
+```
 
 ---
 

content/accessing-current-time-with-clock.mdx

@@ -40,7 +40,86 @@ However, for tasks like validating a user's input, this is poor user experience.
 
 Using `Schema.decode` with the `allErrors: true` option demonstrates this pattern perfectly. The underlying mechanism uses `Either` to collect all parsing errors into an array instead of stopping at the first one.
 
-`<Example path="./src/accumulate-multiple-errors-with-either.ts" />`
+````typescript
+import { Effect, Schema, Data } from "effect";
+
+// Define validation error type
+class ValidationError extends Data.TaggedError("ValidationError")<{
+  readonly field: string;
+  readonly message: string;
+}> {}
+
+// Define user type
+type User = {
+  name: string;
+  email: string;
+};
+
+// Define schema with custom validation
+const UserSchema = Schema.Struct({
+  name: Schema.String.pipe(
+    Schema.minLength(3),
+    Schema.filter((name) => /^[A-Za-z\s]+$/.test(name), {
+      message: () => "name must contain only letters and spaces"
+    })
+  ),
+  email: Schema.String.pipe(
+    Schema.pattern(/@/),
+    Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
+      message: () => "email must be a valid email address"
+    })
+  ),
+});
+
+// Example inputs
+const invalidInputs: User[] = [
+  {
+    name: "Al", // Too short
+    email: "bob-no-at-sign.com", // Invalid pattern
+  },
+  {
+    name: "John123", // Contains numbers
+    email: "john@incomplete", // Invalid email
+  },
+  {
+    name: "Alice Smith", // Valid
+    email: "alice@example.com", // Valid
+  }
+];
+
+// Validate a single user
+const validateUser = (input: User) =>
+  Effect.gen(function* () {
+    const result = yield* Schema.decode(UserSchema)(input, { errors: "all" });
+    return result;
+  });
+
+// Process multiple users and accumulate all errors
+const program = Effect.gen(function* () {
+  console.log("Validating users...\n");
+  
+  for (const input of invalidInputs) {
+    const result = yield* Effect.either(validateUser(input));
+    
+    console.log(`Validating user: ${input.name} <${input.email}>`);
+    
+    yield* Effect.match(result, {
+      onFailure: (error) => Effect.sync(() => {
+        console.log("❌ Validation failed:");
+        console.log(error.message);
+        console.log(); // Empty line for readability
+      }),
+      onSuccess: (user) => Effect.sync(() => {
+        console.log("✅ User is valid:", user);
+        console.log(); // Empty line for readability
+      })
+    });
+  }
+});
+
+// Run the program
+Effect.runSync(program);
+````
 
 ---
 

content/accumulate-multiple-errors-with-either.mdx

@@ -45,7 +45,72 @@ This approach is powerful because:
 
 We have a `WeatherService` that makes slow API calls. We create a `WeatherService.cached` wrapper layer that adds an in-memory cache using a `Ref` and a `Map`.
 
-<Example path="./src/add-caching-by-wrapping-a-layer.ts" />
+```typescript
+import { Effect, Layer, Ref } from "effect";
+
+// 1. Define the service interface
+class WeatherService extends Effect.Service<WeatherService>()(
+  "WeatherService",
+  {
+    sync: () => ({
+      getForecast: (city: string) => Effect.succeed(`Sunny in ${city}`),
+    }),
+  }
+) {}
+
+// 2. The "Live" implementation that is slow
+const WeatherServiceLive = Layer.succeed(
+  WeatherService,
+  WeatherService.of({
+    getForecast: (city) =>
+      Effect.succeed(`Sunny in ${city}`).pipe(
+        Effect.delay("2 seconds"),
+        Effect.tap(() => Effect.log(`Fetched live forecast for ${city}`))
+      ),
+  })
+);
+
+// 3. The Caching Wrapper Layer
+const WeatherServiceCached = Layer.effect(
+  WeatherService,
+  Effect.gen(function* () {
+    // It REQUIRES the original WeatherService
+    const underlyingService = yield* WeatherService;
+    const cache = yield* Ref.make(new Map<string, string>());
+
+    return WeatherService.of({
+      getForecast: (city) =>
+        Ref.get(cache).pipe(
+          Effect.flatMap((map) =>
+            map.has(city)
+              ? Effect.log(`Cache HIT for ${city}`).pipe(
+                  Effect.as(map.get(city)!)
+                )
+              : Effect.log(`Cache MISS for ${city}`).pipe(
+                  Effect.flatMap(() => underlyingService.getForecast(city)),
+                  Effect.tap((forecast) =>
+                    Ref.update(cache, (map) => map.set(city, forecast))
+                  )
+                )
+          )
+        ),
+    });
+  })
+);
+
+// 4. Compose the final layer. The wrapper is provided with the live implementation.
+const AppLayer = Layer.provide(WeatherServiceCached, WeatherServiceLive);
+
+// 5. The application logic
+const program = Effect.gen(function* () {
+  const weather = yield* WeatherService;
+  yield* weather.getForecast("London"); // First call is slow (MISS)
+  yield* weather.getForecast("London"); // Second call is instant (HIT)
+});
+
+Effect.runPromise(Effect.provide(program, AppLayer));
+
+```
 
 ---
 

content/add-caching-by-wrapping-a-layer.mdx

@@ -47,7 +47,38 @@ This allows you to answer questions like:
 
 This example creates a counter to track how many times a user is created and a histogram to track the duration of the database operation.
 
-<Example path="./src/add-custom-metrics.ts" />
+```typescript
+import { Effect, Metric, Duration } from "effect";  // We don't need MetricBoundaries anymore
+
+// 1. Define your metrics
+const userRegisteredCounter = Metric.counter("users_registered_total", {
+  description: "A counter for how many users have been registered.",
+});
+
+const dbDurationTimer = Metric.timer(
+  "db_operation_duration",
+  "A timer for DB operation durations"
+);
+
+// 2. Simulated database call
+const saveUserToDb = Effect.succeed("user saved").pipe(
+  Effect.delay(Duration.millis(Math.random() * 100)),
+);
+
+// 3. Instrument the business logic
+const createUser = Effect.gen(function* () {
+  // Time the operation
+  yield* saveUserToDb.pipe(Metric.trackDuration(dbDurationTimer));
+
+  // Increment the counter
+  yield* Metric.increment(userRegisteredCounter);
+
+  return { status: "success" };
+});
+
+// Run the Effect
+Effect.runPromise(createUser).then(console.log);
+```
 
 ---
 

content/add-custom-metrics.mdx

@@ -25,7 +25,32 @@ debug than deeply nested functional chains.
 
 ## Good Example
 
-<Example path="./src/avoid-long-andthen-chains.ts" />
+```typescript
+import { Effect } from "effect";
+
+// Define our steps with logging
+const step1 = (): Effect.Effect<number> =>
+  Effect.succeed(42).pipe(
+    Effect.tap(n => Effect.log(`Step 1: ${n}`))
+  );
+
+const step2 = (a: number): Effect.Effect<string> =>
+  Effect.succeed(`Result: ${a * 2}`).pipe(
+    Effect.tap(s => Effect.log(`Step 2: ${s}`))
+  );
+
+// Using Effect.gen for better readability
+const program = Effect.gen(function* () {
+  const a = yield* step1();
+  const b = yield* step2(a);
+  return b;
+});
+
+// Run the program
+Effect.runPromise(program).then(
+  result => Effect.runSync(Effect.log(`Final result: ${result}`))
+);
+```
 
 **Explanation:**  
 Generators keep sequential logic readable and easy to maintain.

content/avoid-long-andthen-chains.mdx

@@ -45,7 +45,34 @@ This makes your time-based logic pure, predictable, and easy to test.
 
 This example shows a function that creates a timestamped event. It depends on the `Clock` service, making it fully testable.
 
-<Example path="./src/beyond-the-date-type.ts" />
+```typescript
+import { Effect, Clock } from "effect";
+import type * as Types from "effect/Clock";
+
+interface Event {
+  readonly message: string;
+  readonly timestamp: number; // Store as a primitive number (UTC millis)
+}
+
+// This function is pure and testable because it depends on Clock
+const createEvent = (message: string): Effect.Effect<Event, never, Types.Clock> =>
+  Effect.gen(function* () {
+    const timestamp = yield* Clock.currentTimeMillis;
+    return { message, timestamp };
+  });
+
+// Create and log some events
+const program = Effect.gen(function* () {
+  const loginEvent = yield* createEvent("User logged in");
+  console.log("Login event:", loginEvent);
+
+  const logoutEvent = yield* createEvent("User logged out");
+  console.log("Logout event:", logoutEvent);
+});
+
+// Run the program
+Effect.runPromise(program.pipe(Effect.provideService(Clock.Clock, Clock.make()))).catch(console.error);
+```
 
 ---