@holoscript/framework 6.0.3

package/src/swarm/spatial/__tests__/FormationController.prod.test.ts

@@ -0,0 +1,240 @@
+/**
+ * FormationController — Production Tests
+ */
+import { describe, it, expect } from 'vitest';
+import { FormationController } from '../FormationController';
+import { Vector3 } from '../Vector3';
+
+function make(cfg = {}) {
+  return new FormationController(cfg);
+}
+function v(x: number, y = 0, z = 0) {
+  return new Vector3(x, y, z);
+}
+
+describe('FormationController — defaults', () => {
+  it('constructs without args', () => expect(() => make()).not.toThrow());
+  it('default type=line', () => expect(make().getConfig().type).toBe('line'));
+  it('default spacing=2', () => expect(make().getConfig().spacing).toBe(2));
+  it('default scale=1', () => expect(make().getConfig().scale).toBe(1));
+});
+
+describe('FormationController — line formation', () => {
+  it('generates correct slot count', () => {
+    expect(make({ type: 'line' }).generateSlots(5)).toHaveLength(5);
+  });
+  it('slot[0] is leader', () => {
+    expect(make({ type: 'line' }).generateSlots(3)[0].isLeaderSlot).toBe(true);
+  });
+  it('positions centered at spacing=2', () => {
+    const slots = make({ type: 'line', spacing: 2 }).generateSlots(3);
+    expect(slots[0].localPosition.x).toBeCloseTo(-2, 5);
+    expect(slots[1].localPosition.x).toBeCloseTo(0, 5);
+    expect(slots[2].localPosition.x).toBeCloseTo(2, 5);
+  });
+  it('single slot at origin', () => {
+    expect(make({ type: 'line', spacing: 2 }).generateSlots(1)[0].localPosition.x).toBe(0);
+  });
+});
+
+describe('FormationController — circle formation', () => {
+  it('generates correct count', () => {
+    expect(make({ type: 'circle' }).generateSlots(6)).toHaveLength(6);
+  });
+  it('all slots equidistant from center', () => {
+    const slots = make({ type: 'circle', spacing: 3 }).generateSlots(8);
+    const r = slots[0].localPosition.magnitude();
+    for (const s of slots) expect(s.localPosition.magnitude()).toBeCloseTo(r, 3);
+  });
+  it('y=0 for all slots', () => {
+    for (const s of make({ type: 'circle' }).generateSlots(6)) expect(s.localPosition.y).toBe(0);
+  });
+});
+
+describe('FormationController — grid formation', () => {
+  it('generates correct count', () => {
+    expect(make({ type: 'grid' }).generateSlots(9)).toHaveLength(9);
+  });
+  it('y=0 for all slots', () => {
+    for (const s of make({ type: 'grid' }).generateSlots(4)) expect(s.localPosition.y).toBe(0);
+  });
+});
+
+describe('FormationController — wedge formation', () => {
+  it('generates correct count', () => {
+    expect(make({ type: 'wedge' }).generateSlots(5)).toHaveLength(5);
+  });
+  it('leader at z=0', () => {
+    expect(make({ type: 'wedge' }).generateSlots(5)[0].localPosition.z).toBe(0);
+  });
+});
+
+describe('FormationController — sphere formation', () => {
+  it('generates correct count', () => {
+    expect(make({ type: 'sphere' }).generateSlots(10)).toHaveLength(10);
+  });
+  it('positions unique', () => {
+    const slots = make({ type: 'sphere' }).generateSlots(20);
+    const keys = slots.map(
+      (s) =>
+        `${s.localPosition.x.toFixed(2)},${s.localPosition.y.toFixed(2)},${s.localPosition.z.toFixed(2)}`
+    );
+    expect(new Set(keys).size).toBe(20);
+  });
+});
+
+describe('FormationController — diamond formation', () => {
+  it('generates correct count', () => {
+    expect(make({ type: 'diamond' }).generateSlots(7)).toHaveLength(7);
+  });
+});
+
+describe('FormationController — custom formation', () => {
+  it('creates slots from positions', () => {
+    const f = make();
+    f.setCustomFormation([v(0), v(5), v(10)]);
+    expect(f.getAllSlots()).toHaveLength(3);
+  });
+  it('type becomes custom', () => {
+    const f = make({ type: 'line' });
+    f.setCustomFormation([v(0)]);
+    expect(f.getConfig().type).toBe('custom');
+  });
+});
+
+describe('FormationController — assignAgent / removeAgent', () => {
+  it('first agent gets slot 0', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(3);
+    expect(f.assignAgent('a1')).toBe(0);
+  });
+  it('sequential agents get sequential slots', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(3);
+    expect(f.assignAgent('a1')).toBe(0);
+    expect(f.assignAgent('a2')).toBe(1);
+  });
+  it('assignAgent to specific slot', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(3);
+    expect(f.assignAgent('a1', 2)).toBe(2);
+  });
+  it('returns -1 when full', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(2);
+    f.assignAgent('a1');
+    f.assignAgent('a2');
+    expect(f.assignAgent('a3')).toBe(-1);
+  });
+  it('removeAgent frees slot', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(2);
+    f.assignAgent('a1');
+    expect(f.removeAgent('a1')).toBe(true);
+    expect(f.getAvailableSlots()).toHaveLength(2);
+  });
+  it('removeAgent unknown returns false', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(2);
+    expect(f.removeAgent('ghost')).toBe(false);
+  });
+  it('getAgentSlot returns assigned slot', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(3);
+    f.assignAgent('a1', 1);
+    expect(f.getAgentSlot('a1')?.index).toBe(1);
+  });
+  it('getAgentTarget returns world position', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(3);
+    f.assignAgent('a1');
+    expect(f.getAgentTarget('a1')).toBeDefined();
+  });
+});
+
+describe('FormationController — completeness', () => {
+  it('isComplete=false when slots available', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(2);
+    expect(f.isComplete()).toBe(false);
+  });
+  it('isComplete=true when all filled', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(2);
+    f.assignAgent('a1');
+    f.assignAgent('a2');
+    expect(f.isComplete()).toBe(true);
+  });
+  it('ratio = assigned/total', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(4);
+    f.assignAgent('a1');
+    f.assignAgent('a2');
+    expect(f.getCompletenessRatio()).toBeCloseTo(0.5, 5);
+  });
+});
+
+describe('FormationController — setCenter/setRotation/tightness', () => {
+  it('setCenter offsets world positions', () => {
+    const f = make({ type: 'line', spacing: 2 });
+    f.generateSlots(3);
+    f.setCenter(v(100, 0, 0));
+    expect(f.getAllSlots()[1].worldPosition.x).toBeCloseTo(100, 5);
+  });
+  it('setRotation changes world positions', () => {
+    const f = make({ type: 'line', spacing: 2 });
+    f.generateSlots(3);
+    const before = f.getAllSlots()[2].worldPosition.x;
+    f.setRotation(Math.PI / 2);
+    expect(f.getAllSlots()[2].worldPosition.x).not.toBeCloseTo(before, 1);
+  });
+  it('getCenter returns set value', () => {
+    const f = make({ type: 'line' });
+    f.generateSlots(1);
+    f.setCenter(v(7, 0, 0));
+    expect(f.getCenter().x).toBe(7);
+  });
+  it('tightness=1 when agents exactly on target', () => {
+    const f = make({ type: 'line', spacing: 2 });
+    f.generateSlots(2);
+    f.assignAgent('a1', 0);
+    f.assignAgent('a2', 1);
+    const pos = new Map<string, Vector3>([
+      ['a1', f.getAgentTarget('a1')!],
+      ['a2', f.getAgentTarget('a2')!],
+    ]);
+    expect(f.getFormationTightness(pos)).toBeCloseTo(1, 5);
+  });
+  it('tightness<1 when off target', () => {
+    const f = make({ type: 'line', spacing: 2 });
+    f.generateSlots(2);
+    f.assignAgent('a1', 0);
+    const target = f.getAgentTarget('a1')!;
+    const pos = new Map<string, Vector3>([['a1', v(target.x + 5)]]);
+    expect(f.getFormationTightness(pos)).toBeLessThan(1);
+  });
+});
+
+describe('FormationController — optimizeAssignments', () => {
+  it('assigns all available agents', () => {
+    const f = make({ type: 'line', spacing: 2 });
+    f.generateSlots(2);
+    const slots = f.getAllSlots();
+    const positions = new Map<string, Vector3>([
+      ['a1', v(slots[1].worldPosition.x)],
+      ['a2', v(slots[0].worldPosition.x)],
+    ]);
+    f.optimizeAssignments(positions);
+    expect(f.getAssignedSlots()).toHaveLength(2);
+  });
+});
+
+describe('FormationController — setConfig', () => {
+  it('partial update merges without overwriting others', () => {
+    const f = make({ spacing: 2, type: 'line' });
+    f.generateSlots(3);
+    f.setConfig({ spacing: 5 });
+    expect(f.getConfig().spacing).toBe(5);
+    expect(f.getConfig().type).toBe('line');
+  });
+});

package/src/swarm/spatial/__tests__/FormationController.test.ts

@@ -0,0 +1,297 @@
+/**
+ * FormationController Tests
+ * HoloScript v3.2 - Autonomous Agent Swarms
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { FormationController } from '../FormationController';
+import { Vector3 } from '../Vector3';
+
+describe('FormationController', () => {
+  let formation: FormationController;
+
+  beforeEach(() => {
+    formation = new FormationController({
+      type: 'line',
+      spacing: 2,
+    });
+  });
+
+  describe('slot generation', () => {
+    it('should generate line formation slots', () => {
+      const slots = formation.generateSlots(5);
+      expect(slots).toHaveLength(5);
+      expect(slots[0].isLeaderSlot).toBe(true);
+    });
+
+    it('should center line formation', () => {
+      const slots = formation.generateSlots(3);
+      // With spacing 2 and 3 agents: positions at -2, 0, 2
+      expect(slots[0].localPosition.x).toBe(-2);
+      expect(slots[1].localPosition.x).toBe(0);
+      expect(slots[2].localPosition.x).toBe(2);
+    });
+
+    it('should generate circle formation slots', () => {
+      formation.setConfig({ type: 'circle' });
+      const slots = formation.generateSlots(4);
+      expect(slots).toHaveLength(4);
+
+      // Check positions are distributed around circle
+      const positions = slots.map((s) => s.localPosition);
+      const firstAngle = Math.atan2(positions[0].z, positions[0].x);
+      const secondAngle = Math.atan2(positions[1].z, positions[1].x);
+      const angleDiff = Math.abs(secondAngle - firstAngle);
+      expect(angleDiff).toBeCloseTo(Math.PI / 2, 1);
+    });
+
+    it('should generate grid formation slots', () => {
+      formation.setConfig({ type: 'grid' });
+      const slots = formation.generateSlots(4);
+      expect(slots).toHaveLength(4);
+
+      // 4 agents in 2x2 grid
+      const positions = slots.map((s) => s.localPosition);
+      const uniqueX = new Set(positions.map((p) => Math.round(p.x * 100)));
+      const uniqueZ = new Set(positions.map((p) => Math.round(p.z * 100)));
+      expect(uniqueX.size).toBe(2);
+      expect(uniqueZ.size).toBe(2);
+    });
+
+    it('should generate wedge formation slots', () => {
+      formation.setConfig({ type: 'wedge' });
+      const slots = formation.generateSlots(5);
+      expect(slots).toHaveLength(5);
+
+      // Leader at front (0,0,0)
+      expect(slots[0].localPosition.x).toBe(0);
+      expect(slots[0].localPosition.z).toBe(0);
+    });
+
+    it('should generate diamond formation slots', () => {
+      formation.setConfig({ type: 'diamond' });
+      const slots = formation.generateSlots(5);
+      expect(slots).toHaveLength(5);
+    });
+
+    it('should generate sphere formation slots', () => {
+      formation.setConfig({ type: 'sphere' });
+      const slots = formation.generateSlots(10);
+      expect(slots).toHaveLength(10);
+
+      // Positions should be in 3D (varying y values)
+      const yValues = slots.map((s) => s.localPosition.y);
+      const minY = Math.min(...yValues);
+      const maxY = Math.max(...yValues);
+      expect(maxY - minY).toBeGreaterThan(0);
+    });
+  });
+
+  describe('custom formation', () => {
+    it('should set custom positions', () => {
+      const positions = [new Vector3(0, 0, 0), new Vector3(5, 0, 0), new Vector3(0, 5, 0)];
+      formation.setCustomFormation(positions);
+
+      const slots = formation.getAllSlots();
+      expect(slots).toHaveLength(3);
+      expect(slots[1].localPosition.x).toBe(5);
+    });
+  });
+
+  describe('agent assignment', () => {
+    beforeEach(() => {
+      formation.generateSlots(5);
+    });
+
+    it('should assign agent to first available slot', () => {
+      const index = formation.assignAgent('agent-1');
+      expect(index).toBe(0);
+    });
+
+    it('should assign agent to specified slot', () => {
+      const index = formation.assignAgent('agent-1', 3);
+      expect(index).toBe(3);
+    });
+
+    it('should track agent slot', () => {
+      formation.assignAgent('agent-1', 2);
+      const slot = formation.getAgentSlot('agent-1');
+      expect(slot?.index).toBe(2);
+    });
+
+    it('should return -1 when no slots available', () => {
+      for (let i = 0; i < 5; i++) {
+        formation.assignAgent(`agent-${i}`);
+      }
+      const index = formation.assignAgent('agent-extra');
+      expect(index).toBe(-1);
+    });
+
+    it('should remove agent from slot', () => {
+      formation.assignAgent('agent-1');
+      expect(formation.removeAgent('agent-1')).toBe(true);
+      expect(formation.getAgentSlot('agent-1')).toBeUndefined();
+    });
+
+    it('should make slot available after removal', () => {
+      formation.assignAgent('agent-1', 0);
+      formation.removeAgent('agent-1');
+      expect(formation.getAvailableSlots()).toHaveLength(5);
+    });
+
+    it('should get agent target position', () => {
+      formation.assignAgent('agent-1', 0);
+      const target = formation.getAgentTarget('agent-1');
+      expect(target).toBeDefined();
+    });
+  });
+
+  describe('slot queries', () => {
+    beforeEach(() => {
+      formation.generateSlots(5);
+      formation.assignAgent('agent-1', 0);
+      formation.assignAgent('agent-2', 1);
+    });
+
+    it('should get available slots', () => {
+      expect(formation.getAvailableSlots()).toHaveLength(3);
+    });
+
+    it('should get assigned slots', () => {
+      expect(formation.getAssignedSlots()).toHaveLength(2);
+    });
+  });
+
+  describe('center and rotation', () => {
+    it('should update world positions when center changes', () => {
+      formation.generateSlots(3);
+      formation.setCenter(new Vector3(100, 0, 0));
+
+      const slots = formation.getAllSlots();
+      // All world positions should be offset by 100 in x
+      expect(slots[1].worldPosition.x).toBe(100); // Center slot at x=0 + 100
+    });
+
+    it('should apply rotation', () => {
+      formation.generateSlots(2);
+      // Line along x axis
+      const originalX = formation.getAllSlots()[0].worldPosition.x;
+
+      formation.setRotation(Math.PI / 2); // 90 degrees
+
+      // After rotation, x offset should become z offset
+      const rotatedSlots = formation.getAllSlots();
+      expect(Math.abs(rotatedSlots[0].worldPosition.z)).toBeGreaterThan(0.1);
+    });
+
+    it('should get center', () => {
+      formation.setCenter(new Vector3(50, 50, 50));
+      const center = formation.getCenter();
+      expect(center.x).toBe(50);
+    });
+  });
+
+  describe('completeness', () => {
+    beforeEach(() => {
+      formation.generateSlots(3);
+    });
+
+    it('should detect incomplete formation', () => {
+      formation.assignAgent('agent-1');
+      expect(formation.isComplete()).toBe(false);
+    });
+
+    it('should detect complete formation', () => {
+      formation.assignAgent('agent-1');
+      formation.assignAgent('agent-2');
+      formation.assignAgent('agent-3');
+      expect(formation.isComplete()).toBe(true);
+    });
+
+    it('should calculate completeness ratio', () => {
+      formation.assignAgent('agent-1');
+      expect(formation.getCompletenessRatio()).toBeCloseTo(0.333, 2);
+    });
+
+    it('should return 0 for empty formation', () => {
+      formation = new FormationController();
+      expect(formation.getCompletenessRatio()).toBe(0);
+    });
+  });
+
+  describe('tightness', () => {
+    beforeEach(() => {
+      formation.generateSlots(3);
+      formation.assignAgent('agent-1', 0);
+      formation.assignAgent('agent-2', 1);
+    });
+
+    it('should calculate perfect tightness', () => {
+      const slots = formation.getAllSlots();
+      const positions = new Map([
+        ['agent-1', slots[0].worldPosition.clone()],
+        ['agent-2', slots[1].worldPosition.clone()],
+      ]);
+
+      const tightness = formation.getFormationTightness(positions);
+      expect(tightness).toBe(1);
+    });
+
+    it('should calculate lower tightness for spread agents', () => {
+      const slots = formation.getAllSlots();
+      const positions = new Map([
+        ['agent-1', slots[0].worldPosition.add(new Vector3(1, 0, 0))],
+        ['agent-2', slots[1].worldPosition.add(new Vector3(1, 0, 0))],
+      ]);
+
+      const tightness = formation.getFormationTightness(positions);
+      expect(tightness).toBeLessThan(1);
+      expect(tightness).toBeGreaterThan(0);
+    });
+
+    it('should return 1 for no assigned agents', () => {
+      formation = new FormationController();
+      formation.generateSlots(3);
+      expect(formation.getFormationTightness(new Map())).toBe(1);
+    });
+  });
+
+  describe('optimization', () => {
+    it('should optimize assignments to minimize distance', () => {
+      formation.generateSlots(3);
+
+      const positions = new Map([
+        ['agent-1', new Vector3(2, 0, 0)], // Closest to slot index 2
+        ['agent-2', new Vector3(-2, 0, 0)], // Closest to slot index 0
+        ['agent-3', new Vector3(0, 0, 0)], // Closest to slot index 1
+      ]);
+
+      formation.optimizeAssignments(positions);
+
+      const slot0 = formation.getAllSlots()[0];
+      const slot2 = formation.getAllSlots()[2];
+
+      // slot 0 at x=-2 should have agent-2
+      expect(slot0.agentId).toBe('agent-2');
+      // slot 2 at x=2 should have agent-1
+      expect(slot2.agentId).toBe('agent-1');
+    });
+  });
+
+  describe('configuration', () => {
+    it('should update config and regenerate slots', () => {
+      formation.generateSlots(3);
+      formation.setConfig({ spacing: 5 });
+
+      const slots = formation.getAllSlots();
+      // With spacing 5 and 3 agents: -5, 0, 5
+      expect(slots[2].localPosition.x - slots[0].localPosition.x).toBe(10);
+    });
+
+    it('should get current config', () => {
+      const config = formation.getConfig();
+      expect(config.type).toBe('line');
+      expect(config.spacing).toBe(2);
+    });
+  });
+});