@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/src/__tests__/schedule-inspection.unit.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { defineComponent } from '../component';
+import { FixedUpdate, Update } from '../schedule-token';
+import { World } from '../world';
+
+describe('schedule-scoped inspection', () => {
+  it('groups systems by their owning schedule', () => {
+    const world = new World();
+    world.addSystem(Update, { name: 'update-system', queries: [], fn: () => {} });
+    world.addSystem(FixedUpdate, { name: 'fixed-system', queries: [], fn: () => {} });
+
+    const inspection = world.inspect();
+
+    expect(inspection.scheduleSystemCount(Update)).toBe(1);
+    expect(inspection.scheduleSystemCount(FixedUpdate)).toBe(1);
+    expect(inspection.schedules).toEqual([
+      { schedule: Update, systems: [{ name: 'update-system', sets: [] }] },
+      { schedule: FixedUpdate, systems: [{ name: 'fixed-system', sets: [] }] },
+    ]);
+  });
+
+  it('projects a JSON-safe schedule graph with declared access metadata', () => {
+    const Position = defineComponent('ScheduleDataPosition', { x: 'f32' });
+    const Marker = defineComponent('ScheduleDataMarker', { value: 'u32' });
+    const Optional = defineComponent('ScheduleDataOptional', { value: 'u32' });
+    const world = new World();
+    world.addSystem(Update, {
+      name: 'producer',
+      queries: [{ with: [Position] }],
+      fn: () => {},
+    });
+    world.addSystem(Update, {
+      name: 'consumer',
+      after: ['producer'],
+      queries: [
+        {
+          with: [Position],
+          without: [Marker],
+          optional: [Optional],
+          changed: [Position],
+          added: [Marker],
+        },
+      ],
+      fn: () => {},
+    });
+
+    const data = world.scheduleData();
+    const update = data.find((schedule) => schedule.name === 'Update');
+
+    expect(update?.systems).toEqual([
+      {
+        name: 'producer',
+        sets: [],
+        before: [],
+        after: [],
+        queries: [
+          { with: ['ScheduleDataPosition'], without: [], optional: [], changed: [], added: [] },
+        ],
+        resources: [],
+      },
+      {
+        name: 'consumer',
+        sets: [],
+        before: [],
+        after: ['producer'],
+        queries: [
+          {
+            with: ['ScheduleDataPosition'],
+            without: ['ScheduleDataMarker'],
+            optional: ['ScheduleDataOptional'],
+            changed: ['ScheduleDataPosition'],
+            added: ['ScheduleDataMarker'],
+          },
+        ],
+        resources: [],
+      },
+    ]);
+    expect(update?.dependencies).toContainEqual(['producer', 'consumer']);
+    expect(JSON.parse(JSON.stringify(data))).toEqual(data);
+  });
+});

package/src/__tests__/schedule-scope-error.unit.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { FixedUpdate, Update } from '../schedule-token';
+import { World } from '../world';
+
+describe('schedule scope errors', () => {
+  it('rejects a string system-name ordering edge that crosses schedules', () => {
+    const world = new World();
+    world.addSystem(FixedUpdate, { name: 'fixed-system', queries: [], fn: () => {} });
+    world.addSystem(Update, {
+      name: 'update-system',
+      queries: [],
+      after: ['fixed-system'],
+      fn: () => {},
+    });
+
+    const result = world.update(0);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('schedule-scope-mismatch');
+      expect(result.error.detail).toMatchObject({
+        sourceSchedule: 'Update',
+        targetSchedule: 'FixedUpdate',
+        reference: 'fixed-system',
+      });
+    }
+  });
+
+  it.each([
+    'before',
+    'after',
+  ] as const)('rejects a FixedUpdate %s edge that references the Update token', (edge) => {
+    const world = new World();
+    world.addSystem(FixedUpdate, {
+      name: 'fixed-system',
+      queries: [],
+      [edge]: [Update],
+      fn: () => {},
+    });
+
+    const result = world.update(0);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('schedule-scope-mismatch');
+      expect(result.error.detail).toMatchObject({
+        sourceSchedule: 'FixedUpdate',
+        targetSchedule: 'Update',
+        reference: 'Update',
+      });
+    }
+  });
+
+  it('does not silently skip an unknown schedule token', () => {
+    const world = new World();
+    const unknown = Object.freeze({ name: 'Unknown' }) as typeof Update;
+
+    const result = world.addSystem(unknown, { name: 'unknown', queries: [], fn: () => {} });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('schedule-scope-mismatch');
+      expect(result.error.hint).toContain('Update');
+    }
+  });
+});

package/src/__tests__/schedule-token.unit.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { defineSystemSet } from '../schedule';
+import { FixedUpdate, Update } from '../schedule-token';
+import { World } from '../world';
+
+describe('ScheduleToken registration', () => {
+  it('exports frozen, nominal built-in tokens', () => {
+    expect(Object.isFrozen(Update)).toBe(true);
+    expect(Object.isFrozen(FixedUpdate)).toBe(true);
+    expect(Update).not.toBe(FixedUpdate);
+  });
+
+  it('requires ScheduleToken as the first registration argument', () => {
+    const world = new World();
+    const system = { name: 'update-system', queries: [], fn: () => {} };
+
+    world.addSystem(Update, system);
+    // @ts-expect-error token-first registration has no implicit Update overload
+    world.addSystem(system);
+  });
+
+  it('scopes set membership and configuration to a token', () => {
+    const world = new World();
+    const set = defineSystemSet({ name: 'update-set' });
+    const system = { name: 'set-system', queries: [], fn: () => {} };
+
+    expect(world.addSystems(Update, set, [system]).ok).toBe(true);
+    expect(world.inspect().systemCount).toBe(1);
+  });
+
+  it('requires a token for removal and replacement', () => {
+    const world = new World();
+    world.addSystem(Update, { name: 'replaceable', queries: [], fn: () => {} });
+
+    expect(world.removeSystem(Update, 'replaceable').ok).toBe(true);
+    world.addSystem(Update, { name: 'replaceable', queries: [], fn: () => {} });
+    expect(
+      world.replaceSystem(Update, 'replaceable', {
+        name: 'replaceable',
+        queries: [],
+        fn: () => {},
+      }).ok,
+    ).toBe(true);
+  });
+
+  it('publishes one identity for split runtime bundles', () => {
+    const registry = globalThis as typeof globalThis & {
+      readonly [key: symbol]: unknown;
+    };
+
+    expect(registry[Symbol.for('forgeax.ecs.schedule-token.Update')]).toBe(Update);
+    expect(registry[Symbol.for('forgeax.ecs.schedule-token.FixedUpdate')]).toBe(FixedUpdate);
+  });
+});

package/src/__tests__/schema-vocab.test-d.ts

@@ -0,0 +1,103 @@
+// Compile-time type-derivation tests for the schema-vocab parser (w3 + AC-01).
+//
+// Locks the 5 keyword shapes in ScalarFieldType / SchemaVocabKeyword (the
+// retired predecessor of `array<entity>` is closed out by feat-20260514-ecs-
+// children-instances-managed-buffer-array w3 — `array<entity>` is the SSOT
+// now; migration covered by `managed-array-vocab.test-d.ts`):
+//   - 'buffer:<bytes>'    => Uint8Array
+//   - 'unique<T>'            => Handle<T, 'unique'>
+//   - 'shared<T>'         => Handle<T, 'shared'>
+//   - 'entity'            => Entity | null
+//   - 'array<entity>'     => VarArrayView<Entity>  (covered in managed-array-vocab.test-d)
+//
+// These five keywords are the schema-vocab surface AI users compose into
+// component schemas (`defineComponent('Foo', { mat: { type: 'unique<MaterialAsset>' } })`).
+// `FieldValueType<T>` resolves the JS-value shape so `world.get(e, Foo).mat`
+// is automatically typed as `Handle<'MaterialAsset','unique'>` without casts.
+//
+// Anti-keyword guardrail (AC-01 §"unsupported-keyword fail-fast"): unknown
+// keywords like `'foobar'` must NOT typecheck as a `ScalarFieldType`. The
+// `@ts-expect-error` directive turns RED the moment the union accidentally
+// widens to `string`.
+
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type { FieldValueType, ScalarFieldType, SchemaOf, ShapeOf } from '../component';
+import { defineComponent } from '../component';
+import type { EntityHandle } from '../entity-handle';
+
+describe('schema vocab — keyword recognition (w3, AC-01)', () => {
+  it('buffer:<N> derives to Uint8Array', () => {
+    expectTypeOf<FieldValueType<'buffer<128>'>>().toEqualTypeOf<Uint8Array>();
+    expectTypeOf<FieldValueType<'buffer<1>'>>().toEqualTypeOf<Uint8Array>();
+    expectTypeOf<FieldValueType<'buffer<65536>'>>().toEqualTypeOf<Uint8Array>();
+  });
+
+  it("ref<T> derives to Handle<T, 'unique'>", () => {
+    expectTypeOf<FieldValueType<'unique<MaterialAsset>'>>().toEqualTypeOf<
+      Handle<'MaterialAsset', 'unique'>
+    >();
+    expectTypeOf<FieldValueType<'unique<TextureAsset>'>>().toEqualTypeOf<
+      Handle<'TextureAsset', 'unique'>
+    >();
+  });
+
+  it("handle<T> derives to Handle<T, 'shared'>", () => {
+    expectTypeOf<FieldValueType<'shared<MeshAsset>'>>().toEqualTypeOf<
+      Handle<'MeshAsset', 'shared'>
+    >();
+    expectTypeOf<FieldValueType<'shared<MaterialAsset>'>>().toEqualTypeOf<
+      Handle<'MaterialAsset', 'shared'>
+    >();
+  });
+
+  it('entity derives to Entity | null', () => {
+    expectTypeOf<FieldValueType<'entity'>>().toEqualTypeOf<EntityHandle | null>();
+  });
+
+  it('cross-keyword: ref/handle differ on the mode axis (managed vs unmanaged)', () => {
+    type Managed = FieldValueType<'unique<MaterialAsset>'>;
+    type Unmanaged = FieldValueType<'shared<MaterialAsset>'>;
+    expectTypeOf<Managed>().not.toEqualTypeOf<Unmanaged>();
+  });
+});
+
+describe('schema vocab — anti-keyword (w3, AC-01)', () => {
+  it('unknown keyword is rejected by ScalarFieldType union', () => {
+    // @ts-expect-error 'foobar' is not a ScalarFieldType keyword.
+    const bad: ScalarFieldType = 'foobar';
+    void bad;
+  });
+});
+
+describe('schema vocab — ShapeOf composition (w3, AC-01)', () => {
+  it('ShapeOf threads each keyword through FieldValueType', () => {
+    type S = {
+      data: 'buffer<64>';
+      mat: 'unique<MaterialAsset>';
+      mesh: 'shared<MeshAsset>';
+      parent: 'entity';
+    };
+    type Expected = {
+      data: Uint8Array;
+      mat: Handle<'MaterialAsset', 'unique'>;
+      mesh: Handle<'MeshAsset', 'shared'>;
+      parent: EntityHandle | null;
+    };
+    expectTypeOf<ShapeOf<S>>().toEqualTypeOf<Expected>();
+  });
+
+  it('defineComponent infers the new vocab from the schema literal', () => {
+    const C = defineComponent('VocabSample', {
+      data: { type: 'buffer<32>' },
+      mat: { type: 'unique<MaterialAsset>' },
+      mesh: { type: 'shared<MeshAsset>' },
+      parent: { type: 'entity' },
+    });
+    type Shape = ShapeOf<SchemaOf<typeof C>>;
+    expectTypeOf<Shape['data']>().toEqualTypeOf<Uint8Array>();
+    expectTypeOf<Shape['mat']>().toEqualTypeOf<Handle<'MaterialAsset', 'unique'>>();
+    expectTypeOf<Shape['mesh']>().toEqualTypeOf<Handle<'MeshAsset', 'shared'>>();
+    expectTypeOf<Shape['parent']>().toEqualTypeOf<EntityHandle | null>();
+  });
+});