boardgame-core/tests/core/rule.test.ts

import { describe, it, expect } from 'vitest';
import { createRule, type RuleContext, type RuleEngineHost } from '../../src/core/rule';
import { createGameContext } from '../../src/core/context';
import type { Command } from '../../src/utils/command';

function isCommand(value: Command | RuleContext<unknown>): value is Command {
    return 'name' in value;
}

function schema(value: string | { name: string; params: any[]; options: any[]; flags: any[] }) {
    return { type: 'schema' as const, value };
}

describe('Rule System', () => {
    function createTestGame() {
        const game = createGameContext();
        return game;
    }

    describe('createRule', () => {
        it('should create a rule definition with parsed schema', () => {
            const rule = createRule('<from> <to> [--force]', function*(cmd) {
                return { from: cmd.params[0], to: cmd.params[1] };
            });

            expect(rule.schema.params).toHaveLength(2);
            expect(rule.schema.params[0].name).toBe('from');
            expect(rule.schema.params[0].required).toBe(true);
            expect(rule.schema.params[1].name).toBe('to');
            expect(rule.schema.params[1].required).toBe(true);
            expect(Object.keys(rule.schema.flags)).toHaveLength(1);
            expect(rule.schema.flags.force.name).toBe('force');
        });

        it('should create a generator when called', () => {
            const game = createTestGame();
            const rule = createRule('<target>', function*(cmd) {
                return cmd.params[0];
            });

            const gen = rule.create.call(game as unknown as RuleEngineHost, { name: 'test', params: ['card1'], flags: {}, options: {} });
            const result = gen.next();
            expect(result.done).toBe(true);
            expect(result.value).toBe('card1');
        });
    });

    describe('dispatchCommand - rule invocation', () => {
        it('should invoke a registered rule and yield schema', () => {
            const game = createTestGame();

            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                yield schema({ name: '', params: [], options: [], flags: [] });
                return { moved: cmd.params[0] };
            }));

            const ctx = game.dispatchCommand('move card1 hand');

            expect(ctx).toBeDefined();
            expect(ctx!.state).toBe('yielded');
            expect(ctx!.schema).toBeDefined();
            expect(ctx!.resolution).toBeUndefined();
        });

        it('should complete a rule when final command matches yielded schema', () => {
            const game = createTestGame();

            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                const confirm = yield schema({ name: '', params: [], options: [], flags: [] });
                const confirmCmd = isCommand(confirm) ? confirm : undefined;
                return { moved: cmd.params[0], confirmed: confirmCmd?.name === 'confirm' };
            }));

            game.dispatchCommand('move card1 hand');
            const ctx = game.dispatchCommand('confirm');

            expect(ctx).toBeDefined();
            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toEqual({ moved: 'card1', confirmed: true });
        });

        it('should return undefined when command matches no rule and no yielded context', () => {
            const game = createTestGame();

            const result = game.dispatchCommand('unknown command');

            expect(result).toBeUndefined();
        });

        it('should pass the initial command to the generator', () => {
            const game = createTestGame();

            game.registerRule('attack', createRule('<target> [--power: number]', function*(cmd) {
                return { target: cmd.params[0], power: cmd.options.power || '1' };
            }));

            const ctx = game.dispatchCommand('attack goblin --power 5');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toEqual({ target: 'goblin', power: 5 });
        });

        it('should complete immediately if generator does not yield', () => {
            const game = createTestGame();

            game.registerRule('look', createRule('[--at]', function*() {
                return 'looked';
            }));

            const ctx = game.dispatchCommand('look');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toBe('looked');
        });
    });

    describe('dispatchCommand - rule priority', () => {
        it('should prioritize new rule invocation over feeding yielded context', () => {
            const game = createTestGame();

            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                yield schema({ name: '', params: [], options: [], flags: [] });
                return { moved: cmd.params[0] };
            }));

            game.registerRule('confirm', createRule('', function*() {
                return 'new confirm rule';
            }));

            game.dispatchCommand('move card1 hand');

            const ctx = game.dispatchCommand('confirm');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toBe('new confirm rule');
            expect(ctx!.type).toBe('');
        });
    });

    describe('dispatchCommand - fallback to yielded context', () => {
        it('should feed a yielded context when command does not match any rule', () => {
            const game = createTestGame();

            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                const response = yield schema({ name: '', params: [], options: [], flags: [] });
                const rcmd = isCommand(response) ? response : undefined;
                return { moved: cmd.params[0], response: rcmd?.name };
            }));

            game.dispatchCommand('move card1 hand');
            const ctx = game.dispatchCommand('yes');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toEqual({ moved: 'card1', response: 'yes' });
        });

        it('should skip non-matching commands for yielded context', () => {
            const game = createTestGame();

            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                const response = yield schema('<item>');
                const rcmd = isCommand(response) ? response : undefined;
                return { response: rcmd?.params[0] };
            }));

            game.dispatchCommand('move card1 hand');

            const ctx = game.dispatchCommand('goblin');

            expect(ctx).toBeUndefined();
        });

        it('should validate command against yielded schema', () => {
            const game = createTestGame();

            game.registerRule('trade', createRule('<from> <to>', function*(cmd) {
                const response = yield schema('<item> [amount: number]');
                const rcmd = isCommand(response) ? response : undefined;
                return { traded: rcmd?.params[0] };
            }));

            game.dispatchCommand('trade player1 player2');
            const ctx = game.dispatchCommand('offer gold 5');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toEqual({ traded: 'gold' });
        });
    });

    describe('dispatchCommand - deepest context first', () => {
        it('should feed the deepest yielded context', () => {
            const game = createTestGame();

            game.registerRule('parent', createRule('<action>', function*() {
                yield schema({ name: '', params: [], options: [], flags: [] });
                return 'parent done';
            }));

            game.registerRule('child', createRule('<target>', function*() {
                yield schema({ name: '', params: [], options: [], flags: [] });
                return 'child done';
            }));

            game.dispatchCommand('parent start');
            game.dispatchCommand('child target1');

            const ctx = game.dispatchCommand('grandchild_cmd');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toBe('child done');
        });
    });

    describe('nested rule invocations', () => {
        it('should link child to parent', () => {
            const game = createTestGame();

            game.registerRule('parent', createRule('<action>', function*() {
                yield schema('child_cmd');
                return 'parent done';
            }));

            game.registerRule('child_cmd', createRule('<target>', function*() {
                return 'child done';
            }));

            game.dispatchCommand('parent start');
            const parentCtx = game.ruleContexts.value[0];

            game.dispatchCommand('child_cmd target1');

            expect(parentCtx.state).toBe('waiting');

            const childCtx = game.ruleContexts.value[1];
            expect(childCtx.parent).toBe(parentCtx);
            expect(parentCtx.children).toContain(childCtx);
        });

        it('should discard previous children when a new child is invoked', () => {
            const game = createTestGame();

            game.registerRule('parent', createRule('<action>', function*() {
                yield schema('child_a | child_b');
                return 'parent done';
            }));

            game.registerRule('child_a', createRule('<target>', function*() {
                return 'child_a done';
            }));

            game.registerRule('child_b', createRule('<target>', function*() {
                return 'child_b done';
            }));

            game.dispatchCommand('parent start');
            game.dispatchCommand('child_a target1');

            expect(game.ruleContexts.value.length).toBe(2);

            const oldParent = game.ruleContexts.value[0];
            expect(oldParent.children).toHaveLength(1);

            game.dispatchCommand('parent start');
            game.dispatchCommand('child_b target2');

            const newParent = game.ruleContexts.value[2];
            expect(newParent.children).toHaveLength(1);
            expect(newParent.children[0].resolution).toBe('child_b done');
        });
    });

    describe('context tracking', () => {
        it('should track rule contexts in ruleContexts signal', () => {
            const game = createTestGame();

            game.registerRule('test', createRule('<arg>', function*() {
                yield schema({ name: '', params: [], options: [], flags: [] });
                return 'done';
            }));

            expect(game.ruleContexts.value.length).toBe(0);

            game.dispatchCommand('test arg1');

            expect(game.ruleContexts.value.length).toBe(1);
            expect(game.ruleContexts.value[0].state).toBe('yielded');
        });
    });

    describe('error handling', () => {
        it('should leave context in place when generator throws', () => {
            const game = createTestGame();

            game.registerRule('failing', createRule('<arg>', function*() {
                throw new Error('rule error');
            }));

            expect(() => game.dispatchCommand('failing arg1')).toThrow('rule error');

            expect(game.ruleContexts.value.length).toBe(1);
        });

        it('should leave children in place when child generator throws', () => {
            const game = createTestGame();

            game.registerRule('parent', createRule('<action>', function*() {
                yield schema('child');
                return 'parent done';
            }));

            game.registerRule('child', createRule('<target>', function*() {
                throw new Error('child error');
            }));

            game.dispatchCommand('parent start');
            expect(() => game.dispatchCommand('child target1')).toThrow('child error');

            expect(game.ruleContexts.value.length).toBe(2);
        });
    });

    describe('schema yielding', () => {
        it('should accept a CommandSchema object as yield value', () => {
            const game = createTestGame();

            const customSchema = {
                name: 'custom',
                params: [{ name: 'x', required: true, variadic: false }],
                options: [],
                flags: [],
            };

            game.registerRule('test', createRule('<arg>', function*() {
                const cmd = yield schema(customSchema);
                const rcmd = isCommand(cmd) ? cmd : undefined;
                return { received: rcmd?.params[0] };
            }));

            game.dispatchCommand('test val1');
            const ctx = game.dispatchCommand('custom hello');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toEqual({ received: 'hello' });
        });

        it('should parse string schema on each yield', () => {
            const game = createTestGame();

            game.registerRule('multi', createRule('<start>', function*() {
                const a = yield schema('<value>');
                const b = yield schema('<value>');
                const acmd = isCommand(a) ? a : undefined;
                const bcmd = isCommand(b) ? b : undefined;
                return { a: acmd?.params[0], b: bcmd?.params[0] };
            }));

            game.dispatchCommand('multi init');
            game.dispatchCommand('cmd first');
            const ctx = game.dispatchCommand('cmd second');

            expect(ctx!.state).toBe('done');
            expect(ctx!.resolution).toEqual({ a: 'first', b: 'second' });
        });
    });

    describe('complex flow', () => {
        it('should handle a multi-step game flow', () => {
            const game = createTestGame();

            game.registerRule('start', createRule('<player>', function*(cmd) {
                const player = cmd.params[0];
                const action = yield schema({ name: '', params: [], options: [], flags: [] });

                if (isCommand(action)) {
                    if (action.name === 'move') {
                        yield schema('<target>');
                    } else if (action.name === 'attack') {
                        yield schema('<target> [--power: number]');
                    }
                }

                return { player, action: isCommand(action) ? action.name : '' };
            }));

            const ctx1 = game.dispatchCommand('start alice');
            expect(ctx1!.state).toBe('yielded');

            const ctx2 = game.dispatchCommand('attack');
            expect(ctx2!.state).toBe('yielded');

            const ctx3 = game.dispatchCommand('attack goblin --power 3');
            expect(ctx3!.state).toBe('done');
            expect(ctx3!.resolution).toEqual({ player: 'alice', action: 'attack' });
        });
    });
});