@arcane-engine/runtime 0.1.0

package/src/systems/system.ts

@@ -0,0 +1,150 @@
+import type { Condition, Action, Rule, SystemDef, RuleResult, ExtendOptions } from "./types.ts";
+import { createError } from "../state/error.ts";
+
+/** Create a system definition from a name and list of rules. */
+export function system<S>(name: string, rules: readonly Rule<S>[]): SystemDef<S> {
+  return { name, rules };
+}
+
+// --- Fluent rule builder ---
+
+type RuleBuilderWithConditions<S> = {
+  then(...actions: Action<S>[]): Rule<S>;
+};
+
+type RuleBuilderBase<S> = {
+  when(...conditions: Condition<S>[]): RuleBuilderWithConditions<S>;
+  then(...actions: Action<S>[]): Rule<S>;
+  replaces(targetName: string): {
+    when(...conditions: Condition<S>[]): RuleBuilderWithConditions<S>;
+    then(...actions: Action<S>[]): Rule<S>;
+  };
+};
+
+/** Fluent builder for creating rules. */
+export function rule<S>(name: string): RuleBuilderBase<S> {
+  let replacesName: string | undefined;
+
+  const makeRule = (conditions: readonly Condition<S>[], actions: readonly Action<S>[]): Rule<S> => ({
+    name,
+    conditions,
+    actions,
+    ...(replacesName !== undefined ? { replaces: replacesName } : {}),
+  });
+
+  const withConditions = (conditions: readonly Condition<S>[]): RuleBuilderWithConditions<S> => ({
+    then(...actions: Action<S>[]) {
+      return makeRule(conditions, actions);
+    },
+  });
+
+  return {
+    when(...conditions: Condition<S>[]) {
+      return withConditions(conditions);
+    },
+    then(...actions: Action<S>[]) {
+      return makeRule([], actions);
+    },
+    replaces(targetName: string) {
+      replacesName = targetName;
+      return {
+        when(...conditions: Condition<S>[]) {
+          return withConditions(conditions);
+        },
+        then(...actions: Action<S>[]) {
+          return makeRule([], actions);
+        },
+      };
+    },
+  };
+}
+
+/** Find a rule by name, apply conditions, chain actions. */
+export function applyRule<S>(
+  sys: SystemDef<S>,
+  ruleName: string,
+  state: S,
+  args: Record<string, unknown> = {},
+): RuleResult<S> {
+  const r = sys.rules.find((r) => r.name === ruleName);
+  if (!r) {
+    return {
+      ok: false,
+      state,
+      ruleName,
+      error: createError("UNKNOWN_RULE", `Rule "${ruleName}" not found in system "${sys.name}"`, {
+        action: "applyRule",
+        reason: `No rule named "${ruleName}"`,
+        suggestion: `Available rules: ${sys.rules.map((r) => r.name).join(", ")}`,
+      }),
+    };
+  }
+
+  for (const condition of r.conditions) {
+    if (!condition(state, args)) {
+      return {
+        ok: false,
+        state,
+        ruleName,
+        error: createError("CONDITION_FAILED", `Conditions not met for rule "${ruleName}"`, {
+          action: "applyRule",
+          reason: "One or more conditions returned false",
+        }),
+      };
+    }
+  }
+
+  let current = state;
+  for (const action of r.actions) {
+    current = action(current, args);
+  }
+
+  return { ok: true, state: current, ruleName };
+}
+
+/** Return names of rules whose conditions are all met. */
+export function getApplicableRules<S>(
+  sys: SystemDef<S>,
+  state: S,
+  args: Record<string, unknown> = {},
+): string[] {
+  return sys.rules
+    .filter((r) => r.conditions.every((c) => c(state, args)))
+    .map((r) => r.name);
+}
+
+/** Extend a system: replace rules by name, add new rules, remove rules by name. */
+export function extend<S>(base: SystemDef<S>, options: ExtendOptions<S>): SystemDef<S> {
+  const removeSet = new Set(options.remove ?? []);
+  const newRules = options.rules ?? [];
+
+  // Build replacement map from new rules that have `replaces`
+  const replaceMap = new Map<string, Rule<S>>();
+  const additions: Rule<S>[] = [];
+  for (const r of newRules) {
+    if (r.replaces) {
+      replaceMap.set(r.replaces, r);
+    } else {
+      additions.push(r);
+    }
+  }
+
+  // Process base rules: replace or keep (unless removed)
+  const result: Rule<S>[] = [];
+  for (const r of base.rules) {
+    if (removeSet.has(r.name)) continue;
+    const replacement = replaceMap.get(r.name);
+    if (replacement) {
+      result.push(replacement);
+    } else {
+      result.push(r);
+    }
+  }
+
+  // Append non-replacement additions
+  for (const r of additions) {
+    result.push(r);
+  }
+
+  return { name: base.name, rules: result };
+}

package/src/systems/types.ts

@@ -0,0 +1,35 @@
+import type { ArcaneError } from "../state/error.ts";
+
+/** A condition that must be true for a rule to fire. */
+export type Condition<S> = (state: S, args: Record<string, unknown>) => boolean;
+
+/** An action that transforms state when a rule fires. */
+export type Action<S> = (state: S, args: Record<string, unknown>) => S;
+
+/** A named rule with conditions and actions. */
+export type Rule<S> = Readonly<{
+  name: string;
+  conditions: readonly Condition<S>[];
+  actions: readonly Action<S>[];
+  replaces?: string;
+}>;
+
+/** A named system: a collection of rules. */
+export type SystemDef<S> = Readonly<{
+  name: string;
+  rules: readonly Rule<S>[];
+}>;
+
+/** Result of applying a single rule. */
+export type RuleResult<S> = Readonly<{
+  ok: boolean;
+  state: S;
+  ruleName: string;
+  error?: ArcaneError;
+}>;
+
+/** Options for extending a system. */
+export type ExtendOptions<S> = {
+  rules?: readonly Rule<S>[];
+  remove?: readonly string[];
+};

package/src/testing/harness.ts

@@ -0,0 +1,271 @@
+// Universal test harness — works in both Node.js and V8 (deno_core).
+//
+// Node mode: delegates to node:test and node:assert.
+// V8 mode: standalone implementations with result reporting via
+//   globalThis.__reportTest(suite, test, passed, error?)
+
+type TestFn = () => void | Promise<void>;
+type DescribeFn = (name: string, fn: () => void) => void;
+type ItFn = (name: string, fn: TestFn) => void;
+
+interface Assert {
+  equal(actual: unknown, expected: unknown, message?: string): void;
+  deepEqual(actual: unknown, expected: unknown, message?: string): void;
+  notEqual(actual: unknown, expected: unknown, message?: string): void;
+  notDeepEqual(actual: unknown, expected: unknown, message?: string): void;
+  ok(value: unknown, message?: string): void;
+  match(actual: string, expected: RegExp, message?: string): void;
+  throws(fn: () => unknown, expected?: RegExp, message?: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Environment detection
+// ---------------------------------------------------------------------------
+
+const isNode =
+  typeof globalThis.process !== "undefined" &&
+  typeof globalThis.process.versions?.node === "string";
+
+// ---------------------------------------------------------------------------
+// V8 standalone implementations
+// ---------------------------------------------------------------------------
+
+function deepEqualImpl(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+
+  if (typeof a !== "object") return false;
+
+  // Both are non-null objects at this point
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+
+  const aIsArray = Array.isArray(aObj);
+  const bIsArray = Array.isArray(bObj);
+  if (aIsArray !== bIsArray) return false;
+
+  if (aIsArray) {
+    const aArr = a as unknown[];
+    const bArr = b as unknown[];
+    if (aArr.length !== bArr.length) return false;
+    for (let i = 0; i < aArr.length; i++) {
+      if (!deepEqualImpl(aArr[i], bArr[i])) return false;
+    }
+    return true;
+  }
+
+  const aKeys = Object.keys(aObj).sort();
+  const bKeys = Object.keys(bObj).sort();
+  if (aKeys.length !== bKeys.length) return false;
+  for (let i = 0; i < aKeys.length; i++) {
+    if (aKeys[i] !== bKeys[i]) return false;
+  }
+  for (const key of aKeys) {
+    if (!deepEqualImpl(aObj[key], bObj[key])) return false;
+  }
+  return true;
+}
+
+function formatValue(v: unknown): string {
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "object" && v !== null) {
+    try {
+      return JSON.stringify(v);
+    } catch {
+      return String(v);
+    }
+  }
+  return String(v);
+}
+
+function fail(message: string): never {
+  throw new Error(message);
+}
+
+const v8Assert: Assert = {
+  equal(actual, expected, message?) {
+    if (actual !== expected) {
+      fail(
+        message ??
+          `Expected ${formatValue(actual)} to strictly equal ${formatValue(expected)}`,
+      );
+    }
+  },
+  deepEqual(actual, expected, message?) {
+    if (!deepEqualImpl(actual, expected)) {
+      fail(
+        message ??
+          `Expected deep equality.\nActual:   ${formatValue(actual)}\nExpected: ${formatValue(expected)}`,
+      );
+    }
+  },
+  notEqual(actual, expected, message?) {
+    if (actual === expected) {
+      fail(
+        message ??
+          `Expected ${formatValue(actual)} to not strictly equal ${formatValue(expected)}`,
+      );
+    }
+  },
+  notDeepEqual(actual, expected, message?) {
+    if (deepEqualImpl(actual, expected)) {
+      fail(
+        message ??
+          `Expected values to not be deeply equal.\nValue: ${formatValue(actual)}`,
+      );
+    }
+  },
+  ok(value, message?) {
+    if (!value) {
+      fail(message ?? `Expected truthy value, got ${formatValue(value)}`);
+    }
+  },
+  match(actual, expected, message?) {
+    if (!expected.test(actual)) {
+      fail(
+        message ??
+          `Expected ${formatValue(actual)} to match ${expected}`,
+      );
+    }
+  },
+  throws(fn, expected?, message?) {
+    let threw = false;
+    let error: unknown;
+    try {
+      fn();
+    } catch (e) {
+      threw = true;
+      error = e;
+    }
+    if (!threw) {
+      fail(message ?? "Expected function to throw");
+    }
+    if (expected instanceof RegExp) {
+      const errMsg =
+        error instanceof Error ? error.message : String(error);
+      if (!expected.test(errMsg)) {
+        fail(
+          message ??
+            `Expected thrown error message to match ${expected}, got ${formatValue(errMsg)}`,
+        );
+      }
+    }
+  },
+};
+
+// ---------------------------------------------------------------------------
+// V8 test runner — collects describe/it blocks, runs them on demand
+// ---------------------------------------------------------------------------
+
+interface TestCase {
+  name: string;
+  fn: TestFn;
+}
+
+interface Suite {
+  name: string;
+  tests: TestCase[];
+}
+
+const suites: Suite[] = [];
+let currentSuite: Suite | null = null;
+
+const v8Describe: DescribeFn = (name, fn) => {
+  const suite: Suite = { name, tests: [] };
+  const parentSuite = currentSuite;
+  currentSuite = suite;
+  fn();
+  currentSuite = parentSuite;
+
+  if (parentSuite) {
+    // Nested describe: prefix child tests with parent name
+    for (const test of suite.tests) {
+      parentSuite.tests.push({
+        name: `${name} > ${test.name}`,
+        fn: test.fn,
+      });
+    }
+  } else {
+    suites.push(suite);
+  }
+};
+
+const v8It: ItFn = (name, fn) => {
+  if (!currentSuite) {
+    const anon: Suite = { name: "<root>", tests: [{ name, fn }] };
+    suites.push(anon);
+  } else {
+    currentSuite.tests.push({ name, fn });
+  }
+};
+
+// Declare the reporter op that Rust will provide
+declare const __reportTest: (
+  suite: string,
+  test: string,
+  passed: boolean,
+  error?: string,
+) => void;
+
+(globalThis as any).__runTests = async () => {
+  let total = 0;
+  let passed = 0;
+  let failed = 0;
+
+  const hasReporter = typeof (globalThis as any).__reportTest === "function";
+
+  for (const suite of suites) {
+    for (const test of suite.tests) {
+      total++;
+      try {
+        const result = test.fn();
+        if (result && typeof (result as any).then === "function") {
+          await result;
+        }
+        passed++;
+        if (hasReporter) {
+          (globalThis as any).__reportTest(suite.name, test.name, true);
+        }
+      } catch (e) {
+        failed++;
+        const errMsg = e instanceof Error ? e.message : String(e);
+        if (hasReporter) {
+          (globalThis as any).__reportTest(suite.name, test.name, false, errMsg);
+        }
+      }
+    }
+  }
+
+  return { total, passed, failed };
+};
+
+// ---------------------------------------------------------------------------
+// Node.js — delegate to built-in modules
+// ---------------------------------------------------------------------------
+
+let describe: DescribeFn;
+let it: ItFn;
+let assert: Assert;
+
+if (isNode) {
+  const nodeTest = await import("node:test");
+  const nodeAssert = await import("node:assert");
+  describe = nodeTest.describe;
+  it = nodeTest.it;
+  assert = {
+    equal: nodeAssert.strict.equal,
+    deepEqual: nodeAssert.strict.deepEqual,
+    notEqual: nodeAssert.strict.notEqual,
+    notDeepEqual: nodeAssert.strict.notDeepEqual,
+    ok: nodeAssert.strict.ok,
+    match: nodeAssert.strict.match,
+    throws: nodeAssert.strict.throws as any, // Node's throws has more overloads
+  };
+} else {
+  describe = v8Describe;
+  it = v8It;
+  assert = v8Assert;
+}
+
+export { describe, it, assert };

package/src/testing/mock-renderer.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Tests demonstrating mock renderer usage
+ */
+
+// @ts-nocheck - Uses Node-specific test APIs (beforeEach/afterEach) not in harness
+import { describe, it, assert } from "./harness.ts";
+import { mockRenderer, installMockRenderer, restoreRenderer } from "./mock-renderer.ts";
+
+describe("Mock Renderer", () => {
+  beforeEach(() => {
+    mockRenderer.reset();
+  });
+
+  it("should validate drawRect parameters", () => {
+    mockRenderer.drawRect(10.0, 20.0, 100.0, 50.0, { color: { r: 1.0, g: 0.5, b: 0.0 } });
+
+    mockRenderer.assertNoErrors();
+    mockRenderer.assertCalled("drawRect", 1);
+  });
+
+  it("should catch wrong parameter types", () => {
+    // Wrong: passing object instead of separate params
+    mockRenderer.drawRect({ x: 10 } as any, undefined, undefined, undefined);
+
+    assert(mockRenderer.hasErrors(), "Should have errors");
+    const errors = mockRenderer.getErrors();
+    assert(errors.some(e => e.includes("must be number")), "Should complain about type");
+  });
+
+  it("should catch invalid color values", () => {
+    // Color values must be 0.0-1.0
+    mockRenderer.drawRect(0, 0, 100, 100, { color: { r: 255, g: 255, b: 255 } });
+
+    assert(mockRenderer.hasErrors(), "Should have errors");
+    const errors = mockRenderer.getErrors();
+    assert(errors.some(e => e.includes("color.r must be 0.0-1.0")), "Should catch invalid color");
+  });
+
+  it("should validate drawText parameters", () => {
+    mockRenderer.drawText("Hello", { x: 10.0, y: 20.0, size: 16.0, color: { r: 1.0, g: 1.0, b: 1.0 } });
+
+    mockRenderer.assertNoErrors();
+    mockRenderer.assertCalled("drawText", 1);
+  });
+
+  it("should catch NaN values", () => {
+    mockRenderer.drawRect(NaN, 0, 100, 100);
+
+    assert(mockRenderer.hasErrors(), "Should catch NaN");
+    const errors = mockRenderer.getErrors();
+    assert(errors.some(e => e.includes("NaN")), "Should complain about NaN");
+  });
+});
+
+// Example: Testing a game's rendering code
+describe("Game Visual Tests", () => {
+  beforeEach(() => {
+    mockRenderer.reset();
+    installMockRenderer();
+  });
+
+  afterEach(() => {
+    restoreRenderer();
+  });
+
+  it("should render HUD correctly", () => {
+    // Import game code that uses rendering
+    function renderHUD(health: number, gold: number) {
+      (globalThis as any).drawText(`HP: ${health}`, {
+        x: 10.0,
+        y: 10.0,
+        size: 16.0,
+        color: { r: 1.0, g: 0.0, b: 0.0 }
+      });
+
+      (globalThis as any).drawText(`Gold: ${gold}`, {
+        x: 10.0,
+        y: 30.0,
+        size: 16.0,
+        color: { r: 1.0, g: 0.84, b: 0.0 }
+      });
+    }
+
+    renderHUD(100, 50);
+
+    mockRenderer.assertNoErrors();
+    mockRenderer.assertCalled("drawText", 2);
+
+    const calls = mockRenderer.getCalls("drawText");
+    assert(calls[0].params[0] === "HP: 100", "First text correct");
+    assert(calls[1].params[0] === "Gold: 50", "Second text correct");
+  });
+});