@multiplekex/shallot 0.1.0

package/src/core/xml.ts

@@ -0,0 +1,676 @@
+import { XMLParser } from "fast-xml-parser";
+import { addComponent, Pair } from "bitecs";
+import type { State } from "./state";
+import {
+    getRegisteredComponent,
+    type ParseContext,
+    type ComponentData,
+    type RegisteredComponent,
+} from "./component";
+import { getRelationDef, ChildOf } from "./relation";
+import { toKebabCase, toCamelCase } from "./strings";
+
+function levenshtein(a: string, b: string): number {
+    if (a.length === 0) return b.length;
+    if (b.length === 0) return a.length;
+
+    const matrix: number[][] = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            const cost = a[j - 1] === b[i - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(
+                matrix[i - 1][j] + 1,
+                matrix[i][j - 1] + 1,
+                matrix[i - 1][j - 1] + cost
+            );
+        }
+    }
+
+    return matrix[b.length][a.length];
+}
+
+function findClosestMatch(input: string, candidates: string[]): string | null {
+    const inputKebab = toKebabCase(input);
+
+    let bestMatch: string | null = null;
+    let bestScore = Infinity;
+
+    for (const candidate of candidates) {
+        const candidateKebab = toKebabCase(candidate);
+
+        if (inputKebab === candidateKebab) {
+            return candidate;
+        }
+
+        if (inputKebab.endsWith(candidateKebab) || inputKebab.endsWith("-" + candidateKebab)) {
+            return candidate;
+        }
+
+        const distance = levenshtein(inputKebab, candidateKebab);
+        const maxLen = Math.max(inputKebab.length, candidateKebab.length);
+        const threshold = Math.ceil(maxLen * 0.5);
+
+        if (distance < bestScore && distance <= threshold) {
+            bestScore = distance;
+            bestMatch = candidate;
+        }
+    }
+
+    return bestMatch;
+}
+
+export interface ParsedElement {
+    readonly tag: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly children: readonly ParsedElement[];
+}
+
+export interface EntityRef {
+    readonly attrName: string;
+    readonly targetName: string;
+}
+
+export interface EntityDef {
+    readonly id?: string;
+    readonly components: readonly ComponentDef[];
+    readonly children: readonly EntityDef[];
+    readonly entityRefs: readonly EntityRef[];
+}
+
+export interface ComponentDef {
+    readonly def: RegisteredComponent;
+    readonly attrs: Record<string, string>;
+}
+
+export interface ParseResult {
+    readonly entities: readonly EntityDef[];
+    readonly errors: readonly ParseError[];
+    readonly warnings: readonly string[];
+}
+
+export interface ParseError {
+    readonly message: string;
+    readonly path?: string;
+}
+
+export function parseXml(xml: string): ParseResult {
+    const errors: ParseError[] = [];
+    const warnings: string[] = [];
+
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "",
+        preserveOrder: true,
+        trimValues: true,
+        allowBooleanAttributes: true,
+    });
+
+    let raw: unknown;
+    try {
+        raw = parser.parse(xml, { allowBooleanAttributes: true });
+    } catch (e) {
+        return {
+            entities: [],
+            errors: [{ message: `xml parse error: ${(e as Error).message}` }],
+            warnings: [],
+        };
+    }
+
+    const elements = normalizeRaw(raw);
+    const entities: EntityDef[] = [];
+
+    for (const el of elements) {
+        if (el.tag === "scene") {
+            for (const child of el.children) {
+                const result = parseEntityElement(child, errors, warnings);
+                if (result) entities.push(result);
+            }
+        } else if (el.tag === "a") {
+            const result = parseEntityElement(el, errors, warnings);
+            if (result) entities.push(result);
+        } else if (el.tag.toLowerCase() === "scene" || el.tag.toLowerCase() === "world") {
+            errors.push({ message: `Invalid tag "${el.tag}". Use lowercase <scene>` });
+        }
+    }
+
+    return { entities, errors, warnings };
+}
+
+function isEntityRef(value: string): boolean {
+    return value.startsWith("@") && value.length > 1;
+}
+
+function parseEntityElement(
+    el: ParsedElement,
+    errors: ParseError[],
+    warnings: string[]
+): EntityDef | null {
+    if (el.tag !== "a") {
+        if (el.tag.toLowerCase() === "a") {
+            errors.push({ message: `Invalid tag "${el.tag}". Use lowercase <a>` });
+        }
+        return null;
+    }
+
+    const components: ComponentDef[] = [];
+    const children: EntityDef[] = [];
+    const entityRefs: EntityRef[] = [];
+    const shorthands: Array<{ name: string; value: string }> = [];
+    let entityId: string | undefined;
+
+    for (const [attrName, attrValue] of Object.entries(el.attrs)) {
+        if (attrName === "id") {
+            entityId = attrValue;
+            continue;
+        }
+
+        if (typeof attrValue === "string" && isEntityRef(attrValue)) {
+            entityRefs.push({
+                attrName,
+                targetName: attrValue.slice(1),
+            });
+            continue;
+        }
+
+        const registered = getRegisteredComponent(attrName);
+        if (registered) {
+            const attrs: Record<string, string> = {};
+            if (typeof attrValue === "string" && attrValue !== "") {
+                attrs["_value"] = attrValue;
+            }
+            components.push({ def: registered, attrs });
+            continue;
+        }
+
+        if (typeof attrValue === "string" && attrValue !== "") {
+            shorthands.push({ name: attrName, value: attrValue });
+        }
+    }
+
+    for (const { name, value } of shorthands) {
+        const camel = toCamelCase(name);
+        let matched = false;
+
+        for (const comp of components) {
+            const component = comp.def.component;
+            const hasField = camel in component || `${camel}X` in component;
+
+            if (hasField) {
+                matched = true;
+                if (!comp.attrs._value) {
+                    comp.attrs[name] = value;
+                }
+            }
+        }
+
+        if (!matched) {
+            const id = entityId ? ` (${entityId})` : "";
+            warnings.push(`shorthand "${name}" matches no declared component${id}`);
+        }
+    }
+
+    for (const child of el.children) {
+        if (child.tag === "a") {
+            const childEntity = parseEntityElement(child, errors, warnings);
+            if (childEntity) children.push(childEntity);
+        } else if (child.tag.toLowerCase() === "a") {
+            errors.push({ message: `Invalid tag "${child.tag}". Use lowercase <a>` });
+        } else {
+            errors.push({ message: `Only <a> children allowed, found <${child.tag}>` });
+        }
+    }
+
+    return { id: entityId, components, children, entityRefs };
+}
+
+interface RawElement {
+    [key: string]: unknown;
+    ":@"?: Record<string, string>;
+}
+
+function normalizeRaw(raw: unknown): ParsedElement[] {
+    if (!Array.isArray(raw)) return [];
+
+    const result: ParsedElement[] = [];
+
+    for (const item of raw as RawElement[]) {
+        if (typeof item !== "object" || item === null) continue;
+
+        for (const [key, value] of Object.entries(item)) {
+            if (key === ":@") continue;
+
+            const rawAttrs = item[":@"] ?? {};
+            const attrs: Record<string, string> = {};
+
+            for (const [attrKey, attrVal] of Object.entries(rawAttrs)) {
+                if (typeof attrVal === "string") {
+                    attrs[attrKey] = attrVal;
+                } else if (attrVal === true || attrVal === "") {
+                    attrs[attrKey] = "";
+                }
+            }
+
+            const children = normalizeRaw(value as unknown);
+
+            result.push({
+                tag: key,
+                attrs,
+                children,
+            });
+        }
+    }
+
+    return result;
+}
+
+export interface LoadResult {
+    readonly entities: Map<string, number>;
+    readonly roots: readonly number[];
+    readonly errors: readonly ParseError[];
+}
+
+export type PostLoadHook = (state: State, context: ParseContext) => void;
+
+const postLoadHooks: PostLoadHook[] = [];
+
+export function registerPostLoadHook(hook: PostLoadHook): void {
+    postLoadHooks.push(hook);
+}
+
+export function unregisterPostLoadHook(hook: PostLoadHook): void {
+    const idx = postLoadHooks.indexOf(hook);
+    if (idx !== -1) postLoadHooks.splice(idx, 1);
+}
+
+class LoadParseContext implements ParseContext {
+    private readonly nameToEntity = new Map<string, number>();
+    private _currentEid = 0;
+
+    get currentEid(): number {
+        return this._currentEid;
+    }
+
+    setCurrentEid(eid: number): void {
+        this._currentEid = eid;
+    }
+
+    getEntityByName(name: string): number | null {
+        return this.nameToEntity.get(name) ?? null;
+    }
+
+    setName(name: string, eid: number): void {
+        this.nameToEntity.set(name, eid);
+    }
+
+    getEntityMap(): Map<string, number> {
+        return new Map(this.nameToEntity);
+    }
+}
+
+export function loadScene(state: State, xml: string): LoadResult {
+    const parseResult = parseXml(xml);
+    return instantiateScene(state, parseResult.entities, parseResult.errors);
+}
+
+export async function loadSceneFile(
+    state: State,
+    path: string,
+    readFile: (path: string) => Promise<string>
+): Promise<LoadResult> {
+    const xml = await readFile(path);
+    return loadScene(state, xml);
+}
+
+interface QueuedEntity {
+    readonly def: EntityDef;
+    readonly eid: number;
+    readonly parent?: number;
+}
+
+function instantiateScene(
+    state: State,
+    entityDefs: readonly EntityDef[],
+    parseErrors: readonly ParseError[]
+): LoadResult {
+    const context = new LoadParseContext();
+    const errors: ParseError[] = [...parseErrors];
+    const queue: QueuedEntity[] = [];
+    const roots: number[] = [];
+
+    for (const entityDef of entityDefs) {
+        const eid = createEntityTree(state, entityDef, context, undefined, queue);
+        roots.push(eid);
+    }
+
+    for (const { def, eid, parent } of queue) {
+        if (parent !== undefined) {
+            addComponent(state.world, eid, Pair(ChildOf.relation, parent));
+        }
+
+        for (const ref of def.entityRefs) {
+            applyRelation(state, eid, ref, context, errors);
+        }
+
+        for (const compDef of def.components) {
+            applyComponent(state, eid, compDef, context, errors);
+        }
+    }
+
+    for (const hook of postLoadHooks) {
+        hook(state, context);
+    }
+
+    return {
+        entities: context.getEntityMap(),
+        roots,
+        errors,
+    };
+}
+
+function createEntityTree(
+    state: State,
+    def: EntityDef,
+    context: LoadParseContext,
+    parent: number | undefined,
+    queue: QueuedEntity[]
+): number {
+    const eid = state.addEntity();
+
+    if (def.id) {
+        context.setName(def.id, eid);
+    }
+
+    queue.push({ def, eid, parent });
+
+    for (const childDef of def.children) {
+        createEntityTree(state, childDef, context, eid, queue);
+    }
+
+    return eid;
+}
+
+function applyRelation(
+    state: State,
+    eid: number,
+    ref: EntityRef,
+    context: LoadParseContext,
+    errors: ParseError[]
+): void {
+    const relationDef = getRelationDef(ref.attrName);
+    if (!relationDef) {
+        errors.push({ message: `Unknown relation: "${ref.attrName}"` });
+        return;
+    }
+
+    const targetEid = context.getEntityByName(ref.targetName);
+    if (targetEid === null) {
+        errors.push({ message: `Unknown entity: "@${ref.targetName}"` });
+        return;
+    }
+
+    state.addRelation(eid, relationDef, targetEid);
+}
+
+function applyComponent(
+    state: State,
+    eid: number,
+    compDef: ComponentDef,
+    context: LoadParseContext,
+    errors: ParseError[]
+): void {
+    const { def, attrs } = compDef;
+    const { component, name, traits } = def;
+
+    state.addComponent(eid, component as never);
+
+    const defaults = traits?.defaults?.() ?? {};
+    for (const [field, value] of Object.entries(defaults)) {
+        setFieldValue(component, field, eid, value as number);
+    }
+
+    let values: Record<string, number>;
+
+    context.setCurrentEid(eid);
+    if (traits?.adapter) {
+        values = traits.adapter(attrs, state, context) as Record<string, number>;
+    } else {
+        const result = parseAttrs(def, attrs);
+        values = result.values;
+        for (const err of result.errors) {
+            errors.push({ message: `<${name}> ${err}` });
+        }
+    }
+
+    for (const [field, value] of Object.entries(values)) {
+        setFieldValue(component, field, eid, value);
+    }
+}
+
+function parseAttrs(
+    def: RegisteredComponent,
+    attrs: Record<string, string>
+): { values: Record<string, number>; errors: string[] } {
+    const allValues: Record<string, number> = {};
+    const allErrors: string[] = [];
+
+    if (attrs._value) {
+        if (isCSSAttrSyntax(attrs._value)) {
+            const result = parsePropertyString(def.name, attrs._value, def.component);
+            Object.assign(allValues, result.values);
+            allErrors.push(...result.errors);
+        }
+    }
+
+    for (const [attrName, attrValue] of Object.entries(attrs)) {
+        if (attrName === "_value") continue;
+        if (!attrValue) continue;
+
+        if (isCSSAttrSyntax(attrValue)) {
+            const result = parsePropertyString(def.name, attrValue, def.component);
+            Object.assign(allValues, result.values);
+            allErrors.push(...result.errors);
+        } else {
+            const result = parsePropertyString(
+                def.name,
+                `${attrName}: ${attrValue}`,
+                def.component
+            );
+            Object.assign(allValues, result.values);
+            allErrors.push(...result.errors);
+        }
+    }
+
+    return { values: allValues, errors: allErrors };
+}
+
+function setFieldValue(component: ComponentData, field: string, eid: number, value: number): void {
+    const arr = component[field];
+    if (arr != null && (ArrayBuffer.isView(arr) || Array.isArray(arr))) {
+        arr[eid] = value;
+    }
+}
+
+interface PropertyParseResult {
+    readonly values: Record<string, number>;
+    readonly errors: readonly string[];
+}
+
+function detectVec2(component: ComponentData, base: string): boolean {
+    return `${base}X` in component && `${base}Y` in component;
+}
+
+function detectVec3(component: ComponentData, base: string): boolean {
+    return detectVec2(component, base) && `${base}Z` in component;
+}
+
+function detectVec4(component: ComponentData, base: string): boolean {
+    return detectVec3(component, base) && `${base}W` in component;
+}
+
+function parseNumber(value: string): number | null {
+    value = value.trim();
+
+    if (value.startsWith("0x") || value.startsWith("0X")) {
+        return parseInt(value, 16);
+    }
+
+    if (value.startsWith("#")) {
+        return parseInt(value.slice(1), 16);
+    }
+
+    if (value === "true") return 1;
+    if (value === "false") return 0;
+
+    const num = parseFloat(value);
+    return isNaN(num) ? null : num;
+}
+
+function parseValues(valueStr: string): (number | null)[] {
+    const result: (number | null)[] = [];
+    const trimmed = valueStr.trim();
+    let start = 0;
+    for (let i = 0; i <= trimmed.length; i++) {
+        const isWhitespace = i < trimmed.length && /\s/.test(trimmed[i]);
+        const isEnd = i === trimmed.length;
+        if (isWhitespace || isEnd) {
+            if (start < i) {
+                result.push(parseNumber(trimmed.slice(start, i)));
+            }
+            start = i + 1;
+        }
+    }
+    return result;
+}
+
+function splitProperties(str: string): string[] {
+    const result: string[] = [];
+    let start = 0;
+    for (let i = 0; i <= str.length; i++) {
+        if (i === str.length || str[i] === ";") {
+            const prop = str.slice(start, i).trim();
+            if (prop) result.push(prop);
+            start = i + 1;
+        }
+    }
+    return result;
+}
+
+function parsePropertyString(
+    componentName: string,
+    propertyString: string,
+    component: ComponentData
+): PropertyParseResult {
+    const values: Record<string, number> = {};
+    const errors: string[] = [];
+
+    const properties = splitProperties(propertyString);
+
+    for (const prop of properties) {
+        const colonIdx = prop.indexOf(":");
+        if (colonIdx === -1) {
+            errors.push(`Invalid syntax: "${prop}" (expected "field: value")`);
+            continue;
+        }
+
+        const rawName = prop.slice(0, colonIdx).trim();
+        const valueStr = prop.slice(colonIdx + 1).trim();
+
+        if (!rawName || !valueStr) {
+            errors.push(`Invalid syntax: "${prop}" (empty field or value)`);
+            continue;
+        }
+
+        const name = toCamelCase(rawName);
+        const parsed = parseValues(valueStr);
+
+        if (parsed.some((v) => v === null)) {
+            errors.push(`Invalid number in "${prop}"`);
+            continue;
+        }
+
+        const nums = parsed as number[];
+
+        if (detectVec4(component, name)) {
+            if (nums.length === 4) {
+                values[`${name}X`] = nums[0];
+                values[`${name}Y`] = nums[1];
+                values[`${name}Z`] = nums[2];
+                values[`${name}W`] = nums[3];
+            } else if (nums.length === 1) {
+                values[`${name}X`] = nums[0];
+                values[`${name}Y`] = nums[0];
+                values[`${name}Z`] = nums[0];
+                values[`${name}W`] = nums[0];
+            } else {
+                errors.push(
+                    `${componentName}.${rawName}: expected 1 or 4 values, got ${nums.length}`
+                );
+            }
+            continue;
+        }
+
+        if (detectVec3(component, name)) {
+            if (nums.length === 3) {
+                values[`${name}X`] = nums[0];
+                values[`${name}Y`] = nums[1];
+                values[`${name}Z`] = nums[2];
+            } else if (nums.length === 1) {
+                values[`${name}X`] = nums[0];
+                values[`${name}Y`] = nums[0];
+                values[`${name}Z`] = nums[0];
+            } else {
+                errors.push(
+                    `${componentName}.${rawName}: expected 1 or 3 values, got ${nums.length}`
+                );
+            }
+            continue;
+        }
+
+        if (detectVec2(component, name)) {
+            if (nums.length === 2) {
+                values[`${name}X`] = nums[0];
+                values[`${name}Y`] = nums[1];
+            } else if (nums.length === 1) {
+                values[`${name}X`] = nums[0];
+                values[`${name}Y`] = nums[0];
+            } else {
+                errors.push(
+                    `${componentName}.${rawName}: expected 1 or 2 values, got ${nums.length}`
+                );
+            }
+            continue;
+        }
+
+        if (name in component) {
+            if (nums.length === 1) {
+                values[name] = nums[0];
+            } else {
+                errors.push(`${componentName}.${rawName}: expected 1 value, got ${nums.length}`);
+            }
+            continue;
+        }
+
+        const fieldNames = Object.keys(component);
+        const suggestion = findClosestMatch(rawName, fieldNames);
+        if (suggestion) {
+            errors.push(
+                `${componentName}: unknown field "${rawName}", did you mean "${toKebabCase(suggestion)}"?`
+            );
+        } else {
+            errors.push(`${componentName}: unknown field "${rawName}"`);
+        }
+    }
+
+    return { values, errors };
+}
+
+function isCSSAttrSyntax(value: string): boolean {
+    return value.includes(":") && (value.includes(";") || /^[\w-]+\s*:/.test(value));
+}