boardgame-core/src/core/rule.ts

import {Command, CommandSchema, parseCommand, parseCommandSchema, applyCommandSchema} from "../utils/command";

export type RuleState = 'running' | 'yielded' | 'waiting' | 'invoking' | 'done';

export type SchemaYield = { type: 'schema'; value: string | CommandSchema };
export type InvokeYield = { type: 'invoke'; rule: string; command: Command };
export type RuleYield = SchemaYield | InvokeYield;

export type RuleContext<T = unknown> = {
    type: string;
    schema?: CommandSchema;
    generator: Generator<RuleYield, T, Command | RuleContext<unknown>>;
    parent?: RuleContext<unknown>;
    children: RuleContext<unknown>[];
    state: RuleState;
    resolution?: T;
}

export type RuleDef<T = unknown, H extends RuleEngineHost = RuleEngineHost> = {
    schema: CommandSchema;
    create: (this: H, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>;
};

export type RuleRegistry = Map<string, RuleDef<unknown, RuleEngineHost>>;

export type RuleEngineHost = {
    rules: RuleRegistry;
    ruleContexts: RuleContext<unknown>[];
    addRuleContext: (ctx: RuleContext<unknown>) => void;
    removeRuleContext: (ctx: RuleContext<unknown>) => void;
};

export function createRule<T, H extends RuleEngineHost = RuleEngineHost>(
    schemaStr: string,
    fn: (this: H, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>
): RuleDef<T, H> {
    return {
        schema: parseCommandSchema(schemaStr, ''),
        create: fn as RuleDef<T, H>['create'],
    };
}

function parseYieldedSchema(value: string | CommandSchema): CommandSchema {
    if (typeof value === 'string') {
        return parseCommandSchema(value, '');
    }
    return value;
}

function addContextToHost(host: RuleEngineHost, ctx: RuleContext<unknown>) {
    host.addRuleContext(ctx);
}

function discardChildren(host: RuleEngineHost, parent: RuleContext<unknown>) {
    for (const child of parent.children) {
        host.removeRuleContext(child);
    }
    parent.children = [];
    parent.state = 'yielded';
}

function commandMatchesSchema(command: Command, schema: CommandSchema): boolean {
    const requiredParams = schema.params.filter(p => p.required);
    const variadicParam = schema.params.find(p => p.variadic);

    if (command.params.length < requiredParams.length) {
        return false;
    }

    if (!variadicParam && command.params.length > schema.params.length) {
        return false;
    }

    const requiredOptions = Object.values(schema.options).filter(o => o.required);
    for (const opt of requiredOptions) {
        const hasOption = opt.name in command.options || (opt.short && opt.short in command.options);
        if (!hasOption) {
            return false;
        }
    }

    return true;
}

function applySchemaToCommand(command: Command, schema: CommandSchema): Command {
    return applyCommandSchema(command, schema).command;
}

function findYieldedContext(contexts: RuleContext<unknown>[]): RuleContext<unknown> | undefined {
    for (let i = contexts.length - 1; i >= 0; i--) {
        const ctx = contexts[i];
        if (ctx.state === 'yielded') {
            return ctx;
        }
    }
    return undefined;
}

function createContext<T>(
    command: Command,
    ruleDef: RuleDef<T>,
    host: RuleEngineHost,
    parent?: RuleContext<unknown>
): RuleContext<T> {
    return {
        type: ruleDef.schema.name,
        schema: undefined,
        generator: ruleDef.create.call(host, command),
        parent,
        children: [],
        state: 'running',
        resolution: undefined,
    };
}

function handleGeneratorResult<T>(
    host: RuleEngineHost,
    ctx: RuleContext<T>,
    result: IteratorResult<RuleYield, T>
): RuleContext<unknown> | undefined {
    if (result.done) {
        ctx.resolution = result.value;
        ctx.state = 'done';
        return resumeParentAfterChildComplete(host, ctx as RuleContext<unknown>);
    }

    const yielded = result.value;
    if (yielded.type === 'invoke') {
        const childRuleDef = host.rules.get(yielded.rule);
        if (childRuleDef) {
            ctx.state = 'invoking';
            return invokeChildRule(host, yielded.rule, yielded.command, ctx as RuleContext<unknown>);
        } else {
            ctx.schema = parseYieldedSchema({ name: '', params: [], options: {}, flags: {} });
            ctx.state = 'yielded';
        }
    } else {
        ctx.schema = parseYieldedSchema(yielded.value);
        ctx.state = 'yielded';
    }

    return undefined;
}

function stepGenerator<T>(
    host: RuleEngineHost,
    ctx: RuleContext<T>
): RuleContext<T> {
    const result = ctx.generator.next();
    const resumed = handleGeneratorResult(host, ctx, result);
    if (resumed) return resumed as RuleContext<T>;
    return ctx;
}

function invokeChildRule<T>(
    host: RuleEngineHost,
    ruleName: string,
    command: Command,
    parent: RuleContext<unknown>
): RuleContext<T> {
    const ruleDef = host.rules.get(ruleName)!;
    const ctx = createContext(command, ruleDef, host, parent);

    parent.children.push(ctx as RuleContext<unknown>);
    addContextToHost(host, ctx as RuleContext<unknown>);

    return stepGenerator(host, ctx) as RuleContext<T>;
}

function resumeParentAfterChildComplete(
    host: RuleEngineHost,
    childCtx: RuleContext<unknown>
): RuleContext<unknown> | undefined {
    const parent = childCtx.parent;
    if (!parent || parent.state !== 'invoking') return undefined;

    parent.children = parent.children.filter(c => c !== childCtx);

    const result = parent.generator.next(childCtx);
    const resumed = handleGeneratorResult(host, parent, result);
    if (resumed) return resumed;
    return parent;
}

function invokeRule<T>(
    host: RuleEngineHost,
    command: Command,
    ruleDef: RuleDef<T>,
    parent?: RuleContext<unknown>
): RuleContext<T> {
    const ctx = createContext(command, ruleDef, host, parent);

    if (parent) {
        discardChildren(host, parent);
        parent.children.push(ctx as RuleContext<unknown>);
        parent.state = 'waiting';
    }

    addContextToHost(host, ctx as RuleContext<unknown>);

    return stepGenerator(host, ctx);
}

function feedYieldedContext(
    host: RuleEngineHost,
    ctx: RuleContext<unknown>,
    command: Command
): RuleContext<unknown> {
    const typedCommand = applySchemaToCommand(command, ctx.schema!);
    const result = ctx.generator.next(typedCommand);
    const resumed = handleGeneratorResult(host, ctx, result);
    return resumed ?? ctx;
}

export function dispatchCommand(host: RuleEngineHost, input: string): RuleContext<unknown> | undefined {
    const command = parseCommand(input);

    const matchedRule = host.rules.get(command.name);
    if (matchedRule) {
        const typedCommand = applySchemaToCommand(command, matchedRule.schema);
        const parent = findYieldedContext(host.ruleContexts);
        return invokeRule(host, typedCommand, matchedRule, parent);
    }

    for (let i = host.ruleContexts.length - 1; i >= 0; i--) {
        const ctx = host.ruleContexts[i];
        if (ctx.state === 'yielded' && ctx.schema && commandMatchesSchema(command, ctx.schema)) {
            return feedYieldedContext(host, ctx, command);
        }
    }

    return undefined;
}