Add hooks design document

Analyzes four options for test setup/teardown in funee:
1. Scenario-level setup/teardown - too limited
2. Scenario groups - reintroduces file-level thinking
3. Resource pattern (wrapper functions) - RECOMMENDED
4. Fixture pattern - too much framework magic

Recommends Option 3 (Resource pattern) because:
- Function-centric: Everything is just functions
- Watch mode compatible: Setup/teardown inside closure
- Composable: Standard function composition
- No framework magic: Users write and understand the code
- Type-safe: Standard TypeScript inference

Includes:
- defineResource helper for convenience
- using() helper for composing multiple resources
- Full examples showing simple and complex cases
- Integration details for runScenarios and watch mode

Author: nev-offload

funee-lib/assertions/contains.ts

@@ -0,0 +1,82 @@
+/**
+ * Containment assertion for strings and arrays.
+ */
+
+import { Assertion } from "./Assertion.ts";
+import { AssertionError } from "./AssertionError.ts";
+
+/**
+ * Deep equality check for containment comparison.
+ */
+const isDeepEqual = (a: any, b: any): boolean => {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  
+  if (typeof a === "object" && typeof b === "object") {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    
+    if (aKeys.length !== bKeys.length) return false;
+    
+    for (const key of aKeys) {
+      if (!isDeepEqual(a[key], b[key])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  
+  return false;
+};
+
+/**
+ * Assert that a value contains the expected item.
+ * 
+ * For strings: checks if the string contains the expected substring.
+ * For arrays: checks if the array contains the expected item (using deep equality for objects).
+ * 
+ * @example
+ * await assertThat("hello world", contains("world")); // pass
+ * await assertThat([1, 2, 3], contains(2)); // pass
+ * await assertThat([{a: 1}, {b: 2}], contains({a: 1})); // pass (deep equality)
+ */
+export const contains = (expected: any): Assertion<string | any[]> => {
+  return (actual: string | any[]): void => {
+    if (typeof actual === "string") {
+      if (typeof expected !== "string") {
+        throw AssertionError({
+          message: "Expected string to contain a string, but got " + typeof expected,
+          actual,
+          expected,
+          operator: "contains"
+        });
+      }
+      if (!actual.includes(expected)) {
+        throw AssertionError({
+          message: "Expected string to contain " + JSON.stringify(expected) + " but got " + JSON.stringify(actual),
+          actual,
+          expected,
+          operator: "contains"
+        });
+      }
+    } else if (Array.isArray(actual)) {
+      const found = actual.some((item) => isDeepEqual(item, expected));
+      if (!found) {
+        throw AssertionError({
+          message: "Expected array to contain " + JSON.stringify(expected) + " but got " + JSON.stringify(actual),
+          actual,
+          expected,
+          operator: "contains"
+        });
+      }
+    } else {
+      throw AssertionError({
+        message: "Expected string or array but got " + typeof actual,
+        actual,
+        expected,
+        operator: "contains"
+      });
+    }
+  };
+};

funee-lib/assertions/greaterThan.ts

@@ -0,0 +1,34 @@
+/**
+ * Numeric greater than assertion.
+ */
+
+import { Assertion } from "./Assertion.ts";
+import { AssertionError } from "./AssertionError.ts";
+
+/**
+ * Assert that a number is greater than the expected value.
+ * 
+ * @example
+ * await assertThat(5, greaterThan(3)); // pass
+ * await assertThat(10, greaterThan(10)); // fail
+ */
+export const greaterThan = (expected: number): Assertion<number> => {
+  return (actual: number): void => {
+    if (typeof actual !== "number") {
+      throw AssertionError({
+        message: "Expected a number but got " + typeof actual,
+        actual,
+        expected: "> " + expected,
+        operator: "greaterThan"
+      });
+    }
+    if (!(actual > expected)) {
+      throw AssertionError({
+        message: "Expected " + actual + " to be greater than " + expected,
+        actual,
+        expected: "> " + expected,
+        operator: "greaterThan"
+      });
+    }
+  };
+};

funee-lib/assertions/greaterThanOrEqual.ts

@@ -0,0 +1,35 @@
+/**
+ * Numeric greater than or equal assertion.
+ */
+
+import { Assertion } from "./Assertion.ts";
+import { AssertionError } from "./AssertionError.ts";
+
+/**
+ * Assert that a number is greater than or equal to the expected value.
+ * 
+ * @example
+ * await assertThat(5, greaterThanOrEqual(5)); // pass
+ * await assertThat(6, greaterThanOrEqual(5)); // pass
+ * await assertThat(4, greaterThanOrEqual(5)); // fail
+ */
+export const greaterThanOrEqual = (expected: number): Assertion<number> => {
+  return (actual: number): void => {
+    if (typeof actual !== "number") {
+      throw AssertionError({
+        message: "Expected a number but got " + typeof actual,
+        actual,
+        expected: ">= " + expected,
+        operator: "greaterThanOrEqual"
+      });
+    }
+    if (!(actual >= expected)) {
+      throw AssertionError({
+        message: "Expected " + actual + " to be greater than or equal to " + expected,
+        actual,
+        expected: ">= " + expected,
+        operator: "greaterThanOrEqual"
+      });
+    }
+  };
+};

funee-lib/assertions/index.ts

@@ -35,3 +35,11 @@ export { assertThat } from "./assertThat.ts";
 export { is } from "./is.ts";
 export { not } from "./not.ts";
 export { both } from "./both.ts";
+
+// Matchers
+export { contains } from "./contains.ts";
+export { matches } from "./matches.ts";
+export { greaterThan } from "./greaterThan.ts";
+export { lessThan } from "./lessThan.ts";
+export { greaterThanOrEqual } from "./greaterThanOrEqual.ts";
+export { lessThanOrEqual } from "./lessThanOrEqual.ts";

funee-lib/assertions/lessThan.ts

@@ -0,0 +1,34 @@
+/**
+ * Numeric less than assertion.
+ */
+
+import { Assertion } from "./Assertion.ts";
+import { AssertionError } from "./AssertionError.ts";
+
+/**
+ * Assert that a number is less than the expected value.
+ * 
+ * @example
+ * await assertThat(2, lessThan(10)); // pass
+ * await assertThat(10, lessThan(10)); // fail
+ */
+export const lessThan = (expected: number): Assertion<number> => {
+  return (actual: number): void => {
+    if (typeof actual !== "number") {
+      throw AssertionError({
+        message: "Expected a number but got " + typeof actual,
+        actual,
+        expected: "< " + expected,
+        operator: "lessThan"
+      });
+    }
+    if (!(actual < expected)) {
+      throw AssertionError({
+        message: "Expected " + actual + " to be less than " + expected,
+        actual,
+        expected: "< " + expected,
+        operator: "lessThan"
+      });
+    }
+  };
+};

funee-lib/assertions/lessThanOrEqual.ts

@@ -0,0 +1,35 @@
+/**
+ * Numeric less than or equal assertion.
+ */
+
+import { Assertion } from "./Assertion.ts";
+import { AssertionError } from "./AssertionError.ts";
+
+/**
+ * Assert that a number is less than or equal to the expected value.
+ * 
+ * @example
+ * await assertThat(5, lessThanOrEqual(5)); // pass
+ * await assertThat(4, lessThanOrEqual(5)); // pass
+ * await assertThat(6, lessThanOrEqual(5)); // fail
+ */
+export const lessThanOrEqual = (expected: number): Assertion<number> => {
+  return (actual: number): void => {
+    if (typeof actual !== "number") {
+      throw AssertionError({
+        message: "Expected a number but got " + typeof actual,
+        actual,
+        expected: "<= " + expected,
+        operator: "lessThanOrEqual"
+      });
+    }
+    if (!(actual <= expected)) {
+      throw AssertionError({
+        message: "Expected " + actual + " to be less than or equal to " + expected,
+        actual,
+        expected: "<= " + expected,
+        operator: "lessThanOrEqual"
+      });
+    }
+  };
+};

funee-lib/assertions/matches.ts

@@ -0,0 +1,34 @@
+/**
+ * Regex matching assertion.
+ */
+
+import { Assertion } from "./Assertion.ts";
+import { AssertionError } from "./AssertionError.ts";
+
+/**
+ * Assert that a string matches the expected regular expression.
+ * 
+ * @example
+ * await assertThat("hello123", matches(/\d+/)); // pass
+ * await assertThat("abc", matches(/^[a-z]+$/)); // pass
+ */
+export const matches = (pattern: RegExp): Assertion<string> => {
+  return (actual: string): void => {
+    if (typeof actual !== "string") {
+      throw AssertionError({
+        message: "Expected a string but got " + typeof actual,
+        actual,
+        expected: pattern.toString(),
+        operator: "matches"
+      });
+    }
+    if (!pattern.test(actual)) {
+      throw AssertionError({
+        message: "Expected " + JSON.stringify(actual) + " to match " + pattern.toString(),
+        actual,
+        expected: pattern.toString(),
+        operator: "matches"
+      });
+    }
+  };
+};

funee-lib/index.ts

@@ -354,6 +354,13 @@ export {
   assert,
   strictEqual,
   deepEqual,
+  // Matchers
+  contains,
+  matches,
+  greaterThan,
+  lessThan,
+  greaterThanOrEqual,
+  lessThanOrEqual,
 } from "./assertions/index.ts";
 
 // ============================================================================