@forgeax/engine-ecs 0.1.2

package/src/__tests__/ecs-error-code-31.test-d.ts

@@ -0,0 +1,42 @@
+// ecs-error-code-31.test-d - owner error union boundary type-test.
+//
+// Coverage (plan-strategy D-9):
+//   - EcsErrorCode union has gained the 31st member 'scene-override-type-
+//     mismatch' (literal D-9 string locked).
+//   - The new literal is assignable to EcsErrorCode at the type layer
+//     (positive assertion). Cross-feat hardening: the literal must NOT
+//     be quietly aliased to a different existing member.
+//
+// EcsErrorDetail evolution for this code (detail shape `{ code, comp,
+// field, expectedType, actualType }`) is exercised by M2 unit tests
+// (requirements §Edge cases table last row, reviewer Issue 1) — out
+// of scope here; this file only locks the EcsErrorCode union literal.
+//
+// TDD red signal: until w9 widens EcsErrorCode to 31 members, the
+// `toExtend<EcsErrorCode>` assertion produces TS2344. w9 turns this
+// red into green.
+//
+// Note: plan-tasks.json originally listed the targetFile under
+// packages/types; @forgeax/engine-types has zero engine-ecs dep
+// (math-free + ecs-free per AGENTS.md). The test must live under the
+// ecs package to import EcsErrorCode locally — recorded in the M1
+// report as filesOutsideTargets with reason.
+//
+// Charter mapping: proposition 4 (explicit failure: type-level union
+// widening surfaced at compile-time, not via ad-hoc string literal
+// matching).
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { EcsErrorCode } from '../errors';
+
+describe('owner error union boundary', () => {
+  it("keeps 'scene-override-type-mismatch' out of EcsErrorCode", () => {
+    expectTypeOf<'scene-override-type-mismatch'>().not.toExtend<EcsErrorCode>();
+  });
+});
+
+describe('EcsErrorCode enum write validation', () => {
+  it("includes the 'component-field-invalid-value' literal", () => {
+    expectTypeOf<'component-field-invalid-value'>().toExtend<EcsErrorCode>();
+  });
+});

package/src/__tests__/entity-disabling.unit.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { Disabled, defineComponent, World } from '../index';
+import type { Query } from '../query/query';
+
+const Target = defineComponent('EntityDisablingTarget', { value: 'u32' });
+
+function count(query: Query): number {
+  return [...query].length;
+}
+
+describe('Disabled default query filter', () => {
+  it('excludes disabled entities while explicit Disabled queries include them', () => {
+    const world = new World();
+    world.spawn({ component: Target, data: { value: 1 } }).unwrap();
+    world
+      .spawn({ component: Target, data: { value: 2 } }, { component: Disabled, data: {} })
+      .unwrap();
+
+    const active = world.query({ read: [Target] }).unwrap();
+    const disabled = world.query({ read: [Target], with: [Disabled] }).unwrap();
+
+    expect(count(active)).toBe(1);
+    expect(count(disabled)).toBe(1);
+  });
+
+  it('recomputes the default filter when an entity is disabled and re-enabled', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Target, data: { value: 1 } }).unwrap();
+    const active = world.query({ read: [Target] }).unwrap();
+
+    expect(count(active)).toBe(1);
+    world.addComponent(entity, { component: Disabled, data: {} }).unwrap();
+    expect(count(active)).toBe(0);
+    world.removeComponent(entity, Disabled).unwrap();
+    expect(count(active)).toBe(1);
+  });
+});

package/src/__tests__/entity-handle-codec-parity.unit.test.ts

@@ -0,0 +1,126 @@
+// Entity handle codec parity unit tests (w3).
+//
+// Runtime value assertions verifying bit-pattern equivalence between
+// entity-handle functions and the shared codec in @forgeax/engine-types.
+// These are the AC-14 regression baseline -- encodeEntity must produce
+// identical u32 values to codec.pack, and decode/entityIndex/entityGeneration
+// must match codec unpack results for all gen values including gen>=128
+// (>>>0 anti-ToInt32 guard, R5 from plan-strategy).
+//
+// This file holds runtime assertions; the plan targetFiles listed
+// .test-d.ts which are typecheck-only and cannot execute these checks.
+
+import { MAX_GEN, MAX_SLOT, pack, unpackGen, unpackSlot } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  decodeEntity,
+  ENTITY_MAX_GENERATION,
+  ENTITY_MAX_INDEX,
+  type EntityHandle,
+  encodeEntity,
+  entityGeneration,
+  entityIndex,
+} from '../entity-handle';
+
+describe('[w3] Entity codec parity -- constants', () => {
+  it('ENTITY_MAX_INDEX === MAX_SLOT', () => {
+    expect(ENTITY_MAX_INDEX).toBe(MAX_SLOT);
+  });
+
+  it('ENTITY_MAX_GENERATION === MAX_GEN', () => {
+    expect(ENTITY_MAX_GENERATION).toBe(MAX_GEN);
+  });
+});
+
+describe('[w3] Entity codec parity -- encodeEntity equals codec.pack', () => {
+  const SLOTS = [0, 1, 5, 42, 1023, 1024, 16777215] as const;
+
+  // gen=0: pack(slot,0)===slot invariant (D-8)
+  it('encodeEntity(i, 0) === pack(i, 0) for sampled slot values', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 0)).toBe(pack(slot, 0));
+    }
+  });
+
+  // gen=128: the >>>0 guard is load-bearing (R5)
+  it('encodeEntity(i, 128) === pack(i, 128) -- gen>=128 ToInt32 guard', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 128)).toBe(pack(slot, 128));
+    }
+  });
+
+  // gen=255: edge case, max generation
+  it('encodeEntity(i, 255) === pack(i, 255) -- max gen edge', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 255)).toBe(pack(slot, 255));
+    }
+  });
+
+  // gen=64: mid-range smoke test
+  it('encodeEntity(i, 64) === pack(i, 64) -- mid-range gen', () => {
+    for (const slot of SLOTS) {
+      expect(encodeEntity(slot, 64)).toBe(pack(slot, 64));
+    }
+  });
+
+  // Mixed gen values across different slots
+  it('encodeEntity(s, g) === pack(s, g) for cross-product of {0,1,42,1024,16777215} x {0,5,17,128,255}', () => {
+    const slots = [0, 1, 42, 1024, 16777215];
+    const gens = [0, 5, 17, 128, 255];
+    for (const slot of slots) {
+      for (const gen of gens) {
+        expect(encodeEntity(slot, gen)).toBe(pack(slot, gen));
+      }
+    }
+  });
+});
+
+describe('[w3] Entity codec parity -- decode functions', () => {
+  const CASES: [number, number][] = [
+    [0, 0],
+    [1, 0],
+    [42, 5],
+    [1024, 128],
+    [16777215, 255],
+    [0, 64],
+    [1, 255],
+    [16777215, 0],
+    [1023, 17],
+  ];
+
+  it('decodeEntity(pack(s, g)) returns { index: s, generation: g }', () => {
+    for (const [slot, gen] of CASES) {
+      const raw = pack(slot, gen) as EntityHandle;
+      const { index, generation } = decodeEntity(raw);
+      expect(index).toBe(slot);
+      expect(generation).toBe(gen);
+    }
+  });
+
+  it('entityIndex(pack(s, g)) === unpackSlot(pack(s, g))', () => {
+    for (const [slot, gen] of CASES) {
+      const raw = pack(slot, gen) as EntityHandle;
+      expect(entityIndex(raw)).toBe(unpackSlot(raw));
+    }
+  });
+
+  it('entityGeneration(pack(s, g)) === unpackGen(pack(s, g))', () => {
+    for (const [slot, gen] of CASES) {
+      const raw = pack(slot, gen) as EntityHandle;
+      expect(entityGeneration(raw)).toBe(unpackGen(raw));
+    }
+  });
+
+  // Full round-trip: encodeEntity -> entityIndex/entityGeneration
+  it('entityIndex(encodeEntity(s, g)) === s', () => {
+    for (const [slot, gen] of CASES) {
+      expect(entityIndex(encodeEntity(slot, gen))).toBe(slot);
+    }
+  });
+
+  it('entityGeneration(encodeEntity(s, g)) === g', () => {
+    for (const [slot, gen] of CASES) {
+      expect(entityGeneration(encodeEntity(slot, gen))).toBe(gen);
+    }
+  });
+});